Type:	Package
Title:	Discrete-Event Simulation for R
Version:	4.4.7
Description:	A process-oriented and trajectory-based Discrete-Event Simulation (DES) package for R. It is designed as a generic yet powerful framework. The architecture encloses a robust and fast simulation core written in 'C++' with automatic monitoring capabilities. It provides a rich and flexible R API that revolves around the concept of trajectory, a common path in the simulation model for entities of the same type. Documentation about 'simmer' is provided by several vignettes included in this package, via the paper by Ucar, Smeets & Azcorra (2019, <doi:10.18637/jss.v090.i02>), and the paper by Ucar, Hernández, Serrano & Azcorra (2018, <doi:10.1109/MCOM.2018.1700960>); see 'citation("simmer")' for details.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding:	UTF-8
URL:	https://r-simmer.org, https://github.com/r-simmer/simmer
BugReports:	https://github.com/r-simmer/simmer/issues
Depends:	R (≥ 3.4.0)
Imports:	Rcpp, magrittr, codetools, utils
Suggests:	simmer.plot, parallel, testthat, knitr, rmarkdown, rticles
LinkingTo:	Rcpp (≥ 0.12.9)
RoxygenNote:	7.3.2
VignetteBuilder:	knitr
NeedsCompilation:	yes
Packaged:	2024-09-27 15:53:49 UTC; iucar
Author:	Iñaki Ucar [aut, cph, cre], Bart Smeets [aut, cph]
Maintainer:	Iñaki Ucar <iucar@fedoraproject.org>
Repository:	CRAN
Date/Publication:	2024-09-28 00:10:02 UTC

simmer: Discrete-Event Simulation for R

Description

A process-oriented and trajectory-based Discrete-Event Simulation (DES) package for R. Designed to be a generic framework like SimPy or SimJulia, it leverages the power of Rcpp to boost the performance and turning DES in R feasible. As a noteworthy characteristic, simmer exploits the concept of trajectory: a common path in the simulation model for entities of the same type. It is pretty flexible and simple to use, and leverages the chaining/piping workflow introduced by the magrittr package.

Author(s)

Iñaki Ucar and Bart Smeets

References

Ucar I., Smeets B., Azcorra A. (2019). "simmer: Discrete-Event Simulation for R." Journal of Statistical Software, 90(2), 1-30. doi:10.18637/jss.v090.i02.

Ucar I., Hernández J.A., Serrano P., Azcorra A. (2018). "Design and Analysis of 5G Scenarios with simmer: An R Package for Fast DES Prototyping." IEEE Communications Magazine, 56(11), 145-151. doi:10.1109/MCOM.2018.1700960.

See Also

simmer's homepage https://r-simmer.org and GitHub repository https://github.com/r-simmer/simmer.

Examples

## Not run: 
# introduction to simmer
vignette("simmer-01-introduction")

# JSS paper available as vignette
vignette("simmer-02-jss")

# more vignettes
vignette(package = "simmer")

## End(Not run)

Extract or Replace Parts of a Trajectory

Description

Operators acting on trajectories to extract or replace parts.

Usage

## S3 method for class 'trajectory'
x[i]

## S3 method for class 'trajectory'
x[[i]]

## S3 replacement method for class 'trajectory'
x[i] <- value

## S3 replacement method for class 'trajectory'
x[[i]] <- value

Arguments

Value

Returns a new trajectory object.

See Also

length.trajectory, get_n_activities, join.

Examples

x <- join(lapply(1:12, function(i)
  trajectory() %>% timeout(i)
))
x

x[10]                 # the tenth element of x
x[-1]                 # delete the 1st element of x
x[c(TRUE, FALSE)]     # logical indexing
x[c(1, 5, 2, 12, 4)]  # numeric indexing
x[c(FALSE, TRUE)] <- x[c(TRUE, FALSE)] # replacing
x

Activate/Deactivate Sources

Description

Activities for activating or deactivating the generation of arrivals by name. Sources must be defined in the simulation environment (see add_generator, add_dataframe).

Usage

activate(.trj, sources, ..., tag)

deactivate(.trj, sources, ..., tag)

Arguments

Value

Returns the trajectory object.

See Also

set_trajectory, set_source

Examples

traj <- trajectory() %>%
  deactivate("dummy") %>%
  timeout(1) %>%
  activate("dummy")

simmer() %>%
  add_generator("dummy", traj, function() 1) %>%
  run(10) %>%
  get_mon_arrivals()

Add a Data Frame

Description

Attach a new source of arrivals to a trajectory from a data frame.

Usage

add_dataframe(.env, name_prefix, trajectory, data, mon = 1, batch = 50,
  col_time = "time", time = c("interarrival", "absolute"),
  col_attributes = NULL, col_priority = "priority",
  col_preemptible = col_priority, col_restart = "restart")

Arguments

Details

The data frame provided must have, at least, a column of (inter)arrival times. This method will look for it under the name "time" by default, although this can be changed with the col_time parameter.

If there is any column named col_priority="priority", col_preemptible=priority or col_restart="restart", they will be used to set the prioritization values for each arrival (see add_generator).

If there are additional columns (with col_attributes=NULL, by default), they will be assigned to arrival attributes named after each column name. All these columns must be numeric (or logical). Otherwise, if a vector of column names is specified, only these will be assigned as attributes and the rest of the columns will be ignored.

A value of batch=Inf means that the whole data frame will be attached at the beginning of the simulation. This is not desirable in general, because the performance of the event queue is degraded when it is populated with too many events. On the other hand, a low value results in an increased overhead due to many function calls. The default value has been tested to provide a good trade-off.

Value

Returns the simulation environment.

See Also

Other sources: add_generator.

Add a Generator

Description

Attach a new source of arrivals to a trajectory from a generator function.

Usage

add_generator(.env, name_prefix, trajectory, distribution, mon = 1,
  priority = 0, preemptible = priority, restart = FALSE)

Arguments

Value

Returns the simulation environment.

See Also

Convenience functions: at, from, to, from_to, when_activated.

Other sources: add_dataframe.

Add a Global Attribute

Description

Attach a global variable to the simulation.

Usage

add_global(.env, key, value)

Arguments

Value

Returns the simulation environment.

See Also

Convenience functions: schedule.

Add a Resource

Description

Define a new resource in a simulation environment. Resources are conceived with queuing systems in mind, and therefore they comprise two internal self-managed parts: a server, which is the active part, with a specified capacity that can be seized and released (see seize); and a priority queue of a certain size, in which arrivals may wait for the server to be available.

Usage

add_resource(.env, name, capacity = 1, queue_size = Inf, mon = TRUE,
  preemptive = FALSE, preempt_order = c("fifo", "lifo"),
  queue_size_strict = FALSE, queue_priority = c(0, Inf))

Arguments

Details

An entity trying to seize a resource (see seize) may 1) access the server straightaway if there is enough capacity, 2) wait in the queue if there is no room in the server but there is room in the queue, or 3) rejected if there is no room in the queue either.

There are two special situations regarding queue management: 1) the queue_size is shrinked below the actual number of items waiting, and 2) preemption occurs, and an item previously in the server goes to the queue. By default in both cases, the excess of items in the queue is allowed. However, with queue_size_strict=TRUE, the maximum queue_size is guaranteed, and thus some entities will be rejected (dropped) by the resource.

Whenever an arrival is rejected (due to a server drop or a queue drop), it will set the finished flag to FALSE in the output of get_mon_arrivals. Unfinished arrivals can be handled with a drop-out trajectory that can be set using the handle_unfinished activity.

Value

Returns the simulation environment.

See Also

Convenience functions: schedule.

Batch/Separate Arrivals

Description

Activities for collecting a number of arrivals before they can continue processing and splitting a previously established batch.

Usage

batch(.trj, n, timeout = 0, permanent = FALSE, name = "", rule = NULL,
  ..., tag)

separate(.trj, ..., tag)

Arguments

Value

Returns the trajectory object.

Examples

## unnamed batch with a timeout
traj <- trajectory() %>%
  log_("arrived") %>%
  batch(2, timeout=5) %>%
  log_("in a batch") %>%
  timeout(5) %>%
  separate() %>%
  log_("leaving")

simmer() %>%
  add_generator("dummy", traj, at(0:2)) %>%
  run() %>% invisible

## batching based on some dynamic rule
traj <- trajectory() %>%
  log_("arrived") %>%
  # always FALSE -> no batches
  batch(2, rule=function() FALSE) %>%
  log_("not in a batch") %>%
  timeout(5) %>%
  separate() %>%
  log_("leaving")

simmer() %>%
  add_generator("dummy", traj, at(0:2)) %>%
  run() %>% invisible

## named batch, shared across trajectories
traj0 <- trajectory() %>%
  log_("arrived traj0") %>%
  batch(2, name = "mybatch")

traj1 <- trajectory() %>%
  log_("arrived traj1") %>%
  timeout(1) %>%
  batch(2, name = "mybatch") %>%
  log_("in a batch") %>%
  timeout(2) %>%
  separate() %>%
  log_("leaving traj1")

simmer() %>%
  add_generator("dummy0", traj0, at(0)) %>%
  add_generator("dummy1", traj1, at(0)) %>%
  run() %>% invisible

Fork the Trajectory Path

Description

Activity for defining a fork with N alternative sub-trajectories.

Usage

branch(.trj, option, continue, ..., tag)

Arguments

Value

Returns the trajectory object.

Examples

env <- simmer()

traj <- trajectory() %>%
  set_global("path", 1, mod="+", init=-1) %>%
  log_(function() paste("Path", get_global(env, "path"), "selected")) %>%
  branch(
    function() get_global(env, "path"), continue=c(TRUE, FALSE),
    trajectory() %>%
      log_("following path 1"),
    trajectory() %>%
      log_("following path 2")) %>%
  log_("continuing after the branch (path 0)")

env %>%
  add_generator("dummy", traj, at(0:2)) %>%
  run() %>% invisible

Clone/Synchronize Arrivals

Description

Activities for defining a parallel fork and removing the copies. clone replicates an arrival n times (the original one + n-1 copies). synchronize removes all but one clone for each set of clones.

Usage

clone(.trj, n, ..., tag)

synchronize(.trj, wait = TRUE, mon_all = FALSE, ..., tag)

Arguments

Value

Returns the trajectory object.

Examples

## clone and wait for the others
traj <- trajectory() %>%
  clone(
    n = 3,
    trajectory() %>%
      log_("clone 0 (original)") %>%
      timeout(1),
    trajectory() %>%
      log_("clone 1") %>%
      timeout(2),
    trajectory() %>%
      log_("clone 2") %>%
      timeout(3)) %>%
  log_("sync reached") %>%
  synchronize(wait = TRUE) %>%
  log_("leaving")

simmer() %>%
  add_generator("arrival", traj, at(0)) %>%
  run() %>% invisible

## more clones that trajectories available
traj <- trajectory() %>%
  clone(
    n = 5,
    trajectory() %>%
      log_("clone 0 (original)") %>%
      timeout(1)) %>%
  log_("sync reached") %>%
  synchronize(wait = TRUE) %>%
  log_("leaving")

simmer() %>%
  add_generator("arrival", traj, at(0)) %>%
  run() %>% invisible

## clone and continue without waiting
traj <- trajectory() %>%
  clone(
    n = 3,
    trajectory() %>%
      log_("clone 0 (original)") %>%
      timeout(1),
    trajectory() %>%
      log_("clone 1") %>%
      timeout(2),
    trajectory() %>%
      log_("clone 2") %>%
      timeout(3)) %>%
  log_("sync reached") %>%
  synchronize(wait = FALSE) %>%
  log_("leaving")

simmer() %>%
  add_generator("arrival", traj, at(0)) %>%
  run() %>% invisible

Convenience Functions for Generators

Description

These convenience functions facilitate the definition of generators of arrivals for some common cases.

Usage

at(...)

from(start_time, dist, arrive = TRUE)

to(stop_time, dist)

from_to(start_time, stop_time, dist, arrive = TRUE, every = NULL)

when_activated(n = 1)

Arguments

Details

at generates arrivals at specific absolute times.

from generates inter-arrivals following a given distribution with a specified start time. union of the last two.

to generates inter-arrivals following a given distribution with a specified stop time.

from_to is the union of from and to.

when_activated sets up an initially inactive generator which generates n arrivals each time it is activated from any trajectory using the activity activate.

Value

Returns a generator function (a closure).

See Also

add_generator.

Examples

## common to all examples below
# some trajectory
t0 <- trajectory() %>%
  timeout(0)
# some distribution
distr <- function() runif(1, 1, 2)

# arrivals at 0, 1, 10, 30, 40 and 43
simmer() %>%
  add_generator("dummy", t0, at(0, c(1,10,30), 40, 43)) %>%
  run(100) %>%
  get_mon_arrivals()

# apply distribution starting at 5 (and no end)
simmer() %>%
  add_generator("dummy", t0, from(5, distr)) %>%
  run(10) %>%
  get_mon_arrivals()

# apply distribution until 5 (starting at 0)
simmer() %>%
  add_generator("dummy", t0, to(5, distr)) %>%
  run(10) %>%
  get_mon_arrivals()

# apply distribution from 8 to 16 h every 24 h:
simmer() %>%
  add_generator("dummy", t0, from_to(8, 16, distr, every=24)) %>%
  run(48) %>%
  get_mon_arrivals()

# triggering arrivals on demand from a trajectory
t1 <- trajectory() %>%
  activate("dummy")

simmer() %>%
  add_generator("dummy", t0, when_activated()) %>%
  add_generator("trigger", t1, at(2)) %>%
  run() %>%
  get_mon_arrivals()

Get Resource Parameters

Description

Getters for resources: server capacity/count and queue size/count, seized amount, activity time, and selected resources.

Usage

get_capacity(.env, resources)

get_capacity_selected(.env, id = 0)

get_queue_size(.env, resources)

get_queue_size_selected(.env, id = 0)

get_server_count(.env, resources)

get_server_count_selected(.env, id = 0)

get_queue_count(.env, resources)

get_queue_count_selected(.env, id = 0)

get_seized(.env, resources)

get_seized_selected(.env, id = 0)

get_activity_time(.env, resources)

get_activity_time_selected(.env, id = 0)

get_selected(.env, id = 0)

Arguments

Details

If no resources are provided to get_activity_time, the overall activity time is reported.

Value

Return a vector (character for get_selected, numeric for the rest of them).

See Also

get_resources, set_capacity, set_queue_size, seize, timeout.

Monitoring Statistics

Description

Getters for obtaining monitored data (if any) about arrivals, attributes and resources.

Usage

get_mon_arrivals(.envs, per_resource = FALSE, ongoing = FALSE)

get_mon_attributes(.envs)

get_mon_resources(.envs)

Arguments

Value

Returns a data frame.

Get Process Parameters

Description

Getters for processes (sources and arrivals) number of arrivals generated by a source, the name of the active arrival, an attribute from the active arrival or a global one, prioritization values, or the number of arrivals in an active batch.

Usage

get_n_generated(.env, sources)

get_trajectory(.env, sources)

get_name(.env)

get_start_time(.env)

get_attribute(.env, keys)

get_global(.env, keys)

get_prioritization(.env)

get_batch_size(.env)

Arguments

Details

get_n_generated returns the number of arrivals generated by the given sources. get_trajectory returns the trajectory to which they are attached (as a list).

get_name returns the number of the running arrival. get_start_time returns the start time of the running arrival. get_attribute returns a running arrival's attributes. If a provided key was not previously set, it returns a missing value. get_global returns a global attribute. get_prioritization returns a running arrival's prioritization values. get_name, get_start_time, get_attribute and get_prioritization are meant to be used inside a trajectory; otherwise, there will be no arrival running and these functions will throw an error.

See Also

get_sources, set_trajectory, set_attribute, set_global, set_prioritization, batch.

Get Sources and Resources Defined

Description

Get a list of names of sources or resources defined in a simulation environment.

Usage

get_sources(.env)

get_resources(.env)

Arguments

Value

A character vector.

Handle Unfinished Arrivals

Description

Activity for setting a drop-out trajectory for unfinished arrivals, i.e., those dropped from a resource (due to preemption, resource shrinkage or a rejected seize) or those that leave a trajectory.

Usage

handle_unfinished(.trj, handler, ..., tag)

Arguments

Value

Returns the trajectory object.

See Also

leave, set_capacity

Examples

traj <- trajectory() %>%
  log_("arrived") %>%
  handle_unfinished(
    trajectory() %>%
      log_("preempted!")) %>%
  seize("res") %>%
  log_("resource seized") %>%
  timeout(10) %>%
  release("res") %>%
  log_("leaving")

simmer() %>%
  add_resource("res", 1, 0, preemptive=TRUE, queue_size_strict=TRUE) %>%
  add_generator("dummy", traj, at(0)) %>%
  add_generator("priority_dummy", traj, at(5), priority=1) %>%
  run() %>% invisible

Join Trajectories

Description

Concatenate any number of trajectories in the specified order.

Usage

join(...)

Arguments

Value

Returns a new trajectory object.

See Also

Extract.trajectory, length.trajectory, get_n_activities.

Examples

t1 <- trajectory() %>% seize("dummy", 1)
t2 <- trajectory() %>% timeout(1)
t3 <- trajectory() %>% release("dummy", 1)

## join can be used alone
join(t1, t2, t3)

## or can be chained in a trajectory definition
trajectory() %>%
  join(t1) %>%
  timeout(1) %>%
  join(t3)

Number of Activities in a Trajectory

Description

Get the number of activities in a trajectory. length returns the number of first-level activities (sub-trajectories not included). get_n_activities returns the total number of activities (sub-trajectories included).

Usage

## S3 method for class 'trajectory'
length(x)

get_n_activities(x)

Arguments

Value

Returns a non-negative integer of length 1.

See Also

Extract.trajectory, join.

Examples

x <- trajectory() %>%
  timeout(1)

x <- x %>%
  clone(2, x, x)
x

## length does not account for subtrajectories
length(x)
get_n_activities(x)

Debugging

Description

Activities for displaying messages preceded by the simulation time and the name of the arrival, and for setting conditional breakpoints.

Usage

log_(.trj, message, level = 0, ..., tag)

stop_if(.trj, condition, ..., tag)

Arguments

Value

Returns the trajectory object.

Examples

## log levels
traj <- trajectory() %>%
  log_("this is always printed") %>% # level = 0 by default
  log_("this is printed if `log_level>=1`", level = 1) %>%
  log_("this is printed if `log_level>=2`", level = 2)

simmer() %>%
  add_generator("dummy", traj, at(0)) %>%
  run() %>% invisible

simmer(log_level = 1) %>%
  add_generator("dummy", traj, at(0)) %>%
  run() %>% invisible

simmer(log_level = Inf) %>%
  add_generator("dummy", traj, at(0)) %>%
  run() %>% invisible

Create a Monitor

Description

Methods for creating monitor objects for simulation environments.

Usage

monitor(name, xptr, get_arrivals, get_attributes, get_resources,
  handlers = NULL, finalizer = NULL)

monitor_mem()

monitor_delim(path = tempdir(), keep = FALSE, sep = " ", ext = ".txt",
  reader = read.delim, args = list(stringsAsFactors = FALSE))

monitor_csv(path = tempdir(), keep = FALSE, reader = read.csv,
  args = list(stringsAsFactors = FALSE))

Arguments

Details

The monitor method is a generic function to instantiate a monitor object. It should not be used in general unless you want to extend simmer with a custom monitor.

The in-memory monitor is enabled by default (memory_mem), and it should the fastest.

For large simulations, or if the RAM footprint is an issue, you may consider monitoring to disk. To that end, monitor_delim stores the values in flat delimited files. The usual get_mon_* methods retrieve data frames from such files using the reader provided. By default, read.delim is used, but you may consider using faster alternatives from other packages. It is also possible to keep the files in a custom directory to read and post-process them in a separate workflow.

monitor_csv is a special case of monitor_delim with sep="," and ext=".csv".

Value

A monitor object.

Examples

mon <- monitor_csv()
mon

env <- simmer(mon=mon) %>%
  add_generator("dummy", trajectory() %>% timeout(1), function() 1) %>%
  run(10)
env

read.csv(mon$handlers$arrivals) # direct access
get_mon_arrivals(env)           # adds the "replication" column

Simulation Time

Description

Get the current simulation time.

Usage

now(.env)

Arguments

Value

Returns a numeric value.

See Also

peek.

Peek Next Events

Description

Look for future events in the event queue and (optionally) obtain info about them.

Usage

peek(.env, steps = 1, verbose = FALSE)

Arguments

Value

Returns numeric values if verbose=F and a data frame otherwise.

See Also

now.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

magrittr

%>%

Renege on some Condition

Description

Activities for leaving with some probability, or for setting or unsetting a timer or a signal after which the arrival will abandon.

Usage

leave(.trj, prob, out = NULL, keep_seized = TRUE, ..., tag)

renege_in(.trj, t, out = NULL, keep_seized = FALSE, ..., tag)

renege_if(.trj, signal, out = NULL, keep_seized = FALSE, ..., tag)

renege_abort(.trj, ..., tag)

Arguments

Details

Arrivals that leave the trajectory will set the finished flag to FALSE in the output of get_mon_arrivals. Unfinished arrivals can be handled with a drop-out trajectory that can be set using the optional argument out or the handle_unfinished activity.

Note that, for historical reasons, leave has keep_seized=TRUE by default, while renege_* does not.

Note that renege_if works similarly to trap, but in contrast to that, reneging is triggered even if the arrival is waiting in a queue or is part of a non-permanent batch.

Value

Returns the trajectory object.

See Also

handle_unfinished

send

Examples

## leave with some probability
set.seed(1234)

traj <- trajectory() %>%
  log_("leave with some probability") %>%
  leave(function() runif(1) < 0.5) %>%
  log_("didn't leave")

simmer() %>%
  add_generator("dummy", traj, at(0, 1)) %>%
  run() %>% invisible

## reneging after some time
bank <- trajectory() %>%
  log_("here I am") %>%
  # renege in 5 minutes
  renege_in(
    5,
    out = trajectory() %>%
      log_("lost my patience. Reneging...")) %>%
  seize("clerk") %>%
  # stay if I'm being attended within 5 minutes
  renege_abort() %>%
  log_("I'm being attended") %>%
  timeout(10) %>%
  release("clerk") %>%
  log_("finished")

simmer() %>%
  add_resource("clerk", 1) %>%
  add_generator("customer", bank, at(0, 1)) %>%
  run() %>% invisible

Reset a Simulator

Description

Reset the following components of a simulation environment: time, event queue, resources, sources and statistics.

Usage

reset(.env)

Arguments

Value

Returns the simulation environment.

See Also

stepn, run.

Rollback to a Previous Activity

Description

Activity for going backwards to a previous point in the trajectory. Useful to implement loops.

Usage

rollback(.trj, target, times = Inf, check = NULL, ..., tag)

Arguments

Value

Returns the trajectory object.

Examples

## rollback a specific number of times
traj <- trajectory() %>%
  log_("hello!") %>%
  timeout(1) %>%
  rollback(2, 3)

simmer() %>%
  add_generator("hello_sayer", traj, at(0)) %>%
  run() %>% invisible

## same but with a tag as target
traj <- trajectory() %>%
  log_("hello!", tag="msg") %>%
  timeout(1) %>%
  rollback("msg", 3)

simmer() %>%
  add_generator("hello_sayer", traj, at(0)) %>%
  run() %>% invisible

## custom check
env <- simmer()

traj <- trajectory() %>%
  set_attribute("var", 0) %>%
  log_(tag="msg", function()
    paste("attribute level is at:", get_attribute(env, "var"))) %>%
  set_attribute("var", 25, mod="+") %>%
  rollback("msg", check=function() get_attribute(env, "var") < 100) %>%
  log_("done")

env %>%
  add_generator("dummy", traj, at(0)) %>%
  run() %>% invisible

Run a Simulation

Description

Execute steps until a given criterion.

Usage

run(.env, until = Inf, progress = NULL, steps = 10)

stepn(.env, n = 1)

Arguments

Value

Returns the simulation environment.

See Also

reset.

Examples

## show the progress just printing the steps
simmer() %>%
  run(progress=message, steps=5)

## using the 'progress' package
## Not run: 
mm1 <- trajectory() %>%
  seize("server", 1) %>%
  timeout(function() rexp(1, 66)) %>%
  release("server", 1)

simmer() %>%
  add_resource("server", 1) %>%
  add_generator("customer", mm1, function() rexp(100, 60)) %>%
  run(3000, progress=progress::progress_bar$new()$update)

## End(Not run)

Generate a Scheduling Object

Description

Resource convenience function to generate a scheduling object from a timetable specification.

Usage

schedule(timetable, values, period = Inf)

Arguments

Value

Returns a schedule object.

See Also

add_resource.

Examples

# Schedule 3 units from 8 to 16 h
#          2 units from 16 to 24 h
#          1 units from 24 to 8 h
capacity_schedule <- schedule(c(8, 16, 24), c(3, 2, 1), period=24)

env <- simmer() %>%
  add_resource("dummy", capacity_schedule)

# Composition of schedules
sch1 <- schedule(c(8, 16), c(3, 0), period=24)
sch2 <- schedule(c(16, 24), c(2, 1), period=24)
all.equal(sch1 + sch2, capacity_schedule)

Seize/Release Resources

Description

Activities for seizing/releasing a resource, by name or a previously selected one. Resources must be defined in the simulation environment (see add_resource).

Usage

seize(.trj, resource, amount = 1, continue = NULL, post.seize = NULL,
  reject = NULL, ..., tag)

seize_selected(.trj, amount = 1, id = 0, continue = NULL,
  post.seize = NULL, reject = NULL, ..., tag)

release(.trj, resource, amount = 1, ..., tag)

release_selected(.trj, amount = 1, id = 0, ..., tag)

release_all(.trj, resource, ..., tag)

release_selected_all(.trj, id = 0, ..., tag)

Arguments

Details

Rejection happens when a resource is at full capacity and there is no room in the queue (either because there is a finite queue_size and it is full, or because queue_size=0 and thus it is disabled). In those cases, the reject parameter defines a fallback trajectory. Note, however, that, if the arrival is accepted (either in the queue or in the server) and then it is dropped afterwards due to preemption or resource shrinkage, then this trajectory will not be executed. Instead, see handle_unfinished for another, more general, method for handling all kinds of unfinished arrivals.

Value

Returns the trajectory object.

See Also

select, set_capacity, set_queue_size, set_capacity_selected, set_queue_size_selected

Examples

## simple seize, delay, then release
traj <- trajectory() %>%
  seize("doctor", 1) %>%
  timeout(3) %>%
  release("doctor", 1)

simmer() %>%
  add_resource("doctor", capacity=1) %>%
  add_generator("patient", traj, at(0, 1)) %>%
  run() %>%
  get_mon_resources()

## arrival rejection (no space left in the queue)
traj <- trajectory() %>%
  log_("arriving...") %>%
  seize("doctor", 1) %>%
  # the second patient won't reach this point
  log_("doctor seized") %>%
  timeout(5) %>%
  release("doctor", 1)

simmer() %>%
  add_resource("doctor", capacity=1, queue_size=0) %>%
  add_generator("patient", traj, at(0, 1)) %>%
  run() %>% invisible

## capturing rejection to retry
traj <- trajectory() %>%
  log_("arriving...") %>%
  seize(
    "doctor", 1, continue = FALSE,
    reject = trajectory() %>%
      log_("rejected!") %>%
      # go for a walk and try again
      timeout(2) %>%
      log_("retrying...") %>%
      rollback(amount = 4, times = Inf)) %>%
  # the second patient will reach this point after a couple of walks
  log_("doctor seized") %>%
  timeout(5) %>%
  release("doctor", 1) %>%
  log_("leaving")

simmer() %>%
  add_resource("doctor", capacity=1, queue_size=0) %>%
  add_generator("patient", traj, at(0, 1)) %>%
  run() %>% invisible

## combining post.seize and reject
traj <- trajectory() %>%
  log_("arriving...") %>%
  seize(
    "doctor", 1, continue = c(TRUE, TRUE),
    post.seize = trajectory("admitted patient") %>%
      log_("admitted") %>%
      timeout(5) %>%
      release("doctor", 1),
    reject = trajectory("rejected patient") %>%
      log_("rejected!") %>%
      seize("nurse", 1) %>%
      timeout(2) %>%
      release("nurse", 1)) %>%
  # both patients will reach this point, as continue = c(TRUE, TRUE)
  timeout(10) %>%
  log_("leaving...")

simmer() %>%
  add_resource("doctor", capacity=1, queue_size=0) %>%
  add_resource("nurse", capacity=10, queue_size=0) %>%
  add_generator("patient", traj, at(0, 1)) %>%
  run() %>% invisible

Select Resources

Description

Activity for selecting a resource for a subsequent seize/release or setting its parameters (capacity or queue size). Resources must be defined in the simulation environment (see add_resource).

Usage

select(.trj, resources, policy = c("shortest-queue",
  "shortest-queue-available", "round-robin", "round-robin-available",
  "first-available", "random", "random-available"), id = 0, ..., tag)

Arguments

Details

The 'shortest-queue' policy selects the least busy resource; 'round-robin' selects resources in cyclical order; 'first-available' selects the first resource available, and 'random' selects a resource randomly.

All the 'available'-ending policies ('first-available', but also 'shortest-queue-available', 'round-robin-available' and 'random-available') check for resource availability (i.e., whether the capacity is non-zero), and exclude from the selection procedure those resources with capacity set to zero. This means that, for these policies, an error will be raised if all resources are unavailable.

Value

Returns the trajectory object.

See Also

seize_selected, release_selected, set_capacity_selected, set_queue_size_selected

Examples

## predefined policy
traj <- trajectory() %>%
  select(paste0("doctor", 1:3), "round-robin") %>%
  seize_selected(1) %>%
  timeout(5) %>%
  release_selected(1)

simmer() %>%
  add_resource("doctor1") %>%
  add_resource("doctor2") %>%
  add_resource("doctor3") %>%
  add_generator("patient", traj, at(0, 1, 2)) %>%
  run() %>%
  get_mon_resources()

## custom policy
env <- simmer()
res <- paste0("doctor", 1:3)

traj <- trajectory() %>%
  select(function() {
    occ <- get_server_count(env, res) + get_queue_count(env, res)
    res[which.min(occ)[1]]
  }) %>%
  seize_selected(1) %>%
  timeout(5) %>%
  release_selected(1)

for (i in res) env %>%
  add_resource(i)
env %>%
  add_generator("patient", traj, at(0, 1, 2)) %>%
  run() %>%
  get_mon_resources()

Inter-arrival Communication

Description

These activities enable asynchronous programming. send() broadcasts a signal or a list of signals. Arrivals can subscribe to signals and (optionally) assign a handler with trap(). Note that, while inside a batch, all the signals subscribed before entering the batch are ignored. Upon a signal reception, the arrival stops the current activity and executes the handler (if provided). Then, the execution returns to the activity following the point of the interruption. untrap() can be used to unsubscribe from signals. wait() blocks until a signal is received.

Usage

send(.trj, signals, delay = 0, ..., tag)

trap(.trj, signals, handler = NULL, interruptible = TRUE, ..., tag)

untrap(.trj, signals, ..., tag)

wait(.trj, ..., tag)

Arguments

Value

Returns the trajectory object.

See Also

renege_if

Examples

## block, signal and continue with a handler
signal <- "you shall pass"

t_blocked <- trajectory() %>%
  trap(
    signal,
    trajectory() %>%
      log_("executing the handler")) %>%
  log_("waiting...") %>%
  wait() %>%
  log_("continuing!")

t_signaler <- trajectory() %>%
  log_(signal) %>%
  send(signal)

simmer() %>%
  add_generator("blocked", t_blocked, at(0)) %>%
  add_generator("signaler", t_signaler, at(5)) %>%
  run() %>% invisible

## handlers can be interrupted, unless interruptible=FALSE
t_worker <- trajectory() %>%
  trap(
  signal,
  handler = trajectory() %>%
    log_("ok, I'm packing...") %>%
    timeout(1)) %>%
  log_("performing a looong task...") %>%
  timeout(100) %>%
  log_("and I'm leaving!")

simmer() %>%
  add_generator("worker", t_worker, at(0)) %>%
  add_generator("signaler", t_signaler, at(5, 5.5)) %>%
  run() %>% invisible

Set Attributes

Description

Activity for modifying attributes. Attributes defined with set_attribute are per arrival, meaning that each arrival has its own set of attributes, not visible by any other one. On the other hand, attributes defined with set_global are shared by all the arrivals in the simulation.

Usage

set_attribute(.trj, keys, values, mod = c(NA, "+", "*"), init = 0, ...,
  tag)

set_global(.trj, keys, values, mod = c(NA, "+", "*"), init = 0, ..., tag)

Arguments

Details

Attribute monitoring is disabled by default. To enable it, set mon=2 in the corresponding source (see, e.g., add_generator). Then, the evolution of the attributes during the simulation can be retrieved with get_mon_attributes. Global attributes are reported as unnamed key/value pairs.

Value

Returns the trajectory object.

See Also

get_attribute, get_global, timeout_from_attribute, timeout_from_global

Examples

env <- simmer()

traj <- trajectory() %>%

  # simple assignment
  set_attribute("my_key", 123) %>%
  set_global("global_key", 321) %>%

  # more than one assignment at once
  set_attribute(c("my_key", "other_key"), c(5, 64)) %>%

  # increment
  set_attribute("my_key", 1, mod="+") %>%

  # assignment using a function
  set_attribute("independent_key", function() runif(1)) %>%

  # assignment dependent on another attribute
  set_attribute("dependent_key", function()
    ifelse(get_attribute(env, "my_key") <= 0.5, 1, 0))

env %>%
  add_generator("dummy", traj, at(3), mon=2) %>%
  run() %>%
  get_mon_attributes()

Set Resource Parameters

Description

Activities for dynamically modifying a resource's server capacity or queue size, by name or a previously selected one. Resources must be defined in the simulation environment (see add_resource).

Usage

set_capacity(.trj, resource, value, mod = c(NA, "+", "*"), ..., tag)

set_capacity_selected(.trj, value, id = 0, mod = c(NA, "+", "*"), ..., tag)

set_queue_size(.trj, resource, value, mod = c(NA, "+", "*"), ..., tag)

set_queue_size_selected(.trj, value, id = 0, mod = c(NA, "+", "*"), ...,
  tag)

Arguments

Value

Returns the trajectory object.

See Also

select, seize, release, seize_selected, release_selected, get_capacity, get_queue_size

Examples

## a resource with a queue size equal to the number of arrivals waiting
traj <- trajectory() %>%
  set_queue_size("res", 1, mod="+") %>%
  seize("res") %>%
  set_queue_size("res", -1, mod="+") %>%
  timeout(10) %>%
  release("res")

simmer() %>%
  add_resource("res", 1, 0) %>%
  add_generator("dummy", traj, at(0:2)) %>%
  run() %>%
  get_mon_resources()

Set Prioritization Values

Description

Activity for dynamically modifying an arrival's prioritization values. Default prioritization values are defined by the source (see add_generator, add_dataframe).

Usage

set_prioritization(.trj, values, mod = c(NA, "+", "*"), ..., tag)

Arguments

Value

Returns the trajectory object.

See Also

get_prioritization

Examples

traj <- trajectory() %>%

  # static values
  set_prioritization(c(3, 7, TRUE)) %>%

  # increment
  set_prioritization(c(2, 1, 0), mod="+") %>%

  # dynamic, custom
  set_attribute("priority", 3) %>%
  set_prioritization(function() {
    prio <- get_prioritization(env)
    attr <- get_attribute(env, "priority")
    c(attr, prio[[2]]+1, FALSE)
  })

Set Source Parameters

Description

Activities for modifying a source's trajectory or source object by name. Sources must be defined in the simulation environment (see add_generator, add_dataframe).

Usage

set_trajectory(.trj, sources, trajectory, ..., tag)

set_source(.trj, sources, object, ..., tag)

Arguments

Value

Returns the trajectory object.

See Also

activate, deactivate

Examples

traj1 <- trajectory() %>%
  timeout(1)

traj2 <- trajectory() %>%
  set_source("dummy", function() 1) %>%
  set_trajectory("dummy", traj1) %>%
  timeout(2)

simmer() %>%
  add_generator("dummy", traj2, function() 2) %>%
  run(6) %>%
  get_mon_arrivals()

Create a Simulator

Description

This method initialises a simulation environment.

Usage

simmer(name = "anonymous", verbose = FALSE, mon = monitor_mem(),
  log_level = 0)

Arguments

Value

Returns a simulation environment.

See Also

Available methods by category:

• Simulation control: stepn, run, now, peek, reset

• Resources: add_resource, get_resources, get_capacity, get_capacity_selected, get_queue_size, get_queue_size_selected, get_server_count, get_server_count_selected, get_queue_count, get_queue_count_selected, get_seized, get_seized_selected, get_activity_time, get_activity_time_selected, get_selected

• Sources: add_generator, add_dataframe, get_sources, get_n_generated, get_trajectory

• Arrivals: get_name, get_start_time, get_attribute, get_prioritization, get_batch_size

• Globals: add_global, get_global

• Data retrieval: get_mon_arrivals, get_mon_attributes, get_mon_resources

Examples

## a simple trajectory that prints a message
t0 <- trajectory("my trajectory") %>%
  log_("arrival generated")

## create an empty simulation environment
env <- simmer("SuperDuperSim")
env

## add a generator and attach it to the trajectory above
env %>% add_generator("dummy", t0, function() 1)

## run for some time
env %>% run(until=4.5)
env %>% now()           # current simulation time
env %>% peek()          # time for the next event
env %>% stepn()         # execute next event

Delay

Description

Activity for inserting delays and execute user-defined tasks.

Usage

timeout(.trj, task, ..., tag)

timeout_from_attribute(.trj, key, ..., tag)

timeout_from_global(.trj, key, ..., tag)

Arguments

Value

Returns the trajectory object.

See Also

set_attribute, set_global

set_attribute, set_global

Examples

env <- simmer()

traj <- trajectory() %>%

  # static delay
  timeout(3) %>%

  # dynamic, exponential delay
  timeout(function() rexp(1, 10)) %>%

  # dependent on an attribute
  set_attribute("delay", 2) %>%
  set_global("other", function() rexp(1, 2)) %>%
  timeout_from_attribute("delay") %>%
  timeout_from_global("other")

env %>%
  add_generator("dummy", traj, at(0)) %>%
  run() %>%
  get_mon_arrivals()

Create a Trajectory

Description

This method initialises a trajectory object, which comprises a chain of activities that can be attached to a generator. See below for a complete list of available activities by category.

Usage

trajectory(name = "anonymous", verbose = FALSE)

Arguments

Value

Returns an environment that represents the trajectory.

See Also

Available activities by category:

• Debugging: log_, stop_if

• Delays: timeout, timeout_from_attribute, timeout_from_global

• Arrival properties: set_attribute, set_global, set_prioritization

• Interaction with resources: select, seize, release, release_all, seize_selected, release_selected, release_selected_all, set_capacity, set_queue_size, set_capacity_selected, set_queue_size_selected

• Interaction with generators: activate, deactivate, set_trajectory, set_source

• Branching: branch, clone, synchronize

• Loops: rollback

• Batching: batch, separate

• Asynchronous programming: send, trap, untrap, wait

• Reneging: leave, handle_unfinished, renege_in, renege_if, renege_abort

Manage trajectories:

• Extract or Replace Parts of a Trajectory: Extract.trajectory

• Join Trajectories: join

• Number of Activities in a Trajectory: length.trajectory, get_n_activities

Examples

## create an empty trajectory
x <- trajectory("my trajectory")
x

## add some activities by chaining them
x <- x %>%
  log_("here I am!") %>%
  timeout(5) %>%
  log_("leaving!")
x

## join trajectories
x <- join(x, x)

## extract and replace
x[c(3, 4)] <- x[2]
x

Wrap a Simulation Environment

Description

This function extracts the monitored data from a simulation environment making it accessible through the same methods. Only useful if you want to parallelize heavy replicas (see the example below), because the C++ simulation backend is destroyed when the threads exit.

Usage

wrap(.env)

Arguments

Value

Returns a simulation wrapper.

See Also

Methods for dealing with a simulation wrapper: get_mon_arrivals, get_mon_attributes, get_mon_resources, get_n_generated, get_capacity, get_queue_size, get_server_count, get_queue_count.

Examples

## Not run: 
library(parallel)

mm1 <- trajectory() %>%
  seize("server", 1) %>%
  timeout(function() rexp(1, 2)) %>%
  release("server", 1)

envs <- mclapply(1:4, function(i) {
  simmer("M/M/1 example") %>%
    add_resource("server", 1) %>%
    add_generator("customer", mm1, function() rexp(1, 1)) %>%
    run(100) %>%
    wrap()
})

## End(Not run)