Single Degree of Freedom Gearbox DLL Interface Specification
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.
| Name : DLL_GBX |
| Return value: None |
| Arguments: |
Data type |
Array length |
Description |
| Arg1 |
4-byte
integer |
10 |
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 |
All arguments are passed by pointers, so for example Arg1 is a pointer to the start of an array of ten 4-byte integers, Arg2 is a pointer to a single 8-byte (double-precision) floating point number, 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. |
| 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 |
| 9 |
From DLL |
0 means OK, <0 means Abort |
| 10 |
To DLL |
Unique number representing the number of brakes that
have been activated. Up to 3 can be defined by the user.
The decimal brake flag is \(\Sigma_i 2^{i-1} B_i\),
where \(B_i\) is the state of shaft brake (0=off, 1=on).
May be used by the DLL if the Bladed shaft brake
position is within the scope of the DLL. |
If Arg1(9) is returned with a non-zero value an explanatory message
(terminated by a null character) should be returned in Arg8.
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. |
| Elements of Arg5 REAL*8 array |
| 1 |
To/From
DLL |
Nominal overall gearbox ratio between input and output
shaft. If the value passed by Bladed is not
correct, the DLL should communicate this using Arg1(9)
and Arg8, and substitute the correct value in the case
that Arg1(9) is not set negative. |
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 |
Initial Conditions refine flag for each state.
This is normally 0 but may be set to 1 to request Bladed
to minimise the state derivative during the initial
conditions calculation at the start of a dynamic
simulation. |
| 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 (\(\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 = 3 (Number of variables from DLL) |
| 4 |
|
Reserved for future developments |
| 5 to
Nx+4 |
From DLL |
0 = State disabled; 1 = State enabled |
| Elements of Arg5 REAL*8 array |
| 1 |
To DLL |
Low-speed (input) shaft angular position (rad) |
| 2 |
To DLL |
High-speed (output) shaft angular velocity (rad/s) |
| 3 |
To DLL |
High-speed (output) shaft torque (Nm) |
| 4 |
To DLL |
Brake applied torque if applicable |
| 5 |
To DLL |
Loss Torque if applicable |
| Elements of Arg6 REAL*8 array |
| 1 |
From DLL |
High-speed (output) shaft angular position (rad) |
| 2 |
From DLL |
Low-speed (input) shaft angular velocity (rad/s) |
| 3 |
To/From
DLL |
Low-speed (input) shaft torque (Nm) |
| 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 |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
Nu = 4 (Number of input variables to DLL) |
| 3 to
Nx+2 |
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 |
Low-speed (input) shaft torque (Nm) |
| 2 |
To DLL |
High-speed (output) shaft torque (Nm) |
| 3 |
To DLL |
Brake applied torque if applicable (Nm) |
| 4 |
To DLL |
Loss torque if applicable (Nm) |
| Elements of Arg7 REAL*8 array |
| 1 to Nx |
From DLL |
State derivatives |
| Nx + 1
to
Nx + 2 |
From DLL |
LSS and HSS acceleration |
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, which returns the values of variables \(\bvector{y} (\bvector{y} = \bmatrix{C} \bvector{x} + \bmatrix{D} \bvector{u}_{in})\) that are required by Bladed.
| Elements of Arg3 INTEGER array |
| 1 |
To DLL |
Nx |
| 2 |
To DLL |
Nin = 2 |
| 3 |
To DLL |
Ny = 4 (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 |
Brake applied torque if applicable (Nm) |
| 2 |
To DLL |
Loss torque if applicable (Nm) |
| Elements of Arg7 REAL*8 array |
| 1 |
From DLL |
Low-speed (input) shaft angular position (rad) |
| 2 |
From DLL |
Low-speed (output) shaft angular velocity (rad/s) |
| 3 |
From DLL |
High-speed (input) shaft angular position (rad) |
| 4 |
From DLL |
High-speed (output) shaft angular velocity (rad/s) |
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 = 4 |
| 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 |
Low-speed (input) shaft torque (Nm) |
| 2 |
To DLL |
High-speed (output) shaft torque (Nm) |
| 3 |
To DLL |
Brake applied torque if applicable (Nm) |
| 4 |
To DLL |
Loss torque if applicable (Nm) |
| 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 = 4 |
| 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 |
Low-speed (input) shaft torque (Nm) |
| 2 |
To DLL |
High-speed (output) shaft torque (Nm) |
| 3 |
To DLL |
Brake applied torque if applicable (Nm) |
| 4 |
To DLL |
Loss torque if applicable (Nm) |
| 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 = 4 |
| 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 |
Low-speed (input) shaft torque (Nm) |
| 2 |
To DLL |
High-speed (output) shaft torque (Nm) |
| 3 |
To DLL |
Brake applied torque if applicable (Nm) |
| 4 |
To DLL |
Loss torque if applicable (Nm) |
Last updated 28-08-2024