Utilities
========================

*#include <audi/invert_map.hpp>*

.. doxygenfunction:: audi::invert_map(const taylor_map<Cf, Monomial> &map_in, bool verbose = false)
.. .. cpp:function:: std::vector<gdual_d> invert_map(const std::vector<gdual_d> &map_in, bool verbose = false)
..
..    Inversion of Taylor series.
..
..    Consider a system of non linear equations in :math:`n` variables:
..    
..    .. math:: 
..    
..       \left\{
..       \begin{array}{l}
..       f_1(x_1, x_2, .., x_n) = 0 \\
..       ...                        \\
..       f_n(x_1, x_2, .., x_n) = 0 \\
..       \end{array}
..       \right.
..    
..    and represent each equation via a Taylor polynomial truncated at order :math:`m` (i.e. :math:`\in \mathcal P_{n,m}`) around
..    some point :math:`\overline {\mathbf x}`:
..    
..    .. math::
..    
..       \left\{
..       \begin{array}{l}
..       T_{f_1}(dx_1, dx_2, .., dx_n) = 0 \\
..       ...                        \\
..       T_{f_n}(dx_1, dx_2, .., dx_n) = 0 \\
..       \end{array}
..       \right.
..    
..    The above system of, now, polynomial equations can be written as :math:`C + M + N = C + \mathcal M = 0`, where we have
..    explicitly indicated the constant term :math:`C`, the linear term :math:`M` and the rest :math:`N`. The symbol
..    :math:`\mathcal M` indicates what is called Taylor map and its inverse is found by this function by performing
..    some Picard iterations (fixed point) over the following simple formal equalities:
..      
..    .. math::
..    
..       \mathcal M \circ \mathcal M^{-1} = \mathcal I \rightarrow  (M + N) \circ \mathcal M^{-1}  = \mathcal I \rightarrow M
..       \circ \mathcal M^{-1} + N \circ \mathcal M^{-1} = \mathcal I 
..       
..    and hence: 
..    
..    .. math::
..    
..       \mathcal M^{-1} = M^{-1} \circ \left(\mathcal I - N \circ \mathcal M^{-1}\right)
..       
..    which can be used to make a fixed point iterative scheme once
..    the inverse of the linear part :math:`M^{-1}` is found. Note that the inverse is guaranteed to exist if the linear part is invertible.
..      
..    :param map_in: The input map represented as an *std::vector* of *gdual<double>*. They can have a constant coefficient which will be neglected
..    :param verbose: when true some output is shown during the iterations
..    
..    :return: The inverse map :math:`\mathcal M^{-1}` represented as an *std::vector* of *gduals* with symbol set
..       [p0, p1, .. pn]
..    
..    :exception: std::invalid_argument if *map_in* is empty, if its linear part is not invertable, if the symbol set of the
..       map components are not all equal, if the map is not square (i.e. it is of size n with n symbols) or if the order of
..       the gduals are not all the same.
..
..    .. code-block:: c++
..
..       gdual<double> x(0., "x1", 9);
..       auto sinx = sin(x);
..       auto asinx = asin(x);
..       auto inv_sinx = invert_map({sinx}); 
..       std::cout << "sin x:\t\t" << sinx << std::endl;
..       std::cout << "asin x:\t\t" << asinx << std::endl;
..       std::cout << "inv sinx:\t" << inv_sinx[0] << std::endl;
..
..    The code above will produce the output
..
..    .. code-block:: c++
..
..       sin x:        dx1+2.75573e-06*dx1**9-0.166667*dx1**3+0.00833333*dx1**5-0.000198413*dx1**7
..       asin x:       dx1+0.0303819*dx1**9+0.166667*dx1**3+0.075*dx1**5+0.0446429*dx1**7
..       inv sinx:     dp0+0.0303819*dp0**9+0.166667*dp0**3+0.075*dp0**5+0.0446429*dp0**7
..
..
..