Templates & Examples

When creating a new custom experiment, you can leverage the pre-built templates provided in the Custom Experiment Builder to get started quickly. These carefully designed templates help you understand how to use the blocks effectively and serve as a foundation that can be easily modified to meet your specific experimental requirements.

Each template is also conveniently available as an example in the toolbox, as shown below:

The Custom Experiment Builder toolbox with its Methods category expanded, listing the pre-built templates that are available as ready-to-use examples.

The examples in the Methods category represent Zahner Lab experiments that have been built using visual blocks.

The examples below are explained in general terms. Comprehensive documentation that explains everything in detail is available for each block in the documentation or via the block context menu. The relevant documentation pages that go beyond connecting blocks are linked.

Cyclic Voltammetry

This example demonstrates how to create a cyclic voltammetry (CV) experiment using the Custom Experiment Builder, equivalent to the CV available in the standard GUI.

Block structure of the cyclic voltammetry template: setting the start and end values, determining the OCV, switching on potentiostatically, ramping to the start value, and running polarizations and a two-cycle cyclic voltammetry before switching off.

  1. Set variable start_value to 500 mV

  2. Set variable end_value to 1500 mV

  3. Set variable OCV to the result of an open circuit voltage determination

  4. Switch on at OCV in potentiostatic mode

  5. Ramp from OCV to start_value at a rate of 100 mV/s

  6. Perform a polarization at start_value

  7. Measure a cyclic voltammetry with start_value and end_value, 2 cycles and vertex values of 500 mV and -500 mV.

  8. Measure a polarization at end_value

  9. Switch off

Potentiostatic EIS

This example demonstrates how to create a potentiostatic EIS experiment using the Custom Experiment Builder, equivalent to the Potentiostatic EIS available in the standard GUI.

Block structure of the potentiostatic EIS template: setting the start value, determining the OCV, switching on, ramping to the start value, and measuring a potentiostatic EIS with a 100 mV amplitude before switching off.

  1. Set variable start_value to 500 mV

  2. Set variable OCV to the result of an open circuit voltage determination

  3. Switch on at OCV

  4. Ramp from OCV to start_value at a rate of 100 mV/s

  5. Measure a potentiostatic EIS at start_value with a 100 mV amplitude

  6. Switch off

Chronoamperometry

This example demonstrates how to create a chronoamperometry experiment using the Custom Experiment Builder, equivalent to the chronoamperometry available in the standard GUI.

Block structure of the chronoamperometry template: setting the start value, determining the OCV, switching on, ramping to the start value, defining a stability condition, and measuring a polarization at the start value before switching off.

  1. Set variable start_value to 500 mV

  2. Set variable OCV to the result of an open circuit voltage determination

  3. Switch on at OCV

  4. Ramp from OCV to start_value at a rate of 100 mV/s

  5. Set a stability condition of 1 mA/s or at least 3 seconds

  6. Measure a polarization at start_value for a maximum of 5 seconds

  7. Switch off

CC-CV

This example demonstrates how to use stop conditions to create a combined constant current - constant voltage (CC-CV) charging experiment.

Block structure of the CC-CV charging template: a galvanostatic constant-current phase at 1 A with a voltage-range stop condition, followed by a potentiostatic constant-voltage phase at the charging voltage with a current stop condition below 50 mA.

  1. Set variable charging_voltage to 4.13 V

  2. Set a stop condition for the range between 3.5 V and charging_voltage, to stop if the voltage goes outside this range

  3. Switch on in galvanostatic mode

  4. Measure a galvanostatic polarization at 1 A until the stop condition is met or 1800 s have passed

  5. Switch off and afterwards switch on in potentiostatic mode

  6. Set an additional stop condition for current below 50 mA

  7. Measure a potentiostatic polarization at charging_voltage until a stop condition is met or 1800 s have passed

  8. Switch off

Naming and Combination

This is a complex example that demonstrates how to combine multiple measurement primitives into a single dataset using dynamic naming.

Block structure of the naming and combination template: a for-each loop over a list of bias voltages that builds dynamic dataset names and combines a ramp, a settling polarization, and a cyclic voltammetry per bias into named datasets.

  1. Set start_value to OCV

  2. Initialize a variable last_bias with start_value

  3. Switch on at start_value

  4. Create a for-each loop with the loop parameter bias that will iterate over the list [500m, 1.0, 1.5]

  5. Create a dynamic dataset name for the ramp and settling polarization to the next bias voltage with the name “ramp_and_settling_to_bias_{bias}”

  6. Measure ramp from last_bias to bias at 100 mV/s

  7. Measure potentiostatic polarization at bias for 10 s

  8. Measure cyclic voltammetry starting and ending at bias, with vertex values of +/- 500 mV from bias. The dataset name is “cv_at_bias_{bias}”

  9. Set last_bias to bias for the next iteration

  10. Iterate over all bias values in the list, then switch off

Error Handling

Error handling can be a difficult concept to grasp at first. The following three examples show the most common situations and demonstrate step by step how the error handling blocks work in practice.

Script Error

A script error occurs when there is a logical mistake in your experiment. For example, trying to perform an operation on the wrong type of value. In this example, a number is used where a list is expected, which triggers a "SCRIPT" error.

Error handling example for a script error: the do section sets the variable i to a number and then tries to set its first list item, which is invalid, so the on error section displays a message box with the error type and message.

  1. Inside the do section, the variable i is set to the number 1.

  2. Next, the experiment tries to set the first item of i to 500m, but i is a number, not a list. This is not a valid operation, so an error occurs.

  3. Because the error happened inside do, execution immediately stops there. Any blocks below this point in the do section are skipped.

  4. The program jumps to the on error section. Here, a message box is displayed that combines the text "An error has occurred, which has been caught." with the error type and the error message.

  5. The finally checkbox is not enabled, so no cleanup actions run.

The resulting message box looks like this:

Message box produced by the script error example, showing the error type "SCRIPT" and a message that a property cannot be created on a number.

The type is "SCRIPT" and the message explains that a property cannot be created on a number, confirming that the error was caused by treating a number as a list.

Device Error

A device error occurs when the IM7 reports a problem. For example, when the requested operating conditions cannot be achieved. In this example, a "DEVICE" error is triggered because the potentiostat cannot deliver the requested current through the connected test object.

Error handling example for a device error: the do section tries to switch on the potentiostat galvanostatically at 1 A into a 100 MΩ resistor, the IM7 reports a device error, the on error section shows a message box, and the finally section switches the potentiostat off.

  1. Inside the do section, the experiment tries to switch on the potentiostat MAIN in galvanostatic mode with a bias of 1 A.

  2. However, a 100 MΩ resistor is connected as the test object. To push 1 A through 100 MΩ, the potentiostat would need to output 100 MV, which is far beyond its capabilities. The IM7 detects this and reports a device error. Execution in do stops immediately and the polarization block is not executed.

  3. The program jumps to the on error section, which displays a message box showing the error type ("DEVICE") and the error message with details from the IM7.

  4. The finally checkbox is enabled, so the finally section runs after on error has finished. Here it switches off the potentiostat MAIN. In this particular case, the potentiostat never actually turned on (because the switch-on itself failed), so the switch-off has no practical effect. However, using finally for cleanup is still good practice. In other situations, the error might occur after the potentiostat has already been switched on.

The resulting message box looks like this:

Message box produced by the device error example, showing the error type "DEVICE" and the details reported by the IM7 about why the potentiostat could not be switched on.

The type is "DEVICE" and the message contains the details reported by the IM7 about why the potentiostat could not be switched on.

The finally section is especially useful for device cleanup. In this example, it makes sure the potentiostat is always switched off, even if an error occurs. This prevents the device from being left in an active state after a failed experiment.

Manual Stop

This example shows how to use the Do On Manual Stop block to react when the user presses the stop button during a running experiment.

Manual stop example: a Do On Manual Stop block that plays a 440 Hz beep and shows a "Manual Break" message box, placed above an Open Circuit Voltage Scan that runs for 10 seconds at 50 readings per second.

  1. The Do On Manual Stop block is placed at the top. It defines what should happen if the user clicks the stop button in the Zahner Lab:

    • Play a beep at 440 Hz for 0.5 seconds.

    • Display a message box with the text "Manual Break".

  2. Below that, an Open Circuit Voltage Scan runs for 10 seconds at a sample rate of 50 readings per second.

  3. If the user presses the stop button while the scan is running, the scan is interrupted and the actions defined in the Do On Manual Stop block are executed. The beep sounds and the message box appears.

The resulting message box looks like this:

Message box produced by the manual stop example, displaying the text "Manual Break" after the user pressed the stop button during the Open Circuit Voltage Scan.