Configuration File
==================

The ``config.yaml`` file provides the configuration parameters for the Bulk Parameters module.
An example configuration file:

.. code-block:: yaml

  global:
    input_filename: eos.csv
    method: fitting
    nucleon_mass: 939.00
    nB_min_filter: 0.05
    verbose: 1
    run_name: ""
  derivatives:
    finite_difference:
      precision: 1
      step_size: 0.002
      step_type: relative
    method: gsl
  fitting:
    isoscalar_expansion_order: 4
    isovector_expansion_order: 4
    limit_fitting_range: true
    nB_range: 0.05
    yQ_range: 0.1
  allowed_ranges:
    n0min: 0.0
    n0max: 0.0
    BEmin: 0.0
    BEmax: 0.0

The full schema with all defaults is defined in ``api/OpenAPI_Specifications.yaml``.

Global Settings
---------------

- **input_filename**: *(string, default: "eos.csv")*

  Path to the EoS CSV file. Relative paths are resolved from the directory containing
  ``config.yaml``. **Do not change this if you are using the MUSES Calculation Engine**; the EoS file is automatically mounted to the container at ``/input/eos.csv``.

- **method**: *(string, default: "fitting")*

  Method to compute the bulk parameters. Options are ``fitting`` and ``derivative``.

- **nucleon_mass**: *(float, default: 939.00)*

  Nucleon mass in MeV, used to compute the binding energy per nucleon.

- **nB_min_filter**: *(float, default: 0.05)*

  Rows with baryon density below this threshold (fm\ :sup:`-3`) are excluded before the
  saturation search.  Near-vacuum rows cause spurious :math:`P \approx 0` zeros that
  can lead to false solutions for the saturation density in the root-finder.

- **verbose**: *(integer, default: 0)*

  Console output verbosity.

  - ``0`` — silent
  - ``1`` — standard: progress and final results
  - ``2`` — detailed: intermediate values
  - ``3`` — debug: full solver output

- **run_name**: *(string, default: "")*

  If non-empty, all output files are written to ``output/<run_name>/`` instead of
  ``output/``. **In the MUSES Calculation Engine, do not change this parameter.**

Derivatives Settings
--------------------

These parameters apply only when ``method: derivative``.

- **method**: *(string, default: "gsl")*

  Derivative backend. Options are ``gsl`` (GSL cubic spline) and ``finite_difference``.
  The GSL backend supports up to second-order derivatives; third-order derivatives (Q\ :sub:`0`)
  require ``finite_difference``.  Setting ``isoscalar_expansion_order >= 3`` with the
  ``gsl`` backend raises a configuration error at startup.

  .. note::

     ``isovector_expansion_order`` has no effect in derivative mode.  J and L are always
     computed (using a backward stencil when the yQ grid stops at 0.5);
     K\ :sub:`sym`, Q\ :sub:`sym`, and Z\ :sub:`sym` are always ``NaN``.

Finite Difference Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~

These parameters apply only when the derivatives ``method`` is ``finite_difference``.

- **step_type**: *(string, default: "relative")*

  How the step size is interpreted. ``relative`` sets :math:`h = \text{step\_size} \times x`;
  ``absolute`` sets :math:`h = \text{step\_size}`.

- **step_size**: *(float, default: 0.002)*

  Step size for the finite difference method.

- **precision**: *(integer, default: 1)*

  Order of the central finite difference stencil.

  - ``1`` — :math:`\mathcal{O}(h^2)`
  - ``2`` — :math:`\mathcal{O}(h^4)`

Fitting Settings
----------------

These parameters apply only when ``method: fitting``.

- **isoscalar_expansion_order**: *(integer, default: 3, range: 0–4)*

  Taylor expansion order for the isoscalar sector (BE, K\ :sub:`0`, Q\ :sub:`0`, Z\ :sub:`0`).
  Order *n* includes all terms through :math:`x^n` in the expansion.

- **isovector_expansion_order**: *(integer, default: 2, range: 0–4)*

  Taylor expansion order for the isovector sector (J, L, K\ :sub:`sym`, Q\ :sub:`sym`,
  Z\ :sub:`sym`).

- **limit_fitting_range**: *(boolean, default: false)*

  If ``true``, the fit uses only data within ``nB_range`` of :math:`n_0` and within
  ``yQ_range`` of :math:`y_Q = 0.5`.

- **nB_range**: *(float, default: 0.05)*

  Half-width of the density window around :math:`n_0` used when ``limit_fitting_range``
  is ``true`` (fm\ :sup:`-3`).

- **yQ_range**: *(float, default: 0.1)*

  Half-width of the charge-fraction window around :math:`y_Q = 0.5` used when
  ``limit_fitting_range`` is ``true``.

Allowed Ranges
--------------

These optional bounds validate the computed output parameters.  For each parameter, set
both min and max to ``0.0`` to disable the check.  If a computed value falls outside its
range (and neither bound is zero), the run exits with status code 101.

Available keys: ``n0min``, ``n0max``, ``BEmin``, ``BEmax``, ``K0min``, ``K0max``,
``Q0min``, ``Q0max``, ``Z0min``, ``Z0max``, ``Jmin``, ``Jmax``, ``Lmin``, ``Lmax``,
``Ksymmin``, ``Ksymmax``, ``Qsymmin``, ``Qsymmax``, ``Zsymmin``, ``Zsymmax``.