Monitors

What is a monitor?

When simulating CP-nets, it is often useful to be able to examine the markings and occurring binding elements, to periodically extract information from the markings and binding elements, and then to use the information for different purposes, such as:

  • Stopping a simulation when a particular place is empty
  • Counting the number of times a transition occurs
  • Updating a file when a transition occurs with a variable bound to a specific value
  • Calculating the average number of tokens on a place

Even though the extracted information may be used for different purposes, the way the information is extracted is often very similar.

A monitor is a mechanism in CPN Tools that is used to observe, inspect, control, or modify a simulation of a CP-net. Many different monitors can be defined for a given net. Monitors can inspect both the markings of places and the occurring binding elements during a simulation, and they can take appropriate actions based on the observations. Monitors can be used for each of the activities mentioned above.

An example of a monitor is introduced in the following sections.

Kinds of monitors

There is support for the following kinds of monitors:

Breakpoint monitors
are used to stop a simulation.
Data collector monitors
are used to extract numerical data from a net. The numerical data is then used to calculate statistics, and the data can be saved in log files. The log files can then be post-processed, e.g. by importing them into spreadsheet programs or plotting them in graphs.
Write-in-file monitors
are used to update files during simulations.
User-defined monitors
are generic monitors that can be used for any purposes that are not covered by the other kinds of monitors. For example, a user-defined monitor could be used to update a message sequence chart (MSC) or to check that a particular property holds during the simulation.

Functionality of a monitor

All monitors share the following common functionality:

  1. Periodically examine some markings and/or occurring transitions
  2. Check to see if a particular condition is fulfilled
  3. If the condition is fulfilled then
  4. Possibly extract some information from the markings and/or binding element
  5. Do something relevant (with the corresponding data if necessary)
  6. If the condition is not fulfilled, then do nothing
  7. Repeat

Example of monitor functionality

Let us consider an example of a write-in-file monitor for the example net of the Simple protocol example. This monitor should update a file with information about the tokens that are on the place A. Some information should be added to the file once before the simulation starts, the file should be updated periodically during a simulation, and some additional information should be added to the file when a simulation stops because Simulation stop criteria have been met.

Simple Protocol

Before a simulation starts some information, such as the name of the net and something about the initial marking of place A, should be added to the file.

This monitor should examine and extract information from the place A in order to update the file during a simulation. How often should the monitor update the file? For example, should it be after every step, or only when the marking of place A changes? In this example, the monitor will update the file only when the marking of place A changes. This means that the monitor will also have to observe the transitions that change the marking of place A, i.e. the transitions Send_Packet and Transmit_Packet.

During a simulation, the file should be updated only when either the Send_Packet or Transmit_Packet transition occurs. This means that the monitor will have to check whether one of these transitions has occurred.

If one of these transitions has occurred, then the file must be updated. In this case, the marking of place A must be examined, and a string with relevant information about the marking of the place must be generated. This is the information that is extracted from the net. The string must then be added to the file.

When a transition that is not a neighbor of place A occurs, then the file does not need to be updated, and nothing else needs to be done.

Finally, when Simulation stop criteria have been met, some additional information, such as the number of steps executed in the simulation, should be added to the file.

Monitoring subnets

Each monitor is associated with a relevant set of places and transitions from a net. This is the subnet that the monitor can examine and extract information from during a simulation. Each monitor can be associated with

  • Zero or more places and
  • Zero or more transitions

This means that a monitor can be associated with no nodes in the net, all nodes in the net, or any relevant subset of the nodes in the net.

Monitoring transitions

If a monitor is associated with one or more transitions, then the monitor can check if the relevant condition is fulfilled after any one of the transitions occurs. If the relevant condition is fulfilled, and then the monitor will take appropriate actions, e.g. extracting information from the subnet, and doing something relevant with the information.

When a transition that is not associated with a particular monitor occurs, that monitor will not have any access to the information regarding the transition, and the monitor will not be able to check if the relevant condition is fulfilled.

For each transition that is associated with a monitor, the monitor will be able to determine which transition occurred in a simulation step, and it will also be able to examine the bindings of all of the variables on the arcs surrounding the transition.

If a monitor is associated with zero transitions, then the monitor will be able to check if the relevant condition is fulfilled after every simulation step. However, such a monitor will not be able to access any information about the transitions that occur during a simulation.

Monitoring places

If a monitor is associated with one or more places, then the monitor can examine the tokens on each of the places. The monitor can examine the markings of the places before a simulation starts, during a simulation, and when a simulation stops. A marking of a place is a multi-set of values from the color set of the place.

If the monitor is associated with at least one transition, then the monitor can examine the tokens on the places only when one of the associated transitions occurs during a simulation. If the monitor is associated with zero transitions, then the monitor can examine the tokens on the places after every simulation step.

Example of a monitored subnet

In the example, the write-in-file monitor would be associated with one place and two transitions. The monitor does not need to examine any of the other transitions or places in the net. Below is a group containing the relevant subnet for the write-in-file monitor.

Monitored subnet

When either the Send_Packet or the Transmit_Packet transition occurs, then the monitor can check to see if the relevant condition is fulfilled. If the Send_Packet transition occurs, then the monitor will be able to access the bindings of the variables, n and p. When the Transmit_Packet transition occurs, the monitor can access the bindings of the variables n, p, s and r. When either of these transitions occurs, the monitor can also examine the marking of place A.

Before a simulation starts, the monitor can examine the marking of the place A, but it cannot examine any transitions. Similarly, after a simulation stops, the monitor can again examine the marking of A, but it cannot examine any transitions.

Monitoring functions

Each monitor has a number of different functions that are used for different purposes. Some examples of functions for monitors are:

predicate function
for checking if the relevant condition is fulfilled
observation function
for extracting information from the net
action function
for doing something relevant with the extracted data
initialization function
for initializing a monitor before a simulation starts
stop function
for concluding a monitor when a simulation ends

These functions are collectively referred to as Monitoring functions. Some kinds of monitors will have one of each of these functions, and some monitors will only have a subset of these functions. For example, a write-in-file monitor has all of these functions. However, a breakpoint monitor does not have an observation function because it is not necessary to extract information from the net. For a breakpoint monitor the predicate function will determine when a simulation should stop, and the action function will take the necessary steps to tell the simulator that the simulation should stop.

Visibility of monitoring functions

For some kinds of monitors, the monitoring functions are completely hidden from users, and for other kinds of monitors some or all monitoring functions are visible for users. If a monitoring function is visible for a user, then the user may modify it to obtain the desired behavior.

For example, for a Marking Size monitor, all monitoring functions are hidden, but for a Write-in-file monitor almost all monitoring functions are visible (and modifiable) for the user.

When a monitoring function is accessible, the user is not required to write the function from scratch. When the monitor is created, Monitor template code will be generated for the accessible functions, and the user can then modify the template code.

Examples of monitoring functions

The visible functions (and other information) that are associated with a particular monitor are shown in Monitor index entries.

Index entry for Write-in-file monitor

The visible functions can be viewed and edited either in the index or they can be dragged to declaration sheets in binders.

The initialization function determines the string that is added to the file before the first step of the simulation. Here the initialization function is shown in the index.

Monitoring function in index

The predicate function, shown in a binder below, determines when the file should be updated during a simulation. It returns true when either the Send_Packet or Transmit_Packet transition occurs. In other words, the predicate function returns true whenever tokens are added or removed from place A, i.e. whenever the marking of place A changes.

Monitoring functions in binder

The observation function extracts information from the net. In this case, the observation function must return the string that will be added to the file whenever the predicate function returns true. This is what the template code for the observation function looks like:

Template code for observation function

The template code is syntactically correct, but it is not very interesting because it will always return the empty string. The template code must be modified so that it will return a string with the desired information. The following observation function will return a string containing the current step number together with information about the number of tokens on place A and information about the packet number of the token that was added or removed from the place.

Observation function

The stop function determines the string that should be added to the file when Simulation stop criteria are met.

Stop function in the index

When a simulation is run, a file similar to the one below will be created by the monitor.

File created by write-in-file monitor

Help topics for monitors

Example nets with monitors