PyURDME API

pyurdme module

class pyurdme.pyurdme.CubeMeshPeriodicBoundary(Lx=1.0, Ly=1.0, Lz=1.0)[source]

Bases: dolfin.cpp.mesh.SubDomain

Subdomain for Periodic boundary conditions on a cube domain.

inside(x, on_boundary)[source]

Left boundary is “target domain” G

map(x, y)[source]

# Map right boundary G (x) to left boundary H (y)

class pyurdme.pyurdme.IntervalMeshPeriodicBoundary(a=0.0, b=1.0)[source]

Bases: dolfin.cpp.mesh.SubDomain

Subdomain for Periodic boundary conditions on a interval domain.

inside(x, on_boundary)[source]
map(x, y)[source]
exception pyurdme.pyurdme.InvalidSystemMatrixException[source]

Bases: exceptions.Exception

exception pyurdme.pyurdme.MeshImportError[source]

Bases: exceptions.Exception

Exception to raise when encourntering and error importing a mesh.

exception pyurdme.pyurdme.ModelException[source]

Bases: exceptions.Exception

class pyurdme.pyurdme.SquareMeshPeriodicBoundary(Lx=1.0, Ly=1.0)[source]

Bases: dolfin.cpp.mesh.SubDomain

Subdomain for Periodic boundary conditions on a square domain.

inside(x, on_boundary)[source]

Left boundary is “target domain” G

map(x, y)[source]

# Map right boundary G (x) to left boundary H (y)

class pyurdme.pyurdme.URDMEDataFunction(name=None)[source]

Abstract class used to constuct the URDME data vector.

map(x)[source]

map() takes the coordinate ‘x’ and returns a list of doubles. Args:

x: a list of 3 ints.
Returns:
a list of floats.
name = None
exception pyurdme.pyurdme.URDMEError[source]

Bases: exceptions.Exception

class pyurdme.pyurdme.URDMEMesh(mesh=None)[source]

Bases: dolfin.cpp.mesh.Mesh

A URDME mesh extends the Dolfin mesh class.

Provides wrappers around dolfins built-in simple geometries/mesh generation function. These following methods will all give regular meshes that will produce discretizations that are equivalent to Cartesian grids.

add_periodic_boundary_condition(domain)[source]

Add a periodic boundary mapping object (a subclass of dolfin.SubDomain).

closest_vertex(x)[source]

Get index of the vertex in the coordinate list closest to the point x.

export_to_three_js(colors=None)[source]

return a Json string of the mesh in THREE Js format.

If a colors list is specified, it should have the num_voxels entries

classmethod generate_cube_mesh(L, nx, ny, nz, periodic=False)[source]

Unit Cube (3D) of with nx, ny, nz points in the respective axes, and side length L.

classmethod generate_interval_mesh(nx, a, b, periodic=False)[source]

Interval (1D) of with nx points in the axes, and side length L.

classmethod generate_square_mesh(L, nx, ny, periodic=False)[source]

Unit Square (2D) of with nx, ny points in the respective axes, and side length L.

classmethod generate_unit_cube_mesh(nx, ny, nz, periodic=False)[source]

Unit Cube (3D) of with nx, ny, nz points in the respective axes.

classmethod generate_unit_interval_mesh(nx, periodic=False)[source]

Unit Interval (1D) of with nx points in the axes.

classmethod generate_unit_square_mesh(nx, ny, periodic=False)[source]

Unit Square (2D) of with nx, ny points in the respective axes.

get_function_space()[source]

Get the FunctionSpace dolfin object for this mesh.

get_mesh_size()[source]

Estimate of mesh size at each vertex.

get_normalized_coordinates()[source]

Return vertex coordinates centered at origin.

get_num_dof_voxels()[source]

Get the number of voxels in the DOF ordering.

get_num_voxels()[source]

Get the number of voxels in the vertex ordering.

get_scaled_coordinates()[source]

Return vertex coordinates scaled to the interval (-1,1).

get_scaled_normalized_coordinates()[source]

Return vertex coordinates scaled to the interval (-1,1) and centered at origin.

get_voxels()[source]

Return the (x,y,z) coordinate of each voxel.

classmethod read_dolfin_mesh(filename=None, colors=[])[source]

Import a mesh in Dolfins native .xml format

set_num_dof_voxels(num)[source]

Set the number of voxels in the DOF ordering.

class pyurdme.pyurdme.URDMEModel(name='')[source]

Bases: pyurdme.model.Model

An URDME Model extends Model with spatial information and methods to create URDME solver input. TODO: Documentiation.

add_data_function(data_function)[source]

Add a URDMEDataFunction object to this object.

add_subdomain(subdomain)[source]
assemble()[source]

Assemble the mass and stiffness matrices using Dolfin.

Returns: A dictionary containing two dictionaries, one for the stiffness matrices and one for the mass matrices. Those dictionaries has the species names as keys and the matrices are in CSR format.

create_connectivity_matrix()[source]

Assemble a connectivity matrix in CCS format.

create_dependency_graph()[source]

Construct the sparse dependency graph.

create_extended_mesh()[source]

Extend the primary mesh with information about the degrees of freedom.

create_stoichiometric_matrix()[source]

Generate a stoichiometric matrix in sparse CSC format.

create_system_matrix()[source]

Create the system (diffusion) matrix for input to the URDME solvers. The matrix is built by concatenating the individually assembled matrices for each of the species, and multiplying with the lumped mass matrix (which define the volume of the voxels).

Negative off-diagonal elements in the matrix are set to zero, and the diagonal is renormalized in order to assure that the returned matrix is a Markov transition matrix.

Returns a dictionary containing the volumes of the subvolumes, the system diffusion matrix and the fraction of the mass of the negative off-diagonal elements that has been filtered out.

get_solver_datastructure()[source]

Return the datastructures needed by the URDME solvers.

get_solver_datastructure() creates and populates a dictionary, urdme_solver_data, containing the mandatory input data structures of the core NSM solver in URDME that is derived from the model. The data strucyures are

D - the Diffusion matrix N - the stochiometry matrix G - the dependency graph vol - the volume vector sd - the subdomain vector data - the data vector u0 - the intial condition

This data is also returned, unlike in the Matlab URDME interface

p - the vertex coordinates K - a (Nvoxel x Nvoxel) connectivity matrix

get_species_map()[source]

Get the species map, name to index.

get_subdomain_vector(subdomains={})[source]

Create the ‘sd’ vector. ‘subdomains’ is a dolfin FacetFunction, and if no subdomain input is specified, they voxels default to subdomain 1.

initialize_initial_condition()[source]

Create all-zeros inital condition matrix.

restrict(species, subdomains)[source]

Restrict the diffusion of a species to a subdomain.

run(number_of_trajectories=1, solver='nsm', seed=None, report_level=0)[source]

Simulate the model.

Args:
solver: A str or class type that is a subclass of URDMESolver. Default: NSM solver. number_of_trajectories: How many trajectories should be run. seed: An int, the random seed given to the solver. report_level: An int, Level of output from the solver: 0, 1, or 2. Default: 0.
Returns:
A URDMEResult object with the results of the simulation.
set_initial_condition_distribute_uniformly(spec_init, subdomains=None)[source]

Place the same number of molecules of the species in each voxel.

set_initial_condition_place_near(spec_init, point=None)[source]

Place all molecules of kind species in the voxel nearest a given point.

set_initial_condition_scatter(spec_init, subdomains=None)[source]

Scatter an initial number of molecules over the voxels in a subdomain.

set_subdomain_vector(sd)[source]

Explicitly set the subdomain vector from an array.

timespan(tspan)[source]

Set the time span of simulation.

validate(urdme_solver_data)[source]

Validate the model data structures.

validate should be called prior to writing the model to the solver input file, since the solvers themselves do very limited error checking of the input.

class pyurdme.pyurdme.URDMEResult(model=None, filename=None, loaddata=False)[source]

Bases: dict

Result object for a URDME simulation, extends the dict object.

display(species, time_index)[source]
export_to_particle_js(species, time_index)[source]
export_to_three_js(species, time_index)[source]

Return a json serialized document that can be read and visualized by three.js.

export_to_vtk(species, folder_name)[source]

Dump the trajectory to a collection of vtk files in the folder folder_name (created if non-existant).

export_to_xyx(filename, species=None, file_format='VMD')[source]

Dump the solution attached to a model as a xyz file. This format can be read by e.g. VMD, Jmol and Paraview.

get_d2v()

Return the dof-to-vertex mapping.

get_endtime_model()[source]

Return a URDME model object with the initial conditions set to the final time point of the result object.

get_species(species, timepoints='all', concentration=False)[source]

Returns a slice (view) of the output matrix U that contains one species for the timepoints specified by the time index array. The default is to return all timepoints.

Data is loaded by slicing directly in the hdf5 dataset, i.e. it the entire content of the file is not loaded in memory and the U matrix is never added to the object.

if concentration is False (default), the integer, raw, trajectory data is returned, if set to True, the concentration (=copy_number/volume) is returned.

get_timespan()[source]
get_v2d()

Return the vertex-to-dof mapping.

read_solution()[source]

Read the tspan and U matrix into memory.

class pyurdme.pyurdme.URDMESolver(model, solver_path=None, report_level=0, model_file=None, sopts=None)[source]

Abstract class for URDME solvers.

compile()[source]

Compile the model.

create_propensity_file(file_name=None)[source]

Generate the C propensity file that is used to compile the URDME solvers. Only mass action propensities are supported.

run(number_of_trajectories=1, seed=None, input_file=None, loaddata=False)[source]

Run one simulation of the model.

number_of_trajectories: How many trajectories should be run. seed: the random number seed (incimented by one for multiple runs). input_file: the filename of the solver input data file . loaddata: boolean, should the result object load the data into memory on creation.

Returns:
URDMEResult object.
or, if number_of_trajectories > 1

a list of URDMEResult objects

serialize(filename=None, report_level=0, sopts=None)[source]

Write the datastructures needed by the the core URDME solvers to a .mat input file.

class pyurdme.pyurdme.URDMEXmesh[source]

Extended mesh object.

Contains function spaces and dof mappings.

pyurdme.pyurdme.urdme(model=None, solver='nsm', solver_path='', model_file=None, input_file=None, seed=None, report_level=0)[source]

URDME solver interface.

Similar to model.run() the urdme() function provides an interface that is backwards compatiable with the previous URDME implementation.

After sucessful execution, urdme returns a URDMEResults object with the following members: U: the raw copy number output in a matrix with dimension (Ndofs, num_time_points) tspan: the time span vector containing the time points that corresponds to the columns in U status: Sucess if the solver executed without error stdout: the standard ouput stream from the call to the core solver stderr: the standard error stream from the call to the core solver

pyurdme.model module

This module defines a model of a well mixed biochemical reaction network.

class pyurdme.model.Model(name='', volume=1.0)[source]

Representation of a well mixed biochemical model. Interfaces to solvers in StochSS should attempt to extend Model.

add_parameter(params)[source]

Add Parameter(s) to model.listOfParameters. Input can be either a single Parameter object or a list of Parameter objects.

add_reaction(reacs)[source]

Add Reaction(s) to the model. Input can be single instance, a list of instances or a dict with name,instance pairs.

add_species(obj)[source]

Add a Species to listOfSpecies. Accepts input either as a single Species object, or as a list of Species objects.

delete_all_parameters()[source]
delete_all_reactions()[source]
delete_all_species()[source]
delete_parameter(obj)[source]
delete_reaction(obj)[source]
delete_species(obj)[source]

Remove a Species from model.listOfSpecies.

get_all_parameters()[source]
get_all_reactions()[source]
get_all_species()[source]
get_num_reactions()[source]
get_num_species()[source]
get_parameter(pname)[source]
get_reaction(rname)[source]
get_species(sname)[source]
resolve_parameters()[source]

Attempt to resolve all parameter expressions to scalar floating point values. Must be called prior to exporting the model.

set_parameter(pname, expression)[source]

Set the expression of an existing paramter.

update_namespace()[source]

Create a dict with flattened parameter and species objects.

exception pyurdme.model.ModelError[source]

Bases: exceptions.Exception

class pyurdme.model.Parameter(name='', expression=None, value=None)[source]

Model of a rate paramter. A parameter can be given as a String expression (function) or directly as a scalar value. If given a String expression, it should be evaluable in the namespace of a parent Model.

evaluate(namespace={})[source]

Evaluate the expression and return the (scalar) value

set_expression(expression)[source]
exception pyurdme.model.ParameterError[source]

Bases: pyurdme.model.ModelError

class pyurdme.model.Reaction(name='', reactants={}, products={}, propensity_function=None, massaction=None, rate=None, annotation=None, restrict_to=None)[source]

Models a biochemical reaction. A reaction conatains dictinaries of species (reactants and products) and parameters. The reaction’s propensity function needs to be evaluable and result in a non-negative scalar value in the namespace defined by the union of its Reactant, Product and Parameter dictionaries.

add_product(S, stoichiometry)[source]
add_reactant(S, stoichiometry)[source]
annotate(annotation)[source]
create_mass_action()[source]

Create a mass action propensity function given self.reactants and a single parameter value.

set_type(type)[source]
exception pyurdme.model.ReactionError[source]

Bases: pyurdme.model.ModelError

class pyurdme.model.Species(name='', diffusion_constant=None, reaction_radius=None, dimension=3)[source]

Model of a biochemical species.

dim()[source]
exception pyurdme.model.SpeciesError[source]

Bases: pyurdme.model.ModelError

pyurdme.nsmsolver module

NSM solver.

class pyurdme.nsmsolver.NSMSolver(model, solver_path=None, report_level=0, model_file=None, sopts=None)[source]

Bases: pyurdme.pyurdme.URDMESolver

NSM solver class.

NAME = 'nsm'

Table Of Contents

Previous topic

Installing PyURDME

Next topic

PyURDME Examples

This Page