OMMX Python SDK 3.0.x

OMMX Python SDK 3.0.x#

注釈

Python SDK 3.0.0にはAPIの破壊的な変更が含まれます。マイグレーションガイドを Python SDK v2 to v3 Migration Guide にまとめてあります。

Unreleased#

Indicator Constraintのサポート (#789, #790, #795, #796)#

IndicatorConstraint がOMMXの第一級機能として追加されました。Indicator Constraintは条件付き制約を表現します。ユーザーが定義したバイナリ変数 z に対して、z = 1 の時のみ制約 f(x) <= 0（または f(x) = 0）が課されます。z = 0 の時、制約は無条件に満たされます。

Constraint.with_indicator() を使って既存の制約から IndicatorConstraint を作成できます。PySCIPOpt AdapterはこれをSCIPの addConsIndicator に変換します:

from ommx.v1 import DecisionVariable, Instance
from ommx_pyscipopt_adapter import OMMXPySCIPOptAdapter

b = DecisionVariable.binary(0)
x = DecisionVariable.continuous(1, lower=0, upper=10)

# b = 1 → x <= 5
ic = (x <= 5).with_indicator(b)

instance = Instance.from_components(
    decision_variables=[b, x],
    objective=x,
    constraints=[b >= 1],  # b = 1 を強制
    indicator_constraints=[ic],
    sense=Instance.MAXIMIZE,
)

solution = OMMXPySCIPOptAdapter.solve(instance)
assert abs(solution.objective - 5.0) < 1e-6

評価結果#

求解後、Solution と SampleSet でindicator constraint用のDataFrameを取得できます:

indicator_active カラムにより、「インジケーターがOFFだった（制約は自明に満たされた）」と「インジケーターがONで制約が満たされた」を区別できます。なお、indicator constraintでは双対変数は定義が難しいため、dual variableは含まれません。

緩和と復元#

Indicator constraintは通常の制約と同様にrelax/restoreワークフローをサポートします:

removed_reasons_df の分離#

この変更に伴い、removed_reason は constraints_df のカラムではなくなりました。代わりに removed_reasons_df が Solution と SampleSet の両方で別テーブルとして提供され、constraints_df とJOINして使用できます:

# 通常の制約
df = solution.constraints_df.join(solution.removed_reasons_df)

# Indicator constraint
df = solution.indicator_constraints_df.join(solution.indicator_removed_reasons_df)

Adapter Capabilityモデル (#790, #814)#

IndicatorConstraint のような特殊な制約型が追加されソルバー毎に対応・未対応が分かれるため、Adapter Capabilityモデルが導入されました。Adapterは ADDITIONAL_CAPABILITIES でサポートするCapabilityを宣言し、Instance.reduce_capabilities() がその集合に含まれない制約タイプを通常の制約へ変換（indicator/SOS1 は Big-M、one-hot は線形等式）してから solver に渡します。Instance が現在保持している非標準制約タイプは Instance.required_capabilities で確認できます。

from ommx.v1 import AdditionalCapability
from ommx.adapter import SolverAdapter

class MySolverAdapter(SolverAdapter):
    ADDITIONAL_CAPABILITIES = frozenset({AdditionalCapability.Indicator})

現在、PySCIPOpt Adapter が Indicator 制約と SOS1 のサポートを宣言しています。各OMMX AdapterはPython SDK 3.0.0に対応する際に変更が必要になります。 具体的には、未サポートの Capability を自動変換するために super().__init__(instance) を呼び出す必要があります。

3.0.0 Alpha 1#

Static Badge

詳細な変更点は上のGitHub Releaseをご覧ください。以下に主な変更点をまとめます。これはプレリリースバージョンです。APIは最終的なリリースまでに変更される可能性があります。

ommx.v1 および ommx.artifact 型の完全なRust再エクスポート (#770, #771, #774, #775, #782)#

Python SDK 3.0.0は完全にRust/PyO3ベースになります。 2.0.0ではコア実装がRustで書き直されましたが、互換性のためにPythonラッパークラスが残されていました。3.0.0ではそれらのPythonラッパーを完全に削除し、ommx.v1 およｂ ommx.artifact の全型がRustからの直接再エクスポートとなり、protobuf Pythonランタイム依存も排除されます。また旧来PyO3実装へのアクセスを提供していた .raw 属性も廃止されました。

Sphinxへの移行、ReadTheDocsでのホスティング開始 (#780, #785)#

v2ではSphinxベースのAPI ReferenceとJupyter BookベースのドキュメントがそれぞれGitHub Pagesでホストされていましたが、v3ではSphinxに完全移行し、ReadTheDocsでホスティングを開始しました。GitHub Pagesは2.5.1の段階のドキュメントが引き続きホストされますが、今後の更新はReadTheDocsのみで行われます。

目次