diff --git a/doc/src/Section_howto.txt b/doc/src/Section_howto.txt index 33cbfa958..5e21f8eb8 100644 --- a/doc/src/Section_howto.txt +++ b/doc/src/Section_howto.txt @@ -1,2885 +1,2885 @@ "Previous Section"_Section_accelerate.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_example.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line 6. How-to discussions :h3 This section describes how to perform common tasks using LAMMPS. 6.1 "Restarting a simulation"_#howto_1 6.2 "2d simulations"_#howto_2 6.3 "CHARMM, AMBER, and DREIDING force fields"_#howto_3 6.4 "Running multiple simulations from one input script"_#howto_4 6.5 "Multi-replica simulations"_#howto_5 6.6 "Granular models"_#howto_6 6.7 "TIP3P water model"_#howto_7 6.8 "TIP4P water model"_#howto_8 6.9 "SPC water model"_#howto_9 6.10 "Coupling LAMMPS to other codes"_#howto_10 6.11 "Visualizing LAMMPS snapshots"_#howto_11 6.12 "Triclinic (non-orthogonal) simulation boxes"_#howto_12 6.13 "NEMD simulations"_#howto_13 6.14 "Finite-size spherical and aspherical particles"_#howto_14 6.15 "Output from LAMMPS (thermo, dumps, computes, fixes, variables)"_#howto_15 6.16 "Thermostatting, barostatting and computing temperature"_#howto_16 6.17 "Walls"_#howto_17 6.18 "Elastic constants"_#howto_18 6.19 "Library interface to LAMMPS"_#howto_19 6.20 "Calculating thermal conductivity"_#howto_20 6.21 "Calculating viscosity"_#howto_21 6.22 "Calculating a diffusion coefficient"_#howto_22 6.23 "Using chunks to calculate system properties"_#howto_23 6.24 "Setting parameters for the kspace_style pppm/disp command"_#howto_24 6.25 "Polarizable models"_#howto_25 6.26 "Adiabatic core/shell model"_#howto_26 6.27 "Drude induced dipoles"_#howto_27 :all(b) The example input scripts included in the LAMMPS distribution and highlighted in "Section 7"_Section_example.html also show how to setup and run various kinds of simulations. :line :line 6.1 Restarting a simulation :link(howto_1),h4 There are 3 ways to continue a long LAMMPS simulation. Multiple "run"_run.html commands can be used in the same input script. Each run will continue from where the previous run left off. Or binary restart files can be saved to disk using the "restart"_restart.html command. At a later time, these binary files can be read via a "read_restart"_read_restart.html command in a new script. Or they can be converted to text data files using the "-r command-line switch"_Section_start.html#start_7 and read by a "read_data"_read_data.html command in a new script. Here we give examples of 2 scripts that read either a binary restart file or a converted data file and then issue a new run command to continue where the previous run left off. They illustrate what settings must be made in the new script. Details are discussed in the documentation for the "read_restart"_read_restart.html and "read_data"_read_data.html commands. Look at the {in.chain} input script provided in the {bench} directory of the LAMMPS distribution to see the original script that these 2 scripts are based on. If that script had the line restart 50 tmp.restart :pre added to it, it would produce 2 binary restart files (tmp.restart.50 and tmp.restart.100) as it ran. This script could be used to read the 1st restart file and re-run the last 50 timesteps: read_restart tmp.restart.50 :pre neighbor 0.4 bin neigh_modify every 1 delay 1 :pre fix 1 all nve fix 2 all langevin 1.0 1.0 10.0 904297 :pre timestep 0.012 :pre run 50 :pre Note that the following commands do not need to be repeated because their settings are included in the restart file: {units, atom_style, special_bonds, pair_style, bond_style}. However these commands do need to be used, since their settings are not in the restart file: {neighbor, fix, timestep}. If you actually use this script to perform a restarted run, you will notice that the thermodynamic data match at step 50 (if you also put a "thermo 50" command in the original script), but do not match at step 100. This is because the "fix langevin"_fix_langevin.html command uses random numbers in a way that does not allow for perfect restarts. As an alternate approach, the restart file could be converted to a data file as follows: lmp_g++ -r tmp.restart.50 tmp.restart.data :pre Then, this script could be used to re-run the last 50 steps: units lj atom_style bond pair_style lj/cut 1.12 pair_modify shift yes bond_style fene special_bonds 0.0 1.0 1.0 :pre read_data tmp.restart.data :pre neighbor 0.4 bin neigh_modify every 1 delay 1 :pre fix 1 all nve fix 2 all langevin 1.0 1.0 10.0 904297 :pre timestep 0.012 :pre reset_timestep 50 run 50 :pre Note that nearly all the settings specified in the original {in.chain} script must be repeated, except the {pair_coeff} and {bond_coeff} commands since the new data file lists the force field coefficients. Also, the "reset_timestep"_reset_timestep.html command is used to tell LAMMPS the current timestep. This value is stored in restart files, but not in data files. :line 6.2 2d simulations :link(howto_2),h4 Use the "dimension"_dimension.html command to specify a 2d simulation. Make the simulation box periodic in z via the "boundary"_boundary.html command. This is the default. If using the "create box"_create_box.html command to define a simulation box, set the z dimensions narrow, but finite, so that the create_atoms command will tile the 3d simulation box with a single z plane of atoms - e.g. "create box"_create_box.html 1 -10 10 -10 10 -0.25 0.25 :pre If using the "read data"_read_data.html command to read in a file of atom coordinates, set the "zlo zhi" values to be finite but narrow, similar to the create_box command settings just described. For each atom in the file, assign a z coordinate so it falls inside the z-boundaries of the box - e.g. 0.0. Use the "fix enforce2d"_fix_enforce2d.html command as the last defined fix to insure that the z-components of velocities and forces are zeroed out every timestep. The reason to make it the last fix is so that any forces induced by other fixes will be zeroed out. Many of the example input scripts included in the LAMMPS distribution are for 2d models. NOTE: Some models in LAMMPS treat particles as finite-size spheres, as opposed to point particles. In 2d, the particles will still be spheres, not disks, meaning their moment of inertia will be the same as in 3d. :line 6.3 CHARMM, AMBER, and DREIDING force fields :link(howto_3),h4 A force field has 2 parts: the formulas that define it and the coefficients used for a particular system. Here we only discuss formulas implemented in LAMMPS that correspond to formulas commonly used in the CHARMM, AMBER, and DREIDING force fields. Setting coefficients is done in the input data file via the "read_data"_read_data.html command or in the input script with commands like "pair_coeff"_pair_coeff.html or "bond_coeff"_bond_coeff.html. See "Section 9"_Section_tools.html for additional tools that can use CHARMM or AMBER to assign force field coefficients and convert their output into LAMMPS input. See "(MacKerell)"_#howto-MacKerell for a description of the CHARMM force field. See "(Cornell)"_#howto-Cornell for a description of the AMBER force field. :link(charmm,http://www.scripps.edu/brooks) :link(amber,http://amber.scripps.edu) These style choices compute force field formulas that are consistent with common options in CHARMM or AMBER. See each command's documentation for the formula it computes. "bond_style"_bond_harmonic.html harmonic "angle_style"_angle_charmm.html charmm "dihedral_style"_dihedral_charmm.html charmm "pair_style"_pair_charmm.html lj/charmm/coul/charmm "pair_style"_pair_charmm.html lj/charmm/coul/charmm/implicit "pair_style"_pair_charmm.html lj/charmm/coul/long :ul "special_bonds"_special_bonds.html charmm "special_bonds"_special_bonds.html amber :ul DREIDING is a generic force field developed by the "Goddard group"_http://www.wag.caltech.edu at Caltech and is useful for predicting structures and dynamics of organic, biological and main-group inorganic molecules. The philosophy in DREIDING is to use general force constants and geometry parameters based on simple hybridization considerations, rather than individual force constants and geometric parameters that depend on the particular combinations of atoms involved in the bond, angle, or torsion terms. DREIDING has an "explicit hydrogen bond term"_pair_hbond_dreiding.html to describe interactions involving a hydrogen atom on very electronegative atoms (N, O, F). See "(Mayo)"_#howto-Mayo for a description of the DREIDING force field These style choices compute force field formulas that are consistent with the DREIDING force field. See each command's documentation for the formula it computes. "bond_style"_bond_harmonic.html harmonic "bond_style"_bond_morse.html morse :ul "angle_style"_angle_harmonic.html harmonic "angle_style"_angle_cosine.html cosine "angle_style"_angle_cosine_periodic.html cosine/periodic :ul "dihedral_style"_dihedral_charmm.html charmm "improper_style"_improper_umbrella.html umbrella :ul "pair_style"_pair_buck.html buck "pair_style"_pair_buck.html buck/coul/cut "pair_style"_pair_buck.html buck/coul/long "pair_style"_pair_lj.html lj/cut "pair_style"_pair_lj.html lj/cut/coul/cut "pair_style"_pair_lj.html lj/cut/coul/long :ul "pair_style"_pair_hbond_dreiding.html hbond/dreiding/lj "pair_style"_pair_hbond_dreiding.html hbond/dreiding/morse :ul "special_bonds"_special_bonds.html dreiding :ul :line 6.4 Running multiple simulations from one input script :link(howto_4),h4 This can be done in several ways. See the documentation for individual commands for more details on how these examples work. If "multiple simulations" means continue a previous simulation for more timesteps, then you simply use the "run"_run.html command multiple times. For example, this script units lj atom_style atomic read_data data.lj run 10000 run 10000 run 10000 run 10000 run 10000 :pre would run 5 successive simulations of the same system for a total of 50,000 timesteps. If you wish to run totally different simulations, one after the other, the "clear"_clear.html command can be used in between them to re-initialize LAMMPS. For example, this script units lj atom_style atomic read_data data.lj run 10000 clear units lj atom_style atomic read_data data.lj.new run 10000 :pre would run 2 independent simulations, one after the other. For large numbers of independent simulations, you can use "variables"_variable.html and the "next"_next.html and "jump"_jump.html commands to loop over the same input script multiple times with different settings. For example, this script, named in.polymer variable d index run1 run2 run3 run4 run5 run6 run7 run8 shell cd $d read_data data.polymer run 10000 shell cd .. clear next d jump in.polymer :pre would run 8 simulations in different directories, using a data.polymer file in each directory. The same concept could be used to run the same system at 8 different temperatures, using a temperature variable and storing the output in different log and dump files, for example variable a loop 8 variable t index 0.8 0.85 0.9 0.95 1.0 1.05 1.1 1.15 log log.$a read data.polymer velocity all create $t 352839 fix 1 all nvt $t $t 100.0 dump 1 all atom 1000 dump.$a run 100000 clear next t next a jump in.polymer :pre All of the above examples work whether you are running on 1 or multiple processors, but assumed you are running LAMMPS on a single partition of processors. LAMMPS can be run on multiple partitions via the "-partition" command-line switch as described in "this section"_Section_start.html#start_7 of the manual. In the last 2 examples, if LAMMPS were run on 3 partitions, the same scripts could be used if the "index" and "loop" variables were replaced with {universe}-style variables, as described in the "variable"_variable.html command. Also, the "next t" and "next a" commands would need to be replaced with a single "next a t" command. With these modifications, the 8 simulations of each script would run on the 3 partitions one after the other until all were finished. Initially, 3 simulations would be started simultaneously, one on each partition. When one finished, that partition would then start the 4th simulation, and so forth, until all 8 were completed. :line 6.5 Multi-replica simulations :link(howto_5),h4 Several commands in LAMMPS run mutli-replica simulations, meaning that multiple instances (replicas) of your simulation are run simultaneously, with small amounts of data exchanged between replicas periodically. These are the relevant commands: "neb"_neb.html for nudged elastic band calculations "prd"_prd.html for parallel replica dynamics "tad"_tad.html for temperature accelerated dynamics "temper"_temper.html for parallel tempering "fix pimd"_fix_pimd.html for path-integral molecular dynamics (PIMD) :ul NEB is a method for finding transition states and barrier energies. PRD and TAD are methods for performing accelerated dynamics to find and perform infrequent events. Parallel tempering or replica exchange runs different replicas at a series of temperature to facilitate rare-event sampling. These commands can only be used if LAMMPS was built with the REPLICA package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info on packages. PIMD runs different replicas whose individual particles are coupled together by springs to model a system or ring-polymers. This commands can only be used if LAMMPS was built with the USER-MISC package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info on packages. In all these cases, you must run with one or more processors per replica. The processors assigned to each replica are determined at run-time by using the "-partition command-line switch"_Section_start.html#start_7 to launch LAMMPS on multiple partitions, which in this context are the same as replicas. E.g. these commands: mpirun -np 16 lmp_linux -partition 8x2 -in in.temper mpirun -np 8 lmp_linux -partition 8x1 -in in.neb :pre would each run 8 replicas, on either 16 or 8 processors. Note the use of the "-in command-line switch"_Section_start.html#start_7 to specify the input script which is required when running in multi-replica mode. Also note that with MPI installed on a machine (e.g. your desktop), you can run on more (virtual) processors than you have physical processors. Thus the above commands could be run on a single-processor (or few-processor) desktop so that you can run a multi-replica simulation on more replicas than you have physical processors. :line 6.6 Granular models :link(howto_6),h4 Granular system are composed of spherical particles with a diameter, as opposed to point particles. This means they have an angular velocity and torque can be imparted to them to cause them to rotate. To run a simulation of a granular model, you will want to use the following commands: "atom_style sphere"_atom_style.html "fix nve/sphere"_fix_nve_sphere.html "fix gravity"_fix_gravity.html :ul This compute "compute erotate/sphere"_compute_erotate_sphere.html :ul calculates rotational kinetic energy which can be "output with thermodynamic info"_Section_howto.html#howto_15. Use one of these 3 pair potentials, which compute forces and torques between interacting pairs of particles: "pair_style"_pair_style.html gran/history "pair_style"_pair_style.html gran/no_history "pair_style"_pair_style.html gran/hertzian :ul These commands implement fix options specific to granular systems: "fix freeze"_fix_freeze.html "fix pour"_fix_pour.html "fix viscous"_fix_viscous.html "fix wall/gran"_fix_wall_gran.html :ul The fix style {freeze} zeroes both the force and torque of frozen atoms, and should be used for granular system instead of the fix style {setforce}. For computational efficiency, you can eliminate needless pairwise computations between frozen atoms by using this command: "neigh_modify"_neigh_modify.html exclude :ul :line 6.7 TIP3P water model :link(howto_7),h4 The TIP3P water model as implemented in CHARMM "(MacKerell)"_#howto-MacKerell specifies a 3-site rigid water molecule with charges and Lennard-Jones parameters assigned to each of the 3 atoms. In LAMMPS the "fix shake"_fix_shake.html command can be used to hold the two O-H bonds and the H-O-H angle rigid. A bond style of {harmonic} and an angle style of {harmonic} or {charmm} should also be used. These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid TIP3P-CHARMM model with a cutoff. The K values can be used if a flexible TIP3P model (without fix shake) is desired. If the LJ epsilon and sigma for HH and OH are set to 0.0, it corresponds to the original 1983 TIP3P model "(Jorgensen)"_#Jorgensen. O mass = 15.9994 H mass = 1.008 O charge = -0.834 H charge = 0.417 LJ epsilon of OO = 0.1521 LJ sigma of OO = 3.1507 LJ epsilon of HH = 0.0460 LJ sigma of HH = 0.4000 LJ epsilon of OH = 0.0836 LJ sigma of OH = 1.7753 K of OH bond = 450 r0 of OH bond = 0.9572 K of HOH angle = 55 theta of HOH angle = 104.52 :all(b),p These are the parameters to use for TIP3P with a long-range Coulombic solver (e.g. Ewald or PPPM in LAMMPS), see "(Price)"_#Price for details: O mass = 15.9994 H mass = 1.008 O charge = -0.830 H charge = 0.415 LJ epsilon of OO = 0.102 LJ sigma of OO = 3.188 LJ epsilon, sigma of OH, HH = 0.0 K of OH bond = 450 r0 of OH bond = 0.9572 K of HOH angle = 55 theta of HOH angle = 104.52 :all(b),p Wikipedia also has a nice article on "water models"_http://en.wikipedia.org/wiki/Water_model. :line 6.8 TIP4P water model :link(howto_8),h4 The four-point TIP4P rigid water model extends the traditional three-point TIP3P model by adding an additional site, usually massless, where the charge associated with the oxygen atom is placed. This site M is located at a fixed distance away from the oxygen along the bisector of the HOH bond angle. A bond style of {harmonic} and an angle style of {harmonic} or {charmm} should also be used. A TIP4P model is run with LAMMPS using either this command for a cutoff model: "pair_style lj/cut/tip4p/cut"_pair_lj.html or these two commands for a long-range model: "pair_style lj/cut/tip4p/long"_pair_lj.html "kspace_style pppm/tip4p"_kspace_style.html :ul For both models, the bond lengths and bond angles should be held fixed using the "fix shake"_fix_shake.html command. These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid TIP4P model with a cutoff "(Jorgensen)"_#Jorgensen. Note that the OM distance is specified in the "pair_style"_pair_style.html command, not as part of the pair coefficients. O mass = 15.9994 H mass = 1.008 O charge = -1.040 H charge = 0.520 r0 of OH bond = 0.9572 theta of HOH angle = 104.52 OM distance = 0.15 LJ epsilon of O-O = 0.1550 LJ sigma of O-O = 3.1536 LJ epsilon, sigma of OH, HH = 0.0 Coulombic cutoff = 8.5 :all(b),p For the TIP4/Ice model (J Chem Phys, 122, 234511 (2005); http://dx.doi.org/10.1063/1.1931662) these values can be used: O mass = 15.9994 H mass = 1.008 O charge = -1.1794 H charge = 0.5897 r0 of OH bond = 0.9572 theta of HOH angle = 104.52 OM distance = 0.1577 LJ epsilon of O-O = 0.21084 LJ sigma of O-O = 3.1668 LJ epsilon, sigma of OH, HH = 0.0 Coulombic cutoff = 8.5 :all(b),p For the TIP4P/2005 model (J Chem Phys, 123, 234505 (2005); http://dx.doi.org/10.1063/1.2121687), these values can be used: O mass = 15.9994 H mass = 1.008 O charge = -1.1128 H charge = 0.5564 r0 of OH bond = 0.9572 theta of HOH angle = 104.52 OM distance = 0.1546 LJ epsilon of O-O = 0.1852 LJ sigma of O-O = 3.1589 LJ epsilon, sigma of OH, HH = 0.0 Coulombic cutoff = 8.5 :all(b),p These are the parameters to use for TIP4P with a long-range Coulombic solver (e.g. Ewald or PPPM in LAMMPS): O mass = 15.9994 H mass = 1.008 O charge = -1.0484 H charge = 0.5242 r0 of OH bond = 0.9572 theta of HOH angle = 104.52 OM distance = 0.1250 LJ epsilon of O-O = 0.16275 LJ sigma of O-O = 3.16435 LJ epsilon, sigma of OH, HH = 0.0 :all(b),p Note that the when using the TIP4P pair style, the neighobr list cutoff for Coulomb interactions is effectively extended by a distance 2 * (OM distance), to account for the offset distance of the fictitious charges on O atoms in water molecules. Thus it is typically best in an efficiency sense to use a LJ cutoff >= Coulomb cutoff + 2*(OM distance), to shrink the size of the neighbor list. This leads to slightly larger cost for the long-range calculation, so you can test the trade-off for your model. The OM distance and the LJ and Coulombic cutoffs are set in the "pair_style lj/cut/tip4p/long"_pair_lj.html command. Wikipedia also has a nice article on "water models"_http://en.wikipedia.org/wiki/Water_model. :line 6.9 SPC water model :link(howto_9),h4 The SPC water model specifies a 3-site rigid water molecule with charges and Lennard-Jones parameters assigned to each of the 3 atoms. In LAMMPS the "fix shake"_fix_shake.html command can be used to hold the two O-H bonds and the H-O-H angle rigid. A bond style of {harmonic} and an angle style of {harmonic} or {charmm} should also be used. These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid SPC model. O mass = 15.9994 H mass = 1.008 O charge = -0.820 H charge = 0.410 LJ epsilon of OO = 0.1553 LJ sigma of OO = 3.166 LJ epsilon, sigma of OH, HH = 0.0 r0 of OH bond = 1.0 theta of HOH angle = 109.47 :all(b),p Note that as originally proposed, the SPC model was run with a 9 Angstrom cutoff for both LJ and Coulommbic terms. It can also be used with long-range Coulombics (Ewald or PPPM in LAMMPS), without changing any of the parameters above, though it becomes a different model in that mode of usage. The SPC/E (extended) water model is the same, except the partial charge assignemnts change: O charge = -0.8476 H charge = 0.4238 :all(b),p See the "(Berendsen)"_#howto-Berendsen reference for more details on both the SPC and SPC/E models. Wikipedia also has a nice article on "water models"_http://en.wikipedia.org/wiki/Water_model. :line 6.10 Coupling LAMMPS to other codes :link(howto_10),h4 LAMMPS is designed to allow it to be coupled to other codes. For example, a quantum mechanics code might compute forces on a subset of atoms and pass those forces to LAMMPS. Or a continuum finite element (FE) simulation might use atom positions as boundary conditions on FE nodal points, compute a FE solution, and return interpolated forces on MD atoms. LAMMPS can be coupled to other codes in at least 3 ways. Each has advantages and disadvantages, which you'll have to think about in the context of your application. (1) Define a new "fix"_fix.html command that calls the other code. In this scenario, LAMMPS is the driver code. During its timestepping, the fix is invoked, and can make library calls to the other code, which has been linked to LAMMPS as a library. This is the way the "POEMS"_poems package that performs constrained rigid-body motion on groups of atoms is hooked to LAMMPS. See the "fix poems"_fix_poems.html command for more details. See "this section"_Section_modify.html of the documentation for info on how to add a new fix to LAMMPS. :link(poems,http://www.rpi.edu/~anderk5/lab) (2) Define a new LAMMPS command that calls the other code. This is conceptually similar to method (1), but in this case LAMMPS and the other code are on a more equal footing. Note that now the other code is not called during the timestepping of a LAMMPS run, but between runs. The LAMMPS input script can be used to alternate LAMMPS runs with calls to the other code, invoked via the new command. The "run"_run.html command facilitates this with its {every} option, which makes it easy to run a few steps, invoke the command, run a few steps, invoke the command, etc. In this scenario, the other code can be called as a library, as in (1), or it could be a stand-alone code, invoked by a system() call made by the command (assuming your parallel machine allows one or more processors to start up another program). In the latter case the stand-alone code could communicate with LAMMPS thru files that the command writes and reads. See "Section 10"_Section_modify.html of the documentation for how to add a new command to LAMMPS. (3) Use LAMMPS as a library called by another code. In this case the other code is the driver and calls LAMMPS as needed. Or a wrapper code could link and call both LAMMPS and another code as libraries. Again, the "run"_run.html command has options that allow it to be invoked with minimal overhead (no setup or clean-up) if you wish to do multiple short runs, driven by another program. Examples of driver codes that call LAMMPS as a library are included in the examples/COUPLE directory of the LAMMPS distribution; see examples/COUPLE/README for more details: simple: simple driver programs in C++ and C which invoke LAMMPS as a library :ulb,l lammps_quest: coupling of LAMMPS and "Quest"_quest, to run classical MD with quantum forces calculated by a density functional code :l lammps_spparks: coupling of LAMMPS and "SPPARKS"_spparks, to couple a kinetic Monte Carlo model for grain growth using MD to calculate strain induced across grain boundaries :l :ule :link(quest,http://dft.sandia.gov/Quest) :link(spparks,http://www.sandia.gov/~sjplimp/spparks.html) "This section"_Section_start.html#start_5 of the documentation describes how to build LAMMPS as a library. Once this is done, you can interface with LAMMPS either via C++, C, Fortran, or Python (or any other language that supports a vanilla C-like interface). For example, from C++ you could create one (or more) "instances" of LAMMPS, pass it an input script to process, or execute individual commands, all by invoking the correct class methods in LAMMPS. From C or Fortran you can make function calls to do the same things. See "Section 11"_Section_python.html of the manual for a description of the Python wrapper provided with LAMMPS that operates through the LAMMPS library interface. The files src/library.cpp and library.h contain the C-style interface to LAMMPS. See "Section 6.19"_Section_howto.html#howto_19 of the manual for a description of the interface and how to extend it for your needs. Note that the lammps_open() function that creates an instance of LAMMPS takes an MPI communicator as an argument. This means that instance of LAMMPS will run on the set of processors in the communicator. Thus the calling code can run LAMMPS on all or a subset of processors. For example, a wrapper script might decide to alternate between LAMMPS and another code, allowing them both to run on all the processors. Or it might allocate half the processors to LAMMPS and half to the other code and run both codes simultaneously before syncing them up periodically. Or it might instantiate multiple instances of LAMMPS to perform different calculations. :line 6.11 Visualizing LAMMPS snapshots :link(howto_11),h4 LAMMPS itself does not do visualization, but snapshots from LAMMPS simulations can be visualized (and analyzed) in a variety of ways. LAMMPS snapshots are created by the "dump"_dump.html command which can create files in several formats. The native LAMMPS dump format is a text file (see "dump atom" or "dump custom") which can be visualized by the "xmovie"_Section_tools.html#xmovie program, included with the LAMMPS package. This produces simple, fast 2d projections of 3d systems, and can be useful for rapid debugging of simulation geometry and atom trajectories. Several programs included with LAMMPS as auxiliary tools can convert native LAMMPS dump files to other formats. See the "Section 9"_Section_tools.html doc page for details. The first is the "ch2lmp tool"_Section_tools.html#charmm, which contains a lammps2pdb Perl script which converts LAMMPS dump files into PDB files. The second is the "lmp2arc tool"_Section_tools.html#arc which converts LAMMPS dump files into Accelrys' Insight MD program files. The third is the "lmp2cfg tool"_Section_tools.html#cfg which converts LAMMPS dump files into CFG files which can be read into the "AtomEye"_atomeye visualizer. A Python-based toolkit distributed by our group can read native LAMMPS dump files, including custom dump files with additional columns of user-specified atom information, and convert them to various formats or pipe them into visualization software directly. See the "Pizza.py WWW site"_pizza for details. Specifically, Pizza.py can convert LAMMPS dump files into PDB, XYZ, "Ensight"_ensight, and VTK formats. Pizza.py can pipe LAMMPS dump files directly into the Raster3d and RasMol visualization programs. Pizza.py has tools that do interactive 3d OpenGL visualization and one that creates SVG images of dump file snapshots. LAMMPS can create XYZ files directly (via "dump xyz") which is a simple text-based file format used by many visualization programs including "VMD"_vmd. LAMMPS can create DCD files directly (via "dump dcd") which can be read by "VMD"_vmd in conjunction with a CHARMM PSF file. Using this form of output avoids the need to convert LAMMPS snapshots to PDB files. See the "dump"_dump.html command for more information on DCD files. LAMMPS can create XTC files directly (via "dump xtc") which is GROMACS file format which can also be read by "VMD"_vmd for visualization. See the "dump"_dump.html command for more information on XTC files. :link(pizza,http://www.sandia.gov/~sjplimp/pizza.html) :link(vmd,http://www.ks.uiuc.edu/Research/vmd) :link(ensight,http://www.ensight.com) :link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A) :line 6.12 Triclinic (non-orthogonal) simulation boxes :link(howto_12),h4 By default, LAMMPS uses an orthogonal simulation box to encompass the particles. The "boundary"_boundary.html command sets the boundary conditions of the box (periodic, non-periodic, etc). The orthogonal box has its "origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors starting from the origin given by [a] = (xhi-xlo,0,0); [b] = (0,yhi-ylo,0); [c] = (0,0,zhi-zlo). The 6 parameters (xlo,xhi,ylo,yhi,zlo,zhi) are defined at the time the simulation box is created, e.g. by the "create_box"_create_box.html or "read_data"_read_data.html or "read_restart"_read_restart.html commands. Additionally, LAMMPS defines box size parameters lx,ly,lz where lx = xhi-xlo, and similarly in the y and z dimensions. The 6 parameters, as well as lx,ly,lz, can be output via the "thermo_style custom"_thermo_style.html command. LAMMPS also allows simulations to be performed in triclinic (non-orthogonal) simulation boxes shaped as a parallelepiped with triclinic symmetry. The parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors starting from the origin given by [a] = (xhi-xlo,0,0); [b] = (xy,yhi-ylo,0); [c] = (xz,yz,zhi-zlo). {xy,xz,yz} can be 0.0 or positive or negative values and are called "tilt factors" because they are the amount of displacement applied to faces of an originally orthogonal box to transform it into the parallelepiped. In LAMMPS the triclinic simulation box edge vectors [a], [b], and [c] cannot be arbitrary vectors. As indicated, [a] must lie on the positive x axis. [b] must lie in the xy plane, with strictly positive y component. [c] may have any orientation with strictly positive z component. The requirement that [a], [b], and [c] have strictly positive x, y, and z components, respectively, ensures that [a], [b], and [c] form a complete right-handed basis. These restrictions impose no loss of generality, since it is possible to rotate/invert any set of 3 crystal basis vectors so that they conform to the restrictions. For example, assume that the 3 vectors [A],[B],[C] are the edge vectors of a general parallelepiped, where there is no restriction on [A],[B],[C] other than they form a complete right-handed basis i.e. [A] x [B] . [C] > 0. The equivalent LAMMPS [a],[b],[c] are a linear rotation of [A], [B], and [C] and can be computed as follows: :c,image(Eqs/transform.jpg) where A = | [A] | indicates the scalar length of [A]. The hat symbol (^) indicates the corresponding unit vector. {beta} and {gamma} are angles between the vectors described below. Note that by construction, [a], [b], and [c] have strictly positive x, y, and z components, respectively. If it should happen that [A], [B], and [C] form a left-handed basis, then the above equations are not valid for [c]. In this case, it is necessary to first apply an inversion. This can be achieved by interchanging two basis vectors or by changing the sign of one of them. For consistency, the same rotation/inversion applied to the basis vectors must also be applied to atom positions, velocities, and any other vector quantities. This can be conveniently achieved by first converting to fractional coordinates in the old basis and then converting to distance coordinates in the new basis. The transformation is given by the following equation: :c,image(Eqs/rotate.jpg) where {V} is the volume of the box, [X] is the original vector quantity and [x] is the vector in the LAMMPS basis. There is no requirement that a triclinic box be periodic in any dimension, though it typically should be in at least the 2nd dimension of the tilt (y in xy) if you want to enforce a shift in periodic boundary conditions across that boundary. Some commands that work with triclinic boxes, e.g. the "fix deform"_fix_deform.html and "fix npt"_fix_nh.html commands, require periodicity or non-shrink-wrap boundary conditions in specific dimensions. See the command doc pages for details. The 9 parameters (xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) are defined at the time the simluation box is created. This happens in one of 3 ways. If the "create_box"_create_box.html command is used with a region of style {prism}, then a triclinic box is setup. See the "region"_region.html command for details. If the "read_data"_read_data.html command is used to define the simulation box, and the header of the data file contains a line with the "xy xz yz" keyword, then a triclinic box is setup. See the "read_data"_read_data.html command for details. Finally, if the "read_restart"_read_restart.html command reads a restart file which was written from a simulation using a triclinic box, then a triclinic box will be setup for the restarted simulation. Note that you can define a triclinic box with all 3 tilt factors = 0.0, so that it is initially orthogonal. This is necessary if the box will become non-orthogonal, e.g. due to the "fix npt"_fix_nh.html or "fix deform"_fix_deform.html commands. Alternatively, you can use the "change_box"_change_box.html command to convert a simulation box from orthogonal to triclinic and vice versa. As with orthogonal boxes, LAMMPS defines triclinic box size parameters lx,ly,lz where lx = xhi-xlo, and similarly in the y and z dimensions. The 9 parameters, as well as lx,ly,lz, can be output via the "thermo_style custom"_thermo_style.html command. To avoid extremely tilted boxes (which would be computationally inefficient), LAMMPS normally requires that no tilt factor can skew the box more than half the distance of the parallel box length, which is the 1st dimension in the tilt factor (x for xz). This is required both when the simulation box is created, e.g. via the "create_box"_create_box.html or "read_data"_read_data.html commands, as well as when the box shape changes dynamically during a simulation, e.g. via the "fix deform"_fix_deform.html or "fix npt"_fix_nh.html commands. For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then configurations with tilt = ..., -15, -5, 5, 15, 25, ... are geometrically all equivalent. If the box tilt exceeds this limit during a dynamics run (e.g. via the "fix deform"_fix_deform.html command), then the box is "flipped" to an equivalent shape with a tilt factor within the bounds, so the run can continue. See the "fix deform"_fix_deform.html doc page for further details. One exception to this rule is if the 1st dimension in the tilt factor (x for xy) is non-periodic. In that case, the limits on the tilt factor are not enforced, since flipping the box in that dimension does not change the atom positions due to non-periodicity. In this mode, if you tilt the system to extreme angles, the simulation will simply become inefficient, due to the highly skewed simulation box. The limitation on not creating a simulation box with a tilt factor skewing the box more than half the distance of the parallel box length can be overridden via the "box"_box.html command. Setting the {tilt} keyword to {large} allows any tilt factors to be specified. Box flips that may occur using the "fix deform"_fix_deform.html or "fix npt"_fix_nh.html commands can be turned off using the {flip no} option with either of the commands. Note that if a simulation box has a large tilt factor, LAMMPS will run less efficiently, due to the large volume of communication needed to acquire ghost atoms around a processor's irregular-shaped sub-domain. For extreme values of tilt, LAMMPS may also lose atoms and generate an error. Triclinic crystal structures are often defined using three lattice constants {a}, {b}, and {c}, and three angles {alpha}, {beta} and {gamma}. Note that in this nomenclature, the a, b, and c lattice constants are the scalar lengths of the edge vectors [a], [b], and [c] defined above. The relationship between these 6 quantities (a,b,c,alpha,beta,gamma) and the LAMMPS box sizes (lx,ly,lz) = (xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) is as follows: :c,image(Eqs/box.jpg) The inverse relationship can be written as follows: :c,image(Eqs/box_inverse.jpg) The values of {a}, {b}, {c} , {alpha}, {beta} , and {gamma} can be printed out or accessed by computes using the "thermo_style custom"_thermo_style.html keywords {cella}, {cellb}, {cellc}, {cellalpha}, {cellbeta}, {cellgamma}, respectively. As discussed on the "dump"_dump.html command doc page, when the BOX BOUNDS for a snapshot is written to a dump file for a triclinic box, an orthogonal bounding box which encloses the triclinic simulation box is output, along with the 3 tilt factors (xy, xz, yz) of the triclinic box, formatted as follows: ITEM: BOX BOUNDS xy xz yz xlo_bound xhi_bound xy ylo_bound yhi_bound xz zlo_bound zhi_bound yz :pre This bounding box is convenient for many visualization programs and is calculated from the 9 triclinic box parameters (xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) as follows: xlo_bound = xlo + MIN(0.0,xy,xz,xy+xz) xhi_bound = xhi + MAX(0.0,xy,xz,xy+xz) ylo_bound = ylo + MIN(0.0,yz) yhi_bound = yhi + MAX(0.0,yz) zlo_bound = zlo zhi_bound = zhi :pre These formulas can be inverted if you need to convert the bounding box back into the triclinic box parameters, e.g. xlo = xlo_bound - MIN(0.0,xy,xz,xy+xz). One use of triclinic simulation boxes is to model solid-state crystals with triclinic symmetry. The "lattice"_lattice.html command can be used with non-orthogonal basis vectors to define a lattice that will tile a triclinic simulation box via the "create_atoms"_create_atoms.html command. A second use is to run Parinello-Rahman dyanamics via the "fix npt"_fix_nh.html command, which will adjust the xy, xz, yz tilt factors to compensate for off-diagonal components of the pressure tensor. The analalog for an "energy minimization"_minimize.html is the "fix box/relax"_fix_box_relax.html command. A third use is to shear a bulk solid to study the response of the material. The "fix deform"_fix_deform.html command can be used for this purpose. It allows dynamic control of the xy, xz, yz tilt factors as a simulation runs. This is discussed in the next section on non-equilibrium MD (NEMD) simulations. :line 6.13 NEMD simulations :link(howto_13),h4 Non-equilibrium molecular dynamics or NEMD simulations are typically used to measure a fluid's rheological properties such as viscosity. In LAMMPS, such simulations can be performed by first setting up a non-orthogonal simulation box (see the preceding Howto section). A shear strain can be applied to the simulation box at a desired strain rate by using the "fix deform"_fix_deform.html command. The "fix nvt/sllod"_fix_nvt_sllod.html command can be used to thermostat the sheared fluid and integrate the SLLOD equations of motion for the system. Fix nvt/sllod uses "compute temp/deform"_compute_temp_deform.html to compute a thermal temperature by subtracting out the streaming velocity of the shearing atoms. The velocity profile or other properties of the fluid can be monitored via the "fix ave/chunk"_fix_ave_chunk.html command. As discussed in the previous section on non-orthogonal simulation boxes, the amount of tilt or skew that can be applied is limited by LAMMPS for computational efficiency to be 1/2 of the parallel box length. However, "fix deform"_fix_deform.html can continuously strain a box by an arbitrary amount. As discussed in the "fix deform"_fix_deform.html command, when the tilt value reaches a limit, the box is flipped to the opposite limit which is an equivalent tiling of periodic space. The strain rate can then continue to change as before. In a long NEMD simulation these box re-shaping events may occur many times. In a NEMD simulation, the "remap" option of "fix deform"_fix_deform.html should be set to "remap v", since that is what "fix nvt/sllod"_fix_nvt_sllod.html assumes to generate a velocity profile consistent with the applied shear strain rate. An alternative method for calculating viscosities is provided via the "fix viscosity"_fix_viscosity.html command. :line 6.14 Finite-size spherical and aspherical particles :link(howto_14),h4 Typical MD models treat atoms or particles as point masses. Sometimes it is desirable to have a model with finite-size particles such as spheroids or ellipsoids or generalized aspherical bodies. The difference is that such particles have a moment of inertia, rotational energy, and angular momentum. Rotation is induced by torque coming from interactions with other particles. LAMMPS has several options for running simulations with these kinds of particles. The following aspects are discussed in turn: atom styles pair potentials time integration computes, thermodynamics, and dump output rigid bodies composed of finite-size particles :ul Example input scripts for these kinds of models are in the body, colloid, dipole, ellipse, line, peri, pour, and tri directories of the "examples directory"_Section_example.html in the LAMMPS distribution. Atom styles :h5 There are several "atom styles"_atom_style.html that allow for definition of finite-size particles: sphere, dipole, ellipsoid, line, tri, peri, and body. The sphere style defines particles that are spheriods and each particle can have a unique diameter and mass (or density). These particles store an angular velocity (omega) and can be acted upon by torque. The "set" command can be used to modify the diameter and mass of individual particles, after then are created. The dipole style does not actually define finite-size particles, but is often used in conjunction with spherical particles, via a command like atom_style hybrid sphere dipole :pre This is because when dipoles interact with each other, they induce torques, and a particle must be finite-size (i.e. have a moment of inertia) in order to respond and rotate. See the "atom_style dipole"_atom_style.html command for details. The "set" command can be used to modify the orientation and length of the dipole moment of individual particles, after then are created. The ellipsoid style defines particles that are ellipsoids and thus can be aspherical. Each particle has a shape, specified by 3 diameters, and mass (or density). These particles store an angular momentum and their orientation (quaternion), and can be acted upon by torque. They do not store an angular velocity (omega), which can be in a different direction than angular momentum, rather they compute it as needed. The "set" command can be used to modify the diameter, orientation, and mass of individual particles, after then are created. It also has a brief explanation of what quaternions are. The line style defines line segment particles with two end points and a mass (or density). They can be used in 2d simulations, and they can be joined together to form rigid bodies which represent arbitrary polygons. The tri style defines triangular particles with three corner points and a mass (or density). They can be used in 3d simulations, and they can be joined together to form rigid bodies which represent arbitrary particles with a triangulated surface. The peri style is used with "Peridynamic models"_pair_peri.html and defines particles as having a volume, that is used internally in the "pair_style peri"_pair_peri.html potentials. The body style allows for definition of particles which can represent complex entities, such as surface meshes of discrete points, collections of sub-particles, deformable objects, etc. The body style is discussed in more detail on the "body"_body.html doc page. Note that if one of these atom styles is used (or multiple styles via the "atom_style hybrid"_atom_style.html command), not all particles in the system are required to be finite-size or aspherical. For example, in the ellipsoid style, if the 3 shape parameters are set to the same value, the particle will be a sphere rather than an ellipsoid. If the 3 shape parameters are all set to 0.0 or if the diameter is set to 0.0, it will be a point particle. In the line or tri style, if the lineflag or triflag is specified as 0, then it will be a point particle. Some of the pair styles used to compute pairwise interactions between finite-size particles also compute the correct interaction with point particles as well, e.g. the interaction between a point particle and a finite-size particle or between two point particles. If necessary, "pair_style hybrid"_pair_hybrid.html can be used to insure the correct interactions are computed for the appropriate style of interactions. Likewise, using groups to partition particles (ellipsoids versus spheres versus point particles) will allow you to use the appropriate time integrators and temperature computations for each class of particles. See the doc pages for various commands for details. Also note that for "2d simulations"_dimension.html, atom styles sphere and ellipsoid still use 3d particles, rather than as circular disks or ellipses. This means they have the same moment of inertia as the 3d object. When temperature is computed, the correct degrees of freedom are used for rotation in a 2d versus 3d system. Pair potentials :h5 When a system with finite-size particles is defined, the particles will only rotate and experience torque if the force field computes such interactions. These are the various "pair styles"_pair_style.html that generate torque: "pair_style gran/history"_pair_gran.html "pair_style gran/hertzian"_pair_gran.html "pair_style gran/no_history"_pair_gran.html "pair_style dipole/cut"_pair_dipole.html "pair_style gayberne"_pair_gayberne.html "pair_style resquared"_pair_resquared.html "pair_style brownian"_pair_brownian.html "pair_style lubricate"_pair_lubricate.html "pair_style line/lj"_pair_line_lj.html "pair_style tri/lj"_pair_tri_lj.html "pair_style body"_pair_body.html :ul The granular pair styles are used with spherical particles. The dipole pair style is used with the dipole atom style, which could be applied to spherical or ellipsoidal particles. The GayBerne and REsquared potentials require ellipsoidal particles, though they will also work if the 3 shape parameters are the same (a sphere). The Brownian and lubrication potentials are used with spherical particles. The line, tri, and body potentials are used with line segment, triangular, and body particles respectively. Time integration :h5 There are several fixes that perform time integration on finite-size spherical particles, meaning the integrators update the rotational orientation and angular velocity or angular momentum of the particles: "fix nve/sphere"_fix_nve_sphere.html "fix nvt/sphere"_fix_nvt_sphere.html "fix npt/sphere"_fix_npt_sphere.html :ul Likewise, there are 3 fixes that perform time integration on ellipsoidal particles: "fix nve/asphere"_fix_nve_asphere.html "fix nvt/asphere"_fix_nvt_asphere.html "fix npt/asphere"_fix_npt_asphere.html :ul The advantage of these fixes is that those which thermostat the particles include the rotational degrees of freedom in the temperature calculation and thermostatting. The "fix langevin"_fix_langevin command can also be used with its {omgea} or {angmom} options to thermostat the rotational degrees of freedom for spherical or ellipsoidal particles. Other thermostatting fixes only operate on the translational kinetic energy of finite-size particles. These fixes perform constant NVE time integration on line segment, triangular, and body particles: "fix nve/line"_fix_nve_line.html "fix nve/tri"_fix_nve_tri.html "fix nve/body"_fix_nve_body.html :ul Note that for mixtures of point and finite-size particles, these integration fixes can only be used with "groups"_group.html which contain finite-size particles. Computes, thermodynamics, and dump output :h5 There are several computes that calculate the temperature or rotational energy of spherical or ellipsoidal particles: "compute temp/sphere"_compute_temp_sphere.html "compute temp/asphere"_compute_temp_asphere.html "compute erotate/sphere"_compute_erotate_sphere.html "compute erotate/asphere"_compute_erotate_asphere.html :ul These include rotational degrees of freedom in their computation. If you wish the thermodynamic output of temperature or pressure to use one of these computes (e.g. for a system entirely composed of finite-size particles), then the compute can be defined and the "thermo_modify"_thermo_modify.html command used. Note that by default thermodynamic quantities will be calculated with a temperature that only includes translational degrees of freedom. See the "thermo_style"_thermo_style.html command for details. These commands can be used to output various attributes of finite-size particles: "dump custom"_dump.html "compute property/atom"_compute_property_atom.html "dump local"_dump.html "compute body/local"_compute_body_local.html :ul Attributes include the dipole moment, the angular velocity, the angular momentum, the quaternion, the torque, the end-point and corner-point coordinates (for line and tri particles), and sub-particle attributes of body particles. Rigid bodies composed of finite-size particles :h5 The "fix rigid"_fix_rigid.html command treats a collection of particles as a rigid body, computes its inertia tensor, sums the total force and torque on the rigid body each timestep due to forces on its constituent particles, and integrates the motion of the rigid body. If any of the constituent particles of a rigid body are finite-size particles (spheres or ellipsoids or line segments or triangles), then their contribution to the inertia tensor of the body is different than if they were point particles. This means the rotational dynamics of the rigid body will be different. Thus a model of a dimer is different if the dimer consists of two point masses versus two spheroids, even if the two particles have the same mass. Finite-size particles that experience torque due to their interaction with other particles will also impart that torque to a rigid body they are part of. See the "fix rigid" command for example of complex rigid-body models it is possible to define in LAMMPS. Note that the "fix shake"_fix_shake.html command can also be used to treat 2, 3, or 4 particles as a rigid body, but it always assumes the particles are point masses. Also note that body particles cannot be modeled with the "fix rigid"_fix_rigid.html command. Body particles are treated by LAMMPS as single particles, though they can store internal state, such as a list of sub-particles. Individual body partices are typically treated as rigid bodies, and their motion integrated with a command like "fix nve/body"_fix_nve_body.html. Interactions between pairs of body particles are computed via a command like "pair_style body"_pair_body.html. :line 6.15 Output from LAMMPS (thermo, dumps, computes, fixes, variables) :link(howto_15),h4 There are four basic kinds of LAMMPS output: "Thermodynamic output"_thermo_style.html, which is a list of quantities printed every few timesteps to the screen and logfile. :ulb,l "Dump files"_dump.html, which contain snapshots of atoms and various per-atom values and are written at a specified frequency. :l Certain fixes can output user-specified quantities to files: "fix ave/time"_fix_ave_time.html for time averaging, "fix ave/chunk"_fix_ave_chunk.html for spatial or other averaging, and "fix print"_fix_print.html for single-line output of "variables"_variable.html. Fix print can also output to the screen. :l "Restart files"_restart.html. :l :ule A simulation prints one set of thermodynamic output and (optionally) restart files. It can generate any number of dump files and fix output files, depending on what "dump"_dump.html and "fix"_fix.html commands you specify. As discussed below, LAMMPS gives you a variety of ways to determine what quantities are computed and printed when the thermodynamics, dump, or fix commands listed above perform output. Throughout this discussion, note that users can also "add their own computes and fixes to LAMMPS"_Section_modify.html which can then generate values that can then be output with these commands. The following sub-sections discuss different LAMMPS command related to output and the kind of data they operate on and produce: "Global/per-atom/local data"_#global "Scalar/vector/array data"_#scalar "Thermodynamic output"_#thermo "Dump file output"_#dump "Fixes that write output files"_#fixoutput "Computes that process output quantities"_#computeoutput "Fixes that process output quantities"_#fixprocoutput "Computes that generate values to output"_#compute "Fixes that generate values to output"_#fix "Variables that generate values to output"_#variable "Summary table of output options and data flow between commands"_#table :ul Global/per-atom/local data :h5,link(global) Various output-related commands work with three different styles of data: global, per-atom, or local. A global datum is one or more system-wide values, e.g. the temperature of the system. A per-atom datum is one or more values per atom, e.g. the kinetic energy of each atom. Local datums are calculated by each processor based on the atoms it owns, but there may be zero or more per atom, e.g. a list of bond distances. Scalar/vector/array data :h5,link(scalar) Global, per-atom, and local datums can each come in three kinds: a single scalar value, a vector of values, or a 2d array of values. The doc page for a "compute" or "fix" or "variable" that generates data will specify both the style and kind of data it produces, e.g. a per-atom vector. When a quantity is accessed, as in many of the output commands discussed below, it can be referenced via the following bracket notation, where ID in this case is the ID of a compute. The leading "c_" would be replaced by "f_" for a fix, or "v_" for a variable: c_ID | entire scalar, vector, or array c_ID\[I\] | one element of vector, one column of array c_ID\[I\]\[J\] | one element of array :tb(s=|) In other words, using one bracket reduces the dimension of the data once (vector -> scalar, array -> vector). Using two brackets reduces the dimension twice (array -> scalar). Thus a command that uses scalar values as input can typically also process elements of a vector or array. Thermodynamic output :h5,link(thermo) The frequency and format of thermodynamic output is set by the "thermo"_thermo.html, "thermo_style"_thermo_style.html, and "thermo_modify"_thermo_modify.html commands. The "thermo_style"_thermo_style.html command also specifies what values are calculated and written out. Pre-defined keywords can be specified (e.g. press, etotal, etc). Three additional kinds of keywords can also be specified (c_ID, f_ID, v_name), where a "compute"_compute.html or "fix"_fix.html or "variable"_variable.html provides the value to be output. In each case, the compute, fix, or variable must generate global values for input to the "thermo_style custom"_dump.html command. Note that thermodynamic output values can be "extensive" or "intensive". The former scale with the number of atoms in the system (e.g. total energy), the latter do not (e.g. temperature). The setting for "thermo_modify norm"_thermo_modify.html determines whether extensive quantities are normalized or not. Computes and fixes produce either extensive or intensive values; see their individual doc pages for details. "Equal-style variables"_variable.html produce only intensive values; you can include a division by "natoms" in the formula if desired, to make an extensive calculation produce an intensive result. Dump file output :h5,link(dump) Dump file output is specified by the "dump"_dump.html and "dump_modify"_dump_modify.html commands. There are several pre-defined formats (dump atom, dump xtc, etc). There is also a "dump custom"_dump.html format where the user specifies what values are output with each atom. Pre-defined atom attributes can be specified (id, x, fx, etc). Three additional kinds of keywords can also be specified (c_ID, f_ID, v_name), where a "compute"_compute.html or "fix"_fix.html or "variable"_variable.html provides the values to be output. In each case, the compute, fix, or variable must generate per-atom values for input to the "dump custom"_dump.html command. There is also a "dump local"_dump.html format where the user specifies what local values to output. A pre-defined index keyword can be specified to enumuerate the local values. Two additional kinds of keywords can also be specified (c_ID, f_ID), where a "compute"_compute.html or "fix"_fix.html or "variable"_variable.html provides the values to be output. In each case, the compute or fix must generate local values for input to the "dump local"_dump.html command. Fixes that write output files :h5,link(fixoutput) Several fixes take various quantities as input and can write output files: "fix ave/time"_fix_ave_time.html, "fix ave/chunk"_fix_ave_chunk.html, "fix ave/histo"_fix_ave_histo.html, "fix ave/correlate"_fix_ave_correlate.html, and "fix print"_fix_print.html. The "fix ave/time"_fix_ave_time.html command enables direct output to a file and/or time-averaging of global scalars or vectors. The user specifies one or more quantities as input. These can be global "compute"_compute.html values, global "fix"_fix.html values, or "variables"_variable.html of any style except the atom style which produces per-atom values. Since a variable can refer to keywords used by the "thermo_style custom"_thermo_style.html command (like temp or press) and individual per-atom values, a wide variety of quantities can be time averaged and/or output in this way. If the inputs are one or more scalar values, then the fix generate a global scalar or vector of output. If the inputs are one or more vector values, then the fix generates a global vector or array of output. The time-averaged output of this fix can also be used as input to other output commands. The "fix ave/chunk"_fix_ave_chunk.html command enables direct output to a file of chunk-averaged per-atom quantities like those output in dump files. Chunks can represent spatial bins or other collections of atoms, e.g. individual molecules. The per-atom quantities can be atom density (mass or number) or atom attributes such as position, velocity, force. They can also be per-atom quantities calculated by a "compute"_compute.html, by a "fix"_fix.html, or by an atom-style "variable"_variable.html. The chunk-averaged output of this fix can also be used as input to other output commands. The "fix ave/histo"_fix_ave_histo.html command enables direct output to a file of histogrammed quantities, which can be global or per-atom or local quantities. The histogram output of this fix can also be used as input to other output commands. The "fix ave/correlate"_fix_ave_correlate.html command enables direct output to a file of time-correlated quantities, which can be global values. The correlation matrix output of this fix can also be used as input to other output commands. The "fix print"_fix_print.html command can generate a line of output written to the screen and log file or to a separate file, periodically during a running simulation. The line can contain one or more "variable"_variable.html values for any style variable except the vector or atom styles). As explained above, variables themselves can contain references to global values generated by "thermodynamic keywords"_thermo_style.html, "computes"_compute.html, "fixes"_fix.html, or other "variables"_variable.html, or to per-atom values for a specific atom. Thus the "fix print"_fix_print.html command is a means to output a wide variety of quantities separate from normal thermodynamic or dump file output. Computes that process output quantities :h5,link(computeoutput) The "compute reduce"_compute_reduce.html and "compute reduce/region"_compute_reduce.html commands take one or more per-atom or local vector quantities as inputs and "reduce" them (sum, min, max, ave) to scalar quantities. These are produced as output values which can be used as input to other output commands. The "compute slice"_compute_slice.html command take one or more global vector or array quantities as inputs and extracts a subset of their values to create a new vector or array. These are produced as output values which can be used as input to other output commands. The "compute property/atom"_compute_property_atom.html command takes a list of one or more pre-defined atom attributes (id, x, fx, etc) and stores the values in a per-atom vector or array. These are produced as output values which can be used as input to other output commands. The list of atom attributes is the same as for the "dump custom"_dump.html command. The "compute property/local"_compute_property_local.html command takes a list of one or more pre-defined local attributes (bond info, angle info, etc) and stores the values in a local vector or array. These are produced as output values which can be used as input to other output commands. Fixes that process output quantities :h5,link(fixprocoutput) The "fix vector"_fix_vector.html command can create global vectors as output from global scalars as input, accumulating them one element at a time. The "fix ave/atom"_fix_ave_atom.html command performs time-averaging of per-atom vectors. The per-atom quantities can be atom attributes such as position, velocity, force. They can also be per-atom quantities calculated by a "compute"_compute.html, by a "fix"_fix.html, or by an atom-style "variable"_variable.html. The time-averaged per-atom output of this fix can be used as input to other output commands. The "fix store/state"_fix_store_state.html command can archive one or more per-atom attributes at a particular time, so that the old values can be used in a future calculation or output. The list of atom attributes is the same as for the "dump custom"_dump.html command, including per-atom quantities calculated by a "compute"_compute.html, by a "fix"_fix.html, or by an atom-style "variable"_variable.html. The output of this fix can be used as input to other output commands. Computes that generate values to output :h5,link(compute) Every "compute"_compute.html in LAMMPS produces either global or per-atom or local values. The values can be scalars or vectors or arrays of data. These values can be output using the other commands described in this section. The doc page for each compute command describes what it produces. Computes that produce per-atom or local values have the word "atom" or "local" in their style name. Computes without the word "atom" or "local" produce global values. Fixes that generate values to output :h5,link(fix) Some "fixes"_fix.html in LAMMPS produces either global or per-atom or local values which can be accessed by other commands. The values can be scalars or vectors or arrays of data. These values can be output using the other commands described in this section. The doc page for each fix command tells whether it produces any output quantities and describes them. Variables that generate values to output :h5,link(variable) "Variables"_variable.html defined in an input script can store one or more strings. But equal-style, vector-style, and atom-style or atomfile-style variables generate a global scalar value, global vector or values, or a per-atom vector, resepctively, when accessed. The formulas used to define these variables can contain references to the thermodynamic keywords and to global and per-atom data generated by computes, fixes, and other variables. The values generated by variables can be used as input to and thus output by the other commands described in this section. Summary table of output options and data flow between commands :h5,link(table) This table summarizes the various commands that can be used for generating output from LAMMPS. Each command produces output data of some kind and/or writes data to a file. Most of the commands can take data from other commands as input. Thus you can link many of these commands together in pipeline form, where data produced by one command is used as input to another command and eventually written to the screen or to a file. Note that to hook two commands together the output and input data types must match, e.g. global/per-atom/local data and scalar/vector/array data. Also note that, as described above, when a command takes a scalar as input, that could be an element of a vector or array. Likewise a vector input could be a column of an array. Command: Input: Output: "thermo_style custom"_thermo_style.html: global scalars: screen, log file: "dump custom"_dump.html: per-atom vectors: dump file: "dump local"_dump.html: local vectors: dump file: "fix print"_fix_print.html: global scalar from variable: screen, file: "print"_print.html: global scalar from variable: screen: "computes"_compute.html: N/A: global/per-atom/local scalar/vector/array: "fixes"_fix.html: N/A: global/per-atom/local scalar/vector/array: "variables"_variable.html: global scalars and vectors, per-atom vectors: global scalar and vector, per-atom vector: "compute reduce"_compute_reduce.html: per-atom/local vectors: global scalar/vector: "compute slice"_compute_slice.html: global vectors/arrays: global vector/array: "compute property/atom"_compute_property_atom.html: per-atom vectors: per-atom vector/array: "compute property/local"_compute_property_local.html: local vectors: local vector/array: "fix vector"_fix_vector.html: global scalars: global vector: "fix ave/atom"_fix_ave_atom.html: per-atom vectors: per-atom vector/array: "fix ave/time"_fix_ave_time.html: global scalars/vectors: global scalar/vector/array, file: "fix ave/chunk"_fix_ave_chunk.html: per-atom vectors: global array, file: "fix ave/histo"_fix_ave_histo.html: global/per-atom/local scalars and vectors: global array, file: "fix ave/correlate"_fix_ave_correlate.html: global scalars: global array, file: "fix store/state"_fix_store_state.html: per-atom vectors: per-atom vector/array :tb(c=3,s=:) :line 6.16 Thermostatting, barostatting, and computing temperature :link(howto_16),h4 Thermostatting means controlling the temperature of particles in an MD simulation. Barostatting means controlling the pressure. Since the pressure includes a kinetic component due to particle velocities, both these operations require calculation of the temperature. Typically a target temperature (T) and/or pressure (P) is specified by the user, and the thermostat or barostat attempts to equilibrate the system to the requested T and/or P. Temperature is computed as kinetic energy divided by some number of degrees of freedom (and the Boltzmann constant). Since kinetic energy is a function of particle velocity, there is often a need to distinguish between a particle's advection velocity (due to some aggregate motiion of particles) and its thermal velocity. The sum of the two is the particle's total velocity, but the latter is often what is wanted to compute a temperature. LAMMPS has several options for computing temperatures, any of which can be used in thermostatting and barostatting. These "compute commands"_compute.html calculate temperature, and the "compute pressure"_compute_pressure.html command calculates pressure. "compute temp"_compute_temp.html "compute temp/sphere"_compute_temp_sphere.html "compute temp/asphere"_compute_temp_asphere.html "compute temp/com"_compute_temp_com.html "compute temp/deform"_compute_temp_deform.html "compute temp/partial"_compute_temp_partial.html "compute temp/profile"_compute_temp_profile.html "compute temp/ramp"_compute_temp_ramp.html "compute temp/region"_compute_temp_region.html :ul All but the first 3 calculate velocity biases directly (e.g. advection velocities) that are removed when computing the thermal temperature. "Compute temp/sphere"_compute_temp_sphere.html and "compute temp/asphere"_compute_temp_asphere.html compute kinetic energy for finite-size particles that includes rotational degrees of freedom. They both allow for velocity biases indirectly, via an optional extra argument, another temperature compute that subtracts a velocity bias. This allows the translational velocity of spherical or aspherical particles to be adjusted in prescribed ways. Thermostatting in LAMMPS is performed by "fixes"_fix.html, or in one case by a pair style. Several thermostatting fixes are available: Nose-Hoover (nvt), Berendsen, CSVR, Langevin, and direct rescaling (temp/rescale). Dissipative particle dynamics (DPD) thermostatting can be invoked via the {dpd/tstat} pair style: "fix nvt"_fix_nh.html "fix nvt/sphere"_fix_nvt_sphere.html "fix nvt/asphere"_fix_nvt_asphere.html "fix nvt/sllod"_fix_nvt_sllod.html "fix temp/berendsen"_fix_temp_berendsen.html "fix temp/csvr"_fix_temp_csvr.html "fix langevin"_fix_langevin.html "fix temp/rescale"_fix_temp_rescale.html "pair_style dpd/tstat"_pair_dpd.html :ul "Fix nvt"_fix_nh.html only thermostats the translational velocity of particles. "Fix nvt/sllod"_fix_nvt_sllod.html also does this, except that it subtracts out a velocity bias due to a deforming box and integrates the SLLOD equations of motion. See the "NEMD simulations"_#howto_13 section of this page for further details. "Fix nvt/sphere"_fix_nvt_sphere.html and "fix nvt/asphere"_fix_nvt_asphere.html thermostat not only translation velocities but also rotational velocities for spherical and aspherical particles. DPD thermostatting alters pairwise interactions in a manner analagous to the per-particle thermostatting of "fix langevin"_fix_langevin.html. Any of the thermostatting fixes can use temperature computes that remove bias which has two effects. First, the current calculated temperature, which is compared to the requested target temperature, is caluclated with the velocity bias removed. Second, the thermostat adjusts only the thermal temperature component of the particle's velocities, which are the velocities with the bias removed. The removed bias is then added back to the adjusted velocities. See the doc pages for the individual fixes and for the "fix_modify"_fix_modify.html command for instructions on how to assign a temperature compute to a thermostatting fix. For example, you can apply a thermostat to only the x and z components of velocity by using it in conjunction with "compute temp/partial"_compute_temp_partial.html. Of you could thermostat only the thermal temperature of a streaming flow of particles without affecting the streaming velocity, by using "compute temp/profile"_compute_temp_profile.html. NOTE: Only the nvt fixes perform time integration, meaning they update the velocities and positions of particles due to forces and velocities respectively. The other thermostat fixes only adjust velocities; they do NOT perform time integration updates. Thus they should be used in conjunction with a constant NVE integration fix such as these: "fix nve"_fix_nve.html "fix nve/sphere"_fix_nve_sphere.html "fix nve/asphere"_fix_nve_asphere.html :ul Barostatting in LAMMPS is also performed by "fixes"_fix.html. Two barosttating methods are currently available: Nose-Hoover (npt and nph) and Berendsen: "fix npt"_fix_nh.html "fix npt/sphere"_fix_npt_sphere.html "fix npt/asphere"_fix_npt_asphere.html "fix nph"_fix_nh.html "fix press/berendsen"_fix_press_berendsen.html :ul The "fix npt"_fix_nh.html commands include a Nose-Hoover thermostat and barostat. "Fix nph"_fix_nh.html is just a Nose/Hoover barostat; it does no thermostatting. Both "fix nph"_fix_nh.html and "fix press/bernendsen"_fix_press_berendsen.html can be used in conjunction with any of the thermostatting fixes. As with the thermostats, "fix npt"_fix_nh.html and "fix nph"_fix_nh.html only use translational motion of the particles in computing T and P and performing thermo/barostatting. "Fix npt/sphere"_fix_npt_sphere.html and "fix npt/asphere"_fix_npt_asphere.html thermo/barostat using not only translation velocities but also rotational velocities for spherical and aspherical particles. All of the barostatting fixes use the "compute pressure"_compute_pressure.html compute to calculate a current pressure. By default, this compute is created with a simple "compute temp"_compute_temp.html (see the last argument of the "compute pressure"_compute_pressure.html command), which is used to calculated the kinetic component of the pressure. The barostatting fixes can also use temperature computes that remove bias for the purpose of computing the kinetic component which contributes to the current pressure. See the doc pages for the individual fixes and for the "fix_modify"_fix_modify.html command for instructions on how to assign a temperature or pressure compute to a barostatting fix. NOTE: As with the thermostats, the Nose/Hoover methods ("fix npt"_fix_nh.html and "fix nph"_fix_nh.html) perform time integration. "Fix press/berendsen"_fix_press_berendsen.html does NOT, so it should be used with one of the constant NVE fixes or with one of the NVT fixes. Finally, thermodynamic output, which can be setup via the "thermo_style"_thermo_style.html command, often includes temperature and pressure values. As explained on the doc page for the "thermo_style"_thermo_style.html command, the default T and P are setup by the thermo command itself. They are NOT the ones associated with any thermostatting or barostatting fix you have defined or with any compute that calculates a temperature or pressure. Thus if you want to view these values of T and P, you need to specify them explicitly via a "thermo_style custom"_thermo_style.html command. Or you can use the "thermo_modify"_thermo_modify.html command to re-define what temperature or pressure compute is used for default thermodynamic output. :line 6.17 Walls :link(howto_17),h4 Walls in an MD simulation are typically used to bound particle motion, i.e. to serve as a boundary condition. Walls in LAMMPS can be of rough (made of particles) or idealized surfaces. Ideal walls can be smooth, generating forces only in the normal direction, or frictional, generating forces also in the tangential direction. Rough walls, built of particles, can be created in various ways. The particles themselves can be generated like any other particle, via the "lattice"_lattice.html and "create_atoms"_create_atoms.html commands, or read in via the "read_data"_read_data.html command. Their motion can be constrained by many different commands, so that they do not move at all, move together as a group at constant velocity or in response to a net force acting on them, move in a prescribed fashion (e.g. rotate around a point), etc. Note that if a time integration fix like "fix nve"_fix_nve.html or "fix nvt"_fix_nh.html is not used with the group that contains wall particles, their positions and velocities will not be updated. "fix aveforce"_fix_aveforce.html - set force on particles to average value, so they move together "fix setforce"_fix_setforce.html - set force on particles to a value, e.g. 0.0 "fix freeze"_fix_freeze.html - freeze particles for use as granular walls "fix nve/noforce"_fix_nve_noforce.html - advect particles by their velocity, but without force "fix move"_fix_move.html - prescribe motion of particles by a linear velocity, oscillation, rotation, variable :ul The "fix move"_fix_move.html command offers the most generality, since the motion of individual particles can be specified with "variable"_variable.html formula which depends on time and/or the particle position. For rough walls, it may be useful to turn off pairwise interactions between wall particles via the "neigh_modify exclude"_neigh_modify.html command. Rough walls can also be created by specifying frozen particles that do not move and do not interact with mobile particles, and then tethering other particles to the fixed particles, via a "bond"_bond_style.html. The bonded particles do interact with other mobile particles. Idealized walls can be specified via several fix commands. "Fix wall/gran"_fix_wall_gran.html creates frictional walls for use with granular particles; all the other commands create smooth walls. "fix wall/reflect"_fix_wall_reflect.html - reflective flat walls "fix wall/lj93"_fix_wall.html - flat walls, with Lennard-Jones 9/3 potential "fix wall/lj126"_fix_wall.html - flat walls, with Lennard-Jones 12/6 potential "fix wall/colloid"_fix_wall.html - flat walls, with "pair_style colloid"_pair_colloid.html potential "fix wall/harmonic"_fix_wall.html - flat walls, with repulsive harmonic spring potential "fix wall/region"_fix_wall_region.html - use region surface as wall "fix wall/gran"_fix_wall_gran.html - flat or curved walls with "pair_style granular"_pair_gran.html potential :ul The {lj93}, {lj126}, {colloid}, and {harmonic} styles all allow the flat walls to move with a constant velocity, or oscillate in time. The "fix wall/region"_fix_wall_region.html command offers the most generality, since the region surface is treated as a wall, and the geometry of the region can be a simple primitive volume (e.g. a sphere, or cube, or plane), or a complex volume made from the union and intersection of primitive volumes. "Regions"_region.html can also specify a volume "interior" or "exterior" to the specified primitive shape or {union} or {intersection}. "Regions"_region.html can also be "dynamic" meaning they move with constant velocity, oscillate, or rotate. The only frictional idealized walls currently in LAMMPS are flat or curved surfaces specified by the "fix wall/gran"_fix_wall_gran.html command. At some point we plan to allow regoin surfaces to be used as frictional walls, as well as triangulated surfaces. :line 6.18 Elastic constants :link(howto_18),h4 Elastic constants characterize the stiffness of a material. The formal definition is provided by the linear relation that holds between the stress and strain tensors in the limit of infinitesimal deformation. In tensor notation, this is expressed as s_ij = C_ijkl * e_kl, where the repeated indices imply summation. s_ij are the elements of the symmetric stress tensor. e_kl are the elements of the symmetric strain tensor. C_ijkl are the elements of the fourth rank tensor of elastic constants. In three dimensions, this tensor has 3^4=81 elements. Using Voigt notation, the tensor can be written as a 6x6 matrix, where C_ij is now the derivative of s_i w.r.t. e_j. Because s_i is itself a derivative w.r.t. e_i, it follows that C_ij is also symmetric, with at most 7*6/2 = 21 distinct elements. At zero temperature, it is easy to estimate these derivatives by deforming the simulation box in one of the six directions using the "change_box"_change_box.html command and measuring the change in the stress tensor. A general-purpose script that does this is given in the examples/elastic directory described in "this section"_Section_example.html. Calculating elastic constants at finite temperature is more challenging, because it is necessary to run a simulation that perfoms time averages of differential properties. One way to do this is to measure the change in average stress tensor in an NVT simulations when the cell volume undergoes a finite deformation. In order to balance the systematic and statistical errors in this method, the magnitude of the deformation must be chosen judiciously, and care must be taken to fully equilibrate the deformed cell before sampling the stress tensor. Another approach is to sample the triclinic cell fluctuations that occur in an NPT simulation. This method can also be slow to converge and requires careful post-processing "(Shinoda)"_#Shinoda :line 6.19 Library interface to LAMMPS :link(howto_19),h4 As described in "Section 2.5"_Section_start.html#start_5, LAMMPS can be built as a library, so that it can be called by another code, used in a "coupled manner"_Section_howto.html#howto_10 with other codes, or driven through a "Python interface"_Section_python.html. All of these methodologies use a C-style interface to LAMMPS that is provided in the files src/library.cpp and src/library.h. The functions therein have a C-style argument list, but contain C++ code you could write yourself in a C++ application that was invoking LAMMPS directly. The C++ code in the functions illustrates how to invoke internal LAMMPS operations. Note that LAMMPS classes are defined within a LAMMPS namespace (LAMMPS_NS) if you use them from another C++ application. Library.cpp contains these functions for creating and destroying an instance of LAMMPS and sending it commands to execute. See the documentation in the src/library.cpp file for details: void lammps_open(int, char **, MPI_Comm, void **) void lammps_open_no_mpi(int, char **, void **) void lammps_close(void *) int lammps_version(void *) void lammps_file(void *, char *) char *lammps_command(void *, char *) void lammps_commands_list(void *, int, char **) void lammps_commands_string(void *, char *) void lammps_free(void *) :pre The lammps_open() function is used to initialize LAMMPS, passing in a list of strings as if they were "command-line arguments"_Section_start.html#start_7 when LAMMPS is run in stand-alone mode from the command line, and a MPI communicator for LAMMPS to run under. It returns a ptr to the LAMMPS object that is created, and which is used in subsequent library calls. The lammps_open() function can be called multiple times, to create multiple instances of LAMMPS. LAMMPS will run on the set of processors in the communicator. This means the calling code can run LAMMPS on all or a subset of processors. For example, a wrapper script might decide to alternate between LAMMPS and another code, allowing them both to run on all the processors. Or it might allocate half the processors to LAMMPS and half to the other code and run both codes simultaneously before syncing them up periodically. Or it might instantiate multiple instances of LAMMPS to perform different calculations. The lammps_open_no_mpi() function is similar except that no MPI communicator is passed from the caller. Instead, MPI_COMM_WORLD is used to instantiate LAMMPS, and MPI is initialzed if necessary. The lammps_close() function is used to shut down an instance of LAMMPS and free all its memory. The lammps_version() function can be used to determined the specific version of the underlying LAMMPS code. This is particularly useful when loading LAMMPS as a shared library via dlopen(). The code using the library interface can than use this information to adapt to changes to the LAMMPS command syntax between versions. The returned LAMMPS version code is an integer (e.g. 2 Sep 2015 results in 20150902) that grows with every new LAMMPS version. The lammps_file(), lammps_command(), lammps_commands_list(), and lammps_commands_string() functions are used to pass one or more commands to LAMMPS to execute, the same as if they were coming from an input script. Via these functions, the calling code can read or generate a series of LAMMPS commands one or multiple at a time and pass it thru the library interface to setup a problem and then run it in stages. The caller can interleave the command function calls with operations it performs, calls to extract information from or set information within LAMMPS, or calls to another code's library. The lammps_file() function passes the filename of an input script. The lammps_command() function passes a single command as a string. The lammps_commands_list() function passes multiple commands in a char** list. In both lammps_command() and lammps_commands_list(), individual commands may or may not have a trailing newline. The lammps_commands_string() function passes multiple commands concatenated into one long string, separated by newline characters. In both lammps_commands_list() and lammps_commands_string(), a single command can be spread across multiple lines, if the last printable character of all but the last line is "&", the same as if the lines appeared in an input script. The lammps_free() function is a clean-up function to free memory that the library allocated previously via other function calls. See comments in src/library.cpp file for which other functions need this clean-up. Library.cpp also contains these functions for extracting information from LAMMPS and setting value within LAMMPS. Again, see the documentation in the src/library.cpp file for details, including which quantities can be queried by name: void *lammps_extract_global(void *, char *) void *lammps_extract_atom(void *, char *) void *lammps_extract_compute(void *, char *, int, int) void *lammps_extract_fix(void *, char *, int, int, int, int) void *lammps_extract_variable(void *, char *, char *) :pre int lammps_set_variable(void *, char *, char *) double lammps_get_thermo(void *, char *) :pre int lammps_get_natoms(void *) void lammps_gather_atoms(void *, double *) void lammps_scatter_atoms(void *, double *) :pre void lammps_create_atoms(void *, int, tagint *, int *, double *, double *) :pre The extract functions return a pointer to various global or per-atom quantities stored in LAMMPS or to values calculated by a compute, fix, or variable. The pointer returned by the extract_global() function can be used as a permanent reference to a value which may change. For the other extract functions, the underlying storage may be reallocated as LAMMPS runs, so you need to re-call the function to assure a current pointer or returned value(s). The lammps_set_variable() function can set an existing string-style variable to a new string value, so that subsequent LAMMPS commands can access the variable. The lammps_get_thermo() function returns the current value of a thermo keyword as a double. The lammps_get_natoms() function returns the total number of atoms in the system and can be used by the caller to allocate space for the lammps_gather_atoms() and lammps_scatter_atoms() functions. The gather function collects atom info of the requested type (atom coords, types, forces, etc) from all procsesors, orders them by atom ID, and returns a full list to each calling processor. The scatter function does the inverse. It distributes the same kinds of values, passed by the caller, to each atom owned by individual processors. The lammps_create_atoms() function takes a list of N atoms as input with atom types and coords (required), an optionally atom IDs and velocities. It uses the coords of each atom to assign it as a new atom to the processor that owns it. Additional properties for the new atoms can be assigned via the lammps_scatter_atoms() or lammps_extract_atom() functions. The examples/COUPLE and python directories have example C++ and C and Python codes which show how a driver code can link to LAMMPS as a library, run LAMMPS on a subset of processors, grab data from LAMMPS, change it, and put it back into LAMMPS. NOTE: You can write code for additional functions as needed to define how your code talks to LAMMPS and add them to src/library.cpp and src/library.h, as well as to the "Python interface"_Section_python.html. The added functions can access or change any LAMMPS data you wish. :line 6.20 Calculating thermal conductivity :link(howto_20),h4 The thermal conductivity kappa of a material can be measured in at least 4 ways using various options in LAMMPS. See the examples/KAPPA directory for scripts that implement the 4 methods discussed here for a simple Lennard-Jones fluid model. Also, see "this section"_Section_howto.html#howto_21 of the manual for an analogous discussion for viscosity. The thermal conducitivity tensor kappa is a measure of the propensity of a material to transmit heat energy in a diffusive manner as given by Fourier's law J = -kappa grad(T) where J is the heat flux in units of energy per area per time and grad(T) is the spatial gradient of temperature. The thermal conductivity thus has units of energy per distance per time per degree K and is often approximated as an isotropic quantity, i.e. as a scalar. The first method is to setup two thermostatted regions at opposite ends of a simulation box, or one in the middle and one at the end of a periodic box. By holding the two regions at different temperatures with a "thermostatting fix"_Section_howto.html#howto_13, the energy added to the hot region should equal the energy subtracted from the cold region and be proportional to the heat flux moving between the regions. See the papers by "Ikeshoji and Hafskjold"_#howto-Ikeshoji and "Wirnsberger et al"_#howto-Wirnsberger for details of this idea. Note that thermostatting fixes such as "fix nvt"_fix_nh.html, "fix langevin"_fix_langevin.html, and "fix temp/rescale"_fix_temp_rescale.html store the cumulative energy they add/subtract. Alternatively, as a second method, the "fix heat"_fix_heat.html or "fix ehex"_fix_ehex.html commands can be used in place of thermostats on each of two regions to add/subtract specified amounts of energy to both regions. In both cases, the resulting temperatures of the two regions can be monitored with the "compute temp/region" command and the temperature profile of the intermediate region can be monitored with the "fix ave/chunk"_fix_ave_chunk.html and "compute ke/atom"_compute_ke_atom.html commands. The third method is to perform a reverse non-equilibrium MD simulation using the "fix thermal/conductivity"_fix_thermal_conductivity.html command which implements the rNEMD algorithm of Muller-Plathe. Kinetic energy is swapped between atoms in two different layers of the simulation box. This induces a temperature gradient between the two layers which can be monitored with the "fix ave/chunk"_fix_ave_chunk.html and "compute ke/atom"_compute_ke_atom.html commands. The fix tallies the cumulative energy transfer that it performs. See the "fix thermal/conductivity"_fix_thermal_conductivity.html command for details. The fourth method is based on the Green-Kubo (GK) formula which relates the ensemble average of the auto-correlation of the heat flux to kappa. The heat flux can be calculated from the fluctuations of per-atom potential and kinetic energies and per-atom stress tensor in a steady-state equilibrated simulation. This is in contrast to the two preceding non-equilibrium methods, where energy flows continuously between hot and cold regions of the simulation box. The "compute heat/flux"_compute_heat_flux.html command can calculate the needed heat flux and describes how to implement the Green_Kubo formalism using additional LAMMPS commands, such as the "fix ave/correlate"_fix_ave_correlate.html command to calculate the needed auto-correlation. See the doc page for the "compute heat/flux"_compute_heat_flux.html command for an example input script that calculates the thermal conductivity of solid Ar via the GK formalism. :line 6.21 Calculating viscosity :link(howto_21),h4 The shear viscosity eta of a fluid can be measured in at least 5 ways using various options in LAMMPS. See the examples/VISCOSITY directory for scripts that implement the 5 methods discussed here for a simple Lennard-Jones fluid model. Also, see "this section"_Section_howto.html#howto_20 of the manual for an analogous discussion for thermal conductivity. Eta is a measure of the propensity of a fluid to transmit momentum in a direction perpendicular to the direction of velocity or momentum flow. Alternatively it is the resistance the fluid has to being sheared. It is given by J = -eta grad(Vstream) where J is the momentum flux in units of momentum per area per time. and grad(Vstream) is the spatial gradient of the velocity of the fluid moving in another direction, normal to the area through which the momentum flows. Viscosity thus has units of pressure-time. The first method is to perform a non-equlibrium MD (NEMD) simulation by shearing the simulation box via the "fix deform"_fix_deform.html command, and using the "fix nvt/sllod"_fix_nvt_sllod.html command to thermostat the fluid via the SLLOD equations of motion. Alternatively, as a second method, one or more moving walls can be used to shear the fluid in between them, again with some kind of thermostat that modifies only the thermal (non-shearing) components of velocity to prevent the fluid from heating up. In both cases, the velocity profile setup in the fluid by this procedure can be monitored by the "fix ave/chunk"_fix_ave_chunk.html command, which determines grad(Vstream) in the equation above. E.g. the derivative in the y-direction of the Vx component of fluid motion or grad(Vstream) = dVx/dy. The Pxy off-diagonal component of the pressure or stress tensor, as calculated by the "compute pressure"_compute_pressure.html command, can also be monitored, which is the J term in the equation above. See "this section"_Section_howto.html#howto_13 of the manual for details on NEMD simulations. The third method is to perform a reverse non-equilibrium MD simulation using the "fix viscosity"_fix_viscosity.html command which implements the rNEMD algorithm of Muller-Plathe. Momentum in one dimension is swapped between atoms in two different layers of the simulation box in a different dimension. This induces a velocity gradient which can be monitored with the "fix ave/chunk"_fix_ave_chunk.html command. The fix tallies the cummulative momentum transfer that it performs. See the "fix viscosity"_fix_viscosity.html command for details. The fourth method is based on the Green-Kubo (GK) formula which relates the ensemble average of the auto-correlation of the stress/pressure tensor to eta. This can be done in a fully equilibrated simulation which is in contrast to the two preceding non-equilibrium methods, where momentum flows continuously through the simulation box. Here is an example input script that calculates the viscosity of liquid Ar via the GK formalism: # Sample LAMMPS input script for viscosity of liquid Ar :pre units real variable T equal 86.4956 variable V equal vol variable dt equal 4.0 variable p equal 400 # correlation length variable s equal 5 # sample interval variable d equal $p*$s # dump interval :pre # convert from LAMMPS real units to SI :pre variable kB equal 1.3806504e-23 # \[J/K/] Boltzmann variable atm2Pa equal 101325.0 variable A2m equal 1.0e-10 variable fs2s equal 1.0e-15 variable convert equal $\{atm2Pa\}*$\{atm2Pa\}*$\{fs2s\}*$\{A2m\}*$\{A2m\}*$\{A2m\} :pre # setup problem :pre dimension 3 boundary p p p lattice fcc 5.376 orient x 1 0 0 orient y 0 1 0 orient z 0 0 1 region box block 0 4 0 4 0 4 create_box 1 box create_atoms 1 box mass 1 39.948 pair_style lj/cut 13.0 pair_coeff * * 0.2381 3.405 timestep $\{dt\} thermo $d :pre # equilibration and thermalization :pre velocity all create $T 102486 mom yes rot yes dist gaussian fix NVT all nvt temp $T $T 10 drag 0.2 run 8000 :pre # viscosity calculation, switch to NVE if desired :pre #unfix NVT #fix NVE all nve :pre reset_timestep 0 variable pxy equal pxy variable pxz equal pxz variable pyz equal pyz fix SS all ave/correlate $s $p $d & v_pxy v_pxz v_pyz type auto file S0St.dat ave running variable scale equal $\{convert\}/($\{kB\}*$T)*$V*$s*$\{dt\} variable v11 equal trap(f_SS\[3\])*$\{scale\} variable v22 equal trap(f_SS\[4\])*$\{scale\} variable v33 equal trap(f_SS\[5\])*$\{scale\} thermo_style custom step temp press v_pxy v_pxz v_pyz v_v11 v_v22 v_v33 run 100000 variable v equal (v_v11+v_v22+v_v33)/3.0 variable ndens equal count(all)/vol print "average viscosity: $v \[Pa.s\] @ $T K, $\{ndens\} /A^3" :pre The fifth method is related to the above Green-Kubo method, but uses the Einstein formulation, analogous to the Einstein mean-square-displacement formulation for self-diffusivity. The time-integrated momentum fluxes play the role of Cartesian coordinates, whose mean-square displacement increases linearly with time at sufficiently long times. :line 6.22 Calculating a diffusion coefficient :link(howto_22),h4 The diffusion coefficient D of a material can be measured in at least 2 ways using various options in LAMMPS. See the examples/DIFFUSE directory for scripts that implement the 2 methods discussed here for a simple Lennard-Jones fluid model. The first method is to measure the mean-squared displacement (MSD) of the system, via the "compute msd"_compute_msd.html command. The slope of the MSD versus time is proportional to the diffusion coefficient. The instantaneous MSD values can be accumulated in a vector via the "fix vector"_fix_vector.html command, and a line fit to the vector to compute its slope via the "variable slope"_variable.html function, and thus extract D. The second method is to measure the velocity auto-correlation function (VACF) of the system, via the "compute vacf"_compute_vacf.html command. The time-integral of the VACF is proportional to the diffusion coefficient. The instantaneous VACF values can be accumulated in a vector via the "fix vector"_fix_vector.html command, and time integrated via the "variable trap"_variable.html function, and thus extract D. :line 6.23 Using chunks to calculate system properties :link(howto_23),h4 In LAMMS, "chunks" are collections of atoms, as defined by the "compute chunk/atom"_compute_chunk_atom.html command, which assigns each atom to a chunk ID (or to no chunk at all). The number of chunks and the assignment of chunk IDs to atoms can be static or change over time. Examples of "chunks" are molecules or spatial bins or atoms with similar values (e.g. coordination number or potential energy). The per-atom chunk IDs can be used as input to two other kinds of commands, to calculate various properties of a system: "fix ave/chunk"_fix_ave_chunk.html any of the "compute */chunk"_compute.html commands :ul Here, each of the 3 kinds of chunk-related commands is briefly overviewed. Then some examples are given of how to compute different properties with chunk commands. Compute chunk/atom command: :h5 This compute can assign atoms to chunks of various styles. Only atoms in the specified group and optional specified region are assigned to a chunk. Here are some possible chunk definitions: atoms in same molecule | chunk ID = molecule ID | atoms of same atom type | chunk ID = atom type | all atoms with same atom property (charge, radius, etc) | chunk ID = output of compute property/atom | atoms in same cluster | chunk ID = output of "compute cluster/atom"_compute_cluster_atom.html command | atoms in same spatial bin | chunk ID = bin ID | atoms in same rigid body | chunk ID = molecule ID used to define rigid bodies | atoms with similar potential energy | chunk ID = output of "compute pe/atom"_compute_pe_atom.html | atoms with same local defect structure | chunk ID = output of "compute centro/atom"_compute_centro_atom.html or "compute coord/atom"_compute_coord_atom.html command :tb(s=|,c=2) Note that chunk IDs are integer values, so for atom properties or computes that produce a floating point value, they will be truncated to an integer. You could also use the compute in a variable that scales the floating point value to spread it across multiple intergers. Spatial bins can be of various kinds, e.g. 1d bins = slabs, 2d bins = pencils, 3d bins = boxes, spherical bins, cylindrical bins. This compute also calculates the number of chunks {Nchunk}, which is used by other commands to tally per-chunk data. {Nchunk} can be a static value or change over time (e.g. the number of clusters). The chunk ID for an individual atom can also be static (e.g. a molecule ID), or dynamic (e.g. what spatial bin an atom is in as it moves). Note that this compute allows the per-atom output of other "computes"_compute.html, "fixes"_fix.html, and "variables"_variable.html to be used to define chunk IDs for each atom. This means you can write your own compute or fix to output a per-atom quantity to use as chunk ID. See "Section 10"_Section_modify.html of the documentation for how to do this. You can also define a "per-atom variable"_variable.html in the input script that uses a formula to generate a chunk ID for each atom. Fix ave/chunk command: :h5 This fix takes the ID of a "compute chunk/atom"_compute_chunk_atom.html command as input. For each chunk, it then sums one or more specified per-atom values over the atoms in each chunk. The per-atom values can be any atom property, such as velocity, force, charge, potential energy, kinetic energy, stress, etc. Additional keywords are defined for per-chunk properties like density and temperature. More generally any per-atom value generated by other "computes"_compute.html, "fixes"_fix.html, and "per-atom variables"_variable.html, can be summed over atoms in each chunk. Similar to other averaging fixes, this fix allows the summed per-chunk values to be time-averaged in various ways, and output to a file. The fix produces a global array as output with one row of values per chunk. Compute */chunk commands: :h5 Currently the following computes operate on chunks of atoms to produce per-chunk values. "compute com/chunk"_compute_com_chunk.html "compute gyration/chunk"_compute_gyration_chunk.html "compute inertia/chunk"_compute_inertia_chunk.html "compute msd/chunk"_compute_msd_chunk.html "compute property/chunk"_compute_property_chunk.html "compute temp/chunk"_compute_temp_chunk.html "compute torque/chunk"_compute_vcm_chunk.html "compute vcm/chunk"_compute_vcm_chunk.html :ul They each take the ID of a "compute chunk/atom"_compute_chunk_atom.html command as input. As their names indicate, they calculate the center-of-mass, radius of gyration, moments of inertia, mean-squared displacement, temperature, torque, and velocity of center-of-mass for each chunk of atoms. The "compute property/chunk"_compute_property_chunk.html command can tally the count of atoms in each chunk and extract other per-chunk properties. The reason these various calculations are not part of the "fix ave/chunk command"_fix_ave_chunk.html, is that each requires a more complicated operation than simply summing and averaging over per-atom values in each chunk. For example, many of them require calculation of a center of mass, which requires summing mass*position over the atoms and then dividing by summed mass. All of these computes produce a global vector or global array as output, wih one or more values per chunk. They can be used in various ways: As input to the "fix ave/time"_fix_ave_time.html command, which can write the values to a file and optionally time average them. :ulb,l As input to the "fix ave/histo"_fix_ave_histo.html command to histogram values across chunks. E.g. a histogram of cluster sizes or molecule diffusion rates. :l As input to special functions of "equal-style variables"_variable.html, like sum() and max(). E.g. to find the largest cluster or fastest diffusing molecule. :l :ule Example calculations with chunks :h5 Here are eaxmples using chunk commands to calculate various properties: (1) Average velocity in each of 1000 2d spatial bins: compute cc1 all chunk/atom bin/2d x 0.0 0.1 y lower 0.01 units reduced fix 1 all ave/chunk 100 10 1000 cc1 vx vy file tmp.out :pre (2) Temperature in each spatial bin, after subtracting a flow velocity: compute cc1 all chunk/atom bin/2d x 0.0 0.1 y lower 0.1 units reduced compute vbias all temp/profile 1 0 0 y 10 fix 1 all ave/chunk 100 10 1000 cc1 temp bias vbias file tmp.out :pre (3) Center of mass of each molecule: compute cc1 all chunk/atom molecule compute myChunk all com/chunk cc1 fix 1 all ave/time 100 1 100 c_myChunk\[*\] file tmp.out mode vector :pre (4) Total force on each molecule and ave/max across all molecules: compute cc1 all chunk/atom molecule fix 1 all ave/chunk 1000 1 1000 cc1 fx fy fz file tmp.out variable xave equal ave(f_1\[2\]) variable xmax equal max(f_1\[2\]) thermo 1000 thermo_style custom step temp v_xave v_xmax :pre (5) Histogram of cluster sizes: compute cluster all cluster/atom 1.0 compute cc1 all chunk/atom c_cluster compress yes compute size all property/chunk cc1 count fix 1 all ave/histo 100 1 100 0 20 20 c_size mode vector ave running beyond ignore file tmp.histo :pre :line 6.24 Setting parameters for the "kspace_style pppm/disp"_kspace_style.html command :link(howto_24),h4 The PPPM method computes interactions by splitting the pair potential into two parts, one of which is computed in a normal pairwise fashion, the so-called real-space part, and one of which is computed using the Fourier transform, the so called reciprocal-space or kspace part. For both parts, the potential is not computed exactly but is approximated. Thus, there is an error in both parts of the computation, the real-space and the kspace error. The just mentioned facts are true both for the PPPM for Coulomb as well as dispersion interactions. The deciding difference - and also the reason why the parameters for pppm/disp have to be selected with more care - is the impact of the errors on the results: The kspace error of the PPPM for Coulomb and dispersion interaction and the real-space error of the PPPM for Coulomb interaction have the character of noise. In contrast, the real-space error of the PPPM for dispersion has a clear physical interpretation: the underprediction of cohesion. As a consequence, the real-space error has a much stronger effect than the kspace error on simulation results for pppm/disp. Parameters must thus be chosen in a way that this error is much smaller than the kspace error. When using pppm/disp and not making any specifications on the PPPM parameters via the kspace modify command, parameters will be tuned such that the real-space error and the kspace error are equal. This will result in simulations that are either inaccurate or slow, both of which is not desirable. For selecting parameters for the pppm/disp that provide fast and accurate simulations, there are two approaches, which both have their up- and downsides. The first approach is to set desired real-space an kspace accuracies via the {kspace_modify force/disp/real} and {kspace_modify force/disp/kspace} commands. Note that the accuracies have to be specified in force units and are thus dependend on the chosen unit settings. For real units, 0.0001 and 0.002 seem to provide reasonable accurate and efficient computations for the real-space and kspace accuracies. 0.002 and 0.05 work well for most systems using lj units. PPPM parameters will be generated based on the desired accuracies. The upside of this approach is that it usually provides a good set of parameters and will work for both the {kspace_modify diff ad} and {kspace_modify diff ik} options. The downside of the method is that setting the PPPM parameters will take some time during the initialization of the simulation. The second approach is to set the parameters for the pppm/disp explicitly using the {kspace_modify mesh/disp}, {kspace_modify order/disp}, and {kspace_modify gewald/disp} commands. This approach requires a more experienced user who understands well the impact of the choice of parameters on the simulation accuracy and performance. This approach provides a fast initialization of the simulation. However, it is sensitive to errors: A combination of parameters that will perform well for one system might result in far-from-optimal conditions for other simulations. For example, parametes that provide accurate and fast computations for all-atomistic force fields can provide insufficient accuracy or united-atomistic force fields (which is related to that the latter typically have larger dispersion coefficients). To avoid inaccurate or inefficient simulations, the pppm/disp stops simulations with an error message if no action is taken to control the PPPM parameters. If the automatic parameter generation is desired and real-space and kspace accuracies are desired to be equal, this error message can be suppressed using the {kspace_modify disp/auto yes} command. A reasonable approach that combines the upsides of both methods is to make the first run using the {kspace_modify force/disp/real} and {kspace_modify force/disp/kspace} commands, write down the PPPM parameters from the outut, and specify these parameters using the second approach in subsequent runs (which have the same composition, force field, and approximately the same volume). Concerning the performance of the pppm/disp there are two more things to consider. The first is that when using the pppm/disp, the cutoff parameter does no longer affect the accuracy of the simulation (subject to that gewald/disp is adjusted when changing the cutoff). The performance can thus be increased by examining different values for the cutoff parameter. A lower bound for the cutoff is only set by the truncation error of the repulsive term of pair potentials. The second is that the mixing rule of the pair style has an impact on the computation time when using the pppm/disp. Fastest computations are achieved when using the geometric mixing rule. Using the arithmetic mixing rule substantially increases the computational cost. The computational overhead can be reduced using the {kspace_modify mix/disp geom} and {kspace_modify splittol} commands. The first command simply enforces geometric mixing of the dispersion coeffiecients in kspace computations. This introduces some error in the computations but will also significantly speed-up the simulations. The second keyword sets the accuracy with which the dispersion coefficients are approximated using a matrix factorization approach. This may result in better accuracy then using the first command, but will usually also not provide an equally good increase of efficiency. Finally, pppm/disp can also be used when no mixing rules apply. This can be achieved using the {kspace_modify mix/disp none} command. Note that the code does not check automatically whether any mixing rule is fulfilled. If mixing rules do not apply, the user will have to specify this command explicitly. :line 6.25 Polarizable models :link(howto_25),h4 In polarizable force fields the charge distributions in molecules and materials respond to their electrostatic environements. Polarizable systems can be simulated in LAMMPS using three methods: the fluctuating charge method, implemented in the "QEQ"_fix_qeq.html package, :ulb,l the adiabatic core-shell method, implemented in the "CORESHELL"_#howto_26 package, :l the thermalized Drude dipole method, implemented in the "USER-DRUDE"_#howto_27 package. :l :ule The fluctuating charge method calculates instantaneous charges on interacting atoms based on the electronegativity equalization principle. It is implemented in the "fix qeq"_fix_qeq.html which is available in several variants. It is a relatively efficient technique since no additional particles are introduced. This method allows for charge transfer between molecules or atom groups. However, because the charges are located at the interaction sites, off-plane components of polarization cannot be represented in planar molecules or atom groups. The two other methods share the same basic idea: polarizable atoms are split into one core atom and one satellite particle (called shell or Drude particle) attached to it by a harmonic spring. Both atoms bear a charge and they represent collectively an induced electric dipole. These techniques are computationally more expensive than the QEq method because of additional particles and bonds. These two charge-on-spring methods differ in certain features, with the core-shell model being normally used for ionic/crystalline materials, whereas the so-called Drude model is normally used for molecular systems and fluid states. The core-shell model is applicable to crystalline materials where the high symmetry around each site leads to stable trajectories of the core-shell pairs. However, bonded atoms in molecules can be so close that a core would interact too strongly or even capture the Drude particle of a neighbor. The Drude dipole model is relatively more complex in order to remediate this and other issues. Specifically, the Drude model includes specific thermostating of the core-Drude pairs and short-range damping of the induced dipoles. The three polarization methods can be implemented through a self-consistent calculation of charges or induced dipoles at each timestep. In the fluctuating charge scheme this is done by the matrix inversion method in "fix qeq/point"_fix_qeq.html, but for core-shell or Drude-dipoles the relaxed-dipoles technique would require an slow iterative procedure. These self-consistent solutions yield accurate trajectories since the additional degrees of freedom representing polarization are massless. An alternative is to attribute a mass to the additional degrees of freedom and perform time integration using an extended Lagrangian technique. For the fluctuating charge scheme this is done by "fix qeq/dynamic"_fix_qeq.html, and for the charge-on-spring models by the methods outlined in the next two sections. The assignment of masses to the additional degrees of freedom can lead to unphysical trajectories if care is not exerted in choosing the parameters of the poarizable models and the simulation conditions. In the core-shell model the vibration of the shells is kept faster than the ionic vibrations to mimic the fast response of the polarizable electrons. But in molecular systems thermalizing the core-Drude pairs at temperatures comparable to the rest of the simulation leads to several problems (kinetic energy transfer, too short a timestep, etc.) In order to avoid these problems the relative motion of the Drude particles with respect to their cores is kept "cold" so the vibration of the core-Drude pairs is very slow, approaching the self-consistent regime. In both models the temperature is regulated using the velocities of the center of mass of core+shell (or Drude) pairs, but in the Drude model the actual relative core-Drude particle motion is thermostated separately as well. :line 6.26 Adiabatic core/shell model :link(howto_26),h4 The adiabatic core-shell model by "Mitchell and Finchham"_#MitchellFinchham is a simple method for adding polarizability to a system. In order to mimic the electron shell of an ion, a satellite particle is attached to it. This way the ions are split into a core and a shell where the latter is meant to react to the electrostatic environment inducing polarizability. Technically, shells are attached to the cores by a spring force f = k*r where k is a parametrized spring constant and r is the distance between the core and the shell. The charges of the core and the shell add up to the ion charge, thus q(ion) = q(core) + q(shell). This setup introduces the ion polarizability (alpha) given by alpha = q(shell)^2 / k. In a similar fashion the mass of the ion is distributed on the core and the shell with the core having the larger mass. To run this model in LAMMPS, "atom_style"_atom_style.html {full} can be used since atom charge and bonds are needed. Each kind of core/shell pair requires two atom types and a bond type. The core and shell of a core/shell pair should be bonded to each other with a harmonic bond that provides the spring force. For example, a data file for NaCl, as found in examples/coreshell, has this format: 432 atoms # core and shell atoms 216 bonds # number of core/shell springs :pre 4 atom types # 2 cores and 2 shells for Na and Cl 2 bond types :pre 0.0 24.09597 xlo xhi 0.0 24.09597 ylo yhi 0.0 24.09597 zlo zhi :pre Masses # core/shell mass ratio = 0.1 :pre 1 20.690784 # Na core 2 31.90500 # Cl core 3 2.298976 # Na shell 4 3.54500 # Cl shell :pre Atoms :pre 1 1 2 1.5005 0.00000000 0.00000000 0.00000000 # core of core/shell pair 1 2 1 4 -2.5005 0.00000000 0.00000000 0.00000000 # shell of core/shell pair 1 3 2 1 1.5056 4.01599500 4.01599500 4.01599500 # core of core/shell pair 2 4 2 3 -0.5056 4.01599500 4.01599500 4.01599500 # shell of core/shell pair 2 (...) :pre Bonds # Bond topology for spring forces :pre 1 2 1 2 # spring for core/shell pair 1 2 2 3 4 # spring for core/shell pair 2 (...) :pre Non-Coulombic (e.g. Lennard-Jones) pairwise interactions are only defined between the shells. Coulombic interactions are defined between all cores and shells. If desired, additional bonds can be specified between cores. The "special_bonds"_special_bonds.html command should be used to turn-off the Coulombic interaction within core/shell pairs, since that interaction is set by the bond spring. This is done using the "special_bonds"_special_bonds.html command with a 1-2 weight = 0.0, which is the default value. It needs to be considered whether one has to adjust the "special_bonds"_special_bonds.html weighting according to the molecular topology since the interactions of the shells are bypassed over an extra bond. Note that this core/shell implementation does not require all ions to be polarized. One can mix core/shell pairs and ions without a satellite particle if desired. Since the core/shell model permits distances of r = 0.0 between the core and shell, a pair style with a "cs" suffix needs to be used to implement a valid long-range Coulombic correction. Several such pair styles are provided in the CORESHELL package. See "this doc page"_pair_cs.html for details. All of the core/shell enabled pair styles require the use of a long-range Coulombic solver, as specified by the "kspace_style"_kspace_style.html command. Either the PPPM or Ewald solvers can be used. For the NaCL example problem, these pair style and bond style settings are used: pair_style born/coul/long/cs 20.0 20.0 pair_coeff * * 0.0 1.000 0.00 0.00 0.00 pair_coeff 3 3 487.0 0.23768 0.00 1.05 0.50 #Na-Na pair_coeff 3 4 145134.0 0.23768 0.00 6.99 8.70 #Na-Cl pair_coeff 4 4 405774.0 0.23768 0.00 72.40 145.40 #Cl-Cl :pre bond_style harmonic bond_coeff 1 63.014 0.0 bond_coeff 2 25.724 0.0 :pre When running dynamics with the adiabatic core/shell model, the following issues should be considered. Since the relative motion of the core and shell particles corresponds to the polarization, typical thermostats can alter the polarization behaviour, meaning the shell will not react freely to its electrostatic environment. This is critical during the equilibration of the system. Therefore it's typically desirable to decouple the relative motion of the core/shell pair, which is an imaginary degree of freedom, from the real physical system. To do that, the "compute temp/cs"_compute_temp_cs.html command can be used, in conjunction with any of the thermostat fixes, such as "fix nvt"_fix_nh.html or "fix langevin"_fix_langevin. This compute uses the center-of-mass velocity of the core/shell pairs to calculate a temperature, and insures that velocity is what is rescaled for thermostatting purposes. This compute also works for a system with both core/shell pairs and non-polarized ions (ions without an attached satellite particle). The "compute temp/cs"_compute_temp_cs.html command requires input of two groups, one for the core atoms, another for the shell atoms. Non-polarized ions which might also be included in the treated system should not be included into either of these groups, they are taken into account by the {group-ID} (2nd argument) of the compute. The groups can be defined using the "group {type}"_group.html command. Note that to perform thermostatting using this definition of temperature, the "fix modify temp"_fix_modify.html command should be used to assign the compute to the thermostat fix. Likewise the "thermo_modify temp"_thermo_modify.html command can be used to make this temperature be output for the overall system. For the NaCl example, this can be done as follows: group cores type 1 2 group shells type 3 4 compute CSequ all temp/cs cores shells fix thermoberendsen all temp/berendsen 1427 1427 0.4 # thermostat for the true physical system fix thermostatequ all nve # integrator as needed for the berendsen thermostat fix_modify thermoberendsen temp CSequ thermo_modify temp CSequ # output of center-of-mass derived temperature :pre If "compute temp/cs"_compute_temp_cs.html is used, the decoupled relative motion of the core and the shell should in theory be stable. However numerical fluctuation can introduce a small momentum to the system, which is noticable over long trajectories. Therefore it is recomendable to use the "fix momentum"_fix_momentum.html command in combination with "compute temp/cs"_compute_temp_cs.html when equilibrating the system to prevent any drift. When intializing the velocities of a system with core/shell pairs, it is also desirable to not introduce energy into the relative motion of the core/shell particles, but only assign a center-of-mass velocity to the pairs. This can be done by using the {bias} keyword of the "velocity create"_velocity.html command and assigning the "compute temp/cs"_compute_temp_cs.html command to the {temp} keyword of the "velocity"_velocity.html commmand, e.g. velocity all create 1427 134 bias yes temp CSequ velocity all scale 1427 temp CSequ :pre It is important to note that the polarizability of the core/shell pairs is based on their relative motion. Therefore the choice of spring force and mass ratio need to ensure much faster relative motion of the 2 atoms within the core/shell pair than their center-of-mass velocity. This allow the shells to effectively react instantaneously to the electrostatic environment. This fast movement also limits the timestep size that can be used. The primary literature of the adiabatic core/shell model suggests that the fast relative motion of the core/shell pairs only allows negligible energy transfer to the environment. Therefore it is not intended to decouple the core/shell degree of freedom from the physical system during production runs. In other words, the "compute temp/cs"_compute_temp_cs.html command should not be used during production runs and is only required during equilibration. This way one is consistent with literature (based on the code packages DL_POLY or GULP for instance). -The mentioned energy transfer will typically lead to a a small drift +The mentioned energy transfer will typically lead to a small drift in total energy over time. This internal energy can be monitored using the "compute chunk/atom"_compute_chunk_atom.html and "compute temp/chunk"_compute_temp_chunk.html commands. The internal kinetic energies of each core/shell pair can then be summed using the sum() special function of the "variable"_variable.html command. Or they can be time/averaged and output using the "fix ave/time"_fix_ave_time.html command. To use these commands, each core/shell pair must be defined as a "chunk". If each core/shell pair is defined as its own molecule, the molecule ID can be used to define the chunks. If cores are bonded to each other to form larger molecules, the chunks can be identified by the "fix property/atom"_fix_property_atom.html via assigning a core/shell ID to each atom using a special field in the data file read by the "read_data"_read_data.html command. This field can then be accessed by the "compute property/atom"_compute_property_atom.html command, to use as input to the "compute chunk/atom"_compute_chunk_atom.html command to define the core/shell pairs as chunks. For example, fix csinfo all property/atom i_CSID # property/atom command read_data NaCl_CS_x0.1_prop.data fix csinfo NULL CS-Info # atom property added in the data-file compute prop all property/atom i_CSID compute cs_chunk all chunk/atom c_prop compute cstherm all temp/chunk cs_chunk temp internal com yes cdof 3.0 # note the chosen degrees of freedom for the core/shell pairs fix ave_chunk all ave/time 10 1 10 c_cstherm file chunk.dump mode vector :pre The additional section in the date file would be formatted like this: CS-Info # header of additional section :pre 1 1 # column 1 = atom ID, column 2 = core/shell ID 2 1 3 2 4 2 5 3 6 3 7 4 8 4 (...) :pre :line 6.27 Drude induced dipoles :link(howto_27),h4 The thermalized Drude model, similarly to the "core-shell"_#howto_26 model, representes induced dipoles by a pair of charges (the core atom and the Drude particle) connected by a harmonic spring. The Drude model has a number of features aimed at its use in molecular systems ("Lamoureux and Roux"_#howto-Lamoureux): Thermostating of the additional degrees of freedom associated with the induced dipoles at very low temperature, in terms of the reduced coordinates of the Drude particles with respect to their cores. This makes the trajectory close to that of relaxed induced dipoles. :ulb,l Consistent definition of 1-2 to 1-4 neighbors. A core-Drude particle pair represents a single (polarizable) atom, so the special screening factors in a covalent structure should be the same for the core and the Drude particle. Drude particles have to inherit the 1-2, 1-3, 1-4 special neighbor relations from their respective cores. :l Stabilization of the interactions between induced dipoles. Drude dipoles on covalently bonded atoms interact too strongly due to the short distances, so an atom may capture the Drude particle of a neighbor, or the induced dipoles within the same molecule may align too much. To avoid this, damping at short range can be done by Thole functions (for which there are physical grounds). This Thole damping is applied to the point charges composing the induced dipole (the charge of the Drude particle and the opposite charge on the core, not to the total charge of the core atom). :l :ule A detailed tutorial covering the usage of Drude induced dipoles in LAMMPS is "available here"_tutorial_drude.html. As with the core-shell model, the cores and Drude particles should appear in the data file as standard atoms. The same holds for the springs between them, which are described by standard harmonic bonds. The nature of the atoms (core, Drude particle or non-polarizable) is specified via the "fix drude"_fix_drude.html command. The special list of neighbors is automatically refactored to account for the equivalence of core and Drude particles as regards special 1-2 to 1-4 screening. It may be necessary to use the {extra} keyword of the "special_bonds"_special_bonds.html command. If using "fix shake"_fix_shake.html, make sure no Drude particle is in this fix group. There are two ways to thermostat the Drude particles at a low temperature: use either "fix langevin/drude"_fix_langevin_drude.html for a Langevin thermostat, or "fix drude/transform/*"_fix_drude_transform.html for a Nose-Hoover thermostat. The former requires use of the command "comm_modify vel yes"_comm_modify.html. The latter requires two separate integration fixes like {nvt} or {npt}. The correct temperatures of the reduced degrees of freedom can be calculated using the "compute temp/drude"_compute_temp_drude.html. This requires also to use the command {comm_modify vel yes}. Short-range damping of the induced dipole interactions can be achieved using Thole functions through the the "pair style thole"_pair_thole.html in "pair_style hybrid/overlay"_pair_hybrid.html with a Coulomb pair style. It may be useful to use {coul/long/cs} or similar from the CORESHELL package if the core and Drude particle come too close, which can cause numerical issues. :line :line :link(howto-Berendsen) [(Berendsen)] Berendsen, Grigera, Straatsma, J Phys Chem, 91, 6269-6271 (1987). :link(howto-Cornell) [(Cornell)] Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995). :link(Horn) [(Horn)] Horn, Swope, Pitera, Madura, Dick, Hura, and Head-Gordon, J Chem Phys, 120, 9665 (2004). :link(howto-Ikeshoji) [(Ikeshoji)] Ikeshoji and Hafskjold, Molecular Physics, 81, 251-261 (1994). :link(howto-Wirnsberger) [(Wirnsberger)] Wirnsberger, Frenkel, and Dellago, J Chem Phys, 143, 124104 (2015). :link(howto-MacKerell) [(MacKerell)] MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998). :link(howto-Mayo) [(Mayo)] Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909 (1990). :link(Jorgensen) [(Jorgensen)] Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem Phys, 79, 926 (1983). :link(Price) [(Price)] Price and Brooks, J Chem Phys, 121, 10096 (2004). :link(Shinoda) [(Shinoda)] Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004). :link(MitchellFinchham) [(Mitchell and Finchham)] Mitchell, Finchham, J Phys Condensed Matter, 5, 1031-1038 (1993). :link(howto-Lamoureux) [(Lamoureux and Roux)] G. Lamoureux, B. Roux, J. Chem. Phys 119, 3025 (2003) diff --git a/doc/src/Section_start.txt b/doc/src/Section_start.txt index a0cc79245..ee122e0a7 100644 --- a/doc/src/Section_start.txt +++ b/doc/src/Section_start.txt @@ -1,1907 +1,1907 @@ "Previous Section"_Section_intro.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_commands.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line 2. Getting Started :h3 This section describes how to build and run LAMMPS, for both new and experienced users. 2.1 "What's in the LAMMPS distribution"_#start_1 2.2 "Making LAMMPS"_#start_2 2.3 "Making LAMMPS with optional packages"_#start_3 2.4 "Building LAMMPS via the Make.py script"_#start_4 2.5 "Building LAMMPS as a library"_#start_5 2.6 "Running LAMMPS"_#start_6 2.7 "Command-line options"_#start_7 2.8 "Screen output"_#start_8 2.9 "Tips for users of previous versions"_#start_9 :all(b) :line 2.1 What's in the LAMMPS distribution :h4,link(start_1) When you download a LAMMPS tarball you will need to unzip and untar the downloaded file with the following commands, after placing the tarball in an appropriate directory. tar -xzvf lammps*.tar.gz :pre This will create a LAMMPS directory containing two files and several sub-directories: README: text file LICENSE: the GNU General Public License (GPL) bench: benchmark problems doc: documentation examples: simple test problems potentials: embedded atom method (EAM) potential files src: source files tools: pre- and post-processing tools :tb(s=:) Note that the "download page"_download also has links to download pre-build Windows installers, as well as pre-built packages for several widely used Linux distributions. It also has instructions for how to download/install LAMMPS for Macs (via Homebrew), and to download and update LAMMPS from SVN and Git repositories, which gives you access to the up-to-date sources that are used by the LAMMPS core developers. :link(download,http://lammps.sandia.gov/download.html) The Windows and Linux packages for serial or parallel include only selected packages and bug-fixes/upgrades listed on "this page"_http://lammps.sandia.gov/bug.html up to a certain date, as stated on the download page. If you want an executable with non-included packages or that is more current, then you'll need to build LAMMPS yourself, as discussed in the next section. Skip to the "Running LAMMPS"_#start_6 sections for info on how to launch a LAMMPS Windows executable on a Windows box. :line 2.2 Making LAMMPS :h4,link(start_2) This section has the following sub-sections: 2.2.1 "Read this first"_#start_2_1 2.2.1 "Steps to build a LAMMPS executable"_#start_2_2 2.2.3 "Common errors that can occur when making LAMMPS"_#start_2_3 2.2.4 "Additional build tips"_#start_2_4 2.2.5 "Building for a Mac"_#start_2_5 2.2.6 "Building for Windows"_#start_2_6 :all(b) :line Read this first :h5,link(start_2_1) If you want to avoid building LAMMPS yourself, read the preceeding section about options available for downloading and installing executables. Details are discussed on the "download"_download page. Building LAMMPS can be simple or not-so-simple. If all you need are the default packages installed in LAMMPS, and MPI is already installed on your machine, or you just want to run LAMMPS in serial, then you can typically use the Makefile.mpi or Makefile.serial files in src/MAKE by typing one of these lines (from the src dir): make mpi make serial :pre Note that on a facility supercomputer, there are often "modules" loaded in your environment that provide the compilers and MPI you should use. In this case, the "mpicxx" compile/link command in Makefile.mpi should just work by accessing those modules. It may be the case that one of the other Makefile.machine files in the src/MAKE sub-directories is a better match to your system (type "make" to see a list), you can use it as-is by typing (for example): make stampede :pre If any of these builds (with an existing Makefile.machine) works on your system, then you're done! If you want to do one of the following: use optional LAMMPS features that require additional libraries use optional packages that require additional libraries use optional accelerator packages that require special compiler/linker settings run on a specialized platform that has its own compilers, settings, or other libs to use :ul then building LAMMPS is more complicated. You may need to find where auxiliary libraries exist on your machine or install them if they don't. You may need to build additional libraries that are part of the LAMMPS package, before building LAMMPS. You may need to edit a Makefile.machine file to make it compatible with your system. Note that there is a Make.py tool in the src directory that automates several of these steps, but you still have to know what you are doing. "Section 2.4"_#start_4 below describes the tool. It is a convenient way to work with installing/un-installing various packages, the Makefile.machine changes required by some packages, and the auxiliary libraries some of them use. Please read the following sections carefully. If you are not comfortable with makefiles, or building codes on a Unix platform, or running an MPI job on your machine, please find a local expert to help you. Many compilation, linking, and run problems that users have are often not really LAMMPS issues - they are peculiar to the user's system, compilers, libraries, etc. Such questions are better answered by a local expert. If you have a build problem that you are convinced is a LAMMPS issue (e.g. the compiler complains about a line of LAMMPS source code), then please post the issue to the "LAMMPS mail list"_http://lammps.sandia.gov/mail.html. If you succeed in building LAMMPS on a new kind of machine, for which there isn't a similar machine Makefile included in the src/MAKE/MACHINES directory, then send it to the developers and we can include it in the LAMMPS distribution. :line Steps to build a LAMMPS executable :h5,link(start_2_2) Step 0 :h6 The src directory contains the C++ source and header files for LAMMPS. It also contains a top-level Makefile and a MAKE sub-directory with low-level Makefile.* files for many systems and machines. See the src/MAKE/README file for a quick overview of what files are available and what sub-directories they are in. The src/MAKE dir has a few files that should work as-is on many platforms. The src/MAKE/OPTIONS dir has more that invoke additional compiler, MPI, and other setting options commonly used by LAMMPS, to illustrate their syntax. The src/MAKE/MACHINES dir has many more that have been tweaked or optimized for specific machines. These files are all good starting points if you find you need to change them for your machine. Put any file you edit into the src/MAKE/MINE directory and it will be never be touched by any LAMMPS updates. >From within the src directory, type "make" or "gmake". You should see a list of available choices from src/MAKE and all of its sub-directories. If one of those has the options you want or is the machine you want, you can type a command like: make mpi :pre or make serial :pre or gmake mac :pre Note that the corresponding Makefile.machine can exist in src/MAKE or any of its sub-directories. If a file with the same name appears in multiple places (not a good idea), the order they are used is as follows: src/MAKE/MINE, src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference to a file you have created/edited and put in src/MAKE/MINE. Note that on a multi-processor or multi-core platform you can launch a parallel make, by using the "-j" switch with the make command, which will build LAMMPS more quickly. If you get no errors and an executable like [lmp_mpi] or [lmp_serial] or [lmp_mac] is produced, then you're done; it's your lucky day. Note that by default only a few of LAMMPS optional packages are installed. To build LAMMPS with optional packages, see "this section"_#start_3 below. Step 1 :h6 If Step 0 did not work, you will need to create a low-level Makefile for your machine, like Makefile.foo. You should make a copy of an existing Makefile.* in src/MAKE or one of its sub-directories as a starting point. The only portions of the file you need to edit are the first line, the "compiler/linker settings" section, and the "LAMMPS-specific settings" section. When it works, put the edited file in src/MAKE/MINE and it will not be altered by any future LAMMPS updates. Step 2 :h6 Change the first line of Makefile.foo to list the word "foo" after the "#", and whatever other options it will set. This is the line you will see if you just type "make". Step 3 :h6 The "compiler/linker settings" section lists compiler and linker settings for your C++ compiler, including optimization flags. You can use g++, the open-source GNU compiler, which is available on all Unix systems. You can also use mpicxx which will typically be available if MPI is installed on your system, though you should check which actual compiler it wraps. Vendor compilers often produce faster code. On boxes with Intel CPUs, we suggest using the Intel icc compiler, which can be downloaded from "Intel's compiler site"_intel. :link(intel,http://www.intel.com/software/products/noncom) If building a C++ code on your machine requires additional libraries, then you should list them as part of the LIB variable. You should not need to do this if you use mpicxx. The DEPFLAGS setting is what triggers the C++ compiler to create a dependency list for a source file. This speeds re-compilation when source (*.cpp) or header (*.h) files are edited. Some compilers do not support dependency file creation, or may use a different switch than -D. GNU g++ and Intel icc works with -D. If your compiler can't create dependency files, then you'll need to create a Makefile.foo patterned after Makefile.storm, which uses different rules that do not involve dependency files. Note that when you build LAMMPS for the first time on a new platform, a long list of *.d files will be printed out rapidly. This is not an error; it is the Makefile doing its normal creation of dependencies. Step 4 :h6 The "system-specific settings" section has several parts. Note that if you change any -D setting in this section, you should do a full re-compile, after typing "make clean" (which will describe different clean options). The LMP_INC variable is used to include options that turn on ifdefs within the LAMMPS code. The options that are currently recogized are: -DLAMMPS_GZIP -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG -DLAMMPS_MEMALIGN -DLAMMPS_XDR -DLAMMPS_SMALLBIG -DLAMMPS_BIGBIG -DLAMMPS_SMALLSMALL -DLAMMPS_LONGLONG_TO_LONG -DLAMMPS_EXCEPTIONS -DPACK_ARRAY -DPACK_POINTER -DPACK_MEMCPY :ul The read_data and dump commands will read/write gzipped files if you compile with -DLAMMPS_GZIP. It requires that your machine supports the "popen()" function in the standard runtime library and that a gzip executable can be found by LAMMPS during a run. NOTE: on some clusters with high-speed networks, using the fork() library calls (required by popen()) can interfere with the fast communication library and lead to simulations using compressed output or input to hang or crash. For selected operations, compressed file I/O is also available using a compression library instead, which are provided in the COMPRESS package. From more details about compiling LAMMPS with packages, please see below. If you use -DLAMMPS_JPEG, the "dump image"_dump_image.html command will be able to write out JPEG image files. For JPEG files, you must also link LAMMPS with a JPEG library, as described below. If you use -DLAMMPS_PNG, the "dump image"_dump.html command will be able to write out PNG image files. For PNG files, you must also link LAMMPS with a PNG library, as described below. If neither of those two defines are used, LAMMPS will only be able to write out uncompressed PPM image files. If you use -DLAMMPS_FFMPEG, the "dump movie"_dump_image.html command will be available to support on-the-fly generation of rendered movies the need to store intermediate image files. It requires that your machines supports the "popen" function in the standard runtime library and that an FFmpeg executable can be found by LAMMPS during the run. NOTE: Similar to the note above, this option can conflict with high-speed networks, because it uses popen(). Using -DLAMMPS_MEMALIGN= enables the use of the posix_memalign() call instead of malloc() when large chunks or memory are allocated by LAMMPS. This can help to make more efficient use of vector instructions of modern CPUS, since dynamically allocated memory has to be aligned on larger than default byte boundaries (e.g. 16 bytes instead of 8 bytes on x86 type platforms) for optimal performance. If you use -DLAMMPS_XDR, the build will include XDR compatibility 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, -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 (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. Normally, the only reason to use SMALLSMALL is if your machine does not support 64-bit integers, though you can use SMALLSMALL setting if you are running in serial or on a desktop machine or small cluster where you will never run large systems or for long time (more than 2 billion atoms, more than 2 billion timesteps). See the "Additional build tips"_#start_2_4 section below for more details on these settings. Note that the USER-ATC package is not currently compatible with -DLAMMPS_BIGBIG. Also the GPU package requires the lib/gpu library to be compiled with the same setting, or the link will fail. 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 "long" data type is likely already 64-bits, in which case this setting will convert to that data type. The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative versions of error handling inside of LAMMPS. This is useful when external codes drive LAMMPS as a library. Using this option, LAMMPS errors do not kill the caller. Instead, the call stack is unwound and control returns to the caller. The library interface provides the lammps_has_error() and lammps_get_last_error_message() functions to detect and find out more about a LAMMPS error. Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM solver) on some platforms. The -DPACK_ARRAY setting is the default. See the "kspace_style"_kspace_style.html command for info about PPPM. See Step 6 below for info about building LAMMPS with an FFT library. Step 5 :h6 The 3 MPI variables are used to specify an MPI library to build LAMMPS with. Note that you do not need to set these if you use the MPI compiler mpicxx for your CC and LINK setting in the section above. The MPI wrapper knows where to find the needed files. If you want LAMMPS to run in parallel, you must have an MPI library installed on your platform. If MPI is installed on your system in the usual place (under /usr/local), you also may not need to specify these 3 variables, assuming /usr/local is in your path. On some large parallel machines which use "modules" for their compile/link environements, you may simply need to include the correct module in your build environment, before building LAMMPS. Or the parallel machine may have a vendor-provided MPI which the compiler has no trouble finding. Failing this, these 3 variables can be used to specify where the mpi.h file (MPI_INC) and the MPI library file (MPI_PATH) are found and the name of the library file (MPI_LIB). If you are installing MPI yourself, we recommend Argonne's MPICH2 or OpenMPI. MPICH can be downloaded from the "Argonne MPI site"_http://www.mcs.anl.gov/research/projects/mpich2/. OpenMPI can be downloaded from the "OpenMPI site"_http://www.open-mpi.org. Other MPI packages should also work. If you are running on a big parallel platform, your system people or the vendor should have already installed a version of MPI, which is likely to be faster than a self-installed MPICH or OpenMPI, so find out how to build and link with it. If you use MPICH or OpenMPI, you will have to configure and build it for your platform. The MPI configure script should have compiler options to enable you to use the same compiler you are using for the LAMMPS build, which can avoid problems that can arise when linking LAMMPS to the MPI library. If you just want to run LAMMPS on a single processor, you can use the dummy MPI library provided in src/STUBS, since you don't need a true MPI library installed on your system. See src/MAKE/Makefile.serial for how to specify the 3 MPI variables in this case. You will also need to build the STUBS library for your platform before making LAMMPS itself. Note that if you are building with src/MAKE/Makefile.serial, e.g. by typing "make serial", then the STUBS library is built for you. To build the STUBS library from the src directory, type "make mpi-stubs", or from the src/STUBS dir, type "make". This should create a libmpi_stubs.a file suitable for linking to LAMMPS. If the build fails, you will need to edit the STUBS/Makefile for your platform. The file STUBS/mpi.c provides a CPU timer function called MPI_Wtime() that calls gettimeofday() . If your system doesn't support gettimeofday() , you'll need to insert code to call another timer. Note that the ANSI-standard function clock() rolls over after an hour or so, and is therefore insufficient for timing long LAMMPS simulations. Step 6 :h6 The 3 FFT variables allow you to specify an FFT library which LAMMPS uses (for performing 1d FFTs) when running the particle-particle particle-mesh (PPPM) option for long-range Coulombics via the "kspace_style"_kspace_style.html command. LAMMPS supports various open-source or vendor-supplied FFT libraries for this purpose. If you leave these 3 variables blank, LAMMPS will use the open-source "KISS FFT library"_http://kissfft.sf.net, which is included in the LAMMPS distribution. This library is portable to all platforms and for typical LAMMPS simulations is almost as fast as FFTW or vendor optimized libraries. If you are not including the KSPACE package in your build, you can also leave the 3 variables blank. Otherwise, select which kinds of FFTs to use as part of the FFT_INC setting by a switch of the form -DFFT_XXX. Recommended values for XXX are: MKL, SCSL, FFTW2, and FFTW3. Legacy options are: INTEL, SGI, ACML, and T3E. For backward compatability, using -DFFT_FFTW will use the FFTW2 library. Using -DFFT_NONE will use the KISS library described above. You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables, so the compiler and linker can find the needed FFT header and library files. Note that on some large parallel machines which use "modules" for their compile/link environements, you may simply need to include the correct module in your build environment. Or the parallel machine may have a vendor-provided FFT library which the compiler has no trouble finding. FFTW is a fast, portable library that should also work on any platform. You can download it from "www.fftw.org"_http://www.fftw.org. Both the legacy version 2.1.X and the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3. Building FFTW for your box should be as simple as ./configure; make. Note that on some platforms FFTW2 has been pre-installed, and uses renamed files indicating the precision it was compiled with, e.g. sfftw.h, or dfftw.h instead of fftw.h. In this case, you can specify an additional define variable for FFT_INC called -DFFTW_SIZE, which will select the correct include file. In this case, for FFT_LIB you must also manually specify the correct library, namely -lsfftw or -ldfftw. The FFT_INC variable also allows for a -DFFT_SINGLE setting that will use single-precision FFTs with PPPM, which can speed-up long-range calulations, particularly in parallel or on GPUs. Fourier transform and related PPPM operations are somewhat insensitive to floating point truncation errors and thus do not always need to be performed in double precision. Using the -DFFT_SINGLE setting trades off a little accuracy for reduced memory use and parallel communication costs for transposing 3d FFT data. Note that single precision FFTs have only been tested with the FFTW3, FFTW2, MKL, and KISS FFT options. Step 7 :h6 The 3 JPG variables allow you to specify a JPEG and/or PNG library which LAMMPS uses when writing out JPEG or PNG files via the "dump image"_dump_image.html command. These can be left blank if you do not use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step 4, since in that case JPEG/PNG output will be disabled. A standard JPEG library usually goes by the name libjpeg.a or libjpeg.so and has an associated header file jpeglib.h. Whichever JPEG library you have on your platform, you'll need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the compiler and linker can find it. A standard PNG library usually goes by the name libpng.a or libpng.so and has an associated header file png.h. Whichever PNG library you have on your platform, you'll need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the compiler and linker can find it. As before, if these header and library files are in the usual place on your machine, you may not need to set these variables. Step 8 :h6 Note that by default only a few of LAMMPS optional packages are installed. To build LAMMPS with optional packages, see "this section"_#start_3 below, before proceeding to Step 9. Step 9 :h6 That's it. Once you have a correct Makefile.foo, and you have pre-built any other needed libraries (e.g. MPI, FFT, etc) all you need to do from the src directory is type something like this: make foo make -j N foo gmake foo gmake -j N foo :pre The -j or -j N switches perform a parallel build which can be much faster, depending on how many cores your compilation machine has. N is the number of cores the build runs on. You should get the executable lmp_foo when the build is complete. :line Errors that can occur when making LAMMPS: h5 :link(start_2_3) NOTE: If an error occurs when building LAMMPS, the compiler or linker will state very explicitly what the problem is. The error message should give you a hint as to which of the steps above has failed, and what you need to do in order to fix it. Building a code with a Makefile is a very logical process. The compiler and linker need to find the appropriate files and those files need to be compatible with LAMMPS source files. When a make fails, there is usually a very simple reason, which you or a local expert will need to fix. Here are two non-obvious errors that can occur: (1) If the make command breaks immediately with errors that indicate it can't find files with a "*" in their names, this can be because your machine's native make doesn't support wildcard expansion in a makefile. Try gmake instead of make. If that doesn't work, try using a -f switch with your make command to use a pre-generated Makefile.list which explicitly lists all the needed files, e.g. make makelist make -f Makefile.list linux gmake -f Makefile.list mac :pre The first "make" command will create a current Makefile.list with all the file names in your src dir. The 2nd "make" command (make or gmake) will use it to build LAMMPS. Note that you should include/exclude any desired optional packages before using the "make makelist" command. (2) If you get an error that says something like 'identifier "atoll" is undefined', then your machine does not support "long long" integers. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described above in Step 4. :line Additional build tips :h5,link(start_2_4) Building LAMMPS for multiple platforms. :h6 You can make LAMMPS for multiple platforms from the same src directory. Each target creates its own object sub-directory called Obj_target where it stores the system-specific *.o files. Cleaning up. :h6 Typing "make clean-all" or "make clean-machine" will delete *.o object files created when LAMMPS is built, for either all builds or for a particular machine. Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :h6 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 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. 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. 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 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 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 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 Building for a Mac :h5,link(start_2_5) OS X is a derivative of BSD Unix, so it should just work. See the src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files. :line Building for Windows :h5,link(start_2_6) If you want to build a Windows version of LAMMPS, you can build it yourself, but it may require some effort. LAMMPS expects a Unix-like build environment for the default build procedure. This can be done using either Cygwin or MinGW; the latter also exists as a ready-to-use Linux-to-Windows cross-compiler in several Linux distributions. In these cases, you can do the installation after installing several unix-style commands like make, grep, sed and bash with some shell utilities. For Cygwin and the MinGW cross-compilers, suitable makefiles are provided in src/MAKE/MACHINES. When using other compilers, like Visual C++ or Intel compilers for Windows, you may have to implement your own build system. Since none of the current LAMMPS core developers has significant experience building executables on Windows, we are happy to distribute contributed instructions and modifications, but we cannot provide support for those. With the so-called "Anniversary Update" to Windows 10, there is a Ubuntu Linux subsystem available for Windows, that can be installed and then used to compile/install LAMMPS as if you are running on a Ubuntu Linux system instead of Windows. As an alternative, you can download "daily builds" (and some older versions) of the installer packages from "rpm.lammps.org/windows.html"_http://rpm.lammps.org/windows.html. These executables are built with most optional packages and the download includes documentation, potential files, some tools and many examples, but no source code. :line 2.3 Making LAMMPS with optional packages :h4,link(start_3) This section has the following sub-sections: 2.3.1 "Package basics"_#start_3_1 2.3.2 "Including/excluding packages"_#start_3_2 2.3.3 "Packages that require extra libraries"_#start_3_3 2.3.4 "Packages that require Makefile.machine settings"_#start_3_4 :all(b) Note that the following "Section 2.4"_#start_4 describes the Make.py tool which can be used to install/un-install packages and build the auxiliary libraries which some of them use. It can also auto-edit a Makefile.machine to add settings needed by some packages. :line Package basics: :h5,link(start_3_1) The source code for LAMMPS is structured as a set of core files which are always included, plus optional packages. Packages are groups of files that enable a specific set of features. For example, force fields for molecular systems or granular systems are in packages. "Section 4"_Section_packages.html in the manual has details about all the packages, including specific instructions for building LAMMPS with each package, which are covered in a more general manner below. You can see the list of all packages by typing "make package" from within the src directory of the LAMMPS distribution. This also lists various make commands that can be used to manipulate packages. If you use a command in a LAMMPS input script that is part of a package, you must have built LAMMPS with that package, else you will get an error that the style is invalid or the command is unknown. Every command's doc page specfies if it is part of a package. You can also type lmp_machine -h :pre to run your executable with the optional "-h command-line switch"_#start_7 for "help", which will simply list the styles and commands known to your executable, and immediately exit. There are two kinds of packages in LAMMPS, standard and user packages. More information about the contents of standard and user packages is given in "Section 4"_Section_packages.html of the manual. The difference between standard and user packages is as follows: Standard packages, such as molecule or kspace, are supported by the LAMMPS developers and are written in a syntax and style consistent with the rest of LAMMPS. This means we will answer questions about them, debug and fix them if necessary, and keep them compatible with future changes to LAMMPS. User packages, such as user-atc or user-omp, have been contributed by users, and always begin with the user prefix. If they are a single command (single file), they are typically in the user-misc package. -Otherwise, they are a a set of files grouped together which add a +Otherwise, they are a set of files grouped together which add a specific functionality to the code. User packages don't necessarily meet the requirements of the standard packages. If you have problems using a feature provided in a user package, you may need to contact the contributor directly to get help. Information on how to submit additions you make to LAMMPS as single files or either a standard or user-contributed package are given in "this section"_Section_modify.html#mod_15 of the documentation. :line Including/excluding packages :h5,link(start_3_2) To use (or not use) a package you must include it (or exclude it) before building LAMMPS. From the src directory, this is typically as simple as: make yes-colloid make mpi :pre or make no-manybody make mpi :pre NOTE: You should NOT include/exclude packages and build LAMMPS in a single make command using multiple targets, e.g. make yes-colloid mpi. This is because the make procedure creates a list of source files that will be out-of-date for the build if the package configuration changes within the same command. Some packages have individual files that depend on other packages being included. LAMMPS checks for this and does the right thing. I.e. individual files are only included if their dependencies are already included. Likewise, if a package is excluded, other files dependent on that package are also excluded. If you will never run simulations that use the features in a particular packages, there is no reason to include it in your build. For some packages, this will keep you from having to build auxiliary libraries (see below), and will also produce a smaller executable which may run a bit faster. When you download a LAMMPS tarball, these packages are pre-installed in the src directory: KSPACE, MANYBODY,MOLECULE, because they are so commonly used. When you download LAMMPS source files from the SVN or Git repositories, no packages are pre-installed. Packages are included or excluded by typing "make yes-name" or "make no-name", where "name" is the name of the package in lower-case, e.g. name = kspace for the KSPACE package or name = user-atc for the USER-ATC package. You can also type "make yes-standard", "make no-standard", "make yes-std", "make no-std", "make yes-user", "make no-user", "make yes-lib", "make no-lib", "make yes-all", or "make no-all" to include/exclude various sets of packages. Type "make package" to see all of the package-related make options. NOTE: Inclusion/exclusion of a package works by simply moving files back and forth between the main src directory and sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC), so that the files are seen or not seen when LAMMPS is built. After you have included or excluded a package, you must re-build LAMMPS. Additional package-related make options exist to help manage LAMMPS files that exist in both the src directory and in package sub-directories. You do not normally need to use these commands unless you are editing LAMMPS files or have downloaded a patch from the LAMMPS WWW site. Typing "make package-update" or "make pu" will overwrite src files with files from the package sub-directories if the package has been included. It should be used after a patch is installed, since patches only update the files in the package sub-directory, but not the src files. Typing "make package-overwrite" will overwrite files in the package sub-directories with src files. Typing "make package-status" or "make ps" will show which packages are currently included. For those that are included, it will list any files that are different in the src directory and package sub-directory. Typing "make package-diff" lists all differences between these files. Again, type "make package" to see all of the package-related make options. :line Packages that require extra libraries :h5,link(start_3_3) A few of the standard and user packages require additional auxiliary libraries. Many of them are provided with LAMMPS, in which case they must be compiled first, before LAMMPS is built, if you wish to include that package. If you get a LAMMPS build error about a missing library, this is likely the reason. See the "Section 4"_Section_packages.html doc page for a list of packages that have these kinds of auxiliary libraries. The lib directory in the distribution has sub-directories with package names that correspond to the needed auxiliary libs, e.g. lib/gpu. Each sub-directory has a README file that gives more details. Code for most of the auxiliary libraries is included in that directory. Examples are the USER-ATC and MEAM packages. A few of the lib sub-directories do not include code, but do include instructions (and sometimes scripts) that automate the process of downloading the auxiliary library and installing it so LAMMPS can link to it. Examples are the KIM, VORONOI, USER-MOLFILE, and USER-SMD packages. The lib/python directory (for the PYTHON package) contains only a choice of Makefile.lammps.* files. This is because no auxiliary code or libraries are needed, only the Python library and other system libs that should already available on your system. However, the Makefile.lammps file is needed to tell LAMMPS which libs to use and where to find them. For libraries with provided code, the sub-directory README file (e.g. lib/atc/README) has instructions on how to build that library. This information is also summarized in "Section 4"_Section_packages.html. Typically this is done by typing something like: make -f Makefile.g++ :pre If one of the provided Makefiles is not appropriate for your system you will need to edit or add one. Note that all the Makefiles have a setting for EXTRAMAKE at the top that specifies a Makefile.lammps.* file. If the library build is successful, it will produce 2 files in the lib directory: libpackage.a Makefile.lammps :pre The Makefile.lammps file will typically be a copy of one of the Makefile.lammps.* files in the library directory. Note that you must insure that the settings in Makefile.lammps are appropriate for your system. If they are not, the LAMMPS build may fail. To fix this, you can edit or create a new Makefile.lammps.* file for your system, and copy it to Makefile.lammps. As explained in the lib/package/README files, the settings in Makefile.lammps are used to specify additional system libraries and their locations so that LAMMPS can build with the auxiliary library. For example, if the MEAM package is used, the auxiliary library consists of F90 code, built with a Fortran complier. To link that library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS is built with, typically requires additional Fortran-to-C libraries be included in the link. Another example are the BLAS and LAPACK libraries needed to use the USER-ATC or USER-AWPMD packages. For libraries without provided code, the sub-directory README file has information on where to download the library and how to build it, e.g. lib/voronoi/README and lib/smd/README. The README files also describe how you must either (a) create soft links, via the "ln" command, in those directories to point to where you built or installed the packages, or (b) check or edit the Makefile.lammps file in the same directory to provide that information. Some of the sub-directories, e.g. lib/voronoi, also have an install.py script which can be used to automate the process of downloading/building/installing the auxiliary library, and setting the needed soft links. Type "python install.py" for further instructions. As with the sub-directories containing library code, if the soft links or settings in the lib/package/Makefile.lammps files are not correct, the LAMMPS build will typically fail. :line Packages that require Makefile.machine settings :h5,link(start_3_4) A few packages require specific settings in Makefile.machine, to either build or use the package effectively. These are the USER-INTEL, KOKKOS, USER-OMP, and OPT packages, used for accelerating code performance on CPUs or other hardware, as discussed in "Section 5.3"_Section_accelerate.html#acc_3. A summary of what Makefile.machine changes are needed for each of these packages is given in "Section 4"_Section_packages.html. The details are given on the doc pages that describe each of these accelerator packages in detail: 5.3.1 "USER-INTEL package"_accelerate_intel.html 5.3.3 "KOKKOS package"_accelerate_kokkos.html 5.3.4 "USER-OMP package"_accelerate_omp.html 5.3.5 "OPT package"_accelerate_opt.html :all(b) You can also look at the following machine Makefiles in src/MAKE/OPTIONS, which include the changes. Note that the USER-INTEL and KOKKOS packages allow for settings that build LAMMPS for different hardware. The USER-INTEL package builds for CPU and the Xeon Phi, the KOKKOS package builds for OpenMP, GPUs (Cuda), and the Xeon Phi. Makefile.intel_cpu Makefile.intel_phi Makefile.kokkos_omp Makefile.kokkos_cuda Makefile.kokkos_phi Makefile.omp Makefile.opt :ul Also note that the Make.py tool, described in the next "Section 2.4"_#start_4 can automatically add the needed info to an existing machine Makefile, using simple command-line arguments. :line 2.4 Building LAMMPS via the Make.py tool :h4,link(start_4) The src directory includes a Make.py script, written in Python, which can be used to automate various steps of the build process. It is particularly useful for working with the accelerator packages, as well as other packages which require auxiliary libraries to be built. The goal of the Make.py tool is to allow any complex multi-step LAMMPS build to be performed as a single Make.py command. And you can archive the commands, so they can be re-invoked later via the -r (redo) switch. If you find some LAMMPS build procedure that can't be done in a single Make.py command, let the developers know, and we'll see if we can augment the tool. You can run Make.py from the src directory by typing either: Make.py -h python Make.py -h :pre which will give you help info about the tool. For the former to work, you may need to edit the first line of Make.py to point to your local Python. And you may need to insure the script is executable: chmod +x Make.py :pre Here are examples of build tasks you can perform with Make.py: Install/uninstall packages: Make.py -p no-lib kokkos omp intel Build specific auxiliary libs: Make.py -a lib-atc lib-meam Build libs for all installed packages: Make.py -p cuda gpu -gpu mode=double arch=31 -a lib-all Create a Makefile from scratch with compiler and MPI settings: Make.py -m none -cc g++ -mpi mpich -a file Augment Makefile.serial with settings for installed packages: Make.py -p intel -intel cpu -m serial -a file Add JPG and FFTW support to Makefile.mpi: Make.py -m mpi -jpg -fft fftw -a file Build LAMMPS with a parallel make using Makefile.mpi: Make.py -j 16 -m mpi -a exe Build LAMMPS and libs it needs using Makefile.serial with accelerator settings: Make.py -p gpu intel -intel cpu -a lib-all file serial :tb(s=:) The bench and examples directories give Make.py commands that can be used to build LAMMPS with the various packages and options needed to run all the benchmark and example input scripts. See these files for more details: bench/README bench/FERMI/README bench/KEPLER/README bench/PHI/README examples/README examples/accelerate/README examples/accelerate/make.list :ul All of the Make.py options and syntax help can be accessed by using the "-h" switch. E.g. typing "Make.py -h" gives Syntax: Make.py switch args ... switches can be listed in any order help switch: -h prints help and syntax for all other specified switches switch for actions: -a lib-all, lib-dir, clean, file, exe or machine list one or more actions, in any order machine is a Makefile.machine suffix, must be last if used one-letter switches: -d (dir), -j (jmake), -m (makefile), -o (output), -p (packages), -r (redo), -s (settings), -v (verbose) switches for libs: -atc, -awpmd, -colvars, -cuda -gpu, -meam, -poems, -qmmm, -reax switches for build and makefile options: -intel, -kokkos, -cc, -mpi, -fft, -jpg, -png :pre Using the "-h" switch with other switches and actions gives additional info on all the other specified switches or actions. The "-h" can be anywhere in the command-line and the other switches do not need their arguments. E.g. type "Make.py -h -d -atc -intel" will print: -d dir dir = LAMMPS home dir if -d not specified, working dir must be lammps/src :pre -atc make=suffix lammps=suffix2 all args are optional and can be in any order make = use Makefile.suffix (def = g++) lammps = use Makefile.lammps.suffix2 (def = EXTRAMAKE in makefile) :pre -intel mode mode = cpu or phi (def = cpu) build Intel package for CPU or Xeon Phi :pre Note that Make.py never overwrites an existing Makefile.machine. Instead, it creates src/MAKE/MINE/Makefile.auto, which you can save or rename if desired. Likewise it creates an executable named src/lmp_auto, which you can rename using the -o switch if desired. The most recently executed Make.py commmand is saved in src/Make.py.last. You can use the "-r" switch (for redo) to re-invoke the last command, or you can save a sequence of one or more Make.py commands to a file and invoke the file of commands using "-r". You can also label the commands in the file and invoke one or more of them by name. A typical use of Make.py is to start with a valid Makefile.machine for your system, that works for a vanilla LAMMPS build, i.e. when optional packages are not installed. You can then use Make.py to add various settings (FFT, JPG, PNG) to the Makefile.machine as well as change its compiler and MPI options. You can also add additional packages to the build, as well as build the needed supporting libraries. You can also use Make.py to create a new Makefile.machine from scratch, using the "-m none" switch, if you also specify what compiler and MPI options to use, via the "-cc" and "-mpi" switches. :line 2.5 Building LAMMPS as a library :h4,link(start_5) LAMMPS can be built as either a static or shared library, which can then be called from another application or a scripting language. See "this section"_Section_howto.html#howto_10 for more info on coupling LAMMPS to other codes. See "this section"_Section_python.html for more info on wrapping and running LAMMPS from Python. Static library :h5 To build LAMMPS as a static library (*.a file on Linux), type make foo mode=lib :pre where foo is the machine name. This kind of library is typically used to statically link a driver application to LAMMPS, so that you can insure all dependencies are satisfied at compile time. This will use the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build will create the file liblammps_foo.a which another application can link to. It will also create a soft link liblammps.a, which will point to the most recently built static library. Shared library :h5 To build LAMMPS as a shared library (*.so file on Linux), which can be dynamically loaded, e.g. from Python, type make foo mode=shlib :pre where foo is the machine name. This kind of library is required when wrapping LAMMPS with Python; see "Section 11"_Section_python.html for details. This will use the SHFLAGS and SHLIBFLAGS settings in src/MAKE/Makefile.foo and perform the build in the directory Obj_shared_foo. This is so that each file can be compiled with the -fPIC flag which is required for inclusion in a shared library. The build will create the file liblammps_foo.so which another application can link to dyamically. It will also create a soft link liblammps.so, which will point to the most recently built shared library. This is the file the Python wrapper loads by default. Note that for a shared library to be usable by a calling program, all the auxiliary libraries it depends on must also exist as shared libraries. This will be the case for libraries included with LAMMPS, such as the dummy MPI library in src/STUBS or any package libraries in lib/packages, since they are always built as shared libraries using the -fPIC switch. However, if a library like MPI or FFTW does not exist as a shared library, the shared library build will generate an error. This means you will need to install a shared library version of the auxiliary library. The build instructions for the library should tell you how to do this. Here is an example of such errors when the system FFTW or provided lib/colvars library have not been built as shared libraries: /usr/bin/ld: /usr/local/lib/libfftw3.a(mapflags.o): relocation R_X86_64_32 against '.rodata' can not be used when making a shared object; recompile with -fPIC /usr/local/lib/libfftw3.a: could not read symbols: Bad value :pre /usr/bin/ld: ../../lib/colvars/libcolvars.a(colvarmodule.o): relocation R_X86_64_32 against '__pthread_key_create' can not be used when making a shared object; recompile with -fPIC ../../lib/colvars/libcolvars.a: error adding symbols: Bad value :pre As an example, here is how to build and install the "MPICH library"_mpich, a popular open-source version of MPI, distributed by Argonne National Labs, as a shared library in the default /usr/local/lib location: :link(mpich,http://www-unix.mcs.anl.gov/mpi) ./configure --enable-shared make make install :pre You may need to use "sudo make install" in place of the last line if you do not have write privileges for /usr/local/lib. The end result should be the file /usr/local/lib/libmpich.so. [Additional requirement for using a shared library:] :h5 The operating system finds shared libraries to load at run-time using the environment variable LD_LIBRARY_PATH. So you may wish to copy the file src/liblammps.so or src/liblammps_g++.so (for example) to a place the system can find it by default, such as /usr/local/lib, or you may wish to add the LAMMPS src directory to LD_LIBRARY_PATH, so that the current version of the shared library is always available to programs that use it. For the csh or tcsh shells, you would add something like this to your ~/.cshrc file: setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre Calling the LAMMPS library :h5 Either flavor of library (static or shared) allows one or more LAMMPS objects to be instantiated from the calling program. When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS namespace; you can safely use any of its classes and methods from within the calling code, as needed. When used from a C or Fortran program or a scripting language like Python, the library has a simple function-style interface, provided in src/library.cpp and src/library.h. See the sample codes in examples/COUPLE/simple for examples of C++ and C and Fortran codes that invoke LAMMPS thru its library interface. There are other examples as well in the COUPLE directory which are discussed in "Section 6.10"_Section_howto.html#howto_10 of the manual. See "Section 11"_Section_python.html of the manual for a description of the Python wrapper provided with LAMMPS that operates through the LAMMPS library interface. The files src/library.cpp and library.h define the C-style API for using LAMMPS as a library. See "Section 6.19"_Section_howto.html#howto_19 of the manual for a description of the interface and how to extend it for your needs. :line 2.6 Running LAMMPS :h4,link(start_6) By default, LAMMPS runs by reading commands from standard input. Thus if you run the LAMMPS executable by itself, e.g. lmp_linux :pre it will simply wait, expecting commands from the keyboard. Typically you should put commands in an input script and use I/O redirection, e.g. lmp_linux < in.file :pre For parallel environments this should also work. If it does not, use the '-in' command-line switch, e.g. lmp_linux -in in.file :pre "This section"_Section_commands.html describes how input scripts are structured and what commands they contain. You can test LAMMPS on any of the sample inputs provided in the examples or bench directory. Input scripts are named in.* and sample outputs are named log.*.name.P where name is a machine and P is the number of processors it was run on. Here is how you might run a standard Lennard-Jones benchmark on a Linux box, using mpirun to launch a parallel job: cd src make linux cp lmp_linux ../bench cd ../bench mpirun -np 4 lmp_linux -in in.lj :pre See "this page"_bench for timings for this and the other benchmarks on various platforms. Note that some of the example scripts require LAMMPS to be built with one or more of its optional packages. :link(bench,http://lammps.sandia.gov/bench.html) :line On a Windows box, you can skip making LAMMPS and simply download an installer package from "here"_http://rpm.lammps.org/windows.html For running the non-MPI executable, follow these steps: Get a command prompt by going to Start->Run... , then typing "cmd". :ulb,l Move to the directory where you have your input, e.g. a copy of the [in.lj] input from the bench folder. (e.g. by typing: cd "Documents"). :l At the command prompt, type "lmp_serial -in in.lj", replacing [in.lj] with the name of your LAMMPS input script. :l :ule For the MPI version, which allows you to run LAMMPS under Windows on multiple processors, follow these steps: Download and install "MPICH2"_http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads for Windows. :ulb,l The LAMMPS Windows installer packages will automatically adjust your path for the default location of this MPI package. After the installation of the MPICH software, it needs to be integrated into the system. For this you need to start a Command Prompt in {Administrator Mode} (right click on the icon and select it). Change into the MPICH2 installation directory, then into the subdirectory [bin] and execute [smpd.exe -install]. Exit the command window. Get a new, regular command prompt by going to Start->Run... , then typing "cmd". :l Move to the directory where you have your input file (e.g. by typing: cd "Documents"). :l Then type something like this: mpiexec -localonly 4 lmp_mpi -in in.lj :pre or mpiexec -np 4 lmp_mpi -in in.lj :pre replacing in.lj with the name of your LAMMPS input script. For the latter case, you may be prompted to enter your password. :l In this mode, output may not immediately show up on the screen, so if your input script takes a long time to execute, you may need to be patient before the output shows up. :l The parallel executable can also run on a single processor by typing something like: lmp_mpi -in in.lj :pre :ule :line The screen output from LAMMPS is described in a section below. As it runs, LAMMPS also writes a log.lammps file with the same information. Note that this sequence of commands copies the LAMMPS executable (lmp_linux) to the directory with the input files. This may not be necessary, but some versions of MPI reset the working directory to where the executable is, rather than leave it as the directory where you launch mpirun from (if you launch lmp_linux on its own and not under mpirun). If that happens, LAMMPS will look for additional input files and write its output files to the executable directory, rather than your working directory, which is probably not what you want. If LAMMPS encounters errors in the input script or while running a simulation it will print an ERROR message and stop or a WARNING message and continue. See "Section 12"_Section_errors.html for a discussion of the various kinds of errors LAMMPS can or can't detect, a list of all ERROR and WARNING messages, and what to do about them. LAMMPS can run a problem on any number of processors, including a single processor. In theory you should get identical answers on any number of processors and on any machine. In practice, numerical round-off can cause slight differences and eventual divergence of molecular dynamics phase space trajectories. LAMMPS can run as large a problem as will fit in the physical memory of one or more processors. If you run out of memory, you must run on more processors or setup a smaller problem. :line 2.7 Command-line options :h4,link(start_7) At run time, LAMMPS recognizes several optional command-line switches which may be used in any order. Either the full word or a one-or-two letter abbreviation can be used: -e or -echo -h or -help -i or -in -k or -kokkos -l or -log -nc or -nocite -pk or -package -p or -partition -pl or -plog -ps or -pscreen -r or -restart -ro or -reorder -sc or -screen -sf or -suffix -v or -var :ul For example, lmp_ibm might be launched as follows: mpirun -np 16 lmp_ibm -v f tmp.out -l my.log -sc none -in in.alloy mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none -in in.alloy :pre Here are the details on the options: -echo style :pre Set the style of command echoing. The style can be {none} or {screen} or {log} or {both}. Depending on the style, each command read from the input script will be echoed to the screen and/or logfile. This can be useful to figure out which line of your script is causing an input error. The default value is {log}. The echo style can also be set by using the "echo"_echo.html command in the input script itself. -help :pre Print a brief help summary and a list of options compiled into this executable for each LAMMPS style (atom_style, fix, compute, pair_style, bond_style, etc). This can tell you if the command you want to use was included via the appropriate package at compile time. LAMMPS will print the info and immediately exit if this switch is used. -in file :pre Specify a file to use as an input script. This is an optional switch when running LAMMPS in one-partition mode. If it is not specified, LAMMPS reads its script from standard input, typically from a script via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should also work in parallel, but if it does not (in the unlikely case that an MPI implementation does not support it), then use the -in flag. Note that this is a required switch when running LAMMPS in multi-partition mode, since multiple processors cannot all read from stdin. -kokkos on/off keyword/value ... :pre Explicitly enable or disable KOKKOS support, as provided by the KOKKOS package. Even if LAMMPS is built with this package, as described above in "Section 2.3"_#start_3, this switch must be set to enable running with the KOKKOS-enabled styles the package provides. If the switch is not set (the default), LAMMPS will operate as if the KOKKOS package were not installed; i.e. you can run standard LAMMPS or with the GPU or USER-OMP packages, for testing or benchmarking purposes. Additional optional keyword/value pairs can be specified which determine how Kokkos will use the underlying hardware on your platform. These settings apply to each MPI task you launch via the "mpirun" or "mpiexec" command. You may choose to run one or more MPI tasks per physical node. Note that if you are running on a desktop machine, you typically have one physical node. On a cluster or supercomputer there may be dozens or 1000s of physical nodes. Either the full word or an abbreviation can be used for the keywords. Note that the keywords do not use a leading minus sign. I.e. the keyword is "t", not "-t". Also note that each of the keywords has a default setting. Example of when to use these options and what settings to use on different platforms is given in "Section 5.3"_Section_accelerate.html#acc_3. d or device g or gpus t or threads n or numa :ul device Nd :pre This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and if you are running with only one MPI task per node. The Nd setting is the ID of the GPU on the node to run on. By default Nd = 0. If you have multiple GPUs per node, they have consecutive IDs numbered as 0,1,2,etc. This setting allows you to launch multiple independent jobs on the node, each with a single MPI task per node, and assign each job to run on a different GPU. gpus Ng Ns :pre This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and you are running with multiple MPI tasks per node (up to one per GPU). The Ng setting is how many GPUs you will use. The Ns setting is optional. If set, it is the ID of a GPU to skip when assigning MPI tasks to GPUs. This may be useful if your desktop system reserves one GPU to drive the screen and the rest are intended for computational work like running LAMMPS. By default Ng = 1 and Ns is not set. Depending on which flavor of MPI you are running, LAMMPS will look for one of these 3 environment variables SLURM_LOCALID (various MPI variants compiled with SLURM support) MV2_COMM_WORLD_LOCAL_RANK (Mvapich) OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre which are initialized by the "srun", "mpirun" or "mpiexec" commands. The environment variable setting for each MPI rank is used to assign a unique GPU ID to the MPI task. threads Nt :pre This option assigns Nt number of threads to each MPI task for performing work when Kokkos is executing in OpenMP or pthreads mode. The default is Nt = 1, which essentially runs in MPI-only mode. If there are Np MPI tasks per physical node, you generally want Np*Nt = the number of physical cores per node, to use your available hardware optimally. This also sets the number of threads used by the host when LAMMPS is compiled with CUDA=yes. numa Nm :pre This option is only relevant when using pthreads with hwloc support. In this case Nm defines the number of NUMA regions (typicaly sockets) on a node which will be utilizied by a single MPI rank. By default Nm = 1. If this option is used the total number of worker-threads per MPI rank is threads*numa. Currently it is always almost better to assign at least one MPI rank per NUMA region, and leave numa set to its default value of 1. This is because letting a single process span multiple NUMA regions induces a significant amount of cross NUMA data traffic which is slow. -log file :pre Specify a log file for LAMMPS to write status information to. In one-partition mode, if the switch is not used, LAMMPS writes to the file log.lammps. If this switch is used, LAMMPS writes to the specified file. In multi-partition mode, if the switch is not used, a log.lammps file is created with hi-level status information. Each partition also writes to a log.lammps.N file where N is the partition ID. If the switch is specified in multi-partition mode, the hi-level logfile is named "file" and each partition also logs information to a file.N. For both one-partition and multi-partition mode, if the specified file is "none", then no log files are created. Using a "log"_log.html command in the input script will override this setting. Option -plog will override the name of the partition log files file.N. -nocite :pre Disable writing the log.cite file which is normally written to list references for specific cite-able features used during a LAMMPS run. See the "citation page"_http://lammps.sandia.gov/cite.html for more details. -package style args .... :pre Invoke the "package"_package.html command with style and args. The syntax is the same as if the command appeared at the top of the input script. For example "-package gpu 2" or "-pk gpu 2" is the same as "package gpu 2"_package.html in the input script. The possible styles and args are documented on the "package"_package.html doc page. This switch can be used multiple times, e.g. to set options for the USER-INTEL and USER-OMP packages which can be used together. Along with the "-suffix" command-line switch, this is a convenient mechanism for invoking accelerator packages and their options without having to edit an input script. -partition 8x2 4 5 ... :pre Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P processors and this switch is not used, LAMMPS runs in one partition, i.e. all P processors run a single simulation. If this switch is used, the P processors are split into separate partitions and each partition runs its own simulation. The arguments to the switch specify the number of processors in each partition. Arguments of the form MxN mean M partitions, each with N processors. Arguments of the form N mean a single partition with N processors. The sum of processors in all partitions must equal P. Thus the command "-partition 8x2 4 5" has 10 partitions and runs on a total of 25 processors. Running with multiple partitions can e useful for running "multi-replica simulations"_Section_howto.html#howto_5, where each replica runs on on one or a few processors. Note that with MPI installed on a machine (e.g. your desktop), you can run on more (virtual) processors than you have physical processors. To run multiple independent simulatoins from one input script, using multiple partitions, see "Section 6.4"_Section_howto.html#howto_4 of the manual. World- and universe-style "variables"_variable.html are useful in this context. -plog file :pre Specify the base name for the partition log files, so partition N writes log information to file.N. If file is none, then no partition log files are created. This overrides the filename specified in the -log command-line option. This option is useful when working with large numbers of partitions, allowing the partition log files to be suppressed (-plog none) or placed in a sub-directory (-plog replica_files/log.lammps) If this option is not used the log file for partition N is log.lammps.N or whatever is specified by the -log command-line option. -pscreen file :pre Specify the base name for the partition screen file, so partition N writes screen information to file.N. If file is none, then no partition screen files are created. This overrides the filename specified in the -screen command-line option. This option is useful when working with large numbers of partitions, allowing the partition screen files to be suppressed (-pscreen none) or placed in a sub-directory (-pscreen replica_files/screen). If this option is not used the screen file for partition N is screen.N or whatever is specified by the -screen command-line option. -restart restartfile {remap} datafile keyword value ... :pre Convert the restart file into a data file and immediately exit. This is the same operation as if the following 2-line input script were run: read_restart restartfile {remap} write_data datafile keyword value ... :pre Note that the specified restartfile and datafile can have wild-card characters ("*",%") as described by the "read_restart"_read_restart.html and "write_data"_write_data.html commands. But a filename such as file.* will need to be enclosed in quotes to avoid shell expansion of the "*" character. Note that following restartfile, the optional flag {remap} can be used. This has the same effect as adding it to the "read_restart"_read_restart.html command, as explained on its doc page. This is only useful if the reading of the restart file triggers an error that atoms have been lost. In that case, use of the remap flag should allow the data file to still be produced. Also note that following datafile, the same optional keyword/value pairs can be listed as used by the "write_data"_write_data.html command. -reorder nth N -reorder custom filename :pre Reorder the processors in the MPI communicator used to instantiate LAMMPS, in one of several ways. The original MPI communicator ranks all P processors from 0 to P-1. The mapping of these ranks to physical processors is done by MPI before LAMMPS begins. It may be useful in some cases to alter the rank order. E.g. to insure that cores within each node are ranked in a desired order. Or when using the "run_style verlet/split"_run_style.html command with 2 partitions to insure that a specific Kspace processor (in the 2nd partition) is matched up with a specific set of processors in the 1st partition. See the "Section 5"_Section_accelerate.html doc pages for more details. If the keyword {nth} is used with a setting {N}, then it means every Nth processor will be moved to the end of the ranking. This is useful when using the "run_style verlet/split"_run_style.html command with 2 partitions via the -partition command-line switch. The first set of processors will be in the first partition, the 2nd set in the 2nd partition. The -reorder command-line switch can alter this so that the 1st N procs in the 1st partition and one proc in the 2nd partition will be ordered consecutively, e.g. as the cores on one physical node. This can boost performance. For example, if you use "-reorder nth 4" and "-partition 9 3" and you are running on 12 processors, the processors will be reordered from 0 1 2 3 4 5 6 7 8 9 10 11 :pre to 0 1 2 4 5 6 8 9 10 3 7 11 :pre so that the processors in each partition will be 0 1 2 4 5 6 8 9 10 3 7 11 :pre See the "processors" command for how to insure processors from each partition could then be grouped optimally for quad-core nodes. If the keyword is {custom}, then a file that specifies a permutation of the processor ranks is also specified. The format of the reorder file is as follows. Any number of initial blank or comment lines (starting with a "#" character) can be present. These should be followed by P lines of the form: I J :pre where P is the number of processors LAMMPS was launched with. Note that if running in multi-partition mode (see the -partition switch above) P is the total number of processors in all partitions. The I and J values describe a permutation of the P processors. Every I and J should be values from 0 to P-1 inclusive. In the set of P I values, every proc ID should appear exactly once. Ditto for the set of P J values. A single I,J pairing means that the physical processor with rank I in the original MPI communicator will have rank J in the reordered communicator. Note that rank ordering can also be specified by many MPI implementations, either by environment variables that specify how to order physical processors, or by config files that specify what physical processors to assign to each MPI rank. The -reorder switch simply gives you a portable way to do this without relying on MPI itself. See the "processors out"_processors.html command for how to output info on the final assignment of physical processors to the LAMMPS simulation domain. -screen file :pre Specify a file for LAMMPS to write its screen information to. In one-partition mode, if the switch is not used, LAMMPS writes to the screen. If this switch is used, LAMMPS writes to the specified file instead and you will see no screen output. In multi-partition mode, if the switch is not used, hi-level status information is written to the screen. Each partition also writes to a screen.N file where N is the partition ID. If the switch is specified in multi-partition mode, the hi-level screen dump is named "file" and each partition also writes screen information to a file.N. For both one-partition and multi-partition mode, if the specified file is "none", then no screen output is performed. Option -pscreen will override the name of the partition screen files file.N. -suffix style args :pre Use variants of various styles if they exist. The specified style can be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These refer to optional packages that LAMMPS can be built with, as described above in "Section 2.3"_#start_3. The "gpu" style corresponds to the GPU package, the "intel" style to the USER-INTEL package, the "kk" style to the KOKKOS package, the "opt" style to the OPT package, and the "omp" style to the USER-OMP package. The hybrid style is the only style that accepts arguments. It allows for two packages to be specified. The first package specified is the default and will be used if it is available. If no style is available for the first package, the style for the second package will be used if available. For example, "-suffix hybrid intel omp" will use styles from the USER-INTEL package if they are installed and available, but styles for the USER-OMP package otherwise. Along with the "-package" command-line switch, this is a convenient mechanism for invoking accelerator packages and their options without having to edit an input script. As an example, all of the packages provide a "pair_style lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style can be specified explicitly in your input script, e.g. pair_style lj/cut/gpu. If the -suffix switch is used the specified suffix (gpu,intel,kk,omp,opt) is automatically appended whenever your input script command creates a new "atom"_atom_style.html, "pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or "run"_run_style.html style. If the variant version does not exist, the standard version is created. For the GPU package, using this command-line switch also invokes the default GPU settings, as if the command "package gpu 1" were used at the top of your input script. These settings can be changed by using the "-package gpu" command-line switch or the "package gpu"_package.html command in your script. For the USER-INTEL package, using this command-line switch also invokes the default USER-INTEL settings, as if the command "package intel 1" were used at the top of your input script. These settings can be changed by using the "-package intel" command-line switch or the "package intel"_package.html command in your script. If the USER-OMP package is also installed, the hybrid style with "intel omp" arguments can be used to make the omp suffix a second choice, if a requested style is not available in the USER-INTEL package. It will also invoke the default USER-OMP settings, as if the command "package omp 0" were used at the top of your input script. These settings can be changed by using the "-package omp" command-line switch or the "package omp"_package.html command in your script. For the KOKKOS package, using this command-line switch also invokes the default KOKKOS settings, as if the command "package kokkos" were used at the top of your input script. These settings can be changed by using the "-package kokkos" command-line switch or the "package kokkos"_package.html command in your script. For the OMP package, using this command-line switch also invokes the default OMP settings, as if the command "package omp 0" were used at the top of your input script. These settings can be changed by using the "-package omp" command-line switch or the "package omp"_package.html command in your script. The "suffix"_suffix.html command can also be used within an input script to set a suffix, or to turn off or back on any suffix setting made via the command line. -var name value1 value2 ... :pre Specify a variable that will be defined for substitution purposes when the input script is read. This switch can be used multiple times to define multiple variables. "Name" is the variable name which can be a single character (referenced as $x in the input script) or a full string (referenced as $\{abc\}). An "index-style variable"_variable.html will be created and populated with the subsequent values, e.g. a set of filenames. Using this command-line option is equivalent to putting the line "variable name index value1 value2 ..." at the beginning of the input script. Defining an index variable as a command-line argument overrides any setting for the same index variable in the input script, since index variables cannot be re-defined. See the "variable"_variable.html command for more info on defining index and other kinds of variables and "this section"_Section_commands.html#cmd_2 for more info on using variables in input scripts. NOTE: Currently, the command-line parser looks for arguments that start with "-" to indicate new switches. Thus you cannot specify multiple variable values if any of they start with a "-", e.g. a negative numeric value. It is OK if the first value1 starts with a "-", since it is automatically skipped. :line 2.8 LAMMPS screen output :h4,link(start_8) As LAMMPS reads an input script, it prints information to both the screen and a log file about significant actions it takes to setup a simulation. When the simulation is ready to begin, LAMMPS performs various initializations and prints the amount of memory (in MBytes per processor) that the simulation requires. It also prints details of the initial thermodynamic state of the system. During the run itself, thermodynamic information is printed periodically, every few timesteps. When the run concludes, LAMMPS prints the final thermodynamic state and a total run time for the simulation. It then appends statistics about the CPU time and storage requirements for the simulation. An example set of statistics is shown here: Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s 97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre MPI task timings breakdown: Section | min time | avg time | max time |%varavg| %total --------------------------------------------------------------- Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 Other | | 0.007178 | | | 0.26 :pre Nlocal: 501 ave 508 max 490 min Histogram: 1 0 0 0 0 0 1 1 0 1 Nghost: 6586.25 ave 6628 max 6548 min Histogram: 1 0 1 0 0 0 1 0 0 1 Neighs: 177007 ave 180562 max 170212 min Histogram: 1 0 0 0 0 0 0 1 1 1 :pre Total # of neighbors = 708028 Ave neighs/atom = 353.307 Ave special neighs/atom = 2.34032 Neighbor list builds = 26 Dangerous builds = 0 :pre The first section provides a global loop timing summary. The loop time is the total wall time for the section. The {Performance} line is provided for convenience to help predicting the number of loop continuations required and for comparing performance with other similar MD codes. The CPU use line provides the CPU utilzation per MPI task; it should be close to 100% times the number of OpenMP threads (or 1). Lower numbers correspond to delays due to file I/O or insufficient thread utilization. The MPI task section gives the breakdown of the CPU run time (in seconds) into major categories: {Pair} stands for all non-bonded force computation {Bond} stands for bonded interactions: bonds, angles, dihedrals, impropers {Kspace} stands for reciprocal space interactions: Ewald, PPPM, MSM {Neigh} stands for neighbor list construction {Comm} stands for communicating atoms and their properties {Output} stands for writing dumps and thermo output {Modify} stands for fixes and computes called by them {Other} is the remaining time :ul For each category, there is a breakdown of the least, average and most amount of wall time a processor spent on this section. Also you have the variation from the average time. Together these numbers allow to gauge the amount of load imbalance in this segment of the calculation. Ideally the difference between minimum, maximum and average is small and thus the variation from the average close to zero. The final column shows the percentage of the total loop time is spent in this section. When using the "timer full"_timer.html setting, an additional column is present that also prints the CPU utilization in percent. In addition, when using {timer full} and the "package omp"_package.html command are active, a similar timing summary of time spent in threaded regions to monitor thread utilization and load balance is provided. A new entry is the {Reduce} section, which lists the time spend in reducing the per-thread data elements to the storage for non-threaded computation. These thread timings are taking from the first MPI rank only and and thus, as the breakdown for MPI tasks can change from MPI rank to MPI rank, this breakdown can be very different for individual ranks. Here is an example output for this section: Thread timings breakdown (MPI rank 0): Total threaded time 0.6846 / 90.6% Section | min time | avg time | max time |%varavg| %total --------------------------------------------------------------- Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre The third section lists the number of owned atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored per processor. The max and min values give the spread of these values across processors with a 10-bin histogram showing the distribution. The total number of histogram counts is equal to the number of processors. The last section gives aggregate statistics for pair-wise neighbors and special neighbors that LAMMPS keeps track of (see the "special_bonds"_special_bonds.html command). The number of times neighbor lists were rebuilt during the run is given as well as the number of potentially "dangerous" rebuilds. If atom movement triggered neighbor list rebuilding (see the "neigh_modify"_neigh_modify.html command), then dangerous reneighborings are those that were triggered on the first timestep atom movement was checked for. If this count is non-zero you may wish to reduce the delay factor to insure no force interactions are missed by atoms moving beyond the neighbor skin distance before a rebuild takes place. If an energy minimization was performed via the "minimize"_minimize.html command, additional information is printed, e.g. Minimization stats: Stopping criterion = linesearch alpha is zero Energy initial, next-to-last, final = -6372.3765206 -8328.46998942 -8328.46998942 Force two-norm initial, final = 1059.36 5.36874 Force max component initial, final = 58.6026 1.46872 Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 Iterations, force evaluations = 701 1516 :pre The first line prints the criterion that determined the minimization to be completed. The third line lists the initial and final energy, as well as the energy on the next-to-last iteration. The next 2 lines give a measure of the gradient of the energy (force on all atoms). The 2-norm is the "length" of this force vector; the inf-norm is the largest component. Then some information about the line search and statistics on how many iterations and force-evaluations the minimizer required. Multiple force evaluations are typically done at each iteration to perform a 1d line minimization in the search direction. If a "kspace_style"_kspace_style.html long-range Coulombics solve was performed during the run (PPPM, Ewald), then additional information is printed, e.g. FFT time (% of Kspce) = 0.200313 (8.34477) FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre The first line gives the time spent doing 3d FFTs (4 per timestep) and the fraction it represents of the total KSpace time (listed above). Each 3d FFT requires computation (3 sets of 1d FFTs) and communication (transposes). The total flops performed is 5Nlog_2(N), where N is the number of points in the 3d grid. The FFTs are timed with and without the communication and a Gflop rate is computed. The 3d rate is with communication; the 1d rate is without (just the 1d FFTs). Thus you can estimate what fraction of your FFT time was spent in communication, roughly 75% in the example above. :line 2.9 Tips for users of previous LAMMPS versions :h4,link(start_9) The current C++ began with a complete rewrite of LAMMPS 2001, which was written in F90. Features of earlier versions of LAMMPS are listed in "Section 13"_Section_history.html. The F90 and F77 versions (2001 and 99) are also freely distributed as open-source codes; check the "LAMMPS WWW Site"_lws for distribution information if you prefer those versions. The 99 and 2001 versions are no longer under active development; they do not have all the features of C++ LAMMPS. If you are a previous user of LAMMPS 2001, these are the most significant changes you will notice in C++ LAMMPS: (1) The names and arguments of many input script commands have changed. All commands are now a single word (e.g. read_data instead of read data). (2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS, but you may need to specify the relevant commands in different ways. (3) The format of the data file can be streamlined for some problems. See the "read_data"_read_data.html command for details. The data file section "Nonbond Coeff" has been renamed to "Pair Coeff" in C++ LAMMPS. (4) Binary restart files written by LAMMPS 2001 cannot be read by C++ LAMMPS with a "read_restart"_read_restart.html command. This is because they were output by F90 which writes in a different binary format than C or C++ writes or reads. Use the {restart2data} tool provided with LAMMPS 2001 to convert the 2001 restart file to a text data file. Then edit the data file as necessary before using the C++ LAMMPS "read_data"_read_data.html command to read it in. (5) There are numerous small numerical changes in C++ LAMMPS that mean you will not get identical answers when comparing to a 2001 run. However, your initial thermodynamic energy and MD trajectory should be close if you have setup the problem for both codes the same. diff --git a/doc/src/compute_centro_atom.txt b/doc/src/compute_centro_atom.txt index 2a3ae15aa..0a48ccb5b 100644 --- a/doc/src/compute_centro_atom.txt +++ b/doc/src/compute_centro_atom.txt @@ -1,151 +1,151 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute centro/atom command :h3 [Syntax:] compute ID group-ID centro/atom lattice keyword value ... :pre ID, group-ID are documented in "compute"_compute.html command centro/atom = style name of this compute command lattice = {fcc} or {bcc} or N = # of neighbors per atom to include :l zero or more keyword/value pairs may be appended :l keyword = {axes} :l {axes} value = {no} or {yes} {no} = do not calulate 3 symmetry axes {yes} = calulate 3 symmetry axes :pre :ule [Examples:] compute 1 all centro/atom fcc :pre compute 1 all centro/atom 8 :pre [Description:] Define a computation that calculates the centro-symmetry parameter for each atom in the group, for either FCC or BCC lattices, depending on the choice of the {lattice} argument. In solid-state systems the centro-symmetry parameter is a useful measure of the local lattice disorder around an atom and can be used to characterize whether the atom is part of a perfect lattice, a local defect (e.g. a dislocation or stacking fault), or at a surface. The value of the centro-symmetry parameter will be 0.0 for atoms not in the specified compute group. This parameter is computed using the following formula from "(Kelchner)"_#Kelchner :c,image(Eqs/centro_symmetry.jpg) where the {N} nearest neighbors of each atom are identified and Ri and Ri+N/2 are vectors from the central atom to a particular pair of nearest neighbors. There are N*(N-1)/2 possible neighbor pairs that can contribute to this formula. The quantity in the sum is computed for each, and the N/2 smallest are used. This will typically be for pairs of atoms in symmetrically opposite positions with respect to the central atom; hence the i+N/2 notation. {N} is an input parameter, which should be set to correspond to the number of nearest neighbors in the underlying lattice of atoms. If the keyword {fcc} or {bcc} is used, {N} is set to 12 and 8 respectively. More generally, {N} can be set to a positive, even integer. For an atom on a lattice site, surrounded by atoms on a perfect lattice, the centro-symmetry parameter will be 0. It will be near 0 for small thermal perturbations of a perfect lattice. If a point defect exists, the symmetry is broken, and the parameter will be a larger positive value. An atom at a surface will have a large positive parameter. If the atom does not have {N} neighbors (within the potential cutoff), then its centro-symmetry parameter is set to 0.0. If the keyword {axes} has the setting {yes}, then this compute also estimates three symmetry axes for each atom's local neighborhood. The first two of these are the vectors joining the two pairs of neighbor atoms with smallest contributions to the centrosymmetry parameter, i.e. the two most symmetric pairs of atoms. The third vector is normal to the first two by the right-hand rule. All three vectors are normalized to unit length. For FCC crystals, the first two vectors will lie along a <110> direction, while the third vector will lie along either a <100> or <111> direction. For HCP crystals, the first two vectors will lie along <1000> directions, while the third vector will lie along <0001>. This provides a simple way to measure local orientation in HCP structures. In general, the {axes} keyword can be used to estimate the orientation of symmetry axes in the neighborhood of any atom. Only atoms within the cutoff of the pairwise neighbor list are considered as possible neighbors. Atoms not in the compute group are included in the {N} neighbors used in this calculation. The neighbor list needed to compute this quantity is constructed each time the calculation is performed (e.g. each time a snapshot of atoms is dumped). Thus it can be inefficient to compute/dump this quantity too frequently or to have multiple compute/dump commands, each with a {centro/atom} style. [Output info:] By default, this compute calculates the centrosymmetry value for each atom as a per-atom vector, which can be accessed by any command that uses per-atom values from a compute as input. See "Section 6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. If the {axes} keyword setting is {yes}, then a per-atom array is calculated. The first column is the centrosymmetry parameter. The next three columns are the x, y, and z components of the first symmetry axis, followed by the second, and third symmetry axes in columns 5-7 and 8-10. The centrosymmetry values are unitless values >= 0.0. Their magnitude depends on the lattice style due to the number of contibuting neighbor pairs in the summation in the formula above. And it depends on the local defects surrounding the central atom, as described above. For the {axes yes} case, the vector components are also unitless, since they represent spatial directions. -Here are typical centro-symmetry values, from a a nanoindentation +Here are typical centro-symmetry values, from a nanoindentation simulation into gold (FCC). These were provided by Jon Zimmerman (Sandia): Bulk lattice = 0 Dislocation core ~ 1.0 (0.5 to 1.25) Stacking faults ~ 5.0 (4.0 to 6.0) Free surface ~ 23.0 :pre These values are *not* normalized by the square of the lattice parameter. If they were, normalized values would be: Bulk lattice = 0 Dislocation core ~ 0.06 (0.03 to 0.075) Stacking faults ~ 0.3 (0.24 to 0.36) Free surface ~ 1.38 :pre For BCC materials, the values for dislocation cores and free surfaces would be somewhat different, due to their being only 8 neighbors instead of 12. [Restrictions:] none [Related commands:] "compute cna/atom"_compute_cna_atom.html [Default:] The default value for the optional keyword is axes = no. :line :link(Kelchner) [(Kelchner)] Kelchner, Plimpton, Hamilton, Phys Rev B, 58, 11085 (1998). diff --git a/doc/src/compute_stress_atom.txt b/doc/src/compute_stress_atom.txt index dcfdee9f8..3dc642da3 100644 --- a/doc/src/compute_stress_atom.txt +++ b/doc/src/compute_stress_atom.txt @@ -1,169 +1,169 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute stress/atom command :h3 [Syntax:] compute ID group-ID stress/atom temp-ID keyword ... :pre ID, group-ID are documented in "compute"_compute.html command stress/atom = style name of this compute command temp-ID = ID of compute that calculates temperature, can be NULL if not needed zero or more keywords may be appended keyword = {ke} or {pair} or {bond} or {angle} or {dihedral} or {improper} or {kspace} or {fix} or {virial} :ul [Examples:] compute 1 mobile stress/atom NULL compute 1 mobile stress/atom myRamp compute 1 all stress/atom NULL pair bond :pre [Description:] Define a computation that computes the symmetric per-atom stress tensor for each atom in a group. The tensor for each atom has 6 components and is stored as a 6-element vector in the following order: xx, yy, zz, xy, xz, yz. See the "compute pressure"_compute_pressure.html command if you want the stress tensor (pressure) of the entire system. The stress tensor for atom {I} is given by the following formula, where {a} and {b} take on values x,y,z to generate the 6 components of the symmetric tensor: :c,image(Eqs/stress_tensor.jpg) The first term is a kinetic energy contribution for atom {I}. See details below on how the specified {temp-ID} can affect the velocities used in this calculation. The second term is a pairwise energy contribution where {n} loops over the {Np} neighbors of atom {I}, {r1} and {r2} are the positions of the 2 atoms in the pairwise interaction, and {F1} and {F2} are the forces on the 2 atoms resulting from the pairwise interaction. The third term is a bond contribution of similar form for the {Nb} bonds which atom {I} is part of. There are similar terms for the {Na} angle, {Nd} dihedral, and {Ni} improper interactions atom {I} is part of. There is also a term for the KSpace contribution from long-range Coulombic interactions, if defined. Finally, there is a term for the {Nf} "fixes"_fix.html that apply internal constraint forces to atom {I}. Currently, only the "fix shake"_fix_shake.html and "fix rigid"_fix_rigid.html commands contribute to this term. As the coefficients in the formula imply, a virial contribution produced by a small set of atoms (e.g. 4 atoms in a dihedral or 3 atoms in a Tersoff 3-body interaction) is assigned in equal portions to each atom in the set. E.g. 1/4 of the dihedral virial to each of the 4 atoms, or 1/3 of the fix virial due to SHAKE constraints applied -to atoms in a a water molecule via the "fix shake"_fix_shake.html +to atoms in a water molecule via the "fix shake"_fix_shake.html command. If no extra keywords are listed, all of the terms in this formula are included in the per-atom stress tensor. If any extra keywords are listed, only those terms are summed to compute the tensor. The {virial} keyword means include all terms except the kinetic energy {ke}. Note that the stress for each atom is due to its interaction with all other atoms in the simulation, not just with other atoms in the group. Details of how LAMMPS computes the virial for individual atoms for either pairwise or manybody potentials, and including the effects of periodic boundary conditions is discussed in "(Thompson)"_#Thompson. The basic idea for manybody potentials is to treat each component of the force computation between a small cluster of atoms in the same manner as in the formula above for bond, angle, dihedral, etc interactions. Namely the quantity R dot F is summed over the atoms in the interaction, with the R vectors unwrapped by periodic boundaries so that the cluster of atoms is close together. The total contribution for the cluster interaction is divided evenly among those atoms. The "dihedral_style charmm"_dihedral_charmm.html style calculates pairwise interactions between 1-4 atoms. The virial contribution of these terms is included in the pair virial, not the dihedral virial. The KSpace contribution is calculated using the method in "(Heyes)"_#Heyes for the Ewald method and by the methodology described in "(Sirk)"_#Sirk for PPPM. The choice of KSpace solver is specified by the "kspace_style pppm"_kspace_style.html command. Note that for PPPM, the calcluation requires 6 extra FFTs each timestep that per-atom stress is calculated. Thus it can significantly increase the cost of the PPPM calculation if it is needed on a large fraction of the simulation timesteps. The {temp-ID} argument can be used to affect the per-atom velocities used in the kinetic energy contribution to the total stress. If the kinetic energy is not included in the stress, than the temperature compute is not used and can be specified as NULL. If the kinetic energy is included and you wish to use atom velocities as-is, then {temp-ID} can also be specified as NULL. If desired, the specified temperature compute can be one that subtracts off a bias to leave each atom with only a thermal velocity to use in the formula above, e.g. by subtracting a background streaming velocity. See the doc pages for individual "compute commands"_compute.html to determine which ones include a bias. :line Note that as defined in the formula, per-atom stress is the negative of the per-atom pressure tensor. It is also really a stress*volume formulation, meaning the computed quantity is in units of pressure*volume. It would need to be divided by a per-atom volume to have units of stress (pressure), but an individual atom's volume is not well defined or easy to compute in a deformed solid or a liquid. See the "compute voronoi/atom"_compute_voronoi_atom.html command for one possible way to estimate a per-atom volume. Thus, if the diagonal components of the per-atom stress tensor are summed for all atoms in the system and the sum is divided by dV, where d = dimension and V is the volume of the system, the result should be -P, where P is the total pressure of the system. These lines in an input script for a 3d system should yield that result. I.e. the last 2 columns of thermo output will be the same: compute peratom all stress/atom NULL compute p all reduce sum c_peratom\[1\] c_peratom\[2\] c_peratom\[3\] variable press equal -(c_p\[1\]+c_p\[2\]+c_p\[3\])/(3*vol) thermo_style custom step temp etotal press v_press :pre NOTE: The per-atom stress does not include any Lennard-Jones tail corrections to the pressure added by the "pair_modify tail yes"_pair_modify.html command, since those are contributions to the global system pressure. [Output info:] This compute calculates a per-atom array with 6 columns, which can be accessed by indices 1-6 by any command that uses per-atom values from a compute as input. See "Section 6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The per-atom array values will be in pressure*volume "units"_units.html as discussed above. [Restrictions:] none [Related commands:] "compute pe"_compute_pe.html, "compute pressure"_compute_pressure.html [Default:] none :line :link(Heyes) [(Heyes)] Heyes, Phys Rev B 49, 755 (1994), :link(Sirk) [(Sirk)] Sirk, Moore, Brown, J Chem Phys, 138, 064505 (2013). :link(Thompson) [(Thompson)] Thompson, Plimpton, Mattson, J Chem Phys, 131, 154107 (2009). diff --git a/doc/src/dump_modify.txt b/doc/src/dump_modify.txt index e2f5f1eb8..e70feedcf 100644 --- a/doc/src/dump_modify.txt +++ b/doc/src/dump_modify.txt @@ -1,996 +1,996 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line dump_modify command :h3 [Syntax:] dump_modify dump-ID keyword values ... :pre dump-ID = ID of dump to modify :ulb,l one or more keyword/value pairs may be appended :l these keywords apply to various dump styles :l keyword = {append} or {buffer} or {element} or {every} or {fileper} or {first} or {flush} or {format} or {image} or {label} or {nfile} or {pad} or {precision} or {region} or {scale} or {sort} or {thresh} or {unwrap} :l {append} arg = {yes} or {no} {buffer} arg = {yes} or {no} {element} args = E1 E2 ... EN, where N = # of atom types E1,...,EN = element name, e.g. C or Fe or Ga {every} arg = N N = dump every this many timesteps N can be a variable (see below) {fileper} arg = Np Np = write one file for every this many processors {first} arg = {yes} or {no} {format} args = {line} string, {int} string, {float} string, M string, or {none} string = C-style format string M = integer from 1 to N, where N = # of per-atom quantities being output {flush} arg = {yes} or {no} {image} arg = {yes} or {no} {label} arg = string string = character string (e.g. BONDS) to use in header of dump local file {nfile} arg = Nf Nf = write this many files, one from each of Nf processors {pad} arg = Nchar = # of characters to convert timestep to {pbc} arg = {yes} or {no} = remap atoms via periodic boundary conditions {precision} arg = power-of-10 value from 10 to 1000000 {region} arg = region-ID or "none" {scale} arg = {yes} or {no} {sfactor} arg = coordinate scaling factor (> 0.0) {tfactor} arg = time scaling factor (> 0.0) {sort} arg = {off} or {id} or N or -N off = no sorting of per-atom lines within a snapshot id = sort per-atom lines by atom ID N = sort per-atom lines in ascending order by the Nth column -N = sort per-atom lines in descending order by the Nth column {thresh} args = attribute operator value attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "|^" value = numeric value to compare to, or LAST these 3 args can be replaced by the word "none" to turn off thresholding {unwrap} arg = {yes} or {no} :pre these keywords apply only to the {image} and {movie} "styles"_dump_image.html :l keyword = {acolor} or {adiam} or {amap} or {backcolor} or {bcolor} or {bdiam} or {boxcolor} or {color} or {bitrate} or {framerate} :l {acolor} args = type color type = atom type or range of types (see below) color = name of color or color1/color2/... {adiam} args = type diam type = atom type or range of types (see below) diam = diameter of atoms of that type (distance units) {amap} args = lo hi style delta N entry1 entry2 ... entryN lo = number or {min} = lower bound of range of color map hi = number or {max} = upper bound of range of color map style = 2 letters = "c" or "d" or "s" plus "a" or "f" "c" for continuous "d" for discrete "s" for sequential "a" for absolute "f" for fractional delta = binsize (only used for style "s", otherwise ignored) binsize = range is divided into bins of this width N = # of subsequent entries entry = value color (for continuous style) value = number or {min} or {max} = single value within range color = name of color used for that value entry = lo hi color (for discrete style) lo/hi = number or {min} or {max} = lower/upper bound of subset of range color = name of color used for that subset of values entry = color (for sequential style) color = name of color used for a bin of values {backcolor} arg = color color = name of color for background {bcolor} args = type color type = bond type or range of types (see below) color = name of color or color1/color2/... {bdiam} args = type diam type = bond type or range of types (see below) diam = diameter of bonds of that type (distance units) {boxcolor} arg = color color = name of color for simulation box lines and processor sub-domain lines {color} args = name R G B name = name of color R,G,B = red/green/blue numeric values from 0.0 to 1.0 {bitrate} arg = rate rate = target bitrate for movie in kbps {framerate} arg = fps fps = frames per second for movie :pre :ule [Examples:] dump_modify 1 format line "%d %d %20.15g %g %g" scale yes dump_modify 1 format float %20.15g scale yes dump_modify myDump image yes scale no flush yes dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2 dump_modify xtcdump precision 10000 sfactor 0.1 dump_modify 1 every 1000 nfile 20 dump_modify 1 every v_myVar dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red :pre [Description:] Modify the parameters of a previously defined dump command. Not all parameters are relevant to all dump styles. As explained on the "dump"_dump.html doc page, the {atom/mpiio}, {custom/mpiio}, and {xyz/mpiio} dump styles are identical in command syntax and in the format of the dump files they create, to the corresponding styles without "mpiio", except the single dump file they produce is written in parallel via the MPI-IO library. Thus if a dump_modify option below is valid for the {atom} style, it is also valid for the {atom/mpiio} style, and similarly for the other styles which allow for use of MPI-IO. :line :line These keywords apply to various dump styles, including the "dump image"_dump_image.html and "dump movie"_dump_image.html styles. The description gives details. :line The {append} keyword applies to all dump styles except {cfg} and {xtc} and {dcd}. It also applies only to text output files, not to binary or gzipped or image/movie files. If specified as {yes}, then dump snapshots are appended to the end of an existing dump file. If specified as {no}, then a new dump file will be created which will overwrite an existing file with the same name. This keyword can only take effect if the dump_modify command is used after the "dump"_dump.html command, but before the first command that causes dump snapshots to be output, e.g. a "run"_run.html or "minimize"_minimize.html command. Once the dump file has been opened, this keyword has no further effect. :line The {buffer} keyword applies only to dump styles {atom}, {cfg}, {custom}, {local}, and {xyz}. It also applies only to text output files, not to binary or gzipped files. If specified as {yes}, which is the default, then each processor writes its output into an internal text buffer, which is then sent to the processor(s) which perform file writes, and written by those processors(s) as one large chunk of text. If specified as {no}, each processor sends its per-atom data in binary format to the processor(s) which perform file wirtes, and those processor(s) format and write it line by line into the output file. The buffering mode is typically faster since each processor does the relatively expensive task of formatting the output for its own atoms. However it requires about twice the memory (per processor) for the extra buffering. :line The {element} keyword applies only to the the dump {cfg}, {xyz}, and {image} styles. It associates element names (e.g. H, C, Fe) with LAMMPS atom types. See the list of element names at the bottom of this page. In the case of dump {cfg}, this allows the "AtomEye"_atomeye visualization package to read the dump file and render atoms with the appropriate size and color. In the case of dump {image}, the output images will follow the same "AtomEye"_atomeye convention. An element name is specified for each atom type (1 to Ntype) in the simulation. The same element name can be given to multiple atom types. In the case of {xyz} format dumps, there are no restrictions to what label can be used as an element name. Any whitespace separated text will be accepted. :link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A) :line The {every} keyword changes the dump frequency originally specified by the "dump"_dump.html command to a new value. The every keyword can be specified in one of two ways. It can be a numeric value in which case it must be > 0. Or it can be an "equal-style variable"_variable.html, which should be specified as v_name, where name is the variable name. In this case, the variable is evaluated at the beginning of a run to determine the next timestep at which a dump snapshot will be written out. On that timestep the variable will be evaluated again to determine the next timestep, etc. Thus the variable should return timestep values. See the stagger() and logfreq() and stride() math functions for "equal-style variables"_variable.html, as examples of useful functions to use in this context. Other similar math functions could easily be added as options for "equal-style variables"_variable.html. Also see the next() function, which allows use of a file-style variable which reads successive values from a file, each time the variable is evaluated. Used with the {every} keyword, if the file contains a list of ascending timesteps, you can output snapshots whenever you wish. Note that when using the variable option with the {every} keyword, you need to use the {first} option if you want an initial snapshot written to the dump file. The {every} keyword cannot be used with the dump {dcd} style. For example, the following commands will write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc: variable s equal logfreq(10,3,10) dump 1 all atom 100 tmp.dump dump_modify 1 every v_s first yes :pre The following commands would write snapshots at the timesteps listed in file tmp.times: variable f file tmp.times variable s equal next(f) dump 1 all atom 100 tmp.dump dump_modify 1 every v_s :pre NOTE: When using a file-style variable with the {every} keyword, the file of timesteps must list a first timestep that is beyond the current timestep (e.g. it cannot be 0). And it must list one or more timesteps beyond the length of the run you perform. This is because the dump command will generate an error if the next timestep it reads from the file is not a value greater than the current timestep. Thus if you wanted output on steps 0,15,100 of a 100-timestep run, the file should contain the values 15,100,101 and you should also use the dump_modify first command. Any final value > 100 could be used in place of 101. :line The {first} keyword determines whether a dump snapshot is written on the very first timestep after the dump command is invoked. This will always occur if the current timestep is a multiple of N, the frequency specified in the "dump"_dump.html command, including timestep 0. But if this is not the case, a dump snapshot will only be written if the setting of this keyword is {yes}. If it is {no}, which is the default, then it will not be written. :line The {flush} keyword determines whether a flush operation is invoked after a dump snapshot is written to the dump file. A flush insures the output in that file is current (no buffering by the OS), even if LAMMPS halts before the simulation completes. Flushes cannot be performed with dump style {xtc}. :line The {format} keyword can be used to change the default numeric format output by the text-based dump styles: {atom}, {custom}, {cfg}, and {xyz} styles, and their MPIIO variants. Only the {line} or {none} options can be used with the {atom} and {xyz} styles. All the specified format strings are C-style formats, e.g. as used by the C/C++ printf() command. The {line} keyword takes a single argument which is the format string for an entire line of output for each atom (do not include a trailing "\n"), with N fields, which you must enclose in quotes if it is more than one field. The {int} and {float} keywords take a single format argument and are applied to all integer or floating-point quantities output. The setting for {M string} also takes a single format argument which is used for the Mth value output in each line, e.g. the 5th column is output in high precision for "format 5 %20.15g". NOTE: When using the {line} keyword for the {cfg} style, the first two fields (atom ID and type) are not actually written into the CFG file, however you must include formats for them in the format string. The {format} keyword can be used multiple times. The precedence is that for each value in a line of output, the {M} format (if specified) is used, else the {int} or {float} setting (if specified) is used, else the {line} setting (if specified) for that value is used, else the default setting is used. A setting of {none} clears all previous settings, reverting all values to their default format. NOTE: Atom and molecule IDs are stored internally as 4-byte or 8-byte signed integers, depending on how LAMMPS was compiled. When specifying the {format int} option you can use a "%d"-style format identifier in the format string and LAMMPS will convert this to the corresponding 8-byte form it it is needed when outputting those values. However, when specifying the {line} option or {format M string} option for those values, you should specify a format string appropriate for an 8-byte signed integer, e.g. one with "%ld", if LAMMPS was compiled with the -DLAMMPS_BIGBIG option for 8-byte IDs. NOTE: Any value written to a text-based dump file that is a per-atom quantity calculated by a "compute"_compute.html or "fix"_fix.html is stored internally as a floating-point value. If the value is actually an integer and you wish it to appear in the text dump file as a (large) integer, then you need to use an appropriate format. For example, these commands: compute 1 all property/local batom1 batom2 dump 1 all local 100 tmp.bonds index c_1\[1\] c_1\[2\] dump_modify 1 format "%d %0.0f %0.0f" :pre will output the two atom IDs for atoms in each bond as integers. If the dump_modify command were omitted, they would appear as floating-point values, assuming they were large integers (more than 6 digits). The "index" keyword should use the "%d" format since it is not generated by a compute or fix, and is stored internally as an integer. :line The {fileper} keyword is documented below with the {nfile} keyword. :line The {image} keyword applies only to the dump {atom} style. If the image value is {yes}, 3 flags are appended to each atom's coords which are the absolute box image of the atom in each dimension. For example, an x image flag of -2 with a normalized coord of 0.5 means the atom is in the center of the box, but has passed thru the box boundary 2 times and is really 2 box lengths to the left of its current coordinate. Note that for dump style {custom} these various values can be printed in the dump file by using the appropriate atom attributes in the dump command itself. :line The {label} keyword applies only to the dump {local} style. When it writes local information, such as bond or angle topology to a dump file, it will use the specified {label} to format the header. By default this includes 2 lines: ITEM: NUMBER OF ENTRIES ITEM: ENTRIES ... :pre The word "ENTRIES" will be replaced with the string specified, e.g. BONDS or ANGLES. :line The {nfile} or {fileper} keywords can be used in conjunction with the "%" wildcard character in the specified dump file name, for all dump styles except the {dcd}, {image}, {movie}, {xtc}, and {xyz} styles (for which "%" is not allowed). As explained on the "dump"_dump.html command doc page, the "%" character causes the dump file to be written in pieces, one piece for each of P processors. By default P = the number of processors the simulation is running on. The {nfile} or {fileper} keyword can be used to set P to a smaller value, which can be more efficient when running on a large number of processors. The {nfile} keyword sets P to the specified Nf value. For example, if Nf = 4, and the simulation is running on 100 processors, 4 files will be written, by processors 0,25,50,75. Each will collect information from itself and the next 24 processors and write it to a dump file. For the {fileper} keyword, the specified value of Np means write one file for every Np processors. For example, if Np = 4, every 4th processor (0,4,8,12,etc) will collect information from itself and the next 3 processors and write it to a dump file. :line The {pad} keyword only applies when the dump filename is specified with a wildcard "*" character which becomes the timestep. If {pad} is 0, which is the default, the timestep is converted into a string of unpadded length, e.g. 100 or 12000 or 2000000. When {pad} is specified with {Nchar} > 0, the string is padded with leading zeroes so they are all the same length = {Nchar}. For example, pad 7 would yield 0000100, 0012000, 2000000. This can be useful so that post-processing programs can easily read the files in ascending timestep order. :line The {pbc} keyword applies to all the dump styles. As explained on the "dump"_dump.html doc page, atom coordinates in a dump file may be slightly outside the simulation box. This is because periodic boundary conditions are enforced only on timesteps when neighbor lists are rebuilt, which will not typically coincide with the timesteps dump snapshots are written. If the setting of this keyword is set to {yes}, then all atoms will be remapped to the periodic box before the snapshot is written, then restored to their original position. If it is set to {no} they will not be. The {no} setting is the default because it requires no extra computation. :line The {precision} keyword only applies to the dump {xtc} style. A specified value of N means that coordinates are stored to 1/N nanometer accuracy, e.g. for N = 1000, the coordinates are written to 1/1000 nanometer accuracy. :line The {sfactor} and {tfactor} keywords only apply to the dump {xtc} style. They allow customization of the unit conversion factors used when writing to XTC files. By default they are initialized for whatever "units"_units.html style is being used, to write out coordinates in nanometers and time in picoseconds. I.e. for {real} units, LAMMPS defines {sfactor} = 0.1 and {tfactor} = 0.001, since the Angstroms and fmsec used by {real} units are 0.1 nm and 0.001 psec respectively. If you are using a units system with distance and time units far from nm and psec, you may wish to write XTC files with different units, since the compression algorithm used in XTC files is most effective when the typical magnitude of position data is between 10.0 and 0.1. :line The {region} keyword only applies to the dump {custom}, {cfg}, {image}, and {movie} styles. If specified, only atoms in the region will be written to the dump file or included in the image/movie. Only one region can be applied as a filter (the last one specified). See the "region"_region.html command for more details. Note that a region can be defined as the "inside" or "outside" of a geometric shape, and it can be the "union" or "intersection" of a series of simpler regions. :line The {scale} keyword applies only to the dump {atom} style. A scale value of {yes} means atom coords are written in normalized units from 0.0 to 1.0 in each box dimension. If the simluation box is triclinic (tilted), then all atom coords will still be between 0.0 and 1.0. A value of {no} means they are written in absolute distance units (e.g. Angstroms or sigma). :line 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 {id} means sort the output by atom ID. A sort value of N or -N means sort the output by the value in the Nth column of per-atom info in either ascending or descending order. 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. If multiple processors are writing the dump file, via the "%" wildcard in the dump filename, then sorting cannot be performed. 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, versus unsorted output. :line The {thresh} keyword only applies to the dump {custom}, {cfg}, {image}, and {movie} styles. Multiple thresholds can be specified. Specifying {none} turns off all threshold criteria. If thresholds are specified, only atoms whose attributes meet all the threshold criteria are written to the dump file or included in the image. The possible attributes that can be tested for are the same as those that can be specified in the "dump custom"_dump.html command, with the exception of the {element} attribute, since it is not a numeric value. Note that a different attributes can be used than those output by the "dump custom"_dump.html command. E.g. you can output the coordinates and stress of atoms whose energy is above some threshold. If an atom-style variable is used as the attribute, then it can produce continuous numeric values or effective Boolean 0/1 values which may be useful for the comparision operator. Boolean values can be generated by variable formulas that use comparison or Boolean math operators or special functions like gmask() and rmask() and grmask(). See the "variable"_variable.html command doc page for details. The specified value must be a simple numeric value or the word LAST. If LAST is used, it refers to the value of the attribute the last time the dump command was invoked to produce a snapshot. This is a way to only dump atoms whose attribute has changed (or not changed). Three examples follow. dump_modify ... thresh ix != LAST :pre This will dump atoms which have crossed the periodic x boundary of the simulation box since the last dump. (Note that atoms that crossed once and then crossed back between the two dump timesteps would not be included.) region foo sphere 10 20 10 15 variable inregion atom rmask(foo) dump_modify ... thresh v_inregion |^ LAST This will dump atoms which crossed the boundary of the spherical region since the last dump. variable charge atom "(q > 0.5) || (q < -0.5)" dump_modify ... thresh v_charge |^ LAST This will dump atoms whose charge has changed from an absolute value less than 1/2 to greater than 1/2 (or vice versa) since the last dump. E.g. due to reactions and subsequent charge equilibration in a reactive force field. The choice of operators listed above are the usual comparison operators. The XOR operation (exclusive or) is also included as "|^". In this context, XOR means that if either the attribute or value is 0.0 and the other is non-zero, then the result is "true" and the threshold criterion is met. Otherwise it is not met. :line The {unwrap} keyword only applies to the dump {dcd} and {xtc} styles. If set to {yes}, coordinates will 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. :line :line These keywords apply only to the "dump image"_dump_image.html and "dump movie"_dump_image.html styles. Any keyword that affects an image, also affects a movie, since the movie is simply a collection of images. Some of the keywords only affect the "dump movie"_dump_image.html style. The descriptions give details. :line The {acolor} keyword can be used with the "dump image"_dump_image.html command, when its atom color setting is {type}, to set the color that atoms of each type will be drawn in the image. The specified {type} should be an integer from 1 to Ntypes = the number of atom types. A wildcard asterisk can be used in place of or in conjunction with the {type} argument to specify a range of atom types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the number of atom types, then an asterisk with no numeric values means all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive). The specified {color} can be a single color which is any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option. Or it can be two or more colors separated by a "/" character, e.g. red/green/blue. In the former case, that color is assigned to all the specified atom types. In the latter case, the list of colors are assigned in a round-robin fashion to each of the specified atom types. :line The {adiam} keyword can be used with the "dump image"_dump_image.html command, when its atom diameter setting is {type}, to set the size that atoms of each type will be drawn in the image. The specified {type} should be an integer from 1 to Ntypes. As with the {acolor} keyword, a wildcard asterisk can be used as part of the {type} argument to specify a range of atomt types. The specified {diam} is the size in whatever distance "units"_units.html the input script is using, e.g. Angstroms. :line The {amap} keyword can be used with the "dump image"_dump_image.html command, with its {atom} keyword, when its atom setting is an atom-attribute, to setup a color map. The color map is used to assign a specific RGB (red/green/blue) color value to an individual atom when it is drawn, based on the atom's attribute, which is a numeric value, e.g. its x-component of velocity if the atom-attribute "vx" was specified. The basic idea of a color map is that the atom-attribute will be -within a range of values, and that range is associated with a a series +within a range of values, and that range is associated with a series of colors (e.g. red, blue, green). An atom's specific value (vx = -3.2) can then mapped to the series of colors (e.g. halfway between red and blue), and a specific color is determined via an interpolation procedure. There are many possible options for the color map, enabled by the {amap} keyword. Here are the details. The {lo} and {hi} settings determine the range of values allowed for the atom attribute. If numeric values are used for {lo} and/or {hi}, then values that are lower/higher than that value are set to the value. I.e. the range is static. If {lo} is specified as {min} or {hi} as {max} then the range is dynamic, and the lower and/or upper bound will be calculated each time an image is drawn, based on the set of atoms being visualized. The {style} setting is two letters, such as "ca". The first letter is either "c" for continuous, "d" for discrete, or "s" for sequential. The second letter is either "a" for absolute, or "f" for fractional. A continuous color map is one in which the color changes continuously from value to value within the range. A discrete color map is one in which discrete colors are assigned to sub-ranges of values within the range. A sequential color map is one in which discrete colors are assigned to a sequence of sub-ranges of values covering the entire range. An absolute color map is one in which the values to which colors are assigned are specified explicitly as values within the range. A fractional color map is one in which the values to which colors are assigned are specified as a fractional portion of the range. For example if the range is from -10.0 to 10.0, and the color red is to be assigned to atoms with a value of 5.0, then for an absolute color map the number 5.0 would be used. But for a fractional map, the number 0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0. The {delta} setting must be specified for all styles, but is only used for the sequential style; otherwise the value is ignored. It specifies the bin size to use within the range for assigning consecutive colors to. For example, if the range is from -10.0 to 10.0 and a {delta} of 1.0 is used, then 20 colors will be assigned to the range. The first will be from -10.0 <= color1 < -9.0, then 2nd from -9.0 <= color2 < -8.0, etc. The {N} setting is how many entries follow. The format of the entries depends on whether the color map style is continuous, discrete or sequential. In all cases the {color} setting can be any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option. For continuous color maps, each entry has a {value} and a {color}. The {value} is either a number within the range of values or {min} or {max}. The {value} of the first entry must be {min} and the {value} of the last entry must be {max}. Any entries in between must have increasing values. Note that numeric values can be specified either as absolute numbers or as fractions (0.0 to 1.0) of the range, depending on the "a" or "f" in the style setting for the color map. Here is how the entries are used to determine the color of an individual atom, given the value X of its atom attribute. X will fall between 2 of the entry values. The color of the atom is linearly interpolated (in each of the RGB values) between the 2 colors associated with those entries. For example, if X = -5.0 and the 2 surrounding entries are "red" at -10.0 and "blue" at 0.0, then the atom's color will be halfway between "red" and "blue", which happens to be "purple". For discrete color maps, each entry has a {lo} and {hi} value and a {color}. The {lo} and {hi} settings are either numbers within the range of values or {lo} can be {min} or {hi} can be {max}. The {lo} and {hi} settings of the last entry must be {min} and {max}. Other entries can have any {lo} and {hi} values and the sub-ranges of different values can overlap. Note that numeric {lo} and {hi} values can be specified either as absolute numbers or as fractions (0.0 to 1.0) of the range, depending on the "a" or "f" in the style setting for the color map. Here is how the entries are used to determine the color of an individual atom, given the value X of its atom attribute. The entries are scanned from first to last. The first time that {lo} <= X <= {hi}, X is assigned the color associated with that entry. You can think of the last entry as assigning a default color (since it will always be matched by X), and the earlier entries as colors that override the default. Also note that no interpolation of a color RGB is done. All atoms will be drawn with one of the colors in the list of entries. For sequential color maps, each entry has only a {color}. Here is how the entries are used to determine the color of an individual atom, given the value X of its atom attribute. The range is partitioned into N bins of width {binsize}. Thus X will fall in a specific bin from 1 to N, say the Mth bin. If it falls on a boundary between 2 bins, it is considered to be in the higher of the 2 bins. Each bin is assigned a color from the E entries. If E < N, then the colors are repeated. For example if 2 entries with colors red and green are specified, then the odd numbered bins will be red and the even bins green. The color of the atom is the color of its bin. Note that the sequential color map is really a shorthand way of defining a discrete color map without having to specify where all the bin boundaries are. Here is an example of using a sequential color map to color all the atoms in individual molecules with a different color. See the examples/pour/in.pour.2d.molecule input script for an example of how this is used. variable colors string & "red green blue yellow white & purple pink orange lime gray" variable mol atom mol%10 dump 1 all image 250 image.*.jpg v_mol type & zoom 1.6 adiam 1.5 dump_modify 1 pad 5 amap 0 10 sa 1 10 $\{colors\} :pre In this case, 10 colors are defined, and molecule IDs are mapped to one of the colors, even if there are 1000s of molecules. :line The {backcolor} sets the background color of the images. The color name can be any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option. :line The {bcolor} keyword can be used with the "dump image"_dump_image.html command, with its {bond} keyword, when its color setting is {type}, to set the color that bonds of each type will be drawn in the image. The specified {type} should be an integer from 1 to Nbondtypes = the number of bond types. A wildcard asterisk can be used in place of or in conjunction with the {type} argument to specify a range of bond types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the number of bond types, then an asterisk with no numeric values means all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive). The specified {color} can be a single color which is any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option. Or it can be two or more colors separated by a "/" character, e.g. red/green/blue. In the former case, that color is assigned to all the specified bond types. In the latter case, the list of colors are assigned in a round-robin fashion to each of the specified bond types. :line The {bdiam} keyword can be used with the "dump image"_dump_image.html command, with its {bond} keyword, when its diam setting is {type}, to set the diameter that bonds of each type will be drawn in the image. The specified {type} should be an integer from 1 to Nbondtypes. As with the {bcolor} keyword, a wildcard asterisk can be used as part of the {type} argument to specify a range of bond types. The specified {diam} is the size in whatever distance "units"_units.html you are using, e.g. Angstroms. :line The {bitrate} keyword can be used with the "dump movie"_dump_image.html command to define the size of the resulting movie file and its quality via setting how many kbits per second are to be used for the movie file. Higher bitrates require less compression and will result in higher quality movies. The quality is also determined by the compression format and encoder. The default setting is 2000 kbit/s, which will result in average quality with older compression formats. NOTE: Not all movie file formats supported by dump movie allow the bitrate to be set. If not, the setting is silently ignored. :line The {boxcolor} keyword sets the color of the simulation box drawn around the atoms in each image as well as the color of processor sub-domain boundaries. See the "dump image box" command for how to specify that a box be drawn via the {box} keyword, and the sub-domain boundaries via the {subbox} keyword. The color name can be any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option. :line The {color} keyword allows definition of a new color name, in addition to the 140-predefined colors (see below), and associates 3 red/green/blue RGB values with that color name. The color name can then be used with any other dump_modify keyword that takes a color name as a value. The RGB values should each be floating point values between 0.0 and 1.0 inclusive. When a color name is converted to RGB values, the user-defined color names are searched first, then the 140 pre-defined color names. This means you can also use the {color} keyword to overwrite one of the pre-defined color names with new RBG values. :line The {framerate} keyword can be used with the "dump movie"_dump_image.html command to define the duration of the resulting movie file. Movie files written by the dump {movie} command have a default frame rate of 24 frames per second and the images generated will be converted at that rate. Thus a sequence of 1000 dump images will result in a movie of about 42 seconds. To make a movie run longer you can either generate images more frequently or lower the frame rate. To speed a movie up, you can do the inverse. Using a frame rate higher than 24 is not recommended, as it will result in simply dropping the rendered images. It is more efficient to dump images less frequently. :line :line [Restrictions:] none [Related commands:] "dump"_dump.html, "dump image"_dump_image.html, "undump"_undump.html [Default:] The option defaults are append = no buffer = yes for dump styles {atom}, {custom}, {loca}, and {xyz} element = "C" for every atom type every = whatever it was set to via the "dump"_dump.html command fileper = # of processors first = no flush = yes format = %d and %g for each integer or floating point value image = no label = ENTRIES nfile = 1 pad = 0 pbc = no precision = 1000 region = none scale = yes sort = off for dump styles {atom}, {custom}, {cfg}, and {local} sort = id for dump styles {dcd}, {xtc}, and {xyz} thresh = none unwrap = no :ul acolor = * red/green/blue/yellow/aqua/cyan adiam = * 1.0 amap = min max cf 0.0 2 min blue max red backcolor = black bcolor = * red/green/blue/yellow/aqua/cyan bdiam = * 0.5 bitrate = 2000 boxcolor = yellow color = 140 color names are pre-defined as listed below framerate = 24 :ul :line These are the standard 109 element names that LAMMPS pre-defines for use with the "dump image"_dump_image.html and dump_modify commands. 1-10 = "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne" 11-20 = "Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca" 21-30 = "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni", "Cu", "Zn" 31-40 = "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y", "Zr" 41-50 = "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn" 51-60 = "Sb", "Te", "I", "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd" 61-70 = "Pm", "Sm", "Eu", "Gd", "Tb", "Dy", "Ho", "Er", "Tm", "Yb" 71-80 = "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au", "Hg" 81-90 = "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th" 91-100 = "Pa", "U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm" 101-109 = "Md", "No", "Lr", "Rf", "Db", "Sg", "Bh", "Hs", "Mt" :ul :line These are the 140 colors that LAMMPS pre-defines for use with the "dump image"_dump_image.html and dump_modify commands. Additional colors can be defined with the dump_modify color command. The 3 numbers listed for each name are the RGB (red/green/blue) values. Divide each value by 255 to get the equivalent 0.0 to 1.0 value. aliceblue = 240, 248, 255 | antiquewhite = 250, 235, 215 | aqua = 0, 255, 255 | aquamarine = 127, 255, 212 | azure = 240, 255, 255 | beige = 245, 245, 220 | bisque = 255, 228, 196 | black = 0, 0, 0 | blanchedalmond = 255, 255, 205 | blue = 0, 0, 255 | blueviolet = 138, 43, 226 | brown = 165, 42, 42 | burlywood = 222, 184, 135 | cadetblue = 95, 158, 160 | chartreuse = 127, 255, 0 | chocolate = 210, 105, 30 | coral = 255, 127, 80 | cornflowerblue = 100, 149, 237 | cornsilk = 255, 248, 220 | crimson = 220, 20, 60 | cyan = 0, 255, 255 | darkblue = 0, 0, 139 | darkcyan = 0, 139, 139 | darkgoldenrod = 184, 134, 11 | darkgray = 169, 169, 169 | darkgreen = 0, 100, 0 | darkkhaki = 189, 183, 107 | darkmagenta = 139, 0, 139 | darkolivegreen = 85, 107, 47 | darkorange = 255, 140, 0 | darkorchid = 153, 50, 204 | darkred = 139, 0, 0 | darksalmon = 233, 150, 122 | darkseagreen = 143, 188, 143 | darkslateblue = 72, 61, 139 | darkslategray = 47, 79, 79 | darkturquoise = 0, 206, 209 | darkviolet = 148, 0, 211 | deeppink = 255, 20, 147 | deepskyblue = 0, 191, 255 | dimgray = 105, 105, 105 | dodgerblue = 30, 144, 255 | firebrick = 178, 34, 34 | floralwhite = 255, 250, 240 | forestgreen = 34, 139, 34 | fuchsia = 255, 0, 255 | gainsboro = 220, 220, 220 | ghostwhite = 248, 248, 255 | gold = 255, 215, 0 | goldenrod = 218, 165, 32 | gray = 128, 128, 128 | green = 0, 128, 0 | greenyellow = 173, 255, 47 | honeydew = 240, 255, 240 | hotpink = 255, 105, 180 | indianred = 205, 92, 92 | indigo = 75, 0, 130 | ivory = 255, 240, 240 | khaki = 240, 230, 140 | lavender = 230, 230, 250 | lavenderblush = 255, 240, 245 | lawngreen = 124, 252, 0 | lemonchiffon = 255, 250, 205 | lightblue = 173, 216, 230 | lightcoral = 240, 128, 128 | lightcyan = 224, 255, 255 | lightgoldenrodyellow = 250, 250, 210 | lightgreen = 144, 238, 144 | lightgrey = 211, 211, 211 | lightpink = 255, 182, 193 | lightsalmon = 255, 160, 122 | lightseagreen = 32, 178, 170 | lightskyblue = 135, 206, 250 | lightslategray = 119, 136, 153 | lightsteelblue = 176, 196, 222 | lightyellow = 255, 255, 224 | lime = 0, 255, 0 | limegreen = 50, 205, 50 | linen = 250, 240, 230 | magenta = 255, 0, 255 | maroon = 128, 0, 0 | mediumaquamarine = 102, 205, 170 | mediumblue = 0, 0, 205 | mediumorchid = 186, 85, 211 | mediumpurple = 147, 112, 219 | mediumseagreen = 60, 179, 113 | mediumslateblue = 123, 104, 238 | mediumspringgreen = 0, 250, 154 | mediumturquoise = 72, 209, 204 | mediumvioletred = 199, 21, 133 | midnightblue = 25, 25, 112 | mintcream = 245, 255, 250 | mistyrose = 255, 228, 225 | moccasin = 255, 228, 181 | navajowhite = 255, 222, 173 | navy = 0, 0, 128 | oldlace = 253, 245, 230 | olive = 128, 128, 0 | olivedrab = 107, 142, 35 | orange = 255, 165, 0 | orangered = 255, 69, 0 | orchid = 218, 112, 214 | palegoldenrod = 238, 232, 170 | palegreen = 152, 251, 152 | paleturquoise = 175, 238, 238 | palevioletred = 219, 112, 147 | papayawhip = 255, 239, 213 | peachpuff = 255, 239, 213 | peru = 205, 133, 63 | pink = 255, 192, 203 | plum = 221, 160, 221 | powderblue = 176, 224, 230 | purple = 128, 0, 128 | red = 255, 0, 0 | rosybrown = 188, 143, 143 | royalblue = 65, 105, 225 | saddlebrown = 139, 69, 19 | salmon = 250, 128, 114 | sandybrown = 244, 164, 96 | seagreen = 46, 139, 87 | seashell = 255, 245, 238 | sienna = 160, 82, 45 | silver = 192, 192, 192 | skyblue = 135, 206, 235 | slateblue = 106, 90, 205 | slategray = 112, 128, 144 | snow = 255, 250, 250 | springgreen = 0, 255, 127 | steelblue = 70, 130, 180 | tan = 210, 180, 140 | teal = 0, 128, 128 | thistle = 216, 191, 216 | tomato = 253, 99, 71 | turquoise = 64, 224, 208 | violet = 238, 130, 238 | wheat = 245, 222, 179 | white = 255, 255, 255 | whitesmoke = 245, 245, 245 | yellow = 255, 255, 0 | yellowgreen = 154, 205, 50 :tb(c=5,s=|) diff --git a/doc/src/fix_lb_fluid.txt b/doc/src/fix_lb_fluid.txt index b4447b65c..62265a3bc 100644 --- a/doc/src/fix_lb_fluid.txt +++ b/doc/src/fix_lb_fluid.txt @@ -1,370 +1,370 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line fix lb/fluid command :h3 [Syntax:] fix ID group-ID lb/fluid nevery LBtype viscosity density keyword values ... :pre ID, group-ID are documented in "fix"_fix.html command :ulb,l lb/fluid = style name of this fix command :l nevery = update the lattice-Boltzmann fluid every this many timesteps :l LBtype = 1 to use the standard finite difference LB integrator, 2 to use the LB integrator of "Ollila et al."_#Ollila :l viscosity = the fluid viscosity (units of mass/(time*length)). :l density = the fluid density. :l zero or more keyword/value pairs may be appended :l keyword = {setArea} or {setGamma} or {scaleGamma} or {dx} or {dm} or {a0} or {noise} or {calcforce} or {trilinear} or {D3Q19} or {read_restart} or {write_restart} or {zwall_velocity} or {bodyforce} or {printfluid} :l {setArea} values = type node_area type = atom type (1-N) node_area = portion of the surface area of the composite object associated with the particular atom type (used when the force coupling constant is set by default). {setGamma} values = gamma gamma = user set value for the force coupling constant. {scaleGamma} values = type gammaFactor type = atom type (1-N) gammaFactor = factor to scale the {setGamma} gamma value by, for the specified atom type. {dx} values = dx_LB = the lattice spacing. {dm} values = dm_LB = the lattice-Boltzmann mass unit. {a0} values = a_0_real = the square of the speed of sound in the fluid. {noise} values = Temperature seed Temperature = fluid temperature. seed = random number generator seed (positive integer) {calcforce} values = N forcegroup-ID N = output the force and torque every N timesteps forcegroup-ID = ID of the particle group to calculate the force and torque of {trilinear} values = none (used to switch from the default Peskin interpolation stencil to the trilinear stencil). {D3Q19} values = none (used to switch from the default D3Q15, 15 velocity lattice, to the D3Q19, 19 velocity lattice). {read_restart} values = restart file = name of the restart file to use to restart a fluid run. {write_restart} values = N = write a restart file every N MD timesteps. {zwall_velocity} values = velocity_bottom velocity_top = velocities along the y-direction of the bottom and top walls (located at z=zmin and z=zmax). {bodyforce} values = bodyforcex bodyforcey bodyforcez = the x,y and z components of a constant body force added to the fluid. {printfluid} values = N = print the fluid density and velocity at each grid point every N timesteps. :pre :ule [Examples:] fix 1 all lb/fluid 1 2 1.0 1.0 setGamma 13.0 dx 4.0 dm 10.0 calcforce sphere1 fix 1 all lb/fluid 1 1 1.0 0.0009982071 setArea 1 1.144592082 dx 2.0 dm 0.3 trilinear noise 300.0 8979873 :pre [Description:] Implement a lattice-Boltzmann fluid on a uniform mesh covering the LAMMPS simulation domain. The MD particles described by {group-ID} apply a velocity dependent force to the fluid. The lattice-Boltzmann algorithm solves for the fluid motion governed by the Navier Stokes equations, :c,image(Eqs/fix_lb_fluid_navierstokes.jpg) with, :c,image(Eqs/fix_lb_fluid_viscosity.jpg) where rho is the fluid density, u is the local fluid velocity, sigma is the stress tensor, F is a local external force, and eta and Lambda are the shear and bulk viscosities respectively. Here, we have implemented :c,image(Eqs/fix_lb_fluid_stress.jpg), with a_0 set to 1/3 (dx/dt)^2 by default. The algorithm involves tracking the time evolution of a set of partial distribution functions which evolve according to a velocity discretized version of the Boltzmann equation, :c,image(Eqs/fix_lb_fluid_boltzmann.jpg) where the first term on the right hand side represents a single time relaxation towards the equilibrium distribution function, and tau is a parameter physically related to the viscosity. On a technical note, we have implemented a 15 velocity model (D3Q15) as default; however, the user can switch to a 19 velocity model (D3Q19) through the use of the {D3Q19} keyword. This fix provides the user with the choice of two algorithms to solve this equation, through the specification of the keyword {LBtype}. If {LBtype} is set equal to 1, the standard finite difference LB integrator is used. If {LBtype} is set equal to 2, the algorithm of "Ollila et al."_#Ollila is used. Physical variables are then defined in terms of moments of the distribution functions, :c,image(Eqs/fix_lb_fluid_properties.jpg) Full details of the lattice-Boltzmann algorithm used can be found in "Mackay et al."_#fluid-Mackay. The fluid is coupled to the MD particles described by {group-ID} through a velocity dependent force. The contribution to the fluid force on a given lattice mesh site j due to MD particle alpha is calculated as: :c,image(Eqs/fix_lb_fluid_fluidforce.jpg) where v_n is the velocity of the MD particle, u_f is the fluid velocity interpolated to the particle location, and gamma is the force coupling constant. Zeta is a weight assigned to the grid point, obtained by distributing the particle to the nearest lattice sites. For this, the user has the choice between a trilinear stencil, which provides a support of 8 lattice sites, or the immersed boundary method Peskin stencil, which provides a support of 64 lattice sites. While the Peskin stencil is seen to provide more stable results, the trilinear stencil may be better suited for simulation of objects close to walls, due to its smaller support. Therefore, by default, the Peskin stencil is used; however the user may switch to the trilinear stencil by specifying the keyword, {trilinear}. By default, the force coupling constant, gamma, is calculated according to :c,image(Eqs/fix_lb_fluid_gammadefault.jpg). Here, m_v is the mass of the MD particle, m_u is a representative fluid mass at the particle location, and dt_collision is a collision time, chosen such that tau/dt_collision = 1 (see "Mackay and Denniston"_#Mackay2 for full details). In order to calculate m_u, the fluid density is interpolated to the MD particle location, and multiplied by a volume, node_area*dx_lb, where node_area represents the portion of the surface area of the composite object associated with a given MD particle. By default, node_area is set equal to dx_lb*dx_lb; however specific values for given atom types can be set using the {setArea} keyword. The user also has the option of specifying their own value for the force coupling constant, for all the MD particles associated with the fix, through the use of the {setGamma} keyword. This may be useful when modelling porous particles. See "Mackay et al."_#fluid-Mackay for a detailed description of the method by which the user can choose an appropriate gamma value. NOTE: while this fix applies the force of the particles on the fluid, it does not apply the force of the fluid to the particles. When the force coupling constant is set using the default method, there is only one option to include this hydrodynamic force on the particles, and that is through the use of the "lb/viscous"_fix_lb_viscous.html fix. This fix adds the hydrodynamic force to the total force acting on the particles, after which any of the built-in LAMMPS integrators can be used to integrate the particle motion. However, if the user specifies their own value for the force coupling constant, as mentioned in "Mackay et al."_#fluid-Mackay, the built-in LAMMPS integrators may prove to be unstable. Therefore, we have included our own integrators "fix lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html, and "fix lb/pc"_fix_lb_pc.html, to solve for the particle motion in these cases. These integrators should not be used with the "lb/viscous"_fix_lb_viscous.html fix, as they add hydrodynamic forces to the particles directly. In addition, they can not be used if the force coupling constant has been set the default way. NOTE: if the force coupling constant is set using the default method, and the "lb/viscous"_fix_lb_viscous.html fix is NOT used to add the hydrodynamic force to the total force acting on the particles, this physically corresponds to a situation in which an infinitely massive particle is moving through the fluid (since collisions between the particle and the fluid do not act to change the particle's velocity). Therefore, the user should set the mass of the particle to be significantly larger than the mass of the fluid at the particle location, in order to approximate an infinitely massive particle (see the dragforce test run for an example). :line Inside the fix, parameters are scaled by the lattice-Boltzmann timestep, dt, grid spacing, dx, and mass unit, dm. dt is set equal to (nevery*dt_MD), where dt_MD is the MD timestep. By default, dm is set equal to 1.0, and dx is chosen so that tau/(dt) = (3*eta*dt)/(rho*dx^2) is approximately equal to 1. However, the user has the option of specifying their own values for dm, and dx, by using the optional keywords {dm}, and {dx} respectively. NOTE: Care must be taken when choosing both a value for dx, and a simulation domain size. This fix uses the same subdivision of the simulation domain among processors as the main LAMMPS program. In order to uniformly cover the simulation domain with lattice sites, the lengths of the individual LAMMPS subdomains must all be evenly divisible by dx. If the simulation domain size is cubic, with equal lengths in all dimensions, and the default value for dx is used, this will automatically be satisfied. Physical parameters describing the fluid are specified through {viscosity}, {density}, and {a0}. If the force coupling constant is set the default way, the surface area associated with the MD particles is specified using the {setArea} keyword. If the user chooses to specify a value for the force coupling constant, this is set using the {setGamma} keyword. These parameters should all be given in terms of the mass, distance, and time units chosen for the main LAMMPS run, as they are scaled by the LB timestep, lattice spacing, and mass unit, inside the fix. :line The {setArea} keyword allows the user to associate a surface area with a given atom type. For example if a spherical composite object of radius R is represented as a spherical shell of N evenly distributed MD particles, all of the same type, the surface area per particle associated with that atom type should be set equal to 4*pi*R^2/N. This keyword should only be used if the force coupling constant, gamma, is set the default way. The {setGamma} keyword allows the user to specify their own value for the force coupling constant, gamma, instead of using the default value. The {scaleGamma} keyword should be used in conjunction with the {setGamma} keyword, when the user wishes to specify different gamma values for different atom types. This keyword allows the user to scale the {setGamma} gamma value by a factor, gammaFactor, for a given atom type. The {dx} keyword allows the user to specify a value for the LB grid spacing. The {dm} keyword allows the user to specify the LB mass unit. If the {a0} keyword is used, the value specified is used for the square of the speed of sound in the fluid. If this keyword is not present, the speed of sound squared is set equal to (1/3)*(dx/dt)^2. Setting a0 > (dx/dt)^2 is not allowed, as this may lead to instabilities. -If the {noise} keyword is used, followed by a a positive temperature +If the {noise} keyword is used, followed by a positive temperature value, and a positive integer random number seed, a thermal lattice-Boltzmann algorithm is used. If {LBtype} is set equal to 1 (i.e. the standard LB integrator is chosen), the thermal LB algorithm of "Adhikari et al."_#Adhikari is used; however if {LBtype} is set equal to 2 both the LB integrator, and thermal LB algorithm described in "Ollila et al."_#Ollila are used. If the {calcforce} keyword is used, both the fluid force and torque acting on the specified particle group are printed to the screen every N timesteps. If the keyword {trilinear} is used, the trilinear stencil is used to interpolate the particle nodes onto the fluid mesh. By default, the immersed boundary method, Peskin stencil is used. Both of these interpolation methods are described in "Mackay et al."_#fluid-Mackay. If the keyword {D3Q19} is used, the 19 velocity (D3Q19) lattice is used by the lattice-Boltzmann algorithm. By default, the 15 velocity (D3Q15) lattice is used. If the keyword {write_restart} is used, followed by a positive integer, N, a binary restart file is printed every N LB timesteps. This restart file only contains information about the fluid. Therefore, a LAMMPS restart file should also be written in order to print out full details of the simulation. NOTE: When a large number of lattice grid points are used, the restart files may become quite large. In order to restart the fluid portion of the simulation, the keyword {read_restart} is specified, followed by the name of the binary lb_fluid restart file to be used. If the {zwall_velocity} keyword is used y-velocities are assigned to the lower and upper walls. This keyword requires the presence of walls in the z-direction. This is set by assigning fixed boundary conditions in the z-direction. If fixed boundary conditions are present in the z-direction, and this keyword is not used, the walls are assumed to be stationary. If the {bodyforce} keyword is used, a constant body force is added to the fluid, defined by it's x, y and z components. If the {printfluid} keyword is used, followed by a positive integer, N, the fluid densities and velocities at each lattice site are printed to the screen every N timesteps. :line For further details, as well as descriptions and results of several test runs, see "Mackay et al."_#fluid-Mackay. Please include a citation to this paper if the lb_fluid fix is used in work contributing to published research. :line [Restart, fix_modify, output, run start/stop, minimize info:] Due to the large size of the fluid data, this fix writes it's own binary restart files, if requested, independent of the main LAMMPS "binary restart files"_restart.html; no information about {lb_fluid} is written to the main LAMMPS "binary restart files"_restart.html. None of the "fix_modify"_fix_modify.html options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various "output commands"_Section_howto.html#howto_15. No parameter of this fix can be used with the {start/stop} keywords of the "run"_run.html command. This fix is not invoked during "energy minimization"_minimize.html. [Restrictions:] This fix is part of the USER-LB package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. This fix can only be used with an orthogonal simulation domain. Walls have only been implemented in the z-direction. Therefore, the boundary conditions, as specified via the main LAMMPS boundary command must be periodic for x and y, and either fixed or periodic for z. Shrink-wrapped boundary conditions are not permitted with this fix. This fix must be used before any of "fix lb/viscous"_fix_lb_viscous.html, "fix lb/momentum"_fix_lb_momentum.html, "fix lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html, and/ or "fix lb/pc"_fix_lb_pc.html , as the fluid needs to be initialized before any of these routines try to access its properties. In addition, in order for the hydrodynamic forces to be added to the particles, this fix must be used in conjunction with the "lb/viscous"_fix_lb_viscous.html fix if the force coupling constant is set by default, or either the "lb/viscous"_fix_lb_viscous.html fix or one of the "lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html or "lb/pc"_fix_lb_pc.html integrators, if the user chooses to specifiy their own value for the force coupling constant. [Related commands:] "fix lb/viscous"_fix_lb_viscous.html, "fix lb/momentum"_fix_lb_momentum.html, "fix lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html, "fix lb/pc"_fix_lb_pc.html [Default:] By default, the force coupling constant is set according to :c,image(Eqs/fix_lb_fluid_gammadefault.jpg) and an area of dx_lb^2 per node, used to calculate the fluid mass at the particle node location, is assumed. dx is chosen such that tau/(delta t_LB) = (3 eta dt_LB)/(rho dx_lb^2) is approximately equal to 1. dm is set equal to 1.0. a0 is set equal to (1/3)*(dx_lb/dt_lb)^2. The Peskin stencil is used as the default interpolation method. The D3Q15 lattice is used for the lattice-Boltzmann algorithm. If walls are present, they are assumed to be stationary. :line :link(Ollila) [(Ollila et al.)] Ollila, S.T.T., Denniston, C., Karttunen, M., and Ala-Nissila, T., Fluctuating lattice-Boltzmann model for complex fluids, J. Chem. Phys. 134 (2011) 064902. :link(fluid-Mackay) [(Mackay et al.)] Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031. :link(Mackay2) [(Mackay and Denniston)] Mackay, F. E., and Denniston, C., Coupling MD particles to a lattice-Boltzmann fluid through the use of conservative forces, J. Comput. Phys. 237 (2013) 289-298. :link(Adhikari) [(Adhikari et al.)] Adhikari, R., Stratford, K., Cates, M. E., and Wagner, A. J., Fluctuating lattice Boltzmann, Europhys. Lett. 71 (2005) 473-479.