CAGE

Category-driven Algorithm for the Generation of Emulations

Summary

CAGE is a Matlab tool which interacts with the recently proposed reducer of chemical reaction networks (CRNs) ERODE to compute all emulations between two CRNs.

Given a source and a target chemical reaction network (CRN), an emulation is a function from the species of the source CRN to those of the target one such that the corresponding concentrations coincide at all time points if initialized equally.

The tool implements a novel algorithm which exploits a geometric characterization of emulation. It currently supports the continuous-state semantics of chemical reaction networks (CRNs) based on the law of mass action, providing a system of nonlinear ordinary differential equations (ODEs) associating one ODE variable to each species of the CRN. However, the theory underlying CAGE is more general, and can be applied to any ODE system with a differentiable drift.

The tool currently supports a simple explicit .crn format described at the bottom of this page.

Publications

Download and Installation

A first prototype of our tool is available here.

CAGE does not require any installation process for machines running MATLAB_R2015 or superior. It is sufficient to add the absolute path of the jar file provided in the archive to MATLAB’s static java classpath as described here. In short:

  1. Type ‘prefdir’ in MATLAB’s console
  2. Navigate to the obtained path, and open (or create) the file ‘javaclasspath.txt’
  3. Add to the file a new line with the absolute path of the provided jar file

Usage

The tool accompanies the paper recently published at LICS’16Comparing Chemical Reaction Networks: A Categorical and Algorithmic Perspective.

For the sake of reproducibility, CAGE comes with the models discussed in the paper, stored in the folder “CRNNetworks”.

Emulations between two CRNs can be computed by just opening the MATLAB file “get_all_bdes.m”, and decommenting the corresponding commands, as documented in the file.


Example: computing all emulations from GW’ to AM

% GW' and union (GW',AM)
% Decomment this to calculate emulations from GW' to AM
n = javaMethod('loadCRN', crnreducer, 'CRNNetworks/gw-p.crn'); 
H = javaMethod('computeBB', crnreducer, ones(1,n))';
A = javaMethod('computeJacobian', crnreducer, H); 
crnunion = 'CRNNetworks/gw-p_and_am.crn';

GW’ consists of 12 species: y0, y1, y2, q0, q1, q2, r0, r1, r2, z0, z1, z2,  while AM consists of 3 species: x0, x1, x2.

As depicted in the output given below, there exist two emulations from GW’ to AM. The former relates

  • y0, q0, z2 and r2 to x0;
  • z0, y2, q2 and r0 to x2;
  • y1, q1, z1 and r1 to x1.

Instead, the second emulation relates

  • y0, q0, z2 and r2 to x2;
  • z0, y2, q2 and r0 to x0;
  • y1, q1, z1 and r1 to x1.
====== Emulation 1 =======================
The partition has 3 blocks out of 15 species:
Block 1, Size: 5
0-y0 
4-q0 
8-z2 
11-r2 
12-x0 

Block 2, Size: 5
1-z0 
3-y2 
6-q2 
9-r0 
13-x2 

Block 3, Size: 5
2-y1 
5-q1 
7-z1 
10-r1 
14-x1 
===========================================

====== Emulation 2 =======================
The partition has 3 blocks out of 15 species:
Block 1, Size: 5
0-y0 
4-q0 
8-z2 
11-r2 
13-x2 

Block 2, Size: 5
1-z0 
3-y2 
6-q2 
9-r0 
12-x0 

Block 3, Size: 5
2-y1 
5-q1 
7-z1 
10-r1 
14-x1 
===========================================

As shown in the above output, CAGE prints emulations in form of a block per species in the target CRN. Each block contains a species  of the target CRN (xi), together with all species of the source CRN mapped to it.

All CRNs stored in files with prefix “simp” have been encoded in a simplified but equivalent CRN, as discussed here.


Notes on supported input file formats: .crn format

CAGE currently supports an explicit .crn format for representing chemical reaction networks. The following is a commented example of a simple .crn file with 5 species and 4 reactions:

begin CRN
 #The optional list of parameters
 begin parameters
 a 2.0
 b 3.0
 end parameters

 #The mandatory list of reactions in form: "reagents -> products , rate"
 # where "rate" can be any arithmetic expression, possibly using the parameters or numbers
 begin reactions
 xA + xC -> xC + xE , a
 xB + xC -> xC + xE , a
 xC -> xA , b
 xD -> xB , b
 end reactions

 #The optional list of initial concentration of each species. Non listed species have assigned 0 as 
 #initial concentration.
 begin initialConcentrations
 xA 1.0
 xB 1.0
 xC 1.0
 xD 1.0
 xE 1.0
 end initialConcentrations

end CRN

About

For suggestions, remarks, bugs or requests please do not hesitate to contact any of us.

  • luca@microsoft.com
  • mirco.tribastone@imtlucca.it
  • max.tschaikowski@imtlucca.it
  • andrea.vandin@imtlucca.it