Gadget3 timekeeping actions — action

Add timekeeping to a g3 model

g3a_time(
        start_year,
        end_year,
        step_lengths = c(12),
        final_year_steps = quote( length(step_lengths) ),
        project_years = g3_parameterized("project_years", value = 0, optimise = FALSE),
        retro_years = g3_parameterized("retro_years", value = 0, optimise = FALSE),
        run_at = g3_action_order$initial,
        run_stop_at = g3_action_order$time)

Arguments

start_year

Year model run will start.

end_year

After this year, model run will stop.

step_lengths

Either an MFDB time grouping, e.g. mfdb::mfdb_timestep_quarterly, or a vector of step lengths which should should sum to 12, for example, c(3,3,3,3) for quarterly steps within a year.

final_year_steps

Number of steps of final year to include. Either as an integer or quoted code, in which case it will be calcuated when the model runs. For example:

0: Model stops before the start of end_year (it is exclusive)
length(step_lengths): Model stops at the end of end_year (it is inclusive)
2: Model stops at the second step of end_year, mid-year if step_lengths is quarterly

project_years

Number of years to continue running after the "end" of the model. Must be >= 0

Defaults to an unoptimized project_years parameter, set to 0 (i.e. no projection). Generally, you would change this parameter in the parameter template, rather than changing here.

retro_years

Adjust end_year to finish model early. Must be >= 0 Can be used in conjunction with project_years to project instead.

The true end year of the model will be end_year - retro_years + project_years.

Defaults to an unoptimized retro_years parameter, set to 0. Generally, you would change this parameter in the parameter template, rather than changing here.

run_at, run_stop_at

Integer order that actions will be run within model, see g3_action_order. run_at does year variable accounting, run_stop_at is when the model will finish if past the final step in the model.

Details

The actions will define the following variables in your model:

cur_time: Current iteration of model, starts at 0 and increments until finished
cur_step: Current step within individual year
cur_step_size: Proportion of year this step contains, e.g. quarterly = 3/12
cur_year: Current year
cur_step_final: TRUE iff this is the final step of the year
cur_year_projection: TRUE iff we are currently projecting past end_year
total_steps: Total # of iterations (including projection) before model stops
total_years: Total # of years (including projection) before model stops

Value

g3a_time

An action (i.e. list of formula objects) that will...

Define cur_* variables listed above
If we've reached the end of the model, return nll

Examples

# Run model 2000..2004, in quarterly steps
time_action <- g3a_time(
    start_year = 2000,
    end_year = 2004,
    c(3, 3, 3, 3))