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

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

.. code-block:: yaml

   module: eos_inverter

Labels
------

Input
~~~~~

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

   * - Label
     - Description
     - Path (inside container)
   * - ``config``
     - Configuration of the module runtime options
     - ``/opt/input/config.yaml``
   * - ``eos_csv``
     - Equation of state data to be inverted, in CSV format
     - ``/opt/eos/thermo.csv``
   * - ``eos_hdf5``
     - Equation of state data to be inverted, in HDF5 format
     - ``/opt/eos/thermo.h5``
   * - ``eos_dat``
     - Equation of state data to be inverted, in ``.dat`` format
     - ``/opt/eos/thermo.dat``

Only one of ``eos_csv``, ``eos_hdf5``, or ``eos_dat`` is required, matching
``input.format`` in the config.

.. note::
   The paths above reflect the fixed mount points used by the MUSES Calculation Engine. When running the module manually (see :doc:`installation`), ``input.path`` in the config may instead point directly to any EoS table file path relative to ``/opt``.

Output
~~~~~~

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

   * - Label
     - Description
     - Path (inside container)
   * - ``status``
     - Module execution status
     - ``/opt/output/status.yaml``
   * - ``inverted_eos_csv``
     - Inverted equation of state data, in CSV format
     - ``/opt/output/inverted_eos.csv``
   * - ``inverted_eos_hdf5``
     - Inverted equation of state data, in HDF5 format
     - ``/opt/output/inverted_eos.h5``

Only one of ``inverted_eos_csv`` or ``inverted_eos_hdf5`` is produced, matching
``output.format`` in the config.

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

The snippet below shows a typical CE workflow that pipes the output of an
``eos_module`` into the ``eos_inverter`` module:

.. code-block:: yaml

   processes:
   - name: <<eos_process_name>>
     module: <<ce_eos_module>>
     config:
     {}
   - name: eos_inverter
     module: eos_inverter
     config:
       input:
         format: hdf5
       grid:
         mode: explicit
         output_grid: [s, nB, nS, nQ]
     pipes:
       eos_hdf5:
         label: eos_file
         module: <<ce_eos_module>>
         process: <<eos_process_name>>
   components:
   - type: chain
     name: workflow
     sequence:
     - <<eos_process_name>>
     - eos_inverter

The ``eos_hdf5`` pipe maps the upstream ``eos_file`` output label of the
``<<ce_eos_module>>`` to the ``eos_hdf5`` input label of this module.

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

**The module exits with status 500.**
   ``status.yaml`` contains a code of ``500`` for any failure — a bad config file,
   an invalid grid definition, an EoS table that cannot be read, or an unrecoverable
   error during inversion. Inspect the ``message`` field in
   ``/opt/output/status.yaml`` and the console/log output for the underlying
   exception.

**Many grid points are filled with NaN (``eos_type = -1``).**
   The root-finder failed to converge at those points, and either the ``backup_eos``
   models were disabled or none of them converged either. Enable
   ``backup_eos.enabled: true`` and check that the requested output-grid range is
   physically reachable. If ``output.on_inversion_failure: exclude`` is set, failed
   points are dropped from the output entirely instead of being written as NaN.

**Solutions near the table boundary look unphysical.**
   Enable ``output.enforce_output_envelope: true`` so that stable-phase table
   solutions whose output-space coordinates fall outside the envelope of the raw
   table are rejected in favor of a backup EoS. See :doc:`input/config` for the
   related ``envelope_bandwidth`` parameter.

**Causality or stability filters reject too many solutions.**
   ``output.prohibit_acausal_cs2`` and ``output.restrict_mu_T_ratios`` discard
   otherwise-converged solutions that fail :math:`0 \leq c_s^2 \leq 1` or
   :math:`|\mu_i|/T < 3.5`. Disabling these checks keeps more points but no longer
   guarantees physicality of the returned state.

**Configuration error: "signed log grids crossing zero require an odd number of points".**
   A ``grid`` axis with ``scale: log`` whose range spans negative and non-negative
   values (e.g. ``min: -1.0, max: 1.0``) must use an odd ``points`` count so the
   grid can place a point at the ``inner`` cutoff on each side of zero.

For questions, issues or bug reports, open an issue on the
`GitLab repository <https://gitlab.com/nsf-muses/eos-inverter/-/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