NAG FL Interface
d03ncf (dim1_​blackscholes_​fd)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{kopt}$ – Integer Input

On entry: specifies the kind of option to be valued.

$\mathbf{kopt}=1$

A European call option.

$\mathbf{kopt}=2$

An American call option.

$\mathbf{kopt}=3$

A European put option.

$\mathbf{kopt}=4$

An American put option.

Constraint: $\mathbf{kopt}=1$, $2$, $3$ or $4$.

2: $\mathbf{x}$ – Real (Kind=nag_wp) Input

On entry: the exercise price $X$.

3: $\mathbf{mesh}$ – Character(1) Input

On entry: indicates the type of finite difference mesh to be used:

$\mathbf{mesh}=\text{'U'}$

Uniform mesh.

$\mathbf{mesh}=\text{'C'}$

Custom mesh supplied by you.

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

4: $\mathbf{ns}$ – Integer Input

On entry: the number of stock prices to be used in the finite difference mesh.

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

5: $\mathbf{s}\left(\mathbf{ns}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: if $\mathbf{mesh}=\text{'C'}$, $\mathbf{s}\left(\mathit{i}\right)$ must contain the $\mathit{i}$th stock price in the mesh, for $\mathit{i}=1,2,\dots ,\mathbf{ns}$. These values should be in increasing order, with $\mathbf{s}\left(1\right)=S_{\min }$ and $\mathbf{s}\left(\mathbf{ns}\right)=S_{\max }$.

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

On exit: if $\mathbf{mesh}=\text{'U'}$, the elements of s define a uniform mesh over $\left[S_{\min },S_{\max }\right]$.

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

Constraints:

• if $\mathbf{mesh}=\text{'C'}$, $\mathbf{s}\left(1\right)\ge 0.0$ and $\mathbf{s}\left(\mathit{i}\right)<\mathbf{s}\left(\mathit{i}+1\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{ns}-1$;
• if $\mathbf{mesh}=\text{'U'}$, $0.0\le \mathbf{s}\left(1\right)<\mathbf{s}\left(\mathbf{ns}\right)$.

6: $\mathbf{nt}$ – Integer Input

On entry: the number of time-steps to be used in the finite difference method.

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

7: $\mathbf{t}\left(\mathbf{nt}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: if $\mathbf{mesh}=\text{'C'}$ then $\mathbf{t}\left(\mathit{j}\right)$ must contain the $\mathit{j}$th time in the mesh, for $\mathit{j}=1,2,\dots ,\mathbf{nt}$. These values should be in increasing order, with $\mathbf{t}\left(1\right)=t_{\min }$ and $\mathbf{t}\left(\mathbf{nt}\right)=t_{\max }$.

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

On exit: if $\mathbf{mesh}=\text{'U'}$, the elements of t define a uniform mesh over $\left[t_{\min },t_{\max }\right]$.

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

Constraints:

• if $\mathbf{mesh}=\text{'C'}$, $\mathbf{t}\left(1\right)\ge 0.0$ and $\mathbf{t}\left(\mathit{j}\right)<\mathbf{t}\left(\mathit{j}+1\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{nt}-1$;
• if $\mathbf{mesh}=\text{'U'}$, $0.0\le \mathbf{t}\left(1\right)<\mathbf{t}\left(\mathbf{nt}\right)$.

8: $\mathbf{tdpar}\left(3\right)$ – Logical array Input

On entry: specifies whether or not various arguments are time-dependent. More precisely, $r$ is time-dependent if $\mathbf{tdpar}\left(1\right)=\mathrm{.TRUE.}$ and constant otherwise. Similarly, $\mathbf{tdpar}\left(2\right)$ specifies whether $q$ is time-dependent and $\mathbf{tdpar}\left(3\right)$ specifies whether $\sigma$ is time-dependent.

9: $\mathbf{r}\left(*\right)$ – Real (Kind=nag_wp) array Input

Note: the dimension of the array r must be at least $\mathbf{nt}$ if $\mathbf{tdpar}\left(1\right)=\mathrm{.TRUE.}$, and at least $1$ otherwise.

On entry: if $\mathbf{tdpar}\left(1\right)=\mathrm{.TRUE.}$ then $\mathbf{r}\left(\mathit{j}\right)$ must contain the value of the risk-free interest rate $r\left(t\right)$ at the $\mathit{j}$th time in the mesh, for $\mathit{j}=1,2,\dots ,\mathbf{nt}$.

If $\mathbf{tdpar}\left(1\right)=\mathrm{.FALSE.}$ then $\mathbf{r}\left(1\right)$ must contain the constant value of the risk-free interest rate $r$. The remaining elements need not be set.

10: $\mathbf{q}\left(*\right)$ – Real (Kind=nag_wp) array Input

Note: the dimension of the array q must be at least $\mathbf{nt}$ if $\mathbf{tdpar}\left(2\right)=\mathrm{.TRUE.}$, and at least $1$ otherwise.

On entry: if $\mathbf{tdpar}\left(2\right)=\mathrm{.TRUE.}$ then $\mathbf{q}\left(\mathit{j}\right)$ must contain the value of the continuous dividend $q\left(t\right)$ at the $\mathit{j}$th time in the mesh, for $\mathit{j}=1,2,\dots ,\mathbf{nt}$.

If $\mathbf{tdpar}\left(2\right)=\mathrm{.FALSE.}$ then $\mathbf{q}\left(1\right)$ must contain the constant value of the continuous dividend $q$. The remaining elements need not be set.

11: $\mathbf{sigma}\left(*\right)$ – Real (Kind=nag_wp) array Input

Note: the dimension of the array sigma must be at least $\mathbf{nt}$ if $\mathbf{tdpar}\left(3\right)=\mathrm{.TRUE.}$, and at least $1$ otherwise.

On entry: if $\mathbf{tdpar}\left(3\right)=\mathrm{.TRUE.}$ then $\mathbf{sigma}\left(\mathit{j}\right)$ must contain the value of the volatility $\sigma \left(t\right)$ at the $\mathit{j}$th time in the mesh, for $\mathit{j}=1,2,\dots ,\mathbf{nt}$.

If $\mathbf{tdpar}\left(3\right)=\mathrm{.FALSE.}$ then $\mathbf{sigma}\left(1\right)$ must contain the constant value of the volatility $\sigma$. The remaining elements need not be set.

12: $\mathbf{alpha}$ – Real (Kind=nag_wp) Input

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

$\mathbf{alpha}=0.0$

Explicit forward Euler scheme.

$\mathbf{alpha}=0.5$

Implicit Crank–Nicolson scheme.

$\mathbf{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.

Suggested value: $\mathbf{alpha}=0.55$.

Constraint: $0.0\le \mathbf{alpha}\le 1.0$.

13: $\mathbf{ntkeep}$ – Integer Input

On entry: the number of solutions to be stored in the time direction. The routine calculates the solution backwards from $\mathbf{t}\left(\mathbf{nt}\right)$ to $\mathbf{t}\left(1\right)$ at all times in the mesh. These time solutions and the corresponding Greeks will be stored at times $\mathbf{t}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{ntkeep}$, in the arrays f, theta, delta, gamma, lambda and rho. Other time solutions will be discarded. To store all time solutions set $\mathbf{ntkeep}=\mathbf{nt}$.

Constraint: $1\le \mathbf{ntkeep}\le \mathbf{nt}$.

14: $\mathbf{f}\left(\mathbf{ldf},\mathbf{ntkeep}\right)$ – Real (Kind=nag_wp) array Output

On exit: $\mathbf{f}\left(\mathit{i},\mathit{j}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{ns}$ and $\mathit{j}=1,2,\dots ,\mathbf{ntkeep}$, contains the value $f$ of the option at the $\mathit{i}$th mesh point $\mathbf{s}\left(\mathit{i}\right)$ at time $\mathbf{t}\left(\mathit{j}\right)$.

15: $\mathbf{theta}\left(\mathbf{ldf},\mathbf{ntkeep}\right)$ – Real (Kind=nag_wp) array Output

16: $\mathbf{delta}\left(\mathbf{ldf},\mathbf{ntkeep}\right)$ – Real (Kind=nag_wp) array Output

17: $\mathbf{gamma}\left(\mathbf{ldf},\mathbf{ntkeep}\right)$ – Real (Kind=nag_wp) array Output

18: $\mathbf{lambda}\left(\mathbf{ldf},\mathbf{ntkeep}\right)$ – Real (Kind=nag_wp) array Output

19: $\mathbf{rho}\left(\mathbf{ldf},\mathbf{ntkeep}\right)$ – Real (Kind=nag_wp) array Output

On exit: the values of various Greeks at the $i$th mesh point $\mathbf{s}\left(i\right)$ at time $\mathbf{t}\left(j\right)$, as follows:

$$\begin{array}{lll}\mathbf{theta}\left(i,j\right)=\frac{\partial f}{\partial t}\text{,}& \mathbf{delta}\left(i,j\right)=\frac{\partial f}{\partial S}\text{,}& \mathbf{gamma}\left(i,j\right)=\frac{{\partial }^{2}f}{\partial S^2}\text{,}\\ \\ \mathbf{lambda}\left(i,j\right)=\frac{\partial f}{\partial \sigma }\text{,}& \mathbf{rho}\left(i,j\right)=\frac{\partial f}{\partial r}\text{.}\end{array}$$

20: $\mathbf{ldf}$ – Integer Input

On entry: the first dimension of the arrays f, theta, delta, gamma, lambda and rho as declared in the (sub)program from which d03ncf is called.

Constraint: $\mathbf{ldf}\ge \mathbf{ns}$.

21: $\mathbf{work}\left(4\times \mathbf{ns}\right)$ – Real (Kind=nag_wp) array Workspace

22: $\mathbf{iwork}\left(\mathbf{ns}\right)$ – Integer array Workspace

23: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, $\mathbf{alpha}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{alpha}\le 1.0$.

On entry, $\mathbf{alpha}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{alpha}\ge 0.0$.

On entry, $\mathbf{kopt}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{kopt}=1$, $2$, $3$ or $4$.

On entry, $\mathbf{ldf}=〈\mathit{\text{value}}〉$ and $\mathbf{ns}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldf}\ge \mathbf{ns}$.

On entry, $\mathbf{mesh}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{mesh}=\text{'U'}$ or $\text{'C'}$.

On entry, $\mathbf{ns}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ns}\ge 2$.

On entry, $\mathbf{nt}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nt}\ge 2$.

On entry, $\mathbf{ntkeep}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ntkeep}\ge 1$.

On entry, $\mathbf{ntkeep}=〈\mathit{\text{value}}〉$ and $\mathbf{nt}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ntkeep}\le \mathbf{nt}$.

On entry, $\mathbf{s}\left(1\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{s}\left(1\right)\ge 0.0$.

On entry, $\mathbf{t}\left(1\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{t}\left(1\right)\ge 0.0$.

$\mathbf{ifail}=2$

On entry, $\mathbf{s}\left(\mathbf{ns}\right)=〈\mathit{\text{value}}〉$ and $\mathbf{s}\left(1\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{s}\left(\mathbf{ns}\right)>\mathbf{s}\left(1\right)$.

On entry, $\mathbf{t}\left(\mathbf{nt}\right)=〈\mathit{\text{value}}〉$ and $\mathbf{t}\left(1\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{t}\left(\mathbf{nt}\right)>\mathbf{t}\left(1\right)$.

$\mathbf{ifail}=3$

On entry, $\mathbf{s}\left(〈\mathit{\text{value}}〉+1\right)\le \mathbf{s}\left(〈\mathit{\text{value}}〉\right)$.
Constraint: when $\mathbf{mesh}=\text{'C'}$, $\mathbf{s}\left(\mathit{i}\right)<\mathbf{s}\left(\mathit{i}+1\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{ns}-1$.

On entry, $\mathbf{t}\left(〈\mathit{\text{value}}〉+1\right)\le \mathbf{t}\left(〈\mathit{\text{value}}〉\right)$.
Constraint: when $\mathbf{mesh}=\text{'C'}$, $\mathbf{t}\left(\mathit{i}\right)<\mathbf{t}\left(\mathit{i}+1\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{nt}-1$.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

9.1 Timing

9.2 Algorithmic Details

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results