-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathcoordinates.html
262 lines (249 loc) · 15.5 KB
/
coordinates.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<title>Coordinates - Implementation of Coords class functions for coordinate transformations — SpacePy v0.7.0 Manual</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
<link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css?v=92e3d466" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=fd3f3429" />
<link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
<script src="_static/documentation_options.js?v=fe7df9b0"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script type="text/javascript" src="_static/copybutton.js"></script>
<link rel="icon" href="_static/spacepy_favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Datamodel" href="datamodel.html" />
<link rel="prev" title="SpacePy Scripts" href="scripts.html" />
</head><body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="index.html"><img src="_static/spacepy_logo.jpg" border="0" alt="spacepy_logo"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="datamodel.html" title="Datamodel"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="scripts.html" title="SpacePy Scripts"
accesskey="P">previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">Coordinates - Implementation of Coords class functions for coordinate transformations</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="coordinates-implementation-of-coords-class-functions-for-coordinate-transformations">
<h1>Coordinates - Implementation of Coords class functions for coordinate transformations<a class="headerlink" href="#coordinates-implementation-of-coords-class-functions-for-coordinate-transformations" title="Link to this heading">¶</a></h1>
<nav class="contents local" id="table-of-contents">
<p class="topic-title">Table of Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id1">Introduction</a></p></li>
<li><p><a class="reference internal" href="#earth-centered-inertial-systems" id="id2">Earth-centered Inertial Systems</a></p></li>
<li><p><a class="reference internal" href="#magnetospheric-systems" id="id3">Magnetospheric Systems</a></p></li>
<li><p><a class="reference internal" href="#earth-fixed-systems" id="id4">Earth-fixed Systems</a></p></li>
<li><p><a class="reference internal" href="#differences-between-representations" id="id5">Differences between representations</a></p></li>
<li><p><a class="reference internal" href="#setting-options-for-coordinate-transformation" id="id6">Setting options for coordinate transformation</a></p></li>
</ul>
</nav>
<p>See also the <a class="reference internal" href="autosummary/spacepy.coordinates.html#module-spacepy.coordinates" title="spacepy.coordinates"><code class="xref py py-obj docutils literal notranslate"><span class="pre">full</span> <span class="pre">API</span> <span class="pre">documentation</span></code></a>.</p>
<section id="introduction">
<h2><a class="toc-backref" href="#id1" role="doc-backlink">Introduction</a><a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<p>The coordinate systems supported by this module cover the most commonly
used geophysical and magnetospheric systems. The naming conventions can
follow the names used by the popular IRBEM library, but for inertial
systems we use a more consistent, fine-grained naming convention that
clarifies the different systems.</p>
</section>
<section id="earth-centered-inertial-systems">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Earth-centered Inertial Systems</a><a class="headerlink" href="#earth-centered-inertial-systems" title="Link to this heading">¶</a></h2>
<blockquote>
<div><ul class="simple">
<li><p><strong>ECI2000</strong> Earth-centered Inertial, J2000 epoch</p></li>
<li><p><strong>ECIMOD</strong> Earth-centered Inertial, mean-of-date</p></li>
<li><p><strong>ECITOD</strong> Earth-centered Inertial, true-of-date</p></li>
<li><p><strong>GEI</strong> Geocentric Equatorial Inertial (IRBEM approximation of TOD)</p></li>
</ul>
</div></blockquote>
</section>
<section id="magnetospheric-systems">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Magnetospheric Systems</a><a class="headerlink" href="#magnetospheric-systems" title="Link to this heading">¶</a></h2>
<blockquote>
<div><ul class="simple">
<li><p><strong>GSM</strong> Geocentric Solar Magnetospheric</p></li>
<li><p><strong>GSE</strong> Geocentric Solar Ecliptic</p></li>
<li><p><strong>SM</strong> Solar Magnetic</p></li>
<li><p><strong>MAG</strong> Geomagnetic Coordinate System (aka CDMAG)</p></li>
</ul>
</div></blockquote>
</section>
<section id="earth-fixed-systems">
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Earth-fixed Systems</a><a class="headerlink" href="#earth-fixed-systems" title="Link to this heading">¶</a></h2>
<blockquote>
<div><ul class="simple">
<li><p><strong>GEO</strong> Geocentric geographic, aka Earth-centered Earth-fixed</p></li>
<li><p><strong>GDZ</strong> Geodetic coordinates</p></li>
</ul>
</div></blockquote>
<p>By convention <em>all</em> systems are treated as natively Cartesian except
geodetic (GDZ), which is defined in [altitude, latitude, longitude]
where altitude is relative to a reference ellipsoid. Similarly, distance
units are assumed to be Earth radii (Re) in all systems except GDZ, where
altitude is given in km. Conversions to GDZ will output altitude in km
regardless of the input distance units and conversions from GDZ will
output in Re regardless of input units. In all other cases, the distance
units will be preserved.</p>
<blockquote>
<div><div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.3.0.</span></p>
</div>
<p>The new CTrans backend was added, which includes support for the names
<code class="docutils literal notranslate"><span class="pre">ECI2000</span></code>, <code class="docutils literal notranslate"><span class="pre">ECIMOD</span></code>, <code class="docutils literal notranslate"><span class="pre">ECITOD</span></code>, and <code class="docutils literal notranslate"><span class="pre">CDMAG</span></code>. With the exception
of <code class="docutils literal notranslate"><span class="pre">ECIMOD</span></code>, these can be used with the existing IRBEM backend, and
will be converted to their closest equivalents.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.4.0.</span></p>
</div>
<p>The default backend for coordinate transformations was changed from IRBEM
to the CTrans-based SpacePy backend.</p>
</div></blockquote>
</section>
<section id="differences-between-representations">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Differences between representations</a><a class="headerlink" href="#differences-between-representations" title="Link to this heading">¶</a></h2>
<p>IRBEM’s coordinate transformations are low-accuracy and were written for
a library with a driving philosophy of speed and robustness as priorities.
The coordinate transformations are therefore approximate. Further, most of
the geophysical systems (e.g., GSE, SM) are derived from an inertial
system. It is standard practice to use ECIMOD as this system. However,
IRBEM does not currently make ECIMOD available as one of its inertial
systems. IRBEM’s default inertial system (called GEI) is consistent with
an approximation of ECITOD. Hence there will be small differences between
IRBEM’s transformations and those using SpacePy’s CTrans backend.
Further sources of difference include: IRBEM uses a low-order approximation
to the sidereal time and other parameters; the calculation of the Earth-Sun
vector differs between the representations; the definitions of an Earth
radius differ (SpacePy = 6378.137km; IRBEM = 6371.2 km). SpacePy’s in-built
representation is higher accuracy and is comprehensively tested, including
tests for consistency with other high accuracy packages such as LANLGeoMag
and AstroPy. However, for use cases where the required precision is of order
1 percent the output can be considered equivalent.</p>
</section>
<section id="setting-options-for-coordinate-transformation">
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Setting options for coordinate transformation</a><a class="headerlink" href="#setting-options-for-coordinate-transformation" title="Link to this heading">¶</a></h2>
<p>The backend for coordinate transformations can be provided at
instantiation of a <a class="reference internal" href="autosummary/spacepy.coordinates.Coords.html#spacepy.coordinates.Coords" title="spacepy.coordinates.Coords"><code class="xref py py-class docutils literal notranslate"><span class="pre">Coords</span></code></a> object using a keyword
argument. However, for convenience and flexibility the options can be
set at the module level. Configurable options include the backend used
(<a class="reference internal" href="autosummary/spacepy.irbempy.html#module-spacepy.irbempy" title="spacepy.irbempy"><code class="xref py py-mod docutils literal notranslate"><span class="pre">irbempy</span></code></a> or SpacePy’s <a class="reference internal" href="autosummary/spacepy.ctrans.html#module-spacepy.ctrans" title="spacepy.ctrans"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ctrans</span></code></a>) and the
reference ellipsoid (only configurable for the SpacePy backend). A
warning will be raised if the backend is not set (either through the
defaults or the keyword argument). The final configurable option
(<code class="docutils literal notranslate"><span class="pre">itol</span></code>) is the maximum separation, in seconds, for which the
coordinate transformations will not be recalculated. To force all
transformations to use an exact transform for the time, set <code class="docutils literal notranslate"><span class="pre">itol</span></code>
to zero. Values between 10s and 60s are recommended for speed while
also preserving accuracy, though different applications will require
different accuracies. For example, assuming this module has been
imported as <code class="docutils literal notranslate"><span class="pre">spc</span></code>, to set the SpacePy backend as the default and set
<code class="docutils literal notranslate"><span class="pre">itol</span></code> to 5 seconds:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">spc</span><span class="o">.</span><span class="n">DEFAULTS</span><span class="o">.</span><span class="n">set_values</span><span class="p">(</span><span class="n">use_irbem</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">itol</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coordinates - Implementation of Coords class functions for coordinate transformations</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#earth-centered-inertial-systems">Earth-centered Inertial Systems</a></li>
<li><a class="reference internal" href="#magnetospheric-systems">Magnetospheric Systems</a></li>
<li><a class="reference internal" href="#earth-fixed-systems">Earth-fixed Systems</a></li>
<li><a class="reference internal" href="#differences-between-representations">Differences between representations</a></li>
<li><a class="reference internal" href="#setting-options-for-coordinate-transformation">Setting options for coordinate transformation</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="scripts.html"
title="previous chapter">SpacePy Scripts</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="datamodel.html"
title="next chapter">Datamodel</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/coordinates.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="datamodel.html" title="Datamodel"
>next</a> |</li>
<li class="right" >
<a href="scripts.html" title="SpacePy Scripts"
>previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">Coordinates - Implementation of Coords class functions for coordinate transformations</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2024, The SpacePy Team.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
</div>
</body>
</html>