.. _quickstart:

Quick Start
===========

This example generates a zero-temperature nucleonic equation of state (EOS)
from a set of bulk saturation parameters.

1. Edit ``input/config.yaml`` to choose the model regime, the bulk properties
   (or a named parametrization) and the output grid:

   .. code-block:: yaml

      model_regime: non-relativistic     # or "relativistic"
      bulk_properties:
        parametrization: ''              # or SLy4, SLy4_bar, RATP, SKI4, NL3
        BE:    -15.97                    # MeV
        n0:     0.1595                   # fm^-3
        K0:     230.0                    # MeV
        Q0:    -225.0                    # MeV
        Z0:    -443.0                    # MeV
        Esym:   32.01                    # MeV
        Lsym:   46.0                     # MeV
        Ksym:  -120.0                    # MeV
        Qsym:   350.0                    # MeV
        Zsym:  -690.0                    # MeV
        meff_norm:      0.89
        meff_splitting: 0.0              # MeV
        b0:     6.9
        bsym:   0.0
      grid:
        nB_grid: linear                  # or "log"
        nB_min:  0.05                    # fm^-3
        nB_max:  0.8                     # fm^-3
        nB_points: 25
        delta_grid: linear               # or "log"
        delta_min: 0.0
        delta_max: 1.0
        delta_points: 10

   To use a tabulated parametrization instead of the explicit values, set
   ``bulk_properties.parametrization`` to one of ``SLy4``, ``SLy4_bar``,
   ``RATP``, ``SKI4`` or ``NL3``; the remaining ``bulk_properties`` fields are
   then ignored.  See :doc:`config` for the full field reference.

2. Run from ``src/``:

   .. code-block:: bash

      cd src
      python3 validate_config.py && python3 interface.py

   ``validate_config.py`` checks ``input/config.yaml`` against the OpenAPI
   schema and rewrites it with any missing fields filled in from their
   defaults.  ``interface.py`` then computes the EOS.

3. Results are written to the ``output/`` directory:

   - ``output/eos.csv`` — the tabulated EOS, one row per grid point and no
     header row.  See :doc:`output_eos` for the column layout.
   - ``output/status.yaml`` — an integer status ``code`` and a ``message``
     (``200`` on success, ``400`` for a bad config, ``500`` for a runtime
     error).

.. note::

   Running locally requires the ``libnseos.so`` shared library.  Build it once
   with ``bash install.sh`` from the repository root (needs ``gfortran`` and
   ``make``) before the first run.  See :ref:`installation` for details.

Running with Docker
-------------------

The bundled ``run_docker.sh`` builds the image and runs the same two-step
pipeline, mounting the local ``input/`` and ``output/`` directories:

.. code-block:: bash

   ./run_docker.sh

Equivalently:

.. code-block:: bash

   docker build -t metamodel:latest .
   docker run --rm -it \
       -v "$(pwd)/input:/opt/input" \
       -v "$(pwd)/output:/opt/output" \
       metamodel:latest \
       bash -c "python3 validate_config.py && python3 interface.py"

Config Validation
-----------------

To validate (and normalise) a config without running the model, run from
``src/``:

.. code-block:: bash

   python3 validate_config.py --config_file_path ../input/

Missing fields are filled with their default values and the file is written
back in place.  On failure the script writes ``output/status.yaml`` with code
``400`` and a message naming the offending field.