General data: Restart state

A restart analysis can restart either from the end of the parent analysis, or from a specified time in the parent analysis. This latter option is known as a mid-simulation restart. In order to perform a restart analysis, OrcaFlex must restore the entire calculation state from the parent analysis, at the point of restart. This state is known as the restart state.

The restart state is stored in the simulation file. Because the restart state is large, it is not stored automatically for each log sample. Instead, you must determine the times at which restart state will be recorded and stored.

Mid-simulation restarts are only possible at times for which the parent analysis has recorded restart state. Restarts from the end of the parent analysis do not require additional restart state to be stored because simulation files already store sufficient state to perform these restarts.

Restart state recording times

This table allows you to define a series of times at which restart state will be recorded. Each row of the table can be used to specify a number of times between start and stop, equally spaced at the specified interval.

If start is set to ~ this is interpreted as the start of the simulation. Likewise, if stop is set to ~ this means the end of the simulation. Because restart state is recorded at log samples, if the restart state recording interval is less than the log sample interval then the times are spaced at the log sample interval. Hence a value of 0 can be used to record restart state at every log sample.

Periodic restart state recording

These data can be used to record up to count ($N$) restart state samples at the specified interval. Only the most recent samples are retained, so once $N$ samples have been recorded, and a new sample is required, the earliest one is thrown away to make room for the new sample.

An example of when this functionality would be useful is to handle simulations that may become unstable. If a handful of restart states have been captured towards the end of the simulation, then you can restart the analysis from one of them, and try reducing the time step to help the dynamic analysis continue successfully.

Restart state recording test

The data above requires restart state recording times to be specified before the simulation begins. It can sometimes be useful to use the output of the simulation itself to determine when to record restart state. The restart state recording test allows you to do this using Python code.

Your Python code must define a function named EvaluateRestartStateRecordingTest which is passed an instance of the Model class representing the current OrcaFlex model. The function must return a Python dict with two bool members named "RecordState" and "PauseSimulation".

This function is called at every log sample time. If "RecordState" is True then restart state is recorded for this time. If "PauseSimulation" is True then the simulation will be paused at this time.

For example:

def EvaluateRestartStateRecordingTest(model):
    return {
        "RecordState": False,
        "PauseSimulation": False,
    }

This example demonstrates the most basic form of the function, but it does not do anything useful because it always returns False for each member of the dict. To do something useful the code needs to interrogate the model, using the model argument, and return values based on the simulation state. For example:

def EvaluateRestartStateRecordingTest(model):
    vessel = model["Vessel1"]
    X = vessel.TimeHistory("X", OrcFxAPI.PeriodNum.InstantaneousValue)[0]
    return {
        "RecordState": X > 10,
        "PauseSimulation": False,
    }

In this example, the instantaneous value of the vessel's X position is obtained. If this value if greater than 10, then restart state will be recorded.

Setting "PauseSimulation" to True is useful when you know that the rest of the simulation is not needed. This allows you to pause a simulation being run via the batch processing form (or Distributed OrcaFlex), which means that it is saved in a partially complete state. Simulation files contain the state corresponding to the last simulation time, so it is possible to restart from a partially complete simulation file, and you don't even need to set "RecordState" to True.

The following example demonstrates this concept:

def EvaluateRestartStateRecordingTest(model):
    pauseSimulation = False
    for obj in model.objects:
        if obj.name.startswith("Mooring"):
            tension = obj.TimeHistory("Effective tension", OrcFxAPI.PeriodNum.InstantaneousValue, OrcFxAPI.oeEndA)[0]
            if tension > 90:
                pauseSimulation = True
                break
    return {
        "RecordState": False,
        "PauseSimulation": pauseSimulation,
    }

This code checks the top tension of each line whose name begins with "Mooring". If the effective tension at end A for any such line exceeds 90, then the simulation will be paused. You could then perform a restart analysis, using this partially completed simulation as the parent, where the mooring line with the largest tension was removed, to simulate a mooring failure.