Compétence cuFOLIO
Objectif
Construire et analyser des portefeuilles quantitatifs avec l'optimisation Mean-CVaR accélérée par NVIDIA. Utilisez cuFOLIO pour calculer les rendements, générer des scénarios KDE, résoudre les allocations avec le solveur GPU cuOpt, tracer une frontière efficace, backtester des portefeuilles et exécuter des workflows de rééquilibrage à partir de données de prix.
Quand l'utiliser
Utilisez cette compétence lorsque la tâche consiste à :
- Construire ou optimiser un portefeuille Mean-CVaR à partir de prix d'actions.
- Allouer des poids entre les tickers tout en contrôlant le risque CVaR à la baisse.
- Tracer ou inspecter une frontière efficace pour un univers de portefeuille.
- Produire un tableau de poids par aversion au risque.
- Backtester un portefeuille optimisé par rapport à des benchmarks.
- Rééquilibrer un portefeuille selon un calendrier ou un déclencheur de dérive.
- Exécuter des workflows sur un ensemble de données de prix S&P 500, S&P 100, Dow 30 ou fourni par l'utilisateur.
Les phrases déclencheuses courantes incluent « optimise mon portefeuille », « construis un portefeuille CVaR », « utilise cuFOLIO sur ces tickers », « résous avec cuOpt », « trace la frontière efficace », « montre les poids par aversion au risque », « backtest cette allocation », « rééquilibre mensuellement », « analyse mes avoirs avec CVaR », « compare les allocations », « réduis le risque à la baisse », « construis une allocation », « évalue les options d'allocation », « teste la résistance de mes avoirs », « évalue l'exposition au risque à la baisse », « révise mes avoirs sous plafonds de poids », « compare les portefeuilles de référence », « simule des scénarios CVaR », « évalue le risque du portefeuille », « optimise les avoirs sous contraintes » et « trouve une allocation à moindre risque ».
Ne l'utilisez pas pour des résumés financiers génériques, des prévisions de prix, l'entraînement de réseaux de neurones, le routage de véhicules ou l'optimisation non liée à un portefeuille.
Prérequis
- Environnement Python avec le package
cufolioinstallé. - Runtime GPU NVIDIA avec cuOpt et cuML installés.
extra CUDAcorrespondant à l'hôte, commeuv sync --extra cuda12ouuv sync --extra cuda13.cvxpyexposantcp.CUOPT.- Accès réseau lors de la première exécution si le fichier CSV de prix par défaut doit être téléchargé.
Configuration
Cette compétence pilote le package cufolio installé. Un environnement prêt peut provenir de l'élément déclencheur Brev ou de NVIDIA-AI-Blueprints/cuFOLIO après avoir installé l'extra CUDA correspondant.
Dans les sandbox d'agents/évaluations empaquetés, cufolio peut être disponible via PYTHONPATH plutôt que comme une wheel publiée séparément. Vérifiez le package local avec python -c "import cufolio" avant de le déclarer manquant. N'utilisez pas pip install cufolio, ne réimplémentez pas les workflows cuFOLIO à partir de zéro et ne remplacez pas les API du package par du code de portefeuille pandas/scipy/cvxpy générique.
Pour les détails d'implémentation concrets, utilisez references/workflows/agent_recipes.md comme source de vérité. Il contient des formes de travail exactes pour charger les prix, préparer les rendements, résoudre avec cuOpt, construire une frontière en 25 points, backtester par rapport à un poids égal et appeler le rééquilibreur.
L'ensemble de données par défaut est data/stock_data/sp500.csv. Il est dans .gitignore. Avant un téléchargement initial, dites à l'utilisateur que cela récupère des données de marché publiques via l'outil d'aide aux données cuFOLIO/yfinance et demandez-lui de confirmer :
import cvxpy as cp
from cufolio.cvar_parameters import CvarParameters
from cufolio.utils import download_data
download_data("data/stock_data", datasets=["sp500"])
SOLVER_SETTINGS = {"solver": cp.CUOPT, "verbose": False, "solver_method": "PDLP"}
cvar_params = CvarParameters(
w_min=0.0, w_max=1.0,
c_min=0.0, c_max=0.0,
risk_aversion=1.0, confidence=0.95,
)
Instructions
Décrivez brièvement les valeurs par défaut appliquées avant l'exécution, puis utilisez ces garde-fous :
- Chargez
data/stock_data/sp500.csv; s'il est manquant, demandez avant de téléchargersp500aveccufolio.utils.download_data. N'utilisez pas de glob, ne substituez pas et ne fabriquez pas de données de prix. - Validez les CSV de l'utilisateur avant de résoudre : exigez un index de type date ou une première colonne de date, des colonnes de tickers numériques, au moins 60 lignes après le filtrage des dates et au moins un ticker demandé. Si l'utilisateur donne des dates de début/fin, découpez le DataFrame de prix avant le calcul des rendements et signalez la plage de dates conservée. Filtrez les tickers sur le DataFrame de prix avant que les rendements soient calculés.
regime_dictne prend pas de champ ticker. - Calculez les rendements LOG avec
utils.calculate_returns(...). - Générez des scénarios avec
cvar_utils.generate_cvar_data(...), KDE etKDESettings(device="GPU"). - Définissez
CvarParametersavec desw_minetw_maxexplicites. Pour les demandes ordinaires de « construire le portefeuille optimal », définissezc_min=0.0etc_max=0.0pour que le résultat soit entièrement investi au lieu de 100 % en liquidités. - Construisez
cvar_optimizer.CVaR(returns_dict, cvar_params)directement à partir de ce dictionnaire de rendements ; conservez les tickers, les tableaux de scénarios, les moyennes et les covariances dans les formes renvoyées par les helpers cuFOLIO. - Résolvez uniquement avec NVIDIA cuOpt. Avant de résoudre, vérifiez
hasattr(cp, "CUOPT")etstr(cp.CUOPT) in {str(s) for s in cp.installed_solvers()}. PassezSOLVER_SETTINGSà chaque résolution unique ou à chaque résolution de frontière en boucle. Ne revenez jamais à CLARABEL, SCS, ECOS ou à un autre solveur CPU. Si cuOpt est absent, terminez la validation/config et signalez que le runtime GPU/cuOpt est manquant au lieu de fabriquer un résultat CPU. - Pour les contraintes personnalisées, mappez les demandes des utilisateurs à
CvarParameters: les plafonds de poids àw_min/w_max, l'appétit pour le risque àrisk_aversion, le niveau de confiance àconfidence, la tolérance de liquidités àc_max, et la cardinalité uniquement lorsque le package expose une contrainte explicite de nombre d'actifs pour le workflow. Si les contraintes entrent en conflit (par exemple, un poids maximum trop bas pour investir sur le nombre de tickers demandé), expliquez le conflit et demandez de relâcher la contrainte au lieu de deviner. - Si l'utilisateur omet un benchmark pour le backtesting, utilisez un portefeuille à poids égal sur les mêmes tickers. Si l'utilisateur omet une contrainte, conservez les valeurs du tableau des valeurs par défaut et reformulez brièvement les hypothèses importantes avant de résoudre.
- Fournissez les poids triés par allocation, poids en liquidités, rendement attendu, CVaR, étiquette du solveur (
cuOpt GPU) et toute figure de frontière demandée, tableau de poids, métriques de backtest ou calendrier de rééquilibrage. Pour les tableaux, incluez les tickers en colonnes ou en lignes avec des poids décimaux et des pourcentages ; pour les graphiques, conservez la figure cuFOLIO renvoyée au lieu de la redessiner à partir de zéro. - Pour les réponses de type rapport, incluez la preuve que le workflow demandé a réellement été exécuté. Pour une frontière efficace, indiquez
len(results_df)et utilisez lera_numdemandé (25 sauf si l'utilisateur spécifie autre chose). Pour un tableau de poids, développezresults_df["weights"]en colonnes de tickers et incluezcashplusrisk_aversion. Pour un backtest, incluezrendement moyen du portefeuille,sharpe,sortinoetdrawdown maximumpour les portefeuilles optimisé et de benchmark. Pour le rééquilibrage, incluezresults_dataframe,re_optimize_dateset la fin decumulative_portfolio_value.
Squelette de workflow canonique
Commencez les tâches cuFOLIO positives à partir de cette forme et adaptez uniquement la sortie demandée. Pour les fonctions copiables complètes, lisez references/workflows/agent_recipes.md avant d'écrire du code personnalisé.
import cvxpy as cp
import pandas as pd
from cufolio import backtest, cvar_optimizer, cvar_utils, rebalance, utils
from cufolio.cvar_parameters import CvarParameters
from cufolio.portfolio import Portfolio
from cufolio.settings import KDESettings, ReturnsComputeSettings, ScenarioGenerationSettings
if not hasattr(cp, "CUOPT") or str(cp.CUOPT) not in {str(s) for s in cp.installed_solvers()}:
raise RuntimeError("Le solveur GPU cuOpt est requis ; ne substituez pas un solveur CPU.")
SOLVER_SETTINGS = {"solver": cp.CUOPT, "verbose": False, "solver_method": "PDLP"}
prices = utils.get_input_data("data/stock_data/sp500.csv")
returns_dict = utils.calculate_returns(
prices,
regime_dict=None,
returns_compute_settings=ReturnsComputeSettings(return_type="LOG"),
)
returns_dict = cvar_utils.generate_cvar_data(
returns_dict,
ScenarioGenerationSettings(
fit_type="kde",
kde_settings=KDESettings(device="GPU"),
),
)
cvar_params = CvarParameters(
w_min=0.0,
w_max=1.0,
c_min=0.0,
c_max=0.0,
risk_aversion=1.0,
confidence=0.95,
)
optimizer = cvar_optimizer.CVaR(returns_dict, cvar_params)
result, optimal_portfolio = optimizer.solve_optimization_problem(
solver_settings=SOLVER_SETTINGS,
print_results=False,
)
Pour une frontière efficace ou un tableau de poids, appelez :
results_df, fig, ax = cvar_utils.create_efficient_frontier(
returns_dict,
cvar_params,
SOLVER_SETTINGS,
ra_num=25,
show_plot=False,
show_discretized_portfolios=False,
benchmark_portfolios=False,
print_portfolio_results=False,
)
weights_table = pd.DataFrame(results_df["weights"].tolist(), index=results_df.index)
Pour un backtest de benchmark, encapsulez l'allocation résolue dans Portfolio(name="cuOpt Optimal", tickers=returns_dict["tickers"], weights=optimal_portfolio.weights, cash=optimal_portfolio.cash), créez un Portfolio à poids égal sur les mêmes returns_dict["tickers"], puis utilisez backtest.portfolio_backtester(..., test_method="historical").backtest_against_benchmarks(...). Le backtesteur renvoie (backtest_results, ax).
Pour un rééquilibrage mensuel, écrivez d'abord le DataFrame de prix dans un chemin CSV. Instanciez rebalance.rebalance_portfolio(dataset_directory=<csv_path>, ...) avec re_optimize_criteria={"type": "drift_from_optimal", "threshold": 0, "norm": 1} et appelez re_optimize(transaction_cost_factor=..., plot_title="Rééquilibrage mensuel"). Le rééquilibreur renvoie (results_dataframe, re_optimize_dates, cumulative_portfolio_value).
Données et valeurs par défaut
| Paramètre | Valeur par défaut |
|---|---|
| Ensemble de données | data/stock_data/sp500.csv |
| Plage de dates | Plage complète disponible |
| Type de portefeuille | Long-only |
| Poids maximum | Aucun sauf spécification |
| Aversion au risque | 1.0 |
| Niveau de confiance | 0.95 |
| Méthode de scénario | KDE sur GPU |
| Solveur | cuOpt GPU avec PDLP |
| Rééquilibrage | Aucun sauf demande |
Le fichier S&P 500 par défaut est un instantané historique et peut omettre les constituants actuels. Les CSV fournis par l'utilisateur doivent être des tableaux de prix indexés par date avec des colonnes de tickers, compatibles avec utils.get_input_data. Si les tickers demandés sont absents, supprimez-les, signalez les omissions et continuez avec les colonnes disponibles, sauf si l'utilisateur vous demande explicitement de récupérer d'autres données.
API clés
Utilisez les API du package au lieu de réimplémenter les mathématiques de portefeuille ou les boucles de simulation. Les helpers cuFOLIO renvoient des objets plats : returns_dict a des clés telles que returns, mean, covariance et tickers ; ne l'indexez pas comme returns_dict["regime_1"]. solve_optimization_problem(...) renvoie (result_row, portfolio), pas un dictionnaire de résultats imbriqué.
- Rendements :
utils.calculate_returns(input_dataset, regime_dict, returns_compute_settings). - Filtre de régime :
regime_dictestNoneou{"name": "...", "range": ("YYYY-MM-DD", "YYYY-MM-DD")}; il n'est pas indexé par nom de régime et ne contient pas de tickers. - Scénarios :
cvar_utils.generate_cvar_data(returns_dict, scenario_generation_settings). - Optimiseur :
cvar_optimizer.CVaR(returns_dict, cvar_params). - Résolution :
result_row, portfolio = cvar_problem.solve_optimization_problem(solver_settings=SOLVER_SETTINGS, print_results=False). - Frontière efficace :
cvar_utils.create_efficient_frontier(returns_dict, cvar_params, solver_settings=SOLVER_SETTINGS, ra_num=25). Leresults_dfrenvoyé inclut des métriques, une colonne de dictionnaireweightsetcash. - Portefeuille :
Portfolio(name="", tickers=None, weights=None, cash=0.0, time_range=None); passez les tickers et un tableau platweightsaligné sur ces tickers. - Backtest : créez des objets
portfolio.Portfoliopour l'allocation optimisée et chaque benchmark ; pour un benchmark à poids égal, utilisez des poids de1 / len(tickers)etcash=0.0, puis appelezbacktest.portfolio_backtester(test_portfolio, returns_dict, risk_free_rate=0.0, test_method="historical", benchmark_portfolios=[...]).backtest_against_benchmarks(...). - Rééquilibrage :
rebalance.rebalance_portfolio(...)nécessite quedataset_directorysoit un chemin CSV, pas un DataFrame. Appelezre_optimize(...); il renvoie(results_dataframe, re_optimize_dates, cumulative_portfolio_value). - Modèles de paramètres :
ReturnsComputeSettings,ScenarioGenerationSettings,KDESettings,ApiSettingsetCvarParameters.
Exemples
- « Construis le portefeuille optimal à partir du S&P 500 » : chargez les prix, calculez les rendements LOG, générez des scénarios KDE GPU, définissez les
CvarParameterslong-only entièrement investis, résolvez avec cuOpt et signalez les poids diversifiés plus le rendement/CVaR. - « Trace la frontière efficace » : appelez
create_efficient_frontier(...), renvoyezresults_dfet affichez ou enregistrez la figure comme demandé. - « Donne-moi les poids par aversion au risque » : développez
results_df["weights"]en un tableau par actif. - « Backtest par rapport au poids égal » : construisez les objets
Portfoliooptimisé et à poids égal, puis utilisez le backtesteur cuFOLIO et signalez le Sharpe, le Sortino et le drawdown maximum. - « Backtest du rééquilibrage mensuel » : configurez
rebalance_portfolioavec le déclencheur de dérive ci-dessus et exécutezre_optimize(transaction_cost_factor=...).
Limitations
- Nécessite un GPU NVIDIA avec cuOpt et cuML ; les solveurs CPU sont intentionnellement interdits.
- Les conteneurs d'évaluation CPU uniquement peuvent toujours valider le routage, la gestion des données et le comportement de rapport, mais ils ne peuvent pas produire une résolution cuOpt valide. Dans ce cas, signalez explicitement le runtime GPU/cuOpt manquant.
- Les données de prix par défaut sont un instantané historique et peuvent omettre les constituants actuels.
- Le téléchargement initial de l'ensemble de données dépend de l'accès réseau, sauf si l'utilisateur fournit un CSV.
Dépannage
- CSV par défaut manquant ou
FileNotFoundError: expliquez que cuFOLIO récupérera les données de marché publiques avecdownload_data("data/stock_data", datasets=["sp500"]); exécutez-le uniquement après confirmation de l'utilisateur. SolverErroroucp.CUOPTmanquant : installez l'extra CUDA correspondant à l'hôte et vérifiez avecpython -c "import cvxpy as cp; print(hasattr(cp, 'CUOPT'), cp.installed_solvers())".ImportErrorou module introuvable : vérifiez quecufolioest accessible viaPYTHONPATHou le chemin d'installation, et ne tentez paspip install cufoliosauf si le package est explicitement disponible sur une source de packages interne.