Note: Grammar lines are defined with "<>", "[]", and "|" symbols that are not part of the actual grammar, but indicate different options are permitted. Words in "<>" (i.e. "<symbol name>") indicate a spot that must be filled in with text that matches that description (all such descriptions are defined at the end of the document). Grammar in "[]" (i.e. "[in <compartment>]" is optional. The "|" symbol should be read as an 'or' statement, and indicate that two or more possibilities are valid in that spot (i.e. "[const|var]".

General Specifications

Order

Each statement in Antimony is parsed as a rule that helps define a model. Any rule that does not contradict a different rule may be presented in any order without affecting the final model. If two rules contradict one another, the final rule takes precedence, and the parts of the initial rule that contradict the later rule are discarded. As an example, if earlier in a model we find the rule "x=5" and later find the rule "x=6", the "x=5" rule is discarded in favor of the later rule. Incompatible rules, such as using the same symbol as a species and as the name of a reaction, are illegal.

The one type of symbol that must be defined before being used is that of a submodule. The submodule's definition must have come earlier in the Antimony file than its use as a submodule, and the name used for a submodule must not be used in any capacity before being defined. This goes for subvariable names, too: 'A.y' is an illegal symbol to use before 'A' is defined.

Similarly, once a module has been defined, its components may not be expanded: if submodule 'A' did not declare a symbol 'y', use of the symbol 'A.y' is illegal, and does not create a new variable inside the submodule.

Line endings and white space:

Since Antimony is intended to be easy and simple, it is not a requirement to end every line with a ';'. However, this means that a carriage return is syntactically significant, and breaking up a single statement with returns will not work. If you want to break up your lines anyway, you may use a '\' followed by a return, and Antimony will continue as if that line and the line following were all on one line. This is the only whitespace that Antimony recognizes--all other whitespace is ignored (spaces and tabs) except to distinguish one symbol from another.

Antimony Files

Antimony files may contain the following, in any order:

<import statements>

<model definitions>

<function definitions>

<declarations>

<import statements>:

One or more lines of the format:

import <textstring>

Parse the text string as the name of a file (relative to the directory where the executable is being run) and read in the file in question. First, parse that file using libSBML. If libSBML returns an error, parse the file as if the file was copied and pasted into the Antimony file at this exact spot.

<textstring>:

Any text surrounded by quotation marks ("), and not containing returns. Parsed as filenames for <import statements> and used for <display names>

<model definitions>:

One or more lines of the format:

[model|module] <symbol> [ ( <list of exported variables> ) ] <declarations> end

Defines a new model with the name '<symbol>'. The <declarations> are included in the model, and may define any number of symbols. The <list of exported variables> may be defined in the <declarations>, and are exported for easy synchronization with models that include the defined model (see <imported models>)

<function definitions>:

One or more lines of the format:

function <symbol> ( <list of exported variables> ) [return] <equation> [return] end

Once defined, the <symbol> may be used in subsequent variable definitions in any module as a replacement for the given equation>. Any <symbol> appearing in the equation> must appear in the list of exported variables>.

<list of exported variables>:

A comma-separated list of zero or more <symbol> elements.

<declarations>:

Declarations define elements of a model. If used outside a model definition, they define elements of the model "__main". Declarations are the bulk of Antimony-formatted files, and can contain any of the following, separated by a ';' or by a <return>.

<blank lines>

<comments>

<symbol declarations>

<imported models>

<assignment rules>

<rate rules>

<reaction definitions>

<initializations>

<DNA strand definitions>

<event definitions>

<synchronizations>

<deletions>

<display names>

<blank lines>:

A line with nothing in it is legal in Antimony, and does nothing.

<comments>:

A line of the format:

// [<any text>] <return>

Or any text (potentially spanning multiple lines) of the form:

/* [<any text, including returns>] */

All lines of the above format are ignored, and can be used to comment on a model (but will not be exported to translated forms of the model). They can be used anywhere: the first form will parsed simply as a <return>, and the second will be skipped and not parsed at all.

<return>

Antimony files can read Windows, UNIX, and Mac-formatted text files. This means that a 'return' value can be either LF ('\n'), CR ('\r'), or CRLF ('\r\n'). Returns have semantic meaning in Antimony: they can be used instead of ';' to define breaks between <declarations>, they define the end of <comments>, and they can be used to break up <event definitions>. To make a single <declaration> that spans multiple lines, you may precede the return with a '\' symbol.

<symbol declarations>

Lines that declare some basic property of an element. Can be of the form:

[const|var] <symbol type> <list of symbols>

const|var <list of symbols>

<symbol> in <compartment>

All symbols in <list of symbols> preceded by a 'const' are declared to be const. All symbols preceded by a 'var' are declared to be variable. All symbols defined without ever being declared 'const' or 'var' get their type's default: species are variable, and anything else associated with a value is constant unless it has a variable in the equation that sets its value.

All symbols in <list of symbols> preceded by a <symbol type> have the corresponding type set. The only exceptions are when the <symbol type> is less specific than the type it already has (in which case, it retains its current type), or if the existing type is 'DNA' and the <symbol type> is 'reaction', or if the existing type is 'reaction' and the <symbol type> is 'DNA'. In both cases, the symbol is changed to be the type 'gene'.

If the '<symbol> in <compartment>' line is used, the symbol in question is defined to be a member of the given compartment.

<symbol type>

Valid types for <symbol type> declarations are:

species

reaction

formula

DNA

gene

operator

compartment

Invalid types for <symbol type> declarations (but which exist, just by default) are:

undefined

(symbols used in <equation>s but never elsewhere)

event

(symbols defined in event declarations)

module

(symbols defined in submodule declarations)

DNA strand

(symbols defined in DNA strand declarations)

For more information on symbol type compatibilities, see <species>, <reaction>, <formula>, <DNA>, <operator>, <gene>, <compartment>, <undefined>, <event>, <module>, <DNA strand>, and <interaction>

<list of symbols>:

A comma-separated list of the format:

<symbol> [in <compartment>] [, <symbol> [in <compartment>] ] ...

Each symbol may optionally be further defined to be in the specified compartment symbol.

<symbol>:

A string of one or more characters, the first of which must be a letter, optionally capitalized (a-z or A-Z), or the underscore symbol ('_'), and the following characters of which may additionally include numbers (0-9). "J0" is a valid symbol; "0r" and "$y" are not.

<compartment>:

A symbol defined as a compartment. Symbols previously unused or used only in a 'formula' context are both legal here, but nothing else is. The symbol will subsequently be tagged as a compartment.

<formula>:

A symbol defined as a formula. Symbols previously unused are legal here, and most other types that are compatible with the 'formula' type is legal, but will not change the type of the symbol. (In other words, if you use a symbol defined as a reaction in a formula context, that's fine, and the symbol will still be defined as a reaction, not a formula.)

<DNA>:

A symbol defined as a DNA element (an 'operator' (associated only with a formula) or a 'gene' (associated with a reaction). Symbols previously unused or used in a 'formula' context are legal, and the symbol will subsequently be tagged as 'DNA'. Symbols previously used in an 'operator' or 'gene' context are legal, and the symbol will continue to be tagged as an operator or gene, respectively. Symbols previously used in a 'reaction' context are legal, and will subsequently be tagged as a 'gene'.

<operator>:

A symbol defined as an operator, or, DNA only associated with a formula. Symbols previously unused or used in a 'formula' or 'DNA' context are legal, and subsequently become operators. Other symbols (including genes) are not legal operators.

<gene>:

A symbol defined as a gene, or, DNA associated with a reaction. Symbols previously unused or used in a 'formula' or 'DNA' context are legal, and subsequently become genes. Other symbols (including operators) are not legal genes.

<reaction>:

A symbol with an associated reaction and (optionally) a reaction rate. Symbols previously unused or used in a 'formula' context are legal, and subsequently become reactions.

<interaction>:

A symbol with an associated interaction (a species and a reaction or formula). Any formula associated with the interaction is assigned to the reaction or formula in question. Symbols previously unused or used in a 'formula' context are legal, and subsequently become interactions.

<species>:

A symbol defined as a species, or, for the purposes of modeling, participants in reactions. Symbols previously unused or used in a 'formula' context are legal, and subsequently become species.

<undefined>:

A symbol that is only used in an <equation> is created but left otherwise completely undefined. Obtaining a list of undefined symbols is a good way to 'debug' a model, as they might indicate misspellings. Most symbol types can have been used as an undefined member of an equation prior to their use, but some (models) do not even allow this.

<event>:

A symbol defined as an event, or, a boolean expression associated with a list of one or more rules. Symbols previously unused or used in a 'formula' context are legal, and subsequently become events. If defined, formulas defined for the event symbol are used as that event's trigger.

<module>:

A symbol defined as a module. A module is only created with an <imported models> declaration, and the symbol must not have been used in its containing module before this declaration, in any context. This is the 'local name' of the module, and is different from the name *of* the module.

<DNA strand>:

A symbol defined as a strand of DNA, or, an ordered list of DNA elements.

<imported models>:

Previously-defined models can be imported into a new model by using lines like:

[<symbol> : ] <module name> ( [<list of symbols>] ) [, timeconv=<formula>|<number>] [, extentconv=<formula>|<number>]

If the first '<symbol>' is used, it will be used as the name of the new sub-module. (This symbol must not have been previously used in any context.) If not, its name will be "_sys<#>", where <#> is the lowest possible integer >=0 for which no previous symbol of that form exists. If "_sys0" and "_sys1" exist, for example, "_sys2" will be used. If only "_sys3" exists (for whatever reason), "_sys0" will be used..

The <list of symbols> must be a list equal to or less than the number of symbols in the <list of exported variables> in the definition of the module. Each symbol in this list is a local symbol, and is matched with the corresponding symbol in the exported list, synchronizing the two symbols with the local symbol having precedence (see <synchronizations>). It is not legal to use the 'in <compartment>' optional syntax when importing a model.

The 'timeconv' and 'extentconv' options will set the time conversion factor and the extent conversion factor (respectively) for the submodel. These are used when the global 'time' and 'extent' factors present in all models are different in the submodel from what they are in the containing model. The conversion works such that a unit of time and/or extent in the submodel, multiplied by the appropriate conversion factor, should equal the units of time/extent in the containing model. The symbol for a formula may be used, or an actual number.

<module name>:

The 'global' name of a module, i.e. the symbol used in the <model definitions> section of an Antimony file, or the name used as the 'id' of a model in an imported SBML file.

<reaction definitions>:

Lines that define reactions or interactions in the model, of the form:

[<symbol> : ] <list of reactants> -> <list of products> ; [<equation>]

[<symbol> : ] <species> -| <formula> ; [<equation>]

[<symbol> : ] <species> -o <formula> ; [<equation>]

[<symbol> : ] <species> -( <formula> ; [<equation>]

If the first '<symbol>' is used, it will be used as the name of the new reaction or interaction. (This symbol may have been used in an unknown or formula context.) If not, its name will be "_J<#>", where <#> is the lowest possible integer >=0 for which no previous symbol of that form exists.

The first line describes a reaction, and the other three describe an interaction. The lists of reactant and products (see <list of reactants|products>) take the same form; the former describe species that are consumed in the reaction; the latter species that are created.

The next three lines describe interactions. The first ('-|') describes an inhibition, the second ('-o') an activation, and the last ('-(') an interaction of either unknown form, or of a form that is sometimes inhibitory and sometimes activating. Exactly one species must be provided per interaction on the left hand side of the reaction symbol, and exactly one formula on the right (other symbols that are compatible with the 'formula' type are allowed, but they must not be species. Reactions are probably the most useful thing to put here). Ideally, if the concentration of the species in an interaction changes, the value of the formula in question should change appropriately in response: inversely for inhibitions, concomitantly for activations, and one way or the other (or both) but not remain unchanged for unknown. Antimony does not have the capacity to check this, however, and takes you at your word.

The optional final <equation> will be used as the reaction rate for the reaction form, and will be assigned to the influenced formula for the interaction forms. Typically, the final equation is left unused for interactions, and defined elsewhere.

<list of reactants|products>:

A list of zero or more species of the form:

[<positive number>] <species> [+ [<positive number>] <species> ] ...

The optional positive integers are the stoichiometry for the list. Technically, SBML and other specifications only state that the stoichiometry must be a valid number, either positive or negative (or zero), but while a negative stoichimetry in a reactant is equivalent to a positive stoichiometry in the product list (and visa versa), nobody ever does this, and we feel safe requiring positive values for the stoichiometries.

<assignment rules>

Assigns a value or an equation to a symbol to be updated at all points during a model:

<symbol> := <equation>

It is illegal for the equation to contain the symbol in question, or for it to contain a symbol which, in turn, is defined by an equation containing the symbol, etc. A symbol must have only one assignment rule or rate rule, so only the last such definition in an Antimony file is used.

<rate rules>

Assigns a value or an equation to a symbol that describes how the value of the symbol changes with time (dS/dt):

<symbol>' = <equation>

It is legal for the equation to contain the symbol in question. A symbol must have only one assignment rule or rate rule, so only the last such definition in an Antimony file is used.

<initializations>

Assigns a value or an equation to a symbol for the beginning of the model's simulation:

<symbol> = <equation>

It is illegal for the equation to contain the symbol in question, or for it to contain a symbol which, in turn, is defined by an equation containing the symbol, etc. A symbol must have only one initialization, so only the last such definition in an Antimony file is used (but a symbol may have both an initialization and an assignment or rate rule).

<equation>

A mathematical function. May contain numbers, mathematical symbols ('+', '-', '*', '/', '^', '(', ')', '<', '>'), function names (see <function names>), and the keyword 'time', which refers to the time in the timecourse of the simulation (when converted to SBML, this becomes the MathML csymbol 'time'). Antimony's parsing mechanism steals libSBML's level 1 parser, with the addition of the following boolean symbols: "<=" (less than or equal to), ">=" (greater than or equal to), "==" (exactly equal to), "!=" (not equal to), "&&" (and), "||" (or), and "!" (not).

Equations associated with DNA elements may contain an ellipsis ("..."), which is shorthand for "the rate at the DNA element upstream of this element." If nothing is found upstream of the DNA element in question, or if the element appears in no DNA strands, this rate is defined to be zero. (Note: The ellipsis may appear in initializations, assignment rules, and reaction rates, but not in rate rules.

<function names>

Allowable function names are: "abs", "and", "annotation", "annotation-xml", "apply", "arccos", "arccosh", "arccot", "arccoth", "arccsc", "arccsch", "arcsec", "arcsech", "arcsin", "arcsinh", "arctan", "arctanh", "bvar", "ceiling", "ci", "cn", "cos", "cosh", "cot", "coth", "csc", "csch", "csymbol", "degree", "divide", "eq", "exp", "exponentiale", "factorial", "false", "floor", "geq", "gt", "infinity", "lambda", "leq", "ln", "log", "logbase", "lt", "math", "minus", "neq", "not", "notanumber", "or", "otherwise", "pi", "piece", "piecewise", "plus", "power", "root", "sec", "sech", "semantics", "sep", "sin", "sinh", "tan", "tanh", "times", "true", "xor", "acos", "asin", "atan", "ceil", "delay", "log10", "pow", "sqr", and "sqrt", plus the distribution function names "normal", "truncatedNormal", "uniform", "exponential", (rate), "truncatedExponential", "gamma", "truncatedGamma", "poisson", and "truncatedPoisson". In addition, any <function definitions> previously declared may be used.

<DNA strand definitions>

DNA strands (ordered lists of DNA elements) are defined with lines formatted:

[<symbol> : ] [--] <DNA|DNA strand|module> [ -- <DNA|DNA strand|module> ] [...] [--]

(Note that this must have at least one '--', though it may happen either upstream or downstream of the <DNA | DNA strand>.) If the first '<symbol>' is used, it will be used as the name of the new DNA strand. (This symbol may have been used previously in a DNA context, but not as an operator or gene.) If not, its name will be "_dna<#>", where <#> is the lowest possible integer >=0 for which no previous symbol of that form exists.

The definition of a DNA strand is 'an ordered list of DNA elements', and can affect the rates of the elements it contains: if an element's initialization formula, assignment rule, or kinetic law (for reactions/genes) contains an ellipsis ("...") meaning 'the rate of the DNA element upstream of this element', it is the DNA strand that supplies the identity of the upstream element. If an element is found in multiple DNA strands, its overall rate is equal to the sum of the rates within each individual element (whether or not the element rate contains an ellipsis).

DNA strands are singletons: a DNA strand may itself be a member of one other DNA strand, but not multiple DNA strands.

If a DNA strand is prepended by a '--', Antimony considers it to be 'upstream open'. If it is suffixed by a '--', it is considered to be 'downstream open'. The only difference to the parser is that if a <module> contains exactly one DNA strand that is 'upstream open', that module's name may be used in the definition of a DNA strand where it is downstream of another element. In this case, that DNA strand is place in the containing strand. If a module contains exactly one DNA strand that is 'downstream open', that module's name may be used in the definition of a DNA strand where it is upstream of another element. Again, that DNA strand is used in the module's place in the containing strand. If a module appears in a single DNA strand with both upstream and downstream elements, that module must contain exactly one DNA strand which is both upstream and downstream 'open', and no other DNA strands which are either upstream or downstream 'open'.

<event definitions>

Defines an event (value changes when a condition is met).

[<symbol> : ] at|@ <boolean expression> : [<return>] <symbol> = <equation> [: [<return>] <symbol> = <equation> ]...

If the first '<symbol>' is used, it will be used as the name of the new event. (This symbol must not have been used previously in any context.) If not, its name will be "_E<#>", where <#> is the lowest possible integer >=0 for which no previous symbol of that form exists.

After the <boolean expression> (see below) is a list of assignments that are to happen when the event condition holds true for the first time. The equation is to be assigned to the symbol, which must not be const. (If the symbol was previously undefined for constness, it will now be defined to be variable.)

<boolean expression>

An <equation> which returns a 'true' or 'false'. Expressions are judged whether they are boolean based on libSBML's parser.

<synchronizations>

Particularly useful to 'connect' submodules, a synchronization claims that two elements are actually the same thing:

<symbol> is <symbol>

The two symbols are defined to be actually the same thing, with the second symbol taking precedence. In the final output for this module, only the second symbol will appear. Any characteristic of the first symbol for which that characteristic of the second symbol is undefined or less specific, the second symbol now embodies. For example, if the first symbol is a reaction, and the second symbol is a formula, after this synchronization, the second symbol will be used, and will now be defined as a reaction. If both symbols are defined by conflicting characteristics, the second symbol will take precedence. In our previous example, if the first symbol is a reaction with a defined reaction rate, and the second symbol is a formula with a different rate equation, the rate of the resulting reaction will be the second symbol's original rate.

Two symbols of conflicting types may not be synchronized: a species may not be synchronized with a reaction, for example.

<display names>

<symbol> [ * <formula> ] is <textstring> [ / <formula>]

Provides an alternate way for clients to display the name of a symbol. When translated to SBML, the normal name becomes the 'id', which must be unique and follow certain naming conventions (the same ones used here for <symbols>), and this becomes the 'name'. Any text is allowable in a display name, and it need not be unique.

Either the '* <formula>' or the '/ <formula>' constructs (but not both) may be used to define a conversion factor for the syncronization, such that the first symbol times the conversion factor is equal to the second symbol.

<deletions>

Removes a symbol from the model entirely.

delete <symbol>

The <symbol> in question must be an element of a submodel. This line will remove the element from the submodel along with any assignments to that variable, and will clear any reactions or equations that used that symbol: if 'A.x' is removed, and the submodel used 'x' in an assignment, that assignment will be cleared. If 'x' was a species used in a reaction, that reaction will be removed.