---
title: "Options"
header-includes:
   - \usepackage{amsmath}
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Options}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

[![status](https://img.shields.io/badge/status-working%20draft-red)](https://canmod.github.io/macpan2/articles/vignette-status#working-draft)

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Potentially Useful

* `macpan2_verbose = TRUE` : Should the [TMB](https://github.com/kaskr/adcomp) computational engine used by `macpan2` be verbose (default) or not. In particular, the `silent` argument of `TMB::MakeADFun` gets `!getOption("macpan2_verbose")`.
* `macpan2_session_name = "default"` : Where to put log files generated by the engine. By default this will be `.macpan2/default`.
* `macpan2_tol_hazard_div = 1e-8` : Used by the `mp_hazard()` function to generate an expression that calls the `proportions()` engine function. This option becomes the third tolerance argument to `proportions()`.

## Advanced

You almost always want to leave these at their default values.

* `macpan2_time_dep_funcs = c("convolution", "rbind_lag", "rbind_time", "cbind_lag", "cbind_time")` : List of engine functions that cannot be called unless their first argument has a saved simulation history.
* `macpan2_non_iterable_funcs = c("time_var", "rbinom", "rpois", "rnorm", "rnbinom", "reulermultinom")` : List of functions that cannot be called repeatedly _within_ a single time-step (as would happen for example with RK4 state updates). Randomness and time-variation are the only examples we have now.
* `macpan2_dll = "macpan2"` : What C++ shared object should be used as the [TMB](https://github.com/kaskr/adcomp) engine. This is useful if you want to compare different versions of the engine. To use this feature you need to produce an alternative to `src/macpan2.cpp`, compile it using `TMB::compile("path/to/alt.cpp")`, load it using `dyn.load(TMB::dynlib("alt"))`, and set the option as `macpan2_dll = "alt"` where `"alt"` is the name of the alternative C++ file without the extension. After this, simulation code will utilize this alternative engine as opposed to the built in `src/macpan2.cpp` engine.

## Deprecated

These options should not be used unless an old and deprecated approach is used. They are present for back-compatibility only.

* `macpan2_default_loss = c("clamped_poisson", "poisson", "sum_of_squares", "neg_bin")` : 
      ## FIXME: macpan2_vec_by is old and not relevant i think
* `macpan2_vec_by` = c("state", "flow_rates", "trans_rates") |> self_named_vector()

## No Longer or Not Yet Used

* `macpan2_tmb_type = "ADFun"`
* `macpan2_tmb_check = TRUE`