GROMACS on GitHub: a backup mirror, not the place work happens

Why the canonical project lives on GitLab

The repository description is unusual for a GitHub project and worth reading before anything else. It identifies gromacs/gromacs as the public and backup repository of the GROMACS molecular simulation toolkit, and it asks readers not to mine the metadata blindly, pointing instead at the GitLab project for code review and issue tracking. The README repeats the instruction: report bugs at the GitLab issue tracker, and there are no GitHub releases attached to this repository at all.

The practical consequences are direct. A bug report filed on GitHub will not reach the workflow the project runs. A pull request opened here is not where the review happens, and the continuous integration configuration for the project lives in the .gitlab-ci.yml file at the root, next to a .gitlab directory, which is where the pipeline definitions are kept. The GitHub side has its own .github directory for repository-level configuration, but the build and test pipeline is a GitLab one.

So the sensible way to treat this repository is as a mirror with a public history: a place to read the code, to clone from, to browse the tree, and to look at how the project is laid out. Work goes to GitLab.

That arrangement is not unusual in research software, where the hosting history of a project predates the current host, but it does trip up newcomers who find the repository through a search and assume the visible buttons do something. It is also a reminder of how much of scientific software infrastructure still runs on the conventions of a particular community rather than on the defaults of the largest code host.

The project itself is a molecular simulation toolkit written in C++, with a homepage at gromacs.org, an installation guide in the online manual, and a discussion forum at forums.gromacs.org.

One build system, and where the build instructions actually live

The README's advice to anyone familiar with Unix is that compiling and installing GROMACS should be fairly trivial, and that the project uses only the CMake build system. The word only is the meaningful part. A codebase that has grown over decades often accumulates several build paths, and each one multiplies the number of ways a build can fail on a new platform. Refusing a second build system removes that class of problem.

The build configuration is visible in the repository root. There is a CMakeLists.txt at the top, a cmake directory with the module files, a CPackInit.cmake for packaging, a CTestConfig.cmake for the test harness, and a .clang-format file that pins the C++ formatting rules, which is how a project keeps a large mixed-provenance code base consistent. The Python side of the tree has its own tooling, with a .flake8 file and a .black.toml for formatting, and a python_packaging directory that holds the packaging definition for the Python components.

The installation instructions are not in this repository in any meaningful sense. The README links to the installation guide in the current documentation, hosted with the manual at manual.gromacs.org, and it repeats the request to read the installation instructions before contacting the developers. There is an INSTALL-dev file in the root for developers, which sits alongside a docs directory for the rest of the documentation, and an admin directory plus a scripts directory for the maintainer-facing tooling.

The directory listing otherwise describes a scientific code project with a normal anatomy. The src directory holds the implementation, api holds the public interface layer, share holds the data files the code needs at runtime, tests holds the test suite, and the .black.toml and .clang-format files at the root show that both the C++ and the Python parts are held to a single formatting standard. The git history carries a .git-blame-ignore-revs file, which lists commits that changed formatting only so that blame stays useful, a small sign of the kind of discipline a project of this age has had to adopt.

The LGPL clause that says more than the LGPL does

The licence is GNU LGPL version 2.1, and the README spends more space on it than on any technical topic. The reason it spells out the obligations in plain language is that the obligations go past what most people read in a licence file.

The stated reasoning is that scientific software is a little special compared to most other programs. Everyone who uses the toolkit depends on the quality of the code, and when a bug is found it has to be possible to correct it and to say that it was fixed in version X of a file or a package release, and to reproduce other people's results from a given version. That argument is about reproducibility, and it is the reason the project asks that modifications be pushed into the main distribution rather than kept as private forks.

The practical rules the README states for anyone who does distribute a modified version or uses part of GROMACS in their own program are these. The entire project must be licensed according to the requirements of the LGPL v2.1. The work must be clearly labeled as derived work. It should not use the name official GROMACS. And support questions have to be directed to the distributor rather than to the GROMACS developers, so that a patched build does not send its users to people who cannot see the patch.

The last point is the one that catches teams out. A group that patches the source for their own cluster, keeps the changes internal and does not announce them, is still running something the upstream project cannot help with, and the README's instruction is a warning about where a bug report should go in that situation. The closing line of the paragraph says the hard wording is meant to protect your research results, which reframes the whole section: the concern is that a result produced with an untraceable patch is a result nobody can reproduce.

This describes the published terms and the project's stated policy, not legal advice.

The contribution contract: MPI, threads and double precision

The README explains how it wants changes to arrive. The preferred route is to get modifications included in the main distribution, and the project says it will consider any decent code. For a separate program, the suggestion is that it can probably be included in the contrib directory straight away, with the parenthetical that contrib is not supported by the project itself. For major changes in the main code, the request is that you first test that the work works with, and without, MPI, threads and double precision.

That sentence is the whole engineering culture of the project in miniature. A molecular dynamics toolkit has to give the same answer whether it runs on one core, on many cores through MPI, on threads, or in double precision, and a change that only works in the configuration the developer happens to use is a change that breaks somebody's results. The three axes named in the README are the three that change the numerical behaviour of a run, which is why they are the ones that get called out.

The repository layout supports that approach. There is a tests directory at the root, a CTestConfig.cmake that wires the suite into CTest, and a scripts directory for the tooling that runs it. A project that asks contributors to test across build configurations needs that infrastructure to be in place, and it is.

The corollary for anyone evaluating the project as a dependency is worth stating plainly. GROMACS is not a library you are meant to link against. The README's guidance for using part of GROMACS in your own program is framed as a licensing question about derived work, not as a supported embedding API, so an application that wants to call into the simulation engine is outside what the project documents.

Citation treated as part of the software contract

The README asks users of the toolkit, for research or other purposes, to make sure they reference the correct version of the code, and it points to the CITATION.cff file next to the README as holding all the metadata useful for citation. That file is at the root of the repository, and it is a machine-readable citation format, which is what makes automated referencing of a specific release possible rather than a manual chore.

The papers listed in the README are the historical record of the code, and they are arranged in a way that tells you how the project has changed. The 1995 paper in Computer Physics Communications describes GROMACS as a message-passing parallel molecular dynamics implementation by Berendsen, van der Spoel and van Drunen. The 2008 Journal of Chemical Theory and Computation paper covers GROMACS 4 and its algorithms for efficient, load-balanced and scalable molecular simulation. A 2013 Bioinformatics paper describes the 4.5 release as a high-throughput and highly parallel open source molecular simulation toolkit. A 2015 chapter in the Lecture Notes in Computer Science volume on exascale software challenges covers the multi-level parallelism work, and a 2015 SoftwareX paper describes the same theme, high performance molecular simulations through multi-level parallelism from laptops to supercomputers.

Each entry carries a DOI, and the title of the last two, both from 2015, is the clearest statement of the design goal: a single code that runs on a laptop and on a supercomputer.

For an engineer choosing software, this has a practical consequence beyond citation etiquette. A project that requires version-level provenance and asks contributors to keep behaviour identical across MPI, thread and precision configurations is a project where results are expected to be reproducible. That is a differentiator when the output is a paper, and it is also an argument for using the released version rather than a patched build, since a patch is exactly the thing the citation policy is designed to expose.

Funding, supporters and what the maintainers say about their own limits

The financial picture is stated without embellishment. The development of GROMACS is mainly funded by academic research grants. The project asks users to cite the GROMACS papers to help fund that work, and it lists the papers as the mechanism rather than asking for money directly.

There is a donations route, and it is described as accepting all kinds of donations, in the form of code, hardware and funding. Industrial users are given one specific option: paying for a licence pro bono, and the README notes that the licence remains LGPL and can be redistributed freely, so a pro bono arrangement does not change the terms under which the code travels. Users who contribute in other ways are listed as GROMACS supporters on the project webpages, which is a form of recognition rather than a contractual arrangement.

The project also states its own limits plainly, in a sentence that is more candid than most: there are a lot of features it would like to include in future versions, but its resources are limited. For a toolkit used in research, that is an honest constraint rather than a warning, but it does mean feature requests rarely get priority over correctness and reproducibility work, which is exactly where a scientific code project should spend its time.

The contact point for a commercial arrangement is given in the README, and the tone throughout is that of a volunteer project with academic funding and a professional user base. The README closes with a simple Good luck with your simulations, signed by The GROMACS Crew, which sets the right expectation for what kind of support you are getting.

Editorial conclusion

Adopt the GitHub repository as a read-only reference and a source of truth for the published tree, and send every issue, patch and review comment to the GitLab project, because that is where the maintainers work and where the tooling is configured. It is the wrong place to open a pull request or to expect a response. Before basing a published study on a build, check the CITATION.cff file for the version metadata and cite the specific paper that matches your version, and if you distribute a modified build, label it as derived work and do not call it official GROMACS.

Frequently asked questions

Official sources

1. gromacs/gromacs on GitHub
2. Issues
3. License: LGPL-2.1
4. Project website
5. README