PyCellChemistry 1.0 Online Reference Manual

This page refers to an earlier version of the sofware. Click here for the latest version.

Getting started

Platforms:

PyCellChemistry has been tested under Python 2.6 and 2.7, on MacOS and Linux. The software is designed to be as platform independent as possible, so we expect that it should run on other platforms as well, although we had no opportunity for extensive testing so far.

Requirements:

The core of PyCellChemistry depends only on numpy. Most of the examples generate tab-separated output files that can be plotted with your favorite plotting tool (R, Matlab, Excel, ...)
Optional shell scripts are provided in the src/scripts folder, for convenience. These scripts run the various artificial chemistry examples and plot the results. Many of them rely on gnuplot for plotting, some on python matplotlib.

Downloading the package:

Source code in zip format: pycellchem-1.0.zip
Source code in compressed tar format: pycellchem-1.0.tgz

Installing and running:

Unpack the file pycellchem-1.0.tar.gz or pycellchem-1.0.zip at your favorite location.

Go to the pycellchem-1.0/src folder and execute the desired example from the command line:

   cd pycellchem-1.0/src

   python Chameleons.py > chameleons.gr

   python MatrixChem.py > matchem.gr

Reference Manual

Basic classes:

Located in the src/artchem/ folder, these python modules are not meant to be invoked directly. Instead, they are imported from the modules implementing the chemistries that need them. These modules contain classes that implement the core functionalities of artificial chemistries. So far only well-mixed and compartment-based chemistries are available.

BinaryStrings.py: routines to manipulate binary strings in the form of arbitrarily long integers.
Multiset.py: a bag of chemicals represented as a multiset of objects; these objects are typically strings, often binary strings.
KeyMultiset.py: a multiset indexed by a given key; the key is usually a substring of the molecule, akin to a binding site, but it can also be a shorter tag that is computed from the information within the molecule.
Reaction.py: explicit representation of chemical reactions using multisets: a reaction is made of an educt multiset, a product multiset, and a rate coefficient k.
ReactionParser.py parses chemical reactions in text format, such as: "A + 2 B --> 3 C , k=2.5", and translates them into Reaction objects.
ReactionVessel.py: a reaction vessel for well-mixed ACs with a fixed set of molecular species and reactions. Two algorithms are included: WellStirredVessel (for deterministic ODE integration), and GillespieVessel (for stochastic simulations).
Cell.py: an implementation of hierarchical compartments that grow and divide.

AC Examples:

Located in the src/ folder, these python modules implement various examples of artificial chemistries found in the literature.

Chameleons.py: a colored chameleon chemistry, where molecules are chameleons that change color when they meet each other.
Dimer.py: a reversible dimerization reaction, where two monomers combine into a dimer, then the dimer breaks down again into monomers.
DimerStoch.py: stochastic implementation of the reversible dimerization example.
NumberChem.py: a number chemistry in which molecules are integer numbers that decompose each other in reactions, converging to a "soup" of prime numbers.
MatrixChem.py: a chemistry where molecules are binary strings that "fold" into 2D matrices that multiply each other [Banzhaf1993]; this is a constructive AC that may result in the formation of closed and self-maintaining molecule sets (organizations, [Dittrich2007]).
Logistic.py: an AC implementation of the logistic equation, with comparison between ODE and SSA.
Lotka.py: an AC implementation of the classical predator-prey Lotka-Volterra system, ODE or SSA.
Repressilator.py: stochastic simulation of the repressilator genetic regulatory network (GRN) [Elowitz2000].
Evolution.py: evolutionary dynamics with ACs (not invoked directly, but from the Quasispecies.py and Tournament.py examples).
Quasispecies.py stochastic implementation of a quasispecies evolutionary dynamics [Eigen1977], on top of Evolution.py.
Tournament.py: genetic algorithm with tournament selection implemented as an artificial chemistry, on top of Evolution.py.
NKlandscape.py: a simple implementation of Kauffman's NK model of rugged fitness landscapes [Kauffman1993].
Fraglets.py: an interpreter for the Fraglets language [Tschudin2003].
NetFraglets.py: networked Fraglets, with CDP example.
Disperser.py: an artificial chemistry for load balancing in distributed systems [Meyer2009].
HighOrderChem.py: a simplified high-order chemistry in which the reaction rules are also molecules in a multiset, and are written as strings containing a python method call (not to be invoked directly, but to be used to build other chemistries on top of it, as illustrated so far by NumberChemHO.py and MolecularTSP.py).
NumberChemHO.py: a reimplementation of NumberChem using HighOrderChem.
MolecularTSP.py: a reimplementation of the Molecular Travelling Salesman algorithm [Banzhaf1990] using HighOrderChem.

Shell scripts to run the examples:

Located in the src/scripts/ folder, these shell scripts (bash) automate the process of invoking the corresponding python programme for the chemistry and plotting the obtained results.

chameleons.sh: to run Chameleons.py
dimer.sh: to run Dimer.py
dimerstoch.sh: to run DimerStotch.py
numchem.sh: to run NumberChem.py or NumberChemHO.py
matchem.sh: to run MatrixChem.py
logistic.sh: to run Logistic.py
lotka.sh: to run Lotka.py
repressilator.sh: to run Repressilator.py
quasispec.sh: to run Quasispecies.py
tournament.sh: to run Tournament.py
nk.sh: to run NKlandscape.py
disperser.sh: to run Disperser.py
moltsp.sh: to run MolecularTSP.py

Writing your own AC

The tutorials and examples provided are intended to provide some basic concepts and initial ideas about ways to program new ACs. One of the best ways to learn is via examples, hence we suggest that after playing with the examples, you start your own chemistry by modifying or extending some of these examples. We believe that once the core elements of your chemistry operate well in Python, it will be easier for you to move on to a computationally more efficient implementation in C, C++, Java or other programming languages.

Contributing

We welcome any ideas and contributions. PyCellChemistry is free software, under the terms of the GNU General Public License (GPL). It has primarily an educational goal. We hope that it will foster a community of developers around common methods and best-practice procedures to program ACs, to learn how to program ACs, and to improve their accessibility, such that new and relevant applications can be more easily constructed based on the AC concept.

In the future we should set up a repository for collaborative software development, for instance from github or sourceforge. For now however, please send any bug reports or other remarks concerning the software or the web site to Lidia Yamamoto.

Bibliography

W. Banzhaf. The "molecular" traveling salesman. Biological Cybernetics, 64(1):7-14, 1990.

W. Banzhaf, Self-replicating sequences of binary numbers, Computers and Mathematics with Applications, 26:1-8, 1993.

W. Banzhaf, Self-replicating sequences of binary numbers. Foundations I: General, Biological Cybernetics, August 1993, Volume 69, Issue 4, pp 269-274.

Dittrich, P. and Ziegler, J. and Banzhaf, W., Artificial Chemistries -- A Review, Artificial Life, volume 7, number 3, 2001, p. 225-275,

P. Dittrich and P. Speroni di Fenizio, Chemical Organisation Theory, Bulletin of Mathematical Biology 69(4):1199-1231 (2007).

M. Eigen and P. Schuster. The hypercycle: A principle of natural selforganization, Part A: Emergence of the hypercycle, Naturwissenschaften, 64(11):541-565, November 1977.

M. B. Elowitz and S. Leibler, A synthetic oscillatory network of transcriptional regulators, Nature, 403:335-338, January 2000.

Richard J. Field and Richard M. Noyes, "Oscillations in chemical systems IV: Limit cycle behavior in a model of a real chemical reaction", Journal of Chemical Physics, volume 60, number 5, March 1974, p. 1877-1884.
Fontana, W., Buss, L.W.: The arrival of the fittest: Toward a theory of biological organization. Bulletin of Mathematical Biology, 56(1):1-64 (1994).

Gillespie, D. T., Stochastic Simulation of Chemical Kinetics, Annual Reviews of Physical Chemistry, volume 58, 2007, p. 35-55.

Gillespie, D. T., Exact Stochastic Simulation of Coupled Chemical Reactions, Journal of Physical Chemistry, volume 81, 1977, p. 2340-2361.

S. A. Kauffman. Autocatalytic sets of proteins, Journal of Theoretical Biology, 119:1-24,1986.

S. A. Kauffman. The origins of order: Self-organization and selection in evolution. Oxford University Press, 1993.

T. Meyer, L. Yamamoto, and C. Tschudin, An artificial chemistry for networking, Bio-Inspired Computing and Communication, volume 5151 of Springer LNCS, 2008, p. 45-57.

T. Meyer and C. Tschudin, Chemical networking protocols, Proc. 8th ACM Workshop on Hot Topics in Networks (HotNets-VIII), Oct. 2009.

M. Nowak, Evolutionary Dynamics: Exploring the Equations of Life, Belknap Press of Harvard University Press, 2006.

C. Tschudin, Fraglets: A Metabolistic Execution Model for Communication Protocols, Proc. 2nd Annual Symposium on Autonomous Intelligent Networks and Systems (AINS), Menlo Park, USA, July 2003.

P. Winkler. Puzzled: Understanding relationships among numbers. Communcations of the ACM, 52(5):112, 2009.

P.Winkler. Puzzled: Solutions and sources. Communcations of the ACM, 52(6):103,2009.

Olaf Wolkenhauer, Mukhtar Ullah, Walter Kolch, Kwang-Hyun Cho, Modelling and Simulation of Intracellular Dynamics: Choosing an Appropriate Framework, IEEE Transactions on Nano-Bioscience volume 3, number 3, 2004, p. 200-207.

Lidia Yamamoto and Wolfgang Banzhaf, Emergence in Artificial Chemistries, talk at the 4th Conference on Emergence in Chemical Systems, Anchorage, Alaska, June 2015.

Last updated: September 15, 2015, by Lidia Yamamoto