Moleculizer, for the time being, is a "batch-mode" program. This means that you use it by preparing an input file, say "my-input.xml" with a separate editor, then run the program non-interactively from the input file. From the command line, you might do this as simply as the following:
moleculizer < my-input.xmlMoleculizer and the other main programs in the moleculizer distribution use XML for their input and most of their output. A special editor, xmloperator, written by Didier Demaney, is included to make using XML easier. Xmloperator is a powerful program and will probably require some practice and dedication on your part to learn to use it well. I hope that the provisions in this distribution for using it with Moleculizer and associated programs do it justice and make it worth your effort. The home page for xmloperator is
http://www.xmloperator.netThe xmloperator user guide, announcements, new versions, etc. can be found there.
Because of preparations contained in your .xmloperator directory, this editor is also "aware" of the syntax of moleculizer input files, as well as the input files for other programs in this bundle, like . It will generate a "skeleton" input file, and it will generally allow you to make only legal changes.
Each of xmloperator's document types combines a syntax specification with means of transforming the file into HTML. The xmloperator document types associated with input files for Moleculizer and the other programs transform into HTML pages that link each entry in the input document to its page in Moleculizer docuementation. Use "transform as" from the file menu to save the HTML file in a temporary location (say /tmp) and view the HTML file and documentation with your web browser.
In the document type names given below, "static-doc" refers to the fact that, in the standalone version, documentation pages for the file formats are provided as static HTML pages, pointed to by the links below. In the soon-to-appear server version, the server generates documentation pages on demand and delivers them to you.
| Link to documentation | xmloperator document type | Purpose |
|---|---|---|
| moleculizer-input | moleculizer-input(static-doc) | Input to Moleculizer. |
| moleculizer-state | moleculizer-state(static-doc) | Reaction network dumped from Moleculizer. |
| odie | odie(static-doc) | Input to ODE-based reaction system simulator. |
| rk4tau | rk4tau(static-doc) | Input to experimental tau-leaping simulator rk4tau. |
Moleculizer has only two command-line options, for controlling aspects of Moleculizer's operation without access to the input file:
-t seconds
This causes moleculizer to "time out" after the given (positive integer) number of (clock) seconds and dump the state of its reaction network in a file named "timeout-state.xml". The dumped state, along with the original input file, can be used to restart the simulation later using the "continuator" version of moleculizer.
-s "any old string"
This option uses whatever string you supply, such as the date and time, your name, or whatever, to seed the random number generator. This option makes it easy to do independent runs of a simulation without altering the input file.
Both of these command-line options are also valid for the "continuator" version of moleculizer.
Moleculizer emits time-courses of populations of chemical species in columnar files. Gnuplot is the main plotting program used with Moleculizer. A wrapper program, plt makes it easy to plot columnar time-course files coming from Moleculizer or either of the demonstration simulators in the package.
| Option | Effect | Typical invocation |
|---|---|---|
| none | Plot data to screen once. | plt run_dir/stuff.dmp |
| -r | Plot data to screen and update (replot) every few seconds. Generates a "live" updating plot of data coming from a running simulation. | plt -r run_dir/stuff.dmp |
| -n | Plot data to .png open-source graphics format. The png graphics format is good for web applications. | plt -n run_dir/stuff.dmp > stuff.png |
| -p | Plot data to PostScript output file. | plt -p run_dir/stuff.dmp > stuff.ps |
| -f | Plot data to an xfig graphics document. You can then edit the plot with the xfig graphics editor. | plt -f run_dir/stuff.dmp > stuff.fig |
One of Moleculizer's main purposes is to generate reaction networks for use by other programs. The reaction network in a moleculizer-state file can be translated into the input formats for the demonstration ODE solver "odie" and for the experimental tau-leaping simulator "rk4tau."
These translations are accomplished by means of XSLT transformations. XSLT is an XML-based language for specifying transformations of XML files from one format into another. Each of the transformations from moleculizer-state into the input format of one of the companion simulators has a wrapper script:
| Target format | Target program | Transformation script |
|---|---|---|
| odie | odie | state2odie |
| rk4tau | rk4tau | state2rk4tau |
| sbml | external programs | state2sbml |
The transformation scripts all have the same usage; for example:
state2odie moleculizer-state-file.xml odie-file.xmlEach of the companion programs (odie and rk4tau) has a few input requirements that are not provided by the moleculizer-state file that contains the reaction network. An external program that uses SBML as its input format will not, in all likelihood, be able to accept directly the SBML file generated by translating a moleculizer-state file. Here, for odie and rk4tau, are the "extra bits" that you will need to add manually after converting a moleculizer-state file to input for the companion simulator:
Odie extras:
stop-time -- Manually scheduled Moleculizer events, such as the stop event, are not translated from the moleculizer-state file for now. You must enter the simulation time at which you want the odie simulation to stop here.
epsilon-abs -- This (usually small) number controls the absolute error of every component of the solution and its derivative when the component's value is near zero. Away from zero, error is controlled relative to the size of the component.
epsilon-rel -- This (usually small) number controls the relative error of every component of the solution and its derivative when the component's value is far from zero. Near zero, absolute error is controlled.
state-scalar -- This gives the relative weight of the solution (as opposed to its derivative) when computing relative or absolute error. 1.0 is a viable choice here.
deriv-scalar -- This gives the relative weight of the derivative (as opposed to the solution) when computing relative or absolute error. 1.0 is a viable choice here.
If the "precision" controls (epsilon-rel and epsilon-abs) are set too large, then odie will not generate very many data points. On the other hand, if they are set too small, then odie will generate far too many data points; i.e. odie's progress through the simulation will be too slow if the precision is too constrained.
Rk4tau extras:
stop-time -- Manually scheduled Moleculizer events, such as the stop event, are not translated from the moleculizer-state file for now. You must enter the simulation time at which you want the rk4tau simulation to stop here.
dump-interval -- All the output files in rk4tau dump timepoints simultaneously. Set the interval at which they write a line of output here.
epsilon -- This (usually small) number controls the the absolute error of every component of the solution.
seed -- Allows seeding of the random number generator.