Global Functions in the SST Python Module
- Global Functions in the SST Python Module
- General Control and Informational Functions
- Functions to Get Handles to Existing Objects
- Statistic Enable and Control Functions
- enableAllStatisticsForAllComponents(stat_params_dict)
- enableAllStatisticsForComponentName(name, stat_params_dict, apply_to_children=False)
- enableStatisticForComponentName(name, stat, stat_params_dict, apply_to_children=False)
- enableStatisticsForComponentName(name, stat, stat_params_dict, apply_to_children=False)
- enableAllStatisticsForComponentType(type, stat_params_dict, apply_to_children=False)
- enableStatisticForComponentType(type, stat, stat_params_dict, apply_to_children=False)
- enableStatisticsForComponentType(type, stat_list, stat_params_dict, apply_to_children=False)
- setStatisticLoadLevelForComponentName(name, level, apply_to_children=False)
- setStatisticLoadLevelForComponentType(type, level, apply_to_children=False)
- setStatisticLoadLevel(level)
- getStatisticLoadLevel()
- setStatisticOutput(stat_output_module)
- setStatisticOutputOption(option, value)
- setStatisticOutputOptions(options)
- General Notes on Statistics
The SST core python module provides a set of global functions not attached to any particular class. These functions generally fall into one of the following categories: general control and informational functions, functions to get handles to existing objects and statistic enable and control functions. These functions are described below. Following those descriptions is a section on general notes on statistics.
setProgramOption(option,value)
Sets the specified program option for the simulation. These mirror the options available on the sst command line. Parameters set in the python file will be overwritten by options set on the command line. Use sst –help to get a list of available options.
Parameters
- option (type: string) configuration option to set
- value (type: varies by option) value to set option to
- returns none
getProgramOptions()
Returns a dictionary with the current values of the program options. This will include all program options, not just those set in the python file.
Parameters
- returns python dictionary with program options and values
getMPIRankCount()
Returns the number of physical MPI ranks in the simulation
Parameters
- returns number of MPI ranks in the simulation
getSSTThreadCount()
Returns the threads per rank specified for the simulation
Parameters
- returns number of threads per MPI rank in the simulation
setSSTThreadCount(threads)
Sets the number of threads per rank for the simulation. These values can be overwritten by using -n on the command line.
Parameters
- threads (type: int) number of threads per MPI rank to use in the simulation
- returns none
pushNamePrefix(prefix)
Pushes a name prefix onto the name stack. This prefix will be added on the names of all Components and Links. The names in the stack are separated by a period. Example, if pushNamePrefix(“base”) and pushNamePrefix(“next”) were called in that order, the prefixed name would be “base.next”. Prefixes can be popped from the stack using popNamePrefix().
Parameters
- prefix : (type: string) prefix to add to the name stack
- returns none
popNamePrefix()
Pops a prefix from the name stack. See pushNamePrefix for how name stacks are used.
Parameters
exit()
Causes the simulation to exit.
Parameters
Functions to Get Handles to Existing Objects
findComponentByName(name)
In many cases, Components and SubComponents will be created using library functions and the user will not have direct access to their handles. In some instances, the provided python modules will have accessor functions that can provide handles to these elements. If this is not provided by the library, the user can call the findComponentByName() function to get a handle to the desired element. The function can find handles for both Components and SubComponents. The use of this function presupposes a knowledge of the naming convention of the elements in the build functions of the library.
Parameters
- name (type: string) name of the Component or SubComponent to find. The name for SubComponents is described above. Slot indexes are optional in cases where only on SubComponent has been added to a slot, but you can also use [0] in all cases, even when the actual name will not display this way.
- returns the function will return a handle to the Component/SubComponent with the provided name, or None if the name is not found.
Statistic Enable and Control Functions
The following functions are used to enable statistics on Components and SubComponents using the name or type of the element. See General Notes on Statistics for more information.
enableAllStatisticsForAllComponents(stat_params_dict)
Enables all statistics for all Components in the simulation that have already been instanced.
Parameters
- stat_params_dict (type: dict) Python dictionary that specified the statistic parameters. All statistics will get the same set of parameters.
- returns none
enableAllStatisticsForComponentName(name, stat_params_dict, apply_to_children=False)
Enables all statistics for the Component named in the call. This call works for both Components and SubComponents.
Parameters
- name (type: string) name of the Component or SubComponent on which to enable all statistics. The name for SubComponents is described above. Slot indexes are optional in cases where only one SubComponent has been added to a slot, but you can also use [0] in all cases, even when the actual name will not display this way. If component with the provided name not found, the function will call fatal().
- stat_params_dict (type: dict) Python dictionary that specified the statistic parameters. All statistics will get the same set of parameters
- include_children (type: bool) If set to True, will recursively enable all statistics on all SubComponent descendants of named element.
- returns none
enableStatisticForComponentName(name, stat, stat_params_dict, apply_to_children=False)
Enables a statistic for the component on which the call is made.
Parameters
- name (type: string) name of the Component or SubComponent on which to enable the specified statistic. The name for SubComponents is described above. Slot indexes are optional in cases where only on SubComponent has been added to a slot, but you can also use [0] in all cases, even when the actual name will not display this way. If component with the provided name not found, the function will call fatal().
- stat (type: string) statistic to be enabled
- stat_params_dict (type: dict) Python dictionary that specifies the statistic parameters
- include_children (type: bool) If set to True, will recursively enable specified statistic on all SubComponent descendants.
- returns none
enableStatisticsForComponentName(name, stat, stat_params_dict, apply_to_children=False)
Enables a list of statistics for the component on which the call is made.
Parameters
- name (type: string) name of the Component or SubComponent on which to enable specified statistics. The name for SubComponents is described above. Slot indexes are optional in cases where only on SubComponent has been added to a slot, but you can also use [0] in all cases, even when the actual name will not display this way. If component with the provided name not found, the function will call fatal().
- stat_list (type: list of strings) list of statistics to be enabled. If only one stat is to be enabled, you may pass a single string instead of a list.
- stat_params_dict (type: dict) Python dictionary that specified the statistic parameters
- include_children (type: bool) If set to True, will recursively enable specified statistic on all SubComponent descendants.
- returns none
enableAllStatisticsForComponentType(type, stat_params_dict, apply_to_children=False)
Enables all statistics for all previously instanced Components/SubComponents of the type specified in the call. This call works for both Components and SubComponents.
Parameters
- type (type: string) type of the Component or SubComponent on which to enable all statistics. All previously instanced elements of this type will have their statistics enabled.
- stat_params_dict (type: dict) Python dictionary that specified the statistic parameters. All statistics will get the same set of parameters.
- include_children (type: bool) If set to True, will recursively enable all statistics on all SubComponent descendants.
- returns none
enableStatisticForComponentType(type, stat, stat_params_dict, apply_to_children=False)
Enables a the specified statistic for all previously instanced Components/SubComponents of the type specified in the call. This call works for both Components and SubComponents.
Parameters
- type (type: name) type of the Component or SubComponent on which to enable the specified statistic. All previously instanced elements of this type will have their statistics enabled.
- stat (type: string) statistic to be enabled
- stat_params_dict (type: dict) Python dictionary that specified the statistic parameters
- include_children (type: bool) If set to True, will recursively enable specified statistic on all SubComponent descendants.
- returns none
enableStatisticsForComponentType(type, stat_list, stat_params_dict, apply_to_children=False)
Enables a list of statistics for all previously instanced Components/SubComponents of the type specified in the call. This call works for both Components and SubComponents.
Parameters
- type (type: string) type of the Component or SubComponent on which to enable the specified statistics. All previously instanced elements of this type will have their statistics enabled.
- stat_list (type: list of strings) list of statistics to be enabled. If only one stat is to be enabled, you may pass a single string instead of a list.
- stat_params_dict (type: dict) Python dictionary that specified the statistic parameters
- include_children (type: bool) If set to True, will recursively enable specified statistic on all SubComponent descendants.
- returns none
setStatisticLoadLevelForComponentName(name, level, apply_to_children=False)
Sets the statistic load level for the named component.
Parameters
- name (type: string) name of the Component or SubComponent on which to set the statistic load level. The name for SubComponents is described above. Slot indexes are optional in cases where only on SubComponent has been added to a slot, but you can also use [0] in all cases, even when the actual name will not display this way. If component with the provided name not found, the function will call fatal().
- level (type: int) statistic load level for the component
- include_children : (type:bool) If set to True, will recursively enable specified statistic on all SubComponent descendants.
- returns none
setStatisticLoadLevelForComponentType(type, level, apply_to_children=False)
Sets the statistic load level for all components of the specified type.
Parameters
- type (type: string) type of the Component or SubComponent on which to set the statistic load level. All previously instanced elements of this type will have their level set.
- level (type: int) statistic load level for the components
- include_children (type: bool) If set to True, will recursively enable specified statistic on all SubComponent descendants.
- returns none
setStatisticLoadLevel(level)
Set the global statistic load level. This level is used if individual load levels are not set. Also, the load level is only used for statistics not specifically enabled (i.e., not enabled using one of the enableAllStatistics variants).
Parameters
- level (type: int) value to set global statistic load level to
- returns none
getStatisticLoadLevel()
Return the global statistic load level
Parameters
- returns value of global statistic load level
setStatisticOutput(stat_output_module)
Sets the global StatisticOutput to be of the module type specified
Parameters
- stat_output_module (type: string) name of the stat output module to load in lib.element format.
- returns none
setStatisticOutputOption(option, value)
Set the specified option for the StatisticOutput object.
Parameters
- option (type: string) option to set
- value (type: string) value to set option to
- returns none
setStatisticOutputOptions(options)
Set the specified options for the StatisticOutput object
Parameters
- options (type: dict) dictionary the contents specify the option as dictionary keys with the options value being specified by the corresponding dictionary value.
- returns none
General Notes on Statistics
There are a number of ways to enable statistics on Components and SubComponents. There are a set of functions that can be called directly on Component/SubComponent handles and a set of functions that are provided by the sst python module that use name or type to find the elements on which to enable statistics. There may also be specific methods provided by element library python modules.
Statistic load levels
It is possible to set load levels both globally and per Component/SubComponent. Each statistic defined in Components/SubComponents has a load level assigned to it in order to help with finer grained control with using the enableAllStatistics* functions. Load levels only apply to statistics not explicitly enabled. Also, local load levels will override global load levels.
The precedence for enabling statistics is as follows: If a statistic is explicitly enabled (does not use one of the enableAllStatistics* functions), it will be enabled. Else, if the set load level meets the minimum for a statistic and all statistics for the component have been enabled, the statistic will be enabled. The local load level will be used, if set, otherwise the global load level will be used.
Statistic parameters
Statistic parameters are used to pass the parameters to the statistics subsystem and to the the statistics themselves and are specified in a python dictionary. In addition to statistic specific parameters, the following parameters are supported:
- type type of statistic
- rate collection rate of statistic. Stats will be dumped at this interval. A rate of “0ns” will cause the stats to be dumped only at the end of simulation.
- startat Time that statistic should start recording statistics
- stopat Time that statistic should stop recording statistics
- resetOnRead If set to true, statistics will reset when written out. Default is False.
