The Structural Simulation Toolkit

Using the supercomputers of today to build the supercomputers of tomorrow

Navigation: Home | Downloads | Documentation | Support

- Statistics API

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`

.

- 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 run-time 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 re-register previously registered statistics.

```
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);
```

```
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"})
```

- 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.

- 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.

`Statistic<T>`

is a templated class based off of StatisticBase.- Methods:
- addData(T data) - Templated method to add data to the Statistic.

- Methods:
- 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?

- Methods (see sst/core/statapi/statbase.h for full set of methods):

- 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 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

- 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 non-zero, 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.

- 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.**NumOutOfBounds-MinValue**- If includeoutofbounds is set, then show count of data that was below BinsMinValue.**NumOutOfBounds-MaxValue**- If includeoutofbounds is set, then show count of data that was below BinsMaxValue.**BinX:**- If dumpbinsonoutput is set, show count of Bin X. Name includes bin number x and min and max values.`<min>`

-`<max>`

- 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.

- 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 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()

- Description
- Output statistic data to the console

- Parameters
**help**- Provide help on this output.

- 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.

- 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.

- 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.

- 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 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