ST4A SD Simulator User Guide

Welcome to the complete user guide for ST4A System Dynamics Simulator. This guide covers every feature available in the plugin, from basic model building to advanced analysis tools and AI-powered model generation.

Getting Started

Accessing the Frontend Builder

The Frontend Builder is accessed via the {sd_model_builder} shortcode. Add this shortcode to any WordPress page to display the model builder interface.

{sd_model_builder}

// With options:
{sd_model_builder width="100%" height="700px" allow_create="true" allow_save="true"}

Requirements

• Login Required: Users must be logged in to create and save models
• Permissions: Model limits may apply based on user role
• Browser: Modern browser with JavaScript enabled

Frontend Builder Overview

The Frontend Builder is a visual interface for creating System Dynamics models. It consists of several key areas:

Toolbar Functions

Add Elements Group

Connect Group

Selection Group

Analysis Group

Import/Export Group

Canvas Operations

Navigation

• Pan: Click and drag on empty canvas space to pan the view
• Zoom: Use mouse scroll wheel to zoom in/out
• Fit to View: Double-click empty space to fit all elements in view

Element Manipulation

• Select: Click on an element to select it (highlighted in orange)
• Move: Drag selected element to reposition
• Edit: Double-click an element to open the properties panel
• Delete: Select element and press Delete key or click Delete button

Creating Connections

1. 1Click the “Relationship” or “Flow Link” button
2. 2Click on the source element
3. 3Click on the target element
4. 4For relationships, select polarity (+ or -)

Model Elements

Stocks (Blue Rectangles)

Stocks represent accumulations – quantities that build up or deplete over time. Examples include Population, Inventory, Bank Balance, or Water in a Tank.

Flows (Red Triangles)

Flows represent rates of change – how fast stocks increase or decrease. Examples include Birth Rate, Sales Rate, Interest Payments, or Water Flow.

Variables (Green Circles)

Variables (also called auxiliaries or converters) hold constants, parameters, or intermediate calculations. Examples include Birth Rate, Interest Rate, Price, or Demand.

Relationships (Arrows)

Relationships show causal connections between elements. They indicate that one variable influences another, with polarity showing the direction of influence.

Properties Panel

The Properties Panel appears when you double-click an element. It allows you to edit all properties of the selected element.

Common Fields

• Name: The variable name (must be unique, no spaces)
• Equation: The mathematical formula or constant value
• Units: Optional documentation of the variable’s units
• Description: Optional notes about the variable

Writing Equations

Equations can include:

• Numbers: 100, 0.05, -10
• Other variables: Population * Birth Rate
• Operators: +, -, *, /, ^
• Functions: MAX(a, b), IF(condition, true, false)
• Special variables: TIME, DT

// Example equations:
Birth Rate = 0.03
Births = Population * Birth Rate
Deaths = Population * Death Rate
Net Growth = IF(Population > 1000000, 0, Births - Deaths)
Seasonal Factor = 1 + 0.2 * SIN(TIME * 2 * 3.14159 / 12)

Simulation Controls

Control Buttons

Time Parameters

Speed Slider

Controls animation speed from 0.2x (slow) to 10x (fast). This only affects the visual animation, not the simulation calculation.

Integration Methods

Euler Method

The simplest numerical integration method. Fast but less accurate for stiff systems or when dt is large.

Stock(t+dt) = Stock(t) + derivative * dt

Use when: Simple models, learning, or when speed is more important than precision.

Runge-Kutta 4 (RK4)

Fourth-order method that evaluates derivatives at four points per step. More accurate than Euler, especially for oscillating or stiff systems.

k1 = f(t, y)
k2 = f(t + dt/2, y + dt*k1/2)
k3 = f(t + dt/2, y + dt*k2/2)
k4 = f(t + dt, y + dt*k3)
Stock(t+dt) = Stock(t) + (dt/6) * (k1 + 2*k2 + 2*k3 + k4)

Use when: Accuracy is important, oscillating systems, or when using larger dt values.

Functions Reference

Mathematical Functions

Conditional Functions

// IF examples:
Tax = IF(Income > 50000, Income * 0.3, Income * 0.2)
Growth = IF(Population < Capacity, Births - Deaths, 0)
Status = IF(Inventory > 0, 1, 0)

Time Functions

// Time function examples:
Investment = PULSE(10, 1000)           // $1000 investment at time 10
Policy = STEP(50, 0.1)                 // Policy change at time 50
Demand Growth = RAMP(10, 5, 20)        // Demand grows from time 5 to 20

Delay Functions

// Delay examples:
Shipments = DELAY(Orders, 5, 100)      // Orders arrive after 5 time units
Perceived Demand = SMOOTH(Demand, 3, Demand)  // Smoothed perception
Delivery = DELAY3(Production, 10, 0)   // Production with S-curve delay

Random Functions

Lookup Tables

Lookup tables allow you to define non-linear relationships using data points. Values between points are linearly interpolated.

// Define a lookup table in a variable's equation:
Effect of Temperature = LOOKUP(Temperature Effect Table, Temperature)

// The table is defined separately with input-output pairs
// Example: Temperature Effect Table
// Input: 0, 10, 20, 30, 40
// Output: 0.5, 0.8, 1.0, 0.9, 0.6

Special Variables

Sensitivity Analysis

Sensitivity Analysis helps you understand how changes in a parameter affect your model’s outputs.

How to Use

1. 1Click the “Sensitivity” button in the toolbar
2. 2Select the parameter to vary
3. 3Set minimum and maximum values
4. 4Choose number of steps (2-50)
5. 5Optionally select a specific output variable to track
6. 6Click “Run Analysis”

Results

• Table: Shows parameter values and corresponding final output values
• Chart: Visual representation of how outputs change with parameter
• Statistics: Min, max, range, and sensitivity percentage

Scenario Manager

The Scenario Manager lets you save different parameter configurations and compare them.

Saving a Scenario

1. 1Set up your model with desired parameter values
2. 2Click “Scenarios” in the toolbar
3. 3Enter a scenario name and description
4. 4Click “Save”

Loading a Scenario

1. 1Open the Scenarios panel
2. 2Find the scenario in the list
3. 3Click “Load” to apply those parameter values

Comparing Scenarios

1. 1Select two or more scenarios using checkboxes
2. 2Click “Compare Selected”
3. 3View side-by-side simulation results

Parameter Sliders

Parameter Sliders provide interactive controls for adjusting variable values in real-time.

Using Sliders

1. 1Click “Sliders” in the toolbar
2. 2A panel shows sliders for all adjustable parameters
3. 3Drag sliders to change values
4. 4Run simulation to see effects

Dashboard Builder

The Dashboard Builder lets you create custom interactive interfaces for your models, perfect for sharing with non-technical users or creating presentations.

Accessing Dashboard Builder

1. 1Click “Dashboard” in the toolbar
2. 2Check “Enable Dashboard” to activate
3. 3Configure layout settings (grid, columns)
4. 4Add widgets
5. 5Click “Save Dashboard”

Dashboard Settings

Widget Types

Slider Widget

Allows users to adjust a parameter value within a range.

Value Display Widget

Shows the current or final value of a variable.

Gauge Widget

Circular gauge showing a variable’s value within a range.

Chart Widget

Time-series line chart showing one or more variables over time.

Text Widget

Static text content for instructions or explanations.

Run Button Widget

Simulation control buttons.

Dashboard Preview

Click “Preview Live” in the Dashboard Builder to see a fully functional preview of your dashboard without leaving the builder.

• Sliders work and update parameter values
• Run button executes actual simulation
• Gauges and charts animate with results
• Values update in real-time

Embedding Dashboards

Use the shortcode to embed your dashboard on any page:

{sd_dashboard id="123"}

// With options:
{sd_dashboard id="123" width="800px" height="600px"}

AI Chatbot

The AI Chatbot is a unique feature that lets you create and modify models using natural language. Simply describe what you want, and the AI will generate the model.

Creating a Model with AI

1. 1Open the AI chat panel (appears on the side)
2. 2Describe the model you want to create
3. 3AI will generate the complete model structure
4. 4Review and refine with follow-up messages

Example Prompts

// Creating a new model:
"Create a population model with births, deaths, and migration"

// Modifying existing model:
"Add a carrying capacity that limits population growth"

// Asking questions:
"What would happen if birth rate doubled?"

AI Providers

ST4A supports multiple AI providers:

AI Settings

Users can configure their own API keys for unlimited AI access.

Adding Your API Key

1. 1Click the settings icon in the AI panel
2. 2Enter your API key for the desired provider
3. 3Click “Test” to verify the key works
4. 4Click “Save” to store (encrypted)

Template Library

The Template Library provides pre-built models to help you get started quickly.

Available Templates

Loading a Template

1. 1Click “Templates” in the toolbar
2. 2Browse by category or view all
3. 3Click “Load Template” on desired template
4. 4Confirm to replace current model

Import/Export

Exporting Models

1. 1Click the Export button (download icon) in toolbar
2. 2Copy the JSON from the modal
3. 3Save to a file or share directly

Importing Models

1. 1Click the Import button (upload icon) in toolbar
2. 2Paste the SD-JSON content
3. 3Click “Import”

SD-JSON Format

The SD-JSON format is compatible with the SD-AI project:

{
  "title": "Model Name",
  "explanation": "Model description",
  "variables": [
    {
      "name": "Population",
      "type": "stock",
      "equation": "1000",
      "units": "people"
    },
    {
      "name": "Birth Rate",
      "type": "variable",
      "equation": "0.03"
    }
  ],
  "relationships": [
    {
      "from": "Population",
      "to": "Births",
      "polarity": "+"
    }
  ],
  "specs": {
    "startTime": 0,
    "stopTime": 100,
    "dt": 1,
    "timeUnits": "years"
  }
}

Shortcode Reference

{sd_model_builder}

Displays the full model builder interface.

{sd_model_builder}
{sd_model_builder model_id="123"}
{sd_model_builder width="100%" height="800px" allow_create="false"}

{sd_simulator}

Displays a simulation viewer (read-only, no editing).

{sd_simulator id="123"}
{sd_simulator id="123" width="800px" height="600px"}

{sd_dashboard}

Displays a custom dashboard for a model.

{sd_dashboard id="123"}
{sd_dashboard id="123" width="900px"}