Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       mgd77magref - Evaluate the IGRF or CM4 magnetic field models

SYNOPSIS

       mgd77magref [ inputfile ] [ [+aalt+tdate+y] ] [ cm4file ] [ Dstfile ] [ f107file ] [ flags
       ] [  ] [ c|llow/high ] [ [level] ] [ -b<binary> ] [ -f<flags> ] [ -h<headers> ] [  -:[i|o]
       ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       mgd77magref  will  evaluate  the  IGRF  or  the  CM4  geomagnetic  models at the specified
       locations and times.

REQUIRED ARGUMENTS

       None.

OPTIONAL ARGUMENTS

       inputfile
              Contains the moments in space-time where we want to evaluate the magnetic reference
              field.  The  first two columns must contain longitude and latitude (however, see -:
              for latitude and longitude instead). Normally, the third and  fourth  columns  must
              contain  altitude  (in  km) and time, respectively, but if one or both of these are
              constant for all records they can be supplied via the -A  option  instead  and  are
              thus  not  expected in the input file.  If no input file is given we read stdin.  A
              note about the CM4 validity domain. The core field of CM4 is valid from 1960-2002.5
              but  the ionospheric and magnetospheric fields are computed after the Dst and F10.7
              coefficient files. We extended here those coefficient files up to 2006, which means
              that one can compute external contributions up until 2006 but the Secular Variation
              will  be  biased  (non  reliable).  New  indices  files  may  be   retrieved   from
              from:ftp://ftp.ngdc.noaa.gov/STP/GEOMAGNETIC_DATA/INDICES/DST/       (the       Dst
              coefficients)                                                                   and
              http://umbra.nascom.nasa.gov/sdb/yohkoh/ys_dbase/indices_flux_raw/Penticton_Absolute/monthly/MONTHPLT.ABS
              (The F10.7 index file is a MONTHPLT.ABS). NOTE: since the Dst files in the .../DST/
              directory  are  still  only  up to 2006, for GMT4.5.3 and after we extended the Dst
              until  August  2009  by   reformatting   the   data   in   the   preliminary   file
              Est_Ist_index_0_mean.pli,                 which                is                at
              ftp://ftp.ngdc.noaa.gov/STP/GEOMAGNETIC_DATA/INDICES/EST_IST/. But since this  site
              is    now    also    outdated,    we    now    get    the    DST    indices    from
              http://wdc.kugi.kyoto-u.ac.jp/dstae/index.html However, for the most  recent  dates
              those  indices  are "Quick Look" (the best are the "Definitive" type).  Because the
              F10.7 from the MONTHPLT.ABS file mentioned above are apparently no  being  updated,
              we      found      another      place     where     they     are,     which     is:
              ftp://ftp.ngdc.noaa.gov/STP/space-weather/solar-data/solar-features/
              solar-radio/noontime-flux/penticton/penticton_absolute/listings/
              listing_drao_noontime-flux-absolute_monthly.txt

       -A[+aalt+tdate+y]
              Adjusts how the input record is interpreted. Append +a to set a fixed altitude  (in
              km)  that  should  apply to all data records [Default expects altitude to be in the
              3rd column of all records].  Append +t to set a fixed time that should apply to all
              data  records  [Default  expects  time  to  be  in  the 4th column of all records].
              Finally, append +y to indicate that  all  times  are  specified  as  decimal  years
              [Default is ISO dateTcolck format, see TIME_EPOCH].

       -Ccm4file
              Specify an alternate CM4 coefficient file [umdl.CM4].

       -DDstfile
              Specify an alternate file with hourly means of the Dst index for CM4 [Dst_all.wdc].
              Alternatively, simply specify a single index to apply for all records.

       -Ef107file
              Specify an alternate file with monthly means of absolute F10.7 solar radio flux for
              CM4  [F107_mon.plt].  Alternatively,  simply specify a single flux to apply for all
              records.

       -Fflags
              Selects output items; flags is a string made up of one or more of these characters:

              r means output all input columns before adding the items below

              t means list total field (nT).

              h means list horizontal field (nT).

              x means list X component (nT, positive north).

              y means list Y component (nT, positive east).

              z means list Z component (nT, positive down).

              d means list declination (deg, clockwise from north).

              i means list inclination (deg, positive down).

              Append one or more number to indicate the requested field contribution(s):

              0 means IGRF field (no combinations allowed)

              1 means CM4 Core field

              2 means CM4 Lithospheric field

              3 means CM4 Primary Magnetospheric field

              4 means CM4 Induced Magnetospheric field

              5 means CM4 Primary ionospheric field

              6 means CM4 Induced ionospheric field

              7 means CM4 Toroidal field

              9 means Core field from IGRF and other contributions from CM4.  DO NOT USE  BOTH  0
              AND 9.

              Appending  several  numbers  (1-7)  will  add  up  the different contributions. For
              example -Ft/12 computes the total field due to Core and Lithospheric  sources.  Two
              special  cases  are allowed, which mix which Core field from IGRF and other sources
              from CM4.  -Ft/934 computes Core field due to IGRF plus terms 3 and 4 from CM4 (but
              you can add others). -Ft/934 the same as above but output the field components. The
              data is written out in the order they appear in flags [Default is -Frthxyzdi/1].

       -G     Specifies that coordinates are geocentric [geodetic].

       -L     Computes J field vectors from certain external sources.

              r means output all input columns before adding the items below (all in Ampers/m).

              t means list magnitude field.

              x means list X component.

              y means list Y component.

              z means list Z or current function Psi.

              Append a number to indicate the requested J contribution:

              1 means Induced Magnetospheric field.

              2 means Primary ionospheric field.

              3 means Induced ionospheric field.

              4 means Poloidal field.

       -Sclow/high
              Limits the wavelengths of the core field contribution to the band indicated by  the
              low and high spherical harmonic order [1/13].

       -Sllow/high
              Limits  the wavelengths of the lithosphere field contribution to the band indicated
              by the low and high spherical harmonic order [14/65].

       -V[level] (more ...)
              Select verbosity level [c].

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 4 input columns unless -A is used].

       -bo[ncols][type] (more ...)
              Select native binary output. [Default is reflected by -F].

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s).

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              use just -).

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  of  any
              module-specific option (but not the GMT common options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation of  options,  then
              exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

TIME SETTINGS

       If  binary  input  files  are  used  then absolute time are stored as time relative to the
       selected epoch. However, since the epoch used is not stored in the data files there can be
       problems  decoding the correct time. The mgd77 supplement uses the Unix time system as its
       default; thus you should make sure that binary data files with time uses the  same  system
       (see the GMT default TIME_SYSTEM).

EXAMPLES

       To  get  the  CM4 Total field, Declination and Inclination due to all but lithospheric and
       toroidal field at a one point location and decimal time 2000.0, try

              echo -28 38 0 2000.0 | gmt mgd77magref -A+y -Ftdi/13456

       To do the same as above but at noon (Universal Time) of first May 2001, try

              echo -28 38 0 2001-05-01T12:00:00 | gmt mgd77magref -Ftdi/13456

SEE ALSO

       gmt, mgd77info, mgd77list, mgd77manage, mgd77track, gmt.conf

REFERENCES

       Comprehensive Modeling of the Geomagnetic Field, see http://denali.gsfc.nasa.gov/cm/

       The      International      Geomagnetic      Reference       Field       (IGRF),       see
       http://www.iugg.org/IAGA/iaga_pages/pubs_prods/igrf.htm

COPYRIGHT

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe