Merge branch 'main' into buechler/spiner_constructor

Author: Yurlungur

.github/PULL_REQUEST_TEMPLATE.md

@@ -19,6 +19,8 @@ detail.  Why is this change required?  What problem does it solve?-->
 - [ ] Make sure the copyright notice on any files you modified is up to date.
 - [ ] After creating a pull request, note it in the CHANGELOG.md file.
 - [ ] LANL employees: make sure tests pass both on the github CI and on the Darwin CI
+- [ ] If ML was used, make sure to add a disclaimer at the top of a file indicating ML was used to assist in generating the file.
+- [ ] If Agentic AI was used, have the AI generate a "proposed changes" markdown file and store it in the `plan_histories` folder, with a filename the same as the MR number.
 
 If preparing for a new release, in addition please check the following:
 - [ ] Update the version in cmake.

.gitignore

@@ -1,4 +1,5 @@
 bin
+.codex
 .spack*
 spack.lock
 utils/variant
@@ -14,3 +15,5 @@ CMakeUserPresets.json
 build/
 goldfiles.tar.gz
 .aider*
+CMakeCache.txt
+CMakeFiles

CHANGELOG.md

@@ -11,6 +11,7 @@
 ### Changed (changing behavior/API/variables/...)
 
 ### Infrastructure (changes irrelevant to downstream codes)
+- [[PR629]](https://github.com/lanl/singularity-eos/pull/629) Use macros and eos_base and eos_variant to reduce boiler plate
 - [[PR626]](https://github.com/lanl/singularity-eos/pull/626) Fix C++20 warnings related to lambdas
 
 ## Release 1.11.1

doc/sphinx/src/contributing.rst

@@ -46,6 +46,33 @@ internal tests will not be run automatically. So when the code is
 ready for merge, you must ask a project maintainer to trigger the
 remaining tests for you.
 
+AI-assisted coding
+-------------------
+
+``singularity-eos`` requires that if AI was used to assist in code
+generation, a disclaimer must be made in a comment in the relevant
+file. Also if agentic AI was used, please have your agent dump a
+"proposed plan" markdown file in the ``plan_histories`` folder. This
+provides an LLM-readable history of machine-generated changes and
+helps disentangle human-made choices from machine-made ones. For
+example, if you used codex or claude code, use a workflow like this
+one:
+
+1. Ask the agentic framework to propose a plan targeting your problem.
+2. Tell it to dump the plan into a new file in ``plan_histories``
+3. Iterate until you're happy with the code and submit an MR.
+4. After submitting the MR, rename the new file to be prefixed by the MR number and commit it.
+
+If you submit code to ``singularity-eos`` you own that code and you are
+responsible for understanding it. If code is submitted that the author
+does not understand, the author will be asked to resubmit a changeset
+that they understand.
+
+Finally, please be cognizant of reviewer time and effort. Agentic AI
+can create changesets much faster than a human can review them. When
+possible, please break up large changes and refactors into
+human-parse-able chunks.
+
 Expectations for code review
 -----------------------------
 

plan_histories/MR629-2026-04-06-eos-base-macro-plan.md

@@ -0,0 +1,125 @@
+# Plan: Reduce `EosBase` Vector Wrapper Boilerplate with Macros
+
+## Goal
+
+Reduce duplication in `singularity-eos/eos/eos_base.hpp` for the CRTP-based vector API wrappers that call `portableFor`, without fundamentally changing the public API or overload set.
+
+## Scope
+
+Target the repeated vector wrapper patterns in `EosBase<CRTP>`:
+
+- one-input / one-output wrappers
+- two-input / one-output wrappers
+- wrappers with a `scratch` forwarding overload
+- wrappers with a raw-pointer forwarding overload
+- the special vector wrapper that forwards to a scalar method with an output reference
+
+Leave non-matching methods handwritten if the macro would become harder to read than the original code.
+
+## Proposed Macro Shapes
+
+### 1. `SG_EOS_VEC_2IN_1OUT`
+
+Use for methods shaped like:
+
+```cpp
+out[i] = copy.Method(in1[i], in2[i], lambdas[i]);
+```
+
+Examples:
+
+- `TemperatureFromDensityInternalEnergy`
+- `InternalEnergyFromDensityTemperature`
+- `PressureFromDensityTemperature`
+- `PressureFromDensityInternalEnergy`
+- `EntropyFromDensityTemperature`
+- `EntropyFromDensityInternalEnergy`
+- `SpecificHeatFromDensityTemperature`
+- `SpecificHeatFromDensityInternalEnergy`
+- `BulkModulusFromDensityTemperature`
+- `BulkModulusFromDensityInternalEnergy`
+- `GruneisenParamFromDensityTemperature`
+- `GruneisenParamFromDensityInternalEnergy`
+- `GibbsFreeEnergyFromDensityTemperature`
+- `GibbsFreeEnergyFromDensityInternalEnergy`
+
+Suggested parameters:
+
+- method name
+- first indexed input variable name
+- second indexed input variable name
+- output variable name
+- copy declaration kind: `const CRTP &` or `CRTP`
+
+### 2. `SG_EOS_VEC_1IN_1OUT`
+
+Use for methods shaped like:
+
+```cpp
+out[i] = copy.Method(in1[i], lambdas[i]);
+```
+
+Primary example:
+
+- `MinInternalEnergyFromDensity`
+
+Suggested parameters:
+
+- method name
+- indexed input variable name
+- output variable name
+- copy declaration kind
+
+### 3. `SG_EOS_VEC_2IN_REFOUT`
+
+Use for methods shaped like:
+
+```cpp
+copy.Method(in1[i], in2[i], out[i], lambdas[i]);
+```
+
+Primary example:
+
+- `InternalEnergyFromDensityPressure`
+
+Suggested parameters:
+
+- method name
+- first indexed input variable name
+- second indexed input variable name
+- output variable name
+- copy declaration kind
+
+## Important Constraints
+
+- Preserve the current overload names and signatures.
+- Preserve the `scratch` overload behavior.
+- Preserve the raw-pointer overload behavior with `Transform && = Transform()`.
+- Preserve current `copy` semantics:
+  some methods use `const CRTP &copy`, while others use `CRTP copy`.
+- Keep `FillEos` handwritten unless a separate dedicated macro remains clearly readable.
+
+## Suggested Implementation Order
+
+1. Add the helper macros near the other EOS helper macros at the top of `eos_base.hpp`.
+2. Replace the repetitive vector wrapper bodies with macro invocations.
+3. Keep `FillEos` and any non-conforming methods handwritten.
+4. Build and run the existing test suite that covers EOS vector calls.
+5. Check compiler diagnostics carefully, since macro errors can be noisy in templated code.
+
+## Expected Benefits
+
+- substantially less boilerplate in `EosBase`
+- easier addition of new vector wrapper methods
+- lower risk of copy-paste inconsistencies between overloads
+- no fundamental change to the API seen by derived EOS classes
+
+## Main Risks
+
+- macro-generated template errors may be harder to read
+- overly generic macros can become less maintainable than the duplicated code
+- accidental mismatch between current `const CRTP &copy` and `CRTP copy` behavior
+
+## Recommendation
+
+Proceed with a small macro family rather than one fully generic macro. Three focused macros should remove most duplication while keeping the generated code readable and close to the current implementation.

plan_histories/MR629-2026-04-06-eos-variant-macro-strategy.md

@@ -0,0 +1,103 @@
+# Plan: Reduce `Variant` Boilerplate in `eos_variant.hpp`
+
+## Goal
+
+Reduce duplication in `singularity-eos/eos/eos_variant.hpp` by introducing a small set of helper macros for the repeated `PortsOfCall::visit(...)` wrappers, without changing the public API of `Variant`.
+
+## Summary
+
+A macro-based cleanup should work well in `eos_variant.hpp`.
+
+The vector section is especially repetitive and appears to be a better fit for macros than the already-refactored `EosBase` vector wrappers. Most methods repeat the same four-overload bundle:
+
+1. a no-lambda overload that constructs `NullIndexer`
+2. a lambda-taking overload that dispatches through `PortsOfCall::visit`
+3. a `scratch` + no-lambda overload that constructs `NullIndexer`
+4. a `scratch` + lambda-taking overload that dispatches through `PortsOfCall::visit`
+
+## Recommended Macro Families
+
+### 1. Vector wrappers
+
+Use a small family of macros for the repeated vector forwarding patterns:
+
+- `SG_VARIANT_VEC_2IN_1OUT(NAME, IN1, IN2, OUT)`
+- `SG_VARIANT_VEC_1IN_1OUT(NAME, IN1, OUT)`
+- `SG_VARIANT_VEC_2IN_REFOUT(NAME, IN1, IN2, OUT)`
+
+These would cover the methods that forward to the same method on the active EOS in the variant.
+
+### 2. Optional scalar wrappers
+
+If further cleanup is desired, a second macro family could reduce the scalar `PortsOfCall::visit(...)` wrappers:
+
+- `SG_VARIANT_SCALAR_2IN_1OUT(NAME, A1, A2)`
+- `SG_VARIANT_SCALAR_1IN_1OUT(NAME, A1)`
+- `SG_VARIANT_SCALAR_2IN_REFOUT(NAME, A1, A2, OUT)`
+
+This scalar cleanup is optional. The highest-value, lowest-risk target is the vector section.
+
+## Best Targets For Vector Macros
+
+These methods appear to fit the macro pattern well:
+
+- `TemperatureFromDensityInternalEnergy`
+- `InternalEnergyFromDensityTemperature`
+- `PressureFromDensityTemperature`
+- `PressureFromDensityInternalEnergy`
+- `MinInternalEnergyFromDensity`
+- `EntropyFromDensityTemperature`
+- `EntropyFromDensityInternalEnergy`
+- `GibbsFreeEnergyFromDensityTemperature`
+- `GibbsFreeEnergyFromDensityInternalEnergy`
+- `SpecificHeatFromDensityTemperature`
+- `SpecificHeatFromDensityInternalEnergy`
+- `BulkModulusFromDensityTemperature`
+- `BulkModulusFromDensityInternalEnergy`
+- `GruneisenParamFromDensityTemperature`
+- `GruneisenParamFromDensityInternalEnergy`
+- `InternalEnergyFromDensityPressure`
+
+## Methods To Leave Handwritten
+
+These are less regular and should likely remain explicit:
+
+- `FillEos`
+- `ReferenceDensityTemperature`
+- `ValuesAtReferenceState`
+- `DensityEnergyFromPressureTemperature`
+- various introspection helpers
+- serialization helpers
+
+## Suggested Shape
+
+The vector section could collapse to a short list of macro invocations such as:
+
+```cpp
+SG_VARIANT_VEC_2IN_1OUT(TemperatureFromDensityInternalEnergy, rhos, sies, temperatures)
+SG_VARIANT_VEC_2IN_1OUT(InternalEnergyFromDensityTemperature, rhos, temperatures, sies)
+SG_VARIANT_VEC_2IN_1OUT(PressureFromDensityTemperature, rhos, temperatures, pressures)
+SG_VARIANT_VEC_2IN_1OUT(PressureFromDensityInternalEnergy, rhos, sies, pressures)
+SG_VARIANT_VEC_1IN_1OUT(MinInternalEnergyFromDensity, rhos, sies)
+SG_VARIANT_VEC_2IN_1OUT(EntropyFromDensityTemperature, rhos, temperatures, entropies)
+SG_VARIANT_VEC_2IN_1OUT(EntropyFromDensityInternalEnergy, rhos, sies, entropies)
+SG_VARIANT_VEC_2IN_1OUT(GibbsFreeEnergyFromDensityTemperature, rhos, temperatures, Gs)
+SG_VARIANT_VEC_2IN_1OUT(GibbsFreeEnergyFromDensityInternalEnergy, rhos, sies, Gs)
+SG_VARIANT_VEC_2IN_1OUT(SpecificHeatFromDensityTemperature, rhos, temperatures, cvs)
+SG_VARIANT_VEC_2IN_1OUT(SpecificHeatFromDensityInternalEnergy, rhos, sies, cvs)
+SG_VARIANT_VEC_2IN_1OUT(BulkModulusFromDensityTemperature, rhos, temperatures, bmods)
+SG_VARIANT_VEC_2IN_1OUT(BulkModulusFromDensityInternalEnergy, rhos, sies, bmods)
+SG_VARIANT_VEC_2IN_1OUT(GruneisenParamFromDensityTemperature, rhos, temperatures, gm1s)
+SG_VARIANT_VEC_2IN_1OUT(GruneisenParamFromDensityInternalEnergy, rhos, sies, gm1s)
+SG_VARIANT_VEC_2IN_REFOUT(InternalEnergyFromDensityPressure, rhos, Ps, sies)
+```
+
+## Important Constraint
+
+The macros in `eos_variant.hpp` will be slightly more delicate than those in `eos_base.hpp`, because they use perfect forwarding through `PortsOfCall::visit` lambdas. That is still manageable, but it argues for a small, focused macro family rather than an overly generic one.
+
+## Recommendation
+
+Proceed with the vector macro refactor first.
+
+It offers the best reduction in boilerplate with limited risk and preserves the existing overload set. If the result reads well, consider a second pass for the scalar `visit(...)` wrappers.

plan_histories/MR629-2026-04-07-eospac-vector-wrapper-macro-plan.md

@@ -0,0 +1,72 @@
+# MR629 EOSPAC Vector Wrapper Macro Plan
+
+## Goal
+
+Reduce the boilerplate in `singularity-eos/eos/eos_eospac.hpp` for the repeated EOSPAC vector wrapper declarations that forward `2-in/1-out` calls through `EosBase<EOSPAC>`.
+
+## Scope
+
+Only target the repeated wrapper pattern with:
+
+- two indexed real inputs
+- one indexed real output
+- the no-scratch overload
+- the scratch overload used for type-mismatch fallback
+
+Do not introduce a macro for the warning strings themselves. Keep both warnings written verbatim inside the wrapper macro body.
+
+Do not add a `1-in/1-out` macro. `MinInternalEnergyFromDensity` stays as-is.
+
+Do not touch the specialized pointer-based EOSPAC vector implementations, `FillEos`, `DensityEnergyFromPressureTemperature`, or `ValuesAtReferenceState`.
+
+## Proposed Macro
+
+Add one EOSPAC-local macro near the vector wrapper declarations:
+
+```cpp
+#define SG_EOSPAC_VEC_2IN_1OUT(NAME, IN1, IN2, OUT)                                      \
+  template <typename RealIndexer, typename ConstRealIndexer, typename LambdaIndexer>     \
+  inline void NAME(ConstRealIndexer &&IN1, ConstRealIndexer &&IN2, RealIndexer &&OUT,    \
+                   const int num, LambdaIndexer &&lambdas) const {                       \
+    PORTABLE_WARN("Not providing scratch memory will trigger scalar EOSPAC lookups");    \
+    EosBase<EOSPAC>::NAME(std::forward<ConstRealIndexer>(IN1),                           \
+                          std::forward<ConstRealIndexer>(IN2),                           \
+                          std::forward<RealIndexer>(OUT), num,                           \
+                          std::forward<LambdaIndexer>(lambdas));                         \
+  }                                                                                      \
+  template <typename RealIndexer, typename ConstRealIndexer, typename LambdaIndexer,     \
+            typename = std::enable_if_t<!is_raw_pointer<RealIndexer, Real>::value>>      \
+  inline void NAME(ConstRealIndexer &&IN1, ConstRealIndexer &&IN2, RealIndexer &&OUT,    \
+                   Real * /*scratch*/, const int num, LambdaIndexer &&lambdas) const {   \
+    PORTABLE_WARN("EOSPAC type mismatch will cause significant performance degradation"); \
+    EosBase<EOSPAC>::NAME(std::forward<ConstRealIndexer>(IN1),                           \
+                          std::forward<ConstRealIndexer>(IN2),                           \
+                          std::forward<RealIndexer>(OUT), num,                           \
+                          std::forward<LambdaIndexer>(lambdas));                         \
+  }
+```
+
+## Planned Replacements
+
+Use the macro for these wrapper declarations:
+
+```cpp
+SG_EOSPAC_VEC_2IN_1OUT(TemperatureFromDensityInternalEnergy, rhos, sies, temperatures)
+SG_EOSPAC_VEC_2IN_1OUT(InternalEnergyFromDensityTemperature, rhos, temperatures, sies)
+SG_EOSPAC_VEC_2IN_1OUT(PressureFromDensityTemperature, rhos, temperatures, pressures)
+SG_EOSPAC_VEC_2IN_1OUT(PressureFromDensityInternalEnergy, rhos, sies, pressures)
+SG_EOSPAC_VEC_2IN_1OUT(EntropyFromDensityTemperature, rhos, temperatures, entropies)
+SG_EOSPAC_VEC_2IN_1OUT(EntropyFromDensityInternalEnergy, rhos, sies, entropies)
+SG_EOSPAC_VEC_2IN_1OUT(SpecificHeatFromDensityTemperature, rhos, temperatures, cvs)
+SG_EOSPAC_VEC_2IN_1OUT(SpecificHeatFromDensityInternalEnergy, rhos, sies, cvs)
+SG_EOSPAC_VEC_2IN_1OUT(BulkModulusFromDensityTemperature, rhos, temperatures, bmods)
+SG_EOSPAC_VEC_2IN_1OUT(BulkModulusFromDensityInternalEnergy, rhos, sies, bmods)
+SG_EOSPAC_VEC_2IN_1OUT(GruneisenParamFromDensityTemperature, rhos, temperatures, gm1s)
+SG_EOSPAC_VEC_2IN_1OUT(GruneisenParamFromDensityInternalEnergy, rhos, sies, gm1s)
+```
+
+## Rationale
+
+This follows the same general style as the vector API boilerplate macros in `singularity-eos/eos/eos_base.hpp`, but keeps the implementation local to EOSPAC because the warning behavior is EOSPAC-specific.
+
+The result should remove most of the duplicated declarations without obscuring the actual fallback behavior.