--- trunk/tengDissertation/Appendix.tex 2006/04/24 18:49:04 2729 +++ 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}