updated

Author: Qwen Code

README.md

@@ -1,57 +1,48 @@
 # DRIFT: Multi-Scale Stochastic Research Workbench
-
 [![CI](https://github.com/tomwolfe/DRIFT/actions/workflows/ci.yml/badge.svg)](https://github.com/tomwolfe/DRIFT/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![Coverage Status](https://coveralls.io/repos/github/tomwolfe/DRIFT/badge.svg?branch=main)](https://coveralls.io/github/tomwolfe/DRIFT?branch=main)
-
 ![Sample Dashboard](assets/sample_output.png)
 
 DRIFT (**D**rug-target **R**esponse **I**ntegrated **F**lux **T**rajectory) is a multi-scale stochastic framework designed to bridge the gap between molecular binding events and systemic metabolic phenotypes.
 
 ## 🚀 Interactive Demo
-
 Try DRIFT in your browser without any installation:
-
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tomwolfe/DRIFT/blob/main/examples/quickstart_tutorial.ipynb)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/tomwolfe/DRIFT/main?filepath=examples%2Fquickstart_tutorial.ipynb)
 
 ## 📐 System Architecture
-
 DRIFT integrates three distinct biological scales into a unified simulation loop:
-
 ```mermaid
 graph TD
-    A[Drug Concentration] -->|Hill Equation| B(BindingEngine)
-    B -->|Inhibition Factor| C(StochasticIntegrator)
-    C -->|Langevin Dynamics| D{Signaling State}
-    D -->|PI3K/AKT/mTOR| E(MetabolicBridge)
-    E -->|Vmax Constraints| F(DFBASolver)
-    F -->|FBA Optimization| G[Metabolic Fluxes & Growth]
-    G -->|Feedback/Recording| H[History/Dashboard]
+A[Drug Concentration] -->|Hill Equation| B(BindingEngine)
+B -->|Inhibition Factor| C(StochasticIntegrator)
+C -->|Langevin Dynamics| D{Signaling State}
+D -->|PI3K/AKT/mTOR| E(MetabolicBridge)
+E -->|Vmax Constraints| F(DFBASolver)
+F -->|FBA Optimization| G[Metabolic Fluxes & Growth]
+G -->|Feedback/Recording| H[History/Dashboard]
 ```
 
 ## ❓ Why DRIFT?
-
 In drug discovery, linking a molecular binding event to a systemic outcome (like growth inhibition) is often treated as a "black box." DRIFT provides a transparent, mechanistic bridge by:
 1.  **Capturing Temporal Dynamics:** Moving beyond static $IC_{50}$ values to see how responses evolve.
 2.  **Accounting for Stochasticity:** Modeling the "drift" in metabolic states caused by intrinsic cellular noise.
 3.  **Integrating Scales:** Coupling pharmacokinetics (Binding), pharmacodynamics (Signaling), and phenotype (Metabolism) in a single unified solver.
 
 ## 🌟 Key Features
-
 - **Multi-Scale Integration:** Seamlessly couples molecular binding, stochastic signaling (SDEs), and dynamic flux balance analysis (dFBA). Supports both E. coli core and Human GEMs (e.g., Recon1).
 - **Stochastic Dynamics:** Captures cellular heterogeneity using a high-stability **Milstein scheme** integrator with state-dependent noise, accelerated by **Numba**.
 - **Global Sensitivity Analysis (GSA):** Identify critical drivers of metabolic drift by perturbing signaling parameters and binding affinity simultaneously.
 - **Monte Carlo Uncertainty:** Built-in support for ensemble simulations to assess model robustness and parameter sensitivity.
 - **Interoperability:** Export results to structured Parquet or JSON formats (aligning with SED-ML principles) for cross-platform research.
 - **Interactive Dashboards:** Generates comprehensive HTML reports using **Plotly** for deep-dive analysis of trajectories.
 - **Scientific Validation:** Benchmarked against known biological responses and numerical stability tests.
+- **Polypharmacology Support:** (v0.2.0) Explicitly model drugs targeting multiple proteins with distinct $K_d$ values.
 
 ## 📚 Documentation
-
 Detailed documentation is available in the `docs/` directory:
-
 | Document | Description |
 | --- | --- |
 | [**Case Study Gallery**](docs/gallery.md) | **New:** Predictions for Erlotinib, Imatinib, and more. |
@@ -64,32 +55,28 @@ Detailed documentation is available in the `docs/` directory:
 | [**Tool Comparison**](docs/comparison_tools.md) | How DRIFT compares to DeepPurpose, COBRApy, etc. |
 
 ## 🧪 Scientific Foundation
-
 DRIFT's modeling approach is grounded in established systems biology literature:
-
 - **Signaling Dynamics:** The PI3K/AKT/mTOR SDE model is inspired by the topology described in *Chen et al. (2009), "Input-output behavior of ErbB signaling pathways."*
 - **Metabolic Modeling:** Flux Balance Analysis (FBA) implementation follows the standard protocols in *Orth et al. (2010), "What is flux balance analysis?"*
 - **Multi-scale Coupling:** The integration of signaling and metabolism reflects recent advances in dynamic FBA as reviewed in *Reimers et al. (2021).*
 
 ## 🚀 Quick Start
 
 ### Installation
-
 **Using Pip:**
 ```bash
 pip install -e .
 ```
 
 **Solver Setup (Critical):**
 DRIFT relies on `cobrapy` and `optlang` for metabolic solving. While it handles missing solvers gracefully by falling back to GLPK (via `swiglpk`), we recommend:
-
 1. **GLPK (Default):** Usually installed via `swiglpk`. If you encounter build errors on **M1/M2 Macs**:
-   ```bash
-   brew install glpk
-   export C_INCLUDE_PATH=/opt/homebrew/include
-   export LIBRARY_PATH=/opt/homebrew/lib
-   pip install swiglpk
-   ```
+```bash
+brew install glpk
+export C_INCLUDE_PATH=/opt/homebrew/include
+export LIBRARY_PATH=/opt/homebrew/lib
+pip install swiglpk
+```
 2. **CPLEX / Gurobi:** For large-scale models, these commercial solvers (free for academics) are significantly faster. Ensure they are in your Python environment's path.
 
 **Using Conda:**
@@ -105,7 +92,6 @@ docker run -it drift
 ```
 
 ## ⚡ Performance & Solver Guide
-
 DRIFT is optimized for performance, but the overall speed of multi-scale simulations is often limited by the underlying Linear Programming (LP) solver.
 
 | Model Scale | Recommended Solver | Rationale |
@@ -119,7 +105,6 @@ DRIFT is optimized for performance, but the overall speed of multi-scale simulat
 - **Worker Cache:** The `Workbench` automatically caches initialized models across Monte Carlo iterations to avoid the overhead of reloading genome-scale models.
 
 ### Basic Usage
-
 Run a standard Monte Carlo simulation:
 ```bash
 python main.py --mc-iterations 30 --sim-steps 100
@@ -136,11 +121,9 @@ python main.py --export-json outputs/results.json
 ```
 
 ## 🧪 Development and Testing
-
 ```bash
 # Run the full test suite
 pytest tests/
-
 # Run tests with coverage
 pytest tests/ --cov=drift --cov-report=html
 ```
@@ -150,6 +133,7 @@ To generate a sample dashboard and verify the workbench visualization:
 ```bash
 python scripts/generate_sample_dashboard.py
 ```
+
 Generated reports are saved in the `outputs/` directory (ignored by git).
 
 ### Current Test Coverage
@@ -159,30 +143,26 @@ Generated reports are saved in the `outputs/` directory (ignored by git).
 - **Visualization:** Dashboard generation and data integrity checks
 
 ## 📈 Example Results
-
 Running a typical simulation produces:
 - Interactive HTML dashboard with multi-scale visualization
 - Quantitative summary of growth inhibition and metabolic drift
 - Statistical analysis of ensemble variability
 - Parameter sensitivity reports
 
 ## 🗺️ Project Roadmap
-
 - [x] **v0.1.0:** Initial engine release & Monte Carlo integration.
-- [ ] **v0.2.0:** Support for multi-target inhibition (Polypharmacology).
+- [x] **v0.2.0:** Support for multi-target inhibition (Polypharmacology), strict validation, and enhanced export metadata.
 - [ ] **v0.3.0:** Integration with SBML models for custom signaling topologies.
 - [ ] **v1.0.0:** Stable release with full experimental dataset benchmarking.
 
 ## 🤝 Contributing
-
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
 - Setting up your development environment
 - Code style guidelines
 - Submitting pull requests
 - Reporting issues
 
 ## 📜 Citing DRIFT
-
 If you use DRIFT in your research, please cite it as:
 > Wolfe, T. (2025). DRIFT: A Multi-Scale Stochastic Framework for Predicting Drug-Induced Metabolic Drift. GitHub Repository. https://github.com/tomwolfe/DRIFT
 
@@ -194,17 +174,18 @@ If you use DRIFT in your research, please cite it as:
 
 ## 📋 Release Notes
 
-**Latest Release (v0.1.2):**
-- **Numerical Stability:** Upgraded SDE integrator from Euler-Maruyama to a **Milstein scheme** with state-dependent noise for improved robustness in high-noise scenarios.
-- **Scientific Consistency:** Added explicit support and fallback mechanisms for human metabolic models (e.g., Recon1) and corresponding growth keys.
-- **Dependency Optimization:** Integrated `glpk` and `swiglpk` into environment configurations for seamless FBA solving.
+**Latest Release (v0.2.0):**
+- **Harden polypharmacology validation** with strict input validation for the `targets` dictionary.
+- **Parallel reproducibility fixes** for bit-perfect Monte Carlo simulations.
+- **Explicit 'solver_status' field** added to exported JSON results.
+- Enhanced `BindingEngine` to enforce strict validation of targets dictionary.
+- Fixed seed propagation to Numba-jitted functions in worker processes.
+- Improved export metadata with solver status information.
 
 **Previous Release (v0.1.1):**
 - Initial public release
 - Multi-scale integration engine
 - Monte Carlo uncertainty quantification
 - Interactive visualization dashboard
-
-## 🚀 Release Process
-
-For information about creating new releases, see our [Release Process](RELEASE_PROCESS.md) documentation.
+- Dedicated `outputs/` directory for simulation results
+- Support for custom drift functions