User guide

Latest release: version 3.0.0
on 14 March 2007
Site updated 22-Mar-2007

Catacomb is supported by NIH NIDA DA16454 as part of the CRCNS program, and the NSF Science of Learning Center SBE 0354378 "CELEST". Also by grants NIMH MH60013 and NIMH MH61492 to Professor Mike Hasselmo, Boston University.

Catacomb 3

Catacomb 3 is modeling system for defining, building and exploring biological models. Its focus is on biologically plausible cells, synapses and networks within the context of whole animal behavior.


It is written in Java (version 5) and runs on Windows, Linux and MacOSX.

Right-click on the first link above and select "save target as" or "save link as". Your browser should recognized this as an "Executable jar file". Save it anywhere suitable. If by any chance the operating system renames it to be a ".zip" file, then change it back to ".jar".

To run it, you need to install the Java Runtime Environment from www.java.com (Version 5.0 update 6 or later). Once this is installed:

On Windows you can start it by double clicking on the downloaded jar file.

On Linux change directory to to the place where you saved the downloaded file and, in a terminal type
java -jar -Xmx256M

Running the examples

When you first run it, Catacomb asks for a folder to use for storing new components and models. Models typically involve a number of different files (the models themselves, the components they are made from and possibly further java source files) but can be packaged up as a single jar file (a java archive format, just like a zip file). This has been done with the example models. Importing the corresponding jar file will unpack it into the workspace from which the main model can be run.

To run a model, first select it from the tree on the left. If the model can be run on its own (some models, only make sense within other models and cannot be run on their own) the run button will be enabled. Clicking "run" should open a new window to show the progress and display the results.

Related downloads

  • catacomb-scriptlib-3.0.0.jar A small optional class library that can be used in building independent implementations for components and models. It enables scripts to pass out certain useful data-types such as "Position" and "Timestep" objects.
  • catacomb-src-3.0.0.jar Source code (GPL)


Component based modelling. A model in Catacomb 3 is a collection of components that each does its own thing. Making a model involves connecting together existing components and making new components from templates by setting parameter values. You can also define new component types and specify their behavior.

Workspace format. Each component is stored in a separate file so it can be used in a variety of contexts. The workspace keeps track of all the available models and minimizes the tendency to duplicate models unnecessarily or to produce multiple slightly different versions of the same thing by accident.

Combined graphical and textual model specification. Any model can be viewed and edited both as a tree of objects, parameters and values, and as components on a diagram. Sometimes one is better, sometimes the other.

Flexible communication. Catacomb 3 supports three styles of communication between components: event based, like spikes in axons, except the events can also carry values; continuous, where one component makes values available to others to be read whenever they are required; and physical where components are located in a physical space and interact by contact or various modes of action at a distance.

Extensible model domain. The biggest difference with Catacomb 2 is that you can now define your own components without delving into the source code. Just as you can build a model graphically, you can also build a component template that sets up the structures (parameter names and types etc) needed to model a particular class of object. To set the behavior, you can either link the component to an external code module or you can embed fragments of code in the component specification.

Embedded scripting and code generation. After you define a component by adding parameters or attaching access ports, the system can generate all the code needed to connect up and run the component. It presents you with a set of empty Java methods for all the things that can happen to the component (eg if you add an input port called spike of type "event", you get a method called "receive_spike()"). You simply fill out the method bodies to define the behavior and the system takes care of the rest.

Physical model. Any component can have a physical presence. You can add lines or shapes to set its size and appearance, and you can add subcomponents that use one of the physical modes of communication to make it interact with other physical components. This is how, for example, you add a whisker to a rat so that spikes are generated when it is touching a wall.

Interfacing to existing software. For small models, there are embedded scripts. For more complex models you can develop the code for the model independently and then use Catacomb 3 to set up user interface templates to set the input parameters and visualize the results. You can, of course, connect such externally defined models with other Catacomb components.

Visualization and data export. All data generated as a model runs is stored in tree matching the model structure and can be used later to define views for line graphs or other plots. Physical models give movies that play as the simulation is run and can be replayed at will afterwards.

System independent model specification. Models are saved as "vanilla" XML where the element and attribute names come from the component specification. Importantly, almost none of them are defined by the system (the exceptions are position, scale and visual representations for use in diagrams). This means the schema is under user control, not hardwired into the system, and it makes it much easier to adapt catacomb models to existing XML schemas.