% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim_settings.R
\name{sim_settings}
\alias{sim_settings}
\title{Modify simulation specifications}
\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{
\item{object}{Stock-and-flow model, object of class \code{\link{stockflow}}.}

\item{method}{Integration method. Defaults to \code{"euler"}.}

\item{start}{Start time of simulation. Defaults to \code{0}.}

\item{stop}{End time of simulation. Defaults to \code{100}.}

\item{dt}{Timestep of solver; controls simulation accuracy. Smaller = more
accurate but slower. Defaults to \code{0.01}.}

\item{save_by}{Save output at a regular interval, mirroring the \code{by} argument
of \code{\link[=seq]{seq()}}: output times are \code{seq(start, stop, by = save_by)}. Must be a
single number \verb{>= dt}. Use a value larger than \code{dt} to reduce output size
without sacrificing accuracy. Example: \code{dt = 0.01}, \code{save_by = 1} saves every
100th computed point. Pass \code{NA}, \code{NULL}, or \code{""} to reset to saving all dt
steps. Mutually exclusive with \code{save_times} and \code{save_length}. Defaults to
\code{NULL} (save all).}

\item{save_times}{Numeric vector of explicit output times to save. Values must
lie within \verb{[start, stop]}. Example: \code{save_times = c(0, 10)} saves exactly
those two times. Pass \code{NA}, \code{NULL}, or \code{""} to reset to saving all dt steps.
Mutually exclusive with \code{save_by} and \code{save_length}. Defaults to \code{NULL}
(save all).}

\item{save_length}{Number of output times to save, mirroring the \code{length.out}
argument of \code{\link[=seq]{seq()}}: output times are \code{seq(start, stop, length.out = save_length)}. Must be a single whole positive number. \code{save_length = 1}
saves only the final time point (stop). Pass \code{NA}, \code{NULL}, or \code{""} to reset
to saving all dt steps. Mutually exclusive with \code{save_by} and \code{save_times}.
Defaults to \code{NULL} (save all).}

\item{seed}{Seed number to ensure reproducibility across runs in case of
random elements. Must be an integer. Defaults to \code{NULL} (no seed).}

\item{time_units}{Simulation time unit. Defaults to \code{"seconds"}.}

\item{language}{Coding language in which to simulate model. Either \code{"R"} or
\code{"Julia"}. Defaults to \code{"R"}.}

\item{only_stocks}{If \code{TRUE}, only return stocks in output, discarding flows
and auxiliaries. If \code{FALSE}, flows and auxiliaries are saved, which slows
down the simulation. Defaults to \code{TRUE}.}

\item{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 \code{only_stocks}. Pass \code{NULL}, \code{""},
or an empty character vector to clear a previous \code{vars} setting.}

\item{keep_nonnegative_stock}{If \code{TRUE}, keeps original non-negativity setting
of stocks. Defaults to \code{FALSE}.}

\item{keep_nonnegative_flow}{If \code{TRUE}, keeps original non-negativity setting
of flows. Defaults to \code{TRUE}.}

\item{save_sims}{If \code{TRUE}, individual simulations are retained in
\code{\link[=ensemble]{ensemble()}} output. Defaults to \code{FALSE}.}

\item{central}{Central-tendency statistics to compute across simulations in
\code{\link[=ensemble]{ensemble()}}. One or more of \code{"mean"}, \code{"median"}, or \code{"none"} (compute no
central tendency). Each requested statistic becomes a column in the ensemble
summary. Defaults to \code{c("mean", "median")}. Can be overridden per call via
the \code{central} argument of \code{\link[=ensemble]{ensemble()}}.}

\item{spread}{Spread (uncertainty) statistics to compute across simulations in
\code{\link[=ensemble]{ensemble()}}. One or more of \code{"quantile"} (quantile columns at the
probabilities given by \code{quantiles}), \code{"sd"} (standard deviation), \code{"range"}
(minimum and maximum, returned as \code{min}/\code{max} columns), or \code{"none"} (compute
no spread). Defaults to \code{"quantile"}. Can be overridden per call via the
\code{spread} argument of \code{\link[=ensemble]{ensemble()}}.}

\item{quantiles}{Quantile probabilities to compute when \code{spread} includes
\code{"quantile"}, e.g. \code{c(0.025, 0.975)}. Returned as columns \code{quant1},
\code{quant2}, ... in the order given. At least two unique values are required.
Defaults to \code{c(0.025, 0.975)}. Can be overridden per call via the
\code{quantiles} argument of \code{\link[=ensemble]{ensemble()}}.}

\item{...}{Reserved for future use. Passing unknown arguments (including the
removed \code{save_at} and \code{save_n}) raises an error.}
}
\value{
A stock-and-flow model object of class \code{\link{stockflow}}
}
\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.
}
\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))

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

# Save only specific time points
sfm <- sim_settings(sfm, save_times = c(0, 25, 50))
sim <- simulate(sfm)
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))

}
\seealso{
\code{\link[=sim_methods]{sim_methods()}}
}
\concept{simulate}
