diff --git a/doc/html/Manual.html b/doc/html/Manual.html index 2dfdb1123439f0656c3a56f1b9ad32f06e34eff9..963ee9cacdd038d0141152a0ea8d0009c4cb8b3f 100644 --- a/doc/html/Manual.html +++ b/doc/html/Manual.html @@ -135,7 +135,7 @@

LAMMPS Documentation

-

20 Aug 2016 version

+

23 Aug 2016 version

Version info:

diff --git a/doc/html/_sources/Manual.txt b/doc/html/_sources/Manual.txt deleted file mode 100644 index 7d0992b42bb364598b8f2cb581b8e1b19d5375e9..0000000000000000000000000000000000000000 --- a/doc/html/_sources/Manual.txt +++ /dev/null @@ -1,105 +0,0 @@ -.. raw:: html - -

- -LAMMPS Documentation -==================== - -20 Aug 2016 version -------------------- - -Version info: -------------- - -The LAMMPS "version" is the date when it was released, such as 1 May -2010. LAMMPS is updated continuously. Whenever we fix a bug or add a -feature, we release it immediately, and post a notice on `this page of the WWW site `_. Each dated copy of LAMMPS contains all the -features and bug-fixes up to and including that version date. The -version date is printed to the screen and logfile every time you run -LAMMPS. It is also in the file src/version.h and in the LAMMPS -directory name created when you unpack a tarball, and at the top of -the first page of the manual (this page). - -* If you browse the HTML doc pages on the LAMMPS WWW site, they always - describe the most current version of LAMMPS. -* If you browse the HTML doc pages included in your tarball, they - describe the version you have. -* The `PDF file `_ on the WWW site or in the tarball is updated - about once per month. This is because it is large, and we don't want - it to be part of every patch. -* There is also a `Developer.pdf `_ file in the doc - directory, which describes the internal structure and algorithms of - LAMMPS. - -LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel -Simulator. - -LAMMPS is a classical molecular dynamics simulation code designed to -run efficiently on parallel computers. It was developed at Sandia -National Laboratories, a US Department of Energy facility, with -funding from the DOE. It is an open-source code, distributed freely -under the terms of the GNU Public License (GPL). - -The primary developers of LAMMPS are `Steve Plimpton `_, Aidan -Thompson, and Paul Crozier who can be contacted at -sjplimp,athomps,pscrozi at sandia.gov. The `LAMMPS WWW Site `_ at -http://lammps.sandia.gov has more information about the code and its -uses. - -.. _bug: http://lammps.sandia.gov/bug.html - - - -.. _sjp: http://www.sandia.gov/~sjplimp - - - - ----------- - - -The LAMMPS documentation is organized into the following sections. If -you find errors or omissions in this manual or have suggestions for -useful information to add, please send an email to the developers so -we can improve the LAMMPS documentation. - -Once you are familiar with LAMMPS, you may want to bookmark :ref:`this page ` at Section_commands.html#comm since -it gives quick access to documentation for all LAMMPS commands. - -`PDF file `_ of the entire manual, generated by -`htmldoc `_ - - -.. toctree:: - :maxdepth: 2 - :numbered: - - Section_intro - Section_start - Section_commands - Section_packages - Section_accelerate - Section_howto - Section_example - Section_perf - Section_tools - Section_modify - Section_python - Section_errors - Section_history - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` - -.. raw:: html - - - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Section_commands.html#comm diff --git a/doc/html/_sources/Section_accelerate.txt b/doc/html/_sources/Section_accelerate.txt deleted file mode 100644 index e426b591b8c6c65861da2cab192c78cba41292f4..0000000000000000000000000000000000000000 --- a/doc/html/_sources/Section_accelerate.txt +++ /dev/null @@ -1,398 +0,0 @@ -Accelerating LAMMPS performance -=============================== - -This section describes various methods for improving LAMMPS -performance for different classes of problems running on different -kinds of machines. - -There are two thrusts to the discussion that follows. The -first is using code options that implement alternate algorithms -that can speed-up a simulation. The second is to use one -of the several accelerator packages provided with LAMMPS that -contain code optimized for certain kinds of hardware, including -multi-core CPUs, GPUs, and Intel Xeon Phi coprocessors. - -* 5.1 :ref:`Measuring performance ` -* 5.2 :ref:`Algorithms and code options to boost performace ` -* 5.3 :ref:`Accelerator packages with optimized styles ` -* 5.3.1 :doc:`GPU package ` -* 5.3.2 :doc:`USER-INTEL package ` -* 5.3.3 :doc:`KOKKOS package ` -* 5.3.4 :doc:`USER-OMP package ` -* 5.3.5 :doc:`OPT package ` -* 5.4 :ref:`Comparison of various accelerator packages ` -The `Benchmark page `_ of the LAMMPS -web site gives performance results for the various accelerator -packages discussed in Section 5.2, for several of the standard LAMMPS -benchmark problems, as a function of problem size and number of -compute nodes, on different hardware platforms. - - - - - -.. _acc_1: - -Measuring performance ---------------------------------- - -Before trying to make your simulation run faster, you should -understand how it currently performs and where the bottlenecks are. - -The best way to do this is run the your system (actual number of -atoms) for a modest number of timesteps (say 100 steps) on several -different processor counts, including a single processor if possible. -Do this for an equilibrium version of your system, so that the -100-step timings are representative of a much longer run. There is -typically no need to run for 1000s of timesteps to get accurate -timings; you can simply extrapolate from short runs. - -For the set of runs, look at the timing data printed to the screen and -log file at the end of each LAMMPS run. :ref:`This section ` of the manual has an overview. - -Running on one (or a few processors) should give a good estimate of -the serial performance and what portions of the timestep are taking -the most time. Running the same problem on a few different processor -counts should give an estimate of parallel scalability. I.e. if the -simulation runs 16x faster on 16 processors, its 100% parallel -efficient; if it runs 8x faster on 16 processors, it's 50% efficient. - -The most important data to look at in the timing info is the timing -breakdown and relative percentages. For example, trying different -options for speeding up the long-range solvers will have little impact -if they only consume 10% of the run time. If the pairwise time is -dominating, you may want to look at GPU or OMP versions of the pair -style, as discussed below. Comparing how the percentages change as -you increase the processor count gives you a sense of how different -operations within the timestep are scaling. Note that if you are -running with a Kspace solver, there is additional output on the -breakdown of the Kspace time. For PPPM, this includes the fraction -spent on FFTs, which can be communication intensive. - -Another important detail in the timing info are the histograms of -atoms counts and neighbor counts. If these vary widely across -processors, you have a load-imbalance issue. This often results in -inaccurate relative timing data, because processors have to wait when -communication occurs for other processors to catch up. Thus the -reported times for "Communication" or "Other" may be higher than they -really are, due to load-imbalance. If this is an issue, you can -uncomment the MPI_Barrier() lines in src/timer.cpp, and recompile -LAMMPS, to obtain synchronized timings. - - ----------- - - -.. _acc_2: - -General strategies ------------------------------- - -.. note:: - - this section 5.2 is still a work in progress - -Here is a list of general ideas for improving simulation performance. -Most of them are only applicable to certain models and certain -bottlenecks in the current performance, so let the timing data you -generate be your guide. It is hard, if not impossible, to predict how -much difference these options will make, since it is a function of -problem size, number of processors used, and your machine. There is -no substitute for identifying performance bottlenecks, and trying out -various options. - -* rRESPA -* 2-FFT PPPM -* Staggered PPPM -* single vs double PPPM -* partial charge PPPM -* verlet/split run style -* processor command for proc layout and numa layout -* load-balancing: balance and fix balance - -2-FFT PPPM, also called *analytic differentiation* or *ad* PPPM, uses -2 FFTs instead of the 4 FFTs used by the default *ik differentiation* -PPPM. However, 2-FFT PPPM also requires a slightly larger mesh size to -achieve the same accuracy as 4-FFT PPPM. For problems where the FFT -cost is the performance bottleneck (typically large problems running -on many processors), 2-FFT PPPM may be faster than 4-FFT PPPM. - -Staggered PPPM performs calculations using two different meshes, one -shifted slightly with respect to the other. This can reduce force -aliasing errors and increase the accuracy of the method, but also -doubles the amount of work required. For high relative accuracy, using -staggered PPPM allows one to half the mesh size in each dimension as -compared to regular PPPM, which can give around a 4x speedup in the -kspace time. However, for low relative accuracy, using staggered PPPM -gives little benefit and can be up to 2x slower in the kspace -time. For example, the rhodopsin benchmark was run on a single -processor, and results for kspace time vs. relative accuracy for the -different methods are shown in the figure below. For this system, -staggered PPPM (using ik differentiation) becomes useful when using a -relative accuracy of slightly greater than 1e-5 and above. - -.. image:: JPG/rhodo_staggered.jpg - :align: center - -.. note:: - - Using staggered PPPM may not give the same increase in accuracy - of energy and pressure as it does in forces, so some caution must be - used if energy and/or pressure are quantities of interest, such as - when using a barostat. - - ----------- - - -.. _acc_3: - -Packages with optimized styles ------------------------------------------- - -Accelerated versions of various :doc:`pair_style `, -:doc:`fixes `, :doc:`computes `, and other commands have -been added to LAMMPS, which will typically run faster than the -standard non-accelerated versions. Some require appropriate hardware -to be present on your system, e.g. GPUs or Intel Xeon Phi -coprocessors. - -All of these commands are in packages provided with LAMMPS. An -overview of packages is give in :doc:`Section packages `. - -These are the accelerator packages -currently in LAMMPS, either as standard or user packages: - -+--------------------------------------+------------------------------------------------+ -| :doc:`GPU ` | for NVIDIA GPUs as well as OpenCL support | -+--------------------------------------+------------------------------------------------+ -| :doc:`USER-INTEL ` | for Intel CPUs and Intel Xeon Phi | -+--------------------------------------+------------------------------------------------+ -| :doc:`KOKKOS ` | for GPUs, Intel Xeon Phi, and OpenMP threading | -+--------------------------------------+------------------------------------------------+ -| :doc:`USER-OMP ` | for OpenMP threading | -+--------------------------------------+------------------------------------------------+ -| :doc:`OPT ` | generic CPU optimizations | -+--------------------------------------+------------------------------------------------+ - -Inverting this list, LAMMPS currently has acceleration support for -three kinds of hardware, via the listed packages: - -+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| Many-core CPUs | :doc:`USER-INTEL `, :doc:`KOKKOS `, :doc:`USER-OMP `, :doc:`OPT ` packages | -+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| NVIDIA GPUs | :doc:`GPU `, :doc:`KOKKOS ` packages | -+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| Intel Phi | :doc:`USER-INTEL `, :doc:`KOKKOS ` packages | -+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - -Which package is fastest for your hardware may depend on the size -problem you are running and what commands (accelerated and -non-accelerated) are invoked by your input script. While these doc -pages include performance guidelines, there is no substitute for -trying out the different packages appropriate to your hardware. - -Any accelerated style has the same name as the corresponding standard -style, except that a suffix is appended. Otherwise, the syntax for -the command that uses the style is identical, their functionality is -the same, and the numerical results it produces should also be the -same, except for precision and round-off effects. - -For example, all of these styles are accelerated variants of the -Lennard-Jones :doc:`pair_style lj/cut `: - -* :doc:`pair_style lj/cut/gpu ` -* :doc:`pair_style lj/cut/intel ` -* :doc:`pair_style lj/cut/kk ` -* :doc:`pair_style lj/cut/omp ` -* :doc:`pair_style lj/cut/opt ` - -To see what accelerate styles are currently available, see -:ref:`Section_commands 5 ` of the manual. The -doc pages for individual commands (e.g. :doc:`pair lj/cut ` or -:doc:`fix nve `) also list any accelerated variants available -for that style. - -To use an accelerator package in LAMMPS, and one or more of the styles -it provides, follow these general steps. Details vary from package to -package and are explained in the individual accelerator doc pages, -listed above: - -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| build the accelerator library | only for GPU package | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| install the accelerator package | make yes-opt, make yes-user-intel, etc | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| add compile/link flags to Makefile.machine | in src/MAKE,
- only for USER-INTEL, KOKKOS, USER-OMP, OPT packages | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| re-build LAMMPS | make machine | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| run a LAMMPS simulation | lmp_machine < in.script
- mpirun -np 32 lmp_machine -in in.script | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| enable the accelerator package | via "-c on" and "-k on" :ref:`command-line switches `,
- only for KOKKOS package | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| set any needed options for the package | via "-pk" :ref:`command-line switch ` or - :doc:`package ` command,
- only if defaults need to be changed | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| use accelerated styles in your input script | via "-sf" :ref:`command-line switch ` or - :doc:`suffix ` command | -+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ - -Note that the first 4 steps can be done as a single command, using the -src/Make.py tool. This tool is discussed in :ref:`Section 2.4 ` of the manual, and its use is -illustrated in the individual accelerator sections. Typically these -steps only need to be done once, to create an executable that uses one -or more accelerator packages. - -The last 4 steps can all be done from the command-line when LAMMPS is -launched, without changing your input script, as illustrated in the -individual accelerator sections. Or you can add -:doc:`package ` and :doc:`suffix ` commands to your input -script. - -.. note:: - - With a few exceptions, you can build a single LAMMPS executable - with all its accelerator packages installed. Note however that the - USER-INTEL and KOKKOS packages require you to choose one of their - hardware options when building for a specific platform. I.e. CPU or - Phi option for the USER-INTEL package. Or the OpenMP, Cuda, or Phi - option for the KOKKOS package. - -These are the exceptions. You cannot build a single executable with: - -* both the USER-INTEL Phi and KOKKOS Phi options -* the USER-INTEL Phi or Kokkos Phi option, and the GPU package - -See the examples/accelerate/README and make.list files for sample -Make.py commands that build LAMMPS with any or all of the accelerator -packages. As an example, here is a command that builds with all the -GPU related packages installed (GPU, KOKKOS with Cuda), including -settings to build the needed auxiliary GPU libraries for Kepler GPUs: - -.. parsed-literal:: - - Make.py -j 16 -p omp gpu kokkos -cc nvcc wrap=mpi -gpu mode=double arch=35 -kokkos cuda arch=35 lib-all file mpi - -The examples/accelerate directory also has input scripts that can be -used with all of the accelerator packages. See its README file for -details. - -Likewise, the bench directory has FERMI and KEPLER and PHI -sub-directories with Make.py commands and input scripts for using all -the accelerator packages on various machines. See the README files in -those dirs. - -As mentioned above, the `Benchmark page `_ of the LAMMPS web site gives -performance results for the various accelerator packages for several -of the standard LAMMPS benchmark problems, as a function of problem -size and number of compute nodes, on different hardware platforms. - -Here is a brief summary of what the various packages provide. Details -are in the individual accelerator sections. - -* Styles with a "gpu" suffix are part of the GPU package, and can be run - on NVIDIA GPUs. The speed-up on a GPU depends on a variety of - factors, discussed in the accelerator sections. -* Styles with an "intel" suffix are part of the USER-INTEL - package. These styles support vectorized single and mixed precision - calculations, in addition to full double precision. In extreme cases, - this can provide speedups over 3.5x on CPUs. The package also - supports acceleration in "offload" mode to Intel(R) Xeon Phi(TM) - coprocessors. This can result in additional speedup over 2x depending - on the hardware configuration. -* Styles with a "kk" suffix are part of the KOKKOS package, and can be - run using OpenMP on multicore CPUs, on an NVIDIA GPU, or on an Intel - Xeon Phi in "native" mode. The speed-up depends on a variety of - factors, as discussed on the KOKKOS accelerator page. -* Styles with an "omp" suffix are part of the USER-OMP package and allow - a pair-style to be run in multi-threaded mode using OpenMP. This can - be useful on nodes with high-core counts when using less MPI processes - than cores is advantageous, e.g. when running with PPPM so that FFTs - are run on fewer MPI processors or when the many MPI tasks would - overload the available bandwidth for communication. -* Styles with an "opt" suffix are part of the OPT package and typically - speed-up the pairwise calculations of your simulation by 5-25% on a - CPU. -The individual accelerator package doc pages explain: - -* what hardware and software the accelerated package requires -* how to build LAMMPS with the accelerated package -* how to run with the accelerated package either via command-line switches or modifying the input script -* speed-ups to expect -* guidelines for best performance -* restrictions - - ----------- - - -.. _acc_4: - -Comparison of various accelerator packages ------------------------------------------------------- - -.. note:: - - this section still needs to be re-worked with additional KOKKOS - and USER-INTEL information. - -The next section compares and contrasts the various accelerator -options, since there are multiple ways to perform OpenMP threading, -run on GPUs, and run on Intel Xeon Phi coprocessors. - -All 3 of these packages accelerate a LAMMPS calculation using NVIDIA -hardware, but they do it in different ways. - -As a consequence, for a particular simulation on specific hardware, -one package may be faster than the other. We give guidelines below, -but the best way to determine which package is faster for your input -script is to try both of them on your machine. See the benchmarking -section below for examples where this has been done. - -**Guidelines for using each package optimally:** - -* The GPU package allows you to assign multiple CPUs (cores) to a single - GPU (a common configuration for "hybrid" nodes that contain multicore - CPU(s) and GPU(s)) and works effectively in this mode. -* The GPU package moves per-atom data (coordinates, forces) - back-and-forth between the CPU and GPU every timestep. The - KOKKOS/CUDA package only does this on timesteps when a CPU calculation - is required (e.g. to invoke a fix or compute that is non-GPU-ized). - Hence, if you can formulate your input script to only use GPU-ized - fixes and computes, and avoid doing I/O too often (thermo output, dump - file snapshots, restart files), then the data transfer cost of the - KOKKOS/CUDA package can be very low, causing it to run faster than the - GPU package. -* The GPU package is often faster than the KOKKOS/CUDA package, if the - number of atoms per GPU is smaller. The crossover point, in terms of - atoms/GPU at which the KOKKOS/CUDA package becomes faster depends - strongly on the pair style. For example, for a simple Lennard Jones - system the crossover (in single precision) is often about 50K-100K - atoms per GPU. When performing double precision calculations the - crossover point can be significantly smaller. -* Both packages compute bonded interactions (bonds, angles, etc) on the - CPU. If the GPU package is running with several MPI processes - assigned to one GPU, the cost of computing the bonded interactions is - spread across more CPUs and hence the GPU package can run faster. -* When using the GPU package with multiple CPUs assigned to one GPU, its - performance depends to some extent on high bandwidth between the CPUs - and the GPU. Hence its performance is affected if full 16 PCIe lanes - are not available for each GPU. In HPC environments this can be the - case if S2050/70 servers are used, where two devices generally share - one PCIe 2.0 16x slot. Also many multi-GPU mainboards do not provide - full 16 lanes to each of the PCIe 2.0 16x slots. -**Differences between the two packages:** - -* The GPU package accelerates only pair force, neighbor list, and PPPM - calculations. -* The GPU package requires neighbor lists to be built on the CPU when using - exclusion lists or a triclinic simulation box. - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Section_commands.html#comm diff --git a/doc/html/_sources/Section_commands.txt b/doc/html/_sources/Section_commands.txt deleted file mode 100644 index a91b18f20677e16e08d1ef27ca0320d27c65a13b..0000000000000000000000000000000000000000 --- a/doc/html/_sources/Section_commands.txt +++ /dev/null @@ -1,824 +0,0 @@ -Commands -======== - -This section describes how a LAMMPS input script is formatted and the -input script commands used to define a LAMMPS simulation. - -| 3.1 :ref:`LAMMPS input script ` -| 3.2 :ref:`Parsing rules ` -| 3.3 :ref:`Input script structure ` -| 3.4 :ref:`Commands listed by category ` -| 3.5 :ref:`Commands listed alphabetically ` -| - - - - - -.. _cmd_1: - -LAMMPS input script -------------------- - -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: - -.. parsed-literal:: - - timestep 0.5 - run 100 - run 100 - -does something different than this sequence: - -.. parsed-literal:: - - run 100 - timestep 0.5 - run 100 - -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 -:doc:`read_data ` command initializes the system by setting -up the simulation box and assigning atoms to processors. If default -values are not desired, the :doc:`processors ` and -:doc:`boundary ` 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. :doc:`This section ` gives -more information on what errors mean. The documentation for each -command lists restrictions on how the command can be used. - - ----------- - - -.. _cmd_2: - -Parsing rules -------------- - -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 `_ 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 :doc:`equal-style variable `. 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: - -.. parsed-literal:: - - variable X equal (xlo+xhi)/2+sqrt(v_area) - region 1 block $X 2 INF INF EDGE EDGE - variable X delete - -can be replaced by - -.. parsed-literal:: - - region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE - -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: - -.. parsed-literal:: - - variable a equal 2 - variable b2 equal 4 - print "B2 = ${b$a}" - -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 -:doc:`equal-style variable `. - -See the :doc:`variable ` 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: - -.. parsed-literal:: - - 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 - """ - -In each case, the single, double, or triple quotes are removed when -the single argument they enclose is stored internally. - -See the :doc:`dump modify format `, :doc:`print `, -:doc:`if `, and :doc:`python ` 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 :doc:`print ` command as part of an - :doc:`if ` or :doc:`run every ` 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. - - ----------- - - -.. _cmd_3: - -Input script structure ----------------------------------- - -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 -:doc:`Section_example `, and animated on the `LAMMPS WWW Site `_. - -A LAMMPS input script typically has 4 parts: - -1. Initialization -2. Atom definition -3. Settings -4. Run a simulation - -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 :doc:`units `, -:doc:`dimension `, :doc:`newton `, -:doc:`processors `, :doc:`boundary `, -:doc:`atom_style `, :doc:`atom_modify `. - -If force-field parameters appear in the files that will be read, these -commands tell LAMMPS what kinds of force fields are being used: -:doc:`pair_style `, :doc:`bond_style `, -:doc:`angle_style `, :doc:`dihedral_style `, -:doc:`improper_style `. - -(2) Atom definition - -There are 3 ways to define atoms in LAMMPS. Read them in from a data -or restart file via the :doc:`read_data ` or -:doc:`read_restart ` commands. These files can contain -molecular topology information. Or create atoms on a lattice (with no -molecular topology), using these commands: :doc:`lattice `, -:doc:`region `, :doc:`create_box `, -:doc:`create_atoms `. The entire set of atoms can be -duplicated to make a larger simulation using the -:doc:`replicate ` 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): :doc:`pair_coeff `, -:doc:`bond_coeff `, :doc:`angle_coeff `, -:doc:`dihedral_coeff `, -:doc:`improper_coeff `, -:doc:`kspace_style `, :doc:`dielectric `, -:doc:`special_bonds `. - -Various simulation parameters are set by these commands: -:doc:`neighbor `, :doc:`neigh_modify `, -:doc:`group `, :doc:`timestep `, -:doc:`reset_timestep `, :doc:`run_style `, -:doc:`min_style `, :doc:`min_modify `. - -Fixes impose a variety of boundary conditions, time integration, and -diagnostic options. The :doc:`fix ` command comes in many flavors. - -Various computations can be specified for execution during a -simulation using the :doc:`compute `, -:doc:`compute_modify `, and :doc:`variable ` -commands. - -Output options are set by the :doc:`thermo `, :doc:`dump `, -and :doc:`restart ` commands. - -(4) Run a simulation - -A molecular dynamics simulation is run using the :doc:`run ` -command. Energy minimization (molecular statics) is performed using -the :doc:`minimize ` command. A parallel tempering -(replica-exchange) simulation can be run using the -:doc:`temper ` command. - - ----------- - - -.. _cmd_4: - -Commands listed by category ---------------------------- - -This section lists all LAMMPS commands, grouped by category. The -:ref:`next section ` lists the same commands alphabetically. 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. - -Initialization: - -:doc:`atom_modify `, :doc:`atom_style `, -:doc:`boundary `, :doc:`dimension `, -:doc:`newton `, :doc:`processors `, :doc:`units ` - -Atom definition: - -:doc:`create_atoms `, :doc:`create_box `, -:doc:`lattice `, :doc:`read_data `, -:doc:`read_dump `, :doc:`read_restart `, -:doc:`region `, :doc:`replicate ` - -Force fields: - -:doc:`angle_coeff `, :doc:`angle_style `, -:doc:`bond_coeff `, :doc:`bond_style `, -:doc:`dielectric `, :doc:`dihedral_coeff `, -:doc:`dihedral_style `, -:doc:`improper_coeff `, -:doc:`improper_style `, -:doc:`kspace_modify `, :doc:`kspace_style `, -:doc:`pair_coeff `, :doc:`pair_modify `, -:doc:`pair_style `, :doc:`pair_write `, -:doc:`special_bonds ` - -Settings: - -:doc:`comm_style `, :doc:`group `, :doc:`mass `, -:doc:`min_modify `, :doc:`min_style `, -:doc:`neigh_modify `, :doc:`neighbor `, -:doc:`reset_timestep `, :doc:`run_style `, -:doc:`set `, :doc:`timestep `, :doc:`velocity ` - -Fixes: - -:doc:`fix `, :doc:`fix_modify `, :doc:`unfix ` - -Computes: - -:doc:`compute `, :doc:`compute_modify `, -:doc:`uncompute ` - -Output: - -:doc:`dump `, :doc:`dump image `, -:doc:`dump_modify `, :doc:`dump movie `, -:doc:`restart `, :doc:`thermo `, -:doc:`thermo_modify `, :doc:`thermo_style `, -:doc:`undump `, :doc:`write_data `, -:doc:`write_dump `, :doc:`write_restart ` - -Actions: - -:doc:`delete_atoms `, :doc:`delete_bonds `, -:doc:`displace_atoms `, :doc:`change_box `, -:doc:`minimize `, :doc:`neb ` :doc:`prd `, -:doc:`rerun `, :doc:`run `, :doc:`temper ` - -Miscellaneous: - -:doc:`clear `, :doc:`echo `, :doc:`if `, -:doc:`include `, :doc:`jump `, :doc:`label