GENESIS: Documentation

Related Documentation:

• Add Component to DeveloperPackage
• Add Feature to SSP
• Add SWIG Binding to Heccer
• chemesis-3-log
• Create Heccer Test
• Create Solver Object
• Extend GENESIS Functionality
• Integrating with the G-Shell

Extending the Model Container

This document details the steps a developer must go through in order to add an object called PulseGen() to the Model Container. The following steps are performed in order. Files can be found in the root directory of the source directory, which for the Model Container is likely located at: ~/neurospaces_project/model-container/source/snapshots/0.

Add an entry to hierarchy/symbols

The symbols file contains declarations for class types. A new set of declarations must be added for each unique object added to the Model Container. Again, taking the pool entry as a template, we create a new entry for our pulsegen object:

Note: Commented lines were adapted to reflect PulseGen() semantics.

Because we want to have our instances of pulse_gen to be output as PulseGen(), with a capital letter for each word, we declare the pulse_gen with an underscore between each word.

The Details of Extending the Model Container documentation shows how this configuration changes the grammar for the NDF model specification language.

Add the necessary types to the parser

Open the file hierarchy/parser.start file. In this file there is a union, to this union we add a symbol for our PulseGen() object:

The prefix p for pulsegen indicates that this is a pointer.

Creating source files

Now source files which have the appropriate data structures and functions must be created. Here we use the pool.c and pool.h file as a template so we make copies. pool.c is located in the components directory, and pool.h is located in neurospaces/components.

Now change all references of pool to PulseGen() with appropriate case. This is a good starting point as all that’s needed is to determine which parameters and functions you wish to add. Also since we declared our symbol with an underscore, we must retain this format for certain parts of the file.

Our symbol generated a file called pulse_gen_vtable.c which we must properly point to in our PulseGenCalloc{} function.

Again in PulseGenCalloc{} we must retain the underscore when the system performs a SymbolCalloc. This uses a define which is generated from our symbols entry called HIERARCHY_TYPE_symbols_pulse_gen which retains the underscore.

There are two more instances in the file that use HIERARCHY_TYPE_symbols_pulse_gen. Note: If we were to have declared our symbol as pulsegen then the underscore wouldn’t be needed in those cases, however our generated file calls would reference Pulsegen and not PulseGen.

Include your header

You will need to include your new header into a few files with a line such as:

The following files need to have an include:

• symboltable.c
• parser.decl

Adding to compilation

To have your new Pulse object compile into the Model Container you must add to some of the existing build targets in the top level Makefile.am file.

In the target libneurospacesread_a_SOURCES you must add:

The target nobase_include_HEADERS add:

The target libneurospacesread.so add:

After all of this PulseGen() should compile and your new object is ready to use.

Creating a simple test

The Neurospaces Tester framework provides a general purpose framework for regressing testing. The document also gives generic information on how to configure the tester framework. The information below is specific to testing the new PulseGen object. For full understanding it is also recommended to read the document that describes how to create a test for the Heccer package.

To generate a simple test for our new object we need to create two files: one is a test specification file, the other an NDF file that makes use of our new object. We will create a test that performs a simple parameter check.

NDF file

NDF is the file format used for declaring a model in the Model Container. In your source directory they are located in the library directory, after installation they are in the /usr/local/neurospaces/models/library directory.

Again taking an example from the pools library as a template (golgi_ca.ndf), construct a simple Pulse object which sets parameters with reasonable values:

PulseGen()_1 is our instance of a Pulse object. When we load our model it will be callable via this name. We save this file as pulsegen/pulsegen1.ndf inside of the library directory.

Test specification

Test specification files are essentially Perl hashes stored in the tests/specifications directory. We create a new file in this directory with calls to printparameter to check if each parameter is properly set:

Now with both of these saved you can run the test on the command line with the test_harness located in the tests directory. Since there are several tests for the Model Container we only want to run our pulse test. We do this by using the regex option with the test harness, so from the top level source directory we perform:

This produces the output telling us whether PulseGen() has passed or failed the test. The following output has been shortened to extract the parts we are interested in:

In case of such an error, files whose filename matches /tmp/text_model-container*.expected and /tmp/text_model-container*.seen can be inspected to determine the differences between the specified output and test generated output.

This makes it easy to determine where the error is.