Advanced Trajectory Usage
Iñaki Ucar, Bart Smeets
2024-09-28
Source:vignettes/simmer-03-trajectories.Rmd
simmer-03-trajectories.RmdAvailable set of activities
When a generator creates an arrival, it couples the arrival to a given trajectory. A trajectory is defined as an interlinkage of activities which together form the arrivals’ lifetime in the system. Once an arrival is coupled to the trajectory, it will (in general) start processing activities in the specified order and, eventually, leave the system. Consider the following:
traj <- trajectory() %>%
seize(resource = "doctor", amount = 1) %>%
timeout(task = 3) %>%
release(resource = "doctor", amount = 1)Here we create a trajectory where a patient seizes a doctor for 3 minutes and then releases him again. This is a very straightforward example, however, most of the trajectory-related functions allow for more advanced usage.
Usage examples are provided in the help page for each activity. The complete set of activities can be found and navigated in the reference page, or you can list them as follows:
methods(class="trajectory")
#> [1] [ [[ [[<-
#> [4] [<- activate batch
#> [7] branch clone deactivate
#> [10] get_n_activities handle_unfinished join
#> [13] leave length log_
#> [16] print release_all release_selected_all
#> [19] release_selected release renege_abort
#> [22] renege_if renege_in rep
#> [25] rollback seize_selected seize
#> [28] select send separate
#> [31] set_attribute set_capacity_selected set_capacity
#> [34] set_global set_prioritization set_queue_size_selected
#> [37] set_queue_size set_source set_trajectory
#> [40] stop_if synchronize timeout_from_attribute
#> [43] timeout_from_global timeout trap
#> [46] untrap wait
#> see '?methods' for accessing help and source codeAdditionally, you may want to try the simmer.bricks
package, a plugin for simmer which provides helper methods
for trajectories. Each brick wraps a common activity pattern
that can be used to build trajectories more conveniently (see the Introduction
to simmer.bricks).
Dynamic arguments
Many activities accept functions as arguments to be evaluated
dynamically during the simulation. For example, see
help(timeout):
task: the timeout duration supplied by either passing a numeric or a callable object (a function) which must return a numeric.
Be aware that if you want the timeout()’s
task parameter to be evaluated dynamically, you should
supply a callable function. For example in
timeout(function() rexp(1, 10)), rexp(1, 10)
will be evaluated every time the timeout activity is executed. However,
if you supply it in the form of timeout(rexp(1, 10)), it
will only be evaluated once when the trajectory is defined, and will
remain static after that.
trajectory() %>%
timeout(rexp(1, 10)) %>% # fixed
timeout(function() rexp(1, 10)) # dynamic
#> trajectory: anonymous, 2 activities
#> { Activity: Timeout | delay: 0.237144 }
#> { Activity: Timeout | delay: function() }Of course, this task, supplied as a function, may be as
complex as you need and, for instance, it may check the status of a
particular resource, interact with other entities in your simulation
model… The same applies to all the activities when they accept a
function as a parameter.
Interaction with the environment
Dynamic arguments may interact with the environment to extract
parameters of interest such as the current simulation time (see
?now), status of resources (see
?get_capacity), status of generators (see
?get_n_generated), or directly to gather the history of
monitored values (see ?get_mon). The only requirement is
that the simulation environment must be in the scope of the
trajectory.
Therefore, this will not work:
traj <- trajectory() %>%
log_(function() as.character(now(env)))
env <- simmer() %>%
add_generator("dummy", traj, function() 1) %>%
run(4)
#> 1: dummy0:
#> Error in (function () : object 'env' not foundbecause the global env is not available at runtime: the
simulation runs and then the resulting object is assigned to
env. For env to be in the scope of
t during this simulation, it is enough to detach the
run() method from the definition pipe:
traj <- trajectory() %>%
log_(function() as.character(now(env)))
env <- simmer() %>%
add_generator("dummy", traj, function() 1)
env %>% run(4) %>% invisible
#> 1: dummy0: 1
#> 2: dummy1: 2
#> 3: dummy2: 3And we get the expected output. However, as a general rule of good practice, it is recommended to instantiate the environment always in the first place to avoid possible mistakes, and because the code becomes more readable:
# first, instantiate the environment
env <- simmer()
# here I'm using it
traj <- trajectory() %>%
log_(function() as.character(now(env)))
# and finally, run it
env %>%
add_generator("dummy", traj, function() 1) %>%
run(4) %>% invisible
#> 1: dummy0: 1
#> 2: dummy1: 2
#> 3: dummy2: 3Trajectory toolbox: joining and subsetting
The join(...) method is very useful to concatenate
together any number of trajectories. It may be used as a standalone
function as follows:
t1 <- trajectory() %>% seize("dummy", 1)
t2 <- trajectory() %>% timeout(1)
t3 <- trajectory() %>% release("dummy", 1)
t0 <- join(t1, t2, t3)
t0
#> trajectory: anonymous, 3 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Timeout | delay: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }Or it may operate inline, like another activity:
t0 <- trajectory() %>%
join(t1) %>%
timeout(1) %>%
join(t3)
t0
#> trajectory: anonymous, 3 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Timeout | delay: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }You can think about a trajectory object as a list of activities that has a length
length(t0)
#> [1] 3and can be subset using the standard operator [. For
instance, you can select the activities you want with a logical
vector:
t0[c(TRUE, FALSE, TRUE)]
#> trajectory: anonymous, 2 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }Or a set of indices that respect the order given:
t0[c(1, 3)]
#> trajectory: anonymous, 2 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }
t0[c(3, 1)]
#> trajectory: anonymous, 2 activities
#> { Activity: Release | resource: dummy, amount: 1 }
#> { Activity: Seize | resource: dummy, amount: 1 }Or a set of indices to remove from the selection:
t0[-2]
#> trajectory: anonymous, 2 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }Or by name, but note that this does not respect the order given though, because it performs a match:
t0[c("seize", "release")]
#> trajectory: anonymous, 2 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }
t0[c("release", "seize")]
#> trajectory: anonymous, 2 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }If you provide no indices, the whole trajectory is returned:
t0[]
#> trajectory: anonymous, 3 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Timeout | delay: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }In fact, you are cloning the trajectory with the
latter command. It is equivalent to t0[1:length(t0)] or
join(t0).
The generics head() and tail() use the
[ operator under the hood, thus you can use them as
well:
head(t0, 2)
#> trajectory: anonymous, 2 activities
#> { Activity: Seize | resource: dummy, amount: 1 }
#> { Activity: Timeout | delay: 1 }
tail(t0, -1)
#> trajectory: anonymous, 2 activities
#> { Activity: Timeout | delay: 1 }
#> { Activity: Release | resource: dummy, amount: 1 }The [[ operator can also be used to extract only
one element:
t0[[2]]
#> trajectory: anonymous, 1 activities
#> { Activity: Timeout | delay: 1 }which is equivalent to t0[2]. If a string is provided,
it ensures that only the first match is returned: