User Guide: C++ : Qtables

12. Qtables

A qtable is used to gather statistics on an integer-valued function of time, such as the length of a queue, the population of a subsystem, or the number of available resources. Every change in the value of the function must be "noted" by calling a CSIM function. A qtable does not actually save the functional values; it simply updates the statistics each time the value changes. (See section 12.6 for the only exception to this rule.)
A qtable is also used to gather statistics on a real-valued (double) function of time. Every change in the value of the function is noted by calling a CSIM function. A qtable for real-valued entries is a qtable object; values of the function are entered using the record_value() method.

The statistics maintained by a qtable include the minimum, maximum, range, mean, variance, standard deviation, and coefficient of variation. The number of changes in the functional value is maintained, as well as the initial and final values. Optional features for a qtable allow the creation of a histogram, the calculation of confidence intervals, and the computation of statistics for values in a moving window.

First-time users of qtables should focus on the following three sections, which explain how to set up qtables, note changes in their values, and produce reports. Subsequent sections describe the more advanced features of qtables.

12.1. Declaring and Initializing a Qtable

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

Dynamic Example: qtable *qtd;

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

Prototype: qtable::qtable(char *name)
Static Example: qtable qts("queue length");
Dynamic Example: qtd = new qtable("queue length");

The qtable name is used only to identify the qtable in the output reports. Up to 80 characters in the name will be stored by CSIM. A newly created qtable has an initial value of zero. To create a qtable with a non-zero initial value, call the note_state method (described below) immediately after creating the qtable.

A qtable can be initialized as a permanent qtable using the permanent_qtable class.

Prototype: permanent_qtable::permanent_qtable(char *name)
Dynamic Example: qtd = new permanent_qtable("queue
length");

12.2. Noting a Change in Value

The most common way for the value of a qtable to change is for it to increase or decrease by one. Such a change would occur when a customer joins a queue or a resource is allocated. The value of a qtable is increased by one using the note_entry method.

Prototype: void qtable::note_entry(void)
Dynamic Example: qtd -> note_entry();

The value of a qtable is decreased by one using the note_exit method.

Prototype: void qtable::note_exit(void)
Dynamic Example: qtd->note_exit();

The value of a qtable can be changed to an arbitrary number using the note_value method.

Prototype: void qtable::note_value(long value)
Example: qtd->note_value(12);

The value of a qtable can be changed to an arbitrary floating (double) number using the record_value method.

Prototype: void qtable::record_value(double value)
Example: qtd->note_value(1.75);

The value of a qtable can be initialized to an arbitrary floating (double) number using the set_initial_value method.

Prototype: void qtable::set_initial_value(double value)
Example: qtd->set_initial_value(-1.0);

Note: using the record_value() method and the note methods on the same qtable is incorrect.

12.3. Producing Reports

Reports for qtables 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 qtable at any time by calling the report_qtable method.

Prototype: void qtable::report(void)
Dynamic Example: qtd->report();

Reports can be produced for all existing qtables by calling the report_qtables function.

Prototype: void report_qtables(void)
Example: report_qtables();

The report for a qtable will include the qtable name and all statistics, as illustrated below. If no time has passed since the creation or reset of the qtable, a message to that effect is printed instead of the statistics.

A summary report for all qtables can be generated by calling the qtable_summary function.

Prototype: void qtable_summary (void)
Example: qtable_summary ();

The report that is produced contains one line for each qtable and includes only a subset of the statistics. If no time has passed, no statistics will appear in the last three columns.

Note: the report and histogram for a qtable with floating values are similar to reports for a qtable with integer values, except that double values are printed where appropriate.

12.4. Histograms

A histogram can be specified for a qtable in order to obtain more detailed information about the functional values. Depending on how the qtable is being used, its histogram might give the distribution of the queue lengths, the subsystem population, or the number of available resources. A histogram is specified for a table by calling the add_histogram method.

Prototype: void qtable::add_histogram(long
nbucket, long min, long max)
Example: qtd->add_histogram(11, 0, 10);

The number of buckets in the histogram will be (no greater than) nbucket. The smallest value in the first bucket will be min; the largest value in the last bucket will be max. All buckets will have the same width, which will be rounded up to an integer if necessary. An underflow bucket and an overflow bucket will automatically be created if needed to hold values less than min or greater than max.

Caution: The min and max parameters of qtable_histogram are of type long, whereas the analogous parameters of table_histogram are of type double.

Usually, a histogram is specified for a qtable immediately after the qtable is initialized. Additional calls can be made to qtable_histogram to change the characteristics of the histogram, but only if the qtable is empty.

A report for a qtable having a histogram will include an additional section as illustrated below. For each bucket in the histogram, the following information will be displayed: the smallest value the bucket can hold, the total time the functional value was in the bucket, the proportion of time that the functional value was in the bucket, the proportion of all functional values in the bucket and all preceding buckets, and a bar whose length corresponds to the proportion of time the functional value was in the bucket.

If leading or trailing buckets contain no values, the lines in the report for these buckets will not be printed. This allows the histogram to be output as compactly as possible without losing any information.

CSIM must save information for each bucket in a histogram.

onsequently, the storage requirements for a qtable that has a histogram are proportional to the number of buckets.

12.5. Confidence Intervals

CSIM can automatically compute confidence intervals for the mean value of any qtable. The confidence interval calculations are enabled by calling the confidence method.

Prototype: void qtable::confidence(void)
Dynamic Example: qtd->confidence();

If confidence intervals have been requested, the report for a qtable will include an additional section, as illustrated below.

Section 16.1, "Confidence Intervals", describes confidence intervals in detail and explains how to interpret the information in this report.

12.6. Moving Windows

By default, all changes to the value of a qtable are included in the statistics. If a moving window is specified for a qtable, only the last n changes are used in computing the statistics, where n is called the window size. A moving window is specified for a qtable using the moving_window method.

Prototype: void qtable::moving_window(long n)
Dynamic Example: qtd->moving_window (1000);

Usually, a qtable's moving window is specified immediately after the qtable is initialized. Additional calls can be made to qtable_moving_window to change the qtable's window size. It is an error to specify a moving window for a qtable that is not empty.

If a qtable has a window size of n, the last n changes noted for the qtable must be saved by CSIM. Consequently, the storage requirements for a qtable having a moving window are proportional to its window size.

Note: In an alternate implementation of moving windows, the window size would be specified as an amount of time. The storage requirements of such an implementation would be non-constant and potentially prohibitive.

12.7. Inspector Methods

All statistics maintained by a qtable can be retrieved during the execution of a model or upon its completion. The attributes of a qtable (i.e., its name and moving window size) can also be retrieved.

When a qtable has recorded double values, the following inspector methods should be used (instead of the equivalent methods used listed above)

The following inspector methods retrieve information about the confidence interval associated with a table:

The following inspector methods retrieve information about the run length control associated with a table:

Many statistics are mathematically undefined if zero time has passed since the creation or reset of a qtable. The corresponding inspector methods return a value of zero in this case.

The following inspector methods retrieve information about the histogram associated with a qtable.

The number of buckets in a histogram does not include the underflow or overflow buckets. Bucket number 0 is the underflow bucket; bucket number 1+histogram_num( ) is the overflow bucket. If a histogram has not been specified for a qtable, the above inspector methods all return zero values.

The inspector methods that retrieve information about the results of run-length control are described in section 16.3, "Run Length Control".

12.8. Renaming a Qtable

The name of a qtable can be changed at any time using the set_name method.

Prototype: void qtable::set_name(char *new_name)
Dynamic Example: qtd-> set_name ("number in queue");

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

12.9. Resetting a Qtable

Resetting a qtable causes all information maintained by the qtable to be reinitialized, except that the current value is saved for use in computing future values. All optional features selected for the qtable (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 qtable can be reset using the reset method.

Prototype: void qtable::reset(void)
Example: qtd->reset_qtable ();

Although permanent qtables are not reset by the reset function, they can be reset explicitly by calling reset_qtable.

12.10. Deleting a Qtable

When a dynamic qtable is no longer needed, its storage can be reclaimed as follows:

Example: delete qtd;

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

Next Section