Make sieMin/sieMax pass through systemunits

CHANGELOG.md

@@ -3,15 +3,18 @@
 ## Current develop
 
 ### Added (new features/APIs/variables/...)
+- [[PR658]](https://github.com/lanl/singularity-eos/pull/XXX) Add `MinimumInternalEnergy`/`MaximumInternalEnergy` to the EOS introspection API, so energy bounds are reachable through modifiers and the `singularity::EOS` variant
 
 ### Fixed (Repair bugs, etc)
 
 ### Changed (changing behavior/API/variables/...)
+- [[PR658]](https://github.com/lanl/singularity-eos/pull/XXX) `ScaledEOS::CheckParams` now requires a strictly positive scale factor, where it previously accepted any nonzero value.
 
 ### Infrastructure (changes irrelevant to downstream codes)
 - [[PR653]](https://github.com/lanl/singularity-eos/pull/653) Move pybind11 to a submodule rather than fetching it via cmake fetchcontent
 
 ### Deprecated (soon to be removed behavior/API/variables/...)
+- [[PR658]](https://github.com/lanl/singularity-eos/pull/XXX) The table bounds accessors `sieMin()`/`sieMax()` on `SpinerEOSDependsRhoSie` and `StellarCollapse` are superseded by `MinimumInternalEnergy()`/`MaximumInternalEnergy()`, which every EOS provides and which work through modifiers and the `singularity::EOS` variant. The old names still work but will be removed.
 
 ## Release 1.12.1
 Date: 08/10/2026

doc/sphinx/src/models.rst

@@ -2277,6 +2277,16 @@ functions ``rhoMin()``, ``rhoMax()``, ``TMin()``, ``TMax()``,
 ``YeMin()``, ``YeMax()``, ``sieMin()``, and ``sieMax()``, which all
 return a ``Real`` number.
 
+.. note::
+
+  ``sieMin()`` and ``sieMax()`` are superseded by
+  ``MinimumInternalEnergy()`` and ``MaximumInternalEnergy()``, described
+  in the :ref:`EOS API section<using-eos>`. Prefer the latter: they are
+  part of the general EOS API, so unlike ``sieMin``/``sieMax`` they are
+  available on every model, are transformed correctly by modifiers, and
+  are reachable through the ``singularity::EOS`` variant. The old names
+  still work but will be removed in a future release.
+
 .. warning::
     As with the SpinerEOS models, the stellar collapse models use fast
     logs. You can switch the logs to true logs with the
@@ -2484,3 +2494,5 @@ See :ref:`EOSPAC Vector Functions <eospac_vector>` for more details.
 .. _EOSPAC: https://laws.lanl.gov/projects/data/eos/eospacReleases.php
 
 
+
+This file was made in part with generative AI.

doc/sphinx/src/modifiers.rst

@@ -121,6 +121,11 @@ where the first two parameters are the Gruneisen parameter and
 specific heat required by the ideal gas constructor and the latter is
 the scale.
 
+The scale factor must be strictly positive. A negative scale is not
+physically meaningful: it would invert the sign of energy and entropy,
+and would turn every minimum bound reported by the bounds introspection
+API into a maximum. ``CheckParams`` enforces this.
+
 The Relativistic EOS
 ---------------------
 
@@ -189,6 +194,33 @@ internal energy, and temperature. On the other hand,
 specifies the unit system by specifying units for time, mass, length,
 and temperature.
 
+All of the bounds introspection methods described in the :ref:`EOS API
+section<using-eos>`, including ``MinimumInternalEnergy`` and
+``MaximumInternalEnergy``, are converted to the new unit system. Because
+they are part of the general EOS API, they are also reachable through
+the ``singularity::EOS`` variant, so one no longer needs to call
+``GetUnmodifiedObject`` to retrieve energy bounds, which would return
+them in the unmodified (cgs) unit system:
+
+.. code-block:: cpp
+
+  using namespace singularity;
+  EOS my_eos = UnitSystem<SpinerEOSDependsRhoSie>(/* ... */);
+  // bounds in the new unit system
+  Real sie_min = my_eos.MinimumInternalEnergy();
+  Real sie_max = my_eos.MaximumInternalEnergy();
+
+See :ref:`How Modifiers Transform the Energy
+Bounds<modifier-energy-bounds>` below.
+
+.. note::
+
+  ``UnitSystem`` does *not* forward the model-specific table bounds
+  accessors ``sieMin()``/``sieMax()``. Those are not part of the general
+  EOS API, so they cannot be converted for an arbitrary underlying
+  model. Use ``MinimumInternalEnergy``/``MaximumInternalEnergy``
+  instead, which every model provides.
+
 Z-Split EOS
 -------------
 
@@ -373,3 +405,29 @@ Modifiers can also be undone, extracting the underlying EOS. Continuing the exam
    auto unmodified = my_eos.GetUnmodifiedObject();
 
 will extract the underlying ``IdealGas`` EOS model out from the scale and shift.
+
+.. _modifier-energy-bounds:
+
+How Modifiers Transform the Energy Bounds
+------------------------------------------
+
+Specific internal energy is transformed by several modifiers, so the
+energy bounds reported by ``MinimumInternalEnergy`` and
+``MaximumInternalEnergy`` (described in the :ref:`EOS API
+section<using-eos>`) are transformed to match:
+
+* ``UnitSystem`` divides both bounds by the energy unit.
+* ``ShiftedEOS`` adds the shift to both bounds.
+* ``ScaledEOS`` multiplies both bounds by the scale factor. Since the
+  scale factor is required to be positive, this preserves their ordering.
+* ``RelativisticEOS`` and ``BilinearRampEOS`` leave energy alone, so the
+  bounds pass through unchanged.
+* ``FlooredEnergy`` clamps energy to the per-density cold curve, which
+  lies inside the underlying energy range, so the global bounds pass
+  through unchanged.
+* ``ZSplit`` scales energy by a factor that depends on the ionization
+  state passed through the ``lambda``, but the bounds introspection API
+  takes no ``lambda``. The bounds it reports are therefore the
+  *un-split* bounds of the underlying EOS.
+
+This file was made in part with generative AI.

doc/sphinx/src/using-eos.rst

@@ -1504,14 +1504,35 @@ and the function
 .. cpp:function:: Real MaximumDensity() const;
 
 provide bounds for valid inputs into a table, which can be used by a
-root finder to meaningful bound the root search.
+root finder to meaningful bound the root search. The corresponding
+functions for specific internal energy are
+
+.. cpp:function:: Real MinimumInternalEnergy() const;
+
+and
+
+.. cpp:function:: Real MaximumInternalEnergy() const;
+
+For tabulated models these report the extent of the tabulated energies,
+which is the natural way to seed a root find or a bounds array in
+energy. Note that for a table in density and temperature, energy is a
+dependent variable, so these are the extrema of the tabulated energy
+field over the whole grid rather than the endpoints of an axis.
+
+.. note::
+
+  ``MinimumInternalEnergy`` is a property of the whole table. It is
+  *not* the same quantity as ``MinInternalEnergyFromDensity``, which is
+  the cold curve: the minimum energy at a *given* density.
 
 .. warning::
 
   For unbounded equations of state, ``MinimumDensity`` and
-  ``MinimumTemperature`` will return zero, while ``MaximumDensity``
-  will return a very large finite number. Which number you get,
-  however, is not guaranteed. You may wish to apply more sensible
+  ``MinimumTemperature`` will return zero, while ``MaximumDensity`` and
+  ``MaximumInternalEnergy`` will return very large finite numbers, and
+  ``MinimumInternalEnergy`` a very large negative one. (Energies are
+  legitimately negative, so zero is not a safe floor.) Which number you
+  get, however, is not guaranteed. You may wish to apply more sensible
   bounds in your own code.
 
 Similarly,