diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 568da03..f972b0b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,8 +18,10 @@ jobs: run: | python -m pip install --upgrade pip pip install -e ".[dev]" + - name: Parameter ledger schema (offline) + run: PYTHONPATH=. python scripts/validate_ovarian_parameter_ledger.py - name: Python tests (quantum vs experiment, engine vs OpenMM referee, body vs clinical) - run: pytest -q + run: pytest -q -m "not network" - uses: actions/setup-node@v4 with: node-version: "22" diff --git a/README.md b/README.md index fa4a5fb..0a45503 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ faster than real time. | `vh.molecular` | From-scratch JAX engine: AMBER ff14SB force field, GB-OBC2 implicit water, autodiff forces, Langevin (BAOAB) and Verlet dynamics, L-BFGS minimization | Matches OpenMM (used only as a referee) term by term to ~1e-14 relative on real proteins; trajectories identical step by step; energy conserved ([`docs/validation_molecular.md`](docs/validation_molecular.md)) | | `vh.body` | From-scratch whole-body PBPK: 13 organs + blood, Rodgers & Rowland tissue partitioning, liver (well-stirred, IVIVE), kidney (filtration), oral absorption (stomach + 7-segment intestine) with gut-wall first-pass, virtual populations; solved exactly with matrix exponentials | Bottom-up midazolam predictions vs 100 clinical datasets (IV and oral) digitized by the Open Systems Pharmacology project | | `vh.bridge` | Unbound drug at the target organ → receptor occupancy over time; Kd ↔ binding free energy | Analytic round-trip; kinetic occupancy | -| `vh.graph` | **Formalizes the body as a typed graph** across scales (organs↔blood flow, atoms↔bonds); graph algorithms for reachability, pathways, cycles, flow balance, bottlenecks; **conserved-flow graphs** with R/C/L edge laws, gravity, Bernoulli, Starling collapse and valves; renders and verifies subgraphs | Blood conservation (Kirchhoff) to 1e-16 on the real PBPK model; a pure graph BFS reproduces the force field's exclusion list exactly; steady flow exact against Hagen–Poiseuille/Windkessel/Starling, and the standing foot venous pressure predicted at **88.7 mmHg** vs the physiological **85–90 mmHg** range ([`docs/graph_formalization.md`](docs/graph_formalization.md), [`docs/bernoulli_veins.md`](docs/bernoulli_veins.md)) | +| `vh.graph` | **Formalizes the body as a typed graph** across scales (organs↔blood flow, species↔reactions, atoms↔bonds); graph algorithms for reachability, pathways, cycles, flow balance, bottlenecks; **conserved-flow graphs** with R/C/L edge laws, gravity, Bernoulli, Starling collapse and valves; renders and verifies subgraphs; imports SBML reaction networks with exact conservation and consistency invariants | Blood conservation (Kirchhoff) to 1e-16 on the real PBPK model; a pure graph BFS reproduces the force field's exclusion list exactly; steady flow exact against Hagen–Poiseuille/Windkessel/Starling, and the standing foot venous pressure predicted at **88.7 mmHg** vs the physiological **85–90 mmHg** range; SBML trajectories and steady states match libRoadRunner to ~1e-9 ([`docs/graph_formalization.md`](docs/graph_formalization.md), [`docs/bernoulli_veins.md`](docs/bernoulli_veins.md)) | | `web/` | Real-time demo: atom-level protein dynamics and a virtual patient, live in the browser | JS engine checked against the Python engine to ≤1e-12 | The explicit-solvent engine (`vh.molecular.periodic`, `.constraints`, `.explicit_md`) adds rung 3 of the accuracy ladder: every water molecule, exact long-range electrostatics (Ewald / smooth PME), rigid-water SHAKE/RATTLE and a Monte-Carlo barostat — validated term-by-term against OpenMM Ewald (energy to 1e-13, PME to 1e-11, constraints to 1e-16). @@ -75,16 +75,23 @@ the structural/relational class of problems — and `vh.graph` proves it. The ho boundary (in [`docs/graph_formalization.md`](docs/graph_formalization.md)): a graph solves *where / what-connects / how-much-flows / is-it-consistent*; it does **not** solve *how-strong / how-fast / how-it-folds* — that stays physics. The real win is a -**typed graph that is also executable**: every edge carries the validated model -behind it, so the graph wires the scales together and lets any part be verified -alone. +**typed graph with explicit model references**: an edge can name a computational +model, and the optional [`ModelRegistry`](docs/model_contracts.md) executes a +registered callable after checking its scalar inputs and outputs. Engine +adapters are not registered automatically; model validation remains separate +from checking interface compatibility. The body is already a graph at every scale — organs joined by blood flow, atoms joined by bonds. Formalized from the real, validated engines: -
-
-
The temporal sequence of kinase activation, from MAPKKK (activated RAF) to the final effector MAPK (activated ERK), is described here. It is observed from the model that there is an increase in sensitivity along the levels of the cascade, where the activity of MAPK reaches its maximal before MAPKKK.
+This model is described in the article:
+ + +Abstract:
+The mitogen-activated protein kinase (MAPK) cascade is a highly conserved series of three protein kinases implicated in diverse biological processes. Here we demonstrate that the cascade arrangement has unexpected consequences for the dynamics of MAPK signaling. We solved the rate equations for the cascade numerically and found that MAPK is predicted to behave like a highly cooperative enzyme, even though it was not assumed that any of the enzymes in the cascade were regulated cooperatively. Measurements of MAPK activation in Xenopus oocyte extracts confirmed this prediction. The stimulus/response curve of the MAPK was found to be as steep as that of a cooperative enzyme with a Hill coefficient of 4-5, well in excess of that of the classical allosteric protein hemoglobin. The shape of the MAPK stimulus/ response curve may make the cascade particularly appropriate for mediating processes like mitogenesis, cell fate induction, and oocyte maturation, where a cell switches from one discrete state to another.
+The species K_PP_norm, KKK_P_norm and KK_PP_norm are the relative concentrations of the active MAPK, MAPKK and MAPKKK, that is the double, or single resp. phophorylated forms divided by the total concentrations of each kinase. For MAPK additionally the also active MAPK divided by the maximal concentration of active MAPK is given by rel_K_PP_max. The parameter K_PP_norm_max, the maximal ratio of active MapK, has to be calculated for each change of parameters.
+This model is hosted on BioModels Database + and identified by: BIOMD0000000009 + .
+To cite BioModels Database, please use: BioModels Database: An enhanced, curated and annotated resource for published quantitative kinetic models + .
+To the extent possible under law, all copyright and related or neighbouring rights to this encoded model have been dedicated to the public domain worldwide. Please refer to CC0 Public Domain Dedication + for more information.
++ the maximal value of K_PP_norm at a stimulation conc. of 10.
+ +The combination of ultrasensitivity and negative feedback bring sustained oscillations in the mitogen-activated protein kinase cascades.
+This model is described in the article:
+ + +Abstract:
+Functional organization of signal transduction into protein phosphorylation cascades, such as the mitogen-activated protein kinase (MAPK) cascades, greatly enhances the sensitivity of cellular targets to external stimuli. The sensitivity increases multiplicatively with the number of cascade levels, so that a tiny change in a stimulus results in a large change in the response, the phenomenon referred to as ultrasensitivity. In a variety of cell types, the MAPK cascades are imbedded in long feedback loops, positive or negative, depending on whether the terminal kinase stimulates or inhibits the activation of the initial level. Here we demonstrate that a negative feedback loop combined with intrinsic ultrasensitivity of the MAPK cascade can bring about sustained oscillations in MAPK phosphorylation. Based on recent kinetic data on the MAPK cascades, we predict that the period of oscillations can range from minutes to hours. The phosphorylation level can vary between the base level and almost 100% of the total protein. The oscillations of the phosphorylation cascades and slow protein diffusion in the cytoplasm can lead to intracellular waves of phospho-proteins.
+This model is hosted on BioModels Database + and identified by: BIOMD0000000010 + .
+To cite BioModels Database, please use: BioModels Database: An enhanced, curated and annotated resource for published quantitative kinetic models + .
+To the extent possible under law, all copyright and related or neighbouring rights to this encoded model have been dedicated to the public domain worldwide. Please refer to CC0 Public Domain Dedication + for more information.
+This model describes the deterministic version of the repressilator system.
+The authors of this model (see reference) use three transcriptional repressor systems that are not part of any natural biological clock to build an oscillating network that they called the repressilator. The model system was induced in Escherichia coli.
+In this system, LacI (variable X is the mRNA, variable PX is the protein) inhibits the tetracycline-resistance transposon tetR (Y, PY describe mRNA and protein). Protein tetR inhibits the gene Cl from phage Lambda (Z, PZ: mRNA, protein),and protein Cl inhibits lacI expression. With the appropriate parameter values this system oscillates.
+This model is described in the article:
+ + +Abstract:
+Networks of interacting biomolecules carry out many essential functions in living cells, but the 'design principles' underlying the functioning of such intracellular networks remain poorly understood, despite intensive efforts including quantitative analysis of relatively simple systems. Here we present a complementary approach to this problem: the design and construction of a synthetic network to implement a particular function. We used three transcriptional repressor systems that are not part of any natural biological clock to build an oscillating network, termed the repressilator, in Escherichia coli. The network periodically induces the synthesis of green fluorescent protein as a readout of its state in individual cells. The resulting oscillations, with typical periods of hours, are slower than the cell-division cycle, so the state of the oscillator has to be transmitted from generation to generation. This artificial clock displays noisy behaviour, possibly because of stochastic fluctuations of its components. Such 'rational network design may lead both to the engineering of new cellular behaviours and to an improved understanding of naturally occurring networks.
+The model is based upon the equations in Box 1 of the paper; however, these equations as printed are dimensionless, and the correct dimensions have been returned to the equations, and the parameters set to reproduce Figure 1C (left).
+The original model was generated by B.E. Shapiro using Cellerator version 1.0 update 2.1127 using Mathematica 4.2 for Mac OS X (June 4, 2002), November 27, 2002 12:15:32, using (PowerMac,PowerPC, Mac OS X,MacOSX,Darwin).
+Nicolas Le Novere provided a corrected version generated by SBMLeditor on Sun Aug 20 00:44:05 BST 2006. This removed the EmptySet species. Ran fine on COPASI 4.0 build 18.
+Bruce Shapiro revised the model with SBMLeditor on 23 October 2006 20:39 PST. This defines default units and correct reactions. The original Cellerator reactions while being mathematically correct did not accurately reflect the intent of the authors. The original notes were mostly removed because they were mostly incorrect in the revised version. Tested with MathSBML 2.6.0.
+Nicolas Le Novere changed the volume to 1 cubic micrometre, to allow for stochastic simulation.
+Changed by Lukas Endler to use the average livetime of mRNA instead of its halflife and a corrected value of alpha and alpha0.
+Moreover, the equations used in this model were clarified, cf. below.
+The equations given in box 1 + of the original publication are rescaled in three respects (lowercase letters denote the rescaled, uppercase letters the unscaled number of molecules per cell):
++ α + in the equations should be in units of rescaled proteins per promotor and cell, and β + is the ratio of the protein to the mRNA decay rates or the ratio of the mRNA to the protein halflife.
+In this version of the model α + and β + are calculated correspondingly to the article, while p + and m + where just replaced by P/Km + resp. M/eff + and all equations multiplied by 1/t_ave + . Also, to make the equations easier to read, commonly used variables derived from the parameters given in the article by simple rules were introduced.
+The parameters given in the article were:
+| promotor strength (repressed) ( tps_repr + ): | +5*10 -4 | +transcripts/(promotor*s) | +
| promotor strength (full) ( tps_active + ): | +0.5 | +transcripts/(promotor*s) | +
| mRNA half life, τ 1/2,mRNA + : | +2 | +min | +
| protein half life, τ 1/2,prot + : | +10 | +min | +
| K M + : | +40 | +monomers/cell | +
| Hill coefficient n: | +2 | ++ |
From these the following constants can be derived:
+| average mRNA lifetime ( t_ave + ): | ++ τ 1/2,mRNA + /ln(2) + | += 2.89 min | +
| mRNA decay rate ( kd_mRNA + ): | ++ ln(2)/ τ 1/2,mRNA + | += 0.347 min -1 | +
| protein decay rate ( kd_prot + ): | ++ ln(2)/ τ 1/2,prot + | +|
| transcription rate ( a_tr + ): | ++ tps_active*60 + | += 29.97 transcripts/min | +
| transcription rate (repressed) ( a0_tr + ): | ++ tps_repr*60 + | += 0.03 transcripts/min | +
| translation rate ( k_tl + ): | ++ eff*kd_mRNA + | += 6.93 proteins/(mRNA*min) | +
| α : | ++ a_tr*eff*τ 1/2,prot + /(ln(2)*K M + ) + | += 216.4 proteins/(promotor*cell*Km) | +
| α 0 + : | ++ a0_tr*eff*τ 1/2,prot + /(ln(2)*K M + ) + | += 0.2164 proteins/(promotor*cell*Km) | +
| β : | ++ k_dp/k_dm + | += 0.2 | +
Annotation by the Kinetic Simulation Algorithm Ontology (KiSAO):
+To reproduce the simulations run published by the authors, the model has to be simulated with any of two different approaches. First, one could use a deterministic method ( KISAO_0000035 + ) with continuous variables ( KISAO_0000018 + ). One sample algorithm to use is the CVODE solver ( KISAO_0000019 + ). Second, one could simulate the system using Gillespie's direct method ( KISAO_0000029 + ), which is a stochastic method ( KISAO_0000036 + ) supporting adaptive timesteps ( KISAO_0000041 + ) and using discrete variables ( KISAO_0000016 + ).
+This model is hosted on BioModels Database + and identified by: BIOMD0000000012 + .
+To cite BioModels Database, please use: BioModels Database: An enhanced, curated and annotated resource for published quantitative kinetic models + .
+To the extent possible under law, all copyright and related or neighbouring rights to this encoded model have been dedicated to the public domain worldwide. Please refer to CC0 Public Domain Dedication + for more information.
++ lacI inhibitor
++ Tet repressor protein
++ lambda repressor
++ ratio of protein to mRNA decay rates
++ Leakiness in protein copies per promoter and cell
++ Protein copies per promoter and cell
++ Average number of proteins per transcript
++ Hill coefficient
++ Number of repressor molecules per cell giving half maximal repression, in monomers per cell
++ mRNA decay rate constant
++ Protein decay rate costant
++ Translation rate constant
++ Transcription rate from free promotor minus a0_tr
++ Transcrition from free promotor in transcripts per second and promotor
++ Transcrition from fully repressed promotor in transcripts per second and promotor
++ Transcription rate from fully repressed promotor
+