European Space Agency

European Space Agency

Royal Belgian Institute for Aeronomy

Royal Belgian Institute for Aeronomy

../_images/whiteSpace.png

ud320 - evaluate a double time integral over a drift shell

subroutine  ud320(kpar1, rpar2, zsub, result, rnorm, rdrift, ifail)
Parameters:

  • kpar1 [integer4,in] :: control parameter passed to zsub

  • rpar2 [real8,in] :: control parameter passed to zsub

  • zsub [EXTERNAL,in] :: external subroutine see zsub, below

  • result [real8,out] :: result of the integration

  • rnorm [real8,out] :: time integral of the unity

  • rdrift [real8,out] :: single time integral of the unity

  • ifail [integer4,out] :: error flag (see Diagnostics)

Description

The subroutine ud320() is intended to average physical quantities over a magnetic drift shell. Before any call to this subroutine, a magnetic drift shell has to be traced with the help of subroutine ud310(). As input, the subroutine accepts an external subroutine and two parameters to be passed to this subroutine. The synopsis of the subroutine is given in the note below and is similar to the synopsis of subroutine ua636(). As result, the subroutine returns the value of the double time integral

\(\int \int f(r) \frac{ds}{\sqrt{1-\frac{B}{B_m}}}\frac{dl}{\left ( 2-\frac{B}{B_m} \right )\left| \frac{B \times \nabla B }{B^3} \right|}\)

evaluated over the magnetic drift shell for the function provided by the subroutine zsub (argument result) and for the unity (argument rnorm). The average over the drift shell is given then by result/rnorm. In this equation, ds and dl are elements of length along the field line and along the azimuthal drift direction, respectively. The denominators of ds and dl are proportional to the parallel velocity and the drift velocity, respectively. Since the drift time between two neighbouring field lines depends weakly on the position on the field line, the last factor of the integrant is evaluated only once for each field line (at the local magnetic equator).

The argument rdrift returns the value of the single time integral

\(\int \frac{dl}{\left ( 2-\frac{B}{B_m} \right )\left| \frac{B \times \nabla B }{B^3} \right|}\)

which is proportional to the drift period.

zsub - external subroutine for ud320()

The synopsis of the external subroutine is the following: the arguments kpar1 and rpar2 are control parameters, the arguments mpos and mb are the geographic (geocentric) location and the magnetic field vector where the function has to be evaluated, respectively. The subroutine zsub() returns the value of the evaluated function in argument fct. The argument ifail can be used to flag errors in the subroutine zsub(). When the subroutine returns a negative value for the argument ifail, the computation is aborted.

ua636 - evaluate a weighted amospheric mass provides an example of an implementation of zsub().

subroutine  zsub(kpar1, rpar2, mpos, mb, fct, ifail)
Parameters:

  • kpar1 [integer4] :: control parameters

  • rpar2 [real8] :: control parameters

  • mpos [zgeo,in] :: geographic (geocentric) location

  • mb [zvec,in] :: magnetic field vector

  • fct (*) [real8,out] :: value of the evaluated function

  • ifail [integer4,out] :: error flag (see Diagnostics)

Note

The synopsis has changed between version 2.00 and 2.01 (see history). Moreover, since version 2.01, the entry ud322() allows an array for argument fct.

References

  • Hassitt, A., Average effect of the atmosphere on trapped protons, JGR 70 (1965) 5385-5394

  • Heynderickx, D., Kruglanski, M., and Lemaire, J.F., A new tool for calculating drift shell averaged atmospheric density, in “Radiation Belts: Models and Standards”, AGU Monograph 97 (1996) 173-178

History

  • The subroutine ud320() does not exist in version 1.05 and earlier.

  • In version 2.00 and earlier, the synopsis is CALL ZSUB (kpar1, rpar2, mpos, fct, ifail)

  • The subroutine ud320() has been completely reviewed in version 2.01, as well as subroutine ud321(). The major effects are the addition of a special entry (ud322()) and a modification of the synopsis of the zsub external subroutine. Prior to version 2.01, the argument mb was not included; see note for details. Note that subroutine ua636() has been also adapted.

Diagnostics

  • -32001, invalid drift shell description

  • -32002, invalid drift shell description

Common Blocks

Dependencies

Called by

None

Calls

See also

Reported Bugs

None

Examples

None

UNILIB/tags/v3.02