14.5. steps.API_2.sim

The sim module contains classes related to both serial and parallel simulations.

14.5.1. Simulation paths

Values can be set and retrieved from the simulation by using SimPaths from the Simulation object to the desired value. The following tool allows users to know which paths can be set or accessed:

Get / Set
Solver
Location / Object
Object / Property
Object / Property
Property

Examples:

14.5.2. Detailed documentation

  • Simulation

  • Simulation utilities

  • Parallel simulations

class Simulation(solverName, mdl, geom, rng=None, *args, name=None, check=True, **kwargs)[source]

Bases: NamedObject

The main simulation class

A simulation is defined from a model, a geometry, a solver and a random number generator. Once a Simulation object is created, users can access and set simulated values through the simulation path syntax (see SimPath). newRun() should be called before the simulation can be run and the data to be saved should be declared with steps.API_2.saving.ResultSelector objects and added to the simulation with the toSave() method. The simulation is advanced by calling either step() or run().

Parameters:
SERIAL_SOLVERS = ['Wmdirect', 'Wmrssa', 'Wmrk4', 'Tetexact', 'TetODE']

Available serial solvers

PARALLEL_SOLVERS = ['TetOpSplit', 'TetVesicle', 'DistTetOpSplit']

Available parallel solvers

DISTRIBUTED_SOLVERS = ['DistTetOpSplit']

Available distributed solvers

property model

The model associated to the simulation

Type:

steps.API_2.model.Model, read-only

property geom

The geometry associated to the simulation

Type:

Union[steps.API_2.geom.Geometry, steps.API_2.geom.TetMesh, steps.API_2.geom.DistMesh] read-only

property rng

The random number generator associated to the simulation

Type:

steps.API_2.rng.RNG, read-only

property solver

The solver associated to the simulation

Type:

steps.API_1.solver._Base_Solver, read-only

See steps.API_1.solver for detailed API.

Warning

Direct calls to the solver should only be made if absolutely necessary. They will bypass data saving mechanisms implemented in Simulation.

step()[source]

Advance the simulation for one ‘step’.

In stochastic solvers this is one ‘realization’ of the Gillespie SSA (one reaction ‘event’). In numerical solvers (currently Wmrk4 and TetODE) this is one time-step, with the stepsize defined with the setDT() method.

Warning

If the step happens to jump over a ResultSelector saving timepoint, the data will be saved after the step and the associated timepoint will be modified to match the time after the step. If several saving timepoints are jumped over, the save will be performed only once. The same remark applies to automatic checkpointing (see autoCheckpoint()).

run(t)[source]

Run the simulation until a given time

Automatically save the data that has been specified through ResultSelectors and added to the simulation with the toSave() method. Automatically checkpoint if the autoCheckpoint() method has been called.

Parameters:

t (float) – Run the simulation until this time (in seconds)

newRun(reset=True)[source]

Reset the solver and signal the start of a new run

This method must be called before any call to run() or step(). Since it usually resets the solver, the initial state must be specified after the call to newRun. Result selectors rely on this call to separate the data from different runs.

Parameters:

reset (bool) – If True (default value) resets the state of the solver.

Note

The 'tetODE' solver cannot be reset.

toSave(*selectors, dt=None, timePoints=None)[source]

Add result selectors to the simulation

Parameters:

  • selectors (steps.API_2.saving.ResultSelector) – One or several result selectors that should be saved during the simlulation.

  • dt (float) – If this keyword parameter is specified, the result selectors will be saved every dt seconds.

  • timePoints (List[float]) – A list of timepoints (in seconds) at which the result selectors should be saved.

toDB(dbh, uid=None, **kwargs)[source]

Redirect all the added results selectors to a database

Parameters:

  • dbh (steps.API_2.saving.DatabaseHandler) – The database to which the result selectors should be saved (see e.g. steps.API_2.saving.SQLiteDBHandler).

  • uid (str) – A unique identifier under which all subsequent runs should be saved. It should not contain any slashes. If it is not provided, a default one will be used.

  • kwargs (int, float, str or bytes) – Any additional parameters that should be saved to the database along with the unique identifier. Values are restricted to the documented types.

Returns:

The database run group object to which the subsequent runs will be saved

Return type:

Union[None, steps.API_2.saving.DatabaseGroup]

Usage:

sim.toSave(...) # Add the result selectors

with HDF5Handler(dbPath) as hdf:
    group = sim.toDB(hdf, 'MySimulation', val1=1, val2=2)
    sim.newRun()
    ... # Set initial state
    sim.run(10)

When using MPI, the run group object is only returned on rank 0, the other ranks return None.

saveTetWeights(prefix='')[source]

Records tetrahedron computational weights to a file, for usage with steps.API_2.geom.TetWeightPartition().

Weights for a tetrahedron are calculated according to the number of reactions and diffusions that have occured in that tetrahedron throughout the simulation. Therefore, it is only necessary to collect weights a single time at the end of the simulation.

Logs will be saved to a file called '{prefix}weights.log'.

Parameters:

prefix (str) – An optional prefix to the log filename

autoCheckpoint(period, prefix='', onlyLast=False)[source]

Activates automatic checkpointing

After this method has been called, all subsequent calls to step() or run() will save a checkpoint every period seconds. This method can be called during simulation to change the checkpoint period or prefix. To turn off automatic checkpointing, use sim.autoCheckpoint(None).

Parameters:

  • period (float or None) – The period at which checkpointing should be performed, in seconds. None to disable automatic checkpointing.

  • prefix (str) – An optional prefix to the checkpoint filename. Checkpoint file names follow the pattern '{prefix}_{runId}_{time}_{solver}_cp'.

  • onlyLast (bool) – If True, remove previous checkpoints when a new chekpoint is being saved.

addVesiclePath(name, bind_to_start=True)[source]

Add a 3D vesicle path to the simulation

Paths can be used to transport vesicles.

This method can only be used with the ‘TetVesicle’ solver. It adds an empty 3D path to the simulation, to which nodes and edges can be added. This method returns the path that was added to the simulation, further modifications to the paths are done through the VesiclePathReference class.

Parameters:

  • name (str) – The name given to the path to identify it

  • bind_to_start – Whether vesicles should automatically bind to the path if they overlap the starting point of the path.

Returns:

A reference to the empty path that was added to the simulation

Return type:

VesiclePathReference

addVesicleDiffusionGroup(ves, comps)[source]

Add a diffusion group for vesicles

This method adds a ‘diffusion group’ for vesicles of type ves. Vesicles will diffuse freely amongst compartments in comps (if they border each other).

Parameters:
__getattr__(name)[source]

Redirect attribute access to a SimPath

See SimPath.__getattr__()

ALL(*cls)[source]

Redirect ALL(…) to a SimPath

See SimPath.ALL()

property EfieldDT

The stepsize for membrane potential solver

This is the time for each voltage calculation step. The SSA will run until passing this stepsize, so in fact each membrane potential time step will vary slightly around the dt so as to be aligned with the SSA.

Default value is 1us.

Type:

float

property Temp

The simulation temperature in Kelvins

Currently, this will only influence the GHK flux rate, so will only influence simulations including membrane potential calculation.

Type:

float

property Time

The current simulation time in seconds

Type:

float, read-only

property A0

The total propensity of the current simulation state

The total propensity multiplied by an infinitesimally small time dt gives the probability that a reaction will occur in that dt. For Tetexact this includes the propensity from the extension of the SSA for diffusive flux between tetrahedral elements in the mesh.

Type:

float, read-only

property NSteps

The number of ‘realizations’ of the SSA

It corresponds to the total number of reaction (and diffusion) events in stochastic solvers.

Type:

float, read-only

setDT(dt)[source]

Set the stepsize for numerical solvers

Superceded by setRk4DT, but Included for backwards compatability.

Parameters:

dt (Union[float, steps.API_2.nutils.Parameter]) – The step size in seconds

setRk4DT(dt)[source]

Set the stepsize for numerical solvers

Must be called before running a simulation with these solvers (currently Wmrk4) since there is no default stepsize. The deterministic solver Wmrk4 implements a fixed stepsize (i.e. not adaptive), although the stepsize can be altered at any point during the simulation with this method.

Parameters:

dt (Union[float, steps.API_2.nutils.Parameter]) – The step size in seconds

setVesicleDT(dt)[source]

Set the default vesicle dt

Note: the actual vesicle dt used in the simulation can be lower than this number depending on simulation conditions).

Parameters:

dt (Union[float, steps.API_2.nutils.Parameter]) – The vesicle dt in seconds

setPetscOptions(options)[source]

set PETSc options

With this call we can pass all the petsc options in one string. At the moment only the options for the Krylov solver (ksp) and the preconditioner (pc) used in the efield calculations are going to have an effect. The full list of options:

Syntax: setPetscOptions(“-option1 val1 -option2 val2 -option3 val3”)

Parameters:

options (str) – a string with the options

setEfieldTolerances(atol=1e-50, rtol=1e-05)[source]

Set the absolute and relative tolerances for the Efield solver

See https://petsc.org/release/docs/manual/ksp/#convergence-tests

Parameters:

  • atol (float) – Absolute tolerance

  • rtol – Relative tolerance

setTolerances(atol, rtol)[source]

Set the absolute tolerance and the relative tolerance for CVODE

Only works for ODE solvers.

Parameters:

  • atol (float) – Absolute tolerance for CVODE

  • rtol (float) – Relative tolerance for CVODE

getDiffusionTolerance()[source]

Get the tolerance parameter for diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme.

Returns:

The tolerance parameter (desired maximum relative change in species populations during a diffusion event, a lower value means higher accuracy and slower simulation)

Return type:

float

setDiffusionTolerance(tolerance)[source]

Set the tolerance parameter for diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme. It defaults to 0.1.

Parameters:

tolerance (float) – Tolerance parameter (desired maximum relative change in species populations during a diffusion event, a lower value means higher accuracy and slower simulation)

getDiffusionNormalApproximationThreshold()[source]

Get the normal approximation threshold for skellam distribution sampling during diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme.

Returns:

The threshold (average number of species movement from one tetrahedron to another during a diffusion period) above which a normal approximation is used to sample values that are Skellam-distributed

Return type:

float

setDiffusionNormalApproximationThreshold(threshold)[source]

Set the normal approximation threshold for skellam distribution sampling during diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme. It defaults to 1.0.

Parameters:

threshold (float) – The threshold (average number of species movement from one tetrahedron to another during a diffusion period) above which a normal approximation is used to sample values that are Skellam-distributed

getDiffusionCrankNicolsonThreshold()[source]

Get the Crank-Nicolson threshold for diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme.

Returns:

The threshold (fraction of the default diffusion dt) above which the Crank-Nicolson scheme is used to compute net diffusive fluxes

Return type:

float

setDiffusionCrankNicolsonThreshold(threshold)[source]

Set the Crank-Nicolson threshold for diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme. It defaults to 2.0.

Parameters:

threshold (float) – The threshold (fraction of the default diffusion dt) above which the Crank-Nicolson scheme is used to compute net diffusive fluxes

getDiffusionLeapThreshold()[source]

Get the minimum number of species for leaping with TAU_LEAPING_DT diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme.

Returns:

The minimum number of species (in any tetrahedron) required for diffusion leaping to happen

Return type:

int

setDiffusionLeapThreshold(leap_threshold)[source]

Set the minimum number of species for leaping with TAU_LEAPING_DT diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme. It defaults to 10.

Parameters:

leap_threshold (int) – The minimum number of species (in any tetrahedron) required for diffusion leaping to happen

getDiffusionMaxDtSkips()[source]

Get the maximum number of skips for TAU_LEAPING_DT diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme.

Returns:

The maximum number of time that default diffusion dt should be used when the tau leaping dt was found to be lower than the default dt

Return type:

int

setDiffusionMaxDtSkips(max_skips)[source]

Set the maximum number of skips for TAU_LEAPING_DT diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme. It defaults to 5.

Parameters:

max_skips (int) – The maximum number of time that default diffusion dt should be used when the tau leaping dt was found to be lower than the default dt

getDiffusionMinDtFactor()[source]

Get the factor for computing the minimum diffusion dt for TAU_LEAPING_DT diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme.

Returns:

The factor that determines how the minimum diffusion dt is computed. 0 means that the lowest diffusion propensity out of all tetrahedron is used to compute the diffusion dt. 1 means that the highest value is used, and 0.5 means that the average value is used. Values between 0 and 0.5 are linearly interpolated, values between 0.5 and 1 are also linearly interpolated.

Return type:

float

setDiffusionMinDtFactor(factor)[source]

Set the factor for computing the minimum diffusion dt for TAU_LEAPING_DT diffusion

This is only available with DistTetOpSplit simulations that use the TAU_LEAPING_DT diffusion scheme. It defaults to 1 (same behavior as for the CONSTANT_DT diffusion operator).

Parameters:

factor (float) – The factor that determines how the minimum diffusion dt is computed. 0 means that the lowest diffusion propensity out of all tetrahedron is used to compute the diffusion dt. 1 means that the highest value is used, and 0.5 means that the average value is used. Values between 0 and 0.5 are linearly interpolated, values between 0.5 and 1 are also linearly interpolated.

getReactionSSAThreshold()[source]

Get the minimum leap size for using R-leaping

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator.

Returns:

The minimum leap size for an R-leaping step. Below that number, a series of SSA steps are applied instead.

Return type:

int

setReactionSSAThreshold(threshold)[source]

Set the minimum leap size for using R-leaping

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator. It defaults to 50.

Parameters:

threshold (int) – The minimum leap size for an R-leaping step. Below that number, a series of SSA steps are applied instead.

getReactionSSASteps()[source]

Get the number of standard SSA steps to run in a row when the reaction leaps are below threshold

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator.

Returns:

The number of SSA steps to run in a row when the reaction leaps are below threshold

Return type:

int

setReactionSSASteps(steps)[source]

Set the number of standard SSA steps to run in a row when the reaction leaps are below threshold

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator. It defaults to 100.

Parameters:

steps (int) – The number of SSA steps to run in a row when the reaction leaps are below threshold

getReactionLComputePeriod()[source]

Get the period at which L is computed

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator.

Returns:

The the period at which L is computed

Return type:

int

setReactionLComputePeriod(period)[source]

Set the period at which L is computed

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator. It defaults to 10.

When set to 1, it means that L is computed after every leap.

Parameters:

period (int) – The period at which L is computed

getReactionTolerance()[source]

Get the tolerance parameter for the reaction operator

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator.

Returns:

The tolerance parameter (desired maximum relative change in species populations during a reaction leaping step, a lower value means higher accuracy and slower simulation)

Return type:

float

setReactionTolerance(tolerance)[source]

Set the tolerance parameter for the reaction operator

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator. It defaults to 0.05.

Parameters:

tolerance (float) – Tolerance parameter (desired maximum relative change in species populations during a reaction leaping step, a lower value means higher accuracy and slower simulation)

getReactionTheta()[source]

Get the theta parameter for the reaction operator

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator.

Returns:

The theta parameter (controls the appearance of negative species, a lower value means less negative species but slower simulation)

Return type:

float

setReactionTheta(theta)[source]

Set the theta parameter for the reaction operator

This is only available with DistTetOpSplit simulations that use the RLEAPING reaction operator. It defaults to 0.1.

Parameters:

theta (float) – The theta parameter (controls the appearance of negative species, a lower value means less negative species but slower simulation)

checkpoint(fname)[source]

Checkpoint the current simulation state to a file

See autoCheckpoint() for setting up automatic checkpointing.

Parameters:

fname (str) – The file name / path

restore(fname)[source]

Restore the simulation state to a previously saved checkpoint

Parameters:

fname (str) – The file name / path

saveMembOpt(fname)[source]

Saves the vertex optimization in the Efield structure

Parameters:

fname (str) – The file name / path

dumpDepGraphToFile(path)[source]

Dumps the kproc dependency graph in a file specified by path

Parameters:

fname – The file name / path

class SBMLSimulation(solverName, filepath, rng, maxDt, *args, timeunits_def=1.0, volunits_def=0.001, subsunits_def=1.0, volume_def=False, area_def=False, strict_mode=False, solverDt=None, **kwargs)[source]

Bases: Simulation

Simulation loaded from an SBML model

Parameters:

Optional SBML parameters:

Parameters:

  • timeunits_def (float) – Default time unit in relation to seconds (see below)

  • volunits_def (float) – Default volume unit in relation to cubic meters (see below)

  • subsunits_def (float) – Default substance unit in relation to moles (see below)

  • volume_def (float) – Default volume (see below)

  • area_def (float) – Default area (see below)

  • strict_mode (bool) – False mean that all reactions will be allowed, True means that only fundamental reactions that can be represented in the SSA without modification will be allowed, the import failing if any other types of reactions are present. The vast majority of SBML models include some non-fundamental reactions so setting this to True will mean that most SBML imports will fail.

  • solverDt (float) – If using a numerical solver, the integration time step in seconds. If not specified, the default value will be set to one tenth of the maxDt value.

The ‘units’ arguments are a means to set the default model units and unit itself shoud relate to s.i units. For example: to set default model units to ms, timeunits_def=1.0e-3. To set default model substance units to micromoles, subsunits_def=1.0e-6.

Note

These default units will only be used when units are not explicitly declared in the SBML file.

The volume_def and area_def arguments are a way to set volume of compartments or area of patches with size 1.0 and no units, which are very common in SBML files. This may allow for a model to be run stochastically without modifying the file. Values should be given in s.i. units, based on metres. For example: to set default volume to 100 femtolitre: volume_def=100*1.0e-15*1.0e-3

newRun()[source]

Reload completely the SBML model and update the ResultSelectors

See Simulation.newRun() for more details.

run(t)[source]

Run to time t in increments of at most maxDt

See Simulation.run() for more details.

class SimPath(_sim)[source]

Bases:

Describes the access to data from the solver as a path

The root of the path is a simulation and the parts of the path are separated by dots: sim.cyt.Ca.Count returns the count of species 'Ca' in compartment 'cyt' for simulation 'sim'.

The path usually follows the convention root.location.object.attribute. Objects along the path can be made more specific with the square bracket syntax: sim.ERmemb.sReac1["fwd"].K returns the reaction constant associated to the forward part of reaction 'sReac1' on patch 'ERmemb'.

This syntax allows to either get or set the data: sim.cyt.Ca.Count = 5000 sets the number of 'Ca' in compartment 'cyt' to 5000.

Data can also be accessed in a grouped way: sim.ALL().Ca.Count returns a list of the count of species 'Ca' in all locations. Special methods like ALL(), LIST() and MATCH() allow to select path parts based on their type or names. Special methods like TET(), TRI(), and VERT() allow the specification of single geometrical elements as location (e.g. sim.TET(tet1).Ca.Count) while the plural version (TETS(), …) represents grouped access to lists of geometrical elements.

Note that if the SimPath represents a list of n values, it can be set either with a single value or with a list of the same size n. Setting with a single value is identical to repeating this single value n times.

The last part of the path needs to be a recognized attribute for the path to actually return a value. Recognized attributes are: Vol, Area, K, Active, C, H, A, D, Extent, WeightedExtent, Count, Conc, Amount, Clamped, Dcst, DcstRel, DiffusionActive, Potential, Capac, Erev, Res, VolRes, I, IClamp, V, VClamped, Indices, Pos, PosSpherical, Immobility, Compartment, Patch, OverlapTets, SDiffD, OnPath, LinkedTo, Ves, Events, ReducedVol.

Note

Should not be directly instantiated by a user, the class is only documented for clarity. A SimPath should only be created through a Simulation.

ALL(*cls)[source]

Extend the path by selecting children

This special method can be used in place of a location or object name when building a path. It will add to the path all children of the current path that are of the given classes. If no classes are given, it adds all possible children of the path to the path. Works in the same way as steps.API_2.utils.NamedObject.ALL().

Parameters:

cls (class) – Zero or more STEPS classes

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Examples:

sim.ALL(Compartment).S1.Count        # The number of S1 Species in all compartments,
                                     # it returns a list of length equal to the number
                                     # of compartments in the simulation.
sim.ALL(Patch).ALL(Species).Count    # The number of each species in each compartment,
                                     # it returns a list with length equal to the sum
                                     # of the number of different Species defined in
                                     # each compartment.
sim.comp1.ALL(Reaction).Active       # Whether each reaction in comp1 is active, it
                                     # returns a list of booleans of length equal to
                                     # the total number of reactions in comp1 (forward
                                     # and backward).
sim.ALL(Compartment, Patch).S1.Count # The number of S1 Species in all compartments
                                     # and patches, it returns a list of length equal
                                     # to the number of compartment and patches.
LIST(*lst)[source]

Extend the path by selecting children in a given list

This special method can be used in place of a location or object name when building a path. It will add to the path all children of the current path that are part of the user-supplied list. The list can contain strings corresponding to the names of the elements, or the elements themselves.

Parameters:

lst (str or steps.API_2.utils.NamedObject) – One or several elements

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Examples:

sim.LIST(comp1, comp2).S1.Count            # The number of S1 Species in compartments
                                           # comp1 and comp2 (in this order).
sim.LIST('comp1', 'comp2').S1.Count        # Same as before, but strings are used
                                           # instead of the elements themselves.
sim.LIST(comp1, patch1).LIST(S1, S2).Count # Number of S1 and S2 Species in comp1 and
                                           # patch1. The resulting order is:
                                           # [comp1.S1, comp1.S2, patch1.S1,
                                           #  patch1.S2].

Note

While the order of elements with ALL() depends on the order of addition of the corresponding elements to the model, the order of elements in LIST() follows the order given by the user in lst.

MATCH(regexp)[source]

Extend the path by selecting children whose name match a regular expression

This special method can be used in place of a location or object name when building a path. It will add to the path all children of the current path whose name match the user-supplied regular expression.

Parameters:

regexp (str`) – The regular expression to be matched to children names

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Examples:

sim.MATCH('comp[1-9]').S1.Count    # The number of S1 Species in compartments comp1
                                   # through comp9. Note that it only adds the
                                   # compartment that do exist in the model.
sim.comp1.MATCH('camkII_.*').Count # The count of each element in comp1 whose name
                                   # starts with 'camkII_'.

Note

An exception will be raised if no children match the pattern.

TET(*tet)[source]

Extend the path by selecting a given tetrahedron

This special method can only be used in place of a location when building a path. It will add the given tetrahedron to the path.

Parameters:

tet (Union[steps.API_2.geom.TetReference, int, Tuple[float, float, float]]) – The tetrahedron, or its index in the mesh, or a 3D point contained in a tetrahedron

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Example:

sim.TET(10).S1.Count      # The number of S1 Species in the tetrahedron with index 10
                          # in the mesh.
sim.TET(tet1).S1.Count    # The number of S1 Species in the tet1 tetrahedron.
sim.TET(0, 0, 0).S1.Count # The number of S1 Species in the tetrahedron that contains
                          # the (x=0, y=0, z=0) point.
TETS(tets=None)[source]

Extend the path by selecting tetrahedrons in a list

This special method can only be used in place of a location when building a path. It will add the given tetrahedrons to the path.

Parameters:

tets (steps.API_2.geom.TetList) – The tetrahedrons, or anything that can be used to build a steps.API_2.geom.TetList. If no parameters are given, selects all tetrahedrons in the mesh.

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Example:

tetLst = TetList([1, 2, 3], mesh=mesh)

sim.TETS(tetLst).S1.Count # The number of S1 Species in the tetrahedrons from tetLst
sim.TETS().S1.Count       # The number of S1 Species in all tetrahedrons in the mesh.
TRI(tri)[source]

Extend the path by selecting a given triangle

This special method can only be used in place of a location when building a path. It will add the given triangle to the path.

Parameters:

tri (Union[steps.API_2.geom.TriReference, int]) – The triangle, or its index in the mesh

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Example:

sim.TRI(10).S1.Count      # The number of S1 Species in the triangle with index 10
                          # in the mesh.
sim.TRI(tri1).S1.Count    # The number of S1 Species in the tri1 triangle.
TRIS(tris=None)[source]

Extend the path by selecting triangles in a list

This special method can only be used in place of a location when building a path. It will add the given triangles to the path.

Parameters:

tris (steps.API_2.geom.TriList) – The triangles, or anything that can be used to build a steps.API_2.geom.TriList. If no parameters are given, selects all triangles in the mesh.

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Example:

triLst = TriList([1, 2, 3], mesh=mesh)

sim.TRIS(triLst).S1.Count # The number of S1 Species in the triangles from triLst
sim.TRIS().S1.Count       # The number of S1 Species in all triangles in the mesh.
VERT(vert)[source]

Extend the path by selecting a given vertex

This special method can only be used in place of a location when building a path. It will add the given vertex to the path.

Parameters:

vert (Union[steps.API_2.geom.VertReference, int]) – The vertex, or its index in the mesh

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Example:

sim.VERT(10).S1.Count     # The number of S1 Species in the vertex with index 10
                          # in the mesh.
sim.VERT(vert1).S1.Count  # The number of S1 Species in the vert1 vertex.
VERTS(verts=None)[source]

Extend the path by selecting vertices in a list

This special method can only be used in place of a location when building a path. It will add the given vertices to the path.

Parameters:

verts (steps.API_2.geom.VertList) – The vertices, or anything that can be used to build a steps.API_2.geom.VertList. If no parameters are given, selects all vertices in the mesh.

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Example:

vertLst = VertList([1, 2, 3], mesh=mesh)

sim.VERTS(vertLst).S1.Count # The number of S1 Species in the vertices from vertLst
sim.VERTS().S1.Count        # The number of S1 Species in all vertices in the mesh.
VESICLE(vesicle)[source]

Extend the path by selecting a given vesicle

This special method can only be used in place of a location when building a path. It will add the given vesicle to the path.

Parameters:

vesicle (VesicleReference) – The specific vesicle

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Example:

ves1 = sim.comp1.addVesicle(vesA) # Get a reference to the added vesicle

sim.VESICLE(ves1).S1.Count        # The number of S1 Species in the ves1 vesicle.
VESICLES(vesicles=None)[source]

Extend the path by selecting vesicles

This special method can be used in place of a location when building a path. If so, it expects either a VesicleList or a SimPath that can be used to build a VesicleList.

It is also possible to use this special method after a location when building a path. If so, it expects either nothing (in which case all vesicle types in that location will be considered), or a steps.API_2.model.Vesicle (in which case only vesicles of the corresponding type will be considered).

Parameters:

vesicles (Union[VesicleList, SimPath, steps.API_2.model.Vesicle]) – The vesicles, a SimPath that can be used to build a VesicleList, or a steps.API_2.model.Vesicle.

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Example:

lst = VesicleList(sim.comp1.vesA)
lstIn = VesicleList(sim.comp1.vesA(inside=True))

sim.VESICLES(lst).S1.Count   # The number of S1 Species on the surface of vesicles from lst
sim.VESICLES(lstIn).S2.Count # The number of S2 Species inside vesicles from lstIn

sim.comp1.VESICLES(vesA).Pos     # The positions of each vesicle of type vesA in comp1
sim.VESICLES(sim.comp1.vesA).Pos # Same

sim.comp1.VESICLES().Pos                 # The positions of all vesicles of all types in comp1
sim.VESICLES(sim.comp1.ALL(Vesicle)).Pos # Same
RAFT(raft)[source]

Extend the path by selecting a given raft

This special method can only be used in place of a location when building a path. It will add the given raft to the path.

Parameters:

raft (RaftReference) – The specific raft

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Example:

raft1 = sim.patch1.addRaft(raftA) # Get a reference to the added raft

sim.RAFT(raft1).S1.Count          # The number of S1 Species in the raft1 raft.
RAFTS(rafts=None)[source]

Extend the path by selecting rafts

This special method can be used in place of a location when building a path. If so, it expects either a RaftList or a SimPath that can be used to build a RaftList.

It is also possible to use this special method after a location when building a path. If so, it expects either nothing (in which case all vesicle types in that location will be considered), or a steps.API_2.model.Raft (in which case only rafts of the corresponding type will be considered).

Parameters:

rafts (Union[RaftList, SimPath, steps.API_2.model.Raft]) – The rafts, a SimPath that can be used to build a RaftList, or a steps.API_2.model.Raft.

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Example:

lst = RaftList(sim.patch1.raftA)

sim.RAFTS(lst).S1.Count             # The number of S1 Species on the rafts from lst

sim.patch1.RAFTS(raftA).Pos         # The positions of each raft of type raftA in patch1
sim.RAFTS(sim.patch1.raftA).Pos     # Same

sim.patch1.RAFTS().Pos              # The positions of all rafts of all types in patch1
sim.RAFTS(sim.patch1.ALL(Raft)).Pos # Same
POINTSPEC(pointSpec)[source]

Extend the path by selecting a given point species

This special method can only be used in place of a location when building a path. It will add the given point species to the path.

Parameters:

pointSpec (PointSpecReference) – The specific point species

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Example:

sim.POINTSPEC(pointSpec1).PosSpherical  # The 3D spherical position of pointSpec1
                                        # with respect to its host vesicle.
POINTSPECS(pointSpecs=None)[source]

Extend the path by selecting point species

This special method can be used in place of a location when building a path. If so, it expects either a PointSpecList or a SimPath that can be used to build a PointSpecList.

It is also possible to use this special method after a location when building a path. Currently, only vesicle surfaces support point species, so the location should be the surface (and not the inside) of a vesicle. If so, it expects either nothing (in which case all point species types in that location will be considered), or a steps.API_2.model.Species (in which case only point species of the corresponding type will be considered).

Parameters:

pointSpecs (Union[PointSpecList, SimPath, steps.API_2.model.Species]) – The point species, a SimPath that can be used to build a PointSpecList, or a steps.API_2.model.Species.

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Example:

lst = PointSpecList(sim.VESICLE(ves1)('surf').SpecA)     # All point species of type SpecA on
                                                         # the surface of specific vesicle ves1

sim.POINTSPECS(lst).PosSpherical                         # The spherical positions on the
                                                         # pointSpecs from lst

sim.VESICLE(ves1)('surf').POINTSPECS(SpecA).PosSpherical # The positions of each pointSpec of
                                                         # type SpecA on specific vesicle ves1

sim.VESICLE(ves1)('surf').POINTSPECS().PosSpherical      # The positions of all pointSpecs of
                                                         # all types on specific vesicle ves1
LINKSPEC(linkSpec)[source]

Extend the path by selecting a given link species

This special method can only be used in place of a location when building a path. It will add the given link species to the path.

Parameters:

linkSpec (LinkSpecReference) – The specific link species

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Example:

sim.LINKSPEC(linkSpec1).Pos  # The 3D position of linkSpec1.
LINKSPECS(linkSpecs=None)[source]

Extend the path by selecting link species

This special method can be used in place of a location when building a path. If so, it expects either a LinkSpecList or a SimPath that can be used to build a LinkSpecList.

It is also possible to use this special method after a location when building a path. If so, it expects either nothing (in which case all link species types in that location will be considered), or a steps.API_2.model.LinkSpecies (in which case only link species of the corresponding type will be considered).

Parameters:

linkSpecs (Union[LinkSpecList, SimPath, steps.API_2.model.LinkSpecies]) – The link species, a SimPath that can be used to build a LinkSpecList, or a steps.API_2.model.LinkSpecies.

Returns:

An updated path taking into account the newly added elements.

Return type:

SimPath

Example:

lst = LinkSpecList(sim.VESICLE(ves1).linkSpecA) # All link species of type linkSpecA on
                                                # specific vesicle ves1

sim.LINKSPECS(lst).Pos                          # The positions on the linkSpecs from lst

sim.VESICLE(ves1).LINKSPECS(linkSpecA).Pos      # The positions of each linkSpec of type
                                                # linkSpecA on specific vesicle ves1

sim.VESICLE(ves1).LINKSPECS().Pos              # The positions of all linkSpecs of all types
                                               # on specific vesicle ves1
addVesicle(ves, diameter=-1.0, dcst=-1.0)[source]

Add a vesicle to a location

This method can only be used with the ‘TetVesicle’ solver. It adds a vesicle to the location specified by the simulation path and returns a reference to the added vesicle. See VesicleReference for additional documentation.

Parameters:

  • ves (Union[steps.API_2.model.Vesicle, str]) – The type of the vesicle that should be added

  • diameter (float) – The diameter of the specific vesicle that should be added. If -1.0, the default diameter from the vesicle type will be used

  • dcst (float) – The diffusion constant (in S.I. units) for this specific vesicle. If -1.0, the default diffusion constant from the vesicle type will be used

Returns:

A reference to the specific vesicle that was added

Return type:

VesicleReference

Example:

uniqueVes1 = sim.comp1.addVesicle(ves_A)
uniqueVes2 = sim.comp1.addVesicle(ves_A, diameter=35e-9, dcst=0.1e-12)
addRaft(raft)[source]

Add a raft to a location

This method can only be used with the ‘TetVesicle’ solver. It adds a raft to the location specified by the simulation path and returns a reference to the added raft. See RaftReference for additional documentation.

Parameters:

raft (Union[steps.API_2.model.Raft, str]) – The type of the raft that should be added

Returns:

A reference to the specific raft that was added

Return type:

RaftReference

Example:

uniqueRaft = sim.TRI(tri1).addRaft(raft_A)
__getattr__(name)[source]

Extend the path with a named element

In most cases, the attribute access syntax is used to build paths, the two following lines are equivalent:

sim.comp1.S1.Count
sim.LIST('comp1').LIST('S1').Count

Attribute access makes the paths more readable and should thus be preferred over the LIST() method when only one element is used.

Parameters:

name – Name of the element

Returns:

An updated path taking into account the newly added element.

Return type:

SimPath

Note

This is a special python method, do not call explicitely sim.__getattr__(name).

__getitem__(key)[source]

Specify further the last path element

All objects that implement the __getitem__ special method can be further specified in the path. The key is just passed to the corresponding object’s __getitem__ method. See:

Parameters:

key (Any) – The specifier that will be passed to the last object(s) in the path

Returns:

An updated path taking into account the additional specification.

Return type:

SimPath

Examples:

sim.comp1.reac1['fwd'].K       # The reaction constant addociated with the forward
                               # part of reac1 in comp1.
sim.patch1.VGNaC[m3, h1].Count # The number of VGNaC in state [m3, h1] on patch1.
sim.patch1.diff1[S1A, S1A].D   # Assuming diff1 is a diffusion rule that was declared
                               # for a complex, this line returns the diffusion
                               # constant for complexes in state [S1A, S1A] in patch1.
__call__(*args, **kwargs)[source]

Give additional information about the last path element

All objects that implement the __call__ special method can receive additional information. The arguments are just passed to the corresponding object’s __call__ method. See:

Parameters:

  • *args – The positional arguments that will be passed to the last object(s) in the path

  • **kwargs – The keyword arguments that will be passed to the last object(s) in the path

Returns:

An updated path taking into account the additional information.

Return type:

SimPath

Examples:

sim.TET(tet1).diff1(direc=tet2).D # Returns the diffusion constant from tet1 to tet2
A

Propensity of reaction, object needs to be a Reaction

Active

Whether a reaction or diffusion rule is active, object needs to be a Reaction or Diffusion

Amount

Amount (in mol) of objects

Area

Area, location needs to be a Patch or triangle(s)

C

Stochastic reaction constant, object needs to be a Reaction

Capac

Capacitance of a membrane or of (a) triangle(s), location needs to be a Membrane or (a) triangle(s)

Clamped

Whether the number of objects is clamped, meaning reactions and other processes do not change the number of objects

Compartment

Compartment of a simulation object like a vesicle

Conc

Concentration of objects, location needs to be a Compartment or tetrahedron(s)

Count

Number of objects

D

Diffusion constant, object needs to be a Diffusion

Dcst

Diffusion constant across a diffusion boundary (object needs to be a DiffBoundary, an additional object must be specified (e.g. a Species)), or diffusion constant of vesicles.

DcstRel

Whether the diffusion constant is relative

DiffusionActive

Whether diffusion across a diffusion boundary is active, object needs to be a DiffBoundary

Erev

Reversal potential of an ohmic current, location needs to be a triangle.

Events

List of recent events, no location and object needs to be a Exocytosys, Endocytosis, or a RaftEndocytosys

Extent

Number of times the reaction or diffusion rule has been executed, object needs to be a Reaction or Diffusion

H

The distinct number of ways a reaction can occur h_mu, object needs to be a Reaction

I

Current through the location, object needs to be a Current

IClamp

Current clamp (in A), location needs to be a vertex or a triangle, object needs to be Current

Immobility

Immobility status of a vesicle, 0 means mobile

Indices

Indices of simulation objects like rafts or vesicles

K

Reaction constant, object needs to be a Reaction

LinkedTo

Index of the link species to which a link species is linked

OnPath

A tuple with the name of the path to which a vesicle is bound, and its current position on the path (3D point). If the vesicle is not on a path, this returns None. Location needs to be a specific vesicle (e.g. VESICLE(vesref))

OverlapTets

List of tetrahedrons that include parts of a specific vesicle

Patch

Patch of a simulation object like a raft

Pos

3D position of simulation objects like rafts or vesicles, coordinates in m.

PosSpherical

Relative position of species on vesicles, spherical coordinates (theta, phi) in (rad, rad) with -pi <= theta <= pi and 0 <= phi <= pi

Potential

Potential of a membrane, location needs to be a Membrane

ReducedVol

Reduced volume of a tetrahedron (taking into account vesicles)

Res

Electrical resistivity and reversal potential of a membrane, location needs to be a Membrane

SDiffD

Surface diffusion constant on vesicle surface

V

Potential of the location, location can be (a) tetrahedron(s), (a) triangle(s) or (a) vert(ex/ices)

VClamped

Whether the potential is clamped at the location (same possible location as for V)

Ves

Index of the specific vesicle containing a simulation object like a link species

Vol

Volume, location needs to be a Compartment or tetrahedron(s)

VolRes

Bulk electrical resistivity (in ohm.m) of the volume associated with a membrane, location needs to be a Membrane

WeightedExtent

Number of times all reactions or diffusion rules in a tetrahedron have been executed multiplied by the number of dependents of each reaction, object needs to be a tetrahedron(s)

class MPI[source]

Bases:

Holds MPI related information and links to mpi packages

MPI packages are only loaded if required and the user does not have to load them manually, changing the solver to an MPI-based one does it automatically.

EF_NONE = 0

Possible value for the calcMembPot parameter of solvers that implement EField. Means that no EField solver is needed.

EF_DEFAULT = 1

Possible value for the calcMembPot parameter of solvers that implement EField. Means that serial EField simulation (Tetexact version) should be run on process 0.

EF_DV_BDSYS = 2

Possible value for the calcMembPot parameter of solvers that implement EField. Means that parallel SuperLU EField solver should be used.

EF_DV_PETSC = 3

Possible value for the calcMembPot parameter of solvers that implement EField. Means that parallel PETSc EField solver should be used.

rank

Get the rank of the current process

Type:

int, read-only

Warning

Accessing this property triggers the importing of MPI related packages

nhosts

Get the number of hosts

Type:

int, read-only

Warning

Accessing this property triggers the importing of MPI related packages

class VesiclePathReference(sim, name, *args, **kwargs)[source]

Bases:

Reference to a vesicle path

An object from this class represents a vesicle path that was added to a simulation. Users should usually instantiate it by calling Simulation.addVesiclePath().

In STEPS, a vesicle path is a directed graph composed of points (graph vertices with a 3D position in space), and edges (directed links between two points of the graph). Vesicles can be transported along the edges of the graph after binding to the first added point of the graph, or to edges themselves, depending on the parameters given to addVesicle().

Parameters:

  • sim (Simulation) – The simulation in which the vesicle path was created

  • name (str) – Name of the vesicle path

addPoint(position)[source]

Add a 3D point to the vesicle path

Parameters:

position (Union[steps.API_2.geom.Point, List[double], Tuple[double]]) – 3D position of the point in cartesian coordinates

Returns:

The index of the point that will be used to add branches

Return type:

int

addEdge(source, destination, weight=1, allow_binding=False)[source]

Create a directed edge between two points of the path

Vesicles will be transported along the segment that goes from source to destination.

Parameters:

  • source (int) – An index for the source point, positive integer

  • destination (int) – An index for the destination point, positive integer

  • weight (float) – Weight of the edge when determining which path a vesicle takes. When a vesicle reaches the end of an edge, it checks the weights of the next edges, if any, and randomly selects the next edge to walk along with a probability that is proportional to its weight.

  • allow_binding (bool) – Whether vesicles can bind to that part of the path. By default vesicles cannot bind to path segments, and can only bind to the first point of a path. When allow_binding is set to True, vesicles that have been added with a non-None binding_rate can bind to the segment. See VesiclePathReference.addVesicle().

addBranch(source, destPoints)[source]

Create branching in the path from a point

Parameters:

  • source (int) – An index for the source point, positive integer

  • destPoints (Dict[int, float]) – A dictionary addociating each destination point with a float

Warning

This method is deprecated in favor of VesiclePathReference.addEdge() and will be removed in subsequent versions of STEPS.

addVesicle(ves, speed, dependencies=None, stoch_stepsize=1e-09, binding_rate=None, min_binding_radius=0, max_binding_radius=-1, unbinding_rate=None, allow_path_intersection=True)[source]

Add a vesicle to this path

This means a vesicle of this type can interact with this path upon overlapping it.

Parameters:

  • ves (Union[steps.API_2.model.Vesicle, str]) – Vesicle type that should be added, or its name

  • speed (float) – Speed of the vesicle on this path in m/s

  • dependencies (Union[None, steps.API_2.ReactionSide]) – Optional species dependencies that should be present on the surface of the vesicle in order to have the possibility to bind to the path.

  • stoch_stepsize (Union[float, List[float]]) – Stochastic step length. This may be a single float value where a single-exponential will be applied. If a list of length 2, a double-exponential will be applied by the proportionality specified in the 2nd element.

  • binding_rate (Union[float, None]) – Binding rate in 1/s at which the vesicle can bind to branches of the path. If None, the vesicle cannot bind to segments of the path. Vesicles can only bind to path segments that have been created with allow_binding=True (see VesiclePathReference.addEdge()). The binding rate corresponds to the rate at which the vesicle should bind to a path segment when its binding volume overlaps the path segment. The binding volume consists in the zone between the sphere of radius max_binding_radius and the sphere of radius min_binding_radius, both centered on the vesicle center.

  • min_binding_radius (float) – The minimum distance (in m) at which a vesicle can bind to a path segment (see the binding_rate parameter). It defaults to 0 (no minimum binding radius). Negative values are interpreted as being relative to the vesicle radius (-0.5 means a minimum binding radius of half the vesicle radius)

  • max_binding_radius (Union[float, None]) – The maximum distance (in m) at which a vesicle can bind to a path segment (see the binding_rate parameter). Negative values are interpreted as being relative to the vesicle radius (-2 means a maximum binding radius of twice the vesicle radius). Defaults to -1.

  • unbinding_rate (Union[float, None]) – Unbinding rate from the path in 1/s. If None, the vesicles cannot unbind from the path until they reach an end.

  • allow_path_intersection (bool) – Whether the vesicle can intersect the path in the course of its travel.

class VesicleReference(sim, tpe, idx, *args, **kwargs)[source]

Bases:

Reference to a specific vesicle

An object from this class represents a specific vesicle in a ‘TetVesicle’ simulation. Users should usually instantiate it by calling SimPath.addVesicle() or by iterating on a VesicleList.

Parameters:

  • sim (Simulation) – The simulation in which the vesicle was created

  • ves_type (Union[steps.API_2.model.Vesicle, str]) – The type of the vesicle

  • ves_idx (int) – The global index of the specific vesicle

exists()[source]

Return whether the specific vesicle exists in the simulation

Returns:

True if the specific vesicle currently exists in the simulation

Return type:

bool

delete()[source]

Delete the vesicle from the simulation

If the vesicle does not exist anymore, this method does not do anything.

setPos(pos, force=False)[source]

Move the vesicle to a 3D position

Parameters:

  • pos (steps.API_2.geom.Point) – The destination position (in m)

  • force (bool) – When True, If another vesicle is already occupying this position, this method will swap the positions of both vesicles. If False, the position will not be changed and a warning message will be displayed.

This method is called with force=False when the Pos property is set.

__call__(loc)[source]

Get a version of the vesicle with added information

Parentheses notation (function call) can be used on a vesicle to specify additional information. It is frequently needed for simulation control and data saving (see steps.API_2.sim.SimPath).

Parameters:

loc – If ‘surf’, the simulation path represents the surface of the selected vesicles, if ‘in’, it represents the inside of the selected vesicles

Returns:

An object that represent the vesicle with the added information

class RaftReference(sim, tpe, idx, *args, **kwargs)[source]

Bases:

Reference to a specific raft

An object from this class represents a specific raft in a ‘TetVesicle’ simulation. Users should usually instantiate it by calling SimPath.addRaft() or by iterating on a RaftList.

Parameters:

  • sim (Simulation) – The simulation in which the raft path was created

  • raft_type (Union[steps.API_2.model.Raft, str]) – The type of the raft

  • raft_idx (int) – The global index of the specific raft

exists()[source]

Return whether the specific raft exists in the simulation

Returns:

True if the specific raft currently exists in the simulation

Return type:

bool

class VesicleList(sim, tpe=None, indices=None, specifArgs=None, *args, **kwargs)[source]

Bases:

List of references to specific vesicles

Parameters:

ves (Union[SimPath, List[VesicleReference]]) – Simulation path to the type of vesicle or list of VesicleReference

class RaftList(sim, tpe=None, indices=None, specifArgs=None, *args, **kwargs)[source]

Bases:

List of references to specific rafts

Parameters:

raft (Union[SimPath, List[RaftReference]]) – Simulation path to the type of raft or list of RaftReference

class LinkSpecList(sim, tpe=None, indices=None, specifArgs=None, *args, **kwargs)[source]

Bases:

List of references to specific link species

Parameters:

linkSpec (Union[SimPath, List[LinkSpecReference]]) – Simulation path to the type of link species or list of LinkSpecReference

class SSAMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

SSA = 0
RSSA = 1
RLEAPING = 2
class NextEventSearchMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

DIRECT = 0
GIBSON_BRUCK = 1
RLEAPING = 2
class DiffusionMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

CONSTANT_DT = 0
TAU_LEAPING_DT = 1
class DistributionMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

UNIFORM = 0
MULTINOMIAL = 1