Cross-solver comparisons
========================

femorph-solver is benchmarked against other FEM libraries on a shared cantilever
plate problem (1 m × 1 m × 10 mm steel, clamped at ``x=0``, 1 N ``-z``
tip load for static, 10 lowest modes for modal).  The problem, mesh,
and output numbers are defined in :mod:`perf.compare._problem` so
every backend solves exactly the same thing.

Live (in docs): open-source, pip-installable
---------------------------------------------

These run every time the documentation is built, on whatever CI
hardware is current.  Numbers shown in the gallery are therefore
always up to date.

- **scikit-fem** (BSD-3) — gallery:
  :doc:`fixed mesh </gallery/compare/example_compare_skfem>` and
  :doc:`mesh-size scaling </gallery/compare/example_compare_skfem_scaling>`.
  Physics agrees with femorph-solver to ~10⁻⁹ relative on ``f₁`` and ``tip u_z``
  at 40×40×2, confirming femorph-solver's SOLID185 linear-hex formulation.
  Wall-time ratio grows with mesh size because scikit-fem assembly is
  pure Python and femorph-solver's is a C++ batch kernel.

Local-only (requires conda): conda-forge pipelines
--------------------------------------------------

These have a runnable backend module in :mod:`perf.compare` but do not
execute on CI because the dependency is not pip-installable.  Install
locally and drive ``perf/compare/compare.py`` to get numbers.

- **FEniCSx** (``fenics-dolfinx`` on conda-forge) — see
  :mod:`perf.compare.run_fenicsx`.  Linear P1 hex on
  ``CellType.hexahedron`` with PETSc for the static solve and SLEPc
  (``GHEP`` shift-invert) for modal.

Planned backends (one PR each)
------------------------------

- **SfePy** — BSD-3 pip — live in docs.
- **CalculiX** (``ccx``) — GPL-2 external binary — offline snapshot
  (ships as pinned JSON, not rerun in CI).
- **OpenSeesPy** — BSD-like pip — likely live.
- **SimScale** — SaaS, requires a user account — offline snapshot
  captured manually via their UI/API and committed as a dated JSON.
- **Ansys MAPDL** — commercial — dated offline snapshot (the historical
  tables preserved in :file:`PERFORMANCE.md` at the repo root).

Each new backend lands as ``perf/compare/run_<name>.py`` + a gallery
example (for live ones) or a committed ``perf/compare/snapshots/<name>.json``
(for offline ones).  The aggregate comparison table renders from
whichever result files are present at doc-build time.