--- trunk/tengDissertation/Appendix.tex 2006/06/25 17:39:42 2883 +++ trunk/tengDissertation/Appendix.tex 2006/06/29 23:00:35 2909 @@ -3,7 +3,7 @@ community\cite{Wilson2006}. In the last 20 years , a l 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 +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 . Most of these are commercial programs that are either poorly @@ -35,9 +35,9 @@ extensive set of the STL and Fortran90 modules, {\sc B 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 +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 @@ -52,13 +52,13 @@ wide varieties of integration methods(see 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 +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{StatProps} (see +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 @@ -74,20 +74,21 @@ in software design. Although originated as an architec \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. 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}. +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}. \subsection{\label{appendixSection:singleton}Singletons} @@ -95,7 +96,7 @@ software designs, such as lifespan control \textit{etc 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 +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 @@ -125,29 +126,47 @@ algorithms used upon them by collecting related operat \subsection{\label{appendixSection:visitorPattern}Visitor} The visitor pattern is designed to decouple the data structure and -algorithms used upon them by collecting related operation from +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 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. +class hierarchy in Scheme.~\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{lstlisting}[float,caption={[A classic Singleton design pattern implementation(I)] The declaration of of simple Singleton pattern.},label={appendixScheme:singletonDeclaration}] +\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} -class IntegratorFactory { public: - static IntegratorFactory* getInstance(); protected: +\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: IntegratorFactory(); -private: - static IntegratorFactory* instance_; -}; + private: + static IntegratorFactory* instance_; }; \end{lstlisting} @@ -166,11 +185,12 @@ class IntegratorFactory { public: \begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (I)]Source code of IntegratorFactory class.},label={appendixScheme:factoryDeclaration}] -class IntegratorFactory { public: +class IntegratorFactory { + 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) { @@ -191,24 +211,24 @@ class IntegratorCreator { class IntegratorCreator { public: - IntegratorCreator(const string& ident) : ident_(ident) {} + 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 { +template class IntegratorBuilder : + public IntegratorCreator { public: - IntegratorBuilder(const string& ident) + IntegratorBuilder(const string& ident) : IntegratorCreator(ident) {} - virtual Integrator* create(SimInfo* info) const { - return new ConcreteIntegrator(info); - } + virtual Integrator* create(SimInfo* info) const { + return new ConcreteIntegrator(info); + } }; \end{lstlisting} @@ -216,48 +236,45 @@ class StuntDouble { class StuntDouble { public: - virtual void accept(BaseVisitor* v) = 0; + virtual void accept(BaseVisitor* v) = 0; }; class Atom: public StuntDouble { public: - virtual void accept{BaseVisitor* v*} { - v->visit(this); - } + virtual void accept{BaseVisitor* v*} { + v->visit(this); + } }; class DirectionalAtom: public Atom { public: - virtual void accept{BaseVisitor* v*} { - v->visit(this); - } + virtual void accept{BaseVisitor* v*} { + v->visit(this); + } }; class RigidBody: public StuntDouble { public: - virtual void accept{BaseVisitor* v*} { - v->visit(this); - } + 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); + 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); + virtual void visit(Atom* atom); + virtual void visit(DirectionalAtom* datom); + virtual void visit(RigidBody* rb); }; - class CompositeVisitor: public BaseVisitor { public: typedef list > VistorListType; @@ -265,53 +282,31 @@ class CompositeVisitor: public BaseVisitor { virtual void visit(Atom* atom) { VisitorListIterator i; BaseVisitor* curVisitor; - for(i = visitorScheme.begin();i != visitorScheme.end();++i) { + 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) { + 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 = visitorScheme.begin();i != visitorScheme.end();++i) { + for(i = visitorList.begin();i != visitorList.end();++i) { rb->accept(*i); - for(ai = myAtoms.begin(); ai != myAtoms.end(); ++ai){ + for(ai = myAtoms.begin(); ai != myAtoms.end(); ++ai) (*ai)->accept(*i); - } } - void addVisitor(BaseVisitor* v, int priority); protected: - VistorListType visitorList; + VistorListType visitorList; }; \end{lstlisting} - -\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} - \section{\label{appendixSection:concepts}Concepts} OOPSE manipulates both traditional atoms as well as some objects @@ -552,44 +547,8 @@ Fig.~\ref{oopseFig:gofr}. The vectors (and angles) associated with these angular pair distribution functions are most easily seen in -Fig.~\ref{oopseFig:gofr}. - -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} +Fig.~\ref{oopseFig:gofr}. The options available for {\tt +StaticProps} are showed in Table.~\ref{appendix:staticPropsOptions}. \subsection{\label{appendixSection:DynamicProps}DynamicProps} @@ -629,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 @@ -642,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 \\ @@ -673,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 @@ -709,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