MOOSE¶

What is MOOSE and what is it good for?¶

MOOSE is the Multiscale Object-Oriented Simulation Environment. It is designed to simulate neural systems ranging from subcellular components and biochemical reactions to complex models of single neurons, circuits, and large networks. MOOSE can operate at many levels of detail, from stochastic chemical computations, to multicompartment single-neuron models, to spiking neuron network models.

Multiple scales can be modelled and simulated in MOOSE

MOOSE is multiscale: It can do all these calculations together. One of its major uses is to make biologically detailed models that combine electrical and chemical signaling.

MOOSE is object-oriented. Biological concepts are mapped into classes, and a model is built by creating instances of these classes and connecting them by messages. MOOSE also has numerical classes whose job is to take over difficult computations in a certain domain, and do them fast. There are such solver classes for stochastic and deterministic chemistry, for diffusion, and for multicompartment neuronal models.

MOOSE is a simulation environment, not just a numerical engine: It provides data representations and solvers (of course!), but also a scripting interface with Python, graphical displays with Matplotlib, PyQt, and OpenGL, and support for many model formats. These include SBML, NeuroML, GENESIS kkit and cell.p formats, HDF5 and NSDF for data writing.

Installation¶

Use pre-built packages¶

Linux¶

We recommend that you use our repositories hosted at Open Build Service. We have build packages for most linux distributions. Visit this page to pick your distribution and follow instructions.

Note

moogli (tool to visualize network activity) is not available for CentOS-6.

MacOSX¶

MacOSX support is not complete yet. The GUI does not work due to compatibility isses with PyQt package available on homebrew See status of this ticket. Python interface is available (latest version 3.1.2. Status) and can be installed on MaxOSX using homebrew

$ brew install homebrew/science/moose

Building MOOSE¶

In case your distribution is not listed on our repository page , or if you want to build the lastest development code, read on.

First, you need to get the source code. You can use git (clone the repository) or download snapshot of github repo by clicking on this link.:

$ git clone https://github.com/BhallaLab/moose --depth 100

This will create folder called “moose” with source code. Or,

$ wget https://github.com/BhallaLab/moose/archive/master.zip
$ unzip master.zip

You can download other released versions from here.

Install dependencies¶

Depending on your operating system, names of following packages may vary.

Python interface for core MOOSE API (pymoose)¶

Required
- Python For building the MOOSE Python bindings
- Python development headers and libraries, e.g. python-dev or python-devel
- NumPy ( >= 1.6.x) For array interface, e.g. python-numpy or numpy
Optional
- NetworkX (1.x). Layout is of chemical models is computed using networkx.
- Matplotlib (>=1.1.x) For plotting simulation results
- python-libsbml For reading and writing chemical models in SBML format.

Most of the dependencies can be installed using package manager.

On Debian/Ubuntu

$ sudo apt-get install libhdf5-dev cmake libgsl0-dev libpython-dev python-numpy

Note

Ubuntu 12.04 does not have required version of gsl (required 1.16 or higher, available 1.15). On Ubuntu 16.04, package name is libgsl-dev.

On CentOS/Fedora/RHEL/Scientific Linux

$ sudo yum install hdf5-devel cmake libgsl-dev python-devel python-numpy

On SUSE/OpenSUSE

$ sudo zypper install hdf5-devel cmake libgsl-dev python-devel python-numpy

build moose¶

$ cd /to/moose/source/code
$ mkdir _build
$ cd _build
$ cmake  ..
$ make -j2    # using 2 core to build MOOSE
$ ctest --output-on-failure  # optional
$ sudo make install

This will build MOOSE’s python extention, ctest will run few tests to check if build process was successful.

Note

To install MOOSE into non-standard directory, pass additional argument -DCMAKE_INSTALL_PREFIX=path/to/install/dir to cmake

$ cmake -DCMAKE_INSTALL_PREFIC=$HOME/.local ..

To use different version of python

$ cmake -DPYTHON_EXECUTABLE=/opt/python3/bin/python3 ..

After that installation is pretty easy

$ sudo make install

If everything went fine, you should be able to import moose in python shell.

>>> import moose

Graphical User Interface (GUI)¶

MOOSE-gui can be launched by running the following command

$ moosegui

Below are packages which you may need to install to be able to launch MOOSE Graphical User Interface.

Required:
- PyQt4 (4.8.x)

On Ubuntu/Debian, these can be installed with

$ sudo apt-get install python-qt4

On CentOS/Fedora/RHEL

$ sudo yum install python-qt4

Note

If you have installed moose package, then GUI is launched by running following commnad:

$ moosegui

Building moogli¶

moogli is subproject of MOOSE for visualizing models. More details can be found here.

Moogli is part of moose package. Building moogli can be tricky because of multiple depednecies it has.

Required
- OSG (3.2.x) For 3D rendering and simulation of neuronal models
- Qt4 (4.8.x) For C++ GUI of Moogli

To get the latest source code of moogli, click on this link.

Moogli depends on OpenSceneGraph (version 3.2.0 or higher) which may not be easily available for your operating system. For this reason, we distribute required OpenSceneGraph with moogli source code.

Depending on distribution of your operating system, you would need following packages to be installed.

On Ubuntu/Debian

$ sudo apt-get install python-qt4-dev python-qt4-gl python-sip-dev libqt4-dev

On Fedora/CentOS/RHEL

$ sudo yum install sip-devel PyQt4-devel qt4-devel libjpeg-devel PyQt4

On openSUSE

$ sudo zypper install python-sip python-qt4-devel libqt4-devel python-qt4

After this, building and installing moogli should be as simple as

$ cd /path/to/moogli
$ mkdir _build
$ cd _build
$ cmake ..
$ make
$ sudo make install

If you run into troubles, please report it on our github repository.

Quick Start¶

MOOSE GUI: Graphical interface for MOOSE¶

Upinder Bhalla, Harsha Rani, Aviral Goel

MOOSE is the Multiscale Object-Oriented Simulation Environment. It can do all these calculations together. One of its major uses is to make biologically detailed models that combine electrical and chemical signaling.

This document describes the salient features of the GUI and Kinetickit of MOOSE.

Contents¶

Introduction¶

The Moose GUI currently allow you work on chemical models using a interface. This document describes the salient features of the GUI

Interface¶

The interface layout consists of a menu bar and two views, editor view and run view.

Menu Bar¶

The menu bar appears at the top of the main window. In Ubuntu 12.04, the menu bar appears only when the mouse is in the top menu strip of the screen. It consists of the following options -

File¶

The File menu option provides the following sub options

New - Create a new chemical signalling model.
Load Model - Load a chemical signalling or compartmental neuronal model from a file.
Paper_2015_Demos Model - Loads and Runs chemical signalling or compartmental neuronal model from a file.
Recently Loaded Models - List of models loaded in MOOSE. (Atleast one model should be loaded)
Connect BioModels - Load chemical signaling models from the BioModels database.
Save - Saves chemical model to Genesis/SBML format.
Quit - Quit the interface.

View¶

View menu option provides the following sub options -

Editor View - Switch to the editor view for editing models.
Run View - Switch to run view for running models.
Dock Widgets - Following dock widgets are provided

Python - Brings up a full fledged python interpreter integrated with MOOSE GUI. You can interact with loaded models and load new models through the PyMoose API. The entire power of python language is accessible, as well as MOOSE-specific functions and classes.

Edit - A property editor for viewing and editing the fields of a selected object such as a pool, enzyme, function or compartment. Editable field values can be changed by clicking on them and overwriting the new values. Please be sure to press enter once the editing is complete, in order to save your changes.

SubWindows - This allows you to tile or tabify the run and editor views.

Help¶

About Moose - Version and general information about MOOSE.
Built-in documentation - Documentation of MOOSE GUI.
Report a bug - Directs to the github bug tracker for reporting bugs.

Editor View¶

The editor view provides two windows -

Model Editor - The model editor is a workspace to edit and create models. Using click-and-drag from the icons in the menu bar, you can create model entities such as chemical pools, reactions, and so on. A click on any object brings its property editor on screen (see below). In objects that can be interconnected, a click also brings up a special arrow icon that is used to connect objects together with messages. You can move objects around within the edit window using click-and-drag. Finally, you can delete objects by selecting one or more, and then choosing the delete option from the pop-up menu. The links below is the screenshots point to the details for the chemical signalling model editor.

Chemical Signalling Model Editor

Property Editor - The property editor provides a way of viewing and editing the properties of objects selected in the model editor.

Property Editor

Run View¶

The Run view, as the name suggests, puts the GUI into a mode where the model can be simulated. As a first step in this, you can click-and-drag an object to the graph window in order to create a time-series plot for that object. For example, in a chemical reaction, you could drag a pool into the graph window and subsequent simulations will display a graph of the concentration of the pool as a function of time. Within the Run View window, the time-evolution of the simulation is displayed as an animation. For chemical kinetic models, the size of the icons for reactant pools scale to indicate concentration. Above the Run View window, there is a special tool bar with a set of simulation controls to run the simulation.

Simulation Controls¶

Simulation Control

This panel allows you to control the various aspects of the simulation.

Run Time - Determines duration for which simulation is to run. A simulation which has already run, runs further for the specified additional period.
Reset - Restores simulation to its initial state; re-initializes all variables to t = 0.
Stop - This button halts an ongoing simulation.
Current time - This reports the current simulation time.
Preferences - Allows you to set simulation and visualization related preferences.

Plot Widget¶

Getting started with python scripting for MOOSE¶

Introduction
Importing MOOSE and accessing built-in documentation
Setting the properties of elements: accessing fields
Putting them together: setting up connections
Scheduling
Running the simulation
Some more details
Moving on

Introduction ¶

This document describes how to use the moose module in Python scripts or in an interactive Python shell. It aims to give you enough overview to help you start scripting using MOOSE and extract farther information that may be required for advanced work. Knowledge of Python or programming in general will be helpful. If you just want to simulate existing models in one of the supported formats, you can fire the MOOSE GUI and locate the model file using the File menu and load it. The GUI is described in separate document. If you are looking for recipes for specific tasks, take a look at cookbook. The example code in the boxes can be entered in a Python shell.

Importing MOOSE and accessing built-in documentation ¶

In a python script you import modules to access the functionalities they provide.

>>> import moose

This makes the moose module available for use in Python. You can use Python’s built-in help function to read the top-level documentation for the moose module

>>> help(moose)

This will give you an overview of the module. Press q to exit the pager and get back to the interpreter. You can also access the documentation for individual classes and functions this way.

>>> help(moose.connect)

To list the available functions and classes you can use dir function [1].

>>> dir(moose)

MOOSE has built-in documentation in the C++-source-code independent of Python. The moose module has a separate doc function to extract this documentation.

>>> moose.doc(moose.Compartment)

The class level documentation will show whatever the author/maintainer of the class wrote for documentation followed by a list of various kinds of fields and their data types. This can be very useful in an interactive session.

Each field can have its own detailed documentation, too.

>>> moose.doc('Compartment.Rm')

Note that you need to put the class-name followed by dot followed by field-name within quotes. Otherwise, moose.doc will receive the field value as parameter and get confused.

Creating objects and traversing the object hierarchy¶

Different types of biological entities like neurons, enzymes, etc are represented by classes and individual instances of those types are objects of those classes. Objects are the building-blocks of models in MOOSE. We call MOOSE objects element and use object and element interchangeably in the context of MOOSE. Elements are conceptually laid out in a tree-like hierarchical structure. If you are familiar with file system hierarchies in common operating systems, this should be simple.

At the top of the object hierarchy sits the Shell, equivalent to the root directory in UNIX-based systems and represented by the path /. You can list the existing objects under / using the le function.

>>> moose.le()
Elements under /
/Msgs
/clock
/classes
/postmaster

Msgs, clock and classes are predefined objects in MOOSE. And each object can contain other objects inside them. You can see them by passing the path of the parent object to le

>>> moose.le('/Msgs')
Elements under /Msgs[0]
/Msgs[0]/singleMsg
/Msgs[0]/oneToOneMsg
/Msgs[0]/oneToAllMsg
/Msgs[0]/diagonalMsg
/Msgs[0]/sparseMsg

Now let us create some objects of our own. This can be done by invoking MOOSE class constructors (just like regular Python classes).

>>> model = moose.Neutral('/model')

The above creates a Neutral object named model. Neutral is the most basic class in MOOSE. A Neutral element can act as a container for other elements. We can create something under model

>>> soma = moose.Compartment('/model/soma')

Every element has a unique path. This is a concatenation of the names of all the objects one has to traverse starting with the root to reach that element.

>>> print soma.path
/model/soma

The name of the element can be printed, too.

>>> print soma.name
soma

The Compartment elements model small sections of a neuron. Some basic experiments can be carried out using a single compartment. Let us create another object to act on the soma. This will be a step current generator to inject a current pulse into the soma.

>>> pulse = moose.PulseGen('/model/pulse')

You can use le at any point to see what is there

>>> moose.le('/model')
Elements under /model
/model/soma
/model/pulse

And finally, we can create a Table to record the time series of the soma’s membrane potential. It is good practice to organize the data separately from the model. So we do it as below

>>> data = moose.Neutral('/data')
>>> vmtab = moose.Table('/data/soma_Vm')

Now that we have the essential elements for a small model, we can go on to set the properties of this model and the experimental protocol.

Setting the properties of elements: accessing fields ¶

Elements have several kinds of fields. The simplest ones are the value fields. These can be accessed like ordinary Python members. You can list the available value fields using getFieldNames function

>>> soma.getFieldNames('valueFinfo')

Here valueFinfo is the type name for value fields. Finfo is short form of field information. For each type of field there is a name ending with -Finfo. The above will display the following list

 ('this',
'name',
'me',
'parent',
'children',
'path',
'class',
'linearSize',
'objectDimensions',
'lastDimension',
'localNumField',
'pathIndices',
'msgOut',
'msgIn',
'Vm',
'Cm',
'Em',
'Im',
'inject',
'initVm',
'Rm',
'Ra',
'diameter',
'length',
'x0',
'y0',
'z0',
'x',
'y',
'z')

Some of these fields are for internal or advanced use, some give access to the physical properties of the biological entity we are trying to model. Now we are interested in Cm, Rm, Em and initVm. In the most basic form, a neuronal compartment acts like a parallel RC circuit with a battery attached. Here R and C are resistor and capacitor connected in parallel, and the battery with voltage Em is in series with the resistor, as shown below:

Passive neuronal compartment

The fields are populated with some defaults.

>>> print soma.Cm, soma.Rm, soma.Vm, soma.Em, soma.initVm
1.0 1.0 -0.06 -0.06 -0.06

You can set the Cm and Rm fields to something realistic using simple assignment (we follow SI unit) [2].

>>> soma.Cm = 1e-9
>>> soma.Rm = 1e7
>>> soma.initVm = -0.07

Instead of writing print statements for each field, you could use the utility function showfield to see that the changes took effect

>>> moose.showfield(soma)
[ /soma[0] ]
diameter         = 0.0
Ra               = 1.0
y0               = 0.0
Rm               = 10000000.0
numData          = 1
inject           = 0.0
initVm           = -0.07
Em               = -0.06
y                = 0.0
numField         = 1
path             = /soma[0]
dt               = 5e-05
tick             = 4
z0               = 0.0
name             = soma
Cm               = 1e-09
x0               = 0.0
Vm               = -0.06
className        = Compartment
length           = 0.0
Im               = 0.0
x                = 0.0
z                = 0.0

Now we can setup the current pulse to be delivered to the soma

>>> pulse.delay[0] = 50e-3
>>> pulse.width[0] = 100e-3
>>> pulse.level[0] = 1e-9
>>> pulse.delay[1] = 1e9

This tells the pulse generator to create a 100 ms long pulse 50 ms after the start of the simulation. The amplitude of the pulse is set to 1 nA. We set the delay for the next pulse to a very large value (larger than the total simulation time) so that the stimulation stops after the first pulse. Had we set pulse.delay = 0 , it would have generated a pulse train at 50 ms intervals.

Putting them together: setting up connections ¶

In order for the elements to interact during simulation, we need to connect them via messages. Elements are connected to each other using special source and destination fields. These types are named srcFinfo and destFinfo. You can query the available source and destination fields on an element using getFieldNames as before. This time, let us do it another way: by the class name

>>> moose.getFieldNames('PulseGen', 'srcFinfo')
('childMsg', 'output')

This form has the advantage that you can get information about a class without creating elements of that class.

Here childMsg is a source field that is used by the MOOSE internals to connect child elements to parent elements. The second one is of our interest. Check out the built-in documentation here

>>> moose.doc('PulseGen.output')
PulseGen.output: double - source field
Current output level.

so this is the output of the pulse generator and this must be injected into the soma to stimulate it. But where in the soma can we send it? Again, MOOSE has some introspection built in.

>>> soma.getFieldNames('destFinfo')
('parentMsg',
 'setThis',
 'getThis',
   ...
 'setZ',
 'getZ',
 'injectMsg',
 'randInject',
 'cable',
 'process',
 'reinit',
 'initProc',
 'initReinit',
 'handleChannel',
 'handleRaxial',
 'handleAxial')

Now that is a long list. But much of it are fields for internal or special use. Anything that starts with get or set are internal destFinfo used for accessing value fields (we shall use one of those when setting up data recording). Among the rest injectMsg seems to be the most likely candidate. Use the connect function to connect the pulse generator output to the soma input

>>> m = moose.connect(pulse, 'output', soma, 'injectMsg')

connect(source, source_field, dest, dest_field) creates a message from source element’s source_field field to dest elements dest_field field and returns that message. Messages are also elements. You can print them to see their identity

>>> print m
<moose.SingleMsg: id=5, dataId=733, path=/Msgs/singleMsg[733]>

You can print any element as above and the string representation will show you the class, two numbers(id and dataId) uniquely identifying it among all elements, and its path. You can get some more information about a message

>>> print m.e1.path, m.e2.path, m.srcFieldsOnE1, m.destFieldsOnE2
/model/pulse /model/soma ('output',) ('injectMsg',)

will confirm what you already know.

A message element has fields e1 and e2 referring to the elements it connects. For single one-directional messages these are source and destination elements, which are pulse and soma respectively. The next two items are lists of the field names which are connected by this message.

You could also check which elements are connected to a particular field

>>> print soma.neighbors['injectMsg']
[<moose.vec: class=PulseGen, id=729,path=/model/pulse>]

Notice that the list contains something called vec. We discuss this later. Also neighbors is a new kind of field: lookupFinfo which behaves like a dictionary. Next we connect the table to the soma to retrieve its membrane potential Vm. This is where all those destFinfo starting with get or set come in use. For each value field X, there is a destFinfo get{X} to retrieve the value at simulation time. This is used by the table to record the values Vm takes.

>>> moose.connect(vmtab, 'requestOut', soma, 'getVm')
<moose.SingleMsg: id=5, dataIndex=0, path=/Msgs[0]/singleMsg[0]>

This finishes our model and recording setup. You might be wondering about the source-destination relationship above. It is natural to think that soma is the source of Vm values which should be sent to vmtab. But here requestOut is a srcFinfo acting like a reply card. This mode of obtaining data is called pull mode. [3]

You can skip the next section on fine control of the timing of updates and read Running the simulation.

Scheduling ¶

With the model all set up, we have to schedule the simulation. Different components in a model may have different rates of update. For example, the dynamics of electrical components require the update intervals to be of the order 0.01 ms whereas chemical components can be as slow as 1 s. Also, the results may depend on the sequence of the updates of different components. These issues are addressed in MOOSE using a clock-based update scheme. Each model component is scheduled on a clock tick (think of multiple hands of a clock ticking at different intervals and the object being updated at each tick of the corresponding hand). The scheduling also guarantees the correct sequencing of operations. For example, your Table objects should always be scheduled after the computations that they are recording, otherwise they will miss the outcome of the latest calculation.

MOOSE has a central clock element (/clock) to manage time. Clock has a set of Tick elements under it that take care of advancing the state of each element with time as the simulation progresses. Every element to be included in a simulation must be assigned a tick. Each tick can have a different ticking interval (dt) that allows different elements to be updated at different rates.

By default, every object is assigned a clock tick with reasonable default timesteps as soon it is created:

Class type                      tick    dt
Electrical computations:        0-7     50 microseconds
electrical compartments,
V and ligand-gated ion channels,
Calcium conc and Nernst,
stimulus generators and tables,
HSolve.

Table (to plot elec. signals)   8       100 microseconds

Diffusion solver                10      0.01 seconds
Chemical computations:          11-17   0.1 seconds
Pool, Reac, Enz, MMEnz,
Func, Function,
Gsolve, Ksolve,
Stats (to do stats on outputs)

Table2 (to plot chem. signals)  18      1 second

HDF5DataWriter                  30      1 second
Postmaster (for parallel        31      0.01 seconds
computations)

There are 32 available clock ticks. Numbers 20 to 29 are unassigned so you can use them for whatever purpose you like.

If you want fine control over the scheduling, there are three things you can do.

Alter the ‘tick’ field on the object

Alter the dt associated with a given tick, using the moose.setClock( tick, newdt) command

Go through a wildcard path of objects reassigning there clock ticks, using moose.useClock( path, newtick, function).

Here we discuss these in more detail.

Altering the ‘tick’ field

Every object knows which tick and dt it uses:

>>> a = moose.Pool( '/a' )
>>> print a.tick, a.dt
13 0.1

The tick field on every object can be changed, and the object will adopt whatever clock dt is used for that tick. The dt field is readonly, because changing it would have side-effects on every object associated with the current tick.

Ticks -1 and -2 are special: They both tell the object that it is disabled (not scheduled for any operations). An object with a tick of -1 will be left alone entirely. A tick of -2 is used in solvers to indicate that should the solver be removed, the object will revert to its default tick.

Altering the dt associated with a given tick

We initialize the ticks and set their dt values using the setClock function.

>>> moose.setClock(0, 0.025e-3)
>>> moose.setClock(1, 0.025e-3)
>>> moose.setClock(2, 0.25e-3)

This will initialize tick #0 and tick #1 with dt = 25 Î¼s and tick #2 with dt = 250 Î¼s. Thus all the elements scheduled on ticks #0 and 1 will be updated every 25 Î¼s and those on tick #2 every 250 Î¼s. We use the faster clocks for the model components where finer timescale is required for numerical accuracy and the slower clock to sample the values of Vm.

Note that if you alter the dt associated with a given tick, this will affect the update time for all the objects using that clock tick. If you’re unsure that you want to do this, use one of the vacant ticks.

Assigning clock ticks to all objects in a wildcard path

To assign tick #2 to the table for recording Vm, we pass its whole path to the useClock function.

>>> moose.useClock(2, '/data/soma_Vm', 'process')

Read this as “use tick # 2 on the element at path /data/soma_Vm to call its process method at every step”. Every class that is supposed to update its state or take some action during simulation implements a process method. And in most cases that is the method we want the ticks to call at every time step. A less common method is init, which is implemented in some classes to interleave actions or updates that must be executed in a specific order [4]. The Compartment class is one such case where a neuronal compartment has to know the Vm of its neighboring compartments before it can calculate its Vm for the next step. This is done with:

>>> moose.useClock(0, soma.path, 'init')

Here we used the path field instead of writing the path explicitly.

Next we assign tick #1 to process method of everything under /model.

>>> moose.useClock(1, '/model/##', 'process')

Here the second argument is an example of wild-card path. The ## matches everything under the path preceding it at any depth. Thus if we had some other objects under /model/soma, process method of those would also have been scheduled on tick #1. This is very useful for complex models where it is tedious to scheduled each element individually. In this case we could have used /model/# as well for the path. This is a single level wild-card which matches only the children of /model but does not go farther down in the hierarchy.

Running the simulation ¶

Once the model is all set up, we can put the model to its initial state using

>>> moose.reinit()

You may remember that we had changed initVm from -0.06 to -0.07. The reinit call we initialize Vm to that value. You can verify that

>>> print soma.Vm
-0.07

Finally, we run the simulation for 300 ms

>>> moose.start(300e-3)

The data will be recorded by the soma_vm table, which is referenced by the variable vmtab. The Table class provides a numpy array interface to its content. The field is vector. So you can easily plot the membrane potential using the matplotlib library.

>>> import pylab
>>> t = pylab.linspace(0, 300e-3, len(vmtab.vector))
>>> pylab.plot(t, vmtab.vector)
>>> pylab.show()

The first line imports the pylab submodule from matplotlib. This useful for interactive plotting. The second line creates the time points to match our simulation time and length of the recorded data. The third line plots the Vm and the fourth line makes it visible. Does the plot match your expectation?

Some more details ¶

`vec`, `melement` and `element`¶

MOOSE elements are instances of the class melement. Compartment, PulseGen and other MOOSE classes are derived classes of melement. All melement instances are contained in array-like structures called vec. Each vec object has a numerical id_ field uniquely identifying it. An vec can have one or more elements. You can create an array of elements

>>> comp_array = moose.vec('/model/comp', n=3, dtype='Compartment')

This tells MOOSE to create an vec of 3 Compartment elements with path /model/comp. For vec objects with multiple elements, the index in the vec is part of the element path.

>>> print comp_array.path, type(comp_array)

shows that comp_array is an instance of vec class. You can loop through the elements in an vec like a Python list

>>> for comp in comp_array:
...    print comp.path, type(comp)
...

shows

/model/comp[0] <type 'moose.melement'>
/model/comp[1] <type 'moose.melement'>
/model/comp[2] <type 'moose.melement'>

Thus elements are instances of class melement. All elements in an vec share the id_ of the vec which can retrieved by melement.getId().

A frequent use case is that after loading a model from a file one knows the paths of various model components but does not know the appropriate class name for them. For this scenario there is a function called element which converts (“casts” in programming jargon) a path or any moose object to its proper MOOSE class. You can create additional references to soma in the example this way

x = moose.element('/model/soma')

Any MOOSE class can be extended in Python. But any additional attributes added in Python are invisible to MOOSE. So those can be used for functionalities at the Python level only. You can see moose-examples/squid/squid.py for an example.

`Finfos`¶

The following kinds of Finfo are accessible in Python

``valueFinfo`` : simple values. For each readable valueFinfo XYZ there is a destFinfo getXYZ that can be used for reading the value at run time. If XYZ is writable then there will also be destFinfo to set it: setXYZ. Example: Compartment.Rm
``lookupFinfo`` : lookup tables. These fields act like Python dictionaries but iteration is not supported. Example: Neutral.neighbors.
``srcFinfo`` : source of a message. Example: PulseGen.output.
``destFinfo`` : destination of a message. Example: Compartment.injectMsg. Apart from being used in setting up messages, these are accessible as functions from Python. HHGate.setupAlpha is an example.
``sharedFinfo`` : a composition of source and destination fields. Example: Compartment.channel.

Moving on ¶

Now you know the basics of pymoose and how to access the help system. You can figure out how to do specific things by looking at the ‘cookbook`. In addition, the moose-examples/snippets directory in your MOOSE installation has small executable python scripts that show usage of specific classes or functionalities. Beyond that you can browse the code in the moose-examples directory to see some more complex models.

MOOSE is backward compatible with GENESIS and most GENESIS classes have been reimplemented in MOOSE. There is slight change in naming (MOOSE uses CamelCase), and setting up messages are different. But GENESIS documentation is still a good source for documentation on classes that have been ported from GENESIS.

If the built-in MOOSE classes do not satisfy your needs entirely, you are welcome to add new classes to MOOSE. The API documentation will help you get started.

[1]	To list the classes only, use `moose.le('/classes')`

[2]	MOOSE is unit agnostic and things should work fine as long as you use values all converted to a consistent unit system.

[3]	This apparently convoluted implementation is for performance reason. Can you figure out why? Hint: the table is driven by a slower clock than the compartment.

[4]	In principle any function available in a MOOSE class can be executed periodically this way as long as that class exposes the function for scheduling following the MOOSE API. So you have to consult the class’ documentation for any nonstandard methods that can be scheduled this way.

Demonstration of basic functionalities¶

Load and Run a Model¶

helloMoose.main()[source]¶

This is the Hello MOOSE program. It shows how to get MOOSE to do its most basic operations: to load, run, and graph a model defined in an external model definition file.

The loadModel function is the core of this example. It can accept a range of file and model types, including kkit, cspace and GENESIS .p files. It autodetects the file type and loads in the simulation.

The wildcardFind function finds all objects matching the specified path, in this case Table objects hoding the simulation results. They were all defined in the model file.

Start, Stop, and setting clocks¶

startstop.main()[source]¶

This demo shows how to start, stop, and continue a simulation. This is commonly done when we want to run a model till settling, then change a parameter or deliver a stimulus, and then continue the simulation.

Here, the model is just the output of a PulseGen object which generates periodic pulses. The demo shows how to start the simulation. using the moose.reinit command to reset the model to its initial state, and moose.start command to run the model for the specified duration. We issue multiple moose.start commands and do different things to the model between them. First, we change the delay of the pulseGen. Then we show a number of ways to assign the timestep (dt) to the table object in the simulation. Note that throughout this simulation the pulsegen is going at a uniform rate, it is just being sampled by the output table at different intervals.

stimtable.main()[source]¶

Example of StimulusTable using Poisson random numbers.

Creates a StimulusTable and assigns it signal representing events in a Poisson process. The output of the StimTable is sent to a DiffAmp object for buffering and then recorded in a regular table.

The Hodgkin-Huxley demo¶

This is a self-contained graphical demo implemented by Subhasis Ray, closely based on the ‘Squid’ demo by Mark Nelson which ran in GENESIS.

Hodgkin-Huxley's squid giant axon experiment

Simulation of Hodgkin-Huxley’s experiment on squid giant axon showing action potentials generated by a step current injection.

The demo has built-in documentation and may be run from the moose-examples/squid subdirectory of MOOSE.

Run Python from MOOSE¶

pyrun.input_output()[source]¶

The PyRun class can take a double input through trigger field. Whenever another object sends an input to this field, the runString is executed.

The fun part of this is that you can use the input value in your python statements in runString. This is stored in a local variable called input_. You can rename this by setting inputVar field.

Things become even more interesting when you can send out a value computed using Python. PyRun objects allow you to define a local variable called output and whatever value you assign to this, will be sent out through the source field output on successful execution of the runString.

You can rename the output variable by setting outputVar field.

In this example, we send the output of a pulsegen object sending out the values 1, 2, 3 during each pulse and compute the square of these numbers in Python and set output to this square.

The calculated value is assigned to the output variable and in turn sent out to a Table object’s input and gets recorded.

By default PyRun executes the runString whenever a trigger message is received and when its process method is called at each timestep. In both cases it sends out the output value. Since this may cause inaccuracies depending on what the Python statements in runString do, a mode can be specified to disable one of the above. We set mode = 2 to disable the process method. Note that this could also have been done by setting its tick = -1.

mode = 1 will disable trigger message and mode = 0, the default, enables both.

pyrun.main()[source]¶: You can use the PyRun class to run Python statements from MOOSE at runtime. This opens up many possibilities of interleaving computing in Python and MOOSE. You can also use this for debugging simulations.

pyrun.run_sequence()[source]¶

In this example we demonstrate the use of PyRun objects to execute Python statements from MOOSE. Here is a couple of fun things to indicate the power of MOOSE-Python integration.

First we create a PyRun object called Hello. In its initString we put in Python statements that prints the element’s string representation using pymoose-API. When moose.reinit() is called, this causes MOOSE to execute these Python statements which include Python calling a MOOSE function (Python->MOOSE->Python->MOOSE) - isn’t that cool!

We also initialize a counter called hello_count to 0.

The statements in initString gets executed once, when we call moose.reinit().

In the runString we put a couple of print statements to indicate the name fof the object which is running and the current count. Then we increase the count directly.

When we call moose.start(), the runString gets executed at each time step.

The other PyRun object we create, is /World. In its initString apart from ordinary print statements and initialization, we define a Python function called incr_count. This silly little function just increments the global world_count by 1.

The runString for World simply calls this function to increment the count and print it.

We may notice that we assign tick 0 to Hello and tick 1 to World. Looking at the output, you will realize that the sequences of the ticks strictly maintain the sequence of execution.

pyrun1.main()[source]¶

You can use the PyRun class to run Python statements from MOOSE at runtime. This opens up many possibilities of interleaving computing in Python and MOOSE. You can also use this for debugging simulations.