Generator DLL Introduction
Users may select the External DLL option to indicate that a user-defined DLL will be used to define the generator model. The user-defined model provides generator air-gap torque and electrical power outputs to Bladed. During a simulation, the air-gap torque is applied to the Bladed turbine drivetrain model; therefore, the mechanical equations of motion of the generator, to describe the rotation of the generator rotor, should not be included in the DLL. Note that any electrical faults should be included within the DLL. The dynamics in the DLL may be expressed in state-space form.
To use the feature specify the DLL file path. The Calling convention can be set to either __cdecl or __stdcall. If desired, enter any User Data in the free-format field provided next to DLL parameter data. This data will be placed in a text file whose location is passed to the DLL, so that the DLL may read this information if desired. This is useful for passing parameter values written in the project file to the DLL during initialisation.
The following sections describe the DLL interface in detail. A simple example DLL source code in C++ is provided in the Code Samples folder of your Bladed installation.
Interface Specification
The dynamic link library entry point from Bladed is a single procedure called DLL_GENER (upper case) with eight arguments and no return value. All variables exchanged between Bladed and the DLL are in strict SI units.
| Name : DLL_GENER |
| Arguments: |
Data type |
Array length |
Description |
| Arg1 |
4-byte
integer |
11 |
See below |
| Arg2 |
8-byte
real |
1 |
Time (s) since start of
simulation |
| Arg3 |
4-byte
integer |
Arg1(3) |
See below |
| Arg4 |
1-byte char |
Arg1(4) |
See below |
| Arg5 |
8-byte
real |
Arg1(5) |
See below |
| Arg6 |
8-byte
real |
Arg1(6) |
See below |
| Arg7 |
8-byte
real |
Arg1(7) |
See below |
| Arg8 |
1-byte char |
Arg1(8) |
Message returned by DLL |
In general, the arguments are pointers to the start of an array. For example Arg1 is pointer to the first element of ten 4-byte integers, Arg2 is a pointer to a single 8-byte real, and Arg4 is a pointer to an array of one-byte characters, the number of elements in the array being given by the fourth element of Arg1. The other elements of Arg1 are defined as follows:
| Elements of Arg1 INTEGER array |
| 1 |
To DLL |
DLL interface version number = 4301 |
| 2 |
To DLL |
Call type: 1 to 9. |
| 3 |
To DLL |
NI = Size of Arg3 |
| 4 |
To DLL |
NC = Size of Arg4 |
| 5 |
To DLL |
NR1 = Size of Arg5 |
| 6 |
To DLL |
NR2 = Size of Arg6 |
| 7 |
To DLL |
NR3 = Size of Arg7 |
| 8 |
To DLL |
NC1 = Size of Arg8. |
The procedure is called in different ways by Bladed, depending on the call type given by element 2 of Arg1. Arg2 always contains the time in seconds since the start of the simulation. Arg3 to Arg7 depend on the value of the Call type, Arg1(2), as described below. Any arguments not mentioned are not used in that call, but must still be present.
The number of characters returned in Arg4 and Arg8 must never exceed NC and NC1 respectively.
Call Type 1: Initialisation
This call initialises the DLL model (using any constants which might come from the Bladed model) and returns the required number of integrator states and output variables.
| Elements of Arg3 INTEGER array |
| 1 |
From DLL |
Nx = Number of states to integrate |
| 2 |
From DLL |
Nout = Number of variables to output |
| Elements of Arg4 CHAR*1 array |
| 1
to
NC(max) |
To DLL |
Name of Parameter File and Verification File,
each terminated by a semi-colon (;). If desired
the DLL may open and read the Parameter File,
which contains any user-defined data. The
Verification File must be opened FOR
APPENDING ONLY, and can be used to keep a
record of the DLL parameters. This will be the
$VE file for the simulation, so it is
important not to overwrite the data which it
already contains. If opened, this file must
be closed again before the DLL returns. |
Call Type 2: State Definition
This call returns the names and absolute tolerances of the integrator
states required by the DLL.
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nx |
| 2 to
Nx+1 |
From DLL |
Auto-initialisation flag for each state:
normally 0, but set to 1 if the state
derivative must be zero in the steady state and
you wish to include this state in the
Bladed initial condition refinement step. |
| Elements of Arg4 CHAR*1 array |
| 1 to
NC(max) |
From DLL |
"State name:Units;" for each state |
| Elements of Arg5 REAL*8 array |
| 1 to
Nx |
From DLL |
Absolute tolerances of the integrator states |
Call Type 3: Output Variable Definition
This call returns the names and units of variables from the DLL to be output in time history output from Bladed (i.e. \(\bvector{y}_{out}\) from the second state-space equation \(\bvector{y}_{out} = \bmatrix{C}_{out} \bvector{x} + \bmatrix{D}_{out} \bvector{u}\)).
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nout |
| Elements of Arg4 CHAR*1 array |
| 1 to
NC(max) |
From DLL |
"Variable name:Units;" for each output
variable |
Call Type 4: Initial Conditions
This call executes one step of the initial conditions iteration, and
also returns the initial values of the states (assuming everything is in
the steady state).
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
NinInit = 5 (Number of variables to DLL) |
| 3 |
To DLL |
NoutInit = 2 (Number of variables from DLL) |
| 4 |
To DLL |
0 = trial call, 1 = final call |
| 5 to
Nx+4 |
From DLL |
0 = State disabled; 1 = State enabled |
| Elements of Arg5 REAL*8 array |
| 1 |
To DLL |
Generator speed (rad/s) |
| 2 |
To DLL |
Generator angular position (rad) |
| 3 |
To DLL |
Torque demand (Nm) |
| 4 |
To DLL |
Network voltage disturbance (fraction of nominal) |
| 5 |
To DLL |
Network frequency disturbance (fraction of nominal) |
| Elements of Arg6 REAL*8 array |
| 1 |
From DLL |
Air-gap torque (Nm) |
| 2 |
From DLL |
Electrical power output to sensor (W) |
| Elements of Arg7 REAL*8 array |
| 1 to Nx |
From DLL |
Initial values of states if Arg3(4) = 1 |
| Nx+1
To
Nx+10 |
To/From
DLL |
User variables 1 to 10 |
| Nx+11
onwards |
To/From
DLL |
Additional user variables |
Call Type 5: State Derivatives
This call passes the current DLL state values and any required variables
derived from Bladed states to the DLL, which returns
the state derivatives \(\dot{\bvector{x}}\) calculated by the DLL.
| Elements of Arg3 INTEGER array (NI \(\geq\) Nx+2) |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
Nu = 5 (Number of input variables to DLL) |
| 3 to
Nx+2 |
To DLL |
0 = State disabled; 1 = State enabled |
| Elements of Arg5 REAL*8 array (NR1 \(\geq\) Nx+10) |
| 1 to Nx |
To DLL |
State variables |
| Nx+1
To
Nx+10 |
To/From
DLL |
User variables 1 to 10 |
| Nx+11
onwards |
To/From
DLL |
Additional user variables |
| Elements of Arg6 REAL*8 array (NR2 \(\geq\) Nu) |
| 1 |
To DLL |
Generator speed (rad/s) |
| 2 |
To DLL |
Generator angular position (rad) |
| 3 |
To DLL |
Torque demand (Nm) |
| 4 |
To DLL |
Network voltage disturbance (fraction of nominal) |
| 5 |
To DLL |
Network frequency disturbance (fraction of nominal) |
| Elements of Arg7 REAL*8 array (NR3 \(\geq\) Nx) |
| 1 to Nx |
From DLL |
State derivatives |
Call Type 6: Variables Required by Bladed
This call passes the current DLL state values and any required variables derived from Bladed states to the DLL. The user must then compute the values of variables \(\bvector{y}\) that are required by the Bladed linear model.
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
Nin = 5 |
| 3 |
To DLL |
Ny = 2 (Number of variables required) |
| 4 to
Nx+3 |
To DLL |
0 = State disabled; 1 = State enabled |
| Elements of Arg5 REAL*8 array |
| 1 to Nx |
To DLL |
State variables |
| Nx+1
To
Nx+10 |
To/From
DLL |
User variables 1 to 10 |
| Nx+11
onwards |
To/From
DLL |
Additional user variables |
| Elements of Arg6 REAL*8 array |
| 1 |
To DLL |
Generator speed (rad/s) |
| 2 |
To DLL |
Generator angular position (rad) |
| 3 |
To DLL |
Torque demand (Nm) |
| 4 |
To DLL |
Network voltage disturbance (fraction of nominal) |
| 5 |
To DLL |
Network frequency disturbance (fraction of nominal) |
| Elements of Arg7 REAL*8 array |
| 1 |
From DLL |
Air-gap torque (Nm) |
| 2 |
From DLL |
Electrical power output to sensor (W) |
Call Type 7: Output Variables
This call passes the current DLL state values and any required variables derived from Bladed states to the DLL, which returns the values of the output variables \(\bvector{y}_{out}\) that will be presented in the simulation time-history output.
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
Nu = 5 |
| 3 |
To DLL |
Nout |
| 4 to
Nx+3 |
To DLL |
0 = State disabled; 1 = State enabled |
| Elements of Arg5 REAL*8 array |
| 1 to Nx |
To DLL |
State variables |
| Nx+1
To
Nx+10 |
To/From
DLL |
User variables 1 to 10 |
| Nx+11
onwards |
To/From
DLL |
Additional user variables |
| Elements of Arg6 REAL*8 array |
| 1 |
To DLL |
Generator speed (rad/s) |
| 2 |
To DLL |
Generator angular position (rad) |
| 3 |
To DLL |
Torque demand (Nm) |
| 4 |
To DLL |
Network voltage disturbance (fraction of nominal) |
| 5 |
To DLL |
Network frequency disturbance (fraction of nominal) |
| Elements of Arg7 REAL*8 array |
| 1 to Nout |
From DLL |
Output variables |
Call Type 8: Discontinuity Check
This call asks the DLL whether a discontinuity has been passed. If so, the DLL has the option of specifying a particular step reduction. These calls may be ignored by the DLL if it does not model any discontinuities.
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
Nu = 5 |
| 3 |
To DLL |
0 means OK, <0 means need to step back |
| 4 to
Nx+3 |
To DLL |
0 = State disabled; 1 = State enabled |
| Elements of Arg5 REAL*8 array |
| 1 to Nx |
To DLL |
State variables |
| Nx+1
To
Nx+10 |
To/From
DLL |
User variables 1 to 10 |
| Nx+11
onwards |
To/From
DLL |
Additional user variables |
| Elements of Arg6 REAL*8 array |
| 1 |
To DLL |
Generator speed (rad/s) |
| 2 |
To DLL |
Generator angular position (rad) |
| 3 |
To DLL |
Torque demand (Nm) |
| 4 |
To DLL |
Network voltage disturbance (fraction of nominal) |
| 5 |
To DLL |
Network frequency disturbance (fraction of nominal) |
| Elements of Arg7 REAL*8 array |
| 1 |
From DLL |
Suggested time to step back to if Arg3(3) = -2 |
Call Type 9: Completed Step
This call tells the DLL that the time step is complete, so that a
discontinuous change to the dynamics can be implemented if required.
These calls may be ignored by the DLL if it does not model any
discontinuities.
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
Nu = 5 |
| 3 to
Nx+2 |
To/From
DLL |
0 = State disabled; 1 = State enabled |
| Elements of Arg5 REAL*8 array |
| 1 to Nx |
To/From
DLL |
State variables |
| Nx+1
To
Nx+10 |
To/From
DLL |
User variables 1 to 10 |
| Nx+11
onwards |
To/From
DLL |
Additional user variables |
| Elements of Arg6 REAL*8 array |
| 1 |
To DLL |
Generator speed (rad/s) |
| 2 |
To DLL |
Generator angular position (rad) |
| 3 |
To DLL |
Torque demand (Nm) |
| 4 |
To DLL |
Network voltage disturbance (fraction of nominal) |
| 5 |
To DLL |
Network frequency disturbance (fraction of nominal) |
Last updated 06-09-2024