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

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

.. code-block:: yaml

   module: saturation_properties

Labels
------

Input
~~~~~

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

   * - Label
     - Description
     - Path (inside container)
   * - ``eos``
     - Tabulated nuclear equation of state (CSV)
     - ``/opt/input/eos.csv``

Output
~~~~~~

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

   * - Label
     - Description
     - Path (inside container)
   * - ``saturation_parameters``
     - Saturation properties (one row per temperature)
     - ``/opt/output/saturation.csv``

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

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

.. code-block:: yaml

   processes:
   - name: <<eos_process_name>>
     module: <<ce_eos_module>>
     config:
     {}
   -  name: saturation_properties
      module: saturation_properties
      config:
        global:
          method: fitting
        fitting:
          isoscalar_expansion_order: 4
          isovector_expansion_order: 4
     pipes:
       eos:
         label: eos_file
         module: <<ce_eos_module>>
         process: <<eos_process_name>>
   components:
   - type: chain
     name: workflow
     sequence:
     - <<eos_process_name>>
     - saturation_properties

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

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

**The output ``saturation.csv`` contains NaN for J and L.**
   The EoS grid may not extend beyond :math:`y_Q = 0.5`.  The module falls
   back to a backward stencil; if even that fails (all stencil points are
   out of range) J and L are set to NaN.  Check that the EoS covers
   :math:`y_Q \leq 0.5` with at least four grid points below 0.5.

**Q0, Z0, Ksym, Qsym, Zsym are NaN with** ``method: derivative``.
   These parameters require fourth-order derivatives, which the derivative
   method does not implement.  Use ``method: fitting`` to obtain all ten
   parameters.

**Configuration error: "GSL backend does not support third derivatives".**
   The ``gsl`` derivatives backend supports only first and second
   derivatives.  Either set ``isoscalar_expansion_order: 2`` or switch to
   ``derivatives_method: finite_difference``.

**The module exits with status 400.**
   A required field is missing or out of range.  Inspect
   ``/opt/output/status.yaml`` for the detailed message and re-validate your
   config with:

   .. code-block:: bash

      python3 src/validate_config.py --config_file_path input/

**Verbose / debug output.**
   Increase ``global.verbose`` in the config:

   - ``0`` — silent (default)
   - ``1`` — standard progress
   - ``2`` — detailed
   - ``3`` — debug

   Status code ``100`` entries in ``status.yaml`` are informational warnings
   (e.g. backward stencil activated, parameter out of allowed range).

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