GENESIS: Documentation

Related Documentation:

A Simple Scheduler in Perl

Introduction

Both the Model Container and the mathematical solver Heccer are stand-alone GENESIS components. To be useful, these components must be ‘glued’ together and activated correctly, such that they can work together in co-ordination on a single simulation. This is exactly what the Simple Scheduler in Perl (SSP) does. It is currently the standard scheduler for GENESIS. SSP exploits the sophistication of the Perl scripting language to load software components on demand, and activate them from a configuration file. It achieves this by loading dynamically those software components referenced in its configuration. Because the SSP scheduler does not have any computational load, its implementation is very simple and highly configurable. Other configurations will connect SSP to other modeling services or solvers.

In summary SSP:

The SSP Configuration File

Below is a typical configuration file for SSP. It first configures SSP to use the Model Container for internal storage of biological models. It then instructs SSP to load a model called cells/tensizesp.ndf, and to instantiate a solver called Heccer for that part of the model (/tensizesp). The simulation of the model is run using the apply entry in the configuration file.

Note that the order in the configuration file below is alphabetical, not chronological, i.e. entries may specified in any order.

  --- !!perl/hash:SSP  
  apply:  
    simulation:  
      - arguments:  
          - 10  
          - 1  
        method: steps  
      - arguments:  
          - 0.1  
        method: advance  
  models:  
    - modelname: /tensizesp  
      solverclass: heccer  
  name: tensizesp  
  services:  
    neurospaces:  
      initializers:  
        - arguments:  
            -  
              - ./example  
              - -P  
              - tests/cells/tensizesp.ndf  
          method: read  
      module_name: Neurospaces  
  solverclasses:  
    heccer:  
      module_name: Heccer  
      service_name: neurospaces

Below is a slightly enhanced SSP configuration file that performs several tasks and shows how to:

  --- !!perl/hash:SSP  
  apply:  
    simulation:  
      - arguments:  
          - 1000  
          - 1  
        method: steps  
      - arguments:  
          - 0.1  
        method: advance  
  models:  
    - modelname: /pool1_feedback1  
      solverclass: heccer  
  name: pool1_feedback1  
  outputclasses:  
    double_2_ascii:  
      constructor: Experiment::Output  
      module_name: Experiment  
  outputs:  
    - component_name: ’/pool1_feedback1/segments/main[0]’  
      field: Vm  
      outputclass: double_2_ascii  
    - component_name: ’/pool1_feedback1/segments/main[0]/Ca_pool’  
      field: Ca  
      outputclass: double_2_ascii  
  services:  
    neurospaces:  
      initializers:  
        - arguments:  
            -  
              - ./tests/perl/pool1-feedback1  
              - -P  
              - tests/cells/pool1_feedback1.ndf  
          method: read  
      module_name: Neurospaces  
  solverclasses:  
    heccer:  
      constructor_settings:  
        configuration:  
          reporting:  
            granularity: 100  
            tested_things: 6225920  
        dStep: 1e-06  
      module_name: Heccer  
      service_name: neurospaces

Working with SSP

SSP is started using the command “ssp”. In the absence of any options a description of how to use the component is generated along with a list of options recognized at startup.

The comand “ssp_directory” calls SSP for each schedule in a given directory, with the options “set-name” and “set-outputclass-filename” (see below).

Starting SSP

When starting SSP, you must specify a schedule template (a filename) for SSP to read. SSP will then read the file, modify it according to command line options, convert it to a real schedule, and then execute the schedule. Currently, the most important options are:

Both of these options allow a user to track the correspondence between the schedule filename, the internal schedule name, and the filename of the simulation output file.

SSP Schedules

A schedule is a hierarchical enumeration of “keys” that tell SSP to do certain things. Amongst other contents, a SSP schedule must define:

If some of these are not defined in the schedule, SSP will assume defaults.

There is one special key description. It is available at all levels of the hierarchy, but is ignored by SSP. This allows the inclusion of comments in a SSP file.

The SSP schedules are in YAML format (which is white space sensitive, see further below). The basics of this format are that it uses dashes for an order sensitive enumeration of items, and it uses colons for an order insensitive enumeration of key–value pairs. Each entry is newline terminated.

SSP relies on external “services” and “engines”. In computational neuroscience parlance, the engines are solvers, and the services contain the model that needs to be computed by the solvers. So SSP tells the engines when to do something, but the services tell the engines what has to be done. Currently the services are information services, but that is subject to change (e.g. it is currently unclear if a discrete event scheduler must be specified as a service or as an engine, from semantics it is the former, from software architecture it is the latter).

Important Keys

We now give a non-exhaustive list of keys (about 70% of the currently defined SSP keys are covered here).

apply

Contains a set of subkeys that define how to run a schedule. Each subkey contains an array of ‘methods’ that have to be executed. The most important subkey is called simulation, which defines the method to use to run the simulation and the number of update steps to perform during the simulation.

    simulation:  
      - arguments:  
          - 1000  
          - 1  
        description: run 1000 steps of the simulation.  
        method: steps  
      - arguments:  
          - 0.1  
        description: advance the simulation by 0.1s.  
        method: advance

inputclasses

This option allows you to use external simulation objects with your model. A simulation object can be something compiled into the Experiment component, or completely stand alone. Here in this example, we load the perectclamp object which has been compiled into the Experiment component. The options attribute allows us to set parameters for the object upon initialization.

inputclasses:  
  perfectclamp:  
    module_name: Experiment  
    options:  
      filename: /usr/local/neurospaces/models/library/event_data/soma_vm_trace.yml  
      name: purkinje cell perfect clamp  
    package: Experiment::PerfectClamp

PerfectClamp is part of the Experiment component and takes two options, one for an identifier and one for a filename which points to a file containing event data.

inputs

The inputs attribute allows the user to set an input for a simulation object that has been loaded via the inputclasses attribute. Here in this example an output element along with the intended output parameter are given for a PerfectClamp{} object.

inputs:  
  - component_name: /Purkinje/segments/soma  
    field: Vm  
    inputclass: perfectclamp

This inputs block tells SSP to connect the PerfectClamp to the component /Purkinje/segments/soma via the membrane potential Vm.

services

Contains a definition of all the services, and the method to instantiate these services. For the neurospaces service, the most important methods are ’read’, to read a model specified in a neurospaces description file, and ’load’, to load a model specified in an external format (only GENESIS .p files are supported at present). Additional options like e.g. a shrinkage correction factor, or a spines distribution definition, can be specified here.

solverclasses

The solver classes, and their relationship to the services. E.g. this key tells SSP to load in the Heccer component, and, whenever it is used, it must talk to neurospaces to figure out what needs to be simulated. Solver specific settings, e.g. the time step, are specified here.

models

An enumeration of the parts of the model to simulate, and what solverclasses to use, for this part of the model. Model parts not listed are not simulated. For each entry of the enumeration, i.e. for each part of the model that will be simulated, you have the possibility of setting a number of parameters, right before the engines get to see the model. The subkeys in an entry of the enumeration to do that are:

name

The internal name of the schedule. It is a good idea to maintain a clear correspondence between the internal name and the filename of the schedule.

outputclasses

The output classes specify the type of outputs. Internally, output classes are the same as solver classes, but they come in a separate key for interfacing with other software. Options for the output class can be specified here (e.g. a filename for output).

outputs

The actual outputs of the simulation are defined here. This key is an enumeration of elements and fields that are present in the model. The addressing scheme to get to these fields and elements is defined by the model service. So for GENESIS, “/” is the element separator, and “->” is the field separator.

version

Defines the version number the schedule complies to. If omitted its value is “0”, the current schedule protocol version at this time.

Creating and Changing SSP Schedules

The best way to create a new SSP schedule, is to modify an exising one as required. Small Perl scripts can be used to generate multiple SSP schedules for batch mode simulations. For example:

   ssp_directory > schedules.out 2>&1 --schedules-directory schedules/ --verbose &

The progress of multiple simulations can then be monitored with:

   tail -f schedules.out

SSP schedules are specified in YAML format, an easy to understand format for na´ve computer users. As white space is used to structure the content of information, YAML is white space sensitive. Indentation is used to define the hierarchical depth of an entry, while newlines are used to terminate an entry. This results in a very easy to understand format. All the examples given above employ YAML syntax. Importantly, by far the majority of scripting languages have built-in support for YAML data structures.

The SSP Interface

To properly interface with SSP you need to use these perl subroutines: