mizer (version 3.2.0)

project: Project size spectrum forward in time

Description

Runs the size spectrum model simulation. The function returns an object of type MizerSim that can then be explored with a range of summary_functions, indicator_functions and plotting_functions.

Usage

project(
  object,
  effort,
  t_max = 100,
  dt = 0.1,
  t_save = 1,
  t_start = 0,
  initial_n,
  initial_n_pp,
  append = TRUE,
  progress_bar = TRUE,
  callback = NULL,
  method = c("euler", "predictor_corrector", "tr_bdf2"),
  ...
)

Value

An object of class MizerSim.

Arguments

object

Either a MizerParams object or a MizerSim object (which contains a MizerParams object).

effort

The effort of each fishing gear through time. See notes below.

t_max

The number of years the projection runs for. The default value is 100. When an effort array is supplied, this argument can be used to extend the simulation beyond the times specified in the effort array. See notes below.

dt

Time step of the solver. The default value is 0.1. When object is a MizerSim, defaults to the value used to produce that simulation.

t_save

The frequency with which the output is stored. The default value is 1. See notes below.

t_start

The the year of the start of the simulation. The simulation will cover the period from t_start to t_start + t_max. Defaults to 0. Ignored if an array is used for the effort argument or a MizerSim for the object argument.

initial_n

The initial abundances of species. Instead of using this argument you should set initialN(params) to the desired value.

initial_n_pp

The initial abundances of resource. Instead of using this argument you should set initialNResource(params) to the desired value.

append

A boolean that determines whether the new simulation results are appended to the previous ones. Only relevant if object is a MizerSim object. Default = TRUE.

progress_bar

Either a boolean value to determine whether a progress bar should be shown in the console, or a shiny Progress object to implement a progress bar in a shiny app.

callback

A function to be called at each saved time step of the simulation. The callback function is called with the MizerSim object, the current time index, and any additional arguments passed to project() via ....

method

The numerical method to use for the consumer density update. "euler" uses the first-order semi-implicit Euler update. "predictor_corrector" uses a predictor-corrector Crank-Nicolson update with midpoint rates, which is second order in time but can oscillate at large time steps. "tr_bdf2" uses the L-stable, second-order TR-BDF2 method, which retains second-order accuracy while damping those oscillations. "predictor-corrector" is accepted as an alias for "predictor_corrector". When object is a MizerSim, defaults to the value used to produce that simulation. A warning is issued if append = TRUE and the supplied value differs from the stored one.

...

Other arguments will be passed to rate functions.

Advective flux scheme

The spatial discretisation of the growth (advection) term is controlled by the flux entry of the second_order_w slot of the params object, not by an argument to project(). With the default ("upwind") the first-order upwind flux is used. Setting it to "van_leer" (for example with second_order_w(params) <- TRUE) switches on a flux-limited (van Leer, TVD) deferred correction that removes the leading numerical diffusion \(\approx g\,w\,\log\beta\) of the upwind flux while keeping the density update a tridiagonal solve and preserving positivity. The correction is most useful on coarse logarithmic grids and pairs naturally with the second-order time methods. Because it changes the discrete steady state, the choice lives in the params object alongside the steady state rather than being a per-run argument. See second_order_w().

Examples

# \donttest{
params <- NS_params
# With constant fishing effort for all gears for 20 time steps
sim <- project(params, t_max = 20, effort = 0.5)
# With constant fishing effort which is different for each gear
effort <- c(Industrial = 0, Pelagic = 1, Beam = 0.5, Otter = 0.5)
sim <- project(params, t_max = 20, effort = effort)
# With fishing effort that varies through time for each gear
gear_names <- c("Industrial", "Pelagic", "Beam", "Otter")
times <- seq(from = 1, to = 10, by = 1)
effort_array <- array(NA,
    dim = c(length(times), length(gear_names)),
    dimnames = list(time = times, gear = gear_names)
)
effort_array[, "Industrial"] <- 0.5
effort_array[, "Pelagic"] <- seq(from = 1, to = 2, length = length(times))
effort_array[, "Beam"] <- seq(from = 1, to = 0, length = length(times))
effort_array[, "Otter"] <- seq(from = 1, to = 0.5, length = length(times))
sim <- project(params, effort = effort_array)
# Extend a simulation beyond the effort array times
# Effort values from the final time are used for the extension
sim <- project(params, effort = effort_array, t_max = 15)
# Control save times with an effort array using t_save
sim <- project(params, effort = effort_array, t_save = 2)
# }