E-Cell4 spatiocyte API

class ecell4.spatiocyte.ReactionInfo

A class stores detailed information about a reaction in spatiocyte.

ReactionInfo(t, reactants, products)

Methods

products Return a list of products
reactants Return a list of reactants
t Return a time when a reaction occurred.
products()

Return a list of products

Returns:
list: A list of pairs of ParticleID and Voxel.
reactants()

Return a list of reactants

Returns:
list: A list of pairs of ParticleID and Voxel.
t()

Return a time when a reaction occurred.

class ecell4.spatiocyte.SpatiocyteFactory

A factory class creating a SpatiocyteWorld instance and a SpatiocyteSimulator instance.

SpatiocyteFactory(Real voxel_radius)

Methods

create_simulator((arg1, ...) Return a SpatiocyteSimulator instance.
create_world((arg1=None) -> SpatiocyteWorld) Return a SpatiocyteWorld instance.
rng(...) Set a random number generator, and return self.
create_simulator(arg1, arg2) → SpatiocyteSimulator

Return a SpatiocyteSimulator instance.

Parameters:

arg1 : SpatiocyteWorld

A world

or

arg1 : Model

A simulation model

arg2 : SpatiocyteWorld

A world

Returns:

SpatiocyteSimulator:

The created simulator

create_world(arg1=None) → SpatiocyteWorld

Return a SpatiocyteWorld instance.

Parameters:

arg1 : Real3

The lengths of edges of a SpatiocyteWorld created

or

arg1 : str

The path of a HDF5 file for SpatiocyteWorld

Returns:

SpatiocyteWorld:

The created world

rng(GSLRandomNumberGenerator) → SpatiocyteFactory

Set a random number generator, and return self.

class ecell4.spatiocyte.SpatiocyteSimulator

A class running the simulation with the spatiocyte algorithm.

SpatiocyteSimulator(m, w)

Methods

check_reaction Return if any reaction occurred at the last step, or not.
dt Return the step interval.
initialize Initialize the simulator.
last_reactions(() -> [(ReactionRule, ...) Return reactions occuring at the last step.
model Return the model bound.
next_time Return the scheduled time for the next step.
num_steps Return the number of steps.
run(duration, observers) Run the simulation.
set_dt(dt) Set a step interval.
set_t(t) Set the current time.
step((upto=None) -> bool) Step the simulation.
t Return the time.
world Return the world bound.
check_reaction()

Return if any reaction occurred at the last step, or not.

dt()

Return the step interval.

initialize()

Initialize the simulator.

last_reactions() → [(ReactionRule, ReactionInfo)]

Return reactions occuring at the last step.

Returns:

list:

The list of reaction rules and infos.

model()

Return the model bound.

next_time()

Return the scheduled time for the next step.

num_steps()

Return the number of steps.

run(duration, observers)

Run the simulation.

Parameters:

duration : Real

A duration for running a simulation. A simulation is expected to be stopped at t() + duration.

observers : list of Obeservers, optional

observers

set_dt(dt)

Set a step interval.

Parameters:

dt : Real

A step interval

set_t(t)

Set the current time.

Parameters:

t : Real

A current time.

step(upto=None) → bool

Step the simulation.

Parameters:

upto : Real, optional

The time which to step the simulation up to

Returns:

bool:

True if the simulation did not reach the given time. When upto is not given, nothing will be returned.

t()

Return the time.

world()

Return the world bound.

class ecell4.spatiocyte.SpatiocyteWorld

A class containing the properties of the spatiocyte world.

SpatiocyteWorld(edge_lengths=None, voxel_radius=None, GSLRandomNumberGenerator rng=None)

Methods

actual_lengths Return the actual edge lengths of the world.
add_interface(sp, shape) Add a interface.
add_molecules(sp, num[, shape]) Add some molecules.
add_structure(sp, shape) Add a structure.
as_base Return self as a base class.
bind_to(m) Bind a model to the world
calculate_hcp_lengths(...) Calculate HCP lengths (HCP_L, HCP_X, HCP_Y) from a voxel radius.
calculate_shape((Real3 edge_lengths, ...) Calculate World shape.
calculate_volume((Real3 edge_lengths, ...) Calculate World volume.
calculate_voxel_volume Calculate a voxel volume from a voxel radius.
coordinate2position((coord) -> Real3) Transform a coordinate to a position.
edge_lengths(() -> Real3) Return the edge lengths of the world.
get_neighbor((coord, nrand) -> Integer) Return the neighbor coordinate of a given coordinate.
get_particle(pid) -> (ParticleID, Particle) Return the particle associated a given ParticleID.
get_value((sp) -> Real) Return the value (number) corresponding the given Species.
get_value_exact((sp) -> Real) Return the value (number) corresponding the given Species.
get_volume((sp) -> Real) Return a volume of the given structure.
get_voxel(pid) -> (ParticleID, Voxel) Return the voxel having a particle associated with a given ParticleID.
get_voxel_at(coord) -> (ParticleID, Voxel) Return the voxel at a given coordinate.
has_particle((pid) -> bool) Check if a particle associated with a given particle id exists.
has_voxel((pid) -> bool) Check if a particle exists.
list_non_structure_particles list_strucutre_particles() -> [(ParticleID, Particle)]
list_non_structure_species(() -> [Species]) Return the list of non-structure species.
list_particles((sp) -> [(ParticleID, Particle)]) Return the list of particles.
list_particles_exact((sp) -> [(ParticleID, ...) Return the list of particles of a given species.
list_species(() -> [Species]) Return the list of species.
list_structure_particles list_strucutre_particles() -> [(ParticleID, Particle)]
list_structure_species(() -> [Species]) Return the list of structure species.
list_voxels((sp=None) -> [ParitcleID, Voxel]) Returns the list of voxels.
list_voxels_exact((sp) -> [ParitcleID, Voxel]) Returns the list of voxels.
load(filename) Load the world from a file.
new_particle(arg1[, arg2]) Create a new particle.
new_voxel(arg1, arg2) -> (ParticleID, Voxel) Create a particle.
new_voxel_interface(arg1, ...) Create a particle.
new_voxel_structure(arg1, ...) Create a particle.
num_molecules((sp) -> Integer) Return the number of molecules.
num_molecules_exact((sp) -> Integer) Return the number of molecules of a given species.
num_particles((sp=None) -> Integer) Return the number of particles.
num_particles_exact((sp) -> Integer) Return the number of particles of a given species.
num_voxels((sp=None) -> Integer) Return the number of voxels.
num_voxels_exact((sp) -> Integer) Return the number of voxels of a given species.
on_structure Check if the given voxel would be on the proper structure at the coordinate
position2coordinate((pos) -> Integer) Transform a position to a coordinate.
remove_molecules(sp, num) Remove the molecules.
remove_particle(pid) Remove the particle associated with a given ParticleID.
remove_voxel(pid) Remove the particle associated with a given ParticleID.
rng Return a random number generator object.
save(filename) Save the world to a file.
set_t(t) Set the value of the time of the world.
set_value(sp, value) Set the value of the given species.
shape(() -> Integer3) Return the triplet of sizes of column, row and layer.
size Return the size of voxels.
t Return the time of the world.
update_particle(pid, p) Update a particle.
update_voxel((pid, v) -> bool) Update a particle.
volume Return the volume of the world.
voxel_radius Return the voxel radius.
voxel_volume Return the volume of a voxel.
actual_lengths()

Return the actual edge lengths of the world.

Returns:

Real3:

The actual edge lengths of the world

add_interface(sp, shape)

Add a interface.

Parameters:

sp : Species

A species suggesting the interface.

add_molecules(sp, num, shape=None)

Add some molecules.

Parameters:

sp : Species

A species of molecules to add

num : Integer

The number of molecules to add

shape : Shape, optional

A shape to add molecules on

add_structure(sp, shape)

Add a structure.

Parameters:

sp : Species

A species suggesting the shape.

shape : Shape

A shape of the structure.

as_base()

Return self as a base class. Only for developmental use.

bind_to(m)

Bind a model to the world

Parameters:

m : Model

A model to bind

static calculate_hcp_lengths(Real voxel_radius) → Real3

Calculate HCP lengths (HCP_L, HCP_X, HCP_Y) from a voxel radius.

static calculate_shape(Real3 edge_lengths, Real voxel_radius) → Integer3

Calculate World shape.

static calculate_volume(Real3 edge_lengths, Real voxel_radius) → Real

Calculate World volume.

static calculate_voxel_volume()

Calculate a voxel volume from a voxel radius.

coordinate2position(coord) → Real3

Transform a coordinate to a position.

edge_lengths() → Real3

Return the edge lengths of the world.

get_neighbor(coord, nrand) → Integer

Return the neighbor coordinate of a given coordinate.

Parameters:

coord : Integer

A coordinate of a voxel

nrand : Integer

A key in the range from 0 to 11 to assign a neighbor voxel

Returns:

Integer:

The coordinate of the neighbor voxel

get_particle(pid) -> (ParticleID, Particle)

Return the particle associated a given ParticleID.

Parameters:

pid : ParticleID

A id of the particle you want

Returns:

tuple:

A pair of ParticleID and Particle

get_value(sp) → Real

Return the value (number) corresponding the given Species.

Parameters:

sp : Species

a species whose value you require

Returns:

Real:

the value

get_value_exact(sp) → Real

Return the value (number) corresponding the given Species.

Parameters:

sp : Species

a species whose value you require

Returns:

Real:

the value

get_volume(sp) → Real

Return a volume of the given structure.

Parameters:

sp : Species

A species for the target structure.

Returns:

Real:

A total volume of voxels belonging to the structure.

get_voxel(pid) -> (ParticleID, Voxel)

Return the voxel having a particle associated with a given ParticleID.

Parameters:

pid : ParticleID

An id of the particle in the voxel you want

Returns:

tuple:

A pair of ParticleID and Voxel

get_voxel_at(coord) -> (ParticleID, Voxel)

Return the voxel at a given coordinate.

Parameters:

coord: Integer

A coordinate of the voxel you want

Returns:

tuple:

A pair of ParticleID and Voxel

has_particle(pid) → bool

Check if a particle associated with a given particle id exists.

Parameters:

pid : ParticleID

A particle id to check

Returns:

bool:

if a particle exists, this is true. Otherwise false

has_voxel(pid) → bool

Check if a particle exists.

Parameters:

pid : ParticleID

A particle id of the particle to check

Returns:

bool:

whether a particle associated with a given particle id exists

list_non_structure_particles()

list_strucutre_particles() -> [(ParticleID, Particle)]

Return the list of non-structure particles

Returns:

list:

The list of particles not constructing a structure

list_non_structure_species() → [Species]

Return the list of non-structure species.

Returns:

list:

The list of species not constructing structure

list_particles(sp) → [(ParticleID, Particle)]

Return the list of particles.

Parameters:

sp : Species, optional

The species of particles to list up If no species is given, return the whole list of particles.

Returns:

list:

The list of particles (of the given species)

list_particles_exact(sp) → [(ParticleID, Particle)]

Return the list of particles of a given species.

Parameters:

sp : Species

The species of particles to list up

Returns:

list:

The list of particles of a given species

list_species() → [Species]

Return the list of species.

Returns:

list:

The list of species

list_structure_particles()

list_strucutre_particles() -> [(ParticleID, Particle)]

Return the list of structure particles

Returns:

list:

The list of particles constructing a structure

list_structure_species() → [Species]

Return the list of structure species.

Returns:

list:

The list of species constructing structure

list_voxels(sp=None) → [ParitcleID, Voxel]

Returns the list of voxels.

Parameters:

sp : Species, optional

A species of particles to list up. If no species is given, return a list of all voxels.

Returns:

list:

The list of the pair of ParticleID and Voxel

list_voxels_exact(sp) → [ParitcleID, Voxel]

Returns the list of voxels.

Parameters:

sp : Species, optional

A species of particles to list up. If no species is given, return a list of all voxels.

Returns:

list:

The list of the pair of ParticleID and Voxel

load(filename)

Load the world from a file.

Parameters:

filename : str

A filename to load from

new_particle(arg1, arg2=None) -> (ParticleID, Particle)

Create a new particle.

Parameters:

arg1 : Particle

A particle to be placed.

or

arg1 : Species

A species of a particle

arg2 : Real3

A coordinate to place a particle

Returns:

tuple:

A pair of ParticleID and Particle of a new particle

new_voxel(arg1, arg2) -> (ParticleID, Voxel)

Create a particle.

Parameters:

arg1 : Voxel

The information to create

or

arg1 : Species

The Species of particles to create

arg2 : Integer

The number of particles(voxels)

Returns:

tuple:

A pair of ParticleID and Voxel

new_voxel_interface(arg1, arg2) -> (ParticleID, Voxel)

Create a particle.

Parameters:

arg1 : Species

The Species of particles to create

arg2 : Integer

A coordinate to place the structure

Returns:

tuple:

A pair of ParticleID and Voxel

new_voxel_structure(arg1, arg2) -> (ParticleID, Voxel)

Create a particle.

Parameters:

arg1 : Species

The Species of particles to create

arg2 : Integer

A coordinate to place the structure

Returns:

tuple:

A pair of ParticleID and Voxel

num_molecules(sp) → Integer

Return the number of molecules.

Parameters:

sp : Species

A species whose molecules you count

Returns:

Integer:

The number of molecules (of a given species)

num_molecules_exact(sp) → Integer

Return the number of molecules of a given species.

Parameters:

sp : Species

A species whose molecules you count

Returns:

Integer:

The number of molecules of a given species

num_particles(sp=None) → Integer

Return the number of particles.

Parameters:

sp : Species, optional

The species of particles to count If no species is given, return the total number of particles.

Returns:

Integer:

The number of particles (of the given species)

num_particles_exact(sp) → Integer

Return the number of particles of a given species.

Parameters:

sp : Species

The species of particles to count

Returns:

Integer:

The number of particles of a given species

num_voxels(sp=None) → Integer

Return the number of voxels.

Parameters:

sp : Species, optional

The species of particles to count

Returns:

Integer:

The number of voxels (of the given species)

num_voxels_exact(sp) → Integer

Return the number of voxels of a given species.

Parameters:

sp : Species

The species of particles to count

Returns:

Integer:

The number of voxels of a given species

on_structure()

Check if the given voxel would be on the proper structure at the coordinate Args:

v (Voxel): a voxel scheduled to be placed
Returns:
bool: if it is on the proper structure, or not
position2coordinate(pos) → Integer

Transform a position to a coordinate.

Parameters:

pos : Real3

A position

Returns:

Integer:

A coordinate

remove_molecules(sp, num)

Remove the molecules.

Parameters:

sp : Species

A species whose molecules to remove

num : Integer

A number of molecules to be removed

remove_particle(pid)

Remove the particle associated with a given ParticleID.

Parameters:

pid : ParticleID

A id of particle to remove

remove_voxel(pid)

Remove the particle associated with a given ParticleID.

Parameters:

pid : ParticleID

A id of particle to remove

rng()

Return a random number generator object.

save(filename)

Save the world to a file.

Parameters:

filename : str

A filename to save to

set_t(t)

Set the value of the time of the world.

Parameters:

t : Real

The time of the world

set_value(sp, value)

Set the value of the given species.

Parameters:

sp : Species

a species whose value you set

value : Real

a value set

shape() → Integer3

Return the triplet of sizes of column, row and layer.

size()

Return the size of voxels.

t()

Return the time of the world.

update_particle(pid, p)

Update a particle.

Parameters:

pid : ParticleID

A particle id of the particle to update

p : Particle

The information to update a particle

Returns:

bool:

True if a new particle was created.

update_voxel(pid, v) → bool

Update a particle.

Parameters:

pid : ParticleID

A particle id of the particle to update

v : Voxel

The information to update

Returns:

bool:

whether to succeed to update the particle

volume()

Return the volume of the world.

voxel_radius()

Return the voxel radius.

voxel_volume()

Return the volume of a voxel.