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.

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)[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

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(**kwargs)
setRk4DT(**kwargs)
setVesicleDT(**kwargs)
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

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, Count, Conc, Amount, Clamped, Dcst, DiffusionActive, Potential, Capac, Res, VolRes, I, IClamp, V, VClamped.

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)[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

Returns

A reference to the specific vesicle that was added

Return type

VesicleReference

Example:

uniqueVes = sim.comp1.addVesicle(ves_A)
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)

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

OverlapTets

List of tetrahedrons that include parts of a specific vesicle

Patch

Patch of a simulation object like a raft

PathPositions

List of 3D points that a vesicle will walk along every vesicle dt

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

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

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

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

addVesicle(ves, speed, dependencies=None, stoch_stepsize=1e-09)[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

  • 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.

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

  • 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)[source]

Bases: IntEnum

An enumeration.

SSA = 0
RSSA = 1
class NextEventSearchMethod(value)[source]

Bases: IntEnum

An enumeration.

DIRECT = 0
GIBSON_BRUCK = 1
class DistributionMethod(value)[source]

Bases: IntEnum

An enumeration.

UNIFORM = 0
MULTINOMIAL = 1