..
   Copyright 2021 IRT Saint-Exupéry, https://www.irt-saintexupery.com

   This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
   International License. To view a copy of this license, visit
   http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative
   Commons, PO Box 1866, Mountain View, CA 94042, USA.

.. _gen_mda_algos:

MDA algorithms options
======================

List of available algorithms:
:ref:`GSNewtonMDA_options` -
:ref:`MDAChain_options` -
:ref:`MDAGaussSeidel_options` -
:ref:`MDAJacobi_options` -
:ref:`MDANewtonRaphson_options` -
:ref:`MDAQuasiNewton_options` -
:ref:`MDARoot_options` -
:ref:`MDASequential_options` -
:ref:`SobieskiMDAGaussSeidel_options` -
:ref:`SobieskiMDAJacobi_options` -



.. _GSNewtonMDA_options:


:class:`~gemseo.mda.sequential_mda.GSNewtonMDA`
-----------------------------------------------

Description
~~~~~~~~~~~


    Perform some GaussSeidel iterations and then NewtonRaphson iterations.
    


Options
~~~~~~~


- **grammar_type**, :code:`str` - the type of grammar to use for IO declaration either JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE 


- **linear_solver**, :code:`str` - type of linear solver to be used to solve the Newton problem 


- **linear_solver_tolerance**, :code:`float` - Tolerance of the linear solver in the adjoint equation 


- **max_mda_iter**, :code:`int` - maximum number of iterations 


- **max_mda_iter_gs**, :code:`int` - maximum number of iterations of the GaussSeidel solver 


- **name**, :code:`str` - name 


- **norm0**, :code:`float` - reference value of the norm of the residual to compute the decrease stop criteria. Iterations stops when norm(residual)/norm0<tolerance 


- **relax_factor**, :code:`float` - relaxation factor 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_lu_fact**, :code:`bool` - if True, when using adjoint/forward differenciation, store a LU factorization of the matrix to solve faster multiple RHS problem 


- **warm_start**, :code:`bool` - if True, the second iteration and ongoing start from the previous coupling solution 



.. _MDAChain_options:


:class:`~gemseo.mda.mda_chain.MDAChain`
---------------------------------------

Description
~~~~~~~~~~~

The **MDAChain** computes a chain of subMDAs and simple evaluations.

    The execution sequence is provided by the
    :class:`.DependencyGraph` class.
    


Options
~~~~~~~


- **chain_linearize**, :code:`bool` - linearize the chain of execution, if True Otherwise, linearize the oveall MDA with base class method Last option is preferred to minimize computations in adjoint mode in direct mode, chain_linearize may be cheaper 


- **max_mda_iter**, :code:`int` - maximum number of iterations for sub MDAs 


- **n_processes**, :code:`int` - number of processes for parallel run 


- **name**, :code:`str` - name of self 


- **norm0**, :code:`float` - reference value of the norm of the residual to compute the decrease stop criteria. Iterations stops when norm(residual)/norm0<tolerance 


- **sub_mda_class**, :code:`str` - the class to instantiate for sub MDAs 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_lu_fact**, :code:`bool` - if True, when using adjoint/forward differenciation, store a LU factorization of the matrix to solve faster multiple RHS problem 



.. _MDAGaussSeidel_options:


:class:`~gemseo.mda.gauss_seidel.MDAGaussSeidel`
------------------------------------------------

Description
~~~~~~~~~~~


    Perform a MDA analysis using a Gauss-Seidel algorithm,
    an iterative technique to solve the linear system:

    .. math::

       Ax = b

    by decomposing the matrix :math:`A`
    into the sum of a lower triangular matrix :math:`L_*`
    and a strictly upper triangular matrix :math:`U`.

    The new iterate is given by:

    .. math::

       x_{k+1} = L_*^{-1}(b-Ux_k)
    


Options
~~~~~~~


- **grammar_type**, :code:`str` - the type of grammar to use for IO declaration either JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE 


- **linear_solver_tolerance**, :code:`float` - Tolerance of the linear solver in the adjoint equation 


- **max_mda_iter**, :code:`int` - maximum number of iterations 


- **name**, :code:`str` - the name of the chain 


- **norm0**, :code:`float` - reference value of the norm of the residual to compute the decrease stop criteria. Iterations stops when norm(residual)/norm0<tolerance 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_lu_fact**, :code:`bool` - if True, when using adjoint/forward differenciation, store a LU factorization of the matrix to solve faster multiple RHS problem 


- **warm_start**, :code:`bool` - if True, the second iteration and ongoing start from the previous coupling solution 



.. _MDAJacobi_options:


:class:`~gemseo.mda.jacobi.MDAJacobi`
-------------------------------------

Description
~~~~~~~~~~~


    Perform a MDA analysis using a Jacobi algorithm,
    an iterative technique to solve the linear system:

    .. math::

       Ax = b

    by decomposing the matrix :math:`A`
    into the sum of a diagonal matrix :math:`D`
    and the reminder :math:`R`.

    The new iterate is given by:

    .. math::

       x_{k+1} = D^{-1}(b-Rx_k)
    


Options
~~~~~~~


- **acceleration**, :code:`str` - type of acceleration to be used to extrapolate the residuals and save CPU time by reusing the information from the last iterations, either None, or m2d, or secant, m2d is faster but uses the 2 last iterations 


- **linear_solver_tolerance**, :code:`float` - Tolerance of the linear solver in the adjoint equation 


- **max_mda_iter**, :code:`int` - maximum number of iterations 


- **n_processes**, :code:`int` - maximum number of processors on which to run 


- **name**, :code:`str` - the name of the chain 


- **norm0**, :code:`float` - reference value of the norm of the residual to compute the decrease stop criteria. Iterations stops when norm(residual)/norm0<tolerance 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_lu_fact**, :code:`bool` - if True, when using adjoint/forward differenciation, store a LU factorization of the matrix to solve faster multiple RHS problem 


- **use_threading**, :code:`bool` - use multithreading for parallel executions otherwise use multiprocessing 


- **warm_start**, :code:`bool` - if True, the second iteration and ongoing start from the previous coupling solution 



.. _MDANewtonRaphson_options:


:class:`~gemseo.mda.newton.MDANewtonRaphson`
--------------------------------------------

Description
~~~~~~~~~~~

Newton solver for MDA.

    The `Newton-Raphson method
    <https://en.wikipedia.org/wiki/Newton%27s_method>`__ is parameterized by a
    relaxation factor :math:`\alpha \in (0, 1]` to limit the length of the
    steps taken along the Newton direction.  The new iterate is given by:

    .. math::

       x_{k+1} = x_k - \alpha f'(x_k)^{-1} f(x_k)
    


Options
~~~~~~~


- **grammar_type**, :code:`str` - the type of grammar to use for IO declaration either JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE 


- **linear_solver**, :code:`str` - linear solver used to compute the Newton step 


- **linear_solver_tolerance**, :code:`float` - Tolerance of the linear solver in the adjoint equation 


- **max_mda_iter**, :code:`int` - maximum number of iterations 


- **name**, :code:`str` - name 


- **norm0**, :code:`float` - reference value of the norm of the residual to compute the decrease stop criteria. Iterations stops when norm(residual)/norm0<tolerance 


- **relax_factor**, :code:`float` - relaxation factor in the Newton step (default 1.) 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_lu_fact**, :code:`bool` - if True, when using adjoint/forward differenciation, store a LU factorization of the matrix to solve faster multiple RHS problem 


- **warm_start**, :code:`bool` - if True, the second iteration and ongoing start from the previous coupling solution 



.. _MDAQuasiNewton_options:


:class:`~gemseo.mda.newton.MDAQuasiNewton`
------------------------------------------

Description
~~~~~~~~~~~

Quasi-Newton solver for MDA.

    `Quasi-Newton methods
    <https://en.wikipedia.org/wiki/Quasi-Newton_method>`__
    include numerous variants
    (
    `Broyden
    <https://en.wikipedia.org/wiki/Broyden%27s_method>`__,
    `Levenberg-Marquardt
    <https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm>`__,
    ...).
    The name of the variant should be provided
    as a parameter :code:`method` of the class.

    The new iterate is given by:

    .. math::

       x_{k+1} = x_k - \rho_k B_k f(x_k)

    where :math:`\rho_k` is a coefficient chosen
    in order to minimize the convergence and :math:`B_k` is an approximation
    of the inverse of the Jacobian :math:`Df(x_k)^{-1}`.
    


Options
~~~~~~~


- **grammar_type**, :code:`str` - the type of grammar to use for IO declaration either JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE 


- **linear_solver_tolerance**, :code:`float` - Tolerance of the linear solver in the adjoint equation 


- **max_mda_iter**, :code:`int` - maximum number of iterations 


- **method**, :code:`str` - method name in scipy root finding, among self.QUASI_NEWTON_METHODS 


- **name**, :code:`str` - name 


- **norm0**, :code:`float` - reference value of the norm of the residual to compute the decrease stop criteria. Iterations stops when norm(residual)/norm0<tolerance 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_gradient**, :code:`bool` - if True, used the analytic gradient of the discipline 


- **use_lu_fact**, :code:`bool` - if True, when using adjoint/forward differenciation, store a LU factorization of the matrix to solve faster multiple RHS problem 


- **warm_start**, :code:`bool` - if True, the second iteration and ongoing start from the previous coupling solution 



.. _MDARoot_options:


:class:`~gemseo.mda.newton.MDARoot`
-----------------------------------

Description
~~~~~~~~~~~

Abstract class implementing MDAs based on (Quasi-)Newton methods.


Options
~~~~~~~


- **grammar_type**, :code:`str` - the type of grammar to use for IO declaration either JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE 


- **linear_solver_tolerance**, :code:`float` - Tolerance of the linear solver in the adjoint equation 


- **max_mda_iter**, :code:`int` - maximum number of iterations 


- **name**, :code:`str` - the name of the chain 


- **norm0**, :code:`Unknown` - 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_lu_fact**, :code:`bool` - if True, when using adjoint/forward differenciation, store a LU factorization of the matrix to solve faster multiple RHS problem 


- **warm_start**, :code:`bool` - if True, the second iteration and ongoing start from the previous coupling solution 



.. _MDASequential_options:


:class:`~gemseo.mda.sequential_mda.MDASequential`
-------------------------------------------------

Description
~~~~~~~~~~~


    Perform a MDA defined as a sequence of elementary MDAs.
    


Options
~~~~~~~


- **grammar_type**, :code:`str` - the type of grammar to use for IO declaration either JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE 


- **linear_solver_tolerance**, :code:`float` - Tolerance of the linear solver in the adjoint equation 


- **max_mda_iter**, :code:`int` - maximum number of iterations 


- **name**, :code:`str` - name 


- **norm0**, :code:`float` - reference value of the norm of the residual to compute the decrease stop criteria. Iterations stops when norm(residual)/norm0<tolerance 


- **tolerance**, :code:`float` - tolerance of the iterative direct coupling solver, norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating 


- **use_lu_fact**, :code:`bool` - use LU factorization 


- **warm_start**, :code:`bool` - if True, the second iteration and ongoing start from the previous coupling solution 



.. _SobieskiMDAGaussSeidel_options:


:class:`~gemseo.problems.sobieski.chains.SobieskiMDAGaussSeidel`
----------------------------------------------------------------

Description
~~~~~~~~~~~

Chains Sobieski disciplines to perform and MDA by Gauss Seidel algorithm
    Loops over Sobieski wrappers
    


Options
~~~~~~~


- **dtype**, :code:`str` - data array type, either "float64" or "complex128". 



.. _SobieskiMDAJacobi_options:


:class:`~gemseo.problems.sobieski.chains.SobieskiMDAJacobi`
-----------------------------------------------------------

Description
~~~~~~~~~~~

Chains Sobieski disciplines to perform and MDA by Jacobi algorithm
    Loops over Sobieski wrappers
    


Options
~~~~~~~


- **dtype**, :code:`str` - data array type, either "float64" or "complex128". 


- **n_processes**, :code:`integer` - maximum number of processors on which to run