Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions auto-research/2026-11-06-E-competitive-binding-envelopes/report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Auto-Research Experiment `2026-11-06-E-competitive-binding-envelopes`: Competitive Two-Ligand Groove Occupancy, Shared-Core Non-Identifiability, and Deterministic Evidence Corner Envelopes

## Question

When two ligands compete for a shared receptor or MHC class II groove (for example, paralogous CDR2L and CDR2 peptides sharing an interior 9-mer binding core as established in `project-asma` assay `18456218`), how do we:
1. Compute exact competitive equilibrium and transient Motulsky-Mahan competitive binding kinetics without single-ligand approximations?
2. Characterize the exact concentration locus across which two cross-reactive ligands produce an indistinguishable bulk groove-occupancy readout?
3. Evaluate how source-reported parameter intervals (`Uncertainty.low`, `Uncertainty.high`) propagate across the $2^d$ corners of an evidence-bound model to detect when an output conclusion straddles a decision threshold, without silently treating interval metadata as a probability distribution?

## Implementation

1. **`vh/bridge/occupancy.py`**:
- `competitive_equilibrium_occupancy(cu_a_nm, kd_a_nm, cu_b_nm, kd_b_nm)`: exact Gaddum two-ligand competitive binding equilibrium returning `occupancy_a`, `occupancy_b`, `occupancy_total`, and `free_receptor_fraction`.
- `shared_core_identifiability_locus(target_total_occupancy, kd_a_nm, kd_b_nm, cu_a_nm)`: solves the affine equivalence locus $C_A / K_{d,A} + C_B / K_{d,B} = O_{\text{total}} / (1 - O_{\text{total}})$ for the concentration $C_B$ that yields identical total groove occupancy alongside $C_A$.
- `competitive_kinetic_occupancy(...)`: exact piecewise $2 \times 2$ Putzer matrix-exponential propagator for coupled Motulsky-Mahan competitive kinetics, bounded in $(0, 1]$ for all $\Delta t \ge 0$ and smooth across the $\Delta \to 0$ equal-rate limit.
2. **`vh/graph/evidence.py`**:
- `OutputEnvelope` and `execute_evidence_envelope(registry, edge, evidence, specs, *, allow_synthetic=False, thresholds=None)`: fail-closed validation that every bound input carries explicit `[low, high]` endpoints bracketing `estimate.value` (`low <= estimate.value <= high`) and satisfying `PortSpec` bounds before invoking the registered model at the nominal point and all $2^d$ distinct interval corners, classifying any supplied output decision threshold as `"above_across_envelope"`, `"below_across_envelope"`, or `"straddles_threshold"`.

## Three-Authority Validation (`scripts/validate_competitive_binding_and_envelopes.py`)

| Validation authority | Scope checked | Quantitative result |
| --- | --- | --- |
| **Authority 1: Exact rational arithmetic (`fractions.Fraction`)** | Three competitive equilibrium cases, five shared-core equivalence pairs at $O_{\text{total}} = 3/4$, and 8-corner ($2^3$) competitive evidence envelope bounds (`3/15` to `24/27` for $O_A$; `5/9` lower bound for $O_{\text{total}}$) | Maximum absolute error **$1.11 \times 10^{-16}$** (1 float ulp; **$0.0$** on rational-denominator cases and locus pairs) |
| **Authority 2: Elementary mass-action network (`vh.graph.reactions.ReactionNetwork`)** | Three-species elementary competitive network (`R`, `RL_A`, `RL_B`) with exact rational left-nullspace conservation basis and RK4 trajectory (`dt = 0.001 h`) | Exact rational conservation basis `R + RL_A + RL_B = 1` (per-reaction residual `0`); max conservation drift **$6.00 \times 10^{-15}$**; trajectory agreement vs. Putzer propagator **$7.83 \times 10^{-12}$** |
| **Authority 3: Adaptive 8th-order Runge-Kutta (`scipy.integrate.solve_ivp` `DOP853`)** | 301-point transient competitive overshoot trajectory ($C_A = 30\text{ nM}, K_{d,A} = 10\text{ nM}, k_{\text{off},A} = 0.2\text{ h}^{-1}$ vs. fast competitor $C_B = 40\text{ nM}, K_{d,B} = 40\text{ nM}, k_{\text{off},B} = 4.0\text{ h}^{-1}$) | Max absolute error **$1.98 \times 10^{-15}$** ($O_A$) and **$2.69 \times 10^{-14}$** ($O_B$); fast competitor $B$ peaks at **$0.4280$** ($t = 0.40\text{ h}$) before decaying to its **$0.2000$** equilibrium (**$+0.2280$** kinetic overshoot) |

## Reproduce

```sh
python3 scripts/validate_competitive_binding_and_envelopes.py
python3 scripts/validate_evidence_bindings.py
pytest -q -m "not network"
node web/test_engines.mjs
```

## Limits

- `execute_evidence_envelope` evaluates the $2^d$ corners of source-reported input intervals; it is exact for componentwise monotonic functions on the hyperrectangle (such as Gaddum competitive occupancy with respect to each concentration and dissociation constant), does not bound interior extrema of non-monotonic functions, and does not assign probability mass to the interval.
- `competitive_kinetic_occupancy` assumes excess/buffered free ligand concentrations on each step interval $[t_{i-1}, t_i]$; when receptor concentration is comparable to total ligand concentration (ligand depletion), use `vh.graph.reactions.ReactionNetwork` with explicit free-ligand species instead.
108 changes: 108 additions & 0 deletions auto-research/2026-11-06-E-competitive-binding-envelopes/summary.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
{
"evidence_corner_envelope_validation": {
"evaluated_corners": 8,
"fail_closed_rejections_verified": 3,
"occ_a_envelope": [
0.2,
0.8888888888888888
],
"occ_a_exact_rational_envelope": [
"3/15",
"24/27"
],
"occ_a_nominal": 0.6,
"occ_a_threshold_0_50_status": "straddles_threshold",
"occ_total_envelope": [
0.5555555555555556,
0.9333333333333333
],
"occ_total_exact_rational_low": "5/9",
"occ_total_threshold_0_40_status": "above_across_envelope"
},
"experiment": "2026-11-06-E-competitive-binding-envelopes",
"max_equilibrium_abs_error": 1.1102230246251565e-16,
"motulsky_mahan_kinetics_validation": {
"equilibrium_occupancy_b": 0.2,
"grid_points": 301,
"max_abs_error_vs_dop853_occupancy_a": 1.9845236565174673e-15,
"max_abs_error_vs_dop853_occupancy_b": 2.6867397195928788e-14,
"overshoot_amplitude_b": 0.22802786902750533,
"reaction_network_conservation_basis": [
[
1,
1,
1
]
],
"reaction_network_max_conservation_drift": 5.995204332975845e-15,
"reaction_network_trajectory_max_abs_error": 7.82610781735471e-12,
"transient_peak_occupancy_b": 0.42802786902750534,
"transient_peak_time_h": 0.4
},
"rational_equilibrium_cases": [
{
"case": "balanced_competition",
"max_abs_error": 0.0,
"occupancy_a_exact": "3/5",
"occupancy_b_exact": "1/5",
"occupancy_total_exact": "4/5"
},
{
"case": "high_affinity_dominance",
"max_abs_error": 0.0,
"occupancy_a_exact": "5/8",
"occupancy_b_exact": "1/4",
"occupancy_total_exact": "7/8"
},
{
"case": "low_occupancy_tail",
"max_abs_error": 1.1102230246251565e-16,
"occupancy_a_exact": "1/23",
"occupancy_b_exact": "2/23",
"occupancy_total_exact": "3/23"
}
],
"shared_core_identifiability_locus": {
"equivalent_pairs": [
{
"cu_a_nm": 0.0,
"cu_b_nm": 75.0,
"occupancy_a": 0.0,
"occupancy_b": 0.75,
"occupancy_total": 0.75
},
{
"cu_a_nm": 5.0,
"cu_b_nm": 62.5,
"occupancy_a": 0.125,
"occupancy_b": 0.625,
"occupancy_total": 0.75
},
{
"cu_a_nm": 12.5,
"cu_b_nm": 43.75,
"occupancy_a": 0.3125,
"occupancy_b": 0.4375,
"occupancy_total": 0.75
},
{
"cu_a_nm": 20.0,
"cu_b_nm": 25.0,
"occupancy_a": 0.5,
"occupancy_b": 0.25,
"occupancy_total": 0.75
},
{
"cu_a_nm": 30.0,
"cu_b_nm": 0.0,
"occupancy_a": 0.75,
"occupancy_b": 0.0,
"occupancy_total": 0.75
}
],
"kd_a_nm": 10.0,
"kd_b_nm": 25.0,
"max_abs_error": 0.0,
"target_total_occupancy": 0.75
}
}
1 change: 1 addition & 0 deletions auto-research/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ auto-research/
| 2026-11-05 | E | [Clearance reference validation](2026-11-05-E-clearance-reference/report.md) | Exact organ mass balance and linear ODE integral | Mixed references caught; reported sum 17.104405 L/h, dose/AUC 17.103070 L/h | OpenAI Codex / @ahrazzle |
| 2026-11-05 | E (partial) | [Reaction and intervention experiments](2026-11-05-E-reaction-experiments/report.md) | Exact kinetics/conservation/commutativity; independent DOP853 | Maximum trajectory error 1.479e-11 mol/L; no biological validation | OpenAI Codex / @ahrazzle |
| 2026-11-05 | E | [SBML reaction networks as verified graphs](2026-11-05-E-sbml-import/report.md) | Exact rational algebra; libRoadRunner as independent SBML engine | 3 CC0 BioModels: exact conservation laws, trajectories ≤7e-10, steady states ≤2e-12; positive-mass invariant flags 8 of 49 surveyed models with exact certificates | Claude (Anthropic) |
| 2026-11-06 | E | [Competitive groove occupancy and evidence corner envelopes](2026-11-06-E-competitive-binding-envelopes/report.md) | Exact rational arithmetic (Fraction); elementary mass-action ReactionNetwork; DOP853 | Equilibrium/locus exact to 1 ulp; kinetic propagator vs DOP853 ≤2.7e-14; envelopes fail closed before model invocation | @ahrazzle |
| 2026-11-08 | E | [Conserved-flow graphs: topology → venous pressure](2026-11-08-E-vein-flow-graph/report.md) | Exact Hagen–Poiseuille, Windkessel, Starling, R–L solutions; exact Womersley impedance; physiology reference ranges | Steady flow exact to ~1e-16; standing foot venous pressure **88.7 mmHg** vs **85–90** (foot inside range, ankle 0.6 mmHg below); lumped R–L within 1% up to α=0.48, with measured breakdown at high α | OpenCode agent (DeepSeek V4.1 Flash Free) |
| 2026-11-08 | E | [Steady flow with valves: unique solution, finite solver, honest `converged`](2026-11-08-E-steady-complementarity/report.md) | Exact enumeration of all valve / collapse regimes; closed-form roots | Previous solver: 39/2000 random networks wrong but `converged=True` (worst 23%); now 0/6000, error ≤ 8e-15. Flow uniqueness proved for valves; Starling uniqueness 6000/6000 (conjecture). Expansion kinetic term makes the model ill-posed above 0.53 L/min (documented, not fixed) | MikeMike88 with Claude Code (Claude Opus 5.5) |

Expand Down
Loading
Loading