[HengyuLi-Ozaki-lab]

Summary

Adds the seven geometry-dependent global plasma scalars that FP already computes to fp_state_t, exposed as a TR-style scalars block:

field	unit	Fortran source
TOTAL_IP	MA	Σ_NSA PIT(NSA,NTG1) — fpsave.f90:110,146,286, printed :311
STORED_ENERGY	MJ	Σ_NSA PWT(NSA,NTG1) — fpsave.f90:112, printed in the W column :252
COLLISION_POWER	MW	Σ_NSA PPCT(NSA,NTG1) — fpsave.f90:114,278, printed :307
ABSORPTION_POWER	MW	Σ_NSA PPWT(NSA,NTG1) — fpsave.f90:115,277, printed :305
ABSORPTION_WR	MW	Σ_NSA PWRT(NSA,NTG1) — fpsave.f90:284, same print line
ABSORPTION_WM	MW	Σ_NSA PWMT(NSA,NTG1) — fpsave.f90:285, same print line
PLASMA_VOLUME	m³	TVOLR — fpprep.f90:231-234, banner :237

All seven were already available as fpcomm module data (PIT/PWT/PPCT/PPWT/PWRT/PWMT are (NSAMAX, NTG1M) allocatables; TVOLR is a scalar). None is computed at print time, so all are retrievable after fp_run. The MW/MA conversions are the ones already applied in the moment integrators (fpsave.f90:1310, :1377, :1509, :1510).

Motivation

FP's get_state currently returns only the six per-species profile arrays and the mesh dimensions. Those six are local per-unit-volume moments: with MODELD=0 and no wave or current-drive model, each radial cell is an independent 0-D collisional relaxation depending on local n, T, Z and E — not on B, R or ε.

The practical consequence: loading a completely different equilibrium changes nothing observable. Running fp_iter01 against an analytic equilibrium versus against an eq.bin written by eq's save tool with substantially perturbed geometry (RR 3.0→3.6, RA 1.0→1.2, BB 3.0→4.5, RIP 1.0→2.0, RKAP 1.5→1.8) produces bit-identical RNT/RWT/RTT/RJT/RPCT/RPWT.

The equilibrium is being consumed — eqgetb writes the loaded geometry back into FP, the mesh metrics move (rsrhon 0.805→1.0264, bpm 0.3506→0.1829, ql 2.2961→7.0134), and the global integrals scale with the volume ratio — but it enters only through the volume element and the mesh metrics, and fp_state_t exposed neither. So an MCP/library client driving the MODELG=3 equilibrium-load path had no way to tell whether the file had been used at all.

(Ruled out as a stale-state artifact: changing PTPR/PTPP, PN or NTMAX does move the arrays. Two further attempts to surface a difference — a strong loop voltage driving RJT, and radial transport with MODELD=1 — were also bit-identical, with a control confirming the perturbed eq.bin had been loaded in that arm.)

Why a scalars block

trlib's TrState.to_dict() already returns a top-level "scalars" key; fplib's did not. Beyond exposing the new values, this removes that shape inconsistency — downstream code that reads state["scalars"] generically (for example steady-state detection that looks up a named scalar) silently got None for FP.

Verification

Rebuilt with the repo's current make.header (-fbounds-check -fcheck=all, unmodified).

1 — values agree with the Fortran's own output. Each scalar was compared against the WRITE(6,...) lines of the same run at full precision: TVOLR 0.284245E+02, W 5.3683E+00, collision -2.1308E-01, IP 1.4970E-13, absorption 0.0000E+00. This simultaneously validates the unit conversions and the struct layout — a layout error would read garbage. A supplementary probe with E0=0.05 drove TOTAL_IP to 45.24848, matching the printed 4.5248E+01.

2 — the equilibrium is now observable, and the ratios reproduce what the Fortran diagnostics independently showed:

scalar	analytic equilibrium	loaded eq.bin (perturbed)	ratio
PLASMA_VOLUME	28.42446	53.12014	1.8688
STORED_ENERGY	5.368302	10.33949	1.9260
COLLISION_POWER	−0.2130797	−0.4073574	1.9118

The six profile arrays remain bit-identical between those two runs — i.e. the underlying physics is unchanged and it is the new scalars that make the difference visible.

3 — no regression. State captured with the pre-change .so and with the rebuilt one is bit-identical across all six arrays, the five integer dimensions and TIMEFP. Purely additive.

4 — initialisation safety. After init without run, all seven scalars read 0 (the g_prepared guard prevents an uninitialised TVOLR from leaking); after run, they are populated. Filling is bounds-guarded with MIN(NSAMAX, SIZE(PIT,1)) / MIN(NTG1, SIZE(PIT,2)).

5 — tests. fplib 47 passed (was 45), fp_mcp 46 passed (was 45). New coverage asserts the seven fields are appended last in FpStateC._fields_ and are all c_double, that from_c/to_dict carry them, and that the MCP STATE_SCHEMA stays in sync with SCALAR_FIELDS.

6 — determinism. 5/5 fresh runs of each arm, byte-identical outputs.

Honest caveats

• ABSORPTION_POWER / ABSORPTION_WR / ABSORPTION_WM are verified only at zero. I could not drive them non-zero through the C ABI: MODEL_WAVE=1 with PABS_LH=1.0 still yields 0, and the LH/EC resonance-mesh parameters (DELNPR, NPRMAX, …) are not in fp_param_registry.f90, so they are unreachable from this path. The summation follows exactly the same pattern as the two power fields that are verified against non-trivial values, but a reviewer with a working wave configuration should sanity-check them.
• ABI change. The seven fields are appended at the end of fp_state_t, so libfpapi.so must be rebuilt; python/fplib/_ffi.py is updated in lockstep.
• test_equivalence.py::test_iter01 fails on this branch — pre-existing, not introduced here. Verified by stashing the entire change, rebuilding, and re-running: the same failure appears with 37 mismatches, all in profile[*].RPCT at rel_err ~1e-9–1e-10. Structurally it cannot be affected either: _to_baseline_shape() reads only the six arrays, the integer dimensions and TIMEFP, never the new scalars block.

Files

fp/fp_state.f90, fp/fp_api.f90, fp/fp_api.h, python/fplib/_ffi.py, python/fplib/state.py, python/mcp-servers/fp_mcp/server.py, plus tests in python/fplib/tests/ and python/mcp-servers/fp_mcp/tests/.

Independent of the two companion fp_mcp PRs (#231 set_param_str, #232 stdout guard); this one may need a trivial rebase if #231 lands first, since both touch fp_mcp/server.py in different places.

🤖 Generated with Claude Code

[HengyuLi-Ozaki-lab]

This has been green since 2026-08-06 and has had no review yet. Could one of you look at it when you have time? It is
small and self-contained (9 files, +228/-14: the global plasma scalars in fp_state_t) and the FP work we are doing downstream builds on it. It does not depend
on #226, and a trial merge of #226, #231, #232, #233 and #240 together is clean.

[k-yoshimi]

Reviewed at 92a0163d (based on current develop tip). Approving; one follow-up is filed on the maintainer side (below).

Verified locally (macOS arm64, gfortran 15, rebuilt fp/libfpapi.so from the PR head, pytest 9.1.1 --forked --timeout=120 --timeout-method=signal, strict-subTest override from #243 active):

• python/fplib + python/mcp-servers/fp_mcp: 88 passed, 3 skipped (Linux-canonical equivalence).
• Live probe (NPMAX=NTHMAX=20, run(2), unit 6 captured at fd level): the state's seven scalars equal the last FPWRTGLB block to every printed digit — TOTAL_IP 3.3668E-14, COLLISION_POWER 3.4465E-12, STORED_ENERGY 3.7137E-01 (the W column), PLASMA_VOLUME 3.55306 (the TVOLR banner). Earlier NTG1 samples differ, confirming the "latest NTG1" semantics is what is exposed.
• Array shapes cross-checked: PIT/PWT/PPCT/PPWT/PWRT/PWMT are allocated (NSAMAX, NTG1M) (fp/fpcomm.f90:1204-1217), so SIZE(…,1) for species and SIZE(…,2) for the sample index are the right guards; TVOLR is a module scalar; the g_prepared / NTG1 >= 1 / ALLOCATED guards keep the zeros honest before the first run.
• Layout: the 7 doubles are appended after RPWT in all three declarations (fp_state.f90, fp_api.h, _ffi.py), and test_global_scalars_are_appended_last pins that.

Follow-up (maintainer side, not asked of this PR): the 1e-10 binary-vs-library equivalence gate does not see these scalars yet. fp/fpregress.f90 dumps only TIMEFP, extract_fp_metrics.py's SCALAR_KEYS and the _flatten in python/fplib/tests/test_equivalence.py mirror that, and the fp_* baselines would need regeneration on canonical Linux (the regen workflow covers tr/eq/tot only). That is the same "state field added without the regress mirror" class we hit with AJRFT in TR (#187 → #190/#191), so I am filing it as an issue and will do the fpregress + extractor + baseline regeneration myself after this merges. Nothing in this PR blocks on it: compare_metrics.py compares the scalars the Python side emits, and the Python equivalence flatten still emits TIMEFP only, so CI stays green until the mirror lands with its baselines.

[k-yoshimi]

Independent Codex review (second reviewer, read-only). One concrete regression needs a fix in this PR; the ABI point becomes a repo-wide follow-up issue.

MED — totlib pipeline output changes silently (fix in this PR, please). python/totlib/pipeline.py::_state_to_scalars (lines 149-172) returns dict(state.scalars) as soon as the state has a scalars dict, and only falls back to the numeric top-level attributes for modules without one — that fallback is what FP has been using. With this PR, FP pipeline results (pipeline.py:558 and :650, including partial results) switch from {nrmax, nsamax, npmax, nthmax, ntg2, timefp} to the seven new globals and lose timefp. The existing pipeline tests use mocks that already carry .scalars, so nothing caught it. Suggested fix: in _state_to_scalars, when the state has scalars, still merge in timefp (and the int dims) for FP — or, simpler and uniform, always start from the numeric top-level attributes and update with state.scalars — plus one regression test that feeds a real FpState through it.

Docs to update in this PR: docs/sphinx/modules/fp/en/state.md (lines 19-20 and the table at 74) and the ja twin say state.scalars holds only timefp and that FP has 1 scalar; python/fplib/README.md and docs/fp-library/architecture.md still list the old struct only.

HIGH per Codex, filed as #246 (repo-wide, not a blocker here). Appending members keeps the old offsets but not the allocation size: an old caller with a new .so gets 56 bytes written past its struct during the unconditional zeroing, and a new caller with an old .so reads seven untouched zeros that look like real values (the scalars block then looks valid to an MCP client). The repo's fp_state_t/tr_state_t/… ABI has no size or version query at all, so this is not specific to this PR — it is the same for every state-struct growth we have done (AJRFT in TR, for one). I will track a size-negotiated getter / ABI-version symbol across modules in #246; for this PR the existing rule "rebuild libfpapi.so in the same commit" stands.

LOW (optional): STATE_SCHEMA["scalars"] is required but none of its seven members is (required: list(SCALAR_FIELDS) would make the contract explicit); test_size_matches_header_math checks ctypes arithmetic only, not a C sizeof — covered by #246.

Codex confirmed, consistent with my local probe: field order/types match across the three declarations; NTG1 cannot exceed the accumulators' second dimension; the MA/MJ/MW units match the 1.D-6 conversions in fpsave.f90; TVOLR is valid after fp_prep even with zero steps; libtotapi_mono.so needs no tot_state_t change.

Once the pipeline fix + docs are pushed I will re-approve.

[k-yoshimi]

Heads-up for the rebase: the #245 fix (branch fix/fp-get-state-extents-245, PR to follow #242) changes the profile-copy loop in fp_api_get_state to nr_alloc = MIN(NRMAX, SIZE(RNT,1)), nsa_alloc = MIN(NSAMAX, SIZE(RNT,2)), ntg_last = MIN(MAX(NTG2,1), SIZE(RNT,3)) and reports the copied extents in state%nrmax/nsamax. Your scalar block is inserted after that loop's END IF, so it should 3-way merge cleanly; it already bounds the P*T sums by SIZE(PIT, ...), which is the same pattern. Just make sure nothing in the inserted block loops to the bare NRMAX / NSAMAX.

[HengyuLi-Ozaki-lab]

Pushed e84d336b.

The pipeline regression. Reproduced first: one FP step through run_pipeline on the real library returned the seven globals and no timefp. _state_to_scalars now gives, for an FpState, its numeric top-level attributes together with its scalars dict: 13 keys, the six it had before and the seven new ones.

I took the FP-only form rather than the uniform one, because the uniform one changes every other module's pipeline results: TrState, EqState, WrState and WrxState have top-level counts (nt, nrmax, nsmax, nine dimensions for EQ, modelg and mdlwrq for WRX) that would join their scalars, and the existing mock-based test gains a call_count. An FpState is told by its class's name and module, so totlib imports nothing for it. If you prefer the uniform form I will change it.

Tests: a real FpState through the function; an FpState reached under another package name; a state of another module with top-level counts keeps exactly its dict; one FP step through run_pipeline on libfpapi.so, compared key by key with get_state(). The first, the second and the last fail without the fix.

Documentation. docs/sphinx/modules/fp/{en,ja}/state.md (the scalar section and the comparison table), python/fplib/README.md, docs/fp-library/architecture.md; and the same "1 (timefp)" cell in docs/sphinx/modules/wr/{en,ja}/state.md. Two things the new text says that the comment in python/fplib/state.py does not, both measured on this build: six of the seven are sums over the species at the latest NTG1 sample while PLASMA_VOLUME is TVOLR; and all seven are zero until the first run() (run(0) is enough) and again after a set_param, until the next run(), since fp_set_param clears g_prepared.

LOW. STATE_SCHEMA["scalars"] has required: list(SCALAR_FIELDS), with its test.

Your heads-up about #248. The scalar block does not loop to the bare counts: ntg1_last = MIN(NTG1, SIZE(PIT, 2)) and DO nsa = 1, MIN(NSAMAX, SIZE(PIT, 1)). A trial merge of this branch with #248 (f7d8c2da) on develop has one conflict, in the declarations of fp_api_get_state: this branch has INTEGER :: nr, nsa, ntg_last, ntg1_last, #248 has INTEGER :: nr, nsa, ntg_last, nr_alloc, nsa_alloc. The union resolves it; the rest of fp/fp_api.f90 and the three documents both branches edit merge cleanly. The reviewed head 92a0163d conflicts in the same line. If #248 goes in first I will merge develop into this branch and take the union.

python/ on this branch: 730 passed, 35 skipped, 1 xpassed with CI's flags; with the mono image the three test_mono_* files and the pipeline tests, 52 passed. develop has moved to a0b58408 (#242, #243) since your review: this branch merges into it without a conflict, and on develop with #231, #232, #233 and #240 merged together python/ gives 831 passed, 35 skipped, 1 xfailed (#243's strict subTest active). The workflow run needs your approval. #244 and #246 noted; nothing here touches the regress mirror or the struct layout.

[HengyuLi-Ozaki-lab]

develop (f41fe5bc) is merged in, 0188c139; the conflict was one line.

#248 and this branch both added names to the INTEGER statement of fp_api_get_state; the merge keeps all of them. The two bodies do not overlap: #248 bounds the copy of the six profiles by the allocated extents, and the global scalars here were already bounded by SIZE(PIT, 1) and SIZE(PIT, 2).

The merge puts two rules side by side in the window between an fp_set_param and the next run: the profiles are still the last run's within the allocated extents (#245, #248), and the seven global scalars read zero, because they are filled from a prepared state only. Nothing tested the second in that window, so 7f1b80df adds python/fplib/tests/test_state_scalars_window.py (8 cases: zero before the first run; the volume and the stored energy after a run and after a run of zero steps; after a set_param of NSAMAX + 1, NRMAX + 1 and NRMAX - 1 the seven are zero while timefp and the profiles are the last run's; the next run fills them again). With the gate changed to "the arrays are allocated" four of the eight fail. The documents that said "zero until the first run" now also say "and again after a set_param until the next run that is made". No code change beyond the merge; the CHANGELOG gets the entry this pull request did not have.

On macOS: 838 passed, 35 skipped with the CI flags.

[k-yoshimi]

Heads-up for the rebase: #246's PR (runtime layout check) is up. Once it lands, fp_state_t has a layout version: FP_STATE_ABI_VERSION is 1 in three places (fp/fp_state.f90 PARAMETER, fp/fp_api.h #define, python/fplib/_ffi.py constant) and libfpapi.so exports fp_state_abi_version() / fp_state_size(). This PR appends seven doubles to the struct, so on rebase it bumps all three to 2, adds a History line in fp_api.h, and fplib/tests/test_ffi.py::TestLibraryLayout plus fp/tests/c_abi/test_negative.c then verify the Fortran type, the header and the ctypes struct agree. No other change needed; the wrapper refuses a stale libfpapi.so with FplibAbiError instead of reading zeros.

[HengyuLi-Ozaki-lab]

develop (963ae3dc) is merged in, 6118f9a6, and the layout version is bumped as you described.

• The merge. Conflicts in CHANGELOG.md and the USE lists of fp/fp_api.f90 (both sides kept). One change that no conflict showed: since fix(tr,fp,ti): re-prep after any registry set, including tot's dispatcher (#253) #259 a set no longer clears g_prepared, so the gate of the seven scalars in fp_api_get_state is now g_prepared .AND. g_prep_generation == fp_param_generation(). With g_prepared alone they no longer read zero after a set, and the window tests fail.
• 1146a444: FP_STATE_ABI_VERSION is 2 in fp/fp_state.f90, fp/fp_api.h (with the History line) and python/fplib/_ffi.py; one test pins version 2 to the seven scalars. The recipe in docs/fp-library/architecture.md said "in both files"; it now names the Python constant as the third place.
• 4db47e34: with the registry counting every set, the zero window opens after fp_set_param_str and tot's fp: parameters too; the documents say so, with one more case (set_param_str("KNAMEQ", ...)).

macOS, clean build: 980 passed, 38 skipped with the CI flags; the mono-image tests of the CI job with MONO_LIB_PATH set, 41 passed (3 need TOTLIB_PATH as well); the header, libfpapi.so and libtotapi_mono.so all report version 2 / 38488 bytes.

[k-yoshimi]

Delta review of 6118f9a6 (merge of develop 963ae3dc) + 1146a444 + 4db47e34, in-house + independent Codex. No HIGH, no MED. Approving the delta; the LOWs below are small enough to fold into one push before the merge.

Verified

• The gate change in the hand resolution is correct: fp_api_run re-preps iff .NOT. g_prepared .OR. g_prep_generation /= fp_param_generation() and records the generation only after a successful fp_prep; fp_api_get_state fills the seven scalars iff g_prepared .AND. g_prep_generation == fp_param_generation(). The two predicates are exact complements, so "scalars non-zero" ⇔ "the next run would not re-prep". Walked all six paths against the code: set after run → zero (profiles kept); set_param_str → same; refused set → no generation bump → unchanged; tot fp: dispatcher (counting fp_param_set) → zero; run again → non-zero; finalize/re-init → closed by g_prepared. A failed fp_param_check returns before the generation, so the window persists.
• Version 2 is in all three runtime-compared places (fp_state.f90:38, fp_api.h:62, _ffi.py:49); no tot/mono copy needs a bump (test_set_after_run.py imports FpStateC). Size 38488 on both sides, seven trailing doubles at 38432..38480.
• CHANGELOG resolution kept both entries intact. The window tests are not vacuous: > 0 before the set, all-zero after, > 0 after the next run; the old IF (g_prepared) would fail them.
• Local: clean build of this branch (macOS, gfortran 15), 273 passed with the CI flags over fplib / totlib / fp_mcp / abi_check (the one failure is Python 3.10's missing ExceptionGroup, pre-existing, CI is 3.11+).

LOW, please fold in

1. python/mcp-servers/fp_mcp/server.py:203-204 names set_param_str in STATE_SCHEMA while :100 still says "fplib has no set_param_str" (false since fplib.py:163) and this branch exposes no such tool (that is #231). Make the file consistent with this branch: either drop the tool name here or say it is fplib-level until #231.
2. docs/fp-library/architecture.md:227 "String parameters not wired" is stale for the same reason.
3. python/fplib/state.py:47-48 and the module docstring of test_state_scalars_window.py:7-9 still say "filled from a prepared state only"; the gate is prepared-and-current-generation. Behaviour sentence is right, mechanism wording is stale.
4. CHANGELOG.md:25 says "since #259", the code comments and develop's own Changed entry say #253 (the issue). Pick one.
5. Coverage, optional: no case pins that a refused set leaves the scalars intact, nor that a tot fp: set zeroes them (test_set_after_run.py checks extents only). Both are correct by construction today; a case each would keep them so.

[HengyuLi-Ozaki-lab]

The five LOW points are in one commit, 372aeaa1:

1. The fp_mcp state schema describes the window with set_param only, since this branch has no set_param_str tool. The module comment at server.py:100 ("fplib has no set_param_str") is left for feat(fp_mcp): expose set_param_str tool for KNAMEQ / MODELG=3 equilibrium load #231, which adds the tool and edits that part of the file; this head and feat(fp_mcp): expose set_param_str tool for KNAMEQ / MODELG=3 equilibrium load #231's merge without a conflict. Whichever of the two merges second should say "or set_param_str" in the schema again: the tool opens the same window.
2. docs/fp-library/architecture.md and the same sentence of the fplib README: "String parameters not wired" now says that fp_set_param_str sets KNAMEQ and the other string keys stay at their defaults.
3. state.py and the docstring of test_state_scalars_window.py describe the gate as it is: prepared, and no parameter set since that preparation.
4. CHANGELOG.md says tot: tr: parameter updates after a run bypass tr_api's prepared flag (no re-prep, no #189 pre-run check) #253, as the code comments do.
5. Both cases: a refused set leaves the scalars as they were; a set of tot's fp: parameters makes them read zero, on the mono image (test_set_after_run.py, TestFpScalarsAfterTotSetOnMonoImage, which checks the return code of both fp_get_state calls, since a failed read also leaves zeros). With the gate on g_prepared alone the mono case fails, along with five of the window cases.

macOS: the whole suite 981 passed, 39 skipped with the CI flags; the mono case passes with MONO_LIB_PATH set. No merge of develop was needed: this head merges cleanly with 4b5463e4.

[k-yoshimi]

Delta review of 372aeaa1 (the five LOW items) through the full review cycle (Codex + in-house domain/test-oracle lenses + docs/workflow review).

Verdict: approve. Every statement the delta adds was checked against the Fortran: the gate is g_prepared .AND. g_prep_generation == fp_param_generation() (fp/fp_api.f90:370), the scalars are zeroed before every early return of fp_get_state, tot's fp: dispatcher calls the counted fp_param_set wrapper, fp_set_param_str accepts KNAMEQ only, and #253 is what the code comments cite. The new mono-image test is the real discriminator: on a g_prepared-only gate it fails, and a tot dispatch that bypassed the counted wrapper would fail it too. It runs in the CI mono job (python-tests.yml runs test_set_after_run.py with MONO_LIB_PATH), green at 372aeaa1. Locally (no mono image here): 732 passed, 287 skipped, 1 known Python 3.10 failure.

LOW, for the same push or #231, your choice:

1. fp_mcp/server.py get_state tool docstring (lines ~578-583) lists the returned keys and omits scalars, the block this PR adds.
2. fp_mcp/README.md §8.4 is the third copy of the "string parameters not wired" sentence the PR corrected in architecture.md and fplib/README.md.
3. The raw-ctypes mono test hands FpStateC to the image with no layout check; assert lib.fp_state_size() == ctypes.sizeof(FpStateC) in _load_image (which _FpReprepCase would share) closes that.

Optional: test_a_refused_set_leaves_the_scalars observes only through the gate it tests; adding fp.run(1) afterwards and asserting timefp doubles (continuation, no re-prep) would prove the counter did not move independently of fp_get_state. The server.py:100 comment stays as you said, for #231.

Pre-existing docs drift found on the way (symbol count "5" in two READMEs and architecture.md while libfpapi.so exports 8, set_param_str missing from the API reference) is filed as #273; not for this PR.

Merge waits for the maintainers' instruction.