nse_solver: The energy Jacobian differentiates at fixed Ye, but the residual does not
Maintainers usually reply within 1 day
@zhichen3 is already working on this.
Since Sep 7, 2026.
Assessment
This issue has not been assessed yet.
Description
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:
| Derivative of normalized energy residual | Analytic Jacobian | Finite difference | Missing term |
|---|---|---|---|
| With respect to mu_p | 0.2753995702 | 1.8660438187 | 1.5906442477 |
| With respect to mu_n | 0.2753995702 | 1.8720744501 | 1.5966748796 |
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
- Dominant language
- C++
- Stars
- 44
- Forks
- 46
- Avg merge
- 3d 15h
- Merged PRs (30d)
- 9
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from AMReX-Astro/Microphysics
-
bug GPU
Difficulty 2/5 1-3 hours Newbie friendliness 69/100
AMReX-Astro/Microphysics#2115 ·
Maintainers usually reply within 1 day
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
AMReX-Astro/Microphysics#2104 · 3 comments ·
Maintainers usually reply within 1 day
-
ai-code-audit screening
Difficulty 4/5 3-5 days Newbie friendliness 55/100
AMReX-Astro/Microphysics#2097 · 1 comment ·
Maintainers usually reply within 1 day
-
ai-code-audit screening
Difficulty 4/5 3-5 days Newbie friendliness 72/100
AMReX-Astro/Microphysics#2096 ·
Maintainers usually reply within 1 day
-
ai-code-audit screening
Difficulty 4/5 3-5 days Newbie friendliness 66/100
AMReX-Astro/Microphysics#2095 · 1 comment ·
Maintainers usually reply within 1 day
All issues in AMReX-Astro/Microphysics
Similar issues
-
category:port-update
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 2 days
-
(S1 - Need confirmation)
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
CleverRaven/Cataclysm-DDA#89194 ·
Maintainers usually reply within 1 day
-
reproduced
Difficulty 1/5 Under an hour Newbie friendliness 67/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
moonshine-ai/moonshine#231 ·