|
External functions |
|
|
External functions |
Some data items in OrcaFlex can vary during the course of a simulation, and this can be achieved in a number of different ways. For example some data items can be specified by a time history or an interpolated table. Sometimes this may not provide sufficient flexibility, and for these cases OrcaFlex allows the data to be externally calculated by an external function that you can write yourself.
With externally calculated variable data, OrcaFlex calls an external function that calculates the value for a variable data item. OrcaFlex provides information on the model and current simulation state, and the external function can use this and additional information to determine the value for a data item.
Scenarios where external functions may be useful include modelling of PID controllers, thrusters in a dynamic positioning system, rate dependent line stiffness, etc. Note that this list is not meant to be exhaustive – we are just offering a flavour of the problems external functions might be used to solve.
There are two methods for creating external functions, described below.
Python is a dynamically typed scripting language which offers many advantages, especially to those who feel they do not have the programming experience to use C++. The Python environment takes care of many of the low level programming tasks (such as memory management and type casting), the code is easy to read and it is straightforward to learn. The development cycle (write–test–modify) is short since there is no need to compile and link code. For these reasons Python is a productive language to use with OrcaFlex, and a fairly complex external function can be written in a just few lines of code. See Python External Functions for details on how to write a Python external function and Python interface for details on using Python to interface to OrcaFlex.
The trade off for this convenience is speed: a Python external function will be slower to run than one written in C++. So Python is less suitable if the function does a significant amount of processing and simulation time is an important consideration.
Native external functions can be implemented in any programming language that can produce Windows DLLs, with primary language support for C++ and Delphi. Native external functions are far more complex to write than Python external functions. The coder is responsible for memory management tasks, type conversions and compiling the code into a DLL. This means the development cycle is longer and demands more programming experience. The advantage of native external functions is that they offer improved speed over the interpreted Python code so native external functions should be used if this is a serious issue. See native external functions for more details.
A number of external function examples can be found within this documentation:
Before starting to read our documentation for a specific language, this overview should describe the overall form and behaviour of external functions. We attempt that in this section.
External functions are managed by OrcaFlex using the following general life cycle, which begins whenever you run a simulation that uses an external function:
During use of an external function, OrcaFlex provides information as input to your code. Your external function must also return information to OrcaFlex - at minimum, a value for a variable data item during calculation. This communication uses a special object that is shared between OrcaFlex and your external function. Data within that object can be updated by OrcaFlex as the simulation proceeds, for your code to read as input. Data within that object is also updated by your code for OrcaFlex to read, including the external function return value for use in the simulation.
Some of the information provided by OrcaFlex will locate your external function within the model. For each instance of your external function, OrcaFlex will confirm the model object using this instance, and the model data that this instance is required to provide. The current simulation time is also provided, so you are made aware of the progress of dynamics.
Some model objects using external functions provide additional state data (such as position, velocity etc.) to your code through the information exchange object. The state data will depend on the type of model object using the external function. This data should not be modified, and is intended as input to your calculations.
There are further categories of information available through this object, such as calculation options or choices made for reporting of external results. We defer to the more detailed documentation for a specific programming language to fully describe the elements of the exchange object.
OrcaFlex is subject to some deliberate constraints when calling external functions, and we describe those here in case they are helpful to models where multiple external function instances are used.
For any given externally calculated data item (e.g. a single component of an applied load), the initialisation section will occur before any calculation calls. For any given model object, the externally calculated data items will always be called in the same order each time. But the ordering between different model objects (i.e. different objects in the model browser) is not defined and could change.
For the following situations, which we expect are the most likely coupling of data items, the order of calls is defined as follows:
If you want to write an external function that will be used for coupled data items, you should not assume anything else about the order of calls, other than what is defined above. If this is a problem, and you need to know more about the order of calls, then please contact us.
OrcaFlex line types allow their stiffness data to be externally calculated. In order to place those external functions in context it is helpful to present a brief overview of the OrcaFlex line model.
| Figure: | OrcaFlex line model |
The line is divided into a series of line segments which are then modelled by straight massless elements with a node at each end. Each node is effectively a short straight rod that represents the two half-segments either side of the node. The exception to this is end nodes, which have only one half-segment next to them, and so represent just one half-segment.
OrcaFlex lines are made up of sections and each section has properties as specified by an OrcaFlex line type. In turn, each section is made of a number of nodes and segments which get their properties from the appropriate section's line type.
At each node there are springs which model the stiffnesses of the line. These are shown in more detail below:
| Figure: | Detailed representation of OrcaFlex line model |
For axial and torsional stiffness, the single springs at mid-segment for extension or twist are modelled within your external function.
For bend stiffness we note that, on each side of the node is a bending spring, as shown in the figure above. The functioning of these two bending springs at the line nodes is what the external function implements.
The bending springs that are associated with each node are named as follows. The spring on the side towards end A is called the in bending spring and the spring on the side towards end B is called the out bending spring. For the node at end A there is no in bending spring. Instead the bending connection stiffness is used – this can be thought of as the end fitting stiffness. Similarly there is no out bending spring at end B.
These node bending springs calculate a bend moment in vector form. The bend moment vectors have two components, $x$ and $y$. The third component $z$ is the torsional moment and is handled separately by the torsional spring. Each mid-node must calculate four bend moment values: $x_\textrm{in}$, $y_\textrm{in}$, $x_\textrm{out}$ and $y_\textrm{out}$. Likewise, the node at end A must calculate two bend moment values: $x_\textrm{out}$ and $y_\textrm{out}$. The node at end B must also calculate two bend moment values: $x_\textrm{in}$ and $y_\textrm{in}$.