SébastienMassonsmasson@lodyc.jussieu.fr FrançoisePinsard idl SAXO 0.0 29 July 2005 First draft 0.1 29 August 2005 last japanese version! SAXO needs at least IDL 6.0. SAXO can be used with the 7 minutes demo-mode (within the limitations of this mode: impossible to save data and create a file). Two tar.gz files are available: SAXO_RD_&date;.tar.gz (&szsrc;) contains the latest version of the source files TestsData_&date2;.tar.gz (&szdata;) contains only the NetCDF files used by the test programs Those tar.gzip files could also be downloaded with wget $ wget http://www.lodyc.jussieu.fr/~smasson/SAXO/SRC/SAXO_RD_&date;.tar.gz $ wget http://www.lodyc.jussieu.fr/~smasson/SAXO/DATA/TestsData_&date2;.tar.gz curl $ curl -O http://www.lodyc.jussieu.fr/~smasson/SAXO/SRC/SAXO_RD_&date;.tar.gz $ curl -O http://www.lodyc.jussieu.fr/~smasson/SAXO/DATA/TestsData_&date2;.tar.gz To simplify the explanation, we suppose that SAXO is installed in $HOME. We need to create 2 directories: SAXO_DIR that will contain the source files of SAXO. It should not be modified by the user to simplify later updates MY_IDL that will contain user personal files (including modified SAXO files, if needed). $ cd $HOME $ mkdir My_IDL $ mkdir SAXO_DIR $ mv SAXO_RD_*.tar.gz SAXO_DIR $ cd SAXO_DIR $ tar xvfz SAXO_RD_*.tar.gz $ rm SAXO_RD_*.tar.gz If you also downloaded the data tests files (TestsData_&date2;.tar.gz), You may install this tar.gz file in MY_IDL. This is the easiest solution but it could be unconvenient if your $HOME disk space is limited. Any other Directory of your choice. In that case, when using IDL, you will need to define the variable iodir to the Directory you choose in order to let IDL find the data tests files. This can be done either through the init.pro file (see ) or directly within IDL with the following commad: &promptidl; iodir = "the chosen directory" $ cd $HOME $ mv TestsData_&date2;.tar.gz "CHOSEN_DIR" $ cd "CHOSEN_DIR" $ tar xvfz TestsData_&date2;.tar.gz $ rm TestsData_&date2;.tar.gz To use SAXO, we need to build an idl script that we usually call "init.pro". This file contains a set of IDL commands and default definitions (paths and variables of the common files) that are necessary to SAXO. Once it has ben created, init.pro should the first executed command when starting IDL session. $ cd $HOME/SAXO_DIR $ idl IDL Version 6.0, Mac OS X (darwin ppc m32). (c) 2003, Research Systems, Inc. &promptidl; buildinit % Compiled module: BUILDINIT. You must then answer several questions: give the path of $HOME/My_IDL give the path of $HOME/SAXO_DIR compatibility with the old version: No (except if you want to use old programs) give a default path for the data directory give a default path for the postscript directory give a default path for the images directory give a default path for the animation directory number of accessible printer and their configuration default color table default page orientation (portrait/landscape) default page size default window size postscript archiving options name of the init file (init.pro) % Compiled module: CW_FIELD. % Compiled module: XMANAGER. % Compiled module: LOADCT. % Compiled module: FILEPATH. % Compiled module: PATH_SEP. % Compiled module: CW_FIELD. % Compiled module: STRSPLIT. % Compiled module: CW_FIELD. % Compiled module: CW_FIELD. % Compiled module: CW_FIELD. &promptidl; exit There is an example of the kind of init.pro you should get. Each idl session using SAXO must always start with: &promptidl; @init. 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 @... file will still be accessible after the execution of the @... is finished (which is not the case for procedures and functions that ends with the return instruction). $ cd $HOME/My_IDL $ idl IDL Version 6.0, Mac OS X (darwin ppc m32). (c) 2003, Research Systems, Inc. Installation number: 35411. Licensed for personal use by Jean-Philippe BOULANGER only. All other use is strictly prohibited. &promptidl; @init % Compiled module: KEEP_COMPATIBILITY. % Compiled module: FIND. % Compiled module: PATH_SEP. % Compiled module: STRSPLIT. % Compiled module: DEF_MYUNIQUETMPDIR. We forget the compatibility with the old version % Compiled module: DEMOMODE_COMPATIBILITY. % Compiled module: ISADIRECTORY. % Compiled module: LCT. % Compiled module: RSTRPOS. % Compiled module: REVERSE. % Compiled module: STR_SEP. % Compiled module: LOADCT. &promptidl; As an IDL session using SAXO must always start with &promptidl; @init, it could be convenient to define the environment variable IDL_STARTUP to $HOME/My_IDL/init.pro. In that way, init.pro will automatically been execuded when starting IDL. This can be done with the following command: csh $ setenv IDL_STARTUP $HOME/My_IDL/init.pro ksh $ export IDL_STARTUP=$HOME/My_IDL/init.pro &promptidl; n = 10 &promptidl; y = findgen(n) &numb1; &promptidl; plot, y &showfig; findgen stands for float index generator. &promptidl; print, findgen(6) 0.00000 1.00000 2.00000 3.00000 4.00000 5.00000 Using IDL plot command is quite unconvenient to save the figure as a postscript. In addition, positionning the figure on the window/page by using !p.position, !p.region and !p.multi is often a nightmare. That's why we developped splot (like super-plot) which can be used in the same way as plot but is much more convenient to make postcript and position the figure. &promptidl; splot, y &showfig; % Compiled module: SPLOT. % Compiled module: REINITPLT. % Compiled module: PLACEDESSIN. % Compiled module: CALIBRE. % Compiled module: GIVEWINDOWSIZE. % Compiled module: GET_SCREEN_SIZE. % Compiled module: TERMINEDESSIN. Save the figure seen on the screen as a (real, not a screen capture) postscript in only one command. &promptidl; @ps % Compiled module: GETFILE. % Compiled module: PUTFILE. % Compiled module: OPENPS. % Compiled module: XQUESTION. Name of the postscript file? (default answer is idl.ps) first_ps &numb1; % Compiled module: ISAFILE. % Compiled module: XNOTICE. % Compiled module: CLOSEPS. % Compiled module: PRINTPS. % Compiled module: FILE_WHICH. % Compiled module: CW_BGROUP. % Compiled module: XMANAGER. If needed, the name of the postscript will automatically be completed with .ps. Just hit return, if you want to use the default posscript name: idl.ps. Check that the 'first_ps.ps' file is now existing... &promptidl; print, file_test(psdir + 'first_ps.ps') 1 &promptidl; help, file_info(psdir + 'first_ps.ps'), /structure ** Structure FILE_INFO, 21 tags, length=64, data length=63: NAME STRING '/Users/sebastie/IDL/first_ps.ps' EXISTS BYTE 1 READ BYTE 1 WRITE BYTE 1 EXECUTE BYTE 0 REGULAR BYTE 1 DIRECTORY BYTE 0 BLOCK_SPECIAL BYTE 0 CHARACTER_SPECIAL BYTE 0 NAMED_PIPE BYTE 0 SETUID BYTE 0 SETGID BYTE 0 SOCKET BYTE 0 STICKY_BIT BYTE 0 SYMLINK BYTE 0 DANGLING_SYMLINK BYTE 0 MODE LONG 420 ATIME LONG64 1122424373 CTIME LONG64 1122424373 MTIME LONG64 1122424373 SIZE LONG64 4913 splot accepts the same keywords as plot (/ISOTROPIC, MAX_VALUE=value, MIN_VALUE=value, NSUM=value, /POLAR, THICK=value, /XLOG, /YLOG, /YNOZERO), including the graphics keywords (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). It can therefore be customized as much as you want. See this short example: &promptidl; splot, y, y^2, linestyle = 2, thick = 2, title = 'y = x^2', /portrait &showfig; splot can be used to setup the graphic environment (!p, !x, !y, !z variables) needed by procedures like oplot &promptidl; splot, y, yrange = [0, (n-1)^2], title = 'x and x^2' &promptidl; oplot, y^2, color = 50, linestyle = 2 &showfig; Use the keyword small to produce multi plots figures. &promptidl; splot, y, y^2, title = 'y = x^2', psym = 2, small &numb1; = [1, 2, 1] &promptidl; splot, findgen(360)/36., findgen(360)*2.*!dtor, /polar $ &promptidl; , small &numb1; = [1, 2, 2], /noerase &numb2; &showfig; the small keyword is a 3 elements vector which define how we devide the page in 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. you must put /norease otherwise the second plot will be done in a new window. Following splot example, we provide scontour as a "super contour". &promptidl; z = dist(n) % Compiled module: DIST. &promptidl; scontour, z &showfig; % Compiled module: SCONTOUR. % Compiled module: CHKSTRU. scontour accepts the same keywords as contour (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}), including the graphics keywords (except LINESTYLE, PSYM, SYMSIZE). It can therefore be customized as much as you want. See these short examples: &promptidl; scontour, z, /fill, nlevels = 15, subtitle = 'nicer contour' $ &promptidl; , xtitle = 'x index', charsize = 1.5 &showfig; It can be used in combinanson with contour to make more complex plots: &promptidl; ind = findgen(2*n)/(2.*n) &promptidl; scontour, z, levels = n*ind, c_orientation = 180*ind, c_spacing = 0.4*ind &promptidl; contour, z, /overplot, c_label = rebin([1, 0], 2, n) &numb1;, levels = n*ind $ &promptidl; , c_charthick = 2, c_charsize = 1.5, c_colors = 250*ind &showfig; rebin is used to build an array containing an alternation of 1 and 0 in order to label one contour every two contours. &promptidl; print, rebin([1, 0], 2, 3) 1 0 1 0 1 0 scontour is compatible with the positioning method associated with the small keyword. See for example the test file tst_basic.pro: &promptidl; tst_basic &showfig; tvplus is a enhanced version of tvscl and allow you to have a quick look and perform basic exploration of 2D arrays. &promptidl; tvplus, dist(20) &showfig; left button : mouse position and associated array value middle button: use it twice to define a zoom box right button : quit (x, y) = ( 5, 5), value = 7.07107 (x, y) = ( 12, 8), value = 11.3137 For more informations on tvplus, try: &promptidl; xhelp, 'tvplus' This section briefly describes the main fonctionalities offered by SAXO to explore gridded data on regular or irregular grid. 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 $HOME/SAXO_DIR/Tests, we provide several examples to load a grid. Example of Levitus temprature on a regular 1x1 grid. &promptidl; @tst_initlev % Compiled module: INITNCDF. % Compiled module: ISAFILE. % Compiled module: UNIQ. % Loaded DLM: NCDF. % Compiled module: COMPUTEGRID. % Compiled module: DOMDEF. % Compiled module: INTER. % Compiled module: TRIANGULE. % Compiled module: TRIANGULE_C. % Compiled module: UNDEFINE. % Compiled module: TESTVAR. % Compiled module: DIFFERENT. % Compiled module: DEFINETRI. This @tst_initlev command allows us to define: domain dimensions, stored in jpi, jpj and jpk points abscissa, stored in 2D array glamt points ordinates, stored in 2D array gphit points depths, stored in 1D array gdept cells corners abscissa, storde in 2D array glamf cells corners ordinates, stored in 2D array gphif cells upper bondary depth, stored in 1D array gdepw land-sea mask, stored in tmask the cells size in the longitudinal direction, stored in 2D array e1t the cells size in the latitudinal direction, stored in 2D array e2t the cells size in the vertical direction, stored in 1D array e3t the triangulation used to fill the land points, stored in triangles_list &promptidl; help, jpi,jpj,jpk JPI (LOCAL_COORD) LONG = 360 JPJ (LOCAL_COORD) LONG = 180 JPK (LOCAL_COORD) LONG = 33 &promptidl; help, glamt, gphit,glamf, gphif GLAMT (LONGITUDES) FLOAT = Array[360, 180] GPHIT (LATITUDES) FLOAT = Array[360, 180] GLAMF (LONGITUDES) FLOAT = Array[360, 180] GPHIF (LATITUDES) FLOAT = Array[360, 180] &promptidl; help, gdept, gdepw GDEPT (VERTICAL) FLOAT = Array[33] GDEPW (VERTICAL) FLOAT = Array[33] &promptidl; help, e1t, e2t, e3t E1T (SCALE_FACTORS) FLOAT = Array[360, 180] E2T (SCALE_FACTORS) FLOAT = Array[360, 180] E3T (VERTICAL) FLOAT = Array[33] &promptidl; help, tmask TMASK (MASKS) BYTE = Array[360, 180, 33] &promptidl; help, triangles_list TRIANGLES_LIST (LIEES_A_TRIANGULE) LONG = Array[3, 128880] &promptidl; tvplus, glamt*tmask[*,*,0] &promptidl; tvplus, gphit*tmask[*,*,0] We provide other initialization methods/examples @tst_initorca2_short : ORCA2 example @tst_initorca05_short : ORCA05 example @tst_initlev_stride : same as @tst_initlev but we skip on point over 2 in x and y direction @tst_initorca2_short_stride : ORCA2 with stride @tst_initorca05_short_stride : ORCA05 with stride @tst_initlev_index : in that case we load the grid using points index as axis instead of the longitude/latitude position @tst_initorca2_index : load ORCA2 as it see by the model @tst_initorca05_index : load ORCA05 as it see by the model @tst_initlev_index_stride : @tst_initlev_index with stride @tst_initorca2_index_stride : ORCA2 in index with stride @tst_initorca05_index_stride : ORCA05 in index with stride 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 grid definition from the data itself (with initncdf or computegrid), 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. @tst_initorca2 : ORCA2 @tst_initorca05 : ORCA05 @tst_initorca2_stride : ORCA2 with stride @tst_initorca05_stride : ORCA05 with stride @tst_initorca2_index : load ORCA2 as it see by the model @tst_initorca05_index : load ORCA05 as it see by the model @tst_initorca2_index_stride : ORCA2 in index with stride @tst_initorca05_index_stride : ORCA05 in index with stride A quick presentation of horizontal plots and maps is shown in tst_plt. After laoding any of the grid (for example with one of the above examples). Just try: &promptidl; tst_plt Beware, the command is tst_plt and not @tst_plt as tst_plt.pro is a procedure and not an include. See the results with @tst_initlev&figsplt_lev; @tst_initorca2&figsplt_orca2; @tst_initorca05&figsplt_orca05; @tst_initlev_stride&figsplt_lev_stride; @tst_initorca2_stride&figsplt_orca2_stride; @tst_initorca05_stride&figsplt_orca05_stride; A quick presentation of vertical sections is shown in tst_pltz. After laoding any of the grid (for example with one of the above examples). Just try: &promptidl; tst_pltz Beware, the command is tst_pltz and not @tst_pltz as tst_pltz.pro is a procedure and not an include. See the results with @tst_initlev&figspltz_lev; @tst_initorca2&figspltz_orca2; @tst_initorca05&figspltz_orca05; @tst_initlev_stride&figspltz_lev_stride; @tst_initorca2_stride&figspltz_orca2_stride; @tst_initorca05_stride&figspltz_orca05_stride; A quick presentation of hovmoellers and time series is shown in tst_pltt. After laoding any of the grid (for example with one of the above examples). Just try: &promptidl; tst_pltt Beware, the command is tst_pltt and not @tst_pltt as tst_pltt.pro is a procedure and not an include. See the results with @tst_initlev&figspltt_lev; @tst_initorca2&figspltt_orca2; @tst_initorca05&figspltt_orca05; @tst_initlev_stride&figspltt_lev_stride; @tst_initorca2_stride&figspltt_orca2_stride; @tst_initorca05_stride&figspltt_orca05_stride; To be continued...