dust_generator | R Documentation |

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

A `dust_generator`

object

For discrete time models, dust has an internal "time", which was
called `step`

in version `0.11.x`

and below. This must always
be non-negative (i.e., zero or more) and always increases in
unit increments. Typically a model will remap this internal
time onto a more meaningful time in model space, e.g. by applying
the transform `model_time = offset + time * dt`

; with this approach
you can start at any real valued time and scale the unit increments
to control the model dynamics.

`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.

dust_generator$new( pars, time, n_particles, n_threads = 1L, seed = NULL, pars_multi = FALSE, deterministic = FALSE, gpu_config = NULL, ode_control = NULL )

`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).`time`

Initial time - 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!`ode_control`

For ODE models, control over the integration; must be a

`dust_ode_control`

model, produced by`dust_ode_control()`

. It is an error to provide a non-`NULL`

value for discrete time models.

`name()`

Returns friendly model name

dust_generator$name()

`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.

dust_generator$param()

`run()`

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

dust_generator$run(time_end)

`time_end`

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

`simulate()`

Iterate all particles forward in time over a series of times,
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(time_end)`

)
for single-parameter objects, and (`n_state`

x `n_particles`

x
`n_pars`

x `length(time_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 `time_end`

you would
ordinarily want to use `$run()`

but the resulting numbers would
be identical.

dust_generator$simulate(time_end)

`time_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).

`run_adjoint()`

Run model with gradient information (if supported). The interface here will change, and documentation written once it stabilises.

dust_generator$run_adjoint()

`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.

dust_generator$set_index(index)

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

`index()`

Returns the `index`

as set by `$set_index`

dust_generator$index()

`ode_control()`

Return the ODE control set into the object on creation.
For discrete-time models this always returns `NULL`

.

dust_generator$ode_control()

`ode_statistics()`

Return statistics about the integration, for ODE models. For discrete time models this makes little sense and so errors if used.

dust_generator$ode_statistics()

`n_threads()`

Returns the number of threads that the model was constructed with

dust_generator$n_threads()

`n_state()`

Returns the length of the per-particle state

dust_generator$n_state()

`n_particles()`

Returns the number of particles

dust_generator$n_particles()

`n_particles_each()`

Returns the number of particles per parameter set

dust_generator$n_particles_each()

`shape()`

Returns the shape of the particles

dust_generator$shape()

`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
`time`

. If both `pars`

and `time`

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.

dust_generator$update_state( pars = NULL, state = NULL, time = NULL, set_initial_state = NULL, index = NULL, reset_step_size = NULL )

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

`time`

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

`max(time)`

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

.`index`

Used in conjunction with

`state`

, use this to set a fraction of the model state; the`index`

vector provided must be the same length as the number of provided states, and indicates the index within the model state that should be updated. For example, if your model has states`[a, b, c, d]`

and you provide an index of`[1, 3]`

then of`state`

was`[10, 20]`

you would set`a`

to 10 and`c`

to 20.`reset_step_size`

Logical, indicating if we should reset the initial step size. This only has an effect with ode models and is silently ignored in discrete time models where the step size is constant.

`state()`

Return full model state

dust_generator$state(index = NULL)

`index`

Optional index to select state using

`time()`

Return current model time
For ODE models, sets the schedule at which stochastic events are
handled. The timing here is quite subtle - an event happens
immediately *after* the time (so at `time + eps`

). If your model
runs up to `time`

an event is not triggered, but as soon as that
time is passed, by any amount of time, the event will trigger. It
is an error to set this to a non-`NULL`

value in a discrete time
model; later we may generalise the approach here.

dust_generator$time()

`set_stochastic_schedule()`

dust_generator$set_stochastic_schedule(time)

`time`

A vector of times to run the stochastic update at

`reorder()`

Reorder particles.

dust_generator$reorder(index)

`index`

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

`resample()`

Resample particles according to some weight.

dust_generator$resample(weights)

`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.

`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.

dust_generator$info()

`pars()`

Returns the `pars`

object that your model was constructed with.

dust_generator$pars()

`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.

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

`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.

`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.

dust_generator$set_rng_state(rng_state)

`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.

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

dust_generator$has_openmp()

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

dust_generator$has_gpu_support(fake_gpu = FALSE)

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

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

dust_generator$has_compare()

`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 directly as
`dust_generator$public_methods$real_size()`

dust_generator$real_size()

`time_type()`

Return the type of time this model uses; will be one of `discrete`

(for discrete time models) or `continuous`

(for ODE models).
This method can also be used as a static method by running it
directly as `dust_generator$public_methods$time_type()`

dust_generator$time_type()

`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 directly as
`dust_generator$public_methods$rng_algorithm()`

dust_generator$rng_algorithm()

`uses_gpu()`

Check if the model is running on a GPU

dust_generator$uses_gpu(fake_gpu = FALSE)

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

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

.

dust_generator$n_pars()

`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.

dust_generator$set_n_threads(n_threads)

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

`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.

dust_generator$set_data(data, shared = FALSE)

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

).

`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.

dust_generator$compare_data()

`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 = ..., time = ...)`

before using this method to
get sensible values.

dust_generator$filter( time_end = NULL, save_trajectories = FALSE, time_snapshot = NULL, min_log_likelihood = NULL )

`time_end`

The time to run to. If

`NULL`

, run to the end of the last data. This value must be larger than the current model time (`$time()`

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

.`time_snapshot`

Optional integer vector indicating times that we should record a snapshot of the full particle filter state. If given it must be strictly increasing vector whose elements match times given in the

`data`

object. The return value with be a multidimensional array (`state x <shape> x time_snapshot`

) containing full state values at the requested times.`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.

`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.

dust_generator$gpu_info()

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

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.