2.4.3. sdepy.SDE

class sdepy.SDE(*, paths=1, vshape=(), dtype=None, steps=None, i0=0, info=None, getinfo=True, method='euler', **args)[source]

Class representation of a user defined Stochastic Differential Equation (SDE), intended for subclassing.

This class aims to provide an easy to use and flexible interface, allowing to specify user-defined SDEs and expose them in a standardized form to the cooperating integrator class (the latter should always follow in method resolution order). A minimal definition of an Ornstein-Uhlenbeck process is as follows:

>>> from sdepy import SDE, integrator
>>> class my_process(SDE, integrator):
...     def sde(self, t, x, theta=1., k=1., sigma=1.):
...         return {'dt': k*(theta - x), 'dw': sigma}

An SDE is stated as a dictionary, containing for each differential the value of the corresponding coefficient:

dx = f(t, x)*dt + g(t, x)*dw + h(t, x)*dj

translates to:

{'dt': f(t, x), 'dw': g(t, x), 'dj': h(t, x)}

Instances are callables with signature (timeline) that integrate the SDE along the given timeline, using the configuration set out in the instantiation parameters:

>>> P = my_process(x0=1, sigma=0.5, paths=100*1000, steps=100)
>>> x = P(timeline=(0., 0.5, 1.))
>>> x.shape
(3, 100000)

Subclasses can specify or customize: the equation and its parameters (sde method), initial conditions and preprocessing (init method and log attribute), shape of the values to be computed and stored (shapes method), stochastic differentials appearing in the equation (sources attribute) and their parameters and initialization (methods source_dt, source_dw, source_dn, source_dj, or any custom source_{id} method for a corresponding differential '{id}' declared in sources and used as a key in sde return values), optional non array-like parameters (more method), how to store results at points on the requested timeline (let method), and postprocessing (result method and log attribute).

Parameters:
paths : int

Number of paths of the process.

vshape : int or tuple of int

Shape of the values of the process.

dtype : data-type, optional

Data-type of the process. Defaults to the numpy default.

steps : iterable, or int, or None

Specification of the time points to be touched during integration (as accepted by a cooperating integrator class). 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 integration starts. The timeline is assumed to be in ascending order. Initial conditions are set at timeline[i0], the integration is performed backwards from timeline[i0] to timeline[0], and forwards from timeline[i0] to timeline[-1].

info : dict, optional

Diagnostic information about the integration is stored in this dictionary and is accessible as the info attribute. Defaults to a new empty dict.

getinfo : bool

If True, subclass methods info_begin, info_next, info_store, info_end are invoked during integration. Defaults to True.

method : str

Integration method, as accepted by the integrator cooperating class.

**args : SDE-specific parameters

SDE parameters and initial conditions, as implied by the signature of sde, init and more methods, and stochasticity sources parameters, as implied by the signature of source_{id} methods. Each keyword should be used once (e.g. corr, a source_dw parameter, cannot be used as the name of a SDE parameter).
Returns:
process

Once instantiated as p, p(timeline) performs the integration along the given timeline, based on parameters of instantiation, and returns the resulting process as defined by subclass methods. Defaults to a process of numpy.nan along the given timeline.

See also

paths_generator
integrator
SDEs

Notes

Custom stochastic differentials used in the SDE should be recognized, and treated appropriately, by the chosen integration method. This may require customization of the next method of the integrator class.

All named initialization parameters (paths, steps etc.) are stored as attributes.

Notes on SDE-specific parameters:
  • init parameters are converted to arrays via np.asarray.
  • sde and source quantitative parameters may be array-like, or time dependent with signature (t).
  • both are converted to arrays via np.asarray, and for both, their constant value, or values at each time point, should be broadcastable to a shape wshape + (paths,).
  • more parameters undergo no further initialization, before being made available to the shapes and more methods.

If getinfo is True, the invoked info subclass methods may initialize and cumulate diagnostic information in items of the info dictionary, based on read-only access of the internal variables set during integration by paths_generator and integrator cooperating classes, as exposed in the itervars attribute.

Attributes:
sources : set or dict

As a class attribute, holds the names of the differentials 'dz' expected to appear in the equation. As an instance attribute, sources['dz'] is an object, complying with the source protocol, that instantiates the differential 'dz' used during integration. sources['dz'](t, dt) is computed at every step for each 'dz' in sources, as required by the chosen integration method.

args : dict

Stores parameters passed as **args upon initialization of the SDE.

log : bool

If True, the natural logarithm of the initial values set by the init method is taken as the initial value of the integration, and the result of the integration is exponentiated back before serving it to the result method. The sde should expose the appropriate equation for integrating the logarithm of the intended process.

Methods

sde(t, x) Stochastic Differential Equation (SDE) to be integrated.
shapes(vshape) Shape of the values to be computed and stored upon integration of the SDE.
source_dt() Setup a source of deterministic increments, to be used as ‘dt’ during integration.
source_dw([dw, corr, rho]) Setup a source of standard Wiener process (Brownian motion) increments, to be used as ‘dw’ during integration.
source_dn([dn, ptype, lam]) Setup a source of Poisson process increments, to be used as ‘dn’ during integration.
source_dj([dj, dn, ptype, lam, y]) Set up a source of compound Poisson process increments (jumps), to be used as ‘dj’ during integration.
more() Further optional non array parameters, and initializations.
init(t, out_x[, x0]) Set initial conditions for SDE integration.
let(t, out_x, x) Store the value of the integrated process at time point t belonging to the requested output timeline.
result(tt, xx) Compute the integration output.
info_begin() Optional diagnostic information logging function, called before the integration begins.
info_next() Optional diagnostic information logging function, called after each integration step.
info_store() Optional diagnostic information logging function, called after each invocation of the let method.
info_end() Optional diagnostic information logging function, called after the integration has been completed.