User Guide

This guide walks you through using BAM Engine, from understanding the underlying economic model to writing your own extensions and validating results against the reference literature.

Whether you’re new to agent-based modeling or an experienced researcher, the guide is organized in progressive order: start with the conceptual foundations, learn the core API, then move to advanced customization and validation workflows.

Understanding the Model

• Overview
  • What is BAM Engine?
  • Architecture
  • Key Concepts
  • Auto-Registration
  • Deterministic RNG
  • What’s Next
• The BAM Model
  • Notation
  • Agent Types
  • The Economic Cycle
  • Market Matching
  • Key Parameters
  • Economy Statistics
  • Further Reading

Using BAM Engine

• Running Simulations
  • Initialization
  • Running Periods
  • Single-Step Execution
  • Accessing State During Simulation
  • Stopping Conditions
  • Performance & Scaling
• Configuration
  • Configuration Precedence
  • YAML Configuration Files
  • Parameter Reference
  • Logging Configuration
  • Extension Parameters
  • Configuration Validation
• Data Collection
  • Quick Example
  • Collection Options
  • Collection Settings
  • Discoverability
  • Economy Metrics
  • Full Per-Agent Data
  • Relationship Data Collection
  • Accessing Results
  • Exporting Data
• Operations Module
  • Quick Example
  • Why Use ops?
  • Quick Reference
  • Core Operations
  • Common Patterns
  • When to Use ops vs. NumPy Directly

Extending the Framework

• Custom Roles
  • Quick Example
  • The @role Decorator
  • Type Aliases
  • Initializing Custom Roles
  • Accessing Role Data
  • Built-in Roles
  • Tips
• Custom Events
  • Quick Example
  • The @event Decorator
  • The execute() Method
  • Accessing Simulation State
  • Pipeline Integration
  • Worked Example: Inventory Carrying Cost
  • Built-in Events
  • Tips
• Custom Relationships
  • Quick Example
  • The @relationship Decorator
  • COO Sparse Format
  • Adding and Removing Edges
  • Querying Edges
  • Aggregating Edge Data
  • Built-in Relationship: LoanBook
  • Tips
• Pipeline Customization
  • The Default Pipeline
  • Pipeline Hooks (Recommended)
  • Manual Pipeline Modification
  • Custom Pipeline YAML
  • Planning-Phase Pricing (Alternative)
  • Inspecting the Pipeline
  • Tips

Model Extensions

• Model Extensions
  • The Extension Pattern
  • Built-in Extensions
  • Combining Extensions
  • Writing Your Own Extension

Validation & Calibration

• Validation & Analysis
  • Running Validation
  • Validation Scenarios
  • Understanding Scores
  • Robustness Analysis
  • Parameter Calibration
  • Visualization
• Parameter Calibration
  • Calibration Concepts
  • Quick Start
  • The Three Phases
  • Tips

Reference & Tips

• Implementation Decisions
  • Pricing
  • Market Matching
  • Wages & Contracts
  • Credit Market
  • Inflation
  • Revenue & Dividends
  • Bankruptcy
  • Balance Sheet Design
  • Measurement Timing
• Best Practices
  • Reproducibility
  • Performance Tips
  • Common Pitfalls
  • Extension Best Practices
  • Debugging Tips
  • Project Organization