> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python API

> ionworks-api Python クライアントで、最適化をプログラムから実行、監視、一覧、更新、キャンセルします

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

## 最適化の実行

```python theme={null}
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}")
```

## 完了を待機する

```python theme={null}
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`](/ja/api-client#error-handling) を送出します。例外の代わりに結果の dict を取得するには、`raise_on_failure=False` を設定してください。

## 最適化の一覧

```python theme={null}
# 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)
```

<Note>
  `project_id` を省略すると、`client.optimization.run` と `.list` は Ionworks クライアントに設定された[デフォルトプロジェクト](/ja/api-client#default-project)を使用します。
</Note>

## 最適化の取得

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

```python theme={null}
result = client.optimization.get("your-optimization-id")

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

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

## 最適化の更新

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

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

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

```python theme={null}
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` | この反復におけるモデル出力。設計目的の実行で存在します。                                |

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

## 最適化のキャンセル

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

```python theme={null}
result = client.optimization.cancel("your-optimization-id")
print(result["status"])   # "canceled"
```

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