MATLAB reference: ofxObject

The class ofxObject is the MATLAB interface representation of an OrcaFlex model object such as a vessel, line type or buoy.

Some objects are represented by subclasses:

• Lines are represented by ofxLineObject.
• Line types and bend stiffness variable data items are represented by ofxWizardObject.
• Vessels are represented by ofxVesselObject.

Construction

A new ofxObject is normally created from an ofxModel object like this:

See the ofxModel.CreateObject function.

Properties and functions

modelHandle

Returns the handle of the parent model, see ofxModel.

handle

Returns the handle of this object instance as returned by the C API, see C_CreateObject.

type

Returns a numeric value which identifies the OrcaFlex model object type, see TObjectInfo.

typeName

This is a property which returns the name of the object type of this model object instance. Calls C_GetObjectTypeName.

groupFirstChild

This property returns the first child of the object in the model's group structure.

groupNextSibling

This property returns the next sibling of the object in the model's group structure. If there is no next sibling object because this is the last object at this level, [] is returned.

groupPrevSibling

This property returns the previous sibling of the object in the model's group structure. If there is no previous sibling object because this is the first object at this level, [] is returned.

groupParent

This property gets and sets the parent of the object in the model's group structure.

GroupMoveAfter

Moves an object in the model's group structure to be at the same level, and immediately after, the specified target object.

GroupMoveBefore

Moves an object in the model's group structure to be at the same level, and immediately before, the specified target object.

DataNameValid

dataname is the name of a data item in OrcaFlex, the function returns True if this is valid for this model object. The function calls C_GetDataType to determine validity.

DataNameRequiresIndex

dataname is the name of a data item for this model object. The function returns True if this data item is indexed data.

DataType

dataname is a valid data item name for this model object. Determines what type the data item is. The return value is one of the following: dtDouble, dtInteger, dtIntegerIndex, dtBoolean, dtString or dtVariable. The method is implemented by calling C_GetDataType.

VariableDataType

dataname is a valid data item name for this model object, index is a one-based index value for the data item (non-indexed data items ignore this value). Determines whether a variable data item is currently a constant value or is currently variable. This method can only be called for variable data items. The return value is dtDouble to indicate a constant value or dtString to indicate a variable value. The method is implemented by calling C_GetVariableDataType.

GetData

dataname is a valid data item name for this model object, index is a one-based index value for the data item (this is omitted for non-indexed data items). The function first calls C_GetDataType and depending on the data type value returned then calls one of C_GetVariableDataType, C_GetDataDouble, C_GetDataInteger, or C_GetDataString.

The MATLAB interface allows you to use the data name itself as a property which is a more convenient way to get the data. The examples below get the End A Azimuth and the Length of the second section of a line:

SetData

dataname is a valid data item name for this model object, index is a one-based index value for the data item (this is omitted for non-indexed data items) and value is the data to be assigned to the data item. The function first calls C_GetDataType to determine the expected data type and based on the data type value returned then calls one of C_SetDataDouble, C_SetDataInteger, or C_SetDataString.

The MATLAB interface allows you to use the data name as a property of the model object which is a more convenient way to set the data. The following examples set the End B Connection of a line and the duration of simulation stage 3:

IsDefault, HasChanged, IsMarkedAsChanged, SetToDefault, SetToOriginalValue, MarkAsChanged

These functions are used to query and modify the state of data specified by dataName and index.

IsDefault and SetToDefault are available for all model types. The other functions are only available for variation model and restart analysis model types, for objects whose data changes are being tracked. In particular, newly added objects in a child model do not have data changes tracked.

Returns a boolean indicating whether the current value of the data is equal to the default value.

Returns a boolean indicating whether the current value has changed from the value in the parent model or has been explicitly marked as changed.

Returns a boolean indicating whether the current value has been explicitly marked as changed.

Set the data to its default value.

Set the data to the value in the parent model.

Determines whether or not the data is explicitly marked as changed, as specified by value, which should be a boolean.

InsertDataRow

This function inserts a new data row into the table of the indexed data item specified by indexedDataname. The row is inserted before the row index. If index is equal to the row count + 1 for that data item then the new row is added at the end of the table. See the C API documentation for C_InsertDataRow.

The MATLAB interface enables an alternative form of this function call by treating the indexed data item indexedDataname as an object and calling the InsertRow function on this object, for example inserting a new line section before section 4:

In the following example the rowCount property of an indexed data item is used to add a row to the end of a curved plate profile table:

DeleteDataRow

This function deletes the row, index, from the table of an indexed data item, indexedDataname. See the C API documentation C_DeleteDataRow. The MATLAB interface enables an alternative form of this function call by treating the indexed data item indexedDataname as an object and calling the DeleteRow function on this object, for example deleting the third section from a line:

HasTags

Returns the boolean indicating whether or not this object supports object tags.

GetTag

Returns the object tag with the specified name.

If there is no tag with the specified name then the default parameter is returned. If no default parameter is specified then an error is thrown in case there is no tag with the specified name.

GetTags

Returns a structure array with fields Name and Value that contain the object's tags.

SetTag

Add or modify an object tag.

DeleteTag

Delete the object tag with the specified name.

HasTag

Returns a logical value indicating whether or not the object has a tag with the specified name.

TagCount

Returns the number of tags defined by the object.

ClearTags

Delete all tags from the object.

AssignWireFrameFromPanelMesh

Imports the panel mesh file named filename, and then set the object's wire frame drawing data based on the imported panel mesh.

The format parameter specifies the format of the panel mesh file, and can be one of the following:

• ofx.mfWamitGdf
• ofx.mfWamitFdf
• ofx.mfWamitCsf
• ofx.mfNemohDat
• ofx.mfHydrostarHst
• ofx.mfAqwaDat
• ofx.mfSesamFem
• ofx.mfGmshMsh
• ofx.mfWavefrontObj

The symmetry parameter must be one of ofx.msNone, ofx.msXZ, ofx.msYZ or ofx.msXZYZ. When symmetry is specified, the panel mesh should only contain panels on one side of the symmetry plane (ofx.msXZ, ofx.msYZ) or in one quadrant (ofx.msXZYZ).

The importOrigin defines the location of the mesh file body origin, specified relative to the object body origin. If the parameter is omitted then the import origin is assumed to be zero.

The wireFrameType determines whether the mesh is specified by edges or panels. It must be one of ofx.wftEdges or ofx.wftPanels. If the parameter is omitted then a value of ofx.wftPanels is used.

The scale parameter is used to scale the imported vertices. This is useful when you wish to convert between different length units. Pass 1 to import the mesh without scaling. If the parameter is omitted, then a value of 1 is used.

The bodyNumber parameter is used to specify the body to import, in the case where the mesh file contains multiple bodies. If the parameter is omitted, then a value of 1 is used.

The importDryPanels parameter determines whether or not all panels will be imported (that is both wet diffracting panels and dry panels), or just the panels that are specified as being wet. If the parameter is omitted, then a value of true is used.

CreateClone

This function creates a new object that is a clone of another source object. The newly created cloned object will have identical data to the source object.

The name parameter is an optional text value for a non-default object name, if this parameter is omitted then OrcaFlex will create a unique default name. The optional model parameter allows you to specify the destination model for the cloned object. If no destination model is provided then the new object is created in the same model as the source object. This method is implemented using C_CreateClone2.

If you need to clone multiple objects, or browser groups, use the model function CreateClones which also clones any dependencies such as type objects.

vars, varDetails

These functions both return a cell array of result variable names. resultType is the result type required from the Select Results form in OrcaFlex, it is one of the following values: ofx.rtTimeHistory, ofx.rtRangeGraph, ofx.rtLinkedStatistics or ofx.rtFrequencyDomain (if omitted the default is ofx.rtTimeHistory). objectExtra is an ObjectExtra structure that is only required in specific cases. vars returns a one-dimensional cell array of variable names. varDetails returns a two-dimensional cell array with the following data rows:

• Variable Name, the same data as returned by vars.
• Variable Units, e.g. m, ft, kN, deg, etc.
• Full variable name, a string containing the object name, variable name, the object extra and the units, e.g. 'Line1 ZZ Stress (kPa) at End A, Inner, 0.00 deg'.

See C_EnumerateVars2 and TVarInfo.

ObjectExtraFieldRequired

Returns a boolean indicating whether the specified results variable requires a particular object extra field.

varName is the name of the results variable. field specifies the object extra field and can be one of the following:

• ofx.oefEnvironmentPos
• ofx.oefLinePoint
• ofx.oefRadialPos
• ofx.oefTheta
• ofx.oefWingName
• ofx.oefClearanceLineName
• ofx.oefWinchConnectionPoint
• ofx.oefRigidBodyPos
• ofx.oefExternalResultText
• ofx.oefDisturbanceVesselName
• ofx.oefSupportIndex
• ofx.oefSupportedLineName
• ofx.oefBladeIndex
• ofx.oefElementIndex
• ofx.oefSeaSurfaceScalingFactor

RequiredObjectExtraFields

Returns a list of the object extra fields required for the results variable specified by varName.

LineResultPoints

Returns a value identifying at which points results are reported along a line, a turbine blade or a Morison element.

varName is the name of the results variable. The return value can be one of the following:

• ofx.lrpNone
• ofx.lrpWholeLine
• ofx.lrpNodes
• ofx.lrpMidSegments
• ofx.lrpMidSegmentsAndEnds
• ofx.lrpEnds

UnitsConversionFactor

Returns the scaling factor required to convert between the values in the model unit system, and the SI unit system. Multiply by this conversion factor to convert a value from SI units into model units. Divide by this conversion factor to convert a value from model units into SI units.

units is a string which defines the units of the value to be converted. The string is made up of zero or more fundamental components, separated by '.'. The fundamental components are of the form '<base_unit>^N', where <base_unit> denotes the physical quantity, e.g. length, mass, etc., and $N$ is the exponent. If the exponent is omitted then its value is taken to be 1.

The possible values for the base unit are:

• 'LL': length
• 'MM': mass
• 'TT': time
• 'FF': force
• '$S': stress or pressure
• '$E': energy
• '$P': power

The following examples demonstrate how to specify some commonly used units:

• 'LL^2': area
• 'FF.LL': moment
• 'MM.LL^-3': density
• 'FF.LL^-2': stress or pressure, equivalent to '$S'

TimeHistory

Returns time histories for the specified variable name(s). period is a Period structure, if omitted the default is used (see MATLAB interface: Results). objectExtra is an ObjectExtra structure that is only required specific results.

If varNames contains a string, then a single time history is returned. If varNames contains a cell array of strings, then multiple time histories are returned. The columns of the array correspond to the time axis, and each specified variable is a row in the array.

If the model uses either the implicit or explicit time domain dynamics solution methods, this function is implemented with calls to the C API functions C_GetVarID, C_GetNumOfSamples and C_GetTimeHistory2. If a progressHandler has been set, it will be called during this operation.

If the model uses the frequency domain dynamics solution method, this function returns a time history synthesised from the frequency domain process, over the specified period, with a sample interval specified by the model data FrequencyDomainSampleInterval. The static value is added to the time history before it is returned. The function is implemented with calls to the C API functions C_GetFrequencyDomainResultsProcess, C_GetFrequencyDomainTimeHistorySampleCount and C_GetFrequencyDomainTimeHistoryFromProcess.

StaticResult

This function is equivalent to the following:

TimeHistoryCollated

Returns time histories for the specified variable name(s), that fall within the specified period, collated for the specified restart models.

If varNames contains a string, then a single time history is returned. If varNames contains a cell array of strings, then multiple time histories are returned. The columns of the array correspond to the time axis, and each specified variable is a row in the array.

If period is omitted then all sample times are returned. For a specified period, a value of ofx.OrcinaDefaultReal for from or to means the first sample of the first model or the last sample of the last model, respectively.

objectExtra is an ObjectExtra structure that is only required specific results.

The restartModels argument is an array of integer indices specifying which models are to be included. You can use restartFileNames to obtain the file names of the models in the restart chain, and also the length of the restart chain. If restartModels is omitted, then all models in the restart chain are included.

SpectralDensity

Returns the spectral density in a structure with fields X and Y, containing numeric arrays. varName is the result name for which the spectral density is required. objectExtra is an ObjectExtra object that is required for some varNames.

For time domain dynamics this is calculated by FFT from time history, as described in C_CreateTimeHistorySummary2. fundamentalFrequency specifies the minimum, or fundamental, frequency of the spectral density calculation. If this value is omitted, the value specified in the model (on the General data form) is used.

For frequency domain dynamics the spectral density is available as a direct output from the frequency domain solution, by calling the C API function C_GetFrequencyDomainSpectralDensityGraph. The period and fundamentalFrequency parameters are not required for frequency domain spectral density derivation and so can be omitted.

EmpiricalDistribution, RainflowHalfCycles, UnorderedRainflowHalfCycles, RainflowAssociatedMean

These functions return time history summary results as described in C_CreateTimeHistorySummary2.

varName is the result name for which the time history summary is required. period is a Period structure, if omitted the default is used (see MATLAB interface: Results). objectExtra is an ObjectExtra structure that is only required for some specific object types and results variables.

EmpiricalDistribution returns two arrays containing the result value and the associated distribution.

The value returned by RainflowHalfCycles and UnorderedRainflowHalfCycles is an array containing the rainflow half-cycle ranges. The array returned by RainflowHalfCycles is ordered.

The value returned by RainflowAssociatedMean is a structure array containing fields named HalfCycleRange, AssociatedMean and Rratio containing the half-cycle ranges, their associated mean values and the corresponding R ratio values.

CycleHistogramBins

Returns an array containing the binned rainflow cycles for the specified time history result variable.

varName is the result name for which the time history summary is required. period is a Period structure, if omitted the default is used (see MATLAB interface: Results). objectExtra is an ObjectExtra structure that is only required for some specific object types and results variables. binSize determines the width of each bin. The first bin covers the range 0 to binSize, the second bin covers the range binSize to 2*binSize, etc. If binSize is omitted then OrcaFlex chooses a default bin size based on the range of the data and the total number of cycles.

The return value is a structure array containing the cycle bins. The structure array fields are named Value and Count, corresponding to the fields of the C API type TCycleBin.

SpectralResponseRAO

varName is the result name for which the spectral response is required. objectExtra is an ObjectExtra object that is required for some varNames. This functions calls the C API function C_GetSpectralResponseGraph and returns a structure with fields X and Y, containing numeric arrays.

AnalyseExtrema

This function calls the C API function C_AnalyseExtrema. It returns a structure with the following fields: Max, Min, IndexOfMax, IndexOfMin. varName is the result name for which extrema are required. period is a Period structure, if omitted the default is used (see MATLAB interface: Results. objectExtra is an ObjectExtra structure that is required for some specific varNames.

LinkedStatistics

varNames is a list of result names of interest, period is a Period structure, if omitted the default is used (see MATLAB interface: Results). objectExtra is an ObjectExtra structure that is required for some varNames. This function returns an ofxLinkedStatistics object.

ExtremeStatistics

varName is the result name of interest, period is a Period structure, if omitted the default is used (see MATLAB interface: Results). objectExtra is an ObjectExtra structure that is required for some varNames. This function returns an ofxExtremeStatistics object.

TimeSeriesStatistics

This function calls the C API function C_CalculateTimeSeriesStatistics and returns a structure that represents the C API structure TTimeSeriesStatistics and has the same fields.

FrequencyDomainResults

Extracts frequency domain results. The model must use the frequency domain dynamics solution method and be in the simulation complete state. The function returns a structure with the same fields as the C API structure TFrequencyDomainResults. This function is implemented with a call to the C API function C_GetFrequencyDomainResults.

FrequencyDomainMPM

Calculates the most probable maximum for a frequency domain result. stormDurationHours specifies the storm duration in hours. The other parameters are the same as passed to FrequencyDomainResults.

The value returned is the Rayleigh extremes MPM given by σ[2ln(T/T_z)]^½ where σ is the standard deviation, T is the storm duration and T_z is the mean up-crossing period.

FrequencyDomainResultsProcess

Extracts frequency domain results expressed as a process. The model must use the frequency domain dynamics solution method and be in the simulation complete state. The function returns a numpy array of complex values. This function is implemented with a call to the C API function C_GetFrequencyDomainResultsProcess.

In typical usage the process will be linearly combined with other processes and then passed to the FrequencyDomainResultsFromProcess, FrequencyDomainSpectralDensityFromProcess or FrequencyDomainSpectralResponseRAOFromProcess methods of ofxModel.

SaveSummaryResults

Saves summary results tables for an OrcaFlex object to filename. The file can be an Excel spreadsheet (.xlsx or .xls), a tab delimited file (.txt) or a comma separated file (.csv). The decision is taken based on the file extension that you specify. This method is implemented by calling C_SaveSpreadsheet.

If abbreviated is true then the abbreviated summary results will be output. Note that abbreviated results tables are only available for certain objects, e.g. lines and turbines.

SaveAddedMassDampingData

Saves added mass and damping data for a vessel type or a multibody group to filename. The file can be an Excel spreadsheet (.xlsx or .xls), a tab delimited file (.txt) or a comma separated file (.csv). The decision is taken based on the file extension that you specify. This method is implemented by calling C_SaveSpreadsheet.

SaveConnectionsReport

Saves the connections report spreadsheet to filename. The file can be an Excel spreadsheet (.xlsx or .xls), a tab delimited file (.txt) or a comma separated file (.csv). The decision is taken based on the file extension that you specify. This method is implemented by calling C_SaveSpreadsheet.