[HengyuLi-Ozaki-lab]

What

fp_run refuses, before any work, the counts the FP solver cannot run with. fp_param_check
(fp/fp_param_registry.f90) holds the rules in one place and fp_api_run calls it before fp_prep. A violation is
FP_ERR_INVALID with one XX fp_run: ... line per violation on unit 6; the handle stays usable, so a corrected count
runs on the next call.

Count	Accepted	Otherwise, on develop
NRMAX	1 to FP_MAX_NRMAX (100)	below 1 the mesh set-up runs past an array bound; above 100 the run is made and fp_get_state returns rc=3
NPMAX, NTHMAX	2 or more	the solver runs past an array bound
LMAXFP	0 to HUGE − 1	below 0 no pass is made and fp_loop tests an error flag that no pass has set (fp/fploop.f90:231; on the build measured the process ends); at HUGE the iteration's exit at convergence, N_IMPL = 1 + LMAXFP (fp/fploop.f90:98), overflows, N_IMPL <= LMAXFP (:81) stays true and the step never ends
NSAMAX	at most NSBMAX	the collision arrays are NSBMAX wide in both species directions (fp/fpcomm.f90:472-474)
NS_NSA(1..NSAMAX)	1 to MIN(NSMAX, NSBMAX)	a species has profiles up to NSMAX, and its distribution is copied into the background array at its species number (fp/fpmpi.f90:65-71)
NS_NSB(1..NSBMAX)	1 to NSMAX	profiles exist up to NSMAX

A 0 in either map counts as the slot's own number, which fp_set_nsa_nsb substitutes when the run is prepared.
NSBMAX above NSMAX is not refused in itself: with every NS_NSB entry at most NSMAX it runs (measured, below).
FP_MAX_NRMAX is the API's limit, so fp_api passes it in; the registry module does not depend on fp_state.
fp_get_state's own check stays.

Why

fp_param_set takes these counts as they come, and on develop a value the solver cannot run with is met only deep
inside fp_prep or fp_loop: an array index out of bounds (an abort when the library is built with run-time checks,
undefined behaviour in the default -O3 build), a process that ends, a call that never returns, or a run whose results
fp_get_state cannot return. For a host that holds the library in its own process (the MCP server, a Python session)
each of these takes the host with it. This is validation in one batch before the run (#143) instead of a STOP reached
from the library (#142).

Found while documenting FP's parameters for a downstream client (TASK Web Client); in use there since 2026-10-03.

Measured on libfpapi.so (macOS arm64, gfortran 15, -O0 with run-time checks; one process per case, 10 × 10
momentum cells, fp_run(1) unless stated):

Case	develop	This branch
NRMAX = 101	run made; fp_get_state rc=3	fp_run rc=1
NRMAX = 101 with fp_run(0)	accepted; fp_get_state rc=3	rc=1
NRMAX = 0, -1; NRMAX = 0 with fp_run(0)	abort (index of array rm)	rc=1
NPMAX = 1, 0; NTHMAX = 1, 0	abort	rc=1
LMAXFP = -1	XX mtx_abort: ierr_g= -1, the process ends	rc=1
LMAXFP = 2147483647	no return within 120 s	rc=1
NSAMAX = 2, NSBMAX = 1, NS_NSA(2) = 1	abort (index 2 of lnlam)	rc=1
NS_NSA(1) = 3, NSMAX = 3, NSBMAX = 2	abort (index 3 of fnsb)	rc=1
NS_NSA(1) = 3, NSMAX = 2, NSBMAX = 3, NS_NSB = {1, 2, 1}	abort (index 3 of plf)	rc=1
NS_NSB(2) = 3, NSMAX = 2, NSBMAX = 2	abort (index 3 of plf)	rc=1
NSBMAX = 3, NSMAX = 2 (slot 3 is species 3)	abort (index 3 of plf)	rc=1
NS_NSA(1) = -1	abort (index -1 of modelw)	rc=1
NS_NSB(2) = -1, NSMAX = NSBMAX = 2	abort (index -1 of pz)	rc=1
NS_NSA(2) = 0 (so 2), NSMAX = 1, NSAMAX = NSBMAX = 2, NS_NSB(2) = 1	abort (index 2 of plf)	rc=1
NS_NSB(3) = 0 (so 3), NSMAX = 2, NSBMAX = 3	abort (index 3 of plf)	rc=1
NRMAX = 100	runs, state returned	the same
NPMAX = 2; NTHMAX = 2	runs	the same
LMAXFP = 0, 2147483646	runs	the same
NSAMAX = NSBMAX = 2; species 2 evolved alone with NSBMAX = 2	runs	the same
NSMAX = 2, NSBMAX = 3, NS_NSB = {1, 2, 1}	runs	the same
a 0 in both maps where the slot's own number is valid	runs	the same
the same species in two evolved slots (NSMAX = 1)	runs	the same
NS_NSB(1) = 2, NSBMAX = 1 (species 1 in no background slot)	runs, with XX NS_NSA has no correponding NS_NSB	the same

Checked

• Whole suite, upstream CI's flags (pytest python/ --forked --timeout=120 --timeout-method=signal), the seven
  lib*api.so and libtotapi_mono.so built, MONO_LIB_PATH unset; macOS (Apple silicon), gfortran 15.2.0
  (Homebrew, -O0 -fbounds-check -fcheck=all), Python 3.12.13, pytest 9.0.3, mcp 1.27.1, bpsd develop fb8414f:
  • this branch (develop 4a5d977 and this one commit): 757 passed, 35 skipped, 1 xpassed;
  • develop alone, the same build: 723 passed, 35 skipped, 1 xpassed. The 34 more are the new tests.
• The 35 skips are the 19 equivalence tests that run only on Linux since fplib + wrxlib equivalence tests fail 1e-10 tolerance on develop (mismatches ~1e-9) #213 ("Equivalence tests are
  Linux-canonical"), the mono tests that need MONO_LIB_PATH (CI's mono job runs them) and three ti_mcp tests
  without their data fixture. They were not run here: upstream's Linux CI is their verdict. Downstream, a Linux CI
  with the same four jobs has run them green on this commit merged with other changes, not on this branch alone. The
  xpass is trlib's test_NSMAX_in_range (tr_tst2 fixture: NSMAX>2 mutation produces NaN scalars (RNU/RTU species 3+ unpopulated) #189), as on develop.
• The tests: python/fplib/tests/test_run_checks.py, 34 tests, one per case and no subTest (pytest --forked reports a failing unittest subTest as passed (24 test files use subTest) #241), each species
  case breaking one rule only. The runs that must still be made take three steps and assert the time reached
  (3 × DELT with a DELT that is not the default), the extents asked for and a finite, positive density (the
  two-cell runs, whose density is wrong, the time only). One test holds the eight XX fp_run: lines of a run that
  breaks every rule. Against develop's library the refusals fail (the table above: an abort of the forked child, a
  run that is made, a session that ends, no return within the time limit) and the runs that must still be made pass.
• Mutations of the check: 28 (each bound moved by one or removed, the zero substitution removed or changed in each
  map, each map's loop shortened, a message line removed, the call disabled, a larger limit passed), the library
  rebuilt for each. The tests notice every one.
• make -C fp fp_api_check_so: OK.
• The LMAXFP = HUGE and HUGE − 1 cases run in a process of their own (subprocess.run(..., timeout=30)), killed if
  it does not end: a forked test that hangs inside a Fortran loop cannot be stopped from outside (pytest-timeout ends
  the session with an internal error and the child keeps running).

Things to know

• One refusal changes a run that used to complete. With NRMAX above 100 the run was made, fp_get_state
  returned rc=3, and the results could be read only from unit 6 or from fp_regress.dat (FP_REGRESS_DUMP=1). It is
  now refused before the run; CHANGELOG.md lists it under "Changed". Every other rule is a bound the solver indexes
  by.
• The standalone fp program is unchanged. The namelist path's fp_check (fp/fpparm.f90) stays empty: the menu
  calls it after every input line, where a rule between two parameters (NSAMAX <= NSBMAX) would refuse the state
  between two lines.
• One code for every refusal. fp_run returns FP_ERR_INVALID; the reason is the XX fp_run: line on unit 6. A
  fp_validate() that returns the list, as eq_validate does and Parameter validation API: pre-run consistency check across modules #143 proposes for every module, could be built on
  fp_param_check.
• Not refused, and said so in docs/fp-library/architecture.md: NPMAX = 2 or NTHMAX = 2 (it runs and is too
  coarse for a result); a mesh too large for memory, or whose NRMAX × NPMAX × NTHMAX passes a default integer
  (fp/fpprep.f90:597); an evolved species that no background slot names (reported by fp_set_nsa_nsb, and the run
  is made, without collisions with its own kind).
• fp_get_state after a refusal reads the last run's arrays with the counts now set, past their end when a count
  was raised, as it does on develop after any fp_set_param without a run. The document now says not to call it
  before the next run that is made; the fix belongs to fp_api_get_state and to a pull request of its own.
• fp/fp_api.h, the header comment of fp/fp_api.f90 and fp_mcp's tool text do not mention the check, so that
  this branch merges with feat(fp_mcp): expose set_param_str tool for KNAMEQ / MODELG=3 equilibrium load #231, fix(fp_mcp): redirect Fortran WRITE(6,...) to stderr to protect JSON-RPC channel #232 and feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233 without a hand (they change the lines next to them).
  python/fplib/fplib.py (run) and docs/fp-library/architecture.md document it. Say the word and the three texts
  are added here, or in a follow-up once those are merged.
• Size. 459 added lines: 309 of tests, 94 of Fortran (83 in the registry, 11 in fp_api.f90), 28 of
  documentation, 21 of CHANGELOG, 7 of a docstring.

Scope

Based on current develop (4a5d977) and standing alone on it: one commit. Independent of #226, #231, #232, #233 and
#240: it merges with each of their heads without a conflict (git merge-tree); it shares one file with #233 only
(fp/fp_api.f90, different hunks) and none with the others.

🤖 Generated with Claude Code

[k-yoshimi]

Reviewed at 3eb8f8c4 (based on current develop tip). Approving.

Verified locally (macOS arm64, gfortran 15, repo make.header, pytest 9.1.1 --forked --timeout=120 --timeout-method=signal, with the strict-subTest override from #243 active):

• Rebuilt fp/libfpapi.so from the PR head (fp_param_check exported) and ran python/fplib + python/mcp-servers/fp_mcp: 119 passed, 3 skipped (the Linux-canonical equivalence cases). All 36 cases in the new test_run_checks.py pass, including the two process-isolated LMAXFP cases.
• Cross-checked the bounds against the sources they cite: the collision arrays are (…, NSBMAX, NSBMAX) (fp/fpcomm.f90:472-474), FNSB is written at the species number (fp/fpmpi.f90:65-71), fp_loop's DO WHILE (N_IMPL .le. LMAXFP) with N_IMPL = 1 + LMAXFP as the convergence exit, FP_MAX_NRMAX = 100 in both fp/fp_state.f90 and python/fplib/_ffi.py. The registry's set-time caps (NSMAX <= 100, NSAMAX/NSBMAX <= 8) keep the loops' MIN(…, SIZE(NS_NSA)) guards from ever truncating.
• The check sits after the g_initialized / ntmax < 0 guards and before fp_prep, so a refused handle stays usable, as TestARefusalLeavesTheLibraryUsable shows.

Scope note for the record: the Fortran change is confined to the C-ABI entry (fp_api.f90) and the registry module, no solver change.

Non-blocking:

• CHANGELOG.md describes the same change under both "Changed" and "Fixed"; one entry (Fixed, with the NRMAX > FP_MAX_NRMAX behaviour change called out inside it) would read cleaner.
• The refusal reasons go to unit 6 only. Through fp_mcp they are currently shredded into the JSON-RPC stream (the problem #232 addresses), so an LLM client sees only invalid parameter until #232 lands. Not this PR's concern, just the ordering: #232 (after its main() rework) makes this PR's diagnostics visible.

[k-yoshimi]

Independent Codex review (second reviewer, read-only) found no HIGH items; approval stands. For the record:

• MED → filed as fp_get_state reads past the allocated extents when NRMAX/NSAMAX were raised after the last fp_prep (pre-existing; surfaced by #242 review) #245, not a blocker here. After a run, raising NRMAX/NSAMAX and then calling fp_get_state without a successful fp_run reads past the arrays' allocated extents (fp_api_get_state loops over the current counts, guarded only by ALLOCATED). That is pre-existing on develop; this PR adds one more way to sit in that window (a refused run) and documents the hazard in architecture.md. The minimal fix (bound the copies by SIZE(RNT, …), the pattern feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233 uses for its scalars) will go in after fix(fp): fp_run refuses the counts it cannot run with, before any work #242 and feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233 merge, since both touch fp_api.f90.
• LOW, optional in this PR: CHANGELOG.md could say "with 0 meaning the slot's own number" for the species maps (the architecture table already does); the 30 s subprocess.run timeout in test_run_checks.py for the two process-isolated LMAXFP cases is tighter than CI's 120 s per-test budget — a loaded runner could fail the valid HUGE-1 case spuriously, so 90–100 s would be safer while still containing a hang.
• Codex confirmed: fpcomm_parm supplies every variable fp_param_check references; HUGE(LMAXFP)-1 cannot overflow; the loop bounds are safe under the set-time caps; fp_iter01 / fp_jt60 / fp_dt1 inputs stay valid; checking on every fp_run (including ntmax=0 and the already-prepared case) is the right placement; FLUSH(6) makes the capfd assertions sound under --forked.

[k-yoshimi]

@cursor review

[cursor]

Bugbot couldn't run

Bugbot is not enabled for your user on this team.

Ask your team administrator to increase your team's hard limit for Bugbot seats or add you to the allowlist in the Cursor dashboard.