# Monte Carlo Engine Overview

This note illustrates how the simulator stitches together parameter draws, deterministic schedule builders, and aggregation utilities to produce per-scenario results. It is useful when explaining why a given assumption (for example, the collateral contribution rule or an obsolescence shock) alters both cash flows and exposure metrics.

## Component Flow

```mermaid
flowchart LR
    subgraph Inputs
        A["SimulationConfig<br/>(principal_param,<br/>rate_param,<br/>term_param,<br/>discount hooks,<br/>models)"]
    end

    subgraph Runner
        B["SimulationRunner"]
        C["ScenarioDraw<br/>(sampled principal,<br/>rate,<br/>term,<br/>residual factors)"]
    end

    subgraph Schedules
        D["amortization_schedule"]
        E["cash_collateral_schedule"]
        G["operating_income.generate"]
        M["Cashflow table<br/>(payments + income)"]
    end

    subgraph ResidualValue
        K["Obsolescence samplers<br/>(probability,<br/>timing,<br/>drop)"]
        F["DepreciationModel.sample<br/>(baseline curve * multipliers)"]
        L["Residual value series"]
    end

    subgraph Aggregation
        H["exposure_schedule<br/>(balance - mitigants)"]
        I["metrics<br/>(NPV, IRR, DSCR)"]
    end

    subgraph Outputs
        J["ScenarioResult<br/>(cashflows,<br/>collateral,<br/>exposure,<br/>metrics,<br/>residual curve)"]
        N["Collateral history"]
    end

    A --> B --> C
    A --> K
    C --> D --> E --> N
    C --> G --> M
    C --> F
    K --> F --> L
    D --> M
    N --> H
    L --> H
    M --> H
    H --> I --> J
    M --> J
    N --> J
    L --> J

    classDef inputStroke stroke:#1f77b4,stroke-width:2px,color:#1f77b4;
    classDef residualStroke stroke:#2ca02c,stroke-width:2px,color:#2ca02c;
    classDef scheduleStroke stroke:#ff7f0e,stroke-width:2px,color:#ff7f0e;
    classDef aggregateStroke stroke:#9467bd,stroke-width:2px,color:#9467bd;
    classDef outputStroke stroke:#8c564b,stroke-width:2px,color:#8c564b;

    class A inputStroke;
    class K residualStroke;
    class D,E,G,M scheduleStroke;
    class F,L residualStroke;
    class H,I aggregateStroke;
    class J,N outputStroke;

    linkStyle 0 stroke:#1f77b4,stroke-width:2px;
    linkStyle 1 stroke:#1f77b4,stroke-width:2px;
    linkStyle 2 stroke:#ff7f0e,stroke-width:2px;
    linkStyle 3 stroke:#ff7f0e,stroke-width:2px;
    linkStyle 4 stroke:#ff7f0e,stroke-width:2px;
    linkStyle 5 stroke:#ff7f0e,stroke-width:2px;
    linkStyle 6 stroke:#2ca02c,stroke-width:2px;
    linkStyle 7 stroke:#2ca02c,stroke-width:2px;
    linkStyle 8 stroke:#ff7f0e,stroke-width:2px;
    linkStyle 9 stroke:#8c564b,stroke-width:2px;
    linkStyle 10 stroke:#9467bd,stroke-width:2px;
    linkStyle 11 stroke:#9467bd,stroke-width:2px;
    linkStyle 12 stroke:#9467bd,stroke-width:2px;
    linkStyle 13 stroke:#9467bd,stroke-width:2px;
    linkStyle 14 stroke:#9467bd,stroke-width:2px;
    linkStyle 15 stroke:#8c564b,stroke-width:2px;
    linkStyle 16 stroke:#8c564b,stroke-width:2px;
    linkStyle 17 stroke:#8c564b,stroke-width:2px;
```

### Reading the Diagram
- **Inputs** highlights the knobs where users attach `BaseParameter` distributions, discount policies, and optional operating income or residual value models (including obsolescence specifications).
- **Runner** shows how `SimulationRunner` converts those definitions into scenario draws before dispatching the deterministic engine.
- **Schedules** capture the deterministic builders that align on the cash-flow calendar, culminating in the combined cashflow table `M`.
- **ResidualValue** makes explicit that depreciation curves are adjusted by macro/idiosyncratic multipliers and optional obsolescence shocks before producing the residual series that mitigates exposure.
- **Aggregation** combines the cashflow table, collateral history, and residual value series into net exposure and summary metrics.
- **Outputs** wraps the assembled data—including the cashflow table, collateral history, and residual curve—in `ScenarioResult`, which portfolio tooling can consume directly.

## Monte Carlo vs. Deterministic Runs

Even though the flow chart focuses on Monte Carlo, the deterministic simulator shares the same schedule builders and aggregation plumbing. The key differences are:

- **Draw source**: Monte Carlo invokes `SimulationRunner.draw_scenario` to sample `principal`, `rate`, `term`, and optional residual factors from the configured `BaseParameter` distributions. Deterministic runs call `SimulationRunner.baseline()` (or use `DeterministicDealSimulator` directly) which plugs in the parameter means you configured.
- **Randomness propagation**: In Monte Carlo mode, any component that accepts an `rng` (collateral, operating income, depreciation obsolescence) can incorporate stochastic draws per scenario. Deterministic mode sets `rng=None`, so those components return their baseline series without noise.
- **Output volume**: Monte Carlo yields an iterable of `ScenarioResult` objects—one per scenario—while deterministic mode returns a single `ScenarioResult` that represents the baseline path. Portfolio tooling can aggregate either a single baseline or the full distribution depending on your use case.
- **Metrics interpretation**: With Monte Carlo you interpret each metric (NPV, IRR, DSCR) across many draws to understand dispersion and tail risk; in the deterministic case you receive a single point estimate that is helpful for sanity checks or documentation.