JSim and Antimony

Introduction

Antimony is a simple text language for specifying SBML style models. This document describes how to write Antimony models within JSim, and how to import and export Antimony files to and from JSim. This is not a tutorial of the Antimony language. For that, see the Antimony Home Page.

Antimony support within JSim is available for JSim version 2.03 and above.

Prerequisites:

Introductory Survey of MML (required)
Introduction to the JSim GUI (recommended)

What is Antimony?

Antimony is a human-readable computer language for describing SBML style models developed by Lucian Smith. A complete description of the Antimony language, along with various Antimony software, is available on the Antimony Home Page. Antimony is designed to be "equivalent" to SBML in the sense that an Antimony and its SBML translation describe exactly the same model. From JSim's perspective, Antimony provides a simple and concise language for editing chemical network models. Since it, unlike SBML, it can be edited by hand, it makes for a quick path to SBML-style chemical network modeling within JSim.

Writing Antimony models in JSim

Antimony code can be written within an MML model (or .mod file) by surrounding the Antimony text with the keyword "antimony" and double curly braces. Consider the following Antimony model of enzyme-substrate binding:

 S = 1   // S initial conc
 E = 1   // E initial conc
 ES = 0  // ES initial conc
 S + E -> ES; k1*S*E - k2*ES // enzyme-substrate binding
 k1 = 1  // forward rate
 k2 = .1 // backward rate

Antimony code can be embedded in a JSim model by prepending the keyword "antimony" and surrounding the code in double-curly braces:

antimony {{
   S = 1   // S initial conc
   E = 1   // E initial conc
   ES = 0  // ES initial conc
   S + E -> ES; k1*S*E - k2*ES // enzyme-substrate binding
   k1 = 1  // forward rate
   k2 = .1 // backward rate
}}

When the model above is compiled, JSim translates the embedded Antimony code to flattened MML and then compiles that. If you wish to see the flattened MML version of an Antimony model, you may do so in the JSim GUI by selecting "View flat MML text" from the View menu in the model's Debug tab. Alternatively, jsbatch (command line) users should use the "-oflat" switch:

jsbatch -f sb.mod -oflat > sbflat.mod  // assumes sb.mod contains embedded Antimony

Note that, at present, a JSim model may be either standard MML or embedded Antimony. The two types of models cannot be mixed. However, mixing of models is planned for the future.

Importing Antimony Files into JSim

To import an Antimony model into JSim, select "Import model file" from the "Add" menu under the JSim GUI's "Project" tab. Antimony files have extension .txt. (Note that .txt is used by many other files besides Antimony, so be sure to pick a real Antimony file.) Alternatively, you can load a Antimony file via the -f switch on the command line of either jsim or jsbatch.

When an Antimony file is read into JSim the keyword "antimony" and surrounded double curly braces are added automatically.

Batch translation of Antimony files to embedded MML may be accomplished as follows:

jsbatch -f somemodel.txt -omml > somemodel.mod

Windows users: If you are receiving errors from JSim concerning libSBML please see Installing JSim under MS Windows: SBML, Antimony, and Matlab.

Exporting Antimony Files from JSim

Any MML model may be exported to Antimony, not merely models containing embedded Antimony. However, since Antimony is equivalent to SBML, the same export limitations apply.

To export Antimony from the JSim GUI, compile it, click on the model "Debug" tab and select "View Antimony" from the "View" menu. Translated Antimony will appear in the text area. If any warnings are generated in the translation, a button "Show N translator warnings" will appear. Clicking this button will display the warnings in the JSim message area (right half of GUI).

To export Antimony from the command line, use the "-oantimony" switch in jsbatch:

jsbatch -f somemodel.mod -oantimony > somemodel.xml
   or
jsbatch -f somemodel.proj -oantimony > somemodel.xml

Windows users: If you are receiving errors from JSim concerning libSBML and antimony translation, please see Installing JSim under MS Windows: SBML, Antimony, and Matlab.

Future plans

The following improvements are planned for the future:

Antimony support for physical units (currently missing).
The ability to mix standard MML and embedded Antimony within the same model.

Comments or Questions?

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.