Implementing new types of model

There are a number of possible starting points for a new implementation. You could have some numerical code that you want to make accessible through the Catacomb user interface for running and visualization. Or maybe you are interested in a type of thing that is not yet implemented, in which case you can create the model class specification, and even build some model instances, within Catacomb before handing it over to a software engineer to put the numerical implementation in place.

The key point here is that the model specification, created by someone who understands the biology and how to parameterize it, is quite separate from the implementation. Ideally, the code required for a new model should contain almost nothing other than computational mathematics. All the rest should be handled by Catacomb. This isn't completely true in the current version, but it comes quite close: the rest of this document explains exactly what is involved in implementing a new class of model. A lot depends on how your code is written, but as a rough guide, the catacomb-specific implementation code required for joining the ion channel model specification to standalone ion channel computations is all contained in two classes of about 60 lines in total.

Creating an object tree to mirror the model

The first thing you need is a java representation of the actual model with normal java variables initialized to the parameter values in the model. This is all auto-generated: the "export component (java)" menu option exports any selected components as java classes. These should not be edited at all. When the user runs a model, it is mapped to instances of these classes resulting in an object tree that mirrors the model. This is handed over to an interface class that is supplied by the implementer. For a fixed timestep calculation, this just has an init method that is given the object tree, an advance method to move the calculation on one step, and a couple of methods for getting results back and monitoring progress.

Creating an implementation skeleton

For Catacomb to run a model, it must know that there is an implementation available. You tell it this by creating an "Implementation" file in the components editor. This says where the implementation classes are (the classpath) and type of calculation they do. If you export one of these to java, you get a skeleton for the implementation generated. This should compile and run fine, though it won't do anything particularly interesting.

The work of implementing a model boils down to

• unpacking the model representation into whatever data structures you use internally
• creating structure tp represent the state of the model
• advancing these structures through the progress of the calculation (for short calculations you can do everything in the init method, but it won't show up on Catacomb's fancy progress monitor)
• returning the results of the calculation in a form suitable for visualization. This mainly involves annotating your data storage with certain annotations from the "view" package using Java 1.5 annotations.