-
Notifications
You must be signed in to change notification settings - Fork 1
/
contribute.html
374 lines (361 loc) · 21.1 KB
/
contribute.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
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
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="utf-8" />
<title>Contributing to the code — Magic 6.3 documentation</title>
<link rel="stylesheet" href="_static/magic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Magic 6.3 documentation"
href="_static/opensearch.xml"/>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Input parameters" href="inputNamelists/namelists.html" />
<link rel="prev" title="Numerical technique" href="numerics.html" />
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300,400,700'
rel='stylesheet' type='text/css' />
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1/jquery.js"></script>
<script src="galleria/galleria-1.4.2.min.js"></script>
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
<script type="text/javascript">
// intelligent scrolling of the sidebar content
$(window).scroll(function() {
var sb = $('.sphinxsidebarwrapper');
var win = $(window);
var sbh = sb.height();
var offset = $('.sphinxsidebar').position()['top'];
var wintop = win.scrollTop();
var winbot = wintop + win.innerHeight();
var curtop = sb.position()['top'];
var curbot = curtop + sbh;
// does sidebar fit in window?
if (sbh < win.innerHeight()) {
// yes: easy case -- always keep at the top
sb.css('top', $u.min([$u.max([0, wintop - offset - 10]),
$(document).height() - sbh - 200]));
} else {
// no: only scroll if top/bottom edge of sidebar is at
// top/bottom edge of window
if (curtop > wintop && curbot > winbot) {
sb.css('top', $u.max([wintop - offset - 10, 0]));
} else if (curtop < wintop && curbot < winbot) {
sb.css('top', $u.min([winbot - sbh - offset - 20,
$(document).height() - sbh - 200]));
}
}
});
</script>
</head><body>
<div class="pageheader">
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="install.html">Get it/Run it</a></li>
<li><a href="#">Contribute!</a></li>
<li><a href="numerics.html">Numerical methods</a></li>
<li><a href="contents.html">Contents</a></li>
</ul>
<div>
<a href="index.html">
<img src="_static/logo.png" alt="magic" height="120px" width="192px"/>
</a>
</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"
accesskey="I">index</a></li>
<li class="right" >
<a href="f-modindex.html" title="Fortran Module Index"
>fortran modules</a> |</li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="inputNamelists/namelists.html" title="Input parameters"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="numerics.html" title="Numerical technique"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="contents.html">Magic 6.3 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="contributing-to-the-code">
<span id="seccontribute"></span><h1>Contributing to the code<a class="headerlink" href="#contributing-to-the-code" title="Permalink to this headline">¶</a></h1>
<p>MagIC is an open-source code, we thus value any possible contribution! There are
several ways to directly contribute to the code:</p>
<div class="topic">
<p class="topic-title first">Contribute</p>
<ul class="simple">
<li><p><strong>Do you want to contribute to the code?</strong> Just clone the code and start modyfing it.
Make sure that your modifications <a class="reference internal" href="#secautotest"><span class="std std-ref">don’t alter the code</span></a>, try
to <a class="reference internal" href="#secdocsphinx"><span class="std std-ref">document your changes</span></a> as much as you can and follow
the recommended <a class="reference internal" href="#secmodernfortran"><span class="std std-ref">Fortran coding style</span></a>.</p></li>
<li><p><strong>Do you want to improve the documentation?</strong> Feel free to document some missing
features. The documentation is stored in the directory <code class="code docutils literal notranslate"><span class="pre">$MAGIC_HOME/doc/sphinx</span></code>
and relies on the documenting tool <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a>. Some
recommendations regarding documentation can be found <a class="reference internal" href="#secdocsphinx"><span class="std std-ref">below</span></a>.</p></li>
<li><p><strong>Did you find a bug?</strong> Issues and feature requests should be raised in the
<a class="reference external" href="https://github.com/magic-sph/magic/issues">github tracker</a>.</p></li>
</ul>
</div>
<div class="section" id="checking-the-consistency-of-the-code">
<span id="secautotest"></span><h2>Checking the consistency of the code<a class="headerlink" href="#checking-the-consistency-of-the-code" title="Permalink to this headline">¶</a></h2>
<p>It is frequently required to check the consistency of the code, especially <strong>after
the implementation of new features</strong>. For this reason, we developed the
python test suite <code class="docutils literal notranslate"><span class="pre">magic_wizard.py</span></code>, located in the
directory <code class="code docutils literal notranslate"><span class="pre">$MAGIC_HOME/samples/</span></code>, which tests the compilation of the code
and it’s results against a set of standard solutions in sample directories to
check if the code produces the correct output.</p>
<p>You can run it as follows:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>./magic_wizard.py <options>
</pre></div>
</div>
<p>It supports the following options:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-h, --help Show usage overview
--level LEV Run only tests from level LEV
--use-debug-flags Compile MagIC with the debug flags
--use-mpi Use MPI
--use-openmp Use the hybrid version of MagIC
--use-mkl Use the MKL <span class="k">for</span> FFTs and Lapack calls
--use-shtns Use SHTns <span class="k">for</span> Legendre transforms
--use-precond USE_PRECOND Use matrix preconditioning
--nranks NRANKS Specify the number of MPI ranks
--nthreads NTHREADS Specify the number of threads <span class="o">(</span>hybrid version<span class="o">)</span>
--mpicmd MPICMD Specify the mpi executable <span class="o">(</span>mpiexec, mpirun, srun<span class="o">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Make sure that your environment variables <code class="docutils literal notranslate"><span class="pre">FC</span></code> and <code class="docutils literal notranslate"><span class="pre">CC</span></code> are correctly defined otherwise the script will use the default system compilers.</p>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">--level</span> <span class="pre">LEV</span></code> option defines the priority level of check and validation of the code. It has the following levels of checking:</p>
<blockquote>
<div><table class="docutils align-default">
<colgroup>
<col style="width: 13%" />
<col style="width: 87%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Level</p></th>
<th class="head"><p>Cases to check (subdirectories)</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>0</p></td>
<td><ul class="simple">
<li><p>Boussinesq dynamo benchmark (BM1)
(<a class="reference external" href="http://dx.doi.org/10.1016/S0031-9201(01)00275-8">Christensen et al., 2001</a>)
- start from zero (<code class="docutils literal notranslate"><span class="pre">dynamo_benchmark</span></code>)</p></li>
<li><p>Variable transport properties (viscosity,
thermal diffusivity and electrical diffusivity)
in an anelastic convective model (<code class="docutils literal notranslate"><span class="pre">varProps</span></code>)</p></li>
<li><p>Test of a case that uses finite differences
- restart from a case that used Chebyshev polynomials
(<code class="docutils literal notranslate"><span class="pre">finite_differences</span></code>)</p></li>
<li><p>Boussinesq dynamo benchmark (BM2)
(<a class="reference external" href="http://dx.doi.org/10.1016/S0031-9201(01)00275-8">Christensen et al., 2001</a>)
- start from a saturated state (<code class="docutils literal notranslate"><span class="pre">boussBenchSat</span></code>)</p></li>
<li><p>Double-diffusive convection benchmark
(<a class="reference external" href="http://dx.doi.org/10.1111/j.1365-246X.2010.04722.x">Breuer et al., 2010</a>)
- start from a saturated state (<code class="docutils literal notranslate"><span class="pre">doubleDiffusion</span></code>)</p></li>
<li><p>Axisymmetric spherical Couette flow - this auto-test
checks the axisymmetric version of MagIC
(<code class="docutils literal notranslate"><span class="pre">couetteAxi</span></code>)</p></li>
<li><p>Test Precession (<code class="docutils literal notranslate"><span class="pre">precession</span></code>)</p></li>
<li><p>Whole sphere benchmark
(<a class="reference external" href="http://dx.doi.org/10.1093/gji/ggt518">Marti et al., 2014</a>)
- start from a saturated state (<code class="docutils literal notranslate"><span class="pre">full_sphere</span></code>)</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p>1</p></td>
<td><ul class="simple">
<li><p>Test reading and writing of
restart files (<code class="docutils literal notranslate"><span class="pre">testRestart</span></code>)</p></li>
<li><p>Test different grid truncations (<code class="docutils literal notranslate"><span class="pre">testTruncations</span></code>)</p></li>
<li><p>Test mapping on to a new grid (<code class="docutils literal notranslate"><span class="pre">testMapping</span></code>)</p></li>
<li><p>Test different outputs produced (<code class="docutils literal notranslate"><span class="pre">testOutputs</span></code>)</p></li>
<li><p>Test different radial outputs -
<code class="docutils literal notranslate"><span class="pre">*R.TAG</span></code> (<code class="docutils literal notranslate"><span class="pre">testRadialOutputs</span></code>)</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p>2</p></td>
<td><ul class="simple">
<li><p>Hydrodynamic anelastic benchmark
(<a class="reference external" href="http://dx.doi.org/10.1016/j.icarus.2011.08.014">Jones et al., 2011</a>)
(<code class="docutils literal notranslate"><span class="pre">hydro_bench_anel</span></code>)</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p>3</p></td>
<td><ul class="simple">
<li><p>Heat flux perturbation (<code class="docutils literal notranslate"><span class="pre">fluxPerturbation</span></code>)</p></li>
<li><p>Isothermal model with <span class="math notranslate nohighlight">\(N_{\rho}=3\)</span>
(<code class="docutils literal notranslate"><span class="pre">isothermal_nrho3</span></code>)</p></li>
<li><p>Boussinesq Dynamo benchmark for conducting and
rotating inner core
(<code class="docutils literal notranslate"><span class="pre">dynamo_benchmark_condICrotIC</span></code>)</p></li>
<li><p>Anelastic dynamo with variable conductivity
(<code class="docutils literal notranslate"><span class="pre">varCond</span></code>)</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p>4</p></td>
<td><ul class="simple">
<li><p>Test the writing of CMB and coeff files
(<code class="docutils literal notranslate"><span class="pre">testCoeffOutputs</span></code>)</p></li>
<li><p>Test the writing of RMS force balance
(<code class="docutils literal notranslate"><span class="pre">testRMSOutputs</span></code>)</p></li>
<li><p>Test the writing of Graphic and Movie files
(<code class="docutils literal notranslate"><span class="pre">testGraphMovieOutputs</span></code>)</p></li>
<li><p>Test the writing of TO and Geos outputs
(<code class="docutils literal notranslate"><span class="pre">testTOGeosOutputs</span></code>)</p></li>
</ul>
</td>
</tr>
</tbody>
</table>
</div></blockquote>
</div>
<div class="section" id="advices-when-contributing-to-the-code">
<span id="secmodernfortran"></span><h2>Advices when contributing to the code<a class="headerlink" href="#advices-when-contributing-to-the-code" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p>Before commiting your modifications <strong>always</strong> make sure that the auto-tests pass correctly.</p></li>
<li><p>Try to follow the same coding style rules as in the rest of the code:</p>
<ol class="arabic">
<li><p><strong>Never</strong> use TABS but always SPACES instead</p></li>
<li><p>Use 3 spaces for indentation</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>These two rules can be easily set in your $HOME/.vimrc file if you use
<a class="reference external" href="http://www.vim.org/">vim</a>:</p>
<div class="highlight-vim notranslate"><div class="highlight"><pre><span></span><span class="k">au</span> <span class="nb">FileType</span> fortran <span class="k">set</span> <span class="nb">shiftwidth</span><span class="p">=</span><span class="m">3</span>
<span class="k">au</span> <span class="nb">FileType</span> fortran <span class="k">set</span> <span class="nb">tabstop</span><span class="p">=</span><span class="m">3</span>
<span class="k">au</span> <span class="nb">FileType</span> fortran <span class="k">set</span> <span class="nb">expandtab</span>
</pre></div>
</div>
</div>
</li>
<li><p>Never use capital letters for variable declaration or Fortran keywords</p></li>
<li><p>Never use <code class="code docutils literal notranslate"><span class="pre">dimension(len)</span></code> for declaring array but rather <code class="code docutils literal notranslate"><span class="pre">real(cp)</span> <span class="pre">::</span> <span class="pre">data(len)</span></code></p></li>
<li><p>Always use the default precisions when introducing new variables <code class="code docutils literal notranslate"><span class="pre">(cp)</span></code></p></li>
</ol>
</li>
</ul>
<p>These rules try to follow the general recommendations on modern fortran programming
that can be found on <a class="reference external" href="http://www.fortran90.org/src/best-practices.html">www.fortran90.org</a> or in the book
<a class="reference external" href="http://www.cambridge.org/us/academic/subjects/computer-science/scientific-computing-scientific-software/modern-fortran-style-and-usage">Modern Fortran - style and usage</a> by N. S. Clerman and W. Spector.</p>
</div>
<div class="section" id="building-the-documentation-and-contributing-to-it">
<span id="secdocsphinx"></span><h2>Building the documentation and contributing to it<a class="headerlink" href="#building-the-documentation-and-contributing-to-it" title="Permalink to this headline">¶</a></h2>
<p>The documentation is generated using <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a>. To
build it you’ll thus need to install this python module on your machine. This is in general
directly available on most of the Linux distributions under the name
<code class="docutils literal notranslate"><span class="pre">python-sphinx</span></code>. Once installed, just go to the documentation directory</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">cd</span> <span class="nv">$MAGIC_HOME</span>/doc/sphinx
</pre></div>
</div>
<p>and build the html documentation</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ make html
</pre></div>
</div>
<p>The complete documentation will then be built in a local directory named
<code class="code docutils literal notranslate"><span class="pre">$MAGIC_HOME/doc/sphinx/.build/html</span></code>.</p>
<p>If <a class="reference external" href="http://www.latex-project.org/">LaTeX</a> is installed on your work station, it
is also possible to build the corresponding manual of the documentation in
the pdf format:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ make latexpdf
</pre></div>
</div>
<p>The resulting pdf is then generated in a local directory named
<code class="code docutils literal notranslate"><span class="pre">$MAGIC_HOME/doc/sphinx/.build/latex</span></code>.</p>
<p>It is pretty straightforward to contribute to the documentation by simply adding some
contents to the different <code class="code docutils literal notranslate"><span class="pre">rst</span></code> files. Informations about <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> syntax can be found on <a class="reference external" href="http://sphinx-doc.org/rest.html">www.sphinx-doc.org</a>,
while helpful CheatSheet are accessible <a class="reference external" href="http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html">here</a> or <a class="reference external" href="http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html">there</a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Contributing to the code</a><ul>
<li><a class="reference internal" href="#checking-the-consistency-of-the-code">Checking the consistency of the code</a></li>
<li><a class="reference internal" href="#advices-when-contributing-to-the-code">Advices when contributing to the code</a></li>
<li><a class="reference internal" href="#building-the-documentation-and-contributing-to-it">Building the documentation and contributing to it</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="numerics.html"
title="previous chapter">Numerical technique</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="inputNamelists/namelists.html"
title="next chapter">Input parameters</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/contribute.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div 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" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</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="f-modindex.html" title="Fortran Module Index"
>fortran modules</a> |</li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="inputNamelists/namelists.html" title="Input parameters"
>next</a> |</li>
<li class="right" >
<a href="numerics.html" title="Numerical technique"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="contents.html">Magic 6.3 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2023, Thomas Gastine, Johannes Wicht, Ankit Barik, Lùcia Duarte.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.3.1.
</div>
</body>
</html>