d03pp is the AD Library version of the primal routine d03ppf. Based (in the C++ interface) on overload resolution, d03pp can be used for primal, tangent and adjoint evaluation. It supports tangents and adjoints of first order.

2 Specification

Fortran Interface

Subroutine d03pp_AD_f (

ad_handle, npde, m, ts, tout, pdedef, bndary, uvinit, u, npts, x, nv, odedef, nxi, xi, neqn, rtol, atol, itol, norm, laopt, algopt, remesh, nxfix, xfix, nrmesh, dxmesh, trmesh, ipminf, xratio, con, monitf, rsave, lrsave, isave, lisave, itask, itrace, ind, iuser, ruser, cwsav, lwsav, iwsav, rwsav, ifail)

Integer, Intent (In)	::	npde, m, npts, nv, nxi, neqn, itol, nxfix, nrmesh, ipminf, lrsave, lisave, itask, itrace
Integer, Intent (Inout)	::	isave(lisave), ind, iuser(*), iwsav(505), ifail
ADTYPE, Intent (In)	::	tout, xi(nxi), rtol(), atol(), algopt(30), xfix(nxfix), dxmesh, trmesh, xratio, con
ADTYPE, Intent (Inout)	::	ts, u(neqn), x(npts), rsave(lrsave), ruser(*), rwsav(1100)
Logical, Intent (In)	::	remesh
Logical, Intent (Inout)	::	lwsav(100)
Character (1), Intent (In)	::	norm, laopt
Character (80), Intent (Inout)	::	cwsav(10)
Type (c_ptr), Intent (Inout)	::	ad_handle
External	::	pdedef, bndary, uvinit, odedef, monitf

Corresponding to the overloaded C++ function, the Fortran interface provides five routines with names reflecting the type used for active real arguments. The actual subroutine and type names are formed by replacing AD and ADTYPE in the above as follows:

when ADTYPE is	Real(kind=nag_wp)	then AD is p0w
when ADTYPE is	Type(nagad_a1w_w_rtype)	then AD is a1w
when ADTYPE is	Type(nagad_t1w_w_rtype)	then AD is t1w

C++ Header Interface

#include <dco.hpp>
#include <nagad.h>
namespace nag {
namespace ad {

void d03pp (

void *&ad_handle, const Integer &npde, const Integer &m, ADTYPE &ts, const ADTYPE &tout,
void (NAG_CALL pdedef)(void *&ad_handle, const Integer &npde, const ADTYPE &t, const ADTYPE &x, const ADTYPE u[], const ADTYPE ux[], const Integer &nv, const ADTYPE v[], const ADTYPE vdot[], ADTYPE p[], ADTYPE q[], ADTYPE r[], Integer &ires, Integer iuser[], ADTYPE ruser[]),
void (NAG_CALL bndary)(void *&ad_handle, const Integer &npde, const ADTYPE &t, const ADTYPE u[], const ADTYPE ux[], const Integer &nv, const ADTYPE v[], const ADTYPE vdot[], const Integer &ibnd, ADTYPE beta[], ADTYPE gamma[], Integer &ires, Integer iuser[], ADTYPE ruser[]),
void (NAG_CALL uvinit)(void *&ad_handle, const Integer &npde, const Integer &npts, const Integer &nxi, const ADTYPE x[], const ADTYPE xi[], ADTYPE u[], const Integer &nv, ADTYPE v[], Integer iuser[], ADTYPE ruser[]),
ADTYPE u[], const Integer &npts, ADTYPE x[], const Integer &nv,
void (NAG_CALL odedef)(void *&ad_handle, const Integer &npde, const ADTYPE &t, const Integer &nv, const ADTYPE v[], const ADTYPE vdot[], const Integer &nxi, const ADTYPE xi[], const ADTYPE ucp[], const ADTYPE ucpx[], const ADTYPE rcp[], const ADTYPE ucpt[], const ADTYPE ucptx[], ADTYPE f[], Integer &ires, Integer iuser[], ADTYPE ruser[]),
const Integer &nxi, const ADTYPE xi[], const Integer &neqn, const ADTYPE rtol[], const ADTYPE atol[], const Integer &itol, const char *norm, const char *laopt, const ADTYPE algopt[], const logical &remesh, const Integer &nxfix, const ADTYPE xfix[], const Integer &nrmesh, const ADTYPE &dxmesh, const ADTYPE &trmesh, const Integer &ipminf, const ADTYPE &xratio, const ADTYPE &con,
void (NAG_CALL monitf)(void *&ad_handle, const ADTYPE &t, const Integer &npts, const Integer &npde, const ADTYPE x[], const ADTYPE u[], const ADTYPE r[], ADTYPE fmon[], Integer iuser[], ADTYPE ruser[]),
ADTYPE rsave[], const Integer &lrsave, Integer isave[], const Integer &lisave, const Integer &itask, const Integer &itrace, Integer &ind, const Integer &liuser, Integer iuser[], const Integer &lruser, ADTYPE ruser[], char *cwsav[], logical lwsav[], Integer iwsav[], ADTYPE rwsav[], Integer &ifail)

}
}

The function is overloaded on ADTYPE which represents the type of active arguments. ADTYPE may be any of the following types:
double,
dco::ga1s<double>::type,
dco::gt1s<double>::type

Note: this function can be used with AD tools other than dco/c++. For details, please contact NAG.

3 Description

d03pp is the AD Library version of the primal routine d03ppf.

d03ppf integrates a system of linear or nonlinear parabolic partial differential equations (PDEs) in one space variable, with scope for coupled ordinary differential equations (ODEs), and automatic adaptive spatial remeshing. The spatial discretization is performed using finite differences, and the method of lines is employed to reduce the PDEs to a system of ODEs. The resulting system is solved using a Backward Differentiation Formula (BDF) method or a Theta method (switching between Newton's method and functional iteration). For further information see Section 3 in the documentation for d03ppf.

4 References

Berzins M (1990) Developments in the NAG Library software for parabolic equations Scientific Software Systems (eds J C Mason and M G Cox) 59–72 Chapman and Hall

Berzins M, Dew P M and Furzeland R M (1989) Developing software for time-dependent problems using the method of lines and differential-algebraic integrators Appl. Numer. Math. 5 375–397

Berzins M and Furzeland R M (1992) An adaptive theta method for the solution of stiff and nonstiff differential equations Appl. Numer. Math. 9 1–19

Furzeland R M (1984) The construction of adaptive space meshes TNER.85.022 Thornton Research Centre, Chester

Skeel R D and Berzins M (1990) A method for the spatial discretization of parabolic equations in one space variable SIAM J. Sci. Statist. Comput. 11(1) 1–32

5 Arguments

In addition to the arguments present in the interface of the primal routine, d03pp includes some arguments specific to AD.

A brief summary of the AD specific arguments is given below. For the remainder, links are provided to the corresponding argument from the primal routine. A tooltip popup for all arguments can be found by hovering over the argument name in Section 2 and in this section.

1: ad_handle – Pointer to AD Data Input/Output

On entry: a handle to the AD configuration data object, as created by x10aa.

2: npde – Integer Input

3: m – Integer Input

4: ts – ADTYPE Input/Output

5: tout – ADTYPE Input

6: pdedef – Subroutine External Procedure

The specification of pdedef is:

Fortran Interface

Subroutine pdedef (

ad_handle, npde, t, x, u, ux, nv, v, vdot, p, q, r, ires, iuser, ruser)

Integer, Intent (In)	::	npde, nv
Integer, Intent (Inout)	::	ires, iuser(*)
ADTYPE, Intent (In)	::	t, x, u(npde), ux(npde), v(nv), vdot(nv)
ADTYPE, Intent (Inout)	::	ruser(*)
ADTYPE, Intent (Out)	::	p(npde,npde), q(npde), r(npde)
Type (c_ptr), Intent (Inout)	::	ad_handle

C++ Header Interface

void pdedef (

void *&ad_handle, const Integer &npde, const ADTYPE &t, const ADTYPE &x, const ADTYPE u[], const ADTYPE ux[], const Integer &nv, const ADTYPE v[], const ADTYPE vdot[], ADTYPE p[], ADTYPE q[], ADTYPE r[], Integer &ires, Integer iuser[], ADTYPE ruser[])

1: ad_handle – Pointer to AD Data Input/Output: On entry: a handle to the AD configuration data object.
2: npde – Integer Input
3: t – ADTYPE Input
4: x – ADTYPE Input
5: u – ADTYPE array Input
6: ux – ADTYPE array Input
7: nv – Integer Input
8: v – ADTYPE array Input
9: vdot – ADTYPE array Input
10: p – ADTYPE array Output
11: q – ADTYPE array Output
12: r – ADTYPE array Output
13: ires – Integer Input/Output
14: iuser( $*$ ) – Integer array User Workspace
15: ruser( $*$ ) – ADTYPE array User Workspace

7: bndary – Subroutine External Procedure

The specification of bndary is:

Fortran Interface

Subroutine bndary (

ad_handle, npde, t, u, ux, nv, v, vdot, ibnd, beta, gamma, ires, iuser, ruser)

Integer, Intent (In)	::	npde, nv, ibnd
Integer, Intent (Inout)	::	ires, iuser(*)
ADTYPE, Intent (In)	::	t, u(npde), ux(npde), v(nv), vdot(nv)
ADTYPE, Intent (Inout)	::	ruser(*)
ADTYPE, Intent (Out)	::	beta(npde), gamma(npde)
Type (c_ptr), Intent (Inout)	::	ad_handle

C++ Header Interface

void bndary (

void *&ad_handle, const Integer &npde, const ADTYPE &t, const ADTYPE u[], const ADTYPE ux[], const Integer &nv, const ADTYPE v[], const ADTYPE vdot[], const Integer &ibnd, ADTYPE beta[], ADTYPE gamma[], Integer &ires, Integer iuser[], ADTYPE ruser[])

1: ad_handle – Pointer to AD Data Input/Output: On entry: a handle to the AD configuration data object.
2: npde – Integer Input
3: t – ADTYPE Input
4: u – ADTYPE array Input
5: ux – ADTYPE array Input
6: nv – Integer Input
7: v – ADTYPE array Input
8: vdot – ADTYPE array Input
9: ibnd – Integer Input
10: beta – ADTYPE array Output
11: gamma – ADTYPE array Output
12: ires – Integer Input/Output
13: iuser( $*$ ) – Integer array User Workspace
14: ruser( $*$ ) – ADTYPE array User Workspace

8: uvinit – Subroutine External Procedure

The specification of uvinit is:

Fortran Interface

Subroutine uvinit (

ad_handle, npde, npts, nxi, x, xi, u, nv, v, iuser, ruser)

Integer, Intent (In)	::	npde, npts, nxi, nv
Integer, Intent (Inout)	::	iuser(*)
ADTYPE, Intent (In)	::	x(npts), xi(nxi)
ADTYPE, Intent (Inout)	::	ruser(*)
ADTYPE, Intent (Out)	::	u(npde,npts), v(nv)
Type (c_ptr), Intent (Inout)	::	ad_handle

C++ Header Interface

void uvinit (

void *&ad_handle, const Integer &npde, const Integer &npts, const Integer &nxi, const ADTYPE x[], const ADTYPE xi[], ADTYPE u[], const Integer &nv, ADTYPE v[], Integer iuser[], ADTYPE ruser[])

1: ad_handle – Pointer to AD Data Input/Output: On entry: a handle to the AD configuration data object.
2: npde – Integer Input
3: npts – Integer Input
4: nxi – Integer Input
5: x – ADTYPE array Input
6: xi – ADTYPE array Input
7: u – ADTYPE array Output
8: nv – Integer Input
9: v – ADTYPE array Output
10: iuser( $*$ ) – Integer array User Workspace
11: ruser( $*$ ) – ADTYPE array User Workspace

9: u(neqn) – ADTYPE array Input/Output

10: npts – Integer Input

11: x(npts) – ADTYPE array Input/Output

12: nv – Integer Input

13: odedef – Subroutine External Procedure

If a null pointer is used as the argument, then a NAG supplied routine will be used as the argument for this parameter (C++ only). For the Fortran interface, the NAG supplied routine d03pc_AD_k may be used as the actual argument for this parameter.

The specification of odedef is:

Fortran Interface

Subroutine odedef (

ad_handle, npde, t, nv, v, vdot, nxi, xi, ucp, ucpx, rcp, ucpt, ucptx, f, ires, iuser, ruser)

Integer, Intent (In)	::	npde, nv, nxi
Integer, Intent (Inout)	::	ires, iuser(*)
ADTYPE, Intent (In)	::	t, v(nv), vdot(nv), xi(nxi), ucp(npde,nxi), ucpx(npde,nxi), rcp(npde,nxi), ucpt(npde,nxi), ucptx(npde,nxi)
ADTYPE, Intent (Inout)	::	ruser(*)
ADTYPE, Intent (Out)	::	f(nv)
Type (c_ptr), Intent (Inout)	::	ad_handle

C++ Header Interface

void odedef (

void *&ad_handle, const Integer &npde, const ADTYPE &t, const Integer &nv, const ADTYPE v[], const ADTYPE vdot[], const Integer &nxi, const ADTYPE xi[], const ADTYPE ucp[], const ADTYPE ucpx[], const ADTYPE rcp[], const ADTYPE ucpt[], const ADTYPE ucptx[], ADTYPE f[], Integer &ires, Integer iuser[], ADTYPE ruser[])

1: ad_handle – Pointer to AD Data Input/Output: On entry: a handle to the AD configuration data object.
2: npde – Integer Input
3: t – ADTYPE Input
4: nv – Integer Input
5: v – ADTYPE array Input
6: vdot – ADTYPE array Input
7: nxi – Integer Input
8: xi – ADTYPE array Input
9: ucp – ADTYPE array Input
10: ucpx – ADTYPE array Input
11: rcp – ADTYPE array Input
12: ucpt – ADTYPE array Input
13: ucptx – ADTYPE array Input
14: f – ADTYPE array Output
15: ires – Integer Input/Output
16: iuser( $*$ ) – Integer array User Workspace
17: ruser( $*$ ) – ADTYPE array User Workspace

14: nxi – Integer Input

15: xi(nxi) – ADTYPE array Input

16: neqn – Integer Input

17: rtol( $*$ ) – ADTYPE array Input

18: atol( $*$ ) – ADTYPE array Input

19: itol – Integer Input

20: norm – character Input

21: laopt – character Input

22: algopt( $30$ ) – ADTYPE array Input

23: remesh – logical Input

24: nxfix – Integer Input

25: xfix(nxfix) – ADTYPE array Input

26: nrmesh – Integer Input

27: dxmesh – ADTYPE Input

28: trmesh – ADTYPE Input

29: ipminf – Integer Input

30: xratio – ADTYPE Input

31: con – ADTYPE Input

32: monitf – Subroutine External Procedure

If a null pointer is used as the argument, then a NAG supplied routine will be used as the argument for this parameter (C++ only). For the Fortran interface, the NAG supplied routine d03pc_AD_l may be used as the actual argument for this parameter.

The specification of monitf is:

Fortran Interface

Subroutine monitf (

ad_handle, t, npts, npde, x, u, r, fmon, iuser, ruser)

Integer, Intent (In)	::	npts, npde
Integer, Intent (Inout)	::	iuser(*)
ADTYPE, Intent (In)	::	t, x(npts), u(npde,npts), r(npde,npts)
ADTYPE, Intent (Inout)	::	ruser(*)
ADTYPE, Intent (Out)	::	fmon(npts)
Type (c_ptr), Intent (Inout)	::	ad_handle

C++ Header Interface

void monitf (

void *&ad_handle, const ADTYPE &t, const Integer &npts, const Integer &npde, const ADTYPE x[], const ADTYPE u[], const ADTYPE r[], ADTYPE fmon[], Integer iuser[], ADTYPE ruser[])

1: ad_handle – Pointer to AD Data Input/Output: On entry: a handle to the AD configuration data object.
2: t – ADTYPE Input
3: npts – Integer Input
4: npde – Integer Input
5: x – ADTYPE array Input
6: u – ADTYPE array Input
7: r – ADTYPE array Input
8: fmon – ADTYPE array Output
9: iuser( $*$ ) – Integer array User Workspace
10: ruser( $*$ ) – ADTYPE array User Workspace

33: rsave(lrsave) – ADTYPE array Communication Array

34: lrsave – Integer Input

35: isave(lisave) – Integer array Communication Array

36: lisave – Integer Input

37: itask – Integer Input

38: itrace – Integer Input

39: ind – Integer Input/Output

40: liuser Input

User workspace dimension (C++ only), see x10af to specify the dimension from Fortran.

41: iuser( $*$ ) – Integer array User Workspace

User workspace.

42: lruser Input

User workspace dimension (C++ only), see x10ae to specify the dimension from Fortran.

43: ruser( $*$ ) – ADTYPE array User Workspace

User workspace.

44: cwsav( $10$ ) – character array Communication Array

ind = 0

, cwsav, lwsav, iwsav and rwsav need not be set on entry.

45: lwsav( $100$ ) – logical array Communication Array

ind = 0

, cwsav, lwsav, iwsav and rwsav need not be set on entry.

46: iwsav( $505$ ) – Integer array Communication Array

ind = 0

, cwsav, lwsav, iwsav and rwsav need not be set on entry.

47: rwsav( $1100$ ) – ADTYPE array Communication Array

ind = 0

, cwsav, lwsav, iwsav and rwsav need not be set on entry.

48: ifail – Integer Input/Output

6 Error Indicators and Warnings

d03pp preserves all error codes from d03ppf and in addition can return:

$ifail = - 89$: An unexpected AD error has been triggered by this routine. Please contact NAG.
See Section 4.8.2 in the NAG AD Library Introduction for further information.

$ifail = - 199$: The routine was called using a mode that has not yet been implemented.

$ifail = - 443$: On entry: ad_handle is nullptr.
This check is only made if the overloaded C++ interface is used with arguments not of type double.

$ifail = - 444$: A C++ exception was thrown.
The error message will show the details of the C++ exception text.

$ifail = - 899$: Dynamic memory allocation failed for AD.
See Section 4.8.1 in the NAG AD Library Introduction for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

d03pp is not threaded in any implementation.

9 Further Comments

None.

10 Example

The following examples are variants of the example for d03ppf, modified to demonstrate calling the NAG AD Library.

Description of the primal example.

This example uses Burgers Equation, a common test problem for remeshing algorithms, given by

\frac{\partial U}{\partial t} = - U \frac{\partial U}{\partial x} + E \frac{\partial^{2} U}{\partial x^{2}},

for

x \in [0, 1]

and

t \in [0, 1]

, where

E

is a small constant.

The initial and boundary conditions are given by the exact solution

U (x, t) = \frac{0.1 \exp (- A) + 0.5 \exp (- B) + \exp (- C)}{\exp (- A) + \exp (- B) + \exp (- C)},

where

\begin{aligned} A & = \frac{50}{E} (x - 0.5 + 4.95 t), \\ B & = \frac{250}{E} (x - 0.5 + 0.75 t), \\ C & = \frac{500}{E} (x - 0.375) . \end{aligned}

10.1 Adjoint modes

Language	Source File	Data	Results
Fortran	d03pp_a1w_fe.f90	d03pp_a1w_fe.d	d03pp_a1w_fe.r

10.2 Tangent modes

Language	Source File	Data	Results
Fortran	d03pp_t1w_fe.f90	d03pp_t1w_fe.d	d03pp_t1w_fe.r

10.3 Passive mode

Language	Source File	Data	Results
Fortran	d03pp_p0w_fe.f90	d03pp_p0w_fe.d	d03pp_p0w_fe.r

NAG Library Manual, Mark 27.2

Interfaces: FL CL CPP AD

NAG AD Library Introduction

D03 (Pde) Chapter Contents

D03 (Pde) Chapter Introduction (FL)

d03pp: FL CL CPP AD

NAG AD Libraryd03pp (dim1_parab_remesh_fd)

▸▿ 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

10 Example

10.1 Adjoint modes

10.2 Tangent modes

10.3 Passive mode

NAG AD Library
d03pp (dim1_parab_remesh_fd)