ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.contactcenters.app
Interface ContactCenterEval

All Superinterfaces:
ContactCenterInfo
All Known Subinterfaces:
ContactCenterSim, ContactCenterSimWithObservations, ContactCenterSimWithObservationSets, ObservableContactCenterSim
All Known Implementing Classes:
AbstractCallCenterCTMCSim, AbstractCallCenterCTMCSimMP, AbstractCallCenterSim, AbstractContactCenterEval, AbstractContactCenterSim, BasicCallCenterCTMCSim, BasicCallCenterCTMCSimMP, CallCenterCTMCSimSplit, CallCenterSim, CallCenterSimRQMC, CallCenterSimStrat, ContactCenterEvalResults, ContactCenterSimResults, IntMCallCenterCTMCSim, MBatchMeansSim

public interface ContactCenterEval
extends ContactCenterInfo

Represents a system evaluating some performance measures of a contact center. An evaluation is a process estimating some performance measures according to user-defined parameters. It can be performed by approximation formulas or by simulations while parameters can be obtained from any data source, e.g., files, programs, etc.

This interface represents an evaluation system adapted for contact centers. Each system uses internal, implementation-specific parameters usually read from files and stored into dedicated objects, e.g., CallCenterParams. It also defines some external parameters called evaluation options which can be modified through this interface, by using the setEvalOption(umontreal.iro.lecuyer.contactcenters.app.EvalOptionType, java.lang.Object) method. Evaluations are triggered by using the eval() method, and matrices of performance measures are accessible through the getPerformanceMeasure(umontreal.iro.lecuyer.contactcenters.app.PerformanceMeasureType) method.

The methods setEvalOption(umontreal.iro.lecuyer.contactcenters.app.EvalOptionType, java.lang.Object) and getPerformanceMeasure(umontreal.iro.lecuyer.contactcenters.app.PerformanceMeasureType) are generic methods accepting an argument indicating the evaluation option or group of performance measures of interest, respectively. This design allows the interface to be extended in the future, by adding new options or groups of measures, without affecting current implementations.

The construction of the contact center and the supported evaluation options and performance measures are specific to the implementation of this interface, but the access to the evaluation mechanism is unified. A contact center evaluation system is not forced to support all of the defined performance measures and evaluation options, because the interface specifies facilities to enumerate supported groups of performance measures and evaluation options, and to test the support of a specific measure or option.


Method Summary
 void eval()
          Evaluates the contact center's supported performance measures using the current values of implementation-specific parameters and evaluation options.
 String formatStatistics()
          Formats information about every performance measure after eval() is called.
 boolean formatStatisticsExcel(WritableWorkbook wb)
          Constructs and returns an JExcel API workbook containing the results of the evaluation, and appends the contents of the generated report to the workbook wb.
 String formatStatisticsLaTeX()
          Formats and returns a statistical report that can be included into a LATEX document.
 Map<String,Object> getEvalInfo()
          Represents information about this evaluation system that should be included in any report produced by formatStatistics().
 Object getEvalOption(EvalOptionType option)
          Returns the current value of the evaluation option option.
 EvalOptionType[] getEvalOptions()
          Returns the array of the evaluation option types supported by the implementing object.
 DoubleMatrix2D getPerformanceMeasure(PerformanceMeasureType m)
          Returns the matrix of values corresponding to the group of performance measures m estimated by the last call to eval().
 PerformanceMeasureType[] getPerformanceMeasures()
          Returns an array containing all the groups of performance measures this object can estimate.
 ReportParams getReportParams()
          Returns the parameters for reports formatted by formatStatistics(), or formatStatisticsExcel(WritableWorkbook).
 boolean hasEvalOption(EvalOptionType option)
          Determines if the evaluation option option is supported by the implemented system.
 boolean hasPerformanceMeasure(PerformanceMeasureType m)
          Determines if the evaluation system can estimate performance measures in group m.
 boolean isVerbose()
          Determines if the implementation should print information during the evaluation of the performance measures.
 void reset()
          Resets this contact center evaluation system for new parameters.
 boolean seemsUnstable()
          Determines if the system seems to be unstable.
 void setEvalOption(EvalOptionType option, Object value)
          Sets the evaluation option option to value.
 void setReportParams(ReportParams reportParams)
          Sets the report parameters to reportParams.
 void setVerbose(boolean v)
          Sets the verbose status to v.
 
Methods inherited from interface umontreal.iro.lecuyer.contactcenters.app.ContactCenterInfo
getAgentGroupName, getAgentGroupProperties, getAgentGroupSegmentName, getAgentGroupSegmentProperties, getContactTypeName, getContactTypeProperties, getContactTypeSegmentName, getContactTypeSegmentProperties, getDefaultUnit, getInContactTypeSegmentName, getInContactTypeSegmentProperties, getMainPeriodName, getMainPeriodSegmentName, getMatrixOfAWTName, getNumAgentGroups, getNumAgentGroupSegments, getNumAgentGroupsWithSegments, getNumContactTypes, getNumContactTypeSegments, getNumContactTypesWithSegments, getNumInContactTypes, getNumInContactTypeSegments, getNumInContactTypesWithSegments, getNumMainPeriods, getNumMainPeriodSegments, getNumMainPeriodsWithSegments, getNumMatricesOfAWT, getNumOutContactTypes, getNumOutContactTypeSegments, getNumOutContactTypesWithSegments, getNumWaitingQueues, getNumWaitingQueueSegments, getNumWaitingQueuesWithSegments, getOutContactTypeSegmentName, getOutContactTypeSegmentProperties, getWaitingQueueName, getWaitingQueueProperties, getWaitingQueueSegmentName, getWaitingQueueSegmentProperties
 

Method Detail

getEvalOptions

EvalOptionType[] getEvalOptions()
Returns the array of the evaluation option types supported by the implementing object. The evaluation options are the variable parameters of the contact center which can be changed between calls to eval(). This should never return a null pointer; if no evaluation options are supported for some reasons, this should return an array with length 0.

Returns:
the array of supported evaluation options.

hasEvalOption

boolean hasEvalOption(EvalOptionType option)
Determines if the evaluation option option is supported by the implemented system. It should return true if and only if the option is in the array returned by getEvalOptions(). Otherwise, it returns false.

Parameters:
option - the queried evaluation option.
Returns:
the support status of the option.
Throws:
NullPointerException - if option is null.

getEvalOption

Object getEvalOption(EvalOptionType option)
Returns the current value of the evaluation option option. The class of the returned object must be assignable to the class given by EvalOptionType.getType(). If the option is not supported, this should throw a NoSuchElementException. This exception can be thrown if and only if hasEvalOption(umontreal.iro.lecuyer.contactcenters.app.EvalOptionType) returns false for the given option.

Parameters:
option - the queried evaluation option.
Returns:
the current value of the option.
Throws:
NoSuchElementException - if the option is not available.
NullPointerException - if option is null.

setEvalOption

void setEvalOption(EvalOptionType option,
                   Object value)
Sets the evaluation option option to value. If the given option is not supported, this throws a NoSuchElementException. If the class of the given value is incompatible, this throws a ClassCastException. If the evaluation option cannot be changed, this throws an UnsupportedOperationException.

Parameters:
option - the option to be set.
value - the new value of the option.
Throws:
NoSuchElementException - if the given option is not supported.
ClassCastException - if the given value is from an incompatible class.
IllegalArgumentException - if the given value is invalid.
UnsupportedOperationException - if the evaluation option is read-only.
NullPointerException - if the option is null or the value is unexpectedly null.

eval

void eval()
Evaluates the contact center's supported performance measures using the current values of implementation-specific parameters and evaluation options. If parameters or seeds of random streams are not changed, multiple calls to this method should return the same results. In consequence of this, simulation should reset the random number streams before returning. This method can throw an IllegalStateException if there is an inconsistency in the system's parameters. It can throw an ArithmeticException if, for the given parameters, the performance measures cannot be estimated.

Throws:
IllegalStateException - if there are invalid parameter values.
ArithmeticException - if no solution can be computed.

seemsUnstable

boolean seemsUnstable()
Determines if the system seems to be unstable. When a system is unstable, the returned steady-state performance measures are not reliable. This method mainly applies for stationary simulators which return true when the system appears to be unstable, i.e., some waiting queues grow up with simulation time. The method must throw an IllegalStateException if it is called before eval() and always return false if no stability check applies.

Returns:
the result of the stability check.
Throws:
IllegalStateException - if this method is called before the evaluation is performed.

getEvalInfo

Map<String,Object> getEvalInfo()
Represents information about this evaluation system that should be included in any report produced by formatStatistics(). The information is organized as (key, value) pairs in a map. This information may include steps of an approximation, number of iterations, etc. One can modify the returned map to add custom information. The content of this map should not affect the process of the evaluation; it is used only for building the statistical report. One can use evaluation options for system parameters.

Returns:
the evaluation information.

formatStatistics

String formatStatistics()
Formats information about every performance measure after eval() is called. It can be simulation statistics, information about the steps of an approximation algorithm, or simply the values of all performance measures. This method should call getEvalInfo() to obtain general information about the evaluation and incorporate the information into the returned string. For each entry in the map, the method should add a key: value line in the string. Then, the method appends the performance measures to the returned string. The PerformanceMeasureFormatText class can be used to convert matrices of performance measures into strings. If the evaluation was not triggered by calling eval() before this method is called, an IllegalStateException is thrown. If no statistical information is available even after the evaluation, this method should return an empty string instead of throwing an exception.

Returns:
a string containing a statistical report.
Throws:
IllegalStateException - if no statistical information is available because the evaluation was not triggered.

formatStatisticsLaTeX

String formatStatisticsLaTeX()
Formats and returns a statistical report that can be included into a LATEX document. This is similar to formatStatistics(), except the generated report is in LATEX rather than plain text.

Returns:
the formatted report.

formatStatisticsExcel

boolean formatStatisticsExcel(WritableWorkbook wb)
Constructs and returns an JExcel API workbook containing the results of the evaluation, and appends the contents of the generated report to the workbook wb. This method may add multiple sheets, e.g., for general and detailed information. This method should add the information in the map returned by getEvalInfo() to a sheet in the workbook. This method returns true if and only if the given workbook was modified.

One can then customize the returned workbook as needed. The method WritableWorkbook.write() can be used to export the workbook to an output stream. This can be used to create files that can be opened directly by Microsoft Excel for results analysis and reporting. Excel documents can also be opened by open source software such as OpenOffice.org, KOffice, etc.

Parameters:
wb - the workbook to append report to.
Returns:
true if and only if the given workbook was modified.

getReportParams

ReportParams getReportParams()
Returns the parameters for reports formatted by formatStatistics(), or formatStatisticsExcel(WritableWorkbook). If no object containing report parameters is available, this method should create a new one using the default constructor of ReportParams.

Returns:
the printed statistics.

setReportParams

void setReportParams(ReportParams reportParams)
Sets the report parameters to reportParams.

Parameters:
reportParams - the report parameters..
See Also:
getReportParams()

getPerformanceMeasures

PerformanceMeasureType[] getPerformanceMeasures()
Returns an array containing all the groups of performance measures this object can estimate. If no performance measure is supported by a given implementation, this method should return an array with length 0 instead of null.

Returns:
the array of groups of performance measures.

hasPerformanceMeasure

boolean hasPerformanceMeasure(PerformanceMeasureType m)
Determines if the evaluation system can estimate performance measures in group m. This should return true if and only if the group of performance measures is listed in the array returned by getPerformanceMeasures().

Parameters:
m - the group of performance measures being tested.
Returns:
a true value if the measure is supported, false otherwise.
Throws:
NullPointerException - if m is null.

getPerformanceMeasure

DoubleMatrix2D getPerformanceMeasure(PerformanceMeasureType m)
Returns the matrix of values corresponding to the group of performance measures m estimated by the last call to eval(). The dimensions of the matrix and the role of its elements depend on the queried group of performance measures, and the capabilities of the implementing evaluation system. See the PerformanceMeasureType class for more information about the defined performance measures. If the queried measure is not supported by this evaluation object, this throws a NoSuchElementException. If the values of the measures are not available, e.g., the eval() method was never called after the last call to reset(), this throws an IllegalStateException.

Parameters:
m - the queried group of performance measures.
Returns:
the matrix of values computed by the evaluation system.
Throws:
NoSuchElementException - if the given performance measure is not supported by this object.
IllegalStateException - if the values are not available.
NullPointerException - if m is null.

reset

void reset()
Resets this contact center evaluation system for new parameters. Every cached or processed parameter should be reread from the parameter objects. In the case of the simulation, one should try to preserve random number seeds whenever possible, even if the contact center needs to be reconstructed. Some implementatios of this interface provide specialized reset methods allowing to change the associated parameter objects.


isVerbose

boolean isVerbose()
Determines if the implementation should print information during the evaluation of the performance measures. The information depends on the type of evaluation method being involved. It can include steps or iterations of an approximation algorithm, or information about important elements of a simulation. Summary information should be printed on the standard output while debugging data, e.g., traces of every event in a simulation, should be sent to log files if they are generated. By default, the verbose mode is disabled.

Returns:
true if the implementation is in verbose mode, false otherwise (the default).

setVerbose

void setVerbose(boolean v)
Sets the verbose status to v. If v is true, verbose mode is enabled. Otherwise, it is disabled.

Parameters:
v - true to activate verbose mode, false to disable it.
See Also:
isVerbose()

ContactCenters
V. 0.9.9.

To submit a bug or ask questions, send an e-mail to Richard Simard.