Quick Start Guide

This guide will help you get started with insurance optimization analysis in under 30 minutes. We’ll walk through setting up your company profile, understanding your risks, and running your first simulation.

Prerequisites

Before starting, ensure you have:

  1. Python environment with the ergodic_insurance package installed

  2. Access to Jupyter notebooks or Python IDE

  3. Basic company financial information:

    • Current assets/capital

    • Annual revenue

    • Operating margin

    • Historical loss data (if available)

Step 1: Understanding Your Company Profile

First, let’s define your company using our configuration system. Create a YAML file describing your business:

my_company.yaml
company:
  name: "My Manufacturing Co"
  starting_assets: 10_000_000  # Current asset base in dollars

financial:
  base_revenue: 15_000_000     # Annual revenue
  base_operating_margin: 0.08        # 8% profit margin
  tax_rate: 0.25                # 25% corporate tax
  working_capital_pct: 0.20     # 20% of revenue tied up in working capital

growth:
  base_growth_rate: 0.06        # 6% organic growth
  growth_volatility: 0.15       # 15% standard deviation

Key Parameters Explained

Starting Assets: Your company’s current capital base. This is what you’re protecting with insurance.

Operating Margin: Your profit margin before extraordinary items. Higher margins provide more buffer against losses.

Growth Volatility: How much your revenue varies year-to-year. Tech companies might be 30-40%, utilities 5-10%.

Step 2: Defining Your Risk Profile

Next, characterize your loss exposure. We categorize losses into three buckets:

my_risk_profile.yaml
losses:
  attritional:
    frequency: 5.0              # Average 5 small losses per year
    severity_mean: 50_000       # Average $50K per loss
    severity_cv: 0.8            # Coefficient of variation

  large:
    frequency: 0.3              # One large loss every ~3 years
    severity_mean: 2_000_000    # Average $2M when occurs
    severity_cv: 1.2

  catastrophic:
    frequency: 0.02             # One catastrophic loss every ~50 years
    severity_mean: 15_000_000   # Average $15M when occurs
    severity_cv: 0.5

Understanding Loss Categories

Attritional Losses (High Frequency, Low Severity)

  • Equipment breakdowns

  • Minor accidents

  • Small liability claims

  • Typically retained by company

Large Losses (Medium Frequency, Medium Severity)

  • Major equipment failure

  • Significant liability event

  • Supply chain disruption

  • Primary insurance layer target

Catastrophic Losses (Low Frequency, High Severity)

  • Natural disasters

  • Major product recall

  • Cyber attack

  • Excess insurance layer target

Step 3: Exploring Insurance Structures

Our framework models multi-layer insurance programs. Here’s a typical structure:

insurance_structure.yaml
insurance_program:
  retention: 100_000            # You pay first $100K of any loss

  layers:
    - name: "Primary"
      limit: 5_000_000          # Covers $100K to $5.1M
      base_premium_rate: 0.015       # 1.5% of limit = $75K/year

    - name: "First Excess"
      limit: 20_000_000         # Covers $5.1M to $25.1M
      base_premium_rate: 0.008       # 0.8% of limit = $160K/year

    - name: "Second Excess"
      limit: 25_000_000         # Covers $25.1M to $50.1M
      base_premium_rate: 0.004       # 0.4% of limit = $100K/year

Visualizing Your Insurance Tower

Loss Amount    Coverage           Annual Premium
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
$50M ┌─────────────────────┐
     │   Second Excess      │     $100K
$25M ├─────────────────────┤
     │   First Excess       │     $160K
 $5M ├─────────────────────┤
     │   Primary Layer      │     $75K
$100K├─────────────────────┤
     │   Retention          │     You Pay
  $0 └─────────────────────┘
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                          Total Premium: $335K/year

Step 4: Running Your First Simulation

Now let’s run a basic simulation using Python:

first_simulation.py
from ergodic_insurance.config_loader import load_config
from ergodic_insurance.manufacturer import WidgetManufacturer
from ergodic_insurance.insurance_program import InsuranceProgram
from ergodic_insurance.monte_carlo import MonteCarloEngine
from ergodic_insurance.ergodic_analyzer import ErgodicAnalyzer

# Load your configuration
config = load_config('my_company.yaml')

# Create manufacturer with your parameters
manufacturer = WidgetManufacturer(
    starting_assets=10_000_000,
    base_revenue=15_000_000,
    base_operating_margin=0.08
)

# Define insurance program
insurance = InsuranceProgram(
    retention=100_000,
    layers=[
        {'limit': 5_000_000, 'attachment': 100_000, 'base_premium_rate': 0.015},
        {'limit': 20_000_000, 'attachment': 5_100_000, 'base_premium_rate': 0.008}
    ]
)

# Run Monte Carlo simulation
engine = MonteCarloEngine(n_simulations=1000)
results = engine.run(
    manufacturer=manufacturer,
    insurance_program=insurance,
    n_years=10
)

# Analyze results
analyzer = ErgodicAnalyzer()
metrics = analyzer.calculate_metrics(results)

print(f"10-Year Survival Probability: {metrics['survival_rate']:.1%}")
print(f"Time-Average Growth Rate: {metrics['time_avg_growth']:.2%}")
print(f"Expected Terminal Wealth: ${metrics['expected_terminal_wealth']:,.0f}")

Step 5: Using Pre-Built Notebooks

For easier analysis, use our pre-configured Jupyter notebooks:

Basic Analysis (notebooks/01_basic_manufacturer.ipynb)

Start here to understand the manufacturer model and basic simulations.

Long-Term Simulations (notebooks/02_long_term_simulation.ipynb)

Explore 10, 20, and 50-year horizons to see compounding effects.

Growth Dynamics (notebooks/03_growth_dynamics.ipynb)

Understand how insurance affects growth trajectories.

Ergodic Demo (notebooks/04_ergodic_demo.ipynb)

See the difference between time and ensemble averages.

Risk Metrics (notebooks/05_risk_metrics.ipynb)

Calculate VaR, CVaR, and other risk measures.

To run a notebook:

cd ergodic_insurance/notebooks
jupyter notebook 01_basic_manufacturer.ipynb

Step 6: Interpreting Initial Results

Your first simulation will produce metrics like:

===== Simulation Results =====
Scenarios Run: 1,000
Time Horizon: 10 years

Without Insurance:
- Survival Rate: 72.3%
- Mean Growth (survivors): 5.8%/year
- Median Terminal Wealth: $14.2M
- 5% VaR: -$3.1M (ruin)

With Insurance ($100K retention, $25M limit):
- Survival Rate: 94.7%
- Mean Growth: 7.2%/year
- Median Terminal Wealth: $17.8M
- 5% VaR: $8.9M
- Total Premiums Paid: $3.35M
- Net Benefit: +$3.6M

Key Metrics to Focus On

  1. Survival Rate: Percentage of scenarios avoiding ruin

  2. Time-Average Growth: Your actual experienced growth rate

  3. Terminal Wealth Distribution: Range of possible outcomes

  4. Value at Risk (VaR): Worst-case scenarios (5th percentile)

Quick Decision Rules

Based on thousands of simulations, here are rules of thumb:

When to Buy More Insurance:

  • Survival rate < 90% over 10 years

  • VaR shows negative terminal wealth

  • Growth volatility > 20%

  • Correlation between revenue and losses > 0.3

Optimal Retention Level:

  • Start with 1-2% of assets

  • Lower if: High volatility, thin margins

  • Higher if: Stable revenue, strong balance sheet

Limit Selection:

  • Minimum: 99th percentile annual loss

  • Recommended: 99.5th percentile

  • Consider: Largest historical loss × 2

Next Steps

Now that you’ve run your first simulation:

  1. Proceed to Running Your Analysis for detailed analysis procedures

  2. Use Decision Framework to interpret results

  3. Review Model Cases for similar companies

  4. Explore Advanced Topics for customization

Common Issues

“My survival rate is very low”

Your retention might be too high. Try reducing it by 50%.

“Insurance seems too expensive”

Check if you’re modeling correlation between losses and revenue correctly.

“Results vary significantly between runs”

Increase simulations to 10,000 for more stable results.

“How do I model my specific industry?”

See Advanced Topics for customizing loss distributions.

Ready for More?

You’ve successfully: ✓ Set up your company profile ✓ Defined your risk parameters ✓ Configured insurance structures ✓ Run your first simulation ✓ Interpreted basic results

Continue to Running Your Analysis to dive deeper into optimization techniques.