pyHarm.Solver
=============

.. py:module:: pyHarm.Solver


Classes
-------

.. autoapisummary::

   pyHarm.Solver.SystemSolution
   pyHarm.Solver.FirstSolution


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

.. py:class:: SystemSolution(xs: numpy.ndarray, last_solution_pointer=None, **kwargs)

   Class that represents a solution of the system to be solved.

   This class is the main object that transits in the analysis process while solving a problem.
   The object contains information about its starting point, the previous SystemSolution it is linked to and the actual point the solver is studying.
   Once the solver has converged, the values of the residual and the solution point are stored in some of the attributes.

   :param xs: An array representing the starting point.
   :type xs: np.ndarray
   :param last_solution_pointer: A pointer to the last converged solution object.
   :param \*\*kwargs: Additional keyword arguments.

   .. attribute:: flag_restart

      Flag indicating if the solution is a restart (last_solution_pointer != index - 1).

      :type: bool

   .. attribute:: flag_accepted

      Flag indicating if the solution is considered valid.

      :type: bool

   .. attribute:: flag_bifurcation

      Flag indicating if a bifurcation has been detected at this point.

      :type: bool

   .. attribute:: flag_solved

      Flag indicating if the solution is complete and valid.

      :type: bool

   .. attribute:: flag_intosolver

      Flag indicating if the solution has gone through the solver.

      :type: bool

   .. attribute:: flag_R

      Flag indicating the presence of a residual result.

      :type: bool

   .. attribute:: flag_J

      Flag indicating the presence of a Jacobian result.

      :type: bool

   .. attribute:: flag_J_qr

      Flag indicating the availability of the Jacobian with QR decomposition.

      :type: bool

   .. attribute:: flag_J_lu

      Flag indicating the availability of the Jacobian with LU decomposition.

      :type: bool

   .. attribute:: flag_J_f

      Flag indicating the availability of the full-size Jacobian.

      :type: bool

   .. attribute:: index_insolve

      The index of the solution within the solver.

      :type: int

   .. attribute:: ds

      The step size for the continuation.

      :type: float

   .. attribute:: sign_ds

      Sign of the step size.

      :type: int

   .. attribute:: x_start

      An array representing the starting point.

      :type: np.ndarray

   .. attribute:: x

      An array representing the current solution point.

      :type: np.ndarray

   .. attribute:: x_pred

      An array representing the prediction point during continuation.

      :type: np.ndarray

   .. attribute:: R

      Residual values.

   .. attribute:: J_f

      Full-size Jacobian.

   .. attribute:: J_lu

      Jacobian with LU decomposition.

   .. attribute:: J_qr

      Jacobian with QR decomposition.

   .. attribute:: precedent_solution

      A pointer to the last converged solution.


   .. py:attribute:: index_insolve
      :value: 0



   .. py:attribute:: ds
      :value: 0.0



   .. py:attribute:: sign_ds
      :value: 1.0



   .. py:attribute:: x_start


   .. py:attribute:: x


   .. py:attribute:: x_pred


   .. py:attribute:: R
      :value: None



   .. py:attribute:: J_f
      :value: None



   .. py:attribute:: J_lu
      :value: None



   .. py:attribute:: J_qr
      :value: None



   .. py:attribute:: precedent_solution
      :value: None



   .. py:method:: _init_flags()

      Initialise the different flag attributes of the class.



   .. py:method:: CheckComplete()

      Checks if all elements required to proceed are present in the SystemSolution object.

      :returns: True if the solution is considered valid.
      :rtype: bool



   .. py:method:: SaveSolution(List: list)

      Saves the SystemSolution object in the provided list if it is complete.

      :param List: A list to save the SystemSolution object.
      :type List: list

      :raises ValueError: If the SystemSolution is not complete.



   .. py:method:: getJacobian(format: str = 'full', dump: bool = False) -> numpy.ndarray

      Returns the Jacobian in the specified format.

      :param format: The format of the Jacobian. Options: "full", "qr", "lu" (default: "full").
      :type format: str
      :param dump: If True, erases the Jacobian result with the format_in (default: False).
      :type dump: bool

      :returns: The Jacobian in the requested format, or None if the Jacobian is not available.
      :rtype: np.ndarray

      :raises ValueError: If the format is not compatible.



   .. py:method:: convertJacobian(format_in, format_out, dump=False)

      Converts the Jacobian format from format_in to format_out.

      :param format_in: The current format of the Jacobian.
      :type format_in: str
      :param format_out: The desired format of the Jacobian.
      :type format_out: str
      :param dump: If True, erases the Jacobian result with the format_in (default: False).
      :type dump: bool

      :returns: The updated flags and Jacobian data.
      :rtype: tuple

      :raises ValueError: If the format is not compatible.



.. py:class:: FirstSolution(xs)

   Bases: :py:obj:`SystemSolution`


   Inherits from the SystemSolution class with one major difference: there is no previous SystemSolution point
   for this class.

   :param xs: An array representing the starting point.
   :type xs: np.ndarray


   .. py:attribute:: x


   .. py:attribute:: x_pred