> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/simulate/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](/simulate/universal-cycler-protocol#safety-limits).
## 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](/simulate/universal-cycler-protocol#parameterized-steps-with-input).
### 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
Full reference for the Universal Cycler Protocol YAML format.
Use built-in templates for common battery testing protocols.