Restart analyses

Restart analyses, along with standard and variation models, are one of three types of OrcaFlex model. Whilst a restart analysis tracks its changes against a specified parent model, in the same way that a variation model does, there the similarity ends. From an analysis perspective, restart analyses are conceptually distinct from either of the other two model types. A standard OrcaFlex model behaves in exactly the same fashion as an equivalent variation model once the analysis begins; they only differ in the way that the model data is input and presented. A restart analysis behaves differently: instead of simply running the model with the specified data, it will first load the parent simulation file and inherit as much state (e.g. the positions of objects) as possible, before attempting to pick up where the parent analysis left off. This is not simply the same as extending an existing model because the change tracking architecture allows for changes to be made to the model data before restarting. This capability makes restart analyses much more powerful: in principle, every property of the model could be changed (although not all changes are permitted in practice), e.g. friction coefficients, object positions and even the masses of objects. Objects can even be created and deleted in the restart analysis.

A restart analysis can comprise either a static analysis, a dynamic analysis or both, and can inherit state from either static state analyses or time domain dynamic analyses. Chains of restarts can be constructed, with each link in the chain inheriting from its immediate predecessor. Restarts are easiest to describe using the same parent model and child model terminology that is used to describe variation models. The basic idea is to first create a base model – the ultimate parent – and then to define a child restart file that inherits from this, possibly changing some of the properties and features in the model at the same time. Once the initial child model has been defined, subsequent children – grandchildren, as it were – can be defined in a similar way, each time specifying which parent model to start from and which data will change. In this way, chains and hierarchies of restart analyses can be created, with parent models having multiple child models and these, in turn, having child models of their own, etc.

Note:

Frequency domain restarts are fully supported provided that they occur immediately following a valid static analysis. This static analysis can either take place in the restart itself or be loaded from a parent static state .sim file. However, parent models can never themselves be frequency domain analyses and no further restarts can take place further down the chain once a frequency domain analysis has been performed.

Restart analyses can be created in OrcaFlex by selecting the new restart analysis option on the file menu. You will then be prompted to choose which parent model you wish to restart from. Whilst the restart analysis inherits from the parent .sim file, the parent model shown at the top of the general data form is always an OrcaFlex data file (.dat or .yml). The reason for this is twofold: firstly, the parent simulation file (.sim) file may not exist when the restart model is being built; secondly, .sim files can be associated with both .dat and .yml data files of the same name, so specifying a .sim file as the parent model causes ambiguity when OrcaFlex compares the restart data against the parent model (since files with both .dat and .yml extensions could potentially coexist).

Warning:

We generally advise that the child and parent models of a restart analysis should be run in the same version of OrcaFlex. Newer versions of the software may behave differently to older versions, e.g. due to bug fixes or other code changes (as documented on the what's new page). In some cases, it may be clear that a difference between versions is relevant to your analysis, but in other cases it can be more subtle, especially if the changes from several versions are combined together. The best practice is to run both parent and child models in the latest available version of OrcaFlex.

Uses of restart analysis

Restarts can be useful for a variety of modelling tasks that would otherwise be difficult or impossible to achieve in a standard OrcaFlex analysis. Examples include:

Sometimes one has a suite of models that differ only in their dynamic behaviour, but whose static configuration is common to all the models in the suite. If the statics calculation is slow to converge and takes a long time to run, then a lot of time will be wasted repeating the calculation when batch processing the entire suite. With restart analyses, the static calculation can be performed once only, in a parent model, and then multiple dynamic-only child models can restart from this (each one loading the same static state parent simulation file, rather than recalculating). This is an example of a restart scenario in which no additional physical property changes would be made prior to restarting.
Although OrcaFlex has many features to improve statics convergence, some models can still present significant challenges for static analysis. A series of static restart analyses can often be used to resolve such problems. For instance, you might apply a vessel offset in a series of static restarts, and then introduce current in the final static restart.
Restarts can be used to build up a friction history in a series of successive static analyses. Each analysis would perturb the previous one in a small way (e.g. by slowly changing the current in the model, or dragging the end of a line to a slightly different location), gradually building up to the final static equilibrium required, in a way that more accurately accounted for frictional forces than a single standard analysis.
The same concept could be applied to other history dependent load models, e.g. hysteretic line stiffness (axial, bending or torsional), hysteretic constraint stiffness, nonlinear soil model, etc.

Simple example

It is easiest to understand how a restart works by describing a simple example composed of two data files, parent.yml and restart.yml:

# parent.yml
General:
  StaticsEnabled: No
  StageDuration: [2]
  DefaultViewSize: 150
  DefaultViewCentre: [0, 0, 50]
Environment:
  WaveTrains:
    - Name: Wave1
      WaveHeight: 0
3DBuoys:
  - Name: Blob
    InitialPosition: [0, 0, 100]

# restart.yml
RestartingFrom: parent.yml
3DBuoys:
Blob:
InitialX: 50

Here parent.yml defines a standard OrcaFlex model, which simply creates a default 3D buoy named "Blob" and positions it $100\textrm{m}$ above the global origin; it also disables the static analysis. Of course, all that happens when this model runs is that the buoy begins to fall! It will fall for the $2\textrm{s}$ of simulation time that is defined by the StageDuration data. At the end of this simulation, "Blob" will be roughly $80\textrm{m}$ above the sea surface and be travelling vertically downwards at a velocity of approximately $20\textrm{m/s}$.

A restart from parent.yml is then defined in restart.yml. At the top of restart.yml is the line "RestartingFrom: parent.yml". The keyword RestartingFrom is how OrcaFlex knows that this file defines a restart analysis (c.f. the very similar BaseFile keyword that defines the analogous variation model). Since the static analysis was disabled in parent.yml, it remains disabled in restart.yml (you could re-enable it in restart.yml by including the line "StaticsEnabled: Yes"); so, restart.yml defines a dynamic only restart. Other than this, the only material change defined by restart.yml is to move the 3D buoy $50\textrm{m}$ along the global X-axis. What is the effect of this data change?

If the restart analysis had not set InitialX, then the restart simulation would simply pick up where the parent simulation left off. Running restart.yml would attempt to reload the state of "Blob" (e.g. its position, velocity) from the file parent.sim. If parent.sim cannot be found, then an error would be raised (parent models must be run before their children – the batch calculation form arranges this automatically). If no error is raised, then the restart analysis would be the same as simply loading parent.sim as a standard OrcaFlex model and extending the simulation by $2\textrm{s}$. "Blob" would continue to fall from the same position and velocity that it had at the end of parent.sim.

The actual child restart model behaves in a similar manner to the extended case but, instead of "Blob" continuing from its position in the parent model, it is first translated by $50\textrm{m}$ along the global X-axis before it continues to fall. Note that the $Z$ coordinate of "Blob" still begins the restart simulation with the same value with which it ended the parent (as does the vertical velocity); it is just the $X$ coordinate that changes. If, instead of setting InitialX in restart.yml, we instead set InitialZ, then this new $Z$ coordinate would be applied at the start of the restart instead (but with the vertical velocity unchanged).

If restart.yml is viewed in OrcaFlex, then (analogously to a variation model) the general data form will display that this model is of the restart analysis type and that it has a parent model named parent.yml.

Looking at the analysis page shows several read-only data items marked as changed. The origin of these marked changes is that the start time and first stage are both '~', which means that both actual start time and actual first stage pick up where the parent simulation left off (so have different values from those in the parent data file). The actual start time is $0\textrm{s}$ because the parent simulation ran from $-2\textrm{s}$ to $0\textrm{s}$. The actual first stage takes the value of $1$ – the next available stage after the parent model – because stage $0$ had already been defined in parent.yml.

Figure:

General data form for restart.yml

The restart from time was not specified in the data in restart.yml and defaults to '~'. This means that the child analysis is restarted from the end of parent analysis. Values other than ~ can be specified to perform mid-simulation restarts, provided that the parent model records restart state at the specified restart from time.

When opening up the 3D buoy data form for "Blob", it can be seen that the InitialX data item is highlighted as marked as changed. Note also that the InitialY and InitialZ data items are also highlighted, albeit in a different colour. This is because InitialY and InitialZ are being flagged up as potentially ignored data items. This highlighting is purely cosmetic and merely informs you that the value of the highlighted data item may not be respected by the restart analysis because it might instead be inherited from the appropriate value at the end of the parent simulation.

Figure:

"Blob" data form for restart.yml

You might ask, if the InitialZ data has to be changed relative to the parent model in order for its value to take effect (and override the value in the parent simulation), then how would one restore "Blob" to its starting Z position of $100\textrm{m}$ above the sea surface? Simply setting InitialZ to $100$ means that it would have the same value as in the parent model and not be marked as changed. The solution is to manually mark InitialZ as changed using the always mark selected items as changed item on the popup menu for that data item. It would then result in a restart data file that looked like this:

# restart.yml
RestartingFrom: parent.yml
3DBuoys:
  Blob:
    InitialX: 50
    InitialZ*: 100

where the '*' indicates that InitialZ has been manually marked as changed.

Figure:

InitialZ manually marked as changed

Analysis data

As purported above, the analysis page of the general data has several items that have a special relevance in a restart analysis: start time, first stage, ramp start time and ramp finish time. Setting each of these data to ~ has a special meaning for restart analyses, which is explained in the analysis data documentation. The purpose of the ~ values is to make it easier to construct chains of restart analyses by establishing continuity between a child restart model and its parent. Sometimes, you may wish to override this behaviour; this can be achieved by instead setting bespoke values for these data items.

Validity of restart analyses

Whilst almost all changes to an OrcaFlex model can be tracked in a variation model or restart analysis, not all of these changes are permitted when it comes to actually performing a restart calculation. Some of these will always remain blocked because they correspond to unphysical or nonsensical changes; other are blocked at present because of technical considerations, but may be enabled in future versions of OrcaFlex.

Blocked features

Restarting from a frequency domain parent analysis.
Frequency domain restarts from a parent dynamic analysis without an intervening statics analysis.

Blocked data changes

Units.
Nonlinear soil model data.
Line length, sections and segmentation.
Line initial end arc lengths.
Line inclusion of torsion.
Line attachment data.
Changing line representation from analytic catenary to finite element.
Line time domain VIV model data.
Vessel primary motion is treated as and dividing period.
Turbine blade count.
Turbine blade length and segmentation.
Changing the turbine UA model between González and Minnema Pierce.

In addition, it is important to note that the parent simulation file (.sim) should be commensurate with the parent data file (.dat or .yml) and must have been run to completion before the child restart analysis occurs. OrcaFlex performs some checks to confirm that these conditions are met but, ultimately, responsibility for this lies with the user. When running a chain of restarts in the batch processing facility, OrcaFlex automatically detects the order of dependencies and ensures that the parents are analysed before their children.

Object connections

As well as changing the position and orientation of an object during a restart, it is also possible to change its connection: an object that was free in a parent model could become fixed in the child model, or even connected to another object; likewise, an object that was connected in a parent model could become free in the child. In addition, the behaviour of an object in a restart analysis depends upon whether its coordinates are marked as changed. Once an object's connection has changed, change tracking of object position and orientation data is handled in a bespoke fashion: differences are tracked by comparing the current coordinates to the original position/orientation of the object relative to the global origin but expressed with respect to the axes of the current parent object. This is necessary because the meaning of the object's position and orientation data changes when the connection has changed. If the standard change tracking policy were used for these data items, then a change to the connection would automatically result in the associated coordinates being marked as changed. Adopting a bespoke policy gives users more precise control over the restart behaviour because changing just the connection does not immediately mark the coordinates as changed.

The following procedure occurs for each object when the restart analysis is run:

A check is made to see if the object was also in the parent model. If it was, then as much simulation state as possible is recovered from its counterpart in the parent model, including its position, orientation, velocity and acceleration.
If the connection has changed, then the object is connected to its new parent at the position and orientation loaded from the parent simulation file. If the object's connection is free after this process, then its velocity and acceleration remain at the values inherited from the parent model; otherwise, the velocity and acceleration will change to be consistent with the motion of the new parent object to which it is now connected.
Any coordinate data items that have been marked as changed are then re-applied, overriding the values that were inherited from the parent simulation file. The velocities and accelerations are not changed from their earlier values.

Note:

One potential source of confusion in the above terminology is the use of the words parent and child in two separate contexts: as discussed, the restart analysis and the model from which it will restart are often referred to as the child and parent models, respectively; similarly, if an object is connected to another object, e.g. by setting Buoy1's connection to Vessel1, then the first of these objects (Buoy1 in the example) is referred to as the child object and the second (Vessel1 in the example) is referred to as the parent object. It is important to realise that the latter connection terminology applies to objects that exist together within a single model.

Warning:

Step 2 may result in an instantaneous change to the velocity of an object if its connection changes to anything other than free. This change will be unphysical because it will violate conservation of energy and momentum.

The above scheme is a little complex and is best illustrated by another example:

# parent.yml
General:
  DynamicsSolutionMethod: Explicit time domain
  StageDuration: [5, 20]
Environment:
  WaveTrains:
    - Name: Wave1
      WaveHeight: 0
Vessels:
  - Name: Vessel1
    InitialPosition: [0, 0, 0]
    PrimaryMotion: Prescribed
    SuperimposedMotion: None
    PrescribedMotionMode, PrescribedMotionSpeedValue, PrescribedMotionDirectionRelativeTo, PrescribedMotionDirectionValue, PrescribedMotionRateOfTurn:
      - [Speed change, 5, Vessel heading, 0, 0]
      - [Constant speed, 5, Vessel heading, 0, 0]
6DBuoys:
  - Name: 6D buoy1
    Connection: Vessel1
    InitialPosition: [0, 0, 30]

# restart.yml
RestartingFrom: parent.yml
General:
  StaticsEnabled: No
  StageDuration: [20]
Vessels:
  Vessel1:
    PrescribedMotionMode, PrescribedMotionSpeedValue, PrescribedMotionDirectionRelativeTo, PrescribedMotionDirectionValue, PrescribedMotionRateOfTurn:
      - [Speed change, 0, Vessel heading, 0, 0]
6DBuoys:
  6D buoy1:
    Connection: Fixed
    InitialZ: -30

In the parent simulation, a 6D buoy is connected $30\textrm{m}$ above the origin of a prescribed motion vessel, at global coordinates $(0,0,30)\textrm{m}$ when the model is in its reset state. The vessel then translates along the positive $X$-axis throughout the parent simulation and, by the end, reaches a position of $(100,0,0)\textrm{m}$, with the 6D buoy at $(100,0,30)\textrm{m}$; both objects are moving with velocity $(5,0,0)\textrm{m/s}$. In the restart analysis (restart.yml), the reset position of the 6D buoy has been changed to $(0,0,-30)\textrm{m}$ (i.e. the $Z$ coordinate has changed from its value of $30\textrm{m}$ in the parent model, to $-30\textrm{m}$ in the child model). This means that the InitialZ data item is marked as changed when restart.yml is viewed in the user interface. When the restart analysis is performed, step 1 of the above scheme begins by moving the 6D buoy to its position at the end of the parent model, $(100,0,30)\textrm{m}$, with velocity $(5,0,0)\textrm{m/s}$. Step 2 then takes effect, and the fixed connection is reasserted. This does not affect the position of the buoy, which remains at $(100,0,30)\textrm{m}$; however, a velocity of $(5,0,0)\textrm{m/s}$ is inconsistent with a fixed connection, so it must be zeroised. Step 3 is then applied, which accounts for InitialZ being marked as changed by altering the $Z$ coordinate of the buoy accordingly. At this point, the coordinates of the buoy are $(100,0,-30)\textrm{m}$ and its velocity is $(0,0,0)\textrm{m/s}$. The restart analysis will now proceed from this starting condition. Since the buoy's connection is now fixed, it will remain at this position throughout the duration of the restarted simulation. The vessel continues its prescribed motion and ends the restarted simulation at coordinates $(212.5,0,0)\textrm{m}$, having effectively jettisoned the 6D buoy at the start of the analysis. Note that the momentum accumulated by the 6D buoy in the parent simulation has been completely lost in the restart.

Transferring parent model state

If no data changes have been made between a restart analysis and its parent model, then all the state from the parent model is transferred into the child before the restart analysis is performed. This means that the restart picks up from exactly where the parent analysis left off, just like extending an existing simulation. Examples of such state include friction target positions, hysteretic bending history, vessel added mass and damping convolution integrals, etc.

If data changes have been made, then OrcaFlex will still attempt to transfer any relevant state from the parent model. However, in practice, certain data changes may either render the parent state redundant or else be completely incompatible. In such cases, OrcaFlex will either:

Import as much state as possible and continue.
Neglect the relevant history and restart that particular aspect of the model from scratch.
Block the analysis from proceeding any further.

Which policy is adopted depends upon the particular aspect of the model in question and the nature of the data that has changed.

Results for restart chains

Results for the chain of restart analyses can be collated and presented in a single graph or table. When selecting results, check the include restart parent models option and select which restart parent models you wish to include. Only models further up the chain can be selected, so typically you would load the simulation file of the final child restart model when collating results.

When collating results, OrcaFlex will use whatever simulation time values are defined in the selected models. If the time values are disjoint, or overlapping, then the collated results may look confusing or garbled. In order to get the most out of these feature you should try to arrange that the simulation time values are at least monotone increasing, and preferably contiguous.

This feature can also be used for static restarts. Again, you must take care to specify the simulation times for the restart chain. For a chain of static restarts, the simulation times can often be set to arbitrary values and just act as labels. For instance, the initial analysis might have time $0\textrm{s}$, the first restart time $1\textrm{s}$, the second restart time $2\textrm{s}$, etc. When the simulation times are arranged like this, you can use collated time history graphs to view the progression of chosen results variables through the chain of static restarts.

Replays for restart chains

In a similar fashion, replays for the chain of restart analyses can be shown. You must selected the restarts replay type, and then specify which restart parent models you wish to include, and the simulation time period.

Just as was the case for results, it can be important to choose simulation times in your restart models carefully. Doing so allows you to specify which part of the restart chain is to be replayed conveniently using simulation time. Replays of static restarts are supported.