Related Documentation:
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:
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 |
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).
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:
Overwrite the schedule name with the name of the file that contains the schedule
Overwrite the outputclass filename with something derived from the name of the file that contains the schedule.
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.
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).
We now give a non-exhaustive list of keys (about 70% of the currently defined SSP keys are covered here).
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 |
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.
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.
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.
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.
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:
Allows parameters to be set at a granular level, i.e. the level of the model that the engines will get to see. For example:
runtime_parameters:
- component_name: /Purkinje/segments/soma description: current injection into the somatic compartment. field: INJECT value: 0.2e-9 |
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.
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).
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.
Defines the version number the schedule complies to. If omitted its value is “0”, the current schedule protocol version at this time.
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.
To properly interface with SSP you need to use these perl subroutines: