Quickstart
===========

The code can be built from source or run inside Docker; see :doc:`installation` for
setup instructions. It can also be used through the MUSES Calculation Engine — see
:doc:`ce_integration`.

Running the inverter
--------------------

.. code-block:: bash

   ./build/generate_eos_table path/to/config.yaml

If no config file is given, ``../input/config.yaml`` is used by default.

The executable:

1. Reads the input EoS table specified by ``input.path`` in the config.
2. Builds the output grid according to the ``grid`` section.
3. Inverts the EoS at each grid point using a Newton root-finder.
4. Falls back to analytic backup models for points outside the table domain.
5. Writes the result to the file and format specified by ``output``.

A typical run on a 250x250 grid finishes in under a minute on a 4-core laptop.

Expected output
---------------

By default the output is written to ``../output/eos_table.h5`` (HDF5) or
``../output/eos_table.csv`` (CSV), depending on ``output.format``.
Each row in the output corresponds to one grid point and contains:

- The inversion target coordinates echoed back (e.g. :math:`s`, :math:`n_B`).
- Temperature :math:`T` and chemical potentials :math:`\mu_B, \mu_S, \mu_Q`.
- Derived thermodynamic quantities: :math:`e, p, n_B, n_S, n_Q`, and optionally susceptibilities and :math:`c_s^2`.
- An integer ``eos_type`` column recording which EoS model produced the solution (see :doc:`output/eos`).

Points where the inversion failed are filled with ``NaN`` (or excluded entirely
if ``output.on_inversion_failure: exclude``).

Configuration
-------------

All behaviour — grid axes, units, backup models, solver tolerance — is
controlled through a single YAML file.
See :doc:`input/config` for a full reference of every available option.

Config Utilities
-----------------

**Validate** an existing config against the OpenAPI schema (fills missing fields with
defaults):

.. code-block:: bash

   python3 utilities/validate_config.py --config_file_path input/

By default this reads and overwrites ``input/config.yaml`` in place, filling any
omitted fields with their schema defaults from ``api/OpenAPI_Specifications.yaml``.
Pass ``--output_config_file_path`` to write the validated config elsewhere
instead. On an invalid config, the script writes a status code ``400`` to
``output/status.yaml`` and exits with a non-zero status.

This validation step also runs automatically before every inversion in the
Docker image (and therefore in the MUSES Calculation Engine): the container's
command first runs ``validate_config.py`` and only proceeds to
``generate_eos_table`` if the config is valid — see :doc:`ce_integration`.