Physics 350:
Computational Methods
for the Physical Sciences

Spring Semester 2009

Lab 9: Getting to Know IDLWAVE and IDL

To quote the IDLWAVE User Manual:

IDLWAVE is a package which supports editing source code written in the Interactive Data Language (IDL), and running IDL as an inferior shell.

In a nutshell, IDLWAVE is a nicer way for writing code to be executed in IDL than the build in IDLDE shell, which frankly, is almost painful to work with. The reason we will use IDLWAVE is that it will allow you to concentrate on learning IDL programming over the next few weeks instead of learning "how the heck to I get these commands into IDL." IDLWAVE uses emacs, a text editor, to let you write the code and provides a set of commands for automatically execuring the code you are working on within emacs in IDL.

Your goal for this week's lab is to run through the Tutorial from section 3.1 of the IDLWAVE User Manual and then work through R.W. O'Connel's IDL Tutorial

PART 1) IDLWAVE: Getting Started

This is copied in large part from Section 3.1 of the IDLWAVE User Manual located here with some minor modifications for our course. The original user manual was written by Lionel Cons Lionel.Cons@cern.ch (original author), Karl Berry karl@freefriends.org, Olaf Bachmann obachman@mathematik.uni-kl.de, and many others.

IDLWAVE is a package which supports editing source code written in the Interactive Data Language (IDL), and running IDL as an inferior shell.

Development Cycle

The purpose of this tutorial is to guide you through a very basic development cycle using IDLWAVE. We will paste a simple program into a buffer and use the shell to compile, debug and run it. On the way we will use many of the important IDLWAVE commands. Note, however, that IDLWAVE has many more capabilities than covered here, which can be discovered by reading the entire manual, or hovering over the shoulder of your nearest IDLWAVE guru for a few days.

It is assumed that you have access to Emacs or XEmacs with the full IDLWAVE package including online help (see section Installation). We also assume that you are familiar with Emacs and can read the nomenclature of key presses in Emacs (in particular, C stands for CONTROL and M for META. Typically the ALT key in Linux or Windows or the CMD key under MacOS carries behaves as the META key).

Open a new source file by typing:

C-x C-f tutorial.pro

A buffer for this file will pop up, and it should be in IDLWAVE mode, indicated in the mode line just below the editing window. Also, the menu bar should contain `IDLWAVE'.

Now cut-and-paste the following code, also available as `tutorial.pro' in the IDLWAVE distribution.

function daynr,d,m,y
  ;; compute a sequence number for a date
  ;; works 1901-2099.
  if y lt 100 then y = y+1900
  if m le 2 then delta = 1 else delta = 0
  m1 = m + delta*12 + 1
  y1 = y * delta
  return, d + floor(m1*30.6)+floor(y1*365.25)+5
end
     
function weekday,day,month,year
  ;; compute weekday number for date
  nr = daynr(day,month,year)
  return, nr mod 7
end
     
pro plot_wday,day,month
  ;; Plot the weekday of a date in the first 10 years of this century.
  years = 2000,+indgen(10)
  wdays = intarr(10)
  for i=0,n_elements(wdays)-1 do begin
      wdays[i] =  weekday(day,month,years[i])
  end
  plot,years,wdays,YS=2,YT="Wday (0=Sunday)"
end

The indentation probably looks funny, since it's different from the settings you use, so use the TAB key in each line to automatically line it up (or, more quickly, select the entire buffer with C-x h, and indent the whole region with C-M-\). Notice how different syntactical elements of the IDL commands are highlighted in different colors.

Let's check out two particular editing features of IDLWAVE. Place the cursor after the end statement of the for loop and press Spacebar. IDLWAVE blinks back to the beginning of the block and changes the generic end to the specific endfor automatically. Now place the cursor in any line you would like to split and press M-RET. The line is split at the cursor position, with the continuation `$' and indentation all taken care of. Use C-/ to undo the last change.

The procedure plot_wday is supposed to plot the day of the week of a given date for the first 10 years of the 21st century. As in most code, there are a few bugs, which we are going to use IDLWAVE to help us fix.

Using IDL Shell within IDLWAVE

First, let's launch the IDLWAVE shell. You do this with the command C-c C-s. The Emacs window will split or another window will popup to display IDL running in a shell interaction buffer. Type a few commands like print,!PI to convince yourself that you can work there just as well as in a terminal, or the IDLDE. Use the arrow keys to cycle through your command history. Are we having fun now?

Now go back to the source window and type C-c C-d C-c to compile the program. If you watch the shell buffer, you see that IDLWAVE types `.run "tutorial.pro"' for you. But the compilation fails because there is a comma in the line `years=...'. The line with the error is highlighted and the cursor positioned at the error, so remove the comma (you should only need to hit Delete!). Compile again, using the same keystrokes as before. Notice that the file is automatically saved for you. This time everything should work fine, and you should see the three routines compile.

Now we want to use the command to plot the day of the week on January 1st. We could type the full command ourselves, but why do that? Go back to the shell window, type `plot_' and hit TAB. After a bit of a delay (while IDLWAVE initializes its routine info database, if necessary), the window will split to show all procedures it knows starting with that string, and plot_wday should be one of them. Saving the buffer alerted IDLWAVE about this new routine. Click with the middle mouse button on plot_wday and it will be copied to the shell buffer, or if you prefer, add `w' to `plot_' to make it unambiguous (depending on what other routines starting with `plot_' you have installed on your system), hit TAB again, and the full routine name will be completed. Now provide the two arguments:

plot_wday,1,1

and press RET. This fails with an error message telling you the YT keyword to plot is ambiguous

Debugging IDL Programs (and viewing IDL Help) within IDLWAVE

Why did your IDL program fail? What are the allowed keywords of the plot command again? Go back to the source window and put the cursor into the `plot' line and press C-c ?. This shows the routine info window for the plot routine, which contains a list of keywords, along with the argument list. Oh, we wanted YTITLE. Fix that up. Recompile with C-c C-d C-c. Jump back into the shell with C-c C-s, press the UP arrow to recall the previous command and execute again.

This time we get a plot, but it is pretty ugly -- the points are all connected with a line. Hmm, isn't there a way for plot to use symbols instead? What was that keyword? Position the cursor on the plot line after a comma (where you'd normally type a keyword), and hit M-Tab and a long list of plot's keywords should appear.

Aha, there it is, PSYM. Middle click to insert it. An `=' sign is included for you too. Now what were the values of PSYM supposed to be? With the cursor on or after the keyword, press M-? for online help (alternatively, you could have right clicked on the colored keyword itself in the completion list). A browser will pop up showing the HTML documentation for the PYSM keyword. OK, let's use diamonds=4. Fix this, recompile (you know the command by now: C-c C-d C-c), go back to the shell (if it's vanished, you know what to do: C-c C-s) and execute again. Now things look pretty good.

Let's try a different day -- how about April fool's day?

plot_wday,1,4

Oops, this looks very wrong. All April Fool's days cannot be Fridays! We've got a bug in the program, perhaps in the daynr function. Let's put a breakpoint on the last line there. Position the cursor on the `return, d+...' line and press C-c C-d C-b. IDL sets a breakpoint (as you see in the shell window), and the break line is indicated. Back to the shell buffer, re-execute the previous command. IDL stops at the line with the breakpoint. Now hold down the SHIFT key and click with the middle mouse button on a few variables there: `d', `y', `m', `y1', etc. Maybe d isn't the correct type. CONTROL-SHIFT middle-click on it for help. Well, it's an integer, so that's not the problem. Aha, `y1' is zero, but it should be the year, depending on delta. Shift click `delta' to see that it's 0. Below, we see the offending line: `y1=y*delta...' the multiplication should have been a minus sign! Hit q to exit the debugging mode, and fix the line to read:

y1 = y - delta

Now remove all breakpoints: C-c C-d C-a. Recompile and rerun the command. Everything should now work fine.

LAB ASSIGNMENT PART #1: How about those leap years? Change the code to plot 100 years and see that every 28 years, the sequence of weekdays repeats. The routine you want to modify is the plot_wday procedure.You will have to change several parameters for several commands. To decypher what this IDL code is doing, look up the IDL help for the various commands involved (remember press M-? for online help) and then modify the appropriate commands as necessary.

1. Once you have successfully changed the tutorial.pro file to generate a plot for 100 years, print this out, you will be turning it in as part of your lab.
2. On your print out of the code, provide a brief description of what changes you made to the code. Briefly justify the changes (it might be good to know what the commands you modify do when justifying the changes).

PART 2) IDL: Getting Started

The following section of the lab requires you to work on IDL Exercises I by R.W. O'Connell located online at http://www.astro.virginia.edu/class/oconnell/astr511/IDLexercises/IDL-Exercises-I.html.

LAB ASSIGNMENT PART #2:

1. Load IDL Exercises I in your web browser.
   
   
2. Skip Section 0 and work through Section 1 of the IDL Exercises I. Turn in documentation showing how you answered/did the following:
   1. What is the difference between X = 5/2 and Y = 5./2 ?
   2. Between X = FLOAT(5/2) and Y = FLOAT(5)/2 ?
   3. Set C equal to the numerical value of the speed of light in cgs units
      • Successively print powers of C until you locate the point at which the result becomes "Inf". What power yields this
        result? [NOTE: The answer is non-integer.]
      • Now define C to be the speed of light in double precision. Repeat the exercise above.
        
        
3. Work through Section 2 of the IDL Exercises I regarding vectors and vector manipulation. Turn in documentation showing how you answered/did the following:
   1. Use built-in IDL functions N_ELEMENTS, MIN, MAX, and TOTAL to answer the following:
      • How many elements does X contain?
      • What is the minimum value in X?
      • What is the maximum value in X?
      • What is the sum of all the elements in X?
   2. Is X a row-vector or a column-vector?
   3. Using the WHERE function:
   • Define Q=2*X, then type FIND = WHERE(Q LE 40, COUNT). Predict and confirm the response if you type PRINT,Q[FIND]
   4. What is the difference between Z = X*0.0 and Z = 0?
   5. Print the 11 elements centered on X = 10
      • First do this using a FOR loop (on a single line)
      • Then do this using the standard IDL subscript range notation, e.g. X[2:6]. No FOR loop is needed.
      • Compare to the following: K=5 and PRINT,X(10-K:10+K)
   6. Define Q = Y^4. Define Q = FLOAT(Y)^4. Note the change.
      
      
4. Work through Section 4 of the IDL Exercises I regarding plotting. Turn in documentation showing how you answered/did the following:
   1. Define X to contain the integers in the range 0 to 100. Then compute Z = SIN(X)/X. Is Z a floating point variable?
   2. Plot Z vs X using a solid line. Overplot open triangles at those points you found where Z has an absolute value smaller than 0.05. TURN IN A COPY OF THIS PLOT. HINT: Read Section 7 of IDL Exercises I on generating hardcopies of plots in order to do this.