Add matid capability to the sesame2spiner library

CHANGELOG.md

@@ -4,12 +4,21 @@
 
 ### 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
+- [[PR658]](https://github.com/lanl/singularity-eos/pull/XXX) Add `sesame2spiner::saveAllMaterials` overloads taking a list of matids instead of a list of input files, with optional per-material `Params` overrides, so host codes can generate an sp5 file without writing input decks to disk. Also added an overload taking an already-open `hid_t`, plus `writeSP5RootAttributes`, so a single sp5 file can be built up one material at a time.
+- [[PR653]] (https://github.com/lanl/singularity-eos/pull/659) Added `sesame2spiner::saveAllMaterials` overloads taking a list of matids instead of a list of input files, with optional per-material `Params` overrides, so host codes can generate an sp5 file without writing input decks to disk. Also added an overload taking an already-open `hid_t`, plus `writeSP5RootAttributes`, so a single sp5 file can be built up one material at a time.
 
 ### Fixed (Repair bugs, etc)
 - [[PR661]](https://github.com/lanl/singularity-eos/pull/661) Fix bug in InternalEnergyFromDensityPressure where the lambda wasn't threaded all the way through.
+- `sesame2spiner` now validates the metadata returned by `eosGetMetadata` before using it. A matid absent from the sesame file previously produced all-zero bounds with no error, which reached `log()` and generated NaN grids; it is now reported and skipped.
+- `sesame2spiner` no longer reports an HDF5 failure against every material following the first failed one, and now names the offending matid. Material save status is no longer accumulated by summing `herr_t` values, which could cancel out and report success.
+- [[PR653]] (https://github.com/lanl/singularity-eos/pull/659) `sesame2spiner` now validates the metadata returned by `eosGetMetadata` before using it. A matid absent from the sesame file previously produced 
+all-zero bounds with no error, which reached `log()` and generated NaN grids; it is now reported and skipped.  It also no longer reports an HDF5 failure against every material following the first failed one, 
+and now names the offending matid. Material save status is no longer accumulated by summing `herr_t` values, which could cancel out and report success.
 
 ### 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.
+- [[PR658]](https://github.com/lanl/singularity-eos/pull/XXX) `sesame2spiner` now honors the requested verbosity when reading material metadata, rather than always using `Verbosity::Debug`. Default command line output is correspondingly quieter.
+- [[PR658]](https://github.com/lanl/singularity-eos/pull/XXX) `sesame2spiner::getMatBounds` no longer takes a leading index argument, which was unused.
 
 ### 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

doc/sphinx/src/models.rst

@@ -2126,6 +2126,90 @@ Thus the input block for piecewise grid might look like this:
   on your desk would be at. This is called an *anchor* point for the
   mesh.
 
+Using sesame2spiner as a library
+``````````````````````````````````
+
+The conversion machinery is also available as a library,
+``sesame2spiner-lib`` (aliased ``sesame2spiner::sesame2spiner``), for host
+codes that want to generate an ``sp5`` file directly from a list of
+`sesame`_ material ids without writing input decks to disk first. The
+declarations live in ``<sesame2spiner/generate_files.hpp>``.
+
+To generate a file from a list of matids:
+
+.. code-block:: cpp
+
+  #include <sesame2spiner/generate_files.hpp>
+
+  using namespace sesame2spiner;
+  using EospacWrapper::Verbosity;
+
+  const std::vector<int> matids = {5030, 4272};
+
+  herr_t status = saveAllMaterials("materials.sp5", matids,
+                                   /*printMetadata=*/false, Verbosity::Quiet);
+
+This uses the same default grids the command line tool would use for an
+input deck that names only ``matid``. A material whose metadata cannot be
+read -- most commonly because the matid is not present in the `sesame`_
+file -- is reported on ``stderr`` and skipped; the remaining materials are
+still written and the return value is non-zero. The summary at the end of
+the call lists every matid that failed. Duplicate matids are likewise
+skipped with a warning, but do not count as failures, since the material is
+already present in the file.
+
+Every key accepted in an input deck can also be set programmatically on a
+``Params`` object, one per matid:
+
+.. code-block:: cpp
+
+  std::vector<Params> params(matids.size());
+  params[0].Set("name", "air");
+  params[0].Set("numrho/decade", "40");
+  params[1].Set("ionization", "true");
+
+  herr_t status = saveAllMaterials("materials.sp5", matids, params,
+                                   /*printMetadata=*/false, Verbosity::Quiet);
+
+To build a single file up incrementally -- for instance as a host code
+discovers which materials it needs -- open the file yourself and call the
+``hid_t`` overload once per material. Duplicate matid and name detection
+query the file rather than in-memory state, so this produces the same
+result as saving everything in one call:
+
+.. code-block:: cpp
+
+  hid_t file = H5Fcreate("materials.sp5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+  herr_t status = writeSP5RootAttributes(file);
+
+  for (int matid : matids) {
+    if (saveAllMaterials(file, {matid}, {Params{}},
+                         /*printMetadata=*/false, Verbosity::Quiet) != H5_SUCCESS) {
+      status = -1; // note which materials failed here if you need that detail
+    }
+  }
+
+  if (H5Fclose(file) != H5_SUCCESS) status = -1;
+
+``writeSP5RootAttributes`` records the ``singularity-eos`` version and the
+log type the file was generated with, and must be called once on a newly
+created file before any materials are added. To add materials to a file
+from a previous run, reopen it with ``H5Fopen(..., H5F_ACC_RDWR, ...)`` and
+skip ``writeSP5RootAttributes`` -- the attributes are already there.
+
+.. note::
+
+  Every call to the ``hid_t`` overload checks that the file's log type
+  matches the current build and refuses to proceed otherwise. Appending
+  materials to a file written with a different log type would produce a
+  file whose materials disagree with its own ``log_type`` attribute, which
+  the ``SpinerEOS`` constructors cannot detect.
+
+.. note::
+
+  The file must be closed for the resulting ``sp5`` to be valid, so a host
+  code that may exit early should ensure ``H5Fclose`` still runs.
+
 SAP Polynomial EOS
 ``````````````````