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:
- Periodically examine some markings and/or occurring transitions
- Check to see if a particular condition is fulfilled
- If the condition is fulfilled then
- Possibly extract some information from the markings and/or binding element
- Do something relevant (with the corresponding data if necessary)
- If the condition is not fulfilled, then do nothing
Example of monitor functionality
Let us consider an example of a write-in-file monitor for the example net of the Simple Protocol. 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.
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
During a simulation, the file should be updated only when either the
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.
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.
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.
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.
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,
p. When the
Transmit_Packet transition occurs, the monitor can access the bindings of the variables
r. When either of these transitions occurs, the monitor can also examine the marking of place
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.
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.
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.
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.
The predicate function, shown in a binder below, determines when the file should be updated during a simulation. It returns
true when either the
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
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:
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.
The stop function determines the string that should be added to the file when simulation stop criteria are met.
When a simulation is run, a file similar to the one below will be created by the monitor.
Help topics for monitors
- Create a monitor
- Data types for monitored subnets
- Edit a monitor
- Errors in monitors
- Monitoring functions
- Monitor template code
- Breakpoint monitors
- Breakpoint monitoring functions
- Data collector monitors
- Data Collector Monitoring Functions
- User-defined monitors
- User-defined monitoring functions
- Write-in-file monitors
- Write-in-file monitoring functions
- Monitor index entries
- Known limitations of monitors