Categoría: R

New features:

• New getters (#159):
  • get_sources() and get_resources() retrieve a character vector of source/resource names defined in a simulation environment.
  • get_trajectory() retrieves a trajectory to which a given source is attached.
• New resource selection policies: shortest-queue-available, round-robin-available, random-available (#156). These are the same as the existing non-available ones, but they exclude unavailable resources (capacity set to zero). Thus, if all resources are unavailable, an error is raised.

Minor changes and fixes:

• Rename -DRCPP_PROTECTED_EVAL (Rcpp >= 0.12.17.4) as -DRCPP_USE_UNWIND_PROTECT (6d27671).
• Keep compilation quieter with -DBOOST_NO_AUTO_PTR (70328b6).
• Improve log_ print (7c2e3b1).
• Add when_activated() convenience function to easily generate arrivals on demand from trajectories (#161 closing #160).
• Enhance schedule printing (9c66285).
• Fix generator-manager name clashing (#163).
• Deprecate set_attribute(global=TRUE), get_attribute(global=TRUE) and timeout_from_attribute(global=TRUE) (#164), the *_global versions should be used instead.

Some motivation

Here is a small comparison of the old and the new APIs. The following toy example just calls an R function N times from C++. A pure R for loop is also provided as a reference.

Rcpp::cppFunction('
  void old_api(Function func, int n) {
    for (int i=0; i<n; i++) func();
  }
')

Rcpp::cppFunction(plugins = "unwindProtect", '
  void new_api(Function func, int n) {
    for (int i=0; i<n; i++) func();
  }
')

reference <- function(func, N) {
  for (i in 1:N) func()
}

func <- function() 1
N <- 1e6

system.time(old_api(func, N))

##    user  system elapsed 
##  17.863   0.006  17.950

system.time(new_api(func, N))

##    user  system elapsed 
##   0.289   0.000   0.290

system.time(reference(func, N))

##    user  system elapsed 
##   0.216   0.000   0.217

Obviously, there is still some penalty compared to not switching between domains, but the performance gain with respect to the old API is outstanding.

A real-world example

This is a quite heavy simulation of an M/M/1 system using simmer:

library(simmer)

system.time({
  mm1 <- trajectory() %>%
    seize("server", 1) %>%
    timeout(function() rexp(1, 66)) %>%
    release("server", 1)

  env <- simmer() %>%
    add_resource("server", 1) %>%
    add_generator("customer", mm1, function() rexp(50, 60), mon=F) %>%
    run(10000, progress=progress::progress_bar$new()$update)
})

In my system, it takes around 17 seconds with the old API. The new API makes it in less than 5 seconds. As a reference, if we avoid R calls in the timeout activity and precompute all the arrivals instead of defining a dynamic generator, i.e.:

system.time({
  input <- data.frame(
    time = rexp(10000*60, 60),
    service = rexp(10000*60, 66)
  )

  mm1 <- trajectory() %>%
    seize("server", 1) %>%
    timeout_from_attribute("service") %>%
    release("server", 1)

  env <- simmer() %>%
    add_resource("server", 1) %>%
    add_dataframe("customer", mm1, input, mon=F, batch=50) %>%
    run(10000, progress=progress::progress_bar$new()$update)
})

then the simulation takes around 2.5 seconds.

How to start using this feature

First of all, you need R >= 3.5.0 and Rcpp >= 0.12.18 installed. Then, if you are a user, the easiest way to enable this globally is to add CPPFLAGS += -DRCPP_USE_UNWIND_PROTECT to your ~/.R/Makevars. Packages installed or re-installed, as well as functions compiled with Rcpp::sourceCpp and Rcpp::cppFunction, will benefit from this performance gains. If you are a package maintainer, you can add -DRCPP_USE_UNWIND_PROTECT to your package’s PKG_CPPFLAGS in src/Makevars. Alternatively, there is a plugin available, so this flag can be enabled by adding [[Rcpp::plugins(unwindProtect)]] to one of your source files.

Note that this is fairly safe according to reverse dependency checks, but there might be still issues in some packages. But the sooner we start testing this feature and reporting possible issues, the sooner it will be enabled by default in Rcpp.

New features:

• The C++ core has been refactorised into a header-only library under inst/include (#147 closing #145). Therefore, from now on it is possible to extend the C++ API from another package by listing simmer under the LinkingTo field in the DESCRIPTION file.
• New generic monitor constructor enables the development of new monitoring backends in other packages (179f656, as part of #147).
• New simulation-scoped logging levels. The log_ activity has a new argument level which determines whether the message is printed depending on a global log_level defined in the simmer constructor (#152).
• set_attribute and set_global gain a new argument to automatically initialise new attributes (#157). Useful to update counters and indexes in a single line, without initialisation boilerplate.

Minor changes and fixes:

• Enhanced exception handling, with more informative error messages (#148).
• Refactorisation of the printing methods and associated code (#149).
• Allow empty trajectories in sources and activities with sub-trajectories (#151 closing #150).
• Enable -DRCPP_PROTECTED_EVAL (Rcpp >= 0.12.17.3), which provides fast evaluation of R expressions by leveraging the new stack unwinding protection API (R >= 3.5.0).
• Replace backspace usage in vector’s ostream method (2b2f43e).
• Fix namespace clashes with rlang and purrr (#154).

Attachment of precomputed data

Until v3.7.0, the generator was the only means to attach data to trajectories, and it was primarily intended for dynamic generation of arrivals:

library(simmer)
set.seed(42)

hello_sayer <- trajectory() %>%
  log_("hello!")

simmer() %>%
  add_generator("dummy", hello_sayer, function() rexp(1, 1)) %>%
  run(until=2)

## 0.198337: dummy0: hello!
## 0.859232: dummy1: hello!
## 1.14272: dummy2: hello!
## 1.18091: dummy3: hello!
## 1.65409: dummy4: hello!

## simmer environment: anonymous | now: 2 | next: 3.11771876826972
## { Monitor: in memory }
## { Source: dummy | monitored: 1 | n_generated: 6 }

Although it may be used to attach precomputed data too, especially using the at() adaptor:

simmer() %>%
  add_generator("dummy", hello_sayer, at(seq(0, 10, 0.5))) %>%
  run(until=2)

## 0: dummy0: hello!
## 0.5: dummy1: hello!
## 1: dummy2: hello!
## 1.5: dummy3: hello!

## simmer environment: anonymous | now: 2 | next: 2
## { Monitor: in memory }
## { Source: dummy | monitored: 1 | n_generated: 21 }

Now, let’s say that we want to attach some empirical data, and our observations not only include arrival times, but also priorities and some attributes (e.g., measured service times), as in this question on StackOverflow:

myData <- data.frame(
  time = c(1:10,1:5), 
  priority = 1:3, 
  duration = rnorm(15, 50, 5)) %>%
  dplyr::arrange(time)

This is indeed possible using generators, but it requires some trickery; more specifically, the clever usage of a consumer function as follows:

consume <- function(x, prio=FALSE) {
  i <- 0
  function() {
    i <<- i + 1
    if (prio) c(x[[i]], x[[i]], FALSE)
    else x[[i]]
  }
}

activityTraj <- trajectory() %>%
  seize("worker") %>%
  timeout_from_attribute("duration") %>%
  release("worker")

initialization <- trajectory() %>%
  set_prioritization(consume(myData$priority, TRUE)) %>%
  set_attribute("duration", consume(myData$duration)) %>%
  join(activityTraj)

arrivals_gen <- simmer() %>%
  add_resource("worker", 2, preemptive=TRUE) %>%
  add_generator("dummy_", initialization, at(myData$time)) %>%
  run() %>%
  get_mon_arrivals()

# check the resulting duration times
activity_time <- arrivals_gen %>%
  tidyr::separate(name, c("prefix", "n"), convert=TRUE) %>%
  dplyr::arrange(n) %>%
  dplyr::pull(activity_time)

all(activity_time == myData$duration)

## [1] TRUE

Since this v3.8.0, the new data source add_dataframe greatly simplifies this process:

arrivals_df <- simmer() %>%
  add_resource("worker", 2, preemptive=TRUE) %>%
  add_dataframe("dummy_", activityTraj, myData, time="absolute") %>%
  run() %>%
  get_mon_arrivals()

identical(arrivals_gen, arrivals_df)

## [1] TRUE

On-disk monitoring

As some users noted (see 1, 2), the default in-memory monitoring capabilities can turn problematic for very long simulations. To address this issue, the simmer() constructor gains a new argument, mon, to provide different types of monitors. Monitoring is still performed in-memory by default, but as of v3.8.0, it can be offloaded to disk through monitor_delim() and monitor_csv(), which produce flat delimited files.

mon <- monitor_csv()
mon

## simmer monitor: to disk (delimited files)
## { arrivals: /tmp/RtmpAlQH2g/file6933ce99281_arrivals.csv }
## { releases: /tmp/RtmpAlQH2g/file6933ce99281_releases.csv }
## { attributes: /tmp/RtmpAlQH2g/file6933ce99281_attributes.csv }
## { resources: /tmp/RtmpAlQH2g/file6933ce99281_resources.csv }

env <- simmer(mon=mon) %>%
  add_generator("dummy", hello_sayer, function() rexp(1, 1)) %>%
  run(until=2)

## 0.26309: dummy0: hello!
## 0.982183: dummy1: hello!

env

## simmer environment: anonymous | now: 2 | next: 2.29067480322535
## { Monitor: to disk (delimited files) }
##   { arrivals: /tmp/RtmpAlQH2g/file6933ce99281_arrivals.csv }
##   { releases: /tmp/RtmpAlQH2g/file6933ce99281_releases.csv }
##   { attributes: /tmp/RtmpAlQH2g/file6933ce99281_attributes.csv }
##   { resources: /tmp/RtmpAlQH2g/file6933ce99281_resources.csv }
## { Source: dummy | monitored: 1 | n_generated: 3 }

read.csv(mon$handlers["arrivals"]) # direct access

##     name start_time  end_time activity_time finished
## 1 dummy0  0.2630904 0.2630904             0        1
## 2 dummy1  0.9821828 0.9821828             0        1

get_mon_arrivals(env)              # adds the "replication" column

##     name start_time  end_time activity_time finished replication
## 1 dummy0  0.2630904 0.2630904             0        1           1
## 2 dummy1  0.9821828 0.9821828             0        1           1

See below for a comprehensive list of changes.

New features:

• New data source add_dataframe enables the attachment of precomputed data, in the form of a data frame, to a trajectory. It can be used instead of (or along with) add_generator. The most notable advantage over the latter is that add_dataframe is able to automatically set attributes and prioritisation values per arrival based on columns of the provided data frame (#140 closing #123).
• New set_source activity deprecates set_distribution(). It works both for generators and data sources (275a09c, as part of #140).
• New monitoring interface allows for disk offloading. The simmer() constructor gains a new argument mon to provide different types of monitors. By default, monitoring is performed in-memory, as usual. Additionally, monitoring can be offloaded to disk through monitor_delim and monitor_csv, which produce flat delimited files. But more importantly, the C++ interface has been refactorised to enable the development of new monitoring backends (#146 closing #119).

Minor changes and fixes:

• Some documentation improvements (1e14ed7, 194ed05).
• New default until=Inf for the run method (3e6aae9, as part of #140).
• branch and clone now accept lists of trajectories, in the same way as join, so that there is no need to use do.call (#142).
• The argument continue (present in seize and branch) is recycled if only one value is provided but several sub-trajectories are defined (#143).
• Fix process reset: sources are reset in strict order of creation (e7d909b).
• Fix infinite timeouts (#144).