*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]).
```python
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 `Tensor`s, 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 `Tensor`s 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 `Tensor`s 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)`.