OMMX Adapterを実装する

OMMX Adapterを実装する#

このページは、独自のBackendをOMMXへ接続するAdapter実装者向けの入口です。まず、Adapter利用者にも共通する次のモデルを確認してください。

  1. InstanceClassとAdapterの入力条件

  2. Instance PreparationとPreparationPolicy

  3. Removed constraintsと実行可能性

実装時に参照するAPI#

Instanceが保持する変数の一覧は、そのままBackend変数の一覧にはなりません。変換前の表現や評価のために保持している変数もあります。この区別が初見なら、Instanceの基本モデルを先に確認してください。

Adapterが実装する契約#

  • INPUT_CLASSを必ず宣言する。これはAdapterがPreparationなしで直接受け取るInstanceの集合であり、applicabilityの完全な条件でもあります。

  • check_applicability()とrequire_applicable()はINPUT_CLASS membershipだけを報告・強制する。converterやBackendが返すerrorを追加のapplicability条件やAdapterNotApplicableErrorとして扱いません。

  • Solver Adapterはsolve_without_preparation()、Sampler Adapterはsample_without_preparation()を実装する。これらは入力をPreparationせず、non-memberを拒否する厳格な経路です。

  • 通常のsolve()とsample()は入力のcopyへrecommended_preparation_policy()を適用してから厳格な経路を呼びます。Backend固有の引数のためにこれらをoverrideする場合も、このcopy、Preparation、strict methodという順序を保ちます。

  • Adapter constructorもexact inputだけを受け取り、Preparationしません。

  • OMMX由来の独立変数としてBackendへencodeするのは、used_decision_variablesに限定する。Backend独自の補助変数を追加することはできます。OMMX IDとBackend変数の対応を保持し、すべてのused IDをdecodeしてください。fixed、dependent、irrelevant、removed-constraint-only、named-function-only、output_objective-onlyの変数は独立したBackend入力ではありません。

  • decodeしたstateまたはsamplesは、Backend入力の作成に使った同じInstanceで評価する。encodeからBackend実行、decode完了まで、そのInstanceを変更しない契約を設けてください。そのInstanceがdependent variableの復元とremoved constraintの評価を所有します。呼び出し側が元のInstanceを変更しながら使う必要がある場合に限り、Adapter内部でcopyを保持する方法を検討します。

Backendが報告した最適性をSolutionへ付与するときは、評価に使ったInstanceのmap_active_optimality()を通してください。変換後の問題の最適性と、返す目的値に対する最適性の区別はRemoved constraintsと実行可能性を参照してください。

参照実装#

以下の参照実装は、本ページで確認した基準revision dc533e65be3520137f202538023ab18cbbe631ce に固定しています。公開済みSDKに対してAdapterを実装する場合は、対象releaseのソースコードとAPI契約を確認してください。

Solver Adapterは PySCIPOpt Adapterの実装 を参照してください。INPUT_CLASS、applicability check、used decision variablesのencode/decode、同じInstanceによる評価までをまとめて確認できます。この実装はconstructorへ渡されたInstanceを参照として保持するため、呼び出し側がencodeからdecode完了まで変更しないことを前提にします。

Sampler Adapterが必要な場合は、OpenJij Adapterの実装とサンプルのdecode処理も参照してください。

目次