Heartbeat for year-checkpoint SpaDES simulations

Scans an output directory for files matching the pattern <file_prefix>_year<XXXX>.<ext> (e.g. cohortData_year2920.rds) and returns the furthest simulation year reached, the wall-clock elapsed time since the first checkpoint, and a percentage-complete estimate.

get_sim_year_heartbeat(
  output_path,
  start_year = NULL,
  end_year = NULL,
  file_prefix = "cohortData"
)

Arguments

output_path

Character. Directory to scan for checkpoint files.

start_year

Integer or NULL. Expected start year of the simulation. If NULL (default), inferred as the minimum year found in output_path.

end_year

Integer or NULL. Expected end year. If NULL (default), inferred as the maximum year found in output_path (i.e. 100 % is reported only once the final checkpoint exists). Supply a value (e.g. 3020L) to get a meaningful percentage before the run completes.

file_prefix

Character. Only files whose basename begins with this prefix are used as checkpoint indicators. Defaults to "cohortData" because that file is written after all others at each SpaDES save event, making it the most reliable completion signal.

Value

A named list with elements:

ts

Character. Modification timestamp of the latest checkpoint file.

iter

Integer. Simulation year of the latest checkpoint.

started

Character. Modification timestamp of the first checkpoint file.

elapsed

difftime. Wall-clock time between first and latest checkpoint.

pct_complete

Numeric 0-100. Percentage of the simulation completed, or NA if start_year == end_year.

All elements are NA / NA_character_ when no matching files are found.

Examples

if (FALSE) { # \dontrun{
hb <- get_sim_year_heartbeat(
  output_path = "outputs/6.5/1991-2020/NRV_ssp370/rep1",
  end_year    = 3020L
)
message("Year: ", hb$iter, " (", hb$pct_complete, "%)  -- last checkpoint: ", hb$ts)
} # }