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

Diff Legend

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