API

Python API

class pystospa.Reaction(rate, propensity_func, stoichimetry, diff_idx=- 1)

Reaction class constructor

Parameters:

  • rate = rate of the reaction

  • propensity_func = lambda function that takes number of molecules and voxel are and returns propensity

  • stoichiometry = vector on how number of molecules are going to change if this reaction happens

  • diff_idx = index of a voxel in an list of voxels to which the molecule should jump to

get_propensity(self: pystospa.Reaction, num_molecules: List[int], voxel_size: float) → float

Returns propensity of the reaction given number of molecules and voxel size

Parameters:

  • num_molecules = list of number of molecules

  • voxel_size = size (length/area/volume) of a voxel

Returns:

  • propensity

get_rate(self: pystospa.Reaction) → float

Returns the rate of the reaction

Returns:

  • value of the reaction rate

set_rate(self: pystospa.Reaction, rate: float) → None

Sets the rate of the reaction

Parameters:

  • rate = value to which rate needs to be set

class pystospa.Simulator(voxels)

Simulator class constructor

Parameters:

  • voxels = list of voxel objects already populated with molecules

  • time = initial value of time

advance(self: pystospa.Simulator, time_point: float) → None

Advances the simulation to the specified time point

get_molecules(self: pystospa.Simulator) → List[int]

Returns a concatenated list of number of molecules present in each voxel

Returns:

  • number of molecules present in the whole simulation

get_seed(self: pystospa.Simulator) → int

Returns the number used as the seed for random number generation

Returns:

  • seed

get_time(self: pystospa.Simulator) → float

Returns the current time of the simulation

Returns:

  • current time of the simulation

get_voxels(self: pystospa.Simulator) → List[pystospa.Voxel]

Returns list of voxels that comprise the simulation domain

Returns:

  • list of voxel object present in the Simulator object

run(self: pystospa.Simulator, name: str, time_step: float, num_steps: int, header: str = '# time voxels...\n') → None

Runs the simulation given and saves the output in a file

Parameters:

  • name = name of the file where to save the output of the simulation

  • time_step = how far to advance in time before saving the state of the simulation

  • num_steps = number of steps in time to take

  • header = the string which to write at the top of the file

set_seed(self: pystospa.Simulator, seed: int) → None

Sets the number used as the seed for random number generation

Parameters:

  • seed = a number

step(self: pystospa.Simulator) → None

Makes a single step in the stochastic simulation algorithm

class pystospa.Voxel(num_molecules, voxel_size, growth_func=None, extrande_ratio=2.0)

Voxel class constructor

Parameters:

  • num_molecules = array of number of molecules of each species

  • voxel_size = size (len/area/volume) of a voxel

  • growth_func = lambda function that takes value of time and returns ratio by which voxel size has grown

  • extrande_ratio = by how much the total propensity needs to be multiplied to get an upper bound

add_reaction(self: pystospa.Voxel, reaction: pystospa.Reaction) → None

Adds the given reaction to the list of reactions contained within the voxel

Parameters:

  • reaction = an instance of Reaction class

clear_reactions(self: pystospa.Voxel) → None

Empties the list of reactions contained within the voxel

get_extrande_ratio(self: pystospa.Voxel) → float

Returns value of the extrande ratio

Returns:

  • extrande ratio

get_molecules(self: pystospa.Voxel) → List[int]

Returns the number of molecules present in the voxel

Returns:

  • number of molecules

get_reactions(self: pystospa.Voxel) → List[pystospa.Reaction]

Returns list of reactions contained within the voxel

Returns:

  • list of reactions

get_total_propensity(self: pystospa.Voxel, update: bool = True) → float

Returns the total propensity given all the reactions within the voxel

Parameters:

  • update = whether to update Voxel attribute for total propensity

Returns:

  • total propensity

get_voxel_size(self: pystospa.Voxel) → float

Returns size of the voxel

Returns:

  • voxel size

C++ API

class StoSpa2::Reaction
#include <reaction.hpp>

Reaction class - represents a reaction within stochastic modelling. Reaction class contains rate of a reaction, propensity and stoichiometry vector, all of which need to be given to the constructor.

Public Functions

Reaction(double rate, p_f propensity, std::vector<int> stoichiometry_vec, int diffusion_index = -1)

Constructor for Reaction class

Parameters

  • rate: the rate of the reaction

  • propensity: lambda function that returns propensity given number of molecules and voxel area

  • stoichiometry_vec: stoichiometry vector

  • diffusion_index: index of the voxel in a vector of voxels where a molecule would jump

void set_rate(double rate)

Sets the rate of the reaction instance

Parameters

  • rate: the rate of reaction

double get_rate()

Returns the rate of reaction

Return

copy of the value of m_rate

void update_properties(const double &factor)

Updates any properties of the reaction instance, such as the rate

Parameters

  • factor: value by which to mulpiply the initial reaction rate (m_initial_rate)

double get_propensity(const std::vector<unsigned> &num_molecules, const double &voxel_size)

Returns the value of propensity given the number of molecules and voxel length/area

Parameters

  • num_molecules: number of molecules given as a vector

  • voxel_size: length / area / volume of a voxel

Public Members

const std::vector<int> stoichiometry

The stoichiometry vector i.e. how the number of molecules changes if this reaction happens

const int diffusion_idx

Variable used to indicate if this reaction is a diffusion reaction

Protected Attributes

double m_initial_rate

Initial reaction rate

double m_rate

Rate of reaction that can be updated, hence can be different from m_inital rate

p_f m_propensity

Lambda function that returns propensity given the numebr of molecules and the area of a voxell

Friends

friend std::ostream &operator<<(std::ostream &os, const Reaction &r)

Overloaded operator to pass member variables to the standard output

Return

reference to the output stream

Parameters

  • os: reference to the output stream

  • r: reference to an instance of Reaction class

friend bool operator==(const Reaction &r1, const Reaction &r2)

Overloaded == operator for the Reaction class

Return

whether two Reaction instances are equal

Parameters

friend bool operator!=(const Reaction &r1, const Reaction &r2)

Overloaded != operator for the Reaction class

Return

whether two Reaction instances are not equal

Parameters

class StoSpa2::Simulator
#include <simulator.hpp>

Simulator class - used to step in time using stochastic simulation algorithm (SSA). It uses next subvolume method variation of the SSA to efficiently step through time.

Public Functions

Simulator(std::vector<StoSpa2::Voxel> voxels, double time = 0)

Constructor for the Simulator class

Parameters

  • voxels: vector of Voxel class instances

void set_seed(unsigned seed)

Sets the seed in the random number generator

Parameters

  • seed: the value of the seed

unsigned get_seed()

Returns the number used to generate the random numbers

double get_time()

Returns the current time in the simulation

const std::vector<StoSpa2::Voxel> &get_voxels()

Returns a copy of the vector of voxels used in the simulation

std::vector<unsigned> get_molecules()

Returns the number of molecules contained in each voxel as a single vector

void step()

Function to make a single step in the SSA

void advance(double time_point)

Function to make multiple steps to reach the given point in time

Parameters

  • time_point: the point in time in simulation that is reached

void write_header(std::ofstream &handle, const std::string &header = "# time voxels...\)

Function that writes a given string that describes the simulation

Parameters

  • handle: reference to the output stream to a file

  • header: string that is to be written to a file

void write_header(const std::string &filename, const std::string &header = "# time voxels...\)

Function that writes a given string that describes the simulation

Parameters

  • filename: path to the file

  • header: string that is to be written to a file

void save(std::ofstream &handle)

Function that saves the number of molecules present in each voxel to a file

Parameters

  • handle: reference to the output stream to a file

void save(const std::string &filename)

Function that saves the number of molecules present in each voxel to a file

Parameters

  • filename: path to the file

void run(const std::string &name, double time_step, unsigned num_steps, const std::string &header = "# time voxels...\)

Function that runs a simulation and saves the number of molecules present in each voxel at each time-point to the given file.

Parameters

  • name: path to the file

  • time_step: value of the step in time

  • num_steps: number of steps in time which to take

  • header: string of information that describes the simulation

Protected Functions

double exponential(const double &propensity)

Function that returns a random number from the exponential distribution.

Return

a random number from exponential distribution

Parameters

  • propensity: the total propensity

void initialise_next_reaction_times()

Initialiases all the times until next reactions in all the containers

void update_next_reaction_time(const unsigned &index)

Updates the time until the next reaction for a voxel with the given index

Parameters

  • index: the index of the voxel where time until the next reaction is to be updated

Protected Attributes

double inf = std::numeric_limits<double>::infinity()

Infinity - helper variable

double m_time

Current time in a simulation

std::map<double, unsigned> next_reaction_times

Map of times until next reaction for each voxel to the corresponding indices of voxels

std::vector<double> lookup_times

Vector of times until the next reaction for each voxel ordered according to voxel indices

std::vector<StoSpa2::Voxel> m_voxels

Vector of Voxel class instances

unsigned m_seed

Seed used for generating a random number.

std::mt19937 m_gen

For generating random numbers

std::uniform_real_distribution<double> m_uniform

Uniform distribution.

class StoSpa2::Voxel
#include <voxel.hpp>

Voxel class - represents a voxel (or compartment, i.e. a subinterval or subarea of a domain) in stochastic modelling. A voxel in stochastic modelling contains some number of molecules of different number of species and this information is stored as a vector and each element in this vector represents the number of molecules of some species.

Public Functions

Voxel(std::vector<unsigned> initial_num, double voxel_size)

Constructor for the Voxel class

Parameters

  • initial_num: vector of the number of molecules initially for all species

  • voxel_size: intial size of the voxel

Voxel(std::vector<unsigned> initial_num, double voxel_size, g_f growth, double extrande_ratio = 2.0)

Constructor for the Voxel class

Parameters

  • initial_num: vector of the number of molecules initially for all species

  • voxel_size: intial size of the voxel

  • growth: lambda function that describes how a voxel grows

  • extrande_ratio: ratio between upper bound for total propensity and total propensity

Voxel(std::vector<unsigned> initial_num, double voxel_size, std::vector<g_f> growth, double extrande_ratio = 2.0)

Constructor for the Voxel class

Parameters

  • initial_num: vector of the number of molecules initially for all species

  • voxel_size: intial size of the voxel

  • growth: vector of lambda functions that describe how a voxel grows (one for each spatial dimension)

  • extrande_ratio: ratio between upper bound for total propensity and total propensity

std::vector<unsigned> get_molecules()

Returns number of molecules for each species present in a voxel

Return

copy of m_molecules member variable

double get_voxel_size()

Returns current voxel size

Return

copy of m_voxel_size member variable

bool is_growing()

Returns whether the voxel is growing or not

Return

copy of m_growing member variable

double get_extrande_ratio()

Returns the ratio that is used in the extrande method

Return

copy of m_extrande_ratio member variable

void update_properties(const double &time)

Updates any properties that need to updated due to growth of the voxel

Parameters

  • time: current time of the simulation

void add_extrande()

Adds a reaction (none -> none) that is essential in the extrande method

void add_reaction(StoSpa2::Reaction r)

Adds a Reaction object to a vector of reactions (m_reactions member variable)

std::vector<StoSpa2::Reaction> get_reactions()

Returns the vector of Reaction objects

Return

copy of the m_reactions member variable

void clear_reactions()

Clears the vector of Reaction objects

double get_total_propensity(bool update = true)

Returns the current total propensity

Parameters

  • update: determines whether member variable a_0 is updated

StoSpa2::Reaction &pick_reaction(double random_num)

Picks a reaction from the vector of reactions (m_reactions) and returns a reference to this reaction

Return

reference to the reaction that has been chosen

Parameters

  • random_num: a random number generated from a unfiform distribution

void add_vector(const std::vector<int> &stoichiometry_vec)

Adds the given vector to the m_molecules member variables

Parameters

  • stoichiometry_vec: vector to be added to m_molecules

void subtract_vector(const std::vector<int> &stoichiometry_vec)

Subtracts the given vector to the m_molecules member variables

Parameters

  • stoichiometry_vec: vector that is subtracted from m_molecules

Protected Attributes

double m_voxel_size

Size of the voxel (length/area/volume)

double a_0

Total propensity for all the reactions within a voxel

std::vector<unsigned> m_molecules

Vector of the number of molecules

std::vector<StoSpa2::Reaction> m_reactions

Vector of reactions within a voxel

std::vector<StoSpa2::Reaction> m_extrande_reaction

Container for an extrande reaction if needed

double m_extrande_ratio

Ratio of the upper bound for total propensity and the total propensity

double m_initial_voxel_size

Initial voxel size

std::vector<std::function<double(const double&)>> m_growth_func

Function for how voxel size changes

bool m_growing

Whether the voxel is growing or not

Friends

friend std::ostream &operator<<(std::ostream &os, const Voxel &v)

Friend function for outputting information to stdout

Return

reference to the output stream

Parameters

  • os: reference to output stream

  • v: voxel that is passed to the output stream

friend bool operator==(const Voxel &v1, const Voxel &v2)

Overloaded == operator for the voxel class

Return

whether two voxel instances are equal

Parameters

  • v1: first instance of Voxel class

  • v2: second instance of Voxel class

friend bool operator!=(const Voxel &v1, const Voxel &v2)

Overloaded != operator for the voxel class

Return

whether two voxel instances are not equal

Parameters

  • v1: first instance of Voxel class

  • v2: second instance of Voxel class

namespace StoSpa2

Functions

void add_reaction(std::vector<StoSpa2::Voxel> &voxels, const StoSpa2::Reaction &r)

Function that adds a given instance of the Reaction class to all the voxels in the vector of voxels

Parameters

  • voxels: vector of Voxel class instances

  • r: reaction to be added to all the voxels in the given vector

void add_diffusion(std::vector<StoSpa2::Voxel> &voxels, const std::vector<std::vector<double>> &jump_rates, p_f &propensity, const std::vector<int> &stoichiometry_vec)

Function to add diffusion to all the given voxels based on the matrix of jump rates

Parameters

  • voxels: vector of Voxel class instances

  • jump_rates: matrix (vector of vectors) of jump rates between different voxels

  • propensity: the propensity function used to create a Reaction instance

  • stoichiometry_vec: the stoichiomery vector used to create a Reaction instance

std::vector<double> split(const std::string &input_str, char separator)

Helper function to split a string of characters based on a separator into a vector of doubles

Return

resulting vector of doubles

Parameters

  • input_str: string to be split into vector of doubles

  • separator: the character used to split the string into vector of doubles

std::vector<std::vector<double>> read_matrix(const std::string &filename, char separator = ' ')

Helper function to read in a matrix from a file. Useful for reading the matrix of jump rates in simulations of diffusion.

Return

a matrix (vector of vectors) contained within the file

Parameters

  • filename: path to the file

  • separator: character used to separate the strings into vectors of doubles

file reaction.hpp
#include <functional>#include <iostream>#include <string>#include <utility>#include <vector>

Typedefs

typedef std::function<double(const std::vector<unsigned>&, const double&)> p_f

Type alias p_f for function signature: 

std::function<double (const std::vector<unsigned>&, const double&)>

Functions

template<typename T>
bool operator==(const std::vector<T> &v1, const std::vector<T> &v2)

Overloaded == operator for std::vector class. This operator is used in the reaction class to compare certain member variables

Return

whether v1 is equal to v2

Parameters

  • v1: first instance of std::vector

  • v2: second instance of std::vector

template<typename T>
bool operator!=(const std::vector<T> &v1, const std::vector<T> &v2)

Overloaded != operator for std::vector class. This operator is used in the reaction class to compare certain member variables

Return

whether v1 is not equal to v2

Parameters

  • v1: first instance of std::vector

  • v2: second instance of std::vector

file simulator.hpp
#include <fstream>#include <iostream>#include <limits>#include <map>#include <random>#include <string>#include <vector>#include “reaction.hpp”#include “voxel.hpp”
file tools.hpp
#include <fstream>#include <sstream>#include “reaction.hpp”#include “voxel.hpp”
file voxel.hpp
#include <vector>#include <iostream>#include “reaction.hpp”

Typedefs

typedef std::function<double(const double&)> g_f
dir /home/docs/checkouts/readthedocs.org/user_builds/stospa2/checkouts/latest/src