fn_registry/cpp/functions/datascience/drawdown.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
drawdown	function	cpp	datascience	1.0.0	pure	DrawdownResult drawdown_max(const double* equity, size_t n); void drawdown_series(const double* equity, size_t n, double* out)	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).	drawdown equity finance underwater montecarlo datascience pendiente-usar				false		cstddef	false			cpp/functions/datascience/drawdown.cpp	name desc equity Serie de balance/equity (ej. balance de la sesion en cada spin de vr_tiered_lab, o NAV diario). name desc n Longitud de la serie. name desc out (series) buffer destino double[n] con el drawdown corriente en cada punto.	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

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.