diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index ef53976acc..c73cd6508c 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -56,8 +56,8 @@ If CMake cannot find the library, you can set these variables: **Traditional make**\ : -If make cannot find the library, you can edit the -lib/compress/Makefile.lammps file to specify the paths and library +If make cannot find the library, you can edit the file +lib/compress/Makefile.lammps to specify the paths and library name. @@ -203,7 +203,7 @@ inside the CMake build directory. If the KIM library is already on your system (in a location CMake cannot find it), set the PKG\_CONFIG\_PATH environment variable so that libkim-api can be found. -For using OpenKIM web queries in LAMMPS. +*For using OpenKIM web queries in LAMMPS*\ : If LMP\_DEBUG\_CURL is set, the libcurl verbose mode will be on, and any libcurl calls within the KIM web query display a lot of information about @@ -239,6 +239,13 @@ invoke the lib/kim/Install.py script with the specified args. make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver +Settings for OpenKIM web queries discussed above need to be applied by adding +them to the LMP\_INC variable through editing the Makefile.machine you are +using. For example: + +.. code-block:: make + + LMP_INC = -DLMP_NO_SSL_CHECK ---------- @@ -858,8 +865,10 @@ core LAMMPS makefiles. Optional flags may be specified as environment variables: -COLVARS\_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower) -COLVARS\_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise) +.. code-block:: bash + + COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower) + COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise) The build should produce two files: the library lib/colvars/libcolvars.a (which also includes Lepton objects if enabled) and the specification file diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst index d051bee621..bd391c5655 100644 --- a/doc/src/Build_package.rst +++ b/doc/src/Build_package.rst @@ -14,10 +14,13 @@ package. In general there is no need to include a package if you never plan to use its features. If you get a run-time error that a LAMMPS command or style is -"Unknown", it is often because the command is contained in a package, -and your build did not include that package. Running LAMMPS with the -:doc:`-h command-line switch ` will print all the included -packages and commands for that executable. +"unknown", it is often because the command is contained in a package, +and your build did not include that package. If the command or style +*is* available in a package included in the LAMMPS distribution, +the error message will indicate which package would be needed. +Running LAMMPS with the :doc:`-h command-line switch ` +will print *all* optional commands and packages that were enabled +when building that executable. For the majority of packages, if you follow the single step below to include it, you can then build LAMMPS exactly the same as you would @@ -42,7 +45,7 @@ packages: The mechanism for including packages is simple but different for CMake versus make. -**CMake variables**\ : +**CMake build**\ : .. code-block:: bash @@ -136,9 +139,10 @@ src directory. **CMake shortcuts for installing many packages**\ : Instead of specifying all the CMake options via the command-line, -CMake allows initializing the variable cache using script files. These -are regular CMake files which can manipulate and set variables, and -can also contain control flow constructs. +CMake allows initializing its settings cache using script files. +These are regular CMake files which can manipulate and set CMake +variables (which represent selected options), and can also contain +control flow constructs for more complex operations. LAMMPS includes several of these files to define configuration "presets", similar to the options that exist for the Make based @@ -148,17 +152,17 @@ one of them as a starting point and customize it to your needs. .. code-block:: bash - cmake -C ../cmake/presets/all\_on.cmake [OPTIONS] ../cmake # enable all packages - cmake -C ../cmake/presets/all\_off.cmake [OPTIONS] ../cmake # disable all packages - cmake -C ../cmake/presets/minimal.cmake [OPTIONS] ../cmake # enable just a few core packages - cmake -C ../cmake/presets/most.cmake [OPTIONS] ../cmake # enable most common packages - cmake -C ../cmake/presets/nolib.cmake [OPTIONS] ../cmake # disable packages that do require extra libraries or tools - cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake # change settings to use the Clang compilers by default - cmake -C ../cmake/presets/mingw.cmake [OPTIONS] ../cmake # enable all packages compatible with MinGW compilers + cmake -C ../cmake/presets/all_on.cmake [OPTIONS] ../cmake # enable all packages + cmake -C ../cmake/presets/all_off.cmake [OPTIONS] ../cmake # disable all packages + cmake -C ../cmake/presets/minimal.cmake [OPTIONS] ../cmake # enable just a few core packages + cmake -C ../cmake/presets/most.cmake [OPTIONS] ../cmake # enable most common packages + cmake -C ../cmake/presets/nolib.cmake [OPTIONS] ../cmake # disable packages that do require extra libraries or tools + cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake # change settings to use the Clang compilers by default + cmake -C ../cmake/presets/mingw.cmake [OPTIONS] ../cmake # enable all packages compatible with MinGW compilers .. note:: - Running cmake this way manipulates the variable cache in your + Running cmake this way manipulates the CMake settings cache in your current build directory. You can combine multiple presets and options in a single cmake run, or change settings incrementally by running cmake with new flags. @@ -212,10 +216,12 @@ package" will list all the these commands. .. note:: - Installing or un-installing a package works by simply copying - files back and forth between the main src directory and - sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC), - so that the files are included or excluded when LAMMPS is built. + Installing or un-installing a package for the make based build process + works by simply copying files back and forth between the main source + directory src and the sub-directories with the package name (e.g. + src/KSPACE, src/USER-ATC), so that the files are included or excluded + when LAMMPS is built. Only source files in the src folder will be + compiled. The following make commands help manage files that exist in both the src directory and in package sub-directories. You do not normally diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index 3cee3fdd94..1e668ee95d 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -446,9 +446,10 @@ Exception handling when using LAMMPS as a library ------------------------------------------------------------------ This setting is useful when external codes drive LAMMPS as a library. -With this option enabled LAMMPS errors do not kill the caller. +With this option enabled, LAMMPS errors do not kill the calling code. Instead, the call stack is unwound and control returns to the caller, -e.g. to Python. +e.g. to Python. Of course the calling code has to be set up to +*catch* exceptions from within LAMMPS. **CMake variable**\ : diff --git a/doc/src/Modify_overview.rst b/doc/src/Modify_overview.rst index 9e60702046..495dc0fae8 100644 --- a/doc/src/Modify_overview.rst +++ b/doc/src/Modify_overview.rst @@ -32,14 +32,14 @@ If you wish to invoke those potentials in a LAMMPS input script with a command like -.. parsed-literal:: +.. code-block:: LAMMPS pair_style foo 0.1 3.5 then your pair\_foo.h file should be structured as follows: -.. parsed-literal:: +.. code-block:: c++ #ifdef PAIR_CLASS PairStyle(foo,PairFoo) @@ -58,7 +58,15 @@ the executable and can be invoked with a pair\_style command like the example above. Arguments like 0.1 and 3.5 can be defined and processed by your new class. -As illustrated by this pairwise example, many kinds of options are +.. note: + + With the traditional make process, simply adding the new files to the + src folder and compiling LAMMPS again for the desired configuration + with "make machine" is sufficient. When using CMake, you need to + re-run CMake with "cmake ." in the build folder to have it recognize + the added files and include them into the build system. + +As illustrated by this example pair style, many kinds of options are referred to in the LAMMPS documentation as the "style" of a particular command. @@ -66,11 +74,12 @@ The :doc:`Modify page ` lists all the common styles in LAMMPS, and discusses the header file for the base class that these styles are derived from. Public variables in that file are ones used and set by the derived classes which are also used by the base class. Sometimes -they are also used by the rest of LAMMPS. Virtual functions in the -base class header file which are set = 0 are ones you must define in -your new derived class to give it the functionality LAMMPS expects. -Virtual functions that are not set to 0 are functions you can -optionally define. +they are also used by the rest of LAMMPS. Pure functions, which means +functions declared as virtual in the base class header file which are +also set to 0, are functions you **must** implement in your new derived +class to give it the functionality LAMMPS expects. Virtual functions +that are not set to 0 are functions you may override or not. Those +are usually defined with an empty function body. Additionally, new output options can be added directly to the thermo.cpp, dump\_custom.cpp, and variable.cpp files. These are also @@ -82,21 +91,17 @@ functionality: * Think about whether what you want to do would be better as a pre- or post-processing step. Many computations are more easily and more quickly done that way. -* Don't do anything within the timestepping of a run that isn't - parallel. E.g. don't accumulate a bunch of data on a single processor - and analyze it. You run the risk of seriously degrading the parallel - efficiency. +* Do not try to do anything within the timestepping of a run that is not + parallel. For example do not accumulate a bunch of data on a single + processor and analyze it. You run the risk of seriously degrading + the parallel efficiency this way. * If your new feature reads arguments or writes output, make sure you follow the unit conventions discussed by the :doc:`units ` command. - - ---------- - .. _Foo: - **(Foo)** Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).