|
Python reference: Diffraction |
|
|
Python reference: Diffraction |
The class Diffraction is the Python interface to the OrcaWave diffraction analysis. It encapsulates the following functions from the C API:
To perform a diffraction analysis through the Python interface a Diffraction object must first be created by calling the constructor. An existing OrcaData data file can be loaded, either during construction or by calling LoadData(). Likewise the data can be saved by calling SaveData(). Calculations are performed by calling Calculate(). Results files can be loaded and saved with LoadResults() and SaveResults(). Results can be extracted as numpy arrays.
The data items are set in the same way as data items are set for model objects, this is described under Python interface: Object data. The data item names are obtained from the OrcaWave GUI by selecting the data item of interest and pressing F7 or opening the popup menu and clicking data names.
Diffraction(filename=None, threadCount=None)
The constructor creates a new diffraction object by calling the C API function C_CreateDiffraction.
If the optional filename parameter is specified then the constructor will open this file after creating the diffraction object.
The optional threadCount parameter specifies the number of processing threads used for calculations, if omitted then the default is the number of processing cores of the computer.
Identifies the current state of the diffraction object, returned by C_GetDiffractionState.
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: ModelType.Standard, ModelType.Variation or ModelType.Restart.
It is possible to set this property to ModelType.Standard, but attempts to assign a value of ModelType.Variation or ModelType.Restart are not allowed. In order to create new variation models or restart analysis models, use NewVariationModel() or NewRestartAnalysis().
The threadCount property gets and sets the number of processing threads the used for calculation. See C_GetModelThreadCount and C_SetModelThreadCount.
A progress function can be assigned to this property to receive progress callbacks during file operations. The progress handler function must match the following function signature:
def FileProgress(diffraction, percent)
Where the diffraction parameter is a Python Diffraction object, the percent parameter is an integer indicating the current state of progress. A value of 0 means the operation has just begun; values between 1 and 100 indicate the percentage progress; a value of -1 indicates that the operation has finished.
The progress handler function should return False to continue processing or True to cancel the operation.
A progress function can be assigned to this property to receive progress callbacks during the calculation. The progress handler function must match the following function signature:
def CalculationProgress(diffraction, progress)
Where the diffraction parameter is a Python Diffraction object, the progress parameter is a string indicating the current state of progress.
The progress handler function should return False to continue processing or True to cancel the operation.
This property returns a list of DiffractionWaveComponent objects. See C_GetDiffractionWaveComponents.
LoadData(filename)
This function loads an existing OrcaWave data file named filename.
LoadDataMem(buffer, dataFileType=DataFileType.Binary)
Load data from buffer which should be a bytes or bytearray instance.
LoadResults(filename)
This function loads an existing OrcaWave results file named filename.
LoadResultsMem(buffer)
Load results from buffer which should be a bytes or bytearray instance.
SaveData(filename)
Saves the data to an OrcaWave data file named filename.
SaveDataMem(dataFileType=DataFileType.Binary)
Saves the data returning it as a bytearray object. The dataFileType parameter can be either DataFileType.Binary or DataFileType.Text to specify the data format.
SaveResults(filename)
Saves the results to an OrcaWave results file named filename.
SaveResultsMem()
Saves the results returning it as a bytearray object.
Calculate()
Performs the diffraction calculation.
Reset()
Discards any active calculation and returns the diffraction object to the reset state.
Clear()
Returns all data to their default values. This is equivalent to selecting New from the OrcaWave File menu.
NewVariationModel(parentFileName)
Returns all data to their default values and sets the model to be a variation model based on the specified parentFileName.
NewRestartAnalysis(parentFileName)
Returns all data to their default values and sets the model to be a restart analysis based on the specified parentFileName.
SaveMeshDetailsSpreadsheet(filename)
Saves the diffraction mesh details 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.
SaveMeshDetailsSpreadsheetMem(spreadsheetFileType=SpreadsheetFileType.Xlsx)
Saves the diffraction mesh details spreadsheet, returning it as a bytearray object. The spreadsheetFileType parameter can be either SpreadsheetFileType.Csv, SpreadsheetFileType.Tab or SpreadsheetFileType.Xlsx to specify the spreadsheet format. This method is implemented by calling C_SaveSpreadsheetMem.
SaveAutoGeneratedControlSurfaceMesh(filename)
Saves the automatically generated control surface mesh for the selected body as a WAMIT .gdf file named filename.
SaveAutoGeneratedFreeSurfacePanelledZoneMesh(filename)
Saves the automatically generated free surface panelled zone mesh as a WAMIT .gdf file named filename.
SaveSymmetrisedBodyMesh(symmetry, clippingTolerance, filename)
Saves a symmetrised body mesh file for the selected body as a WAMIT .gdf file named filename. The symmetry parameter, which must be one of PanelMeshSymmetry.XZ, PanelMeshSymmetry.YZ or PanelMeshSymmetry.XZYZ, specifies the symmetry plane(s) to be created.
Specifically, this method takes the contents of the body's original mesh file and clips them along the symmetry plane(s) of the symmetry parameter. That is, panels on the negative side of the plane are removed and any panels which straddle the plane are clipped to remove the portion on the negative side. The clippingTolerance parameter, which must be positive, specifies a length that is used by this method in the same way that waterline Z tolerance is used when OrcaWave clips a body mesh along the free surface.
SaveResultsSpreadsheet(filename)
Saves the diffraction results tables 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.
SaveResultsSpreadsheetMem(spreadsheetFileType=SpreadsheetFileType.Xlsx)
Saves the diffraction results tables, returning them as a bytearray object. The spreadsheetFileType parameter can be either SpreadsheetFileType.Csv, SpreadsheetFileType.Tab or SpreadsheetFileType.Xlsx to specify the spreadsheet format. This method is implemented by calling C_SaveSpreadsheetMem.
These properties return the same text as shown on the validation page in the OrcaWave GUI.
These properties return the diffraction calculation output as numpy arrays. If the results are not available, usually because the calculation data meant they have not been calculated, an empty array is returned.
For more details on the structure and dimensions of these arrays, refer to the C API function C_GetDiffractionOutput.
These methods are passed reporting origins (one origin per included body) and return the corresponding results relative to the specified origins. For example:
addedMassRelativeTo(reportingOrigins)
This function returns the added mass results expressed with respect to axes through the specified reporting origins and parallel to the body axes. The origins are passed in the rows of reportingOrigins. Therefore reportingOrigins should be a numpy array with shape [Nb, 3], where Nb is the number of bodies included in the calculation. Each origin should be given in the body coordinates of the corresponding body. See C_TranslateDiffractionOutput.