Hiperparámetros

Los hiperparámetros permiten que una definición de estrategia produzca un conjunto controlado de backtests. AQE expande los dominios configurados de forma diferida, ejecuta cada combinación secuencialmente y registra los valores exactos con una semilla determinista. Una ejecución normal conserva los valores de respaldo de la estrategia, por lo que añadir esta funcionalidad no modifica los backtests habituales.

Definir una configuración

Crea un HyperParameterConfig y registra cada parámetro una vez. values() define un conjunto discreto. range(min, max, increment) crea un dominio numérico. El valor de respaldo proporcionado a HyperParameter::new() se usa siempre que no se indique ninguna opción de hiperparámetros.

use aq_engine::prelude::*;

let mut hyperparameters = HyperParameterConfig::new();
hyperparameters
    .set_sweep_id("ema-crossover-v1")
    .add_hyper_parameter(
        HyperParameter::new("atr_period", 14).values([10, 14, 20]),
    )?
    .add_hyper_parameter(
        HyperParameter::new("ema_period", 21).range(10.0, 30.0, 5.0),
    )?;

set_sweep_id() es opcional. Si se omite, AQE deriva un ID estable a partir de la configuración. Asígnale un valor explícito cuando quieras un nombre reconocible y duradero para la carpeta del barrido.

Usar un valor en la lógica de la estrategia

Lee un valor activo del contexto de la estrategia con las funciones auxiliares tipadas. El último argumento sigue siendo el valor de respaldo habitual definido en el código.

let atr_period = aq_engine::core::strategy::hyperparameters::hyper_int(
    ctx,
    "atr_period",
    14_usize,
);
let ema_period = aq_engine::core::strategy::hyperparameters::hyper_int(
    ctx,
    "ema_period",
    21_usize,
);

Usa los valores al construir un modelo alfa, un pipe de insights o cualquier otro componente de estrategia. El ejemplo de hiperparámetros de AQE conecta ambas entradas al modelo alfa integrado de cruce de EMA y añade un pipeline de envío de insights.

Ejecutarlo

Asocia la configuración a cada StrategyState y sigue usando los ejecutores de estado habituales. Un estado sin configuración se comporta exactamente como antes. Un estado con configuración resuelve --hyper-seed automáticamente antes de run_backtest() o run_live().

let mut state = build_strategy_state(timeframe.clone());
state.set_hyper_parameter_config(hyperparameters);
state.run_backtest(start, end, timeframe).await?;

Para un barrido completo, enumera hyperparameters.process_runs(&args), crea un estado nuevo para cada selección, llama a set_hyper_parameter_config(config.clone()) y después a set_hyper_parameter_run(&selection, true) antes del run_backtest() habitual. Un estado completado conserva estado mutable del bróker y de la estrategia, por lo que no se puede reutilizar de forma segura para la siguiente semilla.

Para el modo en vivo, usa la misma estructura: asocia la configuración y llama a state.run_live(None).await?. El modo en vivo resuelve automáticamente una semilla seleccionada y rechaza un barrido completo.

La raíz de los artefactos es opcional. Si no se proporciona, los resultados se escriben con relación al directorio de trabajo del proceso (o a una ubicación adyacente de metadatos de estrategia cuando está disponible). No determina si una ejecución es un barrido: eso lo determina la opción de línea de comandos seleccionada.

Opciones de línea de comandos

Comando	Resultado
cargo run --release	Ejecuta una vez con los valores de respaldo habituales.
cargo run --release -- --hyper-sweep	Ejecuta secuencialmente todas las combinaciones cartesianas.
cargo run --release -- --hyper-seed c89cfd30	Ejecuta una combinación guardada. Se acepta un prefijo de semilla único.
cargo run --release -- --live --hyper-seed c89cfd30	Inicia una sesión en vivo con esa selección exacta de parámetros.

La semilla seleccionada debe identificar una única semilla generada. AQE comunica un error claro si un prefijo no coincide con ninguna ejecución o coincide con más de una. Una sesión en vivo acepta como máximo una semilla, por lo que se rechaza --hyper-sweep --live. No necesitas calcular ni pasar manualmente una tabla JSON de permutaciones.

Resultados y reproducibilidad

Para un barrido completo, AQE escribe los resultados en backtests/hyper/<sweep-id>/<seed>/. Cada resultado contiene la base de datos SQLite habitual del backtest y métricas ampliadas con la semilla y los valores resueltos. La misma configuración de estrategia junto con la misma semilla reproduce la misma selección de parámetros; los datos de mercado y cualquier integración externa no determinista también deben mantenerse constantes para obtener un rendimiento idéntico.

Usar AQS como alternativa

Si usas AlgoQuant Studio, configura los mismos dominios en el editor de nodos y vincula las entradas de los nodos desde la barra lateral Hyperparameters. AQS genera la configuración de AQE y gestiona la selección de semillas por ti. Consulta Hiperparámetros en AQS.