Solver algorithms
=================

Reference for the analysis types and backend algorithms femorph-solver
ships.  The :doc:`user-guide </user-guide/solving/index>` section
walks through how to drive each solver; this page lists the
underlying algorithm and its sources.

.. contents:: Solvers at a glance
    :local:
    :depth: 1

Static
------

Linear static analysis :math:`\mathbf{K}\mathbf{u} = \mathbf{f}`
after Dirichlet elimination.  Driven by :meth:`Model.solve`.

* **Boundary-condition reduction.** Master/slave partitioning —
  Cook §2.10; Bathe §3.4.
* **Linear backend.** Any SPD-capable solver from the auto-chain
  (Pardiso → CHOLMOD → MUMPS → UMFPACK → SuperLU) resolves the
  reduced system.

Full cites in :mod:`femorph_solver.solvers.static`.

Modal
-----

Generalised symmetric-definite eigenproblem
:math:`\mathbf{K}\boldsymbol{\phi}=\omega^{2}\mathbf{M}\boldsymbol{\phi}`.
Driven by :meth:`Model.modal_solve`.

* **Default backend.** Shift-invert Lanczos via ARPACK's
  ``eigsh(..., sigma=0)``.  Lehoucq, Sorensen, Yang, *ARPACK Users'
  Guide*, 1998; Ericsson-Ruhe, *Math. Comp.* 1980.
* **Autotune (``eigen_solver="auto"``).** Dispatches ARPACK for
  small / medium problems and PRIMME for large or many-mode runs
  when installed.  PRIMME — Stathopoulos & McCombs, *ACM TOMS*
  2010.
* **Optional LOBPCG.** Factor-free path with a selectable
  preconditioner (``"factor"`` / ``"jacobi"`` / ``"none"``) for
  memory-constrained regimes.  Knyazev 2001.
* **Eigenpair orthogonality.** ``φᵢᵀ M φⱼ = δᵢⱼ`` to machine
  precision on converged modes; verified by
  ``tests/analytical/test_conservation.py``.

Full cites in :mod:`femorph_solver.solvers.modal` and the backend
modules under :mod:`femorph_solver.solvers.eigen`.

Cyclic modal
------------

Per-harmonic-index modal analysis on a single sector.  Driven by
:meth:`Model.cyclic_modal_solve` and the functional
:func:`femorph_solver.solvers.cyclic.solve_cyclic_modal`.

* **Constraint reduction.** ``P^H K P`` complex-Hermitian
  reduction per harmonic index :math:`k`; the plan is cached once
  across :math:`k` (topology-invariant, see
  :mod:`femorph_solver.solvers.cyclic._CyclicReductionPlan`).
* **Real augmentation identity.** Complex Hermitian ``(K, M)``
  are factored at the n-sized complex level inside the OPinv, then
  embedded into a real 2n system only for the eigsh iteration —
  halves the factor cost.  Grimes-Lewis-Simon,
  *SIAM J. Matrix Anal. Appl.* 15 (1994), §5.
* **Theory provenance.** Thomas, *J. Sound Vib.* 1979;
  Wildheim, *J. Appl. Mech.* 1979.

Full cites in :mod:`femorph_solver.solvers.cyclic`.

Transient
---------

Newmark-β time-integration for
:math:`\mathbf{M}\ddot{\mathbf{u}} + \mathbf{C}\dot{\mathbf{u}} +
\mathbf{K}\mathbf{u} = \mathbf{f}(t)`.  Driven by
:meth:`Model.transient_solve`.

* **Scheme.** Newmark 1959 with γ = 0.5, β = 0.25 (average
  acceleration; unconditionally stable).
* **Damping.** Optional Rayleigh damping ``C = αM + βK``.
* **Source.** Hughes §9.1–§9.2; Bathe §9.2.

Full cites in :mod:`femorph_solver.solvers.transient`.

Harmonic (scaffolded)
---------------------

Frequency-domain steady-state response :math:`(\mathbf{K} -
\omega^{2}\mathbf{M} + i\omega\mathbf{C})\tilde{\mathbf{u}} =
\tilde{\mathbf{f}}`.  Scaffolding lives in
:mod:`femorph_solver.solvers.harmonic`; full validation against a
MAPDL ``HARFRQ`` sweep is roadmap.

Linear backends
---------------

Shift-invert factorisation is routed through a pluggable linear
solver registry.  Every backend is wrapped around an established
upstream implementation; the wrappers cite their upstream paper
in the ``References`` docstring block.

.. list-table::
    :header-rows: 1
    :widths: 18 26 56

    * - Name
      - Kind
      - Upstream
    * - ``superlu``
      - direct, LU
      - scipy.sparse.linalg.splu — Demmel/Eisenstat/Gilbert/Li/Liu 1999; Li 2005
    * - ``cholmod``
      - direct, Cholesky (SPD)
      - SuiteSparse CHOLMOD — Chen/Davis/Hager/Rajamanickam 2008
    * - ``umfpack``
      - direct, LU
      - SuiteSparse UMFPACK — Davis, ACM TOMS 2004
    * - ``pardiso``
      - direct, LU / Cholesky
      - Intel MKL Pardiso via pypardiso — Schenk & Gärtner 2004, 2006
    * - ``mkl_direct``
      - direct, LU / Cholesky
      - Intel MKL Pardiso via in-tree ctypes wrapper (PR #126); unlocks ``iparm`` control + out-of-core factor
    * - ``mumps``
      - direct, multifrontal
      - MUMPS via ``python-mumps`` — Amestoy et al. 2001, 2006
    * - ``cg``
      - iterative, Krylov
      - scipy ``cg`` — Hestenes & Stiefel 1952
    * - ``gmres``
      - iterative, Krylov
      - scipy ``gmres`` — Saad & Schultz 1986
    * - ``pyamg``
      - iterative, algebraic multigrid (SPD)
      - PyAMG — Ruge/Stüben 1987; Bell/Olson/Schroder

Full cites live in each backend's module docstring under
:mod:`femorph_solver.solvers.linear`.

Eigen backends
--------------

.. list-table::
    :header-rows: 1
    :widths: 18 82

    * - Name
      - Algorithm / source
    * - ``arpack``
      - Implicitly-restarted Arnoldi, shift-invert.  Lehoucq/Sorensen 1996; Lehoucq/Sorensen/Yang 1998 (Users' Guide)
    * - ``lobpcg``
      - Locally-optimal block preconditioned CG.  Knyazev 2001; Knyazev et al. 2007 (BLOPEX)
    * - ``primme``
      - Preconditioned iterative multi-method eigensolver.  Stathopoulos/McCombs 2010; Davidson 1975
    * - ``lapack_dense``
      - Dense LAPACK ``syevr`` / ``heevr`` for small problems.  LAPACK Users' Guide 1999; Parlett 1998 §7; Golub/Van Loan §8

Full cites live in each backend module under
:mod:`femorph_solver.solvers.eigen`.

.. seealso::

    :doc:`/user-guide/solving/index` — how-to walk-throughs for each
    analysis type, backend autotune behaviour, and performance
    notes.