-------------------------------- | | | 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: @.CDF23-DIST]DEFINITIONS where 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 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