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 assteps
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.
- if
- 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]
totimeline[0]
, and forwards fromtimeline[i0]
totimeline[-1]
.- info : dict, or None
Diagnostic information about the simulation is stored in this dictionary and is accessible as the
info
attribute. IfNone
, a new emptydict
is used.- getinfo : bool
If
True
(default), records basic information in theinfo
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)
wherett
is a reference totimeline
andxx
is an array ofnumpy.nan
of the requested shape.
See also
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 bysteps
.tt
: the output timeline.xx
: simulation output, an array of shapett.shape + xshape + (paths,)
.xx[i]
is the simulated value at timett[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 ofxw[k]
is an array of shapewshape + (paths,)
.reverse
:True
if the simulation runs backwards,False
otherwise. IfTrue
,steps_tt
andtt
are in descending order.i
: such thattt[i]
is the next point along the timeline that will be reached (when invokingnext
), or the point that was just reached (when invokingstore
).
- Note that:
sw
andxw
are rolled at each iteration: subclass methods should not rely on storing references to their elements across iterations.xw[k][...] = value
broadcastsvalue
into the allocated memory ofxw[k]
(this is usually what you want),xw[k] = value
storesvalue
, as an object, inxw[k]
(avoid).xx
andxw[k]
are initialized to arrays filled withnumpy.nan
.
Attributes: - depth : int
Number of time points to be stored in the working space. Defaults to 2.
Methods
__call__
(self, timeline)Run the simulation along the given timeline. pace
(self, timeline)Target integration steps for the current integration. begin
(self)Set initial conditions. next
(self)Numerical simulation step. store
(self, i, k)Store the current integration step into the integration output. end
(self)End of iteration optional tasks. exit
(self, tt, xx)Final tasks and construction of the output value(s).