Python API

ionworks-api Python パッケージは、最適化をプログラムから実行・管理するためのサブクライアントを提供します。インストールと認証についてはPython API クライアントページを参照してください。

最適化の実行

from ionworks import Ionworks

# Reads IONWORKS_API_KEY and IONWORKS_PROJECT_ID from the environment.
# project_id is auto-injected into payloads that don't specify it.
client = Ionworks()

optimization = client.optimization.run({
    "name": "Electrode thickness optimization",
    "parameterized_model_id": "your-parameterized-model-id",
    "protocol_experiment": {
        "protocol": "...",
        "name": "1C Discharge",
    },
    "design_parameters": {
        "Positive electrode thickness [m]": {
            "bounds": [50e-6, 100e-6],
        },
    },
    "objectives": {
        "Discharge capacity [A.h]": {"type": "maximize"},
    },
})

print(f"Optimization ID: {optimization.id}")
print(f"Job ID: {optimization.job_id}")

完了を待機する

result = client.optimization.wait_for_completion(
    "your-optimization-id",
    timeout=600,        # seconds (default: 600)
    poll_interval=3,    # seconds between polls (default: 3)
    verbose=True,       # print status updates (default: True)
)

print(result["status"])   # "succeeded", "failed", または "canceled"
print(result.get("metrics"))

wait_for_completion は最適化が終端状態（succeeded、failed、canceled）に達するまでポーリングし、最適化リソースを返します。デフォルトでは failed または canceled で IonworksError を送出します。例外の代わりに結果の dict を取得するには、raise_on_failure=False を設定してください。

最適化の一覧

# List optimizations in the default project
# (set IONWORKS_PROJECT_ID or pass project_id= to Ionworks(...))
optimizations = client.optimization.list()

# Override the project for a single call
optimizations = client.optimization.list(project_id="other-project-id")

# Paginate results
optimizations = client.optimization.list(limit=10, offset=0)

project_id を省略すると、client.optimization.run と .list は Ionworks クライアントに設定されたデフォルトプロジェクトを使用します。

最適化の取得

最適化リソースをフラットな dict として返します。ライフサイクル status は queued、running、succeeded、failed、canceled のいずれかです。結果の metrics と error は、最適化が終端状態に達したときに設定されます。

result = client.optimization.get("your-optimization-id")

print(result["id"], result["status"])
print(result.get("metrics"))   # status == "succeeded" のときに設定される
print(result.get("error"))     # status == "failed" のときに設定される

以前のレスポンスは optimization と job の 2 つのキーに分かれていました。現在はジョブは公開されておらず、status、metrics、error は最適化リソース自体に含まれます。result["job"]["status"] を読んでいるコードは result["status"] を読むように更新してください。

最適化の更新

optimization = client.optimization.update("your-optimization-id", {
    "name": "Electrode optimization v2",
    "description": "Updated bounds",
})

パラメータトレースの取得

設計最適化とデータフィッティングでは、オプティマイザの反復ごとの進行状況がジョブのメタデータに記録されます。これは Studio のパラメータプロットおよびコスト収束プロットで使われているのと同じデータです。client.job.get_parameter_trace を使うと、保存された反復ごとに 1 エントリ(古いものから順)の辞書のリストとして取得できます。

trace = client.job.get_parameter_trace(optimization.job_id)

for entry in trace:
    print(entry["inputs_unscaled"], entry["cost"], entry["best_cost"])

各エントリには次のキーが含まれます。

キー	説明
`cost`	この反復における目的関数値。
`best_cost`	この反復までに観測された最良(最小)の目的関数値。
`inputs`	この反復におけるスケール済みパラメータ値。
`inputs_unscaled`	スケールなし(物理単位)のパラメータ値。パラメータ名がキーになります。パラメータトレースにはこちらを使用してください。
`multistart_job_id`	該当する場合、このエントリが属するマルチスタートのインデックス。
`outputs` / `best_outputs`	この反復におけるモデル出力。設計目的の実行で存在します。

保存はスロットリングされており(おおむね 100 反復ごと、または 5 秒ごと)、トレースはオプティマイザのすべての評価ではなくサンプリングされた部分集合になります。実行時にライブ進行状況の更新が無効化されていた場合はリストが空になり、反復ごとのウォールクロック時間は含まれません。

最適化のキャンセル

キュー中または実行中の最適化をキャンセルし、更新された最適化リソースを返します。

result = client.optimization.cancel("your-optimization-id")
print(result["status"])   # "canceled"

どのリソースの ID も、Ionworks Studio Web アプリから確認できます。リソースの詳細ページに移動すると、URL に ID が表示されます。

はじめに

基本コンセプト

データ

モデル構築

パイプライン

シミュレーション

最適化

最適化の実行

完了を待機する

最適化の一覧

最適化の取得

最適化の更新

パラメータトレースの取得

最適化のキャンセル

​最適化の実行

​完了を待機する

​最適化の一覧

​最適化の取得

​最適化の更新

​パラメータトレースの取得

​最適化のキャンセル

最適化の実行

完了を待機する

最適化の一覧

最適化の取得

最適化の更新

パラメータトレースの取得

最適化のキャンセル