1.. index:: molecule 2 3molecule command 4================ 5 6Syntax 7"""""" 8 9.. parsed-literal:: 10 11 molecule ID file1 keyword values ... file2 keyword values ... fileN ... 12 13* ID = user-assigned name for the molecule template 14* file1,file2,... = names of files containing molecule descriptions 15* zero or more keyword/value pairs may be appended after each file 16* keyword = *offset* or *toff* or *boff* or *aoff* or *doff* or *ioff* or *scale* 17 18 .. parsed-literal:: 19 20 *offset* values = Toff Boff Aoff Doff Ioff 21 Toff = offset to add to atom types 22 Boff = offset to add to bond types 23 Aoff = offset to add to angle types 24 Doff = offset to add to dihedral types 25 Ioff = offset to add to improper types 26 *toff* value = Toff 27 Toff = offset to add to atom types 28 *boff* value = Boff 29 Boff = offset to add to bond types 30 *aoff* value = Aoff 31 Aoff = offset to add to angle types 32 *doff* value = Doff 33 Doff = offset to add to dihedral types 34 *ioff* value = Ioff 35 Ioff = offset to add to improper types 36 *scale* value = sfactor 37 sfactor = scale factor to apply to the size and mass of the molecule 38 39Examples 40"""""""" 41 42.. code-block:: LAMMPS 43 44 molecule 1 mymol.txt 45 molecule 1 co2.txt h2o.txt 46 molecule CO2 co2.txt boff 3 aoff 2 47 molecule 1 mymol.txt offset 6 9 18 23 14 48 molecule objects file.1 scale 1.5 file.1 scale 2.0 file.2 scale 1.3 49 50Description 51""""""""""" 52 53Define a molecule template that can be used as part of other LAMMPS 54commands, typically to define a collection of particles as a bonded 55molecule or a rigid body. Commands that currently use molecule 56templates include: 57 58* :doc:`fix deposit <fix_deposit>` 59* :doc:`fix pour <fix_pour>` 60* :doc:`fix rigid/small <fix_rigid>` 61* :doc:`fix shake <fix_shake>` 62* :doc:`fix gcmc <fix_gcmc>` 63* :doc:`fix bond/react <fix_bond_react>` 64* :doc:`create_atoms <create_atoms>` 65* :doc:`atom_style template <atom_style>` 66 67The ID of a molecule template can only contain alphanumeric characters 68and underscores. 69 70A single template can contain multiple molecules, listed one per file. 71Some of the commands listed above currently use only the first 72molecule in the template, and will issue a warning if the template 73contains multiple molecules. The :doc:`atom_style template <atom_style>` command allows multiple-molecule templates 74to define a system with more than one templated molecule. 75 76Each filename can be followed by optional keywords which are applied 77only to the molecule in the file as used in this template. This is to 78make it easy to use the same molecule file in different molecule 79templates or in different simulations. You can specify the same file 80multiple times with different optional keywords. 81 82The *offset*, *toff*, *boff*, *aoff*, *doff*, *ioff* keywords 83add the specified offset values to the atom types, bond types, angle 84types, dihedral types, and/or improper types as they are read from the 85molecule file. E.g. if *toff* = 2, and the file uses atom types 861,2,3, then each created molecule will have atom types 3,4,5. For the 87*offset* keyword, all five offset values must be specified, but 88individual values will be ignored if the molecule template does not 89use that attribute (e.g. no bonds). 90 91The *scale* keyword scales the size of the molecule. This can be 92useful for modeling polydisperse granular rigid bodies. The scale 93factor is applied to each of these properties in the molecule file, if 94they are defined: the individual particle coordinates (Coords 95section), the individual mass of each particle (Masses section), the 96individual diameters of each particle (Diameters section), the total 97mass of the molecule (header keyword = mass), the center-of-mass of 98the molecule (header keyword = com), and the moments of inertia of the 99molecule (header keyword = inertia). 100 101.. note:: 102 103 The molecule command can be used to define molecules with bonds, 104 angles, dihedrals, impropers, or special bond lists of neighbors 105 within a molecular topology, so that you can later add the molecules 106 to your simulation, via one or more of the commands listed above. 107 Since this topology-related information requires that suitable storage 108 is reserved when LAMMPS creates the simulation box (e.g. when using 109 the :doc:`create_box <create_box>` command or the 110 :doc:`read_data <read_data>` command) suitable space has to be reserved 111 so you do not overflow those pre-allocated data structures when adding 112 molecules later. Both the :doc:`create_box <create_box>` command and 113 the :doc:`read_data <read_data>` command have "extra" options which 114 insure space is allocated for storing topology info for molecules that 115 are added later. 116 117The format of an individual molecule file is similar but 118(not identical) to the data file read by the :doc:`read_data <read_data>` 119commands, and is as follows. 120 121A molecule file has a header and a body. The header appears first. 122The first line of the header is always skipped; it typically contains 123a description of the file. Then lines are read one at a time. Lines 124can have a trailing comment starting with '#' that is ignored. If the 125line is blank (only white-space after comment is deleted), it is 126skipped. If the line contains a header keyword, the corresponding 127value(s) is read from the line. If it does not contain a header 128keyword, the line begins the body of the file. 129 130The body of the file contains zero or more sections. The first line 131of a section has only a keyword. The next line is skipped. The 132remaining lines of the section contain values. The number of lines 133depends on the section keyword as described below. Zero or more blank 134lines can be used between sections. Sections can appear in any order, 135with a few exceptions as noted below. 136 137These are the recognized header keywords. Header lines can come in 138any order. The numeric value(s) are read from the beginning of the 139line. The keyword should appear at the end of the line. All these 140settings have default values, as explained below. A line need only 141appear if the value(s) are different than the default. 142 143* N *atoms* = # of atoms N in molecule, default = 0 144* Nb *bonds* = # of bonds Nb in molecule, default = 0 145* Na *angles* = # of angles Na in molecule, default = 0 146* Nd *dihedrals* = # of dihedrals Nd in molecule, default = 0 147* Ni *impropers* = # of impropers Ni in molecule, default = 0 148* Nf *fragments* = # of fragments in molecule, default = 0 149* Mtotal *mass* = total mass of molecule 150* Xc Yc Zc *com* = coordinates of center-of-mass of molecule 151* Ixx Iyy Izz Ixy Ixz Iyz *inertia* = 6 components of inertia tensor of molecule 152 153For *mass*, *com*, and *inertia*, the default is for LAMMPS to 154calculate this quantity itself if needed, assuming the molecules 155consists of a set of point particles or finite-size particles (with a 156non-zero diameter) that do not overlap. If finite-size particles in 157the molecule do overlap, LAMMPS will not account for the overlap 158effects when calculating any of these 3 quantities, so you should 159pre-compute them yourself and list the values in the file. 160 161The mass and center-of-mass coordinates (Xc,Yc,Zc) are 162self-explanatory. The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) 163should be the values consistent with the current orientation of the 164rigid body around its center of mass. The values are with respect to 165the simulation box XYZ axes, not with respect to the principal axes of 166the rigid body itself. LAMMPS performs the latter calculation 167internally. 168 169These are the allowed section keywords for the body of the file. 170 171* *Coords, Types, Molecules, Fragments, Charges, Diameters, Masses* = atom-property sections 172* *Bonds, Angles, Dihedrals, Impropers* = molecular topology sections 173* *Special Bond Counts, Special Bonds* = special neighbor info 174* *Shake Flags, Shake Atoms, Shake Bond Types* = SHAKE info 175 176If a Bonds section is specified then the Special Bond Counts and 177Special Bonds sections can also be used, if desired, to explicitly 178list the 1-2, 1-3, 1-4 neighbors within the molecule topology (see 179details below). This is optional since if these sections are not 180included, LAMMPS will auto-generate this information. Note that 181LAMMPS uses this info to properly exclude or weight bonded pairwise 182interactions between bonded atoms. See the 183:doc:`special_bonds <special_bonds>` command for more details. One 184reason to list the special bond info explicitly is for the 185:doc:`thermalized Drude oscillator model <Howto_drude>` which treats the 186bonds between nuclear cores and Drude electrons in a different manner. 187 188.. note:: 189 190 Whether a section is required depends on how the molecule 191 template is used by other LAMMPS commands. For example, to add a 192 molecule via the :doc:`fix deposit <fix_deposit>` command, the Coords 193 and Types sections are required. To add a rigid body via the :doc:`fix pour <fix_pour>` command, the Bonds (Angles, etc) sections are not 194 required, since the molecule will be treated as a rigid body. Some 195 sections are optional. For example, the :doc:`fix pour <fix_pour>` 196 command can be used to add "molecules" which are clusters of 197 finite-size granular particles. If the Diameters section is not 198 specified, each particle in the molecule will have a default diameter 199 of 1.0. See the doc pages for LAMMPS commands that use molecule 200 templates for more details. 201 202Each section is listed below in alphabetic order. The format of each 203section is described including the number of lines it must contain and 204rules (if any) for whether it can appear in the data file. For per- 205atom sections, entries should be numbered from 1 to Natoms (where 206Natoms is the number of atoms in the template), indicating which atom 207(or bond, etc) the entry applies to. Per-atom sections need to 208include a setting for every atom, but the atoms can be listed in any 209order. 210 211---------- 212 213*Coords* section: 214 215* one line per atom 216* line syntax: ID x y z 217* x,y,z = coordinate of atom 218 219---------- 220 221*Types* section: 222 223* one line per atom 224* line syntax: ID type 225* type = atom type of atom 226 227---------- 228 229*Molecules* section: 230 231* one line per atom 232* line syntax: ID molecule-ID 233* molecule-ID = molecule ID of atom 234 235---------- 236 237*Fragments* section: 238 239* one line per fragment 240* line syntax: ID a b c d ... 241* a,b,c,d,... = IDs of atoms in fragment 242 243The ID of a fragment can only contain alphanumeric characters and 244underscores. The atom IDs should be values from 1 to Natoms, where 245Natoms = # of atoms in the molecule. 246 247---------- 248 249*Charges* section: 250 251* one line per atom 252* line syntax: ID q 253* q = charge on atom 254 255This section is only allowed for :doc:`atom styles <atom_style>` that 256support charge. If this section is not included, the default charge 257on each atom in the molecule is 0.0. 258 259---------- 260 261*Diameters* section: 262 263* one line per atom 264* line syntax: ID diam 265* diam = diameter of atom 266 267This section is only allowed for :doc:`atom styles <atom_style>` that 268support finite-size spherical particles, e.g. atom_style sphere. If 269not listed, the default diameter of each atom in the molecule is 1.0. 270 271---------- 272 273*Masses* section: 274 275* one line per atom 276* line syntax: ID mass 277* mass = mass of atom 278 279This section is only allowed for :doc:`atom styles <atom_style>` that 280support per-atom mass, as opposed to per-type mass. See the 281:doc:`mass <mass>` command for details. If this section is not 282included, the default mass for each atom is derived from its volume 283(see Diameters section) and a default density of 1.0, in 284:doc:`units <units>` of mass/volume. 285 286---------- 287 288*Bonds* section: 289 290* one line per bond 291* line syntax: ID type atom1 atom2 292* type = bond type (1-Nbondtype) 293* atom1,atom2 = IDs of atoms in bond 294 295The IDs for the two atoms in each bond should be values 296from 1 to Natoms, where Natoms = # of atoms in the molecule. 297 298---------- 299 300*Angles* section: 301 302* one line per angle 303* line syntax: ID type atom1 atom2 atom3 304* type = angle type (1-Nangletype) 305* atom1,atom2,atom3 = IDs of atoms in angle 306 307The IDs for the three atoms in each angle should be values from 1 to 308Natoms, where Natoms = # of atoms in the molecule. The 3 atoms are 309ordered linearly within the angle. Thus the central atom (around 310which the angle is computed) is the atom2 in the list. 311 312---------- 313 314*Dihedrals* section: 315 316* one line per dihedral 317* line syntax: ID type atom1 atom2 atom3 atom4 318* type = dihedral type (1-Ndihedraltype) 319* atom1,atom2,atom3,atom4 = IDs of atoms in dihedral 320 321The IDs for the four atoms in each dihedral should be values from 1 to 322Natoms, where Natoms = # of atoms in the molecule. The 4 atoms are 323ordered linearly within the dihedral. 324 325---------- 326 327*Impropers* section: 328 329* one line per improper 330* line syntax: ID type atom1 atom2 atom3 atom4 331* type = improper type (1-Nimpropertype) 332* atom1,atom2,atom3,atom4 = IDs of atoms in improper 333 334The IDs for the four atoms in each improper should be values from 1 to 335Natoms, where Natoms = # of atoms in the molecule. The ordering of 336the 4 atoms determines the definition of the improper angle used in 337the formula for the defined :doc:`improper style <improper_style>`. See 338the doc pages for individual styles for details. 339 340---------- 341 342*Special Bond Counts* section: 343 344* one line per atom 345* line syntax: ID N1 N2 N3 346* N1 = # of 1-2 bonds 347* N2 = # of 1-3 bonds 348* N3 = # of 1-4 bonds 349 350N1, N2, N3 are the number of 1-2, 1-3, 1-4 neighbors respectively of 351this atom within the topology of the molecule. See the 352:doc:`special_bonds <special_bonds>` page for more discussion of 3531-2, 1-3, 1-4 neighbors. If this section appears, the Special Bonds 354section must also appear. 355 356As explained above, LAMMPS will auto-generate this information if this 357section is not specified. If specified, this section will 358override what would be auto-generated. 359 360---------- 361 362*Special Bonds* section: 363 364* one line per atom 365* line syntax: ID a b c d ... 366* a,b,c,d,... = IDs of atoms in N1+N2+N3 special bonds 367 368A, b, c, d, etc are the IDs of the n1+n2+n3 atoms that are 1-2, 1-3, 3691-4 neighbors of this atom. The IDs should be values from 1 to 370Natoms, where Natoms = # of atoms in the molecule. The first N1 371values should be the 1-2 neighbors, the next N2 should be the 1-3 372neighbors, the last N3 should be the 1-4 neighbors. No atom ID should 373appear more than once. See the :doc:`special_bonds <special_bonds>` doc 374page for more discussion of 1-2, 1-3, 1-4 neighbors. If this section 375appears, the Special Bond Counts section must also appear. 376 377As explained above, LAMMPS will auto-generate this information if this 378section is not specified. If specified, this section will override 379what would be auto-generated. 380 381---------- 382 383*Shake Flags* section: 384 385* one line per atom 386* line syntax: ID flag 387* flag = 0,1,2,3,4 388 389This section is only needed when molecules created using the template 390will be constrained by SHAKE via the "fix shake" command. The other 391two Shake sections must also appear in the file, following this one. 392 393The meaning of the flag for each atom is as follows. See the :doc:`fix shake <fix_shake>` page for a further description of SHAKE 394clusters. 395 396* 0 = not part of a SHAKE cluster 397* 1 = part of a SHAKE angle cluster (two bonds and the angle they form) 398* 2 = part of a 2-atom SHAKE cluster with a single bond 399* 3 = part of a 3-atom SHAKE cluster with two bonds 400* 4 = part of a 4-atom SHAKE cluster with three bonds 401 402---------- 403 404*Shake Atoms* section: 405 406* one line per atom 407* line syntax: ID a b c d 408* a,b,c,d = IDs of atoms in cluster 409 410This section is only needed when molecules created using the template 411will be constrained by SHAKE via the "fix shake" command. The other 412two Shake sections must also appear in the file. 413 414The a,b,c,d values are atom IDs (from 1 to Natoms) for all the atoms 415in the SHAKE cluster that this atom belongs to. The number of values 416that must appear is determined by the shake flag for the atom (see the 417Shake Flags section above). All atoms in a particular cluster should 418list their a,b,c,d values identically. 419 420If flag = 0, no a,b,c,d values are listed on the line, just the 421(ignored) ID. 422 423If flag = 1, a,b,c are listed, where a = ID of central atom in the 424angle, and b,c the other two atoms in the angle. 425 426If flag = 2, a,b are listed, where a = ID of atom in bond with the 427lowest ID, and b = ID of atom in bond with the highest ID. 428 429If flag = 3, a,b,c are listed, where a = ID of central atom, 430and b,c = IDs of other two atoms bonded to the central atom. 431 432If flag = 4, a,b,c,d are listed, where a = ID of central atom, 433and b,c,d = IDs of other three atoms bonded to the central atom. 434 435See the :doc:`fix shake <fix_shake>` page for a further description 436of SHAKE clusters. 437 438---------- 439 440*Shake Bond Types* section: 441 442* one line per atom 443* line syntax: ID a b c 444* a,b,c = bond types (or angle type) of bonds (or angle) in cluster 445 446This section is only needed when molecules created using the template 447will be constrained by SHAKE via the "fix shake" command. The other 448two Shake sections must also appear in the file. 449 450The a,b,c values are bond types (from 1 to Nbondtypes) for all bonds 451in the SHAKE cluster that this atom belongs to. The number of values 452that must appear is determined by the shake flag for the atom (see the 453Shake Flags section above). All atoms in a particular cluster should 454list their a,b,c values identically. 455 456If flag = 0, no a,b,c values are listed on the line, just the 457(ignored) ID. 458 459If flag = 1, a,b,c are listed, where a = bondtype of the bond between 460the central atom and the first non-central atom (value b in the Shake 461Atoms section), b = bondtype of the bond between the central atom and 462the second non-central atom (value c in the Shake Atoms section), and c = 463the angle type (1 to Nangletypes) of the angle between the 3 atoms. 464 465If flag = 2, only a is listed, where a = bondtype of the bond between 466the 2 atoms in the cluster. 467 468If flag = 3, a,b are listed, where a = bondtype of the bond between 469the central atom and the first non-central atom (value b in the Shake 470Atoms section), and b = bondtype of the bond between the central atom 471and the second non-central atom (value c in the Shake Atoms section). 472 473If flag = 4, a,b,c are listed, where a = bondtype of the bond between 474the central atom and the first non-central atom (value b in the Shake 475Atoms section), b = bondtype of the bond between the central atom and 476the second non-central atom (value c in the Shake Atoms section), and c = 477bondtype of the bond between the central atom and the third non-central 478atom (value d in the Shake Atoms section). 479 480See the :doc:`fix shake <fix_shake>` page for a further description 481of SHAKE clusters. 482 483---------- 484 485Restrictions 486"""""""""""" 487 488None 489 490Related commands 491"""""""""""""""" 492 493:doc:`fix deposit <fix_deposit>`, :doc:`fix pour <fix_pour>`, 494:doc:`fix gcmc <fix_gcmc>` 495 496Default 497""""""" 498 499The default keywords values are offset 0 0 0 0 0 and scale = 1.0. 500