Skip to main content

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.

Protocols define the sequence of electrochemical steps that make up an experiment — charges, discharges, rests, EIS measurements, and more. Ionworks lets you create protocols from scratch, upload them from cycler software, or start from built-in templates, and then reuse them across simulations.

​
Protocols page

Navigate to Protocols in the sidebar to see all saved protocols in your project. The list shows each protocol’s name, when it was created, and whether it has configurable input parameters. From here you can:
  • Create a new protocol
  • View a protocol’s source, parsed representation, and input parameters
  • Clone a protocol to create a modified version
  • Edit a protocol’s name and input parameter configuration

​
Creating a protocol

Click New Protocol to open the protocol editor. You have several ways to define a protocol:

​
Type or paste

Enter protocol text directly in the source editor on the left. Ionworks supports multiple cycler formats:
  • UCP (Universal Cycler Protocol) — Ionworks’ native YAML format
  • Maccor — Maccor procedure files (.000 XML format)
  • Neware — Neware protocol exports
  • BioLogic — BioLogic protocol exports
The editor automatically detects the format and parses it. The right side shows the parsed result in UCP (YAML) and human-readable formats so you can verify the interpretation.

​
Upload a file

Click Upload to load a protocol file from your computer. The file is read, its format detected, and the content placed into the source editor. The protocol name is pre-filled from the filename.

​
Interactive builder

Click Interactive Builder to open a visual step-by-step protocol editor. You can add charge, discharge, rest, and other step types, configure their parameters, and set termination conditions. The builder generates UCP YAML which is placed into the source editor when you apply.

​
Start from an existing protocol

Use the Start from existing protocol dropdown to select a saved protocol as a starting point. This pre-fills the editor with the protocol’s source text, which you can then modify.

​
Parameterized inputs

Protocols can use input["..."] expressions to define parameters that are configurable at simulation time. For example: 
global:
    initial_temperature: input["Temperature [°C]"]
    initial_state_type: soc_percentage
    initial_state_value: input["Initial SOC [%]"]

steps:
    - Discharge:
        mode: C-rate
        value: input["C-rate"]
        ends:
            - Voltage < input["Cut-off voltage [V]"]
When you enter or upload a protocol, Ionworks automatically detects these input["..."] references and displays them below the editor. For each detected input you can configure:
  • Type — whether the input is a numeric value (e.g. C-rate, temperature) or a direction selector (Charge / Discharge)
  • Default value — the value to pre-fill when this protocol is used in a simulation
These settings are saved as the protocol’s parameters schema. When someone uses this protocol to run a simulation, the schema generates the appropriate input form with the configured defaults.

​
Voltage cut-off inputs

Inputs named Lower voltage cut-off [V] and Upper voltage cut-off [V] are special — they are automatically provided by the cell model’s voltage limits and do not appear as user-configurable fields.

​
Special values

Default values can reference cell-specific properties:
  • V_MIN — the cell model’s minimum safe voltage
  • V_MAX — the cell model’s maximum safe voltage
These are automatically resolved to the correct values based on the selected cell when running a simulation.

​
Built-in templates

Ionworks provides 9 pre-configured experiment templates for common battery testing protocols. Each template defines a protocol with adjustable parameters that you can use directly or as a starting point for your own protocols.

Constant Current Discharge

Discharge at a fixed C-rate until voltage cutoff

Constant Current Charge

Standard CC-CV charging protocol

GITT

Galvanostatic intermittent titration technique

PITT

Potentiostatic intermittent titration technique

Pulse Resistance

DC internal resistance (DCIR) measurement

Pseudo-OCV

Open-circuit voltage approximation at low C-rate

EIS

Electrochemical impedance spectroscopy

Cyclic Voltammetry

Voltage sweep to identify redox reactions

Cycle Aging

Repeated charge/discharge with capacity fade monitoring
See the full template reference for detailed parameters and UCP protocol definitions.

​
Using protocols in simulations

When running a simulation, you can provide a protocol in several ways:
  1. Select a saved protocol from the “Start from existing protocol” dropdown — this includes both the built-in templates and your custom protocols
  2. Paste or type a protocol directly in the editor
  3. Upload a protocol file
  4. Use the Interactive Builder to create one visually
If the protocol has detected input parameters, they appear as configurable fields in the simulation setup. You can enter values (or comma-separated lists for parameter sweeps) for each input. If you enter a custom protocol and choose to name it, it is saved for future reuse and appears in the protocols list and the “Start from existing protocol” dropdown.

​
Next steps