sdbuildR (version 2.0.0)

sim_settings: Modify simulation specifications

Description

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
)

Value

A stock-and-flow model object of class stockflow

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.

See Also

sim_methods()

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))

# 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))

# 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))