1. Getting Started with Ergodic Insurance Limits

This tutorial introduces the Ergodic Insurance Limits framework and guides you through installation and your first simulation.

1.1. What is Ergodic Insurance Optimization?

Traditional insurance analysis uses ensemble averages - the expected value across many parallel scenarios. This works well for large insurers diversifying across thousands of policies, but it doesn’t capture what happens to a single business over time.

Ergodic economics uses time averages - what actually happens to one entity as it evolves through time. For businesses facing large, volatile losses, the time-average growth rate can differ dramatically from ensemble expectations.

Key takeaway: Insurance that appears “expensive” from an expected-value perspective may actually increase long-term wealth growth when analyzed through time averages.

1.2. Installation

1.2.1. Prerequisites

Python 3.12 or higher
pip or uv package manager
Git (optional, for cloning the repository)

1.2.2. Install from Source

Clone the repository:

git clone https://github.com/AlexFiliakov/Ergodic-Insurance-Limits.git
cd "Ergodic Insurance Limits/ergodic_insurance"

Create and activate a virtual environment:

# On Windows
python -m venv .venv
.venv\Scripts\activate

# On Unix/macOS
python -m venv .venv
source .venv/bin/activate

Install the package:

# Using pip
pip install -e ".[dev,notebooks]"

# Or using uv (recommended)
uv sync

Verify the installation:

python -c "import ergodic_insurance; print(ergodic_insurance.__version__)"

1.3. Your First Analysis

The fastest way to get results is run_analysis() — one import, one call:

from ergodic_insurance import run_analysis

results = run_analysis(
    initial_assets=10_000_000,       # $10M starting assets
    operating_margin=0.08,           # 8% operating margin
    loss_frequency=2.5,              # ~2.5 losses per year
    loss_severity_mean=1_000_000,    # $1M average loss
    deductible=500_000,              # $500K self-insured retention
    coverage_limit=10_000_000,       # $10M policy limit
    premium_rate=0.025,              # 2.5% rate on limit
    n_simulations=1000,              # Monte Carlo paths
    time_horizon=20,                 # 20-year horizon
)

print(results.summary())

That’s it — run_analysis builds the manufacturer, loss model, insurance policy, and simulation engine internally, runs both insured and uninsured Monte Carlo batches, and returns a rich result object.

1.3.1. Inspect the Results

# Export per-simulation metrics to a DataFrame
df = results.to_dataframe()
print(df.head())

# Quick 2x2 comparison chart
results.plot()

1.3.2. Under the Hood

run_analysis is a convenience wrapper around the framework’s building blocks. Power users can import them directly:

from ergodic_insurance import Config, WidgetManufacturer, ManufacturingLossGenerator, Simulation

See Tutorial 2: Basic Simulation for a deeper dive into the individual components.

1.4. Understanding the Output

Metric	Description
`assets`	Total assets at each year-end
`equity`	Shareholder equity (assets minus liabilities)
`roe`	Return on equity for each year
`revenue`	Annual revenue generated
`net_income`	Annual profit after taxes
`claim_counts`	Number of claims in each year
`claim_amounts`	Total claim dollars in each year
`insolvency_year`	Year of bankruptcy (None if survived)

1.5. Next Steps

Now that you’ve run your first simulation, continue with:

Tutorial 2: Basic Simulation - Deeper dive into simulation mechanics
Tutorial 3: Configuring Insurance - Add insurance to your simulation
Tutorial 4: Optimization Workflow – Use the optimizer to automatically find the best deductible and limit for your business
Tutorial 5: Analyzing Results – Deep dive into ergodic analysis, volatility drag, and DuPont decomposition
Tutorial 6: Advanced Scenarios – Monte Carlo simulations, market cycles, and multi-line programs

1.6. Quick Reference

1.6.1. Key Classes

Class / Function	Purpose
`run_analysis()`	Quick-start — one call for a full insured-vs-uninsured comparison
`AnalysisResults`	Container returned by `run_analysis` with `.summary()`, `.to_dataframe()`, `.plot()`
`ManufacturerConfig`	Configure business financial parameters
`WidgetManufacturer`	Business model with financial operations
`ManufacturingLossGenerator`	Generate random loss events (recommended)
`Simulation`	Run time evolution of the business
`SimulationResults`	Container for simulation output

1.6.2. Common Parameters

Parameter	Typical Range	Description
`initial_assets`	\(1M - \)100M	Starting capital
`asset_turnover_ratio`	0.5 - 2.0	Revenue efficiency
`base_operating_margin`	5% - 15%	Profitability before insurance
`base_frequency`	0.05 - 0.5	Claims per year
`time_horizon`	10 - 100 years	Simulation length