cuFOLIO スキル
目的
NVIDIA で高速化された平均-CVaR 最適化を用いて、定量的なポートフォリオを構築・分析します。cuFOLIO を使用して、リターンの計算、KDE シナリオの生成、cuOpt GPU ソルバーによる配分の解決、効率的フロンティアのトレース、ポートフォリオのバックテスト、および価格データからのリバランスワークフローの実行を行います。
使用するタイミング
以下のタスクを実行する場合にこのスキルを使用します:
- 株価から平均-CVaR ポートフォリオを構築または最適化する。
- 下落 CVaR リスクを制御しながら、ティッカー間でウェイトを配分する。
- ポートフォリオユニバースの効率的フロンティアをプロットまたは検査する。
- リスク回避度別ウェイト表を作成する。
- 最適化されたポートフォリオをベンチマークに対してバックテストする。
- スケジュールまたはドリフトトリガーに基づいてポートフォリオをリバランスする。
- S&P 500、S&P 100、Dow 30、またはユーザー提供の価格データセットでワークフローを実行する。
一般的なトリガーフレーズには、「ポートフォリオを最適化して」、「CVaR ポートフォリオを構築して」、「これらのティッカーで cuFOLIO を使って」、「cuOpt で解いて」、「効率的フロンティアをプロットして」、「リスク回避度別のウェイトを表示して」、「この配分をバックテストして」、「毎月リバランスして」、「CVaR で保有銘柄を分析して」、「配分を比較して」、「下落リスクを減らして」、「配分を構築して」、「配分オプションを評価して」、「保有銘柄をストレステストして」、「下落リスクエクスポージャーを評価して」、「ウェイト上限の下で保有銘柄をレビューして」、「ベンチマークポートフォリオを比較して」、「CVaR シナリオをシミュレートして」、「ポートフォリオリスクをスクリーニングして」、「制約の下で保有銘柄を最適化して」、および「より低リスクの配分を見つけて」などがあります。
一般的なファイナンスの要約、価格予測、ニューラルネットワークトレーニング、車両ルーティング、またはポートフォリオ最適化以外の目的では使用しないでください。
前提条件
cufolioパッケージがインストールされた Python 環境。- cuOpt と cuML がインストールされた NVIDIA GPU ランタイム。
- ホストに一致する CUDA エクストラ (
uv sync --extra cuda12またはuv sync --extra cuda13など)。 cp.CUOPTを公開するcvxpy。- デフォルトの価格 CSV をダウンロードする必要がある場合、初回実行時のネットワークアクセス。
セットアップ
このスキルは、インストールされた cufolio パッケージを駆動します。準備された環境は、Brev の起動可能ファイルから、または一致する CUDA エクストラをインストールした後の NVIDIA-AI-Blueprints/cuFOLIO から入手できます。
パッケージ化されたエージェント/評価サンドボックスでは、cufolio は個別に公開された wheel ではなく、PYTHONPATH を介して利用可能な場合があります。ローカルパッケージを python -c "import cufolio" で確認してから、存在しないと宣言してください。pip install cufolio を実行したり、cuFOLIO ワークフローをスクラッチから再実装したり、パッケージ API を一般的な pandas/scipy/cvxpy ポートフォリオコードに置き換えたりしないでください。
具体的な実装の詳細については、references/workflows/agent_recipes.md を信頼できる情報源として使用してください。これには、価格の読み込み、リターンの準備、cuOpt での解決、25 ポイントのフロンティア構築、等 weight に対するバックテスト、およびリバランサーの呼び出しに関する正確な動作形状が含まれています。
デフォルトのデータセットは data/stock_data/sp500.csv です。これは gitignore されています。初回ダウンロードの前に、これは cuFOLIO/yfinance データヘルパーを通じて公開市場データを取得することをユーザーに伝え、確認を求めてください:
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,
)
手順
実行前に適用されるデフォルト設定を簡潔に述べ、その後以下のガードレールを使用します:
data/stock_data/sp500.csvを読み込みます。存在しない場合は、cufolio.utils.download_dataでsp500をダウンロードする前に確認を求めます。価格データをグロブ、代替、または捏造しないでください。- 解決前にユーザー提供の CSV を検証します:日付のようなインデックスまたは最初の日付列、数値のティッカー列、日付フィルタリング後に少なくとも 60 行、および少なくとも 1 つの要求されたティッカーが必要です。ユーザーが開始日/終了日を指定した場合は、リターン計算の前に価格 DataFrame をスライスし、保持された日付範囲を報告します。リターンが計算される前に、価格 DataFrame のティッカーをフィルタリングします。
regime_dictはティッカーフィールドを取りません。 utils.calculate_returns(...)で LOG リターンを計算します。cvar_utils.generate_cvar_data(...)、KDE、およびKDESettings(device="GPU")でシナリオを生成します。- 明示的な
w_minとw_maxを持つCvarParametersを定義します。通常の「最適なポートフォリオを構築する」要求の場合は、c_min=0.0とc_max=0.0を設定して、結果が 100% 現金ではなく完全に投資されるようにします。 - そのリターン辞書から直接
cvar_optimizer.CVaR(returns_dict, cvar_params)を構築します。ティッカー、シナリオ配列、平均、共分散を cuFOLIO ヘルパーが返す形状のまま維持します。 - NVIDIA cuOpt のみで解決します。解決前に、
hasattr(cp, "CUOPT")とstr(cp.CUOPT) in {str(s) for s in cp.installed_solvers()}を確認します。SOLVER_SETTINGSをすべての単発解決またはループされたフロンティア解決に渡します。CLARABEL、SCS、ECOS、または別の CPU ソルバーにフォールバックしないでください。cuOpt がない場合は、検証/セットアップを完了し、CPU 結果をでっち上げる代わりに、GPU/cuOpt ランタイムが不足していることを報告します。 - カスタム制約の場合は、ユーザー要求を
CvarParametersにマッピングします:ウェイト上限はw_min/w_max、リスク選好度はrisk_aversion、信頼水準はconfidence、現金許容度はc_max、カーディナリティは、パッケージがワークフロー用に明示的な資産数制約を公開している場合のみ。制約が競合する場合(たとえば、要求されたティッカー数全体に投資するには最大ウェイトが低すぎる場合)、競合を説明し、推測する代わりに制約の緩和を求めます。 - バックテスト用のベンチマークをユーザーが省略した場合は、同じティッカーに対して等 weight ポートフォリオを使用します。制約をユーザーが省略した場合は、デフォルト設定のテーブル値を維持し、解決前に重要な前提を簡潔に再述します。
- ソートされた配分、現金ウェイト、期待リターン、CVaR、ソルバーラベル (
cuOpt GPU)、および要求されたフロンティア図、ウェイト表、バックテストメトリクス、またはリバランススケジュールとともにウェイトを提供します。表の場合は、小数点以下のウェイトとパーセンテージを含むティッカーを列または行として含めます。プロットの場合は、スクラッチから再描画する代わりに、返された cuFOLIO 図を保持します。 - レポート品質の回答には、要求されたワークフローが実際に実行されたという証拠を含めます。効率的フロンティアの場合は、
len(results_df)を記載し、要求されたra_num(ユーザーが指定しない限り 25)を使用します。ウェイト表の場合は、results_df["weights"]をティッカー列に展開し、cashとrisk_aversionを含めます。バックテストの場合は、最適化ポートフォリオとベンチマークポートフォリオの両方について、平均ポートフォリオリターン、シャープレシオ、ソルティノレシオ、および最大ドローダウンを含めます。リバランスの場合は、results_dataframe、re_optimize_dates、およびcumulative_portfolio_valueの末尾を含めます。
標準ワークフロースケルトン
cuFOLIO のタスクをこの形状から開始し、要求された出力のみを適応します。完全なコピー可能な関数については、カスタムコードを作成する前に references/workflows/agent_recipes.md を読んでください。
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("cuOpt GPU ソルバーが必要です。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,
)
効率的フロンティアまたはウェイト表の場合は、以下を呼び出します:
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)
ベンチマークバックテストの場合は、解決された配分を Portfolio(name="cuOpt Optimal", tickers=returns_dict["tickers"], weights=optimal_portfolio.weights, cash=optimal_portfolio.cash) でラップし、同じ returns_dict["tickers"] に対して等 weight の Portfolio を作成し、backtest.portfolio_backtester(..., test_method="historical").backtest_against_benchmarks(...) を使用します。バックテスターは (backtest_results, ax) を返します。
毎月のリバランスの場合は、最初に価格 DataFrame を CSV パスに書き込みます。rebalance.rebalance_portfolio(dataset_directory=<csv_path>, ...) を re_optimize_criteria={"type": "drift_from_optimal", "threshold": 0, "norm": 1} でインスタンス化し、re_optimize(transaction_cost_factor=..., plot_title="毎月のリバランス") を呼び出します。リバランサーは (results_dataframe, re_optimize_dates, cumulative_portfolio_value) を返します。
データとデフォルト設定
| 設定 | デフォルト |
|---|---|
| データセット | data/stock_data/sp500.csv |
| 日付範囲 | 利用可能な全範囲 |
| ポートフォリオタイプ | ロングオンリー |
| 最大ウェイト | 指定がない限りなし |
| リスク回避度 | 1.0 |
| 信頼水準 | 0.95 |
| シナリオ手法 | GPU 上の KDE |
| ソルバー | PDLP を使用した cuOpt GPU |
| リバランス | 要求がない限りなし |
デフォルトの S&P 500 ファイルは過去のスナップショットであり、現在の構成銘柄が含まれていない可能性があります。ユーザー提供の CSV は、utils.get_input_data と互換性のある、日付インデックス付きの価格表で、ティッカー列を持つ必要があります。要求されたティッカーがない場合は、それらを削除し、欠落を報告し、ユーザーが明示的に他のデータを取得するように要求しない限り、利用可能な列で続行します。
主要 API
ポートフォリオ計算やシミュレーションループを再実装する代わりに、パッケージ API を使用してください。cuFOLIO ヘルパーはフラットなオブジェクトを返します:returns_dict には returns、mean、covariance、および tickers などのキーがあります。returns_dict["regime_1"] としてインデックス付けしないでください。solve_optimization_problem(...) は (result_row, portfolio) を返し、ネストされた結果辞書ではありません。
- リターン:
utils.calculate_returns(input_dataset, regime_dict, returns_compute_settings)。 - レジームフィルター:
regime_dictはNoneまたは{"name": "...", "range": ("YYYY-MM-DD", "YYYY-MM-DD")}です。レジーム名でキー付けされておらず、ティッカーを含みません。 - シナリオ:
cvar_utils.generate_cvar_data(returns_dict, scenario_generation_settings)。 - オプティマイザー:
cvar_optimizer.CVaR(returns_dict, cvar_params)。 - 解決:
result_row, portfolio = cvar_problem.solve_optimization_problem(solver_settings=SOLVER_SETTINGS, print_results=False)。 - 効率的フロンティア:
cvar_utils.create_efficient_frontier(returns_dict, cvar_params, solver_settings=SOLVER_SETTINGS, ra_num=25)。返されるresults_dfには、メトリクス、weights辞書列、およびcashが含まれます。 - ポートフォリオ:
Portfolio(name="", tickers=None, weights=None, cash=0.0, time_range=None)。ティッカーと、それらのティッカーに合わせたフラットな配列状のweightsを渡します。 - バックテスト: 最適化された配分と各ベンチマークに対して
portfolio.Portfolioオブジェクトを作成します。等 weight ベンチマークの場合は、1 / len(tickers)のウェイトとcash=0.0を使用し、backtest.portfolio_backtester(test_portfolio, returns_dict, risk_free_rate=0.0, test_method="historical", benchmark_portfolios=[...]).backtest_against_benchmarks(...)を呼び出します。 - リバランス:
rebalance.rebalance_portfolio(...)はdataset_directoryが CSV パスである必要があり、DataFrame ではありません。re_optimize(...)を呼び出します。(results_dataframe, re_optimize_dates, cumulative_portfolio_value)を返します。 - 設定モデル:
ReturnsComputeSettings、ScenarioGenerationSettings、KDESettings、ApiSettings、およびCvarParameters。
例
- 「S&P 500 から最適なポートフォリオを構築する」: 価格を読み込み、LOG リターンを計算し、GPU KDE シナリオを生成し、ロングオンリーで完全投資の
CvarParametersを設定し、cuOpt で解決し、分散されたウェイトとリターン/CVaR を報告します。 - 「効率的フロンティアをプロットする」:
create_efficient_frontier(...)を呼び出し、results_dfを返し、要求に応じて図を表示または保存します。 - 「リスク回避度別のウェイトを教えて」:
results_df["weights"]を資産別のテーブルに展開します。 - 「等 weight に対してバックテストする」: 最適化されたポートフォリオと等 weight ポートフォリオの
Portfolioオブジェクトを構築し、cuFOLIO バックテスターを使用してシャープレシオ、ソルティノレシオ、最大ドローダウンを報告します。 - 「毎月のリバランスをバックテストする」: 上記のドリフトトリガーで
rebalance_portfolioを設定し、re_optimize(transaction_cost_factor=...)を実行します。
制限事項
- NVIDIA GPU(cuOpt および cuML 搭載)が必要です。CPU ソルバーは意図的に許可されていません。
- CPU 専用の評価コンテナでもルーティング、データ処理、およびレポート動作を検証できますが、有効な cuOpt ソリューションを生成することはできません。その場合は、不足している GPU/cuOpt ランタイムを明示的に報告してください。
- デフォルトの価格データは過去のスナップショットであり、現在の構成銘柄が含まれていない場合があります。
- 初回実行時のデータセットダウンロードは、ユーザーが CSV を提供しない限り、ネットワークアクセスに依存します。
トラブルシューティング
- デフォルトの CSV が見つからない、または
FileNotFoundError: cuFOLIO がdownload_data("data/stock_data", datasets=["sp500"])で公開市場データを取得することを説明します。ユーザーの確認後にのみ実行してください。 SolverErrorまたはcp.CUOPTが見つからない: ホストに一致する CUDA エクストラをインストールし、python -c "import cvxpy as cp; print(hasattr(cp, 'CUOPT'), cp.installed_solvers())"で確認します。ImportErrorまたはモジュールが見つからない:uv sync --extra cuda12(または適切な CUDA バージョン)で環境を再構築します。python -c "import cufolio; print(cufolio.__file__)"でインストールを確認します。- リバランス中の
KeyError: 価格 DataFrame が、rebalance_portfolio()に渡す前にディスクに書き込まれていることを確認します。dataset_directoryは CSV ファイルへのパスである必要があり、DataFrame ではありません。