From af658bc7258e977189f3e425128335498fabb587 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Fri, 17 Jan 2014 19:02:13 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@11251 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/Section_start.html | 79 +++++++++++++++++++----------------- doc/Section_start.txt | 79 +++++++++++++++++++----------------- doc/atom_modify.html | 90 ++++++++++++++++++++++++++++++------------ doc/atom_modify.txt | 88 ++++++++++++++++++++++++++++++----------- 4 files changed, 213 insertions(+), 123 deletions(-) diff --git a/doc/Section_start.html b/doc/Section_start.html index e4f42bccac..239b7f7e8f 100644 --- a/doc/Section_start.html +++ b/doc/Section_start.html @@ -233,16 +233,16 @@ files for doing particle dumps in XTC format. This is only necessary if your platform does have its own XDR files available. See the Restrictions section of the dump command for details.

-

Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, --D-DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. -These settings refer to use of 4-byte (small) vs 8-byte (big) integers +

Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, -D- +DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These +settings refer to use of 4-byte (small) vs 8-byte (big) integers within LAMMPS, as specified in src/lmptype.h. The only reason to use the BIGBIG setting is to enable simulation of huge molecular systems -with more than 2 billion atoms or to allow moving atoms to wrap back -through a periodic box more than 512 times. The only reason to use -the SMALLSMALL setting is if your machine does not support 64-bit -integers. See the Additional build tips section below -for more details. +(which store bond topology info) with more than 2 billion atoms, or to +track the image flags of moving atoms that wrap around a periodic box +more than 512 times. The only reason to use the SMALLSMALL setting is +if your machine does not support 64-bit integers. See the Additional +build tips section below for more details.

The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or MPI version does not recognize "long long" data types. In this case a @@ -464,42 +464,47 @@ particular machine. LMP_INC line in your low-level src/MAKE/Makefile.foo.

The default is -DLAMMPS_SMALLBIG which allows for systems with up to -2^63 atoms and timesteps (about 9 billion billion). The atom limit is -for atomic systems that do not require atom IDs. For molecular -models, which require atom IDs, the limit is 2^31 atoms (about 2 -billion). With this setting, image flags are stored in 32-bit -integers, which means for 3 dimensions that atoms can only wrap around -a periodic box at most 512 times. If atoms move through the periodic -box more than this limit, the image flags will "roll over", e.g. from -511 to -512, which can cause diagnostics like the mean-squared -displacement, as calculated by the compute msd -command, to be faulty. +2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for +atomic systems which do not store bond topology info and thus do not +require atom IDs. If you use atom IDs for atomic systems (which is +the default) or if you use a molecular model, which stores bond +topology info and thus requires atom IDs, the limit is 2^31 atoms +(about 2 billion). This is because the IDs are stored in 32-bit +integers.

-

To allow for larger molecular systems or larger image flags, compile -with -DLAMMPS_BIGBIG. This enables molecular systems with up to 2^63 -atoms (about 9 billion billion). And image flags will not "roll over" -until they reach 2^20 = 1048576. +

Likewise, with this setting, the 3 image flags for each atom (see the +dump doc page for a discussion) are stored in a 32-bit +integer, which means the atoms can only wrap around a periodic box (in +each dimension) at most 512 times. If atoms move through the periodic +box more than this many times, the image flags will "roll over", +e.g. from 511 to -512, which can cause diagnostics like the +mean-squared displacement, as calculated by the compute +msd command, to be faulty.

-

IMPORTANT NOTE: As of 6/2012, the BIGBIG setting does not yet enable -molecular systems to grow as large as 2^63. Only the image flag roll -over is currently affected by this compile option. +

To allow for larger atomic systems with atom IDs or larger molecular +systems or larger image flags, compile with -DLAMMPS_BIGBIG. This +stores atom IDs and image flags in 64-bit integers. This enables +atomic or molecular systems with atom IDS of up to 2^63 atoms (about +9e18). And image flags will not "roll over" until they reach 2^20 = +1048576.

If your system does not support 8-byte integers, you will need to -compile with the -DLAMMPS_SMALLSMALL setting. This will restrict your -total number of atoms (for atomic or molecular models) and timesteps +compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the +total number of atoms (for atomic or molecular systems) and timesteps to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512.

-

Note that in src/lmptype.h there are also settings for the MPI data -types associated with the integers that store atom IDs and total -system sizes. These need to be consistent with the associated C data -types, or else LAMMPS will generate a run-time error. +

Note that in src/lmptype.h there are definitions of all these data +types as well as the MPI data types associated with them. The MPI +types need to be consistent with the associated C data types, or else +LAMMPS will generate a run-time error. As far as we know, the +settings defined in src/lmptype.h are portable and work on every +current system.

-

In all cases, the size of problem that can be run on a per-processor -basis is limited by 4-byte integer storage to 2^31 atoms per processor -(about 2 billion). This should not normally be a restriction since -such a problem would have a huge per-processor memory footprint due to -neighbor lists and would run very slowly in terms of CPU -secs/timestep. +

In all cases, the size of problem that can be run on a per-processor +basis is limited by 4-byte integer storage to 2^31 atoms per processor +(about 2 billion). This should not normally be a limitation since such +a problem would have a huge per-processor memory footprint due to +neighbor lists and would run very slowly in terms of CPU secs/timestep.

diff --git a/doc/Section_start.txt b/doc/Section_start.txt index b11648ffe3..ca0c8061c1 100644 --- a/doc/Section_start.txt +++ b/doc/Section_start.txt @@ -227,16 +227,16 @@ files for doing particle dumps in XTC format. This is only necessary if your platform does have its own XDR files available. See the Restrictions section of the "dump"_dump.html command for details. -Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, --D-DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. -These settings refer to use of 4-byte (small) vs 8-byte (big) integers +Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, -D- +DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These +settings refer to use of 4-byte (small) vs 8-byte (big) integers within LAMMPS, as specified in src/lmptype.h. The only reason to use the BIGBIG setting is to enable simulation of huge molecular systems -with more than 2 billion atoms or to allow moving atoms to wrap back -through a periodic box more than 512 times. The only reason to use -the SMALLSMALL setting is if your machine does not support 64-bit -integers. See the "Additional build tips"_#start_2_4 section below -for more details. +(which store bond topology info) with more than 2 billion atoms, or to +track the image flags of moving atoms that wrap around a periodic box +more than 512 times. The only reason to use the SMALLSMALL setting is +if your machine does not support 64-bit integers. See the "Additional +build tips"_#start_2_4 section below for more details. The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or MPI version does not recognize "long long" data types. In this case a @@ -458,42 +458,47 @@ As explained above, any of these 3 settings can be specified on the LMP_INC line in your low-level src/MAKE/Makefile.foo. The default is -DLAMMPS_SMALLBIG which allows for systems with up to -2^63 atoms and timesteps (about 9 billion billion). The atom limit is -for atomic systems that do not require atom IDs. For molecular -models, which require atom IDs, the limit is 2^31 atoms (about 2 -billion). With this setting, image flags are stored in 32-bit -integers, which means for 3 dimensions that atoms can only wrap around -a periodic box at most 512 times. If atoms move through the periodic -box more than this limit, the image flags will "roll over", e.g. from -511 to -512, which can cause diagnostics like the mean-squared -displacement, as calculated by the "compute msd"_compute_msd.html -command, to be faulty. +2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for +atomic systems which do not store bond topology info and thus do not +require atom IDs. If you use atom IDs for atomic systems (which is +the default) or if you use a molecular model, which stores bond +topology info and thus requires atom IDs, the limit is 2^31 atoms +(about 2 billion). This is because the IDs are stored in 32-bit +integers. -To allow for larger molecular systems or larger image flags, compile -with -DLAMMPS_BIGBIG. This enables molecular systems with up to 2^63 -atoms (about 9 billion billion). And image flags will not "roll over" -until they reach 2^20 = 1048576. +Likewise, with this setting, the 3 image flags for each atom (see the +"dump"_dump.html doc page for a discussion) are stored in a 32-bit +integer, which means the atoms can only wrap around a periodic box (in +each dimension) at most 512 times. If atoms move through the periodic +box more than this many times, the image flags will "roll over", +e.g. from 511 to -512, which can cause diagnostics like the +mean-squared displacement, as calculated by the "compute +msd"_compute_msd.html command, to be faulty. -IMPORTANT NOTE: As of 6/2012, the BIGBIG setting does not yet enable -molecular systems to grow as large as 2^63. Only the image flag roll -over is currently affected by this compile option. +To allow for larger atomic systems with atom IDs or larger molecular +systems or larger image flags, compile with -DLAMMPS_BIGBIG. This +stores atom IDs and image flags in 64-bit integers. This enables +atomic or molecular systems with atom IDS of up to 2^63 atoms (about +9e18). And image flags will not "roll over" until they reach 2^20 = +1048576. If your system does not support 8-byte integers, you will need to -compile with the -DLAMMPS_SMALLSMALL setting. This will restrict your -total number of atoms (for atomic or molecular models) and timesteps +compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the +total number of atoms (for atomic or molecular systems) and timesteps to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512. -Note that in src/lmptype.h there are also settings for the MPI data -types associated with the integers that store atom IDs and total -system sizes. These need to be consistent with the associated C data -types, or else LAMMPS will generate a run-time error. +Note that in src/lmptype.h there are definitions of all these data +types as well as the MPI data types associated with them. The MPI +types need to be consistent with the associated C data types, or else +LAMMPS will generate a run-time error. As far as we know, the +settings defined in src/lmptype.h are portable and work on every +current system. -In all cases, the size of problem that can be run on a per-processor -basis is limited by 4-byte integer storage to 2^31 atoms per processor -(about 2 billion). This should not normally be a restriction since -such a problem would have a huge per-processor memory footprint due to -neighbor lists and would run very slowly in terms of CPU -secs/timestep. +In all cases, the size of problem that can be run on a per-processor +basis is limited by 4-byte integer storage to 2^31 atoms per processor +(about 2 billion). This should not normally be a limitation since such +a problem would have a huge per-processor memory footprint due to +neighbor lists and would run very slowly in terms of CPU secs/timestep. :line diff --git a/doc/atom_modify.html b/doc/atom_modify.html index 2eaa729fbe..58bdda6574 100644 --- a/doc/atom_modify.html +++ b/doc/atom_modify.html @@ -1,5 +1,6 @@ -
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands +
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS +Commands
@@ -17,13 +18,15 @@ @@ -35,19 +38,58 @@ atom_modify first colloid

Description:

-

Modify properties of the atom style selected within LAMMPS. +

Modify certain attributes of atoms defined and stored within LAMMPS, +in addition to what is specified by the atom_style +command. The id and map keywords must be specified before a +simulation box is defined; other keywords can be specified any time. +

+

The id keyword determines whether non-zero atom IDs can be assigned +to each atom. If the value is yes, which is the default, IDs are +assigned, whether you use the create atoms or +read_data or read_restart +commands to initialize atoms. If atom IDs are used, they must all be +positive integers. They should also be unique, though LAMMPS does not +check for this. Typically they should also be consecutively numbered +(from 1 to Natoms), though this is not required. Molecular atom +styles are those that store bond topology information +(styles bond, angle, molecular, full). These styles require atom IDs +since the IDs are used to encode the topology. Some other LAMMPS +commands also require the use of atom IDs. E.g. some many-body pair +styles use them to avoid double computation of the I-J interaction +between two atoms. +

+

The only reason not to use atom IDs is if you are running an atomic +simulation so large that IDs cannot be uniquely assigned. For a +default LAMMPS build this limit is 2^31 or ~2 billion atoms. However, +even in this case, you can use 64-bit atom IDs, allowing 2^63 or ~9e18 +atoms, if you build LAMMPS with the - DLAMMPS_BIGBIG switch. This is +described in Section 2.2 of the manual. +If atom IDs are not used, they must be specified as 0 for all atoms, +e.g. in a data or restart file.

The map keyword determines how atom ID lookup is done for molecular -problems. Lookups are performed by bond (angle, etc) routines in +atom styles. Lookups are performed by bond (angle, etc) routines in LAMMPS to find the local atom index associated with a global atom ID. -When the array value is used, each processor stores a lookup table -of length N, where N is the total # of atoms in the system. This is -the fastest method for most simulations, but a processor can run out -of memory to store the table for very large simulations. The hash -value uses a hash table to perform the lookups. This method can be -slightly slower than the array method, but its memory cost is -proportional to N/P on each processor, where P is the total number of -processors running the simulation. +

+

When the array value is used, each processor stores a lookup table +of length N, where N is the largest atom ID in the system. This is a +fast, simple method for many simulations, but requires too much memory +for large simulations. The hash value uses a hash table to perform +the lookups. This can be slightly slower than the array method, but +its memory cost is proportional to the number of atoms owned by a +processor, i.e. N/P when N is the total number of atoms in the system +and P is the number of processors. +

+

When this setting is not specified in your input script, LAMMPS +creates a map, if one is needed, as an array or hash. See the +discussion of default values below for how LAMMPS chooses which kind +of map to build. Note that atomic systems do not normally need to +create a map. However, even in this case some LAMMPS commands will +create a map to find atoms (and then destroy it), or require a +permanent map. An example of the former is the velocity loop +all command, which uses a map when looping over all +atoms and insuring the same velocity values are assigned to an atom +ID, no matter which processor owns it.

The first keyword allows a group to be specified whose atoms will be maintained as the first atoms in each processor's list @@ -111,10 +153,6 @@ if sorting is enabled.

Restrictions:

-

The map keyword can only be used before the simulation box is defined -by a read_data or create_box -command. -

The first and sort options cannot be used together. Since sorting is on by default, it will be turned off if the first keyword is used with a group-ID that is not "all". @@ -123,10 +161,12 @@ used with a group-ID that is not "all".

Default:

-

By default, atomic (non-molecular) problems do not allocate maps. For -molecular problems, the option default is map = array. By default, a -"first" group is not defined. By default, sorting is enabled with a -frequency of 1000 and a binsize of 0.0, which means the neighbor +

By default, id is yes. By default, atomic systems (no bond topology +info) do not use a map. For molecular systems (with bond topology +info), a map is used. The default map style is array if no atom ID is +larger than 1 million, otherwise the default is hash. By default, a +"first" group is not defined. By default, sorting is enabled with a +frequency of 1000 and a binsize of 0.0, which means the neighbor cutoff will be used to set the bin size.

diff --git a/doc/atom_modify.txt b/doc/atom_modify.txt index b3992bb419..c7d7e68e16 100644 --- a/doc/atom_modify.txt +++ b/doc/atom_modify.txt @@ -1,4 +1,5 @@ -"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c +"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS +Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) @@ -13,12 +14,14 @@ atom_modify command :h3 atom_modify keyword values ... :pre one or more keyword/value pairs may be appended :ulb,l -keyword = {map} or {first} or {sort} :l - {map} value = {array} or {hash} - {first} value = group-ID = group whose atoms will appear first in internal atom lists - {sort} values = Nfreq binsize - Nfreq = sort atoms spatially every this many time steps - binsize = bin size for spatial sorting (distance units) :pre +keyword = {id} or {map} or {first} or {sort} :l + {id} value = {yes} or {no} + {map} value = {array} or {hash} + {first} value = group-ID = group whose atoms will appear first in +internal atom lists + {sort} values = Nfreq binsize + Nfreq = sort atoms spatially every this many time steps + binsize = bin size for spatial sorting (distance units) :pre :ule [Examples:] @@ -29,19 +32,58 @@ atom_modify first colloid :pre [Description:] -Modify properties of the atom style selected within LAMMPS. +Modify certain attributes of atoms defined and stored within LAMMPS, +in addition to what is specified by the "atom_style"_atom_style.html +command. The {id} and {map} keywords must be specified before a +simulation box is defined; other keywords can be specified any time. + +The {id} keyword determines whether non-zero atom IDs can be assigned +to each atom. If the value is {yes}, which is the default, IDs are +assigned, whether you use the "create atoms"_create_atoms.html or +"read_data"_read_data.html or "read_restart"_read_restart.html +commands to initialize atoms. If atom IDs are used, they must all be +positive integers. They should also be unique, though LAMMPS does not +check for this. Typically they should also be consecutively numbered +(from 1 to Natoms), though this is not required. Molecular "atom +styles"_atom_style.html are those that store bond topology information +(styles bond, angle, molecular, full). These styles require atom IDs +since the IDs are used to encode the topology. Some other LAMMPS +commands also require the use of atom IDs. E.g. some many-body pair +styles use them to avoid double computation of the I-J interaction +between two atoms. + +The only reason not to use atom IDs is if you are running an atomic +simulation so large that IDs cannot be uniquely assigned. For a +default LAMMPS build this limit is 2^31 or ~2 billion atoms. However, +even in this case, you can use 64-bit atom IDs, allowing 2^63 or ~9e18 +atoms, if you build LAMMPS with the - DLAMMPS_BIGBIG switch. This is +described in "Section 2.2"_Section_start.html#start_2 of the manual. +If atom IDs are not used, they must be specified as 0 for all atoms, +e.g. in a data or restart file. The {map} keyword determines how atom ID lookup is done for molecular -problems. Lookups are performed by bond (angle, etc) routines in +atom styles. Lookups are performed by bond (angle, etc) routines in LAMMPS to find the local atom index associated with a global atom ID. + When the {array} value is used, each processor stores a lookup table -of length N, where N is the total # of atoms in the system. This is -the fastest method for most simulations, but a processor can run out -of memory to store the table for very large simulations. The {hash} -value uses a hash table to perform the lookups. This method can be -slightly slower than the {array} method, but its memory cost is -proportional to N/P on each processor, where P is the total number of -processors running the simulation. +of length N, where N is the largest atom ID in the system. This is a +fast, simple method for many simulations, but requires too much memory +for large simulations. The {hash} value uses a hash table to perform +the lookups. This can be slightly slower than the {array} method, but +its memory cost is proportional to the number of atoms owned by a +processor, i.e. N/P when N is the total number of atoms in the system +and P is the number of processors. + +When this setting is not specified in your input script, LAMMPS +creates a map, if one is needed, as an array or hash. See the +discussion of default values below for how LAMMPS chooses which kind +of map to build. Note that atomic systems do not normally need to +create a map. However, even in this case some LAMMPS commands will +create a map to find atoms (and then destroy it), or require a +permanent map. An example of the former is the "velocity loop +all"_velocity.html command, which uses a map when looping over all +atoms and insuring the same velocity values are assigned to an atom +ID, no matter which processor owns it. The {first} keyword allows a "group"_group.html to be specified whose atoms will be maintained as the first atoms in each processor's list @@ -105,10 +147,6 @@ if sorting is enabled. [Restrictions:] -The map keyword can only be used before the simulation box is defined -by a "read_data"_read_data.html or "create_box"_create_box.html -command. - The {first} and {sort} options cannot be used together. Since sorting is on by default, it will be turned off if the {first} keyword is used with a group-ID that is not "all". @@ -117,10 +155,12 @@ used with a group-ID that is not "all". [Default:] -By default, atomic (non-molecular) problems do not allocate maps. For -molecular problems, the option default is map = array. By default, a -"first" group is not defined. By default, sorting is enabled with a -frequency of 1000 and a binsize of 0.0, which means the neighbor +By default, {id} is yes. By default, atomic systems (no bond topology +info) do not use a map. For molecular systems (with bond topology +info), a map is used. The default map style is array if no atom ID is +larger than 1 million, otherwise the default is hash. By default, a +"first" group is not defined. By default, sorting is enabled with a +frequency of 1000 and a binsize of 0.0, which means the neighbor cutoff will be used to set the bin size. :line