SST 11 Python Module

SST provides a python module to allow interaction with the simulation build system. The python module is defined in cpython and is only available in the python interpreter launched within a running SST executable. The module is accessed by importing the sst module. This can be done in a number of ways. The two most common being:

import sst
from sst import *

Within this module, there are a number of available classes and global functions. The available classes are: Component, SubComponent, Link, StatisticOutput and StatisticGroup. The global functions are divided between general functions and functions operating on or returning one of the available objects. This document will first discuss the available classes in the SST python module and will then document the global functions.

SST Classes

There are 5 classes available in SST: Component, SubComponent, Link, StatisticGroup and StatisticOutput. The Component and SubComponent classes share many of the same functions and will be covered together.

Component

A Component is created by instancing an sst.Component class. The user initialization function is:

Component(name, type):

Parameters:

SubComponent

A SubComponent is created by calling setSubComponent() on either a Component or SubComponent object. Instancing a SubComponent in this way creates a User SubComponent and allows the user to specify the parameters and statistics directly on the SubComponent. The name of the SubComponent is automatically generated using the name of the parent Component and the slot_name(s) in which SubComponents are loaded. If more than one SubComponent is loaded into a slot, the slot_name is also indexed. This name can be used to get a handle to the SubComponent later in the python code. See setSubComponent function description below.

Functions Common to Component and SubComponent

setSubComponent(slot_name, type, slot_index = 0):

Inserts a subcomponent of the specified type into the indicated slot name and index.

Parameters:

Return value: the function returns an sst.SubComponent object

addParam(key, value):

Adds a parameter to the Params object for the Component/SubComponent

Parameters:

Return value: none

addParams(params):

Adds multiple parameters to the Params object for the Component/SubComponent

Parameters:

Return value: none

Connects a link to the specified port with the specified latency on the link. You can also connect a link by using Link.connect(). If a default latency is specified on the Link, then the latency parameter is optional, however, if no default latency is set on the Link, the latency parameter to addLink is required.

Parameters:

Return value: none

getFullName():

Returns the full name of the Component/SubComponent. For Components, the name is the one supplied by the user at the time the Component was created. For SubComponents, the name is automatically generated from the parent Component and slot name. At each level, the name is generated as the parent's name plus the slot name, separated by a colon. The slot number is appended in square brackets:

Parent:slot[index]

This holds true for SubComponents of SubComponents, the slotname and index are just appended to the parent name:

Parent:slot[index]:slot[index]

Parameters:

Return value: full name of Component/SubComponent

getType():

Returns the type of the component in lib.element format. This is simply the type supplied to either the Component constructor or setSubComponent() call.

Parameters:

Return value: type of Component/SubComponent

setStatisticLoadLevel(level, apply_to_children=False):

Sets the load level for this statistic. This overrides the default load level. Load levels are not used for statistics that are explicitly enabled (i.e., does not use one of the "All" variants for enabling statistics. See "General Notes on Statistics" below for more information.

Parameters:

enableAllStatistics(stat_params_dict, apply_to_children=False):

Enables all statistics for the Component/SubComponent on which the call is made. See "General Notes on Statistics" below for more information.

Parameters:

Call example:

comp.enableAllStatistics({
    "type":"sst.AccumulatorStatistic",
    "rate":"0ns"
})

enableStatistics(stat_list, stat_params_dict, apply_to_children=False):

Enables a list of statistics for the component on which the call is made. See "General Notes on Statistics" below for more information.

Parameters:

setCoordinates():

Documentation forthcoming

Functions Unique to Component

setRank(mpi_rank, thread = 0):

Sets the rank the Component should be assigned to. This information is only used if the partitioner is set to sst.self.

Parameters:

Return value: none

setWeight(weight):

Sets the weight of the Component. The weight is used by some partitioners to help balance Components across ranks.

Parameters:

Return value: none

The Link object is used to connect Component/SubComponents together to form the simulation. The Link is created using:

Link(name, latency=None):

Parameters:

connect( (comp1, port1 latency1=default), (comp2, port2, latency2=default):

Connects two ports using the link object. If a default latency is specified on the Link, then the latency parameters are optional, however, if no default latency is set on the Link, the latency parameters to connect are required.

Parameters:

Actual parameters are two tuples representing the information for the ports to be connected. The fields in the tuple are (comp, port, latency) as describe below.

Return value: none

setNoCut()

Tell the simulator that this link should not be "cut" by a partition boundary. In effect, it will guarantee that the two Components connected by this link will be on the same rank. This must be used with care, as you can easily get into a situation where too many components are on the same rank.

Parameters:

Return value: former value of no_cut variable

StatisticOutput

Documentation forthcoming

StatisticGroup

Documentation forthcoming

Global Functions in SST Python Module

General Control and Informational Functions

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:

setProgramOptions(options):

Sets the specified program options 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:

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:

Return value: python dictionary with program options and values

getMPIRankCount():

Returns the number of physical MPI ranks in the simulation

Parameters:

Return value: number of MPI ranks in the simulation

getSSTThreadCount():

Returns the threads per rank specified for the simulation

Parameters:

Return value: number of threads per MPI rank in the simulation

setSSTThreadCount(threads):

Sets the number of threads per rank for the simulation. This value is overwritten if -n is specified on the command line.

Parameters:

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:

popNamePrefix()

Pops a prefix from the name stack. See pushNamePrefix for how name stacks are used.

exit()

Causes the simulation to exit.

Function to Get Handles to Existing Objects

findComponentByName(name):

In many cases, Component 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:

Return value: 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" below for more information.

enableAllStatisticsForAllComponents(stat_params_dict):

Enables all statistics for all Components in the simulation that have already been instanced.

Parameters:

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:

enableStatisticForComponentName(name, stat, stat_params_dict, apply_to_children=False):

Enables a statistic for the component on which the call is made.

Parameters:

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:

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:

enableStatisticForComponentType(type, stat, stat_params_dict, apply_to_children=False):

Enables a list of statistics for the component on which the call is made.

Parameters:

enableStatisticsForComponentType(type, stat_list, stat_params_dict, apply_to_children=False):

Enables a list of statistics for the component on which the call is made.

Parameters:

setStatisticLoadLevelForComponentName(name, level, apply_to_children=False):

Sets the statistic load level for the named component.

Parameters:

name: 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 a component with the provided name is not found, the function will call fatal().

setStatisticLoadLevelForComponentType(type, level, apply_to_children=False):

Sets the statistic load level for all components of the specified type.

Parameters:

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:

getStatisticLoadLevel():

Return the global load level

Parameters:

Return Value: value of global load level

setStatisticOutput(stat_output_module):

Sets the global StatisticOutput to be of the module type specified

Parameters:

setStatisticOutputOption(option,value):

Set the specified option for the StatisticOutput object.

Parameters:

setStatisticOutputOptions(options):

Set the specified options for the StatisticOutput object

Parameters:

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 statistics themselves and are specified in a python dictionary. In addition to statistic specific parameters, the following parameters are supported: