TODO: A bit about Linear Algebra...

# Linear_Algebra¶

## Linear Algebra Base Classes¶

class StateVectorBase(model_vector_ref)

Bases: object

Abstract class defining the model state vector.

Base class for model state vector objects. A model state vector should provide all basic functionalities such as vector addition, scaling, norm, vector-vector dot-product, etc.

Parameters: model_vector_ref – a reference (pointer) to the model’s state vector object. This could be a reference to a numpy array for example. It could even be a reference to the initial index of some bizzare model-based structure. All is needed is that the implemented methods be aware of this structure and handle it properly.

Attributes

Methods

__init__(model_vector_ref)
abs(in_place=True)

Evaluate absolute value of all entries.

Parameters: in_place – If True the absolute values are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the absolute value (of all entries) of the StateVector (self)
add(other, in_place=True)

Add other to the vector. in_place: If True addition is applied (in-place) to the passed vector.

If False, a new copy will be returned.
Parameters: other – another StateVector object StateVector; self + other is returned
axpy(alpha, other, in_place=True)

Add the vector with a scaled vector.

Parameters: alpha – scalar other – another StateVector object in_place – If True scaled addition is applied (in-place) to the passed vector. If False, a new copy will be returned. StateVector; self + alpha * other is returned
copy()

Return a (deep) copy of the StateVector object.

cross(other)

Perform a cross product producing a StateMatrix.

Parameters: other – another StateVector object StateMatrix object containing the cross product of self with other.
dot(other)

Perform a dot product with other.

Parameters: other – another StateVector object. The (scalar) dot-product of self with other
get_numpy_array()

Return a copy of the internal vector (underlying reference data structure) converted to Numpy ndarray.

Returns: a Numpy representation of the nuderlying data state vector structure.
get_raw_vector_ref()

Return a reference to the wrapped data structure constructed by the model.

Returns: a reference to the model’s vector object (StateVector._raw_vector).
max()

Return maximum of entries of the StateVector

min()

Return minimum of entries of the StateVector

multiply(other, in_place=True)

Return point-wise multiplication with other

Parameters: other – another StateVector object in_place – If True multiplication is applied (in-place) to the passed vector. If False, a new copy will be returned. point-wise multiplication of self with other
norm2()

Return the 2-norm of the StateVector (self).

Parameters: alpha – scalar other – another StateVector object 2-norm of self
prod()

Return product of entries of the StateVector

reciprocal(in_place=True)

Return the reciprocal of all entries.

Parameters: in_place – If True reciprocals are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the reciprocal (of all entries) of the StateVector (self)
scale(alpha, in_place=True)

BLAS-like method; scale the underlying StateVector by the constant (scalar) alpha.

Parameters: alpha – scalar in_place – If True, scaling is applied (in-place) to the passed StateVector (self) If False, a new copy will be returned. The StateVector object scaled by the constant (scalar) alpha.
set_raw_vector_ref(model_vector_ref)

Sets the model vector reference to a new object. This should do what the constructor is doing. This however, can be called if the reference of the underlying data structure is to be updated after initialization.

Parameters: model_vector_ref – a reference (pointer) to the model’s state vector object. This could be a reference to a numpy array for example. It could even be a reference to the initial index of some bizzare model-based structure. All is needed is that the implemented methods be aware of this structure and handle it properly. This can be very useful for example when a time integrator is to update a state vector in-place.
shape

Get the size of the state vector.

size

Get the size of the state vector.

sqrt(in_place=True)

Evaluate square root of all entries.

Parameters: in_place – If True the square roots are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the square root (of all entries) of the StateVector (self)
square(in_place=True)

Evaluate square of all entries.

Parameters: in_place – If True the squares are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the square (of all entries) of the StateVector (self)
sum()

Return sum of entries of the StateVector

class ObservationVectorBase(model_vector_ref)

Bases: object

Base class for model observation vector objects. a model observation vector should provide all basic functionalities such as vector addition, scaling, norm, vector-vector dot-product, etc. This should be very similar to state_vector_base.

Parameters: model_vector_ref – a reference (pointer) to the model’s observation vector object. could be a reference to a numpy array for example. (This) – could even be a reference to the initial index of some bizzare model-based structure. (It) – is needed is that the implemented methods be aware of this structure and handle it properly. (All) –

Attributes

Methods

__init__(model_vector_ref)
abs(in_place=True)

Evaluate absolute value of all entries.

Parameters: in_place – If True the absolute values are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the absolute value (of all entries) of the ObservationVector (self)
add(other, in_place=True)

Add other to the vector. in_place: If True addition is applied (in-place) to the passed vector.

If False, a new copy will be returned.
Parameters: other – another ObservationVector object ObservationVector; self + other is returned
axpy(alpha, other, in_place=True)

Add the vector with a scaled vector.

Parameters: alpha – scalar other – another ObservationVector object in_place – If True scaled addition is applied (in-place) to the passed vector. If False, a new copy will be returned. ObservationVector; self + alpha * other is returned
copy()

Return a (deep) copy of the ObservationVector object.

cross(other)

Perform a cross product producing a ObservationMatrix.

Parameters: other – another ObservationVector object ObservationMatrix object containing the cross product of self with other.
dot(other)

Perform a dot product with other.

Parameters: other – another ObservationVector object. The (scalar) dot-product of self with other
get_numpy_array()

Return a copy of the internal vector (underlying reference data structure) converted to Numpy ndarray.

Parameters: None – a Numpy representation of the nuderlying data observation vector structure.
get_raw_vector_ref()

Returns a reference to the enclosed vector object constructed by the model.

Parameters: None – a reference to the model’s vector object (ObservationVectorNumpy._raw_vector).
max()

Return maximum of entries of the ObservationVector

min()

Return minimum of entries of the ObservationVector

multiply(other, in_place=True)

Return point-wise multiplication with other

Parameters: other – another ObservationVector object in_place – If True multiplication is applied (in-place) to the passed vector. If False, a new copy will be returned. point-wise multiplication of self with other
norm2()

Return the 2-norm of the ObservationVector (self).

Parameters: alpha – scalar other – another ObservationVector object 2-norm of self
prod()

Return product of entries of the ObservationVector

reciprocal(in_place=True)

Return the reciprocal of all entries.

Parameters: in_place – If True reciprocals are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the reciprocal (of all entries) of the ObservationVector (self)
scale(alpha, in_place=True)

BLAS-like method; scale the underlying ObservationVector by the constant (scalar) alpha.

Parameters: alpha – scalar in_place – If True scaling is applied (in-place) to the passed vector. If False, a new copy will be returned. The ObservationVector object scaled by the constant (scalar) alpha.
set_raw_vector_ref(model_vector_ref)

Sets the model vector reference to a new object. This should do what the constructor is doing. This however, can be called if the reference of the underlying data structure is to be updated after initialization.

Parameters: model_vector_ref – a reference (pointer) to the model’s observation vector object. could be a reference to a numpy array for example. (This) – could even be a reference to the initial index of some bizzare model-based structure. (It) – is needed is that the implemented methods be aware of this structure and handle it properly. (All) – None
shape

Get the size of the observation vector.

size

Get the size of the observation vector.

sqrt(in_place=True)

Evaluate square root of all entries.

Parameters: in_place – If True the square roots are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the square root (of all entries) of the ObservationVector (self)
square(in_place=True)

Evaluate square of all entries.

Parameters: in_place – If True the squares are evaluated (in-place) to the passed vector. If False, a new copy will be returned. the square (of all entries) of the ObservationVector (self)
sum()

Return sum of entries of the ObservationVector

class StateMatrixBase(model_matrix_ref)

Bases: object

Base class for model state matrix objects. A model state matrix should provide all basic functionalities such as matrix addition, matrix-vector product, matrix-inv prod vector, etc.

Abstract class defining DATeS interface to model matrices (such as the model Jacobian, or background error covariance matrix).

Parameters: model_matrix_ref – a reference to the model’s matrix object to be wrapped. This could be a reference to a numpy 2d array for example. It could even be a reference to the initial index of some bizzare model-based structure. All is needed is that the implemented methods be aware of this structure and handle it properly.

Attributes

Methods

__init__(model_matrix_ref)
add(other, in_place=True)

Parameters: other – another StateMatrix object of the same type as this object in_place – If True, matrix addition is applied (in-place) to (self) If False, a new copy will be returned. The sum of self with the passed StateMatrix (other).
addAlphaI(alpha, in_place=True)

Parameters: alpha – scalar in_place – If True, scaled diagonal is added (in-place) to (self) If False, a new copy will be returned. self + alpha * Identity matrix
cholesky(in_place=True)

Return a Cholesky decomposition of self._raw_matrix

Parameters: other – another StateMatrix object of the same type as this object in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned. Cholesky decomposition of self (or a copy of it).
cond()

Return the condition number of the matrix.

copy()

Return a (deep) copy of the matrix.

det()

Returns the determinate of the matrix

diag(k=0)

Return the matrix diagonal as numpy 1D array.

Parameters: k – int, optional Diagonal in question. The default is 0. Use k>0 for diagonals above the main diagonal, and k<0 for diagonals below the main diagonal. The extracted diagonal as numpy array
diagonal(k=0)

Return the matrix diagonal as numpy 1D array.

Parameters: k – int, optional Diagonal in question. The default is 0. Use k>0 for diagonals above the main diagonal, and k<0 for diagonals below the main diagonal. The extracted diagonal as numpy array
eig()

Return the eigenvalues of the matrix.

get_numpy_array()

Returns the state matrix (a copy) as a 2D NxN Numpy array.

Returns: a Numpy representation (2D NxN Numpy array) of the nuderlying data state matrix structure.
get_raw_matrix_ref()

Returns a reference to the enclosed matrix object constructed by the model.

Returns: a reference to the model’s matrix object.
inv(in_place=True)

Invert the matrix.

Parameters: in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.

Returns:

inverse(in_place=True)

Invert the matrix.

Parameters: in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.

Returns:

lu_factor()

Compute pivoted LU decomposition of a matrix. The decomposition is:

A = P L U


where P is a permutation matrix, L lower triangular with unit diagonal elements, and U upper triangular.

Args:

Returns: A tuple (lu, piv) to be used by lu_factor. lu : (N, N) ndarray Matrix containing U in its upper triangle, and L in its lower triangle. The unit diagonal elements of L are not stored. piv : (N,) ndarray Pivot indices representing the permutation matrix P: row i of matrix was interchanged with row piv[i]
lu_solve(b, lu_and_piv=None)

Return the solution of the linear system created by the matrix and RHS vector b.

Parameters: lu_and_piv – (lu, piv) the output of lu_factor b – a StateVectorNumpy making up the RHS of the linear system. a StateVectorNumpy containing the solution to the linear system.
matrix_product(other, in_place=True)

Right multiplication by a matrix.

Parameters: other – another StateMatrix object of the same type as this object in_place – If True, matrix-matrix product is applied (in-place) to (self) If False, a new copy will be returned. The product of self by the passed StateMatrix (other).
matrix_product_matrix_transpose(other, in_place=True)

Right multiplication of the by a matrix-transpose.

Parameters: other – another StateMatrix object of the same type as this object The product of self by the passed StateMatrix-transposed (other).
norm2()

Return the 2-norm of the matrix.

presolve()

Prepare for performing a linear solve (by, for example, performing an LU factorization).

scale(alpha, in_place=True)

BLAS-like method; scale the underlying StateMatrix by the constant (scalar) alpha.

Parameters: alpha – scalar in_place – If true scaling is applied (in-place) to (self). If False, a new copy will be returned. The StateMatrix object scaled by the constant (scalar) alpha.
schur_product(other, in_place=True)

Perform elementwise (Hadamard) multiplication with another state matrix.

Parameters: other – another StateMatrix object of the same type as this object in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned. The result of Hadamard prodect of self with other
set_diag(diagonal)

Update the matrix diagonal to the passed diagonal.

Parameters: diagonal – a one dimensional numpy array, or a scalar
set_diagonal(diagonal)

Update the matrix diagonal to the passed diagonal.

Parameters: diagonal – a one dimensional numpy array, or a scalar
set_raw_matrix_ref(model_matrix_ref)
Set the model matrix reference to a new object.
This should do what the constructor is doing. This however, can be called if the reference of the underlying data structure is to be updated after initialization.
Parameters: model_matrix_ref – a reference (pointer) to the model’s state matrix object. This could be a reference to a numpy array for example. It could even be a reference to the initial index of some bizzare model-based structure. All is needed is that the implemented methods be aware of this structure and handle it properly. None
shape

Get the size of the state matrix.

size

Get the size of the state matrix.

solve(b)

Return the solution of the linear system created by the matrix and RHS vector b.

Parameters: b – a StateVectorNumpy making up the RHS of the linear system.
str_type

Get the size of the state matrix.

svd()

Return the singular value decomposition of the matrix.

Args:

Returns:

transpose(in_place=True)

Return slef transposed

Parameters: in_place – If True, matrix transpose is applied (in-place) to (self) If False, a new copy will be returned. self (or a copy of it) transposed
transpose_matrix_product(other, in_place=True)

Right multiplication of the matrix-transpose by a matrix.

Parameters: other – another StateMatrix object of the same type as this object in_place – If True, matrix-transpose-matrix product is applied (in-place) to (self) If False, a new copy will be returned. The product of self-transposed by the passed StateMatrix (other).
transpose_vector_product(vector, in_place=True)

Right multiplication of the matrix-transpose.

Parameters: vector – StateVector object in_place – If True, matrix-transpose-vector product is applied (in-place) to the passed vector If False, a new copy will be returned. The product of self-transposed by the passed vector.
vector_product(vector, in_place=True)

Return the vector resulting from the right multiplication of the matrix and vector.

Parameters: vector – StateVector object in_place – If True, matrix-vector product is applied (in-place) to the passed StateVector If False, a new copy will be returned. The product of self by the passed vector.
class ObservationMatrixBase(model_obs_matrix_ref)

Bases: object

Base class for model observation matrix objects. A model observation matrix should provide all basic functionalities such as matrix addition, matrix-vector product, matrix-inv prod vector, etc.

This should be very similar to state_matrix_base.StateMatrixBase Abstract class defining DATeS interface to model matrices (such as observation error covariance matrix).

Parameters: model_obs_matrix_ref – a reference to the model’s matrix object to be wrapped. This could be a reference to a numpy 2d array for example. It could even be a reference to the initial index of some bizzare model-based structure. All is needed is that the implemented methods be aware of this structure and handle it properly.

Attributes

Methods

__init__(model_obs_matrix_ref)
add(other, in_place=True)

Parameters: other – another ObservationMatrix object of the same type as this object in_place – If True, matrix addition is applied (in-place) to (self) If False, a new copy will be returned. The sum of self with the passed ObservationMatrix (other).
addAlphaI(alpha, in_place=True)

Parameters: alpha – scalar in_place – If True, scaled diagonal is added (in-place) to (self) If False, a new copy will be returned. self + alpha * Identity matrix
cholesky(in_place=True)

Return a Cholesky decomposition of self._raw_matrix

Parameters: other – another ObservationMatrix object of the same type as this object in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned. Cholesky decomposition of self (or a copy of it).
cond()

Return the condition number of the matrix.

Args:

Returns:

copy()

Return a (deep) copy of the matrix.

det()

Returns the determinate of the matrix

Args:

Returns:

diag(k=0)

Return the matrix diagonal as numpy 1D array.

Parameters: k – int, optional Diagonal in question. The default is 0. Use k>0 for diagonals above the main diagonal, and k<0 for diagonals below the main diagonal. The extracted diagonal as numpy array
diagonal(k=0)

Return the matrix diagonal as numpy 1D array.

Parameters: k – int, optional Diagonal in question. The default is 0. Use k>0 for diagonals above the main diagonal, and k<0 for diagonals below the main diagonal. The extracted diagonal as numpy array
eig()

Return the eigenvalues of the matrix.

Args:

Returns:

get_numpy_array()

Returns the observation matrix (a copy) as a 2D NxN Numpy array.

Returns: a Numpy representation (2D NxN Numpy array) of the nuderlying data observation matrix structure.
get_raw_matrix_ref()

Returns a reference to the enclosed matrix object constructed by the model.

Returns: a reference to the model’s matrix object.
inv(in_place=True)

Invert the matrix.

Parameters: in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.

Returns:

inverse(in_place=True)

Invert the matrix.

Parameters: in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.

Returns:

lu_factor()

Compute pivoted LU decomposition of a matrix. The decomposition is:

A = P L U


where P is a permutation matrix, L lower triangular with unit diagonal elements, and U upper triangular.

Args:

Returns: A tuple (lu, piv) to be used by lu_factor. lu : (N, N) ndarray Matrix containing U in its upper triangle, and L in its lower triangle. The unit diagonal elements of L are not stored. piv : (N,) ndarray Pivot indices representing the permutation matrix P: row i of matrix was interchanged with row piv[i]
lu_solve(b, lu_and_piv=None)

Return the solution of the linear system created by the matrix and RHS vector b.

Parameters: lu_and_piv – (lu, piv) the output of lu_factor b – a ObservationVectorNumpy making up the RHS of the linear system. a ObservationVectorNumpy containing the solution to the linear system.
matrix_product(other, in_place=True)

Right multiplication by a matrix.

Parameters: other – another ObservationMatrix object of the same type as this object in_place – If True, matrix-matrix product is applied (in-place) to (self) If False, a new copy will be returned. The product of self by the passed ObservationMatrix (other).
matrix_product_matrix_transpose(other, in_place=True)

Right multiplication of the by a matrix-transpose.

Parameters: other – another ObservationMatrix object of the same type as this object The product of self by the passed ObservationMatrix-transposed (other).
norm2()

Return the 2-norm of the matrix.

Args:

Returns:

presolve()

Prepare for performing a linear solve (by, for example, performing an LU factorization).

Args:

Returns:

scale(alpha, in_place=True)

BLAS-like method; scale the underlying ObservationMatrix by the constant (scalar) alpha.

Parameters: alpha – scalar in_place – If true scaling is applied (in-place) to (self). If False, a new copy will be returned. The ObservationMatrix object scaled by the constant (scalar) alpha.
schur_product(other)

Perform elementwise (Hadamard) multiplication with another observation matrix.

Parameters: other – another ObservationMatrix object of the same type as this object in_place – If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned. The result of Hadamard prodect of self with other
set_diag(diagonal)

Update the matrix diagonal to the passed diagonal.

Parameters: diagonal – a one dimensional numpy array, or a scalar None
set_diagonal(diagonal)

Update the matrix diagonal to the passed diagonal.

Parameters: diagonal – a one dimensional numpy array, or a scalar None
set_raw_matrix_ref(model_obs_matrix_ref)

Set the model matrix reference to a new object. This should do what the constructor is doing. This however, can be called if the reference of the underlying data structure is to be updated after initialization.

Parameters: model_matrix_ref – a reference (pointer) to the model’s observation matrix object. could be a reference to a numpy array for example. (This) – could even be a reference to the initial index of some bizzare model-based structure. (It) – is needed is that the implemented methods be aware of this structure and handle it properly. (All) –
shape

Get the size of the observation matrix.

size

Get the size of the observation matrix.

solve(b)

Return the solution of the linear system created by the matrix and RHS vector b.

Parameters: b – a ObservationVectorNumpy making up the RHS of the linear system.

Returns:

str_type

Get the size of the observation matrix.

svd()

Return the singular value decomposition of the matrix.

Args:

Returns:

transpose(in_place=True)

Return slef transposed

Parameters: in_place – If True, matrix transpose is applied (in-place) to (self) If False, a new copy will be returned. self (or a copy of it) transposed
transpose_matrix_product(other, in_place=True)

Right multiplication of the matrix-transpose by a matrix.

Parameters: other – another ObservationMatrix object of the same type as this object in_place – If True, matrix-transpose-matrix product is applied (in-place) to (self) If False, a new copy will be returned. The product of self-transposed by the passed ObservationMatrix (other).
transpose_vector_product(vector, in_place=True)

Right multiplication of the matrix-transpose.

Parameters: vector – ObservationVector object in_place – If True, matrix-transpose-vector product is applied (in-place) to the passed vector If False, a new copy will be returned. The product of self-transposed by the passed vector.
vector_product(vector, in_place=True)

Return the vector resulting from the right multiplication of the matrix and vector.

Parameters: vector – ObservationVector object in_place – If True, matrix-vector product is applied (in-place) to the passed ObservationVector If False, a new copy will be returned. The product of self by the passed vector.