.. _ce_integration:

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

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

.. code-block:: yaml

   module: synthesis

Labels
------

Input
~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 50 25

   * - Label
     - Description
     - Path (inside container)
   * - ``config``
     - Configuration of the module runtime options
     - ``/opt/input/config.yaml``
   * - ``model1_BetaEq_eos``
     - Beta-equilibrated 1D EoS for the first model (required)
     - ``/opt/input/eos_beta_model1.csv``
   * - ``model2_BetaEq_eos``
     - Beta-equilibrated 1D EoS for the second model (required)
     - ``/opt/input/eos_beta_model2.csv``
   * - ``model1_Grid_eos``
     - 2D grid EoS for the first model, needed for the Gibbs construction
     - ``/opt/input/eos_grid_model1.csv``
   * - ``model2_Grid_eos``
     - 2D grid EoS for the second model, needed for the Gibbs construction
     - ``/opt/input/eos_grid_model2.csv``
   * - ``lepton_eos``
     - 2D grid leptonic EoS, needed for the Gibbs construction
     - ``/opt/input/lepton_eos.csv``
   * - ``model1_BetaEq_particle_properties`` / ``model2_BetaEq_particle_properties``
     - Beta-equilibrated particle properties associated with each model's EoS
     - ``/opt/input/particle_properties_beta_model{1,2}.csv``
   * - ``model1_Grid_particle_properties`` / ``model2_Grid_particle_properties``
     - Grid particle properties associated with each model's EoS
     - ``/opt/input/particle_properties_grid_model{1,2}.csv``
   * - ``lepton_particle_properties``
     - Grid particle properties for the leptonic EoS
     - ``/opt/input/lepton_particle_properties.csv``

The Grid EoS/particle-properties and lepton labels are only required for
``synthesis_type: gibbs``; the Maxwell, tanh-interpolation, and attach methods only need
the two beta-equilibrated EoS files. See :doc:`input/index` for the full description of each
file's format.

Output
~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 50 25

   * - Label
     - Description
     - Path (inside container)
   * - ``status``
     - Module execution status
     - ``/opt/output/status.yaml``
   * - ``eos``
     - Joined 1D equation of state
     - ``/opt/output/eos.csv``
   * - ``particle_properties``
     - Joined 1D particle properties
     - ``/opt/output/particle_properties.csv``

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

The snippet below feeds the EoS output of two generic upstream modules into a single
``synthesis_run`` step configured for ``synthesis_type: statistical_mixture``.

.. code-block:: yaml

   processes:
   - name: mod_1
     module: <<module_1>>
     config:
       {}
   - name: mod_2
     module: <<module_2>>
     config:
       {} 
   - name: synthesis_run
     module: synthesis
     config:
       global:
         synthesis_type: statistical_mixture
         verbose: 1
       output:
         output_particle_properties: true
     pipes:
       model1_BetaEq_eos:
         label: <<mod_1_eos>>
         module: <<module_1>>
         process: mod_1
       model2_BetaEq_eos:
         label: <<mod_2_eos>>
         module: <<module_2>>
         process: mod_2
   components:
   - type: chain
     name: workflow
     sequence:
     - mod_1
     - mod_2
     - synthesis_run

The ``synthesis_run`` step pipes the ``eos`` output label of ``mod_1`` and ``mod_2``
into its own input labels, then runs after both in the chain.

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

**The module exits with a non-zero status code.**
   Inspect ``/opt/output/status.yaml`` for the code and message. Codes below 100 map to
   distinct error conditions raised throughout the module (invalid config, unstable or
   acausal EoS, failed root-finding in the phase transition, etc.); the message describes
   which check failed.

**Configuration validation fails before the module runs.**
   Validate and auto-fill defaults locally with:

   .. code-block:: bash

      python3 src/validate_config.py

   This is the same ``openapi-core``-based check the module performs internally against
   the `OpenAPI Specification <https://gitlab.com/nsf-muses/module-cmf/eos-synthesis/-/blob/main/api/OpenAPI_Specifications_synthesis.yaml?ref_type=heads>`_.

**I'm not sure which EoS files are required for my chosen method.**
   ``maxwell``, ``interpolation``, and ``attach`` only need the two beta-equilibrated EoS
   files. ``gibbs`` additionally needs both models' 2D grid EoS/particle-properties files
   and the leptonic EoS. ``statistical_mixture`` needs only the two models' 2D grid EoS
   files (a temperature-muB grid, not the muB-muQ grid used by ``gibbs``) and does not
   use the beta-equilibrated or leptonic EoS at all — see the Labels tables above and
   :doc:`input/eos` for the grid conventions.

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

   - ``0`` — silent
   - ``1`` — standard progress
   - ``2`` — detailed (e.g. per-iteration Gibbs construction and attach diagnostics)

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