From 936e136b9db85498c5721ea454a40f920ee9163e Mon Sep 17 00:00:00 2001 From: sjplimp Date: Thu, 16 Jul 2015 23:37:03 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@13628 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/molecule.html | 27 ++++++++------ doc/molecule.txt | 27 ++++++++------ doc/read_data.html | 91 ++++++++++++++++++++++++++++++++++++++++++++- doc/read_data.txt | 92 ++++++++++++++++++++++++++++++++++++++++++++-- 4 files changed, 210 insertions(+), 27 deletions(-) diff --git a/doc/molecule.html b/doc/molecule.html index 3b312fbc5a..f1e201859f 100644 --- a/doc/molecule.html +++ b/doc/molecule.html @@ -24,12 +24,13 @@
  • keyword = offset or auto 
      offset values = toff boff aoff doff ioff
-    toff = offset to add to atom type
-    boff = offset to add to bond type
-    aoff = offset to add to angle type
-    doff = offset to add to dihedral type
-    ioff = offset to add to improper type
-  auto value = none = generate special bond lists automatically 
+    toff = offset to add to atom types
+    boff = offset to add to bond types
+    aoff = offset to add to angle types
+    doff = offset to add to dihedral types
+    ioff = offset to add to improper types
+  auto value = none
+    generate special bond lists automatically if auto is specified
    @@ -65,15 +66,15 @@ contains multiple molecules. The atom_style template command allows multiple-molecule templates to define a system with more than one templated molecule.

    -

    The optional offset keyword will add the specified offset values to -the atom types, bond types, angle types, dihedral types, and improper +

    The optional offset keyword adds the specified offset values to the +atom types, bond types, angle types, dihedral types, and improper types as they are read from the molecule file. E.g. if toff = 2, and the file uses atom types 1,2,3, then each created molecule will have atom types 3,4,5. This makes it easy to use the same molecule template file in different simulations. Note that the same offsets are applied to the molecules in all specified files. All five offset -values are required, but individual values will be ignored if the -molecule template does not define that attribute. +values must be speicified, but individual values will be ignored if +the molecule template does not use that attribute (e.g. no bonds).

    The optional auto keyword can be used for molecules with bonds instead of listing neighbors within the molecular topology explicitly. @@ -450,6 +451,10 @@ of SHAKE clusters.

    fix deposit, fix pour, fix_gcmc

    -

    Default: none +

    Default: +

    +

    The default keyword values are offset 0 0 0 0 0, and no +auto-generation of special bond lists. The latter is overridden in +the auto keyword is used.

    diff --git a/doc/molecule.txt b/doc/molecule.txt index cff68cb9db..1504e896f4 100644 --- a/doc/molecule.txt +++ b/doc/molecule.txt @@ -17,12 +17,13 @@ file1,file2,... = names of files containing molecule descriptions :l zero or more keyword/value pairs may be appended :l keyword = {offset} or {auto} :l {offset} values = toff boff aoff doff ioff - toff = offset to add to atom type - boff = offset to add to bond type - aoff = offset to add to angle type - doff = offset to add to dihedral type - ioff = offset to add to improper type - {auto} value = none = generate special bond lists automatically :pre + toff = offset to add to atom types + boff = offset to add to bond types + aoff = offset to add to angle types + doff = offset to add to dihedral types + ioff = offset to add to improper types + {auto} value = none + generate special bond lists automatically if {auto} is specified :pre :ule [Examples:] @@ -57,15 +58,15 @@ contains multiple molecules. The "atom_style template"_atom_style.html command allows multiple-molecule templates to define a system with more than one templated molecule. -The optional {offset} keyword will add the specified offset values to -the atom types, bond types, angle types, dihedral types, and improper +The optional {offset} keyword adds the specified offset values to the +atom types, bond types, angle types, dihedral types, and improper types as they are read from the molecule file. E.g. if {toff} = 2, and the file uses atom types 1,2,3, then each created molecule will have atom types 3,4,5. This makes it easy to use the same molecule template file in different simulations. Note that the same offsets are applied to the molecules in all specified files. All five offset -values are required, but individual values will be ignored if the -molecule template does not define that attribute. +values must be speicified, but individual values will be ignored if +the molecule template does not use that attribute (e.g. no bonds). The optional {auto} keyword can be used for molecules with bonds instead of listing neighbors within the molecular topology explicitly. @@ -442,4 +443,8 @@ of SHAKE clusters. "fix deposit"_fix_deposit.html, "fix pour"_fix_pour.html, "fix_gcmc"_fix_gcmc.html -[Default:] none +[Default:] + +The default keyword values are offset 0 0 0 0 0, and no +auto-generation of special bond lists. The latter is overridden in +the {auto} keyword is used. diff --git a/doc/read_data.html b/doc/read_data.html index 072c396b30..4f627238f6 100644 --- a/doc/read_data.html +++ b/doc/read_data.html @@ -19,9 +19,23 @@
  • zero or more keyword/arg pairs may be appended -
  • keyword = fix +
  • keyword = add or offset or shift or group or fix -
      fix args = fix-ID header-string section-string
+
      add arg = append or Nstart or merge
+    append = add new atoms with IDs appended to current IDs
+    Nstart = add new atoms with IDs starting with Nstart
+    merge = add new atoms with their IDs, assumed to not conflict with atoms that already exist
+  offset args = toff boff aoff doff ioff
+    toff = offset to add to atom types
+    boff = offset to add to bond types
+    aoff = offset to add to angle types
+    doff = offset to add to dihedral types
+    ioff = offset to add to improper types
+  shift args = Sx Sy Sz
+    Sx,Sy,Sz = distance to shift atoms when adding to system (distance units)
+  group args = groupID
+    groupID = add atoms in data file to this group
+  fix args = fix-ID header-string section-string
     fix-ID = ID of fix to process header lines and sections of data file
     header-string = header lines containing this string will be passed to fix
     section-string = section names with this string will be passed to fix 
@@ -33,6 +47,8 @@
 
    read_data data.lj
 read_data ../run7/data.polymer.gz
 read_data data.protein fix mycmap crossterm CMAP 
+read_data data.water add append offset 3 1 1 1 1 shift 0.0 0.0 50.0
+read_data data.water add merge 1 group solvent 
 
    
 
    Description:
 
    
@@ -45,6 +61,77 @@ Also see the explanation of the -restart
 switch which can convert a restart file to
 a data file.
 
    
+
    This command can also be used to add new atoms and their properties to
+an existing system by using the add keyword.  If a simulation box
+does not yet exist, the add keyword cannot be used; the box size is
+defined in the data file.  If a simulation box does exist, due to
+using the create_box command, or a previous
+read_data command, then the add keyword must be used.  The box
+information in the new data file will be ignored.
+
    
+
    The three choices for the add argument affect how the IDs of atoms
+in the data file are treated.  If append is specified, atoms in the
+data file are added to the current system, with their atom IDs reset
+so that an atomID = M in the data file becomes atomID = N+M, where N
+is the largest atom ID in the current system.  This rule is applied to
+all occurrences of atom IDs in the data file, e.g. in the Velocity or
+Bonds section.  If Nstart is specified, then a numeric value is
+given, e.g. 1000, so that atomID in the data file becomes atomID =
+1000+M.  If merge is specified, the data file atoms are added to the
+current system without changing their IDs.  They are assumed to merge
+(without conflict) with the currently defined atoms.  It is up to you
+to insure there are no multiply defined atom IDs, as LAMMPS cannot
+easily check that this is the case.
+
    
+
    The offset and shift keywords can only be used if
+the add keyword is also used.
+
    
+
    The offset keyword adds the specified offset values to the atom
+types, bond types, angle types, dihedral types, and improper types as
+they are read from the data file.  E.g. if toff = 2, and the file
+uses atom types 1,2,3, then the added atoms will have atom types
+3,4,5.  These offsets apply to all occurrences of types in the data
+file, e.g. for the Atoms or Masses or Pair Coeffs or Bond Coeffs
+sections.  This makes it easy to use atoms and molecules and their
+attributes from a data file in different simulations.  All five offset
+values must be specified, but individual values will be ignored if the
+data file does not use that attribute (e.g. no bonds).
+
    
+
    The shift keyword can be used to specify a displacement applied to
+the coordinates of each atom.  This is a mechanism for adding
+structured collections of atoms at different locations within the
+simulation box, to build up a complex geometry.  It is up to you to
+insure atoms do not overlap unphysically which would lead to bad
+dynamics.  The delete_atoms command can be used to
+remove overlapping atoms.
+
    
+
    The group keyword adds all the atoms in the data file to the
+specified group-ID.  The group will be created if it does not already
+exist.  This is useful if you wish to change the coordinates of a
+particular set of atoms in a more complex way than can be done via the
+shift keyword, after using the read_data command multiple times.
+E.g. a group of atoms can be diplaced via the
+displate_atoms command, which includes options
+for rotation or rescaling.
+
    
+
    The use of the fix keyword is discussed below.
+
    
+
    IMPORTANT NOTE: You cannot use the append keyword if a previously
+read-in data file defined any per-type quantities, e.g. via Masses or
+Pair Coeffs or Bond Coeffs sections.  This is because those
+definitions trigger the allocation of arrays with length = # of
+currently defined types, and they cannot be reallocated.  There are
+two solutions to this issue.  The first is to define the per-type
+quantities in the input script, after all data files are read,
+e.g. via the mass or pair_coeff command.
+The second is to use the create_box command to create the
+simulation box and use its various options to define the total number
+of types of all kinds (atom, bond, etc).  Then use the merge keyword
+to read as many data files as needed, with Masses, Pair Coeffs, etc
+sections that are indexed with appropriate types.
+
    
+
    
+
 
    The structure of the data file is important, though many settings and
 sections are optional or can come in any order.  See the examples
 directory for sample data files for different problems.
diff --git a/doc/read_data.txt b/doc/read_data.txt
index ab37632215..14c4ec6733 100644
--- a/doc/read_data.txt
+++ b/doc/read_data.txt
@@ -14,19 +14,34 @@ read_data file keyword args ... :pre
 
 file = name of data file to read in :ulb,l
 zero or more keyword/arg pairs may be appended :l
-keyword = {fix} :l
+keyword = {add} or {offset} or {shift} or {group} or {fix} :l
+  {add} arg = {append} or {Nstart} or {merge}
+    append = add new atoms with IDs appended to current IDs
+    Nstart = add new atoms with IDs starting with Nstart
+    merge = add new atoms with their IDs, assumed to not conflict with atoms that already exist
+  {offset} args = toff boff aoff doff ioff
+    toff = offset to add to atom types
+    boff = offset to add to bond types
+    aoff = offset to add to angle types
+    doff = offset to add to dihedral types
+    ioff = offset to add to improper types
+  {shift} args = Sx Sy Sz
+    Sx,Sy,Sz = distance to shift atoms when adding to system (distance units)
+  {group} args = groupID
+    groupID = add atoms in data file to this group
   {fix} args = fix-ID header-string section-string
     fix-ID = ID of fix to process header lines and sections of data file
     header-string = header lines containing this string will be passed to fix
     section-string = section names with this string will be passed to fix :pre
 :ule
 
-
 [Examples:]
 
 read_data data.lj
 read_data ../run7/data.polymer.gz
-read_data data.protein fix mycmap crossterm CMAP :pre
+read_data data.protein fix mycmap crossterm CMAP 
+read_data data.water add append offset 3 1 1 1 1 shift 0.0 0.0 50.0
+read_data data.water add merge 1 group solvent :pre
 
 [Description:]
 
@@ -39,6 +54,77 @@ Also see the explanation of the "-restart command-line
 switch"_Section_start.html#start_7 which can convert a restart file to
 a data file.
 
+This command can also be used to add new atoms and their properties to
+an existing system by using the {add} keyword.  If a simulation box
+does not yet exist, the {add} keyword cannot be used; the box size is
+defined in the data file.  If a simulation box does exist, due to
+using the "create_box"_create_box.html command, or a previous
+read_data command, then the {add} keyword must be used.  The box
+information in the new data file will be ignored.
+
+The three choices for the {add} argument affect how the IDs of atoms
+in the data file are treated.  If {append} is specified, atoms in the
+data file are added to the current system, with their atom IDs reset
+so that an atomID = M in the data file becomes atomID = N+M, where N
+is the largest atom ID in the current system.  This rule is applied to
+all occurrences of atom IDs in the data file, e.g. in the Velocity or
+Bonds section.  If {Nstart} is specified, then a numeric value is
+given, e.g. 1000, so that atomID in the data file becomes atomID =
+1000+M.  If {merge} is specified, the data file atoms are added to the
+current system without changing their IDs.  They are assumed to merge
+(without conflict) with the currently defined atoms.  It is up to you
+to insure there are no multiply defined atom IDs, as LAMMPS cannot
+easily check that this is the case.
+
+The {offset} and {shift} keywords can only be used if
+the {add} keyword is also used.
+
+The {offset} keyword adds the specified offset values to the atom
+types, bond types, angle types, dihedral types, and improper types as
+they are read from the data file.  E.g. if {toff} = 2, and the file
+uses atom types 1,2,3, then the added atoms will have atom types
+3,4,5.  These offsets apply to all occurrences of types in the data
+file, e.g. for the Atoms or Masses or Pair Coeffs or Bond Coeffs
+sections.  This makes it easy to use atoms and molecules and their
+attributes from a data file in different simulations.  All five offset
+values must be specified, but individual values will be ignored if the
+data file does not use that attribute (e.g. no bonds).
+
+The {shift} keyword can be used to specify a displacement applied to
+the coordinates of each atom.  This is a mechanism for adding
+structured collections of atoms at different locations within the
+simulation box, to build up a complex geometry.  It is up to you to
+insure atoms do not overlap unphysically which would lead to bad
+dynamics.  The "delete_atoms"_delete_atoms.html command can be used to
+remove overlapping atoms.
+
+The {group} keyword adds all the atoms in the data file to the
+specified group-ID.  The group will be created if it does not already
+exist.  This is useful if you wish to change the coordinates of a
+particular set of atoms in a more complex way than can be done via the
+{shift} keyword, after using the read_data command multiple times.
+E.g. a group of atoms can be diplaced via the
+"displate_atoms"_displace_atoms.html command, which includes options
+for rotation or rescaling.
+
+The use of the {fix} keyword is discussed below.
+
+IMPORTANT NOTE: You cannot use the {append} keyword if a previously
+read-in data file defined any per-type quantities, e.g. via Masses or
+Pair Coeffs or Bond Coeffs sections.  This is because those
+definitions trigger the allocation of arrays with length = # of
+currently defined types, and they cannot be reallocated.  There are
+two solutions to this issue.  The first is to define the per-type
+quantities in the input script, after all data files are read,
+e.g. via the "mass"_mass.html or "pair_coeff"_pair_coeff.html command.
+The second is to use the "create_box"_create_box command to create the
+simulation box and use its various options to define the total number
+of types of all kinds (atom, bond, etc).  Then use the {merge} keyword
+to read as many data files as needed, with Masses, Pair Coeffs, etc
+sections that are indexed with appropriate types.
+
+:line
+
 The structure of the data file is important, though many settings and
 sections are optional or can come in any order.  See the examples
 directory for sample data files for different problems.