diff --git a/cmake/Modules/Packages/GPU.cmake b/cmake/Modules/Packages/GPU.cmake index a9ae551df0d..3974e5ccc72 100644 --- a/cmake/Modules/Packages/GPU.cmake +++ b/cmake/Modules/Packages/GPU.cmake @@ -146,11 +146,18 @@ if(GPU_API STREQUAL "CUDA") if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1") string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]") endif() - # Lovelace (GPU Arch 8.9) is supported by CUDA 11.8 and later + # Ada Lovelace (GPU Arch 8.9) and Hopper (GPU Arch 9.0) are supported by CUDA 11.8 and later if(CUDA_VERSION VERSION_GREATER_EQUAL "11.8") string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]") endif() - # newer GPU Arch versions require CUDA 12.0 or later which is handled above + # Backwell (GPU Arch 100) is supported by CUDA 12.4 and later + if(CUDA_VERSION VERSION_GREATER_EQUAL "12.4") + string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_100,code=[sm_100,compute_100]") + endif() + # Rubin (GPU Arch 120) require CUDA 12.8 and later + if(CUDA_VERSION VERSION_GREATER_EQUAL "12.8") + string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_120,code=[sm_120,compute_120]") + endif() endif() endif() @@ -331,11 +338,18 @@ elseif(GPU_API STREQUAL "HIP") if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1") string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]") endif() - # Lovelace (GPU Arch 8.9) is supported by CUDA 11.8 and later + # Ada Lovelace (GPU Arch 8.9) and Hopper (GPU Arch 9.0) are supported by CUDA 11.8 and later if(CUDA_VERSION VERSION_GREATER_EQUAL "11.8") string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]") endif() - # newer GPU Arch versions require CUDA 12.0 or later which is handled above + # Backwell (GPU Arch 100) is supported by CUDA 12.4 and later + if(CUDA_VERSION VERSION_GREATER_EQUAL "12.4") + string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_100,code=[sm_100,compute_100]") + endif() + # Rubin (GPU Arch 120) require CUDA 12.8 and later + if(CUDA_VERSION VERSION_GREATER_EQUAL "12.8") + string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_120,code=[sm_120,compute_120]") + endif() endif() endif() diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 34f4a0c2b38..e7bdcb32cba 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -137,16 +137,15 @@ to: e.g. ``KSPACE``, and ``COLVARS``. See the :doc:`Packages details ` page for more info on these packages, and the pages for their respective commands for OpenMP threading info. -For CMake, if you use ``BUILD_OMP=yes``, you can use these packages -and turn on their native OpenMP support and turn on their native OpenMP -support at run time, by setting the ``OMP_NUM_THREADS`` environment -variable before you launch LAMMPS. - -For building via conventional make, the ``CCFLAGS`` and ``LINKFLAGS`` -variables in Makefile.machine need to include the compiler flag that -enables OpenMP. For the GNU compilers or Clang, it is ``-fopenmp``\ . -For (recent) Intel compilers, it is ``-qopenmp``\ . If you are using a -different compiler, please refer to its documentation. +For CMake, if you use ``BUILD_OMP=yes``, you can use these packages and +turn on their native OpenMP support at run time by setting the +``OMP_NUM_THREADS`` environment variable before you launch LAMMPS. + +When building LAMMPS with conventional make, the ``CCFLAGS`` and +``LINKFLAGS`` variables in Makefile.machine need to include the compiler +flag that enables OpenMP. For the GNU compilers or Clang, it is +``-fopenmp``\ . For (recent) Intel compilers, it is ``-qopenmp``\ . If +you are using a different compiler, please refer to its documentation. .. _default-none-issues: diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst index f889bd7f0ac..85538f47deb 100644 --- a/doc/src/Build_cmake.rst +++ b/doc/src/Build_cmake.rst @@ -206,14 +206,14 @@ Configuration and build options The CMake commands have one mandatory argument: a folder containing a file called ``CMakeLists.txt`` (for LAMMPS it is located in the -``cmake`` folder, in that case the current working directory becomes -the build folder) or a build folder containing a file called +``cmake`` folder, in that case the current working directory becomes the +build folder) or a build folder containing a file called ``CMakeCache.txt``, which is generated at the end of the CMake configuration step. The cache file contains all current CMake settings. -This is a "legacy mode" or running CMake and thus often found -when searching the web. We recommend to use the ``-S`` and ``-B`` -folders to explicitly set the path to the folder containing the -``CMakeLists.txt`` file and the build folder, respectively. +This is a "legacy mode" of running CMake and thus often found when +searching the web. We recommend to use the ``-S`` and ``-B`` folders to +explicitly set the path to the folder containing the ``CMakeLists.txt`` +file and the build folder, respectively. To modify settings, enable or disable features, you need to set *variables* with either the ``-D`` command-line flag (``-D @@ -252,19 +252,21 @@ of them you can use the command: cmake --build build --target lmp -Especially, when programming LAMMPS and you are making just local -changes, or only want to make certain that the code still compiles -and links, you may want to skip may of the extra steps that are -run by default and then append "/fast" to the target. Example: +Especially, when programming LAMMPS and you are making only local +changes, or only want to make certain that the code still compiles and +links, you may want to skip many of the extra steps that are run by +default and then append "/fast" to the target. Example: .. code-block:: bash cmake --build build --target lammps/fast -Note that this speeds up the build by skipping a lot of checks for -dependencies, and avoiding to re-run CMake, so you may occasionally need -to compile without the "/fast" suffix or use the "all" (= default) -target to update everything. +Note that this speeds up the build by avoiding to re-run CMake and +skipping a lot of checks for possible dependencies, so you may +occasionally need to compile without the "/fast" suffix or use the "all" +(= default) target to update everything. This would be *required* when +adding new files, additional dependencies, or making changes to the +CMake scripts. Some custom targets, e.g. "install-python" are explicitly excluded from the "all" target and must be built individually. diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst index a6c3b2fecb1..4d7eaaefa1a 100644 --- a/doc/src/Build_development.rst +++ b/doc/src/Build_development.rst @@ -55,8 +55,8 @@ during CMake configuration. -D ENABLE_IWYU=value # value = no (default) or yes This will check if the required binary (include-what-you-use or iwyu) -and python script script (iwyu-tool or iwyu_tool or iwyu_tool.py) can -be found in the path. The analysis can then be started with: +and python script (iwyu-tool or iwyu_tool or iwyu_tool.py) can be found +in the path. The analysis can then be started with: .. code-block:: bash diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index ff99b1d8db9..9b7549e9039 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -838,7 +838,7 @@ This list was last updated for version 4.7.1 of the Kokkos library. .. versionchanged:: 11Feb2026 - The KOKKOS package no longer supports the the traditional make build. + The KOKKOS package no longer supports the traditional make build. You need to build LAMMPS with CMake. Advanced KOKKOS compilation settings @@ -1945,5 +1945,5 @@ your system. .. versionchanged:: 10Sep2025 - The VTK package no longer supports the the traditional make build. + The VTK package no longer supports the traditional make build. You need to build LAMMPS with CMake. diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst index fd42aa92f41..7ef962368a3 100644 --- a/doc/src/Build_link.rst +++ b/doc/src/Build_link.rst @@ -128,7 +128,7 @@ POEMS package installed becomes: .. code-block:: bash - gcc -c -O -I${HOME}/lammps/src -caller.c + gcc -c -O -I${HOME}/lammps/src caller.c g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial Locating liblammps.so at runtime @@ -156,7 +156,7 @@ would add something like this to your ``${HOME}/.profile`` file: .. code-block:: bash - LD_LIBRARY_PATH ${LD_LIBRARY_PATH-/usr/lib64}:${HOME}/lammps/src + LD_LIBRARY_PATH=${LD_LIBRARY_PATH-/usr/lib64}:${HOME}/lammps/src export LD_LIBRARY_PATH For the csh or tcsh shells, you would equivalently add something like this diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst index 85c2a4df2a6..061b10c2eb0 100644 --- a/doc/src/Build_manual.rst +++ b/doc/src/Build_manual.rst @@ -34,7 +34,7 @@ the rest the build process will attempt to download and install them into a python virtual environment and local folders. A current version of the manual (latest feature release, that is the state -of the *release* branch) is is available online at: +of the *release* branch) is available online at: `https://docs.lammps.org/ `_. A version of the manual corresponding to the ongoing development (that is the state of the *develop* branch) is available online at: diff --git a/doc/src/Build_prerequisites.rst b/doc/src/Build_prerequisites.rst index d4ab5ffae03..e3082be9125 100644 --- a/doc/src/Build_prerequisites.rst +++ b/doc/src/Build_prerequisites.rst @@ -34,7 +34,7 @@ Compiler and OS compatibility The LAMMPS developers aim to keep LAMMPS very portable and usable - at least in parts - on most operating systems commonly used for -running MD simulations. Please see the :doc:`section on portablility +running MD simulations. Please see the :doc:`section on portability ` for more details. .. admonition:: Warning: LLVM based Intel Compilers @@ -52,10 +52,10 @@ running MD simulations. Please see the :doc:`section on portablility Unfortunately there is no simple way to detect whether a binary is working correctly outside of running the unit and regression tests, - but those do not cover all of LAMMPS and and would be reliable only - for no or moderate optimization anyway. For most of LAMMPS there is - not much of a benefit (if any) to use the Intel compilers over the - GCC or Clang compilers, except for the INTEL package (which *can* be + but those do not cover all of LAMMPS and would be reliable only for + no or moderate optimization anyway. For most of LAMMPS there is not + much of a benefit (if any) to use the Intel compilers over the GCC or + Clang compilers, except for the INTEL package (which *can* be compiled with other compilers, but most vectorization directives are inactive for those) or KOKKOS with SYCL. diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index a0a9acbd86a..7ff06cd8514 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -254,8 +254,8 @@ use and parallel communication costs for transposing 3d FFT data. When using ``-DFFT_SINGLE`` with FFTW3, you may need to ensure that the FFTW3 installation includes support for single-precision. -When compiler FFTW3 from source, you can do the following, which should -produce the additional libraries ``libfftw3f.a`` and/or ``libfftw3f.so``\ . +When compiling FFTW3 from source, you can do the following, which should +produce the additional libraries ``libfftw3f.a`` and ``libfftw3f.so``\ . .. code-block:: bash diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index f010a97b0de..cfacd81726d 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -124,7 +124,7 @@ An alphabetic list of general LAMMPS commands. Additional general LAMMPS commands provided by packages. A few commands have accelerated versions. This is indicated by an -additional letter in parenthesis: k = KOKKOS. +additional letter in parentheses: k = KOKKOS. .. table_from_list:: :columns: 6 diff --git a/doc/src/Commands_parse.rst b/doc/src/Commands_parse.rst index a342441878a..5a6971ab0e1 100644 --- a/doc/src/Commands_parse.rst +++ b/doc/src/Commands_parse.rst @@ -159,11 +159,11 @@ LAMMPS: .. 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 + 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 + for those commands for examples. Only one level of nesting is allowed, but that should be sufficient for most use cases. .. admonition:: ASCII versus UTF-8 diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index d455b9697d9..fd0784589a8 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -30,12 +30,11 @@ ATC, AWPMD, and POEMS packages .. deprecated:: 10Sep2025 -The ATC, AWPMD, and POEMS packages are removed.because there were +The ATC, AWPMD, and POEMS packages are removed because they were unmaintained for a long time and their legacy C++ programming style -started to create problems with modern C++ compilers. LAMMPS version -22 July 2025 is the last version that contains them. You have to -download and compile this version, if you want to use any of these -packages. +started to create problems with modern C++ compilers. LAMMPS version 22 +July 2025 is the last version that contains them. You have to download +and compile this version, if you want to use any of these packages. .. toctree:: :maxdepth: 0 diff --git a/doc/src/Developer_platform.rst b/doc/src/Developer_platform.rst index 9c8fb601a69..f004be2b306 100644 --- a/doc/src/Developer_platform.rst +++ b/doc/src/Developer_platform.rst @@ -80,6 +80,12 @@ to the path as a C++ string class instance. .. doxygenfunction:: file_is_readable :project: progguide +.. doxygenfunction:: file_is_writable + :project: progguide + +.. doxygenfunction:: file_redirect + :project: progguide + .. doxygenfunction:: is_console :project: progguide diff --git a/doc/src/Errors_common.rst b/doc/src/Errors_common.rst index 23c450c4fce..ea560b0c7b9 100644 --- a/doc/src/Errors_common.rst +++ b/doc/src/Errors_common.rst @@ -57,7 +57,7 @@ sometimes be confusing or need additional explanations. do, but very strictly applies the syntax as described in the documentation. If you run into errors that LAMMPS does not catch that you think it should flag, please send an email to the `developers - `_ or create an new topic on the + `_ or create a new topic on the dedicated `MatSci forum section `_. - If you get an error message about an invalid command in your input diff --git a/doc/src/Errors_debug.rst b/doc/src/Errors_debug.rst index 61fb1f75250..cae727779b4 100644 --- a/doc/src/Errors_debug.rst +++ b/doc/src/Errors_debug.rst @@ -248,7 +248,7 @@ can have multiple reasons: system size, e.g. :doc:`kspace styles like ewald or pppm `. There is very little that can be done in this case. - The output interval is not set or set to a large value with the - :doc:`thermo ` command. I the first case, there will be output + :doc:`thermo ` command. In the first case, there will be output only at the first and last step. - The output is block-buffered and instead of line-buffered. The output will only be written to the screen after 4096 or 8192 characters of diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst index 2191b857ea8..f75b4f0a8a0 100644 --- a/doc/src/Errors_details.rst +++ b/doc/src/Errors_details.rst @@ -31,8 +31,9 @@ Create a small test system Debugging problems often requires running a simulation many times with small modifications, thus it can be a huge time saver to first assemble a small test system input that has the same issue, but will take much -time until it triggers the error condition. Also, it will be easier to -see what happens. +less time until it triggers the error condition. Also, it will be +easier to see what happens when visualizing the system or looking at +output files. .. _hint02: @@ -81,15 +82,15 @@ While a segmentation fault is likely an indication of a bug in LAMMPS, it need not always be; it can also be the consequence of too aggressive simulation settings. For time critical code paths, LAMMPS will assume the user has chosen the settings carefully and will not make any checks -to avoid to avoid performance penalties. +to avoid performance penalties. A crucial step in resolving a segmentation fault is to identify the -exact location in the code where it happens. Please see `Errors_debug` -for a couple of examples showing how to do this on a Linux machine. -With this information -- a simple way to reproduce the segmentation -fault and the exact :doc:`LAMMPS version ` and platform -you are running on -- you can contact the LAMMPS developers or post in -the LAMMPS forum to get assistance. +exact location in the code where it happens. Please see +:doc:`Errors_debug` for a couple of examples showing how to do this on a +Linux machine. With this information -- a simple way to reproduce the +segmentation fault and the exact :doc:`LAMMPS version ` +and platform you are running on -- you can contact the LAMMPS developers +or post in the LAMMPS forum to get assistance. .. _hint05: @@ -100,7 +101,7 @@ Fast moving atoms may be "lost" or "missing" when their velocity becomes so large that they can cross a sub-domain within one timestep. This often happens when atoms are too close, but atoms may also "move" too fast from sub-domain to sub-domain if the box changes rapidly. -E.g. when setting a large an initial box with :doc:`shrink-wrap boundary +E.g. when setting a large initial box with :doc:`shrink-wrap boundary conditions ` that collapses on the first step (in this case the solution is often using 'm' instead of 's' as a boundary condition). @@ -266,7 +267,7 @@ before the box (e.g. a compute or fix reference or a thermo keyword). Illegal ... command ^^^^^^^^^^^^^^^^^^^ -These are a catchall error messages that used to be used a lot in LAMMPS +These are catchall error messages that used to be used a *lot* in LAMMPS (also programmers are sometimes lazy). They usually include the name of the source file and the line where the error happened. This can be used to track down what caused the error (most often some form of syntax error) @@ -433,7 +434,7 @@ Nose-Hoover (or other) barostat, and thus it may be advisable to run with only a thermostat for a bit until the potential energy has stabilized. -.. _err007: +.. _err0007: Fix used in ... not computed at compatible time ----------------------------------------------- @@ -521,7 +522,7 @@ executable. In rare cases, there may be licensing or portability issues that prevent including a package in publicly accessible binaries or in a specific environment. -.. _err011: +.. _err0011: Energy or stress was not tallied by pair style ---------------------------------------------- @@ -570,7 +571,7 @@ For example: variable cutoff index 10.0 pair_style lj/cut ${cutoff} # this is correct pair_style lj/cut $cutoff # this is incorrect, LAMMPS looks for 'c' instead of 'cutoff' - variable c index 5.0 # if $c is defined, LAMMPS subsitutes only '$c' and reads: 5utoff + variable c index 5.0 # if $c is defined, LAMMPS substitutes only '$c' and reads: 5utoff Another potential source of this error may be invalid command line variables (-var or -v argument) used when launching LAMMPS from an @@ -908,7 +909,7 @@ the lack of a time-integrating fix is intentional or not. System is not charge neutral, net charge = ... ---------------------------------------------- -the sum of charges in the system is not zero. When a system is not +The sum of charges in the system is not zero. When a system is not charge-neutral, methods that evolve/manipulate per-atom charges, evaluate Coulomb interactions, evaluate Coulomb forces, or evaluate/manipulate other properties relying on per-atom charges may @@ -1021,7 +1022,7 @@ Error messages ending in 'Please contact the LAMMPS developers' Such error messages indicate that something unexpected has happened and that it will require a good understanding of the details of the design of LAMMPS to resolve this. This can be due to some bug in contributed -code, and oversight when updating functionality, a feature that is +code, an oversight when updating functionality, a feature that is scheduled to be removed or reaching a combination of flags and settings that should not be possible or similar. diff --git a/doc/src/Errors_messages.rst b/doc/src/Errors_messages.rst index 526c74fa66e..596ed594265 100644 --- a/doc/src/Errors_messages.rst +++ b/doc/src/Errors_messages.rst @@ -463,10 +463,6 @@ Please also see the page with :doc:`Warning messages `. *Cannot clear group all* This operation is not allowed. -*Cannot close restart file - MPI error: %s* - This error was generated by MPI when reading/writing an MPI-IO restart - file. - *Cannot compute initial g_ewald_disp* LAMMPS failed to compute an initial guess for the PPPM_disp g_ewald_6 factor that partitions the computation between real space and k-space @@ -703,14 +699,6 @@ Please also see the page with :doc:`Warning messages `. The specified polymorphic potential file cannot be opened. Check that the path and name are correct. -*Cannot open restart file for reading - MPI error: %s* - This error was generated by MPI when reading/writing an MPI-IO restart - file. - -*Cannot open restart file for writing - MPI error: %s* - This error was generated by MPI when reading/writing an MPI-IO restart - file. - *Cannot open screen file* The screen file specified as a command-line argument cannot be opened. Check that the directory you are running in allows for files @@ -726,10 +714,6 @@ Please also see the page with :doc:`Warning messages `. Check that the directory you are running in allows for files to be created. -*Cannot read from restart file - MPI error: %s* - This error was generated by MPI when reading/writing an MPI-IO restart - file. - *Cannot read_restart after simulation box is defined* The read_restart command cannot be used after a read_data, read_restart, or create_box command. @@ -784,10 +768,6 @@ Please also see the page with :doc:`Warning messages `. In the rRESPA integrator, you must define both a inner and outer setting in order to use a middle setting. -*Cannot set restart file size - MPI error: %s* - This error was generated by MPI when reading/writing an MPI-IO restart - file. - *Cannot set temperature for fix rigid/nph* The temp keyword cannot be specified. @@ -1107,10 +1087,6 @@ Please also see the page with :doc:`Warning messages `. *Cannot wiggle and shear fix wall/gran* Cannot specify both options at the same time. -*Cannot write to restart file - MPI error: %s* - This error was generated by MPI when reading/writing an MPI-IO restart - file. - *Cannot yet use KSpace solver with grid with comm style tiled* This is current restriction in LAMMPS. @@ -1707,10 +1683,6 @@ Please also see the page with :doc:`Warning messages `. *Dump every variable returned a bad timestep* The variable must return a timestep greater than the current timestep. -*Dump file MPI-IO output not allowed with % in filename* - This is because a % signifies one file per processor and MPI-IO - creates one large file for all processors. - *Dump image requires one snapshot per file* Use a "\*" in the filename. @@ -4203,10 +4175,6 @@ Please also see the page with :doc:`Warning messages `. It cannot be larger than the size of atom IDs, e.g. the maximum 32-bit integer. -*Read restart MPI-IO input not allowed with % in filename* - This is because a % signifies one file per processor and MPI-IO - creates one large file for all processors. - *Read_data shrink wrap did not assign all atoms correctly* This is typically because the box-size specified in the data file is large compared to the actual extent of atoms in a shrink-wrapped @@ -4278,10 +4246,6 @@ Please also see the page with :doc:`Warning messages `. *Respa middle cutoffs are invalid* The first cutoff must be <= the second cutoff. -*Restart file MPI-IO output not allowed with % in filename* - This is because a % signifies one file per processor and MPI-IO - creates one large file for all processors. - *Restart file byte ordering is not recognized* The file does not appear to be a LAMMPS restart file since it does not contain a recognized byte-ordering flag at the beginning. @@ -4297,15 +4261,9 @@ Please also see the page with :doc:`Warning messages `. Use your older version of LAMMPS and convert the restart file to a data file. -*Restart file is a MPI-IO file* - The file is inconsistent with the filename you specified for it. - *Restart file is a multi-proc file* The file is inconsistent with the filename you specified for it. -*Restart file is not a MPI-IO file* - The file is inconsistent with the filename you specified for it. - *Restart file is not a multi-proc file* The file is inconsistent with the filename you specified for it. diff --git a/doc/src/Howto_bioFF.rst b/doc/src/Howto_bioFF.rst index cf8e4ab13e6..7c5df22dd9d 100644 --- a/doc/src/Howto_bioFF.rst +++ b/doc/src/Howto_bioFF.rst @@ -248,7 +248,7 @@ groups in organic and biological molecules. Each atom includes a static, partial atomic charge reflecting the oxidation state of the element derived from its bonded neighbors :ref:`(Jorgensen) ` and computed based on increments determined by the -atom type of the atoms bond to it. +atom type of the atoms bonded to it. The interaction styles listed below compute force field formulas that are fully or in part consistent with the OPLS style force fields. See diff --git a/doc/src/Howto_body.rst b/doc/src/Howto_body.rst index e5ee25a52a9..c4d72a5931a 100644 --- a/doc/src/Howto_body.rst +++ b/doc/src/Howto_body.rst @@ -108,13 +108,13 @@ are listed in the sections below. Note that for all the body styles, if the data file defines a general triclinic box, then the orientation of the body particle and its corresponding 6 moments of inertia and other orientation-dependent -values should reflect the fact the body is defined withing a general +values should reflect the fact the body is defined within a general triclinic box with edge vectors **A**,**B**,**C**. LAMMPS will rotate the box to convert it to a restricted triclinic box. This operation will also rotate the orientation of the body particles. See the -:doc:`Howto triclinic ` doc page for more details. -The sections below highlight the orientation-dependent values specific -to each body style. +:doc:`Howto triclinic ` doc page for more details. The +sections below highlight the orientation-dependent values specific to +each body style. ---------- @@ -464,7 +464,7 @@ these polyhedron vertex displacements are orientation-dependent and, as mentioned above, should reflect the body particle's orientation within the general triclinic box. -The :doc:`pair_style body/rounded/polhedron +The :doc:`pair_style body/rounded/polyhedron ` command can be used with this body style to compute body/body interactions. The :doc:`fix wall/body/polyhedron ` command can be used with @@ -476,7 +476,7 @@ wall. **Output specifics for all body styles:** For the :doc:`compute body/local ` and :doc:`dump -local ` commands, all 3 of the body styles described on his page +local ` commands, all 3 of the body styles described on this page produces one datum for each of the N vertices (of sub-particles) in a body particle. The datum has 3 values: diff --git a/doc/src/Howto_bulk2slab.rst b/doc/src/Howto_bulk2slab.rst index 2c26961522e..6d58bdb9e0a 100644 --- a/doc/src/Howto_bulk2slab.rst +++ b/doc/src/Howto_bulk2slab.rst @@ -104,7 +104,7 @@ potential energy, we reduce the thermostat time constant from 100.0 to Also the high potential energy of the surface atoms can cause that some of them are ejected from the slab. In order to suppress that, we add soft harmonic walls to push back any atoms that want to leave the slab. -To determine the position of the wall, we first need to to determine the +To determine the position of the wall, we first need to determine the extent of the atoms in z-direction and then place the harmonic walls based on that information: @@ -131,8 +131,8 @@ z-direction will experience a restoring force, nudging them back to the slab. The force constant of :math:`10.0 \frac{\mathrm{kcal/mol}}{\AA}` was determined empirically. -Adding these "restoring" soft walls assist in making the free surfaces -above and below the slab flat, instead of having rugged or ondulated +Adding these "restoring" soft walls assists in making the free surfaces +above and below the slab flat, instead of having rugged or undulated surfaces. The impact of the walls can be changed by adjusting the force constant, cutoff, and position of the wall. diff --git a/doc/src/Howto_cmake.rst b/doc/src/Howto_cmake.rst index 9146bb79405..1fb3b349a5d 100644 --- a/doc/src/Howto_cmake.rst +++ b/doc/src/Howto_cmake.rst @@ -395,7 +395,7 @@ change some variables later with additional *-D* flags. A few examples: The first command will install the packages ``KSPACE``, ``MANYBODY``, ``MOLECULE``, ``RIGID``, ``GRAPHICS``, and ``MISC``; the first five from -the preset file and the fifth from the explicit variable definition. +the preset file and the sixth from the explicit variable definition. The second command will first switch the compiler toolchain to use the Clang compilers and install a large number of packages that are not depending on any special external libraries or tools and are not very diff --git a/doc/src/Howto_coreshell.rst b/doc/src/Howto_coreshell.rst index d235550c908..95f31e40f6f 100644 --- a/doc/src/Howto_coreshell.rst +++ b/doc/src/Howto_coreshell.rst @@ -223,7 +223,7 @@ For example if core/shell pairs and other molecules are present: compute prop all property/atom i_CSID (...) -The additional section in the date file would be formatted like this: +The additional section in the data file would be formatted like this: .. parsed-literal:: diff --git a/doc/src/Howto_drude2.rst b/doc/src/Howto_drude2.rst index 00289a989a8..be0cf171d22 100644 --- a/doc/src/Howto_drude2.rst +++ b/doc/src/Howto_drude2.rst @@ -1,15 +1,14 @@ Tutorial for Thermalized Drude oscillators in LAMMPS ==================================================== -This tutorial explains how to use Drude oscillators in LAMMPS to -simulate polarizable systems using the DRUDE package. As an +This Howto document explains how to use Drude oscillators in LAMMPS to +simulate polarizable systems using the DRUDE package. As an illustration, the input files for a simulation of 250 phenol molecules -are documented. First of all, LAMMPS has to be compiled with the -DRUDE package activated. Then, the data file and input scripts -have to be modified to include the Drude dipoles and how to handle -them. +are documented. First of all, LAMMPS has to be compiled with the DRUDE +package included. Then, the data file and input scripts have to be +modified to include the Drude dipoles and how to handle them. -Example input scripts available: examples/PACKAGES/drude +Example input scripts are available: ``examples/PACKAGES/drude`` ---------- @@ -43,43 +42,68 @@ charge, and force constant can be chosen following different strategies, as in the following examples of polarizable force fields: -* :ref:`Lamoureux and Roux ` suggest adopting a global half-stiffness, :math:`K_D` = 500 kcal/(mol Ang :math:`{}^2`) - which corresponds to a force constant :math:`k_D` = 4184 kJ/(mol Ang :math:`{}^2`) - for all types of core-Drude bond, a global mass :math:`m_D` = 0.4 g/mol (or u) for all types of Drude particles, and to calculate the Drude charges for individual atom types from the atom polarizabilities using equation (1). This choice is followed in the polarizable CHARMM force field. -* Alternately :ref:`Schroeder and Steinhauser ` suggest adopting a global charge :math:`q_D` = -1.0e and a global mass :math:`m_D` = 0.1 g/mol (or u) for all Drude particles, and to calculate the force constant for each type of core-Drude bond from equation (1). The timesteps used by these authors are between 0.5 and 2 fs, with the degrees of freedom of the Drude oscillators kept cold at 1 K. -* In both these force fields hydrogen atoms are treated as non-polarizable. - -The motion of of the Drude particles can be calculated by minimizing -the energy of the induced dipoles at each timestep, by an iterative, -self-consistent procedure. The Drude particles can be massless and -therefore do not contribute to the kinetic energy. However, the -relaxed method is computational slow. An extended-lagrangian method -can be used to calculate the positions of the Drude particles, but -this requires them to have mass. It is important in this case to -decouple the degrees of freedom associated with the Drude oscillators -from those of the normal atoms. Thermalizing the Drude dipoles at -temperatures comparable to the rest of the simulation leads to several -problems (kinetic energy transfer, very short timestep, etc.), which -can be remedied by the "cold Drude" technique (:ref:`Lamoureux and Roux `). +* :ref:`Lamoureux and Roux ` suggest adopting a global + half-stiffness, :math:`K_D` = 500 kcal/(mol Ang :math:`{}^2`) - which + corresponds to a force constant :math:`k_D` = 4184 kJ/(mol Ang + :math:`{}^2`) - for all types of core-Drude bond, a global mass + :math:`m_D` = 0.4 g/mol (or u) for all types of Drude particles, and + to calculate the Drude charges for individual atom types from the atom + polarizabilities using equation (1). This choice is followed in the + polarizable CHARMM force field. +* Alternately, :ref:`Schroeder and Steinhauser ` suggest + adopting a global charge :math:`q_D` = -1.0e and a global mass + :math:`m_D` = 0.1 g/mol (or u) for all Drude particles, and to + calculate the force constant for each type of core-Drude bond from + equation (1). The timesteps used by these authors are between 0.5 and + 2 fs, with the degrees of freedom of the Drude oscillators kept cold + at 1 K. +* In both these force fields hydrogen atoms are treated as + non-polarizable. + +The motion of the Drude particles can be calculated by minimizing the +energy of the induced dipoles at each timestep, by an iterative, +self-consistent procedure. The Drude particles can be massless and +therefore do not contribute to the kinetic energy. However, the relaxed +method is computationally slow. An extended-lagrangian method can be +used to calculate the positions of the Drude particles, but this +requires them to have mass. It is important in this case to decouple +the degrees of freedom associated with the Drude oscillators from those +of the normal atoms. Thermalizing the Drude dipoles at temperatures +comparable to the rest of the simulation leads to several problems +(kinetic energy transfer, very short timestep, etc.), which can be +remedied by the "cold Drude" technique (:ref:`Lamoureux and Roux +`). Two closely related models are used to represent polarization through -"charges on a spring": the core-shell model and the Drude -model. Although the basic idea is the same, the core-shell model is -normally used for ionic/crystalline materials, whereas the Drude model -is normally used for molecular systems and fluid states. In ionic -crystals the symmetry around each ion and the distance between them -are such that the core-shell model is sufficiently stable. But to be -applicable to molecular/covalent systems the Drude model includes two -important features: - -#. The possibility to thermostat the additional degrees of freedom associated with the induced dipoles at very low temperature, in terms of the reduced coordinates of the Drude particles with respect to their cores. This makes the trajectory close to that of relaxed induced dipoles. -#. The Drude dipoles on covalently bonded atoms interact too strongly due to the short distances, so an atom may capture the Drude particle (shell) of a neighbor, or the induced dipoles within the same molecule may align too much. To avoid this, damping at short of the interactions between the point charges composing the induced dipole can be done by :ref:`Thole ` functions. +"charges on a spring": the core-shell model and the Drude model. +Although the basic idea is the same, the core-shell model is normally +used for ionic/crystalline materials, whereas the Drude model is +normally used for molecular systems and fluid states. In ionic crystals +the symmetry around each ion and the distance between them are such that +the core-shell model is sufficiently stable. But to be applicable to +molecular/covalent systems the Drude model includes two important +features: + +#. The possibility to thermostat the additional degrees of freedom + associated with the induced dipoles at very low temperature, in terms + of the reduced coordinates of the Drude particles with respect to + their cores. This makes the trajectory close to that of relaxed + induced dipoles. +#. The Drude dipoles on covalently bonded atoms interact too strongly + due to the short distances, so an atom may capture the Drude particle + (shell) of a neighbor, or the induced dipoles within the same + molecule may align too much. To avoid this, damping at short range + of the interactions between the point charges composing the induced + dipole can be done by :ref:`Thole ` functions. ---------- **Preparation of the data file** The data file is similar to a standard LAMMPS data file for -*atom_style full*. The DPs and the *harmonic bonds* connecting them -to their DC should appear in the data file as normal atoms and bonds. +:doc:`atom_style full `. The DPs and the :doc:`harmonic +bonds ` connecting them to their DC should appear in the +data file as normal atoms and bonds. You can use the *polarizer* tool (Python script distributed with the DRUDE package) to convert a non-polarizable data file (here @@ -244,9 +268,10 @@ The input file should now be ready for use! You will notice that the global temperature *thermo_temp* computed by LAMMPS is not 300. K as wanted. This is because LAMMPS treats DPs as -standard atoms in his default compute. If you want to output the +standard atoms in its default compute. If you want to output the temperatures of the DC-DP pair centers of mass and of the DPs relative -to their DCs, you should use the :doc:`compute temp_drude ` +to their DCs, you should use the :doc:`compute temp_drude +` .. code-block:: LAMMPS diff --git a/doc/src/Howto_granular.rst b/doc/src/Howto_granular.rst index b0c801be112..57bd7ea2c17 100644 --- a/doc/src/Howto_granular.rst +++ b/doc/src/Howto_granular.rst @@ -1,9 +1,9 @@ Granular models =============== -Granular system are composed of spherical particles with a diameter, -as opposed to point particles. This means they have an angular -velocity and torque can be imparted to them to cause them to rotate. +Granular systems are composed of spherical particles with a diameter, as +opposed to point particles. This means they have an angular velocity +and torque can be imparted to them to cause them to rotate. To run a simulation of a granular model, you will want to use the following commands: @@ -16,12 +16,13 @@ This compute * :doc:`compute erotate/sphere ` -calculates rotational kinetic energy which can be :doc:`output with thermodynamic info `. -The compute +calculates rotational kinetic energy which can be :doc:`output with +thermodynamic info `. The compute * :doc:`compute fabric ` -calculates various versions of the fabric tensor for granular and non-granular pair styles. +calculates various versions of the fabric tensor for granular and +non-granular pair styles. Use one of these 4 pair potentials, which compute forces and torques between interacting pairs of particles: diff --git a/doc/src/Howto_manifold.rst b/doc/src/Howto_manifold.rst index 67c9d70ea62..10491b5f3d3 100644 --- a/doc/src/Howto_manifold.rst +++ b/doc/src/Howto_manifold.rst @@ -23,7 +23,7 @@ to the relevant fixes. +----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | dumbbell | a A B c | -( x\^2 + y\^2 ) + (a\^2 - z\^2/c\^2) \* ( 1 + (A\*sin(B\*z\^2))\^4) = 0 | A dumbbell | +----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| ellipsoid | a b c | (x/a)\^2 + (y/b)\^2 + (z/c)\^2 = 0 | An ellipsoid | +| ellipsoid | a b c | (x/a)\^2 + (y/b)\^2 + (z/c)\^2 - 1 = 0 | An ellipsoid | +----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | gaussian_bump | A l rc1 rc2 | if( x < rc1) -z + A \* exp( -x\^2 / (2 l\^2) ); else if( x < rc2 ) -z + a + b\*x + c\*x\^2 + d\*x\^3; else z | A Gaussian bump at x = y = 0, smoothly tapered to a flat plane z = 0. | +----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/src/Howto_moltemplate.rst b/doc/src/Howto_moltemplate.rst index cd5a1fb1008..4a5d93c02a9 100644 --- a/doc/src/Howto_moltemplate.rst +++ b/doc/src/Howto_moltemplate.rst @@ -134,7 +134,7 @@ master file (``solv_01.lt``) follows: timestep \$\{ts\} fix NPT all npt temp \$\{temp\} \$\{temp\} \$\{tcouple\} iso \$p \$p \$\{pcouple\} velocity all create \$\{temp\} 858096 dist gaussian - # Short runs to update the PPPM settings as the box shinks. + # Short runs to update the PPPM settings as the box shrinks. run \$\{equi\} post no run \$\{equi\} post no run \$\{equi\} post no diff --git a/doc/src/Howto_output.rst b/doc/src/Howto_output.rst index 6fcd36ab56c..30c8d1b8c0a 100644 --- a/doc/src/Howto_output.rst +++ b/doc/src/Howto_output.rst @@ -385,10 +385,10 @@ Every :doc:`compute ` in LAMMPS produces either global or per-atom or local or per-grid values. The values can be scalars or vectors or arrays of data. These values can be output using the other commands described in this section. The page for each compute command -describes what it produces. Computes that produce per-atom or local -or per-grid values have the word "atom" or "local" or "grid as the -last word in their style name. Computes without the word "atom" or -"local" or "grid" produce global values. +describes what it produces. Computes that produce per-atom or local or +per-grid values have the word "atom" or "local" or "grid" as the last +word in their style name. Computes without the word "atom" or "local" +or "grid" produce global values. .. _fix: diff --git a/doc/src/Howto_peri.rst b/doc/src/Howto_peri.rst index fa299e7f844..8acce226858 100644 --- a/doc/src/Howto_peri.rst +++ b/doc/src/Howto_peri.rst @@ -186,7 +186,7 @@ Linear Peridynamic Solid (LPS) Model We summarize the linear peridynamic solid (LPS) material model. For more on this model, the reader is referred to :ref:`(Silling 2007) `. This model is a nonlocal analogue to a classical -linear elastic isotropic material. The elastic properties of a a +linear elastic isotropic material. The elastic properties of a classical linear elastic isotropic material are determined by (for example) the bulk and shear moduli. For the LPS model, the elastic properties are analogously determined by the bulk and shear moduli, @@ -558,7 +558,7 @@ both the position and velocity of the particle are stored explicitly. The velocity-Verlet scheme is generally expressed in three steps. In :ref:`Algorithm 1 `, :math:`\rho_i` denotes the mass density of a particle and :math:`\widetilde{\textbf{f}}_i^n` -denotes the the net force density on particle :math:`i` at timestep +denotes the net force density on particle :math:`i` at timestep :math:`n`. The LAMMPS command :doc:`fix nve ` performs a velocity-Verlet integration. @@ -818,7 +818,7 @@ the LAMMPS :doc:`boundary ` command has been set. If a particle drifts outside the simulation box during the course of a simulation, it is called *lost*. -As an option of the :doc:`themo_modify ` command of +As an option of the :doc:`thermo_modify ` command of LAMMPS, the lost keyword determines whether LAMMPS checks for lost atoms each time it computes thermodynamics and what it does if atoms are lost. If the value is *ignore*, LAMMPS does not check for lost atoms. If diff --git a/doc/src/Howto_triclinic.rst b/doc/src/Howto_triclinic.rst index 24ac66e1034..3d405edbe4d 100644 --- a/doc/src/Howto_triclinic.rst +++ b/doc/src/Howto_triclinic.rst @@ -98,7 +98,7 @@ keywords for outputting the various parameters that define the size and shape of orthogonal, restricted triclinic, and general triclinic simulation boxes. -For orthogonal boxes there 6 thermo keywords (xlo,ylo,zlo) and +For orthogonal boxes there are 6 thermo keywords (xlo,ylo,zlo) and (xhi,yhi,zhi). For restricted triclinic boxes there are 9 thermo keywords for diff --git a/doc/src/Howto_viz.rst b/doc/src/Howto_viz.rst index 517fc025484..8172fdcaae6 100644 --- a/doc/src/Howto_viz.rst +++ b/doc/src/Howto_viz.rst @@ -238,13 +238,13 @@ example to color atoms of type 1 in gray and type 2 in white, you would use: dump_modify img acolor 1 gray acolor 2 white -There are 144 predefined colors, but you can add new colors or modify +There are 140 predefined colors, but you can add new colors or modify existing ones, too, with the *dump_modify color* keyword. The *color* keyword is followed by the name of the color and the intensity of the red, green, and blue components (R/G/B) in a range from 0.0 to 1.0. Here is an example to create eight new color names followed by the *acolor* keyword with a wildcard to replace the default map of six atom colors -with a new map of the either newly defined colors. +with a new map of the eight newly defined colors. .. code-block:: LAMMPS @@ -275,7 +275,7 @@ the charge: .. code-block:: LAMMPS dump viz peptide image 1000 image-*.png q type size 600 600 zoom 2.0 - dump_modify amap -1.0 1.0 ca 0 3 min blue 0.0 white max red + dump_modify viz amap -1.0 1.0 ca 0 3 min blue 0.0 white max red .. |colors1| image:: img/colors-default.png @@ -454,13 +454,14 @@ lines can be transferred to the cut-n-paste buffer of the windowing system and pasted into the input file and then further adjusted. Once the input contains a :doc:`dump image ` command, -LAMMPS-GUI will notice when a new image has been created and load it -into "Slide Show Dialog". This streamlines the process of building more -complex visualizations once you have copied it into the input since you -have editor and image viewer as part of the same program and can quickly -start and stop LAMMPS with a mouse click or keystroke. A large part of -the visualization examples on shown in this Howto page have been created -this way. +LAMMPS-GUI notices when a new image has been created and loads it into +the "Slide Show Dialog". This streamlines the process of building more +complex visualizations once you have copied an initial draft created +with the "Image Viewer Dialog" into the input since you have editor and +image viewer as part of the same program and can quickly start and stop +LAMMPS with a mouse click or keystroke. A large part of the +visualization examples shown in this Howto page have been created this +way. .. |gui1| image:: JPG/lammps-gui-main.png :width: 38% @@ -477,14 +478,14 @@ Visualizing systems using potentials with implicit bonds -------------------------------------------------------- There are several pair styles available in LAMMPS where the bond -information is not taken from from the bond topology in a data file but -the potentials first determine a "bond-order" parameter for pairs of -atoms and - depending on the value of that parameter - apply forces for -bonded interactions. This applies to :doc:`ReaxFF `, -:doc:`REBO and AIREBO `, :doc:`BOP `, and several -others pair styles. These implicit bonds will not be shown by -:doc:`dump image ` since its mechanism for displaying bonds -relies on explicit bonds being present in the bond topology. +information is not taken from the bond topology in a data file but the +potentials first determine a "bond-order" parameter for pairs of atoms +and - depending on the value of that parameter - apply forces for bonded +interactions. This applies to :doc:`ReaxFF `, :doc:`REBO +and AIREBO `, :doc:`BOP `, and several others +pair styles. These implicit bonds will not be shown by :doc:`dump image +` since its mechanism for displaying bonds relies on +explicit bonds being present in the bond topology. One can hide the fact that there are no bonds by setting the atom radii to the covalent radii of the corresponding elements (see leftmost @@ -501,7 +502,7 @@ currently three approaches to make those bonds visible. the computation of the model. This is currently only available for ReaxFF by using :doc:`fix reaxff/bonds `. -#. Use the *autobonds* keyword of :doc:`dump image ` to +#. Use the *autobond* keyword of :doc:`dump image ` to approximate the bonds based on a simple distance heuristic. This is similar to the *Dynamic Bonds* representation in `VMD `_. How accurate this option @@ -516,18 +517,18 @@ currently three approaches to make those bonds visible. hydrogen-hydrogen distance for hydrogen atoms bound to the same atom (e.g. in water, methane or hydrocarbon chains). -#. Use use a combination of :doc:`fix bond/break ` - and :doc:`fix bond/create/angle ` with :doc:`bond - style zero ` to dynamically create and remove bonds that - do not add any forces. This also requires to tell the neighbor list - code to not treat any pairs of atoms as special neighbors (otherwise - the corresponding pairs of atoms could be excluded from the neighbor - list and thus the forces computed by the pair style incorrect) - through using the :doc:`special_bonds ` command. - Unlike the two other options which were recently added when this - document when was written, this method also works with older versions - of LAMMPS. Here is an example of the necessary commands for a carbon - nanotube (that is modeled with AIREBO): +#. Use a combination of :doc:`fix bond/break ` and + :doc:`fix bond/create/angle ` with :doc:`bond style + zero ` to dynamically create and remove bonds that do not + add any forces. This also requires to tell the neighbor list code to + not treat any pairs of atoms as special neighbors (otherwise the + corresponding pairs of atoms could be excluded from the neighbor list + and thus the forces computed by the pair style incorrect) through + using the :doc:`special_bonds ` command. Unlike the + two other options, which were added more recently, this method also + works with older versions of LAMMPS. Here is an example of the + necessary commands for a carbon nanotube modeled with the AIREBO + potential: .. code-block:: LAMMPS @@ -910,7 +911,7 @@ velocities: fix dipole all graphics/objects 1 arrow 1 v_dip1x v_dip1y v_dip1z v_dip2x v_dip2y v_dip2z 0.3 0.2 dump viz all image 100 image-*.png element type size 600 600 zoom 1.3 view 70 20 shiny 0.1 & - bond atom 0.2box yes 0.025 axes no 0.0 0.0 center s 0.5 0.5 0.5 fsaa yes & + bond atom 0.2 box yes 0.025 axes no 0.0 0.0 center s 0.5 0.5 0.5 fsaa yes & fix dipole const 0 0 fix vec const 0 0 fix vel const 0 0 ssao yes 315465 0.8 dump_modify viz pad 6 boxcolor white backcolor gray element O H bdiam 1 0.2 & adiam 1 0.5 adiam 2 0.3 acolor 1 silver acolor 2 red fcolor vec goldenrod & diff --git a/doc/src/Intro_authors.rst b/doc/src/Intro_authors.rst index ad38051e4c6..7f9cba350a2 100644 --- a/doc/src/Intro_authors.rst +++ b/doc/src/Intro_authors.rst @@ -109,7 +109,7 @@ general-purpose as it is without their expertise and efforts. * Reese Jones (Sandia) and colleagues, ATC package for atom/continuum coupling * Christoph Kloss (DCS Computing), LIGGGHTS code for granular materials, built on top of LAMMPS * Rudra Mukherjee (JPL), POEMS package for articulated rigid body motion -* Trung Ngyuen (U Chicago), GPU, RIGID, BODY, and DIELECTRIC packages +* Trung Nguyen (U Chicago), GPU, RIGID, BODY, and DIELECTRIC packages * Mike Parks (Sandia), PERI package for Peridynamics * Roy Pollock (LLNL), Ewald and PPPM solvers * Julien Tranchida (CEA Cadarache), SPIN package diff --git a/doc/src/Intro_citing.rst b/doc/src/Intro_citing.rst index 8b906bb7259..6878cbd4cfe 100644 --- a/doc/src/Intro_citing.rst +++ b/doc/src/Intro_citing.rst @@ -6,7 +6,7 @@ Core Algorithms The paper mentioned below is the best overview of LAMMPS, but there are also publications describing particular models or algorithms implemented -in LAMMPS or complementary software that is has interfaces to. Please +in LAMMPS or complementary software that it has interfaces to. Please see below for how to cite contributions to LAMMPS. .. _lammps_paper: diff --git a/doc/src/Intro_nonfeatures.rst b/doc/src/Intro_nonfeatures.rst index f3d104b0a94..6fe94c2f858 100644 --- a/doc/src/Intro_nonfeatures.rst +++ b/doc/src/Intro_nonfeatures.rst @@ -81,8 +81,8 @@ Here are suggestions on how to perform these tasks: on the LAMMPS homepage lists some external packages for analysis of MD simulation data, including data produced by LAMMPS. -* **Visualization:** LAMMPS can produce NETPBM, JPG, or PNG format - snapshot images on-the-fly via its :doc:`dump image ` +* **Visualization:** LAMMPS can produce NETPBM, TGA, JPG, or PNG + format snapshot images on-the-fly via its :doc:`dump image ` command and pass them to an external program, `FFmpeg `_, to generate movies from them. The :ref:`LAMMPS-GUI tool ` has a *Snapshot Image Viewer* @@ -90,7 +90,7 @@ Here are suggestions on how to perform these tasks: visualization settings interactively. It also has a *Slide Show* feature where images created by :doc:`dump image ` are collected during a simulation and can be animated interactively or - exported to a movie with FFmpeg. + exported to a movie with FFmpeg or ImageMagick. For high-quality, interactive visualization, there are many excellent and free tools available. See the `Visualization Tools @@ -113,4 +113,4 @@ Here are suggestions on how to perform these tasks: setup, analysis, plotting, and visualization (via OpenGL) for LAMMPS simulations. It thus provides some functionality for several of the above bullets. Pizza.py is written in `Python `_ - and is available for download from `this page `_. + and is available for download from https://lammps.github.io/pizza/. diff --git a/doc/src/Intro_overview.rst b/doc/src/Intro_overview.rst index 0f777a9adc3..9511873f4c0 100644 --- a/doc/src/Intro_overview.rst +++ b/doc/src/Intro_overview.rst @@ -37,7 +37,7 @@ executables are provided. LAMMPS is designed to be easy to modify or extend with new capabilities, such as new force fields, atom types, boundary conditions, or -diagnostics. See the :doc:`Modify` section of for more details. +diagnostics. See the :doc:`Modify` section for more details. In the most general sense, LAMMPS integrates Newton's equations of motion for a collection of interacting particles. A single particle can diff --git a/doc/src/Intro_portability.rst b/doc/src/Intro_portability.rst index b505578be49..292537ff1a7 100644 --- a/doc/src/Intro_portability.rst +++ b/doc/src/Intro_portability.rst @@ -115,19 +115,28 @@ In addition to using automated tests, code contributed to LAMMPS is subject to a code review by core LAMMPS developers (that includes contributions by the core LAMMPS developers themselves). -we also make use of a number static code analysis tools for maintaining -and improving the quality of the LAMMPS source code through tools like -`Coverity SCAN `_, `CodeQL -`_, `Clang Static Analyzer -`_, `Clang-Tidy -`_ and simply looking at -compiler warnings. +We make use of a number of static code analysis tools for maintaining +and improving the quality of the LAMMPS source code. Tools used +include: + +- `Coverity SCAN `_ +- `CodeQL `_ +- `Clang Static Analyzer `_ +- `Clang-Tidy `_ +- Enabling and looking at compiler warnings CodeQL alerts for the ``develop`` branch of LAMMPS can be seen at -https://github.com/lammps/lammps/security/code-scanning and static code +https://github.com/lammps/lammps/security/code-scanning. Static code analysis reports for the ``develop`` branch from the clang tools are available at https://download.lammps.org/analysis/ +We currently also request code reviews from `GitHub Copilot +`_ to lower the code review +workload for the LAMMPS developers. The LAMMPS git repository includes +specific instructions for Copilot to particularly look for compliance of +submitted pull requests with LAMMPS coding and documentation +conventions. + A discussion of software engineering methods applied to LAMMPS over time can be found in the paper `LAMMPS: A Case Study For Applying Modern Software Engineering to an Established Research Software Package, diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 8e2636b2f8a..d0dcdbe4be6 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -367,14 +367,15 @@ BROWNIAN package **Contents:** -This package provides :doc:`fix brownian, fix brownian/sphere, and -fix brownian/asphere ` as well as -:doc:`fix propel/self ` which allow to do Brownian -Dynamics time integration of point, spherical and aspherical particles -and also support self-propelled particles. +This package provides :doc:`fix brownian, fix brownian/sphere, and fix +brownian/asphere ` as well as :doc:`fix propel/self +` which allow performing Brownian Dynamics time +integration of point, spherical and aspherical particles and also +support self-propelled particles. -**Authors:** Sam Cameron (University of Bristol), Arthur Straube (Zuse Institute Berlin), -Stefan Paquay (while at Brandeis University) (initial version of fix propel/self) +**Authors:** Sam Cameron (University of Bristol), Arthur Straube (Zuse +Institute Berlin), Stefan Paquay (while at Brandeis University) (initial +version of fix propel/self) .. versionadded:: 14May2021 @@ -1084,7 +1085,7 @@ GRAPHICS package Dump styles :doc:`image and movie `, supporting classes for rendering images and fonts, several fixes for adding graphics objects to visualizations, and the region2vmd command for exporting visualizations -of regions scripted graphics in VMD. +of regions as scripted graphics in VMD. **Supporting info:** @@ -1408,7 +1409,8 @@ Ontario). **Install:** -The LATBOLTZ package requires that LAMMPS is build in :ref:`MPI parallel mode `. +The LATBOLTZ package requires that LAMMPS is built in :ref:`MPI parallel +mode `. **Supporting info:** @@ -1560,15 +1562,16 @@ MBX Package **Contents** -The pair_style mbx command implements the MBX library for -MB-pol and MB-nrg data-driven many-body potential energy functions. MBX -is called using :doc:`pair_style mbx ` command, which -allow for MB-nrg potentials such as MB-pol to be used in LAMMPS. -For more information on MBX, see the `MBX library `_ website. +The pair_style mbx command implements the MBX library for MB-pol and +MB-nrg data-driven many-body potential energy functions. MBX is called +using :doc:`pair_style mbx ` command, which allows for MB-nrg +potentials such as MB-pol to be used in LAMMPS. For more information on +MBX, see the `MBX library `_ website. -**Authors:** The `MBX library `_ is developed -by the Paesani group at the University of California, San Diego. Major contributors -include: Marc Riera, Christopher Knight, Ethan Bull-Vulpe, and Henry Agnew. +**Authors:** The `MBX library `_ is +developed by the Paesani group at the University of California, San +Diego. Major contributors include: Marc Riera, Christopher Knight, Ethan +Bull-Vulpe, and Henry Agnew. .. versionadded:: 11Feb2026 @@ -1797,10 +1800,10 @@ ML-HDNNP package **Contents:** -A :doc:`pair_style hdnnp ` command which allows to use -high-dimensional neural network potentials (HDNNPs), a form of machine learning -potentials. HDNNPs must be carefully trained prior to their application in a -molecular dynamics simulation. +A :doc:`pair_style hdnnp ` command which allows the use of +high-dimensional neural network potentials (HDNNPs), a form of machine +learning potentials. HDNNPs must be carefully trained prior to their +application in a molecular dynamics simulation. .. _n2p2: https://github.com/CompPhysVienna/n2p2 @@ -2745,24 +2748,26 @@ SCAFACOS package **Contents:** -A KSpace style which wraps the `ScaFaCoS Coulomb solver library `_ to compute long-range Coulombic +A KSpace style which wraps the `ScaFaCoS Coulomb solver library +`_ to compute long-range Coulombic interactions. -To use this package you must have the ScaFaCoS library available on -your system. +To use this package you must have the ScaFaCoS library available on your +system. **Author:** Rene Halver (JSC) wrote the scafacos LAMMPS command. ScaFaCoS itself was developed by a consortium of German research -facilities with a BMBF (German Ministry of Science and Education) -funded project in 2009-2012. Participants of the consortium were the -Universities of Bonn, Chemnitz, Stuttgart, and Wuppertal as well as -the Forschungszentrum Juelich. +facilities with a BMBF (German Ministry of Science and Education) funded +project in 2009-2012. Participants of the consortium were the +Universities of Bonn, Chemnitz, Stuttgart, and Wuppertal as well as the +Forschungszentrum Juelich. **Install:** -This package has :ref:`specific installation instructions ` on the :doc:`Build extras ` page. -The SCAFACOS package requires that LAMMPS is build in :ref:`MPI parallel mode `. +This package has :ref:`specific installation instructions ` on +the :doc:`Build extras ` page. The SCAFACOS package +requires that LAMMPS is built in :ref:`MPI parallel mode `. **Supporting info:** @@ -2981,7 +2986,7 @@ VORONOI package A compute command which calculates the Voronoi tesselation of a collection of atoms by wrapping the `Voro++ library `_. This can be used to calculate the -local volume or each atoms or its near neighbors. +local volume of atoms or their near neighbors. To use this package you must have the Voro++ library available on your system. diff --git a/doc/src/Run_formats.rst b/doc/src/Run_formats.rst index 60b391a2c1f..f85a2456206 100644 --- a/doc/src/Run_formats.rst +++ b/doc/src/Run_formats.rst @@ -29,7 +29,7 @@ symbols and more. Modern text often uses `UTF-8 character encoding `_ instead. This encoding is a way to represent many more different characters as defined by the Unicode -standard. UFT-8 is compatible with ASCII, since the first 128 values +standard. UTF-8 is compatible with ASCII, since the first 128 values are identical with the ASCII encoding. It is important to note, however, that there are Unicode characters that *look* similar to ASCII characters, but have a different binary representation. As a general @@ -175,8 +175,9 @@ used as a portable alternatives to a :doc:`binary restart file :doc:`command line `. Data files have a header section at the very beginning of the file and -multiple titled sections such as "Atoms", Masses", "Pair Coeffs", and so -on. Header keywords can only be used *before* the first title section. +multiple titled sections such as "Atoms", "Masses", "Pair Coeffs", and +so on. Header keywords can only be used *before* the first title +section. The data file **always** starts with a "title" line, which will be **ignored** by LAMMPS. Omitting the title line can lead to unexpected diff --git a/doc/src/Run_output.rst b/doc/src/Run_output.rst index bf8e2de4072..f5cb8d36723 100644 --- a/doc/src/Run_output.rst +++ b/doc/src/Run_output.rst @@ -232,7 +232,7 @@ input failed. Example: Four lines ^^^^^^^^^^ -The three line output is expanded to four lines, if the the input is +The three line output is expanded to four lines, if the input is modified through input pre-processing, e.g. when substituting variables. Now the last command is printed once in the original form and a second time after substitutions are applied. The caret character diff --git a/doc/src/Run_windows.rst b/doc/src/Run_windows.rst index 6f9e6a5a7e9..5e4c955e95c 100644 --- a/doc/src/Run_windows.rst +++ b/doc/src/Run_windows.rst @@ -64,9 +64,9 @@ with MPI using something like: MPI parallelization will work for *all* functionality in LAMMPS and in many cases the MPI parallelization is more efficient than -multi-threading since LAMMPS was designed from ground up for MPI +multi-threading since LAMMPS was designed from the ground up for MPI parallelization using domain decomposition. Multi-threading is only available for selected styles and implemented on top of the MPI parallelization. Multi-threading is most useful for systems with large -load imbalances when using domain decomposition and a smaller number -of threads (<= 8). +load imbalances when using domain decomposition and a smaller number of +threads (<= 8). diff --git a/doc/src/Speed_compare.rst b/doc/src/Speed_compare.rst index 1d613f2b6d8..f1044d0d145 100644 --- a/doc/src/Speed_compare.rst +++ b/doc/src/Speed_compare.rst @@ -54,7 +54,7 @@ section below for examples where this has been done. (desktop) GPUs. Using lower performance GPUs (e.g. on laptops) may result in a slowdown instead. * For the GPU package, specifically when running in parallel with MPI, - if it often more efficient to exclude the PPPM kspace style from GPU + it is often more efficient to exclude the PPPM kspace style from GPU acceleration and instead run it - concurrently with a GPU accelerated pair style - on the CPU. This can often be easily achieved with placing a *suffix off* command before and a *suffix on* command after the diff --git a/doc/src/Speed_gpu.rst b/doc/src/Speed_gpu.rst index c90e3fcc5e5..eccc9c8d76d 100644 --- a/doc/src/Speed_gpu.rst +++ b/doc/src/Speed_gpu.rst @@ -185,7 +185,7 @@ Guidelines for best performance """"""""""""""""""""""""""""""" * Using multiple MPI tasks (2-10) per GPU will often give the best - performance, as allowed my most multicore CPU/GPU configurations. + performance, as allowed by most multicore CPU/GPU configurations. Using too many MPI tasks will result in worse performance due to growing overhead with the growing number of MPI tasks. * If the number of particles per MPI task is small (e.g. 100s of diff --git a/doc/src/Speed_intel.rst b/doc/src/Speed_intel.rst index 78a88f44070..850a8229fe7 100644 --- a/doc/src/Speed_intel.rst +++ b/doc/src/Speed_intel.rst @@ -214,10 +214,10 @@ directory: .. code-block:: bash - Makefile.intel_cpu_intelmpi # Intel Compiler, Intel MPI, No Offload - Makefile.knl # Intel Compiler, Intel MPI, No Offload - Makefile.intel_cpu_mpich # Intel Compiler, MPICH, No Offload - Makefile.intel_cpu_openpmi # Intel Compiler, OpenMPI, No Offload + Makefile.intel_cpu_intelmpi # Intel Compiler, Intel MPI, No Offload + Makefile.knl # Intel Compiler, Intel MPI, No Offload + Makefile.intel_cpu_mpich # Intel Compiler, MPICH, No Offload + Makefile.intel_cpu_openmpi # Intel Compiler, OpenMPI, No Offload Makefile.intel_co-processor # Intel Compiler, Intel MPI, Offload Makefile.knl is identical to Makefile.intel_cpu_intelmpi except that diff --git a/doc/src/Speed_omp.rst b/doc/src/Speed_omp.rst index 906acf3ce8d..00c9a8abbc8 100644 --- a/doc/src/Speed_omp.rst +++ b/doc/src/Speed_omp.rst @@ -142,16 +142,16 @@ circumstances: where MPI parallelism is maxed out. For example, this can happen when using the :doc:`PPPM solver ` for long-range electrostatics on large numbers of nodes. The scaling of the KSpace - calculation (see the :doc:`kspace_style ` command) becomes - the performance-limiting factor. Using multi-threading allows less - MPI tasks to be invoked and can speed-up the long-range solver, while - increasing overall performance by parallelizing the pairwise and - bonded calculations via OpenMP. Likewise additional speedup can be + calculation (see the :doc:`kspace_style ` command) + becomes the performance-limiting factor. Using multi-threading allows + less MPI tasks to be invoked and can speed-up the long-range solver, + while increasing overall performance by parallelizing the pairwise and + bonded calculations via OpenMP. Likewise, additional speedup can sometimes be achieved by increasing the length of the Coulombic cutoff and thus reducing the work done by the long-range solver. Using the :doc:`run_style verlet/split ` command, which is compatible - with the OPENMP package, is an alternative way to reduce the number - of MPI tasks assigned to the KSpace calculation. + with the OPENMP package, is an alternative way to reduce the number of + MPI tasks assigned to the KSpace calculation. Additional performance tips are as follows: diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index c7ae09a0d2d..7382309cf69 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -709,7 +709,7 @@ the same ``LAMMPS_CACHING_DIR``. This script does the following: ``pip`` and ``git`` #. Start a simple local HTTP server using Python to host files for CMake -Afterwards, it will print out instruction on how to modify the CMake +Afterwards, it will print out instructions on how to modify the CMake commands to make sure it uses the local HTTP server. To undo the environment changes and shutdown the local HTTP server, @@ -780,9 +780,9 @@ The phonon subdirectory contains a post-processing tool, *phana*, useful for analyzing the output of the :doc:`fix phonon ` command in the PHONON package. -See the README file for instruction on building the tool and what -library it needs. And see the examples/PACKAGES/phonon directory -for example problems that can be post-processed with this tool. +See the README file for instructions on building the tool and what +library it needs. And see the examples/PACKAGES/phonon directory for +example problems that can be post-processed with this tool. This tool was written by Ling-Ti Kong at Shanghai Jiao Tong University. @@ -1084,10 +1084,11 @@ tabulate tool .. versionadded:: 22Dec2022 -The ``tabulate`` folder contains Python scripts scripts to generate and -visualize tabulated potential files for LAMMPS. The bulk of the code is in the -``tabulate`` module in the ``tabulate.py`` file. Some example files -demonstrating its use are included. See the README file for more information. +The ``tabulate`` folder contains Python scripts to generate and +visualize tabulated potential files for LAMMPS. The bulk of the code is +in the ``tabulate`` module in the ``tabulate.py`` file. Some example +files demonstrating its use are included. See the README file for more +information. ---------- @@ -1096,7 +1097,7 @@ demonstrating its use are included. See the README file for more information. tinker tool -------------- -The ``tinker`` folder contains Python scripts scripts to convert Tinker input +The ``tinker`` folder contains Python scripts to convert Tinker input files to LAMMPS. See the README file for more information. @@ -1115,7 +1116,7 @@ using `valgrind's `_ ` `memcheck tool `_ to search for memory access violation and memory leaks. These suppressions are automatically invoked when running tests through CMake "ctest -T memcheck". See the -instruction in the ``README`` file to add these suppressions when using +instructions in the ``README`` file to add these suppressions when using valgrind with LAMMPS or other programs. ---------- diff --git a/doc/src/compute_hbond_local.rst b/doc/src/compute_hbond_local.rst index 1d4c05ac65e..9bf4cbe6aa4 100644 --- a/doc/src/compute_hbond_local.rst +++ b/doc/src/compute_hbond_local.rst @@ -187,7 +187,7 @@ timestep to the next. The output for *dist* and *hdist* will be in distance :doc:`units `. The output for *angle* will be in degrees. The output for -*strength* will be in energy :doc:`units `. +*ehb* will be in energy :doc:`units `. ----------- diff --git a/doc/src/compute_sna_atom.rst b/doc/src/compute_sna_atom.rst index 2f8c4c4f5d5..d80f779f1a4 100644 --- a/doc/src/compute_sna_atom.rst +++ b/doc/src/compute_sna_atom.rst @@ -22,13 +22,10 @@ compute snap command compute sna/grid command ======================== -compute sna/grid/kk command -=========================== - compute sna/grid/local command ============================== -Accelerator Variants: *sna/grid/local/kk* +Accelerator Variants: *sna/grid/kk*, *sna/grid/local/kk* Syntax """""" diff --git a/doc/src/dihedral_fourier.rst b/doc/src/dihedral_fourier.rst index 287ea5524ac..a8d3a392dba 100644 --- a/doc/src/dihedral_fourier.rst +++ b/doc/src/dihedral_fourier.rst @@ -6,7 +6,7 @@ dihedral_style fourier command ============================== -Accelerator Variants: *fourier/intel*, *fourier/omp* +Accelerator Variants: *fourier/intel*, *fourier/kk*, *fourier/omp* Syntax """""" diff --git a/doc/src/dump_image.rst b/doc/src/dump_image.rst index f922e761cc5..8bb387be10a 100644 --- a/doc/src/dump_image.rst +++ b/doc/src/dump_image.rst @@ -126,7 +126,7 @@ Syntax dump_modify dump-ID keyword values ... * these keywords apply only to the *image* and *movie* styles and are documented on this page -* keyword = *acolor* or *adiam* or *amap* or *gmap* or *atrans* or *backcolor* or *backcolor2* or *bcolor* or *bdiam* or *btrans* or *bitrate* or *boxcolor* or *color* or *framerate* or *axestrans* or *boxtrans* or *subboxtrans* +* keyword = *acolor* or *adiam* or *amap* or *gmap* or *atrans* or *backcolor* or *backcolor2* or *bcolor* or *bdiam* or *btrans* or *bitrate* or *boxcolor* or *color* or *framerate* or *axestrans* or *boxtrans* or *subboxtrans* or *ccolor* or *ctrans* or *fcolor* or *ftrans* * see the :doc:`dump modify ` doc page for more general keywords .. parsed-literal:: @@ -163,7 +163,7 @@ Syntax *backcolor* arg = color color = name of color for background *backcolor2* arg = color - color = name of second color for vertical background gradiant. "none" to disable gradient + color = name of second color for vertical background gradient. "none" to disable gradient *bcolor* args = type color type = bond type (numeric or type label) or range of numeric types (see below) color = name of color or color1/color2/... @@ -393,7 +393,7 @@ discretely so that the value of -3.2 is "orange". If "vx", for example, is used as the *diameter* setting, then the atom will be rendered using the x-component of its velocity as the -diameter. If the per-atom value <= 0.0, them the atom will not be +diameter. If the per-atom value <= 0.0, then the atom will not be drawn. Note that finite-size spherical particles, as defined by :doc:`atom_style sphere ` define a per-particle radius or diameter, which can be used as the *diameter* setting. @@ -500,15 +500,14 @@ spheres, the same as if they were regular atoms. added *index* and *atom* color styles -The there are currently three supported settings for the *color* value: -*type*, *index*, or *atom*. With the *type* setting the line particles -will be colored according to the atom type of the particle. With the -*index* setting the coloring follows the line index instead. With the -*atom* setting, the color follows the coloring selected for coloring -atoms (including using color maps). For *type* and *index* settings, -the value is mapped to the colors of atom types thus the coloring style -for atoms **must** be set to *type*. The list of colors is by default -the list of atom type colors as follows: +There are currently three supported settings for the *color* value: +*type*, *index*, or *atom*. With the *type* setting the line segment +particles will be colored according to the atom type of the particle. +With the *index* setting, colors from the list of available per-atom +type colors are assigned to the line particles in a non-deterministic +round-robin fashion. With the *atom* setting, the color follows the +coloring selected for coloring atoms (including using color maps). The +list of atom type colors is by default as follows: * type 1 = red * type 2 = green @@ -541,15 +540,14 @@ be drawn as spheres, the same as if they were regular atoms. added *index* and *atom* color styles -The there are currently three supported settings for the *color* value: -*type*, *index*, or *atom*. With the *type* setting the triangles -will be colored according to the atom type of the particle. With the -*index* setting the coloring follows the triangle index instead. With the -*atom* setting, the color follows the coloring selected for coloring -atoms (including using color maps). For *type* and *index* settings, -the value is mapped to the colors of atom types thus the coloring style -for atoms **must** be set to *type*. The list of colors is by default -the list of atom type colors as follows: +There are currently three supported settings for the *color* value: +*type*, *index*, or *atom*. With the *type* setting the triangles will +be colored according to the atom type of the particle. With the *index* +setting, colors from the list of available per-atom type colors are +assigned to the triangulated particles in a non-deterministic +round-robin fashion. With the *atom* setting, the color follows the +coloring selected for coloring atoms (including using color maps). The +list of atom type colors is by default as follows: * type 1 = red * type 2 = green @@ -580,15 +578,14 @@ atoms. added *index* and *atom* color styles -The there are currently three supported settings for the *color* value: +There are currently three supported settings for the *color* value: *type*, *index*, or *atom*. With the *type* setting the ellipsoids will be colored according to the atom type of the particle. With the *index* -setting the coloring follows the ellipsoid index instead. With the -*atom* setting, the color follows the coloring selected for coloring -atoms (including using color maps). For *type* and *index* settings, -the value is mapped to the colors of atom types thus the coloring style -for atoms **must** be set to *type*. The list of colors is by default -the list of atom type colors as follows: +setting, colors from the list of available per-atom type colors are +assigned to the ellipsoid particles in a non-deterministic round-robin +fashion. With the *atom* setting, the color follows the coloring +selected for coloring atoms (including using color maps). The list of +atom type colors is by default as follows: * type 1 = red * type 2 = green @@ -651,15 +648,14 @@ parameters mean for each body style. added *atom* color style -The there are currently three supported settings for the *color* value: +There are currently three supported settings for the *color* value: *type*, *index*, or *atom*. With the *atom* setting, the color follows the coloring selected for coloring atoms (including using color maps). With the *type* setting the body particles will be colored according to -the atom type of the particle. With the *index* setting the coloring -follows the body index instead. For the *type* and *index* settings, -the value (type or index) is mapped to the colors of atom types thus -the coloring style for atoms **must** be set to *type*. The list of -colors is by default as follows: +the atom type of the particle. With the *index* setting, colors from +the list of available per-atom type colors are assigned to the body +particles in a non-deterministic round-robin fashion. The list of atom +type colors is by default as follows: * type 1 = red * type 2 = green @@ -792,7 +788,7 @@ center point in simulation space. The *up* keyword determines what direction in simulation space will be "up" in the image. Internally it is stored as a vector that is in the plane perpendicular to the view vector implied by the *theta* and -*pni* values, and which is also in the plane defined by the view +*phi* values, and which is also in the plane defined by the view vector and user-specified up vector. Thus this internal vector is computed from the user-specified *up* vector as @@ -831,8 +827,8 @@ green, and blue, respectively. The origin of these arrows will be offset from the lower left corner of the box by 10%. If *center* is set the origin of the arrows will be in the center of the box. If *lowerright* is set, the origin of the arrows will be offset by 20% of -the lower right corner of the box. If *upperleft* or *upperight* are set -the origin of the arrows will be placed similar to the lower corner +the lower right corner of the box. If *upperleft* or *upperright* are +set the origin of the arrows will be placed similar to the lower corner arrows, but offset by 20% from the top. The *length* setting determines how long the cylinders will be as a fraction of the respective box lengths. The *diam* setting determines their thickness as a fraction of @@ -1069,7 +1065,7 @@ graphics/labels ` to generate a colormap legend: dump_modify viz pad 6 boxcolor lightskyblue backcolor darkgray backcolor2 silver adiam * 1.2 # customize the color map using a continuous map with fractions - dump_modify viz amap 0.0 8 cf 0.0 6 min red 0.2 organge 0.4 green 0.6 darkcyan 0.8 blue max purple + dump_modify viz amap 0.0 8 cf 0.0 6 min red 0.2 orange 0.4 green 0.6 darkcyan 0.8 blue max purple This is an altered *dump_modify* command line to generate a sequential color map: @@ -1201,7 +1197,7 @@ floating point values between 0.0 and 1.0 inclusive or as a single 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. +pre-defined color names with new RGB values. ---------- @@ -1340,7 +1336,7 @@ The defaults for the dump image and dump movie keywords are as follows: * zoom = 1.0 * box = yes 0.02 * axes = no 0.0 0.0 -* subbox no 0.0 +* subbox = no 0.0 * shiny = 1.0 * ssao = no * fsaa = no diff --git a/doc/src/fix_bond_react.rst b/doc/src/fix_bond_react.rst index 0602c2ddfbd..ad1a95d53a1 100644 --- a/doc/src/fix_bond_react.rst +++ b/doc/src/fix_bond_react.rst @@ -436,15 +436,15 @@ provided on the :doc:`molecule ` command page. The map file is a text document with the following format: -A map file has a header and a body. The header of map file the -contains one mandatory keyword and five optional keywords. The +A map file has a header and a body. The header of the map file +contains one mandatory keyword and six optional keywords. The mandatory keyword is *equivalences*\ : .. parsed-literal:: N *equivalences* = # of atoms N in the reaction molecule templates -The optional keywords are *edgeIDs*\ , *wildcards*\ ,*deleteIDs*\ , +The optional keywords are *edgeIDs*\ , *wildcards*\ , *deleteIDs*\ , *createIDs*\ , *chiralIDs*\ , and *constraints*\ : .. parsed-literal:: @@ -456,7 +456,7 @@ The optional keywords are *edgeIDs*\ , *wildcards*\ ,*deleteIDs*\ , N *chiralIDs* = # of chiral centers N N *constraints* = # of reaction constraints N -The body of the map file contains two mandatory sections and five +The body of the map file contains two mandatory sections and six optional sections. The first mandatory section begins with the keyword "InitiatorIDs" and lists the two atom IDs of the initiator atom pair in the pre-reacted molecule template. The second mandatory section @@ -908,11 +908,14 @@ create images like those shown below: Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -Cumulative reaction counts for each reaction are written to :doc:`binary restart files `. -These values are associated with the reaction name (react-ID). -Additionally, internally-created per-atom properties are stored to -allow for smooth restarts. None of the :doc:`fix_modify ` -options are relevant to this fix. +Cumulative reaction counts for each reaction are written to :doc:`binary +restart files `. These values are associated with the reaction +name (react-ID). Additionally, internally-created per-atom properties +are stored to allow for smooth restarts. + +The *vizsteps* option of the :doc:`fix_modify ` command is +supported by this fix to control on which timesteps reacted atoms are +highlighted in :doc:`dump image ` output. This fix computes one statistic for each *react* argument that it stores in a global vector, of length (number of react arguments), that diff --git a/doc/src/fix_efield.rst b/doc/src/fix_efield.rst index ecdb25fca59..19da8bee428 100644 --- a/doc/src/fix_efield.rst +++ b/doc/src/fix_efield.rst @@ -8,6 +8,8 @@ fix efield command fix efield/tip4p command ======================== +Accelerator Variant: *efield/kk* + Syntax """""" diff --git a/doc/src/fix_graphics_arrows.rst b/doc/src/fix_graphics_arrows.rst index 1d2d1c5a10e..f83ea97de63 100644 --- a/doc/src/fix_graphics_arrows.rst +++ b/doc/src/fix_graphics_arrows.rst @@ -192,9 +192,9 @@ Related commands :doc:`fix graphics/labels `, :doc:`fix graphics/isosurface `, +:doc:`fix graphics/lines `, :doc:`fix graphics/objects `, :doc:`fix graphics/periodic `, -:doc:`fix graphics/objects `, :doc:`compute hbond/local ` Default diff --git a/doc/src/fix_graphics_isosurface.rst b/doc/src/fix_graphics_isosurface.rst index 4aa424e446a..42e5c23d0fa 100644 --- a/doc/src/fix_graphics_isosurface.rst +++ b/doc/src/fix_graphics_isosurface.rst @@ -97,7 +97,7 @@ the values at the grid points for the isosurface. The default setting of *none* just uses a value of 1.0, resulting in the data grid representing a smoothed out number density. Other possible arguments are *mass* (for representing the smoothed out mass density) or a -references to a a :doc:`compute `, a :doc:`fix `, or a +references to a :doc:`compute `, a :doc:`fix `, or a reference to an atom-style :doc:`variable `. The compute or fix must produce a per-atom vector or array, not a global or local quantity. In case the property is a per-atom array, the column must be @@ -135,9 +135,9 @@ Dump image info Fix graphics/isosurface is designed to be used with the *fix* keyword of :doc:`dump image `. The fix will construct an isosurface -based on the atom positions, the selected property. of the atoms in the -fix group and pass the graphics geometry information about it to *dump -image* so that it is included in the rendered image. +based on the atom positions and the selected property of the atoms in +the fix group and pass the graphics geometry information about it to +*dump image* so that it is included in the rendered image. The *fflag1* setting of *dump image fix* determines whether the isosurface will be rendered as a set of connected triangles (1) or as a @@ -228,7 +228,7 @@ and the Tachyon ray tracer (from left to right). .. raw:: html -
(Fix graphics/isosurface visualization and exporty example. Click to see the full-size images)

+
(Fix graphics/isosurface visualization and export example. Click to see the full-size images)

Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/fix_graphics_objects.rst b/doc/src/fix_graphics_objects.rst index d8064a2dac6..af34b99a3b2 100644 --- a/doc/src/fix_graphics_objects.rst +++ b/doc/src/fix_graphics_objects.rst @@ -83,9 +83,9 @@ Available graphics objects are (see above for exact command line syntax): - *cylinder* - a cylinder defined by its two center endpoints and its radius - *arrow* - a cylinder with a cone at one side (see note below) - *cone* - a truncated cone with a flat circular cap at either side (see note below) -- *progbar* - progress bar a long a selected axis and with optional tick marks +- *progbar* - progress bar along a selected axis and with optional tick marks -The *type* quantity determines the color of the object. Its represents +The *type* quantity determines the color of the object. It represents an *atom* type and the object will be colored the same as the corresponding atom type when the "type" or "element" color style is used in the :doc:`dump image fix ` command. For the *progbar* diff --git a/doc/src/fix_lambda_la_csp_apip.rst b/doc/src/fix_lambda_la_csp_apip.rst index d5069fe03fa..dce4a141de9 100644 --- a/doc/src/fix_lambda_la_csp_apip.rst +++ b/doc/src/fix_lambda_la_csp_apip.rst @@ -17,7 +17,7 @@ Syntax * cut_lo = radius below which the weighting function for the local averaging is 1 (distance units) * cut_hi = radius above which the weighting function for the local averaging is 0 (distance units) * lattice = *fcc* or *bcc* or N = # of neighbors per atom to include in the CSP calculation -* zero or one keyword/args pairs may be appended +* zero or more keyword/args pairs may be appended * keyword = *csp_cut* or *csp_mode* or *forces* or *lambda_non_group* or *store_peratom* .. parsed-literal:: diff --git a/doc/src/fix_reaxff_bonds.rst b/doc/src/fix_reaxff_bonds.rst index f35f17fdc89..dd89855bed5 100644 --- a/doc/src/fix_reaxff_bonds.rst +++ b/doc/src/fix_reaxff_bonds.rst @@ -14,7 +14,7 @@ Syntax fix ID group-ID reaxff/bonds Nevery filename * ID, group-ID are documented in :doc:`fix ` command -* reax/bonds = style name of this fix command +* reaxff/bonds = style name of this fix command * Nevery = output interval in timesteps * filename = name of output file @@ -61,7 +61,7 @@ smaller than the text version, but will also take longer to write. .. versionadded:: 2Apr2025 If the filename contains the wildcard character "\*", a new file is -created on every timestep there bond information is written. The "\*" +created on every timestep where bond information is written. The "\*" character is replaced with the timestep value. Note that the :doc:`fix_modify pad ` command can be used so that all timestep numbers have the same length by adding leading zeroes diff --git a/doc/src/fix_spring_self.rst b/doc/src/fix_spring_self.rst index a78e7575f85..0dae5fe2247 100644 --- a/doc/src/fix_spring_self.rst +++ b/doc/src/fix_spring_self.rst @@ -4,6 +4,8 @@ fix spring/self command ======================= +Accelerator Variant: *spring/self/kk* + Syntax """""" diff --git a/doc/src/group.rst b/doc/src/group.rst index 12ff3141053..7fdf7069c0d 100644 --- a/doc/src/group.rst +++ b/doc/src/group.rst @@ -116,7 +116,7 @@ to a group. The *region* style puts all atoms in the region volume into the group. Note that this is a static one-time assignment. The atoms remain -assigned (or not assigned) to the group even in they later move out of +assigned (or not assigned) to the group even if they later move out of the region volume. The *type*, *id*, and *molecule* styles put all atoms with the @@ -132,7 +132,7 @@ with an optional increment. The first example with ``500:1000`` has the default increment of 1 and would add all atom IDs from 500 to 1000 (inclusive) to the group sub, along with 10, 25, and 50 since they also appear in the list of values. The second example with ``100:10000:10`` -uses an increment of 10 and would thus would add atoms IDs +uses an increment of 10 and would thus add atoms IDs :math:`100, 110, 120, \dots, 9990, 10000` to the group sub. The second format is a *logical* followed by one or two values (type diff --git a/doc/src/improper_cvff.rst b/doc/src/improper_cvff.rst index 46801cc169d..de68306fcc8 100644 --- a/doc/src/improper_cvff.rst +++ b/doc/src/improper_cvff.rst @@ -6,7 +6,7 @@ improper_style cvff command =========================== -Accelerator Variants: *cvff/intel*, *cvff/omp* +Accelerator Variants: *cvff/intel*, *cvff/kk*, *cvff/omp* Syntax """""" diff --git a/doc/src/pair_eam_apip.rst b/doc/src/pair_eam_apip.rst index e1ef646b59b..b162d29aed7 100644 --- a/doc/src/pair_eam_apip.rst +++ b/doc/src/pair_eam_apip.rst @@ -94,8 +94,8 @@ The eam/apip pair styles can only be used via the *pair* keyword of the Restrictions """""""""""" -This pair styles are part of the APIP package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package +These pair styles are part of the APIP package. They are only enabled +if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. Related commands diff --git a/doc/src/pair_lj_cubic.rst b/doc/src/pair_lj_cubic.rst index 6bf2c902008..1bb2eaadbfd 100644 --- a/doc/src/pair_lj_cubic.rst +++ b/doc/src/pair_lj_cubic.rst @@ -42,13 +42,12 @@ the energy and force are zero. & = u_{LJ}(r_s) + (r-r_s) u'_{LJ}(r_s) - \frac{1}{6} A_3 (r-r_s)^3 \qquad r_s < r \leq r_c \\ & = 0 \qquad r > r_c -The location of the inflection point :math:`r_s` is defined -by the LJ diameter, :math:`r_s/\sigma = (26/7)^{1/6}`. The cutoff distance -is defined by :math:`r_c/r_s = 67/48` or :math:`r_c/\sigma = 1.737...` -The analytic expression for the -the cubic coefficient -:math:`A_3 r_{min}^3/\epsilon = 27.93...` is given in the paper by -Holian and Ravelo :ref:`(Holian) `. +The location of the inflection point :math:`r_s` is defined by the LJ +diameter, :math:`r_s/\sigma = (26/7)^{1/6}`. The cutoff distance is +defined by :math:`r_c/r_s = 67/48` or :math:`r_c/\sigma = 1.737...` The +analytic expression for the cubic coefficient :math:`A_3 +r_{min}^3/\epsilon = 27.93...` is given in the paper by Holian and +Ravelo :ref:`(Holian) `. This potential is commonly used to study the shock mechanics of FCC solids, as in Ravelo et al. :ref:`(Ravelo) `. diff --git a/doc/src/pair_pace_apip.rst b/doc/src/pair_pace_apip.rst index 29c2a6088dc..0b1e3c8bbd3 100644 --- a/doc/src/pair_pace_apip.rst +++ b/doc/src/pair_pace_apip.rst @@ -94,16 +94,16 @@ two different element types, mixing is performed by LAMMPS with user-specifiable parameters as described above. You never need to specify a pair_coeff command with I != J arguments for this style. -This pair styles does not support the :doc:`pair_modify ` +These pair styles do not support the :doc:`pair_modify ` shift, table, and tail options. -This pair styles does not write its information to :doc:`binary restart +These pair styles do not write their information to :doc:`binary restart files `, since it is stored in potential files. Thus, you need to re-specify the pair_style and pair_coeff commands in an input script that reads a restart file. -This pair styles can only be used via the *pair* keyword of the -:doc:`run_style respa ` command. It does not support the +These pair styles can only be used via the *pair* keyword of the +:doc:`run_style respa ` command. They do not support the *inner*, *middle*, *outer* keywords. ---------- @@ -111,8 +111,8 @@ This pair styles can only be used via the *pair* keyword of the Restrictions """""""""""" -This pair styles are part of the APIP package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package +These pair styles are part of the APIP package. They are only enabled +if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. Related commands diff --git a/doc/src/region2vmd.rst b/doc/src/region2vmd.rst index 81913aeaef7..3b66fc11403 100644 --- a/doc/src/region2vmd.rst +++ b/doc/src/region2vmd.rst @@ -8,7 +8,7 @@ Syntax .. code-block:: LAMMPS - region2vmd file keyword arg ... + region2vmd filename keyword arg ... * filename = name of file to write VMD script commands to * zero or more keyword/arg pairs may be appended @@ -51,7 +51,7 @@ represent the region in VMD. Each region will be stored in a separate :doc:`dump image ` command. For more information, see :doc:`Howto_viz`. -The *region2vmd* command is following by the filename for the resulting +The *region2vmd* command is followed by the filename for the resulting VMD script and an arbitrary number of keyword argument pairs to either write out a new *region* visualization, change the *color* or *material* setting, or to insert arbitrary VMD script *command*\ s. The keywords diff --git a/doc/src/temper.rst b/doc/src/temper.rst index 8157072f667..233070b84e5 100644 --- a/doc/src/temper.rst +++ b/doc/src/temper.rst @@ -8,10 +8,10 @@ Syntax .. code-block:: LAMMPS - temper N M temp fix-ID seed1 seed2 index + temper Nsteps Nevery temp fix-ID seed1 seed2 index -* N = total # of timesteps to run -* M = attempt a tempering swap every this many steps +* Nsteps = total # of timesteps to run +* Nevery = attempt a tempering swap every this many steps * temp = initial temperature for this ensemble * fix-ID = ID of the fix that will control temperature during the run * seed1 = random # seed used to decide on adjacent temperature to partner with @@ -60,20 +60,20 @@ command for more details. For example: would define 4 temperatures, and assign one of them to the thermostat used by each replica, and to the temper command. -As the tempering simulation runs for *N* timesteps, a temperature swap -between adjacent ensembles will be attempted every *M* timesteps. If -*seed1* is 0, then the swap attempts will alternate between odd and -even pairings. If *seed1* is non-zero then it is used as a seed in a -random number generator to randomly choose an odd or even pairing each -time. Each attempted swap of temperatures is either accepted or -rejected based on a Boltzmann-weighted Metropolis criterion which uses -*seed2* in the random number generator. +As the tempering simulation runs for *Nsteps* timesteps, a temperature +swap between adjacent ensembles will be attempted every *Nevery* +timesteps. If *seed1* is 0, then the swap attempts will alternate +between odd and even pairings. If *seed1* is non-zero then it is used +as a seed in a random number generator to randomly choose an odd or even +pairing each time. Each attempted swap of temperatures is either +accepted or rejected based on a Boltzmann-weighted Metropolis criterion +which uses *seed2* in the random number generator. As a tempering run proceeds, multiple log files and screen output files are created, one per replica. By default these files are named ``log.lammps.M`` and ``screen.M`` where *M* is the replica number from 0 to *N*-1, with *N* = # of replicas. See the :doc:`-log and -screen -command-line swiches ` for info on how to change these +command-line switches ` for info on how to change these names. The main screen and log file (``log.lammps``) will list information @@ -123,7 +123,7 @@ manner: contain "continuous trajectories" for individual atoms, because two successive snapshots (in time) may be from different replicas. The reorder_remd_traj python script can do the reordering for you - (and additionally also calculated configurational log-weights of + (and additionally also calculates configurational log-weights of trajectory snapshots in the canonical ensemble). The script can be found in the tools/replica directory while instructions on how to use it is available in doc/Tools (in brief) and as a README file in tools/replica diff --git a/lib/gpu/README b/lib/gpu/README index e341393262e..05af3473aaf 100644 --- a/lib/gpu/README +++ b/lib/gpu/README @@ -134,6 +134,91 @@ for CUDA: and for ROCm HIP: ./hip_get_devices +------------------------------------------------------------------------------ + ADD NEW PAIR STYLES +------------------------------------------------------------------------------ + +Suppose that you have already implemented a pair style class named PairFoo. +Now you want to have a new class PairFooGPU for GPU acceleration. The following +steps will guide you through the process of adding a new pair style to +the GPU package in LAMMPS. There are two places you need to add +new source files: the Foo class and exported functions the GPU library +in lib/gpu (i.e. libgpu.a) and the new /gpu styles in src/GPU. + +1. Addition to the GPU library under lib/gpu + +You will need to add four source files: + lal_foo.h: header of the class Foo + lal_foo.cpp: contains the implementation of the class Foo + lal_foo.cu: contains the GPU kernel(s) for the force compute, + where the computation mirrors what you have in PairFoo. + lal_foo_ext.cpp: creates an instance of the Foo class and exports + the necessary functions to be invoked by the GPU + version of the pair style to initialize a Foo instance. + +A good start for implementing a new pair style to look at is +the corresponding files for the Gauss class in lib/gpu. You will see +how the per-type arrays are declared and allocated (lal_gauss.h and lal_gauss.cpp), +how the kernels are implemented (lal_gauss.cu) and how the exported functions +are defined (lal_gauss_ext.cpp). + +The class Gauss is derived from BaseAtomic, which handles the host device +transfers for the atom properties (positions and types) and the force +computation in two compute() functions. One compute() function is invoked +when the atom neighbor lists are copied from the host, the other +(with the sub-domain coordinates arguments sublo and subhi) when +the atom neighbor lists are built from the device. After the neighbor lists +are ready, both compute() functions invoke the loop() function to launch +the force compute kernels. Any child class of BaseAtomic, Gauss in this case, +needs to override this virtual loop() function. The pair force kernels +are defined in the .cu file: the _fast kernel is invoked in the cases +where all the pair coefficients can be loaded in the thread block +shared memory, i.e., when the number of atom types is smaller than 12. + +The Gauss class also needs to allocate and deallocate memory for +the arrays that store pair coefficients, and transfer them to the device +in the init() member function. These arrays are data structures provided +by the Geryon library that allow for efficient memory management and +data transfer between host and device. + +2. Addition to src/GPU + +Next, you will create an entry from src/GPU to call the external functions +defined in lal_foo_ext.cpp. You will need to implement the PairFooGPU class +derived from your PairFoo class with a header file (pair_foo_gpu.h) and +a source file (pair_foo_gpu.cpp). Again, pair_gauss_gpu.h and +pair_gauss_gpu.cpp are good examples to start with. + +In the PairFooGPU class, you will invoke the external functions from +the Gauss class provided by lal_gauss_ext.cpp at the proper place. +For instance, in the init_style() function, you will call the init() +function of the Gauss class to allocate memory for the pair coefficients +and transfer them to the device. In the PairFooGPU::compute() function, +you will call the corresponding functions: _compute() function for "neigh no" +(neighbor builds on the host) or _compute_n() for "neigh yes" +(neighbor builds on the device) to compute the atom forces, potential energy +and virial. The class destructor will invoke the clear() function to release +the memory allocated by the GPU library both on host and device. + +3. Build LAMMPS with the new pair style + +For CMake builds, you may want to modify the file cmake/Module/Packages/GPU.cmake +if the new pair style depends on certain packages to be installed. +You then run cmake with the following command to build LAMMPS with +the GPU package with your new pair style: + + cmake -S cmake -B build -C cmake/presets/basic.cmake -D PKG_GPU=ON + cmake --build build -j4 + +By design, your PairFooGPU class depends on PairFoo, so if PairFoo is +part of the MISC package, for example, PairFooGPU will be built with +both -D PKG_MISC=ON and -D PKG_GPU=ON. + +Note: It is possible to support fix and compute styles within the GPU package +using the Geryon library. You need to perform host-device data transfers and +computation on the device for each MPI process. The PPPMGPU class is an example +for this extension. + ------------------------------------------------------------------------------ References for Details ------------------------------------------------------------------------------ diff --git a/src/GRAPHICS/dump_image.cpp b/src/GRAPHICS/dump_image.cpp index 671e78dd0d0..015dac6fad4 100644 --- a/src/GRAPHICS/dump_image.cpp +++ b/src/GRAPHICS/dump_image.cpp @@ -75,6 +75,37 @@ enum { NO = 0, YES = 1, AUTO = 2 }; enum { FILLED, FRAME, POINTS, TRANSPARENT }; enum { OFF = 0, CENTER, LOWERLEFT, LOWERRIGHT, UPPERLEFT, UPPERRIGHT }; +// convenience functions to change and restore lighting, assuming uncolored light + +struct savedColors { + double ambient; + double key; + double fill; + double back; +}; + +savedColors reset_lighting(Image *image, double ambient, double key, double fill, double back) +{ + savedColors saved; + saved.ambient = image->ambientColor[0]; + image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = ambient; + saved.key = image->keyLightColor[0]; + image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = key; + saved.fill = image->fillLightColor[0]; + image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = fill; + saved.back = image->backLightColor[0]; + image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = back; + return saved; +} + +void restore_lighting(const savedColors &saved, Image *image) +{ + image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = saved.ambient; + image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = saved.key; + image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = saved.fill; + image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = saved.back; +} + } // namespace // clang-format off @@ -265,9 +296,6 @@ DumpImage::DumpImage(LAMMPS *lmp, int narg, char **arg) : else if (strcmp(arg[iarg+1],"index") == 0) lcolor = INDEX; else error->all(FLERR, iarg+1, "Dump image line only supports color by type, atom, or index"); - if ((lcolor != ATOM) && (acolor != TYPE)) - error->all(FLERR, iarg+1, - "Must color atoms by type with line particles colored by type or index"); ldiam = NUMERIC; ldiamvalue = utils::numeric(FLERR,arg[iarg+2],false,lmp); iarg += 3; @@ -280,9 +308,6 @@ DumpImage::DumpImage(LAMMPS *lmp, int narg, char **arg) : else if (strcmp(arg[iarg+1],"index") == 0) tcolor = INDEX; else error->all(FLERR, iarg+1, "Dump image tri only supports color by type, atom, or index"); - if ((tcolor != ATOM) && (acolor != TYPE)) - error->all(FLERR, iarg+1, - "Must color atoms by type with tri particles colored by type or index"); tstyle = utils::inumeric(FLERR,arg[iarg+2],false,lmp); tdiamvalue = utils::numeric(FLERR,arg[iarg+3],false,lmp); iarg += 4; @@ -295,9 +320,6 @@ DumpImage::DumpImage(LAMMPS *lmp, int narg, char **arg) : else if (strcmp(arg[iarg+1],"index") == 0) ecolor = INDEX; else error->all(FLERR, iarg+1, "Dump image ellipsoid only supports color by type, atom, or index"); - if ((ecolor != ATOM) && (acolor != TYPE)) - error->all(FLERR, iarg+1, - "Must color atoms by type with ellipsoid particles colored by type or index"); estyle = utils::inumeric(FLERR,arg[iarg+2],false,lmp); if ((estyle < 0) || (estyle > 3)) error->all(FLERR, iarg+2, "Dump image ellipsoid only supports style setting 1, 2, or 3"); @@ -316,9 +338,6 @@ DumpImage::DumpImage(LAMMPS *lmp, int narg, char **arg) : else if (strcmp(arg[iarg+1],"index") == 0) bodycolor = INDEX; else error->all(FLERR, iarg+1, "Dump image body only supports color by type, atom, or index"); - if ((bodycolor != ATOM) && (acolor != TYPE)) - error->all(FLERR, iarg+1, - "Must color atoms by type with body particles colored by type or index"); bodyflag1 = utils::numeric(FLERR,arg[iarg+2],false,lmp); bodyflag2 = utils::numeric(FLERR,arg[iarg+3],false,lmp); iarg += 4; @@ -1123,7 +1142,7 @@ void DumpImage::create_image() { int i,j,k,m,n,itype,atom1,atom2,imol,iatom,btype,ibonus,drawflag; tagint tagprev; - double diameter,delx,dely,delz; + double diameter,opacity,delx,dely,delz; int *bodyvec; double **bodyarray; double *color,*color1,*color2; @@ -1131,10 +1150,15 @@ void DumpImage::create_image() double pt1[3],pt2[3],pt3[3]; double mat[3][3]; + // set defaults to avoid accidental uninitialized accesses + diameter = 1.0; + opacity = 1.0; + // render my atoms if (atomflag) { double **x = atom->x; + int *type = atom->type; int *line = atom->line; int *tri = atom->tri; int *ellipsoid = atom->ellipsoid; @@ -1144,11 +1168,11 @@ void DumpImage::create_image() for (i = 0; i < nchoose; i++) { j = clist[i]; + itype = type[j]; + opacity = aopacity[itype]; if (acolor == TYPE) { - itype = static_cast(buf[m]); color = colortype[itype]; } else if (acolor == ELEMENT) { - itype = static_cast(buf[m]); color = colorelement[itype]; } else if (acolor == ATTRIBUTE) { color = image->map_value2color(0,buf[m]); @@ -1157,10 +1181,8 @@ void DumpImage::create_image() if (adiam == NUMERIC) { diameter = adiamvalue; } else if (adiam == TYPE) { - itype = static_cast(buf[m+1]); diameter = diamtype[itype]; } else if (adiam == ELEMENT) { - itype = static_cast(buf[m+1]); diameter = diamelement[itype]; } else if (adiam == ATTRIBUTE) { diameter = buf[m+1]; @@ -1176,7 +1198,7 @@ void DumpImage::create_image() if (bodyflag && body[j] >= 0) drawflag = 0; } - if (drawflag) image->draw_sphere(x[j],color,diameter,aopacity[atom->type[j]]); + if (drawflag) image->draw_sphere(x[j],color,diameter,opacity); m += size_one; } @@ -1191,10 +1213,7 @@ void DumpImage::create_image() // reset lighting for flat surfaces to make them brighter - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.9; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.3; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.3; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.3; + auto saved = reset_lighting(image, 0.9, 0.3, 0.3, 0.3); int n = 0; if (domain->dimension == 2) { @@ -1234,10 +1253,7 @@ void DumpImage::create_image() // restore lighting for curved objects - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.0; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.9; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.45; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.9; + restore_lighting(saved, image); } // render atoms that are lines @@ -1254,7 +1270,7 @@ void DumpImage::create_image() if (line[j] < 0) continue; itype = type[j]; - double opacity = aopacity[itype]; + opacity = aopacity[itype]; if (lcolor == TYPE) { color = colortype[itype]; } else if (lcolor == INDEX) { @@ -1290,7 +1306,7 @@ void DumpImage::create_image() pt2[1] = x[j][1] - dy; pt2[2] = 0.0; - image->draw_cylinder(pt1,pt2,color,ldiamvalue,3,aopacity[atom->type[j]]); + image->draw_cylinder(pt1,pt2,color,ldiamvalue,3,opacity); m += size_one; } @@ -1315,7 +1331,7 @@ void DumpImage::create_image() if (tri[j] < 0) continue; itype = type[j]; - double opacity = aopacity[itype]; + opacity = aopacity[itype]; if (tcolor == TYPE) { color = colortype[itype]; } else if (tcolor == INDEX) { @@ -1344,19 +1360,13 @@ void DumpImage::create_image() MathExtra::add3(pt3,x[j],pt3); if (tridraw) { - // brighten flat surfaces a little bit - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.3; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.8; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.45; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.8; + // brighten flat surfaces a bit + auto saved = reset_lighting(image, 0.3, 0.8, 0.45, 0.8); image->draw_triangle(pt1,pt2,pt3,color,opacity); // restore previous settings - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.0; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.9; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.45; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.9; + restore_lighting(saved, image); } if (edgedraw) { image->draw_cylinder(pt1,pt2,color,tdiamvalue,3,opacity); @@ -1381,7 +1391,7 @@ void DumpImage::create_image() if (ellipsoid[j] < 0) continue; itype = type[j]; - double opacity = aopacity[itype]; + opacity = aopacity[itype]; if (ecolor == TYPE) { color = colortype[itype]; } else if (ecolor == INDEX) { @@ -1400,22 +1410,17 @@ void DumpImage::create_image() } else { color = image->color2rgb("white"); } + savedColors saved; if (estyle & 1) { // brighten flat surfaces a little bit - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.3; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.8; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.45; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.8; + saved = reset_lighting(image, 0.3, 0.8, 0.45, 0.8); } EllipsoidObj e(elevel); e.draw(image, estyle, color, x[j], avec_ellipsoid->bonus[ellipsoid[j]].shape, avec_ellipsoid->bonus[ellipsoid[j]].quat, ediamvalue, opacity); if (estyle & 1) { // restore previous settings - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.0; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.9; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.45; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.9; + restore_lighting(saved, image); } m += size_one; } @@ -1426,24 +1431,24 @@ void DumpImage::create_image() if (bodyflag) { Body *bptr = avec_body->bptr; int *body = atom->body; + int *type = atom->type; m = 0; for (i = 0; i < nchoose; i++) { j = clist[i]; if (body[j] < 0) continue; + itype = type[j]; + opacity = aopacity[itype]; if (bodycolor == TYPE) { - itype = static_cast(buf[m]); color = colortype[itype]; } else if (bodycolor == INDEX) { itype = (body[j] % atom->ntypes) + 1; color = colortype[itype]; } else if (bodycolor == ATOM) { if (acolor == TYPE) { - itype = static_cast(buf[m]); color = colortype[itype]; } else if (acolor == ELEMENT) { - itype = static_cast(buf[m]); color = colorelement[itype]; } else if (acolor == ATTRIBUTE) { color = image->map_value2color(0,buf[m]); @@ -1453,7 +1458,6 @@ void DumpImage::create_image() } else { color = image->color2rgb("white"); } - double opacity = aopacity[atom->type[j]]; ibonus = body[j]; n = bptr->image(ibonus,bodyflag1,bodyflag2,bodyvec,bodyarray); @@ -1464,15 +1468,12 @@ void DumpImage::create_image() image->draw_cylinder(&bodyarray[k][0],&bodyarray[k][3],color,bodyarray[k][6],3,opacity); else if (bodyvec[k] == Graphics::TRI) { // brighten flat surfaces a little bit - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.3; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.8; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.45; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.8; + auto saved = reset_lighting(image, 0.3, 0.8, 0.45, 0.8); + image->draw_triangle(&bodyarray[k][0],&bodyarray[k][3],&bodyarray[k][6],color,opacity); - image->ambientColor[0] = image->ambientColor[1] = image->ambientColor[2] = 0.0; - image->keyLightColor[0] = image->keyLightColor[1] = image->keyLightColor[2] = 0.9; - image->fillLightColor[0] = image->fillLightColor[1] = image->fillLightColor[2] = 0.45; - image->backLightColor[0] = image->backLightColor[1] = image->backLightColor[2] = 0.9; + + // restore previous settings + restore_lighting(saved, image); } } @@ -1755,7 +1756,7 @@ void DumpImage::create_image() if (!objvec || !objarray) continue; // set color and transparency - double opacity = iobj.opacity; + opacity = iobj.opacity; if (iobj.colorstyle == TYPE) { itype = static_cast(objarray[i][0] - 1.0) % ntypes + 1; color = colortype[itype]; @@ -1826,7 +1827,7 @@ void DumpImage::create_image() int type1 = static_cast(objarray[i][0] - 1.0) % ntypes + 1; int type2 = static_cast(objarray[i][1] - 1.0) % ntypes + 1; double *color1, *color2; - double opacity = iobj.opacity; + opacity = iobj.opacity; if (iobj.colorstyle == TYPE) { color1 = colortype[type1]; color2 = colortype[type2]; @@ -1841,7 +1842,7 @@ void DumpImage::create_image() color2 = image->color2rgb("white"); } - double diameter = 0.5; + diameter = 0.5; if (bdiam == ATOM) { if (adiam == NUMERIC) { diameter = adiamvalue; @@ -2003,7 +2004,7 @@ void DumpImage::create_image() DRAW_CYLINDER(4, 7); DRAW_CYLINDER(6, 7); } else if ((reg.style == FILLED) || (reg.style == TRANSPARENT)) { - double opacity = (reg.style == TRANSPARENT) ? reg.opacity : 1.0; + opacity = (reg.style == TRANSPARENT) ? reg.opacity : 1.0; if (!reg.ptr->open_faces[0]) { DRAW_TRIANGLE(0, 1, 2); DRAW_TRIANGLE(2, 3, 0); @@ -2121,7 +2122,7 @@ void DumpImage::create_image() // determine draw style flags int drawflag = (reg.style == FRAME) ? 2 : 1; - double opacity = (reg.style == TRANSPARENT) ? reg.opacity : 1.0; + opacity = (reg.style == TRANSPARENT) ? reg.opacity : 1.0; ConeObj c(length, radiushi, radiuslo, faceflag, (reg.style == FRAME) ? RESOLUTION : 2 * RESOLUTION); @@ -2159,7 +2160,7 @@ void DumpImage::create_image() // determine draw style flags int flag = 1; - double opacity = 1.0; + opacity = 1.0; if (reg.style == FRAME) { flag = 2; } else if (reg.style == TRANSPARENT) { @@ -2185,7 +2186,7 @@ void DumpImage::create_image() double radius[3] = {myreg->radius, myreg->radius, myreg->radius}; EllipsoidObj(4).draw(image, 2, reg.color, center, radius, reg.ptr, reg.diameter, 1.0); } else if ((reg.style == FILLED) || (reg.style == TRANSPARENT)) { - double opacity = (reg.style == TRANSPARENT) ? reg.opacity : 1.0; + opacity = (reg.style == TRANSPARENT) ? reg.opacity : 1.0; myreg->forward_transform(center[0], center[1], center[2]); image->draw_sphere(center, reg.color, 2.0 * myreg->radius, opacity); } diff --git a/src/platform.cpp b/src/platform.cpp index d2546ac37d3..7032e6341a0 100644 --- a/src/platform.cpp +++ b/src/platform.cpp @@ -18,6 +18,7 @@ #include "platform.h" #include "fmt/format.h" +#include "safe_pointers.h" #include "text_file_reader.h" #include "utils.h" @@ -1006,6 +1007,27 @@ bool platform::file_is_writable(const std::string &path) return false; } +/* ---------------------------------------------------------------------- + read first line of file to see if it is a redirect file of a git checkout + on a file system without symlinks +------------------------------------------------------------------------- */ + +std::string platform::file_redirect(const std::string &path) +{ +#if defined(_WIN32) + // read the first (and only) line and see if it is a valid path + SafeFilePtr fp = fopen(path.c_str(), "r"); + if (fp) { + char buffer[1024]; + if (fgets(buffer, 1024, fp)) { + auto target = utils::trim(buffer); + if (platform::file_is_readable(target)) return target; + } + } +#endif + return path; +} + /* ---------------------------------------------------------------------- get file modification time since initial time stamp ------------------------------------------------------------------------- */ diff --git a/src/platform.h b/src/platform.h index 3a00e17975a..b08ec178675 100644 --- a/src/platform.h +++ b/src/platform.h @@ -370,6 +370,21 @@ bool file_is_readable(const std::string &path); bool file_is_writable(const std::string &path); +/*! Return target path if the file is a 'redirect file' + * + * Git uses 'redirect files' instead of symbolic links on Windows since + * the Windows file system has no symbolic links. The redirect file + * is a text file with just one line: the symbolic link target path. + * This function opens the path parameter and reads a line. If that + * line is a readable file, it returns that path, otherwise the + * original path. The check is only performed when compiled for + * Windows. Otherwise the original path is always returned. + * + * \param path file path to check + * \return the redirected path or the original path */ + +std::string file_redirect(const std::string &path); + /*! Report a time stamp when a file was last written to * * For increased accuracy and portability, the time stamp is relative @@ -385,7 +400,7 @@ bool file_is_writable(const std::string &path); double file_write_time(const std::string &path); - /*! Return free disk space in bytes of file system pointed to by path +/*! Return free disk space in bytes of file system pointed to by path * * Returns -1.0 if the path is invalid or free space reporting not supported. * diff --git a/src/read_data.cpp b/src/read_data.cpp index d86ee82092b..5ed44816cac 100644 --- a/src/read_data.cpp +++ b/src/read_data.cpp @@ -2466,13 +2466,15 @@ int ReadData::reallocate(int **pcount, int cmax, int amax) void ReadData::open(const std::string &file) { - if (platform::has_compress_extension(file)) { + // file may be a redirect, e.g. on a git checkout on Windows in lieu of a symbolic link + auto path = platform::file_redirect(file); + if (platform::has_compress_extension(path)) { compressed = 1; - fp = platform::compressed_read(file); + fp = platform::compressed_read(path); if (!fp) error->one(FLERR, "Cannot open compressed file {}", file); } else { compressed = 0; - fp = fopen(file.c_str(), "r"); + fp = fopen(path.c_str(), "r"); if (!fp) error->one(FLERR, "Cannot open file {}: {}", file, utils::getsyserror()); } } diff --git a/src/utils.cpp b/src/utils.cpp index 10c0298e6cc..8b719c86009 100644 --- a/src/utils.cpp +++ b/src/utils.cpp @@ -1921,6 +1921,8 @@ FILE *utils::open_potential(const std::string &name, LAMMPS *lmp, int *auto_conv std::string filepath = get_potential_file_path(name); if (!filepath.empty()) { + // update path if file is a redirect file on Windows + filepath = platform::file_redirect(filepath); std::string unit_style = lmp->update->unit_style; std::string date = get_potential_date(filepath, "potential"); std::string units = get_potential_units(filepath, "potential");