Skip to main content

​
What is a Simulation?

A simulation is a year-by-year projection of all ESOP activities, from company contributions and share releases to diversification elections and repurchase obligations.
The engine processes each year as a discrete unit, applying a strict sequence of operations that mirror real-world ESOP administration.

​
The Annual Cycle

Each simulation year follows a 9-step process:

​
Key Processing Steps

Step 0: Turnover Projection

Forecast which employees will terminate

Step 1: Initialization

Calculate share price and prepare for annual processing

Step 2: Share Pool

Calculate shares available for allocation (loan-by-loan mechanics)

Step 3: Allocate Shares

Distribute shares to eligible participants pro-rata by compensation

Step 4: Contribution

Determine company contribution for the year

Step 5: Update Vesting

Calculate vested balances and potential forfeitures

Step 6: Diversification

Process diversification elections

Step 7: Repurchases

Execute share repurchases using the Funding Waterfall

Step 8: Year-End Closing

Finalize annual results and prepare for next year

All Steps

Complete step-by-step breakdown

​
Simulation Inputs

Legal framework (rarely changes)
{
  "vesting_schedule": {...},
  "distribution_policy": {...},
  "cash_usage_policy": [...]
}

​
Simulation Outputs

After running a simulation, you receive:
Year-by-year forecasts for all key metrics:
  • Company contributions
  • Share releases and allocations
  • Repurchase obligations
  • Trust cash flows
  • Loan balances
Individual account details for every participant, every year:
  • Allocated shares
  • Vested percentages
  • Account values
  • Diversification status
Complete trust accounting:
  • Cash balances by source
  • Share pools (allocated, suspense, unallocated)
  • Loan balances and terms
Key insights:
  • Total 10/20-year repurchase obligations
  • Peak cash year
  • Average annual contribution
  • Final trust solvency

​
Simulation Types

Single projection with best-estimate assumptions.Use For:
  • Annual planning
  • Budget preparation
  • Board presentations

​
Running a Simulation

1

Prepare Inputs

Configure PlanRules, OperatingAssumptions, InitialState
2

Execute

results = engine.simulate(
    plan_rules=plan_rules,
    operating_assumptions=operating_assumptions,
    initial_state=initial_state,
    system_config=system_config
)
3

Review Results

Analyze outputs, visualize trends, identify issues
4

Iterate

Adjust assumptions and re-run as needed

​
Best Practices

Start Simple

Begin with basic assumptions, add complexity gradually

Validate Inputs

Ensure census data and financials are accurate

Run Multiple Scenarios

Don’t rely on a single forecast

Document Assumptions

Record rationale for all major assumptions

Update Annually

Recalibrate models with actual results

Focus on Trends

Look for patterns, not individual year precision

​
Next Steps

Run Quick Start

Create your first simulation

Explore Examples

See complete simulation examples

Processing Steps

Deep dive into each step

API Reference

Full API documentation