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_at = 0.1,
  save_n = NULL,
  seed = NULL,
  time_units = "seconds",
  language = "R",
  only_stocks = TRUE,
  vars = NULL,
  keep_nonnegative_stock = FALSE,
  keep_nonnegative_flow = TRUE,
  save_sims = FALSE
)

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_at

Controls which time points are saved in the output. Either:

A single number: save every N time units (interval). Must be >= dt. Use larger than dt to reduce output size without sacrificing accuracy. Example: dt = 0.01, save_at = 1 saves every 100th computed point.
A numeric vector: explicit time points to include in output. Values must lie within [start, stop].

Pass NA, NULL, or "" to reset to saving all dt steps. Mutually exclusive with save_n. Defaults to NULL (save all).

save_n

Save exactly N evenly-spaced time points from start to stop. save_n = 1 saves only the final time point (stop). Pass NA, NULL, or "" to reset to saving all dt steps. Mutually exclusive with save_at. 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. If specified, this overrides only_stocks.

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.

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 an interval to reduce output size without affecting accuracy
sfm <- sim_settings(sfm, save_at = 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_n = 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

# 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