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.
earth a, b, aref: The coefficients are computed with respect to a reference radius, aref in km; 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 also 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 IAGA IGRF-10 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-2005 in steps of 5 years. The data set is the
IAGA IGRF-10 set; see
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 remaining 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 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.
dimensions m, n: The array dimensions of the field map.
Default values are 40, 79 for 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. 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. 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.
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, temp.con. 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.
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
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 sirisaac in ˜parker/General/Magmap along
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, so that degree zero is permitted for internal source fields.
The coefficients of the function to be mapped must be
formatted as before, with one of the permitted normalizations.
Fields with external sources can be specified by setting the degree
negative in the input file, though not with serial input.
or
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.
Notes