3.2. stochsim submodule

class mod.stochsim.Simulator(*, labelSettings: mod.LabelSettings = mod.LabelSettings(mod.LabelType.String, mod.LabelRelation.Isomorphism), graphDatabase: List[mod.Graph], strategy: mod.DGStrat, initialState: Dict[mod.Graph, int], draw: Callable[[mod.DG], Callable[[List[mod.DGHyperEdge], mod.PetriNetMarking], Tuple[mod.DGHyperEdge, float]]] = DrawMassAction(), transfer: Dict[mod.Graph, Callable[[mod.Graph, int, float, float], float]] = {}, defaultTransfer: Optional[Callable[[mod.Graph, int, float, float], float]] = None, withSetCompare=True, sortReactions=False)

The main class for performing stochasim simulations.

Parameters

  • labelSettings (mod.LabelSettings) – a settings object that will be passed to mod.DG.__init__().

  • GraphDatabase (list[mod.Graph]) – a list of graphs that will be passed to mod.DG.__init__().

  • strategy (mod.DGStrat) – a strategy that will be passed to mod.DGBuilder.execute() when the simulator needs new hyperedge/reaction information.

  • initialState (dict[mod.Graph, int]) – the initial simulation state in terms of the number of copies of each graph/molecule. Graphs/molecules not mentioned are set to 0.

  • draw (Callable[[mod.DG], Callable[[list[mod.DGHyperEdge], mod.PetriNetMarking], tuple[mod.DGHyperEdge, float]]]) – The simulator will initially create a mod.DG which is given to this function. It must then return a callable that is used in each simulation step to draw the next hyperedge/reaction. Defaults to a default constructed instance of DrawMassAction.

  • transfer (dict[mod.Graph, Callable[[mod.Graph, int, float, float], float]]) –

    a collection of callbacks used in each simulation step to forcibly add or remove copies of specific graphs/molecules. The collection is indexed by the graph/molecule to invoke the callback on. The callback is given

    1. that same graph,

    2. the population count of that graph in the current state,

    3. the current simulation time,

    4. the increase in simulation time for this step.

    It must then return the number of copies to change the population count with. Use a negative count to remove copies and a positive to add. The count may be fractional, and will then be rounded by the simulator randomly weighted by the fractional part. If the resulting count removes more copies from the simulation than are present, then all copies are removed.

    The helper classes LinearTransfer and ExponentialTransfer can be used as a shorthand to make specific types of callbacks.

  • defaultTransfer – a callback similar to those in transfer, but will be applied to every graph/molecule with non-zero population count.

simulate(self, *, time: Optional[float] = None, iterations: Optional[int] = None)

Start/continue the simulation.

Simulate an additional amount of time or number of iterations, whichever is reached first.

Parameters

  • time (Optional[float]) – the additional amount of time to simulate, or None for unbounded.

  • iterations (Optional[int]) – the additional number of iterations to simulate, or None for unbounded.

Returns

a references to the event trace for the simulation. It should not be modified.

Return type

mod.EventTrace

class mod.stochsim.DrawMassAction(rate: Callable[[mod.DGHyperEdge], float] = lambda r: ...)

A creator for a drawing function implementing the law of mass action.

Parameters

rate (Callable[[mod.DGHyperEdge], float]) – a callback for reaction rates, defaulting to a function returning 1.0 for every reaction.

__call__(self, dg: mod.DG)
Parameters

dg (mod.DG) – the derivation graph underlying the simulation.

Returns

a drawing function implementing the law of mass action.

Return type

mod.MassActionKinetics

class mod.stochsim.LinearTransfer(change: float, perTime: float)

A shorthand for a linear transfer function.

Transfer with a fixed rate, given as a fraction change/perTime.

Parameters

  • change (float) – the amount to trasfer.

  • perTime (float) – the time scale to transfer over.

__call__(self, graph: mod.Graph, count: int, time: float, dt: float)
Parameters

  • graph (mod.Graph) – the graph to transfer.

  • count (int) – the current count of the graph.

  • time (float) – the current simulation time.

  • dt (float) – the time increment for this simulation step.

Returns

(dt / perTime) * change

Return type

float

class mod.stochsim.ExponentialTransfer(change: float, perTime: float)

A shorthand for an exponental transfer function.

Transfer in proportion to the current count.

Parameters

  • change (float) – the percentage to change with. Use a number less than 1 to remove (e.g., 0.95 removes 5%), and greater than 1 to add (e.g., 1.05 adds 5%).

  • perTime (float) – the time scale to transfer over.

__call__(self, graph: mod.Graph, count: int, time: float, dt: float)
Parameters

  • graph (mod.Graph) – the graph to transfer.

  • count (int) – the current count of the graph.

  • time (float) – the current simulation time.

  • dt (float) – the time increment for this simulation step.

Returns

count * change**(dt / perTime) - count

Return type

float