2.4.1. sdepy.paths_generator

class sdepy.paths_generator(*, paths=1, xshape=(), wshape=(), dtype=None, steps=None, i0=0, info=None, getinfo=True)[source]

Step by step generation of stochastic simulations across multiple paths, intended for subclassing.

Given a number of requested paths, shapes and output timeline, encapsulates the low level tasks of memory allocation and step by step iteration along the timeline.

The definition of the target iteration steps (pace method), initialization (begin method), computation of next step (next method), storing results at points on the requested timeline (store method), cleaning up (end method) and evaluation of a final result to be returned (exit method), are delegated to subclasses.

Instances are callables with signature (timeline) that iterate subclass methods along the given timeline, using the configuration set out at instantiation.

Parameters:
paths : int

Size of last axis of the allocated arrays (number of paths of the simulation).

xshape : int or tuple of int

Shape of values that will be stored at each point of the output timeline.

wshape : int or tuple of int

Shape of working space used for step by step iteration.

dtype : data-type

Data-type of the output and working space.

steps : iterable, or int, or None

Specification of the time points to be touched during the simulation (as defined by the pace method). Default behaviour is:

  • if None, the simulated steps coincide with the timeline;
  • if int, the simulated steps touch all timeline points, as well as steps equally spaced points between the minimum and maximum point in the timeline;
  • if iterable, the simulated steps touch all timeline points, as well as all values in steps between the minimum and maximum points in the timeline.
i0 : int

Index along the timeline at which the simulation starts. The timeline is assumed to be in ascending order. The simulation is performed backwards from timeline[i0] to timeline[0], and forwards from timeline[i0] to timeline[-1].

info : dict, or None

Diagnostic information about the simulation is stored in this dictionary and is accessible as the info attribute. If None, a new empty dict is used.

getinfo : bool

If True (default), records basic information in the info attribute about the last performed simulation (if the simulation is both backwards and forwards, the information pertains to the forwards part only). Used by subclasses to enable/disable diagnostic info generation.
Returns:
simulation results

Once instantiated as p, p(timeline) runs the simulation along the given timeline, based on parameters of instantiation, returning results as determined by subclass methods. Defaults to (tt, xx) where tt is a reference to timeline and xx is an array of numpy.nan of the requested shape.

See also

integrator
SDE
SDEs

Notes

All initialization parameters are stored as attributes of the same name, and may be accessed by subclasses.

During the simulation, a itervars attribute is present, pointing to a dictionary that contains the following items, to be used by subclass methods (double letters refer to values along the entire timeline, single letters refer to single time points):

  • steps_tt : an array of all time points to be touched by the simulation. It consolidates the output timeline and the time points to be touched, as specified by steps.
  • tt: the output timeline.
  • xx: simulation output, an array of shape tt.shape + xshape + (paths,). xx[i] is the simulated value at time tt[i].
  • sw: working space for time points, an array of shape (depth,).
  • xw: working space for paths generation, an array of objects of shape (depth,), where each of xw[k] is an array of shape wshape + (paths,).
  • reverse : True if the simulation runs backwards, False otherwise. If True, steps_tt and tt are in descending order.
  • i : such that tt[i] is the next point along the timeline that will be reached (when invoking next), or the point that was just reached (when invoking store).
Note that:
  • sw and xw are rolled at each iteration: subclass methods should not rely on storing references to their elements across iterations.
  • xw[k][...] = value broadcasts value into the allocated memory of xw[k] (this is usually what you want), xw[k] = value stores value, as an object, in xw[k] (avoid).
  • xx and xw[k] are initialized to arrays filled with numpy.nan.
Attributes:
depth : int

Number of time points to be stored in the working space. Defaults to 2.

Methods

__call__(timeline) Run the simulation along the given timeline.
pace(timeline) Target integration steps for the current integration.
begin() Set initial conditions.
next() Numerical simulation step.
store(i, k) Store the current integration step into the integration output.
end() End of iteration optional tasks.
exit(tt, xx) Final tasks and construction of the output value(s).