-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathinstallation_and_structure.html
More file actions
377 lines (257 loc) · 19.5 KB
/
installation_and_structure.html
File metadata and controls
377 lines (257 loc) · 19.5 KB
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
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>4. Installation and Project Structure — Cherab 1.5.0 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/theme_overrides.css" type="text/css" />
<link rel="stylesheet" href="_static/tabs.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="5. Available Packages" href="available_modules.html" />
<link rel="prev" title="3. Project Governance" href="governance.html" />
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Cherab
</a>
<div class="version">
1.5
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="welcome.html">1. Welcome</a></li>
<li class="toctree-l1"><a class="reference internal" href="licence.html">2. Licence</a></li>
<li class="toctree-l1"><a class="reference internal" href="governance.html">3. Project Governance</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">4. Installation and Project Structure</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#prerequisites">4.1. Prerequisites</a></li>
<li class="toctree-l2"><a class="reference internal" href="#project-structure">4.2. Project Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installation">4.3. Installation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#installing-through-pip">4.3.1. Installing through Pip</a></li>
<li class="toctree-l3"><a class="reference internal" href="#installing-from-source">4.3.2. Installing from source</a></li>
<li class="toctree-l3"><a class="reference internal" href="#installing-for-development">4.3.3. Installing for development</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#configuring-atomic-data">4.4. Configuring Atomic Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#testing">4.5. Testing</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="available_modules.html">5. Available Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="atomic/atomic_data.html">6. Atomic Data</a></li>
<li class="toctree-l1"><a class="reference internal" href="plasmas/plasmas.html">7. Plasmas</a></li>
<li class="toctree-l1"><a class="reference internal" href="models/emission_models.html">8. Emission Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="math/math.html">9. Function Framework</a></li>
<li class="toctree-l1"><a class="reference internal" href="tools/tools.html">10. Tools</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Demonstrations</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html">Atomic Data</a></li>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html#creating-plasmas">Creating Plasmas</a></li>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html#surface-radiation-loads">Surface Radiation Loads</a></li>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html#active-spectroscopy">Active Spectroscopy</a></li>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html#passive-spectroscopy">Passive Spectroscopy</a></li>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html#bolometry">Bolometry</a></li>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html#geometry-matrices">Geometry Matrices</a></li>
<li class="toctree-l1"><a class="reference internal" href="demonstrations/demonstrations.html#code-examples-gallery">Code examples gallery</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Cherab</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li><span class="section-number">4. </span>Installation and Project Structure</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/installation_and_structure.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="installation-and-project-structure">
<h1><span class="section-number">4. </span>Installation and Project Structure<a class="headerlink" href="#installation-and-project-structure" title="Permalink to this heading">¶</a></h1>
<section id="prerequisites">
<h2><span class="section-number">4.1. </span>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading">¶</a></h2>
<p>The Cherab package requires Python 3.5+, numpy, scipy, matplotlib and <a class="reference external" href="https://raysect.github.io/documentation/">Raysect</a>.
Scipy version 0.13 or higher is recommended. IPython is recommended for interactive use.</p>
</section>
<section id="project-structure">
<h2><span class="section-number">4.2. </span>Project Structure<a class="headerlink" href="#project-structure" title="Permalink to this heading">¶</a></h2>
<p>Cherab is a large code framework consisting of a main core package and many smaller feature
packages. The overall structure of the framework is best visualised as onion shells. The full
project structure is most relevant for researchers in fusion plasma physics. Researchers in other
areas such as industrial plasmas and astrophysics will only require layers 1, 2 for their
applications.</p>
<figure class="align-center" id="id5">
<a class="reference internal image-reference" href="_images/CHERAB_structure.png"><img alt="_images/CHERAB_structure.png" src="_images/CHERAB_structure.png" style="width: 650px;" /></a>
<figcaption>
<p><span class="caption-text"><strong>Caption:</strong> A high level diagram illustrating the structure of the Cherab framework.</span><a class="headerlink" href="#id5" title="Permalink to this image">¶</a></p>
</figcaption>
</figure>
<p><strong>1. Ray-tracing Engine:</strong> Cherab was built on top of a ray-tracing engine to provide all the core
ray-tracing functionality, mesh handling, etc. <a class="reference external" href="https://raysect.github.io/documentation/">Raysect</a> is currently
the only ray-tracing engine supported, but the framework has been designed such that this
component is interchangeable. Support for other ray-tracers may be added in the future.</p>
<p><strong>2. Core API Module:</strong> The <a class="reference external" href="https://pypi.org/project/cherab">cherab</a> package defines
all the API interfaces for the whole framework. It defines all the core functionality such
as: how plasmas are defined and the properties that can be computed from them; the types of
atomic data that can be used in spectroscopic calculations; and the types of plasma emission
that Cherab can calculate. This package is strictly managed by the Cherab development team.</p>
<p><strong>3a. Atomic Data Providers:</strong> Almost all of the plasma emission models implemented in Cherab
require some type of atomic data for their calculations. The base types of reaction rates and
photon emissivity coefficients are defined in the Core API Module,
<a class="reference external" href="https://pypi.org/project/cherab">cherab</a>. A default atomic data source module based on
the <a class="reference external" href="http://open.adas.ac.uk/">OpenADAS project</a>, is included in the package. In future
other atomic data sources, such as the ALADDIN database for example, could be made available
through additional packages.</p>
<p><strong>3b. Machine Specific Packages:</strong> These components are for functionality associated with
a specific fusion experiment. For example, each experiment tends to have its own systems
for loading and saving experiment/simulation data. These packages allow the local facility
experts to provide models and diagnostic settings that are unique to their experiments.</p>
<p><strong>4. User Packages:</strong> This is the layer where most Cherab users will do their work.
Code in this layer will usually take the form of scripts configured for a particular
analysis pipeline such as performing a synthetic diagnostic simulation or fitting some
measured data. These projects may just be collections of scripts owned by diagnostic
responsible officers or they could be organised into formal packages.</p>
</section>
<section id="installation">
<h2><span class="section-number">4.3. </span>Installation<a class="headerlink" href="#installation" title="Permalink to this heading">¶</a></h2>
<p>Users will generally just install the core package and the specific feature packages they
need for their work. For example, users working on the JET tokamak will require the
<a class="reference external" href="https://pypi.org/project/cherab">cherab</a> package and the <a class="reference external" href="https://github.com/cherab/jet">cherab-jet</a>
package. The core <code class="docutils literal notranslate"><span class="pre">cherab</span></code> package is available through pip. The additional fusion specific
packages, offering extra functionality, should be cloned from their respective repositories.</p>
<section id="installing-through-pip">
<h3><span class="section-number">4.3.1. </span>Installing through Pip<a class="headerlink" href="#installing-through-pip" title="Permalink to this heading">¶</a></h3>
<p>Cherab is available from the python package repository <a class="reference external" href="https://pypi.org/project/cherab">pypi</a>.
Unless developing new code for a cherab package, most users should use the latest versioned release
packages available through pypi.</p>
<p>The easiest way to install Cherab with OpenADAS is using <a class="reference external" href="https://pip.pypa.io/en/stable/">pip</a>:</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">cherab</span>
</pre></div>
</div>
<p>This will either install a binary package or build Cherab from source (which may take some time).
If you don’t have administrator access to install the packages, add the <code class="docutils literal notranslate"><span class="pre">--user</span></code> flag to the above
line to install the packages under your own user account. Alternatively, consider using a
<a class="reference external" href="https://docs.python.org/3/tutorial/venv.html">virtual environment</a> to avoid the risk of
conflicting versions of packages in your Python environment.</p>
<p>By default, pip will install from wheel archives on PyPI. If a binary wheel is not available for
your version of Python, or if you are installing from source in editable mode for development (see
below), the package will be compiled locally on your machine. Compilation is done in parallel by
default, using all available processors, but can be overridden by setting the environment variable
<code class="docutils literal notranslate"><span class="pre">CHERAB_NCPU</span></code> to the number of processors to use.</p>
</section>
<section id="installing-from-source">
<h3><span class="section-number">4.3.2. </span>Installing from source<a class="headerlink" href="#installing-from-source" title="Permalink to this heading">¶</a></h3>
<p>If pip is not available the source files can be downloaded from <a class="reference external" href="https://pypi.org/project/cherab">pypi</a>
or from our <a class="reference external" href="https://github.com/cherab/core">development repository</a>. Once you have the source files,
locate the folder containing setup.py and run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span>
</pre></div>
</div>
<p>If all the required dependencies are present (cython, numpy, scipy, matplotlib and raysect), this should
start the Cherab compilation and installation process. If you don’t have administrator access to install
the package, add the <code class="docutils literal notranslate"><span class="pre">--user</span></code> flag to the above line to install the package under your own user account.</p>
<p>As all the Cherab packages are dependent on the core <code class="docutils literal notranslate"><span class="pre">cherab</span></code> package, this package must be installed first.
Note that other packages may have their own inter-dependencies, see the specific package documentation for
more information.</p>
</section>
<section id="installing-for-development">
<h3><span class="section-number">4.3.3. </span>Installing for development<a class="headerlink" href="#installing-for-development" title="Permalink to this heading">¶</a></h3>
<p>When developing cherab it is usually preferred that the packages be installed in “develop” mode.
Clone the project from the development repository, locate the folder containing setup.py and run:</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">e</span> <span class="o">.</span>
</pre></div>
</div>
<p>The alternative command if pip is not available is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">develop</span>
</pre></div>
</div>
<p>Either command will cause the original installation folder to be added to the
site-package path. Modifications to the code will therefore be visible to python next
time the code is imported. If you are modifying Cython source files then run
<code class="docutils literal notranslate"><span class="pre">./dev/build.sh</span></code> to re-build those files in order for the changes to be visible. A
virtual environment, or the <code class="docutils literal notranslate"><span class="pre">--user</span></code> flag, should be used if you do not have
administrative permission for your python installation.</p>
<p>When developing new features for Cherab, the development branch should be used as the base.</p>
</section>
</section>
<section id="configuring-atomic-data">
<h2><span class="section-number">4.4. </span>Configuring Atomic Data<a class="headerlink" href="#configuring-atomic-data" title="Permalink to this heading">¶</a></h2>
<p>Regardless of the method you used to install Cherab, you will need a valid atomic data source for your
calculations. Cherab provides a default atomic data source through the OpenADAS module. To use this module
it is necessary to obtain the atomic data files from the OpenADAS web archive. An automated download script
is provided to download and install the most common atomic data files. This data is required to run many of
the demos supplied with Cherab. To run the script please enter the following commands in a python terminal:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">cherab.openadas.repository</span> <span class="kn">import</span> <span class="n">populate</span>
<span class="gp">>>> </span><span class="n">populate</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="testing">
<h2><span class="section-number">4.5. </span>Testing<a class="headerlink" href="#testing" title="Permalink to this heading">¶</a></h2>
<p>A selection of test scripts can be run with the <cite>nose</cite> testing framework. These are routinely
run on the development version. Running <code class="docutils literal notranslate"><span class="pre">./dev/test.sh</span></code> at the terminal in the source directory
should run all of these tests to completion without errors or failures.</p>
<p>Many of the demos used throughout the documentation are distributed with the source code in
the <code class="docutils literal notranslate"><span class="pre">demo</span></code> folder.</p>
</section>
</section>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="available_modules.html" class="btn btn-neutral float-right" title="5. Available Packages" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="governance.html" class="btn btn-neutral" title="3. Project Governance" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2024, Cherab Team
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>