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

        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.