Skip to main content

AdaSurroG

AdaSurroG trains fast, differentiable surrogate models for parameterized ordinary differential equation systems. It is designed for repeated-query scientific workflows such as parameter studies, uncertainty quantification, optimization, and systems-biology simulation.

The default high-precision pipeline uses a fixed high-fidelity dataset and combines:

  • automatic state transforms for multiscale variables;
  • adaptive fixed output-time selection from pilot trajectories;
  • proper orthogonal decomposition (POD) trajectory compression;
  • a Chebyshev polynomial coefficient backbone;
  • a residual PyTorch network;
  • time/accuracy-bounded AdamW training;
  • deterministic CPU float64 full-batch L-BFGS refinement;
  • resumable atomic checkpoints and explicit accuracy diagnostics.

AdaSurroG trains one surrogate per mechanistic ODE model. The pipeline is generic: users provide the ODE definition, parameter bounds, initial conditions, and time interval rather than manually designing a new neural architecture for each model.

Installation

Install the universal ODE pipeline:

python -m pip install "adasurrog[universal]"

Install plotting utilities and all runtime extras:

python -m pip install "adasurrog[all]"

For development from a source checkout:

python -m pip install -e ".[dev]"

Python 3.10–3.13 is supported. PyTorch is a required dependency. SciPy is required for generating ODE reference trajectories, and PyYAML is required for YAML-based training configurations.

Quick start: built-in benchmark

List the included benchmark models:

adasurrog-benchmark --list

Train a surrogate for the SEIR benchmark:

adasurrog-benchmark \
  --problem seir \
  --train 192 \
  --validation 48 \
  --test 48 \
  --target-rmse 0.002 \
  --training-seconds 900 \
  --lbfgs-seconds 300

The pipeline writes its dataset, checkpoints, pilot diagnostics, and final certification report under the selected run directory.

YAML training

problem:
  factory: benchmark:seir

sampling:
  pilot_trajectories: 24
  train_trajectories: 192
  validation_trajectories: 48
  test_trajectories: 48
  time_points: 128
  seed: 17

accuracy:
  target_rmse: 0.002
  target_p99: 0.01
  pod_floor_fraction: 0.30

budget:
  training_seconds: 900
  lbfgs_seconds: 300

surrogate:
  weighted_pod: auto
  rank_candidates: [4, 8, 12, 16, 24, 32, 48, 64]
  polynomial_degrees: [1, 2, 3, 4]

runtime:
  run_directory: runs/universal_seir
  device: mps
  lbfgs_device: cpu
  resume: none

storage:
  mode: compact
  dataset_dtype: float32
  checkpoint_dtype: float32
  keep_dataset: true
  minimum_free_disk_gb: 5.0

Run it with:

adasurrog-train examples/universal/seir.yaml

On Apple Silicon, AdamW may run on MPS while float64 L-BFGS runs on CPU.

Define a custom ODE problem

import numpy as np

from adasurrog import ODEProblem


def create_problem() -> ODEProblem:
    def rhs(time, state, parameters):
        del time
        production, degradation = parameters
        return np.array([production - degradation * state[0]])

    def jacobian_state(time, state, parameters):
        del time, state
        return np.array([[-parameters[1]]])

    return ODEProblem(
        name="production_degradation",
        state_names=("concentration",),
        parameter_names=("production", "degradation"),
        parameter_lower=np.array([0.1, 0.05]),
        parameter_upper=np.array([10.0, 2.0]),
        time_span=(0.0, 20.0),
        rhs_function=rhs,
        initial_condition_function=lambda parameters: np.array([0.0]),
        jacobian_state_function=jacobian_state,
    )

Reference the factory from YAML:

problem:
  factory: my_models.production_degradation:create_problem

Parameters currently require strictly positive lower bounds because the default pipeline uses a normalized log-parameter box.

Python API

from pathlib import Path

from adasurrog import (
    AccuracyConfig,
    AutoPipelineConfig,
    BudgetConfig,
    SamplingConfig,
    UniversalODEPipeline,
)
from my_models.production_degradation import create_problem

config = AutoPipelineConfig(
    sampling=SamplingConfig(
        pilot_trajectories=16,
        train_trajectories=128,
        validation_trajectories=32,
        test_trajectories=32,
        time_points=96,
    ),
    accuracy=AccuracyConfig(target_rmse=1e-3),
    budget=BudgetConfig(training_seconds=600, lbfgs_seconds=180),
    run_directory=Path("runs/production_degradation"),
)

surrogate, report = UniversalODEPipeline(create_problem(), config).fit()
print(report.status, report.validation_rmse, report.test_rmse)

Load and query a trained surrogate

import numpy as np

from adasurrog import AdaSurrogate

surrogate = AdaSurrogate.load(
    "runs/production_degradation/checkpoints/universal_best.pt",
    device="cpu",
)

trajectory = surrogate.predict(
    parameters=np.array([2.0, 0.4]),
)

selected_times = surrogate.predict(
    parameters=np.array([2.0, 0.4]),
    time=np.linspace(0.0, 20.0, 50),
)

check = surrogate.check_domain(np.array([2.0, 0.4]))
print(check.inside)

Physical query times are accepted directly. A checkpoint contains the POD representation, coefficient model, state transforms, parameter domain, time grid, and training report; the original training dataset is not required for inference.

Stopping, checkpoint, and disk behavior

Training is controlled by a validation target and cumulative wall-clock budget instead of a fixed epoch count. Since version 0.5.2, storage.mode: compact is the default. Compact mode keeps only the float32 deployment checkpoint, fixed dataset, and diagnostics:

runs/<problem>/
├── data/fixed_dataset.npz
├── pilot_diagnostics.json
├── universal_diagnostics.json
└── checkpoints/
    └── universal_best.pt

It does not retain AdamW/L-BFGS optimizer histories, periodic checkpoints, terminal duplicates, or exception checkpoints. This is the recommended setting for benchmark matrices. Interrupted compact runs restart from the same fixed Sobol design.

Use storage.mode: resumable when mid-run resume is required. It keeps one latest optimizer-state checkpoint but no periodic history. storage.mode: full preserves the legacy debugging behavior.

Remove redundant checkpoints produced by older releases with a dry run followed by deletion:

adasurrog-clean-runs runs --show-files
adasurrog-clean-runs runs --apply

Add --remove-datasets only when regenerated high-fidelity data are not needed.

Inspect a checkpoint:

adasurrog checkpoint-info runs/my_model/checkpoints/universal_best.pt

Inspect the installed environment:

adasurrog info

Accuracy diagnostics

The final report classifies a run as one of:

  • certified (legacy label meaning the configured validation target was met; it is not a formal certificate);
  • representation_limited;
  • regression_limited;
  • data_limited;
  • optimization_limited;
  • tail_error_limited.

The report includes validation and test errors, explicit validation_target_met and test_target_met booleans, the POD representation floor, selected POD rank, selected polynomial model, and regression amplification over the POD floor. The legacy status is derived from validation diagnostics only; it is not a statistical guarantee or a certificate of held-out test accuracy. A failure to reach a target is therefore reported diagnostically rather than hidden behind a final loss value.

Included benchmark models

  • Robertson kinetics: severe stiffness, conservation, and scale separation;
  • Lotka–Volterra: nonlinear oscillation and phase sensitivity;
  • Brusselator: limit-cycle dynamics and nearby bifurcation behavior;
  • SEIR: nonnegative compartment dynamics, conservation, and a transient peak.

Legacy and experimental commands

The distribution retains the gene-feedback examples and the earlier pool-based active-learning prototype for reproducibility. The recommended production path is adasurrog-train or the UniversalODEPipeline; active learning is not part of the default automatic pipeline.

Experimental trajectory CorrectNet

AdaSurroG 0.5.7 provides a second-stage GatedCorrectNet for structured errors that remain after BaseNet training. The BaseNet remains frozen. CorrectNet receives the projected BaseNet trajectory, its finite-difference ODE defect, normalized parameters, and time coordinates. It predicts a gated residual trajectory.

State geometry is explicit rather than hard-coded:

  • signed: negative and positive states are allowed;
  • positive: nonnegative states;
  • box: fixed lower and upper bounds;
  • mixed: per-state combinations of signed, positive, and box domains;
  • none or linear invariants of the form C y = b.

Correction geometry is selected explicitly: simplex_logit for equal-total nonnegative systems, positive_log_projected for nonnegative non-conserved systems, and additive_projected for signed/mixed states and general linear invariants. Candidate trajectories are projected to the declared convex feasible set and blended through the learned gate. A positive zero-lower-bound domain with C = [1, ..., 1] reproduces the conserved-simplex use case. Nonlinear invariants are not included in 0.5.7. See CORRECTNET.md and examples/correctnet/.

CorrectNet reporting is split into global performance, benefit-harm balance, and practical case outcomes. The global group includes case CVaR90/CVaR95. Benefit-harm metrics compare the total absolute tail gains with the total absolute easy-case harm. Practical outcomes use configurable absolute and relative tolerances, so numerically tiny changes in already-accurate cases do not dominate deployment acceptance.

The standard validation decision is available as evaluate_correctnet_acceptance(), so notebooks and production code use the same policy. Deployment bundle creation and loading validate BaseNet/CorrectNet parameter domains, state counts, physical output grids, required rhs_torch, and parameter/state metadata before inference.

Current scope

Version 0.5.7 supports continuous parameterized ODE initial-value problems with strictly positive parameter bounds and fixed simulation horizons. Global unweighted or metric-weighted POD is used for trajectory representation. Event resets, discontinuous controls, automatic state/time-blocked POD, nonlinear latent representations, derivative-supervised training, and nonlinear invariant projection are not yet automatic. The experimental CorrectNet helper currently accepts autonomous batched RHS functions on a fixed shared output grid and supports signed or bounded states with optional static linear invariants. Deployable target="initial" invariants require an exact linear_invariant_target_torch(parameters) problem function.

Reproducibility

sampling.seed now seeds Python, NumPy, PyTorch, the Sobol design, and shuffled training batches in the universal pipeline. Set sampling.deterministic_algorithms: true to require deterministic PyTorch algorithms where they are available; this can reject unsupported accelerator operations.

Citation

See CITATION.cff for citation metadata. Release history is recorded in CHANGELOG.md.

License

AdaSurroG is distributed under the MIT License.

Metadata

Release files for adasurrog 0.5.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adasurrog 0.5.7
File Size Uploaded Provenance Actions
adasurrog-0.5.7.tar.gz 107.3 kB Without provenance Details for adasurrog-0.5.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adasurrog 0.5.7
File Interpreter ABI Platform Actions
adasurrog-0.5.7-py3-none-any.whl Python 3 none any Details for adasurrog-0.5.7-py3-none-any.whl

Total release size: 209.4 kB

Release files / adasurrog-0.5.7.tar.gz

Download URL adasurrog-0.5.7.tar.gz
Size 107.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0dfcf47aa9c8d9d6e63ecdbe062cf47a7717df2c9c6ce5d30b30a4227272c1fe
BLAKE2b-256 checksum
How to use checksums
aabf3f57f39d1b9f6fa9896739e902bf2858df7c04a62d4e9ba59662bff8a8c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Release files / adasurrog-0.5.7-py3-none-any.whl

Download URL adasurrog-0.5.7-py3-none-any.whl
Size 102.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a85505480aa9533934b8fb3d727dadd201a9272290d4e65c0a08557ea931c14
BLAKE2b-256 checksum
How to use checksums
82ea4b47618f0e062026e724e8c444c45c35c8d2264df89ab3ee81ea2bff49ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Security for adasurrog 0.5.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page