lqcdock

Description

A ready-to-use, cross-platform container to build Chroma (Jefferson Lab) and openQCD: it works on ARM64 and AMD64 (x86) architectures. Here is the content of this package:

• Dockerfile: the ubuntu:24.04 base image, the working tree and the shell environment.
• bash/: install.sh (installs the dependencies only) and welcome.sh (the welcome banner).
• script/: build_chroma.rb (fetches from git and builds QMP, QDP++ and Chroma) and build_openqcd.rb (builds openQCD).
• versions.txt: the QMP, QDP++ and Chroma commits the build was tested with.
• openqcd/: where the openQCD sources go; they end up inside the image.
• CHANGELOG.md: what changed from one version of this package to the next.
• LICENSE: the GNU General Public License v2, under which lqcdock is released.
• THIRD_PARTY_LICENSES.md: licences of the third-party software in the image.
• VERSION: the version of this package, read by the Dockerfile and shown by the welcome banner.

Difference with respect to laphbox: the Chroma, QDP++ and QMP sources are not shipped in the image, they are cloned from GitHub at build time, at the commits pinned in versions.txt. The laph packages (chroma_laph, last_laph) are not here, and neither are HDF5 and MKL, which only they needed.

Getting started on your laptop

Make sure Docker is installed on your local machine, with

>> docker --version

Then build the image and run the container:

>> docker build -t lqcdock .
>> docker run -h lqcdock -ti --rm lqcdock /bin/bash

If you need an image for an architecture other than your own (for instance x86 emulated on ARM) use buildx, which drives the QEMU emulator:

>> docker buildx version
>> docker buildx build --load --platform=linux/amd64 -t lqcdock .
>> docker run --platform=linux/amd64 -h lqcdock -ti --rm lqcdock /bin/bash

where:

• --platform selects the architecture the image is built for or run on. It is needed only when emulating a different architecture.
• --load loads the image into the local Docker daemon. It is not needed with docker build, but it is essential for cross-platform images.
• -h <HOST_NAME> sets the host name inside the container.
• -ti opens an interactive shell.
• --rm removes the container once it is stopped.

You can add -v <local/absolute/path>:/<container/absolute/path> to mount a volume, that is, a directory shared between your machine and the container.

Installing the dependencies

Inside the container, at first login:

>> cd /root
>> source install.sh

It installs compilers, autotools, OpenMPI, libxml2, BLAS/LAPACK, GSL, GMP, ruby, git and cmake, then writes the environment variables into ~/.bashrc and the list of the installed packages, with their versions, into /root/apt_requirements.txt. It is idempotent: if ~/install.log already exists it only upgrades.

If you prefer an image that already carries the dependencies, uncomment the RUN bash /root/install.sh line in the Dockerfile.

Building QMP, QDP++ and Chroma

>> cd $LQCD_ROOT/script
>> ruby build_chroma.rb

With no arguments it uses the defaults: MPI, OpenMP, double precision, cb2 layout, Nd = 4 and 3, make -j2. The most useful options:

option	effect
--nd 4	build the four-dimensional version only
--jobs 4	more parallel make jobs (mind the memory: Chroma is greedy)
--only chroma	rebuild one step only (fetch, qmp, qdpxx, chroma)
--comm serial	serial build, no MPI and no QMP
--prec single	single precision
--latest	follow the branch tips instead of the pinned commits
--dry-run	print the commands without running them
--interactive	ask for the choices on screen, like the older scripts

The result goes into $LQCD_ROOT/install, one directory per configuration, for instance chroma_mpi_omp_dp_cb2_4d. $LQCD_ROOT/build keeps the configure.log, build.log and install.log of every package.

To check that everything went well:

>> mpirun --allow-run-as-root -np 1 \
       $LQCD_ROOT/install/chroma_mpi_omp_dp_cb2_4d/bin/t_mesplq

It computes the average plaquette on a random gauge field and writes t_mesplq.xml.

Building openQCD

The openQCD sources are yours, already modified. They live in openqcd/ and end up in $LQCD_ROOT/src/openQCD-<version> inside the image; you can also mount another tree with -v and point at it with --src.

>> cd $LQCD_ROOT/script
>> ruby build_openqcd.rb --version 1.6

Only 1.6 and 2.4.2 are accepted and the script is fully non-interactive. There is nothing to configure: each tree carries its own main/Makefile, which picks the compiler flags according to ARCH_NAME and takes the MPI paths from MPI_INCLUDE and MPI_HOME, all three exported by the Dockerfile and by install.sh. The script only checks the environment and runs make in main/, where openQCD leaves its executables (ym1, qcd1, ms1, ...).

Versions of the Chroma sources

versions.txt pins one commit per package. The three current commits are the ones the whole chain was built and tested with, on ubuntu:24.04 with gcc 13.3.0.

Two warnings worth keeping in mind:

• the master branch of qdpxx and chroma does not compile with gcc 13: include/qdp_map_obj_disk.h is missing #include <array> and the build stops with "'std::array<long unsigned int, 2>' is incomplete". On the devel branch, the one used here, the line is there. For QMP, master is fine;
• the configure script shipped with QMP was generated with automake 1.15, which does not exist on Ubuntu 24.04: without a preliminary autoreconf -fi, make dies with "aclocal-1.15: command not found". build_chroma.rb takes care of it.

To update the pinned commits: run ruby build_chroma.rb --latest --refetch, check that everything still builds, then copy the new SHAs into versions.txt.

Saving your changes

Once you have built the environment, freeze the state of the container into a new image. This is done from outside the container with

>> docker ps                                   # to find the CONTAINER_ID
>> docker commit -p <CONTAINER_ID> <NEW_IMAGE_NAME>

where -p pauses the container while committing.

Requirements

If the build fails, compare the version of your packages, listed in /root/apt_requirements.txt, with the ones in the repository. If you know of package versions that give a smoother build, do not hesitate to get in touch or to push a new version of this package.

License

lqcdock is released under the GNU General Public License v2 (GPL-2.0-only): see LICENSE. The third-party software it builds or ships keeps its own licence; THIRD_PARTY_LICENSES.md summarises them.

Further documentation

• Chroma: https://jeffersonlab.github.io/chroma/
• openQCD: https://luscher.web.cern.ch/luscher/openQCD/

Contacts

davide.laudicina1@gmail.com