NAG Toolbox: nag_ode_ivp_adams_rootdiag (d02qy)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{neqg}$ – int64int32nag_int scalar

The number of event functions defined for the integration function. It must be the same argument neqg supplied to the setup function nag_ode_ivp_adams_setup (d02qw) and to the integration function (nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg)).

2:     $\mathrm{rwork}\left(\mathit{lrwork}\right)$ – double array

This must be the same argument rwork as supplied to nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg). It is used to pass information from the integration function to nag_ode_ivp_adams_rootdiag (d02qy) and therefore the contents of this array must not be changed before calling nag_ode_ivp_adams_rootdiag (d02qy).

3:     $\mathrm{iwork}\left(\mathit{liwork}\right)$ – int64int32nag_int array

This must be the same argument iwork as supplied to nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg). It is used to pass information from the integration function to nag_ode_ivp_adams_rootdiag (d02qy) and therefore the contents of this array must not be changed before calling nag_ode_ivp_adams_rootdiag (d02qy).

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{index}$ – int64int32nag_int scalar

The index $k$ of the event equation $g_k\left(x,y,y^{\prime }\right)=0$ for which the root has been detected.

2:     $\mathrm{itype}$ – int64int32nag_int scalar

Information about the root detected for the event equation defined by index. The possible values of itype with their interpretations are as follows:

$\mathbf{itype}=1$

A simple root, or lack of distinguishing information available.

$\mathbf{itype}=2$

A root of even multiplicity is believed to have been detected, that is no change in sign of the event function was found.

$\mathbf{itype}=3$

A high-order root of odd multiplicity.

$\mathbf{itype}=4$

A possible root, but due to high multiplicity or a clustering of roots accurate evaluation of the event function was prohibited by round-off error and/or cancellation.

In general, the accuracy of the root is less reliable for values of $\mathbf{itype}>1$.

3:     $\mathrm{events}\left(\mathbf{neqg}\right)$ – int64int32nag_int array

Information about the $k$th event function on a very small interval containing the root, t (see nag_ode_ivp_adams_roots (d02qf) and nag_ode_ivp_adams_roots_revcom (d02qg)), as output from the integration function. All roots lying in this interval are considered indistinguishable numerically and therefore should be regarded as defining a root at t. The possible values of $\mathbf{events}\left(k\right)$ with their interpretations are as follows:

$\mathbf{events}\left(k\right)=0$

The $k$th event function did not have a root.

$\mathbf{events}\left(k\right)=-1$

The $k$th event function changed sign from positive to negative about a root, in the direction of integration.

$\mathbf{events}\left(k\right)=1$

The $k$th event function changed sign from negative to positive about a root, in the direction of integration.

$\mathbf{events}\left(k\right)=2$

A root was identified, but no change in sign was observed.

4:     $\mathrm{resids}\left(\mathbf{neqg}\right)$ – double array

The value of the $k$th event function computed at the root, t (see nag_ode_ivp_adams_roots (d02qf) and nag_ode_ivp_adams_roots_revcom (d02qg)).

5:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

An integration function (nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg)) has not been called, no root was detected or one or more of the arguments lrwork, liwork and neqg does not match the corresponding values supplied to nag_ode_ivp_adams_setup (d02qw). Values for the arguments index, itype, events and resids will not have been set.

This error exit may be caused by overwriting elements of iwork.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: d02qy_example

function d02qy_example


fprintf('d02qy example results\n\n');

neqf   = int64(2);
neqg   = int64(2);
vectol = true;
atol   = [1e-06;  1e-06];
rtol   = [0.0001; 0.0001];
onestp = false;
crit   = true;
tcrit  = 10;
hmax   = 0;
maxstp = int64(0);
lrwork = 23*(1+neqf) + 14*neqg;
alterg = false;
sophst = true;

lrwork = 23*(1+neqf) + 14*neqg;
rwork  = zeros(lrwork,1);
liwork = 21 + 4*neqg;
iwork  = zeros(liwork, 1, 'int64');

% Adams method setup
[statefOut, altergOut, rwork, iwork, ifail] = ...
  d02qw(...
        'Start', neqf, vectol, atol, rtol, onestp, crit, tcrit, hmax, ...
        maxstp, neqg, alterg, sophst, rwork, iwork);

% Integrate from t = 0 to 10
t    = 0;
tout = 10;
y    = [0; 1];

[t, y, root, rwork, iwork, ifail] = ...
    d02qf(...
          @fcn, t, y, tout, @g, neqg, rwork, iwork);

% Display solution and root statistics.
fprintf('Solution and root functions at t = %7.4f is:\n',t);

[index, itype, events, resids, ifail] = d02qy(neqg, rwork, iwork);

fprintf('\n y :');
fprintf('%10.4f',y);
fprintf('\n g :');
fprintf('%10.4f',resids);
fprintf('\n\nRoot Diagnostics:\n');
fprintf('  Index of event function,  k : %d\n',index);
fprintf('  Type of root                : ');
if itype==1
   fprintf('simple root\n');
elseif itype==2
   fprintf('root of even multiplicity\n');
elseif itype==3
   fprintf('root of odd multiplicity\n');
else
   fprintf('root of high multiplicity or cluster?\n');
end
fprintf('  event function sign change  : ');
if events(index)==-1
   fprintf('positive to negative\n');
elseif events(index)==1
   fprintf('negative to positive\n');
else events(index)==2
   fprintf('no change in sign\n');
end



function f = fcn(neqf, x, y)
  f=zeros(neqf,1);
  f(1)=y(2);
  f(2)=-y(1);

function result = g(neqf, x, y, yp, k)
  if (k == 1)
    result = yp(1)+0.5;
  else
    result = y(1)-sqrt(0.5);
  end

d02qy example results

Solution and root functions at t =  0.7854 is:

 y :    0.7071    0.7071
 g :    1.2071    0.0000

Root Diagnostics:
  Index of event function,  k : 2
  Type of root                : simple root
  event function sign change  : negative to positive