Create a dust system object — dust_system

Create a dust system object from a system generator. This allocates a system and sets an initial set of parameters. Once created you can use other dust functions to interact with it.

Usage

dust_system_create(
  generator,
  pars = list(),
  n_particles = 1,
  n_groups = 1,
  time = 0,
  dt = NULL,
  ode_control = NULL,
  seed = NULL,
  deterministic = FALSE,
  n_threads = 1,
  preserve_particle_dimension = FALSE,
  preserve_group_dimension = FALSE
)

Arguments

generator: A system generator object, with class dust_system_generator
pars: A list of parameters. The format of this will depend on the system. If n_groups is 1 or more, then this must be a list of length n_groups where each element is a list of parameters for your system. The default list() assumes your system has no required parameters, but you may need to pass a list of parameters here.
n_particles: The number of particles to create, defaulting to a single particle
n_groups: Optionally, the number of parameter groups
time: The initial time, defaults to 0
dt: The time step for discrete time systems, defaults to 1 if not given. It is an error to provide a non-NULL argument with continuous-time systems.
ode_control: The ODE integration control for continuous time systems. Defaults to the default return of dust_ode_control. It is an error to provide this with discrete-time systems.
seed: Optionally, a seed. Otherwise we respond to R's RNG seed on initialisation.
deterministic: Logical, indicating if the system should be allocated in deterministic mode.
n_threads: Integer, the number of threads to use in parallelisable calculations. See Details.
preserve_particle_dimension: Logical, indicating if output from the system should preserve the particle dimension in the case where a single particle is run. In the case where more than one particle is run, this argument has no effect as the dimension is always preserved.
preserve_group_dimension: Logical, indicating if state and output from the system should preserve the group dimension in the case where a single group is run. In the case where more than one group is run, this argument has no effect as the dimension is always preserved.

Value

A dust_system object, with opaque format.

Parallelisation

Many calculations within a dust system can be parallelised straightforwardly - the most important of these is typically running the model (via dust_system_run_to_time or dust_system_simulate) but we also parallelise dust_system_set_state_initial, dust_system_compare_data and even dust_system_reorder. You need to set the number of threads for parallelism at system creation, and this number cannot be usefully larger than n_particles (or n_particles * n_groups if you have a grouped system).