feat(codegen): analytic sensitivity RHS for Functional rate laws (#67)

[wshlavacek]

Closes #67. Stage 3 of #55; follows #65 (PR #80) and #66 (PR #83).

The problem

A single Functional reaction put a whole model on CVODES' internal difference
quotient. CVodeSensInit1 installs one callback for every sensitivity
column, and generate_sens_rhs_c returned None on the first non-Elementary
rate law — so 1.1% of reactions blocked 187 of 585 corpus models (32%).

#66 derived the analytic ∂f/∂p and left it gated off, because the other half of
ySdot = J·yS + ∂f/∂p was still Elementary-only. This supplies that half and
opens the gate.

What it does

J·yS is not a second derivation. It is the same per-species chain rule and
per-observable product rule generate_jacobian_from_model already emits and
validates. Both callers now share one reconstruction,
_functional_jacobian_groups, and differ only in where a contribution lands:

/* analytical Jacobian */   jac[j*N_SPECIES + i] += coeff * dj;
/* sensitivity RHS      */  Jv_out[i]            += (coeff * dj) * v[j];

Both indices are known at emit time, so the matvec fuses into the scatter. No
n×n scratch buffer inside the CVODES callback (267 KiB on atg_model_v2, and
bngsim_codegen_jac memsets it per column per step), O(nnz) instead of O(n²),
and no CodegenSensUserData widening — the alternative §1.3 of the plan costed
out. bngsim_jac_vec takes t/obs/func only when its body reads them, so an
Elementary model's signature and whole emitted source are unchanged.

generate_combined_c falls back to the model-based emitter when the .net one
declines. The .net emitter reads rate laws as text and has no expression to
differentiate; the built model does. This is the path a .net-loaded model
actually takes, so without the hook #67 would have reached only the
SBML/Antimony entry points.

Validation

Byte-identity. generate_jacobian_from_model and generate_sens_from_model
emit byte-identical C on all 585 corpus models, before vs. after the extraction
(both emitters loaded in one process and string-compared).

Corpus.

	before	after
models with an analytic sensitivity RHS	398	535 (+137)
models lost	—	0
gained sources that compile + export the symbol	—	137 / 137

The 50 still declining are Michaelis–Menten and the Functional laws carrying a
condition (#68 owns those) or a non-smooth builtin. Every decline warns and names
what blocked it.

Correctness. Four independent oracles, none circular:

1. Central FD of the emitted bngsim_codegen_rhs in each species, against
   J·yS at unit yS — solver-free, through ctypes, over both reconstruction
   branches (per-observable and per-species).
2. bngsim_jac_vec against the dense bngsim_codegen_jac from the same .so,
   times v in Python. This is what tests the matvec fusion specifically; an FD
   oracle cannot separate a bad fusion from a bad derivative.
3. Re-solved trajectories at p ± h — the only non-circular end-to-end ground
   truth, since the difference quotient is the thing under suspicion.
4. Sampled against the difference quotient on 46 corpus models (every one
   above 100 reactions, plus a random 24): 46/46 agree, median relative
   disagreement 6.1e-08, worst 6.0e-05.

Performance, warm, cost per analytic column in plain-solve equivalents
((t_sens − t_plain) / (k · t_plain)):

model	species	k	analytic	difference quotient	speedup
Zhang2021	150	16	0.59	9.04	13.9×
bcr-signaling	14	16	0.76	36.70	44.5×
RBM_covid_v3	182	16	1.04	28.95	26.3×
IgE_v3	63	4	1.16	6187	4400×
jnk-mapk	21	4	1.06	5124	3904×

#55's claimed 0.75–0.95 band lands at realistic k; at k = 4 the per-column
fixed cost still shows on sub-millisecond solves. The DQ needed a median 295×
more steps across the 46 sampled models, up to 177 060×.

And on 2 of the 6 benchmarked models the difference quotient never converged
at all — it exhausted mxstep and returned a gradient of exactly zero, which
reads downstream as a converged answer. The SIR fixture in the new test file is
one: 30 920 562 DQ steps returning zeros, versus 1 777 analytic steps landing on
the re-solved trajectory to 7 digits. Verified identical on main, so this is a
pre-existing silent-wrong-answer that #67 fixes rather than anything introduced
here.

Downstream

steady_state.cpp reads the same bngsim_codegen_sens_rhs at yS = 0 for the
∂f/∂p factor of dY_ss/dp = -J⁻¹·(∂f/∂p), so a Functional model's
ss.sens_dfdp_source moves "finite-difference" → "codegen" — retiring the
√eps step floor #76 describes, for those models. Checked against a re-solved
steady state (9 significant digits) and pinned by a test.

Notes for review

• BNGSIM_NO_FUNCTIONAL_SENS_RHS=1 restores the previous behaviour for an A/B.
  It is part of the .net codegen cache key and the in-process memo key, so a
  hatched run cannot collide with a .so compiled without it.
• The gate is per model, not per requested parameter set (#55c — enable the analytic sens RHS for condition-free Functional models (140/585) #67's open
  question) — CVodeSensInit1 is all-or-nothing, so there is nothing finer to
  key on.
• No new guard was written. The condition/banned-construct rejection reuses
  unsupported_expr_construct through #55b — analytic df/dp for Functional rate laws (emitted, gated off) #66's _functional_dfdp_terms, so #55d — extend the switch-condition guard so condition-bearing Functional laws can use the analytic sens RHS #68 has
  one place to lift, behind the shared switch-time predicate.
• src/steady_state.cpp is a comment-only change (its "every Functional/MM
  model" claim is now wrong).
• Full Python suite: 2720 passed, 0 failed.

[wshlavacek]

Added a second commit (05e3dc7) that puts test_codegen_functional_dfdp.py and
test_codegen_functional_sens_rhs.py into the MIR job's run list.

Both files already triggered that job — its paths filter is
python/tests/test_codegen*.py — but neither was in the list it actually runs, so
#66's tests and these new ones fired the matrix without ever executing in it, and
the pre-push hook was their only gate. Running them under BNGSIM_CODEGEN_JIT=mir
additionally covers c2mir compiling the newly-emitted Functional ∂f/∂p and J·v,
which no cc-only run does.

One test needed adjusting for that: test_the_analytic_rhs_is_actually_the_one_installed
read model._codegen_so_path, and the JIT path produces a C source string and no
.so. It now accepts either artifact shape.

[wshlavacek]

Reverted the mir.yml commit (c520c4c) — the MIR legs it turned red are a
pre-existing bug on main, not #67.

c2mir rejects bngsim_codegen_output_sens (GH #198), which this branch emits
byte-identically to main (diffed the block). Proven by dispatching the MIR
workflow against a branch off clean main carrying only a Functional model run
with sensitivity_params under the JIT:
run 30290133235 —
1 failed, 155 passed, same error on every leg. Filed as #85 with the reproducer.

Nothing in the MIR job's list reached that combination before: the one Functional
test there pre-sets _codegen_so_path, which makes the Simulator skip
auto-codegen entirely, so the JIT never saw the module. The mir.yml one-liner
therefore belongs with #85's fix, and #85 records it as the follow-up.

Kept from that commit: the JIT-aware assertion in
test_the_analytic_rhs_is_actually_the_one_installed, which is correct against
either artifact shape.

Worth flagging for review: #85 grows in scope once this lands. Today it bites
"Functional model + sensitivity_params + MIR JIT"; after #67 the same module is
emitted for every Functional model that gains an analytic sensitivity RHS. The
.so path (the default) is unaffected — cc compiles the identical source
fine — but if the MIR JIT is a supported production backend for sensitivity runs,
#85 is worth fixing before or alongside this.