Skip to main content

​
Overview

Veydra runs Python-based system dynamics models entirely in your browser — no server, no downloads, no local Python installation required. When you open a model, Veydra automatically sets up a complete scientific Python environment using WebAssembly, fetches the model source code, and executes it locally on your machine. This page explains the full lifecycle: how models are loaded, how the Python runtime is initialized, and what happens behind the scenes when you click “Run.”

​
How It Works

1

Open a Model

Navigate to any model via the Model Playground. Veydra immediately begins the auto-initialization process.
2

Python Runtime Loads

Veydra downloads and boots Pyodide — a complete Python interpreter compiled to WebAssembly — directly in your browser. Core scientific packages (numpy, scipy) are loaded automatically.
3

Model Code Is Fetched

The model’s Python source files are downloaded from cloud storage, cached locally in your browser’s IndexedDB, and written into a virtual filesystem inside the Python runtime.
4

Model Executes Locally

The Python model code runs on your machine. Results (stocks, flows, time series) are rendered as interactive charts. All computation happens in your browser — nothing is sent to a server.

​
The Pyodide Runtime

Veydra uses Pyodide v0.25.0, a port of CPython to WebAssembly, to run Python natively in the browser.

​
What Gets Loaded

PackagePurpose
Pyodide CoreFull CPython 3.11 interpreter (~10 MB)
NumPyArray computation and mathematical operations
SciPyScientific computing, ODE solvers, optimization
micropipDynamic package installation if needed
Pyodide is loaded from a CDN with automatic fallback across three providers (jsDelivr, unpkg, cdnjs) for reliability.

​
Performance

  • WebAssembly execution delivers near-native speed for numerical computation
  • First load takes a few seconds while the runtime downloads and initializes
  • Subsequent visits are faster because your browser caches the Pyodide files

​
Model Loading & Caching

​
How Model Files Are Fetched

When you open a model, Veydra:
  1. Requests the model’s file index from the Veydra API
  2. Downloads all source files (src/ and config/) in parallel via signed URLs
  3. Stores everything in IndexedDB for fast reloads

​
Local Cache Details

Veydra maintains an intelligent local cache using IndexedDB:

Up to 5 Models Cached

The most recent 5 models are kept locally. Older models are evicted automatically (LRU).

100 MB Budget

The cache respects a 100 MB storage budget. If the quota is exceeded, only the 2 most recent models are retained.

1-Hour Index Expiry

File indexes refresh after 1 hour to pick up model updates.

Instant Chart Restore

Cached simulation results are displayed immediately while the Python runtime loads in the background.
If a model seems stale, use the Refresh button or clear your browser’s site data to force a fresh download.

​
Model Execution

​
Virtual Filesystem

When models execute, Veydra creates an isolated virtual filesystem inside the Pyodide environment: 
/home/pyodide/<model_namespace>/
├── src/
│   ├── __init__.py
│   ├── model.py              # Main model entry point
│   ├── veydra_model_standard.py  # Standard library
│   └── <submodels>.py        # Additional model modules
└── config/
    └── outputs.json           # Output variable configuration
Each model runs in its own isolated namespace, preventing conflicts between models.

​
The Model Contract

Every Veydra model exposes two core functions: 
def initialize_model():
    """Set up the model and return default results."""
    # Returns: (model_instance, default_results)
    ...

def run_interactive_simulation(model_instance, params):
    """Run the model with the given parameter overrides."""
    # Returns: dict with 'stocks', 'flows', 'time', etc.
    ...
  • initialize_model() is called once when the model first loads, producing the baseline results you see on the charts.
  • run_interactive_simulation() is called each time you adjust a slider or change parameters, re-running the simulation with your new values.

​
What Happens When You Move a Slider

1

Parameter Change Detected

The UI captures the new slider value and builds a parameter dictionary.
2

Python Simulation Runs

run_interactive_simulation() executes locally in Pyodide with the updated parameters.
3

Results Render

Time series data is returned to JavaScript and rendered on the interactive charts in real time.
4

Results Cached

The latest results are saved to IndexedDB so they load instantly next time you visit.

​
Initialization States

The Model Playground shows a progress indicator as the model loads. Here’s what each phase means:
PhaseWhat’s Happening
Loading PyodideDownloading and booting the Python WebAssembly runtime
Loading FilesFetching model source code and writing it to the virtual filesystem
Initializing ModelExecuting initialize_model() and rendering default charts
ReadyModel is fully loaded — adjust parameters and run simulations
If initialization fails (e.g., due to a network issue), you can retry by refreshing the page. Cached files will be reused where possible.

​
Security & Privacy

Because models run entirely in your browser:
  • Your data stays local — simulation inputs and results never leave your machine during execution
  • No server compute costs — all processing uses your device’s CPU
  • Isolated execution — each model runs in a sandboxed Python namespace within WebAssembly, which itself runs in the browser’s security sandbox

​
Requirements

Modern Browser

Chrome, Edge, Firefox, or Safari with WebAssembly support (all modern versions)

Internet Connection

Required for the initial load of Pyodide and model files. Cached models can display prior results offline, but new simulations require the runtime.
No local Python installation, no pip install, no terminal commands. Everything runs in the browser automatically.

​
Installing Veydra as a Desktop App

Veydra can be installed as a Progressive Web App (PWA) on desktop and mobile for a more native experience.

​
How to Install

  1. Visit app.veydra.io
  2. Click the install icon in the address bar (or go to ⋮ → Install Veydra)
  3. Confirm the installation
  4. Veydra opens in its own window and appears in your Start Menu / Dock
Firefox does not currently support PWA installation on desktop. Use Veydra in a regular browser tab.
  1. Visit app.veydra.io in your mobile browser
  2. Tap Share → Add to Home Screen
  3. Veydra appears as an app icon on your home screen
The installed app behaves identically to the browser version — same models, same performance, same account. It just runs in its own window without the browser toolbar.