Skip to content

Algorithm Reference

This section is the authoritative technical reference for every mathematical algorithm used in ForecastAI 2026.01 (Mirabelle). It is written for two audiences:

  • Supply chain planners who need to understand what a method does, when it is selected, and how to interpret its outputs.
  • Developers and data scientists who need to understand the implementation, tune parameters, or extend the system.

What is covered

Chapter Content
Time Series Characterization How each series is profiled before any model is chosen — seasonality, trend, intermittency, stationarity, complexity, and data sufficiency
Outlier Detection IQR, Z-Score, and STL decomposition methods; how outliers are corrected and stored
Forecasting Methods All 10 forecasting algorithms: 5 statistical (StatsForecast), 5 neural (NeuralForecast), and 1 foundation model (TimesFM)
Backtesting & Method Selection Rolling-window walk-forward validation, all accuracy metrics with formulas, and the composite weighted scoring that selects the winning method per series
Distribution Fitting Parametric demand distribution fitting (Normal, Lognormal, Gamma, Poisson, Weibull) for MEIO safety stock
MEIO Theory Multi-Echelon Inventory Optimisation theory: demand characterisation, service level targets, safety stock formulas
K-Curve K-Curve exchange curve: portfolio-level cycle stock optimisation, budget mode, hyperbolic trade-off between inventory investment and order frequency — now with order-frequency constraints (snap-to-grid k points, constrained frontier)
Safety Stock Safety stock formula derivation, service level to fill rate conversion, demand uncertainty models
MEIO EOQ→ROP Loss Function How EOQ refines the reorder point: V1/V2/V3 current-state analysis and the exact Type-2 loss-function improvement plan — also a standalone rich page
EOQ & Lot-Sizing All four lot-sizing methods: Classic EOQ, K-Curve portfolio EOQ, order-frequency constrained EOQ, and Wagner-Whitin dynamic lot-sizing — with full derivations, a worked DP example, the per-item eoq field, shared EOQ overrides, and supplier constraint handling. WW also has a standalone rich page.
Allocation Algorithm 8-pass deterministic Rust engine: scoring formula, priority classes, starvation, fairness, reservation, routing
LP Transport Solver Alternative supply planning engine: Pyomo + HIGHS LP formulation that minimizes total transport cost across multi-echelon networks with reverse logistics
MRP Engine Architecture How the 2-pass Rust MRP actually works: BFS discovery, demand explosion, proportional allocation, echelon depth limits
Causal SQL Engine SQL-first causal demand engine: CTE chain, failure rate waterfall, deployment filtering, override handling, parity testing

Why characterization drives everything

ForecastAI does not apply the same model to every series. The pipeline first characterizes each series (detects seasonality, trend, intermittency, etc.), then routes it to the most appropriate pool of candidate models. Backtesting then determines the winner within that pool.

flowchart LR
    A[demand_actuals] --> B[Outlier Detection]
    B --> C[Characterization]
    C --> D{Route to\nmethod group}
    D --> E[Sparse → SeasonalNaive / HistoricAverage / TimesFM]
    D --> F[Intermittent → Croston / ADIDA / IMAPA]
    D --> G[Complex → NHITS / NBEATS / TFT / PatchTST]
    D --> H[Seasonal → MSTL / AutoETS / NHITS / PatchTST]
    D --> I[Standard → AutoETS / AutoARIMA / AutoTheta / NHITS]
    E & F & G & H & I --> J[Backtesting]
    J --> K[Composite Scoring]
    K --> L[Best Method per Series]

Data flow context

The algorithm pipeline runs inside the broader ForecastAI data pipeline:

PostgreSQL demand_actuals
  → Outlier Detection       (files/outlier/detection.py)
  → Characterization        (files/characterization/characterization.py)
  → Forecasting             (files/forecasting/statistical_models.py
                             files/forecasting/neural_models.py
                             files/forecasting/foundation_models.py)
  → Backtesting             (files/evaluation/)
  → Best Method Selection   (files/selection/best_method.py)
  → Distribution Fitting    (files/distribution/fitting.py)
  → PostgreSQL scenario schema
  → FastAPI / React frontend

Steps 3, 4, and 6 are parallelized via Dask (default: 64 workers, batches of 100 series).

Configuration

All algorithm parameters live in the scenario.parameters PostgreSQL table and are resolved at runtime by the ParameterResolver three-level hierarchy:

  1. Per-SKU hyperparameter override (most specific)
  2. Segment-based parameter set
  3. Default parameter set

See the Configuration Reference for details.