PyCellChemistry Online Documentation

About PyCellChemistry

PyCellChemistry is a software package for the design and development of Artificial Chemistries (ACs) and for the exploration of their behavior. It is intended to facilitate people to program their own artificial chemistries in Python, a programming language that is especially accessible and easy to learn. The package illustrates how to implement artificial chemistries through simple examples.

Beware that in contrast with related AC packages, PyCellChemistry does not focus on the usage a specific chemistry, but on the implementation of a variety of chemistries. Therefore the user of PyCellChemistry must have at least some notions of programming, especially object-oriented programming. Some guidelines for beginners are available here.

The package has been designed with a minimalistic philosophy in mind. Our main concerns were an easy installation and programming, enabling a quick start for new users. Therefore we have tried to reduce the amount of external libraries and packages required to a minimum. Hence the basic package does not offer fancy graphics and user interfaces, in order to avoid dependency on elaborated graphics support.

However, since graphics and visualization are also important in artificial chemistries, we are taking steps to integrate graphics into the system in an incremental way: first of all, a few optional shell scripts are included in the package, that visualize various results using gnuplot and python matplotlib. We are also envisaging an extension of the package that would feature optional graphics support through, for instance, VPython. A collection of resources including graphics support for Python is also included here.

Disclaimer: The package is provided as is, without any guarantees. Although we have done our best to offer a functional package, it is still possible that bugs persist to date. Beware that the package has been designed for maximum ease of use and didactic content, and not necessarily for maximum efficiency. We believe that the main usage of this package is as a rapid prototyping tool to test and compare a variety of ACs.

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

See the documentation below for more examples and more detailed information about each example. Some introductory slides can also be found in [Yamamoto2015].

Warming up

The first step to build an artificial chemistry is to decide whether it should be constructive or not:

A constructive chemistry enables new molecule species to be created which had not been "pre-programmed" in the system beforehand. The creation of such novel species opens up the possibilities for new reaction pathways too. AlChemy [Fontana1994], autocatalytic sets of proteins [Kauffman1986], and the matrix chemistry [Banzhaf1993] are examples of constructive chemistries.
A nonconstructive chemistry, on the other hand, presents a fixed set of molecular species and their reactions, well-known by design time. This is the case of designed molecular circuits such as the repressilator [Elowitz2000] or the Oregonator model of the Belousov-Zhabotinsky reaction [Field1974].

Building a nonconstructive chemistry:

A constructive chemistry:

The Number Chemistry example

Delving deeper into the chemistries

More details about the other chemistries in the package will appear in this section soon. Meanwhile a reference manual for each module is provided below.

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: July 14, 2015, by Lidia Yamamoto