cuopt-numerical-optimization-api-cli

cuOpt 数値最適化 — CLI

cuopt_cli を使用して、MPS または LP ファイルから LP、MILP、QP 問題を解きます。3 つすべてで同じコマンドとオプションを使用できます。QP は MPS（QPS）ファイルと LP ファイルの両方でサポートされています。

コーディングの前に、問題の種類と定式化（変数、目的関数、制約、変数の種類）を確認してください。

このスキルは CLI 専用 です（MPS または LP ファイル入力）。

基本的な使い方

cuopt_cli <problem-file> [options]

最初の位置引数は入力ファイルです。形式は拡張子から自動的に選択されます。MPS、QPS、LP ファイル（.gz／.bz2 圧縮ファイルを含む）をすべて受け付けます。サポートされている拡張子の正確な一覧は、cuopt_cli --help を実行して確認してください。

オプション

cuopt_cli --help が正式な一覧です。固定された一部のオプションだけを前提にしないでください。 CLI では、実行時にパラメーター一覧から生成されたすべてのソルバー設定がフラグとして公開されます。cuOpt 設定リファレンスに記載されている任意のパラメーターで、アンダースコアをハイフンに置き換えてください（time_limit → --time-limit、mip_relative_gap → --mip-relative-gap）。したがって、ドキュメントに記載されているパラメーターにはフラグが存在します。名前、意味、デフォルト値については、--help とソルバー設定ドキュメントを正として参照してください。

CLI 固有のオプション（ソルバーパラメーターではないもの）のうち、パラメーター名からは推測できないため、知っておくとよいものをいくつか紹介します。

• --params-file <file> — フラグを繰り返し指定する代わりに、key = value 形式の設定ファイルから複数のパラメーターを指定します。
• --relaxation — MILP の連続緩和問題を解きます（整数制約を除外します）。
• --initial-solution <file> — 解ファイルを使ってウォームスタートします。

最新のオプション一覧は、cuopt_cli --help を実行して確認してください。

入力ファイルの作成

MPS、QPS、LP は、外部で仕様が定められた厳密なファイル形式です。レイアウトの記憶やあいまいな記憶だけを頼りに、手作業で作成しないでください。列位置のルール、マーカーの規約、二次目的関数のエンコード方法、符号やスケーリングの規約は、少しの違いで誤りやすく、不正なファイルは解析に失敗するか、意図とは異なるモデルを気付かないうちにエンコードしてしまいます。

ファイルをすでに持っていてそれを解くのではなく、データからモデルを構築する場合は、cuOpt Python API または任意のモデリングインターフェースで問題を定義してください。CLI に渡す MPS ファイルや LP ファイルを手作業で生成しないでください。 これらのインターフェースでは、係数、境界、変数の型をネイティブのデータ構造として指定するため、誤りやすいテキスト形式を扱う必要がありません。cuOpt Python API では同じプログラム内で問題を解いて解を返します（cuopt-numerical-optimization-api-python スキルを参照）。別のモデリングライブラリ（PuLP、Pyomo、JuMP など）では、CLI 用の有効なファイルをエクスポートするか、そのライブラリ独自のソルバーを呼び出せます。cuopt_cli を使うのは、すでにモデルファイルがある場合にしてください。たとえば、ベンチマーク用インスタンスや、これらのツールでエクスポートしたファイルが該当します。

ファイルを生成することが本当に適切な場合でも、手作業ではなくプログラムで生成してください。

• cuOpt の Python API から生成する場合 — モデルを構築してから、model.writeMPS("problem.mps") でエクスポートします（QP の二次目的関数を含む有効な MPS ファイルを生成します）。その後、cuopt_cli problem.mps で解きます。
• 別のモデリングツールから生成する場合 — 多くの LP／MILP モデリングライブラリやソルバーは、標準の MPS ファイルまたは LP ファイルをエクスポートできます。エクスポートしたファイルをそのまま cuopt_cli に渡してください。

それでもこれらの形式を手作業で読み書きする必要がある場合は、例だけを参考にするのではなく、形式の完全な仕様と、二次目的関数のエンコード方法など cuOpt 固有の規約が記載された cuOpt リポジトリのドキュメント docs/cuopt/source/cuopt-cli/ を参照してください。

いずれの場合も、結果を信頼する前に検証してください。解析に成功すると cuopt_cli は Read file ... をログに出力し、変数数、制約数、目的関数の値を報告します。これらが意図したモデルと一致するか、妥当性を確認してください。

QP に関する注意事項（ベータ版）： 二次目的関数は MINIMIZE のみに対応しています（最大化する場合は、二次項を含め目的関数の符号を反転してください）。また、連続変数のみが必要です（二次目的関数と整数変数を混在させることはできません）。QP 固有のフラグについては、cuopt_cli --help を確認してください。

トラブルシューティング

• 入力ファイルの解析に失敗した — 拡張子が形式（.lp と .mps／.qps）に一致していることを確認してください。認識されない拡張子は解析前に拒否されます。パーサーのエラーには問題のある行が示されます。形式仕様に照らして修正するか、（より確実な方法として）手作業で修正するのではなく、モデリングツールからファイルを再生成してください。
• 実行可能解がない — 制約の向き、右辺、変数の境界が、意図した定式化と一致しているか再確認してください。

例

• assets/README.md — MPS サンプルファイルのビルド／実行
• lp_simple — 最小構成の LP（PROD_X、PROD_Y、2 つの制約）
• lp_production — 生産計画：椅子とテーブル、木材／労働力
• milp_facility — バイナリ変数を使った施設の開設／閉鎖

CLI の入手

CLI は Python パッケージ（cuopt）に含まれています。pip または conda でインストールし、cuopt_cli --help を実行して確認してください。