Simulations

Run single simulations or sweeps with parameterized models, configure protocols and design parameters, and visualize results

A Simulation is the result of running a Parameterized Model with a specific set of inputs and experimental conditions. Simulations are the core of Ionworks, allowing you to explore the performance of your Cell Specification beyond what you have measured experimentally.

Simulations are always created and viewed within the context of a Study.

Running a New Simulation

You can run a new simulation or a sweep of simulations from within a study. The process is broken down into a simple, step-by-step workflow.

1. Select Cell Specification: First, choose the cell you want to simulate.
2. Select Parameterized Model: Next, select a parameterized model that has been created for your chosen cell. Parameterized models combine a Model (mathematical framework) with specific parameters.
3. Define Experiment Protocol: Provide the protocol for your experiment using one of these methods:
   • Start from an existing protocol — select a saved protocol from the searchable dropdown
   • Paste or type — enter protocol text directly in the editor (supports UCP, Maccor, Neware, Biologic, and other cycler formats)
   • Upload a file — upload a protocol file from your cycler software
   • Interactive Builder — use the visual protocol builder to construct a protocol step by step
4. Configure Simulation Parameters: Set initial conditions (SOC, temperature) and any protocol input parameters. If the protocol uses input["..."] expressions, these are automatically detected and shown as configurable fields.
5. Configure Design Parameters (Optional): You can also vary the parameterized model’s parameters to explore their effect on performance (e.g., “Positive electrode thickness [m]”). See Design Parameters below for details.

Running Sweeps: For any experiment or design parameter, you can enter multiple values separated by commas (e.g., 1, 2, 5). Ionworks Studio will automatically create and run a simulation for every possible combination of the parameters you’ve entered. The UI will show you the total number of simulations that will be run.

To save you time and computational resources, Ionworks Studio automatically checks if an identical simulation has already been run. Existing results are reused, and new results are saved for future use.

Design Parameters

Design parameters allow you to override specific values in your battery model to explore how changes to the cell’s physical and electrochemical properties affect performance. By default, simulations use the parameter values defined in your model. Design parameters let you modify these values without changing the model itself.

Custom variables defined on the model are also available in simulation output. See Custom Variables for details.

The available parameters for design overrides depend on your selected model. Only scalar parameters that are actually used in the model can be chosen as design parameters—parameters defined as functions or interpolating tables are not eligible.

How to Use Design Parameters

When setting up a simulation, you’ll see a “Design Parameters” section where you can:

1. Add Parameters - Click “Add Design Parameters” to start customizing values
2. Select Which Parameters to Vary - Choose from the list of parameters available in your model (geometry, electrode properties, separator characteristics, etc.)
3. Set Values - Enter the value(s) you want to use for each parameter

Parameter Input Methods

For each design parameter you add, you can choose how to specify values:

Discrete

Enter specific values separated by commas. This is the most direct method when you know exactly which values you want to test.

Example:

• Enter 50e-6, 75e-6, 100e-6 for Negative electrode thickness [m]
• This will test exactly these three thicknesses

Range

Specify a minimum value, maximum value, and how many evenly-spaced points to generate between them. Useful for exploring a continuous range.

Example:

• Min: 50e-6, Max: 100e-6, Count: 5
• This automatically generates: 50e-6, 62.5e-6, 75e-6, 87.5e-6, 100e-6

Normal (Statistical)

Specify a mean (center), standard deviation (spread), and number of points. Points are distributed around the mean following a normal distribution pattern (±2 standard deviations).

Example:

• Mean: 75e-6, Std: 10e-6, Count: 5
• This generates values clustered around 75 microns with more samples near the center

Combining Parameters

When you add multiple design parameters, simulations will run for combinations of all values. For example:

• Negative electrode thickness: 50e-6, 75e-6, 100e-6 (3 values)
• Negative particle radius: 3e-6, 5e-6 (2 values)
• Total simulations: 6 (3 × 2)

Advanced: Sampling Methods

For large parameter sweeps, you can choose different sampling methods instead of testing every combination:

• Grid (default) - Tests all combinations of the values you provide
• Latin Hypercube Sampling (LHS) - Efficiently samples the parameter space with fewer simulations
• Sobol - Low-discrepancy sequence for uniform coverage
• Random - Random sampling within the specified ranges

These methods are particularly useful when sweeping many parameters to avoid an explosion in the number of simulations.

What Happens Without Design Parameters

If you don’t add any design parameters, the simulation will use the default values from your selected model. This is perfectly fine for most use cases - design parameters are optional and only needed when you want to explore variations from your baseline model.

Visualizing and Comparing Results

Once your simulations are complete, they are added to the study’s results page, which provides powerful tools for analysis.

Simulation results are organized by “experiment type” so that you can compare like-for-like results within a single experiment type - for example, investigating the effect of C-rate on capacity in a constant current discharge.

You can switch between two views:

Data View

This is a table containing the results of all simulations within the study. It includes the inputs for each simulation and the key summary metrics that were calculated. You can sort any column by clicking its header — click once for ascending order, click again for descending, and a third time to clear the sort. Use sorting and filtering together to find specific runs quickly.

When you run a simulation using a built-in experiment template, metrics like capacity, energy, resistance, and electrode potentials are automatically computed and included in the results. See the experiment templates reference for the full list of metrics each template provides.

Design parameter columns are visible by default so you can quickly compare how different parameter values affect results. Experiment parameter and metric columns are hidden by default but can be toggled on from the column visibility menu.

Visualization View

This is a customizable dashboard where you can create plots to visualize and compare your simulation results.

• Add Plots: Click the “Add Plot” button to configure and add a new visualization to your dashboard. You can choose between “time series” (whole variable trace vs time or capacity) and “metrics” (single values e.g. “Capacity” vs “C-rate”).
• Custom Layout: You can add multiple plots to your dashboard to compare different simulations or look at different variables. The plots can be dragged, dropped, and resized to create the perfect layout for your analysis.
• Interactivity: The plots are fully interactive, allowing you to zoom, pan, and hover over data points to get more detail. Any new simulations you run within the same study will automatically be added to the plots.

This flexible visualization tool allows you to build a comprehensive view of your simulation results, tailored to your specific analysis needs.

Canceling simulations

You can cancel a running simulation if it is still in the Pending or Processing state.

1. Open the simulation from the Data View
2. Click the Cancel button in the top-right area of the detail page
3. Confirm the cancellation in the dialog

Once confirmed, the simulation and its underlying job are moved to a Canceled status. Any child jobs associated with the simulation are also canceled.

Canceling a simulation cannot be undone. Any work already completed is lost. You can rerun the simulation to get results.

You can also cancel multiple simulations at once from the simulation list. Select the simulations you want to cancel, then use the Cancel bulk action. Simulations that have already finished are automatically skipped.

Rerunning simulations

You can rerun one or more simulations directly from the Data View. Select the simulations you want to rerun, then use the rerun action. When you rerun a simulation, all of its original configuration is preserved — including experiment parameters, design parameters, and the parameterized model — so the new run reproduces the same conditions as the original.

This is useful when:

• A simulation failed due to a transient issue and you want to retry it
• You want to force a fresh run to bypass cached results
• A simulation was canceled and you want to run it again

The rerun action uses force rerun by default, which means a new simulation job is always submitted even if matching cached results exist.

Troubleshooting

All steps skipped — no data generated

When a simulation completes but every step in the protocol was skipped, you’ll see a warning:

All steps skipped — no data generated Every step ended immediately because its termination condition was already satisfied before the simulation began.

This happens when the battery’s initial state already meets the termination condition for every step in the protocol. For example, trying to discharge a battery that is already fully depleted, or charging one that is already at 100% SOC.

Common causes and fixes:

Cause	Fix
Discharging a battery that is already depleted	Increase the Initial SOC value in the simulation parameters
Charging a battery that is already fully charged	Decrease the Initial SOC value
C-rate or current too high for the cell — the instantaneous voltage drop at t=0 immediately trips the voltage cutoff, so the termination condition is already met before the step starts	Lower the C-rate or current to a realistic value for the cell’s capacity (e.g. a 50 A discharge is unrealistic for a 2 mAh coin cell)
Voltage cutoff already reached at initial state	Adjust the cutoff voltage or initial conditions so the simulation has room to run

If you’re unsure what went wrong, check the experiment protocol panel on the results page to review the parsed steps and their termination conditions.

Next steps

• Learn about Protocols including built-in experiment templates
• Explore Optimization to find optimal parameter values automatically