GENESIS: Documentation

SSPy developer document

Introduction

SSPy is a framework that combines the various part of GENESIS together into a usable state for performing simulations. This document outlines some of the internal frameworks employed so that a developer can extend SSPy by way of the plugin architecture or even modifications to core code.

Prerequisites

In order to run SSPy you must first install PyYAML to handle YAML files and dictionaries.
Python version 2.5 or greater is required
Python SWIG bindings must be compiled for each component of GENESIS 3. This can be automatically handled via the developer scripts for your system installation.

Configuration Files

Since SSPy is directly compatible with SSP all information present in the section titled ”The SSP Configuration File” apply here.

Plugin Structure

The plugin structure is designed to play on the strengths of the imp module and Python’s duck typing feature. A plugin is defined as directory with a Python module that contains specific class declarations, and an accompanying configuration file.

Configuration File

There are four different types of plugins, each is defined by a differently named configuration file:

solvers.yml for Solver plugins.
service.yml for Modeling services.
output.yml for Output objects.
input.yml for Input objects.

The configuration file is in YAML format with the following keys present:

name: A unique identifier for the plugin. This will be what will is inserted into the SSPy configuration file to indicate which plugin to use for your simulation.
label: A human readable name for the plugin. Purpose of such is so that when building GUI’s and deriving publications, the human readable name is inserted where appropriate.
description: Like the label tag, this provides a human readable description for use in derived output.
version: The version number or version identifier of the plugin. This should make possible the ability to set up a simulation configuration using two different solvers of the same type, with the same parameters, but different versions, thus allowing you to compare output.
file or source: This is the file containing the required declaration class within the plugins directory.
module : Contains the declaration class for the plugin. It is identical to the file and source tag only it is the module name, which is the python file without the ”.py” suffix.
services: Found in solver plugin configurations. A list of compatible services. If a user tries to pass a service to the solver that is not in this compatibility list an exception is thrown.

Here is an example solver.yml file for Heccer:

---
name: heccer
label: Heccer Solver
version: 0.1
description: This is the SSPy object for driving the Heccer solver
file: heccer.py
source: heccer.py
module: heccer
services:
  - name: heccer_intermediary
    version: 0.1
  - name: model_container
    version: 0.1

Declaration

Each plugin module that is given in the configuration file options for file, source, or module must have the corresponding classes:

Solver for solvers.
Service for modeling services.
Output for output objects.
Input for input objects.

so long as the correct methods are filled in with the appropriate functionality and given the required arguments and return types, the classes can be loaded interchangeably and used to drive any combination of simulations (provided a solver is compatible with the declared service and protocols).

Services

Modeling services must allow users to load a model into memory and allow accessibility to element lists and coordinates. From the plugins API it should also be possible to set model parameters.

A modeling service class must have the following structure:

class Service:
  def __init__(self, name="Untitled Model Container", plugin=None, arguments=None, verbose=False)
  def Load(self, modelfile):
  def GetCore(self):
  def GetName(self):
  def GetPluginName(self):
  def GetType(self):
  def GetArguments(self):
  def GetCoordinates(self):
  def GetElements(self):
  def SetParameter(self, path, field, value):

Solver

Solver plugins are simulation objects that are scheduled and perform time steps during a simulation. They have logic to connect to services, set the simulation time step, and report simulation status.

A solver plugin class must have the following structure:

class Solver:
  def __init__(self,  name="Untitled solver", plugin=None, constructor_settings=None, verbose=False):
  def Initialize(self):
  def GetCore(self):
  def GetName(self):
  def SetTimeStep(self, time_step):
  def GetTimeStep(self):
  def GetType(self):
  def SetConfiguration(self, config):
  def New(self, modelname, filename):
  def Advance(self):
  def Compile(self):
  def IsCompiled(self):
  def Connect(self, service=None):
  def SetModelName(self, model_name):
  def SetGranularity(self, granularity):
  def Deserialize(self, filename):
  def DeserializeState(self, filename):
  def Finish(self):
  def Name(self):
  def SetSolverField(self, field, value):
  def GetSolverField(self, field):
  def Serialize(self, filename):
  def SerializeState(self, filename):
  def Output(self, serial, field):
  def Run(self, time):
  def Step(self, time=None):
  def Report(self):
  def Steps(self, steps):

Input

An input plugin is a simulation object that is scheduled and performs time steps during a simulation.

An input plugin class must have the following structure:

class Input:
  def __init__(self, name="Untitled PerfectClamp", plugin=None, arguments=None, verbose=False):
  def Format(self):
  def GetName(self):
  def Name(self):
  def GetTimeStep(self):
  def SetTimeStep(self, time_step):
  def GetType(self):
  def AddInput(self, name, field):
  def SetInputs(self, inputs):
  def SetCommandVoltage(self, voltage):
  def Advance(self):
  def Connect(self, solver):
  def Finish(self):
  def Initialize(self):
  def Compile(self):
  def New(self):
  def Step(self, time):
  def Report(self):

Output

An output plugin is a simulation object that is scheduled and performs time steps during a simulation. The primary purpose of an output object is to output data during a simulation.

An input plugin class must have the following structure:

class Output:
  def __init__(self,  name="Untitled Output", plugin=None, filename=None, arguments=None, verbose=False):
  def Compile(self):
  def Finish(self):
  def GetName(self):
  def Name(self):
  def SetOutputs(self, outputs):
  def AddOutput(self, name, field):
  def GetTimeStep(self):
  def SetTimeStep(self, time_step):
  def GetType(self):
  def Finish(self):
  def Initialize(self):
  def Connect(self, solver):
  def Step(self, time=None):
  def Report(self):
  def SetMode(self, mode=None):
  def SetResolution(self, res=None):
  def SetFormat(self, strfmt=None):
  def SetFilename(self, filename=None):
  def GetFilename(self):