MOOSE builtins

MOOSE = Multiscale Object Oriented Simulation Environment.

How to use the documentation

MOOSE documentation is split into Python documentation and builtin documentation. The functions and classes that are only part of the Python interface can be viewed via Python’s builtin help function:

>>> help(moose.connect)

...

The documentation built into main C++ code of MOOSE can be accessed via the module function doc:

>>> moose.doc('Neutral')

...

To get documentation about a particular field:

>>> moose.doc('Neutral.childMsg')

Brief overview of PyMOOSE

Classes:

vec

this is the unique identifier of a MOOSE object. Note that you can create multiple references to the same MOOSE object in Python, but as long as they have the same path/id value, they all point to the same entity in MOOSE.

Constructor:

You can create a new vec using the constructor:

vec(path, dimension, classname)

Fields:

value – unsigned integer representation of id of this vec

path – string representing the path corresponding this vec

shape – tuple containing the dimensions of this vec

Apart from these, every vec exposes the fields of all its elements in a vectorized form. For example:

>>> iaf = moose.vec('/iaf', (10), 'IntFire')
>>> iaf.Vm = range(10) 
>>> print iaf[5].Vm 
5.0
>>> print iaf.Vm
array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.,  9.])

Methods:

vec implements part of the sequence protocol:

len(em) – the first dimension of em.

em[n] – the n-th element in em.

em[n1:n2] – a tuple containing n1 to n2-th (exclusive) element in em.

elem in em – True if elem is contained in em.

melement

Single moose object. It has three numbers to uniquely identify it:

id - id of the vec containing this element

dataIndex - index of this element in the container vec

fieldIndex - if this is a tertiary object, i.e. acts as a field in another element (like synapse[0] in IntFire[1]), then the index of this field in the containing element.

Methods:

getId – vec object containing this element. vec() – vec object containing this element.

getDataIndex() – unsigned integer representing the index of this element in containing MOOSE object.

getFieldIndex() – unsigned integer representing the index of this element as a field in the containing Element.

getFieldType(field) – human readable datatype information of field

getField(field) – get value of field

setField(field, value) – assign value to field

getFieldNames(fieldType) – tuple containing names of all the fields of type fieldType. fieldType can be valueFinfo, lookupFinfo, srcFinfo, destFinfo and sharedFinfo. If nothing is passed, a union of all of the above is used and all the fields are returned.

connect(srcField, destObj, destField, msgType) – connect srcField of this element to destField of destObj.

melement is something like an abstract base class in C++. The concrete base class is Neutral. However you do not need to cast objects down to access their fields. The PyMOOSE interface will automatically do the check for you and raise an exception if the specified field does not exist for the current element.

Creating melements

To create the objects of concrete subclasses of melement, the class can be called as follows:

melement(path, dims, dtype, parent)

path: This is like unix filesystem path and is the concatenation of name of the element to be created and that of all its ancestors spearated by /. For example, path=`/a/b` will create the element named b under element a. Note that if a does not exist, this will raise an error. However, if parent is specified, path should contain only the name of the element.

dims: (optional) tuple specifying the dimension of the containing melement to be created. It is (1,) by default.

dtype: string specifying the class name of the element to be created.

parent: (optional) string specifying the path of the parent element or the Id or the ObjId of the parent element or a reference to the parent element. If this is specified, the first argument path is treated as the name of the element to be created.

All arguments can be passed as keyword arguments.

For concrete subclasses of melement, you do not need to pass the class argument because the class name is passed automatically to melement __init__ method.

a = Neutral(‘alpha’) # Creates element named alpha under current working element b = Neutral(‘alpha/beta’) # Creates the element named beta under alpha c = Cell(‘charlie’, parent=a) # creates element charlie under alpha d = DiffAmp(‘delta’, parent=’alpha/beta’) # creates element delta under beta

module functions

element(path) - returns a reference to an existing object converted to the right class. Raises ValueError if path does not exist.

copy(src=<src>, dest=<dest>, name=<name_of_the_copy>, n=<num_copies>, copyMsg=<whether_to_copy_messages) – make a copy of source object as a child of the destination object.

move(src, dest) – move src object under dest object.

useClock(tick, path, update_function) – schedule <update_function> of every object that matches <path> on clock no. <tick>. Most commonly the function is ‘process’. NOTE: unlike earlier versions, now autoschedule is not available. You have to call useClock for every element that should be updated during the simulation.

The sequence of clockticks with the same dt is according to their number. This is utilized for controlling the order of updates in various objects where it matters.

The following convention should be observed when assigning clockticks to various components of a model:

Clock ticks 0-3 are for electrical (biophysical) components, 4 and 5 are for chemical kinetics, 6 and 7 are for lookup tables and stimulus, 8 and 9 are for recording tables.

Generally, ‘process’ is the method to be assigned a clock tick. Notable exception is ‘init’ method of Compartment class which is assigned tick 0.

0 : Compartment: ‘init’ 1 : Compartment: ‘process’ 2 : HHChannel and other channels: ‘process’ 3 : CaConc : ‘process’ 4,5 : Elements for chemical kinetics : ‘process’ 6,7 : Lookup (tables), stimulus : ‘process’ 8,9 : Tables for plotting : process

Example: moose.useClock(0, ‘/model/compartment_1’, ‘init’) moose.useClock(1, ‘/model/compartment_1’, ‘process’)

setClock(tick, dt) – set dt of clock no <tick>.

start(runtime) – start simulation of <runtime> time.

reinit() – reinitialize simulation.

stop() – stop simulation

isRunning() – true if simulation is in progress, false otherwise.

exists(path) – true if there is a pre-existing object with the specified path.

loadModel(filepath, modelpath) – load file in <filepath> into node <modelpath> of the moose model-tree.

setCwe(obj) – set the current working element to <obj> - which can be either a string representing the path of the object in the moose model-tree, or an vec. ce(obj) – an alias for setCwe.

getCwe() – returns vec containing the current working element. pwe() – an alias for getCwe.

showfields(obj) – print the fields in object in human readable format

le(obj) – list element under object, if no parameter specified, list elements under current working element

moose.pwe()

Print present working element. Convenience function for GENESIS users. If you want to retrieve the element in stead of printing the path, use moose.getCwe()

moose.le(el=None)

List elements under el or current element if no argument specified.

Parameters :

el : str/melement/vec/None

The element or the path under which to look. If None, children

of current working element are displayed.

Returns :

None

moose.ce()

Set the current working element. ‘ce’ is an alias of this function

moose.showfield(el, field='*', showtype=False)

Show the fields of the element el, their data types and values in human readable format. Convenience function for GENESIS users.

Parameters :

el : melement/str

Element or path of an existing element.

field : str

Field to be displayed. If ‘*’ (default), all fields are displayed.

showtype : bool

If True show the data type of each field. False by default.

Returns :

None

moose.showmsg(el)

Print the incoming and outgoing messages of el.

Parameters :

el : melement/vec/str

Object whose messages are to be displayed.

Returns :

None

moose.doc(arg, inherited=True, paged=True)

Display the documentation for class or field in a class.

Parameters :

arg : str/class/melement/vec

A string specifying a moose class name and a field name separated by a dot. e.g., ‘Neutral.name’. Prepending moose. is allowed. Thus moose.doc(‘moose.Neutral.name’) is equivalent to the above. It can also be string specifying just a moose class name or a moose class or a moose object (instance of melement or vec or there subclasses). In that case, the builtin documentation for the corresponding moose class is displayed.

paged: bool

Whether to display the docs via builtin pager or print and exit. If not specified, it defaults to False and moose.doc(xyz) will print help on xyz and return control to command line.

Returns :

None

Raises :

NameError

If class or field does not exist.

moose.element(arg) → moose object

Convert a path or an object to the appropriate builtin moose class instance

Parameters :

arg : str/vec/moose object

path of the moose element to be converted or another element (possibly available as a superclass instance).

Returns :

melement

MOOSE element (object) corresponding to the arg converted to write subclass.

moose.getFieldNames(className, finfoType='valueFinfo') → tuple

Get a tuple containing the name of all the fields of finfoType kind.

Parameters :

className : string

Name of the class to look up.

finfoType : string

The kind of field (valueFinfo, srcFinfo, destFinfo, lookupFinfo, fieldElementFinfo.).

Returns :

tuple

Names of the fields of type finfoType in class className.

moose.copy(src, dest, name, n, toGlobal, copyExtMsg) → bool

Make copies of a moose object.

Parameters :

src : vec, element or str

source object.

dest : vec, element or str

Destination object to copy into.

name : str

Name of the new object. If omitted, name of the original will be used.

n : int

Number of copies to make.

toGlobal : int

Relevant for parallel environments only. If false, the copies will reside on local node, otherwise all nodes get the copies.

copyExtMsg : int

If true, messages to/from external objects are also copied.

Returns :

vec

newly copied vec

moose.move()

Move a vec object to a destination.

moose.delete(obj) → None

Delete the underlying moose object. This does not delete any of the Python objects referring to this vec but does invalidate them. Any attempt to access them will raise a ValueError.

Parameters :

id : vec

vec of the object to be deleted.

Returns :

None

moose.useClock()

Schedule objects on a specified clock

moose.setClock()

Set the dt of a clock.

moose.start(time) → None

Run simulation for t time. Advances the simulator clock by t time.

After setting up a simulation, YOU MUST CALL MOOSE.REINIT() before CALLING MOOSE.START() TO EXECUTE THE SIMULATION. Otherwise, the simulator behaviour will be undefined. Once moose.reinit() has been called, you can call moose.start(t) as many time as you like. This will continue the simulation from the last state for t time.

Parameters :

t : float

duration of simulation.

Returns :

None

See also

moose.reinit
(Re)initialize simulation
moose.reinit() → None

Reinitialize simulation.

This function (re)initializes moose simulation. It must be called before you start the simulation (see moose.start). If you want to continue simulation after you have called moose.reinit() and moose.start(), you must NOT call moose.reinit() again. Calling moose.reinit() again will take the system back to initial setting (like clear out all data recording tables, set state variables to their initial values, etc.

moose.stop()

Stop simulation

moose.isRunning()

True if the simulation is currently running.

moose.exists()

True if there is an object with specified path.

moose.writeSBML()

Export biochemical model to an SBML file.

moose.readSBML()

Import SBML model to Moose.

moose.loadModel(filename, modelpath, solverclass) → vec

Load model from a file to a specified path.

Parameters :

filename : str

model description file.

modelpath : str

moose path for the top level element of the model to be created.

solverclass : str, optional

solver type to be used for simulating the model.

Returns :

vec

loaded model container vec.

moose.saveModel(source, filename) → None

Save model rooted at source to file filename.

Parameters :

source : vec/element/str

root of the model tree

filename : str

destination file to save the model in.

Returns :

None

moose.connect(src, src_field, dest, dest_field, message_type) → bool

Create a message between src_field on src object to dest_field on dest object.

Parameters :

src : element/vec/string

the source object (or its path)

src_field : str

the source field name. Fields listed under srcFinfo and sharedFinfo qualify for this.

dest : element/vec/string

the destination object.

dest_field : str

the destination field name. Fields listed under destFinfo and sharedFinfo qualify for this.

message_type : str (optional)

Type of the message. Can be Single, OneToOne, OneToAll. If not specified, it defaults to Single.

Returns :

melement

message-manager for the newly created message.

moose.getCwe()

Get the current working element. ‘pwe’ is an alias of this function.

moose.setCwe()

Set the current working element. ‘ce’ is an alias of this function

moose.getFieldDict(className, finfoType) → dict

Get dictionary of field names and types for specified class.

Parameters :

className : str

MOOSE class to find the fields of.

finfoType : str (optional)

Finfo type of the fields to find. If empty or not specified, all fields will be retrieved.

Returns :

dict

field names and their types.

Notes

This behaviour is different from getFieldNames where only valueFinfo`s are returned when `finfoType remains unspecified.

moose.getField()

getField(element, field, fieldtype) – Get specified field of specified type from object vec.

moose.seed(seedvalue) → None

Reseed MOOSE random number generator.

Parameters :

seed : int

Optional value to use for seeding. If 0, a random seed is automatically created using the current system time and other information. If not specified, it defaults to 0.

Returns :

None

moose.rand() -> [0, 1)
Returns :float in [0, 1) real interval generated by MT19937.
moose.wildcardFind(expression) → tuple of melements.

Find an object by wildcard.

Parameters :

expression : str

MOOSE allows wildcard expressions of the form:

{PATH}/{WILDCARD}[{CONDITION}]

where {PATH} is valid path in the element tree. {WILDCARD} can be # or ##.

# causes the search to be restricted to the children of the element specified by {PATH}.

## makes the search to recursively go through all the descendants of the {PATH} element. {CONDITION} can be:

TYPE={CLASSNAME} : an element satisfies this condition if it is of
class {CLASSNAME}.
ISA={CLASSNAME} : alias for TYPE={CLASSNAME}
CLASS={CLASSNAME} : alias for TYPE={CLASSNAME}
FIELD({FIELDNAME}){OPERATOR}{VALUE} : compare field {FIELDNAME} with
{VALUE} by {OPERATOR} where {OPERATOR} is a comparison operator (=,
!=, >, <, >=, <=).

For example, /mymodel/##[FIELD(Vm)>=-65] will return a list of all the objects under /mymodel whose Vm field is >= -65.

moose.quit()

Finalize MOOSE threads and quit MOOSE. This is made available for debugging purpose only. It will automatically get called when moose module is unloaded. End user should not use this function.

,