\(\renewcommand{\AA}{\text{Å}}\)

2.6. Download the LAMMPS source with git

LAMMPS development is coordinated through the “LAMMPS GitHub site”. If you clone the LAMMPS repository onto your local machine, it has several advantages:

• You can stay current with changes to LAMMPS with a single git command.

• You can create your own development branches to add code to LAMMPS.

• You can submit your new features back to GitHub for inclusion in LAMMPS. For that, you should first create your own fork on GitHub, though.

You must have git installed on your system to use the commands explained below to communicate with the git servers on GitHub. For people still using subversion (svn), GitHub also provides limited support for subversion clients.

Note

As of October 2016, the official home of public LAMMPS development is on GitHub. The previously advertised LAMMPS git repositories on git.lammps.org and bitbucket.org are now offline or deprecated.

You can follow the LAMMPS development on 4 different git branches:

• develop : this branch follows the ongoing development and is updated with every merge commit of a pull request

• releasethis branch is updated with every “feature release”;

  updates are always “fast-forward” merges from develop

• maintenance : this branch collects back-ported bug fixes from the develop branch to the stable branch. It is used to update the stable branch for “stable update releases”.

• stable : this branch is updated from the release branch with every “stable release” version and also has selected bug fixes with every “update release” when the maintenance branch is merged into it

To access the git repositories on your box, use the clone command to create a local copy of the LAMMPS repository with a command like:

git clone -b release https://github.com/lammps/lammps.git mylammps

where “mylammps” is the name of the directory you wish to create on your machine and “release” is one of the 3 branches listed above. (Note that you actually download all 3 branches; you can switch between them at any time using “git checkout <branch name>”.)

Saving time and disk space when using git clone

The complete git history of the LAMMPS project is quite large because it contains the entire commit history of the project since fall 2006, which includes the time when LAMMPS was managed with subversion. This includes a few commits that have added and removed some large files (mostly by accident). If you do not need access to the entire commit history (most people don’t), you can speed up the “cloning” process and reduce local disk space requirements by using the --depth git command line flag. That will create a “shallow clone” of the repository, which contains only a subset of the git history. Using a depth of 1000 is usually sufficient to include the head commits of the develop, the release, and the maintenance branches. To include the head commit of the stable branch you may need a depth of up to 10000. If you later need more of the git history, you can always convert the shallow clone into a “full clone”.

Once the command completes, your directory will contain the same files as if you unpacked a current LAMMPS tarball, with the exception, that the HTML documentation files are not included. They can be generated from the content provided in doc/src by typing make html from the doc directory.

After initial cloning, as bug fixes and new features are added to LAMMPS you can stay up-to-date by typing the following git commands from within the “mylammps” directory:

git checkout release      # not needed if you always stay in this branch
git checkout stable       # use one of these 4 checkout commands
git checkout develop      # to choose the branch to follow
git checkout maintenance
git pull

Doing a “pull” will not change any files you have added to the LAMMPS directory structure. It will also not change any existing LAMMPS files you have edited, unless those files have changed in the repository. In that case, git will attempt to merge the changes from the repository file with your version of the file and tell you if there are any conflicts. See the git documentation for details.

If you want to access a particular previous release version of LAMMPS, you can instead “check out” any version with a published tag. See the output of git tag -l for the list of tags. The git command to do this is as follows.

git checkout tagID

Stable versions and what tagID to use for a particular stable version are discussed on this page. Note that this command will print some warnings, because in order to get back to the latest revision and to be able to update with git pull again, you will need to do git checkout release (or check out any other desired branch) first.

Once you have updated your local files with a git pull (or git checkout), you still need to re-build LAMMPS if any source files have changed. How to do this depends on the build system you are using.

CMake buildTraditional make

Change to your build folder and type:

cmake --build .

CMake should auto-detect whether it needs to re-run the CMake configuration step and otherwise redo the build for all files that have been changed or files that depend on changed files. In case some build options have been changed or renamed, you may have to update those by running:

cmake .

and then rebuild.

Git protocols

The servers at github.com support the “https” access protocol for anonymous, read-only access. If you have a suitably configured GitHub account, you may also use SSH protocol with the URL git@github.com:lammps/lammps.git.

The LAMMPS GitHub project is currently overseen by Axel Kohlmeyer (Temple U, akohlmey at gmail.com).