Usage with the MUSES Calculation Engine
=======================================

Module name
-----------

.. code-block:: yaml

   module: metamodel

Labels
------

Input
~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 50 30

   * - Label
     - Description
     - Path (inside container)
   * - ``config``
     - Configurational and physical parameters of the module
     - ``/opt/input/config.yaml``

Output
~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 50 30

   * - Label
     - Description
     - Path (inside container)
   * - ``eos``
     - Tabulated equation of state (one row per grid point)
     - ``/opt/output/eos.csv``
   * - ``status``
     - Module execution status (code and message)
     - ``/opt/output/status.yaml``

Workflow example
----------------

The snippet below computes a metamodel EOS and pipes it into the ``lepton``
module for a beta-equilibrium solution:

.. code-block:: yaml

   processes:
   - name: metamodel_eos
     module: metamodel
     config:
       model_regime: relativistic
       bulk_properties:
         parametrization: ''
         BE: -15.97
         n0: 0.1595
         K0: 230.0
         Q0: -225.0
         Z0: -443.0
         Esym: 32.01
         Lsym: 46.0
         Ksym: -120.0
         Qsym: 350.0
         Zsym: -690.0
         meff_norm: 0.89
         meff_splitting: 0.0
         b0: 6.9
         bsym: 0.0
       grid:
         nB_grid: linear
         nB_min: 0.05
         nB_max: 0.8
         nB_points: 50
         delta_grid: linear
         delta_min: 0.0
         delta_max: 1.0
         delta_points: 25
   - name: lepton_mm
     module: lepton
     config:
       global:
         use_beta_equilibrium: true
     pipes:
       input_eos:
         label: eos
         module: metamodel
         process: metamodel_eos
   components:
   - type: chain
     name: workflow
     sequence:
     - metamodel_eos
     - lepton_mm

The ``input_eos`` pipe maps the ``eos`` output label of this module onto the
``lepton`` module's input.

Troubleshooting
---------------

**The module exits with status 400.**
   ``config.yaml`` failed validation against the OpenAPI schema — a field is
   missing or out of range (e.g. an unknown ``model_regime`` or grid type).
   Inspect ``/opt/output/status.yaml`` for the detailed message and re-validate
   locally with:

   .. code-block:: bash

      python3 src/validate_config.py --config_file_path input/

**The module exits with status 500.**
   An internal error occurred during the EOS computation.  This most often
   happens when a named ``parametrization`` is used outside its validated
   regime — for example ``SLy4`` with ``model_regime: relativistic`` becomes
   numerically unstable above roughly twice the saturation density.  Try
   ``model_regime: non-relativistic`` or a narrower ``nB_max``.

**The output EOS looks unphysical (negative** :math:`\mu_B` **,** :math:`c_s^2 > 1` **).**
   Same cause as above: the chosen parametrization / regime combination is not
   well-behaved across the full density grid.  Check ``status.yaml`` and reduce
   ``grid.nB_max`` or switch regime.

For questions, issues or bug reports, open an issue on the
`GitLab repository <https://gitlab.com/nsf-muses/metamodel/-/issues>`__ of the
module, post on the `MUSES Forum`_, or contact the lead developer:

- Mateus Reinke Pelicer (mateus.reinke@gmail.com)

.. _MUSES Forum: https://forum.musesframework.io/c/cyberinfrastructure/13