Skip to content

Commit 93d7024

Browse files
joa-quimjoa-quim
committed
magref
1 parent 5d4ca7a commit 93d7024

File tree

5 files changed

+213
-7
lines changed

5 files changed

+213
-7
lines changed

‎_libs/lunr/lunr_index.js

+2-2
Large diffs are not rendered by default.

‎documentation/all_docs_ref/all_refs.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737
## Supplemental Modules (Potential methods)
3838
| | | | | | | | |
3939
|:-----|:----|:----|:----|:----|:----|:----|:----|
40-
| \myreflink{gravmag3d} | \myreflink{gravfft} | \myreflink{grdgravmag3d} | \myreflink{gravprisms} | \myreflink{parkergrav} | \myreflink{parkermag} | | |
40+
| \myreflink{gravmag3d} | \myreflink{gravfft} | \myreflink{grdgravmag3d} | \myreflink{gravprisms} | \myreflink{magref} | \myreflink{parkergrav} | \myreflink{parkermag} | |
4141

4242
## Supplemental Modules (short docs)
4343

‎documentation/modules/magref.md

+207
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# magref
2+
3+
```julia
4+
magref(cmd0::String=""; kwargs...)
5+
```
6+
7+
*keywords: GMT, Julia, Geomagnetic, IGRF, CM4*
8+
9+
Description
10+
-----------
11+
12+
Evaluates the IGRF or the CM4 geomagnetic models at the specified locations and times.
13+
14+
Required Arguments
15+
------------------
16+
17+
None.
18+
19+
Optional Arguments
20+
------------------
21+
22+
*input*
23+
Contains the moments in space-time where we want to evaluate the magnetic reference field.
24+
The first two columns must contain longitude and latitude (however, see **yx** for latitude and
25+
longitude instead). Normally, the third and fourth columns must contain altitude (in km) and time,
26+
respectively, but if one or both of these are constant for all records they can be supplied via the
27+
**adjust** option instead and are thus not expected in the input file. The alternative to provide the
28+
_x,y_ locations is to use the **region** and (when grids are not global) the **inc** options.
29+
With them we get the results in a grid form. It requires setting *time* and *altitude* via the
30+
**adjust** option.
31+
32+
A note about the CM4 validity domain. The core field of CM4 is valid from 1960-2002.5 but the
33+
ionospheric and magnetospheric fields are computed after the *Dst* and *F10.7* coefficient files.
34+
We extended here those coefficient files up to 2006, which means that one can compute external
35+
contributions up until 2006 but the Secular Variation will be biased (non reliable). New indices
36+
files may be retrieved from from:ftp://ftp.ngdc.noaa.gov/STP/GEOMAGNETIC_DATA/INDICES/DST/ (the *Dst* coefficients)
37+
and http://umbra.nascom.nasa.gov/sdb/yohkoh/ys_dbase/indices_flux_raw/Penticton_Absolute/monthly/MONTHPLT.ABS
38+
(The *F10.7* index file is a MONTHPLT.ABS). **Note**: since the *Dst* files in the .../DST/ directory
39+
are still only up to 2006, for GMT4.5.3 and after we extended the *Dst* until August 2009 by reformatting
40+
the data in the preliminary file Est_Ist_index_0_mean.pli, which is at
41+
ftp://ftp.ngdc.noaa.gov/STP/GEOMAGNETIC_DATA/INDICES/EST_IST/. But since
42+
this site is now also outdated, we get the DST indices from
43+
http://wdc.kugi.kyoto-u.ac.jp/dstae/index.html However, for the most recent dates those indices are
44+
"Quick Look" (the best are the "Definitive" type). Because the *F10.7* from the MONTHPLT.ABS file mentioned
45+
above are apparently no being updated, we found another place where they are, which is:
46+
ftp://ftp.ngdc.noaa.gov/STP/space-weather/solar-data/solar-features/
47+
solar-radio/noontime-flux/penticton/penticton_absolute/listings/
48+
listing_drao_noontime-flux-absolute_monthly.txt
49+
50+
Another update in January 2025. The NASA site above no longer updated its data and now we use *F10.7* data
51+
downloaded from https://celestrak.org/spacedata/SW-All.csv (Matlab refences this site as well). But it
52+
contains only daily data. Hence we computed the montly averages. However, comparing previous and computed
53+
averages from this site show some differences. For example the first 4 months of 2018 (replaced to in this
54+
update) compare like this: [609 632 608 634] (nasa) _vs_ [699 725 683 700] (celestrak).
55+
56+
- **A** or **adjust** : -- *input_params=(alt|altitude=true, onetime=true, yeardec=true)*\
57+
Adjusts how the input record is interpreted. Use **alt=true** to set a fixed *altitude* (in km) that should
58+
apply to all data records [Default expects *altitude* to be in the 3rd column of all records]. Use
59+
**onetime=true** to set a fixed *time* that should apply to all data records [Default expects *time* to be in
60+
the 4th column of all records]. Finally, use **yeardec=true** to indicate that all times are specified as
61+
decimal years [Default is ISO _date_T_colck_ format, see
62+
[IME_EPOCH](https://docs.generic-mapping-tools.org/dev/gmt.conf.html#term-TIME_EPOCH)].\
63+
**NOTE**: This basically only applies when passing data via a file, where we have no chance to know if time
64+
was passed as decimar years or as a DateTime string. When passing data directly in numeric form, we try to
65+
guess all this for you. So, for example, you can do `magref([-28 38 0 "2001-05-01T12:00:00"], internal=...)`
66+
or `magref([-28 38 0 2001.330137], ...)` and we do the guessings. If input has only two columns, we assume
67+
an altitude of zero and current time.
68+
69+
- **C** or **cm4file** : -- *cm4file=file*\
70+
Specify an alternate CM4 coefficient file [umdl.CM4].
71+
72+
- **D** or **dstfile** : -- *dstfile=file*
73+
Specify an alternate file with hourly means of the Dst index for CM4 [Dst_all.wdc].
74+
Alternatively, simply specify a single index to apply for all records.
75+
76+
- **E** or **f107file** : -- *f107file=file*
77+
Specify an alternate file with monthly means of absolute F10.7 solar radio flux for CM4 [F107_mon.plt].
78+
Alternatively, specify a single flux to apply for all records.
79+
80+
- **F** or **internal** : -- *internal=flags* **|** *internal=(all_input=true, total|T=true, horizontal|H=true, X=true, Y=true, Z=true, dec|declination=true, inc|inclination=true, IGRF=true, CM4core=true, CM4litho=true, CM4mag_p=true, CM4mag_i=true, CM4iono_p=true, CM4iono_i=true, CM4toroid=true, IGRG_CM4=true)*\
81+
Selects output items; Use, **in alternative**, the expanded form or the *flags* string made up of one or more of these characters:
82+
- **r** or **all_input=true** means output all input columns before adding the items below
83+
- **t** or **total|T=true** means list total field (nT).
84+
- **h** or **horizontal|H=true** means list horizontal field (nT).
85+
- **x** or **X=true** means list X component (nT, positive north).
86+
- **y** or **Y=true** means list Y component (nT, positive east).
87+
- **z** or **Z=true** means list Z component (nT, positive down).
88+
- **d** or **dec|declination=true** means list declination (deg, clockwise from north).
89+
- **i** or **inc|inclination=true** means list inclination (deg, positive down).
90+
Select requested field contribution(s) using either the keyword **or** append one or more numbers after a slash (**/**):
91+
- **0** or **IGRF=true** means IGRF field (no combinations allowed)
92+
- **1** or **CM4core=true** means CM4 Core field
93+
- **2** or **CM4litho=true** means CM4 Lithospheric field
94+
- **3** or **CM4mag_p=true** means CM4 Primary Magnetospheric field
95+
- **4** or **CM4mag_i=true** means CM4 Induced Magnetospheric field
96+
- **5** or **CM4iono_p=true** means CM4 Primary ionospheric field
97+
- **6** or **CM4iono_i=true** means CM4 Induced ionospheric field
98+
- **7** or **CM4toroid=true** means CM4 Toroidal field
99+
- **9** or **IGRG_CM4=true** means Core field from IGRF and other contributions from CM4.
100+
Do **not** use both **IGRF** and **IGRG_CM4** (or **0** and **9**).
101+
102+
Using several of the fiels contribution options (or appending several numbers (1-7)) will add up the different
103+
contributions. For example **internal=(total=true, CM4core=true, CM4litho=true)** (or **internal=t/12**)
104+
computes the total field due to Core and Lithospheric sources. The special case, that mixes Core field from
105+
IGRF and other sources from CM4, **internal=t/934** computes Core field due to IGRF plus terms 3 and 4
106+
from CM4 (but you can add others). This case is very important to be able to continue to use the CM4 model
107+
outside of its original time validity limits. The data is written out in the
108+
order they appear in *flags* [Default is **F=rthxyzdi/1**].
109+
110+
- **G** or **geocentric** : -- *geocentric=true*\
111+
Specifies that coordinates are geocentric [geodetic].
112+
113+
\textinput{common_opts/opt_I}
114+
115+
- **L** or **external** : -- *external=(all_input=true, total|T=true, X=true, Y=true, Z=true, mag_i=true, iono_p=true, iono_i=true, poloidal=true)*\
116+
Computes J field vectors from certain external sources.
117+
- **r** or **all_input=true** means output all input columns before adding the items below (all in Ampers/m).
118+
- **t** or **total|T=true** means list magnitude field.
119+
- **x** or **X=true** means list X component.
120+
- **y** or **Y=true** means list Y component.
121+
- **z** or **Z=true** means list Z or current function Psi.
122+
Append a number to indicate the requested J contribution:
123+
- **1** or **mag_i=true** means Induced Magnetospheric field.
124+
- **2** or **iono_p=true** means Primary ionospheric field.
125+
- **3** or **iono_i=true** means Induced ionospheric field.
126+
- **4** or **poloidal=true** means Poloidal field.
127+
128+
\textinput{common_opts/opt_R}
129+
130+
- **Sc** or **core_coef** : -- *core_coef=(low,high)*\
131+
Limits the wavelengths of the core field contribution to the band
132+
indicated by the low and high spherical harmonic order [1/13].
133+
134+
- **Sl** or **litho_coef** : -- *litho_coef=(low,high)*\
135+
Limits the wavelengths of the lithosphere field contribution to the
136+
band indicated by the low and high spherical harmonic order [14/65].
137+
138+
\textinput{common_opts/opt_V}
139+
140+
\textinput{common_opts/opt_bi}
141+
142+
\textinput{common_opts/opt_h}
143+
144+
\textinput{common_opts/opt_o}
145+
146+
\textinput{common_opts/opt_yx}
147+
.. include:: ../../explain_colon.rst_
148+
149+
Time Settings
150+
-------------
151+
152+
If binary input files are used then absolute time are stored as time relative to the
153+
selected epoch. However, since the epoch used is not stored in the data files there
154+
can be problems decoding the correct time. The mgd77 supplement uses the Unix time
155+
system as its default; thus you should make sure that binary data files with time
156+
uses the same system (see the GMT default TIME_SYSTEM).
157+
158+
Examples
159+
--------
160+
161+
To get the CM4 Total field, Declination and Inclination due to all but lithospheric
162+
and toroidal field at a one point location and decimal time 2000.0, do
163+
164+
```julia
165+
magref([-28 38 0 2000.0], internal=(T=true, dec=true, inc=true, CM4core=true, CM4litho=true, CM4mag_p=true))
166+
1×3 GMTdataset{Float64, 2}
167+
Row │ col.1 col.2 col.3
168+
─────┼───────────────────────────
169+
1 │ 43795.6 -12.1047 54.178
170+
```
171+
172+
To do the same as above but at noon (Universal Time) of first May 2001, try
173+
(note, we now use the condensed form of specifying the field components):
174+
175+
```julia
176+
D = magref([-28 38 0 "2001-05-01T12:00:00"], internal="tdi/123")
177+
1×3 GMTdataset{Float64, 2}
178+
Row │ col.1 col.2 col.3
179+
─────┼───────────────────────────
180+
1 │ 43758.0 -11.866 54.0388
181+
```
182+
183+
And to see the IGRF field at 2025.0. Since we are not specifying the grid increments
184+
(**inc**) it will assume a **inc=0.25** degrees.
185+
186+
\begin{examplefig}{}
187+
```julia
188+
using GMT
189+
190+
G = magref(R=:d, onetime=2025);
191+
viz(G, coast=true, colorbar=true)
192+
```
193+
\end{examplefig}
194+
195+
See Also
196+
--------
197+
198+
\myreflink{mgd77track}
199+
200+
References
201+
----------
202+
203+
Comprehensive Modeling of the Geomagnetic Field, see
204+
`<https://doi.org/10.1111/j.1365-246X.2004.02421.x>`_.
205+
206+
The International Geomagnetic Reference Field (IGRF), see
207+
`<https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html>`_.

‎documentation/supplements.txt

-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ mgd77convert*
1818
mgd77header*
1919
mgd77info*
2020
mgd77list*
21-
mgd77magref*
2221
mgd77manage*
2322
mgd77path*
2423
mgd77sniffer*

‎gallery/ex40.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ plot!("@GSHHS_h_Australia.txt", pen=:faint, fill=(240,255,240))
1818
plot!("@GSHHS_h_Australia.txt", ms=0.025, fill=:red)
1919
T500k = gmtsimplify("@GSHHS_h_Australia.txt", tolerance="500k");
2020
t = gmtspatial("@GSHHS_h_Australia.txt", colinfo=:g, length=:k);
21-
area = GMT.@sprintf("Full area = %.0f km@+2@+", t.data[3]);
21+
area = @sprintf("Full area = %.0f km@+2@+", t.data[3]);
2222
t = gmtspatial(T500k, colinfo=:g, length=:k);
23-
area_T500k = GMT.@sprintf("Reduced area = %.0f km@+2@+", t.data[3]);
23+
area_T500k = @sprintf("Reduced area = %.0f km@+2@+", t.data[3]);
2424
plot!(T500k, pen=(1,:blue))
2525
plot!(centroid, marker=:cross, ms=0.75, ml=3)
2626
text!(text_record([112 -10], "T = 500 km"), offset=(away=true, shift=(0.25,0.25)), font=18, justify=:TL)
@@ -31,7 +31,7 @@ plot!("@GSHHS_h_Australia.txt", pen=:faint, fill=(240,255,240))
3131
plot!("@GSHHS_h_Australia.txt", ms=0.025, fill=:red)
3232
T100k = gmtsimplify("@GSHHS_h_Australia.txt", tolerance="100k");
3333
t = gmtspatial(T100k, colinfo=:g, length=:k);
34-
area_T100k = GMT.@sprintf("Reduced area = %.0f km@+2@+", t.data[3]);
34+
area_T100k = @sprintf("Reduced area = %.0f km@+2@+", t.data[3]);
3535
plot!(T100k, pen=(1,:blue))
3636
plot!(centroid, marker=:cross, ms=0.75, ml=3)
3737
text!(text_record([112 -10], "T = 100 km"), offset=(away=true, shift=(0.25,0.25)), font=18, justify=:TL)

0 commit comments

Comments
 (0)