TABLES, QTABLES, HISTOGRAMS AND QHISTOGRAMS

CSIM automatically collects and produces some statistics on the usage of facilities and storage blocks. In addition to these, CSIM has several other structures which can be used to gather more specialized data as a model executes

  • Table - contains a statistical summary of the values which have been recorded (in that table).
  • Histogram - is a both a Table and a frequency “histogram”. The histogram itself is printed as a table indicating frequencies rather than as a graph.
  • Qtable - can be used to maintain statistics on the behavior of a queue of processes. These statistics summarize the number of processes in this queue and the time processes wait in this queue.
  • Qhistogram - is both a Qtable and a distribution of the number of processes "in the queue". The qhistogram itself is printed as a table rather than as a graph. The term queue in this context really means some collection of identifiable states. One common use for a qtable is to collect information on the number of processes at a facility. A note_entry statement is executed by a process as it enters a facility, and a note_exit statement is executed when a process leaves a facility. Various report statements print the (q)tables and (q)histograms (see “CSIM Report Output” on page 45 for details about the reports that are generated):
  • report_table prints a specific table or histogram (and its associated table).
  • report_qtable prints a specific qtable or qhistogram (and its associated qtable).
  • report_tables prints all tables, histograms, qtables, and qhistograms.
  • report prints all of the tables as in report_tables as well as the facility and storage statistics. Tables can be defined to be either permanent or non-permanent. A permanent table is not affected by requests to reset statistics or rerun the model. Permanent tables can therefore be used to gather data across multiple runs of a model.

    Declaring and Initializing Table Structures

    To declare a table, qtable, histogram, or qhistogram:
    TABLE t;
    QTABLE qt;
    HIST hst;
    QHIST qhst;
    Where:

  • t - is the variable name representing the table (type TABLE)
  • qt - is the variable name representing the qtable (type QTABLE)
  • hst - is the variable name representing the histogram and its corresponding table (type HIST)
  • qhst - is the variable name representing the qhistogram and its corresponding qtable (type QHIST)
    Notes:
  • A table must be initialized via a table or permanent_table statement before it can be used in any other statement.
  • A qtable must be initialized via a qtable or permanent_qtable statement before it can be used in any other statement.
  • A histogram must be initialized via a histogram or permanent_histogram statement before it can be used in any other statement.
  • A qhistogram must be initialized via a qhistogram or permanent_qhistogram statement before it can be used in any other statement.
  • If you declare and initialize a (q)histogram, you should not declare and initialize its corresponding (q)table. The (q)histogram is the combination of the (q)table and the (q)histogram.

    To initialize a non-permanent or permanent table
    t = table("name");
    t = permanent_table(‘name”);
    Where:

  • t - is the variable name representing the table (type TABLE)
  • name - is the name of the table (quoted string or type char*)
    Notes:
  • Tables should be declared with global variables in the sim (main) process, prior to the beginning of the simulation part of the model.
  • The contents of a permanent table are not cleared when a model executes a reset, rerun, or clear_tables statement.
  • name is used only for output (reports, status, traces).

    To initialize a non-permanent or permanent qtable
    qt = qtable("name");
    qt = permanent_qtable(‘name”);
    Where:

  • qt - is the variable name representing the table (type QTABLE)
  • name - is the name of the qtable (quoted string or type char*)
    Notes:
  • Qtables should be declared with global variables in the sim (main) process, prior to the beginning of the simulation part of the model.
  • The contents of a permanent qtable are not cleared when a model executes a reset, rerun, or clear_tables statement.
  • name is used only for output (reports, status, traces).

    To initialize a non-permanent or permanent histogram and its corresponding table
    hst = histogram("name", num_intervals, low, high);
    hst = permanent_histogram("name", num_intervals, low, high);
    Where:

  • hst - is the variable name representing the histogram and its corresponding table (type HIST)
  • name - is the name of the histogram and its corresponding table (quoted string or type char*)
  • num_intervals - num_intervals + 2 is the number of buckets into which the histogram is to be divided (type long)
  • One bucket counts the recorded values less than low
  • One bucket counts the recorded values greater than or equal to high
  • The remaining buckets equally distribute the values between low and high and each counts the recorded values in its range
  • low - is the lowest value in the table that is of interest to the modeler (type double)
  • high - is the highest value in the table that is of interest to the modeler (type double)
    Notes:
  • Histograms should be declared with global variables in the sim (main) process, prior to the beginning of the simulation part of the model.
  • The contents of a permanent histogram are not cleared when a model executes a reset, rerun, or clear_tables statement.
  • name is used only for output (reports, status, traces).

    To initialize a non-permanent or permanent qhistogram and its corresponding qtable
    qhst = qhistogram("name", num_intervals);
    qhst = permanent_qhistogram("name", num_intervals);
    Where:

  • qhst - is the variable name representing the histogram and its corresponding qtable (type QHIST)
  • name - is the name of the qhistogram and its corresponding qtable (quoted string or type char*)
  • num_intervals - num_intervals + 2 is the number of buckets into which theqhistogram is to be divided (type long)
  • One bucket counts the recorded values for queue length 0
  • One bucket counts the recorded values greater than the number specified in num_intervals
  • The remaining buckets each handle one queue length from 1 to the number specified in num_intervals
  • num_intervals - is the number of buckets into which the qhistogram is to be divided (type long)
    Notes:
  • Qhistograms should be declared with global variables in the sim (main) process, prior to the beginning of the simulation part of the model.
  • The contents of a permanent qhistogram are not cleared when a model executes a reset, rerun, or clear_tables statement.
  • name is used only for output (reports, status, traces).

    Deleting Table Structures

    To delete a (q)table or a (q)histogram
    delete_table(t);
    delete_qtable(qt);
    Where:

  • t - is the table or histogram to be deleted (type TABLE or HIST)
  • qt - is the qtable or qhistogram to be deleted (type QTABLE or QHIST)

    Using Table Structures

    To enter a value into a table or histogram/table combination
    record(value, t);
    Where:

  • t - is the table or histogram into which the value is to be entered (type TABLE or HIST)
  • value - is the value to be entered into the table or histogram/table combination (type double)

    To enter information into a qtable or qhistogram/qtable combination
    note_entry(qt);
    note_exit(qt);
    Where:

  • qt - is the qtable or qhistogram into which the information is to be entered (type QTABLE or QHIST)
    Notes:
  • These statements are used to collect information which looks like queue length data.
  • When note_entry is called, the queue data is updated and the current queue length (queue state) is increased by one. This statement might be issued before a reserve or use is done on a facility.
  • When note_exit is called, the queue data is updated and the current queue length is decreased by one. This statement might be issued after a release or use is done on a facility.

    To clear the contents of a specific (q)table or (q)histogram/(q)table combination
    reset_table(t);
    reset_qtable(qt);
    Where:

  • t - is the table or histogram to be cleared to zeros (type TABLE or HIST)
  • qt - is the qtable or qhistogram to be cleared to zeros (type QTABLE or QHIST)

    To set the moving average attribute for a (q)table or (q)histogram/(q)table combination
    set_moving_table, n);
    set_moving_qtable(qt, n);
    Where:

  • t - is the table or histogram for which a moving average is to be kept (type TABLE or HIST)
  • qt - is the qtable or qhistogram for which a moving average is to be kept (type QTABLE or QHIST)
  • n - is the number of values in the moving average

    Retrieving (Q)Table/(Q)Histogram-Related Information

    These functions each return a statistic which describes some aspect of the usage of the specified table structure. The syntax conventions for these statements are as follows

  • t - is the table or histogram about which information is requested. It must be type TABLE or HIST.
  • qt - is the qtable or qhistogram about which information is requested. It must be type QTABLE or QHIST.
  • h - is the histogram about which information is requested. It must be type HIST.
  • qh - is the qhistogram about which information is requested. It must be type QHIST.
  • a - is a returned value of type char*.
  • n - is a returned value of type long.
  • x - is a returned value of type double.

    Retrieving Static (Q)Table/(Q)Histogram Information 

    Statement				Returned Value

a = table_name(t);			pointer to name of table/histogram t
a = qtable_name(qt);			pointer to name of qtable/qhistogram qt
n = table_moving_window(t);		number of values in moving window for table/histogram t
n = qtable_moving_window(qt);		number of values in moving window for qtable/qhistogram qt
x = histogram_high(h);			high value defined for a bucket in histogram h
x = histogram_low(h);			low value defined for a bucket in histogram h
n = histogram_num(h);			number of buckets defined for histogram h
n = qhistogram_num(qh);			number of buckets defined for qhistogram qh
x = histogram_width(h)			width (defined number of values) per bucket in histogram h
    Retrieving (Q)Table/(Q)Histogram Status Information 
    Statement				Returned Value

n = current_state(qt);
    
n = qtable_cur(qt);
    

  •  current length of queue (note_entry’s - note_exit’s) in qtable/qhist qt (thtwo statements

  •      yield the identical result)
    • Retrieving (Q)Table/(Q)Histogram Summary Information 
    Statement				Returned Value

n = table_cnt(t);			number of values recorded in table/histogram t
n = qtable_cnt(qt)			number of note_exit’s from qtable /qhistogram qt
x = table_mean(t);			mean of values recorded in table/histogram. t
x = qtable_qlen(qt);			mean queue length from qtable/qhistogram qt
x = table_min(t);			minimum value recorded in table histogram t
x = table_max(t);			maximum value recorded in table/histogram t
x = qtable_max(t);			maximum queue length recorded in qtable/qhistogram qt
x = table_sum(t);			sum of values recorded in table/histogram t
x = table_sum_square(t);		sum of squares of values recorded in table/histogram t
x = table_var(t);			variance of values recorded in table/histogram t
x = qtable_qtime(qt);			mean time in queue (mean time between note_entry and note_exit) for 
						qtable/qhistogram qt
x = qtable_qtsum(qt);			sum of (time * number of values) for qtable/qhist qt
						(space-time integral)
n = histogram_bucket(h, i);		contents of bucket i in histogram h
n = qhistogram_bucket_cnt(qh, i);	number of times queue is a length within bucket i of qhistogram qh
n = qhistogram_bucket_time(qh, i);	percentage of elapsed times queue is a length
						within bucket i in qhistogram qh
n = qhistogram_time(qh);		Total elapsed time in qhistogram qh
    Notes:
  • For a qhistogram, each “bucket” contains just one queue length except for the last bucket, which contains all queue lengths larger than the number of intervals that was specified in the qhistogram definition.