*Last updated: 2023-03-16.*
# tf_quant_finance.models.hull_white.HullWhiteModel1F
View source
One Factor Hull-White Model.
Inherits From: [`VectorHullWhiteModel`](../../../tf_quant_finance/models/hull_white/VectorHullWhiteModel.md)
```python
tf_quant_finance.models.hull_white.HullWhiteModel1F(
mean_reversion, volatility, initial_discount_rate_fn, dtype=None, name=None
)
```
Represents the Ito process:
```None
dr(t) = (theta(t) - a(t) * r(t)) dt + sigma(t) * dW_{r}(t)
```
where `W_{r}` is a 1D Brownian motion.
`theta`, `a`, `sigma`, are positive functions of time.
`a` correspond to the mean-reversion rate, `sigma` is the volatility of
the process, `theta(t)` is the function that determines long run behaviour
of the process `r(t)` and is defined to match the market data through the
instantaneous forward rate matching:
```None
\theta = df(t) / dt + a * f(t) + 0.5 * sigma**2 / a
* (1 - exp(-2 * a *t)), 1 <= i <= n
```
where `f(t)` is the instantaneous forward rate at time `0` for a maturity
`t` and `df(t)/dt` is the gradient of `f` with respect to the maturity.
See Section 3.3.1 of [1] for details.
If the parameters `a` and `sigma` are piecewise constant functions, the
process is sampled exactly. Otherwise, Euler sampling is used.
#### Example. Hull-White processes with piecewise constant coefficients.
```python
import numpy as np
import tensorflow as tf
import tf_quant_finance as tff
dtype = tf.float64
# Mean-reversion is a piecewise constant function.
mean_reversion = tff.math.piecewise.PiecewiseConstantFunc(
jump_locations=[1, 2, 3, 4],
values=[0.1, 0.2, 0.3, 0.4, 0.5],
dtype=dtype)
# Volatility is a piecewise constant function.
volatility = tff.math.piecewise.PiecewiseConstantFunc(
jump_locations=[0.1, 2.],
values=[0.1, 0.2, 0.1],
dtype=dtype)
initial_discount_rate_fn = lambda *args: [0.01]
process = tff.models.hull_white.HullWhiteModel1F(
mean_reversion=mean_reversion,
volatility=volatility,
initial_discount_rate_fn=initial_discount_rate_fn,
dtype=dtype)
# Sample 10000 paths using Sobol numbers as a random type.
times = np.linspace(0., 1.0, 10)
num_samples = 10000 # number of trajectories
paths = process.sample_paths(
times,
num_samples=num_samples,
times_grid=times,
random_type=tff.math.random.RandomType.SOBOL)
# Compute mean for each Hull-White process at the terminal value
tf.math.reduce_mean(paths[:, -1, 0], axis=0)
# Expected value: 0.02996
```
#### References:
[1]: D. Brigo, F. Mercurio. Interest Rate Models. 2007.
#### Args:
* `mean_reversion`: A real positive scalar `Tensor` or a Python callable. The
callable can be one of the following:
(a) A left-continuous piecewise constant object (e.g.,
`tff.math.piecewise.PiecewiseConstantFunc`) that has a property
`is_piecewise_constant` set to `True`. In this case the object
should have a method `jump_locations(self)` that returns a
`Tensor` of shape `[num_jumps]`. `mean_reversion(t)` should return a
`Tensor` `t.shape`,
where `t` is a rank 1 `Tensor` of the same `dtype` as the output.
See example in the class docstring.
(b) A callable that accepts scalars (stands for time `t`) and returns a
scalar `Tensor` of the same `dtype` as the input.
Corresponds to the mean reversion rate.
* `volatility`: A real positive scalar `Tensor` of the same `dtype` as
`mean_reversion` or a callable with the same specs as above.
Corresponds to the lond run price variance.
* `initial_discount_rate_fn`: A Python callable that accepts expiry time as a
real `Tensor` of the same `dtype` as `mean_reversion` and returns
a `Tensor` of either shape `input_shape`. Corresponds to the initial
discount rates at time `t=0` such that
`P(0,t) = exp(-y(t) * t)` where `P(0,t)` denotes the initial discount
bond prices.
* `dtype`: The default dtype to use when converting values to `Tensor`s.
Default value: `None` which maps to `tf.float32`.
* `name`: Python string. The name to give to the ops created by this class.
Default value: `None` which maps to the default name `hull_white_model`.
#### Attributes:
* `mean_reversion`
* `volatility`
## Methods
dim
View source
```python
dim()
```
The dimension of the process.
discount_bond_price
View source
```python
discount_bond_price(
short_rate, times, maturities, name=None
)
```
Returns zero-coupon bond prices `P(t,T)` conditional on `r(t)`.
#### Args:
* `short_rate`: A `Tensor` of real dtype and shape `batch_shape + [dim]`
specifying the short rate `r(t)`.
* `times`: A `Tensor` of real dtype and shape `batch_shape`. The time `t`
at which discount bond prices are computed.
* `maturities`: A `Tensor` of real dtype and shape `batch_shape`. The time
to maturity of the discount bonds.
* `name`: Str. The name to give this op.
Default value: `discount_bond_prices`.
#### Returns:
A `Tensor` of real dtype and the same shape as `batch_shape + [dim]`
containing the price of zero-coupon bonds.
drift_fn
View source
```python
drift_fn()
```
Python callable calculating instantaneous drift.
The callable should accept two real `Tensor` arguments of the same dtype.
The first argument is the scalar time t, the second argument is the value of
Ito process X - `Tensor` of shape
`batch_shape + sample_shape + [dim]`, where `batch_shape` represents a batch
of models and `sample_shape` represents samples for each of the models. The
result is value of drift a(t, X). The return value of the callable is a real
`Tensor` of the same dtype as the input arguments and of shape
`batch_shape + sample_shape + [dim]`. For example, `sample_shape` can stand
for `[num_samples]` for Monte Carlo sampling, or
`[num_grid_points_1, ..., num_grid_points_dim]` for Finite Difference
solvers.
#### Returns:
The instantaneous drift rate callable.
dtype
View source
```python
dtype()
```
The data type of process realizations.
fd_solver_backward
View source
```python
fd_solver_backward(
start_time, end_time, coord_grid, values_grid, discounting=None,
one_step_fn=None, boundary_conditions=None, start_step_count=0, num_steps=None,
time_step=None, values_transform_fn=None, dtype=None, name=None, **kwargs
)
```
Returns a solver for Feynman-Kac PDE associated to the process.
This method applies a finite difference method to solve the final value
problem as it appears in the Feynman-Kac formula associated to this Ito
process. The Feynman-Kac PDE is closely related to the backward Kolomogorov
equation associated to the stochastic process and allows for the inclusion
of a discounting function.
For more details of the Feynman-Kac theorem see [1]. The PDE solved by this
method is:
```None
V_t + Sum[mu_i(t, x) V_i, 1<=i<=n] +
(1/2) Sum[ D_{ij} V_{ij}, 1 <= i,j <= n] - r(t, x) V = 0
```
In the above, `V_t` is the derivative of `V` with respect to `t`,
`V_i` is the partial derivative with respect to `x_i` and `V_{ij}` the
(mixed) partial derivative with respect to `x_i` and `x_j`. `mu_i` is the
drift of this process and `D_{ij}` are the components of the diffusion
tensor:
```None
D_{ij}(t,x) = (Sigma(t,x) . Transpose[Sigma(t,x)])_{ij}
```
This method evolves a spatially discretized solution of the above PDE from
time `t0` to time `t1 < t0` (i.e. backwards in time).
The solution `V(t,x)` is assumed to be discretized on an `n`-dimensional
rectangular grid. A rectangular grid, G, in n-dimensions may be described
by specifying the coordinates of the points along each axis. For example,
a 2 x 4 grid in two dimensions can be specified by taking the cartesian
product of [1, 3] and [5, 6, 7, 8] to yield the grid points with
coordinates: `[(1, 5), (1, 6), (1, 7), (1, 8), (3, 5) ... (3, 8)]`.
This method allows batching of solutions. In this context, batching means
the ability to represent and evolve multiple independent functions `V`
(e.g. V1, V2 ...) simultaneously. A single discretized solution is specified
by stating its values at each grid point. This can be represented as a
`Tensor` of shape [d1, d2, ... dn] where di is the grid size along the `i`th
axis. A batch of such solutions is represented by a `Tensor` of shape:
`batch_shape + payoff_shape + [d1, d2, ... dn]` where `batch_shape` is the
batch of processes as in the underlying `drift_fn` and `volatility_fn` and
`payoff_shape` are the equations to be solved for each batch element.
The evolution of the solution from `t0` to `t1` is often done by
discretizing the differential equation to a difference equation along
the spatial and temporal axes. The temporal discretization is given by a
(sequence of) time steps [dt_1, dt_2, ... dt_k] such that the sum of the
time steps is equal to the total time step `t0 - t1`. If a uniform time
step is used, it may equivalently be specified by stating the number of
steps (n_steps) to take. This method provides both options via the
`time_step` and `num_steps` parameters. However, not all methods need
discretization along time direction (e.g. method of lines) so this argument
may not be applicable to some implementations.
The workhorse of this method is the `one_step_fn`. For the commonly used
methods, see functions in math.pde.steppers module.
The mapping between the arguments of this method and the above
equation are described in the Args section below.
For a simple instructive example of implementation of this method, see
models.GenericItoProcess.fd_solver_backward.
#### Examples
```python
import tensorflow as tf
import numpy as np
import tf_quant_finance as tff
dtype = tf.float64
# Specify volatilities, interest rates and strikes for the options
volatilities = tf.constant([[0.3], [0.15], [0.1]], dtype)
rates = tf.constant([[0.01], [0.03], [0.01]], dtype)
expiries = 1.0
# Define Generic Ito Process
# Process dimensionality
dim = 1
# Batch size of the process
num_processes = 3
def drift_fn(t, x):
del t
# `x` is expected to be of shape [num_processes] + sample_shape + [dim]
# We need to expand rank of rates to
# `[num_processes] + extra_rank * [1] + [1]`
expand_rank = x.shape.rank - 2
rates_expand = tf.reshape(
rates, [num_processes] + (expand_rank + 1) * [1])
# Output is of shape [num_processes] + sample_shape + [dim]
return rates_expand * x
def vol_fn(t, x):
del t
# `x` is expected to be of shape [num_processes] + sample_shape + [dim]
# As before, need to expand rank of volatilities to
# `[num_processes] + extra_rank * [1] + [1]`
expand_rank = x.shape.rank - 2
volatilities_expand = tf.reshape(
volatilities, [num_processes] + (expand_rank + 1) * [1])
# Output is of shape [num_processes] + sample_shape + [dim, dim]
return (tf.expand_dims(volatilities_expand * x, axis=-1)
* tf.eye(dim, batch_shape=x.shape.as_list()[:-1], dtype=x.dtype))
process = tff.models.GenericItoProcess(dim=dim,
drift_fn=drift_fn,
volatility_fn=vol_fn,
dtype=dtype)
# Define a 2 strikes for each batch process,
num_strikes = 2
# Shape [num_processes, num_strikes, 1]. Here 1 at the end is just for
# convenience
strikes = tf.constant([[[50], [60]], [[100], [90]], [[120], [90]]], dtype)
# Price a batch of European call options
@tff.math.pde.boundary_conditions.dirichlet
def upper_boundary_fn(t, grid):
del grid
# Shape (num_processes, num_strikes)
return tf.squeeze(s_max - strikes * tf.exp(-rates * (expiries - t)))
# Define discounting function
def discounting(t, x):
del t, x
rates_expand = tf.expand_dims(rates, axis=-1)
# Shape compatible with (num_processes, num_strikes)
return rates_expand
# Build a uniform grid
s_min = 0
s_max = 200
num_grid_points = 256 # Number of grid points
grid = tff.math.pde.grids.uniform_grid(minimums=[s_min],
maximums=[s_max],
sizes=[num_grid_points],
dtype=dtype)
# Shape [num_processes, num_strikes, num_grid_points]
final_value_grid = tf.nn.relu(grid[0] - strikes)
# Estimated prices for the European options
process.fd_solver_backward(
start_time=expiries,
end_time=0,
time_step=0.1,
coord_grid=grid,
values_grid=final_value_grid,
discounting=discounting,
boundary_condtions=[(None, upper_boundary_fn)])[0]
# Shape of the output is [num_processes, num_strikes, num_grid_points]
```
#### Args:
* `start_time`: Real positive scalar `Tensor`. The start time of the grid.
Corresponds to time `t0` above.
* `end_time`: Real scalar `Tensor` smaller than the `start_time` and greater
than zero. The time to step back to. Corresponds to time `t1` above.
* `coord_grid`: List of `n` rank 1 real `Tensor`s. `n` is the dimension of the
domain. The i-th `Tensor` has shape, `[d_i]` where `d_i` is the size of
the grid along axis `i`. The coordinates of the grid points. Corresponds
to the spatial grid `G` above.
* `values_grid`: Real `Tensor` containing the function values at time
`start_time` which have to be stepped back to time `end_time`. The shape
of the `Tensor` must broadcast with
`batch_shape + payoff_shape + [d_1, d_2, ..., d_n]`. `batch_shape`
represents the batch of the processes as in the underlying `drift_fn`
and `volatility_fn`. `payoff_shape` specifies equations to be solved for
each batch element (with potentially different boundary/final conditions
and for various coordinate grids). When the batch dimensions
`batch_shape` or `payoff_shape` are present, the shape of values_grid`
must be at least `batch_shape + payoff_shape + dim * [1]`.
* `discounting`: Callable corresponding to `r(t,x)` above. If not supplied,
zero discounting is assumed.
* `one_step_fn`: The transition kernel. A callable that consumes the following
arguments by keyword:
1. 'time': Current time
2. 'next_time': The next time to step to. For the backwards in time
evolution, this time will be smaller than the current time.
3. 'coord_grid': The coordinate grid.
4. 'values_grid': The values grid.
5. 'boundary_conditions': The boundary conditions.
6. 'quadratic_coeff': A callable returning the quadratic coefficients
of the PDE (i.e. `(1/2)D_{ij}(t, x)` above). The callable accepts
the time and coordinate grid as keyword arguments and returns a
`Tensor` with shape that broadcasts with `[dim, dim]`.
7. 'linear_coeff': A callable returning the linear coefficients of the
PDE (i.e. `mu_i(t, x)` above). Accepts time and coordinate grid as
keyword arguments and returns a `Tensor` with shape that broadcasts
with `[dim]`.
8. 'constant_coeff': A callable returning the coefficient of the
linear homogeneous term (i.e. `r(t,x)` above). Same spec as above.
The `one_step_fn` callable returns a 2-tuple containing the next
coordinate grid, next values grid.
* `boundary_conditions`: The boundary conditions. Only rectangular boundary
conditions are supported. A list of tuples of size `n` (space dimension
of the PDE). The elements of the Tuple can be either a Python Callable
or `None` representing the boundary conditions at the minimum and
maximum values of the spatial variable indexed by the position in the
list. E.g., for `n=2`, the length of `boundary_conditions` should be 2,
`boundary_conditions[0][0]` describes the boundary `(y_min, x)`, and
`boundary_conditions[1][0]`- the boundary `(y, x_min)`. `None` values
mean that the second order terms for that dimension on the boundary are
assumed to be zero, i.e., if `boundary_conditions[k][0]` is `None`,
'dV/dt + Sum[a_ij d2(A_ij V)/dx_i dx_j, 1 <= i, j <= n, i!=k+1, j!=k+1]
+ Sum[b_i d(B_i V)/dx_i, 1 <= i <= n] + c V = 0.'
For not `None` values, the boundary conditions are accepted in the form
`alpha(t, x) V + beta(t, x) V_n = gamma(t, x)`, where `V_n` is the
derivative with respect to the exterior normal to the boundary.
Each callable receives the current time `t` and the `coord_grid` at the
current time, and should return a tuple of `alpha`, `beta`, and `gamma`.
Each can be a number, a zero-rank `Tensor` or a `Tensor` whose shape is
the grid shape with the corresponding dimension removed.
For example, for a two-dimensional grid of shape `(b, ny, nx)`, where
`b` is the batch size, `boundary_conditions[0][i]` with `i = 0, 1`
should return a tuple of either numbers, zero-rank tensors or tensors of
shape `(b, nx)`. Similarly for `boundary_conditions[1][i]`, except the
tensor shape should be `(b, ny)`. `alpha` and `beta` can also be `None`
in case of Neumann and Dirichlet conditions, respectively.
Default value: `None`. Unlike setting `None` to individual elements of
`boundary_conditions`, setting the entire `boundary_conditions` object
to `None` means Dirichlet conditions with zero value on all boundaries
are applied.
* `start_step_count`: Scalar integer `Tensor`. Initial value for the number of
time steps performed.
Default value: 0 (i.e. no previous steps performed).
* `num_steps`: Positive int scalar `Tensor`. The number of time steps to take
when moving from `start_time` to `end_time`. Either this argument or the
`time_step` argument must be supplied (but not both). If num steps is
`k>=1`, uniform time steps of size `(t0 - t1)/k` are taken to evolve the
solution from `t0` to `t1`. Corresponds to the `n_steps` parameter
above.
* `time_step`: The time step to take. Either this argument or the `num_steps`
argument must be supplied (but not both). The type of this argument may
be one of the following (in order of generality): (a) None in which case
`num_steps` must be supplied. (b) A positive real scalar `Tensor`. The
maximum time step to take. If the value of this argument is `dt`, then
the total number of steps taken is N = (t0 - t1) / dt rounded up to
the nearest integer. The first N-1 steps are of size dt and the last
step is of size `t0 - t1 - (N-1) * dt`. (c) A callable accepting the
current time and returning the size of the step to take. The input and
the output are real scalar `Tensor`s.
* `values_transform_fn`: An optional callable applied to transform the
solution values at each time step. The callable is invoked after the
time step has been performed. The callable should accept the time of the
grid, the coordinate grid and the values grid and should return the
values grid. All input arguments to be passed by keyword.
* `dtype`: The dtype to use.
* `name`: The name to give to the ops.
Default value: None which means `solve_backward` is used.
* `**kwargs`: Additional keyword args:
(1) pde_solver_fn: Function to solve the PDE that accepts all the above
arguments by name and returns the same tuple object as required below.
Defaults to `tff.math.pde.fd_solvers.solve_backward`.
#### Returns:
A tuple object containing at least the following attributes:
final_values_grid: A `Tensor` of same shape and dtype as `values_grid`.
Contains the final state of the values grid at time `end_time`.
final_coord_grid: A list of `Tensor`s of the same specification as
the input `coord_grid`. Final state of the coordinate grid at time
`end_time`.
step_count: The total step count (i.e. the sum of the `start_step_count`
and the number of steps performed in this call.).
final_time: The final time at which the evolution stopped. This value
is given by `max(min(end_time, start_time), 0)`.
fd_solver_forward
View source
```python
fd_solver_forward(
start_time, end_time, coord_grid, values_grid, one_step_fn=None,
boundary_conditions=None, start_step_count=0, num_steps=None, time_step=None,
values_transform_fn=None, dtype=None, name=None, **kwargs
)
```
Returns a solver for the Fokker Plank equation of this process.
The Fokker Plank equation (also known as the Kolmogorov Forward equation)
associated to this Ito process is given by:
```None
V_t + Sum[(mu_i(t, x) V)_i, 1<=i<=n]
- (1/2) Sum[ (D_{ij} V)_{ij}, 1 <= i,j <= n] = 0
```
with the initial value condition $$V(0, x) = u(x)$$.
This method evolves a spatially discretized solution of the above PDE from
time `t0` to time `t1 > t0` (i.e. forwards in time).
The solution `V(t,x)` is assumed to be discretized on an `n`-dimensional
rectangular grid. A rectangular grid, G, in n-dimensions may be described
by specifying the coordinates of the points along each axis. For example,
a 2 x 4 grid in two dimensions can be specified by taking the cartesian
product of [1, 3] and [5, 6, 7, 8] to yield the grid points with
coordinates: `[(1, 5), (1, 6), (1, 7), (1, 8), (3, 5) ... (3, 8)]`.
This method allows batching of solutions. In this context, batching means
the ability to represent and evolve multiple independent functions `V`
(e.g. V1, V2 ...) simultaneously. A single discretized solution is specified
by stating its values at each grid point. This can be represented as a
`Tensor` of shape [d1, d2, ... dn] where di is the grid size along the `i`th
axis. A batch of such solutions is represented by a `Tensor` of shape:
`batch_shape + payoff_shape + [d1, d2, ... dn]` where `batch_shape` is the
batch of processes as in the underlying `drift_fn` and `volatility_fn` and
`payoff_shape` are the equations to be solved for each batch element.
The evolution of the solution from `t0` to `t1` is often done by
discretizing the differential equation to a difference equation along
the spatial and temporal axes. The temporal discretization is given by a
(sequence of) time steps [dt_1, dt_2, ... dt_k] such that the sum of the
time steps is equal to the total time step `t1 - t0`. If a uniform time
step is used, it may equivalently be specified by stating the number of
steps (n_steps) to take. This method provides both options via the
`time_step` and `num_steps` parameters. However, not all methods need
discretization along time direction (e.g. method of lines) so this argument
may not be applicable to some implementations.
The workhorse of this method is the `one_step_fn`. For the commonly used
methods, see functions in math.pde.steppers module.
The mapping between the arguments of this method and the above
equation are described in the Args section below.
For a simple instructive example of implementation of this method, see
models.GenericItoProcess.fd_solver_forward.
#### Args:
* `start_time`: Real positive scalar `Tensor`. The start time of the grid.
Corresponds to time `t0` above.
* `end_time`: Real scalar `Tensor` smaller than the `start_time` and greater
than zero. The time to step back to. Corresponds to time `t1` above.
* `coord_grid`: List of `n` rank 1 real `Tensor`s. `n` is the dimension of the
domain. The i-th `Tensor` has shape, `[d_i]` where `d_i` is the size of
the grid along axis `i`. The coordinates of the grid points. Corresponds
to the spatial grid `G` above.
* `values_grid`: Real `Tensor` containing the function values at time
`start_time` which have to be stepped back to time `end_time`. The shape
of the `Tensor` must broadcast with
`batch_shape + payoff_shape + [d_1, d_2, ..., d_n]`. `batch_shape`
represents the batch of the processes as in the underlying `drift_fn`
and `volatility_fn`. `payoff_shape` specifies equations to be solved for
each batch element (with potentially different boundary/final conditions
and for various coordinate grids). When the batch dimensions
`batch_shape` or `payoff_shape` are present, the shape of values_grid`
must be at least `batch_shape + payoff_shape + dim * [1]`.
* `one_step_fn`: The transition kernel. A callable that consumes the following
arguments by keyword:
1. 'time': Current time
2. 'next_time': The next time to step to. For the backwards in time
evolution, this time will be smaller than the current time.
3. 'coord_grid': The coordinate grid.
4. 'values_grid': The values grid.
5. 'quadratic_coeff': A callable returning the quadratic coefficients
of the PDE (i.e. `(1/2)D_{ij}(t, x)` above). The callable accepts
the time and coordinate grid as keyword arguments and returns a
`Tensor` with shape that broadcasts with `[dim, dim]`.
6. 'linear_coeff': A callable returning the linear coefficients of the
PDE (i.e. `mu_i(t, x)` above). Accepts time and coordinate grid as
keyword arguments and returns a `Tensor` with shape that broadcasts
with `[dim]`.
7. 'constant_coeff': A callable returning the coefficient of the
linear homogeneous term (i.e. `r(t,x)` above). Same spec as above.
The `one_step_fn` callable returns a 2-tuple containing the next
coordinate grid, next values grid.
* `boundary_conditions`: The boundary conditions. Only rectangular boundary
conditions are supported. A list of tuples of size `n` (space dimension
of the PDE). The elements of the Tuple can be either a Python Callable
or `None` representing the boundary conditions at the minimum and
maximum values of the spatial variable indexed by the position in the
list. E.g., for `n=2`, the length of `boundary_conditions` should be 2,
`boundary_conditions[0][0]` describes the boundary `(y_min, x)`, and
`boundary_conditions[1][0]`- the boundary `(y, x_min)`. `None` values
mean that the second order terms for that dimension on the boundary are
assumed to be zero, i.e., if `boundary_conditions[k][0]` is `None`,
'dV/dt + Sum[a_ij d2(A_ij V)/dx_i dx_j, 1 <= i, j <= n, i!=k+1, j!=k+1]
+ Sum[b_i d(B_i V)/dx_i, 1 <= i <= n] + c V = 0.'
For not `None` values, the boundary conditions are accepted in the form
`alpha(t, x) V + beta(t, x) V_n = gamma(t, x)`, where `V_n` is the
derivative with respect to the exterior normal to the boundary.
Each callable receives the current time `t` and the `coord_grid` at the
current time, and should return a tuple of `alpha`, `beta`, and `gamma`.
Each can be a number, a zero-rank `Tensor` or a `Tensor` whose shape is
the grid shape with the corresponding dimension removed.
For example, for a two-dimensional grid of shape `(b, ny, nx)`, where
`b` is the batch size, `boundary_conditions[0][i]` with `i = 0, 1`
should return a tuple of either numbers, zero-rank tensors or tensors of
shape `(b, nx)`. Similarly for `boundary_conditions[1][i]`, except the
tensor shape should be `(b, ny)`. `alpha` and `beta` can also be `None`
in case of Neumann and Dirichlet conditions, respectively.
Default value: `None`. Unlike setting `None` to individual elements of
`boundary_conditions`, setting the entire `boundary_conditions` object
to `None` means Dirichlet conditions with zero value on all boundaries
are applied.
* `start_step_count`: Scalar integer `Tensor`. Initial value for the number of
time steps performed.
Default value: 0 (i.e. no previous steps performed).
* `num_steps`: Positive int scalar `Tensor`. The number of time steps to take
when moving from `start_time` to `end_time`. Either this argument or the
`time_step` argument must be supplied (but not both). If num steps is
`k>=1`, uniform time steps of size `(t0 - t1)/k` are taken to evolve the
solution from `t0` to `t1`. Corresponds to the `n_steps` parameter
above.
* `time_step`: The time step to take. Either this argument or the `num_steps`
argument must be supplied (but not both). The type of this argument may
be one of the following (in order of generality): (a) None in which case
`num_steps` must be supplied. (b) A positive real scalar `Tensor`. The
maximum time step to take. If the value of this argument is `dt`, then
the total number of steps taken is N = (t1 - t0) / dt rounded up to
the nearest integer. The first N-1 steps are of size dt and the last
step is of size `t1 - t0 - (N-1) * dt`. (c) A callable accepting the
current time and returning the size of the step to take. The input and
the output are real scalar `Tensor`s.
* `values_transform_fn`: An optional callable applied to transform the
solution values at each time step. The callable is invoked after the
time step has been performed. The callable should accept the time of the
grid, the coordinate grid and the values grid and should return the
values grid. All input arguments to be passed by keyword.
* `dtype`: The dtype to use.
* `name`: The name to give to the ops.
Default value: None which means `solve_forward` is used.
* `**kwargs`: Additional keyword args:
(1) pde_solver_fn: Function to solve the PDE that accepts all the above
arguments by name and returns the same tuple object as required below.
Defaults to `tff.math.pde.fd_solvers.solve_forward`.
#### Returns:
A tuple object containing at least the following attributes:
final_values_grid: A `Tensor` of same shape and dtype as `values_grid`.
Contains the final state of the values grid at time `end_time`.
final_coord_grid: A list of `Tensor`s of the same specification as
the input `coord_grid`. Final state of the coordinate grid at time
`end_time`.
step_count: The total step count (i.e. the sum of the `start_step_count`
and the number of steps performed in this call.).
final_time: The final time at which the evolution stopped. This value
is given by `max(min(end_time, start_time), 0)`.
instant_forward_rate
View source
```python
instant_forward_rate(
t
)
```
Returns the instantaneous forward rate.
name
View source
```python
name()
```
The name to give to ops created by this class.
sample_discount_curve_paths
View source
```python
sample_discount_curve_paths(
times, curve_times, num_samples=1, random_type=None, seed=None, skip=0,
time_step=None, times_grid=None, normal_draws=None, validate_args=False,
name=None
)
```
Returns a sample of simulated discount curves for the Hull-white model.
### References:
[1]: Leif B.G. Andersen and Vladimir V. Piterbarg. Interest Rate Modeling,
Volume II: Term Structure Models. 2010.
#### Args:
* `times`: Rank 1 `Tensor` of positive real values. The times at which the
discount curves are to be evaluated.
* `curve_times`: Rank 1 `Tensor` of positive real values. The maturities
at which discount curve is computed at each simulation time.
* `num_samples`: Positive scalar `int`. The number of paths to draw.
* `random_type`: Enum value of `RandomType`. The type of (quasi)-random
number generator to use to generate the paths.
Default value: None which maps to the standard pseudo-random numbers.
* `seed`: Seed for the random number generator. The seed is
only relevant if `random_type` is one of
`[STATELESS, PSEUDO, HALTON_RANDOMIZED, PSEUDO_ANTITHETIC,
STATELESS_ANTITHETIC]`. For `PSEUDO`, `PSEUDO_ANTITHETIC` and
`HALTON_RANDOMIZED` the seed should be an Python integer. For
`STATELESS` and `STATELESS_ANTITHETIC` must be supplied as an integer
`Tensor` of shape `[2]`.
Default value: `None` which means no seed is set.
* `skip`: `int32` 0-d `Tensor`. The number of initial points of the Sobol or
Halton sequence to skip. Used only when `random_type` is 'SOBOL',
'HALTON', or 'HALTON_RANDOMIZED', otherwise ignored.
Default value: `0`.
* `time_step`: Scalar real `Tensor`. Maximal distance between time grid points
in Euler scheme. Used only when Euler scheme is applied.
Default value: `None`.
* `times_grid`: An optional rank 1 `Tensor` representing time discretization
grid. If `times` are not on the grid, then the nearest points from the
grid are used. When supplied, `time_step` and jumps of the piecewise
constant arguments are ignored.
Default value: `None`, which means that the times grid is computed using
`time_step`. When exact sampling is used, the shape should be equal to
`[num_time_points + 1]` where `num_time_points` is `tf.shape(times)[0]`
plus the number of jumps of the Hull-White piecewise constant
parameters. The grid should include the initial time point which is
usually set to `0.0`.
* `normal_draws`: A `Tensor` of shape `[num_samples, num_time_points, dim]`
and the same `dtype` as `times`. Represents random normal draws to
compute increments `N(0, t_{n+1}) - N(0, t_n)`. When supplied,
`num_samples` argument is ignored and the first dimensions of
`normal_draws` is used instead. When exact sampling is used,
`num_time_points` should be equal to `tf.shape(times)[0]` plus the
number of jumps of the Hull-White piecewise constant parameters.
Default value: `None` which means that the draws are generated by the
algorithm.
* `validate_args`: Python `bool`. When `True` and `normal_draws` are supplied,
checks that `tf.shape(normal_draws)[1]` is equal to the total number of
time steps performed by the sampler.
When `False` invalid dimension may silently render incorrect outputs.
Default value: `False`.
* `name`: Str. The name to give this op.
Default value: `sample_discount_curve_paths`.
#### Returns:
A tuple containing two `Tensor`s. The first element is a `Tensor` of
shape [num_samples, m, k, dim] and contains the simulated bond curves
where `m` is the size of `curve_times`, `k` is the size of `times` and
`dim` is the dimension of the process. The second element is a `Tensor`
of shape [num_samples, k, dim] and contains the simulated short rate
paths.
#### Raises:
* `ValueError`: (a) If `times` has rank different from `1`.
(b) If Euler scheme is used by times is not supplied.
(c) When neither `times_grid` nor `time_step` are supplied and Euler
scheme is used.
(d) If `normal_draws` is supplied and `dim` is mismatched.
* `tf.errors.InvalidArgumentError`: If `normal_draws` is supplied and the
number of time steps implied by `times_grid` or `times_step` is
mismatched.
(e) If any of the parameters `mean_reversion`, `volatility`,
`corr_matrix` is a generic callable.
sample_paths
View source
```python
sample_paths(
times, num_samples, random_type=None, seed=None, skip=0, time_step=None,
times_grid=None, normal_draws=None, validate_args=False, name=None
)
```
Returns a sample of paths from the correlated Hull-White process.
Uses exact sampling if `self.mean_reversion` is constant and
`self.volatility` and `self.corr_matrix` are all `Tensor`s or piecewise
constant functions, and Euler scheme sampling otherwise.
The exact sampling implements the algorithm and notations in [1], section
10.1.6.1.
#### Args:
* `times`: Rank 1 `Tensor` of positive real values. The times at which the
path points are to be evaluated.
* `num_samples`: Positive scalar `int32` `Tensor`. The number of paths to
draw.
* `random_type`: Enum value of `RandomType`. The type of (quasi)-random
number generator to use to generate the paths.
Default value: `None` which maps to the standard pseudo-random numbers.
* `seed`: Seed for the random number generator. The seed is
only relevant if `random_type` is one of
`[STATELESS, PSEUDO, HALTON_RANDOMIZED, PSEUDO_ANTITHETIC,
STATELESS_ANTITHETIC]`. For `PSEUDO`, `PSEUDO_ANTITHETIC` and
`HALTON_RANDOMIZED` the seed should be an Python integer. For
`STATELESS` and `STATELESS_ANTITHETIC `must be supplied as an integer
`Tensor` of shape `[2]`.
Default value: `None` which means no seed is set.
* `skip`: `int32` 0-d `Tensor`. The number of initial points of the Sobol or
Halton sequence to skip. Used only when `random_type` is 'SOBOL',
'HALTON', or 'HALTON_RANDOMIZED', otherwise ignored.
Default value: `0`.
* `time_step`: Scalar real `Tensor`. Maximal distance between time grid points
in Euler scheme. Used only when Euler scheme is applied.
Default value: `None`.
* `times_grid`: An optional rank 1 `Tensor` representing time discretization
grid. If `times` are not on the grid, then the nearest points from the
grid are used. When supplied, `time_step` and jumps of the piecewise
constant arguments are ignored.
Default value: `None`, which means that the times grid is computed using
`time_step`. When exact sampling is used, the shape should be equal to
`[num_time_points + 1]` where `num_time_points` is `tf.shape(times)[0]`
plus the number of jumps of the Hull-White piecewise constant
parameters. The grid should include the initial time point which is
usually set to `0.0`.
* `normal_draws`: A `Tensor` of shape `[num_samples, num_time_points, dim]`
and the same `dtype` as `times`. Represents random normal draws to
compute increments `N(0, t_{n+1}) - N(0, t_n)`. When supplied,
`num_samples` argument is ignored and the first dimensions of
`normal_draws` is used instead. When exact sampling is used,
`num_time_points` should be equal to `tf.shape(times)[0]` plus the
number of jumps of the Hull-White piecewise constant parameters.
Default value: `None` which means that the draws are generated by the
algorithm.
* `validate_args`: Python `bool`. When `True` and `normal_draws` are supplied,
checks that `tf.shape(normal_draws)[1]` is equal to the total number of
time steps performed by the sampler.
When `False` invalid dimension may silently render incorrect outputs.
Default value: `False`.
* `name`: Python string. The name to give this op.
Default value: `sample_paths`.
#### Returns:
A `Tensor` of shape [num_samples, k, dim] where `k` is the size
of the `times` and `dim` is the dimension of the process.
#### Raises:
* `ValueError`: (a) If `times` has rank different from `1`.
(b) If Euler scheme is used by times is not supplied.
(c) When neither `times_grid` nor `time_step` are supplied and Euler
scheme is used.
(d) If `normal_draws` is supplied and `dim` is mismatched.
* `tf.errors.InvalidArgumentError`: If `normal_draws` is supplied and the
number of time steps implied by `times_grid` or `times_step` is
mismatched.
volatility_fn
View source
```python
volatility_fn()
```
Python callable calculating the instantaneous volatility.
The callable should accept two real `Tensor` arguments of the same dtype and
shape `times_shape`. The first argument is the scalar time t, the second
argument is the value of Ito process X - `Tensor` of shape
`batch_shape + sample_shape + [dim]`, where `batch_shape` represents a batch
of models and `sample_shape` represents samples for each of the models. The
result is value of volatility S_{ij}(t, X). The return value of the callable
is a real `Tensor` of the same dtype as the input arguments and of shape
`batch_shape + sample_shape + [dim, dim]`. For example, `sample_shape` can
stand for `[num_samples]` for Monte Carlo sampling, or
`[num_grid_points_1, ..., num_grid_points_dim]` for Finite Difference
solvers.
#### Returns:
The instantaneous volatility callable.