Stock and Flow Diagrams - Veydra Documentation

Overview

Stock and Flow diagrams are the visual foundation of system dynamics modeling in Veydra. These interactive diagrams provide an intuitive way to understand, build, and modify the structure of your models by representing the accumulations (stocks) and rates of change (flows) in your system.

Core Concepts

Stocks (Accumulations)

Stocks represent things that can be measured at a point in time:

Population

Number of people in a system at any given time

Inventory

Amount of goods or materials stored

Money

Financial balances and account values

Knowledge

Accumulated information or skills

Flows (Rates)

Flows represent activities that occur over time and change stock levels:

Inflows: Activities that increase a stock (births, production, income)
Outflows: Activities that decrease a stock (deaths, consumption, expenses)
Bi-directional: Flows that can go either direction based on conditions

Connectors

Links that show influence relationships between elements:

Information Links: Show what factors influence flows
Causal Relationships: Indicate cause-and-effect connections
Feedback Loops: Circular relationships that create system behavior

Visual Elements

Stock Representation

Stocks are displayed as rectangular boxes with:

┌─────────────────┐
│   POPULATION    │
│     1,000       │
└─────────────────┘

Name: Clear identifier for the stock
Current Value: Real-time value during simulation
Units: Measurement units (people, dollars, etc.)
Color Coding: Visual indication of status or category

Flow Representation

Flows are shown as arrows with:

    Birth Rate
  ────────────►
   +50 /year

Direction: Arrow indicates flow direction
Rate Value: Current flow rate during simulation
Rate Name: Descriptive name for the flow
Units: Rate units (per day, per year, etc.)

Connector Types

Information Links

Thin arrows showing what information influences a flow rate (e.g., population size affecting birth rate)

Material Flows

Thick arrows representing actual movement of materials, people, or resources

Feedback Loops

Curved connections showing how outputs influence inputs in the system

Interactive Features

Real-time Updates

During simulation, the diagram shows live data:

Stock Values: Numbers update in real-time
Flow Rates: Current rates display on arrows
Color Changes: Visual indicators of increase/decrease
Animation: Optional flow animation to show activity

Drag and Drop

Build and modify models visually:

Add Elements

Drag stocks and flows from palette onto canvas

Connect Elements

Draw connections between stocks and flows

Position Layout

Arrange elements for optimal readability

Configure Properties

Set names, initial values, and parameters

Element Properties

Click any element to configure:

Basic Properties: Name, initial value, units
Visual Properties: Color, size, label position
Behavior: Calculation formulas and logic
Documentation: Notes and descriptions

Diagram Types

Simple Linear Flow

Basic accumulation with inflow and outflow:

[Source] ──► [Stock] ──► [Sink]
           Inflow    Outflow

Example: Water tank with input and output valves

Aging Chain

Multiple connected stocks representing progression:

[Young] ──► [Adult] ──► [Elderly]
       Aging      Aging

Example: Population age groups or product lifecycle stages

Circular Flow

Closed loop with materials/people cycling:

[Active] ◄──► [Inactive]
   ▲              │
   └──────────────┘

Example: Employment/unemployment or active/dormant customers

Network Structure

Complex interconnected stocks and flows:

[Stock A] ──► [Stock B]
    │             ▲
    ▼             │
[Stock C] ──► [Stock D]

Example: Supply chain networks or ecosystem models

Building Diagrams

Design Process

Identify Stocks

What are the key accumulations in your system?

Identify Flows

What activities change these accumulations?

Find Influences

What factors affect the flow rates?

Create Connections

Draw the causal relationships

Test Structure

Run simulation to verify behavior

Best Practices

Clear Layout

Left to Right: Arrange flows from left to right when possible
Avoid Crossings: Minimize crossing lines for clarity
Group Related: Keep related elements close together
Use Space: Don’t crowd elements together

Naming Conventions

Noun Phrases: Stocks should be named with nouns (Population, Inventory)
Rate Phrases: Flows should describe rates (Birth Rate, Sales Rate)
Descriptive: Use clear, meaningful names
Consistent: Maintain naming patterns across models

Documentation

Element Notes: Add descriptions to complex elements
Assumptions: Document key assumptions and logic
Units: Clearly specify units for all quantities
Sources: Reference data sources and research

Advanced Features

Conditional Flows

Flows that change behavior based on conditions:

# Example: Population growth with carrying capacity
if population < carrying_capacity:
    birth_rate = base_birth_rate
else:
    birth_rate = base_birth_rate * (carrying_capacity / population)

Non-linear Relationships

Complex mathematical relationships:

Exponential Growth: Accelerating change over time
S-Curves: Growth that levels off at limits
Oscillations: Cyclical behavior patterns
Threshold Effects: Sudden changes at specific points

Table Functions

Lookup tables for empirical relationships:

# Example: Effect of temperature on reaction rate
temperature_effect = table_lookup(temperature, [
    (0, 0.1),    # 0°C: 10% normal rate
    (25, 1.0),   # 25°C: 100% normal rate
    (50, 3.0),   # 50°C: 300% normal rate
    (75, 0.5)    # 75°C: 50% normal rate (degradation)
])

Integration with Code

Model Generation

Diagrams automatically generate Python code structure:

# Generated model structure
class SystemModel:
    def __init__(self):
        self.stocks = {
            'population': 1000,
            'resources': 500
        }
        
    def calculate_flows(self, dt):
        birth_rate = self.stocks['population'] * 0.05
        resource_consumption = self.stocks['population'] * 0.1
        
        return {
            'births': birth_rate,
            'consumption': resource_consumption
        }

Bi-directional Sync

Changes in either direction are synchronized:

Diagram → Code: Visual changes update Python model
Code → Diagram: Code edits refresh visual layout
Real-time: Changes appear immediately in both views
Conflict Resolution: Smart merging of simultaneous changes

Collaboration Features

Shared Editing

Multiple users can edit diagrams simultaneously:

Real-time Updates: See changes from other users instantly
Conflict Prevention: Locking system prevents editing conflicts
Change Tracking: Visual indicators show who made what changes
Comment System: Attach notes and feedback to diagram elements

Version Control

Full version history for diagram changes:

Git Integration: Diagrams are versioned with model code
Visual Diffs: See changes between diagram versions
Branching: Create experimental diagram variations
Merge Tools: Combine changes from different contributors

Validation and Testing

Structure Validation

Automatic checks for diagram integrity:

Conservation Laws

Verify that flows properly connect to stocks and conserve quantities

Unit Consistency

Check that connected elements have compatible units

Completeness

Ensure all stocks have appropriate inflows and outflows

Reachability

Verify that all elements can be influenced by model parameters

Behavior Testing

Validate model behavior through simulation:

Extreme Conditions: Test with unusual parameter values
Equilibrium: Verify steady-state behavior
Sensitivity: Check response to parameter changes
Reality Check: Compare results to real-world expectations

Accessibility and Usability

Full keyboard support for diagram interaction:

Tab Navigation: Move between elements with tab key
Arrow Keys: Navigate spatial relationships
Shortcuts: Quick access to common operations
Screen Readers: Full compatibility with assistive technology

Visual Accessibility

High Contrast: Clear distinction between elements
Color Independence: Information not conveyed by color alone
Scalable Text: Respect system font size preferences
Motion Options: Respect reduced motion preferences

Start with simple stock and flow structures, then gradually add complexity as your understanding of the system develops

Getting Started

Features

Components

​Overview

​Core Concepts

​Stocks (Accumulations)

Population

Inventory

Money

Knowledge

​Flows (Rates)

​Connectors

​Visual Elements

​Stock Representation

​Flow Representation

​Connector Types

​Interactive Features

​Real-time Updates

​Drag and Drop

​Element Properties

​Diagram Types

​Simple Linear Flow

​Aging Chain

​Circular Flow

​Network Structure

​Building Diagrams

​Design Process

​Best Practices

​Clear Layout

​Naming Conventions

​Documentation

​Advanced Features

​Conditional Flows

​Non-linear Relationships

​Table Functions

​Integration with Code

​Model Generation

​Bi-directional Sync

​Collaboration Features

​Shared Editing

​Version Control

​Validation and Testing

​Structure Validation

​Behavior Testing

​Accessibility and Usability

​Keyboard Navigation

​Visual Accessibility

​Next Steps

Model Playground

Model Controls

Overview

Core Concepts

Stocks (Accumulations)

Flows (Rates)

Connectors

Visual Elements

Stock Representation

Flow Representation

Connector Types

Interactive Features

Real-time Updates

Drag and Drop

Element Properties

Diagram Types

Simple Linear Flow

Aging Chain

Circular Flow

Network Structure

Building Diagrams

Design Process

Best Practices

Clear Layout

Naming Conventions

Documentation

Advanced Features

Conditional Flows

Non-linear Relationships

Table Functions

Integration with Code

Model Generation

Bi-directional Sync

Collaboration Features

Shared Editing

Version Control

Validation and Testing

Structure Validation

Behavior Testing

Accessibility and Usability

Keyboard Navigation

Visual Accessibility

Next Steps