Python File Format

Introduction

Beginning with version 4.0 of SST, an Python-based format was developed for configuring SST Simulations.

This script-based configuration has multiple benefits, including allowing configuration files to be much smaller and simpler, as well as less error-prone.

NOTE: The minimum version of Python supported is version 2.6 (Python 3.0 and onwards is not supported).

Python Functionality

All Python-based SST functionality is provided in the sst Python module which is provided within the SST application. A configuration file must import this module to configure SST.

#!python
import sst

Module Methods


Program Options

SST program options may be retrieved via sst.getProgramOptions(), which returns a dictionary of the current status of the program options. A single program option may be changed by calling sst.setProgramOption(name, value), and multiple options may be changed at once by passing a dictionary to sst.setProgramOptions().

Available program options include:

Name Prefixes

To assist with automatically naming components in a hierarchical simulation, a user may call pushNamePrefix(name) and popNamePrefix() to push and pop a name onto a prefix string that will be prepended to the names of any subsequently created components or links.

For example:

#!python
sst.pushNamePrefix("n0")
sst.Component("MyNode", "mycomp.node")
sst.pushNamePrefix("c0")
sst.Component("core", "mycomp.core")
sst.Component("memory", "mycomp.memory")
sst.popNamePrefix()
sst.Component("test", "mycomp.test")
sst.popNamePrefix()
sst.Component("otherComp", "mycomp.test")

Will produce the following Component names:

n0.MyNode
n0.c0.core
n0.c0.memory
n0.test
otherComp

In order to retrieve the full name of a component, use the getFullName() method on the Component object.

Exiting Simulation

If the config script runs into an error condition, it may call sst.exit() to signal that it wishes SST to terminate.

Components


An SST Component is a class in the sst module. Its constructor takes the name of the component, as well as its type.

#!python
comp = sst.Component("comp", "simpleComponent.simpleComponent)

Component parameters are specified by passing a name and value to addParam(), or a dictionary of parameters to addParams().

Component Methods


Links are classes in the sst module as well. They are created with just a name.

#!python
link = sst.Link("mylink")

To connect two components via a link, one can either pass the link object to each component’s addLink() method, or call connect() on the link object, passing two tuples, each containing a component, it’s port name, and link latency.

The following two examples are equivalent:

#!python
compA = sst.Component("Comp A", "dummy.Component")
compB = sst.Component("Comp B", "dummy.Component")
link = sst.Link("mylink")

compA.addLink(link, "myPort", "10ns")
compB.addLink(link, "myPort", "10ns")
#!python
compA = sst.Component("Comp A", "dummy.Component")
compB = sst.Component("Comp B", "dummy.Component")
link = sst.Link("mylink")

link.connect((compA, "myPort", "10ns"), (compB, "myPort", "10ns"))

Statistics


Statistics has 2 major sections for setup (General Statistics Setup and Statistic Enables):

General Statistics Setup

General setup involves setting the Statistic Load Level and setting the Statistic Output.

Statistic Load Level

To set the Statistic Load Level:

sst.setStatisticLoadLevel(x)

where x = unsigned integer value (0 = all Statistics are disabled)

Note: if Statistic Load Level is not set, all statistics will be disabled

Statistic Output

To set the Statistic Output and its parameters:

sst.setStatisticOutput("outputname", {"param_1" : "value_1",
                                      "param_n" : "value_n" 
                                      } )

sst.setStatisticOutputOptions({"param_1" : "value_1", 
                               "param_n" : "value_n" 
                               } )

sst.setStatisticOutputOption("param", "value")

Note: If Statistic Output is not set, the default will be “sst.statOutputConsole”

Example General Statistics Setup
sst.setStatisticLoadLevel(7)
sst.setStatisticOutput("sst.statOutputCSV", {"filepath" : "./TestOutput.csv",
                                             "separator" : ", " } )
sst.setStatisticOutputOption("outputsimtime, "1")
sst.setStatisticOutputOption("outputrank", "1")

Statistics Enables

Statistics can be enabled multiple ways:

When a statistic is enabled, the collection type of statistic (accumulator, histogram, etc) can be identified along with any of that statistic type parameters.

NOTE: Enabling statistics must occur after the related components are created in the python file.

All statistic enable functions will take a parameters list. This list is optional but it is recommended. Four parameters are always available to set the collection type, the output rate, and a start and stop time:

All other parameters are dependent upon the Statistic Collection type selected.

Statistics Enables on the Component
compA.enableAllStatistics({"param_1" : "value_1", 
                           "param_n" : "value_n" })

compA.enableStatistics(["statistic_name_1", 
                        "statistic_name_2", 
                        "statistic_name_n"], 
                       {"param_1" : "value_1", 
                        "param_n" : "value_n" })
SST Level Statistics Enables
sst.enableAllStatisticsForAllComponents({"param_1" : "value_1", 
                                         "param_n" : "value_n" })

sst.enableAllStatisticsForComponentName("Component_Name",
                                       {"param_1" : "value_1", 
                                        "param_n" : "value_n" })

sst.enableStatisticForComponentName("Component_Name",
                                    "Statistic_Name", 
                                   {"param_1" : "value_1", 
                                    "param_n" : "value_n" })

sst.enableAllStatisticsForComponentType("Component_Type",
                                       {"param_1" : "value_1", 
                                        "param_n" : "value_n" })

sst.enableStatisticForComponentType("Component_Type",
                                    "Statistic_Name", 
                                   {"param_1" : "value_1", 
                                    "param_n" : "value_n" })
Statistics Enables Examples
compA = sst.Component("statTestA", "ElementExample.StatisticsComponent_1")
compB = sst.Component("statTestB", "ElementExample.StatisticsComponent_2")
compC = sst.Component("statTestC", "ElementExample.StatisticsComponent_3")
compD = sst.Component("statTestD", "ElementExample.StatisticsComponent_3")
compE = sst.Component("statTestE", "ElementExample.StatisticsComponent_3")
compF = sst.Component("statTestF", "ElementExample.StatisticsComponent_4")

compA.enableStatistics(["statname1", "statname4"], 
                       {"type" : "sst.AccumulatorStatistic", 
                        "rate" : "100 ns", 
                        "stopat" : "800 ns" })

compB.enableAllStatistics({"type" : "sst.AccumulatorStatistic", 
                           "rate" : "500 events" })

sst.enableAllStatisticsForComponentType("ElementExample.StatisticsComponent3", 
                                       {"type":"sst.HistogramStatistic",
                                        "minvalue" : "10",
                                        "binwidth" : "10", 
                                        "numbins"  : "41", 
                                        "IncludeOutOfBounds" : "1"})

sst.enableAllStatisticsForComponentName("StatTestF")

SST Command-line Arguments


The string passed on the SST command-line argument “model-options” is parsed and becomes available to the model configuration file via the standard Python command-line argument mechanism of sys.argv.

For example, if foo.py contains:

#!python
import sst
import sys
print sys.argv
sst.ext()

This could be the result:

$ sst --model-options="-h -x foo" foo.py
['sstsim.x', '-h', '-x', 'foo']

Examples

3-component (CPU, Cache, Memory)

Taken from MemHierarchy/test/sdl-1.py:

#!python
import sst

memDebug = 0
coherency = "MSI"
lat = "1ns"
buslat = "50ps"

sst.setProgramOption("timebase", "1ns")

cpu = sst.Component("cpu", "memHierarchy.trivialCPU")
cpu.addParams({"workPerCycle": 1000, "commFreq": 100, "memSize": 0x1000, "do_write": 1, "num_loadstore": 1000})

l1cache = sst.Component("l1cache", "memHierarchy.Cache")
l1cache.addParams({
        "cache_frequency": "2 GHz",
        "cache_size": "2 KB",
        "associativity": 4,
        "cache_line_size" : 64,
        "coherence_protocol": coherency,
        "replacement_policy": "lru",
        "access_latency_cycles" : 4,
        "low_network_links": 1,
        "L1" : 1,
        "debug" : memDebug,
        "statistics" : 1})

memory = sst.Component("memory", "memHierarchy.MemController")
memory.addParams({
        "access_time" : "1000 ns",
        "mem_size" : 512,
        "coherence_protocol": coherency,
        "clock" : "1 GHz",
        "debug" : memDebug } )

cpuLink = sst.Link("cpu_cache_link")
cpuLink.connect((cpu, "mem_link", lat), (l1cache, "high_network_0", lat))

link = sst.Link("cache_mem_link")
link.connect((l1cache, "low_network_0", buslat), (memory, "direct_link", buslat))

Element Library Extensions

Element library writes may choose to add functionality to the Python environment for configuration. For example, the Merlin element library does this to simplify creation of large, simple networks. This additional functionality would show up under a sub-module to SST. For example: import sst.merlin.