Solving
=======

The solve phase turns a pre-processed :class:`~femorph_solver.Model`
into numbers.  femorph-solver exposes four top-level analyses and shares a
single backend registry underneath them:

.. grid:: 1 2 2 2
    :gutter: 3

    .. grid-item-card:: Static
        :link: static
        :link-type: doc

        :math:`K u = F` — one factorisation, one back-solve.  The
        fastest path, and the pre-stress foundation for everything
        else.

    .. grid-item-card:: Modal
        :link: modal
        :link-type: doc

        :math:`K \varphi = \omega^2 M \varphi` — free-vibration
        eigenpairs via ARPACK / LOBPCG / PRIMME / dense.

    .. grid-item-card:: Transient
        :link: transient
        :link-type: doc

        :math:`M \ddot{u} + C \dot{u} + K u = F(t)` — Newmark-β
        time integration with a one-time factorisation.

    .. grid-item-card:: Cyclic-symmetry modal
        :link: cyclic
        :link-type: doc

        One-sector reduction + harmonic-index phase constraints for
        rotors and other periodic structures.

Backend and performance
-----------------------

.. grid:: 1 3 3 3
    :gutter: 3

    .. grid-item-card:: Choosing a solver
        :link: choosing-a-solver
        :link-type: doc

        The linear / eigen backend registry, how ``"auto"`` picks,
        and when to override.

    .. grid-item-card:: Performance
        :link: performance
        :link-type: doc

        Wall-time numbers for assembly, static, and modal across
        backends and mesh sizes.

    .. grid-item-card:: Thread control
        :link: threads
        :link-type: doc

        BLAS / OpenMP cap via :func:`femorph_solver.set_thread_limit`,
        ``FEMORPH_SOLVER_NUM_THREADS``, and the per-call
        ``thread_limit`` kwarg.

Extras
------

.. grid:: 1 2 2 2
    :gutter: 3

    .. grid-item-card:: Solver exploration
        :link: solver-exploration
        :link-type: doc

        In-depth investigation of every sparse SPD direct solver we
        considered as an alternative to MKL Pardiso — measured
        results, the NixOS OpenBLAS 0.3.30 bug we hit, why STRUMPACK
        HSS didn't land on hex elasticity, and a drop-in
        ``MumpsSolver`` adapter.

.. toctree::
    :hidden:
    :maxdepth: 1

    static
    modal
    transient
    cyclic
    choosing-a-solver
    performance
    threads
    benchmark
    estimating
    solver-exploration
    ooc-limits