E-Cell4 egfrd API

class ecell4.egfrd.BDFactory

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

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

Methods

create_simulator((arg1, arg2) -> BDSimulator) Return a BDSimulator instance.
create_world((arg1=None) -> EGFRDWorld) Return a EGFRDWorld instance.
rng((GSLRandomNumberGenerator) -> BDFactory) Set a random number generator, and return self.
create_simulator(arg1, arg2) → 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) → EGFRDWorld

Return a EGFRDWorld instance.

Parameters:

arg1 : Real3

The lengths of edges of a EGFRDWorld created

or

arg1 : str

The path of a HDF5 file for EGFRDWorld

Returns:

EGFRDWorld:

The created world

rng(GSLRandomNumberGenerator) → BDFactory

Set a random number generator, and return self.

class ecell4.egfrd.BDSimulator

A class running the simulation with the bd algorithm.

BDSimulator(m, w)

Methods

check_reaction Return if any reaction occurred at the last step, or not.
dt Return the step interval.
dt_factor
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.egfrd.EGFRDFactory

A factory class creating a EGFRDWorld instance and a EGFRDSimulator instance.

EGFRDFactory(Integer3 matrix_sizes=None, Real bd_dt_factor=None,
Integer dissociation_retry_moves=None, Real user_max_shell_size=None)

Methods

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

Return a EGFRDSimulator instance.

Parameters:

arg1 : EGFRDWorld

A world

or

arg1 : Model

A simulation model

arg2 : EGFRDWorld

A world

Returns:

EGFRDSimulator:

The created simulator

create_world(arg1=None) → EGFRDWorld

Return a EGFRDWorld instance.

Parameters:

arg1 : Real3

The lengths of edges of a EGFRDWorld created

or

arg1 : str

The path of a HDF5 file for EGFRDWorld

Returns:

EGFRDWorld:

The created world

rng(GSLRandomNumberGenerator) → EGFRDFactory

Set a random number generator, and return self.

class ecell4.egfrd.EGFRDSimulator

A class running the simulation with the egfrd algorithm.

EGFRDSimulator(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_paranoiac
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.egfrd.EGFRDWorld

A class containing the properties of the egfrd world.

EGFRDWorld(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.
bind_to(m) Bind a model to the world
distance((Real3 pos1, Real3 pos2) -> Real) Return 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.
has_species((sp) -> bool) Check if the given species is in the space or not.
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.
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.
set_value(sp, value) Set the value of the given species.
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.

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.

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

has_species(sp) → bool

Check if the given species is in the space or not.

Parameters:

sp : Species

A species to be found.

Returns:

bool:

True if the species in the space.

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

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

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

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.egfrd.ReactionInfo

A class stores detailed information about a reaction in egfrd.

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.