ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/OpenMD/trunk/doc/SelectionExpression.html
Revision: 432
Committed: Fri Mar 11 15:00:20 2005 UTC (20 years, 7 months ago) by tim
Content type: text/html
File size: 18252 byte(s)
Log Message: 
clean up SimInfo; modify the images of SelectionExpression.html

File Contents

# User Rev Content
1 tim 430 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2     <html>
3     <head>
4     <title>Selection syntax for OOPSE utility programs</title>
5     </head>
6     <body style="background-color: white;">
7     <basefont size="3">
8     <div align="center">
9     <p><font size="+2"><b>Selection syntax for OOPSE utility programs</b></font><span
10     style="font-weight: bold;"></span><br>
11     </p>
12     <h2 align="left"><a name="introduction" id="introduction"> Introduction
13     </a></h2>
14     <p style="text-align: left;">The OOPSE utility programs compute
15     properties from the <span
16     style="font-family: monospace; font-weight: bold;">dump</span><span
17     style="font-weight: bold;">
18     </span>files that are generated during a molecular dynamics
19     simulation.&nbsp;
20     These programs are:<br>
21     </p>
22     <ul style="text-align: left;">
23     <li><span style="font-family: monospace; font-weight: bold;">Dump2XYZ</span><span
24     style="font-weight: bold;"> </span>- Converts an OOPSE dump file into
25     a file suitable
26     for viewing in a molecular dynamics viewer like <a
27     href="http://www.jmol.org">Jmol</a><br>
28     </li>
29     <li><span style="font-family: monospace; font-weight: bold;">StaticProps</span><span
30     style="font-weight: bold;"> </span>- Computes static properties like
31     the pair distribution function, <span style="font-style: italic;">g(r)</span>.<br>
32     </li>
33     <li><span style="font-family: monospace; font-weight: bold;">DynamicProps</span><span
34     style="font-weight: bold;"> </span>- Computes time correlation
35     functions like the
36     velocity autocorrelation function, <span style="font-style: italic;">&lt;<span
37     style="font-weight: bold;">v</span>(t)<span style="font-weight: bold;">v</span>(0)&gt;</span>,
38     or the mean square displacement <span style="font-style: italic;">&lt;|<span
39     style="font-weight: bold;">r</span>(t) - <span
40     style="font-weight: bold;">r</span>(0)|<sup>2</sup>&gt;.</span></li>
41     </ul>
42     <div style="text-align: left;">These programs often need to operate on
43     a subset of the data contained within a dump file.&nbsp; For example,
44     if you want only the <span style="font-style: italic;">oxygen-oxygen</span>
45     pair distribution from a water simulation, or if you want to make a
46     movie including only the water molecules within a 6 angstrom radius of
47     lipid head groups, you need a way to specify your selection to these
48     utility programs.&nbsp;&nbsp; OOPSE has a selection syntax which allows
49     you to specify the selection in a compact form in order to generate
50     only the data you want.&nbsp; For example a common use of the
51     StaticProps command would be:<br>
52     <br>
53     <div style="margin-left: 80px;"><span
54     style="font-family: monospace; font-weight: bold;">StaticProps -i
55     tp4.dump --gofr --sele1="select O*" --sele2="select O*"</span><br>
56     </div>
57     <br>
58     This command computes the oxygen-oxygen pair distribution function, <span
59     style="font-style: italic;">g<sub>OO</sub>(r)</span>, from a file
60     named <span style="font-family: monospace;">tp4.dump</span>.&nbsp; In
61     order to understand this selection syntax and to make full use of the
62     selection capabilities of the analysis programs, it is necessary to
63     understand a few of the core concepts that are used to perform
64     simulations.<br>
65     <h2><a name="Concepts"></a>Concepts</h2>
66     OOPSE manipulates both traditional atoms as well as some objects that <span
67     style="font-style: italic;">behave like atoms</span>.&nbsp; These
68     objects can be rigid collections of atoms or atoms which have
69     orientational degrees of freedom.&nbsp; Here is a diagram of the class
70     heirarchy:<br>
71     <span style="font-style: italic;"></span></div>
72 tim 432 <p align="center"><img src="heirarchy.png" width="212" height="136"><br>
73 tim 430 </p>
74     <ul style="text-align: left;">
75     <li>A <span style="font-family: monospace; font-weight: bold;">StuntDouble</span>
76     is <span style="font-style: italic;">any</span> object that can be
77     manipulated by the integrators and minimizers.</li>
78     <li>An <span style="font-family: monospace; font-weight: bold;">Atom</span>
79     is a fundamental point-particle that can be moved around during a
80     simulation.</li>
81     <li>A <span style="font-family: monospace; font-weight: bold;">DirectionalAtom</span>
82     is an atom which has <span style="font-style: italic;">orientational</span>
83     as well as translational degrees of freedom.</li>
84     <li>A <span style="font-family: monospace; font-weight: bold;">RigidBody</span>
85     is a collection of <span
86     style="font-family: monospace; font-weight: bold;">Atom</span>s or <span
87     style="font-family: monospace; font-weight: bold;">DirectionalAtom</span>s
88     which behaves as a <span style="font-style: italic;">single unit.</span></li>
89     </ul>
90     <p align="left"> Every Molecule, Atom and DirectionalAtom in OOPSE
91     have their own names which are specified in the <span
92     style="font-family: monospace; font-weight: bold;">.md</span> file. In
93     contrast, RigidBodies are denoted by their membership and index inside
94     a particular molecule: <span style="font-family: monospace;">[MoleculeName]_RB_[index]</span>
95     (the contents inside
96     the brackets depend on the specifics of the simulation). The names of
97     rigid bodies are generated automatically. For
98     example, the name of the first rigid body in a DMPC molecule is
99     DMPC_RB_0.<br>
100     </p>
101     </div>
102     <h2><a name="select"></a>Syntax of the Select Command</h2>
103     The most general form of the select command is: <b>select <i>expression</i>
104     </b>
105     <p>This expression represents an arbitrary set of StuntDoubles (Atoms
106     or
107     RigidBodies) in OOPSE. Expressions are composed of either name
108     expressions, index expression, predefined sets, user-defined
109     expression,
110     comparison operators, within expressions, or logical combinations of
111     the above expression types. Expression can be combined using
112     parentheses
113     and the Boolean operators</p>
114     <p><b><a name="logic"></a> Logical expression. </b> </p>
115     <p>The logical operators allow complex queries to be constructed out of
116     simpler ones using the standard boolean connectives <b>and, or, not</b>.
117     Parentheses can be used to alter the precedence of the operators.
118     </p>
119     <ul>
120     <table bgcolor="#ffffff" border="1" cellpadding="5" width="441">
121     <tbody>
122     <tr bgcolor="#ffccff">
123     <td width="174">
124     <div align="left">logical operator </div>
125     </td>
126     <td width="241">
127     <div align="left">equivalent operator</div>
128     </td>
129     </tr>
130     <tr bgcolor="#ffccff">
131     <td>
132     <div align="left">and</div>
133     </td>
134     <td>
135     <div align="left">"&amp;", "&amp;&amp;" </div>
136     </td>
137     </tr>
138     <tr bgcolor="#ffccff">
139     <td>
140     <div align="left">or</div>
141     </td>
142     <td>
143     <div align="left">"|", "||", "," </div>
144     </td>
145     </tr>
146     <tr bgcolor="#ffccff">
147     <td>
148     <div align="left">not</div>
149     </td>
150     <td>
151     <div align="left">"!"</div>
152     </td>
153     </tr>
154     </tbody>
155     </table>
156     <p>&nbsp;</p>
157     </ul>
158     <p><a name="name"><b> Name expression.
159     </b></a> </p>
160     <ul>
161     <table bgcolor="#ffffcc" border="1" bordercolor="#6b7683" width="886">
162     <tbody>
163     <tr>
164     <td colspan="2">
165     <div align="center">expression</div>
166     </td>
167     <td width="434">
168     <div align="center">description</div>
169     </td>
170     </tr>
171     <tr>
172     <td rowspan="3" width="183">expression without "." </td>
173     <td width="247">
174     <div align="left">select DMPC</div>
175     </td>
176     <td>select all StuntDoubles belonging to all DMPC molecules </td>
177     </tr>
178     <tr>
179     <td>
180     <div align="left">select C*</div>
181     </td>
182     <td>select all atoms which have atom types beginning with C<br>
183     </td>
184     </tr>
185     <tr>
186     <td>
187     <div align="left">select DMPC_RB_*</div>
188     </td>
189     <td>select all RigidBodies in DMPC molecules (only select
190     rigid-bodies, but not
191     include the atoms belong to them)</td>
192     </tr>
193     <tr>
194     <td rowspan="3">expression has one "." </td>
195     <td>select TIP3P.O_TIP3P</td>
196     <td>select the O_TIP3P Atoms belong to TIP3P molecules </td>
197     </tr>
198     <tr>
199     <td>select DMPC_RB_0.PO4</td>
200     <td>select the PO4 Atoms belonging to first RigidBody in each
201     DMPC molecule<br>
202     </td>
203     </tr>
204     <tr>
205     <td>select DMPC.20</td>
206     <td>select the 20th StuntDouble in each DMPC molecule<br>
207     </td>
208     </tr>
209     <tr>
210     <td>expression has two "."</td>
211     <td>select DMPC.DMPC_RB_?.*</td>
212     <td>select all Atoms belonging to all rigid-bodies within all
213     DMPC molecules</td>
214     </tr>
215     </tbody>
216     </table>
217     <p>&nbsp;</p>
218     </ul>
219     <p><a name="index" id="index"><b> Index expression </b></a></p>
220     <ul>
221     <table bgcolor="#ffffff" border="1" cellpadding="5" width="894">
222     <tbody>
223     <tr bgcolor="#ffffcc">
224     <td width="113">select 20 </td>
225     <td width="520">select all of the StuntDoubles belonging to
226     Molecule 20</td>
227     </tr>
228     <tr bgcolor="#ffffcc">
229     <td>select 20 to 30 </td>
230     <td>select all of the StuntDoules belonging to molecules which
231     have global
232     indices between 20 (inclusive) and 30 (exclusive) </td>
233     </tr>
234     </tbody>
235     </table>
236     </ul>
237     <p>&nbsp; </p>
238     <p><a name="predefine" id="predefine"><b> Predefined sets </b></a></p>
239     <ul>
240     <table bgcolor="#ffffff" border="1" cellpadding="5" width="449">
241     <tbody>
242     <tr bgcolor="#ffccff">
243     <td width="91">
244     <div align="left">keyword</div>
245     </td>
246     <td width="332">
247     <div align="left">description</div>
248     </td>
249     </tr>
250     <tr bgcolor="#ffccff">
251     <td>
252     <div align="left">all</div>
253     </td>
254     <td>
255     <div align="left">select all StuntDoubles</div>
256     </td>
257     </tr>
258     <tr bgcolor="#ffccff">
259     <td>
260     <div align="left">none</div>
261     </td>
262     <td>
263     <div align="left">select none of the StuntDoubles </div>
264     </td>
265     </tr>
266     </tbody>
267     </table>
268     </ul>
269     <p>&nbsp;</p>
270     <p><a name="user" id="user"><b> User defined expressions</b></a></p>
271     <p> Users can define arbitrary terms to represent groups of
272     StuntDoubles, and then use the define terms in select
273     commands. The general form for the define command is: <strong>define <em>term
274     expression</em></strong></p>
275     <p> Once defined, the user can specify such terms in boolean
276     expressions </p>
277     <ul>
278     <table bgcolor="#ffffff" border="1" cellpadding="5" width="659">
279     <tbody>
280     <tr bgcolor="#ffffcc">
281     <td>
282     <p>define SSDWATER SSD or SSD1 or SSDRF</p>
283     <p>select SSDWATER </p>
284     </td>
285     </tr>
286     </tbody>
287     </table>
288     </ul>
289     <p><a name="comparison" id="comparison"> <b>Comparison expression.</b></a></p>
290     <p>StuntDoubles can be selected by using comparision operators on
291     their properties. The general form for the comparison command is: a
292     property name, followed by a comparision operator and then a number.</p>
293     <ul>
294     <table bgcolor="#ffffff" border="1" cellpadding="5" width="668">
295     <tbody>
296     <tr bgcolor="#ffccff">
297     <td width="305">
298     <div align="left">property</div>
299     </td>
300     <td width="331">
301     <div align="left">mass, charge </div>
302     </td>
303     </tr>
304     <tr bgcolor="#ffccff">
305     <td>
306     <div align="left">comparision operator</div>
307     </td>
308     <td>
309     <div align="left">"&gt;", "&lt;", "=", "&gt;=", "&lt;=", "!=" </div>
310     </td>
311     </tr>
312     </tbody>
313     </table>
314     </ul>
315     <ul>
316     <table bgcolor="#ffffff" border="1" cellpadding="5" width="672">
317     <tbody>
318     <tr bgcolor="#ffffcc">
319     <td width="302">select mass &gt; 16.0 and charge &lt; -2 </td>
320     <td width="338">select StuntDoubles which have mass greater
321     than
322     16.0 and charges less than -2 </td>
323     </tr>
324     </tbody>
325     </table>
326     </ul>
327     <p>&nbsp;</p>
328     <p><b> <a name="within"></a> Within expression.</b>
329     </p>
330     <p> The "within" selection allows the user to select all StuntDoubles
331     within the specified
332     distance (in Angstroms) from a selection, including the selected atom
333     itself. The
334     general form for within selection is: <b>select within(<i>distance,
335     expression</i>) </b>
336     </p>
337     <ul>
338     <table bgcolor="#ffffff" border="1" cellpadding="5" width="681">
339     <tbody>
340     <tr bgcolor="#ffffcc">
341     <td width="306">select within(2.5, PO4 or NC4) </td>
342     <td width="343">
343     <blockquote>select all StuntDoubles which are within 2.5
344     angstroms of PO4 or NC4 atoms<br>
345     </blockquote>
346     </td>
347     </tr>
348     </tbody>
349     </table>
350     </ul>
351     <p>
352     </p>
353     <h2><a name="syntax" id="syntax"> Tools which use the selection command
354     </a></h2>
355     <p><b><a name="within"></a> Dump2XYZ</b>
356     </p>
357     <p>Dump2XYZ can transform an OOPSE dump file into a xyz file which
358     could be opened by other molecular viewers, such as Jmol and VMD. </p>
359     <ul>
360     <table bgcolor="#ffffff" border="1" cellpadding="5" width="890">
361     <tbody>
362     <tr bgcolor="#6699ff">
363     <td width="191">
364     <blockquote>
365     <p>--selection</p>
366     </blockquote>
367     </td>
368     <td width="667">Specifying --selection="selection command" with
369     Dump2XYZ, user can select an arbitrary set of stuntdoubles to be
370     converted. </td>
371     </tr>
372     <tr bgcolor="#ccff99">
373     <td>
374     <blockquote>
375     <p>--originsele</p>
376     </blockquote>
377     </td>
378     <td rowspan="2">In order to rotate the system, --originsele and
379     --refselec must be given to define the new coordinate set. A
380     stuntdouble with a dipole, which direction is always (0, 0, 1) in body
381     frame, is specified by --originsele. The new x-z plane is defined by
382     the direction of dipole and the StuntDouble is specified by --refsele. </td>
383     </tr>
384     <tr bgcolor="#ccff99">
385     <td>
386     <blockquote>
387     <p>--refsele</p>
388     </blockquote>
389     </td>
390     </tr>
391     </tbody>
392     </table>
393     </ul>
394     <p>
395     </p>
396     <p><b><a name="within"></a> StaticProps<br>
397     </b></p>
398     StaticProps can compute properties which are averaged over the
399     configurations that are contained within a dump file.&nbsp;&nbsp; The
400     most common example of a static property that can be computed is the
401     pair distribution function between atoms of type A and other atoms of
402     type B, <span style="font-style: italic;">g<sub>AB</sub>(r)</span>.&nbsp;
403     StaticProps can also be used to compute the density distributions of
404     other molecules in a reference frame <span style="font-style: italic;">fixed
405     to the body-fixed reference frame</span> of a selected atom or rigid
406     body.<b><br>
407     </b>
408     <p> </p>
409 tim 432 <p align="center"><img src="definition.jpg" width="718" height="255"></p>
410     <p align="center"><img src="gofr.jpg" width="384" height="76"></p>
411     <p align="center"><img src="gofrtheta.jpg" width="468" height="70"></p>
412 tim 430 <p align="left">There are five seperate radial distribution functions
413     availiable in OOPSE. Since every radial distrbution function invlove
414     the calculation between a pair, --sele1 and --sele2 must be given.
415     </p>
416     <ul>
417     <table bgcolor="#ffffff" border="1" cellpadding="5" width="890">
418     <tbody>
419     <tr bgcolor="#ccffcc">
420     <td width="191">
421     <blockquote>
422     <p>option</p>
423     </blockquote>
424     </td>
425     <td width="667">
426     <blockquote>
427     <div align="center">description</div>
428     </blockquote>
429     </td>
430     </tr>
431     <tr bgcolor="#ccffcc">
432     <td>
433     <blockquote>
434     <p>--gofr</p>
435     </blockquote>
436     </td>
437     <td>Computes the pair distribution function.</td>
438     </tr>
439     <tr bgcolor="#ccffcc">
440     <td>
441     <blockquote>
442     <p>--r_theta</p>
443     </blockquote>
444     </td>
445     <td>Computes the angle-dependent pair distribution function.
446     The
447     angle is defined by the intermolecular vector r and z-axis of
448     DirectionalAtom A.<br>
449     </td>
450     </tr>
451     <tr bgcolor="#ccffcc">
452     <td>
453     <blockquote>
454     <p>--r_omega</p>
455     </blockquote>
456     </td>
457     <td>Computes an angle-dependent pair distribution function. The
458     angle is defined by the z-axes of the two DirectionalAtoms A and B.<br>
459     </td>
460     </tr>
461     <tr bgcolor="#ccffcc">
462     <td>
463     <blockquote>
464     <p>--theta_omega</p>
465     </blockquote>
466     </td>
467     <td>Calculate the pair distribution of the two angles.</td>
468     </tr>
469     <tr bgcolor="#ccffcc">
470     <td>
471     <blockquote>
472     <p>--gxyz</p>
473     </blockquote>
474     </td>
475     <td>Calculate the density distribution of particles
476     of type B in the body frame of particle A. Therefore, --originsele and
477     --refsele must be given to define A's internal coordinate set. </td>
478     </tr>
479     </tbody>
480     </table>
481     </ul>
482     <p>&nbsp; </p>
483     <p><b><a name="within"></a> DynamicProps<br>
484     <span style="font-weight: bold;"><br>
485     </span></b>DynamicProps computes time correlation functions from the
486     configurations stored in a dump file.&nbsp; Typical examples of time
487     correlation functions are the mean square displacement and the velocity
488     autocorrelation functions. <b><span style="font-weight: bold;"><br>
489     </span> </b></p>
490     <ul>
491     <table bgcolor="#ffffff" border="1" cellpadding="5" width="890">
492     <tbody>
493     <tr bgcolor="#ccffcc">
494     <td width="191">
495     <p align="center">option</p>
496     </td>
497     <td width="667">
498     <blockquote>
499     <div align="center">description</div>
500     </blockquote>
501     </td>
502     </tr>
503     <tr bgcolor="#ccffcc">
504     <td>
505     <p align="center">--rcorr</p>
506     </td>
507     <td>mean square displacement </td>
508     </tr>
509     <tr bgcolor="#ccffcc">
510     <td>
511     <p align="center">--vcorr</p>
512     </td>
513     <td>velocity autocorrelation function</td>
514     </tr>
515     <tr bgcolor="#ccffcc">
516     <td>
517     <p align="center">--dcorr</p>
518     </td>
519     <td>dipole correlation function </td>
520     </tr>
521     </tbody>
522     </table>
523     </ul>
524     <p>
525     </p>
526     </body>
527     </html>

Properties

Name Value
svn:executable *