Overview Step 1 initializes the annual processing cycle by calculating the current share price and preparing all state variables for the year’s simulation.
This is the foundation step that establishes share valuations used throughout all subsequent steps.
Core Responsibilities
Share Price Calculation Calculate per-share value from company equity and outstanding shares
Multi-Class Support Initialize security-specific prices and aggregate metrics
Growth Application Apply annual growth rate to company equity value
Processing Logic Single-Class Mode The simplest calculation:
# Calculate share price from company equity share_price = company_equity_value / total_outstanding_shares # Example: # Company Equity: $50,000,000 # Outstanding Shares: 100,000 # Share Price: $50,000,000 / 100,000 = $500.00/share
Multi-Class Mode When multiple securities exist, Step 1:
Initialize Security Prices
Set each security’s price from its FMV or use company aggregate price as fallback
Calculate Aggregate Equity
Sum equity value across all securities: equity_total = sum ( security.current_share_price * security.total_outstanding_shares for security in securities.values() )
Set Aggregate Share Price
For legacy compatibility: company_share_price = equity_total / total_outstanding_shares
Initialize Carry-Over Pools
Set up per-security recycled and forfeited share pools
Example Multi-Class Calculation: # Class A: 60,000 shares at $600/share = $36,000,000 # Class B: 40,000 shares at $400/share = $16,000,000 # Total Equity: $52,000,000 # Aggregate Price: $52,000,000 / 100,000 = $520/share
Growth Application After initializing prices, Step 1 applies the annual growth rate:
growth_rate = 1 + share_price_growth_rate # e.g., 1.05 for 5% company_equity_value *= growth_rate # Example: # Beginning Equity: $50,000,000 # Growth Rate: 5% (1.05) # Ending Equity: $50,000,000 * 1.05 = $52,500,000 # New Share Price: $52,500,000 / 100,000 = $525/share
Growth is applied uniformly across all securities : growth_rate = 1 + share_price_growth_rate for security in securities.values(): security.current_share_price *= growth_rate # Recalculate aggregate equity equity_total = sum ( security.current_share_price * security.total_outstanding_shares for security in securities.values() ) company_equity_value = equity_total
Example:
Class A: 600 ∗ 1.05 = 600 * 1.05 = 600 ∗ 1.05 =
Class B: 400 ∗ 1.05 = 400 * 1.05 = 400 ∗ 1.05 =
New aggregate: (630 ∗ 60 , 000 ) + ( 630 * 60,000) + ( 630 ∗ 60 , 000 ) + (
Growth is applied to equity value , not share count. Outstanding shares remain constant unless modified by redemptions in Step 7.
Compliance Events Step 1 emits two compliance events:
Initial price before growth: { "year" : 2025 , "phase" : "initialization" , "event" : "share_price_calculated" , "details" : { "share_price" : 500.00 , "equity_value" : 50000000.00 , "outstanding_shares" : 100000.0 } }
Price after applying growth: { "year" : 2025 , "phase" : "init" , "event" : "share_price_initialized" , "details" : { "growth_applied" : 1.05 , "new_equity_value" : 52500000.00 } }
Complete audit trail: { "year" : 2025 , "phase" : "init" , "event" : "share_price_computed" , "entity_type" : "company" , "entity_id" : null , "inputs" : { "equity_value" : 50000000.00 , "outstanding_shares" : 100000.0 , "share_price_growth_rate" : 0.05 }, "outputs" : { "share_price" : 525.00 , "new_equity_value" : 52500000.00 } }
Data Flow Company State
Financial Assumptions
{ "company_equity_value" : 50000000.00 , # Total company value "total_outstanding_shares" : 100000.0 , # Shares in circulation "securities" : { # Multi-class mode only "CLASS_A" : { "security_id" : "CLASS_A" , "initial_fair_market_value" : 600.00 , "total_outstanding_shares" : 60000.0 , "initial_recycled_shares" : 500.0 , "initial_forfeited_shares" : 150.0 }, "CLASS_B" : { ... } } }
{ "share_price_growth_rate" : 0.05 # 5% annual growth }
Outputs Company State (Updated)
Carry-Over State
{ "current_share_price" : 525.00 , # New price after growth "company_equity_value" : 52500000.00 , # New equity after growth "securities" : { # Multi-class mode "CLASS_A" : { "current_share_price" : 630.00 # Grown price }, "CLASS_B" : { "current_share_price" : 420.00 # Grown price } } }
{ "recycled_shares_by_security" : { # Multi-class mode "CLASS_A" : 500.0 , "CLASS_B" : 0.0 }, "forfeited_shares_next_year_by_security" : { "CLASS_A" : 150.0 , "CLASS_B" : 0.0 } }
Implementation Notes Division by Zero Protection # If no shares outstanding, use default denominator denominator = total_outstanding_shares if total_outstanding_shares > 0 else Decimal( "1" ) share_price = company_equity_value / denominator
Precision Handling All financial calculations use Decimal type to avoid floating-point errors:
from decimal import Decimal growth_rate = Decimal( str ( 1 + share_price_growth_rate)) company_equity_value *= growth_rate
Timing Note Important: Yearly evolution of employee data (age, service years, compensation growth) happens in Step 8 , not Step 1.Step 1 focuses solely on share price and company-level state initialization.
Example Scenario Setup:
Company Equity: $50M
Outstanding Shares: 100,000
Growth Rate: 5%
Multi-class: Class A (60K shares), Class B (40K shares)
Processing: # 1. Initialize Class A CLASS_A .current_share_price = 600.00 CLASS_A_equity = 600.00 * 60 , 000 = $ 36 , 000 , 000 # 2. Initialize Class B CLASS_B .current_share_price = 400.00 CLASS_B_equity = 400.00 * 40 , 000 = $ 16 , 000 , 000 # 3. Calculate aggregate company_equity_value = $36M + $16M = $52M company_share_price = $52M / 100 , 000 = $ 520 / share # 4. Apply growth (5%) CLASS_A .current_share_price = 600.00 * 1.05 = $ 630.00 CLASS_B .current_share_price = 400.00 * 1.05 = $ 420.00 # 5. Recalculate aggregate company_equity_value = ( 630 * 60K ) + ( 420 * 40K ) = $ 54. 6M company_share_price = $ 54. 6M / 100 , 000 = $ 546 / share # (Removed OIA BOY setup in v0.3)
Result:
✅ Share prices calculated and grown
✅ Aggregate metrics updated
✅ Ready for Step 2
Summary Step 1 is a foundational initialization step that:
✅ Calculates share price from company equity
✅ Supports both single-class and multi-class modes
✅ Applies annual growth rate
✅ Sets up per-security carry-over pools
✅ Emits comprehensive compliance events
This step establishes the pricing basis used throughout all subsequent steps in the annual cycle. .png?fit=max&auto=format&n=_b1oFDtC7brS6c3Z&q=85&s=d3ec56559a51e770e67aa19d77e1da67)
.png?fit=max&auto=format&n=AWN49C5ILGJ2VJNX&q=85&s=9e43d95342e1c0ca7d9eadaa6d3acb0d)