qmat.qcoeff
===========

.. py:module:: qmat.qcoeff

.. autoapi-nested-parse::

   Defines the base abstract class to generate :math:`Q`-coefficients (Butcher tables) :
   the :class:`QGenerator` 🚀

   Each submodule contains specializations of this class for many kind of
   methods :

   - :class:`collocation` : Collocation based
   - :class:`butcher` : Runge-Kutta based (Butcher tables)



Submodules
----------

.. toctree::
   :maxdepth: 1

   /api/qmat/qcoeff/butcher/index
   /api/qmat/qcoeff/collocation/index


Attributes
----------

.. autoapisummary::

   qmat.qcoeff.Q_GENERATORS


Classes
-------

.. autoapisummary::

   qmat.qcoeff.QGenerator


Functions
---------

.. autoapisummary::

   qmat.qcoeff.register
   qmat.qcoeff.genQCoeffs


Package Contents
----------------

.. py:class:: QGenerator



   Base abstract class for all :math:`Q`-coefficients generators


   .. py:method:: getInstance()
      :classmethod:


      Provide an instance of this QGenerator using default parameters.



   .. py:property:: nodes
      :abstractmethod:


      Nodes :math:`\tau` (:math:`c` coefficients in Butcher table)


   .. py:property:: Q
      :abstractmethod:


      :math:`Q` coefficients (:math:`A` Butcher table)


   .. py:property:: weights
      :abstractmethod:


      Weights :math:`\omega` (:math:`b` coefficients in Butcher table)


   .. py:property:: weightsEmbedded
      :abstractmethod:


      Weights for a secondary lower order method from the same stages.


   .. py:property:: nNodes
      :type: int


      Number of nodes (or stages) for this QGenerator


   .. py:property:: rightIsNode
      :type: bool


      Wether or not the last nodes is the right boundary


   .. py:property:: T
      :type: numpy.ndarray


      Transfer matrix from zero-to-nodes to node-to-node


   .. py:property:: S
      :type: numpy.ndarray


      Quadrature matrix in node to node (N2N)


   .. py:property:: Tinv
      :type: numpy.ndarray


      Transfer matrix from node-to-node to zero-to-node


   .. py:property:: hCoeffs
      :type: numpy.ndarray


      :math:`h` interpolation coefficients for the right boundary


   .. py:method:: genCoeffs(form='Z2N', hCoeffs=False, embedded=False)

      Generate :math:`Q`-coefficients of this :class:`QGenerator` object.

      :Parameters: * **form** (*str, optional*) -- Write coefficients in zero-to-nodes (Z2N) or node-to-node (N2N).
                     The default is "Z2N".
                   * **hCoeffs** (*bool, optional*) -- Wether or not returning the :math:`h` coefficients. The default is False.
                   * **embedded** (*bool, optional*) -- Wether or not returning the embedded :math:`h` coefficients.
                     The default is False.

      :returns: **out** -- Contains (nodes, weights, Q).
                If `hCoeffs=True`, returns (nodes, weights, Q, hCoeffs).
                If `embedded=True`, `weights` is a 2xM array containing embedded weights in `weights[1]`.
      :rtype: tuple



   .. py:property:: order
      :abstractmethod:


      Global convergence order of the method


   .. py:property:: orderEmbedded
      :type: int


      Global convergence order of the associated embedded method


   .. py:method:: solveDahlquist(lam, u0, tEnd, nSteps, useEmbeddedWeights=False)

      Solve the Dahlquist test problem

      .. math::

          \frac{du}{dt} = \lambda u, \quad t \in [0, T], \quad u(0)=u_0

      :Parameters: * **lam** (*complex or float*) -- The :math:`\lambda` coefficient.
                   * **u0** (*complex or float*) -- The initial solution :math:`u_0`.
                   * **tEnd** (*float*) -- Final time :math:`T`.
                   * **nSteps** (*int*) -- Number of time-step for the whole :math:`[0,T]` interval.
                   * **useEmbeddedWeights** (*bool, optional*) -- Wether or not use the embedded weights for the step update. The default is False.

      :returns: **uNum** -- Array containing the `nSteps+1` solutions :math:`\{u(0), ..., u(T)\}`.
      :rtype: np.ndarray



   .. py:method:: errorDahlquist(lam, u0, tEnd, nSteps, uNum=None, useEmbeddedWeights=False)

      Compute :math:`L_\infty` error in time for the Dahlquist problem

      :Parameters: * **lam** (*complex or float*) -- The :math:`\lambda` coefficient.
                   * **u0** (*complex or float*) -- The initial solution :math:`u_0`.
                   * **tEnd** (*float*) -- Final time :math:`T`.
                   * **nSteps** (*int*) -- Number of time-step for the whole :math:`[0,T]` interval.
                   * **uNum** (*np.ndarray, optional*) -- Numerical solution, if not provided use the `solveDahlquist` method
                     to compute the solution. The default is None.
                   * **useEmbeddedWeights** (*bool, optional*) -- Wether or not use the embedded weights for the step update. The default is False.

      :returns: The :math:`L_\infty` norm.
      :rtype: float



.. py:data:: Q_GENERATORS
   :type:  dict[str, type[QGenerator]]

   Dictionary containing all specialized :class:`QGenerator` classes, with all their aliases

.. py:function:: register(cls: type[T]) -> type[T]

   Class decorator to register a specialized :class:`QGenerator` class in qmat


.. py:function:: genQCoeffs(qType, form='Z2N', hCoeffs=False, embedded=False, **params)

   Generate :math:`Q`-coefficients for a given method

   :Parameters: * **qType** (*str*) -- Name (or alias) of the QGenerator.
                * **form** (*str, optional*) -- Write coefficients in zero-to-nodes (Z2N) or node-to-node (N2N).
                  The default is "Z2N".
                * **hCoeffs** (*bool, optional*) -- Wether or not returning the :math:`h` coefficients. The default is False.
                * **embedded** (*bool, optional*) -- Wether or not returning the embedded :math:`h` coefficients.
                  The default is False.
                * **\*\*params** -- Parameters to be used to instantiate the QGenerator.

   :returns: **out** -- Contains (nodes, weights, Q).
             If `hCoeffs=True`, returns (nodes, weights, Q, hCoeffs).
             If `embedded=True`, `weights` is a 2xM array containing embedded weights in `weights[1]`.
   :rtype: tuple