DAE constraint restructure to full mass-matrix row replacement

[davidfillmore]

Constraints can either be solver variables (i.e. species), or parameterized species that aren't solver variables.
This implementation supports the first case where the constraints are solver variables.

• Structures the DAE constraint plumbing around the Rosenbrock solver
• Adds EquilibriumConstraint for chemical equilibrium relationships
• Adds LinearConstraint for mass conservation.
• Closes Create CPU constrained Rosenbrock #853
• Test includes Robertson reaction with the constraint A + B + C = constant, and Terminator reaction without any constraint (test/integration/test_linear_constraint.cpp)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.83099% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.61%. Comparing base (a9dd096) to head (3e7724b).

Files with missing lines	Patch %	Lines
include/micm/constraint/constraint_set.hpp	95.83%	2 Missing ⚠️
include/micm/constraint/equilibrium_constraint.hpp	84.61%	2 Missing ⚠️
...micm/solver/backward_euler_temporary_variables.hpp	33.33%	2 Missing ⚠️
include/micm/constraint/linear_constraint.hpp	94.44%	1 Missing ⚠️
include/micm/solver/rosenbrock.inl	97.50%	1 Missing ⚠️
include/micm/solver/state.inl	90.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #931      +/-   ##
==========================================
+ Coverage   94.04%   94.61%   +0.56%     
==========================================
  Files          68       69       +1     
  Lines        3797     3973     +176     
==========================================
+ Hits         3571     3759     +188     
+ Misses        226      214      -12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR restructures the DAE constraint implementation to use full species-row replacement (mass-matrix diagonal with algebraic rows) and expands unit/regression/integration coverage for constraint-related solver edge cases.

Changes:

• Integrates ConstraintSet into solver build + Rosenbrock solve loop (constraint residuals/Jacobian terms; algebraic-row mass-matrix handling; clamp behavior adjusted for DAEs).
• Updates ConstraintSet semantics to map constraints onto existing species rows (instead of appending extra constraint rows), and updates Jacobian sparsity/flat-id handling accordingly.
• Adds new unit/regression/integration tests covering constraint/DAE builds, error normalization behavior, reordering, and solve-time constraint enforcement.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/unit/solver/test_solver_builder.cpp	Adds regression tests ensuring DAE builds don’t throw when constrained species appears in kinetics (reactant/product).
test/unit/solver/test_rosenbrock.cpp	Adds normalized-error tests ensuring constraint-only columns don’t affect normalization.
test/unit/solver/test_lu_decomposition_policy.hpp	Adds <iomanip> include (test infra tweak).
test/unit/solver/test_lu_decomposition_in_place_policy.hpp	Adds <iomanip> include (test infra tweak).
test/unit/solver/test_linear_solver_policy.hpp	Adds <iomanip> include (test infra tweak).
test/unit/solver/test_linear_solver_in_place_policy.hpp	Adds <iomanip> include (test infra tweak).
test/unit/process/test_process_configuration.cpp	Fixes a spelling issue in a test comment.
test/unit/constraint/test_constraint_set.cpp	Updates tests for row-replacement constraint semantics; adds vectorized-matrix indexing test.
test/regression/RosenbrockChapman/regression_test_solve.cpp	Switches a regression to SixStageDifferentialAlgebraicRosenbrockParameters().
test/integration/test_equilibrium.cpp	New integration suite exercising constraint APIs and DAE solve behavior (incl. reorder + multi-cell cases).
test/integration/CMakeLists.txt	Registers new equilibrium integration test.
include/micm/solver/temporary_variables.hpp	Makes TemporaryVariables polymorphically clonable (Clone()), enabling correct State copy behavior.
include/micm/solver/state.inl	Adds mass-matrix diagonal initialization + constraint metadata into State construction.
include/micm/solver/state.hpp	Extends StateParameters/State with constraint metadata + mass-matrix diagonal; uses TemporaryVariables::Clone() for deep copy.
include/micm/solver/solver_builder.inl	Adds SetConstraints, incorporates constraints into sparsity/Jacobian IDs, sets algebraic-row masks and mass-matrix diagonal.
include/micm/solver/solver_builder.hpp	Adds constraints support to builder API and stores constraints in the builder.
include/micm/solver/solver.hpp	Adds post-solve clamp logic that avoids clamping algebraic variables; removes species/reaction count accessors.
include/micm/solver/rosenbrock_temporary_variables.hpp	Implements Clone() for Rosenbrock temporary variables.
include/micm/solver/rosenbrock.inl	Adds constraint residual/Jacobian integration + mass-matrix scaling; adjusts error norm implementation.
include/micm/solver/rosenbrock.hpp	Plumbs ConstraintSet through solver constructors; minor template naming fix.
include/micm/solver/backward_euler_temporary_variables.hpp	Implements Clone() for Backward Euler temporary variables.
include/micm/solver/backward_euler.hpp	Plumbs ConstraintSet through Backward Euler solver constructor for API compatibility.
include/micm/process/process_set.hpp	Adds algebraic-row masking: skips kinetic forcing/Jacobian updates for algebraic rows and aligns flat-id vectors.
include/micm/cuda/solver/cuda_rosenbrock.hpp	Updates CUDA Rosenbrock constructor signature to accept ConstraintSet.
include/micm/constraint/equilibrium_constraint.hpp	Refactors equilibrium constraint to a concrete type used via Constraint variant; adds negative-concentration guarding.
include/micm/constraint/constraint_set.hpp	Reworks constraint bookkeeping for row replacement (algebraic row mapping, Jacobian nonzeros/flat-ids, vectorized handling).
include/micm/constraint/constraint.hpp	Refactors constraints to a std::variant wrapper (currently EquilibriumConstraint).
docs/design/FULL_REVIEW.md	Removes internal design/review artifact doc.
docs/design/CODEX_TODO.md	Removes internal TODO artifact doc.
.gitignore	Ignores docs/design/ and CLAUDE.md.

Comments suppressed due to low confidence (1)

include/micm/constraint/equilibrium_constraint.hpp:12

• EquilibriumConstraint uses std::max but this header doesn't include <algorithm>. Since this is a public header (pulled in via constraint.hpp / solver_builder.hpp), it should be self-contained; add the missing include to avoid compile failures depending on include order.

#include <micm/constraint/constraint_error.hpp>
#include <micm/system/stoich_species.hpp>

#include <cmath>
#include <cstddef>
#include <string>
#include <system_error>
#include <vector>

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[boulderdaze]

The review comments were addressed in #937

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

include/micm/constraint/equilibrium_constraint.hpp:12

• EquilibriumConstraint uses std::max(...) but this header doesn't include <algorithm>. Relying on transitive includes is fragile and can break compilation on some standard library implementations; please include <algorithm> here explicitly.

#include <micm/constraint/constraint_error.hpp>
#include <micm/system/stoich_species.hpp>

#include <cmath>
#include <cstddef>
#include <string>
#include <system_error>
#include <vector>

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[K20shores]

Should we consider moving the indexing logic into Residual? I don't think we'd need the temporary concentrations vector above. That would reduce our memory footprint a little

[K20shores]

Same question here

[K20shores]

I get that turning concentrations into one of our matrix types makes this implementation more complicated, but especially in large models when we might be solving a million grid cells in one state, the copy of concentrations could get large

[mattldawson]

In general, I like it, particularly that it sets up a structure similar to what exists for processes.

A couple general suggestions:

• maybe move the specific constraints (linear, equilibrium) into a sub-folder, similar to how rate constants are in a sub-folder of process/.
• I agree with Kyle about avoiding allocating memory in the functions called by the linear solver. The functions that calculate forcing and Jacobian terms need to be as performant as possible. So, specifically:
  • allocate any working memory needed in the Forcing or Jacobian functions as part of the State (trying to minimize what's needed as much as possible)
  • avoid using the square-bracket syntax for matrix objects (this is not performant enough to use in the linear solver workflow). You could specialize functions for the various matrix types (as done in ProcessSet), but this might be a good opportunity to use the new DenseMatrixPolicy::Function() and SparseMatrixPolicy::Function() that were created for the external aerosol/cloud model API. These should be as performant as the specialized linear solver functions in ProcessSet but don't require specialization for the different matrix orderings.

I'm happy to do another review after you have a chance to work through the existing comments.

[boulderdaze]

Kyle suggested merging this PR and addressing the comments in a separate PR. I'm happy to do that since resolving the review comments requires changes in multiple places. Let me know what you think! @mattldawson

I learned from Kyle that @mattldawson suggested merging this PR, so I'll go ahead and merge it.