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 2685 by tim, Mon Apr 3 18:07:54 2006 UTC vs.
Revision 2840 by tim, Fri Jun 9 02:54:01 2006 UTC

# Line 1 | Line 1
1 < \chapter{\label{chapt:appendix}APPENDIX}
1 > \appendix
2 > \chapter{\label{chapt:oopse}Object-Oriented Parallel Simulation Engine}
3  
4 + Absence of applying modern software development practices is the
5 + bottleneck of Scientific Computing community\cite{Wilson2006}. In
6 + the last 20 years , there are quite a few MD packages that were
7 + developed to solve common MD problems and perform robust simulations
8 + . However, many of the codes are legacy programs that are either
9 + poorly organized or extremely complex. Usually, these packages were
10 + contributed by scientists without official computer science
11 + training. The development of most MD applications are lack of strong
12 + coordination to enforce design and programming guidelines. Moreover,
13 + most MD programs also suffer from missing design and implement
14 + documents which is crucial to the maintenance and extensibility.
15 + Along the way of studying structural and dynamic processes in
16 + condensed phase systems like biological membranes and nanoparticles,
17 + we developed and maintained an Object-Oriented Parallel Simulation
18 + Engine ({\sc OOPSE}). This new molecular dynamics package has some
19 + unique features
20 + \begin{enumerate}
21 +  \item {\sc OOPSE} performs Molecular Dynamics (MD) simulations on non-standard
22 + atom types (transition metals, point dipoles, sticky potentials,
23 + Gay-Berne ellipsoids, or other "lumpy"atoms with orientational
24 + degrees of freedom), as well as rigid bodies.
25 +  \item {\sc OOPSE} uses a force-based decomposition algorithm using MPI on cheap
26 + Beowulf clusters to obtain very efficient parallelism.
27 +  \item {\sc OOPSE} integrates the equations of motion using advanced methods for
28 + orientational dynamics in NVE, NVT, NPT, NPAT, and NP$\gamma$T
29 + ensembles.
30 +  \item {\sc OOPSE} can carry out simulations on metallic systems using the
31 + Embedded Atom Method (EAM) as well as the Sutton-Chen potential.
32 +  \item {\sc OOPSE} can perform simulations on Gay-Berne liquid crystals.
33 +  \item  {\sc OOPSE} can simulate systems containing the extremely efficient
34 + extended-Soft Sticky Dipole (SSD/E) model for water.
35 + \end{enumerate}
36 +
37 + \section{\label{appendixSection:architecture }Architecture}
38 +
39 + Mainly written by \texttt{C/C++} and \texttt{Fortran90}, {\sc OOPSE}
40 + uses C++ Standard Template Library (STL) and fortran modules as the
41 + foundation. As an extensive set of the STL and Fortran90 modules,
42 + {\sc Base Classes} provide generic implementations of mathematical
43 + objects (e.g., matrices, vectors, polynomials, random number
44 + generators) and advanced data structures and algorithms(e.g., tuple,
45 + bitset, generic data, string manipulation). The molecular data
46 + structures for the representation of atoms, bonds, bends, torsions,
47 + rigid bodies and molecules \textit{etc} are contained in the {\sc
48 + Kernel} which is implemented with {\sc Base Classes} and are
49 + carefully designed to provide maximum extensibility and flexibility.
50 + The functionality required for applications is provide by the third
51 + layer which contains Input/Output, Molecular Mechanics and Structure
52 + modules. Input/Output module not only implements general methods for
53 + file handling, but also defines a generic force field interface.
54 + Another important component of Input/Output module is the meta-data
55 + file parser, which is rewritten using ANother Tool for Language
56 + Recognition(ANTLR)\cite{Parr1995, Schaps1999} syntax. The Molecular
57 + Mechanics module consists of energy minimization and a wide
58 + varieties of integration methods(see Chap.~\ref{chapt:methodology}).
59 + The structure module contains a flexible and powerful selection
60 + library which syntax is elaborated in
61 + Sec.~\ref{appendixSection:syntax}. The top layer is made of the main
62 + program of the package, \texttt{oopse} and it corresponding parallel
63 + version \texttt{oopse\_MPI}, as well as other useful utilities, such
64 + as \texttt{StatProps} (see Sec.~\ref{appendixSection:StaticProps}),
65 + \texttt{DynamicProps} (see Sec.~\ref{appendixSection:DynamicProps}),
66 + \texttt{Dump2XYZ} (see Sec.~\ref{appendixSection:Dump2XYZ}),
67 + \texttt{Hydro} (see Sec.~\ref{appendixSection:hydrodynamics})
68 + \textit{etc}.
69 +
70 + \begin{figure}
71 + \centering
72 + \includegraphics[width=\linewidth]{architecture.eps}
73 + \caption[The architecture of {\sc OOPSE}] {Overview of the structure
74 + of {\sc OOPSE}} \label{appendixFig:architecture}
75 + \end{figure}
76 +
77   \section{\label{appendixSection:desginPattern}Design Pattern}
78  
79 + Design patterns are optimal solutions to commonly-occurring problems
80 + in software design. Although originated as an architectural concept
81 + for buildings and towns by Christopher Alexander
82 + \cite{Alexander1987}, software patterns first became popular with
83 + the wide acceptance of the book, Design Patterns: Elements of
84 + Reusable Object-Oriented Software \cite{Gamma1994}. Patterns reflect
85 + the experience, knowledge and insights of developers who have
86 + successfully used these patterns in their own work. Patterns are
87 + reusable. They provide a ready-made solution that can be adapted to
88 + different problems as necessary. Pattern are expressive. they
89 + provide a common vocabulary of solutions that can express large
90 + solutions succinctly.
91  
92 < \subsection{\label{appendixSection:visitorPattern}Visitor Pattern}
92 > Patterns are usually described using a format that includes the
93 > following information:
94 > \begin{enumerate}
95 >  \item The \emph{name} that is commonly used for the pattern. Good pattern names form a vocabulary for
96 >  discussing conceptual abstractions. a pattern may have more than one commonly used or recognizable name
97 >  in the literature. In this case it is common practice to document these nicknames or synonyms under
98 >  the heading of \emph{Aliases} or \emph{Also Known As}.
99 >  \item The \emph{motivation} or \emph{context} that this pattern applies
100 >  to. Sometimes, it will include some prerequisites that should be satisfied before deciding to use a pattern
101 >  \item The \emph{solution} to the problem that the pattern
102 >  addresses. It describes how to construct the necessary work products. The description may include
103 >  pictures, diagrams and prose which identify the pattern's structure, its participants, and their
104 >  collaborations, to show how the problem is solved.
105 >  \item The \emph{consequences} of using the given solution to solve a
106 >  problem, both positive and negative.
107 > \end{enumerate}
108  
109 < \subsection{\label{appendixSection:templatePattern}Template Pattern}
109 > As one of the latest advanced techniques emerged from
110 > object-oriented community, design patterns were applied in some of
111 > the modern scientific software applications, such as JMol, {\sc
112 > OOPSE}\cite{Meineke2005} and PROTOMOL\cite{Matthey2005}
113 > \textit{etc}. The following sections enumerates some of the patterns
114 > used in {\sc OOPSE}.
115  
116 < \subsection{\label{appendixSection:factoryPattern}Factory Pattern}
116 > \subsection{\label{appendixSection:singleton}Singleton}
117  
118 < \section{\label{appendixSection:hierarchy}Hierarchy}
118 > The Singleton pattern not only provides a mechanism to restrict
119 > instantiation of a class to one object, but also provides a global
120 > point of access to the object. Currently implemented as a global
121 > variable, the logging utility which reports error and warning
122 > messages to the console in {\sc OOPSE} is a good candidate for
123 > applying the Singleton pattern to avoid the global namespace
124 > pollution.Although the singleton pattern can be implemented in
125 > various ways  to account for different aspects of the software
126 > designs, such as lifespan control \textit{etc}, we only use the
127 > static data approach in {\sc OOPSE}. IntegratorFactory class is
128 > declared as
129  
130 < \section{\label{appendixSection:selectionSyntax}Selection Syntax}
130 > \begin{lstlisting}[float,caption={[A classic Singleton design pattern implementation(I)] The declaration of of simple Singleton pattern.},label={appendixScheme:singletonDeclaration}]
131  
132 < \section{\label{appendixSection:hydrodynamics}Hydrodynamics}
132 > class IntegratorFactory {
133 > public:
134 >  static IntegratorFactory*
135 >  getInstance();
136 > protected:
137 >  IntegratorFactory();
138 > private:
139 >  static IntegratorFactory* instance_;
140 > };
141  
142 < \section{\label{appendixSection:analysisFramework}Analysis Framework}
142 > \end{lstlisting}
143  
144 < \subsection{\label{appendixSection:staticProps}Factory Properties}
144 > The corresponding implementation is
145  
146 < \subsection{\label{appendixSection:dynamicProps}Dynamics Properties}
146 > \begin{lstlisting}[float,caption={[A classic implementation of Singleton design pattern (II)] The implementation of simple Singleton pattern.},label={appendixScheme:singletonImplementation}]
147 >
148 > IntegratorFactory::instance_ = NULL;
149 >
150 > IntegratorFactory* getInstance() {
151 >  if (instance_ == NULL){
152 >    instance_ = new IntegratorFactory;
153 >  }
154 >  return instance_;
155 > }
156 >
157 > \end{lstlisting}
158 >
159 > Since constructor is declared as protected, a client can not
160 > instantiate IntegratorFactory directly. Moreover, since the member
161 > function getInstance serves as the only entry of access to
162 > IntegratorFactory, this approach fulfills the basic requirement, a
163 > single instance. Another consequence of this approach is the
164 > automatic destruction since static data are destroyed upon program
165 > termination.
166 >
167 > \subsection{\label{appendixSection:factoryMethod}Factory Method}
168 >
169 > Categoried as a creational pattern, the Factory Method pattern deals
170 > with the problem of creating objects without specifying the exact
171 > class of object that will be created. Factory Method is typically
172 > implemented by delegating the creation operation to the subclasses.
173 > Parameterized Factory pattern where factory method (
174 > createIntegrator member function) creates products based on the
175 > identifier (see List.~\ref{appendixScheme:factoryDeclaration}). If
176 > the identifier has been already registered, the factory method will
177 > invoke the corresponding creator (see List.~\ref{integratorCreator})
178 > which utilizes the modern C++ template technique to avoid excess
179 > subclassing.
180 >
181 > \begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (I)]Source code of IntegratorFactory class.},label={appendixScheme:factoryDeclaration}]
182 >
183 > class IntegratorFactory {
184 > public:
185 >  typedef std::map<string, IntegratorCreator*> CreatorMapType;
186 >
187 >  bool registerIntegrator(IntegratorCreator* creator) {
188 >    return creatorMap_.insert(creator->getIdent(), creator).second;
189 >  }
190 >
191 >  Integrator* createIntegrator(const string& id, SimInfo* info) {
192 >    Integrator* result = NULL;
193 >    CreatorMapType::iterator i = creatorMap_.find(id);
194 >    if (i != creatorMap_.end()) {
195 >      result = (i->second)->create(info);
196 >    }
197 >    return result;
198 >  }
199 >
200 > private:
201 >  CreatorMapType creatorMap_;
202 > };
203 > \end{lstlisting}
204 >
205 > \begin{lstlisting}[float,caption={[The implementation of Parameterized Factory pattern (III)]Source code of creator classes.},label={appendixScheme:integratorCreator}]
206 >
207 > class IntegratorCreator {
208 > public:
209 >    IntegratorCreator(const string& ident) : ident_(ident) {}
210 >
211 >    const string& getIdent() const { return ident_; }
212 >
213 >    virtual Integrator* create(SimInfo* info) const = 0;
214 >
215 > private:
216 >    string ident_;
217 > };
218 >
219 > template<class ConcreteIntegrator>
220 > class IntegratorBuilder : public IntegratorCreator {
221 > public:
222 >  IntegratorBuilder(const string& ident)
223 >                   : IntegratorCreator(ident) {}
224 >  virtual  Integrator* create(SimInfo* info) const {
225 >    return new ConcreteIntegrator(info);
226 >  }
227 > };
228 > \end{lstlisting}
229 >
230 > \subsection{\label{appendixSection:visitorPattern}Visitor}
231 >
232 > The visitor pattern is designed to decouple the data structure and
233 > algorithms used upon them by collecting related operation from
234 > element classes into other visitor classes, which is equivalent to
235 > adding virtual functions into a set of classes without modifying
236 > their interfaces. Fig.~\ref{appendixFig:visitorUML} demonstrates the
237 > structure of Visitor pattern which is used extensively in {\tt
238 > Dump2XYZ}. In order to convert an OOPSE dump file, a series of
239 > distinct operations are performed on different StuntDoubles (See the
240 > class hierarchy in Fig.~\ref{oopseFig:hierarchy} and the declaration
241 > in List.~\ref{appendixScheme:element}). Since the hierarchies
242 > remains stable, it is easy to define a visit operation (see
243 > List.~\ref{appendixScheme:visitor}) for each class of StuntDouble.
244 > Note that using Composite pattern\cite{Gamma1994}, CompositVisitor
245 > manages a priority visitor list and handles the execution of every
246 > visitor in the priority list on different StuntDoubles.
247 >
248 > \begin{figure}
249 > \centering
250 > \includegraphics[width=\linewidth]{visitor.eps}
251 > \caption[The UML class diagram of Visitor patten] {The UML class
252 > diagram of Visitor patten.} \label{appendixFig:visitorUML}
253 > \end{figure}
254 >
255 > \begin{figure}
256 > \centering
257 > \includegraphics[width=\linewidth]{hierarchy.eps}
258 > \caption[Class hierarchy for ojects in {\sc OOPSE}]{ A diagram of
259 > the class hierarchy. } \label{oopseFig:hierarchy}
260 > \end{figure}
261 >
262 > \begin{lstlisting}[float,caption={[The implementation of Visitor pattern (II)]Source code of the element classes.},label={appendixScheme:element}]
263 >
264 > class StuntDouble { public:
265 >  virtual void accept(BaseVisitor* v) = 0;
266 > };
267 >
268 > class Atom: public StuntDouble { public:
269 >  virtual void accept{BaseVisitor* v*} {
270 >    v->visit(this);
271 >  }
272 > };
273 >
274 > class DirectionalAtom: public Atom { public:
275 >  virtual void accept{BaseVisitor* v*} {
276 >    v->visit(this);
277 >  }
278 > };
279 >
280 > class RigidBody: public StuntDouble { public:
281 >  virtual void accept{BaseVisitor* v*} {
282 >    v->visit(this);
283 >  }
284 > };
285 >
286 > \end{lstlisting}
287 >
288 > \begin{lstlisting}[float,caption={[The implementation of Visitor pattern (I)]Source code of the visitor classes.},label={appendixScheme:visitor}]
289 >
290 > class BaseVisitor{
291 > public:
292 >  virtual void visit(Atom* atom);
293 >  virtual void visit(DirectionalAtom* datom);
294 >  virtual void visit(RigidBody* rb);
295 > };
296 >
297 > class BaseAtomVisitor:public BaseVisitor{ public:
298 >  virtual void visit(Atom* atom);
299 >  virtual void visit(DirectionalAtom* datom);
300 >  virtual void visit(RigidBody* rb);
301 > };
302 >
303 > class SSDAtomVisitor:public BaseAtomVisitor{ public:
304 >  virtual void visit(Atom* atom);
305 >  virtual void visit(DirectionalAtom* datom);
306 >  virtual void visit(RigidBody* rb);
307 > };
308 >
309 > class CompositeVisitor: public BaseVisitor {
310 > public:
311 >
312 >  typedef list<pair<BaseVisitor*, int> > VistorListType;
313 >  typedef VistorListType::iterator VisitorListIterator;
314 >  virtual void visit(Atom* atom) {
315 >    VisitorListIterator i;
316 >    BaseVisitor* curVisitor;
317 >    for(i = visitorList.begin();i != visitorList.end();++i) {
318 >      atom->accept(*i);
319 >    }
320 >  }
321 >
322 >  virtual void visit(DirectionalAtom* datom) {
323 >    VisitorListIterator i;
324 >    BaseVisitor* curVisitor;
325 >    for(i = visitorList.begin();i != visitorList.end();++i) {
326 >      atom->accept(*i);
327 >    }
328 >  }
329 >
330 >  virtual void visit(RigidBody* rb) {
331 >    VisitorListIterator i;
332 >    std::vector<Atom*> myAtoms;
333 >    std::vector<Atom*>::iterator ai;
334 >    myAtoms = rb->getAtoms();
335 >    for(i = visitorList.begin();i != visitorList.end();++i) {{
336 >      rb->accept(*i);
337 >      for(ai = myAtoms.begin(); ai != myAtoms.end(); ++ai){
338 >        (*ai)->accept(*i);
339 >    }
340 >  }
341 >
342 >  void addVisitor(BaseVisitor* v, int priority);
343 >
344 >  protected:
345 >    VistorListType visitorList;
346 > };
347 >
348 > \end{lstlisting}
349 >
350 > \section{\label{appendixSection:concepts}Concepts}
351 >
352 > OOPSE manipulates both traditional atoms as well as some objects
353 > that {\it behave like atoms}.  These objects can be rigid
354 > collections of atoms or atoms which have orientational degrees of
355 > freedom.  A diagram of the class hierarchy is illustrated in
356 > Fig.~\ref{oopseFig:hierarchy}. Every Molecule, Atom and
357 > DirectionalAtom in {\sc OOPSE} have their own names which are
358 > specified in the {\tt .md} file. In contrast, RigidBodies are
359 > denoted by their membership and index inside a particular molecule:
360 > [MoleculeName]\_RB\_[index] (the contents inside the brackets depend
361 > on the specifics of the simulation). The names of rigid bodies are
362 > generated automatically. For example, the name of the first rigid
363 > body in a DMPC molecule is DMPC\_RB\_0.
364 > \begin{itemize}
365 > \item A {\bf StuntDouble} is {\it any} object that can be manipulated by the
366 > integrators and minimizers.
367 > \item An {\bf Atom} is a fundamental point-particle that can be moved around during a simulation.
368 > \item A {\bf DirectionalAtom} is an atom which has {\it orientational} as well as translational degrees of freedom.
369 > \item A {\bf RigidBody} is a collection of {\bf Atom}s or {\bf
370 > DirectionalAtom}s which behaves as a single unit.
371 > \end{itemize}
372 >
373 > \section{\label{appendixSection:syntax}Syntax of the Select Command}
374 >
375 > {\sc OOPSE} provides a powerful selection utility to select
376 > StuntDoubles. The most general form of the select command is:
377 >
378 > {\tt select {\it expression}}.
379 >
380 > This expression represents an arbitrary set of StuntDoubles (Atoms
381 > or RigidBodies) in {\sc OOPSE}. Expressions are composed of either
382 > name expressions, index expressions, predefined sets, user-defined
383 > expressions, comparison operators, within expressions, or logical
384 > combinations of the above expression types. Expressions can be
385 > combined using parentheses and the Boolean operators.
386 >
387 > \subsection{\label{appendixSection:logical}Logical expressions}
388 >
389 > The logical operators allow complex queries to be constructed out of
390 > simpler ones using the standard boolean connectives {\bf and}, {\bf
391 > or}, {\bf not}. Parentheses can be used to alter the precedence of
392 > the operators.
393 >
394 > \begin{center}
395 > \begin{tabular}{|ll|}
396 > \hline
397 > {\bf logical operator} & {\bf equivalent operator}  \\
398 > \hline
399 > and & ``\&'', ``\&\&'' \\
400 > or & ``$|$'', ``$||$'', ``,'' \\
401 > not & ``!''  \\
402 > \hline
403 > \end{tabular}
404 > \end{center}
405 >
406 > \subsection{\label{appendixSection:name}Name expressions}
407 >
408 > \begin{center}
409 > \begin{tabular}{|llp{2in}|}
410 > \hline {\bf type of expression} & {\bf examples} & {\bf translation
411 > of
412 > examples} \\
413 > \hline expression without ``.'' & select DMPC & select all
414 > StuntDoubles
415 > belonging to all DMPC molecules \\
416 > & select C* & select all atoms which have atom types beginning with C
417 > \\
418 > & select DMPC\_RB\_* & select all RigidBodies in DMPC molecules (but
419 > only select the rigid bodies, and not the atoms belonging to them). \\
420 > \hline expression has one ``.'' & select TIP3P.O\_TIP3P & select the
421 > O\_TIP3P
422 > atoms belonging to TIP3P molecules \\
423 > & select DMPC\_RB\_O.PO4 & select the PO4 atoms belonging to
424 > the first
425 > RigidBody in each DMPC molecule \\
426 > & select DMPC.20 & select the twentieth StuntDouble in each DMPC
427 > molecule \\
428 > \hline expression has two ``.''s & select DMPC.DMPC\_RB\_?.* &
429 > select all atoms
430 > belonging to all rigid bodies within all DMPC molecules \\
431 > \hline
432 > \end{tabular}
433 > \end{center}
434 >
435 > \subsection{\label{appendixSection:index}Index expressions}
436 >
437 > \begin{center}
438 > \begin{tabular}{|lp{4in}|}
439 > \hline
440 > {\bf examples} & {\bf translation of examples} \\
441 > \hline
442 > select 20 & select all of the StuntDoubles belonging to Molecule 20 \\
443 > select 20 to 30 & select all of the StuntDoubles belonging to
444 > molecules which have global indices between 20 (inclusive) and 30
445 > (exclusive) \\
446 > \hline
447 > \end{tabular}
448 > \end{center}
449 >
450 > \subsection{\label{appendixSection:predefined}Predefined sets}
451 >
452 > \begin{center}
453 > \begin{tabular}{|ll|}
454 > \hline
455 > {\bf keyword} & {\bf description} \\
456 > \hline
457 > all & select all StuntDoubles \\
458 > none & select none of the StuntDoubles \\
459 > \hline
460 > \end{tabular}
461 > \end{center}
462 >
463 > \subsection{\label{appendixSection:userdefined}User-defined expressions}
464 >
465 > Users can define arbitrary terms to represent groups of
466 > StuntDoubles, and then use the define terms in select commands. The
467 > general form for the define command is: {\bf define {\it term
468 > expression}}. Once defined, the user can specify such terms in
469 > boolean expressions
470 >
471 > {\tt define SSDWATER SSD or SSD1 or SSDRF}
472 >
473 > {\tt select SSDWATER}
474 >
475 > \subsection{\label{appendixSection:comparison}Comparison expressions}
476 >
477 > StuntDoubles can be selected by using comparision operators on their
478 > properties. The general form for the comparison command is: a
479 > property name, followed by a comparision operator and then a number.
480 >
481 > \begin{center}
482 > \begin{tabular}{|l|l|}
483 > \hline
484 > {\bf property} & mass, charge \\
485 > {\bf comparison operator} & ``$>$'', ``$<$'', ``$=$'', ``$>=$'',
486 > ``$<=$'', ``$!=$'' \\
487 > \hline
488 > \end{tabular}
489 > \end{center}
490 >
491 > For example, the phrase {\tt select mass > 16.0 and charge < -2}
492 > would select StuntDoubles which have mass greater than 16.0 and
493 > charges less than -2.
494 >
495 > \subsection{\label{appendixSection:within}Within expressions}
496 >
497 > The ``within'' keyword allows the user to select all StuntDoubles
498 > within the specified distance (in Angstroms) from a selection,
499 > including the selected atom itself. The general form for within
500 > selection is: {\tt select within(distance, expression)}
501 >
502 > For example, the phrase {\tt select within(2.5, PO4 or NC4)} would
503 > select all StuntDoubles which are within 2.5 angstroms of PO4 or NC4
504 > atoms.
505 >
506 >
507 > \section{\label{appendixSection:analysisFramework}Analysis Framework}
508 >
509 > \subsection{\label{appendixSection:StaticProps}StaticProps}
510 >
511 > {\tt StaticProps} can compute properties which are averaged over
512 > some or all of the configurations that are contained within a dump
513 > file. The most common example of a static property that can be
514 > computed is the pair distribution function between atoms of type $A$
515 > and other atoms of type $B$, $g_{AB}(r)$.  {\tt StaticProps} can
516 > also be used to compute the density distributions of other molecules
517 > in a reference frame {\it fixed to the body-fixed reference frame}
518 > of a selected atom or rigid body.
519 >
520 > There are five seperate radial distribution functions availiable in
521 > OOPSE. Since every radial distrbution function invlove the
522 > calculation between pairs of bodies, {\tt -{}-sele1} and {\tt
523 > -{}-sele2} must be specified to tell StaticProps which bodies to
524 > include in the calculation.
525 >
526 > \begin{description}
527 > \item[{\tt -{}-gofr}] Computes the pair distribution function,
528 > \begin{equation*}
529 > g_{AB}(r) = \frac{1}{\rho_B}\frac{1}{N_A} \langle \sum_{i \in A}
530 > \sum_{j \in B} \delta(r - r_{ij}) \rangle
531 > \end{equation*}
532 > \item[{\tt -{}-r\_theta}] Computes the angle-dependent pair distribution
533 > function. The angle is defined by the intermolecular vector
534 > $\vec{r}$ and $z$-axis of DirectionalAtom A,
535 > \begin{equation*}
536 > g_{AB}(r, \cos \theta) = \frac{1}{\rho_B}\frac{1}{N_A} \langle
537 > \sum_{i \in A} \sum_{j \in B} \delta(r - r_{ij}) \delta(\cos
538 > \theta_{ij} - \cos \theta)\rangle
539 > \end{equation*}
540 > \item[{\tt -{}-r\_omega}] Computes the angle-dependent pair distribution
541 > function. The angle is defined by the $z$-axes of the two
542 > DirectionalAtoms A and B.
543 > \begin{equation*}
544 > g_{AB}(r, \cos \omega) = \frac{1}{\rho_B}\frac{1}{N_A} \langle
545 > \sum_{i \in A} \sum_{j \in B} \delta(r - r_{ij}) \delta(\cos
546 > \omega_{ij} - \cos \omega)\rangle
547 > \end{equation*}
548 > \item[{\tt -{}-theta\_omega}] Computes the pair distribution in the angular
549 > space $\theta, \omega$ defined by the two angles mentioned above.
550 > \begin{equation*}
551 > g_{AB}(\cos\theta, \cos \omega) = \frac{1}{\rho_B}\frac{1}{N_A}
552 > \langle \sum_{i \in A} \sum_{j \in B} \langle \delta(\cos
553 > \theta_{ij} - \cos \theta) \delta(\cos \omega_{ij} - \cos
554 > \omega)\rangle
555 > \end{equation*}
556 > \item[{\tt -{}-gxyz}] Calculates the density distribution of particles of type
557 > B in the body frame of particle A. Therefore, {\tt -{}-originsele}
558 > and {\tt -{}-refsele} must be given to define A's internal
559 > coordinate set as the reference frame for the calculation.
560 > \end{description}
561 >
562 > The vectors (and angles) associated with these angular pair
563 > distribution functions are most easily seen in the figure below:
564 >
565 > \begin{figure}
566 > \centering
567 > \includegraphics[width=3in]{definition.eps}
568 > \caption[Definitions of the angles between directional objects]{ \\
569 > Any two directional objects (DirectionalAtoms and RigidBodies) have
570 > a set of two angles ($\theta$, and $\omega$) between the z-axes of
571 > their body-fixed frames.} \label{oopseFig:gofr}
572 > \end{figure}
573 >
574 > Due to the fact that the selected StuntDoubles from two selections
575 > may be overlapped, {\tt StaticProps} performs the calculation in
576 > three stages which are illustrated in
577 > Fig.~\ref{oopseFig:staticPropsProcess}.
578 >
579 > \begin{figure}
580 > \centering
581 > \includegraphics[width=\linewidth]{staticPropsProcess.eps}
582 > \caption[A representation of the three-stage correlations in
583 > \texttt{StaticProps}]{This diagram illustrates three-stage
584 > processing used by \texttt{StaticProps}. $S_1$ and $S_2$ are the
585 > numbers of selected stuntdobules from {\tt -{}-sele1} and {\tt
586 > -{}-sele2} respectively, while $C$ is the number of stuntdobules
587 > appearing at both sets. The first stage($S_1-C$ and $S_2$) and
588 > second stages ($S_1$ and $S_2-C$) are completely non-overlapping. On
589 > the contrary, the third stage($C$ and $C$) are completely
590 > overlapping} \label{oopseFig:staticPropsProcess}
591 > \end{figure}
592 >
593 > The options available for {\tt StaticProps} are as follows:
594 > \begin{longtable}[c]{|EFG|}
595 > \caption{StaticProps Command-line Options}
596 > \\ \hline
597 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
598 > \endhead
599 > \hline
600 > \endfoot
601 >  -h& {\tt -{}-help}                    &  Print help and exit \\
602 >  -V& {\tt -{}-version}                 &  Print version and exit \\
603 >  -i& {\tt -{}-input}          &  input dump file \\
604 >  -o& {\tt -{}-output}         &  output file name \\
605 >  -n& {\tt -{}-step}                &  process every n frame  (default=`1') \\
606 >  -r& {\tt -{}-nrbins}              &  number of bins for distance  (default=`100') \\
607 >  -a& {\tt -{}-nanglebins}          &  number of bins for cos(angle)  (default= `50') \\
608 >  -l& {\tt -{}-length}           &  maximum length (Defaults to 1/2 smallest length of first frame) \\
609 >    & {\tt -{}-sele1}   & select the first StuntDouble set \\
610 >    & {\tt -{}-sele2}   & select the second StuntDouble set \\
611 >    & {\tt -{}-sele3}   & select the third StuntDouble set \\
612 >    & {\tt -{}-refsele} & select reference (can only be used with {\tt -{}-gxyz}) \\
613 >    & {\tt -{}-molname}           & molecule name \\
614 >    & {\tt -{}-begin}                & begin internal index \\
615 >    & {\tt -{}-end}                  & end internal index \\
616 > \hline
617 > \multicolumn{3}{|l|}{One option from the following group of options is required:} \\
618 > \hline
619 >    &  {\tt -{}-gofr}                    &  $g(r)$ \\
620 >    &  {\tt -{}-r\_theta}                 &  $g(r, \cos(\theta))$ \\
621 >    &  {\tt -{}-r\_omega}                 &  $g(r, \cos(\omega))$ \\
622 >    &  {\tt -{}-theta\_omega}             &  $g(\cos(\theta), \cos(\omega))$ \\
623 >    &  {\tt -{}-gxyz}                    &  $g(x, y, z)$ \\
624 >    &  {\tt -{}-p2}                      &  $P_2$ order parameter ({\tt -{}-sele1} and {\tt -{}-sele2} must be specified) \\
625 >    &  {\tt -{}-scd}                     &  $S_{CD}$ order parameter(either {\tt -{}-sele1}, {\tt -{}-sele2}, {\tt -{}-sele3} are specified or {\tt -{}-molname}, {\tt -{}-begin}, {\tt -{}-end} are specified) \\
626 >    &  {\tt -{}-density}                 &  density plot ({\tt -{}-sele1} must be specified) \\
627 >    &  {\tt -{}-slab\_density}           &  slab density ({\tt -{}-sele1} must be specified)
628 > \end{longtable}
629 >
630 > \subsection{\label{appendixSection:DynamicProps}DynamicProps}
631 >
632 > {\tt DynamicProps} computes time correlation functions from the
633 > configurations stored in a dump file.  Typical examples of time
634 > correlation functions are the mean square displacement and the
635 > velocity autocorrelation functions.   Once again, the selection
636 > syntax can be used to specify the StuntDoubles that will be used for
637 > the calculation.  A general time correlation function can be thought
638 > of as:
639 > \begin{equation}
640 > C_{AB}(t) = \langle \vec{u}_A(t) \cdot \vec{v}_B(0) \rangle
641 > \end{equation}
642 > where $\vec{u}_A(t)$ is a vector property associated with an atom of
643 > type $A$ at time $t$, and $\vec{v}_B(t^{\prime})$ is a different
644 > vector property associated with an atom of type $B$ at a different
645 > time $t^{\prime}$.  In most autocorrelation functions, the vector
646 > properties ($\vec{v}$ and $\vec{u}$) and the types of atoms ($A$ and
647 > $B$) are identical, and the three calculations built in to {\tt
648 > DynamicProps} make these assumptions.  It is possible, however, to
649 > make simple modifications to the {\tt DynamicProps} code to allow
650 > the use of {\it cross} time correlation functions (i.e. with
651 > different vectors).  The ability to use two selection scripts to
652 > select different types of atoms is already present in the code.
653 >
654 > For large simulations, the trajectory files can sometimes reach
655 > sizes in excess of several gigabytes. In order to effectively
656 > analyze that amount of data. In order to prevent a situation where
657 > the program runs out of memory due to large trajectories,
658 > \texttt{dynamicProps} will estimate the size of free memory at
659 > first, and determine the number of frames in each block, which
660 > allows the operating system to load two blocks of data
661 > simultaneously without swapping. Upon reading two blocks of the
662 > trajectory, \texttt{dynamicProps} will calculate the time
663 > correlation within the first block and the cross correlations
664 > between the two blocks. This second block is then freed and then
665 > incremented and the process repeated until the end of the
666 > trajectory. Once the end is reached, the first block is freed then
667 > incremented, until all frame pairs have been correlated in time.
668 > This process is illustrated in
669 > Fig.~\ref{oopseFig:dynamicPropsProcess}.
670 >
671 > \begin{figure}
672 > \centering
673 > \includegraphics[width=\linewidth]{dynamicPropsProcess.eps}
674 > \caption[A representation of the block correlations in
675 > \texttt{dynamicProps}]{This diagram illustrates block correlations
676 > processing in \texttt{dynamicProps}. The shaded region represents
677 > the self correlation of the block, and the open blocks are read one
678 > at a time and the cross correlations between blocks are calculated.}
679 > \label{oopseFig:dynamicPropsProcess}
680 > \end{figure}
681 >
682 > The options available for DynamicProps are as follows:
683 > \begin{longtable}[c]{|EFG|}
684 > \caption{DynamicProps Command-line Options}
685 > \\ \hline
686 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
687 > \endhead
688 > \hline
689 > \endfoot
690 >  -h& {\tt -{}-help}                   & Print help and exit \\
691 >  -V& {\tt -{}-version}                & Print version and exit \\
692 >  -i& {\tt -{}-input}         & input dump file \\
693 >  -o& {\tt -{}-output}        & output file name \\
694 >    & {\tt -{}-sele1} & select first StuntDouble set \\
695 >    & {\tt -{}-sele2} & select second StuntDouble set (if sele2 is not set, use script from sele1) \\
696 > \hline
697 > \multicolumn{3}{|l|}{One option from the following group of options is required:} \\
698 > \hline
699 >  -r& {\tt -{}-rcorr}                  & compute mean square displacement \\
700 >  -v& {\tt -{}-vcorr}                  & compute velocity correlation function \\
701 >  -d& {\tt -{}-dcorr}                  & compute dipole correlation function
702 > \end{longtable}
703 >
704 > \section{\label{appendixSection:tools}Other Useful Utilities}
705 >
706 > \subsection{\label{appendixSection:Dump2XYZ}Dump2XYZ}
707 >
708 > {\tt Dump2XYZ} can transform an OOPSE dump file into a xyz file
709 > which can be opened by other molecular dynamics viewers such as Jmol
710 > and VMD\cite{Humphrey1996}. The options available for Dump2XYZ are
711 > as follows:
712 >
713 >
714 > \begin{longtable}[c]{|EFG|}
715 > \caption{Dump2XYZ Command-line Options}
716 > \\ \hline
717 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
718 > \endhead
719 > \hline
720 > \endfoot
721 >  -h & {\tt -{}-help} &                        Print help and exit \\
722 >  -V & {\tt -{}-version} &                     Print version and exit \\
723 >  -i & {\tt -{}-input}  &             input dump file \\
724 >  -o & {\tt -{}-output} &             output file name \\
725 >  -n & {\tt -{}-frame}   &                 print every n frame  (default=`1') \\
726 >  -w & {\tt -{}-water}       &                 skip the the waters  (default=off) \\
727 >  -m & {\tt -{}-periodicBox} &                 map to the periodic box  (default=off)\\
728 >  -z & {\tt -{}-zconstraint}  &                replace the atom types of zconstraint molecules  (default=off) \\
729 >  -r & {\tt -{}-rigidbody}  &                  add a pseudo COM atom to rigidbody  (default=off) \\
730 >  -t & {\tt -{}-watertype} &                   replace the atom type of water model (default=on) \\
731 >  -b & {\tt -{}-basetype}  &                   using base atom type  (default=off) \\
732 >     & {\tt -{}-repeatX}  &                 The number of images to repeat in the x direction  (default=`0') \\
733 >     & {\tt -{}-repeatY} &                 The number of images to repeat in the y direction  (default=`0') \\
734 >     &  {\tt -{}-repeatZ}  &                The number of images to repeat in the z direction  (default=`0') \\
735 >  -s & {\tt -{}-selection} & By specifying {\tt -{}-selection}=``selection command'' with Dump2XYZ, the user can select an arbitrary set of StuntDoubles to be
736 > converted. \\
737 >     & {\tt -{}-originsele} & By specifying {\tt -{}-originsele}=``selection command'' with Dump2XYZ, the user can re-center the origin of the system around a specific StuntDouble \\
738 >     & {\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}.
739 > \end{longtable}
740 >
741 > \subsection{\label{appendixSection:hydrodynamics}Hydro}
742 >
743 > {\tt Hydro} can calculate resistance and diffusion tensors at the
744 > center of resistance. Both tensors at the center of diffusion can
745 > also be reported from the program, as well as the coordinates for
746 > the beads which are used to approximate the arbitrary shapes. The
747 > options available for Hydro are as follows:
748 > \begin{longtable}[c]{|EFG|}
749 > \caption{Hydrodynamics Command-line Options}
750 > \\ \hline
751 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
752 > \endhead
753 > \hline
754 > \endfoot
755 >  -h & {\tt -{}-help} &                        Print help and exit \\
756 >  -V & {\tt -{}-version} &                     Print version and exit \\
757 >  -i & {\tt -{}-input}  &             input dump file \\
758 >  -o & {\tt -{}-output} &             output file prefix  (default=`hydro') \\
759 >  -b & {\tt -{}-beads}  &                   generate the beads only, hydrodynamics calculation will not be performed (default=off)\\
760 >     & {\tt -{}-model}  &                 hydrodynamics model (supports ``AnalyticalModel'', ``RoughShell'' and ``BeadModel'') \\
761 > \end{longtable}

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines