--- trunk/tengDissertation/Appendix.tex	2006/04/05 03:44:32	2693
+++ trunk/tengDissertation/Appendix.tex	2006/04/24 18:49:32	2730
@@ -76,12 +76,354 @@ that you are operating on.
 
 \section{\label{appendixSection:analysisFramework}Analysis Framework}
 
-\section{\label{appendixSection:hierarchy}Hierarchy}
+\section{\label{appendixSection:concepts}Concepts}
 
-\subsection{\label{appendixSection:selectionSyntax}Selection Syntax}
+OOPSE manipulates both traditional atoms as well as some objects
+that {\it behave like atoms}.  These objects can be rigid
+collections of atoms or atoms which have orientational degrees of
+freedom.  Here is a diagram of the class heirarchy:
 
-\subsection{\label{appendixSection:hydrodynamics}Hydrodynamics}
+\begin{figure}
+\centering
+\includegraphics[width=3in]{heirarchy.pdf}
+\caption[Class heirarchy for StuntDoubles in {\sc oopse}-3.0]{ \\
+The class heirarchy of StuntDoubles in {\sc oopse}-3.0. The
+selection syntax allows the user to select any of the objects that
+are descended from a StuntDouble.} \label{oopseFig:heirarchy}
+\end{figure}
 
-\subsection{\label{appendixSection:staticProps}Static Properties}
+\begin{itemize}
+\item A {\bf StuntDouble} is {\it any} object that can be manipulated by the
+integrators and minimizers.
+\item An {\bf Atom} is a fundamental point-particle that can be moved around during a simulation.
+\item A {\bf DirectionalAtom} is an atom which has {\it orientational} as well as translational degrees of freedom.
+\item A {\bf RigidBody} is a collection of {\bf Atom}s or {\bf
+DirectionalAtom}s which behaves as a single unit.
+\end{itemize}
 
-\subsection{\label{appendixSection:dynamicProps}Dynamics Properties}
+Every Molecule, Atom and DirectionalAtom in {\sc oopse} have their
+own names which are specified in the {\tt .md} file. In contrast,
+RigidBodies are denoted by their membership and index inside a
+particular molecule: [MoleculeName]\_RB\_[index] (the contents
+inside the brackets depend on the specifics of the simulation). The
+names of rigid bodies are generated automatically. For example, the
+name of the first rigid body in a DMPC molecule is DMPC\_RB\_0.
+
+\section{\label{appendixSection:syntax}Syntax of the Select Command}
+
+The most general form of the select command is: {\tt select {\it
+expression}}
+
+This expression represents an arbitrary set of StuntDoubles (Atoms
+or RigidBodies) in {\sc oopse}. Expressions are composed of either
+name expressions, index expressions, predefined sets, user-defined
+expressions, comparison operators, within expressions, or logical
+combinations of the above expression types. Expressions can be
+combined using parentheses and the Boolean operators.
+
+\subsection{\label{appendixSection:logical}Logical expressions}
+
+The logical operators allow complex queries to be constructed out of
+simpler ones using the standard boolean connectives {\bf and}, {\bf
+or}, {\bf not}. Parentheses can be used to alter the precedence of
+the operators.
+
+\begin{center}
+\begin{tabular}{|ll|}
+\hline
+{\bf logical operator} & {\bf equivalent operator}  \\
+\hline
+and & ``\&'', ``\&\&'' \\
+or & ``$|$'', ``$||$'', ``,'' \\
+not & ``!''  \\
+\hline
+\end{tabular}
+\end{center}
+
+\subsection{\label{appendixSection:name}Name expressions}
+
+\begin{center}
+\begin{tabular}{|llp{3in}|}
+\hline {\bf type of expression} & {\bf examples} & {\bf translation
+of
+examples} \\
+\hline expression without ``.'' & select DMPC & select all
+StuntDoubles
+belonging to all DMPC molecules \\
+ & select C* & select all atoms which have atom types beginning with C
+\\
+ & select DMPC\_RB\_* & select all RigidBodies in DMPC molecules (but
+only select the rigid bodies, and not the atoms belonging to them). \\
+\hline expression has one ``.'' & select TIP3P.O\_TIP3P & select the
+O\_TIP3P
+atoms belonging to TIP3P molecules \\
+ & select DMPC\_RB\_O.PO4 & select the PO4 atoms belonging to
+the first
+RigidBody in each DMPC molecule \\
+ & select DMPC.20 & select the twentieth StuntDouble in each DMPC
+molecule \\
+\hline expression has two ``.''s & select DMPC.DMPC\_RB\_?.* &
+select all atoms
+belonging to all rigid bodies within all DMPC molecules \\
+\hline
+\end{tabular}
+\end{center}
+
+\subsection{\label{appendixSection:index}Index expressions}
+
+\begin{center}
+\begin{tabular}{|lp{4in}|}
+\hline
+{\bf examples} & {\bf translation of examples} \\
+\hline
+select 20 & select all of the StuntDoubles belonging to Molecule 20 \\
+select 20 to 30 & select all of the StuntDoubles belonging to
+molecules which have global indices between 20 (inclusive) and 30
+(exclusive) \\
+\hline
+\end{tabular}
+\end{center}
+
+\subsection{\label{appendixSection:predefined}Predefined sets}
+
+\begin{center}
+\begin{tabular}{|ll|}
+\hline
+{\bf keyword} & {\bf description} \\
+\hline
+all & select all StuntDoubles \\
+none & select none of the StuntDoubles \\
+\hline
+\end{tabular}
+\end{center}
+
+\subsection{\label{appendixSection:userdefined}User-defined expressions}
+
+Users can define arbitrary terms to represent groups of
+StuntDoubles, and then use the define terms in select commands. The
+general form for the define command is: {\bf define {\it term
+expression}}
+
+Once defined, the user can specify such terms in boolean expressions
+
+{\tt define SSDWATER SSD or SSD1 or SSDRF}
+
+{\tt select SSDWATER}
+
+\subsection{\label{appendixSection:comparison}Comparison expressions}
+
+StuntDoubles can be selected by using comparision operators on their
+properties. The general form for the comparison command is: a
+property name, followed by a comparision operator and then a number.
+
+\begin{center}
+\begin{tabular}{|l|l|}
+\hline
+{\bf property} & mass, charge \\
+{\bf comparison operator} & ``$>$'', ``$<$'', ``$=$'', ``$>=$'',
+``$<=$'', ``$!=$'' \\
+\hline
+\end{tabular}
+\end{center}
+
+For example, the phrase {\tt select mass > 16.0 and charge < -2}
+wouldselect StuntDoubles which have mass greater than 16.0 and
+charges less than -2.
+
+\subsection{\label{appendixSection:within}Within expressions}
+
+The ``within'' keyword allows the user to select all StuntDoubles
+within the specified distance (in Angstroms) from a selection,
+including the selected atom itself. The general form for within
+selection is: {\tt select within(distance, expression)}
+
+For example, the phrase {\tt select within(2.5, PO4 or NC4)} would
+select all StuntDoubles which are within 2.5 angstroms of PO4 or NC4
+atoms.
+
+\section{\label{appendixSection:tools}Tools which use the selection command}
+
+\subsection{\label{appendixSection:Dump2XYZ}Dump2XYZ}
+
+Dump2XYZ can transform an OOPSE dump file into a xyz file which can
+be opened by other molecular dynamics viewers such as Jmol and VMD.
+The options available for Dump2XYZ are as follows:
+
+
+\begin{longtable}[c]{|EFG|}
+\caption{Dump2XYZ Command-line Options}
+\\ \hline
+{\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
+\endhead
+\hline
+\endfoot
+  -h & {\tt -{}-help} &                        Print help and exit \\
+  -V & {\tt -{}-version} &                     Print version and exit \\
+  -i & {\tt -{}-input=filename}  &             input dump file \\
+  -o & {\tt -{}-output=filename} &             output file name \\
+  -n & {\tt -{}-frame=INT}   &                 print every n frame  (default=`1') \\
+  -w & {\tt -{}-water}       &                 skip the the waters  (default=off) \\
+  -m & {\tt -{}-periodicBox} &                 map to the periodic box  (default=off)\\
+  -z & {\tt -{}-zconstraint}  &                replace the atom types of zconstraint molecules  (default=off) \\
+  -r & {\tt -{}-rigidbody}  &                  add a pseudo COM atom to rigidbody  (default=off) \\
+  -t & {\tt -{}-watertype} &                   replace the atom type of water model (default=on) \\
+  -b & {\tt -{}-basetype}  &                   using base atom type  (default=off) \\
+     & {\tt -{}-repeatX=INT}  &                 The number of images to repeat in the x direction  (default=`0') \\
+     & {\tt -{}-repeatY=INT} &                 The number of images to repeat in the y direction  (default=`0') \\
+     &  {\tt -{}-repeatZ=INT}  &                The number of images to repeat in the z direction  (default=`0') \\
+  -s & {\tt -{}-selection=selection script} & By specifying {\tt -{}-selection}=``selection command'' with Dump2XYZ, the user can select an arbitrary set of StuntDoubles to be
+converted. \\
+     & {\tt -{}-originsele} & By specifying {\tt -{}-originsele}=``selection command'' with Dump2XYZ, the user can re-center the origin of the system around a specific StuntDouble \\
+     & {\tt -{}-refsele} &  In order to rotate the system, {\tt -{}-originsele} and {\tt -{}-refsele} must be given to define the new coordinate set. A StuntDouble which contains a dipole (the direction of the dipole is always (0, 0, 1) in body frame) is specified by {\tt -{}-originsele}. The new x-z plane is defined by the direction of the dipole and the StuntDouble is specified by {\tt -{}-refsele}.
+\end{longtable}
+
+
+\subsection{\label{appendixSection:StaticProps}StaticProps}
+
+{\tt StaticProps} can compute properties which are averaged over
+some or all of the configurations that are contained within a dump
+file. The most common example of a static property that can be
+computed is the pair distribution function between atoms of type $A$
+and other atoms of type $B$, $g_{AB}(r)$.  StaticProps can also be
+used to compute the density distributions of other molecules in a
+reference frame {\it fixed to the body-fixed reference frame} of a
+selected atom or rigid body.
+
+There are five seperate radial distribution functions availiable in
+OOPSE. Since every radial distrbution function invlove the
+calculation between pairs of bodies, {\tt -{}-sele1} and {\tt
+-{}-sele2} must be specified to tell StaticProps which bodies to
+include in the calculation.
+
+\begin{description}
+\item[{\tt -{}-gofr}] Computes the pair distribution function,
+\begin{equation*}
+g_{AB}(r) = \frac{1}{\rho_B}\frac{1}{N_A} \langle \sum_{i \in A}
+\sum_{j \in B} \delta(r - r_{ij}) \rangle
+\end{equation*}
+\item[{\tt -{}-r\_theta}] Computes the angle-dependent pair distribution
+function. The angle is defined by the intermolecular vector
+$\vec{r}$ and $z$-axis of DirectionalAtom A,
+\begin{equation*}
+g_{AB}(r, \cos \theta) = \frac{1}{\rho_B}\frac{1}{N_A} \langle
+\sum_{i \in A} \sum_{j \in B} \delta(r - r_{ij}) \delta(\cos
+\theta_{ij} - \cos \theta)\rangle
+\end{equation*}
+\item[{\tt -{}-r\_omega}] Computes the angle-dependent pair distribution
+function. The angle is defined by the $z$-axes of the two
+DirectionalAtoms A and B.
+\begin{equation*}
+g_{AB}(r, \cos \omega) = \frac{1}{\rho_B}\frac{1}{N_A} \langle
+\sum_{i \in A} \sum_{j \in B} \delta(r - r_{ij}) \delta(\cos
+\omega_{ij} - \cos \omega)\rangle
+\end{equation*}
+\item[{\tt -{}-theta\_omega}] Computes the pair distribution in the angular
+space $\theta, \omega$ defined by the two angles mentioned above.
+\begin{equation*}
+g_{AB}(\cos\theta, \cos \omega) = \frac{1}{\rho_B}\frac{1}{N_A}
+\langle \sum_{i \in A} \sum_{j \in B} \langle \delta(\cos
+\theta_{ij} - \cos \theta) \delta(\cos \omega_{ij} - \cos
+\omega)\rangle
+\end{equation*}
+\item[{\tt -{}-gxyz}] Calculates the density distribution of particles of type
+B in the body frame of particle A. Therefore, {\tt -{}-originsele}
+and {\tt -{}-refsele} must be given to define A's internal
+coordinate set as the reference frame for the calculation.
+\end{description}
+
+The vectors (and angles) associated with these angular pair
+distribution functions are most easily seen in the figure below:
+
+\begin{figure}
+\centering
+\includegraphics[width=3in]{definition.pdf}
+\caption[Definitions of the angles between directional objects]{ \\
+Any two directional objects (DirectionalAtoms and RigidBodies) have
+a set of two angles ($\theta$, and $\omega$) between the z-axes of
+their body-fixed frames.} \label{oopseFig:gofr}
+\end{figure}
+
+The options available for {\tt StaticProps} are as follows:
+\begin{longtable}[c]{|EFG|}
+\caption{StaticProps Command-line Options}
+\\ \hline
+{\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
+\endhead
+\hline
+\endfoot
+  -h& {\tt -{}-help}                    &  Print help and exit \\
+  -V& {\tt -{}-version}                 &  Print version and exit \\
+  -i& {\tt -{}-input=filename}          &  input dump file \\
+  -o& {\tt -{}-output=filename}         &  output file name \\
+  -n& {\tt -{}-step=INT}                &  process every n frame  (default=`1') \\
+  -r& {\tt -{}-nrbins=INT}              &  number of bins for distance  (default=`100') \\
+  -a& {\tt -{}-nanglebins=INT}          &  number of bins for cos(angle)  (default= `50') \\
+  -l& {\tt -{}-length=DOUBLE}           &  maximum length (Defaults to 1/2 smallest length of first frame) \\
+    & {\tt -{}-sele1=selection script}   & select the first StuntDouble set \\
+    & {\tt -{}-sele2=selection script}   & select the second StuntDouble set \\
+    & {\tt -{}-sele3=selection script}   & select the third StuntDouble set \\
+    & {\tt -{}-refsele=selection script} & select reference (can only be used with {\tt -{}-gxyz}) \\
+    & {\tt -{}-molname=STRING}           & molecule name \\
+    & {\tt -{}-begin=INT}                & begin internal index \\
+    & {\tt -{}-end=INT}                  & end internal index \\
+\hline
+\multicolumn{3}{|l|}{One option from the following group of options is required:} \\
+\hline
+    &  {\tt -{}-gofr}                    &  $g(r)$ \\
+    &  {\tt -{}-r\_theta}                 &  $g(r, \cos(\theta))$ \\
+    &  {\tt -{}-r\_omega}                 &  $g(r, \cos(\omega))$ \\
+    &  {\tt -{}-theta\_omega}             &  $g(\cos(\theta), \cos(\omega))$ \\
+    &  {\tt -{}-gxyz}                    &  $g(x, y, z)$ \\
+    &  {\tt -{}-p2}                      &  $P_2$ order parameter ({\tt -{}-sele1} and {\tt -{}-sele2} must be specified) \\
+    &  {\tt -{}-scd}                     &  $S_{CD}$ order parameter(either {\tt -{}-sele1}, {\tt -{}-sele2}, {\tt -{}-sele3} are specified or {\tt -{}-molname}, {\tt -{}-begin}, {\tt -{}-end} are specified) \\
+    &  {\tt -{}-density}                 &  density plot ({\tt -{}-sele1} must be specified) \\
+    &  {\tt -{}-slab\_density}           &  slab density ({\tt -{}-sele1} must be specified)
+\end{longtable}
+
+\subsection{\label{appendixSection:DynamicProps}DynamicProps}
+
+{\tt DynamicProps} computes time correlation functions from the
+configurations stored in a dump file.  Typical examples of time
+correlation functions are the mean square displacement and the
+velocity autocorrelation functions.   Once again, the selection
+syntax can be used to specify the StuntDoubles that will be used for
+the calculation.  A general time correlation function can be thought
+of as:
+\begin{equation}
+C_{AB}(t) = \langle \vec{u}_A(t) \cdot \vec{v}_B(0) \rangle
+\end{equation}
+where $\vec{u}_A(t)$ is a vector property associated with an atom of
+type $A$ at time $t$, and $\vec{v}_B(t^{\prime})$ is a different
+vector property associated with an atom of type $B$ at a different
+time $t^{\prime}$.  In most autocorrelation functions, the vector
+properties ($\vec{v}$ and $\vec{u}$) and the types of atoms ($A$ and
+$B$) are identical, and the three calculations built in to {\tt
+DynamicProps} make these assumptions.  It is possible, however, to
+make simple modifications to the {\tt DynamicProps} code to allow
+the use of {\it cross} time correlation functions (i.e. with
+different vectors).  The ability to use two selection scripts to
+select different types of atoms is already present in the code.
+
+The options available for DynamicProps are as follows:
+\begin{longtable}[c]{|EFG|}
+\caption{DynamicProps Command-line Options}
+\\ \hline
+{\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
+\endhead
+\hline
+\endfoot
+  -h& {\tt -{}-help}                   & Print help and exit \\
+  -V& {\tt -{}-version}                & Print version and exit \\
+  -i& {\tt -{}-input=filename}         & input dump file \\
+  -o& {\tt -{}-output=filename}        & output file name \\
+    & {\tt -{}-sele1=selection script} & select first StuntDouble set \\
+    & {\tt -{}-sele2=selection script} & select second StuntDouble set (if sele2 is not set, use script from sele1) \\
+\hline
+\multicolumn{3}{|l|}{One option from the following group of options is required:} \\
+\hline
+  -r& {\tt -{}-rcorr}                  & compute mean square displacement \\
+  -v& {\tt -{}-vcorr}                  & compute velocity correlation function \\
+  -d& {\tt -{}-dcorr}                  & compute dipole correlation function
+\end{longtable}
+
+\subsection{\label{appendixSection:hydrodynamics}Hydrodynamics}
