[HengyuLi-Ozaki-lab]

The first of the three pieces split out of #226, as asked there on 2026-10-13: eq_save with its error reporting, the header and the docstrings, so that the contract ships with the code.

develop has no eq_save yet (it is on #226's branch only), so this pull request brings the feature together with its error reporting rather than the error reporting alone. Reviewing it turned up four more ways in which a save could go wrong without saying so; they are closed here for eq's own entry points and listed below.

What is added

• eq_save() in the C ABI (eq/eq_api.f90, eq/eq_api.h): writes the equilibrium of the last eq_run to the TASK/EQ binary file named by KNAMEQ, through EQSAVE.
• Eq.save(path) in eqlib: sets KNAMEQ, calls eq_save.
• The save tool of eq_mcp (12 tools now).

The file is the one MODELG=3 with KNAMEQ loads, in EQ and in the modules that read an equilibrium file (it is what #231's set_param_str("KNAMEQ", ...) for FP is for).

A save that wrote nothing is an error (#227 item 3)

EQSAVE has an argument now, IERR_OUT: 0 when the file was opened and written, FWOPEN's IERR when it refused the file, 9 when the file was opened and could not be written. It returned silently on a refused open before.

eq_save returns:

Code	When
EQ_ERR_NOT_INIT	before eq_init
EQ_ERR_INVALID, no file touched	the fields do not hold the equilibrium of the present parameters (no successful eq_run since eq_init, a later solve or load that failed, or eq_set_param of anything but MODEFR and MODEFW since); a blank KNAMEQ; MODEFW other than 0 or 3
EQ_ERR_CALC_FAILED	EQSAVE could not open the file (a directory that is missing or not writable; MODEFW=3 and an existing file) or not write it (an existing file without write permission); or no non-empty file exists afterwards
EQ_OK	this call wrote the file

Looking for the file alone is not enough: a save to a path that already holds an earlier file would pass for a success (the repeat-save case of the 2026-07-26 exchange).

Four things beyond that exchange, each measured before it was changed:

• An existing file without write permission ended the process. FWOPEN opens an existing file with STATUS='OLD' and no ACTION, so gfortran opens a read-only file for reading and FWOPEN returns 0; the first WRITE of EQSAVE then stopped the program (Fortran runtime error: Cannot write to file opened for READ, exit status 2). That WRITE has an IOSTAT now and the case is IERR_OUT = 9.

• MODEFW 1, 2 and 4 to 7 can read unit 5. With 1 or 2 FWOPEN asks Y/N before it overwrites an existing file, with 4 to 7 it asks for the file name. Unit 5 of a stdio server is the JSON-RPC pipe: measured with MODEFW=4, the save returned success, left the named file as it was and wrote a file called after the next JSON-RPC line. eq_save takes 0 (overwrite) and 3 (refuse an existing file) only. eq_mcp described MODEFR and MODEFW to its clients as "frequency-space mode switch" and "wave-frequency mode switch"; they are the file modes of FROPEN and FWOPEN and say so now.

• A save of something that is not an equilibrium. Before any run, a save returned success and wrote 45956 bytes that stop the process that loads them (XX setup_psig: SPL2D ERROR, then the STOP of eq/eqsub.f90). After a grid count raised following a run (NRGMAX and NZGMAX to 65) it wrote 96644 bytes that end the loading process the same way, since EQSAVE writes the counts as they stand over fields computed for the old ones. After a run that failed following a good one it wrote whatever the failed iteration had left, and returned success. eq_save therefore keeps a flag, set by a successful eq_run and cleared when an eq_run starts and by eq_set_param of anything but the two file modes, and refuses to save without it. This is stricter than Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226's eq_save; say if you would rather have only the first case.

• eq_run(1) reported a failed load as a success, or not at all. The check above rests on the run's return code. EQ_READ called EQCALQ after EQDSKR had failed and handed back EQCALQ's code, and left IERR unassigned for a MODELG that is no file format: on develop, in a build with run-time checks, the load of a missing EQDSK file (MODELG=5) ends the process at a STOP with exit status 0. EQ_READ now starts from IERR=0, calls EQCALQ only after a successful EQDSKR, and returns 1 for an unknown MODELG: three lines, the same ones the downstream product line has carried since September.

In eqlib: Eq.save takes a str or an os.PathLike; it refuses, with EqlibInvalidParamError, a path longer than the 80 bytes of KNAMEQ and a path that ends in a blank (Fortran drops the blank: save("result ") wrote result).

The other call sites of EQSAVE pass a variable: the S command of the eq menu (a read-only target no longer ends the program there either), and tr/f77/trfile.f, a file no Makefile builds, whose CALL EQSAVE(4) fitted neither the old routine nor the new one.

Tests

• python/eqlib/tests/test_save.py, 20 cases in a temporary directory with relative names (KNAMEQ holds 80 characters): the saved file loads back with MODELG=3 and gives the grids and the two profiles it was saved with, exactly, and five scalars that are recomputed after the load, to 1e-9; a pathlib path and something that is no path; no run yet; a run that failed after a good one; a failed EQDSK load after a good run and a changed parameter; a parameter set after the run; the file modes set after the run; a missing directory; a blank path; 80 bytes taken and 81 refused; a path ending in a blank; a repeat save refused by MODEFW=3; a read-only file; MODEFW 1, 2, 4, 5, 6, 7.

• python/eqlib/tests/test_load_errors.py, 3: the load of a missing file with MODELG 3 and 5, and with a MODELG that is no file format, is EqlibCalculationFailedError. Against develop's library the MODELG=5 case does not fail: it ends its process at the STOP (and under --forked the session with it); the MODELG=2 case passes there on this machine, where the unassigned code happened to be nonzero.

• python/mcp-servers/eq_mcp/tests/test_save_tool.py, 6: the handler, the two error mappings, the tool list, one sequence through the real library, the two descriptions.

• eq/tests/c_abi/test_negative.c: eq_save before eq_init. make -C eq eq_api_check_all does not link in a build without the graphics library (on develop neither, and CI does not run it); built against libeqapi.so directly, the test passes.

• With a fault put in and the library rebuilt:

  Fault	Tests that fail
  eq_save ignores EQSAVE's argument	the repeat save, the read-only file
  EQSAVE's first WRITE without IOSTAT	the read-only file
  no MODEFW check	the six MODEFW cases
  no check for an equilibrium	"no run yet", the sequence through the real library
  the flag not cleared when a run starts	"a run that failed"
  the flag not cleared by a setter	"a parameter set after the run"
  the flag cleared by the file modes too	"the file modes set after the run", the repeat save

• One real stdio session (initialize, init, save, run(mode=0), save, save into a missing directory): "invalid parameter: eq_save: rc=1" and no file before the run; a 45956-byte file after it; "calculation failed: eq_save: rc=3" for the missing directory.

python/ with CI's flags, macOS arm64, gfortran 15: 802 passed, 35 skipped, 1 xfailed (develop a0b58408: 773 passed). The 35 skips are the 19 Linux-only equivalence tests, 13 that need the mono image or TOTLIB_PATH, and 3 without a ti fixture; with the mono image, the three test_mono_* files, python/eqlib and eq_mcp: 130 passed, 2 skipped. Linux CI is the measurement of the equivalence tests. On the solver's side the change is EQSAVE's argument, the IOSTAT of its first WRITE and the three lines of EQ_READ, none of which a successful run reaches differently; the flag lives in eq_api.f90. Measured against develop: the state after a run is bit-identical for the two EQ fixtures that load a file and the analytic default (512 values each), and for tr_tst2, tr_iter01, tr_m0904, the TR defaults and a current ramp.

Not changed, and known

• EQSAVE writes PSI, DELPSI and HJT as (NSG,NTG) blocks where the arrays are (NTG,NSG) and the reader reads them so: the same bytes when NSGMAX = NTGMAX (the default, 32 and 32), transposed extents otherwise. S. Terasaki reported it on Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226. It is older than this change, and a fix alters the file for unequal grids, so I left it for its own pull request; say if you would rather have it here.
• Only the first WRITE of EQSAVE has an IOSTAT. A failure later in the file (a full disk) still ends the program.
• MODEFR=1 makes the load path ask for a file name on unit 5 in the same way. Not touched.
• The flag is eq_api's own: set by eq_run, cleared by eq_run and eq_set_param. An equilibrium that another module computes through EQ inside the mono image does not set it, and a parameter changed by another route does not clear it: tot's eq: names call the registry directly, and in the mono image the other modules' setters write the shared plcomm (measured there: eq_run(0), tot_set_param("eq:NRGMAX", 65), eq_save returns EQ_OK). Moving the mark into eq_param_registry would cover tot's route; say if you want that here.
• EQ_READ has other callers: eq_load (tr, fp, wr, wrx), EQLOAD (ob, wm, wmx) and the L and K commands of the eq menu. tr, fp, wr, wrx, wm and wmx ask for MODELG 3, 5 or 8, where a successful load is as before (K sets MODELG=5 itself). The L command passes on whatever MODELG is set (2 as 3), and ob/obprep.f90 calls it for any: for a MODELG that is no file format they now get IERR=1.
• Unit 6. Without the stdio isolation of the companion pull request (fix(mcp): eq_mcp, tr_mcp and tot_mcp keep Fortran output off the JSON-RPC pipe #257), EQSAVE's messages reach the JSON-RPC pipe like the rest of EQ's output (5 of the 11 stdout lines of the session above are not JSON-RPC).
• get_psi_rz, the other tool of the same group of Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226, is not here. It can follow as a fourth piece or stay with Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226, as you prefer.

Scope

Based on develop (a0b58408). It merges with the companion pull request for the stdio isolation (#257), with #231, #232, #233 and #240, without a conflict (trial merge of all of them together); it shares python/mcp-servers/eq_mcp/server.py with the companion and python/eqlib/_ffi.py with #240, in different hunks. #226 will take develop's version of these files when it is brought up to date.

🤖 Generated with Claude Code

[k-yoshimi]

Review of 411971c (in-house + two independent Codex passes, plus a local build and test run; details at the end). The C ABI, the Python wrapper, the MCP tool, the doc sync and the test coverage are clean and consistent, and the EQ_READ fix is correct. Two things before merge, the rest are suggestions.

Before merge

1. EQSAVE still aborts on every record after the first (eq/eqfile.f90:49 is the only WRITE(21,IOSTAT=…); the ~30 WRITE(21) at :56-84 and the CLOSE(21) have no IOSTAT/ERR). ENOSPC, quota or EIO mid-file is a gfortran runtime error that ends the host process (pytest, the MCP server) and leaves a truncated file that EQRTSK's unguarded READs choke on later. The CHANGELOG, README and the eq_api.h text promise "an error return, not the end of the process"; today that holds for the EACCES-on-first-record case only. The least invasive shape is one ERR= label on every WRITE(21…) and the CLOSE that does CLOSE(21) + IERR_OUT=9 (or IOSTAT=IST on each with the same check). A /dev/full test (skip when absent) would pin it.

2. Keep the zero-argument EQSAVE as a compatibility entry. eqfile.f90, eqmenu.f90 and tr/f77/trfile.f are upstream TASK Fortran, and the fork rule is that changes to the eq/tr Fortran body go to the lead for sign-off; the C ABI, wrappers, registries, tests and docs do not. If the status-returning routine gets its own name (say EQSAVE_IERR(IERR_OUT)) and the old SUBROUTINE EQSAVE becomes a two-line wrapper that calls it and drops the code, eqmenu.f90 and trfile.f stay untouched and the upstream-visible diff shrinks to one file (plus the EQ_READ change, which is a genuine bug fix and should be shown to the lead either way). I will raise the sign-off question with @k-yoshimi; this item makes that conversation smaller.

Suggestions (not blocking; say which you take, the rest I will track)

• g_has_equilibrium is bypassed by sibling modules in the mono image (libtotapi_mono.so, MONO_LIB_PATH): tot's eq: namespace calls eq_param_set / eq_param_set_str directly (tot/tot_param_registry.f90:150, :223), tr_init / fp_init / ti_init call eq_init (tr/tr_api.f90:94, fp/fp_api.f90:102, ti/ti_api.f90:106), and the tr/fp run paths call eq_load / eq_calc (tr/trmetric.f90:41,55, tr/trloop.f90:80, fp/fpprep.f90:66). After any of these the flag is still .TRUE. and eq_save writes whatever the fields hold. Standalone libeqapi.so is not affected. This is the same design class as #253 (tot's tr: setter bypassing tr's prepared flag), so I would be content with one sentence in eq_api.h and the README ("the flag tracks the eq_api entry points; in the mono image sibling modules can change the equilibrium without clearing it") and I will widen #253 to cover eq. If you prefer to fix it here, an invalidation hook that the registry setters call is the natural place.
• Mono image: eq_save is refused after tot_init until MODEFW is set to 0. tot_api_init ends in pl_init, which sets MODEFW=5 (pl/plinit.f90:461); only eq_init sets it to 0 (eq/eqinit.f90:368). It fails safe (no unit-5 read), but worth a line in the docs.
• MCP save overwrites any writable path by default (MODEFW=0). For an agent-facing tool an overwrite: bool = False argument that maps to MODEFW=3 unless set would be a safer default. Design preference, your call.
• Eq.save sets KNAMEQ before the precondition check (python/eqlib/eqlib.py:341), so after EQ_ERR_INVALID the parameter state has changed even though the filesystem has not (a later run(1) loads from the new path). Restore it on failure, or say so in the docstring.
• bytes paths and non-ASCII paths both end as EqlibInvalidParamError from _encode_name (the docstring says TypeError for non-str/non-PathLike, and does not mention the ASCII limit). State the restriction or os.fsdecode deliberately.
• eq_api_set_param_str never clears the flag. That is right for KNAMEQ (it is the save target, and run(1) sets the flag itself after a successful load); a comment saying that none of the KNAM* strings feeds the solve would make the asymmetry intentional rather than accidental.
• Stale text next to the edit: eq/eq_api.h:19-20 still says eq_run(0) returns EQ_ERR_NOT_IMPL pending L-4; docs/sphinx/modules/eq/{en,ja}/parameters.md still lists MODEFR/MODEFW as "(internal)" while server.py now documents them as the FROPEN/FWOPEN modes that save depends on.
• python/eqlib/tests/test_eqlib.py:198: eq.save("/tmp/eq.bin") is a dead path (the closed-handle check raises first); a relative name avoids the /tmp literal.

Verified OK

• Only eq/Makefile compiles eqfile.f90; the two updated call sites are the only EQSAVE callers (case-insensitive grep), and nothing builds tr/f77/, so the CHANGELOG sentence holds.
• Implicit typing of IERR_OUT/IST/IERR is INTEGER; unit 21 is closed on every failure path that exists today; MODEFW ∈ {0,3} matches FWOPEN (MOD(MODEP,4) ∈ {1,2} or MODEP ≥ 4 read unit 5); INQUIRE SIZE=-1 is caught by <= 0.
• EQ_READ: EQDSKR returns FROPEN's 7 on a missing file and used to be overwritten by EQCALQ; the new order is right and eq_load already checks the code before eq_bpsd_init/eqcalq.
• All "11 → 12" tool counts updated; "six + eq_validate + eq_save" (design.md) and "eight" (eq_api.f90 header) agree; api-reference.md autoclass picks up save.
• Local: fresh clone of this branch + unbuilt bpsd clone, make -C eq libeqapi.so → OK; EQLIB_PATH=… pytest python/eqlib/tests/{test_save,test_load_errors,test_eqlib}.py python/mcp-servers/eq_mcp/tests/{test_save_tool,test_server}.py --forked --timeout=120 --timeout-method=signal → 88 passed (macOS, gfortran).

[HengyuLi-Ozaki-lab]

Both items are in, in one commit on 411971c7 (ae6463f5). Of the suggestions, seven are taken and one is not, with the measurement that speaks against it.

1. The writes after the first. Every WRITE(21…) after the first and the CLOSE carry ERR=, as you proposed. That alone did not make eq_save report the failure, so there is a second check; the reason is what a refused write does here. Measured with a file size limit in a child process (macOS, gfortran 15, -O0, the library loaded by Python, SIGXFSZ ignored so that write() returns EFBIG):

what is written	result
a test routine, one 160 kB record in one transfer	a plain WRITE ends the process ("Fortran runtime error: File too large"); with IOSTAT= the error is returned. This is the case you describe
a test routine, records of 16 kB	IOSTAT is 0 on every WRITE, on FLUSH and on CLOSE; the file is short
EQSAVE, limits of 16, 1024, 4096 and 20000 bytes, over nothing, an empty file and files of 8, 3000 and 45956 bytes (20 cases)	in 17 no statement reports anything and the file has the limit's length, of 45956 bytes written; in the three with the 16-byte limit over a file that is not empty, the first WRITE returns IOSTAT 27

So on 411971c7 a save to a new file under a limit did not end the process: eq_save returned EQ_OK and left a file of 16, 1024, 4096 or 20000 bytes. EQSAVE_IERR therefore also compares the length written to the unit (INQUIRE(UNIT=21, SIZE=) before the CLOSE) with the length of the file after it (INQUIRE(FILE=, SIZE=)), and returns 9 when the file is shorter; all 20 cases above are now an error. For a regular file that was written the two lengths are equal, also when a longer or a shorter file is overwritten (checked: no false alarm), and when either cannot be had the comparison is left out. The name is asked of the unit, since with MODEFW 4 to 7 FWOPEN opens the name it read and not KNAMEQ. A device has length 0 and is reported short as well.

The /dev/full test is there and skips where the device does not exist, which is here: its first run is this push's CI. Not measured: a full disk, and anything on Linux.

What is at the path after such a 9 is left there (it may name a device; deleting it is not this routine's decision), and the header, the docstring and the README say that it cannot be taken for the equilibrium and must not be loaded: run(1) with MODELG=3 on a file cut at 4096 bytes ends the process in EQRTSK. Those are the unguarded reads I asked about on #231; they are not touched here. In these measurements a save that leaves a short file also leaves one descriptor open.

2. EQSAVE keeps its entry. EQSAVE is argument-less again and calls EQSAVE_IERR(IERR_OUT), which eq_save calls directly. eq/eqmenu.f90 and tr/f77/trfile.f are as on develop, so the upstream Fortran this pull request touches is eq/eqfile.f90: the new routine with its checks, and the EQ_READ order from before. A test calls eqsave_ and compares its file with eq_save's.

Suggestions.

• The flag and the mono image: the sentence is in eq_api.h and the README (the flag is what eq_api's own entry points saw; in the mono image sibling modules can change the equilibrium without clearing it), with your examples. No hook here; tot: tr: parameter updates after a run bypass tr_api's prepared flag (no re-prep, no #189 pre-run check) #253 can cover it.
• eq_save refused after tot_init until MODEFW is 0: not taken, because I could not reproduce it. In the mono image of this branch MODEFW is 0 after tot_init, and eq_run(0) followed by eq_save writes the file (rc 0): the last init of tot_api_init is wr_api_init (wrx/wrx_api.f90:129-130), which calls EQINIT right after pl_init, and EQINIT sets it to 0. If you saw the refusal in a run, tell me the build and I will add the line.
• overwrite: taken, default false. The tool refuses an existing file with a message that names the argument (for a path that is not a regular file, one that says that) and changes nothing; when it saves it sets MODEFW itself, 3 or 0, so FWOPEN's own refusal still holds when a file appears between the tool's look and the open (a test).
• KNAMEQ set before the check: said in the docstring. eqlib has no getter to restore it from.
• bytes and non-ASCII paths: the docstring states both restrictions; two tests (refused, nothing touched).
• eq_api_set_param_str and the flag: the comment is there.
• Stale text: eq_api.h no longer says eq_run(0) is not implemented; MODEFR and MODEFW are described in parameters.md (en, ja).
• The /tmp literal: a relative name.

Measured. The present tests on the Fortran of 411971c7: 4 fail of 36 (the two refused-write cases, because the save reports success; the two that call EQSAVE without an argument, because the process ends). On this commit, after a clean build on macOS: 811 passed, 36 skipped, 1 xfailed with the CI flags; the EQ and TR states of the baseline cases are bit-identical to 411971c7's.

[k-yoshimi]

One more input for the g_has_equilibrium precondition, from #259 (the #253 fix, now up for review): tr / fp / ti's registries now count every successful set (<mod>_param_generation(), private counter advanced by the public *_param_set wrappers), and the API modules compare the count they saw at their last prep instead of clearing a flag in the setter. If eq_param_registry gets the same five lines, eq_api_run can snapshot eq_param_generation() after a successful solve / load and eq_save can refuse when the current count differs, which closes tot's eq: dispatch bypass (tot/tot_param_registry.f90:150, :223) without any hook in tot, and makes the MODEFR / MODEFW exemption a one-line comparison tweak (snapshot after setting those two, or exclude them in the registry wrapper). It would replace the clear in eq_api_set_param, not add to it. The sibling-module paths (eq_init from tr/fp/ti init, eq_load / eq_calc from trmetric / fpprep) stay out of reach of any registry mechanism; they are now tracked in #260, so a sentence in the docs is enough for them here.

[k-yoshimi]

Re-review of ae6463f (in-house + Codex on the delta, plus a fresh-clone build and the eq test suites locally: make -C eq libeqapi.so from a bare checkout → OK; pytest python/eqlib/tests python/mcp-servers/eq_mcp/tests --forked --timeout=120 --timeout-method=signal → 125 passed, 3 skipped on macOS).

Both items are in as asked and verified: every WRITE(21) after the first and the CLOSE carry ERR=, label 900 closes the unit, unit 21 is closed on every path; the length comparison is strictly "file shorter than what the unit wrote", so on a runtime that reports the on-disk size it degrades to a no-op and cannot false-fail; EQSAVE is argument-less again and eq/eqmenu.f90 / tr/f77/trfile.f are identical to develop; EQ_READ is unchanged from the first round. Your MODEFW-after-tot_init rebuttal is right: the last init in tot_api_init is wr_api_init, which calls EQINIT after pl_init, so MODEFW is 0 there; my note came from reading the init list without the wr step. Thanks for taking the other seven.

Approving. Notes for a follow-up or a later commit, none blocking:

• handle_save sets MODEFW to 3 / 0 and leaves it there; one clause in the tool docstring that the value persists would do.
• The descriptor that a short-file save leaves open (your measurement, now in the docstring) is libgfortran's, not something EQSAVE_IERR can release; recorded as a documented limit.
• eq/eqfile.f90 comment: one sentence that the size comparison's usefulness depends on the runtime reporting the unit's written length (another runtime makes it a no-op, not a failure) would save a future reader a measurement.
• test_save.py assert getsize == limit assumes one flush at CLOSE (default 128 KiB buffer); <= limit also holds under GFORTRAN_UNFORMATTED_BUFFER_SIZE overrides.
• _encode_name's docstring says 79 bytes where the constant, the README and the test say 80; pre-existing on develop, not this PR.

For the maintainer: this PR changes eq/eqfile.f90 (new EQSAVE_IERR, EQ_READ error order), which is upstream eq Fortran; the lead should see it, before or after merge per our rule.