An individual-based simulation framework for studying antimicrobial use, antimicrobial resistance (AMR), infection outcomes, and potential policy interventions across a broad bacterial and antibacterial ecosystem.

The current executable configuration represents:

• 42 bacteria
• 62 individual antibacterial drugs
• 39 internal drug classes
• 46 resistance mechanisms
• 6 world regions
• daily simulation from 1930 to 2025 for calibration, or to 2035 for policy branches

The framework is under active development and calibration. It is intended for research and policy analysis, not for diagnosis, prescribing, or individual clinical decision-making. A formal open-source licence has not yet been selected, so this repository is not yet a released software version.

The model follows simulated people through demographic change, bacterial infection and carriage, symptoms and sepsis, diagnostic testing, antibacterial treatment, resistance dynamics, and mortality.

Resistance can be introduced or altered through:

• resistance profiles sampled at infection or carriage acquisition
• de novo mechanism emergence under relevant drug pressure
• horizontal gene transfer for eligible mobile mechanisms
• mechanism reversion and fitness costs
• treatment selection and differential bacterial clearance
• regional and care-setting resistance history
• a bounded local persistence archive representing resistant strains circulating outside the finite simulated sample

Infection incidence is externally parameterised. The model does not dynamically generate infection incidence from the prevalence of infected people. Its dynamic population interaction concerns resistance profiles and treatment pressure rather than explicit person-to-person transmission.

The framework deliberately does not model organism-drug MIC values or detailed drug-specific PK/PD. Resistance severity is represented by bounded model quantities such as any_r, while Figure 2 calibration prevalence is based on whether any_r > 0.

See the technical model description for the complete scientific and implementation specification.

The executable inventories are defined in:

• BACTERIA_LIST in src/simulation/population.rs
• DRUG_SHORT_NAMES in src/simulation/population.rs
• ResistanceMechanism::all() in src/simulation/population.rs

Current parameter values are defined in src/config.rs. Files under archive/ are historical evidence only and are not model or analysis inputs. Repository tests protect the dimensions and relationships between the executable inventories, parameters, targets, and output schema.

• Rust stable with Cargo; the crate uses Rust edition 2021
• Python 3.10 or later for analysis
• Substantial RAM and runtime for research-scale simulations

The Python environment is currently specified by lower bounds in requirements.txt; a frozen release environment is still to be added.

cargo build --release
cargo test --all-targets

The default binary is executable_amr.

cargo run --release

Run settings are currently selected near the top of main() in src/main.rs. The checked-in configuration uses a population of 3,000,000, CalibrationMode::Full, random seeding, and no individual or infection-journey logging. This is a long research run, not a quick installation test.

For a smoke test only, temporarily use a much smaller population_size. Outputs from a small population must not be interpreted as calibrated model results.

time_steps is selected from the mode in src/main.rs: 35,040 days for calibration modes and 38,325 days for the full policy horizon.

The launcher generates and records a random u64 seed unless fixed seeding is enabled. AMR_RNG_SEED overrides the source setting and is the preferred way to replay a run.

PowerShell:

$env:AMR_RNG_SEED = "1234567890"
cargo run --release

Bash:

AMR_RNG_SEED=1234567890 cargo run --release

Fixed-seed runs use named ChaCha RNG streams and deterministic population chunks. For the same source, configuration, and seed, summary output is expected to be reproducible across repeated runs and different RAYON_NUM_THREADS settings.

Rayon uses the available logical cores unless RAYON_NUM_THREADS is set.

PowerShell:

$env:RAYON_NUM_THREADS = "4"
cargo run --release

Bash:

RAYON_NUM_THREADS=4 cargo run --release

Simulation outputs are written under amr_simulation_output_analysis_outputs/. A completed run normally produces:

• simulation_summary_NNNNNN.csv
• run_metadata_<timestamp>_seed_<seed>.txt
• config_validation_<timestamp>.txt

The summary CSV uses output schema version 1. Its fields depend on the selected run mode and can number in the tens of thousands. The metadata records the source hash, seed and seed source, run ID, population, time steps, mode, policies, thread count, duration, output path, CSV SHA-256 hash, validation status, and completion or failure state.

The source hash can be supplied by AMR_SOURCE_HASH or source_hash.txt. Otherwise the launcher uses the current Git commit and marks a dirty worktree. For formal analyses, retain the metadata file and exact source snapshot with the CSV.

Parameter validation is strict by default. AMR_CONFIG_VALIDATION=warn permits a diagnostic run to continue despite validation errors, but such a run should not be used as a calibrated research result.

Create an environment and install the current analysis dependencies:

python -m venv .venv
python -m pip install -r requirements.txt

Activate the environment using the command appropriate for the operating system. Select the input CSV through DataConfig.simulation_file in amr_simulation_output_analysis/config.py, then run:

python -m amr_simulation_output_analysis.amr_analysis

The analysis writes calibration summaries and configured plots under output_graphs/. Plot selection, policies, output format, caching, and memory settings are controlled by PlotConfig in amr_simulation_output_analysis/config.py.

Run the Python regression tests from the repository root with:

python -m unittest discover -s tests -p "test_*.py"

The current calibration combines sourced estimates, transformed comparisons, evidence-informed benchmarks, and transparent expert-informed placeholders. These categories must not be treated as interchangeable observations.

Key provenance documents are:

• Resistance target provenance
• Comparison overlay provenance
• data/resistance_targets_v1.manifest.json

Best-guess placeholder overlays are disabled by default and are not calibration score inputs.

CalibrationMode::None can run five independent branches from 2027:

These branches are research scenarios and should not be interpreted as validated policy forecasts without scenario-specific calibration, uncertainty analysis, and suitable comparison across well-fitting parameter sets.

src/
  main.rs                         Run launcher and provenance
  config.rs                       Model parameters
  config_validation.rs            Parameter validation
  observability.rs                Run/source observability
  rules/mod.rs                    Daily individual-level rules
  simulation/
    population.rs                 State, inventories, and enums
    simulation.rs                 Simulation loop, caches, branches, CSV export
    journey_logger.rs             Optional sampled infection journeys

amr_simulation_output_analysis/   Python analysis package
data/                             Calibration targets and comparison data
model_description/                Technical model description
tests/                            Rust integration and Python regression tests
paper_tables/                     Generated manuscript tables and figures
archive/                          Historical, non-executable material

Sampled infection-journey logging can be enabled in src/main.rs for illustrative or diagnostic work. It records much denser individual traces and can materially slow a run, so it is disabled for routine calibration.

Contribution guidance, citation metadata, a stable run configuration interface, a locked Python environment, and a formal release archive are still being prepared. Until those are available, please treat the repository as an active research workspace rather than a stable public API.

No software licence has yet been selected. A standard open-source licence and the appropriate UCL/contributor copyright notice must be added before formal public release and reuse.