[k-yoshimi]

Fixes #189: tr_run refuses, before tr_prep, an active species whose namelist profile the solver cannot evolve, and tr_validate reports the same findings. The strict xfail on test_NSMAX_in_range is removed.

Root cause (corrects the issue text)

The issue attributed the NaN to the equilibrium import copying RNU/RTU(...,3..NSMAX) from an eqdata.TST-2 built for two species. That is not the path the tst2 fixture takes: it runs with MDLUF = 0, where tr/trprof.f90 builds RN/RT for ns = 1..NSMAX from the namelist pairs PN/PNS and PT/PTS (RNU/RTU are zero-filled and unused). Reproduced on the fixture:

NSMAX=3 mutation (tst2 fixture)	after 2 steps
none (species 3 at the tr_init defaults PN=PNS=0)	RN(:,3) = 0 after prep, all species' RT and WPT/BETA/TAUE = NaN** after the first step
PN[3]=0.005, PNS[3]=0.0005	finite
PN[3]=0, PNS[3]=0.0005 (5 steps)	finite
PN[3]=1e-8, PNS[3]=1e-9	finite
PN[3]<0	NaN
PT[3]=0 or PTS[3]=0 (density set)	NaN

So the transport step divides by the density / temperature of every active species; a species whose density is identically zero or negative, or whose temperature is non-positive at the centre or the edge, poisons the whole state. NSMAX=2 with PN[2]=PNS[2]=0 happened to fail inside tr_loop (TrlibRunError); species 3/4 produced silent NaN.

Change

• tr/tr_api.f90: new private species_profile_violations (every MDLUF outside the UFILE modes 1/2/3, i.e. tr_prof's namelist branch; ns = 1..MIN(NSMAX, array extents)): non-finite PN/PNS/PT/PTS -> OUT_OF_RANGE; PN/PNS negative -> OUT_OF_RANGE; both zero -> OUT_OF_RANGE_AFTER_DEP; PT <= 0 / PTS <= 0 -> OUT_OF_RANGE; parameters named in the registry spelling (PN[3]). tr_api_run calls it whenever it is about to run tr_prep and returns TR_ERR_INVALID with one XX tr_run: PN[3]: ... line per finding on unit 6 (the fix(fp): fp_run refuses the counts it cannot run with, before any work #242 contract: the handle stays usable, set the parameters and run again); it also refuses NSMAX > NSM (4) there, which only validate() used to report. tr_api_validate pushes the same findings as diagnostics. No physics code touched (C-ABI layer only).
• Out of scope, filed: tr: UFILE modes (MDLUF=1/2/3) still take some species from PN/PNS/PT/PTS; the #189 pre-run check does not cover them #252 (the species that MDLUF = 1/2/3 still take from PN/PNS/PT/PTS, selected by MDNI/MODEP/RHOA inside tr_prof; no UFILE fixture to verify a mirror against) and tot: tr: parameter updates after a run bypass tr_api's prepared flag (no re-prep, no #189 pre-run check) #253 (tot_set_param("tr:...") calls tr_param_set directly, so after a first run tot mutations never clear tr_api's prepared flag: no re-prep and no pre-run check; changing that alters tot's coupled-pipeline semantics and needs its own decision).
• Tests: test_NSMAX_in_range loses its xfail (the refusal is the tolerated "controlled failure"); a new positive test runs NSMAX=3/4 finite with the added species' profiles set; python/trlib/tests/test_species_profile_checks.py (21 cases, one per case): the refusal matrix (defaults, zero density, negative PN / PNS, zero / negative PT, zero PTS, NaN density, +Inf temperature, NSMAX=5 with all profiles set, MDLUF=4 (tr_prof's default branch), species-2 zero density now refused instead of failing in the loop), the accepted cases (profiles set, PN=0 with PNS>0, the fixture as-is, handle usable after a refusal; finiteness asserted on the scalars and every RN/RT entry), and validate() parity (codes, parameter names, -Inf, clean when profiles are set, inactive species ignored).
• Docs: python/trlib/README.md, docs/sphinx/modules/tr/{en,ja}/parameter-setting.md (list of checks validate() performs), docs/sphinx/modules/tr/{en,ja}/mcp.md (error table: the NSMAX/PN/PT case is now invalid parameter, not calculation failed).

Default state (NSMAX=2, species 1/2 at PN=0.5, PNS=0.05, PT=1.5, PTS=0.05) and every fixture / sample input (tr_iter01, tr_m0904: NSMAX=4 with four positive values each; tr_tst2: NSMAX=2) pass the check unchanged.

Verification

Local (macOS, CI flags): the four touched trlib test files 50 passed; trlib + tr_mcp + totlib 269 passed, 1 pre-existing macOS/py3.10 ExceptionGroup failure, 18 pre-existing skips; make -C tr tr_api_check_so OK (tr_api_check_all's non-PIC link needs the gsaf graphics library, absent on macOS; CI runs it). Every refusal case fails on develop (NaN or TrlibRunError instead of TrlibParamError).

Review

In-house review + Codex (codex-rescue) + ai-review-cycle Codex on the first version: their findings (MDLUF gate shape, non-finite inputs, NSMAX > NSM at run time, RN/RT finiteness in the positive tests, stale docblock and mcp.md rows) are in this commit; the UFILE-mode subset and the tot bypass became #252 / #253. The delta was re-reviewed by Codex (ship; three LOW wording/coverage items applied).

Refs: #189, #143 (batch pre-run validation), #242 (the fp precedent).

🤖 Generated with Claude Code

https://claude.ai/code/session_01TA2KahTs3qLMZL6yjSsWwT

---

Note

Medium Risk
Changes pre-run validation in the C ABI entry path (not core physics), but alters when run() fails (TrlibParamError vs silent NaN or mid-loop errors) and tightens NSMAX-at-run behavior callers may have relied on.

Overview
Fixes #189 by rejecting active species whose namelist density/temperature profiles cannot be evolved, instead of letting the transport step divide by zero and poison the state with NaN.

tr/tr_api.f90 adds species_profile_violations (non-UFILE MDLUF, species 1..NSMAX): non-finite, negative, or all-zero PN/PNS, and non-positive PT/PTS, reported as PN[ns] / PT[ns] / PTS[ns]. tr_run calls this (and blocks NSMAX > NSM) before tr_prep, returning TR_ERR_INVALID with per-line stdout messages while keeping the handle usable. tr_validate emits the same rules as diagnostics.

Tests drop the test_NSMAX_in_range xfail, add a positive NSMAX=3/4 case with profiles set, and add test_species_profile_checks.py for run/validate parity. Docs (trlib README, Sphinx EN/JA parameter-setting and MCP troubleshooting) describe the new checks and retarget calculation failed guidance toward DT/equilibrium rather than PN/PT.

^{Reviewed by Cursor Bugbot for commit 72fb0d5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[k-yoshimi]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 72fb0d5. Configure here.}