.. _lin-solve_hpp:

lin-solve.hpp
=============

This header file provides classes for solving linear systems using iterative methods, including a GMRES solver and a Krylov-subspace preconditioner.

Classes and Types
-----------------

.. doxygenclass:: sctl::KrylovPrecond
..   :members:
..

    **Constructor**:

    - ``KrylovPrecond()``: Constructor.

    **Methods**:

    - ``Size() const``: Get the size of the input vector to the operator.

    - ``Rank() const``: Get the cumulative size of the Krylov-subspaces.

    - ``Append(Qt, U)``: Append a Krylov-subspace to the operator.

    - ``Apply(x, comm) const``: Apply the preconditioner.


    **Usage guide**: :ref:`Using GMRES and KrylovPrecond classes <tutorial-gmres>`

|

.. doxygenclass:: sctl::GMRES
..   :members:
..

    **Constructor**:

    - ``GMRES(comm=Comm::Self(), verbose=true, gs=GramSchmidt::MGS, num_reorth=0)``: Constructor.

    **Member Functions**:

    - ``operator()(x, A, b, tol, max_iter=-1, use_abs_tol=false, solve_iter=nullptr, krylov_precond=nullptr) const``: Solve the linear system A(x) = b.

    **Types**:

    - ``ParallelOp``: Function type for the linear operator. The callback must
      not call ``Ax->ReInit(...)`` when ``Ax`` is already the right size;
      guard with ``if (Ax->Dim() != x.Dim()) Ax->ReInit(x.Dim());``.

    - ``GramSchmidt``: Orthogonalization scheme used in the Arnoldi step.
      ``MGS`` (Modified Gram-Schmidt — one reduction per basis vector;
      Allreduce-latency-bound on distributed runs) or ``CGS`` (Classical
      Gram-Schmidt — all ``k+1`` dot products batched into one Allreduce;
      pair with ``num_reorth >= 1`` for stability).


    **Usage guide**: :ref:`Using GMRES and KrylovPrecond classes <tutorial-gmres>`


|

.. raw:: html

   <div style="border-top: 3px solid"></div>
   <br>

.. literalinclude:: ../../include/sctl/lin-solve.hpp
   :language: c++