tf_quant_finance.math.pde.steppers.douglas_adi.douglas_adi_scheme

Last updated: 2023-03-16.

tf_quant_finance.math.pde.steppers.douglas_adi.douglas_adi_scheme#

View source

Applies Douglas time marching scheme (see [1] and Eq. 3.1 in [2]).

tf_quant_finance.math.pde.steppers.douglas_adi.douglas_adi_scheme(
    theta
)

Time marching schemes solve the space-discretized equation du_inner/dt = A(t) u_inner(t) + A_mixed u(t) + b(t), where u, u_inner and b are vectors and A, A_mixed are matrices. u_inner is u with all boundaries having Robin boundary conditions trimmed and A_mixed are contributions of mixed derivative terms. See more details in multidim_parabolic_equation_stepper.py.

In Douglas scheme (as well as other ADI schemes), the matrix A is represented as sum A = sum_i A_i. A_i is the contribution of terms with partial derivatives w.r.t. dimension i. The shift term is split evenly between A_i. Similarly, inhomogeneous term is represented as sum b = sum_i b_i, where b_i comes from boundary conditions on boundary orthogonal to dimension i.

Given the current values vector u(t1), the step is defined as follows (using the notation of Eq. 3.1 in [2]): Y_0 = (1 + (A(t1) + A_mixed(t1)) dt) U_{n-1} + b(t1) dt, Y_j = Y_{j-1} + theta dt (A_j(t2) Y_j - A_j(t1) U_{n-1} + b_j(t2) - b_j(t1)) for each spatial dimension j, and U_n = Y_{n_dims-1}.

Here the parameter theta is a non-negative number, U_{n-1} = u(t1), U_n = u(t2), and dt = t2 - t1.

Note: Douglas scheme is only first-order accurate if mixed terms are present. More advanced schemes, such as Craig-Sneyd scheme, are needed to achieve the second-order accuracy.

References:#

[1] Douglas Jr., Jim (1962), “Alternating direction methods for three space variables”, Numerische Mathematik, 4 (1): 41-63 [2] Tinne Haentjens, Karek J. in’t Hout. ADI finite difference schemes for the Heston-Hull-White PDE. https://arxiv.org/abs/1111.4087

Args:#

  • theta: Number between 0 and 1 (see the step definition above). theta = 0 corresponds to fully-explicit scheme.

Returns:#

A callable consumes the following arguments by keyword:

  1. inner_value_grid: Grid of solution values at the current time of the same dtype as value_grid and shape of batch_shape + [d_1 - 2 + n_def_i , ..., d_n -2 + n_def_i] where d_i is the number of space discretization points along dimension i and n_def_i is the number of default boundaries along that dimension. n_def_i takes values 0, 1, 2 (default boundary),

  2. t1: Time before the step.

  3. t2: Time after the step.

  4. equation_params_fn: A callable that takes a scalar Tensor argument representing time, and returns a tuple of two objects:

    • First object is a nested list L such that L[i][i] is a tuple of three Tensors, main, upper, and lower diagonal of the tridiagonal matrix A in a direction i. Each element L[i][j] corresponds to the mixed terms and is either None (meaning there are no mixed terms present) or a tuple of Tensors representing contributions of mixed terms in directions (i + 1, j + 1), (i + 1, j - 1), (i - 1, j + 1), and (i - 1, j - 1).

    • The second object is a tuple of inhomogeneous terms for each dimension. All of the Tensors are of the same dtype as inner_value_grid and of the shape broadcastable with the shape of inner_value_grid.

  5. A callable that accepts a Tensor of shape inner_value_grid and appends boundaries according to the boundary conditions, i.e. transforms u_inner to u.

  6. n_dims: A Python integer, the spatial dimension of the PDE.

  7. has_default_lower_boundary: A Python list of booleans of length n_dims. List indices enumerate the dimensions with True values marking default lower boundary condition along corresponding dimensions, and False values indicating Robin boundary conditions.

  8. has_default_upper_boundary: Similar to has_default_lower_boundary, but for upper boundaries. The callable returns a Tensor of the same shape and dtype a values_grid and represents an approximate solution u(t2).

Contents