--------------------------------
                  |                              |
                  |     USER'S GUIDE FOR THE     |   
                  |                              |
                  |  ARTIFICIAL SKY MAP PROGRAM  |
                  |                              |
                  |        (Version 2.3)         |
                  |                              |
                  --------------------------------


Program Description
-------------------
   
   The purpose of this program is to synthesize artificial data for use
in developing and testing methods for Wave Distribution Function (WDF)
analysis.  WDF analysis is a method for making approximate sky maps of 
the sources of natural radio waves in space from experimental estimates 
of the spectral matrices of these waves, based in turn on measurements
by spacecraft of the electric and magnetic wave fields.  Sky maps are
plots of the WDF versus wave normal direction on the celestial sphere.
The Artificial Sky Map (ASM) program first constructs an artificial sky 
map of the WDF from the user's specifications of the wave sources, then 
it calculates the spectral matrix corresponding to the given WDF and to 
a given state of the plasma in which the spacecraft is supposed to be 
located.  These artificial data are stored finally in data files, using
the NSSDC Common Data Format (CDF) scientific data base software.

   The ASM program was written in Fortran 77 on and for a DEC Vax 9410
computer, which runs under the VMS operating system.  At the NSSDC, the
present version 2.3 of this program runs under VMS version 5.5_2, after
having been compiled by version 6.0 of the Vax Fortran compiler.

   This User's Guide has been written both for persons who wish to use
the ASM program as it stands, and for Fortran programmers who may wish
to modify it.


Preliminaries
-------------

   The program is to be utilized in conjunction with the NSSDC Common
Data Format (CDF) scientific data base software.  It was written for
use with CDF Version 2.3 but may well be usable with later versions.  
Before any use is made of the ASM Graphics program, the CDF software
must first be installed on the same computer.

   In order for the user to have access to the complete library of CDF
utilities, an instruction of the following form should be executed on
the command line (i.e., at the $ prompt) at the start of each session, 
or better, implemented once and for all by adding it to the LOGIN.COM
file in the user's home directory:

               @<path>.CDF23-DIST]DEFINITIONS

where <path> is system-dependent.  For instance, on the Vax cluster at
the National Space Science Data Center the proper instruction is:

          @NCF_CDF_OPER:[NCDF.CDF23-DIST]DEFINITIONS

On any other computer, the tail end ".CDF23-DIST]DEFINITIONS" of this
instruction would be the same but <path> would be different.

   In order to be able to compile, link, and run Version 2.3 of the
ASM program, all the files of Fortran 77 source code for it must be 
brought into your working directory.  Proceed as follows:

 *  From the anonymous directory ANON_DIR:[ASM.PROG21], copy all 80
    files for Version 2.1 of the program into your working directory.
    The version number should be 1 for all these files, i.e., their
    complete names should all end with ";1".

 *  From the anonymous directory ANON_DIR:[ASM.PROG23], copy all 18
    files for Version 2.3 that differ from the corresponding files
    for Version 2.1.  The version number should be 3 for all these
    files.

 *  Purge your working directory.  This operation will eliminate all
    the obsolete files, leaving the 80 files that constitute Version
    2.3 of the program.


Compiling the Program
---------------------

   This Fortran 77 program can be compiled in the usual way.  Since
the file name for the main program is ASMP_MAIN.FOR, the instruction
for compiling it is

FOR ASMP_MAIN

The 79 subroutines are included in the compilation automatically.


Linking the Program
-------------------

   The linking instruction for the object file is

LINK ASMP_MAIN, CDF$LIB:LIBCDF/LIB


Running the program
-------------------

   When the program has been compiled and linked, the executable file
can be run by giving the command

RUN ASMP_MAIN

and then following the instructions displayed on the terminal screen.
The operations that the program performs are described below, section
by section.  The program contains nine major sections:  Introduction, 
Metadata Input, WDF Data Input, Map Data Input, Input Data Storage,
Sky Map, Entropy, Spectral Matrix, and Session Summary.

Introduction
- - - - - - -
   Here some basic information is supplied, informing the user about
what program does and what it expects the user to do.

   This first section should be easy to modify, if necessary, because 
it consists mainly of PRINT statements for the text to be displayed on
the screen.  

   A feature that may need to be modified is the number of blank lines
that are printed, at the very outset of the program, in order to clear 
the screen before printing the introduction.  This task is performed by 
the following DO loop,

      DO I=1,15
          PRINT*,' '
      END DO

which prints 15 consecutive blank lines.  The number of such lines that
is required depends on the type of terminal in use, specifically on how
many consecutive lines of characters this terminal can display at once.
The ASM program was written to be used with a DEC VT100 terminal, which
can display 20 lines at once.  This is the minimum number; any terminal
displaying fewer than 20 lines could not be used without shortening some
of the texts or tables that the program displays.  However, any terminal
displaying more than 20 lines could be used readily.  For this purpose,
the number of blank lines printed by the aforementioned DO loop should
be increased.  If the terminal can display 20 + n lines, then the loop
should be modified to make it print 15 + n blank lines.

   At many points later in the program, similar DO loops are utilized to 
clear the screen before displaying some text or table.  Comments similar 
to those in the preceding paragraph apply in all these cases.


Metadata Input
- - - - - - - -
   This enables the user to put in identifying personal information, 
including the user's name, the user's institute or other professional
affiliation, and the date on which the session is taking place.  The 
program currently accepts a maximum of 50 characters for each input.
Following these initial metadata, the program will prompt the user to 
enter a name for the artificial sky map.  This name again is limited
to 50 characters, which should be consecutive (i.e., there should be
no blank spaces), and the only characters allowed are letters of the
alphabet, numbers, hyphens and underscores.  This name will be given 
to the CDF file in which the sky map data are stored.  Therefore the
program checks whether a CDF with the given name exists already.  It
does this by attempting to open this CDF, and if it is able to do so,
this means that the CDF exists.  In this case, it offers the user the 
option either of choosing some other name or of deleting the existing 
CDF so that a new one with the same name can be created.  Otherwise,
if it is unable to open a CDF with the given name, it concludes that
no such CDF exists and therefore the given name is acceptable.

   If a CDF with the initial given name exists, and the user opts to
choose another name, then, before allowing the user to do so, the ASM
Program first closes the existing CDF.  After this and all subsequent
operations involving CDF software, the program checks that the status
of the CDF is OK, meaning that the operation has been done correctly.
A subroutine named ASM_CDF_STATUS is dedicated to this task; if ever
the CDF status is not OK after a call to the CDF software, then this
subroutine halts execution of the ASM Program, and prints a message 
identifying the point at which the error occurred and the nature of
the error.

   Apart from the PRINT statements for the text shown on the screen, 
most of the code in this section is concerned with checking that the
metadata entered by the user conform to the specifications.  A final
routine in this section prints some instructions as to how, in later
sections, numerical data should be entered into the computer.

WDF Data Input
- - - - - - -
   In this section, the program interrogates the user for the values 
of certain parameters that jointly define the shape of the model WDF.  
They consist firstly of some parameters that govern the influence of 
the plasma and magnetic field on whistler-mode wave propagation, and
secondly of the parameters of the wave sources.

   The influence of the plasma on the waves is taken into account in
the approximation that considers solely the effects of the electrons
and ignores those of the positive ions.  Under these conditions, the
properties of the waves are governed by the relative values of three
characteristic frequencies:  the plasma frequency, the gyrofrequency
of the electrons, and the frequency of the wave itself.  The program
asks the user to enter the values (in Hz) of these three frequencies
in succession.  It checks that each of them is positive, and if not,
asks the user to enter another value.  Then it checks that the wave
frequency is smaller than both the plasma frequency and the electron
gyrofrequency, which is a necessary condition for propagation in the
whistler mode.  If not, it offers the user the choice between either
just changing the wave frequency, or of going back to the beginning
of the WDF Data Input section so that any of these three frequencies
can be changed if necessary.

    After all three have been entered, the program computes from them
the value of the resonance angle, which is the half-width of the cone
of directions around the magnetic field within which the wave normal
must lie if the waves are to be able to propagate freely; elsewhere,
in a band of directions centered on the equator (i.e., on the plane 
perpendicular to the field), wave propagation in the whistler mode is 
forbidden.  The values of the polar wave normal angle at the edges of
this forbidden zone are displayed so that the user can avoid placing
any wave sources there.

   The model adopted for the WDF lets the user define wave sources of 
two kinds:  point sources and extended sources.

   Point sources are sources having angular dimensions much too small
to be determined by WDF analysis, so for this practical purpose their
dimensions are negligible.  In mathematical terms, the contribution of
a point source to the WDF is a Dirac distribution or "delta function."
Each point source is characterized by three parameters, two of which
are angles specifying the wave normal direction for the waves arriving
at the spacecraft from this source.  The first of these angles, called
"theta," is the polar angle between the wave normal direction and the
local direction of the Earth's magnetic field.  The program refuses to
accept values for the polar angle that would place the wave normal in
the zone where wave propagation is forbidden.  The second such angle,
called "phi," is an azimuthal one measured right-handedly around the
direction of the field; the origin for phi is the projection, into the
plane perpendicular to the field, of the radius vector from the center
of the Earth to the position of the spacecraft.  For each point source
that the user wants to define, the program requests that the values of
these angles be entered in degrees.  

   The third parameter characterizing a point source is its integrated 
intensity, which is the integral over solid angle of the contribution 
that the source makes to the WDF; considering this contribution to be 
approximated by a delta function, the integrated intensity of a source 
is the "strength" of the delta function.  

   On physical grounds, namely that a WDF is a distribution of energy
density, the intensity of a source cannot be negative.  Nevertheless,
the program does permit the user to enter negative source intensities,
after querying them and receiving confirmation from the user.  The aim
of this facility is to enable the user to test certain algorithms used
in WDF analysis for checking that the spectral matrix data contain no
gross errors that would prevent any solution being found for the WDF.
This facility is offered for extended as well as for point sources.

   For the extended sources synthesized by this program, the profile
of the intensity of a source versus position on the celestial sphere
is approximately Gaussian along any great circle passing through the
center of the source, and the contours of equal intensity are roughly
elliptical; the profile would be truly Gaussian and the contours truly
elliptical, were it not that the ASM Program modifies the shape of the
source so as to make the WDF fall smoothly to zero at the edges of the
zone in which wave propagation is forbidden.  The physical reason for
making it do this is that waves propagating very close to a resonance
cone tend to be absorbed.  

   Each extended source is characterized by a total of six parameters,
the first three of which are similar to those that characterize point 
sources.  They are the polar angle theta and the azimuthal phi of the
wave normal direction for the center of the source, i.e., the point at
which the WDF is maximum, while the third parameter is the intensity of
source as measured by the value of the WDF at the maximum.

   It should be noted that the units user for the intensities of point
sources and of extended sources are not the same.  The two units must
be consistent, however.  This means that if a certain unit (U, say) is 
used for the intensities of the point sources, then the unit used for 
those of the extended sources must be U per steradian.  Subject to that
condition, the choice of units for the intensities is left to the user.

   The remaining three parameters that characterize an extended source
specify its extension in terms of the dimensions of the contour where
the WDF equals exp(-1/2) = 0.61 times the maximum value.  They are the
half-length (entered in degrees) of the major axis of the ellipse, the
angle (again in degrees) between this axis and the line of constant phi
passing through the center of the source, and the axial ratio (ratio of
the length of the minor axis to that of the major axis).  More exactly,
these are the dimensions that the contour in question would have, were
it not that the program modifies the profile of the source so that the
WDF falls to zero at the edges of the forbidden zone, as was mentioned
earlier.

   After all the data for the extended sources have been entered, the
program sorts these sources according to whether they are in the north
or south hemisphere, and makes a set of pointers to the sources in each
hemisphere.  For present purposes, a "north hemisphere" source is one
having a polar wave normal (theta) angle less than 90 degrees, while a
"south hemisphere" source is one having theta greater than 90 degrees.
The justification for this terminology is that, when wave observations
are made by a spacecraft on the magnetic equator, these two ranges of
theta correspond to wave normals directed into the magnetic north and
south hemispheres respectively.

   The program enables the user to specify up to ten point sources and
ten extended sources.  

Map Data Input
- - - - - - - 
   If any extended sources have been specified, the ASM Program offers 
the option of having the combined contribution of these sources to the
WDF calculated as a function of position on the celestial sphere, and
its values stored in a CDF data file in the working directory so that
later it can be visualized as a sky map, for instance on the screen of 
a computer graphics terminal or as hard copy.  Another program, named
ASM Graphics, has been written to perform the visualization; it plots
the sky map for one hemisphere at a time.  

   If the user takes this option, then, in the Map Data Input section,
the program enables the user to enter the specifications for the grid,
or mesh, on which the WDF is to be computed.  This grid is uniform in
both the polar angle theta and the azimuthal angle phi, in the range
of permitted wave normal directions in each hemisphere.  For the polar
angle (also known as the colatitude), the user must specify the number
of intervals in the grid between the pole and the resonance cone.  For
the azimuthal angle (or longitude), which runs from 0 to 360.0 degrees
around each parallel of latitude, the number of grid intervals in this
range must be entered.  These specifications define a rectangular grid,
and later the ASM Program will compute the WDF at the center points of
all the rectangles.

   If the computed WDF is to be visualized as a sky map by means of the
ASM Graphics program, then the number of grid intervals for each of the
two angles should not be less than about 100, otherwise the contours of
constant WDF on the sky map will be jagged.  The ASM Program allows the
user to enter smaller numbers here, however.  Another requirement of the
ASM Graphics program is that the number of intervals for the azimuthal
angle should be even, and the ASM Program imposes this condition:  if by
inadvertence the user enters an odd number here, then the program adds 
1 to it to make it even.  The point of this condition is to ensure that,
if calculations are made of the WDF in both hemispheres, they are made
at two sets of points that are diametrically opposed to one another on
the celestial sphere; that is to say, if the WDF is calculated at some
point in the north hemisphere, it is also calculated at the diametric-
ally opposite point in the south hemisphere.

Input Data Storage
- - - - - - - - - -
   At this point in the execution of the ASM Program, the user of it
has supplied, as input, all the data that would be required in order
to compute the WDF, though there is no obligation to have this done
unless the user wants it.  In any case, however, before computing the
WDF, the program must create the CDF in which all of its values would 
be stored.  Even if the user chooses not to compute the WDF, the CDF
must be created and the input data stored in it.  These are the tasks
of the Input Data Storage section of the program.

   By means of a sequence of level-1 subroutines, the program creates 
the CDF and stores there the metadata, the characteristic frequencies, 
the resonance angle and its cosine, the numbers of point and extended
sources defined by the user, the three parameters of each point source
and the six parameters of each extended source, and also the map data
(if any).  When all this has been done, it closes the CDF (the CDF is
closed at the end of each major section of the program, and reopened
whereever it is next required).

   The program creates the CDF, giving it the name chosen by the user
in the Metadata section.  The file name given to the CDF is this name
followed by the characters ".cdf".  For instance, if the user were to 
choose the name "Example_1", the name of the corresponding file would 
be "Example_1.cdf".  The CDF is created using network encoding, which
means that the file can be be created on a VMS system, then ported to
a Unix system and opened there (for instance by ASM Graphics) without
having to be modified in any way.  The instruction used to create the
CDF specifies that the computed values of the WDF are to be stored in
a 2-dimensional array with the dimensions that the user asked for in 
the Map Data Input section; if the WDF is not to be computed, however,
then both of these dimensions are set to zero at this point.  Finally,
the same instruction specifies that the array should be column major,
which means that the first dimension in the array varies the faster;
this is the normal state of affairs in Fortran arrays.  For additional
information on the matters of encoding and majority, consult the "CDF
User's Guide for VMS Systems" listed in the Bibliography.

   The metadata and data mentioned in the last-but-one paragraph are
stored in the CDF as global CDF attributes; see the CDF User's Guide
for an explanation of this term.  The attributes for the metadata and
for most other data have only single entries.  However, the attributes 
for the parameters of the sources have multiple entries, one for each
source of a particular type (point or extended).  If only one type of
source is present, then the number of sources of the type not present
is stored as zero, and the attributes corresponding to the parameters
of the latter type of source are not created.  Likewise, if the user
has not opted to have the WDF computed and tabulated for plotting as
a sky map, then the attributes for the map data are not created.

   The user's name for the CDF is stored in two different global CDF
attributes, called TITLE and MPNAME.  The reason for this redundancy
is historic.  The initial version of the ASM program was written for
use with version 1.1 of the CDF software, and it stored the name of 
the CDF in a single global attribute called MPNAME.  When version 2.0 
of the CDF software was published, however, the creation of a global
attribute called TITLE became mandatory.  In revising the program to
allow it to operate with CDF V2.0, this new global attribute was set
identical to MPNAME so as to minimize the changes that had to be made
to the Fortran code.  In some future version of the program, however,
the character variable MPNAME will probably be renamed TITLE in order
to eliminate this redundancy.

   Appendix 1 below contains the full list of the input data that the 
program stores in the CDF when the user has defined sources of both 
types and has opted for having the WDF computed and tabulated.  For
each datum, the list gives the name of the CDF attribute, the maximum 
number of entries, and a description of the datum concerned.

Sky Map
- - - -
   This section of the program computes a table of the WDF and stores
it in the CDF, so it is executed only if the user has opted for doing
these things in view of plotting the sky map.

   If so, then as a first step the program reopens the CDF and creates
the obligatory variable attributes, i.e., the attributes that have to
be specified for each of the variables, both independent and dependent,
that are involved in the tabulation of the WDF.  Elsewhere in the ASM
Program the WDF is considered to be a function of a polar angle called
"theta" and an azimuth angle called "phi," but for tabulating data on 
a sphere the NSSDC standard CDF variables are latitude and longitude; 
hence the latter are taken as the independent variables at this point.  
On going from the north pole to the south pole, theta varies from 0 to
180 degrees while the latitude varies from + 90 to - 90 degrees.  The
angle phi and the longitude are the same, however; both vary from 0 to
360 degrees.  The dependent variable is, of course, the WDF, or, to be
more exact, the contribution to the WDF from the extended sources.

   The preceding statements concerning the latitude and the WDF should 
be qualified by stating that the program actually takes the modulus of
the latitude as the independent variable; this quantity varies from 0
to 90 degrees on going from the equator to either pole.  Moreover the 
WDF data for the north and south hemispheres are given different names 
and are stored in separate tables in the CDF.  Thus there are actually 
two dependent variables, with the names WDFNOR and WDFSOU; both these
variables are normalized values of the WDF (see below).

   For each of these four variables, latitude, longitude, WDFNOR, and
WDFSOU, the following standard attributes must be created:  FIELDNAM, 
VALIDMIN, VALIDMAX, UNITS, and FORMAT.  The program also creates some 
optional standard attributes, called SCALEMIN, SCALEMAX, and MONOTON.  
For the definitions of these variable attributes, see the CDF User's 
Guide.

   The program then creates two CDF variables representing the latitude 
and longitude, assigns the proper values to each of their attributes as 
mentioned above, and generates the grid on which WDFNOR and WDFSOU are
to be computed, i.e., it computes and stores the value of the latitude
or longitude corresponding to each grid line.  The grid is uniform in
both of these independent variables.  In each hemisphere, however, the 
useful range of latitudes, in which the WDF can be non-zero, runs from
the pole to the resonance cone; it is this range, less than 90 degrees
in width, that the program divides into the required number of uniform
intervals.  The same grid is used for the WDF in the two hemispheres,
the latitude variable being effectively north latitude in the one case
and south latitude in the other.  

   The main task of this section is to compute and store the values of
the WDF at the centers of the grid rectangles in each hemisphere that
contains one or more extended sources.  First the CDF variables WDFNOR
and/or WDFSOU have to be created and values given to their attributes.  
Next, the values of the WDF are computed for the hemisphere containing
extended sources, or for both hemispheres if both contain them.  These
values are stored temporarily as a two-dimensional array in an internal 
computer file.  During the computation of the WDF, note is taken of the 
maximum value encountered.  Then the whole set of stored values of the 
WDF is normalized with respect to this maximum value in such a way that
the maximum value becomes 10 and all other values are proportionately
smaller. Finally the arrays of these normalized values of WDFNOR and/or 
WDFSOU are stored as the corresponding CDF variables, while the maximum
non-normalized value is stored as a global CDF attribute.  When all of
this has been done, the program closes the WDF.

   The maximum value of the non-normalized WDF is stored in the CDF as
a global CDF attribute named WDFMAX.  The value of the non-normalized
WDF at any point on the sky map can be found by taking the normalized
value as tabulated, multiplying it by WDFMAX, then dividing by 10.

Entropy
- - - -
   If the sky map contains no point sources, only extended sources, the 
program offers the user the option of computing the entropy of the WDF.
This is the quantity used when analyzing experimental spectral matrices
by the method of maximum entropy, so as to obtain estimates of the WDFs.
In point of fact, different experimenters use different expressions for 
the entropy, so the program computes it using two of the expressions in
most common use.  In both of them, the entropy is given by an integral
over the region of the celestial sphere where the WDF is non-zero.  If
the symbol f is used for the WDF itself, and F for its mean value over
this region, then the integrands used are - f.ln(f) and - (f/F).ln(f/F)
in the two cases.

   If the sky map contains any point sources then these two "entropies"
cannot be computed, because the entropy of a point source is negative
infinite.  In this case, the program displays a text explaining to the
user why the computation cannot be done.  If, on the other hand, there
are no point sources, it displays a different text offering the option
to have the entropies computed, and if the user agrees it performs the
computation.

   The major part of this computation is the evaluation of the double 
integrals for the - f.ln(f) entropy and for the mean value; these two 
integrals are obtained iteratively, to specified relative accuracies,
by Romberg integration.  Given both, the - (f/F).ln(f/F) entropy can be
computed from them without having to evaluate another double integral.

   If the program does a prescribed number of iterations (currently 12)
without reaching the specified accuracies, it displays a notice telling
the user that this situation has arisen and suggesting several possible 
reasons.  However, it then accepts the computed values of F and of the 
- f.ln(f) entropy despite their insufficient accuracy, and obtains the
other - (f/F).ln(f/F) entropy by combining them as mentioned above.

   Having done this, the program reopens the CDF, stores in it the two
entropies and the mean WDF, then closes the CDF again.

Spectral Matrix
- - - - - - - -
   This is the most computationally intensive section of the program.
Its purpose is to compute the elements of the 6 x 6 spectral matrix of
a random electromagnetic wave field in the given plasma, at the given
wave frequency, and characterized statistically by the given WDF.  The
spectral matrix is complex, with Hermitian symmetry.  Counting the real
and imaginary parts as separate quantities, a Hermitian matrix of this
size could contain 36 independent quantities.  However, in the present 
case three of them happen to be identically zero, which leaves just 33 
to be computed.  All these quantities - real or imaginary parts of the 
spectral matrix elements - are linear functionals of the WDF.  That is 
to say, they are given by integrals with respect to solid angle of the
products of the WDF with certain weighting functions, or kernels.  The
properties of the plasma affect the computation of the spectral matrix
though the intermediary of the kernels, which also depend on the wave
frequency and on the wave normal direction.  The algebraic expressions
for the integration kernels in terms of all these variables are fairly
complicated, which is why a lot of computation has to be done in order
to obtain the spectral matrix.  This computation is performed only if
the user opts for it.

   The kernels and the matrix elements that this program computes are
similar to those defined by Storey and Lefeuvre in their two Geophys. 
J. Roy. Astron. Soc. papers cited below in the Bibliography.  There is
one important difference, however:  the quantities computed by the ASM
program equal those defined by Storey and Lefeuvre, multiplied by the
electric permittivity of free space (epsilon_zero).  Multiplying them
by this factor makes the kernels and matrix elements dimensionless.

   The computation of the set of 33 integration kernels, for any given
wave normal direction, starts by computing the Stix parameters:  R, L,
and P.  These are independent of direction, involving only the relative
values of the plasma, gyro, and wave frequencies.  See the referenced
book by T.H. Stix for further information about them.

   From the Stix parameters, the program then computes the refractive
index for whistler-mode waves with the given frequency and wave normal
direction.  More exactly, it computes the inverse of the square of the
phase refractive index, since it is in this form that the index enters
into the expressions used for the kernels.  The reason for using these
particular expressions, rather than alternatives into which the index
enters as such, is that they are computable right up to the resonance
cones where the refractive index becomes infinite, but the inverse of
its square tends to zero.

   For a given wave normal direction, defined by angles theta and phi,
the kernels are computed in two steps.  In the first step, the program
computes a set of coefficients named B(i,j) which depend only on theta.
In the second, it computes the kernels A(i,j,k) which depend on phi as 
well.  In both sets, the indices i and j refer to the axial components 
of the electric and magnetic wave fields in a Cartesian coordinate sys-
tem with the z-axis along the direction of the Earth's magnetic field.  
The kernels are independent of the directions of the other two axes, 
provided that they form with the first a right-handed set.  (However, 
customarily the x-axis is aligned with the projection, into the plane 
transverse to the Earth's field, of the radius vector from the center 
of the Earth to the position of the spacecraft).  With this choice of 
coordinates, the indices i and j, each of which runs from 1 to 6, refer 
to the wave field components according to the following scheme:

                1       x-component of E
                2       y-component of E
                3       z-component of E
                4       x-component of H
                5       y-component of H
                6       z-component of H

Here the symbols E and H refer to the electric and magnetic components
of the wave field respectively.  

   The computation of the kernels, like most of the computation done by 
the ASM program, is done in single (4-byte) precision.  A small part of 
it, however, has to be done in double (8-byte) precision.  The reason
for doing this is that the expressions for some of the kernels include
the term (1-R*n**(-2))/tan(theta); in this Fortran expression, R is one
of the Stix parameters and n is the phase refractive index.  When the
angle theta tends to zero, the reciprocal of the tangent diverges, but 
at the same time n tends to the limit R**(0.5) so 1-R*n**(-2) tends to 
zero.  As a result, the term (1-R*n**(-2))/tan(theta) tends towards a
finite asymptotic value when theta tends to zero.  It cannot, however,
be calculated accurately as the product of these two disparate factors 
when theta is small.  For values of theta (or of 180 - theta) below a
certain limit, the above algebraic expression for this term has to be
replaced by an asymptotic approximation that becomes steadily more and
accurate as theta decreases.  The following question therefore arises:
what is the limit of theta, below which this asymptotic approximation
should be used instead of the algebraic expression given above?

   The answer to this question is supplied by the subroutine ASM_THETA
_LIMIT.  It computes both expressions for the term, and compares them
at different values of theta, starting with a fairly large value then
reducing it progressively.  As theta becomes smaller and smaller, the 
relative difference between the values given by these two expressions 
decreases initially, because the asymptotic approximation is becoming
more accurate.  Below a certain value of theta, however, the relative
difference starts to increase, because numerical round-off errors are
degrading the results obtained from the nominally correct expression.
The subroutine ASM_THETA_LIMIT identifies the value of theta at which
the relative difference between the results from the two expressions
is smallest (in modulus).  When the kernels are computed, this value
of theta is taken as the limit below which it is appropriate to use
the asymptotic approximation.

   For theta close to this limit, however, the values computed from
from the expression (1-R*n**(-2))/tan(theta) have larger-than-usual
fractional errors, because the quantity R*n**(-2) is very close to
unity.  Accordingly, so as to be sure of obtaining 4-byte accuracy
for the factor 1-R*n**(-2), the quantity R*n**(-2) is calculated in
double (8-byte) precision.  For this purpose, the subroutine named
ASM_PHASE_INDEX calculates first n**(-2) then 1-R*n**(-2) in double
precision, using a double-precision value of R from the subroutine
named ASM_STIX.  After calculating 1-R*n**(-2) in double precision,
the subroutine ASM_PHASE_INDEX rounds this quantity off to single
precision for use by other parts of the program.

   According to whether the value of theta is greater or less than
the limit given by ASM_THETA_LIMIT, the subroutine ASM_BIJ computes
the coefficients B(i,j) using the term (1-R*n**(-2))/tan(theta) or
the asymtotic approximation for this term.  Then another subroutine,
named ASM_AIJK, computes the kernels A(i,j,k).  In these quantities,
the indices i and j refer to the wave field components in the same
way as they do in the B(i,j).  When i is not equal to j, the kernels 
are generally complex, so a third index, k, is used to distinguish 
their real parts from their imaginary parts:  k=1 for a real part, 
k=2 for an imaginary part.  The matrix of the complex kernels A(i,j)
has Hermitian symmetry, which means that A(i,j,1) = A(j,i,1) while
A(i,j,2) = - A(i,j,2).  Consequently only the elements on or above
the diagonal of the complex matrix are computed; these are the ones
with j greater than or equal to i.  The elements below the diagonal,
which have j less than i, can be obtained from the symmetry.

   The elements S(i,j,k) of the complex spectral matrix are computed 
by multiplying the kernels A(i,j,k) by the WDF, and integrating the
products over the region of the unit sphere within which the kernels
and the WDF are nonzero.  As with the entropies, the integrations are
performed by a Romberg method to predetermined relative accuracies,
but the process is stopped after 12 iterations even if the specified
accuracy has not been achieved for all of the matrix elements.
   
   The values of the matrix elements are stored in the CDF data file
as global CDF attributes.  For this purpose, the element S(i,j,k) is
given the name SPMTXijk, where i, j, and k are the numerical indices.
Thus, for example, the value of the matrix element S(2,3,1) is stored
as the global attribute SPMTX231.  All 36 matrix elements have their
values stored, including the three that are identically zero.

   Failure to achieve the specified accuracy for all of the spectral
matrix elements is recorded using two global CDF attributes, called
FLAG8 and FLAG9.  See Appendix 2 for how to interpret their values;
this second appendix catalogs all the quantities that the ASM program
stores in the CDF data file.

Session Summary
- - - - - - - -
   This section allows the user to have a summary of the interactive
session written to a text file.  This summary records all the input
metadata and data supplied to the program by the user in the course
of the session.  It does not record the output from the program; all
of this output is stored in the CDF.  The user can open the CDF and
inspect its contents by means of the CDFbrowse and CDFlist utilities.

   The file name for the session summary is constructed from the one
that the user gave to the CDF earlier, in the Metadata section.  The 
name now given to the summary text file is this name followed by the
characters ".txt".  For instance, if the name "Example_1" were given 
to the CDF, the file name for the session summary text file would be 
"Example_1.txt".  Any pre-existing text file having the same name is
deleted before the new one is created.

   If the user decides not to have a summary text file written, then
the program terminates the session forthwith.  Otherwise, it does so
after having written this file.


Example of a CDF
----------------

   An example of a CDF created by Version 2.1 of the ASM program may
be found, together with the corresponding summary text file, in the
Anonymous directory ANON_DIR:[ASM.CDF].  The names of these two files
are respectively Example_1.cdf and Example_1.txt.  Though created by
the previous version of the ASM program which used version 2.1 of the
CDF software, Example_1.cdf is compatible with CDF V2.3.

   The sky map represented by the data in this CDF has only extended
sources in the north hemisphere, and only point sources in the south
hemisphere.  Five sources of each kind have been used in making this
sky map.

   The sky map for the north hemisphere is same as the one shown in
Figure 5 of the report by Storey and Yeh listed in the bibliography
at the end of the present text.

   The point sources in the south hemisphere are sited in directions
diametrically opposed to those of the centers of the extended sources
in the north hemisphere.

   Consequently, if the ASM Graphics program is used to display the
sum of the WDFs for the two hemispheres, then the images of the point
sources will mark the positions of the centers of the extended sources.


Listing the Source Code
-----------------------

   The Fortran 77 source code for the Artificial Sky Map program 
comprises the main program ASM_PROGRAM and 79 subroutines.  They
occupy altogether 694 blocks (= 347 kB) of memory on a Vax.  When he
wrote this code, the author made some use of tabs.  Users who wish 
to list the code as written should set the tabs on their printers to 
the following positions:  8, 16, 24, 32, ... etc.  These are the de-
fault tab positions normally used on DEC Vax computer systems.


Bibliography
------------

NSSDC, "NSSDC CDF User's Guide for VMS Systems, Version 2.1," National
      Space Science Data Center, NASA Goddard Space Flight Center, 
      Greenbelt, Technical note NSSDC/WDC-A-R&S 91-31, 1991.

STIX, T.H., "The Theory of Plasma Waves," McGraw-Hill, 1962.

STOREY, L.R.O., and F. LEFEUVRE, "The analysis of 6-component measure-
      ments of a random electromagnetic wave field in a magnetoplasma
      - I. The direct problem," Geophys. J. Roy. Astron. Soc. 56, 255-
      270, 1979.

STOREY, L.R.O., and F. LEFEUVRE, "The analysis of 6-component measure-
      ments of a random electromagnetic wave field in a magnetoplasma
      - II. The integration kernels," Geophys. J. Roy. Astron. Soc. 62, 
      173-194, 1980.

STOREY, L.R.O., and K.J. YEH, "Data Synthesis and Display Programs for
      Wave Distribution Function Analysis," NSSDC Technical Note No.
      NSSDC/WDC-A-R&S 92-05, June 1992.


************************************************************************


              APPENDIX 1.  INPUT DATA STORED IN THE CDF
              -----------------------------------------

  	Maximum
 Name   entries           Description

TITLE	   1	Title of the CDF (same as MPNAME).
AUTHOR     1    Name of the author of the sky map (i.e., user of program).
AFFIL      1    Author's professional affiliation.
DATE       1    Date of creation of the sky map.
MPNAME     1    Name given to the sky map.
FPLAS      1    Plasma frequency (Hz).
FGYRO      1    Electron gyrofrequency (Hz).
FWAVE      1    Wave frequency (Hz).
THERES     1    Whistler-mode resonance angle (degrees).
CHIRES     1    Cosine of the resonance angle.
NPOINT     1    Total number of point sources.
POLPNT    10    Polar angles of the point sources (degrees).
AZIPNT    10    Azimuth angles of the point sources (degrees).
INTPNT    10    Intensities of the point sources (user-defined units).
NEXTEN     1    Total number of extended sources.
POLEXT    10    Polar angles of the extended sources (degrees).
AZIEXT    10    Azimuth angles of the extended sources (degrees).
INTEXT    10    Intensities of the extended sources (user-defined units).
LENGTH    10    Lengths of the source semi-major axes (degrees).
DIRECT    10    Direction angles of the major axes (degrees).
AXIRAT    10    Axial ratios of the source ellipses.
NPOLAR     1    Number of intervals of polar angle in each sky map.
NAZIMU     1    Number of intervals of azimuth angle in each sky map.


All of these data are stored as global CDF attributes.  However, any
one CDF may not have all these attributes; which of them are present 
depends on which options the user has taken.  Thus, for instance, if 
the user had decided not to define any point sources, then the three
attributes POLPNT, AZIPNT, and INTPNT would not have been created.


************************************************************************


              APPENDIX 2.  OUTPUT DATA STORED IN THE CDF
              ------------------------------------------

  	Maximum
 Name   entries           Description

FIELDNAME  4	Variable CDF attribute
VALIDMIN   4    Variable CDF attribute
VAKIDMAX   4    Variable CDF attribute
SCALEMIN   4    Variable CDF attribute
SCALEMAX   4    Variable CDF attribute
UNITS      4    Variable CDF attribute
FORMAT     4    Variable CDF attribute
MONOTON    4    Variable CDF attribute
WDFMAX     1    Maximum value of the WDF
ENTROPY1   1    Value of the f.ln(f) entropy
ENTROPY2   1    Value of the (f/F).ln(f/F) entropy
WDF_MEAN   1    Mean value F of the WDF
SPMTX111   1    Spectral matrix element with indices (1,1,1)
SPMTX121   1    Spectral matrix element with indices (1,2,1)
SPMTX122   1    Spectral matrix element with indices (1,2,2)
********
Etc.            The total number of matrix elements is 36
********
SPMTX561   1    Spectral matrix element with indices (5,6,1)
SPMTX562   1    Spectral matrix element with indices (5,6,2)
SPMTX661   1    Spectral matrix element with indices (6,6,1)
FLAG8      1    TRUE if all the integrals over cos(theta) for the 
                matrix elements achieved the specified accuracy
FLAG9      1    TRUE if all the integrals over phi for the 
                matrix elements achieved the specified accuracy


All of these data are stored as global CDF attributes, except for
the eight standard variable attributes (FIELDNAME through MONOTON)
at the head of the list.  These standard variable attributes are
created only if the user decides to have the sky map computed and
stored in the CDF (see the section "Map Data Input").  Again, not
all the global CDF attributes listed above are necessarily present
in any one CDF; some may be absent, corresponding to options that
the user did not take.

   If the user decides to have the sky map computed and stored in
the CDF, then, besides the attributes listed above, the values of
the following variables will also be tabulated in the CDF:


LATITUDE   Modulus of the latitude of a point on the celestial 
           sphere (varies from 0.0 to 90.0 degrees)

LONGITUD   Longitude of a point on the celestial sphere (varies
           from 0.0 to 360.0 degrees)

WDFNOR     Normalized value of the contribution to the WDF from
           extended sources in the northern hemisphere, at the
           point specified by LATITUDE and LONGITUD.
           
WDFSOU     Normalized value of the contribution to the WDF from
           extended sources in the southern hemisphere, at the
           point specified by LATITUDE and LONGITUD.


The option for computing and storing the sky map is offered only
if the user has defined some extended sources.  If such sources
have been defined in only one of the two hemispheres, then only
the corresponding dependent variable (WDFNOR or WDFSOU) will be
created and tabulated.


                                                   30 June 1993