From 9d9b0897003d81e350cb2ce1b6d0870fbb795405 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 25 Jul 2021 10:03:16 -0400 Subject: [PATCH] get rid of references to USER-MISC in the general discussion --- doc/src/Developer_org.rst | 2 +- doc/src/Errors_bugs.rst | 5 ++- doc/src/Examples.rst | 7 +-- doc/src/Howto_cmake.rst | 2 +- doc/src/Howto_replica.rst | 49 ++++++++++---------- doc/src/Intro_website.rst | 3 +- doc/src/Modify_contribute.rst | 84 ++++++++++++++++++----------------- doc/src/Packages_details.rst | 3 -- 8 files changed, 77 insertions(+), 78 deletions(-) diff --git a/doc/src/Developer_org.rst b/doc/src/Developer_org.rst index 133d567cb3..b5acdf5631 100644 --- a/doc/src/Developer_org.rst +++ b/doc/src/Developer_org.rst @@ -17,7 +17,7 @@ currently supports building with :doc:`conventional makefiles differ in how packages are enabled or disabled for inclusion into a LAMMPS binary so they cannot be mixed. The source files for each package are in all-uppercase sub-directories of the ``src`` folder, for -example ``src/MOLECULE`` or ``src/USER-MISC``. The ``src/STUBS`` +example ``src/MOLECULE`` or ``src/EXTRA-MOLECULE``. The ``src/STUBS`` sub-directory is not a package but contains a dummy MPI library, that is used when building a serial version of the code. The ``src/MAKE`` directory and its sub-directories contain makefiles with settings and diff --git a/doc/src/Errors_bugs.rst b/doc/src/Errors_bugs.rst index 1ea368a5a3..dbec1ef895 100644 --- a/doc/src/Errors_bugs.rst +++ b/doc/src/Errors_bugs.rst @@ -17,8 +17,9 @@ the steps outlined below: if your issue has already been reported and if it is still open. * Check the `GitHub Pull Requests page `_ to see if there is already a fix for your bug pending. - * Check the `mailing list archives `_ - to see if the issue has been discussed before. + * Check the `mailing list archives `_ or + the `LAMMPS forum `_ to see if the + issue has been discussed before. If none of these steps yields any useful information, please file a new bug report on the `GitHub Issue page `_. diff --git a/doc/src/Examples.rst b/doc/src/Examples.rst index df9d1616a6..043820c5dd 100644 --- a/doc/src/Examples.rst +++ b/doc/src/Examples.rst @@ -207,14 +207,12 @@ Uppercase directories +------------+--------------------------------------------------------------------------------------------------+ | MC | using LAMMPS in a Monte Carlo mode to relax the energy of a system | +------------+--------------------------------------------------------------------------------------------------+ -| PACKAGES | examples for specific packages and contributed commands in USER-MISC | +| PACKAGES | examples for specific packages and contributed commands | +------------+--------------------------------------------------------------------------------------------------+ | SPIN | examples for features of the SPIN package | +------------+--------------------------------------------------------------------------------------------------+ | UNITS | examples that run the same simulation in lj, real, metal units | +------------+--------------------------------------------------------------------------------------------------+ -| USER-MISC | examples for commands in the USER-MISC packages | -+------------+--------------------------------------------------------------------------------------------------+ | VISCOSITY | compute viscosity via several methods | +------------+--------------------------------------------------------------------------------------------------+ @@ -228,7 +226,4 @@ of the sub-directories have their own README files which give further instructions. See the :doc:`Packages_details ` doc page for more info on specific packages. -Similarly the USER-MISC directory has sub-directories for examples -corresponding to individual commands or styles in the USER-MISC package. - .. _openkim: https://openkim.org diff --git a/doc/src/Howto_cmake.rst b/doc/src/Howto_cmake.rst index 244bcf6323..832a8b8770 100644 --- a/doc/src/Howto_cmake.rst +++ b/doc/src/Howto_cmake.rst @@ -362,7 +362,7 @@ have to be enabled to be included into a LAMMPS executable. Packages are enabled through setting variables of the kind ``PKG_`` to ``on`` and disabled by setting them to ``off`` (or using ``yes``, ``no``, ``1``, ``0`` correspondingly). ```` has to be replaced by -the name of the package, e.g. ``MOLECULE`` or ``USER-MISC``. +the name of the package, e.g. ``MOLECULE`` or ``EXTRA-PAIR``. Using presets diff --git a/doc/src/Howto_replica.rst b/doc/src/Howto_replica.rst index e9fba37dcd..e34f3523f0 100644 --- a/doc/src/Howto_replica.rst +++ b/doc/src/Howto_replica.rst @@ -8,34 +8,33 @@ periodically. These are the relevant commands: -* :doc:`neb ` for nudged elastic band calculations +* :doc:`hyper ` for bond boost hyperdynamics (HD) +* :doc:`neb ` for nudged elastic band calculations (NEB) * :doc:`neb_spin ` for magnetic nudged elastic band calculations -* :doc:`prd ` for parallel replica dynamics -* :doc:`tad ` for temperature accelerated dynamics -* :doc:`temper ` for parallel tempering +* :doc:`prd ` for parallel replica dynamics (PRD) +* :doc:`tad ` for temperature accelerated dynamics (TAD) +* :doc:`temper ` for parallel tempering with fixed volume +* :doc:`temper/npt ` for parallel tempering extended for NPT +* :doc:`temper/grem ` for parallel tempering with generalized replica exchange (gREM) * :doc:`fix pimd ` for path-integral molecular dynamics (PIMD) -NEB is a method for finding transition states and barrier energies. -PRD and TAD are methods for performing accelerated dynamics to find -and perform infrequent events. Parallel tempering or replica exchange -runs different replicas at a series of temperature to facilitate -rare-event sampling. +NEB is a method for finding transition states and barrier potential energies. +HD, PRD, and TAD are methods for performing accelerated dynamics to find and +perform infrequent events. Parallel tempering or replica exchange runs +different replicas at a series of temperature to facilitate rare-event +sampling. PIMD runs different replicas whose individual particles in different +replicas are coupled together by springs to model a system of ring-polymers which +can represent the quantum nature of atom cores. These commands can only be used if LAMMPS was built with the REPLICA package. See the :doc:`Build package ` doc page for more info. -PIMD runs different replicas whose individual particles are coupled -together by springs to model a system or ring-polymers. - -This commands can only be used if LAMMPS was built with the USER-MISC -package. See the :doc:`Build package ` doc page for more -info. - In all these cases, you must run with one or more processors per replica. The processors assigned to each replica are determined at -run-time by using the :doc:`-partition command-line switch ` to launch LAMMPS on multiple partitions, -which in this context are the same as replicas. E.g. these commands: +run-time by using the :doc:`-partition command-line switch +` to launch LAMMPS on multiple partitions, which in this +context are the same as replicas. E.g. these commands: .. code-block:: bash @@ -46,9 +45,11 @@ would each run 8 replicas, on either 16 or 8 processors. Note the use of the :doc:`-in command-line switch ` to specify the input script which is required when running in multi-replica mode. -Also note that with MPI installed on a machine (e.g. your desktop), -you can run on more (virtual) processors than you have physical -processors. Thus the above commands could be run on a -single-processor (or few-processor) desktop so that you can run -a multi-replica simulation on more replicas than you have -physical processors. +Also note that with MPI installed on a machine (e.g. your desktop), you +can run on more (virtual) processors than you have physical processors. +Thus the above commands could be run on a single-processor (or +few-processor) desktop so that you can run a multi-replica simulation on +more replicas than you have physical processors. This is useful for +testing and debugging, since with most modern processors and MPI +libraries the efficiency of a calculation can severely diminish when +oversubscribing processors. diff --git a/doc/src/Intro_website.rst b/doc/src/Intro_website.rst index 3fccaf4dca..2ea1969f2a 100644 --- a/doc/src/Intro_website.rst +++ b/doc/src/Intro_website.rst @@ -20,7 +20,8 @@ available online are listed below. * `Glossary of terms relevant to LAMMPS `_ * `LAMMPS highlights with images `_ * `LAMMPS highlights with movies `_ -* `Mail list `_ +* `Mailing list `_ +* `LAMMPS forum `_ * `Workshops `_ * `Tutorials `_ diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 42ce8d2498..bcd368c3a3 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -25,13 +25,16 @@ the work of others (and possibly get scooped by them) or have your work duplicated by others. For informal communication with (some of) the LAMMPS developers you may -ask to join the `LAMMPS developers on Slack `_. -This slack work space is by invitation only. Thus for access, please -send an e-mail to ``slack@lammps.org`` explaining what part of LAMMPS -you are working on. Only discussions related to LAMMPS development are -tolerated, so this is **NOT** for people that look for help with compiling, -installing, or using LAMMPS. Please contact the `lammps-users mailing -list `_ for those purposes instead. +ask to join the `LAMMPS developers on Slack +`_. This slack work space is by invitation +only. Thus for access, please send an e-mail to ``slack@lammps.org`` +explaining what part of LAMMPS you are working on. Only discussions +related to LAMMPS development are tolerated, so this is **NOT** for +people that look for help with compiling, installing, or using +LAMMPS. Please contact the +`lammps-users mailing list `_ or the +`LAMMPS forum `_ for those purposes +instead. How quickly your contribution will be integrated depends largely on how much effort it will cause to integrate and test it, how many and what @@ -49,11 +52,9 @@ with gzip. Please only use gzip compression, as this works well and is available on all platforms. If the new features/files are broadly useful we may add them as core -files to LAMMPS or as part of a :doc:`package `. The -USER-MISC package is simply a collection of (mostly) unrelated single -files, which is the simplest way to have your contribution quickly added -to the LAMMPS distribution. All packages are listed and described -on the :doc:`Packages details ` doc page. +files to LAMMPS or as part of a :doc:`package `. All +packages are listed and described on the :doc:`Packages details +` doc page. Note that by providing us files to release, you are agreeing to make them open-source, i.e. we can release them under the terms of the GPL @@ -92,7 +93,7 @@ trivial change is making a parent-class method "virtual" when you derive a new child class from it. Here is a checklist of steps you need to follow to submit a single file -or user package for our consideration. Following these steps will save +or package for our consideration. Following these steps will save both you and us time. Please have a look at the existing files in packages in the src directory for examples. If you are uncertain, please ask. @@ -150,37 +151,40 @@ packages in the src directory for examples. If you are uncertain, please ask. You may also use ``// clang-format on/off`` throughout your file to protect sections of the file from being reformatted. -* If you want your contribution to be added as a user-contributed - feature, and it's a single file (actually a \*.cpp and \*.h file) it can - rapidly be added to the USER-MISC directory. Send us the one-line - entry to add to the USER-MISC/README file in that dir, along with the - 2 source files. You can do this multiple times if you wish to - contribute several individual features. +* Please review the list of :doc:`available Packages ` + to see if your contribution could be added to be added to one of them. + It should fit into the general purposed of that package. If it does not + fit well, it can be added to one of the EXTRA- packages or the MISC package. -* If you want your contribution to be added and it has several related - features or is dependent on an external or bundled library, it is best - to make it a package directory with a name like FOO. In addition to - your new files, the directory should contain a README text file. The - README should contain your name and contact information and a brief - description of what your new package does. If your files depend on - other LAMMPS style files also being installed (e.g. because your file - is a derived class from the other LAMMPS class), then an Install.sh - file is also needed to check for those dependencies. See other README - and Install.sh files in other directories as examples. Submit a pull - request on GitHub or send us a tarball of this FOO directory. Pull - requests are strongly encouraged since the greatly reduce the effort - to integrate a contribution and simplify the process of adjusting the - contributed code to cleanly integrate into the LAMMPS distribution. +* If your contribution has several related features that are not covered + by one of the existing packages or is dependent on a library (bundled + or external), it is best to make it a package directory with a name + like FOO. In addition to your new files, the directory should contain + a README text file. The README should contain your name and contact + information and a brief description of what your new package does. If + your files depend on other LAMMPS style files also being installed + (e.g. because your file is a derived class from the other LAMMPS + class), then an Install.sh file is also needed to check for those + dependencies and modifications to src/Depend.sh to trigger the checks. + See other README and Install.sh files in other directories as examples. + Similarly for CMake support changes need to be made to cmake/CMakeLists.txt, + the files in cmake/presets, and possibly a file to cmake/Modules/Packages/ + added. Please check out how this is handled for existing packages and + ask the LAMMPS developers if you need assistance. Please submit a pull + request on GitHub or send us a tarball of this FOO directory and all + modified files. Pull requests are strongly encouraged since they greatly + reduce the effort required to integrate a contribution and simplify the + process of adjusting the contributed code to cleanly fit into the + LAMMPS distribution. * Your new source files need to have the LAMMPS copyright, GPL notice, and your name and email address at the top, like other user-contributed LAMMPS source files. They need to create a class - that is inside the LAMMPS namespace. If the file is for one of the - USER packages, including USER-MISC, then we are not as picky about the - coding style (see above). I.e. the files do not need to be in the - same stylistic format and syntax as other LAMMPS files, though that - would be nice for developers as well as users who try to read your - code. + that is inside the LAMMPS namespace. To simplify maintenance, we + may ask to adjust the progamming style and formatting style to closer + match the rest of LAMMPS. We bundle a clang-format configuration file + that can help with adjusting the formatting, although this is not a + strict requirement. * You **must** also create a **documentation** file for each new command or style you are adding to LAMMPS. For simplicity and convenience, @@ -205,7 +209,7 @@ packages in the src directory for examples. If you are uncertain, please ask. cite itself. Citation labels must be unique across all .rst files. The "Restrictions" section of the doc page should indicate if your command is only available if LAMMPS is built with the appropriate - USER-MISC or FOO package. See other package doc files for examples of + FOO package. See other package doc files for examples of how to do this. Please run at least "make html" and "make spelling" and carefully inspect and proofread the resulting HTML format doc page before submitting your code. Upon submission of a pull request, diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 5051ce937c..28ae032d34 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -2781,6 +2781,3 @@ which discuss the `QuickFF `_ methodology. * :doc:`pair_style mm3/switch3/coulgauss/long ` * :doc:`pair_style lj/switch3/coulgauss/long ` * examples/PACKAGES/yaff - ----------- -