\documentclass[psfig,preprint]{aastex}

\begin{document}
\title{\bf QUICK IDL TUTORIAL NUMBER ONE \\ \today}

\author{Carl Heiles}

\tableofcontents


	This tutorial provides only those few things you need to get
started and prepare your first lab report. IDL is far more powerful than
you would guess from this tutorial, and as the course evolves you will
experience some of this power.

	In our tutorials, commands you enter are in {\bf bold type}, our
comments are in ordinary type, and when we refer to variables in our
comments the variables are in $italics$.  Go through the following
steps. 

\section {THE VERY BASICS}

\subsection{Basic IDL Commands, Constants and Arrays}

\noindent {\bf print, 3*5} This command prints the integer 15, the
result of 3 times 5.  Integer numbers have no decimal point. 

\noindent {\bf A = 3*5} Creates the variable {\it A} and sets it equal
to 15. 

\noindent {\bf help, a} Tells you about the variable $A$.  In IDL,
uppercase and lowercase are identical, so $A$ is the same as $a$. 

\noindent {\bf HELP, A} Identical to the lowercase command above---IDL
doesn't care about case. 

\noindent {\bf a = sqrt(a) \& help, a} Redefines $A$ to be the square
root of its previous value and also tell about $A$.  Typing {\bf \&}
allows you to put a second (or more) command on the same line.  Note
that, now, $a$ has a decimal point.  Numbers with decimal points are
called {\it floating point} numbers. 

\noindent {\bf a = 4.3} Defines $a$ as a floating point number equal to
4.3. 

\noindent {\bf a = 'Joe'} defines $a$ as a string variable---that is,
ordinary text---and sets it equal to ``Joe''.

\noindent {\bf a = [1,2,3,4,5,6]} Make $A$ a six-element array
containing the integer values 1 through 6. 

\noindent {\bf print, a, 2*a} prints the array $A$ and, also, two times
$A$. 

\noindent {\bf b = sqrt(A)} Creates a new array, $b$, in which each
element is the square root of the corresponding element in $a$. 

\noindent {$\bf c = a \wedge 0.5$} Creates a new array, $c$.  The
$\wedge$ symbol is how you raise something to a power.  We'd better have
$b=c$; test it by typing

\noindent {\bf print, max(b-c) \& print, min(b-c)} Prints the maximum
and minimum values of the array $b-c$.  Both $b$ and $c$ are 6-element
arrays, so their difference $b-c$ is also a 6-element array. 

\noindent {\bf print, array\_equal(b,c)} Prints 1 if the arrays are equal
and 0 if they are not. For success, the arrays must not only have equal
elements, but equal length.

\noindent {\bf print, total(b)} Prints the sum of all elements in b.
You'll need this for statistical analysis. 


\noindent {\bf a = fltarr(100)} Define $a$ as an array of 100 floating
point numbers, each element of which equals zero. 

\noindent {\bf a = findgen(100)} Define $a$ as an array of 100 floating
point numbers in which the values increase sequentially from 0 to 99. 

\noindent {\bf print, a[0], a[99]} Print the first and last elements of
$a$.  Elements of an array are designated by a numerical index.  The
index begins with zero; the last element of the array has index $n-1$,
where $n$ is the number of elements in the array.  Why doesn't the index
run from $1 \rightarrow 100$ instead of $0 \rightarrow 99$? You'll
appreciate why\dots later in the course. 

\noindent {\bf print, a[10:20]} Prints $a$ array elements $10
\rightarrow 20$. Such printouts are often handy but it's hard to
identify each array element with its index. To get a printout in {\it
column format}:

\noindent {\bf for nr=0,99 do print, nr, a[nr]} This uses a {\it for
loop} to cycle through the indices numbered $0 \rightarrow 99$ and print
a separate line with two numbers, the index number and the corresponding
array element.

\noindent {\bf b = sin(a/5.)/exp(a/50.)} Defines the new array, $b$, in
which each element is related to the corresponding element in $a$ by the
mathematical expression.  {\it Note} that when we divide anything by a
number we {\it always express the denominator as a floating point
number}.  {\it Always do this} until you learn more. 

\noindent {\bf Plot, b} Make a plot of $b$ versus its index number. 

\noindent {\bf plot, a, b} Make a plot of $b$ versus $a$, with $a$ on
the horizontal ($x$) axis and $b$ on the vertical axis. 

\noindent {\bf z = fltarr(3,7)} Defines a new, array, $z$, as a
two-dimensional array with $3 \times 7$ elements. 

\noindent {\bf help, z} Tells about $z$. 

\subsection{Matrix operations}

	A matrix is just one step away from a 2-d array. IDL provides
all of the standard, and many sophisticated and advanced matrix,
operations. To multiply two matrices you use the $\#$ operator. Thus, the
matrix product {\bf C} of two matrices {\bf A} and {\bf B} is {\bf C} =
{\bf A} \# \# {\bf B}---or {\bf C} = {\bf A} \# {\bf B} depending on\dots a
tricky little point about matrices having to do with row-major or
column-major formats. You need to be aware of this if you will use
matrices; see \S \ref{matrices}. 

\section {THINGS THAT YOU REALLY WANT TO KNOW}

\subsection{ Fundamental mathematical constants}

       A number of mathematical constants are stored in IDL's
``internal variables'', which are characterized by the first character
being ``!''. Here's just a few:

\noindent {\bf print, !pi} (yep! this is just $\pi$)

\noindent {\bf help, !dtor} (degrees times !dtor gives radians)

\noindent {\bf print, !radeg} (radians times !radeg gives degrees)

\noindent There's no variable for $e$, the base of natural logarithms;
to get its numerical value, you have to take $e^1$:

\noindent {\bf print, exp(1)} (base of natural logarithms)

\subsection {The hypertext HELP facility}

        Hypertext on-line documentation is provided by IDL's {\it HELP}
facility.  To access {\it HELP}, type

\noindent {\bf ?}

\noindent and after some huffing and puffing a hypertext window will
come up.  Type in something under
``Look For''. 

For example, in the following pages we will use the random number
generator {\it RANDOMU}.  Type {\it randomu} into the Look For box and
you will see several entries. To generate random numbers we will use
the {\it RANDOMU function}, so single click on that; it will highlight ``RANDOMU
function''.  Click on that.

	In the documentation display, the first portion gives
information about the function or procedure.  Then it defines the
required input parameters.  {\bf RANDOMU} needs two input parameters,
the ``seed'' and the number of random numbers to generate.  (All random
number generators use an input number, called a ``seed'', to begin the
process of generating random numbers; they have to start somewhere!). 
In IDL, if you don't specify the numerical value of the seed, it sets
{\it seed} equal to the time from the system clock, which means the
numbers differ each time you call {\bf RANDOMU}.  For example, with
RANDOMU if you want 230 numbers distributed randomly between 0 and 1,
type

\noindent {\bf output = randomu(seed, 230)}

\noindent This generates a 230-element array called {\it output}.

        Next in the documentation comes the list of keywords, which are
optional.  With {\bf RANDOMU} you can not only generate numbers that are
distributed uniformly, but also with other distributions.  For example,
you can get a normal (also called ``Gaussian'') distribution by setting
the {\it normal} keyword equal to unity:

\noindent {\bf output = randomu(seed, 230, normal=1)}

\noindent or, equivalently when a keyword is equal to unity,

\noindent {\bf output = randomu(seed, 230, /normal)}

\noindent After all this, the help facility provides an example, and
then it gives related items that you can click on if you wish.

	So why are you just sitting there? Generate an array of random
numbers, as in the last line above for example, and plot them with

\noindent {\bf help, output \& plot, output}

\subsection {Command-line editing}

       By now you might be sick of typing.  Typing involves making
mistakes and then retyping the whole line with yet different mistakes;
or perhaps wanting to enter a command that differs just a bit from a
previous one.  The most important editing commands are listed when you
start IDL with our startup file:

\begin {tabbing}
{\bf arrow keys} \hspace{0.8in} \= move the cursor as you'd expect \\
{\bf Ctrl-d} \> deletes the character under the cursor. \\
{\bf backspace} \> deletes the character behind the cursor. \\
{\bf Ctrl-e} \> moves the cursor to the end of the line. \\
{\bf Ctrl-a} \> moves the cursor to the beginning of the line. \\
{\bf Ctrl-k} \> deletes the the rest of the line.
\end{tabbing}

\noindent Sometimes, when command-line editing, you inadvertently hit {\bf
  Ctrl-s}; this prevents the cursor from responding to your keystrokes. If
you encounter this condition, type {\bf Ctrl-q}, after which things will
work normally again.\footnote{This behavior is the default in UNIX and
  Linux; it allows you to start and stop output to your workstation by
  pressing {\bf Ctrl-s} or {\bf Ctrl-q}, respectively. Most people find
  this pretty annoying and if you'd like to turn this ``feature'' off,
  just include this line in your {\tt .cshrc} file: {\tt stty -ixon} }

	{\bf ***}{\it Important Caveat!!!}{\bf ***} {\bf Ctrl-d} will
knock you out of IDL unless you redefine its meaning with the statement

\noindent \textbf{define\_key, /control, '$\wedge$D', /delete\_current}

\noindent You should put this statement in your idl startup file.  If
you use my startup file, it's done; see \S \ref{startup}.

Finally, a very useful feature is the caret key ($\wedge$).  If you press
this, IDL will ask you for a {\it String To Match}.  Type in a string and
IDL will find the previous command in its memory buffer in which this
string appears.  This is great if you need to get a command that you
entered a hundred lines ago.

\subsection {Batch files}

        Suppose you have entered a series of commands and want to repeat
the series, perhaps after making either small or large modifications.
More typing! But you {\it don't have} to do all this typing!

	Create a file containing this series of commands.  This is
called a batch file, which is simply a file that contains the list of
IDL commands you wish to run.  Once you have generated the file with a
UNIX text editor (e.g., textedit or emacs), you invoke it in IDL using
the {\it @} symbol. 

        For example, consider the following series of commands:

\noindent {\bf original = sin( (findgen(200)/35.)$\wedge$2.5)}

\noindent {\bf original = original + 2}

\noindent {\bf time = 3 * findgen(200)}

\noindent {\bf plot, time, original, xtitle="Time", ytitle="amplitude",
\$}

\noindent {\bf yrange=[0.5, 3.5], xrange=[0,600], ystyle=1, psym=-4}

\noindent In the above, the dollar sign \$ is a continuation character,
meaning that the line is continued on the next line. 

	Now, you could type each of these commands on the IDL screen. 
But you could also put them in a batch file called ``test.idlbatch.pro'', or
some other pet name\footnote{It's best to append the abbreviation
  ``pro'' to the name of any IDL procedure, function, run-time
  procedure, or batch file. The reason: IDL assumes that you do so, and
  it allows IDL to find your routines in the IDL path.}. {\it DO THIS NOW!!!}.

	Then invoke the commands by typing in IDL (you don't need to
	type the ``pro'' at the end)

\noindent {\bf @test.idlbatch}

\noindent and you can then edit the file and re-invoke it at your
pleasure. Saves huge amounts of time!

        {\it One important point}.  As you write software you'll create
dozens, if not hundreds, of files containing software. You need to
annotate those files and explain what you've done so that, when you
come back a day or week later, you can decipher what you've done. You
can insert a comment in any IDL software file by preceding the comment
with a semicolon. For example, you ought to insert at the very beginning
of {\it test.idlbatch} the comment

\noindent {\bf ;This file was made for tutorial number 1 at the} 

\noindent {\bf ;idiotic insistence of the professors involved}

\noindent or something to that effect. You can also insert a semicolon
anywhere in a line and the rest of the line will be ignored, e.g.

\noindent {\bf original = original + 2  ;We could instead have added 3}

\noindent Heed the voice of experience: {\it You can't have too many
comments!} 

\subsection {I GOOFED!}

	Sometimes we goof, and sometimes this puts IDL into some sort of
bad state---usually doing something that seems to take forever. If you
could only STOP it!

	You {\it can} stop it. To interrupt any IDL command or program
type

{\noindent} {\bf CTRL-c}

\noindent which means: hold down the {\it Control} key and type the
letter ``c''.  (This works on UNIX system commands, too).  In
IDL, after you've done this it sometimes leaves IDL within a procedure,
and you need to get back to the main level by typing

\noindent {\bf retall}

\noindent which means ``return all''---get out of all procedures and go
back to the main level. Whenever things look weird in IDL, type {\bf
retall}. 

\section {MAKING PLOTS}

\subsection {Specifying data ranges, titles, etc}

	It's easy to make beautiful plots in IDL.  First, generate the
batch file as discussed above (\S 2.4) and run it; you see the plot.  It
has the x- and y-ranges you specified---titles too! Those aspects are
specified by the keywords in the plot procedure.  The ${\bf psym=-4}$
keyword puts each point on the plot as a diamond; try it with ${\bf
psym=+4}$, too---and {\bf 2} and {\bf 0}, too (${\bf psym=0}$ is
equivalent to not specifying psym as a keyword).  The plot procedure has
{\it lots} of keywords.  For the documentation, use the {\it HELP}
facility! In addition to those we've introduced above, take a look at
{\it linestyle}, {\it title}, and {\it ystyle}. 

\subsection {Overplotting}

	Often you want to plot two graphs on the same plot---comparing
the data with a theory, for example. Just to illustrate this, suppose
you want to compare your current plot of {\it original} with what you'd
get by changing the 2.5 power to 2.0. You can do this by:

\noindent {\bf original\_2 = 2 + sin( (findgen(200)/35.)$\wedge$2.0)}

\noindent {\bf oplot, time, original\_2, linestyle=2}

\noindent which will overplot $original\_2$ using a dashed line. If you
want to plot just a single point, you can use {\bf plots}.

\subsection {Making a Hard Copy on Paper}

You do this by creating and then printing a PostScript file.  There are
several ways to do this.  We recommend the following procedure (which is
described in more detail in our memo {\it Making, Printing, and
  PowerPointing PostScript Files of Graphs and Images}): \begin{enumerate}

	\item Using a batch file, edit it so that invoking it makes
your plot look good on the screen. 

	\item Use the procedure \verb$psopen$ to open a PostScript file.
This takes as an argument the name of the PostScript file; you can also
specify the size of the plot (the default is 8.5 by 11 inches). For
example, to make a 5 by 4 inch plot in the file called
\verb$plotfile.ps$ you'd type
\begin{verbatim}
psopen, 'plotfile.ps', xsize=5, ysize=4, /inches
\end{verbatim}

\noindent One important option for PostScript files is using PostScript
fonts, which are really nice; and, also, using thicker lines. To
accomplish this the easy way, replace {\tt psopen} with our wrapper
procedure {\tt ps\_ch}:
\begin{verbatim}
ps_ch, 'plotfile.ps', xsize=5, ysize=4, /inches
\end{verbatim}

\item Invoke your batch file. Because you called
\verb$psopen$ or {\tt ps\_ch}, your plot will be written to the
postcript file instead of to the screen.

	\item Close the poscript file by typing \verb$psclose$; or, if
	you used {\tt ps\_ch}, type {\tt ps\_ch, /close}.

	\item It looks a bit different on the paper than on the screen. 
Before wasting a piece of paper, look at the ps file to make sure you
like it.  You can use one of two programs for this (from the UNIX
prompt):
\begin{verbatim}
	xv plotfile.ps

	or

	gv plotfile.ps
\end{verbatim}

	\item Once you like it so much you are willing to spend a sheet of paper,
print it from the UNIX prompt with the command \verb$lp plotfile.ps$ .
\end{enumerate}

\section {STARTUP FILE} \label{startup}

The IDL startup file enables you to customize IDL by invoking a set of
IDL commands when you begin your IDL session. If you have a good startup
file, you can do things like type

\noindent {\bf plot, x, y, color=!red}

\noindent and the plot will come out in red.  If you use my startup
file, you have these features and the colors include red, green, blue,
cyan, magenta, yellow, white, and black---plus orange, forest, purple,
and gray.  If you're on the {\it astro}
network, to use my startup file define this alias in UNIX (put it in
your \verb$.cshrc$ or \verb$.idlenv$ file):\footnote{The {\tt .cshrc}
  file is like the IDL startup file, but for Linux/UNIX: it enables you to invoke a set of
  Linux/UNIX commands when you open a terminal window.}

\begin{verbatim}
setenv CARLPATH  /dzd2/heiles/
setenv IDL_STARTUP   /dzd2/heiles/idl/gen/idlstartup_ay204
\end{verbatim}

\noindent and if you're on the {\it ugastro} cluster then it's

\begin{verbatim}
setenv AY121PATH    /home/global/ay121/
setenv IDL_STARTUP   /home/global/ay121/idl/gen/idlstartup_ay121.pro

\end{verbatim}

\noindent What's happening here: The first statement creates a
Linux/UNIX environment variable that names the origin of
the tree that contains the IDL procedures; this environment variable is
used in the IDL startup file. The second statement tells the path and
name of the IDL startup file. Using environment variables is a powerful
way to have the same IDL environment on more than one computer.

\section{IDL SAVE FILES}

You can easily write IDL variables to disk and retrieve them during a later
session by using the \verb$save$ and \verb$restore$ commands. See IDL's
online help.. 

\section {READING AND WRITING FORMATTED DATA ONTO DISK}

	Formatted data files are text files of the sort made by a text
editor. You can read such files that you typed in by hand; you can
generate such files in IDL.

\subsection{Writing a file}

	Suppose you want to save the above arrays $original$ and
$original \_ 2$ by writing them into a disk file.  This is a three-step
process:

\noindent {\bf openw, 1, 'original.dat'} Opens logical unit number 1 for
writing (the ``w'' in ``openw'' means ``write'') and equates it to the
filename ``original.dat''. 

\noindent {\bf printf, 1, original, original\_2} {\it Printf} is like
{\it print}, but the ``f'' on the end tells IDL to write the data to
logical unit number 1 in exactly the same format you'd see on the screen
with {\it print}. 

\noindent {\bf close, 1} Closes logical unit number 1.

	To test this, make a directory from the UNIX prompt; you should
see the file name {\it original.dat}.  Also, print the file from the
UNIX prompt by typing

\noindent {\it more original.dat}

\noindent You see all those numbers...first the 200 numbers of
$original$, then the 200 numbers of $original\_2$. Quite a jumble, and
you can't easily compare the two variables or read off what the value of
a particular array element is. It's cleaner to write the numbers in {\it
column format} using a {\it for} loop, by substituting for the above {\bf
printf} statement the following:

\noindent {\bf for nr=0,199 do printf, 1, nr, original[nr], original\_2[nr]}

\noindent Try it!

\subsection{Formatting print statements}

	{\bf print} and {\bf printf} don't necessarily give you what you
want: you might want more or fewer decimal points, for example.  You can
use these in conjunction with the {\bf format} keyword; see IDL's {\bf
?explicitly formated I/O} help.\footnote{Instead of typing {\bf ?} and
working with IDL's help windows for info on {\bf topic}, you can just
type {\bf ?topic}.} 

\subsection{Reading a file IN COLUMN FORMAT}

	When you enter data by hand or write them out with a {\it for}
loop as above, you have {\it column format}. There's an easy way to read
column-formatted data. In the above example, we have three columns.
Suppose we want to read these columns into arrays named $a$, $b$, and
$c$. Then just type

\noindent {\bf readcol, 'original.dat', a, b, c}

\noindent Try it!!! This is not an IDL routine, but rather exists in the
Goddard library.  To get documentation on properly-documented non-IDL
routines, type

\noindent {\bf doc\_library, 'readcol'}

\noindent {\tt doc\_library} is a native IDL procedure; we recommend
usinag our {\tt doc}, which is better (as well as being quicker to type!): 

\noindent {\bf doc, 'readcol'}


\noindent Perhaps you are interested in looking at the code, or in
importing it to your own directory so you can make some changes for
yourself. You can find where the procedure is located by typing

\noindent {\bf which, 'readcol}

\noindent This works for all code that is written in IDL, including
IDL-supplied procedures. But it does not work for IDL-supplied
procedures that are {\it not} written in IDL (such as {\bf plot}, for
example).

\subsection{Reading a file in yourself, without using readcol}

	This is similar to writing a file and requires three statements.
You can use free-format or specify the format. See the documentation by
typing {\bf ?read} and then click on {\it READF procedure}.

\section{OPERATORS}

\subsection{ The $<$ and $>$ operators}

	Suppose {\bf a} and {\bf b} are two arrays.  The statement {\bf
c=( a $<$ b)} sets the new array {\bf c} equal to either {\bf a} or {\bf
b}, whichever is smaller.  Ditto for $>$, except it's whichever is
larger. 

	Example: suppose you want to plot an array {\bf a}, but restrict
the range to the range $(-1 \rightarrow +1)$.  You could either use the
{\bf yrange} keyword or you could type $\mathbf {plot, a < 1 > (-1)}$. 

\subsection{ Relational operators}

	Suppose {\bf a} is an array. The statement {\bf c=(a eq 5)} sets
the new array, $c$, equal to 1 for those elements where {\bf a} is equal
to 5 and zero elsewhere. In place of {\bf eq}, you can write {\bf ne},
{\bf lt}, etc. See IDL's {\bf ?relational operators} help. 

	Why would you want to do this? Suppose {\bf a} consists of
angles that are in the range $0 \rightarrow 2\pi$ and you want to put
them in the range $-\pi \rightarrow \pi$.  The easy IDL command is 
{\bf c = a -- 2*!pi*(a gt !pi)}

\subsection{ The hugely important WHERE}

	Suppose you have an array {\bf a} and you want to identify the
indices of that array for which the elements exceed 10, say.  They are
given by {\bf indices = where(a gt 10)}.  Then {\bf b=a[indices]}
contains only those elements.  This is great for finding bad data
points!

\section{FOR LOOPS: USING THEM AND AVOIDING THEM}

		For loops are handy because you can repeat things easily and
automatically; same for While loops.  However, they are painfully slow. 
You should avoid them when possible.  And IDL provides some very
powerful tools to replace their use; specifically, the operators
discussed above allow you to avoid the for/if combination that is so
often a part of Fortran and C. 

	However, sometimes you really do need to use loops.  The example
below is a case in which a loop was {\it not} necessary; one could
simply write {\bf a=indgen(6)} and {\bf b=indgen(6)$\wedge$2}.  To learn
how to use loops, see IDL's {\bf ?for} help.  Contrary to popular
misconception, you can use a {\bf for} loop in a batch file, but you
have to put the special characters {\bf \&\$} at the end of each line to
tell IDL that the statements are in a group.  Example:

\noindent {\bf for n=0 to 5 do begin \&\$ }

\noindent {\bf a[n]=n \&\$ }

\noindent {\bf b[n]=n$\wedge$2 \&\$ }

\noindent {\bf endfor }

\section{PROCEDURES, FUNCTIONS, AND MAIN PROGRAMS}

\subsection{Procedures and functions}

	Often you find yourself invoking a specific calculation again
and again.  In this case, you should define a {\it procedure} or a {\it
function}.  We cannot overemphasize the importance of breaking down your
code into small segments, each of which is defined by a procedure or
function that resides in a separate file, with each one thoroughly
checked so that there is absolutely no doubt about its reliability. 
This is called {\it modular programming}, and unless you get into the
habit you'll find yourself dealing with undocumented, unreadable,
unmodifiable software files that are hundreds of lines long. 

\subsection{DOCUMENTING your procedures; and reading others' documentation}

	IDL provides an easy way for you to document any procedure or
function that you write. To see how, look for {\bf doc\_library} under
IDL's hypertext help. This command also gives you the documentation for
any procedure for which documentation has been provided; for example,
all of the Goddard library's procedures are documented in this way.

	If you write a procedure and don't document it, you might as
well forget it---because you {\it WILL} forget it!

\subsection{Main programs}

	A main program is exactly like a procedure, residing in a
separate file, except that there is no procedure statement.  This makes
it very much like a batch file; you invoke it from the keyboard by
typing {\bf .run batchfilename} (instead of using the {\bf @} symbol). 
However, there are crucial differences: the main program doesn't need
any special symbols in loops, and it must have an {\it end} statement. 
When developing a procedure, it is often handy to work with it as a main
program. 

\section{ROW- vs.\ COLUMN-MAJOR: AN IMPORTANT DETAIL ABOUT MATRICES} \label{matrices}

	IDL covers matrix operations completely, from elementary to
sophisticated. Before you forage in this territory, you must understand
the following details.

        In a computer, a multidimensional data set can be indexed in two
ways, the {\it column-major} and {\it row-major} formats.  IDL uses the
row-major format, as does Fortran; the other major language, C, uses
column-major.  Suppose you have a $2 \times 2$ matrix called ${\it A}$. 
In IDL's row-major format, when you type {\bf print, A} IDL prints

\begin{mathletters} 
\begin{eqnarray} 
\left[ 
\begin{array}{rrr}
A_{0,0} & A_{1,0} \\
A_{0,1} & A_{1,1} \\
\end{array} 
\; \right] \; ,
\end{eqnarray} 

\noindent which is different from (i.e., it's the {\it transpose} of) what
you are used to seeing in standard matrix notation which is the
column-major format

\begin{eqnarray} 
\left[ 
\begin{array}{rrr}
A_{0,0} & A_{0,1} \\
A_{1,0} & A_{1,1} \\
\end{array} 
\; \right] \; .
\end{eqnarray} 
\end{mathletters} 

        We ourselves use the row-major convention such that when
displayed in a standard IDL {\it print} statement, they look
correct. That means that our definition is the transpose of the standard
one.

	There are some matrix operations for which the difference is
important. This includes not only multiplication, but also some other
operations such as {\bf invert} and {\bf svsol}. IDL almost always
assumes that the inputs to these other operations follow our row-major
convention. 

        If you want to be a purist and define the matrices in the
standard column-major manner, then go ahead and do so.  You then need to
do three things.  First, if you want to see the matrix displayed in the
usual way, then print its transpose by typing {\bf print,
transpose(A)}.  Second, in all our IDL matrix equations, replace ${\bf
\# \#}$ by ${\bf \#}$. Third, check any IDL procedure having a matrix as
input to see what it assumes (the default is almost always row-major). 

	To be specific: if you follow our row-major convention, which is the
transpose of the standard one, then the matrix product must be written

\begin{mathletters}
\begin{equation}
{\bf C = A \ \# \# \ B}
\end{equation}

\noindent while, in contrast, if you follow the standard
column-major one then you must write

\begin{equation}
{\bf C = A \ \# \ B}
\end{equation}
\end{mathletters}

          Why does IDL do this nonstandard thing? It's because it's more
straightforward for image processing, in which traditionally the images
are scanned row-by-row (as in a TV set) instead of column-by-column. And
IDL's origins are image processing, not matrix math. You might find
IDL's convention annoying when you're doing matrix math, but this is
more than compensated for by the intuitive feel you gain when doing
image processing.

\enddocument
\end



