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.
A meter is declared in a CSIM program
using the built-in type METER.
Example: METER m;
Before a meter can be used, it must
be initialized by calling the meter
function.
Prototype:
METER meter(char*
name)
Example:
m = 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.
An entity notes its passage by a meter
using the note_passage
function.
Prototype:
void note_passage(METER
m)
Example:
note_passage(m);
For the statistics to be accurate, every
entity of interest must note its passage
and do so at the correct time.
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_meter
function.
Prototype:
void report_meter(METER
m)
Example:
report_meter(m);
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.
A histogram can be specified for the
interpassage times of a meter. This
is accomplished using the meter_histogram
function.
Prototype:
void meter_histogram(METER m, long nbucket,
double min, double max)
Example:
meter_histogram(m,
10, 0.0, 10.0);
The histogram for a meter is exactly
the same as the histogram for a table.
See section 9.4, "Histograms",
for details.
CSIM can automatically compute confidence
intervals for the mean interpassage
time at a meter. The confidence interval
calculations are enabled by calling
the meter_confidence
function.
Prototype:
void meter_confidence(METER
m)
Example:
meter_confidence(m);
The confidence intervals for a meter
are the same as the confidence intervals
for a table. See
section 11.5, "Confidence Intervals",
for details.
Moving windows are not supported by
meters.
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.
| Prototype: |
Functional
Value: |
| char* meter_name
(METER m) |
pointer to name
of meter |
| double meter_start_time
(METER m) |
time at which
recording began |
| long meter_cnt
(METER m) |
number of passages
noted |
| double meter_rate
(METER m) |
rate of passages |
| TABLE meter_ip_table
(METER m) |
pointer to interpassage
time table |
Although the passage rate is mathematically
undefined if no time has passed, the
meter_rate
function 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 = table_max(meter_ip_table(m));
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 set_name_meter(METER
m, char *new_name)
Example: set_name_meter(m,
"system departures");
Only the first 80 characters of the meter's
name are stored.
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 reset_meter(METER
m)
Example:
reset_meter(m);
When a meter is no longer needed, its
storage can be reclaimed using the
delete_meter
function.
Prototype:
void delete_meter(METER
m)
Example:
delete_meter(m);
Once a meter has been deleted, it must
not be further referenced.
