Analysis persistence#

Use the case attribute of Session to access commands relating to the persistence and overall state of an analysis case:

Saving and opening a case
Saving a case snapshot
Clearing/resetting the entire state

In the code snippets that follow, the case variable is assumed to have been assigned as follows:

case = syc_session.case

Saving and opening a case#

Files defining the state of an analysis case are always saved and loaded from a SyC/ subdirectory which exists, by default, in the working directory.

# Open a case from sub-directory SyC of current working directory:
case.open()
...

Opening a case restores the analysis settings at the time of saving, and loads results data if it exists.

Similarly for saving the current state of a case:

# Save a case to sub-directory SyC of current working directory:
case.save()
...

When saving a case, the SyC directory is created if it does not already exist. Settings data is saved in a file called settings.h5.

If the case has been successfully solved, restart files exist (these are files with names of the form Restart_step<n> or Restart_iter<n>), depending on whether the analysis is a transient or steady cases. The restart files allow the results to be loaded at any point partway through the analysis for which a restart file exists. For example, if results were saved at the end of step 2, then the coupling_step option may be provided to open:

# Open at step 2
case.open(coupling_step=2)

The frequency with which restart files are written during a solution is controlled by the setting setup.output_control.option.

Note

Opening a case at a restart point that is not the final step/iteration causes later restart files to be deleted. Typically, the reason for opening at an earlier point is to re-run the analysis from that point. If it is important to save all of the results, the Case snapshots facility may be used.

The results data itself is stored in the Results subdirectory of SyC.

Case snapshots#

Snapshot capabilities allow you to capture the current state of a coupled analysis as a whole and then later restore the analysis to that state.

Snapshots give you the ability to save and return to a specific point in a coupled analysis.

A snapshot captures the current state of the coupled analysis as a whole (rather than just of the data model). It includes all the files and directories contained in System Coupling’s working directory that are necessary to restore the coupled analysis to its current state — specifically, the SyC subdirectory and the coupling working directories of all loaded coupling participants.

The snapshot facility relies on the SyC directory and the participants’ working directories being subdirectories of the System Coupling working directory.

Snapshots are saved in a subdirectory SyCSnapshots that exists in the working directory alongside the SyC directory. Each snapshot is saved as a zip file. A snapshot named Initial.zip is created automatically when a solve is started (if it does not already exist); otherwise, snapshots are managed on demand using the API commands as discussed below.

The basic operations supported are:

Saving a snapshot
Loading a snapshot
Deleting a snapshot
Querying available snapshots

# solve the current case
solution.solve()
...

# Save the solution as a snapshot
case.save_snapshot(snapshot_name="Solution1")

# Restore the the Initial snapshot from before solve
case.open_snapshot(snapshot_name="Initial")
# Make some changes and solve again
...
solution.solve()
# Save this solution to a snapshot
case.save_snapshot(snapshot_name="Solution2")

# Query snapshots..
case.get_snapshots()
# Returns a dict, snapshot name=>file name
#
# { 'Initial': 'Initial.zip',
#   'Solution1': 'Solution1.zip',
#   'Solution2': 'Solution2.zip' }
#

# Delete Solution1
case.delete_snapshot(snapshot_name="Solution1")

Clearing the current state#

Occasionally, it might be useful to be able to clear the entire state of the settings and results that are loaded in the current System Coupling session.

To do this, call the clear_state command:

case.clear_state()

Another option for achieving the same result is to exit the current session and create a new one:

syc_session.exit()
syc_session = pysystemcoupling.launch()