|
General data: Post calculation actions |
|
|
General data: Post calculation actions |
Post calculation actions provide a means to include post-processing as part of your wider OrcaFlex automation process. The data are described below and are specified on the general data form.
For example, consider the batch processing capability. This is typically used to run large numbers of dynamic simulations. The input data files are added to the batch form, and then OrcaFlex performs the simulations using as many processors are available on the machine.
The next step is to post-process the simulations to extract the desired results. This can also be a time consuming task and it is very desirable that it be automated. If the post-processing is performed using the OrcaFlex spreadsheet, then the spreadsheet can also be added to the list of batch form jobs. The post-processing will then be performed after all the simulation files have been generated. So, if your post-processing uses the OrcaFlex spreadsheet then it can be integrated into your automation process.
However, if you do not use the OrcaFlex spreadsheet for post-processing, then you need a different mechanism to integrate your post-processing. Post calculation actions meet that need.
A model can define one or more post calculation actions. The actions can be executed after a static analysis is completed or after a dynamic analysis is completed. Post calculation actions are executed when you perform a calculation using batch mode or Distributed OrcaFlex (requires version 5 or later). Post calculation actions can also be invoked from the OrcaFlex programming interface, and interactively from the calculation menu for debugging purposes. Note that post calculation actions are not executed automatically when an analysis is performed interactively in OrcaFlex.
There are two types of post calculation action: in-process Python actions and command script actions.
| Note: | See Python Interface: Installation for more information on installing Python, and on the embedded Python distribution that can be automatically installed as part of the OrcaFlex installation process. |
This action type takes advantage of the Python interface to OrcaFlex. The script is run inside the OrcaFlex process, by an embedded Python interpreter. The benefit of using an in-process execution model is that the script has direct access to the same model that OrcaFlex used to perform the analysis. This is in contrast to the command script actions which need to start separate processes to execute the script, and then load the model and simulation file into memory. In fact an in-process Python action is executed before the simulation file is saved.
The action is specified by a Python script containing Python code. The script must define a function named Execute which receives a single parameter. The sequence of events that are carried out around the action's execution is as follows:
The single parameter that is received by the Execute function can be named whatever you like: for the sake of discussion, we adopt the convention of naming it info. The info object defines the following attributes: model, params, modelDirectory and modelFileName.
The model attribute is an instance of the Model class defined in the OrcFxAPI module. Through this object you can perform your post-processing in exactly the same way as with a standalone Python script.
The params attribute is a string containing the Parameters text specified on the data form.
The other attributes, modelDirectory and modelFileName, provide information about the file on which the analysis was performed. The modelFileName attribute contains the absolute path of the simulation file. Note that the simulation file is yet to be saved. You would typically use modelFileName to create the file name for any output files that your post-processing script saves. For example you might simply change the file extension from .sim to .txt. The modelDirectory attribute is simply the name of the directory that contains modelFileName. Of course, modelDirectory could be obtained by simple text processing of modelFileName, but we provide modelDirectory for the sake of convenience.
Post-processing actions can be quite time consuming. If you wish to report progress, you can call model.ReportActionProgress(progressText). OrcaFlex will then display the contents of the string progressText in the batch form's list of jobs. If the action is executing in the context of Distributed OrcaFlex, then the progress text will appear in the Distributed OrcaFlex viewer's list of jobs.
If your post-processing tool of choice is other than Python, then you must use the command script action type. This action type executes in a separate process. Whilst this is perhaps somewhat less efficient than the in-process Python actions, the command script actions are extremely flexible. The sequence of events is a little different for command script actions:
Since the command interpreter cannot perform OrcaFlex post-processing, your script will typically contain a command to launch another process that can. For example you may launch a MATLAB process. See MATLAB Interface: Installation for details on installing the OrcaFlex interface for MATLAB.
| Note: | Command scripts that invoke MATLAB cannot be used when processing using Distributed OrcaFlex. Distributed OrcaFlex runs as a Windows service which does not allow interaction with the desktop, and the MATLAB executable always interacts with the desktop. |
The command script has access to the same information that is passed to in-process Python actions. However, for a command script these values are passed using environment variables with the following names: PostCalcActionParams, PostCalcActionModelDirectory and PostCalcActionModelFileName.
Progress is reported simply by writing to the standard output device. If your process buffers the standard output then you will need to flush those buffers in order for the progress to be delivered to OrcaFlex in a timely manner.
| Note: | MATLAB uses its own console which captures the standard output and standard error output buffers. Consequently these outputs are not available to OrcaFlex to display. |
Each post calculation action is defined by the following data.
Determines whether the action is run after the static analysis, or after the dynamic analysis.
| Note: | Command script actions that are scheduled to run after statics are sometimes not executed. If the overall analysis is a dynamic analysis, then a command script action will not execute after the statics calculation. The issue is that the statics calculation is performed as a pre-requisite step for the ultimate dynamic analysis, but the simulation file is not saved until the dynamic simulation is completed. On the other hand, in-process Python actions can run because they are not dependent on the existence of the simulation file. This issue is not usually a problem since, commonly, a single set of OrcaFlex data files is designed with either static analysis or dynamic analysis in mind, and the post calculation actions would be configured to run after statics or dynamics respectively. Furthermore, both types of action can extract static results after a dynamic simulation. |
Specifies whether the action is an in-process Python action or a command script action.
Specifies whether the script is embedded directly in the data, or defined in an external file.
The action script.
The file name of the action script. You can give either its full path or a relative path.
Text which is passed to the action. This text can be used for whatever purposes you like. For example, you could define a list of results that are to be extracted.
Suppresses the saving of simulation files when running in batch mode or Distributed OrcaFlex (i.e. whenever post calculation actions are active). This is useful if the post calculation action extracts all the output you need from the simulation. Skipping the saving of the simulation file allows you to reduce storage and bandwidth demands.
Note that this data item is only available if there are some actions defined. And the data item can only be checked if all of the actions are in-process Python actions, since command script actions rely on the presence of a simulation file.
To complement the formal descriptions above, we present here examples for each type of post calculation action. These actions should be assigned to a model that contains a line named Line1.
These examples assume external script files.
Save the following code to a text file named script.py in the same folder as your OrcaFlex data file.
import os.path
def Execute(info):
line = info.model["Line1"]
tension = line.TimeHistory("Effective tension", objectExtra=OrcFxAPI.oeEndA)
outputFileName = os.path.splitext(info.modelFileName)[0] + ".txt"
with open(outputFileName, "w") as f:
f.write(line.name + " End A effective tension\n")
for value in tension:
f.write(str(value) + "\n")
| Notes: | You must not explicitly import the OrcFxAPI module in post calculation action code. This import is performed automatically by the host OrcaFlex process. This import must be performed by the host OrcaFlex process to ensure that the imported OrcFxAPI module correctly references the host OrcaFlex process. The post calculation action code can access the implicitly imported OrcFxAPI module in the usual way, as is demonstrated in this example. |
| If you are extracting large numbers of time histories, it is significantly more efficient to make a single call to OrcFxAPI.GetMultipleTimeHistories() than it is to make multiple calls to modelObject.TimeHistory(). |
Add a single post calculation action and set its data as follows, setting the Python version data to match what is installed on your machine:
Save the data file and run it via the OrcaFlex batch form. Once the dynamic simulation completes, a text file will be created containing the effective tension time history values for end A of the line.
Let's illustrate command script actions with MATLAB. Save the following code to a text file named PostProcess.m in the same directory as your OrcaFlex data file.
try
modelFileName = getenv('PostCalcActionModelFileName')
model = ofxModel(modelFileName)
line = model('Line1')
tension = line.TimeHistory('Effective tension', ofx.oeEndA)
[pathstr, name, ext] = fileparts(modelFileName)
outputFileName = fullfile(pathstr, [name '.txt'])
outfile = fopen(outputFileName, 'wt')
fprintf(outfile, '%s End A effective tension\n', line.name)
fprintf(outfile, '%f\n', tension)
fclose(outfile)
catch
exit(-1)
end
This MATLAB script performs the exact same operation as the Python script above. The script assumes that the MATLAB interface to OrcaFlex is available. You may need to add it to your global MATLAB path, or include an addpath statement in the .m file above.
We also need to create a simple command script to call the MATLAB script. Save the following to a text file named script.bat, again in the same directory as your OrcaFlex data file.
rem Requires that matlab.exe is on the system path.
rem Alternatively, set the PATH variable here:
rem set path=path\to\matlab\bin;%path%
matlab.exe -wait -nodesktop -minimize -r "PostProcess, exit"
| Note: | If there is no explicit exit command then MATLAB will remain open and not return to OrcaFlex. If an error occurs within the script then the exit command in the script.bat file will not be reached, so we need to include try…catch statements around our code to trap an error and exit with an error code to OrcaFlex. |
Add a single post calculation action and set its data as follows:
Save the data file and run it via the OrcaFlex batch form. Once the dynamic simulation completes, a text file will be created containing the effective tension time history values for end A of the line.
Post calculation actions are typically invoked in batch mode or by Distributed OrcaFlex. However, when developing the post calculation action code, this can be inconvenient. As an aid to debugging and testing, post calculation actions can be invoked interactively from the calculation menu. Note that the model must be in the statics complete or the dynamics complete model state in order to invoke the actions interactively.
An alternative is to use a short Python script to load the simulation file, via the Python interface, and then invoke the post calculation actions. For example:
import sys
import OrcFxAPI
for file in sys.argv[1:]:
model = OrcFxAPI.Model(file)
model.ExecutePostCalculationActions(file, OrcFxAPI.PostCalculationActionType.InProcPython)
Save this script in the same directory as your simulation files and give it an appropriate name, for example ExecuteActions.py. Now you can execute the script passing the simulation files as arguments:
python ExecuteActions.py SimFile1.sim SimFile2.sim
An advantage to this approach is that, if you are using a Python debugger, you can step through your post calculation action using that debugger.
As noted previously, MATLAB does not output to the conventional standard output and error buffers. To capture error information from a script, the following methods can be used:
try
your script code...
catch err
errfid = fopen('matlab_error.txt', 'a+')
fprintf(errfid, '%s\n', err.message)
fclose(errfid);
exit(-1)
end