cayenne package¶
Subpackages¶
- cayenne.algorithms package
- Submodules
- cayenne.algorithms.direct.cpython-36m-x86_64-linux-gnu module
- cayenne.algorithms.direct.cpython-37m-x86_64-linux-gnu module
- cayenne.algorithms.direct module
- cayenne.algorithms.tau_adaptive.cpython-36m-x86_64-linux-gnu module
- cayenne.algorithms.tau_adaptive.cpython-37m-x86_64-linux-gnu module
- cayenne.algorithms.tau_adaptive module
- cayenne.algorithms.tau_leaping.cpython-36m-x86_64-linux-gnu module
- cayenne.algorithms.tau_leaping.cpython-37m-x86_64-linux-gnu module
- cayenne.algorithms.tau_leaping module
- Module contents
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
-
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
-
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
.
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
andchem_flag
need to be supplied for second and third order reactions.volume
represents the size of the system containing the reactants.In chemical systems
chem_flag
should generally be set toTrue
ask_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 computingk_stoc
(\(c_\mu\) in [3] ) fromk_det
.In biological systems,
chem_flag
should be generally be set toFalse
ask_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 bytau_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:
-
plot
(species_names: list = None, new_names: list = None, thinning: int = 1)[source]¶ Plot the simulation
Parameters: - species_names (list, optional) – The names of the species to be plotted (
list
ofstr
). The default isNone
and plots all species. - new_names (list, optional) – The names of the species to be plotted.
The default is
"xi"
for speciesi
. - thinning (int) – The parameter that controls the sampling Eg. a value of 100 means that 1 point will be sampled every 100 steps The default is 1 (every time-point is sampled)
Returns: - fig (class ‘matplotlib.figure.Figure’) – Figure object of the generated plot.
- ax (class ‘matplotlib.axes._subplots.AxesSubplot) – Axis objected of the generated plot.
- species_names (list, optional) – The names of the species to be plotted (
-
results
The
Results
instance of the simulationReturns: 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.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.