leonarski_f
84228bf8be
Build Packages / Create release (push) Successful in 24s
Build Packages / build:viewer:macos-arm64:nocuda (push) Successful in 3m29s
Build Packages / build:rugnux:macos-arm64:nocuda (push) Successful in 2m43s
Build Packages / build:rugnux:linux-aarch64:cuda (push) Successful in 8m27s
Build Packages / build:rugnux:linux-x86_64:cuda (push) Successful in 9m53s
Build Packages / build:viewer:linux-x86_64:nocuda (push) Successful in 9m58s
Build Packages / build:viewer:linux-x86_64:cuda (push) Successful in 11m22s
Build Packages / build:jfjoch:rocky8:nocuda (push) Successful in 13m39s
Build Packages / build:viewer:windows-x86_64:nocuda (push) Successful in 18m37s
Build Packages / build:jfjoch:rocky9:nocuda (push) Successful in 16m32s
Build Packages / build:viewer:windows-x86_64:cuda (push) Successful in 24m11s
Build Packages / HDF5 consumer tests (DIALS, XDS) (push) Successful in 25m30s
Build Packages / build:jfjoch:ubuntu2404:nocuda (push) Successful in 19m3s
Build Packages / build:jfjoch:ubuntu2204:nocuda (push) Successful in 20m23s
Build Packages / build:jfjoch:rocky8:cuda-sls9 (push) Successful in 19m41s
Build Packages / Generate python client (push) Successful in 50s
Build Packages / Build documentation (push) Successful in 1m16s
Build Packages / build:jfjoch:rocky9:cuda-sls9 (push) Successful in 21m0s
Build Packages / build:jfjoch:rocky8:cuda (push) Successful in 18m38s
Build Packages / build:rugnux:windows-x86_64:cuda (push) Successful in 14m33s
Build Packages / build:jfjoch:rocky9:cuda (push) Successful in 17m55s
Build Packages / build:jfjoch:ubuntu2204:cuda (push) Successful in 20m50s
Build Packages / build:jfjoch:ubuntu2404:cuda (push) Successful in 18m38s
Build Packages / Unit tests (push) Successful in 1h46m14s
* jfjoch_broker: Optional per-dataset authentication - statistics, images and plots can require a bearer token, which jfjoch_viewer supports. * jfjoch_viewer: Dark mode and a theme-matched colour scheme, a magnifier panel, and simpler contrast and background controls. * Rugnux: Multiple performance improvements on GPU and CPU (CPU-only processing up to 40% faster, faster image decoding on ARM), with unchanged results. * Rugnux: `--model` rigid-body refinement runs on the GPU, and the model-validation check is faster and more reliable. * Rugnux: Improved scaling and merging - error model, outlier rejection, absorption correction and French-Wilson amplitudes now agree more closely with XDS and ctruncate. * Rugnux: Improved integration - radial background on powder and ice rings, crowded rotation data keep their reflections, and CPU-only builds integrate large unit cells as GPU builds do. * Rugnux: More robust detector geometry - measured beam centre, X-ray bandwidth and goniometer rate, and geometry refinement accepted only on significant evidence. * Rugnux: Merged files are written in the standard setting, or in the setting of a reference MTZ, structure-factor mmCIF or model, with its free-R flags. * Rugnux: Richer report - ice and powder rings, further lattices, superstructure candidates and mosaicity, with warnings worded as prompts to check. * Rugnux: Clear error messages when a data set needs more GPU or host memory than is available. Reviewed-on: #83 Co-authored-by: Filip Leonarski <filip.leonarski@psi.ch>
200 lines
13 KiB
Markdown
200 lines
13 KiB
Markdown
# Release contents
|
|
|
|
This page describes **what a Jungfraujoch release ships and what each artefact needs on the target
|
|
machine** — which CPU instruction set the binaries were compiled for, which CUDA toolkit they were
|
|
built against, and which runtime libraries are bundled rather than expected from the host.
|
|
|
|
The artefacts in the table below are built and published by the continuous-integration pipeline
|
|
(`.gitea/workflows/build_and_test.yml`) when a tag is pushed. For *how* to install and configure the
|
|
result see [Deployment](DEPLOYMENT.md); for the package-repository URLs see
|
|
[Linux package repositories](REPOSITORIES.md).
|
|
|
|
## Artefacts
|
|
|
|
| Artefact | Distributed via | Contains |
|
|
| --- | --- | --- |
|
|
| `.rpm` / `.deb` packages | [package repositories](REPOSITORIES.md) | The full server stack: `jfjoch` (broker, frontend, FPGA and detector tools), `jfjoch-writer`, `jfjoch-viewer` (incl. the XDS plugin), `jfjoch-driver-dkms`, and `rugnux` (offline analysis, independent of the rest) |
|
|
| `jfjoch_viewer-<version>-linux-cuda<major>.tgz`, `...-linux-cpu.tgz` | Gitea release page | Portable Linux viewer: `jfjoch_viewer`, its desktop entry, icon and D-Bus service, and the license notices |
|
|
| `jfjoch-viewer-<version>-win64-cuda<major>.exe`, `...-win64-cpu.exe` | Gitea release page | Windows installer for `jfjoch_viewer`, plus the Qt runtime |
|
|
| `jfjoch-viewer-<version>-macos-arm64.dmg` | Gitea release page | macOS disk image with `jfjoch_viewer.app` (Apple Silicon), the Qt runtime and the license notices inside the app |
|
|
| `rugnux-<version>-linux-x86_64-cuda<major>.tgz` | Gitea release page | Portable Linux [`rugnux`](RUGNUX.md), the offline analysis CLI, and the license notices. One executable |
|
|
| `rugnux-<version>-linux-aarch64-cuda<major>.tgz` | Gitea release page | The same, cross-built for 64-bit Arm — NVIDIA GH200 and DGX Spark |
|
|
| `rugnux-<version>-win64-cuda<major>.zip` | Gitea release page | The same for Windows, plus the cuFFT DLL |
|
|
| `rugnux-<version>-macos-arm64-cpu.tgz` | Gitea release page | The same for macOS on Apple Silicon, CPU only |
|
|
| `jfjoch-writer` `.rpm` / `.deb` | Gitea release page | The writer alone, for a file-writing machine without the rest of the stack |
|
|
| `libjfjoch_xds_plugin.so.<version>` | Gitea release page | XDS HDF5 read plugin (built on RHEL 8); see [Integration with MX software](SOFTWARE_INTEGRATION.md) |
|
|
| `jfjoch-client` | [PyPI](https://pypi.org/project/jfjoch-client/) and the Gitea PyPI index | Generated Python OpenAPI client |
|
|
| Documentation | [Read the Docs](https://jungfraujoch.readthedocs.io) and the `gitea-pages` branch | This documentation set |
|
|
|
|
The FPGA firmware (`.mcs`) images are attached to the release as well. The firmware is stable and is
|
|
carried from version to version, and is rebuilt with Vivado (see [FPGA smartNIC](FPGA.md)) when it
|
|
needs to change — so a card keeps its image across a software upgrade unless the release notes say
|
|
otherwise.
|
|
|
|
## CPU instruction set
|
|
|
|
The architecture flags live in the CI configuration rather than in `CMakeLists.txt`, so a site
|
|
building from source picks its own (`x86-64-v4` on an AVX-512 cluster, `-march=native`, or the plain
|
|
baseline the compiler defaults to). The released binaries are compiled to a fixed floor:
|
|
|
|
| Release | Flags | Minimum CPU |
|
|
| --- | --- | --- |
|
|
| Linux (all packages, and the portable `.tgz`) | `-march=x86-64-v3 -flto=auto` | AVX2 + FMA + BMI2 — Intel Haswell (2013) / AMD Zen (2017) and newer |
|
|
| Windows installer | `/arch:AVX` | AVX — Intel Sandy Bridge (2011) / AMD Bulldozer and newer |
|
|
| macOS `.dmg` and `rugnux` `.tgz` | none (the compiler's default Apple Silicon target) | Any Apple Silicon Mac — M1 and newer |
|
|
|
|
The Windows floor is lower because MSVC has no spelling for the `x86-64-v2` level; `/arch:AVX` is
|
|
the nearest one and implies SSE4.1/4.2, which is what actually matters — without it Eigen has no
|
|
vectorised `round` and falls back to a libm call per element. Link-time optimisation is applied on
|
|
Linux only. The macOS artefacts need no flag: the Apple compiler's default target is already the
|
|
M1, the oldest Apple Silicon chip.
|
|
|
|
A binary will fault with an illegal instruction on a CPU below its floor. If you must run on older
|
|
hardware, build from source without the flags.
|
|
|
|
## Operating-system floor
|
|
|
|
The `.rpm` / `.deb` packages are built per distribution (RHEL/Rocky 8 and 9, Ubuntu 22.04 and 24.04)
|
|
and are tied to it. The portable viewer `.tgz` and the **x86_64** `rugnux` `.tgz` are built on
|
|
RHEL 8, the oldest supported distribution, so their glibc floor is low enough to run on any newer
|
|
Linux — that is what they are for, and why they replace the per-distro packaging of those programs
|
|
on the release page. The **aarch64** `rugnux` `.tgz` is the exception: it is cross-built against
|
|
Ubuntu 24.04, so it needs glibc 2.39 or newer (which DGX OS 7 and any current Arm server distribution
|
|
have). The Windows installer is built and verified on Windows 11. The macOS artefacts need
|
|
**macOS 13 (Ventura) or newer** — the floor of the Qt 6.11 they bundle — and an **Apple Silicon**
|
|
Mac; see [macOS](#macos) below.
|
|
|
|
**The portable archives have no top-level directory.** They unpack straight into `bin/` and
|
|
`share/`, so always extract them into a directory of their own (`tar xzf … -C /opt/rugnux-<version>`)
|
|
rather than into a working directory.
|
|
|
|
## CUDA and non-CUDA builds
|
|
|
|
Every Linux and Windows binary artefact is released in **two variants**, `cuda<major>` and `cpu`
|
|
(the macOS ones exist only as `cpu`: there is no CUDA on macOS). The CUDA variant adds
|
|
the GPU fast-feedback indexer (`ffbidx`), the GPU FFT indexer and GPU image processing; the CPU-only
|
|
variant runs the same pipeline on the CPU with the FFTW indexer, at much lower throughput.
|
|
|
|
The CUDA toolkit used is the one on the corresponding build machine: **CUDA 12** for the RHEL 8
|
|
packages, **CUDA 13** for RHEL 9, Ubuntu and Windows. The major version is part of the artefact and
|
|
repository name, so a download is self-identifying. Building from source needs CUDA 12.8 or newer.
|
|
|
|
**A CUDA build does not require a CUDA machine.** Jungfraujoch asks how many CUDA devices are
|
|
present at start-up and treats "none" (including "no driver installed") as zero GPUs, falling back
|
|
to the CPU path. So a CUDA build starts and runs correctly on a machine with no NVIDIA GPU at all.
|
|
What each artefact has to find at run time differs:
|
|
|
|
- **Portable Linux `.tgz`** — nothing. The CUDA runtime, the fast-feedback indexer **and cuFFT** are
|
|
all linked statically, so each archive is a single executable that depends on nothing but the C
|
|
and C++ runtimes. On a GPU machine the NVIDIA driver is the only NVIDIA component needed.
|
|
- **Windows installer and `.zip`** — the CUDA toolkit ships no static cuFFT for Windows, so the
|
|
cuFFT DLL is **part of the distribution**, next to the executable. No CUDA toolkit is needed.
|
|
- **`.rpm` / `.deb`** — these deliberately keep cuFFT dynamic, so that one dependency is managed
|
|
centrally with the rest of CUDA. Install the cuFFT package alongside, or use the `nocuda`
|
|
repositories on a machine where CUDA is not wanted.
|
|
|
|
Static CUDA linkage makes the Linux CUDA artefacts substantially bigger than the CPU ones, and the
|
|
Windows cuFFT DLL is ~256 MB — which is the other reason for shipping both variants.
|
|
|
|
On a machine with an NVIDIA GPU, take the CUDA variant: only that one uses the GPU.
|
|
|
|
## GPU generations and the NVIDIA driver
|
|
|
|
A CUDA variant carries compiled device code for a fixed set of GPU generations, and which
|
|
generations those are follows from the CUDA toolkit it was built with. The CUDA runtime is linked
|
|
statically, so the only NVIDIA component the target machine has to supply is the **driver** — there
|
|
is no CUDA-toolkit version requirement on the host.
|
|
|
|
| Artefact | CUDA toolkit | GPU generations | Minimum driver |
|
|
| --- | --- | --- | --- |
|
|
| RHEL 8 packages, portable viewer `.tgz`, x86_64 `rugnux` `.tgz` | 12.9 | Volta (V100) through Blackwell: `sm_70`, `75`, `80`, `86`, `89`, `90`, `100`, `120`, `121` | 525.60.13 |
|
|
| RHEL 9 and Ubuntu packages, Windows installer, Windows `rugnux` `.zip` | 13.x | Turing (T4) through Blackwell: the same list **without** `sm_70` | 580.65.06 (Linux), R580 (Windows) |
|
|
| aarch64 `rugnux` `.tgz` | 13.x | `sm_90` (GH200) and `sm_121` (DGX Spark) only | 580.65.06 |
|
|
| any `cpu` / `nocuda` variant, and everything for macOS | — | — | none |
|
|
|
|
The aarch64 build is cross-compiled and verified in CI to be Arm, self-contained and to carry both
|
|
GPU targets, but it is **not exercised on hardware** — CI has no GH200 or Spark runner.
|
|
|
|
**A V100 needs the CUDA 12 build.** CUDA 13 dropped offline compilation for Volta, and the PTX that a
|
|
fatbin also carries only ever JIT-compiles *forwards*, so a CUDA 13 artefact contains nothing a V100
|
|
can execute: every kernel launch fails with *no kernel image is available for execution on the
|
|
device*. On a V100 host take the RHEL 8 packages or the portable Linux `.tgz`. Nothing older than
|
|
Volta is supported.
|
|
|
|
Newer GPUs never need a newer build — the highest generation in the list ships PTX as well as SASS,
|
|
which the driver JIT-compiles for a GPU that came out after the release.
|
|
|
|
The minimum driver above is the floor for the whole CUDA *major* version, which is what applies here
|
|
because the CUDA runtime is statically linked
|
|
([CUDA minor version compatibility](https://docs.nvidia.com/deploy/cuda-compatibility/minor-version-compatibility.html)).
|
|
Newer drivers are always fine; they are backward compatible. A driver from the same release as the
|
|
build toolkit (575.57.08 for the CUDA 12.9 build, 610.43.02 for a CUDA 13.3 one) additionally rules
|
|
out the single caveat of minor version compatibility — a call into a driver API newer than the
|
|
installed driver, which fails with `cudaErrorCallRequiresNewerDriver`.
|
|
|
|
## Windows installer
|
|
|
|
The Windows artefacts are the `jfjoch_viewer` installer and the separate `rugnux` `.zip`; the rest
|
|
of Jungfraujoch (broker, receiver, FPGA host, detector control) is Linux-only.
|
|
|
|
The toolchain bounds of the released installer are:
|
|
|
|
- **Visual Studio 2026** with the C++ (MSVC) toolset. MSVC is not optional — CUDA on Windows builds
|
|
through it — and it is what the release is compiled with.
|
|
- **CUDA Toolkit 13.3** for the `cuda13` variant.
|
|
- **Qt 6.11** for MSVC (`msvc2022_64`), including Qt Charts.
|
|
- Ninja as the generator; every third-party library is fetched and built by the configure.
|
|
|
|
The installer is generated with NSIS and **bundles the Qt runtime** (via `windeployqt`) and, on the
|
|
CUDA variant, the cuFFT DLL — so the end user installs neither Qt nor a CUDA toolkit. The two
|
|
variants share an install directory and Start Menu group and replace each other (CUDA is a strict
|
|
superset); they are told apart by the installer filename and the Add/Remove Programs entry:
|
|
|
|
| Build | Installer file | Add/Remove Programs |
|
|
| --- | --- | --- |
|
|
| CUDA (default) | `jfjoch-viewer-<version>-win64-cuda<major>.exe` | `Jungfraujoch (CUDA)` |
|
|
| CPU-only | `jfjoch-viewer-<version>-win64-cpu.exe` | `Jungfraujoch (CPU)` |
|
|
|
|
To build the viewer yourself on Windows, see
|
|
[jfjoch_viewer ▸ Building from source on Windows](JFJOCH_VIEWER.md#building-from-source-on-windows).
|
|
|
|
## macOS
|
|
|
|
The macOS artefacts are the `jfjoch_viewer` disk image and the `rugnux` `.tgz`; as on Windows, the
|
|
rest of Jungfraujoch is Linux-only. Both are **CPU-only** — macOS has no CUDA, so indexing uses the
|
|
FFTW indexer and the whole pipeline runs on the CPU — and both are built for **Apple Silicon only**.
|
|
They need **macOS 13 (Ventura) or newer**.
|
|
|
|
**Intel Macs are not supported.** No Intel (`x86_64`) code is built for macOS, and Rosetta cannot
|
|
help here: it runs Intel programs on Apple Silicon, not the other way round.
|
|
|
|
`jfjoch-viewer-<version>-macos-arm64.dmg` holds `jfjoch_viewer.app`; open the image and drag the
|
|
app onto the *Applications* shortcut next to it. The app is self-contained: the Qt frameworks are
|
|
inside it, and so are the license notices (`Contents/Resources`), which is where a macOS app keeps
|
|
them.
|
|
|
|
**The release is not notarized yet** (that needs an Apple Developer account), so macOS refuses to
|
|
open a downloaded copy the first time. On macOS 15 and newer: try to open it once, then allow it in
|
|
*System Settings ▸ Privacy & Security* with *Open Anyway*. On macOS 13 and 14, Control-click the app
|
|
and choose *Open*. Alternatively, clear the download flag in Terminal:
|
|
|
|
```
|
|
xattr -dr com.apple.quarantine /Applications/jfjoch_viewer.app
|
|
```
|
|
|
|
The same applies to the `rugnux` binary from the `.tgz` — see
|
|
[Installing Rugnux](RUGNUX_INSTALL.md#from-the-release-archive).
|
|
|
|
The toolchain of the released macOS artefacts is Xcode (Apple Clang) and Qt 6.11 for macOS,
|
|
including Qt Charts; to build the viewer yourself see
|
|
[jfjoch_viewer ▸ Building from source on macOS](JFJOCH_VIEWER.md#building-from-source-on-macos).
|
|
|
|
## Licenses
|
|
|
|
Every package variant carries the project license, the third-party manifest and the verbatim
|
|
license texts of the bundled dependencies, each package under a directory of its own —
|
|
`share/doc/jfjoch_broker`, `jfjoch_writer`, `jfjoch_viewer`, `jfjoch_rugnux`, `jfjoch_driver_dkms` —
|
|
so that no two packages claim the same path and they can be upgraded independently. The macOS
|
|
viewer is the exception: its notices are inside the app, in `jfjoch_viewer.app/Contents/Resources`. See
|
|
[Third-party software notices](THIRD_PARTY_NOTICES.md).
|