[ViewVC] Diff of: group/trunk/tengDissertation/Appendix.tex

Comparing trunk/tengDissertation/Appendix.tex (file contents):
Revision 2688 by tim, Tue Apr 4 04:32:24 2006 UTC vs.
Revision 2836 by tim, Fri Jun 9 02:12:42 2006 UTC

-<
+\chapter{\label{chapt:appendix}APPENDIX}
->
+\appendix
->
+\chapter{\label{chapt:oopse}Object-Oriented Parallel Simulation Engine}
+Designing object-oriented software is hard, and designing reusable
+object-oriented scientific software is even harder. Absence of
+applying modern software development practices is the bottleneck of
-<
+Scientific Computing community\cite{wilson}. For instance, in the
-<
+last 20 years , there are quite a few MD packages that were
->
+Scientific Computing community\cite{Wilson2006}. For instance, in
->
+the last 20 years , there are quite a few MD packages that were
+developed to solve common MD problems and perform robust simulations
+. However, many of the codes are legacy programs that are either
+poorly organized or extremely complex. Usually, these packages were
+coordination to enforce design and programming guidelines. Moreover,
+most MD programs also suffer from missing design and implement
+documents which is crucial to the maintenance and extensibility.
-+
+Along the way of studying structural and dynamic processes in
-+
+condensed phase systems like biological membranes and nanoparticles,
-+
+we developed and maintained an Object-Oriented Parallel Simulation
-+
+Engine ({\sc OOPSE}). This new molecular dynamics package has some
-+
+unique features
-+
+\begin{enumerate}
-+
+  \item {\sc OOPSE} performs Molecular Dynamics (MD) simulations on non-standard
-+
+atom types (transition metals, point dipoles, sticky potentials,
-+
+Gay-Berne ellipsoids, or other "lumpy"atoms with orientational
-+
+degrees of freedom), as well as rigid bodies.
-+
+  \item {\sc OOPSE} uses a force-based decomposition algorithm using MPI on cheap
-+
+Beowulf clusters to obtain very efficient parallelism.
-+
+  \item {\sc OOPSE} integrates the equations of motion using advanced methods for
-+
+orientational dynamics in NVE, NVT, NPT, NPAT, and NP$\gamma$T
-+
+ensembles.
-+
+  \item {\sc OOPSE} can carry out simulations on metallic systems using the
-+
+Embedded Atom Method (EAM) as well as the Sutton-Chen potential.
-+
+  \item {\sc OOPSE} can perform simulations on Gay-Berne liquid crystals.
-+
+  \item  {\sc OOPSE} can simulate systems containing the extremely efficient
-+
+extended-Soft Sticky Dipole (SSD/E) model for water.
-+
+\end{enumerate}
-+
+\section{\label{appendixSection:architecture }Architecture}
-+
-+
+Mainly written by \texttt{C/C++} and \texttt{Fortran90}, {\sc OOPSE}
-+
+uses C++ Standard Template Library (STL) and fortran modules as the
-+
+foundation. As an extensive set of the STL and Fortran90 modules,
-+
+{\sc Base Classes} provide generic implementations of mathematical
-+
+objects (e.g., matrices, vectors, polynomials, random number
-+
+generators) and advanced data structures and algorithms(e.g., tuple,
-+
+bitset, generic data, string manipulation). The molecular data
-+
+structures for the representation of atoms, bonds, bends, torsions,
-+
+rigid bodies and molecules \textit{etc} are contained in the {\sc
-+
+Kernel} which is implemented with {\sc Base Classes} and are
-+
+carefully designed to provide maximum extensibility and flexibility.
-+
+The functionality required for applications is provide by the third
-+
+layer which contains Input/Output, Molecular Mechanics and Structure
-+
+modules. Input/Output module not only implements general methods for
-+
+file handling, but also defines a generic force field interface.
-+
+Another important component of Input/Output module is the meta-data
-+
+file parser, which is rewritten using ANother Tool for Language
-+
+Recognition(ANTLR)\cite{Parr1995, Schaps1999} syntax. The Molecular
-+
+Mechanics module consists of energy minimization and a wide
-+
+varieties of integration methods(see Chap.~\ref{chapt:methodology}).
-+
+The structure module contains a flexible and powerful selection
-+
+library which syntax is elaborated in
-+
+Sec.~\ref{appendixSection:syntax}. The top layer is made of the main
-+
+program of the package, \texttt{oopse} and it corresponding parallel
-+
+version \texttt{oopse\_MPI}, as well as other useful utilities, such
-+
+as \texttt{StatProps} (see Sec.~\ref{appendixSection:StaticProps}),
-+
+\texttt{DynamicProps} (see
-+
+Sec.~\ref{appendixSection:appendixSection:DynamicProps}),
-+
+\texttt{Dump2XYZ} (see
-+
+Sec.~\ref{appendixSection:appendixSection:Dump2XYZ}), \texttt{Hydro}
-+
+(see Sec.~\ref{appendixSection:appendixSection:hydrodynamics})
-+
+\textit{etc}.
-+
-+
+\begin{figure}
-+
+\centering
-+
+\includegraphics[width=\linewidth]{architecture.eps}
-+
+\caption[The architecture of {\sc OOPSE}] {Overview of the structure
-+
+of {\sc OOPSE}} \label{appendixFig:architecture}
-+
+\end{figure}
-+
+\section{\label{appendixSection:desginPattern}Design Pattern}
+Design patterns are optimal solutions to commonly-occurring problems
+in software design. Although originated as an architectural concept
-<
+for buildings and towns by Christopher Alexander \cite{alexander},
-<
+software patterns first became popular with the wide acceptance of
-<
+the book, Design Patterns: Elements of Reusable Object-Oriented
-<
+Software \cite{gamma94}. Patterns reflect the experience, knowledge
-<
+and insights of developers who have successfully used these patterns
-<
+in their own work. Patterns are reusable. They provide a ready-made
-<
+solution that can be adapted to different problems as necessary.
-<
+Pattern are expressive. they provide a common vocabulary of
-<
+solutions that can express large solutions succinctly.
->
+for buildings and towns by Christopher Alexander
->
+\cite{Alexander1987}, software patterns first became popular with
->
+the wide acceptance of the book, Design Patterns: Elements of
->
+Reusable Object-Oriented Software \cite{Gamma1994}. Patterns reflect
->
+the experience, knowledge and insights of developers who have
->
+successfully used these patterns in their own work. Patterns are
->
+reusable. They provide a ready-made solution that can be adapted to
->
+different problems as necessary. Pattern are expressive. they
->
+provide a common vocabulary of solutions that can express large
->
+solutions succinctly.
+Patterns are usually described using a format that includes the
+following information:
+As one of the latest advanced techniques emerged from
+object-oriented community, design patterns were applied in some of
-<
+the modern scientific software applications, such as JMol, OOPSE
-<
+\cite{Meineke05} and PROTOMOL \cite{} \textit{etc}.
->
+the modern scientific software applications, such as JMol, {\sc
->
+OOPSE}\cite{Meineke05} and PROTOMOL\cite{Matthey05} \textit{etc}.
->
+The following sections enumerates some of the patterns used in {\sc
->
+OOPSE}.
-+
+\subsection{\label{appendixSection:singleton}Singleton}
-+
-+
+The Singleton pattern not only provides a mechanism to restrict
-+
+instantiation of a class to one object, but also provides a global
-+
+point of access to the object. Currently implemented as a global
-+
+variable, the logging utility which reports error and warning
-+
+messages to the console in {\sc OOPSE} is a good candidate for
-+
+applying the Singleton pattern to avoid the global namespace
-+
+pollution.Although the singleton pattern can be implemented in
-+
+various ways  to account for different aspects of the software
-+
+designs, such as lifespan control \textit{etc}, we only use the
-+
+static data approach in {\sc OOPSE}. IntegratorFactory class is
-+
+declared as
-+
-+
+\begin{lstlisting}[float,caption={[A classic Singleton design pattern implementation(I)] The declaration of of simple Singleton pattern.},label={appendixScheme:singletonDeclaration}]
-+
-+
+class IntegratorFactory {
-+
+public:
-+
+  static IntegratorFactory*
-+
+  getInstance();
-+
+protected:
-+
+  IntegratorFactory();
-+
+private:
-+
+  static IntegratorFactory* instance_;
-+
+};
-+
-+
+\end{lstlisting}
-+
-+
+The corresponding implementation is
-+
-+
+\begin{lstlisting}[float,caption={[A classic implementation of Singleton design pattern (II)] The implementation of simple Singleton pattern.},label={appendixScheme:singletonImplementation}]
-+
-+
+IntegratorFactory::instance_ = NULL;
-+
-+
+IntegratorFactory* getInstance() {
-+
+  if (instance_ == NULL){
-+
+    instance_ = new IntegratorFactory;
-+
+  }
-+
+  return instance_;
-+
+}
-+
-+
+\end{lstlisting}
-+
-+
+Since constructor is declared as protected, a client can not
-+
+instantiate IntegratorFactory directly. Moreover, since the member
-+
+function getInstance serves as the only entry of access to
-+
+IntegratorFactory, this approach fulfills the basic requirement, a
-+
+single instance. Another consequence of this approach is the
-+
+automatic destruction since static data are destroyed upon program
-+
+termination.
-+
+\subsection{\label{appendixSection:factoryMethod}Factory Method}
-–
+The Factory Method pattern is a creational pattern which deals with
-–
+the problem of creating objects without specifying the exact class
-–
+of object that will be created. Factory Method solves this problem
-–
+by defining a separate method for creating the objects, which
-–
+subclasses can then override to specify the derived type of product
-–
+that will be created.
-+
+Categoried as a creational pattern, the Factory Method pattern deals
-+
+with the problem of creating objects without specifying the exact
-+
+class of object that will be created. Factory Method is typically
-+
+implemented by delegating the creation operation to the subclasses.
-+
+Parameterized Factory pattern where factory method (
-+
+createIntegrator member function) creates products based on the
-+
+identifier (see List.~\ref{appendixScheme:factoryDeclaration}). If
-+
+the identifier has been already registered, the factory method will
-+
+invoke the corresponding creator (see List.~\ref{integratorCreator})
-+
+which utilizes the modern C++ template technique to avoid excess
-+
+subclassing.
-+
+\begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (I)]Source code of IntegratorFactory class.},label={appendixScheme:factoryDeclaration}]
-+
-+
+class IntegratorFactory {
-+
+public:
-+
+  typedef std::map<string, IntegratorCreator*> CreatorMapType;
-+
-+
+  bool registerIntegrator(IntegratorCreator* creator) {
-+
+    return creatorMap_.insert(creator->getIdent(), creator).second;
-+
+  }
-+
-+
+  Integrator* createIntegrator(const string& id, SimInfo* info) {
-+
+    Integrator* result = NULL;
-+
+    CreatorMapType::iterator i = creatorMap_.find(id);
-+
+    if (i != creatorMap_.end()) {
-+
+      result = (i->second)->create(info);
-+
+    }
-+
+    return result;
-+
+  }
-+
-+
+private:
-+
+  CreatorMapType creatorMap_;
-+
+};
-+
+\end{lstlisting}
-+
-+
+\begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (III)]Source code of creator classes.},label={appendixScheme:integratorCreator}]
-+
-+
+class IntegratorCreator {
-+
+public:
-+
+    IntegratorCreator(const string& ident) : ident_(ident) {}
-+
-+
+    const string& getIdent() const { return ident_; }
-+
-+
+    virtual Integrator* create(SimInfo* info) const = 0;
-+
-+
+private:
-+
+    string ident_;
-+
+};
-+
-+
+template<class ConcreteIntegrator>
-+
+class IntegratorBuilder : public IntegratorCreator {
-+
+public:
-+
+  IntegratorBuilder(const string& ident)
-+
+                   : IntegratorCreator(ident) {}
-+
+  virtual  Integrator* create(SimInfo* info) const {
-+
+    return new ConcreteIntegrator(info);
-+
+  }
-+
+};
-+
+\end{lstlisting}
-+
+\subsection{\label{appendixSection:visitorPattern}Visitor}
-–
+The purpose of the Visitor Pattern is to encapsulate an operation
-–
+that you want to perform on the elements of a data structure. In
-–
+this way, you can change the operation being performed on a
-–
+structure without the need of changing the classes of the elements
-–
+that you are operating on.
-+
+The visitor pattern is designed to decouple the data structure and
-+
+algorithms used upon them by collecting related operation from
-+
+element classes into other visitor classes, which is equivalent to
-+
+adding virtual functions into a set of classes without modifying
-+
+their interfaces. Fig.~\ref{appendixFig:visitorUML} demonstrates the
-+
+structure of Visitor pattern which is used extensively in {\tt
-+
+Dump2XYZ}. In order to convert an OOPSE dump file, a series of
-+
+distinct operations are performed on different StuntDoubles (See the
-+
+class hierarchy in Fig.~\ref{oopseFig:hierarchy} and the declaration
-+
+in List.~\ref{appendixScheme:element}). Since the hierarchies
-+
+remains stable, it is easy to define a visit operation (see
-+
+List.~\ref{appendixScheme:visitor}) for each class of StuntDouble.
-+
+Note that using Composite pattern\cite{Gamma1994}, CompositVisitor
-+
+manages a priority visitor list and handles the execution of every
-+
+visitor in the priority list on different StuntDoubles.
-<
+\subsection{\label{appendixSection:templateMethod}Template Method}
->
+\begin{figure}
->
+\centering
->
+\includegraphics[width=\linewidth]{visitor.eps}
->
+\caption[The UML class diagram of Visitor patten] {The UML class
->
+diagram of Visitor patten.} \label{appendixFig:visitorUML}
->
+\end{figure}
-+
+%\begin{figure}
-+
+%\centering
-+
+%\includegraphics[width=\linewidth]{hierarchy.eps}
-+
+%\caption[Class hierarchy for ojects in {\sc OOPSE}]{ A diagram of
-+
+%the class hierarchy.
-+
+%\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}
-+
+%} \label{oopseFig:hierarchy}
-+
+%\end{figure}
-<
+\section{\label{appendixSection:analysisFramework}Analysis Framework}
->
+\begin{lstlisting}[float,caption={[The implementation of Visitor pattern (II)]Source code of the element classes.},label={appendixScheme:element}]
-<
+\section{\label{appendixSection:hierarchy}Hierarchy}
->
+class StuntDouble { public:
->
+  virtual void accept(BaseVisitor* v) = 0;
->
+};
-<
+\subsection{\label{appendixSection:selectionSyntax}Selection Syntax}
->
+class Atom: public StuntDouble { public:
->
+  virtual void accept{BaseVisitor* v*} {
->
+    v->visit(this);
->
+  }
->
+};
-<
+\subsection{\label{appendixSection:hydrodynamics}Hydrodynamics}
->
+class DirectionalAtom: public Atom { public:
->
+  virtual void accept{BaseVisitor* v*} {
->
+    v->visit(this);
->
+  }
->
+};
-<
+\subsection{\label{appendixSection:staticProps}Static Properties}
->
+class RigidBody: public StuntDouble { public:
->
+  virtual void accept{BaseVisitor* v*} {
->
+    v->visit(this);
->
+  }
->
+};
-<
+\subsection{\label{appendixSection:dynamicProps}Dynamics Properties}
->
+\end{lstlisting}
->
->
+\begin{lstlisting}[float,caption={[The implementation of Visitor pattern (I)]Source code of the visitor classes.},label={appendixScheme:visitor}]
->
->
+class BaseVisitor{
->
+public:
->
+  virtual void visit(Atom* atom);
->
+  virtual void visit(DirectionalAtom* datom);
->
+  virtual void visit(RigidBody* rb);
->
+};
->
->
+class BaseAtomVisitor:public BaseVisitor{ public:
->
+  virtual void visit(Atom* atom);
->
+  virtual void visit(DirectionalAtom* datom);
->
+  virtual void visit(RigidBody* rb);
->
+};
->
->
+class SSDAtomVisitor:public BaseAtomVisitor{ public:
->
+  virtual void visit(Atom* atom);
->
+  virtual void visit(DirectionalAtom* datom);
->
+  virtual void visit(RigidBody* rb);
->
+};
->
->
+class CompositeVisitor: public BaseVisitor {
->
+public:
->
->
+  typedef list<pair<BaseVisitor*, int> > VistorListType;
->
+  typedef VistorListType::iterator VisitorListIterator;
->
+  virtual void visit(Atom* atom) {
->
+    VisitorListIterator i;
->
+    BaseVisitor* curVisitor;
->
+    for(i = visitorList.begin();i != visitorList.end();++i) {
->
+      atom->accept(*i);
->
+    }
->
+  }
->
->
+  virtual void visit(DirectionalAtom* datom) {
->
+    VisitorListIterator i;
->
+    BaseVisitor* curVisitor;
->
+    for(i = visitorList.begin();i != visitorList.end();++i) {
->
+      atom->accept(*i);
->
+    }
->
+  }
->
->
+  virtual void visit(RigidBody* rb) {
->
+    VisitorListIterator i;
->
+    std::vector<Atom*> myAtoms;
->
+    std::vector<Atom*>::iterator ai;
->
+    myAtoms = rb->getAtoms();
->
+    for(i = visitorList.begin();i != visitorList.end();++i) {{
->
+      rb->accept(*i);
->
+      for(ai = myAtoms.begin(); ai != myAtoms.end(); ++ai){
->
+        (*ai)->accept(*i);
->
+    }
->
+  }
->
->
+  void addVisitor(BaseVisitor* v, int priority);
->
->
+  protected:
->
+    VistorListType visitorList;
->
+};
->
->
+\end{lstlisting}
->
->
+\section{\label{appendixSection:concepts}Concepts}
->
->
+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.  A diagram of the class hierarchy is illustrated in
->
+Fig.~\ref{oopseFig:hierarchy}. 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{2in}|}
->
+\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}
->
+would select 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:analysisFramework}Analysis Framework}
->
->
+\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)$.  {\tt 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.eps}
->
+\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}
->
->
+Due to the fact that the selected StuntDoubles from two selections
->
+may be overlapped, {\tt StaticProps} performs the calculation in
->
+three stages which are illustrated in
->
+Fig.~\ref{oopseFig:staticPropsProcess}.
->
->
+\begin{figure}
->
+\centering
->
+\includegraphics[width=\linewidth]{staticPropsProcess.eps}
->
+\caption[A representation of the three-stage correlations in
->
+\texttt{StaticProps}]{This diagram illustrates three-stage
->
+processing used by \texttt{StaticProps}. $S_1$ and $S_2$ are the
->
+numbers of selected stuntdobules from {\tt -{}-sele1} and {\tt
->
+-{}-sele2} respectively, while $C$ is the number of stuntdobules
->
+appearing at both sets. The first stage($S_1-C$ and $S_2$) and
->
+second stages ($S_1$ and $S_2-C$) are completely non-overlapping. On
->
+the contrary, the third stage($C$ and $C$) are completely
->
+overlapping} \label{oopseFig:staticPropsProcess}
->
+\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}          &  input dump file \\
->
+  -o& {\tt -{}-output}         &  output file name \\
->
+  -n& {\tt -{}-step}                &  process every n frame  (default=`1') \\
->
+  -r& {\tt -{}-nrbins}              &  number of bins for distance  (default=`100') \\
->
+  -a& {\tt -{}-nanglebins}          &  number of bins for cos(angle)  (default= `50') \\
->
+  -l& {\tt -{}-length}           &  maximum length (Defaults to 1/2 smallest length of first frame) \\
->
+    & {\tt -{}-sele1}   & select the first StuntDouble set \\
->
+    & {\tt -{}-sele2}   & select the second StuntDouble set \\
->
+    & {\tt -{}-sele3}   & select the third StuntDouble set \\
->
+    & {\tt -{}-refsele} & select reference (can only be used with {\tt -{}-gxyz}) \\
->
+    & {\tt -{}-molname}           & molecule name \\
->
+    & {\tt -{}-begin}                & begin internal index \\
->
+    & {\tt -{}-end}                  & 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.
->
->
+For large simulations, the trajectory files can sometimes reach
->
+sizes in excess of several gigabytes. In order to effectively
->
+analyze that amount of data. In order to prevent a situation where
->
+the program runs out of memory due to large trajectories,
->
+\texttt{dynamicProps} will estimate the size of free memory at
->
+first, and determine the number of frames in each block, which
->
+allows the operating system to load two blocks of data
->
+simultaneously without swapping. Upon reading two blocks of the
->
+trajectory, \texttt{dynamicProps} will calculate the time
->
+correlation within the first block and the cross correlations
->
+between the two blocks. This second block is then freed and then
->
+incremented and the process repeated until the end of the
->
+trajectory. Once the end is reached, the first block is freed then
->
+incremented, until all frame pairs have been correlated in time.
->
+This process is illustrated in
->
+Fig.~\ref{oopseFig:dynamicPropsProcess}.
->
->
+\begin{figure}
->
+\centering
->
+\includegraphics[width=\linewidth]{dynamicPropsProcess.eps}
->
+\caption[A representation of the block correlations in
->
+\texttt{dynamicProps}]{This diagram illustrates block correlations
->
+processing in \texttt{dynamicProps}. The shaded region represents
->
+the self correlation of the block, and the open blocks are read one
->
+at a time and the cross correlations between blocks are calculated.}
->
+\label{oopseFig:dynamicPropsProcess}
->
+\end{figure}
->
->
+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}         & input dump file \\
->
+  -o& {\tt -{}-output}        & output file name \\
->
+    & {\tt -{}-sele1} & select first StuntDouble set \\
->
+    & {\tt -{}-sele2} & 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}
->
->
+\section{\label{appendixSection:tools}Other Useful Utilities}
->
->
+\subsection{\label{appendixSection:Dump2XYZ}Dump2XYZ}
->
->
+{\tt 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\cite{Humphrey1996}. 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}  &             input dump file \\
->
+  -o & {\tt -{}-output} &             output file name \\
->
+  -n & {\tt -{}-frame}   &                 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}  &                 The number of images to repeat in the x direction  (default=`0') \\
->
+     & {\tt -{}-repeatY} &                 The number of images to repeat in the y direction  (default=`0') \\
->
+     &  {\tt -{}-repeatZ}  &                The number of images to repeat in the z direction  (default=`0') \\
->
+  -s & {\tt -{}-selection} & 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:hydrodynamics}Hydro}
->
->
+{\tt Hydro} can calculate resistance and diffusion tensors at the
->
+center of resistance. Both tensors at the center of diffusion can
->
+also be reported from the program, as well as the coordinates for
->
+the beads which are used to approximate the arbitrary shapes. The
->
+options available for Hydro are as follows:
->
+\begin{longtable}[c]{|EFG|}
->
+\caption{Hydrodynamics 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}  &             input dump file \\
->
+  -o & {\tt -{}-output} &             output file prefix  (default=`hydro') \\
->
+  -b & {\tt -{}-beads}  &                   generate the beads only, hydrodynamics calculation will not be performed (default=off)\\
->
+     & {\tt -{}-model}  &                 hydrodynamics model (supports ``AnalyticalModel'', ``RoughShell'' and ``BeadModel'') \\
->
+\end{longtable}

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing trunk/tengDissertation/Appendix.tex (file contents): Revision 2688 by tim, Tue Apr 4 04:32:24 2006 UTC vs. Revision 2836 by tim, Fri Jun 9 02:12:42 2006 UTC

Diff Legend

Comparing trunk/tengDissertation/Appendix.tex (file contents):
Revision 2688 by tim, Tue Apr 4 04:32:24 2006 UTC vs.
Revision 2836 by tim, Fri Jun 9 02:12:42 2006 UTC