dubfi.linalg.types
==================

.. py:module:: dubfi.linalg.types

.. autoapi-nested-parse::

   Abstract types for linear algebra.

   This module defines abstract Vector and Operator types for basic
   linear algebra operations as required for data assimilation or
   inverse problems.

   .. codeauthor:: Valentin Bruch, DWD <valentin.bruch@dwd.de>
   .. versionadded:: 0.1.0 (initial release)



Classes
-------

.. autoapisummary::

   dubfi.linalg.types.AbstractVector
   dubfi.linalg.types.Vector
   dubfi.linalg.types.AbstractOperator
   dubfi.linalg.types.Operator
   dubfi.linalg.types.OperatorChain
   dubfi.linalg.types.InvOperator
   dubfi.linalg.types.InvOperatorNp


Module Contents
---------------

.. py:class:: AbstractVector

   Bases: :py:obj:`abc.ABC`


   Abstract element of a finite-dimensional vector space over real numbers.


   .. py:property:: shape
      :type: tuple[int, Ellipsis]

      :abstractmethod:


      Shape of array representation of self, last dimension is the vector dimension.


   .. py:property:: ndim

      Number of dimensions, of which one is the vector dimension.


   .. py:property:: data
      :type: numpy.ndarray

      :abstractmethod:


      Numpy array representation of self.


   .. py:method:: tonumpy()

      Numpy array representation of self.



   .. py:method:: __matmul__(other)

      Compute scalar product with other vector or with numpy array.



   .. py:method:: apply(other)
      :abstractmethod:


      Compute scalar product with other vector.



   .. py:method:: dot(other)
      :abstractmethod:


      Compute scalar product along some non-vector dimension.



   .. py:method:: __mul__(other)
      :abstractmethod:


      Multiply by scalar or numpy array treated as scalar along vector space dimension.



   .. py:method:: __add__(other)
      :abstractmethod:


      Add two vectors, applying broadcasting rules.



   .. py:method:: __sub__(other)
      :abstractmethod:


      Subtract vector from self, applying broadcasting rules.



   .. py:method:: iszero()

      Check if all elements are zero.



.. py:class:: Vector(size, entry_shape = ())

   Bases: :py:obj:`AbstractVector`


   Simple vector with explicit array representation.


   .. py:property:: shape
      :type: tuple[int, Ellipsis]


      Shape of array representation of self, with vector space along last dimension.


   .. py:property:: data

      Numpy array representation of self.


   .. py:method:: fromdata(data, other = None)
      :classmethod:


      Construct vector from numpy array.



   .. py:method:: dot(other)

      Compute scalar product along some non-vector dimension.



   .. py:method:: __mul__(other)

      Multiply by scalar or numpy array treated as scalar along vector space dimension.



   .. py:method:: __add__(other)

      Add two vectors, applying broadcasting rules.



   .. py:method:: __iadd__(other)

      Add vector in-place.



   .. py:method:: __sub__(other)

      Add two vectors, applying broadcasting rules.



   .. py:method:: __isub__(other)

      Subtract vector in-place.



   .. py:method:: apply(other)

      Compute scalar product with other vector.



.. py:class:: AbstractOperator

   Bases: :py:obj:`abc.ABC`


   Abstract linear operator acting on vectors.


   .. py:property:: shape
      :type: tuple[int, Ellipsis]

      :abstractmethod:


      Shape of array (matrix) representation of self.


   .. py:property:: symmetric
      :type: bool


      True if self equals its adjoint.


   .. py:method:: tonumpy()
      :abstractmethod:


      Numpy array (matrix) representation of self.



   .. py:method:: solve(vec)
      :abstractmethod:


      Solve linear equation self @ x = vec for x.



   .. py:method:: inv()

      Compute (multiplicative) inverse operator.



   .. py:method:: diagonal()
      :abstractmethod:


      Return diagonal of self as vector.



   .. py:method:: __mul__(other)
      :abstractmethod:


      Multiply element-wise.



   .. py:method:: __matmul__(other)

      Act with operator on other operator or on vector.



   .. py:method:: trace()
      :abstractmethod:


      Compute trace of self.



   .. py:method:: trace_product(other)

      Compute trace of (self @ other).



   .. py:method:: apply(vec)
      :abstractmethod:


      Apply operator on vector: self @ vec.



   .. py:method:: rapply(vec)

      Apply transpose operator on vector: self.T @ vec.



   .. py:method:: sandwich(vec)

      Compute vec @ self @ vec.



   .. py:method:: chain(other)

      Combine operators: self @ other.



   .. py:method:: dot(other)
      :abstractmethod:


      Inner product along non-vector dimensions.



   .. py:method:: logdet()
      :abstractmethod:


      Compute log(det(self)) assuming that self is a positive definite, real-symmetric matrix.



.. py:class:: Operator(size, entry_shape = ())

   Bases: :py:obj:`AbstractOperator`


   Abstract operator enriched with functions for computing the trace.


   .. py:property:: shape
      :type: tuple[int, Ellipsis]


      Shape of array representation of self, with vector space along last two dimensions.


   .. py:method:: trace()

      Compute trace(self).



   .. py:method:: trace_product_self(chunk=30)

      Compute trace(self @ self).



   .. py:method:: trace_product(other)

      Compute trace(self @ other).



.. py:class:: OperatorChain(*operators)

   Bases: :py:obj:`Operator`


   Generic representation of the product of multiple linear operators.


   .. py:method:: apply(vec)

      Apply operator on vector: self @ vec.



   .. py:method:: rapply(vec)

      Apply transpose operator on vector: self.T @ vec.



   .. py:method:: tonumpy()

      Numpy array (matrix) representation of self.



   .. py:method:: __mul__(other)

      Multiply element-wise.



   .. py:method:: __rmul__(other)

      Multiply element-wise.



   .. py:method:: __imul__(other)

      Multiply element-wise in-place.



   .. py:method:: inv()

      Compute (multiplicative) inverse operator.



   .. py:method:: solve(vec)

      Solve linear equation self @ x = vec for x.



   .. py:method:: chain(other)

      Combine operators: self @ other.



   .. py:method:: logdet()

      Compute log(det(self)) assuming that self is a positive definite, real-symmetric matrix.



.. py:class:: InvOperator(inv, solver=None)

   Bases: :py:obj:`Operator`


   Generic implementation of the inverse of a linear operator.


   .. py:property:: shape

      Shape of array (matrix) representation of self.


   .. py:property:: symmetric

      True if self equals its adjoint.


   .. py:method:: __mul__(other)
      :abstractmethod:


      Multiply element-wise.



   .. py:method:: inv()

      Compute (multiplicative) inverse operator.



   .. py:method:: tonumpy()

      Numpy array (matrix) representation of self.



   .. py:method:: solve(vec)

      Solve linear equation self @ x = vec for x.



   .. py:method:: apply_np(vec)

      Apply to numpy array representation of vector, return numpy representation of result.



   .. py:method:: apply(vec)

      Apply operator on vector: self @ vec.



   .. py:method:: logdet()

      Compute log(det(self)) assuming that self is a positive definite, real-symmetric matrix.



   .. py:method:: rapply(vec)

      Apply transpose operator on vector: self.T @ vec.



.. py:class:: InvOperatorNp(inv, solver)

   Bases: :py:obj:`InvOperator`


   Inverse of a linear operator, constructed from a solver acting on numpy arrays.


   .. py:method:: apply_np(vec)

      Apply to numpy array representation of vector, return numpy representation of result.



   .. py:method:: apply(vec)

      Apply operator on vector: self @ vec.