-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathinstall.html
326 lines (313 loc) · 22.1 KB
/
install.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
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
<!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>Installing SpacePy — 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="SpacePy Dependencies" href="dependencies.html" />
<link rel="prev" title="SpacePy 0.7.0 documentation" href="index.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="dependencies.html" title="SpacePy Dependencies"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="SpacePy 0.7.0 documentation"
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="">Installing SpacePy</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="installing-spacepy">
<h1>Installing SpacePy<a class="headerlink" href="#installing-spacepy" title="Link to this heading">¶</a></h1>
<p>The simplest way from zero (no Python) to a working SpacePy setup is:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>Install the <a class="reference external" href="https://docs.anaconda.com/anaconda/">Anaconda</a> Python
environment. 64-bit is recommended.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">--upgrade</span> <span class="pre">spacepy</span></code></p></li>
</ol>
</div></blockquote>
<p>If you already have a working Python setup, install SpacePy by:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">--upgrade</span> <span class="pre">spacepy</span></code></p></li>
</ol>
</div></blockquote>
<p>In most cases this will install a binary build of SpacePy which
includes runtime dependencies. Otherwise it will attempt to compile
from source.</p>
<p>If you are familiar with installing Python packages, have particular
preferences for managing an installation, or if the above doesn’t
work, refer to platform-specific instructions and the details
below.</p>
<p>Depending on your Python environment, you may need to explicitly
specify Python 3 throughout these commands, e.g. <code class="docutils literal notranslate"><span class="pre">pip3</span></code> instead of
<code class="docutils literal notranslate"><span class="pre">pip</span></code>.</p>
<p>The first time a user imports SpacePy, it automatically creates the
<a class="reference internal" href="configuration.html"><span class="doc">configuration directory</span></a>.</p>
<p>If you need further assistance, you can <a class="reference external" href="https://github.com/spacepy/spacepy/discussions/categories/support-and-q-a">check our support discussions</a>
and <a class="reference external" href="https://github.com/spacepy/spacepy/discussions/new?category=support-and-q-a">start a new discussion</a>
if there are no discussions on your topic of interest.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="dependencies.html">SpacePy Dependencies</a></li>
<li class="toctree-l1"><a class="reference internal" href="install_linux.html">Linux Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="install_mac.html">MacOS Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="install_windows.html">Windows Installation</a></li>
</ul>
</div>
<nav class="contents local" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#documentation" id="id1">Documentation</a></p></li>
<li><p><a class="reference internal" href="#compiling" id="id2">Compiling</a></p></li>
<li><p><a class="reference internal" href="#troubleshooting" id="id3">Troubleshooting</a></p>
<ul>
<li><p><a class="reference internal" href="#pip-failures" id="id4">pip failures</a></p></li>
<li><p><a class="reference internal" href="#irbempy" id="id5">irbempy</a></p></li>
</ul>
</li>
</ul>
</nav>
<p>SpacePy installs with the common Python distutils and pip.</p>
<p>The latest stable release is provided via <a class="reference external" href="https://pypi.org/project/SpacePy/">PyPI</a> To install from PyPI, make sure
you have pip installed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">spacepy</span>
</pre></div>
</div>
<p>If you are installing for a single user, and are not working in a
virtual environment, add the <code class="docutils literal notranslate"><span class="pre">--user</span></code> flag when installing with pip.</p>
<p>Source releases are available from <a class="reference external" href="https://pypi.org/project/SpacePy/#files">PyPI</a> and <a class="reference external" href="https://github.com/spacepy/spacepy/releases">our github</a>. Development versions
are on <a class="reference external" href="https://github.com/spacepy/spacepy">github</a>. In addition to
downloading tarballs, the development version can be directly installed
with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">git</span><span class="o">+</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">spacepy</span><span class="o">/</span><span class="n">spacepy</span>
</pre></div>
</div>
<p>For source releases, after downloading and
unpacking, run (a virtual environment, such as a conda environment, is
recommended):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">.</span>
</pre></div>
</div>
<p>or, to install for all users (not in a virtual environment):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">pip</span> <span class="n">install</span> <span class="o">.</span>
</pre></div>
</div>
<p>or, to install for a single user (not in a virtual environment):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">.</span> <span class="o">--</span><span class="n">user</span>
</pre></div>
</div>
<p>If you do not have administrative privileges, or you will be
developing for SpacePy, we strongly recommend using virtual
environments.</p>
<p>To install in custom location, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">.</span> <span class="o">--</span><span class="n">prefix</span> <span class="o">/</span><span class="n">n</span><span class="o">/</span><span class="n">packages</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python</span>
</pre></div>
</div>
<p>(See <a class="reference external" href="https://pip.pypa.io/en/stable/cli/pip_install/#install-prefix" title="(in pip v24.3)"><span class="xref std std-ref">--prefix</span></a> documentation
and the related <a class="reference external" href="https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-t" title="(in pip v24.3)"><code class="xref std std-option docutils literal notranslate"><span class="pre">--target</span></code></a>, <a class="reference external" href="https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-root" title="(in pip v24.3)"><code class="xref std std-option docutils literal notranslate"><span class="pre">--root</span></code></a>).</p>
<p>The closest analogy to the old <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> handling (no dependency
handling, no isolated build) is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">.</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">build</span><span class="o">-</span><span class="n">isolation</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">deps</span>
</pre></div>
</div>
<p>This is recommended if dependencies are managed by the OS or manually.</p>
<p>If installing into the system Python version on Linux (and potentially
some other cases), you will need to pass the flag
<a class="reference external" href="https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-break-system-packages" title="(in pip v24.3)"><code class="xref std std-option docutils literal notranslate"><span class="pre">--break-system-packages</span></code></a>. Despite the frightening name this is
usually safe, although in this case it is recommended to use
<a class="reference external" href="https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-no-build-isolation" title="(in pip v24.3)"><code class="xref std std-option docutils literal notranslate"><span class="pre">--no-build-isolation</span></code></a> <a class="reference external" href="https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-no-deps" title="(in pip v24.3)"><code class="xref std std-option docutils literal notranslate"><span class="pre">--no-deps</span></code></a> and manage the
dependencies using the system package manager or conda.</p>
<section id="documentation">
<h2><a class="toc-backref" href="#id1" role="doc-backlink">Documentation</a><a class="headerlink" href="#documentation" title="Link to this heading">¶</a></h2>
<p>If you want to build the documentation yourself (rather than using the
online documentation), install sphinx and numpydoc. The easiest way is
via pip:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">sphinx</span> <span class="n">numpydoc</span>
</pre></div>
</div>
<p>They are also available via conda:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">install</span> <span class="n">sphinx</span> <span class="n">numpydoc</span>
</pre></div>
</div>
</section>
<section id="compiling">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Compiling</a><a class="headerlink" href="#compiling" title="Link to this heading">¶</a></h2>
<p>With the dependencies installed, SpacePy can be built from source.
You can always get the latest source code for SpacePy from our <a class="reference external" href="https://github.com/spacepy/spacepy">github
repository</a> and the latest
release from <a class="reference external" href="https://pypi.org/project/SpacePy/#files">PyPI</a></p>
<p>Following the instructions above will compile before the installation,
if installing from source or a binary installer is not available. If
this fails, specify the name of, or full path to, the Fortran compiler
with the <code class="docutils literal notranslate"><span class="pre">FC</span></code> environment variable, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FC</span><span class="o">=/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">gfortran</span> <span class="n">pip</span> <span class="n">install</span> <span class="o">.</span>
<span class="n">FC</span><span class="o">=</span><span class="n">arm64</span><span class="o">-</span><span class="n">apple</span><span class="o">-</span><span class="n">darwin20</span><span class="mf">.0.0</span><span class="o">-</span><span class="n">gfortran</span> <span class="n">pip</span> <span class="n">install</span> <span class="o">.</span>
</pre></div>
</div>
<p>The supported compiler is the current GNU gfortran compiler, also
called <code class="docutils literal notranslate"><span class="pre">gnu95</span></code>.</p>
<p>If defined, the <code class="docutils literal notranslate"><span class="pre">LDFLAGS</span></code> environment variable is also honored when
linking irbem. The contents must be valid <code class="docutils literal notranslate"><span class="pre">gfortran</span></code> flags.</p>
<p>If irbem compilation fails, SpacePy will install without <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>
support. This can be forced by e.g. setting <code class="docutils literal notranslate"><span class="pre">FC</span></code> to
<code class="docutils literal notranslate"><span class="pre">/usr/bin/false</span></code>.</p>
</section>
<section id="troubleshooting">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Link to this heading">¶</a></h2>
<section id="pip-failures">
<span id="install-pip-failures"></span><h3><a class="toc-backref" href="#id4" role="doc-backlink">pip failures</a><a class="headerlink" href="#pip-failures" title="Link to this heading">¶</a></h3>
<p>If <code class="docutils literal notranslate"><span class="pre">pip</span></code> completely fails to build, a common issue is a failure in
the isolated build environment that <code class="docutils literal notranslate"><span class="pre">pip</span></code> sets up. Usually this can
be addressed by eschewing the separate build environment:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">spacepy</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">build</span><span class="o">-</span><span class="n">isolation</span>
</pre></div>
</div>
<p>Another option is manually installing all dependencies (via <code class="docutils literal notranslate"><span class="pre">pip</span></code>,
<code class="docutils literal notranslate"><span class="pre">conda</span></code>, or other means) and then installing from an unpacked source
release with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">build</span><span class="o">-</span><span class="n">isolation</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">deps</span> <span class="o">.</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">pip</span></code> suppresses detailed output from the build process. To
troubleshoot a failure to install, it is useful to write this detailed
output to a file using the <code class="docutils literal notranslate"><span class="pre">--log</span></code> option, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">spacepy</span> <span class="o">--</span><span class="n">log</span><span class="o">=</span><span class="n">install_log</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
<p>Please include this log file if opening an issue related to installation.</p>
<p><code class="docutils literal notranslate"><span class="pre">pip</span></code> will also cache packages; unfortunately sometimes it will use
a cached package which is incompatible with the current
environment. In that case, try clearing the cache first, so all
locally-compiled packages are rebuilt:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">cache</span> <span class="n">purge</span>
</pre></div>
</div>
</section>
<section id="irbempy">
<h3><a class="toc-backref" href="#id5" role="doc-backlink">irbempy</a><a class="headerlink" href="#irbempy" title="Link to this heading">¶</a></h3>
<p>The most common failures relate to compilation of the IRBEM
library. Unfortunately <code class="docutils literal notranslate"><span class="pre">pip</span></code> will hide these warnings, so they
manifest when running <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">spacepy.irbempy</span></code> (or some other
component of SpacePy that uses irbempy).</p>
<p>The error <code class="docutils literal notranslate"><span class="pre">RuntimeError:</span> <span class="pre">cannot</span> <span class="pre">load</span> <span class="pre">IRBEM</span> <span class="pre">library;</span> <span class="pre">irbempy</span> <span class="pre">is</span> <span class="pre">not</span>
<span class="pre">available.</span></code> means the IRBEM library did not compile at
all. This is most likely a compiler issue: either there is no Fortran
compiler, or, when using conda on <a class="reference internal" href="install_mac.html"><span class="doc">Mac</span></a>, the correct
SDK version has not been installed.</p>
</section>
</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="#">Installing SpacePy</a><ul>
<li><a class="reference internal" href="#documentation">Documentation</a></li>
<li><a class="reference internal" href="#compiling">Compiling</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#pip-failures">pip failures</a></li>
<li><a class="reference internal" href="#irbempy">irbempy</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">SpacePy 0.7.0 documentation</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="dependencies.html"
title="next chapter">SpacePy Dependencies</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/install.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="dependencies.html" title="SpacePy Dependencies"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="SpacePy 0.7.0 documentation"
>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="">Installing SpacePy</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>