Data Collector Monitoring Functions

Each one of the Data collector monitors has the following monitoring functions:

• Initialization function is called once before a simulation starts. It returns an optional numerical value (see below for more information about optional values). If the function returns NONE then nothing will happen. If the function returns a value of the form SOME x where x is a number, then x will be used to update statistics and it will be saved in a log file (if the Logging option for the data collector monitor is checked).
• Predicate function is called after simulation steps. When the predicate function returns true, the observation and action functions are called.
• Observation function examines the monitored nodes, and returns a numerical value.
• Action function uses the numerical values that are returned by the observation function to update statistics, and the values are also saved in a log file (if the Logging option for the data collector monitor is checked).
• Stop function is analogous to the initialization function, but it is called when simulation stop criteria are met.

Accessibility of the monitoring functions for the different kinds of data collector monitors:

Generic data collector monitors

Function types for the accessible functions

• init: markings -> <numerical type> option initialization function
• pred: subnet -> bool predicate function
• obs: subnet -> <numerical type> observation function
• stop: markings -> <numerical type> option stop function

For more information about the subnet and markings data types, see Data types for monitored subnets.

For each generic data collector monitor the type <numerical type> can be one of the following:

• real
• int
• IntInf.int

The initialization and stop functions must return values of type <numerical type> option. This means that they can return the following values:

• NONE
• SOME x

where x has type <numerical type>. For more information about optional values please see the Option structure in the SML Basis Library Manual.

The <numerical type> must be the same for the observation, initialization, and stop functions in a given monitor. For example, if the observation function returns values of type int, then the stop function must return values of type int option, i.e. the stop function cannot return values of type real option.

Note that when an observation, initialization, or stop function returns integer values, the values are converted to infinite integers, i.e. IntInf.int, in order to avoid Overflow exceptions when calculating statistics.

Examples of monitoring functions

In the examples below, two different subnets of the Simple Protocol net will be considered. One subnet consists just of the place B, which is on the page Top.

Place B in the Simple Protocol

The other subnet consists of place B and its surrounding transitions on page Top.

Monitored subnet

Additional examples of data collector monitoring functions can be found in the example net for the Queue System example.

Initialization functions

The arguments for an initialization function will be the same for the two subnets described above. This is due to the fact that transitions cannot be inspected in initialization functions, and that both subnets contain the same place.

Example 1

This initialization function returns the value NONE, which means that no data value will extracted from the net by the monitor before the first step of a simulation.

fun init (Top’B_1_mark : INTxDATA ms) = NONE

Example 2

This initialization function returns a value an integer option, as indicated by SOME ... which means that a data value will be extracted from the net by the monitor before the first step of a simulation. In this case the data value is equal to the number of tokens on the place B in the initial marking. The size function is a function for multisets.

fun init (Top’B_1_mark : INTxDATA ms) =
SOME (size Top’B_1_mark)

Predicate functions

Example 1

This predicate function is for a monitor that is associated with just place B from the Simple Protocol net. The predicate function will be invoked after every step in a simulation, because the monitor is not associated with any transitions. The function will return true each time it is invoked, i.e. it will return true after every simulation step.

fun pred (Top’B_1_mark : INTxDATA ms) = true

Example 2

This predicate function is for a monitor that is associated with place B and its surrounding transitions from the Simple Protocol net.

The predicate function returns true when either of the two transitions occurs, and it does not examine the marking of the place B. This function returns true each time one of the transitions surrounding place B occurs, i.e. when the marking of place B changes.

fun pred (bindelem,
Top’B_1_mark : INTxDATA ms) =
let
fun predBindElem (Top’Receive_Packet (1, {k,n,p,str})) = true
| predBindElem (Top’Transmit_Packet (1, {n,p,r,s})) = true
| predBindElem _ = false
in
predBindElem bindelem
end

Observation functions

Example 1

This observation function is for a monitor that is associated with just place B. The function will return the number of tokens on place B each time it is invoked.

fun obs (Top’B_1_mark : INTxDATA ms) = size Top’B_1_mark

Example 2

This observation function is for a monitor that is associated with place B and its surrounding transitions. The function will also return the number of tokens on place B each time it is invoked. The function ignores the binding element argument bindelem.

fun obs (bindelem,
Top’B_1_mark : INTxDATA ms) =
let
fun obsBindElem (Top’Receive_Packet (1, {k,n,p,str})) = 0
| obsBindElem (Top’Transmit_Packet (1, {n,p,r,s})) = 0
| obsBindElem _ = ~1
in
size Top’B_1_mark
end

Example 3

This observation function is for a monitor that is associated with place B and its surrounding transitions. The observation function will be invoked when the predicate function for the monitor returns true, and it may only be invoked after the Receive_Packet or the Transmit_Packet transitions occur.

fun obs (bindelem,
Top’B_1_mark : INTxDATA ms) =
let
fun obsBindElem (Top’Receive_Packet (1, {k,n,p,str})) =
size (filter (fn (sn,data) => sn=n) Top’B_1_mark)
| obsBindElem (Top’Transmit_Packet (1, {n,p,r,s})) =
size (filter (fn (sn,data) => sn=n) Top’B_1_mark)
| obsBindElem _ = ~1
in
obsBindElem bindelem
end

If the observation function is invoked after the Receive_Packet occurs, then the observation function will return the number of tokens on place B that have a sequence number equal to the value bound to the variable n when the transition occurred. The size and filter functions are functions for multisets. The filter function takes two arguments: a predicate function and a multiset. The function will return all of the elements in the multiset which satisfy the predicate.

Consider the statement (filter (fn (sn,data) => sn=n) Top'B_1_mark). The value Top'B_1_mark will correspond to the tokens on place B, i.e. it will be a multiset of values of type INTxDATA.

The function size (fn (sn,data) => sn=n) is a predicate function that takes an argument of type INTxDATA, and it compares the first value in the pair to the value n, where n is the value that was bound to the variable n when either the transition Receive_Packet or Transmit_Packet occurred.

When the filter function is invoked, the predicate function will be applied to each element in the multiset Top'B_1_mark, i.e. to each token on place B. When the function filter applies the predicate function to the marking of place B, it will return the tokens on place B that have sequence number equal to n. The size function is then used to find out how many tokens on place B have sequence number equal to n.

Stop functions

The arguments for stop functions for the two subnets will be the same because stop functions cannot examine transitions and because the two subnets contain the same place. Stop functions are similar to initialization functions, but they are invoked when simulation stop criteria are met (rather than before the first step in a simulation).

Example 1

This stop function returns the value NONE, which means that no data value will extracted from the net by the monitor when simulation stop criteria are met.

fun stop (Top’B_1_mark : INTxDATA ms) = NONE

Example 2

This stop function returns a value an integer option, as indicated by SOME ... which means that a data value will be extracted from the net by the monitor when simulation stop criteria are met. In this case the data value is equal to the number of tokens on the place B in the final marking. The size function is a function for multisets.

fun stop (Top’B_1_mark : INTxDATA ms) =
SOME (size Top’B_1_mark)

Related pages

Monitoring functions, Data collector monitors