MAPDL interop
=============

femorph-solver is a general-purpose structural solver with a
**secondary** MAPDL compatibility layer.  If your starting point is
a MAPDL workflow (a CDB deck, an RST result, an APDL-style
declaration sequence), this page is where to start.  If you're
building from scratch, use the native :class:`~femorph_solver.Model`
primitives shown in the :doc:`quickstart` — they're the primary API
and will stay so.

The deep dive on format compatibility lives in
:doc:`/user-guide/mapdl-compatibility`.

Load a CDB deck
---------------

One call (``from_cdb``) reads MAPDL's ASCII deck format and returns
a :class:`~femorph_solver.Model` ready to assemble::

    from femorph_solver.mapdl_api.cdb import from_cdb

    model = from_cdb("rotor_sector.cdb")
    result = model.modal_solve(n_modes=12)

The CDB's ``ET`` table is translated on load — every element id
declared with ``ET, i, SOLID186`` is registered against the HEX20
kernel automatically.  ``/UNITS`` is detected and stamped onto
``model.unit_system``.  ``mapdl-archive`` (MIT) handles the parse;
MAPDL itself is never invoked.

APDL-style declaration commands
-------------------------------

When porting a deck line-by-line, the MAPDL-compat verbs mirror the
APDL command set one-for-one:

.. list-table::
    :widths: 18 42 40
    :header-rows: 1

    * - APDL
      - Native equivalent
      - Notes
    * - ``ET, id, name``
      - ``model.et(id, name)``
      - Accepts neutral (``"HEX8"``) or MAPDL (``"SOLID185"``) names;
        both resolve to the same kernel.
    * - ``MP, prop, mat_id, value``
      - ``model.mp(prop, mat_id, value)``
      - One property at a time.  Prefer
        :meth:`~femorph_solver.Model.assign` for native code.
    * - ``R, id, v1, v2, …``
      - ``model.r(id, v1, v2, …)``
      - Real-constant arrays.
    * - ``D, node, label, value``
      - ``model.d(node, label, value)``
      - Native shortcut: :meth:`~femorph_solver.Model.fix`.
    * - ``F, node, label, value``
      - ``model.f(node, label, value)``
      - Native shortcut: :meth:`~femorph_solver.Model.apply_force`.

A MAPDL-literal quickstart equivalent:

.. code-block:: python

    import femorph_solver as fs

    model = fs.Model.from_grid(fs.examples.quarter_arc_sector())

    # APDL-literal declaration
    model.et(1, "SOLID185")              # ET, 1, SOLID185
    model.mp("EX",   1, 2.1e11)          # MP, EX,   1, 2.1e11
    model.mp("PRXY", 1, 0.30)            # MP, PRXY, 1, 0.30
    model.mp("DENS", 1, 7850.0)          # MP, DENS, 1, 7850.0

    # One D per pinned node — hence why the native `fix(where=...)`
    # is preferable when not porting from an APDL macro.
    for nn in (1, 2, 3, 4):
        model.d(nn, "ALL", 0.0)          # D, nn, ALL, 0

    result = model.modal_solve(n_modes=10)

Both styles produce identical stamps on the Model (``et`` / ``mp`` /
``d`` / ``f`` are the same code path as the native primitives; the
native methods just compose them).  Mixing is allowed; the test
``test_native_api_equivalent_to_mapdl_verbs`` pins round-trip
equivalence.

Format status
-------------

.. list-table::
    :widths: 15 15 15 55
    :header-rows: 1

    * - Format
      - Read
      - Write
      - Notes
    * - CDB
      - ✅
      - ❌
      - Via ``mapdl-archive``.  Supports SOLID185/186/187, SHELL181,
        BEAM188, LINK180, COMBIN14, MASS21, PLANE182 + degenerate
        SOLID186 (wedge, pyramid).
    * - RST
      - ✅
      - 🚧
      - Read via ``ansys-mapdl-reader``; progressive write in
        :mod:`femorph_solver.mapdl_api.io.rst_schema`.
    * - FULL
      - ✅
      - 🚧
      - K / M matrix export; :mod:`femorph_solver.mapdl_api.io.full_schema`.
    * - EMAT
      - ✅
      - 🚧
      - Per-element K / M; :mod:`femorph_solver.mapdl_api.io.emat_schema`.
    * - MODE / SUB / DB
      - ❌
      - ❌
      - Planned.

Element compatibility
---------------------

Each registered element targets the same behaviour as its MAPDL
counterpart under the default KEYOPT settings.  See the
:doc:`/gallery/elements/index` for bit-level parity tests and the
per-element pages under :doc:`/user-guide/pre-processing/elements/index` for the
KEYOPT table.