nag_dae_ivp_dassl_setup (d02mwc) (PDF version)
d02 Chapter Contents
d02 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_dae_ivp_dassl_setup (d02mwc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_dae_ivp_dassl_setup (d02mwc) is a setup function which must be called prior to the integrator nag_dae_ivp_dassl_gen (d02nec), if the DASSL implementation of Backward Differentiation Formulae (BDF) is to be used.

2  Specification

#include <nag.h>
#include <nagd02.h>
void  nag_dae_ivp_dassl_setup (Integer neq, Integer maxord, Nag_EvaluateJacobian jceval, double hmax, double h0, Nag_Boolean vector_tol, Integer icom[], Integer licom, double com[], Integer lcom, NagError *fail)

3  Description

This integrator setup function must be called before the first call to the integrator nag_dae_ivp_dassl_gen (d02nec). nag_dae_ivp_dassl_setup (d02mwc) permits you to define options for the DASSL integrator, such as: whether the Jacobian is to be provided or is to be approximated numerically by the integrator; the initial and maximum step-sizes for the integration; whether relative and absolute tolerances are system wide or per system equation; and the maximum order of BDF method permitted.

4  References

None.

5  Arguments

1:     neqIntegerInput
On entry: the number of differential-algebraic equations to be solved.
Constraint: neq1.
2:     maxordIntegerInput
On entry: the maximum order to be used for the BDF method. Orders up to 5th order are available; setting maxord>5 means that the maximum order used will be 5.
Constraint: 1maxord.
3:     jcevalNag_EvaluateJacobianInput
On entry: specifies the technique to be used to compute the Jacobian.
jceval=Nag_NumericalJacobian
The Jacobian is to be evaluated numerically by the integrator.
jceval=Nag_AnalyticalJacobian
You must supply a function to evaluate the Jacobian on a call to the integrator.
Constraint: jceval=Nag_NumericalJacobian or Nag_AnalyticalJacobian.
4:     hmaxdoubleInput
On entry: the maximum absolute step size to be allowed. Set hmax=0.0 if this option is not required.
Constraint: hmax0.0.
5:     h0doubleInput
On entry: the step size to be attempted on the first step. Set h0=0.0 if the initial step size is calculated internally.
6:     vector_tolNag_BooleanInput
On entry: a value to indicate the form of the local error test.
vector_tol=Nag_FALSE
rtol and atol are single element vectors.
vector_tol=Nag_TRUE
rtol and atol are vectors. This should be chosen if you want to apply different tolerances to each equation in the system.
Note: the tolerances must either both be single element vectors or both be vectors of length neq.
Constraint: vector_tol=Nag_FALSE or Nag_TRUE.
7:     icom[licom]IntegerCommunication Array
On exit: used to communicate details of the task to be carried out to the integration function nag_dae_ivp_dassl_gen (d02nec).
8:     licomIntegerInput
On entry: the dimension of the array icom.
Constraint: licomneq+50.
9:     com[lcom]doubleCommunication Array
On exit: used to communicate problem parameters to the integration function nag_dae_ivp_dassl_gen (d02nec). This must be the same communication array as the array com supplied to nag_dae_ivp_dassl_gen (d02nec). In particular, the values of hmax and h0 are contained in com.
10:   lcomIntegerInput
On entry: the dimension of the array com.
Constraints:
the array com must be large enough for the requirements of nag_dae_ivp_dassl_gen (d02nec). That is:
  • if the system Jacobian is dense, lcom 40 + maxord+4 × neq + neq2 ;
  • if the system Jacobian is banded, lcom 40 + maxord+4 × neq + 2×ml+mu+1 × neq + 2 × neq / ml + mu + 1 + 1 .
Here ml and mu are the lower and upper bandwidths respectively that are to be specified in a subsequent call to nag_dae_ivp_dassl_linalg (d02npc).
11:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_INT_ARG_GT
On entry, licom=value and neq=value.
Constraint: licom50+neq.
NE_INT_ARG_LT
On entry, maxord=value.
Constraint: maxord1.
On entry, neq=value.
Constraint: neq1.
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.
NE_REAL_ARG_LT
On entry, hmax=value.
Constraint: hmax0.0.

7  Accuracy

Not applicable.

8  Further Comments

None.

9  Example

This example solves the plane pendulum problem, defined by the following equations:
x = u y = v u = -λx v = -λy-1 x2+y2 = 1.
Differentiating the algebraic constraint once, a new algebraic constraint is obtained
xu+yv=0 .
Differentiating the algebraic constraint one more time, substituting for x, y, u, v and using x2+y2-1=0, the corresponding DAE system includes the differential equations and the algebraic equation in λ:
u2 + v2 - λ - y = 0 .
We solve the reformulated DAE system
y1 = y3 y2 = y4 y3 = -y5×y1 y4 = -y5×y2-1 y32 + y42 - y5 - y2 = 0.
For our experiments, we take consistent initial values
y10 = 1 , ​ y20 = 0 , ​ y30 = 0 , ​ y40 = 1 ​ and ​ y50 = 1
at t=0.

9.1  Program Text

Program Text (d02mwce.c)

9.2  Program Data

None.

9.3  Program Results

Program Results (d02mwce.r)


nag_dae_ivp_dassl_setup (d02mwc) (PDF version)
d02 Chapter Contents
d02 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012