Merge branch 'tufte' -- preparing for ICCP organization

Author: rayhem

cag.sty

@@ -1,5 +1,5 @@
 \RequirePackage{latexsym,amsmath,amssymb,makeidx}
-\RequirePackage[dvipsnames,usenames]{color}
+%\RequirePackage[dvipsnames,usenames]{color}
 %\RequirePackage[colorlinks=true,urlcolor=Blue,citecolor=Green,linkcolor=BrickRed]{hyperref}
 
 \hyphenation{co-or-din-ate co-or-din-ates half-plane half-space stereo-iso-mers

chapters/Coding_style.tex

@@ -18,21 +18,21 @@
   \item\textbf{Line width}---Limit the line width of your source to 80 characters.
     This has been standard practice for decades, and vastly improves both readability and the ability to cleanly print your code.
     If you do need more than 80 characters on a line, use the Fortran continuation character `\texttt{\&}'.
-  \item\textbf{Indentation}---Indent every block, be it  a \keyword{program}, \keyword{module}, \keyword{subroutine}, \keyword{function}, \keyword{do} or \keyword{if} block by 2 or 4 spaces.
+  \item\textbf{Indentation}---Indent every block, be it  a \keyword{program}, \keyword{module}, \linebreak \keyword{subroutine}, \keyword{function}, \keyword{do} or \keyword{if} block by 2 or 4 spaces.
     \emph{Don't use tabs!} Code that looks properly aligned on your machine may look horrible on another because of a different tab setting.
     Proper indentation makes it clear where control structures begin and end, and is a major boon to readability.
     If the indentation puts you over the 80 character limit, that's an indication that you may need to refactor your code intro smaller subroutines.
     Four levels of indentation should generally be the maximum.
-  \item\textbf{Spaces}---Put spaces around binary operators, including \texttt{::}, and after keywords and commas, not after unary operators, function names or around parentheses. For example\newpage
-\begin{lstlisting}[caption=,nolol,float=t!]
+  \item\textbf{Spaces}---Put spaces around binary operators, including \texttt{::}, and after keywords and commas, not after unary operators, function names or around parentheses. For example
+\begin{lstlisting}[caption=,nolol,float=h!]
   real(8) :: x, y
   x = func1()
   if ((x < 0) .or. (x > 1)) then
       y = func2(-2, 2*x + 3)
   end if
 \end{lstlisting}
   \item\textbf{Naming}---Identifiers in Fortran can't contain spaces.
-    Use \texttt{CamelCase} to separate words in program and module names, and \texttt{lower\_case\_with\_underscores} for function and variable names.
+    Use \linebreak \texttt{CamelCase} to separate words in program and module names, and \linebreak \texttt{lower\_case\_with\_underscores} for function and variable names.
     Names should be descriptive, but they don't have to be overly long.
     You can use \texttt{calc\_deriv} instead of \texttt{calculate\_derivative}, but naming your function \texttt{cd} is a shooting offense.
     Unfortunately, until the appearance of Fortran 90, only the first six characters of an identifier were significant, leading to such beautifully transparent function names as \texttt{DSYTRF}\footnote{DSYTRF computes the factorization of a real symmetric matrix using the Bunch-Kaufman diagonal pivoting method, in case you wondered.} in legacy codes like \idx{LAPACK}.
@@ -46,16 +46,16 @@
     Don't worry about the overhead of calling a function.
     If you use optimization flags like \texttt{-O3}, the compiler will try to inline them anyway.
   \item\textbf{Modules}---Separate your program into logical units.
-    Combine related functions and subroutines into modules.
-    For example, a single module with function integrators, or ODE solvers.
+    Combine related functions and subroutines into modules\footnote{It's also convenient to put all physical parameters (number of particles, $\pi$, $c$, $k_B$, etc.) into their own module, even if they're just constant numbers. You can then ``load'' the parameters into your subroutines with the \keyword{use} statement instead of having absurdly long lists of arguments, or worse, global variables.}.
+    For example, a single module with function integrators, or ODE solvers. 
     If you use the object-oriented features of Fortran, it is also good practice to create separate modules for classes, \eg, a sparse-matrix object.
   \item\textbf{Comments}---Comments are kind of a double-edged sword.
     If used wrongly, they can actually hurt readability.
     The golden rule is: never explain \emph{how} it works, just \emph{what} it does.
     The how should be evident from the code itself.
     \emph{``Good code is its own best documentation.''} If you follow the other guidelines regarding naming and keeping functions small, you can generally suffice with a small comment at the beginning of every function or subroutine.
 \end{itemize}
-One final point, not of style, but important nonetheless: start every program and module with \keyword{implicit none}\index{Fortran!implicit none@\keyword{implicit none}}.
+One final point, not of style, but important nonetheless: start every program and module with \keyword{implicit none}\marginnote{The \texttt{-fimplicit-none}\index{compiler flags!-fimplicit-none} compiler flag will also turn off implicit typing globally.}  \index{Fortran!implicit none@\keyword{implicit none}}.
 This is an unfortunate holdover from older versions of Fortran; it forces you to explicitly declare all variables, instead of allowing Fortran to infer the type from the name.
 Forgetting \keyword{implicit none} and making a typo in one of your variable names is a major source of bugs.
 \emph{Never ever omit this!}

chapters/Debugging.tex

@@ -3,7 +3,7 @@
 
 \begin{quote}\small
   \emph{``Everyone knows that debugging is twice as hard as writing a program in the first place.
-  So if you're as clever as you can be when you write it, how will you ever debug it?'' \\ \\
+  So if you're as clever as you can be when you write it, how will you ever debug it?'' \\
   ``The most effective debugging tool is still careful thought, coupled with judiciously placed print statements.''} \\\hspace*{\fill}---Brian Kernighan
 \end{quote}
 The \texttt{MyProg} program does not contain any bugs (fingers crossed) and works as expected.

chapters/Getting_your_toes_wet.tex

@@ -13,14 +13,14 @@
 After booting Ubuntu, you need to install a Fortran compiler.
 Open a terminal and at the prompt (the \$) type
 \begin{lstlisting}[style=prompt, nolol]
-  $ sudo aptitude install gfortran gfortran-doc
+  $ sudo apt-get install gfortran gfortran-doc
 \end{lstlisting}
 \emph{Note that anything you type in the console is case-sensitive!}
 This command grants \texttt{aptitude} privileges to search for and then install the \texttt{gfortran} package and its documentation.
 You may also find it useful to install the \LaTeX\ typesetting system for writing reports.
 You can install it with another call to \texttt{aptitude}:
 \begin{lstlisting}[style=prompt, nolol]
-  $ sudo aptitude install texlive # or texlive-full for a complete installation
+  $ sudo apt-get install texlive # or texlive-full for a complete installation
 \end{lstlisting}
 
 Once you have \texttt{gfortran} installed, you can start writing programs.
@@ -40,6 +40,8 @@
 \end{lstlisting}
 
 For your first program, open a terminal, create a directory for ICCP files and open your first Fortran file by typing
+\marginnote[-0.5cm]{Modern terminal emulators all have a feature called
+  \emph{tab completion}\index{Tab completion}; enter part of a command \& hit the \texttt{TAB} key and the terminal will attempt to fill in the rest of the command for you.}
 \begin{lstlisting}[style=prompt, nolol]
   $ mkdir iccp          # create a new directory called 'iccp'
   $ cd iccp             # move to the new directory
@@ -50,7 +52,7 @@
 \begin{itemize}
   \item The program starts with a declaration of variables.\index{Fortran!types}
     \texttt{\keyword{real}(8)} denotes a floating-point variable with double (8 byte) precision.
-    Similarly, \keyword{integer} denotes an integer number.\footnote{Fortran intrinsic types include \keyword{logical}, \keyword{integer}, \keyword{real}, \keyword{complex}, and \keyword{character} data.}
+    Similarly, \keyword{integer} denotes an integer number.\footnote{Fortran intrinsic types include \keyword{logical}, \keyword{integer}, \keyword{real}, \keyword{complex}, and \keyword{character} data. Modern Fortran also gives you the ability to define your own datatypes.}
     Not specifying a size generally defaults to 4-byte precision.
     \keyword{implicit none}\index{Fortran!implicit none@\keyword{implicit none}} prevents Fortran from trying to infer the type from the variable name, which is a major source of bugs---\emph{always include this!}
   \item The attribute \keyword{parameter}\index{Fortran!parameter@\keyword{parameter}} specifies that we are declaring a constant.
@@ -61,14 +63,14 @@
     It is also possible to specify the precision as a suffix: \texttt{1.0\_4} for single and \texttt{1.0\_8} for double precision.
     This also works for integers.
   \item \texttt{\keyword{integer} :: fibonacci(N)} allocates an array of 20
-    integers, with the array\index{Fortran!arrays} index\footnote{Array indices can start at any integer by replacing \texttt{N} with a lower and upper bound separated with a colon.} running from 1 to 20.
+    integers, with the array\index{Fortran!arrays} index\footnote{Array indices can start at any integer by replacing \texttt{N} with a lower and upper bound separated with a colon. Thus, \lstinline$real :: myArray(-312:74)$ means \texttt{myArray} starts at index -312 and runs through index 74.} running from 1 to 20.
   \item `\texttt{*}' is multiplication, `\texttt{**}' is exponentiation.
   \item The \keyword{print} statement on line 24 contains the format code\index{Fortran!format codes} \str{"(4I6)"}.
-    This tells Fortran to print 4 records of integer type per line, each taking up 6 characters.
-    Format strings for other datatypes include E$w.d$ (real -- decimal form), ES$w.d$ (real -- scientific form), EN$w.d$ (real -- engineering form), L$w$ (logical), and A (characters). Here, $w$ gives the width of a record and $d$ gives the number of places right of the decimal.
+    This tells Fortran to print 4 records of integer type, each having a width of 6 characters (including spaces), per line. 
+    Format strings for other datatypes include \texttt{Ew.d} (real -- decimal form), \texttt{ESw.d} (real -- scientific form), \texttt{ENw.d} (real -- engineering form), \texttt{Lw} (logical), and \texttt{A} (characters). Here, \texttt{w} gives the width of a record and \texttt{d} gives the number of places right of the decimal.
   \item Comments in Fortran start with `\texttt{!}' and last until the end of the line.
   \item Dividing integers \textcolor{red}{\textbf{results in an integer}}\index{Fortran!integer division}, so \texttt{3 / 2 == 1} instead of 1.5 as you might expect.
-    Multiplying by \texttt{1d0} on line 27 forces Fortran to do a double-precision floating-point calculation.
+    Multiplying by \texttt{1d0} on line 28 forces Fortran to do a double-precision floating-point calculation.
 \end{itemize}
 Now we compile and run the program.
 Compiling means translating the Fortran source code into machine code (processor instructions).
@@ -101,7 +103,7 @@
     The downside is that it can result in executables that will not run on a different machine.
   \item \texttt{-O3}\index{compiler flags!-O3} turns on all optimizations.
     This increases the compilation time significantly, although it should still be fast enough for the programs you'll write in ICCP.
-    The runtime of your program, on the other hand, will dramatically decrease.
+    The run time of your program, on the other hand, will dramatically decrease.
     The only reason not to use this flag is that it might interfere with the debugger (see below).
   \item A possible additional optimization flag is \texttt{-ffast-math}\index{compiler flags!-ffast-math}.
     This flag enables floating-point optimizations which might reduce accuracy or result in incorrect behavior, especially in situations such as divide-by-zero.