Set system state. Takes a multidimensional array (2- or 3d depending on if the system is grouped or not). Dimensions of length 1 will be recycled as appropriate. For continuous time systems, we will initialise the solver immediately after setting state, which may cause errors if your initial state is invalid for your system. There are many ways that you can use this function to set different fractions of state (a subset of states, particles or parameter groups, recycling over any dimensions that are missing). Please see the Examples section for usage.
Usage
dust_system_set_state(
sys,
state,
index_state = NULL,
index_particle = NULL,
index_group = NULL
)Arguments
- sys
A
dust_systemobject- state
A matrix or array of state. If ungrouped, the dimension order expected is state x particle. If grouped the order is state x particle x group. If you have a grouped system with 1 particle and
preserve_state_dimension = FALSEthen the state has size state x group. You can omit higher dimensions, so if you pass a vector it will be treated as if all higher dimensions are length 1 (or if you have a grouped system you can provide a matrix and treat it as if the third dimension had length 1). If you provide anyindex_argument then the length of the corresponding state dimension must match the index length.- index_state
An index to control which state variables we set. You can use this to set a subset of state variables.
- index_particle
An index to control which particles have their state updated
- index_group
An index to control which groups have their state updated.
Examples
# Consider a system with 3 particles and 1 group:
sir <- dust_example("sir")
sys <- dust_system_create(sir(), list(), n_particles = 3)
# The state for this system is packed as S, I, R, cases_cumul, cases_inc:
dust_unpack_index(sys)
#> $S
#> [1] 1
#>
#> $I
#> [1] 2
#>
#> $R
#> [1] 3
#>
#> $cases_cumul
#> [1] 4
#>
#> $cases_inc
#> [1] 5
#>
# Set all particles to the same state:
dust_system_set_state(sys, c(1000, 10, 0, 0, 0))
dust_system_state(sys)
#> [,1] [,2] [,3]
#> [1,] 1000 1000 1000
#> [2,] 10 10 10
#> [3,] 0 0 0
#> [4,] 0 0 0
#> [5,] 0 0 0
# We can set everything to different states by passing a vector
# with this shape:
m <- cbind(c(1000, 10, 0, 0, 0), c(999, 11, 0, 0, 0), c(998, 12, 0, 0, 0))
dust_system_set_state(sys, m)
dust_system_state(sys)
#> [,1] [,2] [,3]
#> [1,] 1000 999 998
#> [2,] 10 11 12
#> [3,] 0 0 0
#> [4,] 0 0 0
#> [5,] 0 0 0
# Or set the state for just one state:
dust_system_set_state(sys, 1, index_state = 4)
dust_system_state(sys)
#> [,1] [,2] [,3]
#> [1,] 1000 999 998
#> [2,] 10 11 12
#> [3,] 0 0 0
#> [4,] 1 1 1
#> [5,] 0 0 0
# If you want to set a different state across particles, you must
# provide a *matrix* (a vector always sets the same state into
# every particle)
dust_system_set_state(sys, rbind(c(1, 2, 3)), index_state = 4)
dust_system_state(sys)
#> [,1] [,2] [,3]
#> [1,] 1000 999 998
#> [2,] 10 11 12
#> [3,] 0 0 0
#> [4,] 1 2 3
#> [5,] 0 0 0
# This will not work as it can be ambiguous what you are
# trying to do:
#> dust_system_set_state(sys, c(1, 2, 3), index_state = 4)
# State can be set for specific particles:
dust_system_set_state(sys, c(900, 100, 0, 0, 0), index_particle = 2)
dust_system_state(sys)
#> [,1] [,2] [,3]
#> [1,] 1000 900 998
#> [2,] 10 100 12
#> [3,] 0 0 0
#> [4,] 1 0 3
#> [5,] 0 0 0
# And you can combine 'index_particle' with 'index_state' to set
# small rectangles of state:
dust_system_set_state(sys, matrix(c(1, 2, 3, 4), 2, 2),
index_particle = 2:3, index_state = 4:5)
dust_system_state(sys)
#> [,1] [,2] [,3]
#> [1,] 1000 900 998
#> [2,] 10 100 12
#> [3,] 0 0 0
#> [4,] 1 1 3
#> [5,] 0 2 4