calminer-docs/specifications/monte_carlo_simulation.md

Monte Carlo Simulation Specification

1. Purpose

Define the configuration, inputs, and outputs for CalMiner's Monte Carlo simulation engine used to evaluate project scenarios with stochastic cash-flow assumptions. The engine augments deterministic profitability metrics by sampling cash-flow distributions and aggregating resulting Net Present Value (NPV), Internal Rate of Return (IRR), and Payback Period statistics.

2. Scope

• Applies to scenario-level profitability analysis executed via services/simulation.py.
• Covers configuration dataclasses (SimulationConfig, CashFlowSpec, DistributionSpec) and supported distribution families.
• Outlines expectations for downstream reporting and visualization modules that consume simulation results.

3. Inputs

3.1 Cash Flow Specifications

Each Monte Carlo run receives an ordered collection of CashFlowSpec entries. Each spec pairs a deterministic CashFlow (amount, period index/date) with an optional DistributionSpec. When no distribution is provided the deterministic value is used for every iteration.

3.2 Simulation Configuration

SimulationConfig controls execution:

Field	Description
iterations	Number of Monte Carlo iterations (must be > 0).
discount_rate	Annual discount rate (decimal) passed to NPV helper.
seed	Optional RNG seed to ensure reproducible sampling.
metrics	Tuple of requested metrics (npv, irr, payback).
percentiles	Percentile cutoffs (0–100) computed for each metric.
compounds_per_year	Compounding frequency reused by financial helpers.
return_samples	When True, raw metric samples are returned alongside summaries.
residual_value / residual_periods	Optional residual cash flow inputs reused by NPV.

3.3 Context Metadata

Optional dictionaries provide dynamic parameters when sourcing distribution means or other values:

• scenario_context: scenario-specific values (e.g., salvage mean, cost overrides).
• metadata: shared configuration (e.g., global commodity price expectations).

4. Distributions

DistributionSpec defines stochastic behaviour:

Property	Description
type	normal, lognormal, triangular, or discrete.
parameters	Mapping of required parameters per distribution family.
source	How base parameters are sourced: static, scenario_field, or metadata_key.
source_key	Identifier used for non-static sources.

4.1 Parameter Validation

• normal: requires non-negative std_dev; defaults mean to baseline cash flow amount when omitted.
• lognormal: requires mean (mu in log space) and non-negative sigma.
• triangular: requires min, mode, max with constraint min <= mode <= max.
• discrete: requires paired values/probabilities sequences; probabilities must be non-negative and sum to 1.0.

Invalid definitions raise DistributionConfigError before sampling.

5. Algorithm Overview

1. Seed a NumPy Generator (default_rng(seed)) unless a generator instance is supplied.
2. For each iteration:
   • Realise cash flows by sampling distributions or using deterministic values.
   • Compute requested metrics using shared helpers from services/financial.py:
     • NPV via net_present_value (respecting residual_value inputs).
     • IRR via internal_rate_of_return; non-converging or invalid trajectories return NaN and increment failed_runs.
     • Payback via payback_period; scenarios failing to hit non-negative cumulative cash flow record NaN.
3. Aggregate results into per-metric arrays; calculate summary statistics: mean, sample standard deviation, min/max, and configured percentiles using numpy.percentile.
4. Assemble SimulationResult containing summary descriptors and optional raw samples when return_samples is enabled.

6. Outputs

SimulationResult includes:

• iterations: total iteration count executed.
• summaries: mapping of SimulationMetric to MetricSummary objects with:
  • mean, std_dev, minimum, maximum.
  • percentiles: mapping of configured percentile cutoffs to values.
  • sample_size: number of successful (non-NaN) samples.
  • failed_runs: count of iterations producing NaN for the metric.
• samples: optional mapping of metric to raw numpy.ndarray of samples when detailed analysis is required downstream.

7. Error Handling

• Invalid configuration or missing context raises DistributionConfigError.
• Zero iterations or invalid percentile ranges raise ValueError.
• Financial helper exceptions (ConvergenceError, PaybackNotReachedError) are captured per iteration and converted to NaN samples to preserve aggregate results while flagging failure counts.

8. Usage Guidance

• Scenario services should construct CashFlowSpec instances from persisted financial inputs and optional uncertainty definitions stored alongside the scenario.
• Reporting routes can request raw samples when producing histogram or violin plots; otherwise rely on MetricSummary statistics for tabular output.
• Visualizations implementing FR-005 should leverage percentile outputs to render fan charts or confidence intervals.
• When integrating with scheduling workflows, persist the deterministic seed to ensure repeated runs remain comparable.

9. Testing

tests/test_simulation.py covers deterministic parity with financial helpers, seed reproducibility, context parameter sourcing, failure accounting for metrics that cannot be computed, error handling for misconfigured distributions, and sample-return functionality. Additional regression cases should accompany new metrics or distribution families.

10. References

• Implementation: calminer/services/simulation.py
• Financial helpers: calminer/services/financial.py
• Tests: calminer/tests/test_simulation.py
• Related specification: calminer-docs/specifications/financial_metrics.md