Wednesday, April 2, 2008

Tracing the BEAST

I have spent some time on analyzing BEAST code. I have started with the describing packages with UML. Then I've moved to the business logic analysis.
Let me introduce you BEAST's configurator. It can be found in dr.xml.
Configuration of BEAST simulation is given by xml file. Each xml node has its realization in java code.
BEAST is using builder pattern (or maybe it's better to say builder's builder) for the software initial setup. However this is some data driven, distributed variation on this pattern ;).
As you can see at the picture there are two classes marked yellow.

XMLParser is responsible for parsing XML file with the configuration. It uses DOM model of that file as an input. The traversing through the code is done in post-order manner. To parse each node from the description BEAST uses multiple AbstractXMLObjectParser's specialization instances (this builders can setup instance of the classes with the business logic).
And at this point I can explain what I mean saying distributed. Most of the specializations of the AbstractXMLObjectParser are anonymous classes which can be found in model's classes.
To see whole set of object parser you can always look into BeastParser.setup() method.

Reference class is realization of idref's concept from setup file.
Each parsed node is stored (as a new node realization instance) in some object's registry or/and added to it's parent node. When such a object is referred in other parts of configuration it is wrapped in Reference and returned to caller node. That means we can refer to the classes which was built before.
E.g. When parsing proces reach the mcmc node it look for the builder which is responsible for building class which implements MCMC process (I am skipping building of the mcmc's child nodes). At this point every referred object (is already consturcted) is taken from the registry and used for correct in construction of MCMC implementation.

So the formula for extending BEAST is simple.

  1. define xml for your contribution

  2. provide builder for your implementation

  3. implement your contribution

I don't want to go into much details about this engine (as for example how the simplation is started, after construction or how the xml description is validated) so if you can any questions and suggestions (as I only interpret the code I could misunderstand some concepts) leave a comment.
Next time I will show you simple recipe for adding new tree mutator to the BEAST.


No comments: