E-Cell4 bd API

class ecell4.bd.BDFactory

A factory class creating a BDWorld instance and a BDSimulator instance.

BDFactory(Integer3 matrix_sizes=None, Real bd_dt_factor=None)

Methods

create_simulator((arg1[, arg2]) Return a BDSimulator instance.
create_world((arg1=None) -> BDWorld) Return a BDWorld instance.
rng((GSLRandomNumberGenerator) -> BDFactory) Set a random number generator, and return self.
create_simulator(arg1, arg2=None) → BDSimulator

Return a BDSimulator instance.

Parameters:

arg1 : BDWorld

A world

or

arg1 : Model

A simulation model

arg2 : BDWorld

A world

Returns:

BDSimulator:

The created simulator

create_world(arg1=None) → BDWorld

Return a BDWorld instance.

Parameters:

arg1 : Real3

The lengths of edges of a BDWorld created

or

arg1 : str

The path of a HDF5 file for BDWorld

Returns:

BDWorld:

The created world

rng(GSLRandomNumberGenerator) → BDFactory

Set a random number generator, and return self.

class ecell4.bd.BDSimulator

A class running the simulation with the bd algorithm.

BDSimulator(m, w, bd_dt_factor)

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.bd.BDWorld

A class containing the properties of the bd world.

BDWorld(edge_lengths=None, matrix_sizes=None, GSLRandomNumberGenerator rng=None)

Methods

actual_lengths(() -> Real3) Return the actual edge lengths of the world.
add_molecules(sp, num[, shape]) Add some molecules.
apply_boundary((Real3 pos) -> Real3) Return a position within the world by applying periodic boundaries to the given position.
as_base Return self as a base class.
bind_to(m) Bind a model to the world
distance((Real3 pos1, Real3 pos2) -> Real) Return the closest distance between the given positions.
distance_sq((Real3 pos1, Real3 pos2) -> Real) Return a square of the closest distance between the given positions.
edge_lengths(() -> Real3) Return the edge lengths of the world.
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.
has_particle((pid) -> bool) Check if a particle associated with a given particle id exists.
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_particles_within_radius((pos, radius[, ...]) Returns a list of pairs of a particle and distance within the given sphere.
list_species Return a list of species.
load(filename) Load the world from a file.
new_particle(arg1[, arg2]) Create a new 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.
periodic_transpose((Real3 pos1, ...) Return a closest image of pos1 relative to the given position (pos2).
remove_molecules(sp, num) Remove the molecules.
remove_particle(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.
t Return the time of the world.
update_particle((pid, p) -> bool) Update a particle.
volume Return the volume of the world.
actual_lengths() → Real3

Return the actual edge lengths of the world. Same as edge_lengths.

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 [not supported yet]

apply_boundary(Real3 pos) → Real3

Return a position within the world by applying periodic boundaries to the given position.

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

distance(Real3 pos1, Real3 pos2) → Real

Return the closest distance between the given positions.

distance_sq(Real3 pos1, Real3 pos2) → Real

Return a square of the closest distance between the given positions.

edge_lengths() → Real3

Return the edge lengths of the world.

get_particle(pid) -> (ParticleID, Particle)

Return the particle associated a given ParticleID.

Parameters:

pid : ParticleID

An 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

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, return True. Otherwise return False

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_particles_within_radius(pos, radius, ignore1=None, ignore2=None) → [((ParticleID, Particle), Real)]

Returns a list of pairs of a particle and distance within the given sphere. The region is specified with a center position and radius. ignore1 and ignore2 will be removed from the list.

Parameters:

pos : Real3

A center position.

radius : Real

A radius.

ignore1 : ParticleID, optional

An id ignored.

ignore2 : ParticleID, optional

An id ignored.

Returns:

list:

A list of pairs of a particle and its distance from the center position.

list_species()

Return a list of species.

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 position to place a particle

Returns:

tuple:

A pair of ParticleID and Particle of a new particle

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

periodic_transpose(Real3 pos1, Real3 pos2) → Real3

Return a closest image of pos1 relative to the given position (pos2).

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

An 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

t()

Return the time of the world.

update_particle(pid, p) → bool

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.

volume()

Return the volume of the world.

class ecell4.bd.ReactionInfo

A class stores detailed information about a reaction in bd.

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 Particle.
reactants()

Return a list of reactants

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

Return a time when a reaction occurred.