|
External functions |
External function data sources are yet another variety of variable data source. These allow data to be specified by a user-defined function, provided in an external DLL or a Python script. We refer to these two types of external functions as native code external functions and Python external functions, respectively. This function is called repeatedly during the OrcaFlex simulation and is passed the current value of the variable data item. The function must then recalculate and update the value of the variable data item.
The following are required to specify an external function data source:
Specifies whether the external function is embedded directly in the data (Python external functions only), or defined in an external file.
The external function code.
The file containing the external function. This is the name of a DLL for a native code external function, or the name of a Python script for a Python external function.
The file name may use a relative path, in which case it is relative to the folder containing the latest OrcaFlex file which has been opened or saved. If there is no such file (for example, you are working on a new model which has not yet been saved) then the file name is relative to the value of the working directory when OrcaFlex started.
For native code external functions given by a relative path, if the named DLL is not found relative to the directory containing the latest OrcaFlex file, then the system DLL search order is used.
The name of the external function. For a native code external function this is the name of a function exported by the external DLL. For a Python external function this is the name of a class defined in the Python script. In either case, OrcaFlex will list the available function names in the drop-down list: you can select one from the list, or type a name directly into this field.
For details on how to implement external functions please refer to the OrcaFlex programming interface documentation.
When OrcaFlex calls the external function for the first time it passes this value to the function. The function may use this value as its starting value; equally, it can ignore this value and substitute a different one.
| Note: | This value is used by OrcaFlex when drawing the model in reset state. |
This specifies the frequency with which OrcaFlex calls the external function to update the value of the variable data item. You can use the inner time step, the outer time step, or a user-specified time step. If you choose user-specified, then you must also supply a target time step; OrcaFlex will use the nearest whole multiple of the inner time step, and will report this value as the (non-editable) actual specified time step.
| Note: | When using implicit integration, this data item is ignored and the external function is called on each iteration of each time step. |
The bitness of OrcaFlex and compiled native external functions must match: to call native external functions from 64 bit OrcaFlex, they must be compiled as 64 bit; and to call native external functions from 32 bit OrcaFlex, they must be compiled as 32 bit. You can, if you need your external function to work with both 32 and 64 bit versions of OrcaFlex, compile both 32 bit and 64 bit versions of your external function: these should be located in the same folder, and the filename root of the 64 bit version given the suffix '64'. For example, if the 32 bit external function DLL is named ExtFn.dll then the 64 bit DLL must be named ExtFn64.dll. If you follow this naming convention, then OrcaFlex will automatically load which of the two external function DLLs it requires. Please refer to the OrcFxAPI help for full details.
Likewise, the bitness of OrcaFlex and Python must match: to call Python external functions from 64 bit OrcaFlex, you must have a 64 bit version of Python; and to call Python external functions from 32 bit OrcaFlex, you must have a 32 bit version of Python. You may, if you wish, have both 32 and 64 bit versions of Python installed simultaneously; you will, by default, have both 32 and 64 bit versions of OrcaFlex installed. See Python Interface: Installation for more information on installing Python, and on the embedded Python distribution that can be automatically installed as part of the OrcaFlex installation process.
Object tags can be used to pass parameters to external functions. They have the advantage that model-specific data can then be defined together with the OrcaFlex data, rather than being hard-coded into the external function.
The external function examples demonstrate how to pass parameters to external functions in this way.
The following data items can be controlled by external functions:
A selection of example external functions are installed along with OrcaFlex, to the selected location, and can also be downloaded from www.orcina.com/resources/external-function-examples/.
A guide to using external functions to model turbine controllers is available at https://github.com/Orcina-Ltd/turbine-controllers. This includes example Python controllers and an example of using external functions to wrap a Bladed style control DLL.