---
name: monte_carlo_market
kind: pipeline
lang: py
domain: pipelines
version: "1.0.0"
purity: impure
signature: "def monte_carlo_market(n_simulations: int, base_params: dict, vary_params: dict, seed_start: int) -> list[dict]"
description: "Ejecuta N simulaciones de mercado con parámetros variados uniformemente. Cada simulación usa run_market_sim y retorna métricas resumen: spreads, trades por tick, volatilidad realizada y PnL total de makers."
tags: [montecarlo, simulation, market, launcher, finance, microstructure]
uses_functions:
  - run_market_sim_py_pipelines
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [numpy]
params:
  - name: n_simulations
    desc: "Número de simulaciones de mercado a ejecutar"
  - name: base_params
    desc: "Parámetros base aplicados a todas las simulaciones"
  - name: vary_params
    desc: "Parámetros a variar uniformemente: {param: (min, max)}"
  - name: seed_start
    desc: "Seed inicial para generador aleatorio (se incrementa por simulación)"
output: "Lista de dicts con parámetros usados y métricas: spreads, trades, volatilidad, PnL"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/pipelines/monte_carlo_market.py"
---

## Ejemplo

```bash
# 10 simulaciones con sigma y gamma variables
python python/functions/pipelines/monte_carlo_market.py -n 10
```

```python
from monte_carlo_market import monte_carlo_market

results = monte_carlo_market(
    n_simulations=50,
    base_params={'n_ticks': 300, 'n_makers': 3},
    vary_params={
        'sigma': (0.005, 0.05),
        'gamma': (0.01, 1.0),
        'hawkes_alpha': (0.1, 0.9),
    },
    seed_start=42,
)
# Cada resultado tiene: sim_id, seed, sigma, gamma, hawkes_alpha,
# total_trades, mean_spread, std_spread, mean_trades_per_tick,
# price_return, maker_total_pnl, realized_vol
```

## Flujo

1. Para cada simulación i en range(n_simulations):
   - Tomar `base_params` + `seed = seed_start + i`
   - Samplear `vary_params` uniformemente con rng derivado de `seed_start`
   - Llamar `run_market_sim(**params)`
   - Calcular métricas resumen sobre el resultado
2. Reportar progreso cada 10% de simulaciones
3. Retornar lista de dicts con params usados + métricas

## Métricas por simulación

| Campo | Descripción |
|---|---|
| `total_trades` | Número total de trades en la simulación |
| `mean_spread` | Spread bid-ask medio |
| `std_spread` | Desviación estándar del spread |
| `mean_trades_per_tick` | Intensidad media del flujo de órdenes |
| `price_return` | Retorno % del precio fundamental |
| `maker_total_pnl` | PnL agregado de todos los makers |
| `realized_vol` | Volatilidad realizada de los trade prices (si hay trades) |

## Notas

`vary_params` acepta cualquier parámetro válido de `run_market_sim` como clave, con valor `(min, max)`.
Los parámetros en `base_params` tienen precedencia sobre los defaults pero son sobreescritos por `vary_params`.
