dust_generator: The dust class

dust_generatorR Documentation

The dust class

Description

All "dust" dust models are R6 objects and expose a common set of "methods". To create a dust model of your own, see dust and to interact with some built-in ones see dust_example()

Value

A dust_generator object

Methods

Public methods


Method new()

Create a new model. Note that the behaviour of this object created by this function will change considerably based on whether the pars_multi argument is TRUE. If not (the default) then we create n_particles which all share the same parameters as specified by the pars argument. If pars_multi is TRUE then pars must be an unnamed list, and each element of it represents a different set of parameters. We will create length(pars) sets of n_particles particles which will be simulated together. These particles must have the same dimension - that is, they must correspond to model state that is the same size.

Usage
dust_generator$new(
  pars,
  step,
  n_particles,
  n_threads = 1L,
  seed = NULL,
  pars_multi = FALSE,
  deterministic = FALSE,
  gpu_config = NULL
)
Arguments
pars

Data to initialise your model with; a list object, but the required elements will depend on the details of your model. If pars_multi is TRUE, then this must be an unnamed list of pars objects (see Details).

step

Initial step - must be nonnegative

n_particles

Number of particles to create - must be at least 1

n_threads

Number of OMP threads to use, if dust and your model were compiled with OMP support (details to come). n_particles should be a multiple of n_threads (e.g., if you use 8 threads, then you should have 8, 16, 24, etc particles). However, this is not compulsory.

seed

The seed to use for the random number generator. Can be a positive integer, NULL (initialise with R's random number generator) or a raw vector of a length that is a multiple of 32 to directly initialise the generator (e..g., from the dust object's $rng_state() method).

pars_multi

Logical, indicating if pars should be interpreted as a set of different initialisations, and that we should prepare n_particles * length(pars) particles for simulation. This has an effect on many of the other methods of the object.

deterministic

Run random number generation deterministically, replacing a random number from some distribution with its expectation. Deterministic models are not compatible with running on a a GPU.

gpu_config

GPU configuration, typically an integer indicating the device to use, where the model has GPU support. If not given, then the default value of NULL will fall back on the first found device if any are available. An error is thrown if the device id given is larger than those reported to be available (note that CUDA numbers devices from 0, so that '0' is the first device, and so on). See the method $gpu_info() for available device ids; this can be called before object creation as dust_generator$public_methods$gpu_info(). For additional control, provide a list with elements device_id and run_block_size. Further options (and validation) of this list will be added in a future version!


Method name()

Returns friendly model name

Usage
dust_generator$name()

Method param()

Returns parameter information, if provided by the model. This describes the contents of pars passed to the constructor or to $update_state() as the pars argument, and the details depend on the model.

Usage
dust_generator$param()

Method run()

Run the model up to a point in time, returning the filtered state at that point.

Usage
dust_generator$run(step_end)
Arguments
step_end

Step to run to (if less than or equal to the current step(), silently nothing will happen)


Method simulate()

Iterate all particles forward in time over a series of steps, collecting output as they go. This is a helper around $run() where you want to run to a series of points in time and save output. The returned object will be filtered by your active index, so that it has shape (n_state x n_particles x length(step_end)) for single-parameter objects, and (n_state x n_particles x n_pars x length(step_end)) for multiparameter objects. Note that this method is very similar to $run() except that the rank of the returned array is one less. For a scalar step_end you would ordinarily want to use $run() but the resulting numbers would be identical.

Usage
dust_generator$simulate(step_end)
Arguments
step_end

A vector of time points that the simulation should report output at. This the first time must be at least the same as the current time, and every subsequent time must be equal or greater than those before it (ties are allowed though probably not wanted).


Method set_index()

Set the "index" vector that is used to return a subset of pars after using run(). If this is not used then run() returns all elements in your state vector, which may be excessive and slower than necessary.

Usage
dust_generator$set_index(index)
Arguments
index

The index vector - must be an integer vector with elements between 1 and the length of the state (this will be validated, and an error thrown if an invalid index is given).


Method index()

Returns the index as set by $set_index

Usage
dust_generator$index()

Method n_threads()

Returns the number of threads that the model was constructed with

Usage
dust_generator$n_threads()

Method n_state()

Returns the length of the per-particle state

Usage
dust_generator$n_state()

Method n_particles()

Returns the number of particles

Usage
dust_generator$n_particles()

Method n_particles_each()

Returns the number of particles per parameter set

Usage
dust_generator$n_particles_each()

Method shape()

Returns the shape of the particles

Usage
dust_generator$shape()

Method update_state()

Update one or more components of the model state. This method can be used to update any or all of pars, state and step. If both pars and step are given and state is not, then by default we will update the model internal state according to your model's initial conditions - use set_initial_state = FALSE to prevent this.

Usage
dust_generator$update_state(
  pars = NULL,
  state = NULL,
  step = NULL,
  set_initial_state = NULL
)
Arguments
pars

New pars for the model (see constructor)

state

The state vector - can be either a numeric vector with the same length as the model's current state (in which case the same state is applied to all particles), or a numeric matrix with as many rows as your model's state and as many columns as you have particles (in which case you can set a number of different starting states at once).

step

New initial step for the model. If this is a vector (with the same length as the number of particles), then particles are started from different initial steps and run up to the largest step given (i.e., max(step))

set_initial_state

Control if the model initial state should be set while setting parameters. It is an error for this to be TRUE when either pars is NULL or when state is non-NULL.


Method state()

Return full model state

Usage
dust_generator$state(index = NULL)
Arguments
index

Optional index to select state using


Method step()

Return current model step

Usage
dust_generator$step()

Method reorder()

Reorder particles.

Usage
dust_generator$reorder(index)
Arguments
index

An integer vector, with values between 1 and n_particles, indicating the index of the current particles that new particles should take.


Method resample()

Resample particles according to some weight.

Usage
dust_generator$resample(weights)
Arguments
weights

A numeric vector representing particle weights. For a "multi-parameter" dust object this should be be a matrix with the number of rows being the number of particles per parameter set and the number of columns being the number of parameter sets. long as all particles or be a matrix.


Method info()

Returns information about the pars that your model was created with. Only returns non-NULL if the model provides a dust_info template specialisation.

Usage
dust_generator$info()

Method pars()

Returns the pars object that your model was constructed with.

Usage
dust_generator$pars()

Method rng_state()

Returns the state of the random number generator. This returns a raw vector of length 32 * n_particles. This can be useful for debugging or for initialising other dust objects. The arguments first_only and last_only are mutually exclusive. If neither is given then all all particles states are returned, being 32 bytes per particle. The full returned state or first_only are most suitable for reseeding a new dust object.

Usage
dust_generator$rng_state(first_only = FALSE, last_only = FALSE)
Arguments
first_only

Logical, indicating if we should return only the first random number state

last_only

Logical, indicating if we should return only the last random number state, which does not belong to a particle.


Method set_rng_state()

Set the random number state for this model. This replaces the RNG state that the model is using with a state of your choosing, saved out from a different model object. This method is designed to support advanced use cases where it is easier to manipulate the state of the random number generator than the internal state of the dust object.

Usage
dust_generator$set_rng_state(rng_state)
Arguments
rng_state

A random number state, as saved out by the $rng_state() method. Note that unlike seed as passed to the constructor, this must be a raw vector of the expected length.


Method has_openmp()

Returns a logical, indicating if this model was compiled with "OpenMP" support, in which case it will react to the n_threads argument passed to the constructor. This method can also be used as a static method by running it directly as dust_generator$public_methods$has_openmp()

Usage
dust_generator$has_openmp()

Method has_gpu_support()

Returns a logical, indicating if this model was compiled with "CUDA" support, in which case it will react to the device argument passed to the run method. This method can also be used as a static method by running it directly as dust_generator$public_methods$has_gpu_support()

Usage
dust_generator$has_gpu_support(fake_gpu = FALSE)
Arguments
fake_gpu

Logical, indicating if we count as TRUE models that run on the "fake" GPU (i.e., using the GPU version of the model but running on the CPU)


Method has_compare()

Returns a logical, indicating if this model was compiled with "compare" support, in which case the set_data and compare_data methods are available (otherwise these methods will error). This method can also be used as a static method by running it directly as dust_generator$public_methods$has_compare()

Usage
dust_generator$has_compare()

Method real_size()

Return the size of real numbers (in bits). Typically this will be 64 for double precision and 32 for float. This method can also be used as a static method by running it directory as dust_generator$public_methods$real_size()

Usage
dust_generator$real_size()

Method rng_algorithm()

Return the random number algorithm used. Typically this will be xoshiro256plus for models using double precision reals and xoshiro128plus for single precision (float). This method can also be used as a static method by running it directory as dust_generator$public_methods$rng_algorithm()

Usage
dust_generator$rng_algorithm()

Method uses_gpu()

Check if the model is running on a GPU

Usage
dust_generator$uses_gpu(fake_gpu = FALSE)
Arguments
fake_gpu

Logical, indicating if we count as TRUE models that run on the "fake" GPU (i.e., using the GPU version of the model but running on the CPU)


Method n_pars()

Returns the number of distinct pars elements required. This is 0 where the object was initialised with pars_multi = FALSE and an integer otherwise. For multi-pars dust objects, Where pars is accepted, you must provide an unnamed list of length $n_pars().

Usage
dust_generator$n_pars()

Method set_n_threads()

Change the number of threads that the dust object will use. Your model must be compiled with "OpenMP" support for this to have an effect. Returns (invisibly) the previous value.

Usage
dust_generator$set_n_threads(n_threads)
Arguments
n_threads

The new number of threads to use. You may want to wrap this argument in dust_openmp_threads() in order to verify that you can actually use the number of threads requested (based on environment variables and OpenMP support).


Method set_data()

Set "data" into the model for use with the $compare_data() method. This is not supported by all models, depending on if they define a data_type type. See dust_data() for a helper function to construct suitable data and a description of the required format. You will probably want to use that here, and definitely if using multiple parameter sets.

Usage
dust_generator$set_data(data, shared = FALSE)
Arguments
data

A list of data to set.

shared

Logical, indicating if the data should be shared across all parameter sets, if your model is initialised to use more than one parameter set (pars_multi = TRUE).


Method compare_data()

Compare the current model state against the data as set by set_data. If there is no data set, or no data corresponding to the current time then NULL is returned. Otherwise a numeric vector the same length as the number of particles is returned. If model's underlying compare_data function is stochastic, then each call to this function may be result in a different answer.

Usage
dust_generator$compare_data()

Method filter()

Run a particle filter. The interface here will change a lot over the next few versions. You must reset the dust object using $update_state(pars = ..., step = ...) before using this method to get sensible values.

Usage
dust_generator$filter(
  step_end = NULL,
  save_trajectories = FALSE,
  step_snapshot = NULL,
  min_log_likelihood = NULL
)
Arguments
step_end

The step to run to. If NULL, run to the end of the last data. This value must be larger than the current model step ($step()) and must exactly appear in the data.

save_trajectories

Logical, indicating if the filtered particle trajectories should be saved. If TRUE then the trajectories element will be a multidimensional array (state x <shape> x time) containing the state values, selected according to the index set with $set_index().

step_snapshot

Optional integer vector indicating steps that we should record a snapshot of the full particle filter state. If given it must be strictly increasing vector whose elements match steps given in the data object. The return value with be a multidimensional array (state x <shape> x step_snapshot) containing full state values at the requested steps.

min_log_likelihood

Optionally, a numeric value representing the smallest likelihood we are interested in. If non-NULL either a scalar value or vector the same length as the number of parameter sets. Not yet supported, and included for future compatibility.


Method gpu_info()

Return information about GPU devices, if the model has been compiled with CUDA/GPU support. This can be called as a static method by running dust_generator$public_methods$gpu_info(). If run from a GPU enabled object, it will also have an element config containing the computed device configuration: the device id, shared memory and the block size for the run method on the device.

Usage
dust_generator$gpu_info()

Examples

# An example dust object from the package:
walk <- dust::dust_example("walk")

# The generator object has class "dust_generator"
class(walk)

# The methods below are are described in the documentation
walk

mrc-ide/dust documentation built on May 21, 2022, 7:57 a.m.