> ## Documentation Index > Fetch the complete documentation index at: https://village-docs.villagelabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Simulation Overview > Understanding the annual processing pipeline ## 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: ```mermaid theme={null} graph LR S0[Step 0: Turnover] --> S1[Step 1: Initialization] S1 --> S2[Step 2: Share Pool] S2 --> S3[Step 3: Allocate] S3 --> S4[Step 4: Contribution] S4 --> S5[Step 5: Vesting] S5 --> S6[Step 6: Diversification] S6 --> S7[Step 7: Repurchases] S7 --> S8[Step 8: Year-End] style S2 fill:#29371F,color:#fff style S7 fill:#29371F,color:#fff ``` ## Key Processing Steps Forecast which employees will terminate Calculate share price and prepare for annual processing Calculate shares available for allocation (loan-by-loan mechanics) Distribute shares to eligible participants pro-rata by compensation Determine company contribution for the year Calculate vested balances and potential forfeitures Process diversification elections Execute share repurchases using the Funding Waterfall Finalize annual results and prepare for next year Complete step-by-step breakdown ## Simulation Inputs Legal framework (rarely changes) ```json theme={null} { "vesting_schedule": {...}, "distribution_policy": {...}, "cash_usage_policy": [...] } ``` Annual strategy (changes frequently) ```json theme={null} { "contribution_policy": {...}, "share_valuation": {...}, "repurchase_strategy": {...} } ``` Current ESOP status ```json theme={null} { "participants": [...], "trust_cash": {...}, "esop_loans": [...] } ``` Simulation settings ```json theme={null} { "projection_years": 20, "include_turnover": true } ``` ## 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 Multiple simulations with different assumptions. **Use For:** * Comparing contribution strategies * Evaluating refinancing options * Stress testing **Example:** * Scenario A: \$500K annual contribution * Scenario B: \$600K annual contribution * Compare 10-year obligations Systematically vary key assumptions. **Use For:** * Understanding model sensitivity * Identifying key drivers * Risk assessment **Example:** Vary share price growth: -5%, 0%, +5%, +10% ## Running a Simulation Configure PlanRules, OperatingAssumptions, InitialState ```python theme={null} results = engine.simulate( plan_rules=plan_rules, operating_assumptions=operating_assumptions, initial_state=initial_state, system_config=system_config ) ``` Analyze outputs, visualize trends, identify issues Adjust assumptions and re-run as needed ## Best Practices Begin with basic assumptions, add complexity gradually Ensure census data and financials are accurate Don't rely on a single forecast Record rationale for all major assumptions Recalibrate models with actual results Look for patterns, not individual year precision ## Next Steps Create your first simulation See complete simulation examples Deep dive into each step Full API documentation