# Easy Solver の使用方法 :::{container} prog-cpp **Easy Solver** は QUBO/HUBO 式のヒューリスティックソルバーです。 Easy Solver を使って問題を解く手順は以下の3ステップで構成されます： 1. `Easy Solver`（または `qbpp::easy_solver::EasySolver`）オブジェクトを作成する。 2. `qbpp::Params` オブジェクトのメンバ関数を呼び出して検索オプションを設定する。 3. `search(params)` メンバ関数を呼び出して解を検索する。これにより、`qbpp::easy_solver::Sols` オブジェクトが返されます。 ## Easy Solver オブジェクトの作成 Easy Solver を使用するには、次のように式（または `qbpp::Expr`）オブジェクトを用いて `Easy Solver` オブジェクト（または `qbpp::easy_solver::EasySolver`）を構築します： - **`qbpp::easy_solver::EasySolver(const qbpp::Expr& f)`** ここで `f` は解く対象の式です。事前に `simplify_as_binary()` 関数を呼び出して、二値式として簡略化されている必要があります。この関数は、与えられた式 `f` を解探索中に使用される内部フォーマットに変換します。 ## 探索パラメータの設定 探索パラメータは `search()` オブジェクトを使用して設定します。 以下のパラメータが利用可能です： | パラメータ | 説明 | デフォルト | |------------|------|------------| | `time_limit` | 制限時間（秒）。`"0"` で時間制限なし。 | `"10.0"` | | `target_energy` | ターゲットエネルギー。この値以下の解が見つかると探索を終了。 | （なし） | | `enable_default_callback` | `"1"` で新たに得られた最良解を出力。 | `"0"` | | `topk_sols` | 保持するtop-k解の数。 | （無効） | | `best_energy_sols` | 最良エネルギーの解を保持。`"0"` で無制限。 | （無効） | パラメータは `search()` に初期化子リストとして渡します： ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` 未知のパラメータキーを設定するとランタイムエラーが発生します。 ## 解の探索 Easy Solver は、`Easy Solver` オブジェクトの `search()` メンバ関数を呼び出すだけで解を探索します。 ## プログラム例 以下のプログラムは、Easy Solver を用いて **低自己相関二値列（Low Autocorrelation Binary Sequences, LABS）問題** の解を探索します： ```{literalinclude} ../../programFiles/cppPrograms/solver/easy-solver-usage-program1.cpp :language: cpp :caption: easy-solver-usage-program1.cpp ``` この例では、以下のオプションが設定されています： - 5.0秒の時間制限 - 目標エネルギー900 - デフォルトのコールバックが有効 したがって、ソルバーは経過時間が5.0秒に達するか、エネルギー900以下の解が見つかった時点で終了します。 例えば、このプログラムは次のような出力を生成します： ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` ## 高度な使用法 ### 複数のトップk解の保持 Easy Solverは探索中に見つかった**複数のtop-k解**を保持できます。 この機能を有効にするには、`topk_sols` パラメータを設定します。 このパラメータが設定されると、`search()`によって返されるソリューションオブジェクトには保存されたトップk解が含まれます。返されたオブジェクト`sols`に対しては、インデックスまたはイテレータを使用して保存された解にアクセスできます： - `sols[i]`：`i`番目の`qbpp::Sol`オブジェクトを返します。 - `size()`：保存された解の数を返します。 - `begin(), end(), cbegin(), cend()`：範囲ベースのforループを使用して順番に各解にアクセスできるイテレータです。 以下のプログラムは、Easy Solverを使用して低自己相関二進列（Low Autocorrelation Binary Sequence、LABS）問題を解きます。`enable_topk_sols(20)`が呼び出されているため、ソルバーは最大20個のトップk解を保持します。プログラムは範囲ベースのforループを使用して各保存された解を出力します。 ```{literalinclude} ../../programFiles/cppPrograms/solver/easy-solver-usage-program2.cpp :language: cpp :caption: easy-solver-usage-program2.cpp ``` このプログラムは次の出力を表示します: ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` ## 複数の最良エネルギー解を保持する Easy Solverは探索中に見つかった最良（最小）エネルギーを共有する複数の解を保持できます。 この機能を有効にするには、`best_energy_sols` パラメータを設定します。 値は保持する最大解数を指定します。`0` で無制限です。 使い方は `topk_sols` と同じです。 したがって、上記のQUBO++プログラムでこの機能を有効にするには、`topk_sols` を `best_energy_sols` に置き換えます： ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` このパラメータが設定された場合、ソルバーは見つかった最良エネルギーと等しいエネルギーの解のみを保持します。 結果として得られるプログラムは、すべて最良エネルギー値26を持つ以下の解を生成します： ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` ::: :::{container} prog-python **Easy Solver** は QUBO/HUBO 式のヒューリスティックソルバーです。 Easy Solver を使って問題を解く手順は以下の2ステップで構成されます： 1. 解きたい式に対して `EasySolver` オブジェクトを作成します。 2. キーワード引数を渡して `search()` メソッドを呼び出し、解を探索します。見つかった最良解が返されます。 ## Easy Solver オブジェクトの作成 Easy Solverを使用するには、以下のように式を引数として `EasySolver` オブジェクトを作成します: - **`EasySolver(f)`** ここで `f` は解く対象の式です。事前に `simplify_as_binary()` 関数を呼び出して、二値式として簡略化されている必要があります。この関数は、与えられた式 `f` を解探索中に使用される内部フォーマットに変換します。コンストラクタは式をホストメモリにロードします。以降 `search()` を複数回呼び出してもこのロードは1度きりなので、同じ式に対して繰り返し探索する際のオーバーヘッドがありません。 ## 探索パラメータの設定 探索パラメータは `search()` メソッドにキーワード引数として直接渡します。 以下のパラメータが利用可能です: | パラメータ | 型 | 説明 | デフォルト | |---|---|---|---| | `time_limit` | `float` | 制限時間（秒）。`0` で時間制限なし。 | `10.0` | | `target_energy` | `int` | 目標エネルギー。この値以下の解が見つかると探索を終了します。 | （なし） | | `enable_default_callback` | `int` (`0` または `1`) | `1` に設定すると、新たに得られた最良解のエネルギーとTTSを自動的に出力します。 | `0` | | `topk_sols` | `int` | 保持するtop-k解の数。 | （無効） | | `best_energy_sols` | `int` | 最良エネルギーの解を保持。`0` で無制限。 | （無効） | パラメータは `search()` にキーワード引数として渡します: ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` 未知のパラメータキーを設定するとランタイムエラーが発生します。 ## 解の探索 Easy Solverは、`search()` メソッドを呼び出すことで解を探索します。必要に応じてパラメータをキーワード引数として渡すことができます。 このメソッドは、見つかった最良解を返します。返される解は `sol.energy`（エネルギー値）、`sol(x)`（変数値の取得）、`sol.info`（ソルバー情報の辞書）などを提供します。詳細は QR_SOLUTION を参照してください。 ## プログラム例 以下のプログラムは、Easy Solver を用いて **低自己相関二値列（Low Autocorrelation Binary Sequences, LABS）** 問題の解を探索します： ```{literalinclude} ../../programFiles/pythonPrograms/solver/easy-solver-usage-program1.py :language: python :caption: easy-solver-usage-program1.py ``` この例では、以下のオプションが設定されています： - 5.0秒の時間制限 - 目標エネルギー900 - 新しい最良解が見つかるたびにエネルギーとTTSを表示するコールバック。 したがって、ソルバーは経過時間が5.0秒に達するか、エネルギー900以下の解が見つかった時点で終了します。 例えば、このプログラムは次のような出力を生成します： ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` ## 複数のtop-k解の保持 Easy Solverは探索中に見つかった**複数のtop-k解**を保持できます。 この機能を有効にするには、`topk_sols` パラメータを設定します。 このパラメータが設定されると、`search()` が返す解は保持されたtop-k解も保持します。 これらは以下のプロパティや操作でアクセスできます: - `sol.sols`: エネルギーの昇順にソートされた解のリスト。 - `sol.sols[i]`: `i` 番目の解を返します。 - `len(sol.sols)`: 保持されている解の数。 以下のプログラムは、Easy Solverを使用してLABS問題を解きます。 `topk_sols` を `20` に設定しているため、ソルバーは最大20個のtop-k解を保持します。 プログラムはrange-based forループを使用して各保持解を出力します。 ```{literalinclude} ../../programFiles/pythonPrograms/solver/easy-solver-usage-program2.py :language: python :caption: easy-solver-usage-program2.py ``` このプログラムは以下のような出力を表示します: ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` ## 複数の最良エネルギー解を保持する Easy Solverは探索中に見つかった最良（最小）エネルギーを共有する複数の解を保持できます。 この機能を有効にするには、`best_energy_sols` パラメータを設定します。 値は保持する最大解数を指定します。`0` で無制限です。 使い方は `topk_sols` と同じです。 したがって、上記のプログラムでこの機能を有効にするには、`topk_sols` を `best_energy_sols` に置き換えます: ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` このパラメータが設定された場合、ソルバーは見つかった最良エネルギーと等しいエネルギーの解のみを保持します。 結果として得られるプログラムは、すべて最良エネルギー値26を持つ以下の解を生成します: ```{include} ../../programFiles/markDown/solver/easy-solver-usage-program.md :start-after: :end-before: ``` :::