Text data files

Text data files are used to define and represent OrcaFlex models in a human readable and easily editable format. Text data files can be opened and saved by OrcaFlex. A very simple example is shown below:

General:
  StageDuration:
    - 10.0
    - 50.0
Lines:
  - Name: Line1
    Length, TargetSegmentLength:
      - [60.0, 5.0]
      - [40.0, 2.0]
      - [120.0, 10.0]

This example first defines a 10s build-up stage followed by stage 1 with 50s duration. Then a line is created and named "Line1". Finally the section data are specified: three sections are created with varying section lengths and segment lengths. Default values are used for all data which are not specified.

Note: The formatting (colour, bold, italic etc.) in the examples here has been added to aid readability, and is not a feature or requirement of text data files themselves.

Editing models as text in the OrcaFlex user interface

The text data representation of an OrcaFlex model can be viewed and edited using the edit data as text item on the model menu.

YAML file format

Text data files use a standard file format called YAML and should be saved with the .yml file extension. The YAML file format was chosen because it is extremely easy to read and write.

YAML files are plain text files and so can be edited in any text editor. We have found Notepad++ to be a very effective editor for YAML files. Notepad++ has a tabbed interface for easy editing of multiple files and has code folding and syntax highlighting facilities that work well with YAML files.

Note: YAML files must be saved with the UTF-8 character encoding.

More details on the YAML format and Notepad++ can be obtained from the following web sites:

Elements of a text data file

The most basic element of a text data file is the name/value pair:

UnitsSystem: SI

The name (UnitsSystem) is written first, followed by a colon (:), then a SPACE, and then the value (SI). The names used in text data files are the same as used to identify data items in batch script files.

Names and values in YAML files can contain spaces and other punctuation:

Lines:
  - Name: 12" Riser
  - Name: Umbilical, upper
  - Name: £"!\$%^&*(){}[]=+-_#~'@:;/?.>,<\|

This example also contains a list. New items in a list are introduced by a dash (-) followed by a SPACE. Items in a list can span more than a single line:

Lines:
  - Name: Riser
    TopEnd: End B
    ContentsDensity: 0.8
  - Name: Umbilical
    TopEnd: End A
    ContentsDensity: 0.0

Outline indentation is used to delimit blocks in a YAML file. This concept, known as significant indentation, is perhaps a little unusual as most data formats and programming languages use symbols to indicate the beginnings and ends of blocks. To understand this better consider the following example:

General:
  UnitsSystem: SI
  DynamicsSolutionMethod: Implicit
Environment:
  WaterDepth: 80

The two lines immediately following General: which are indented by two spaces, form a single block. This block is ended by Environment: because it is not indented. A second block follows Environment: containing a single name/value pair which defines the water depth.

Indentation must be made with SPACE characters rather than TAB characters. It does not matter how many spaces are used so long as the indentation is consistent within each block. However, it is good practice to use the same indentation throughout a file. OrcaFlex itself uses indentation of two spaces when it writes YAML files.

Lists are commonly used to represent tables of data:

Lines:
  - Name: Line1
    LineType, Length, TargetSegmentLength:
      - [Line Type1, 60, 5]
      - [Line Type1, 40, 2]
      - [Line Type2, 120, 10]

The name LineType, Length, TargetSegmentLength indicates three columns of data, LineType, Length and TargetSegmentLength which are interpreted in that order. The comma (,) character is used as a separator. Note that you do not have to present the data in the same order as it appears in OrcaFlex. The following example is equivalent to the previous example:

Lines:
  - Name: Line1
    Length, TargetSegmentLength, LineType:
      - [60, 5, Line Type1]
      - [40, 2, Line Type1]
      - [120, 10, Line Type2]

You can, if you wish, omit columns, in which case default values will be used:

Lines:
  - Name: Line1
    LineType, Length:
      - [Line Type1, 60]
      - [Line Type1, 40]
      - [Line Type2, 120]

Some data are closely related to each other and can naturally be grouped in a text data file:

3DBuoys:
  - Name: 3D Buoy1
    InitialPosition: [0, 0, 10]
    DragArea: [100, 100, 30]
    Pen: [4, Solid, Yellow]

Without grouping the file would be significantly longer:

3DBuoys:
  - Name: 3D Buoy1
    InitialX: 0
    InitialY: 0
    InitialZ: 10
    DragAreaX: 100
    DragAreaY: 100
    DragAreaZ: 30
    PenWidth: 4
    PenStyle: Solid
    PenColour: Yellow

The majority of grouped data are X,Y,Z components and we adopt the convention that these components appear in that order when grouped.

YAML files may contain comments which are introduced by a hash (#) character followed by a SPACE. All subsequent text on the same line is comment and is ignored when OrcaFlex reads a text data file. Comments are not preserved by OrcaFlex and any user comments in a manually edited YAML file opened with OrcaFlex will be lost if the file is saved. Comments are formatted in green in the following example:

General:
  # Statics
  BuoysIncludedInStatics: Individually Specified
  # Dynamics
  StageDuration:
    - 8
    - 16
  TargetLogSampleInterval: 0.1
  # Integration
  DynamicsSolutionMethod: Implicit
  ImplicitConstantTimeStep: 0.1

A text data file can be rather large, particularly if it contains vessel hydrodynamic data. Code folding editors can help somewhat, but even so such files can be awkward to work with. The IncludeFile identifier allows you to move data into a separate file which is then included in the main file:

# File: C:\Desktop\main.yml
VesselTypes:
  - Name: FPSO
    IncludeFile: FPSO.yml
Vessels:
  - Name: Vessel1
    VesselType: FPSO

The included file contains just the data for the vessel type:

# File: C:\Desktop\FPSO.yml
Length: 240
RAOResponseUnits: degrees
RAOWaveUnit: amplitude
WavesReferredToBy: period (s)
# ... remainder of large file omitted ...

As well as making the main file shorter and more readable, using this approach can offer significant QA benefits. The included file can be a text file or a ZIP file containing a single text YAML file.

In this example we have used a relative path and so OrcaFlex will look for FPSO.yml in the same directory as the main text data file.

A text data file saved by OrcaFlex contains some extra information:

%YAML 1.1
# Program: OrcaFlex 9.3a
# File: C:\Desktop\untitled.yml
# Created: 12:35 on 21/07/2009
# User: kevin
# Machine: crusher42
---
General:
  # Statics
  BuoysIncludedInStatics: Individually Specified
  # Dynamics
  StageDuration:
    - 8
    - 16
  TargetLogSampleInterval: 0.1
  # Integration
  DynamicsSolutionMethod: Implicit
  ImplicitConstantTimeStep: 0.1
Environment:
  # Seabed
  SeabedType: Flat
  WaterDepth: 100
  SeabedModel: Linear
  SeabedNormalStiffness: 100
  # Current
  RefCurrentSpeed: 0.4
  RefCurrentDirection: 180
...

The section between the --- and ... lines is the main body of the file and is known in YAML terminology as a document. Everything else is in fact optional and can be omitted. A YAML file can contain multiple documents, separated by --- lines but OrcaFlex has no special treatment for such multi-document files and all data are read into a single OrcaFlex model.

The first line (%YAML 1.1) is known as the YAML directive and specifies which version of YAML the file adheres to. The YAML directive can be omitted. The rest of the header contains a number of comments detailing the version of OrcaFlex which created the file, the file name etc. Again, these comments can be omitted.

Ordering issues

The order in which the data appear in a text data file is very important. OrcaFlex processes the file line by line in the order in which it appears in the file.

Any references (e.g. lines referring to line types) must be ordered so that the referenced object appears before any references to it. So line types appear before lines in the file. Similarly vessels and 3D/6D buoys appear before lines, links, winches and shapes so that any connection references (e.g. a line connected to a vessel) can be ordered correctly.

The other ordering issue relates to inactive data. Data which are not currently available are known as inactive data. For example, data relating to the explicit solver are inactive when the implicit solver is selected. Inactive data cannot be specified in a text data file.

This rule has implications for the order in which data are presented in the text data file. Consider the following example:

General:
  InnerTimeStep: 0.01
  DynamicsSolutionMethod: Explicit

Since the default integration method is the implicit solver the attempt to set the explicit time step (InnerTimeStep) will fail because it is inactive data. The solution is to set the integration method before setting the time step:

General:
  DynamicsSolutionMethod: Explicit
  InnerTimeStep: 0.01

This principle applies in general – you should set as soon as possible all data which influences whether other data are active.

Automation

Text data files can easily be modified and/or generated by computer programs/scripts. This means that the text data file format, combined with a text processing script language (e.g. Python, Perl, Ruby etc.), can form a very effective automation tool. The OrcaFlex spreadsheet provides a simple, yet effective, facility for automating the production of text data files. A common automation task is to make systematic variations to a base case; this can readily be achieved via the use of variation models. The automation topic text data files: examples of setting data has various examples of setting model data items using variation files. Another specialist automation feature is the expression evaluator. To create a base file for automation, or to discover data names and data structure for an object, we would recommend that you start by using the OrcaFlex user interface. The text representation of your model can then be viewed and edited using the edit data as text item on the model menu.

Updating issues

Some data items are interpreted with respect to the values of other data in the model – for example connection data. The way such data are handled can make certain automation tasks difficult. Consider the following simple example consisting of two YAML input files, base.yml and rotation.yml:

# base.yml
Vessels:
  - Name: Vessel1
Lines:
  - Name: Line1
    EndAConnection: Vessel1
    EndAX: 45
    EndBX: 90

# rotation.yml
BaseFile: base.yml
Line1:
  EndAConnection: Fixed
Vessel1:
  InitialHeading: 45
Line1:
  EndAConnection: Vessel1

The idea here is to rotate the vessel, but leave the line in the exact same position, with respect to global axes, that it was in before the rotation. Unfortunately the above files do not achieve this, because updates to the position and connection are postponed until the entire file loading process has been completed. This can be very counter-intuitive since the same actions, carried out interactively in the GUI behave as expected. We have illustrated the point here with connection data, but a few other data items also suffer from this problem.

The solution is to force OrcaFlex to update the model fully after each item has been read from the YAML file. This can be achieved by setting a special attribute of the General object named UpdateModelWhilstReadingFile, as illustrated below:

# rotation.yml
BaseFile: base.yml
General:
  UpdateModelWhilstReadingFile: True
Line1:
  EndAConnection: Fixed
Vessel1:
  InitialHeading: 45
Line1:
  EndAConnection: Vessel1

This setting is disabled by default because it does affect load performance. So for a very large YAML file it is not desirable to enable this. However, for a small YAML variation file, the impact is negligible. So, it makes sense to use this feature as a matter of course for text data file automation.

Expression evaluator

OrcaFlex can understand mathematical expressions in text data files. An expression is indicated by the presence of a prefixed equals sign.

General:
  StageDuration:
    - =4+3
    - =5*(4+3)

This file specifies a model with two stages of duration 7 and 35.

In addition you can define named variables. So the previous file could also be written as follows:

Variables:
  BuildUp: 7
  Stage1: =5*BuildUp
General:
  StageDuration:
    - =BuildUp
    - =Stage1

The expression evaluator supports the following operators:

The comparison operators evaluate to 1 if the condition is satisfied, otherwise to 0. These operators will invariably be used with the conditional function if(X, Y, Z).

The pre-defined constant pi can be used to express the value $\pi$. In addition, a number of pre-defined functions are supported:

Function Description
abs(X) The magnitude or absolute value of X
sgn(X) The sign of X, evaluates to -1 if X<0, +1 if X>0, 0 if X=0
rand A random number between 0 and 1
if(X, Y, Z) The conditional operator, evaluates to Y if X≠0, Z if X=0
round(X) The nearest integer to X
floor(X) The largest integer not greater than X
ceil(X) The smallest integer not less than X
pow(X, Y) XY, equivalent to the exponentiation operator X^Y
sqrt(X) The square root of X
exp(X) The exponential function, eX
ln(X) The natural logarithm, loge
log10(X) Logarithm to base 10, log10
deg(X) Converts from radians to degrees, evaluates to $\frac{180}{\pi}$ X
rad(X) Converts from degrees to radians, evaluates to $\frac{\pi}{180}$ X
sin(X) The sine of X
cos(X) The cosine of X
tan(X) The tangent of X
asin(X) The inverse sine of X
acos(X) The inverse cosine of X
atan(X) The inverse tangent of X
atan2(Y, X) The two argument version of the inverse tangent.
sinh(X) The hyperbolic sine of X
cosh(X) The hyperbolic cosine of X
tanh(X) The hyperbolic tangent of X
asinh(X) The inverse hyperbolic sine of X
acosh(X) The inverse hyperbolic cosine of X
atanh(X) The inverse hyperbolic tangent of X