source: trunk/SRC/Documentation/xmldoc/firststeps.xml @ 259

Last change on this file since 259 was 193, checked in by pinsard, 18 years ago

add ENTITY hellip in xml files using it, necessary because I don't know yet how to handle entity with xmllint (1/2).
  • Property svn:keywords set to Id
File size: 34.3 KB
Line 
1<?xml version='1.0' encoding='iso-8859-1'?>
2<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4[
5<!ENTITY hellip "&#x2026;">
6<!ENTITY promptidl "idl&gt;">
7<!ENTITY numb1 '<inlinemediaobject><imageobject><imagedata fileref="images/callouts/1.png" format="PNG"/></imageobject><textobject><phrase>1</phrase></textobject></inlinemediaobject>'>
8<!ENTITY numb2 '<inlinemediaobject><imageobject><imagedata fileref="images/callouts/2.png" format="PNG"/></imageobject><textobject><phrase>2</phrase></textobject></inlinemediaobject>'>
9<!ENTITY showfig '<inlinemediaobject><imageobject><imagedata fileref="images/showfig.png" format="PNG"/></imageobject><textobject><phrase>show result</phrase></textobject></inlinemediaobject>'>
10]>
11
12<!--
13instructions to create html file
14xsltproc ?-?-param  section.autolabel 1 -output firststep.html /sw/share/xml/xsl/docbook-xsl/xhtml/docbook.xsl firststep.xml
15xsltproc -output firststep.html /sw/share/xml/xsl/docbook-xsl/xhtml/docbook.xsl firststep.xml
16xsltproc  /sw/share/xml/xsl/docbook-xsl/xhtml/chunk.xsl  firststep.xml
17xsltproc ?-?-param  section.autolabel 1 /sw/share/xml/xsl/docbook-xsl/xhtml/chunk.xsl firststep.xml
18
19wget http://www.lodyc.jussieu.fr/~smasson/japon.html
20curl -O  http://www.lodyc.jussieu.fr/~smasson/japon.html
21-->
22
23<!--
24module :
25first steps with SAXO ...
26
27source :
28./SRC/Documentation/xmldoc/firststeps.xml
29
30-->
31<article lang="en">
32  <title>
33    First steps with <application>SAXO</application>
34  </title>
35 
36  <articleinfo>
37    <authorgroup>
38      <author><firstname>Sébastien</firstname> <surname>Masson</surname> <email>Sebastien.Masson_at_locean-ipsl.upmc.fr</email></author>
39      <author><firstname>Françoise</firstname> <surname>Pinsard</surname> <email>Francoise.Pinsard_at_locean-ipsl.upmc.fr</email></author>
40    </authorgroup>
41    <keywordset>
42      <keyword>IDL</keyword>
43      <keyword>SAXO</keyword>
44    </keywordset>
45    <revhistory>
46      <revision>
47        <revnumber>0.0</revnumber>
48        <date>29 July 2005</date>
49        <revremark>First draft</revremark>
50      </revision>
51      <revision>
52        <revnumber>0.1</revnumber>
53        <date>29 August 2005</date>
54        <revremark>last Japanese version!</revremark>
55      </revision>
56      <revision>
57        <revnumber>0.2</revnumber>
58        <date>May 2006</date>
59        <revremark>split with getsaxo</revremark>
60      </revision>
61     </revhistory> 
62     <pubdate>$Id$</pubdate>
63  </articleinfo>
64 
65
66 
67<sect1 id="beforefirststeps">
68<title>Before this</title>
69<para>
70In this document, we supposed that you followed <ulink url="./getsaxo.html">Get SAXO</ulink> recommendations.
71</para>
72</sect1>
73
74  <sect1 id="first_plots">
75    <title>
76      First plots &hellip;
77    </title>
78    <sect2 id="start_with_init">
79      <title>
80        Start IDL session: <userinput><command>@init</command></userinput>
81      </title>
82      <para>
83        Each IDL session using <application>SAXO</application> must always start with: <prompt>&promptidl;</prompt> <userinput><command>@init</command></userinput>.     
84      </para>
85      <para>
86        <emphasis>The @ is equivalent to an include. It is used to execute a set of IDL commands that will be directly executed without any compilation (as it is the case for a procedure or a function). All variables defined and used in the @&hellip; file will still be accessible after the execution of the @&hellip; is finished (which is not the case for procedures and functions that ends with the return instruction).</emphasis>
87        <screen format="linespecific">
88  <prompt>$</prompt> <userinput><command>cd</command> <filename class="directory"><envar>${HOME}</envar>/My_IDL/</filename></userinput>
89  <prompt>$</prompt> <userinput><command>idl</command></userinput>
90  <computeroutput>IDL Version 6.0, Mac OS X (darwin ppc m32). (c) 2003, Research Systems, Inc.</computeroutput>
91  <computeroutput>Installation number: 35411.</computeroutput>
92  <computeroutput>Licensed for personal use by Jean-Philippe BOULANGER only.</computeroutput>
93  <computeroutput>All other use is strictly prohibited.</computeroutput>
94  <prompt>&promptidl;</prompt> <userinput><command>@init</command></userinput>
95  <computeroutput>% Compiled module: KEEP_COMPATIBILITY.</computeroutput>
96  <computeroutput>% Compiled module: FIND.</computeroutput>
97  <computeroutput>% Compiled module: PATH_SEP.</computeroutput>
98  <computeroutput>% Compiled module: STRSPLIT.</computeroutput>
99  <computeroutput>% Compiled module: DEF_MYUNIQUETMPDIR.</computeroutput>
100  <computeroutput>We forget the compatibility with the old version</computeroutput>
101  <computeroutput>% Compiled module: DEMOMODE_COMPATIBILITY.</computeroutput>
102  <computeroutput>% Compiled module: ISADIRECTORY.</computeroutput>
103  <computeroutput>% Compiled module: LCT.</computeroutput>
104  <computeroutput>% Compiled module: RSTRPOS.</computeroutput>
105  <computeroutput>% Compiled module: REVERSE.</computeroutput>
106  <computeroutput>% Compiled module: STR_SEP.</computeroutput>
107  <computeroutput>% Compiled module: LOADCT.</computeroutput>
108  <prompt>&promptidl;</prompt>
109        </screen>
110        As an IDL session using <application>SAXO</application> must always start with <prompt>&promptidl;</prompt> <userinput><command>@init</command></userinput>, it could be convenient to define the environment variable <envar>IDL_STARTUP</envar> to <filename><envar>${HOME}</envar>/My_IDL/init.pro</filename>. In that way, <filename>init.pro</filename> will automatically been executed when starting IDL. This can be done with the following command:
111      <variablelist>
112        <varlistentry><term><command>csh</command></term>
113        <listitem><screen><prompt>$</prompt> <userinput><command>setenv</command> <envar>IDL_STARTUP</envar> <filename><envar>${HOME}</envar>/My_IDL/init.pro</filename></userinput></screen></listitem>
114        </varlistentry>
115        <varlistentry><term><command>ksh</command></term>
116        <listitem><screen><prompt>$</prompt> <userinput><command>export</command> <envar>IDL_STARTUP</envar>=<filename><envar>${HOME}</envar>/My_IDL/init.pro</filename></userinput></screen></listitem>
117        </varlistentry>
118      </variablelist>
119      </para>
120 
121     
122    </sect2>
123    <sect2 id="basic_plots">
124      <title>
125        basic plots &hellip;
126      </title>
127      <sect3 id="basic_splot">
128      <title>
129        splot
130      </title>
131
132      <para>
133        <screenco>
134          <areaspec>
135            <area id="findgen" coords='2'/>
136          </areaspec>
137        <screen format="linespecific">
138   <prompt>&promptidl;</prompt> <userinput><command>n = 10</command></userinput>
139   <prompt>&promptidl;</prompt> <userinput><command>y = findgen(n)</command></userinput> &numb1;
140   <prompt>&promptidl;</prompt> <userinput><command>plot, y</command></userinput> <ulink url="./figpng/basic_plot.png">&showfig;</ulink>
141        </screen>
142          <calloutlist>
143            <callout arearefs="findgen">
144              <para>
145                <command>findgen</command> stands for
146<emphasis role="bold">f</emphasis>loat <emphasis role="bold">ind</emphasis>ex <emphasis role="bold">gen</emphasis>erator.
147                <screen format="linespecific">
148  <prompt>&promptidl;</prompt> <userinput><command>print, findgen(6)</command></userinput>
149  <computeroutput>      0.00000      1.00000      2.00000      3.00000      4.00000      5.00000</computeroutput>
150                </screen>
151              </para> 
152            </callout>
153          </calloutlist>
154        </screenco>
155     </para>
156     
157      <para>
158        Using IDL <command>plot</command> command is quite inconvenient to save the figure as a postscript. In addition, positioning the figure on the window/page by using <varname>!p.position</varname>, <varname>!p.region</varname> and <varname>!p.multi</varname> is often a nightmare. That's why we developed <command>splot</command> (like super-plot) which can be used in the same way as plot but is much more convenient to make postscript and position the figure.
159        <screen format="linespecific">
160  <prompt>&promptidl;</prompt> <userinput><command>splot, y</command></userinput> <ulink url="./figpng/basic_splot1.png">&showfig;</ulink>
161  <computeroutput>% Compiled module: SPLOT.</computeroutput>
162  <computeroutput>% Compiled module: REINITPLT.</computeroutput>
163  <computeroutput>% Compiled module: PLACEDESSIN.</computeroutput>
164  <computeroutput>% Compiled module: CALIBRE.</computeroutput>
165  <computeroutput>% Compiled module: GIVEWINDOWSIZE.</computeroutput>
166  <computeroutput>% Compiled module: GET_SCREEN_SIZE.</computeroutput>
167  <computeroutput>% Compiled module: TERMINEDESSIN.</computeroutput>
168        </screen>
169        Save the figure seen on the screen as a (real, not a screen capture) postscript in only one command.
170        <screenco>
171          <areaspec>
172            <area id="make_ps" coords='6'/>
173          </areaspec>
174        <screen format="linespecific">
175  <prompt>&promptidl;</prompt> <userinput><command>@ps</command></userinput>
176  <computeroutput>% Compiled module: GETFILE.</computeroutput>
177  <computeroutput>% Compiled module: PUTFILE.</computeroutput>
178  <computeroutput>% Compiled module: OPENPS.</computeroutput>
179  <computeroutput>% Compiled module: XQUESTION.</computeroutput>
180  <computeroutput>Name of the postscript file? (default answer is idl.ps)</computeroutput><userinput>first_ps</userinput> &numb1;
181  <computeroutput>% Compiled module: ISAFILE.</computeroutput>
182  <computeroutput>% Compiled module: XNOTICE.</computeroutput>
183  <computeroutput>% Compiled module: CLOSEPS.</computeroutput>
184  <computeroutput>% Compiled module: PRINTPS.</computeroutput>
185  <computeroutput>% Compiled module: FILE_WHICH.</computeroutput>
186  <computeroutput>% Compiled module: CW_BGROUP.</computeroutput>
187  <computeroutput>% Compiled module: XMANAGER.</computeroutput>
188        </screen>
189          <calloutlist>
190            <callout arearefs="make_ps">
191              <para>
192                <remark>If needed, the name of the postscript will automatically be completed with .ps. Just hit return, if you want to use the default postscript name: <filename>idl.ps</filename>.</remark> 
193              </para>
194            </callout>
195          </calloutlist>
196        </screenco>
197        Check that the <quote><filename>first_ps.ps</filename></quote> file is now existing &hellip;
198        <screen format="linespecific">
199  <prompt>&promptidl;</prompt> <userinput><command>print, file_test(psdir + 'first_ps.ps')</command></userinput>
200  <computeroutput>           1</computeroutput>
201  <prompt>&promptidl;</prompt> <userinput><command>help, file_info(psdir + 'first_ps.ps'), /structure</command></userinput>
202  <computeroutput>** Structure FILE_INFO, 21 tags, length=64, data length=63:</computeroutput>
203  <computeroutput>   NAME            STRING    '/Users/sebastie/IDL/first_ps.ps'</computeroutput>
204  <computeroutput>   EXISTS          BYTE         1</computeroutput>
205  <computeroutput>   READ            BYTE         1</computeroutput>
206  <computeroutput>   WRITE           BYTE         1</computeroutput>
207  <computeroutput>   EXECUTE         BYTE         0</computeroutput>
208  <computeroutput>   REGULAR         BYTE         1</computeroutput>
209  <computeroutput>   DIRECTORY       BYTE         0</computeroutput>
210  <computeroutput>   BLOCK_SPECIAL   BYTE         0</computeroutput>
211  <computeroutput>   CHARACTER_SPECIAL</computeroutput>
212  <computeroutput>                   BYTE         0</computeroutput>
213  <computeroutput>   NAMED_PIPE      BYTE         0</computeroutput>
214  <computeroutput>   SETUID          BYTE         0</computeroutput>
215  <computeroutput>   SETGID          BYTE         0</computeroutput>
216  <computeroutput>   SOCKET          BYTE         0</computeroutput>
217  <computeroutput>   STICKY_BIT      BYTE         0</computeroutput>
218  <computeroutput>   SYMLINK         BYTE         0</computeroutput>
219  <computeroutput>   DANGLING_SYMLINK</computeroutput>
220  <computeroutput>                   BYTE         0</computeroutput>
221  <computeroutput>   MODE            LONG               420</computeroutput>
222  <computeroutput>   ATIME           LONG64                1122424373</computeroutput>
223  <computeroutput>   CTIME           LONG64                1122424373</computeroutput>       
224  <computeroutput>   MTIME           LONG64                1122424373</computeroutput>       
225  <computeroutput>   SIZE            LONG64                      4913</computeroutput>
226        </screen>
227      </para>
228      <para id="splot_description">
229        <command>splot</command> accepts the same keywords as <command>plot</command> (<computeroutput id="plot_kwd">/ISOTROPIC, MAX_VALUE=value, MIN_VALUE=value, NSUM=value, /POLAR, THICK=value, /XLOG, /YLOG, /YNOZERO</computeroutput>), including the graphics keywords (<computeroutput id="gr_kwd">BACKGROUND, CHARSIZE, CHARTHICK, CLIP, COLOR, DATA, DEVICE, FONT, LINESTYLE, NOCLIP, NODATA, NOERASE, NORMAL, POSITION, PSYM, SUBTITLE, SYMSIZE, T3D, THICK, TICKLEN, TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKINTERVAL, [XYZ]TICKLAYOUT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKUNITS, [XYZ]TICKV, [XYZ]TICK_GET, [XYZ]TITLE, ZVALUE</computeroutput>).
230      </para>
231      <simpara>
232        It can therefore be customized <emphasis>as much as you want</emphasis>. See this short example:
233      </simpara>
234      <para>
235        <screen format="linespecific">
236  <prompt>&promptidl;</prompt> <userinput><command>splot, y, y^2, linestyle = 2, thick = 2, title = 'y = x^2', /portrait</command></userinput> <ulink url="./figpng/basic_splot2.png">&showfig;</ulink>
237        </screen>
238        <command>splot</command> can be used to setup the graphic environment (<varname>!p</varname>, <varname>!x</varname>, <varname>!y</varname>, <varname>!z</varname> variables) needed by procedures like <command>oplot</command>
239        <screen format="linespecific">
240  <prompt>&promptidl;</prompt> <userinput><command>splot, y, yrange = [0, (n-1)^2], title = 'x and x^2'</command></userinput>
241  <prompt>&promptidl;</prompt> <userinput><command>oplot, y^2, color = 50, linestyle = 2</command></userinput> <ulink url="./figpng/basic_splot4.png">&showfig;</ulink>
242        </screen>
243        Use the keyword small to produce multi plots figures.
244        <screenco>
245          <areaspec>
246            <areaset id="small" coords="">
247              <area id="small.1" coords='1'/>
248              <area id="small.2" coords='2'/>
249            </areaset>
250            <area id="noerase" coords='2'/>
251          </areaspec>
252        <screen format="linespecific">
253  <prompt>&promptidl;</prompt> <userinput><command>splot, y, y^2, title = 'y = x^2', psym = 2, small &numb1; = [1, 2, 1]</command></userinput>
254  <prompt>&promptidl;</prompt> <userinput><command>splot, findgen(360)/36., findgen(360)*2.*!dtor, /polar $</command></userinput>
255  <prompt>&promptidl;</prompt> <userinput><command>    , small &numb1; = [1, 2, 2], /noerase &numb2;</command></userinput> <ulink url="./figpng/basic_splot3.png">&showfig;</ulink>
256        </screen>
257          <calloutlist>
258            <callout arearefs="small">
259              <para>
260                the <computeroutput>small</computeroutput> keyword is a 3 elements vector which defines how we divide the page and in which case we should make the plot: [number of columns, number of rows, case number]. The case numbering is starting at 1, from top to bottom and left to right.
261              </para>
262            </callout>
263            <callout arearefs="noerase">
264              <simpara>
265                you must put <computeroutput>/noerase</computeroutput> otherwise the second plot will be done in a new window.
266              </simpara>
267            </callout>
268          </calloutlist>
269        </screenco>
270      </para>
271     
272      </sect3>
273
274      <sect3 id="basic_contour">
275      <title>
276        scontour
277      </title>
278      <para>
279        Following <command><link linkend="basic_splot">splot</link></command> example, we provide <command>scontour</command> as a "super <command>contour</command>".
280        <screen format="linespecific">
281  <prompt>&promptidl;</prompt> <userinput><command>z = dist(n)</command></userinput>
282  <computeroutput>% Compiled module: DIST.</computeroutput>
283  <prompt>&promptidl;</prompt> <userinput><command>scontour, z</command></userinput> <ulink url="./figpng/basic_scontour1.png">&showfig;</ulink>
284  <computeroutput>% Compiled module: SCONTOUR.</computeroutput>
285  <computeroutput>% Compiled module: CHKSTRU.</computeroutput>
286        </screen>
287        <command>scontour</command> accepts the same keywords as <command>contour</command> (<computeroutput>C_ANNOTATION=vector_of_strings, C_CHARSIZE=value, C_CHARTHICK=integer, C_COLORS=vector, C_LABELS=vector{each element 0 or 1}, C_LINESTYLE=vector, { /FILL | /CELL_FILL | C_ORIENTATION=degrees}, C_SPACING=value, C_THICK=vector, /CLOSED, /DOWNHILL, /FOLLOW, /IRREGULAR, /ISOTROPIC, LEVELS=vector, NLEVELS=integer{1 to 60}, MAX_VALUE=value, MIN_VALUE=value, /OVERPLOT, {/PATH_DATA_COORDS, PATH_FILENAME=string, PATH_INFO=variable, PATH_XY=variable}, TRIANGULATION=variable, /PATH_DOUBLE, /XLOG, /YLOG, ZAXIS={0 | 1 | 2 | 3 | 4}</computeroutput>), including the <link linkend="gr_kwd">graphics keywords</link> (except <computeroutput>LINESTYLE, PSYM, SYMSIZE</computeroutput>).
288      </para>
289      <simpara>It can therefore be customized <emphasis>as much as you want</emphasis>. See these short examples:</simpara>
290      <para>
291        <screen format="linespecific">
292  <prompt>&promptidl;</prompt> <userinput><command>scontour, z, /fill, nlevels = 15, subtitle = 'nicer contour' $</command></userinput>
293  <prompt>&promptidl;</prompt> <userinput><command>    , xtitle = 'x index', charsize = 1.5</command></userinput> <ulink url="./figpng/basic_scontour2.png">&showfig;</ulink>
294        </screen>
295It can be used in combination with contour to make more complex plots:
296        <screenco>
297          <areaspec>
298            <area id="rebin" coords='1'/>
299          </areaspec>
300        <screen format="linespecific">
301  <prompt>&promptidl;</prompt> <userinput><command>ind = findgen(2*n)/(2.*n)</command></userinput>
302  <prompt>&promptidl;</prompt> <userinput><command>scontour, z, levels = n*ind, c_orientation = 180*ind, c_spacing = 0.4*ind</command></userinput>
303  <prompt>&promptidl;</prompt> <userinput><command>contour, z, /overplot, c_label = rebin([1, 0], 2, n) &numb1;, levels = n*ind $</command></userinput>
304  <prompt>&promptidl;</prompt> <userinput><command>    , c_charthick = 2, c_charsize = 1.5, c_colors = 250*ind</command></userinput> <ulink url="./figpng/basic_scontour3.png">&showfig;</ulink>
305        </screen>
306        <calloutlist>
307          <callout arearefs="rebin">
308            <para>
309              <command>rebin</command> is used to build an array containing an alternation of 1 and 0 in order to label one contour every two contours.
310                <screen format="linespecific">
311  <prompt>&promptidl;</prompt> <userinput><command>print, rebin([1, 0], 2, 3)</command></userinput>
312  <computeroutput>       1       0</computeroutput>
313  <computeroutput>       1       0</computeroutput>
314  <computeroutput>       1       0</computeroutput>
315                </screen>
316            </para>
317          </callout>
318        </calloutlist>
319        </screenco>
320        <command>scontour</command> is compatible with the positioning method associated with the <computeroutput>small</computeroutput> keyword. See for example the test file <ulink type="text" url="../../Tests/tst_basic.pro"><filename>tst_basic.pro</filename></ulink>:
321        <screen format="linespecific">
322  <prompt>&promptidl;</prompt> <userinput><command>tst_basic</command></userinput> <ulink url="./figpng/tst_basic.png">&showfig;</ulink>
323        </screen>
324      </para>
325      </sect3>
326
327      <sect3 id="tvplus">
328        <title>
329          Quick look and explore 2D arrays: tvplus
330        </title>
331        <para>
332          <command>tvplus</command> is a enhanced version of tvscl and allow you to have a quick look and perform basic exploration of 2D arrays.
333          <screen format="linespecific">
334  <prompt>&promptidl;</prompt> <userinput><command>tvplus, dist(20)</command></userinput> <ulink url="./figpng/tvplus.png">&showfig;</ulink>
335  <computeroutput>left button  : mouse position and associated array value</computeroutput>
336  <computeroutput>middle button: use it twice to define a zoom box</computeroutput>
337  <computeroutput>right button : quit</computeroutput>
338  <computeroutput>(x, y) = (  5,   5), value = 7.07107</computeroutput>
339  <computeroutput>(x, y) = ( 12,   8), value = 11.3137</computeroutput>
340          </screen>
341          For more informations on <command>tvplus</command>, try:
342          <screen format="linespecific">
343  <prompt>&promptidl;</prompt> <userinput><command>xhelp, 'tvplus'</command></userinput>
344          </screen>
345          To see the source code of <command>tvplus</command>, try:
346          <screen format="linespecific">
347  <prompt>&promptidl;</prompt> <userinput><command>xfile, 'tvplus'</command></userinput>
348          </screen>
349          <note><title>New Feature</title><para>
350          If you use an IDL 6.2 or later revision, you can simply get the help of any command by typing ?<replaceable>command_name</replaceable>, for example:
351          <screen format="linespecific">
352  <prompt>&promptidl;</prompt> <userinput><command>?tvplus</command></userinput>
353          </screen>
354          </para></note>
355        </para>
356      </sect3>
357
358      <sect3 id="pltv">
359        <title>
360          Formal quick look at 2D arrays: pltv
361        </title>
362        <para>
363          <command>pltv</command> is a mix between <link linkend="tvplus">tvplus</link> and <link linkend="plt">plt</link> and allow you to have formal quick look of 2D arrays.
364          <screen format="linespecific">
365  <prompt>&promptidl;</prompt> <userinput><command>pltv, dist(20)</command></userinput> <ulink url="./figpng/pltv.png">&showfig;</ulink>
366          </screen>
367        </para>
368      </sect3>
369    </sect2>
370  </sect1>
371
372  <sect1 id="gridded_data">
373    <title>
374      Explore gridded data (model outputs and observations)
375    </title>
376    <para>
377      This section briefly describes the main functionalities offered by SAXO to explore gridded data on regular or irregular grid.
378    </para>
379
380    <sect2 id="load_grid">
381      <title>
382        Load the data grid
383      </title>
384      <para>
385        As we focus in this section on the gridded data, we must first load the grid informations before reading and plotting the data. Loading the grid independently of the data allow you to reload the grid only when it is strictly necessary and not every time you access the data. In <filename class="directory"><envar>${HOME}</envar>/SAXO_DIR/Tests/</filename>, we provide several examples to load a grid.
386      </para>
387      <sect3 id="load_fromdata">
388        <title>
389          Easiest solution: load data grid (regular or not) directly from the data file.
390        </title>
391        <para>
392          Example of Levitus temperature on a regular 1x1 grid.
393          <screen format="linespecific">
394  <prompt>&promptidl;</prompt> <userinput><command>@tst_initlev</command></userinput>
395  <computeroutput>% Compiled module: INITNCDF.</computeroutput>
396  <computeroutput>% Compiled module: ISAFILE.</computeroutput>
397  <computeroutput>% Compiled module: UNIQ.</computeroutput>
398  <computeroutput>% Loaded DLM: NCDF.</computeroutput>
399  <computeroutput>% Compiled module: COMPUTEGRID.</computeroutput>
400  <computeroutput>% Compiled module: DOMDEF.</computeroutput>
401  <computeroutput>% Compiled module: INTER.</computeroutput>
402  <computeroutput>% Compiled module: TRIANGULE.</computeroutput>
403  <computeroutput>% Compiled module: TRIANGULE_C.</computeroutput>
404  <computeroutput>% Compiled module: UNDEFINE.</computeroutput>
405  <computeroutput>% Compiled module: TESTVAR.</computeroutput>
406  <computeroutput>% Compiled module: DIFFERENT.</computeroutput>
407  <computeroutput>% Compiled module: DEFINETRI.</computeroutput>
408          </screen>
409          This <ulink type="text" url="../../Tests/tst_initlev.pro"><command>@tst_initlev</command></ulink> command allows us to define:
410          <itemizedlist>
411            <listitem><simpara>domain dimensions, stored in <varname>jpi, jpj and jpk</varname></simpara></listitem>
412            <listitem><simpara>points abscissa, stored in 2D array <varname></varname>glamt</simpara></listitem>
413            <listitem><simpara>points ordinates, stored in 2D array <varname></varname>gphit</simpara></listitem>
414            <listitem><simpara>points depths, stored in 1D array <varname></varname>gdept</simpara></listitem>
415            <listitem><simpara>cells corners abscissa, stored in 2D array <varname></varname>glamf</simpara></listitem>
416            <listitem><simpara>cells corners ordinates, stored in 2D array <varname></varname>gphif</simpara></listitem>
417            <listitem><simpara>cells upper boundary depth, stored in 1D array <varname></varname>gdepw</simpara></listitem>
418            <listitem><simpara>land-sea mask, stored in <varname>tmask</varname></simpara></listitem>
419            <listitem><simpara>the cells size in the longitudinal direction, stored in 2D array <varname></varname>e1t</simpara></listitem>
420            <listitem><simpara>the cells size in the latitudinal direction, stored in 2D array <varname></varname>e2t</simpara></listitem>
421            <listitem><simpara>the cells size in the vertical direction, stored in 1D array <varname></varname>e3t</simpara></listitem>
422            <listitem><simpara>the triangulation used to fill the land points, stored in <varname></varname>triangles_list</simpara></listitem>
423          </itemizedlist>
424
425          <screen format="linespecific">
426  <prompt>&promptidl;</prompt> <userinput><command>help, jpi,jpj,jpk</command></userinput>
427  <computeroutput>JPI (LOCAL_COORD)   LONG      =          360</computeroutput>
428  <computeroutput>JPJ (LOCAL_COORD)   LONG      =          180</computeroutput>
429  <computeroutput>JPK (LOCAL_COORD)   LONG      =           33</computeroutput>
430  <prompt>&promptidl;</prompt> <userinput><command>help, glamt, gphit,glamf, gphif</command></userinput>
431  <computeroutput>GLAMT (LONGITUDES)  FLOAT     = Array[360, 180]</computeroutput>
432  <computeroutput>GPHIT (LATITUDES)   FLOAT     = Array[360, 180]</computeroutput>
433  <computeroutput>GLAMF (LONGITUDES)  FLOAT     = Array[360, 180]</computeroutput>
434  <computeroutput>GPHIF (LATITUDES)   FLOAT     = Array[360, 180]</computeroutput>
435  <prompt>&promptidl;</prompt> <userinput><command>help, gdept, gdepw</command></userinput>
436  <computeroutput>GDEPT (VERTICAL)    FLOAT     = Array[33]</computeroutput>
437  <computeroutput>GDEPW (VERTICAL)    FLOAT     = Array[33]</computeroutput>
438  <prompt>&promptidl;</prompt> <userinput><command>help, e1t, e2t, e3t</command></userinput>
439  <computeroutput>E1T (SCALE_FACTORS) FLOAT     = Array[360, 180]</computeroutput>
440  <computeroutput>E2T (SCALE_FACTORS) FLOAT     = Array[360, 180]</computeroutput>
441  <computeroutput>E3T (VERTICAL)      FLOAT     = Array[33]</computeroutput>
442  <prompt>&promptidl;</prompt> <userinput><command>help, tmask</command></userinput>
443  <computeroutput>TMASK (MASKS)       BYTE      = Array[360, 180, 33]</computeroutput>
444  <prompt>&promptidl;</prompt> <userinput><command>help, triangles_list</command></userinput>
445  <computeroutput>TRIANGLES_LIST (LIEES_A_TRIANGULE) LONG      = Array[3, 128880]</computeroutput>
446  <prompt>&promptidl;</prompt> <userinput><command>tvplus, glamt*tmask[*,*,0]</command></userinput>
447  <prompt>&promptidl;</prompt> <userinput><command>tvplus, gphit*tmask[*,*,0]</command></userinput>
448          </screen>
449          We provide other initialization methods/examples
450          <itemizedlist>
451            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2_short.pro">@tst_initorca2_short</ulink> : ORCA2 example</simpara></listitem>
452            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05_short.pro">@tst_initorca05_short</ulink> : ORCA05 example</simpara></listitem>
453            <listitem><simpara><ulink type="text" url="../../Tests/tst_initlev_stride.pro">@tst_initlev_stride</ulink> : same as @tst_initlev but we skip on point over 2 in x and y direction</simpara></listitem>
454            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2_short_stride.pro">@tst_initorca2_short_stride</ulink> : ORCA2 with stride</simpara></listitem>
455            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05_short_stride.pro">@tst_initorca05_short_stride</ulink> : ORCA05 with stride</simpara></listitem>
456            <listitem><simpara><ulink type="text" url="../../Tests/tst_initlev_index.pro">@tst_initlev_index</ulink> : in that case we load the grid using points index as axis instead of the longitude/latitude position</simpara></listitem>
457            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2_index.pro">@tst_initorca2_index</ulink> : load ORCA2 as it see by the model</simpara></listitem>
458            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05_index.pro">@tst_initorca05_index</ulink> : load ORCA05 as it see by the model</simpara></listitem>
459            <listitem><simpara><ulink type="text" url="../../Tests/tst_initlev_index_stride.pro">@tst_initlev_index_stride</ulink> : @tst_initlev_index with stride</simpara></listitem>
460            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2_index_stride.pro">@tst_initorca2_index_stride</ulink> : ORCA2 in index with stride</simpara></listitem>
461            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05_index_stride.pro">@tst_initorca05_index_stride</ulink> : ORCA05 in index with stride</simpara></listitem>
462          </itemizedlist>
463        </para>
464      </sect3>
465      <sect3 id="load_meshmask">
466        <title>
467          Load the grid from OPA <filename>meshmask</filename> file
468        </title>
469        <para>
470          When the grid is really irregular (its abscissa and ordinate cannot be descried by a vector), loading the grid directly from the data forces us to make an approximation when computing the grid corners position and the cells size. In that case, it can be preferable to load the grid from the meshmask file created by OPA. As OPA use a Arakawa-C discretization, loading the grid from the meshmask will also define all parameters related to the U, V and F grids (glam[uv],gphi[uv], e[12][uvf]). Note that, when using a simple <link linkend="load_fromdata">grid definition from the data itself</link> (with <filename>initncdf</filename> or <filename>computegrid</filename>), adding the keyword /FULLCGRID leads also to the definition of all U, V and F grids parameters. There is the examples to load ORCA grids from OPA meshmask.
471          <itemizedlist>
472            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2.pro">@tst_initorca2</ulink> : ORCA2</simpara></listitem>
473            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05.pro">@tst_initorca05</ulink> : ORCA05</simpara></listitem>
474            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2_stride.pro">@tst_initorca2_stride</ulink> : ORCA2 with stride</simpara></listitem>
475            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05_stride.pro">@tst_initorca05_stride</ulink> : ORCA05 with stride</simpara></listitem>
476            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2_index.pro">@tst_initorca2_index</ulink> : load ORCA2 as it see by the model</simpara></listitem>
477            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05_index.pro">@tst_initorca05_index</ulink> : load ORCA05 as it see by the model</simpara></listitem>
478            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca2_index_stride.pro">@tst_initorca2_index_stride</ulink> : ORCA2 in index with stride</simpara></listitem>
479            <listitem><simpara><ulink type="text" url="../../Tests/tst_initorca05_index_stride.pro">@tst_initorca05_index_stride</ulink> : ORCA05 in index with stride</simpara></listitem>
480          </itemizedlist>
481        </para>
482        </sect3>
483    </sect2>
484
485    <sect2 id="plt">
486      <title>
487        horizontal plots and maps
488      </title>
489        <para>
490          A quick presentation of horizontal plots and maps is shown in <ulink type="text" url="../../Tests/tst_plt.pro">tst_plt</ulink>. After loading any of the grid (for example with one of the <link linkend="load_grid">above examples</link>). Just try:
491          <screen format="linespecific">
492  <prompt>&promptidl;</prompt> <userinput><command>tst_plt</command></userinput>
493          </screen>
494        </para>
495        <simpara><emphasis>Beware, the command is <command>tst_plt</command> and not <command>@tst_plt</command> as <filename>tst_plt.pro</filename> is a procedure and not an include.</emphasis></simpara>
496        <para>
497          See the results with
498          <itemizedlist>
499          <listitem><simpara><command>@tst_initlev</command>&figsplt_lev;</simpara></listitem>
500          <listitem><simpara><command>@tst_initorca2</command>&figsplt_orca2;</simpara></listitem>
501          <listitem><simpara><command>@tst_initorca05</command>&figsplt_orca05;</simpara></listitem>
502          <listitem><simpara><command>@tst_initlev_stride</command>&figsplt_lev_stride;</simpara></listitem>
503          <listitem><simpara><command>@tst_initorca2_stride</command>&figsplt_orca2_stride;</simpara></listitem>
504          <listitem><simpara><command>@tst_initorca05_stride</command>&figsplt_orca05_stride;</simpara></listitem>
505          </itemizedlist>
506        </para>
507    </sect2>
508
509    <sect2 id="pltz">
510      <title>
511        vertical sections
512      </title>
513        <para>
514          A quick presentation of vertical sections is shown in <ulink type="text" url="../../Tests/tst_pltz.pro">tst_pltz</ulink>. After loading any of the grid (for example with one of the <link linkend="load_grid">above examples</link>). Just try:
515          <screen format="linespecific">
516  <prompt>&promptidl;</prompt> <userinput><command>tst_pltz</command></userinput>
517          </screen>
518        </para>
519          <simpara><emphasis>Beware, the command is <command>tst_pltz</command> and not <command>@tst_pltz</command> as <filename>tst_pltz.pro</filename> is a procedure and not an include.</emphasis></simpara>         
520        <para>
521          See the results with
522          <itemizedlist>
523          <listitem><simpara><command>@tst_initlev</command>&figspltz_lev;</simpara></listitem>
524          <listitem><simpara><command>@tst_initorca2</command>&figspltz_orca2;</simpara></listitem>
525          <listitem><simpara><command>@tst_initorca05</command>&figspltz_orca05;</simpara></listitem>
526          <listitem><simpara><command>@tst_initlev_stride</command>&figspltz_lev_stride;</simpara></listitem>
527          <listitem><simpara><command>@tst_initorca2_stride</command>&figspltz_orca2_stride;</simpara></listitem>
528          <listitem><simpara><command>@tst_initorca05_stride</command>&figspltz_orca05_stride;</simpara></listitem>
529          </itemizedlist>
530        </para>
531    </sect2>
532
533    <sect2 id="pltt">
534      <title>
535        hovmoellers and time series
536      </title>
537        <para>
538          A quick presentation of hovmoellers and time series is shown in <ulink type="text" url="../../Tests/tst_pltt.pro">tst_pltt</ulink>. After loading any of the grid (for example with one of the <link linkend="load_grid">above examples</link>). Just try:
539          <screen format="linespecific">
540  <prompt>&promptidl;</prompt> <userinput><command>tst_pltt</command></userinput>
541          </screen>
542        </para>
543          <simpara><emphasis>Beware, the command is <command>tst_pltt</command> and not <command>@tst_pltt</command> as <filename>tst_pltt.pro</filename> is a procedure and not an include.</emphasis></simpara>
544        <para>
545          See the results with
546          <itemizedlist>
547          <listitem><simpara><command>@tst_initlev</command>&figspltt_lev;</simpara></listitem>
548          <listitem><simpara><command>@tst_initorca2</command>&figspltt_orca2;</simpara></listitem>
549          <listitem><simpara><command>@tst_initorca05</command>&figspltt_orca05;</simpara></listitem>
550          <listitem><simpara><command>@tst_initlev_stride</command>&figspltt_lev_stride;</simpara></listitem>
551          <listitem><simpara><command>@tst_initorca2_stride</command>&figspltt_orca2_stride;</simpara></listitem>
552          <listitem><simpara><command>@tst_initorca05_stride</command>&figspltt_orca05_stride;</simpara></listitem>
553          </itemizedlist>
554        </para>
555    </sect2>
556
557    <sect2 id="plt1d">
558      <title>
559        1D plots
560      </title>
561        <para>
562          To be continued &hellip;
563        </para>
564   </sect2>
565
566
567  </sect1>
568 
569</article>
Note: See TracBrowser for help on using the repository browser.