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 2811 by tim, Wed Jun 7 02:24:27 2006 UTC

# Line 1 | Line 1
1 + \appendix
2   \chapter{\label{chapt:appendix}APPENDIX}
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.
17 +
18   \section{\label{appendixSection:desginPattern}Design Pattern}
19  
20 + Design patterns are optimal solutions to commonly-occurring problems
21 + in software design. Although originated as an architectural concept
22 + for buildings and towns by Christopher Alexander
23 + \cite{Alexander1987}, software patterns first became popular with
24 + the wide acceptance of the book, Design Patterns: Elements of
25 + Reusable Object-Oriented Software \cite{Gamma1994}. Patterns reflect
26 + the experience, knowledge and insights of developers who have
27 + successfully used these patterns in their own work. Patterns are
28 + reusable. They provide a ready-made solution that can be adapted to
29 + different problems as necessary. Pattern are expressive. they
30 + provide a common vocabulary of solutions that can express large
31 + solutions succinctly.
32  
33 < \subsection{\label{appendixSection:visitorPattern}Visitor Pattern}
33 > Patterns are usually described using a format that includes the
34 > following information:
35 > \begin{enumerate}
36 >  \item The \emph{name} that is commonly used for the pattern. Good pattern names form a vocabulary for
37 >  discussing conceptual abstractions. a pattern may have more than one commonly used or recognizable name
38 >  in the literature. In this case it is common practice to document these nicknames or synonyms under
39 >  the heading of \emph{Aliases} or \emph{Also Known As}.
40 >  \item The \emph{motivation} or \emph{context} that this pattern applies
41 >  to. Sometimes, it will include some prerequisites that should be satisfied before deciding to use a pattern
42 >  \item The \emph{solution} to the problem that the pattern
43 >  addresses. It describes how to construct the necessary work products. The description may include
44 >  pictures, diagrams and prose which identify the pattern's structure, its participants, and their
45 >  collaborations, to show how the problem is solved.
46 >  \item The \emph{consequences} of using the given solution to solve a
47 >  problem, both positive and negative.
48 > \end{enumerate}
49  
50 < \subsection{\label{appendixSection:templatePattern}Template Pattern}
50 > As one of the latest advanced techniques emerged from
51 > object-oriented community, design patterns were applied in some of
52 > the modern scientific software applications, such as JMol, OOPSE
53 > \cite{Meineke05} and PROTOMOL \cite{Matthey05} \textit{etc}.
54  
55 < \subsection{\label{appendixSection:factoryPattern}Factory Pattern}
55 > \subsection{\label{appendixSection:singleton}Singleton}
56 > The Singleton pattern ensures that only one instance of a class is
57 > created. All objects that use an instance of that class use the same
58 > instance.
59  
60 < \section{\label{appendixSection:hierarchy}Hierarchy}
60 > \subsection{\label{appendixSection:factoryMethod}Factory Method}
61 > The Factory Method pattern is a creational pattern which deals with
62 > the problem of creating objects without specifying the exact class
63 > of object that will be created. Factory Method solves this problem
64 > by defining a separate method for creating the objects, which
65 > subclasses can then override to specify the derived type of product
66 > that will be created.
67  
14 \section{\label{appendixSection:selectionSyntax}Selection Syntax}
68  
69 < \section{\label{appendixSection:hydrodynamics}Hydrodynamics}
69 > \subsection{\label{appendixSection:visitorPattern}Visitor}
70 > The purpose of the Visitor Pattern is to encapsulate an operation
71 > that you want to perform on the elements of a data structure. In
72 > this way, you can change the operation being performed on a
73 > structure without the need of changing the classes of the elements
74 > that you are operating on.
75  
76 +
77 + \subsection{\label{appendixSection:templateMethod}Template Method}
78 +
79 + \section{\label{appendixSection:concepts}Concepts}
80 +
81 + OOPSE manipulates both traditional atoms as well as some objects
82 + that {\it behave like atoms}.  These objects can be rigid
83 + collections of atoms or atoms which have orientational degrees of
84 + freedom.  Here is a diagram of the class heirarchy:
85 +
86 + %\begin{figure}
87 + %\centering
88 + %\includegraphics[width=3in]{heirarchy.eps}
89 + %\caption[Class heirarchy for StuntDoubles in {\sc oopse}-3.0]{ \\
90 + %The class heirarchy of StuntDoubles in {\sc oopse}-3.0. The
91 + %selection syntax allows the user to select any of the objects that
92 + %are descended from a StuntDouble.} \label{oopseFig:heirarchy}
93 + %\end{figure}
94 +
95 + \begin{itemize}
96 + \item A {\bf StuntDouble} is {\it any} object that can be manipulated by the
97 + integrators and minimizers.
98 + \item An {\bf Atom} is a fundamental point-particle that can be moved around during a simulation.
99 + \item A {\bf DirectionalAtom} is an atom which has {\it orientational} as well as translational degrees of freedom.
100 + \item A {\bf RigidBody} is a collection of {\bf Atom}s or {\bf
101 + DirectionalAtom}s which behaves as a single unit.
102 + \end{itemize}
103 +
104 + Every Molecule, Atom and DirectionalAtom in {\sc oopse} have their
105 + own names which are specified in the {\tt .md} file. In contrast,
106 + RigidBodies are denoted by their membership and index inside a
107 + particular molecule: [MoleculeName]\_RB\_[index] (the contents
108 + inside the brackets depend on the specifics of the simulation). The
109 + names of rigid bodies are generated automatically. For example, the
110 + name of the first rigid body in a DMPC molecule is DMPC\_RB\_0.
111 +
112 + \section{\label{appendixSection:syntax}Syntax of the Select Command}
113 +
114 + The most general form of the select command is: {\tt select {\it
115 + expression}}
116 +
117 + This expression represents an arbitrary set of StuntDoubles (Atoms
118 + or RigidBodies) in {\sc oopse}. Expressions are composed of either
119 + name expressions, index expressions, predefined sets, user-defined
120 + expressions, comparison operators, within expressions, or logical
121 + combinations of the above expression types. Expressions can be
122 + combined using parentheses and the Boolean operators.
123 +
124 + \subsection{\label{appendixSection:logical}Logical expressions}
125 +
126 + The logical operators allow complex queries to be constructed out of
127 + simpler ones using the standard boolean connectives {\bf and}, {\bf
128 + or}, {\bf not}. Parentheses can be used to alter the precedence of
129 + the operators.
130 +
131 + \begin{center}
132 + \begin{tabular}{|ll|}
133 + \hline
134 + {\bf logical operator} & {\bf equivalent operator}  \\
135 + \hline
136 + and & ``\&'', ``\&\&'' \\
137 + or & ``$|$'', ``$||$'', ``,'' \\
138 + not & ``!''  \\
139 + \hline
140 + \end{tabular}
141 + \end{center}
142 +
143 + \subsection{\label{appendixSection:name}Name expressions}
144 +
145 + \begin{center}
146 + \begin{tabular}{|llp{2in}|}
147 + \hline {\bf type of expression} & {\bf examples} & {\bf translation
148 + of
149 + examples} \\
150 + \hline expression without ``.'' & select DMPC & select all
151 + StuntDoubles
152 + belonging to all DMPC molecules \\
153 + & select C* & select all atoms which have atom types beginning with C
154 + \\
155 + & select DMPC\_RB\_* & select all RigidBodies in DMPC molecules (but
156 + only select the rigid bodies, and not the atoms belonging to them). \\
157 + \hline expression has one ``.'' & select TIP3P.O\_TIP3P & select the
158 + O\_TIP3P
159 + atoms belonging to TIP3P molecules \\
160 + & select DMPC\_RB\_O.PO4 & select the PO4 atoms belonging to
161 + the first
162 + RigidBody in each DMPC molecule \\
163 + & select DMPC.20 & select the twentieth StuntDouble in each DMPC
164 + molecule \\
165 + \hline expression has two ``.''s & select DMPC.DMPC\_RB\_?.* &
166 + select all atoms
167 + belonging to all rigid bodies within all DMPC molecules \\
168 + \hline
169 + \end{tabular}
170 + \end{center}
171 +
172 + \subsection{\label{appendixSection:index}Index expressions}
173 +
174 + \begin{center}
175 + \begin{tabular}{|lp{4in}|}
176 + \hline
177 + {\bf examples} & {\bf translation of examples} \\
178 + \hline
179 + select 20 & select all of the StuntDoubles belonging to Molecule 20 \\
180 + select 20 to 30 & select all of the StuntDoubles belonging to
181 + molecules which have global indices between 20 (inclusive) and 30
182 + (exclusive) \\
183 + \hline
184 + \end{tabular}
185 + \end{center}
186 +
187 + \subsection{\label{appendixSection:predefined}Predefined sets}
188 +
189 + \begin{center}
190 + \begin{tabular}{|ll|}
191 + \hline
192 + {\bf keyword} & {\bf description} \\
193 + \hline
194 + all & select all StuntDoubles \\
195 + none & select none of the StuntDoubles \\
196 + \hline
197 + \end{tabular}
198 + \end{center}
199 +
200 + \subsection{\label{appendixSection:userdefined}User-defined expressions}
201 +
202 + Users can define arbitrary terms to represent groups of
203 + StuntDoubles, and then use the define terms in select commands. The
204 + general form for the define command is: {\bf define {\it term
205 + expression}}
206 +
207 + Once defined, the user can specify such terms in boolean expressions
208 +
209 + {\tt define SSDWATER SSD or SSD1 or SSDRF}
210 +
211 + {\tt select SSDWATER}
212 +
213 + \subsection{\label{appendixSection:comparison}Comparison expressions}
214 +
215 + StuntDoubles can be selected by using comparision operators on their
216 + properties. The general form for the comparison command is: a
217 + property name, followed by a comparision operator and then a number.
218 +
219 + \begin{center}
220 + \begin{tabular}{|l|l|}
221 + \hline
222 + {\bf property} & mass, charge \\
223 + {\bf comparison operator} & ``$>$'', ``$<$'', ``$=$'', ``$>=$'',
224 + ``$<=$'', ``$!=$'' \\
225 + \hline
226 + \end{tabular}
227 + \end{center}
228 +
229 + For example, the phrase {\tt select mass > 16.0 and charge < -2}
230 + would select StuntDoubles which have mass greater than 16.0 and
231 + charges less than -2.
232 +
233 + \subsection{\label{appendixSection:within}Within expressions}
234 +
235 + The ``within'' keyword allows the user to select all StuntDoubles
236 + within the specified distance (in Angstroms) from a selection,
237 + including the selected atom itself. The general form for within
238 + selection is: {\tt select within(distance, expression)}
239 +
240 + For example, the phrase {\tt select within(2.5, PO4 or NC4)} would
241 + select all StuntDoubles which are within 2.5 angstroms of PO4 or NC4
242 + atoms.
243 +
244 +
245   \section{\label{appendixSection:analysisFramework}Analysis Framework}
246  
247 < \subsection{\label{appendixSection:staticProps}Factory Properties}
247 > \subsection{\label{appendixSection:StaticProps}StaticProps}
248  
249 < \subsection{\label{appendixSection:dynamicProps}Dynamics Properties}
249 > {\tt StaticProps} can compute properties which are averaged over
250 > some or all of the configurations that are contained within a dump
251 > file. The most common example of a static property that can be
252 > computed is the pair distribution function between atoms of type $A$
253 > and other atoms of type $B$, $g_{AB}(r)$.  StaticProps can also be
254 > used to compute the density distributions of other molecules in a
255 > reference frame {\it fixed to the body-fixed reference frame} of a
256 > selected atom or rigid body.
257 >
258 > There are five seperate radial distribution functions availiable in
259 > OOPSE. Since every radial distrbution function invlove the
260 > calculation between pairs of bodies, {\tt -{}-sele1} and {\tt
261 > -{}-sele2} must be specified to tell StaticProps which bodies to
262 > include in the calculation.
263 >
264 > \begin{description}
265 > \item[{\tt -{}-gofr}] Computes the pair distribution function,
266 > \begin{equation*}
267 > g_{AB}(r) = \frac{1}{\rho_B}\frac{1}{N_A} \langle \sum_{i \in A}
268 > \sum_{j \in B} \delta(r - r_{ij}) \rangle
269 > \end{equation*}
270 > \item[{\tt -{}-r\_theta}] Computes the angle-dependent pair distribution
271 > function. The angle is defined by the intermolecular vector
272 > $\vec{r}$ and $z$-axis of DirectionalAtom A,
273 > \begin{equation*}
274 > g_{AB}(r, \cos \theta) = \frac{1}{\rho_B}\frac{1}{N_A} \langle
275 > \sum_{i \in A} \sum_{j \in B} \delta(r - r_{ij}) \delta(\cos
276 > \theta_{ij} - \cos \theta)\rangle
277 > \end{equation*}
278 > \item[{\tt -{}-r\_omega}] Computes the angle-dependent pair distribution
279 > function. The angle is defined by the $z$-axes of the two
280 > DirectionalAtoms A and B.
281 > \begin{equation*}
282 > g_{AB}(r, \cos \omega) = \frac{1}{\rho_B}\frac{1}{N_A} \langle
283 > \sum_{i \in A} \sum_{j \in B} \delta(r - r_{ij}) \delta(\cos
284 > \omega_{ij} - \cos \omega)\rangle
285 > \end{equation*}
286 > \item[{\tt -{}-theta\_omega}] Computes the pair distribution in the angular
287 > space $\theta, \omega$ defined by the two angles mentioned above.
288 > \begin{equation*}
289 > g_{AB}(\cos\theta, \cos \omega) = \frac{1}{\rho_B}\frac{1}{N_A}
290 > \langle \sum_{i \in A} \sum_{j \in B} \langle \delta(\cos
291 > \theta_{ij} - \cos \theta) \delta(\cos \omega_{ij} - \cos
292 > \omega)\rangle
293 > \end{equation*}
294 > \item[{\tt -{}-gxyz}] Calculates the density distribution of particles of type
295 > B in the body frame of particle A. Therefore, {\tt -{}-originsele}
296 > and {\tt -{}-refsele} must be given to define A's internal
297 > coordinate set as the reference frame for the calculation.
298 > \end{description}
299 >
300 > The vectors (and angles) associated with these angular pair
301 > distribution functions are most easily seen in the figure below:
302 >
303 > \begin{figure}
304 > \centering
305 > \includegraphics[width=3in]{definition.eps}
306 > \caption[Definitions of the angles between directional objects]{ \\
307 > Any two directional objects (DirectionalAtoms and RigidBodies) have
308 > a set of two angles ($\theta$, and $\omega$) between the z-axes of
309 > their body-fixed frames.} \label{oopseFig:gofr}
310 > \end{figure}
311 >
312 > The options available for {\tt StaticProps} are as follows:
313 > \begin{longtable}[c]{|EFG|}
314 > \caption{StaticProps Command-line Options}
315 > \\ \hline
316 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
317 > \endhead
318 > \hline
319 > \endfoot
320 >  -h& {\tt -{}-help}                    &  Print help and exit \\
321 >  -V& {\tt -{}-version}                 &  Print version and exit \\
322 >  -i& {\tt -{}-input}          &  input dump file \\
323 >  -o& {\tt -{}-output}         &  output file name \\
324 >  -n& {\tt -{}-step}                &  process every n frame  (default=`1') \\
325 >  -r& {\tt -{}-nrbins}              &  number of bins for distance  (default=`100') \\
326 >  -a& {\tt -{}-nanglebins}          &  number of bins for cos(angle)  (default= `50') \\
327 >  -l& {\tt -{}-length}           &  maximum length (Defaults to 1/2 smallest length of first frame) \\
328 >    & {\tt -{}-sele1}   & select the first StuntDouble set \\
329 >    & {\tt -{}-sele2}   & select the second StuntDouble set \\
330 >    & {\tt -{}-sele3}   & select the third StuntDouble set \\
331 >    & {\tt -{}-refsele} & select reference (can only be used with {\tt -{}-gxyz}) \\
332 >    & {\tt -{}-molname}           & molecule name \\
333 >    & {\tt -{}-begin}                & begin internal index \\
334 >    & {\tt -{}-end}                  & end internal index \\
335 > \hline
336 > \multicolumn{3}{|l|}{One option from the following group of options is required:} \\
337 > \hline
338 >    &  {\tt -{}-gofr}                    &  $g(r)$ \\
339 >    &  {\tt -{}-r\_theta}                 &  $g(r, \cos(\theta))$ \\
340 >    &  {\tt -{}-r\_omega}                 &  $g(r, \cos(\omega))$ \\
341 >    &  {\tt -{}-theta\_omega}             &  $g(\cos(\theta), \cos(\omega))$ \\
342 >    &  {\tt -{}-gxyz}                    &  $g(x, y, z)$ \\
343 >    &  {\tt -{}-p2}                      &  $P_2$ order parameter ({\tt -{}-sele1} and {\tt -{}-sele2} must be specified) \\
344 >    &  {\tt -{}-scd}                     &  $S_{CD}$ order parameter(either {\tt -{}-sele1}, {\tt -{}-sele2}, {\tt -{}-sele3} are specified or {\tt -{}-molname}, {\tt -{}-begin}, {\tt -{}-end} are specified) \\
345 >    &  {\tt -{}-density}                 &  density plot ({\tt -{}-sele1} must be specified) \\
346 >    &  {\tt -{}-slab\_density}           &  slab density ({\tt -{}-sele1} must be specified)
347 > \end{longtable}
348 >
349 > \subsection{\label{appendixSection:DynamicProps}DynamicProps}
350 >
351 > {\tt DynamicProps} computes time correlation functions from the
352 > configurations stored in a dump file.  Typical examples of time
353 > correlation functions are the mean square displacement and the
354 > velocity autocorrelation functions.   Once again, the selection
355 > syntax can be used to specify the StuntDoubles that will be used for
356 > the calculation.  A general time correlation function can be thought
357 > of as:
358 > \begin{equation}
359 > C_{AB}(t) = \langle \vec{u}_A(t) \cdot \vec{v}_B(0) \rangle
360 > \end{equation}
361 > where $\vec{u}_A(t)$ is a vector property associated with an atom of
362 > type $A$ at time $t$, and $\vec{v}_B(t^{\prime})$ is a different
363 > vector property associated with an atom of type $B$ at a different
364 > time $t^{\prime}$.  In most autocorrelation functions, the vector
365 > properties ($\vec{v}$ and $\vec{u}$) and the types of atoms ($A$ and
366 > $B$) are identical, and the three calculations built in to {\tt
367 > DynamicProps} make these assumptions.  It is possible, however, to
368 > make simple modifications to the {\tt DynamicProps} code to allow
369 > the use of {\it cross} time correlation functions (i.e. with
370 > different vectors).  The ability to use two selection scripts to
371 > select different types of atoms is already present in the code.
372 >
373 > The options available for DynamicProps are as follows:
374 > \begin{longtable}[c]{|EFG|}
375 > \caption{DynamicProps Command-line Options}
376 > \\ \hline
377 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
378 > \endhead
379 > \hline
380 > \endfoot
381 >  -h& {\tt -{}-help}                   & Print help and exit \\
382 >  -V& {\tt -{}-version}                & Print version and exit \\
383 >  -i& {\tt -{}-input}         & input dump file \\
384 >  -o& {\tt -{}-output}        & output file name \\
385 >    & {\tt -{}-sele1} & select first StuntDouble set \\
386 >    & {\tt -{}-sele2} & select second StuntDouble set (if sele2 is not set, use script from sele1) \\
387 > \hline
388 > \multicolumn{3}{|l|}{One option from the following group of options is required:} \\
389 > \hline
390 >  -r& {\tt -{}-rcorr}                  & compute mean square displacement \\
391 >  -v& {\tt -{}-vcorr}                  & compute velocity correlation function \\
392 >  -d& {\tt -{}-dcorr}                  & compute dipole correlation function
393 > \end{longtable}
394 >
395 > \section{\label{appendixSection:tools}Other Useful Utilities}
396 >
397 > \subsection{\label{appendixSection:Dump2XYZ}Dump2XYZ}
398 >
399 > Dump2XYZ can transform an OOPSE dump file into a xyz file which can
400 > be opened by other molecular dynamics viewers such as Jmol and VMD.
401 > The options available for Dump2XYZ are as follows:
402 >
403 >
404 > \begin{longtable}[c]{|EFG|}
405 > \caption{Dump2XYZ Command-line Options}
406 > \\ \hline
407 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
408 > \endhead
409 > \hline
410 > \endfoot
411 >  -h & {\tt -{}-help} &                        Print help and exit \\
412 >  -V & {\tt -{}-version} &                     Print version and exit \\
413 >  -i & {\tt -{}-input}  &             input dump file \\
414 >  -o & {\tt -{}-output} &             output file name \\
415 >  -n & {\tt -{}-frame}   &                 print every n frame  (default=`1') \\
416 >  -w & {\tt -{}-water}       &                 skip the the waters  (default=off) \\
417 >  -m & {\tt -{}-periodicBox} &                 map to the periodic box  (default=off)\\
418 >  -z & {\tt -{}-zconstraint}  &                replace the atom types of zconstraint molecules  (default=off) \\
419 >  -r & {\tt -{}-rigidbody}  &                  add a pseudo COM atom to rigidbody  (default=off) \\
420 >  -t & {\tt -{}-watertype} &                   replace the atom type of water model (default=on) \\
421 >  -b & {\tt -{}-basetype}  &                   using base atom type  (default=off) \\
422 >     & {\tt -{}-repeatX}  &                 The number of images to repeat in the x direction  (default=`0') \\
423 >     & {\tt -{}-repeatY} &                 The number of images to repeat in the y direction  (default=`0') \\
424 >     &  {\tt -{}-repeatZ}  &                The number of images to repeat in the z direction  (default=`0') \\
425 >  -s & {\tt -{}-selection} & By specifying {\tt -{}-selection}=``selection command'' with Dump2XYZ, the user can select an arbitrary set of StuntDoubles to be
426 > converted. \\
427 >     & {\tt -{}-originsele} & By specifying {\tt -{}-originsele}=``selection command'' with Dump2XYZ, the user can re-center the origin of the system around a specific StuntDouble \\
428 >     & {\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}.
429 > \end{longtable}
430 >
431 > \subsection{\label{appendixSection:hydrodynamics}Hydrodynamics}
432 >
433 > \begin{longtable}[c]{|EFG|}
434 > \caption{Hydrodynamics Command-line Options}
435 > \\ \hline
436 > {\bf option} & {\bf verbose option} & {\bf behavior} \\ \hline
437 > \endhead
438 > \hline
439 > \endfoot
440 >  -h & {\tt -{}-help} &                        Print help and exit \\
441 >  -V & {\tt -{}-version} &                     Print version and exit \\
442 >  -i & {\tt -{}-input}  &             input dump file \\
443 >  -o & {\tt -{}-output} &             output file prefix  (default=`hydro') \\
444 >  -b & {\tt -{}-beads}  &                   generate the beads only, hydrodynamics calculation will not be performed (default=off)\\
445 >     & {\tt -{}-model}  &                 hydrodynamics model (support ``AnalyticalModel'', ``RoughShell'' and ``BeadModel'') \\
446 > \end{longtable}

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines