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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
|
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>read_dump command — LIGGGHTS v3.X documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="top" title="LIGGGHTS v3.X documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LIGGGHTS
</a>
<div class="version">
v3.X
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_input_script.html">3. Input Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">4. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_gran_models.html">5. Contact models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_mesh_modules.html">6. Mesh modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">7. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">8. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">9. Modifying & extending LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">10. Python interface to LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">11. Errors</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LIGGGHTS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>read_dump command</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/read_dump.txt" rel="nofollow"> View page source</a>
<a href="http://www.cfdem.com"> Website</a>
<a href="Section_commands.html#comm" rel="nofollow"> Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="read-dump-command">
<span id="index-0"></span><h1>read_dump command<a class="headerlink" href="#read-dump-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>read_dump file Nstep field1 field2 ... keyword values ...
</pre></div>
</div>
<ul class="simple">
<li>file = name of dump file to read</li>
<li>Nstep = snapshot timestep to read from file</li>
<li>one or more fields may be appended</li>
</ul>
<pre class="literal-block">
field = <em>x</em> or <em>y</em> or <em>z</em> or <em>vx</em> or <em>vy</em> or <em>vz</em> or <em>q</em> or <em>ix</em> or <em>iy</em> or <em>iz</em>
<em>x</em>,*y*,*z* = atom coordinates
<em>radius</em> = atom radii
<em>vx</em>,*vy*,*vz* = velocity components
<em>q</em> = charge
<em>ix</em>,*iy*,*iz* = image flags in each dimension
</pre>
<ul class="simple">
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>box</em> or <em>replace</em> or <em>purge</em> or <em>trim</em> or <em>add</em> or <em>label</em> or <em>scaled</em> or <em>wrapped</em> or <em>format</em></li>
</ul>
<pre class="literal-block">
<em>box</em> value = <em>yes</em> or <em>no</em> = replace simulation box with dump box
<em>replace</em> value = <em>yes</em> or <em>no</em> = overwrite atoms with dump atoms
<em>purge</em> value = <em>yes</em> or <em>no</em> = delete all atoms before adding dump atoms
<em>trim</em> value = <em>yes</em> or <em>no</em> = trim atoms not in dump snapshot
<em>add</em> value = <em>yes</em> or <em>no</em> = add new dump atoms to system
<em>label</em> value = field column
field = one of the listed fields or <em>id</em> or <em>type</em>
column = label on corresponding column in dump file
<em>scaled</em> value = <em>yes</em> or <em>no</em> = coords in dump file are scaled/unscaled
<em>wrapped</em> value = <em>yes</em> or <em>no</em> = coords in dump file are wrapped/unwrapped
<em>format</em> values = format of dump file, must be last keyword if used
<em>native</em> = native LIGGGHTS(R)-PUBLIC dump file
<em>xyz</em> = XYZ file
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>read_dump dump.file 5000 x y z radius
read_dump dump.xyz 5 x y z radius format xyz box no
read_dump dump.file 5000 x y vx vy radius trim yes
read_dump ../run7/dump.file.gz 10000 x y z radius box yes
read_dump dump.xyz 5 x y z radius box no format xyz
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Read atom information from a dump file to overwrite the current atom
coordinates, and optionally the atom velocities and image flags and
the simluation box dimensions. This is useful for restarting a run
from a particular snapshot in a dump file. See the
<a class="reference internal" href="read_restart.html"><em>read_restart</em></a> and <a class="reference internal" href="read_data.html"><em>read_data</em></a>
commands for alternative methods to do this. Also see the
<code class="xref doc docutils literal"><span class="pre">rerun</span></code> command for a means of reading multiple snapshots
from a dump file.</p>
<p>Note that a simulation box must already be defined before using the
read_dump command. This can be done by the
<a class="reference internal" href="create_box.html"><em>create_box</em></a>, <a class="reference internal" href="read_data.html"><em>read_data</em></a>, or
<a class="reference internal" href="read_restart.html"><em>read_restart</em></a> commands. The read_dump command can
reset the simulation box dimensions, as explained below.</p>
<p>Since LIGGGHTS(R)-PUBLIC needs valid radii, the radius field is mandatory
to be read.</p>
<p>Also note that reading per-atom information from a dump snapshot is
limited to the atom coordinates, radii, velocities and image flags, as
explained below. Other atom properties, which may be necessary to run
a valid simulation, such as atom charge, or bond topology information
for a molecular system, are not read from (or even contained in) dump
files. Thus this auxiliary information should be defined in the usual
way, e.g. in a data file read in by a <a class="reference internal" href="read_data.html"><em>read_data</em></a>
command, before using the read_dump command, or by the <a class="reference internal" href="set.html"><em>set</em></a>
command, after the dump snapshot is read.</p>
<hr class="docutils" />
<p>If the dump filename specified as <em>file</em> ends with ”.gz”, the dump
file is read in gzipped format. You cannot (yet) read a dump file
that was written in binary format with a ”.bin” suffix, or to multiple
files via the “%” option in the dump file name. See the
<a class="reference internal" href="dump.html"><em>dump</em></a> command for details.</p>
<p>The format of the dump file is selected through the <em>format</em> keyword.
If specified, it must be the last keyword used, since all remaining
arguments are passed on to the dump reader. The <em>native</em> format is
for native LIGGGHTS(R)-PUBLIC dump files, written with a “dump atom”.html or <a class="reference internal" href="dump.html"><em>dump custom</em></a> command. The <em>xyz</em> format is for generic XYZ
formatted dump files,</p>
<p>Support for other dump format readers may be added in the future.</p>
<hr class="docutils" />
<p>Global information is first read from the dump file, namely timestep
and box information.</p>
<p>The dump file is scanned for a snapshot with a time stamp that matches
the specified <em>Nstep</em>. This means the LIGGGHTS(R)-PUBLIC timestep the dump file
snapshot was written on for the <em>native</em> format. However, the <em>xyz</em>
formats do not store the timestep. For these formats,
timesteps are numbered logically, in a sequential manner, starting
from 0. Thus to access the 10th snapshot in an <em>xyz</em> or <em>mofile</em>
formatted dump file, use <em>Nstep</em> = 9.</p>
<p>The dimensions of the simulation box for the selected snapshot are
also read; see the <em>box</em> keyword discussion below. For the <em>native</em>
format, an error is generated if the snapshot is for a triclinic box
and the current simulation box is orthogonal or vice versa. A warning
will be generated if the snapshot box boundary conditions (periodic,
shrink-wrapped, etc) do not match the current simulation boundary
conditions, but the boundary condition information in the snapshot is
otherwise ignored. See the “boundary” command for more details.</p>
<p>For the <em>xyz</em> format, no information about the box is available, so
you must set the <em>box</em> flag to <em>no</em>. See details below.</p>
<hr class="docutils" />
<p>Per-atom information from the dump file snapshot is then read from the
dump file snapshot. This corresponds to the specified <em>fields</em> listed
in the read_dump command. It is an error to specify a z-dimension
field, namely <em>z</em>, <em>vz</em>, or <em>iz</em>, for a 2d simulation.</p>
<p>For dump files in <em>native</em> format, each column of per-atom data has a
text label listed in the file. A matching label for each field must
appear, e.g. the label “vy” for the field <em>vy</em>. For the <em>x</em>, <em>y</em>, <em>z</em>
fields any of the following labels are considered a match:</p>
<pre class="literal-block">
x, xs, xu, xsu for field <em>x</em>
y, ys, yu, ysu for field <em>y</em>
z, zs, zu, zsu for field <em>z</em>
</pre>
<p>The meaning of xs (scaled), xu (unwrapped), and xsu (scaled and
unwrapped) is explained on the <a class="reference internal" href="dump.html"><em>dump</em></a> command doc page.
These labels are searched for in the list of column labels in the dump
file, in order, until a match is found.</p>
<p>The dump file must also contain atom IDs, with a column label of “id”.</p>
<p>If the <em>add</em> keyword is specified with a value of <em>yes</em>, as discussed
below, the dump file must contain atom types, with a column label of
“type”.</p>
<p>If a column label you want to read from the dump file is not a match
to a specified field, the <em>label</em> keyword can be used to specify the
specific column label from the dump file to associate with that field.
An example is if a time-averaged coordinate is written to the dump
file via the <a class="reference internal" href="fix_ave_atom.html"><em>fix ave/atom</em></a> command. The column
will then have a label corresponding to the fix-ID rather than “x” or
“xs”. The <em>label</em> keyword can also be used to specify new column
labels for fields <em>id</em> and <em>type</em>.</p>
<p>For dump files in <em>xyz</em> format, only the <em>x</em>, <em>y</em>, and <em>z</em> fields are
supported. The dump file does not store atom IDs, so these are
assigned consecutively to the atoms as they appear in the dump file,
starting from 1. Thus you should insure that order of atoms is
consistent from snapshot to snapshot in the the XYZ dump file. See
the <a class="reference internal" href="dump_modify.html"><em>dump_modify sort</em></a> command if the XYZ dump file
was written by LIGGGHTS(R)-PUBLIC.</p>
<hr class="docutils" />
<p>Information from the dump file snapshot is used to overwrite or
replace properties of the current system. There are various options
for how this is done, determined by the specified fields and optional
keywords.</p>
<p>The timestep of the snapshot becomes the current timestep for the
simulation. See the <a class="reference internal" href="reset_timestep.html"><em>reset_timestep</em></a> command if
you wish to change this after the dump snapshot is read.</p>
<p>If the <em>box</em> keyword is specified with a <em>yes</em> value, then the current
simulation box dimensions are replaced by the dump snapshot box
dimensions. If the <em>box</em> keyword is specified with a <em>no</em> value, the
current simulatoin box is unchanged.</p>
<p>If the <em>purge</em> keyword is specified with a <em>yes</em> value, then all
current atoms in the system are deleted before any of the operations
invoked by the <em>replace</em>, <em>trim</em>, or <em>add</em> keywords take place.</p>
<p>If the <em>replace</em> keyword is specified with a <em>yes</em> value, then atoms
with IDs that are in both the current system and the dump snapshot
have their properties overwritten by field values. If the <em>replace</em>
keyword is specified with a <em>no</em> value, atoms with IDs that are in
both the current system and the dump snapshot are not modified.</p>
<p>If the <em>trim</em> keyword is specified with a <em>yes</em> value, then atoms with
IDs that are in the current system but not in the dump snapshot are
deleted. These atoms are unaffected if the <em>trim</em> keyword is
specified with a <em>no</em> value.</p>
<p>If the <em>add</em> keyword is specified with a <em>yes</em> value, then atoms with
IDs that are in the dump snapshot, but not in the current system are
added to the system. These dump atoms are ignored if the <em>add</em>
keyword is specified with a <em>no</em> value.</p>
<p>Note that atoms added via the <em>add</em> keyword will have only the
attributes read from the dump file due to the <em>field</em> arguments. If
<em>x</em> or <em>y</em> or <em>z</em> is not specified as a field, a value of 0.0 is used
for added atoms. Added atoms must have an atom type, so this value
must appear in the dump file.</p>
<p>Any other attributes (e.g. charge or particle diameter for spherical
particles) will be set to default values, the same as if the
<a class="reference internal" href="create_atoms.html"><em>create_atoms</em></a> command were used.</p>
<p>Note that atom IDs are not preserved for new dump snapshot atoms added
via the <em>add</em> keyword. The procedure for assigning new atom IDS to
added atoms is the same as is described for the
<a class="reference internal" href="create_atoms.html"><em>create_atoms</em></a> command.</p>
<hr class="docutils" />
<p>Atom coordinates read from the dump file are first converted into
unscaled coordinates, relative to the box dimensions of the snapshot.
These coordinates are then be assigned to an existing or new atom in
the current simulation. The coordinates will then be remapped to the
simulation box, whether it is the original box or the dump snapshot
box. If periodic boundary conditions apply, this means the atom will
be remapped back into the simulation box if necessary. If shrink-wrap
boundary conditions apply, the new coordinates may change the
simulation box dimensions. If fixed boundary conditions apply, the
atom will be lost if it is outside the simulation box.</p>
<p>For <em>native</em> format dump files, the 3 xyz image flags for an atom in
the dump file are set to the corresponding values appearing in the
dump file if the <em>ix</em>, <em>iy</em>, <em>iz</em> fields are specified. If not
specified, the image flags for replaced atoms are not changed and
image flags for new atoms are set to default values. If coordinates
read from the dump file are in unwrapped format (e.g. <em>xu</em>) then the
image flags for read-in atoms are also set to default values. The
remapping procedure described in the previous paragraph will then
change images flags for all atoms (old and new) if periodic boundary
conditions are applied to remap an atom back into the simulation box.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you get a warning about inconsistent image flags
after reading in a dump snapshot, it means one or more pairs of bonded
atoms now have inconsistent image flags. As discussed in <a class="reference internal" href="Section_errors.html"><em>Section errors</em></a> this may or may not cause problems for
subsequent simulations, One way this can happen is if you read image
flag fields from the dump file but do not also use the dump file box
parameters.</p>
</div>
<p>LIGGGHTS(R)-PUBLIC knows how to compute unscaled and remapped coordinates for the
snapshot column labels discussed above, e.g. <em>x</em>, <em>xs</em>, <em>xu</em>, <em>xsu</em>.
If another column label is assigned to the <em>x</em> or <em>y</em> or <em>z</em> field via
the <em>label</em> keyword, e.g. for coordinates output by the <a class="reference internal" href="fix_ave_atom.html"><em>fix ave/atom</em></a> command, then LIGGGHTS(R)-PUBLIC needs to know whether
the coordinate information in the dump file is scaled and/or wrapped.
This can be set via the <em>scaled</em> and <em>wrapped</em> keywords. Note that
the value of the <em>scaled</em> and <em>wrapped</em> keywords is ignored for fields
<em>x</em> or <em>y</em> or <em>z</em> if the <em>label</em> keyword is not used to assign a
column label to that field.</p>
<p>The scaled/unscaled and wrapped/unwrapped setting must be identical
for any of the <em>x</em>, <em>y</em>, <em>z</em> fields that are specified. Thus you
cannot read <em>xs</em> and <em>yu</em> from the dump file. Also, if the dump file
coordinates are scaled and the simulation box is triclinic, then all 3
of the <em>x</em>, <em>y</em>, <em>z</em> fields must be specified, since they are all
needed to generate absolute, unscaled coordinates.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>To read gzipped dump files, you must compile LIGGGHTS(R)-PUBLIC with the
-DLAMMPS_GZIP option - see the <span class="xref std std-ref">Making LIGGGHTS(R)-PUBLIC</span> section of the documentation.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="dump.html"><em>dump</em></a>,
<a class="reference internal" href="read_data.html"><em>read_data</em></a>, <a class="reference internal" href="read_restart.html"><em>read_restart</em></a>,
<code class="xref doc docutils literal"><span class="pre">rerun</span></code></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The option defaults are box = yes, replace = yes, purge = no, trim =
no, add = no, scaled = no, wrapped = yes, and format = native.</p>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2016, DCS Computing GmbH, JKU Linz and Sandia Corporation.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'v3.X',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: ''
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
|
