Text data files: Automating generation

The OrcaFlex spreadsheet has facilities for automating the generation of text data files for a regular set of cases. To use this facility, select the pre-processing worksheet, then select the text data files cell and then click the create text data files command which can be found on the OrcaFlex tab of the Excel ribbon.

The basic idea is very similar to the facility for automating generation of batch script files. Here is an example table:

The cell containing Text Data Files, highlighted in yellow, is known as the anchor cell. The text data files are generated based on the template file specified the in cell immediately to the right of the anchor cell. In this example the template file might specify a variation model like this:

BaseFile: basecase.dat
Environment:
  WaveTrains:
    Wave1:
      WaveDirection: %direction
      WaveHeight: %height
Lines:
  Line1:
    Length[1]: %length

The row immediately below the anchor cell, highlighted in blue, contains variable names. You are free to choose these names as you please. We have adopted a convention that the variable names begin with a percentage sign (%). Although you do not need to follow this convention, doing so will have the benefit of making the variable names stand out.

The rows beneath the variable names row are known as the value rows. Each row defines a single text data file. The text data file is generated by starting from the template file and then replacing each variable name, in turn, by the value specified in the table. The %filename variable name is compulsory, that is it must be included as one of the variable names. It specifies the name of the generated text data file. Relative paths can be used for the template file name and the output file names.

The extent of the table is determined by the presence of empty cells. So the variable names row ends at the first empty cell. Likewise the value rows end at the first empty cell in the column beneath the anchor cell.

The example above produces 8 text data files as its output, named Case01.yml, Case02.yml, etc. This first of these looks like this:

BaseFile: basecase.dat
Environment:
  WaveTrains:
    Wave1:
      WaveDirection: 0
      WaveHeight: 8
Lines:
  Line1:
    Length[1]: 100

Choosing variable names

It is clearly important that you choose unique variable names. However, there is a further subtlety which can arise when one variable name is a sub-string of another. For example, consider the variable names %x1 and %x10. When occurrences of %x1 in the template file are replaced by their actual values, the first 3 characters of any occurrences of %x10 will also be detected.

Such ambiguities seldom arise, but if you are affected then you can extend the naming convention to include a trailing % sign. In the example given above, the variable names become %x1% and %x10% and clearly the problem does not arise.

Multiple tables

You can have multiple tables within a workbook. To process all the tables in one operation, select all the tables and then click the create text data files command.

Benefits over script tables

The variation model text data file approach to load case file generation described above is very similar to the approach using batch script files. The choice of which to use is largely one of personal preference. If you are already familiar with batch script and not yet familiar with text data files then it may prove easier to continue using batch script.

There is one significant advantage of using text data files, which is that it avoids duplication of the OrcaFlex model data. Consider the following typical sequence of actions when using batch script where we assume that the basic model and scripts are already in place:

1. Modify the single base model, represented by an OrcaFlex data file.
2. Run the batch script (or scripts) that generate all the load case data files.
3. Run the simulations for all load case data files.

If text data files are used, as described above, then step 2 is not required. This is because the load case text data files contain a reference to the base model rather than containing a copy as is the case when using batch script.

This is a relatively minor advantage but it does reduce the likelihood of omitting step 2 by mistake when using batch script files. In addition, more complex analyses can lead to your load cases being defined by multiple script files which have to be executed in a particular order. Using the text data file approach means that this complexity is dealt with just once when setting up the text data files, as opposed to every time a modification to the base model is made.