Legacy External DLL Common Features
To customise the dynamics of certain turbine components the user may make use of a set of external DLL interfaces defined in Bladed. This includes the drive train DLL options such as the Single degree of freedom (DoF) gearbox DLL & 6DoF gearbox DLL, the generator DLL and the pitch actuator DLL. This section explains common features of the various external DLL interfaces.
Simple example DLL source codes in Fortran and C++ are provided in the Code Samples folder of your Bladed installation.
DLL Operating System Compatibility
The DLL may be written in any language which can be compiled to a Windows DLL or Linux SO. For dynamic simulation run on a Windows operating system a DLL or Dynamic Link Library must be compiled. Likewise dynamic simulation on a Linux operating system an SO or Shared Object must be compiled.
External DLL State-Space Model
For all DLL models, the dynamics in the DLL are defined in state-space form:
where \(\bvector{x}\) is a vector of state variables defined in the DLL, \(\bvector{u}\) and \(\bvector{u}_{in}\) are vectors of input variables defined below, \(\bvector{y}\) is a vector of output variables made during call type 6, and \(\bvector{y}_{out}\) is a vector of output variables defined in the DLL defined in call type 3 that are written to disk in call type 7.
Matrices \(\bmatrix{A}\), \(\bmatrix{B}\), \(\bmatrix{C}\), \(\bmatrix{D}\), \(\bmatrix{C}_{out}\) and \(\bmatrix{D}_{out}\) represent terms defined in the DLL, although they need not be defined explicitly as matrices, and need not be constant: in other words the dynamic model may be non-linear and time-varying, and discontinuous changes are allowed. The Bladed integrator will integrate the states \(x\); note however that the number of states defined in the DLL may be zero, in which case the DLL may use its own integrator, whether in continuous or discrete time, to integrate any dynamic equations it contains – this is known as co-simulation. If this is done it is important to realise that any dynamic coupling to the Bladed equations of motion will be lost, and this should therefore be done only for dynamics which do not couple strongly with the dynamics of the turbine modelled by Bladed. It is also important to realise that the variable time step integrator used by Bladed will make DLL calls at varying intervals of simulated time, and that the integrator trial steps, which result in call type 5 and call type 6 defined below, may step backwards in time as well as forwards, but will never step backwards further than the last completed integrator step which corresponds to call type 9 defined below. It is also possible to use a combination of “Bladed” and “co-simulation” states. Using the terms 'displacement' and 'velocity' as the last word in the state name for physical states that are part of a pair will help in the identification of states for the Campbell diagram.
External Interface Call Types and Call Arguments
At run time the procedure passes information between the DLL and Bladed via a series of arguments. These are referred to as Arg1, Arg2, and so on. The arguments can be doubles, array of characters, integers or double values. The procedure is called in different ways by Bladed and the definition of the arguments changes. This depends on the call type given by element 2 of Arg1 (Arg1(2)). Please see Table 1 for a list of all call types.
In general, Arg2 always contains the time in seconds since the start of the simulation. Then arguments such as 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.
Note that the documentation uses a 1-based indexing system to represent the first element. Different programming languages adopt either a 0-based or 1-based indexing convention for the first index. When coding the interface comply with the programming convention of the adopted language.
Table 1 - Definition of the interface call types controlled by Arg1(2)
| Arg1(2) | Call types | Purpose |
|---|---|---|
| 1 | Initialisation | Size arrays such as number of states to integrate and number of variables to output. Read user-defined data. |
| 2 | State definition | Specify the names and units of states \(\bvector{x}\) to integrate. |
| 3 | Output variable | Specify names and units of all output variables to log during the simulation. These are the values \(\bvector{y}_{out}\). |
| 4 | Initial conditions | Define initial value of certain state space model states. |
| 5 | State derivatives | Use state-space model to return state derivatives to Bladed for integration of state variables. These are the values of \(\dot{\bvector{x}}\). |
| 6 | Variables required | Compute the output variables of the of user-defined states \(\bvector{y}\). |
| 7 | Output variables | Log output variables \(\bvector{y}_{out}\). |
| 8 | Discontinuity step | Check for discontinuity and request a restep. |
| 9 | Completed step | Point at which calculation has reached end of a time step. |
User-defined Data
If desired, enter any User Data in the free-format field provided. 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 to the DLL which are also stored in the project file or the calculation details file. This data is read during initalisation call type 1.
User-defined Variables
User variables may be used to share information between user-defined DLLs for different turbine components. They can be accessed through the DLL function arguments as explained in the respective DLL interface. The number of user variables (NuserVars) is at least 10. Additional user variables may be defined in an External controller DLL, using the External Controller API function ‘AppendIndexedUserVariable’. The External Controller DLL can send and receive data to and from the gearbox DLL using the ‘SetIndexedUserVariable’ and ‘GetIndexedUserVariable’ API functions respectively.
Logging Outputs
Additional data may be sent back to Bladed for logging in supplementary output files in a similar format to that of other simulation outputs. This data can then be viewed directly using the Data View, Results Viewer, or post-processed via the Results API. This is particularly useful for debugging the controller, or for illustrating the details of its operation.
When using a legacy DLL interface then the user will need to set the units of any data to be logged during call type 2. The values themselves are logged during call type 7. For the modern function based External Controller and External Loads DLL interfaces the user can add the required number of logging values using the function AddLogValue. This is called once for each log value, with arguments for the name of the quantity being logged, and the units. On subsequent calls, the function SetLoggingValue can be used to set the value in that time-step, and this value will appear in the log files. SetLoggingValue requires the index of the log value. As the function AddLogValue returns the new number of log values, the index for that addition would be 1 minus this size, or else the function GetLogIndexFromName can be used to recover the index.
The various units that can be defined are written in the allowed units table.
Last updated 06-09-2024