Scenario YAML Reference

This document summarises the structure expected by the simulator when loading scenario configuration files. The authoritative machine-readable specification lives alongside the loader in simulator/io/scenario_schema.json; editors and validation tooling can use that JSON Schema to lint scenario files before they reach the loader. For single-deal deterministic runs, see Deterministic Deal YAML.

Top-Level Structure

Key	Type	Notes
version	string/number (optional)	Free-form schema or configuration revision identifier.
metadata	object (optional)	Carried through untouched; useful for provenance (owner, timestamps, etc.).
deals	array (required)	At least one deal definition. Each entry must satisfy the Deal Definition section below.
simulation	object (required)	Global simulation controls (scenario count, discounting, etc.).

Deal Definition

Every deal entry captures static attributes, stochastic parameter specifications, and optional collateral/insurance/residual configuration.

Required keys

• id: unique string identifier.

• start_date: ISO date (YYYY-MM-DD).

• parameters: object describing stochastic inputs (principal, rate, term, etc.).

Optional keys

• asset_type: free-form descriptor (e.g. gpu_compute_cluster).

• currency: ISO currency code.

• frequency: payment interval (M, Q, or A). Defaults to monthly.

• collateral: cash collateral configuration (upfront ratio, contribution rules, yield spec).

• insurance_policy: insured value curve and premium assumptions.

• liquidation: recovery schedule to overlay when defaults occur.

• revenue_offsets: fee and rental models contributing to exposure reduction.

• operating_income: operating cash-flow generator; supports constant, probabilistic, or driver modes.

• residual_model: depreciation curve, multipliers, and optional obsolescence shocks.

• downpayment_percent: deterministic borrower equity share (1 - initial LTV).

Within revenue_offsets, supply continuous fee parameters via:

• origination_fee_pct: upfront fee expressed as a fraction of principal (e.g. 0.02 for 2%).

• servicing_fee_pct: annual servicing fee applied to the outstanding balance (decimal form).

• aum_fee_pct: annual fee applied to collateral balances (decimal form).

• Legacy keys (*_percent/*_apr) remain accepted but are deprecated.

Parameters block

Each parameter entry combines a distribution specification with optional truncation and quantisation directives. Distributions are described via spec, whose mode is one of:

• params: direct call-through to SciPy (e.g. {family: "lognorm", params: {...}}).

• quantiles_fit: recover distribution parameters from a list of quantile anchors.

• histogram: discrete histogram defined by bins + counts.

• from_values: empirical samples.

When using quantiles_fit, provide a quantiles array under the spec:

rate:
  spec:
    mode: quantiles_fit
    family: beta
    params:
      lo: 0.02
      hi: 0.25
    quantiles:
      - { q: 0.1, x: 0.035 }
      - { q: 0.5, x: 0.085 }
      - { q: 0.9, x: 0.17 }
  truncation:
    lo: 0.025
    hi: 0.22
  rounding_step: 0.0005

Collateral and insurance

• collateral.contribution supports combinations of fixed amounts, payment percentages, age curves, and ratio-based schedules (mirrors simulator.engine.collateral).

• collateral.yield accepts either a fixed rate ({mode: fixed, rate: 0.02}) or a distribution spec ({mode: distribution, spec: {...}}).

• insurance_policy.insured_value_curve maps month → insured percentage.

Residual model

Define the baseline depreciation curve (straight_line today), optional macro/idiosyncratic multipliers, and a list of obsolescence_shocks. Each shock can carry probabilistic triggers, relative timing, and drop magnitudes/fractions.

Simulation Settings

Key	Type	Notes
n_scenarios	integer (required)	Number of Monte Carlo draws.
discount_rate	number	Portfolio-wide base discount rate.
rng_seed	integer/null	Seed for reproducible draws; omit for stochastic runs.
scenario_discount_rule	object (optional)	Currently supports type: piecewise_rate with an ordered rules array.
deterministic_baseline	object (optional)	Enables deterministic draw (enabled: true) with optional per-field overrides.
output_controls	object (optional)	Path and inclusion toggles for persisted artefacts.

Example discount rule:

scenario_discount_rule:
  type: piecewise_rate
  rules:
    - max_rate: 0.08
      discount_rate: 0.05
    - max_rate: 0.12
      discount_rate: 0.0575
    - discount_rate: 0.065

`hazard_curve.extend_with_last` is an optional boolean that mirrors the loader's default of
extending the final supplied monthly hazard rate across the remaining term when the input
curve is shorter than the simulated horizon.

Validating Scenarios

Run a JSON Schema validator (e.g. jsonschema, ajv, or your IDE integration) against simulator/io/scenario_schema.json before committing new scenarios. Example using jsonschema:

jsonschema -i examples/server_finance_scenario.yaml simulator/io/scenario_schema.json

The loader raises descriptive errors for common issues (missing quantile lists, unknown truncation modes, etc.), but schema validation catches most structural mistakes earlier in the workflow.