NAG FL Interface
d02jbf (bvp_​coll_​sys)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

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

On entry: $n$, the order of the system of differential equations.

Constraint: $\mathbf{n}\ge 1$.

2: $\mathbf{cf}$ – real (Kind=nag_wp) Function, supplied by the user. External Procedure

cf defines the system of differential equations (see Section 3). It must return the value of a coefficient function $a_{i,j}\left(x\right)$, of $A$, at a given point $x$, or of a right-hand side function $r_i\left(x\right)$ if $\mathbf{j}=0$.

The specification of cf is:

Fortran Interface

Function cf ( i, j, x) Real (Kind=nag_wp) :: cf Integer, Intent (In) :: i, j Real (Kind=nag_wp), Intent (In) :: x

C Header Interface

double  cf_ (const Integer *i, const Integer *j, const double *x)

C++ Header Interface

#include <nag.h> extern "C" { double  cf_ (const Integer &i, const Integer &j, const double &x) }

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

2: $\mathbf{j}$ – Integer Input

On entry: indicate the function to be evaluated, namely $a_{i,j}\left(x\right)$ if $1\le \mathbf{j}\le n$, or $r_i\left(x\right)$ if $\mathbf{j}=0$.
$1\le \mathbf{i}\le n$, $0\le \mathbf{j}\le n$.

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

On entry: the point at which the function is to be evaluated.

cf must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02jbf is called. Arguments denoted as Input must not be changed by this procedure.

Note: cf should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02jbf. If your code inadvertently does return any NaNs or infinities, d02jbf is likely to produce unexpected results.

3: $\mathbf{bc}$ – Subroutine, supplied by the user. External Procedure

bc defines the $n$ boundary conditions, which have the form $y_k\left(x_0\right)=s$ or $y_k\left(x_1\right)=s$. The boundary conditions may be specified in any order.

The specification of bc is:

Fortran Interface

Subroutine bc ( i, j, rhs) Integer, Intent (In) :: i Integer, Intent (Out) :: j Real (Kind=nag_wp), Intent (Out) :: rhs

C Header Interface

void  bc_ (const Integer *i, Integer *j, double *rhs)

C++ Header Interface

#include <nag.h> extern "C" { void  bc_ (const Integer &i, Integer &j, double &rhs) }

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

On entry: the index of the boundary condition to be defined.

2: $\mathbf{j}$ – Integer Output

On exit: must be set to $-k$ if the $i$th boundary condition is $y_k\left(x_0\right)=s$, or to $+k$ if it is $y_k\left(x_1\right)=s$.

j must not be set to the same value $k$ for two different values of i.

3: $\mathbf{rhs}$ – Real (Kind=nag_wp) Output

On exit: the value $s$.

bc must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02jbf is called. Arguments denoted as Input must not be changed by this procedure.

Note: bc should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02jbf. If your code inadvertently does return any NaNs or infinities, d02jbf is likely to produce unexpected results.

4: $\mathbf{x0}$ – Real (Kind=nag_wp) Input

5: $\mathbf{x1}$ – Real (Kind=nag_wp) Input

On entry: the left- and right-hand boundaries, $x_0$ and $x_1$, respectively.

Constraint: $\mathbf{x1}>\mathbf{x0}$.

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

On entry: the number of coefficients to be returned in the Chebyshev series representation of the components of the solution (hence the degree of the polynomial approximation is $\mathbf{k1}-1$).

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

7: $\mathbf{kp}$ – Integer Input

On entry: the number of collocation points to be used.

Constraint: $\mathbf{kp}\ge \mathbf{k1}-1$.

8: $\mathbf{c}\left(\mathbf{ldc},\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: the computed Chebyshev coefficients of the $k$th component of the solution, $y_k$; that is, the computed solution is:

$$y_k=\underset{i=1}{\overset{\mathbf{k1}}{{\sum }^{\prime }}}\mathbf{c}\left(i,k\right)T_{i-1}\left(x\right)\text{, \hspace{1em}}1\le k\le n$$

where $T_i\left(x\right)$ is the $i$th Chebyshev polynomial of the first kind, and ${\sum }^{\prime }$ denotes that the first coefficient, $\mathbf{c}\left(1,k\right)$, is halved.

9: $\mathbf{ldc}$ – Integer Input

On entry: the first dimension of the array c as declared in the (sub)program from which d02jbf is called.

Constraint: $\mathbf{ldc}\ge \mathbf{k1}$.

10: $\mathbf{w}\left(\mathbf{lw}\right)$ – Real (Kind=nag_wp) array Workspace

11: $\mathbf{lw}$ – Integer Input

On entry: the dimension of the array w as declared in the (sub)program from which d02jbf is called.

Constraint: $\mathbf{lw}\ge 2\times \mathbf{n}\times \left(\mathbf{kp}+1\right)\times \left(\mathbf{n}\times \mathbf{k1}+1\right)+7\times \mathbf{n}\times \mathbf{k1}$.

12: $\mathbf{iw}\left(\mathbf{liw}\right)$ – Integer array Workspace

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

On entry: the dimension of the array iw as declared in the (sub)program from which d02jbf is called.

Constraint: $\mathbf{liw}\ge \mathbf{n}\times \left(\mathbf{k1}+2\right)$.

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

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 4 in the Introduction to the NAG Library FL Interface for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ 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{k1}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{k1}\ge 2$.

On entry, $\mathbf{kp}=〈\mathit{\text{value}}〉$ and $\mathbf{k1}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{kp}+1\ge \mathbf{k1}$.

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

On entry, $\mathbf{x1}=〈\mathit{\text{value}}〉$ and $\mathbf{x0}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{x1}>\mathbf{x0}$.

$\mathbf{ifail}=2$

On entry, $\mathbf{liw}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{liw}\ge \mathbf{n}\times \mathbf{k1}+2\times \mathbf{n}$; that is, $〈\mathit{\text{value}}〉$.

On entry, $\mathbf{lw}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lw}\ge 2\times \mathbf{n}\times \left(\mathbf{kp}+1\right)\times \left(\mathbf{n}\times \mathbf{k1}+1\right)+7\times \mathbf{n}\times \mathbf{k1}$; that is, $〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=3$

Either the boundary conditions are not linearly independent, or the coefficient matrix is rank deficient. Increasing the number of collocation points may overcome this latter problem.

$\mathbf{ifail}=4$

Iterative refinement in the least squares solution has failed to converge. The coefficient matrix is too ill-conditioned.

$\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

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results