External Loads DLL Interface

Overview

Bladed provides the facility for users to apply external loads to the multibody model during the simulation. This is implemented via dynamic link library (DLL) in windows and via shared object(so) in Linux.

Note

External Loads DLL functionality is available for Linux and Bladed distributions with the similar capabilities. For simplicity, in this this documentation we will be focusing on the Windows version.

During the simulation, whenever loads are applied to the model, the external loads DLL is called and has the opportunity to interrogate the positions and velocities of the model, prescribe accelerations and apply forces and torques to any node.

The mechanics of this interface are different from that of the external controller. The principle differences are:

1. External loads DLL must be written in C++.

2. The external loads DLL must be compiled to go with the appropriate version of Bladed's provided header files. They are not guaranteed to be backwards compatible.

3. The external loads DLL does not require any linking or delay loading of libraries.

It is possible to debug through external loads DLL in a manner very similar to that for the external controllers.

Note

Examples of External Loads DLL(simple and advanced) are provided in the installation folder.

DLL Interface

Interface

An external loads DLL is expected to implement its functionality through the four DLL export calls: Initialise, ApplyExternalLoads,StepComplete and LogResults. Table below shows the periodicity of their invocation and their purpose.

Table 1 - Overview of four main export calls in the external loads DLL interface.

Function name	When is it called?	Usage
Initialise	Called at the beginning of the simulation.	Initialising logging Initialising user code
ApplyExternalLoads	Called every time that loads are applied to the model.	Getting positions and velocities Getting component state value and state rate Applying loads
StepComplete	Called when the integrator has found the state values at end of a time step. Convergence criteria and step size constraints have been satisfied.	Getting internal loads Getting positions and velocities Getting component state value and state rate
LogResults	Called once the integrator has found a consistent set of states at every Bladed Output time step.	Get and write out values obtained from Bladed calculations in the Bladed output format

DLL call sequence within simulation

This section describes the call sequence of the DLL export calls available in the framework of external loads DLL interface. Further detail about the functions call sequence is presented in Figure 1.

Figure 1: Call sequence of external loads DLL functions during Bladed simulations.

ApplyExternalLoads

On an ApplyExternalLoads call, the Bladed calculation can pass the position, velocity, state and state rate of the structure and the user can apply loads to be considered. ApplyExternalLoads is called during initial conditions iteration and in the time domain calculations at various instances:

• At the beginning or end of a time step, or on trial time steps for the Runge-Kutta integrator.

• For the variable step Runge-Kutta integrator ApplyExternalLoads calls will be at irregular time intervals.

• The fixed step (Explicit and Implicit) Newmark Beta and Generalised Alpha integrators often call ApplyExternalLoads at regular time intervals, but can reduce step size due to phenomena such as stick-slip friction. Additionally the Implicit Newmark Beta can reduce step size if the integration iterations do not converge at the requested step size.

• The Implicit Newmark Beta integrator will make several calls to ApplyExternalLoads on the same end of step time instance as part of the iteration scheme.

For all integrator types, the ApplyExternalLoads calls are not strictly in ascending time order, i.e. later calls to ApplyExternalLoads may be at an earlier time step than previous calls.

StepComplete

When the integrator has found a valid solution at the end of a timestep, StepComplete is called.

StepComplete calls are in strictly ascending time order. At this point, internal loads and quantities that depend on the system accelerations (e.g. support structure fininte element deflections) can be examined. One can also examine end of step quantities such as positions and velocities. If the desired quantities to be extracted from or applied into Bladed require the time to be in strictly ascending order, then it is best to get all relevant information from Bladed on the StepComplete and then apply any calculated loads in the following ApplyExternalLoads calls (see Figure 1).

LogResults

On the LogResults call type, one may write data to Bladed standard output format. This function is called only on the results output time step. The usage of this function ensures only the most updated values are written as a Bladed output format. The data will be stored inside a result group denoted by External Loads DLL N with N being the ID of the external loads being applied (1,2,3,..). The actual data itself will be written out into the output file depending on the length of the output buffer defined by the user.

Lifecycle of DLL Within Simulation

When an external loads DLL is defined and the Bladed simulation engine (dtbladed.exe) is requested to perform a dynamic simulation, then the DLL specified is loaded into the simulation engine's address space at the point of initialising the run. Subsequently, dtbladed.exe makes calls into the DLL as specified above. Each of these function calls is made with a single interface/exchange object as the argument, allowing the DLL to access functionality exposed by it. The DLL is unloaded at the end of the simulation and the interface/exchange object is deleted.

Users can hook into DLL lifecycle events (e.g. load/unload) by implementing a DLL entry point function. This may be necessary in cases where external resources may need to be initialised or freed by the DLL. However, such mechanisms -- e.g. DllMain on Windows, are typically platform specific and may hinder portability of the DLL, making it harder to move your simulations to another platform such as Linux.

Interface/Exchange Object

The interface/exchange object passed in by the simulation engine to the external loads DLL defines the full range of functionality available to the external loads DLL. For example, below is how IInitialiseExternalLoadsLatest object pointer is passed to Initialise.

extern "C" void __declspec(dllexport) __cdecl Initialise(IInitialiseExternalLoadsLatest * ext_loads)

When new functionality is added to the interface/exchange object, this will typically result in a new version of the interface being created, which then also leads on to a change in the argument type on the export calls. For example, the original interface/exchange was Initialise which took object type IExternalLoads as an argument. This has been extended to provide additional functionality. The latest version of the interface/exchange export calls are Initialise, ApplyExternalLoads, StepComplete and LogResults. These calls must use the latest object type as an argument, such as IInitialiseExternalLoadsLatest, IApplyExternalLoadsLatest, IStepCompleteExternalLoadsLatest and ILogResultsExternalLoadsLatest respectively to reflect this modification. The new version supports all existing functionality as well as the extensions introduced through it. This method of explicit versioning helps maintain binary compatibility so that new versions of the simulation engine can continue to work with external loads DLL implementations that were built using an older interface definition. In other words, users typically need not rebuild their existing external loads DLL when upgrading their models to use new versions of Bladed. A rebuild is generally only needed if they would like to make use of new functions exposed by a newer interface.

Specify External Loads DLL in Bladed

Once you have created your own external loads DLL project, you have to then generate the DLL by building the project. After the DLL is generated, you now need to specify the path to the external loads DLL in Bladed. Follow the steps below to specify the external loads DLL path (also see Figure 2):

• Open Bladed and load a Bladed project file (Ex: ‘demo_a.prj’).

• Click Specify from toolbar menu.

• Click Additional Items.

• Click to expand 'External Loads DLL'.

• Tick 'Use external loads DLL?'.

• Specify the path for 'External Loads DLL Location'.

• Specify any additional parameters in the Additional Parameters input box. These can be read in the external loads DLL.

• Click Okay.

Figure 2: Specifying external loads DLL into Bladed.

Article last updated on 25-03-2024