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

Variable Categories in Veydra

Veydra uses two layers of variable typing: core simulation categories and optional role labels. Core simulation categories (used by the solver):

Category	What it means
Stock	A state that accumulates over time and is updated by integration
Flow	A rate that increases or decreases one or more stocks
Parameter	An exogenous or configured value used by equations
Auxiliary	A derived value used to compute other variables

Role labels (used for authoring and visualization):

Role label	Typical interpretation
Constant	A parameter that does not vary during a run
Converter	A parameter or auxiliary computed from a lookup/table or transformation
Supplementary	A post-rate auxiliary often calculated after core stock/flow updates
Internal	A helper auxiliary used for implementation details, usually hidden in default diagrams

In practice, the diagram engine still reasons in terms of stock, flow, parameter, and auxiliary. Role labels add context for humans and UI behavior.

Visual Elements

Node Representation

The diagram uses distinct visual notation for major element types:

Flow Nodes: Blue circular nodes with a valve marker (bowtie symbol and stem) above the node
Parameter-Like Nodes: Smaller green circles for parameter, constant, converter, and variable values, with orange circles for auxiliary/supplementary values
Cloud Source/Sink Nodes: Compact cloud nodes with context-aware labels (source labels above, sink labels below)
Labels: Readable labels are positioned consistently per node type to reduce overlap

Each node still supports clear naming, values, units, and metadata in the editor.

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

Physical flow connections are rendered as pipe-style links with:

Source ====> Sink

Pipe Styling: Double-line visual treatment for physical transfers
Direction: Fixed-size arrowheads indicate transfer direction
Valve Notation: Flow nodes use the bowtie valve marker to distinguish rates from accumulations
Rate Context: Flow names and values remain visible in labels/tooltips during simulation

Connector Types

Information Links

Dashed gray connectors showing informational influence on rates and decisions (for example, population affecting birth rate)

Material Flows

Blue pipe-style links representing movement of materials, people, resources, or quantities

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 flows shown using bowtie valve markers

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

Platform Features

Model Playground

Simulation Components

Tools

Integrations

Development

Documentation Index

​Overview

​Core Concepts

​Stocks (Accumulations)

Population

Inventory

Money

Knowledge

​Flows (Rates)

​Connectors

​Variable Categories in Veydra

​Visual Elements

​Node Representation

​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

Variable Categories in Veydra

Visual Elements

Node Representation

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