PSS SINCAL Models
Page 1 of 9
Interfaces for Use of DLLs in BOSL Models
Models
The BOSL Interpreter of the PSS SINCAL Platform independently executes models such as in the schema shown and makes it possible for the calculation cores of the
PSS products to interact with the models via the available interfaces by means of input and output signals.
Besides the native XMAC or MAC models created with the Graphical Model Builder (GMB) in ASCII code format, integrated subsystems or subroutines containing a
DLL (Dynamic Link Library) can also be included. These DLL files can be implemented and compiled by the user in other programming languages (e.g. c, c++ etc.), or
generated through the use of automatic code generation from other software tools (e.g. MATLAB/Simulink) and then easily integrated in the XMAC or MAC models,
such as shown in the following two illustrations.
The internal structure of this type of DLL does not have to be known. This feature has the following benefits:
l
Protection of intellectual property in a DLL subsystem (black box)
l
Reproducibility of the model behavior results in different software and simulation environments which can integrate the generated DLL accordingly
l
Creation of reusable function blocks for use in different models
l
Use of complex data structures, enhanced possibilities to input and output data in/out of the model, as well as concepts for coupling simulations (e.g. using
concepts such as "Shared Memory" or "Named Pipes").
The following describes the two interfaces IEC DLL and EXTERN DLL and shows how these DLLs can be used and assigned parameters in BOSL models. The
following sections refer to the example network (Example DLL) as an illustration.
Related Links
l
IEC DLL (IEC 61400-27-1)
l
EXTERN DLL
IEC DLL (IEC 61400-27-1)
Models - Interfaces for Use of DLLs in BOSL Models
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 2 of 9
The structure and the format of this DLL interface, as well as the header required are described in the IEC 61400-27-1:2015 standard (Appendix F: "Generic Software
Interface for Use of Models in Different Software Environments"). The generic software interface allows the independent use of the DLL in different software
environments and models created by the equipment manufacturers in their own software environment. The Extended Simulation Environment interface (ESE interface)
is supported by the BOSL Interpreter and thus allows the integration of one or multiple standard compliant DLLs in the BOSL models.
The description of the interface in this documentation and in the supplied example is based on c code. There are furthermore no restrictions to the creation of DLL
subsystems based on implementations in other programming languages (e.g. Fortran, c++, Python, …).
The description of the IEC DLL as a block diagram is shown in the following illustration. The parameters are scalar. However, input and output signals can be one(width = 1) or multi-dimensional arrays (width > 1).
Related Links
l
Structure and Functions of the IEC DLL
l
Embedding a IEC DLL in a Model
l
Application Example of a Model with an IEC DLL Subsystem
Structure and Functions of the IEC DLL
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1)
To support the interface, the IEC DLL has structures containing information on the DLL as well as information describing the inputs, outputs and parameters. It also
provides functions that are called by the simulation environment in order to integrate the DLL in the simulation sequence.
The structures of the DLL include the following information that is required for the correct integration of the DLL in a model:
l
General information on the model (name, version, description, …)
l
Information for sampling (step width)
l
Number of inputs, outputs and pointers to the signal descriptions
l
Parameters of the model, limit values and pointers to the parameter descriptions
l
Number and quantity of states and variables
l
Switches for indicating supported calculation methods (power flow, RMS, EMT)
l
Additional equations and extensions (optional)
The appropriate structure of the c code for the inputs and parameters is illustrated in the example below.
The complete list of data structures and functions of the ESE interface are described in detail in the standard and can also be viewed in the implementation (source code)
of the example supplied (see chapter GMB Model with DLL Subsystems in the Examples Electrical Networks Manual.
During the individual steps of the simulation (initialization, power flow, simulation, …) the appropriate functions of the DLL are called by the simulation environment.
The sequence of function calls of the ESE interface is illustrated in the following program extract. An IEC DLL is thus treated by the BOSL Interpreter according to this
sequence.
// --- Initialization --S = Model GetInfo()
// Static model information to configure the environment.
M = Model_Instance(Solver, Ta) // Create instance, use internal (1) or external (0) solver,
// set sample time.
Model_CheckParameters(M)
// Check parameters.
// --- LoadFlow --LoadFlowIteration: {
Model_Loadflow(M)
}
Model_Initialize(M)
// Number of iterations depends on power flow solver.
// Calculate outputs of power flow function.
// Reset and initialize the states.
// --- Simulation in time domain --SimulatlonLoop: {
Model_Outputs(M, 1)
// Calculate system outputs on major time step (1).
Model_Update(M)
// Update discrete states (and continuous states.
// if internal solver used).
IntegrationLoop: {
// Only needed if external solver is used.
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 3 of 9
Model_Derivatives(M) // Calculate continuous state derivatives.
IterationLoop: {
Model_Outputs(M, 0) // Calculate system outputs on minor time step (0).
Model_Derivatives(M) // Calculate continuous state derivatives.
}
}
}
Model Terminate(M)
// Delete the instance.
The use of sampling time and frequency is an important point in the integration of subroutines/subsystems in a model. Two options are available for the BOSL
Interpreter for configuring the sampling time of a DLL block for the IEC DLL. A description of the options is provided in the chapter Use with the Sampling Time Step.
Embedding a IEC DLL in a Model
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1)
The special DLL_IEC block enables the use of an IEC DLL as one or several subsystems in a BOSL model. The following describes the concept of the integration up
to the complete workflow of the embedding.
Related Links
l
Concept of the Integration
l
Use of Signal Arrays
l
Call of the DLL in the Power Flow
l
Use with the Sampling Time Step
l
Search Path for an IEC DLL
l
Integration of an IEC DLL in an XMAC Model in the GMB
l
Integration of an IEC DLL in a MAC Model (ASCII)
Concept of the Integration
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1) - Embedding a IEC DLL in a Model
The concept of the integration of this DLL type is based on the use of two model files: The inner macro and the outer macro. The outer macro here is the BOSL model
edited by the user in the GMB or the text editor.
The inner macro is a MAC file (ASCII), which links the DLL file (.dll) to the inputs and outputs and transfers the parameters. The DLL itself contains the appropriate
system behavior of the subsystem; e.g. as shown in the following illustration, the simplified simulation of an active and reactive power control circuit.
The MAC file (for the structure of this example, see the illustration below) must as the inner macro have the same name as the DLL itself (e.g. Example_DLL.mac for
the DLL Example_DLL.dll) and be located in the same directory. The (automatic) generation of the inner macro file is described in the relevant sections of the
documentation describing the process for integrating in the MAC Models or XMAC Models (GMB).
The elements of the inner macro are described in the following table.
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 4 of 9
Sections Content below the section definition
[Version] Version information (from structure StaticExtSimEnvCapi, the BOSL Interpreter only supports DLL subsystems that were created for ESE interface version
number 0.7.0.3 or higher)
[Link]
List of the input signals of the DLL (prefix "IMPORT_") and list of the output signals of the DLL (prefix "EXPORT_")
[Data]
Name, default values of the parameters, limit values and descriptions.
Note: The default values for the parameters are only used if parameters are not overwritten by the outer macro.
[Equations]Additional equations for parameters (optional)
[End]
Lines
Name of the DLL (incl. file suffix)
HZ1: Sampling time step (#DT)
HZ1, HZ2, …: Parameter (#P1, …)
(optionally other lines with parameters in HZ1, …)
The graphic below shows the inner macro of the IEC DLL used in the application example.
In the outer macro, the inner macro is then embedded as a module once or multiple times in the context of the inputs, outputs, equations and model parameters. These
are defined as local parameters which are valid for the next macro call and which can overwrite preset default values (with @DEFAULT@).
Use of Signal Arrays
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1) - Embedding a IEC DLL in a Model
The modelling of signals in BOSL is based on scalar numerical signals (type double). If the DLL contains input and output signals in the form of arrays, these are
converted to individual scalar signals which can then be connected in the model with scalar signals.
Call of the DLL in the Power Flow
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1) - Embedding a IEC DLL in a Model
If the value of the LoadFlowFlag is set to "1", it is assumed that the DLL also provides a function that is called in the power flow. When the DLL is embedded, this is
checked and set via the "yes/no" attribute for "Loadflow" in the [Version] section.
Use with the Sampling Time Step
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1) - Embedding a IEC DLL in a Model
The DLL can be used in the simulation in two different variants in relation to the sampling time step. The difference is in whether the integrated DLL has the ability to
call itself or depends on the call of the outer macro. A deviation from the two methods particularly occurs in the following cases:
l
if the BOSL Interpreter calls the outer macro several times as part of the Korrektor procedure,
l
if discontinuities are detected and therefore only half a time step is calculated, or
l
if a user-defined step width adjustment is carried out in a simulation run.
Variant 1: FixedTimeStep = yes (per Default)
The standard definition of the DLL subsystem requires a fixed time step of the DLL, for which the value itself contains this as a property (Property:
FixedStepBaseSampleTime). To ensure the call is executed with a fixed time step the integrated DLL is treated as a sampling controller (see chapter Sampling
Controllers, Equidistant Time Step in the PSS NETOMAC Procedure Manual) with the appropriate sampling frequency and at the end of each complete simulation step.
The value of the sampling rate is outlined in the following illustration.
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 5 of 9
As soon as the DLL is embedded in the GMB (when the inner macro is generated) the value (property: FixedStepBaseSampleTime) is read out (red arrow) and is set as
a default value for the #DT parameter in the inner macro. The value entered for #DT is then used as the sampling time step for calling the DLL as a sampling controller
in the inner macro (blue arrow). At the same time, it is transferred to the DLL as input Ta, so that this can be used internally (e.g. for the implementation of integrator
blocks).
The value for #DT can be overwritten from the outer macro (green arrow), in order for example to use the value of the fixed simulation time step #SDT also as the value
for #DT by means of an equation.
In this variant, a possible variation of the time step length in PSS NETOMAC during the integration no longer has an effect on the sampling of the DLL. This can cause
the call of the DLL to no longer be synchronous with the time step (changing during the simulation). In this case, the input and output values of the DLL are interpolated
in order to calculate a value for these signals for the variable time step of the simulation.
Variant 2: FixedTimeStep = no (Use of the Time Step of the Outer Macro)
To avoid the behavior described in variant 1, the time step of the outer macro can also be used as the time step for calling the DLL, so that the call of the outer macro
and the DLL integrated in the inner macro are synchronized. This makes it possible to avoid the asynchronous call and the interpolation.
However, this requires an implementation of the DLL that supports the call with the variable time step length by adjusting the internal calculation. This must be ensured
by the DLL developer.
In order to use this variant, it is possible to manually change the value for FixedTimeStep in the inner macro (.mac) to "no" after its generation.
Search Path for an IEC DLL
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1) - Embedding a IEC DLL in a Model
The DLL file must be stored in the same directory as the MAC file of the inner macro.
The search for the DLL and the inner macro file is carried out by default in the directory containing the outer macro. It is also possible here to separate 32-bit DLLs
from the 64-bit DLLs by using the subdirectories "DLL" and "DLL64". These must store both the inner macro as well as the corresponding 32-bit or 64-bit DLL.
Integration of an IEC DLL in an XMAC Model in the GMB
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1) - Embedding a IEC DLL in a Model
The special IEC DLL block is used to integrate an IEC DLL in the GMB (XMAC model).
For this the Insert Special Block function is activated in the Model Editor by clicking the appropriate button in the toolbar.
DLL IEC is selected in the selection list.
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 6 of 9
This opens a dialog box for opening files. After navigating to the directory of the DLL and selecting the DLL file, an IEC DLL block is generated in the Model Editor.
The inner macro is generated automatically by the GMB as a MAC file in the directory of the DLL file. Suitable write permissions must be obtained by the user
beforehand. The file name of the MAC file is taken here from the name of the DLL file. Already existing MAC files with this name in the directory are overwritten.
The connections of the inputs and outputs are then made in the input screen form in the Topology tab and the parameters are entered in the Data tab.
Note: The # names of the variables can be used directly in order to link variables from the parameter list of the model (outer macro) with the DLL
parameters.
Integration of an IEC DLL in a MAC Model (ASCII)
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1) - Embedding a IEC DLL in a Model
To manually integrate an IEC DLL in a MAC file (outer macro), the conversion and thus generation of the inner macro is carried out manually in the native GUI of
PSS NETOMAC.
The generation of the inner macro can be started via Tools – Conversations – Convert IEC DLL.
This opens a dialog box for opening files. After navigating to the directory of the DLL and selecting the DLL file, the MAC file (inner macro) is automatically
generated in the same directory. Suitable write permissions must be obtained by the user beforehand. The inner macro can then be integrated as a module in any outer
macro (.mac). The following illustration shows an example of the integration in the code of a MAC file.
Application Example of a Model with an IEC DLL Subsystem
Models - Interfaces for Use of DLLs in BOSL Models - IEC DLL (IEC 61400-27-1)
An application example of a model with an integrated IEC DLL subsystem is provided with the installation and is described in the Examples Electrical Networks
Manual, chapter GMB Model with DLL Subsystems.
EXTERN DLL
Models - Interfaces for Use of DLLs in BOSL Models
The structure of the EXTERN DLL interface is specifically designed for the BOSL Interpreter and does not follow any standard requirement (cf. IEC DLL). The
interface provides a simple way to integrate externally implemented subroutines in a model or to link the model to other external processes via the subroutine (and
synchronize these processes via the shared subroutine).
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 7 of 9
The EXTERN BOSL block makes it possible to integrate a DLL of type EXTERN DLL both in XMAC models (GMB) as well as in MAC models (ASCII). The
EXTERN block is called directly like all other blocks during the execution of a model. As the call of the DLL is not wrapped (without an additional inner macro and
sampling controller as with IEC DLL), the integration in the processes and the sampling is carried out directly from the model (outer macro), in which the DLL is
integrated. It is then up to the user whether the DLL inside a model is treated like a sampling controller with a fixed time step in the simulation process, runs through the
correction process or is called at the end of a simulation step.
Related Links
l
Structure and Functions of the EXTERN DLL
l
Embedding an EXTERN DLL in a Model
l
Application Example of a Model with an EXTERN DLL Subroutine
Structure and Functions of the EXTERN DLL
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL
No internal static structures with information on the DLL exist for an EXTERN DLL. The DLL of type EXTERN DLL (unlike the IEC DLL) provides a single function
(EXTERN) that can be externally called, which is then called by the BOSL Interpreter.
When the EXTERN function is called, the following parameters are transferred, which can be used in the DLL to enable an implementation according to the calculation
type as well as a time response and much more.
Parameter
Description
char* psName Name of the calling function
(second line of the EXTERN block, column NAME3)
int* piNumber Index (consecutive numbering, if several DLLs of type EXTERN are used)
int* piInMax Length of the input arrays X0, X1, which are assigned to the block in the model
double* X0
Input values of the previous time step: X0 = X(T0 = t – DT)
double* X1
Input values of the current time step: X1 = X(T1 = t)
double* CX Inputs for complex calculations (can be used for frequency response)
int* piOutMax Length of the output arrays Y0, Y1, which are assigned to the block in the model
double* Y0
Output values of the previous time step/power flow: Y0 = Y(T0 = t – DT)
double* Y1
Output values of the current time step: Y1 = Y(T1 = t)
double* CY Outputs for complex calculations (can be used for frequency response)
int* piDatMax Length of the DataArray (multiple of 9), which is assigned to the block in the model
double* Dat Data array
double* T0
piMode = 1 and 2: Simulation time in [s]
piMode = 3: Saves t in [s] of the previous time step (in case of discontinuities)
double* T1
piMode = 1 and 2: Time step in [s]
piMode = 3: Simulation time in [s]
int* piMode PSS NETOMAC calculation mode:
1 = Initialization
2 = Power flow
3 = Simulation
4 = Reset
int* piContinueCan be used for the implementation of snapshots (value is not set by PSS NETOMAC)
int* piExtMax Length of the StringData array
char* psExt
Array StringData
strExts(1): PSS NETOMAC installation path
strExts(2): Path of the current NET file
strExts(3): Name of the current NET file
int iLenName Number of characters of the name (always 8 char)
int iLenExt
Number of characters in the string (always 500 char)
Embedding an EXTERN DLL in a Model
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL
Inside a model, a DLL of type EXTERN DLL is integrated via the interface directly in the model as a subroutine.
Related Links
l
Concept of the Integration
l
Use of Signal Arrays
l
Call of the DLL
l
Sampling and Time Step
l
Search Path for an EXTERN DLL
l
Integration of an EXTERN DLL in an XMAC Model in the GMB
l
Integration of an EXTERN DLL in a MAC Model (ASCII)
Concept of the Integration
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL - Embedding an EXTERN DLL in a Model
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 8 of 9
The DLL is integrated directly in a model by connecting the input and output signals. The number of inputs and outputs of the DLL must be known to the user as the
DLL itself does not provide any information about this that can be called up.
The parameters (e.g. #t1 and #t2) of the subroutine can be transferred as inputs and also as constants. The following primarily covers the first option.
Use of Signal Arrays
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL - Embedding an EXTERN DLL in a Model
The use of signal arrays is not implemented in the EXTERN DLL interface. The signals in the BOSL are scalar numerical values (double data type). Inputs and output
signals which are transferred to the DLL therefore comply with this data type.
Call of the DLL
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL - Embedding an EXTERN DLL in a Model
To enable a suitable implementation in the DLL of the behavior of the subsystem for the different calculation types/steps, the call of the DLL by the BOSL Interpreter
always transfers the current calculation mode (piMode). The numbers for the piMode parameter are shown in the following table.
piModeDescription
1
Initialization
2
Power flow
3
Simulation
4
Reset
There are four types of call. Before and at the beginning of the calculation, a DLL of type EXTERN DLL is called during the initialization and at the end with the
release (in order to release the allocated memory). During the calculation, the subroutine is called in the power flow (however, only if the model is also called in the
power flow) and in the simulation (stability, EMT) and piMode transferred accordingly.
Note: The BOSL Interpreter does not check a DLL of type EXTERN DLL for whether the required functions (e.g. adequate implementation for the power
flow) are provided. This must be taken into consideration by the DLL developer and documented, in order to enable the correct use of the DLL (without
source code).
The DLL subroutine is called in the power flow calculation provided that the model containing it is also called in the power flow. The value for piMode then enables a
suitable function for the behavior in the power flow to be implemented in the DLL.
Note: In the power flow, the input and output values of the DLL are exchanged with the model via the signals of the values for the previous time step (X0
and Y0).
Sampling and Time Step
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL - Embedding an EXTERN DLL in a Model
The sampling of the DLL is synchronized with the model containing it (outer macro).
Note: Depending on the integration time of the model (integration type), the DLL is called several times if the controller integration "During the network
iteration" is carried out. The use of a multiple DLL call must be considered in the implementation of the DLL (e.g. for blocks with a time response inside
the DLL).
The calculation of the time step when the DLL is called and its length can be carried out inside the DLL based on T0 and T1.
Search Path for an EXTERN DLL
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL - Embedding an EXTERN DLL in a Model
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
PSS SINCAL Models
Page 9 of 9
The search for the DLL file is carried out by default in the directory in which the calling macro is located. It is also possible here to separate 32-bit DLLs from the 64-bit
DLLs by using the subdirectories "DLL" and "DLL64". These must store the corresponding 32-bit or 64-bit DLL.
Integration of an EXTERN DLL in an XMAC Model in the GMB
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL - Embedding an EXTERN DLL in a Model
The special EXTERN DLL block is used to integrate an EXTERN DLL in the GMB (XMAC model).
For this the Insert Special Block function is activated in the Model Editor by clicking the appropriate button in the toolbar.
DLL EXTERN is selected in the selection list.
An EXTERN DLL block is generated in the model graphic. The marking points of the block for connecting signals are not displayed until the input and output signals
are entered in the input screen form. The file name (including file suffix *.dll) is entered in the input screen form of the block in the DLL File field of the Topology tab.
The name of the block (up to 8 freely selectable characters, then transferred as psName at the call) is entered in the Block name field.
The signals of the model are connected to the DLL in the Inputs and Outputs tabs. After the entry, the marking points for creating the graphical connections to the
inputs and outputs of the other blocks are provided for the signals.
Note: The number of input and output signals can only be provided for the user in a documentation or by means of the source code of the DLL as they are
not read from the DLL.
Integration of an EXTERN DLL in a MAC Model (ASCII)
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL - Embedding an EXTERN DLL in a Model
The manual integration of a DLL of type EXTERN DLL in a MAC model is carried out with the EXTERN block. The description of the EXTERN block is provided in
the PSS NETOMAC Procedure Manual in chapter Control Blocks, Special Functions under EXTERN – User Defined Subroutine.
Application Example of a Model with an EXTERN DLL Subroutine
Models - Interfaces for Use of DLLs in BOSL Models - EXTERN DLL
An application example of a model with an integrated EXTERN DLL subroutine is provided with the installation and is described in the Examples Electrical Networks
Manual, chapter GMB Model with DLL Subsystems.
file:///C:/Users/TS23/AppData/Local/Temp/~hh42F2.htm
14/04/2022
