--- trunk/tengDissertation/Appendix.tex 2006/06/08 22:39:54 2835 +++ trunk/tengDissertation/Appendix.tex 2006/07/03 20:22:28 2922 @@ -1,28 +1,23 @@ \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{Wilson2006}. For instance, in -the last 20 years , there are quite a few MD packages that were +The absence of modern software development practices has been a +bottleneck limiting progress in the Scientific Computing +community. In the last 20 years, a large number of +MD packages\cite{Brooks1983, Vincent1995, Kale1999} 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 -contributed by scientists without official computer science -training. The development of most MD applications are lack of strong -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 +. Most of these are commercial programs that are either poorly +written or extremely complicated to use correctly. This situation +prevents researchers from reusing or extending those packages to do +cutting-edge research effectively. In the process of studying +structural and dynamic processes in condensed phase systems like +biological membranes and nanoparticles, we developed an open source +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 +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. @@ -38,38 +33,36 @@ Mainly written by \texttt{C/C++} and \texttt{Fortran90 \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}. +Mainly written by C++ and Fortran90, {\sc OOPSE} uses C++ Standard +Template Library (STL) and fortran modules as a foundation. As an +extensive set of the STL and Fortran90 modules, the {\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 and 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 provided by the third layer which +contains Input/Output, Molecular Mechanics and Structure modules. +The 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 parser for +meta-data files, which has been implemented using the ANother Tool +for Language Recognition(ANTLR)\cite{Parr1995, Schaps1999} syntax. +The Molecular Mechanics module consists of energy minimization and a +wide variety 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{StaticProps} (see +Sec.~\ref{appendixSection:StaticProps}), \texttt{DynamicProps} (see +Sec.~\ref{appendixSection:DynamicProps}), \texttt{Dump2XYZ} (see +Sec.~\ref{appendixSection:Dump2XYZ}), \texttt{Hydro} (see +Sec.~\ref{appendixSection:hydrodynamics}) \textit{etc}. \begin{figure} \centering @@ -78,71 +71,105 @@ of {\sc OOPSE}} \label{appendixFig:architecture} of {\sc OOPSE}} \label{appendixFig:architecture} \end{figure} -\section{\label{appendixSection:desginPattern}Design Pattern} +\section{\label{appendixSection:desginPattern}Design Patterns} 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{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. +in software design. Although they originated as an architectural +concept for buildings and towns by Christopher Alexander +\cite{Alexander1987}, design patterns first became popular in +software engineering 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. As +one of the latest advanced techniques to emerge from object-oriented +community, design patterns were applied in some of the modern +scientific software applications, such as JMol, {\sc +OOPSE}\cite{Meineke2005} and PROTOMOL\cite{Matthey2004} +\textit{etc}. The following sections enumerates some of the patterns +used in {\sc OOPSE}. -Patterns are usually described using a format that includes the -following information: -\begin{enumerate} - \item The \emph{name} that is commonly used for the pattern. Good pattern names form a vocabulary for - discussing conceptual abstractions. a pattern may have more than one commonly used or recognizable name - in the literature. In this case it is common practice to document these nicknames or synonyms under - the heading of \emph{Aliases} or \emph{Also Known As}. - \item The \emph{motivation} or \emph{context} that this pattern applies - to. Sometimes, it will include some prerequisites that should be satisfied before deciding to use a pattern - \item The \emph{solution} to the problem that the pattern - addresses. It describes how to construct the necessary work products. The description may include - pictures, diagrams and prose which identify the pattern's structure, its participants, and their - collaborations, to show how the problem is solved. - \item The \emph{consequences} of using the given solution to solve a - problem, both positive and negative. -\end{enumerate} +\subsection{\label{appendixSection:singleton}Singletons} -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, {\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}. {\tt 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}] +point of access to the object. Although the singleton pattern can be +implemented in various ways to account for different aspects of the +software design, such as lifespan control \textit{etc}, we only use +the static data approach in {\sc OOPSE}. The declaration and +implementation of IntegratorFactory class are given by declared in +List.~\ref{appendixScheme:singletonDeclaration} and +Scheme.~\ref{appendixScheme:singletonImplementation} respectively. +Since the 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 Methods} + +The Factory Method pattern is a creational pattern and 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. +One of the most popular Factory pattern is Parameterized Factory +pattern which creates products based on their identifiers (see +Scheme.~\ref{appendixScheme:factoryDeclaration}). If the identifier +has been already registered, the factory method will invoke the +corresponding creator (see +Scheme.~\ref{appendixScheme:integratorCreator}) which utilizes the +modern C++ template technique to avoid excess subclassing. + +\subsection{\label{appendixSection:visitorPattern}Visitor} + +The visitor pattern is designed to decouple the data structure and +algorithms used upon them by collecting related operations 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 a 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 Scheme.~\ref{appendixScheme:element}). Since the +hierarchies remain stable, it is easy to define a visit operation +(see Scheme.~\ref{appendixScheme:visitor}) for each class of +StuntDouble. Note that by using the Composite +pattern\cite{Gamma1994}, CompositeVisitor manages a priority visitor +list and handles the execution of every visitor in the priority list +on different StuntDoubles. + +\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. Objects below others on the diagram inherit +data structures and functions from their parent classes above them.} +\label{oopseFig:hierarchy} +\end{figure} + +\begin{lstlisting}[float,basicstyle=\ttfamily,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: + public: + static IntegratorFactory* getInstance(); + protected: IntegratorFactory(); -private: - static IntegratorFactory* instance_; -}; + 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; @@ -155,35 +182,15 @@ Since constructor is declared as {\tt protected}, a cl } \end{lstlisting} -Since constructor is declared as {\tt protected}, a client can not -instantiate {\tt IntegratorFactory} directly. Moreover, since the -member function {\tt getInstance} serves as the only entry of access -to {\tt 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} +\begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (I)]Source code of IntegratorFactory class.},label={appendixScheme:factoryDeclaration}] -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. -{\tt Integrator} class Parameterized Factory pattern where factory -method ({\tt 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 subclassing. -\begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (I)]Source code of {\tt IntegratorFactory} class.},label={appendixScheme:factoryDeclaration}] - class IntegratorFactory { -public: + public: typedef std::map CreatorMapType; - bool registerIntegrator(IntegratorCreator* creator) { - return creatorMap_.insert(creator->getIdent(), creator).second; + bool registerIntegrator(IntegratorCreator* creator){ + return creatorMap_.insert(creator->getIdent(),creator).second; } Integrator* createIntegrator(const string& id, SimInfo* info) { @@ -199,98 +206,55 @@ class IntegratorFactory { (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) {} + public: + IntegratorCreator(const string& ident) : ident_(ident) {} - const string& getIdent() const { return ident_; } + const string& getIdent() const { return ident_; } - virtual Integrator* create(SimInfo* info) const = 0; + virtual Integrator* create(SimInfo* info) const = 0; -private: - string ident_; + private: + string ident_; }; -template -class IntegratorBuilder : public IntegratorCreator { -public: +template class IntegratorBuilder : + public IntegratorCreator { + public: IntegratorBuilder(const string& ident) - : IntegratorCreator(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. The operation being -performed on a structure can be switched without changing the -interfaces of the elements. In other words, one can add 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 and -unrelated operations are performed on different StuntDoubles. -Visitor allows one to keep related operations together by packing -them into one class. {\tt BaseAtomVisitor} is a typical example of -visitor in {\tt Dump2XYZ} program{see -List.~\ref{appendixScheme:visitor}}. In contrast to the operations, -the object structure or element classes rarely change(See -Fig.~\ref{oopseFig:heirarchy} and -List.~\ref{appendixScheme:element}). - - -\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{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); -}; - -\end{lstlisting} - \begin{lstlisting}[float,caption={[The implementation of Visitor pattern (II)]Source code of the element classes.},label={appendixScheme:element}] class StuntDouble { -public: + public: virtual void accept(BaseVisitor* v) = 0; }; class Atom: public StuntDouble { -public: + public: virtual void accept{BaseVisitor* v*} { v->visit(this); } }; class DirectionalAtom: public Atom { -public: + public: virtual void accept{BaseVisitor* v*} { v->visit(this); } }; class RigidBody: public StuntDouble { -public: + public: virtual void accept{BaseVisitor* v*} { v->visit(this); } @@ -298,47 +262,88 @@ class RigidBody: public StuntDouble { (public) \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 CompositeVisitor: public BaseVisitor { + public: + typedef list > VistorListType; + typedef VistorListType::iterator VisitorListIterator; + virtual void visit(Atom* atom) { + VisitorListIterator i; + BaseVisitor* curVisitor; + for(i = visitorScheme.begin();i != visitorScheme.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 myAtoms; + std::vector::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 heirarchy is illustrated in -Fig.~\ref{oopseFig:heirarchy}. Every Molecule, Atom and +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 +specified in the meta data 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. -%\begin{figure} -%\centering -%\includegraphics[width=\linewidth]{heirarchy.eps} -%\caption[Class heirarchy for ojects in {\sc OOPSE}]{ A diagram of -%the class heirarchy. -%\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:heirarchy} -%\end{figure} +\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} \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. +{\sc OOPSE} provides a powerful selection utility to select +StuntDoubles. 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 @@ -375,7 +380,7 @@ atoms belonging to TIP3P molecules \\ \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 + & select DMPC\_RB\_0.PO4 & select the PO4 atoms belonging to the first RigidBody in each DMPC molecule \\ & select DMPC.20 & select the twentieth StuntDouble in each DMPC @@ -470,8 +475,34 @@ of a selected atom or rigid body. 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. +of a selected atom or rigid body. 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} +\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} + 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 @@ -515,73 +546,10 @@ distribution functions are most easily seen in the fig \end{description} The vectors (and angles) associated with these angular pair -distribution functions are most easily seen in the figure below: +distribution functions are most easily seen in +Fig.~\ref{oopseFig:gofr}. The options available for {\tt +StaticProps} are showed in Table.~\ref{appendix:staticPropsOptions}. -\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 @@ -607,12 +575,11 @@ sizes in excess of several gigabytes. In order to effe 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 +sizes in excess of several gigabytes. In order to prevent a +situation where the program runs out of memory due to large +trajectories, \texttt{dynamicProps} will first estimate the size of +free memory, and determine the number of frames in each block, which +will allow 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 @@ -621,7 +588,9 @@ Fig.~\ref{oopseFig:dynamicPropsProcess}. 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}. +Fig.~\ref{oopseFig:dynamicPropsProcess} and the options available +for DynamicProps are showed in +Table.~\ref{appendix:dynamicPropsOptions} \begin{figure} \centering @@ -634,14 +603,51 @@ The options available for DynamicProps are as follows: \label{oopseFig:dynamicPropsProcess} \end{figure} -The options available for DynamicProps are as follows: \begin{longtable}[c]{|EFG|} -\caption{DynamicProps Command-line Options} +\caption{STATICPROPS COMMAND-LINE OPTIONS} +\label{appendix:staticPropsOptions} \\ \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} + +\begin{longtable}[c]{|EFG|} +\caption{DYNAMICPROPS COMMAND-LINE OPTIONS} +\label{appendix:dynamicPropsOptions} +\\ \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 \\ @@ -665,9 +671,8 @@ as follows: and VMD\cite{Humphrey1996}. The options available for Dump2XYZ are as follows: - \begin{longtable}[c]{|EFG|} -\caption{Dump2XYZ Command-line Options} +\caption{DUMP2XYZ COMMAND-LINE OPTIONS} \\ \hline {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline \endhead @@ -701,7 +706,7 @@ options available for Hydro are as follows: 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} +\caption{HYDRODYNAMICS COMMAND-LINE OPTIONS} \\ \hline {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline \endhead