nse_solver: The energy Jacobian differentiates at fixed Ye, but the residual does not

Suggested priority: Medium
Reviewed commit: 3ac0bda4f00da3eed0446beadfc1cd5c51b99a40

Affected code: nse_eqns.H:304–319, nse_eqns.H:460–466, eos_composition.H:68–77.

This affects nse.solve_nse_e_mode = 2. The residual sends each trial composition to the EOS, which computes Ye_trial = sum(Z X/A) and zbar = abar * Ye_trial. During the solve, the charge constraint is not identically satisfied. Even at the solution, independent perturbations of the chemical potentials change Ye_trial.

The energy row instead uses the input target Ye and includes only the derivative through abar. Writing S = sum(X/A), the composition contribution should be

de/dx_j = -abar^2 * (dedA + Ye_trial * dedZ) * dS/dx_j
          + abar * dedZ * dYe_trial/dx_j

with the explicit temperature derivative added for x_j = T9, and the whole row divided by the input energy. The second term is missing, and the first should use the trial electron fraction.

Reproduction: Solve NSE at rho = 1e7 g/cm^3, T = 6e9 K, Ye = 0.5 using ase, Helmholtz, and Chabrier screening. Compare the analytic energy row to centered differences of nse_fcn() with chemical-potential perturbations of 1e-6 MeV:

Impact: The supplied Jacobian is inconsistent with the function being solved, which can impair convergence and reliability. The ordinary cell test still converges; this is not evidence that its final equilibrium composition is wrong.

Suggested fix: Include both composition derivatives consistently with the EOS residual. Add finite-difference checks at converged and off-constraint states, covering all three columns. The reproduction verifies the missing term for the chemical-potential columns; complete temperature-derivative validation remains necessary.

Reproduction commands and test scope

The supplied reproduce.cpp uses actual repository routines, AMReX, the ase network, and Helmholtz EOS. run_harness.py compiles it with the flags and links it with the objects from a fresh NSE cell build. Run from the repository root, using a fresh temporary build directory if repeating the build:

CCACHE_DISABLE=1 make -C unit_test/nse_net_cell -j4 \
  TMP_BUILD_DIR=/tmp/nse-review-build-20260907 \
  EBASE=/tmp/nse-review-20260907 \
  AMREX_HOME=/home/zingale/development/amrex \
  > /tmp/nse-review-build-20260907.log 2>&1

python3 agent-notes/nse-review-2026-09-07/run_harness.py \
  /tmp/nse-review-build-20260907.log

cd unit_test/nse_net_cell
/tmp/nse-review-202609073d.gnu.ex inputs_ase

Adjust AMREX_HOME for another machine. The runner needs a fresh build log containing both the main compilation and link commands.

Validation used GNU C++20, double precision, CPU, no MPI/OpenMP, simplified SDC, and Chabrier screening. AMReX revision: 3c3bbaa34cd3. The existing NSE cell executable completed and recovered the requested perturbed energy with both energy modes. The focused cases expose defects absent from that happy-path check. GPU execution, other networks, and parameter-space sweeps were not tested.

baseline-output.txt
reproduce.cpp
reproduction-output.txt
run_harness.py