qmat.qdelta =========== .. py:module:: qmat.qdelta .. autoapi-nested-parse:: Defines the base abstract class to generate :math:`Q_\Delta` approximations : the :class:`QDeltaGenerator` 🚀 Each submodule contains specializations of this class for many kind of methods : - :class:`timestepping` : based on time-stepping methods (Backward Euler, etc ...) - :class:`algebraic` : based on algebraic consideration on the :math:`Q` matrix - :class:`min` : diagonal approximations based on minimization .. rubric:: Examples >>> qGen:QGenerator = ... # any QGenerator object implemented in qmat.qcoeff.[...] >>> >>> # Generate QDelta coefficients with generic function >>> from qmat.qdelta import genQDeltaCoeffs >>> qDeltaBE = genQDeltaCoeffs("BE", nodes=qGen.nodes) # Backward Euler approximation >>> qDeltaLU = genQDeltaCoeffs("LU", Q=qGen.Q) # LU approximation >>> >>> # Generate QDelta coefficients with QDeltaGenerator objects >>> from qmat.qdelta.timestepping import BE >>> qDeltaBE = BE(nodes=qGen.nodes).getQDelta() >>> from qmat.qdelta.algebraic import LU >>> qDeltaLU = LU(Q=qGen.Q) >>> >>> # Simplified import for all QDeltaGenerator objects >>> from qmat.qdelta import QDELTA_GENERATORS # 💡 can also be imported from qmat directly >>> qDeltaBE = QDELTA_GENERATORS["BE"](nodes=qGen.nodes).getQDelta() >>> qDeltaLU = QDELTA_GENERATORS["LU"](Q=qGen.Q).getQDelta() .. note:: 📣 If you want to **cover all available approximations** implemented in `qmat`, we highly suggest to use the `qGen` keyword argument, allowing to extract any required parameter from a `QGenerator` object, e.g : >>> # Using generic function >>> for qdType in ["BE", "LU", "MIN-SR-S", "MIN-SR-NS", "MIN-SR-FLEX"]: >>> qDelta = genQDeltaCoeffs(qdType, qGen=qGen) >>> >>> # Using QDeltaGenerator objects >>> for qdType in ["BE", "LU", "MIN-SR-S", "MIN-SR-NS", "MIN-SR-FLEX"]: >>> qDelta = QDELTA_GENERATORS[qdType](qGen=qGen).getQDelta() 💡 This ensure forward compatibility in your code, so it can use any other :math:`Q_\Delta` approximations added later in `qmat` without modification. ⚠️ You can also specify :math:`Q_\Delta` specific parameter(s) in addition to `qGen` : in that case, the corresponding parameters extracted from `qGen` are **overridden**. Submodules ---------- .. toctree:: :maxdepth: 1 /api/qmat/qdelta/algebraic/index /api/qmat/qdelta/diag/index /api/qmat/qdelta/mincoeffs/index /api/qmat/qdelta/timestepping/index Attributes ---------- .. autoapisummary:: qmat.qdelta.QDELTA_GENERATORS Classes ------- .. autoapisummary:: qmat.qdelta.QDeltaGenerator Functions --------- .. autoapisummary:: qmat.qdelta.register qmat.qdelta.genQDeltaCoeffs Package Contents ---------------- .. py:class:: QDeltaGenerator(Q, **kwargs) Base abstract class for :math:`Q_\Delta` coefficients generators. :Parameters: * **Q** (*np.ndarray*) -- The :math:`Q` matrix of the base approximated method. * **\*\*kwargs** -- Additional parameters given in for generic calls, ignored by the class. .. py:method:: isKDependent() Wether or not the :math:`Q_\Delta` coefficients varies with the iterations .. py:attribute:: Q :type: numpy.ndarray :math:`Q` matrix of the approximated time-integration method .. py:method:: extractParams(qGen: qmat.qcoeff.QGenerator) -> dict :staticmethod: Extract from a :math:`Q`-generator object all parameters required to instantiate the :math:`Q_\Delta`-generator .. py:property:: size :type: int Dimension of the approximated :math:`Q`-coefficients (number of nodes) .. py:property:: zeros :type: numpy.ndarray Seros matrix with the same size of the underlying :math:`Q` matrix .. py:method:: computeQDelta(k=None) -> numpy.ndarray :abstractmethod: Compute and returns the :math:`Q_\Delta` matrix, has to be implemented in the specialized class. :Parameters: **k** (*int, optional*) -- Iteration number of the approximation. The default is None. :returns: **QDelta** :rtype: np.ndarray .. py:method:: getQDelta(k=None, copy=True) Generic method to retrieve the :math:`Q_\Delta` coefficients :Parameters: * **k** (*int, optional*) -- Iteration number of the approximation (if needed). The default is None. * **copy** (*bool, optional*) -- Return a copy of the the result returned by `computeQDelta`. The default is True. :returns: **QDelta** :rtype: np.ndarray .. py:method:: getSDelta(k=None) Compute the :math:`S_\Delta` matrix (approximation of :math:`S`). :Parameters: **k** (*int, optional*) -- Iteration number, used when the approximation depends on it. The default is None. :returns: **SDelta** :rtype: np.ndarray .. py:property:: dTau :type: numpy.ndarray The :math:`\delta_\tau` coefficients associated to :math:`Q_\Delta` .. py:method:: genCoeffs(k=None, form='Z2N', dTau=False) Generic method to produce :math:`Q_\Delta` coefficients :Parameters: * **k** (*int or list, optional*) -- Iteration(s) for the approximation. The default is None. * **form** (*str, optional*) -- Build approximation in zero-to-nodes (Z2N) or node-to-node (N2N). The default is "Z2N". * **dTau** (*bool, optional*) -- Wether or not to return the :math:`\delta_\tau`. The default is False. :returns: If `k` is a scalar or `None`, returns a MxM matrix. If `k` is a list, returns a len(k)xMxM matrix. If `dTau=True`, returns a tuple `(QDelta, dTau)`. :rtype: np.ndarray or tuple .. py:data:: QDELTA_GENERATORS :type: dict[str, type[QDeltaGenerator]] Dictionary containing all specialized :class:`QDeltaGenerator` classes .. py:function:: register(cls: type[T]) -> type[T] Class decorator to register a specialized :class:`QDeltaGenerator` class in `qmat` .. py:function:: genQDeltaCoeffs(qDeltaType, nSweeps=None, form='Z2N', dTau=False, **params) Generic function to produce :math:`Q_\Delta` coefficients :Parameters: * **qDeltaType** (*str or list*) -- The type of approximation, can be a list to have several sweeps. * **nSweeps** (*int, optional*) -- Number of sweeps when :math:`Q_\Delta` matrices are required for several sweeps. The default is None. * **form** (*str, optional*) -- Build approximation in zero-to-nodes (Z2N) or node-to-node (N2N). The default is "Z2N". * **dTau** (*bool, optional*) -- Wether or not to return the :math:`\delta_\tau`. The default is False. * **\*\*params** -- Additional arguments used to instantiate all :class:`QDeltaGenerator` :returns: If `qDeltaType` is a string, returns a :math:`M \times M` matrix. If `qDeltaType` is a list or `nSweeps != None`, returns a :math:`N_{sweeps} \times M \times M` matrix. If `dTau=True`, returns a tuple `(QDelta, dTau)`. :rtype: np.ndarray or tuple