Package Overview
The Stat (Statistic) package contains Kernel Procedures that provide mechanisms for writing user-defined and automatically-computed statistics to the output data files created during simulations.
Simulation output is stored in output vector (.ov) files. These files contain two kinds of statistics:
- Vector statistics—dynamic, event-oriented metrics that trace a statistic over time; each data point has an associated time at which it was logged.
- Scalar statistics—non-dynamic performance metrics of the simulated system, such as averages, variances, or extrema of statistics. A scalar is stored as a single value that is associated with a scalar name.
A vector file can contain data from one simulation run only. A simulation cannot add new data to a previously-constructed output vector file.
All node modules, except antennas, compute built-in statistics automatically. These statistics can be routed by statistic wires to affect processes or they can be probed so that their changing values appear in output vector files. In addition to having built-in statistics, the queue and processor modules also support user-defined output statistics. This allows a process to compute individually named statistics using any metric or algorithm and log their values separately over time.
Because output statistics are stored on a per-module basis, they are useful for local observations of statistics within a module. Another type of statistic—global statistic—is not associated with a specific module and is accessible to all processes in the simulation. Global statistics can be used to observe general network behavior, such as the measured delays of all packets traversing the network, regardless of the source or destination.
For convenience, both local and global statistics are referenced by alphanumeric names.
The Stat package provides two ways to add supplemental information to statistics: annotations and tags.
- An annotation appends a label to a statistic name in the output vector file. Use the KP op_stat_annotate() to add an annotation.
- A statistic tag associates a name:value pair with a statistic. Tags give additional details about a statistic and permit more convenient access to simulation results by allowing related statistics to be grouped in the Results Browser. Use the KPs op_stat_tag_add_str(), op_stat_tag_add_int32(), op_stat_tag_add_int64(), and op_stat_tag_add_dbl() to add tags to a statistic.
The KP op_stat_rename() is used to rename a statistic in the output vector file.
The KP op_stat_reg() is used to convert designated names into statistic handles that can be used by other KPs to write into the local or global statistics of a process.
The KP op_stat_obj_reg() is similar to op_stat_reg(), but does not require processor context and can be used to access an arbitrary link, path, module, or submodule local statistic.
The KP op_stat_valid() is used to verify that a statistic handle is valid (that is, that it has been registered). With dimensioned statistics, you might need to have invalid statistic handles for unregistered statistics. You can manage this with op_stat_invalid_get() and op_stat_invalid_set().
The KP op_stat_dim_size_get() is used to read the dimension array value of a process local or global statistic.
The KP op_stat_obj_dim_size_get() is similar to op_stat_dim_size_get(), but can access local statistics in things other than process models, such as paths, links, and demands.
The KP op_stat_write() logs a value associated with the current time into the specified statistic.
The variant KP op_stat_write_t() logs a value associated with a specified time.
Scalar statistics can be logged anytime during a simulation. There is only one value per scalar statistic, which represents the whole simulation; a scalar value is not associated with a specific time. The KPs op_stat_scalar_write() and op_stat_scalar_write_symbol() automatically log a scalar value to a vector output file, so a probe does not need to be specified using the Probe Editor.
In addition to output statistics, processor and queue modules also support input statistics, which are the destination points of statistic wires. Input statistics provide the capability of using statistic wires as a form of interprocess communication. The KP op_stat_local_read() returns the current value of the specified statistic wire.