diff --git a/doc/Section_commands.txt b/doc/Section_commands.txt new file mode 100644 index 0000000000..0d7e069e06 --- /dev/null +++ b/doc/Section_commands.txt @@ -0,0 +1,1266 @@ +"Previous Section"_Section_start.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_packages.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +3. Commands :h2 + +This section describes how a LAMMPS input script is formatted and the +input script commands used to define a LAMMPS simulation. + +3.1 "LAMMPS input script"_#cmd_1 +3.2 "Parsing rules"_#cmd_2 +3.3 "Input script structure"_#cmd_3 +3.4 "Commands listed by category"_#cmd_4 +3.5 "Commands listed alphabetically"_#cmd_5 :all(b) + +:line +:line + +3.1 LAMMPS input script :link(cmd_1),h4 + +LAMMPS executes by reading commands from a input script (text file), +one line at a time. When the input script ends, LAMMPS exits. Each +command causes LAMMPS to take some action. It may set an internal +variable, read in a file, or run a simulation. Most commands have +default settings, which means you only need to use the command if you +wish to change the default. + +In many cases, the ordering of commands in an input script is not +important. However the following rules apply: + +(1) LAMMPS does not read your entire input script and then perform a +simulation with all the settings. Rather, the input script is read +one line at a time and each command takes effect when it is read. +Thus this sequence of commands: + +timestep 0.5 +run 100 +run 100 :pre + +does something different than this sequence: + +run 100 +timestep 0.5 +run 100 :pre + +In the first case, the specified timestep (0.5 fmsec) is used for two +simulations of 100 timesteps each. In the 2nd case, the default +timestep (1.0 fmsec) is used for the 1st 100 step simulation and a 0.5 +fmsec timestep is used for the 2nd one. + +(2) Some commands are only valid when they follow other commands. For +example you cannot set the temperature of a group of atoms until atoms +have been defined and a group command is used to define which atoms +belong to the group. + +(3) Sometimes command B will use values that can be set by command A. +This means command A must precede command B in the input script if it +is to have the desired effect. For example, the +"read_data"_read_data.html command initializes the system by setting +up the simulation box and assigning atoms to processors. If default +values are not desired, the "processors"_processors.html and +"boundary"_boundary.html commands need to be used before read_data to +tell LAMMPS how to map processors to the simulation box. + +Many input script errors are detected by LAMMPS and an ERROR or +WARNING message is printed. "This section"_Section_errors.html gives +more information on what errors mean. The documentation for each +command lists restrictions on how the command can be used. + +:line + +3.2 Parsing rules :link(cmd_2),h4 + +Each non-blank line in the input script is treated as a command. +LAMMPS commands are case sensitive. Command names are lower-case, as +are specified command arguments. Upper case letters may be used in +file names or user-chosen ID strings. + +Here is how each line in the input script is parsed by LAMMPS: + +(1) If the last printable character on the line is a "&" character, +the command is assumed to continue on the next line. The next line is +concatenated to the previous line by removing the "&" character and +line break. This allows long commands to be continued across two or +more lines. See the discussion of triple quotes in (6) for how to +continue a command across multiple line without using "&" characters. + +(2) All characters from the first "#" character onward are treated as +comment and discarded. See an exception in (6). Note that a +comment after a trailing "&" character will prevent the command from +continuing on the next line. Also note that for multi-line commands a +single leading "#" will comment out the entire command. + +(3) The line is searched repeatedly for $ characters, which indicate +variables that are replaced with a text string. See an exception in +(6). + +If the $ is followed by curly brackets, then the variable name is the +text inside the curly brackets. If no curly brackets follow the $, +then the variable name is the single character immediately following +the $. Thus $\{myTemp\} and $x refer to variable names "myTemp" and +"x". + +How the variable is converted to a text string depends on what style +of variable it is; see the "variable"_variable.html doc page for details. +It can be a variable that stores multiple text strings, and return one +of them. The returned text string can be multiple "words" (space +separated) which will then be interpreted as multiple arguments in the +input command. The variable can also store a numeric formula which +will be evaluated and its numeric result returned as a string. + +As a special case, if the $ is followed by parenthesis, then the text +inside the parenthesis is treated as an "immediate" variable and +evaluated as an "equal-style variable"_variable.html. This is a way +to use numeric formulas in an input script without having to assign +them to variable names. For example, these 3 input script lines: + +variable X equal (xlo+xhi)/2+sqrt(v_area) +region 1 block $X 2 INF INF EDGE EDGE +variable X delete :pre + +can be replaced by + +region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE :pre + +so that you do not have to define (or discard) a temporary variable X. + +Note that neither the curly-bracket or immediate form of variables can +contain nested $ characters for other variables to substitute for. +Thus you cannot do this: + +variable a equal 2 +variable b2 equal 4 +print "B2 = $\{b$a\}" :pre + +Nor can you specify this $($x-1.0) for an immediate variable, but +you could use $(v_x-1.0), since the latter is valid syntax for an +"equal-style variable"_variable.html. + +See the "variable"_variable.html command for more details of how +strings are assigned to variables and evaluated, and how they can be +used in input script commands. + +(4) The line is broken into "words" separated by whitespace (tabs, +spaces). Note that words can thus contain letters, digits, +underscores, or punctuation characters. + +(5) The first word is the command name. All successive words in the +line are arguments. + +(6) If you want text with spaces to be treated as a single argument, +it can be enclosed in either single or double or triple quotes. A +long single argument enclosed in single or double quotes can span +multiple lines if the "&" character is used, as described above. When +the lines are concatenated together (and the "&" characters and line +breaks removed), the text will become a single line. If you want +multiple lines of an argument to retain their line breaks, the text +can be enclosed in triple quotes, in which case "&" characters are not +needed. For example: + +print "Volume = $v" +print 'Volume = $v' +if "$\{steps\} > 1000" then quit +variable a string "red green blue & + purple orange cyan" +print """ +System volume = $v +System temperature = $t +""" :pre + +In each case, the single, double, or triple quotes are removed when +the single argument they enclose is stored internally. + +See the "dump modify format"_dump_modify.html, "print"_print.html, +"if"_if.html, and "python"_python.html commands for examples. + +A "#" or "$" character that is between quotes will not be treated as a +comment indicator in (2) or substituted for as a variable in (3). + +NOTE: If the argument is itself a command that requires a quoted +argument (e.g. using a "print"_print.html command as part of an +"if"_if.html or "run every"_run.html command), then single, double, or +triple quotes can be nested in the usual manner. See the doc pages +for those commands for examples. Only one of level of nesting is +allowed, but that should be sufficient for most use cases. + +:line + +3.3 Input script structure :h3,link(cmd_3) + +This section describes the structure of a typical LAMMPS input script. +The "examples" directory in the LAMMPS distribution contains many +sample input scripts; the corresponding problems are discussed in +"Section 7"_Section_example.html, and animated on the "LAMMPS +WWW Site"_lws. + +A LAMMPS input script typically has 4 parts: + +Initialization +Atom definition +Settings +Run a simulation :ol + +The last 2 parts can be repeated as many times as desired. I.e. run a +simulation, change some settings, run some more, etc. Each of the 4 +parts is now described in more detail. Remember that almost all the +commands need only be used if a non-default value is desired. + +(1) Initialization + +Set parameters that need to be defined before atoms are created or +read-in from a file. + +The relevant commands are "units"_units.html, +"dimension"_dimension.html, "newton"_newton.html, +"processors"_processors.html, "boundary"_boundary.html, +"atom_style"_atom_style.html, "atom_modify"_atom_modify.html. + +If force-field parameters appear in the files that will be read, these +commands tell LAMMPS what kinds of force fields are being used: +"pair_style"_pair_style.html, "bond_style"_bond_style.html, +"angle_style"_angle_style.html, "dihedral_style"_dihedral_style.html, +"improper_style"_improper_style.html. + +(2) Atom definition + +There are 3 ways to define atoms in LAMMPS. Read them in from a data +or restart file via the "read_data"_read_data.html or +"read_restart"_read_restart.html commands. These files can contain +molecular topology information. Or create atoms on a lattice (with no +molecular topology), using these commands: "lattice"_lattice.html, +"region"_region.html, "create_box"_create_box.html, +"create_atoms"_create_atoms.html. The entire set of atoms can be +duplicated to make a larger simulation using the +"replicate"_replicate.html command. + +(3) Settings + +Once atoms and molecular topology are defined, a variety of settings +can be specified: force field coefficients, simulation parameters, +output options, etc. + +Force field coefficients are set by these commands (they can also be +set in the read-in files): "pair_coeff"_pair_coeff.html, +"bond_coeff"_bond_coeff.html, "angle_coeff"_angle_coeff.html, +"dihedral_coeff"_dihedral_coeff.html, +"improper_coeff"_improper_coeff.html, +"kspace_style"_kspace_style.html, "dielectric"_dielectric.html, +"special_bonds"_special_bonds.html. + +Various simulation parameters are set by these commands: +"neighbor"_neighbor.html, "neigh_modify"_neigh_modify.html, +"group"_group.html, "timestep"_timestep.html, +"reset_timestep"_reset_timestep.html, "run_style"_run_style.html, +"min_style"_min_style.html, "min_modify"_min_modify.html. + +Fixes impose a variety of boundary conditions, time integration, and +diagnostic options. The "fix"_fix.html command comes in many flavors. + +Various computations can be specified for execution during a +simulation using the "compute"_compute.html, +"compute_modify"_compute_modify.html, and "variable"_variable.html +commands. + +Output options are set by the "thermo"_thermo.html, "dump"_dump.html, +and "restart"_restart.html commands. + +(4) Run a simulation + +A molecular dynamics simulation is run using the "run"_run.html +command. Energy minimization (molecular statics) is performed using +the "minimize"_minimize.html command. A parallel tempering +(replica-exchange) simulation can be run using the +"temper"_temper.html command. + +:line + +3.4 Commands listed by category :link(cmd_4),h4 + +This section lists core LAMMPS commands, grouped by category. +The "next section"_#cmd_5 lists all commands alphabetically. The +next section also includes (long) lists of style options for entries +that appear in the following categories as a single command (fix, +compute, pair, etc). Commands that are added by user packages are not +included in the categories here, but they are in the next section. + +Initialization: + +"newton"_newton.html, +"package"_package.html, +"processors"_processors.html, +"suffix"_suffix.html, +"units"_units.html + +Setup simulation box: + +"boundary"_boundary.html, +"box"_box.html, +"change_box"_change_box.html, +"create_box"_create_box.html, +"dimension"_dimension.html, +"lattice"_lattice.html, +"region"_region.html + +Setup atoms: + +"atom_modify"_atom_modify.html, +"atom_style"_atom_style.html, +"balance"_balance.html, +"create_atoms"_create_atoms.html, +"create_bonds"_create_bonds.html, +"delete_atoms"_delete_atoms.html, +"delete_bonds"_delete_bonds.html, +"displace_atoms"_displace_atoms.html, +"group"_group.html, +"mass"_mass.html, +"molecule"_molecule.html, +"read_data"_read_data.html, +"read_dump"_read_dump.html, +"read_restart"_read_restart.html, +"replicate"_replicate.html, +"set"_set.html, +"velocity"_velocity.html + +Force fields: + +"angle_coeff"_angle_coeff.html, +"angle_style"_angle_style.html, +"bond_coeff"_bond_coeff.html, +"bond_style"_bond_style.html, +"bond_write"_bond_write.html, +"dielectric"_dielectric.html, +"dihedral_coeff"_dihedral_coeff.html, +"dihedral_style"_dihedral_style.html, +"improper_coeff"_improper_coeff.html, +"improper_style"_improper_style.html, +"kspace_modify"_kspace_modify.html, +"kspace_style"_kspace_style.html, +"pair_coeff"_pair_coeff.html, +"pair_modify"_pair_modify.html, +"pair_style"_pair_style.html, +"pair_write"_pair_write.html, +"special_bonds"_special_bonds.html + +Settings: + +"comm_modify"_comm_modify.html, +"comm_style"_comm_style.html, +"info"_info.html, +"min_modify"_min_modify.html, +"min_style"_min_style.html, +"neigh_modify"_neigh_modify.html, +"neighbor"_neighbor.html, +"partition"_partition.html, +"reset_timestep"_reset_timestep.html, +"run_style"_run_style.html, +"timer"_timer.html, +"timestep"_timestep.html + +Operations within timestepping (fixes) and diagnostics (computes): + +"compute"_compute.html, +"compute_modify"_compute_modify.html, +"fix"_fix.html, +"fix_modify"_fix_modify.html, +"uncompute"_uncompute.html, +"unfix"_unfix.html + +Output: + +"dump image"_dump_image.html, +"dump movie"_dump_image.html, +"dump"_dump.html, +"dump_modify"_dump_modify.html, +"restart"_restart.html, +"thermo"_thermo.html, +"thermo_modify"_thermo_modify.html, +"thermo_style"_thermo_style.html, +"undump"_undump.html, +"write_coeff"_write_coeff.html, +"write_data"_write_data.html, +"write_dump"_write_dump.html, +"write_restart"_write_restart.html + +Actions: + +"minimize"_minimize.html, +"neb"_neb.html, +"prd"_prd.html, +"rerun"_rerun.html, +"run"_run.html, +"tad"_tad.html, +"temper"_temper.html + +Input script control: + +"clear"_clear.html, +"echo"_echo.html, +"if"_if.html, +"include"_include.html, +"jump"_jump.html, +"label"_label.html, +"log"_log.html, +"next"_next.html, +"print"_print.html, +"python"_python.html, +"quit"_quit.html, +"shell"_shell.html, +"variable"_variable.html + +:line + +3.5 Individual commands :h3,link(cmd_5),link(comm) + +This section lists all LAMMPS commands alphabetically, with a separate +listing below of styles within certain commands. The "previous +section"_#cmd_4 lists the same commands, grouped by category. Note +that some style options for some commands are part of specific LAMMPS +packages, which means they cannot be used unless the package was +included when LAMMPS was built. Not all packages are included in a +default LAMMPS build. These dependencies are listed as Restrictions +in the command's documentation. + +"angle_coeff"_angle_coeff.html, +"angle_style"_angle_style.html, +"atom_modify"_atom_modify.html, +"atom_style"_atom_style.html, +"balance"_balance.html, +"bond_coeff"_bond_coeff.html, +"bond_style"_bond_style.html, +"bond_write"_bond_write.html, +"boundary"_boundary.html, +"box"_box.html, +"change_box"_change_box.html, +"clear"_clear.html, +"comm_modify"_comm_modify.html, +"comm_style"_comm_style.html, +"compute"_compute.html, +"compute_modify"_compute_modify.html, +"create_atoms"_create_atoms.html, +"create_bonds"_create_bonds.html, +"create_box"_create_box.html, +"delete_atoms"_delete_atoms.html, +"delete_bonds"_delete_bonds.html, +"dielectric"_dielectric.html, +"dihedral_coeff"_dihedral_coeff.html, +"dihedral_style"_dihedral_style.html, +"dimension"_dimension.html, +"displace_atoms"_displace_atoms.html, +"dump"_dump.html, +"dump image"_dump_image.html, +"dump_modify"_dump_modify.html, +"dump movie"_dump_image.html, +"echo"_echo.html, +"fix"_fix.html, +"fix_modify"_fix_modify.html, +"group"_group.html, +"if"_if.html, +"info"_info.html, +"improper_coeff"_improper_coeff.html, +"improper_style"_improper_style.html, +"include"_include.html, +"jump"_jump.html, +"kspace_modify"_kspace_modify.html, +"kspace_style"_kspace_style.html, +"label"_label.html, +"lattice"_lattice.html, +"log"_log.html, +"mass"_mass.html, +"minimize"_minimize.html, +"min_modify"_min_modify.html, +"min_style"_min_style.html, +"molecule"_molecule.html, +"neb"_neb.html, +"neigh_modify"_neigh_modify.html, +"neighbor"_neighbor.html, +"newton"_newton.html, +"next"_next.html, +"package"_package.html, +"pair_coeff"_pair_coeff.html, +"pair_modify"_pair_modify.html, +"pair_style"_pair_style.html, +"pair_write"_pair_write.html, +"partition"_partition.html, +"prd"_prd.html, +"print"_print.html, +"processors"_processors.html, +"python"_python.html, +"quit"_quit.html, +"read_data"_read_data.html, +"read_dump"_read_dump.html, +"read_restart"_read_restart.html, +"region"_region.html, +"replicate"_replicate.html, +"rerun"_rerun.html, +"reset_ids"_reset_ids.html, +"reset_timestep"_reset_timestep.html, +"restart"_restart.html, +"run"_run.html, +"run_style"_run_style.html, +"set"_set.html, +"shell"_shell.html, +"special_bonds"_special_bonds.html, +"suffix"_suffix.html, +"tad"_tad.html, +"temper"_temper.html, +"thermo"_thermo.html, +"thermo_modify"_thermo_modify.html, +"thermo_style"_thermo_style.html, +"timer"_timer.html, +"timestep"_timestep.html, +"uncompute"_uncompute.html, +"undump"_undump.html, +"unfix"_unfix.html, +"units"_units.html, +"variable"_variable.html, +"velocity"_velocity.html, +"write_coeff"_write_coeff.html, +"write_data"_write_data.html, +"write_dump"_write_dump.html, +"write_restart"_write_restart.html :tb(c=6,ea=c) + +These are additional commands in USER packages, which can be used if +"LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"dump netcdf"_dump_netcdf.html, +"dump netcdf/mpiio"_dump_netcdf.html, +"dump vtk"_dump_vtk.html, +"group2ndx"_group2ndx.html, +"ndx2group"_group2ndx.html, +"temper/grem"_temper_grem.html, +"temper/npt"_temper_npt.html :tb(c=3,ea=c) + +:line + +Fix styles :h3 + +See the "fix"_fix.html command for one-line descriptions of each style +or click on the style itself for a full description. Some of the +styles have accelerated versions, which can be used if LAMMPS is built +with the "appropriate accelerated package"_Section_accelerate.html. +This is indicated by additional letters in parenthesis: g = GPU, i = +USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT. + +"adapt"_fix_adapt.html, +"addforce"_fix_addforce.html, +"append/atoms"_fix_append_atoms.html, +"atom/swap"_fix_atom_swap.html, +"aveforce"_fix_aveforce.html, +"ave/atom"_fix_ave_atom.html, +"ave/chunk"_fix_ave_chunk.html, +"ave/correlate"_fix_ave_correlate.html, +"ave/histo"_fix_ave_histo.html, +"ave/histo/weight"_fix_ave_histo.html, +"ave/time"_fix_ave_time.html, +"balance"_fix_balance.html, +"bond/break"_fix_bond_break.html, +"bond/create"_fix_bond_create.html, +"bond/swap"_fix_bond_swap.html, +"box/relax"_fix_box_relax.html, +"cmap"_fix_cmap.html, +"controller"_fix_controller.html, +"deform (k)"_fix_deform.html, +"deposit"_fix_deposit.html, +"drag"_fix_drag.html, +"dt/reset"_fix_dt_reset.html, +"efield"_fix_efield.html, +"ehex"_fix_ehex.html, +"enforce2d"_fix_enforce2d.html, +"evaporate"_fix_evaporate.html, +"external"_fix_external.html, +"freeze"_fix_freeze.html, +"gcmc"_fix_gcmc.html, +"gld"_fix_gld.html, +"gravity (o)"_fix_gravity.html, +"halt"_fix_halt.html, +"heat"_fix_heat.html, +"indent"_fix_indent.html, +"latte"_fix_latte.html, +"langevin (k)"_fix_langevin.html, +"lineforce"_fix_lineforce.html, +"momentum (k)"_fix_momentum.html, +"move"_fix_move.html, +"mscg"_fix_mscg.html, +"msst"_fix_msst.html, +"neb"_fix_neb.html, +"nph (ko)"_fix_nh.html, +"nphug (o)"_fix_nphug.html, +"nph/asphere (o)"_fix_nph_asphere.html, +"nph/body"_fix_nph_body.html, +"nph/sphere (o)"_fix_nph_sphere.html, +"npt (kio)"_fix_nh.html, +"npt/asphere (o)"_fix_npt_asphere.html, +"npt/body"_fix_npt_body.html, +"npt/sphere (o)"_fix_npt_sphere.html, +"nve (kio)"_fix_nve.html, +"nve/asphere (i)"_fix_nve_asphere.html, +"nve/asphere/noforce"_fix_nve_asphere_noforce.html, +"nve/body"_fix_nve_body.html, +"nve/limit"_fix_nve_limit.html, +"nve/line"_fix_nve_line.html, +"nve/noforce"_fix_nve_noforce.html, +"nve/sphere (o)"_fix_nve_sphere.html, +"nve/tri"_fix_nve_tri.html, +"nvt (iko)"_fix_nh.html, +"nvt/asphere (o)"_fix_nvt_asphere.html, +"nvt/body"_fix_nvt_body.html, +"nvt/sllod (io)"_fix_nvt_sllod.html, +"nvt/sphere (o)"_fix_nvt_sphere.html, +"oneway"_fix_oneway.html, +"orient/bcc"_fix_orient.html, +"orient/fcc"_fix_orient.html, +"planeforce"_fix_planeforce.html, +"poems"_fix_poems.html, +"pour"_fix_pour.html, +"press/berendsen"_fix_press_berendsen.html, +"print"_fix_print.html, +"property/atom (k)"_fix_property_atom.html, +"python/invoke"_fix_python_invoke.html, +"python/move"_fix_python_move.html, +"qeq/comb (o)"_fix_qeq_comb.html, +"qeq/dynamic"_fix_qeq.html, +"qeq/fire"_fix_qeq.html, +"qeq/point"_fix_qeq.html, +"qeq/shielded"_fix_qeq.html, +"qeq/slater"_fix_qeq.html, +"rattle"_fix_shake.html, +"reax/bonds"_fix_reax_bonds.html, +"recenter"_fix_recenter.html, +"restrain"_fix_restrain.html, +"rigid (o)"_fix_rigid.html, +"rigid/nph (o)"_fix_rigid.html, +"rigid/npt (o)"_fix_rigid.html, +"rigid/nve (o)"_fix_rigid.html, +"rigid/nvt (o)"_fix_rigid.html, +"rigid/small (o)"_fix_rigid.html, +"rigid/small/nph"_fix_rigid.html, +"rigid/small/npt"_fix_rigid.html, +"rigid/small/nve"_fix_rigid.html, +"rigid/small/nvt"_fix_rigid.html, +"setforce (k)"_fix_setforce.html, +"shake"_fix_shake.html, +"spring"_fix_spring.html, +"spring/chunk"_fix_spring_chunk.html, +"spring/rg"_fix_spring_rg.html, +"spring/self"_fix_spring_self.html, +"srd"_fix_srd.html, +"store/force"_fix_store_force.html, +"store/state"_fix_store_state.html, +"temp/berendsen"_fix_temp_berendsen.html, +"temp/csld"_fix_temp_csvr.html, +"temp/csvr"_fix_temp_csvr.html, +"temp/rescale"_fix_temp_rescale.html, +"tfmc"_fix_tfmc.html, +"thermal/conductivity"_fix_thermal_conductivity.html, +"tmd"_fix_tmd.html, +"ttm"_fix_ttm.html, +"tune/kspace"_fix_tune_kspace.html, +"vector"_fix_vector.html, +"viscosity"_fix_viscosity.html, +"viscous"_fix_viscous.html, +"wall/colloid"_fix_wall.html, +"wall/gran"_fix_wall_gran.html, +"wall/gran/region"_fix_wall_gran_region.html, +"wall/harmonic"_fix_wall.html, +"wall/lj1043"_fix_wall.html, +"wall/lj126"_fix_wall.html, +"wall/lj93 (k)"_fix_wall.html, +"wall/piston"_fix_wall_piston.html, +"wall/reflect (k)"_fix_wall_reflect.html, +"wall/region"_fix_wall_region.html, +"wall/srd"_fix_wall_srd.html :tb(c=8,ea=c) + +These are additional fix styles in USER packages, which can be used if +"LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"adapt/fep"_fix_adapt_fep.html, +"addtorque"_fix_addtorque.html, +"atc"_fix_atc.html, +"ave/correlate/long"_fix_ave_correlate_long.html, +"colvars"_fix_colvars.html, +"dpd/energy (k)"_fix_dpd_energy.html, +"drude"_fix_drude.html, +"drude/transform/direct"_fix_drude_transform.html, +"drude/transform/reverse"_fix_drude_transform.html, +"edpd/source"_fix_dpd_source.html, +"eos/cv"_fix_eos_cv.html, +"eos/table"_fix_eos_table.html, +"eos/table/rx (k)"_fix_eos_table_rx.html, +"filter/corotate"_fix_filter_corotate.html, +"flow/gauss"_fix_flow_gauss.html, +"gle"_fix_gle.html, +"grem"_fix_grem.html, +"imd"_fix_imd.html, +"ipi"_fix_ipi.html, +"langevin/drude"_fix_langevin_drude.html, +"langevin/eff"_fix_langevin_eff.html, +"lb/fluid"_fix_lb_fluid.html, +"lb/momentum"_fix_lb_momentum.html, +"lb/pc"_fix_lb_pc.html, +"lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html, +"lb/viscous"_fix_lb_viscous.html, +"meso"_fix_meso.html, +"manifoldforce"_fix_manifoldforce.html, +"meso/stationary"_fix_meso_stationary.html, +"mvv/dpd"_fix_mvv_dpd.html, +"mvv/edpd"_fix_mvv_dpd.html, +"mvv/tdpd"_fix_mvv_dpd.html, +"nve/dot"_fix_nve_dot.html, +"nve/dotc/langevin"_fix_nve_dotc_langevin.html, +"nve/manifold/rattle"_fix_nve_manifold_rattle.html, +"nvk"_fix_nvk.html, +"nvt/manifold/rattle"_fix_nvt_manifold_rattle.html, +"nph/eff"_fix_nh_eff.html, +"npt/eff"_fix_nh_eff.html, +"nve/eff"_fix_nve_eff.html, +"nvt/eff"_fix_nh_eff.html, +"nvt/sllod/eff"_fix_nvt_sllod_eff.html, +"npt/uef"_fix_nh_uef.html, +"nvt/uef"_fix_nh_uef.html, +"phonon"_fix_phonon.html, +"pimd"_fix_pimd.html, +"qbmsst"_fix_qbmsst.html, +"qeq/reax (ko)"_fix_qeq_reax.html, +"qmmm"_fix_qmmm.html, +"qtb"_fix_qtb.html, +"reax/c/bonds (k)"_fix_reax_bonds.html, +"reax/c/species (k)"_fix_reaxc_species.html, +"rhok"_fix_rhok.html, +"rx (k)"_fix_rx.html, +"saed/vtk"_fix_saed_vtk.html, +"shardlow (k)"_fix_shardlow.html, +"smd"_fix_smd.html, +"smd/adjust/dt"_fix_smd_adjust_dt.html, +"smd/integrate/tlsph"_fix_smd_integrate_tlsph.html, +"smd/integrate/ulsph"_fix_smd_integrate_ulsph.html, +"smd/move/triangulated/surface"_fix_smd_move_triangulated_surface.html, +"smd/setvel"_fix_smd_setvel.html, +"smd/wall/surface"_fix_smd_wall_surface.html, +"tdpd/source"_fix_dpd_source.html, +"temp/rescale/eff"_fix_temp_rescale_eff.html, +"ti/spring"_fix_ti_spring.html, +"ttm/mod"_fix_ttm.html, +"wall/ees"_fix_wall_ees.html, +"wall/region/ees"_fix_wall_ees.html :tb(c=6,ea=c) + +:line + +Compute styles :h3 + +See the "compute"_compute.html command for one-line descriptions of +each style or click on the style itself for a full description. Some +of the styles have accelerated versions, which can be used if LAMMPS +is built with the "appropriate accelerated +package"_Section_accelerate.html. This is indicated by additional +letters in parenthesis: g = GPU, i = USER-INTEL, k = +KOKKOS, o = USER-OMP, t = OPT. + +"aggregate/atom"_compute_cluster_atom.html, +"angle"_compute_angle.html, +"angle/local"_compute_angle_local.html, +"angmom/chunk"_compute_angmom_chunk.html, +"body/local"_compute_body_local.html, +"bond"_compute_bond.html, +"bond/local"_compute_bond_local.html, +"centro/atom"_compute_centro_atom.html, +"chunk/atom"_compute_chunk_atom.html, +"cluster/atom"_compute_cluster_atom.html, +"cna/atom"_compute_cna_atom.html, +"com"_compute_com.html, +"com/chunk"_compute_com_chunk.html, +"contact/atom"_compute_contact_atom.html, +"coord/atom"_compute_coord_atom.html, +"damage/atom"_compute_damage_atom.html, +"dihedral"_compute_dihedral.html, +"dihedral/local"_compute_dihedral_local.html, +"dilatation/atom"_compute_dilatation_atom.html, +"dipole/chunk"_compute_dipole_chunk.html, +"displace/atom"_compute_displace_atom.html, +"erotate/asphere"_compute_erotate_asphere.html, +"erotate/rigid"_compute_erotate_rigid.html, +"erotate/sphere"_compute_erotate_sphere.html, +"erotate/sphere/atom"_compute_erotate_sphere_atom.html, +"event/displace"_compute_event_displace.html, +"fragment/atom"_compute_cluster_atom.html, +"global/atom"_compute_global_atom.html, +"group/group"_compute_group_group.html, +"gyration"_compute_gyration.html, +"gyration/chunk"_compute_gyration_chunk.html, +"heat/flux"_compute_heat_flux.html, +"hexorder/atom"_compute_hexorder_atom.html, +"improper"_compute_improper.html, +"improper/local"_compute_improper_local.html, +"inertia/chunk"_compute_inertia_chunk.html, +"ke"_compute_ke.html, +"ke/atom"_compute_ke_atom.html, +"ke/rigid"_compute_ke_rigid.html, +"msd"_compute_msd.html, +"msd/chunk"_compute_msd_chunk.html, +"msd/nongauss"_compute_msd_nongauss.html, +"omega/chunk"_compute_omega_chunk.html, +"orientorder/atom"_compute_orientorder_atom.html, +"pair"_compute_pair.html, +"pair/local"_compute_pair_local.html, +"pe"_compute_pe.html, +"pe/atom"_compute_pe_atom.html, +"plasticity/atom"_compute_plasticity_atom.html, +"pressure"_compute_pressure.html, +"property/atom"_compute_property_atom.html, +"property/local"_compute_property_local.html, +"property/chunk"_compute_property_chunk.html, +"rdf"_compute_rdf.html, +"reduce"_compute_reduce.html, +"reduce/region"_compute_reduce.html, +"rigid/local"_compute_rigid_local.html, +"slice"_compute_slice.html, +"sna/atom"_compute_sna_atom.html, +"snad/atom"_compute_sna_atom.html, +"snav/atom"_compute_sna_atom.html, +"stress/atom"_compute_stress_atom.html, +"temp (k)"_compute_temp.html, +"temp/asphere"_compute_temp_asphere.html, +"temp/body"_compute_temp_body.html, +"temp/chunk"_compute_temp_chunk.html, +"temp/com"_compute_temp_com.html, +"temp/deform"_compute_temp_deform.html, +"temp/partial"_compute_temp_partial.html, +"temp/profile"_compute_temp_profile.html, +"temp/ramp"_compute_temp_ramp.html, +"temp/region"_compute_temp_region.html, +"temp/sphere"_compute_temp_sphere.html, +"ti"_compute_ti.html, +"torque/chunk"_compute_torque_chunk.html, +"vacf"_compute_vacf.html, +"vcm/chunk"_compute_vcm_chunk.html, +"voronoi/atom"_compute_voronoi_atom.html :tb(c=6,ea=c) + +These are additional compute styles in USER packages, which can be +used if "LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"ackland/atom"_compute_ackland_atom.html, +"basal/atom"_compute_basal_atom.html, +"cnp/atom"_compute_cnp_atom.html, +"dpd"_compute_dpd.html, +"dpd/atom"_compute_dpd_atom.html, +"edpd/temp/atom"_compute_edpd_temp_atom.html, +"fep"_compute_fep.html, +"force/tally"_compute_tally.html, +"heat/flux/tally"_compute_tally.html, +"ke/eff"_compute_ke_eff.html, +"ke/atom/eff"_compute_ke_atom_eff.html, +"meso/e/atom"_compute_meso_e_atom.html, +"meso/rho/atom"_compute_meso_rho_atom.html, +"meso/t/atom"_compute_meso_t_atom.html, +"pe/tally"_compute_tally.html, +"pe/mol/tally"_compute_tally.html, +"pressure/uef"_compute_pressure_uef.html, +"saed"_compute_saed.html, +"smd/contact/radius"_compute_smd_contact_radius.html, +"smd/damage"_compute_smd_damage.html, +"smd/hourglass/error"_compute_smd_hourglass_error.html, +"smd/internal/energy"_compute_smd_internal_energy.html, +"smd/plastic/strain"_compute_smd_plastic_strain.html, +"smd/plastic/strain/rate"_compute_smd_plastic_strain_rate.html, +"smd/rho"_compute_smd_rho.html, +"smd/tlsph/defgrad"_compute_smd_tlsph_defgrad.html, +"smd/tlsph/dt"_compute_smd_tlsph_dt.html, +"smd/tlsph/num/neighs"_compute_smd_tlsph_num_neighs.html, +"smd/tlsph/shape"_compute_smd_tlsph_shape.html, +"smd/tlsph/strain"_compute_smd_tlsph_strain.html, +"smd/tlsph/strain/rate"_compute_smd_tlsph_strain_rate.html, +"smd/tlsph/stress"_compute_smd_tlsph_stress.html, +"smd/triangle/mesh/vertices"_compute_smd_triangle_mesh_vertices.html, +"smd/ulsph/num/neighs"_compute_smd_ulsph_num_neighs.html, +"smd/ulsph/strain"_compute_smd_ulsph_strain.html, +"smd/ulsph/strain/rate"_compute_smd_ulsph_strain_rate.html, +"smd/ulsph/stress"_compute_smd_ulsph_stress.html, +"smd/vol"_compute_smd_vol.html, +"stress/tally"_compute_tally.html, +"tdpd/cc/atom"_compute_tdpd_cc_atom.html, +"temp/drude"_compute_temp_drude.html, +"temp/eff"_compute_temp_eff.html, +"temp/deform/eff"_compute_temp_deform_eff.html, +"temp/region/eff"_compute_temp_region_eff.html, +"temp/rotate"_compute_temp_rotate.html, +"temp/uef"_compute_temp_uef.html, +"xrd"_compute_xrd.html :tb(c=6,ea=c) + +:line + +Pair_style potentials :h3 + +See the "pair_style"_pair_style.html command for an overview of pair +potentials. Click on the style itself for a full description. Many +of the styles have accelerated versions, which can be used if LAMMPS +is built with the "appropriate accelerated +package"_Section_accelerate.html. This is indicated by additional +letters in parenthesis: g = GPU, i = USER-INTEL, k = +KOKKOS, o = USER-OMP, t = OPT. + +"none"_pair_none.html, +"zero"_pair_zero.html, +"hybrid"_pair_hybrid.html, +"hybrid/overlay (k)"_pair_hybrid.html, +"adp (o)"_pair_adp.html, +"airebo (oi)"_pair_airebo.html, +"airebo/morse (oi)"_pair_airebo.html, +"beck (go)"_pair_beck.html, +"body"_pair_body.html, +"bop"_pair_bop.html, +"born (go)"_pair_born.html, +"born/coul/dsf"_pair_born.html, +"born/coul/dsf/cs"_pair_born.html, +"born/coul/long (go)"_pair_born.html, +"born/coul/long/cs"_pair_born.html, +"born/coul/msm (o)"_pair_born.html, +"born/coul/wolf (go)"_pair_born.html, +"born/coul/wolf/cs"_pair_born.html, +"brownian (o)"_pair_brownian.html, +"brownian/poly (o)"_pair_brownian.html, +"buck (giko)"_pair_buck.html, +"buck/coul/cut (giko)"_pair_buck.html, +"buck/coul/long (giko)"_pair_buck.html, +"buck/coul/long/cs"_pair_buck.html, +"buck/coul/msm (o)"_pair_buck.html, +"buck/long/coul/long (o)"_pair_buck_long.html, +"colloid (go)"_pair_colloid.html, +"comb (o)"_pair_comb.html, +"comb3"_pair_comb.html, +"coul/cut (gko)"_pair_coul.html, +"coul/debye (gko)"_pair_coul.html, +"coul/dsf (gko)"_pair_coul.html, +"coul/long (gko)"_pair_coul.html, +"coul/long/cs"_pair_coul.html, +"coul/msm"_pair_coul.html, +"coul/streitz"_pair_coul.html, +"coul/wolf (ko)"_pair_coul.html, +"coul/wolf/cs"_pair_coul.html, +"dpd (gio)"_pair_dpd.html, +"dpd/tstat (go)"_pair_dpd.html, +"dsmc"_pair_dsmc.html, +"eam (gikot)"_pair_eam.html, +"eam/alloy (gikot)"_pair_eam.html, +"eam/fs (gikot)"_pair_eam.html, +"eim (o)"_pair_eim.html, +"gauss (go)"_pair_gauss.html, +"gayberne (gio)"_pair_gayberne.html, +"gran/hertz/history (o)"_pair_gran.html, +"gran/hooke (o)"_pair_gran.html, +"gran/hooke/history (o)"_pair_gran.html, +"gw"_pair_gw.html, +"gw/zbl"_pair_gw.html, +"hbond/dreiding/lj (o)"_pair_hbond_dreiding.html, +"hbond/dreiding/morse (o)"_pair_hbond_dreiding.html, +"kim"_pair_kim.html, +"lcbop"_pair_lcbop.html, +"line/lj"_pair_line_lj.html, +"lj/charmm/coul/charmm (iko)"_pair_charmm.html, +"lj/charmm/coul/charmm/implicit (ko)"_pair_charmm.html, +"lj/charmm/coul/long (giko)"_pair_charmm.html, +"lj/charmm/coul/msm"_pair_charmm.html, +"lj/charmmfsw/coul/charmmfsh"_pair_charmm.html, +"lj/charmmfsw/coul/long"_pair_charmm.html, +"lj/class2 (gko)"_pair_class2.html, +"lj/class2/coul/cut (ko)"_pair_class2.html, +"lj/class2/coul/long (gko)"_pair_class2.html, +"lj/cubic (go)"_pair_lj_cubic.html, +"lj/cut (gikot)"_pair_lj.html, +"lj/cut/coul/cut (gko)"_pair_lj.html, +"lj/cut/coul/debye (gko)"_pair_lj.html, +"lj/cut/coul/dsf (gko)"_pair_lj.html, +"lj/cut/coul/long (gikot)"_pair_lj.html, +"lj/cut/coul/long/cs"_pair_lj.html, +"lj/cut/coul/msm (go)"_pair_lj.html, +"lj/cut/coul/wolf (o)"_pair_lj.html, +"lj/cut/dipole/cut (go)"_pair_dipole.html, +"lj/cut/dipole/long"_pair_dipole.html, +"lj/cut/tip4p/cut (o)"_pair_lj.html, +"lj/cut/tip4p/long (ot)"_pair_lj.html, +"lj/expand (gko)"_pair_lj_expand.html, +"lj/gromacs (gko)"_pair_gromacs.html, +"lj/gromacs/coul/gromacs (ko)"_pair_gromacs.html, +"lj/long/coul/long (io)"_pair_lj_long.html, +"lj/long/dipole/long"_pair_dipole.html, +"lj/long/tip4p/long"_pair_lj_long.html, +"lj/smooth (o)"_pair_lj_smooth.html, +"lj/smooth/linear (o)"_pair_lj_smooth_linear.html, +"lj96/cut (go)"_pair_lj96.html, +"lubricate (o)"_pair_lubricate.html, +"lubricate/poly (o)"_pair_lubricate.html, +"lubricateU"_pair_lubricateU.html, +"lubricateU/poly"_pair_lubricateU.html, +"meam"_pair_meam.html, +"mie/cut (o)"_pair_mie.html, +"morse (gkot)"_pair_morse.html, +"nb3b/harmonic (o)"_pair_nb3b_harmonic.html, +"nm/cut (o)"_pair_nm.html, +"nm/cut/coul/cut (o)"_pair_nm.html, +"nm/cut/coul/long (o)"_pair_nm.html, +"peri/eps"_pair_peri.html, +"peri/lps (o)"_pair_peri.html, +"peri/pmb (o)"_pair_peri.html, +"peri/ves"_pair_peri.html, +"polymorphic"_pair_polymorphic.html, +"python"_pair_python.html, +"reax"_pair_reax.html, +"rebo (oi)"_pair_airebo.html, +"resquared (go)"_pair_resquared.html, +"snap (k)"_pair_snap.html, +"soft (go)"_pair_soft.html, +"sw (giko)"_pair_sw.html, +"table (gko)"_pair_table.html, +"tersoff (giko)"_pair_tersoff.html, +"tersoff/mod (gko)"_pair_tersoff_mod.html, +"tersoff/mod/c (o)"_pair_tersoff_mod.html, +"tersoff/zbl (gko)"_pair_tersoff_zbl.html, +"tip4p/cut (o)"_pair_coul.html, +"tip4p/long (o)"_pair_coul.html, +"tri/lj"_pair_tri_lj.html, +"ufm (got)"_pair_ufm.html, +"vashishta (ko)"_pair_vashishta.html, +"vashishta/table (o)"_pair_vashishta.html, +"yukawa (gok)"_pair_yukawa.html, +"yukawa/colloid (go)"_pair_yukawa_colloid.html, +"zbl (gok)"_pair_zbl.html :tb(c=4,ea=c) + +These are additional pair styles in USER packages, which can be used +if "LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"agni (o)"_pair_agni.html, +"awpmd/cut"_pair_awpmd.html, +"buck/mdf"_pair_mdf.html, +"coul/cut/soft (o)"_pair_lj_soft.html, +"coul/diel (o)"_pair_coul_diel.html, +"coul/long/soft (o)"_pair_lj_soft.html, +"coul/shield"_pair_coul_shield.html, +"dpd/fdt"_pair_dpd_fdt.html, +"dpd/fdt/energy (k)"_pair_dpd_fdt.html, +"eam/cd (o)"_pair_eam.html, +"edip (o)"_pair_edip.html, +"edip/multi"_pair_edip.html, +"edpd"_pair_meso.html, +"eff/cut"_pair_eff.html, +"exp6/rx (k)"_pair_exp6_rx.html, +"extep"_pair_extep.html, +"gauss/cut"_pair_gauss.html, +"ilp/graphene/hbn"_pair_ilp_graphene_hbn.html, +"kolmogorov/crespi/full"_pair_kolmogorov_crespi_full.html, +"kolmogorov/crespi/z"_pair_kolmogorov_crespi_z.html, +"lennard/mdf"_pair_mdf.html, +"list"_pair_list.html, +"lj/charmm/coul/long/soft (o)"_pair_charmm.html, +"lj/cut/coul/cut/soft (o)"_pair_lj_soft.html, +"lj/cut/coul/long/soft (o)"_pair_lj_soft.html, +"lj/cut/dipole/sf (go)"_pair_dipole.html, +"lj/cut/soft (o)"_pair_lj_soft.html, +"lj/cut/thole/long (o)"_pair_thole.html, +"lj/cut/tip4p/long/soft (o)"_pair_lj_soft.html, +"lj/mdf"_pair_mdf.html, +"lj/sdk (gko)"_pair_sdk.html, +"lj/sdk/coul/long (go)"_pair_sdk.html, +"lj/sdk/coul/msm (o)"_pair_sdk.html, +"mdpd"_pair_meso.html, +"mdpd/rhosum"_pair_meso.html, +"meam/c"_pair_meam.html, +"meam/spline (o)"_pair_meam_spline.html, +"meam/sw/spline"_pair_meam_sw_spline.html, +"mgpt"_pair_mgpt.html, +"momb"_pair_momb.html, +"morse/smooth/linear"_pair_morse.html, +"morse/soft"_pair_morse.html, +"multi/lucy"_pair_multi_lucy.html, +"multi/lucy/rx (k)"_pair_multi_lucy_rx.html, +"oxdna/coaxstk"_pair_oxdna.html, +"oxdna/excv"_pair_oxdna.html, +"oxdna/hbond"_pair_oxdna.html, +"oxdna/stk"_pair_oxdna.html, +"oxdna/xstk"_pair_oxdna.html, +"oxdna2/coaxstk"_pair_oxdna2.html, +"oxdna2/dh"_pair_oxdna2.html, +"oxdna2/excv"_pair_oxdna2.html, +"oxdna2/stk"_pair_oxdna2.html, +"quip"_pair_quip.html, +"reax/c (ko)"_pair_reaxc.html, +"smd/hertz"_pair_smd_hertz.html, +"smd/tlsph"_pair_smd_tlsph.html, +"smd/triangulated/surface"_pair_smd_triangulated_surface.html, +"smd/ulsph"_pair_smd_ulsph.html, +"smtbq"_pair_smtbq.html, +"snap (k)"_pair_snap.html, +"sph/heatconduction"_pair_sph_heatconduction.html, +"sph/idealgas"_pair_sph_idealgas.html, +"sph/lj"_pair_sph_lj.html, +"sph/rhosum"_pair_sph_rhosum.html, +"sph/taitwater"_pair_sph_taitwater.html, +"sph/taitwater/morris"_pair_sph_taitwater_morris.html, +"srp"_pair_srp.html, +"table/rx (k)"_pair_table_rx.html, +"tdpd"_pair_meso.html, +"tersoff/table (o)"_pair_tersoff.html, +"thole"_pair_thole.html, +"tip4p/long/soft (o)"_pair_lj_soft.html :tb(c=4,ea=c) + +:line + +Bond_style potentials :h3 + +See the "bond_style"_bond_style.html command for an overview of bond +potentials. Click on the style itself for a full description. Some +of the styles have accelerated versions, which can be used if LAMMPS +is built with the "appropriate accelerated +package"_Section_accelerate.html. This is indicated by additional +letters in parenthesis: g = GPU, i = USER-INTEL, k = +KOKKOS, o = USER-OMP, t = OPT. + +"none"_bond_none.html, +"zero"_bond_zero.html, +"hybrid"_bond_hybrid.html, +"class2 (ko)"_bond_class2.html, +"fene (iko)"_bond_fene.html, +"fene/expand (o)"_bond_fene_expand.html, +"gromos (o)"_bond_gromos.html, +"harmonic (ko)"_bond_harmonic.html, +"morse (o)"_bond_morse.html, +"nonlinear (o)"_bond_nonlinear.html, +"quartic (o)"_bond_quartic.html, +"table (o)"_bond_table.html :tb(c=4,ea=c) + +These are additional bond styles in USER packages, which can be used +if "LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"harmonic/shift (o)"_bond_harmonic_shift.html, +"harmonic/shift/cut (o)"_bond_harmonic_shift_cut.html, +"oxdna/fene"_bond_oxdna.html, +"oxdna2/fene"_bond_oxdna.html :tb(c=4,ea=c) + +:line + +Angle_style potentials :h3 + +See the "angle_style"_angle_style.html command for an overview of +angle potentials. Click on the style itself for a full description. +Some of the styles have accelerated versions, which can be used if +LAMMPS is built with the "appropriate accelerated +package"_Section_accelerate.html. This is indicated by additional +letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = +USER-OMP, t = OPT. + +"none"_angle_none.html, +"zero"_angle_zero.html, +"hybrid"_angle_hybrid.html, +"charmm (ko)"_angle_charmm.html, +"class2 (ko)"_angle_class2.html, +"cosine (o)"_angle_cosine.html, +"cosine/delta (o)"_angle_cosine_delta.html, +"cosine/periodic (o)"_angle_cosine_periodic.html, +"cosine/squared (o)"_angle_cosine_squared.html, +"harmonic (iko)"_angle_harmonic.html, +"table (o)"_angle_table.html :tb(c=4,ea=c) + +These are additional angle styles in USER packages, which can be used +if "LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"cosine/shift (o)"_angle_cosine_shift.html, +"cosine/shift/exp (o)"_angle_cosine_shift_exp.html, +"dipole (o)"_angle_dipole.html, +"fourier (o)"_angle_fourier.html, +"fourier/simple (o)"_angle_fourier_simple.html, +"quartic (o)"_angle_quartic.html, +"sdk"_angle_sdk.html :tb(c=4,ea=c) + +:line + +Dihedral_style potentials :h3 + +See the "dihedral_style"_dihedral_style.html command for an overview +of dihedral potentials. Click on the style itself for a full +description. Some of the styles have accelerated versions, which can +be used if LAMMPS is built with the "appropriate accelerated +package"_Section_accelerate.html. This is indicated by additional +letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = +USER-OMP, t = OPT. + +"none"_dihedral_none.html, +"zero"_dihedral_zero.html, +"hybrid"_dihedral_hybrid.html, +"charmm (iko)"_dihedral_charmm.html, +"charmmfsw"_dihedral_charmm.html, +"class2 (ko)"_dihedral_class2.html, +"harmonic (io)"_dihedral_harmonic.html, +"helix (o)"_dihedral_helix.html, +"multi/harmonic (o)"_dihedral_multi_harmonic.html, +"opls (iko)"_dihedral_opls.html :tb(c=4,ea=c) + +These are additional dihedral styles in USER packages, which can be +used if "LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"cosine/shift/exp (o)"_dihedral_cosine_shift_exp.html, +"fourier (io)"_dihedral_fourier.html, +"nharmonic (o)"_dihedral_nharmonic.html, +"quadratic (o)"_dihedral_quadratic.html, +"spherical (o)"_dihedral_spherical.html, +"table (o)"_dihedral_table.html :tb(c=4,ea=c) + +:line + +Improper_style potentials :h3 + +See the "improper_style"_improper_style.html command for an overview +of improper potentials. Click on the style itself for a full +description. Some of the styles have accelerated versions, which can +be used if LAMMPS is built with the "appropriate accelerated +package"_Section_accelerate.html. This is indicated by additional +letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = +USER-OMP, t = OPT. + +"none"_improper_none.html, +"zero"_improper_zero.html, +"hybrid"_improper_hybrid.html, +"class2 (ko)"_improper_class2.html, +"cvff (io)"_improper_cvff.html, +"harmonic (iko)"_improper_harmonic.html, +"umbrella (o)"_improper_umbrella.html :tb(c=4,ea=c) + +These are additional improper styles in USER packages, which can be +used if "LAMMPS is built with the appropriate +package"_Section_start.html#start_3. + +"cossq (o)"_improper_cossq.html, +"distance"_improper_distance.html, +"fourier (o)"_improper_fourier.html, +"ring (o)"_improper_ring.html :tb(c=4,ea=c) + +:line + +Kspace solvers :h3 + +See the "kspace_style"_kspace_style.html command for an overview of +Kspace solvers. Click on the style itself for a full description. +Some of the styles have accelerated versions, which can be used if +LAMMPS is built with the "appropriate accelerated +package"_Section_accelerate.html. This is indicated by additional +letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = +USER-OMP, t = OPT. + +"ewald (o)"_kspace_style.html, +"ewald/disp"_kspace_style.html, +"msm (o)"_kspace_style.html, +"msm/cg (o)"_kspace_style.html, +"pppm (gok)"_kspace_style.html, +"pppm/cg (o)"_kspace_style.html, +"pppm/disp (i)"_kspace_style.html, +"pppm/disp/tip4p"_kspace_style.html, +"pppm/stagger"_kspace_style.html, +"pppm/tip4p (o)"_kspace_style.html :tb(c=4,ea=c) diff --git a/doc/compute_displace_atom.txt b/doc/compute_displace_atom.txt new file mode 100644 index 0000000000..150a6fb30e --- /dev/null +++ b/doc/compute_displace_atom.txt @@ -0,0 +1,137 @@ +"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 displace/atom command :h3 + +[Syntax:] + +compute ID group-ID displace/atom :pre + +ID, group-ID are documented in "compute"_compute.html command :ulb,l +displace/atom = style name of this compute command :l +zero or more keyword/arg pairs may be appended :l +keyword = {refresh} :l + {replace} arg = per-atom variable ID :pre +:ule + +[Examples:] + +compute 1 all displace/atom +compute 1 all displace/atom refresh myVar :pre + +[Description:] + +Define a computation that calculates the current displacement of each +atom in the group from its original (reference) coordinates, including +all effects due to atoms passing thru periodic boundaries. + +A vector of four quantities per atom is calculated by this compute. +The first 3 elements of the vector are the dx,dy,dz displacements. +The 4th component is the total displacement, i.e. sqrt(dx*dx + dy*dy + +dz*dz). + +The displacement of an atom is from its original position at the time +the compute command was issued. The value of the displacement will be +0.0 for atoms not in the specified compute group. + +NOTE: Initial coordinates are stored in "unwrapped" form, by using the +image flags associated with each atom. See the "dump +custom"_dump.html command for a discussion of "unwrapped" coordinates. +See the Atoms section of the "read_data"_read_data.html command for a +discussion of image flags and how they are set for each atom. You can +reset the image flags (e.g. to 0) before invoking this compute by +using the "set image"_set.html command. + +NOTE: If you want the quantities calculated by this compute to be +continuous when running from a "restart file"_read_restart.html, then +you should use the same ID for this compute, as in the original run. +This is so that the fix this compute creates to store per-atom +quantities will also have the same ID, and thus be initialized +correctly with time=0 atom coordinates from the restart file. + +:line + +The {refresh} option can be used in conjuction with the "dump_modify +refresh" command to generate incremental dump files. + +The definition and motivation of an incremental dump file is as +follows. Instead of outputting all atoms at each snapshot (with some +associated values), you may only wish to output the subset of atoms +with a value that has changed in some way compared to the value the +last time that atom was output. In some scenarios this can result in +a dramatically smaller dump file. If desired, by post-processing the +sequence of snapshots, the values for all atoms at all timesteps can +be inferred. + +A concrete example using this compute, is a simulation of atom +diffusion in a solid, represented as atoms on a lattice. Diffusive +hops are rare. Imagine that when a hop occurs an atom moves more than +a distance {Dhop}. For any snapshot we only want to output atoms that +have hopped since the last snapshot. This can be accomplished with +something like the following commands: + +write_dump all custom tmp.dump id type x y z # see comment below :pre + +variable Dhop equal 0.6 +variable check atom "c_dsp[4] > v_Dhop" +compute dsp all displace/atom refresh check +dump 1 all custom 100 tmp.dump id type x y z +dump_modify 1 append yes thresh c_dsp[4] > ${Dhop} & + refresh c_dsp delay 100 :pre + +The "dump_modify thresh"_dump_modify.html command will only ouptut +atoms that have displaced more than 0.6 Angstroms on each snapshot +(assuming metal units). The dump_modify {refresh} option triggers a +call to this compute at the end of every dump. + +The {refresh} argument for this compute is the ID of an "atom-style +variable"_variable.html which calculates a Boolean value (0 or 1) +based on the same criterion used by dump_modify thresh. This compute +evaluates the atom-style variable. For each atom that returns 1 +(true), the original (reference) coordinates of the atom (stored by +this compute) are updated. + +The effect of these commands is that a particular atom will only be +output in the dump file on the snapshot after it makes a diffusive +hop. It will not be output again until it makes another hop. + +Note that in the first snapshot of a subsequent run, no atoms will be +typically be output. That is because the initial displacement for all +atoms is 0.0. If an initial dump snapshot is desired, containing the +initial reference positions of all atoms, one way to do this is +illustrated above. An initial write_dump command can be used before +the first run. It will contain the positions of all the atoms, +Options in the "dump_modify"_dump_modify.html command above will +append new output to that same file and delay the output until a later +timestep. The {delay} setting avoids a second time = 0 snapshot which +would be empty. + +:line + +[Output info:] + +This compute calculates a per-atom array with 4 columns, which can be +accessed by indices 1-4 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 distance "units"_units.html. + +This compute supports the {refresh} option as explained above, for use +in conjunction with "dump_modify refresh"_dump_modify.html to generate +incremental dump files. + +[Restrictions:] none + +[Related commands:] + +"compute msd"_compute_msd.html, "dump custom"_dump.html, "fix +store/state"_fix_store_state.html + +[Default:] none diff --git a/doc/create_atoms.txt b/doc/create_atoms.txt new file mode 100644 index 0000000000..5d824ae1ef --- /dev/null +++ b/doc/create_atoms.txt @@ -0,0 +1,335 @@ +"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 + +create_atoms command :h3 + +[Syntax:] + +create_atoms type style args keyword values ... :pre + +type = atom type (1-Ntypes) of atoms to create (offset for molecule creation) :ulb,l +style = {box} or {region} or {single} or {random} :l + {box} args = none + {region} args = region-ID + region-ID = particles will only be created if contained in the region + {single} args = x y z + x,y,z = coordinates of a single particle (distance units) + {random} args = N seed region-ID + N = number of particles to create + seed = random # seed (positive integer) + region-ID = create atoms within this region, use NULL for entire simulation box :pre +zero or more keyword/value pairs may be appended :l +keyword = {mol} or {basis} or {remap} or {var} or {set} or {units} :l + {mol} value = template-ID seed + template-ID = ID of molecule template specified in a separate "molecule"_molecule.html command + seed = random # seed (positive integer) + {basis} values = M itype + M = which basis atom + itype = atom type (1-N) to assign to this basis atom + {remap} value = {yes} or {no} + {var} value = name = variable name to evaluate for test of atom creation + {set} values = dim name + dim = {x} or {y} or {z} + name = name of variable to set with x, y, or z atom position + {rotate} values = theta Rx Ry Rz + theta = rotation angle for single molecule (degrees) + Rx,Ry,Rz = rotation vector for single molecule + {units} value = {lattice} or {box} + {lattice} = the geometry is defined in lattice units + {box} = the geometry is defined in simulation box units :pre +:ule + +[Examples:] + +create_atoms 1 box +create_atoms 3 region regsphere basis 2 3 +create_atoms 3 single 0 0 5 +create_atoms 1 box var v set x xpos set y ypos :pre + +[Description:] + +This command creates atoms (or molecules) on a lattice, or a single +atom (or molecule), or a random collection of atoms (or molecules), as +an alternative to reading in their coordinates explicitly via a +"read_data"_read_data.html or "read_restart"_read_restart.html +command. A simulation box must already exist, which is typically +created via the "create_box"_create_box.html command. Before using +this command, a lattice must also be defined using the +"lattice"_lattice.html command, unless you specify the {single} style +with units = box or the {random} style. For the remainder of this doc +page, a created atom or molecule is referred to as a "particle". + +If created particles are individual atoms, they are assigned the +specified atom {type}, though this can be altered via the {basis} +keyword as discussed below. If molecules are being created, the type +of each atom in the created molecule is specified in the file read by +the "molecule"_molecule.html command, and those values are added to +the specified atom {type}. E.g. if {type} = 2, and the file specifies +atom types 1,2,3, then each created molecule will have atom types +3,4,5. + +For the {box} style, the create_atoms command fills the entire +simulation box with particles on the lattice. If your simulation box +is periodic, you should insure its size is a multiple of the lattice +spacings, to avoid unwanted atom overlaps at the box boundaries. If +your box is periodic and a multiple of the lattice spacing in a +particular dimension, LAMMPS is careful to put exactly one particle at +the boundary (on either side of the box), not zero or two. + +For the {region} style, a geometric volume is filled with particles on +the lattice. This volume what is inside the simulation box and is +also consistent with the region volume. See the "region"_region.html +command for details. Note that a region can be specified so that its +"volume" is either inside or outside a geometric boundary. Also note +that if your region is the same size as a periodic simulation box (in +some dimension), LAMMPS does not implement the same logic described +above as for the {box} style, to insure exactly one particle at +periodic boundaries. if this is what you desire, you should either +use the {box} style, or tweak the region size to get precisely the +particles you want. + +For the {single} style, a single particle is added to the system at +the specified coordinates. This can be useful for debugging purposes +or to create a tiny system with a handful of particles at specified +positions. + +For the {random} style, N particles are added to the system at +randomly generated coordinates, which can be useful for generating an +amorphous system. The particles are created one by one using the +specified random number {seed}, resulting in the same set of particles +coordinates, independent of how many processors are being used in the +simulation. If the {region-ID} argument is specified as NULL, then +the created particles will be anywhere in the simulation box. If a +{region-ID} is specified, a geometric volume is filled which is both +inside the simulation box and is also consistent with the region +volume. See the "region"_region.html command for details. Note that +a region can be specified so that its "volume" is either inside or +outside a geometric boundary. + +NOTE: Particles generated by the {random} style will typically be +highly overlapped which will cause many interatomic potentials to +compute large energies and forces. Thus you should either perform an +"energy minimization"_minimize.html or run dynamics with "fix +nve/limit"_fix_nve_limit.html to equilibrate such a system, before +running normal dynamics. + +Note that this command adds particles to those that already exist. +This means it can be used to add particles to a system previously read +in from a data or restart file. Or the create_atoms command can be +used multiple times, to add multiple sets of particles to the +simulation. For example, grain boundaries can be created, by +interleaving create_atoms with "lattice"_lattice.html commands +specifying different orientations. By using the create_atoms command +in conjunction with the "delete_atoms"_delete_atoms.html command, +reasonably complex geometries can be created, or a protein can be +solvated with a surrounding box of water molecules. + +In all these cases, care should be taken to insure that new atoms do +not overlap existing atoms inappropriately, especially if molecules +are being added. The "delete_atoms"_delete_atoms.html command can be +used to remove overlapping atoms or molecules. + +NOTE: You cannot use any of the styles explained above to create atoms +that are outside the simulation box; they will just be ignored by +LAMMPS. This is true even if you are using shrink-wrapped box +boundaries, as specified by the "boundary"_boundary.html command. +However, you can first use the "change_box"_change_box.html command to +temporarily expand the box, then add atoms via create_atoms, then +finally use change_box command again if needed to re-shrink-wrap the +new atoms. See the "change_box"_change_box.html doc page for an +example of how to do this, using the create_atoms {single} style to +insert a new atom outside the current simulation box. + +:line + +Individual atoms are inserted by this command, unless the {mol} +keyword is used. It specifies a {template-ID} previously defined +using the "molecule"_molecule.html command, which reads a file that +defines the molecule. The coordinates, atom types, charges, etc, as +well as any bond/angle/etc and special neighbor information for the +molecule can be specified in the molecule file. See the +"molecule"_molecule.html command for details. The only settings +required to be in this file are the coordinates and types of atoms in +the molecule. + +Using a lattice to add molecules, e.g. via the {box} or {region} or +{single} styles, is exactly the same as adding atoms on lattice +points, except that entire molecules are added at each point, i.e. on +the point defined by each basis atom in the unit cell as it tiles the +simulation box or region. This is done by placing the geometric +center of the molecule at the lattice point, and giving the molecule a +random orientation about the point. The random {seed} specified with +the {mol} keyword is used for this operation, and the random numbers +generated by each processor are different. This means the coordinates +of individual atoms (in the molecules) will be different when running +on different numbers of processors, unlike when atoms are being +created in parallel. + +Also note that because of the random rotations, it may be important to +use a lattice with a large enough spacing that adjacent molecules will +not overlap, regardless of their relative orientations. + +NOTE: If the "create_box"_create_box.html command is used to create +the simulation box, followed by the create_atoms command with its +{mol} option for adding molecules, then you typically need to use the +optional keywords allowed by the "create_box"_create_box.html command +for extra bonds (angles,etc) or extra special neighbors. This is +because by default, the "create_box"_create_box.html command sets up a +non-molecular system which doesn't allow molecules to be added. + +:line + +This is the meaning of the other allowed keywords. + +The {basis} keyword is only used when atoms (not molecules) are being +created. It specifies an atom type that will be assigned to specific +basis atoms as they are created. See the "lattice"_lattice.html +command for specifics on how basis atoms are defined for the unit cell +of the lattice. By default, all created atoms are assigned the +argument {type} as their atom type. + +The {remap} keyword only applies to the {single} style. If it is set +to {yes}, then if the specified position is outside the simulation +box, it will mapped back into the box, assuming the relevant +dimensions are periodic. If it is set to {no}, no remapping is done +and no particle is created if its position is outside the box. + +The {var} and {set} keywords can be used together to provide a +criterion for accepting or rejecting the addition of an individual +atom, based on its coordinates. The {name} specified for the {var} +keyword is the name of an "equal-style variable"_variable.html which +should evaluate to a zero or non-zero value based on one or two or +three variables which will store the x, y, or z coordinates of an atom +(one variable per coordinate). If used, these other variables must be +"internal-style variables"_variable.html defined in the input script; +their initial numeric value can be anything. They must be +internal-style variables, because this command resets their values +directly. The {set} keyword is used to identify the names of these +other variables, one variable for the x-coordinate of a created atom, +one for y, and one for z. + +When an atom is created, its x,y,z coordinates become the values for +any {set} variable that is defined. The {var} variable is then +evaluated. If the returned value is 0.0, the atom is not created. If +it is non-zero, the atom is created. + +As an example, these commands can be used in a 2d simulation, to +create a sinusoidal surface. Note that the surface is "rough" due to +individual lattice points being "above" or "below" the mathematical +expression for the sinusoidal curve. If a finer lattice were used, +the sinusoid would appear to be "smoother". Also note the use of the +"xlat" and "ylat" "thermo_style"_thermo_style.html keywords which +converts lattice spacings to distance. Click on the image for a +larger version. + +dimension 2 +variable x equal 100 +variable y equal 25 +lattice hex 0.8442 +region box block 0 $x 0 $y -0.5 0.5 +create_box 1 box :pre + +variable xx internal 0.0 +variable yy internal 0.0 +variable v equal "(0.2*v_y*ylat * cos(v_xx/xlat * 2.0*PI*4.0/v_x) + 0.5*v_y*ylat - v_yy) > 0.0" +create_atoms 1 box var v set x xx set y yy +write_dump all atom sinusoid.lammpstrj :pre + +:c,image(JPG/sinusoid_small.jpg,JPG/sinusoid.jpg) + +The {rotate} keyword can only be used with the {single} style and +when adding a single molecule. It allows to specify the orientation +at which the molecule is inserted. The axis of rotation is +determined by the rotation vector (Rx,Ry,Rz) that goes through the +insertion point. The specified {theta} determines the angle of +rotation around that axis. Note that the direction of rotation for +the atoms around the rotation axis is consistent with the right-hand +rule: if your right-hand's thumb points along {R}, then your fingers +wrap around the axis in the direction of rotation. + +The {units} keyword determines the meaning of the distance units used +to specify the coordinates of the one particle created by the {single} +style. A {box} value selects standard distance units as defined by +the "units"_units.html command, e.g. Angstroms for units = real or +metal. A {lattice} value means the distance units are in lattice +spacings. + +:line + +Atom IDs are assigned to created atoms in the following way. The +collection of created atoms are assigned consecutive IDs that start +immediately following the largest atom ID existing before the +create_atoms command was invoked. This is done by the processor's +communicating the number of atoms they each own, the first processor +numbering its atoms from 1 to N1, the second processor from N1+1 to +N2, etc. Where N1 = number of atoms owned by the first processor, N2 += number owned by the second processor, etc. Thus when the same +simulation is performed on different numbers of processors, there is +no guarantee a particular created atom will be assigned the same ID in +both simulations. If molecules are being created, molecule IDs are +assigned to created molecules in a similar fashion. + +Aside from their ID, atom type, and xyz position, other properties of +created atoms are set to default values, depending on which quantities +are defined by the chosen "atom style"_atom_style.html. See the "atom +style"_atom_style.html command for more details. See the +"set"_set.html and "velocity"_velocity.html commands for info on how +to change these values. + +charge = 0.0 +dipole moment magnitude = 0.0 +diameter = 1.0 +shape = 0.0 0.0 0.0 +density = 1.0 +volume = 1.0 +velocity = 0.0 0.0 0.0 +angular velocity = 0.0 0.0 0.0 +angular momentum = 0.0 0.0 0.0 +quaternion = (1,0,0,0) +bonds, angles, dihedrals, impropers = none :ul + +If molecules are being created, these defaults can be overridden by +values specified in the file read by the "molecule"_molecule.html +command. E.g. the file typically defines bonds (angles,etc) between +atoms in the molecule, and can optionally define charges on each atom. + +Note that the {sphere} atom style sets the default particle diameter +to 1.0 as well as the density. This means the mass for the particle +is not 1.0, but is PI/6 * diameter^3 = 0.5236. + +Note that the {ellipsoid} atom style sets the default particle shape +to (0.0 0.0 0.0) and the density to 1.0 which means it is a point +particle, not an ellipsoid, and has a mass of 1.0. + +Note that the {peri} style sets the default volume and density to 1.0 +and thus also set the mass for the particle to 1.0. + +The "set"_set.html command can be used to override many of these +default settings. + +:line + +[Restrictions:] + +An "atom_style"_atom_style.html must be previously defined to use this +command. + +A rotation vector specified for a single molecule must be in +the z-direction for a 2d model. + +[Related commands:] + +"lattice"_lattice.html, "region"_region.html, "create_box"_create_box.html, +"read_data"_read_data.html, "read_restart"_read_restart.html + +[Default:] + +The default for the {basis} keyword is that all created atoms are +assigned the argument {type} as their atom type (when single atoms are +being created). The other defaults are {remap} = no, {rotate} = +random, and {units} = lattice. diff --git a/doc/delete_atoms.txt b/doc/delete_atoms.txt new file mode 100644 index 0000000000..1aa71d341f --- /dev/null +++ b/doc/delete_atoms.txt @@ -0,0 +1,152 @@ +"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 + +delete_atoms command :h3 + +[Syntax:] + +delete_atoms style args keyword value ... :pre + +style = {group} or {region} or {overlap} or {porosity} :ulb,l + {group} args = group-ID + {region} args = region-ID + {overlap} args = cutoff group1-ID group2-ID + cutoff = delete one atom from pairs of atoms within the cutoff (distance units) + group1-ID = one atom in pair must be in this group + group2-ID = other atom in pair must be in this group + {porosity} args = region-ID fraction seed + region-ID = region within which to perform deletions + fraction = delete this fraction of atoms + seed = random number seed (positive integer) :pre +zero or more keyword/value pairs may be appended :l +keyword = {compress} or {bond} or {mol} :l + {compress} value = {no} or {yes} + {bond} value = {no} or {yes} + {mol} value = {no} or {yes} :pre +:ule + +[Examples:] + +delete_atoms group edge +delete_atoms region sphere compress no +delete_atoms overlap 0.3 all all +delete_atoms overlap 0.5 solvent colloid +delete_atoms porosity cube 0.1 482793 bond yes :pre + +[Description:] + +Delete the specified atoms. This command can be used to carve out +voids from a block of material or to delete created atoms that are too +close to each other (e.g. at a grain boundary). + +For style {group}, all atoms belonging to the group are deleted. + +For style {region}, all atoms in the region volume are deleted. +Additional atoms can be deleted if they are in a molecule for which +one or more atoms were deleted within the region; see the {mol} +keyword discussion below. + +For style {overlap} pairs of atoms whose distance of separation is +within the specified cutoff distance are searched for, and one of the +2 atoms is deleted. Only pairs where one of the two atoms is in the +first group specified and the other atom is in the second group are +considered. The atom that is in the first group is the one that is +deleted. + +Note that it is OK for the two group IDs to be the same (e.g. group +{all}), or for some atoms to be members of both groups. In these +cases, either atom in the pair may be deleted. Also note that if +there are atoms which are members of both groups, the only guarantee +is that at the end of the deletion operation, enough deletions will +have occurred that no atom pairs within the cutoff will remain +(subject to the group restriction). There is no guarantee that the +minimum number of atoms will be deleted, or that the same atoms will +be deleted when running on different numbers of processors. + +For style {porosity} a specified {fraction} of atoms are deleted +within the specified region. For example, if fraction is 0.1, then +10% of the atoms will be deleted. The atoms to delete are chosen +randomly. There is no guarantee that the exact fraction of atoms will +be deleted, or that the same atoms will be deleted when running on +different numbers of processors. + +If the {compress} keyword is set to {yes}, then after atoms are +deleted, then atom IDs are re-assigned so that they run from 1 to the +number of atoms in the system. Note that this is not done for +molecular systems (see the "atom_style"_atom_style.html command), +regardless of the {compress} setting, since it would foul up the bond +connectivity that has already been assigned. However, the +"reset_ids"_reset_ids.html command can be used after this command to +accomplish the same thing. + +Note that the re-assignement of IDs is not really a compression, where +gaps in atom IDs are removed by decrementing atom IDs that are larger. +Instead the IDs for all atoms are erased, and new IDs are assigned so +that the atoms owned by individual processors have consecutive IDs, as +the "create_atoms"_create_atoms.html command explains. + +A molecular system with fixed bonds, angles, dihedrals, or improper +interactions, is one where the topology of the interactions is +typically defined in the data file read by the +"read_data"_read_data.html command, and where the interactions +themselves are defined with the "bond_style"_bond_style.html, +"angle_style"_angle_style.html, etc commands. If you delete atoms +from such a system, you must be careful not to end up with bonded +interactions that are stored by remaining atoms but which include +deleted atoms. This will cause LAMMPS to generate a "missing atoms" +error when the bonded interaction is computed. The {bond} and {mol} +keywords offer two ways to do that. + +It the {bond} keyword is set to {yes} then any bond or angle or +dihedral or improper interaction that includes a deleted atom is also +removed from the lists of such interactions stored by non-deleted +atoms. Note that simply deleting interactions due to dangling bonds +(e.g. at a surface) may result in a inaccurate or invalid model for +the remaining atoms. + +It the {mol} keyword is set to {yes}, then for every atom that is +deleted, all other atoms in the same molecule (with the same molecule +ID) will also be deleted. This is not done for atoms with molecule ID += 0, since such an ID is assumed to flag isolated atoms that are not +part of molecules. + +NOTE: The molecule deletion operation in invoked after all individual +atoms have been deleted using the rules described above for each +style. This means additional atoms may be deleted that are not in the +group or region, that are not required by the overlap cutoff +criterion, or that will create a higher fraction of porosity than was +requested. + +[Restrictions:] + +The {overlap} styles requires inter-processor communication to acquire +ghost atoms and build a neighbor list. This means that your system +must be ready to perform a simulation before using this command (force +fields setup, atom masses set, etc). Since a neighbor list is used to +find overlapping atom pairs, it also means that you must define a +"pair style"_pair_style.html with the minimum force cutoff distance +between any pair of atoms types (plus the "neighbor"_neighbor.html +skin) >= the specified overlap cutoff. + +If the "special_bonds"_special_bonds.html command is used with a +setting of 0, then a pair of bonded atoms (1-2, 1-3, or 1-4) will not +appear in the neighbor list, and thus will not be considered for +deletion by the {overlap} styles. You probably don't want to be +deleting one atom in a bonded pair anyway. + +The {bond yes} option cannot be used with molecular systems defined +using molecule template files via the "molecule"_molecule.html and +"atom_style template"_atom_style.html commands. + +[Related commands:] + +"create_atoms"_create_atoms.html, "reset_ids"_reset_ids.html + +[Default:] + +The option defaults are compress = yes, bond = no, mol = no. diff --git a/doc/dump.txt b/doc/dump.txt new file mode 100644 index 0000000000..9c386e2410 --- /dev/null +++ b/doc/dump.txt @@ -0,0 +1,664 @@ + "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 command :h3 +"dump vtk"_dump_vtk.html command :h3 +"dump h5md"_dump_h5md.html command :h3 +"dump molfile"_dump_molfile.html command :h3 +"dump netcdf"_dump_netcdf.html command :h3 +"dump image"_dump_image.html command :h3 +"dump movie"_dump_image.html command :h3 + +[Syntax:] + +dump ID group-ID style N file args :pre + +ID = user-assigned name for the dump :ulb,l +group-ID = ID of the group of atoms to be dumped :l +style = {atom} or {atom/gz} or {atom/mpiio} or {cfg} or {cfg/gz} or {cfg/mpiio} or {custom} or {custom/gz} or {custom/mpiio} or {dcd} or {h5md} or {image} or or {local} or {molfile} or {movie} or {netcdf} or {netcdf/mpiio} or {vtk} or {xtc} or {xyz} or {xyz/gz} or {xyz/mpiio} :l +N = dump every this many timesteps :l +file = name of file to write dump info to :l +args = list of arguments for a particular style :l + {atom} args = none + {atom/gz} args = none + {atom/mpiio} args = none + {cfg} args = same as {custom} args, see below + {cfg/gz} args = same as {custom} args, see below + {cfg/mpiio} args = same as {custom} args, see below + {custom}, {custom/gz}, {custom/mpiio} args = see below + {dcd} args = none + {h5md} args = discussed on "dump h5md"_dump_h5md.html doc page + {image} args = discussed on "dump image"_dump_image.html doc page + {local} args = see below + {molfile} args = discussed on "dump molfile"_dump_molfile.html doc page + {movie} args = discussed on "dump image"_dump_image.html doc page + {netcdf} args = discussed on "dump netcdf"_dump_netcdf.html doc page + {netcdf/mpiio} args = discussed on "dump netcdf"_dump_netcdf.html doc page + {vtk} args = same as {custom} args, see below, also "dump vtk"_dump_vtk.html doc page + {xtc} args = none + {xyz} args = none + {xyz/gz} args = none + {xyz/mpiio} args = none :pre + +{custom} or {custom/gz} or {custom/mpiio} or {netcdf} or {netcdf/mpiio} args = list of atom attributes :l + possible attributes = id, mol, proc, procp1, type, element, mass, + x, y, z, xs, ys, zs, xu, yu, zu, + xsu, ysu, zsu, ix, iy, iz, + vx, vy, vz, fx, fy, fz, + q, mux, muy, muz, mu, + radius, diameter, omegax, omegay, omegaz, + angmomx, angmomy, angmomz, tqx, tqy, tqz, + c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :pre + + id = atom ID + mol = molecule ID + proc = ID of processor that owns atom + procp1 = ID+1 of processor that owns atom + type = atom type + element = name of atom element, as defined by "dump_modify"_dump_modify.html command + mass = atom mass + x,y,z = unscaled atom coordinates + xs,ys,zs = scaled atom coordinates + xu,yu,zu = unwrapped atom coordinates + xsu,ysu,zsu = scaled unwrapped atom coordinates + ix,iy,iz = box image that the atom is in + vx,vy,vz = atom velocities + fx,fy,fz = forces on atoms + q = atom charge + mux,muy,muz = orientation of dipole moment of atom + mu = magnitude of dipole moment of atom + radius,diameter = radius,diameter of spherical particle + omegax,omegay,omegaz = angular velocity of spherical particle + angmomx,angmomy,angmomz = angular momentum of aspherical particle + tqx,tqy,tqz = torque on finite-size particles + c_ID = per-atom vector calculated by a compute with ID + c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below) + f_ID = per-atom vector calculated by a fix with ID + f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below) + v_name = per-atom vector calculated by an atom-style variable with name + d_name = per-atom floating point vector with name, managed by fix property/atom + i_name = per-atom integer vector with name, managed by fix property/atom :pre + +{local} args = list of local attributes :l + possible attributes = index, c_ID, c_ID\[I\], f_ID, f_ID\[I\] + index = enumeration of local values + c_ID = local vector calculated by a compute with ID + c_ID\[I\] = Ith column of local array calculated by a compute with ID, I can include wildcard (see below) + f_ID = local vector calculated by a fix with ID + f_ID\[I\] = Ith column of local array calculated by a fix with ID, I can include wildcard (see below) :pre + +:ule + +[Examples:] + +dump myDump all atom 100 dump.atom +dump myDump all atom/mpiio 100 dump.atom.mpiio +dump myDump all atom/gz 100 dump.atom.gz +dump 2 subgroup atom 50 dump.run.bin +dump 2 subgroup atom 50 dump.run.mpiio.bin +dump 4a all custom 100 dump.myforce.* id type x y vx fx +dump 4b flow custom 100 dump.%.myforce id type c_myF\[3\] v_ke +dump 4b flow custom 100 dump.%.myforce id type c_myF\[*\] v_ke +dump 2 inner cfg 10 dump.snap.*.cfg mass type xs ys zs vx vy vz +dump snap all cfg 100 dump.config.*.cfg mass type xs ys zs id type c_Stress\[2\] +dump 1 all xtc 1000 file.xtc :pre + +[Description:] + +Dump a snapshot of atom quantities to one or more files every N +timesteps in one of several styles. The {image} and {movie} styles are +the exception: the {image} style renders a JPG, PNG, or PPM image file +of the atom configuration every N timesteps while the {movie} style +combines and compresses them into a movie file; both are discussed in +detail on the "dump image"_dump_image.html doc page. The timesteps on +which dump output is written can also be controlled by a variable. +See the "dump_modify every"_dump_modify.html command. + +Only information for atoms in the specified group is dumped. The +"dump_modify thresh and region and refresh"_dump_modify.html commands +can also alter what atoms are included. Not all styles support all +these options; see details on the "dump_modify"_dump_modify.html doc +page. + +As described below, the filename determines the kind of output (text +or binary or gzipped, one big file or one per timestep, one big file +or multiple smaller files). + +NOTE: Because periodic boundary conditions are enforced only on +timesteps when neighbor lists are rebuilt, the coordinates of an atom +written to a dump file may be slightly outside the simulation box. +Re-neighbor timesteps will not typically coincide with the timesteps +dump snapshots are written. See the "dump_modify +pbc"_dump_modify.html command if you with to force coordinates to be +strictly inside the simulation box. + +NOTE: Unless the "dump_modify sort"_dump_modify.html option is +invoked, the lines of atom information written to dump files +(typically one line per atom) will be in an indeterminate order for +each snapshot. This is even true when running on a single processor, +if the "atom_modify sort"_atom_modify.html option is on, which it is +by default. In this case atoms are re-ordered periodically during a +simulation, due to spatial sorting. It is also true when running in +parallel, because data for a single snapshot is collected from +multiple processors, each of which owns a subset of the atoms. + +For the {atom}, {custom}, {cfg}, and {local} styles, sorting is off by +default. For the {dcd}, {xtc}, {xyz}, and {molfile} styles, sorting by +atom ID is on by default. See the "dump_modify"_dump_modify.html doc +page for details. + +The {atom/gz}, {cfg/gz}, {custom/gz}, and {xyz/gz} styles are identical +in command syntax to the corresponding styles without "gz", however, +they generate compressed files using the zlib library. Thus the filename +suffix ".gz" is mandatory. This is an alternative approach to writing +compressed files via a pipe, as done by the regular dump styles, which +may be required on clusters where the interface to the high-speed network +disallows using the fork() library call (which is needed for a pipe). +For the remainder of this doc page, you should thus consider the {atom} +and {atom/gz} styles (etc) to be inter-changeable, with the exception +of the required filename suffix. + +As explained below, the {atom/mpiio}, {cfg/mpiio}, {custom/mpiio}, and +{xyz/mpiio} 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. For the remainder of this doc page, +you should thus consider the {atom} and {atom/mpiio} styles (etc) to +be inter-changeable. The one exception is how the filename is +specified for the MPI-IO styles, as explained below. + +The precision of values output to text-based dump files can be +controlled by the "dump_modify format"_dump_modify.html command and +its options. + +:line + +The {style} keyword determines what atom quantities are written to the +file and in what format. Settings made via the +"dump_modify"_dump_modify.html command can also alter the format of +individual values and the file itself. + +The {atom}, {local}, and {custom} styles create files in a simple text +format that is self-explanatory when viewing a dump file. Many of the +LAMMPS "post-processing tools"_Section_tools.html, including +"Pizza.py"_http://www.sandia.gov/~sjplimp/pizza.html, work with this +format, as does the "rerun"_rerun.html command. + +For post-processing purposes the {atom}, {local}, and {custom} text +files are self-describing in the following sense. + +The dimensions of the simulation box are included in each snapshot. +For an orthogonal simulation box this information is is formatted as: + +ITEM: BOX BOUNDS xx yy zz +xlo xhi +ylo yhi +zlo zhi :pre + +where xlo,xhi are the maximum extents of the simulation box in the +x-dimension, and similarly for y and z. The "xx yy zz" represent 6 +characters that encode the style of boundary for each of the 6 +simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each of +the 6 characters is either p = periodic, f = fixed, s = shrink wrap, +or m = shrink wrapped with a minimum value. See the +"boundary"_boundary.html command for details. + +For triclinic simulation boxes (non-orthogonal), 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 xx yy zz +xlo_bound xhi_bound xy +ylo_bound yhi_bound xz +zlo_bound zhi_bound yz :pre + +The presence of the text "xy xz yz" in the ITEM line indicates that +the 3 tilt factors will be included on each of the 3 following lines. +This bounding box is convenient for many visualization programs. The +meaning of the 6 character flags for "xx yy zz" is the same as above. + +Note that the first two numbers on each line are now xlo_bound instead +of xlo, etc, since they represent a bounding box. See "this +section"_Section_howto.html#howto_12 of the doc pages for a geometric +description of triclinic boxes, as defined by LAMMPS, simple formulas +for how the 6 bounding box extents (xlo_bound,xhi_bound,etc) are +calculated from the triclinic parameters, and how to transform those +parameters to and from other commonly used triclinic representations. + +The "ITEM: ATOMS" line in each snapshot lists column descriptors for +the per-atom lines that follow. For example, the descriptors would be +"id type xs ys zs" for the default {atom} style, and would be the atom +attributes you specify in the dump command for the {custom} style. + +For style {atom}, atom coordinates are written to the file, along with +the atom ID and atom type. By default, atom coords are written in a +scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom +is at a location 1/4 of the distance from xlo to xhi of the box +boundaries. The format can be changed to unscaled coords via the +"dump_modify"_dump_modify.html settings. Image flags can also be +added for each atom via dump_modify. + +Style {custom} allows you to specify a list of atom attributes to be +written to the dump file for each atom. Possible attributes are +listed above and will appear in the order specified. You cannot +specify a quantity that is not defined for a particular simulation - +such as {q} for atom style {bond}, since that atom style doesn't +assign charges. Dumps occur at the very end of a timestep, so atom +attributes will include effects due to fixes that are applied during +the timestep. An explanation of the possible dump custom attributes +is given below. + +For style {local}, local output generated by "computes"_compute.html +and "fixes"_fix.html is used to generate lines of output that is +written to the dump file. This local data is typically calculated by +each processor based on the atoms it owns, but there may be zero or +more entities per atom, e.g. a list of bond distances. An explanation +of the possible dump local attributes is given below. Note that by +using input from the "compute +property/local"_compute_property_local.html command with dump local, +it is possible to generate information on bonds, angles, etc that can +be cut and pasted directly into a data file read by the +"read_data"_read_data.html command. + +Style {cfg} has the same command syntax as style {custom} and writes +extended CFG format files, as used by the +"AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A visualization +package. Since the extended CFG format uses a single snapshot of the +system per file, a wildcard "*" must be included in the filename, as +discussed below. The list of atom attributes for style {cfg} must +begin with either "mass type xs ys zs" or "mass type xsu ysu zsu" +since these quantities are needed to write the CFG files in the +appropriate format (though the "mass" and "type" fields do not appear +explicitly in the file). Any remaining attributes will be stored as +"auxiliary properties" in the CFG files. Note that you will typically +want to use the "dump_modify element"_dump_modify.html command with +CFG-formatted files, to associate element names with atom types, so +that AtomEye can render atoms appropriately. When unwrapped +coordinates {xsu}, {ysu}, and {zsu} are requested, the nominal AtomEye +periodic cell dimensions are expanded by a large factor UNWRAPEXPAND = +10.0, which ensures atoms that are displayed correctly for up to +UNWRAPEXPAND/2 periodic boundary crossings in any direction. Beyond +this, AtomEye will rewrap the unwrapped coordinates. The expansion +causes the atoms to be drawn farther away from the viewer, but it is +easy to zoom the atoms closer, and the interatomic distances are +unaffected. + +The {dcd} style writes DCD files, a standard atomic trajectory format +used by the CHARMM, NAMD, and XPlor molecular dynamics packages. DCD +files are binary and thus may not be portable to different machines. +The number of atoms per snapshot cannot change with the {dcd} style. +The {unwrap} option of the "dump_modify"_dump_modify.html command +allows DCD coordinates to be written "unwrapped" by the image flags +for each atom. Unwrapped means that if the atom has passed through +a periodic boundary one or more times, the value is printed for what +the coordinate would be if it had not been wrapped back into the +periodic box. Note that these coordinates may thus be far outside +the box size stored with the snapshot. + +The {xtc} style writes XTC files, a compressed trajectory format used +by the GROMACS molecular dynamics package, and described +"here"_http://manual.gromacs.org/current/online/xtc.html. +The precision used in XTC files can be adjusted via the +"dump_modify"_dump_modify.html command. The default value of 1000 +means that coordinates are stored to 1/1000 nanometer accuracy. XTC +files are portable binary files written in the NFS XDR data format, +so that any machine which supports XDR should be able to read them. +The number of atoms per snapshot cannot change with the {xtc} style. +The {unwrap} option of the "dump_modify"_dump_modify.html command allows +XTC coordinates to be written "unwrapped" by the image flags for each +atom. Unwrapped means that if the atom has passed thru a periodic +boundary one or more times, the value is printed for what the +coordinate would be if it had not been wrapped back into the periodic +box. Note that these coordinates may thus be far outside the box size +stored with the snapshot. + +The {xyz} style writes XYZ files, which is a simple text-based +coordinate format that many codes can read. Specifically it has +a line with the number of atoms, then a comment line that is +usually ignored followed by one line per atom with the atom type +and the x-, y-, and z-coordinate of that atom. You can use the +"dump_modify element"_dump_modify.html option to change the output +from using the (numerical) atom type to an element name (or some +other label). This will help many visualization programs to guess +bonds and colors. + +Note that {atom}, {custom}, {dcd}, {xtc}, and {xyz} style dump files +can be read directly by "VMD"_http://www.ks.uiuc.edu/Research/vmd, a +popular molecular viewing program. + +:line + +Dumps are performed on timesteps that are a multiple of N (including +timestep 0) and on the last timestep of a minimization if the +minimization converges. Note that this means a dump will not be +performed on the initial timestep after the dump command is invoked, +if the current timestep is not a multiple of N. This behavior can be +changed via the "dump_modify first"_dump_modify.html command, which +can also be useful if the dump command is invoked after a minimization +ended on an arbitrary timestep. N can be changed between runs by +using the "dump_modify every"_dump_modify.html command (not allowed +for {dcd} style). The "dump_modify every"_dump_modify.html command +also allows a variable to be used to determine the sequence of +timesteps on which dump files are written. In this mode a dump on the +first timestep of a run will also not be written unless the +"dump_modify first"_dump_modify.html command is used. + +The specified filename determines how the dump file(s) is written. +The default is to write one large text file, which is opened when the +dump command is invoked and closed when an "undump"_undump.html +command is used or when LAMMPS exits. For the {dcd} and {xtc} styles, +this is a single large binary file. + +Dump filenames can contain two wildcard characters. If a "*" +character appears in the filename, then one file per snapshot is +written and the "*" character is replaced with the timestep value. +For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000, +tmp.dump.20000, etc. This option is not available for the {dcd} and +{xtc} styles. Note that the "dump_modify pad"_dump_modify.html +command can be used to insure all timestep numbers are the same length +(e.g. 00010), which can make it easier to read a series of dump files +in order with some post-processing tools. + +If a "%" character appears in the filename, then each of P processors +writes a portion of the dump file, and the "%" character is replaced +with the processor ID from 0 to P-1. For example, tmp.dump.% becomes +tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller +files and can be a fast mode of output on parallel machines that +support parallel I/O for output. This option is not available for the +{dcd}, {xtc}, and {xyz} styles. + +By default, P = the number of processors meaning one file per +processor, but P can be set to a smaller value via the {nfile} or +{fileper} keywords of the "dump_modify"_dump_modify.html command. +These options can be the most efficient way of writing out dump files +when running on large numbers of processors. + +Note that using the "*" and "%" characters together can produce a +large number of small dump files! + +For the {atom/mpiio}, {cfg/mpiio}, {custom/mpiio}, and {xyz/mpiio} +styles, a single dump file is written in parallel via the MPI-IO +library, which is part of the MPI standard for versions 2.0 and above. +Using MPI-IO requires two steps. First, build LAMMPS with its MPIIO +package installed, e.g. + +make yes-mpiio # installs the MPIIO package +make mpi # build LAMMPS for your platform :pre + +Second, use a dump filename which contains ".mpiio". Note that it +does not have to end in ".mpiio", just contain those characters. +Unlike MPI-IO restart files, which must be both written and read using +MPI-IO, the dump files produced by these MPI-IO styles are identical +in format to the files produced by their non-MPI-IO style +counterparts. This means you can write a dump file using MPI-IO and +use the "read_dump"_read_dump.html command or perform other +post-processing, just as if the dump file was not written using +MPI-IO. + +Note that MPI-IO dump files are one large file which all processors +write to. You thus cannot use the "%" wildcard character described +above in the filename since that specifies generation of multiple +files. You can use the ".bin" suffix described below in an MPI-IO +dump file; again this file will be written in parallel and have the +same binary format as if it were written without MPI-IO. + +If the filename ends with ".bin", the dump file (or files, if "*" or +"%" is also used) is written in binary format. A binary dump file +will be about the same size as a text version, but will typically +write out much faster. Of course, when post-processing, you will need +to convert it back to text format (see the "binary2txt +tool"_Section_tools.html#binary) or write your own code to read the +binary file. The format of the binary file can be understood by +looking at the tools/binary2txt.cpp file. This option is only +available for the {atom} and {custom} styles. + +If the filename ends with ".gz", the dump file (or files, if "*" or "%" +is also used) is written in gzipped format. A gzipped dump file will +be about 3x smaller than the text version, but will also take longer +to write. This option is not available for the {dcd} and {xtc} +styles. + +:line + +Note that in the discussion which follows, for styles which can +reference values from a compute or fix, like the {custom}, {cfg}, or +{local} styles, the bracketed index I can be specified using a +wildcard asterisk with the index to effectively specify multiple +values. This takes the form "*" or "*n" or "n*" or "m*n". If N = the +size of the vector (for {mode} = scalar) or the number of columns in +the array (for {mode} = vector), then an asterisk with no numeric +values means all indices from 1 to N. A leading asterisk means all +indices from 1 to n (inclusive). A trailing asterisk means all +indices from n to N (inclusive). A middle asterisk means all indices +from m to n (inclusive). + +Using a wildcard is the same as if the individual columns of the array +had been listed one by one. E.g. these 2 dump commands are +equivalent, since the "compute stress/atom"_compute_stress_atom.html +command creates a per-atom array with 6 columns: + +compute myPress all stress/atom NULL +dump 2 all custom 100 tmp.dump id myPress\[*\] +dump 2 all custom 100 tmp.dump id myPress\[1\] myPress\[2\] myPress\[3\] & + myPress\[4\] myPress\[5\] myPress\[6\] :pre + +:line + +This section explains the local attributes that can be specified as +part of the {local} style. + +The {index} attribute can be used to generate an index number from 1 +to N for each line written into the dump file, where N is the total +number of local datums from all processors, or lines of output that +will appear in the snapshot. Note that because data from different +processors depend on what atoms they currently own, and atoms migrate +between processor, there is no guarantee that the same index will be +used for the same info (e.g. a particular bond) in successive +snapshots. + +The {c_ID} and {c_ID\[I\]} attributes allow local vectors or arrays +calculated by a "compute"_compute.html to be output. The ID in the +attribute should be replaced by the actual ID of the compute that has +been defined previously in the input script. See the +"compute"_compute.html command for details. There are computes for +calculating local information such as indices, types, and energies for +bonds and angles. + +Note that computes which calculate global or per-atom quantities, as +opposed to local quantities, cannot be output in a dump local command. +Instead, global quantities can be output by the "thermo_style +custom"_thermo_style.html command, and per-atom quantities can be +output by the dump custom command. + +If {c_ID} is used as a attribute, then the local vector calculated by +the compute is printed. If {c_ID\[I\]} is used, then I must be in the +range from 1-M, which will print the Ith column of the local array +with M columns calculated by the compute. See the discussion above +for how I can be specified with a wildcard asterisk to effectively +specify multiple values. + +The {f_ID} and {f_ID\[I\]} attributes allow local vectors or arrays +calculated by a "fix"_fix.html to be output. The ID in the attribute +should be replaced by the actual ID of the fix that has been defined +previously in the input script. + +If {f_ID} is used as a attribute, then the local vector calculated by +the fix is printed. If {f_ID\[I\]} is used, then I must be in the +range from 1-M, which will print the Ith column of the local with M +columns calculated by the fix. See the discussion above for how I can +be specified with a wildcard asterisk to effectively specify multiple +values. + +Here is an example of how to dump bond info for a system, including +the distance and energy of each bond: + +compute 1 all property/local batom1 batom2 btype +compute 2 all bond/local dist eng +dump 1 all local 1000 tmp.dump index c_1\[1\] c_1\[2\] c_1\[3\] c_2\[1\] c_2\[2\] :pre + +:line + +This section explains the atom attributes that can be specified as +part of the {custom} and {cfg} styles. + +The {id}, {mol}, {proc}, {procp1}, {type}, {element}, {mass}, {vx}, +{vy}, {vz}, {fx}, {fy}, {fz}, {q} attributes are self-explanatory. + +{Id} is the atom ID. {Mol} is the molecule ID, included in the data +file for molecular systems. {Proc} is the ID of the processor (0 to +Nprocs-1) that currently owns the atom. {Procp1} is the proc ID+1, +which can be convenient in place of a {type} attribute (1 to Ntypes) +for coloring atoms in a visualization program. {Type} is the atom +type (1 to Ntypes). {Element} is typically the chemical name of an +element, which you must assign to each type via the "dump_modify +element"_dump_modify.html command. More generally, it can be any +string you wish to associated with an atom type. {Mass} is the atom +mass. {Vx}, {vy}, {vz}, {fx}, {fy}, {fz}, and {q} are components of +atom velocity and force and atomic charge. + +There are several options for outputting atom coordinates. The {x}, +{y}, {z} attributes write atom coordinates "unscaled", in the +appropriate distance "units"_units.html (Angstroms, sigma, etc). Use +{xs}, {ys}, {zs} if you want the coordinates "scaled" to the box size, +so that each value is 0.0 to 1.0. If the simulation box is triclinic +(tilted), then all atom coords will still be between 0.0 and 1.0. +I.e. actual unscaled (x,y,z) = xs*A + ys*B + zs*C, where (A,B,C) are +the non-orthogonal vectors of the simulation box edges, as discussed +in "Section 6.12"_Section_howto.html#howto_12. + +Use {xu}, {yu}, {zu} if you want the coordinates "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 using {xu}, {yu}, {zu} means +that the coordinate values may be far outside the box bounds printed +with the snapshot. Using {xsu}, {ysu}, {zsu} is similar to using +{xu}, {yu}, {zu}, except that the unwrapped coordinates are scaled by +the box size. Atoms that have passed through a periodic boundary will +have the corresponding coordinate increased or decreased by 1.0. + +The image flags can be printed directly using the {ix}, {iy}, {iz} +attributes. For periodic dimensions, they specify which image of the +simulation box the atom is considered to be in. An image of 0 means +it is inside the box as defined. A value of 2 means add 2 box lengths +to get the true value. A value of -1 means subtract 1 box length to +get the true value. LAMMPS updates these flags as atoms cross +periodic boundaries during the simulation. + +The {mux}, {muy}, {muz} attributes are specific to dipolar systems +defined with an atom style of {dipole}. They give the orientation of +the atom's point dipole moment. The {mu} attribute gives the +magnitude of the atom's dipole moment. + +The {radius} and {diameter} attributes are specific to spherical +particles that have a finite size, such as those defined with an atom +style of {sphere}. + +The {omegax}, {omegay}, and {omegaz} attributes are specific to +finite-size spherical particles that have an angular velocity. Only +certain atom styles, such as {sphere} define this quantity. + +The {angmomx}, {angmomy}, and {angmomz} attributes are specific to +finite-size aspherical particles that have an angular momentum. Only +the {ellipsoid} atom style defines this quantity. + +The {tqx}, {tqy}, {tqz} attributes are for finite-size particles that +can sustain a rotational torque due to interactions with other +particles. + +The {c_ID} and {c_ID\[I\]} attributes allow per-atom vectors or arrays +calculated by a "compute"_compute.html to be output. The ID in the +attribute should be replaced by the actual ID of the compute that has +been defined previously in the input script. See the +"compute"_compute.html command for details. There are computes for +calculating the per-atom energy, stress, centro-symmetry parameter, +and coordination number of individual atoms. + +Note that computes which calculate global or local quantities, as +opposed to per-atom quantities, cannot be output in a dump custom +command. Instead, global quantities can be output by the +"thermo_style custom"_thermo_style.html command, and local quantities +can be output by the dump local command. + +If {c_ID} is used as a attribute, then the per-atom vector calculated +by the compute is printed. If {c_ID\[I\]} is used, then I must be in +the range from 1-M, which will print the Ith column of the per-atom +array with M columns calculated by the compute. See the discussion +above for how I can be specified with a wildcard asterisk to +effectively specify multiple values. + +The {f_ID} and {f_ID\[I\]} attributes allow vector or array per-atom +quantities calculated by a "fix"_fix.html to be output. The ID in the +attribute should be replaced by the actual ID of the fix that has been +defined previously in the input script. The "fix +ave/atom"_fix_ave_atom.html command is one that calculates per-atom +quantities. Since it can time-average per-atom quantities produced by +any "compute"_compute.html, "fix"_fix.html, or atom-style +"variable"_variable.html, this allows those time-averaged results to +be written to a dump file. + +If {f_ID} is used as a attribute, then the per-atom vector calculated +by the fix is printed. If {f_ID\[I\]} is used, then I must be in the +range from 1-M, which will print the Ith column of the per-atom array +with M columns calculated by the fix. See the discussion above for +how I can be specified with a wildcard asterisk to effectively specify +multiple values. + +The {v_name} attribute allows per-atom vectors calculated by a +"variable"_variable.html to be output. The name in the attribute +should be replaced by the actual name of the variable that has been +defined previously in the input script. Only an atom-style variable +can be referenced, since it is the only style that generates per-atom +values. Variables of style {atom} can reference individual atom +attributes, per-atom atom attributes, thermodynamic keywords, or +invoke other computes, fixes, or variables when they are evaluated, so +this is a very general means of creating quantities to output to a +dump file. + +The {d_name} and {i_name} attributes allow to output custom per atom +floating point or integer properties that are managed by +"fix property/atom"_fix_property_atom.html. + +See "Section 10"_Section_modify.html of the manual for information +on how to add new compute and fix styles to LAMMPS to calculate +per-atom quantities which could then be output into dump files. + +:line + +[Restrictions:] + +To write gzipped dump files, you must either compile LAMMPS with the +-DLAMMPS_GZIP option or use the styles from the COMPRESS package +- see the "Making LAMMPS"_Section_start.html#start_2 section of +the documentation. + +The {atom/gz}, {cfg/gz}, {custom/gz}, and {xyz/gz} styles are part +of the COMPRESS package. They are only enabled if LAMMPS was built +with that package. See the "Making +LAMMPS"_Section_start.html#start_3 section for more info. + +The {atom/mpiio}, {cfg/mpiio}, {custom/mpiio}, and {xyz/mpiio} styles +are part of the MPIIO package. They are only enabled if LAMMPS was +built with that package. See the "Making +LAMMPS"_Section_start.html#start_3 section for more info. + +The {xtc} style is part of the MISC 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. + +[Related commands:] + +"dump h5md"_dump_h5md.html, "dump image"_dump_image.html, +"dump molfile"_dump_molfile.html, "dump_modify"_dump_modify.html, +"undump"_undump.html + +[Default:] + +The defaults for the {image} and {movie} styles are listed on the +"dump image"_dump_image.html doc page. diff --git a/doc/dump_modify.txt b/doc/dump_modify.txt new file mode 100644 index 0000000000..6de6de545e --- /dev/null +++ b/doc/dump_modify.txt @@ -0,0 +1,1090 @@ +"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 {at} or {buffer} or {delay} 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} + {at} arg = N + N = index of frame written upon first dump + {buffer} arg = {yes} or {no} + {delay} arg = Dstep + Dstep = delay output until this timestep + {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" + {refresh} arg = c_ID = compute ID that supports a refresh operation + {scale} arg = {yes} or {no} + {sfactor} arg = coordinate scaling factor (> 0.0) + {thermo} arg = {yes} or {no} + {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. + +:line + +The {at} keyword only applies to the {netcdf} dump style. It can only +be used if the {append yes} keyword is also used. The {N} argument is +the index of which frame to append to. A negative value can be +specified for {N}, which means a frame counted from the end of the +file. The {at} keyword can only be used if the dump_modify command is +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 {delay} keyword applies to all dump styles. No snapshots will be +output until the specified {Dstep} timestep or later. Specifying +{Dstep} < 0 is the same as turning off the delay setting. This is a +way to turn off unwanted output early in a simulation, for example, +during an equilibration phase. + +:line + +The {element} keyword applies only to 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 {refresh} keyword only applies to the dump {custom}, {cfg}, +{image}, and {movie} styles. It allows an "incremental" dump file to +be written, by refreshing a compute that is used as a threshold for +determining which atoms are included in a dump snapshot. The +specified {c_ID} gives the ID of the compute. It is prefixed by "c_" +to indicate a compute, which is the only current option. At some +point, other options may be added, e.g. fixes or variables. + +NOTE: This keyword can only be specified once for a dump. Refreshes +of multiple computes cannot yet be performed. + +The definition and motivation of an incremental dump file is as +follows. Instead of outputting all atoms at each snapshot (with some +associated values), you may only wish to output the subset of atoms +with a value that has changed in some way compared to the value the +last time that atom was output. In some scenarios this can result in +a dramatically smaller dump file. If desired, by post-processing the +sequence of snapshots, the values for all atoms at all timesteps can +be inferred. + +A concrete example is a simulation of atom diffusion in a solid, +represented as atoms on a lattice. Diffusive hops are rare. Imagine +that when a hop occurs an atom moves more than a distance {Dhop}. For +any snapshot we only want to output atoms that have hopped since the +last snapshot. This can be accomplished with something the following +commands: + +variable Dhop equal 0.6 +variable check atom "c_dsp[4] > v_Dhop" +compute dsp all displace/atom refresh check +dump 1 all custom 20 tmp.dump id type x y z +dump_modify 1 append yes thresh c_dsp[4] > ${Dhop} refresh c_dsp :pre + +The "compute displace/atom"_compute_displace_atom.html command +calculates the displacement of each atom from its reference position. +The "4" index is the scalar displacement; 1,2,3 are the xyz components +of the displacement. The "dump_modify thresh"_dump_modify.html +command will cause only atoms that have displaced more than 0.6 +Angstroms to be output on a given snapshot (assuming metal units). +However, note that when an atom is output, we also need to update the +reference position for that atom to its new coordinates. So that it +will not be output in every snapshot thereafter. That reference +position is stored by "compute +displace/atom"_compute_displace_atom.html. So the dump_modify +{refresh} option triggers a call to compute displace/atom at the end +of every dump to perform that update. The {refresh check} option +shown as part of the "compute +displace/atom"_compute_displace_atom.html command enables the compute +to respond to the call from the dump command, and update the +appropriate reference positions. This is done be defining an +"atom-style variable"_variable.html, {check} in this example, which +calculates a Boolean value (0 or 1) for each atom, based on the same +criterion used by dump_modify thresh. + +See the "compute displace/atom"_compute_displace_atom.html command for +more details, including an example of how to produce output that +includes an initial snapshot with the reference position of all atoms. + +Note that only computes with a {refresh} option will work with +dump_modify refresh. See individual compute doc pages for details. +Currently, only compute displace/atom supports this option. Others +may be added at some point. If you use a compute that doesn't support +refresh operations, LAMMPS will not complain; dump_modify refresh will +simply do nothing. + +: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 simulation 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 {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 {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 {thermo} keyword only applies the dump {netcdf} style. It +triggers writing of "thermo"_thermo.html information to the dump file +alongside per-atom data. The values included in the dump file are +identical to the values specified by "thermo_style"_thermo_style.html. + +: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 comparison 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 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/reset_ids.txt b/doc/reset_ids.txt new file mode 100644 index 0000000000..8655a9d54f --- /dev/null +++ b/doc/reset_ids.txt @@ -0,0 +1,56 @@ +"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 + +reset_ids command :h3 + +[Syntax:] + +reset_ids :pre + +[Examples:] + +reset_ids :pre + +[Description:] + +Reset atom IDs for the system, including all the global IDs stored +for bond, angle, dihedral, improper topology data. This will +create a set of IDs that are numbered contiguously from 1 to N +for a N atoms system. + +This can be useful to do after perfoming a "delete_atoms" command for +a molecular system. The delete_atoms compress yes option will not +perform this operation due to the existence of bond topology. It can +also be useful to do after any simulation which has lost atoms, +e.g. due to atoms moving outside a simulation box with fixed +boundaries (see the "boundary command"), or due to evaporation (see +the "fix evaporate" command). + +Note that the resetting of IDs is not really a compression, where gaps +in atom IDs are removed by decrementing atom IDs that are larger. +Instead the IDs for all atoms are erased, and new IDs are assigned so +that the atoms owned by an individual processor have consecutive IDs, +as the "create_atoms"_create_atoms.html command explains. + +NOTE: If this command is used before a "pair style"_pair_style.html is +defined, an error about bond topology atom IDs not being found may +result. This is because the cutoff distance for ghost atom +communication was not sufficient to find atoms in bonds, angles, etc +that are owned by other processors. The "comm_modify +cutoff"_comm_modify.html command can be used to correct this issue. +Or you can define a pair style before using this command. If you do +the former, you should unset the comm_modify cutoff after using +reset_ids so that subsequent communication is not inefficient. + +[Restrictions:] none + +[Related commands:] + +"delete_atoms"_delete_atoms.html + +[Default:] none diff --git a/src/atom.h b/src/atom.h index 72c7aedc0d..6d8db51d74 100644 --- a/src/atom.h +++ b/src/atom.h @@ -187,7 +187,8 @@ class Atom : protected Pointers { int nextra_store; int map_style; // style of atom map: 0=none, 1=array, 2=hash - int map_user; // user selected style = same 0,1,2 + int map_user; // user requested map style: + // 0 = no request, 1=array, 2=hash, 3=yes tagint map_tag_max; // max atom ID that map() is setup for // spatial sorting of atoms diff --git a/src/delete_atoms.cpp b/src/delete_atoms.cpp index 4c7829662c..f5324f9558 100644 --- a/src/delete_atoms.cpp +++ b/src/delete_atoms.cpp @@ -22,13 +22,13 @@ #include "force.h" #include "group.h" #include "region.h" +#include "modify.h" #include "neighbor.h" #include "neigh_list.h" #include "neigh_request.h" #include "random_mars.h" #include "memory.h" #include "error.h" -#include "modify.h" #include <map> @@ -68,7 +68,8 @@ void DeleteAtoms::command(int narg, char **arg) if (allflag) { int igroup = group->find("all"); - if ((igroup >= 0) && modify->check_rigid_group_overlap(group->bitmask[igroup])) + if ((igroup >= 0) && + modify->check_rigid_group_overlap(group->bitmask[igroup])) error->warning(FLERR,"Attempting to delete atoms in rigid bodies"); } else { if (modify->check_rigid_list_overlap(dlist)) @@ -105,7 +106,7 @@ void DeleteAtoms::command(int narg, char **arg) memory->destroy(dlist); } - // if non-molecular system and compress flag set, + // if non-molecular system and compress flag set: // reset atom tags to be contiguous // set all atom IDs to 0, call tag_extend() diff --git a/src/dump.cpp b/src/dump.cpp index ddd958c25c..cfa3e873f4 100644 --- a/src/dump.cpp +++ b/src/dump.cpp @@ -85,6 +85,7 @@ Dump::Dump(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) buffer_flag = 0; padflag = 0; pbcflag = 0; + delay_flag = 0; maxbuf = maxids = maxsort = maxproc = 0; buf = bufsort = NULL; @@ -304,6 +305,10 @@ void Dump::write() imageint *imagehold; double **xhold,**vhold; + // if timestep < delaystep, just return + + if (delay_flag && update->ntimestep < delaystep) return; + // if file per timestep, open new file if (multifile) openfile(); @@ -876,6 +881,13 @@ void Dump::modify_params(int narg, char **arg) error->all(FLERR,"Dump_modify buffer yes not allowed for this style"); iarg += 2; + } else if (strcmp(arg[iarg],"delay") == 0) { + if (iarg+2 > narg) error->all(FLERR,"Illegal dump_modify command"); + delaystep = force->bnumeric(FLERR,arg[iarg+1]); + if (delaystep >= 0) delay_flag = 1; + else delay_flag = 0; + iarg += 2; + } else if (strcmp(arg[iarg],"every") == 0) { if (iarg+2 > narg) error->all(FLERR,"Illegal dump_modify command"); int idump; diff --git a/src/dump.h b/src/dump.h index a5582ce5a5..8b4071b9f7 100644 --- a/src/dump.h +++ b/src/dump.h @@ -77,6 +77,8 @@ class Dump : protected Pointers { int sortcol; // 0 to sort on ID, 1-N on columns int sortcolm1; // sortcol - 1 int sortorder; // ASCEND or DESCEND + int delay_flag; // 1 if delay output until delaystep + bigint delaystep; char boundstr[9]; // encoding of boundary flags diff --git a/src/read_dump.cpp b/src/read_dump.cpp index fcb0e4d2fe..7f2488fbb2 100644 --- a/src/read_dump.cpp +++ b/src/read_dump.cpp @@ -577,13 +577,14 @@ int ReadDump::fields_and_keywords(int narg, char **arg) fieldlabel = new char*[narg+2]; // add id and type fields as needed - // scan ahead to see if "add yes" keyword/value is used + // scan ahead to see if "add yes/keep" keyword/value is used // requires extra "type" field from from dump file int iarg; for (iarg = 0; iarg < narg; iarg++) if (strcmp(arg[iarg],"add") == 0) - if (iarg < narg-1 && strcmp(arg[iarg+1],"yes") == 0) break; + if (iarg < narg-1 && (strcmp(arg[iarg+1],"yes") == 0 || + strcmp(arg[iarg+1],"keep") == 0)) break; nfield = 0; fieldtype[nfield++] = ID; diff --git a/src/reset_ids.cpp b/src/reset_ids.cpp new file mode 100644 index 0000000000..8a33cd535b --- /dev/null +++ b/src/reset_ids.cpp @@ -0,0 +1,246 @@ +/* ---------------------------------------------------------------------- + LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator + http://lammps.sandia.gov, Sandia National Laboratories + Steve Plimpton, sjplimp@sandia.gov + + Copyright (2003) Sandia Corporation. Under the terms of Contract + DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains + certain rights in this software. This software is distributed under + the GNU General Public License. + + See the README file in the top-level LAMMPS directory. +------------------------------------------------------------------------- */ + +#include "reset_ids.h" +#include "atom.h" +#include "atom_vec.h" +#include "domain.h" +#include "comm.h" +#include "memory.h" +#include "error.h" + +using namespace LAMMPS_NS; + +/* ---------------------------------------------------------------------- */ + +ResetIDs::ResetIDs(LAMMPS *lmp) : Pointers(lmp) {} + +/* ---------------------------------------------------------------------- */ + +void ResetIDs::command(int narg, char **arg) +{ + if (domain->box_exist == 0) + error->all(FLERR,"Reset_ids command before simulation box is defined"); + if (narg != 0) error->all(FLERR,"Illegal reset_ids command"); + if (atom->tag_enable == 0) + error->all(FLERR,"Cannot use reset_ids unless atoms have IDs"); + + // NOTE: check if any fixes exist which store atom IDs? + // if so, this operation will mess up the fix + + if (comm->me == 0) { + if (screen) fprintf(screen,"Resetting atom IDs ...\n"); + if (logfile) fprintf(logfile,"Resetting atom IDs ...\n"); + } + + // create an atom map if one doesn't exist already + + int mapflag = 0; + if (atom->map_style == 0) { + mapflag = 1; + atom->nghost = 0; + atom->map_init(); + atom->map_set(); + } + + // initialize system since comm->borders() will be invoked + + lmp->init(); + + // setup domain, communication + // acquire ghosts - is that really necessary? + // exchange will clear map, borders will reset + // this is the map needed to lookup current global IDs for bond topology + + if (domain->triclinic) domain->x2lamda(atom->nlocal); + domain->pbc(); + domain->reset_box(); + comm->setup(); + comm->exchange(); + comm->borders(); + if (domain->triclinic) domain->lamda2x(atom->nlocal+atom->nghost); + + // oldIDs = copy of current owned IDs + + tagint *tag = atom->tag; + int nlocal = atom->nlocal; + int nall = nlocal + atom->nghost; + + tagint *oldIDs; + memory->create(oldIDs,nlocal,"reset_ids:oldIDs"); + + for (int i = 0; i < nlocal; i++) { + oldIDs[i] = tag[i]; + tag[i] = 0; + } + + // assign new contigous IDs to owned atoms via tag_extend() + + atom->tag_extend(); + + // newIDs = copy of new IDs + // restore old IDs, consistent with existing atom map + // forward_comm_array acquires new IDs for ghost atoms + + double **newIDs; + memory->create(newIDs,nall,1,"reset_ids:newIDs"); + + for (int i = 0; i < nlocal; i++) { + newIDs[i][0] = tag[i]; + tag[i] = oldIDs[i]; + } + + comm->forward_comm_array(1,newIDs); + + // loop over bonds, angles, etc and reset IDs in stored topology arrays + // only necessary for molecular = 1, not molecular = 2 + // badcount = atom IDs that could not be found + + int badcount = 0; + + if (atom->molecular == 1) { + int j,m; + tagint oldID; + + if (atom->avec->bonds_allow) { + int *num_bond = atom->num_bond; + tagint **bond_atom = atom->bond_atom; + for (int i = 0; i < nlocal; i++) { + for (j = 0; j < num_bond[i]; j++) { + oldID = bond_atom[i][j]; + m = atom->map(oldID); + if (m >= 0) bond_atom[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + } + } + } + + if (atom->avec->angles_allow) { + int *num_angle = atom->num_angle; + tagint **angle_atom1 = atom->angle_atom1; + tagint **angle_atom2 = atom->angle_atom2; + tagint **angle_atom3 = atom->angle_atom3; + for (int i = 0; i < nlocal; i++) { + for (j = 0; j < num_angle[i]; j++) { + oldID = angle_atom1[i][j]; + m = atom->map(oldID); + if (m >= 0) angle_atom1[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = angle_atom2[i][j]; + m = atom->map(oldID); + if (m >= 0) angle_atom2[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = angle_atom3[i][j]; + m = atom->map(oldID); + if (m >= 0) angle_atom3[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + } + } + } + + if (atom->avec->dihedrals_allow) { + int *num_dihedral = atom->num_dihedral; + tagint **dihedral_atom1 = atom->dihedral_atom1; + tagint **dihedral_atom2 = atom->dihedral_atom2; + tagint **dihedral_atom3 = atom->dihedral_atom3; + tagint **dihedral_atom4 = atom->dihedral_atom4; + for (int i = 0; i < nlocal; i++) { + for (j = 0; j < num_dihedral[i]; j++) { + oldID = dihedral_atom1[i][j]; + m = atom->map(oldID); + if (m >= 0) dihedral_atom1[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = dihedral_atom2[i][j]; + m = atom->map(oldID); + if (m >= 0) dihedral_atom2[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = dihedral_atom3[i][j]; + m = atom->map(oldID); + if (m >= 0) dihedral_atom3[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = dihedral_atom4[i][j]; + m = atom->map(oldID); + if (m >= 0) dihedral_atom4[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + } + } + } + + if (atom->avec->impropers_allow) { + int *num_improper = atom->num_improper; + tagint **improper_atom1 = atom->improper_atom1; + tagint **improper_atom2 = atom->improper_atom2; + tagint **improper_atom3 = atom->improper_atom3; + tagint **improper_atom4 = atom->improper_atom4; + for (int i = 0; i < nlocal; i++) { + for (j = 0; j < num_improper[i]; j++) { + oldID = improper_atom1[i][j]; + m = atom->map(oldID); + if (m >= 0) improper_atom1[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = improper_atom2[i][j]; + m = atom->map(oldID); + if (m >= 0) improper_atom2[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = improper_atom3[i][j]; + m = atom->map(oldID); + if (m >= 0) improper_atom3[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + + oldID = improper_atom4[i][j]; + m = atom->map(oldID); + if (m >= 0) improper_atom4[i][j] = static_cast<tagint> (newIDs[m][0]); + else badcount++; + } + } + } + } + + // error check + + int all; + MPI_Allreduce(&badcount,&all,1,MPI_INT,MPI_SUM,world); + if (all) { + char str[128]; + sprintf(str,"Reset_ids missing %d bond topology atom IDs - " + "use comm_modify cutoff",all); + error->all(FLERR,str); + } + + // reset IDs and atom map for owned atoms + + atom->map_clear(); + atom->nghost = 0; + for (int i = 0; i < nlocal; i++) tag[i] = static_cast<tagint> (newIDs[i][0]); + atom->map_init(); + atom->map_set(); + + // delete temporary atom map + + if (mapflag) { + atom->map_delete(); + atom->map_style = 0; + } + + // clean up + + memory->destroy(oldIDs); + memory->destroy(newIDs); +} diff --git a/src/reset_ids.h b/src/reset_ids.h new file mode 100644 index 0000000000..065f440a8b --- /dev/null +++ b/src/reset_ids.h @@ -0,0 +1,42 @@ +/* -*- c++ -*- ---------------------------------------------------------- + LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator + http://lammps.sandia.gov, Sandia National Laboratories + Steve Plimpton, sjplimp@sandia.gov + + Copyright (2003) Sandia Corporation. Under the terms of Contract + DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains + certain rights in this software. This software is distributed under + the GNU General Public License. + + See the README file in the top-level LAMMPS directory. +------------------------------------------------------------------------- */ + +#ifdef COMMAND_CLASS + +CommandStyle(reset_ids,ResetIDs) + +#else + +#ifndef LMP_RESET_IDS_H +#define LMP_RESET_IDS_H + +#include "pointers.h" + +namespace LAMMPS_NS { + +class ResetIDs : protected Pointers { + public: + ResetIDs(class LAMMPS *); + void command(int, char **); + + private: +}; + +} + +#endif +#endif + +/* ERROR/WARNING messages: + +*/