AChemKit Package — AChemKit v0.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- AChemKit v0.1 documentation »
- Project Modules »

# 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`()

## Subpackages

- tools Package
  - `tools` Package
  - `chem_pp` Module
  - `chem_to_dot` Module
  - `chem_to_pdf` Module
  - `log_to_chem` Module
- utils Package
  - `utils` Package
  - `bag` Module
  - `bag_test` Module
  - `simpledot` Module
  - `utils` Module
  - `utils_test` Module

### Navigation

- index
- modules |
- next |
- previous |
- AChemKit v0.1 documentation »
- Project Modules »