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 commercial code — it is an
independent solver developed from published FEM theory (Bathe,
Zienkiewicz, Hughes, Cook, and the peer-reviewed literature) with
the explicit goal of being **better, faster, and more transparent**
than the commercial alternatives.

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

- **A structural FEM solver.**  Linear static, modal, harmonic,
  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,
  MUMPS, MKL Pardiso) and eigen solvers (ARPACK, LOBPCG, PRIMME,
  dense) register too and are selected at call time.
- **Multi-solver deck interop.**  Foreign-deck readers translate
  established commercial-solver formats into the same neutral
  :class:`Model`:

  - :func:`femorph_solver.interop.mapdl.from_cdb` — Ansys MAPDL
    CDB decks
  - :func:`femorph_solver.interop.nastran.from_bdf` — NASTRAN BDF
  - :func:`femorph_solver.interop.abaqus.from_inp` — Abaqus INP
  - :func:`femorph_solver.interop.optistruct.from_fem` —
    Altair OptiStruct FEM

  Each reader rewrites the deck's element / load / boundary
  catalogue into femorph-solver's neutral kernel names at the
  boundary; downstream code never sees vendor-specific spelling.

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

- **Not a clone of any vendor product.**  Foreign-deck
  interoperability is a feature, not a goal in itself.  Compatibility
  layers exist so existing users can bring their meshes and load
  cases 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
  foreign deck; 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; nothing in
  the kernels is sourced from vendor manuals.
- **File formats** (CDB / BDF / INP / FEM input decks; RST / FULL /
  EMAT binary outputs from MAPDL where exercised) are treated as
  interoperability interfaces.  Their layouts are determined from
  the files themselves and from public community documentation —
  not from confidential vendor manuals.
- **Cross-solver benchmarks** use only observable inputs and
  outputs of legally-licensed installations (mesh in, numbers out).
  MAPDL is the most-frequently-used yardstick because the project
  has direct access to it and it is the oldest of the major
  commercial structural solvers, but it is not a uniquely
  privileged reference; NASTRAN / Abaqus / OptiStruct check rows
  land alongside it as their decks come online.
- **Goal**: a best-in-class open-source structural FEM solver that
  outperforms the commercial alternatives on every axis we
  measure — accuracy, speed, transparency, ease of use — *and*
  whose users can keep their existing decks intact during the
  migration.