Skip to content

Competitive groove occupancy kinetics and evidence corner envelopes - #7

Open
ahrazzle wants to merge 4 commits into
import/foundation-graph-stackfrom
auto/E-competitive-binding-envelopes
Open

ahrazzle wants to merge 4 commits into
import/foundation-graph-stackfrom
auto/E-competitive-binding-envelopes

Conversation

@ahrazzle

@ahrazzle ahrazzle commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Stack: #5 → #6 → #7 → #8 (this PR is layer 3 of 4). Each branch contains the previous layer, so merging in order with merge commits lands the whole stack in one sweep with no conflicts (verified locally: four sequential merges, final tree identical to the #8 tip, 304 tests passing). GitHub retargets each child to main as its parent merges. Please avoid squash- or rebase-merging individual layers, which would strand the child branches' copies of the parent commits.
Stacked on the Foundation-0 integration PR #6 (base branch import/foundation-graph-stack). This brings over the fork's one never-pushed piece of work: competitive two-ligand groove occupancy + deterministic evidence corner envelopes, with its auto-research report at auto-research/2026-11-06-E-competitive-binding-envelopes/report.md. This is its first review anywhere.

  • vh/bridge/occupancy.py: exact Gaddum two-ligand competitive equilibrium; the shared-core identifiability locus (concentration pairs giving identical total occupancy — the CDR2/CDR2L shared 9-mer core case); exact piecewise 2×2 Putzer matrix-exponential propagator for Motulsky–Mahan competitive kinetics, smooth through the equal-rate limit.
  • vh/graph/evidence.py: execute_evidence_envelope + OutputEnvelope — evaluates a registered scalar model at nominal evidence and all 2^d corners of source-reported input intervals, failing closed before any model call if endpoints are missing, don't bracket the estimate, or violate the port contract; classifies decision thresholds as above/below/straddling. Corners are exact bounds only for componentwise-monotonic models, and intervals are never treated as probability distributions (both limits stated in the report).

Validation (re-run on this branch, not just checked-in claims)

  • scripts/validate_competitive_binding_and_envelopes.py: exit 0 — summary verified against three independent authorities: exact rational arithmetic (Fraction, max error 1.11e-16), elementary mass-action ReactionNetwork (exact conservation basis, drift 6.0e-15), DOP853 (≤2.7e-14; reproduces the +0.228 transient competitive overshoot).
  • Full suite: 275 passed, 1 skipped, 1 deselected, 0 failed.

First-review fix (second commit, test-only)

Two envelope tests were written against a ModelRegistry.register(spec, fn) signature that does not exist (the callable lives in the ModelSpec), and one fail-closed case expected a Decimal endpoint to reach the envelope when Uncertainty construction already rejects non-Real endpoints. Tests corrected to the actual API; the implementation is byte-identical to the original commit and needed no changes — the fail-closed behaviour it asserts holds.

Limits

Kinetics assume buffered/excess free ligand per step (ligand-depletion regimes should use ReactionNetwork with explicit free-ligand species). Envelope corners do not bound interior extrema of non-monotonic models.

First review of this branch: two tests called
ModelRegistry.register(spec, fn), but the registry takes the ModelSpec
alone (the callable lives in the spec), and one fail-closed case
expected a Decimal uncertainty endpoint to reach the envelope when
Uncertainty construction already rejects non-Real endpoints. Test-only
changes; the occupancy/envelope implementation is unchanged and its
validator (Fraction / ReactionNetwork / DOP853) passes as checked in.
Comment thread vh/bridge/occupancy.py
tau = 0.5 * (m11 + m22)
half_diff = 0.5 * (m11 - m22)
delta = float(np.sqrt(half_diff * half_diff + m12 * m21))
lam_minus = tau - delta

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Subtracting the eigenvalues' midpoint and spread can freeze dissociation.

Repro: competitive_kinetic_occupancy([0, 10], 1e16, 1, 1, 0, 1, 1, ob0=1) returns B occupancy of 1 at 10 h. With free B concentration zero and B dissociation at 1/h, its equation is exactly dO_B/dt = -O_B. B occupancy should be exp(-10), about 0.0000454.

Here tau - delta rounds to zero. The determinant is already computed as a sum of positive terms, so the slow eigenvalue can be recovered as det / lam_plus. Please add the zero-free-B case with very different rate scales as a regression.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants