Skip to content

Declarative JSON mechanism files as the default interface - #17

Merged
rmrsk merged 7 commits into
mainfrom
json-interface
Oct 21, 2026
Merged

rmrsk merged 7 commits into
mainfrom
json-interface

Conversation

@rmrsk

@rmrsk rmrsk commented Oct 21, 2026 •

Copy link
Copy Markdown
Member

Summary

Closes #16. A mechanism is now a JSON mechanism file, checked strictly when it is loaded and compiled into the interface the solver already uses; it is the documented, default way to describe a gas. Paschen, Pancheshnyi air and two-body air are converted and their Python code removed. Python mechanisms remain the opt-in route for models the format cannot express (RFD).

Background

A mechanism was a Python module exposing the solver's own matrices (get_R, get_B, the row selectors Π, ...), plus a config.py that injected globals before the module ran. Every derivable input was built by hand, configuration keys were checked inconsistently (Paschen's config.py dropped unknown keys silently), a fallback gas mixture was applied silently, and loading someone else's mechanism meant running their code. The Pancheshnyi air scheme took 1555 lines across module, config and shared helpers.

Solution

  • incept1d.expressions — Coefficients are formulas. The string is parsed with ast, every node checked against a whitelist (numbers, names, + - * / **, exp log log10 sqrt abs tanh cos sin min max), and only the checked tree is compiled. No attributes, subscripts, comparisons, conditionals or other calls. Literals are NumPy floats, so 1/0 and overflow give inf instead of raising or hanging.
  • incept1d.declarative — The format ("format": "incept1d-mechanism/1"): parameters, gas, tables, definitions, species (charge, mobility), explicit alpha/eta, reactions (k in SI times the neutral densities the string names), photoionization (absorption model, source reactions × efficiency, coupling per product, cathode yield, optional direction → PHOTON_DIRECTIONS), emission. Row selectors, drift directions and the matrices follow from the file. Load-time checks: unknown keys, unknown or reused names, charge balance, one tracked reactant, declared products, duplicate reactions, mixture in [0,1] summing to 1, a yield for every cation.
  • Configurations — May set exactly the file's parameters (numbers, or file names resolved against the configuration first), label, reaction_multipliers (keyed by reaction string; unknown keys refused) and positive/negative (any parameter, per polarity). Anything else is an error.
  • incept1d.tables — BOLSIG+ output (transport columns by label, rates by 'target type' summed over processes, recorded mixture and temperature) and two-column LXCat tables. A table that records its mixture must match gas to 1e-3; one that does not warns unless the configuration sets it; a run temperature > 20 K from the table's warns.
  • incept1d.zheleznyak — The two-stream Zheleznyak fit moved into the package and cached per group count (load 0.03 s instead of 0.2 s). mechanisms/air/zheleznyak.py stays as the figure's plotting command.
  • incept1d chombo — Exports mechanism files: the file's rate coefficients with multipliers, alpha/N and eta/N from its alpha/eta, the mean energy from its mean_energy variable (refused if absent).
  • Mechanisms — paschen.json (36 lines), air_pancheshnyi.json (96), air_2body.json.
  • Docs — New configuration/mechanisms.rst (the format, block by block, with the rate and photon equations; its complete example is loaded by tests/test_docs.py); overview, configuration files and modifying reactions rewritten with mechanism files first; the Python pages framed as the advanced route; the Paschen and air example pages include the files. Every command in the docs, READMEs, figure Makefile and CLI help names the .json mechanisms.

Design decisions (from the issue discussion)

  • Formulas, not a catalogue of rate forms — one evaluator covers every shipped fit; no conditionals, so it cannot grow into a language.
  • alpha/eta explicit, never derived from the reactions — a model may ionize through a cascade (e + M -> e(low) + e(low) + M+, e(low) -> e) with no single reaction to derive α from; derivation would silently give 0.
  • Own strict format, not chombo-discharge's — both chombo JSON dialects are schema-less (unknown keys ignored) and cannot express two-stream photons, cathode-specific or field-dependent yields, or reaction ids. The reaction grammar follows chombo's; an importer is possible later.
  • Only declared parameters are configurable — the mechanism file is the complete list of what a configuration may change, with defaults.

Evidence

Equivalence with the Python mechanisms, checked before each was removed:

Mechanism Check Largest difference
Paschen R, V, γ, α, A_aug; incept1d pdiv output (3 gases × 30 pd) 0 (bit-identical)
Pancheshnyi A_aug (λ = 0, 1e7), α, η, γ_+, γ_Ψ, every shipped config × both polarities 5e-15
Pancheshnyi test_air A3 inception fields 175.4867 / 116.2765 / 100.711 Td within 1e-5 (the test tolerance)
2body A_aug, α, η, yields, every example_config.json config × both polarities 5.1e-16
chombo export Phelps table, 24 columns, with a multiplier 6e-16

What stays in the suite: Paschen against its closed form (1e-9), the air reference values, strict-loading tests (tests/test_declarative.py), the documented example, and the chombo columns against the mechanism's own R.

Side-effects

  • Configurations are strict. A key that is not a parameter of the mechanism is refused.
  • Mixture assumptions are explicit. databases.json and conservative.json set x_n2 = 0.8, x_o2 = 0.2 for Phelps/Trinity/Biagi, which record no mixture — what air_pancheshnyi.py used for them silently; results unchanged. The default is the 79/21 that lisbon.txt records.
  • 2body reaction renamed O2- + O2 -> e + 2O2 → O2- + M -> e + O2 + M (its rate always used the total density); the multiplier key in example_config.json follows.
  • chombo table units follow the number of neutral partners (s⁻¹ / m³/s / m⁶/s); the Python path's m⁶/s for X + M and m³/s for unimolecular reactions do not occur for mechanism files.
  • Zero-field yield. Formulas have no conditionals, so the air ion yield at E = 0 is γ₀ rather than 0; no inception occurs at zero field.
  • Docs correction. The air page gave eref = 1.7e9 V/m; the code always used 1.7e8.
  • Default label of an unlabelled configuration is "Baseline" for every mechanism file.
  • Mechanism.init_photoionization removed. The wrapper had no callers; a Python mechanism's own config.py can still call its module's function in post_exec_init.

Alternative solutions

  • Reading chombo-discharge JSON directly — rejected for the reasons above; an importer can map a useful subset later.
  • Keeping the Python air mechanisms beside the JSON — two sources for the same physics; removed once equivalence was shown.
  • Deriving α/η when absent — rejected as unsafe (above); a mechanism without them simply cannot use ionization / --streamer-criterion.

PR-review checklist

Mandatory:

  • I have run pre-commit run --all-files (black, flake8, Sphinx) and it passed. All hooks pass; reuse lint fails locally only on an untracked .claude/ checkout that is not part of the repository.
  • I have run the test suite and made sure that it passed. 734 passed, including slow.
  • I have added all relevant user documentation to Sphinx, and make -C docs html builds without warnings. Dummy builder with -W; default figures rebuilt.
  • I have added NumPy-style docstrings to all new public functions and classes.
  • I have added appropriate labels to this PR.
  • I have added/revised proper licensing and copyright information.
  • I have run a PR review using @claude review. Findings addressed in 819727d; see the reply in the thread.

If this PR changes the physics or the numerics:

  • I have cited the corresponding equation label or table in docs/source/theory/ in the commit message or docstring, and updated the theory page if the model itself changed. No model change; the reference cites eq_two_stream, eq_two_stream_directional.
  • I have checked the closed-form limit with mechanisms/air/pancheshnyi/paschen.json and it still reproduces the standard Paschen law. test_air A2, slow suite.
  • I have included before/after inception curves (or equivalent evidence) for a case the change is expected to affect. Equivalence table above.
  • I have confirmed that cases the change is not expected to affect are unchanged. All of them: results are unchanged to round-off.

If this PR adds or modifies a mechanism:

  • I have given the swarm-data source and a literature reference for every rate. Carried over from the Python mechanisms as _ comments and the air docs.
  • I have added a configuration file that reduces the scheme to a limit with a known answer. paschen.json (air), gases.json (Paschen).

🤖 Generated with Claude Code

rmrsk and others added 5 commits October 21, 2026 10:16
…#16)

A mechanism may now be a JSON file (format "incept1d-mechanism/1"),
compiled into the interface the solver uses; load_mechanism dispatches on
.json.  Step 1 of #16: everything the Paschen mechanism needs.

* incept1d.expressions: rate coefficients, mobilities and yields are
  formulas.  The string is parsed with ast and every node checked against a
  whitelist (numbers, names, + - * / **, exp/log/log10/sqrt/abs/tanh/
  min/max) before the checked tree is compiled; literals are NumPy floats,
  so 1/0 and overflow give inf instead of raising or hanging.
* incept1d.declarative: parameters, gas composition, definitions, species
  with charge and mobility, explicit alpha / eta (never derived from the
  reactions: an ionization that runs through a cascade has no single
  reaction to derive it from), reactions with k in SI times the densities
  of the neutral reactants the string names, and ion-induced yields per
  cation.  Row selectors, drift directions and the reaction matrix follow
  from the file.  Every key, name, reaction and charge balance is checked
  when the file is loaded.  A configuration sets parameters by name,
  scales reactions by their string, and overrides parameters per polarity
  ('positive' / 'negative'); unknown keys are errors.
* mechanisms/paschen/paschen.json: the Townsend model.  Its augmented
  matrix equals paschen.py's to round-off (bit-identical on the tested
  grid) and incept1d pdiv gives identical curves for all three gases.
  paschen.py stays until the air mechanisms are converted too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…cheshnyi air (#16)

Step 2 of #16: what the Pancheshnyi air mechanism needs, and the mechanism
itself as mechanisms/air/pancheshnyi/air_pancheshnyi.json.

* incept1d.tables: BOLSIG+ output (section-1 columns by label, A1/A2/...;
  section-2 rates by 'target type', summed over every process of that kind;
  the recorded mixture and gas temperature) and two-column LXCat tables.
  Each column is a variable of the mechanism, interpolated in E/N and held
  at the ends, as before.
* incept1d.zheleznyak: the Zheleznyak absorption function and its two-stream
  fit, moved from mechanisms/air/zheleznyak.py (which keeps the command-line
  plot and re-exports them), with the fit cached per group count; a load is
  now 0.03 s instead of 0.2 s.
* incept1d.declarative:
  - String parameters are files: relative to the mechanism file, or for a
    configuration value to the configuration first, as cross_sections was.
  - A BOLSIG+ table that records its mixture must match 'gas' to 1e-3; one
    that does not warns once unless the configuration sets the mixture; a
    run temperature more than 20 K from the table's warns once.
  - 'photoionization': absorption by a named model (zheleznyak, groups,
    absorber gas), source = named reactions times an efficiency formula,
    coupling per product species, cathode yield, optional direction (gives
    PHOTON_DIRECTIONS).  The source uses the reactions' rates before
    multipliers, as air_pancheshnyi.py did.
  - cos, sin and pi in formulas.
* air_pancheshnyi.json: A_aug equal to air_pancheshnyi.py's to <= 5e-15 for
  every shipped configuration and both polarities, alpha/eta/yields to
  round-off, and the test_air A3 reference values from the JSON mechanism.
* conservative.json, databases.json: the five configurations whose tables
  (phelps, trinity, biagi) record no mixture now set the N2 0.8 / O2 0.2
  that air_pancheshnyi.py used for them silently, so their results are
  unchanged and the assumption is visible.  The JSON default is the 79/21
  that lisbon.txt records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Docs (Configuration chapter):
* configuration/mechanisms.rst (new, Chap:MechanismFiles): the mechanism
  file block by block -- structure, formulas and the names they may use,
  parameters, gas, tables, definitions, species, Townsend coefficients,
  reactions and the rate convention, photoionization, emission -- what is
  checked at load, and when to write a Python mechanism instead.  Its
  complete example is loaded by tests/test_docs.py.
* overview, jsonfiles (configurations: parameters by name, multipliers,
  per-polarity overrides of any parameter, file resolution) and reactions
  rewritten with the mechanism file first; mechanismfile and configpy
  become the Python route, and configpy keeps the load_mechanism
  walk-through the overview had.
* examples/paschen.rst and examples/air.rst include the mechanism files;
  the air page's configuration table follows the JSON parameters (and its
  eref default is corrected to 1.7e8 V/m, the value the code always used).
* Every command in the docs, READMEs, figures Makefile and CLI help names
  the .json mechanisms, except incept1d chombo, which still reads only
  Python mechanisms.

Paschen: paschen.py and its config.py are removed; gases.json sets A, B
and gamma0 per gas; the tests and examples/paschen/closed_form.py write the
closed form out themselves (identical table, solver to 1e-9 as before).

The layout tests accept a directory holding a mechanism file, a Python
mechanism, or both forms of one mechanism; a configuration with no label is
"Baseline", as for the Python air mechanisms; two reactions with the same
string are refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
generate_declarative tabulates a mechanism file in the layout generate
writes for a Python mechanism: the rate coefficients as the file gives
them, times the configuration's multipliers; alpha/N and eta/N from the
file's alpha and eta (not summed from the reactions); the mean energy from
its variable mean_energy.  A file without alpha, eta or mean_energy is
refused rather than given an invented column.  Units follow the number of
neutral partners (s^-1, m^3/s, m^6/s), which also corrects the Python
path's m^6/s for 'X + M' and m^3/s for a unimolecular reaction in the
mechanism-file table.

For a .json mechanism the CLI reads the configuration with
read_json_configs / load_mechanism, as every other command does, and the
header names the file parameters.  DeclarativeMechanism gains a small
read-only interface for this (reaction_strings, mole_fractions, files,
neutral_partners, rate_coefficient, neutral_density_factor, variable).

The Phelps table from air_pancheshnyi.json equals the Python export in all
24 columns to <= 6e-16, with a reaction multiplier applied (K5-K7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mechanisms/air/2body/air_2body.json: the two-body air scheme, with the
quasi-steady-state ratios as definitions and the disabled O3- detachment
kept as a rate of 0 with its candidate formula in a comment.  Its A_aug,
alpha, eta and yields equal air_2body.py's to <= 5.1e-16 for every
configuration of example_config.json and both polarities.  The reaction
'O2- + O2 -> e + 2O2', whose rate used the total density, is now written
'O2- + M -> e + O2 + M', so the string says what the rate does; its
multiplier key in example_config.json follows.

With incept1d chombo reading mechanism files, nothing needs the Python air
code any more: air_pancheshnyi.py, air_2body.py, their config.py files,
air_config.py and bolsig_conditions.py are removed (the mixture and
temperature checks live in incept1d.declarative; their tests move to
test_declarative D15-D15c).  mechanisms/air/zheleznyak.py remains as the
plotting command for the documentation figure.

Tests: the air fixture, test_air, the layout and chombo tests use the
mechanism files; the Python chombo path is tested on a minimal module
written by the test.  The equivalence checks against the deleted Python
mechanisms ran before the deletion and are in the earlier commits' notes;
what stays is the solver against closed forms and the reference values.

Docs and comments that pointed to the Python air module for the
coordinate convention now point to the Python interface page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rmrsk rmrsk added documentation Improvements or additions to documentation enhancement New feature or request labels Oct 21, 2026
@rmrsk

rmrsk commented Oct 21, 2026

Copy link
Copy Markdown
Member Author

@claude review

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Claude finished @rmrsk's task in 57s —— View job


Review of PR #17: declarative JSON mechanism files

I read expressions.py, declarative.py, tables.py and the mechanism.py glue. I did not run the test suite or pre-commit, and I did not read the docs, the chombo export, the JSON mechanisms or the tests. Everything below comes from reading the code.

The design is clean. The expression whitelist is tight: Starred, Attribute, Subscript, Compare and lambdas all fall through to the final raise. Binding literals as NumPy floats closes the 9**9**9 hole. The load-time checks (charge balance, one tracked reactant, mixture sum, a yield for every cation) are what the PR description promises. Nothing below blocks the merge; items 1 and 2 deserve a decision first.

Worth deciding before merge

  1. Multipliers scale R but not the photon source.

    • get_R applies self._multipliers (declarative.py:670).
    • get_C builds the photon source from self._rate(rx, env) with no multiplier (declarative.py:726).
    • If reaction_multipliers targets a reaction listed in photoionization.source.reactions, such as the N2 excitation that emits photons, the ionization-side rate changes and the photon emission does not.
    • That may be intended ("scale the reaction, not the photon yield"), but it is a surprising asymmetry. Either apply the multiplier in get_C or document it in mechanisms.rst.
    • A test that scales a source reaction and checks C would pin whichever behavior you choose.
  2. get_gamma_plus_with silently ignores its arguments (declarative.py:698).

    • The Python path's Mechanism.get_gamma_plus passes gamma0, gamma1, eref and beta.
    • For declarative mechanisms these are dropped without a message.
    • Per-polarity overrides go through resolve(), so this is probably safe today. A None-only guard would turn any future regression into an error instead of a silent no-op.
  3. The photon-group count is fixed at compile time (declarative.py:549-561).

    • Mechanism.init_photoionization(ngroups, cone_angle_deg) only forwards to Python mechanisms (mechanism.py:171). The declarative path takes groups from the file.
    • If a CLI option such as --photon-groups still exists for the Python mechanisms, it is silently ineffective for JSON ones. Please confirm it is either removed or rejected. My grep found no other callers in src/, so this may already be fine.

Smaller points

  1. np.errstate only ignores divide and over (expressions.py:101).

    • (-1)**0.5, 0/0 and inf-inf give nan and emit a RuntimeWarning, once per call, inside the scan loops.
    • Consider invalid="ignore" as well, and document that nan is possible.
    • Alternatively, reject non-finite R entries or rates in get_R so a typo in a formula doesn't turn into a silent no-root result.
  2. Wrong-arity function calls raise TypeError at evaluation time.

    • exp(1,2) or min(1) passes _check and fails at the first call.
    • Because compile() already succeeds, you could cheaply check arity in _check: one argument for the unary functions, two for min and max. The error would then name the file and key.
  3. np.interp clamps outside the table range (declarative.py:644).

    • An E/N scan beyond the BOLSIG+ grid silently uses the end value. For rates this is probably what the Python mechanisms did, but it could hide a table that is too narrow.
    • A one-time warning when EN leaves [x[0], x[-1]] would be cheap.
  4. The gas sum check allows 1e-3 slack without renormalizing (declarative.py:363).

    • Fractions summing to 1.0009 give a slightly wrong N per component. Normalizing, or tightening the tolerance for file-defined mixtures, would avoid the drift.
  5. _WARNED is process-global (declarative.py:92).

    • Tests that assert on the mixture or temperature warnings will pass or fail depending on test order. Check that the tests in test_declarative.py clear it with a fixture or use unique paths.
    • stacklevel=4 also doesn't point anywhere useful for the caller.
  6. tables.py:_read_bolsig will raise a bare IndexError if a transport header lists more labels than the data has columns (data[:, 2 + k]). A TableError with the file name would be friendlier. The same applies when the _rows result is empty.

  7. DeclarativeMechanism._env is a one-slot cache, keyed on (EN, p, T) and returning a shared mutable dict. This is fine with forked workers. Mention in the docstring that it is not thread-safe, since parallel.py could change.

  8. resolve() recompiles the whole mechanism per polarity (declarative.py:800) and re-reads tables from _CACHE. That is cheap, but _multipliers is then overwritten after construction, so the multiplier validation in __init__ never sees the resolved config. It is harmless today. Passing reaction_multipliers through the config would make the object self-consistent.

Docs and housekeeping

  • The checklist item for @claude review can be ticked.
  • The side-effects list is thorough. Please also state in mechanisms.rst that multipliers don't touch photon sources, once item 1 is settled.
  • reuse lint on the new .json files: the PR says REUSE.toml globs cover them. I did not verify this.

Overall: the approach is sound, the equivalence evidence is convincing, and the strictness is a real improvement. Items 1 and 2 are the ones where behavior could silently differ from what a user expects.

* expressions: function arity is checked when a formula is compiled
  (exp/log/... one argument, min/max two), so exp(1, 2) is refused at
  load with its place in the file instead of failing at the first call.
* declarative:
  - Mole fractions must sum to 1 within 1e-9; the 1e-3 tolerance is only
    for matching a table's recorded mixture.
  - get_gamma_plus_with raises if given yields: a mechanism file's yields
    come from its parameters and resolve(), and are never silently
    ignored.
  - resolve() passes the configuration's reaction multipliers through the
    configuration, so the resolved object checks and holds them itself.
  - _env documents its one-slot cache as not thread-safe.
* tables: a BOLSIG+ section with fewer columns than its header names, no
  rows, or ragged rows is a TableError naming the file, not an IndexError.
* mechanism: Mechanism.init_photoionization, which nothing calls any more,
  is removed, with its row in the Python interface table; the
  transport-helper row now names only ElectronMeanEnergy, the one
  incept1d chombo reads.
* Docs: the formula rules state the argument counts, that 0/0 is NaN and
  warned about, and the sum tolerance.
* Tests D22-D27, including one that pins the photon source to the rates
  before multipliers (documented, and what the Python air mechanism did).

Not changed, with reasons in the PR: NaN warnings stay (each is shown once
per location, and E/N = 0 gives NaN as it did before); no warning when E/N
leaves a table (clamping is documented and every root scan leaves the
range); the warning registry is cleared by the tests that need it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rmrsk

rmrsk commented Oct 21, 2026

Copy link
Copy Markdown
Member Author

Thanks for the review. Addressed in 819727d:

# Point Outcome
1 Multipliers vs photon source Kept, now pinned. The source uses the rates before multipliers, as air_pancheshnyi.py did. This was already documented in mechanisms.rst ("K_r is the rate before reaction multipliers") and reactions.rst. Test D24 pins it.
2 get_gamma_plus_with ignores arguments Fixed. It raises TypeError if given yields; per-polarity values come from resolve() (D25).
3 Photon-group count fixed at compile time No CLI option sets it. Mechanism.init_photoionization had no callers left and is removed. ngroups is a parameter, so a configuration sets it.
4 invalid in np.errstate Not changed. NaN warnings point at genuine problems, Python shows each once per location rather than per call, and E/N = 0 gives NaN as the Python mechanisms did. Rejecting non-finite R would break incept1d ionization at U = 0. The docs now say 0/0 is NaN and warned about.
5 Function arity Fixed. Checked at compile time with the place in the file (D22).
6 Warn when E/N leaves a table Not changed. Clamping is documented and matches the Python mechanisms, and every root scan leaves the table range, so the warning would fire on every run.
7 1e-3 slack in the mixture sum Fixed. The fractions must sum to 1 within 1e-9 (D23). The 1e-3 tolerance remains only for matching a table's recorded mixture.
8 Process-global _WARNED The tests that assert on these warnings clear it. The messages name the file, so stacklevel carries no information.
9 Bare IndexError from tables Fixed. A missing, short or ragged section is a TableError naming the file (D27).
10 One-slot cache Documented as not thread-safe; the solver's workers are forked processes.
11 resolve() sets multipliers after construction Fixed. They are passed through the configuration (D26).

REUSE: the CI job "REUSE compliance" passes, and reuse lint locally reports nothing outside the untracked .claude/ folder, so the existing globs cover the new .json files.

All 729 tests pass locally (including slow); pre-commit is clean apart from that .claude/ finding.

🤖 Generated with Claude Code

@rmrsk

rmrsk commented Oct 21, 2026

Copy link
Copy Markdown
Member Author

@claude review — please check the fixes in 819727d against your earlier findings (see the reply above), and anything new they introduce.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Claude finished @rmrsk's task in 28s —— View job


Re-review of 819727d

I read the diff of 819727d against my earlier findings. I did not run the tests or pre-commit, so "verified" below means read in the diff, not executed.

# Your outcome My check
1 Kept and pinned (D24) Agreed. The behaviour is documented, and a test pins it.
2 get_gamma_plus_with raises TypeError Good. The check is is not None on all four arguments, so 0.0 also raises.
3 init_photoionization removed Confirmed. A grep over src, docs, tests and mechanisms finds no remaining references. The comment on PHOTON_DIRECTIONS is updated.
4 Not changed Accepted. The reasons are sound, including E/N = 0 giving NaN as before.
5 Arity checked at compile time Good. node.keywords was already rejected, and *args falls through to the final raise, so the len(node.args) check cannot be bypassed.
6 Not changed Accepted. The warning would fire on every root scan.
7 SUM_TOL = 1e-9 Good. MIXTURE_TOL stays for matching a table's recorded mixture, as stated.
8 Tests clear _WARNED Accepted.
9 TableError for short or ragged tables Mostly fixed. See the first point below.
10 Docstring notes the cache is not thread-safe Good.
11 resolve() passes multipliers through the config Good. The resolved object now validates and holds them itself. This also fixes the old overwrite after construction.

New findings

None block the merge.

  1. The ragged-row error does not name the file.
    • _rows raises rows of unequal length after line N (tables.py:116). It has no path argument, so it is the one case the D27 fix does not cover. The commit message says all three cases name the file.
    • A non-numeric token inside a data row, such as 1.0E+0x, still gives a bare ValueError from float(v) at tables.py:114.
    • The simplest fix is to wrap the two _rows(...) calls (tables.py:159 and :177) in a try/except that re-raises with path. Alternatively, pass path into _rows.
    • Please confirm that D27 covers the ragged case. I only saw it asserting match="bad.txt" for one malformed file.
  2. Removing Mechanism.init_photoionization breaks Python mechanisms that define it.
    • Python mechanisms can still define that function, but nothing calls it now.
    • air_rfd.py was touched in this PR. If it or any user mechanism relied on the hook for its group count, it would now silently keep the default.
    • A grep finds no uses, so this is fine for the shipped files. The removal could be mentioned in the side-effects list.
  3. A TypeError in get_gamma_plus_with could hide a regression.
    • The TypeError is raised only if a caller still passes yields. Mechanism.get_gamma_plus passes gamma0, gamma1, eref and beta, so I checked it in mechanism.py.
    • If Mechanism.get_gamma_plus ever forwards non-None values to a declarative mechanism, every run fails with a TypeError. That is the intended loud failure.
    • Please confirm that a test drives the polarity path end to end, for example pdiv with positive/negative overrides. Equivalence on both polarities is claimed in the PR, and that would cover it.

Everything else in 819727d reads as intended. I found no new problems in the arity check, resolve() or the SUM_TOL change.

* tables: _rows takes the path, so ragged rows and a non-numeric token in a
  data row are TableErrors naming the file and the line, like a short or
  empty section (the previous commit claimed this for all of them; it held
  for two).  D27 now covers all four faults.
* test_paschen_mechanism: a 'negative'-only gamma0 override goes through the
  full solver in both polarities, each matching Paschen's law with its own
  gamma -- the end-to-end polarity check that the comparison with the old
  Python Paschen module used to provide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rmrsk

rmrsk commented Oct 21, 2026

Copy link
Copy Markdown
Member Author

Re-review points, addressed in f6b6e04:

  1. Ragged / non-numeric rows now name the file (and the line, for a non-numeric token): _rows takes the path. You were right that 819727d only covered the short and empty cases. D27 is now parametrised over all four faults (short, ragged, non-numeric, empty), each matching the file name and the fault.
  2. Mechanism.init_photoionization: nothing ever called the wrapper. A Python mechanism's own config.py called the module's function directly in post_exec_init (that is what the removed air_config.py did), and that still works unchanged. Added to the side-effects list.
  3. End-to-end polarity: added TestPolarity in tests/test_paschen_mechanism.py. A negative-only gamma0 override runs through the full solver in both polarities, and each matches Paschen's law with its own γ to 1e-9. This replaces the polarity check that the deleted comparison with the Python Paschen module provided.

734 tests pass locally.

🤖 Generated with Claude Code

@rmrsk
rmrsk merged commit 0254ced into main Oct 21, 2026
7 checks passed
@rmrsk
rmrsk deleted the json-interface branch October 21, 2026 18:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Declarative mechanism files compiled into the solver interface

1 participant