ionworks-api Python パッケージは、Ionworks Studio でリソースの管理、シミュレーションの実行、パイプラインの送信、データのアップロードを行うためのプログラマブルなインターフェースを提供します。
コーディングエージェントから Ionworks を操作しますか？Ionworks エージェントツールキット は、Claude Code、Codex、その他のエージェント向けに SDK 対応のスキルを提供します。このページのセットアップを代行する install スキルも含まれています。 インストール
リポジトリからパッケージをインストールします:
Ionworks のアカウント設定から API キーを取得し、設定します:
from ionworks import Ionworks
# Option 1: Environment variable (recommended)
# Set IONWORKS_API_KEY in your environment or .env file
client = Ionworks()
# Option 2: Direct configuration
client = Ionworks(api_key="your_key")
# Option 3: Custom timeout and retry settings
client = Ionworks(
timeout=30, # Request timeout in seconds (default: 10)
max_retries=3 # Max retries on failure (default: 5)
)
API キーをバージョン管理にコミットしないでください。資格情報の管理には環境変数または .env ファイルを使用してください。
API キーを検証する
client.whoami() を使用して、設定された API キーがどのユーザーと組織に解決されるかを確認します。これは 401/403 エラーをデバッグしたり、間違った組織のデータが表示される理由を確認したりするための推奨方法です。
me = client.whoami()
print(me["email"], me["authorized_organization"])
# [email protected] {'id': 'org_abc123', 'name': 'Acme Battery'}
authorized_organization — このリクエストが 認可されている 組織。SDK 呼び出しの場合、これは設定された API キーが発行された組織であり、クライアントが行うすべてのリクエストの権限チェックに使用される唯一の情報源です。組織コンテキストを解決できない場合は None になります。organizations — ユーザーの完全なメンバーシップリスト（所属するすべての組織）。これは別の情報であり、権限チェックには 使用されません。
authorized_organization の id または name が期待と異なる場合は、誤ったキーが使用されています。アカウント設定から正しい組織用に再生成してください。
デフォルトプロジェクト
ほとんどのサブクライアント（pipelines、studies、optimizations、cell specifications、…）はプロジェクト内で動作します。すべての呼び出しに project_id を渡す代わりに、クライアントに一度デフォルトを設定できます。project_id 引数を取るサブクライアントメソッドは、明示的に渡されない場合このデフォルトにフォールバックします。
クライアントはデフォルトを次の順序で解決します:
Ionworks(...) に渡される project_id= 引数。IONWORKS_PROJECT_ID 環境変数。- それ以外の場合、デフォルトは設定されません。プロジェクトを必要とするメソッドは、呼び出し時に
project_id が渡されない限り ValueError を発生させます。
# Option 1: Environment variable (recommended)
# Set IONWORKS_PROJECT_ID in your environment or .env file
client = Ionworks()
# Option 2: Pass to the client constructor
client = Ionworks(project_id="your-project-id")
# Override on a per-call basis when needed
client.study.list(project_id="other-project-id")
https://app.ionworks.com/dashboard/projects/<project-id>/settings。
PROJECT_ID 環境変数は後方互換のため引き続き受け入れられますが、非推奨です。代わりに IONWORKS_PROJECT_ID を設定してください。古い名前を使用すると DeprecationWarning が発生し、将来のリリースで動作しなくなります。
環境変数
クライアントは python-dotenv を介して .env ファイルを自動的に読み込みます。
| 変数 | 必須 | デフォルト | 説明 |
|---|
IONWORKS_API_KEY | はい | — | アカウント設定からの API キー。 |
IONWORKS_API_URL | いいえ | https://api.ionworks.com | API ベース URL。 |
IONWORKS_PROJECT_ID | プロジェクトスコープの呼び出しでは必須 | — | サブクライアントメソッドのデフォルトプロジェクト ID。 |
IONWORKS_DATAFRAME_BACKEND | いいえ | polars | DataFrame バックエンド: polars または pandas。 |
DataFrame バックエンド
デフォルトでは、クライアントはデータを polars DataFrame として返します。ワークフローで必要な場合は pandas に切り替えられます。
# Option 1: Set via constructor
client = Ionworks(dataframe_backend="pandas")
# Option 2: Set via environment variable
# IONWORKS_DATAFRAME_BACKEND=pandas
# Option 3: Set at runtime
from ionworks import set_dataframe_backend, get_dataframe_backend
set_dataframe_backend("pandas")
print(get_dataframe_backend()) # "pandas"
タイムアウトとリトライの挙動
クライアントは接続エラー、タイムアウト、サーバーエラー（5xx）で失敗したリクエストを自動的にリトライします。デフォルトでは:
- リクエストは 10 秒 でタイムアウト
- 失敗したリクエストは指数バックオフで最大 5 回 リトライ
- リトライされるのは GET と DELETE のみ。重複操作を防ぐため、POST と PATCH リクエストはリトライされません。
これらの設定はカスタマイズできます:
# Longer timeout for large uploads
client = Ionworks(timeout=60)
# Disable retries
client = Ionworks(max_retries=0)
サブクライアント
Ionworks クライアントはドメイン固有のサブクライアントを公開しています:
| サブクライアント | アクセス | ドキュメント |
|---|
| Projects | client.project | Core Concepts API |
| Models | client.model | Build API |
| Parameterized models | client.parameterized_model | Build API |
| Studies | client.study | Simulate API |
| Protocols | client.protocol | Simulate API |
| Simulations | client.simulation | Simulate API |
| Pipelines | client.pipeline | Simulate API |
| Simple pipelines | client.simple_pipeline | Simulate API |
| Optimizations | client.optimization | Optimize API |
| Cell specifications | client.cell_spec | データのアップロード |
| Cell instances | client.cell_instance | データのアップロード |
| Cell measurements | client.cell_measurement | 測定 |
| Jobs | client.job | ジョブのキャンセル |
ジョブのキャンセル
Python API を使用して、実行中のジョブ（シミュレーション、パイプライン、最適化）をキャンセルできます。各ジョブには一意の ID があり、それを使用してキャンセルできます。
# Cancel a job by ID
client.job.cancel(job_id="job_abc123")
