Element library
===============

femorph-solver ships a library of structural finite elements.  Each
element is built from published FEM theory (textbook / journal
citations on its theory page).  Element names are **topology-first
and vendor-neutral** — ``HEX8``, ``HEX20``, ``TET10``, ``BEAM2``,
``QUAD4_SHELL``, etc.  Foreign-deck spellings (e.g. MAPDL
``SOLID185``, NASTRAN ``CHEXA``, Abaqus ``C3D8``) are translated to
these neutral names at each interop boundary; every internal call-
site sees only the neutral form.

Correctness is verified against two independent evidence sources:
analytical / textbook closed-form solutions (``tests/analytical/``)
and migration-safety agreement with established commercial solvers
on shared benchmarks.  Commercial solvers are yardsticks for
migration safety, not a source of implementation detail.

Pick an element by dimension and kinematics:

.. list-table::
    :widths: 22 22 56
    :header-rows: 1

    * - Element
      - Kind
      - Notes
    * - :doc:`TRUSS2 <truss2>`
      - 3D 2-node truss
      - Axial only; 3 DOF/node.
    * - :doc:`SPRING <spring>`
      - 3D 2-node spring
      - Longitudinal mode; 3 DOF/node.
    * - :doc:`POINT_MASS <point_mass>`
      - 1-node point mass
      - Translational-only (3 DOF/node).
    * - :doc:`BEAM2 <beam2>`
      - 3D 2-node Euler–Bernoulli beam
      - 6 DOF/node; axial + torsion + two bending planes.
    * - :doc:`QUAD4_PLANE <quad4_plane>`
      - 2D 4-node quad
      - 2 DOF/node; plane stress / plane strain.
    * - :doc:`QUAD4_SHELL <quad4_shell>`
      - 4-node Mindlin shell
      - Selective reduced integration; drilling stabilisation.
    * - :doc:`HEX8 <hex8>`
      - 3D 8-node hex
      - 2×2×2 Gauss; B-bar / enhanced-strain options.
    * - :doc:`HEX20 <hex20>`
      - 3D 20-node serendipity hex
      - Reduced 2×2×2 stiffness with Irons 14-point mass; degenerate
        ``WEDGE15`` and ``PYR13`` auto-dispatched.
    * - :doc:`TET10 <tet10>`
      - 3D 10-node tet
      - 4-point Keast Gauss (both K and M).

Registry and dispatch
---------------------

Element classes register into :mod:`femorph_solver.elements` and are
discovered by their neutral kernel name::

    from femorph_solver.elements import get, registered

    registered()
    # ['BEAM2', 'HEX20', 'HEX8', 'POINT_MASS', 'PYR13', 'QUAD4_PLANE',
    #  'QUAD4_SHELL', 'SPRING', 'TET10', 'TRUSS2', 'WEDGE15']

    hex_kernel = get("HEX8")

The native API (:meth:`femorph_solver.Model.assign`) takes a
typed :data:`~femorph_solver.ELEMENTS` spec rather than a string::

    import femorph_solver as fs
    model = fs.Model.from_grid(grid)
    model.assign(fs.ELEMENTS.HEX8, {"EX": 2.1e11, "PRXY": 0.30, "DENS": 7850.0})
    model.assign(
        fs.ELEMENTS.HEX8(integration="enhanced_strain"),
        {"EX": 2.1e11, "PRXY": 0.30, "DENS": 7850.0},
    )

Foreign-deck readers (:func:`femorph_solver.interop.mapdl.from_cdb`,
:func:`femorph_solver.interop.nastran.from_bdf`,
:func:`femorph_solver.interop.abaqus.from_inp`) translate their
respective catalogue names into the neutral kernel names above
before the model is constructed.

Every element class implements the
:class:`~femorph_solver.elements.ElementBase` interface — :meth:`ke`
for stiffness, :meth:`me` for mass, optional :meth:`ke_batch` /
:meth:`me_batch` for vectorised assembly.

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

    truss2
    spring
    point_mass
    beam2
    quad4_plane
    quad4_shell
    hex8
    hex20
    tet10