Protocol Builder

Visually create UCP cycling protocols with steps, safety limits, and live YAML preview—no hand-written YAML required

The Protocol Builder is a visual editor for creating Universal Cycler Protocol (UCP) files directly in Ionworks Studio. You can add and configure steps, set global parameters and safety limits, and preview the generated YAML in real time — all without writing YAML by hand.

Getting started

Open the Protocol Builder from the Protocol Builder page in Studio. The editor has two panels:

• Left panel — step editor with global configuration and the step list
• Right panel — live YAML preview that updates as you make changes

Global configuration

The collapsible Global Settings section at the top of the editor lets you configure protocol-wide defaults:

• Initial state — set the starting state of the cell as either an SOC percentage (0–100%) or a voltage
• Initial temperature — ambient temperature in °C
• Resolution — time, voltage, and current resolution for the simulation output

Safety limits

You can define global safety limits that terminate any step if breached:

Limit	Description
Voltage min / max	Lower and upper voltage bounds (V)
Temperature min / max	Lower and upper temperature bounds (°C)
Charge current max	Maximum charge current (A)
Discharge current max	Maximum discharge current (A)

These correspond to the safety_limits section in the UCP format.

Adding steps

Click Add Step to open a categorized menu of available step types:

Common steps:

• Charge — constant current, voltage, power, or C-rate charge
• Discharge — constant current, voltage, power, or C-rate discharge
• Rest — open-circuit rest period
• Drive — drive cycle from a CSV file

Advanced steps:

• EIS — electrochemical impedance spectroscopy sweep
• Waveform — custom waveform step
• Ambient temperature — change the ambient temperature mid-protocol
• Step block — group steps into a named, repeatable block

Control flow:

• Control — set variables or add programmatic logic
• Subroutine — call a reusable step sequence
• Increment cycle number — advance the cycle counter
• End / Pause — terminate the protocol

Each step opens in a slide-out editor where you configure its parameters, control mode, and end conditions.

Editing steps

Click any step card to open its editor. Depending on the step type, you can configure:

• Mode — the control mode (C-rate, Current, Power, or Voltage)
• Value — the setpoint, either as a fixed number or a parameterized expression using input["..."] syntax
• Duration — maximum step duration in seconds
• End conditions — one or more termination conditions (voltage, current, C-rate, capacity, temperature, or duration thresholds) with support for derivative-based termination (d/dt)
• Variables — define set_variable entries that compute values after the step completes
• Notes — free-text annotation

Toggle between Fixed and Input for step values and end conditions to create parameterized protocols. Input expressions use the input["name"] syntax described in the UCP reference.

Drive cycle steps

For Drive steps, you can upload a CSV file containing a time-current or time-power profile. The builder shows a chart preview of the uploaded waveform and automatically sets the step name from the filename.

End conditions

Each end condition specifies a variable, an operator (< or >), and a threshold value. You can also configure:

• Derivative termination — terminate based on the rate of change (d/dt) of a variable
• Goto — jump to a named step block when the condition is met

Organizing steps

The Protocol Builder provides several tools for managing step order and structure:

• Move up / down — reorder steps within the list
• Duplicate — create a copy of a step (or an entire block with all nested steps)
• Wrap in block — select multiple steps and group them into a new step block with an optional repeat count
• Move to block — move selected steps into an existing named block
• Move out of block — promote steps from inside a block to the parent level

Step blocks support arbitrary nesting, so you can create complex looping structures by placing blocks inside other blocks.

YAML preview and import/export

The right panel shows the generated YAML in real time. From this panel you can:

• Copy to clipboard — copy the full YAML to your clipboard
• Download — save the protocol as a .yaml file
• Upload — import an existing .yaml or .yml file to load it into the editor
• Edit manually — switch to a text editor to modify the YAML directly, then apply your changes back to the visual editor

Uploaded and manually edited YAML is validated before being applied. If the YAML contains errors, you will see a validation message and the changes will not be applied until the errors are resolved.

Validation

The Protocol Builder validates your protocol at two levels:

1. Frontend validation — checks structure, required fields, and common mistakes (such as duplicate block names or missing end conditions) as you edit
2. Backend validation — sends the protocol to the server for deeper checks, including compatibility with the simulation engine

Validation errors appear as alerts between the global configuration and the step list. Fix any reported issues before using the protocol in a simulation.

Next steps

UCP reference

Full reference for the Universal Cycler Protocol YAML format.

Experiment templates

Use built-in templates for common battery testing protocols.