CLI Reference

Command-line interface reference for PatchSim.

Overview

patchsim [COMMAND] [OPTIONS]

Available commands:

• init – Scaffold a new project

• run – Execute a simulation

• validate – Check configuration and inputs

• list-models – Show available templates

• --version – Display version

---

init

Initialize a new PatchSim project with starter files.

Usage

patchsim init PROJECT_NAME [--template TEMPLATE] [--force]

Arguments

Argument	Required	Description
PROJECT_NAME	Yes	Directory name for the new project

Options

Option	Default	Description
--template	sir	Starter model template: sir, seir, sirs, sis
--force	-	Overwrite target directory if it already exists

Examples

# Create a new SIR project (default)
patchsim init my-project

# Create with SEIR template
patchsim init my-project --template seir

# Overwrite existing directory
patchsim init my-project --force

Output

Creates a directory with:

config.yaml                              # Model configuration
data/
  patch/                                 # Patch population files
  seeds/                                 # Initial conditions
  networks/                              # Network topology (if multi-patch)
output/                                  # (Empty until run)

---

validate

Validate configuration file and input data for consistency.

Usage

patchsim validate [-c CONFIG] [--schema] [--json]

Options

Option	Required	Description
-c, --config	Conditional*	Path to config YAML file
--schema	-	Print the configuration JSON Schema
--json	-	Output validation results as JSON

*Required unless --schema is used.

Examples

# Validate a configuration file
patchsim validate -c config.yaml

# Print the JSON Schema for config files
patchsim validate --schema

# Validate and output JSON
patchsim validate -c config.yaml --json

Output (Plain Text)

Configuration is valid: config.yaml

Output (JSON)

{
  "ok": true,
  "config": "config.yaml",
  "model_name": "sample-sir-ode",
  "num_patches": 1,
  "patches": ["PatchA"]
}

Validation Checks

• All required fields present (see Configuration)

• Compartments defined and non-empty

• Transitions use valid compartments and parameters

• Patch file exists and is readable

• Seed file has correct structure

• Compartments match seed file columns

• Seed values sum to patch population

• Network file (if provided) is consistent

---

run

Execute a simulation and generate outputs.

Usage

patchsim run -c CONFIG [--json]

Options

Option	Required	Description
-c, --config	Yes	Path to configuration YAML file
--json	-	Output run summary as JSON

Examples

# Run a simulation
patchsim run -c config.yaml

# Run and capture output as JSON
patchsim run -c config.yaml --json

Output (Plain Text)

Starting PatchSim simulation...
Model: sample-sir-ode
Parameters: beta=0.5, gamma=0.1
Simulation completed successfully.

Output (JSON)

{
  "ok": true,
  "config": "config.yaml",
  "model_name": "sample-sir-ode",
  "output_dir": "output",
  "csv_path": "output/runs/all_patches_sample-sir-ode_ode.csv",
  "plot_path": "output/plots/patch_timeseries_sample-sir-ode_ode.png",
  "num_patches": 1,
  "patches": ["PatchA"],
  "t_max": 100
}

Output Files

Generates in OutputDir (from config):

File	Description
runs/all_patches_MODEL_ode.csv	Time series data (time + all compartments)
plots/patch_timeseries_MODEL_ode.png	Line plot of all compartments over time
logs/MODEL_run_*.log	Simulation log (detailed diagnostics)

See Results for output format details.

---

list-models

Display available starter templates.

Usage

patchsim list-models [--json]

Options

Option	Description
--json	Output model list as JSON

Examples

# List available templates
patchsim list-models

# Output as JSON
patchsim list-models --json

Output (Plain Text)

Built-in models and templates:
- seir (yaml-template)
- sir (yaml-template)
- sirs (yaml-template)
- sis (yaml-template)

Output (JSON)

{
  "models": [
    {"name": "seir", "kind": "yaml-template"},
    {"name": "sir", "kind": "yaml-template"},
    {"name": "sirs", "kind": "yaml-template"},
    {"name": "sis", "kind": "yaml-template"}
  ]
}

---

Global Options

--version

Display the installed PatchSim version.

patchsim --version

Output:

patchsim 0.1.0b1

---

Common Errors and Solutions

Error	Cause	Solution
Compartment mismatch	Seed file columns don’t match config	Update seed file or config compartments
Unknown names in expression	Typo in transition rate	Check parameter/compartment names in config
Refusing to overwrite	Target directory exists	Use --force or choose a different name
Missing required field	Config missing field (e.g., TMax)	See Configuration for required fields
Population mismatch	Seed values don’t sum to population	Fix seed file CSV