Python API

Run, monitor, list, update, and cancel optimizations programmatically with the ionworks-api Python client

The ionworks-api Python package provides a sub-client for running and managing optimizations programmatically. For installation and authentication, see the Python API client page.

Running an optimization

from ionworks import Ionworks

client = Ionworks()

optimization = client.optimization.run({
    "project_id": "your-project-id",
    "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}")

Waiting for completion

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)
)

Set raise_on_failure=False to get the result dict instead of raising an exception when an optimization fails.

Listing optimizations

# List all optimizations
optimizations = client.optimization.list()

# Filter by project
optimizations = client.optimization.list(project_id="your-project-id")

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

Getting an optimization

Returns the optimization record along with its associated job status.

result = client.optimization.get("your-optimization-id")
print(result["optimization"])
print(result["job"])

Updating an optimization

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

Canceling an optimization

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

You can find the ID for any resource from the Ionworks Studio web app. The ID is displayed in the URL when you navigate to a resource’s detail page.