|
Python reference: OrcFxAPI Module |
|
|
Python reference: OrcFxAPI Module |
The OrcFxAPI Module encapsulates access to the OrcaFlex C API using Python. It contains a number of classes and functions. The classes are documented in the remaining topics in this section and the functions are documented below.
Vector(x, y, z)
Vector(sequence)
Vector2(x, y, z)
Vector2(sequence)
The Vector() function returns a Python list of three values which is the equivalent to the C API structure TVector. There are two ways to call it: either pass three parameters, or pass a sequence (i.e. list, tuple etc.) of length three.
The Vector2() function is exactly analogous, only it returns returns a Python list of two values, equivalent to the C API structure TVector2.
DLLVersion()
This function returns the version number of OrcaFlex DLL being used, as a string. This function calls the C API function C_GetDLLVersion.
DLLLocation()
This function returns the full path of the OrcaFlex DLL being used, as a string.
SetLibraryPolicy(name, value=None)
This function is used to specify module wide policies as listed in the C API function C_SetLibraryPolicy.
FileCreatorVersion(filename)
This function returns the version of OrcaFlex used to create the OrcaFlex data or simulation file identified by filename. This function calls the C API function C_GetFileCreatorVersion.
BinaryFileType(filename)
This function returns the OrcaFlex file type of the OrcaFlex file filename. The value returned is one of the following values: FileType.DataFile, FileType.StaticStateSimulationFile, FileType.DynamicSimulationFile.
for filename in orcaFlex_filename_list:
if BinaryFileType(filename) == FileType.DynamicSimulationFile:
DoSomethingWith(filename)
BinaryFileType calls the C API function C_GetBinaryFileType.
RestartParentFileName(filename)
Returns the parent file name for the specified restart analysis file. If the specified file is not a restart file then None is returned.
OrcinaDefaultReal()
OrcinaDittoReal()
OrcinaInfinity()
OrcinaUndefinedReal()
OrcinaNullReal()
These functions return double values that represent special data values in OrcaFlex. See the C API documentation for: OrcinaDefaultReal, OrcinaDittoReal, OrcinaInfinity, OrcinaUndefinedReal, OrcinaNullReal.
OrcinaDefaultWord
The integer representation of data values which are displayed as ~ in OrcaFlex. See the C API documentation for OrcinaDefaultWord.
MoveObjects(specification, points)
This function exposes the functionality of the OrcaFlex move selected objects wizard. The specification parameter is an instance of MoveObjectSpecification and specifies how to move the points. The points parameter is a sequence of instances of MoveObjectPoint containing the points which are to be moved.
MoveObjects calls the C API function C_MoveObjects.
CompoundProperties(objects, referenceObject=None, referencePoint=None)
Returns overall properties for a collection of objects, specified by the objects parameter. The return value is an object containing attributes corresponding to the fields of the C API type TCompoundProperties.
Properties are reported with respect to the axes of the referenceObject and referencePoint. If these parameters are omitted then the default reference object and point are used, as described in the documentation for the C API function C_GetCompoundProperties.
If the referenceObject parameter is specified, it must be a member of objects. The the referencePoint parameter is a string whose possible values are described in the documentation for the C API function C_GetCompoundProperties.
ExchangeObjects(object1, object2)
Changes the order in which objects appear in their containing list by exchanging them. This function can be used to implement sorting functions that can re-order objects in a model according to, for example, their names.
ExchangeObjects calls the C API function C_ExchangeObjects.
CalculateMooringStiffness(vessels)
Calculates the mooring stiffness for the specified vessels. The vessels parameter must be an iterable object (e.g. tuple or list) containing one or more vessel objects. The vessel objects must all be part of the same model. The model must be in the statics completed state.
The stiffness is returned in a 6N*6N numpy array, where N is the number of vessels specified.
ReadPanelMesh(filename, format, scale=1, bodyNumber=1, importDryPanels=True)
Imports the panel mesh file named filename.
The format parameter specifies the format of the panel mesh file, and can be one of the following:
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.
The bodyNumber parameter is used to specify the body to import, in the case where the mesh file contains multiple bodies.
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.
The return value is an object with attributes panels and symmetry. panels is a numpy array containing the panel vertices. symmetry contains the symmetry defined in the panel mesh file and is one of PanelMeshSymmetry.none, PanelMeshSymmetry.XZ, PanelMeshSymmetry.YZ or PanelMeshSymmetry.XZYZ. Symmetry is not defined for PanelMeshFileFormat.WamitFdf, PanelMeshFileFormat.NemohDat, PanelMeshFileFormat.SesamFem, PanelMeshFileFormat.GmshMsh and
SolveEquation(calcY, initialX, targetY, params=None)
This function is used to solve equations of the form Y(X) = targetY where calcY is the user defined function Y(X). The initialX parameter is the start value for X and targetY is the target return value for calcY. The optional params parameter is an instance of SolveEquationParameters. This function calls the C API function C_SolveEquation.
| Warning: | There is a bug in Python, introduced in version 3.8.0 (32 bit only), which results in Python crashing when using SolveEquation. |
TimeHistorySpecification(modelObject, varName, objectExtra=None)
Returns an object that describes a single time history variable. This function is used to create iterable objects to pass to GetMultipleTimeHistories.
GetMultipleTimeHistories(specification, period=None)
Returns time histories for the specified results variables. Using this function is usually more efficient than making multiple calls to TimeHistory.
specification is an iterable where each element is a time history specification obtained by calling TimeHistorySpecification. period is a Period object, if omitted or set to None then the default value depends on the model state, see Python interface: Results.
The function returns a 2D numpy array. The rows of the array correspond to the time axis, and each specified variable is a column in the array.
For example, the following code extracts position time histories for all points on on a line object:
arclengths = line.RangeGraphXaxis("X")
varNames = "X", "Y", "Z"
spec = [
OrcFxAPI.TimeHistorySpecification(line, varName, OrcFxAPI.oeArcLength(arclength))
for varName, arclength in itertools.product(varNames, arclengths)
]
period = OrcFxAPI.SpecifiedPeriod(0, 10800)
values = OrcFxAPI.GetMultipleTimeHistories(spec, period)
GetMultipleTimeHistoriesCollated(specification, period=None, restartModels=None)
Returns time histories for the specified results variables, that fall within the specified period, collated for the specified restart models. Using this function is usually more efficient than making multiple calls to TimeHistoryCollated.
specification is an iterable where each element is a time history specification obtained by calling TimeHistorySpecification.
If period is omitted then all sample times are returned. For a specified period, a value of OrcinaDefaultReal() for FromTime or ToTime means the first sample of the first model or the last sample of the last model, respectively.
The restartModels argument is an iterable 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.
The function returns a 2D numpy array. The rows of the array correspond to the time axis, and each specified variable is a column in the array.
RayleighStatisticsSpecification(ExtremesToAnalyse=DistributionTail.Upper)
This function returns an instance of the class ExtremeStatisticsSpecification for a Rayleigh distribution.
LikelihoodStatisticsSpecification(Distribution, Threshold, DeclusterPeriod, ExtremesToAnalyse=DistributionTail.Upper)
This function returns an instance of the class ExtremeStatisticsSpecification. The parameters correspond to the fields of the C API type TExtremeStatisticsSpecification.
RayleighStatisticsQuery(StormDurationHours, RiskFactor)
This function returns an instance of the class ExtremeStatisticsQuery for a Rayleigh distribution. The parameters correspond to the fields of the C API type TExtremeStatisticsQuery.
LikelihoodStatisticsQuery(StormDurationHours, ConfidenceLevel)
This function returns an instance of the class ExtremeStatisticsQuery for a Weibull or Generalised Pareto distribution. The parameters correspond to the fields of the C API type TExtremeStatisticsQuery.
TimeSeriesStatistics(values, sampleInterval)
This function is called by the TimeSeriesStatistics method of OrcaFlexObject, but can be called directly, passing a list of time series values in the values parameter.
EmpiricalDistribution(values)
RainflowHalfCycles(values)
UnorderedRainflowHalfCycles(values)
RainflowAssociatedMean(values)
Rratio(range, associatedMean)
SpectralDensity(times, values, fundamentalFrequency=None)
These functions are called by the OrcaFlexObject methods with the same names to return time history summary results, but these functions can be also be called directly. You must provide a time history of values in the values parameter. For the Rratio function you provide cycle ranges and their associated mean values. For the SpectralDensity function the times parameter contains the sample times corresponding to the values provided. See EmpiricalDistribution, RainflowHalfCycles, UnorderedRainflowHalfCycles, RainflowAssociatedMean and SpectralDensity.
CycleHistogramBins(halfCycleRanges, binSize=None)
This function is called by the CycleHistogramBins method of OrcaFlexObject to return rainflow cycle bins, but this function can be also be called directly. You must provide a list of half cycle ranges in the halfCycleRanges parameter which will typically be the result of a call to RainflowHalfCycles. 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 None is passed 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 tuple containing the cycle bins. Each element of the tuple is an object containing attributes named Value and Count, corresponding to the fields of the C API type TCycleBin.
AnalyseExtrema(values)
This function is called by the AnalyseExtrema method of OrcaFlexObject, but can be called directly, passing a list of values in the values parameter.
FrequencyDomainMPM(stormDuration, StdDev, Tz)
Calculates the most probable maximum for a frequency domain result. This function is called by the FrequencyDomainMPM method of OrcaFlexObject, but can be called directly, passing the storm duration, standard deviation, and mean up-crossing period. The storm duration and mean up-crossing period must be specified in the same units of time, and the value returned has the same units as the standard deviation.
The value returned is the Rayleigh extremes MPM given by σ[2ln(T/Tz)]½ where σ is the standard deviation and T is the storm duration.
DisableModule(Module)
Disables the OrcaFlex module identified by the module constant Module which should be OptionalModule.Dynamics. This function must be called before creating a model, for more details see the C API function C_DisableModule.