Statistics API
Introduction
Beginning with version 5.0 of SST, a common interface statistics API was developed for for SST components.
The goal of the statistics API was to create a consistent method for collecting statistic data across all SST components, using a simplified interface. Additionally, the API is designed to allow growth in the architecture with minimal impact to users of the API.
An example of statistic usage can be examined in the simpleElementExample under <sstroot>/sst/elements
.
General Operation
User’s Tasks
 The user identifies the statistics they wish to collect and assign names to them (these names are generic and not tied to any specific collection type i.e. histogram, accumulator, etc).
 The user adds all statistic names to the component’s ElementInfoStatistic structure. The ElementInfoStatistic identifies the Statistic Name, description and an enable level for the statistic. The ElementInfoStatistic must also be tied to the components ElementInfoComponent.
 In the component (during construction), each statistic name is registered along with its collection data type. The registration method will instantiate a statistic object in the system and return a pointer to the registered statistic. If the statistic is not enabled (see below), a pointer to a NullStatistic will be returned which will allow all statistic API calls to work, but collects no data.
 The supported collection data types are:
 uint32_t
 uint64_t
 int32_t
 int64_t
 float
 double
 The component will call registeredStatistic>addData(data) to add data to the statistic.
 The user will modify the simulation’s python input file to identify the type of Statistic Output desired, and enable the statistics. Enabling the statistic also allows the user to set the desired collection type (histogram, accumulator) for that statistic name. For more information on the syntax of the Python file see Python File Format.
Note On registering Statistics: All statistics must be registered during component construction before simulation start (sim time advances). After simulation start, attempting to register statistics will cause a runtime error except under the following condition: Attempting to register a statistic with the same “signature” as a previously (before simulation start) registered statistic will return a pointer to the previously registered statistic. This allows components to be destroyed at runtime (the component must not delete the statistic object) and if constructed again to reregister previously registered statistics.
Example C++ Code
static const ElementInfoStatistic StatisticsComponent_statistics[] = {
{ "statA", "Statistic A  Collecting U32 Data", "reads", 1}, // Name, Desc, Units, Enable Level
{ "statB", "Statistic B  Collecting U64 Data", "writes", 2},
{ "statC", "Statistic C  Collecting float Data", "%done", 3},
{ NULL, NULL, NULL, 0 }
};
static const ElementInfoComponent testComponent[] = {
{ "StatisticsComponent", // Name
"StatisticsComponent Desc", // Description
NULL, // PrintHelp
create_ StatisticsComponent, // Allocator
StatisticsComponent_params, // Parameters
StatisticsComponent_ports, // Ports
COMPONENT_CATEGORY_UNCATEGORIZED, // Category
StatisticsComponent_statistics // Statistics
},
{ NULL, NULL, NULL, NULL, NULL, NULL, 0, NULL}
};
//////
Statistic<uint32_t>* statisticA;
Statistic<uint64_t>* statisticB;
Statistic<float>* statisticC;
statisticA = registerStatistic<uint32_t>("statA");
statisticB = registerStatistic<uint64_t>("statB");
statisticC = registerStatistic<float>("statC");
statisticA>addData(data_U32);
statisticB>addData(data_U64);
statisticC>addData(float_data);
Example Python Code
sst.setStatisticLoadLevel(7)
sst.setStatisticOutput("sst.statOutputCSV", {"filepath" : "./TestOutput.csv",
"separator" : ", " } )
compA = sst.Component("statA", "Element.StatisticsComponent")
compB = sst.Component("statB", "Element.StatisticsComponent")
compC = sst.Component("statC", "Element.StatisticsComponent")
sst.enableAllStatisticsForComponentType("Element.StatisticsComponent",
{"type":"sst.HistogramStatistic",
"minvalue" : "10",
"binwidth" : "10",
"numbins" : "41",
"IncludeOutOfBounds" : "1",
"rate" : "100 ns",
"startat" : "100 ns",
"stopat" : "900 ns"})
Operation During Simulation
 At the start of simulation, the selected Statistic Output will be instantiated, and the Statistic Load Level identified.
 When the statistic is registered by a call to component::registerStatistic(), a number of checks to see if the statistic can be enabled are performed:
 Verify that the Statistic Name is found in the ElementInfoStatistic.
 Verify that the statistic has be enabled in the Python File.
 Perform validity checks on the parameters passed from the Python statistic enable function.
 Verity that the system statistic’s load level > statistic enable level defined in the ElementInfoStatistic
 Verity that the Statistic Name (with statSubId) is unique.
 if the checks during component::registerStatistic() succeed, the system will instantiate a Statistic object identified by the type parameter. Otherwise, a NullStatistic will be returned.
 During the simulation, a component can call registeredStatistic>addData(data). This will add the data to the appropriate statistic collection type object instantiated during simulation startup.
 During simulation, the statistic can be setup to output its data at a periodic rate or by number of addData() events.
 The statistic can be optionally configured to clean its data on every output.
 The statistic collection ability can optionally be disabled permanently or for a duration of time.
 The statistic periodic output can optionally be delayed for a duration of time.
 During simulation, the statistic can be setup to start and/or stop at a given point in time.
 At the end of the simulation, any information generated by the Statistic Output can be analyzed.
Notes on SubComponents
 Statistics can be registered in subcomponents.
 The ElementInfoSubComponent “stats” field must be populated similarly to how a ElementInfoComponent is setup (see examples above).
 In the Python script, when enabling a statistic for a subcomponent, the parent component that instantiated the subcomponent must be used as the component name or component type.
Statistics API
Statistic and StatisticBase

Statistic<T>
is a templated class based off of StatisticBase.
 Methods:
 addData(T data)  Templated method to add data to the Statistic.
 StatisticBase is the main class that implements a statistic object.
 Methods (see sst/core/statapi/statbase.h for full set of methods):
 disable()  Disable the Statistic preventing collection.
 enable()  Enable the Statistic
 setFlagResetCountOnOutput()  Enable/Disable resetting the collection count on an output.
 setFlagClearDataOnOutput()  Enable/Disable clearing the data on an output.
 setFlagOutputAtEndOfSim()  Enable/Disable outputting the data at the end of simulation.
 delayOutput()  Delay output of statistic data for a period of simulation time.
 delayCollection()  Prevent collection of statistic data for a period of simulation time.
 isNullStatistic()  Is this statistic a NullStatistic?
Components and SubComponents
 Statistics can be registered in either a Component or a SubComponent using the registerStatistic() method:
template <typename T>
Statistic<T>* registerStatistic(std::string statName, std::string statSubId = "")
 Note: the registerStatistic is a templated function. A collection data type must be provided.

statName is a generic name for the statistic or a group of statistics of the same general type (i.e. SendBitCount).

statSubId is an optional unique identifier for a group of statistics (i.e SendBitCount_Port_1 … SendBitCount_Port_n)
Statistic Collection Types
Statistic Collection Types are templated classes derived from Statistic<T>
.
The available Collection types are:
 Accumulator (sst.AccumulatorStatistic)  Accumulate statistic data
 Histogram (sst.HistogramStatistic)  Histogram of statistic data
 UniqueCount (sst.UniqueCountStatistic)  Count unique entries
 Null (sst.NullStatistic)  Empty “do nothing” statistic; placeholder for statistics that are not enabled.
When instantiated, Statistics will register data fields with the Statistic Output. Fields may be optionally registered depending upon the parameters provided (from the Python file) when the statistic is instantiated.
Duplicated registered fields are not unique across statistics. The allows for common field names to be used thereby reducing output sizes.
When an Statistic is commanded to perform an output, the Statistic will update all registered data fields to the Statistic Output.
When output, the registered fields will include an indicator of the data type for that field
Adding Additional Collection Types To The Core can be achieved by implementing the new statistic collection type in the sst/core/statapi/<collectiontype>.h
, and then adding the new type in simulation::CreateStatistic(). Reference existing
sst.AccumulatorStatistic
 Description
 A simple Accumulator that stored summed and sum squared data. This is the default Statistic Collection Type
 Parameters

type = sst.AccumulatorStatistic

rate = User defined. if not provided or 0, output at end of simulation.

startat = User defined. If set to a time value, the statistic will start disabled, and then be enabled at the set time. If not provided or 0, statistic will start enabled.

stopat = User defined. If set to a time value, the statistic will be disabled at the set time. If not provided or 0, then no change in enable will occur.
Parameter startat (default = 0ns) will identify a time in the simulation when to enable the statistic. If set to nonzero, the statistic will not be enabled at startup. Parameter stopat (default = 0ns) will identify a time in the simulation when to disable the statistic. If set to zero, the statistic will not be disabled.
 Fields Output

Sum  The sum of all data collected

SumSQ  The sum squared of all data collected

CollectionCount  The count of data added to the statistic.
sst.HistogramStatistic
 Description
 A Histogram data collection
 Parameters

type = sst.HistogramStatistic

rate = User defined. if not provided or 0, output at end of simulation.

startat = User defined. If set to a time value, the statistic will start disabled, and then be enabled at the set time. If not provided or 0, statistic will start enabled.

stopat = User defined. If set to a time value, the statistic will be disabled at the set time. If not provided or 0, then no change in enable will occur.

minvalue = The lowest value to be binned.

binwidth = How wide the bins are.

numbins = The number of bins desired.

dumpbinsonoutput = Output the bin counts during an output (default = on)

includeoutofbounds = Provide a Out of Bounds Low Bin and Out of Bounds High Bin for data that is out of normal bin range.
 Fields Output

BinsMinValue  Min bin value.

BinsMaxValue  Max bin value.

BinWidth  Width of bins.

TotalNumBins  Total number of bins.

Sum  The sum of all data collected

SumSQ  The sum squared of all data collected

NumActiveBins  The count of bins that have data in them

NumItemsCollected  The count of data added to the statistic

NumItemsBinned  The count of data that has been binned.

NumOutOfBoundsMinValue  If includeoutofbounds is set, then show count of data that was below BinsMinValue.

NumOutOfBoundsMaxValue  If includeoutofbounds is set, then show count of data that was below BinsMaxValue.

BinX:
<min>
<max>
 If dumpbinsonoutput is set, show count of Bin X. Name includes bin number x and min and max values.
sst.UniqueCountStatistic
 Description
 Collect count of unique entries.
 Parameters

type = sst.UniqueCountStatistic

rate = User defined. if not provided or 0, output at end of simulation.

startat = User defined. If set to a time value, the statistic will start disabled, and then be enabled at the set time. If not provided or 0, statistic will start enabled.

stopat = User defined. If set to a time value, the statistic will be disabled at the set time. If not provided or 0, then no change in enable will occur.
 Fields Output

UniqueItems  The count of unique items (values) added to the statistic.
sst.NullStatistic
 Description
 A place holder statistic that does nothing.
 If statistic fails the RegisterStatistic() call (due to not being enabled or other errors), a Null Statistic will be returned.
 The Null Statistic has no fields or parameters. It is a stub statistic that allows all existing statistic calls to be properly linked and called.
Statistic Outputs
Statistic Outputs control how the output is generated
The available outputs are:
 Console (sst.statOutputConsole)
 Text (sst.statOutputTXT)
 Comma Separated Value (sst.statOutputCSV)
 Compressed Outputs (Only available if libz is included in SST Build):
 Compressed Text (sst.statOutputTXTgz)
 Compressed Comma Separated Value (sst.statOutputCSVgz)
Duplicated registered fields are not unique across statistics. The allows for common field names to be used thereby reducing output sizes.
Adding Additional Statistic Outputs To The Core can be achieved by implementing the new statistic output in the sst/core/statapi/<statoutput>
.h/.cc, and then adding the new type in factory::LoadCoreModule_StatisticOutputs()
sst.statOutputConsole
 Description
 Output statistic data to the console
 Parameters

help  Provide help on this output.
sst.statOutputTXT
 Description
 Output statistic data to a text file
 Parameters

help  Provide help on this output.

filepath  The path to the text file to be created. Default is “./StatisticOutput.txt”

outputtopheader  If set, output a header at start of simulation providing name of each unique registered field of all statistics. Default = 1.

outputinlineheader  If set, output field names inline with the data. Default = 1.

outputsimtime  If set, output simulation time as a field. Default = 1.

outputrank  If set, output rank a field. Default = 1.
sst.statOutputCSV
 Description
 Output statistic data to a csv file
 Parameters

help  Provide help on this output.

separator  The separator between fields. Default is “, “

filepath  The path to the CSV file to be created. Default is “./StatisticOutput.csv”

outputtopheader  If set, output a header at start of simulation providing name of each unique registered field of all statistics. Default = 1.

outputsimtime  If set, output simulation time as a field. Default = 1.

outputrank  If set, output rank a field. Default = 1.
sst.statOutputTXTgz
 Description
 Output statistic data to a compressed text file
 NOTE: Only available if libz is included in SST Build.
 Parameters

help  Provide help on this output.

filepath  The path to the compressed text file to be created. Default is “./StatisticOutput.txt”

outputtopheader  If set, output a header at start of simulation providing name of each unique registered field of all statistics. Default = 1.

outputinlineheader  If set, output field names inline with the data. Default = 1.

outputsimtime  If set, output simulation time as a field. Default = 1.

outputrank  If set, output rank a field. Default = 1.
sst.statOutputCSVgz
 Description
 Output statistic data to a compressed csv file
 NOTE: Only available if libz is included in SST Build.
 Parameters

help  Provide help on this output.

separator  The separator between fields. Default is “, “

filepath  The path to the compressed CSV file to be created. Default is “./StatisticOutput.csv”

outputtopheader  If set, output a header at start of simulation providing name of each unique registered field of all statistics. Default = 1.

outputsimtime  If set, output simulation time as a field. Default = 1.

outputrank  If set, output rank a field. Default = 1.
Custom Statistic Outputs
Custom statistic outputs can be created within an element if the core provided outputs do not meet the users needs.
The custom statistic output must be derived from the StatisticOutput
class (which is itself derived from the Module
class).
To instantiate the custom statistic output, use the sst.setStatisticOutput() method in the Python input file.
sst.setStatisticOutput("myElementExample.myStatisticOutput", {"filepath" : "./TestOutput.xyx"})
For examples of Statistic Outputs, look at:
 sst/core/statapi/statoutputconsole.h/.cpp
 sst/core/statapi/statoutputtxt.h/.cpp
 sst/core/statapi/statoutputcsv.h/.cpp