308 lines
12 KiB
ReStructuredText
308 lines
12 KiB
ReStructuredText
Include packages in build
|
|
=========================
|
|
|
|
In LAMMPS, a package is a group of files that enable a specific set of
|
|
features. For example, force fields for molecular systems or
|
|
rigid-body constraints are in packages. In the src directory, each
|
|
package is a subdirectory with the package name in capital letters.
|
|
|
|
An overview of packages is given on the :doc:`Packages <Packages>` doc
|
|
page. Brief overviews of each package are on the :doc:`Packages details
|
|
<Packages_details>` page.
|
|
|
|
When building LAMMPS, you can choose to include or exclude each
|
|
package. Generally, 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. 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 <Run_options>`
|
|
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
|
|
without any packages installed. A few packages may require additional
|
|
steps, as explained on the :doc:`Build extras <Build_extras>` page.
|
|
|
|
These links take you to the extra instructions for those select
|
|
packages:
|
|
|
|
.. this list must be kept in sync with its counterpart in Build_extras.rst
|
|
.. table_from_list::
|
|
:columns: 6
|
|
|
|
* :ref:`ADIOS <adios>`
|
|
* :ref:`ATC <atc>`
|
|
* :ref:`AWPMD <awpmd>`
|
|
* :ref:`COLVARS <colvar>`
|
|
* :ref:`COMPRESS <compress>`
|
|
* :ref:`ELECTRODE <electrode>`
|
|
* :ref:`GPU <gpu>`
|
|
* :ref:`H5MD <h5md>`
|
|
* :ref:`INTEL <intel>`
|
|
* :ref:`KIM <kim>`
|
|
* :ref:`KOKKOS <kokkos>`
|
|
* :ref:`LEPTON <lepton>`
|
|
* :ref:`MACHDYN <machdyn>`
|
|
* :ref:`MDI <mdi>`
|
|
* :ref:`MISC <misc>`
|
|
* :ref:`ML-HDNNP <ml-hdnnp>`
|
|
* :ref:`ML-IAP <mliap>`
|
|
* :ref:`ML-PACE <ml-pace>`
|
|
* :ref:`ML-POD <ml-pod>`
|
|
* :ref:`ML-QUIP <ml-quip>`
|
|
* :ref:`MOLFILE <molfile>`
|
|
* :ref:`NETCDF <netcdf>`
|
|
* :ref:`OPENMP <openmp>`
|
|
* :ref:`OPT <opt>`
|
|
* :ref:`PLUMED <plumed>`
|
|
* :ref:`POEMS <poems>`
|
|
* :ref:`PYTHON <python>`
|
|
* :ref:`QMMM <qmmm>`
|
|
* :ref:`RHEO <rheo>`
|
|
* :ref:`SCAFACOS <scafacos>`
|
|
* :ref:`VORONOI <voronoi>`
|
|
* :ref:`VTK <vtk>`
|
|
|
|
The mechanism for including packages is simple but different for CMake
|
|
versus make.
|
|
|
|
.. tabs::
|
|
|
|
.. tab:: CMake build
|
|
|
|
.. code-block:: csh
|
|
|
|
-D PKG_NAME=value # yes or no (default)
|
|
|
|
Examples:
|
|
|
|
.. code-block:: csh
|
|
|
|
-D PKG_MANYBODY=yes
|
|
-D PKG_INTEL=yes
|
|
|
|
All packages are included the same way. See the shortcut section
|
|
below for how to install many packages at once with CMake.
|
|
|
|
.. note::
|
|
|
|
If you switch between building with CMake and make builds, no
|
|
packages in the src directory can be installed when you invoke
|
|
``cmake``. CMake will give an error if that is not the case,
|
|
indicating how you can uninstall all packages in the src dir.
|
|
|
|
.. tab:: Traditional make
|
|
|
|
.. code-block:: bash
|
|
|
|
cd lammps/src
|
|
make ps # check which packages are currently installed
|
|
make yes-name # install a package with name
|
|
make no-name # uninstall a package with name
|
|
make mpi # build LAMMPS with whatever packages are now installed
|
|
|
|
Examples:
|
|
|
|
.. code-block:: bash
|
|
|
|
make no-rigid
|
|
make yes-intel
|
|
|
|
All packages are included the same way. See the shortcut section
|
|
below for how to install many packages at once with make.
|
|
|
|
.. note::
|
|
|
|
You must always re-build LAMMPS (via make) after installing or
|
|
uninstalling a package, for the action to take effect. The
|
|
included dependency tracking will make certain only files that
|
|
are required to be rebuilt are recompiled.
|
|
|
|
.. note::
|
|
|
|
You cannot install or uninstall packages and build LAMMPS in a
|
|
single make command with multiple targets, e.g. ``make
|
|
yes-colloid mpi``. This is because the make procedure creates
|
|
a list of source files that will be out-of-date for the build
|
|
if the package configuration changes within the same command.
|
|
You can include or exclude multiple packages in a single make
|
|
command, e.g. ``make yes-colloid no-manybody``.
|
|
|
|
|
|
Information for both build systems
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Almost all packages can be included or excluded in a LAMMPS build,
|
|
independent of the other packages. However, some packages include files
|
|
derived from files in other packages. LAMMPS checks for this and does
|
|
the right thing. Individual files are only included if their
|
|
dependencies are already included. Likewise, if a package is excluded,
|
|
other files dependent on that package are also excluded.
|
|
|
|
.. note::
|
|
|
|
By default no packages are installed. Prior to August 2018, however,
|
|
if you downloaded a tarball, 3 packages (KSPACE, MANYBODY, MOLECULE)
|
|
were pre-installed via the traditional make procedure in the ``src``
|
|
directory. That is no longer the case, so that CMake will build
|
|
as-is without needing to uninstall those packages.
|
|
|
|
----------
|
|
|
|
.. _cmake_presets:
|
|
|
|
CMake presets for installing many packages
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Instead of specifying all the CMake options via the command-line,
|
|
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
|
|
system. Using these files, you can enable/disable portions of the
|
|
available packages in LAMMPS. If you need a custom preset, you can
|
|
make a copy of one of them and modify it to suit your needs.
|
|
|
|
.. code-block:: bash
|
|
|
|
# enable just a few core packages
|
|
cmake -C ../cmake/presets/basic.cmake [OPTIONS] ../cmake
|
|
|
|
# enable most packages
|
|
cmake -C ../cmake/presets/most.cmake [OPTIONS] ../cmake
|
|
|
|
# enable packages which download sources or potential files
|
|
cmake -C ../cmake/presets/download.cmake [OPTIONS] ../cmake
|
|
|
|
# disable packages that do require extra libraries or tools
|
|
cmake -C ../cmake/presets/nolib.cmake [OPTIONS] ../cmake
|
|
|
|
# change settings to use the Clang compilers by default
|
|
cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake
|
|
|
|
# change settings to use the GNU compilers by default
|
|
cmake -C ../cmake/presets/gcc.cmake [OPTIONS] ../cmake
|
|
|
|
# change settings to use the Intel compilers by default
|
|
cmake -C ../cmake/presets/intel.cmake [OPTIONS] ../cmake
|
|
|
|
# change settings to use the PGI compilers by default
|
|
cmake -C ../cmake/presets/pgi.cmake [OPTIONS] ../cmake
|
|
|
|
# enable all packages
|
|
cmake -C ../cmake/presets/all_on.cmake [OPTIONS] ../cmake
|
|
|
|
# disable all packages
|
|
cmake -C ../cmake/presets/all_off.cmake [OPTIONS] ../cmake
|
|
|
|
# compile with MinGW cross-compilers
|
|
mingw64-cmake -C ../cmake/presets/mingw-cross.cmake [OPTIONS] ../cmake
|
|
|
|
# compile serial multi-arch binaries on macOS
|
|
cmake -C ../cmake/presets/macos-multiarch.cmake [OPTIONS] ../cmake
|
|
|
|
Presets that have names starting with "windows" are specifically for
|
|
compiling LAMMPS :doc:`natively on Windows <Build_windows>` and
|
|
presets that have names starting with "kokkos" are specifically for
|
|
selecting configurations for compiling LAMMPS with :ref:`KOKKOS <kokkos>`.
|
|
|
|
.. note::
|
|
|
|
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. If you use a present for selecting a set of
|
|
compilers, it will reset all settings from previous CMake runs.
|
|
|
|
|
|
Example
|
|
"""""""
|
|
|
|
.. code-block:: bash
|
|
|
|
# build LAMMPS with most commonly used packages, but then remove
|
|
# those requiring additional library or tools, but still enable
|
|
# GPU package and configure it for using CUDA. You can run.
|
|
mkdir build
|
|
cd build
|
|
cmake -C ../cmake/presets/most.cmake -C ../cmake/presets/nolib.cmake \
|
|
-D PKG_GPU=on -D GPU_API=cuda ../cmake
|
|
|
|
# to add another package, say BODY to the previous configuration you can run:
|
|
cmake -D PKG_BODY=on .
|
|
|
|
# to reset the package selection from above to the default of no packages
|
|
# but leaving all other settings untouched. You can run:
|
|
cmake -C ../cmake/presets/all_off.cmake .
|
|
|
|
----------
|
|
|
|
Make shortcuts for installing many packages
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The following commands are useful for managing package source files
|
|
and their installation when building LAMMPS via traditional make.
|
|
Just type ``make`` in lammps/src to see a one-line summary.
|
|
|
|
These commands install/uninstall sets of packages:
|
|
|
|
.. code-block:: bash
|
|
|
|
make yes-all # install all packages
|
|
make no-all # check for changes and uninstall all packages
|
|
make no-installed # only check and uninstall installed packages
|
|
make yes-basic # install a few commonly used packages'
|
|
make no-basic # remove a few commonly used packages'
|
|
make yes-most # install most packages w/o libs'
|
|
make no-most # remove most packages w/o libs'
|
|
make yes-lib # install packages that require extra libraries
|
|
make no-lib # uninstall packages that require extra libraries
|
|
make yes-ext # install packages that require external libraries
|
|
make no-ext # uninstall packages that require external libraries
|
|
|
|
which install/uninstall various sets of packages. Typing ``make
|
|
package`` will list all the these commands.
|
|
|
|
.. note::
|
|
|
|
Installing or uninstalling a package for the make based build process
|
|
works by simply copying files back and forth between the main source
|
|
directory src and the subdirectories with the package name (e.g.
|
|
src/KSPACE, src/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 subdirectories. You do not normally
|
|
need to use these commands unless you are editing LAMMPS files or are
|
|
updating LAMMPS via git.
|
|
|
|
Type ``make package-status`` or ``make ps`` to show which packages are
|
|
currently installed. For those that are installed, it will list any
|
|
files that are different in the src directory and package
|
|
subdirectory.
|
|
|
|
Type ``make package-installed`` or ``make pi`` to show which packages are
|
|
currently installed, without listing the status of packages that are
|
|
not installed.
|
|
|
|
Type ``make package-update`` or ``make pu`` to overwrite src files with
|
|
files from the package subdirectories if the package is installed. It
|
|
should be used after the checkout has been :doc:`updated or changed
|
|
with git <Install_git>`, this will only update the files in the package
|
|
subdirectories, but not the copies in the src folder.
|
|
|
|
Type ``make package-overwrite`` to overwrite files in the package
|
|
subdirectories with src files.
|
|
|
|
Type ``make package-diff`` to list all differences between pairs of
|
|
files in both the source directory and the package directory.
|