=======================================
Solve a System of Linear Equations (sv)                               [TOC:2]
=======================================

*sv* (defined in namespace `flens::lapack`) computes the solution to a real
system of linear equations

    *--[LATEX]-----*
    |              |
    |  A X = B,    |
    |              |
    *--------------*

where $A$ is an $n \times n$ matrix and $X$ and $B$ are $n \times n_{rhs}$
matrices.


The $LU$ decomposition with partial pivoting and row interchanges is
used to factor $A$ as

    *--[LATEX]-----*
    |              |
    |  A = P L U,  |
    |              |
    *--------------*

where $P$ is a permutation matrix, $L$ is unit lower triangular, and $U$ is
upper triangular.  The factored form of $A$ is then used to solve the
system of equations $A X = B$.

Interface: Multiple Right-Hand Sides
====================================
*--[CODEREF]----------------------------------------------------------------*
|                                                                           |
|  template <typename MA, typename VPIV, typename MB>                       |
|      typename RestrictTo<IsGeMatrix<MA>::value                            |
|                       && IsIntegerDenseVector<VPIV>::value                |
|                       && IsGeMatrix<MB>::value,                           |
|               typename RemoveRef<MA>::Type::IndexType>::Type              |
|      sv(MA &&A, VPIV &&piv, MB &&B);                                      |
|                                                                           |
*---------------------------------------------------------------------------*
                         [c:@N@flens@N@lapack@FT@>3#T#T#Tsv#&t0.0#&t0.1#&t0.]
                         [2#templatetypenameMA,typenameVPIV,typenameMBtypena]
                         [meRestrictToIsGeMatrixMAvalueandIsIntegerDenseVect]
                         [orVPIVvalueandIsGeMatrixMBvalue,typenameRemoveRefM]
                         [ATypeIndexTypeType                                ]

    A       `(input/output) real or complex valued GeMatrix`                   +
            On entry, the $n \times n$ coefficient matrix $A$.                 +
            On exit, the factors $L$ and $U$ from the factorization
            $A = P L U$.  The unit diagonal elements of $L$ are not stored.
    piv     `(output) integer valued DenseVector`                              +
            The pivot indices that define the permutation matrix $P$. Row $i$
            of the matrix was interchanged with $piv_i$.
    B       `(input/output) real or complex valued GeMatrix`                   +
            On entry, the $n \times n_{rhs}$ matrix of right hand side matrix
            $B$.                                                               +
            On exit, if the return value equals $0$, the $n \times n_{rhs}$
            solution matrix $X$.

    *Return value:*

    $i=0$    Successfull exit.
    $i>0$    $U_{i,i}$ is exactly zero.  The factorization has been completed,
             but the factor U is exactly singular, so the solution could not be
             computed.


Interface: Single Right-Hand Side
=================================
*--[CODEREF]----------------------------------------------------------------*
|                                                                           |
|  template <typename MA, typename VPIV, typename VB>                       |
|      typename RestrictTo<IsGeMatrix<MA>::value                            |
|                       && IsIntegerDenseVector<VPIV>::value                |
|                       && IsDenseVector<VB>::value,                        |
|               typename RemoveRef<MA>::Type::IndexType>::Type              |
|      sv(MA &&A, VPIV &&piv, VB &&b);                                      |
|                                                                           |
*---------------------------------------------------------------------------*
                         [c:@N@flens@N@lapack@FT@>3#T#T#Tsv#&t0.0#&t0.1#&t0.]
                         [2#templatetypenameMA,typenameVPIV,typenameVBtypena]
                         [meRestrictToIsGeMatrixMAvalueandIsIntegerDenseVect]
                         [orVPIVvalueandIsDenseVectorVBvalue,typenameRemoveR]
                         [efMATypeIndexTypeType                             ]

    A       `(input/output) real or complex valued GeMatrix`                   +
            On entry, the $n \times n$ coefficient matrix $A$.                 +
            On exit, the factors $L$ and $U$ from the factorization
            $A = P L U$.  The unit diagonal elements of $L$ are not stored.
    piv     `(output) integer valued DenseVector`                              +
            The pivot indices that define the permutation matrix $P$. Row $i$
            of the matrix was interchanged with $piv_i$.
    b       `(input/output) real or complex valued DenseVector`                +
            On entry, the right hand side vector $b$ with length $n$.          +
            On exit, if the return value equals $0$, the solution vector $x$.

    *Return value:*

    $i=0$    Successfull exit.
    $i>0$    $U_{i,i}$ is exactly zero.  The factorization has been completed,
             but the factor U is exactly singular, so the solution could not be
             computed.


Notes
=====

- *Example*: __lapack-gesv__.
- *sv* is a port of __dgesv__ and __zgesv__.  Also this documentation is
  taken from there.

:links: lapack-gesv -> doc:flens/examples/tut04-page03
        (d.+)       -> file:cxxlapack/netlib/lapack/$1.f
        (z.+)       -> file:cxxlapack/netlib/lapack/$1.f