-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtutorial.html
507 lines (484 loc) · 64.6 KB
/
tutorial.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
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Tutorial — OpenDrift documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=4ae1632d" />
<link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery.css?v=d2d258e8" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery-binder.css?v=f4aeca0c" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery-dataframe.css?v=2082cf3c" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery-rendered-html.css?v=1277b6f3" />
<link rel="stylesheet" type="text/css" href="_static/theme_overrides.css" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Theory" href="theory/index.html" />
<link rel="prev" title="Performance in OpenDrift" href="performance.html" />
</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">
OpenDrift
<img src="_static/opendrift_logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="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="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to OpenDrift</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="history_link.html">History</a></li>
<li class="toctree-l1"><a class="reference internal" href="install.html">Installing OpenDrift</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance in OpenDrift</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#import-a-specific-model-for-the-relevant-application">1. Import a specific <strong>model</strong> for the relevant application</a></li>
<li class="toctree-l2"><a class="reference internal" href="#adding-readers">2. Adding <strong>Readers</strong></a><ul>
<li class="toctree-l3"><a class="reference internal" href="#lazy-readers">2.1 Lazy Readers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#seeding-elements">3. Seeding elements</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuration">4. Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="#running-the-model">5. Running the model</a></li>
<li class="toctree-l2"><a class="reference internal" href="#plotting-and-analysing-the-results">6. Plotting and analysing the results</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="theory/index.html">Theory</a></li>
<li class="toctree-l1"><a class="reference internal" href="theory/index.html#drift-in-the-ocean">Drift in the Ocean</a></li>
<li class="toctree-l1"><a class="reference internal" href="choosing_a_model.html">How to choose which model to use</a></li>
<li class="toctree-l1"><a class="reference internal" href="writing_a_new_model.html">How to write a new module</a></li>
<li class="toctree-l1"><a class="reference internal" href="gallery/index.html">Gallery</a></li>
<li class="toctree-l1"><a class="reference internal" href="oil_types.html">Oil types</a></li>
<li class="toctree-l1"><a class="reference internal" href="interaction_with_coastline.html">Interaction with coastline</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker.html">Using OpenDrift in a container</a></li>
<li class="toctree-l1"><a class="reference internal" href="gui.html">Graphical User Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="references.html">Publications</a></li>
<li class="toctree-l1"><a class="reference internal" href="services.html">Services using OpenDrift</a></li>
<li class="toctree-l1"><a class="reference internal" href="autoapi/index.html">API Reference</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">OpenDrift</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Tutorial</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/tutorial.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="tutorial">
<h1>Tutorial<a class="headerlink" href="#tutorial" title="Link to this heading"></a></h1>
<p>OpenDrift does come with a basic <a class="reference internal" href="gui.html"><span class="doc">graphical user interface</span></a>, but the most flexible and powerful way to operate the model is through a set of Python commands. This requires only basic knowledge of Python.</p>
<p>The best way to get familiar with OpenDrift is to run and examine/edit the example-scripts located in the <a class="reference external" href="https://github.com/OpenDrift/opendrift/tree/master/examples">examples</a> folder (also shown in the <a class="reference internal" href="gallery/index.html"><span class="doc">gallery</span></a>). The main steps involved are explained below.</p>
<section id="import-a-specific-model-for-the-relevant-application">
<h2>1. Import a specific <strong>model</strong> for the relevant application<a class="headerlink" href="#import-a-specific-model-for-the-relevant-application" title="Link to this heading"></a></h2>
<p>The first step is to decide which model to use, based on your application. All available models are stored in the subfolder <a class="reference internal" href="autoapi/opendrift/models/index.html#module-opendrift.models" title="opendrift.models"><code class="xref py py-mod docutils literal notranslate"><span class="pre">models</span></code></a>. The .py files in this folder are Python “modules” containing a class which is a subclass (specialisation) of the generic class <a class="reference internal" href="autoapi/opendrift/models/basemodel/index.html#opendrift.models.basemodel.OpenDriftSimulation" title="opendrift.models.basemodel.OpenDriftSimulation"><code class="xref py py-mod docutils literal notranslate"><span class="pre">OpenDriftSimulation</span></code></a>.</p>
<p>The most basic model, <a class="reference internal" href="autoapi/opendrift/models/oceandrift/index.html#opendrift.models.oceandrift.OceanDrift" title="opendrift.models.oceandrift.OceanDrift"><code class="xref py py-mod docutils literal notranslate"><span class="pre">OceanDrift</span></code></a>, is suitable for passive tracers (substances with no properties except for position, flowing with the ocean current) or objects at the ocean surface which may be subject to an additional wind drag. <strong>OceanDrift</strong> may be imported with the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">opendrift.models.oceandrift</span><span class="w"> </span><span class="kn">import</span> <span class="n">OceanDrift</span>
</pre></div>
</div>
<p>For Search and Rescue applications, the <a class="reference internal" href="autoapi/opendrift/models/leeway/index.html#module-opendrift.models.leeway" title="opendrift.models.leeway"><code class="xref py py-mod docutils literal notranslate"><span class="pre">Leeway</span></code></a> model (class) may be imported with the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">opendrift.models.leeway</span><span class="w"> </span><span class="kn">import</span> <span class="n">Leeway</span>
</pre></div>
</div>
<p>For oil drift applications, import the <a class="reference internal" href="autoapi/opendrift/models/openoil/index.html#module-opendrift.models.openoil" title="opendrift.models.openoil"><code class="xref py py-mod docutils literal notranslate"><span class="pre">OpenOil</span></code></a> model by the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">opendrift.models.openoil</span><span class="w"> </span><span class="kn">import</span> <span class="n">OpenOil</span>
</pre></div>
</div>
<p>A simulation instance (object) is created by calling the imported class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span> <span class="o">=</span> <span class="n">OpenOil</span><span class="p">(</span><span class="n">loglevel</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
</pre></div>
</div>
<p>The argument loglevel is optional, and 0 (debug mode, default) means that a lot of diagnostic information is displayed to the terminal during the run. This may be useful if something goes wrong. Use a value of 20 to get only a minimum of information, or a value of 50 for no output at all.</p>
<p><a class="reference internal" href="autoapi/opendrift/models/openoil/index.html#module-opendrift.models.openoil" title="opendrift.models.openoil"><code class="xref py py-mod docutils literal notranslate"><span class="pre">OpenOil</span></code></a> uses the element type <a class="reference internal" href="autoapi/opendrift/models/openoil/index.html#opendrift.models.openoil.Oil" title="opendrift.models.openoil.Oil"><code class="xref py py-mod docutils literal notranslate"><span class="pre">Oil</span></code></a> (subclass of <a class="reference internal" href="autoapi/opendrift/elements/elements/index.html#opendrift.elements.elements.LagrangianArray" title="opendrift.elements.elements.LagrangianArray"><code class="xref py py-mod docutils literal notranslate"><span class="pre">LagrangianArray</span></code></a>), which defines some properties specific to oil (e.g. density, viscosity…). The element class may be defined in the same module/file as the trajectory model class, as in this case, or imported from the various element types in the subfolder <a class="reference internal" href="autoapi/opendrift/elements/index.html#module-opendrift.elements" title="opendrift.elements"><code class="xref py py-mod docutils literal notranslate"><span class="pre">opendrift.elements</span></code></a>, for possible re-use by other models.</p>
<p>Any <strong>model</strong> contains at least the function <strong>update()</strong> which is called at each step of the model run to update the positions and properties of particles (added when seeding, see below) using environmental data (wind, current, temperature…) provided by some <strong>readers</strong> (below).
A specific model implementation does not need to worry about map projections, vector orientations, how data are obtained, etc - it will focus on the advection/physical/chemical processes only.</p>
<p>With OpenDrift it is fairly easy to <a class="reference internal" href="writing_a_new_model.html"><span class="doc">make your own model/class</span></a> by simply defining element properties and an update function to describe the desired advection and other processes.</p>
</section>
<section id="adding-readers">
<h2>2. Adding <strong>Readers</strong><a class="headerlink" href="#adding-readers" title="Link to this heading"></a></h2>
<p>Readers are independent Python objects which provide the variables (e.g. current, wind, temperature…) needed by the model to update particle properties. Readers normally read from a file (hence the name) or from a remote URL, or use some analytical function such as <a class="reference internal" href="autoapi/opendrift/readers/reader_ArtificialOceanEddy/index.html#module-opendrift.readers.reader_ArtificialOceanEddy" title="opendrift.readers.reader_ArtificialOceanEddy"><code class="xref py py-mod docutils literal notranslate"><span class="pre">this</span> <span class="pre">idealistic</span> <span class="pre">eddy</span></code></a>.
Different reader classes exist for different file types. E.g. for data following the NetCDF CF-convention, use the following class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">opendrift.readers</span><span class="w"> </span><span class="kn">import</span> <span class="n">reader_netCDF_CF_generic</span>
</pre></div>
</div>
<p>A Reader instance may then be created to obtain data from a local file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">reader_norkyst</span> <span class="o">=</span> <span class="n">reader_netCDF_CF_generic</span><span class="o">.</span><span class="n">Reader</span><span class="p">(</span><span class="s1">'norkyst800_16Nov2015.nc'</span><span class="p">)</span>
</pre></div>
</div>
<p>To generate a reader for data on a Thredds server (here the same reader class may be used, as files are still CF-compliant):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">reader_norkyst</span> <span class="o">=</span> <span class="n">reader_netCDF_CF_generic</span><span class="o">.</span><span class="n">Reader</span><span class="p">(</span>
<span class="s1">'https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be'</span><span class="p">)</span>
</pre></div>
</div>
<p>The reader can be inspected with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">reader_norkyst</span><span class="p">)</span>
<span class="o">===========================</span>
<span class="n">Reader</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">thredds</span><span class="o">.</span><span class="n">met</span><span class="o">.</span><span class="n">no</span><span class="o">/</span><span class="n">thredds</span><span class="o">/</span><span class="n">dodsC</span><span class="o">/</span><span class="n">sea</span><span class="o">/</span><span class="n">norkyst800m</span><span class="o">/</span><span class="mi">1</span><span class="n">h</span><span class="o">/</span><span class="n">aggregate_be</span>
<span class="n">Projection</span><span class="p">:</span>
<span class="o">+</span><span class="n">proj</span><span class="o">=</span><span class="n">stere</span> <span class="o">+</span><span class="n">ellps</span><span class="o">=</span><span class="n">WGS84</span> <span class="o">+</span><span class="n">lat_0</span><span class="o">=</span><span class="mf">90.0</span> <span class="o">+</span><span class="n">lat_ts</span><span class="o">=</span><span class="mf">60.0</span> <span class="o">+</span><span class="n">x_0</span><span class="o">=</span><span class="mi">3192800</span> <span class="o">+</span><span class="n">y_0</span><span class="o">=</span><span class="mi">1784000</span> <span class="o">+</span><span class="n">lon_0</span><span class="o">=</span><span class="mi">70</span>
<span class="n">Coverage</span><span class="p">:</span> <span class="p">[</span><span class="n">m</span><span class="p">]</span>
<span class="n">xmin</span><span class="p">:</span> <span class="mf">0.000000</span> <span class="n">xmax</span><span class="p">:</span> <span class="mf">2080800.000000</span> <span class="n">step</span><span class="p">:</span> <span class="mi">800</span> <span class="n">numx</span><span class="p">:</span> <span class="mi">2602</span>
<span class="n">ymin</span><span class="p">:</span> <span class="mf">0.000000</span> <span class="n">ymax</span><span class="p">:</span> <span class="mf">720800.000000</span> <span class="n">step</span><span class="p">:</span> <span class="mi">800</span> <span class="n">numy</span><span class="p">:</span> <span class="mi">902</span>
<span class="n">Corners</span> <span class="p">(</span><span class="n">lon</span><span class="p">,</span> <span class="n">lat</span><span class="p">):</span>
<span class="p">(</span> <span class="o">-</span><span class="mf">1.58</span><span class="p">,</span> <span class="mf">58.50</span><span class="p">)</span> <span class="p">(</span> <span class="mf">23.71</span><span class="p">,</span> <span class="mf">75.32</span><span class="p">)</span>
<span class="p">(</span> <span class="mf">9.19</span><span class="p">,</span> <span class="mf">55.91</span><span class="p">)</span> <span class="p">(</span> <span class="mf">38.06</span><span class="p">,</span> <span class="mf">70.03</span><span class="p">)</span>
<span class="n">Vertical</span> <span class="n">levels</span> <span class="p">[</span><span class="n">m</span><span class="p">]:</span>
<span class="p">[</span><span class="o">-</span><span class="mf">0.0</span> <span class="o">-</span><span class="mf">3.0</span> <span class="o">-</span><span class="mf">10.0</span> <span class="o">-</span><span class="mf">15.0</span> <span class="o">-</span><span class="mf">25.0</span> <span class="o">-</span><span class="mf">50.0</span> <span class="o">-</span><span class="mf">75.0</span> <span class="o">-</span><span class="mf">100.0</span> <span class="o">-</span><span class="mf">150.0</span> <span class="o">-</span><span class="mf">200.0</span> <span class="o">-</span><span class="mf">250.0</span>
<span class="o">-</span><span class="mf">300.0</span> <span class="o">-</span><span class="mf">500.0</span> <span class="o">-</span><span class="mf">1000.0</span> <span class="o">-</span><span class="mf">2000.0</span> <span class="o">-</span><span class="mf">3000.0</span><span class="p">]</span>
<span class="n">Available</span> <span class="n">time</span> <span class="nb">range</span><span class="p">:</span>
<span class="n">start</span><span class="p">:</span> <span class="mi">2017</span><span class="o">-</span><span class="mi">02</span><span class="o">-</span><span class="mi">20</span> <span class="mi">00</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span> <span class="n">end</span><span class="p">:</span> <span class="mi">2019</span><span class="o">-</span><span class="mi">09</span><span class="o">-</span><span class="mi">08</span> <span class="mi">18</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span> <span class="n">step</span><span class="p">:</span> <span class="mi">1</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="mi">22339</span> <span class="n">times</span> <span class="p">(</span><span class="mi">3120</span> <span class="n">missing</span><span class="p">)</span>
<span class="n">Variables</span><span class="p">:</span>
<span class="n">y_wind</span>
<span class="n">sea_water_temperature</span>
<span class="n">upward_sea_water_velocity</span>
<span class="n">eastward_sea_water_velocity</span>
<span class="n">salinity_vertical_diffusion_coefficient</span>
<span class="n">y_sea_water_velocity</span>
<span class="n">longitude</span>
<span class="n">latitude</span>
<span class="n">sea_floor_depth_below_sea_level</span>
<span class="n">northward_sea_water_velocity</span>
<span class="n">sea_water_salinity</span>
<span class="n">x_sea_water_velocity</span>
<span class="n">time</span>
<span class="n">forecast_reference_time</span>
<span class="n">sea_surface_elevation</span>
<span class="n">x_wind</span>
<span class="o">===========================</span>
</pre></div>
</div>
<p>The suitability of a file or URL may also be tested from the Linux/DOS command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./scripts/readerinfo.py <filename/URL>
</pre></div>
</div>
<p>Adding the option -p to the above command will also plot the geographical coverage. From Python the same plot can be obtained with the command <code class="docutils literal notranslate"><span class="pre">reader_norkyst.plot()</span></code></p>
<p>The coverage of the NorKyst ocean model on the met.no Thredds server may e.g. be plotted with the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">readerinfo</span><span class="o">.</span><span class="n">py</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">thredds</span><span class="o">.</span><span class="n">met</span><span class="o">.</span><span class="n">no</span><span class="o">/</span><span class="n">thredds</span><span class="o">/</span><span class="n">dodsC</span><span class="o">/</span><span class="n">sea</span><span class="o">/</span><span class="n">norkyst800m</span><span class="o">/</span><span class="mi">1</span><span class="n">h</span><span class="o">/</span><span class="n">aggregate_be</span> <span class="o">-</span><span class="n">p</span>
</pre></div>
</div>
<img alt="https://www.dropbox.com/s/wb1ztfct47eooy0/norkyst_coverage.png?raw=1" src="https://www.dropbox.com/s/wb1ztfct47eooy0/norkyst_coverage.png?raw=1" />
<p>The variables (e.g. wind, current…) required by a specific model are given in the list “required_variables” in the model class implementation, and may be listed by:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">pprint</span><span class="w"> </span><span class="kn">import</span> <span class="n">pprint</span>
<span class="gp">>>> </span><span class="n">pprint</span><span class="p">(</span><span class="n">OpenOil</span><span class="o">.</span><span class="n">required_variables</span><span class="p">)</span>
<span class="go"> {'land_binary_mask': {'fallback': 0},</span>
<span class="go"> 'ocean_vertical_diffusivity': {'fallback': 0.02,</span>
<span class="go"> 'important': False,</span>
<span class="go"> 'profiles': True},</span>
<span class="go"> 'sea_ice_area_fraction': {'fallback': 0, 'important': False},</span>
<span class="go"> 'sea_ice_x_velocity': {'fallback': 0, 'important': False},</span>
<span class="go"> 'sea_ice_y_velocity': {'fallback': 0, 'important': False},</span>
<span class="go"> 'sea_surface_wave_mean_period_from_variance_spectral_density_second_frequency_moment': {'fallback': 0,</span>
<span class="go"> 'important': False},</span>
<span class="go"> 'sea_surface_wave_period_at_variance_spectral_density_maximum': {'fallback': 0,</span>
<span class="go"> 'important': False},</span>
<span class="go"> 'sea_surface_wave_significant_height': {'fallback': 0, 'important': False},</span>
<span class="go"> 'sea_surface_wave_stokes_drift_x_velocity': {'fallback': 0,</span>
<span class="go"> 'important': False},</span>
<span class="go"> 'sea_surface_wave_stokes_drift_y_velocity': {'fallback': 0,</span>
<span class="go"> 'important': False},</span>
<span class="go"> 'sea_water_salinity': {'fallback': 34, 'profiles': True},</span>
<span class="go"> 'sea_water_temperature': {'fallback': 10, 'profiles': True},</span>
<span class="go"> 'upward_sea_water_velocity': {'fallback': 0, 'important': False},</span>
<span class="go"> 'x_sea_water_velocity': {'fallback': None},</span>
<span class="go"> 'x_wind': {'fallback': None},</span>
<span class="go"> 'y_sea_water_velocity': {'fallback': None},</span>
<span class="go"> 'y_wind': {'fallback': None}}</span>
</pre></div>
</div>
<p>Variable names follow the CF-convention, ensuring that any reader may be used by any model, although developed independently.
It is necessary to add readers for all required variables, unless they have been given a fallback (default) value which is not None.
In the above example, it is only strictly necessary to provide readers for wind and current.
The fallback values will be used for elements which move out of the coverage of a reader in space or time, if there is no other readers which provides the given variable.
Variables where <cite>important</cite> is set to False will only be obtained from readers which are already available, new lazy readers will not be initialized if these are missing.
Most applications will need a landmask, for stranding towards a coastline. The default is to use the global <a class="reference external" href="https://www.soest.hawaii.edu/pwessel/gshhg/">GSHHG database</a> landmask, unless explicitly disabled with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">set_config</span><span class="p">(</span><span class="s1">'general:use_auto_landmask'</span><span class="p">,</span> <span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
<p>After Readers are created, they must be added to the model instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">add_reader</span><span class="p">([</span><span class="n">reader_landmask</span><span class="p">,</span> <span class="n">reader_norkyst</span><span class="p">,</span> <span class="n">reader_nordic</span><span class="p">])</span>
</pre></div>
</div>
<p>The order will decide if several readers provide the same variable. In the above example, current will be obtained from the Reader <strong>reader_norkyst</strong> whenever possible, or else from the Reader <strong>reader_nordic</strong>. The landmask will be taken from the landmask reader since this is listed first, even if the other readers would also contain a landmask (e.g. a coarse raster used by the ocean model).</p>
<p>When later running a simulation, the readers will first read data from file/URL, before interpolating onto the element positions. The default horizontal interpolation method is ‘LinearNDFast’, which interpolates/fill holes (e.g. islands in a coarse ocean model may appears as a large square of no values) and extrapolates towards the (GSHHG) coastline.</p>
<p>Readers also take care of reprojecting all data from their native map projection to a common projection, which is generally necessary as different readers may have different projection. This allows OpenDrift to use raw output from ocean/wave/atmosphere models, without the need to preprocess large amounts of data. Vectors (wind, current) are also rotated to the common calculation projection. By default, the common projection is taken from the first added reader, so that data from this reader must not be reprojected/rotated.</p>
<p>In addition to providing variables interpolated to the element positions, readers will also provide vertical profiles (e.g. from a 3D ocean model) at all positions for variables where <code class="docutils literal notranslate"><span class="pre">profiles</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> in the variable listing above. Profiles are here obtained for salinity, temperature and diffusivity, as these are used for the vertical mixing algorithm. See <a class="reference internal" href="gallery/example_vertical_mixing.html"><span class="doc">Vertical mixing</span></a> for a demonstration.</p>
<section id="lazy-readers">
<h3>2.1 Lazy Readers<a class="headerlink" href="#lazy-readers" title="Link to this heading"></a></h3>
<p>For an operational setup, it is convenient to have a long priority list of available readers/sources, to be sure that the desired location and time is covered by forcing data. However, initialising all readers before the simulation starts may then take some time, especially if the list of readers include some slow or potentially hanging Thredds servers.
The concept of <em>Lazy Readers</em> allows to delay the initialisation of readers until they are actually needed. This minimises statup time, and decreases the risk of hanging. Readers are by default <em>Lazy</em> if they are initiated with the methods <code class="docutils literal notranslate"><span class="pre">add_readers_from_list(<list_of_reader_filenames/URLs>)</span></code> or <code class="docutils literal notranslate"><span class="pre">add_readers_from_file(<file_with_lines</span> <span class="pre">of_reader_filenames/URLs>)</span></code>, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">add_readers_from_list</span><span class="p">([</span><span class="s1">'somelocalfile.nc'</span><span class="p">,</span>
<span class="s1">'https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be'</span><span class="p">,</span>
<span class="s1">'https://thredds.met.no/thredds/dodsC/sea/nordic4km/zdepths1h/aggregate_be'</span><span class="p">])</span>
</pre></div>
</div>
<p>Printing the simulation object then shows that these have been added as lazy readers. Since initialisation of these have been delayed, we do not yet know whether they cover the required variables, but this will be checked whenever necessary during the upcoming simulation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">o</span><span class="p">)</span>
<span class="o">===========================</span>
<span class="n">Model</span><span class="p">:</span> <span class="n">OceanDrift</span> <span class="p">(</span><span class="n">OpenDrift</span> <span class="n">version</span> <span class="mf">1.0.5</span><span class="p">)</span>
<span class="mi">0</span> <span class="n">active</span> <span class="n">PassiveTracer</span> <span class="n">particles</span> <span class="p">(</span><span class="mi">0</span> <span class="n">deactivated</span><span class="p">,</span> <span class="mi">0</span> <span class="n">scheduled</span><span class="p">)</span>
<span class="n">Projection</span><span class="p">:</span> <span class="o">+</span><span class="n">proj</span><span class="o">=</span><span class="n">latlong</span>
<span class="o">-------------------</span>
<span class="n">Environment</span> <span class="n">variables</span><span class="p">:</span>
<span class="o">-----</span>
<span class="n">Readers</span> <span class="ow">not</span> <span class="n">added</span> <span class="k">for</span> <span class="n">the</span> <span class="n">following</span> <span class="n">variables</span><span class="p">:</span>
<span class="n">land_binary_mask</span>
<span class="n">x_sea_water_velocity</span>
<span class="n">x_wind</span>
<span class="n">y_sea_water_velocity</span>
<span class="n">y_wind</span>
<span class="o">---</span>
<span class="n">Lazy</span> <span class="n">readers</span><span class="p">:</span>
<span class="n">LazyReader</span><span class="p">:</span> <span class="n">somelocalfile</span><span class="o">.</span><span class="n">nc</span>
<span class="n">LazyReader</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">thredds</span><span class="o">.</span><span class="n">met</span><span class="o">.</span><span class="n">no</span><span class="o">/</span><span class="n">thredds</span><span class="o">/</span><span class="n">dodsC</span><span class="o">/</span><span class="n">sea</span><span class="o">/</span><span class="n">norkyst800m</span><span class="o">/</span><span class="mi">1</span><span class="n">h</span><span class="o">/</span><span class="n">aggregate_be</span>
<span class="n">LazyReader</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">thredds</span><span class="o">.</span><span class="n">met</span><span class="o">.</span><span class="n">no</span><span class="o">/</span><span class="n">thredds</span><span class="o">/</span><span class="n">dodsC</span><span class="o">/</span><span class="n">sea</span><span class="o">/</span><span class="n">nordic4km</span><span class="o">/</span><span class="n">zdepths1h</span><span class="o">/</span><span class="n">aggregate_be</span>
<span class="o">===========================</span>
</pre></div>
</div>
<p>If <code class="docutils literal notranslate"><span class="pre">somelocalfile.nc</span></code> contains the required variables for the element positions throughout the simulation, the Thredds-readers will never be initialised, thus saving time.
If you want readers to be intialised immediately, you may provide the keyword <code class="docutils literal notranslate"><span class="pre">lazy=False</span></code> to <code class="docutils literal notranslate"><span class="pre">add_readers_from_list()</span></code> or <code class="docutils literal notranslate"><span class="pre">add_readers_from_file()</span></code>.
These methods are robust regarding nonexisting files or URLs, which will then be marked as “Discarded readers” during the simulation.</p>
</section>
</section>
<section id="seeding-elements">
<h2>3. Seeding elements<a class="headerlink" href="#seeding-elements" title="Link to this heading"></a></h2>
<p>Before starting a model run, some elements must be seeded (released).
The simplest case is to seed a single element at a given position and time:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">seed_elements</span><span class="p">(</span><span class="n">lon</span><span class="o">=</span><span class="mf">4.3</span><span class="p">,</span> <span class="n">lat</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="n">time</span><span class="o">=</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2016</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">25</span><span class="p">,</span><span class="mi">18</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">))</span>
</pre></div>
</div>
<p>The time may be defined explicitly as in the above example, or one may e.g. use the starting time of one of the available readers (e.g. time=reader_norkyst.start_time).
To seed 100 elements within a radius of 1000 m:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">seed_elements</span><span class="p">(</span><span class="n">lon</span><span class="o">=</span><span class="mf">4.3</span><span class="p">,</span> <span class="n">lat</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="n">number</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">radius</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span>
<span class="n">time</span><span class="o">=</span><span class="n">reader_norkyst</span><span class="o">.</span><span class="n">start_time</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that the radius is not an absolute boundary within which elements will be seeded, but one standard deviation of a normal distribution in space. Thus about 68% of elements will be seeded within this radius, with more elements near the center.
By default, elements are seeded at the surface (z=0), but the depth may be given as a negative scalar (same for all elements), or as a vector of the same length as the number of elements. Elements may also be seeded at the seafloor by specifying <code class="docutils literal notranslate"><span class="pre">z='seafloor'</span></code>, however, this requires that a reader providing the variable <code class="docutils literal notranslate"><span class="pre">sea_floor_depth_below_sea_level</span></code> has been already been added. It is also possible to seed elements a given height above seafloor, e.g. <code class="docutils literal notranslate"><span class="pre">z='seafloor+50'</span></code> to seed elements 50m above seafloor.</p>
<p>All seeded elements will get the default values of any properties as defined in the model implementation, or the properties may be specified (overridden) with a name-value pair:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">seed_elements</span><span class="p">(</span><span class="n">lon</span><span class="o">=</span><span class="mf">4.3</span><span class="p">,</span> <span class="n">lat</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="n">number</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">radius</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span>
<span class="n">density</span><span class="o">=</span><span class="mi">900</span><span class="p">,</span> <span class="n">time</span><span class="o">=</span><span class="n">reader_norkyst</span><span class="o">.</span><span class="n">start_time</span><span class="p">)</span>
</pre></div>
</div>
<p>This will give all 100 oil elements (if o is an OpenOil instance) a density of 900 kg/m3, instead of the default value of 880 kg/m3. To assign unique values to each element, the properties may be given as an array with length equal the number of elements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">numpy</span><span class="w"> </span><span class="kn">import</span> <span class="n">random</span>
<span class="n">o</span><span class="o">.</span><span class="n">seed_elements</span><span class="p">(</span><span class="n">lon</span><span class="o">=</span><span class="mf">4.3</span><span class="p">,</span> <span class="n">lat</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="n">number</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">radius</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span>
<span class="n">density</span><span class="o">=</span><span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="mi">880</span><span class="p">,</span> <span class="mi">920</span><span class="p">,</span> <span class="mi">100</span><span class="p">),</span>
<span class="n">time</span><span class="o">=</span><span class="n">reader_norkyst</span><span class="o">.</span><span class="n">start_time</span><span class="p">)</span>
</pre></div>
</div>
<p>The properties of the seeded elements may be displayed with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">elements_scheduled</span>
</pre></div>
</div>
<p>Elements may be seeded along a line (or cone) between two points by using the method <code class="docutils literal notranslate"><span class="pre">seed_cone</span></code>. Lon and lat must then be two element arrays, indicating start and end points. An uncertainty radius may also be given as a two element array, thus tracing out a cone (where a line is a special case with same radius at both ends):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">seed_cone</span><span class="p">(</span><span class="n">lon</span><span class="o">=</span><span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mf">4.8</span><span class="p">],</span> <span class="n">lat</span><span class="o">=</span><span class="p">[</span><span class="mi">60</span><span class="p">,</span> <span class="mi">61</span><span class="p">],</span> <span class="n">number</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span> <span class="n">radius</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">5000</span><span class="p">],</span>
<span class="n">time</span><span class="o">=</span><span class="n">reader_norkyst</span><span class="o">.</span><span class="n">start_time</span><span class="p">)</span>
</pre></div>
</div>
<p>If time is also given as a two element list (of datetime objects), elements are seeded linearly in time (here over a 5 hour interval):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">seed_cone</span><span class="p">(</span><span class="n">lon</span><span class="o">=</span><span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mf">4.8</span><span class="p">],</span> <span class="n">lat</span><span class="o">=</span><span class="p">[</span><span class="mi">60</span><span class="p">,</span> <span class="mi">61</span><span class="p">],</span> <span class="n">number</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span> <span class="n">radius</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">5000</span><span class="p">],</span>
<span class="n">time</span><span class="o">=</span><span class="p">[</span><span class="n">norkyst</span><span class="o">.</span><span class="n">start_time</span><span class="p">,</span> <span class="n">norkyst</span><span class="o">.</span><span class="n">start_time</span><span class="o">+</span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">5</span><span class="p">)])</span>
</pre></div>
</div>
<p>Specific OpenDrift models may have additional seed-functions. E.g. <a class="reference internal" href="autoapi/opendrift/models/openoil/index.html#module-opendrift.models.openoil" title="opendrift.models.openoil"><code class="xref py py-mod docutils literal notranslate"><span class="pre">opendrift.models.openoil</span></code></a> contains a function (seed_from_gml) to seed oil elements within contours from satellite detected oil slicks read from a GML-file. The Leeway model overloads the generic seed_elements function since it needs to read some object properties from a text-file.</p>
<p>The seed functions may also be called repeatedly before starting the simulation, try <a class="reference internal" href="gallery/example_grid_time.html"><span class="doc">Grid time</span></a> for an example of this.</p>
<p>Run the script <a class="reference internal" href="gallery/example_seed_demonstration.html"><span class="doc">Seed demonstration</span></a> for a demonstration of various ways to seed elements.</p>
</section>
<section id="configuration">
<h2>4. Configuration<a class="headerlink" href="#configuration" title="Link to this heading"></a></h2>
<p>OpenDrift allows for configuration of the model using the package <a class="reference external" href="https://www.voidspace.org.uk/python/configobj.html">ConfigObj</a>. The properties which can be configured can be listed by the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">list_configspec</span><span class="p">()</span>
</pre></div>
</div>
<p>Parameters may be set with commands like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">set_config</span><span class="p">(</span><span class="s1">'drift:advection_scheme'</span><span class="p">,</span> <span class="s1">'runge-kutta'</span><span class="p">)</span>
</pre></div>
</div>
<p>This example specifies that the Runge-Kutta propagation scheme shall be used for the run, instead of the default Euler-scheme.</p>
<p>The following command specifies that the elements at the ocean surface shall drift with 2 % of the wind speed (in addition to the current):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">set_config</span><span class="p">(</span><span class="s1">'seed:wind_drift_factor'</span><span class="p">,</span> <span class="mf">.02</span><span class="p">)</span>
</pre></div>
</div>
<p>The configuration value is retrieved by:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">wind_drift_factor</span> <span class="o">=</span> <span class="n">o</span><span class="o">.</span><span class="n">get_config</span><span class="p">(</span><span class="s1">'seed:wind_drift_factor'</span><span class="p">)</span>
</pre></div>
</div>
<p>See the example-files for more examples of configuration.</p>
</section>
<section id="running-the-model">
<h2>5. Running the model<a class="headerlink" href="#running-the-model" title="Link to this heading"></a></h2>
<p>After initialisation, adding readers and seeding elements, a model run (simulation) can be started by calling the function run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>The simulation will start at the time of the first seeded element, and continue until the end of any of the added readers. The default time step is one hour (3600 seconds). The calculation time step may be specified with the parameter <strong>time_step</strong>, in seconds, or as a datetime.timedelta object:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">time_step</span><span class="o">=</span><span class="mi">900</span><span class="p">)</span>
</pre></div>
</div>
<p>which is equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timedelta</span>
<span class="n">o</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">time_step</span><span class="o">=</span><span class="n">timedelta</span><span class="p">(</span><span class="n">minutes</span><span class="o">=</span><span class="mi">15</span><span class="p">))</span>
</pre></div>
</div>
<p>The duration of the simulation may be specified by providing one (and only one) of the following parameters:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">steps</span></code> [integer] The number of calculation steps</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">duration</span></code> [datetime.timedelta] The length of the simulation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">end_time</span></code> [datetime.datetime] The end time of the simulation</p></li>
</ul>
</div></blockquote>
<p>The output may be saved to a file, if specifying <code class="docutils literal notranslate"><span class="pre">outfile=<filename></span></code>.
Currently only one output format is supported: the <a class="reference external" href="https://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#_trajectory_data">NetCDF CF convention on Trajectory data</a>.
A sample output NetCDF file is available <a class="reference external" href="https://dl.dropboxusercontent.com/s/qcsyqh5eyazyo1h/openoil.nc">here</a>.
It is possible to make “writers” for other output formats, and these must be stored in the subfolder <strong>export</strong>.</p>
<p>By default, all element properties (position (lon/lat/z), density etc) and all environment variables (current, wind etc) are saved to the file, and are stored in an array <code class="docutils literal notranslate"><span class="pre">o.history</span></code> in memory for plotting and analysis. There are two ways to reduce the memory consumption and file size:</p>
<blockquote>
<div><ul class="simple">
<li><p>save only a subset of the variables/parameters by providing <code class="docutils literal notranslate"><span class="pre">export_variables</span></code> [list of strings]</p></li>
<li><p>save data only at a specified time interval by providing <code class="docutils literal notranslate"><span class="pre">time_step_output</span></code> [seconds, or timedelta]. The output time step must be larger or equal to the calculation time step, and must be an integer multiple of this.</p></li>
</ul>
</div></blockquote>
<p>The following command will run a simulation from the first seeding time until the end of the reader_norkyst reader (current data) with a calculation time step of 15 minutes, but output (saved) only every hour. The properties ‘density’ and ‘water_content’ are saved to the file ‘openoil.nc’ (in addition to the obligatory element properties ‘lon’ and ‘lat’, and the internal parameters ‘ID’ and ‘status’):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">end_time</span><span class="o">=</span><span class="n">reader_norkyst</span><span class="o">.</span><span class="n">end_time</span><span class="p">,</span> <span class="n">time_step</span><span class="o">=</span><span class="mi">900</span><span class="p">,</span>
<span class="n">time_step_output</span><span class="o">=</span><span class="mi">3600</span><span class="p">,</span> <span class="n">outfile</span><span class="o">=</span><span class="s1">'openoil.nc'</span><span class="p">,</span>
<span class="n">export_variables</span><span class="o">=</span><span class="p">[</span><span class="s1">'density'</span><span class="p">,</span> <span class="s1">'water_content'</span><span class="p">])</span>
</pre></div>
</div>
<p>The saved output may later be imported with the commands:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span> <span class="o">=</span> <span class="n">OpenOil</span><span class="p">()</span>
<span class="n">o</span><span class="o">.</span><span class="n">io_import_file</span><span class="p">(</span><span class="o"><</span><span class="n">filename</span><span class="o">></span><span class="p">)</span>
</pre></div>
</div>
<p>During a model run, the following actions are performed repeatedly at the given calculation time step:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>Readers are called successively to retrieve all required environment variables, and interpolate onto the element positions.</p></li>
<li><p>Element properties and positions are updated by the model specific function <code class="docutils literal notranslate"><span class="pre">update()</span></code></p></li>
<li><p>Elements are deactivated if any required_variables are missing (and there is no fallback_value), or by any other reason as specified in the relevant <code class="docutils literal notranslate"><span class="pre">update()</span></code> function (e.g. stranding towards coast, or “evaporated”).</p></li>
</ol>
</div></blockquote>
<p>The run continues until one of the following conditions are met:</p>
<blockquote>
<div><ul class="simple">
<li><p>All elements have been deactivated</p></li>
<li><p>The specified end time has been reached (as given by <code class="docutils literal notranslate"><span class="pre">end_time</span></code>, <code class="docutils literal notranslate"><span class="pre">duration</span></code> or <code class="docutils literal notranslate"><span class="pre">steps</span></code>)</p></li>
<li><p>Anything crashes during the simulation, for any given reason (which is displayed to the terminal)</p></li>
</ul>
</div></blockquote>
</section>
<section id="plotting-and-analysing-the-results">
<h2>6. Plotting and analysing the results<a class="headerlink" href="#plotting-and-analysing-the-results" title="Link to this heading"></a></h2>
<p>After the run (or after importing from a file), the status can be inspected:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">o</span><span class="p">)</span>
<span class="o">===========================</span>
<span class="n">Model</span><span class="p">:</span> <span class="n">OpenOil</span>
<span class="mi">83</span> <span class="n">active</span> <span class="n">Oil</span> <span class="n">particles</span> <span class="p">(</span><span class="mi">17</span> <span class="n">deactivated</span><span class="p">)</span>
<span class="n">Projection</span><span class="p">:</span> <span class="o">+</span><span class="n">proj</span><span class="o">=</span><span class="n">stere</span> <span class="o">+</span><span class="n">lat_0</span><span class="o">=</span><span class="mi">90</span> <span class="o">+</span><span class="n">lon_0</span><span class="o">=</span><span class="mi">70</span> <span class="o">+</span><span class="n">lat_ts</span><span class="o">=</span><span class="mi">60</span> <span class="o">+</span><span class="n">units</span><span class="o">=</span><span class="n">m</span> <span class="o">+</span><span class="n">a</span><span class="o">=</span><span class="mf">6.371e+06</span> <span class="o">+</span><span class="n">e</span><span class="o">=</span><span class="mi">0</span> <span class="o">+</span><span class="n">no_defs</span>
<span class="o">-------------------</span>
<span class="n">Environment</span> <span class="n">variables</span><span class="p">:</span>
<span class="o">-----</span>
<span class="n">x_sea_water_velocity</span>
<span class="n">y_sea_water_velocity</span>
<span class="mi">1</span><span class="p">)</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">thredds</span><span class="o">.</span><span class="n">met</span><span class="o">.</span><span class="n">no</span><span class="o">/</span><span class="n">thredds</span><span class="o">/</span><span class="n">dodsC</span><span class="o">/</span><span class="n">sea</span><span class="o">/</span><span class="n">norkyst800m</span><span class="o">/</span><span class="mi">1</span><span class="n">h</span><span class="o">/</span><span class="n">aggregate_be</span>
<span class="o">-----</span>
<span class="n">x_wind</span>
<span class="n">y_wind</span>
<span class="mi">1</span><span class="p">)</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">thredds</span><span class="o">.</span><span class="n">met</span><span class="o">.</span><span class="n">no</span><span class="o">/</span><span class="n">thredds</span><span class="o">/</span><span class="n">dodsC</span><span class="o">/</span><span class="n">arome25</span><span class="o">/</span><span class="n">arome_metcoop_default2_5km_latest</span><span class="o">.</span><span class="n">nc</span>
<span class="o">-----</span>
<span class="n">land_binary_mask</span>
<span class="mi">1</span><span class="p">)</span> <span class="n">global_landmask</span>
<span class="n">Time</span><span class="p">:</span>
<span class="n">Start</span><span class="p">:</span> <span class="mi">2015</span><span class="o">-</span><span class="mi">03</span><span class="o">-</span><span class="mi">04</span> <span class="mi">06</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Present</span><span class="p">:</span> <span class="mi">2015</span><span class="o">-</span><span class="mi">03</span><span class="o">-</span><span class="mi">12</span> <span class="mi">14</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Iterations</span><span class="p">:</span> <span class="mi">200</span>
<span class="n">Time</span> <span class="n">spent</span><span class="p">:</span>
<span class="n">Fetching</span> <span class="n">environment</span> <span class="n">data</span><span class="p">:</span> <span class="mi">0</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mf">15.250431</span>
<span class="n">Updating</span> <span class="n">elements</span><span class="p">:</span> <span class="mi">0</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mf">00.268629</span>
<span class="o">===========================</span>
</pre></div>
</div>
<p>A map showing the trajectories is plotted with the command <code class="docutils literal notranslate"><span class="pre">o.plot()</span></code></p>
<p>The trajectories may be colored by any of the element properties by giving the keyword linecolor to the plot function, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">linecolor</span><span class="o">=</span><span class="s1">'z'</span><span class="p">)</span>
</pre></div>
</div>
<p>which will color lines according to depth (z):</p>
<img alt="https://dl.dropboxusercontent.com/s/3bncjqcgh1s4dn1/OpenDrift_linecolorZ.png" src="https://dl.dropboxusercontent.com/s/3bncjqcgh1s4dn1/OpenDrift_linecolorZ.png" />
<p>Green stars mark initial (seeding) positions, and blue elements are still active at end of simulation.</p>
<p>A variable field from any of the readers may be used as background to the plot by providing the variable name as the keyword string <code class="docutils literal notranslate"><span class="pre">background</span></code>. Vector fields (winds, current) may also be plotted by giving the x- and y-components in a two element list:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">background</span><span class="o">=</span><span class="p">[</span><span class="s1">'x_sea_water_velocity'</span><span class="p">,</span> <span class="s1">'y_sea_water_velocity'</span><span class="p">])</span>
</pre></div>
</div>
<p>This may be useful for visualising where the model (reader) eventually may be missing data (white areas on the plot below). Note that the “holes” will be filled/interpolated during the simulation, with the default interpolation method (‘LinearNDFast’, see above).
Contourlines are plotted instead of background color if parameter ‘contourlines’ is set to True or to a list of values for the contour levels.</p>
<img alt="https://www.dropbox.com/s/91pco06cwkuhtyp/OpenDrift_background.png?raw=1" src="https://www.dropbox.com/s/91pco06cwkuhtyp/OpenDrift_background.png?raw=1" />
<p><code class="docutils literal notranslate"><span class="pre">o.animation()</span></code> will show an animation of the last run.</p>
<p>An animation comparing two runs is obtained by:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">.</span><span class="n">animation</span><span class="p">(</span><span class="n">compare</span><span class="o">=</span><span class="n">o2</span><span class="p">,</span> <span class="n">legend</span><span class="o">=</span><span class="p">[</span><span class="s1">'Current + 3 % wind drift'</span><span class="p">,</span> <span class="s1">'Current only'</span><span class="p">])</span>
</pre></div>
</div>
<p>where o2 is another simulation object (or filename of saved simulation). The legend items correspond to the first (o) and second (o2) simulations. The two runs must have identical time steps and start time.</p>
<p>The animation may be saved to file if providing the keyword <code class="docutils literal notranslate"><span class="pre">filename</span></code>. Supported output is animated GIF (if file suffix is .gif, and if imagemagick is available) or otherwise mp4 (file suffix .mp4). For mp4 you might need to install <a class="reference external" href="https://ffmpeg.org/download.html">ffmpeg</a> or <a class="reference external" href="https://www.mplayerhq.hu/design7/dload.html">mencoder</a> if not already available on your system.
The quality of mp4-files is quite low with older versions of Matplotlib, as bitrate may not be set manually. With newer versions of Matplotlib, the animate function might however need some updates to work properly (please <a class="reference external" href="https://github.com/opendrift/opendrift/issues">report</a> any errors).
When exporting animation to mp4, an additional parameter <code class="docutils literal notranslate"><span class="pre">fps</span></code> may be provided to specify the number of frames per seconds (speed of animation), default is 20 frames/second.</p>
<p>Specific models may define specific plotting functions. One example is <code class="docutils literal notranslate"><span class="pre">OpenOil.plot_oil_budget()</span></code> which plots the oil mass budget of a simulation.
The examples <a class="reference internal" href="gallery/example_codegg.html"><span class="doc">Cod egg</span></a> and <a class="reference internal" href="gallery/example_oil_verticalmixing.html"><span class="doc">Oil vertical mixing</span></a> demonstrate the function plot_vertical_distribution() to show a histogram of the element depths, with an interactive time slider.</p>
<p>See the <a class="reference internal" href="gallery/index.html"><span class="doc">gallery</span></a> for some examples of output figures and animations.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="performance.html" class="btn btn-neutral float-left" title="Performance in OpenDrift" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="theory/index.html" class="btn btn-neutral float-right" title="Theory" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2020, Knut-Frode Dagestad ([email protected]) and Gaute Hope ([email protected])..</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>