> ## 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.

# Experiment Templates

> Reference for the 9 built-in UCP experiment templates with adjustable parameters and computed metrics

<Info>
  This page is a detailed reference for built-in templates. See [Protocols](/simulate/protocols) for the full guide on creating, managing, and using protocols.
</Info>

# Experiment Templates

Ionworks provides 9 built-in experiment templates — pre-configured battery testing protocols that can be customized with different parameters. Each template defines a protocol using the [Universal Cycler Protocol (UCP)](/simulate/universal-cycler-protocol) format with adjustable variables to suit your needs.

## Template metrics

Some experiment templates include built-in **metrics** — summary values automatically computed from simulation results. When you run a simulation using one of these templates, the metrics are calculated and displayed in the [Data View](/simulate/simulations#data-view) alongside the simulation inputs.

Metrics use a declarative configuration format with these types:

| Category        | Types                                                | Description                                                                    |
| --------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Aggregation** | `First`, `Last`, `Mean`, `Minimum`, `Maximum`, `Sum` | Compute a single value from a time series variable                             |
| **Crossing**    | `SOC`, `Voltage`, `Time`                             | Find the value of a variable at a specific state of charge, voltage, or time   |
| **Composed**    | `ComposedMetric`                                     | Combine metrics with arithmetic operations (`add`, `sub`, `mul`, `div`, `abs`) |

Metrics can also target a specific protocol step using the `step` field (0-indexed), which is useful for multi-step experiments like pulse resistance tests.

<Tip>
  The same metric type system is used in [Optimization Templates](/optimize/templates#metric-types) for defining optimization objectives and constraints.
</Tip>

## Available Templates

### 1. Constant Current Discharge

**Description:** Discharges the battery at a constant C-rate until a voltage cutoff is reached.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Initial SOC \[%]** - Starting state of charge (default: 100%)
* **C-rate** - Discharge rate relative to nominal capacity (default: 1C)
* **Cut-off voltage \[V]** - Minimum voltage to stop discharge (default: V\_MIN)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  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"]
          resolution:
              time: 10 / input["C-rate"]
          ends:
              - Voltage < input["Cut-off voltage [V]"]
  ```
</Accordion>

**Computed metrics:**

| Metric                         | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| Capacity \[A.h]                | Final discharge capacity                       |
| Energy \[W\.h]                 | Final discharge energy                         |
| Mean internal resistance \[mΩ] | Average internal resistance over the discharge |
| Mean current \[A]              | Absolute average current                       |
| Mean power \[W]                | Absolute average power                         |
| Min/Max anode potential \[V]   | Anode potential range during discharge         |
| Min/Max cathode potential \[V] | Cathode potential range during discharge       |

***

### 2. Constant Current Charge

**Description:** Charges the battery using a constant current (CC) phase followed by a constant voltage (CV) hold. This is the standard CC-CV charging protocol.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Initial SOC \[%]** - Starting state of charge (default: 0%)
* **C-rate** - Charge rate during CC phase (default: 1C)
* **Cut-off voltage \[V]** - Maximum voltage for CC/CV phases (default: V\_MAX)
* **CV cut-off C-rate** - C-rate threshold to end CV phase (default: 0.02C)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: soc_percentage
      initial_state_value: input["Initial SOC [%]"]

  steps:
      - Charge:
          mode: C-rate
          value: input["C-rate"]
          resolution:
              time: 10 / input["C-rate"]
          ends:
              - Voltage > input["Cut-off voltage [V]"]
      - Charge:
          mode: Voltage
          value: input["Cut-off voltage [V]"]
          ends:
              - C-rate < input["CV cut-off C-rate"]
  ```
</Accordion>

**Computed metrics:**

| Metric                          | Description                                                |
| ------------------------------- | ---------------------------------------------------------- |
| Charge capacity \[A.h]          | Final charge capacity                                      |
| Energy \[W\.h]                  | Final charge energy                                        |
| Mean internal resistance \[mΩ]  | Average internal resistance                                |
| Mean current \[A]               | Average charging current                                   |
| Mean power \[W]                 | Absolute average power                                     |
| Min/Max anode potential \[V]    | Anode potential range during charge                        |
| Min/Max cathode potential \[V]  | Cathode potential range during charge                      |
| Charge time (10-80% SOC) \[min] | Time to charge from 10% to 80% state of charge, in minutes |

***

### 3. GITT (Galvanostatic Intermittent Titration Technique)

**Description:** Alternates between current pulses and rest periods to measure quasi-equilibrium voltage as a function of state of charge. This technique separates kinetic and thermodynamic contributions to the cell voltage. This experiment will run until the voltage reaches the upper or lower voltage cut-off during the pulse phase.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Direction** - 'Charge' or 'Discharge' (default: 'Discharge')
* **Pulse C-rate** - Current rate during active pulses (default: 0.1C)
* **Pulse duration \[s]** - Length of each current pulse (default: 1800s / 30 min)
* **Rest duration \[s]** - Length of each rest period (default: 1800s / 30 min)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: soc_percentage
      initial_state_value: ifelse(input["Direction"] == "Charge", 0, 100)

  steps:
      - Control:
          set_variable:
              - name: VAR_IS_CHARGE
                eval: ifelse(input["Direction"] == "Charge", 1, 0)
              - name: VAR_VMAX
                eval: input["Upper voltage cut-off [V]"]
              - name: VAR_VMIN
                eval: input["Lower voltage cut-off [V]"]
      - Pulse Block:
          steps:
              - Direction[input["Direction"]]:
                  mode: C-rate
                  value: input["Pulse C-rate"]
                  duration: input["Pulse duration [s]"]
                  ends:
                      - "Voltage > ifelse(VAR_IS_CHARGE == 1, VAR_VMAX, 1e9)":
                          goto: Final Rest Block
                      - "Voltage < ifelse(VAR_IS_CHARGE == 0, VAR_VMIN, -1e9)":
                          goto: Final Rest Block
              - Rest:
                  duration: input["Rest duration [s]"]
          repeat: 1000
      - Final Rest Block:
          - Rest:
              duration: input["Rest duration [s]"]
  ```
</Accordion>

***

### 4. PITT (Potentiostatic Intermittent Titration Technique)

**Description:** Steps the voltage in small increments with rest periods between steps. Measures current response to voltage changes to study electrode kinetics.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Starting voltage \[V]** - Initial cell voltage (default: V\_MIN)
* **Final voltage \[V]** - Target cell voltage (default: V\_MAX)
* **Voltage step \[V]** - Size of voltage increments (default: 0.1V)
* **Pulse duration \[s]** - Hold time at each voltage (default: 900s / 15 min)
* **Rest duration \[s]** - Rest time between voltage steps (default: 900s / 15 min)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: voltage
      initial_state_value: input["Starting voltage [V]"]

  steps:
      - Control:
          set_variable:
              - name: VAR_VOLTAGE
                eval: input["Starting voltage [V]"]
              - name: VAR_CHARGE
                eval: input["Final voltage [V]"] > input["Starting voltage [V]"]
              - name: VAR_END_CONDITION
                eval: input["Final voltage [V]"]

      - Pulse Block:
          steps:
              - Direction[ifelse(VAR_CHARGE == 1, "Charge", "Discharge")]:
                  mode: Voltage
                  value: VAR_VOLTAGE
                  duration: input["Pulse duration [s]"]
                  ends:
                      - "Voltage > ifelse(VAR_CHARGE == 1, VAR_END_CONDITION, 1e9)":
                          goto: Final Rest Block
                      - "Voltage < ifelse(VAR_CHARGE == 0, VAR_END_CONDITION, -1e9)":
                          goto: Final Rest Block

              - Rest:
                  set_variable:
                      - name: VAR_VOLTAGE
                        eval: VAR_VOLTAGE + input["Voltage step [V]"]
                  duration: input["Rest duration [s]"]
          repeat: 1000

      - Final Rest Block:
          - Rest:
              duration: input["Rest duration [s]"]
  ```
</Accordion>

***

### 5. Pulse Resistance

**Description:** Measures DC internal resistance (DCIR) using a rest-pulse-rest sequence. Quantifies the instantaneous voltage response to a current pulse.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Initial SOC \[%]** - State of charge for test (default: 50%)
* **C-rate** - Magnitude of current pulse (default: 1C)
* **Direction** - 'Charge' or 'Discharge' (default: 'Discharge')
* **Duration \[s]** - Total pulse duration (default: 10s)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: soc_percentage
      initial_state_value: input["Initial SOC [%]"]

  steps:
      - Rest:
          duration: input["Duration [s]"]/2
      - Discharge:
          mode: C-rate
          value: input["C-rate"]
          duration: input["Duration [s]"]
      - Rest:
          duration: input["Duration [s]"]/2
  ```
</Accordion>

**Computed metrics:**

| Metric                    | Description                                                                      |
| ------------------------- | -------------------------------------------------------------------------------- |
| Pulse overpotential \[mV] | Voltage difference between rest and pulse end, in millivolts                     |
| Pulse resistance \[mΩ]    | DC internal resistance calculated as overpotential divided by mean pulse current |

<Info>
  Pulse resistance metrics use step-level filtering to compare the voltage at the end of the initial rest period (step 0) with the voltage at the end of the current pulse (step 1).
</Info>

***

### 6. Pseudo-OCV

**Description:** Measures the voltage profile at a very low C-rate to approximate the open-circuit voltage (OCV) vs. SOC relationship. The slow rate minimizes polarization effects.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Direction** - 'Charge' or 'Discharge' (default: 'Discharge')
* **C-rate** - Very slow rate to minimize polarization (default: 0.05C)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: soc_percentage
      initial_state_value: ifelse(input["Direction"] == "Charge", 0, 100)

  steps:
      - Control:
          set_variable:
              - name: VAR_IS_CHARGE
                eval: input["Direction"] == "Charge"
              - name: VAR_VMAX
                eval: input["Upper voltage cut-off [V]"]
              - name: VAR_VMIN
                eval: input["Lower voltage cut-off [V]"]
      - Direction[input["Direction"]]:
          mode: C-rate
          value: input["C-rate"]
          ends:
              # End of charge/discharge
              - Voltage > ifelse(VAR_IS_CHARGE == 1, VAR_VMAX, 1e9)
              - Voltage < ifelse(VAR_IS_CHARGE == 0, VAR_VMIN, -1e9)
  ```
</Accordion>

**Computed metrics:**

| Metric                         | Description                          |
| ------------------------------ | ------------------------------------ |
| Capacity \[A.h]                | Absolute step capacity               |
| Mean internal resistance \[mΩ] | Absolute average internal resistance |
| Mean current \[A]              | Absolute average current             |

***

### 7. EIS (Electrochemical Impedance Spectroscopy)

**Description:** Applies small AC voltage perturbations across a range of frequencies to measure the complex impedance of the cell. Maps out kinetic and transport processes.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **SOC \[%]** - State of charge for measurement (default: 50%)
* **Lower frequency \[Hz]** - Minimum frequency (default: 0.0001 Hz)
* **Upper frequency \[Hz]** - Maximum frequency (default: 10000 Hz)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: soc_percentage
      initial_state_value: input["SOC [%]"]

  steps:
      - EIS:
          lower_frequency: input["Lower frequency [Hz]"]
          upper_frequency: input["Upper frequency [Hz]"]
  ```
</Accordion>

***

### 8. Cyclic Voltammetry

**Description:** Sweeps the cell voltage linearly between upper and lower limits at a controlled scan rate. Measures current response to identify redox reactions.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Scan rate \[mV/s]** - Rate of voltage sweep (default: 0.1 mV/s)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: voltage
      initial_state_value: input["Lower voltage cut-off [V]"]

  steps:
      - Control:
          set_variable:
              - name: VAR_SCAN_RATE_VS
                eval: input["Scan rate [mV/s]"] / 1000
      - Charge:
          mode: Voltage
          value: input["Lower voltage cut-off [V]"] + VAR_SCAN_RATE_VS * t
          ends:
              - Voltage > input["Upper voltage cut-off [V]"]
      - Discharge:
          mode: Voltage
          value: input["Upper voltage cut-off [V]"] - VAR_SCAN_RATE_VS * t
          ends:
              - Voltage < input["Lower voltage cut-off [V]"]
  ```
</Accordion>

***

### 9. Cycle Aging

**Description:** Repeated charge/discharge cycles with capacity fade monitoring. Uses CCCV charge (constant current to voltage limit, then constant voltage to C-rate cutoff) and CC discharge with dual termination (voltage cutoff or depth-of-discharge capacity limit). Tracks capacity retention and can stop early when capacity falls below a specified percentage of nominal.

**Adjustable Parameters:**

* **Temperature \[°C]** - Operating temperature (default: 25°C)
* **Nominal capacity \[A.h]** - Cell capacity for C-rate and DOD calculations (default: 5.0 A.h)
* **Charge C-rate** - C-rate during CC charge phase (default: 1C)
* **Discharge C-rate** - C-rate during discharge (default: 1C)
* **Depth of discharge \[%]** - Target DOD per cycle as % of nominal capacity (default: 100%)
* **Discharge voltage cutoff \[V]** - Minimum voltage to stop discharge (default: V\_MIN)
* **Charge voltage \[V]** - Maximum voltage for CC/CV charge (default: V\_MAX)
* **Charge C-rate cutoff** - C-rate threshold to end CV phase (default: 0.05C)
* **Post charge rest time \[s]** - Rest after charge (default: 600 s)
* **Post discharge rest time \[s]** - Rest after discharge (default: 600 s)
* **Number of cycles** - Maximum charge/discharge cycles (default: 100)
* **End capacity \[%]** - Stop cycling when capacity falls below this % of nominal (default: 80%)

<Accordion title="UCP Protocol">
  ```yaml theme={null}
  global:
      initial_temperature: input["Temperature [°C]"]
      initial_state_type: soc_percentage
      initial_state_value: 50

  steps:
      - Control:
          set_variable:
              - name: VAR_VMAX
                eval: input["Charge voltage [V]"]
              - name: VAR_VMIN
                eval: input["Discharge voltage cutoff [V]"]
              - name: VAR_NOMINAL_CAPACITY
                eval: input["Nominal capacity [A.h]"]
              - name: VAR_DOD_FRACTION
                eval: input["Depth of discharge [%]"] / 100
              - name: VAR_END_CAPACITY_RATIO
                eval: input["End capacity [%]"] / 100
              - name: VAR_CURRENT_CAPACITY
                eval: "0"
              - name: VAR_CAPACITY_RATIO
                eval: "1.0"
      - Control:
          set_variable:
              - name: VAR_DOD_CAPACITY_LIMIT
                eval: VAR_DOD_FRACTION * VAR_NOMINAL_CAPACITY
      - Cycle Block:
          repeat: input["Number of cycles"]
          steps:
              - Increment cycle number
              - Charge:
                  mode: C-rate
                  value: input["Charge C-rate"]
                  resolution:
                      time: 10 / input["Charge C-rate"]
                  ends:
                      - Voltage > VAR_VMAX
              - Charge:
                  mode: Voltage
                  value: VAR_VMAX
                  resolution:
                      time: 10 / input["Charge C-rate"]
                  ends:
                      - C-rate < input["Charge C-rate cutoff"]
              - Rest:
                  duration: input["Post charge rest time [s]"]
              - Discharge:
                  mode: C-rate
                  value: input["Discharge C-rate"]
                  resolution:
                      time: 10 / input["Discharge C-rate"]
                  ends:
                      - Voltage < VAR_VMIN
                      - Capacity > VAR_DOD_CAPACITY_LIMIT
                  set_variable:
                      - name: VAR_CURRENT_CAPACITY
                        eval: abs(last(Capacity))
              - Control:
                  set_variable:
                      - name: VAR_CAPACITY_RATIO
                        eval: VAR_CURRENT_CAPACITY / VAR_NOMINAL_CAPACITY
              - Rest:
                  duration: input["Post discharge rest time [s]"]
                  ends:
                      - type: Variable
                        expression: VAR_CAPACITY_RATIO < VAR_END_CAPACITY_RATIO
                        goto: End Block
      - End Block:
          - Rest:
              duration: 1
  ```
</Accordion>

**Computed metrics:**

| Metric                          | Description                                                   |
| ------------------------------- | ------------------------------------------------------------- |
| Total cycles                    | Number of completed charge/discharge cycles                   |
| Initial capacity \[A.h]         | Absolute discharge capacity from the first cycle              |
| Final capacity \[A.h]           | Absolute discharge capacity from the last cycle               |
| Capacity retention \[%]         | Ratio of final to initial capacity, expressed as a percentage |
| Total energy throughput \[W\.h] | Sum of discharge and charge energy over all cycles            |
| Total charge throughput \[A.h]  | Sum of discharge and charge capacity over all cycles          |

***

## Parameter Types

### Standard Parameters

Most templates accept these common parameters:

* **Temperature \[°C]**: Operating temperature
* **Initial SOC \[%]**: Starting state of charge (0-100%)
* **C-rate**: Current normalized by nominal capacity (e.g., 1C = full capacity in 1 hour)

### Voltage References

Some parameters can reference cell-specific voltages:

* **V\_MIN**: Minimum safe voltage for the cell model
* **V\_MAX**: Maximum safe voltage for the cell model

These are automatically replaced with values from your selected cell model.

### Direction

For bidirectional tests, specify 'Charge' or 'Discharge' to set the current direction.

***

## Using Experiment Templates

### In Simulations

1. Select a cell and model
2. Choose an experiment template from the "Start from existing protocol" dropdown
3. Adjust parameters as needed
4. Run the simulation

### Creating Studies

You can run multiple experiments with different parameters in a study to:

* Compare performance at different temperatures
* Evaluate different C-rates
* Map out behavior across SOC range

## Next Steps

* [Create your own protocols](/simulate/protocols) with custom parameters
* Learn more about [Projects and Studies](/core-concepts/projects-studies)
* Explore [Simulations](/simulate/simulations)
* Understand the [Universal Cycler Protocol](/simulate/universal-cycler-protocol) format