From 1d3b37782fa50af944654ee98d3f580a41bcb245 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Wed, 15 Sep 2010 22:15:54 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@4794 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/dump.html | 57 +++++++++++++++++++++----------------------- doc/dump.txt | 57 +++++++++++++++++++++----------------------- doc/dump_modify.html | 28 ++++++++++++++++------ doc/dump_modify.txt | 28 ++++++++++++++++------ 4 files changed, 96 insertions(+), 74 deletions(-) diff --git a/doc/dump.html b/doc/dump.html index dd05e52dde..b0afc59733 100644 --- a/doc/dump.html +++ b/doc/dump.html @@ -108,22 +108,20 @@ on timesteps when neighbor lists are rebuilt, the coordinates of an atom written to a dump file may be slightly outside the simulation box.

-

When LAMMPS is running on a single processor, if the atom_modify -sort option is on, which it is by default, then -atoms are re-ordered periodically during a simulation, due to spatial -sorting, and hence the atom information written to dump files +

IMPORTANT NOTE: Unless the dump_modify sort option +is invoked, the lines of atom information written to dump files (typically one line per atom) will be in an indeterminate order for -each snapshot. +each snapshot. This is even true when running on a single processor, +if the atom_modify sort option is on, which it is +by default. In this case atoms are re-ordered periodically during a +simulation, due to spatial sorting. It is also true when running in +parallel, because data for a single snapshot is collected from +multiple processors.

-

When LAMMPS is running in parallel, this is also true, both due to -sorting and because data for a single snapshot is collected from -multiple processors. This is the case for the atom, local, and -custom styles. It is also the case for the xyz style if the dump -group is not all. It is not the case for the dcd and xtc styles -which always write atoms in sorted order. So does the xyz style if -the dump group is all. The cfg style supports the sort option -of the dump_modify command which allows sorting to -be turned on or off. +

For the atom, custom, cfg, and local styles, sorting is off by +default. For the dcd, xtc, and xyz styles, sorting by atom ID +is on by default. See the dump_modify doc page for +details.

@@ -199,14 +197,14 @@ atoms appropriately.

The dcd style writes DCD files, a standard atomic trajectory format used by the CHARMM, NAMD, and XPlor molecular dynamics packages. DCD files are binary and thus may not be portable to different machines. -The dump group must be all for the dcd style. The unwrap option -of the dump_modify command allows DCD coordinates -to be written "unwrapped" by the image flags for each atom. Unwrapped -means that if the atom has passed thru a periodic boundary one or more -times, the value is printed for what the coordinate would be if it had -not been wrapped back into the periodic box. Note that these -coordinates may thus be far outside the box size stored with the -snapshot. +The number of atoms per snapshot cannot change with the dcd style. +The unwrap option of the dump_modify command +allows DCD coordinates to be written "unwrapped" by the image flags +for each atom. Unwrapped means that if the atom has passed thru a +periodic boundary one or more times, the value is printed for what the +coordinate would be if it had not been wrapped back into the periodic +box. Note that these coordinates may thus be far outside the box size +stored with the snapshot.

The xtc style writes XTC files, a compressed trajectory format used by the GROMACS molecular dynamics package, and described @@ -216,14 +214,13 @@ The precision used in XTC files can be adjusted via the means that coordinates are stored to 1/1000 nanometer accuracy. XTC files are portable binary files written in the NFS XDR data format, so that any machine which supports XDR should be able to read them. The -dump group must be all for the xtc style. The unwrap option of -the dump_modify command allows XTC coordinates to -be written "unwrapped" by the image flags for each atom. Unwrapped -means that if the atom has passed thru a periodic boundary one or more -times, the value is printed for what the coordinate would be if it had -not been wrapped back into the periodic box. Note that these -coordinates may thus be far outside the box size stored with the -snapshot. +unwrap option of the dump_modify command allows +XTC coordinates to be written "unwrapped" by the image flags for each +atom. Unwrapped means that if the atom has passed thru a periodic +boundary one or more times, the value is printed for what the +coordinate would be if it had not been wrapped back into the periodic +box. Note that these coordinates may thus be far outside the box size +stored with the snapshot.

The xyz style writes XYZ files, which is a simple text-based coordinate format that many codes can read. diff --git a/doc/dump.txt b/doc/dump.txt index edff15a51c..4d5091b995 100644 --- a/doc/dump.txt +++ b/doc/dump.txt @@ -98,22 +98,20 @@ on timesteps when neighbor lists are rebuilt, the coordinates of an atom written to a dump file may be slightly outside the simulation box. -When LAMMPS is running on a single processor, if the "atom_modify -sort"_atom_modify.html option is on, which it is by default, then -atoms are re-ordered periodically during a simulation, due to spatial -sorting, and hence the atom information written to dump files +IMPORTANT NOTE: Unless the "dump_modify sort"_dump_modify.html option +is invoked, the lines of atom information written to dump files (typically one line per atom) will be in an indeterminate order for -each snapshot. +each snapshot. This is even true when running on a single processor, +if the "atom_modify sort"_atom_modify.html option is on, which it is +by default. In this case atoms are re-ordered periodically during a +simulation, due to spatial sorting. It is also true when running in +parallel, because data for a single snapshot is collected from +multiple processors. -When LAMMPS is running in parallel, this is also true, both due to -sorting and because data for a single snapshot is collected from -multiple processors. This is the case for the {atom}, {local}, and -{custom} styles. It is also the case for the {xyz} style if the dump -group is not {all}. It is not the case for the {dcd} and {xtc} styles -which always write atoms in sorted order. So does the {xyz} style if -the dump group is {all}. The {cfg} style supports the {sort} option -of the "dump_modify"_dump_modify.html command which allows sorting to -be turned on or off. +For the {atom}, {custom}, {cfg}, and {local} styles, sorting is off by +default. For the {dcd}, {xtc}, and {xyz} styles, sorting by atom ID +is on by default. See the "dump_modify"_dump_modify.html doc page for +details. :line @@ -189,14 +187,14 @@ atoms appropriately. The {dcd} style writes DCD files, a standard atomic trajectory format used by the CHARMM, NAMD, and XPlor molecular dynamics packages. DCD files are binary and thus may not be portable to different machines. -The dump group must be {all} for the {dcd} style. The {unwrap} option -of the "dump_modify"_dump_modify.html command allows DCD coordinates -to be written "unwrapped" by the image flags for each atom. Unwrapped -means that if the atom has passed thru a periodic boundary one or more -times, the value is printed for what the coordinate would be if it had -not been wrapped back into the periodic box. Note that these -coordinates may thus be far outside the box size stored with the -snapshot. +The number of atoms per snapshot cannot change with the {dcd} style. +The {unwrap} option of the "dump_modify"_dump_modify.html command +allows DCD coordinates to be written "unwrapped" by the image flags +for each atom. Unwrapped means that if the atom has passed thru a +periodic boundary one or more times, the value is printed for what the +coordinate would be if it had not been wrapped back into the periodic +box. Note that these coordinates may thus be far outside the box size +stored with the snapshot. The {xtc} style writes XTC files, a compressed trajectory format used by the GROMACS molecular dynamics package, and described @@ -206,14 +204,13 @@ The precision used in XTC files can be adjusted via the means that coordinates are stored to 1/1000 nanometer accuracy. XTC files are portable binary files written in the NFS XDR data format, so that any machine which supports XDR should be able to read them. The -dump group must be {all} for the {xtc} style. The {unwrap} option of -the "dump_modify"_dump_modify.html command allows XTC coordinates to -be written "unwrapped" by the image flags for each atom. Unwrapped -means that if the atom has passed thru a periodic boundary one or more -times, the value is printed for what the coordinate would be if it had -not been wrapped back into the periodic box. Note that these -coordinates may thus be far outside the box size stored with the -snapshot. +{unwrap} option of the "dump_modify"_dump_modify.html command allows +XTC coordinates to be written "unwrapped" by the image flags for each +atom. Unwrapped means that if the atom has passed thru a periodic +boundary one or more times, the value is printed for what the +coordinate would be if it had not been wrapped back into the periodic +box. Note that these coordinates may thus be far outside the box size +stored with the snapshot. The {xyz} style writes XYZ files, which is a simple text-based coordinate format that many codes can read. diff --git a/doc/dump_modify.html b/doc/dump_modify.html index 3a18ca5686..e9795dc0d7 100644 --- a/doc/dump_modify.html +++ b/doc/dump_modify.html @@ -36,7 +36,10 @@ precision arg = power-of-10 value from 10 to 1000000 region arg = region-ID or "none" scale arg = yes or no - sort arg = yes or no + sort arg = off or 0 or N + off = no sorting of per-atom lines within a snapshot + 0 = sort per-atom lines by atom ID + N = sort per-atom lines by the Nth column thresh args = attribute operation value attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style operation = "<" or "<=" or ">" or ">=" or "==" or "!=" @@ -169,11 +172,21 @@ value of yes means atom coords are written in normalized units from value of no means they are written in absolute distance units (e.g. Angstroms or sigma).

-

The sort keyword applies only to the dump cfg style. A sort value -of yes means atoms will be written into the CFG file in sorted -order, sorted by the atom ID. A value of no means a sort will not -be performed and that atoms may be in an indeterminate order, -depending on which processor owns which atoms. +

The sort keyword determines whether lines of per-atom output in a +snapshot are sorted or not. A sort value of off means they will +typically be written in indeterminate order, either in serial or +parallel. This is the case even in serial if the atom_modify +sort option is turned on, which it is by default, to +improve performance. A sort value of 0 means sort the output by atom +ID. A sort value of N means sort the output by the value in the Nth +column of per-atom info. The dump local style cannot be sorted by +atom ID, since there are typically multiple lines of output per atom. +Some dump styles, such as dcd and xtc, require sorting by atom +ID to format the output file correctly. +

+

IMPORTANT NOTE: Unless it is required by the dump style, sorting dump +file output requires extra overhead in terms of CPU and communication +cost, as well as memory.

The thresh keyword only applies to the dump custom and cfg styles. Multiple thresholds can be specified. Specifying "none" @@ -215,7 +228,8 @@ box size stored with the snapshot.

  • precision = 1000
  • region = none
  • scale = yes -
  • sort = no +
  • sort = off for dump styles atom, custom, cfg, and local +
  • sort = 0 for dump styles dcd, xtc, and xyz meaning sort by atom ID
  • thresh = none
  • unwrap = no diff --git a/doc/dump_modify.txt b/doc/dump_modify.txt index 27ca230a71..4e3b9fef10 100644 --- a/doc/dump_modify.txt +++ b/doc/dump_modify.txt @@ -30,7 +30,10 @@ keyword = {append} or {every} or {flush} or {format} or {image} or {label} or {p {precision} arg = power-of-10 value from 10 to 1000000 {region} arg = region-ID or "none" {scale} arg = {yes} or {no} - {sort} arg = {yes} or {no} + {sort} arg = {off} or 0 or N + off = no sorting of per-atom lines within a snapshot + 0 = sort per-atom lines by atom ID + N = sort per-atom lines by the Nth column {thresh} args = attribute operation value attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style operation = "<" or "<=" or ">" or ">=" or "==" or "!=" @@ -162,11 +165,21 @@ value of {yes} means atom coords are written in normalized units from value of {no} means they are written in absolute distance units (e.g. Angstroms or sigma). -The {sort} keyword applies only to the dump {cfg} style. A sort value -of {yes} means atoms will be written into the CFG file in sorted -order, sorted by the atom ID. A value of {no} means a sort will not -be performed and that atoms may be in an indeterminate order, -depending on which processor owns which atoms. +The {sort} keyword determines whether lines of per-atom output in a +snapshot are sorted or not. A sort value of {off} means they will +typically be written in indeterminate order, either in serial or +parallel. This is the case even in serial if the "atom_modify +sort"_atom_modify.html option is turned on, which it is by default, to +improve performance. A sort value of 0 means sort the output by atom +ID. A sort value of N means sort the output by the value in the Nth +column of per-atom info. The dump {local} style cannot be sorted by +atom ID, since there are typically multiple lines of output per atom. +Some dump styles, such as {dcd} and {xtc}, require sorting by atom +ID to format the output file correctly. + +IMPORTANT NOTE: Unless it is required by the dump style, sorting dump +file output requires extra overhead in terms of CPU and communication +cost, as well as memory. The {thresh} keyword only applies to the dump {custom} and {cfg} styles. Multiple thresholds can be specified. Specifying "none" @@ -208,6 +221,7 @@ label = ENTRIES precision = 1000 region = none scale = yes -sort = no +sort = off for dump styles {atom}, {custom}, {cfg}, and {local} +sort = 0 for dump styles {dcd}, {xtc}, and {xyz} meaning sort by atom ID thresh = none unwrap = no :ul