---
name: run_market_sim
kind: pipeline
lang: py
domain: pipelines
version: "1.0.0"
purity: impure
signature: "def run_market_sim(initial_price: float, n_ticks: int, sigma: float, mu: float, jump_intensity: float, jump_size_std: float, n_makers: int, maker_spread: float, gamma: float, maker_levels: int, maker_qty: float, n_takers_lambda: float, taker_size_alpha: float, taker_size_min: float, taker_size_max: float, hawkes_alpha: float, hawkes_beta: float, seed: int) -> dict"
description: "Simula un mercado completo con matching engine FIFO. Makers usan Avellaneda-Stoikov, takers llegan según proceso Hawkes con tamaños power-law. Retorna trades, spreads, midprices y PnL de makers."
tags: [simulation, market, matching-engine, montecarlo, launcher, finance, microstructure]
uses_functions:
  - generate_gbm_prices_py_finance
  - avellaneda_stoikov_quotes_py_finance
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [numpy]
params:
  - name: initial_price
    desc: "Precio inicial del activo"
  - name: n_ticks
    desc: "Número de ticks a simular"
  - name: sigma
    desc: "Volatilidad del precio fundamental"
  - name: mu
    desc: "Drift del precio fundamental"
  - name: jump_intensity
    desc: "Intensidad de saltos de Poisson"
  - name: jump_size_std
    desc: "Desviación estándar de tamaños de salto"
  - name: n_makers
    desc: "Número de market makers"
  - name: gamma
    desc: "Parámetro de aversión al riesgo de Avellaneda-Stoikov"
  - name: hawkes_alpha
    desc: "Parámetro de excitación del proceso Hawkes"
  - name: seed
    desc: "Seed para reproducibilidad"
output: "Dict con trades, spreads, midprices, PnL de makers y estadísticas del matching"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/pipelines/run_market_sim.py"
---

## Ejemplo

```bash
python python/functions/pipelines/run_market_sim.py
# {
#   "total_trades": 1234,
#   "mean_spread": 0.4821,
#   "maker_pnls": [12.5, -3.2, 8.1, 5.6, -1.4]
# }
```

```python
from run_market_sim import run_market_sim

result = run_market_sim(
    initial_price=100.0,
    n_ticks=200,
    sigma=0.01,
    n_makers=3,
    seed=0,
)
print(result['total_trades'])
print(result['maker_pnls'])
```

## Flujo

1. `generate_gbm_prices` — genera la serie de precios fundamentales con GBM + saltos
2. Loop por ticks:
   - Cada maker coloca quotes via `avellaneda_stoikov_quotes`
   - Takers llegan según Poisson con intensidad modulada por excitación Hawkes
   - Tamaños de taker siguen distribución Pareto (power-law)
   - Matching FIFO sobre el order book simplificado
   - Excitación Hawkes decae exponencialmente entre ticks
3. Mark-to-market final de inventarios de makers

## Notas

Los parámetros Hawkes (`hawkes_alpha`, `hawkes_beta`) controlan la autocorrelación del flujo de órdenes.
`branching_ratio = hawkes_alpha / hawkes_beta`; si > 1, el proceso es explosivo.
El matching es simplificado: no hay cancelaciones intra-tick, el book se reconstituye en cada tick.
