Bulk Parameters
===============

The Bulk Parameters module computes saturation properties of nuclear matter from a tabulated
equation of state (EoS) in :math:`(n_B, y_Q)` space, where :math:`n_B` is the baryon number
density and :math:`y_Q = n_Q / n_B` is the charge fraction.
The EoS is provided as a CSV file over a grid of temperatures.


The module locates the saturation point (where the pressure vanishes in symmetric nuclear matter, :math:`y_Q = 0.5`) and extracts the following bulk parameters at that point:

- Saturation density :math:`n_0` (fm\ :sup:`-3`)
- Binding energy :math:`\text{BE}` (MeV)
- Incompressibility :math:`K_0` (MeV)
- Skewness :math:`Q_0` (MeV)
- Kurtosis :math:`Z_0` (MeV)
- Symmetry energy :math:`J` (MeV)
- Slope of the symmetry energy :math:`L` (MeV)
- Curvature of the symmetry energy :math:`K_\text{sym}` (MeV)
- Skewness of the symmetry energy :math:`Q_\text{sym}` (MeV)
- Kurtosis of the symmetry energy :math:`Z_\text{sym}` (MeV)

These parameters arise from the Taylor expansion of the energy per baryon around the
saturation point:

.. math::

   E(n_B,\, y_Q) = \text{BE} + \frac{K_0}{2} x^2 + \frac{Q_0}{6} x^3 + \frac{Z_0}{24} x^4
   + \left( J + L\, x + \frac{K_\text{sym}}{2} x^2 + \frac{Q_\text{sym}}{6} x^3
   + \frac{Z_\text{sym}}{24} x^4 \right) \delta^2
   + \mathcal{O}(x^5,\, \delta^4)

where :math:`x = (n_B - n_0)/(3\, n_0)` and :math:`\delta = 1 - 2 y_Q`.

Two computation methods are available:

**Fitting** (``method: fitting``)
   Non-linear least-squares fit of the full dataset to the Taylor expansion above using the
   Ceres solver with AutoDiff.  All ten parameters are extracted simultaneously.

**Derivative** (``method: derivative``)
   Numerical derivatives of the energy per baryon at :math:`n_0`.
   The parameters computed depend on the backend:

   - ``derivatives.method: gsl`` — GSL cubic spline; supports first and second derivatives
     only (n\ :sub:`0`, BE, K\ :sub:`0`, J, L).  Setting ``isoscalar_expansion_order >= 3``
     with this backend raises a configuration error.
   - ``derivatives.method: finite_difference`` — central finite-difference stencils;
     supports up to third-order derivatives (adds Q\ :sub:`0`).

   **Symmetry energy when yQ grid stops at 0.5:** if the EoS grid does not extend beyond
   :math: `y_Q = 0.5`, the module automatically falls back to a 2nd-order one-sided (backward) stencil using
   the :math: `y_Q` grid spacing as the step size so that the evaluation points land on or between
   grid nodes.  J and L remain finite but are less accurate than with a full central stencil.

   Z\ :sub:`0`, K\ :sub:`sym`, Q\ :sub:`sym`, and Z\ :sub:`sym` require fourth-order
   derivatives and are **not computable** via the derivative method regardless of backend;
   their output columns are set to ``NaN``.


This is available within the `MUSES Calculation Engine <http://ce.musesframework.io/>`_. See the :ref:`quickstart` for a minimal example of how to use the module.

To use it locally, see the :ref:`installation` instructions.

.. toctree::
   :maxdepth: 2
   :caption: Contents

   _contents/input/index
   _contents/output/eos
   _contents/quickstart
   _contents/installation
   _contents/ce_integration