naginterfaces.library.pde.dim1_​blackscholes_​fd

naginterfaces.library.pde.dim1_blackscholes_fd(kopt, x, mesh, s, t, tdpar, r, q, sigma, ntkeep, alpha=0.55)

dim1_blackscholes_fd solves the Black–Scholes equation for financial option pricing using a finite difference scheme.

For full information please refer to the NAG Library document for d03nc

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d03/d03ncf.html

Parameters

koptint

Specifies the kind of option to be valued.

$kopt=1$

A European call option.

$kopt=2$

An American call option.

$kopt=3$

A European put option.

$kopt=4$

An American put option.

xfloat

The exercise price $X$.

meshstr, length 1

Indicates the type of finite difference mesh to be used:

$mesh=\text{'U'}$

Uniform mesh.

$mesh=\text{'C'}$

Custom mesh supplied by you.

sfloat, array-like, shape $\left(\text{ns}\right)$

If $mesh=\text{'C'}$, $s[\text{i}-1]$ must contain the $\text{i}$th stock price in the mesh, for $\text{i}=1,2,\dots ,\text{ns}$. These values should be in increasing order, with $s\left[0\right]=S_{min}$ and $s[\text{ns}-1]=S_{max}$.

If $mesh=\text{'U'}$, $s\left[0\right]$ must be set to $S_{min}$ and $s[\text{ns}-1]$ to $S_{max}$, but $s\left[1\right],s\left[2\right],\dots ,s[\text{ns}-2]$ need not be initialized, as they will be set internally by the function in order to define a uniform mesh.

tfloat, array-like, shape $\left(\text{nt}\right)$

If $mesh=\text{'C'}$ then $t[\text{j}-1]$ must contain the $\text{j}$th time in the mesh, for $\text{j}=1,2,\dots ,\text{nt}$. These values should be in increasing order, with $t\left[0\right]=t_{min}$ and $t[\text{nt}-1]=t_{max}$.

If $mesh=\text{'U'}$ then $t\left[0\right]$ must be set to $t_{min}$ and $t[\text{nt}-1]$ to $t_{max}$, but $t\left[1\right],t\left[2\right],\dots ,t[\text{nt}-2]$ need not be initialized, as they will be set internally by the function in order to define a uniform mesh.

tdparbool, array-like, shape $\left(3\right)$

Specifies whether or not various arguments are time-dependent. More precisely, $r$ is time-dependent if $tdpar\left[0\right]=True$ and constant otherwise. Similarly, $tdpar\left[1\right]$ specifies whether $q$ is time-dependent and $tdpar\left[2\right]$ specifies whether $\sigma$ is time-dependent.

rfloat, array-like, shape $(:)$

Note: the required length for this argument is determined as follows: if $tdpar\left[0\right]=True$: $\text{nt}$; otherwise: $1$.

If $tdpar\left[0\right]=True$ then $r[\text{j}-1]$ must contain the value of the risk-free interest rate $r\left(t\right)$ at the $\text{j}$th time in the mesh, for $\text{j}=1,2,\dots ,\text{nt}$.

If $tdpar\left[0\right]=False$ then $r\left[0\right]$ must contain the constant value of the risk-free interest rate $r$.

The remaining elements need not be set.

qfloat, array-like, shape $(:)$

Note: the required length for this argument is determined as follows: if $tdpar\left[1\right]=True$: $\text{nt}$; otherwise: $1$.

If $tdpar\left[1\right]=True$ then $q[\text{j}-1]$ must contain the value of the continuous dividend $q\left(t\right)$ at the $\text{j}$th time in the mesh, for $\text{j}=1,2,\dots ,\text{nt}$.

If $tdpar\left[1\right]=False$ then $q\left[0\right]$ must contain the constant value of the continuous dividend $q$.

The remaining elements need not be set.

sigmafloat, array-like, shape $(:)$

Note: the required length for this argument is determined as follows: if $tdpar\left[2\right]=True$: $\text{nt}$; otherwise: $1$.

If $tdpar\left[2\right]=True$ then $sigma[\text{j}-1]$ must contain the value of the volatility $\sigma \left(t\right)$ at the $\text{j}$th time in the mesh, for $\text{j}=1,2,\dots ,\text{nt}$.

If $tdpar\left[2\right]=False$ then $sigma\left[0\right]$ must contain the constant value of the volatility $\sigma$.

The remaining elements need not be set.

ntkeepint

The number of solutions to be stored in the time direction. The function calculates the solution backwards from $t[\text{nt}-1]$ to $t\left[0\right]$ at all times in the mesh. These time solutions and the corresponding Greeks will be stored at times $t[\text{i}-1]$, for $\text{i}=1,2,\dots ,ntkeep$, in the arrays $f$, $theta$, $delta$, $gamma$, $lamda$ and $rho$. Other time solutions will be discarded. To store all time solutions set $ntkeep=\text{nt}$.

alphafloat, optional

The value of $\lambda$ to be used in the time-stepping scheme. Typical values include:

$alpha=0.0$

Explicit forward Euler scheme.

$alpha=0.5$

Implicit Crank–Nicolson scheme.

$alpha=1.0$

Implicit backward Euler scheme.

The value $0.5$ gives second-order accuracy in time.

Values greater than $0.5$ give unconditional stability.

Since $0.5$ is at the limit of unconditional stability this value does not damp oscillations.

Returns

sfloat, ndarray, shape $\left(\text{ns}\right)$

If $mesh=\text{'U'}$, the elements of $s$ define a uniform mesh over $[S_{min},S_{max}]$.

If $mesh=\text{'C'}$, the elements of $s$ are unchanged.

tfloat, ndarray, shape $\left(\text{nt}\right)$

If $mesh=\text{'U'}$, the elements of $t$ define a uniform mesh over $[t_{min},t_{max}]$.

If $mesh=\text{'C'}$, the elements of $t$ are unchanged.

ffloat, ndarray, shape $(\text{ns},ntkeep)$

$f[\text{i}-1,\text{j}-1]$, for $\text{j}=1,2,\dots ,ntkeep$, for $\text{i}=1,2,\dots ,\text{ns}$, contains the value $f$ of the option at the $\text{i}$th mesh point $s[\text{i}-1]$ at time $t[\text{j}-1]$.

thetafloat, ndarray, shape $(\text{ns},ntkeep)$

The values of various Greeks at the $i$th mesh point $s[i-1]$ at time $t[j-1]$, as follows:

$$\begin{array}{c}\begin{array}{ccc}theta[i-1,j-1]=\frac{\partial f}{\partial t}\text{,}& delta[i-1,j-1]=\frac{\partial f}{\partial S}\text{,}& gamma[i-1,j-1]=\frac{{\partial }^{2}f}{\partial S^2}\text{,}\\ & & \\ lamda[i-1,j-1]=\frac{\partial f}{\partial \sigma }\text{,}& rho[i-1,j-1]=\frac{\partial f}{\partial r}\text{.}& \end{array}\end{array}$$

deltafloat, ndarray, shape $(\text{ns},ntkeep)$

The values of various Greeks at the $i$th mesh point $s[i-1]$ at time $t[j-1]$, as follows:

$$\begin{array}{c}\begin{array}{ccc}theta[i-1,j-1]=\frac{\partial f}{\partial t}\text{,}& delta[i-1,j-1]=\frac{\partial f}{\partial S}\text{,}& gamma[i-1,j-1]=\frac{{\partial }^{2}f}{\partial S^2}\text{,}\\ & & \\ lamda[i-1,j-1]=\frac{\partial f}{\partial \sigma }\text{,}& rho[i-1,j-1]=\frac{\partial f}{\partial r}\text{.}& \end{array}\end{array}$$

gammafloat, ndarray, shape $(\text{ns},ntkeep)$

The values of various Greeks at the $i$th mesh point $s[i-1]$ at time $t[j-1]$, as follows:

$$\begin{array}{c}\begin{array}{ccc}theta[i-1,j-1]=\frac{\partial f}{\partial t}\text{,}& delta[i-1,j-1]=\frac{\partial f}{\partial S}\text{,}& gamma[i-1,j-1]=\frac{{\partial }^{2}f}{\partial S^2}\text{,}\\ & & \\ lamda[i-1,j-1]=\frac{\partial f}{\partial \sigma }\text{,}& rho[i-1,j-1]=\frac{\partial f}{\partial r}\text{.}& \end{array}\end{array}$$

lamdafloat, ndarray, shape $(\text{ns},ntkeep)$

The values of various Greeks at the $i$th mesh point $s[i-1]$ at time $t[j-1]$, as follows:

$$\begin{array}{c}\begin{array}{ccc}theta[i-1,j-1]=\frac{\partial f}{\partial t}\text{,}& delta[i-1,j-1]=\frac{\partial f}{\partial S}\text{,}& gamma[i-1,j-1]=\frac{{\partial }^{2}f}{\partial S^2}\text{,}\\ & & \\ lamda[i-1,j-1]=\frac{\partial f}{\partial \sigma }\text{,}& rho[i-1,j-1]=\frac{\partial f}{\partial r}\text{.}& \end{array}\end{array}$$

rhofloat, ndarray, shape $(\text{ns},ntkeep)$

The values of various Greeks at the $i$th mesh point $s[i-1]$ at time $t[j-1]$, as follows:

$$\begin{array}{c}\begin{array}{ccc}theta[i-1,j-1]=\frac{\partial f}{\partial t}\text{,}& delta[i-1,j-1]=\frac{\partial f}{\partial S}\text{,}& gamma[i-1,j-1]=\frac{{\partial }^{2}f}{\partial S^2}\text{,}\\ & & \\ lamda[i-1,j-1]=\frac{\partial f}{\partial \sigma }\text{,}& rho[i-1,j-1]=\frac{\partial f}{\partial r}\text{.}& \end{array}\end{array}$$

Raises

NagValueError

(errno $1$)

On entry, $ntkeep=⟨value⟩$ and $\text{nt}=⟨value⟩$.

Constraint: $ntkeep\le \text{nt}$.

(errno $1$)

On entry, $ntkeep=⟨value⟩$.

Constraint: $ntkeep\ge 1$.

(errno $1$)

On entry, $alpha=⟨value⟩$.

Constraint: $alpha\le 1.0$.

(errno $1$)

On entry, $alpha=⟨value⟩$.

Constraint: $alpha\ge 0.0$.

(errno $1$)

On entry, $mesh=⟨value⟩$.

Constraint: $mesh=\text{'U'}$ or $\text{'C'}$.

(errno $1$)

On entry, $t\left[0\right]=⟨value⟩$.

Constraint: $t\left[0\right]\ge 0.0$.

(errno $1$)

On entry, $s\left[0\right]=⟨value⟩$.

Constraint: $s\left[0\right]\ge 0.0$.

(errno $1$)

On entry, $\text{nt}=⟨value⟩$.

Constraint: $\text{nt}\ge 2$.

(errno $1$)

On entry, $\text{ns}=⟨value⟩$.

Constraint: $\text{ns}\ge 2$.

(errno $1$)

On entry, $kopt=⟨value⟩$.

Constraint: $kopt=1$, $2$, $3$ or $4$.

(errno $2$)

On entry, $t[\text{nt}-1]=⟨value⟩$ and $t\left[0\right]=⟨value⟩$.

Constraint: $t[\text{nt}-1]>t\left[0\right]$.

(errno $2$)

On entry, $s[\text{ns}-1]=⟨value⟩$ and $s\left[0\right]=⟨value⟩$.

Constraint: $s[\text{ns}-1]>s\left[0\right]$.

(errno $3$)

On entry, $t\left[0\right]\le t[⟨value⟩]$.

Constraint: when $mesh=\text{'C'}$, $t[\text{i}-1]<t\left[\text{i}\right]$, for $\text{i}=1,2,\dots ,\text{nt}-1$.

(errno $3$)

On entry, $s\left[0\right]\le s[⟨value⟩]$.

Constraint: when $mesh=\text{'C'}$, $s[\text{i}-1]<s\left[\text{i}\right]$, for $\text{i}=1,2,\dots ,\text{ns}-1$.

Notes

dim1_blackscholes_fd solves the Black–Scholes equation (see Hull (1989) and Wilmott et al. (1995))

$$\frac{\partial f}{\partial t}+(r-q)S\frac{\partial f}{\partial S}+\frac{{\sigma }^2{S}^2}{2}\frac{{\partial }^{2}f}{\partial S^2}=rf$$

$$S_{min}<S<S_{max}\text{,}{t}_{min}<t<t_{max}\text{,}$$

for the value $f$ of a European or American, put or call stock option, with exercise price $X$. In equation (1) $t$ is time, $S$ is the stock price, $r$ is the risk free interest rate, $q$ is the continuous dividend, and $\sigma$ is the stock volatility. According to the values in the array $tdpar$, the arguments $r$, $q$ and $\sigma$ may each be either constant or functions of time. The function also returns values of various Greeks.

dim1_blackscholes_fd uses a finite difference method with a choice of time-stepping schemes. The method is explicit for $alpha=0.0$ and implicit for nonzero values of $alpha$. Second order time accuracy can be obtained by setting $alpha=0.5$. According to the value of the argument $mesh$ the finite difference mesh may be either uniform, or user-defined in both $S$ and $t$ directions.

References

Hull, J, 1989, Options, Futures and Other Derivative Securities, Prentice–Hall

Wilmott, P, Howison, S and Dewynne, J, 1995, The Mathematics of Financial Derivatives, Cambridge University Press