diff --git a/README.md b/README.md index e225aec5b..639e41fb7 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,17 @@ -# Jungfraujoch +# Repository content -Jungfraujoch is open-source software from the Paul Scherrer Institute for X-ray diffraction data. -It is the data-acquisition and real-time analysis system for the PSI **JUNGFRAU** detector and, -through their detector control unit, for **DECTRIS** detectors, and it includes **Rugnux**, the -program that processes diffraction data from the images to merged reflections and a refined -structure. +This repository is about doing macromolecular crystallography fast, at the edge and automatically. +The data are processed where they are collected, next to the detector at the beamline, at the +detector's frame rate and with nothing to set by hand, so that a structure is available seconds +after the measurement ends. + +**Jungfraujoch** is the data-acquisition and real-time analysis system for the PSI **JUNGFRAU** +detector and, through their detector control unit, for **DECTRIS** detectors. **Rugnux** is its +program for processing diffraction data from the images to merged reflections and a refined +structure. Both are open-source software from the Paul Scherrer Institute. Repository: **https://gitea.psi.ch/mx/jungfraujoch**. Documentation: -**https://jungfraujoch.readthedocs.io** (source in [docs/](docs/)). +**https://jungfraujoch.readthedocs.io**. ## The programs @@ -28,7 +32,7 @@ acquisition system needs a beamline and is covered by its own pages. ## Requirements -Rugnux runs on Linux x86-64 and aarch64, Windows 11 and macOS 13 or newer on Apple Silicon. An +Rugnux runs on Linux x86-64 and ARM (aarch64), Windows 11 and macOS 13 or newer on Apple Silicon. An NVIDIA GPU is optional and recommended: the demo below takes seconds on a GPU and minutes without one. The CUDA archive needs only the NVIDIA driver, no CUDA toolkit. The demo needs about 10 GB of host memory and 9 GB of GPU memory. Details in [Installing Rugnux](docs/RUGNUX_INSTALL.md). @@ -47,15 +51,15 @@ Rugnux is one executable in an archive on the release page, it into a directory of its own. On Linux x86-64, with or without an NVIDIA GPU: ``` -VERSION=1.0.0-rc.183 # the newest release on the page +VERSION=1.0.0-rc.184 # the newest release on the page curl -L -O https://gitea.psi.ch/mx/jungfraujoch/releases/download/$VERSION/rugnux-$VERSION-linux-x86_64-cuda12.tgz mkdir -p rugnux-$VERSION && tar xzf rugnux-$VERSION-linux-x86_64-cuda12.tgz -C rugnux-$VERSION export PATH=$PWD/rugnux-$VERSION/bin:$PATH rugnux # prints the version and the usage ``` -The archive is 268 MB, installs in under a minute, and nothing else is installed. The same page has -the CPU-only, aarch64, Windows and macOS archives, the viewer and the XDS plugin. On RHEL / Rocky +The same page has the CPU-only, ARM (aarch64), Windows and macOS archives, the viewer and the XDS +plugin. On RHEL / Rocky and Ubuntu, Rugnux is also a package (`dnf install rugnux`, `apt install rugnux`; [package repositories](docs/REPOSITORIES.md)). @@ -64,7 +68,7 @@ and Ubuntu, Rugnux is also a package (`dnf install rugnux`, `apt install rugnux` The demo is the 9ZLO dataset ([PDB 9ZLO](https://www.rcsb.org/structure/9ZLO)): 3600 EIGER images of *Proteus mirabilis* UreE collected at the Australian Synchrotron, 10.8 GB in 19 files on Zenodo ([10.5281/zenodo.18652652](https://doi.org/10.5281/zenodo.18652652), CC-BY 4.0). Cite the record if -you use the data. The download takes about 30 minutes at 50 Mbit/s. +you use the data. ``` mkdir -p demo/9zlo && cd demo @@ -74,8 +78,8 @@ rugnux -o 9zlo 9zlo/ASP0887_09_0114_master.h5 `-o 9zlo` is the prefix of every output file; the last argument is the dataset's HDF5 master file (for a CBF, marCCD, SMV or SFRM sequence, any one of its images). No other option is needed: Rugnux -tells rotation data from serial data by the goniometer axis, determines the unit cell, space group -and resolution cutoff from the data, and scales and merges by default. +tells rotation data from serial data by the associated metadata (goniometer axis), determines the +unit cell, space group and resolution cutoff from the data, and scales and merges by default. ### Terminal output @@ -121,7 +125,7 @@ curl -L -O https://gitea.psi.ch/mx/jungfraujoch/raw/branch/main/tools/battery/mo rugnux -o 9zlo --model AF-P17090-F1-model_v6.cif 9zlo/ASP0887_09_0114_master.h5 ``` -The model does not change the processing. Molecular replacement places the two copies +The model does not affect the intensities or the lattice. Molecular replacement places the two copies (`MR_DECISION= AGREES` in the report), refinement brings them to R-work / R-free 0.27 / 0.30, and the run takes **22 s**. It adds these files: @@ -257,11 +261,16 @@ and [Tests](docs/TESTS.md). ## Licence -The software is free software under the **GNU General Public License v3.0** -([LICENSE](LICENSE)); the FPGA design is released under the **CERN Open Hardware Licence v2, -strongly reciprocal** ([fpga/LICENSE](fpga/LICENSE)). Third-party components bundled in the -releases are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md); the methods taken from the -literature are credited in [docs/ACKNOWLEDGEMENT.md](docs/ACKNOWLEDGEMENT.md). +The software is free software under the **GNU General Public License v3.0** ([LICENSE](LICENSE)). +It is free to use for industry and academia. If you modify this code and distribute it, you must +do so under the same GNU General Public License. The FPGA design is released under the **CERN Open +Hardware Licence v2, strongly reciprocal** ([fpga/LICENSE](fpga/LICENSE)). Third-party components +bundled in the releases are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). + +## Acknowledgements + +Rugnux builds on many crystallographic methods published by others. We acknowledge their authors +in [docs/ACKNOWLEDGEMENT.md](docs/ACKNOWLEDGEMENT.md), which names each method and its paper. ## How to cite diff --git a/docs/RUGNUX.md b/docs/RUGNUX.md index 2ef0a2684..64994618a 100644 --- a/docs/RUGNUX.md +++ b/docs/RUGNUX.md @@ -53,7 +53,7 @@ Rugnux is one executable in an archive on the release page, https://gitea.psi.ch On Linux x86-64 (the other platforms are on [Download](RUGNUX_DOWNLOAD.md)): ``` -VERSION=1.0.0-rc.183 +VERSION=1.0.0-rc.184 curl -L -O https://gitea.psi.ch/mx/jungfraujoch/releases/download/$VERSION/rugnux-$VERSION-linux-x86_64-cuda12.tgz mkdir -p rugnux-$VERSION && tar xzf rugnux-$VERSION-linux-x86_64-cuda12.tgz -C rugnux-$VERSION export PATH=$PWD/rugnux-$VERSION/bin:$PATH @@ -70,9 +70,9 @@ for f in ASP0887_09_0114_master.h5 ASP0887_09_0114_data_0000{01..18}.h5; do curl rugnux -o 9zlo 9zlo/ASP0887_09_0114_master.h5 ``` -No other option is needed. Rugnux tells rotation data from serial data by the goniometer axis, -determines the unit cell, space group and resolution cutoff from the data, and scales and merges by -default. The results are written next to each other under the prefix: `9zlo.mtz` (merged +No other option is needed. Rugnux tells rotation data from serial data by the associated metadata +(goniometer axis), determines the unit cell, space group and resolution cutoff from the data, and +scales and merges by default. The results are written next to each other under the prefix: `9zlo.mtz` (merged intensities and amplitudes), `9zlo.cif`, `9zlo.hkl` with `9zlo.ins`, `9zlo_unmerged.mtz`, `9zlo_report.txt` (statistics and decisions, written for a person), `9zlo_plot.txt`, `9zlo_detector.jpg` and `9zlo_log.txt`. Without `-o`, the prefix is `output`. On a desktop with a diff --git a/docs/RUGNUX_INSTALL.md b/docs/RUGNUX_INSTALL.md index 0a8172d27..a9b2d74be 100644 --- a/docs/RUGNUX_INSTALL.md +++ b/docs/RUGNUX_INSTALL.md @@ -40,7 +40,7 @@ release page: give `tar` a destination of its own, or it will scatter those into whatever directory you are in: ``` -VERSION=1.0.0-rc.183 # the newest release on the page +VERSION=1.0.0-rc.184 # the newest release on the page curl -L -O https://gitea.psi.ch/mx/jungfraujoch/releases/download/$VERSION/rugnux-$VERSION-linux-x86_64-cuda12.tgz mkdir -p /opt/rugnux-$VERSION tar xzf rugnux-$VERSION-linux-x86_64-cuda12.tgz -C /opt/rugnux-$VERSION