simmer 3.6.3

The third update of the 3.6.x release of simmer, the Discrete-Event Simulator for R, is on CRAN. First of all and once again, I must thank Duncan Garmonsway (@nacnudus) for writing a new vignette: “The Bank Tutorial: Part II”.

Among various fixes and performance improvements, this release provides a way of knowing the progress of a simulation. This feature is embed into the run() function as a parameter called progress, which accepts a function with a single argument and will be called for each one of the steps (10 by default) with the current progress ratio (a number between 0 and 1). A very naive example using a simple print():

library(simmer)

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

simmer() %>%
  add_generator("dummy", wait_and_go, function() 1) %>%
  run(until=10, progress=print, steps=5)
## [1] 0
## [1] 0.2
## [1] 0.4
## [1] 0.6
## [1] 0.8
## [1] 1
## simmer environment: anonymous | now: 10 | next: 10
## { Generator: dummy | monitored: 1 | n_generated: 10 }

Or we can get a nice progress bar with the assistance of the progress package:

simmer() %>%
  add_generator("dummy", wait_and_go, function() 1) %>%
  run(until=1e5, progress=progress::progress_bar$new()$update)
#> [==============---------------------------------------------------------]  20%

But more importantly, this release implements a new way of retrieving attributes (thus deprecating the old approach, which will be still available throughout the 3.6.x series and will be removed in version 3.7). Since v3.1.x, arrival attributes were retrieved by providing a function with one argument. A very simple example:

trajectory() %>%
  set_attribute("delay", 3) %>%
  timeout(function(attr) attr["delay"])
## Warning: Attribute retrieval through function arguments is deprecated.
## Use 'get_attribute' instead.
## trajectory: anonymous, 2 activities
## { Activity: SetAttribute | key: delay, value: 3, global: 0 }
## { Activity: Timeout      | delay: 0x5569098b9228 }

Later on, v3.5.1 added support for global attributes, making it necessary to add a second argument to retrieve this new set of attributes:

trajectory() %>%
  set_attribute("delay", 3, global=TRUE) %>%
  timeout(function(attr, glb) glb["delay"])
## Warning: Attribute retrieval through function arguments is deprecated.
## Use 'get_attribute' instead.
## trajectory: anonymous, 2 activities
## { Activity: SetAttribute | key: delay, value: 3, global: 1 }
## { Activity: Timeout      | delay: 0x556908730320 }

This method is a kind of rarity in simmer. It’s clunky, as it is not easy to document (and therefore to discover and learn), and non-scalable, because new features would require more and more additional arguments. Thus, it is now deprecated, and the get_attribute() function becomes the new method for retrieving attributes. It works in the same way as now() for the simulation time:

env <- simmer()

trajectory() %>%
  set_attribute("delay_1", 3) %>%
  # shortcut equivalent to set_attribute(..., global=TRUE)
  set_global("delay_2", 2) %>% 
  timeout(function() get_attribute(env, "delay_1")) %>%
  # shortcut equivalent to get_attribute(..., global=TRUE)
  timeout(function() get_global(env, "delay_2"))
## trajectory: anonymous, 4 activities
## { Activity: SetAttribute | key: delay_1, value: 3, global: 0 }
## { Activity: SetAttribute | key: delay_2, value: 2, global: 1 }
## { Activity: Timeout      | delay: 0x55690829f550 }
## { Activity: Timeout      | delay: 0x55690830c310 }

This is a little bit more verbose, but I believe it is more consistent and intuitive. Moreover, it allows us to easily implement new features for extracting arrival information. In fact, get_attribute() will come hand in hand with two more verbs: get_name() and get_prioritization(), to retrieve the arrival name and prioritization values respectively.

New features:

• Show simulation progress via an optional progress callback in run() (#103).
• New “The Bank Tutorial: Part II” vignette, by Duncan Garmonsway @nacnudus (#106).
• New getters for running arrivals (#109), meant to be used inside trajectories:
  • get_name() retrieves the arrival name.
  • get_attribute() retrieves an attribute by name. The old method of retrieving them by providing a function with one argument is deprecated in favour of get_attribute(), and will be removed in version 3.7.x.
  • get_prioritization() retrieves the three prioritization values (priority, preemptible, restart) of the active arrival.
• New shortcuts for global attributes (#110): set_global() and get_global(), equivalent to set_attribute(global=TRUE) and get_attribute(global=TRUE) respectively.

Minor changes and fixes:

• Some code refactoring and performance improvements (2f4b484, ffafe1e, f16912a, fb7941b, 2783cd8).
• Use Rcpp::DataFrame instead of Rcpp::List (#104).
• Improve argument parsing and error messages (#107).
• Improve internal function make_resetable() (c596f73).