General and Input Commands
?: Print a brief version of this catalog.
clear cmd: Remove all instances of the command cmd from the instruction stack. For example, nondipole can be canceled, or silent.
execute: With the model saved in memory, compute the field values and map as requested. When these calculations have been completed magmap returns asking for further work, such as finding another map from the same model or calculations with a different model. The contour maps (if any) are generated after the quit command.
earth a, b, aref: The coefficients are computed with respect to a reference radius, aref in km. In the site command (but not on the maps) the geographic positions are specified with respect to an ellipsoid, equatorial and polar radii a and b (km). The default values are: 6378.17, 6356.91 and 6371.20 km. With this command you can degrade the earth model to a spherical approximation by setting a=b=aref. Setting the radii equal is useful for geocentric coordinate calculations needed in satellite data reduction.
file filename: The diskfile containing the SH
coefficients is named here. Each line of the input file must contain
four numbers: l, the spherical harmonic degree; m the order; g(l,m)
the cosine coefficient; h(l,m) the sine term. When m=0 the sine term
is always zero, but it must be present in the file nonetheless. With
this scheme the lines of the file can be in any order.
If the degree is negative, the coefficient is taken describe a field
with an exterior source. Lines in the file may begin with the
percent sign (%); then they are treated as comments and skipped by
magmap. SH data can be supplied in an ordered list without m
and l; see serial. The standard IGRF field models are stored
internally and accessed with the igrf command.
If * is entered for the filename magmap will read the
coefficients from the terminal immediately after the execute
command. The end of input is signaled with degree l < -499.
igrf year: Instead of opening an external diskfile for the Gauss coefficients use one of the internal set of IGRF field models from the years 1900-2010 in steps of 5 years. The data set is the IUGG year 2010 version. See http://www.ngdc.noaa.gov/IAGA/vmod/igrf.html. The entered year will be rounded to the nearest allowed integer.
list: Print listings of the field model coefficients. Two listings are produced: the first is exactly as read from the file (with some caveats; see below); the second is in the F1 normalization, scaled to the requested referenced sphere radius, which is how the coefficients are stored internally. When serial input is requested, the first listing includes the degree and order of the coefficients, even though these are absent from the data file.
lmax L : Accept spherical harmonic coefficients only up to degree L, and skip any in the file of higher degree.
nondipole [1]: Delete the dipole (l=1) terms in this and subsequent input files, thus allowing a map of the nondipole field to be made. If the optional 1 follows, delete only the axial m=0 term. In serial input mode all dipole terms are deleted, even if the integer 1 is present. Use clear to revoke this command. See also serial.
normalization X: where X must be one of S, F1, F2, G, U. Here S means Schmidt normalization; X=F1 means fully normalized coefficients with integral of the squared spherical harmonic equal to 1 with factor (-1)**m; X=F2 means fully normalized, but with the integral equal to 4 pi; G1 means normalized for gravity coefficients, like F2, but with (-1)**m factor omitted; U means unnormalized basis functions are used. Most magnetic field models are of so-called Gauss coefficients, and then X=S. A normalization must be given or the program will stop, unless the igrf command was used, when the correct normalization is automatically assigned. Maps will be drawn with contours scaled by 0.001 on the assumption the input data are in nT, and the maps are in muT; this arrangement does not apply to X=U, however.
quit: Cease. Plot any contour maps first.
radius r: The map is computed on a sphere radius = r*aref (see earth). The internally stored coefficients are renormalized to this radius, so this is effectively an input command. Thus maps of the field on the core (almost the only use for this command) take r=0.547. Default value is unity, of course.
serial [without zeros]: Instead of holding to the standard format of two Gauss coefficients per line preceded by the degree and order, the input file of coefficients is arranged in a serial listing in the normal order, beginning at l=1, m=0. Any number of coefficients may appear on each line. If the optional phrase appears in the command, the coefficients for the sine part when m=0 (which are conventionally set to zero) are omitted from the list, otherwise it is assumed they are present. When nondipole is turned on, the series must begin at degree l=2. To cancel this command use clear. Exterior source fields cannot be specified in serial mode.
silent: Once issued all printing to the screen (except error messages) is suppressed. This command can be reversed with clear.
Commands Governing Calculation
center lat, long: Geographic coordinates of the map center when both are present. However, for the Hammer-Aitoff, Mercator and rectilinear projections the center is always on the equator so that the latitude is ignored if both are given; alternatively, if only one coordinate is supplied it is taken to be the longitude. Default value is the Greenwich meridian, longitude zero, and latitude 90 degrees if appropriate. For polar projections the map is oriented so that a meridian through the center is vertical on the page. See projection.
dimensions m, n: The array dimensions of the field map. Default values are 40, 79 for Hammer-Aitoff and rectilinear, 40, 40 for the others. These are usually adequate.
field E: The field element to be computed for the map where E is one of X, Y, Z, H, F, R or V. The names are the conventional geomagnetic field elements: X north, Y east, Z vertical positive down, H horizontal component, F field magnitude, and R=-Z, which is the default; V gives the scalar potential divided by the reference radius.
magnify f: The scale of the mapping is changed to enlarge the image by the factor f. The magnified image is plotted around the center of the map; see center. If f is less than unity the command is ignored.
output filename: The name of the output file to contain the regular grid of points defining a magnetic map is specified. The numbers are written in sequence across rows of the matrix, one number per line in ASCII. If multiple maps are to be plotted, each one must be assigned its own file with an output command or previous values will be overwritten by subsequent calculations. If this command is not provided, results will be sent to files in a sequence, fort.9, fort.90, fort.91, ... .
color script: Create a color contouring program to display the map and put it in the file script. If there are several maps, and the command color has been issued only once, write all the programs to the same file; note that different output files must be named for each. Alternatively each map can have its own color command with a different script file in each. Magmap launches a shell that plots the map to the screen at the end of the run, or whenever the name script is changed. If the word script is omitted, a default name tmp.plt is supplied.
contour filename: the same as color, but a contour program is written.
projection p: where p is one of A, L, O, M, R. Here A gives Hammer-Aitoff equal area projection; p=L gives Lambert equal area; p=O gives orthographic projection; p=R gives rectilinear, or longitude-latitude coordinates; p=M gives Mercator conformal projection. Orthographic projection (O) yields rather disappointing results because of the foreshortening at the map edges; Lambert is generally superior.
If no map is required enter p=N for None, or just omit the projection command. This option is useful if only point values are needed.
All the map projections are performed in a spherical approximation, and the Earth's ellipticity is neglected in the component evaluations for the maps too. For the small-scale synoptic maps of the kind normally required in geomagnetic work, the error in this approximation is unimportant. Accurate values on the spheroid with proper accounting of ellipticity are computed by the site command. See also center, color, coast.
noplot: Do not create a color or contour script after computing the map array; simply save the array to the file named in output. Overrides color and contour commands.
coast grid
coast [filename]: With a blank field, a new file called
coast10 is created from an internal datset of about 3200 points
of a coastline, transformed according to the map projection;
coast10 is read by the mapping script, named tmp.plt
by default; see color. If a filename is specified, coastline
data are read from that file, which must contain latitude-longitude
pairs; breaks are indicated by latitudes greater than 90. Obviously
your input filename should not be called coast10. When several
maps are drawn in one run of magmap, using different coastlines
or map projections, the numerical part of new the coast file name
is augmented by one for every new case, eg, coast11, coast12, etc.
If the projection is changed, a new file of transformed coastlines
will be created based on the last set of data points used. Finally,
if the filename is set to grid a latitude-longitude grid is
superimposed on the map instead of a coastline.
symbols filename type h [color=X]: It is sometimes useful to be able to plot points on the finished map. This command reads latitude-longitude pairs from the specified file, transforms them according to the current map projection, and creates a new file, symxx, containing the mapped coordinates to be read at plot time; here xx is a 2-digit integer. The symbol type and height h, hold for all points in the file. When several symbol types are required, each kind of symbol must be assigned its own file with a separate symbols command; there can be as many such files as needed. If the map projection remains constant, the symbols will be carried forward onto subsequent plots, but upon changing the projection, the current symbol set is lost unless the symbols commands are repeated. The symbol code type follows the convention in the program color: 0 square; 1 triangle; 2 octagon; 3 diamond; 4 plus; 5 asterisk; 6 cross; 7 5-ray; 8 Y upside down; 9 pentagon; 10 triangle, base up; 11 hexagon; 12 Y; 13 bar; 14 6-ray; 15 dot; 16 heptagon; 17 circle; 18 large circle (double height); 19 small filled circle; 20 small filled square; 21 small filled triangle. Colors are set by choosing X from the list: black, white, red, blue, green, yellow, orange, purple.
A blank command field deletes the current symbol set. If a new symbol set is read for a later map, this action automatically deletes any earlier symbol data because symbols commands are not cumulative across multiple maps.
Currently (Jan, 2003) this command applies only to maps made with the color command.
scale factor: Multiply the SH coefficients by the quantity factor before all other calculations. Except in the U normalization, it is assumed the coefficients are in nT and the contour map is required in muT, so there is an implicit internal factor of 0.001 applied to the contour maps.
site filename
site lat, long, alt: in the second form, enter on the
command line the geographic coordinates and altitude (in meters above
the geoid) of a single site where the field is to be computed. As
many of these commands as desired can be issued and these are
independent of any map that may be computed. For each site, all
magnetic elements are found and printed at the terminal. The results
are also written to the file fort.8. The site
commands are cleared as they are executed, so that if a second file
of coefficients is input, the sites for evaluation must be repeated.
In the first form you may enter the name of a diskfile containing locations in the same format as the in-line command: lat, long, altitude, one site per line in the file. This file is read to the end-of-file. Results are printed and written to fort.8 as before.
sums: Print the values of certain sums at the terminal. The sums are of the fully normalized coefficients, squared and weighted by a function the degree l: w1=l+1, proportional to the field energy outside the Earth's core; w2= (l+1)**2; w3= (l+1)(2l+1)**2*(2l+3)/l, proportional to the Ohmic heating within the core; w4=l(l+1)**3.
Fortran source is on the website http://igppweb.ucsd.edu/˜parker/Software/ together with this documentation.
Geocentric coordinates are often given for satellite positions. Since the site command always uses geographic coordinates (that is, corrected for ellipticity) to apply this command to satellite positions you must first make a spherical earth with the earth command. Notice that then, not only are the locations in a geocentric system, but so are the local coordinates for the magnetic elements as required.
Magmap can be used to generate maps of spherical harmonic developments of any function on a sphere, not just magnetic fields. The coefficients of the function to be mapped must be formatted as before, with one of the permitted normalizations. Then the following commands will be needed:
field V
radius 1
scale 1000
The last command cancels the implicit conversion from nanotesla to microtesla normally applied when geomagnetic models are calculated.
Here is the result of the script given at the beginning of this document. If you are looking at the PDF version you will see the graphic below. Details of this map, like its size and color palette can be changed by editing the file polar.col with knowledge of the workings of the program color.