commol 0.1.0b2__cp314-cp314-macosx_11_0_arm64.whl

commol-0.1.0b2.dist-info/METADATA

@@ -0,0 +1,555 @@
+Metadata-Version: 2.4
+Name: commol
+Version: 0.1.0b2
+Requires-Dist: cffi>=2.0,<3.0
+Requires-Dist: numpy>=2.4.0,<3.0
+Requires-Dist: pint>=0.25.2,<0.26.0
+Requires-Dist: pydantic>=2.0,<3.0
+Requires-Dist: scikit-learn>=1.8,<2.0
+Requires-Dist: seaborn>=0.13.2,<0.14.0
+Requires-Dist: maturin>=1.9.1,<1.10.0 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.8,<4.0 ; extra == 'dev'
+Requires-Dist: pytest>=8.4,<9.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=6.2,<7.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.12,<0.13 ; extra == 'dev'
+Requires-Dist: twine>=6.2.0,<7.0.0 ; extra == 'dev'
+Requires-Dist: ty>=0.0.9,<0.0.10 ; extra == 'dev'
+Requires-Dist: vulture>=2.14,<3.0 ; extra == 'dev'
+Requires-Dist: mike>=2.0,<3.0 ; extra == 'docs'
+Requires-Dist: mkdocs>=1.6,<2.0 ; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26,<1.0 ; extra == 'docs'
+Requires-Dist: mkdocs-autorefs>=1.2,<2.0 ; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5,<10.0 ; extra == 'docs'
+Provides-Extra: dev
+Provides-Extra: docs
+Summary: A high-performance compartment modelling library in Rust and Python.
+Author-email: "Rafael J. Villanueva Micó" <rjvillan@imm.upv.es>, Carlos Andreu Vilarroig <caranvi1@upv.es>, David Martínez Rodríguez <damarro3@upv.es>
+License-Expression: MIT
+Requires-Python: >=3.12.0
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/MUNQU/commol
+Project-URL: Documentation, https://munqu.github.io/commol
+Project-URL: Repository, https://github.com/MUNQU/commol
+Project-URL: Bug Tracker, https://github.com/MUNQU/commol/issues
+
+# Commol
+
+A high-performance compartment modelling library for mathematical modeling using difference equations. Commol provides a clean Python API backed by a fast Rust engine for numerical computations.
+
+> ⚠️ **Alpha Stage Warning**: Commol is currently in alpha development. The API is not yet stable and may change between versions without backward compatibility guarantees. Use in production at your own risk.
+
+## Features
+
+- **Intuitive Model Building**: Fluent API for constructing compartment models
+- **Mathematical Expressions**: Support for complex mathematical formulas in transition rates (sin, cos, exp, log, etc.)
+- **Unit Checking**: Automatic dimensional analysis to catch unit errors before simulation
+- **High Performance**: Rust-powered simulation engine for fast computations
+- **Flexible Architecture**: Support for stratified populations and conditional transitions
+- **Type Safety**: Comprehensive validation using Pydantic models
+- **Multiple Output Formats**: Get results as dictionaries or lists for easy analysis
+
+## Installation
+
+```bash
+# Install from PyPI (once published)
+pip install commol
+
+# Or install from source
+git clone https://github.com/MUNQU/commol.git
+cd commol/py-commol
+pip install maturin
+
+# If using a virtual environment, activate it first
+# source venv/bin/activate  # On Linux/macOS
+# venv\Scripts\activate     # On Windows
+
+maturin develop --release
+```
+
+> **⚠️ Important**: The project directory path must not contain tildes (`~`) or spaces. Maturin may fail with paths like `~/projects/commol` or `/home/my projects/commol`. Use full paths like `/home/username/projects/commol` instead.
+
+## Quick Start
+
+```python
+from commol import ModelBuilder, Simulation
+
+# Build a simple SIR model
+model = (
+    ModelBuilder(name="Basic SIR", version="1.0")
+    .add_bin(id="S", name="Susceptible")
+    .add_bin(id="I", name="Infected")
+    .add_bin(id="R", name="Recovered")
+    .add_parameter(id="beta", value=0.3)
+    .add_parameter(id="gamma", value=0.1)
+    .add_transition(
+        id="infection",
+        source=["S"],
+        target=["I"],
+        rate="beta * S * I / N"
+    )
+    .add_transition(
+        id="recovery",
+        source=["I"],
+        target=["R"],
+        rate="gamma"
+    )
+    .set_initial_conditions(
+        population_size=1000,
+        bin_fractions=[
+            {"bin": "S", "fraction": 0.99},
+            {"bin": "I", "fraction": 0.01},
+            {"bin": "R", "fraction": 0.0}
+        ]
+    )
+    .build(typology="DifferenceEquations")
+)
+
+# Run simulation
+simulation = Simulation(model)
+results = simulation.run(num_steps=100)
+
+# Display results
+print(f"Final infected: {results['I'][-1]:.0f}")
+
+# Visualize results
+from commol import SimulationPlotter
+
+plotter = SimulationPlotter(simulation, results)
+plotter.plot_series(output_file="sir_model.png")
+```
+
+### Using $compartment Placeholder for Multiple Transitions
+
+When you need to apply the same transition to multiple compartments (like death rates), use the `$compartment` placeholder instead of writing repetitive code:
+
+```python
+model = (
+    ModelBuilder(name="SLIR with Deaths", version="1.0")
+    .add_bin(id="S", name="Susceptible")
+    .add_bin(id="L", name="Latent")
+    .add_bin(id="I", name="Infected")
+    .add_bin(id="R", name="Recovered")
+    .add_parameter(id="beta", value=0.3, unit="1/day")
+    .add_parameter(id="gamma", value=0.2, unit="1/day")
+    .add_parameter(id="delta", value=0.1, unit="1/day")
+    .add_parameter(id="d", value=0.01, unit="1/day")  # Death rate
+    .add_transition(
+        id="infection",
+        source=["S"],
+        target=["L"],
+        rate="beta * S * I / N"
+    )
+    .add_transition(
+        id="progression",
+        source=["L"],
+        target=["I"],
+        rate="gamma * L"
+    )
+    .add_transition(
+        id="recovery",
+        source=["I"],
+        target=["R"],
+        rate="delta * I"
+    )
+    # Single transition automatically expands to 4 separate death transitions
+    .add_transition(
+        id="death",
+        source=["S", "L", "I", "R"],
+        target=[],
+        rate="d * $compartment"  # Expands to: d*S, d*L, d*I, d*R
+    )
+    .set_initial_conditions(
+        population_size=1000,
+        bin_fractions=[
+            {"bin": "S", "fraction": 0.99},
+            {"bin": "L", "fraction": 0.005},
+            {"bin": "I", "fraction": 0.005},
+            {"bin": "R", "fraction": 0.0}
+        ]
+    )
+    .build(typology="DifferenceEquations")
+)
+```
+
+**The `$compartment` placeholder:**
+
+- Automatically expands to multiple transitions (one per source compartment)
+- Replaces `$compartment` with the actual compartment name in the rate formula
+- Works with stratified rates for age-structured or location-based models
+- Reduces code duplication and improves maintainability
+
+**Example with stratified rates:**
+
+```python
+.add_transition(
+    id="death",
+    source=["S", "I", "R"],
+    target=[],
+    rate="d_base * $compartment",  # Fallback rate
+    stratified_rates=[
+        {
+            "conditions": [{"stratification": "age", "category": "young"}],
+            "rate": "d_young * $compartment"  # Lower death rate for young
+        },
+        {
+            "conditions": [{"stratification": "age", "category": "old"}],
+            "rate": "d_old * $compartment"  # Higher death rate for old
+        }
+    ]
+)
+```
+
+### With Unit Checking
+
+Add units to parameters and bins for automatic dimensional validation and annotated equation display:
+
+```python
+model = (
+    ModelBuilder(name="SIR with Units", version="1.0", bin_unit="person")
+    .add_bin(id="S", name="Susceptible")
+    .add_bin(id="I", name="Infected")
+    .add_bin(id="R", name="Recovered")
+    .add_parameter(id="beta", value=0.5, unit="1/day")  # Rate with units
+    .add_parameter(id="gamma", value=0.1, unit="1/day")
+    .add_transition(
+        id="infection",
+        source=["S"],
+        target=["I"],
+        rate="beta * S * I / N"
+    )
+    .add_transition(
+        id="recovery",
+        source=["I"],
+        target=["R"],
+        rate="gamma * I"
+    )
+    .set_initial_conditions(
+        population_size=1000,
+        bin_fractions=[
+            {"bin": "S", "fraction": 0.99},
+            {"bin": "I", "fraction": 0.01},
+            {"bin": "R", "fraction": 0.0}
+        ]
+    )
+    .build(typology="DifferenceEquations")
+)
+
+# Validate dimensional consistency
+model.check_unit_consistency()  # Ensures all equations have correct units
+
+# Print equations with unit annotations
+model.print_equations()
+# Output shows:
+#   S -> I: beta(1/day) * S(person) * I(person) / N(person) [person/day]
+#   I -> R: gamma(1/day) * I(person) [person/day]
+
+# Export equations in LaTeX format for publications
+model.print_equations(format="latex")
+# Output: \[\frac{dS}{dt} = - (\beta \cdot S \cdot I / N)\]
+```
+
+**Note**: Units must be defined for ALL parameters and bins, or for NONE. Partial unit definitions will raise a `ValueError` to prevent inconsistent models.
+
+### Model Calibration
+
+Fit model parameters to observed data using optimization algorithms. Parameters to be calibrated should be set to `None`:
+
+```python
+from commol import (
+    ModelBuilder,
+    Simulation,
+    Calibrator,
+    CalibrationProblem,
+    CalibrationParameter,
+    ObservedDataPoint,
+    ParticleSwarmConfig,
+)
+
+# Build model with unknown parameters
+model = (
+    ModelBuilder(name="SIR Model", version="1.0")
+    .add_bin(id="S", name="Susceptible")
+    .add_bin(id="I", name="Infected")
+    .add_bin(id="R", name="Recovered")
+    .add_parameter(id="beta", value=None)   # To be calibrated
+    .add_parameter(id="gamma", value=None)  # To be calibrated
+    .add_transition(
+        id="infection",
+        source=["S"],
+        target=["I"],
+        rate="beta * S * I / N"
+    )
+    .add_transition(
+        id="recovery",
+        source=["I"],
+        target=["R"],
+        rate="gamma * I"
+    )
+    .set_initial_conditions(
+        population_size=1000,
+        bin_fractions=[
+            {"bin": "S", "fraction": 0.99},
+            {"bin": "I", "fraction": 0.01},
+            {"bin": "R", "fraction": 0.0}
+        ]
+    )
+    .build(typology="DifferenceEquations")
+)
+
+# Define observed data from real outbreak
+observed_data = [
+    ObservedDataPoint(step=10, compartment="I", value=45.2),
+    ObservedDataPoint(step=20, compartment="I", value=78.5),
+    ObservedDataPoint(step=30, compartment="I", value=62.3),
+]
+
+# Simulation can be created with None values for calibration
+simulation = Simulation(model)
+
+# Specify parameters to calibrate with bounds and initial guesses
+parameters = [
+    CalibrationParameter(
+        id="beta",
+        parameter_type="parameter",
+        min_bound=0.0,
+        max_bound=1.0,
+        initial_guess=0.3  # Starting point
+    ),
+    CalibrationParameter(
+        id="gamma",
+        parameter_type="parameter",
+        min_bound=0.0,
+        max_bound=1.0,
+    ),
+]
+
+# Configure optimization algorithm (config type determines the algorithm)
+pso_config = ParticleSwarmConfig(
+    num_particles=40,
+    max_iterations=300,
+    verbose=True
+)
+
+# Configure calibration problem
+problem = CalibrationProblem(
+    observed_data=observed_data,
+    parameters=parameters,
+    loss_function="sse",
+    optimization_config=pso_config,  # ParticleSwarmConfig or NelderMeadConfig
+)
+
+# Run calibration
+calibrator = Calibrator(simulation, problem)
+result = calibrator.run()
+
+print(f"Calibrated beta: {result.best_parameters['beta']:.4f}")
+print(f"Calibrated gamma: {result.best_parameters['gamma']:.4f}")
+
+# Update model with calibrated parameters
+model.update_parameters(result.best_parameters)
+
+# Create new simulation with calibrated model
+calibrated_simulation = Simulation(model)
+calibrated_results = calibrated_simulation.run(num_steps=100)
+```
+
+**Calibrating with Scale Parameters:**
+
+When observed data is underreported, use scale parameters to estimate the reporting rate:
+
+```python
+# Reported cases (potentially underreported)
+reported_cases = [10, 15, 25, 40, 60, 75, 85, 70, 50, 30]
+
+# Link observed data to scale parameter
+observed_data = [
+    ObservedDataPoint(
+        step=idx,
+        compartment="I",
+        value=cases,
+        scale_id="reporting_rate"  # Links to scale parameter
+    )
+    for idx, cases in enumerate(reported_cases)
+]
+
+parameters = [
+    CalibrationParameter(
+        id="beta",
+        parameter_type="parameter",
+        min_bound=0.1,
+        max_bound=1.0
+    ),
+    CalibrationParameter(
+        id="gamma",
+        parameter_type="parameter",
+        min_bound=0.05,
+        max_bound=0.5
+    ),
+    CalibrationParameter(
+        id="reporting_rate",
+        parameter_type="scale",
+        min_bound=0.01,
+        max_bound=1.0
+    ),
+]
+
+# Run calibration
+result = calibrator.run()
+
+# Separate parameters by type
+scale_values = {
+    param.id: result.best_parameters[param.id]
+    for param in problem.parameters
+    if param.parameter_type == "scale"
+}
+
+print(f"Calibrated reporting rate: {scale_values['reporting_rate']:.2%}")
+
+# Visualize with scale_values for correct display
+plotter.plot_series(observed_data=observed_data, scale_values=scale_values)
+```
+
+**Constraining Parameters:**
+
+Apply constraints to enforce biological knowledge during calibration.
+
+```python
+from commol import CalibrationConstraint
+
+# Add constraint: beta/gamma <= 5 (written as 5 - beta/gamma >= 0)
+constraints = [
+    CalibrationConstraint(
+        id="r0_bound",
+        expression="5.0 - beta/gamma",
+        description="R0 <= 5",
+    )
+]
+
+problem = CalibrationProblem(
+    observed_data=observed_data,
+    parameters=parameters,
+    constraints=constraints,  # Include constraints
+    loss_function="sse",
+    optimization_config=pso_config,
+)
+
+result = calibrator.run()
+```
+
+**Probabilistic Calibration:**
+
+For uncertainty quantification, use probabilistic calibration to get an ensemble of parameter sets:
+
+```python
+from commol import ProbabilisticCalibrationConfig
+
+# Configure probabilistic calibration
+prob_config = ProbabilisticCalibrationConfig(
+    n_runs=20,  # Number of calibration runs
+    confidence_level=0.95
+)
+
+problem = CalibrationProblem(
+    observed_data=observed_data,
+    parameters=parameters,
+    loss_function="sse",
+    optimization_config=pso_config,
+    probabilistic_config=prob_config,  # Enable probabilistic mode
+)
+
+# Run probabilistic calibration
+calibrator = Calibrator(simulation, problem)
+prob_result = calibrator.run_probabilistic()
+```
+
+## Documentation
+
+**[Full Documentation](https://munqu.github.io/commol)**
+
+- [Installation Guide](https://munqu.github.io/commol/getting-started/installation/) - Setup and installation
+- [Quick Start](https://munqu.github.io/commol/getting-started/quickstart/) - Build your first model
+- [User Guide](https://munqu.github.io/commol/guide/core-concepts/) - Core concepts and tutorials
+- [Model Calibration](https://munqu.github.io/commol/guide/calibration/) - Parameter fitting and optimization
+- [API Reference](https://munqu.github.io/commol/api/model-builder/) - Complete API documentation
+- [Examples](https://munqu.github.io/commol/guide/examples/) - SIR, SEIR, and advanced models
+
+## Development
+
+For contributors and developers:
+
+- [Development Workflow](https://munqu.github.io/commol/development/workflow/) - Setup, branching, CI/CD
+- [Contributing Guidelines](https://munqu.github.io/commol/development/contributing/) - How to contribute
+- [Release Process](https://munqu.github.io/commol/development/release/) - Version management
+
+### Local Development
+
+```bash
+# Clone repository
+git clone https://github.com/MUNQU/commol.git
+cd commol
+
+# Create and activate virtual environment
+python -m venv venv
+
+source venv/bin/activate  # On Linux/macOS
+venv\Scripts\activate   # On Windows
+
+# Install Python dependencies
+cd py-commol
+pip install -e ".[dev,docs]"
+
+# Build Rust workspace
+cd ..
+cargo build --workspace
+
+# Build Python extension (with virtual environment activated)
+cd py-commol
+maturin develop --release
+
+# Run tests
+pytest
+cd ..
+cargo test --workspace
+
+# Build documentation locally
+cd py-commol
+mkdocs serve
+```
+
+> **⚠️ Path Requirements**: Ensure the project path contains no tildes (`~`) or spaces. Maturin may fail otherwise.
+>
+> **💡 Tip**: Make sure your virtual environment is activated before running `maturin develop`.
+
+## License
+
+Commol is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Authors
+
+- Rafael J. Villanueva Micó - [rjvillan@imm.upv.es](mailto:rjvillan@imm.upv.es)
+- Carlos Andreu Vilarroig - [caranvi1@upv.es](mailto:caranvi1@upv.es)
+- David Martínez Rodríguez - [damarro3@upv.es](mailto:damarro3@upv.es)
+
+## Citation
+
+If you use Commol in your research, please cite:
+
+```bibtex
+@software{commol2025,
+  title = {Commol: A High-Performance Compartment Modelling Library},
+  author = {
+    Villanueva Micó, Rafael J.
+    and Andreu Vilarroig, Carlos
+    and Martínez Rodríguez, David
+  },
+  year = {2025},
+  url = {https://github.com/MUNQU/commol}
+}
+```
+
+## Support
+
+- Documentation: https://munqu.github.io/commol
+- Issue Tracker: https://github.com/MUNQU/commol/issues
+- Discussions: https://github.com/MUNQU/commol/discussions
+

commol-0.1.0b2.dist-info/RECORD

@@ -0,0 +1,6 @@
+commol-0.1.0b2.dist-info/METADATA,sha256=tb56qeRXaC0T7g_tsUP2laNgXwyZemkJJi2Cqg3z6K4,16708
+commol-0.1.0b2.dist-info/WHEEL,sha256=1PvyiPvcJ94VD-5qzLXvCxiTKltkB9r5dXMQ1otw8Pg,104
+commol_rs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commol_rs/commol_rs.cpython-314-darwin.so,sha256=4sGndTCZ39VI-9eql0_WoHaFqvysi1fCGgrmvOajAsQ,5338656
+commol_rs/commol_rs.pyi,sha256=CGw8HFA3sajCc8fzjGnfJez3lFWuLdqGKpVVSh_O7ik,15103
+commol-0.1.0b2.dist-info/RECORD,,

commol-0.1.0b2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.6)
+Root-Is-Purelib: false
+Tag: cp314-cp314-macosx_11_0_arm64

commol_rs/commol_rs.pyi

@@ -0,0 +1,464 @@
+from typing import Protocol
+
+from commol.constants import LogicOperators, ModelTypes, VariablePrefixes
+
+class RuleProtocol(Protocol):
+    variable: str
+    operator: LogicOperators
+    value: str | int | float | bool
+
+class ConditionProtocol(Protocol):
+    logic: LogicOperators
+    rules: list[RuleProtocol]
+
+class DiseaseStateProtocol(Protocol):
+    id: str
+    name: str
+
+class StratificationProtocol(Protocol):
+    id: str
+    categories: list[str]
+
+class StratificationConditionProtocol(Protocol):
+    stratification: str
+    category: str
+
+class StratifiedRateProtocol(Protocol):
+    conditions: list[StratificationConditionProtocol]
+    rate: str
+
+class TransitionProtocol(Protocol):
+    id: str
+    source: list[str]
+    target: list[str]
+    rate: RateMathExpressionProtocol | None
+    stratified_rates: list[StratifiedRateProtocol] | None
+    condition: ConditionProtocol | None
+
+class ParameterProtocol(Protocol):
+    id: str
+    value: float
+    description: str | None
+
+class StratificationFractionProtocol(Protocol):
+    category: str
+    fraction: float
+
+class StratificationFractionsProtocol(Protocol):
+    stratification: str
+    fractions: list[StratificationFractionProtocol]
+
+class InitialConditionsProtocol(Protocol):
+    population_size: int
+    disease_state_fraction: dict[str, float]
+    stratification_fractions: list[StratificationFractionsProtocol]
+
+class PopulationProtocol(Protocol):
+    disease_states: list[DiseaseStateProtocol]
+    stratifications: list[StratificationProtocol]
+    transitions: list[TransitionProtocol]
+    initial_conditions: InitialConditionsProtocol
+
+class DynamicsProtocol(Protocol):
+    typology: ModelTypes
+    transitions: list[TransitionProtocol]
+
+class RustModelProtocol(Protocol):
+    name: str
+    description: str | None
+    version: str | None
+    population: PopulationProtocol
+    parameters: list[ParameterProtocol]
+    dynamics: DynamicsProtocol
+    @staticmethod
+    def from_json(json_string: str) -> RustModelProtocol: ...
+
+class DifferenceEquationsProtocol(Protocol):
+    def __init__(self, model: RustModelProtocol) -> None: ...
+    def run(self, num_steps: int) -> list[list[float]]: ...
+    def step(self) -> None: ...
+    @property
+    def population(self) -> list[float]: ...
+    @property
+    def compartments(self) -> list[str]: ...
+
+class DifferenceModule(Protocol):
+    DifferenceEquations: type[DifferenceEquationsProtocol]
+
+class ObservedDataPointProtocol(Protocol):
+    def __init__(
+        self,
+        step: int,
+        compartment: str,
+        value: float,
+        weight: float | None = None,
+        scale_id: str | None = None,
+    ) -> None: ...
+    @property
+    def time_step(self) -> int: ...
+    @property
+    def compartment(self) -> str: ...
+    @property
+    def value(self) -> float: ...
+    @property
+    def scale_id(self) -> str | None: ...
+
+class CalibrationParameterTypeProtocol(Protocol):
+    Parameter: "CalibrationParameterTypeProtocol"
+    InitialCondition: "CalibrationParameterTypeProtocol"
+    Scale: "CalibrationParameterTypeProtocol"
+
+class CalibrationParameterProtocol(Protocol):
+    def __init__(
+        self,
+        id: str,
+        parameter_type: CalibrationParameterTypeProtocol,
+        min_bound: float,
+        max_bound: float,
+        initial_guess: float | None = None,
+    ) -> None: ...
+    @property
+    def id(self) -> str: ...
+    @property
+    def parameter_type(self) -> CalibrationParameterTypeProtocol: ...
+    @property
+    def min_bound(self) -> float: ...
+    @property
+    def max_bound(self) -> float: ...
+
+class CalibrationConstraintProtocol(Protocol):
+    def __init__(
+        self,
+        id: str,
+        expression: str,
+        description: str | None = None,
+        weight: float = 1.0,
+        time_steps: list[int] | None = None,
+    ) -> None: ...
+    @property
+    def id(self) -> str: ...
+    @property
+    def expression(self) -> str: ...
+    @property
+    def description(self) -> str | None: ...
+    @property
+    def weight(self) -> float: ...
+    @property
+    def time_steps(self) -> list[int] | None: ...
+
+class LossConfigProtocol(Protocol):
+    @staticmethod
+    def sse() -> LossConfigProtocol: ...
+    @staticmethod
+    def rmse() -> LossConfigProtocol: ...
+    @staticmethod
+    def mae() -> LossConfigProtocol: ...
+    @staticmethod
+    def weighted_sse() -> LossConfigProtocol: ...
+
+class NelderMeadConfigProtocol(Protocol):
+    def __init__(
+        self,
+        max_iterations: int = 1000,
+        sd_tolerance: float = 1e-6,
+        simplex_perturbation: float = 1.1,
+        alpha: float | None = None,
+        gamma: float | None = None,
+        rho: float | None = None,
+        sigma: float | None = None,
+        verbose: bool = False,
+        header_interval: int = 100,
+    ) -> None: ...
+
+class PSOInertiaConstantProtocol(Protocol):
+    def __init__(self, factor: float) -> None: ...
+    @property
+    def factor(self) -> float: ...
+
+class PSOInertiaChaoticProtocol(Protocol):
+    def __init__(self, w_min: float, w_max: float) -> None: ...
+    @property
+    def w_min(self) -> float: ...
+    @property
+    def w_max(self) -> float: ...
+
+class PSOAccelerationConstantProtocol(Protocol):
+    def __init__(self, cognitive: float, social: float) -> None: ...
+    @property
+    def cognitive(self) -> float: ...
+    @property
+    def social(self) -> float: ...
+
+class PSOAccelerationTimeVaryingProtocol(Protocol):
+    def __init__(
+        self, c1_initial: float, c1_final: float, c2_initial: float, c2_final: float
+    ) -> None: ...
+    @property
+    def c1_initial(self) -> float: ...
+    @property
+    def c1_final(self) -> float: ...
+    @property
+    def c2_initial(self) -> float: ...
+    @property
+    def c2_final(self) -> float: ...
+
+class PSOMutationProtocol(Protocol):
+    def __init__(
+        self, strategy: str, scale: float, probability: float, application: str
+    ) -> None: ...
+    @property
+    def strategy(self) -> str: ...
+    @property
+    def scale(self) -> float: ...
+    @property
+    def probability(self) -> float: ...
+    @property
+    def application(self) -> str: ...
+
+class PSOVelocityProtocol(Protocol):
+    def __init__(
+        self, clamp_factor: float | None = None, mutation_threshold: float | None = None
+    ) -> None: ...
+    @property
+    def clamp_factor(self) -> float | None: ...
+    @property
+    def mutation_threshold(self) -> float | None: ...
+
+class ParticleSwarmConfigProtocol(Protocol):
+    def __init__(
+        self,
+        num_particles: int = 20,
+        max_iterations: int = 1000,
+        verbose: bool = False,
+        inertia: PSOInertiaConstantProtocol | PSOInertiaChaoticProtocol | None = None,
+        acceleration: PSOAccelerationConstantProtocol
+        | PSOAccelerationTimeVaryingProtocol
+        | None = None,
+        mutation: PSOMutationProtocol | None = None,
+        velocity: PSOVelocityProtocol | None = None,
+        initialization: str = "uniform",
+        seed: int | None = None,
+    ) -> None: ...
+
+class OptimizationConfigProtocol(Protocol):
+    @staticmethod
+    def nelder_mead(
+        config: NelderMeadConfigProtocol | None = None,
+    ) -> OptimizationConfigProtocol: ...
+    @staticmethod
+    def particle_swarm(
+        config: ParticleSwarmConfigProtocol | None = None,
+    ) -> OptimizationConfigProtocol: ...
+
+class CalibrationResultProtocol(Protocol):
+    @property
+    def best_parameters(self) -> dict[str, float]: ...
+    @property
+    def best_parameters_list(self) -> list[float]: ...
+    @property
+    def parameter_names(self) -> list[str]: ...
+    @property
+    def final_loss(self) -> float: ...
+    @property
+    def iterations(self) -> int: ...
+    @property
+    def converged(self) -> bool: ...
+    @property
+    def termination_reason(self) -> str: ...
+    def to_dict(self) -> dict[str, object]: ...
+
+class CalibrationEvaluationProtocol(Protocol):
+    def __init__(
+        self,
+        parameters: list[float],
+        loss: float,
+        predictions: list[list[float]],
+    ) -> None: ...
+    @property
+    def parameters(self) -> list[float]: ...
+    @property
+    def loss(self) -> float: ...
+    @property
+    def predictions(self) -> list[list[float]]: ...
+
+class CalibrationResultWithHistoryProtocol(Protocol):
+    @property
+    def best_parameters(self) -> dict[str, float]: ...
+    @property
+    def best_parameters_list(self) -> list[float]: ...
+    @property
+    def parameter_names(self) -> list[str]: ...
+    @property
+    def final_loss(self) -> float: ...
+    @property
+    def iterations(self) -> int: ...
+    @property
+    def converged(self) -> bool: ...
+    @property
+    def termination_reason(self) -> str: ...
+    @property
+    def evaluations(self) -> list[CalibrationEvaluationProtocol]: ...
+
+class ParetoSolutionProtocol(Protocol):
+    @property
+    def ensemble_size(self) -> int: ...
+    @property
+    def ci_width(self) -> float: ...
+    @property
+    def coverage(self) -> float: ...
+    @property
+    def size_penalty(self) -> float: ...
+    @property
+    def selected_indices(self) -> list[int]: ...
+
+class EnsembleSelectionResultProtocol(Protocol):
+    @property
+    def selected_ensemble(self) -> list[int]: ...
+    @property
+    def pareto_front(self) -> list[ParetoSolutionProtocol]: ...
+    @property
+    def selected_pareto_index(self) -> int: ...
+
+class CalibrationModule(Protocol):
+    ObservedDataPoint: type[ObservedDataPointProtocol]
+    CalibrationParameterType: type[CalibrationParameterTypeProtocol]
+    CalibrationParameter: type[CalibrationParameterProtocol]
+    CalibrationConstraint: type[CalibrationConstraintProtocol]
+    LossConfig: type[LossConfigProtocol]
+    NelderMeadConfig: type[NelderMeadConfigProtocol]
+    PSOInertiaConstant: type[PSOInertiaConstantProtocol]
+    PSOInertiaChaotic: type[PSOInertiaChaoticProtocol]
+    PSOAccelerationConstant: type[PSOAccelerationConstantProtocol]
+    PSOAccelerationTimeVarying: type[PSOAccelerationTimeVaryingProtocol]
+    PSOMutation: type[PSOMutationProtocol]
+    PSOVelocity: type[PSOVelocityProtocol]
+    ParticleSwarmConfig: type[ParticleSwarmConfigProtocol]
+    OptimizationConfig: type[OptimizationConfigProtocol]
+    CalibrationResult: type[CalibrationResultProtocol]
+    CalibrationEvaluation: type[CalibrationEvaluationProtocol]
+    CalibrationResultWithHistory: type[CalibrationResultWithHistoryProtocol]
+    ParetoSolution: type[ParetoSolutionProtocol]
+    EnsembleSelectionResult: type[EnsembleSelectionResultProtocol]
+
+    def calibrate(
+        self,
+        engine: DifferenceEquationsProtocol,
+        observed_data: list[ObservedDataPointProtocol],
+        parameters: list[CalibrationParameterProtocol],
+        constraints: list[CalibrationConstraintProtocol],
+        loss_config: LossConfigProtocol,
+        optimization_config: OptimizationConfigProtocol,
+        initial_population_size: int,
+    ) -> CalibrationResultProtocol: ...
+    def calibrate_with_history(
+        self,
+        engine: DifferenceEquationsProtocol,
+        observed_data: list[ObservedDataPointProtocol],
+        parameters: list[CalibrationParameterProtocol],
+        constraints: list[CalibrationConstraintProtocol],
+        loss_config: LossConfigProtocol,
+        optimization_config: OptimizationConfigProtocol,
+        initial_population_size: int,
+    ) -> CalibrationResultWithHistoryProtocol: ...
+    def run_multiple_calibrations(
+        self,
+        engine: DifferenceEquationsProtocol,
+        observed_data: list[ObservedDataPointProtocol],
+        parameters: list[CalibrationParameterProtocol],
+        constraints: list[CalibrationConstraintProtocol],
+        loss_config: LossConfigProtocol,
+        optimization_config: OptimizationConfigProtocol,
+        initial_population_size: int,
+        n_runs: int,
+        seed: int,
+    ) -> list[CalibrationResultWithHistoryProtocol]: ...
+    def select_optimal_ensemble(
+        self,
+        candidates: list[CalibrationEvaluationProtocol],
+        observed_data_tuples: list[tuple[int, int, float]],
+        population_size: int,
+        generations: int,
+        confidence_level: float,
+        seed: int,
+        pareto_preference: float,
+        ensemble_size_mode: str,
+        ensemble_size: int | None = None,
+        ensemble_size_min: int | None = None,
+        ensemble_size_max: int | None = None,
+        ci_margin_factor: float = 0.1,
+        ci_sample_sizes: list[int] | None = None,
+        nsga_crossover_probability: float = 0.9,
+    ) -> EnsembleSelectionResultProtocol: ...
+    def deduplicate_evaluations(
+        self,
+        evaluations: list[CalibrationEvaluationProtocol],
+        tolerance: float,
+    ) -> list[CalibrationEvaluationProtocol]: ...
+    def generate_predictions_parallel(
+        self,
+        engine: DifferenceEquationsProtocol,
+        parameter_sets: list[list[float]],
+        parameter_names: list[str],
+        time_steps: int,
+    ) -> list[list[list[float]]]: ...
+    def select_cluster_representatives(
+        self,
+        evaluations: list[CalibrationEvaluationProtocol],
+        cluster_labels: list[int],
+        max_representatives: int,
+        elite_fraction: float,
+        strategy: str,
+        selection_method: str = "crowding_distance",
+        quality_temperature: float = 1.0,
+        seed: int = 42,
+        k_neighbors_min: int = 5,
+        k_neighbors_max: int = 10,
+        sparsity_weight: float = 2.0,
+        stratum_fit_weight: float = 10.0,
+    ) -> list[int]: ...
+
+class MathExpressionProtocol(Protocol):
+    def __init__(self, expression: str) -> None: ...
+    def validate(self) -> None: ...
+
+class RateMathExpressionProtocol(Protocol):
+    @staticmethod
+    def from_string_py(s: str) -> RateMathExpressionProtocol: ...
+    @staticmethod
+    def parameter(name: str) -> RateMathExpressionProtocol: ...
+    @staticmethod
+    def formula(formula: str) -> RateMathExpressionProtocol: ...
+    @staticmethod
+    def constant(value: float) -> RateMathExpressionProtocol: ...
+    def py_get_variables(self) -> list[str]: ...
+
+class CoreModule(Protocol):
+    Model: type[RustModelProtocol]
+    Population: type[PopulationProtocol]
+    DiseaseState: type[DiseaseStateProtocol]
+    Stratification: type[StratificationProtocol]
+    StratificationCondition: type[StratificationConditionProtocol]
+    StratifiedRate: type[StratifiedRateProtocol]
+    Transition: type[TransitionProtocol]
+    Parameter: type[ParameterProtocol]
+    InitialConditions: type[InitialConditionsProtocol]
+    StratificationFraction: type[StratificationFractionProtocol]
+    StratificationFractions: type[StratificationFractionsProtocol]
+    Condition: type[ConditionProtocol]
+    Rule: type[RuleProtocol]
+    LogicOperator: type[LogicOperators]
+    ModelTypes: type[ModelTypes]
+    VariablePrefixes: type[VariablePrefixes]
+    Dynamics: type[DynamicsProtocol]
+    MathExpression: type[MathExpressionProtocol]
+    RateMathExpression: type[RateMathExpressionProtocol]
+
+class RustEpiModelModule(Protocol):
+    core: CoreModule
+    difference: DifferenceModule
+    calibration: CalibrationModule
+
+core: CoreModule
+difference: DifferenceModule
+calibration: CalibrationModule
+rust_epimodel: RustEpiModelModule