Universal Cycler Protocol

The Universal Cycler Protocol (UCP) is a flexible YAML-based language for defining battery cycling experiments. It allows you to create complex experimental sequences with programmatic control.

You can create and edit UCP protocols visually using the Protocol Builder, or by converting a commercial protocol into UCP format. This page is the full reference for the underlying UCP file format.

Global Configuration

You can define global settings for the entire protocol under the optional global key.

global:
  initial_temperature: 25
  initial_state_type: soc_percentage # or "voltage"
  initial_state_value: 100 # percent if soc_percentage, volts if voltage
  resolution:
    time: 60

initial_temperature: The starting temperature for the experiment in degrees Celsius. Defaults to 25. When used in a design optimization, this value is automatically converted to Kelvin and applied as both the initial and ambient temperature for the simulation.
initial_state_type: How to define the initial state of the cell. Allowed values:
- soc_percentage: Interpret initial_state_value as a percentage of state of charge (0–100).
- voltage: Interpret initial_state_value as a starting voltage in Volts.
initial_state_value: The initial value for the selected type.
resolution: The time resolution for the simulation output in seconds. Defaults to 60.

Safety Limits

You can define optional safety limits for the simulation. If any of these are breached, the simulation jumps to a recovery step (goto) or, if no goto is supplied, ends the test. Each limit may be given as a bare number or as an object with an explicit goto so that different fault conditions can route to different recovery steps:

safety_limits:
  # Object form — this limit has its own dedicated recovery step.
  voltage_max:
    value: 4.525
    goto: Pause_Voltage_Fault
    delay: 3 # Optional debounce in seconds. The safety only trips when
             # ``Voltage > 4.525 V`` AND the step has been running for more
             # than 3 s, mirroring the Maccor ``VOLT>=4.525&STIME>3`` idiom.
  # Bare-number form — falls back to the protocol-level `goto` below.
  voltage_min: 2.5
  temperature_min: -20
  temperature_max:
    value: 60
    goto: Pause_Thermal_Fault
  charge_current_max: 10 # Max charge current in Amps (positive value)
  discharge_current_max: 15 # Max discharge current in Amps (positive value)
  # Optional fallback target for any limit that doesn't specify its own `goto`.
  goto: Pause_Generic_Fault

Resolution order when a limit triggers:

If the triggering limit has its own goto, jump there.
Otherwise, if safety_limits.goto is set, jump there.
Otherwise, the test ends.

If a step’s termination condition (see below) has the same value as a global safety_limit, the safety limit takes precedence.

Simulation Steps

Each simulation step is defined as a dictionary with a single key that defines the step’s direction. The value of this key is a dictionary containing the step’s parameters. The primary step directions are:

Rest: The cell is at rest.
Charge: The cell is being charged.
Discharge: The cell is being discharged.
Drive: A drive cycle step (see below).
EIS: An Electrochemical Impedance Spectroscopy step (see below).

Step Parameters

mode: The control mode for the step (e.g., C-rate, Current, Power, Voltage). Required unless the step is Rest.
value: The setpoint for the control mode. This can be a fixed number or a dynamic expression.
duration: The maximum duration of the step in seconds.
ends: A list of one or more cut-off conditions. A step must have either a duration or at least one ends condition.
temperature: (Optional) The ambient temperature for this specific step in Celsius, overriding the global setting.
resolution: (Optional) The time resolution for this specific step, overriding the global setting.
set_variable: (Optional) A list of variables to calculate and set after the step completes.
note: (Optional) A string for informational purposes.

Parameterized Steps with `input['...']`

You can use input['...'] syntax in value, duration, and ends fields to create parameterized protocols. When running the protocol, the actual values are provided at runtime.

steps:
  # Parameterized step value
  - Discharge:
      mode: C-rate
      value: input["C-rate"]
      ends:
        - Voltage < input["Cut-off voltage [V]"]

  # Parameterized duration
  - Rest:
      duration: input["Rest duration [s]"]

  # Parameterized duration in ends
  - Discharge:
      mode: Power
      value: 2
      ends:
        - "Duration > input['Cruise duration [s]']"
        - Voltage < 3.0

  # Expressions with inputs
  - Rest:
      duration: input["Duration [s]"] / 2

Inputs can also be used in resolution, global settings, and set_variable expressions. See Experiment Templates for complete examples.

Termination Conditions (`ends`)

The ends conditions define when a step should terminate.

# Simple termination
ends:
  - "Voltage > 4.2"

# Derivative-based termination
ends:
  - "d/dt(Voltage) < 0.001"

# Termination with a `goto` to another step block
ends:
  - "Voltage < 2.7":
      goto: My_Next_Step

# Termination that ends the entire test
ends:
  - "Voltage < 2.5":
      goto: End Test

Supported Types: Voltage, Current, C-rate, Capacity, Temperature (case-insensitive).
Supported Operators: < and >.
Sign Convention: For Current, C-rate, and Capacity terminations, always provide a positive value. The engine automatically handles the internal sign convention (e.g., negative current for charge). For Voltage and Temperature, signs are respected as written.
Derivative Terminations: To terminate based on the rate of change of a variable, use the format "d/dt(Type) operator value".

If a step’s termination condition is met at the very beginning (e.g., trying to charge a battery that is already at 4.2V), the step will be skipped. Any goto transitions on that termination condition will not be executed. The step’s set_variable entries are still evaluated, so accumulators and reference values you compute at the end of a step remain consistent whether the step ran or was skipped.

Example: Derivative Termination

Derivative-based terminations are useful for ending a step based on the stability of a signal. For example, a constant-voltage charge phase can be terminated when the current stops changing, which indicates the battery is full.

- CV Charge with Current Stability Check:
    - Charge:
        mode: Voltage
        value: 4.2 # Constant Voltage phase
        ends:
          - "d/dt(Current) < 0.001"

Example: CCCV Charge

- CC Charge:
    - Charge:
        mode: C-rate
        value: 1
        ends:
          - "Voltage > 4.2"
- CV Charge:
    - Charge:
        mode: Voltage
        value: 4.2
        ends:
          - "Current < 0.05"

Ambient Temperature Steps

The Ambient Temperature step changes the ambient (chamber) temperature mid-protocol. It is an instantaneous step — it sets the chamber setpoint and immediately advances to the next step; the simulation continues at the new ambient temperature until another Ambient Temperature step is reached.

temperature_setpoint: Required. The new ambient temperature in degrees Celsius. Must be greater than absolute zero.
temperature_ramp_rate: (Optional) Ramp rate in °C/min. Defaults to 2.0.

- Soak at 45 C:
    - Ambient Temperature:
        temperature_setpoint: 45
    - Rest:
        duration: 3600
- Cool to 25 C:
    - Ambient Temperature:
        temperature_setpoint: 25
    - Rest:
        duration: 1800

Use this step for thermal-soak segments, RPT diagnostics that run at a fixed reference temperature, or any protocol whose chamber setpoint changes during the test.

An Ambient Temperature step overrides the global.initial_temperature setting (and any prior step’s temperature override) from that point in the protocol onward.

EIS Steps

The EIS step performs an Electrochemical Impedance Spectroscopy measurement at the current state of the cell.

lower_frequency: The lower frequency bound for the EIS sweep in Hz.
upper_frequency: The upper frequency bound for the EIS sweep in Hz.

Both frequency parameters can be a fixed number or a dynamic expression.

EIS steps are not supported in design optimization experiments. Use EIS steps in standalone simulations instead.

EIS steps run against both physics-based models (using pybamm.EISSimulation under the hood) and Equivalent Circuit Models. For an ECM the impedance is computed analytically from the series resistance parameter R0 [Ohm] and each indexed R_rc (i) [Ohm] / C_rc (i) [F] parallel branch — so the Battery Cycler Simulator, which uses an ECM, can run EIS steps from uploaded protocols (e.g. BioLogic PEIS/GEIS techniques) without any extra configuration. Analytic ECM EIS requires the resistance and capacitance parameters to be constants; SOC- or current-dependent ECM parameters are rejected with a clear error. In the simulation results view, each EIS step is marked with a vertical line on the time-domain plots at the instant the impedance sweep was taken; hovering the marker shows an EIS step N tooltip so you can correlate the Nyquist trace with its position in the cycling history.

Example: Basic EIS

Perform an EIS measurement after a 30-minute rest period.

- Rest:
    - Rest:
        duration: 1800
- Impedance Measurement:
    - EIS:
        lower_frequency: 0.1
        upper_frequency: 1000

Example: EIS with Dynamic Frequencies

The frequencies can be calculated dynamically using variables.

- Set Up Frequencies:
    - Control:
        set_variable:
          - name: VAR_UPPER_FREQ
            eval: 10 * input['Frequency Multiplier']
- Perform EIS:
    - EIS:
        lower_frequency: VAR_UPPER_FREQ / 1000
        upper_frequency: VAR_UPPER_FREQ

Control Steps

Control steps are used for programmatic logic and do not run a simulation. They are ideal for setting variables or creating loops with goto.

- Setup and Jump:
    - Control:
        set_variable:
          - name: VAR_C_RATE
            eval: 1.5
    - "Increment cycle number"

Control step parameters

set_variable: (Optional) A list of variables to set (see dynamic behavior with variables).
goto: (Optional) The name of the step block to jump to after executing this control step. This enables non-sequential control flow, such as branching to different steps based on variable values.

- Assign C-rate and Continue:
    - Control:
        set_variable:
          - name: VAR_C_RATE
            eval: 0.33
        goto: Start_Discharge

Special string commands are also available:

"Increment cycle number": Increments the internal cycle counter.
"End" or "Pause": Terminates the entire simulation.

Reserved `goto` targets

In addition to jumping to a named step block, goto accepts the reserved target End Test, which stops the simulation immediately. This works from both step termination conditions (ends) and from Control step goto fields, and is also valid inside subschedules — jumping to End Test from a subschedule ends the entire test, not just the subschedule. A Control step’s goto runs unconditionally every time the step is entered, so use it to terminate a branch you have already routed into:

# Unconditional: entering this Control step always ends the test
- Stop Here:
    - Control:
        goto: End Test

To terminate conditionally, attach the goto to a step termination condition instead — the jump fires only when that condition is met:

# Conditional: only jumps to End Test when the voltage drops below 2.8 V
- Discharge until fault:
    Discharge:
      C-rate: 0.33
    ends:
      - "Voltage < 2.8":
          goto: End Test

Use End Test when you want a fault condition or logic branch to terminate the run explicitly rather than falling through to the next step.

Dynamic Behavior with Variables

You can define variables using set_variable and use them to create dynamic, responsive protocols.

name: The name of the variable. Must start with VAR_.
eval: A Python expression to be evaluated. The result must be a number.

The eval expression can use:

User Inputs: input['...']
Other Variables: Any VAR_ variable already defined.
Special Variables: t (step-relative time in seconds), Cycle (0-indexed cycle counter).
Simulation Results: Voltage, Current, etc. from the previous step.
Helper Functions: first(), last(), mean(), abs(), sign(), min(), max(), ifelse().

Initialising variables

Expressions are evaluated eagerly — ifelse(condition, A, B) evaluates both branches before picking one — so a variable referenced anywhere in an expression must already exist. Use a Control step at the top of the protocol to seed every variable you’ll write to:

- Initialize Variables:
    - Control:
        set_variable:
          - { name: VAR_REFERENCE_CAPACITY, eval: "0" }
          - { name: VAR_PEAK_TEMP, eval: "25" }
        note: Seed accumulator variables before the cycling loop.

This matters most for the common “set on first cycle, carry over otherwise” idiom:

set_variable:
  - name: VAR_REFERENCE_CAPACITY
    # Without an init Control step above, VAR_REFERENCE_CAPACITY is undefined
    # the first time this expression runs and the simulation will fail.
    eval: ifelse(Cycle == 0, last(Capacity), VAR_REFERENCE_CAPACITY)

Protocols imported from a Maccor .000 file automatically gain a leading Initialize Variables Control block that seeds every referenced VARn to 0 — this mirrors the way real Maccor cyclers default user variables in hardware. You’ll see it at the top of the parsed UCP YAML.

Example: Time-Varying Control

Linearly ramp the C-rate from 0.1 to 1.1 over one hour.

- Ramp Discharge:
    - Discharge:
        mode: C-rate
        value: 0.1 + t / 3600
        duration: 3600

Time-varying values can also change sign within a step — for example, a piecewise current waveform built with sign() that charges for the first 30 s and then discharges for the next 30 s:

- Piecewise Current:
    - Charge:
        mode: Current
        value: sign(30 - t) * 1.0
        duration: 60
        ends:
          - Voltage > input["Upper voltage cut-off [V]"]
          - Voltage < input["Lower voltage cut-off [V]"]

When a step value is an explicit function of t, the waveform may legitimately drive the cell in both directions during the single step. The usual rule that a Charge step can only carry an upper voltage cut-off (and a Discharge step a lower one) is relaxed for time-varying values, so you can attach safety cut-offs on both sides.

Example: Conditional Logic

Use the ifelse helper to create conditional logic. This example defines a subsequent step’s direction based on the final voltage of the previous step.

- Discharge and Check:
    - Discharge:
        mode: C-rate
        value: 1
        duration: 600
        set_variable:
          - name: VAR_NEEDS_CHARGE
            eval: ifelse(last(Voltage) < 3.5, 1, 0)

- Conditional Step:
    - Direction[ifelse(VAR_NEEDS_CHARGE == 1, "Charge", "Rest")]:
        mode: C-rate
        value: 1
        ends:
          - "Voltage > input['Upper voltage cut-off [V]']"

Step Blocks

Steps can be grouped into named blocks. This is essential for goto targets and for repeating a sequence of steps using the repeat keyword.

- Ten Pulses:
    - Discharge:
        mode: C-rate
        value: 5
        duration: 1
    - Rest:
        duration: 1
  repeat: 10

A block’s name cannot be one of the reserved step types (Charge, Discharge, Rest, Control, etc.). The reserved goto target End Test is allowed as a jump destination but cannot be used as a block name.

Drive Cycles

You can use a drive cycle for complex profiles by passing data to the solve_protocol function in your Python code and referencing it in the YAML.

In Python: Pass a drive_cycles dictionary where values are 2-column NumPy arrays (time, value).
In YAML: Use the Drive direction. The value is the name of the drive cycle from the dictionary. The duration is defined by the time column in the data.
mode: Controls how the second data column is interpreted. Use Current (default, amps) for a current profile, or Power (watts) for a power profile. Voltage cut-offs can be attached to either mode via ends.

# Current-mode drive cycle (values in amps)
- US06 Drive Cycle:
    - Drive:
        mode: Current
        value: US06

# Power-mode drive cycle (values in watts)
- Power Profile:
    - Drive:
        mode: Power
        value: LoadProfile
        ends:
          - Voltage < input['Lower voltage cut-off [V]']
          - Voltage > input['Upper voltage cut-off [V]']

Subroutines

Subroutines are reusable sequences of steps defined in your Python code and called from the YAML protocol. This is useful for standard procedures like a CCCV charge.

In Python: Pass a subroutines dictionary to solve_protocol. The values are lists of steps.
In YAML: Use the Subroutine step type with the name of the subroutine to execute.

# In your main protocol.yaml file
steps:
  - Initial Rest:
      - Rest:
          duration: 1800

  - "Increment cycle number"
  - Subroutine: CCCV # This calls the "CCCV" subroutine defined in Python

Output

The protocol solver returns a pandas DataFrame containing the results of the simulation, including time, voltage, current, temperature, cycle number, and any custom variables defined with set_variable. For EIS steps, the output DataFrame includes frequency-domain impedance data instead of time-domain data:

Column	Description
`Frequency [Hz]`	Excitation frequency
`Z_Re [Ohm]`	Real part of impedance
`Z_Im [Ohm]`	Imaginary part of impedance (negative for capacitive behavior)

During EIS steps, time-domain columns (Time [s], Voltage [V], Current [A]) are present but contain NaN values. The Step count column identifies which step each row belongs to, allowing you to separate EIS data from cycling data.

Get Started

Core Concepts

Operate

Data

Build

Pipelines

Simulate

Optimize

Global Configuration

Safety Limits

Simulation Steps

Step Parameters

Parameterized Steps with `input['...']`

Termination Conditions (`ends`)

Example: Derivative Termination

Example: CCCV Charge

Ambient Temperature Steps

EIS Steps

Example: Basic EIS

Example: EIS with Dynamic Frequencies

Control Steps

Control step parameters

Reserved `goto` targets

Dynamic Behavior with Variables

Initialising variables

Example: Time-Varying Control

Example: Conditional Logic

Step Blocks

Drive Cycles

Subroutines

Output

​Global Configuration

​Safety Limits

​Simulation Steps

​Step Parameters

​Parameterized Steps with input['...']

​Termination Conditions (ends)

​Example: Derivative Termination

​Example: CCCV Charge

​Ambient Temperature Steps

​EIS Steps

​Example: Basic EIS

​Example: EIS with Dynamic Frequencies

​Control Steps

​Control step parameters

​Reserved goto targets

​Dynamic Behavior with Variables

​Initialising variables

​Example: Time-Varying Control

​Example: Conditional Logic

​Step Blocks

​Drive Cycles

​Subroutines

​Output

Global Configuration

Safety Limits

Simulation Steps

Step Parameters

Parameterized Steps with `input['...']`

Termination Conditions (`ends`)

Example: Derivative Termination

Example: CCCV Charge

Ambient Temperature Steps

EIS Steps

Example: Basic EIS

Example: EIS with Dynamic Frequencies

Control Steps

Control step parameters

Reserved `goto` targets

Dynamic Behavior with Variables

Initialising variables

Example: Time-Varying Control

Example: Conditional Logic

Step Blocks

Drive Cycles

Subroutines

Output