|
Variation models |
|
|
Variation models |
A variation model is specified entirely in terms of the differences between itself and another OrcaFlex model – the parent model. This differs from the usual concept of an OrcaFlex model, in which all the data specifying an analysis is held within a single model.
The differences defining a variation model are most concisely expressed in YAML text data file format. The main benefit of this is that it permits collections of minor variations to be set up from a single parent model. This is an efficient aid to automation tasks because only those data items which differ from the parent model are present in the text data. This means that you can make modifications to the parent model, and then those changes are automatically inherited by the variation models.
Variation models form a distinct class of model type compared to standard OrcaFlex models and come with additional functionality, change tracking, to identify those data items that differ versus the parent model. The difference between a variation model and a standard model is in how the model data is stored and presented; fundamentally, the model could be expressed in either format and the results of the analysis would be the same. Both of these model types differ fundamentally from the third class of OrcaFlex models, restart analyses, which can be understood as an advancement on a variation model which also inherits simulation state from the parent analysis. A restart analysis is not generally equivalent to a standard or variation model. A given OrcaFlex model can be identified as a variation model (as opposed to a standard model or restart analysis) from the model type displayed on the general data form. If it is a variation model (or restart analysis), then the parent model is shown here also.
In terms of terminology, we find it easiest to refer to the base file, against which changes are tracked, as the parent model; whereas, the variation (or restart) model is known as the child model. Chains of variation models (and restarts) can be set up, allowing for variations upon variations, etc. In such a chain, a given model can be both a parent and a child. We refer to the first model in the chain – the one from which all others ultimately derive – as the ultimate parent.
As already indicated, variation models are most naturally expressed as text data. The following YAML example illustrates the concept:
# variation.yml
BaseFile: parent.dat
Environment:
WaveTrains:
Wave1:
WaveHeight: 2.2
When this text data file is loaded in OrcaFlex, the program does the following:
The BaseFile identifier differs from IncludeFile in that it is able to load either binary or text data files (IncludeFile only works with text data files). In addition BaseFile clears all existing data in the model before loading the contents of the specified file. On the other hand, IncludeFile acts incrementally, starting from whatever state the model is in when the IncludeFile identifier is encountered.
Variation models can be created from the file menu in OrcaFlex, and also via the OrcFxAPI programming interface; they can also be created manually in a text editor. However, once a variation model has been created, the choice of parent model becomes fixed and cannot be directly changed in the user interface. It can, however, be changed by editing the text data file representation or using the edit data as text capability that is built into the user interface. Editing a variation text data file by hand in a text editor is a good way to create a base file for automation, or to discover data names and data structure for an object. Variation models can be also be converted into standard OrcaFlex models, if required, although this means that all the data from the parent is copied into the child model and any subsequent changes to the parent model will have no effect on the child.
| Warnings: | Variation files can also be saved using binary data file format. This is not recommended because it leads to a copy of the parent model data being stored in the file, which means that any changes made in the parent model will not be inherited when the child model is opened. The binary data format is only intended to be used to save variation data when dealing with text file incompatibilities between different OrcaFlex versions. The text file format is recommended in all other situations. A further subtlety of binary data files is that the tracked changes are written to the file based on the data name of the value that has changed. For technical reasons, these may occasionally need to be modified in future versions of the software. This means that a binary file containing change tracking data is not guaranteed to load successfully in all future versions of OrcaFlex. |
| Older versions of OrcaFlex can also read in text data files with the BaseFile keyword but these would be interpreted very differently. Previously, such a variation file would have been loaded as a standard OrcaFlex model, meaning that this was strictly a one way process: saving the file again would overwrite the original variation model with a standard text data file, exporting each object and including any default values. Consequently, the save process was not the inverse of the load process and any manual modifications to the input file would have been overwritten when the file was saved by OrcaFlex. With new style variation models, the process is bijective and OrcaFlex is capable of writing variation text files as well as reading them. |
Standard text data files typically specify the entire model, whereas a variation file only specifies differences. The common automation task of making systematic variations to a base case requires the ability to specify an existing object for which data modifications are to be made. This is done using the object's name:
BaseFile: parent.dat
Vessels:
Deleted: FPSO
Lines:
New: MooringChain
Riser:
Length[1]: 180
When this text data file is loaded in OrcaFlex the program does the following:
It is a common requirement to delete certain objects that were in the parent model or to modify data for certain items in a list or table without specifying the entire table. The indexing syntax (Length[1] in the example) performs this task. Note that, as for batch script files, the indices are always 1-based.
| Note: |
In older versions of OrcaFlex (before the variation model type was introduced) the above YAML example would have been written slightly differently: BaseFile: parent.dat The new format is more powerful and can support a wider paradigm; however, the old format is still supported for convenience. |
As well as the New and Deleted keywords, another useful keyword is Order. This is used to specify the order of a group of named objects within a list, as in the following example:
BaseFile: parent.dat
VesselTypes:
FPSO vessel type
Draughts:
Order:
- Draught2
- Draught1
Opening this file would ensure that "Draught2" appeared before "Draught1" when viewing the vessel types data form. The automation topic text data files: examples of setting data has various other examples of setting model data items.
The data in a new variation model is effectively the same as in the parent model. Opening a data form and changing a data item, e.g. WaterSurfaceZ on the environment data form, will result in that data item being highlighted. By default, this takes the form of a red line (this colour is a user preference) around the boundary of the relevant data control. We say such data items are marked as changed.
| Figure: | A single data item marked as changed |
When the variation file is saved, only those data items that are marked as changed (with a few exceptions described below) are written to the text data file:
BaseFile: parent.dat
Environment:
WaterSurfaceZ: 10
New model objects, added relative to the parent model, have their whole data form marked as changed, rather than each individual data item being highlighted.
| Figure: | A newly added model object marked as changed |
Sometimes, especially when the variation file defines a restart, it is desirable to artifically mark unchanged data items as changed. This can be achieved by highlighting the data item(s), right-clicking and selecting the always mark selected items as changed option from the popup menu. Items that have been manually marked as changed are output to the text variation file with a '*', as can be seen in the following example:
BaseFile: parent.dat
Vessels:
Vessel1:
InitialHeel*: 13
InitialTrim*: 17
InitialHeading: 45
Here, the initial heel and trim of "Vessel1" have been marked as changed but the initial heading has not. The initial heading must have been different from its value in the parent model for it to have been output to the variation file; it is not possible to tell whether the initial heel and initial trim have actually changed their values because they would have been exported in either case.
Also on the popup menu is an option called restore selected data items to original value, which sets the data back to its value in the parent model and removes any change tracking highlighting. This only works for data items that were available in the parent model.
For purposes of change tracking, all data items that were not available in the parent model, but become available in the child, are treated as having changed. Similarly, all data items on newly added objects (those that were not in the parent model) are also treated as changed. Data items that are read-only also get marked as changed if their read-only value differs (compared to the equivalent parent model value) because of changes to other data items. Mostly, such read-only data items are not output to the YAML text file anyway, but it can be helpful to see that the value of such items is different from that in the parent model.
Opening variation files with large parent models can take a long time due to the overhead of change tracking. In our experience this issue is uncommon, but if you do encounter delays when opening variation models it may be productive to disable change tracking for these variation files. This can be done by modifying the text data file in a text editor by replacing BaseFile with BaseFileNoTracking. When such a file is opened, OrcaFlex does not track changes, which means that the file can be loaded more quickly. However, because change tracking has been disabled, if you open such a file, and then save it, the entire model data will be saved, rather than just the tracked changes from the parent. Because of this, if you are going to use BaseFileNoTracking then you should edit the data in a text editor and not in the OrcaFlex GUI.
Issues can arise when a connection is permanently changed. For instance, creating a variation model from base.yml, then setting EndAConnection to fixed, results in EndAConnection being marked as changed but the associated connection coordinates (e.g. EndAX) remaining unchanged. When connected to the same object as in the parent model, the rest of the connection data (positions and orientations) are treated exactly like any other data items: their values are tracked relative and with respect to the axes of the parent object in the connection. This means that moving the parent object (Vessel1 in this particular case) leaves the child object's position and orientation connection data unchanged. However, this policy no longer applies when we change the parent object to which the child is connected (e.g. changing EndAConnection from Vessel1 to fixed). If this happens, change tracking of the position data takes place against the original global position and orientation of the child object in the parent model, but with respect to the axes of the new parent object. This means that changing EndAConnection from Vessel1 to fixed does not result in data items like EndAX becoming marked as changed, even though their numerical values do change: it is because the global position of End A of the line has not changed.