fix(gradient): route on what bngsim says it carries, and keep every saved state seeded the same

[wshlavacek]

Closes #864. Closes #992.

Four finite-difference oracle tests in tests/test_gradient_sbml.py pass with bngsim v0.16.0 and fail with bngsim main (c966928). A bisect of bngsim found two merges:

• bngsim On the bngsim backend, a hand-written parameter_scan or bifurcate puts the scanned parameter back afterwards, while BNG2.pl leaves it at the last scanned value, so the same job fits differently on the two backends #941 (issue Multiple shooting (job_type = ms) never runs the user's postprocess script, so it fits and reports the objective of the unprocessed simulation, with no warning #912): a derived parameter's sensitivity column is now its own, where it used to be 0. PyBNF added that column on top of the primary's, which already carries the chain, so gradients came out 2× too large, and about 4× in one case.
• bngsim An invisible character beside a setOption line (a non-breaking space, for example) makes BNG2.pl skip the line while PyBNF applies it #982 (issue fix(tutorial): teach lesson 25's two minima, and check it from three seeds (#703) #704): after save_concentrations(), bngsim's model no longer carries its initial-condition seeds, consistently with holding S(0) fixed. PyBNF overwrites initials and saves, so gradients for S0/I0 came back 0.

In both cases bngsim's columns match central differences of bngsim's own simulation. PyBNF was right on 0.16 by accident, so the fix is PyBNF's. ADR 0153 records the design.

The rule

PyBNF now asks the run model what bngsim does, and assumes nothing, so the same code is right on every bngsim build:

1. Don't write what bngsim already holds: a live derived parameter, or a species initial value equal to bngsim's to 1e-12 relative. This also removes a one-ulp hazard: a write-back one ulp off turned a derived parameter into an override, and the primary's column then dropped to 0.
2. Re-declare initial-condition seeding around every save of a fresh state. The seeding is read just before the save, and declared back after the reset and after every later reset to that state. A scan point reads it off a clean clone, and a multiple-shooting knot is declared as seeded by nothing.
3. Check before every fresh-start sensitivity run that the run model matches what the route assumed, and raise naming the parameter or pair if not. The router drops a seed onto a live derived parameter, and refuses if the backend cannot report liveness.

Also:

• Unit filter: a stale filter that marked amount species in a size≠1 compartment as unseeded is gone. On 0.16.0 it doubled one gradient: 935.9 against an FD value of 461.3.
• Newton scans: a scored .net ss_method => "newton" scan is refused on a bngsim build without fix(tutorial): teach lesson 25's two minima, and check it from three seeds (#703) #704. On those builds its initial-condition column comes back 0, and a one-model probe detects that, since no version string or feature key distinguishes the builds.

Sibling paths

Path	Status
SBML/Antimony time course, conditions, scan points, first pre-equilibration phase	Changed (shared preparation and check). FD test for Antimony added.
SBML pre-equilibrated scan (carried state), measured phase	Doesn't apply: bngsim's carried seeding; species writes there were already refused.
SBML experiments at t = 0 only	Doesn't apply: finite differences of re-prepared models.
.net start-of-run sync, resetConcentrations / saveConcentrations	Changed.
.net scan points; parity and Newton steady-state scans	Changed; Newton refused where unsupported.
.net _run_protocol, threaded steady-state, continuation and bifurcate scans	Doesn't apply: refused on the gradient path, or scalar only.
.net conditions	Covered; FD test added.
Multiple shooting, SBML and .net	Changed: knots are seeded by nothing, and a lane saved into is rebuilt.
Liu–West segment integrator	Doesn't apply: no sensitivities.

Checks

• Independent oracles: the FD tests compare the assembled gradient with central differences of PyBNF's scalar loss, which runs no sensitivity code. Closed forms are also checked: e^{-kt}, kf/(kf+kr), and 0 for a knot.

• New .net oracle for the An invisible character beside a setOption line (a non-breaking space, for example) makes BNG2.pl skip the line while PyBNF applies it #982 sibling: test_net_fd_oracle_seeded_initial_condition_on_the_parameter_axis fails on bngsim main before this change (0.0 against 0.773).

• Tests changed:

  • The bind-by-id and multi-species routes now follow bngsim's liveness answer.
  • The condition-target classify test asserts both answers.
  • The amount-species seed test's route moved to S0's own axis.

• Both bngsim builds, with a separate codegen cache each, give identical counts. The gradient files:

  file	passed
  test_gradient_sbml	25
  test_gradient_routing	72
  test_gradient_assembly	208
  test_gradient_seeding (new)	23
  test_shooting_sbml	18
  test_shooting_net	10
  test_shooting	58

  So do 16 backend files, and the slow and recovery tiers of the gradient and shooting files.

• Not established:

  • bngsim 0.15.x was not run.
  • No performance cost was measured.
  • No real models from the corpus were run (Bertozzi, Raia, Fiedler).

Tested on macOS x86_64 (Intel), Python 3.12. An independent review found two regressions and five older defects; the second commit (54c0258) addresses them (see the comment below), and a re-review of it is in progress.

[wshlavacek]

First independent review, and what 54c0258 changes

The review ran each finding on bngsim main (c966928), v0.16.0 and v0.15.1, against central differences of the scalar loss.

#864 is fixed by this PR on all three builds. The issue's own lbfgs fit now stops at g = 0.19765680 (objective 4.00207942), the issue's independent optimum. On main it stops at 0.19784812, and the pure alias came out 2×. The issue's cases are now tests.

Regressions in the first commit, now fixed:

1. A valid configuration was refused. The SBML run-time check refused a fit where one condition estimates a seed and another pins the species. It now exempts species the evaluation itself wrote, and the case gives [337.0144, 2.33698] against finite differences.
2. A Newton scan could return a silently zero gradient. The refusal missed a conserved species seeded by setConcentration: on 0.16.0 the gradient was 0 against a finite difference of 167.42. It is now decided from the prepared dose point's seed rows intersected with the conservation laws, and that case is refused on 0.16.0.

Older defects, fixed here:

• On the bngsim .net backend, a scored Newton steady-state scan reports every initial-condition sensitivity as exactly zero, so a gradient column routed through a conserved species' initial amount comes back 0 #992: a Newton scan's initial-condition axis for a conserved species is refused on every build. The parity path no longer drops that tensor: it gives 133.444 against a finite difference of 133.442, where it used to fail with a misleading message.
• A stale chain through an overridden derived parameter on 0.15/0.16. Examples: a fitted k2 = 2*k1 gave 1085.38 against a finite difference of 54.53, and a condition, setParameter or pre-equilibration pin was off by 2–30%. A new one-model witness detects the build. Where it fails, a run that overrides a derived parameter the right-hand side reads, and that a requested parameter feeds, is refused. bngsim main passes the witness, and the gradients match.
• The bngsim floor is now >=0.16.0. On 0.15.1, A() 3*A0 is not seeded, so one of this PR's own tests failed: 10.15 against 14.65.
• A relative condition on a derived parameter whose inputs are requested gave a zero column (0 against 601.23). It is now refused at load.
• The new initialAssignment-target refusal was too broad. It now fires only where something re-derives the target. Fitting k_used alone is allowed again: 699.8855 against 699.8854.
• Small fixes:
  • unreachable labelled-snapshot seeding is removed;
  • the nested-chain refusal no longer names a condition that doesn't exist (the chain itself is On the bngsim SBML backend, a free parameter that feeds a chain of parameter initialAssignments (k2 := 2*k1, k3 := k2 + k1) is refused on the gradient path, although bngsim's own column for it is exact #993);
  • string seed entries are hardened.

The reviewer's test file tests/test_gradient_routing_review_oracles.py is included unchanged. All 9 of its tests pass on both builds.

Per the author's runs, 31 gradient and bngsim test files pass on both builds, with identical counts. A re-review of 54c0258 is in progress.

Found along the way and filed separately: #993 and #865 (the scalar-path initialAssignment overwrite, unchanged here).