---
name: drawdown
kind: function
lang: cpp
domain: datascience
version: "1.0.0"
purity: pure
signature: "DrawdownResult drawdown_max(const double* equity, size_t n); void drawdown_series(const double* equity, size_t n, double* out)"
description: "Max drawdown sobre serie de equity/balance: peak-to-trough absoluto y porcentual + indices del peak y trough relevantes. drawdown_series llena un array con el underwater chart (peak_so_far - equity[i] en cada punto)."
tags: [drawdown, equity, finance, underwater, montecarlo, datascience, pendiente-usar]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [cstddef]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/datascience/drawdown.cpp"
params:
  - name: equity
    desc: "Serie de balance/equity (ej. balance de la sesion en cada spin de vr_tiered_lab, o NAV diario)."
  - name: n
    desc: "Longitud de la serie."
  - name: out
    desc: "(series) buffer destino double[n] con el drawdown corriente en cada punto."
output: "DrawdownResult con max_dd, max_dd_pct (relativo al peak), peak_idx y trough_idx. drawdown_series llena out con peak_so_far - equity[i]."
---

# drawdown

Metrica clave de los simuladores de sesiones (vr_tiered_lab) y de cualquier backtest. Se calcula en una pasada O(n).

## Patron

```cpp
std::vector<double> balance(N);
// ... sesion simulada llena balance[] ...

auto dd = fn::ds::drawdown_max(balance.data(), N);
// dd.max_dd     = mayor caida absoluta
// dd.max_dd_pct = mayor caida porcentual (relativa al peak previo)
// dd.peak_idx   = step donde estaba el peak
// dd.trough_idx = step donde la caida es maxima

// Underwater chart
std::vector<double> uw(N);
fn::ds::drawdown_series(balance.data(), N, uw.data());
fn::viz::line_plot(uw.data(), N, /* fill negativo */);
```

## Notas

- `max_dd_pct` se calcula relativo al peak. Si el peak es <=0 (la serie nunca cruzo cero), devuelve 0 — un drawdown porcentual sobre balance no positivo no esta bien definido.
- Para distribuciones de drawdown sobre N sesiones simuladas Monte Carlo: bucle externo llamando `drawdown_max` por sesion, y luego `stats_quantile` sobre el array de max_dd para CIs. Coste despreciable.
- No es trade analytics completo — no calcula recovery time, time underwater, etc. Se puede añadir si los calculadores lo piden.