Modify simulation specifications

Simulation specifications are the settings that determine how the model is simulated, such as the integration method (i.e., solver), start and stop time, and timestep. Modify these specifications for an existing stock-and-flow model.

Usage

sim_settings(
  object,
  method = "euler",
  start = 0,
  stop = 100,
  dt = 0.01,
  save_by = NULL,
  save_times = NULL,
  save_length = NULL,
  seed = NULL,
  time_units = "seconds",
  language = "R",
  only_stocks = TRUE,
  vars = NULL,
  keep_nonnegative_stock = FALSE,
  keep_nonnegative_flow = TRUE,
  save_sims = FALSE,
  central = c("mean", "median"),
  spread = "quantile",
  quantiles = c(0.025, 0.975),
  ...
)

Arguments

object: Stock-and-flow model, object of class stockflow.
method: Integration method. Defaults to "euler".
start: Start time of simulation. Defaults to 0.
stop: End time of simulation. Defaults to 100.
dt: Timestep of solver; controls simulation accuracy. Smaller = more accurate but slower. Defaults to 0.01.
save_by: Save output at a regular interval, mirroring the by argument of seq(): output times are seq(start, stop, by = save_by). Must be a single number >= dt. Use a value larger than dt to reduce output size without sacrificing accuracy. Example: dt = 0.01, save_by = 1 saves every 100th computed point. Pass NA, NULL, or "" to reset to saving all dt steps. Mutually exclusive with save_times and save_length. Defaults to NULL (save all).
save_times: Numeric vector of explicit output times to save. Values must lie within [start, stop]. Example: save_times = c(0, 10) saves exactly those two times. Pass NA, NULL, or "" to reset to saving all dt steps. Mutually exclusive with save_by and save_length. Defaults to NULL (save all).
save_length: Number of output times to save, mirroring the length.out argument of seq(): output times are seq(start, stop, length.out = save_length). Must be a single whole positive number. save_length = 1 saves only the final time point (stop). Pass NA, NULL, or "" to reset to saving all dt steps. Mutually exclusive with save_by and save_times. Defaults to NULL (save all).
seed: Seed number to ensure reproducibility across runs in case of random elements. Must be an integer. Defaults to NULL (no seed).
time_units: Simulation time unit. Defaults to "seconds".
language: Coding language in which to simulate model. Either "R" or "Julia". Defaults to "R".
only_stocks: If TRUE, only return stocks in output, discarding flows and auxiliaries. If FALSE, flows and auxiliaries are saved, which slows down the simulation. Defaults to TRUE.
vars: Character vector of variable names to save in simulation output. Use this to keep selected flows or auxiliaries without saving every model variable. If specified, this overrides only_stocks. Pass NULL, "", or an empty character vector to clear a previous vars setting.
keep_nonnegative_stock: If TRUE, keeps original non-negativity setting of stocks. Defaults to FALSE.
keep_nonnegative_flow: If TRUE, keeps original non-negativity setting of flows. Defaults to TRUE.
save_sims: If TRUE, individual simulations are retained in ensemble() output. Defaults to FALSE.
central: Central-tendency statistics to compute across simulations in ensemble(). One or more of "mean", "median", or "none" (compute no central tendency). Each requested statistic becomes a column in the ensemble summary. Defaults to c("mean", "median"). Can be overridden per call via the central argument of ensemble().
spread: Spread (uncertainty) statistics to compute across simulations in ensemble(). One or more of "quantile" (quantile columns at the probabilities given by quantiles), "sd" (standard deviation), "range" (minimum and maximum, returned as min/max columns), or "none" (compute no spread). Defaults to "quantile". Can be overridden per call via the spread argument of ensemble().
quantiles: Quantile probabilities to compute when spread includes "quantile", e.g. c(0.025, 0.975). Returned as columns quant1, quant2, ... in the order given. At least two unique values are required. Defaults to c(0.025, 0.975). Can be overridden per call via the quantiles argument of ensemble().
...: Reserved for future use. Passing unknown arguments (including the removed save_at and save_n) raises an error.

Value

A stock-and-flow model object of class stockflow

Examples

sfm <- stockflow("predator_prey") |>
  sim_settings(start = 0, stop = 50, dt = 0.1)
sim <- simulate(sfm)
plot(sim)


# Change the simulation method to "rk4"
sfm <- sim_settings(sfm, method = "rk4")

# Change the time units to "years", such that one time unit is one year
sfm <- sim_settings(sfm, time_units = "years")

# Save at a regular interval to reduce output size without affecting accuracy
sfm <- sim_settings(sfm, save_by = 1)
sim <- simulate(sfm)
head(as.data.frame(sim))
#>   time variable    value
#> 1    0 predator 10.00000
#> 2    1 predator 19.44201
#> 3    2 predator 24.98656
#> 4    3 predator 21.93852
#> 5    4 predator 16.30464
#> 6    5 predator 11.45100

# Save exactly 11 evenly-spaced time points (t=0, 5, 10, ..., 50)
sfm <- sim_settings(sfm, save_length = 11)
sim <- simulate(sfm)
head(as.data.frame(sim))
#>   time variable     value
#> 1    0 predator 10.000000
#> 2    5 predator 11.451000
#> 3   10 predator  2.741946
#> 4   15 predator 21.126645
#> 5   20 predator  7.444416
#> 6   25 predator  2.811715

# Save only specific time points
sfm <- sim_settings(sfm, save_times = c(0, 25, 50))
sim <- simulate(sfm)
as.data.frame(sim)
#>   time variable     value
#> 1    0 predator 10.000000
#> 2   25 predator  2.811715
#> 3   50 predator  3.528707
#> 4    0     prey 50.000000
#> 5   25     prey 25.655322
#> 6   50     prey 10.079878

# Add stochastic initial condition but specify seed to obtain same result
sfm <- sim_settings(sfm, seed = 1) |>
  update(c(predator, prey), eqn = runif(1, 20, 50))

Usage

Arguments

Value

See also

Examples