rhd instruments GmbH & Co. KG, Otto-Hesse-Str.
19/T3, 64293 Darmstadt
Tel.: 06151-8707187, E-Mail: info@[Link]
RelaxIS SDK – Basic Tutorial
Contents of this Tutorial
In this tutorial you will learn the following steps:
• Creating a new plugin
• Writing a basic new circuit element
• Compiling and using the new plugin
Please follow the steps to get a basic idea of how to write plugins using the RelaxIS SDK. Please install
and start RelaxIS 3 to begin.
Step 1 – Launching the RelaxIS SDK Code Editor
In RelaxIS please select Extras > Tools > RelaxIS SDK Code Editor from the ribbon bar.
This launches the code editor, that lets you create plugins easily. Alternativly you can
launch the editor directly from the Windows start menu.
It is also possible to use the Microsoft Visual Studio IDE to write plugins with additional
editor features, however this tutorial focuses on the inbuilt code editor.
Step 2 – Creating a new Circuit Element plugin
In the Code Editor, please select Main > Program > New.
In the window, please select “Circuit Element” from the list of available templates.
Enter a name of the plugin. Please use a name that starts with a letter and only contains letters
and numbers.
You can choose, which programming language you want to use. This tutorial uses Visual [Link], as
it provides easier readability for new users. The C# language is more familiar to users who already
programmed in C, C++ or Java.
Please click OK to create the plugin.
Step 3 – Writing the plugin code
Step 3.1 Writing general plugin description properties
The template automatically creates functions and properties of the selected plugin type. It is your
responsibility to fill them with life. Please note that lines starting with ‘ (or // in C#) are called
comments and are not seen as program code.
Notice that the class name is derived from the plugin name you entered, and that the class inherits
from the RelaxISPlugin_CircuitElement2 class.
Basic SDK Tutorial – rev1.1 – 2024/09
RelaxIS - Impedance Spectrum Analysis © 2013-2024 Jens Wallauer
rhd instruments GmbH & Co. KG, Otto-Hesse-Str. 19/T3, 64293 Darmstadt
Tel.: 06151-8707187, E-Mail: info@[Link]
Each plugin needs a name and a description, represented by the String (meaning text) properties
Name and Description. The plugin name should be unique among all plugins. The description is
text that is displayed in the RelaxIS Setup screen.
An example implementation for a String property is
Public Overrides ReadOnly Property Name As String
Get
Return “MyPlugin”
End Get
End Property
Here MyPlugin would be the name of the new plugin. The Return statement says that this property
should give back the value it is followed by. A string is enclosed in double-quotes. You can
implement the Description properly similarly.
The Abbreviation property defines, which symbol the new circuit element has in an equivalent
circuit (like the P for a constant phase element). It has to start with an uppercase letter followed only
by lowercase letters or numbers.
Public Overrides ReadOnly Property Abbreviation As String
Get
Return “Mp”
End Get
End Property
The Formula property is again only for display in the setup dialog and can return the formula in a
text representation.
Step 3.2 Defining the circuit element parameters
Next the plugin needs to define which parameters go into the impedance calculation. Each parameter
consists of a name, a default value, default limits and whether the parameter is fixed by default. To
define the parameters, the StandardParameters property is used. Note, that the return type of
this property is not String as in the other properties we encountered, but instead is
IReadOnlyCollection(Of Fitparameter).
That means it is a collection of multiple objects of type Fitparameter. A collection in this context
can be various different specific types. In this tutorial we will return a List(Of Fitparameter),
since the List class also implements the required IReadOnlyCollection interface.
We require 2 parameters for the CPE calculation and hence the list will have two objects in it.
Public Overrides ReadOnly Property StandardParameters As IReadOnlyCollection(Of Fitparameter)
Get
Return New List(Of Fitparameter) From {
New Fitparameter("CPE Q", False, 1e-6, 0, 1e-15, 1e15),
New Fitparameter("CPE alpha", False, 0.9, 0, 0.15, 1)
}
End Get
End Property
Basic SDK Tutorial – rev1.1 – 2024/09
RelaxIS - Impedance Spectrum Analysis © 2013-2024 Jens Wallauer
rhd instruments GmbH & Co. KG, Otto-Hesse-Str. 19/T3, 64293 Darmstadt
Tel.: 06151-8707187, E-Mail: info@[Link]
You can see that the new list is initialized with two parameters that are constructed with the default
parameter values. The order of the parameters is defined by the given class constructor. This is
documented in the API reference:
Step 3.3 Writing the impedance calculation formula
The workhorse of the circuit element is the calculation of the impedance. This is done in the function
CalculateImpedance, that Returns a Complex value. The latter is a type that contains two
floating point numbers as real and imaginary parts and implements mathematical function for complex
numbers.
The function is called with three parameters: frequency, parameters and index. Frequency
is a single floating point value that gives the frequency (note: not the angular frequency).
Parameters is a list of parameter values for the full model that the circuit element is a part of. That
means that it will in most cases contain more values than the amount of parameters defined for this
element. The 0-based index, at which the parameters of this element are found is given by the index
parameter. For example if our element here is used in the model R-(R)(Mp), the layout of the
parameters array will be
Index 0 1 2 3
Name Resistance 1 Resistance 2 CPE Q 1 CPE alpha 1
Value 55.5 123.8 2e-6 0.94
The value of the index parameter in this case will be 2. Hence, use the index parameter value to
calculate the index of our parameter values in the overall array.
In this tutorial we will reimplement the Constant Phase Element, that is defined as:
1
𝑍𝐶𝑃𝐸 = 𝛼
𝑄∙ (𝑖𝜔)
At the top of the template you can find the line Imports RelaxIS_SDK.libMath. This imports
code from a certain part of the RelaxIS SDK, that contains various helpful math related functions. One
of these is complex number math in the class Complex. It implements most common math functions
for complex numbers. An implementation of above formula would look like this:
Basic SDK Tutorial – rev1.1 – 2024/09
RelaxIS - Impedance Spectrum Analysis © 2013-2024 Jens Wallauer
rhd instruments GmbH & Co. KG, Otto-Hesse-Str. 19/T3, 64293 Darmstadt
Tel.: 06151-8707187, E-Mail: info@[Link]
Public Overrides Function CalculateImpedance(frequency As Double,
parameters() As Double, index as Integer) As Complex
Dim w As Double = 2 * [Link] * Frequency
Dim i As Complex = [Link]
Dim Q As Double = parameters(index + 0)
Dim alpha As Double = parameters(index + 1)
Dim Result As Complex = 1 / (Q * (i * w)^alpha)
Return Result
End Function
The first four lines basically just create new variables that store the part after the equality sign. These
are mainly created for readability. Notice that the parameters variable is a so-called Array,
meaning a list of multiple values. These values are accessed using an array index, starting with zero,
that is enclosed in brackets behind it. For the first parameter belonging to this element in the overall
model we use the array index index + 0, in order to take the starting index into account.
The variable Result is then defined using the variables created before. Note that the variable i is
defined as the imaginary unit in the definitions, so the math will also result in a complex value that is
stored in the Result variable. The last line then returns the calculated value to the caller of the
function.
The main advantage of creating the circuit element in this manner is that you are completely free in
the way you actually retrieve your impedance value. Not in all cases is the calculation based on a simple
formula. For example, the Transmission Line circuit elements often use recursion to calculate the value.
You can add additional functions to the class to calculate intermediate results, or you can even
reference and use other code libraries.
Step 4 – Checking and Compiling the Code
Once the code is completed, it has to be checked for errors by compiling it. This means that the code
is turned into something that the computer can actually understand and run.
You can check the code for errors by clicking on Main > Compile > Check Code in the main
ribbon. If you have entered all code correctly the Compilation Log window will show a
message like
Compilation started on 11.02.2016, 22:56:57
Compilation successful.
If there is incorrect code in your plugin the log will show a message containing the line number that
the error occurred in as well as an error message that describes what is wrong. Please check the code
at the given line and correct the error.
Optionally (see below), once all errors are fixed, click the Main > Compile > Compile button.
Select a name for the DLL file to create (or keep the suggested one) and click on Save. The
code is compiled and saved under the given name. See the notes about the DLL location in
Step 5 below.
Basic SDK Tutorial – rev1.1 – 2024/09
RelaxIS - Impedance Spectrum Analysis © 2013-2024 Jens Wallauer
rhd instruments GmbH & Co. KG, Otto-Hesse-Str. 19/T3, 64293 Darmstadt
Tel.: 06151-8707187, E-Mail: info@[Link]
Please note, that you are not able to compile the plugin, when RelaxIS or the Circuit Simulator is started
and the plugin is already loaded by RelaxIS. In this case please close the program(s) first and then
compile the plugin.
Compilation is optional! If the plugin is not compiled, but the plugin is saved into the plugin folder as
an XML document (see Step 5), RelaxIS will automatically compile the code on the fly during startup.
Hence, the compilation step can be skipped.
Step 5 – Saving the Plugin Code
The .DLL file can’t be easily edited, as it no longer contains all your original code. To make
changes to the plugin later, you should save the code as well. Click on Main > Program >
Save As to save it as an XML document. You can load this document later by using the Main
> Program > Open button. If RelaxIS finds an XML file without associated DLL file, it will
compile the code saved in it automatically during startup.
Please note: Only XML or DLL files saved in the folder %UserData%\Plugins are loaded by RelaxIS
(default: My Documents\RelaxIS\3.0\Plugins). Make sure you save your plugins in that folder, or they
will not be loaded by RelaxIS.
Step 6 – Testing the Plugin
Plugins are (re)loaded when RelaxIS starts. To test the plugin you therefore need to close
and restart RelaxIS.
Whenever a new or changed plugin is detected, before loading it RelaxIS will inform you
about the change and you need to manually accept the plugin. Please check that the plugin you accept
is really your plugin. Plugins can execute arbitrary code, so make sure that you trust all the plugins you
decide to load.
Afterwards when RelaxIS has loaded, please select Main > Settings from the main ribbon and navigate
to the Plugins section. Under the Circuit Elements plugin type, you should now find the newly created
plugin with the information you defined in the properties.
Basic SDK Tutorial – rev1.1 – 2024/09
RelaxIS - Impedance Spectrum Analysis © 2013-2024 Jens Wallauer
rhd instruments GmbH & Co. KG, Otto-Hesse-Str. 19/T3, 64293 Darmstadt
Tel.: 06151-8707187, E-Mail: info@[Link]
You can also try and use the plugin in circuits with the abbreviation you defined and compare the
results to the other implementation of the constant phase element.
Summary
This tutorial described the basic steps to write a plugin using the RelaxIS SDK. It used the example of a
circuit element and showed how to implement the default properties and functions in the Visual
[Link] programming language. It also showed how to compile, save and test the new plugin.
Basic SDK Tutorial – rev1.1 – 2024/09
RelaxIS - Impedance Spectrum Analysis © 2013-2024 Jens Wallauer