ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/group/trunk/tengDissertation/Appendix.tex
(Generate patch)

Comparing trunk/tengDissertation/Appendix.tex (file contents):
Revision 2805 by tim, Tue Jun 6 20:33:28 2006 UTC vs.
Revision 2883 by tim, Sun Jun 25 17:39:42 2006 UTC

# Line 1 | Line 1
1   \appendix
2 < \chapter{\label{chapt:appendix}APPENDIX}
2 > \chapter{\label{chapt:oopse}Object-Oriented Parallel Simulation Engine}
3  
4 < Designing object-oriented software is hard, and designing reusable
5 < object-oriented scientific software is even harder. Absence of
6 < applying modern software development practices is the bottleneck of
7 < Scientific Computing community\cite{wilson}. For instance, in the
8 < last 20 years , there are quite a few MD packages that were
4 > The absence of modern software development practices has been a
5 > bottleneck limiting progress in the Scientific Computing
6 > community\cite{Wilson2006}. In the last 20 years , a large number of
7 > few MD packages\cite{Brooks1983, Vincent1995, Kale1999} were
8   developed to solve common MD problems and perform robust simulations
9 < . However, many of the codes are legacy programs that are either
10 < poorly organized or extremely complex. Usually, these packages were
11 < contributed by scientists without official computer science
12 < training. The development of most MD applications are lack of strong
13 < coordination to enforce design and programming guidelines. Moreover,
14 < most MD programs also suffer from missing design and implement
15 < documents which is crucial to the maintenance and extensibility.
9 > . Most of these are commercial programs that are either poorly
10 > written or extremely complicated to use correctly. This situation
11 > prevents researchers from reusing or extending those packages to do
12 > cutting-edge research effectively. In the process of studying
13 > structural and dynamic processes in condensed phase systems like
14 > biological membranes and nanoparticles, we developed an open source
15 > Object-Oriented Parallel Simulation Engine ({\sc OOPSE}). This new
16 > molecular dynamics package has some unique features
17 > \begin{enumerate}
18 >  \item {\sc OOPSE} performs Molecular Dynamics (MD) simulations on non-standard
19 > atom types (transition metals, point dipoles, sticky potentials,
20 > Gay-Berne ellipsoids, or other "lumpy"atoms with orientational
21 > degrees of freedom), as well as rigid bodies.
22 >  \item {\sc OOPSE} uses a force-based decomposition algorithm using MPI on cheap
23 > Beowulf clusters to obtain very efficient parallelism.
24 >  \item {\sc OOPSE} integrates the equations of motion using advanced methods for
25 > orientational dynamics in NVE, NVT, NPT, NPAT, and NP$\gamma$T
26 > ensembles.
27 >  \item {\sc OOPSE} can carry out simulations on metallic systems using the
28 > Embedded Atom Method (EAM) as well as the Sutton-Chen potential.
29 >  \item {\sc OOPSE} can perform simulations on Gay-Berne liquid crystals.
30 >  \item  {\sc OOPSE} can simulate systems containing the extremely efficient
31 > extended-Soft Sticky Dipole (SSD/E) model for water.
32 > \end{enumerate}
33  
34 < \section{\label{appendixSection:desginPattern}Design Pattern}
34 > \section{\label{appendixSection:architecture }Architecture}
35  
36 + Mainly written by C++ and Fortran90, {\sc OOPSE} uses C++ Standard
37 + Template Library (STL) and fortran modules as a foundation. As an
38 + extensive set of the STL and Fortran90 modules, {\sc Base Classes}
39 + provide generic implementations of mathematical objects (e.g.,
40 + matrices, vectors, polynomials, random number generators) and
41 + advanced data structures and algorithms(e.g., tuple, bitset, generic
42 + data and string manipulation). The molecular data structures for the
43 + representation of atoms, bonds, bends, torsions, rigid bodies and
44 + molecules \textit{etc} are contained in the {\sc Kernel} which is
45 + implemented with {\sc Base Classes} and are carefully designed to
46 + provide maximum extensibility and flexibility. The functionality
47 + required for applications is provided by the third layer which
48 + contains Input/Output, Molecular Mechanics and Structure modules.
49 + The Input/Output module not only implements general methods for file
50 + handling, but also defines a generic force field interface. Another
51 + important component of Input/Output module is the parser for
52 + meta-data files, which has been implemented using the ANother Tool
53 + for Language Recognition(ANTLR)\cite{Parr1995, Schaps1999} syntax.
54 + The Molecular Mechanics module consists of energy minimization and a
55 + wide varieties of integration methods(see
56 + Chap.~\ref{chapt:methodology}). The structure module contains a
57 + flexible and powerful selection library which syntax is elaborated
58 + in Sec.~\ref{appendixSection:syntax}. The top layer is made of the
59 + main program of the package, \texttt{oopse} and it corresponding
60 + parallel version \texttt{oopse\_MPI}, as well as other useful
61 + utilities, such as \texttt{StatProps} (see
62 + Sec.~\ref{appendixSection:StaticProps}), \texttt{DynamicProps} (see
63 + Sec.~\ref{appendixSection:DynamicProps}), \texttt{Dump2XYZ} (see
64 + Sec.~\ref{appendixSection:Dump2XYZ}), \texttt{Hydro} (see
65 + Sec.~\ref{appendixSection:hydrodynamics}) \textit{etc}.
66 +
67 + \begin{figure}
68 + \centering
69 + \includegraphics[width=\linewidth]{architecture.eps}
70 + \caption[The architecture of {\sc OOPSE}] {Overview of the structure
71 + of {\sc OOPSE}} \label{appendixFig:architecture}
72 + \end{figure}
73 +
74 + \section{\label{appendixSection:desginPattern}Design Patterns}
75 +
76   Design patterns are optimal solutions to commonly-occurring problems
77   in software design. Although originated as an architectural concept
78 < for buildings and towns by Christopher Alexander \cite{alexander},
79 < software patterns first became popular with the wide acceptance of
80 < the book, Design Patterns: Elements of Reusable Object-Oriented
81 < Software \cite{gamma94}. Patterns reflect the experience, knowledge
82 < and insights of developers who have successfully used these patterns
83 < in their own work. Patterns are reusable. They provide a ready-made
84 < solution that can be adapted to different problems as necessary.
85 < Pattern are expressive. they provide a common vocabulary of
86 < solutions that can express large solutions succinctly.
78 > for buildings and towns by Christopher Alexander
79 > \cite{Alexander1987}, software patterns first became popular with
80 > the wide acceptance of the book, Design Patterns: Elements of
81 > Reusable Object-Oriented Software \cite{Gamma1994}. Patterns reflect
82 > the experience, knowledge and insights of developers who have
83 > successfully used these patterns in their own work. Patterns are
84 > reusable. They provide a ready-made solution that can be adapted to
85 > different problems as necessary. As one of the latest advanced
86 > techniques to emerge from object-oriented community, design patterns
87 > were applied in some of the modern scientific software applications,
88 > such as JMol, {\sc OOPSE}\cite{Meineke2005} and
89 > PROTOMOL\cite{Matthey2004} \textit{etc}. The following sections
90 > enumerates some of the patterns used in {\sc OOPSE}.
91  
92 < Patterns are usually described using a format that includes the
33 < following information:
34 < \begin{enumerate}
35 <  \item The \emph{name} that is commonly used for the pattern. Good pattern names form a vocabulary for
36 <  discussing conceptual abstractions. a pattern may have more than one commonly used or recognizable name
37 <  in the literature. In this case it is common practice to document these nicknames or synonyms under
38 <  the heading of \emph{Aliases} or \emph{Also Known As}.
39 <  \item The \emph{motivation} or \emph{context} that this pattern applies
40 <  to. Sometimes, it will include some prerequisites that should be satisfied before deciding to use a pattern
41 <  \item The \emph{solution} to the problem that the pattern
42 <  addresses. It describes how to construct the necessary work products. The description may include
43 <  pictures, diagrams and prose which identify the pattern's structure, its participants, and their
44 <  collaborations, to show how the problem is solved.
45 <  \item The \emph{consequences} of using the given solution to solve a
46 <  problem, both positive and negative.
47 < \end{enumerate}
92 > \subsection{\label{appendixSection:singleton}Singletons}
93  
94 < As one of the latest advanced techniques emerged from
95 < object-oriented community, design patterns were applied in some of
96 < the modern scientific software applications, such as JMol, OOPSE
97 < \cite{Meineke05} and PROTOMOL \cite{Matthey05} \textit{etc}.
94 > The Singleton pattern not only provides a mechanism to restrict
95 > instantiation of a class to one object, but also provides a global
96 > point of access to the object. Although the singleton pattern can be
97 > implemented in various ways  to account for different aspects of the
98 > software designs, such as lifespan control \textit{etc}, we only use
99 > the static data approach in {\sc OOPSE}. The declaration and
100 > implementation of IntegratorFactory class are given by declared in
101 > List.~\ref{appendixScheme:singletonDeclaration} and
102 > Scheme.~\ref{appendixScheme:singletonImplementation} respectively.
103 > Since the constructor is declared as protected, a client can not
104 > instantiate IntegratorFactory directly. Moreover, since the member
105 > function getInstance serves as the only entry of access to
106 > IntegratorFactory, this approach fulfills the basic requirement, a
107 > single instance. Another consequence of this approach is the
108 > automatic destruction since static data are destroyed upon program
109 > termination.
110  
111 < \subsection{\label{appendixSection:singleton}Singleton}
55 < The Singleton pattern ensures that only one instance of a class is
56 < created. All objects that use an instance of that class use the same
57 < instance.
111 > \subsection{\label{appendixSection:factoryMethod}Factory Methods}
112  
113 < \subsection{\label{appendixSection:factoryMethod}Factory Method}
60 < The Factory Method pattern is a creational pattern which deals with
113 > The Factory Method pattern is a creational pattern and deals with
114   the problem of creating objects without specifying the exact class
115 < of object that will be created. Factory Method solves this problem
116 < by defining a separate method for creating the objects, which
117 < subclasses can then override to specify the derived type of product
118 < that will be created.
115 > of object that will be created. Factory method is typically
116 > implemented by delegating the creation operation to the subclasses.
117 > One of the most popular Factory pattern is Parameterized Factory
118 > pattern which creates products based on their identifiers (see
119 > Scheme.~\ref{appendixScheme:factoryDeclaration}). If the identifier
120 > has been already registered, the factory method will invoke the
121 > corresponding creator (see
122 > Scheme.~\ref{appendixScheme:integratorCreator}) which utilizes the
123 > modern C++ template technique to avoid excess subclassing.
124  
67 –
125   \subsection{\label{appendixSection:visitorPattern}Visitor}
69 – The purpose of the Visitor Pattern is to encapsulate an operation
70 – that you want to perform on the elements of a data structure. In
71 – this way, you can change the operation being performed on a
72 – structure without the need of changing the classes of the elements
73 – that you are operating on.
126  
127 + The visitor pattern is designed to decouple the data structure and
128 + algorithms used upon them by collecting related operation from
129 + element classes into other visitor classes, which is equivalent to
130 + adding virtual functions into a set of classes without modifying
131 + their interfaces. Fig.~\ref{appendixFig:visitorUML} demonstrates the
132 + structure of a Visitor pattern which is used extensively in {\tt
133 + Dump2XYZ}. In order to convert an OOPSE dump file, a series of
134 + distinct operations are performed on different StuntDoubles (See the
135 + class hierarchy in Fig.~\ref{oopseFig:hierarchy} and the declaration
136 + in Scheme.~\ref{appendixScheme:element}). Since the hierarchies
137 + remain stable, it is easy to define a visit operation (see
138 + Scheme.~\ref{appendixScheme:visitor}) for each class of StuntDouble.
139 + Note that using Composite pattern\cite{Gamma1994}, CompositeVisitor
140 + manages a priority visitor list and handles the execution of every
141 + visitor in the priority list on different StuntDoubles.
142  
143 < \subsection{\label{appendixSection:templateMethod}Template Method}
143 > \begin{lstlisting}[float,caption={[A classic Singleton design pattern implementation(I)] The declaration of of simple Singleton pattern.},label={appendixScheme:singletonDeclaration}]
144  
145 < \section{\label{appendixSection:analysisFramework}Analysis Framework}
145 > class IntegratorFactory { public:
146 >  static IntegratorFactory* getInstance(); protected:
147 >  IntegratorFactory();
148 > private:
149 >  static IntegratorFactory* instance_;
150 > };
151  
152 < \section{\label{appendixSection:concepts}Concepts}
152 > \end{lstlisting}
153  
154 < OOPSE manipulates both traditional atoms as well as some objects
155 < that {\it behave like atoms}.  These objects can be rigid
156 < collections of atoms or atoms which have orientational degrees of
157 < freedom.  Here is a diagram of the class heirarchy:
154 > \begin{lstlisting}[float,caption={[A classic implementation of Singleton design pattern (II)] The implementation of simple Singleton pattern.},label={appendixScheme:singletonImplementation}]
155 >
156 > IntegratorFactory::instance_ = NULL;
157 >
158 > IntegratorFactory* getInstance() {
159 >  if (instance_ == NULL){
160 >    instance_ = new IntegratorFactory;
161 >  }
162 >  return instance_;
163 > }
164 >
165 > \end{lstlisting}
166 >
167 > \begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (I)]Source code of IntegratorFactory class.},label={appendixScheme:factoryDeclaration}]
168 >
169 > class IntegratorFactory { public:
170 >  typedef std::map<string, IntegratorCreator*> CreatorMapType;
171 >
172 >  bool registerIntegrator(IntegratorCreator* creator) {
173 >    return creatorMap_.insert(creator->getIdent(), creator).second;
174 >  }
175 >
176 >  Integrator* createIntegrator(const string& id, SimInfo* info) {
177 >    Integrator* result = NULL;
178 >    CreatorMapType::iterator i = creatorMap_.find(id);
179 >    if (i != creatorMap_.end()) {
180 >      result = (i->second)->create(info);
181 >    }
182 >    return result;
183 >  }
184 >
185 > private:
186 >  CreatorMapType creatorMap_;
187 > };
188 > \end{lstlisting}
189 >
190 > \begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (III)]Source code of creator classes.},label={appendixScheme:integratorCreator}]
191 >
192 > class IntegratorCreator {
193 >  public:
194 >    IntegratorCreator(const string& ident) : ident_(ident) {}
195 >
196 >    const string& getIdent() const { return ident_; }
197 >
198 >    virtual Integrator* create(SimInfo* info) const = 0;
199 >
200 > private:
201 >    string ident_;
202 > };
203 >
204 > template<class ConcreteIntegrator> class IntegratorBuilder : public
205 > IntegratorCreator {
206 >  public:
207 >    IntegratorBuilder(const string& ident)
208 >                     : IntegratorCreator(ident) {}
209 >    virtual  Integrator* create(SimInfo* info) const {
210 >      return new ConcreteIntegrator(info);
211 >    }
212 > };
213 > \end{lstlisting}
214 >
215 > \begin{lstlisting}[float,caption={[The implementation of Visitor pattern (II)]Source code of the element classes.},label={appendixScheme:element}]
216 >
217 > class StuntDouble {
218 >  public:
219 >    virtual void accept(BaseVisitor* v) = 0;
220 > };
221 >
222 > class Atom: public StuntDouble {
223 >  public:
224 >    virtual void accept{BaseVisitor* v*} {
225 >      v->visit(this);
226 >    }
227 > };
228 >
229 > class DirectionalAtom: public Atom {
230 >  public:
231 >    virtual void accept{BaseVisitor* v*} {
232 >      v->visit(this);
233 >    }
234 > };
235 >
236 > class RigidBody: public StuntDouble {
237 >  public:
238 >    virtual void accept{BaseVisitor* v*} {
239 >      v->visit(this);
240 >    }
241 > };
242 >
243 > \end{lstlisting}
244 >
245 > \begin{lstlisting}[float,caption={[The implementation of Visitor pattern (I)]Source code of the visitor classes.},label={appendixScheme:visitor}]
246 >
247 > class BaseVisitor{
248 >  public:
249 >    virtual void visit(Atom* atom);
250 >    virtual void visit(DirectionalAtom* datom);
251 >    virtual void visit(RigidBody* rb);
252 > };
253 >
254 > class BaseAtomVisitor:public BaseVisitor{
255 >  public:
256 >    virtual void visit(Atom* atom);
257 >    virtual void visit(DirectionalAtom* datom);
258 >    virtual void visit(RigidBody* rb);
259 > };
260  
261 + class CompositeVisitor: public BaseVisitor {
262 +  public:
263 +  typedef list<pair<BaseVisitor*, int> > VistorListType;
264 +  typedef VistorListType::iterator VisitorListIterator;
265 +  virtual void visit(Atom* atom) {
266 +    VisitorListIterator i;
267 +    BaseVisitor* curVisitor;
268 +    for(i = visitorScheme.begin();i != visitorScheme.end();++i) {
269 +      atom->accept(*i);
270 +    }
271 +  }
272 +
273 +  virtual void visit(DirectionalAtom* datom) {
274 +    VisitorListIterator i;
275 +    BaseVisitor* curVisitor;
276 +    for(i = visitorScheme.begin();i != visitorScheme.end();++i) {
277 +      atom->accept(*i);
278 +    }
279 +  }
280 +
281 +  virtual void visit(RigidBody* rb) {
282 +    VisitorListIterator i;
283 +    std::vector<Atom*> myAtoms;
284 +    std::vector<Atom*>::iterator ai;
285 +    myAtoms = rb->getAtoms();
286 +    for(i = visitorScheme.begin();i != visitorScheme.end();++i) {
287 +      rb->accept(*i);
288 +      for(ai = myAtoms.begin(); ai != myAtoms.end(); ++ai){
289 +        (*ai)->accept(*i);
290 +      }
291 +    }
292 +
293 +  void addVisitor(BaseVisitor* v, int priority);
294 +  protected:
295 +    VistorListType visitorList;
296 + };
297 + \end{lstlisting}
298 +
299   \begin{figure}
300   \centering
301 < \includegraphics[width=3in]{heirarchy.eps}
302 < \caption[Class heirarchy for StuntDoubles in {\sc oopse}-3.0]{ \\
303 < The class heirarchy of StuntDoubles in {\sc oopse}-3.0. The
92 < selection syntax allows the user to select any of the objects that
93 < are descended from a StuntDouble.} \label{oopseFig:heirarchy}
301 > \includegraphics[width=\linewidth]{visitor.eps}
302 > \caption[The UML class diagram of Visitor patten] {The UML class
303 > diagram of Visitor patten.} \label{appendixFig:visitorUML}
304   \end{figure}
305  
306 + \begin{figure}
307 + \centering
308 + \includegraphics[width=\linewidth]{hierarchy.eps}
309 + \caption[Class hierarchy for ojects in {\sc OOPSE}]{ A diagram of
310 + the class hierarchy. Objects below others on the diagram inherit
311 + data structures and functions from their parent classes above them.}
312 + \label{oopseFig:hierarchy}
313 + \end{figure}
314 +
315 + \section{\label{appendixSection:concepts}Concepts}
316 +
317 + OOPSE manipulates both traditional atoms as well as some objects
318 + that {\it behave like atoms}.  These objects can be rigid
319 + collections of atoms or atoms which have orientational degrees of
320 + freedom.  A diagram of the class hierarchy is illustrated in
321 + Fig.~\ref{oopseFig:hierarchy}. Every Molecule, Atom and
322 + DirectionalAtom in {\sc OOPSE} have their own names which are
323 + specified in the meta data file. In contrast, RigidBodies are
324 + denoted by their membership and index inside a particular molecule:
325 + [MoleculeName]\_RB\_[index] (the contents inside the brackets depend
326 + on the specifics of the simulation). The names of rigid bodies are
327 + generated automatically. For example, the name of the first rigid
328 + body in a DMPC molecule is DMPC\_RB\_0.
329   \begin{itemize}
330   \item A {\bf StuntDouble} is {\it any} object that can be manipulated by the
331   integrators and minimizers.
# Line 102 | Line 335 | Every Molecule, Atom and DirectionalAtom in {\sc oopse
335   DirectionalAtom}s which behaves as a single unit.
336   \end{itemize}
337  
105 – Every Molecule, Atom and DirectionalAtom in {\sc oopse} have their
106 – own names which are specified in the {\tt .md} file. In contrast,
107 – RigidBodies are denoted by their membership and index inside a
108 – particular molecule: [MoleculeName]\_RB\_[index] (the contents
109 – inside the brackets depend on the specifics of the simulation). The
110 – names of rigid bodies are generated automatically. For example, the
111 – name of the first rigid body in a DMPC molecule is DMPC\_RB\_0.
112 –
338   \section{\label{appendixSection:syntax}Syntax of the Select Command}
339  
340 < The most general form of the select command is: {\tt select {\it
341 < expression}}
340 > {\sc OOPSE} provides a powerful selection utility to select
341 > StuntDoubles. The most general form of the select command is:
342  
343 + {\tt select {\it expression}}.
344 +
345   This expression represents an arbitrary set of StuntDoubles (Atoms
346 < or RigidBodies) in {\sc oopse}. Expressions are composed of either
346 > or RigidBodies) in {\sc OOPSE}. Expressions are composed of either
347   name expressions, index expressions, predefined sets, user-defined
348   expressions, comparison operators, within expressions, or logical
349   combinations of the above expression types. Expressions can be
# Line 203 | Line 430 | expression}}
430   Users can define arbitrary terms to represent groups of
431   StuntDoubles, and then use the define terms in select commands. The
432   general form for the define command is: {\bf define {\it term
433 < expression}}
433 > expression}}. Once defined, the user can specify such terms in
434 > boolean expressions
435  
208 – Once defined, the user can specify such terms in boolean expressions
209 –
436   {\tt define SSDWATER SSD or SSD1 or SSDRF}
437  
438   {\tt select SSDWATER}
# Line 242 | Line 468 | atoms.
468   select all StuntDoubles which are within 2.5 angstroms of PO4 or NC4
469   atoms.
470  
245 – \section{\label{appendixSection:tools}Tools which use the selection command}
471  
472 < \subsection{\label{appendixSection:Dump2XYZ}Dump2XYZ}
472 > \section{\label{appendixSection:analysisFramework}Analysis Framework}
473  
249 – Dump2XYZ can transform an OOPSE dump file into a xyz file which can
250 – be opened by other molecular dynamics viewers such as Jmol and VMD.
251 – The options available for Dump2XYZ are as follows:
252 –
253 –
254 – \begin{longtable}[c]{|EFG|}
255 – \caption{Dump2XYZ Command-line Options}
256 – \\ \hline
257 – {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
258 – \endhead
259 – \hline
260 – \endfoot
261 –  -h & {\tt -{}-help} &                        Print help and exit \\
262 –  -V & {\tt -{}-version} &                     Print version and exit \\
263 –  -i & {\tt -{}-input=filename}  &             input dump file \\
264 –  -o & {\tt -{}-output=filename} &             output file name \\
265 –  -n & {\tt -{}-frame=INT}   &                 print every n frame  (default=`1') \\
266 –  -w & {\tt -{}-water}       &                 skip the the waters  (default=off) \\
267 –  -m & {\tt -{}-periodicBox} &                 map to the periodic box  (default=off)\\
268 –  -z & {\tt -{}-zconstraint}  &                replace the atom types of zconstraint molecules  (default=off) \\
269 –  -r & {\tt -{}-rigidbody}  &                  add a pseudo COM atom to rigidbody  (default=off) \\
270 –  -t & {\tt -{}-watertype} &                   replace the atom type of water model (default=on) \\
271 –  -b & {\tt -{}-basetype}  &                   using base atom type  (default=off) \\
272 –     & {\tt -{}-repeatX=INT}  &                 The number of images to repeat in the x direction  (default=`0') \\
273 –     & {\tt -{}-repeatY=INT} &                 The number of images to repeat in the y direction  (default=`0') \\
274 –     &  {\tt -{}-repeatZ=INT}  &                The number of images to repeat in the z direction  (default=`0') \\
275 –  -s & {\tt -{}-selection=selection script} & By specifying {\tt -{}-selection}=``selection command'' with Dump2XYZ, the user can select an arbitrary set of StuntDoubles to be
276 – converted. \\
277 –     & {\tt -{}-originsele} & By specifying {\tt -{}-originsele}=``selection command'' with Dump2XYZ, the user can re-center the origin of the system around a specific StuntDouble \\
278 –     & {\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}.
279 – \end{longtable}
280 –
281 –
474   \subsection{\label{appendixSection:StaticProps}StaticProps}
475  
476   {\tt StaticProps} can compute properties which are averaged over
477   some or all of the configurations that are contained within a dump
478   file. The most common example of a static property that can be
479   computed is the pair distribution function between atoms of type $A$
480 < and other atoms of type $B$, $g_{AB}(r)$.  StaticProps can also be
481 < used to compute the density distributions of other molecules in a
482 < reference frame {\it fixed to the body-fixed reference frame} of a
483 < selected atom or rigid body.
480 > and other atoms of type $B$, $g_{AB}(r)$.  {\tt StaticProps} can
481 > also be used to compute the density distributions of other molecules
482 > in a reference frame {\it fixed to the body-fixed reference frame}
483 > of a selected atom or rigid body. Due to the fact that the selected
484 > StuntDoubles from two selections may be overlapped, {\tt
485 > StaticProps} performs the calculation in three stages which are
486 > illustrated in Fig.~\ref{oopseFig:staticPropsProcess}.
487 >
488 > \begin{figure}
489 > \centering
490 > \includegraphics[width=\linewidth]{staticPropsProcess.eps}
491 > \caption[A representation of the three-stage correlations in
492 > \texttt{StaticProps}]{This diagram illustrates three-stage
493 > processing used by \texttt{StaticProps}. $S_1$ and $S_2$ are the
494 > numbers of selected StuntDobules from {\tt -{}-sele1} and {\tt
495 > -{}-sele2} respectively, while $C$ is the number of StuntDobules
496 > appearing at both sets. The first stage($S_1-C$ and $S_2$) and
497 > second stages ($S_1$ and $S_2-C$) are completely non-overlapping. On
498 > the contrary, the third stage($C$ and $C$) are completely
499 > overlapping} \label{oopseFig:staticPropsProcess}
500 > \end{figure}
501  
502 + \begin{figure}
503 + \centering
504 + \includegraphics[width=3in]{definition.eps}
505 + \caption[Definitions of the angles between directional objects]{Any
506 + two directional objects (DirectionalAtoms and RigidBodies) have a
507 + set of two angles ($\theta$, and $\omega$) between the z-axes of
508 + their body-fixed frames.} \label{oopseFig:gofr}
509 + \end{figure}
510 +
511   There are five seperate radial distribution functions availiable in
512   OOPSE. Since every radial distrbution function invlove the
513   calculation between pairs of bodies, {\tt -{}-sele1} and {\tt
# Line 333 | Line 551 | distribution functions are most easily seen in the fig
551   \end{description}
552  
553   The vectors (and angles) associated with these angular pair
554 < distribution functions are most easily seen in the figure below:
554 > distribution functions are most easily seen in
555 > Fig.~\ref{oopseFig:gofr}.
556  
338 – \begin{figure}
339 – \centering
340 – \includegraphics[width=3in]{definition.eps}
341 – \caption[Definitions of the angles between directional objects]{ \\
342 – Any two directional objects (DirectionalAtoms and RigidBodies) have
343 – a set of two angles ($\theta$, and $\omega$) between the z-axes of
344 – their body-fixed frames.} \label{oopseFig:gofr}
345 – \end{figure}
346 –
557   The options available for {\tt StaticProps} are as follows:
558   \begin{longtable}[c]{|EFG|}
559   \caption{StaticProps Command-line Options}
# Line 354 | Line 564 | The options available for {\tt StaticProps} are as fol
564   \endfoot
565    -h& {\tt -{}-help}                    &  Print help and exit \\
566    -V& {\tt -{}-version}                 &  Print version and exit \\
567 <  -i& {\tt -{}-input=filename}          &  input dump file \\
568 <  -o& {\tt -{}-output=filename}         &  output file name \\
569 <  -n& {\tt -{}-step=INT}                &  process every n frame  (default=`1') \\
570 <  -r& {\tt -{}-nrbins=INT}              &  number of bins for distance  (default=`100') \\
571 <  -a& {\tt -{}-nanglebins=INT}          &  number of bins for cos(angle)  (default= `50') \\
572 <  -l& {\tt -{}-length=DOUBLE}           &  maximum length (Defaults to 1/2 smallest length of first frame) \\
573 <    & {\tt -{}-sele1=selection script}   & select the first StuntDouble set \\
574 <    & {\tt -{}-sele2=selection script}   & select the second StuntDouble set \\
575 <    & {\tt -{}-sele3=selection script}   & select the third StuntDouble set \\
576 <    & {\tt -{}-refsele=selection script} & select reference (can only be used with {\tt -{}-gxyz}) \\
577 <    & {\tt -{}-molname=STRING}           & molecule name \\
578 <    & {\tt -{}-begin=INT}                & begin internal index \\
579 <    & {\tt -{}-end=INT}                  & end internal index \\
567 >  -i& {\tt -{}-input}          &  input dump file \\
568 >  -o& {\tt -{}-output}         &  output file name \\
569 >  -n& {\tt -{}-step}                &  process every n frame  (default=`1') \\
570 >  -r& {\tt -{}-nrbins}              &  number of bins for distance  (default=`100') \\
571 >  -a& {\tt -{}-nanglebins}          &  number of bins for cos(angle)  (default= `50') \\
572 >  -l& {\tt -{}-length}           &  maximum length (Defaults to 1/2 smallest length of first frame) \\
573 >    & {\tt -{}-sele1}   & select the first StuntDouble set \\
574 >    & {\tt -{}-sele2}   & select the second StuntDouble set \\
575 >    & {\tt -{}-sele3}   & select the third StuntDouble set \\
576 >    & {\tt -{}-refsele} & select reference (can only be used with {\tt -{}-gxyz}) \\
577 >    & {\tt -{}-molname}           & molecule name \\
578 >    & {\tt -{}-begin}                & begin internal index \\
579 >    & {\tt -{}-end}                  & end internal index \\
580   \hline
581   \multicolumn{3}{|l|}{One option from the following group of options is required:} \\
582   \hline
# Line 405 | Line 615 | The options available for DynamicProps are as follows:
615   different vectors).  The ability to use two selection scripts to
616   select different types of atoms is already present in the code.
617  
618 + For large simulations, the trajectory files can sometimes reach
619 + sizes in excess of several gigabytes. In order to prevent a
620 + situation where the program runs out of memory due to large
621 + trajectories, \texttt{dynamicProps} will first estimate the size of
622 + free memory, and determine the number of frames in each block, which
623 + will allow the operating system to load two blocks of data
624 + simultaneously without swapping. Upon reading two blocks of the
625 + trajectory, \texttt{dynamicProps} will calculate the time
626 + correlation within the first block and the cross correlations
627 + between the two blocks. This second block is then freed and then
628 + incremented and the process repeated until the end of the
629 + trajectory. Once the end is reached, the first block is freed then
630 + incremented, until all frame pairs have been correlated in time.
631 + This process is illustrated in
632 + Fig.~\ref{oopseFig:dynamicPropsProcess}.
633 +
634 + \begin{figure}
635 + \centering
636 + \includegraphics[width=\linewidth]{dynamicPropsProcess.eps}
637 + \caption[A representation of the block correlations in
638 + \texttt{dynamicProps}]{This diagram illustrates block correlations
639 + processing in \texttt{dynamicProps}. The shaded region represents
640 + the self correlation of the block, and the open blocks are read one
641 + at a time and the cross correlations between blocks are calculated.}
642 + \label{oopseFig:dynamicPropsProcess}
643 + \end{figure}
644 +
645   The options available for DynamicProps are as follows:
646   \begin{longtable}[c]{|EFG|}
647   \caption{DynamicProps Command-line Options}
# Line 415 | Line 652 | The options available for DynamicProps are as follows:
652   \endfoot
653    -h& {\tt -{}-help}                   & Print help and exit \\
654    -V& {\tt -{}-version}                & Print version and exit \\
655 <  -i& {\tt -{}-input=filename}         & input dump file \\
656 <  -o& {\tt -{}-output=filename}        & output file name \\
657 <    & {\tt -{}-sele1=selection script} & select first StuntDouble set \\
658 <    & {\tt -{}-sele2=selection script} & select second StuntDouble set (if sele2 is not set, use script from sele1) \\
655 >  -i& {\tt -{}-input}         & input dump file \\
656 >  -o& {\tt -{}-output}        & output file name \\
657 >    & {\tt -{}-sele1} & select first StuntDouble set \\
658 >    & {\tt -{}-sele2} & select second StuntDouble set (if sele2 is not set, use script from sele1) \\
659   \hline
660   \multicolumn{3}{|l|}{One option from the following group of options is required:} \\
661   \hline
# Line 427 | Line 664 | The options available for DynamicProps are as follows:
664    -d& {\tt -{}-dcorr}                  & compute dipole correlation function
665   \end{longtable}
666  
667 < \subsection{\label{appendixSection:hydrodynamics}Hydrodynamics}
667 > \section{\label{appendixSection:tools}Other Useful Utilities}
668 >
669 > \subsection{\label{appendixSection:Dump2XYZ}Dump2XYZ}
670 >
671 > {\tt Dump2XYZ} can transform an OOPSE dump file into a xyz file
672 > which can be opened by other molecular dynamics viewers such as Jmol
673 > and VMD\cite{Humphrey1996}. The options available for Dump2XYZ are
674 > as follows:
675 >
676 >
677 > \begin{longtable}[c]{|EFG|}
678 > \caption{Dump2XYZ Command-line Options}
679 > \\ \hline
680 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
681 > \endhead
682 > \hline
683 > \endfoot
684 >  -h & {\tt -{}-help} &                        Print help and exit \\
685 >  -V & {\tt -{}-version} &                     Print version and exit \\
686 >  -i & {\tt -{}-input}  &             input dump file \\
687 >  -o & {\tt -{}-output} &             output file name \\
688 >  -n & {\tt -{}-frame}   &                 print every n frame  (default=`1') \\
689 >  -w & {\tt -{}-water}       &                 skip the the waters  (default=off) \\
690 >  -m & {\tt -{}-periodicBox} &                 map to the periodic box  (default=off)\\
691 >  -z & {\tt -{}-zconstraint}  &                replace the atom types of zconstraint molecules  (default=off) \\
692 >  -r & {\tt -{}-rigidbody}  &                  add a pseudo COM atom to rigidbody  (default=off) \\
693 >  -t & {\tt -{}-watertype} &                   replace the atom type of water model (default=on) \\
694 >  -b & {\tt -{}-basetype}  &                   using base atom type  (default=off) \\
695 >     & {\tt -{}-repeatX}  &                 The number of images to repeat in the x direction  (default=`0') \\
696 >     & {\tt -{}-repeatY} &                 The number of images to repeat in the y direction  (default=`0') \\
697 >     &  {\tt -{}-repeatZ}  &                The number of images to repeat in the z direction  (default=`0') \\
698 >  -s & {\tt -{}-selection} & By specifying {\tt -{}-selection}=``selection command'' with Dump2XYZ, the user can select an arbitrary set of StuntDoubles to be
699 > converted. \\
700 >     & {\tt -{}-originsele} & By specifying {\tt -{}-originsele}=``selection command'' with Dump2XYZ, the user can re-center the origin of the system around a specific StuntDouble \\
701 >     & {\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}.
702 > \end{longtable}
703 >
704 > \subsection{\label{appendixSection:hydrodynamics}Hydro}
705 >
706 > {\tt Hydro} can calculate resistance and diffusion tensors at the
707 > center of resistance. Both tensors at the center of diffusion can
708 > also be reported from the program, as well as the coordinates for
709 > the beads which are used to approximate the arbitrary shapes. The
710 > options available for Hydro are as follows:
711 > \begin{longtable}[c]{|EFG|}
712 > \caption{Hydrodynamics Command-line Options}
713 > \\ \hline
714 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
715 > \endhead
716 > \hline
717 > \endfoot
718 >  -h & {\tt -{}-help} &                        Print help and exit \\
719 >  -V & {\tt -{}-version} &                     Print version and exit \\
720 >  -i & {\tt -{}-input}  &             input dump file \\
721 >  -o & {\tt -{}-output} &             output file prefix  (default=`hydro') \\
722 >  -b & {\tt -{}-beads}  &                   generate the beads only, hydrodynamics calculation will not be performed (default=off)\\
723 >     & {\tt -{}-model}  &                 hydrodynamics model (supports ``AnalyticalModel'', ``RoughShell'' and ``BeadModel'') \\
724 > \end{longtable}

Diff Legend

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