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_dbl is 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_dbl is a qtable structure;
values of the function are entered using
the record_value() procedure. A qtable
becomes a qtable_dbl when a double value
is recorded in it (using the record_value()
function).
The statistics maintained by a qtable
and a qtable_dbl 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.
A qtable is declared in a CSIM program
using the built-in type QTABLE.
Example:
QTABLE qt;
Before a qtable can be used, it must
be initialized by calling the qtable
function.
Prototype:
QTABLE qtable(char* name)
Example:
qt = 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
function (described below) immediately
after creating the qtable.
A qtable can be initialized as a permanent
qtable using the permanent_qtable
function.
Prototype:
QTABLE permanent_qtable(char*
name)
Example:
qt = permanent-qtable("queue length");
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
function.
Prototype:
void note_entry(QTABLE
qt)
Example:
note_entry(qt);
The value of a qtable is decreased by
one using the note_exit
function.
Prototype:
void note_exit(QTABLE
qt)
Example:
note_exit(qt);
The value of a qtable can be changed
to an arbitrary integer-valued number
using the note_value
function.
Prototype:
void note_value(QTABLE
qt, long value)
Example:
note_value(qt,
12);
The value of a qtable_dbl can be changed
to an arbitrary floating (double) number
using the record_value
function.
Prototype:
void record_value
(QTABLE qt, double fvalue)
Example:
record_value(qt,
1.75);
The value of a qtable_dbl can be initialized
to an arbitrary floating (double) number
using the set_initial_value
function.
Prototype:
void set_initial_value(QTABLE
qt,
double fvalue)
Example:
set_initial_value(qt,
-1.0);
Note:
a qtable becomes a qtable_dbl when a
record_value() or a set_initial_value()
operation is executed. Using note_value
and record_value
operations on the same qtable is incorrect.
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
function.
void report_qtable(QTABLE
qt)
report_qtable(qt);
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_dbl
are similar to the reports for a qtable,
except that double values are printed
where appropiate.
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 qtable_histogram
function.
Prototype:
void qtable_histogram(QTABLE
qt, long
nbucket, long min, long max)
Example:
qtable_histogram(qt,
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. Consequently,
the storage requirements for a qtable
that has a histogram are proportional
to the number of buckets.
CSIM can automatically compute confidence
intervals for the mean value of any
qtable. The confidence interval calculations
are enabled by calling the qtable_confidence
function.
Prototype:
void qtable_confidence(QTABLE
qt)
Example:
qtable_confidence(qt);
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.
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 qtable_moving_window
function.
Prototype:
void qtable_moving_window(QTABLE
qt, long n)
Example:
qtable_moving_window(qt,
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.
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.
| Prototype: |
Functional
value: |
| char* qtable_name(QTABLE
qt) |
pointer to name
of qtable |
| long qtable_window_size(QTABLE
qt) |
moving window size |
| long qtable_entries(QTABLE
qt) |
number of note_entry's |
| long qtable_exits(QTABLE
qt) |
number of note_exit's |
| long qtable_min(QTABLE
qt) |
minimum value |
| long qtable_max(QTABLE
qt) |
maximum value |
| long qtable_range(QTABLE
qt) |
range of values |
| long qtable_initial(QTABLE
qt) |
initial value |
| long qtable_current(QTABLE
qt) |
current value |
| double qtable_sum(QTABLE
qt) |
sum of values
weighted by time |
| double qtable_sum_square(QTABLE
qt) |
sum of squared
weighted |
| double qtable_mean(QTABLE
qt) |
mean value |
| double qtable_var(QTABLE
qt) |
variance of values |
| double qtable_stddev(QTABLE
qt) |
standard deviation
of values |
| double qtable_cv(QTABLE
qt) |
coefficient of
variation of values |
When a qtable has recorded double values,
the following inspector functions should
be used (instead of the equivalent functions
listed above):
| Prototype: |
Functional
value: |
| double qtable_entries(QTABLE
qt) |
sum of positive
changes |
| double qtable_dbl_exits(QTABLE
qt) |
sum of negative
changes |
| double qtable_dbl_range(QTABLE
qt) |
range of values |
| double qtable_dbl_min(QTABLE
qt) |
minimum value |
| double qtable_dbl_max(QTABLE
qt) |
maximum value |
| double qtable_dbl_initial(QTABLE
qt) |
initial value |
| double qtable_dbl_current(QTABLE
qt) |
current value |
The following inspector functions
retrieve information about the confidence
interval associated with a table:
| Prototype: |
Functional
Value: |
| double qtable_conf_halfwidth(double
level, QTABLE qt) |
halfwidth |
| double qtable_conf_lower(double
level, QTABLE qt) |
lower end |
| double qtable_conf_upper(double
level, QTABLE qt) |
upper end |
The following inspector functions retrieve
information about the run length control
associated with a table:
| Prototype: |
Functional
Value: |
| long qtable_batch_size(QTABLE
qt) |
current size
of batch |
| long qtable_batch_count(QTABLE
qt) |
number of batches
used |
| double qtable_conf_mean(QTABLE
qt) |
mid point of
conf. int. |
| long qtable_converged(QTABLE
qt) |
TRUE or FALSE |
| double qtable_conf_aaccuracy(double
level, QTABLE qt) |
accuracy achieved
|
Many statistics are mathematically undefined
if zero time has passed since the creation
or reset of a qtable. The corresponding
inspector functions return a value of
zero in this case.
The following inspector functions retrieve
information about the histogram associated
with a qtable.
| Prototype: |
Functional
Value: |
| long qtable_histogram_num(QTABLE
qt) |
number of buckets |
| double qtable_histogram_low(QTABLE
qt) |
smallest value
that is not underflow |
| double qtable_histogram_high(QTABLE
qt) |
largest value
that is not overflow |
| double qtable_histogram_width(QTABLE
qt) |
width of each
bucket |
| long qtable_histogram_bucket
(QTABLE qt,long i) |
total time value
is in bucket |
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+qtable_histogram_num(
) is the overflow bucket. If a
histogram has not been specified for a
qtable, the above inspector functions
all return zero values.
The inspector functions that retrieve
information about the results of run-length
control are described in
section
16.3, "Run Length Control".
The name of a qtable can be changed at
any time using the
set_name_qtable
function.
Prototype:
void set_name_qtable(QTABLE
qt, char
*new_name)
Example:
set_name_qtable(qt,
"number in queue");
Only the first 80 characters of the qtable's
name are stored.
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_qtable
function.
Prototype:
void reset_qtable(QTABLE
qt)
Example:
reset_qtable(qt);
Although permanent qtables are not reset
by the reset function, they can be reset
explicitly by calling
reset_qtable.
When a qtable is no longer needed, its
storage can be reclaimed using the
delete_qtable
function.
Prototype:
void delete_qtable(QTABLE
qt)
Example:
delete_qtable(qt);
Once a qtable has been deleted, it must
not be further referenced.
