Overview
========

**femorph-solver** is an open-source, Python-first finite-element solver
for structural mechanics.  It is *not* a reimplementation, clone, or
reverse-engineering of any proprietary code — it is an independent
solver developed from published FEM theory (Bathe, Zienkiewicz,
Hughes, Cook, and the peer-reviewed literature).

What it is
----------

- **A structural FEM solver.**  Linear static, modal, transient (Newmark-β),
  and cyclic-symmetry modal analyses on linear-elastic media.
- **Python-first.**  A :class:`~femorph_solver.Model` wraps a
  :class:`pyvista.UnstructuredGrid`; the rest of the public API is
  NumPy / SciPy / pyvista.
- **Pluggable under the hood.**  Elements register into a dispatch
  registry; linear solvers (PARDISO, CHOLMOD, UMFPACK, SuperLU) and
  eigen solvers (ARPACK, LOBPCG, PRIMME, dense) register too and are
  selected at call time.
- **MAPDL-interoperable at the deck level.**  CDB input files load
  directly; RST / EMAT / FULL binary formats read and (progressively)
  write; element names, KEYOPT options, and DOF conventions match
  MAPDL so an existing deck runs without translation.

What it isn't
-------------

- **Not a clone of any vendor product.**  File-format interoperability
  is a feature, not a goal in itself.  MAPDL compatibility is there so
  existing users can bring their meshes over; the solver is evaluated
  and developed against the academic literature.
- **Not a nonlinear solver (yet).**  The current scope is small-strain
  linear elasticity.  Contact, plasticity, large deformation are on
  the roadmap but not in any released milestone.
- **Not a mesher.**  femorph-solver consumes a pyvista mesh or a CDB; mesh
  generation is intentionally delegated to other tools.

Positioning and sources
-----------------------

- **Element formulations** are derived from published academic sources
  (textbooks and peer-reviewed papers).  Each element's theory page
  cites the reference it was built from.
- **File formats** (CDB input decks; RST / FULL / EMAT binary outputs)
  are treated as interoperability interfaces.  Their layouts are
  determined from the files themselves and from public community
  documentation, not from confidential vendor manuals.
- **Benchmarks against MAPDL** use only observable inputs and outputs
  of a legally-licensed MAPDL installation (mesh in, numbers out).
  The comparison is scientific — same problem, different solver, see
  how they line up.
- **Goal**: a best-in-class OSS structural FEM solver whose users
  happen to be able to keep their existing MAPDL decks.  Not a
  drop-in replacement product.