I mentioned that I’d rewrite this to use the reflection API to directly set fields. In fact, it would be better to fully implement the Key-Value Coding hierarchy of Cocoa: first look for a setter method, and then directly set the field.

Directly setting the field, of course, breaks data hiding. This feature is meant for debuggers, not for applications. So, rather than just letting the standard parameter-setting capabilities set any field, there will be an annotation, @Parameter, to specify that a field should be accessible as a parameter to be set during a model’s MyModel(Map<String, Object> parameters) constructor.

There will be no setParameter method for use at runtime, because the only time parameters should be set is during object creation. Any class can choose to bypass this restriction by providing setter methods or declaring a parameter public, but

What about reading parameters at runtime? Just use the standard methods. A model will be able to access its own fields as usual. If the model wants other objects (such as its children) to have access, it should declare an accessor method.

I was hoping it would be possible to modify final fields using reflection in the constructor, but this is not the case (at least not with JDK 5.0—apparently it was possible in 1.3.0). That would let you do things like declaring parameters with @Parameter public final int beta = 0.3;, where the default value of a parameter is set in its declaration, AND it’s publicly accessible (for speed and convenience) without being modifiable, AND it gets automatically set in the constructor. I guess I can live with @Parameter public int beta = 0.3; (dangerous) or @Parameter private int beta = 0.3; + an accessor (safe).

In short, parameters will work like this:

• Parameter fields are declared with the @Parameter annotation.
• By calling the Model parameter-setting constructor in a subclass constructor, all parameters present in the parameter map will get set automatically.
• Normal access modifiers will apply at runtime.

I considered a few ways of structuring this object. The following were rejected for fairly obvious reasons:

• Specify events as Method objects Seemed like the right approach at first, because then you can just directly implement events as methods in the class. But it’s ultimately a bad idea. Doing indirect method invocation using Java reflection is way, way slower than direct method calls. Event methods are going to be called all the time. Furthermore, I’d have to wrap Method in an Event object anyway, since you might want to specify arguments to the methods.
• Use a string or int or enum The idea here is to just specify different events using some identifier that gets parsed out by a standard method implemented by the model. It’s basically indirect method calling, but faster, and uglier. Still indirect, though.

The structure I adopted is to represent events using inner classes. Each event is an instance of a subclass of Model.Event, which the model implementor will define as, e.g., MyModel.MyEvent. The event includes a rate (for use in the Gillespie algorithm) and one required method, perform(), which actually performs the event. Because Event is an inner class of Model, it can access members and methods of Model directly. So with just a few extra curly braces and so on, you get all the advantages of passing Method objects without the slowdown.

A modeler could decide to have just one Event subclass, and add member data to store the specifics of the event. Or if there are a few distinct types of events, each of which has very different behavior, there could be separate subclasses for each type, with different implementations of perform(). It doesn’t matter—all the framework cares about is the presence of the rate value and the perform() method.

Pretty slick, I think.

I’ve had an on-again, off-again relationship with Java. It always appealed to me: it runs on every platform without modification (particularly if you’re not dealing with a GUI); since the invention of JIT compilers, it’s basically as fast as C/C++, and faster than Objective-C; and its syntax is like C++, only way less convoluted.

Still, a couple years ago, I probably wouldn’t have decided to do EcoGillespie in Java. Back then, Java had this weird hybrid between static and dynamic typing. Where this caused me trouble was with collections, primarily: you could put any kind of object you wanted into a collection (good general feature of collections!) but, because the Java compiler enforces type-checking strongly, when you pulled that object out of the collection, you had to manually cast it to the correct type. (The “correct” way to do something like that is to actually CHECK its type using the instanceof operator when you pull it out of the collection. But I’m talking about cases where you NEVER put anything other than one type of object into a particular collection.) In C++, there’s this abomination called templates, where the compiler automatically generates an entirely new class whenever you have a collection with a parameterized type.

C# added this nice thing called generics that’s the best of both worlds. Like Java collections, there’s just one class for all types of objects; like C++ template collections, instances are tied to parameterized types. The improvement on Java is that you have type parameterization, so you can specify at compile time what kind of objects are going into (and thus coming out of) your collections. But you do this without generating new classes for each parameterized collection type—rather, the parameters are set *per instance*.

The Java guys thought this was a good idea too, so it has made an appearance in the 1.5/5.0 release of Java (code-named Tiger, a name no doubt picked in order to cause confusion with Mac OS X 10.4).

There are bunch more features that make life easier: autoboxing (automatic conversion of primitive types like int and double to object types like Integer and Double), automatically iterating for loops (for object : collection rather than the full iterator rigamarole), and some others.

That was a long rant not really relevant to the meat of this post. The point is, I like Java way, way more now than I did. I don’t mind that generics work a little hackishly at the compiler level, for reasons of backward-compatibility: since I’m writing all new JDK 1.5/5.0/whatever the hell they’re calling it now code, I don’t have to worry.

The Wonder of Eclipse

I had heard about this free thing called Eclipse that’s all the rage these days, so I downloaded it and tried it out. At first I was confused—too many things going on! But after working with it for about a day, getting to know its way of thinking, I really like it. I’m particularly loving its refactoring features. Say I decide a method should be named something else, or have parameters in a different order: I just right-click, choose something from the Refactor submenu, tell it what I want, and not only does the method get fixed up, but every call to the method anywhere in the project gets fixed as well. Sure beats a manual find/replace, even if you’re comfortable with regular expressions (which I am ashamed to say are not second nature to me yet). Syntax coloring, completion, etc., etc., all nice.

One thing that annoys me: you can’t pop subviews of the window out into separate windows. You can create a new full environment window and do things that way, but I’d prefer being able to just drag a view out of the main window and have it magically turn into a single-function mini-window that logically behaves as a child of the main window. I like the one-window approach in general, but I like to be able to break things out across multiple monitors when I need to.

The only other annoyance is that completion doesn’t know the names to parameters (it calls them arg0, arg1, etc.)—they should integrate it with Javadoc and not just the class bytecode so this is smarter.

JUnit

I have also been hearing the joys of unit testing trumpeted for many years, but, being lazy and never working on mission-critical code, I never got around to using that methodology myself. Well, I read up on JUnit today and put in unit tests for the ParameterMap class in EcoGillespie, and, what can I say, it’s wonderful. For a modest increase in programming time, testing time will be greatly reduced, and test coverage will be way better. Furthermore, it just makes you write better code to write the tests first: your brain is forced to concentrate on the edge cases, as well as the usability of your classes, from the very beginning. Wunderbar.

Oh, and it integrates beautifully with Eclipse. And JUnit 4, which is built into Eclipse 3.2 (in development, but so far quite stable), uses a new JDK 1.5 feature called annotations to make defining test cases even easier.

Now that I’ve tried unit testing, I shall never go back! I’ll definitely add OCUnit tests to LilyPad.

The work-in-progress simulation algorithm goes something like this:

1. Initialize model: simply call the top-level model object’s constructor, with parameter settings, and let it do its thing.
2. Create a top-level simulation object that will manage sub-simulation objects, one for each processor.
3. Partition the model into n pieces, where n is the number of processors available to the simulation. In the case of, say, two processors and a top-level model object that contains two lower-level objects (say, metapopulations that in turn contain subnetworks), this is easy: assign one object to one processor. If there’s just one high-level network—say, one scale-free disease network—the graph will be partitioned using a mincut algorithm or something like that to ensure that connections between subgraphs is minimized.
4. Create a sub-simulation object for each of the pieces of the model. One thread, one simulation object. Also assign one random number generator per object.
5. Execute the Gillespie algorithm in parallel on each sub-simulation.

That last step is the tricky part, because the question arises: what happens when an event occurs on one thread that affects another thread? Next post…

These field-setting methods are still primitive compared to KVC in Cocoa. They’re intended for debuggers directly editing fields, not for dynamic application setting, so they don’t actually call setter/getter methods—they do it directly. That’s probably fine for parameter setting.

• EcoGillespie
• LilyPad

1. Renamed the Individual class Node, to reflect that it’s the superclass for anything that can be a node in a network.
2. Wrote a temporary main() function in the DiseaseNetwork example that actually instantiates an object.
3. That is, three things. I also actually tested the code that I had written so far, finding that there was a problem with the parameter-setting code (see below).

One cool thing that’s in this code that I forgot to mention in the earlier post:

Automatic parameter setting Cocoa has this fancy thing called key-value coding that lets you set properties on objects without a compile-time binding to a setter method. You just say [object setValue:someValue forKey:@"someKey"] and Cocoa automatically does the rest. This naturally extends to things like [object takeValuesFromDictionary:dict], letting you set a whole bunch of values in one go.

Seems like a perfect match for setting parameters on model objects. Too bad Java doesn’t have it. If Java had support for categories like Objective-C, I could have just added a category to Object to provide this . This isn’t the case, so instead I added methods to the ParameterMap class to do this: void applyAllParameters(Object) and void applyParameter(String, Object). They use the Java reflection API to look up the appropriate setter method and call it with the value set in the parameter map. This means that, as long as the model object inherits Model’s constructor implementation, parameters will get set automatically.

Finally, something I plan to start soon:

Unit testing I’ve never been conscientious about doing this before. My first public API seems like a good place to start. I want this code to be very strong.

Class hierarchy The root object for all objects created in EcoGillespie is Model. In a network model, Node is a subclass of Model. Network, in addition to containing a bunch of Node objects, is itself a subclass of Node, so Networks can be themselves linked together in a Network. In the disease model I’m implementing as a first example and to help guide the design of the system, the top-level model object is a DiseaseNetwork, and it contains a bunch of DiseaseNode objects.

Protecting the modeler from the simulation kernel A key design goal of this system is to ensure that all the things that exist in pretty much every model get taken care of in the simulation kernel and don’t have to be reinvented . Plus, there should be a simple set of conventions that ensure that the modeler doesn’t accidentally mess up this separation. A couple examples:

• The actual execution of the Gillespie algorithm will not be seen anywhere in a model’s code. Everything from calculating the next time to selecting the event to be executed will be handled by the simulation engine. A node will simply get called on to perform an event when appropriate.
• Random number generation: the model will never create random number generators itself, but will simply call a standard method, getRNG(), to get the random number generator it should use. If I figure out a good way to parallelize this onto multiple threads, there will probably be a different RNG object per thread, and getRNG() will return the correct one. But the modeler shouldn’t have to know that.

Convenience methods There are a lot of things that are done in most models that aren’t necessarily obvious things to implement, because they’re so simple. But I will implement as many of these things that come up directly in the library, because any place you can shift complexity from the application to the framework is a good thing for code reliability. Super-simple example: say you want something to happen with 40% probability. The standard way is to get a random double between 0.0 and 1.0. If it’s less than 0.4, do it; if greater than 0.4, don’t. Because it’s so common, it makes sense to have a method in the RNG library: boolean trueWithProbability(double probability).

Use classes, not interfaces Swarm, Repast, and the Java libraries themselves make heavy use of interfaces (protocols in Objective-C) to define how objects interact with the system. This is all well and good from a theoretical standpoint, because it separates the interface completely from the implementation, and makes it possible for the same object, by implementing several different interfaces, to theoretically be both a random number generator and an agent. In practice, however, I find that, when building a framework, you build it with the idea of having users of the framework use a lot of functionality you’re providing—not just the interfaces, but the implementations too! By having an interface and an standard base class implementation, you’re just unnecessarily cluttering the library and confusing the user.

To see this more concretely, compare the complex forest of Java with the elegant simplicity of Cocoa. In my experience, the latter is far more intuitive and easy to work with, although that’s admittedly colored by the fact that I simply know it better.

If I do all this and find that (a) people actually use this software and (b) they provide good reasons for wanting interfaces, a refactoring can take place at that point. But I don’t anticipate it.

To be clearer: before each event, you can think of the system as being comprised of a whole bunch of Poisson processes, each of which corresponds to one of the events that could be the next event to happen. As with failure rates or chemical events, you can draw from an exponential probability distribution to figure out how long it will be until the next event—the lambda parameter is simply the sum of the rates of all the “Poisson” processes (possible events). Then you can decide what the next event actually is by drawing from a discrete probability distribution, weighted with the individual rates for the individual processes. The tricky step here is that every event can change the

One important advantage of these models over discrete-time simulations is that they map perfectly onto differential equations. For example, say you’re starting with a basic SIR (Susceptible-Infected-Recovered) model of disease spreading. Assuming a well mixed system, you can set up a set of differential equations relating the rates of change of the three classes to the densities of the other three classes alone. If you want to relax the assumption of well-mixedness, start by setting up a Gillespie-type model with a fully connected network, so that any individual can be infected by any other individual, with rates proportional to the coefficients in the ODEs. Assuming proper scaling and all that, if you run the model a bunch of times and average the runs, the graph should look exactly like the ODE’s. So you can check your model against the ODE first, and then begin changing assumptions (like the network structure).

This is such a nice approach to building ecological models (or any other kind of agent-based model) that I thought I’d build a general software framework for others to use. The idea is to let the modeler write the software without dealing at all with the actual simulation algorithm, because that remains constant from model to model. All the modeler has to do is define two things: (1) the code for individuals to perform events; and (2) the relationships of individuals in a network structure.

When an event occurs, the affected individuals will have a chance to tell the framework that their list of possible events have changed. The framework then updates any necessary data structures, simulates the next event, and repeats. This makes it really easy to build models and know that you don’t have some subtle problem in the basic algorithm.

The framework approach also means that any improvements made to the core simulation algorithm will help any models implemented using the framework. If I figure out a way to parallelize the algorithm on two processors (or, hell, across a whole network), there’s no extra work for the modeler. If I implement a faster algorithm for drawing from discrete probability distributions, models will just get it for free.

The basic algorithm is as follows:

1. Setup: create a discrete probability distribution based on the Poisson rates of all “reactions” (possible events) in the system.
2. Calculate the time until the next event by drawing from an exponential distribution with the sum of all the individual Poisson rates as the parameter.
3. Choose the event to occur by drawing the event from the distribution. This algorithm (Matias, Vitter, Ni) seems to be the state of the art in drawing from discrete probability distributions, but a modified version of this (Rajasekaran, Ross) that I came up with independently in the shower is all I’ve implemented so far.
4. Perform the event, updating the probability distribution for the next event in the process. The update process is an important part of how these algorithms are fast, of course.
5. Repeat from step 2.

My framework, which I’m uncreatively calling EcoGillespie, is based on what I think is a pretty elegant object structure. At the top level of the simulation is a Model object, which, you guessed it, represents the model of the whole system. The Model could be just a single object with a set of events that can happen to it at any point in time. However, it could also be a Network object, which is a subclass of Model that contains a network of individuals, each of which manages its own set of events at any point in time. (Conceivably, one could—and maybe I will—write Model subclasses specifically for lattices, or for continuous spaces.) Of course, each of those could in turn be networks, so you can have an infinite hierarchy of Model objects. No matter how many levels you have, you’ll never have to touch the details of scheduling events and drawing from probability distributions: all you have to do is say what events can happen, and at what rate, and the simulation kernel will handle the rest.

That is, it will work that way when it’s done. The code doesn’t do much yet, but the basic structure is slightly apparent from what I’ve written so far. I’m hosting my development live on this site:

http://code.edbaskerville.com/svn/ecogillespie/

I will track my progress on this blog.