Chapter 15: Snapshots and Restarts

Fred models can be run for a certain period of simulated time, and then be saved so that they can be continued later. The information required to do this is called a snapshot. The continuation of a simulation from a snapshot is called a restart.

Creating Snapshots

Snapshots are files that contains all the information needed to restart a FRED job from a given simulation date. Snapshots are only created at the end of a simulation day.

Snapshot files are large and they take significant time to make, so the user should carefully consider how frequently to take snapshots based on the specific needs of their workflow.

Snapshot files are compressed and are not meant to be human-readable.

The following properties determine the number of snapshots for the job:

simulation {
   snapshots = <n>
   snapshot_final = <n>
   snapshot_date = <date_string>
   snapshot_interval = <n>
}

The number of snapshots for the job is determined by the following rules:

If the property snapshot_final is set, then a final snapshot is always generated.

If the property snapshot_date is set and the simulation reaches the specified simulation date, then the snapshot of that date is generated. It is not set by default. It is a string of the form YYYY-MM-DD, e.g., 2021-03-25.

If the property snapshot_intervals has a value n greater than 0, then snapshots will be generated after every n days. The final periodic snapshot is guaranteed to be kept.

If the snapshots property exceeds the number of snapshots required by the preceding rules, then additional periodic snapshots (if any) will be kept, until the total number of snapshots reaches the value of snapshots, at which point the oldest periodic snapshot will be deleted.

For example, the following property settings will keep the final two weekly snapshots and the final snapshot:

simulation {
    snapshot_final = 1
    snapshot_interval = 7
    snapshots = 3
}

The following property settings will keep the final snapshot, the snapshot on the specifed date, and the final weekly snapshot:

simulation {
    snapshot_final = 1
    snapshot_date = 2022-05-22
    snapshot_interval = 7
}

The following settings will produce a snapshot every 30 days. The last two will be kept.

simulation {
    snapshot_interval = 30
    snapshots = 2
}

Fetching Snapshots

Each run in a FRED job produces its own snapshot, and all run-specific snapshots are rolled into a single snapshot for the job.

The FRED command:

$ fred_get_snapshot -k <key>

fetches the snapshot file for the job with the given key and copies it to snapshot.tgz in the current directory by default. To give the snapshot file another name using the -o option:

$ fred_get_snapshot -k <key> -o <output_file_name>

Restarts

To restart a job from a snapshot, using the -R option to fred_job:

$ fred_job -k <key> ... -R <snapshot_file_name>

The resulting job will be initialized using the given snapshot, and will set the simulation day to the day after the snapshot day. The start_date of the new job must be the same as the start_date of the snapshot job, and the end_date of the new job must be after the snapshot day.

Restart blocks

A model may contain a restart_block to reset variables after a restart.

restart {
    # actions to be performed by the Mate agent
}

The restart block is used to override shared variables after a restart. This block is executed after reading the snapshot files, so the actions in the block will override the settings of any shared variables defined in the snapshot.

It is an error to set a variable in a restart block that is not declared elsewhere in the program in a variables block.

For example, the following restart block overrides the end_date variable, and this extends the simuation to the new end date.

restart {
    end_date = 2022-Dec-31
}

Rules specific to a restart

A FRED model can contain rules that apply only during a restart by using the following predicate:

• is_restart() : returns 1 (true) if and only if it is executed during a FRED restart.

For example,

if (is_restart()) then intervention_policy = new_policy