Skip to content

Examples

This section contains practical examples demonstrating Procela's capabilities, from basic simulations to advanced governance patterns. Each example is fully runnable and includes detailed explanations.

This provides:

  • Clear three-level organization (Beginner, Intermediate, Advanced)
  • Brief descriptions of what each level covers
  • Links to specific examples
  • Prerequisites and setup instructions
  • Consistent example structure
  • Contribution guidelines

Example Levels

The examples are organized by complexity to help you progress at your own pace:

Level Focus Prerequisites Time to Complete
Beginner Core concepts and basic workflows Python basics 5-10 min each
Intermediate Governance patterns and multi-variable systems Beginner examples 15-30 min each
Advanced Custom policies, performance optimization, real-world case studies Intermediate examples 30-60 min each

🟢 Beginner Examples

Start here if you're new to Procela

These examples introduce the fundamental abstractions: Variables, Mechanisms, and the Executive.

What you'll learn:

  • Creating and configuring Variables
  • Implementing custom Mechanisms
  • Running simulations with the Executive
  • Basic governance with SystemInvariant

🟡 Intermediate Examples

Deepen your understanding of governance and epistemic signals

These examples explore adaptive behavior, signal monitoring, and structural changes.

What you'll learn:

  • Implementing adaptive governance strategies
  • Creating and using custom epistemic signals
  • Managing multiple variables with dependencies
  • Saving/restoring simulation state

🔴 Advanced Examples

Push the boundaries of epistemic governance

These examples demonstrate complex patterns, performance optimization, and real-world applications.

What you'll learn:

  • Real-world research applications (epidemiology, climate science)
  • Advanced governance patterns (probing, exploration/exploitation)
  • Performance tuning for large-scale simulations
  • Integration with external tools (RL, optimization, visualization)

Running the Examples

Prerequisites

# Install Procela
pip install procela

# For visualization examples
pip install matplotlib

# For data analysis examples
pip install numpy pandas

Getting the Code

All examples are available in the GitHub repository:

git clone https://github.com/kvernet/procela.git
cd procela/examples

Running an Example

# Run a specific example
python beginner/simple_growth.py

# Or with verbose output
python beginner/simple_growth.py --verbose

# Save results to file
python beginner/simple_growth.py --output results.json

Example Structure

Each example follows a consistent structure:

"""
Example: [Name]
Level: [Beginner/Intermediate/Advanced]
Concepts: [Variables, Mechanisms, Governance, ...]
"""

# 1. Imports
from procela import *

# 2. Define components (Variables, Mechanisms, Governance)
class MyMechanism(Mechanism):
    # ...

# 3. Create and configure
executive = Executive(mechanisms=[...])

# 4. Run simulation
executive.run(steps=100)

# 5. Analyze results
print(f"Final value: {variable.value}")

Contributing Examples

Have an interesting use case or tutorial? We welcome contributions!

  1. Fork the repository
  2. Add your example to the appropriate level directory
  3. Include docstrings and comments
  4. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

Next Steps