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