AChemKit Package

AChemKit Package

Detailed documentation for all the components of AChemKit. It is generated directly from the source code, so should be up-to-date.

bucket Module

Library for working with Bucket objects; instances of a simulation of an Artificial Chemistry.

Various tools for going between ReactionNetwork and Bucket objects, as well an analysing the data within Bucket objects.

class AChemKit.bucket.Bucket(events)

Bases: object

Event history of a simulation of an Artificial Chemistry.

classmethod from_file(file)

Alternative constructor that accepts a file() object (or equivalent).

Source must be formatted as a bucket log file, see bucket_file_format.

classmethod from_filename(infilename)

Wrapper around from_file() that opens the provided filename as a file to read.

classmethod from_string(instr)

Wrapper around from_file() that uses StringIO.

reactionnet

A property that generates and caches a ReactionNetwork object representing the reaction network exhibited by this bucket.

Rates are calculated based on repeats of events in this bucket. This may have a large sampling error depending on how many repeates there were.

class AChemKit.bucket.Event(time, reactants, products)

Bases: object

Mini-class for tracking events (instances of a reaction) within a Bucket.

Supports comparisons, is hashable, is immutable.

properties Module

Functions for testing properties of particular reaction networks.

These functions expect an object of class AChemKit.reactionnet.ReactionNetwork or subclass or something with an equivalent API. It does not enforce this however, so you may use custom classes with the same API.

Some of these properties have logical prerequisites, but these are not tested for explicitly.

AChemKit.properties.has_catalysis_direct(rn)

Tests for reactions where some species is both consumed and produced by the same reaction.

For example:

A + C -> B + C
AB + C -> A + B + C
AChemKit.properties.has_decomposition(rn)

Tests for reactions where reactants combine to produce more products.

For example:

AB -> A + B
AB + C -> A + B + C
AChemKit.properties.has_divergence(rn)

Tests for divergent reactions.

Divergent reactions are where the same reactants have multiple possible collections of products

AChemKit.properties.has_reversible(rn)

Tests for a pair of reactions where the products of one is the reactants of the other and visa vera.

For example:

A + B -> AB
AB -> A + B
AChemKit.properties.has_synthesis(rn)

Tests for reactions where reactants combine to produce fewer products.

May also be called a combination reaction.

For example:

A + B -> AB
A + B + C -> AB + D
AChemKit.properties.has_varying_rates(rn)

Tests that the reaction network has different rates for different reactions.

To get the range of rates a reaction network spans, use:

span = max(rn.rates.values())-min(rn.rates.values())
AChemKit.properties.not_conservation_mass(rn)

Tests for violation of conservation of mass.

Note, we can show that a reaction network breaks conservation of mass, but not prove that it obeys it.

This is done by arranging all the molecules into a partially ordered set - a tree from largest to smallest. If this cannot be done, then conservation of mass must be violated. If this can be done, then conservation of mass may or may not apply - it cannot be said for certain.

This requires that each molecular species can be separated into individual atoms. If this is not possible, then this function will not work.

NEEDS TO BE WRITTEN

(Credit to Adam Nellis for algorithm)

properties_wnx Module

Various functions that interact with NetworkX (http://networkx.lanl.gov/)

AChemKit.properties_wnx.MultiDiGraph_make_flow(G, sizeprop=0.5, catalysts=True)

Creates a flow network from a MultiDiGraph (usually created by ReactionNetwork_to_MultiDiGraph).

sizeprop is the proportion if the larger molecule that must be contained in the smaller one.

catalysts determines if catalsysts should be considered when looking at edges between reactants and products. If this is false, then molecules that are both in the reactants and the products are removed and do not flow.

AChemKit.properties_wnx.ReactionNetwork_to_MultiDiGraph(net)

Converts a ReactionNetwork (or class with same interface) to a MultiDiGraph.

Converts each reaction into a node, and each molecular species into a node.

AChemKit.properties_wnx.find_cycles(G)

Find some of the cycles in G.

Does this by splitting it into strongly connected subgraphs, then for each edge of each node find the shorted path exists that goes the other way. If it does, then it is a cycle.

Once cycles are found, they are ordered so the lowest node is first. Repeated cycles are ignored.

Ineffeicient algorithm, needs optimization for large highly-connected graphs.

randomnet Module

Functions that construct random ReactionNetwork instances by various methods.

This is designed to provide null hypothesis data for various situations and metrics. As with random graphs, there is no single best way to generate a random reaction network.

AChemKit.randomnet.Linear(natoms, maxlength, pform, pbreak, directed=True, rates=1.0, cls=<class 'AChemKit.reactionnet.ReactionNetwork'>, rng=None)

Generates a random ReactionNetwork from molecules that are strings of atoms and can join together or break apart.

Based on the paper Autocatalytic sets of proteins. 1986. Journal of Theoretical Biology 119:1-24 by Kauffman, Stuart A. but without the explicit catalytic activity.

Arguments:

natoms
Number of atoms to use. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution), or a dict of value:weight which will be sampled from.

Note

AChemKit.reactionnet.ReactionNetwork tracks molecules by their reactions, so if a molecule is not part of any reaction it will not appear at all e.g. in seen.

maxlength
Maximum number of atoms in a molecule. If this is None, then they are unbounded; this might cause problems with a computational explosion. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution), or a dict of value:weight which will be sampled from.
pform
Probability that a pair of molecules will join together per orientation. Must be between 0 and 1. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution), or a dict of value:weight which will be sampled from.
pbreak
Probability that any pair of atoms will break. Must be between 0 and 1.Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution), or a dict of value:weight which will be sampled from.
directed
If false, molecules have no intrinsic direction so AlphBeta is equivlanet to BetaAlpha.
rates
Rate of each reaction in the reaction network. Can be a single value, or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution), or a dict of value:weight which will be sampled from.
cls
Alternative class to use for constructing the return rather than AChemKit.reactionnet.ReactionNetwork.
rng
Random number generator to use. If not specifed, one will be generated at random.
AChemKit.randomnet.Uniform(nmols, nreactions, nreactants, nproducts, rates=1.0, cls=<class 'AChemKit.reactionnet.ReactionNetwork'>, rng=None)

Generates a random ReactionNetwork by assigning reaction randomly between all molecular species.

Arguments:

nmols
Number of molecules in the reaction network. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution).

Note

AChemKit.reactionnet.ReactionNetwork tracks molecules by their reactions, so if a molecule is not part of any reaction it will not appear at all e.g. in seen. This could lead to differences from nmols.

nreactions
Number of reaction in the reaction network. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution).

Note

The value of nreactions is the number of times a reaction will be added to the ReactionNetwork. If it is already in the ReactionNetwork, it will be replaced. This can lead to AChemKit.reactionnet.ReactionNetwork with less than nreactions reactions.

nreactants

Number of reactants for each reaction in the reaction network. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution).

Note

If this is a tuple/list it will be sampled for each reaction.

nproducts

Number of products for each reaction in the reaction network. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution).

If this is None, then nreactants must be a list/tuple of tuples of (nreactants, nproducts) pairs that will be uniformly sampled from. Or nreactants must be a dictionary with keys of (nreactants, nproducts) and values of weightings, which will be sampled from.

Note

If this is a tuple/list it will be sampled for each reaction.

rates

Rate of each reaction in the reaction network. Can be a single value or a tuple/list which will be uniformly sampled from (duplicates can be used to give a non-uniform distribution).

Note

If this is a tuple/list it will be sampled for each reaction.

cls
Alternative class to use for constructing the return rather than AChemKit.reactionnet.ReactionNetwork.
rng
Random number generator to use. If not specifed, one will be generated at random.

These arguments can be a single value, a tuple/list which will be uniformly sampled from, or a dictionary of value/weighting which will be sampled from

For example:

Uniform(5,3,2,1) will generate 5 molecules with 3 reactions between them where each reaction has two reactants and one product.

Uniform(5,3,(1,2), (1,2)) will generate 5 molecules with 3 reactions between them where each reaction has one or two reactants and one or two products.

Uniform(5,3,((2,1),(1,2)), None) will generate 5 molecules with 3 reactions between them where each reaction has either two reactants and one product or one reactant and two products.

AChemKit.randomnet.combinations_with_replacement(iterable, r)

randomnet_test Module

This is the test harness for AChemKit.randomnet.

Tricky to test well because it is non-deterministic.

class AChemKit.randomnet_test.TestLinear(methodName='runTest')

Bases: unittest.TestCase

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()
test_directed()
test_maxlengt_dict()
test_maxlengt_tuple()
test_natoms_dict()
test_natoms_int()
test_natoms_tuple()
test_pbreak_tuple()
test_pform_tuple()
test_undirected()
class AChemKit.randomnet_test.TestUniform(methodName='runTest')

Bases: unittest.TestCase

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()
test_nmols_dict()
test_nmols_int()
test_nmols_list()
test_nmols_tuple()
test_nprods_dict()
test_nprods_int()
test_nprods_list()
test_nprods_none_dict()
test_nprods_none_tuple()
test_nprods_tuple()
test_nreacts_dict()
test_nreacts_int()
test_nreacts_list()
test_nreacts_tuple()
test_rate_dict()
test_rate_float()
test_rate_int()
test_rate_list()
test_rate_tuple()

reactionnet Module

Core for all ReactionNetwork classes

Of particular note are the alternative constructors of ReactionNetwork, from_file(), from_filename() and from_string().

class AChemKit.reactionnet.ReactionNetwork(rates)

Bases: object

A dictionary of reactions where each key is a reaction composed of (reactants, products) and each value is the rate.

ReactionNetwork objects are immutable and hashable.

ReactionNetwork objects support __eq__() and __ne__(), but none of the other rich comparison operators (__lt__, __le__, __gt__, __ge__).

Different subclassess could be implemented to generate reaction networks on demand (artificial chemistries, etc) and provide additional functionallity, such as visualization or metrics.

Can be cast to string to get a .chem representation.

classmethod from_file(infile)

Alternative constructor that accepts a file() object (or equivalent).

Source must be formatted as a .chem file, see .chem Format.

classmethod from_filename(infilename)

Wrapper around AChemKit.reactionnet.ReactionNetwork.from_file() that opens the provided filename as a file to read.

classmethod from_string(instr)

Wrapper around AChemKit.reactionnet.ReactionNetwork.from_file() that uses StringIO.

classmethod reaction_to_string(reaction, rate=1.0)

Produces a human-readable string for a particular reaction.

Mainly used to convert entire reaction network to a string representation, but can also be used for individual reactions if desired.

reactions

Sorted tuple of all reactions in the network

seen

Sorted tuple of all molecular species in the network

reactionnet_test Module

This is the test harness for AChemKit.reactionnet.

class AChemKit.reactionnet_test.TestReactionNetwork(methodName='runTest')

Bases: unittest.TestCase

This is the main class to test ReactionNetwork class.

It relies on setUp to generate a ReactionNetwork instance which is then probed by the other functions

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()
test_equal()

As ReactionNetwork has a custom __eq__ function, it is tested here.

Needs to both pass and fail.

test_hash()

As ReactionNetwork has a custom __hash__ function, it is tested here.

Needs to both pass and fail.

Technically, the fail here could be true and still be a hash but it is supposed to usually be wrong so assume that it will be wrong.

test_rates()
test_reaction_to_string()

Check that it convert a reaction to a string correctly

test_reactions()

Makes sure the reactions that were specified are in reactions. Also checks that they are in sorted order TODO check sorted order between reactions

test_seen()

Makes sure the molecules that were specified are in seen. Also checks that they are in sorted order.

test_to_string()

Check that it converts to a string correctly

class AChemKit.reactionnet_test.TestReactionNetwork_from_string(methodName='runTest')

Bases: AChemKit.reactionnet_test.TestReactionNetwork

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()

reactionnetdot Module

class AChemKit.reactionnetdot.ReactionNetworkDot(rates)

Bases: AChemKit.reactionnet.ReactionNetwork

This is a subclass of AChemKit.reactionnet.ReactionNetwork that adds a .dot representation. It is in a subclass so that on machines where dot is not installed, the basic class can still be used.

dot

Property wrapper around to_dot() to provide attribute-like access.

to_dot(names=None, rates=None, shown=(), hidden=())

Return a .dot format string constructed using a AChemKit.utils.simpledot.SimpleDot view of this reaction network.

Molecular species are shown as either full names, identifier numbers, or as blank circles. This is determined by the names parameter, which is a string indicating which to use:

“full”
This will use the full molecule name specified in the .chem file
“id”
This will use a shortened identifier of that molecules index in the seen tuple.
“blank”
This will not name any molecules, but will put an empty circle instead.

A sub-set of the reaction network can be drawn using the shown and hidden parameters.

Reactions involving only molecular species on the hidden list are not shown. Molecular species on the hidden list are not shown unless they are involved in a reaction with molecular species not on the hidden list, in which case the molecular species on the hidden list is unlabeled and shown as a point.

The shown list in the inverse of the hidden list. If it is used, any molecular species not on the shown list is treated as being on the hidden list. If a molecular species is on both shown and hidden lists, the hidden lists wins.

Catalysts (defined as molecules that are required for but unchanged by a reaction) are indicated with a grey line.

Reversible reactions (defined as a pair of reactions where reactants of one are the products of the other and visa versa) are combined and indicated with double arrows resembling a diamond shape.

reactionnetdot_test Module

This is the test harness for AChemKit.reactionnetdot.

class AChemKit.reactionnetdot_test.TestReactionNetworkDot(methodName='runTest')

Bases: unittest.TestCase

This is the main class to test ReactionNetwork class.

It relies on setUp to generate a ReactionNetwork instance which is then probed by the other functions

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()
test_to_dot_str()

Test for dot conversion by string representation

Assumes that the dot representation itself is valid

sims_gillespie Module

class AChemKit.sims_gillespie.Gillespie(achem, mols, rng, intervalscaling=100.0)

Bases: object

next_reaction()
AChemKit.sims_gillespie.simulate_gillespie(achem, mols, maxtime, rng=None)
AChemKit.sims_gillespie.simulate_gillespie_iter(achem, mols, maxtime, rng=None)

Given an Artificial Chemistry, this simulates a series of simple iterative reactions. It returns events as tuples of (time, reactants, products).

This is an implementation of the Gillespie algorithm. It is a simulation of a well-mixed container.

Is an iterator to reduce memory consumption. See simulate_gillespie for this function wrapped in a tuple.

sims_gillespie_test Module

This is the test harness for AChemKit.sims_simple.

class AChemKit.sims_gillespie_test.TestGillespie(methodName='runTest')

Bases: unittest.TestCase

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()
test_basic()

sims_simple Module

class AChemKit.sims_simple.AChemAbstract

Bases: object

This is an abstract base class for an AChem that can be used in a simulation or similar. It defines core attribtues and functions that subclasses must implement in order to follow the API correctly.

It is not required that an AChem inherits this, as Python follows the principle of “duck typing”.

react(*reactants)

Given some number of reactants, return the products.

The reactant objects should not be changed. Rather, copies should be returned. This is so events and buckets work correctly.

class AChemKit.sims_simple.AChemReactionNetwork(reactionnetwork)

Bases: AChemKit.sims_simple.AChemAbstract

This is an AChem class that uses a Reaction Network as its base.

The main point of this is to be able to compare different simuatlion approaches to see which ones best reconstruct the original Reaction Network.

react(*reactants)
AChemKit.sims_simple.simulate_itterative(achem, mols, maxtime, rng=None)
AChemKit.sims_simple.simulate_itterative_iter(achem, mols, maxtime, rng=None)

Given an Artificial Chemistry, this simulates a series of simple iterative reactions. It returns events as tuples of (time, reactants, products).

One reaction occurs each second for a number of seconds up to the maximum time specified.

Works as an iterator to reduce memory consumption. See simulate_itterative for this function wrapped in a tuple.

AChemKit.sims_simple.simulate_stepwise(achem, mols, maxtime, rng=None)
AChemKit.sims_simple.simulate_stepwise_iter(achem, mols, maxtime, rng=None)

Given an Artificial Chemistry, this simulates a series of simple iterative reactions. It returns events as tuples of (time, reactants, products).

Each molecule will attempt to react once for each second. If there are any leftover molecules, they will get a free pass to the next second.

Is an iterator to reduce memory consumption. See simulate_stepwise for this function wrapped in a tuple.

AChemKit.sims_simple.simulate_stepwise_multiprocessing(achem, mols, maxtime, rng=None)
AChemKit.sims_simple.simulate_stepwise_multiprocessing_iter(achem, mols, maxtime, rng=None)

Given an Artificial Chemistry, this simulates a series of simple iterative reactions. It returns events as tuples of (time, reactants, products).

Each molecule will attempt to react once for each second. If there are any leftover molecules, they will get a free pass to the next second.

Is an iterator to reduce memory consumption. See simulate_stepwise_multiprocessing for this function wrapped in a tuple.

Uses multiprocessing to parallelize reactions. This does not work that well because the individual reactions are not that complicated.

sims_simple_test Module

This is the test harness for AChemKit.sims_simple.

class AChemKit.sims_simple_test.TestItterative(methodName='runTest')

Bases: unittest.TestCase

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()
test_basic()
class AChemKit.sims_simple_test.TestStepwise(methodName='runTest')

Bases: AChemKit.sims_simple_test.TestItterative

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

test_basic()
class AChemKit.sims_simple_test.TestStepwiseMultiprocessing(methodName='runTest')

Bases: AChemKit.sims_simple_test.TestItterative

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

test_basic()