naginterfaces.library.ode.ivp_​adams_​setup

naginterfaces.library.ode.ivp_adams_setup(statef, neqf, vectol, atol, rtol, onestp, crit, tcrit, hmax, maxstp, neqg, alterg, sophst, comm)

ivp_adams_setup is a setup function which must be called prior to the first call of either of the integrators ivp_adams_roots() and ivp_adams_roots_revcom() and may be called prior to any continuation call to these functions.

For full information please refer to the NAG Library document for d02qw

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/d02/d02qwf.html

Parameters

statefstr, length 1

Specifies whether the integration function (ivp_adams_roots() or ivp_adams_roots_revcom()) is to start a new system of ordinary differential equations, restart a system or continue with a system.

$statef=\text{'S'}$

Start integration with a new differential system.

$statef=\text{'R'}$

Restart integration with the current differential system.

$statef=\text{'C'}$

Continue integration with the current differential system.

neqfint

The number of ordinary differential equations to be solved by the integration function. $neqf$ must remain unchanged on subsequent calls to ivp_adams_setup with $statef=\text{'C'}$ or $\text{'R'}$.

vectolbool

Specifies whether vector or scalar error control is to be employed for the local error test in the integration.

If $vectol=True$, vector error control will be used and you must specify values of $rtol[\text{i}-1]$ and $atol[\text{i}-1]$, for $\text{i}=1,2,\dots ,neqf$.

Otherwise scalar error control will be used and you must specify values of just $rtol\left[0\right]$ and $atol\left[0\right]$.

The error test to be satisfied is of the form

$$\sqrt{\sum _{i=1}^{neqf}{\left(\frac{e_i}{w_i}\right)}^2}\le 1.0\text{.}$$

where $w_i$ is defined as follows:

$vectol$	$w_i$
$True$	$rtol[i-1]\times \left|y_i\right|+atol[i-1]$
$False$	$rtol\left[0\right]\times \left|y_i\right|+atol\left[0\right]$

and $e_i$ is an estimate of the local error in $y_i$, computed internally. $vectol$ must remain unchanged on subsequent calls to ivp_adams_setup with $statef=\text{'C'}$ or $\text{'R'}$.

atolfloat, array-like, shape $\left(\text{latol}\right)$

The absolute local error tolerance (see $vectol$).

rtolfloat, array-like, shape $\left(\text{lrtol}\right)$

The relative local error tolerance (see $vectol$).

onestpbool

The mode of operation of the integration function. If $onestp=True$, the integration function will operate in one-step mode, that is it will return after each successful step. Otherwise the integration function will operate in interval mode, that is it will return at the end of the integration interval.

critbool

Specifies whether or not there is a value for the independent variable beyond which integration is not to be attempted. Setting $crit=True$ indicates that there is such a point, whereas $crit=False$ indicates that there is no such restriction.

tcritfloat

With $crit=True$, $tcrit$ must be set to a value of the independent variable beyond which integration is not to be attempted. Otherwise $tcrit$ is not referenced.

hmaxfloat

If $hmax\ne 0.0$, a bound on the absolute step size during the integration is taken to be $\left|hmax\right|$.

If $hmax=0.0$, no bound is assumed on the step size during the integration.

A bound may be required if there are features of the solution on very short ranges of integration which may be missed.

You should try $hmax=0.0$ first.

Note: this argument only affects the step size if the option $crit=True$ is being used.

maxstpint

A bound on the number of attempted steps in any one call to the integration function. If $maxstp\le 0$ on entry, a value of $1000$ is used.

neqgint

Specifies whether or not root-finding is required in ivp_adams_roots() or ivp_adams_roots_revcom().

$neqg\le 0$

No root-finding is attempted.

$neqg>0$

Root-finding is required and $neqg$ event functions will be specified for the integration function.

altergbool

Specifies whether or not the event functions have been redefined. $alterg$ need not be set if $statef=\text{'S'}$. On subsequent calls to ivp_adams_setup, if $neqg$ has been set positive, $alterg=False$ specifies that the event functions remain unchanged, whereas $alterg=True$ specifies that the event functions have changed. Because of the expense in reinitializing the root searching procedure, $alterg$ should be set to $True$ only if the event functions really have been altered. $alterg$ need not be set if the root-finding option is not used.

sophstbool

The type of search technique to be used in the root-finding. If $sophst=True$ then a sophisticated and reliable but expensive technique will be used, whereas for $sophst=False$ a simple but less reliable technique will be used. If $neqg\le 0$, $sophst$ is not referenced.

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

Returns

statefstr, length 1

Is set to ‘C’, except that if an error is detected, $statef$ is unchanged.

altergbool

Is set to $False$.

Raises

NagValueError

(errno $1$)

On entry, $statef=⟨value⟩$.

Constraint: $statef=\text{'S'}$, $\text{'R'}$ or $\text{'C'}$.

(errno $1$)

On entry, for $i=⟨value⟩$, $atol\left[i\right]=0.0$, $rtol\left[i\right]=⟨value⟩$ and $4\times \text{eps}=⟨value⟩$.

Constraint: if $atol\left[i\right]=0.0$ then $rtol\left[i\right]\ge 4\times \text{eps}$ for all $i$.

(errno $1$)

On entry, $rtol[⟨value⟩]=⟨value⟩$.

Constraint: $rtol\left[i\right]\ge 0.0$ for all $i$.

(errno $1$)

On entry, $atol[⟨value⟩]=⟨value⟩$.

Constraint: $atol\left[i\right]\ge 0.0$ for all $i$.

(errno $1$)

On entry, $statef=\text{'R'}$ or $\text{'C'}$, $alterg=False$ and $neqg=⟨value⟩$.

Constraint: if $statef=\text{'R'}$ or $\text{'C'}$ and $alterg=False$ then $neqg$ must retain its value from the prior call with $statef=\text{'S'}$.

(errno $1$)

On entry, $statef=\text{'R'}$ or $\text{'C'}$ and $vectol=False$.

Constraint: if $statef=\text{'R'}$ or $\text{'C'}$ then $vectol$ must retain its value from the prior call with $statef=\text{'S'}$.

(errno $1$)

On entry, $statef=\text{'R'}$ or $\text{'C'}$ and $vectol=True$.

Constraint: if $statef=\text{'R'}$ or $\text{'C'}$ then $vectol$ must retain its value from the prior call with $statef=\text{'S'}$.

(errno $1$)

On entry, $statef=\text{'R'}$ or $\text{'C'}$ and $neqf=⟨value⟩$.

Constraint: if $statef=\text{'R'}$ or $\text{'C'}$ then $neqf$ must retain its value, $⟨value⟩$, from the prior call with $statef=\text{'S'}$.

(errno $1$)

On entry, $\text{latol}=⟨value⟩$.

Constraint: $\text{latol}\ge 1$.

(errno $1$)

On entry, $\text{lrtol}=⟨value⟩$.

Constraint: $\text{lrtol}\ge 1$.

(errno $1$)

On entry, $vectol=True$, $\text{latol}=⟨value⟩$ and $neqf=⟨value⟩$.

Constraint: if $vectol=True$ then $\text{latol}\ge neqf$.

(errno $1$)

On entry, $vectol=True$, $\text{lrtol}=⟨value⟩$ and $neqf=⟨value⟩$.

Constraint: if $vectol=True$ then $\text{lrtol}\ge neqf$.

(errno $1$)

On entry, $neqf=⟨value⟩$.

Constraint: $neqf\ge 1$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

ivp_adams_setup permits initialization of the integration method and setting of optional inputs prior to any call of ivp_adams_roots() or ivp_adams_roots_revcom(). It must be called before the first call of either of the functions ivp_adams_roots() or ivp_adams_roots_revcom() and it may be called before any continuation call of either of the functions ivp_adams_roots() or ivp_adams_roots_revcom().