Debian Codegraph @

docs/manual/chapters/tutorial.xml

raw
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 (C) Copyright 1996-2016 ECMWF.
4
5 This software is licensed under the terms of the Apache Licence Version 2.0
6 which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
7 In applying this licence, ECMWF does not waive the privileges and immunities
8 granted to it by virtue of its status as an intergovernmental organisation nor
9 does it submit to any jurisdiction.
10 -->
11
12 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
13 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
14
15 <!-- Note: This file has been edited with indentations of 2 spaces.
16 It would be best if this was continued and no tabs were used! -->
17
18 <appendix id="MAGICS_Tutorial" label="A">
19 <title>MAGICS Tutorial</title>
20
21 <xi:include href="../phrases/appendixinfo_mod.xml"
22 xmlns:xi="http://www.w3.org/2001/XInclude" />
23
24 <section id="Tutorial_Introduction">
25 <title>Introduction</title>
26
27 <para>During the training course, we will present the functionalities of Magics.
28 Most of the time we will use the fortran interface and
29 <productname>MAGICS</productname> User Version, 6.11. We will also use
30 <productname>MAGICS++</productname> User Version, 2.6
31 to present the main differences between the two versions and
32 discover the new functionalities of <productname>MAGICS++</productname>.
33 In addtion, we will present how to use the new XML-Base interface called <productname>MagML</productname>.
34 </para>
35
36
37
38 <section id="Tutorial_Creating_a_Basic_Program">
39 <title>Creating a Basic MAGICS Program</title>
40
41 <para>First, create a new Fortran source file using your favourite
42 text editor, for example <application>vi</application> or
43 <application>NEdit</application>.
44 </para>
45
46 <para>Here is the code of your first basic <productname>MAGICS</productname> program:
47 <filename>basic.f</filename>
48 <programlisting>
49 <xi:include href="../examples/tutorial/fortran/source/basic.f_cc" parse="xml"
50 xmlns:xi="http://www.w3.org/2001/XInclude" />
51 </programlisting>
52 </para>
53
54 <section id="Tutorial_Compiling_Magics++">
55 <title>Compiling using <productname>MAGICS++</productname></title>
56 <para> Type on an xterm window </para>
57 <programlisting>
58 use newmagics++
59 pgf90 -o basic basic.f $MAGPLUSLIB_SHARED
60 </programlisting>
61 </section>
62
63 <section id="Tutorial_Compiling_Magics">
64 <title>Compiling using <productname>MAGICS</productname></title>
65 <para> Type on an xterm window </para>
66 <programlisting>
67 use magics
68 pgf90 -o basic basic.f $MAGLIB $EMOSLIB
69 </programlisting>
70 </section>
71
72 <section id="executing_and_visualising">
73 <title>Executing and visualising the result</title>
74 <para>Type on an xterm window</para>
75 <programlisting>
76 basic --> run the program
77 gv basic.ps --> Visualise the postscript
78 </programlisting>
79 </section>
80 <section id="bug_report">
81 <title>Sending us a bug report</title>
82 <para> Magics++ is still under development, it will help us a lot if you could send us any program
83 that are not behaving the way you think they should. You can send the Fortran program in question
84 to [email protected] by typing:</para>
85 <programlisting>
86 mail magicsplus -s "magics course 2009" &lt; your-fortran-file.f
87 </programlisting>
88 </section>
89
90 </section>
91
92 <section id="Tutorial_Basic_Comment">
93 <title>Spot the differences!</title>
94 <para>If you compare the two plots you can immediately see some differences.</para>
95 <figure id="figure_output_from_basic_f_magics">
96 <title>Output from basic.f using <productname>MAGICS</productname></title>
97 <mediaobject id="output_from_basic_f_magics">
98 <imageobject role="fo">
99 <imagedata fileref="../examples/tutorial/fortran/png/basic_m69_CYLINDRICAL_01.png" format="PNG"
100 width="14cm" align="center"/>
101 </imageobject>
102
103 <imageobject role="html">
104 <imagedata fileref="images/fortran/basic_m69_CYLINDRICAL_01_thumb.png" format="PNG" align="center"/>
105 </imageobject>
106 </mediaobject>
107 </figure>
108 <figure id="figure_output_from_basic_f_magics++">
109 <title>Output from basic.f using <productname>MAGICS++</productname></title>
110 <mediaobject id="output_from_basic_f_magics++">
111 <imageobject role="fo">
112 <imagedata fileref="../examples/tutorial/fortran/png/basic_01.png" format="PNG"
113 width="14cm" align="center"/>
114 </imageobject>
115
116 <imageobject role="html">
117 <imagedata fileref="images/fortran/basic_01_thumb.png" format="PNG"
118 align="center"/>
119 </imageobject>
120 </mediaobject>
121 </figure>
122
123 <important> <title>MAGICS++</title>
124 <productname>MAGICS++</productname> has black coastlines and grid by default</important>
125
126 <para>Can you change your program in order to get a black coastlines and grid even when using <productname>MAGICS</productname> ? </para>
127
128 <para>Try to add the following instructions</para>
129
130 <programlisting>
131 call <function>psetc</function> ('<parameter>map_grid_colour</parameter>', 'black')
132 call <function>psetc</function> ('<parameter>map_coastline_colour</parameter>', 'black')
133 </programlisting>
134
135 <para> compile, execute and visualise again ...</para>
136 </section><!-- end of Tutorial_Basic_Comment -->
137 </section> <!-- Tutorial_Introduction -->
138
139 <section id="Tutorial_coastlines">
140 <title> Projection and coastlines </title>
141 <para> In this first tutorial, we will learn how to set a geographical area
142 and a projection. We will also discover the plotting attributes for coastlines </para>
143
144 <para>You will have to use the following Magics routines</para>
145
146 <itemizedlist>
147 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETR </olink> </function> to set the <productname>MAGICS</productname>
148 parameters which expect <emphasis>real</emphasis> parameters</para></listitem>
149 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETC </olink> </function> to set the <productname>MAGICS</productname>
150 parameters which expect <emphasis>character</emphasis> parameters</para></listitem>
151 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETI </olink></function> to set the <productname>MAGICS</productname>
152 parameters which expect <emphasis>integer</emphasis> parameters</para></listitem>
153 </itemizedlist>
154
155 <para>You will also use the following Action or Pseudo-Action routines</para>
156
157 <itemizedlist>
158 <listitem><para><function>PCOAST</function> to draw the coastlines.</para></listitem>
159 <listitem><para><function>PNEW</function> to change page.</para></listitem>
160 <listitem><para><function>PTEXT</function> to add some titles.</para></listitem>
161 </itemizedlist>
162 </section>
163 <section id='coastlines_map_1'>
164 <title> Europe in cylindrical projection </title>
165 <para> In the example we are going to plot a european map on cylindrical projection </para>
166 <figure id="figure_coastlines_map_1">
167 <title>The result</title>
168 <mediaobject id="output_coastlines_map_1">
169 <imageobject role="fo">
170 <imagedata fileref="../examples/tutorial/fortran/png/coast_1_01.png" format="PNG"
171 align="center"/>
172 </imageobject>
173
174 <imageobject role="html">
175 <imagedata fileref="images/fortran/coast_1_01_thumb.png" format="PNG"
176 align="center"/>
177 </imageobject>
178 </mediaobject>
179 </figure>
180
181 <section id='coastlines_map_1_requirements'>
182 <title> Requirements </title>
183 <para> Here are our requirements </para>
184 <itemizedlist>
185 <listitem><para> <olink targetdoc="Magics_tutorial" targetptr="coastlines_map_1_clues_1">Geographical Area </olink>: <emphasis>15W/30N/40E/70N </emphasis></para></listitem>
186 <listitem><para> <olink targetdoc="Magics_tutorial" targetptr="coastlines_map_1_clues_2">Grid setting </olink>:
187 <emphasis>Coastlines:colour=tan, Grid: colour=tan, line-style=dot </emphasis></para></listitem>
188 </itemizedlist>
189 </section>
190
191
192 <?pagebreak?>
193
194 <section id='coastlines_map_1_clues'>
195 <title>Clues</title>
196 <section id='coastlines_map_1_clues_1'>
197 <title>Setting the geographical area</title>
198 <table id="table_coastlines_map_1_clues_1_params">
199 <title>Parameters for setting the geographical area</title>
200 <tgroup cols="2">
201 <colspec colwidth="190" />
202 <colspec colwidth="60" />
203
204 <thead>
205 <row>
206 <entry> Parameters </entry>
207 <entry> Functions </entry>
208 </row>
209 </thead>
210 <tbody>
211 <row>
212 <entry><parameter>subpage_lower_left_latitude</parameter></entry>
213 <entry><function>psetr</function></entry>
214 </row>
215 <row>
216 <entry><parameter>subpage_lower_left_longitude</parameter></entry>
217 <entry><function>psetr</function></entry>
218 </row>
219 <row>
220 <entry><parameter>subpage_upper_right_latitude</parameter></entry>
221 <entry><function>psetr</function></entry>
222 </row>
223 <row>
224 <entry><parameter>subpage_upper_right_longitude</parameter></entry>
225 <entry><function>psetr</function></entry>
226 </row>
227 </tbody>
228 </tgroup>
229 </table>
230 <table id="table_coastlines_map_1_clues_1_actions">
231 <title>Action routine for setting the geographical area</title>
232 <tgroup cols="1">
233 <colspec colwidth="150" />
234 <thead>
235 <row>
236 <entry> Action routines </entry>
237 </row>
238 </thead>
239 <tbody>
240 <row>
241 <entry><function>pcoast</function></entry>
242 </row>
243 </tbody>
244 </tgroup>
245 </table>
246
247 <para> More information in <olink targetdoc="Magics_layout_mapping_coastlines" targetptr="Subpage_Mapping" />. </para>
248 </section>
249
250 <section id='coastlines_map_1_clues_2'>
251 <title>Setting of the visual Attributes</title>
252 <table id="table_coastlines_map_1_clues_2_params">
253 <title>Parameters for setting the coastline attributes</title>
254 <tgroup cols="2">
255 <colspec colwidth="190"/>
256 <colspec colwidth="60"/>
257 <thead>
258 <row>
259 <entry> Parameters </entry>
260 <entry> Functions </entry>
261 </row>
262 </thead>
263 <tbody>
264 <row>
265 <entry><parameter>map_coastline_colour</parameter></entry>
266 <entry><function>psetc</function></entry>
267 </row>
268
269 <row>
270 <entry><parameter>map_grid_colour</parameter></entry>
271 <entry><function>psetc</function></entry>
272 </row>
273 <row>
274 <entry><parameter>map_grid_line_style</parameter></entry>
275 <entry><function>psetc</function></entry>
276 </row>
277 </tbody>
278 </tgroup>
279 </table>
280
281 <table id="table_coastlines_map_1_clues_2_actions">
282 <title>Action routine for setting the coastline attributes</title>
283 <tgroup cols="1">
284 <colspec colwidth="150"/>
285 <thead>
286 <row>
287 <entry> Action routines </entry>
288 </row>
289 </thead>
290 <tbody>
291 <row>
292 <entry><function>pcoast</function></entry>
293 </row>
294 </tbody>
295 </tgroup>
296 </table>
297
298 <para> More information on <olink targetdoc="Magics_layout_mapping_coastlines" targetptr="pcoast_tables" >the coastlines parameters</olink> </para>
299
300 </section>
301 </section> <!-- coastlines_map_1_clues -->
302
303
304 <section id='coastlines_map_1_solution'>
305 <title>Solution</title>
306 <para> Here is the complete solution
307 <filename>coast_01.f</filename></para>
308 <programlisting>
309 <xi:include href="../examples/tutorial/fortran/source/coast_1.f_cc" parse="xml"
310 xmlns:xi="http://www.w3.org/2001/XInclude" />
311 </programlisting>
312 </section>
313
314
315
316 <section id='coastlines_map_1_diff'>
317 <title> Spot the differences... </title>
318 <para> Output for <productname>Magics++</productname> </para>
319 <mediaobject id="output_mpp_coastlines_map_1">
320
321 <imageobject role="fo">
322 <imagedata fileref="../examples/tutorial/fortran/png/coast_1_01.png" format="PNG"
323 align="center"/>
324 </imageobject>
325
326 <imageobject role="html">
327 <imagedata fileref="images/fortran/coast_1_01_thumb.png" format="PNG"
328 align="center"/>
329 </imageobject>
330 </mediaobject>
331 <para> Output for <productname>Magics 6.11</productname> </para>
332 <mediaobject id="output_m69_coastlines_map_1">
333
334 <imageobject role="fo">
335 <imagedata fileref="../examples/tutorial/fortran/png/coast_1_m69_CYLINDRICAL_01.png" format="PNG"
336 align="center"/>
337 </imageobject>
338
339 <imageobject role="html">
340 <imagedata fileref="images/fortran/coast_1_m69_CYLINDRICAL_01_thumb.png" format="PNG"
341 align="center"/>
342 </imageobject>
343 </mediaobject>
344 </section >
345
346
347
348 <section id='coastlines_map_1_magml'>
349 <title> Using MagML </title>
350 <para> To get the same result, you can create the following <productname>magml</productname> description </para>
351 <para><filename>coast_1.magml</filename></para>
352 <programlisting>
353 <xi:include href="../examples/tutorial/magml/source/coast_1.magml_cc" parse="xml"
354 xmlns:xi="http://www.w3.org/2001/XInclude" />
355 </programlisting>
356 <mediaobject id="output_magml_coastlines_map_1">
357 <imageobject role="fo">
358 <imagedata fileref="../examples/tutorial/magml/png/coast_1.png" format="PNG"
359 align="center"/>
360 </imageobject>
361
362 <imageobject role="html">
363 <imagedata fileref="images/magml/coast_1_thumb.png" format="PNG"
364 align="center"/>
365 </imageobject>
366 </mediaobject>
367
368 </section >
369
370 </section >
371
372 <xi:include href="../exercises/coast_2.xml"
373 xmlns:xi="http://www.w3.org/2001/XInclude" />
374
375 <xi:include href="../exercises/coast_3.xml"
376 xmlns:xi="http://www.w3.org/2001/XInclude" />
377 <section id="Tutorial_Contouring">
378 <title> Contouring </title>
379 <para> In this second tutorial, we will learn how to load a grib file and how to contour it.
380 We will also discover the various attributes of the contour action routines. </para>
381
382 Download the data <ulink url="http://www.ecmwf.int/publications/manuals/magics/magplus/data/z500_tc.grib">
383 z500_tc.grib
384 </ulink> from http://www.ecmwf.int/publications/manuals/magics/magplus/data
385
386
387 <para>You will have use the following Action routines</para>
388
389 <itemizedlist>
390 <listitem><para><function>PCOAST</function> to draw the coastlines.</para></listitem>
391 <listitem><para><function>PCONT</function> to add some isolines.</para></listitem>
392 <listitem><para><function>PTEXT</function> to add some titles.</para></listitem>
393 </itemizedlist>
394
395 <para>You will also have to use the following Magics routines</para>
396
397 <itemizedlist>
398 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETR </olink> </function> to set the <productname>MAGICS</productname>
399 parameters which expect <emphasis>real</emphasis> parameters</para></listitem>
400 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETC </olink> </function> to set the <productname>MAGICS</productname>
401 parameters which expect <emphasis>character</emphasis> parameters</para></listitem>
402 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETI </olink></function> to set the <productname>MAGICS</productname>
403 parameters which expect <emphasis>integer</emphasis> parameters</para></listitem>
404 </itemizedlist>
405
406 </section>
407
408 <xi:include href="../exercises/contour_1.xml"
409 xmlns:xi="http://www.w3.org/2001/XInclude" />
410
411 <xi:include href="../exercises/contour_2.xml"
412 xmlns:xi="http://www.w3.org/2001/XInclude" />
413
414 <xi:include href="../exercises/contour_3.xml"
415 xmlns:xi="http://www.w3.org/2001/XInclude" />
416
417 <xi:include href="../exercises/contour_4.xml"
418 xmlns:xi="http://www.w3.org/2001/XInclude" />
419
420
421 <section id="Tutorial_wind_plotting">
422 <title> Wind plotting </title>
423 <para> In this section , we will learn how to load the components of the wind from a grib file and how to contour it.
424 We will also discover the various attributes of the wind action routine. </para>
425
426 Download the data <ulink url="http://www.ecmwf.int/publications/manuals/magics/magplus/data/uv500_tc.grib">
427 uv500_tc.grib
428 </ulink> from http://www.ecmwf.int/publications/manuals/magics/magplus/data
429
430
431
432 <para>You will have use the following Action routines</para>
433
434 <itemizedlist>
435 <listitem><para><function>PCOAST</function> to draw the coastlines.</para></listitem>
436 <listitem><para><function>PWIND</function> to draw the wind.</para></listitem>
437 <listitem><para><function>PCONT</function> to add some contours.</para></listitem>
438 </itemizedlist>
439
440 <para>You will also have to use the following Magics routines</para>
441
442 <itemizedlist>
443 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETR </olink> </function> to set the <productname>MAGICS</productname>
444 parameters which expect <emphasis>real</emphasis> parameters</para></listitem>
445 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETC </olink> </function> to set the <productname>MAGICS</productname>
446 parameters which expect <emphasis>character</emphasis> parameters</para></listitem>
447 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETI </olink></function> to set the <productname>MAGICS</productname>
448 parameters which expect <emphasis>integer</emphasis> parameters</para></listitem>
449 </itemizedlist>
450 </section>
451 <xi:include href="../exercises/wind_1.xml"
452 xmlns:xi="http://www.w3.org/2001/XInclude" />
453 <xi:include href="../exercises/wind_2.xml"
454 xmlns:xi="http://www.w3.org/2001/XInclude" />
455 <xi:include href="../exercises/wind_3.xml"
456 xmlns:xi="http://www.w3.org/2001/XInclude" />
457 <xi:include href="../exercises/wind_4.xml"
458 xmlns:xi="http://www.w3.org/2001/XInclude" />
459 <section id="Tutorial_obs_plotting">
460 <title> Observation plotting </title>
461 <para>In this section, we will learn how to filter observations from a bufr file and how to plot them.
462 We will also discover the various attributes of the obs action routine.</para>
463
464 <para>Please be aware that, because observation plotting is still in the devlopment stage, these examples
465 are all run only with MAGICS 6.11.</para>
466
467 <para>Download the data <ulink url="http://www.ecmwf.int/publications/manuals/magics/magplus/data/obs_tc.bfr">obs_tc.bfr</ulink>from http://www.ecmwf.int/publications/manuals/magics/magplus/data
468 </para>
469
470
471 <para>You will have use the following Action routines</para>
472
473 <itemizedlist>
474 <listitem><para><function>PCOAST</function> to draw the coastlines.</para></listitem>
475 <listitem><para><function>POBS</function> to plot the observations</para></listitem>
476 </itemizedlist>
477
478 <para>You will also to use the following Magics routines</para>
479
480 <itemizedlist>
481 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETR </olink> </function> to set the <productname>MAGICS</productname>
482 parameters which expect <emphasis>real</emphasis> parameters</para></listitem>
483 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETC </olink> </function> to set the <productname>MAGICS</productname>
484 parameters which expect <emphasis>character</emphasis> parameters</para></listitem>
485 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETI </olink></function> to set the <productname>MAGICS</productname>
486 parameters which expect <emphasis>integer</emphasis> parameters</para></listitem>
487 </itemizedlist>
488 </section>
489 <xi:include href="../exercises/obs_1.xml"
490 xmlns:xi="http://www.w3.org/2001/XInclude" />
491 <xi:include href="../exercises/obs_2.xml"
492 xmlns:xi="http://www.w3.org/2001/XInclude" />
493 <xi:include href="../exercises/obs_3.xml"
494 xmlns:xi="http://www.w3.org/2001/XInclude" />
495
496 <section id="Tutorial_graph_plotting">
497 <title> Graph plotting </title>
498 <para> In this section , we will lear how to use the <function>pgraph</function> action routine.
499 We will discover the various attributes of the graph plotting </para>
500
501 <para>You will have use the following Action routines</para>
502
503 <itemizedlist>
504 <listitem><para><function>PAXIS</function> to draw the axis and define the coordinates system.</para></listitem>
505 <listitem><para><function>PGRAPH</function> to plot the curves.</para></listitem>
506 </itemizedlist>
507
508 <para>You will also to use the following Magics routines</para>
509
510 <itemizedlist>
511 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Array_Parameter_Setting" > PSET1R </olink> </function> to set the <productname>MAGICS</productname>
512 parameters which expect an array of <emphasis>real</emphasis> parameters</para></listitem>
513 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETR </olink> </function> to set the <productname>MAGICS</productname>
514 parameters which expect <emphasis>real</emphasis> parameters</para></listitem>
515 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETC </olink> </function> to set the <productname>MAGICS</productname>
516 parameters which expect <emphasis>character</emphasis> parameters</para></listitem>
517 <listitem><para><function><olink targetdoc="Magics_using" targetptr="Single_Parameter_Setting" > PSETI </olink></function> to set the <productname>MAGICS</productname>
518 parameters which expect <emphasis>integer</emphasis> parameters</para></listitem>
519 </itemizedlist>
520 </section>
521 <xi:include href="../exercises/graph_1.xml"
522 xmlns:xi="http://www.w3.org/2001/XInclude" />
523 <xi:include href="../exercises/graph_2.xml"
524 xmlns:xi="http://www.w3.org/2001/XInclude" />
525
526
527 </appendix>