System Dynamics Model Builder – User Guide

1. Understanding Model Elements

System Dynamics models are built using three fundamental types of elements:

2. Getting Started

The Canvas

The large white area is your modeling canvas. This is where you’ll place and connect your model elements. You can:

• Pan – Click and drag on empty space to move around the canvas
• Zoom – Use your mouse scroll wheel or pinch gesture to zoom in/out
• Select – Click on any element to select it
• Move – Drag selected elements to reposition them

The Toolbar

The toolbar at the top provides quick access to common actions:

3. Creating Elements

Adding a Stock

1. Click the “Add Stock” button in the toolbar
2. A new stock will appear on the canvas with a default name
3. Double-click on the stock to open the properties panel
4. Enter a descriptive name (e.g., “Population”, “Inventory”)
5. Set the initial value in the equation field (e.g., 1000)
6. Optionally add units and documentation
7. Click Save to apply your changes

Adding a Flow

1. Click the “Add Flow” button in the toolbar
2. A new flow will appear on the canvas
3. Double-click to edit the flow properties
4. Name your flow (e.g., “Births”, “Sales”)
5. Write an equation that calculates the flow rate
6. Click Save

Adding a Variable

1. Click the “Add Variable” button
2. Double-click to edit properties
3. Name your variable (e.g., “Birth Rate”, “Price”)
4. Enter a constant value or formula
5. Click Save

Moving and Resizing Elements

• Move: Click and drag any element to reposition it
• Resize: Select an element and drag the corner handles to resize
• Delete: Select an element and press Delete or Backspace

4. Creating Relationships

Relationships (also called causal links) show how elements influence each other. They appear as curved arrows with a polarity indicator.

Adding a Relationship

1. Click the “Add Relationship” button
2. Click on the source element (the influencer)
3. Click on the target element (what’s being influenced)
4. An arrow will be created connecting them

Understanding Polarity

The polarity shows whether the relationship is positive or negative:

Polarity	Meaning	Example
+ Positive	When the source increases, the target increases (and vice versa)	Population → Births: More people = more births
− Negative	When the source increases, the target decreases (and vice versa)	Price → Demand: Higher price = lower demand

Editing Relationships

1. Click on the relationship arrow or the polarity circle (+/−)
2. The properties panel will open
3. Change the polarity if needed
4. Adjust the curvature using the slider
5. Add reasoning to document why this relationship exists
6. Click Save

5. Writing Equations

Basic Syntax

Equations define how elements are calculated. You can use:

Operation	Symbol	Example
Addition	+	Inflow + Extra
Subtraction	-	Revenue - Costs
Multiplication	*	Population * Birth Rate
Division	/	Inventory / Coverage Time
Exponentiation	^	Base ^ 2
Parentheses	( )	(Price - Cost) * Quantity

Available Functions

Function	Description	Example
MIN(a, b)	Returns the smaller value	MIN(Demand, Supply)
MAX(a, b)	Returns the larger value	MAX(0, Inventory - Safety)
IF(cond, true, false)	Conditional logic	IF(Stock < 10, 100, 0)
SQRT(x)	Square root	SQRT(Variance)
ABS(x)	Absolute value	ABS(Error)
EXP(x)	Exponential (e^x)	EXP(Growth Rate)
LOG(x)	Natural logarithm	LOG(Population)

Special Variables

• TIME - The current simulation time

6. Running Simulations

Simulation Controls

Simulation Parameters

Before running, configure your simulation settings:

• Start Time: When the simulation begins (usually 0)
• Stop Time: When the simulation ends (e.g., 100)
• Time Step (DT): The calculation interval (smaller = more accurate but slower)
• Time Units: Label for your time axis (seconds, days, months, years)

Viewing Results

During simulation:

• Canvas Animation: Watch values change in real-time on the diagram
• Chart: View time-series graphs of all variables
• Toggle Variables: Show/hide specific variables in the chart

7. Saving and Exporting

Saving Your Model

1. Click the "Save Model" button
2. Enter a name for your model
3. Your model will be saved and you can return to it later

Exporting to JSON

Export your model in SD-JSON format for backup or sharing:

1. Click "Export JSON"
2. A file will download containing your complete model
3. This format is compatible with other SD tools

Importing a Model

1. Click "Import JSON"
2. Select or paste your SD-JSON file
3. The model will load onto the canvas

Exporting Results to CSV

After running a simulation:

1. Click "Export CSV"
2. A spreadsheet file will download with all simulation data
3. Open in Excel or Google Sheets for further analysis

8. Example: Building a Population Model

Let's build a simple population growth model step by step:

Step 1: Create the Stock

1. Click "Add Stock"
2. Double-click and name it Population
3. Set equation to 1000 (initial population)
4. Set units to people
5. Save

Step 2: Create the Variables

1. Add a variable, name it Birth Rate, equation: 0.03 (3% per year)
2. Add a variable, name it Death Rate, equation: 0.02 (2% per year)

Step 3: Create the Flows

1. Add a flow, name it Births, equation: Population * Birth Rate
2. Add a flow, name it Deaths, equation: Population * Death Rate

Step 4: Create Relationships

1. Add relationship: Population → Births (polarity: +)
2. Add relationship: Birth Rate → Births (polarity: +)
3. Add relationship: Population → Deaths (polarity: +)
4. Add relationship: Death Rate → Deaths (polarity: +)
5. Add relationship: Births → Population (polarity: +)
6. Add relationship: Deaths → Population (polarity: −)

Step 5: Run the Simulation

1. Set Stop Time to 100 years
2. Set Time Step to 1
3. Click Play
4. Watch the population grow exponentially!

9. Tips and Tricks

Best Practices

• Start simple: Begin with 2-3 elements and add complexity gradually
• Name clearly: Use descriptive names that explain what each element represents
• Document: Add documentation to elements explaining your assumptions
• Test often: Run simulations frequently to catch errors early
• Check units: Ensure your units are consistent (e.g., people/year × years = people)

Troubleshooting

Problem	Possible Cause	Solution
Values explode to infinity	Positive feedback without limits	Add constraints using MIN/MAX or negative feedback
Values oscillate wildly	Time step too large	Reduce DT (try 0.25 or 0.1)
Nothing changes	Missing connections or zero rates	Check that flows connect to stocks and have non-zero equations
NaN or error values	Division by zero or undefined reference	Check equations for divide-by-zero cases; verify element names match

Keyboard Shortcuts

Shortcut	Action
Delete / Backspace	Delete selected element
Escape	Cancel current action / Close panel
Double-click	Edit element properties