*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.Returns: 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 objectReturns: StateVector; self + other is returned

`axpy`

(alpha,other,in_place=True)¶Add the vector with a scaled vector.

Parameters:

alpha– scalarother– another StateVector objectin_place– If True scaled addition is applied (in-place) to the passed vector. If False, a new copy will be returned.Returns: 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 objectReturns: StateMatrix object containing the cross product of self with other.

`dot`

(other)¶Perform a dot product with other.

Parameters: other– another StateVector object.Returns: 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 objectin_place– If True multiplication is applied (in-place) to the passed vector. If False, a new copy will be returned.Returns: point-wise multiplication of self with other

`norm2`

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

Parameters:

alpha– scalarother– another StateVector objectReturns: 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.Returns: 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– scalarin_place– If True, scaling is applied (in-place) to the passed StateVector (self) If False, a new copy will be returned.Returns: 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.Returns: 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.Returns: 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.Returns: 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 objectReturns: ObservationVector; self + other is returned

`axpy`

(alpha,other,in_place=True)¶Add the vector with a scaled vector.

Parameters:

alpha– scalarother– another ObservationVector objectin_place– If True scaled addition is applied (in-place) to the passed vector. If False, a new copy will be returned.Returns: 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 objectReturns: ObservationMatrix object containing the cross product of self with other.

`dot`

(other)¶Perform a dot product with other.

Parameters: other– another ObservationVector object.Returns: 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–Returns: 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–Returns: 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 objectin_place– If True multiplication is applied (in-place) to the passed vector. If False, a new copy will be returned.Returns: point-wise multiplication of self with other

`norm2`

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

Parameters:

alpha– scalarother– another ObservationVector objectReturns: 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.Returns: 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– scalarin_place– If True scaling is applied (in-place) to the passed vector. If False, a new copy will be returned.Returns: 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) –Returns: 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.Returns: 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.Returns: 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)¶Add a matrix.

Parameters:

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

`addAlphaI`

(alpha,in_place=True)¶Add a scaled identity matrix.

Parameters:

alpha– scalarin_place– If True, scaled diagonal is added (in-place) to (self) If False, a new copy will be returned.Returns: 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 objectin_place– If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.Returns: 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.Returns: 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.Returns: 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 Uwhere 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_factorb– a StateVectorNumpy making up the RHS of the linear system.Returns: 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 objectin_place– If True, matrix-matrix product is applied (in-place) to (self) If False, a new copy will be returned.Returns: 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 objectReturns: 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– scalarin_place– If true scaling is applied (in-place) to (self). If False, a new copy will be returned.Returns: 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 objectin_place– If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.Returns: 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.Returns: 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.Returns: 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 objectin_place– If True, matrix-transpose-matrix product is applied (in-place) to (self) If False, a new copy will be returned.Returns: 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 objectin_place– If True, matrix-transpose-vector product is applied (in-place) to the passed vector If False, a new copy will be returned.Returns: 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 objectin_place– If True, matrix-vector product is applied (in-place) to the passed StateVector If False, a new copy will be returned.Returns: 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)¶Add a matrix.

Parameters:

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

`addAlphaI`

(alpha,in_place=True)¶Add a scaled identity matrix.

Parameters:

alpha– scalarin_place– If True, scaled diagonal is added (in-place) to (self) If False, a new copy will be returned.Returns: 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 objectin_place– If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.Returns: 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.Returns: 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.Returns: 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 Uwhere 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_factorb– a ObservationVectorNumpy making up the RHS of the linear system.Returns: 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 objectin_place– If True, matrix-matrix product is applied (in-place) to (self) If False, a new copy will be returned.Returns: 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 objectReturns: 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– scalarin_place– If true scaling is applied (in-place) to (self). If False, a new copy will be returned.Returns: 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 objectin_place– If True, inverse of the matrix is carried out (in-place) to (self) If False, a new copy will be returned.Returns: 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 scalarReturns: None

`set_diagonal`

(diagonal)¶Update the matrix diagonal to the passed diagonal.

Parameters: diagonal– a one dimensional numpy array, or a scalarReturns: 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.Returns: 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 objectin_place– If True, matrix-transpose-matrix product is applied (in-place) to (self) If False, a new copy will be returned.Returns: 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 objectin_place– If True, matrix-transpose-vector product is applied (in-place) to the passed vector If False, a new copy will be returned.Returns: 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 objectin_place– If True, matrix-vector product is applied (in-place) to the passed ObservationVector If False, a new copy will be returned.Returns: The product of self by the passed vector.