simulation_service

SimulationService: thin orchestrator that sequences service calls for each date.

Classes:

SimulationService –

Thin orchestrator: sequences service calls for each simulation date.

SimulationService

SimulationService(
    bank: Bank,
    market_data: MarketDataStore,
    valuation_service: ValuationService,
    rule_engine: RuleEngine,
    accounting_service: AccountingService,
    metrics_service: MetricsService,
    valuation_store: ValuationStore,
    metric_store: MetricStore,
    transaction_log: TransactionLog,
    event_bus: EventBus,
)

Thin orchestrator: sequences service calls for each simulation date.

Calling :meth:advance moves the simulation to the given date by running valuation, rule application, accounting, metrics, and emitting :class:DateAdvanced. No step-back support — history is external.

Methods:

advance –

Advance the simulation by one calendar day (or to an explicit date).
initialize_from_snapshot –

Set the simulation state after loading a snapshot with opening balances.

Attributes:

current_date (date | None) –

The most recently advanced date, or None.
end_date (date | None) –

The last available simulation date.
start_date (date | None) –

The configured simulation start date, or None.

current_date `property`

current_date: date | None

The most recently advanced date, or None.

end_date `property`

end_date: date | None

The last available simulation date.

start_date `property` `writable`

start_date: date | None

The configured simulation start date, or None.

advance

advance(date: date | None = None) -> None

Advance the simulation by one calendar day (or to an explicit date).

Steps performed (in order): 1. Determine the target date (next calendar day or explicit). 2. Fetch market state if available for this date. 3. Value all positions (only on market-data days). 4. Apply rules via the rule engine to obtain transactions. 5. Post all transactions to the ledger via the accounting service. 6. Record the transaction batch in the transaction log. 7. Compute metrics (only on market-data days). 8. Emit granular events and :class:DateAdvanced.

initialize_from_snapshot

initialize_from_snapshot(
    start_date: date, end_date: date | None = None
) -> None

Set the simulation state after loading a snapshot with opening balances.

The snapshot represents ledger state as of start_date - 1. Setting _current_date to that date ensures the first advance() sees a proper previous_date — accrual rules then compute the correct one-day delta instead of reposting from the last coupon/payment reset.

simulation_service