Courant — System Dynamics Modeling Tool

Current release: 1.0-Beta-0

The ability to reason about and make predictions on complex, dynamic systems is essential today. Courant is an open-source System Dynamics simulation engine and visual modeling environment written in Java. It was created so that, when it's ready, everyone will have access to a professional quality system dynamics environment for free.

It provides two ways to build and run models:

• Visual Editor — a JavaFX canvas-based GUI for interactively building stock-and-flow diagrams and causal loop diagrams
• Programmable Engine — a code-first Java API for defining, compiling, and running models programmatically

The engine supports creating training simulations, games, scenario testing, and planning models across domains including ecology, epidemiology, project management, software development, business strategy, economics, demographics, and supply chain management.

Feature Highlights

• Stock-and-flow modeling — stocks, flows, variables, constants, lookup tables, and subscripts/arrays
• Causal loop diagrams — CLD variables, signed causal links (+/−), automatic loop detection with reinforcing (R) / balancing (B) classification
• Equation editor — multi-line editor with syntax highlighting, function autocomplete, and inline canvas editing
• Simulation analysis — parameter sweep, multi-parameter sweep, Monte Carlo sampling, and optimization (BOBYQA, CMA-ES, Nelder-Mead)
• Scenario comparison — run multiple simulations with different parameters and overlay results as color-differentiated ghost runs
• Feedback loop analysis — automatic detection and highlighting of feedback loops in stock-and-flow diagrams
• Model validation — structural validation with error/warning indicators on canvas elements
• Delay detection — visual "D" badges on elements containing delay functions (SMOOTH, DELAY3, DELAY_FIXED)
• Canvas features — sparklines in stocks, resizable elements, undo/redo, zoom, diagram export (PNG/JPG)
• Import/export — Vensim .mdl import, XMILE import/export, native JSON persistence
• More than 100 bundled example models spanning causal loops, control theory, demographics, ecology, economics, education, environment, epidemiology, management, marketing, physics, policy, population, social dynamics, supply chain, technology adoption, urban systems, and more

Screenshots

Installation

Requirements

• Java 25 or later
• Maven 3.x (to build from source)

Build from Source

git clone https://github.com/Courant-Systems/courant.git
cd courant
mvn clean package -DskipTests

Run the Visual Editor

java -jar courant-app/target/courant-app-*.jar

Open an example model via File → Open Example to explore the 100+ bundled models.

Quick Start

Visual Editor

1. Launch the application
2. File → Open Example → Introductory → Exponential Growth to open a simple model
3. Click Simulate → Run Simulation to run it
4. Modify parameter values by double-clicking constants on the canvas
5. Re-run to compare results as ghost runs

See the Quickstart Tutorial for a 10-minute hands-on walkthrough building a coffee cooling model.

Programmable Engine

Build and run an SIR epidemic model in pure Java:

Model model = new Model("SIR Epidemic");

Stock susceptible = new Stock("Susceptible", 1000, PEOPLE);
Stock infectious  = new Stock("Infectious", 10, PEOPLE);
Stock recovered   = new Stock("Recovered", 0, PEOPLE);

Flow infection = Flow.create("Infection", DAY, () -> {
    double totalPop = susceptible.getValue() + infectious.getValue()
            + recovered.getValue();
    double infectiousFraction = infectious.getValue() / totalPop;
    return new Quantity(
            8.0 * infectiousFraction * 0.1 * susceptible.getValue(), PEOPLE);
});

Flow recovery = Flow.create("Recovery", DAY, () ->
        new Quantity(infectious.getValue() * 0.2, PEOPLE));

susceptible.addOutflow(infection);
infectious.addInflow(infection);
infectious.addOutflow(recovery);
recovered.addInflow(recovery);

model.addStock(susceptible);
model.addStock(infectious);
model.addStock(recovered);

Simulation sim = new Simulation(model, DAY, Times.weeks(8));
sim.addEventHandler(new StockLevelChartViewer());
sim.execute();

Or define models as data and compile them:

ModelDefinition def = new ModelDefinitionBuilder()
    .name("Population Model")
    .stock("Population", 1000, "Person")
    .flow("Births", "Population * birth_rate", "Year", null, "Population")
    .constant("birth_rate", 0.03, "1/Year")
    .defaultSimulation("Day", 365, "Day")
    .build();

CompiledModel compiled = new ModelCompiler().compile(def);
compiled.createSimulation().execute();

See Programmable Engine for the full API reference. The 23 runnable demos in courant-demos cover exponential growth, delays, feedback, epidemiology, predator-prey, inventory management, and software development models.

Core Concepts

System Dynamics models represent a system as a network of stocks, flows, and feedback loops. Stocks capture the state of the system — things like population, inventory, or debt. Flows represent the processes that change stocks over time — births, shipments, or interest payments. Variables and constants parameterize the relationships between them. These elements are connected into feedback loops — circular causal chains where effects feed back to influence their own causes — which drive the dynamic behavior of the system.

Stock-and-Flow Diagrams

• Stocks — accumulations representing system state (e.g., population, inventory)
• Flows — rates of change that add to or drain from stocks
• Variables — calculated quantities derived from formulas, including fixed constants that serve as model parameters
• Lookup Tables — piecewise interpolation curves for nonlinear effects
• Subscripts / Arrays — dimensions that expand elements into parallel instances (e.g., by region or cohort)

Causal Loop Diagrams

Courant also supports Causal Loop Diagrams (CLDs) — the qualitative diagramming technique used in early-stage system dynamics modeling:

• CLD Variables — qualitative concepts with no equation or unit
• Causal Links — directed connections with polarity: positive (+), negative (−), or unknown (?)
• Automatic Loop Detection — finds feedback cycles and classifies them as reinforcing (R) or balancing (B)
• Classification — CLD variables can be converted into S&F elements (stock, flow, auxiliary, constant)

CLDs and S&F elements share a single canvas and model definition.

Architecture

Modules

Module	Purpose
courant-engine	Core simulation engine, model definitions, expression AST and parser, two-pass compiler, dependency graphs, dimensional analysis, parameter sweeps, Monte Carlo, optimization, JSON/Vensim/XMILE I/O
courant-ui	JavaFX chart visualization components
courant-demos	23 runnable example programs with source code
courant-app	Visual editor application with canvas-based GUI, inline editing, simulation, and analysis
courant-tools	Model analysis and transformation utilities

Model Import & Export

Courant can exchange models with other System Dynamics tools:

• Vensim .mdl import — reads Vensim model files including stocks, flows, auxiliaries, constants, lookup tables, subscripts, sketch data, and simulation settings. See Vensim Import.
• XMILE import & export — bidirectional exchange with Stella/iThink via the OASIS standard XML format. See XMILE Import & Export.
• JSON — native round-trip persistence format. See Programmable Engine.

Example Models

Programmable Engine Demos

Category	Models
Fundamental	Exponential growth/decay, coffee cooling, bathtub, S-shaped growth, flow time conversion, lookup tables
Delays	First-order material delay, third-order material delay, FIFO pipeline delay
Feedback & Interaction	SIR epidemic (+ sweep, multi-sweep, Monte Carlo, calibration variants), multi-region SIR with subscripts, population by region × age, predator-prey, inventory with delays, sales mix
Software Development	Agile project with rework dynamics, waterfall project with composable modules

Visual Editor Bundled Models

More than 100 models across 18 categories accessible via File → Open Example: introductory, causal loop, control, demographics, ecology, economics, education, environment, epidemiology, management, marketing, physics, policy, population, social, supply chain, technology, and urban.

Documentation

Document	Contents
Quickstart Tutorial	Build your first model in 10 minutes
Visual Editor Guide	GUI features, tools, keyboard shortcuts, simulation, analysis
Programmable Engine	Code API: lambda-based models, definitions, compiler, expressions, sweep/Monte Carlo/optimization
Expression Language	Equation syntax, operators, and built-in functions reference
From Vensim PLE	Migration guide for Vensim PLE users
Vensim Import	Vensim .mdl import: supported constructs and limitations
XMILE Import & Export	XMILE import/export: supported constructs and limitations

Learning System Dynamics

• Why System Dynamics? — when and why to use this approach
• Thinking in Systems: A Primer by Donella Meadows
• MIT OCW: Introduction to System Dynamics
• MIT OCW: System Dynamics Self Study
• System Dynamics Society: Introduction
• Small System Dynamics Models for Big Issues by Erik Pruyt (TU Delft, 2013) — free e-book covering real-world SD modeling with many worked examples

License

This project is licensed under the GNU Affero General Public License v3.0. Demo models and imported third-party models carry separate Creative Commons licenses. See LICENSING.md for the full breakdown of how source code, original models, and third-party models are licensed.

Support

See Support for how to get help, report bugs, and request features.