Hyperparamètres

Les hyperparamètres permettent à une définition de stratégie de produire un ensemble contrôlé de backtests. AQE énumère les domaines de manière paresseuse, exécute chaque combinaison séquentiellement et enregistre les valeurs exactes avec une seed déterministe. Un run normal conserve les valeurs fallback de la stratégie.

Définir une configuration

Créez un HyperParameterConfig et enregistrez chaque paramètre une fois. values() définit un ensemble discret. range(min, max, increment) crée un domaine numérique. Le fallback fourni à HyperParameter::new() est utilisé sans flag hyperparamètre.

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() est facultatif. Sans lui, AQE dérive un identifiant stable depuis la configuration. Donnez-lui une valeur explicite pour un nom de dossier de balayage reconnaissable.

Utiliser une valeur dans la stratégie

Lisez une valeur active depuis le contexte avec les helpers typés. Le dernier argument reste le fallback codé en dur pour un run ordinaire.

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,
);

Utilisez ces valeurs lors de la construction d’un modèle alpha, d’un insight pipe ou de tout autre composant de stratégie. L’exemple hyperparameter d’AQE relie les deux entrées au modèle EMA crossover intégré et ajoute un pipeline de soumission.

Exécuter

Attachez la configuration à chaque StrategyState, puis conservez les runners d’état ordinaires. Un état sans configuration garde exactement son comportement précédent. Avec une configuration, l’état résout automatiquement --hyper-seed avant run_backtest() ou run_live().

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

Pour un balayage complet, énumérez hyperparameters.process_runs(&args), créez un état neuf pour chaque sélection, appelez set_hyper_parameter_config(config.clone()), puis set_hyper_parameter_run(&selection, true) avant le run_backtest() habituel. Un état terminé possède l’état mutable du courtier et de la stratégie ; il ne peut donc pas être réutilisé pour la seed suivante.

Pour le live, utilisez la même forme : attachez la configuration puis appelez state.run_live(None).await?. Le mode live résout automatiquement une seed sélectionnée et refuse un balayage complet.

La racine d’artefacts est facultative. Sans elle, les résultats sont écrits relativement au répertoire de travail du processus (ou près des métadonnées de stratégie lorsqu’elles existent). Elle ne détermine pas si un run est un balayage : le flag choisi le fait.

Flags de ligne de commande

Commande	Résultat
cargo run --release	Exécute une fois avec les valeurs fallback.
cargo run --release -- --hyper-sweep	Exécute chaque combinaison cartésienne séquentiellement.
cargo run --release -- --hyper-seed c89cfd30	Exécute une combinaison enregistrée. Un préfixe de seed unique est accepté.
cargo run --release -- --live --hyper-seed c89cfd30	Démarre une session live avec cette sélection exacte de paramètres.

La seed sélectionnée doit correspondre à une seule seed générée. AQE retourne une erreur claire si le préfixe ne correspond à aucun run ou à plusieurs runs. Une session live accepte une seule seed ; --hyper-sweep --live est donc refusé. Vous n’avez pas besoin de calculer ou transmettre vous-même une table de permutations JSON.

Résultats et reproductibilité

Pour un balayage complet, AQE écrit sous backtests/hyper/<sweep-id>/<seed>/. Chaque résultat contient la base SQLite habituelle et des métriques enrichies de la seed et des valeurs résolues. La même configuration et la même seed reproduisent la même sélection de paramètres ; les données de marché et toute intégration externe non déterministe doivent aussi rester constantes pour obtenir exactement la même performance.

Utiliser AQS à la place

Dans AlgoQuant Studio, configurez les mêmes domaines dans l’éditeur de nœuds et liez les entrées depuis la barre Hyperparamètres. AQS génère la configuration AQE et gère la sélection de seed. Consultez Hyperparamètres dans AQS.