maths.cholesky_decomposition
============================

.. py:module:: maths.cholesky_decomposition


Functions
---------

.. autoapisummary::

   maths.cholesky_decomposition.cholesky_decomposition
   maths.cholesky_decomposition.solve_cholesky


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

.. py:function:: cholesky_decomposition(matrix: numpy.ndarray) -> numpy.ndarray

   Return a Cholesky decomposition of the matrix A.

   The Cholesky decomposition decomposes the square, positive definite matrix A
   into a lower triangular matrix L such that A = L L^T.

   https://en.wikipedia.org/wiki/Cholesky_decomposition

   Arguments:
   A -- a numpy.ndarray of shape (n, n)

   >>> A = np.array([[4, 12, -16], [12, 37, -43], [-16, -43, 98]], dtype=float)
   >>> L = cholesky_decomposition(A)
   >>> np.allclose(L, np.array([[2, 0, 0], [6, 1, 0], [-8, 5, 3]]))
   True

   >>> # check that the decomposition is correct
   >>> np.allclose(L @ L.T, A)
   True

   >>> # check that L is lower triangular
   >>> np.allclose(np.tril(L), L)
   True

   The Cholesky decomposition can be used to solve the linear system A x = y.

   >>> x_true = np.array([1, 2, 3], dtype=float)
   >>> y = A @ x_true
   >>> x = solve_cholesky(L, y)
   >>> np.allclose(x, x_true)
   True

   It can also be used to solve multiple equations A X = Y simultaneously.

   >>> X_true = np.random.rand(3, 3)
   >>> Y = A @ X_true
   >>> X = solve_cholesky(L, Y)
   >>> np.allclose(X, X_true)
   True


.. py:function:: solve_cholesky(lower_triangle: numpy.ndarray, right_hand_side: numpy.ndarray) -> numpy.ndarray

   Given a Cholesky decomposition L L^T = A of a matrix A, solve the
   system of equations A X = Y where the right-hand side Y is either
   a matrix or a vector.

   >>> L = np.array([[2, 0], [3, 4]], dtype=float)
   >>> Y = np.array([[22, 54], [81, 193]], dtype=float)
   >>> X = solve_cholesky(L, Y)
   >>> np.allclose(X, np.array([[1, 3], [3, 7]], dtype=float))
   True