Tracing and debugging tools

Tracing and debugging tools for a G3 model

g3a_trace_var(
        actions,
        check_finite = TRUE,
        check_positive = FALSE,
        check_strictly_positive = FALSE,
        on_error = c("continue", "browser", "stop"),
        print_var = FALSE,
        var_re = c("__num$", "__wgt$"))

g3a_trace_timings(
        actions,
        action_re = NULL )

Arguments

actions: A list of model actions to add tracing to
check_finite: Boolean, notify if variable is not finite (i.e. Inf, NA, NaN)
check_positive: Boolean, notify if variable is < 0
check_strictly_positive: Boolean, notify if variable is <= 0
on_error: What to do when a variable fails one of the checks? NB: "browser" will not work in a TMB-compiled model.
print_var: Boolean, if true print the value of the variable at the point the test fails. NB: This will not work in a TMB-compiled model.
var_re: Regular expression(s), variable whose name matches will be traced.
action_re: Regular expression(s), action step IDs that match will be traced (or all if NULL)

Details

The main reason to use g3a_trace_var is to find out why a model is producing NaN in reports / likelihood. Adding this to your model will help pinpoint the action this originally occurs in, so you can inspect closer for incorrect settings and/or bugs.

Suggested `var_re` settings

The var_re parameter chooses which variables are traced, and should be tweaked to further pinpoint the problem. Generally, once an error has been found, dig into the code (e.g. by doing edit(g3_to_r(actions))), and see what other variables are available for tracing. Some pre-canned suggestions follow:

c("__num$", "__wgt$") (i.e. default): This will trace abundance/weight for all stocks, and a good starting point.
^[stock_name]__(num|wgt|cons|suit|totalpredate|consratio|feedinglevel)$: This will, once [stock_name] is replaced with the name of your stock, dig deeper into the predation mechanisms.

g3a_trace_timings will report a variable, trace_timings, with the min/mean/max number of seconds spent computing each step in the model. You can use g3_to_desc to extract more descriptive names for each step.

Value

g3_trace_var

A list of actions that will report when variables stop being finite (e.g.)

g3_trace_timings

A list of actions to report a trace_timings variable, with how long each step is taking

Examples

stocks <- list(
    st = g3_stock("st", 1:10 * 10) |> g3s_age(1, 5) )

actions <- list(
    g3a_time(1990, 1995, c(3,3,3,3)),
    g3a_initialconditions_normalcv(stocks$st),
    g3a_growmature(stocks$st, impl_f = gadget3::g3a_grow_impl_bbinom(
        maxlengthgroupgrowth = 2L) ),

    NULL )
model_fn <- g3_to_r(c(actions, list(
    g3a_trace_var(actions),
    g3a_trace_timings(actions),
    g3a_report_detail(actions) )))

# Configure set of working parameters
attr(model_fn, "parameter_template") |>
    g3_init_val("*.K", 0.3) |>
    g3_init_val("*.t0", 0.2) |>
    g3_init_val("*.Linf", 80) |>
    g3_init_val("*.lencv", 0.1) |>
    g3_init_val("*.walpha", 0.01) |>
    g3_init_val("*.wbeta", 3) |>
    g3_init_val("*.M.#", 0.01) |>
    identity() -> params.in
nll <- model_fn(params.in) ; r <- attributes(nll) ; nll <- as.vector(nll)

# Show timings of each step of model
r$trace_timings
#>                                                                     total min
#> -01:-                                                               0.000   0
#> -01:g3a_initialconditions:st                  :cf01db7cbcae6d233393 0.001   0
#> 001                                                                 0.000   0
#> 005:st                  :c253dae816f524c9ff63                       0.008   0
#>                                                                       max
#> -01:-                                                               0.000
#> -01:g3a_initialconditions:st                  :cf01db7cbcae6d233393 0.001
#> 001                                                                 0.000
#> 005:st                  :c253dae816f524c9ff63                       0.001
#>                                                                             mean
#> -01:-                                                               0.000000e+00
#> -01:g3a_initialconditions:st                  :cf01db7cbcae6d233393 4.166667e-05
#> 001                                                                 0.000000e+00
#> 005:st                  :c253dae816f524c9ff63                       3.333333e-04

# Find more informative names with g3_to_desc
as.list(g3_to_desc(actions))
#> $`-01:-                   `
#> [1] "g3a_time: Start of time period"
#> 
#> $`-01:g3a_initialconditions:st                  :cf01db7cbcae6d233393`
#> [1] "g3a_initialconditions for st"
#> 
#> $`005:st                  :c253dae816f524c9ff63`
#> [1] "g3a_grow for st"
#> 

# Try setting parameters to NaN and see what fails:
r <- model_fn(params.in |> g3_init_val("*.t0", NaN))
#> st__num failed test at 1990-1, after 'g3a_initialconditions for st'
#> st__wgt failed test at 1990-1, after 'g3a_grow for st'
r <- model_fn(params.in |> g3_init_val("*.bbin", NaN))
#> st__num failed test at 1990-1, after 'g3a_grow for st'
#> st__wgt failed test at 1990-1, after 'g3a_grow for st'