BATCH PROCESSING .1 Introduction

Simulations, script files, post-processing spreadsheets and fatigue analyses can all be run in unattended mode, by using the Calculation | Batch Processing menu item. This command opens a form that allows you to set up a list of jobs that are to be run. The list can include any number and mixture of the following types of job:

1. Static analysis of pre-prepared OrcaFlex data files (.dat or .yml). OrcaFlex opens the data file, performs the static analysis and then saves the results in a simulation file with the same name as the data file, but with a .sim extension.

2. Dynamic analysis of pre-prepared OrcaFlex data files (.dat or .yml). OrcaFlex opens the data file, performs the static analysis, runs the dynamic simulation and then saves the results in a simulation file with the same name as the data file, but with a .sim extension.

3. Partially-run OrcaFlex simulation files (.sim). OrcaFlex opens the simulation file, finishes the dynamic simulation and then saves the completed simulation, overwriting the original file.

4. A batch script file (.txt). This is a text file which contains OrcaFlex script commands. OrcaFlex opens the script file and obeys the commands in turn. The most common use of script files is to perform a series of systematic variations on a base data file.

5. A fatigue analysis file (.ftg or .yml). OrcaFlex performs the fatigue analysis and saves the results to a binary .ftg file. In addition the results tables are saved to an .xls spreadsheet.

6. An OrcaFlex Spreadsheet (.xls or .xlsx). OrcaFlex will process all post-processing sheets in the Excel workbook.

Note that if the spreadsheet's "Contains Dependencies" options is checked then the workbook will be processes as a single job using a single thread. If it isn’t checked, then each instructions sheet will be broken down into multiple load cases which are individually added to the batch and may be processed simultaneously.

Note: If you wish to use Excel for any reason while OrcaFlex is processing spreadsheets within a batch it is important that you open Excel first, then open the file you wish to work on. The reason for this is that when you double click an Excel file, Windows will try to use the copy of Excel OrcaFlex has claimed, resulting in unpredictable failures.

When adding data files (.dat or .yml) you need to specify whether static or dynamic analysis is to be performed.

This choice is made from the Add Files file dialog window, or from the popup menu.

OrcaFlex can auto-save partial completed dynamic simulations to file at regular intervals during the batch job. This is useful if your computer is prone to failure (for example because of overnight power failures) since the part-run simulation file can be loaded and continued, rather than having to re-run the whole simulation from scratch.

Multi-threading

The batch processing functionality can make use of multiple processor cores. So, for example, if you have a

quad-Automation, Batch Processing

w

Since some batch tasks can depend on the output of other tasks OrcaFlex processes tasks in a very particular order, as follows:

 The batch script files are all processed first. Because it is common to write scripts that output data files it is important to complete all batch scripts before processing the data files.

 Any data or simulation files are processed next.

 Fatigue files are processed next. These use simulation files as input and so should not be started until all data or simulation files have been processed.

 Finally any OrcaFlex spreadsheet files or load cases are processed. These also cannot be started until all data or simulation files have been processed.

The commands in batch script files are processed sequentially. Consequently any simulations that are processed with RunDynamics commands cannot be performed in parallel. Because of this it is advisable to use the SaveData command rather than the RunDynamics command when creating batch scripts. Such a script would create a number of OrcaFlex data files which you could then process in the batch form using all available processor cores.

Batch Form User Interface Close

Dismisses the batch form.

Add Files

Adds jobs to the list. Files can also be added by drag and drop. That is if you are browsing your file system then you can highlight files and drag them onto the jobs list.

Files can be added whilst a batch is running. Note that this feature has the limitation that all pre-existing jobs must be run to completion before the program starts processing the files added whilst the batch was active.

Remove Files

Removes any files highlighted in the jobs list.

Check Files

OrcaFlex opens each file in the jobs list, checks that they contain valid OrcaFlex data or script commands and reports any errors. When checking OrcaFlex spreadsheet or fatigue files it simply confirms the file exists.

Run Batch

Processes the list of jobs. If a job fails then it is abandoned but other jobs are still attempted. Any errors are reported once all jobs have been processed.

Pause Batch

Pauses the currently running batch jobs. This can be useful if you temporarily want another process on your machine to have the processor resource that OrcaFlex is using.

Stop Batch

Terminate processing of batch jobs.

Warnings

Displays a window allowing you to review all warnings generated by OrcaFlex during a calculation. These warnings are suppressed when you are operating in batch mode and this button allows you to review them once the simulation has completed.

Close program when Batch completes

If checked then OrcaFlex will close once the processing of jobs completes. This feature is intended principally for users with networked licences. It allows you to release your claim on an OrcaFlex licence as soon as the batch of jobs is complete.

4.2.2 Script Files

OrcaFlex provides special facilities for running a series of variations on a base data file, using a script file. This contains a sequence of commands to read a data file, make modifications to it, and run the modified file, storing the results for later processing. The file can also include comments. The syntax for the instructions is described in the next topic.

Script files can be written using any text editor. However, it is quite unusual to do this because there are very productive facilities in the OrcaFlex spreadsheet for automatically generating script files for regular sets of cases.

A more recently introduced alternative to script files are text data files. These can be used to specify load case variations. Once again, the OrcaFlex spreadsheet offers a facility to generate these text data files.

w

Automation, Batch Processing

4.2.3 Script Syntax

An OrcaFlex batch script is made up of commands, which are obeyed sequentially, and comments, which are ignored. A comment is a line that is either blank or on which the first non-blank characters are "//". A command can be:

1. A directive followed by one or more arguments, optionally separated by white space (one or more spaces or tabs). For example: load c:\temp\test.dat where load is the directive and c:\temp\test.dat is the argument.

2. An assignment of the form VariableName=value, again with optional white space separators. For example:

Length = 55.0.

Note that:

 Directives, variable names, and object names are all case independent.

 If your script includes a relative file name then it is taken to be relative to the directory from which the script was loaded.

 File names, arguments, variables or values containing spaces or non-alphanumeric characters must be enclosed in single or double quotes and they must not contain the same quote character as is used to enclose them. For example '6" pipe' and "200' riser" are valid, but the following are not valid:

6 inch pipe – contains spaces, so needs to be enclosed in quotes;

6"pipe – contains a double quote, so needs to be enclosed in single quotes;

'6' pipe' – contains a single quote, so needs to be enclosed in double quotes instead of single.

4.2.4 Script Commands

The script commands are executed in the context of an active model. This can be either an OrcaFlex model containing Vessels, Lines etc., or a Fatigue Analysis. The active model defaults, at the start of script execution to being an OrcaFlex model. The active model can change due to a Load/LoadData command, or following a NewModel/NewFatigue command. Some of the commands have different interpretations, depending on what type of model is active, as described below.

The following batch script commands are currently available. You need to put quotes round file names or other parameters that include spaces or non-alphanumeric characters.

Load <FileName>

Opens the OrcaFlex file named <FileName>. The file can be a data file, a simulation file or a fatigue analysis file.

LoadData <FileName>

Opens the data from the OrcaFlex data file named <FileName>.

RunStatics <FileName>

Perform statics for the current model and save the resulting simulation to <FileName>. After the file is saved the model is reset.

RunDynamics <FileName>

Run dynamics for the current model and save the resulting simulation to <FileName>. After the file is saved the model is reset.

Note: We no longer recommend that you use the RunStatics and RunDynamics commands. The commands in a batch script are executed sequentially. This means that if your machine has multiple processors, those processors will not be fully utilised. The recommended approach is to use the batch script to generate OrcaFlex data files and then add those to the batch job list. This will result in the most effective use of processor resources.

Run <FileName> (OrcaFlex model active) This command is identical to RunDynamics.

Run <FileName> (Fatigue active) This command:

1. Performs the fatigue analysis.

2. Saves the results to <FileName> which should have the .ftg extension.

3. Saves tabular results to an Excel workbook with the same name, but an .xls extension.

Automation, Batch Processing

w

Save <FileName> (OrcaFlex model active)

Save the current model to <FileName>. If calculation results (either statics or dynamics) are available then a simulation file will be saved. Otherwise a data file will be saved. When saving data, if the file extension is .yml then a text data file will be saved; otherwise a binary data file will be saved.

Save <FileName> (Fatigue active)

Saves the fatigue model to <FileName> which should have the .ftg extension.

SaveData <FileName>

Save the data from the current model to <FileName>.

If the file extension is .yml then a text data file will be saved; otherwise a binary data file will be saved.

Note: In the Load/LoadData, Save/SaveData and RunStatics/RunDynamics/Run commands, if

<FileName> is a relative path then it is taken to be relative to the directory from which the script file was loaded.

ExtendSimulation <StageDuration>

Adds a new stage of length <StageDuration>. This command is equivalent to the Calculation | Extend Dynamic Simulation menu item. You would normally follow this command with a Save command.

Reset

Resets the current model. This command is equivalent to the Calculation | Reset menu item.

NewModel

This command makes the active model an OrcaFlex model, deletes all objects from the model and then resets data to default values. This command is equivalent to the File | New menu item.

NewFatigue

This command makes the active model a Fatigue Analysis and then resets data to default values. This command is equivalent to the Fatigue Analysis File | New menu item.

Create <ObjectType> [<ObjectName>]

Creates a new object of type <ObjectType>. The new object is automatically selected which means that subsequent assignment commands apply to this new object.

The <ObjectType> parameter can be "Line Type", "Vessel Type", "Line", "Winch" etc. Select Edit | Add from the Model Browser menu to see a list of possible values for this parameter.

Alternatively variable data sources can be created by setting the <ObjectType> parameter to "Bending Stiffness",

"Drag Coefficient" etc. This list of possible variable data source object types can be found in the Data Source Type tree on the variable data form.

If the optional <ObjectName> parameter is included then the new object will be given that name.

Delete <ObjectName>

Deletes the object called <ObjectName>.

Select [<Object Type>] <ObjectName>

Specify the object to which subsequent assignment commands will apply.

The <ObjectType> parameter is optional, and by default is 'object', meaning select the named object. <ObjectName>

must then be either the name of an object that exists in the current model or one of the reserved names 'General' (for the General data form) or 'Environment' (for the Environment data form).

Some examples of the select and assignment commands are given in Examples of setting data.

Other <ObjectType> values only need to be specified in the following special cases.

If the Environment has been selected and there is more than one wave train, then before you can specify any wave train data you must give another select command to select the wave train. This second select command has the form:

Select WaveTrain <WaveTrainName>

So, for example:

Select Environment

Select WaveTrain Primary WaveDirection = 30.0

Similarly, if the Environment has been selected and there is more than one current data set, then you must select one of them before specifying any current data. For example:

w

Automation, Batch Processing Select Environment

Select Current Current2 RefCurrentDirection = 270.0

Note that this is not the same as setting the Active Current. In fact, you should avoid setting up multiple current data in batch scripts if possible: this is best done interactively on the Environment form.

If a vessel type has been selected and it has more than one draught, then before specifying any draught-dependent data you must give another select command that selects the draught. This second select command has the form:

Select Draught <DraughtName>

Before specifying data for RAOs you need to specify the type of RAOs – this can be either Displacement, WaveLoad or QTF. This is done with a command of the form:

Select RAOs <RAO type>

Similarly, before specifying vessel type data for a given wave direction you must give another select command to select that direction. This takes the form:

Select Direction <Direction>

Note: Indentation with spaces or tabs is optional, but makes scripts more readable.

Assignment

Assignment commands take the form VariableName = Value

The VariableName on the left-hand side must be one of the recognised variable names and the named variable must exist in the currently selected object. The Value on the right-hand side must be in the appropriate form for that variable (i.e. numeric or text) and it must be given in the same units as used in the current model.

For example:

Select Vessel1 Length = 110

Draught = "Operating draught"

If VariableName is the name of a variable that appears in a check box in OrcaFlex then the Value should be Yes or No.

For example:

Select Environment CurrentRamp = Yes

If VariableName is the name of a variable that appears in a table in OrcaFlex, then its row number must be given.

The row number is given as an index enclosed by either square or round brackets (don't mix them on the same line), and is always 1-based, i.e. [1] is the first row of the table. Note that this sometimes requires care, since in OrcaFlex the table might not be 1-based. For example, when setting the prescribed motion for a vessel, the command

PrescribedMotionVelocity[2] = 4.8

sets the velocity in the 2^nd row of the table, but in this case the first row of the table is stage 0 (the build-up stage) so this command (slightly confusingly) sets the velocity for stage 1.

More examples of the select and assignment commands are given in Examples of setting data.

Automation, Batch Processing

w

InvokeWizard

Sets the data for the selected object using either the Line Type Wizard or the Plasticity Wizard. The selected object must be either a line type or a bend stiffness variable data source. The input data for the Wizard should first be set using data assignment commands.

An example of how to use this command is given in Examples of setting data.

InvokeLineSetupWizard

Invokes the Line Setup Wizard calculation. The input data for the Wizard should first be set using data assignment commands.

An example of how to use this command is given in Examples of setting data.

WaveSearch <FileName>

Exports the wave search spreadsheet to the specified file. The file can be an Excel spreadsheet (.xls), a tab delimited file (.txt) or a comma separated file (.csv). The decision is taken based on the file extension that you specify. The input data for the wave search should first be set using data assignment commands.

DisplacementRAOsReport <FileName> [<VesselName>]

SpectralResponseReport <FileName> [<VesselName>]

Exports the vessel response report spreadsheets to the specified file for the specified vessel. The file can be an Excel spreadsheet (.xls), a tab delimited file (.txt) or a comma separated file (.csv). The decision is taken based on the file extension that you specify. If no vessel is specified, and there is only one vessel in the model, then that vessel will be used. The input data for the response reports should first be set using data assignment commands.

SHEAR7DataFile <LineName> <FileName>

Exports to <FileName> a SHEAR7 data file for the line named <LineName>.

SHEAR7MdsFile <LineName> <FileName> [<FirstMode> <LastMode>]

Exports to <FileName> a SHEAR7 Mds file for the line named <LineName>.

The <FirstMode> and <LastMode> parameters are optional. If they are specified then mode numbers in the range

<FirstMode> to <LastMode> inclusive are exported. If these parameters are omitted then all modes are exported.

Only the Transverse and Mostly Transverse modes are included in the exported file. If you have specified first and last modes to export then these mode numbers refer to the transverse and mostly transverse modes. The program takes the following steps:

1. Calculate all modes.

2. Sort the modes into order of decreasing period / increasing frequency.

3. Remove all modes which are not Transverse or Mostly Transverse.

4. Export the modes in the range <FirstMode> to <LastMode> inclusive.

SHEAR7OutputFile <LineName> <FileName>

Exports to <FileName> the SHEAR7 output file for the line named <LineName>. The file extension that you specify (e.g. .out, .plt etc.) is used to determine which output file is exported. This command is only available if the SHEAR7 interface is in use.

4.2.5 Examples of setting data

The Select command is probably the most difficult script command to use. To help understand how it works we present some examples of its use below:

Simple examples

For many objects the script commands for setting data take the form:

For many objects the script commands for setting data take the form:

In document OrcaFlex Tutorial (Page 83-88)