--- trunk/tengDissertation/Appendix.tex 2006/06/06 20:33:28 2805 +++ trunk/tengDissertation/Appendix.tex 2006/06/25 17:39:42 2883 @@ -1,98 +1,331 @@ \appendix -\chapter{\label{chapt: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 +The absence of modern software development practices has been a +bottleneck limiting progress in the Scientific Computing +community\cite{Wilson2006}. In the last 20 years , a large number of +few 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. +. 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 +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:desginPattern}Design Pattern} +\section{\label{appendixSection:architecture }Architecture} +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, {\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 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:DynamicProps}), \texttt{Dump2XYZ} (see +Sec.~\ref{appendixSection:Dump2XYZ}), \texttt{Hydro} (see +Sec.~\ref{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 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{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. 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, OOPSE -\cite{Meineke05} and PROTOMOL \cite{Matthey05} \textit{etc}. +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. 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}. 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:singleton}Singleton} -The Singleton pattern ensures that only one instance of a class is -created. All objects that use an instance of that class use the same -instance. +\subsection{\label{appendixSection:factoryMethod}Factory Methods} -\subsection{\label{appendixSection:factoryMethod}Factory Method} -The Factory Method pattern is a creational pattern which deals with +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 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. +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 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 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 using Composite pattern\cite{Gamma1994}, CompositeVisitor +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{lstlisting}[float,caption={[A classic Singleton design pattern implementation(I)] The declaration of of simple Singleton pattern.},label={appendixScheme:singletonDeclaration}] -\section{\label{appendixSection:analysisFramework}Analysis Framework} +class IntegratorFactory { public: + static IntegratorFactory* getInstance(); protected: + IntegratorFactory(); +private: + static IntegratorFactory* instance_; +}; -\section{\label{appendixSection:concepts}Concepts} +\end{lstlisting} -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: +\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} + +\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 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 IntegratorBuilder : public +IntegratorCreator { + public: + IntegratorBuilder(const string& ident) + : IntegratorCreator(ident) {} + virtual Integrator* create(SimInfo* info) const { + return new ConcreteIntegrator(info); + } +}; +\end{lstlisting} + +\begin{lstlisting}[float,caption={[The implementation of Visitor pattern (II)]Source code of the element classes.},label={appendixScheme:element}] + +class StuntDouble { + public: + virtual void accept(BaseVisitor* v) = 0; +}; + +class Atom: public StuntDouble { + public: + virtual void accept{BaseVisitor* v*} { + v->visit(this); + } +}; + +class DirectionalAtom: public Atom { + public: + virtual void accept{BaseVisitor* v*} { + v->visit(this); + } +}; + +class RigidBody: public StuntDouble { + public: + virtual void accept{BaseVisitor* v*} { + v->visit(this); + } +}; + +\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 = visitorScheme.begin();i != visitorScheme.end();++i) { + atom->accept(*i); + } + } + + virtual void visit(RigidBody* rb) { + VisitorListIterator i; + std::vector myAtoms; + std::vector::iterator ai; + myAtoms = rb->getAtoms(); + for(i = visitorScheme.begin();i != visitorScheme.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} + \begin{figure} \centering -\includegraphics[width=3in]{heirarchy.eps} -\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} +\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} + +\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 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{itemize} \item A {\bf StuntDouble} is {\it any} object that can be manipulated by the integrators and minimizers. @@ -102,21 +335,15 @@ Every Molecule, Atom and DirectionalAtom in {\sc oopse DirectionalAtom}s which behaves as a single unit. \end{itemize} -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}} +{\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 +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 @@ -203,10 +430,9 @@ expression}} 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}} +expression}}. Once defined, the user can specify such terms in +boolean expressions -Once defined, the user can specify such terms in boolean expressions - {\tt define SSDWATER SSD or SSD1 or SSDRF} {\tt select SSDWATER} @@ -242,54 +468,46 @@ atoms. 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} +\section{\label{appendixSection:analysisFramework}Analysis Framework} -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. +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. 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 @@ -333,17 +551,9 @@ 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}. -\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} - The options available for {\tt StaticProps} are as follows: \begin{longtable}[c]{|EFG|} \caption{StaticProps Command-line Options} @@ -354,19 +564,19 @@ The options available for {\tt StaticProps} are as fol \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 \\ + -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 @@ -405,6 +615,33 @@ The options available for DynamicProps are as follows: 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 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 +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} @@ -415,10 +652,10 @@ The options available for DynamicProps are as follows: \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) \\ + -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 @@ -427,4 +664,61 @@ The options available for DynamicProps are as follows: -d& {\tt -{}-dcorr} & compute dipole correlation function \end{longtable} -\subsection{\label{appendixSection:hydrodynamics}Hydrodynamics} +\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}