> ## 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/build/models)と[パラメータ化モデル](/ja/build/parameterized-models)をプログラムから管理するためのサブクライアントを提供します。インストールと認証については[Python API クライアント](/ja/api-client)ページを参照してください。

## モデル

`client.model` を使用してモデルの作成、一覧、更新、削除を行います。

### モデルの一覧

```python theme={null}
from ionworks import Ionworks

client = Ionworks()

# List all models
models = client.model.list()
for model in models:
    print(f"{model.name} ({model.id})")

# Filter by name
models = client.model.list(name="SPM")

# Paginate results
models = client.model.list(limit=10, offset=0)
```

サポートされるフィルター: `name`、`name_exact`、`created_by_email`、`created_after`、`created_before`、`updated_after`、`updated_before`、`order_by`、`order`。

### モデルの取得

```python theme={null}
model = client.model.get("your-model-id")
print(model.config)
# {"type": "SPMe"}
```

`config` フィールド（例: `{"type": "SPMe"}`）は `get` レスポンスに含まれます。`create` のレスポンスでは `None` になる場合があるため、必要な場合は `get` で再取得してください。

### モデルの作成

```python theme={null}
model = client.model.create({
    "name": "Custom SPM",
    "config": {"type": "SPM"},
    "description": "Single Particle Model with custom variables",
})
```

`config` の `type` は PyBaMM のモデルクラス名です（`SPM`、`SPMe`、`DFN`）。

<Tip>
  カスタム変数が必要な場合のみモデルを作成します。標準的なモデルであれば、パラメータ化モデルを作成する際に組み込みのシステムモデルを名前で参照できます（例: `"SPMe (Full Cell)"`）。モデルの作成は不要です。[モデル](/build/models) を参照してください。
</Tip>

### モデルの更新

```python theme={null}
model = client.model.update("your-model-id", {
    "name": "Custom SPM v2",
    "description": "Updated description",
})
```

### カスタム変数の追加

```python theme={null}
model = client.model.add_custom_variable("your-model-id", {
    "name": "Total energy [W.h]",
    "expression": "Voltage [V] * Current [A] * Time [s] / 3600",
})
```

### モデルの削除

```python theme={null}
client.model.delete("your-model-id")
```

### Ionworks モデルを PyBaMM モデルとしてダウンロード

`client.model.download()` を使うと、[Ionworks モデル](/ja/build/models#ionworks-models)
(`ECM`、`LumpedSPMR`、`LumpedSPMeR`、MSMR モデル、`GITTModel` など) をすぐに使える
PyBaMM モデルとして取得できます。サーバー側でライセンス付き `ionworkspipeline`
パッケージからモデルを構築し、シリアライズされた形で返すため、ローカルでは
`pybamm` のみインストールされていれば実行可能です（`ionworkspipeline` の
ライセンスは不要です）。

```python theme={null}
import pybamm

model = client.model.download("ECM")
# model は pybamm.BaseModel — そのまま pybamm.Simulation に渡せます
sim = pybamm.Simulation(model)
```

モデルコンストラクタのオプションは `options=` で指定でき、`path=` で
シリアライズ後の JSON をディスクに保存して後で再読み込みしたり、
[カスタムモデル](/ja/build/models#creating-a-model)として再アップロードしたりできます:

```python theme={null}
model = client.model.download(
    "LumpedSPMR",
    options={"thermal": "lumped", "surface temperature": "ambient"},
    path="lumped_spmr.json",
)
```

利用可能なモデル名は `client.pybamm_models()` が返す
`"ionworks_models"` 配下のエントリと一致します。標準の PyBaMM モデル
（`SPM`、`SPMe`、`DFN` など）はこのエンドポイントでは提供されません —
直接 `pybamm` でインスタンス化してください。

<Note>
  シリアライズはモデルの数学的構造（rhs、代数方程式、変数、イベント、
  初期条件）を保持しますが、`set_initial_state` などの Python ヘルパー
  メソッドや classmethod は保持しません。

  `path` を指定した場合、ファイル内に `Infinity`/`NaN` トークンが含まれる
  ことがあります（PyBaMM は無限大の境界やイベントしきい値を使用するため）。
  Python の `json` および `Serialise.load_custom_model` はこれを問題なく
  読み込めますが、厳格なパーサ（`JSON.parse`、`jq` など）は拒否します。
</Note>

シリアライズ済みドキュメントだけが必要な場合（保存・再アップロード・
中身の検査など）には、`client.model.serialize()` を使うと PyBaMM を
経由せずに dict を取得できます:

```python theme={null}
model_json = client.model.serialize("GITTModel")
```

#### ジオメトリとメッシュは保持されます

ダウンロードされたモデルは、元の Ionworks モデルが構築されたときの
`geometry`、`var_pts`、`spatial_methods`、`submesh_types` を
シリアライズした形で保持しています。これをカスタムモデルとして
再アップロードした場合 — あるいは `parse_model` を経由するパイプラインに
渡した場合 — これらの値はモデルの `default_geometry`、`default_var_pts`、
`default_spatial_methods`、`default_submesh_types` として復元されるため、
下流の `pybamm.Simulation` が空のデフォルトにフォールバックすることなく
正しいメッシュで離散化を行います。ジオメトリを手動で再構築する必要は
ありません。

## パラメータ化モデル

`client.parameterized_model` を使用してパラメータ化モデルの作成、一覧、更新を行います。パラメータ化モデルは[セル仕様](/ja/core-concepts/cells)にスコープされます。

### パラメータ化モデルの一覧

パラメータ化モデルは、単一のセル仕様にスコープして一覧表示することも、プロジェクト内のすべてのセル仕様にまたがって一覧表示することもできます。

```python theme={null}
# List parameterized models for a single cell specification
param_models = client.parameterized_model.list_by_cell_specification("your-cell-spec-id")
for pm in param_models:
    print(f"{pm.name} (ID: {pm.id})")

# Paginate results
param_models = client.parameterized_model.list_by_cell_specification(
    "your-cell-spec-id", limit=10, offset=0
)
```

プロジェクト内の任意のセル仕様に紐づくすべてのパラメータ化モデルを一覧表示するには、`list_by_project` を使用します。`project_id` を省略した場合、クライアントに設定された `project_id` がデフォルトとして使用されます（[API クライアント](/ja/api-client)を参照）。

```python theme={null}
# All parameterized models in the client's default project
param_models = client.parameterized_model.list_by_project()

# Explicit project, paginated
param_models = client.parameterized_model.list_by_project(
    project_id="your-project-id", limit=100, offset=0
)

# Narrow a project-scoped query to one cell specification
param_models = client.parameterized_model.list_by_project(
    project_id="your-project-id", cell_spec_id="your-cell-spec-id"
)
```

<Note>
  `list_by_project` は最大 1000 件までの `limit` 値を受け付けるため、UI セレクターの初期化やモデルの一括処理時に、プロジェクト内のすべてのモデルを 1 回のリクエストで読み込むことができます。
</Note>

### パラメータ化モデルの取得

```python theme={null}
param_model = client.parameterized_model.get("your-parameterized-model-id")
```

### パラメータ化モデルの作成

```python theme={null}
param_model = client.parameterized_model.create("your-cell-spec-id", {
    "name": "NMC622 Fitted Parameters",
    "model_id": "your-model-id",
    "description": "Parameters from 1C discharge fitting",
    "parameters": {
        "Negative electrode diffusivity [m2.s-1]": 3.3e-14,
    },
})
```

### パラメータ化モデルの作成または取得

セットアップスクリプトを安全に再実行可能にするには、`create_or_get` を使用します。同じセル仕様に対して同じ名前のパラメータ化モデルが既に存在する場合、`409 Conflict` エラーを発生させる代わりに既存のものを返します。

```python theme={null}
param_model = client.parameterized_model.create_or_get("your-cell-spec-id", {
    "name": "NMC622 Fitted Parameters",
    "model_id": "your-model-id",
    "parameters": {
        "Negative electrode diffusivity [m2.s-1]": 3.3e-14,
    },
})
```

これは、`client.cell_spec`、`client.cell_instance`、`client.cell_measurement` で既に利用可能な `create_or_get` の動作を踏襲しています。セルデータに対する同じパターンについては、[べき等なアップロード](/ja/data/uploading#create_or_get-による冪等なアップロード) を参照してください。

### パラメータ化モデルの更新

```python theme={null}
param_model = client.parameterized_model.update(
    "your-cell-spec-id",
    "your-parameterized-model-id",
    {"name": "NMC622 Fitted Parameters v2"},
)
```

### パラメータ値の取得

すべてのパラメータ値を辞書として取得します。データフィッティングや最適化ワークフローのベースラインパラメータとして便利です。

```python theme={null}
params = client.parameterized_model.get_parameter_values("your-parameterized-model-id")
print(params)
# {"Negative electrode diffusivity [m2.s-1]": 3.3e-14, ...}
```

### 変数名の取得

パラメータ化モデルから利用可能なスカラー変数名を一覧表示します。

```python theme={null}
variables = client.parameterized_model.get_variable_names("your-parameterized-model-id")
print(variables)
# ["Terminal voltage [V]", "Current [A]", ...]
```

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

## ECM パラメータ化

`client.ecm` を使用して、サイクリングデータに等価回路モデル (R0 + N 個の RC ペア、および任意の OCV) をフィットし、その結果を[パラメータ化モデル](/ja/build/parameterized-models)として永続化します。認証済みのフィットはバックグラウンドジョブとして実行されます — `fit_from_measurements` と `fit_from_file` はすぐに `EcmFitJob` ハンドルを返し、`wait_for_completion` がワーカーの完了までブロックします (通常 10–60 秒)。

`ocv_soc_curve` を使った容量同時フィット、セグメントごとの SOC シード、ノット解像度のチューニングを含む完全なガイドは [ECM パラメータ化](/ja/build/ecm-parameterization#python-からフィットする)を参照してください。

### 保存された測定からフィットする

```python theme={null}
from ionworks import Ionworks

client = Ionworks()

fit_job = client.ecm.fit_from_measurements({
    "measurements": [
        {"id": "meas-id-1"},
        {"id": "meas-id-2", "start_step": 5, "end_step": 50, "initial_soc": 0.95},
    ],
    "ecm_options": {"num_rcs": 2, "fit_ocv": True},
})

result = client.ecm.wait_for_completion(fit_job, timeout=300)
print(f"RMSE: {result.rmse_mV:.2f} mV")
```

### ローカルファイルからフィットする

```python theme={null}
fit_job = client.ecm.fit_from_file("data/pulse_test.csv", num_rcs=2, capacity=4.85)
result = client.ecm.wait_for_completion(fit_job)
```

`fit_from_file` は CSV、parquet、`ionworksdata` が検出できるすべてのサイクラー形式を受け付けます。フィット前にファイルをプレビューするには `client.ecm.detect_and_read(file)` を使用します。

### フィット結果をパラメータ化モデルとして保存

```python theme={null}
saved = client.ecm.save_to_project(
    name="ECM 2RC — pulse test",
    cell_spec_id="cell-spec-id",
    fit_results=result,
)

print(saved.parameterized_model_id)
```

返された `parameterized_model_id` は `client.simulation.protocol(...)` で `parameterized_model` として使用できます。

### 認証なしで組み込みの例をフィットする

```python theme={null}
examples = client.ecm.list_examples()
result = client.ecm.fit_from_example(examples[0]["id"], num_rcs=2)
```

デモエンドポイントはレート制限付き (60/分) で同期です。RC ペアパラメータは、組織で ECM 結果アクセスが有効になっている認証済み呼び出し元にのみ含まれます。