Create a Monitor — monitor • simmer

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

name: an identifier to show when printed.
xptr: an external pointer pointing to a C++ object derived from the abstract class simmer::Monitor. See C++ API for further details and, in particular, the simmer/monitor.h header.
get_arrivals: a function to retrieve the arrivals tables. It must accept the xptr as a first argument, even if it is not needed, and a boolean per_resource as a second argument (see get_mon_arrivals).
get_attributes: a function to retrieve the attributes table. It must accept the xptr as a first argument, even if it is not needed.
get_resources: a function to retrieve the resources table. It must accept the xptr as a first argument, even if it is not needed.
handlers: an optional list of handlers that will be stored in a slot of the same name. For example, monitor_mem does not use this slot, but monitor_delim and monitor_csv store the path to the created files.
finalizer: an optional one-argument function to be called when the object is destroyed. For example, monitor_mem does not require any finalizer, but monitor_delim and monitor_csv use this to remove the created files when the monitor is destroyed.
path: directory where files will be created (must exist).
keep: whether to keep files on exit. By default, files are removed.
sep: separator character.
ext: file extension to use.
reader: function that will be used to read the files.
args: a list of further arguments for reader.

Value

A monitor object.

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".

Examples

mon <- monitor_csv()
mon
#> simmer monitor: to disk (delimited files)
#> { arrivals: /tmp/RtmpLoWAIb/file2557a3a5f926c_arrivals.csv }
#> { releases: /tmp/RtmpLoWAIb/file2557a3a5f926c_releases.csv }
#> { attributes: /tmp/RtmpLoWAIb/file2557a3a5f926c_attributes.csv }
#> { resources: /tmp/RtmpLoWAIb/file2557a3a5f926c_resources.csv }

env <- simmer(mon=mon) %>%
  add_generator("dummy", trajectory() %>% timeout(1), function() 1) %>%
  run(10)
env
#> simmer environment: anonymous | now: 10 | next: 10
#> { Monitor: to disk (delimited files) }
#>   { arrivals: /tmp/RtmpLoWAIb/file2557a3a5f926c_arrivals.csv }
#>   { releases: /tmp/RtmpLoWAIb/file2557a3a5f926c_releases.csv }
#>   { attributes: /tmp/RtmpLoWAIb/file2557a3a5f926c_attributes.csv }
#>   { resources: /tmp/RtmpLoWAIb/file2557a3a5f926c_resources.csv }
#> { Source: dummy | monitored: 1 | n_generated: 10 }

read.csv(mon$handlers$arrivals) # direct access
#>     name start_time end_time activity_time finished
#> 1 dummy0          1        2             1        1
#> 2 dummy1          2        3             1        1
#> 3 dummy2          3        4             1        1
#> 4 dummy3          4        5             1        1
#> 5 dummy4          5        6             1        1
#> 6 dummy5          6        7             1        1
#> 7 dummy6          7        8             1        1
#> 8 dummy7          8        9             1        1
get_mon_arrivals(env)           # adds the "replication" column
#>     name start_time end_time activity_time finished replication
#> 1 dummy0          1        2             1        1           1
#> 2 dummy1          2        3             1        1           1
#> 3 dummy2          3        4             1        1           1
#> 4 dummy3          4        5             1        1           1
#> 5 dummy4          5        6             1        1           1
#> 6 dummy5          6        7             1        1           1
#> 7 dummy6          7        8             1        1           1
#> 8 dummy7          8        9             1        1           1