cayenne package — Stochastic Simulation Algorithms in Python 0.9.1 documentation (original) (raw)

Stochastic Simulation Algorithms in Python

Subpackages

Submodules

cayenne.model_io module

The class that handles model IO

exception cayenne.model_io. ChemFlagError[source]

Bases: cayenne.model_io.ModelError

exception cayenne.model_io. InitialStateError[source]

Bases: cayenne.model_io.ModelError

exception cayenne.model_io. ModelError[source]

Bases: Exception

class cayenne.model_io. ModelIO(model_contents: str, content_type: str)[source]

Bases: object

Class for loading and parsing models

Parameters: model_contents (str) – Either the model string or the file path content_type (str , {"ModelString" , "ModelFile"}) – The type of the model

react_stoic

A 2D array of the stoichiometric coefficients of the reactants. Reactions are columns and species are rows.

Type: (ns, nr) ndarray

prod_stoic

A 2D array of the stoichiometric coefficients of the products. Reactions are columns and species are rows.

Type: (ns, nr) ndarray

init_state

A 1D array representing the initial state of the system.

Type: (ns,) ndarray

k_det

A 1D array representing the deterministic rate constants of the system.

Type: (nr,) ndarray

volume

The volume of the reactor vessel which is important for second and higher order reactions. Defaults to 1 arbitrary units.

Type: float, optional

chem_flag

If True, divide by Na (Avogadro’s constant) while calculating stochastic rate constants. Defaults to False.

Type: bool, optional

args

Returns the attributes of the ModelIO class

classmethod translate_sbml(sbml_file: str)[source]

Translate SBML file to Antimony model specification. cayenne’s model specification is loosely based on Antimony’s model specification.

exception cayenne.model_io. RateConstantError[source]

Bases: cayenne.model_io.ModelError

exception cayenne.model_io. VolumeError[source]

Bases: cayenne.model_io.ModelError

cayenne.results module

Module that defines the Results class

class cayenne.results. Results(species_names: List[str], rxn_names: List[str], t_list: List[numpy.ndarray], x_list: List[numpy.ndarray], status_list: List[int], algorithm: str, sim_seeds: List[int])[source]

Bases: collections.abc.Collection

A class that stores simulation results and provides methods to access them

Parameters: species_names (List [ str ]) – List of species names rxn_names (List [ str ]) – List of reaction names t_list (List [ float ]) – List of time points for each repetition x_list (List [ np.ndarray ]) – List of system states for each repetition status_list (List [ int ]) – List of return status for each repetition algorithm (str) – Algorithm used to run the simulation sim_seeds (List [ int ]) – List of seeds used for the simulation

Notes

The status indicates the status of the simulation at exit. Each repetition will have a status associated with it, and these are accessible through the status_list.

1: Succesful completion, terminated when max_iter iterations reached.

2: Succesful completion, terminated when max_t crossed.

3: Succesful completion, terminated when all species went extinct.

-1: Failure, order greater than 3 detected.

-2: Failure, propensity zero without extinction.

final

Returns the final times and states of the system in the simulations

Returns: The final times and states of the sytem
Return type: Tuple[np.ndarray, np.ndarray]

get_species(species_names: List[str]) → List[numpy.ndarray][source]

Returns the species concentrations only for the species in species_names

Parameters: species_names (List [ str ]) – The names of the species as a list
Returns: Simulation output of the selected species.
Return type: List[np.ndarray]

get_state(t: float) → List[numpy.ndarray][source]

Returns the states of the system at time point t.

Parameters: t (float) – Time point at which states are wanted.
Returns: The states of the system at t for all repetitions.
Return type: List[np.ndarray]
Raises: UserWarning – If simulation ends before t but system does not reach extinction.

cayenne.simulation module

The main class for running stochastic simulation

class cayenne.simulation. Simulation(species_names: List[str], rxn_names: List[str], react_stoic: numpy.ndarray, prod_stoic: numpy.ndarray, init_state: numpy.ndarray, k_det: numpy.ndarray, chem_flag: bool = False, volume: float = 1.0)[source]

Bases: object

A main class for running simulations.

Parameters: species_names (List [ str ]) – List of species names rxn_names (List [ str ]) – List of reaction names react_stoic (( ns , nr ) ndarray) – A 2D array of the stoichiometric coefficients of the reactants. Reactions are columns and species are rows. prod_stoic (( ns , nr ) ndarray) – A 2D array of the stoichiometric coefficients of the products. Reactions are columns and species are rows. init_state (( ns , ) ndarray) – A 1D array representing the initial state of the system. k_det (( nr , ) ndarray) – A 1D array representing the deterministic rate constants of the system. volume (float , optional) – The volume of the reactor vessel which is important for second and higher order reactions. Defaults to 1 arbitrary units. chem_flag (bool , optional) – If True, divide by Na (Avogadro’s constant) while calculating stochastic rate constants. Defaults to False.

results

The results instance

Type: Results
Raises: ValueError – If supplied with order > 3.

Examples

V_r = np.array([[1,0],[0,1],[0,0]]) V_p = np.array([[0,0],[1,0],[0,1]]) X0 = np.array([10,0,0]) k = np.array([1,1]) sim = Simulation(V_r, V_p, X0, k)

Notes

Stochastic reaction rates depend on the size of the system for second and third order reactions. By this, we mean the volume of the system in which the reactants are contained. Intuitively, this makes sense considering that collisions between two or more molecules becomes rarer as the size of the system increases. A detailed mathematical treatment of this idea can be found in [3] .

In practice, this means that volume and chem_flag need to be supplied for second and third order reactions. volumerepresents the size of the system containing the reactants.

In chemical systems chem_flag should generally be set to Trueas k_det is specified in units of molarity or M or mol/L. For example, a second order rate constant could be = 0.15 mol / (L s). Then Avogadro’s constant (\(N_a\)) is used for normalization while computing k_stoc (\(c_\mu\) in [3] ) from k_det.

In biological systems, chem_flag should be generally be set toFalse as k_det is specified in units of copies/L or CFU/L. For example, a second order rate constant could be = 0.15 CFU / (L s).

References

[3] (1, 2) Gillespie, D.T., 1976. A general method for numerically simulating the stochastic time evolution of coupled chemical reactions. J. Comput. Phys. 22, 403–434. doi:10.1016/0021-9991(76)90041-3.

HOR

Determine the HOR vector. HOR(i) is the highest order of reaction in which species S_i appears as a reactant.

Returns: HOR – Highest order of the reaction for the reactive species as defined under Eqn. (27) of [1]. HOR can be 1, 2 or 3 if the species appears only once in the reactants. If HOR is -2, it appears twice in a second order reaction. If HOR is -3, it appears thrice in a third order reaction. If HOR is -32, it appears twice in a third order reaction. The corresponding value of g_i in Eqn. (27) is handled by tau_adaptive.
Return type: np.ndarray

References

[1] Cao, Y., Gillespie, D.T., Petzold, L.R., 2006. Efficient step size selection for the tau-leaping simulation method. J. Chem. Phys. 124, 044109. doi:10.1063/1.2159468

classmethod load_model(contents: str, contents_type: str) → cayenne.simulation.Simulation[source]

Load model contents into a Simulation object

Parameters: model_contents (str) – Either the model string or the file path content_type (str , {"ModelString" , "ModelFile"}) – The type of the model
Returns: sim – An instance of the Simulation class.
Return type: Simulation

plot(species_names: list = None, new_names: list = None)[source]

Plot the simulation

Parameters: species_names (list , optional) – The names of the species to be plotted (list of str). The default is None and plots all species. new_names (list , optional) – The names of the species to be plotted. The default is "xi" for species i.
Returns: fig (class ‘matplotlib.figure.Figure’) – Figure object of the generated plot. ax (class ‘matplotlib.axes._subplots.AxesSubplot) – Axis objected of the generated plot.

results

The Results instance of the simulation

Returns:
Return type: Optional[Results]

simulate(max_t: float = 10.0, max_iter: int = 1000, seed: int = 0, n_rep: int = 1, n_procs: Optional[int] = 1, algorithm: str = 'direct', debug: bool = False, **kwargs) → None[source]

Run the simulation

Parameters: max_t (float , optional) – The end time of the simulation. The default is 10.0. max_iter (int , optional) – The maximum number of iterations of the simulation loop. The default is 1000 iterations. seed (int , optional) – The seed used to generate simulation seeds. The default value is 0. n_rep (int , optional) – The number of repetitions of the simulation required. The default value is 1. n_procs (int , optional) – The number of cpu cores to use for the simulation. Use None to automatically detect number of cpu cores. The default value is 1. algorithm (str , optional) – The algorithm to be used to run the simulation. The default value is "direct".

Notes

The status indicates the status of the simulation at exit. Each repetition will have a status associated with it, and these are accessible through the Simulation.results.status_list.

status: int

Indicates the status of the simulation at exit.

1: Succesful completion, terminated when max_iter iterations reached.

2: Succesful completion, terminated when max_t crossed.

3: Succesful completion, terminated when all species went extinct.

-1: Failure, order greater than 3 detected.

-2: Failure, propensity zero without extinction.

cayenne.simulation. wrapper(x, func)[source]

cayenne.utils.cpython-36m-x86_64-linux-gnu module

cayenne.utils module

Contains various utility functions

cayenne.utils. get_kstoc

Compute k_stoc from k_det.

Return a vector of the stochastic rate constants (k_stoc) determined from the deterministic rate constants (k_det) [2]

Parameters: react_stoic (( ns , nr ) ndarray) – A 2D array of the stoichiometric coefficients of the reactants. Reactions are columns and species are rows. k_det (( nr , ) ndarray) – A 1D array representing the deterministic rate constants of the system. volume (float) – The volume of the reactor vessel which is important for second and higher order reactions chem_flag (bool) – If True, divide by Na (Avogadro’s constant) while calculating stochastic rate constants. Defaults to False.
Returns: k_stoc – A 1D array representing the stochastic rate constants of the system.
Return type: (nr,) ndarray

References

[2] Gillespie, D.T., 1976. A general method for numerically simulating the stochastic time evolution of coupled chemical reactions. J. Comput. Phys. 22, 403–434. doi:10.1016/0021-9991(76)90041-3.

cayenne.utils. py_roulette_selection

Perform roulette selection on the list of propensities.

Return the index of the selected reaction (choice) by performing Roulette selection on the given list of reaction propensities.

Parameters: prop_list (array_like) – A 1D array of the propensities of the reactions. Xt (array_like) – A 1D array of the current simulation state.
Returns: choice (int) – Index of the chosen reaction. status (int) – Status of the simulation as described in direct.

Module contents

Top-level package for Stochastic Simulation Algorithms in Python.

CLICK