User Guide: C++ : Meters

13. Meters

A meter is used to gather statistics on the flow of entities such as customers or resources past a specific point in a model. Meters can be used to measure arrival rates, completion rates, and allocation rates. A meter can be thought of as a probe that is inserted at some point in a model.

While a meter primarily measures the rate at which entities flow past it, a meter also keeps statistics on the times between passages. These interpassage times are recorded in a table, which is an integral part of every meter.

First-time users of meters should focus on the following three sections, which explain how to set up meters, update meters, and produce reports. Subsequent sections describe the more advanced features of meters.

13.1. Declaring and Initializing a Meter

A pointer to a dynamic meter is declared in a CSIM program as follows:

Dynamic Example: meter *md;

Before a meter can be used, it must be initialized by invoking the meter constructor.

Prototype: meter::meter(char *name)
Static Example: meter ms("system completions");
Dynamic Example: md = new meter("system completions");

The meter name is used only to identify the meter in the output reports. Up to 80 characters in the name will be stored by CSIM.

13.2. Instrumenting a Model

An entity notes its passage by a meter using the note_passage method.

Prototype: void meter::note_passage(void)
Dynamic Example: md-> note_passage();

For the statistics to be accurate, every entity of interest must note its passage and do so at the correct time.

13.3. Producing Reports

Reports for meters are most often produced by calling the report function, which prints reports for all statistics gathering objects. A report can be generated for a specified meter at any time by calling the report method.

Prototype: void meter::report(void)
Example: md->report();

Reports can be produced for all existing meters by calling the report_meters function.

Prototype: void report_meters(void)
Example: report_meters();

The report for a meter, as illustrated below, will include the meter name, the number of passages, the passage rate, and statistics on the interpassage times. If no time has elapsed, a message to that effect is printed instead of the statistics.

A summary report for all meters can be generated by calling the meter_summary function.

Prototype: void meter_summary(void)
Example: meter_summary();

The report that is produced contains one line for each meter and includes only a subset of the statistics. If no time has passed, undefined statistics will be omitted.

13.4. Histograms

A histogram can be specified for the interpassage times of a meter. This is accomplished using the add_histogram method.

Prototype: void meter::add_histogram(long nbucket,
double min, double max)
Dynamic Example: md -> add_histogram(10, 0.0, 10.0);

The histogram for a meter is exactly the same as the histogram for a table. See section 11.4, "Histograms", for details.

13.5. Confidence Intervals

CSIM can automatically compute confidence intervals for the mean interpassage time at a meter. The confidence interval calculations are enabled by calling the confidence method.

Prototype: void meter::confidence(void)
Dynamic Example: md -> confidence();

The confidence intervals for a meter are the same as the confidence intervals for a table. See section 16.1, "Confidence Intervals", for details.

13.6. Moving Windows

Moving windows are not supported by meters.

13.7. Inspector Methods

All statistics maintained by a meter can be retrieved during the execution of a model or upon its completion. The name of a meter can also be retrieved.

Although the passage rate is mathematically undefined if no time has passed, the rate method returns the value zero in this case.

The pointer to a meter's interpassage time table can be passed to the inspector functions for a table in order to obtain interpassage time statistics.

Example: max_ip_time = m->ip_table()->max();

If no passages have occurred, the interpassage time table is empty. The interpassage time contributed by the first passage is the time from the beginning of the observation period to that first passage.

13.8. Renaming a Meter

The name of a meter can be changed at any time using the set_name_meter function.

Prototype: void meter::set_name(char *new_name)
Dynamic Example: md -> set_name("system departures");

Only the first 80 characters of the meter's name are stored.

13.9. Resetting a Meter

Resetting a meter causes all information maintained by the meter to be reinitialized, except that the time of the last passage is saved for use in computing the next interpassage time. All optional features selected for the meter (e.g., histogram, confidence intervals, moving window) remain in effect and are also reinitialized.

The reset function is usually used to reset all statistics gathering tools at once. A specific meter can be reset using the reset_meter function.

Prototype: void meter::reset(void)
Dynamic Example: md->reset();

13.10. Deleting a Meter

When a dynamic meter is no longer needed, its storage can be reclaimed using the delete_meter function.

Example: delete md;

Once a meter has been deleted, it must not be further referenced.

Next Section