Idl commands and Syntax

Procedures and Functions

Logical Operators

Mathematical Operators

Mathematical Functions

Command Statements

Arrays

I/O and Files

Variable Types

The types of variables that IDL supports are: Boolean, Integer, Long Integer, Floating Point Decimal, Double Precision Floating Point Decimal, Complex, Characters, and Strings.

Lets assume that we have some variable named ‘a’. We wish to declare it with a value of 5. Here are some various ways to do so.

Integer: a = 5

Long Integer: a = 5L (lower case l is acceptable but looks like a 1)

Floating Point: a = 5.0

Double Precision a = 5.0D

Complex a = complex(5,0)

String a = ’5’

a = 5

b = a / 2

print, b

b = a / 2.0

print, b

We see that the first time that we divide a by 2 we get 2 because b is assumed to be integer. But if we divide a by 2.0 then b will be automatically changed to a floating variable.

print, 1024 * 768

you wish your program code to be readable,

you wish your code to be smaller,

your program needs to repeat the same commands often,

you wish to reuse similar instructions in other programs.
Procedures including the main procedure begin with the word pro.

This is followed by the name of the procedure. The main procedure must be named the same as the file it is saved in. For example, if my program was saved as decay.pro, then the first line of the main procedure would have to be pro decay.

In many procedures you will wish to pass information from the procedure that invoked it. There are two ways to do this. One is to directly use the same variables as the invoking procedure. The other is to pass the variables as parameters of the procedure. The latter of these is generally preferable to the former option for reasons of style and clarity.

To pass information to be a parameter for the procedure, the first line of the procedure must list those variables that it expects as input. A good example of this is the ‘initialize’ procedure from the tutorial document:

pro initialize, nuclei, t, tau, dt
This defines that ‘initialize’ can accept four arguments as listed above. Then when the procedure is called it must be sent four parameters of the same type as the procedure expects. Here is what the invoking command may look like: initialize, nuclei, t, tau, dt. Please note that the names of the variables being passed do not have to be the same as those in the procedure, but they can be.

After the first line defines the name and input parameters of the procedure, the remainder follows as normal IDL commands. You may invoke command loops and other procedures. With caution you may even invoke the same procedure from within itself, which is called recursion.

All procedures must end with the command end.

Functions are like procedures except that they return one argument and accept their input parameters in parenthesis rather then by separation by commas.

radius(x,y,z) = sqrt(x^2 + y^2 + z^2)

I would begin by declaring ‘radius’ with the word function, and then listing the expected input parameters separated by commas. Then I could define the function with a series of commands. Before terminating the function with the command end, it is necessary to return the output argument of the functions using the command return.
function radius,x,y,z

r = sqrt(x^2 + y^2 + z^2)

return, r

end

Then in my IDL code I could invoke this function by writing:

x2 = 4.2

hypotenuse = radius(x1,x2,x3)

print, hypotenuse
In procedures in IDL, variables and arrays are passed by reference when specified as parameters for the procedure. This means that if you alter the value of the parameters within the procedure, that the alteration will be transferred to the calling procedure as well. Keep this in mind, as it can be the source of annoying programming errors, which are often very difficult to trace. An important exception to this rule is the use of elements of structures or arrays. Array elements will always be passed by value, meaning that if you use an array element as a parameter of a function or procedure, the structure may use but not change the value of that parameter. An example of this is reading input from the keyboard to an array.

Valid Invalid

read,x read, ans(3)

ans(3)=x
For further help on procedure structure, select the help option from the menu bar of IDL. Then select ‘contents’, then ‘Building IDL Applications’, then ‘Defining Procedures and Functions’.

Logical Operators

Logical operators are often used in command loops and also mathematical statements. These operators return either a value of 1 if the statement they evaluate is true or 0 if false. There are two kinds of logical operators: Boolean operators and Relational operators.

There are four Boolean operators in IDL. They take arguments of 1 (true) or 0 (false) and return either a 1 or a 0. The operators are:

AND, OR, XOR, NOT. These are all straightforward with the possible exception of XOR which stands for eXclusive OR, meaning that one and only one of the arguments may be true for XOR to be true. Consider the following examples:
1 and 1 = 1 1 and 0 = 0 0 and 1 = 0 0 and 0 = 0

1 or 1 = 1 1 or 0 = 1 0 or 1 = 1 0 or 0 = 0

1 xor 1 = 0 1 xor 0 = 1 0 xor 1 = 1 0 xor 0 = 0

not 1 = 0 not 0 = 1

There are six relational operators in IDL. They compare numbers which can be integer or decimal. These return 1 for true and 0 for false. The relational operators are: EQ, NE, LE, LT, GE, GT.

NE is ‘not equal’ 5 ne 5 = 0 5 ne 4 = 1

LE is ‘less than or equal’ 5 le 5 = 1 5 le 4 = 0 5 le 6 = 1

LT is ‘less than’ 5 lt 5 = 0 5 lt 4 = 0 5 lt 6 = 1

GE is ‘greater than or equal’ 5 ge 5 = 1 5 ge 4 = 1 5 ge 6 = 0

GT is ‘greater than’ 5 gt 5 = 0 5 gt 4 = 1 5 gt 6 = 0

(A le 50) and (A ge 25) will only be true if A is between 25 and 50. If A is an array of numbers, then the result will be an array of the same dimension consisting of 0’s and 1’s appropriate to the statement.

Mathematical Operators
IDL has all of the familiar mathematical operators (^*/+-) and a few additional ones for matrix mathematics. These operators in combination with the logical operators detailed above follow a system of algebraic precedence. Precedence is what determines which order that operators act within an statement. Operations of the same order of precedence are generally commutative so that ambiguity in their order of execution is usually irrelevant. It is recommended that for complex statements where is order of operation is unclear that parenthesis be used even if not explicitly necessary. The operators will be listed and briefly explained in the order of their precedence.

Highest Precedence
Parentheses ()

The parentheses override any of the algebraic precedences. Use

these as often as is necessary to be certain that IDL evaluates your

statement as you intend.

The carat (^) raises one number to the power of another. For

example: 9⁶ would be expressed in IDL as 9^6.
SECOND Precendence
Multiplication *

The asterisk (*) is the multiplication operator. 9*6 = 54

The forward slash (/) is the division operator. If the arguments of this operator are both integer, the result will be integer as well. If one or two of the operators are decimal, the result will also be a floating decimal.

9/6 = 1 9.0/6 = 1.5 9/6.0 = 1.5
Modulo

The keyword MOD is the Modulo operator. The result of A mod B is

the remainder of A divided by B. This works for integer division and

also for floating division.

9 mod 6 = 3 9.1 mod 6 = 3.1 9 mod 6.1 = 2.9
THIRD Precedence
Addition +

(+) is the addition operator. It is straightforward. 9+6 = 15

(-) is the subtraction operator. It is also straightforward. 9-6 = 3

The not operator is also assigned to the Third level of precedence.

The relational operators (eq,ne,ge,gt,le,lt) are all assigned to the

Fourth level of algebraic precedence.
FIFTH Precedence
Boolean Operators

The remaining three Boolean operators are assigned to the Fifth level

of algebraic precedence.

As stated above, these levels of precedence can be overridden by parentheses. 5 + 2 / 2 + 5 = 11 (5 + 2)/(2 + 5) = 1

It is always preferable to use parenthesis whenever you wish to force the order of operations in a set manner.
Mathematical Functions
Besides the basic operators, IDL has implemented numerous mathematical functions. A list of the most useful ones follows. For a comprehensive list invoke IDL help from the menu bar, select contents and then index. Type mathematics, select ‘Alphabetical list of Mathematics Routines’ and hit display. You will see as list which is similar to but longer than this one.
In the following examples, ‘a’ is a matrix [1,3,5,2,4]
Command Explanation Example

ABS Absolute Value abs(-6)=6

ACOS Inverse Cosine (in radians) acos(0)= 1.57080

ALOG Natural Log ( ln(x) ) alog(2.71828) = 1

ALOG10 Log Base 10 alog(100)=2

ASIN Inverse Sine (in radians) asin(1)= 1.57080

ATAN Inverse Tangent (in radians) atan(1)= 0.785398

COS Cosine (argument in radians) cos(1.57080)=0

COSH Hyperbolic Cosine cosh(.5) = 1.12763

EXP Natural Exponent ( e ) exp(1)= 2.71828

FACTORIAL Factorial ( ! ) factorial(4) = 24

FFT Fast Fourier Transform see IDL help on FFT

FIX Truncates Decimal to Integer fix(3.8) = 3

FLOAT Changes Integer to Decimal float(3) = 3.000

MAX Maximum Value of an Array max(a) = 5

MEAN The Mean of an Array mean(a) = 3

MIN Minimum Value of an Array min(a) = 1

!PI System Constant for pi !PI = 3.141593

PRIMES Computes First n Prime #’s primes(5)= 2,3,5,7,11

RANDOMU Generates a Uniformly Distributed

Random # Between 0 and 1 randomu(1) = .04234

ROUND Rounds a Number round(2.7) = 3

SIN Sine (argument in radians) sin(1.57080)=1

SINH Hyperbolic Sine sinh(1.5) = 2.12928

SQRT Square Root sqrt(16) = 4

TAN Tangent (argument in radians) tan(0.785398)=1

TANH Hyperbolic Tangent tanh(1.5)= 0.905148

TOTAL Sum of Matrix Operations see IDL help on TOTAL

Command Statements
There are four statements which can be used to execute or create a loop though a block of instructions until a specified condition is met. These statements are FOR, IF, REPEAT, WHILE.
FOR-DO Loop

The FOR loop repeats its block of instructions and increments its counter by one for each time the loop is run.

for i = 1,4 do print, i, i^2 will output

1 1 2 4 3 9 4 16

i is the counter. 1,4 are the beginning and ending values for i. Do is the header for the command(s) to be executed. Print displays the counter i and i². The loop executes with i = 1,2,3,4 and then terminates.
If you wish the loop to count to a number greater than 32000, it is necessary to specify that i is a long integer. This can be done by specifying the limits as long integers. For example the above could be written:

for i = 1L,50000 do print, i, i^2. I do not recommend that you actually run this because it will take a very long time! The ‘L’ after the 1 in the counter limits tells IDL that i is a long integer.

You would then terminate the block with and ‘end’ or ‘endfor’ statement. Either will work, though we find the endfor to be preferable for style.

For example:

for i = 0, 98 do begin

nuclei(i+1)=nuclei(i)-(nuclei(i)*(dt/tau))

t(i+1)=t(i)+dt

endfor

Will loop 99 times and calculate (Euler method) the radioactive decay of ‘nuclei’ through 99 timesteps.

for i = 4,1,-1 do print, i, i^2 will output

4 16 3 9 2 4 1 1

This time the loop executes with i = 4,3,2,1 and then terminates. The third argument (-1) specifies that the increment be -1.

The IF Statement is used in conjunction with the logical operators to only execute a command or block of commands when a certain condition is TRUE. For example:

if a ne 1 then print, ‘ a equals one’

You can also provide alternatives with the ELSE command

if a ne 1 then print, ‘ a equals one’ else print, ‘ a is not one’

You can use blocks with IF statements. After THEN put a BEGIN. This starts the block of commands. End the block with END or ENDIF. Again we prefer the ENDIF for style reasons. IF Statements can make your code run very slowly. Often you will want to avoid them, and use more efficient methods.

Consider the following code:
print, 'The Count wishes to know the product of 3 and 2'

read,i

print, 'You selected a number other than 6'

print, 'The Count is most disappointed'

endif else begin

print, 'You selected the number 6'

print, 'Six Sensational Singing Salamanders -- Ha Ha Ha Ha!'

endelse
REPEAT Loop

The REPEAT Loop will repeat a command or a block of commands until a condition is met to stop the loop. The syntax is REPEAT-Command-UNTIL(condition). An example would be:

a = 1

b = 10

Like with all of the other control loops, a block of commands may be substituted for the single command by inserting a BEGIN after the REPEAT and an ENDREP at the end of the block followed by UNTIL(condition).

Consider the following code:

a = 1

repeat begin

a = 2*a

print, 'The Borg have now assimilated ',a,' natives!'

endrep until a gt b
WHILE Loop

The WHILE Loop is like the REPEAT loop except that it tests the condition for execution before executing the command or block of commands that it controls. Here is an example that repeats a calculation until the difference in the result of the current and previous calculations is less than an allowed error. This is a good way to test for convergence in your numerical method.

old_result = new_result

new_result = somefunction(old_result)

delta_result = new_result - old_result

endwhile
Arrays
Arrays are lists of numbers with integer indices. In our computational physics class, we will often want to calculate a list of numbers representing some quantity at various timesteps. An array is perfectly suited to this. There are as many kinds of arrays as there are variables. You can create an array of integers or characters or floating point numbers or Boolean variables. We will most often need to create arrays of integers and floating point numbers. Here is how to accomplish this.
To create a 1-dimensional array (or vector) of floating numbers, type:

nuclei = fltarr(100). This creates a list of 100 numbers indexed from 0 to 99. A 3-dimensional array can be created like this: V3D = fltarr(10,7,5).

This would be a 10x7x5 tensor indexed from (0-9,0-6,0-4). To put information into an array, you must set the array with the appropriate index to that value. For example:

nuclei(7) = 6.8

nuclei(i+1) = nuclei(i) + c

nuclei = nuclei * 0

This last line would set every element of ‘nuclei’ to be zero.
To create an array of integers, the command is intarr(dim). It is used just like the fltarr command explained above. To create an array of long integers use lonarr(dim). The command dblarr(dim) makes an array of double precision floating numbers. The command strarr(dim) creates and array of strings. All of these commands set the elements of the created arrays to zero by default.
Sometimes you will not want the elements of your array to be zero. The command indgen(dim) creates an array of the specified dimensions, with each element set to the same number as its corresponding index.
It is also useful to be able to determine the size of an array, especially if you want to access every element without exceeding the limits of the array. The command N_ELEMENTS will return the size of a specified array.

for i = 0, (n_elements(t)-1) do begin

.

endfor

I/O and Files

print, ‘hello world’ at the Command Line, and you will see the string

‘hello world’ displayed in the Output Log. PRINT can also be used to display variables and statements. If x=2.5 then the command print,x would produce the output ’2.5’ in the Output Log. The command print, alog(x)

would produce the output 0.916291.

You can give the PRINT command multiple arguments seperated by commas. This will generate multiple outputs on the same line.
The command READ is used to take input from the keyboard. It is useful to use the PRINT command to prompt for input and the READ command to receive the input. For example, the following code…

print, "Time Constant (tau):"

read, tau

The PRINT command sends the message to the Output Log specifying what information is required from the user, and the read command takes the next keyboard entry and stores it in the variable tau.

Before any file input or output can be performed, it is necessary to open a file. This is done using either the OPENR (Open an existing file for Reading only), OPENW (Open and create an empty file for Writing), or OPENU (Open an existing file for Update) procedures. When a file is opened, it is associated with a Logical Unit Number, or LUN. All file input and output routines in IDL use the LUN rather than the filename, and most require that the LUN be explicitly specified. Do not use -2, -1, or 0 as a LUN as they are reserved by the system.

Once the file is appropriately opened, there are various commands for reading and writing data. The PRINTF command is like print, except that it directs its output to the file specified by the LUN. There is also a READF command which will read data from a specified file, in much the same way as read will take input from the keyboard. Here is an example program:
OPENW, 1, 'hello.dat' `;Open LUN 1 for hello.dat with write access.

PRINTF, 1, 'Hello World.' ;Do the output operation to the file.

CLOSE, 1 ;Close the file.

OPENR, 1, 'hello.dat' ;Reopen the file.

READF, 1, message ;Read the string.

PRINT, message ;Print the string to the Output Log.

CLOSE, 1 ;Close the file.
For further help on File I/O, select the help option from the menu bar of IDL. Then select ‘contents’, then ‘Building IDL Applications’, then ‘Files and Input/Output’.
Graphics and Devices
The problems that we solve in Computational Physics are seldom ones where you just get ‘an answer’. Sometimes it will be the case that our program will run through its algorithms and at the end generate one number which is ‘the answer’. More often, we will generate lots of numbers and want to see them in some relation to each other. These problems are naturally suited to graphical interpretation. One of IDL’s greatest strengths as a programming language is the ease at which it can display data in a wide variety of graphical representations. For the purpose of this document, only a simple x-y plot will be explained, with references listed for further study.
Whether IDL is operating in the Microsoft Windows or Unix-X Windows environment, it uses ‘windows’ for its graphical output. There can be multiple windows open simultaneously. The windows have numbers. They can be assigned and accessed as follows.

window, 0 ;opens window #0

wset, 0 ;makes window #0 the current window

If you do not specify a window, IDL will automatically open one when you invoke a graphical command such as plot.

plot, x, y ;where x and y are 1-D arrays of the same dim.

0 Continuous lines (default) 1 Plus sign (+)

2 Asterisk (*) 3 Period (.)

4 Diamond 5 Triangle

6 Square 7 X

Consider the following example:

title='RadioActive Decay - Euler Method', xtitle = 'Time', $

ytitle='Number of Nuclei', xrange=[0, max(t)]
The '$' is to tell IDL to continue the command line on to the next line.

This example plots 't' versus 'nuclei' in the range [0,0],[max(t), max(nuclei)]

0 Black & White Linear 22 Hue Sat Value 2

1 Blue/White Linear 23 Purple-Red + Stripes

2 Green-Red-Blue-White 24 Beach

3 Red Temperature 25 Mac Style

4 Blue-Green-Red-Yellow 26 Eos A

5 Standard Gamma-II 27 Eos B

6 Prism 28 Hardcandy

7 Red-Purple 29 Nature

8 Green/White Linear 30 Ocean

9 Green/White Exponential 31 Peppermint

10 Green-Pink 32 Plasma

11 Blue-Red 33 Blue-Red 2

12 16 Level 34 Rainbow 2

13 Rainbow 35 Blue Waves

14 Steps 36 Volcano

15 Stern Special 37 Waves

16 Haze 36 Volcano

17 Blue-Pastel-Red 37 Waves

18 Pastels 38 Rainbow18

19 Hue Sat Lightness 1 39 Rainbow + white

20 Hue Sat Lightness 2 40 Rainbow + black

21 Hue Sat Value 1
As all of these color options can be overwhelming, I would suggest using table 13 (rainbow). It contains all of the necessary colors, and they are in an order that should make sense to a physicist familiar with Newton’s work in Optics. The following list is valid only for table #13.

Color = 0 will give you black (this is the case for most of the tables).

Colors 1-50 are shades of violet.

Colors 51-110 are shades of blue.

Colors 111-170 are shades of green.

Colors 171-210 are shades of yellow.

Colors 211-230 are shades of orange.

Colors 231-255 are shades of red.

device, decompose = 0

x=[1.3, 2.6, 3.7]

y=[2.3, 4.5, 6.1]

loadct, 13

plot, x, y, color = 150, psym = 5

oplot, x, y, color = 250, psym = 6

The four that are most likely going to affect us are printer, ps, win and X.

To send graphics output directly to a printer, type set_plot, ‘printer’ , and then execute the plot that you wish to generate.

To generate a postscript file, use ps instead of printer. You must also specify the name of the file to be generated using the device command. For example, to make a postscript file named ‘plot.ps’ you would type:

set_plot, 'ps'

device, /symbol, /color, bits=8, filename= 'plot.ps'

device, /close
The 'device' command allows you to specify the parameters of your plot. The '/symbol' keyword specifies the font to use. The '/color' keyword signifies that the intended plot will be saved in color. The 'bits =8' directive is to specify the depth of the color (8bit).
On a Windows 95 or NT machine, it is necessary to tell IDL that you are done ploting to the printer or postscript file by typing set_plot, ‘win’. This returns plotting control to the Windows graphic window.
On a UNIX machine, the X-windows graphics system is used. So it is necessary to tell IDL that you are done ploting to the printer or postscript file by typing set_plot, ‘X’. This returns plotting control to the X-windows graphics window.
It is also possible to generate Bitmap, GIF, and JPEG representations of your plot. To write to a GIF file, generate your plot as to the graphics window, and in the next line type: WRITE_GIF, 'plot.gif', TVRD()

To make a Bitmap image, type: WRITE_BMP, 'plot.bmp', TVRD()