E-Cell4 core API

class ecell4.core.AABB

A class representing an axis aligned bounding box (AABB), which is available to define structures.

AABB(lower, upper)

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
distance Return a minimum distance from the given point to the surface.
is_inside Return if the given point is inside or not.
lower Return a vertex suggesting the lower bounds.
surface Create and return a surface shape.
upper Return a vertex suggesting the upper bounds.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

distance()

Return a minimum distance from the given point to the surface.

Parameters:

pos : Real3

A position.

Returns:

distance : float

A minimum distance from the given point. Negative if the given point is inside.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

lower()

Return a vertex suggesting the lower bounds.

surface()

Create and return a surface shape.

Returns:

shape : Surface

The surface shape.

upper()

Return a vertex suggesting the upper bounds.

class ecell4.core.AffineTransformation

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
is_inside Return if the given point is inside or not.
rescale Rescale the object.
surface Create and return a surface shape.
translate Translate the object.
xroll Roll the object around x-axis.
yroll Roll the object around y-axis.
zroll Roll the object around z-axis.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

rescale()

Rescale the object.

Parameters:

value : Real3

A scaling factor

surface()

Create and return a surface shape.

Returns:

shape : Surface

The surface shape.

translate()

Translate the object.

Parameters:

value : Real3

A shift

xroll()

Roll the object around x-axis.

Parameters:

value : Real

A rotation angle

yroll()

Roll the object around y-axis.

Parameters:

value : Real

A rotation angle

zroll()

Roll the object around z-axis.

Parameters:

value : Real

A rotation angle

class ecell4.core.CSVObserver

An Observer class to log the state of World in CSV format. This Observer saves the World at the current time first, and then keeps saving every after steps.

CSVObserver(filename, species=None)

Methods

as_base Clone self as a base class.
filename Return a file name to be saved at the next time
log Force to log the given World to a file.
next_time Return the next time for logging.
num_steps Return the number of steps.
reset Reset the internal state.
set_formatter Set the formatter.
set_header Set the header.
as_base()

Clone self as a base class. This function is for developers.

filename()

Return a file name to be saved at the next time

log()

Force to log the given World to a file.

Parameters:

w : Space

A Space (World) to be logged.

Examples

This is an easy way to save a World in CSV format without running a simulation.

>>> w = spatiocyte.SpatiocyteWorld(Real3(1, 1, 1), 0.005)
>>> w.bind_to(NetworkModel())
>>> w.add_molecules(Species("A"), 3)
>>> CSVObserver(1, "test.csv").log(w)
>>> print(open("test.csv").read())
x,y,z,r,sid
0.10614455552060439,0.66106605822212161,0.81500000000000006,0.0050000000000000001,0
0.38375339303603129,0.37527767497325676,0.23999999999999999,0.0050000000000000001,0
0.25311394008759508,0.05484827557301445,0.495,0.0050000000000000001,0
next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

reset()

Reset the internal state.

set_formatter()

Set the formatter.

8 arguments are given: (1) the current time, (2-4) x, y, z, (5) radius, (6-7) lot and serial of a ParticleID, (8) species index. (1-5) are Real, and (6-8) Integer. Its default value is ‘%2%,%3%,%4%,%5%,%8%’.

set_header()

Set the header. ‘x,y,z,r,sid’ as a default.

class ecell4.core.Cylinder

A class representing a cylinder shape, which is available to define structures.

Cylinder(center, radius, axis, half_height)

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
distance Return a minimum distance from the given point to the surface.
is_inside Return if the given point is inside or not.
surface Create and return a surface shape.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

distance()

Return a minimum distance from the given point to the surface.

Parameters:

pos : Real3

A position.

Returns:

distance : float

A minimum distance from the given point. Negative if the given point is inside.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

surface()

Create and return a surface shape.

Returns:

shape : CylindricalSurface

The surface shape.

class ecell4.core.CylindricalSurface

A class representing a hollow cylindrical surface, which is available to define structures.

CylindricalSurface(center, radius, axis, half_height)

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
distance Return a minimum distance from the given point to the surface.
inside Create and return a volume shape.
is_inside Return if the given point is inside or not.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

distance()

Return a minimum distance from the given point to the surface.

Parameters:

pos : Real3

A position.

Returns:

distance : float

A minimum distance from the given point. Negative if the given point is inside.

inside()

Create and return a volume shape.

Returns:

shape : Cylinder

The volume shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

class ecell4.core.FixedIntervalCSVObserver

An Observer class to log the state of World in CSV format with the fixed step interval. This Observer saves the World at the current time first, and then keeps saving every after the interval.

FixedIntervalCSVObserver(dt, filename, species=None)

Methods

as_base Clone self as a base class.
filename Return a file name to be saved at the next time
log Force to log the given World to a file.
next_time Return the next time for logging.
num_steps Return the number of steps.
reset Reset the internal state.
set_formatter Set the formatter.
set_header Set the header.
as_base()

Clone self as a base class. This function is for developers.

filename()

Return a file name to be saved at the next time

log()

Force to log the given World to a file.

Parameters:

w : Space

A Space (World) to be logged.

Examples

This is an easy way to save a World in CSV format without running a simulation.

>>> w = spatiocyte.SpatiocyteWorld(Real3(1, 1, 1), 0.005)
>>> w.bind_to(NetworkModel())
>>> w.add_molecules(Species("A"), 3)
>>> FixedIntervalCSVObserver(1, "test.csv").log(w)
>>> print(open("test.csv").read())
x,y,z,r,sid
0.10614455552060439,0.66106605822212161,0.81500000000000006,0.0050000000000000001,0
0.38375339303603129,0.37527767497325676,0.23999999999999999,0.0050000000000000001,0
0.25311394008759508,0.05484827557301445,0.495,0.0050000000000000001,0
next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

reset()

Reset the internal state.

set_formatter()

Set the formatter.

8 arguments are given: (1) the current time, (2-4) x, y, z, (5) radius, (6-7) lot and serial of a ParticleID, (8) species index. (1-5) are Real, and (6-8) Integer. Its default value is ‘%2%,%3%,%4%,%5%,%8%’.

set_header()

Set the header. ‘x,y,z,r,sid’ as a default.

class ecell4.core.FixedIntervalHDF5Observer

An Observer class to log the state of World in HDF5 format with the fixed step interval. This Observer saves the World at the current time first, and then keeps saving every after the interval.

FixedIntervalHDF5Observer(dt, filename)

Methods

as_base Clone self as a base class.
filename Return a file name to be saved at the next time
next_time Return the next time for logging.
num_steps Return the number of steps.
prefix Return a prefix of a file name given at the construction
reset Reset the internal state.
as_base()

Clone self as a base class. This function is for developers.

filename()

Return a file name to be saved at the next time

next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

prefix()

Return a prefix of a file name given at the construction

reset()

Reset the internal state.

class ecell4.core.FixedIntervalNumberObserver

An Observer``class to log the number of molecules with the fixed step interval. This ``Observer logs at the current time first, and then keeps logging every after the interval.

FixedIntervalNumberObserver(dt, species)

Methods

as_base Clone self as a base class.
data Return a list of the number of molecules you specified.
next_time Return the next time for logging.
num_steps Return the number of steps.
reset Reset the internal state.
save Save data to an output with the given filename.
targets Return a list of Species, which this Observer observes
as_base()

Clone self as a base class. This function is for developers.

data()

Return a list of the number of molecules you specified.

Returns:

list:

A list of lists of the numbers of molecules. The size of a return value is equal to num_steps. Each element of a return value is a list consisting of time and the number of molecules specified at the construction.

next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

reset()

Reset the internal state.

save()

Save data to an output with the given filename.

targets()

Return a list of Species, which this Observer observes

Returns:

list:

A list of Species. This is generated from arguments you gave at the construction.

class ecell4.core.FixedIntervalTrackingObserver

An Observer class to trace and log trajectories of diffusing particles in a World with the fixed step interval. This Observer logs at the current time first, and then keeps logging every after the interval.

FixedIntervalTrackingObserver(dt, species, resolve_boundary=None, subdt=None, threshold=None)

Methods

as_base Clone self as a base class.
data Return a list of trajectories for each particles.
next_time Return the next time for logging.
num_steps Return the number of steps.
num_tracers Return the number of tracer molecules.
reset Reset the internal state.
t Return time points at logging as a list.
as_base()

Clone self as a base class. This function is for developers.

data()

Return a list of trajectories for each particles.

Returns:

list:

A list of lists of Real3. An element of a return value is corresponding the trajectory of each particle. Thus, the size of a return value is the same with that of pids you gave at the construction. If a particle corresponding to the given ParticleID is missing, i.e. for a reaction, this Observer just skips to log the position. Therefore, lengths of the trajectories can be diverse.

next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

num_tracers()

Return the number of tracer molecules.

reset()

Reset the internal state.

t()

Return time points at logging as a list.

class ecell4.core.FixedIntervalTrajectoryObserver

An Observer class to trace and log trajectories of diffusing particles in a World with the fixed step interval. This Observer logs at the current time first, and then keeps logging every after the interval.

FixedIntervalTrajectoryObserver(dt, pids=None, resolve_boundary=None, subdt=None)

Methods

as_base Clone self as a base class.
data Return a list of trajectories for each particles.
next_time Return the next time for logging.
num_steps Return the number of steps.
num_tracers Return the number of tracer molecules.
reset Reset the internal state.
t Return time points at logging as a list.
as_base()

Clone self as a base class. This function is for developers.

data()

Return a list of trajectories for each particles.

Returns:

list:

A list of lists of Real3. An element of a return value is corresponding the trajectory of each particle. Thus, the size of a return value is the same with that of pids you gave at the construction. If a particle corresponding to the given ParticleID is missing, i.e. for a reaction, this Observer just skips to log the position. Therefore, lengths of the trajectories can be diverse.

next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

num_tracers()

Return the number of tracer molecules.

reset()

Reset the internal state.

t()

Return time points at logging as a list.

class ecell4.core.GSLRandomNumberGenerator

A random number generator using the GNU Scientific Library (GSL).

GSLRandomNumberGenerator(Integer myseed=None)

Methods

binomial((p, n) -> Integer) Return a random integer from the binomial distribution, the number of successes in n independent trials with probability p.
gaussian((sigma, mean = None) -> Real) Return a Gaussian variate with the given mean and standard deviation.
load(filename) Load the random number generator state from a file.
save(filename) Save the random number generator state to a file.
seed([val]) Reset the random number seed.
uniform((min, max) -> Real) Return a uniform random number within the given range.
uniform_int((min, max) -> Integer) Return a uniform random number within the given range.
binomial(p, n) → Integer

Return a random integer from the binomial distribution, the number of successes in n independent trials with probability p.

Parameters:

p : Real

A probability.

n : Integer

The number of trials.

Returns:

Integer:

A random integer from a binomial distribution.

gaussian(sigma, mean = None) → Real

Return a Gaussian variate with the given mean and standard deviation.

Parameters:

sigma : Real

The standard deviation.

mean : Real

The mean value.

Returns:

Real:

A random number from a Gaussian distribution.

load(filename)

Load the random number generator state from a file.

Parameters:

filename : str

A filename to load from

save(filename)

Save the random number generator state to a file.

Parameters:

filename : str

A filename to save to

seed(val=None)

Reset the random number seed.

Parameters:

val : Integer, optional

A new seed. If no seed is given, reset the seed by the current time.

uniform(min, max) → Real

Return a uniform random number within the given range.

Parameters:

min : Real

The minimum value in the range.

max : Real

The maximum value in the range.

Returns:

Real:

A random number uniformly distributed in the range [min, max).

uniform_int(min, max) → Integer

Return a uniform random number within the given range.

Parameters:

min : Real

The minimum value in the range.

max : Real

The maximum value in the range.

Returns:

Integer:

A random integer uniformly distributed in the range [min, max].

class ecell4.core.Integer3

A class representing a vector consisting of three integers.

Integer3(Integer p1, Integer p2, Integer p3)

Attributes

col Return the first value.
layer Return the third value.
row Return the second value.
col

Return the first value.

layer

Return the third value.

row

Return the second value.

class ecell4.core.MeshSurface

A class representing a triangular mesh surface, which is available to define structures. The polygonal shape is given as a STL (STereoLithography) format. This object needs VTK support.

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
is_inside Return if the given point is inside or not.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

class ecell4.core.Model

A base class of a model

Model()

Methods

add_reaction_rule(rr) Add a new reaction rule.
add_reaction_rules(rrs) Add a list of new reaction rules.
add_species_attribute(sp) Add a species attribute to the bottom.
add_species_attributes(attrs) Extend a list of species attributes to the bottom.
apply_species_attributes((sp) -> Species) Return a species with attributes.
expand((seeds[, max_itr, max_stoich]) Expand a rule-based model into a network model.
has_reaction_rule((rr) -> bool) Return if the given reaction rule is existing or not.
has_species_attribute((sp) -> bool) Return if the given species can be attributed or not.
list_species Return a list of species, contained in reaction rules in the model.
num_reaction_rules Return a number of reaction rules contained in the model.
query_reaction_rules((sp1[, sp2]) Query and return a list of reaction rules, which have the given species as their reactants.
reaction_rules Return a list of reaction rules contained in the model.
remove_reaction_rule(rr) Remove a reaction rule.
remove_species_attribute(sp) Remove the species attribute.
species_attributes Return a list of species attributes contained in the model.
add_reaction_rule(rr)

Add a new reaction rule.

Parameters:

rr : ReactionRule

A new reaction rule.

add_reaction_rules(rrs)

Add a list of new reaction rules.

Parameters:

rrs : list

A list of new ``ReactionRule``s.

add_species_attribute(sp)

Add a species attribute to the bottom.

Parameters:

sp : Species

A new species with attributes.

add_species_attributes(attrs)

Extend a list of species attributes to the bottom.

Parameters:

attrs : list

A list of new Species with attributes.

apply_species_attributes(sp) → Species

Return a species with attributes.

Parameters:

sp : Species

An original species.

Returns:

Species:

A new species attributed by species attributes in the model.

expand(seeds, max_itr=None, max_stoich=None) → Model

Expand a rule-based model into a network model.

Parameters:

seeds : list

A list of Species which gives seeds.

max_itr : Integer

A maximum number of iterations to generate new products.

max_stoich : Integer

A maximum stoichiometry of UnitSpecies in a Species.

Returns:

Model:

A network model.

has_reaction_rule(rr) → bool

Return if the given reaction rule is existing or not.

has_species_attribute(sp) → bool

Return if the given species can be attributed or not.

list_species()

Return a list of species, contained in reaction rules in the model.

num_reaction_rules()

Return a number of reaction rules contained in the model.

query_reaction_rules(sp1, sp2=None) → [ReactionRule]

Query and return a list of reaction rules, which have the given species as their reactants.

Parameters:

sp1 : Species

The first reactant

sp2 : Species

The second reactant. This is for querying second order reaction rules.

Returns:

list:

A list of ``ReactionRule``s.

reaction_rules()

Return a list of reaction rules contained in the model.

remove_reaction_rule(rr)

Remove a reaction rule.

remove_species_attribute(sp)

Remove the species attribute.

species_attributes()

Return a list of species attributes contained in the model.

class ecell4.core.NetfreeModel

A netfree model class.

NetfreeModel()

Methods

add_reaction_rule(rr) Add a new reaction rule.
add_reaction_rules(rrs) Add a list of new reaction rules.
add_species_attribute(sp) Add a species attribute to the bottom.
add_species_attributes(attrs) Extend a list of species attributes to the bottom.
apply_species_attributes((sp) -> Species) Return a species with attributes.
effective() Return if this model uses effective or intrinsic kinetic rates.
expand((seeds[, max_itr, max_stoich]) Expand a rule-based model into a network model.
has_reaction_rule((rr) -> bool) Return if the given reaction rule is existing or not.
has_species_attribute((sp) -> bool) Return if the given species can be attributed or not.
list_species Return a list of species, contained in reaction rules in the model.
num_reaction_rules Return a number of reaction rules contained in the model.
query_reaction_rules((sp1[, sp2]) Query and return a list of reaction rules, which have the given species as their reactants.
reaction_rules Return a list of reaction rules contained in the model.
remove_reaction_rule(rr) Remove a reaction rule.
remove_species_attribute(sp) Remove the species attribute.
set_effective(effective) Set if this model uses effective or intrinsic kinetic rates.
species_attributes Return a list of species attributes contained in the model.
add_reaction_rule(rr)

Add a new reaction rule.

Parameters:

rr : ReactionRule

A new reaction rule.

add_reaction_rules(rrs)

Add a list of new reaction rules.

Parameters:

rrs : list

A list of new ``ReactionRule``s.

add_species_attribute(sp)

Add a species attribute to the bottom.

Parameters:

sp : Species

A new species with attributes.

add_species_attributes(attrs)

Extend a list of species attributes to the bottom.

Parameters:

attrs : list

A list of new Species with attributes.

apply_species_attributes(sp) → Species

Return a species with attributes.

Parameters:

sp : Species

An original species.

Returns:

Species:

A new species attributed by species attributes in the model.

effective()

Return if this model uses effective or intrinsic kinetic rates.

expand(seeds, max_itr=None, max_stoich=None) → Model

Expand a rule-based model into a network model.

Parameters:

seeds : list

A list of Species which gives seeds.

max_itr : Integer

A maximum number of iterations to generate new products.

max_stoich : dict

A maximum stoichiometry of each UnitSpecies in a Species. Given as a set of pairs of Species and the stoichiometry.

Returns:

Model:

A network model.

has_reaction_rule(rr) → bool

Return if the given reaction rule is existing or not.

has_species_attribute(sp) → bool

Return if the given species can be attributed or not.

list_species()

Return a list of species, contained in reaction rules in the model.

num_reaction_rules()

Return a number of reaction rules contained in the model.

query_reaction_rules(sp1, sp2=None) → [ReactionRule]

Query and return a list of reaction rules, which have the given species as their reactants.

Parameters:

sp1 : Species

The first reactant

sp2 : Species

The second reactant. This is for querying second order reaction rules.

Returns:

list:

A list of ``ReactionRule``s.

reaction_rules()

Return a list of reaction rules contained in the model.

remove_reaction_rule(rr)

Remove a reaction rule.

remove_species_attribute(sp)

Remove the species attribute.

set_effective(effective)

Set if this model uses effective or intrinsic kinetic rates.

Parameters:

effective : bool

Whether this model is based on the effective reaction rates or not. If True, this model automatically halve the rate of homodimerization reactions.

species_attributes()

Return a list of species attributes contained in the model.

class ecell4.core.NetworkModel

A network model class.

NetworkModel()

Methods

add_reaction_rule(rr) Add a new reaction rule.
add_reaction_rules(rrs) Add a list of new reaction rules.
add_species_attribute(sp) Add a species attribute to the bottom.
add_species_attributes(attrs) Extend a list of species attributes to the bottom.
apply_species_attributes((sp) -> Species) Return a species with attributes.
expand((seeds[, max_itr, max_stoich]) Expand a rule-based model into a network model.
has_reaction_rule((rr) -> bool) Return if the given reaction rule is existing or not.
has_species_attribute((sp) -> bool) Return if the given species can be attributed or not.
list_species Return a list of species, contained in reaction rules in the model.
num_reaction_rules Return a number of reaction rules contained in the model.
query_reaction_rules((sp1[, sp2]) Query and return a list of reaction rules, which have the given species as their reactants.
reaction_rules Return a list of reaction rules contained in the model.
remove_reaction_rule(rr) Remove a reaction rule.
remove_species_attribute(sp) Remove the species attribute.
species_attributes Return a list of species attributes contained in the model.
add_reaction_rule(rr)

Add a new reaction rule.

Parameters:

rr : ReactionRule

A new reaction rule.

add_reaction_rules(rrs)

Add a list of new reaction rules.

Parameters:

rrs : list

A list of new ``ReactionRule``s.

add_species_attribute(sp)

Add a species attribute to the bottom.

Parameters:

sp : Species

A new species with attributes.

add_species_attributes(attrs)

Extend a list of species attributes to the bottom.

Parameters:

attrs : list

A list of new Species with attributes.

apply_species_attributes(sp) → Species

Return a species with attributes.

Parameters:

sp : Species

An original species.

Returns:

Species:

A new species attributed by species attributes in the model.

expand(seeds, max_itr=None, max_stoich=None) → Model

Expand a rule-based model into a network model.

Parameters:

seeds : list

A list of Species which gives seeds.

max_itr : Integer

A maximum number of iterations to generate new products.

max_stoich : Integer

A maximum stoichiometry of UnitSpecies in a Species.

Returns:

Model:

A network model.

has_reaction_rule(rr) → bool

Return if the given reaction rule is existing or not.

has_species_attribute(sp) → bool

Return if the given species can be attributed or not.

list_species()

Return a list of species, contained in reaction rules in the model.

num_reaction_rules()

Return a number of reaction rules contained in the model.

query_reaction_rules(sp1, sp2=None) → [ReactionRule]

Query and return a list of reaction rules, which have the given species as their reactants.

Parameters:

sp1 : Species

The first reactant

sp2 : Species

The second reactant. This is for querying second order reaction rules.

Returns:

list:

A list of ``ReactionRule``s.

reaction_rules()

Return a list of reaction rules contained in the model.

remove_reaction_rule(rr)

Remove a reaction rule.

remove_species_attribute(sp)

Remove the species attribute.

species_attributes()

Return a list of species attributes contained in the model.

class ecell4.core.NumberObserver

An Observer``class to log the number of molecules. This ``Observer logs at the current time first, and then keeps logging every after simulation steps. Warning: This doesn’t work with ODESimulator.

NumberObserver(species)

Methods

as_base Clone self as a base class.
data Return a list of the numbers of molecules you specified.
next_time Return the next time for logging.
num_steps Return the number of steps.
reset Reset the internal state.
save Save data to an output with the given filename.
targets Return a list of Species, which this Observer observes
as_base()

Clone self as a base class. This function is for developers.

data()

Return a list of the numbers of molecules you specified.

Returns:

list:

A list of lists of the number of molecules. The size of a return value is equal to num_steps. Each element of a return value is a list consisting of time and the number of molecules specified at the construction.

next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

reset()

Reset the internal state.

save()

Save data to an output with the given filename.

targets()

Return a list of Species, which this Observer observes

Returns:

list:

A list of Species. This is generated from arguments you gave at the construction.

class ecell4.core.Observer

A wrapper for a base class of Observers.

Warning: This is mainly for developers. Do not use this for your simulation.

Methods

next_time Return the next time for logging.
reset Reset the internal state.
next_time()

Return the next time for logging.

reset()

Reset the internal state.

class ecell4.core.Particle

A class representing a particle

Particle(Species sp, Real3 pos, Real radius, Real D)

Methods

D Return the diffusion coefficient.
position(() -> Real3) Return the position.
radius Return the radius.
species(() -> Species) Return the species.
D()

Return the diffusion coefficient.

position() → Real3

Return the position.

radius()

Return the radius.

species() → Species

Return the species.

class ecell4.core.ParticleID

A class representing an ID of each particle

ParticleID(value)

Methods

lot Return the first value.
serial Return the second value.
lot()

Return the first value.

serial()

Return the second value.

class ecell4.core.PlanarSurface

A class representing a planar surface, which is available to define structures.

PlanarSurface(origin, e0, e1)

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
is_inside Return if the given point is inside or not.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

class ecell4.core.ReactionRule

A class representing a reaction rule between Species.

ReactionRule(reactants=None, products=None, k=None)

Methods

add_product(sp) Append a product to the end.
add_reactant(sp) Append a reactant to the end.
as_string(() -> str) Return an unicode string describing this object.
count((reactants) -> Integer) Count the number of matches for reactants.
generate((reactants) -> [ReactionRule]) Generate ``ReactionRule``s from given reactants.
k Return the kinetic rate constant as a float value.
policy(() -> int) Return a policy for the rule-based modeling.
products List all products.
reactants List all reactants.
set_k(k) Set a kinetic rate constant.
set_policy(policy) Set a policy for the rule-based modeling.
add_product(sp)

Append a product to the end.

Parameters:

sp : Species

A new product.

add_reactant(sp)

Append a reactant to the end.

Parameters:

sp : Species

A new reactant.

as_string() → str

Return an unicode string describing this object.

Returns:

str:

An unicode string describing this object.

Examples

The string consists of a list of reactants, a list of products, and a kinetic rate constant.

>>> rr = ReactionRule([Species("A"), Species("B")], [Species("C")], 1.0)
>>> rr.as_string()
u'A+B>C|1'
count(reactants) → Integer

Count the number of matches for reactants.

Parameters:

reactants : list

A list of Species. The order of reactants is respected.

Returns:

Integer:

The number of matches.

generate(reactants) → [ReactionRule]

Generate ``ReactionRule``s from given reactants.

Parameters:

reactants : list

A list of Species. The order of reactants is respected.

Returns:

list:

A list of ReactionRule``s. The reactants of each ``ReactionRule are equal to the given reactants. If the ReactionRule does not match the reactants, return an empty list.

Examples

>>> rr = ReactionRule([Species("_(b=x)")], [Species("_(b=y)")], 1.0)
>>> reactants = [Species("A(a^1,b=x).B(a^1,b=x)")]
>>> [r.as_string() for r in rr.generate(reactants)]
[u'A(a^1,b=x).B(a^1,b=x)>A(a^1,b=y).B(a^1,b=x)|1',
 u'A(a^1,b=x).B(a^1,b=x)>A(a^1,b=x).B(a^1,b=y)|1']
k()

Return the kinetic rate constant as a float value.

policy() → int

Return a policy for the rule-based modeling.

products()

List all products.

Returns:

list:

A list of product Species.

reactants()

List all reactants.

Returns:

list:

A list of reactant Species.

set_k(k)

Set a kinetic rate constant.

Parameters:

k : float

A kinetic rate constant.

set_policy(policy)

Set a policy for the rule-based modeling.

Examples

>>> rr = ReactionRule()
>>> rr.set_policy(ReactionRule.STRICT | ReactionRule.DESTROY)
class ecell4.core.Real3

A class representing a three-dimensional vector or position.

Real3(Real p1, Real p2, Real p3)

class ecell4.core.Rod

A class representing a Rod shape, which is available to define structures. The cylinder is aligned to x-axis.

Rod(length, radius, origin=Real3(0, 0, 0))

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
distance Return a minimum distance from the given point to the surface.
is_inside Return if the given point is inside or not.
length Return a length of a cylinder part.
origin Return a center position of mass
radius Return a radius of a cylinder.
shift Move the center toward the given displacement
surface Create and return a surface shape.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

distance()

Return a minimum distance from the given point to the surface.

Parameters:

pos : Real3

A position.

Returns:

distance : float

A minimum distance from the given point. Negative if the given point is inside.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

length()

Return a length of a cylinder part.

origin()

Return a center position of mass

radius()

Return a radius of a cylinder.

shift()

Move the center toward the given displacement

Parameters:

vec : Real3

A displacement.

surface()

Create and return a surface shape.

Returns:

shape : RodSurface

The surface shape.

class ecell4.core.RodSurface

A class representing a hollow rod surface shape, which is available to define structures. The cylinder is aligned to x-axis.

RodSurface(length, radius, origin=Real3(0, 0, 0))

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
distance Return a minimum distance from the given point to the surface.
inside Create and return a volume shape.
is_inside Return if the given point is inside or not.
length Return a length of a cylinder part.
origin Return a center position of mass
radius Return a radius of a cylinder.
shift Move the center toward the given displacement
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

distance()

Return a minimum distance from the given point to the surface.

Parameters:

pos : Real3

A position.

Returns:

distance : float

A minimum distance from the given point. Negative if the given point is inside.

inside()

Create and return a volume shape.

Returns:

shape : Rod

The volume shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

length()

Return a length of a cylinder part.

origin()

Return a center position of mass

radius()

Return a radius of a cylinder.

shift()

Move the center toward the given displacement

Parameters:

vec : Real3

A displacement.

class ecell4.core.Shape

A wrapper for a base class of Shapes.

Warning: This is mainly for developers. Do not use this for your simulation.

Methods

dimension Return a dimension of this shape.
is_inside Return if the given point is inside or not.
dimension()

Return a dimension of this shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

class ecell4.core.Space

An abstract base class of all worlds. This is for developers.

Space()

class ecell4.core.Species

A class representing a type of molecules with attributes.

Species(serial=None, radius=None, D=None, location=None)

Methods

D((string) -> Species) set attribute ‘D’, and return self.
add_unit(usp) Append an UnitSpecies to the end.
count((sp) -> Integer) Count the number of matches for a target given as a Species.
get_attribute((name) -> str) Return an attribute as an unicode string.
has_attribute((name) -> bool) Return if the attribute exists or not.
list_attributes(() -> [(str, str)]) List all attributes.
location((string) -> Species) set attribute ‘location’, and return self.
radius((string) -> Species) set attribute ‘radius’, and return self.
remove_attribute(name) Remove an attribute.
serial Return the serial name as an unicode string.
set_attribute(name, value) Set an attribute.
units(() -> [UnitSpecies]) Return a list of all UnitSpecies contained.
D(string) → Species

set attribute ‘D’, and return self.

add_unit(usp)

Append an UnitSpecies to the end.

Parameters:

usp : UnitSpecies

An UnitSpecies to be added.

count(sp) → Integer

Count the number of matches for a target given as a Species.

Parameters:

sp : Species

A target to be count.

Returns:

Integer:

The number of matches.

get_attribute(name) → str

Return an attribute as an unicode string. If no corresponding attribute is found, raise an error.

Parameters:

name : str

The name of an attribute.

Returns:

str:

The value of the attribute.

has_attribute(name) → bool

Return if the attribute exists or not.

Parameters:

name : str

The name of an attribute.

Returns:

bool:

True if the attribute exists, False otherwise.

list_attributes() → [(str, str)]

List all attributes.

Returns:

list:

A list of pairs of name and value. name and value are given as unicode strings.

location(string) → Species

set attribute ‘location’, and return self.

radius(string) → Species

set attribute ‘radius’, and return self.

remove_attribute(name)

Remove an attribute. If no corresponding attribute is found, raise an error.

Parameters:

name : str

The name of an attribute to be removed.

serial()

Return the serial name as an unicode string.

set_attribute(name, value)

Set an attribute. If existing already, the attribute will be overwritten.

Parameters:

name : str

The name of an attribute.

value : str

The value of an attribute.

units() → [UnitSpecies]

Return a list of all UnitSpecies contained.

class ecell4.core.Sphere

A class representing a sphere shape, which is available to define structures.

Sphere(center, radius)

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
distance Return a minimum distance from the given point to the surface.
is_inside Return if the given point is inside or not.
surface Create and return a surface shape.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

distance()

Return a minimum distance from the given point to the surface.

Parameters:

pos : Real3

A position.

Returns:

distance : float

A minimum distance from the given point. Negative if the given point is inside.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

surface()

Create and return a surface shape.

Returns:

shape : SphericalSurface

The surface shape.

class ecell4.core.SphericalSurface

A class representing a hollow spherical surface, which is available to define structures.

SphericalSurface(center, radius)

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
distance Return a minimum distance from the given point to the surface.
inside Create and return a volume shape.
is_inside Return if the given point is inside or not.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

distance()

Return a minimum distance from the given point to the surface.

Parameters:

pos : Real3

A position.

Returns:

distance : float

A minimum distance from the given point. Negative if the given point is inside.

inside()

Create and return a volume shape.

Returns:

shape : Sphere

The volume shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

class ecell4.core.Surface

Methods

as_base Clone self as a base class.
dimension Return a dimension of this shape.
is_inside Return if the given point is inside or not.
as_base()

Clone self as a base class. This function is for developers.

dimension()

Return a dimension of this shape.

is_inside()

Return if the given point is inside or not.

Parameters:

pos : Real3

A position.

Returns:

value : float

Zero or negative if the given point is inside.

class ecell4.core.TimeoutObserver

An ``Observer``class to stop simulation at the given calculation time.

TimeoutObserver(interval)

Methods

accumulation Return the accumulation time.
as_base Clone self as a base class.
duration Return the last time to be called.
interval Return the timeout in seconds.
reset Reset the internal state.
accumulation()

Return the accumulation time.

as_base()

Clone self as a base class. This function is for developers.

duration()

Return the last time to be called.

interval()

Return the timeout in seconds.

reset()

Reset the internal state.

class ecell4.core.TimingNumberObserver

An ``Observer``class to log the number of molecules just at the time you assigned.

TimingNumberObserver(t, species)

Methods

as_base Clone self as a base class.
data Return a list of the numbers of molecules you specified.
next_time Return the next time for logging.
num_steps Return the number of steps.
reset Reset the internal state.
save Save data to an output with the given filename.
targets Return a list of Species, which this Observer observes
as_base()

Clone self as a base class. This function is for developers.

data()

Return a list of the numbers of molecules you specified.

Returns:

list:

A list of lists of the number of molecules. The size of a return value is equal to num_steps. Each element of a return value is a list consisting of time and the number of molecules specified at the construction.

next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

reset()

Reset the internal state.

save()

Save data to an output with the given filename.

targets()

Return a list of Species, which this Observer observes

Returns:

list:

A list of Species. This is generated from arguments you gave at the construction.

class ecell4.core.TimingTrajectoryObserver

An Observer class to trace and log trajectories of diffusing particles in a World at the given logging times.

TimingTrajectoryObserver(t, pids, resolve_boundary=None, subdt=None)

Methods

as_base Clone self as a base class.
data Return a list of trajectories for each particles.
next_time Return the next time for logging.
num_steps Return the number of steps.
num_tracers Return the number of tracer molecules.
reset Reset the internal state.
t Return time points at logging as a list.
as_base()

Clone self as a base class. This function is for developers.

data()

Return a list of trajectories for each particles.

Returns:

list:

A list of lists of Real3. An element of a return value is corresponding the trajectory of each particle. Thus, the size of a return value is the same with that of pids you gave at the construction. If a particle corresponding to the given ParticleID is missing, i.e. for a reaction, this Observer just skips to log the position. Therefore, lengths of the trajectories can be diverse.

next_time()

Return the next time for logging.

num_steps()

Return the number of steps.

num_tracers()

Return the number of tracer molecules.

reset()

Reset the internal state.

t()

Return time points at logging as a list.

class ecell4.core.UnitSpecies

A class representing an unit of species.

UnitSpecies(name=None)

See also

Species

Methods

add_site(name, state, bond) Add a new site.
deserialize(serial) Deserialize the given serial, and load it.
name Return a name.
serial Return the serial, which consists of a name and sites.
add_site(name, state, bond)

Add a new site.

Parameters:

name : str

A name of the site

state : str

A state name of the site

bond : str

A bond of the site.

deserialize(serial)

Deserialize the given serial, and load it.

Parameters:

serial : str

A serial

name()

Return a name.

serial()

Return the serial, which consists of a name and sites.

class ecell4.core.Voxel

A class representing a voxel in LatticeSpace.

Voxel(Species sp, Integer coord, Real radius, Real D, loc=None)

Methods

D Return the diffusion coefficient.
coordinate Return the coordinate.
loc(() -> str) Return the location information as a string.
radius Return the radius.
species(() -> Species) Return the species.
D()

Return the diffusion coefficient.

coordinate()

Return the coordinate.

loc() → str

Return the location information as a string.

radius()

Return the radius.

species() → Species

Return the species.

ecell4.core.cbrt(x) → Real

Return a cubic root of the given value.

ecell4.core.count_spmatches(pttrn, sp) → Integer

Count the number of matches for a pattern given as a Species.

Parameters:

pttrn : Species

A pattern.

sp : Species

A target.

Returns:

Integer:

The number of matches.

Notes

Rather use Species.count.

ecell4.core.create_binding_reaction_rule(reactant1, reactant2, product1, k) → ReactionRule

Create a binding ReactionRule.

Parameters:

reactant1 : Species

One of two reactants.

reactant2 : Species

One of two reactants.

product1 : Species

A product.

k : float

A kinetic parameter.

Notes

This is equivalent to ReactionRule([reactant1, reactant2], [product1], k).

ecell4.core.create_degradation_reaction_rule(reactant1, k) → ReactionRule

Create a degradation ReactionRule.

Parameters:

reactant1 : Species

A reactant to be degradated.

k : float

A kinetic parameter.

Notes

This is equivalent to ReactionRule([reactant1], [], k).

ecell4.core.create_synthesis_reaction_rule(product1, k) → ReactionRule

Create a synthesis ReactionRule.

Parameters:

product1 : Species

A product to be synthesized.

k : float

A kinetic parameter.

Notes

This is equivalent to ReactionRule([], [product1], k).

ecell4.core.create_unbinding_reaction_rule(reactant1, product1, product2, k) → ReactionRule

Create an unbinding ReactionRule.

Parameters:

reactant1 : Species

A reactant.

product1 : Species

One of two products.

product2 : Species

One of two products.

k : float

A kinetic parameter.

Notes

This is equivalent to ReactionRule([reactant1], [product1, product2], k).

ecell4.core.create_unimolecular_reaction_rule(reactant1, product1, k) → ReactionRule

Create an unimolecular ReactionRule.

Parameters:

reactant1 : Species

A reactant to be modified.

product1 : Species

A product.

k : float

A kinetic parameter.

Notes

This is equivalent to ReactionRule([reactant1], [product1], k).

ecell4.core.create_x_plane()

Return PlanarSurface(Real3(x, 0, 0), Real3(0, 1, 0), Real3(0, 0, 1)).

ecell4.core.create_y_plane()

Return PlanarSurface(Real3(0, y, 0), Real3(1, 0, 0), Real3(0, 0, 1)).

ecell4.core.create_z_plane()

Return PlanarSurface(Real3(0, 0, z), Real3(1, 0, 0), Real3(0, 1, 0)).

ecell4.core.cross_product(p1, p2) → Real3

Return a cross product between two vectors

ecell4.core.dot_product(p1, p2) → Real or Integer

Return a dot product between two vectors

ecell4.core.format_species(sp) → Species

Return a species uniquely reformatted.

ecell4.core.integer3_abs(p1) → Integer3

Return an absolute vector of the given vector.

Parameters:

p1 : Integer3

A vector.

Returns:

Integer3:

The absolute vector, which consists of absolute value of the given vector.

See also

length

Notes

This is NOT for taking the norm of a vector.

ecell4.core.integer3_add(p1, p2) → Integer3

Add two ``Integer3``s, and returns the sum.

Parameters:

p1 : Integer3

The first vector.

p2 : Integer3

The second vector.

Returns:

Integer3:

The sum of two vectors, p1 + p2.

ecell4.core.integer3_dot_product(p1, p2) → Integer

Return a dot product between two vectors

ecell4.core.integer3_length(p1) → Real

Return a Euclidean norm of the given vector. This is almost equivalent to call sqrt(length_sq(p1))

ecell4.core.integer3_length_sq(p1) → Integer

Return a square of a Euclidean norm of the given vector.

ecell4.core.integer3_multiply(p1, p2) → Integer3

Multiply p1 by p2.

Parameters:

p1 : Integer3

A vector.

p2 : Integer

A factor.

Returns:

Integer3:

The multipled vector, p1 * p2.

ecell4.core.integer3_subtract(p1, p2) → Integer3

Subtract p2 from p1.

Parameters:

p1 : Integer3

The left-hand-side vector.

p2 : Integer3

The right-hand-side vector.

Returns:

Integer3:

Its difference, p1 - p2.

ecell4.core.length(p1) → Real

Return a Euclidean norm of the given vector. This is almost equivalent to call sqrt(length_sq(p1))

ecell4.core.length_sq(p1) → Real or Integer

Return a square of a Euclidean norm of the given vector.

ecell4.core.load_version_information()

Return a version information of HDF5 as a string.

ecell4.core.ones()

Return Real3(1.0, 1.0, 1.0).

ecell4.core.real3_abs(p1) → Real3

Return an absolute vector of the given vector.

Parameters:

p1 : Real3

A vector.

Returns:

Real3:

The absolute vector, which consists of absolute value of the given vector.

See also

length

Notes

This is NOT for taking the norm of a vector.

ecell4.core.real3_add(p1, p2) → Real3

Add two ``Real3``s, and returns the sum.

Parameters:

p1 : Real3

The first vector.

p2 : Real3

The second vector.

Returns:

Real3:

The sum of two vectors, p1 + p2.

ecell4.core.real3_divide(p1, p2) → Real3

Divide p1 by p2.

Parameters:

p1 : Real3

The numerator.

p2 : Real

The denominator.

Returns:

Real3:

The divided vector, p1 / p2.

ecell4.core.real3_dot_product(p1, p2) → Real

Return a dot product between two vectors

ecell4.core.real3_length(p1) → Real

Return a Euclidean norm of the given vector. This is almost equivalent to call sqrt(length_sq(p1))

ecell4.core.real3_length_sq(p1) → Real

Return a square of a Euclidean norm of the given vector.

ecell4.core.real3_multiply(p1, p2) → Real3

Multiply p1 by p2.

Parameters:

p1 : Real3

A vector.

p2 : Real

A factor.

Returns:

Real3:

The multipled vector, p1 * p2.

ecell4.core.real3_subtract(p1, p2) → Real3

Subtract p2 from p1.

Parameters:

p1 : Real3

The left-hand-side vector.

p2 : Real3

The right-hand-side vector.

Returns:

Real3:

Its difference, p1 - p2.

ecell4.core.spmatch(pttrn, sp) → bool

Return if a pattern matches the target Species or not.

Parameters:

pttrn : Species

A pattern.

sp : Species

A target.

Returns:

bool:

True if pttrn matches sp at least one time, False otherwise.

ecell4.core.unique_serial(sp) → str

Return a serial of a species uniquely reformatted. This is equivalent to call format_species(sp).serial()

ecell4.core.unitx()

Return Real3(1.0, 0.0, 0.0).

ecell4.core.unity()

Return Real3(0.0, 1.0, 0.0).

ecell4.core.unitz()

Return Real3(0.0, 0.0, 1.0).