Optimizations#

Run and manage design optimizations in Ionworks Studio.

For usage examples and guides, see Managing optimizations on docs.ionworks.com.

Optimization client for managing design optimizations.

This module provides the OptimizationClient for running, monitoring, and managing battery design optimization jobs.

class ionworks.optimization.OptimizationClient(client)[source]#

Client for managing design optimizations.

Optimizations run parameter sweeps and objective-driven searches over parameterized battery models.

__init__(client)[source]#

Initialize the OptimizationClient.

Parameters:: client (Any) – The HTTP client instance for making API requests.
Return type:: None

run(data)[source]#

Submit a new optimization job.

Parameters:: data (dict[str, Any]) – The optimization configuration. See backend documentation for the full schema (varies by optimization type: design optimization, data fit optimization, etc.). Typically includes name, project_id, parameterized_model_id, and type-specific config.
Returns:: The newly created optimization record (includes job_id).
Return type:: Optimization

get(optimization_id)[source]#

Get an optimization resource by id.

Parameters:: optimization_id (str) – The ID of the optimization to retrieve.
Returns:: The optimization resource. Includes the lifecycle status (one of queued, running, succeeded, failed, canceled), result metrics, error, names, and counts.
Return type:: dict[str, Any]

list(project_id=None, limit=None, offset=None)[source]#

List optimizations with optional filtering.

Parameters:

project_id (str | None, optional) – Filter by project ID. If not provided, uses the project_id set on the Ionworks client (resolved from the IONWORKS_PROJECT_ID env var if not passed to the client).
limit (int | None, optional) – Maximum number of optimizations to return.
offset (int | None, optional) – Number of optimizations to skip for pagination.

Returns:

Dictionary with optimizations (job-free resources) and total keys.

Return type:

dict[str, Any]

update(optimization_id, data)[source]#

Update an optimization’s name and/or description.

Parameters:

optimization_id (str) – The ID of the optimization to update.
data (dict[str, Any]) – Dictionary containing the fields to update. Supports name and description.

Returns:

The updated optimization object.

Return type:

Optimization

cancel(optimization_id)[source]#

Cancel a running optimization.

Parameters:: optimization_id (str) – The ID of the optimization to cancel.
Returns:: The optimization resource with its updated status.
Return type:: dict[str, Any]

wait_for_completion(optimization_id, timeout=600, poll_interval=3, verbose=True, raise_on_failure=True)[source]#

Poll an optimization until it completes, fails, or times out.

Parameters:

optimization_id (str) – The ID of the optimization to wait for.
timeout (int, optional) – Maximum time to wait in seconds. Defaults to 600.
poll_interval (int, optional) – Time between polls in seconds. Defaults to 3.
verbose (bool, optional) – If True, print status updates. Defaults to True.
raise_on_failure (bool, optional) – If True, raise an error when the optimization fails. Defaults to True.

Returns:

The final optimization resource (including its status).

Return type:

dict[str, Any]

Raises: