1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
|
<html><head><title></title></head>
<body>
<a name="158126">
<h1>1.0 </a>Introduction</h1>
</a>
<a name="158091">
The </a>PACT system provides a number of tools for working with </a>PDB files in a fairly generic fashion. In particular, </a>PDBDiff compares the contents of two PDB files and displays the differences (in a manner similar but not identical to the </a>UNIX utility </a>diff). PDBDiff can also be run in an </a>interactive </a>mode which allows you to compare two PDB files on a variable by variable or even leaf by leaf basis.<p>
</a>
<a name="158218">
PDBDiff is an </a>SX program. SX is the </a>SCHEME dialect of the </a>LISP programming language with PACT extensions. The extensions provide functionality for graphics, binary data handling, and other areas of functionality.<p>
</a>
<a name="158106">
PDBDiff has a </a>help command which provides information about available commands. <p>
</a>
<a name="158127">
Note: The files compared may have been created on or for different </a>target machines. Consequently, a given data type may be represented differently in the two files. In this event values are compared to the </a>precision in the first file, or the precision in the second file, or the precision you specify, whichever is least.<p>
</a>
<a name="158105">
<h1>2.0 </a>Data Files with PDBDiff</h1>
</a>
<a name="158228">
PDBDiff can be used to compare the contents of any two PDB files. It compares files entry by entry. In the most commonly used mode of use it has no knowledge of the semantics of the data in the files it compares.<p>
</a>
<a name="158217">
<h2>2.1 </a>PVA Files</h2>
</a>
<a name="158229">
There is a </a>special kind of PDB file called a </a>PVA (</a>Portable Visualization and Analysis) file which contains data sets structured in a particular way so as to completely specify all information necessary to visualize the data set or to perform mathematical operations such as differentiation and integration on it. </a>PANACEA codes produce PVA files as the PACT supported option for data output. PDBDiff can compare these files in a special way. Since it has complete information about the data sets, it can compare data sets which represent the same quantity but, potentially, with different amounts of information. For example, two runs of a numerical simulation code might compute a given quantity but with different resolution on the computational mesh. PDBDiff can compare these data sets by interpolating them to a common domain and computing the </a>difference measure:<p>
</a>
<a name="158226">
<img src="pdbdiff5.doc.anc.gif"><p>
</a>
<a name="158227">
If the difference measure is less than a specified </a>threshold, PDBDiff goes on to the next mapping in the file. However, if the difference measure exceeds the threshold, the two mappings, a and b, are displayed in separate windows along with the integrand above in its own window. The user is prompted to specify whether or not the differences are acceptable. In this way PDBDiff can be used as an aide to developing simulation codes and testing them.<p>
</a>
<a name="158120">
<p>
</a>
<a name="158036">
<h1>3.0 </a>PDBDiff Syntax</h1>
</a>
<a name="158135">
PDBDiff uses a slightly different data description </a>syntax than </a>PDBLib. With PDBLib </a>variable names and </a>names of </a>members of </a>structures cannot contain the characters: “</a>.”, “</a>(“, “</a>)”, “</a>[“, and “</a>]”. The characters “(“, “)”, “</a>[“, and “</a>]” are used in array reference and dimension definition expressions. In PDBDiff, “(“ and “)” CANNOT be used in variable reference expressions because they are special characters for PDBDiff. For example,<p>
</a>
<A NAME="158136"><PRE> print a(2)
</PRE><a name="158137">
is illegal and results in an error. The legal expression is:<p>
</a>
<A NAME="158138"><PRE> print a[2]
</PRE><a name="158139">
Other examples of legal expressions are:<p>
</a>
<A NAME="158140"><PRE> print a.b[3,2]
</PRE><A NAME="158141"><PRE> print a.b[3][2]
</PRE><A NAME="158142"><PRE> print a[3].b[2][5].c
</PRE><A NAME="158243"><PRE> print a[3].b[2][3].c[3:4,5:50:10]
</PRE><a name="158144">
The first two forms are not identical. In the first form an element of a two dimensional array is being referenced. In the second form, the third element of the fourth array of arrays is being referenced (assuming zero based indexing in the definition of the b member of a).<p>
</a>
<a name="158242">
For completeness and clarity in the following discussion, an </a>index expression is defined as:<p>
</a>
<A NAME="158230"><PRE> </a>index expression := [index list]
</PRE><A NAME="158231"><PRE> </a>index list := index | index, index list
</PRE><A NAME="158145"><PRE> </a>index := simple index |
</PRE><A NAME="158233"><PRE> index-min : index-max | (*)
</PRE><A NAME="158234"><PRE> index-min : index-max : increment (*)
</PRE><A NAME="158146"><PRE> </a>simple index := integer
</PRE><A NAME="158147"><PRE> </a>index-min := integer
</PRE><A NAME="158232"><PRE> </a>index-max := integer
</PRE><A NAME="158148"><PRE> </a>increment := integer
</PRE><a name="158151">
If an index expression uses either of the two starred forms it is said to be a </a>hyper-index expression. A hyper-index expression implies more than one data item. Only the </a>terminating index expression in a </a>data reference may be a hyper-index expression. An index expression is said to </a>dereference an </a>indirection (or</a> pointer or array). For each </a>level of indirection a suitable index expression </a>dereferences the desired data.<p>
</a>
<a name="158244">
For example, this means that a variable defined as:<p>
</a>
<A NAME="158236"><PRE> char **s
</PRE><a name="158240">
is said to have two </a>levels of indirection and can have parts accessed as follows:<p>
</a>
<A NAME="158237"><PRE> print s prints the entire item
</PRE><A NAME="158238"><PRE> print s[2] prints the third character array of s
</PRE><A NAME="158239"><PRE> print s[3][10] prints the eleventh character of the fourth character array of s
</PRE><a name="158156">
In the above example a zero based index is assumed.<p>
</a>
<a name="158098">
When referring to part of a variable, especially a structured variable, the terminal node must be of primitive type or a structure containing no indirections and whose descendant members contain no indirections. Furthermore, the path to the desired part must contain one array reference for each level of </a>indirection traversed.<p>
</a>
<a name="158109">
<h1>4.0 </a>Starting </a>PDBDiff</h1>
</a>
<a name="158115">
On UNIX systems a shell script called </a>pdbdiff is provided; it starts up </a>SX and loads the PDBDiff </a>SCHEME forms. You must add a line to your </a>.cshrc or </a>.profile file that defines the </a>environment variable SCHEME. This variable tells SX where to find the PDBDiff program. Consult your system administrator or some other knowledgeable source to find where this is kept. If, for example, the directory /usr/local/scheme contains the PDBDiff program file, add the line:<p>
</a>
<A NAME="158118"><PRE> </a>setenv SCHEME </a>/usr/local/scheme
</PRE><a name="158119">
to your .cshrc or .profile file.<p>
</a>
<A NAME="158216"><BR><B>Usage: pdbdiff [</a>-a] [</a>-b n] [</a>-d] [</a>-i] [</a>-l] [</a>-p f] [</a>-s] [</a>-v] pdb-file1 pdb-file2
</B><BR><A NAME="158121"></a>Options:
<P><A NAME="158123"><PRE> a - </a>display all elements if any differ
</PRE><A NAME="158125"><PRE> b - </a>number of </a>mantissa bits to use in </a>floating point comparisons
</PRE><A NAME="158130"><PRE> d - compare floating point </a>types of differing </a>precision
</PRE><A NAME="158210"><PRE> i - enter </a>interactive mode
</PRE><A NAME="158060"><PRE> l - compare fixed point </a>types of differing </a>precision
</PRE><A NAME="158205"><PRE> p - </a>fractional </a>decimal </a>precision to use in floating point comparisons
</PRE><A NAME="158208"><PRE> s - </a>display only differing elements (default)
</PRE><A NAME="158215"><PRE> v - </a>compare PVA files (batch mode only currently)
</PRE><a name="158084">
<p>
</a>
<a name="158094">
<h1>5.0 </a>PDBDiff </a>Commands</h1>
</a>
<a name="158108">
In this section the PDBDiff commands are listed alphabetically. Each command is given with a brief description of its function and examples of its usage. The examples are intended to illustrate the various ways of invoking each command.<p>
</a>
<A NAME="158316"><BR><B></a>CD
</B><BR><a name="158320">
</a>Change the current file </a>directory in the designated file. The first file is designated by 1, a, or first and the second file is designated by 2, b, or second. If neither file is specified the file directory is changed for both files. The new directory may be specified by either a </a>relative path or a </a>full path.<p>
</a>
<A NAME="158160">Usage: cd [directory] [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]
<P><A NAME="158165">Examples:
<P><A NAME="158168"><PRE> cd /zoo/mammals
</PRE><A NAME="158172"><PRE> cd ../reptiles first
</PRE><A NAME="158173"><PRE> cd
</PRE><A NAME="158107"><BR><B></a>CLOSE
</B><BR><a name="158017">
Close the current pair of files.<p>
</a>
<A NAME="158024">Usage: close
<P><A NAME="158047"><BR><B></a>DESC
</B><BR><a name="158163">
</a>Describe the named variable or </a>structure </a>member in the designated file. The first file is designated by 1, a, or first and the second file is designated by 2, b, or second. To get a description of part of a variable or structure member, qualify the name with </a>index expressions (see the </a>PDBDiff Syntax section for a discussion of index expressions).<p>
</a>
<A NAME="158051">Usage: desc variable | structure-member [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]
<P><A NAME="158029">Examples:
<P><A NAME="158033"><PRE> desc Mapping1
</PRE><A NAME="158131"><PRE> desc Mapping1.range 1
</PRE><A NAME="158038"><PRE> desc baz second
</PRE><A NAME="158187"><BR><B></a>DIFF
</B><BR><a name="158180">
</a>Compare the values of the named variable(s) or </a>structure </a>member(s) in the two open files. If two variable names are provided, the values of the first variable in the first file will be compared with the values of the second variable in the second file. To compare part of a variable or structure member, qualify the name with </a>index expressions (see the </a>PDBDiff Syntax section for a discussion of index expressions). You may specify the </a>format of the </a>output with the </a>mode and </a>set commands.<p>
</a>
<A NAME="158192">Usage: diff variable | structure-member [variable | structure-member]
<P><A NAME="158128">Examples:
<P><A NAME="158040"><PRE> diff Mapping3
</PRE><A NAME="158235"><PRE> diff foo.bar
</PRE><A NAME="158241"><PRE> diff abc def
</PRE><A NAME="158194"><PRE>
</PRE><A NAME="158088"><BR><B></a>END
</B><BR><a name="158046">
End the PDBDiff session.<p>
</a>
<A NAME="158039">Usage: end
<P><A NAME="158041"><BR><B></a>FILE
</B><BR><a name="158056">
</a>Describe a PDB file. The first file is designated by 1, a, or first and the second file is designated by 2, b, or second. <p>
</a>
<A NAME="158061">Usage: file [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]
<P><A NAME="158065">Examples:
<P><A NAME="158090"><PRE> file
</PRE><A NAME="158095"><PRE> file second
</PRE><A NAME="158178"><BR><B></a>FORMAT
</B><BR><a name="158179">
</a>Set the </a>printing format for a specified </a>data </a>type. If the argument specifying the type has ‘</a>1’ or ‘</a>2’ appended, then the new format is applied only to arrays shorter than </a>array-length or to arrays longer than or equal to array-length, respectively. Otherwise, the format applies to both. Invoking the format command with the single argument, </a>default, causes the formats for all types to be reset to their default values. The format argument must be a Standard C I/O Library format string. </a>Double </a>quotes are only necessary if the format string contains </a>embedded </a>blanks. See the </a>set command for more information about the array-length display control parameter. This command overrides the settings of the </a>decimal-precision and </a>bits-precision </a>display </a>control </a>parameters.<p>
</a>
<A NAME="158181">Usage: format </a>integer[1 | 2] | </a>long[1 | 2] | </a>float[1 | 2] |
<P><A NAME="158182"><PRE> </a>double[1 | 2] | </a>short[1 | 2] | </a>char[1 | 2] format
</PRE><A NAME="158189">Usage: format default
<P><A NAME="158186">Examples:
<P><A NAME="158183"><PRE> format double </a>%12.5</a>e
</PRE><A NAME="158185"><PRE> format double2 %10.2e
</PRE><A NAME="158191"><PRE> format char “</a>%s “
</PRE><A NAME="158203"><PRE> format default
</PRE><A NAME="158043"><BR><B></a>HELP
</B><BR><a name="158053">
</a>Print a list of the available commands or information about the specified command.<p>
</a>
<A NAME="158104">Usage: help [command]
<P><A NAME="158058">Examples:
<P><A NAME="158045"><PRE> help
</PRE><A NAME="158188"><PRE> help open
</PRE><A NAME="158327"><BR><B></a>LS
</B><BR><a name="158360">
</a>List the names of variables, links, and directories in the designated file. The first file is designated by 1, a, or first and the second file is designated by 2, b, or second. If neither file is specified the information is listed for both files. Directories have a terminal slash. An optional </a>selection </a>pattern may be specified. Each ‘</a>?’ in the pattern matches any single character. Each ‘</a>*’ in the pattern matches any string of zero or more characters. An optional </a>type qualifier may also be specified in order restrict the list to a given type. A type qualifier of ‘*’ may be used to match all types. Both a selection pattern and a type qualifier must be specified if you wish to designate a file.<p>
</a>
<A NAME="158372">Usage: ls [pattern [type [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]]]
<P><A NAME="158174">Examples:
<P><A NAME="158175"><PRE> ls dir1/curve*
</PRE><A NAME="158177"><PRE> ls var? integer second
</PRE><A NAME="158184"><PRE> ls * Directory
</PRE><A NAME="158358"><PRE> ls * * first
</PRE><A NAME="158143"><BR><B></a>MODE
</B><BR><a name="158079">
</a>Set the </a>print mode for </a>arrays and </a>structures.<p>
</a>
<a name="158086">
</a>Display modes are:<p>
</a>
<A NAME="158072"><PRE> </a>full-path - the full </a>path name is printed at each </a>branch, e.g. foo.bar[3].baz
</PRE><A NAME="158149"><PRE> </a>indent - indent 4 spaces at each branch (</a>default)
</PRE><A NAME="158153"><PRE> </a>tree - display as a tree (lines connecting branches)
</PRE><a name="158068">
Type display is controlled by:<p>
</a>
<A NAME="158064"><PRE> </a>no-type - turns off the display of types (</a>default)
</PRE><A NAME="158063"><PRE> </a>type - displays the type of each item and branch
</PRE><a name="158035">
Display of recursive structures is controlled by:<p>
</a>
<A NAME="158037"><PRE> </a>recursive - indent each level of </a>recursive structures
</PRE><A NAME="158050"><PRE> </a>iterative - number each level of recursive structures (</a>default)
</PRE><a name="158066">
</a>Display of differing elements is controlled by:<p>
</a>
<A NAME="158155"><PRE> </a>individual - </a>display only differing elements (</a>default)
</PRE><A NAME="158059"><PRE> </a>display-all - </a>display all elements if even one differs
</PRE><A NAME="158057">Usage: mode full-path | indent | tree | no-type | type |
<P><A NAME="158132"><PRE> recursive | iterative | individual | display-all
</PRE><A NAME="158133">Example:
<P><A NAME="158085"><PRE> mode no-type
</PRE><A NAME="158162"><BR><B></a>OPEN
</B><BR><a name="158087">
Open a new pair of files.<p>
</a>
<A NAME="158164">Usage: open filename1 filename2
<P><A NAME="158021">Example:
<P><A NAME="158089"><PRE> open foo.s00 bar.s00
</PRE><A NAME="158022"><BR><B></a>PRINT
</B><BR><a name="158097">
Print out all or part of the specified variable or </a>structure </a>member from the first or second file. The first file is designated by 1, a, or first and the second file is designated by 2, b, or second. To </a>print part of a variable or structure member, qualify the name with </a>index expressions (see the </a>PDBDiff Syntax section for a discussion of index expressions).<p>
</a>
<A NAME="158103">Usage: print variable | structure-member [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]
<P><A NAME="158166">Examples:
<P><A NAME="158167"><PRE> Mapping2 first
</PRE><A NAME="158169"><PRE> print Mapping2.range.elements[1] 2
</PRE><A NAME="158170"><PRE> a[5,10:20,1:8:3]
</PRE><A NAME="158176"><PRE> print a.b[3].c[5,10:20,1:8:3] b
</PRE><A NAME="158213"><BR><B></a>PROMOTE
</B><BR><a name="158219">
Promote lower </a>precision types in the specified </a>class or classes to higher precision to permit comparison, if necessary. Turn off promotion for classes not specified. The default is no promotion.<p>
</a>
<A NAME="158220">Usage: promote [</a>fixed] [</a>float]
<P><A NAME="158221">Examples:
<P><A NAME="158222"><PRE> promote
</PRE><A NAME="158223"><PRE> promote fixed
</PRE><A NAME="158224"><PRE> promote float
</PRE><A NAME="158225"><PRE> promote fixed float
</PRE><A NAME="158190"><BR><B></a>PWD
</B><BR><a name="158390">
</a>Print the </a>current file </a>directory for the designated file.The first file is designated by 1, a, or first and the second file is designated by 2, b, or second. If neither file is specified the current file directory will be printed for both files. NOTE: If the current file directory is the same for both files, it will only be printed once.<p>
</a>
<A NAME="158397">Usage: pwd [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]
<P><A NAME="158398">Examples:
<P><A NAME="158384"><PRE> pwd
</PRE><A NAME="158385"><PRE> pwd first
</PRE><A NAME="158054"><BR><B></a>SET
</B><BR><a name="158055">
Set the value of some </a>display </a>parameters. Parameters:<p>
</a>
<A NAME="158110"><PRE> </a>line-length - </a>number of array elements per line
</PRE><A NAME="158112"><PRE> </a>array-length - for arrays shorter than value, label </a>each element individually
</PRE><A NAME="158069"><PRE> </a>bits-precision - </a>number of </a>mantissa bits compared in </a>floating point numbers
</PRE><A NAME="158070"><PRE> </a>decimal-precision - limit on the </a>fractional difference reported
</PRE><A NAME="158114">Usage: set line-length | array-length | bits-precision | decimal-precision value
<P><A NAME="158023">Examples:
<P><A NAME="158116"><PRE> set line-length 3
</PRE><A NAME="158117"><PRE> set array-length 20
</PRE><A NAME="158082"><PRE> set bits-precision 10
</PRE><A NAME="158026"><PRE> set decimal-precision 1.0e-6
</PRE><A NAME="158196"><BR><B></a>STRUCT
</B><BR><a name="158099">
</a>Describe the named </a>data type in the specified file. The first file is designated by 1, a, or first and the second file is designated by 2, b, or second.<p>
</a>
<A NAME="158198">Usage: struct data-type [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]
<P><A NAME="158129">Examples:
<P><A NAME="158100"><PRE> struct double 1
</PRE><A NAME="158199"><PRE> struct PM_mapping second
</PRE><A NAME="158071"><BR><B></a>TRANSCRIPT
</B><BR><a name="158080">
</a>Toggle a transcript of the PDBDiff session. The name of the </a>transcript file may be specified when the transcript is activated. A file named </a>pdbdiff.trn will contain the </a>transcript of the session if no name is given.<p>
</a>
<A NAME="158093">Usage: transcript [filename]
<P><A NAME="158134">Examples:
<P><A NAME="158096"><PRE> transcript
</PRE><A NAME="158101"><PRE> transcript foo.bar
</PRE><A NAME="158204"><BR><B></a>TYPES
</B><BR><a name="158102">
</a>List the data types in the designated file.The first file is designated by 1, a, or first and the second file is designated by 2, b, or second. If neither file is specified the data types will be printed for both files.<p>
</a>
<A NAME="158206">Usage: types [</a>1 | </a>a | </a>first | </a>2 | </a>b | </a>second]
<P><A NAME="158419">Examples:
<P><A NAME="158420"><PRE> types
</PRE><A NAME="158421"><PRE> types second
</PRE><a name="158209">
<h1>6.0 </a></a>Default State</h1>
</a>
<a name="158111">
The </a>initial state of PDBDiff is:<p>
</a>
<ul><a name="158211">
<li></a>mode </a>indent
</a>
<a name="158195">
<li>mode </a>no-type
</a>
<a name="158042">
<li>mode </a>iterative
</a>
<a name="158212">
<li>mode </a>individual
</a>
<a name="158193">
<li></a>set </a>line-length 2
</a>
<a name="158052">
<li>set </a>array-length 4
</a>
<a name="158025">
<li>set </a>bits-precision 128 (i.e. </a>use all </a>mantissa bits in </a>floating point comparisons)
</a>
</ul><a name="158214">
<h1>7.0 Other </a>PACT Documents</h1>
</a>
<a name="158030">
Interested readers may wish to refer to the other </a>PACT </a>documents which describe the data structures and functionality underlying the more common </a>PDB files upon which PDBDiff operates. The </a>PANACEA, </a>PGS, and </a>PDBLib </a>manuals are of special interest to people who wish to generate and view data files with PACT.<p>
</a>
<a name="158028">
The list of PACT Documents is:<p>
</a>
<A NAME="158067"><PRE> PACT User’s Guide, UCRL-MA-112087
</PRE><A NAME="158081"><PRE> SCORE User’s Manual, UCRL-MA-108976 Rev.1
</PRE><A NAME="158083"><PRE> PPC User’s Manual UCRL-MA-108964 Rev.1
</PRE><A NAME="158092"><PRE> PML User’s Manual, UCRL-MA-108965 Rev.1
</PRE><A NAME="158113"><PRE> PDBLib User’s Manual, M-270 Rev.2
</PRE><A NAME="158152"><PRE> PGS User’s Manual, UCRL-MA-108966 Rev.1
</PRE><A NAME="158158"><PRE> PANACEA User’s Manual, M-276 Rev.2
</PRE><A NAME="158159"><PRE> ULTRA II User’s Manual, UCRL-MA-108967 Rev.1
</PRE><A NAME="158161"><PRE> PDBDiff User’s Manual, UCRL-MA-108975 Rev.1 (this document)
</PRE><A NAME="158171"><PRE> PDBView User’s Manual, UCRL-MA-108968 Rev.1
</PRE><A NAME="158034"><PRE> SX User’s Manual, UCRL-MA-112315
</PRE><a name="158150">
<p>
</a>
<p><hr>
</body></html>
|
