% actually an appendix; -*- LaTeX -*-
\chapter{Software used for wave-function propagation}

\section{Choosing the programming language}

MIT's public computing system, named Athena, consists of about five
hundred workstations in a dozen computer clusters that are made freely
available to the MIT community.  The software used for calculation of
return probabilities was intended to be able to be run on them.
Unfortunately, FORTRAN compilers were available only for the oldest,
slowest of these machines at the time when I started writing my
simulation software.  This made using FORTRAN impractical.

One notable disadvantage C in numerical modeling of quantum mechanics
is the lack of availability of complex numbers.  Of course, it isn't
hard to explicitly write out the complex-number operations in terms of
their real and imaginary parts, but it makes longer expressions nearly
unreadable and typing errors almost impossible to find.  How can this
be avoided?

Some C compilers provide complex numbers as an extension to the
standard C language.  The one example available to me is gcc, the GNU
C compiler.  Gcc is widely used on UNIX systems, comparatively easy to
port, and free.  Most importantly to me, it has been made available on
all current Athena platforms.

Thus, gcc seemed the compiler of choice for working on Athena.
However, relying on it would cause problems for using my code in a
different environment.  A possible alternative would be to choose C++,
where I could implement complex numbers as an object class and define
arithmetic operations for them myself.  (Some C++ compilers already
provide a complex class, but creating my own would help both
performance\footnote{In at least one case, the compiler's complex
class failed to specify rules for complex-times-real multiplication,
which means that the compiler must generate code for real-to-complex
conversion and a complex multiplication.  In theory, the inefficiency
could get fixed by a compiler's optimization pass-- but in this case
it doesn't.} and portability.)  C++ isn't as widely used as C, but
this approach will work with {\em any\/} C++ compiler.

The two approaches described above are not mutually exclusive.  C++ is
closely enough related to C that it's easy to make most ANSI C code
compile under a standard C++ compiler.  It is easy to design a few
simple syntactical conventions that can be used as props to access the
underlying implementation of complex numbers.  These props will be
implemented completely differently for C++ than for extended C, but
the differences can be restricted to a header file.  The rest of the
software can then simply use a unified set of conventions that will
work under both gcc and C++.

\section{Complex number conventions}

% Before I explain the particular coding conventions I chose, I should
% briefly explain the syntax used by gcc and C++ to describe complex
% numbers.
% 
% With gcc, it is possible to declare a complex counterpart of any
% numeric type, i.e. not only of {\tt double} and {\tt float}, but any of
% the integer types as well.  The complex type whose real and imaginary
% parts are doubles is declared as {\tt \_\_complex\_\_
% double}.\footnote{The ANSI standard for C specifies that identifiers
% which extend the language syntax must begin and end with two
% underscores, to avoid conflicts with user-defined names.}  The
% imaginary unit is most easily written as {\tt 1i}.  Real and imaginary
% parts of an expression are accessed as {\tt \_\_real\_\_(expr)} and
% {\tt \_\_imag\_\_(expr)}, respectively.  Arithmetic operations use the
% usual symbols ({\tt + - * /}).  The complex conjugate of an expression
% is written as {\tt \~ expr}.
% 
% In C++, the most convenient way of handling complex numbers is to
% define an object class.  (Here we clearly have more choice in the
% selection of names and such, and the following will provide an
% illustration of the general syntax.)  The imaginary unit would most
% easily be written as {\tt complex(0,1)}.  Real and imaginary parts of
% a complex value {\tt z} will be accessed as {\tt z.real} and {\tt
% z.imag}.  The usual arithmetic operators can be extended to apply to
% complex numbers.  We could also define {\tt \~} (which is normally
% used for a bit-complement) to represent the complex conjugate as in
% gcc.

The following are the conventions I decided to implement and use in my
code, in order to hide the language-dependent details of the
implementation of complex numbers:

\begin{itemize}
\item The complex numbers should be declared as type {\tt complex}.
Addition, subtraction, multiplication, division and negation (unary
minus) applied to numbers of this type use complex-number arithmetic.

\item To simplify changes required to adapt the code to more powerful
numeric types (such as {\tt long double}), type {\tt real} should be
used as the real number type corresponding to {\tt complex}.
(Currently, {\tt real} is always an alias for {\tt double}.)

\item The symbol {\tt I} represents the imaginary unit.  (Lower-case
{\tt i} is not used to avoid conflicts with a commonly used index
variable.)

\item Real and imaginary parts of an expression can be extracted with
{\tt Re(expr)} and {\tt Im(expr)}, respectively.

\item The complex conjugate of an expression can be written as {\tt
conj(expr)}.
\end{itemize}

In addition, several handy functions for common complex-number
operations are defined as follows:

\noindent\null
\halign{\hskip1.5cm\hfil\tt #&returns #\cr
Cexp(z) &   $e^z$.                        \hfil \cr
Cabs(z) &   $|z| = \sqrt{(\Re z)^2+(\Im z)^2}$. \cr
Csqabs(z) & $|z|^2 \,=\,  (\Re z)^2+(\Im z)^2$. \cr
Csqrt(z) &  $\sqrt{z}$.                   \hfil \cr
Carg(z) &   $\arg z = \tan^{-1}\left(\Im z\over\Re z\right)$. \hss \cr}

\ifcode
\section{Source code}
\tgrindfile{source/complex-class_h.tex}
\tgrindfile{source/complex-gcc_c.tex}
\tgrindfile{source/complex-gcc_h.tex}
\tgrindfile{source/complex_h.tex}
\tgrindfile{source/errctl_c.tex}
\tgrindfile{source/errctl_h.tex}
\tgrindfile{source/expect_c.tex}
\tgrindfile{source/expect_h.tex}
\tgrindfile{source/fft_h.tex}
\tgrindfile{source/fftw-support_c.tex}
\tgrindfile{source/oppack_c.tex}
\tgrindfile{source/oppack_h.tex}
\tgrindfile{source/param_c.tex}
\tgrindfile{source/param_h.tex}
\tgrindfile{source/propagate_c.tex}
\tgrindfile{source/propagate_h.tex}
\tgrindfile{source/return_c.tex}
\tgrindfile{source/twodim_c.tex}
\tgrindfile{source/util_c.tex}
\tgrindfile{source/util_h.tex}
\fi
