source: flex_extract.git/Documentation/html/quick_start.html @ 6931f61

ctbtodev
Last change on this file since 6931f61 was 6931f61, checked in by anphi <anne.philipp@…>, 4 years ago

Update Onlinedocumentation after review of language editing
  • Property mode set to 100644
File size: 58.4 KB
Line 
1
2
3<!DOCTYPE html>
4<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
5<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
6<head>
7  <meta charset="utf-8">
8 
9  <meta name="viewport" content="width=device-width, initial-scale=1.0">
10 
11  <title>Usage &mdash; flex_extract 7.1.2 documentation</title>
12 
13
14 
15 
16 
17 
18
19 
20  <script type="text/javascript" src="_static/js/modernizr.min.js"></script>
21 
22   
23      <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
24        <script src="_static/jquery.js"></script>
25        <script src="_static/underscore.js"></script>
26        <script src="_static/doctools.js"></script>
27        <script src="_static/language_data.js"></script>
28        <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
29   
30    <script type="text/javascript" src="_static/js/theme.js"></script>
31
32   
33
34 
35  <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
36  <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
37  <link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
38  <link rel="stylesheet" href="_static/css/theme_overrides.css" type="text/css" />
39    <link rel="index" title="Index" href="genindex.html" />
40    <link rel="search" title="Search" href="search.html" />
41    <link rel="next" title="Code-Level Documentation" href="documentation.html" />
42    <link rel="prev" title="Local mode installation" href="Installation/local.html" /> 
43</head>
44
45<body class="wy-body-for-nav">
46
47   
48  <div class="wy-grid-for-nav">
49   
50    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
51      <div class="wy-side-scroll">
52        <div class="wy-side-nav-search" >
53         
54
55         
56            <a href="index.html" class="icon icon-home"> flex_extract
57         
58
59         
60          </a>
61
62         
63           
64           
65              <div class="version">
66                7.1.2
67              </div>
68           
69         
70
71         
72<div role="search">
73  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
74    <input type="text" name="q" placeholder="Search docs" />
75    <input type="hidden" name="check_keywords" value="yes" />
76    <input type="hidden" name="area" value="default" />
77  </form>
78</div>
79
80         
81        </div>
82
83        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
84         
85           
86           
87             
88           
89           
90              <p class="caption"><span class="caption-text">Table of Contents:</span></p>
91<ul class="current">
92<li class="toctree-l1"><a class="reference internal" href="ecmwf_data.html">ECMWF Data</a></li>
93<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
94<li class="toctree-l1 current"><a class="current reference internal" href="#">Usage</a><ul>
95<li class="toctree-l2"><a class="reference internal" href="#job-preparation">Job preparation</a><ul>
96<li class="toctree-l3"><a class="reference internal" href="#remote-and-gateway-modes">Remote and gateway modes</a></li>
97<li class="toctree-l3"><a class="reference internal" href="#local-mode">Local mode</a></li>
98</ul>
99</li>
100<li class="toctree-l2"><a class="reference internal" href="#selection-and-adjustment-of-control-files">Selection and adjustment of <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files</a><ul>
101<li class="toctree-l3"><a class="reference internal" href="#public-datasets">Public datasets</a></li>
102<li class="toctree-l3"><a class="reference internal" href="#cera">CERA</a></li>
103<li class="toctree-l3"><a class="reference internal" href="#era-5">ERA 5</a></li>
104<li class="toctree-l3"><a class="reference internal" href="#era-interim">ERA-Interim</a></li>
105<li class="toctree-l3"><a class="reference internal" href="#operational-data">Operational data</a></li>
106<li class="toctree-l3"><a class="reference internal" href="#specific-features">Specific features</a></li>
107<li class="toctree-l3"><a class="reference internal" href="#hints-for-proper-definition-of-certain-parameter-combinations">Hints for proper definition of certain parameter combinations</a><ul class="simple">
108</ul>
109</li>
110</ul>
111</li>
112</ul>
113</li>
114<li class="toctree-l1"><a class="reference internal" href="documentation.html">Code-Level Documentation</a></li>
115<li class="toctree-l1"><a class="reference internal" href="evaluation.html">Evaluation</a></li>
116<li class="toctree-l1"><a class="reference internal" href="dev_guide.html">Developer Guide</a></li>
117<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
118<li class="toctree-l1"><a class="reference internal" href="support.html">Support</a></li>
119<li class="toctree-l1"><a class="reference internal" href="Support/faq.html">FAQ - Frequently asked questions</a></li>
120<li class="toctree-l1"><a class="reference internal" href="authors.html">Developer Team</a></li>
121</ul>
122
123           
124         
125        </div>
126      </div>
127    </nav>
128
129    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
130
131     
132      <nav class="wy-nav-top" aria-label="top navigation">
133       
134          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
135          <a href="index.html">flex_extract</a>
136       
137      </nav>
138
139
140      <div class="wy-nav-content">
141       
142        <div class="rst-content">
143       
144         
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160<div role="navigation" aria-label="breadcrumbs navigation">
161
162  <ul class="wy-breadcrumbs">
163   
164      <li><a href="index.html">Docs</a> &raquo;</li>
165       
166      <li>Usage</li>
167   
168   
169      <li class="wy-breadcrumbs-aside">
170       
171           
172            <a href="_sources/quick_start.rst.txt" rel="nofollow"> View page source</a>
173         
174       
175      </li>
176   
177  </ul>
178
179 
180  <hr/>
181</div>
182          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
183           <div itemprop="articleBody">
184           
185  <div class="section" id="usage">
186<h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline"></a></h1>
187<p><code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> is a command-line tool. In the first versions, it was started via a korn shell script and since version 6, the entry point was a python script. From version 7.1, a bash shell script was implemented to call <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> with the command-line parameters.</p>
188<p>To submit an extraction job, change the working directory to the subdirectory <code class="docutils literal notranslate"><span class="pre">Run</span></code> (directly under the <code class="docutils literal notranslate"><span class="pre">flex_extract_vX.X</span></code> root directory, where  <code class="docutils literal notranslate"><span class="pre">X.X</span></code> is the version number):</p>
189<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> &lt;path-to-flex_extract_vX.X&gt;/Run
190</pre></div>
191</div>
192<p>Within this directory you can find everything you need to modify and run <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code>. The following tree shows a shortened list of directories and important files. The <code class="docutils literal notranslate"><span class="pre">*</span></code> serves as a wildcard. The brackets <code class="docutils literal notranslate"><span class="pre">[]</span></code> indicate that the file is present only in certain modes of application.</p>
193<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>Run
194├── Control
195│   ├── CONTROL_*
196├── Jobscripts
197│   ├── compilejob.ksh
198│   ├── job.ksh
199│   ├── <span class="o">[</span>joboper.ksh<span class="o">]</span>
200├── Workspace
201│   ├── CERA_example
202│   │   ├── CE000908*
203├── <span class="o">[</span>ECMWF_ENV<span class="o">]</span>
204├── run_local.sh
205└── run.sh
206</pre></div>
207</div>
208<p>The <code class="docutils literal notranslate"><span class="pre">Jobscripts</span></code> directory is used to store the Korn shell job scripts generated by a <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> run in the <strong>Remote</strong> or <strong>Gateway</strong> mode. They are used to submit the setup information to the ECMWF server and start the jobs in ECMWF’s batch mode. The typical user must not touch these files. They are generated from template files which are stored in the <code class="docutils literal notranslate"><span class="pre">Templates</span></code> directory under <code class="docutils literal notranslate"><span class="pre">flex_extract_vX.X</span></code>. Usually there will be a <code class="docutils literal notranslate"><span class="pre">compilejob.ksh</span></code> and a <code class="docutils literal notranslate"><span class="pre">job.ksh</span></code> script which are explained in the section <a class="reference internal" href="Documentation/input.html"><span class="doc">Control &amp; input data</span></a>. In the rare case of operational data extraction there will be a <code class="docutils literal notranslate"><span class="pre">joboper.ksh</span></code> which reads time information from environment variables at the ECMWF servers.</p>
209<p>The <code class="docutils literal notranslate"><span class="pre">Controls</span></code> directory contains a number of sample <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files. They cover the current range of possible kinds of extractions. Some parameters in the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files can be adapted and some others should not be changed. In this <a class="reference internal" href="#"><span class="doc">Usage</span></a> guide we explain how an extraction with <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> can be started in the different <a class="reference internal" href="Documentation/Overview/app_modes.html"><span class="doc">Application modes</span></a> and point out some specifics of each dataset and <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file.</p>
210<p>Directly under <code class="docutils literal notranslate"><span class="pre">Run</span></code> you find the files <code class="docutils literal notranslate"><span class="pre">run.sh</span></code> and <code class="docutils literal notranslate"><span class="pre">run_local.sh</span></code> and according to your selected <a class="reference internal" href="Documentation/Overview/app_modes.html"><span class="doc">Application modes</span></a> there might also be a file named <code class="docutils literal notranslate"><span class="pre">ECMWF_ENV</span></code> for the user credentials to quickly and automatically access ECMWF servers.</p>
211<p>From version 7.1 on, the <code class="docutils literal notranslate"><span class="pre">run.sh</span></code> (or <code class="docutils literal notranslate"><span class="pre">run_local.sh</span></code>) script is the main entry point to <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code>.</p>
212<div class="admonition note">
213<p class="admonition-title">Note</p>
214<p>Note that for experienced users (or users of older versions), it is still possible to start <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> directly via the <code class="docutils literal notranslate"><span class="pre">submit.py</span></code> script in directory <code class="docutils literal notranslate"><span class="pre">flex_extract_vX.X/Source/Python</span></code>.</p>
215</div>
216<div class="section" id="job-preparation">
217<h2>Job preparation<a class="headerlink" href="#job-preparation" title="Permalink to this headline"></a></h2>
218<p>To actually start a job with <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> it is sufficient to start either <code class="docutils literal notranslate"><span class="pre">run.sh</span></code> or <code class="docutils literal notranslate"><span class="pre">run_local.sh</span></code>. Data sets and access modes are selected in <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files and within the user section of the <code class="docutils literal notranslate"><span class="pre">run</span></code> scripts. One should select one of the sample <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files. The following sections describes the differences in the application modes and where the results will be stored.</p>
219<div class="section" id="remote-and-gateway-modes">
220<h3>Remote and gateway modes<a class="headerlink" href="#remote-and-gateway-modes" title="Permalink to this headline"></a></h3>
221<p>For member-state users it is recommended to use the <em>remote</em> or <em>gateway</em> mode, especially for more demanding tasks,  which retrieve and convert the data on ECMWF machines; only the final output files are transferrred to the local host.</p>
222<dl>
223<dt>Remote mode</dt><dd><p>The only difference between both modes is the users working location. In the <em>remote</em> mode you have to login to the ECMWF server and then go to the <code class="docutils literal notranslate"><span class="pre">Run</span></code> directory as shown above. At ECMWF servers <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> is installed in the <code class="docutils literal notranslate"><span class="pre">$HOME</span></code> directory. However, to be able to start the program you have to load the <code class="docutils literal notranslate"><span class="pre">Python3</span></code> environment with the module system first.</p>
224<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Remote mode</span>
225ssh -X &lt;ecuid&gt;@ecaccess.ecmwf.int
226</pre></div>
227</div>
228<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># On ECMWF server</span>
229<span class="o">[</span>&lt;ecuid&gt;@ecgb11 ~<span class="o">]</span>$ <span class="nb">cd</span> flex_extract_vX.X/Run
230</pre></div>
231</div>
232</dd>
233<dt>Gateway mode</dt><dd><p>For the gateway mode you have to log in on the gateway server and go to the <code class="docutils literal notranslate"><span class="pre">Run</span></code> directory of <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code>:</p>
234<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Gateway mode</span>
235ssh &lt;user&gt;@&lt;gatewayserver&gt;
236<span class="nb">cd</span> &lt;path-to-flex_extract_vX.X&gt;/Run
237</pre></div>
238</div>
239</dd>
240</dl>
241<p>From here on the working process is the same for both modes.</p>
242<p>For your first submission you should use one of the example <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files stored in the <code class="docutils literal notranslate"><span class="pre">Control</span></code> directory. We recommend to extract <em>CERA-20C</em> data since they usually guarantee quick results and are best for testing reasons.</p>
243<p>Therefore open the <code class="docutils literal notranslate"><span class="pre">run.sh</span></code> file and modify the parameter block marked in the file as shown below:</p>
244<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># -----------------------------------------------------------------</span>
245<span class="c1"># AVAILABLE COMMANDLINE ARGUMENTS TO SET</span>
246<span class="c1">#</span>
247<span class="c1"># THE USER HAS TO SPECIFY THESE PARAMETERS:</span>
248
249<span class="nv">QUEUE</span><span class="o">=</span><span class="s1">&#39;ecgate&#39;</span>
250<span class="nv">START_DATE</span><span class="o">=</span>None
251<span class="nv">END_DATE</span><span class="o">=</span>None
252<span class="nv">DATE_CHUNK</span><span class="o">=</span>None
253<span class="nv">JOB_CHUNK</span><span class="o">=</span><span class="m">3</span>
254<span class="nv">BASETIME</span><span class="o">=</span>None
255<span class="nv">STEP</span><span class="o">=</span>None
256<span class="nv">LEVELIST</span><span class="o">=</span>None
257<span class="nv">AREA</span><span class="o">=</span>None
258<span class="nv">INPUTDIR</span><span class="o">=</span>None
259<span class="nv">OUTPUTDIR</span><span class="o">=</span>None
260<span class="nv">PP_ID</span><span class="o">=</span>None
261<span class="nv">JOB_TEMPLATE</span><span class="o">=</span><span class="s1">&#39;jobscript.template&#39;</span>
262<span class="nv">CONTROLFILE</span><span class="o">=</span><span class="s1">&#39;CONTROL_CERA&#39;</span>
263<span class="nv">DEBUG</span><span class="o">=</span><span class="m">0</span>
264<span class="nv">REQUEST</span><span class="o">=</span><span class="m">2</span>
265<span class="nv">PUBLIC</span><span class="o">=</span><span class="m">0</span>
266</pre></div>
267</div>
268<p>This would retrieve a one day (08.09.2000) <em>CERA-20C</em> dataset with 3 hourly temporal resolution and a small 1° domain over Europe. Since the <code class="docutils literal notranslate"><span class="pre">ectrans</span></code> parameter is set to <code class="docutils literal notranslate"><span class="pre">1</span></code> the resulting output files will be transferred to the local gateway into the path stored in the destination (SEE INSTRUCTIONS FROM INSTALLATION).  The parameters listed in the <code class="docutils literal notranslate"><span class="pre">run.sh</span></code> file would overwrite existing settings in the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file.</p>
269<p>To start the retrieval you only have to start the script by:</p>
270<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>./run.sh
271</pre></div>
272</div>
273<p><code class="docutils literal notranslate"><span class="pre">Flex_extract</span></code> will print some information about the job. If there is no error in the submission to the ECMWF server you will see something like this:</p>
274<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>---- On-demand mode! ----
275The job id is: <span class="m">10627807</span>
276You should get an email per job with subject flex.hostname.pid
277FLEX_EXTRACT JOB SCRIPT IS SUBMITED!
278</pre></div>
279</div>
280<p>Once submitted you can check the progress of the submitted job using <code class="docutils literal notranslate"><span class="pre">ecaccess-job-list</span></code>. You should get an email after the job is finished with a detailed protocol of what was done.</p>
281<p>In case the job fails you will receive an email with the subject <code class="docutils literal notranslate"><span class="pre">ERROR!</span></code> and the job name. You can then check for information in the email or you can check on ECMWF server in the <code class="docutils literal notranslate"><span class="pre">$SCRATCH</span></code> directory for debugging information.</p>
282<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> <span class="nv">$SCRATCH</span>
283ls -rthl
284</pre></div>
285</div>
286<p>The last command lists the most recent logs and temporary retrieval directories (usually <code class="docutils literal notranslate"><span class="pre">extractXXXXX</span></code>, where XXXXX is the process id). Under <code class="docutils literal notranslate"><span class="pre">extractXXXXX</span></code> a copy of the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file is stored under the name <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code>, the protocol is stored in the file <code class="docutils literal notranslate"><span class="pre">prot</span></code> and the temporary files as well as the resulting files are stored in a directory <code class="docutils literal notranslate"><span class="pre">work</span></code>. The original name of the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file is stored in this new file under parameter <code class="docutils literal notranslate"><span class="pre">controlfile</span></code>.</p>
287<div class="literal-block-wrapper docutils container" id="id2">
288<div class="code-block-caption"><span class="caption-text">“Example structure of <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> output directory on ECMWF servers.”</span><a class="headerlink" href="#id2" title="Permalink to this code"></a></div>
289<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>extractXXXXX
290├── CONTROL
291├── prot
292├── work
293│   ├── temporary files
294│   ├── CE000908* <span class="o">(</span>resulting files<span class="o">)</span>
295</pre></div>
296</div>
297</div>
298<p>If the job was submitted to the HPC ( <code class="docutils literal notranslate"><span class="pre">queue=cca</span></code> or  <code class="docutils literal notranslate"><span class="pre">queue=ccb</span></code> ) you may login to the HPC and look into the directory <code class="docutils literal notranslate"><span class="pre">/scratch/ms/ECGID/ECUID/.ecaccess_do_not_remove</span></code> for job logs. The working directories are deleted after job failure and thus normally cannot be accessed.</p>
299<p>To check if the resulting files are still transferred to local gateway server you can use the command <code class="docutils literal notranslate"><span class="pre">ecaccess-ectrans-list</span></code> or check the destination path for resulting files on your local gateway server.</p>
300</div>
301<div class="section" id="local-mode">
302<h3>Local mode<a class="headerlink" href="#local-mode" title="Permalink to this headline"></a></h3>
303<p>To get to know the working process and to start your first submission you could use one of the example <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files stored in the <code class="docutils literal notranslate"><span class="pre">Control</span></code> directory as they are. For quick results and for testing reasons it is recommended to extract <em>CERA-20C</em> data.</p>
304<p>Open the <code class="docutils literal notranslate"><span class="pre">run_local.sh</span></code> file and modify the parameter block marked in the file as shown below. The differences are highlighted.</p>
305<table class="docutils align-default">
306<colgroup>
307<col style="width: 50%" />
308<col style="width: 50%" />
309</colgroup>
310<tbody>
311<tr class="row-odd"><td><p>Take this for <strong>member-state user</strong></p></td>
312<td><p>Take this for <strong>public user</strong></p></td>
313</tr>
314<tr class="row-even"><td><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># -----------------------------------------</span>
315<span class="c1"># AVAILABLE COMMANDLINE ARGUMENTS TO SET</span>
316<span class="c1">#</span>
317<span class="c1"># THE USER HAS TO SPECIFY THESE PARAMETERs:</span>
318<span class="c1">#</span>
319
320<span class="nv">QUEUE</span><span class="o">=</span><span class="s1">&#39;&#39;</span>
321<span class="nv">START_DATE</span><span class="o">=</span>None
322<span class="nv">END_DATE</span><span class="o">=</span>None
323<span class="nv">DATE_CHUNK</span><span class="o">=</span>None
324<span class="nv">JOB_CHUNK</span><span class="o">=</span>None
325<span class="nv">BASETIME</span><span class="o">=</span>None
326<span class="nv">STEP</span><span class="o">=</span>None
327<span class="nv">LEVELIST</span><span class="o">=</span>None
328<span class="nv">AREA</span><span class="o">=</span>None
329<span class="hll"><span class="nv">INPUTDIR</span><span class="o">=</span><span class="s1">&#39;./Workspace/CERA&#39;</span>
330</span><span class="nv">OUTPUTDIR</span><span class="o">=</span>None
331<span class="nv">PP_ID</span><span class="o">=</span>None
332<span class="nv">JOB_TEMPLATE</span><span class="o">=</span><span class="s1">&#39;&#39;</span>
333<span class="hll"><span class="nv">CONTROLFILE</span><span class="o">=</span><span class="s1">&#39;CONTROL_CERA&#39;</span>
334</span><span class="nv">DEBUG</span><span class="o">=</span><span class="m">0</span>
335<span class="nv">REQUEST</span><span class="o">=</span><span class="m">0</span>
336<span class="hll"><span class="nv">PUBLIC</span><span class="o">=</span><span class="m">0</span>
337</span></pre></div>
338</div>
339</td>
340<td><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># -----------------------------------------</span>
341<span class="c1"># AVAILABLE COMMANDLINE ARGUMENTS TO SET</span>
342<span class="c1">#</span>
343<span class="c1"># THE USER HAS TO SPECIFY THESE PARAMETERs:</span>
344<span class="c1">#</span>
345
346<span class="nv">QUEUE</span><span class="o">=</span><span class="s1">&#39;&#39;</span>
347<span class="nv">START_DATE</span><span class="o">=</span>None
348<span class="nv">END_DATE</span><span class="o">=</span>None
349<span class="nv">DATE_CHUNK</span><span class="o">=</span>None
350<span class="nv">JOB_CHUNK</span><span class="o">=</span>None
351<span class="nv">BASETIME</span><span class="o">=</span>None
352<span class="nv">STEP</span><span class="o">=</span>None
353<span class="nv">LEVELIST</span><span class="o">=</span>None
354<span class="nv">AREA</span><span class="o">=</span>None
355<span class="hll"><span class="nv">INPUTDIR</span><span class="o">=</span><span class="s1">&#39;./Workspace/CERApublic&#39;</span>
356</span><span class="nv">OUTPUTDIR</span><span class="o">=</span>None
357<span class="nv">PP_ID</span><span class="o">=</span>None
358<span class="nv">JOB_TEMPLATE</span><span class="o">=</span><span class="s1">&#39;&#39;</span>
359<span class="hll"><span class="nv">CONTROLFILE</span><span class="o">=</span><span class="s1">&#39;CONTROL_CERA.public&#39;</span>
360</span><span class="nv">DEBUG</span><span class="o">=</span><span class="m">0</span>
361<span class="nv">REQUEST</span><span class="o">=</span><span class="m">0</span>
362<span class="hll"><span class="nv">PUBLIC</span><span class="o">=</span><span class="m">1</span>
363</span></pre></div>
364</div>
365</td>
366</tr>
367</tbody>
368</table>
369<p>This would retrieve a one day (08.09.2000) <em>CERA-20C</em> dataset with 3 hourly temporal resolution and a small 1° domain over Europe. The destination location for this retrieval will be within the <code class="docutils literal notranslate"><span class="pre">Workspace</span></code> directory within <code class="docutils literal notranslate"><span class="pre">Run</span></code>. This can be changed to whatever path you like. The parameters listed in <code class="docutils literal notranslate"><span class="pre">run_local.sh</span></code> would overwrite existing settings in the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file.</p>
370<p>To start the retrieval you then start the script by:</p>
371<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>./run_local.sh
372</pre></div>
373</div>
374<p>While job submission on the local host is convenient and easy to monitor (on standard output), there are a few caveats with this option:</p>
375<blockquote>
376<div><ol class="arabic simple">
377<li><p>There is a maximum size of 20GB for single retrieval via ECMWF Web API. Normally this is not a problem but for global fields with T1279 resolution and hourly time steps the limit may already apply.</p></li>
378<li><p>If the retrieved MARS files are large but the resulting files are relative small (small local domain) then the retrieval to the local host may be inefficient since all data must be transferred via the Internet. This scenario applies most notably if <code class="docutils literal notranslate"><span class="pre">etadot</span></code> has to be calculated via the continuity equation as this requires global fields even if the domain is local. In this case job submission via ecgate might be a better choice. It really depends on the use patterns and also on the internet connection speed.</p></li>
379</ol>
380</div></blockquote>
381</div>
382</div>
383<div class="section" id="selection-and-adjustment-of-control-files">
384<h2>Selection and adjustment of <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files<a class="headerlink" href="#selection-and-adjustment-of-control-files" title="Permalink to this headline"></a></h2>
385<p>This section describes how to work with the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files. A detailed explanation of <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file parameters and naming compositions can be found <a class="reference external" href="Documentation/Input/control.html">here</a>. The more accurately the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file describes the retrieval needed, the fewer command-line parameters are needed to be set in the <code class="docutils literal notranslate"><span class="pre">run</span></code> scripts. With version <code class="docutils literal notranslate"><span class="pre">7.1</span></code> all <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file parameters have default values. They can be found in section <a class="reference external" href="Documentation/Input/control_params.html">CONTROL parameters</a> or in the <code class="docutils literal notranslate"><span class="pre">CONTROL.documentation</span></code> file within the <code class="docutils literal notranslate"><span class="pre">Control</span></code> directory. Only those parameters which need to be changed for a dataset retrieval needs to be set in a <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file!</p>
386<p>The limitation of a dataset to be retrieved should be done very cautiously. The datasets can differ in many ways and vary over the time in resolution and parameterisations methods, especially the operational model cycles improves through a lot of changes over the time. If you are not familiar with the data it might be useful or necessary to check for availability of data in ECMWF’s MARS:</p>
387<blockquote>
388<div><ul class="simple">
389<li><p><strong>Public users</strong> can use a web mask to check on data or list available data at this <a class="reference external" href="https://apps.ecmwf.int/datasets/">Public datasets web interface</a>.</p></li>
390<li><p><strong>Member state users</strong> can check availability of data online in the <a class="reference external" href="https://apps.ecmwf.int/mars-catalogue/">MARS catalogue</a>.</p></li>
391</ul>
392</div></blockquote>
393<p>There you can select step by step what data suits your needs. This would be the most straightforeward way of checking for available data and therefore limit the possibility of <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> to fail. The following figure gives an example how the web interface would look like:</p>
394<div class="figure align-default" id="ref-fig-mars-catalogue-ss">
395<img alt="_images/MARS_catalogue_snapshot.png" src="_images/MARS_catalogue_snapshot.png" />
396</div>
397<p>Additionally, you can find a lot of helpful links to dataset documentations, direct links to specific dataset web catalogues or further general information at the <a class="reference external" href="Ecmwf/ec-links.html">link collection</a> in the ECMWF data section.</p>
398<p><code class="docutils literal notranslate"><span class="pre">Flex_extract</span></code> is specialised to retrieve a limited number of datasets, namely <em>ERA-Interim</em>, <em>CERA-20C</em>, <em>ERA5</em> and <em>HRES (operational data)</em> as well as the <em>ENS (operational data, 15-day forecast)</em>. The limitation relates mainly to the dataset itself, the stream (what kind of forecast or what subset of dataset) and the experiment number. Mostly, the experiment number is equal to <code class="docutils literal notranslate"><span class="pre">1</span></code> to signal that the actual version should be used.</p>
399<p>The next level of differentiation would be the field type, level type and time period. <code class="docutils literal notranslate"><span class="pre">Flex_extract</span></code> currently only supports the main streams for the re-analysis datasets and provides extraction of different streams for the operational dataset. The possibilities of compositions of dataset and stream selection are represented by the current list of example <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files. You can see this in the naming of the example files:</p>
400<div class="literal-block-wrapper docutils container" id="id3">
401<div class="code-block-caption"><span class="caption-text">“Current example <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files distributed with <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code>. “</span><a class="headerlink" href="#id3" title="Permalink to this code"></a></div>
402<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>CONTROL_CERA
403CONTROL_CERA.global
404CONTROL_CERA.public
405CONTROL_EA5
406CONTROL_EA5.global
407CONTROL_EI
408CONTROL_EI.global
409CONTROL_EI.public
410CONTROL_OD.ELDA.FC.eta.ens.double
411CONTROL_OD.ENFO.CF
412CONTROL_OD.ENFO.CV
413CONTROL_OD.ENFO.PF
414CONTROL_OD.ENFO.PF.36hours
415CONTROL_OD.ENFO.PF.ens
416CONTROL_OD.OPER.4V.operational
417CONTROL_OD.OPER.FC.36hours
418CONTROL_OD.OPER.FC.eta.global
419CONTROL_OD.OPER.FC.eta.highres
420CONTROL_OD.OPER.FC.gauss.highres
421CONTROL_OD.OPER.FC.operational
422CONTROL_OD.OPER.FC.twicedaily.1hourly
423CONTROL_OD.OPER.FC.twicedaily.3hourly
424</pre></div>
425</div>
426</div>
427<p>The main differences and features in the datasets are listed in the table shown below:</p>
428<div class="figure align-default" id="ref-tab-dataset-cmp">
429<img alt="_images/dataset_cmp_table.png" src="_images/dataset_cmp_table.png" />
430</div>
431<p>A common problem for beginners in retrieving ECMWF datasets is a mismatch in the choice of values for these parameters. For example, if you try to retrieve operational data for 24 June 2013 or earlier and set the maximum level to 137, you will get an error because this number of levels was introduced only on 25 June 2013. Thus, be careful in the combination of space and time resolution as well as the field types.</p>
432<div class="admonition note">
433<p class="admonition-title">Note</p>
434<p>Sometimes it might not be clear how specific parameters in the control file must be set in terms of format. Please consult the description of the parameters in section <a class="reference external" href="Documentation/Input/control_params.html">CONTROL parameters</a> or have a look at the ECMWF user documentation for <a class="reference external" href="https://confluence.ecmwf.int/display/UDOC/MARS+keywords">MARS keywords</a></p>
435</div>
436<p>In the following, we shortly discuss the typical retrievals for the different datasets and  point to the respective <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files.</p>
437<div class="section" id="public-datasets">
438<h3>Public datasets<a class="headerlink" href="#public-datasets" title="Permalink to this headline"></a></h3>
439<p>The main characteristic in the definition of a <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file for a public dataset is the parameter <code class="docutils literal notranslate"><span class="pre">DATASET</span></code>. Its specification enables the selection of a public dataset in MARS. Without this parameter, the request would not find the dataset.
440For the two public datasets <em>CERA-20C</em> and <em>ERA-Interim</em> an example file with the ending <code class="docutils literal notranslate"><span class="pre">.public</span></code> is provided and can be used straightaway.</p>
441<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>CONTROL_CERA.public
442CONTROL_EI.public
443</pre></div>
444</div>
445<p>For <em>CERA-20C</em> it seems that there are no differences compared the full dataset, whereas the <em>public ERA-Interim</em> has only 6-hourly analysis fields, without forecasts to fill in between, for model levels. Therefore, it is only possible to retrieve 6-hourly data for <em>public ERA-Interim</em>.</p>
446<div class="admonition note">
447<p class="admonition-title">Note</p>
448<p>In principle, <em>ERA5</em> is a public dataset. However, since the model levels are not yet publicly available, it is not possible to retrieve <em>ERA5</em> data to drive the <code class="docutils literal notranslate"><span class="pre">FLEXPART</span></code> model. As soon as this is possible it will be announced at the community website and on the FLEXPART user email list.</p>
449</div>
450</div>
451<div class="section" id="cera">
452<h3>CERA<a class="headerlink" href="#cera" title="Permalink to this headline"></a></h3>
453<p>For this dataset, it is important to keep in mind that it is available for the period 09/1901 until 12/2010, and that the temporal resolution is limited to 3 h.
454It is also a pure ensemble data assimilation dataset and is stored under the <code class="docutils literal notranslate"><span class="pre">enda</span></code> stream.
455There are 10 ensemble members. The example <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files retrieves the first member only (<code class="docutils literal notranslate"><span class="pre">number=0</span></code>). You may change this to another number or a list of numbers (e.g. <code class="docutils literal notranslate"><span class="pre">NUMBER</span> <span class="pre">0/to/10</span></code>).
456Another important difference to all other datasets is that there is one forecast per day, starting at 18 UTC. The forecast lead time is 24 hours and extends beyond the calendar day. Therefore, <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> needs to extract also the day before the first day for which data are desired, which is handled automatically.</p>
457</div>
458<div class="section" id="era-5">
459<h3>ERA 5<a class="headerlink" href="#era-5" title="Permalink to this headline"></a></h3>
460<p>This is the latest re-analysis dataset, and has a temporal resolution of 1-h (analysis fields). At the time of writing, it is available until April 2019 with regular release of new months.
461The original horizontal resolution is 0.28125° which needs some caution in the definition of the domain, since the length of the domain in longitude or latitude direction  must be an integer multiple of the resolution. It is also possible to use <code class="docutils literal notranslate"><span class="pre">0.25</span></code> for the resolution; MARS will then automatically interpolate to this resolution which is still close enough to be acceptable.
462The forecast starting time is <code class="docutils literal notranslate"><span class="pre">06/18</span> <span class="pre">UTC</span></code> which is important for the flux data. Correspondingly, one should set in the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file <code class="docutils literal notranslate"><span class="pre">ACCTIME</span> <span class="pre">06/18</span></code>, <code class="docutils literal notranslate"><span class="pre">ACCMAXSTEP</span> <span class="pre">12</span></code>, and <code class="docutils literal notranslate"><span class="pre">ACCTYPE</span> <span class="pre">FC</span></code>.</p>
463<div class="admonition note">
464<p class="admonition-title">Note</p>
465<p><em>ERA5</em> also includes an ensemble data assimilation system but related fields are not yet retrievable with <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> since the deaccumulation of the flux fields works differently in this stream. Ensemble field retrieval for <em>ERA5</em> is a <em>to-do</em> for the future.</p>
466</div>
467</div>
468<div class="section" id="era-interim">
469<h3>ERA-Interim<a class="headerlink" href="#era-interim" title="Permalink to this headline"></a></h3>
470<p>The production of this re-analysis dataset has stopped on 31 August 2019!
471It is available for the period from 1 January 1979 to 31 August 2019. The <code class="docutils literal notranslate"><span class="pre">etadot</span></code> parameter is not available in this dataset. Therefore, one must use the <code class="docutils literal notranslate"><span class="pre">GAUSS</span></code> parameter, which retrieves the divergence field in addition and calculates the vertical velocity from the continuity equation in the Fortran program <code class="docutils literal notranslate"><span class="pre">calc_etadot</span></code>. While the analysis fields are only available for every 6th hour, the dataset can be made 3-hourly by adding forecast fields in between. No ensemble members are available.</p>
472</div>
473<div class="section" id="operational-data">
474<h3>Operational data<a class="headerlink" href="#operational-data" title="Permalink to this headline"></a></h3>
475<p>This data set provides the output of the real-time atmospheric model runs in high resolution, including 10-day forecasts. The model undergoes frequent adaptations and improvements. Thus, retrieving data from this dataset requires extra attention in selecting correct settings of the parameters. See <a class="reference internal" href="#ref-tab-dataset-cmp"><span class="std std-ref">[Table of datasets]</span></a> for the most important parameters.
476Currently, fields can be retrieved at 1 h temporal resolution by filling the gaps between analysis fields with 1-hourly forecast fields. Since 4 June 2008, the eta coordinate vertical velocity is directly available from MARS, therefore <code class="docutils literal notranslate"><span class="pre">ETA</span></code> should be set to <code class="docutils literal notranslate"><span class="pre">1</span></code> to save computation time. The horizontal resolution can be up to <code class="docutils literal notranslate"><span class="pre">0.1°</span></code> and in combination with <code class="docutils literal notranslate"><span class="pre">137</span></code> vertical levels can lead to problems in terms of job duration and disk space quota.
477It is recommended to submit such high resolution cases as single day retrievals (see <code class="docutils literal notranslate"><span class="pre">JOB_CHUNK</span></code> parameter in <code class="docutils literal notranslate"><span class="pre">run.sh</span></code> script) to avoid job failures due to exceeding limits.</p>
478<p><code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> files for standard retrievals with a mix of analysis and forecast fields are listed below:</p>
479<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>CONTROL_OD.OPER.4V.eta.global
480CONTROL_OD.OPER.FC.eta.global
481CONTROL_OD.OPER.FC.eta.highres
482CONTROL_OD.OPER.FC.gauss.highres
483</pre></div>
484</div>
485<p>These files defines the minimum number of parameters necessary to retrieve a daily subset. The given settings for the TYPE parameter are already optimised, and should only be changed if you know what you are doing. Grid, domain, and temporal resolution may be changed according to availability.</p>
486<div class="admonition note">
487<p class="admonition-title">Note</p>
488<p>Please see <a class="reference external" href="https://confluence.ecmwf.int/display/UDOC/Retrieve#Retrieve-Retrievalefficiency">Information about MARS retrievement</a> for hints about retrieval efficiency and troubleshooting.</p>
489</div>
490<dl>
491<dt>Long forecast</dt><dd><p>It is possible to retrieve long forecasts exceeding one day. The forecast period available depends on the date and forecast field type. Please use MARS catalogue to check the availability. Below are some examples for 36 hour forecasts of <em>Forecast (FC)</em>, <em>Control forecast (CF)</em> and <em>Calibration/Validation forecast (CV)</em>.
492The <em>CV</em> field type was only available 3-hourly from 2006 up to 2016. It is recommended to use the <em>CF</em> type since this is available from 1992 (3-hourly) on up to today (1-hourly). <em>CV</em> and <em>CF</em> field types belong to the <em>Ensemble prediction system (ENFO)</em> which currently works with 50 ensemble members.
493Please be aware that in this case it is necessary to set the type for flux fields explicitly, otherwise a default value might be selected, different from what you expect!</p>
494<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>CONTROL_OD.ENFO.CF.36hours
495CONTROL_OD.ENFO.CV.36hours
496CONTROL_OD.OPER.FC.36hours
497</pre></div>
498</div>
499</dd>
500<dt>Half-day retrievals</dt><dd><p>If a forecast is wanted for half a day only, this can be done by substituting the analysis fields by forecast fields as shown in files with <code class="docutils literal notranslate"><span class="pre">twicedaily</span></code> in their name. They produce a full-day retrieval with pure 12 hour forecasts, twice a day. It is also possible to use the operational version which would obtain the time information from ECMWF’s environment variables and therefore use the newest forecast for each day. This version uses a <code class="docutils literal notranslate"><span class="pre">BASETIME</span></code> parameter which tells MARS to extract the exact 12 hours up to the selected date. If the <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file with <code class="docutils literal notranslate"><span class="pre">basetime</span></code> in the filename is used, this can be done for any other date, too.</p>
501<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>CONTROL_OD.OPER.FC.eta.basetime
502CONTROL_OD.OPER.FC.operational
503CONTROL_OD.OPER.FC.twicedaily.1hourly
504CONTROL_OD.OPER.FC.twicedaily.3hourly
505</pre></div>
506</div>
507</dd>
508<dt>Ensemble members</dt><dd><p>The retrieval of ensemble members was already mentioned in the pure forecast section and for <em>CERA-20C</em> data.
509This <code class="docutils literal notranslate"><span class="pre">flex_extract</span></code> version allows to retrieve the <em>Ensemble Long window Data Assimilation (ELDA)</em> stream from the operational dataset. Until May 2019, there were 25 ensemble members and a control run (<code class="docutils literal notranslate"><span class="pre">number</span> <span class="pre">0</span></code>). Starting with June 2019, the number of ensemble members has been increased to 50. Therefore, we created the option to create 25 additional “pseudo-ensemble members” for periods before June 2019. The original 25 members from MARS are taken, and the difference between the member value and the control value is subtracted twice. This is done if the parameter <code class="docutils literal notranslate"><span class="pre">DOUBLEELDA</span></code> is included and set it to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
510<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>CONTROL_OD.ELDA.FC.eta.ens.double
511CONTROL_OD.ENFO.PF.ens
512</pre></div>
513</div>
514</dd>
515</dl>
516</div>
517<div class="section" id="specific-features">
518<h3>Specific features<a class="headerlink" href="#specific-features" title="Permalink to this headline"></a></h3>
519<dl class="simple">
520<dt>rrint</dt><dd><p>Selects the disaggregation scheme for precipitation flux: old (<code class="docutils literal notranslate"><span class="pre">0</span></code>) or new (<code class="docutils literal notranslate"><span class="pre">1</span></code>). See <a class="reference internal" href="Documentation/disagg.html"><span class="doc">Disaggregation of flux data</span></a> for explanation.</p>
521</dd>
522<dt>cwc</dt><dd><p>If present and set to <code class="docutils literal notranslate"><span class="pre">1</span></code>, the total cloud water content will be retrieved in addition. This is the sum of cloud liquid and cloud ice water content.</p>
523</dd>
524<dt>addpar</dt><dd><p>With this parameter. an additional list of 2-dimensional, non-flux parameters can be retrieved. Use the format <code class="docutils literal notranslate"><span class="pre">param1/param2/.../paramx</span></code> to list the parameters. Please be consistent in using either the parameter IDs or the short names as defined by MARS.</p>
525</dd>
526<dt>doubleelda</dt><dd><p>Use this to double the ensemble member number by adding further disturbance to each member (to be used with 25 members).</p>
527</dd>
528<dt>debug</dt><dd><p>If set to <code class="docutils literal notranslate"><span class="pre">1</span></code>, all temporary files are preserved. Otherwise, everything except the final output files will be deleted.</p>
529</dd>
530<dt>request</dt><dd><p>This produces an extra <em>csv</em> file <code class="docutils literal notranslate"><span class="pre">mars_requests.csv</span></code> where the content of each MARS request submitted within the job is stored, which is useful for debugging and documentation. Possible values are 0 for normal data retrieval, 1 for not retrieving data and just writing out the MARS requests, and 2 to retrieve data and write out requests.</p>
531</dd>
532<dt>mailfail</dt><dd><p>As a default, e-mails are sent to the mail address defined for the ECMWF user account. It is possible to overwrite this by specifying one or more e-mail addresses (comma-separated list). In order to include the e-mail associated with the user account, add <code class="docutils literal notranslate"><span class="pre">${USER}</span></code> to the list.</p>
533</dd>
534</dl>
535</div>
536<div class="section" id="hints-for-proper-definition-of-certain-parameter-combinations">
537<h3>Hints for proper definition of certain parameter combinations<a class="headerlink" href="#hints-for-proper-definition-of-certain-parameter-combinations" title="Permalink to this headline"></a></h3>
538<dl>
539<dt>Field type and time</dt><dd><p>This combination is very important. It defines the temporal resolution and which field type is extracted on each time step.
540The time declaration for analysis (AN) fields uses the times of the specific analysis while the (forecast time) step has to be <code class="docutils literal notranslate"><span class="pre">0</span></code>.
541The forecast field types (e.g. FC, CF, CV, PF) need to declare a combination of (forescast start) time and the (forecast) step. Together they define the actual time. It is important to know the forecast starting times for the dataset to be retrieved, since they are different. In general, it is sufficient to give information for the exact time steps, but it is also possible to have more time step combinations of <code class="docutils literal notranslate"><span class="pre">TYPE</span></code>, <code class="docutils literal notranslate"><span class="pre">TIME</span></code> and <code class="docutils literal notranslate"><span class="pre">STEP</span></code> because the temporal (hourly) resolution with the <code class="docutils literal notranslate"><span class="pre">DTIME</span></code> parameter will select the correct combinations.</p>
542<div class="literal-block-wrapper docutils container" id="id4">
543<div class="code-block-caption"><span class="caption-text">Example of a setting for the field types and temporal resolution. It will retrieve 3-hourly fields, with analyses at 00 and 12 UTC and the corresponding forecasts inbetween.</span><a class="headerlink" href="#id4" title="Permalink to this code"></a></div>
544<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> DTIME <span class="m">3</span>
545 TYPE AN FC FC FC AN FC FC FC
546 TIME <span class="m">00</span> <span class="m">00</span> <span class="m">00</span> <span class="m">00</span> <span class="m">12</span> <span class="m">12</span> <span class="m">12</span> <span class="m">12</span>
547 STEP <span class="m">00</span> <span class="m">03</span> <span class="m">06</span> <span class="m">09</span> <span class="m">00</span> <span class="m">03</span> <span class="m">06</span> <span class="m">09</span>
548</pre></div>
549</div>
550</div>
551</dd>
552<dt>Vertical velocity</dt><dd><p>The vertical velocity for <code class="docutils literal notranslate"><span class="pre">FLEXPART</span></code> is not directly available from MARS and has to be calculated.
553There are several options for this, and the following parameters are responsible for the selection.                 See <a class="reference internal" href="Documentation/vertco.html"><span class="doc">Vertical wind</span></a> for a detailed explanation. Using <code class="docutils literal notranslate"><span class="pre">ETADIFF</span> <span class="pre">1</span></code>, <code class="docutils literal notranslate"><span class="pre">OMEGA</span> <span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">OMEGADIFF</span> <span class="pre">1</span></code> is recommended for debugging and testing only.
554Usually, one has to decide between <code class="docutils literal notranslate"><span class="pre">GAUSS</span> <span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">ETA</span> <span class="pre">1</span></code>. <code class="docutils literal notranslate"><span class="pre">GAUSS</span> <span class="pre">1</span></code> means that spectral fields of the horizontal wind fields and the divergence are retrieved and that the vertical velocity is calculate using the continuity equation. <code class="docutils literal notranslate"><span class="pre">ETA</span> <span class="pre">1</span></code> means that horizontal wind fields etadot are retrieved on a regular lat-lon grid. It is recommended to use <code class="docutils literal notranslate"><span class="pre">ETA</span> <span class="pre">1</span></code> where possible, as there is a substantial computational overhead for solving the continuity equation.</p>
555<div class="literal-block-wrapper docutils container" id="id5">
556<div class="code-block-caption"><span class="caption-text">Example setting for the vertical coordinate retrieval (recommended if etadot fields are available).</span><a class="headerlink" href="#id5" title="Permalink to this code"></a></div>
557<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>GAUSS <span class="m">0</span>
558ETA <span class="m">1</span>
559ETADIFF <span class="m">0</span>
560DPDETA <span class="m">1</span>
561OMEGA <span class="m">0</span>
562OMEGADIFF <span class="m">0</span>
563</pre></div>
564</div>
565</div>
566</dd>
567<dt>Grid resolution and domain</dt><dd><p>The grid and domain parameters depends on each other. <code class="docutils literal notranslate"><span class="pre">grid</span></code> refers to the grid resolution. It can be given as decimal values (e.g., <code class="docutils literal notranslate"><span class="pre">1.</span></code> meaning 1.0°), or as in previous versions of flex_extract, as integer values refering to 1/1000 degrees (e.g., <code class="docutils literal notranslate"><span class="pre">1000</span></code> means also 1°). The code applies common sense to determine what format is to be assumed.
568After selecting grid, the <code class="docutils literal notranslate"><span class="pre">domain</span></code> has to be defined. The extension in longitude or latitude direction must be an integer multiple of <code class="docutils literal notranslate"><span class="pre">grid</span></code>.</p>
569<p>The horizontal resolution for spectral fields is set by the parameter <code class="docutils literal notranslate"><span class="pre">RESOL</span></code>. For information about how to select an appropriate value please read the explanation of the MARS keyword RESOL as found <a class="reference external" href="https://confluence.ecmwf.int/display/UDOC/Post-processing+keywords#Post-processingkeywords-resol">in this entry of the ECMWF on-line documentation</a> and  <a class="reference external" href="https://confluence.ecmwf.int/display/UDOC/Retrieve#Retrieve-Truncationbeforeinterpolation">this table (also ECMWF documentation)</a>.</p>
570<div class="literal-block-wrapper docutils container" id="id6">
571<div class="code-block-caption"><span class="caption-text">Example setting for a domain covering the northern hemisphere domain with a grid resolution of <code class="docutils literal notranslate"><span class="pre">0.25°</span></code>.</span><a class="headerlink" href="#id6" title="Permalink to this code"></a></div>
572<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>GRID <span class="m">0</span>.25
573RESOL <span class="m">799</span>
574SMOOTH <span class="m">0</span>
575UPPER <span class="m">90</span>.
576LOWER <span class="m">0</span>.
577LEFT -179.75
578RIGHT <span class="m">180</span>.
579</pre></div>
580</div>
581</div>
582</dd>
583<dt>Flux data</dt><dd><p>Flux fields are always forecast fields and contain values of the fluxes accumulated since the start of the respective forecast. As certain re-analysis dataset cover all time steps with analysis fields, it was necessary to define a new parameter set for the definition of the flux fields. The following parameters are used specifically for flux fields. <code class="docutils literal notranslate"><span class="pre">ACCTYPE</span></code> is the field type (must be a type of forecast), <code class="docutils literal notranslate"><span class="pre">ACCTIME</span></code>  the forecast starting time, and  <code class="docutils literal notranslate"><span class="pre">ACCMAXSTEP</span></code> the maximum forecast step;``DTIME`` the temporal resolution. ACCTYPE is assumed to be the same during the whole period given by ACCTIME and ACCMAXSTEP. These values will be set automatically if not provided in a <code class="docutils literal notranslate"><span class="pre">CONTROL</span></code> file.</p>
584<div class="literal-block-wrapper docutils container" id="id7">
585<div class="code-block-caption"><span class="caption-text">Example setting for the definition of flux fields.</span><a class="headerlink" href="#id7" title="Permalink to this code"></a></div>
586<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> DTIME <span class="m">3</span>
587 ACCTYPE FC
588 ACCTIME <span class="m">00</span>/12
589 ACCMAXSTEP <span class="m">36</span>
590</pre></div>
591</div>
592</div>
593</dd>
594</dl>
595<div class="toctree-wrapper compound">
596</div>
597</div>
598</div>
599</div>
600
601
602           </div>
603           
604          </div>
605          <footer>
606 
607    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
608     
609        <a href="documentation.html" class="btn btn-neutral float-right" title="Code-Level Documentation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
610     
611     
612        <a href="Installation/local.html" class="btn btn-neutral float-left" title="Local mode installation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
613     
614    </div>
615 
616
617  <hr/>
618
619  <div role="contentinfo">
620    <p>
621        &copy; Copyright 2020, Anne Philipp, Leopold Haimberger and Petra Seibert
622
623    </p>
624  </div>
625  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
626
627</footer>
628
629        </div>
630      </div>
631
632    </section>
633
634  </div>
635 
636
637
638  <script type="text/javascript">
639      jQuery(function () {
640          SphinxRtdTheme.Navigation.enable(true);
641      });
642  </script>
643
644 
645 
646   
647   
648
649</body>
650</html>
Note: See TracBrowser for help on using the repository browser.
hosted by ZAMG