NAG AD Library
d03ra (dim2_gen_order2_rectangle)

Settings help

AD Name Style:


AD Specification Language:

1 Purpose

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

2 Specification

Fortran Interface
Integer, Intent (In) :: npde, nx, ny, opti(4), lenrwk, leniwk, lenlwk, itrace
Integer, Intent (Inout) :: iwk(leniwk), ind, iuser(*), iwsav(20), ifail
ADTYPE, Intent (In) :: tout, xmin, xmax, ymin, ymax, tols, tolt, optr(3,npde)
ADTYPE, Intent (Inout) :: ts, dt(3), rwk(lenrwk), ruser(*), rwsav(25)
Logical, Intent (Inout) :: lwsav(5)
Logical, Intent (Out) :: lwk(lenlwk)
Type (c_ptr), Intent (Inout) :: ad_handle
External :: pdedef, bndary, pdeiv, monitr
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 d03ra ( void *&ad_handle, const Integer &npde, ADTYPE &ts, const ADTYPE &tout, ADTYPE dt[], const ADTYPE &xmin, const ADTYPE &xmax, const ADTYPE &ymin, const ADTYPE &ymax, const Integer &nx, const Integer &ny, const ADTYPE &tols, const ADTYPE &tolt,
void (NAG_CALL pdedef)(void *&ad_handle, const Integer &npts, const Integer &npde, const ADTYPE &t, const ADTYPE x[], const ADTYPE y[], const ADTYPE u[], const ADTYPE ut[], const ADTYPE ux[], const ADTYPE uy[], const ADTYPE uxx[], const ADTYPE uxy[], const ADTYPE uyy[], ADTYPE res[], Integer iuser[], ADTYPE ruser[]),
void (NAG_CALL bndary)(void *&ad_handle, const Integer &npts, const Integer &npde, const ADTYPE &t, const ADTYPE x[], const ADTYPE y[], const ADTYPE u[], const ADTYPE ut[], const ADTYPE ux[], const ADTYPE uy[], const Integer &nbpts, const Integer lbnd[], ADTYPE res[], Integer iuser[], ADTYPE ruser[]),
void (NAG_CALL pdeiv)(void *&ad_handle, const Integer &npts, const Integer &npde, const ADTYPE &t, const ADTYPE x[], const ADTYPE y[], ADTYPE u[], Integer iuser[], ADTYPE ruser[]),
void (NAG_CALL monitr)(void *&ad_handle, const Integer &npde, const ADTYPE &t, const ADTYPE &dt, const ADTYPE &dtnew, const logical &tlast, const Integer &nlev, const Integer ngpts[], const ADTYPE xpts[], const ADTYPE ypts[], const Integer lsol[], const ADTYPE sol[], Integer &ierr, Integer iuser[], ADTYPE ruser[]),
const Integer opti[], const ADTYPE optr[], ADTYPE rwk[], const Integer &lenrwk, Integer iwk[], const Integer &leniwk, logical lwk[], const Integer &lenlwk, const Integer &itrace, Integer &ind, const Integer &liuser, Integer iuser[], const Integer &lruser, ADTYPE ruser[], 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

d03ra is the AD Library version of the primal routine d03raf.
d03raf integrates a system of linear or nonlinear, time-dependent partial differential equations (PDEs) in two space dimensions on a rectangular domain. The method of lines is employed to reduce the PDEs to a system of ordinary differential equations (ODEs) which are solved using a backward differentiation formula (BDF) method. The resulting system of nonlinear equations is solved using a modified Newton method and a Bi-CGSTAB iterative linear solver with ILU preconditioning. Local uniform grid refinement is used to improve the accuracy of the solution. d03raf originates from the VLUGR2 package (see Blom and Verwer (1993) and Blom et al. (1996)). For further information see Section 3 in the documentation for d03raf.

4 References

Adjerid S and Flaherty J E (1988) A local refinement finite element method for two-dimensional parabolic systems SIAM J. Sci. Statist. Comput. 9 792–811
Blom J G, Trompert R A and Verwer J G (1996) Algorithm 758. VLUGR2: A vectorizable adaptive grid solver for PDEs in 2D Trans. Math. Software 22 302–328
Blom J G and Verwer J G (1993) VLUGR2: A vectorized local uniform grid refinement code for PDEs in 2D Report NM-R9306 CWI, Amsterdam
Brown P N, Hindmarsh A C and Petzold L R (1994) Using Krylov methods in the solution of large scale differential-algebraic systems SIAM J. Sci. Statist. Comput. 15 1467–1488
Trompert R A (1993) Local uniform grid refinement and systems of coupled partial differential equations Appl. Numer. Maths 12 331–355
Trompert R A and Verwer J G (1993) Analysis of the implicit Euler local uniform grid refinement method SIAM J. Sci. Comput. 14 259–278

5 Arguments

In addition to the arguments present in the interface of the primal routine, d03ra 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: tsADTYPE Input/Output
4: toutADTYPE Input
5: dt(3) – ADTYPE array Input/Output
6: xminADTYPE Input
7: xmaxADTYPE Input
8: yminADTYPE Input
9: ymaxADTYPE Input
10: nx – Integer Input
11: ny – Integer Input
12: tolsADTYPE Input
13: toltADTYPE Input
14: pdedef – Subroutine External Procedure
The specification of pdedef is:
Fortran Interface
Subroutine pdedef ( ad_handle, npts, npde, t, x, y, u, ut, ux, uy, uxx, uxy, uyy, res, iuser, ruser)
Integer, Intent (In) :: npts, npde
Integer, Intent (Inout) :: iuser(*)
ADTYPE, Intent (In) :: t, x(npts), y(npts), u(npts,npde), ut(npts,npde), ux(npts,npde), uy(npts,npde), uxx(npts,npde), uxy(npts,npde), uyy(npts,npde)
ADTYPE, Intent (Inout) :: ruser(*)
ADTYPE, Intent (Out) :: res(npts,npde)
Type (c_ptr), Intent (Inout) :: ad_handle
C++ Header Interface
void pdedef ( void *&ad_handle, const Integer &npts, const Integer &npde, const ADTYPE &t, const ADTYPE x[], const ADTYPE y[], const ADTYPE u[], const ADTYPE ut[], const ADTYPE ux[], const ADTYPE uy[], const ADTYPE uxx[], const ADTYPE uxy[], const ADTYPE uyy[], ADTYPE res[], Integer iuser[], ADTYPE ruser[])
1: ad_handle – Pointer to AD Data Input/Output
On entry: a handle to the AD configuration data object.
2: npts – Integer Input
3: npde – Integer Input
4: tADTYPE Input
5: xADTYPE array Input
6: yADTYPE array Input
7: uADTYPE array Input
8: utADTYPE array Input
9: uxADTYPE array Input
10: uyADTYPE array Input
11: uxxADTYPE array Input
12: uxyADTYPE array Input
13: uyyADTYPE array Input
14: resADTYPE array Output
15: iuser(*) – Integer array User Workspace
16: ruser(*)ADTYPE array User Workspace
15: bndary – Subroutine External Procedure
The specification of bndary is:
Fortran Interface
Subroutine bndary ( ad_handle, npts, npde, t, x, y, u, ut, ux, uy, nbpts, lbnd, res, iuser, ruser)
Integer, Intent (In) :: npts, npde, nbpts, lbnd(nbpts)
Integer, Intent (Inout) :: iuser(*)
ADTYPE, Intent (In) :: t, x(npts), y(npts), u(npts,npde), ut(npts,npde), ux(npts,npde), uy(npts,npde)
ADTYPE, Intent (Inout) :: res(npts,npde), ruser(*)
Type (c_ptr), Intent (Inout) :: ad_handle
C++ Header Interface
void bndary ( void *&ad_handle, const Integer &npts, const Integer &npde, const ADTYPE &t, const ADTYPE x[], const ADTYPE y[], const ADTYPE u[], const ADTYPE ut[], const ADTYPE ux[], const ADTYPE uy[], const Integer &nbpts, const Integer lbnd[], ADTYPE res[], Integer iuser[], ADTYPE ruser[])
1: ad_handle – Pointer to AD Data Input/Output
On entry: a handle to the AD configuration data object.
2: npts – Integer Input
3: npde – Integer Input
4: tADTYPE Input
5: xADTYPE array Input
6: yADTYPE array Input
7: uADTYPE array Input
8: utADTYPE array Input
9: uxADTYPE array Input
10: uyADTYPE array Input
11: nbpts – Integer Input
12: lbnd – Integer array Input
13: resADTYPE array Input/Output
14: iuser(*) – Integer array User Workspace
15: ruser(*)ADTYPE array User Workspace
16: pdeiv – Subroutine External Procedure
The specification of pdeiv is:
Fortran Interface
Subroutine pdeiv ( ad_handle, npts, npde, t, x, y, u, iuser, ruser)
Integer, Intent (In) :: npts, npde
Integer, Intent (Inout) :: iuser(*)
ADTYPE, Intent (In) :: t, x(npts), y(npts)
ADTYPE, Intent (Inout) :: ruser(*)
ADTYPE, Intent (Out) :: u(npts,npde)
Type (c_ptr), Intent (Inout) :: ad_handle
C++ Header Interface
void pdeiv ( void *&ad_handle, const Integer &npts, const Integer &npde, const ADTYPE &t, const ADTYPE x[], const ADTYPE y[], ADTYPE u[], Integer iuser[], ADTYPE ruser[])
1: ad_handle – Pointer to AD Data Input/Output
On entry: a handle to the AD configuration data object.
2: npts – Integer Input
3: npde – Integer Input
4: tADTYPE Input
5: xADTYPE array Input
6: yADTYPE array Input
7: uADTYPE array Output
8: iuser(*) – Integer array User Workspace
9: ruser(*)ADTYPE array User Workspace
17: monitr – Subroutine External Procedure
The specification of monitr is:
Fortran Interface
Subroutine monitr ( ad_handle, npde, t, dt, dtnew, tlast, nlev, ngpts, xpts, ypts, lsol, sol, ierr, iuser, ruser)
Integer, Intent (In) :: npde, nlev, ngpts(nlev), lsol(nlev)
Integer, Intent (Inout) :: ierr, iuser(*)
ADTYPE, Intent (In) :: t, dt, dtnew, xpts(*), ypts(*), sol(*)
ADTYPE, Intent (Inout) :: ruser(*)
Logical, Intent (In) :: tlast
Type (c_ptr), Intent (Inout) :: ad_handle
C++ Header Interface
void monitr ( void *&ad_handle, const Integer &npde, const ADTYPE &t, const ADTYPE &dt, const ADTYPE &dtnew, const logical &tlast, const Integer &nlev, const Integer ngpts[], const ADTYPE xpts[], const ADTYPE ypts[], const Integer lsol[], const ADTYPE sol[], Integer &ierr, 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: tADTYPE Input
4: dtADTYPE Input
5: dtnewADTYPE Input
6: tlast – logical Input
7: nlev – Integer Input
8: ngpts – Integer array Input
9: xptsADTYPE array Input
10: yptsADTYPE array Input
11: lsol – Integer array Input
12: solADTYPE array Input
13: ierr – Integer Input/Output
14: iuser(*) – Integer array User Workspace
15: ruser(*)ADTYPE array User Workspace
18: opti(4) – Integer array Input
19: optr(3, npde) – ADTYPE array Input
20: rwk(lenrwk) – ADTYPE array Communication Array
21: lenrwk – Integer Input
22: iwk(leniwk) – Integer array Communication Array
23: leniwk – Integer Input
24: lwk(lenlwk) – logical array Workspace
25: lenlwk – Integer Input
26: itrace – Integer Input
27: ind – Integer Input/Output
28: liuser Input
User workspace dimension (C++ only), see x10af to specify the dimension from Fortran.
29: iuser(*) – Integer array User Workspace
User workspace.
30: lruser Input
User workspace dimension (C++ only), see x10ae to specify the dimension from Fortran.
31: ruser(*) – ADTYPE array User Workspace
User workspace.
32: lwsav(5) – logical array Communication Array
Communication Array.
33: iwsav(20) – Integer array Communication Array
Communication Array.
34: rwsav(25) – ADTYPE array Communication Array
Communication Array.
35: ifail – Integer Input/Output

6 Error Indicators and Warnings

d03ra preserves all error codes from d03raf 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

d03ra is not threaded in any implementation.

9 Further Comments

None.

10 Example

The following examples are variants of the example for d03raf, modified to demonstrate calling the NAG AD Library.
Description of the primal example.
For this routine two examples are presented, with a main program and two example problems given in Example 1 (EX1) and Example 2 (EX2).
Example 1 (EX1)
This example stems from combustion theory and is a model for a single, one-step reaction of a mixture of two chemicals (see Adjerid and Flaherty (1988)). The PDE for the temperature of the mixture u is
u t =d ( 2u x2 + 2u y2 )+D(1+α-u) exp(-δu)  
for 0x,y1 and t0, with initial conditions u(x,y,0)=1 for 0x,y1, and boundary conditions
ux (0,y,t) = 0, u (1,y,t) = 1   for ​ 0y1,  
uy (x,0,t) = 0, u (x,1,t) = 1   for ​ 0x 1.  
The heat release argument α=1, the Damkohler number D=Rexp(δ)/(αδ), the activation energy δ=20, the reaction rate R=5, and the diffusion argument d=0.1.
For small times the temperature gradually increases in a circular region about the origin, and at about t=0.24 ‘ignition’ occurs causing the temperature to suddenly jump from near unity to 1+α, and a reaction front forms and propagates outwards, becoming steeper. Thus during the solution, just one grid level is used up to the ignition point, then two levels, and then three as the reaction front steepens.
Example 2 (EX2)
This example is taken from a multispecies food web model, in which predator-prey relationships in a spatial domain are simulated (see Brown et al. (1994)). In this example there is just one species each of prey and predator, and the two PDEs for the concentrations c1 and c2 of the prey and the predator respectively are
c1 t =c1(b1+a11c1+a12c2)+d1 ( 2c1 x2 + 2c1 y2 ) ,  
0=c2 (b2+a21c1+a22c2)+d2 ( 2 c2 x2 + 2 c2 y2 ) ,  
with
a11=a22=−1, a12=-0.5×10−6, and a21=104, and b1=1+αxy+βsin(4πx)sin(4πy),  
where α=50 and β=300, and b2=-b1.
The initial conditions are taken to be simple peaked functions which satisfy the boundary conditions and very nearly satisfy the PDEs:
c1=10+(16x(1-x)y(1-y))2,  
c2=b2+a21c1,  
and the boundary conditions are of Neumann type, i.e., zero normal derivatives everywhere.
During the solution a number of peaks and troughs develop across the domain, and so the number of levels required increases with time. Since the solution varies rapidly in space across the whole of the domain, refinement at intermediate levels tends to occur at all points of the domain.

10.1 Adjoint modes

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

10.2 Tangent modes

None.

10.3 Passive mode

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