Running Models Locally

You can find your model’s GitHub repository URL in the model’s Settings page on app.veydra.io. For more details on how models connect to GitHub, see GitHub Integration.

Overview

Every Veydra model is a standalone Python project hosted on GitHub. You can clone any model repository and run it locally with standard Python tooling — no special platform or runtime required. This page walks through the repository structure, setup, execution, and testing workflow that all models follow.

Quick Start

Clone the Repository

Each model lives in its own GitHub repo. Clone it to your machine:

git clone <model-repo-url>
cd veydra-model-<id>

Create a Virtual Environment

python -m venv .venv
source .venv/bin/activate        # macOS / Linux
.\.venv\Scripts\activate         # Windows

Install Dependencies

pip install -r requirements.txt

Run the Model

python main.py

Requirements

Python 3.11+

A local Python installation. Any recent 3.11+ version works.

pip

Used to install dependencies from requirements.txt.

Dependencies

All models declare their dependencies in requirements.txt. A typical model requires:

Package	Purpose
veydra-model-standard	Base classes and utilities for VMS-compliant models
NumPy	Array computation and mathematical operations
SciPy	Scientific computing, ODE solvers, optimization
pytest	Running the test suite

Repository Structure

Every model repository follows the same layout:

veydra-model-<id>/
├── main.py                        # CLI entry point
├── requirements.txt               # Python dependencies
├── test_main.py                   # pytest test suite (generic VMS tests)
├── test_model.py                  # Quick smoke tests
├── src/
│   ├── model.py                   # Main model orchestrator
│   ├── veydra_model_standard.py   # VMS base classes (Submodel, SimulationContext, etc.)
│   ├── <submodel_a>.py            # Domain-specific submodel
│   ├── <submodel_b>.py            # Domain-specific submodel
│   └── README.md                  # Model-specific documentation
└── config/
    ├── outputs.json               # Which stocks & flows to include in results
    ├── model-parameters.json      # Full parameter metadata (ranges, units, defaults)
    ├── presets.json                # Named parameter presets / scenarios
    └── flow-diagram.json          # Visual layout for the flow diagram

Key Files

main.py

The command-line entry point. Initializes the model, runs a default simulation, then runs an interactive simulation with the same defaults to validate the full pipeline.

python main.py

src/model.py

Contains the master orchestrator class (inherits from VeydraModelStandard) and the two contract functions — initialize_model() and run_interactive_simulation(). This is where submodels are wired together, derivatives are computed, and the ODE solver is invoked.

config/outputs.json

Controls which stocks and flows are included in simulation results. All variables are computed internally, but only those listed here are returned.

{
  "stocks": [
    "population.s_population",
    "resource.s_resource_stock"
  ],
  "flows": [
    "population.population_growth_flow",
    "resource.resource_extraction_flow"
  ]
}

config/presets.json

Defines named scenarios with specific parameter overrides. Each preset has an id, a description, and a variables dict of parameter values.

config/model-parameters.json

Full metadata for every parameter: label, min/max, step, default, units, category, and namespace. Generated automatically by the Veydra AST analysis pipeline.

The Model Contract

Every VMS-compliant model exposes two functions from src/model.py:

def initialize_model():
    """Set up the model and return default results."""
    # Returns: (model_instance, default_results)
    ...

def run_interactive_simulation(model_instance, params, return_json=False):
    """Run the model with the given parameter overrides."""
    # Returns: dict with 'success', 'stocks', 'flows', 'time', etc.
    ...

initialize_model() — creates the model instance, runs a simulation with default parameters, and returns both the instance and the default results dict.
run_interactive_simulation() — takes an existing model instance and a dict of parameter overrides, re-runs the simulation, and returns updated results. Pass return_json=True to get a JSON string instead of a Python dict.

Results Format

Both functions return a results dictionary with this shape:

{
    "success": True,
    "stocks": {
        "population.s_population": [1000.0, 1010.2, ...],
        "resource.s_resource_stock": [10000.0, 9989.8, ...],
    },
    "flows": {
        "population.population_growth_flow": [20.0, 20.1, ...],
        "resource.resource_extraction_flow": [10.2, 10.1, ...],
    },
    "time": [0.0, 0.125, 0.25, ...],
    "dates": ["2024-01-01", "2024-02-15", ...],
}

Stock and flow keys use the full namespaced parameter name (submodel.variable_name).

Running Simulations

Default Run

python main.py

This initializes the model with default parameters and prints key outputs to the console.

Custom Parameters

You can override parameters programmatically by passing a dictionary to run_interactive_simulation():

from src.model import initialize_model, run_interactive_simulation

model, defaults = initialize_model()

# Override specific parameters
params = {
    "population.population_growth_rate": {"value": 0.03},
    "resource.resource_extraction_rate_per_capita": {"value": 0.05},
}

results = run_interactive_simulation(model, params)
print(results["stocks"]["population.s_population"][-1])

Running Presets

Presets from config/presets.json can be loaded and passed directly:

import json
from src.model import initialize_model, run_interactive_simulation

model, _ = initialize_model()

with open("config/presets.json") as f:
    presets = json.load(f)["presetConditions"]

for preset in presets:
    params = {k: {"value": v} for k, v in preset["variables"].items()}
    results = run_interactive_simulation(model, params)
    print(f"{preset['id']}: success={results['success']}")

Testing

All models ship with two test files:

Smoke Tests

python test_model.py

Runs quick validation: can the model be imported, initialized, and executed?

Full Test Suite

pytest test_main.py -v

Uses pytest to run structured tests including:

Default parameters — model runs and returns valid numeric results
All presets — every preset from config/presets.json is run and validated automatically

The generic test_main.py works with any VMS-compliant model — it discovers presets automatically, so you don’t need to update tests when adding new scenarios.

Model Architecture

Submodels

Models are decomposed into submodels — one per domain (e.g., population_submodel.py, resource_submodel.py). Each submodel:

Defines its own VARIABLES dict with parameter metadata
Inherits from the Submodel base class in veydra_model_standard.py
Implements a calculate_derivatives_and_flows() method

The master orchestrator in src/model.py wires all submodels together, collects their derivatives, and passes them to SciPy’s ODE solver (solve_ivp).

Parameter Namespacing

All parameters use a submodel.variable_name naming convention to avoid collisions:

population.population_growth_rate
resource.resource_extraction_rate_per_capita
environmental_degradation.waste_generation_rate_per_capita
simulation.duration

Simulation Variables

In addition to submodel parameters, every model has a set of simulation.* variables controlling execution:

Variable	Default	Description
`simulation.duration`	200	Total simulation length (years)
`simulation.time_step`	0.125	Integration time step (years)
`simulation.start_date`	2024-01-01	Calendar start date
`simulation.intervention_start_time`	100	When interventions activate (years)

Getting Started

Platform Features

Model Playground

Simulation Components

Tools

Integrations

Development

Overview

Quick Start

Requirements

Python 3.11+

pip

Dependencies

Repository Structure

Key Files

The Model Contract

Results Format

Running Simulations

Default Run

Custom Parameters

Running Presets

Testing

Smoke Tests

Full Test Suite

Model Architecture

Submodels

Parameter Namespacing

Simulation Variables

​Overview

​Quick Start

​Requirements

Python 3.11+

pip

​Dependencies

​Repository Structure

​Key Files

​The Model Contract

​Results Format

​Running Simulations

​Default Run

​Custom Parameters

​Running Presets

​Testing

​Smoke Tests

​Full Test Suite

​Model Architecture

​Submodels

​Parameter Namespacing

​Simulation Variables

Overview

Quick Start

Requirements

Dependencies

Repository Structure

Key Files

The Model Contract

Results Format

Running Simulations

Default Run

Custom Parameters

Running Presets

Testing

Smoke Tests

Full Test Suite

Model Architecture

Submodels

Parameter Namespacing

Simulation Variables