|
MATLAB reference: ofxModel |
|
|
MATLAB reference: ofxModel |
The class ofxModel is the MATLAB interface representation of an OrcaFlex model.
ofxModel([filename][, createModelParams])
ofxModel(modelHandle)
The constructor creates a new OrcaFlex model object. If the filename parameter is specified then the constructor attempts to open this as a simulation file first and as a data file second. If a modelHandle parameter is specified (from another ofxModel instance) the new ofxModel instance will be a copy of the original ofxModel instance but without ownership of the MATLAB interface objects. If no parameters are given then an empty model is created. See the C API documentation C_CreateModel.
The optional parameter createModelParams is a structure to specify the number of processing threads required for a simulation, see CreateModelParams. When this parameter is specified the C API function C_CreateModel2 is called. Otherwise the default number of processing threads is the number of processing cores on the computer.
When the MATLAB garbage collector destroys this object, and it has ownership of the MATLAB objects it contains, then the C_DestroyModel C API function is called.
This function returns a structure representing the C API structure TViewParameters. This structure is used as a parameter to the SaveModelView, SaveModelViewMem, SaveModelViewMetafile and SaveModelViewMetafileMem functions.
The attributes of this view parameters object are the same as in TViewParameters and take the same values. There are additional attributes which provide convenient alternatives to handle attributes:
RelativeToObject provides an alternative to RelativeToObjectHandle, allowing an OrcaFlex object to be used instead of a handle.DisturbanceVessel provides an alternative to DisturbanceVesselHandle, allowing an OrcaFlex object to be used instead of a handle.Filter provides an alternative to FilterHandle, allowing a ViewFilter object to be used instead of a handle.You can use either the handle attribute or its corresponding class based alternative, both approaches will work. However, it is generally more convenient to use the class based alternatives. For example:
params = model.defaultViewParameters;
filter = ofxViewFilter;
filter.Add(...);
params.Filter = filter;
% equivalent to the above, but slightly more verbose
params.FilterHandle = filter.handle;
This function returns a cell array of ofxObject instances for each of the OrcaFlex model objects in the model.
This function returns the simulation start time.
This function returns the simulation stop time.
This property returns true if the simulation has completed. See C_GetSimulationComplete
This function returns the current state of the OrcaFlex model, see the C API documentation for C_GetModelState. The value returned will be one of: ofx.msReset, ofx.msCalculatingStatics, ofx.msInStaticState, ofx.msSimulationStopped, ofx.msSimulationStoppedUnstable.
Properties that give details of the dongle used to provide the OrcaFlex licence. These properties are not available for FlexNet licences.
A string detailing how the OrcaFlex licence is provided. This property is available for both dongle and FlexNet licences.
The name of file that was most recently loaded or saved.
This property can also be assigned to. This is sometimes necessary when loading memory files in order to provide a root for relative paths.
The model type, one of the following: ofx.mtStandard, ofx.mtVariation or ofx.mtRestart.
It is possible to set this property to ofx.mtStandard, but attempts to assign a value of ofx.mtVariation or ofx.mtRestart are not allowed. In order to create new variation models or restart analysis models, use NewVariationModel() or NewRestartAnalysis().
A boolean property that determines whether or not the group structure is output when saving text data files for ofx.mtVariation or ofx.mtRestart model types.
A property returning the full chain of parent file names for a restart analysis model.
A property returning the full chain of file names for a restart analysis model, including this model, and the parent models.
A boolean property that indicates whether the model uses frequency domain dynamics.
A boolean property that indicates whether the model uses time domain dynamics.
A boolean property that indicates whether the simulation can be resumed after having been saved and then loaded.
The target simulation times where mid-simulation restart state will be recorded.
The actual simulation times where mid-simulation restart state have been recorded. These can differ from the target times if the simulation times do not happen to fall exactly at target times.
A boolean property that indicates whether a line in the model has exceeded its Euler buckling limit during the simulation.
| Note: | This property is only relevant when working with frequency domain simulations that use the low frequency, combined linearisation solution frequencies. In this particular scenario both wave frequency and low frequency solves have been performed, and it is necessary to specify which solve is used for drawing. |
This property is used to get or set the frequency domain solve type used by drawing functions such as SaveModelView, SaveModelViewMetafile, etc. The value is one of ofx.fdstLatest, ofx.fdstWaveFrequency or ofx.fdstLowFrequency.
See C_SetSimulationDrawFrequencyDomainSolveType.
This property is used to get or set the simulation time used by drawing functions such as SaveModelView, SaveModelViewMetafile, etc. See C_SetSimulationDrawTime.
This function returns a structure with attributes StartTime, StopTime and CurrentTime. See C_GetSimulationTimeStatus.
This function returns the estimated remaining runtime for a long running simulation, see C_GetSimulationTimeToGo.
This function returns a structure with attributes InnerTimeStep and OuterTimeStep. See C_GetRecommendedTimeSteps.
The threadCount property gets and sets the number of processing threads the model can use. See C_GetModelThreadCount and C_SetModelThreadCount.
This property returns the first child in the model's group structure.
These properties can be assigned functions to receive progress callbacks during statics calculation (including line setup wizard), dynamics calculation, TOrcFxAPIHandle running operations and running a batch script respectively. The progress handler function must match the appropriate function signature for the type of progress required:
function cancel = StaticsProgress(model, progress)
function cancel = DynamicsProgress(model, time, start, stop)
function cancel = PercentProgress(model, percent)
function cancel = BatchProgress(model, progress)
Where the model parameter is a MATLAB ofxModel object reference, the progress parameter is a string indicating the current state of progress and the time, start, stop parameters are the current simulation time, simulation start time and simulation stop time respectively. The PercentProgress handler is called during some TOrcFxAPIHandle running operations, see C_SetProgressHandler, the percent parameter is an integer value.
The return value cancel from each progress handler function should be false to continue processing or true to cancel the operation. The example below shows how to set a simple static progress handler:
% Define the progress handler function somewhere in your code:
function cancel = StaticsProgress(model, progress)
disp(progress)
cancel = false
end
model = ofxModel
model.staticsProgressHandler = @StaticsProgress
model.CalculateStatics
The ofxModel.PauseSimulation function can be called from within the dynamics progress handler.
The warnings function returns a cell array of any warning texts generated by a model. This function calls the C API functions C_GetNumOfWarnings and C_GetWarningText.
This property returns a structure array of wave components. The structure has the same fields as the C API TWaveComponent2 structure. See C_GetWaveComponents2.
This property returns a structure array of wind components. The structure has the same fields as the C API TWindComponent structure. See C_GetWindComponents.
This property returns a structure array of frequency domain process components. The structure has the same fields as the C API TFrequencyDomainProcessComponent2 structure. See C_GetFrequencyDomainProcessComponents2.
The CreateObject function creates a new model object and returns either an ofxObject or one of its subclasses, according to the object type requested. This function calls C_CreateObject.
CreateObject(type[, name])
The type parameter corresponds to the ObjectType value required by C_CreateObject, object type constants are contained in the static MATLAB OrcaFlex interface class ofx. The name parameter is an optional text value required for a non-default object name. If the parameter is omitted then OrcaFlex creates a unique default name.
DestroyObject(obj)
This function removes an object from the model, where obj is a model object name or a MATLAB object reference to an ofxObject or one of its subclasses. See C_DestroyObject.
CreateClones(objects[, model])
This function creates new objects that are clones of an existing collections of objects. The newly created cloned objects will have identical data to the source objects. Any dependencies, such as type objects, which are not present in the destination model, will also be cloned.
The new objects will be created in the model specified by the model parameter. If this parameter is omitted then the new objects will be created in this model.
Delete any types (e.g. line types, clump types etc.) that are not in use.
Delete any variable data sources that are not in use.
Discards any active calculation and returns the model to the reset state.
Removes all objects from the model, returns the general and environment data to their default values and sets the model to be a standard model.
NewVariationModel(parentFileName)
Sets the model to be a variation model based on the specified parentFileName.
NewRestartAnalysis(parentFileName)
Sets the model to be a restart analysis based on the specified parentFileName.
These functions allow you to control the logging storage policy for the model. For more details, see the documentation for the C API function C_DisableInMemoryLogging.
UseVirtualLogging
Enables virtual logging for this model. When virtual logging is enabled, log files are not created, and post-processing is performed by reading directly from the simulation file. For more details, see the documentation for the C API function C_UseVirtualLogging.
LoadData(filename)
Load model data from filename.
The following file types are supported:
LoadDataMem(buffer[, dataFileType])
Load model data from buffer which should be an array of bytes. The dataFileType parameter can be either ofx.dftBinary or ofx.dftText to specify the data format. If the dataFileType parameter is omitted then ofx.dftBinary is used.
The same file types are supported as by LoadData.
SaveData(filename)
Save the model data to filename.
If the file extension is '.yml' then a text data file will be saved, otherwise a binary data file will be saved.
result = SaveDataMem([dataFileType])
Saves the model data returning it as an array of bytes. The dataFileType parameter can be either ofx.dftBinary or ofx.dftText to specify the data format. If the dataFileType parameter is omitted then ofx.dftBinary is used.
LoadSimulation(filename)
Load a simulation file from filename.
LoadSimulationMem(buffer)
Load a simulation from buffer which should be an array of bytes
SaveSimulation(filename)
Save a simulation to filename.
result = SaveSimulationMem
Saves the simulation returning it as an array of bytes.
CalculateStatics
Run a statics calulation on the model. See C_CalculateStatics.
RunSimulation([enableAutoSave, autoSaveFileName[, autoSaveIntervalMinutes]])
RunSimulation % Autosave disabled
RunSimulation(true, 'AutoSaved.sim', 10) # Autosave every 10 minutes to AutoSaved.sim
RunSimulation(true, 'AutoSaved.sim') % Autosave using the default interval
Run a simulation, including calculating statics if the model is in reset state. See C_RunSimulation2. The parameters are optional, if no parameters are specified then autosave is disabled. If enableAutoSave is true and autoSaveIntervalMinutes is omitted then the default autosave interval is 60 minutes.
ExtendSimulation(time)
This function extends a simulation by adding a new stage with a duration of time. This function can only be called when the model is either paused or completed. See the C API function C_ExtendSimulation.
PauseSimulation
This function pauses a running simulation, this function should only be called from within a dynamics progress handler. See the C API function C_PauseSimulation.
ProcessBatchScript(filename[, enableAutoSave, autoSaveFileName[, autoSaveIntervalMinutes]])
ProcessBatchScript(filename) % Run the batch script in filename with no auto save.
ProcessBatchScript(filename, true, 'AutoSaved.sim') % Run batch script with auto saving at the default interval.
ProcessBatchScript(filename, true, 'AutoSaved.sim', 10) % Run batch script with auto saving at 10 minute intervals.
This function runs an OrcaFlex batch script file. See the documentation for the C API function C_ProcessBatchScript. The optional autosave parameters are as described for RunSimulation above.
InvokeLineSetupWizard()
Invokes the line setup wizard calculation. The input data for the wizard should first be set using data assignment commands. These data are owned by a variety of different objects. The model wide data (e.g. calculation mode and convergence parameters) are owned by the General object. The line specific data are owned by each individual line. The following script illustrates this:
model = ofxModel('inputfile.dat')
model.general.LineSetupCalculationMode = 'Calculate line lengths'
model.general.LineSetupMaxDamping = 20
model('Line1').LineSetupTargetVariable = 'Effective tension'
model('Line1').LineSetupLineEnd = 'End A'
model('Line1').LineSetupTargetValue = 830.0
model('Line2').LineSetupIncluded = 'No'
model.InvokeLineSetupWizard()
UseCalculatedPositions([setLinesToUserSpecifiedStartingShape][, simulationTime])
When called with parameter setLinesToUserSpecifiedStartingShape omitted or set to its default value of false this is equivalent to the Model | Use calculated positions menu item in OrcaFlex. When setLinesToUserSpecifiedStartingShape is set to true this is equivalent to the Model | Use specified starting shape for lines menu item in OrcaFlex.
If simulationTime is omitted or set to ofx.OrcinaDefaultReal, then the calculated positions will be based on the static state, if the model is in statics completed state, or the latest calculated simulation time if a time domain dynamic simulation has been performed. Otherwise, the calculated positions will be based on the closest log sample to the specified simulationTime.
UseStaticLineEndOrientations()
This is equivalent to the Model | Use static line end orientations menu item in OrcaFlex.
SaveModelView(filename[, viewParameters])
This function saves a bitmap of the model view to filename. The view is defined in the structure viewParameters, this structure is obtained by calling the function defaultViewParameters and can be modified to define the view required. The viewParameters parameter is optional and can be omitted if the default view parameters are sufficient. See C_SaveModel3DViewBitmapToFile in the C API.
result = SaveModelViewMem([viewParameters])
Saves a bitmap of the view defined in viewParameters returning it as an array of bytes. The viewParameters parameter is optional and can be omitted if the default view parameters are sufficient. See C_SaveModel3DViewBitmapMem in the C API.
SaveModelViewMetafile(filename[, viewParameters])
Saves an enhanced metafile of the model view to filename. The view is defined in the structure viewParameters, this structure is obtained by calling the function defaultViewParameters and can be modified to define the view required. The viewParameters parameter is optional and can be omitted if the default view parameters are sufficient. See C_SaveModel3DViewMetafileToFile in the C API.
SaveModelViewMetafileMem([viewParameters])
Saves an enhanced metafile of the view defined in viewParameters returning it as an array of bytes. The viewParameters parameter is optional and can be omitted if the default view parameters are sufficient. See C_SaveModel3DViewMetafileMem in the C API.
SaveWaveSearchSpreadsheet(filename)
Saves an OrcaFlex wave search 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.
SaveLineTypesPropertiesSpreadsheet(filename)
Saves the OrcaFlex line types properties spreadsheet data 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.
SaveCodeChecksProperties(filename)
Saves the OrcaFlex code checks properties spreadsheet data 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(filename)
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.
SaveReferencesReport(filename)
Saves the references 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.
SampleTimes([period])
Returns an array of the sample times falling within the specified period, where period is a structure returned by the static function ofx.Period. If there is no period parameter then the default is used, see MATLAB interface: Results.
If the model uses either the implicit or explicit time domain dynamics solution methods, this function returns the sample times that fall within the simulation period defined by period. It is implemented with calls to the C API functions C_GetNumOfSamples and C_GetSampleTimes.
If the model uses the frequency domain dynamics solution method, this function returns the sample times for a synthesised time history, over the specified period, with a sample interval specified by the model data FrequencyDomainSampleInterval. It is implemented with calls to the C API functions C_GetFrequencyDomainTimeHistorySampleCount and C_GetFrequencyDomainTimeHistorySampleTimes.
SampleTimesCollated([period][, restartModels])
Returns an array of the sample times falling within the specified period, collated for the specified restart models.
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.
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.
object.SaveSummaryResults(filename[, abbreviated])
Saves summary results tables for all objects 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.
FrequencyDomainResultsFromProcess(process)
FrequencyDomainSpectralDensityFromProcess(process)
FrequencyDomainSpectralResponseRAOFromProcess(process)
Analogous to the FrequencyDomainResults, SpectralDensity and SpectralResponseRAO methods of ofxObject, respectively. Instead of returning results for a specified variable name, these functions instead return results for a specified process. Typically the process is obtained by linearly combining processes returned from calls to FrequencyDomainResultsProcess.
ExecutePostCalculationActions(filename, actionType[, treatExecutionErrorsAsWarnings])
Executes the post calculation actions for the specified actionType which can be either ofx.atInProcPython or ofx.atCmdScript.
The filename is the name of the simulation file associated with the model. This name will be passed to the post calculation action.
Pass true to treatExecutionErrorsAsWarnings if you wish errors that occur during action execution to be treated as OrcaFlex warnings. Pass false if you want such errors to be treated as errors. The treatExecutionErrorsAsWarnings parameter is optional and if omitted defaults to false.