Biocham 4.0 Developer Manual

Contents

Chapter 1
Getting Started

1.1. Overview

1.1.1. doc.pl

doc(_).
Writes in the documentation (both the Reference Manual and the Developer Manual).
devdoc(_).
Writes in the Developer Manual.
grammar(_).
Declares a grammar predicate to be written in the documentation.

1.1.2. biocham.pl

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.
biocham_command.
Declares a command for the top-level.
biocham_command(_).
With a * : declares a command for the top-level that can take an unlimited number of arguments. The additional arguments are given as a list in the last parameter.

1.1.3. about.pl

about.

1.1.4. platform/current/platform.pl

1.2. Installing and Running Biocham Locally

1.2.1. commandline.pl

1.2.2. util.pl

name_variables(L).
instantiates a list of bindings returned by read_term/3's variable_names option (X = 'X').
name_anonymous(L).
associates the atom '_' to each variable in L.
name_variables_and_anonymous(Goal, VariableNames).
instantiates all variables in Goal, either through the VariableNames bindings or to the atom '_'.

1.2.3. counters.pl

1.3. About this manual

1.3.1. filename.pl

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

2.1.1. objects.pl

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

2.2. Reaction and transport rules

2.2.1. reaction_rules.pl

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

2.2.2. kinetics.pl

2.2.3. types.pl

Chapter 3
Syntax of Biocham Influence Systems

3.1. influence_rules.pl

Grammars

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

Public API

Chapter 4
Syntax of Biocham Temporal Properties

4.1. Boolean temporal logic CTL

4.1.1. ctl.pl

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)

4.2.1. foltl.pl

Commands
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.
Public API
Private predicates

Chapter 5
Commands at Top-level

5.1. toplevel.pl

Commands

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.

Public API

toplevel.
executes the toplevel loop.
command(Command).
executes the given command. It can be used to execute commands in the code while using (a part of) the Biocham syntax.
execute_command(Command).
executes the given command and prints an error message if it fails. The predicate itself always succeeds.
prompt(biocham: ).
unifies the argument with the current prompt.
set_prompt(NewPrompt).
changes the prompt.
option(Name, _Type, Value, _Doc).
defines an option for the command and gets its value.
list_model_options.
lists all the options in a loadable syntax (auxiliary predicate of list_model).

Private predicates

5.2. namespace.pl

Public API

Private predicates

5.3. Loading, listing, importing and exporting models

5.3.1. Biocham files

5.3.1.1. models.pl
Grammars
range ::=
ref ::=
| [ range , ... , range ]
| name
Commands
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.
Public API
Private predicates

5.3.2. SBML files

5.3.2.1. sbml_files.pl
Commands
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.
Public API
5.3.2.2. sbml_qual_files.pl
Commands
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.
Public API

5.3.3. ODE files

5.3.3.1. ode.pl
Grammars
oderef ::=
| name
Commands
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.
Public API
Private predicates
5.3.3.2. odefunction.pl
Commands
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.3.4. GPAC files

5.3.4.1. wgpac.pl
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.3.5. Transfer function files

5.3.5.1. transfer_function.pl
Grammars
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
compile_transfer_function(F, U: object, Y: object).
compile a transfer function in variable s into a chemical filter.
compile_transfer_function(NL, DL, U: object, Y: object).
compile a transfer function into a chemical filter.
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.3.6. Graphics files

5.3.7. Other files

5.4. Listing and editing reactions, influences and events

5.4.1. Reactions

5.4.1.1. reaction_editor.pl
Commands
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.
Public API
is_reaction_model.
succeeds if the current model is a reaction model (i.e., does not contain any influence rules).
list_model_reactions.
lists all the reaction rules in a loadable syntax (auxiliary predicate of list_model).

5.4.2. Influences

5.4.2.1. influence_editor.pl
s.
Commands
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
Public API
is_influence_model.
succeeds if the current model is an influence model (i.e., does not contain any reaction rules).
check_influence_model.
succeeds if the current model is an influence model (i.e., does not contain any reaction rules) and throws an exception otherwise.
list_model_influences.
lists all the influence rules in a loadable syntax (auxiliary predicate of list_model).
influence(InfluenceRule, Force, PositiveInputs, NegativeInputs, Sign, Output).
builds or decomposes an influence rule.
Private predicates
5.4.2.2. influence_properties.pl
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.4.3. Events

5.4.3.1. events.pl
Commands
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.
Private predicates
list_model_events.
lists all the events in a loadable syntax (auxiliary predicate of list_model).

5.5. Listing and defining initial states, molecules and locations

5.5.1. Molecules

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

5.5.2. Initial state

5.5.2.1. initial_state.pl
Commands
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.
Public API
list_model_initial_state.
lists the initial state in a loadable syntax (auxiliary predicate of list_model).
Private predicates

5.6. Listing and declaring parameters, functions and aliases

5.6.1. Parameters

5.6.1.1. parameters.pl
Commands
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
Public API
list_model_parameters.
lists all the parameters in a loadable syntax (auxiliary predicate of list_model).

5.6.2. Functions

5.6.2.1. functions.pl
Commands
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.
Public API
list_model_functions.
lists all the functions in a loadable syntax (auxiliary predicate of list_model).

5.6.3. Aliases

5.6.3.1. aliases.pl
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.7. Simulations

5.7.1. ODE and stochastic simulations

5.7.1.1. arithmetic_rules.pl
5.7.1.2. formal_derivation.pl
5.7.1.3. gsl.pl
Public API
Private predicates
5.7.1.4. numerical_simulation.pl
Grammars
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 ::=
Commands
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
Private predicate

5.7.2. Traces and tables

5.7.2.1. tables.pl
Commands
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.
Public API
Private predicates

5.7.3. Plotting the result of simulations

5.7.3.1. plot.pl
Commands
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
Public API
Private predicates

5.8. Listing and editing graphs

5.8.1. reaction_graphs.pl

Commands
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.

Public API
Private predicates

5.8.2. influence_graphs.pl

Commands
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.

Public API
Private predicates

5.8.3. graph_editor.pl

Grammars
attribute ::=
| name = term
| name
edge ::=
| name -> name
edgeref ::=
| edge
Commands
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.
Public API
Private predicates

5.8.4. graphviz.pl

Commands
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.
Public API
Internal predicates

5.9. Static analyses

5.9.1. Algebraic invariants, conservation laws and P-invariants

5.9.1.1. conservation_laws.pl
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.
solution_to_conservation(Solution, Conservation).
transforms a solution to a factorized list of coeff*object
5.9.1.2. invariants.pl

5.9.2. Model reduction detection

5.10. Boolean dynamical analyses

5.10.1. Verification of CTL properties

5.10.1.1. nusmv.pl
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.10.2. CTL based model reduction and revision

5.10.2.1. revision.pl
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.11. Numerical dynamical analyses

5.11.2. Sensitivity of FOLTL(R) properties

5.11.3. Robustness of FOLTL(R) properties

Chapter 6
Index

A

B

C

D

E

F

G

I

L

M

N

O

P

Q

R

S

T

U

V

W

Chapter 7
Bibliography