NAG Library Function Document

nag_pde_bs_1d (d03ncc)

nag_pde_bs_1d (Nag_OptionType kopt, double x, Nag_MeshType mesh, Integer ns, double s[], Integer nt, double t[], const Nag_Boolean tdpar[], const double r[], const double q[], const double sigma[], double alpha, Integer ntkeep, double f[], double theta[], double delta[], double gamma[], double lambda[], double rho[], NagError *fail)

3 Description

nag_pde_bs_1d (d03ncc) 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{σ^{2} S^{2}}{2} \frac{\partial^{2} f}{\partial S^{2}} = r f

(1)

S_{\min} < S < S_{\max}, t_{\min} < t < t_{\max},

(2)

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

σ

is the stock volatility. According to the values in the array tdpar, the arguments

r

q

and

σ

may each be either constant or functions of time. The function also returns values of various Greeks.

nag_pde_bs_1d (d03ncc) 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.

4 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

5 Arguments

1: $kopt$ – Nag_OptionTypeInput

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

$kopt = Nag_EuropeanCall$: A European call option.
$kopt = Nag_AmericanCall$: An American call option.
$kopt = Nag_EuropeanPut$: A European put option.
$kopt = Nag_AmericanPut$: An American put option.

Constraint:

kopt = Nag_EuropeanCall

Nag_AmericanCall

Nag_EuropeanPut

Nag_AmericanPut

2: $x$ – doubleInput

On entry: the exercise price

X

3: $mesh$ – Nag_MeshTypeInput

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

$mesh = Nag_UniformMesh$: Uniform mesh.
$mesh = Nag_CustomMesh$: Custom mesh supplied by you.

Constraint:

mesh = Nag_UniformMesh

Nag_CustomMesh

4: $ns$ – IntegerInput

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

Constraint:

ns \geq 2

5: $s [ns]$ – doubleInput/Output

On entry: if

mesh = Nag_CustomMesh

s [i - 1]

must contain the

i

th stock price in the mesh, for

i = 1, 2, \dots, ns

. These values should be in increasing order, with

s [0] = S_{\min}

and

s [ns - 1] = S_{\max}

mesh = Nag_UniformMesh

s [0]

must be set to

S_{\min}

and

s [ns - 1]

S_{\max}

, but

s [1], s [2], \dots, s [ns - 2]

need not be initialized, as they will be set internally by the function in order to define a uniform mesh.

On exit: if

mesh = Nag_UniformMesh

, the elements of s define a uniform mesh over

[S_{\min}, S_{\max}]

mesh = Nag_CustomMesh

, the elements of s are unchanged.

Constraints:

if $mesh = Nag_CustomMesh$ , $s [0] \geq 0.0$ and $s [i - 1] < s [i]$ , for $i = 1, 2, \dots, ns - 1$ ;
if $mesh = Nag_UniformMesh$ , $0.0 \leq s [0] < s [ns - 1]$ .

6: $nt$ – IntegerInput

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

Constraint:

nt \geq 2

7: $t [nt]$ – doubleInput/Output

On entry: if

mesh = Nag_CustomMesh

then

t [j - 1]

must contain the

j

th time in the mesh, for

j = 1, 2, \dots, nt

. These values should be in increasing order, with

t [0] = t_{\min}

and

t [nt - 1] = t_{\max}

mesh = Nag_UniformMesh

then

t [0]

must be set to

t_{\min}

and

t [nt - 1]

t_{\max}

, but

t [1], t [2], \dots, t [nt - 2]

need not be initialized, as they will be set internally by the function in order to define a uniform mesh.

On exit: if

mesh = Nag_UniformMesh

, the elements of t define a uniform mesh over

[t_{\min}, t_{\max}]

mesh = Nag_CustomMesh

, the elements of t are unchanged.

Constraints:

if $mesh = Nag_CustomMesh$ , $t [0] \geq 0.0$ and $t [j - 1] < t [j]$ , for $j = 1, 2, \dots, nt - 1$ ;
if $mesh = Nag_UniformMesh$ , $0.0 \leq t [0] < t [nt - 1]$ .

8: $tdpar [3]$ – const Nag_BooleanInput

On entry: specifies whether or not various arguments are time-dependent. More precisely,

r

is time-dependent if

tdpar [0] = Nag_TRUE

and constant otherwise. Similarly,

tdpar [1]

specifies whether

q

is time-dependent and

tdpar [2]

specifies whether

σ

is time-dependent.

9: $r [\dim]$ – const doubleInput

Note: the dimension, dim, of the array r must be at least

$nt$ when $tdpar [0] = Nag_TRUE$ ;
$1$ otherwise.

On entry: if

tdpar [0] = Nag_TRUE

then

r [j - 1]

must contain the value of the risk-free interest rate

r (t)

at the

j

th time in the mesh, for

j = 1, 2, \dots, nt

tdpar [0] = Nag_FALSE

then

r [0]

must contain the constant value of the risk-free interest rate

r

. The remaining elements need not be set.

10: $q [\dim]$ – const doubleInput

Note: the dimension, dim, of the array q must be at least

$nt$ when $tdpar [1] = Nag_TRUE$ ;
$1$ otherwise.

On entry: if

tdpar [1] = Nag_TRUE

then

q [j - 1]

must contain the value of the continuous dividend

q (t)

at the

j

th time in the mesh, for

j = 1, 2, \dots, nt

tdpar [1] = Nag_FALSE

then

q [0]

must contain the constant value of the continuous dividend

q

. The remaining elements need not be set.

11: $sigma [\dim]$ – const doubleInput

Note: the dimension, dim, of the array sigma must be at least

$nt$ when $tdpar [2] = Nag_TRUE$ ;
$1$ otherwise.

On entry: if

tdpar [2] = Nag_TRUE

then

sigma [j - 1]

must contain the value of the volatility

σ (t)

at the

j

th time in the mesh, for

j = 1, 2, \dots, nt

tdpar [2] = Nag_FALSE

then

sigma [0]

must contain the constant value of the volatility

σ

. The remaining elements need not be set.

12: $alpha$ – doubleInput

On entry: the value of

λ

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.

Suggested value:

alpha = 0.55

Constraint:

0.0 \leq alpha \leq 1.0

13: $ntkeep$ – IntegerInput

On entry: the number of solutions to be stored in the time direction. The function calculates the solution backwards from

t [nt - 1]

t [0]

at all times in the mesh. These time solutions and the corresponding Greeks will be stored at times

t [i - 1]

, for

i = 1, 2, \dots, ntkeep

, in the arrays f, theta, delta, gamma, lambda and rho. Other time solutions will be discarded. To store all time solutions set

ntkeep = nt

Constraint:

1 \leq ntkeep \leq nt

14: $f [ns \times ntkeep]$ – doubleOutput

On exit:

f [ns \times (j - 1) + i - 1]

, for

i = 1, 2, \dots, ns

and

j = 1, 2, \dots, ntkeep

, contains the value

f

of the option at the

i

th mesh point

s [i - 1]

at time

t [j - 1]

15: $theta [ns \times ntkeep]$ – doubleOutput

16: $delta [ns \times ntkeep]$ – doubleOutput

17: $gamma [ns \times ntkeep]$ – doubleOutput

18: $lambda [ns \times ntkeep]$ – doubleOutput

19: $rho [ns \times ntkeep]$ – doubleOutput

On exit: the values of various Greeks at the

i

th mesh point

s [i - 1]

at time

t [j - 1]

, as follows:

\begin{array}{l} theta [ns \times (j - 1) + i - 1] = \frac{\partial f}{\partial t}, & delta [ns \times (j - 1) + i - 1] = \frac{\partial f}{\partial S}, & gamma [ns \times (j - 1) + i - 1] = \frac{\partial^{2} f}{\partial S^{2}}, \\ lambda [ns \times (j - 1) + i - 1] = \frac{\partial f}{\partial σ}, & rho [ns \times (j - 1) + i - 1] = \frac{\partial f}{\partial r} . \end{array}

20: $fail$ – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
See Section 3.2.1.2 in the Essential Introduction for further information.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_INT: On entry, $ns = 〈value〉$ .
Constraint: $ns \geq 2$ .

On entry, $nt = 〈value〉$ .
Constraint: $nt \geq 2$ .

On entry, $ntkeep = 〈value〉$ .
Constraint: $ntkeep \geq 1$ .
NE_INT_2: On entry, $ntkeep = 〈value〉$ and $nt = 〈value〉$ .
Constraint: $ntkeep \leq nt$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.
NE_NO_LICENCE: Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.
NE_NOT_STRICTLY_INCREASING: On entry, $s [I] \leq s [I - 1]$ in custom mesh: $I = 〈value〉$ .

On entry, $t [J] \leq t [J - 1]$ in custom mesh: $J = 〈value〉$ .
NE_REAL: On entry, $alpha = 〈value〉$ .
Constraint: $alpha \leq 1.0$ .

On entry, $alpha = 〈value〉$ .
Constraint: $alpha \geq 0.0$ .

On entry, $s [0] < 0.0$ : $s [0] = 〈value〉$ .

On entry, $t [0] < 0.0$ : $t [0] = 〈value〉$ .
NE_REAL_2: On entry, $s [ns - 1] = 〈value〉$ and $s [0] = 〈value〉$ .
Constraint: $s [ns - 1] > s [0]$ .

On entry, $t [nt - 1] = 〈value〉$ and $t [0] = 〈value〉$ .
Constraint: $t [nt - 1] > t [0]$ .

7 Accuracy

The accuracy of the solution

f

and the various derivatives returned by the function is dependent on the values of ns and nt supplied, the distribution of the mesh points, and the value of alpha chosen. For most choices of alpha the solution has a truncation error which is second-order accurate in

S

and first order accurate in

t

. For

alpha = 0.5

the truncation error is also second-order accurate in

t

The simplest approach to improving the accuracy is to increase the values of both ns and nt.

8 Parallelism and Performance

nag_pde_bs_1d (d03ncc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.

nag_pde_bs_1d (d03ncc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

9.1 Timing

Each time-step requires the construction and solution of a tridiagonal system of linear equations. To calculate each of the derivatives lambda and rho requires a repetition of the entire solution process. The time taken for a call to the function is therefore proportional to

ns \times nt

9.2 Algorithmic Details

nag_pde_bs_1d (d03ncc) solves equation (1) using a finite difference method. The solution is computed backwards in time from

t_{\max}

t_{\min}

using a

λ

scheme, which is implicit for all nonzero values of

λ

, and is unconditionally stable for values of

λ > 0.5

. For each time-step a tridiagonal system is constructed and solved to obtain the solution at the earlier time. For the explicit scheme (

λ = 0

) this tridiagonal system degenerates to a diagonal matrix and is solved trivially. For American options the solution at each time-step is inspected to check whether early exercise is beneficial, and amended accordingly.

To compute the arrays lambda and rho, which are derivatives of the stock value

f

with respect to the problem arguments

σ

and

r

respectively, the entire solution process is repeated with perturbed values of these arguments.

10 Example

This example, taken from Hull (1989), solves the one-dimensional Black–Scholes equation for valuation of a

5

-month American put option on a non-dividend-paying stock with an exercise price of $50. The risk-free interest rate is 10% per annum, and the stock volatility is 40% per annum.

A fully implicit backward Euler scheme is used, with a mesh of

20

stock price intervals and

10

time intervals.

NAG Library Function Documentnag_pde_bs_1d (d03ncc)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

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

NAG Library Function Document

nag_pde_bs_1d (d03ncc)