linear_algebra.src.conjugate_gradient
=====================================

.. py:module:: linear_algebra.src.conjugate_gradient

.. autoapi-nested-parse::

   Resources:
   - https://en.wikipedia.org/wiki/Conjugate_gradient_method
   - https://en.wikipedia.org/wiki/Definite_symmetric_matrix



Functions
---------

.. autoapisummary::

   linear_algebra.src.conjugate_gradient._create_spd_matrix
   linear_algebra.src.conjugate_gradient._is_matrix_spd
   linear_algebra.src.conjugate_gradient.conjugate_gradient
   linear_algebra.src.conjugate_gradient.test_conjugate_gradient


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

.. py:function:: _create_spd_matrix(dimension: int) -> Any

   Returns a symmetric positive definite matrix given a dimension.

   Input:
   dimension gives the square matrix dimension.

   Output:
   spd_matrix is an diminesion x dimensions symmetric positive definite (SPD) matrix.

   >>> import numpy as np
   >>> dimension = 3
   >>> spd_matrix = _create_spd_matrix(dimension)
   >>> _is_matrix_spd(spd_matrix)
   True


.. py:function:: _is_matrix_spd(matrix: numpy.ndarray) -> bool

   Returns True if input matrix is symmetric positive definite.
   Returns False otherwise.

   For a matrix to be SPD, all eigenvalues must be positive.

   >>> import numpy as np
   >>> matrix = np.array([
   ... [4.12401784, -5.01453636, -0.63865857],
   ... [-5.01453636, 12.33347422, -3.40493586],
   ... [-0.63865857, -3.40493586,  5.78591885]])
   >>> _is_matrix_spd(matrix)
   True
   >>> matrix = np.array([
   ... [0.34634879,  1.96165514,  2.18277744],
   ... [0.74074469, -1.19648894, -1.34223498],
   ... [-0.7687067 ,  0.06018373, -1.16315631]])
   >>> _is_matrix_spd(matrix)
   False


.. py:function:: conjugate_gradient(spd_matrix: numpy.ndarray, load_vector: numpy.ndarray, max_iterations: int = 1000, tol: float = 1e-08) -> Any

   Returns solution to the linear system np.dot(spd_matrix, x) = b.

   Input:
   spd_matrix is an NxN Symmetric Positive Definite (SPD) matrix.
   load_vector is an Nx1 vector.

   Output:
   x is an Nx1 vector that is the solution vector.

   >>> import numpy as np
   >>> spd_matrix = np.array([
   ... [8.73256573, -5.02034289, -2.68709226],
   ... [-5.02034289,  3.78188322,  0.91980451],
   ... [-2.68709226,  0.91980451,  1.94746467]])
   >>> b = np.array([
   ... [-5.80872761],
   ... [ 3.23807431],
   ... [ 1.95381422]])
   >>> conjugate_gradient(spd_matrix, b)
   array([[-0.63114139],
          [-0.01561498],
          [ 0.13979294]])


.. py:function:: test_conjugate_gradient() -> None

   >>> test_conjugate_gradient()  # self running tests