Home » SSTDocumentation » Core Python Module

Core Python Module

Core Python Module
Component/SubComponent Classes
Link Class
Statistic
- addParam(key, value)
- addParams(params)
StatisticOutput
StatisticGroup

There are five 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/SubComponent Classes

The Component and SubComponent Python classes represent the Component and SubComponent C++ classes that are used to implement the simulation models used in SST. They are similar, and have similar APIs, but SubComponents can only exist inside of Components. Subsequently, Components are instanced directly, but SubComponents are only instanced through a Component or another SubComponent.

The figures below show the main structures of the Component/SubComponent objects. The right image illustrates the arbitrary nesting capability of SubComponents.

Main structures of the Component and SubComponent objects Component with SubComponents loaded, showing that SubComponents can be arbitrarily nested

An instance of Component is created using:

Component(name, element_type)

Creates a new Component object.

Parameters

name (type: string) name of the Component specified as string. The name can be used to get a handle to the Component later in the Python code. The name is also available to the C++ implementation of the Component
element_type (type: string) type of the Component in the lib.element format (for example, "merlin.hr_router") specified as a string
returns Component object

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 using square brackets (e.g. [0]). This name can be used to get a handle to the SubComponent later in the Python code. See setSubComponent function description below.

setSubComponent(slot_name, element_type, slot_index = 0)

Inserts a SubComponent of the specified type into the indicated slot name and index and creates a new SubComponent object

Parameters

slot_name (type: string) name of the slot in which the SubComponent should be loaded.
element_type type of the SubComponent in the lib.element format (for example, "merlin.linkcontrol")
slot_index (type: string) slot index in which the SubComponent should be inserted. This defaults to 0 and is not required if only one SubComponent is being loaded into the specified slot. Each SubComponent must be loaded into a unique slot_index and some (Sub)Components will require the indexes to be linear with no gaps.
returns SubComponent object

Functions Common to Component and SubComponent

The following functions are available to both Component and SubComponent classes.

addParam(key, value)

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

Parameters

key (type: string) name of the parameter
value (type: varies) value of the parameter. This can be almost any Python object and the __str__ method will be called to get a string representation. A list can be passed to this call when the find_array function is used in the class to retrieve the parameters.
returns none

addParams(params)

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

Parameters

params (type: dict) a Python dict of key, value pairs. See addParam() description for information about how key and value are used.
returns none

addLink(link, port, latency=link_default)

Connects a link to the specified port with the specified latency on the link. You can also connect a link by using Link.connect().

Parameters

link (type: sst.Link) sst.Link object that will be connected to the port
port (type: string) name of the port to connect the link to
latency (type: string) latency of the link from the perspective of this Component/SubComponent sending an event. This parameter is optional and the call will use the default latency set on the link if it’s not specified in the call.
returns 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

returns full name of Component/SubComponent as a string

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

returns type of Component/SubComponent

setStatistic(stat_name, stat_obj=None)

Sets the statistic object to use in the specified statistic slot.

Parameters

stat_name Name of the statistic that will be set
stat_obj Statistic object that will be used for the named statistic slot. If no stat object is specified, a new one will be created and returned.
returns Statistic object loaded into the specified statistic slot.

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 for more information.

Parameters

level (type: int) statistic load level for the component
include_children (type: bool) If set to True, will recursively enable specified statistics on all currently instanced SubComponent descendants. SubComponents created after this call will not have their load level set
returns none

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 for more information.

Parameters

stat_params_dict (type: dict) Python dictionary that specified the statistic parameters. All statistics will get the same set of parameters
include_children If set to True, will recursively enable specified statistics on all currently instanced SubComponent descendants. SubComponents created after this call will not have their statistics enabled.
returns none

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 for more information.

Parameters

stat_list (type: string or 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. All statistics will get the same set of parameters
include_children (type: bool) If set to True, will recursively enable specified statistics on all currently instanced SubComponent descendants. SubComponents created after this call will not have their statistics enabled.
returns none

setCoordinates(x, y=0.0, z=0.0)

Sets the x, y, z coordinates for this element. This is for use with visualization.

Parameters

x (type: float) sets the x position of the element
y (type: float) sets the y position of the element
z (type: float) sets the z position of the element
returns none

Functions Unique to Component

The following functions are unique to Components, and, therefore, are not available to SubComponents.

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

mpi_rank (type: int) MPI rank the Component should be assigned to
thread (type: int) thread the Component should be assigned to
returns none

setWeight(weight)

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

Parameters

weight (type: float) weight of the Component specified as a float. Weights can have any value, but should be meaningful in the context of the overall simulation.
returns none

Link Class

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

Link(name, latency=None)

Creats a new Link object

Parameters

name (type: string) Name of the link
latency (type: string) default latency for the link, optional. This will be used if no latency is specified in calls to Link.connect() or (Sub)Component.addLink().
returns Link object

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

Connects two ports using the link object.

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.

Parameters

comp (type: Component or SubComponent) Component/SubComponent object that the port is a part of
port (type: string) port to connect to
latency (type: string) latency of link from the perspective of the corresponding Component/SubComponent sending an event. This is optional, and if not specified, the default latency of the link will be used. If no latency is set, either in the call or as a default, the call will fatal.
returns 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 when using an autotmatic partitioning scheme (this attribute is ignored if the self partitioner is used). This must be used with care, as you can easily get into a situation where too many components are on the same rank.

Parameters

returns none

Statistic

A Statistic object is created using the setStatistic() function in a Component or SubComponent.

The following functions are also available to configure the statistics object.

addParam(key, value)

Adds a parameter to the statistics Params

Parameters

key (type: string) name of the parameter
value (type: varies) value of the parameter. This can be almost any Python object and the __str__ method will be called to get a string representation. A list can be passed to this call when the find_array function is used in the class to retrieve the parameters.
returns none

addParams(params)

Adds multiple parameters to the Params object for the Statistic.

Parameters

params (type: dict) a Python dict of key, value pairs. See addParam() description for information about how key and value are used.
returns none

StatisticOutput

The StatisticOutput object is used to configure the output type and options for statistics and is for use with StatisticGroup. For the global statistics output, see the global functions: setStatisticOutput(), setStatisticOutputOption() and setStatisticOutputOptions().

The StatisticOutput object is created using:

StatisticOutput(type, params=None)

Constructor for StatisticOutput

Parameters

type (type: string) type of Statistic output to use
params (type:dict) Diction of key value pairs to be added to the StatisticOutput’s parameters
returns created StatisticOutput object

addParam(key, value)

Adds a parameter to the Params object for the StatisticOutput.

Parameters

key (type: string) name of the parameter
value (type: varies) value of the parameter. This can be almost any Python object and the __str__ method will be called to get a string representation. A list can be passed to this call when the find_array function is used in the class to retrieve the parameters.
returns none

addParams(params)

Adds multiple parameters to the Params object for the StatisticOutput.

Parameters

params (type: dict) a Python dict of key, value pairs. See addParam() description for information about how key and value are used.
returns none

StatisticGroup

The StatisticsGroup object is used to group Statistics object together to be written to the same StatisticOutput object.

NOTE: The StatisticGroup object had limited use in the past and is evolving to include new functionality. This is the proposed functionality of the class and may not be the final API for the object.

A StatisticGroup is creating using:

StatisticGroup(name)

Constructor for StatisticGroup

Parameters

name name of the group
returns created StatisticGroup object

addStatistic(stat)

Adds a statistic to the group.

Parameters

stat Statistic to add to the group
returns none

addComponent(comp)

Add a component to the group

Parameters

comp Component/SubComponent to add to the group
returns none

setOutput(output)

Configure how the Statistics in the group should be written

Parameters

output StatisticOutput object that will record the data
returns none

setFrequency(interval)

Set the frequency or rate (e.g.: “10ms”, “25kHz”) to write out the statistics.

Parameters

interval Interval at which to write out statistics. A rate of “0ns” will cause the output to be written only at the completion of simulation.”
returns none