|
Python external functions: ExternalFunctionInfo |
|
|
Python external functions: ExternalFunctionInfo |
This class is a Python equivalent of the C external function type TExtFnInfo although it omits some fields of the C type and adds others useful to Python programmers. OrcaFlex itself creates this type in the Python namespace and passes an instance of this class as a parameter to the Python external function methods.
Instances of this class are created by OrcaFlex.
This is the name of the data item being calculated. Data items for table data (e.g. globally applied loads) will be post-fixed with the table row number in square brackets. The data name will be one of the variable dataname constants listed in the OrcFxAPI.py module (these constant names are prefixed with "vdn"). See lpDataName in TExtFnInfo.
The name of the variable datasource using this external function, defined in the Variable Data Form in OrcaFlex. Equivalent to lpDataSourceName in TExtFnInfo.
Custom results calculated by the external function are registered with OrcaFlex by setting this attribute in the RegisterResults() method. The value returned should be a Python array of dictionaries, with one dictionary per external result. The dictionary should contain 3 items – "ID", "Name" and "Units". The "ID" item is an Integer value which uniquely identifies a custom result, OrcaFlex passes this value to the DeriveResult() method to specify which result value is required. The "Name" item is the name of the result that will appear in the OrcaFlex Select Results form, and the name used to refer to the result through the Python API. The "Units" item is displayed with the result name in the result's graph or table, this item can be a custom string or a coded string which will be substituted with the appropriate unit text by OrcaFlex. The unit codes are:
| OrcaFlex Display | ||
| String Code | SI Units | US Units |
| $E – Energy | kJ | kpf.ft |
| FF – Force | kN | kpf |
| LL – Length | m | ft |
| MM – Mass | te | kp |
| $S – Stress | kPa | kpf/ft^2 |
| TT – Time | s | s |
| 1/TT – Frequency | Hz | Hz |
| °T – Temperature | °C | °F |
| $P – Power | kW | kpf.ft/s |
The base units above can be combined, for example for velocity use "LL/TT" which OrcaFlex will display as "m/s" in SI units. See TExtFnResultInfo for details of the C API structure.
| Note: | If the units string is "deg" then range jump suppression will be performed for the result. |
A Python object that provides additional information on an object's instantaneous state, see Instantaneous Calculation Data. Not all model objects provide this information, in which case this attribute will be None. See lpInstantaneousCalculationData in TExtFnInfo.
This attribute holds external result calculation data stored in the simulation file. Data to be logged by the external function class is returned to OrcaFlex as a string in this attribute when OrcaFlex calls the LogResult() method. Logged data from the simulation file is passed to the external function's DeriveResult() method as a string when an external result is requested. See lpLogData in TExtFnInfo.
This is a Python OrcaFlex interface Model instance representing the currently running model.
This attribute contains the name of the latest OrcaFlex file (.dat, .yml or .sim) that was opened or saved. If the model has not yet been saved then this attribute will be the empty string. See lpModelFileName in TExtFnInfo.
This attribute contains the directory of the currently running model. If the model is not yet saved then this attribute will be the empty string. See lpModelDirectory in TExtFnInfo.
This is a Python OrcaFlex interface OrcaFlexObject instance representing the model object calling the external function.
This attribute usually refers to the same object as ModelObject. However, externally calculated axial stiffness, bend stiffness or torsional stiffness functions are handled slightly differently. The data for the external function is specified for line type objects, but the external function is called for nodes on OrcaFlex line objects. For such functions this attribute refers to the line type object used to define the line properties.
This attribute is True when OrcaFlex is starting a new time step when using implicit integration. For more details see NewTimeStep in TExtFnInfo.
This is a Python OrcaFlex interface ObjectExtra instance providing additional information on a model object, for instance a wing name for a 6D buoy. If no additional information is required then this attribute will be None.
| Note: | It is usually more convenient to use object tags rather than the ObjectParameters attribute to pass object specific data to an external function. |
If the model object has a tag named ExternalFunctionParameters this attribute will contain a Python object representing the tag's value, otherwise this attribute will be None. Parameters can be in plain text or YAML format. The plain text form needs to be in the following format:
# Comments are prefixed with # or //
//Comments and blank lines are ignored
name1 = value1 # name value pair delimited by =
name2: value2 # or an equivalent, alternative form
There should be no more than one name/value pair per line. Each name/value pair is added as an entry to a Python dict, the values are added as strings. If the data begins with a brace or square bracket ("{" or "[") then the string will be assumed to be in JSON (Javascript Object Notation) format and passed as a Python string for the external function to convert.
The parameter data can also be represented in YAML format (this is the same format that OrcaFlex uses for its text data file). To take advantage of this, you will need to have the YAML Python module in your Python library. This data format is a convenient way of passing more complex parameter data. The first line of the parameter data must be %YAML x.x where x.x is the yaml version number. For example:
%YAML 1.1
---
dataset1: [x, y, x]
...
The parameter data must be formatted according to YAML rules. The ObjectParameters attribute will again be a Python dict but can have a richer structure than the plain text format. In this YAML example, ObjectParameters contains a single item named dataset1 with a value that is a Python list containing three string items.
Parameter data that does not follow one of these formats will be passed as a simple Python string.
The integer result id of a registered external result passed to the DeriveResult() method. This result id will have been registered with OrcaFlex in a call to the external function's RegisterResults() method.
The current simulation time in the OrcaFlex model.
If a simulation is saved then this attribute can be used to store the state of the external function in a call to the StoreState() method. The data should be a Python string or byte data, this can be in any format but we recommend using Python's json module as the most efficient way to do this. If a simulation file is reloaded containing saved state data then this attribute can be read and the state restored in the external function's Initialise() method.
Some external functions return more than a single value and do so using this attribute instead of the Value attribute.
The types of external function that use this attribute are:
Otherwise the attribute is set to None.
This attribute indicates whether the external function will be updated during statics, see the UpdateDuringStatics member of TExtFnInfo.
This attribute is True by default. If the external function does not support resuming partially run simulation files, then is should set the value to False in the external function's Initialise() method.
If possible, external functions should be coded to support resuming partially run simulation files. Typically this will involve saving state in the StoreState() method, and restoring that state in the Initialise() method. However, this is not always possible, for example when the state is held by an external DLL that does not provide access to it.
This is the value of the variable data item. When calling the external function's Initialise() method this will contain the Initial value as specified in the Variable Data Form for the external function. When calling the external function's Calculate() method, this attribute will contain the value set by the previous call. Modify this attribute with the new value for the variable data item calculated in the external function. This attribute is also used to return the result value from a call to DeriveResult(). See the Value member of TExtFnInfo.
This attribute is a Python dictionary for sharing working data between external function instances. This dictionary is shared model wide but is private to the model. Entries need to be keyed with an appropriate identifier to prevent unintended overwriting by other external functions in the same model.
TExtFnInfo, TExtFnResultInfo, Instantaneous Calculation Data, ExternallyCalculatedImposedMotion and ExternallyCalculatedScalarImposedMotion.