Biocham 4.0 Reference Manual

Contents

Chapter 1
Getting Started

1.1. Overview

The Biochemical Abstract Machine (Biocham) is a software environment for modeling and analyzing biochemical systems. Biocham is mainly composed of:
Biocham is a free software protected by the GNU General Public License GPL version 2. This is an Open Source license that allows free usage of this software.
about.

1.2. Installing and Running Biocham Locally

1.3. About this manual

This reference manual (and its extended version for developpers) is automaticaly generated from the source code of Biocham. The syntax of Biocham is described with formal grammar rules which define new syntactic tokens from primitive tokens such as atom (i.e. string), number, term (e.g. atom(..., ...)). For instance, the syntax of an input or output file is just the syntax of an atom in both cases, but they are distinguished in this manual for documentation purposes:
input_file ::=
| atom
output_file ::=
| atom

Chapter 2
Syntax of Biocham Reaction Systems

2.1. Biochemical objects

concentration ::=
time ::=
name ::=
| atom
parameter ::=
| atom
function_prototype ::=
| term
object ::=
| atom

2.2. Reaction and transport rules

reaction ::=
basic_reaction ::=
solution ::=
| _
kinetics ::=
condition ::=
| true
| false
| not condition
arithmetic_expression ::=
| [ object ]
| product( term in term , arithmetic_expression )
| name

Chapter 3
Syntax of Biocham Influence Systems

influence ::=
basic_influence ::=
inputs ::=
enumeration ::=
| _

Chapter 4
Syntax of Biocham Temporal Properties

4.1. Boolean temporal logic CTL

ctl ::=
| EX( ctl )
| EF( ctl )
| EG( ctl )
| EU( ctl , ctl )
| AX( ctl )
| AF( ctl )
| AG( ctl )
| AU( ctl , ctl )
| not ctl
| ctl /\ ctl
| ctl \/ ctl
| ctl -> ctl
| reachable( ctl )
reachable(φ) is equivalent to EF(φ)
| oscil( ctl )
oscil(φ) is equivalent to AG((φ -> EF(not φ)) /\ (not φ -> EF(φ))), i.e. AG(EF(φ) /\ EF(not φ))
| checkpoint( ctl , ctl )
checkpoint(φ, ψ) is equivalent to not EU(not φ, ψ)
add_ctl(Formula: ctl).
Adds a CTL formula to the currently declared CTL specification.
delete_ctl(Formula: ctl).
Removes a CTL formula to the currently declared CTL specification.
delete_ctl.
Removes all formulae from the current CTL specification.
list_ctl.
Prints out all formulae from the current CTL specification.

4.2. First-order numerical temporal logic FOLTL(R)

foltl ::=
| X( foltl )
| F( foltl )
| G( foltl )
| not foltl
| U( foltl , foltl )
| W( foltl , foltl )
| foltl /\ foltl
| foltl \/ foltl
foltl_predicate ::=
foltl_expression ::=
| name
validity_domain(Formula: foltl).
solves a FOLTL(R) constraint on the current trace, i.e. computes the validity domain for the free variables that make the formula true on the numerical trace.

Chapter 5
Commands at Top-level

quit.
quits the interpreter.
Some commands (e.g., numerical_simulation/1) take named options as arguments. All the options can either be defined either locally for a single command or globally for the whole model. Options can be defined for a single command by adding additional arguments of the form Option: Value.
Example.
biocham: a->b.

biocham: a-<a.

biocham: present(a).

biocham: numerical_simulation(5,method:msbdf).

biocham: plot.

Options can be defined globally for the model with the command option(Option: Value, ..., Option: Value). Local options take precedence over global options.
list_options.
lists the set of options defined in the current model.

5.1. Loading, listing, importing and exporting models

5.1.1. Biocham files

range ::=
ref ::=
| [ range , ... , range ]
| name
load(input_file).
acts as the corresponding load_biocham/1 / load_sbml/1 / load_ode/1 / load_trace/1, depending on the file extension (respectively .bc, .xml, .ode, .csv – assuming no extension is .bc).
add(input_file).
acts as the corresponding add_biocham/1 / add_sbml/1 / add_ode/1 / add_trace/1, depending on the file extension (respectively .bc, .xml, .ode, .csv – assuming no extension is .bc).
load_biocham(input_file).
opens a new model, loads the reaction rules and executes the commands (with the file directory as current directory) contained in the given Biocham .bc file. The suffix .bc is automatically added to the name if such a file exists.
add_biocham(input_file).
the rules of the given .bc file are loaded and added to the current set of rules. The commands contained in the file are executed (with the file directory as current directory).
export_biocham(output_file).
exports the current model into a .bc file.
new_model.
opens a new fresh model.
clear_model.
clears the current model.
list_models.
lists all open models.
list_current_models.
lists current models.
list_model.
lists the contents of the current Biocham model.
select_model({ref1, ..., refn}).
selects some models.
set_model_name(name).
changes the current model name.
delete([range1], ..., [rangen]).
deletes the listed elements from the model.
inherits(ref1, ..., refn).
makes the current model inherit from the given ancestor models.

5.1.2. SBML files

load_sbml(input_file).
acts as load_biocham/1 but importing reactions, parameters and initial state (and only that!) from an SBML .xml file.
add_sbml(input_file).
acts as add_biocham/1 but importing reactions, parameters and initial state (and only that!) from an SBML .xml file.
load_qual(input_file).
acts as load_biocham/1 but importing influences and initial state (and only that!) from an SBML3qual .sbml file.
add_qual(input_file).
acts as add_biocham/1 but importing influences and initial state (and only that!) from an SBML3qual .sbml file.

5.1.3. ODE files

oderef ::=
| name
new_ode_system.
creates an ODE system.
delete_ode_system(name).
deletes an ODE system.
set_ode_system_name(name).
sets the name of the current ODE system.
list_ode_systems.
lists the ODE systems of the current model.
select_ode_system(name).
selects an ODE system
ode ::=
add_ode(ode1, ..., oden).
If there is a current ODE system, adds the given set of ODEs to it. If there is no current ODE system, imports the reactions inferred from the given set of ODEs.
import_reactions_from_ode_system.
adds the reactions that match the current ODE system.
delete_ode(oderef1, ..., oderefn).
removes the given set of ODEs from the current ODE system.
list_ode.
returns the set of ordinary differential equations and initial concentrations (one line per molecule) associated to the current model.
Example.
biocham: a=>b.

biocham: list_ode.
[0] d(b)/dt=a
[1] d(a)/dt= -a
ode_system.
builds the set of ODES corresponding to the reactions of the current model.
import_ode(input_file).
imports a set of ODEs.
init(name1 = arithmetic_expression1, ..., namen = arithmetic_expressionn).
sets the initial value of a variable in the current set of ODEs.
load_ode_system(input_file).
acts as load_biocham/1 but importing a model from an ODE system.
add_ode_system(input_file).
acts as add_biocham/1 but importing a model from an ODE system.
export_ode_system(output_file).
exports the current ODE system.
add_function(term1 = term1, ..., termn = termn).
adds reactions to compute the result of a function of the current variables in the concentration of a new variable at steady state.
Example.
biocham: present(x,1).

biocham: present(y,3).

biocham: add_function(z=x+y).

biocham: list_reactions.
[0] _=[x]=>z
[1] _=[y]=>z
[2] z=>_
biocham: list_ode.
[0] d(z)/dt=x+y-z
[1] d(y)/dt=0
[2] d(x)/dt=0

5.1.4. GPAC files

Biocham can import GPAC (Shannon's General Purpose Analog Computer) and compile them into reaction systems. Only weak GPACs, in which the integration is with respect to time and not a variable, are considered. The syntax of weak GPACs is as follows:
wgpac ::=
wgpac_box ::=
| integral wgpac
wgpac_named ::=
compile_wgpac(wgpac, Rate: number).
compiles a wgpac into a biochemical system.
compile_wgpac({wgpac1, ..., wgpacn}, Rate).
compiles a set of wgpac.
Example. Cosine is generable:
biocham: compile_wgpac(a::integral integral-1*a,100).

biocham: present(a).

biocham: numerical_simulation(10,method:msbdf).

biocham: plot.

debug_iswgpac(W).
debug_iswgpacbox(B).

5.1.5. Transfer function files

transfer_polynomial ::=
| s
transfer_function ::=
enable_plus_minus_mode.
Each variable corresponds to two species: one for the negative part and one for the positive part.
disable_plus_minus_mode.
Each variable corresponds to one species.
which_plus_minus_mode.
Displays which mode is being used.
set_plus_minus_rate(Rate: number).
Set the annihilation rate between two complementary species.
set_kinetics_rate(Rate: number).
Set the final summator rate
Example.
biocham: set_kinetics_rate(1000).

biocham: compile_transfer_function([22,51,47,19,3],[30,66,67,36,10,1],a,b).

biocham: present(a).

biocham: numerical_simulation(20,method:msbdf).

biocham: plot.

5.1.6. Graphics files

5.1.7. Other files

5.2. Listing and editing reactions, influences and events

5.2.1. Reactions

add_reaction(reaction).
adds reaction rules to the current set of reactions. This command is implicit: reaction rules can be added directly in reaction models.
list_reactions.
lists the current set of reaction rules.

5.2.2. Influences

s.
add_influence(influence).
adds influence rules to the current set of influences. This command is implicit: influence rules can be added directly in influence models.
list_influences.
lists the current set of influence rules. If the current model is a reaction model, the influence rules are inferred from the reaction model (see influence_model/0).
influence_model.
creates a new influence model by inferring the influences between all molecular objects of the current reaction model
list_stable_states.
lists stable steady states of the state transition graph corresponding to the positive semantics of the current influence model.
list_tscc_candidates.
lists possible representative states of Terminal Strongly Connected Components (TSCC) of the state transition graph corresponding to the positive semantics of the current influence model.

5.2.3. Events

add_event(condition, parameter1 = arithmetic_expression1, ..., parametern = arithmetic_expressionn).
sets up an event that will be fired each time the condition given as first argument goes from false to true. This command is effective in numerical simulations only. Upon firing, the parameters receive new values computed from the expression. The initial values of the parameters are restored after the simulation.
Example.
biocham: 'MA'(k)for a=>b.

biocham: set_parameter(k=1).

biocham: add_event(b>0.5,k=0).

biocham: present(a).

biocham: numerical_simulation(2,maximum_step_size:0.001).

biocham: plot.

list_events.
lists all the declared events.

5.3. Listing and defining initial states, molecules and locations

5.3.1. Molecules

list_molecules.
lists all the molecules of the current model.
list_locations.
lists all the locations of the current model.

5.3.2. Initial state

list_initial_state.
lists the objects which are present (including their initial concentration) and absent from the initial state.
clear_initial_state.
makes undefined all objects possibly present or absent in the initial state.
present({object1, ..., objectn}).
Every object in [object1, ..., objectn] is made present in the initial state.
present({object1, ..., objectn}, concentration).
Every object in [object1, ..., objectn] is initialized with the given initial concentration. An initial value equal to 0 means absent.
absent({object1, ..., objectn}).
Every object in [object1, ..., objectn] is made absent in the initial state.
undefined({object1, ..., objectn}).
Every object in [object1, ..., objectn] is made possibly present or absent in the initial state.
make_present_not_absent.
makes all objects (appearing in the instances of the current set of rules) which are not declared absent, present in the initial state.
make_absent_not_present.
makes all objects (appearing in the instances of the current set of rules) which are not declared present, absent in the initial state.

5.4. Listing and declaring parameters, functions and aliases

5.4.1. Parameters

set_parameter(parameter1 = arithmetic_expression1, ..., parametern = arithmetic_expressionn).
sets the value of parameters.
show_parameter(parameter).
shows the value of parameter.
list_parameters.
shows the values of all known parameters.
delete_parameter({parameter1, ..., parametern}).
deletes some parameters

5.4.2. Functions

function(function_prototype1 = term1, ..., function_prototypen = termn).
sets the value of functions.
show_function(Functor: name).
shows the expression associated to the given function.
list_functions.
lists all known functions.
delete_function({name1, ..., namen}).
deletes some functions.

5.4.3. Aliases

alias(object1 = ... = objectn).
makes Objects be alternative names for the same object.
canonical(object).
makes object be the canonical representant for all its aliases.
list_aliases.
shows the values of all known aliases.
delete_alias(object).
makes object distinct from all other objects.

5.5. Simulations

5.5.1. ODE and stochastic simulations

The page http://www.gnu.org/software/gsl/manual/html_node/Stepping-Functions.html#Stepping-Functions gives a detailed description of all the numerical methods listed below.
method ::=
| rk2
| rk4
| rkf45
| rkck
| rk8pd
| rk1imp
| rk2imp
| rk4imp
| bsimp
| msadams
| msbdf
time ::=
numerical_simulation(time).
performs a numerical simulation up to a given time.
Options.
method: method
method for the numerical solver
error_epsilon_absolute: number
absolute error for the numerical solver
error_epsilon_relative: number
relative error for the numerical solver
initial_step_size: number
initial step size for the numerical solver
maximum_step_size: number
maximum step size for the numerical solver, as a fraction of time
precision: number
precision for the numerical solver

5.5.2. Traces and tables

load_table(input_file).
loads the given .csv file as a table.
export_table(output_file).
exports the current table into a .csv file.
list_tables.
lists the current set of tables.
select_table(table).
selects table to be the current table.
rename_table(name).
renames the current table.
delete_table({table1, ..., tablen}).
deletes some tables.
list_rows.
lists the rows of the current table.
list_columns.
lists the column names of the current table.
column ::=
| name
delete_column(column1, ..., columnn).
deletes the given columns from the current table.
rename_column(column, name).
renames the given column of the current table.
delete_row(number1, ..., numbern).
deletes the given rows from the current table.

5.5.3. Plotting the result of simulations

plot.
plots the current trace.
Example.
biocham: load(library:examples/mapk/mapk).

biocham: numerical_simulation(20,method:msbdf).

biocham: plot.

export_plot(FileTemplate).
saves the current trace into two files: FileTemplate.csv and .plot.
export_plot_to_png(output_file).
plots the current trace in a PNG file
export_plot_to_canvas(output_file, BaseOutputFile: output_file).
plots the current trace as a canvas element in an HTML file

5.6. Listing and editing graphs

reaction_graph.
Builds the reaction graph of the current model.
import_reactions_from_graph.
Updates the set of reactions of the current model with the current graph.
draw_reactions.
Draws the reaction graph of the current model. Equivalent to reaction_graph. draw_graph.
Example.
biocham: load(library:examples/mapk/mapk).

biocham: draw_reactions.

influence_graph.
builds the influence graph of the current model.
draw_influences.
Draws the influence graph of the current model.
Example.
biocham: load(library:examples/mapk/mapk).

biocham: draw_influences.

attribute ::=
| name = term
| name
edge ::=
| name -> name
edgeref ::=
| edge
new_graph.
Creates a new graph.
delete_graph(name).
Deletes a graph.
set_graph_name(name).
Sets the name of the current graph.
list_graphs.
Lists the graph of the current model.
select_graph(name).
Selects a graph
add_vertex(name1, ..., namen).
Adds new vertices to the current graph.
delete_vertex(name1, ..., namen).
Deletes a set of vertices from the current graph.
add_edge(edge1, ..., edgen).
Adds the given set of edges to the current graph. The vertices are added if needed.
delete_edge(edgeref1, ..., edgerefn).
Deletes a set of edges from the current graph.
list_edges.
Lists the edges of the current graph.
list_isolated_vertices.
Lists the isolated vertices of the current graph.
list_graph_objects.
Lists the edges and the isolated vertices of the current graph, and their attributes if any.
graph_object ::=
| edge
| name
set_attribute({graph_object1, ..., graph_objectn}, attribute).
Adds an attribute to every vertex or edge in the given set. The vertices and the edges are added if needed.
place(name1, ..., namen).
Sets that the vertices [name1, ..., namen] are places.
transition(name1, ..., namen).
Sets that the vertices [name1, ..., namen] are transitions.
delete_attribute(graph_object, Attribute: name).
Removes an attribute from graph_object.
list_attributes(graph_object).
List the attributes of graph_object.
draw_graph.
Draws the current graph.
export_graph(output_file).
Exports the current graph in a file. The format is chosen from the suffix: .dot, texttt{.pdf}, texttt{.eps}, texttt{.ps}, texttt{.png} or texttt{.svg} – assuming no extension is .dot.

5.7. Static analyses

5.7.1. Algebraic invariants, conservation laws and P-invariants

add_conservation(Conservation: solution).
declares a new mass conservation law for all molecules given with the corresponding weight in Conservation. During a numerical simulation, one of those variables will be eliminated thanks to this conservation law. Be careful if you declare conservation laws and then plot the result of a previous simulation, the caption might not be correct. When added, the conservation law will be checked against the reactions (i.e. purely from stoichiometry), if that fails against the kinetics. Since these checks are not complete, even a failure will be accepted with a warning.
delete_conservation(Conservation: solution).
removes the given mass conservation law.
delete_conservations.
removes all mass conservation laws.
list_conservations.
prints out all the mass conservation laws.
check_conservations.
checks all conservation laws against reactions, and if necessary kinetics (see also add_conservation/1).
search_conservations.
calls search_conservations/1 with the default size of 4.
search_conservations(integer).
computes and displays the P-invariants of the system up to the maximal size integer. Such P-invariants are particular mass conservation laws that are independent from the kinetics.

5.7.2. Model reduction detection

5.8. Boolean dynamical analyses

5.8.1. Verification of CTL properties

export_nusmv(output_file).
exports the current Biocham set of reactions and initial state in an SMV .smv file.
Options.
boolean_semantics: boolean_semantics
Use positive or negative boolean semantics for inhibitors.
boolean_semantics ::=
| positive
| negative
nusmv_counter_example ::=
| yes
| no
nusmv_initial_states ::=
| some
| all
check_ctl(Query: ctl).
evaluates the Query on the current model by calling the NuSMV model-checker. As is usual in Model-Checking, the query is evaluated for all possible initial states (Ai in Biocham v3). This can be changed via the nusmv_initial_states option.
Options.
nusmv_initial_states: nusmv_initial_states
Consider that a query is true if verified for all/some initial states.
nusmv_counter_example: nusmv_counter_example
Compute a counter-example for a query when possible.
boolean_semantics: boolean_semantics
Use positive or negative boolean semantics for inhibitors.
Example.
biocham: present(a).

biocham: absent(b).

biocham: a=>b.

biocham: a+b=>a.

biocham: check_ctl('EX'(not a\/'EG'(not b)),nusmv_counter_example:yes).
EX(not a\/EG(not b)) is true
biocham: check_ctl('EG'(not b),nusmv_counter_example:yes).
Trace:
a	b
TRUE	FALSE

EG(not b) is false
biocham: check_ctl(reachable(b),nusmv_counter_example:yes).
reachable(b) is true
check_ctl.
Checks the current CTL specification (i.e., the conjunction of all formulae of the current specification).

5.8.2. CTL based model reduction and revision

revise_model(Query: ctl).
Use theory-revision on the current model to satisfy the query given as argument. cf. CCFS05tcsb.
revise_model.
Use theory-revision as above, using the currently defined CTL specification.

5.9. Numerical dynamical analyses

5.9.2. Sensitivity of FOLTL(R) properties

5.9.3. Robustness of FOLTL(R) properties

Chapter 6
Index

A

C

D

E

F

I

L

M

N

O

P

Q

R

S

T

U

V

W

Chapter 7
Bibliography