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

Diff Legend

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