commit 2b3095879fe146a773d16a5eeb5822e78ceff2d0 Author: Filip Leonarski (Gitea) Date: Fri Nov 13 19:15:43 2026 +0000 Deploy site diff --git a/.buildinfo b/.buildinfo new file mode 100644 index 000000000..6d7ae3dc3 --- /dev/null +++ b/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 551daee3beb9b44d9cf00401cc4480cc +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.doctrees/ACKNOWLEDGEMENT.doctree b/.doctrees/ACKNOWLEDGEMENT.doctree new file mode 100644 index 000000000..a0ac25d0b Binary files /dev/null and b/.doctrees/ACKNOWLEDGEMENT.doctree differ diff --git a/.doctrees/CBOR.doctree b/.doctrees/CBOR.doctree new file mode 100644 index 000000000..2a7c2e2fb Binary files /dev/null and b/.doctrees/CBOR.doctree differ diff --git a/.doctrees/CHANGELOG.doctree b/.doctrees/CHANGELOG.doctree new file mode 100644 index 000000000..4a38270a4 Binary files /dev/null and b/.doctrees/CHANGELOG.doctree differ diff --git a/.doctrees/CPU_DATA_ANALYSIS.doctree b/.doctrees/CPU_DATA_ANALYSIS.doctree new file mode 100644 index 000000000..f96e20029 Binary files /dev/null and b/.doctrees/CPU_DATA_ANALYSIS.doctree differ diff --git a/.doctrees/CPU_DATA_ANALYSIS_DECISIONS.doctree b/.doctrees/CPU_DATA_ANALYSIS_DECISIONS.doctree new file mode 100644 index 000000000..c9c7ab420 Binary files /dev/null and b/.doctrees/CPU_DATA_ANALYSIS_DECISIONS.doctree differ diff --git a/.doctrees/CPU_DATA_ANALYSIS_IMAGE.doctree b/.doctrees/CPU_DATA_ANALYSIS_IMAGE.doctree new file mode 100644 index 000000000..d9c469bd7 Binary files /dev/null and b/.doctrees/CPU_DATA_ANALYSIS_IMAGE.doctree differ diff --git a/.doctrees/CPU_DATA_ANALYSIS_INDEXING.doctree b/.doctrees/CPU_DATA_ANALYSIS_INDEXING.doctree new file mode 100644 index 000000000..b0f88217d Binary files /dev/null and b/.doctrees/CPU_DATA_ANALYSIS_INDEXING.doctree differ diff --git a/.doctrees/CPU_DATA_ANALYSIS_INTEGRATION.doctree b/.doctrees/CPU_DATA_ANALYSIS_INTEGRATION.doctree new file mode 100644 index 000000000..7d721b4ac Binary files /dev/null and b/.doctrees/CPU_DATA_ANALYSIS_INTEGRATION.doctree differ diff --git a/.doctrees/CPU_DATA_ANALYSIS_REFINEMENT.doctree b/.doctrees/CPU_DATA_ANALYSIS_REFINEMENT.doctree new file mode 100644 index 000000000..54af5f8b4 Binary files /dev/null and b/.doctrees/CPU_DATA_ANALYSIS_REFINEMENT.doctree differ diff --git a/.doctrees/DEPLOYMENT.doctree b/.doctrees/DEPLOYMENT.doctree new file mode 100644 index 000000000..1350fdb15 Binary files /dev/null and b/.doctrees/DEPLOYMENT.doctree differ diff --git a/.doctrees/DETECTORS.doctree b/.doctrees/DETECTORS.doctree new file mode 100644 index 000000000..9ea184887 Binary files /dev/null and b/.doctrees/DETECTORS.doctree differ diff --git a/.doctrees/DETECTOR_GEOMETRY.doctree b/.doctrees/DETECTOR_GEOMETRY.doctree new file mode 100644 index 000000000..2a7c5f39a Binary files /dev/null and b/.doctrees/DETECTOR_GEOMETRY.doctree differ diff --git a/.doctrees/EXTERNAL_TEST_DATA.doctree b/.doctrees/EXTERNAL_TEST_DATA.doctree new file mode 100644 index 000000000..92ab71cf7 Binary files /dev/null and b/.doctrees/EXTERNAL_TEST_DATA.doctree differ diff --git a/.doctrees/EXTERNAL_TEST_DATA_STILLS.doctree b/.doctrees/EXTERNAL_TEST_DATA_STILLS.doctree new file mode 100644 index 000000000..522187b1f Binary files /dev/null and b/.doctrees/EXTERNAL_TEST_DATA_STILLS.doctree differ diff --git a/.doctrees/FPGA.doctree b/.doctrees/FPGA.doctree new file mode 100644 index 000000000..a34581467 Binary files /dev/null and b/.doctrees/FPGA.doctree differ diff --git a/.doctrees/FPGA_DATA_ANALYSIS.doctree b/.doctrees/FPGA_DATA_ANALYSIS.doctree new file mode 100644 index 000000000..4a1d6be24 Binary files /dev/null and b/.doctrees/FPGA_DATA_ANALYSIS.doctree differ diff --git a/.doctrees/FPGA_DESIGN.doctree b/.doctrees/FPGA_DESIGN.doctree new file mode 100644 index 000000000..ed08df361 Binary files /dev/null and b/.doctrees/FPGA_DESIGN.doctree differ diff --git a/.doctrees/FPGA_LICENSE.doctree b/.doctrees/FPGA_LICENSE.doctree new file mode 100644 index 000000000..9e76d8d42 Binary files /dev/null and b/.doctrees/FPGA_LICENSE.doctree differ diff --git a/.doctrees/FPGA_NETWORK.doctree b/.doctrees/FPGA_NETWORK.doctree new file mode 100644 index 000000000..d2de1a390 Binary files /dev/null and b/.doctrees/FPGA_NETWORK.doctree differ diff --git a/.doctrees/FPGA_PCIE_DRIVER.doctree b/.doctrees/FPGA_PCIE_DRIVER.doctree new file mode 100644 index 000000000..198b6da65 Binary files /dev/null and b/.doctrees/FPGA_PCIE_DRIVER.doctree differ diff --git a/.doctrees/FPGA_SETTINGS.doctree b/.doctrees/FPGA_SETTINGS.doctree new file mode 100644 index 000000000..a3ee3969b Binary files /dev/null and b/.doctrees/FPGA_SETTINGS.doctree differ diff --git a/.doctrees/GPU_DATA_ANALYSIS.doctree b/.doctrees/GPU_DATA_ANALYSIS.doctree new file mode 100644 index 000000000..8d14aa1de Binary files /dev/null and b/.doctrees/GPU_DATA_ANALYSIS.doctree differ diff --git a/.doctrees/HARDWARE.doctree b/.doctrees/HARDWARE.doctree new file mode 100644 index 000000000..3d8210b80 Binary files /dev/null and b/.doctrees/HARDWARE.doctree differ diff --git a/.doctrees/HDF5.doctree b/.doctrees/HDF5.doctree new file mode 100644 index 000000000..50f463eaa Binary files /dev/null and b/.doctrees/HDF5.doctree differ diff --git a/.doctrees/IMAGE_STREAM.doctree b/.doctrees/IMAGE_STREAM.doctree new file mode 100644 index 000000000..51585f8a2 Binary files /dev/null and b/.doctrees/IMAGE_STREAM.doctree differ diff --git a/.doctrees/JFJOCH_BROKER.doctree b/.doctrees/JFJOCH_BROKER.doctree new file mode 100644 index 000000000..9f5f3b0cc Binary files /dev/null and b/.doctrees/JFJOCH_BROKER.doctree differ diff --git a/.doctrees/JFJOCH_VIEWER.doctree b/.doctrees/JFJOCH_VIEWER.doctree new file mode 100644 index 000000000..08b687e9e Binary files /dev/null and b/.doctrees/JFJOCH_VIEWER.doctree differ diff --git a/.doctrees/JFJOCH_WRITER.doctree b/.doctrees/JFJOCH_WRITER.doctree new file mode 100644 index 000000000..5c92f06fb Binary files /dev/null and b/.doctrees/JFJOCH_WRITER.doctree differ diff --git a/.doctrees/JUNGFRAUJOCH.doctree b/.doctrees/JUNGFRAUJOCH.doctree new file mode 100644 index 000000000..cea3b9779 Binary files /dev/null and b/.doctrees/JUNGFRAUJOCH.doctree differ diff --git a/.doctrees/LICENSE.doctree b/.doctrees/LICENSE.doctree new file mode 100644 index 000000000..86e1c05ff Binary files /dev/null and b/.doctrees/LICENSE.doctree differ diff --git a/.doctrees/NAMING.doctree b/.doctrees/NAMING.doctree new file mode 100644 index 000000000..a722b7291 Binary files /dev/null and b/.doctrees/NAMING.doctree differ diff --git a/.doctrees/OPENAPI.doctree b/.doctrees/OPENAPI.doctree new file mode 100644 index 000000000..d8b3ecf86 Binary files /dev/null and b/.doctrees/OPENAPI.doctree differ diff --git a/.doctrees/OPENAPI_SPECS.doctree b/.doctrees/OPENAPI_SPECS.doctree new file mode 100644 index 000000000..2c353cb88 Binary files /dev/null and b/.doctrees/OPENAPI_SPECS.doctree differ diff --git a/.doctrees/PIXEL_MASK.doctree b/.doctrees/PIXEL_MASK.doctree new file mode 100644 index 000000000..18c93d994 Binary files /dev/null and b/.doctrees/PIXEL_MASK.doctree differ diff --git a/.doctrees/PUBLICATIONS.doctree b/.doctrees/PUBLICATIONS.doctree new file mode 100644 index 000000000..d932fd9b7 Binary files /dev/null and b/.doctrees/PUBLICATIONS.doctree differ diff --git a/.doctrees/PYTHON_CLIENT.doctree b/.doctrees/PYTHON_CLIENT.doctree new file mode 100644 index 000000000..d556df257 Binary files /dev/null and b/.doctrees/PYTHON_CLIENT.doctree differ diff --git a/.doctrees/RELEASE_CONTENTS.doctree b/.doctrees/RELEASE_CONTENTS.doctree new file mode 100644 index 000000000..ac762bb98 Binary files /dev/null and b/.doctrees/RELEASE_CONTENTS.doctree differ diff --git a/.doctrees/REPOSITORIES.doctree b/.doctrees/REPOSITORIES.doctree new file mode 100644 index 000000000..34d3a42b2 Binary files /dev/null and b/.doctrees/REPOSITORIES.doctree differ diff --git a/.doctrees/RUGNUX.doctree b/.doctrees/RUGNUX.doctree new file mode 100644 index 000000000..9798a26c3 Binary files /dev/null and b/.doctrees/RUGNUX.doctree differ diff --git a/.doctrees/RUGNUX_ADVANCED.doctree b/.doctrees/RUGNUX_ADVANCED.doctree new file mode 100644 index 000000000..806c90304 Binary files /dev/null and b/.doctrees/RUGNUX_ADVANCED.doctree differ diff --git a/.doctrees/RUGNUX_BENCHMARKING.doctree b/.doctrees/RUGNUX_BENCHMARKING.doctree new file mode 100644 index 000000000..588670789 Binary files /dev/null and b/.doctrees/RUGNUX_BENCHMARKING.doctree differ diff --git a/.doctrees/RUGNUX_CALIBRATION.doctree b/.doctrees/RUGNUX_CALIBRATION.doctree new file mode 100644 index 000000000..be6a34f7c Binary files /dev/null and b/.doctrees/RUGNUX_CALIBRATION.doctree differ diff --git a/.doctrees/RUGNUX_CLI.doctree b/.doctrees/RUGNUX_CLI.doctree new file mode 100644 index 000000000..6fd1a3128 Binary files /dev/null and b/.doctrees/RUGNUX_CLI.doctree differ diff --git a/.doctrees/RUGNUX_DOWNLOAD.doctree b/.doctrees/RUGNUX_DOWNLOAD.doctree new file mode 100644 index 000000000..3222b6843 Binary files /dev/null and b/.doctrees/RUGNUX_DOWNLOAD.doctree differ diff --git a/.doctrees/RUGNUX_FORMATS.doctree b/.doctrees/RUGNUX_FORMATS.doctree new file mode 100644 index 000000000..e35588b39 Binary files /dev/null and b/.doctrees/RUGNUX_FORMATS.doctree differ diff --git a/.doctrees/RUGNUX_INSTALL.doctree b/.doctrees/RUGNUX_INSTALL.doctree new file mode 100644 index 000000000..e2e108b3c Binary files /dev/null and b/.doctrees/RUGNUX_INSTALL.doctree differ diff --git a/.doctrees/RUGNUX_INTEGRATION.doctree b/.doctrees/RUGNUX_INTEGRATION.doctree new file mode 100644 index 000000000..6ab957f0a Binary files /dev/null and b/.doctrees/RUGNUX_INTEGRATION.doctree differ diff --git a/.doctrees/RUGNUX_MODEL_AND_REFERENCE.doctree b/.doctrees/RUGNUX_MODEL_AND_REFERENCE.doctree new file mode 100644 index 000000000..5b06f8852 Binary files /dev/null and b/.doctrees/RUGNUX_MODEL_AND_REFERENCE.doctree differ diff --git a/.doctrees/RUGNUX_OVERVIEW.doctree b/.doctrees/RUGNUX_OVERVIEW.doctree new file mode 100644 index 000000000..b0dc4c17a Binary files /dev/null and b/.doctrees/RUGNUX_OVERVIEW.doctree differ diff --git a/.doctrees/RUGNUX_REPORT.doctree b/.doctrees/RUGNUX_REPORT.doctree new file mode 100644 index 000000000..527644191 Binary files /dev/null and b/.doctrees/RUGNUX_REPORT.doctree differ diff --git a/.doctrees/RUGNUX_TUTORIAL.doctree b/.doctrees/RUGNUX_TUTORIAL.doctree new file mode 100644 index 000000000..1de23174a Binary files /dev/null and b/.doctrees/RUGNUX_TUTORIAL.doctree differ diff --git a/.doctrees/SECURITY.doctree b/.doctrees/SECURITY.doctree new file mode 100644 index 000000000..bddd2d19b Binary files /dev/null and b/.doctrees/SECURITY.doctree differ diff --git a/.doctrees/SOFTWARE.doctree b/.doctrees/SOFTWARE.doctree new file mode 100644 index 000000000..30b08b053 Binary files /dev/null and b/.doctrees/SOFTWARE.doctree differ diff --git a/.doctrees/SOFTWARE_INTEGRATION.doctree b/.doctrees/SOFTWARE_INTEGRATION.doctree new file mode 100644 index 000000000..d9bb097e3 Binary files /dev/null and b/.doctrees/SOFTWARE_INTEGRATION.doctree differ diff --git a/.doctrees/TECHNICAL.doctree b/.doctrees/TECHNICAL.doctree new file mode 100644 index 000000000..f753b2d77 Binary files /dev/null and b/.doctrees/TECHNICAL.doctree differ diff --git a/.doctrees/TESTS.doctree b/.doctrees/TESTS.doctree new file mode 100644 index 000000000..b4eb942d9 Binary files /dev/null and b/.doctrees/TESTS.doctree differ diff --git a/.doctrees/THIRD_PARTY_NOTICES.doctree b/.doctrees/THIRD_PARTY_NOTICES.doctree new file mode 100644 index 000000000..4c9e16245 Binary files /dev/null and b/.doctrees/THIRD_PARTY_NOTICES.doctree differ diff --git a/.doctrees/TOOLS.doctree b/.doctrees/TOOLS.doctree new file mode 100644 index 000000000..91b380505 Binary files /dev/null and b/.doctrees/TOOLS.doctree differ diff --git a/.doctrees/VERSIONING.doctree b/.doctrees/VERSIONING.doctree new file mode 100644 index 000000000..e68bd9491 Binary files /dev/null and b/.doctrees/VERSIONING.doctree differ diff --git a/.doctrees/VIEWER_DOWNLOAD.doctree b/.doctrees/VIEWER_DOWNLOAD.doctree new file mode 100644 index 000000000..ce1096c34 Binary files /dev/null and b/.doctrees/VIEWER_DOWNLOAD.doctree differ diff --git a/.doctrees/WEB_FRONTEND.doctree b/.doctrees/WEB_FRONTEND.doctree new file mode 100644 index 000000000..cf8bc0ac7 Binary files /dev/null and b/.doctrees/WEB_FRONTEND.doctree differ diff --git a/.doctrees/documentation.doctree b/.doctrees/documentation.doctree new file mode 100644 index 000000000..e42990f37 Binary files /dev/null and b/.doctrees/documentation.doctree differ diff --git a/.doctrees/environment.pickle b/.doctrees/environment.pickle new file mode 100644 index 000000000..dfd64de60 Binary files /dev/null and b/.doctrees/environment.pickle differ diff --git a/.doctrees/python_client/README.doctree b/.doctrees/python_client/README.doctree new file mode 100644 index 000000000..9e95c129a Binary files /dev/null and b/.doctrees/python_client/README.doctree differ diff --git a/.doctrees/python_client/docs/AzimIntSettings.doctree b/.doctrees/python_client/docs/AzimIntSettings.doctree new file mode 100644 index 000000000..be76ef266 Binary files /dev/null and b/.doctrees/python_client/docs/AzimIntSettings.doctree differ diff --git a/.doctrees/python_client/docs/BraggIntegrationSettings.doctree b/.doctrees/python_client/docs/BraggIntegrationSettings.doctree new file mode 100644 index 000000000..8a65505d0 Binary files /dev/null and b/.doctrees/python_client/docs/BraggIntegrationSettings.doctree differ diff --git a/.doctrees/python_client/docs/BrokerStatus.doctree b/.doctrees/python_client/docs/BrokerStatus.doctree new file mode 100644 index 000000000..132fe9db0 Binary files /dev/null and b/.doctrees/python_client/docs/BrokerStatus.doctree differ diff --git a/.doctrees/python_client/docs/CalibrationStatisticsInner.doctree b/.doctrees/python_client/docs/CalibrationStatisticsInner.doctree new file mode 100644 index 000000000..2f30d3f52 Binary files /dev/null and b/.doctrees/python_client/docs/CalibrationStatisticsInner.doctree differ diff --git a/.doctrees/python_client/docs/DarkMaskSettings.doctree b/.doctrees/python_client/docs/DarkMaskSettings.doctree new file mode 100644 index 000000000..b7ed23aa0 Binary files /dev/null and b/.doctrees/python_client/docs/DarkMaskSettings.doctree differ diff --git a/.doctrees/python_client/docs/DatasetSettings.doctree b/.doctrees/python_client/docs/DatasetSettings.doctree new file mode 100644 index 000000000..9c72a6b1f Binary files /dev/null and b/.doctrees/python_client/docs/DatasetSettings.doctree differ diff --git a/.doctrees/python_client/docs/DatasetSettingsSmargon.doctree b/.doctrees/python_client/docs/DatasetSettingsSmargon.doctree new file mode 100644 index 000000000..ef560a438 Binary files /dev/null and b/.doctrees/python_client/docs/DatasetSettingsSmargon.doctree differ diff --git a/.doctrees/python_client/docs/DatasetSettingsXrayFluorescenceSpectrum.doctree b/.doctrees/python_client/docs/DatasetSettingsXrayFluorescenceSpectrum.doctree new file mode 100644 index 000000000..1b34cc7b7 Binary files /dev/null and b/.doctrees/python_client/docs/DatasetSettingsXrayFluorescenceSpectrum.doctree differ diff --git a/.doctrees/python_client/docs/DefaultApi.doctree b/.doctrees/python_client/docs/DefaultApi.doctree new file mode 100644 index 000000000..a95cd2f53 Binary files /dev/null and b/.doctrees/python_client/docs/DefaultApi.doctree differ diff --git a/.doctrees/python_client/docs/Detector.doctree b/.doctrees/python_client/docs/Detector.doctree new file mode 100644 index 000000000..225d2f96f Binary files /dev/null and b/.doctrees/python_client/docs/Detector.doctree differ diff --git a/.doctrees/python_client/docs/DetectorList.doctree b/.doctrees/python_client/docs/DetectorList.doctree new file mode 100644 index 000000000..f951b0d76 Binary files /dev/null and b/.doctrees/python_client/docs/DetectorList.doctree differ diff --git a/.doctrees/python_client/docs/DetectorListElement.doctree b/.doctrees/python_client/docs/DetectorListElement.doctree new file mode 100644 index 000000000..dda31eb6e Binary files /dev/null and b/.doctrees/python_client/docs/DetectorListElement.doctree differ diff --git a/.doctrees/python_client/docs/DetectorModule.doctree b/.doctrees/python_client/docs/DetectorModule.doctree new file mode 100644 index 000000000..5abcb0d59 Binary files /dev/null and b/.doctrees/python_client/docs/DetectorModule.doctree differ diff --git a/.doctrees/python_client/docs/DetectorModuleDirection.doctree b/.doctrees/python_client/docs/DetectorModuleDirection.doctree new file mode 100644 index 000000000..b510009fd Binary files /dev/null and b/.doctrees/python_client/docs/DetectorModuleDirection.doctree differ diff --git a/.doctrees/python_client/docs/DetectorModulePlacement.doctree b/.doctrees/python_client/docs/DetectorModulePlacement.doctree new file mode 100644 index 000000000..a550acc23 Binary files /dev/null and b/.doctrees/python_client/docs/DetectorModulePlacement.doctree differ diff --git a/.doctrees/python_client/docs/DetectorPowerState.doctree b/.doctrees/python_client/docs/DetectorPowerState.doctree new file mode 100644 index 000000000..115ce3324 Binary files /dev/null and b/.doctrees/python_client/docs/DetectorPowerState.doctree differ diff --git a/.doctrees/python_client/docs/DetectorSelection.doctree b/.doctrees/python_client/docs/DetectorSelection.doctree new file mode 100644 index 000000000..765b84ce8 Binary files /dev/null and b/.doctrees/python_client/docs/DetectorSelection.doctree differ diff --git a/.doctrees/python_client/docs/DetectorSettings.doctree b/.doctrees/python_client/docs/DetectorSettings.doctree new file mode 100644 index 000000000..2557ede2c Binary files /dev/null and b/.doctrees/python_client/docs/DetectorSettings.doctree differ diff --git a/.doctrees/python_client/docs/DetectorState.doctree b/.doctrees/python_client/docs/DetectorState.doctree new file mode 100644 index 000000000..84750d048 Binary files /dev/null and b/.doctrees/python_client/docs/DetectorState.doctree differ diff --git a/.doctrees/python_client/docs/DetectorStatus.doctree b/.doctrees/python_client/docs/DetectorStatus.doctree new file mode 100644 index 000000000..316cb6cbf Binary files /dev/null and b/.doctrees/python_client/docs/DetectorStatus.doctree differ diff --git a/.doctrees/python_client/docs/DetectorTiming.doctree b/.doctrees/python_client/docs/DetectorTiming.doctree new file mode 100644 index 000000000..22dc0c03b Binary files /dev/null and b/.doctrees/python_client/docs/DetectorTiming.doctree differ diff --git a/.doctrees/python_client/docs/DetectorType.doctree b/.doctrees/python_client/docs/DetectorType.doctree new file mode 100644 index 000000000..f4e0a6a95 Binary files /dev/null and b/.doctrees/python_client/docs/DetectorType.doctree differ diff --git a/.doctrees/python_client/docs/ErrorMessage.doctree b/.doctrees/python_client/docs/ErrorMessage.doctree new file mode 100644 index 000000000..41404f389 Binary files /dev/null and b/.doctrees/python_client/docs/ErrorMessage.doctree differ diff --git a/.doctrees/python_client/docs/FileWriterFormat.doctree b/.doctrees/python_client/docs/FileWriterFormat.doctree new file mode 100644 index 000000000..42d7d43c9 Binary files /dev/null and b/.doctrees/python_client/docs/FileWriterFormat.doctree differ diff --git a/.doctrees/python_client/docs/FileWriterSettings.doctree b/.doctrees/python_client/docs/FileWriterSettings.doctree new file mode 100644 index 000000000..7a71193d2 Binary files /dev/null and b/.doctrees/python_client/docs/FileWriterSettings.doctree differ diff --git a/.doctrees/python_client/docs/FpgaStatusInner.doctree b/.doctrees/python_client/docs/FpgaStatusInner.doctree new file mode 100644 index 000000000..ed1965ab2 Binary files /dev/null and b/.doctrees/python_client/docs/FpgaStatusInner.doctree differ diff --git a/.doctrees/python_client/docs/GeomRefinementAlgorithm.doctree b/.doctrees/python_client/docs/GeomRefinementAlgorithm.doctree new file mode 100644 index 000000000..3430aa012 Binary files /dev/null and b/.doctrees/python_client/docs/GeomRefinementAlgorithm.doctree differ diff --git a/.doctrees/python_client/docs/GridScan.doctree b/.doctrees/python_client/docs/GridScan.doctree new file mode 100644 index 000000000..c7e653816 Binary files /dev/null and b/.doctrees/python_client/docs/GridScan.doctree differ diff --git a/.doctrees/python_client/docs/ImageBufferStatus.doctree b/.doctrees/python_client/docs/ImageBufferStatus.doctree new file mode 100644 index 000000000..04efdce5f Binary files /dev/null and b/.doctrees/python_client/docs/ImageBufferStatus.doctree differ diff --git a/.doctrees/python_client/docs/ImageFormatSettings.doctree b/.doctrees/python_client/docs/ImageFormatSettings.doctree new file mode 100644 index 000000000..d795ce4ba Binary files /dev/null and b/.doctrees/python_client/docs/ImageFormatSettings.doctree differ diff --git a/.doctrees/python_client/docs/ImagePusherStatus.doctree b/.doctrees/python_client/docs/ImagePusherStatus.doctree new file mode 100644 index 000000000..2be4badd9 Binary files /dev/null and b/.doctrees/python_client/docs/ImagePusherStatus.doctree differ diff --git a/.doctrees/python_client/docs/ImagePusherType.doctree b/.doctrees/python_client/docs/ImagePusherType.doctree new file mode 100644 index 000000000..b9e53dc3c Binary files /dev/null and b/.doctrees/python_client/docs/ImagePusherType.doctree differ diff --git a/.doctrees/python_client/docs/IndexingAlgorithm.doctree b/.doctrees/python_client/docs/IndexingAlgorithm.doctree new file mode 100644 index 000000000..e150689f1 Binary files /dev/null and b/.doctrees/python_client/docs/IndexingAlgorithm.doctree differ diff --git a/.doctrees/python_client/docs/IndexingSettings.doctree b/.doctrees/python_client/docs/IndexingSettings.doctree new file mode 100644 index 000000000..fafce0551 Binary files /dev/null and b/.doctrees/python_client/docs/IndexingSettings.doctree differ diff --git a/.doctrees/python_client/docs/InstrumentMetadata.doctree b/.doctrees/python_client/docs/InstrumentMetadata.doctree new file mode 100644 index 000000000..769d4b73d Binary files /dev/null and b/.doctrees/python_client/docs/InstrumentMetadata.doctree differ diff --git a/.doctrees/python_client/docs/IntegrationModel.doctree b/.doctrees/python_client/docs/IntegrationModel.doctree new file mode 100644 index 000000000..5c3b85f83 Binary files /dev/null and b/.doctrees/python_client/docs/IntegrationModel.doctree differ diff --git a/.doctrees/python_client/docs/JfjochSettings.doctree b/.doctrees/python_client/docs/JfjochSettings.doctree new file mode 100644 index 000000000..a607c1d2d Binary files /dev/null and b/.doctrees/python_client/docs/JfjochSettings.doctree differ diff --git a/.doctrees/python_client/docs/JfjochStatistics.doctree b/.doctrees/python_client/docs/JfjochStatistics.doctree new file mode 100644 index 000000000..96d2ecff2 Binary files /dev/null and b/.doctrees/python_client/docs/JfjochStatistics.doctree differ diff --git a/.doctrees/python_client/docs/MeasurementStatistics.doctree b/.doctrees/python_client/docs/MeasurementStatistics.doctree new file mode 100644 index 000000000..a5e569773 Binary files /dev/null and b/.doctrees/python_client/docs/MeasurementStatistics.doctree differ diff --git a/.doctrees/python_client/docs/PcieDevicesInner.doctree b/.doctrees/python_client/docs/PcieDevicesInner.doctree new file mode 100644 index 000000000..15ace3201 Binary files /dev/null and b/.doctrees/python_client/docs/PcieDevicesInner.doctree differ diff --git a/.doctrees/python_client/docs/PixelMaskStatistics.doctree b/.doctrees/python_client/docs/PixelMaskStatistics.doctree new file mode 100644 index 000000000..d3e9f09da Binary files /dev/null and b/.doctrees/python_client/docs/PixelMaskStatistics.doctree differ diff --git a/.doctrees/python_client/docs/Plot.doctree b/.doctrees/python_client/docs/Plot.doctree new file mode 100644 index 000000000..b9bb9578a Binary files /dev/null and b/.doctrees/python_client/docs/Plot.doctree differ diff --git a/.doctrees/python_client/docs/PlotUnitX.doctree b/.doctrees/python_client/docs/PlotUnitX.doctree new file mode 100644 index 000000000..5f0ace53b Binary files /dev/null and b/.doctrees/python_client/docs/PlotUnitX.doctree differ diff --git a/.doctrees/python_client/docs/Plots.doctree b/.doctrees/python_client/docs/Plots.doctree new file mode 100644 index 000000000..299ab240f Binary files /dev/null and b/.doctrees/python_client/docs/Plots.doctree differ diff --git a/.doctrees/python_client/docs/PowderCalibrationFitSigma.doctree b/.doctrees/python_client/docs/PowderCalibrationFitSigma.doctree new file mode 100644 index 000000000..3a283111b Binary files /dev/null and b/.doctrees/python_client/docs/PowderCalibrationFitSigma.doctree differ diff --git a/.doctrees/python_client/docs/PowderCalibrationOutput.doctree b/.doctrees/python_client/docs/PowderCalibrationOutput.doctree new file mode 100644 index 000000000..2dc2f66bb Binary files /dev/null and b/.doctrees/python_client/docs/PowderCalibrationOutput.doctree differ diff --git a/.doctrees/python_client/docs/PowderCalibrationQuality.doctree b/.doctrees/python_client/docs/PowderCalibrationQuality.doctree new file mode 100644 index 000000000..927c07f1a Binary files /dev/null and b/.doctrees/python_client/docs/PowderCalibrationQuality.doctree differ diff --git a/.doctrees/python_client/docs/PowderCalibrationSpotCheck.doctree b/.doctrees/python_client/docs/PowderCalibrationSpotCheck.doctree new file mode 100644 index 000000000..747636404 Binary files /dev/null and b/.doctrees/python_client/docs/PowderCalibrationSpotCheck.doctree differ diff --git a/.doctrees/python_client/docs/QBinning.doctree b/.doctrees/python_client/docs/QBinning.doctree new file mode 100644 index 000000000..5984e4fd1 Binary files /dev/null and b/.doctrees/python_client/docs/QBinning.doctree differ diff --git a/.doctrees/python_client/docs/RoiAzimList.doctree b/.doctrees/python_client/docs/RoiAzimList.doctree new file mode 100644 index 000000000..f9a57907f Binary files /dev/null and b/.doctrees/python_client/docs/RoiAzimList.doctree differ diff --git a/.doctrees/python_client/docs/RoiAzimuthal.doctree b/.doctrees/python_client/docs/RoiAzimuthal.doctree new file mode 100644 index 000000000..9f8e90848 Binary files /dev/null and b/.doctrees/python_client/docs/RoiAzimuthal.doctree differ diff --git a/.doctrees/python_client/docs/RoiBox.doctree b/.doctrees/python_client/docs/RoiBox.doctree new file mode 100644 index 000000000..929be63d0 Binary files /dev/null and b/.doctrees/python_client/docs/RoiBox.doctree differ diff --git a/.doctrees/python_client/docs/RoiBoxList.doctree b/.doctrees/python_client/docs/RoiBoxList.doctree new file mode 100644 index 000000000..65cdc1ef3 Binary files /dev/null and b/.doctrees/python_client/docs/RoiBoxList.doctree differ diff --git a/.doctrees/python_client/docs/RoiCircle.doctree b/.doctrees/python_client/docs/RoiCircle.doctree new file mode 100644 index 000000000..3fd5dacf9 Binary files /dev/null and b/.doctrees/python_client/docs/RoiCircle.doctree differ diff --git a/.doctrees/python_client/docs/RoiCircleList.doctree b/.doctrees/python_client/docs/RoiCircleList.doctree new file mode 100644 index 000000000..ea9ddcafc Binary files /dev/null and b/.doctrees/python_client/docs/RoiCircleList.doctree differ diff --git a/.doctrees/python_client/docs/RoiDefinitions.doctree b/.doctrees/python_client/docs/RoiDefinitions.doctree new file mode 100644 index 000000000..e282ae2cf Binary files /dev/null and b/.doctrees/python_client/docs/RoiDefinitions.doctree differ diff --git a/.doctrees/python_client/docs/RotationAxis.doctree b/.doctrees/python_client/docs/RotationAxis.doctree new file mode 100644 index 000000000..91189243b Binary files /dev/null and b/.doctrees/python_client/docs/RotationAxis.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveBlob.doctree b/.doctrees/python_client/docs/RugnuxLiveBlob.doctree new file mode 100644 index 000000000..e41cfbea5 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveBlob.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveFrameRange.doctree b/.doctrees/python_client/docs/RugnuxLiveFrameRange.doctree new file mode 100644 index 000000000..a2c5a3248 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveFrameRange.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveModel.doctree b/.doctrees/python_client/docs/RugnuxLiveModel.doctree new file mode 100644 index 000000000..7f1d73d2c Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveModel.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveRefinement.doctree b/.doctrees/python_client/docs/RugnuxLiveRefinement.doctree new file mode 100644 index 000000000..5e04c5475 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveRefinement.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveShell.doctree b/.doctrees/python_client/docs/RugnuxLiveShell.doctree new file mode 100644 index 000000000..880fc6be3 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveShell.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveStatus.doctree b/.doctrees/python_client/docs/RugnuxLiveStatus.doctree new file mode 100644 index 000000000..dcf0c1b69 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveStatus.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveStep.doctree b/.doctrees/python_client/docs/RugnuxLiveStep.doctree new file mode 100644 index 000000000..16c2c1d41 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveStep.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxLiveStills.doctree b/.doctrees/python_client/docs/RugnuxLiveStills.doctree new file mode 100644 index 000000000..5da413ad8 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxLiveStills.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxSettings.doctree b/.doctrees/python_client/docs/RugnuxSettings.doctree new file mode 100644 index 000000000..cffb1d5cf Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxSettings.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxStatus.doctree b/.doctrees/python_client/docs/RugnuxStatus.doctree new file mode 100644 index 000000000..b60d4cab7 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxStatus.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxSummaryRow.doctree b/.doctrees/python_client/docs/RugnuxSummaryRow.doctree new file mode 100644 index 000000000..4d2414bd8 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxSummaryRow.doctree differ diff --git a/.doctrees/python_client/docs/RugnuxTriageItem.doctree b/.doctrees/python_client/docs/RugnuxTriageItem.doctree new file mode 100644 index 000000000..93daf4838 Binary files /dev/null and b/.doctrees/python_client/docs/RugnuxTriageItem.doctree differ diff --git a/.doctrees/python_client/docs/ScanResult.doctree b/.doctrees/python_client/docs/ScanResult.doctree new file mode 100644 index 000000000..c6b205335 Binary files /dev/null and b/.doctrees/python_client/docs/ScanResult.doctree differ diff --git a/.doctrees/python_client/docs/ScanResultImagesInner.doctree b/.doctrees/python_client/docs/ScanResultImagesInner.doctree new file mode 100644 index 000000000..48359b4a7 Binary files /dev/null and b/.doctrees/python_client/docs/ScanResultImagesInner.doctree differ diff --git a/.doctrees/python_client/docs/SpotFindingSettings.doctree b/.doctrees/python_client/docs/SpotFindingSettings.doctree new file mode 100644 index 000000000..5b522e758 Binary files /dev/null and b/.doctrees/python_client/docs/SpotFindingSettings.doctree differ diff --git a/.doctrees/python_client/docs/StandardDetectorGeometry.doctree b/.doctrees/python_client/docs/StandardDetectorGeometry.doctree new file mode 100644 index 000000000..04e06feaf Binary files /dev/null and b/.doctrees/python_client/docs/StandardDetectorGeometry.doctree differ diff --git a/.doctrees/python_client/docs/TcpSettings.doctree b/.doctrees/python_client/docs/TcpSettings.doctree new file mode 100644 index 000000000..c19a1c7da Binary files /dev/null and b/.doctrees/python_client/docs/TcpSettings.doctree differ diff --git a/.doctrees/python_client/docs/UnitCell.doctree b/.doctrees/python_client/docs/UnitCell.doctree new file mode 100644 index 000000000..536658f22 Binary files /dev/null and b/.doctrees/python_client/docs/UnitCell.doctree differ diff --git a/.doctrees/python_client/docs/ZeromqMetadataSettings.doctree b/.doctrees/python_client/docs/ZeromqMetadataSettings.doctree new file mode 100644 index 000000000..6af290dcc Binary files /dev/null and b/.doctrees/python_client/docs/ZeromqMetadataSettings.doctree differ diff --git a/.doctrees/python_client/docs/ZeromqPreviewSettings.doctree b/.doctrees/python_client/docs/ZeromqPreviewSettings.doctree new file mode 100644 index 000000000..cbd200c29 Binary files /dev/null and b/.doctrees/python_client/docs/ZeromqPreviewSettings.doctree differ diff --git a/.doctrees/python_client/docs/ZeromqSettings.doctree b/.doctrees/python_client/docs/ZeromqSettings.doctree new file mode 100644 index 000000000..633af6f57 Binary files /dev/null and b/.doctrees/python_client/docs/ZeromqSettings.doctree differ diff --git a/ACKNOWLEDGEMENT.html b/ACKNOWLEDGEMENT.html new file mode 100644 index 000000000..bcca14ed9 --- /dev/null +++ b/ACKNOWLEDGEMENT.html @@ -0,0 +1 @@ + Acknowledgements — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Acknowledgements

How to cite Jungfraujoch and Rugnux, and the papers that describe them, is on the Publications page. In short:

  • Rugnux: F. Leonarski and M. Wang, “Rugnux: from diffraction images to structure at synchrotrons and XFELs in one program” (2026), bioRxiv doi:10.64898/2026.10.24.761522.

  • Jungfraujoch: F. Leonarski, M. Brückner, C. Lopez-Cuenca, A. Mozzanica, H.-C. Stadler, Z. Matěj, A. Castellane, B. Mesnet, J. Wojdyla, B. Schmitt and M. Wang, “Jungfraujoch: hardware-accelerated data-acquisition system for kilohertz pixel-array X-ray detectors” (2023), J. Synchrotron Rad. 30, 227-234 doi:10.1107/S1600577522010268; for real-time serial crystallography and live indexing feedback also J. Duan, H.-C. Stadler, J. Nan et al., “Jungfraujoch: 38 GB s⁻¹ real-time serial crystallography – data acquisition and live indexing feedback” (2026), J. Appl. Cryst. 59, 1668-1677 doi:10.1107/S1600576726008083.

Funding and support

The project is supported by:

  • Innosuisse via Innovation Project “NextGenDCU high data rate acquisition system for X-ray detectors in structural biology applications” (101.535.1 IP-ENG; Apr 2023 - Sep 2025).

  • ETH Domain via Open Research Data Contribute project (Jan - Dec 2023).

  • AMD University Program with donation of licenses of Ethernet IP cores and Vivado software.

Crystallographic methods adopted from other packages

The analysis pipeline builds on methods first published, and in most cases first implemented, by other crystallographic software. The code is Jungfraujoch’s own; the methods are theirs, and are acknowledged here, entry by entry: what was taken, from whom, and the citation. How rugnux uses each method is described in the data-analysis reference, not here. Where a package’s source was consulted this is said explicitly. Most of these packages are neither linked nor vendored; the three that are - GEMMI, traccc and fast-feedback-indexer - also carry a licence obligation, recorded in THIRD_PARTY_NOTICES.md.

Experimental geometry and physical corrections

autoPROC — the principle, long argued for by Clemens Vonrhein, that a pipeline does not take the experimental metadata it is given (beam centre, detector geometry, goniometer axis) on trust but verifies it against the images and corrects it where it is wrong, and with it that the beam centre is found from the images; the aim of a pipeline that takes the decisions an expert would take and reports the evidence for each. C. Vonrhein, C. Flensburg, P. Keller, A. Sharff, O. Smart, W. Paciorek, T. Womack and G. Bricogne, “Data processing and analysis with the autoPROC toolbox” (2011), Acta Cryst. D67, 293-302 doi:10.1107/S0907444911007773.

Sensor absorption and air path — the attenuation coefficients of silicon, CdTe, dry air and helium behind the oblique-incidence sensor efficiency, the parallax variance and the air-path attenuation are the NIST tabulation. J. H. Hubbell and S. M. Seltzer, “Tables of X-Ray Mass Attenuation Coefficients and Mass Energy-Absorption Coefficients from 1 keV to 20 MeV for Elements Z = 1 to 92 and 48 Additional Substances of Dosimetric Interest” (1995, data updated 2004), NIST Standard Reference Database 126 doi:10.18434/T4D01F.

Polarization correction — the azimuthal polarization factor for a partially polarized synchrotron source. R. Kahn, R. Fourme, A. Gadet, J. Janin, C. Dumas and D. Andre, “Macromolecular crystallography with synchrotron radiation: photographic data collection and polarization correction” (1982), J. Appl. Cryst. 15, 330-337 doi:10.1107/S0021889882012060.

Hexagonal-ice ring positions — the eleven measured ring spacings from 3.895 to 1.522 Å. D. W. Moreau, H. Atakisi and R. E. Thorne, “Ice in biomolecular cryocrystallography” (2021), Acta Cryst. D77, 540-554 doi:10.1107/S2059798321001170. The bands below 1.522 Å are calculated here from ice Ih structure factors on the lattice constants of K. Röttger, A. Endriss, J. Ihringer, S. Doyle and W. F. Kuhs, “Lattice constants and thermal expansion of H2O and D2O ice Ih between 10 and 265 K” (1994), Acta Cryst. B50, 644-648 doi:10.1107/S0108768194004933.

Powder calibrants — the silver behenate cell is T. C. Huang, H. Toraya, T. N. Blanton and Y. Wu, “X-ray powder diffraction analysis of silver behenate, a possible low-angle diffraction standard” (1993), J. Appl. Cryst. 26, 180-184 doi:10.1107/S0021889892009762; the CeO2 and silicon cells are those of the NIST standard reference materials SRM 674b and SRM 640 (certificates, no DOI).

Spot finding

CrystFEL — spot finding, the three-ring integration region, the serial/stills processing model, and the per-frame indexing acceptance test (indexing_peak_check() in peaks.c). T. A. White, R. A. Kirian, A. V. Martin, A. Aquila, K. Nass, A. Barty and H. N. Chapman, “CrystFEL: a software suite for snapshot serial crystallography” (2012), J. Appl. Cryst. 45, 335-341 doi:10.1107/S0021889812002312.

Cheetah — the per-resolution-ring background statistics with the Bragg peaks excluded by iterated clipping, from peakfinder8. A. Barty, R. A. Kirian, F. R. N. C. Maia, M. Hantke, C. H. Yoon, T. A. White and H. N. Chapman, “Cheetah: software for high-throughput reduction and analysis of serial femtosecond X-ray diffraction data” (2014), J. Appl. Cryst. 47, 1118-1131 doi:10.1107/S1600576714007626.

Poisson significance threshold — beyond the summation limit the Poisson quantile of the adaptive spot-finding threshold is taken from the Cornish-Fisher expansion. E. A. Cornish and R. A. Fisher, “Moments and cumulants in the specification of distributions” (1938), Rev. Int. Stat. Inst. 5, 307-320 doi:10.2307/1400905.

GPU spot finder — the CUDA spot finder was developed by Hans-Christian Stadler (PSI).

traccc — the sparse connected-component labelling that groups strong pixels into spots: the CPU extractor adapts its SparseCCL source, the CUDA extractor follows the design of its GPU counterpart (MPL-2.0; see THIRD_PARTY_NOTICES.md). P. Gessinger, H. M. Gray, A. Krasznahorkay, C. Leggett, J. Niermann, A. Salzburger, S. N. Swatman and B. Yeo, “traccc: GPU track reconstruction library for HEP experiments” (2025), arXiv:2505.22822. The SparseCCL algorithm itself: A. Hennequin, B. Couturier, V. V. Gligorov and L. Lacassagne, “SparseCCL: Connected Components Labeling and Analysis for sparse images” (2019), DASIP 2019, 65-70 doi:10.1109/DASIP48288.2019.9049184.

XDS and DISTL — bounding a spot by its shape (how much of its bounding box it fills) rather than by its size; the statistic is rugnux’s own. XDS is cited under Integration and rotation geometry; Z. Zhang, N. K. Sauter, H. van den Bedem, G. Snell and A. M. Deacon, “Automated diffraction image analysis and spot searching for high-throughput crystal screening” (2006), J. Appl. Cryst. 39, 112-119 doi:10.1107/S0021889805040677.

Indexing

Fourier-transform indexing — indexing with no prior knowledge of the cell by Fourier-transforming the reciprocal-space positions of the spots, proposed as a three-dimensional transform; the de-novo indexers (-X fft, -X fftw) use its one-dimensional projection form. G. Bricogne (1986), in Proceedings of the EEC Cooperative Workshop on Position-Sensitive Detector Software (Phase III), LURE, Paris, p. 28 (a workshop proceedings without a DOI).

Rossmann FFT autoindexing — projecting the reciprocal-space points onto many directions and Fourier-transforming the 1D histograms. I. Steller, R. Bolotovsky and M. G. Rossmann, “An algorithm for automatic indexing of oscillation images using Fourier analysis” (1997), J. Appl. Cryst. 30, 1036-1040 doi:10.1107/S0021889897008777.

MOSFLM — the practice of that algorithm, and the post-refinement practice of which parameters are refined per image and which over a wedge. H. R. Powell, “The Rossmann Fourier autoindexing algorithm in MOSFLM” (1999), Acta Cryst. D55, 1690-1695 doi:10.1107/S0907444999009506; A. G. W. Leslie and H. R. Powell, “Processing diffraction data with MOSFLM” (2007), in Evolving Methods for Macromolecular Crystallography, NATO Science Series II, vol. 245, 41-51 doi:10.1007/978-1-4020-6316-9_4; T. G. G. Battye, L. Kontogiannis, O. Johnson, H. R. Powell and A. G. W. Leslie, “iMOSFLM: a new graphical interface for diffraction-image processing with MOSFLM” (2011), Acta Cryst. D67, 271-281 doi:10.1107/S0907444910048675; H. R. Powell, T. G. G. Battye, L. Kontogiannis, O. Johnson and A. G. W. Leslie, “Integrating macromolecular X-ray diffraction data with the graphical user interface iMosflm” (2017), Nat. Protoc. 12, 1310-1325 doi:10.1038/nprot.2017.037.

fast-feedback-indexer — the known-cell indexer for serial stills (-X ffbidx), PSI’s library linked at build time (BSD-3-Clause; see THIRD_PARTY_NOTICES.md), implementing TORO. P. Gasparotto, L. Barba, H.-C. Stadler, G. Assmann, H. Mendonça, A. W. Ashton, M. Janousch, F. Leonarski and B. Béjar, “TORO Indexer: a PyTorch-based indexing algorithm for kilohertz serial crystallography” (2024), J. Appl. Cryst. 57, 931-944 doi:10.1107/S1600576724003182. The CPU implementation used without a GPU is a port of the library’s CUDA kernels by H.-C. Stadler (PSI).

Cell reduction and lattice symmetry

GEMMI — symmetry operations, unit-cell and structure-factor machinery, and MTZ / XDS_ASCII I/O; vendored in gemmi_gph/, so it also carries a licence obligation. M. Wojdyr, “GEMMI: A library for structural biology” (2022), J. Open Source Softw. 7, 4200 doi:10.21105/joss.04200.

Niggli reduction — used through GEMMI’s implementation. I. Křivý and B. Gruber, “A unified algorithm for determining the reduced (Niggli) cell” (1976), Acta Cryst. A32, 297-298 doi:10.1107/S0567739476000636. The table of lattice characters that maps a reduced cell to Bravais lattices and centrings follows International Tables for Crystallography Vol. A, Table 9.2.5.1.

Numerically stable cell reduction — the magnitude-scaled tolerance that decides the sign of a structurally-zero scalar product. R. W. Grosse-Kunstleve, N. K. Sauter and P. D. Adams, “Numerically stable algorithms for the computation of reduced unit cells” (2004), Acta Cryst. A60, 1-6 doi:10.1107/S010876730302186X.

Metric-symmetry search — the obliquity of the 81 candidate two-folds of a reduced cell, and the conventional axes derived from the rotation group found; the two-fold search is used through GEMMI. Y. Le Page, “The derivation of the axes of the conventional unit cell from the dimensions of the Buerger-reduced cell” (1982), J. Appl. Cryst. 15, 255-259 doi:10.1107/S0021889882011959. The step from the two-folds found to a conventional cell, a centring and an integral change of basis follows R. W. Grosse-Kunstleve, “Algorithms for deriving crystallographic space-group information” (1999), Acta Cryst. A55, 383-395 doi:10.1107/S0108767398010186.

Integration and rotation geometry

XDS — rotation geometry and notation, the reciprocal Lorentz and partiality treatment, the maximum-likelihood mosaicity estimate, the MINPK criterion for a reflection whose predicted profile is not cleanly its own, the intensity-based test for a centred lattice, the recognition of shaded detector regions (DEFPIX), and the scaling correction surfaces indexed by image number and detector region. W. Kabsch, “XDS” (2010), Acta Cryst. D66, 125-132 doi:10.1107/S0907444909047337; W. Kabsch, “Integration, scaling, space-group assignment and post-refinement” (2010), Acta Cryst. D66, 133-144 doi:10.1107/S0907444909047374.

Profile fitting — the Kabsch/Otwinowski iteration with reweighted, de-biased variances, from the second XDS paper above and from Z. Otwinowski and W. Minor, “Processing of X-ray diffraction data collected in oscillation mode” (1997), Methods Enzymol. 276, 307-326 doi:10.1016/S0076-6879(97)76066-X.

Two-dimensional integration — integrating each image in the detector plane and only afterwards combining a reflection’s partials into a full, as against three-dimensional profile fitting through the image stack, is the architecture of DENZO/SCALEPACK (Otwinowski and Minor, above) and MOSFLM (cited under Indexing).

Space group, twinning and pseudo-symmetry

POINTLESS (CCP4) — the space-group search: scoring each candidate rotation operator by the correlation of I(h) with I(Rh) on resolution-normalised intensities (E²); the screw-axis test that scores a predicted-absent class against the rest of its own axial row and lets confidence fall with the number of axial reflections instead of refusing below a count; and the same test on a zone for a glide plane. P. Evans, “Scaling and assessment of data quality” (2006), Acta Cryst. D62, 72-82 doi:10.1107/S0907444905036693; P. R. Evans, “An introduction to data reduction: space-group determination, scaling and intensity statistics” (2011), Acta Cryst. D67, 282-292 doi:10.1107/S090744491003982X; P. R. Evans and G. N. Murshudov, “How good are my data and what is the resolution?” (2013), Acta Cryst. D69, 1204-1214 doi:10.1107/S0907444913000061; J. Agirre, M. Atanasova, H. Bagdonas et al., “The CCP4 suite: integrative software for macromolecular crystallography” (2023), Acta Cryst. D79, 449-461 doi:10.1107/S2059798323003595.

Centrosymmetric glide groups — of two absence-equivalent glide groups the search writes the centrosymmetric one (P2/c over Pc, C2/c over Cc), a missed inversion centre being the common error. W. H. Baur and D. Kassner, “The perils of Cc: comparing the frequencies of falsely assigned space groups with their general population” (1992), Acta Cryst. B48, 356-369 doi:10.1107/S0108768191014726.

Centre-of-symmetry statistics — the acentric and centric intensity distributions and the cumulative N(z) test built on them, read beside <|E^2-1|> and the L test. A. J. C. Wilson, “The probability distribution of X-ray intensities” (1949), Acta Cryst. 2, 318-321 doi:10.1107/S0365110X49000813; E. R. Howells, D. C. Phillips and D. Rogers, “The probability distribution of X-ray intensities. II. Experimental investigation and the X-ray detection of centres of symmetry” (1950), Acta Cryst. 3, 210-214 doi:10.1107/S0365110X50000513.

Twinning L test — the moments of L = (I1−I2)/(I1+I2) over pairs of neighbouring acentric reflections against their untwinned and perfect-twin values; its robustness to pseudo-centering is kept by the partner steps, which are restricted when a non-half-integer pseudo-translation is found. J. E. Padilla and T. O. Yeates, “A statistic for local intensity differences: robustness to anisotropy and pseudo-centering and utility for detecting twinning” (2003), Acta Cryst. D59, 1124-1130 doi:10.1107/S0907444903007947. The test’s design - indicators on shell-normalised merged intensities, a twin law admitted within 3 degrees of obliquity - follows phenix.xtriage: Zwart, Grosse-Kunstleve and Adams (2005, cited under Data quality and anisotropy); D. Liebschner, P. V. Afonine, M. L. Baker et al., “Macromolecular structure determination using X-rays, neutrons and electrons: recent developments in Phenix” (2019), Acta Cryst. D75, 861-877 doi:10.1107/S2059798319011471.

Twin fraction and twinned intensity — the model (1−α) I(h) + α I(Th), and the fraction read from the median of H = |I(h) − I(Th)|/(I(h) + I(Th)), uniform on [0, 1−2α]. T. O. Yeates, “Detecting and overcoming crystal twinning” (1997), Methods Enzymol. 276, 344-358 doi:10.1016/S0076-6879(97)76068-3.

Twin refinement — one fraction per domain operator of the lattice refined with the model, small domains dropped, and twin-related reflections kept in one free set, as REFMAC5 does; the fractions re-fitted by least squares at every cycle as REFMAC5 refines them, against an amplitude likelihood with the twinned model amplitude in it (a simplification of REFMAC5’s twinned-intensity target). G. N. Murshudov, P. Skubák, A. A. Lebedev, N. S. Pannu, R. A. Steiner, R. A. Nicholls, M. D. Winn, F. Long and A. A. Vagin, “REFMAC5 for the refinement of macromolecular crystal structures” (2011), Acta Cryst. D67, 355-367 doi:10.1107/S0907444911001314; P. Roversi, E. Blanc, S. Johnson and S. M. Lea, “Tetartohedral twinning could happen to you too” (2012), Acta Cryst. D68, 418-424 doi:10.1107/S0907444912006737; the six-domain case of a monoclinic crystal on a hexagonal metric is K. A. Sultana, I. Alexeev, I. Kursula, P. Mäntsälä, J. Niemi and G. Schneider, “Structure determination by multiwavelength anomalous diffraction of aclacinomycin oxidoreductase: indications of multidomain pseudomerohedral twinning” (2007), Acta Cryst. D63, 149-159 doi:10.1107/S0907444906044271. A twin fraction as a parameter refined beside the model is SHELXL’s BASF (rugnux re-fits it between cycles rather than in the same least squares): R. Herbst-Irmer and G. M. Sheldrick, “Refinement of twinned structures with SHELXL97” (1998), Acta Cryst. B54, 443-449 doi:10.1107/S0108768197018454. The twin laws come from the lattice’s metric: A. A. Lebedev, A. A. Vagin and G. N. Murshudov, “Intensity statistics in twinned crystals with examples from the PDB” (2006), Acta Cryst. D62, 83-95 doi:10.1107/S0907444905036759.

Deciding pseudo-symmetry by refinement — carrying the adopted group and the index-2 subgroups a refused promotion leaves, each perfectly twinned by a law of its coset, to the model and deciding by placing and refining it in each, rather than from intensity statistics. P. H. Zwart, R. W. Grosse-Kunstleve, A. A. Lebedev, G. N. Murshudov and P. D. Adams, “Surprises and pitfalls arising from (pseudo)symmetry” (2008), Acta Cryst. D64, 99-107 doi:10.1107/S090744490705531X; A. A. Lebedev and M. N. Isupov, “Space-group and origin ambiguity in macromolecular structures with pseudo-symmetry and its treatment with the program Zanuda” (2014), Acta Cryst. D70, 2430-2443 doi:10.1107/S1399004714014795.

Twinning by reticular merohedry — a first-pass cell that is the coincidence lattice of two twin domains (reticular merohedry or pseudo-merohedry of index up to 10, e.g. obverse/reverse rhombohedral domains) is recognised by the nodes of neither domain being empty. The twin index is Friedel’s (G. Friedel, Leçons de cristallographie, 1926; no DOI); the split of the reflections into those of one domain, of the other, of both and of neither, and the treatment of reticular pseudo-merohedry (Herbst-Irmer and Sheldrick 1998, above), are Herbst-Irmer and Sheldrick’s: R. Herbst-Irmer and G. M. Sheldrick, “Refinement of obverse/reverse twins” (2002), Acta Cryst. B58, 477-481 doi:10.1107/S0108768102001039.

Translational pseudo-symmetry — the off-origin native-Patterson peak read as a pseudo-translation between copies of the asymmetric unit, and the modulation it puts on the intensities, which the axial systematic-absence test also scores against. The per-dataset permutation null for the peak, the per-row estimate of the modulation depth, and its averaging over the lattice’s rotations are rugnux’s own. R. J. Read, P. D. Adams and A. J. McCoy, “Intensity statistics in the presence of translational noncrystallographic symmetry” (2013), Acta Cryst. D69, 176-183 doi:10.1107/S0907444912045374. A pseudo-translation is declared at a Patterson peak of a fifth of the origin or more, Phaser’s default (McCoy et al. 2007, cited under Model placement and molecular replacement).

Scaling and merging

DIALS — the resolution cutoff from the CC1/2 fall-off, per-observation outlier rejection at merge, the scaling error model, and the treatment of a reflection whose background is contaminated; its published behaviour, and in places its source, settled several choices here. G. Winter, D. G. Waterman, J. M. Parkhurst et al., “DIALS: implementation and evaluation of a new integration package” (2018), Acta Cryst. D74, 85-97 doi:10.1107/S2059798317017235; D. G. Waterman, G. Winter, R. J. Gildea et al., “Diffraction-geometry refinement in the DIALS framework” (2016), Acta Cryst. D72, 558-575 doi:10.1107/S2059798316002187; J. Beilsten-Edmands, G. Winter, R. Gildea et al., “Scaling diffraction data in the DIALS software package: algorithms and new approaches for multi-crystal scaling” (2020), Acta Cryst. D76, 385-399 doi:10.1107/S2059798320003198; J. M. Parkhurst, G. Winter, D. G. Waterman et al., “Robust background modelling in DIALS” (2016), J. Appl. Cryst. 49, 1912-1921 doi:10.1107/S1600576716013595.

Wilson outlier test — judging an observation without symmetry mates against the acentric and centric distributions of its shell, with the symmetry enhancement factor; rejecting only significant observations, and keeping a reflection whose observations are all large, follows AIMLESS’s EMAX test. A. J. C. Wilson, “The probability distribution of X-ray intensities” (1949), Acta Cryst. 2, 318-321 doi:10.1107/S0365110X49000813; P. Evans, “Scaling and assessment of data quality” (2006), Acta Cryst. D62, 72-82 doi:10.1107/S0907444905036693.

Amplitudes from intensities — the posterior-mean amplitude under the acentric and centric Wilson priors. S. French and K. Wilson, “On the treatment of negative intensity observations” (1978), Acta Cryst. A34, 517-525 doi:10.1107/S0567739478001114. Giving no amplitude to an intensity more than 3.7 sigma below zero, and scaling each reflection’s prior by the anisotropy tensor along its direction, follow CCP4’s ctruncate (C. Ballard and N. Stein), cited through the suite: M. D. Winn, C. C. Ballard, K. D. Cowtan et al., “Overview of the CCP4 suite and current developments” (2011), Acta Cryst. D67, 235-242 doi:10.1107/S0907444910045749.

Absorption as spherical harmonics — the empirical absorption correction as a series of real spherical harmonics of the beam directions in the crystal frame is Blessing’s; its use as a restrained scaling surface of the diffracted-beam direction follows SCALA and AIMLESS. R. H. Blessing, “An empirical correction for absorption anisotropy” (1995), Acta Cryst. A51, 33-38 doi:10.1107/S0108767394005726; P. Evans, “Scaling and assessment of data quality” (2006), Acta Cryst. D62, 72-82 doi:10.1107/S0907444905036693.

Per-frame scale smoothing — the Whittaker smoother (a second-difference penalty, the smoothness chosen by cross-validation) in Eilers’s form. P. H. C. Eilers, “A perfect smoother” (2003), Anal. Chem. 75, 3631-3636 doi:10.1021/ac034173t; E. T. Whittaker, “On a new method of graduation” (1923), Proc. Edinburgh Math. Soc. 41, 63-75 doi:10.1017/S0013091500077853.

Fisher’s z-transformation — averaging the change of the half-set CC1/2 over resolution shells on atanh(CC) when the correction surfaces are cross-validated. R. A. Fisher, “Frequency distribution of the values of the correlation coefficient in samples from an indefinitely large population” (1915), Biometrika 10, 507-521 doi:10.2307/2331838.

Frame disposition by delta-CC1/2 — the statistic in its sigma-tau form, the Fisher transformation used to compare it, its standard error, and the rejection discipline (never remove a group whose delta-CC1/2 is positive or near zero; remove a little, re-form the reference and repeat), whose reference implementation is XDSCC12. G. Assmann, W. Brehm and K. Diederichs, “Identification of rogue datasets in serial crystallography” (2016), J. Appl. Cryst. 49, 1021-1028 doi:10.1107/S1600576716005471; G. M. Assmann, M. Wang and K. Diederichs, “Making a difference in multi-data-set crystallography: simple and deterministic data-scaling/selection methods” (2020), Acta Cryst. D76, 636-652 doi:10.1107/S2059798320006348. Applying it at scaling, to groups of images rather than whole datasets, follows DIALS (dials.scale): J. Beilsten-Edmands, G. Winter, R. Gildea et al., “Scaling diffraction data in the DIALS software package: algorithms and new approaches for multi-crystal scaling” (2020), Acta Cryst. D76, 385-399 doi:10.1107/S2059798320003198.

Reasons for a weak stretch of a sweep — named in the field’s own words: “loss of centring” after autoPROC’s “loss of centring during crystal rotation” (cited under Experimental geometry and physical corrections), and “crystal rotating out of the beam” after the HKL-2000 manual (HKL: Otwinowski and Minor 1997, cited under Integration and rotation geometry).

Several sweeps merged as one — each sweep’s partials combined into fulls on their own, then the fulls of all sweeps scaled together with per-sweep frame scales and a relative B, as XSCALE merges data sets (W. Kabsch, “Integration, scaling, space-group assignment and post-refinement” (2010), above). Ordering the sweeps by dose from their relative B follows K. Diederichs, “Some aspects of quantitative analysis and correction of radiation damage” (2006), Acta Cryst. D62, 96-101 doi:10.1107/S0907444905031537.

Reference sweep of a joint merge — the sweep whose own merge reaches the finest resolution, as KAMO takes the data set of the smallest Wilson B. K. Yamashita, K. Hirata and M. Yamamoto, “KAMO: towards automated data processing for microcrystals” (2018), Acta Cryst. D74, 441-449 doi:10.1107/S2059798318004576.

Serial data

Per-crystal post-refinement of stills — refining per still the partiality parameters the spot positions cannot pin (a small reorientation, the rocking width, the radial scale of the reciprocal lattice) against the merged intensities, after PRIME and the mosaic-block model of Sauter et al. M. Uervirojnangkoorn, O. B. Zeldin, A. Y. Lyubimov, J. Hattne, A. S. Brewster, N. K. Sauter, A. T. Brunger and W. I. Weis, “Enabling X-ray free electron laser crystallography for challenging biological systems from a limited number of crystals” (2015), eLife 4, e05421; N. K. Sauter, J. Hattne, A. S. Brewster, N. Echols, P. H. Zwart and P. D. Adams, “Improved crystal orientation and physical properties from single-shot XFEL stills” (2014), Acta Cryst. D70, 3299-3309 (DOIs not verified here, so not given).

Indexing ambiguity without a reference — putting each crystal into the indexing in which its intensities agree best with all the others, iterated to convergence, the method CrystFEL’s ambigator also implements; rugnux measures the agreement as a product of standardised amplitudes rather than a correlation. W. Brehm and K. Diederichs, “Breaking the indexing ambiguity in serial crystallography” (2014), Acta Cryst. D70, 101-109 doi:10.1107/S1399004713025431. The same objective settles the indexing of each sweep of a joint merge, decided over all pairs at once as dials.cosym does: R. J. Gildea and G. Winter, “Determination of Patterson group symmetry from sparse multi-crystal data sets in the presence of an indexing ambiguity” (2018), Acta Cryst. D74, 405-410 doi:10.1107/S2059798318002978.

Data quality and anisotropy

Data-quality statistics — R_meas and R_pim, CC1/2 and CC*, the per-shell CC(model, data), and the reporting of I/sigma(I) follow the established conventions. K. Diederichs and P. A. Karplus, “Improved R-factors for diffraction data analysis in macromolecular crystallography” (1997), Nat. Struct. Biol. 4, 269-275 doi:10.1038/nsb0497-269; P. A. Karplus and K. Diederichs, “Linking crystallographic model and data quality” (2012), Science 336, 1030-1033 doi:10.1126/science.1218231; M. S. Weiss, “Global indicators of X-ray data quality” (2001), J. Appl. Cryst. 34, 130-135 doi:10.1107/S0021889800018227; K. Diederichs and P. A. Karplus, “Better models by discarding data?” (2013), Acta Cryst. D69, 1215-1222 doi:10.1107/S0907444913001121.

Isomorphism of sweeps — CC_AB / (CC*_A CC*_B) as the cosine of the angle between two data sets, on which a joint merge decides whether a sweep joins. K. Diederichs, “Dissecting random and systematic differences between noisy composite data sets” (2017), Acta Cryst. D73, 286-293 doi:10.1107/S2059798317000699.

Diffraction anisotropy — the overall fall-off as a single anisotropic displacement tensor, its symmetry constraints and the determinacy of its deviatoric part only: S. Sheriff and W. A. Hendrickson, “Description of overall anisotropy in diffraction from macromolecular crystals” (1987), Acta Cryst. A43, 118-121 doi:10.1107/S010876738709977X. Fitting it to the intensity distribution with sigma(I) taken into account: A. N. Popov and G. P. Bourenkov, “Choice of data-collection parameters based on statistic modelling” (2003), Acta Cryst. D59, 1145-1153 doi:10.1107/S0907444903008163. The directional diffraction limits and the anisotropic deltaB reported as the range of the principal components follow AIMLESS: P. R. Evans and G. N. Murshudov, “How good are my data and what is the resolution?” (2013), Acta Cryst. D69, 1204-1214 doi:10.1107/S0907444913000061. That every run should analyse and report its anisotropy is inspired by STARANISO: I. J. Tickle, C. Flensburg, P. Keller, W. Paciorek, A. Sharff, C. Vonrhein and G. Bricogne (2016), STARANISO (staraniso.globalphasing.org/cgi-bin/staraniso.cgi), Cambridge, United Kingdom: Global Phasing Ltd. Rugnux reports the anisotropy; it corrects no intensity and removes no reflection on a directional criterion.

Uncertainty conventions — the IUCr Commission on Crystallographic Nomenclature’s. D. Schwarzenbach, S. C. Abrahams, H. D. Flack et al., “Statistical descriptors in crystallography: Report of the IUCr Subcommittee on Statistical Descriptors” (1989), Acta Cryst. A45, 63-75 doi:10.1107/S0108767388009596; D. Schwarzenbach, S. C. Abrahams, H. D. Flack, E. Prince and A. J. C. Wilson, “Statistical descriptors in crystallography. II. Report of a Working Group on Expression of Uncertainty in Measurement” (1995), Acta Cryst. A51, 565-569 doi:10.1107/S0108767395002340.

Unit-cell e.s.d.s — that the e.s.d.s of a least-squares cell fit are too small is Herbstein’s survey, which is why the cell is also fitted on blocks of consecutive frames. F. H. Herbstein, “How precise are measurements of unit-cell dimensions from single crystals?” (2000), Acta Cryst. B56, 547-557 doi:10.1107/S010876810000269X.

Measurability — the fraction of acentric Bijvoet pairs significant at three sigma, reported beside SigAno and CCanom, is phenix.xtriage’s. P. H. Zwart, “Anomalous signal indicators in protein crystallography” (2005), Acta Cryst. D61, 1437-1448 doi:10.1107/S0907444905023589.

Ice in the merged intensities — reading ice off a merge’s own intensities at the hexagonal-ice ring positions, and the table of the rings’ line strengths, are phenix.xtriage’s; rugnux’s comparison is local in resolution where xtriage’s is against the whole Wilson curve. P. H. Zwart, R. W. Grosse-Kunstleve and P. D. Adams, “Xtriage and Fest: automatic assessment of X-ray data and substructure structure factor estimation” (2005), CCP4 Newsletter on Protein Crystallography 43 (no DOI).

Advice on the next collection — the rotation a sweep needs and the blind region about the spindle that a tilted second sweep recovers. Z. Dauter, “Data-collection strategies” (1999), Acta Cryst. D55, 1703-1717 (DOI not verified here).

Model placement and molecular replacement

Bulk-solvent correction and overall scaling — the flat bulk-solvent model, its starting values and the physically meaningful range of its two parameters: A. Fokine and A. Urzhumtsev, “Flat bulk-solvent model: obtaining optimal parameters” (2002), Acta Cryst. D58, 1387-1392 doi:10.1107/S0907444902010284. The mask (the region a probe cannot reach, shrunk back), drawn with the radii REFMAC5 uses: J.-S. Jiang and A. T. Brünger, “Protein hydration observed by X-ray diffraction: solvation properties of penicillopepsin and neuraminidase crystal structures” (1994), J. Mol. Biol. 243, 100-115 doi:10.1006/jmbi.1994.1633. The grid search over the solvent pair with scale and anisotropic B refitted at each point: P. V. Afonine, R. W. Grosse-Kunstleve and P. D. Adams, “A robust bulk-solvent correction and anisotropic scaling procedure” (2005), Acta Cryst. D61, 850-855 doi:10.1107/S0907444905007894. The fit is unweighted, as there and in REFMAC5: G. N. Murshudov, P. Skubak, A. A. Lebedev, N. S. Pannu, R. A. Steiner, R. A. Nicholls, M. D. Winn, F. Long and A. A. Vagin, “REFMAC5 for the refinement of macromolecular crystal structures” (2011), Acta Cryst. D67, 355-367 doi:10.1107/S0907444911001314.

sigma_A map coefficients — the Rice and Woolfson likelihoods of |Fo| given |Fc| and sigma_A, the figure of merit m and the scale D, and the bias-corrected coefficients 2mFo-DFc (acentric) and mFo (centric). R. J. Read, “Improved Fourier coefficients for maps using phases from partial structures with errors” (1986), Acta Cryst. A42, 140-149 doi:10.1107/S0108767386099622.

ANODE — reading the anomalous difference map at the atoms of a supplied model and reporting the strongest sites by name, instead of searching the map for blobs. A. Thorn and G. M. Sheldrick, “ANODE: anomalous and heavy-atom density calculation” (2011), J. Appl. Cryst. 44, 1285-1287 doi:10.1107/S0021889811041768.

Uniform random rotations — the null a supplied model, and a molecular-replacement search, are scored against draws rotations uniformly from SO(3) through a uniform random unit quaternion. K. Shoemake, “Uniform Random Rotations”, in Graphics Gems III, ed. D. Kirk, Academic Press (1992), 124-132 (no DOI).

Variable projection — the rigid-body placement re-fits the overall scale at every step and folds that re-fit into its Jacobian, in Kaufman’s simplified form of Golub and Pereyra’s derivative. G. H. Golub and V. Pereyra, “The Differentiation of Pseudo-Inverses and Nonlinear Least Squares Problems Whose Variables Separate” (1973), SIAM J. Numer. Anal. 10, 413-432 doi:10.1137/0710036; L. Kaufman, “A variable projection method for solving separable nonlinear least squares problems” (1975), BIT 15, 49-57 doi:10.1007/BF01932995.

Predicted models — --model (and --mr) place an AlphaFold prediction by molecular replacement. J. Jumper, R. Evans, A. Pritzel et al., “Highly accurate protein structure prediction with AlphaFold” (2021), Nature 596, 583-589 doi:10.1038/s41586-021-03819-2; the models are those of the AlphaFold Protein Structure Database: M. Varadi, S. Anyango, M. Deshpande et al., “AlphaFold Protein Structure Database: massively expanding the structural coverage of protein-sequence space with high-accuracy models” (2022), Nucleic Acids Res. 50, D439-D444 doi:10.1093/nar/gkab1061. The model is prepared as phenix.process_predicted_model prepares one (residues below pLDDT 70 removed, B factors from the predicted coordinate error) and cut into rigid domains by its predicted aligned error: R. D. Oeffner, T. Croll, C. Millán et al., “Putting AlphaFold models to work with phenix.process_predicted_model and ISOLDE” (2022), Acta Cryst. D78, 1303-1314 doi:10.1107/S2059798322010026; the error itself is AlphaFold’s: J. Jumper, R. Evans, A. Pritzel et al., “Highly accurate protein structure prediction with AlphaFold” (2021), Nature 596, 583-589 doi:10.1038/s41586-021-03819-2.

Molecular replacement search — scoring each orientation of the model by interpolating its molecular transform, computed once by FFT, as AMoRe does: J. Navaza, “AMoRe: an automated package for molecular replacement” (1994), Acta Cryst. A50, 157-163 doi:10.1107/S0108767393007597. The full-symmetry translation function, all pairs of symmetry copies on one Fourier synthesis: R. A. Crowther and D. M. Blow, “A method of positioning a known molecule in an unknown crystal structure” (1967), Acta Cryst. 23, 544-548 doi:10.1107/S0365110X67003172. A placement is a solution, as Phaser calls one, where its translation-function Z-score reaches 8: A. J. McCoy, R. W. Grosse-Kunstleve, P. D. Adams, M. D. Winn, L. C. Storoni and R. J. Read, “Phaser crystallographic software” (2007), J. Appl. Cryst. 40, 658-674 doi:10.1107/S0021889807021206.

Cell contents — whether one copy fits the cell is read off the Matthews coefficient: B. W. Matthews, “Solvent content of protein crystals” (1968), J. Mol. Biol. 33, 491-497 doi:10.1016/0022-2836(68)90205-2; how many copies to search for is weighed by its distribution over protein crystals: K. A. Kantardjieff and B. Rupp, “Matthews coefficient probabilities: Improved estimates for unit cell contents of proteins, DNA, and protein-nucleic acid complex crystals” (2003), Protein Sci. 12, 1865-1871 doi:10.1110/ps.0350503. The placements of several copies are compared by least-squares superposition: W. Kabsch, “A solution for the best rotation to relate two sets of vectors” (1976), Acta Cryst. A32, 922-923 doi:10.1107/S0567739476001873.

Likelihood scoring of placements — the log-likelihood gain from the Rice and Woolfson distributions of the normalised amplitudes given the model’s, with sigma_A falling off with resolution for the model’s expected coordinate error as Luzzati’s D: V. Luzzati, “Traitement statistique des erreurs dans la détermination des structures cristallines” (1952), Acta Cryst. 5, 802-810 doi:10.1107/S0365110X52002161; R. J. Read, “Pushing the boundaries of molecular replacement with maximum likelihood” (2001), Acta Cryst. D57, 1373-1382 doi:10.1107/S0907444901012471; the gain read as a Z-score over the same orientation at other positions, as the likelihood-enhanced translation function’s is: A. J. McCoy, R. W. Grosse-Kunstleve, L. C. Storoni and R. J. Read, “Likelihood-enhanced fast translation functions” (2005), Acta Cryst. D61, 458-464 doi:10.1107/S0907444905001617; and a model whose expected log-likelihood gain is too small for a placement to stand out is not searched for: A. J. McCoy, R. D. Oeffner, A. G. Wrobel, J. R. M. Ojala, K. Tryggvason, B. Lohkamp and R. J. Read, “Ab initio solution of macromolecular crystal structures without direct methods” (2017), Proc. Natl. Acad. Sci. USA 114, 3637-3641 doi:10.1073/pnas.1701640114. Translational NCS is looked for in the native Patterson before the search, read as under Translational pseudo-symmetry. The logarithm of the Bessel function I0 is evaluated with the polynomial approximations of M. Abramowitz and I. A. Stegun, “Handbook of Mathematical Functions” (1964), National Bureau of Standards, 9.8.1-9.8.2.

Structure refinement

Likelihood target — the Rice distribution of an observed amplitude given the model’s, and its centric counterpart. N. S. Pannu and R. J. Read, “Improved structure refinement through maximum likelihood” (1996), Acta Cryst. A52, 659-668 doi:10.1107/S0108767396004370; G. N. Murshudov, A. A. Vagin and E. J. Dodson, “Refinement of macromolecular structures by the maximum-likelihood method” (1997), Acta Cryst. D53, 240-255 doi:10.1107/S0907444996012255. Its parameters are fitted in resolution bins, the variance on the free reflections and D on the working ones, as REFMAC5 divides them (Murshudov et al. 2011, above); estimating them on free reflections follows V. Y. Lunin and T. P. Skovoroda, “R-free likelihood-based estimates of errors for phases calculated from atomic models” (1995), Acta Cryst. A51, 880-887 doi:10.1107/S010876739500688X; V. Y. Lunin, P. V. Afonine and A. G. Urzhumtsev, “Likelihood-based refinement. I. Irremovable model errors” (2002), Acta Cryst. A58, 270-282 doi:10.1107/S0108767302001046.

Gradients by FFT — the derivatives of the target with respect to the structure factors transformed into a map and summed against each atom’s density derivatives. R. C. Agarwal, “A new least-squares refinement technique based on the fast Fourier transform algorithm” (1978), Acta Cryst. A34, 791-809 doi:10.1107/S0567739478001618.

Minimiser — L-BFGS (rugnux’s own implementation). D. C. Liu and J. Nocedal, “On the limited memory BFGS method for large scale optimization” (1989), Math. Program. 45, 503-528 doi:10.1007/BF01589116; its two-loop recursion: J. Nocedal, “Updating quasi-Newton matrices with limited storage” (1980), Math. Comp. 35, 773-782 doi:10.1090/S0025-5718-1980-0572855-7. The initial inverse Hessian is rescaled at each iteration by the latest pair, the self-scaling of S. S. Oren and D. G. Luenberger, “Self-scaling variable metric (SSVM) algorithms. Part I” (1974), Management Sci. 20, 845-862 doi:10.1287/mnsc.20.5.845, and D. F. Shanno and K.-H. Phua, “Matrix conditioning and nonlinear optimization” (1978), Math. Program. 14, 149-160 doi:10.1007/BF01588962.

Geometry restraints — those of the CCP4 Monomer Library, a subset of which rugnux carries (see THIRD_PARTY_NOTICES.md). A. A. Vagin, R. A. Steiner, A. A. Lebedev, L. Potterton, S. McNicholas, F. Long and G. N. Murshudov, “REFMAC5 dictionary: organization of prior chemical knowledge and guidelines for its use” (2004), Acta Cryst. D60, 2184-2195 doi:10.1107/S0907444904023510. They are applied through GEMMI’s topology (links, modifications, planes, chiral volumes, torsions): M. Wojdyr, “GEMMI: A library for structural biology” (2022), J. Open Source Softw. 7, 4200 doi:10.21105/joss.04200. The torsion derivatives follow A. Blondel and M. Karplus, “New formulation for derivatives of torsion angles and improper torsion angles in molecular mechanics: elimination of singularities” (1996), J. Comput. Chem. 17, 1132-1141 doi:10.1002/(SICI)1096-987X(19960715)17:9<1132::AID-JCC5>3.0.CO;2-T.

Riding hydrogens — placed on their parent atoms by GEMMI’s riding-hydrogen code, which follows D. Liebschner, P. V. Afonine, A. G. Urzhumtsev and P. D. Adams, “Implementation of the riding hydrogen model in CCTBX to support the next generation of X-ray and neutron joint refinement in Phenix” (2020), Methods Enzymol. 634, 177-199 doi:10.1016/bs.mie.2020.01.007.

B-factor restraints — bonded atoms, and atoms in contact, restrained to each other in the Kullback-Leibler form REFMAC5 uses (Murshudov et al. 2011, above); the divergence itself is S. Kullback and R. A. Leibler’s, “On information and sufficiency” (1951), Ann. Math. Statist. 22, 79-86 doi:10.1214/aoms/1177729694. The overall isotropic B of the scale is moved into the atoms as phenix.refine moves it (Afonine et al. 2012, below).

Weights and R-free — the weights of the X-ray term against the geometry and B restraints start from the ratios of the gradients, as X-PLOR’s crystallographic weight was first set: A. T. Brünger, M. Karplus and G. A. Petsko, “Crystallographic refinement by simulated annealing: application to crambin” (1989), Acta Cryst. A45, 50-61 doi:10.1107/S0108767388009195; and are chosen among short refinements by R-free with the geometry held within bounds, as phenix.refine chooses them: P. V. Afonine, R. W. Grosse-Kunstleve, N. Echols, J. J. Headd, N. W. Moriarty, M. Mustyakimov, T. C. Terwilliger, A. Urzhumtsev, P. H. Zwart and P. D. Adams, “Towards automated crystallographic structure refinement with phenix.refine” (2012), Acta Cryst. D68, 352-367 doi:10.1107/S0907444912001308. R-free itself: A. T. Brünger, “Free R value: a novel statistical quantity for assessing the accuracy of crystal structures” (1992), Nature 355, 472-475 doi:10.1038/355472a0.

Robust scaling of the model — the overall scale and anisotropic B are fitted by iteratively reweighted least squares with the pseudo-Huber weight. P. J. Huber, “Robust estimation of a location parameter” (1964), Ann. Math. Statist. 35, 73-101 doi:10.1214/aoms/1177703732, in the smooth form of P. Charbonnier, L. Blanc-Féraud, G. Aubert and M. Barlaud, “Deterministic edge-preserving regularization in computed imaging” (1997), IEEE Trans. Image Process. 6, 298-311 doi:10.1109/83.551699.

Metal-site restraints — the bonds of metal ions to the donor atoms the model’s LINK records name are restrained at the distances of the Monomer Library’s own metal-site statistics (metals.json, embedded as monomers/metals.cif), in line with the surveys of M. M. Harding, “Geometry of metal-ligand interactions in proteins” (2001), Acta Cryst. D57, 401-411 doi:10.1107/S0907444900019168 and “Small revisions to predicted distances around metal sites in proteins” (2006), Acta Cryst. D62, 678-682 doi:10.1107/S0907444906014594, and, for Mg²⁺, Na⁺ and K⁺ at nucleic acids, F. Leonarski, L. D’Ascenzo and P. Auffinger, “Mg2+ ions: do they bind to nucleobase nitrogens?” (2017), Nucleic Acids Res. 45, 987-1004 doi:10.1093/nar/gkw1175.

Anisotropic displacements — the TLS model of a rigid body’s translation, libration and their correlation: V. Schomaker and K. N. Trueblood, “On the rigid-body motion of molecules in crystals” (1968), Acta Cryst. B24, 63-76 doi:10.1107/S0567740868001718; refined against the likelihood with a residual B per atom, the B column read as total or residual, as in M. D. Winn, M. N. Isupov and G. N. Murshudov, “Use of TLS parameters to model anisotropic displacements in macromolecular refinement” (2001), Acta Cryst. D57, 122-133 doi:10.1107/S0907444900014736. The chains are cut into TLS groups as TLSMD cuts them: J. Painter and E. A. Merritt, “Optimal description of a protein structure in terms of multiple groups undergoing TLS motion” (2006), Acta Cryst. D62, 439-450 doi:10.1107/S0907444906005270. Atoms with a U of their own are restrained by the rigid-bond postulate of F. L. Hirshfeld, “Can X-ray data distinguish bonding effects from vibrational smearing?” (1976), Acta Cryst. A32, 239-244 doi:10.1107/S0567739476000533, in the form of SHELXL’s RIGU: A. Thorn, B. Dittrich and G. M. Sheldrick, “Enhanced rigid-bond restraints” (2012), Acta Cryst. A68, 448-451 doi:10.1107/S0108767312014535, with SHELXL’s SIMU and ISOR restraints as G. M. Sheldrick, “Crystal structure refinement with SHELXL” (2015), Acta Cryst. C71, 3-8 doi:10.1107/S2053229614024218 documents them. Which displacement model a refinement keeps is decided on the free set rather than by a rule of resolution: E. A. Merritt, “To B or not to B: a question of resolution?” (2012), Acta Cryst. D68, 468-477 doi:10.1107/S0907444911028320.

NCS restraints — copies found by sequence alignment with REFMAC5’s criterion (Murshudov et al. 2011, above) and restrained locally on pairs of corresponding interatomic distances under the Geman-McClure loss, as REFMAC5’s local NCS restraints are, with the distance range of R. A. Nicholls, F. Long and G. N. Murshudov, “Low-resolution refinement tools in REFMAC5” (2012), Acta Cryst. D68, 404-417 doi:10.1107/S090744491105606X. The superposition behind the rms criterion is GEMMI’s QCP: D. L. Theobald, “Rapid calculation of RMSDs using a quaternion-based characteristic polynomial” (2005), Acta Cryst. A61, 478-480 doi:10.1107/S0108767305015266; P. Liu, D. K. Agrafiotis and D. L. Theobald, “Fast determination of the optimal rotational matrix for macromolecular superpositions” (2010), J. Comput. Chem. 31, 1561-1563 doi:10.1002/jcc.21439. The case for local restraints over a superposition, decided by R-free: G. J. Kleywegt, “Use of non-crystallographic symmetry in protein structure refinement” (1996), Acta Cryst. D52, 842-857 doi:10.1107/S0907444995016477; I. Usón, E. Pohl, T. R. Schneider, Z. Dauter, A. Schmidt, H.-J. Fritz and G. M. Sheldrick, “1.7 Å structure of the stabilized REIv mutant T39K. Application of local NCS restraints” (1999), Acta Cryst. D55, 1158-1167 doi:10.1107/S0907444999003972; and J. J. Headd, N. Echols, P. V. Afonine, N. W. Moriarty, R. J. Gildea and P. D. Adams, “Flexible torsion-angle noncrystallographic symmetry restraints for improved macromolecular structure refinement” (2014), Acta Cryst. D70, 1346-1356 doi:10.1107/S1399004714003277, whose comparison is why the copies’ B factors are refined independently.

Special positions — an atom on a special position is kept on it, its shifts confined to the subspace its site symmetry leaves unchanged. R. W. Grosse-Kunstleve and P. D. Adams, “Algorithms for deriving crystallographic space-group information. II. Treatment of special positions” (2002), Acta Cryst. A58, 60-65 doi:10.1107/S0108767301016658.

Solvent, ions and unmodelled density

Unmodelled density — the connected regions of the difference map above a cutoff, found by flood fill as Coot’s “unmodelled blobs” are, in GEMMI’s implementation. P. Emsley, B. Lohkamp, W. G. Scott and K. Cowtan, “Features and development of Coot” (2010), Acta Cryst. D66, 486-501 doi:10.1107/S0907444910007493.

Water build — the documented ordered-solvent defaults of phenix.refine (difference-map peaks from 3 σ, picking to 2.8 Å, waters added, filtered and refined between macro-cycles; Afonine et al. 2012, above); the distance band to the model, widened a little from the 2.4-3.2 Å Coot’s Find Waters keeps (Emsley et al. 2010, above); and the removal of a water in negative difference density at -3 σ (Echols et al. 2014, below).

Ion stereochemistry — the coordination bands, the Mg²⁺ exclusion zone and the clash shells of the surveys of ions at nucleic acids by P. Auffinger’s group. N. Naleem, A. Henning-Knechtel, S. Kirmizialtin and P. Auffinger, “Cat_Wiz: a stereochemistry-guided toolkit for locating, diagnosing, and annotating Mg2+ ions in RNA structures” (2026), Nucleic Acids Res. 54, gkag120 doi:10.1093/nar/gkag120; F. Leonarski, A. Henning-Knechtel, S. Kirmizialtin, E. Ennifar and P. Auffinger, “Principles of ion binding to RNA inferred from the analysis of a 1.55 Å resolution bacterial ribosome structure – Part I: Mg2+” (2025), Nucleic Acids Res. 53, gkae1148 doi:10.1093/nar/gkae1148; F. Leonarski, L. D’Ascenzo and P. Auffinger, “Nucleobase carbonyl groups are poor Mg2+ inner-sphere binders but excellent monovalent ion binders—a critical PDB survey” (2019), RNA 25, 173-192 doi:10.1261/rna.068437.118; and their 2017 survey (above). The score that combines the criteria is rugnux’s own.

Ion identification — the ligand sphere of the bond-valence sums, the reading of halides by their donors, and telling a light ion from a water by its density: N. Echols, N. Morshed, P. V. Afonine, A. J. McCoy, M. D. Miller, R. J. Read, J. S. Richardson, T. C. Terwilliger and P. D. Adams, “Automated identification of elemental ions in macromolecular crystal structures” (2014), Acta Cryst. D70, 1104-1114 doi:10.1107/S1399004714001308; N. Morshed, N. Echols and P. D. Adams, “Using support vector machines to improve elemental ion identification in macromolecular crystal structures” (2015), Acta Cryst. D71, 1147-1158 doi:10.1107/S1399004715004241. The chloride’s shell of donors: O. Carugo, “Buried chloride stereochemistry in the Protein Data Bank” (2014), BMC Struct. Biol. 14, 19 doi:10.1186/s12900-014-0019-8; halides at hydrophobic surfaces: Z. Dauter and M. Dauter, “Entering a new phase: using solvent halide ions in protein structure determination” (2001), Structure 9, R21-R26 doi:10.1016/S0969-2126(01)00565-2.

Bond-valence sums — I. D. Brown and D. Altermatt, “Bond-valence parameters obtained from a systematic analysis of the Inorganic Crystal Structure Database” (1985), Acta Cryst. B41, 244-247 doi:10.1107/S0108768185002063, with the R₀ of N. E. Brese and M. O’Keeffe, “Bond-valence parameters for solids” (1991), Acta Cryst. B47, 192-197 doi:10.1107/S0108768190011041, as tabulated by H. Zheng, K. M. Langner, G. P. Shields, J. Hou, M. Kowiel, F. H. Allen, G. Murshudov and W. Minor, “Data mining of iron(II) and iron(III) bond-valence parameters, and their relevance for macromolecular crystallography” (2017), Acta Cryst. D73, 316-325 doi:10.1107/S2059798317000584; weighted by occupancy as P. Müller, S. Köpke and G. M. Sheldrick weight them, “Is the bond-valence method able to identify metal atoms in protein structures?” (2003), Acta Cryst. D59, 32-37 doi:10.1107/S0907444902018000; the normalised vector sum and its outlier bound are CheckMyMetal’s: H. Zheng, D. R. Cooper, P. J. Porebski, I. G. Shabalin, K. B. Handing and W. Minor, “CheckMyMetal: a macromolecular metal-binding validation tool” (2017), Acta Cryst. D73, 223-233 doi:10.1107/S2059798317001061.

Anomalous scattering factors — f″ at the data’s wavelength, as GEMMI computes it (its port of the Larch routines). D. T. Cromer and D. A. Liberman, “Anomalous dispersion calculations near to and on the long-wavelength side of an absorption edge” (1981), Acta Cryst. A37, 267-268 doi:10.1107/S0567739481000600, with the corrections of L. Kissel and R. H. Pratt, “Corrections to tabulated anomalous-scattering factors” (1990), Acta Cryst. A46, 170-175 doi:10.1107/S0108767389010718.

Software and computing methods

GPU decompression — decoding bitshuffle+LZ4 images on the GPU rather than on the host follows Jon Wright (ESRF): “Experiences with GPU decompression for bitshuffle + LZ4 data”, HDF5 User Group meeting (2021), and bslz4decoders. The CUDA kernels are Jungfraujoch’s own; the approach is his.

Parallel connected components — removing the islands of the bulk-solvent mask on the GPU with a parallel union-find. D. P. Playne and K. Hawick, “A New Algorithm for Parallel Connected-Component Labelling on GPUs” (2018), IEEE Trans. Parallel Distrib. Syst. 29, 1217-1230 doi:10.1109/TPDS.2018.2799216.

Correctly rounded integer division — the FFT indexer’s GPU peak search divides by a reciprocal multiplication corrected once by the exact remainder. P. W. Markstein, “Computation of elementary functions on the IBM RISC System/6000 processor” (1990), IBM J. Res. Dev. 34, 111-119.

Anderson acceleration — of the per-frame scaling loops of the rotation merge, in the type-II form. H. F. Walker and P. Ni, “Anderson acceleration for fixed-point iterations” (2011), SIAM J. Numer. Anal. 49, 1715-1735 doi:10.1137/10078356X, after D. G. Anderson, “Iterative procedures for nonlinear integral equations” (1965), J. ACM 12, 547-560 doi:10.1145/321296.321305.

Bootstrap — the interval reported for ISa. B. Efron, “Bootstrap methods: another look at the jackknife” (1979), Ann. Statist. 7, 1-26 doi:10.1214/aos/1176344552. Its draws are Poisson weights hashed with the SplitMix64 finaliser of G. L. Steele Jr., D. Lea and C. H. Flood, “Fast splittable pseudorandom number generators” (2014), Proc. OOPSLA 2014, 453-472 doi:10.1145/2660193.2660195.

Error-free floating-point arithmetic — the single-precision exp shared between the CPU and an Apple GPU (BraggExp.h): the argument reduction of W. J. Cody and W. Waite, “Software Manual for the Elementary Functions” (1980), Prentice-Hall; the exact product (with Veltkamp’s split) and Fast2Sum of T. J. Dekker, “A floating-point technique for extending the available precision” (1971), Numer. Math. 18, 224-242; and the 2Sum of D. E. Knuth, “The Art of Computer Programming, Vol. 2: Seminumerical Algorithms”, section 4.2.2.

Colormaps — Viridis, Magma and Inferno from Matplotlib, under its BSD-compatible license. J. D. Hunter, “Matplotlib: A 2D graphics environment” (2007), Comput. Sci. Eng. 9, 90-95 doi:10.1109/MCSE.2007.55.

Mol* — the web frontend’s structure viewer. D. Sehnal, S. Bittrich, M. Deshpande, R. Svobodová, K. Berka, V. Bazgier, S. Velankar, S. K. Burley, J. Koča and A. S. Rose, “Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures” (2021), Nucleic Acids Res. 49, W431-W437 doi:10.1093/nar/gkab314. Its setup follows the one Guillaume Gotthard (PSI) tuned for AareDB, the sample-management and data-pipeline system of the PSI MX beamlines: the Coot-style mouse controls, the model representations and colours, and the display of the density maps. The virtual trackball is a port of Coot’s, itself a port of SGI’s trackball.c by Gavin Bell.

File formats read from a published specification

CBF / imgCIF — the native miniCBF reader implements the x-CBF_BYTE_OFFSET compression and the imgCIF _axis table from the specification alone; no CBFlib or other CBF code is used. H. J. Bernstein and A. P. Hammersley, “Specification of the Crystallographic Binary File (CBF/imgCIF)” (2006), International Tables for Crystallography Vol. G, 37-43 doi:10.1107/97809553602060000729; A. P. Hammersley, H. J. Bernstein and J. D. Westbrook, “Image dictionary (imgCIF)” (2006), International Tables for Crystallography Vol. G, 444-458 doi:10.1107/97809553602060000746.

PILATUS count-rate clipping — that the count-rate correction clips an over-range pixel to the cutoff rather than flagging it, which is how the miniCBF reader tells a saturated pixel. P. Trueb, C. Dejoie, M. Kobas, P. Pattison, D. J. Peake, V. Radicci, B. A. Sobott, D. A. Walko and C. Broennimann, “Bunch mode specific rate corrections for PILATUS3 detectors” (2015), J. Synchrotron Rad. 22, 701-707 doi:10.1107/S1600577515003288.

d*TREK SMV — the SMV reader reads the d*TREK header vocabulary of Rigaku’s CrystalClear from the headers themselves, interpreting the detector vectors as dxtbx does; no d*TREK or dxtbx code is used. J. W. Pflugrath, “The finer things in X-ray diffraction data collection” (1999), Acta Cryst. D55, 1718-1725 doi:10.1107/S090744499900935X; dxtbx: J. M. Parkhurst, A. S. Brewster, L. Fuentes-Montero, D. G. Waterman et al., “dxtbx: the diffraction experiment toolbox” (2014), J. Appl. Cryst. 47, 1459-1465 doi:10.1107/S1600576714011996.

Public diffraction data used for testing

In addition to in-house datasets collected at SLS 2.0, Jungfraujoch is tested against public diffraction data collected on other people’s beamlines, on detectors and in file formats we do not produce ourselves. Every dataset used, the DOI to cite for it, and the deposition it belongs to are listed in EXTERNAL_TEST_DATA and EXTERNAL_TEST_DATA_STILLS; we thank the depositors, and the repositories that make the data findable and citable.

IRRMC, the Integrated Resource for Reproducibility in Macromolecular Crystallography (Minor lab, University of Virginia), is the source of the largest share of them; it releases its data under CC0 and asks that the DOI of the dataset be cited. M. Grabowski, K. M. Langner, M. Cymborowski, P. J. Porebski, P. Sroka, H. Zheng, D. R. Cooper, M. D. Zimmerman, M.-A. Elsliger, S. K. Burley and W. Minor, “A public database of macromolecular diffraction experiments” (2016), Acta Cryst. D72, 1181-1193 doi:10.1107/S2059798316014716; M. Grabowski, M. Cymborowski, P. J. Porebski, T. Osinski, I. G. Shabalin, D. R. Cooper and W. Minor, “The Integrated Resource for Reproducibility in Macromolecular Crystallography: Experiences of the first four years” (2019), Struct. Dyn. 6, 064301 doi:10.1063/1.5128672.

SBGrid Data Bank, the structural biology community’s data publication service (SBGrid Consortium, Harvard Medical School). P. A. Meyer, S. Socias, J. Key, E. Ransey, E. C. Tjon, A. Buschiazzo et al., “Data publication with the structural biology data grid supports live analysis” (2016), Nat. Commun. 7, 10882 doi:10.1038/ncomms10882.

Zenodo, CERN’s open repository, hosts datasets deposited there directly by the groups that collected them. European Organization for Nuclear Research and OpenAIRE, “Zenodo” (2013), CERN doi:10.25495/7GXK-RD71. The IUCrData Raw Data Letters describing some of those deposits are cited on the EXTERNAL_TEST_DATA page.

CXIDB, the Coherent X-ray Imaging Data Bank, is the source of the serial (XFEL stills) datasets. F. R. N. C. Maia, “The Coherent X-ray Imaging Data Bank” (2012), Nat. Methods 9, 854-855 doi:10.1038/nmeth.2110.

MXRDR, the Macromolecular Xtallography Raw Data Repository (ICM, University of Warsaw), releases its data under CC0 and asks that the DOI of the dataset be cited.

XRDa, the Xtal Raw Data Archive (Protein Data Bank Japan), publishes raw diffraction images and mints a DOI for each, which it asks to be cited. It has no canonical citation paper.

The ESRF data portal, through which the European Synchrotron publishes raw data under its data policy (CC BY 4.0, with the dataset DOI to be cited). R. Dimper, A. Götz, A. De Maria, V. A. Solé, M. Chaillet and B. Lebayle, “ESRF Data Policy, Storage, and Services” (2019), Synchrotron Rad. News 32, 7-12 doi:10.1080/08940886.2019.1608119.

The Keele University research data repository and UQ eSpace (The University of Queensland) host the raw images of datasets deposited there by the groups that collected them; the dataset DOIs are cited on the EXTERNAL_TEST_DATA page.

The Protein Data Bank supplies, through the RCSB PDB data API, the beamline, resolution, space group and unit cell quoted for each dataset, and the deposited coordinates and structure factors of the public entries the refinement battery starts from. H. M. Berman, J. Westbrook, Z. Feng, G. Gilliland, T. N. Bhat, H. Weissig, I. N. Shindyalov and P. E. Bourne, “The Protein Data Bank” (2000), Nucleic Acids Res. 28, 235-242 doi:10.1093/nar/28.1.235.

The Crystallography Open Database supplies the reference cells of the small-molecule sets. S. Gražulis, D. Chateigner, R. T. Downs, A. F. T. Yokochi, M. Quirós, L. Lutterotti, E. Manakova, J. Butkus, P. Moeck and A. Le Bail, “Crystallography Open Database – an open-access collection of crystal structures” (2009), J. Appl. Cryst. 42, 726-729 doi:10.1107/S0021889809016690; S. Gražulis, A. Daškevič, A. Merkys et al., “Crystallography Open Database (COD): an open-access collection of crystal structures and platform for world-wide collaboration” (2012), Nucleic Acids Res. 40, D420-D427 doi:10.1093/nar/gkr900.

The AlphaFold Protein Structure Database (EMBL-EBI and Google DeepMind) supplies the start models of the battery’s timing benchmark: the predictions of the deposited entities of 9ZLO (AF-P17090-F1), 9S02 (AF-P32322-F1) and 9GJX (AF-Q65MG6-F1) and, for the in-house benchmark, of horse myoglobin (AF-P68082-F1) and bovine cytochrome c (AF-P62894-F1), model version 6, with their predicted aligned error, kept unmodified in tools/battery/models/ under CC BY 4.0. J. Jumper, R. Evans, A. Pritzel et al., “Highly accurate protein structure prediction with AlphaFold” (2021), Nature 596, 583-589 doi:10.1038/s41586-021-03819-2; M. Varadi, S. Anyango, M. Deshpande et al., “AlphaFold Protein Structure Database: massively expanding the structural coverage of protein-sequence space with high-accuracy models” (2022), Nucleic Acids Res. 50, D439-D444 doi:10.1093/nar/gkab1061; M. Varadi, D. Bertoni, P. Magana et al., “AlphaFold Protein Structure Database in 2024: providing structure coverage for over 214 million protein sequences” (2024), Nucleic Acids Res. 52, D368-D375 doi:10.1093/nar/gkad1011. The large case of both benchmarks is the deposited model of PDB entry 4NWV, moved away from its place.

Generative AI usage declaration

Large language models were used extensively in developing this code. Jungfraujoch development was supported with JetBrains AI (mostly GPT models) to refactor and verify particular code fragments. Rugnux was developed with the assistance of Claude Code (mostly the Opus model). This documentation was written with the assistance of Claude Opus and Fable models.

\ No newline at end of file diff --git a/CBOR.html b/CBOR.html new file mode 100644 index 000000000..4aacb138b --- /dev/null +++ b/CBOR.html @@ -0,0 +1 @@ + CBOR messages — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

CBOR messages

To communicate between the FPGA-equipped receiver system and the writers, Jungfraujoch uses binary CBOR encoding with the tinycbor library (Intel). The protocol is based on and compatible with DECTRIS Stream2. There are minor differences at the moment:

  • LZ4 alone is not allowed; Bitshuffle+LZ4 and Bitshuffle+Zstandard are allowed

  • A few fields are currently absent

  • Extra fields are present beyond DECTRIS standard

  • There are calibration and metadata messages defined beyond DECTRIS specification

Start message

Field name

Type

Description

Present in DECTRIS format

type

String

value “start”

X

magic_number

uint64

Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver

detector_distance

float

Detector distance [m]

detector_translation

Array(float)

Detector translation vector [m]

X

beam_center_x

float

Beam center in X direction [pixels]

X

beam_center_y

float

Beam center in Y direction [pixels]

X

direct_beam_x

float (optional)

Where the undeflected beam lands on the detector, X [pixels]. Not the same point as beam_center_x, which is the PONI - the foot of the perpendicular from the sample - and separates from the beam position as soon as the detector is tilted. This is the number a program that asks for “the beam centre” (XDS ORGX, for one) wants

direct_beam_y

float (optional)

Where the undeflected beam lands on the detector, Y [pixels] (XDS ORGY)

countrate_correction_enabled

bool

Countrate correction enabled

X

countrate_correction_lookup_table

uint32 array (optional)

Maps a measured count c to its corrected value [c], as sent by a DECTRIS detector

X

flatfield_enabled

bool

Flatfield enabled

X

virtual_pixel_interpolation_enabled

bool (optional)

Virtual pixel interpolation enabled, as reported by a DECTRIS detector

X

number_of_images

uint64

Number of images in the series

X

image_size_x

uint64

Image width [pixels]

X

image_size_y

uint64

Image height [pixels]

X

mirror_y

bool

Whether the assembled image is mirrored in Y relative to the detector’s raw readout order. True is the MX convention - row 0 at the top of the detector seen from the sample - and is what absence of the key means

detector_orientation_mirror_y

bool

Whether the assembled image is mirrored in Y relative to the frame the PONI angles are stated in. A different setting from mirror_y above, which is about the module layout; this one changes no pixel. Absence means false

detector_orientation_quarter_turns

int

How many multiples of 90 degrees about the beam the assembled image is turned by, relative to the frame the PONI angles are stated in (0-3). Absence means 0

detector_modules

Array(object) (optional)

Panels: where the image’s pixels lie on the detector plane the geometry describes. Each has x0, y0, width, height (int, the panel’s box in the image) and ox, oy, fx, fy, sx, sy (double, plane pixels): image pixel (x, y) of the panel is at (ox, oy) + (x - x0) (fx, fy) + (y - y0) (sx, sy); fast_axis, slow_axis (string Xp/Xn/Yp/Yn, optional, default Xp/Yp) say which way the panel’s readout axes run in the image, naming it in a module placement. Absent for a flat detector, the image being the plane; spot and reflection positions are always plane coordinates

incident_energy

float

X-ray energy [eV]

X

incident_wavelength

float

X-ray wavelength [Angstrom]

X

incident_wavelength_spread

float (optional)

FWHM of the X-ray wavelength distribution [Angstrom] (NXmx incident_wavelength_spread); omitted when the beam is monochromatic

beam_size_x

float (optional)

Horizontal size of the X-ray beam at the sample [m] (first element of NXmx incident_beam_size)

beam_size_y

float (optional)

Vertical size of the X-ray beam at the sample [m] (second element of NXmx incident_beam_size)

frame_time

float

Frame time, if multiple frames per trigger [s]

X

count_time

float

Exposure time [s]

X

saturation_value

int64

Maximum valid sample value

X

error_value

int64 (optional)

Value used in images to describe pixels that are in error state or missing

pixel_size_x

float

Pixel width [m]

X

pixel_size_y

float

Pixel height [m]

X

sensor_thickness

float

Sensor thickness [m]

X

sensor_material

string

Sensor material

X

arm_date

date

Approximate date of arming

X

pixel_mask_enabled

bool

Pixel mask applied on images

X

detector_description

string

Name of the detector

X

detector_serial_number

string

Detector serial number

X

series_unique_id

string

Unique text ID of the series (run_name parameter)

X

series_id

uint64

Unique numeric ID of the series (run_number parameter)

X

fluorescence

object (optional)

X-ray fluorescence spectrum collected at start

- energy

Array(float)

Energy of measuring point [eV]

- data

Array(float)

Fluorescence scan result data [arbitrary units]; must be strictly the same length as energy

goniometer

Map

Definition of rotation axis (optional)

X

- AXIS

string

Rotation axis name (e.g. omega) - only one axis is supported in Jungfraujoch

X

- - increment

float

Rotation axis increment (per image) in degree [deg]

X

- - start

float

Rotation axis start angle [deg]

X

- - axis

Array(float)

Vector for the rotation axis

- - helical_step

Array(float)

Translation for helical scan for 1 image [m]

- - screening_wedge

Array(float)

Wedge for screening [deg] (increment would correspond to difference between screening points)

grid_scan

object

Grid scan definition (optional). Send goniometer with it, increment 0, to state the angle the spindle stood at; without one the spindle is recorded at 0, meaning “nobody said”

- n_fast

uint64

Number of elements along fast axis

- n_slow

uint64

Number of elements along slow axis

- step_x_axis

float

Step along X axis, can be negative [m]

- step_y_axis

float

Step along Y axis, can be negative [m]

- snake_scan

bool

Snake scan (rows alternate direction)

- vertical_scan

bool

Vertical scan (enabled: fast direction = Y, disabled: fast direction = X)

jungfrau_conversion_enabled

bool (optional)

Applying JUNGFRAU pixel conversion (to photons or keV)

jungfrau_conversion_factor

float (optional)

Factor used for JUNGFRAU conversion [eV]

geometry_transformation_enabled

bool (optional)

Transformation from detector module geometry (512x1024) to full detector geometry

pixel_mask

Map(string -> Image)

Pixel mask - multiple in case of storage cells

X

channels

Array(string)

List of image channels

X

max_spot_count

uint64

Maximum number of spots identified in spot finding

max_extra_lattices

uint64

Maximum number of extra lattices

storage_cell_number

uint64 (optional)

Number of storage cells used by JUNGFRAU

storage_cell_delay

Rational

Delay of storage cells in JUNGFRAU

threshold_energy

Map(string -> float)

Per-channel threshold energy [eV] (map of channel name to value)

image_dtype

string

Pixel type of the image data: uint8, uint16, uint32 (DECTRIS), plus int8, int16, int32 as a Jungfraujoch extension. Sole wire encoding of both the bit depth and the sign, and must agree with the per-image typed-array tag

X

unit_cell

object (optional)

Unit cell of the system: a, b, c [angstrom] and alpha, beta, gamma [degree]

az_int_q_bin_count

uint64

Number of azimuthal integration bins in the radial direction

az_int_phi_bin_count

uint64

Number of azimuthal integration bins in the phi angle direction

az_int_bin_to_q

Array(float)

Q value for each azimuthal integration bin [angstrom^-1]

az_int_bin_to_two_theta

Array(float)

Two theta angle value for each azimuthal integration bin [deg]

az_int_bin_to_phi

Array(float)

Phi value for each azimuthal integration bin [deg]

az_int_map

Image

Mapping between pixel and bin number

summation

uint64

Factor of frame summation

user_data

string

JSON serialized to string that can contain the following fields (all fields are optional):

X

- file_prefix

string

File prefix

- images_per_file

uint64

Number of images written per file

- images_per_trigger

uint64

Number of images collected per trigger

- source_name

string

Facility name

- source_type

string

Type of X-ray source (use NXsource/type values, for example “Synchrotron X-ray Source” or “Free-Electron Laser”)

- instrument_name

string

Instrument name

- sample_name

string

Name of the sample

- user

any valid JSON

Value of header_appendix provided at collection start to Jungfraujoch

- attenuator_transmission

float

Attenuator transmission []

- total_flux

float

Total flux [ph/s]

- space_group_number

uint64

Space group number

- summation_mode

string

Summation mode (internal|fpga|cpu)

- overwrite

bool

Overwrite existing HDF5 files

- file_format

int

File writer format: 0 = only data files, 1 = NXmx legacy external links, 2 = NXmx VDS, 3 = NXmx integrated, 4 = CBF (retired; rejected), 5 = TIFF (retired; rejected), 6 = no file written

- roi

Array(object)

ROI configurations; each has a name (the key of its roi_integrals entry and of /entry/roi/<name> in HDF5) and is one of:

type “box”: xmin, xmax, ymin, ymax (numbers)

type “circle”: r, x, y (numbers)

type “azim”: qmin, qmax (numbers); optional phi_min, phi_max (numbers, deg) for an angular sector

- gain_file_names

Array(string)

Names of JUNGFRAU gain files used for the current detector

- write_master_file

bool

With multiple sockets, it selects which socket will provide master file

- write_images

bool

Write images in the HDF5 file (if false, will only write metadata)

- data_reduction_factor_serialmx

uint64

Data reduction factor for serial MX

- experiment_group

string

ID of instrument user, e.g., p-group (SLS/SwissFEL) or proposal number

- jfjoch_release

string

Jungfraujoch release number

- socket_number

uint64

Number of ZeroMQ socket (on jfjoch_broker side) used for transmission

- bit_depth_readout

uint64

Bit depth of the stored image (see note below), copied to NXmx bit_depth_readout

- underload_value

int64

Lowest valid value; copied to NXmx underload_value. 0 for an unsigned image, INTx_MIN + 1 for a signed one

- writer_notification_zmq_addr

string

ZeroMQ address to inform jfjoch_broker about writers that finished operation

- xfel_pulse_id

uint64

Pulse IDs are recorded for images

- ring_current_mA

float

Ring current at the start of the measurement

- sample_temperature_K

float

Sample temperature [K]

- detect_ice_rings

bool

Ice ring detection feature is enabled; absent where the dataset settings left it unset (rugnux then decides)

- indexing_algorithm

string

Indexing algorithm used on-the-fly; allowed values: ffbidx, fft, fftw, none

- geom_refinement_algorithm

string

Post-indexing detector geometry refinement algorithm; allowed values: none, beam_center

- poni_rot1

float

Tilt of the detector rot1 according to PyFAI PONI convention [rad]

- poni_rot2

float

Tilt of the detector rot2 according to PyFAI PONI convention [rad]

- poni_rot3

float

Tilt of the detector rot3 according to PyFAI PONI convention [rad]

- smargon

object

Smargon head position, where one was given: chi_deg, phi_deg and the chi_axis, phi_axis vectors

roi_map

Image

ROI bitmask per pixel (uint16, bit n = pixel belongs to ROI n); present when ROIs are defined

See DECTRIS documentation for definition of Image as MultiDimArray with optional compression.

Image message

Every scalar of the image message is optional: a quantity that was not computed for the image is absent from the map, whatever the column below says. spots[].panel, az_int_profile_std, indexing_extra_lattices and roi_integrals are likewise present only where there is something to report; the reflection fields qe and flight are always written.

Field name

Type

Description

Present in DECTRIS format

Optional

type

String

value “image”

X

magic_number

uint64

Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver

series_unique_id

string

Unique text ID of the series (run_name parameter)

X

series_id

uint64

Unique numeric ID of the series (run_number parameter)

X

image_id

uint64

Number of image within the series; for MX lossy compression this is sequential excluding removed frames

X

original_image_id

uint64

Number of image within the series; for MX lossy compression this includes removed frames in the count

real_time

Rational

Exposure time

X

start_time

Rational

Exposure start time (highly approximate)

X

end_time

Rational

Exposure end time (highly approximate)

X

spots

Array(object)

Spots:

- x

float

observed position in x (pixels)

- y

float

observed position in y (pixels)

- I

float

intensity (photons)

- maxc

int64

max count (photons)

- ice_ring

bool

spot in resolution range for ice rings

- indexed

bool

indexed solution

- latt

int64

Lattice to which the peak belongs (negative number = not indexed)

- image

int64

image number the spot belongs to

- panel

int64 (optional)

panel (index into detector_modules) the spot was found on; absent for a detector without a panel table

- h

int64

Miller index (indexed spots only)

- k

int64

Miller index (indexed spots only)

- l

int64

Miller index (indexed spots only)

- dist_ewald

float

distance to Ewald sphere [Angstrom^-1] (indexed spots only)

reflections

Array(object)

Reflections:

- h

int64

Miller index

- k

int64

Miller index

- l

int64

Miller index

- x

float

predicted position in x (pixels)

- y

float

predicted position in y (pixels)

- obs_x

float

observed position in x (pixels)

- obs_y

float

observed position in y (pixels)

- d

float

resolution [Angstrom]

- I

float

integrated intensity (photons)

- bkg

float

mean background value (photons)

- var_bkg

float

non-signal (background) part of sigma^2, carried to the merge (photons^2)

- sigma

float

standard deviation, estimated from counting statistics (photons)

- image

int64

image number the reflection belongs to

- rp

float

Distance to Ewald sphere [Angstrom^-1]

- rlp

float

Reciprocal Lorentz-polarization factor: the multiplier taking the raw integrated count toward a quantity proportional to |F|^2. Lorentz x polarization only - a still has no Lorentz term, so there it is the polarization alone

- qe

float

Sensor efficiency at the reflection’s angle of incidence, QE(0)/QE(alpha); <= 1, and 1 where the sensor is opaque or unknown. Carried beside rlp, not inside it: the total correction is rlp * qe. Optional

- flight

float

Attenuation of the reflection in the flight path between the sample and its pixel, normalised to normal incidence; >= 1, and exactly 1 for a vacuum path. Carried beside rlp and qe: the total correction is rlp * qe * flight. Optional

- partiality

float

Partiality of the reflection

- phi

float

phi angle from XDS: difference from middle of current frame, not absolute [deg]

- zeta

float

Lorentz zeta factor (reciprocal-space geometry term)

- image_scale_corr

float

Per-image scale correction; I_true = image_scale_corr * I

spot_count

uint64

Spot count

spot_count_ice_rings

uint64

Number of spots within identified rings (experimental)

spot_count_low_res

uint64

Number of spots in low resolution (prior to filtering)

spot_count_indexed

uint64

Number of spots which fit indexing solution within a given tolerance

az_int_profile

Array(float)

Azimuthal integration results, use az_int_bin_to_q from start message for legend

NaN is used for empty bins and has to be taken care by the receiver

az_int_profile_std

Array(float)

Standard deviation for azimuthal integration. (NaN for less than 2 samples)

az_int_profile_count

Array(uint64)

Number of pixels contributing to azimuthal bin

indexing_result

bool

Indexing successful

indexing_lattice_count

int64

Number of indexing lattices found for this image

indexing_lattice

Array(9 * float)

Indexing result real lattice; present only if indexed

X

indexing_extra_lattices

Array(Array(9*float))

Additional indexed lattices (orientation variants); present only if found

indexing_unit_cell

object

Indexing result unit cell: a, b, c [angstrom] and alpha, beta, gamma [degree]; present only if indexed

X

Unit cell is redundant to lattice - yet to simplify downstream programs to analyze results, both are provided

profile_radius

float

Profile radius of the image - describes distance of observed reflections from the Ewald sphere [Angstrom^-1]

integrated_reflections

int64

Count of integrated reflections

mosaicity

float

Angular range of spots in image from a rotation scan [degree]

b_factor

float

Estimated B-factor (Angstrom^2)

compression_time

float

Time spent on compression/decompressing image [s]

preprocessing_time

float

Time spent on preparing the image for analysis [s]

azint_time

float

Time spent on azimuthal integration [s]

spot_finding_time

float

Time spent on spot finding [s]

indexing_time

float

Time spent on indexing [s]

refinement_time

float

Time spent on refinement of indexing solution and experimental geometry [s]

index_analysis_time

float

Time spent on analyzing indexing solution, calculating profile radius and mosaicity [s]

bragg_prediction_time

float

Time spent on predicting Bragg spots [s]

integration_time

float

Time spent on Bragg integration [s]

image_scale_time

float

Time spent on on-the-fly scaling [s]

processing_time

float

Total processing time [s]

xfel_pulse_id

uint64

Bunch ID (for pulsed source, e.g., SwissFEL)

X

xfel_event_code

uint64

Event code (for pulsed source, e.g., SwissFEL)

X

lattice_type

object

Bravais lattice classification of the indexing result (present only if available)

X

- centering

string

One-letter centering code: P, A, B, C, I, F, or R

- niggli_class

int64

Integer identifier for the Niggli-reduced Bravais class

- system

string

Crystal system: triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, cubic

jf_info

uint64

Detector info field

receiver_aq_dev_delay

uint64

Receiver internal delay

receiver_free_send_buf

uint64

Receiver internal number of available buffer locations

receiver_buf_in_sending

uint64

Receiver internal number of buffer locations currently in sending/writing

receiver_buf_in_preparation

uint64

Receiver internal number of buffer locations currently in processing

storage_cell

uint64

Storage cell number

saturated_pixel_count

uint64

Saturated pixel count

pixel_sum

int64

Sum of pixels, excl. device-masked, error and saturated (negative values included)

error_pixel_count

uint64

Error pixel count

strong_pixel_count

uint64

Strong pixel count (first stage of spot finding)

min_viable_pixel_value

int64

Minimal pixel value, excl. error and saturation

max_viable_pixel_value

int64

Maximal pixel value, excl. error and saturation

resolution_estimate

float

Resolution the merged data are predicted to reach, from this image’s spots alone [Angstrom]

X

data_collection_efficiency

float

Image collection efficiency []

packets_expected

uint64

Number of packets expected per image (in units of 2 kB)

packets_received

uint64

Number of packets received per image (in units of 2 kB)

bkg_estimate

float

Mean value for pixels in resolution range from 3.0 to 5.0 A [photons]

ice_ring_score

float

Strongest hexagonal-ice ring intensity over the smooth radial background (1 = no ice)

spindle_blind_fraction

float

Fraction (0-1) of a rotation sweep’s blind cone this orientation makes unrecoverable, as a lone-2-fold worst-case bound; >= 0.5 should engage a recovery protocol, and ABSENT means the frame could not be assessed, which automation must treat the same way

spot_count_ice_control

float

Spots in the ice-free flanks beside the hexagonal rings, rescaled to the ring bands’ own q width (control for spot_count_ice_rings)

beam_corr_x

float

Beam center correction X applied during processing [pixel]

X

beam_corr_y

float

Beam center correction Y applied during processing [pixel]

X

image_scale_factor

float

Scaling result: Image scale factor (g)

X

image_scale_mosaicity

float

Scaling result: Image scale mosaicity [deg]

X

image_scale_cc

float

Scaling result: Image scale CC

X

adu_histogram

Array(uint64)

ADU histogram

roi_integrals

Map(string -> object)

Results of ROI calculation, one entry per ROI keyed by its name

X

- sum

int64

Sum of pixels in ROI area [photons]

- sum_square

int64

Sum of squares of pixels in ROI area [photons]

- pixels

uint64

Valid pixels in ROI area

- max_count

int64

Highest count in ROI area [photons]

- x_weighted_sum

int64

ROI pixel X position multiplied by photon count [photons * pixels]

- y_weighted_sum

int64

ROI pixel Y position multiplied by photon count [photons * pixels]

user_data

string

Optional user defined text information - this is image_appendix serialized to JSON format

X

data

Map(string -> Image)

Image

X

Metadata message

Field name

Type

Description

Present in DECTRIS format

Optional

type

String

value “metadata”

X

magic_number

uint64

Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver

series_unique_id

string

Unique text ID of the series (run_name parameter)

X

series_id

uint64

Unique numeric ID of the series (run_number parameter)

X

images

Array(object)

Array of images (order and size of the array are not guaranteed)

X

- …

Every field of the image message except spots, reflections and data (the image itself), with the same names, types and optionality

End message

Field name

Type

Description

Present in DECTRIS format

type

String

value “end”

X

magic_number

uint64

Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver

series_unique_id

string

Unique text ID of the series (run_name parameter)

X

series_id

uint64

Unique numeric ID of the series (run_number parameter)

X

end_date

string

Approximate end date

max_image_number

uint64

Number of image with the highest number; counted from 1 to distinguish zero images and one image

transformations

Array(object) (optional)

Sample transformation chain in mounting order, base first. Each element mirrors a NeXus NXtransformations axis: name, transformation_type (rotation/translation), units, vector, offset, depends_on (the axis this one is mounted on, empty for the base), optional equipment and equipment_component (NXtransformations attributes; equipment_component is smargon on a head’s chi/phi, which is how a reader tells them from the spindle), and values - a single number for an axis that does not move, otherwise one per image. An ARRAY because the order matters and a CBOR map has none. Optional: when absent the writer builds the same chain from the start message. It is in the END message because a producer may want to report positions that were measured rather than commanded, which are only known once the run is over

images_collected

uint64

Number of images collected

images_sent_to_write

uint64

Number of images sent to writer; if writer queues were full, it is possible this is less than images collected

data_collection_efficiency

float

Overall network packets collected / network packets expected

az_int_result

Map(text->Array(float))

Azimuthal integration results, use az_int_bin_to_q from start message for legend

adu_histogram

Map(text->Array(uint64))

ADU values histogram

adu_histogram_bin_width

uint64

Width of bins in the above histogram [ADU]

max_receiver_delay

uint64

Internal performance of Jungfraujoch

bkg_estimate

float

Mean background estimate for the whole run

refined_beam_center_x

float

Beam centre X the frames were analysed at, where the analysis refined it [pixel]

refined_beam_center_y

float

Beam centre Y the frames were analysed at, where the analysis refined it [pixel]

refined_detector_distance_mm

float

Detector distance the frames were analysed at, where the analysis refined it [mm]

spindle_blind_fraction

float

Run mean of the per-image spindle_blind_fraction, over the frames that had one

spindle_lost_unique_fraction

float

Fraction (0-1) of unique reflections the mounting made unmeasurable, exact under the measured point group; offline (Rugnux) only

indexing_rate

float

Mean indexing rate for the whole run

unit_cell

object (optional)

Unit cell of the system, based on the actual experiment: a, b, c [angstrom] and alpha, beta, gamma [degree]

unit_cell_esd

object (optional)

e.s.d.s of unit_cell, same layout: a, b, c [angstrom] and alpha, beta, gamma [degree]; rotation, offline (Rugnux) and in-broker analysis only

space_group_name

string (optional)

The space group determined by the analysis, gemmi extended Hermann-Mauguin (carries the setting; what a reader should take)

space_group_number

uint64 (optional)

Its International Tables number, beside the name for a reader written before the name existed

rotation_lattice_type

object

Bravais lattice classification of the total rotation solution over the run, if available; same schema as lattice_type

- centering

string

One-letter centering code: P, A, B, C, I, F, or R

- niggli_class

int64

Integer identifier for the Niggli-reduced Bravais class

- system

string

Crystal system: triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, cubic

rotation_lattice

Array(9 * float)

Real-space lattice basis, flattened 3x3 in row-major order

rotation_extra_lattices

Array(Array(9*float))

Additional indexed lattices (orientation variants); present only if found

data_collection_efficiency_image

Array(float)

Per-image data collection efficiency. Missing values are encoded as 0 or 1 depending on producer context

spot_count

Array(int32)

Per-image spot count

spot_count_ice_ring

Array(int32)

Per-image number of spots within identified ice-ring resolution ranges

key is singular here; the per-image message uses spot_count_ice_rings

spot_count_low_res

Array(int32)

Per-image number of low-resolution spots

spot_count_indexed

Array(int32)

Per-image number of spots fitting indexing solution

image_indexed

Array(uint8)

Per-image indexing result; 0 = not indexed, nonzero = indexed

v_bkg_estimate

Array(float)

Per-image background estimate

v_spindle_blind_fraction

Array(float)

Per-image spindle_blind_fraction; NaN where the frame had no value (which is “cannot say”, not zero)

ice_ring_score

Array(float)

Per-image strongest ice-ring intensity over the smooth radial background (1 = no ice)

spot_count_ice_control

Array(float)

Per-image spot count in the ice-free flanks beside the hexagonal rings, rescaled to the ring bands’ q width

ice_ring_score_mean

float

Mean ice-ring score for the whole run (1 = no ice)

profile_radius

Array(float)

Per-image profile radius [Angstrom^-1]

mosaicity

Array(float)

Per-image mosaicity [degree]

bFactor

Array(float)

Per-image estimated B-factor [Angstrom^2]

resolution_estimate

Array(float)

Per-image predicted merged resolution, from spots alone [Angstrom]

min_viable_pixel_value

Array(int64)

Per-image minimum valid pixel value, excluding error/saturated pixels

max_viable_pixel_value

Array(int64)

Per-image maximum valid pixel value, excluding error/saturated pixels

saturated_pixel_count

Array(int32)

Per-image saturated pixel count

error_pixel_count

Array(int32)

Per-image error pixel count

image_scale_factor

Array(float)

Per-image scale factor, if scaling/merging was performed

integrated_reflections

Array(int32)

Per-image count of integrated reflections

indexed_lattice_count

Array(int32)

Per-image count of indexed lattices

niggli_class

Array(uint8)

Per-image Niggli class identifier for indexed images; 0 if unavailable

pixel_sum

Array(int64)

Per-image sum of pixels, excl. device-masked, error and saturated (0 for an image with no analysis)

image_scale_mosaicity

Array(float)

Scaling result: Image scale mosaicity [deg]

image_scale_cc

Array(float)

Scaling result: Image scale CC

merged

object (optional)

Merged reflections of an in-broker analysis run, written by the writer as <file_prefix>.mtz. An MTZ table (layout below)

map_coefficients

object (optional)

Map coefficients of an in-broker analysis run, written as <file_prefix>_maps.mtz. An MTZ table (layout below)

placed_model

object (optional)

Atomic model placed against the data, written as <file_prefix>_model.cif and <file_prefix>_model.pdb. name (string), unit_cell (object, as above), space_group_name (the data’s, gemmi extended H-M), model_space_group_name (the coordinates’), then one array per atom: model_number, seq_num, charge (int32), chain, residue_name, atom_name, element (Array(string)), icode (uint8, space where none), het_flag (uint8, A, H or 0 where unknown), altloc (uint8, 0 where none), x, y, z (double, Angstrom), b_iso, occupancy (float), aniso (float, 6 per atom: U11 U22 U33 U12 U13 U23; empty where no atom has one), subchain, entity_id (Array(string), mmCIF label_asym_id / label_entity_id), label_seq (int32, label_seq_id, INT32_MIN where none) - these three optional; metadata_mmcif (gzipped string, optional, see Notes on gzipped text): the input model’s metadata (entities, sequences, references, authors, software, secondary structure) as mmCIF categories without coordinates, parsed by the writer with gemmi

refined_model

object (optional)

The placed model after refinement, written as <file_prefix>_refined_model.cif and <file_prefix>_refined_model.pdb; same layout as placed_model

refined_map_coefficients

object (optional)

Map coefficients of the refined model, written as <file_prefix>_refined_maps.mtz. An MTZ table (layout below)

blobs

object (optional)

Unexplained blobs of the refined model’s mFo-DFc map, strongest first, written as <file_prefix>_blobs.json. One array per field, one entry per blob: kind (Array(string): WATER, ION, LIGAND, MODEL_ERROR, UNASSIGNED), x, y, z (double, centroid, Angstrom), peak_sigma (double, map rms), volume (double, Angstrom^3), score (double, sigma Angstrom^3), nearest_atom (Array(string)), nearest_atom_distance (double, Angstrom), polar_contacts, metal_contacts (int32), anomalous_sigma (double, 0 where there is no anomalous map)

report

gzipped string (optional)

The in-broker analysis run’s results report, written as <file_prefix>_report.txt: the text rugnux writes as its own _report.txt (see RUGNUX_REPORT)

End-message vector fields are optional. When present, they provide master-file summary data so readers can inspect scan-level and per-image analysis results without opening every linked data file. Missing optional per-image values are encoded by the producer as zero unless otherwise noted.

An MTZ table (merged, map_coefficients, refined_map_coefficients) carries an MTZ file’s content as the writer writes it, column by column:

Field name

Type

Description

title

string

MTZ title

unit_cell

object

a, b, c [angstrom] and alpha, beta, gamma [degree]

space_group_name

string

Space group, gemmi extended Hermann-Mauguin (keeps the setting)

history

Array(string)

MTZ HISTORY records

sort_order

Array(int32)

MTZ sort order, 5 entries

datasets

Array(object)

One per MTZ dataset: project_name, crystal_name, dataset_name (string), wavelength (float, Angstrom; 0 = not set)

columns

Array(object)

One per MTZ column: label (string), type (string, one character: the MTZ column type H, J, F, Q, I, …), dataset_id (int), values (float typed array, one per row)

batches

Array(object)

One per image of unmerged data (empty for merged data): number (int), title (string), ints (int32), floats (float) - the MTZ batch header arrays - and axes (Array(string), goniostat axis names)

Calibration message

Field name

Type

Description

Present in DECTRIS format

type

String

value “calibration”

magic_number

uint64

Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver

data

Map(string -> Image)

Calibration map (only single pedestal array per message)

User data

Facilities often need to forward more metadata than Jungfraujoch models explicitly. For this reason two fields can be provided: header_appendix (sent with the start message) and image_appendix (sent with the image message). To increase flexibility, both appendices can contain any valid JSON message. These appendices are serialized into string and stored in CBOR messages as user_data.

Notably for start message, user_data carries more information (non-DECTRIS compliant metadata, the fields listed above). It is still a JSON text string; its member user holds the header_appendix defined in OpenAPI of Jungfraujoch.

Notes on images and compression

  • Images are encoded as DECTRIS MultiDimArray with typed array tags:

    • For RGB: shape [3, height, width], type: u8

    • For grayscale: shape [height, width], type according to bit depth and sign (e.g., uint16 LE)

  • Compression:

    • Uncompressed: raw CBOR byte string

    • Bitshuffle+LZ4: tag with [“bslz4”, elem_size, bytes]

    • Bitshuffle+Zstandard: tag with [“bszstd”, elem_size, bytes]. The BSHUF_ZSTD, BSHUF_ZSTD_RLE and BSHUF_ZSTD_RLE_HUFF algorithms all travel under this tag, and a receiver decodes the tag as plain BSHUF_ZSTD.

    • The start message’s pixel_mask, az_int_map and roi_map are always Bitshuffle+LZ4.

Notes on gzipped text

The long texts of the END message - report and the metadata_mmcif of placed_model and refined_model - are sent gzipped (RFC 1952), under the same tag as compressed images: tag 56500 with [“gzip”, 1, bytes], bytes being one gzip stream of the UTF-8 text. A reader that knows the tag also accepts a plain text string there. A reader that does not know it finds a tag where it expects a text string and refuses the END message, rather than writing the files without the text.

Notes on typed arrays

Jungfraujoch uses RFC 8746-style typed byte-string tags for compact numeric arrays.

Common tags used in this protocol include:

  • float32 little-endian arrays for Array(float)

  • uint8 arrays for compact boolean/integer flags such as image_indexed

  • int32 little-endian arrays for per-image counts

  • int64 little-endian arrays for large per-image integer values

  • uint64 little-endian arrays for histograms

\ No newline at end of file diff --git a/CHANGELOG.html b/CHANGELOG.html new file mode 100644 index 000000000..ad9c60671 --- /dev/null +++ b/CHANGELOG.html @@ -0,0 +1 @@ + Changelog — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Changelog

1.0.0

1.0.0-rc.186

  • jfjoch_broker (experimental): Live Rugnux covers serial collections from DECTRIS detectors; a rotation collection too large for the image buffer falls back to standard per-image processing with a warning, and a stream that ends without its end message finishes the collection instead of hanging it.

  • jfjoch_broker (experimental): Live Rugnux settings to build the solvent during refinement and to process a rotation collection as stills, a Clear action for the last result, a _report.txt for live rotation runs, R-free reported for the refined model, and ice-ring detection on by default for rotation as in the command line.

  • jfjoch_broker (experimental): More complete and reproducible live serial merges, analysed for twinning, pseudo-translation and anisotropy, with merging statistics by resolution shell in the live status.

  • jfjoch_writer: Live results with large models are written reliably; update jfjoch_writer together with jfjoch_broker (the data interface release is now 7, a mismatched writer refuses the run at its start).

  • Rugnux: Several masters can be processed together with --force-still, including grid scans; more robust and faster merging of several sweeps; improved twinning, pseudo-translation, anisotropy, anomalous-signal and space-group decisions.

  • Rugnux: Molecular replacement places the copies of a multi-copy solution together; the pseudo-translation warning quotes the Patterson peak and is not raised once a model is placed; the report advises on extending the rotation or reorienting the crystal where the coverage would gain from it.

  • Web frontend: Light and dark modes, a phone layout, a hideable page list, a redesigned Rugnux live page with step-through of the Fo-Fc peaks in the structure view.

  • jfjoch_viewer: A broker URL given on the command line follows the running collection.

1.0.0-rc.185

  • jfjoch_broker: The master file records the unit cell given for the collection, not the mean of the per-image refined cells; the redundant input_unit_cell is no longer written.

1.0.0-rc.184

  • Rugnux: Rotation processing recovers most of the speed lost since 1.0.0-rc.180; live processing in jfjoch_broker finishes sooner.

  • Rugnux: More reliable rotation processing and indexing, including small molecules and supercells.

  • Rugnux: More robust serial data and model refinement; molecular replacement handles multi-chain models.

  • jfjoch_broker (experimental): Live serial processing keeps the detector geometry fixed for the whole run.

  • jfjoch_broker: Pixel sum without an FPGA, a mask bit for inactive pixels, and several stability fixes.

  • jfjoch_broker: Rotation indexing and quick integration moved to rugnux live mode; their API settings are deprecated and ignored.

  • jfjoch_broker, Rugnux: Azimuthal integration can use logarithmic (log10) Q bins or a given number of bins, set from the API, the web interface and the Rugnux command line.

  • jfjoch_viewer: Build and display fixes; the README is rewritten.

1.0.0-rc.183

  • jfjoch_broker (experimental): Serial data are merged live, with intermediate results during the collection.

  • Rugnux: More robust processing of serial data, including CCD detectors.

  • Rugnux: Parts of a rotation sweep that spoil the merge are removed automatically.

  • Rugnux: Clearer maps, and anomalous peaks not explained by the model are reported.

  • Rugnux: SHELX files work with SHELXL; XFEL pulse IDs are kept in _process.h5.

  • Web frontend: Spot-finding settings change only when the user changes them.

  • Rugnux: Faster processing.

1.0.0-rc.182

  • Rugnux: Fixed indexing of stills of a centred lattice with a known cell.

  • jfjoch_broker (experimental): Live Rugnux processing of serial collections.

  • Rugnux: Stills detector modules are placed from the data and written to <prefix>_module_placement.json; --panel-refine replaces --refine-modules.

  • Rugnux: More reliable rotation processing - indexing, monoclinic setting, space-group choice and refinement of multi-domain twins.

1.0.0-rc.181

  • Rugnux: Several rotation sweeps of one crystal are merged as one dataset (rugnux a_master.h5 b_master.h5), on a common indexing and cell, with a non-isomorphous sweep left out and reported; --sweeps separate processes each sweep on its own. Bruker .sfrm frames and imgCIF files with a full goniometer axis chain are read.

  • Rugnux: More robust rotation processing - a retry with a more sensitive spot finder when no lattice is found, a self-consistent detector distance, long axes and doubled cells tested as hypotheses, a -C supercell multiple stepped down, and each ice ring merged, down-weighted or rejected on its own.

  • Rugnux: Serial stills are merged with a partiality-aware error model, reported as ERROR_MODEL_A/B/C with no ISa or R_merge/R_meas/R_pim; runs without -S have an overall intensity scale about 0.86-0.88 times that of earlier versions, with unchanged statistics. A second crystal form is left out of the merge and reported, the indexing ambiguity is resolved more reliably, and --model no longer influences processing.

  • Rugnux: The reported CC1/2 is the standard unweighted one, which can be lower than before on sweeps with weak frames; ISa comes with a 95% interval (ISA_LOW/ISA_HIGH).

  • Rugnux: Model refinement adds anisotropic/TLS, local NCS and twin refinement where R-free supports them; building waters and relabelling ions is now off by default (--refine-solvent turns it on).

  • NXmx: A detector of several modules is written as module_0 … module_N only, so DIALS reads each module as its own panel.

  • Other: JPEG previews use a bundled encoder (libjpeg-turbo no longer needed), Rugnux prints how to cite it, and the release archives contain the HTML documentation.

1.0.0-rc.180

  • Rugnux: A placed model is refined by default - restrained maximum-likelihood refinement on the GPU (CPU without one), writing <prefix>_refined_model.cif, <prefix>_refined_maps.mtz and the difference-map blobs in <prefix>_blobs.json; --no-refine skips it.

  • Rugnux: --mode refine refines a model against merged structure factors from an MTZ or mmCIF file.

  • Rugnux: The embedded restraint dictionary covers amino acids, nucleotides including common modified RNA nucleotides, common cofactors, crystallisation additives, waters and ions, with metal sites restrained from the model’s LINK records.

  • Rugnux: A model or reference file can be given among the inputs in any order, recognised by its contents.

  • Rugnux: The geometry refinement algorithm option is now -r, --geom-refine (was --refine).

  • Rugnux: Serial stills resolve the indexing ambiguity from the data when no model or reference is given, reject merge outliers by default, follow the run’s measured rocking curve in prediction and partiality (also in --mode scale), and index reproducibly on the GPU.

  • Rugnux: Reflections touching the beam-stop shadow are not integrated, reflections coarser than the low-resolution limit are merged and written (but kept out of the scale fit), and the polarisation plane is measured more reliably.

  • Rugnux: Small-molecule runs report unit-cell e.s.d.s, in a SHELX .ins beside the .hkl and in the mmCIF.

  • jfjoch_broker: Live Rugnux refines the uploaded model after placement; the web frontend’s Rugnux live page has a hero panel with resolution, ISa, space group, placement and refined R-work/R-free, and its Mol* viewer shows the refined model and maps.

  • Documentation: A new front page with download pages for Rugnux and the viewer, and the technical reference reorganised below it.

  • Build: The fast-feedback indexer is part of the source tree instead of being downloaded at build time.

1.0.0-rc.179

  • Rugnux: Stills processing needs only the unit cell and space group beyond what the file records - detector distance, beam centre, tilt, panel placement, saturation level, gain and polarisation plane are found from the images - and is up to twice as fast.

  • Rugnux: Stills can be indexed without a GPU, with a CPU implementation of the fast-feedback indexer (macOS, computers without a GPU).

  • Rugnux: Rotation and stills data are integrated in the detector’s own units with one gain model, improving data from CCD detectors.

  • Web frontend: The Rugnux live page shows the placed model with its electron density and anomalous difference map in a Mol* viewer.

1.0.0-rc.178

  • Rugnux: Processes serial crystallography data from XFELs - SACLA (MPCCD), PAL-XFEL and European XFEL (CXI), LCLS (XTC) and SwissFEL Alvra (JUNGFRAU with a CrystFEL module geometry) - with several files or Jungfraujoch master files merged in one run (rugnux *_master.h5).

  • Rugnux: Stills processing takes a known unit cell and space group as a starting point, finds the beam centre (and, with a cell, the detector distance) from the images, detects the saturation level in other facilities’ files and refines the placement of individual detector panels.

  • Rugnux: The stills report gives R_split and CC1/2 from frame half-sets, comparable with CrystFEL.

  • jfjoch_viewer: Opens the same XFEL file formats.

  • Validation: A stills battery checks Rugnux against deposited structures from SACLA, PAL-XFEL, LCLS, European XFEL and SwissFEL.

  • Rugnux: More reliable convergence of rotation scaling, and live molecular replacement starts as soon as the model is uploaded.

  • jfjoch_broker: Initialize clears the previous dataset’s bearer tokens, image buffer and live Rugnux status, and a slow CUDA JIT cache is reported at start.

1.0.0-rc.177

  • jfjoch_broker: Faster live Rugnux analysis, with the GPU indexers prepared at the start of a collection and kept between collections; Rugnux no longer writes .ccp4 maps (the map coefficients are in <prefix>_maps.mtz).

1.0.0-rc.176

  • jfjoch_broker: Optional live Rugnux analysis of DECTRIS rotation collections inside the broker, with merged data, maps and the placed model written beside the master file, the rotation lattice in the scan result, and a “Rugnux live” tab and dashboard row in the web frontend.

  • Rugnux: Faster processing, with molecular replacement and model validation spread over several GPUs and run on the Apple GPU on macOS.

  • Rugnux: The polarization stated in miniCBF and d*TREK headers is used, twinned crystals’ space groups are decided more reliably, and a run that finds no lattice still reports every image.

1.0.0-rc.175

  • Rugnux: Processes a collection live while jfjoch_broker writes it (rugnux <master.h5> <broker URL>).

  • Rugnux: Processing starts on the first images and confirms its choices once all are in, so analysis can begin during collection.

  • Rugnux: Faster processing, especially on servers with several GPUs and CPU sockets and on computers without a GPU (--no-gpu, macOS).

  • Rugnux: Uses much less GPU memory, so large data sets stay on the GPU of smaller cards, and a data set too large for the card is processed on the CPU instead.

  • Rugnux: On macOS, Bragg integration runs on the Apple GPU.

  • Rugnux: Better handling of twinning and pseudo-symmetry, with the twin hypothesis written as <prefix>_twin_<SG>.mtz, and a wrong --model no longer confirms the data or decides the hand.

  • Rugnux: --model accepts predicted (AlphaFold) models and falls back to molecular replacement when the model is not placed as a rigid body (experimental --mr forces it), settling space group, hand and twinning and writing a different answer as <prefix>_mr.mtz.

  • Rugnux: Molecular replacement is faster and settles the space group in more cases with several copies in the asymmetric unit.

  • Rugnux: Deposition-ready mmCIF, a richer report, and numbered steps on the terminal with the full log in <prefix>_log.txt; _P1.mtz, --estimate-beam-center and --beam-center-search are removed.

  • Rugnux: The beam-stop shadow is found correctly on tilted detectors.

  • Rugnux: Stills files that record a stationary goniometer axis get the default stills geometry refinement.

  • jfjoch_viewer: “Analyze dataset” uses the same defaults as a bare rugnux <file>, and shows the results of processed CBF, marCCD and SMV sweeps.

  • jfjoch_viewer: The Files panel refreshes on F5 and every few seconds, and the plot type and other selections stay put during live collection.

  • jfjoch_writer: Memory stays bounded and old data files are closed efficiently on long runs, any failure ends the run in an error state the broker is told about, and the master file appears only after its data files; the ZeroMQ pusher logs when a stalled writer makes it drop images.

  • Fixes: The TCP image pusher no longer blocks the broker’s receiver, GPU out-of-memory failures stop with a clear message, and the XDS plugin masks module and chip edges.

1.0.0-rc.174

  • Rugnux: Performance improvements on GPU and CPU (more of the pre-scan and of scaling on the GPU, faster CPU spot finding and crystal refinement), with unchanged results.

  • Rugnux: More robust processing - patches of persistently hot pixels are masked, an inconsistent merge triggers a retry at the measured beam centre, and builds targeting different CPU levels give the same results.

  • Rugnux: Improved scaling and merging - reflections with an overloaded pixel are dropped, as in XDS, sparse rotation sweeps are scaled more reliably, and French-Wilson amplitudes use an anisotropic Wilson prior.

  • Rugnux: Improved space-group determination - glide planes in groups without a centre of symmetry, screw axes from short or weak axial rows kept when a higher group is adopted, and more reliable decisions on twinned and pseudo-symmetric crystals.

  • Rugnux: Improved small-molecule processing - spots that grow wider than the integration disk and split spots are integrated over their measured footprint, sparse lattices are integrated on every frame, and the .hkl file holds unmerged scaled reflections (SHELX HKLF 4).

  • Rugnux: Reads Rigaku d*TREK SMV images (Saturn CCD), including detector 2theta and encoded pixel overflows; home-source (rotating-anode) datasets were added to the validation battery.

  • jfjoch_viewer: Fixed processing failing at the end with “Wrong JPEG library version” on Linux; the merge window shows the space group with proper subscripts and a checklist of crystal pathologies.

1.0.0-rc.173

  • 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.

1.0.0-rc.172

  • Fixed jfjoch_broker cancelling every data collection with a CUDA “out of memory” error after long operation: GPU memory no longer leaks with each collection.

  • Rugnux scales a rotation sweep until the per-frame scales settle instead of for a fixed three rounds, and says so when they did not - merged intensities, and the space group, resolution cut and frame rejection read off them, change accordingly; --scaling-iterations is now the cap on that loop (default 100).

  • Rugnux places every frame of a marCCD, SMV or miniCBF series at the spindle angle its own header states, so a series with missing frames, or with angles written modulo 360, is no longer read at the wrong geometry or refused.

  • Every rotation run writes two diagnostic files beside its reflections: <prefix>_detector.jpg, the detector projection with the pixel mask and the detected beam-stop shadow drawn on it, and <prefix>_plot.txt, one row per image.

1.0.0-rc.171

  • Rugnux: basic support for CCD images (marCCD, SMV) and for gzipped miniCBF.

  • jfjoch_viewer: opens the CCD formats, and fixes to the dataset plots.

  • Documentation updates.

1.0.0-rc.170

  • Fixed a jfjoch_broker crash during indexing: sorting no longer misbehaves on non-finite values, and GPU FFT indexer kernel launches are now error-checked.

  • Rugnux needs about 40% less peak memory to scale, merge and post-refine rotation data, with identical results.

  • rugnux --model: the placed coordinate file carries the space group its own coordinates obey, and says so when that is not the group the reflection files beside it carry.

  • jfjoch_viewer: fixes in the dataset plots, inspector and layout; spot markers lose their black outline by default (a checkbox under “Image features” restores it) and the highest-pixel markers are white boxes around the pixel.

1.0.0-rc.169

  • Building Jungfraujoch no longer needs zlib or Eigen installed on the machine, and the dependencies the build fetches are pinned and updated to current releases.

  • Rugnux: improvements in indexing, lattice selection and geometry post-refinement, which index crystals that previously returned no lattice and keep the better of the two geometries a run measures.

  • Rugnux: improvements in beam-centre measurement, beam-stop detection and space-group determination.

  • Rugnux: the unit cell reported with a determined space group now obeys that group - a cell whose symmetry was confirmed from the intensities is re-refined under it, and a cell the group cannot describe is reported with a warning rather than as it stands.

  • Rugnux drops the stretches of a rotation sweep whose removal measurably improves the merged intensities and reports what became of every frame, and decides the resolution cut on the crystal’s own diffraction rather than on its ice rings.

  • The Rugnux results report is machine-readable - every line that is not KEY= value data starts with # - and states the build it was written by, its authorship and its terms of use (REPORT_VERSION= 8).

  • jfjoch_viewer: improvements in the file manager (CBF frames beside HDF5 datasets, a remembered root), the dataset plots, the inspector and the image statistics, plus a settable font size, a view of the Rugnux results report, usable performance over a remote display (ssh -X) and a reset of all settings to defaults; the reciprocal-space window is removed.

  • Broker fixes around DECTRIS collections and dark-mask calibration: re-initialising after a run that never started no longer freezes the broker, a cancelled calibration is abandoned instead of reported as done, and a collection whose start message never arrives ends by itself.

1.0.0-rc.168

  • Rugnux is substantially faster - a corpus of 145 rotation datasets processes in about two thirds of the time - with identical results.

  • A crystal whose lattice looks more symmetric than it is because the beam centre is off is no longer processed on the wrong cell.

  • Rugnux prints at startup, and writes at the foot of every results report, a short acknowledgement of the X-ray research community whose methods it implements and of the open-source projects it builds on; ACKNOWLEDGEMENT.md now ships in every package beside LICENSE and THIRD_PARTY_NOTICES.md.

1.0.0-rc.167

  • rugnux --model reports CC(model, data) - the correlation of the merged intensities with the placed, scaled model - by resolution shell, on the same shells as CC1/2, with the reflection count and a significance for each.

  • rugnux --model fits the model’s scale, anisotropic B and bulk-solvent parameters on the working reflections only, so the R-free it reports is measured against a model no free reflection helped scale.

  • The bulk-solvent parameters of rugnux --model are searched over their physically meaningful range instead of being fitted without bounds, so a model is never scaled with a solvent term that has silently switched itself off.

  • The rigid-body placement of rugnux --model uses the same bounded bulk solvent as the reported fit, so a model is no longer placed against a target carrying a solvent term with no physical meaning.

  • rugnux --model puts the model into the data’s own description of the lattice before placing it, so a model whose cell is written on other axes - I-centred where the run indexed C-centred, a different unique axis, a permuted orthorhombic cell - is placed rather than scored where it was read; MODEL_CHANGE_OF_BASIS= and MODEL_SETTING_AS_READ= report it when it happens.

  • The Rugnux results report opens with a summary - VERDICT= (OK, WARNINGS, UNUSABLE, FAILED), VERDICT_TEXT=, PATHOLOGY_FLAGS= with one closed-vocabulary code per condition that warned, and the WARNING: lines, which used to close the file - and the sections after it are renumbered 1-5 with no gaps.

  • rugnux --developer writes the full results report - the pipeline-internal keys and the long explanations the default report now leaves out - and --finalist-ledger adds the evidence for every space group the search considered, not only the one it adopted.

  • The results report warns when the merged data carry no usable signal and when too little of reciprocal space was measured inside the fitted resolution, and omits FITTED_RESOLUTION where the CC1/2 curve it is fitted on never falls off.

  • Rugnux detects translational pseudo-symmetry and reports it under the PSEUDO_TRANSLATION flag as TNCS_DETECTED= and the TNCS_* keys - a translation the merged data are exactly invariant under is reported as UNDECLARED_LATTICE_TRANSLATION= under LATTICE_TRANSLATION instead - and a detected pseudo-translation can no longer buy a false screw axis in the space-group search or hide a twin from the L-test (L_TEST_VS_TNCS=).

  • The space-group search determines glide planes from zonal systematic absences, so a non-Sohncke space group such as P 2_1/c or Pbca is named where the run previously stopped at its Sohncke subgroup; SOHNCKE_SPACE_GROUP= carries the best Sohncke group beside it on every run that searched, and a centre of symmetry is never claimed.

  • Where the cell metric carries more rotational symmetry than the Bravais class the indexer named, the extra rotations are put to the intensities and the space-group search is asked again on the metric’s own cell - adopted only where the intensities confirm the higher symmetry - so a lattice that is nearly but not exactly hexagonal, or whose reduction landed in a sub-cell, still reaches its true point group.

  • Systematic-absence calls rest on the evidence rather than on counts: a screw axis whose absent class the data show extinct is no longer refused because a handful of reflections in it read as present, and SPACE_GROUP_ALTERNATIVES= no longer drops a candidate that differs only on a zone the sweep never measured.

  • A reference correlation measured on too few reflections is refused instead of scored zero, so a run given a reference MTZ is no longer reindexed on an operator that mapped almost everything outside the reference’s coverage.

  • A frame counts as indexed from 6 spots on its lattice rather than 9, so a weakly diffracting crystal whose frames cannot carry 9 is no longer refused the lattice it fits; --min-indexed-spots overrides it.

  • -C accepts a known cell in any equivalent description - conventional or primitive, centred or not - instead of only the reduced primitive form, so a centred cell given the way it is published no longer makes the run report that it found no lattice.

  • Each reflection is corrected for the sensor’s quantum efficiency at the angle it meets the detector (attenuation lengths from the NIST tables, which also fixes the spot-width parallax term on CdTe) and for the attenuation of the flight path between the sample and its pixel; --flight-path air|helium|vacuum declares the medium - default air, since no file states it - and the report says what was assumed and what it was worth. The unmerged MTZ records the factors in new QE and FLIGHT columns beside LP, so raw counts are I / LP * QE * FLIGHT, and _process.h5 in new optional qe and flight datasets.

  • Rotation geometry post-refinement fits the crystal and the detector at once, against the observed spot positions and the observed rocking angles together, so the refined distance depends far less on how wrong the file’s distance was.

  • A coarsely sliced sweep integrates correctly: partials are joined into one rocking event by angle rather than by frame count, so two crossings of the Ewald sphere are no longer summed into one full, and at 0.5 degrees per image or coarser the per-frame geometry refinement accepts a spot whose miss the exposure’s own rotation accounts for.

  • rugnux --mode scale reports the detector tilt and direct beam of the geometry it re-scaled at, instead of zeros that read as a flat detector, and no longer warns that no image was indexed on a run whose lattice came from its input file.

  • Every rotation run that determined a space group and merged reports what the mounting cost: SPINDLE_LOST_UNIQUE_FRACTION= is the fraction (0-1) of unique reflections the mounting made unmeasurable under the measured point group, also written to the master as /entry/MX/spindleLostUniqueFraction and what the mounting warning fires on; SPINDLE_SYMMETRY_AXIS_ANGLE_DEG= / SPINDLE_SYMMETRY_AXIS_ORDER= describe the mounting in the --developer report.

  • Stills and grid scans carry a per-image spindle_blind_fraction - how much of a rotation sweep’s blind cone this orientation would make unrecoverable, 0.5 and above calling for a second orientation - through the CBOR stream, HDF5 (/entry/MX/spindleBlindFraction), the plot and scan-result APIs, and the viewer and frontend plots; an absent value means the frame could not be assessed and is not a 0.

  • jfjoch_viewer gains Help entries for the mouse shortcuts and the acknowledgements, and Inspector toggles that hide non-indexed spots and spots on ice rings.

  • The results report’s REPORT_VERSION is 7.

1.0.0-rc.166

  • rugnux --model treats the model as a hypothesis: it decides the enantiomorph and the indexing only where its R-work beats that of the same model in random orientations, and a model the data reject is still scored, placed and mapped, but leaves the reflection files byte for byte what a run with no model writes.

  • rugnux --model places the model against the data as a rigid body before scoring it, writes sigma_A-weighted 2mFo-DFc and mFo-DFc maps in place of the unweighted 2Fo-Fc and Fo-Fc, and writes the model as it was placed - <prefix>_model.cif, and <prefix>_model.pdb where the PDB format can express the cell - in the cell and space group of the reflection files beside it.

  • rugnux and jfjoch_viewer read PILATUS miniCBF sweeps natively, and open masters written at other facilities, including Eiger 1.x and third-party NXmx.

  • rugnux determines the lattice and the space group more reliably - the true cell where the first pass offers a whole-number multiple of it, so a pseudo-translated crystal keeps its full-length axis and a small molecule is indexed on its own cell rather than a protein-sized one, and the point group, the setting and the systematic absences - and -S refuses or re-seats a fixed space group whose symmetry axes the indexed cell does not carry.

  • rugnux measures the beam centre on every run and indexes with it when the file’s value indexes nothing, refines only the detector-tilt component the data determine - a beam-centre error is no longer reported as a tilt - and places a detector swung out on a 2theta arm where the file says it stands.

  • rugnux writes the unmerged MTZ by default, with a P1 merge beside it, a batch header for every image the observations span, and events kept to the same --min-captured-fraction as the merge, so a wrong space group can be re-merged in a scaling program without reprocessing.

  • rugnux writes reflection files in the conventions downstream programs read: FreeR_flag is 0 for the test set and 1 for the working set - it was the other way round - the merged and P1 MTZ carry the reserved HKL_base dataset so a CCP4 program reads the wavelength instead of falling back to 1.54187 A, and the merged mmCIF marks the free set as _refln.status = f.

  • The Rugnux results report carries the space groups the data cannot separate and the enantiomorph state, the model’s verdict and what it was allowed to decide, the detector geometry measured and what a single sweep cannot determine, the resolution the CC1/2 fit reached, which reciprocal axis each anisotropic diffraction limit belongs to, and twinning measured before and after the space group was decided; REPORT_VERSION is 6, and SPACE_GROUP_ENANTIOMORPH= DETERMINED_FROM_MODEL is now ASSUMED_FROM_MODEL.

  • rugnux --mode calibration writes <prefix>.json beside the .poni, holding the geometry as a jfjoch_broker dataset_settings body, and refuses a fit that is not a measurement - no .poni, a non-zero exit, converged recorded in the .json; --no-refine-tilt holds the detector tilt at the file’s value instead of zeroing it.

  • A snake grid scan with a negative slow step and an even number of rows no longer has its positions mirrored along the fast axis in the HDF5 master and the grid map, so the positions recorded for that configuration change; jfjoch_viewer draws grid scan cells in the proportion of the scan steps, labels the merge-statistics plot over the range the axis is drawn on, and builds its powder-calibration ring list from the loaded dataset’s space group as well as its cell, so a centred sample cell no longer scales the whole fit.

  • The HDF5 master records direct_beam_x/direct_beam_y - where the undeflected beam lands, sent on the CBOR start message too - the beam size at the sample as incident_beam_size from the new dataset_settings beam_size_x_um/beam_size_y_um, and /entry/MX/peakCountUnfiltered; dataset_settings accepts any smargon.chi_deg, which was restricted to 0-90 degrees.

  • Reported completeness counts the reflections the beam stop, a detector mask or the low-resolution limit kept out of the merge as missing: the denominator, and the resolution shells it is binned into, now span the run’s declared resolution range rather than the range of the reflections that survived, so the innermost shell boundary moves and its numbers are not comparable with those of an earlier release.

  • The Rugnux results report carries CC_ANOM beside SIGANO, overall and per shell: the anomalous difference measured from one half of the observations correlated against the same difference from the other half, which says whether there is an anomalous signal to phase on without depending on the error model. Reported on Friedel-merged runs too; it matches AIMLESS and phenix, and XDS’s similarly named Anomal Corr is a different quantity.

  • A quantity a Rugnux run did not measure is left out of the results report altogether instead of being written as nan - SIGANO= on a Friedel-merged run, which is the default, is the case a script meets first - and a merging-statistics shell prints - in its place.

  • FITTED_RESOLUTION= in the results report is the resolution fit of the run’s own merge rather than of the P1 cross-check, and the unmerged MTZ is written in the space-group setting the run adopted rather than in that setting’s reference one.

  • rugnux --mode calibration refuses to write a .poni for a detector whose stored image is mirrored or turned by a multiple of 90 degrees, the format having no field for it.

  • CC1/2 is computed on half-sets of equal size, so every reflection measured more than once contributes to it, as in XDS and phenix.merging_statistics, and a CPU-only build now reports the same value as a CUDA one; reported CC1/2 values move slightly, most where multiplicity is low.

  • The Rugnux manual is reorganised into task pages with a run overview and worked phenix / REFMAC5 / Phaser / SHELXC/D/E / POINTLESS-AIMLESS / careless examples, and the HDF5 and API documentation say how a grid scan records the angle its spindle stood at: the goniometer axis with a step of 0.

1.0.0-rc.165

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • rugnux --model adopts the model’s space group as a label where the data were merged in its enantiomorph, instead of reindexing the reflections - which swapped I(+) with I(-).

  • rugnux --model warns, naming the atom, when the anomalous density at the model’s atoms comes out inverted, which means the data and the model are in opposite hands.

  • rugnux --model writes an anomalous difference map (<prefix>_anom.ccp4) when the merge kept the Bijvoet split, and names the ten model atoms it peaks highest on as ANOMALOUS_SITE_01.._10.

  • MEAN_ATOM_DENSITY_SIGMA is read from the map by cubic rather than linear interpolation and comes out around a tenth higher; it is no longer comparable with the figure earlier versions printed.

  • rugnux --model reads an mmCIF coordinate file as well as a PDB one, gzipped or not, taking the format from the file’s content rather than its name.

  • A model rugnux --model cannot use is reported as a WARNING: line in the results report instead of only in the log.

  • The Rugnux results report has a 10. MODEL VALIDATION section when --model was given; REPORT_VERSION is 4, WARNINGS moves to section 11 and no existing key changed.

  • The Rugnux results report records how the run was invoked, what it cost and what it ran on: COMMAND_LINE=, WALL_TIME= and GPU_COUNT= / GPU=.

  • Rugnux says which GPUs it can see before it starts processing.

  • rugnux --export-unmerged also writes <prefix>_unmerged.mtz on a --no-merge run, and is ignored on a run with no output prefix instead of writing a file called _unmerged.mtz.

  • /start asks the writer whether the run can be written before the detector is armed, so a run whose master file already exists, or whose output directory cannot be created, is refused up front with the writer’s own message. This needs the TCP image stream or the built-in HDF5 writer; the ZeroMQ stream is unchanged.

  • A calibration that fails goes to Error carrying the reason instead of Inactive, so /wait_till_done and /wait_until_running report it; a cancelled calibration still goes to Inactive.

  • /wait_till_done answers 500 with the message when a collection ended in an error. A cancelled collection and a collection that only triggered a warning still answer 200.

  • A pending start failure is discarded by /cancel and /deactivate, as it already was by /start and /initialize.

  • /scan_result no longer reports the previous run’s images after a collection that failed to start, or after /deactivate.

  • The TCP image stream protocol version is 4. jfjoch_writer and jfjoch_broker have to be of the same release, as before.

1.0.0-rc.164

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • Rugnux now tells you whether a crystal diffracts anisotropically and how far it reaches in each direction, without a second program: a new 9. DIFFRACTION ANISOTROPY section in <prefix>_report.txt and matching _reflns.pdbx_aniso_B_tensor_* / _reflns.jfjoch_aniso_* items in the merged mmCIF report the anisotropic deltaB, the diffraction limit along each principal direction, and a NOT DETECTED / DETECTED / CANNOT DETERMINE verdict measured against the data set’s own systematic error. It is a description only - no intensity is corrected, no reflection is removed, and the merged data do not depend on direction.

  • Rugnux can hand its integrated observations to another scaling program: --export-unmerged writes <prefix>_unmerged.mtz, an unmerged MTZ readable by aimless, pointless, careless and iotbx.merging_statistics, in --mode mx and --mode scale alike. Each rotation reflection’s partials are summed into one full; --export-unmerged-partials writes one row per image instead. Intensities carry the Lorentz-polarization factor and nothing else, since those programs scale the data themselves. Lattice-centring absences are not written; screw and glide absences are.

  • Rugnux integrates crystals with broad spots better - where it changes anything, per-shell mean I/sigma improves by up to 31% and R_meas by up to 24% - because on rotation data the integration signal radius is now taken from the crystal’s own measured spot width instead of a fixed 4 px. --adaptive-integration-radius=off restores the fixed radius and an explicit --integration-radius still overrides both. The widened radius applies to the final integration pass only, and a pattern too dense for it is re-integrated at 4 px with a note in the log.

  • Rugnux discards fewer stills reflections for want of a background ring, improving per-shell R_meas over most of the signal-bearing range: the stills background ring now runs to 14 px instead of 12. The gain reverses in shells below a mean I/sigma of about 4.

  • Rugnux determines the space group with thresholds that mean the same thing on a weak crystal as on a strong one: symmetry operators are scored on resolution-normalised intensities (E squared) instead of raw merged intensities, and a reflection counts as genuinely present on its counting significance instead of on the merged I/sigma, which saturates at the merge’s own ISa. The search resolution cut is no longer able to move the answer, and the twin-law H bound moves from 1.70 to 1.85, which stops one class of correct high-symmetry assignment being refused as twinning.

  • Rugnux says what the space-group search tested and what it could not: the twin-law disagreement H is printed for every operator together with the adopted point group’s H ratio and its bound; alternatives that are not on the reported lattice are named with how their cell differs; and a lattice centring the data could not test - the crystal having been integrated on the primitive sub-cell, so the reflections it extinguishes were never measured - is marked UNTESTED and warned about where it is adopted, as coming from the lattice metric rather than from the intensities.

  • Rugnux --mode scale re-merges a _process.h5 in the right symmetry without being told it: the file now records the space group on every run - a two-pass rotation run wrote none before, so re-merging defaulted to P1 - together with the change of basis under /entry/MX/reindexMatrix where the lattice was re-seated, and --mode scale also reports the Wilson B-factor estimate instead of WILSON_B= nan. A file written before this stops with a message naming the two cells and the override to use, instead of failing inside the merge. A third-party reader of a _process.h5 must apply reindexMatrix where it is present.

  • Rugnux installs on its own, as a package called rugnux - dnf install rugnux or apt install rugnux - instead of arriving inside jfjoch-viewer. It pulls in none of the acquisition stack, so a machine that only processes data no longer has to carry the broker, the detector libraries or Qt to get it. Installing it over a jfjoch-viewer from rc.163 or earlier, which still owns /usr/bin/rugnux, upgrades cleanly rather than failing on the duplicate file.

  • Rugnux is also a standalone download, built for arm64 as well as x86_64: rugnux-<version>-linux-{x86_64|aarch64}-cuda<major>.tgz and rugnux-<version>-win64-cuda<major>.zip on the release page, for machines that are not managed by a package manager. The aarch64 build targets GH200 and DGX Spark, and is untested on hardware.

  • Every portable Linux binary is now a single self-contained file: cuFFT is linked statically instead of being shipped beside the executable and found through an rpath, so rugnux and jfjoch_viewer need nothing but an NVIDIA driver, and only to use the GPU. The .rpm/.deb continue to take cuFFT from the distribution. The developer utilities jfjoch_extract_hkl and jfjoch_recompress are no longer packaged anywhere.

  • Jungfraujoch needs six fewer shared libraries on the machine - libopenblas and libmetis, and libgfortran, libquadmath, libgomp and libz behind them - because the Ceres LAPACK, METIS and SuiteSparse back-ends are no longer built. Nothing in the code ever selected them, and results are unchanged.

  • The PCIe driver DKMS package builds for the kernel it is being installed for instead of the running one, so a module built while a kernel update is being applied loads after the reboot.

  • The PCIe driver builds on RHEL 9.5 and later, and on their CentOS Stream, Rocky and AlmaLinux equivalents, where the vm_flags kernel interface was backported into the 5.14 kernel.

  • A data collection started with async_start that fails to start - a writer refusing to overwrite an existing file, for instance - is reported as an error by /wait_until_running and /wait_till_done instead of as a timeout and a successful collection respectively. The error message is the one the writer gave.

  • A calibration that is cancelled or that fails to collect its pedestals is no longer reported as a successful one. The broker goes to Inactive with an error message and has to be initialized again, instead of sitting in Idle looking ready to measure while holding partial pedestals - data collected in that state was silently mis-converted.

  • A failed /initialize is reported to /wait_until_running and /wait_till_done as soon as it happens, instead of when their timeout expires.

  • space_group_number accepts space groups up to 230 in the API schema, so cubic space groups can be recorded. The broker always accepted them; the generated clients rejected them before the request was sent.

  • The results report’s REPORT_VERSION is 3, two sections having been added. Existing key names and table columns are unchanged.

  • The merged statistics table has 9 resolution shells instead of 10, which is what XDS reports. The bins were already XDS’s - equal steps in 1/d^2 between the lowest- and the highest-resolution reflection the merge kept - so at the same resolution limits the two tables now have the same shell boundaries and can be read row for row. --resolution-shells sets a different count.

  • rugnux --model now settles the frame the merged reflections are written in, not only the frame the R-factors and the maps are computed in: the .mtz/.cif/.hkl come out in the model’s indexing, and where the data were merged in the model’s enantiomorph they take the model’s hand and space group - which on anomalous data puts I(+) and I(-) the right way round. The indexing choice is logged with the winning R-free and the runner-up, so a decision made within noise is visible.

  • rugnux --model can resolve the indexing ambiguity of a serial stills run, which a model could not do before: structure factors computed from the model become the per-image reference, the same role a reference MTZ plays. It needs the cell and space group up front (-C / -S). Without one or the other, a merohedral serial run still merges both hands together and says so.

  • The Rugnux documentation opens with a quick start - the default run, and runs with a reference MTZ, with a model, or with the space group and cell pinned - and explains the indexing ambiguity: what it costs on rotation and on serial data, and which of -z / --model resolves it in each case. The long reference pages now carry a table of contents.

1.0.0-rc.163

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • Packaging: each package installs its license notices under a directory of its own - share/doc/jfjoch_broker, share/doc/jfjoch_writer, share/doc/jfjoch_viewer, share/doc/jfjoch_driver_dkms - instead of all of them into the shared share/doc/jfjoch, so jfjoch and jfjoch-writer can be upgraded one at a time instead of only together.

1.0.0-rc.162

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

Files written by Jungfraujoch now import correctly in DIALS, XDS and pyFAI. A tilted detector, a grid scan, a still recorded at a goniometer position, and saturated or unreadable pixels were each described in a way that a third-party program acted on wrongly. If you process Jungfraujoch data outside Jungfraujoch, prefer this release to any earlier one.

  • HDF5: the detector tilt (rot1/rot2/rot3) is exported correctly in the NXmx transformation chain; untilted geometries are unaffected.

  • HDF5: a still recorded at a goniometer position is no longer read back as a single image, and a grid scan records a stationary spindle so a program that requires a rotation axis can open it.

  • HDF5: the sample transformation chain is written in mounting order, with a Smargon head position told apart from the spindle, one entry per image, module_offset as a float unit vector, and offset_units on every offset.

  • HDF5: saturated, underloaded and unreadable pixels are described so a downstream program masks them - saturation_value, underload_value, error_value and bit_depth_readout are written correctly, and a data file missing next to a VDS master reads as the error marker rather than as zero counts.

  • HDF5: the rotation axis is read back under whatever name it carries, and mirror_y records whether the assembled image is mirrored in Y relative to the detector’s raw readout.

  • A grid scan and a goniometer axis can both be set; they are no longer alternatives.

  • images_per_file is chosen from the acquisition when it is not given: a rotation sweep of at most 20000 images goes into a single data file, a grid scan splits on whole fast-axis rows, and stills and serial keep 1000.

  • The writer refuses a stream whose start message declares a different pixel format than its images carry, and a DECTRIS detector sending signed images is no longer declared unsigned.

  • The image stream can carry the sample transformation chain (transformations, in the END message); a producer that does not send it gets the same chain built by the writer.

  • Rugnux: fixing the space group with -S no longer prevents the lattice from being found - a lattice indexed in a different setting is reindexed into that group’s own setting, and a run whose crystal does not have that group’s lattice stops and names the cell it indexed as, rather than reporting statistics that cannot describe it.

  • Rugnux: the per-image resolution estimate now predicts the resolution the merged data reach rather than the highest-resolution spot found, and is reported as SPOT_RESOLUTION_ESTIMATE.

  • Rugnux: two runs of the same command on the same images produce the same merged intensities; the azimuthal profile written alongside them is not yet reproducible in the same way.

  • Rugnux: the offline lattice refinement is bounded by iterations rather than by a wall clock, so a loaded machine can no longer refine to a different lattice; a live acquisition keeps its real-time bound.

  • Rugnux: the detector-frame modulation correction is fitted on a grid spanning the detector, so whether it is applied no longer depends on how far integration reached.

  • Rugnux: the geometry pre-pass no longer writes <prefix>_01.mtz, _01.cif, _01.hkl and _01_image.dat; the refined second pass writes those files under <prefix>, and that is the result to use.

  • Rugnux: _process.h5 describes the pixel format of the images it links to, and is written on a thread of its own.

  • Rugnux: the detector geometry is also logged in XDS’s convention (ORGX/ORGY, detector axis vectors, rotation axis), so it can be compared with an XDS refinement.

  • Rugnux: an image integrated in pyFAI through the .poni file written by --mode calibration comes out with the correct azimuth, and the file declares pyFAI’s orientation, which needs pyFAI 2024.01 or newer. Radial integration is unchanged.

  • Rugnux: a rotation run is substantially faster throughout - beam-stop detection, first-pass indexing, geometry refinement, integration, scaling and merging - and observations outside the scaling resolution range are dropped as they are ingested. The refined geometry, the space group chosen and the merged statistics are unchanged.

  • Faster spot finding and indexing, on the broker as well as in Rugnux; the spots found and the lattices indexed are unchanged.

  • A run reserves substantially less GPU memory: nothing is allocated for buffers that are never read, and a worker builds only the engines it uses.

  • Rugnux: with -N left at its default the per-image loop of --mode mx uses at most 16 workers per GPU, rather than one per hardware thread; an explicit -N is obeyed as given.

  • CUDA 12 builds now contain device code for Volta, so the RHEL 8 packages and the portable Linux .tgz run on a V100; the CUDA 13 artefacts (RHEL 9, Ubuntu, Windows) remain Turing and newer.

  • The build resolves a single Eigen for the whole project, and refuses to configure if Ceres picks up a different one; a build that mixed two Eigen versions was undefined behaviour and crashed at -O2.

  • Documentation: a security page, and the supported GPU generations and minimum NVIDIA driver version of every released artefact.

Breaking change to OpenAPI - regenerate the client (jfjoch-client 1.0.0-rc.162, frontend/src/client):

  • dataset_settings.images_per_file is no longer default: 1000 and no longer accepts 0; it is optional, and its minimum is 1. A client sending 0 (previously “one file for the whole run”) is now rejected - omit the field instead, which for a rotation sweep gives the same single file.

  • file_writer_format now defaults to NXmxVDS, matching the server’s own default and the layout recommended for DIALS, XDS and CrystFEL. A generated client that fills in schema defaults and does not set the format explicitly will write VDS masters where it previously wrote legacy ones; set NXmxLegacy explicitly to keep them.

1.0.0-rc.161

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • Rugnux: significantly better quality of results, and faster. A large rework of integration, scaling, merging, geometry refinement and space-group determination, together with measurements the program previously made no attempt at - the direct beam before indexing, the beam stop, the goniometer rotation scale, and the stretches of a sweep the crystal did not deliver. A rotation dataset typically gains observations at better <I/sigma> and R_meas, and every mx and scale run writes a <prefix>_report.txt results report modelled on XDS’s CORRECT.LP. Many defaults moved with it: spot detection is self-calibrating, beam-stop detection and rotation geometry post-refinement are on, resolution limits default to as far as the detector reaches, and ice-ring handling engages only where the crystal is measured to have ice.

  • jfjoch_viewer: the beam-stop shadow, the detector calibration and the beam-centre measurement are reachable from “Analyze dataset”; the settings panel reports how the sample moved and how polarized the beam was; image rendering and interaction are faster.

  • Performance: bitshuffle+LZ4 images are decoded on the GPU rather than on the host, with the bitshuffle inverse fused into preprocessing so the decompressed frame is never held in device memory.

  • Broker, writer, packaging and build: image-slot lifetime and locking fixes, per-image datasets sized by the images actually written, the Debian/Ubuntu broker package renamed to jfjoch, and image_analysis compiling under MSVC again.

Breaking change to the Rugnux command line:

  • --azint-only and --scale are removed, replaced by --mode azint and --mode scale; the full pipeline is --mode mx and remains the default. A script passing the old flags now fails with the list of valid modes rather than silently running the wrong one.

  • -t/--stride is refused on rotation data: skipping frames cuts every reflection’s rocking curve, so the combined fulls and their partiality would be measured over frames the sweep never recorded. Select a contiguous range with -s/-e instead. --mode azint and --force-still still take a stride.

Breaking changes to OpenAPI - regenerate the client (jfjoch-client 1.0.0-rc.161, frontend/src/client) or read the affected fields as optional:

  • image_scale_b is removed from the plot_type enum, so a client requesting that plot now gets an error rather than a curve.

  • azim_int_settings.high_q_recipA, spot_finding_settings.high_resolution_limit and spot_finding_settings.low_resolution_limit are no longer required. All three mean “no limit at that end” when unset and are omitted from the response instead of carrying a placeholder value, which raises in a client generated from an rc.160-or-earlier spec. A value of 0 is still accepted and means the same thing.

Breaking changes to the stored formats - a consumer reading these fields must treat them as optional:

  • The per-image image-scale B factor is no longer computed, so /entry/MX/imageScaleBFactor is absent from newly written HDF5 files and the corresponding key is absent from the CBOR DataMessage and END blocks. Files written by rc.160 and earlier still contain it and still open; nothing in the pipeline reads it any more.

  • _reflns.jfjoch_diffrn_ISa now carries the whole-range 1/sqrt(a*b) that XDS’s ISa denotes, and the error-model a and b are reported in XDS’s convention; the strong-reflection asymptote moves to _reflns.jfjoch_diffrn_ISa_asymptotic. A file written by an earlier version carries the asymptote under the plain ISa name.

1.0.0-rc.160

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • Rugnux: Rotation geometry post-refinement is now on by default (--rotation-no-postrefine to disable; also a viewer checkbox). A first pass integrates at the header geometry, then the shared detector distance + beam centre and the crystal cell/goniometer-axis are post-refined over all frames (cross-validated, committed only for a small < 1 % move, with the gauge-weak beam centre restrained toward the header); a second pass re-indexes de novo and re-integrates at the refined geometry. The refined pass is the canonical <prefix>_* output; the header-geometry pass is kept as <prefix>_01_*.

  • Rugnux: Optional per-batch relative-B correction for rotation (--relative-b[=deg], default 10°-of-rotation batches when bare, off otherwise) - a cross-validated, curvature-smoothed resolution×dose correction beyond the single global decay slope.

  • Rugnux: Always-on radiation-damage report for rotation - the per-image scale correlation-to-merge and mosaicity versus dose, plus the relative B-factor change over the run (first→last) as a scalar and a per-batch relative-B curve, printed to the log and written to the merged mmCIF. Report-only; it never alters the merge.

  • Rugnux: De-novo space-group search ranks candidate lattice centerings by net absences (systematically-absent minus violating), not the gross absent count, fixing an over-centering of a genuinely C-centred lattice to F.

  • Rugnux: Record the producing software (name and version) and the refined detector distance and beam centre in the merged mmCIF (and the software in the MTZ history).

  • Bragg integration: Carry the box-sum observed centroid through the profile-fit path, so the observed spot centroid is emitted in every integrator mode.

  • Rugnux: Report ISa as the counting-subtracted strong-reflection asymptote, not 1/b of the whole-range fit; it also sets the merged-sigma floor. CC1/2, R-meas and per-obs sigmas unchanged.

  • Frontend: Azimuthal-integration Q fields (Q spacing / Low Q / High Q) accept 5 decimals (was 3), matching the 1e-5 q_spacing minimum; number-field precision is now configurable.

  • Rugnux: Add a dataset-wide Wilson B-factor estimate to the merged output (mmCIF, stats table, log); the per-image viewer Wilson B emits NaN for implausible fits.

  • Rugnux: De-novo space-group search vetoes a merohedral-twin over-promotion whose systematic error-model b balloons past a calibrated bound (keeps R3 as R3, not R32).

  • Rugnux: De-novo space-group search decides lattice centering from the strength (mean I/sigma) of the systematically-absent class, not a per-reflection violation count.

  • Rugnux: Recover lattice centering on weak / low-energy data via a floor-independent test (rate of significant absent vs present reflections), fixing a missed I-centring at 5/13 keV.

  • Rugnux: Report anomalous signal-to-noise SigAno = <|I(+)-I(-)|>/ per shell and overall (mmCIF PDBx items + stats-table column); anomalous merges only.

  • Rugnux: De-novo space-group search recovers a genuine high-symmetry group on weak data with a broken sigma model by confirming on the systematic-b test alone (restores an F432 case).

  • Rugnux: Print the adopted space group and unit cell as a one-line summary at the end of the run (de-novo or user-fixed -S).

  • Rugnux: Score the radiation-damage decay cross-validation on a sigma-independent (R-meas-like) metric, so a spurious slope can’t pass by reshaping sigmas.

  • Rugnux: Fix de-novo rotation indexing committing a spurious axis-multiple supercell (collapsing to P1) via a cross-scheme smaller-cell tie-break on near-integer volume ratios.

  • Rugnux: Widen refined-cell angle bounds to [30, 150] deg (rotation candidate and per-frame stills refinement); check refined angles against the reference cell.

  • Rugnux: -S/--space-group now accepts a Hermann-Mauguin symbol (e.g. P43212) as well as a space-group number.

  • Rugnux: Warn when the chosen cell/space group carries an indexing (merohedral) ambiguity needing a reference to resolve.

  • Indexing: Requesting the FFTW (CPU) indexer on a GPU node now fails with a clear, actionable message (rotation always uses the GPU FFT indexer there).

  • Rugnux: Stills --refine-geometry[=N|off] - first-pass bundle-adjust of beam/distance/cell then re-index (default ON with a reference cell); accepts reference F/FP columns.

  • Rugnux: Per-image geometry refinement -r flex tries all three algorithms per image and keeps the best (old name multi kept as an alias).

  • Rugnux: Experimental stills partiality --still-partiality (Gaussian excitation-error) and --partiality-uncertainty <num> down-weighting the least-complete partials.

  • Rugnux: Default the stills Bragg-integration box to r=6 (integration radii 6, 8, 12).

  • Rugnux: Self-referenced stills scale in a single pass (fixing a weak-data collapse); a reference MTZ (-z) fixes SG/cell/ambiguity but never anchors the scale (stills and rotation).

  • Rugnux: Cap normalised intensity (E^2) on second-lattice overlaps in the de-novo space-group search, so strong overlaps don’t skew the symmetry decision.

  • Rugnux: Fix --scale on a self-contained _process.h5 (stored reflections and error model reload correctly).

  • Rugnux: Add --spot-low-resolution <num> (default 50 A) and --min-pix-per-spot <num> (default 2) to tune spot finding on weak serial data.

  • jfjoch_viewer: Expose stills processing settings in the settings dock, rename geometry-refinement multi to flex, and refit the initial image on resize.

  • jfjoch_writer: Remove the CBF and TIFF image writers - only NXmx HDF5 is written (all three layouts remain).

  • Reader: Treat a negative total_flux in a stored dataset as unknown/absent rather than a valid flux.

  • Packaging: Build the self-contained Linux viewer against a static libdbus with glib disabled; add parallel image-build and in-container viewer-verification scripts.

  • Rugnux: Write anomalous data as a standard CCP4 anomalous MTZ (one row per reflection: IMEAN, I(+)/I(-), F/F(+)/F(-)), readable by aimless/mtz2sca/ANODE.

  • Rugnux: Always write merged reflections as both <prefix>.mtz and <prefix>.cif; the --scaling-output selector and text .hkl output are removed.

  • Rugnux: Add a detector-plane modulation (flat-field) correction surface to rotation scaling (cross-validated, on by default; --no-scaling-corrections disables all), dropping R-meas.

  • Rugnux: Add optional stills detector-plane modulation (--stills-modulation, default off) - the same cross-validated surface for the on-the-fly stills path.

  • Bragg integration: Local background is now a symmetric trimmed mean of the ring (--background-trim <f>, default 0.10; monochromatic), improving <I/sigma> and resolution-edge CC1/2.

1.0.0-rc.159

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • Rugnux: Add --model model.pdb - score the merged data against an atomic model and compute initial maps. It reports R-work/R-free (scaling the model to the observed amplitudes with an overall scale, an anisotropic B and a flat bulk solvent - the standard few-parameter model, so a batch of maps stays directly comparable) and writes 2Fo-Fc / Fo-Fc electron-density maps (CCP4) plus a map-coefficient MTZ. The structure itself is not refined; the model is only re-fractionalised into the data cell.

  • Rugnux: The merged reflection output now carries French-Wilson amplitudes (|F| and its sigma) next to the intensities - MTZ F/SIGF, mmCIF _refln.F_meas_au, and the text HKL - computed with the correct centric/acentric Wilson prior and epsilon multiplicity, so a downstream program (e.g. phenix.refine) can refine against amplitudes. The intensity columns are unchanged.

  • Rugnux: R-free test-set flags are now assigned deterministically and consistently across symmetry - a Bijvoet pair I(+)/I(-) is never split between the work and free sets, and the assignment is a reproducible per-hkl hash that depends only on the reflection index, so every dataset of one crystal form gets the same ~5% free set (what a multi-dataset campaign such as PanDDA needs). On small data the fraction is floored so the test set stays large enough for a stable R-free (~500 reflections, capped at 10%); it stays flat at 5% on ordinary data. When a reference MTZ carries a FreeR_flag column its test set is imported instead, letting a whole campaign inherit one shared free set.

  • Rugnux: A reference MTZ (--reference-mtz) can now fix the space group and cell for rotation data too (previously rejected), without being used to scale - the rotation merge stays self-consistent. When the crystal has an indexing (merohedral) ambiguity - a lattice symmetry higher than its Laue symmetry, e.g. P3/P4/P6/C2 - the reference also resolves it: each candidate reindexing (identity plus the twin-law cosets of the metric symmetry) is scored by its intensity correlation against the reference and the data are re-merged in the best-correlating one. This is a metric-preserving relabelling of hkl (the cell is unchanged) and a no-op for a holohedral crystal (which has no twin laws).

  • Rugnux: --model validation now aligns the data to the model before scoring - the observed reflections are reindexed into the model’s enantiomorph when the two differ only by hand (indistinguishable from merged intensities). A merohedral indexing ambiguity is resolved against the reference MTZ when one is given (so a whole campaign shares one indexing convention); only with a model and no reference does validation fall back to fitting each candidate reindexing and keeping the lowest R-free.

  • Rugnux: De-novo symmetry - recover a genuine high-symmetry group whose data are imperfectly scaled. Such a merge’s within-orbit chi² lands just past the self-consistency bound (each real symmetry step adds a little systematic scatter), right where a merohedral twin also lands, so the chi² ratio alone cannot separate them. The candidate is now rescued when the extra intensity-proportional systematic error it invokes stays small relative to the confirmed subgroup - a genuine symmetry step gains multiplicity without inflating the merge error model’s b, whereas a twin forces non-equivalent reflections together and b balloons. Fixes a cubic case (I23 instead of I222) with no change to any other crystal in the test battery, including the twins that must stay in their lower symmetry.

  • Docs: Document the French-Wilson amplitude estimation, R-free flagging, reference-based space-group/ambiguity resolution, and model-based validation/maps in CPU_DATA_ANALYSIS.md.

  • Frontend: The status-bar pill now shows a progress bar during detector calibration (previously only during measurement), and the calibration state and its button are labelled “Calibration”/“CALIBRATE” (the internal Pedestal state name is unchanged for back-compatibility).

1.0.0-rc.158

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • Analysis: The azimuthal-integration solid-angle correction now follows the incidence angle to the detector normal (cos^3 of that angle) instead of cos^3(2*theta), so it is correct for a tilted detector and matches PyFAI solidAngleArray and MAX IV azint (unchanged for an untilted detector). Crystal geometry refinement (XtalOptimizer) no longer silently ignores an imported PONI rot3 (rotation about the beam): it is applied as a fixed rotation in the residual so refinement stays consistent with the rest of the pipeline. Polarization and azimuthal binning already honoured rot3 through the full PONI rotation.

  • jfjoch_viewer: Open datasets on the WSL2/UNC filesystem (paths starting \\); write processing outputs next to the input file, with a Browse button and independent _process.h5 / merged .mtz/.cif toggles; and show the determined space group in the merge-statistics window.

  • jfjoch_viewer: Connect to a broker over https (an http/https selector in the connect dialog), and keep the HTTP connection alive across reads for faster live-follow.

  • jfjoch_viewer: Time out stalled HTTP requests (5 s) so an unreachable broker cannot hang the reader thread, and drop the cached pixel mask when switching data source.

  • Rugnux: Accept an absolute -o output prefix in offline processing.

  • Rugnux: Faster two-pass rotation indexing - the first pass now runs its FFT indexing and geometry refinement in parallel (results unchanged).

  • Rugnux: Rotation indexing now works on standard DECTRIS datasets that store no spots - the first pass finds spots itself instead of failing.

  • Rugnux: De-novo symmetry robustness - don’t over-promote a merohedral twin to the holohedral group (keep e.g. R3, not R32), make the intensity second-moment twinning statistic robust on weak/mis-integrated data, and don’t flag twinning in holohedral Laue classes where no twin law can exist.

  • jfjoch_writer: Fold the refined beam centre into the NXmx detector translation vector too (not only the informational beam_center fields), so a reprocessed _process.h5 has a self-consistent refined geometry.

  • Robustness: Harden size handling of untrusted input in TIFF reading and raw-TCP frames.

  • Packaging: The self-contained Linux viewer .tgz now bundles cuFFT, so it runs without a system CUDA toolkit (.deb/.rpm are unchanged, distro-managed).

  • Docs: Documentation updated to match the current analysis code and CLI.

1.0.0-rc.157

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • Rugnux: Rebrand the offline data-processing subsystem as rugnux and consolidate all offline analysis into the single rugnux binary - jfjoch_process is now rugnux, the former jfjoch_azint is now rugnux --azint-only, and jfjoch_scale is now rugnux --scale (see the new docs/NAMING.md and docs/RUGNUX.md). Scaling and merging are on by default for rotation and stills (--no-merge disables them), replacing the previous opt-in -M, --scale-merge.

  • Rugnux: CLI fixes - default -N to all hardware threads, parse numeric option arguments strictly (reject non-numeric or trailing input instead of silently yielding 0), require --wavelength > 0, and correct the reproduced command line and --scale reference-cell handling.

  • Rugnux: De-novo space-group improvements - recover genuine high symmetry and centred Bravais lattices from intensities, add an automatic CC1/2 high-resolution cutoff, and report L-test twinning statistics.

  • Rugnux: Index weakly-diffracting low-resolution rotation data that previously failed (e.g. F-cubic crystals that diffract only to ~4 A on a detector reaching ~1.5 A). The per-frame indexing gate now measures the indexed fraction only within the resolution range the lattice actually diffracts to, so the many sub-diffraction ice/noise spots no longer make the fraction floor unreachable; the two-pass first pass tries several image-sampling schemes (spread across the whole rotation vs a consecutive wedge whose native stride keeps a reflection’s rocking curve continuous, letting the FFT resolve a long axis) and keeps the one that indexes the most frames; and the de-novo space-group search no longer discards all reflections (and crashes) when every resolution shell falls below <I/sigma> = 1.

  • Rugnux: Lower the low-resolution R-meas for strongly-diffracting rotation data - drop edge-of-sweep truncated fulls whose rocking curve was captured below --min-captured-fraction (default 0.7 for rotation), and report R-meas only over the observations kept by outlier rejection (matching XDS). The 0.7 default also strips the partiality-extrapolated fulls that dominate the intensity second moment on weakly-diffracting crystals, so the de-novo space-group search is no longer starved by the error-model I/sigma floor and recovers the correct symmetry (e.g. for F-centred cubic lattices that would otherwise be under-assigned).

  • Rugnux: Write the refined geometry (beam, tilt, axis) to _process.h5 and place non-standard mmCIF items under a reserved jfjoch prefix.

  • jfjoch_broker: Ordinary acquisition failures (receiver/writer/analysis problems, missed packets, writer disconnect) now return to the Idle state with an Error-severity message, so a run can be retried without an expensive re-initialisation; only failures that leave the detector in an undefined state (new JFJochCriticalException, e.g. PCIe/FPGA faults) go to the Error state and force re-initialisation.

  • jfjoch_broker: A synchronous /start now reports its failure to the HTTP caller instead of returning HTTP 200, and an incomplete or truncated dataset (missing packets, writer disconnect) is reported as an error rather than a “reduce frame rate” warning.

  • jfjoch_broker: Drop uncollected placeholder rows (number = -1) from the scan_result REST endpoint.

  • jfjoch_broker: Fix the inverted per-image compression ratio reported by the Lite receiver (was compressed/uncompressed instead of uncompressed/compressed).

  • jfjoch_broker: Bragg integration adds a quantization-noise variance floor with a box-sum fallback, and treats the type-maximum marker as an invalid pixel for unsigned image types.

  • jfjoch_writer: Detect file-overwrite conflicts at start for back-channel transports, and reset the writer when end-of-collection finalisation fails.

  • jfjoch_viewer: Preview overlays follow the geometry (resolution/ROI arcs, true beam centre, predictions, coral secondary-lattice spots, legend), add save-as-JPEG, and fix an HTTP live-follow memory leak.

  • Frontend: Improved aesthetics and usability, and added in-browser pixel-mask and JUNGFRAU-pedestal visualisation.

  • CI: Name the Windows installer jfjoch-viewer-* instead of jfjoch-*.

1.0.0-rc.156

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • jfjoch_process: Major rotation (rot3d) data processing overhaul - robust profile-fit integration, Cauchy-loss scaling with optional absorption surface, de-novo indexing and space-group/centering determination fixes, and merging statistics + ISa in the mmCIF output.

  • jfjoch_process: Bragg integration now runs on the GPU in the offline/non-FPGA workflow (one box-sum + profile-fit engine, GPU when available, CPU otherwise); the FPGA workflow integrates on the CPU directly from the assembled image. The previous standalone integrators are removed.

  • jfjoch_process: Deterministic Bragg prediction - when more reflections are predicted than fit the output, they are ranked by distance to the Ewald sphere before truncation, so repeated runs produce identical reflections.

  • jfjoch_process: Judge systematic absences by resolution-normalised intensity instead of I/sigma alone, so screw axes are no longer missed when the error model under-estimates sigma on weak axial reflections (e.g. the monoclinic 2_1 screw).

  • jfjoch_process: GPU-accelerated rotation scaling and merging (RotationScaleMerge), substantially faster than the previous CPU path.

  • jfjoch_process: Unify still and rotation processing on a single –force-still flag (replaces the -P partiality-model option); rotation is auto-detected from the goniometer and processed as rot3d two-pass by default, the default reflection output is mmCIF, and the experimental –reciprocal-profile option is removed.

  • jfjoch_process: Add EXPERIMENTAL ice-ring detection (–detect-ice-rings) that excludes ice reflections from scaling.

  • jfjoch_broker: The Bragg integration model (profile-fit Gaussian, empirical, or box-sum) is now selectable via the REST API (/config/bragg_integration) and the web frontend.

  • jfjoch_broker: Write smargon chi/phi goniometer positions to NXmx; read sensor thickness/material from HDF5 metadata.

  • jfjoch_writer: Don’t write empty grid-scan position arrays when the dataset has no images.

  • Compression: Add BSHUF_ZSTD_RLE_HUFF, make compression size-aware (drop frames that don’t fit rather than aborting), and add the jfjoch_recompress tool.

  • jfjoch_viewer: Report “Multiple lattices detected” and grey out “Analyze dataset” on a live connection.

  • jfjoch_viewer: Frontend fixes - detector settings widget, panel/preview overflow, and navigation icons.

  • CI: Build Windows (CUDA and non-CUDA) installers.

  • CI: Ship jfjoch_viewer to the release as a Linux-agnostic .tgz.

1.0.0-rc.155

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • jfjoch_process: Remove pixelrefine option (replaced with ProfileIntegrate2D)

  • jfjoch_viewer: Some graphical improvements.

  • jfjoch_viewer: Simplify and unify data analysis settings.

  • jfjoch_writer: Add TCP keepalive to increase robustness if jfjoch_broker “dies” in the middle of data acquisition.

1.0.0-rc.154

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • jfjoch_broker: Fix to TCP file pusher (remove kernel zero copy to improve reliability)

1.0.0-rc.153

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

  • jfjoch_broker: Add EXPERIMENTAL pixelrefine mode for image processing

  • jfjoch_broker: Allow to load user mask from 8-bit and 16-bit TIFF files

  • jfjoch_broker: Add ROI calculation in non-FPGA workflow

  • jfjoch_broker: Fixes to TCP image pusher

  • jfjoch_broker: Remove NUMA bindings

  • jfjoch_broker: Improvements to indexing

  • jfjoch_broker: For PSI EIGER, trimming energies are taken from the detector configuration (now compulsory) instead of hardcoded values

  • jfjoch_writer: Save ROI definitions and the per-pixel ROI bitmap in the master file; azimuthal ROIs support phi (angular) sectors

  • jfjoch_viewer: Major redesign with dockable panels and saved layouts, plus on-canvas creation/move/resize of box, circle and azimuthal ROIs

  • jfjoch_viewer: Run jfjoch_process reprocessing jobs from inside the GUI and overlay per-run results

1.0.0-rc.152

  • jfjoch_broker: Fix bounds for azimuthal integration for Q spacing (allow Q of 1e-5)

  • jfjoch_viewer: Adjust Q bounds for azimuthal integration

  • jfjoch_azint: Add tool to do quick azimuthal integration

1.0.0-rc.151

  • jfjoch_broker: For PSI EIGER detector allow to disable individual half-modules by putting empty hostname

1.0.0-rc.150

  • jfjoch_broker: When in FPGA workflow (with PSI detectors) azimuthal integration might be forced to CPU - this will require more computational power, but it enables more integration bins and reports standard deviation of each bin.

  • jfjoch_broker: Raise error if one is in FPGA flow and there are too many azimuthal integration bins.

1.0.0-rc.149

  • XDS plugin: Fix HDF5 mutex to run on multiple processors

1.0.0-rc.148

This is an UNSTABLE release. The release has significant modifications for data processing - in case of troubles go back to 1.0.0-rc.144.

  • jfjoch_broker: Improve azimuthal integration (add <I^2> calculation)

  • jfjoch_broker: Fixes around indexing, aiming to handle multi-lattice crystals (work in progress, it is not fully integrated)

  • jfjoch_writer: Save mean(I), stddev(I), and count(I) for each azimuthal bin

1.0.0-rc.147

This is an UNSTABLE release. The release has significant modifications for data processing - in case of troubles go back to 1.0.0-rc.144.

  • CI pipeline builds software with x86_64-v3 architecture, it should be compatible with practically all x86 hardware manufactured after 2015.

  • jfjoch_viewer: Add reciprocal space viewer

  • jfjoch_process: Two pass algorithm that does spot finding/indexing + integration of full dataset

  • jfjoch_process: Improve logic for rotation indexer, to make execution more deterministic (still work in progress)

1.0.0-rc.146

This is an UNSTABLE release. The release has significant modifications for data processing - in case of troubles go back to 1.0.0-rc.144.

  • jfjoch_broker: Add a lattice-orientation-only refinement option, in addition to full refinement (beam center, lattice orientation, lattice dimension)

  • jfjoch_process: Generate a dedicated file (_process.h5), which can be used as a replacement for the _master.h5 file for a reanalyzed dataset.

  • jfjoch_process: Improve the performance of scaling and merging, implement on the fly scaling.

  • jfjoch_writer: All final data analysis results are repopulated in the _master.h5 file.

  • jfjoch_scale: Dedicated tool for rescaling/merging existing data.

  • jfjoch_viewer: Fix bugs where pixel labels were displayed on a wrong pixel.

WARNING! Scaling and merging are experimental at the moment, and may not provide reasonable results for the time being.

1.0.0-rc.145

This is an UNSTABLE release. The release has significant modifications for HDF5 writing logic - in case of troubles go back to 1.0.0-rc.144.

  • Default HDF5 writing mode is with VDS, not soft-links - this improves DIALS compatibility and makes format more future-proof, NXmx legacy format might be phased-out in the future.

  • XDS plugin: Improve performance of VDS reading.

  • jfjoch_writer: Significant improvement on how file systems I/O are handled through a dedicated pass-through VFD.

  • jfjoch_writer: Clean-up of HDF5 routines to better handle issues.

1.0.0-rc.144

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Improve performance of preview JPEG image generator at receiver startup (saving about 150 ms on measurement start for 16M)

1.0.0-rc.143

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Avoid copying gain calibration together with DiffractionExperiment

1.0.0-rc.142

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • Support for newer CUDA architectures (notably Blackwell); minimum CUDA version 12.8

  • Minor changes to jfjoch_process, jfjoch_fpga_test and jfjoch_lite_perf_test to make them more consistent

1.0.0-rc.141

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Azimuthal integration mapping is generated with parallel computations, significantly reducing setup times

  • frontend: Fix selection of FFTW in indexing settings

1.0.0-rc.140

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: For DECTRIS detectors, ZeroMQ link is persistent, to save time for establishing new connection

  • jfjoch_broker: Minor bug fixes for rare conditions

  • jfjoch_process: Significantly improve performance

1.0.0-rc.139

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Further reduce startup time for DECTRIS detectors by selectively modifying SIMPLON parameters on /start

  • jfjoch_broker: Further reduce startup time for DECTRIS detectors by not setting beam center and detector distance via SIMPLON API on ‘/start’

  • jfjoch_broker: Add an extra message to ZeroMQ puller ready to monitor Lite workflow preparation time

  • jfjoch_broker: Image buffer configuration is postponed for Lite receiver flow till start message is received

  • jfjoch_broker: Use nanoseconds internally for frame/image/readout time

  • jfjoch_broker: Extra messages added for receiver operation (to be removed after debugging finished)

  • jfjoch_broker: Improve profiling of different data analysis steps

  • jfjoch_broker: Record integration reflection count

  • jfjoch_broker: Fix bug where ZeroMQ preview frequency was confusing time units (micro vs. milliseconds)

  • jfjoch_broker: Fix bug where ‘/wait_till_done’ got deadlocked

  • jfjoch_writer: Fix confusion between NaN and zero in floating-point datasets

Breaking changes: detector definition is now using nanoseconds to define minimum frame time, minimum count time and readout time.

1.0.0-rc.138

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Cleanup DECTRIS start-up code to enable a shorter start time

  • jfjoch_broker: Allow for asynchronous start to allow overlapping detector configuration with other beamline preparations

  • jfjoch_broker: Goniometer axis name is converted to lowercase

  • jfjoch_broker: Fix bug, where wrong HTTP error codes were returned

  • jfjoch_process: Improve sigma estimation during merging (K. Takaba)

  • jfjoch_process: Modify spot finding thresholds

1.0.0-rc.137

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Better track time for each operation in the processing stack

  • jfjoch_broker: Rewrite preprocessing of diffraction images in the non-FPGA workflow to better use GPUs (work in progress)

  • jfjoch_broker: Remove ROI calculation in the non-FPGA workflow (work in progress)

  • jfjoch_viewer: Toolbar displays image number starting from 1 (instead of 0)

1.0.0-rc.136

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Improve logic regarding indexing architecture and thread pools (work in progress).

1.0.0-rc.135

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • Multiple small bug fixes scattered across the whole code base. (detected with GPT-5.4)

  • jfjoch_viewer: Improve image render performance

1.0.0-rc.134

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Add better locking for detector object - should help, when detector initialization takes too long

  • jfjoch_writer: Enable writing single, integrated HDF5 file with both data and metadata

  • XDS plugin: Add generation of Jungfraujoch plugin for XDS

  • CI: Add tests with XDS and DIALS (xia2.ssx)

1.0.0-rc.133

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132.

  • jfjoch_broker: Use httplib for HTTP server instead of Pistache

  • jfjoch_broker: Drop OpenSSL support

  • jfjoch_broker: Base work for multi-lattice support in the future

  • jfjoch_broker: Improve recording time of data analysis steps

  • jfjoch_writer: Save per-image information about data analysis timing

  • Update dependencies to more recent versions (spdlog, HDF5, Catch2, httplib)

1.0.0-rc.132

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124.

  • Documentation: Fix equation rendering

1.0.0-rc.131

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124.

  • jfjoch_broker: Fix bug in saving JUNGFRAU calibration (pedestal/pedestalRMS)

  • jfjoch_viewer: Fix calibration (pedestal) images being open flipped

  • jfjoch_process: Add space group detection (EXPERIMENTAL)

1.0.0-rc.130

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124.

  • jfjoch_broker: Rotation indexer has two retries if it fails

  • jfjoch_broker: Rotation indexer handles small number of rotation images (like test shot)

  • jfjoch_broker: Integration calculates background mask based on R2 radius

  • jfjoch_process: HDF5 files are not saved by default

1.0.0-rc.129

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124.

  • jfjoch_broker: Significant improvements in TCP image socket, as a viable alternative for ZeroMQ sockets (only a single port on broker side, dynamically change number of writers, acknowledgments for written files)

  • jfjoch_broker: Delta phi is calculated also for still data in Bragg prediction

  • jfjoch_broker: Image pusher statistics are accessible via the REST interface

  • jfjoch_writer: Supports TCP image socket and for these auto-forking option

1.0.0-rc.128

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124.

  • jfjoch_broker: Handle properly reuse of image buffer locations

  • jfjoch_broker: Fix bug in counting idle slots

  • jfjoch_broker: Force obtuse angle for monoclinic cells

  • jfjoch_process: Change scaling refinement tolerance

1.0.0-rc.127

This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124.

  • jfjoch_broker: Default EIGER readout time is 20 microseconds

  • jfjoch_broker: Multiple improvements regarding performance

  • jfjoch_broker: Image buffer allows to track frames in preparation and sending

  • jfjoch_broker: Dedicated thread for ZeroMQ transmission to better utilize the image buffer

  • jfjoch_broker: Experimental implementation of transmission with raw TCP/IP sockets

  • jfjoch_writer: Fixes regarding properly closing files in long data collections

  • jfjoch_process: Scale & merge has been significantly improved, but it is not yet integrated into mainstream code

1.0.0-rc.126

This is an UNSTABLE release. If things go wrong with analysis, it is better to revert to 1.0.0-rc.124.

  • jfjoch_broker: Fix bug for monoclinic space groups being wrongly refined when beta is much different from 90 deg.

1.0.0-rc.125

This is an UNSTABLE release. This version adds scaling and merging. These are experimental at the moment, and should not be used for production analysis. If things go wrong with analysis, it is better to revert to 1.0.0-rc.124.

  • jfjoch_broker: Improve logic on switching on/off spot finding

  • jfjoch_broker: Increase maximum spot count for FFBIDX to 65536

  • jfjoch_broker: Increase default maximum unit cell for FFT to 500 A (could have performance impact, TBD)

  • jfjoch_process: Add scaling and merging functionality - program is experimental at the moment and should not be used for production analysis

  • jfjoch_viewer: Display partiality and reciprocal Lorentz-polarization correction for each reflection

  • jfjoch_writer: Save more information about each reflection

1.0.0-rc.124

This is an UNSTABLE release. This version significantly rewrites code to predict reflection position and integrate them, especially in case of rotation crystallography. If things go wrong with analysis, it is better to revert to 1.0.0-rc.123.

  • jfjoch_broker: Improve reflection position prediction and Bragg integration code.

  • jfjoch_broker: Align with XDS way of calculating Lorentz correction and general notation.

  • jfjoch_writer: Fix saving mosaicity properly in HDF5 file.

  • jfjoch_viewer: Introduce high-dynamic range mode for images

  • jfjoch_viewer: Ctrl+mouse wheel has exponential change in foreground (+/-15%)

  • jfjoch_viewer: Zoom-in numbers have better readability

1.0.0-rc.123

This is an UNSTABLE release.

  • jfjoch_broker: Use newer version of Google Ceres for (potential) CUDA 13 compatibility

  • jfjoch_broker: Improve performance of generating preview images, especially for large detectors (9M-16M)

  • jfjoch_viewer: Improve performance of displaying images, especially for large detectors (9M-16M)

  • jfjoch_viewer: Add more color schemes for better image readability

  • HDF5: Common mutex for reading and writing HDF5 if both operations were to happen in the same executable

  • HDF5: suppress warning if path (upstream group) doesn’t exist when checking if leaf exists

1.0.0-rc.122

This is an UNSTABLE release.

  • jfjoch_broker: Add thresholding to prefer shorter vectors after FFT

  • jfjoch_broker: Add experimental mosaicity estimation for rotation experiments (this is work in progress)

  • jfjoch_broker: Update nlohmann::json to 3.12.0

  • jfjoch_viewer: Display file opening errors

  • jfjoch_viewer: When loading files over DBus add retry/back-off till the file is available

1.0.0-rc.121

This is an UNSTABLE release.

  • jfjoch_broker: Report changes in the image buffer, so viewer doesn’t reload constantly

  • jfjoch_viewer: Improve performance of loading images

  • jfjoch_viewer: Auto-throttle image loading in HTTP-sync / movie modes

  • jfjoch_viewer: Auto-foreground calculated with histogram

  • jfjoch_viewer: Fix rare segmentation fault

1.0.0-rc.120

This is an UNSTABLE release.

  • jfjoch_broker: Improve performance of binary plot export

1.0.0-rc.119

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_broker: Add binary export of data analysis plots over OpenAPI

  • jfjoch_broker: Minor fixes to HTTP error handling

  • jfjoch_viewer: Prefer binary plots over JSON plots

  • jfjoch_viewer: Change foreground with F button + wheel

  • jfjoch_viewer: Change way how angles are displayed

  • jfjoch_viewer: Display resolution of the mouse cursor in top left corner

1.0.0-rc.118

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_viewer: Fix issue when HTTP sync silently disconnected when it was enabled when the broker was starting measurement.

  • jfjoch_broker: Add protections on time of geometry optimization and reduce rotation recalculations

1.0.0-rc.117

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_viewer: Add ROI results to the dataset info plots

  • jfjoch_writer: Remove HTTP interface, as it is not needed/used at the moment

1.0.0-rc.116

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_viewer: Add binning options in the context menu

1.0.0-rc.115

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_broker: Default spot finding settings can be configured via config JSON

  • jfjoch_viewer: FFT analysis of data in the dataset plot

1.0.0-rc.114

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_broker: Fix generating JPEG images with resolution estimation

1.0.0-rc.113

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_broker: Improve handling of rotation indexing

  • jfjoch_broker: More information saved in CBOR end message (WIP)

  • jfjoch_writer: Save rotation indexing lattice parameters and Niggli class

  • jfjoch_viewer: Remove (for now) primitive cell information

  • jfjoch_viewer: Use angle for dataset info plot for rotation scans

1.0.0-rc.112

This is an UNSTABLE release and not recommended for production use (please use rc.111 instead).

  • jfjoch_broker: Experimental rotation (3D) indexing

  • jfjoch_broker: Minor fix to error in optimizer potentially returning NaN values

1.0.0-rc.111

This is an UNSTABLE release.

  • jfjoch_viewer: Remove 3D lattice viewer (not really useful at this moment)

  • jfjoch_viewer: Fix auto contrast not refreshing image

1.0.0-rc.110

This is an UNSTABLE release.

  • jfjoch_broker: Add auto-contrast option for preview images

  • Frontend: Add logo image

  • jfjoch_viewer: Add logo image

  • jfjoch_viewer: For image chart allow to set min value to zero

  • jfjoch_viewer: For resolution estimation plots, visualization uses 1/d^2 as measure

  • jfjoch_viewer: Add 3D unit cell visualization (experimental/WIP/not really there)

  • Documentation: Add logo image

1.0.0-rc.109

This is an UNSTABLE release.

  • jfjoch_viewer: Add keyboard shortcuts and option to copy image to clipboard

  • jfjoch_broker: Fix bit-width and exposure time for PSI EIGER detectors

1.0.0-rc.108

This is an UNSTABLE release.

  • jfjoch_viewer: Fix bug when resolution estimation/B-Factor/Profile radius were not set (NaN)

  • jfjoch_viewer: Show spots is off by default, resolution ring mode is enabled by default

  • jfjoch_viewer: Fit to window of image is now default when size of the grid changes

1.0.0-rc.107

This is an UNSTABLE release.

  • jfjoch_viewer: Minor polishing of new functionality

  • jfjoch_broker: Use NaN for empty azimuthal bins

1.0.0-rc.106

This is an UNSTABLE release.

  • jfjoch_viewer: Allow for multiple dataset info plots

  • jfjoch_viewer: Highlight current element in grid

1.0.0-rc.105

This is an UNSTABLE release.

  • jfjoch_viewer: Clean-up widgets slightly

  • jfjoch_viewer: Limit right panel to 600 pixels

  • jfjoch_viewer: Parse crystal symmetry type

  • jfjoch_viewer: Grid scan view takes color map and can be fit to zoom

1.0.0-rc.104

This is an UNSTABLE release.

  • jfjoch_writer: Fix and improve the way grid scan geometry is saved (non-NXmx extension makes it way easier)

  • jfjoch_viewer: Display grid scan results in 2D (work in progress)

  • jfjoch_viewer: Improve auto-scaling on start of images (work in progress)

  • jfjoch_viewer: Add B-factor and resolution estimate to the dataset info plots

1.0.0-rc.103

This is an UNSTABLE release.

  • jfjoch_viewer: Minor improvements to the viewer

  • jfjoch_broker: Change behavior for modular detectors: coordinates of 0-th pixel can be now arbitrary and detector will be cropped to the smallest rectangle limited by module coordinates

1.0.0-rc.102

This is an UNSTABLE release.

  • jfjoch_viewer: Minor improvements to the viewer

1.0.0-rc.101

This is an UNSTABLE release.

  • jfjoch_viewer: Auto load is better handling change of states

  • jfjoch_viewer: Fix DBus registration

  • jfjoch_viewer: Handle charts better with vertical lines on hover and status bar update

  • jfjoch_viewer: Calculate ROI in a more efficient way

1.0.0-rc.100

This is an UNSTABLE release.

  • jfjoch_viewer: Fix dbus registration

  • jfjoch_viewer: Remove background slider for diffraction image

  • jfjoch_viewer: Adjustments for 2D azimuthal image viewer

1.0.0-rc.99

This is an UNSTABLE release.

  • jfjoch_broker: Fix output during mask data collection

1.0.0-rc.98

This is an UNSTABLE release and not recommended for production use (please use rc.96 instead).

  • jfjoch_broker: For DECTRIS detectors fix dark data collection during initialization

1.0.0-rc.97

This is an UNSTABLE release and not recommended for production use (please use rc.96 instead).

  • jfjoch_broker: For DECTRIS detectors add dark data collection during initialization for bad pixel mask

  • jfjoch_broker: Refactor of calibration logic for more clear code (likely to introduce problems)

  • jfjoch_viewer: Add option to handle user pixel mask (experimental)

  • jfjoch_viewer: More options for ROI

  • jfjoch_viewer: Add window to display calibration

1.0.0-rc.96

This is an UNSTABLE release.

  • Fixes in CI pipeline

  • jfjoch_broker: Remove PNG preview, no dependency on libpng

  • jfjoch_writer: Fix UTC timestamp being generated wrong (mix between milli- and microseconds)

  • jfjoch_viewer: Show data collection time in dataset tooltip

  • jfjoch_viewer: Allow to choose the calibrant (presets for LaB6 and silver behenate)

  • jfjoch_viewer: Auto foreground value

  • Use external libjpeg-turbo and libtiff: simpler build stack, these are built and linked statically in automated Docker builds

  • Remove OpenBLAS dependency

1.0.0-rc.95

This is an UNSTABLE release.

  • Fixes in CI pipeline

  • Add git-lfs to Rocky8 docker image

Previous releases (91-94) had a wrong FPGA image upload to Gitlab release. This is now solved.

1.0.0-rc.94

This is an UNSTABLE release.

  • FFTIndexer: Add limit on angles to avoid colinear vectors

  • Docker images: Add 3D Qt

  • Gitea: Fixes to the pipeline

1.0.0-rc.93

This is an UNSTABLE release.

  • CI: Fixes to Gitlab based pipeline

  • PCIe driver: Fix PCIe revision being hex number

1.0.0-rc.92

This is an UNSTABLE release.

  • jfjoch_broker: Fix code that predicted Bragg reflections scattering back from the sample.

1.0.0-rc.91

This is an UNSTABLE release. This release introduces new features, which usually means these need more field testing before enough maturity. For production use we recommend waiting for a future bug-fix release.

  • FPGA: Implement high pixel value threshold - pixels above the given value will be considered saturated

  • jfjoch_broker: Spot finding and integration predictions are ported to a GPU

  • jfjoch_broker: Estimate resolution

  • jfjoch_broker: Lattice search

  • jfjoch_broker: Many more improvements in image analysis

1.0.0-rc.90

This is an UNSTABLE release.

  • jfjoch_broker: for indexing min index spots for a viable cell can be changed via OpenAPI

  • jfjoch_viewer: Optional auto-reanalyze images

  • jfjoch_writer: Add option where no files at all are saved

  • Documentation: improvements

1.0.0-rc.89

This is an UNSTABLE release.

  • jfjoch_broker: Fix resolution estimation code

  • jfjoch_broker: Fix Wilson B-factor calculation code

  • jfjoch_viewer: Improve display of plots

  • jfjoch_viewer: Fix segmentation fault

  • jfjoch_viewer: Display missing metadata when using HTTP

  • jfjoch_viewer: Fix bug when opening the same file twice

1.0.0-rc.88

This is an UNSTABLE release.

  • jfjoch_viewer: Add resolution estimation to the image information

  • jfjoch_broker: Minor changes to resolution estimate routine

1.0.0-rc.87

This is an UNSTABLE release.

  • jfjoch_viewer: Display more image metadata (angle / exposure time)

  • jfjoch_viewer: Improve I/sigma and B-factor plots

  • jfjoch_broker: Estimate resolution based on visible spots

1.0.0-rc.86

This is an UNSTABLE release.

  • jfjoch_broker: Update logic when initializing detector to make it a bit more resilient

  • Gitea pipelines have nocuda option for all architectures

1.0.0-rc.85

This is an UNSTABLE release.

  • jfjoch_viewer: When using online view, dataset info plots are not switched back to the first category for each image

  • jfjoch_viewer: Handle spot count better in dataset info plots

  • jfjoch_viewer: Highlight spots in ice ring resolutions in cyan, when detection is enabled

1.0.0-rc.84

This is an UNSTABLE release.

  • jfjoch_broker: Write in log which detector is being initialized

  • Changes to automated build system

1.0.0-rc.83

This is an UNSTABLE release.

  • jfjoch_viewer: Fix in generating preview image for signed data (wrong bit-width was assumed before)

  • CI: Fix script to generate python client

1.0.0-rc.82

This is an UNSTABLE release.

  • jfjoch_viewer: Enable FFTW based indexing in viewer (very slow at the moment)

  • Frontend: Minor fixes

  • Build scripts: Minor fixes to FFTW

1.0.0-rc.81

This is an UNSTABLE release. This release introduces new features, which usually means these need more field testing before enough maturity. For production use we recommend waiting for a future bug-fix release.

  • jfjoch_broker: Add option to detect ice rings, adjust width of ice ring and change of logic to exclude ice rings in indexing

  • jfjoch_broker: Add FFTW based indexer for CPU only indexing

  • jfjoch_broker: Enable saving X-ray fluorescence spectra

  • jfjoch_writer: Write total spot count (before filtering)

  • jfjoch_viewer: Add more information on source, sample, and button to show ice rings

  • jfjoch_viewer: Enable data processing inside the viewer

CI: Moving from Gitlab to Gitea at PSI

1.0.0-rc.80

This is an UNSTABLE release.

  • jfjoch_broker: Fix bug when wrong value for a plot (NaN or infinity) would lead to a null in a plot, which cannot be parsed by viewer

1.0.0-rc.79

This is an UNSTABLE release.

  • jfjoch_viewer: Fix bug when loading new dataset was creating a cascade of signals leading to poor performance

  • jfjoch_writer: Save nimages_per_trigger in detectorSpecific

1.0.0-rc.78

This is an UNSTABLE release.

  • jfjoch_viewer: Using a single event loop (reading images is not in dedicated thread anymore)

1.0.0-rc.77

This is an UNSTABLE release.

  • jfjoch_viewer: Display detector and dataset settings with tooltips

  • jfjoch_viewer: Clean excessive HDF5 warnings

  • jfjoch_viewer: Display unit cell

  • jfjoch_extract_hkl: Write a tool to extract reflection intensity from a dataset

1.0.0-rc.76

This is an UNSTABLE release.

  • jfjoch_broker: Increase predicted hkl to 100.0, use lighter math to exclude too-high resolution ones

  • jfjoch_broker: Use standard deviation formula to find profile radius (not the one using median)

  • jfjoch_writer: Save space group number (non-NXmx addition) in addition to name

  • jfjoch_viewer: Fix the bug on reading space_group as string

  • jfjoch_viewer: Add missing resolution labels on rings

  • jfjoch_viewer: Remove Q value from the status bar

1.0.0-rc.75

This is an UNSTABLE release.

  • jfjoch_broker: EIGER2 missing minimum threshold - hardcoded to 2.7 keV for the time being

1.0.0-rc.74

This is an UNSTABLE release.

  • jfjoch_broker: Fix for EIGER UDP port settings (vertical half of the module missing)

  • jfjoch_broker: Detector settings were not applied for EIGER/DECTRIS detector when changed after initialization

1.0.0-rc.73

This is an UNSTABLE release.

  • jfjoch_broker: Space group number treatment in OpenAPI was wrong, zero value is no longer allowed and no longer default

1.0.0-rc.72

This is an UNSTABLE release. This release introduces new features, which usually means these need more field testing before enough maturity. For production use we recommend waiting for a future bug-fix release.

  • jfjoch_broker: Refactor of indexing and geometry refinement code

  • jfjoch_broker: Handle space group/centering in refinement code

  • jfjoch_broker: Replace mosaicity with profile radius: refining the former is difficult with still images

  • jfjoch_broker: There is no longer 0.5 pxl offset for spots-to-reciprocal-space conversion

  • jfjoch_writer: Experimental saving of reflections

  • jfjoch_writer: Save space group name as string

  • jfjoch_viewer: Add profile radius and B-factor

  • jfjoch_viewer: Show 4 digits for wavelength

  • jfjoch_viewer: Match rings between calibrant and observation (will handle missing/wrong rings)

  • FPGA: Use UDP destination port to distinguish between detector modules and data streams

  • FPGA: Add experimental PTP core (PTP over L2, only Sync/Follow_up)

  • FPGA driver: Fix for Linux kernel 6.12+ (thanks to Tim Gruene)

1.0.0-rc.71

This is an UNSTABLE release.

  • jfjoch_broker: Remove resolution estimation via machine learning

  • jfjoch_broker: Harmonize code to analyze spot finding results (indexing/refinement/integration) between CPU and FPGA receivers

  • jfjoch_viewer: Fix error when HDF5 files with indexing results couldn’t be loaded on a machine without GPU

1.0.0-rc.70

This is an UNSTABLE release. This release introduces new features (geometry refinement), which usually means these need more field testing before enough maturity. For production use we recommend waiting for a future bug-fix release.

  • jfjoch_broker: Fix bug when PSI EIGER frame time was not set properly at the start of the measurement

  • jfjoch_broker: Fix PONI rot2 angle rotating detector in a wrong direction (PyFAI convention is for this angle to rotate detector downwards)

  • jfjoch_broker: Enable geometry refinement - first try (work in progress)

  • jfjoch_viewer: Fix deadlock when opening HTTP connections

  • jfjoch_viewer: Display rings as ellipses with detector tilt

  • jfjoch_viewer: Add button to calibrate detector geometry based on LaB6 image

  • jfjoch_writer: Save detector tilt angles (rot1, rot2, rot3)

  • Add Google Ceres a non-linear least-square optimization library to Jungfraujoch

  • Add experimental detector calibration routines (for LaB6)

  • Improve documentation on the ZeroMQ writer notification socket and detector geometry

1.0.0-rc.69

This is an UNSTABLE release.

  • jfjoch_viewer: Metadata can be modified for an open dataset (no option to save)

  • jfjoch_viewer: Refactor multiple issues in the viewer regarding image reading code to allow for further developments

  • jfjoch_viewer: Resolution rings not enabled by default

  • jfjoch_broker: Handle properly PONI rotations in dataset settings though still not updated properly in the HDF5 file

1.0.0-rc.68

This is an UNSTABLE release.

  • jfjoch_broker: Temperature threshold can be changed for JUNGFRAU detector

  • jfjoch_broker: Default detector settings can be configured for each detector separately

  • jfjoch_broker: Refactor spot filtering code, max spot count can be modified for dataset settings

  • jfjoch_broker: Refactor indexing refinement, make it the same for both FFBIDX and FFT indexing

  • jfjoch_broker: Reference unit cell will be taken into account for FFT indexing to filter

  • jfjoch_broker: Review PONI rotation angles and azimuthal angle conventions along with PyFAI

1.0.0-rc.67

This is an UNSTABLE release.

  • jfjoch_broker: Enable SSL

  • jfjoch_broker: Wilson B-factor only provided if fit is relatively OK (R^2 > 0.3); this will be refined much more in the future

1.0.0-rc.66

This is an UNSTABLE release.

  • jfjoch_broker: Indexers operate as a thread pool

  • jfjoch_viewer: Increase interval between loading images + fix too many verbose messages

1.0.0-rc.65

This is an UNSTABLE release.

  • jfjoch_broker: Print information regarding used image pushers

  • jfjoch_viewer: Allow syncing with Jungfraujoch server

  • OpenAPI: Clarify licensing terms in the file

1.0.0-rc.64

This is an UNSTABLE release.

  • jfjoch_broker: Fix issue in receiver light with very long preparation time for threads

  • jfjoch_broker: Add verbose option

  • jfjoch_broker: Don’t trigger pedestal if critical settings are not changed when loading detector settings

  • jfjoch_broker: Detector left in busy state when detector settings were improper

  • jfjoch_viewer: Modify DBus interface to avoid loading same file and image 0 multiple times

  • jfjoch_lite_perf_test: Add verbose option

1.0.0-rc.63

This is an UNSTABLE release.

  • jfjoch_broker: Save NX/NY for grid scan result

  • jfjoch_broker: Add processing time to CBOR output and plot

  • jfjoch_writer: Add processing time to data file

1.0.0-rc.62

This is an UNSTABLE release.

  • jfjoch_broker: Fix bug where low resolution spots were not counted properly

  • jfjoch_broker: Spot count is provided prior to filtering of spots to max_spot_count

  • jfjoch_broker: Add more spot count information to CBOR

  • jfjoch_viewer: Fix issue with ROI drawing resulting in multiple overlapping rectangles

1.0.0-rc.61

This is an UNSTABLE release.

  • jfjoch_broker: Fix bug where FFT indexing could result in a very short or even zero length vector

  • jfjoch_broker: Ice ring and indexed spot count enabled as plots and saved in grid scan results

  • jfjoch_broker: High resolution limit for low res. spot counting can be adjusted

1.0.0-rc.60

This is an UNSTABLE release.

  • jfjoch_broker: Fix bug when the neural network inference client was busy and this status was never released

  • jfjoch_broker: Revert the indexing threshold with distance from integer for Miller indices

  • jfjoch_broker: Fix bug in scattering vector calculation, resulting in indexing not working outside 1.0 A X-ray wavelength

1.0.0-rc.59

This is an UNSTABLE release.

  • jfjoch_broker: Fix bug when broker was waiting for notification message before sending end message, resulting in deadlock.

  • jfjoch_writer: Verbose option for debugging.

1.0.0-rc.58

This is an UNSTABLE release.

  • jfjoch_viewer: Fix memory leak

  • jfjoch_writer: Add detector_number/serial_number to master file

1.0.0-rc.57

This is an UNSTABLE release.

  • jfjoch_broker: Fix bug when enabling ML resolution estimation was not possible

  • jfjoch_viewer: “Movie” mode

1.0.0-rc.56

This is an UNSTABLE release.

  • jfjoch_broker: Fixing more bugs related to neural network inference for ML estimation

1.0.0-rc.55

This is an UNSTABLE release.

  • jfjoch_broker: Fixing minor bugs related to neural network inference for ML estimation

1.0.0-rc.54

This is an UNSTABLE release.

  • jfjoch_broker: Indexing with AUTO settings (FFBIDX if unit cell provided; FFT if not)

  • jfjoch_broker: Don’t remove shared memory area when deactivating detector

  • jfjoch_writer: Save writer release

  • jfjoch_viewer: Increase time for the messages in the status bar

1.0.0-rc.53

This is an UNSTABLE release.

  • PCIe driver: Imperfect solution for RHEL 9.5+ changes

  • jfjoch_writer: Fix to angle containers for AutoProc compatibility

  • jfjoch_fpga_test: Use consecutive number for devices, not interleaved

1.0.0-rc.52

This is an UNSTABLE release.

  • jfjoch_viewer: Use warmer colors to distinguish from AareGUI

  • jfjoch_viewer: Minor adjustments to DBus setting image number

  • jfjoch_broker: Fix in low resolution spot count plotting

1.0.0-rc.51

This is an UNSTABLE release.

  • jfjoch_broker: Send preview in PNG format

  • jfjoch_broker: Provide count of spots in 50.0 - 5.0 A range

  • jfjoch_broker: Provide ML resolution estimation in scan result

  • jfjoch_broker: Allow removing beam center in web preview

1.0.0-rc.50

This is an UNSTABLE release.

  • The release fixes some of many bugs introduced in recent releases

  • jfjoch_viewer: display predictions for indexed cells

1.0.0-rc.49

This is an UNSTABLE release.

  • jfjoch_broker: Add sample temperature (K) and ring current (mA) to metadata

  • jfjoch_writer: For angle containers in NXmx add _end dataset, sample temp. and ring current

1.0.0-rc.48

This is an UNSTABLE release.

  • jfjoch_broker: fix the bug when a unit cell was not exported for a scan result.

1.0.0-rc.47

This is an UNSTABLE release.

  • jfjoch_viewer: fix dbus service path

  • jfjoch_writer: fix CBF/TIFF writing

1.0.0-rc.46

This is an UNSTABLE release.

  • jfjoch_viewer: remove dependency on image analysis

1.0.0-rc.45

This is an UNSTABLE release.

  • jfjoch_broker: Detector list returns pixel size (mm)

1.0.0-rc.44

This is an UNSTABLE release.

  • jfjoch_broker: more general definition of scan result export

Breaking changes:

  • It removes additions to OpenAPI from 1.0.0-rc.43

  • It makes changes to the “unit_cell” definition in OpenAPI specs. It might be harmless in some languages and may result in errors in other implementations.

1.0.0-rc.43

This is an UNSTABLE release.

  • jfjoch_broker: Export grid scan results into a single data structure

1.0.0-rc.42

This is an UNSTABLE release.

  • jfjoch_broker: Add pixel_sum to CBOR output.

  • jfjoch_broker: Changes to sigma estimation in QuickIntegrate routine

  • jfjoch_writer: Save pixel_sum

1.0.0-rc.41

This is an UNSTABLE release. This release includes multiple new features, it should not be used in production at the moment.

  • jfjoch_broker: Estimate B-factor, mosaicity to evaluate crystal diffraction

  • jfjoch_broker: Export GPU count via OpenAPI

  • jfjoch_broker: Enable 2D azimuthal integration and PONI rotations for detector

  • FPGA: Increase the number of integration bins to 2048

1.0.0-rc.40

This is an UNSTABLE release. This release includes multiple new features, it should not be used in production at the moment.

  • jfjoch_broker: Jungfraujoch supports grid scan metadata, including dedicated plotting schemes and NXmx structures

  • jfjoch_broker: Improve metadata for rotation data collection

  • jfjoch_broker: Better handling of plotting

  • jfjoch_broker: FFT based indexing

  • jfjoch_broker: Integration, first try, results not saved at the moment

  • jfjoch_broker: Internal improvements in image handling

  • jfjoch_writer: Multiple adjustments adapt to changes in this release for new features

  • jfjoch_writer: New state management model to improve clarity of error reporting

  • jfjoch_viewer: Remote control via DBus

  • Frontend: Multiple adjustments for new features

  • Frontend: Grid scan plots

WARNING! OpenAPI contains breaking changes in regard to plotting results, so care has to be taken.

1.0.0-rc.39

  • FPGA: Bugfix for pixel masked for data analysis if summation was on

  • jfjoch_viewer: Fix segmentation fault when cursor was outside of image

1.0.0-rc.38

  • jfjoch_broker: Neural net model is not linked with C++ code due to deployment issues, it is rather distributed as python code, connected via REST

  • jfjoch_broker: Neural net model can use all 4 quadrants of the detector

  • jfjoch_broker: For EIGER image time can be provided through /start

  • jfjoch_viewer: Add image list option

  • jfjoch_viewer: Drawing circular ROIs with shift

  • jfjoch_viewer: Enable image summation

  • jfjoch_viewer: Image reader is significantly reworked, hopefully without affecting the viewer

1.0.0-rc.37

  • jfjoch_broker: Make locking rules more flexible

  • jfjoch_broker: Load mask via SIMPLON interface for DECTRIS detectors

  • jfjoch_viewer: Add status bar

1.0.0-rc.36

This is an UNSTABLE release. Wait for a new version to use in a production environment.

  • jfjoch_broker: Support for Jungfraujoch Lite is enabled - software-based receiver for DECTRIS detectors (required a lot of refactoring, potentially leading to unstable code)

  • jfjoch_broker: Enable Resonet support (ML-based diffraction resolution estimation)

  • jfjoch_broker: Fix error in compression, where bitshuffle/LZ4 and bitshuffle/Zstd HDF5 headers were wrongly generated for 8-bit and 32-bit data

  • jfjoch_writer: Increase buffering to 1000 images in the receiver

  • jfjoch_writer: Images can be written as CBF or TIFF in addition to HDF5

1.0.0-rc.35

This is an UNSTABLE release, not properly tested. Wait for a new version before using it in production.

  • jfjoch_broker: If module is delayed by more than 50 frames versus other modules, it will be ignored and receiver is not waiting.

  • jfjoch_writer: Save EIGER energy threshold

  • jfjoch_writer: Add /entry/sample/goniometer for compatibility with eiger2cbf program

1.0.0-rc.34

This is an UNSTABLE release - introducing new features, but not properly tested. Wait for a new version before using it in production.

  • jfjoch_broker: More consistency for file format definition (breaking change in API from 1.0.0-rc.31 for file writer settings)

  • jfjoch_broker: For storage cells mask is logical sum of detector bad pixels for all storage cells

  • jfjoch_broker: Handle situation when detector doesn’t want to gracefully stop (to be tested)

  • jfjoch_broker: Center-of-mass position and mean for ROI is added to available plots

  • jfjoch_viewer: Can extract data analysis results from “legacy” format

  • jfjoch_viewer: Display dataset name

  • FPGA: Pixel mask is used for data analysis part even if it is not applied to pixels

  • FPGA: Add pixel sum to module statistics

  • FPGA: ROI number is reduced to 16, but pixel can belong to every defined ROI

  • FPGA: Spot finder is back to full dynamic range (24-bit)

  • FPGA: More debug features for internal FIFOs

Known issues:

  • ROI count flag was added to firmware. For the time being the flag will be wrongly set to 10 due to mismatch of FPGA build scripts.

  • EIGER data acquisition has an issue that is currently debugged

1.0.0-rc.33

  • jfjoch_broker: Fix issue with EIGER settings being loaded improperly

1.0.0-rc.32

  • jfjoch_broker: Refactor code for azimuthal integration for further improvements

  • jfjoch_broker: Minor fix for EIGER (trim energies are manually set for E9M, to be fixed properly later)

  • jfjoch_writer: Fix too much verbose information

  • FPGA: Minor fixes to spot finder (enable two-pass operation and limit number range to int20)

1.0.0-rc.31

This is UNSTABLE release - introducing many features, but still needs more testing. Expecting soon to put bugfix release.

  • jfjoch_writer: Allow to enable overwriting existing files (not enabled by default)

  • jfjoch_writer: Add new HDF5 master file format, which uses HDF5 virtual data sets and links processing results to data files (not enabled by default)

  • jfjoch_viewer: Image viewer, early test version

  • jfjoch_broker: Fixes to counting packets per dataset/image

  • jfjoch_broker: Image buffer is accessible for outside to check images

  • jfjoch_broker: error/saturated pixels and dedicated ROI “beam” can be tracked online

  • jfjoch_broker: Fix bug in handling pedestal G1/G2 count time for JUNGFRAU

  • jfjoch_broker: Fix bug in applying pixel mask interfering with pedestal calculation

  • jfjoch_broker: Fix bug in EIGER initializing

  • jfjoch_broker: Save maximum pixel value to HDF5 file and export as Web plot

  • PCIe driver: Add PCIe link speed and width

  • FPGA: Improve counting error/saturated/min/max pixels

  • FPGA: Spot finder is gradual column-wise (15 columns up/down) and fixed row-wise (32 pixel boxes); previously it was fixed both column- and row-wise with 32x32 pixel areas

  • FPGA: Require Vivado 2022.2

Warning: There are breaking changes to HDF5 file format, renaming entries regarding image storage cell number and image collection efficiency.

1.0.0-rc.30

  • jfjoch_writer: replace non-blocking with blocking operation on internal queues - less likely to “lose” images within the writer

1.0.0-rc.29

  • jfjoch_broker: refactor logic regarding frame time and count time for more flexibility for EIGER and JUNGFRAU

  • jfjoch_broker: readout time for EIGER is 3 us and JUNGFRAU is 20 us, this can be changed in input file

  • jfjoch_broker: OpenAPI interface includes more ways to provide information on the status (error/warning/info)

  • jfjoch_broker: ROIs handling via OpenAPI and frontend is more user friendly

Warning - two breaking changes to OpenAPI:

  • Handling of ROIs is through /config/roi path only for both circle and box ROIs, paths in /roi are no longer accessible

  • broker_status structure introduced in 1.0.0-rc.28 has member message and not error_message to allow handling info/warning messages as well

1.0.0-rc.28

  • jfjoch_broker: save error message for initialization and data collection and provide these with OpenAPI

  • jfjoch_broker: fixed issue when in error state, response to /wait_till_done was not compliant with OpenAPI specs

  • jfjoch_test: remove header that failed when CUDA is absent during compilation

  • frontend: add soft trigger button in data collection tab

  • frontend: show error message when in error state

  • CMake: add option to force compilation without CUDA (-DJFJOCH_USE_CUDA=OFF)

1.0.0-rc.27

  • jfjoch_broker: add option to select electron source in instrument metadata, adapt wavelength calculation

  • jfjoch_broker: update pistache web server version

  • jfjoch_writer: minor changes to republish logic

  • Improvements to documentation

1.0.0-rc.26

  • jfjoch_broker: implement ZeroMQ stream for image metadata information

  • jfjoch_broker: refactor ZeroMQ stream for preview: start/end messages always sent

  • jfjoch_broker: add crystal lattice plots

  • jfjoch_broker: remove empty bins from the plots

  • jfjoch_broker: Fix bugs in ModuleSummation and MXAnalyzer for CPU “long” summation

  • jfjoch_broker: Fix bug when mean background estimation / indexing rate were affected by previous experiment

  • jfjoch_writer: fix missing “-w” parameter

  • jfjoch_writer: temporary files have “.tmp” suffix

  • jfjoch_writer: refactor logic for watermarks

  • jfjoch_writer: report on internal FIFO utilization

  • jfjoch_writer: clean-up naming for azimuthal integration and background estimate

  • jfjoch_writer: write final background estimate and indexing rate in the master file

  • tools/: remove unnecessary tools, make naming consistent

  • CBOR: Add indexing rate and background estimate to end message

  • CBOR: Clean-up documentation

1.0.0-rc.25

  • Updates to documentation

  • License set to GPLv3 / OHL-S

  • Fix bug in DiffractionExperiment::GetDefaultPlotBinning() - resulting in division by 0 if image time longer than 500ms

  • Add information on JUNGFRAU conversion and geometry transformation to CBOR and HDF5

1.0.0-rc.24

New FPGA functionality:

  • EIGER supports 8, 16 and 32-bit data input (for 8-bit mode at half performance; for 32-bit “real” depth is 23-bit + 1-bit signed)

  • Output possible to 8, 16 and 32-bit data

  • Threshold is applied before summation

  • Pixel mask can be applied on FPGA

  • Mark pixels with ADC content = 0 as bad pixels

  • FPGA stores semantic version information (access via /sys/class/misc/jfjoch…/version)

New software functionality:

  • Long summation (above 256 frames) done on CPU

  • Mechanism to save arbitrary data to HDF5 file

  • ZeroMQ preview has option to send start message

  • Rework pixel mask + add statistics displayed in web interface

Bug fixes:

  • Web frontend: Update preview image automatically during data acquisition

  • jfjoch_broker: Error handling if CUDA driver is not installed

  • jfjoch_broker: Correctly update progress during pedestal

  • jfjoch_broker: Provide proper error when uploaded file is not a proper TIFF

  • jfjoch_action_test: enable HLS simulation

Documentation improvement and placement in a dedicated directory

\ No newline at end of file diff --git a/CPU_DATA_ANALYSIS.html b/CPU_DATA_ANALYSIS.html new file mode 100644 index 000000000..8ba12b0ce --- /dev/null +++ b/CPU_DATA_ANALYSIS.html @@ -0,0 +1 @@ + CPU-side crystallographic data analysis (Jungfraujoch) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

CPU-side crystallographic data analysis (Jungfraujoch)

This document describes the crystallographic algorithms implemented in Jungfraujoch for CPU- and GPU-side real‑time and near‑real‑time data analysis.

Scope. The pipeline covered here comprises:

  1. geometry mapping and corrections,

  2. azimuthal integration (powder/radial profiles),

  3. Bragg spot finding (strong pixels → connected components → spot descriptors),

  4. indexing (still and rotation modes),

  5. Bravais lattice / centering inference,

  6. geometry and lattice refinement,

  7. reflection prediction (still and rotation),

  8. Bragg integration by either 2D box summation or profile fitting (Kabsch, reference-free),

  9. scaling and merging,

  10. merge-level error modelling, outlier rejection and the resolution cutoff,

  11. space-group determination from the merged intensities (Laue group, screw axes, glide planes, centering, the centre of symmetry), the twinning check and the translational pseudo-symmetry check,

  12. auxiliary statistics (Wilson plot, ⟨I/σ(I)⟩, CC1/2, CCref),

  13. amplitude estimation (French–Wilson) and R-free test-set flagging,

  14. optional model-based validation: rigid-body placement of a supplied model (molecular replacement where the rigid body does not place it, or for a predicted model), R-free against it, sigma_A-weighted 2mFo−DFc / mFo−DFc electron-density maps, and an anomalous difference map with the strongest anomalous sites named.

  15. restrained refinement of the placed model (wherever a model is placed): rigid bodies and group B, then positions and B against a maximum-likelihood amplitude target with the dictionary’s geometry, the X-ray weight chosen by R-free within geometry bounds, and the unexplained blobs of the refined difference map.

The reference is split into five parts, in pipeline order; the section numbers run continuously across them and are the ones the rest of the documentation cites.

  • From images to spots (§0–§3) — device-side decoding, geometry and reciprocal-space mapping, azimuthal integration, spot finding.

  • Indexing and geometry refinement (§4–§7) — FFT and fast-feedback indexing, the lattice search, geometry refinement, post-refinement, powder calibration, and the stills geometry with a given cell and detector modules.

  • Prediction, integration, scaling and merging (§8–§12) — reflection prediction, profile-fitted integration, scaling, merging, mosaicity and the auxiliary statistics.

  • Space group and validation (§13–§14) — the space-group search, twinning and translational pseudo-symmetry, the resolution cutoff, diffraction anisotropy, model-based validation and molecular replacement.

  • Refinement of a placed model (§15) — the maximum-likelihood target and its FFT gradient, the scale, bulk solvent and likelihood parameters, the dictionary and its restraints (metal sites and B included), the minimiser, the weights chosen by trial, the refined maps and their unexplained blobs, and what is not implemented yet.

References

The methods draw on, and in places reimplement, solutions from:

  • W. Kabsch, “XDS”, Acta Cryst. D66 (2010), 125–132 and related XDS papers (rotation geometry, partiality, scaling concepts).

  • W. Kabsch, “Integration, scaling, space-group assignment and post-refinement”, Acta Cryst. D66 (2010), 133–144 (mosaicity/partiality likelihood treatment; notation such as ζ and rotation factors).

  • T. A. White et al., CrystFEL method papers (spot finding, three‑ring integration, serial/still diffraction processing concepts).

  • J. Kieffer & J. P. Wright, “PyFAI: a Python library for high performance azimuthal integration on GPU”, Powder Diffraction 28 (2013), S339-S350 (detector geometry definition, azimuthal integration)

  • G. Bricogne, Proceedings of the EEC Cooperative Workshop on Position-Sensitive Detector Software (Phase III), LURE, Paris (1986), p. 28 (Fourier-transform indexing, proposed as a three-dimensional transform; §5 uses its one-dimensional projection form).

  • I. Steller, R. Bolotovsky & M. G. Rossmann, “An algorithm for automatic indexing of oscillation images using Fourier analysis”, J. Appl. Cryst. 30 (1997), 1036-1040 (the projection/1D-FFT autoindexing algorithm of §5).

  • H. Powell, “The Rossmann Fourier autoindexing algorithm in MOSFLM”, Acta Cryst. D55 (1999), 1690-1695 (the MOSFLM implementation of it, whose practice is followed)

  • P. Gasparotto, L. Barba, H.-C. Stadler et al., “TORO Indexer: a PyTorch-based indexing algorithm for kilohertz serial crystallography”, J. Appl. Cryst. 57 (2024), 931-944 (the algorithm of the ffbidx fast-feedback indexer, §4).

  • I. Křivý & B. Gruber, “A unified algorithm for determining the reduced (Niggli) cell”, Acta Cryst. A32 (1976), 297-298, and International Tables for Crystallography Vol. A, Table 9.2.5.1 (the Niggli reduction and the lattice-character table of §5.3/§6).

  • J. E. Padilla & T. O. Yeates, “A statistic for local intensity differences: robustness to anisotropy and pseudo-centering and utility for detecting twinning”, Acta Cryst. D59 (2003), 1124-1130 (the L test, §13.2).

  • T. O. Yeates, “Detecting and overcoming crystal twinning”, Methods Enzymol. 276 (1997), 344-358 (the twinned intensity model and the \(H\) statistic behind the twin fraction of the twin hypothesis, §13.2, §14.9).

  • A. J. C. Wilson, “The probability distribution of X-ray intensities”, Acta Cryst. 2 (1949), 318-321, and E. R. Howells, D. C. Phillips & D. Rogers, “The probability distribution of X-ray intensities. II. Experimental investigation and the X-ray detection of centres of symmetry”, Acta Cryst. 3 (1950), 210-214 (the acentric and centric intensity distributions behind the centre-of-symmetry statistics of §13.1 and the Wilson outlier test of §13.3).

  • W. H. Baur & D. Kassner, “The perils of Cc: comparing the frequencies of falsely assigned space groups with their general population”, Acta Cryst. B48 (1992), 356-369 (writing the centrosymmetric group where the absences cannot decide the centre, §13.1).

  • R. J. Read, P. D. Adams & A. J. McCoy, “Intensity statistics in the presence of translational noncrystallographic symmetry”, Acta Cryst. D69 (2013), 176-183 (the native-Patterson detection of translational pseudo-symmetry, and the intensity modulation it produces, which the axial-zone screw-absence test scores against).

  • A. Barty, R. A. Kirian, F. R. N. C. Maia et al., “Cheetah: software for high-throughput reduction and analysis of serial femtosecond X-ray diffraction data”, J. Appl. Cryst. 47 (2014), 1118-1131 (peakfinder8: the per-resolution-ring background statistics of §3.2).

  • A. Hennequin, B. Couturier, V. V. Gligorov & L. Lacassagne, “SparseCCL: Connected Components Labeling and Analysis for sparse images”, DASIP 2019, 65-70 (the connected-component labelling of §3.4, used via ACTS/traccc).

  • S. French & K. Wilson, “On the treatment of negative intensity observations”, Acta Cryst. A34 (1978), 517-525 (Bayesian amplitude estimation from intensities), and CCP4’s ctruncate (C. Ballard & N. Stein), whose anisotropic Wilson prior §10.8 follows, cited through M. D. Winn et al., “Overview of the CCP4 suite and current developments”, Acta Cryst. D67 (2011), 235-242.

  • A. T. Brünger, “Free R value: a novel statistical quantity for assessing the accuracy of crystal structures”, Nature 355 (1992), 472-475 (R-free cross-validation).

  • P. H. C. Eilers, “A perfect smoother”, Anal. Chem. 75 (2003), 3631-3636, after E. T. Whittaker, “On a new method of graduation”, Proc. Edinburgh Math. Soc. 41 (1923), 63-75 (the penalised smoother of the fulls’ per-frame scale, §10.6).

  • H. F. Walker & P. Ni, “Anderson acceleration for fixed-point iterations”, SIAM J. Numer. Anal. 49 (2011), 1715-1735, after D. G. Anderson, “Iterative procedures for nonlinear integral equations”, J. ACM 12 (1965), 547-560 (the acceleration of the per-frame scaling loops, §10.6).

  • R. A. Fisher, “Frequency distribution of the values of the correlation coefficient in samples from an indefinitely large population”, Biometrika 10 (1915), 507-521 (the z-transformation on which the correction surfaces’ held-out half-set CC1/2 is compared).

  • R. C. Agarwal, “A new least-squares refinement technique based on the fast Fourier transform algorithm”, Acta Cryst. A34 (1978), 791-809 (the gradient of the refinement target, §15).

  • N. S. Pannu & R. J. Read, “Improved structure refinement through maximum likelihood”, Acta Cryst. A52 (1996), 659-668, and G. N. Murshudov, A. A. Vagin & E. J. Dodson, “Refinement of macromolecular structures by the maximum-likelihood method”, Acta Cryst. D53 (1997), 240-255 (the maximum-likelihood amplitude target and the B restraints, §15).

  • V. Y. Lunin & T. P. Skovoroda, “R-free likelihood-based estimates of errors for phases calculated from atomic models”, Acta Cryst. A51 (1995), 880-887 (the likelihood parameters from the free set, §15).

  • A. A. Vagin et al., “REFMAC5 dictionary: organization of prior chemical knowledge and guidelines for its use”, Acta Cryst. D60 (2004), 2184-2195 (the restraint dictionary, §15).

  • P. V. Afonine et al., “Towards automated crystallographic structure refinement with phenix.refine”, Acta Cryst. D68 (2012), 352-367 (the weight chosen among refinements by R-free, §15).

  • D. C. Liu & J. Nocedal, “On the limited memory BFGS method for large scale optimization”, Math. Program. 45 (1989), 503-528 (the minimiser, §15).

  • J. Nocedal, “Updating quasi-Newton matrices with limited storage”, Math. Comp. 35 (1980), 773-782 (the two-loop recursion of the minimiser, §15.6).

  • G. N. Murshudov, P. Skubák, A. A. Lebedev et al., “REFMAC5 for the refinement of macromolecular crystal structures”, Acta Cryst. D67 (2011), 355-367 (the likelihood’s D from the working set and its variance from the free, and the Kullback-Leibler B restraints, §15.3, §15.5).

  • P. Roversi, E. Blanc, S. Johnson & S. M. Lea, “Tetartohedral twinning could happen to you too”, Acta Cryst. D68 (2012), 418-424 (twin refinement with more than two domains, and the free set closed under the twin domains, §15.12).

  • K. A. Sultana, I. Alexeev, I. Kursula, P. Mäntsälä, J. Niemi & G. Schneider, “Structure determination by multiwavelength anomalous diffraction of aclacinomycin oxidoreductase: indications of multidomain pseudomerohedral twinning”, Acta Cryst. D63 (2007), 149-159 (a six-domain twin of a monoclinic crystal on a hexagonal metric, §15.12).

  • A. T. Brünger, M. Karplus & G. A. Petsko, “Crystallographic refinement by simulated annealing: application to crambin”, Acta Cryst. A45 (1989), 50-61 (the starting weight from the ratio of the gradients, §15.7).

  • P. J. Huber, “Robust estimation of a location parameter”, Ann. Math. Statist. 35 (1964), 73-101, and P. Charbonnier, L. Blanc-Féraud, G. Aubert & M. Barlaud, “Deterministic edge-preserving regularization in computed imaging”, IEEE Trans. Image Process. 6 (1997), 298-311 (the robust, pseudo-Huber scale fit of the refinement’s score, §15.3).

  • J.-S. Jiang & A. T. Brünger, “Protein hydration observed by X-ray diffraction”, J. Mol. Biol. 243 (1994), 100-115 (the flat bulk-solvent mask, §14.2, §15.3).

  • A. Blondel & M. Karplus, “New formulation for derivatives of torsion angles and improper torsion angles in molecular mechanics: elimination of singularities”, J. Comput. Chem. 17 (1996), 1132-1141 (the torsion derivatives, §15.5).

  • M. M. Harding, “Geometry of metal-ligand interactions in proteins”, Acta Cryst. D57 (2001), 401-411, and “Small revisions to predicted distances around metal sites in proteins”, Acta Cryst. D62 (2006), 678-682, and F. Leonarski, L. D’Ascenzo & P. Auffinger, “Mg2+ ions: do they bind to nucleobase nitrogens?”, Nucleic Acids Res. 45 (2017), 987-1004 (the metal-site distances, §15.5).

  • P. Emsley, B. Lohkamp, W. G. Scott & K. Cowtan, “Features and development of Coot”, Acta Cryst. D66 (2010), 486-501 (unmodelled blobs, §15.9).

  • M. Wojdyr, “GEMMI: A library for structural biology”, J. Open Source Softw. 7 (2022), 4200 (model / structure-factor / map machinery used in §14; the topology, riding hydrogens and blob search of §15).

  • J. P. Wright, “Experiences with GPU decompression for bitshuffle + LZ4 data”, HDF5 User Group meeting (2021), and github.com/jonwright/bslz4decoders (device-side decoding of bitshuffle+LZ4 images, §0).

  • A. Thorn & G. M. Sheldrick, “ANODE: anomalous and heavy-atom density calculation”, J. Appl. Cryst. 44 (2011), 1285-1287 (anomalous difference density read at the model’s sites).

  • R. Kahn, R. Fourme, A. Gadet, J. Janin, C. Dumas & D. Andre, “Macromolecular crystallography with synchrotron radiation: photographic data collection and polarization correction”, J. Appl. Cryst. 15 (1982), 330-337 (the azimuthal polarization factor of §2.2, applied to the azimuthal profile, the Bragg intensities and the ring background the beam-stop shadow test compares against).

  • R. J. Read, “Improved Fourier coefficients for maps using phases from partial structures with errors”, Acta Cryst. A42 (1986), 140-149 (the sigma_A formalism and the m, D weighting of the map coefficients of §14.4).

  • A. Fokine & A. Urzhumtsev, “Flat bulk-solvent model: obtaining optimal parameters”, Acta Cryst. D58 (2002), 1387-1392 (the flat bulk-solvent model, its optimal parameters and the range they are physically meaningful over, used when scaling a model to the data in §14).

  • P. V. Afonine, R. W. Grosse-Kunstleve & P. D. Adams, “A robust bulk-solvent correction and anisotropic scaling procedure”, Acta Cryst. D61 (2005), 850-855 (the grid search over that range that fits k_sol and b_sol, with the overall scale and anisotropic B refitted at each grid point).

  • K. Shoemake, “Uniform Random Rotations”, in Graphics Gems III, ed. D. Kirk, Academic Press (1992), 124-132 (the uniform random rotations the model-fit null of §14.5 is built from).

  • G. H. Golub & V. Pereyra, “The differentiation of pseudo-inverses and nonlinear least squares problems whose variables separate”, SIAM J. Numer. Anal. 10 (1973), 413-432, and L. Kaufman, “A variable projection method for solving separable nonlinear least squares problems”, BIT 15 (1975), 49-57 (the scale re-fit folded into the rigid-body Jacobian of §14.8).

  • Z. Otwinowski & W. Minor, “Processing of X-ray diffraction data collected in oscillation mode”, Methods Enzymol. 276 (1997), 307-326 (reweighted, de-biased profile-fit variances).

  • G. Winter et al., “DIALS: implementation and evaluation of a new integration package”, Acta Cryst. D74 (2018), 85-97, and J. Beilsten-Edmands et al., Acta Cryst. D76 (2020), 385-399 (CC1/2 resolution cutoff, merge outlier rejection, scaling error model).

  • R. H. Blessing, “An empirical correction for absorption anisotropy”, Acta Cryst. A51 (1995), 33-38 (absorption as spherical harmonics of the beam directions).

  • P. Evans, “Scaling and assessment of data quality”, Acta Cryst. D62 (2006), 72-82, and P. R. Evans, Acta Cryst. D67 (2011), 282-292 (POINTLESS: operator-by-operator point-group scoring, and the axial-zone screw-absence test).

  • A. G. W. Leslie & H. R. Powell, “Processing diffraction data with MOSFLM” (2007), NATO Science Series II 245, 41-51 (post-refinement practice: what is refined per image and what over a wedge).

  • D. W. Moreau, H. Atakisi & R. E. Thorne, “Ice in biomolecular cryocrystallography”, Acta Cryst. D77 (2021), 540-554 (measured hexagonal-ice ring positions, used by the ice-ring score, the ice flagging and the ice calibrant).

  • K. Röttger, A. Endriss, J. Ihringer, S. Doyle & W. F. Kuhs, “Lattice constants and thermal expansion of H2O and D2O ice Ih between 10 and 265 K”, Acta Cryst. B50 (1994), 644-648 (the ice Ih cell the ring positions below 1.522 Å are calculated from).

  • S. Sheriff & W. A. Hendrickson, “Description of overall anisotropy in diffraction from macromolecular crystals”, Acta Cryst. A43 (1987), 118-121 (the overall anisotropic B tensor and its symmetry constraints), and A. N. Popov & G. P. Bourenkov, “Choice of data-collection parameters based on statistic modelling”, Acta Cryst. D59 (2003), 1145-1153 (the sigma-aware estimation of the anisotropy of the observed intensity distribution, part of that paper’s statistic modelling).

  • I. J. Tickle, C. Flensburg, P. Keller, W. Paciorek, A. Sharff, C. Vonrhein & G. Bricogne, STARANISO (2016), Global Phasing Ltd, staraniso.globalphasing.org (the inspiration for analysing and reporting diffraction anisotropy on every run, §13.5).

  • C. Vonrhein, C. Flensburg, P. Keller et al., “Data processing and analysis with the autoPROC toolbox”, Acta Cryst. D67 (2011), 293-302 (the inspiration for not trusting header geometry and for finding the beam centre from the images, §1.4).

  • P. R. Evans & G. N. Murshudov, “How good are my data and what is the resolution?”, Acta Cryst. D69 (2013), 1204-1214 (AIMLESS: the anisotropic deltaB as the range of the principal components, and diffraction limits from a cone about each principal direction).

  • G. Assmann, W. Brehm & K. Diederichs, “Identification of rogue datasets in serial crystallography”, J. Appl. Cryst. 49 (2016), 1021-1028, and G. M. Assmann, M. Wang & K. Diederichs, Acta Cryst. D76 (2020), 636-652 (XDSCC12: sigma-tau CC1/2, delta-CC1/2, the Fisher transformation and the rejection discipline the frame disposition follows).

  • W. Brehm & K. Diederichs, “Breaking the indexing ambiguity in serial crystallography”, Acta Cryst. D70 (2014), 101-109 (serial stills without a reference: each crystal put into the indexing in which it agrees best with all the others).

  • K. Diederichs & P. A. Karplus, Nat. Struct. Biol. 4 (1997), 269-275, and P. A. Karplus & K. Diederichs, Science 336 (2012), 1030-1033 (R_meas / R_pim, CC1/2 and CC*).

  • M. S. Weiss, “Global indicators of X-ray data quality”, J. Appl. Cryst. 34 (2001), 130-135 (R_pim).

  • IUCr Commission on Crystallographic Nomenclature, “Statistical descriptors in crystallography”, Acta Cryst. A45 (1989), 63-75, and Acta Cryst. A51 (1995), 565-569 (uncertainty conventions).

  • J. Navaza, “AMoRe: an automated package for molecular replacement”, Acta Cryst. A50 (1994), 157-163 (the rotation function on an interpolated molecular transform, §14.10).

  • R. A. Crowther & D. M. Blow, “A method of positioning a known molecule in an unknown crystal structure”, Acta Cryst. 23 (1967), 544-548 (the full-symmetry translation function, §14.10).

  • B. W. Matthews, “Solvent content of protein crystals”, J. Mol. Biol. 33 (1968), 491-497, and K. A. Kantardjieff & B. Rupp, “Matthews coefficient probabilities”, Protein Sci. 12 (2003), 1865-1871 (how many copies the cell holds, §14.10).

  • R. J. Read, “Pushing the boundaries of molecular replacement with maximum likelihood”, Acta Cryst. D57 (2001), 1373-1382; A. J. McCoy, R. W. Grosse-Kunstleve, L. C. Storoni & R. J. Read, “Likelihood-enhanced fast translation functions”, Acta Cryst. D61 (2005), 458-464; A. J. McCoy et al., “Phaser crystallographic software”, J. Appl. Cryst. 40 (2007), 658-674; A. J. McCoy et al., Proc. Natl. Acad. Sci. USA 114 (2017), 3637-3641 (the likelihood target, the solution criterion and the expected gain of molecular replacement, §14.10).

  • R. D. Oeffner, T. Croll, C. Millán et al., “Putting AlphaFold models to work with phenix.process_predicted_model and ISOLDE”, Acta Cryst. D78 (2022), 1303-1314, and J. Jumper et al., “Highly accurate protein structure prediction with AlphaFold”, Nature 596 (2021), 583-589 (preparing a predicted model for molecular replacement, §14.10).

  • E. A. Cornish & R. A. Fisher, “Moments and cumulants in the specification of distributions”, Rev. Int. Stat. Inst. 5 (1938), 307-320 (the Poisson quantile of the adaptive spot-finding threshold beyond the summation limit).

  • R. W. Grosse-Kunstleve, “Algorithms for deriving crystallographic space-group information”, Acta Cryst. A55 (1999), 383-395 (from Le Page’s two-folds to a conventional cell, centring and change of basis, §13.1).

  • T. C. Huang, H. Toraya, T. N. Blanton & Y. Wu, “X-ray powder diffraction analysis of silver behenate, a possible low-angle diffraction standard”, J. Appl. Cryst. 26 (1993), 180-184 (the silver behenate calibrant cell, §7.6).

  • P. Trueb, C. Dejoie, M. Kobas et al., “Bunch mode specific rate corrections for PILATUS3 detectors”, J. Synchrotron Rad. 22 (2015), 701-707 (the count-rate correction clips an over-range pixel to the cutoff, §1.7).

  • D. Liebschner, P. V. Afonine, M. L. Baker et al., “Macromolecular structure determination using X-rays, neutrons and electrons: recent developments in Phenix”, Acta Cryst. D75 (2019), 861-877 (phenix.xtriage, the model of the twinning test, §13.2).

  • V. Luzzati, “Traitement statistique des erreurs dans la détermination des structures cristallines”, Acta Cryst. 5 (1952), 802-810 (the fall-off of \(\sigma_A\) with resolution for a model’s coordinate error, Luzzati’s \(D\), in the likelihood of a placement, §14.10).

  • D. Liebschner, P. V. Afonine, A. G. Urzhumtsev & P. D. Adams, “Implementation of the riding hydrogen model in CCTBX to support the next generation of X-ray and neutron joint refinement in Phenix”, Methods Enzymol. 634 (2020), 177-199 (the riding hydrogens, placed by GEMMI’s code, §15.2).

  • D. L. Theobald, “Rapid calculation of RMSDs using a quaternion-based characteristic polynomial”, Acta Cryst. A61 (2005), 478-480, and P. Liu, D. K. Agrafiotis & D. L. Theobald, J. Comput. Chem. 31 (2010), 1561-1563 (the QCP superposition behind the NCS rms criterion, via GEMMI, §15.5).

  • S. S. Oren & D. G. Luenberger, “Self-scaling variable metric (SSVM) algorithms. Part I”, Management Sci. 20 (1974), 845-862, and D. F. Shanno & K.-H. Phua, “Matrix conditioning and nonlinear optimization”, Math. Program. 14 (1978), 149-160 (the rescaling of the L-BFGS initial inverse Hessian by the latest pair, §15.6).

(list is not exhaustive; the full citations, with DOIs, are in ACKNOWLEDGEMENT.md)

\ No newline at end of file diff --git a/CPU_DATA_ANALYSIS_DECISIONS.html b/CPU_DATA_ANALYSIS_DECISIONS.html new file mode 100644 index 000000000..257a6d42f --- /dev/null +++ b/CPU_DATA_ANALYSIS_DECISIONS.html @@ -0,0 +1 @@ + Data analysis: space group and validation (§13–§14) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Data analysis: space group and validation (§13–§14)

Part of the CPU/GPU data-analysis reference; the section numbers are continuous across its parts.

13. Space-group determination and merge-level decisions

13.1 Space-group determination

When no space group is supplied, a POINTLESS-like search scores Laue-group symmetry (CC of \(E^2(h)\) vs \(E^2(Rh)\) — the intensities normalised by the mean of their own resolution shell — plus merge self-consistency) and detects screw/centering absences from the \(P1\)-merged intensities. Three tests weigh a promotion to higher symmetry, all aimed at the merohedral twin, whose twin law forces non-equivalent reflections together and so mimics symmetry:

  1. Merge self-consistency (\(\chi^2\) under the candidate group, relative to the confirmed subgroup). On its own this is not sufficient: it is a ratio to an error model that moves with the amount of data — the parent’s systematic term grows as \(\sigma\) shrinks with \(1/\sqrt{N}\), while a twin’s is already saturated — so its verdict depends on how much data the search saw.

  2. Error-model \(b\) (the intensity-proportional systematic). A genuine symmetry step gains multiplicity without inflating \(b\); merging a twin law’s extra operator inflates it. This is a rescue and never a veto: a \(\chi^2\)-borderline promotion whose \(b\) stays close to the confirmed subgroup’s is confirmed on it, which is what recovers a genuine high-symmetry group on imperfectly-scaled data, but it cannot demote a promotion that passed. The veto it once carried was removed. It was guarded by “\(H\) could not be computed”, so it could only ever act where the one statistic that discriminates here is blind, and what it compared there was not a measurement but the error-model bisection’s own ceiling — which made a space group depend on the compiler flags, the same source refusing a correct \(P2_12_12_1\) in one build and not in the other. No bound repairs it: genuine promotions have since been measured up to 5.8 where the bound was calibrated at 1.62 against a twin at 2.1, so the two populations have swapped sides. The case it was meant to catch — a merohedral twin too sparse for \(H\) — is answered below it by the added-operator \(R\) gate, whose reference is the global best rather than the parent.

  3. Operator disagreement, a sigma-free statistic \(H=\mathrm{median}\,|I_1-I_2|/(I_1+I_2)\), formed as the ratio of the operators a promotion adds to the parent’s own, measured on the same reflections. Normalising against the parent divides out the systematic floor that symmetry mates carry on real data, which varies by crystal and by operator; a median is used because a twin perturbs every pair whereas a badly-measured minority perturbs only the tail. Where a candidate has several parents of the same order, it is judged against the worst of them, since a rival subgroup can itself contain the twin laws.

The correlation is on resolution-normalised intensity \(E^2 = I/\langle I\rangle(\text{shell})\), normalised over exactly the reflections the correlation pairs. Both members of a symmetry pair lie at the same \(|s|\), so on raw \(I\) the resolution fall-off is variance shared perfectly between the two arms and appears as a positive correlation for any pairing at all: a shell-matched random pairing — the exact null for a metrically-allowed false operator — scores a median 0.31 across the rotation battery, and on one crystal 0.53 — above the bound the correlation is tested against. That floor varies more from crystal to crystal (spread 0.46) than the whole true/false gap is wide (0.38), so an absolute bound on the raw statistic is a different test on every crystal; and it moves with the search resolution cut, which is what made that cut a symmetry-deciding parameter. Normalised, the floor has a median of 0.015, never exceeds 0.06, and barely moves with the cut.

Both the correlation stage and the absence tests need to know whether a reflection is genuinely present, and that question is asked of its counting significance, not of the merged \(I/\sigma\). A merged \(\sigma\) carries the error model’s intensity-proportional term, \(\sigma^2 = a\,\sigma_0^2 + (b\,I)^2\), so merged \(I/\sigma\) saturates — at \(\mathrm{ISa}\sqrt{n}\) for a reflection observed \(n\) times, and at \(\mathrm{ISa}\) exactly for one observed once. Above that knee it stops rising with the intensity: on the weakest search merge of the rotation battery the \(I/\sigma\) of every decile of \(E^2\) reads 1.58–1.65 against an \(\mathrm{ISa}\) of 1.70, so reflections an order of magnitude apart in real intensity report the same number. A single constant applied there demands anywhere between 2.2 and 11.9 in counting significance depending on the crystal.

The nominal cut \(T\) (default 3.0) is therefore converted once, using the ISa of the merge being searched. For a reflection observed once \(\sigma_\text{counting}^2 = \sigma^2 - (b\,I)^2\), so \(I/\sigma_\text{counting} \ge T\) is exactly

\[\frac{I}{\sigma} \;\ge\; \frac{T}{\sqrt{1 + (T/\mathrm{ISa})^2}}\]

The converted cut lies strictly below \(\mathrm{ISa}\) for every \(\mathrm{ISa}\), so it is always reachable by the reflection the ceiling binds hardest, and it is within 1 % of \(T\) on any merge with \(\mathrm{ISa} \ge 21\) — a healthy merge is left exactly where it was. Multiplicity is taken as 1 deliberately rather than estimated, for the same reason. Where the merge reports no ISa (or \(b = 0\)) the cut is used as it stands.

The candidates are enumerated in every setting the refined cell can host, not only in the settings the International Tables call the reference one. A setting is a statement about direction — \(P112_1\) puts its \(2_1\) on \(c\) where \(P12_11\) puts it on \(b\), and both are space group 4 — so a search restricted to reference settings can only ever put a screw or a centring on the axis the convention chose, whatever the data say. Two things bound the widened set. The cell’s own metric is asked once, when a point group’s rotation set is chosen — a set whose rotations it does not host (\(\alpha=\beta=90^\circ\) for a \(2\)-fold on \(c\)) is not offered — and every setting of a chosen set is then offered without asking again, because a cell refined free after integration sits a few tenths of a degree off \(90^\circ\) and asking per setting kept only the reference one; and a candidate predicting exactly the absences another candidate already predicts is dropped as the same hypothesis under a second name. A non-reference setting is additionally refused when its centring class holds no reflection in this merge, since there is then nothing to confirm it with. Because the candidates of a point group all share its rotations, this cannot raise the symmetry: it decides which axes carry the screws and the centring, never how many operators there are. The setting found this way is the one the decisions are made in. The files are then written in the ITA standard setting (as XDS and POINTLESS write it: \(P2_12_12\) with the pure axis on \(c\) and \(a<b\), monoclinic \(b\)-unique and \(C\)-centred with \(\beta\ge 90^\circ\), the other orthorhombic groups \(a\le b\le c\), triclinic reduced), or in the one the user supplied — a reference MTZ, a model that fits, the axis order of -C, a non-standard -S symbol, in that priority. That is an integer, determinant \(+1\) change of basis applied after every decision, to the merged and unmerged files and the _process.h5 alike, and reported as SETTING_OPERATOR; where the written group is not the reference setting (because the user asked for another) the report and the files name it by its full Hermann–Mauguin symbol. A group given with -S is placed on the axes its absences name before the merge: every change of basis that keeps its metric and centring is a candidate, each class of axial and zonal reflections some candidate predicts absent is read as the ratio of its mean \(I/\sigma\) to that of the reflections none predicts absent, and the candidate that calls absent the classes that read weak and present the ones that read strong wins.

Several space groups may be indistinguishable on the measured data. Where they are, the search scores them identically and all of them are named in the result rather than one being reported as the answer: some are enantiomorph pairs, which merged intensities cannot distinguish in principle, others differ only by a screw condition that the centering condition already implies, so the screw has no observable signature at all, and others differ only on a zone the sweep never measured. Equality is keyed on the measured absence evidence, not on a count of predicted absences — two settings of one point group routinely predict a different number of absences on an unmeasured zone, which argues nothing either way. Among the tied candidates, where at least one axial zone was judged, the representative is the one claiming a screw on the rows this merge holds no control class for — a stated prior, not a measurement: a crystal that has already shown one screw is the group carrying the rest an order of magnitude more often than not, and a sweep short of half a turn routinely records one axial row and not the next. Centring-driven axial conditions do not count towards the claim, so a centred group and its screw partner still tie. What remains tied is represented by the lowest space-group number, which is a convention and not a measurement.

Glide planes are detected the same way screws are, from the zone they extinguish: a glide removes half of a whole zone (\(h0l\) with \(h+l\) odd for an \(n\) glide perpendicular to \(\mathbf{b}\), and so on), and the extinguished class is scored against the rest of its own plane, as POINTLESS scores zonal absences. The statistic is per reflection rather than the zone’s sum — a plane holds hundreds to thousands of reflections where an axial row holds tens, so a summed statistic reaches enormous values on a class that is merely a few times weak, where per reflection the false and the genuine zones separate cleanly — and a zone that cannot be measured refuses its candidate rather than abstaining, because a glide is an extra claim on top of a group that already fits without it. Candidates whose glides share a plane and differ only in the translation (the \(c\) and the \(n\) of the same plane) are one zone, keyed by the rotation part of the improper operator, not two scored twice. A Sohncke group has no improper operator at all, so on chiral data the zone loop never runs and every Sohncke candidate scores exactly what it scored before. Both readings are reported on every searched run — SPACE_GROUP_NAME= carries the glide where one was found, and SOHNCKE_SPACE_GROUP= the best group without — because a crystal of chiral molecules cannot have a glide plane, and a reader who knows the sample is a protein must be able to read the Sohncke answer without processing the images again. Non-Sohncke candidates are enumerated by Laue class, so the groups without a centre of symmetry (Pc, Pna2_1, I-42d, Fdd2) are candidates as well as the centrosymmetric ones; a candidate is enumerated only where its absences differ from a Sohncke candidate’s, because an inversion centre or a mirror alone predicts exactly what the Sohncke subgroup predicts. A centre of symmetry is then settled by the absences where they can settle it: no group without a centre predicts the absences of P2_1/c, Pbca or Ia-3d, and no centrosymmetric group those of I-42d or Fdd2. Where two non-Sohncke groups predict the same absences (C2/c and Cc, Pnma and Pna2_1, I4_1md and I-42d) they are reported as alternatives these data cannot separate (SPACE_GROUP_CENTRE=NOT_DETERMINED), and the centrosymmetric one is written by default — a missed centre is the common error in small-molecule space-group assignment (Baur & Kassner 1992). That default gives way only when the intensity distribution of the general reflections reads acentric on <|L|>, <|E²-1|> and N(0.1), each calibrated against acentric and centric intensities simulated with the reflections’ own sigmas, every reading lies in the range a Wilson population can produce, the reflections centric in both groups read centric, and the lattice excludes twinning (the metric admits no rotation beyond the Laue class and no twin-domain lattice was found), because a twinned centrosymmetric crystal reads exactly like an untwinned acentric one. Between two groups without a centre, the lowest-numbered is written.

The Lorentz factor \(\zeta\) (§8.3) governs how well a reflection can be measured, so when the spindle lies in a plane of the lattice, an operator permuting the two in-plane axes samples a different mixture of measurement qualities than one that only flips signs. The search is therefore run a second time on a merge of only the well-measured observations (--search-min-zeta, rotation default 0.85), both answers are reported, and where they disagree the merge of all the observations decides. The filter discards 40–80 % of the observations, which can starve an operator correlation the full merge confirms and can equally leave an operator confirmed that the full merge refuses, so the decision — the point group as well as the absences, which live in the weak reflections the filter removes — rests on the arm with every observation behind it. A tie (same order, different symmetry) is reported with both candidates named, for trying in molecular replacement.

Both search merges are cut in resolution where the data stop carrying signal: the shell means of \(\langle I/\sigma\rangle\) are given their best non-increasing fit (pool-adjacent-violators, weighted by shell size) and the cut is where the fit drops under 1. Cutting at the first single shell to dip under 1 made the cut a coin toss on a merge whose \(\langle I/\sigma\rangle\) is flat near 1: one crystal was cut at 0.85 Å or 1.19 Å depending on the compiler flags, and the coarser cut left its glide zones too few absences to be judged. The fit moves only as much as its input does, and on a profile that already falls monotonically the cut is unchanged.

Both search merges also drop the frames whose fitted per-frame scale came out below a tenth of the run median — the stretches where the crystal was barely in the beam. The scale enters as \(1/G\), so such a frame’s intensities arrive amplified tenfold or more, with their \(\sigma\) amplified by the identical factor and the scale’s own error nowhere in it; the production merge survives that because a reflection in the determined symmetry is measured ten or twenty times and --reject-outliers removes the amplified observation, but the search merges in \(P1\), where a reflection has two or three observations and no majority exists to call any of them an outlier. On a crystal that repeatedly left the beam over a full turn this cost the \(422\) point group outright, its operators reading \(0.08\)–\(0.38\) on a merge that gives \(\mathrm{CC}_{1/2} = 96\,\%\) in that same point group once it is assumed. Like the \(\zeta\) filter, this is a filter of the search passes alone — the production merge keeps every frame.

Screw axes are scored per axial zone, not pooled over them. The conditions on \(h00\), \(0k0\) and \(00l\) are independent, so their log-likelihoods add, and a zone that was never measured is allowed to abstain rather than to argue: pooling let one unmeasured row veto a confirmed one, and it read three genuine screws as weaker than two whenever the third row was shallow. A screw is claimed when its absence evidence reaches 8 nats. The bound is set on the zones themselves, every single-axis candidate of a battery of rotation datasets labelled against the deposited group: a false zone with no violation reads at most +4 nats, a true one from +10, and the true zones below the former bound of 20 were all short rows — a \(2_1\) along a monoclinic axis of 25–30 Å reaches four to six odd reflections inside the search’s resolution range, which on weak data sit at a few per cent of their row rather than at zero. Two absences clear the bound if both read below about 2 % of their row.

A pseudo-translation is divided out before an axial absence is judged. A translational pseudo-symmetry (§13.2) splits the reflections into two classes by the parity of the index along the translation, one systematically strong and the other systematically weak. Where the translation is half-integer along an axis, those two classes are exactly the absent class and the control class of a screw on that same axis, so the absence test would divide one by the other and pay the suppression twice — reading a class that is present but suppressed as extinct, and buying a screw the crystal does not have. The modulation is therefore measured along each axis from the intensities themselves — per axis, not pooled, since one row can be strongly modulated while its neighbours are not — and divided out of both the absence evidence and the violation count before the screw is scored. Only order-two screws are treated this way; a three-fold with a one-third translation is left unanswered rather than answered no.

The violation count can be deferred to the absences, one zone at a time. A screw candidate is refused when too many of its predicted-absent reflections read as present — but on a strong axial row near the spindle those readings need not be structure factors at all: the same reflection can read far positive at one Ewald crossing and negative at the other, the directional smear tail of the strong reflections beside it. A zone whose per-reflection absence evidence clears the claim bar may therefore stand despite its count, since the likelihood has already priced those reflections in and still reads the class as extinct. The deferral is licensed zone by zone — the evidence is a group-level number while the count indicts particular zones, so an overwhelming genuine zone must not pay another zone’s debts — and it is not available on a zone corrected for a measured pseudo-translation, where the corrected count is the one instrument the modulation does not reach.

Centering is accepted when the systematically-absent class is weak relative to the present one by either of two floor-independent tests: its mean signed \(I/\sigma\) well below the present mean, or its rate of individually-significant reflections well below the present class’s own significant rate. The second test covers weak and low-energy data, where a positive intensity floor (background and profile leakage) lifts the absent class’s mean \(I/\sigma\) well above zero and, when the present class is itself weak, carries the plain mean ratio past its bound; a false centering fails both tests, its absent class being as strong as the present one. When several centerings pass they are ranked by a Beta-tail likelihood rather than by a count of net absences: a count lets a centering that extinguishes many more reflections out-rank one that violates far fewer, and the likelihood weighs the violations against the class each belongs to instead. The acceptance bounds above are unchanged by that ranking.

A confirmed promotion that is refused is decided by the twin-immune zone of its added operators, and only where that is undecided by merging under it. The zone (§13.2) is the one reading that does not depend on the per-frame scales or on a reference operator: read on the all-observation P1 merge where the two search arms disagree, and on the adopted group’s own merge at the remerge, an index-2 promotion whose calibrated zone evidence is acentric by 20 nats stays refused — on all observations, and the first added operator is recorded as the twin law — and one whose zone is centric by 20 nats is taken. Where the zone cannot decide (a higher index, no zone reflections in the shells with signal, within the margin, or an acentric control more compressed than a perfect twin’s 0.541 — something other than a twin, the overlapping spots of a long axis, then compresses the zone too and a genuine one reads acentric), the merge is asked. Every gate that refuses a confirmed higher point group is a ratio — the added operators’ disagreement against the parent’s, or their \(R\) against the best-agreeing operator anywhere — and both references are properties of how the crystal was mounted rather than of its symmetry. A 2-fold within a degree of the spindle records its mates on the same detector pixel half a turn later, so it carries no geometry-dependent systematic at all, and by being that clean it makes every other operator look bad against it; the best-agreeing operator can also be one of the operators under test, which collapses the ratio on worse data and raises it on better. So where a promotion is confirmed and then refused, the merge is asked instead of the ratio. Both groups are scaled and merged over one pinned resolution range — the adopted group’s own cut — and the promotion is taken only if neither \(R_\mathrm{meas}\) nor ISa gets worse. \(R_\mathrm{meas}\) is multiplicity-corrected, so folding non-equivalent reflections together has to inflate it, and the error model is refitted per merge, so ISa says whether the extra multiplicity was bought with systematic disagreement. \(CC_{1/2}\) and \(\langle I/\sigma\rangle\) cannot arbitrate this: both rise on a false promotion too. Two details the comparison turns on: the refused point group’s representative is primitive and symmorphic, so the arm merged under it takes the adopted group’s centring — merged in the bare representative, a centred crystal is handed its centring-absent class as data, which inverts the decision — and the absence stage is asked of the adopted merge, so both arms carry the same absence classes and differ by the added rotations alone. That merge no longer holds the adopted group’s screw-absent axial reflections, so the higher group also keeps the screws the adopted group decided — among the higher candidates the merge cannot separate, the one that predicts every such axial absence is taken — rather than the lowest-numbered one, which claims none. The cost is two extra merges, and only on a run that records a refusal, which is a few in a hundred.

On a merge that reads twinned, the search asks the zone itself. A twin of an index-2 subgroup by exactly the operators a promotion adds defeats every agreement gate once its fraction is high — the added operators then agree like real ones — so where the P1 merge’s \(\langle|L|\rangle\) lies in the partial-twin band (0.375 to 0.44), the candidate is refused when the twin-immune zone of one of its index-2 subgroups reads acentric by 20 nats. That holds for a candidate that is the whole symmetry of its lattice too: the subgroup’s twin law is one of the candidate’s own operators, so a crystal in 4 twinned by \(k,h,\bar{l}\) is exactly such a twin of 422. Below 0.375 something other than a twin compresses the intensities, the zones with them, and they are not read. A \(P3_1\) crystal twinned at \(\alpha \ge 0.4\) by its 321 law, whose 32 promotion every agreement gate passed, reads −230 nats there; a body-centred crystal in 4 twinned at about 0.3, promoted to 422 at an \(H\) ratio of 1.51, −58 nats. Between two candidates of the same order the one whose own two-folds carry screw absences is preferred, but an axial row whose odd class a lattice centring extinguishes is not counted where the merge reads that centring in its general reflections: on a body-centred crystal every principal row reads extinct whatever the two-folds are, which would hand 222 the tie over 4.

A point group’s own operators must agree with each other. A point group is the claim that all of its operators are symmetries of one crystal, and a mixture of real and false operators has a specific shape: the real ones form a subgroup — the true group’s intersection with the candidate — and everything outside it is false. The gate therefore reads the operators sorted by their \(R\) against the merge, finds every prefix that closes into a subgroup, and takes the largest factor by which every operator outside such a subgroup reads worse than every operator inside it; above 3.2 the candidate is refused. A genuine group whose operators merely spread over a continuum — anisotropic systematic error spreads a cubic crystal’s operators twofold — has no such gap. The earlier form, worst-agreeing over best-agreeing operator, divided by an extreme order statistic and refused a genuine \(432\) as soon as one of its operators happened to agree unusually well.

A group that holds every rotation of its lattice is refused when merging under it narrows the L-test like a twin. Every gate above compares the added operators with a reference, and a pseudo-symmetric structure or a twin defeats them all. For a candidate that holds every rotation its lattice admits no twin law exists, so intensities merged under it that read like a twin’s are not a twin. The Padilla–Yeates \(L\)-test is read twice on the same pairs of the \(P1\) merge — as measured, and with every intensity replaced by the mean of its orbit under the candidate — and the candidate is refused where the merged \(\langle|L| angle\) reads twin-like (\(0.375 \le \langle|L| angle < 0.44\)) and the averaging closed a third or more of the gap from the unmerged value to 0.375. Genuine lattice-holohedral groups close 0.01–0.25 of it. A merge reading below 0.375 is not read: nothing a twin or a false operator does reaches that, so something else compresses the intensities.

The lattice class is re-asked where the metric knows more. The Bravais class comes from Niggli reduction and a lattice-character lookup (§6), and that lookup can land short of the truth or beside it: near the Niggli type-I/type-II boundary it is decided by the last digits of the refined cell, and a lattice that is nearly but not exactly hexagonal matches the hexagonal character even when no point group that class can host carries the two-folds the data actually have. Two recoveries run, both settled by the intensities. Every rotation the cell metric can host beyond the named class — read off Le Page’s two-fold search on the lattice itself, which measures each rotation’s obliquity in a primitive basis and owes nothing to the character table — is put to the intensities as a single operator, scored exactly as the search scores its own operators, on the same reflection population and the same \(E^2\) normalisation. And where the metric group is larger than the adopted class’s holohedry, the merge is reindexed into the metric group’s conventional cell and the space-group search is run again there, with every gate live; the reindex is committed only where the search in the new setting confirms a strictly higher point group and the centring the new cell describes, so a pseudo-symmetric metric leaves the answer already in hand standing. The same bound governs the test for a centred lattice that runs after a triclinic indexing: its candidate class comes from the character table, which names a class on looser tolerances, so the test runs only where Le Page finds every rotation of that class’s holohedry within the run’s obliquity bound. Otherwise the intensities could confirm only a pseudo-symmetry the lattice does not host, and the question is left to the Le Page re-ask.

13.2 Twinning check, and translational pseudo-symmetry

A Padilla–Yeates \(L\)-test (\(\langle|L|\rangle\), \(\langle L^2\rangle\) — 0.500 and 0.333 untwinned, 0.375 and 0.200 for a perfect twin) and the second moment \(\langle I^2\rangle/\langle I\rangle^2\) (2.0 for untwinned acentric data, 1.5 for a perfect twin) are written to the merged mmCIF as a twinning diagnostic. Both are taken on intensities divided by their resolution-shell mean, over the shells whose intensities are measured (at least 85% of a shell’s reflections at \(I/\sigma > 3\), phenix.xtriage’s cut for its twin tests; noise pulls \(\langle|L|\rangle\) below 0.5 like a twin does), with Wilson outliers rejected; the \(L\)-test pairs are therefore compared on one scale even where two index steps span a steep fall-off, as in phenix.xtriage and ctruncate, and the selection is by shell, never by the individual reflection’s \(I/\sigma\), which would cut the weak tail and bias \(\langle|L|\rangle\) down. The twin fraction is quoted from the statistic that carries the verdict — the \(L\)-test unless the call rests on the second moment alone — and a second moment is not turned into a fraction under a detected pseudo-translation, which inflates it. A twin law exists only where the lattice has a rotation the group lacks, so whether one is possible is read off the cell, not off the name of the Laue class: the lattice’s two-folds are found as for the free set (Le Page, within 3° obliquity — GEMMI’s find_twin_laws), and where none lies outside the group no twin is called. That covers the holohedral classes (\(4/mmm\) on a tetragonal lattice, \(6/mmm\), \(m\bar{3}m\), \(\bar{3}m\) on a rhombohedral one) and equally \(mmm\) or \(2/m\) on a lattice with no special metric, while a pseudo-merohedral \(2/m\) or \(mmm\) lattice — a monoclinic \(\beta\) near 90°, a C-centred cell with \(b \approx a\sqrt{3}\) — admits a law and stays eligible. The \(L\)-test is still read where no law is possible, for a different question: merging \(I(h)\) with \(I(Th)\) under a false operator \(T\) gives \((I(h)+I(Th))/2\) whatever the twin fraction, which has the perfect-twin distribution, so \(\langle|L|\rangle\) below 0.42 there is reported as an adopted operator averaging unequal intensities — the space group is too high, or a twin law was absorbed into the point group — a warning, never a change to the space group. A genuine operator leaves the untwinned 0.5. Reflections that overlap along a very long axis narrow the distribution the same way, which is one reason it stays a warning. The same numbers measured on the P1 merge the space-group search was given, before any point group was adopted, are reported beside them (_BEFORE_SEARCH), with that merge’s own pseudo-translation declared and the reflections its lattice centring extinguishes left out. Between that bar and the twin band’s 0.44 the verdict is NO_TWIN_LAW: the intensities read twin-like, but the lattice admits no law for the group, so they are not a twin in it — the group may be too high (a subgroup’s twin law absorbed, or non-crystallographic symmetry taken for real), or something other than twinning narrowed the distribution. It is reported as such rather than as a twin that “needs a twin law” no refinement program could be given.

The twin hypothesis. Where the adopted group may have absorbed a twin law — a twin gate of the search refused it and was overruled (§13.1), or a group above \(P1\) was adopted on a merge that read twin-like before the search — the same observations are also merged in a subgroup and written beside the answer as <prefix>_twin_<SG>.mtz / .cif, in the subgroup’s standard setting, to the answer’s resolution and with the answer’s free set (each reflection takes the flag of the reflection of the answer’s merge its orbit falls in, so twin mates share it). The subgroup is the one a decision named — the group a refused promotion was adopted over, or the indexed lattice’s group a metric re-ask promoted from — and otherwise, among the index-2 subgroups of the adopted group that the search confirmed as point-group finalists, the one whose lost two-fold agrees worst with the intensities (lowest operator CC): the most likely twin law. One file is written; the other subgroups that qualified are named in the report. The law is in the mmCIF’s _pdbx_reflns_twin with its fraction, from Yeates’ \(H\) on the pairs it relates in the subgroup merge — \(H = |I(h)-I(Th)|/(I(h)+I(Th))\) is uniform on \([0, 1-2\alpha]\), so \(\alpha = 1/2 - \mathrm{median}\,H\), a lower bound since measurement error only adds to \(H\). Nothing the answer is made of depends on it: it is a second merge from the same scaled observations, and the answer’s files are byte for byte what they are without it. Refinement programs want twinned data merged in the true lower group, never detwinned, which is why the file is the merge and not a correction of the answer; a near-perfect twin of a subgroup and the higher group predict the same intensities, so which of the two is the crystal is a question for a model (§14.9).

Beside them, on rotation data with --finalist-ledger, the run reports twin-immune zone evidence for the operators the adopted point group adds over each of its index-2 subgroups, read on a full-resolution merge of the observations in P1 that the option makes for the purpose. Under a twin law \(T\), \(I_\mathrm{obs}(h)=(1-\alpha)I(h)+\alpha I(Th)\); a reflection whose twin mate is itself up to the subgroup and Friedel is untouched at every \(\alpha\), and those are exactly the reflections centric in the group but acentric in the subgroup. They read centric (\(\langle|E^2-1|\rangle = 0.968\)) if the added operators are real and acentric (0.736) if they are a twin law or a pseudo-symmetry — the one intensity statistic that still separates the two at \(\alpha = 0.5\), where every operator statistic reads “real”. Each zone is normalised against its own mean in resolution bins (and within the two phase classes of a detected pseudo-translation), read only in shells with \(\langle I/\sigma\rangle \ge 5\) because noise inflates every class towards centric, and reported with \(n\), a standard error and the centric-over-acentric Wilson log-likelihood ratio in nats (both densities convolved with each reflection’s measurement error), beside the acentric control. It is read absolutely, never as the difference to the control: a perfect twin’s control (0.541) plus noise inflation would otherwise look like true symmetry. An absolute reading is only as good as the normalisation, though, and the acentric control certifies it: an acentric population reads \(-0.130\) nats per reflection when the normalisation is right, and whatever the control reads above that is the normalisation’s — anisotropy, a pseudo-translation, a pseudo-centring, noise all inflate every class towards centric alike — so the zone, normalised the same way, carries the same per reflection and the calibrated evidence has it taken off (a twinned control reads below the expectation, so nothing is taken off a twin). The centric side is read twinned at the fraction the lattice’s other operations show by their own correlation — the strongest CC of a lattice rotation outside the group, relative to the mean CC of the group’s own operators, inverted through \(\rho = 2\alpha(1-\alpha)/((1-\alpha)^2+\alpha^2)\) — because a twin by another law reaches a genuine zone exactly as it reaches the control: a genuine 321 crystal twinned by a 622 law read its 2-folds at −206 nats against the untwinned centric density and +209 at that law’s fraction of 0.07. The operators’ own twin law cannot reach their zone, so the acentric side stays untwinned, and the control’s expectation is taken at the same fraction. Measured, a 6/m crystal with a 67 Ų anisotropy read its control at \(+0.10\) nats per reflection and the zone of a refused 622 the same, so the zone’s \(+124\) nats were the normalisation’s; calibrated it reads \(-115\), and genuine promotions keep \(+200\) and above. The calibrated zone is what a refused promotion is decided on (above). It is an in-house method: published practice (Yeates’ \(H\)-test, xtriage) excludes these reflections as uninformative about the twin fraction, and no published test was found that uses them positively; the one precedent here is a trigonal crystal whose twin-immune zone read centric and whose higher group was then confirmed by refinement.

Translational pseudo-symmetry — two copies of the contents of the asymmetric unit related by a pure translation that is not a lattice vector — is looked for on every merging run, because it is the classic predictor of a failed molecular replacement, and because it raises the second moment where twinning lowers it, so each can mask the other’s test. The detection is the native-Patterson route of Read, Adams & McCoy (see the references): the largest off-origin peak of a Patterson computed from the merged intensities over 20–5 Å, as a fraction of the origin peak, with the peak vector then refined against the intensity modulation it should produce — the correlation between \(E^2\) and \(\cos 2\pi\,\mathbf{h}\cdot\mathbf{u}\) over the acentric reflections beyond 4 Å (or the 2000 lowest-resolution ones where a small cell has fewer there). Both halves are scored against a null computed for the crystal at hand rather than against a fixed bound — both against the same intensities permuted within resolution shells — the peak against that map, the modulation against the same search made on the shuffled intensities and started where the search starts — because the noise floor of the peak statistic spans an order of magnitude across data sets, so no fixed percentage means the same thing twice. The shuffle leaves the reflection count and the \(E^2\) distribution untouched and removes only the correlation between a reflection’s intensity and \(\mathbf{h}\cdot\mathbf{u}\), which is the thing the modulation claims to see; the shells are split by the reciprocal axis \(\mathbf{h}\) lies closest to, so that anisotropy, which the spherical normalisation leaves in \(E^2\) as a dependence on direction, is neither read as a modulation nor left out of the null, and the search stays 15 Å from every lattice point, where the phase would sort the reflections by exactly that direction. Re-running the greedy search from random starting vectors over the same intensities does not work as a control: a greedy search started anywhere walks into a real modulation’s basin, so it measures the search and whatever modulation the crystal carries. A vector that modulates is a fact about the crystal; the pseudo-translation reported is the one molecular replacement has to be told about, and the programs that correct for it act on a Patterson peak of a fifth of the origin — read in the band, or as the Patterson height the modulation’s depth gives at the vector, fitted over every reflection of the modulation population (undiluted by a twin; over classes averaged across the lattice’s rotations it also counts the copy pairs at the other images of the vector, and reads above the Patterson at the vector itself), which on a small cell or one whose low-resolution reflections were lost to overloads is the better measure of how much of the scattering the translation relates. Below that nothing in the data tells a weak pseudo-translation from two rotated copies that look alike at 20–5 Å (over the deposited models of a 200-dataset corpus the models’ own Pattersons read 18–80 % where a pseudo-translation is there and 4–15 % where it is not), and nothing downstream needs it, so it is noted and not flagged. A peak of that size the data cannot establish — a 30 Å cell has about 150 reflections in the band, where the noise floor is itself a fifth of the origin — is carried as POSSIBLE rather than dropped. A translation the merged data are exactly invariant under is reported as an undeclared lattice translation instead — a translation the data are exactly invariant under is a lattice vector by definition, so the centring or the cell is wrong, not the packing — and the pseudo-symmetry search continues underneath it, so a real pseudo-translation sitting under an undeclared centring is still found. The finding itself is report-only (the TNCS_* keys of <prefix>_report.txt): it gates nothing and changes no reflection, no scale and no group — but the axial-absence test (§13.1) and the \(L\)-test here both correct themselves against the modulation it measures, and the vectors are carried onto the axes the files are written on when a model or a reference moves them after the analysis.

The \(L\)-test partners are chosen so a pseudo-translation cannot silence it. The test compares each reflection with a partner a fixed index step away, and a pseudo-translation biases \(\langle|L|\rangle\) upwards unless the partner shares its modulation class. The ordinary step of 2 preserves the class of a half-integer translation — the pseudo-centering the statistic’s authors call it robust to — but not of one of a third, which inflates \(\langle|L|\rangle\) past the bound that is read as evidence against twinning and silently loses the twin call on a crystal that has one. Where a pseudo-translation is detected, the partner steps are restricted to those that preserve its class; where no step does, the statistic is dropped from the twin verdict in both directions — it can no longer indicate a twin and can no longer be read as proof that there is none — and the second moment decides alone. L_TEST_VS_TNCS= in the report says which of the three happened.

13.3 Outlier rejection

Merging applies a per-observation median-based \(N\sigma\) cut (--reject-outliers, default 6σ on rotation, 10σ on stills). On the rotation path the median is weighted by each full’s counting variance taken at the reflection’s expected intensity, as the merge weights are (§10.4): an observation’s own Poisson variance falls with its own intensity, so own-variance weights hand the median to whichever equivalents came out low — on a strongly absorbing crystal, where some frames read equivalents ten to a hundred times down, the median sat on the absorbed ones and the test removed correct measurements far above it. The band about the median keeps the counting part linear, \(\pm N\sigma_\text{counting}\), but takes the systematic part as a factor, \(e^{\pm N s}\) about the expected intensity: the error model’s systematic term is multiplicative — absorption, illuminated volume, a scale that is off — and as likely to be a factor \(1/f\) as \(f\), while a band symmetric in \(I\) reaches far below the median and only a little above it once that term is large. \(s\) is the spread of \(\ln(I/\text{median})\) measured on the merge’s own fulls (their weighted median of \(|\ln(I/\text{median})|\), weighted by \((\langle I\rangle/\sigma_\text{counting})^2\) so the fulls whose ratio counting noise does not blur carry it), with the error model’s \(b\) as the fallback where it cannot be measured; to first order in \(Ns\) the band is the linear one. The same \(N\sigma\) cut is fed back into the error model: after an initial \(a,b\) fit the parameters are re-fit once on the reflections that survive rejection (dropping any whose squared deviation exceeds \(N^2\,[a\,\sigma^2 + (b\,\langle I\rangle)^2]\)), so the calibrated errors describe the reflections that actually enter the merge rather than the pre-rejection pool. On stills the band is the plain linear one, \(\pm N\sqrt{a\,\sigma^2 + (b\,\langle I\rangle)^2}\) about the median: a still’s observations of one reflection are partials and per-crystal scales, many of them near zero, so the spread of \(\ln(I/\text{median})\) is wide and a band drawn from it let through a powder grain or a neighbour’s spot in the box at hundreds of \(\sigma\) — on a high-multiplicity run a single such observation was a weak reflection’s whole merged intensity, and they took the low-resolution shells’ \(\mathrm{CC}_{1/2}\) down to 0.6. The error model’s \(b\) is that spread as it is. \(N\) is wider than on rotation because a still’s partials scatter with heavier tails than the band’s normal core; what has to go sits tens to hundreds of \(\sigma\) out.

The median needs three observations, so a reflection measured once or twice — typically one good observation and one artefact (a hot pixel, a zinger) after Friedel merging — is never tested by it, and an artefact that looks precise (thousands of counts, a small relative \(\sigma\)) can outweigh mates from weak frames and become the median itself. Every observation of the written merge is therefore also judged by Wilson statistics. Beyond 4 Å its \(E^2 = I/(\varepsilon\,\langle I/\varepsilon\rangle_\mathrm{shell})\) is compared with a bound set by a budget of \(\alpha = 0.01\) expected false rejections per dataset: with \(N\) observations tested, \(\ln(2N/\alpha)\) for acentrics and twice that for centrics, and the observation’s lower confidence limit \(I - z\sigma\) (with its own \(\sigma\), and \(z\) from the same budget) must exceed it, so noise in weak shells does not trigger it; a shell whose \(\langle I\rangle\) is not itself established at that significance is not judged. The bound is widened by the tail scale of the dataset’s own intensity distribution, measured on its well-measured observations (1 for a Wilson crystal; larger under a pseudo-translation or anisotropy). An improbable singleton is dropped; an improbable observation with company only when most of the reflection’s other observations are probable and it disagrees with their mean beyond the errors — several large observations confirm each other. A Friedel mate does not confirm: an improbable observation of the exactly opposite indices is not counted as company at all. A spot of another lattice (a satellite crystal, a crystallite of salt or ice) that lands on a predicted reflection is the commonest large observation that is not the crystal’s, and that lattice diffracts centrosymmetrically too: half a turn later the rotation brings \(-h\) and the spot’s own Friedel mate to the same mirrored detector position, so the two always arrive together and would otherwise vouch for each other. A probable Friedel mate still testifies against the observation. An observation whose signal disk lost pixels to the mask or to saturation is never counted as such a witness, since its profile estimate may be low: a strong reflection is not replaced by its clipped mate. The count is OBSERVATIONS_REJECTED_WILSON= in the report (included in OBSERVATIONS_REJECTED=), and the developer report lists each observation with its image and detector position.

13.4 Automatic resolution cutoff

By default the reported/written high-resolution limit is trimmed where \(\mathrm{CC}_{1/2}\) falls off: a logistic is fitted to \(\mathrm{CC}_{1/2}(s)\), and the limit is set one tenth of the kept range in \(s = 1/d\) past the point where the fit crosses 0.30 — one shell of a ten-shell division, independent of the nine reported shells; deliberately “one shell too far”, so weak-but-real data below the crossing are kept rather than discarded. The extension is measured over the range that is actually kept, not the full measured range, so a detector reaching far past where the crystal diffracts cannot inflate it. --scaling-high-resolution overrides the limit and --resolution-cutoff off disables it.

The fit runs on an internal, weighted \(\mathrm{CC}_{1/2}\), not on the reported one. An observation from a frame at scale \(G\) below the run’s typical scale \(G_\mathrm{ref}\) was scaled up by \(G_\mathrm{ref}/G\) and carries \((G_\mathrm{ref}/G)^2\) more counting variance than the same observation at the typical scale. On rotation each reflection’s half-set pair therefore enters the fit’s Pearson sums with a weight in \((0, 1]\): the variance its two half-set means would have had with every observation at the typical scale, over the variance they have. It is 1 on a sweep without a weak stretch, and small for a reflection measured only where the crystal barely diffracted, whose scaled-up noise would otherwise pull the curve down as much as a well-measured pair holds it up. The same per-frame factor sets the information each observation carries in the ΔCC1/2 frame ledger (§ frame disposition in integration), and the two-pass and beam-centre guards read this weighted form too. The reported \(\mathrm{CC}_{1/2}\) — CC_HALF, CC_STAR, the shell tables and the mmCIF — is the standard one of XDS, Aimless and DIALS: the plain Pearson correlation of the \(1/\sigma^2\)-weighted half-set means, every reflection counted alike. Stills weight nothing in either.

Ice sits out of this fit, and only this fit. A powder ring is reproducible: past the crystal’s own limit the ice is still there and still the same in both half-sets, so the two halves agree about the ring, and a Pearson \(\mathrm{CC}_{1/2}\) cannot tell that agreement from diffraction. Shells have been measured at \(\mathrm{CC}_{1/2}=0.765\) where \(\langle I/\sigma\rangle\) is \(-0.1\) and \(R_\mathrm{meas}\) is 470 %, inside the written range because the logistic was fitted through them; against archived references, runs whose frames carry ice were written a mean twelve per cent finer than the reference where runs without ice were written four per cent finer, and every over-claim past twenty per cent has rings. The same ring drags the curve the other way where the data are good — one shell of forty falling to 0.51 because the two strongest ice lines cross it, with the shells either side at 0.99 — which is a real defect of those reflections but narrower than the shell it defames. Both signs are the same cause and both leave the fit: the reflections flagged in §3.3 are still merged, written and counted in the shell table wherever the per-ring decision of §10.10 keeps them, and what changes is only that the resolution decision now reads the same curve that scaling, the error model and the space-group search already read.

A cut the shell table refutes is not quoted. Two things keep the number inside what the bins show. The fitted crossing has to lie inside the fitted bins: on a real fall-off it sits between the last bin at the target and the first bin below it, with the extension bins to spare, and a crossing past the last fitted bin is an extrapolation of a fall-off these data never showed — the crossing is then read off the bins themselves, between the two that straddle the target. And no single resolution is quoted at all where the curve is not a fall-off: where \(\mathrm{CC}_{1/2}\) never reaches the target in any shell, where the fit reads finer than the finest shell whose \(\mathrm{CC}_{1/2}\) still reaches it, or where \(\mathrm{CC}_{1/2}\) climbs back over the target after falling below it — a noise shell that climbs back is not the edge of the data. The report then says which of the three happened and points at the shell table instead.

13.5 Diffraction anisotropy

How fast the intensity falls off with resolution can depend on direction. Rugnux measures that and reports it. No intensity is corrected and no reflection is removed on a directional criterion; the one use of the tensor is the Wilson prior of the French–Wilson amplitudes (§10.8), so F/SIGF follow the fall-off along each reflection’s direction while the intensities do not depend on direction at all. Treating anisotropy as something every run should analyse and report is inspired by STARANISO (see Acknowledgements).

The tensor. A deviatoric anisotropic displacement tensor is fitted to the merged intensities as

\[\ln \langle I(\mathbf{s})\rangle = c(\text{shell}) - \tfrac{1}{2}\,\mathbf{s}^\mathsf{T} B\, \mathbf{s},\qquad \mathbf{s} = \text{reciprocal-space vector},\ |\mathbf{s}| = 1/d\]

(§10.6 and §14.2 write \(s\) for \(\sin\theta/\lambda = 1/2d\), so their \(s^2 = 1/4d^2\); the two conventions give the same exponent \(-(B/2)(1/d^2)\), and \(B\) is the same \(B\).)

with one free constant per resolution shell, so every isotropic feature — the Wilson curve, an ice ring, a noise floor, a scaling error — is absorbed exactly and only the \(\ell = 2\) angular part drives the tensor. For an isotropic \(B\) this reduces to the ordinary Wilson plot, so \(B\) here is the ordinary crystallographic (\(B = 8\pi^2 U\)) \(B\), directly comparable with phenix.xtriage’s B_cart, ctruncate’s anisotropic \(B\) eigenvalues and AIMLESS’s anisotropic \(\Delta B\). Only the deviatoric part is fitted: the isotropic part is degenerate with the overall scale. The tensor is constrained to the directions the Laue class allows — five free deviatoric parameters in triclinic, three in monoclinic, two in orthorhombic, one in tetragonal, trigonal and hexagonal, and none at all in cubic, where symmetry forces \(\Delta B\) to be exactly zero.

The fit is on intensities, with no positivity cut. Fitting amplitudes, or dropping non-positive intensities as an amplitude-based tool must, loses roughly 40% of the signal: in a direction that has died half the merged intensities are negative, so a positivity cut keeps only the positive noise excursions and flattens the fall-off exactly where the anisotropy is largest.

That is not a small effect, and it is the whole of the difference from phenix.xtriage’s B_cart. Measured over the battery against the model-free fall-off of \(\langle I\rangle\) (negatives kept) in 20° cones about the principal directions: the tensor above reproduces that fall-off; xtriage’s eigenvalue range is a quarter lower on a typical crystal (median ratio 1.36), and four to eight times lower on a crystal whose weakest direction stops diffracting inside the measured range — its positivity cut floors the dead direction at the noise’s positive half, and its single Wilson curve over 11.2 Å to \(d_\min\) averages the deficit over the shells beyond that direction’s limit, so the value also shrinks as the written range extends past it (truncating one such data set at the fitted resolution raised xtriage’s range by a third; a shell earlier, it doubled). Restricting the same cone fall-off to positive intensities reproduces xtriage’s number. xtriage’s own verdict, range over mean \(B \ge 0.5\) with mean \(B > 20\) (the Read et al. 2011 cutoffs), is blind on low-resolution data for a second reason: the mean \(B\) it divides by is 100–180 Ų there, so a crystal whose weakest direction reaches 5.6 Å against 3.7 Å along the best scores “not significantly anisotropic”.

The grade — measurable but small, noticeable, STRONG (the warning) — is read on the directional limits, as the ratio of the weakest to the best (1.125 and 1.25), not as their spread in Å: the same spread is a 12% loss of resolution at 4 Å and a 33% one at 1.5 Å, and a spread graded every 4 Å crystal strong and a 1 Å crystal losing a third of its reach noticeable. The two ratios are the former 0.25 Å and 0.5 Å spreads read at 2 Å, so the bands keep their meaning where most data sit. The limits are the number to compare between programs: on the open-arm depositions that were processed with STARANISO, rugnux’s limits reproduce the deposited ellipsoid to about 0.1 Å per axis and its axis ratio to a few per cent.

Two different quantities are reported, and they are not interchangeable. \(\Delta B\) (the range of the principal components) is a rate; the diffraction limit along each principal direction — where \(\langle I/\sigma(I)\rangle\) in a 20° cone about that direction falls through 2, read by interpolation in \(s^2\) over equal-count shells — is where the signal actually runs out. A crystal can have a large \(\Delta B\) and almost no spread in directional limit, or the reverse. Where \(\langle I/\sigma(I)\rangle\) never falls through 2 in a direction, the limit returned is the edge of the measured data rather than the crystal’s own; such a direction is marked — with a < in the report, a 1 in ANISOTROPY_D_MIN_CENSORED, and a note in the mmCIF — so the spread is not read as a measurement when it is a lower bound. Both constants are AIMLESS’s defaults (cone half-angle 20°, \(\langle I/\sigma\rangle = 2\)). The 2 is a per-direction diagnostic level only: the dataset-wide resolution cut (§13.4) is CC\(_{1/2}\)-based, and the two criteria are not interchangeable.

The resolution signature. A genuine Debye–Waller \(B\) makes the directional deficit a straight line through the origin in \(s^2\). The per-shell \(\ell = 2\) amplitude is therefore fitted against \(s^2\) and the curve is classified: linear (a real \(B\)), flat (a deficit that does not follow \(\exp(-\tfrac12 \mathbf{s}^\mathsf{T} B \mathbf{s})\) at all, so the fitted \(\Delta B\) describes the data with the wrong functional form and may be an under-estimate), or convex (a deficit that grows faster than \(s^2\), which a \(B\) cannot do). The verdict is re-derived at 8 and at 16 shells, and reported as undetermined if it moves.

The verdict, and what it is measured against. Whether an anisotropy is real is not decided against a counting-statistics error bar. Real data carry systematic error far larger than counting error, and gating on the latter reports anisotropy on datasets that have none. Instead the data set measures its own systematic error: in the tensor directions the Laue class forbids, the true tensor is exactly zero whatever the crystal is, so whatever is measured there is systematic. That measurement needs the unmerged observations — a merge has exact Laue symmetry by construction, and the forbidden directions are identically zero in it — so it is made on the scaled, rocking-curve-assembled observations. The counting part is subtracted, the counting error of the directions actually being tested is added back, and the result is the floor. What is tested against it is \(\Delta B_\text{linear}\) — the part of the fall-off that actually follows \(\exp(-\tfrac12\mathbf{s}^\mathsf{T}B\mathbf{s})\), clamped at zero — and not the headline \(\Delta B\); the report names which of the two it is quoting. The ratio is banded: below 2 not established, 2–3.5 marginal, above 3.5 established, above 5 strong. The bands are calibrated against known ground truth — merging cubic crystals in proper subgroups of their own Laue class, where the true anisotropy is exactly zero — which puts the false-positive rate at 24 % at 2.0, 10 % at 3.5 and 5 % at 5.0.

The report says NOT DETECTED, DETECTED, or CANNOT DETERMINE, and the third is a real answer rather than an evasion. It is returned when the Laue class is triclinic (no forbidden direction exists, so there is no internal measurement of the systematic error and no substitute for it), when the observed rotation range is under about 90° (a lab-fixed systematic then reaches several tensor directions instead of one), when the merged data are at the noise floor, when the scale model carried no dose term (an uncorrected dose ramp manufactures anisotropy that no significance test can see through), or when no unmerged observations were available. The smallest \(\Delta B\) that could have been established on the data set is reported with the verdict; it is set by the systematic error rather than by counting, so it does not improve with more reflections or a longer exposure.

A too-high space-group assignment is the one failure mode that is silent: real anisotropy is then pushed into the directions used to measure the systematic error, which inflates the floor and biases the answer towards reporting none. A caution says so, but only where that is actually indicated — a single free direction, no detection, and a forbidden-direction measurement far above its own counting noise — rather than on every tetragonal, trigonal and hexagonal data set.

Everything lands in <prefix>_report.txt section 4 (ANISOTROPY_* keys), in the printed statistics, and in the merged mmCIF: the eigen-decomposition of the tensor as the standard _reflns.pdbx_aniso_B_tensor_* items (relative to the weakest direction, since only the deviatoric part is determined), and the directional limits, the shape and the verdict under the _reflns.jfjoch_aniso_* local prefix.

13.6 Practical notes and limitations

  • Bragg integration is profile-fitted by default (per-shell Gaussian profile, Kabsch extraction; §9.3), with plain box summation available as a fallback (--integrator boxsum). The profiles are built per frame from that frame’s strong spots, which suits fast-feedback and serial/streaming use; a profile shared across many frames (as in full offline workflows) is not currently formed.

  • Space-group symmetry beyond centering absences is not enforced during prediction/integration unless the space group is supplied and used downstream.

  • Resolution masking is controllable, and so is every stage of ice-ring handling (§3.3, §10.10). None of it runs unless the crystal is measured to have ice, because the fixed bands are a fixed cost in unique reflections whether it does or not.

  • Rotation vs still modes differ substantially in prediction and scaling: partiality is angle-driven in rotation data, while stills are predicted within an excitation-error window that follows the run’s rocking curve (§8.2) and get their partiality from the default-on per-crystal tilt post-refinement (§10.2) — or unit partiality with --simple-stills.

  • Amplitudes and intensities. The merged output carries both intensities (mmCIF intensity_meas, MTZ IMEAN/SIGIMEAN) and French–Wilson amplitudes (mmCIF F_meas_au, MTZ F/SIGF; §10.8), so a downstream program can refine against either.


14. Model-based validation: R-free against a model and electron-density maps

Offline (rugnux --model model.pdb) the merged data can be scored against a supplied atomic model and electron-density maps computed — enough to confirm that a model fits the data and to inspect the density. The numbers of this section are those of the model as placed, not refined - a placed model is refined afterwards by default (--no-refine skips it), on the side and deciding nothing (§15, Refinement of a placed model); the model is re-fractionalized into the data unit cell and then placed as one rigid body (§14.8) - or, where the rigid body does not place it and for a predicted model, by molecular replacement (§14.10) - and the observed amplitudes are the French–Wilson \(|F|\) from §10.8, so the R-free and the maps use exactly the same amplitudes as the written reflection file. The model, structure-factor, bulk-solvent and FFT machinery is provided by GEMMI.

14.1 Model structure factors

The model electron density is sampled on a grid (IT92 X-ray form factors, with a Refmac-compatible Gaussian blur chosen for the grid spacing) and Fourier-transformed to structure factors \(F_\mathrm{calc}(hkl)\) up to the data resolution.

14.2 Bulk solvent and scaling

A flat bulk-solvent mask around the model (the REFMAC radii, on the density’s grid, or on one of its own at 0.75 Å where that grid is too coarse for the mask’s 0.8 Å shrink to act) is transformed to \(F_\mathrm{mask}\), and the model is scaled to the observed amplitudes by an overall least-squares fit of a scale \(k\), an anisotropic \(B\), and the flat-solvent parameters \(k_\mathrm{sol}, B_\mathrm{sol}\):

\( F_\mathrm{model} = k\,e^{-\mathbf{h}^\top \mathbf{B}\,\mathbf{h}/4}\left(F_\mathrm{calc} + k_\mathrm{sol}\,e^{-B_\mathrm{sol}\,s^2}\,F_\mathrm{mask}\right),\quad s^2 = 1/4d^2. \)

This is the standard, few-parameter scaling model used by refinement programs. No free-form per-resolution-shell rescale is applied: such a rescale is dataset-specific and reshapes each map’s radial amplitude profile differently, which would make maps from a multi-dataset campaign no longer directly comparable.

That decision has a cost, and it is paid by the R-factors rather than by the maps. \(k\exp(-\mathbf{s}^\mathsf{T} B \mathbf{s})\) can only bend one way with resolution, so whatever a dataset’s radial amplitude profile does that this shape cannot follow is reported as R — which makes R a reading of this dataset and not a quantity comparable with another reduction of the same crystal. Both uses are wanted, so both are served, separately: the maps and R_WORK / R_FREE keep the scale above, and a second reading, R_MODEL_SHELL_SCALED, applies one free scale per resolution shell to the same fit and is reported beside them, with MODEL_RADIAL_MISFIT saying how much that rescale had to do. Nothing is written from the second reading; it never reaches a map, a map coefficient or a decision (§14.3, and RUGNUX_REPORT).

The fit sees the working reflections only; the parameters it returns are then applied to every reflection, free ones included, so that R-free (§14.3) is computed against them. The parameters are few, but they are fitted by minimising the very sum R is made of, and a free reflection that helped choose them is no longer held out.

14.3 R-work and R-free

Crystallographic R-factors are reported over the work and free sets (the §10.7 flags):

\( R = \frac{\sum \big|\,|F_o| - |F_\mathrm{model}|\,\big|}{\sum |F_o|}, \)

with R-free the same sum restricted to the free set. Every parameter \(F_\mathrm{model}\) carries — the scaling of §14.2 and the rigid-body placement of §14.8 alike — is fitted on the working set alone, so the free reflections are held out of the fit as well as out of the sum. Two choices are still selected with the free set rather than fitted to it, and both are single discrete decisions rather than continuous parameters: the rigid-body step is committed only if it lowers R-free (§14.8), and the alternative indexing of §14.6 is the candidate with the lowest R-free. Both are the conventional use of a test set to accept or reject a step; both leave R-free very slightly optimistic where they fire.

14.4 Electron-density maps

Two sets of map coefficients are formed with the model phases \(\varphi_\mathrm{model}\), both \(\sigma_A\) weighted: \(2mF_o-DF_c\) and \(mF_o-DF_c\). They are written as a map-coefficient MTZ (<prefix>_maps.mtz: FP, FC, PHIC, FWT/PHWT, FWT_no_fill/PHWT_no_fill, DELFWT/PHDELWT, FOM, FREE, and where the merge kept the Bijvoet pairs ANOM/PHANOM, the anomalous difference map’s coefficients), which Coot / PyMOL open directly as maps. The \(2mF_o-DF_c\) coefficients are also inverse-Fourier-transformed to a real-space map internally, for the mean density at the atom centres.

\(\sigma_A\) is estimated by maximum likelihood per resolution shell, on the free reflections only — on the working set the model has been fitted to the data, so \(\sigma_A\) would come out too high and the weighting would understate exactly the model error the map is meant to reveal. The shells are cut by equal reflection count, and it is the number of shells that is chosen from the size of the free set (about 50 free reflections to a shell, at most 20 shells), so no shell is thin by construction; a shell that still ends up with fewer than 10 free reflections takes the estimate made over the whole free set instead. Acentric and centric reflections enter with their own likelihoods (Rice and Woolfson respectively), and the epsilon factor is divided out before normalising both amplitudes to \(\langle|E|^2\rangle = 1\) within the shell. The figure of merit is then \(m = I_1(X)/I_0(X)\) with \(X = 2\sigma_A|E_o||E_c|/(1-\sigma_A^2)\) for an acentric reflection and \(m = \tanh(X/2)\) for a centric one, and \(D = \sigma_A\sqrt{\Sigma_o/\Sigma_c}\) carries \(F_c\) onto the observed amplitudes’ scale. The \(2F_o-F_c\) combination becomes \(2mF_o - DF_c\) for acentric reflections and \(mF_o\) for centric ones — a centric reflection’s phase is either exactly right or 180° wrong, never in between — while the difference coefficient is \(mF_o - DF_c\) throughout. The coefficients written to the MTZ then have the overall anisotropy of the scale divided out: each is divided by \(\exp(-\tfrac14\,\mathbf{h}^T B^*_\mathrm{aniso}\mathbf{h})\), \(B^*_\mathrm{aniso}\) the overall anisotropic B of §14.2 less its isotropic part, as phenix.refine does with its maps. Left in, the data’s anisotropy stretches every atom along the weak direction; taken out, the map has the isotropic fall-off of the data and of the model. FP and FC stay on the observed scale, and the map read internally keeps it too. FWT/PHWT is filled: every reflection of the data’s resolution range that the data do not have is added with \(DF_c\), its expected value given the model, \(D\) that of the observed reflection nearest in resolution - the convention of phenix.refine (fill_missing_f_obs) and BUSTER, which keeps the missing reflections from biasing the map towards zero. Those rows have FP, FOM, FREE and the difference coefficients missing. FWT_no_fill/PHWT_no_fill is the same \(2mF_o-DF_c\) map on the observed reflections only (phenix’s 2FOFCWT_no_fill), and the difference map DELFWT/PHDELWT is never filled.

\(m\) and \(D\) are estimated on each dataset separately, so two datasets of one crystal form get slightly different weights and their maps are to that extent no longer scaled identically — the same property §14.2 deliberately protects by refusing a free-form per-shell rescale. The two are not the same thing: the weighting never rescales \(F_o\) and never touches the R-factors of §14.3, and the difference between two datasets’ \(\sigma_A\) curves is the difference in how well the model explains each of them, which is what a screening campaign is looking for. A PanDDA-style analysis consumes \(2mF_o-DF_c\) maps and normalises each dataset’s map against the ensemble before comparing them. The per-reflection FOM is written to the MTZ so the weighting can be read off and undone.

14.5 Does the model fit? The null it is scored against

A model supplied with --model is a hypothesis about the crystal, not an instruction. It is always scaled, always placed (§14.8) and always scored, and its R-factors and maps are always reported — but before it is allowed to change anything about the reflections that are written, the data have to accept it. There are only two such things (§14.6); the same verdict also says whether the rigid body placed the model at all (below).

No fixed threshold on R can decide that. The classical acentric random-structure value is \(R = 0.586\) at unit scale, but the scale here is fitted to minimise the very sum the R is made of, which pulls it to about 0.550; observed nulls on real data land at 0.60–0.62; and the value moves with the model — its atom count and its B-factors — as much as with the data, so a cut calibrated on one pair misjudges the next: an unrelated protein can reach a lower raw R-free on one dataset than the correct model does on another.

The only null that fits both the model and the data is therefore made out of them: the same model is re-oriented at random about its own centroid and run through the identical path — the same scaling, the same rigid-body placement, the same R — nine times, and the real fit is asked how far above the resulting distribution it sits (MODEL_FIT_SIGMA, accepted at 4.51: see below). The replicates are placed as well as fitted, or the comparison would be between a placed model and unplaced nulls and the margin would be inflated by the placement rather than by the model. Measured on one rotation data set: the crystal’s own model +15.0σ, an unrelated protein +1.8σ, and the correct model rigidly rotated 90° −1.0σ.

A replicate is a sample of the null only while it stays away from the model’s own solution. A draw within the rigid body’s reach of an orientation equivalent to the model’s — under the space group’s rotations or a twin law of the lattice — is drawn again before it is placed, and a replicate the placement nevertheless carries to within that reach is drawn and placed again afterwards, each replicate from a generator of its own so the result does not depend on the order the concurrent replicates finish in.

R-work carries the decision, not R-free. Nothing is refined against the working set here — the scale has a handful of parameters (a scale, an anisotropic \(B\) and two solvent terms) and the placement six — so R-work carries no optimism, and it has an order of magnitude more reflections than R-free, and so that much more power to separate the two arms. R-free is still reported, and is still what the placement of §14.8 is committed on, since that is a fit.

What the verdict gates is exactly the two decisions of §14.6 that rewrite the data: the space-group label and the indexing. It does not gate the R-factors, the maps or the rigid-body placement, which are statements about the model and cannot corrupt a reflection. A rejected model therefore leaves the written files byte for byte what a run with no model would have produced, and the report says so beside the R it was rejected on: a negative result, not a failed run.

The null is built for every model the rigid body is tried on. A model already in the data’s group, on a crystal with no merohedral ambiguity, claims nothing about the written reflections, but the null is built for it too, because its verdict has a second use: it is what says whether the rigid body placed the model at all, and a model it did not place - a deposited structure of another crystal form, a model in a subgroup the data were merged above - is then searched for by molecular replacement, which may only relabel the enantiomorph of the answer (past the anomalous veto) and writes any other group it chooses beside it as <prefix>_mr. The cost is the null’s one to two seconds on every run with a model.

The count is nine, and it is the spread that sets it rather than the mean: the verdict is (mean − real)/sd of the sample, the relative error on an sd from \(n\) draws is \(1/\sqrt{2(n-1)}\), and a sample that happens to come out narrow is what turns a model that does not fit into one that appears to: for an unrelated protein near the gate, the chance of reading over it on a different seed falls from about a third at \(n=3\) to a few percent at \(n=9\). The gate itself allows for it: the intended cut is 3σ of the null (one-sided, 0.135 %), and a new draw from a null known only through \(n\) draws lies \(t_{n-1}\sqrt{1+1/n}\) sample sds above their mean at that probability — 4.51 for \(n=9\). Read as if the sd were known, an unrelated model can pass 3σ against nine draws and fall to about 2σ against many more. Deposited models of their own crystal read +7σ and up. The indexing lead (§14.6) stays at 3σ of its own null: it is only read for a model that has passed this gate, and deposited models settle an indexing lead by +4σ and up. Nine is affordable only because the replicates run at once: the null costs the slowest of them rather than their sum, and the slowest of nine is barely above the slowest of five.

The null costs one full fit and one rigid-body placement per replicate. The replicates share nothing — each is the same model under a different rotation, scored the same way — so each takes a copy of the model and of its structure factors and they run concurrently, on the run’s own thread budget (-N); the real model is not touched by any of them. Measured on an idle machine, five replicates cost 2.5 s together where running them one after another costs 10 s, on a --mode scale run that merges in 2 s. What remains is the cost of the slowest replicate: how many placement evaluations an orientation needs varies by nearly half between them, so the concurrency saturates around 4×, and more threads than replicates buy nothing. The orientations are drawn up front, in order, from the fixed seed, so replicate \(i\) gets the same orientation whatever order the threads run in — a σ that depended on the scheduling would not be a measurement. That is the price of the answer being a measurement rather than a threshold.

14.6 Aligning the data to the model: enantiomorph and indexing ambiguity

The model fixes a definite hand and indexing, but the merged data need not share them, so before comparison the observed reflections are brought into the model’s frame.

  • Enantiomorph / screw. When the data space group is the enantiomorph of the model’s (e.g. data \(P4_12_12\), model \(P4_32_12\); or \(P3_1/P3_2\)), the two are indistinguishable from merged intensities — \(|F_\mathrm{calc}|\) is invariant under the change of hand, so R-free cannot choose between them and probing would be meaningless. Where the model was accepted (§14.5), its group is therefore adopted as the label the reflections are written under, and the reflections themselves are left untouched. Where it was not, the label is left alone: adopting it is arithmetic on two group numbers, which a model that does not belong to this crystal can do exactly as readily as one that does, and the anomalous map of §14.7 vetoes it outright where it says the two are in opposite hands. The two groups of an enantiomorphic pair differ only in the translations of their operations: their rotations are identical, so they transform \(hkl\) identically, share a reciprocal ASU, and assign the Bijvoet hands identically. The label carries no handedness, and there is nothing about it to undo. Reindexing by the change-of-hand operator — which is the inversion — would instead swap \(I(+)\) with \(I(-)\), flipping every anomalous difference on the strength of a label the space-group search itself reports as undetermined; where the model is genuinely the wrong enantiomorph for the crystal, it would manufacture agreement rather than reveal the mismatch. What does carry the hand is the indexing the data already have, from the diffraction geometry, and the anomalous differences that come with it. §14.7 is what tests them against the model.

  • Indexing (merohedral) ambiguity. When the crystal has a merohedral ambiguity (§10.9), the observed intensities do differ between indexings, and the right one is chosen against the best available reference. If a reference MTZ was supplied, the data were already reindexed to agree with it (§10.9 — by the reference-intensity correlation, at the merge stage for rotation data or per image in stills scaling), and model validation keeps that authoritative choice. Only with a model and no reference does validation resolve the ambiguity itself, as a fallback: the scaled model is fit to each reindexing of the data (identity plus the twin-law cosets) and the one giving the lowest R-free is kept — but only where its lead over the runner-up beats the lead the same model in a random orientation takes, since a random model also picks a winner, and, as measured, by a comparable margin. Where it does not, the data keep the indexing they were merged in. The candidate operators are enumerated from the data’s space group, not the model’s: it is the observed intensities that are being relabelled, and asking the model’s group enumerates nothing at all wherever the two differ. This matters for a multi-dataset campaign — a single shared reference fixes one indexing convention for every dataset, whereas an independent per-dataset lowest-R-free choice could send borderline datasets to different conventions. A no-op either way for a holohedral crystal (no twin laws). The two decisions then reach the written output differently, because only one of them moves reflections. The ambiguity choice is applied to the merged reflections themselves — and to the integrated observations behind the unmerged export — which are written after this step, so the reflection file, the R-factors and the maps describe one indexing. The change of hand changes only the space group the files are written under (the model’s enantiomorph): no reflection moves, exactly as the first bullet says, so \(I(+)\) and \(I(-)\) stay as measured and §14.7’s hand check remains a genuine test rather than an agreement manufactured by reindexing. The ambiguity choice is reported with that margin and with the null it was judged against, since the margin alone is what cannot say whether the data decided or the two came out within noise of each other.

14.7 Anomalous difference map and the sites it names

Where the merge kept the Bijvoet split (§10.5) — which a rotation merge does by default, whether or not the mates were averaged — an anomalous difference map is computed as well, with coefficients

\( \big(|F(+)| - |F(-)|\big)\, e^{i(\varphi_\mathrm{model} - \pi/2)}, \)

over the acentric reflections that have both hands (a centric reflection has no anomalous difference, only noise). Turning the model phase back by 90° is what makes the anomalous scattering, which is 90° out of phase with the normal scattering, add up in the real part: the map’s peaks then sit on the anomalous scatterers. It is read here and not written out. Its hand is the one §14.6 settled: with the mates the wrong way round every peak becomes a trough, so a map of clean peaks is itself a check that the frame is right.

Rather than searching the map for blobs and leaving a list of coordinates, the map is read at the model’s own atom centres (hydrogens excluded — they scatter no anomalous signal), and the ten highest, in units of the map’s r.m.s., are reported in the log and as ANOMALOUS_SITE_01…ANOMALOUS_SITE_10 in the results report. Each site is therefore named — the atom, residue and chain it belongs to — which is what says what carries the signal, not just where it is. The reading is cubic, not linear: the map is sampled every \(d_\mathrm{min}/3\), and a peak that sharp read by trilinear interpolation comes out up to a quarter low — unevenly enough to reorder the sites. This reading is the one ANODE reports. The same reading averaged over the model’s anomalous scatterers — every atom from phosphorus (\(Z = 15\)) up: the S of Met and Cys, metals, Cl, I — is reported as ANOMALOUS_SCATTERER_MEAN_SIGMA (with their count, ANOMALOUS_SCATTERERS): one number for how much anomalous signal the merge carries, which does not depend on which ten atoms happen to come out on top. Below phosphorus (C, N, O, Na, Mg) \(f''\) is a fraction of sulfur’s at any wavelength these data are taken at, and counting those atoms would only dilute the mean with noise. Reading the map at the atoms cannot show a scatterer the model does not have, so the map’s own peaks are searched as well (gemmi’s flood fill, each symmetry copy once): every peak of 5 σ or more with no atom of the model from phosphorus up within 1.5 Å is reported as ANOMALOUS_UNEXPLAINED_PEAK_01… with its position and the model’s nearest atom - an ion or a heavy atom left out of the model, or modelled as a lighter element.

Because the map is built on the model’s phases and the data’s own indexing, it is also the only test of whether the two agree about the hand (§14.6). A model and a dataset in opposite hands turn every anomalous peak into a trough, so a map whose deepest hole at an atom is both deeper than \(5\sigma\) and deeper than its highest peak says so, and the run reports it as a warning naming that atom. It is not repaired by reindexing: that would make the two agree by construction and destroy the evidence for which of the model and the data is in the wrong hand. Note that R-free cannot see this at all — a mirrored model gives R-free to four decimal places unchanged, and an exactly inverted anomalous map.

The list is always ten entries long, so it is their height that carries the information: on a sulfur-SAD dataset the sulfurs fill the top of the list and are followed by a clear drop to the couple of sigma that is the map’s noise, while a dataset with no anomalous signal has no such separation and lists ten unrelated atoms at noise level. A scatterer the model does not contain — a bound ion, a soaked heavy atom — is by construction invisible in the list, and takes the anomalous difference map itself, which rugnux does not write out.

14.8 Rigid-body placement of the model

Re-fractionalizing a model into the data cell puts it in the right box but not necessarily in the right place: a non-isomorphous cell squeezes the box without moving the body inside it, and the body’s own position in the cell differs from crystal to crystal. Six parameters recover that — an angle-axis rotation about the model’s own centroid, then a translation. Rotating about the centroid rather than the cell origin is what keeps the rotation from moving the body bodily, so the two triplets are close to independent. Parameters are carried as six lengths in ångström (the rotation vector multiplied by the model’s r.m.s. radius), so a unit of each moves a typical atom by the same amount.

It is one rigid body. A fragment-screening model arrives already solved and isomorphous, and what is being recovered is the crystal’s movement, not the molecule’s; splitting it into domains, or giving a bound ligand six parameters of its own, would refine against evidence these data do not separately carry — and the ligand is what the difference map is there to show, not to model away.

The refinement walks a coarse-to-fine ladder, 6 Å → 4.5 Å → 3.5 Å, each zone starting from the previous one’s answer. It stops at 3.5 Å because that is where rigid-body refinement is conventionally run and because the movement being recovered is a few tenths of an ångström, a tenth of that resolution; a finer zone costs \((1/d)^3\) in grid points and reflections for a placement it cannot meaningfully sharpen. Each evaluation recomputes \(F_\mathrm{calc}\) and the solvent mask for the moved model and re-fits the scale of §14.2 — otherwise the target would measure the scale as much as the placement, and the body would translate to repair a scale error instead of moving to where the density is. The minimiser is Levenberg–Marquardt on the amplitude residuals. \(F_\mathrm{calc}\) is computed from one copy of the model, gridded without symmetrization and transformed once, and composed over the space group’s operators, \(F(\mathbf h) = n_\mathrm{cen}\sum_{(R,\mathbf t)} e^{2\pi i\,\mathbf h\cdot\mathbf t}\,F_1(\mathbf hR)\) — the transform of the symmetrized map, rearranged. That makes the derivative with respect to the translation exact and free (\(F_1(\mathbf k)\) only picks up the phase \(e^{2\pi i\,\mathbf s_\mathbf k\cdot\Delta}\)). The rotation’s three columns are forward differences, the step a fixed fraction of the zone’s resolution, each needing only one copy gridded and transformed. The Jacobian holds the scale and the bulk-solvent mask at the evaluation’s; the residuals keep both exact, and the scale re-fit is folded into the Jacobian by variable projection (Golub & Pereyra 1973, in Kaufman’s 1975 form), so a step is judged on the target the evaluations actually compute.

The refinement sees only the working reflections. The step is then committed only if it lowers R-free, computed at full resolution on the free set it never saw; otherwise the model is put back exactly where it was read and the maps are the ones it would have given. The whole addition costs about two seconds. Note that the origin is a gauge in some space groups — free in all three directions in \(P1\), and along the unique axis in a polar group — so those components of the translation are undetermined; nothing is done about that beyond the Levenberg–Marquardt damping and the R-free gate, which between them make an undetermined direction harmless rather than unstable.

Where a CUDA GPU is present, the refinement’s target is evaluated on it: the same density, the same composition of \(F_\mathrm{calc}\) from one copy of the model, the same bulk-solvent mask with its islands removed, the same scale fit and the same Jacobian, computed on the device, where a fit takes a fraction of a second rather than several seconds. The device is chosen once per validation, before anything is computed, and never revisited - the real fit and every replicate of the null of §14.5 on the same one. What goes on the GPU is decided for all parts at once, on one budget: 80% of the card’s total memory (judged on the total, so the same input on the same machine always takes the same path), less what a merge still at work holds there. Every engine is reserved up front and kept to the end, so it is their sum that has to fit: the structure factors to the data’s resolution (which also make the maps), one rigid-body engine, the null’s structure factors to its coarser limit and one engine for the scale fits of §14.2 each take their place in that order where they still fit, and more rigid-body engines and then more scale-fit engines are added only within half of the budget: they change only how many fits run at once, and on a large cell, where one fit already fills the card, they buy little. A part that does not fit, or a cell too small for the GPU’s gridding, runs on the CPU, as everything does where there is no GPU. A CUDA failure ends the validation, not the run: the validation reports why it did not finish, decides nothing, and the reflection files are those of a run without a model. The two agree to rounding and not bit for bit: the device measures distances in single precision and transforms with cuFFT instead of FFTW, and GEMMI’s scale fit, whose stopping rule leaves it unconverged at about \(10^{-4}\) of \(|F|\), can respond to that rounding with a step of its own. A rigid-body step accepted or rejected on an R-free difference below about \(5\cdot10^{-4}\) can therefore go either way between the two; every kernel is deterministic, so either one gives the same answer on every run.

The rotation and translation actually taken are reported (RIGID_BODY_ROTATION_DEG, RIGID_BODY_SHIFT_A), together with the R-free before it (R_FREE_BEFORE_RIGID_BODY), so what the placement bought is visible.

The coordinates as placed are written as <prefix>_model.cif, and as <prefix>_model.pdb where the PDB format can hold the cell (the fragment-screening tools the file feeds — PanDDA, and the pair dimple produces — take a PDB beside the MTZ), so there is a coordinate file that describes the maps: the input’s chains, residues, ligands, waters, B-factors, occupancies and anisotropic \(U\)s, moved, in the same cell and space group as <prefix>.mtz. Taking the frame from the written reflections rather than from the input model matters — §14.6 may have relabelled them to the model’s enantiomorph, which is neither the data’s original group nor, necessarily, the model’s. It is written whenever the maps are, not only where the rigid-body step was committed: the model is re-fractionalized into the data cell and may be relabelled whatever the placement decided, so an unmoved model is still not the input file. Neither is written for a model placed nowhere (MODEL_PLACEMENT=NOT_PLACED: the null of §14.5 rejected it and molecular replacement did not place it): it is scored like any other and its R-factors are reported as the negative result, but coordinates and maps of it would read as a placement of a model that is not this crystal’s.

14.9 The twin hypothesis: which merge the maps come from

Where the run wrote a twin hypothesis (§13.2), the model is scored against that merge too: as merged, and as twinned by its law — \(|F_\mathrm{twin}(h)|^2 = (1-\alpha)|F_\mathrm{model}(h)|^2 + \alpha|F_\mathrm{model}(Th)|^2\) from the placed, scaled model, one overall scale refitted at each \(\alpha\), \(\alpha\) scanned from 0 to 0.5 in steps of 0.01 on the working set and R-free read at the chosen one. The placement, the anisotropic \(B\) and the bulk solvent are those of the untwinned fit (§14.2, §14.8), so this is the same few-parameter comparison as §14.3, not a twin refinement. Against the answer’s merge the model is scored as in §14.3, the subgroup model’s structure factors simply read at each of the higher group’s reflections.

The maps and the placed model are then made from whichever merge the model fits better on R-free — the lower of the subgroup’s plain and twinned R-free against the answer’s — and the report says which (MAPS_FROM=) and with what R-free for each. The map coefficients are those of §14.4 against the chosen merge’s amplitudes, not detwinned. This chooses the maps, and never the answer: the space group, the answer’s reflection files and every number in the report outside the twin keys are what the run decided without the model, because a model can be wrong and the reflection files must not depend on one (§14.5). Where the model also fits the subgroup’s merge against its own null (§14.5), it has chosen the subgroup, and that merge is written beside the answer as <prefix>_mr.mtz/.cif, with the model as placed there. The structure factors come from the same GPU engine as §14.1 where there is a GPU.

14.10 Molecular replacement: placing a model the rigid body cannot

The rigid body of §14.8 only moves a model that already sits near its place. A model it does not place - the null of §14.5 is not beaten in the answer’s merge nor in the twin hypothesis’ one - is searched for from scratch, and so is a predicted model, which has no placement of its own, and any model given with --mr. The kind of model is read from the file: a prediction (ModelCIF’s _ma_qa_metric, or no cell and one B value per residue between 0 and 100) is trimmed to the residues of pLDDT 70 and above, its B-factors made from the pLDDT and its coordinate error from them (following Oeffner et al., 2022), and cut into rigid domains where the AlphaFold DB’s predicted-aligned-error file sits beside it; anything else is an experimental structure, used as its polymer alone.

The search is the classical one, scored by likelihood. A rotation function over the point group, its best peaks refined off the sampling grid (following Navaza, 1994); for each orientation a full-symmetry translation function computed as one Fourier synthesis (following Crowther & Blow, 1967), in every space group the merge cannot tell apart and in the twin hypothesis’ subgroup; and the best placements of each group put through the rigid body, the bulk solvent and R-free. Further copies are added one at a time, up to the copy number the cell can hold by its Matthews coefficient (Matthews, 1968; the probabilities of Kantardjieff & Rupp, 2003), each with the copies already placed as a known partial structure and ranked by the log-likelihood gain of the Rice/Woolfson distributions of \(E_\mathrm{obs}\) given \(E_\mathrm{calc}\), with \(\sigma_A\) falling off with the coordinate error (following Read, 2001, and McCoy et al., 2005 and 2007). A model whose expected gain (McCoy et al., 2017) is too small to be found is not searched for. A copy is kept where it stands out from the translation function’s own peaks, packs without clashing, and lowers R-free; in \(P1\), where the first copy’s position is a gauge, it has to stand out in the rotation function instead.

Translational NCS changes what the search can tell apart (Read, Adams & McCoy, 2013): with a pseudo-translation, one copy beside a translated twin of itself fits the data as well in a group whose screw axes the translation turns into the chosen group’s, so such a choice is left undecided unless the copies, carried into the other group and refined there, fit clearly worse; and where the vector is half a lattice vector, the placement is compared with every move of itself the vector allows, each refined, on the weak reflections it modulates, and left undecided only where the best is not ahead of every other by 3 standard errors of the paired per-reflection difference there. A model of several chains is searched for as a whole and, side by side, as one chain of each molecule in it: the chains of an experimental model from another crystal form need not sit in this crystal as they sat in that one, and the whole model’s choice gives way to a chain’s where the chain’s fits better by the R-free margin.

The choice between groups and merges is a hypothesis comparison like §14.5: the candidate the choice falls on has to beat a null of the same model placed from random orientations, and lead the other groups by a margin in R-free. Where another group is within that margin with as many copies placed, the two have as many parameters, so the working reflections compare them as fairly as the free ones and there are some twenty times as many: the other group is ruled out where the chosen placement’s \(|F_\mathrm{obs}-F_\mathrm{calc}|\) is lower by 3 standard errors of the paired per-reflection difference over every reflection to the scoring limit, and the choice is left undecided otherwise. What the choice may do is limited exactly as for the rigid body, and less: it may relabel the enantiomorph of the answer, past the anomalous check of §14.7, and never reindexes; another group with the answer’s rotations, or the twin hypothesis’ subgroup, is written beside the answer as <prefix>_mr.mtz/.cif with the model as placed there, and the answer’s own files stay what the run decided. The rotation and translation functions, the rigid body and the structure factors run on the GPU where there is one, decided for each merge before its search starts on the budget of §14.8 (80% of the card’s total memory, less what a merge still at work holds there): the molecular transform, one rigid-body engine shared by every fit of the merge and the largest score engine take their place in that order where they still fit, more rigid-body engines are added only within half of the budget, and the score engines and the functions’ working buffers share what is left, waiting for each other rather than spilling past it. On the CPU the molecular transform’s FFT is split over the threads by columns and planes, each done by one plan, so its result does not depend on the thread count. The keys, thresholds and table are described in the results report.

\ No newline at end of file diff --git a/CPU_DATA_ANALYSIS_IMAGE.html b/CPU_DATA_ANALYSIS_IMAGE.html new file mode 100644 index 000000000..4d659760f --- /dev/null +++ b/CPU_DATA_ANALYSIS_IMAGE.html @@ -0,0 +1 @@ + Data analysis: from images to spots (§0–§3) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Data analysis: from images to spots (§0–§3)

Part of the CPU/GPU data-analysis reference; the section numbers are continuous across its parts.

0. Getting the image onto the GPU: device-side decoding

HDF5 images mostly arrive bitshuffle+LZ4 compressed (HDF5 filter 32008), and everything from §1 onwards runs on the GPU when one is present. Instead of decompressing on the host and uploading the image, the compressed chunk is uploaded — a few MB rather than tens of MB — and decoded on the device. The approach follows Jon Wright (ESRF); the kernels are Jungfraujoch’s own.

One kernel does the work: one CUDA block owns one bitshuffle block, from the compressed payload through to finished pixels.

  1. LZ4 into shared memory, one warp per bitshuffle block. Blocks are independent, so the parallelism is across them; within the warp every lane runs the same sequence parser over the same bytes, and the literal and match copies are split across the 32 lanes so the stores coalesce. An overlapping match is treated as a pattern of period offset sourced from bytes that already precede the write position, which keeps it parallel rather than a serial byte loop; offset == 1 (a run of one repeated byte, the common case in sparse detector data) and power-of-two offsets avoid the modulo altogether. Because the lanes cooperate on the copies, each one is followed by __syncwarp() — a later match can read bytes another lane wrote, and since Volta that ordering is not implicit.

  2. The bitshuffle inverse fused with preprocessing. The whole CUDA block then reads that shared buffer back: one thread owns one group of 8 elements across every byte-plane, so once it has transposed its 8 bytes out of each plane it holds 8 complete elements — and it applies the pixel mask, the error marker and the saturation cap and emits 8 finished int32 pixels directly. Nothing of the block reaches device memory but the pixels — neither the bitshuffled bytes nor the decompressed image is ever materialised. For 8-bit images there is a single plane and the assembly degenerates to a copy.

Decoding into shared memory is worth more than the bandwidth it saves: an LZ4 match reads back bytes written a few sequences earlier, so every copy step is a dependent round trip — tens of cycles in shared memory against hundreds in device memory. It is paid for in residency, because the buffer holds a whole bitshuffle block, and a block larger than 16 kB (larger than either writer this pipeline reads produces) falls back to a pair of kernels instead, the first writing the shuffled image to device memory and the second un-transposing and preprocessing out of it.

The block offsets inside the container can only be discovered by reading the block lengths in order, so that scan stays on the host.

Two stored formats of other detectors also reach the card as the file stores them. A miniCBF frame’s x-CBF_BYTE_OFFSET stream is decoded on the device into the same int32 image: the stream is cut into short parts; for every byte offset a part can be entered at, one thread works out where the decode leaves the part, how many pixels it emitted and their running sum; a scan composing those maps gives every part its true entry and running value; and a second walk writes the pixels. A stream that ends before the image is refused, as on the host. A marCCD frame’s 16-bit pixels cross the bus at two bytes each and are widened by the preprocessing kernel itself, which tests the error marker and the saturation cap on the pixel’s value, so a marCCD’s 65535 - its saturation marker, not an error - is treated exactly as in the int32 image the host would have made. Both are staged through the engine’s own page-locked buffer, as the BSLZ4 chunks are; .cbf.gz is still inflated on the host.

For the zstd variants (BSHUF_ZSTD, BSHUF_ZSTD_RLE, BSHUF_ZSTD_RLE_HUFF), and for other uncompressed or float images, the pipeline decompresses on the host and uploads as before. The host decoders are the CPU build’s path, not a fallback: a frame the device refuses is not retried on the host.

The container arrives off the network or off disk and is not trusted. Everything checkable on the host — declared sizes, the block scan, a block size that is not a multiple of 8 elements, a block count the chunk could not hold, trailing bytes — is rejected before any work is queued; the kernel additionally flags a block that did not decode to exactly its declared length, which becomes an exception once the caller has synchronised. That last check matters because the decode buffers are reused frame to frame: a block that stopped early would leave the previous image’s most significant byte-plane in place, which reads not as a missing corner but as real pixels several powers of two too bright.

1. Geometry, reciprocal-space mapping, and basic quantities

1.1 Coordinate conventions

For a pixel coordinate \((x,y)\) (in pixels), Jungfraujoch converts to a laboratory direction vector via:

  1. shift by the beam-centre pixel \((x_\mathrm{beam}, y_\mathrm{beam})\) — the PONI, pyFAI’s point of normal incidence, which coincides with the direct-beam impact point only for an untilted detector (see Detector geometry),

  2. scale by pixel size \(p\) (mm),

  3. set detector distance \(D\) (mm),

  4. apply detector orientation rotation \(R_\mathrm{det}\) (PyFAI-like parameterization).

The unnormalized detector coordinate (mm) is: \( \mathbf{r}_\mathrm{det}(x,y) = \begin{pmatrix} (x-x_\mathrm{beam})p\\ (y-y_\mathrm{beam})p\\ D \end{pmatrix}. \)

The lab-frame vector is: \( \mathbf{r}_\mathrm{lab} = R_\mathrm{det}\,\mathbf{r}_\mathrm{det}. \)

By this construction \((x_\mathrm{beam}, y_\mathrm{beam})\) maps to \((0,0,D)\) before the rotation — the point where the detector normal through the sample meets the detector — which is what makes it the PONI rather than the direct beam; the two differ by \(D\tan(\mathrm{tilt})\) on a tilted detector. The laboratory frame is fixed the same way everywhere in the system: \(+z\) along the beam propagation, \(+x\) along increasing pixel column (the fast axis) and \(+y\) along increasing pixel row (the slow axis) — a right-handed triple that coincides with XDS’s laboratory frame, which is what makes the geometry echo of Rugnux directly comparable. The absolute hand of an indexing — and with it the Bijvoet hands of §14.6–§14.7 — follows from this convention.

Let the incident wavevector magnitude be \(k = 1/\lambda\) in Å\(^{-1}\), and define: \( \mathbf{S}_0 = (0,0,k). \)

The reciprocal-space scattering vector associated with pixel \((x,y)\) is: \( \mathbf{s}(x,y) = k\,\frac{\mathbf{r}_\mathrm{lab}}{\lVert \mathbf{r}_\mathrm{lab}\rVert} - \mathbf{S}_0. \)

This \(\mathbf{s}\) is the fundamental quantity used for spot finding (resolution filters), indexing, and refinement.

1.2 Two-theta, azimuth, resolution and \(q\)

The scattering angle \(2\theta\) is computed from \(\mathbf{r}_\mathrm{lab}\) via: \( 2\theta = \mathrm{atan2}\!\left(\sqrt{x_\mathrm{lab}^2 + y_\mathrm{lab}^2},\; z_\mathrm{lab}\right), \)

evaluated as a two-argument arctangent, so the mapping stays correct where a strongly tilted detector’s far corner reaches past \(2\theta = 90°\).

Resolution (Å) at a pixel is: \( d = \frac{\lambda}{2\sin\theta}. \)

The magnitude \(q = 2\pi/d\) is used for radial binning and ice-ring handling.

1.3 Distance from the Ewald sphere

For a reciprocal lattice point \(\mathbf{p}\) (Å\(^{-1}\)), define: \( \Delta_\mathrm{Ewald}(\mathbf{p}) = \lVert \mathbf{p} + \mathbf{S}_0\rVert - k. \) Jungfraujoch uses \(|\Delta_\mathrm{Ewald}|\) as an operational proxy for excitation error. This appears in:

  • still prediction (accept if \(|\Delta_\mathrm{Ewald}|\le \Delta_\mathrm{cut}\)),

  • profile radius estimation (see §11.1),

  • still partiality option in scaling/merging (§10.2).

1.4 The beam centre

A run starts from the beam centre in the file, or from --beam-x/--beam-y where they are given. Header centres are often typed rather than measured, and on rotation data a wrong one is not repaired by anything downstream: the error is fixed in the laboratory frame, so accumulating a sweep smears every reciprocal-lattice point around a circle, and a displacement \(\delta p\) on the detector multiplies the FFT amplitude at an axis of length \(a\) by \(J_0(2\pi\,\delta p\,a/(D\lambda))\). Past the first zero the true axis is gone and its harmonic wins. Rugnux therefore measures the centre itself on every run and treats the measurement as a second hypothesis to be tested against the file’s, not as a replacement for it. Distrusting the header and finding the centre from the images are ideas inspired by autoPROC (see Acknowledgements). The steps, in the order they run:

Step

Runs

Effect on the centre

Header check

every run, before a frame is read

none; reported

Background measurement (--beam-center-check)

every run with the beam-stop pre-scan

none at this point; reported

Second first pass at the measured centre

rotation

adopts the measured centre in the cases listed below

Both centres judged on the merge

rotation, two-pass

adopts the measured centre where its first pass merges better

Post-refinement (§7.5)

rotation, two-pass

refines the centre from the integrated reflections, within 15 px

On most runs the measured centre is reported, the second first pass finds the same lattice at both centres, and the run continues at the file’s centre until post-refinement moves it.

What the file says. Before any frame is read, a centre within one pixel of the geometric centre of the detector, or a whole number of pixels in both coordinates, is reported as a value written rather than measured, and a centre that lands on a masked pixel is a warning — a real beam does not sit on a dead pixel or in a module gap. These lines change nothing.

Measured on every run (--beam-center-check, on by default). The isotropy of the scattered background places the point the beam lands on; the leverage is the curvature of the solvent ring. The fit runs over the mean image the beam-stop pre-scan already builds (§1.5), with the opaque part of the shadow masked, so it costs no frames of its own. For the same reason --detect-beam-stop=off leaves nothing to measure it on, and the check then does nothing.

The fit starts with a whole-detector capture. The centrosymmetry score of the projection about a candidate centre \(\mathbf{c}\), \(\sum_\mathbf{x} I(\mathbf{x})\,I(2\mathbf{c}-\mathbf{x})\), is the self-convolution \((I*I)(2\mathbf{c})\), so one FFT pair scores every candidate centre on the detector at half-pixel spacing: the cost is \(O(N\log N)\) and independent of how far the header is from the truth. The surface scored is the 2D point inversion, which measures the same isotropic background the walk below fits. The beam-stop shadow is blanked out of the scored image, a one-sided opaque obstruction being a centrosymmetry defect in its own right. What comes back is a shortlist and a margin, not a centre: the surface can be locally flat over tens of pixels, and the peak-to-runner-up margin says so. A local walk is then seeded at the capture and refines it; where it declines there it is started again from the file’s centre, and only where neither start gives it something to fit does the capture stand alone. The transforms run on the GPU where one is present and they fit half of the card’s total memory, and on FFTW otherwise, with everything that decides anything shared between the two.

The run log then carries:

  • Beam centre capture: the strongest point-symmetry centre and its margin (under about 3 % the surface is flat).

  • Beam centre check: the file puts the direct beam at (x,y), the scattered background puts it at (x,y) +- σ px - a difference of d px, against the t px this geometry asks the centre to be right to. The comparison is against the direct beam, not the PONI: beam_x_pxl is the point of normal incidence, and the two part by \(D\tan(\mathrm{rot})/p\) as soon as the detector is tilted, while the background is centrosymmetric about where the beam lands. \(t = 0.183\,D\lambda/(p\,a_\mathrm{max})\) is the displacement at which the \(J_0\) factor above has fallen to 0.70 for the longest axis of the cell given with -C (200 Å where none is given); it runs from well under a pixel to several. It is reported, not used as a gate: a centre change far smaller than \(t\) can still decide between a cell and its harmonic.

  • One of three follow-ups: the difference is under three times the fit’s σ (the file’s centre is as good as this measurement can tell); more than \(t\) of it lies across the spindle, where it can cost peaks or an axis; or it is a real difference, mostly along the spindle, where a wrong centre does not announce itself.

None of these lines moves the centre. What consumes the measurement is the second first pass below (rotation runs) and the bound on the post-refinement.

The second first pass (rotation). After the first pass — and after the rotation-axis sign rescue below — the first pass is indexed again at the measured centre, however small the difference. A trial centre gets its own azimuthal mapping, spot engines and spot cache: raw centroids do not move with the centre, but which spots are in the list does (the resolution limit, the ice-ring flag, the beam-stop mask and the strongest-\(N\) ranking are all radial), and the starting centre’s spots are parked and restored so a trial that adopts nothing leaves the run as it was.

The indexed frame count is not used to choose between two centres that both index: acceptance is a fractional-Miller test, so a cell twice as long must place every spot twice as accurately to score the same, and a halved axis can index more frames than the true cell. “Indexes” below means more than half of the validation frames; “same lattice” means the same Bravais class with primitive volumes within 2 %. The outcomes:

  1. The file’s centre indexes and the measured one does not. The file’s centre stands.

  2. Both index the same lattice. The file’s centre is kept, and the log says the difference does not decide this crystal’s cell. A centre off by about one reflection spacing still indexes the same cell, with part of the sweep given indices one out, so where the two centres are further apart than both \(t\) and three σ of the fit, the measured centre is kept as a hypothesis for the merge (next paragraph).

  3. Both index the same cell in a different Bravais class. Whether the centre could have decided the class is arithmetic: a shift of \(n\) pixels of size \(p\) moves an axis of length \(a\) by \(n\,p\,a/(D\lambda)\) relative, and the lattice search holds an axis equality to 3 %. Where the shift is worth that much on the pair of reduced-cell axes the equality compares, both centres are carried to the merge; otherwise the file’s centre and its class are kept.

  4. Both index, on different lattices. Both cells are reported in a warning. Where the primitive volumes differ by an integer factor of 2 to 4 — an axis harmonic, which a centre error along the spindle produces — the choice is made first on the pre-scan’s point-symmetry capture, a second reading of the same background by an estimator that sees neither lattice: where its margin is at least 1.5 % (below ~1 % its surface is flat and its peak can be anywhere), the centre nearer the capture is taken with its cell. Otherwise it is made on the pooled validation spots: the measured centre is adopted where its lattice, larger or smaller, beats chance and puts a share of the spots on itself over its own wrong-spindle null that exceeds the file’s by more than the binomial noise of the two (z = 3.29). Where that does not adopt it, the file’s centre is kept for the first pass and, on a two-pass run, both centres are carried to the merge (next paragraph). Whichever cell a centre brings, the long-axis and sub-lattice hypotheses then test it on its own spots, so a centre is not refused for the harmonic it first indexed.

  5. The file’s centre does not index. Nothing defends it, so:

    • where the measured centre indexes, it is adopted;

    • where it does not, the rotation-axis sign is flipped at the measured centre, since each of the two errors can hide the other; where that indexes, both are adopted;

    • where it still does not, the first-pass depth ladder of §6 (how much of each frame the pass reads) is run at both centres, so the centre moves only when it is the centre that pays. The measured centre is adopted where its lean rung indexes and beats the file’s; where both index the same lattice once less of each frame is read, both centres are carried to the merge; where the file’s centre wins or ties, the depth was the problem and the file’s centre stays;

    • where nothing indexes at either centre, the pooled spots decide as in case 4; failing that, the file’s centre is put back, so a run that fails for some other reason fails at the geometry it was given.

Both centres judged on the merge (rotation, two-pass). Where case 3, 4 or 5 carried both centres, the whole first pass is run again at the measured centre — with its own post-refinement — and the two arms are compared on their search merges (\(P1\), whole range, before the correction surfaces). Where case 2 held a hypothesis, this is done only if the file’s arm merges inconsistently: \(\mathrm{CC}_{1/2}\) below 0.9 in the lowest-resolution shell of its search merge, where every reflection is strong and a consistent merge reads close to 1. The measured centre wins where:

  • both arms ended on the same lattice, and it merges more reflections at \(I/\sigma \ge 2\), or its lowest-shell \(\mathrm{CC}_{1/2}\) is higher by more than 0.05;

  • the arms ended on different lattices, and its search-merge \(\mathrm{CC}_{1/2}\) is higher by more than 0.05.

Otherwise, or where the measured arm does not complete, the run keeps the file’s centre. The log lines are Beam centre check: running the first pass again at the measured centre … followed by … the run adopts the measured centre and the lattice it finds or the measured centre does not win.

After a first pass that failed. A rotation sweep leaves one further thing the input often cannot settle, decided on the same count the rest of the first pass uses — the right answer indexes and the wrong one does not.

  • The rotation-axis sign. A miniCBF header names the axis but gives no direction, and an NXmx vector is only meaningful together with the detector mounting. So after a poor first pass the opposite sign is tried and whichever indexes more validation frames is kept, the flipped one only where its lattice also beats chance on the pooled spots (§4.1), so that one frame against none on a sparse pattern cannot flip it. The decision holds for the rest of the run, and it flips the axis, not the angles, because prediction reads the axis too. It runs before the second first pass above and before the long-axis hypothesis, since with the sign wrong every candidate lattice is wrong.

Post-refinement. On a two-pass rotation run, whatever centre the first pass ends on is refined together with the distance, cell, orientation and axis by the post-refinement of §7.5, and the second pass is integrated there. The background measurement does not move that fit; it only widens where the fit may go: the refined beam is committed only within 15 px of the nearer of the pass-1 centre and the measured one (the measured one counting where its σ is within \(\max(1\ \mathrm{px}, t)\)), so a header that is far out can still be corrected. Where the refined pass is judged worse, the run goes back to the pass-1 geometry.

Stills. There is no second first pass and no post-refinement on stills; the centre is decided before the images are processed, as competing hypotheses tested on the data. Spots are found once on a sample of frames spread over the run, and three centres are tried: the file’s, the background measurement above, and the point-symmetry capture (a second estimator, because the background one is biased where a shadow - a sample-delivery tape, say - covers part of the scattering). Each re-indexes the same spots and is scored by how many land on their frame’s lattice; the file’s centre is kept unless another puts at least 1/0.9 as many there. Where a reference cell is given, or the stills geometry refinement has fitted one de novo (below), the detector distance is a hypothesis too. The spots of the sample are found without resolution limits (a d-spacing depends on the distance being checked) and spots piled up at one radius - a powder ring - are left out. A scan over 30-3000 mm in 2.5 % steps at every centre candidate finds the peaks, the strongest are looked at more closely and a finer step about the best decides against the file’s distance, which is kept unless the best puts at least 1/0.9 as many spots on the lattice; a local grid of centres follows at the distance decided. The range is in millimetres, not in multiples of the file’s value, so a stated camera length that is nominal or wrong does not limit where the search looks, and an input that states no distance (an XTC) is searched too. The spot count is flat to a percent or two about the right distance, so with -C the same sample is also indexed de novo at the distance decided: a frame’s de novo cell takes up the distance’s error in its scale, and the distance at which the cell given has the volume of the frames’ cell is taken where it puts at least 0.9 times as many sampled spots on the lattice and lies more than half the 1 % fine step from the distance decided. The same de novo cell, as a known cell, is the frames’ evidence on the cell given (§7.7 of the indexing page). A distance given with --detector-distance is held: it is neither searched nor refined. Without a cell nothing is searched in distance: on its own a wrong distance indexes as a wrong cell, not as fewer indexed spots. The stills geometry refinement, --refine-geometry, bundle-adjusts the centre and the distance together with the cell over strongly indexed frames (§7.7); it is on by default for all stills. Without a reference cell it anchors on the cell most of the sampled frames index to de novo (the frames on it are the ones fitted), and that cell serves the geometry steps only: the run itself is still indexed de novo.

What ends up in the output. The report’s BEAM_CENTRE (the PONI) and DIRECT_BEAM are the geometry the result was integrated at, and so is JFJOCH_DATASET_SETTINGS; POSTREFINE_BEAM_CENTRE gives the post-refinement’s move as before -> after. Which of the steps above changed the centre, and why, is in the run log only.

Options.

  • --beam-x/--beam-y set the starting centre. The background check still runs and can still adopt the measured centre in the cases above; add --beam-center-check=off to hold a typed centre until post-refinement.

  • --beam-center-check=off skips the background measurement and the second first pass, and removes the measured centre from the post-refinement bound.

  • --detect-beam-stop=off removes the projection the background measurement is read from.

  • --rotation-no-postrefine removes the post-refinement, and with it the merge-judged arms.

1.5 Finding the beam stop

The beam stop and its holder arm shadow part of the detector. A reflection behind them is attenuated but otherwise ordinary — it integrates low, with a plausible \(\sigma\), and no outlier test catches it — so the shadow is found and masked instead. --detect-beam-stop[=N|off] (on by default, \(N=60\) frames) projects those frames to a per-pixel mean and maximum, and writes the result into the pixel mask as bit 9, from where it excludes those pixels from every later stage.

The shadow is a place where the background is missing, so it is found by comparing each pixel’s background against the background at the same \(2\theta\). The mean is pooled over a small box first — a single pixel of a sparse background carries too few counts to tell a shadow from a Poisson hole, and the stop is much wider than the box — and the comparison is against the median of the pixel’s own ring, taken over the pixels not already excluded and iterated a few times so the shadow stays out of the baseline it is measured against. A pixel is shadow when the ratio falls below 0.50 and the deficit is significant against its own Poisson scatter, \(\sqrt{2\,(E-N+N\ln(N/E))}\) over the pooled counts, taken in photons (on a detector read in ADU the counts are divided by its gain, as the protected reflection count of 25 photons is multiplied by it), with the pooled count taken as at least zero: on frames taken with the shutter closed the pixels scatter about zero, and a pooled sum below zero is no deficit of photons. A ratio says nothing when the background behind it is a handful of photons, and it is that significance that makes the comparison scale-free rather than tuned to one exposure: rebuilt from six frames of a low-background sweep, the same ratio without it masks three quarters of the detector. The index of dispersion does not do this job — it is 1.0 inside the shadow and 1.0 outside it, a shadowed pixel being Poisson at a low rate and a lit one Poisson at a high rate — only the rate relative to the ring separates them.

A ring is a cone of constant \(2\theta\), indexed by \(D\tan 2\theta\) in pixels. On an untilted detector that is a circle about the beam centre; on a tilted one — a swung \(2\theta\) arm — it is not, and a circle about the centre runs across the background’s own fall-off with \(2\theta\): at a 5° swing and 50 mm that put a quarter of the detector in the shadow.

Nothing assumes the stop and the beam are concentric, because only the per-ring comparison is used; a ring lying wholly inside the stop has no unshadowed pixel for its median to find, which is exactly the case where the comparison must fail. Such a ring is judged against what this detector’s background typically is — the median over the rings the walk is willing to judge — and is shadow in its entirety when it falls far below that. Comparing it instead against the largest background further out reads an ordinary background inside a strong ring as blocked, and the walk then runs out to that ring and returns a filled disk of good detector with diffraction rings plainly visible inside it.

The rings are drawn about the centre the data measure, not the one the file claims. Displacing the centre costs nothing for tens of pixels and a great deal beyond: at 150 px out the comparison describes the background’s own radial fall-off rather than the hardware, and returns a tenth of the detector as shadow with nothing blocking it — and header centres are wrong by that much. The centre is therefore fitted from the same per-pixel mean the mask is computed from, before the mask is read, and named to the finder; it costs no frame of its own. That first fit is itself biased by the shadow it has not yet masked (on a sweep with a third of the detector behind a pin it landed 5 px out and called itself 0.40 px), and it does not have to be unbiased: the ring comparison does not notice tens of pixels, and the centre the run reports and consumes is the second fit of §1.4, the one that runs after the mask is loaded with the shadow out of the way. The order is fit, mask, fit, and only the second answer leaves. Two rounds are enough, measured rather than assumed — on clean sweeps the two fits agree to 0.03 px, so a third would draw the same rings.

A ring is only flat once the polarization is divided out. The comparison assumes the background is flat around a ring with nothing in the beam, and it is not: a polarized source suppresses the background in its own plane by the azimuthal factor of §2.2, a factor of three at \(2\theta=55°\) and four at \(70°\) — several times the dip the test is looking for, so on a short-distance geometry the two in-plane lobes of every outer ring read as shadow (measured: 5 % and 11 % of two detectors, with nothing visible under either mask). The mean projection is therefore divided by that factor before the ring comparison, and the Poisson deficit multiplies it back in so the significance is still the significance of the counts that were recorded. The factor is the geometry’s own, evaluated about the centre just fitted rather than the one in the file, because the geometry is what knows where the polarization plane lies once the detector is tilted, the stored image quarter-turned or the detector rotated in its own plane. On a tilted detector the solid angle of a pixel varies along a ring too — by tens of per cent at a 5° swing and 50 mm — so the mean is divided as well by the pixel’s solid angle over the one an untilted detector has at the same \(2\theta\), \((D/l_z)^3\) with \(l_z\) the pixel’s distance along the beam, which is exactly 1 untilted; the Poisson deficit multiplies that back in as it does the polarization. Detector response and air absorption are functions of \(2\theta\) alone, nearly enough, and the ring median absorbs them.

What survives is then shaped into a region, and what makes it specific is size, not connection to the beam. A shadow is cast by something physical and is correspondingly large, while the background wanders a pixel or two at a time, so the connected components holding at least 2000 pixels, of which at least 200 deep (well below the ring’s level, not merely dim), are kept and the rest dropped; on a clean sweep that returns exactly one such component — the beam stop — and a spurious candidate is at most a few dozen pixels. Requiring the region to touch the direct beam instead is written for the stop and its holder arm; hardware standing in the beam further out — a pin, a loop — casts a shadow that begins some way out in radius, with lit detector between it and the stop and no bridge across the gap, and such a shadow would then go unmasked and be integrated as measured-and-near-zero. The kept components are bridged across the module gaps the holder arm crosses, grown outward through the partially shadowed penumbra — much wider for a pin than for a stop edge — closed, and with the interior of the disk filled; the rings found lying wholly inside the stop join the region after the size filter rather than being asked to be large themselves.

Last, any pixel that ever recorded a real reflection — a maximum over the frames well above background, in a cluster, so that a single-frame zinger does not count — is given back, because a beam stop cannot have blocked a reflection that was measured.

Pixels the finder reports that hold the detector’s no-data mark (a PILATUS module gap stored as \(-1\)) are the darkest pixels there are, but they are not shadow: they are masked as dead (bit 10) instead, so that the reported shadow share is the shadow’s and the test below does not drop every reflection a module gap clips. A mean of zero is not taken as dead, since a deep shadow on a still counts nothing.

A reflection whose signal disk reaches into the shadow is not integrated. The profile fit keeps a disk that lost pixels to the mask and fits the pixels that remain (§9.3), which is right for a gap or a dead pixel but not for the shadow: the mask is drawn where the background is dimmed, and the Bragg half-shadow does not end there, so the rest of such a disk is attenuated too - measured against the symmetry mates, such observations read low by 12-60 %. The test is made where each image is integrated, so rotation, stills, the _process.h5 and --mode scale see the same reflections; with no shadow in the mask (the broker) it does nothing.

1.6 Defective pixels

A pixel that reads high frame after frame, whatever the crystal does, is integrated into whichever reflection’s box it falls in; under rotation that is one pixel collecting a different reflection on every frame that reaches it, and a merged intensity hundreds or thousands of times its shell mean, carried by one or two observations the merge’s outlier test cannot judge. The file’s mask misses such pixels on many detectors, so Rugnux measures them on the pre-scan’s own sample of frames on every run (the hot and unstable rules need a rotation, where a reflection moves off a pixel and a defect does not; dead pixels and those holding the detector’s error value are measured on stills too) (HotPixelFinder, image_analysis/hot_pixels/HotPixels.h) and masks them as bit 10. The frames are read a second time for it, once the beam-stop projection has measured where the scattered background puts the beam: the rings have to be drawn about the true beam, and a file’s centre can be far enough out that a ring crosses the background’s radial fall-off.

On each frame a pixel is lit when it exceeds \(b + 3.3\,\max(\sqrt{b}, 1.4826\,\mathrm{MAD}) + 2\), with \(b\) the larger of the median of its 2 px iso-\(2\theta\) ring and of that ring’s sixteenth in azimuth, so ice and powder rings, the polarization dip and partial shadows set their own level. It is persistent when it is lit on at least \(\max(k_1, k_B)\) of the sampled frames: one reflection stays on a pixel for \((\Delta\phi + w)/|\zeta|\) of rotation (\(w = 5°\), a generous rocking width), which covers fewer than \(k_1 = 1 + \lceil (\Delta\phi + w)/(|\zeta|\,\delta) \rceil\) frames sampled \(\delta\) apart; and \(k_B\) is the binomial bound, from the lit rate of the ring’s other pixels, that fewer than 0.01 pixels of the whole detector reach by chance. A persistent pixel is masked if it reads on average at least ten times its ring and its mean excess is above the Poisson bound; a weaker one cannot make an outlier. This holds for a patch of such pixels as for a lone one: a patch lit through the whole sweep is stationary in the lab, so it is no reflection of the rotating crystal, and a reflection crossing it would read the patch. Pixels holding the detector’s error value on most frames (already invalid on every frame, but not in the static mask) are masked with them, as are dead pixels (reading at most half of their ring’s level frame after frame), unstable ones (far below zero on a twentieth of their frames - no photon makes a count negative) and pixels stuck at saturation. A CCD (read with an offset, not Poisson) needs no rule of its own: its dead pixels read the offset, far below any ring with background on it, and a hot one ten times its ring. One log line says how many pixels were masked and why.

Outside a CCD’s active area. An input in detector units whose background shows no photon peaks (a CCD, an image plate or another integrating detector read through an amplifier) has read noise on every live pixel, so no live pixel reads the same value on all 16 frames the detector gain is measured on. A pixel that does lies outside the active area - the corners of a round CCD, a border or seam the detector’s corrections leave at zero - and is masked as inactive (bit 11) before the run starts. A test that compares a pixel with its own resolution ring cannot see such an area: beyond the circle of a round CCD the whole ring reads zero. It is not made where the pixels that do vary read zero on 1 % or more of their readings (counted photons, or a file cut at a threshold), since a pixel at zero on every frame may then simply have had nothing to record. The beam-stop finder (§1.5) reads these pixels as the input has them, because a CCD reads the deep shadow of a beam stop at one value too.

1.7 The saturation level

A detector that saturates clips every value beyond its ceiling down to it, so on a frame’s bright tail - the cores of Bragg peaks, which otherwise fall off steadily with value - the values pile up just below where they stop. Where each pixel has its own ceiling (an ADC limit less that pixel’s dark), the pile-up is a band, and its lower edge is where clipping starts. A file’s own statement of the limit is often missing or wrong for detectors outside the facility that wrote it, so on stills Rugnux reads it off the values: a histogram of pixel values on a sample of frames, binned on a log scale, and the lowest bin that rises above the tail below it. Pixels from there on are treated as overloaded where that level is below the file’s; the file’s is kept for a file Jungfraujoch wrote, whose limit is the detector’s own, and when --saturation is given. The log states both values. Where an XFEL file states no limit at all, the reader holds the values to their integer type’s range.


2. Azimuthal integration (radial profiles)

Azimuthal integration produces a radial profile \(I(q)\) or \(I(d)\) by histogramming pixels into radial bins. Pixels are not split across bins; each pixel contributes wholly to a single bin. By default the profile is purely radial (a single azimuthal bin), but the azimuth can optionally be split into up to 512 \(\phi\) sectors (azim_bins, --azim-phi-bins), giving a 2D \(q\times\phi\) profile that exposes azimuthal anisotropy such as detector shadowing or sample texture.

The \(q\) bins run from the low to the high \(q\) limit and are laid out in one of two ways. Linear (the default) gives bins of equal width in \(q\), set either by the spacing (q_spacing, --azim-q-spacing) or by the number of bins (q_bins, --azim-q-bins); with a spacing that does not divide the range the last bin is cut at the high limit. Logarithmic (q_binning = log10, --azim-q-binning log10) gives \(B_q\) bins equally spaced in \(\log_{10} q\), with edges \(q_i = q_\mathrm{low}\,(q_\mathrm{high}/q_\mathrm{low})^{i/B_q}\), so a bin’s width grows in proportion to its \(q\) — dense sampling where the features of small-angle scattering are, coarse sampling at high \(q\); it needs the number of bins. The \(q\) reported for a bin (bin_to_q) is its centre on the binning scale: the arithmetic mean of its edges for linear bins, the geometric mean for logarithmic ones. The adaptive spot finder and the ice-ring score read their per-ring background off these same bins, so coarse logarithmic bins at high \(q\) coarsen them as well.

2.1 Histogram estimator

Let bin index \(b(x,y)\) be precomputed from \(q(x,y)\) (or equivalently from \(d(x,y)\)) and, when \(\phi\) sectors are enabled, the azimuth \(\phi(x,y)\) — so \(b = b_q + b_\phi B_q\). For each bin \(b\):

  • accumulate corrected intensity and its square: \( S_b = \sum_{(x,y):\,b(x,y)=b} I(x,y)\,C(x,y),\qquad S^{(2)}_b = \sum I(x,y)^2\,C(x,y)^2, \)

  • and count: \( N_b = \#\{(x,y):\,b(x,y)=b \text{ and pixel is valid}\}. \)

The profile reports both the mean \(\bar{I}_b = S_b / N_b\) (when \(N_b>0\)) and a per-bin sample standard deviation \(\sigma_b = \sqrt{(S^{(2)}_b - S_b^2/N_b)/(N_b-1)}\) (a spread/error estimate for each radial point). Invalid pixels (masked, saturated, detector error codes) are excluded.

2.2 Corrections applied

Two standard corrections are available:

(i) Solid angle / geometric correction. A flat pixel’s solid angle falls off with the incidence angle \(\alpha\) between the scattered ray and the detector normal. With the in-plane detector offsets \(u=(x-x_\mathrm{beam})p\) and \(v=(y-y_\mathrm{beam})p\) — measured from the PONI (§1.1), which is what the tilt-invariance below rests on — and detector distance \(D\), \( \cos\alpha = \frac{D}{\sqrt{u^2+v^2+D^2}},\qquad C_\Omega = \cos^3\alpha, \) applied — like the polarization term below — as a divisor (intensities are scaled by \(1/\cos^3\alpha\)), so pixels at oblique incidence, which subtend a smaller solid angle, are boosted. Because \(\alpha\) is evaluated in the detector’s own frame it is invariant under detector tilt (\(\mathrm{rot1}/\mathrm{rot2}/\mathrm{rot3}\)), matching PyFAI’s solidAngleArray and MAX IV azint. It reduces to the commonly quoted \(\cos^3(2\theta)\) form only for an untilted detector, where the incidence angle coincides with the scattering angle.

(ii) Polarization correction. With polarization coefficient \(P\) (beamline dependent) and azimuth \(\phi\): \( C_\mathrm{pol}(2\theta,\phi) = \frac{1}{2}\left(1+\cos^2(2\theta) - P\cos(2\phi)\left(1-\cos^2(2\theta)\right)\right), \) applied as a divisor to intensities (i.e. scale by \(1/C_\mathrm{pol}\)) when enabled. This is the factor of Kahn et al. (1982); \(\phi\) is the azimuth in the lab frame, so the correction follows detector tilt and a swung-out \(2\theta\) arm without further work.

The polarization plane is taken to contain the lab \(x\) axis — a horizontally polarized source. A vertically polarized one is expressed by a negative \(P\): flipping the sign of the \(\cos 2\phi\) term is exactly a \(90^\circ\) rotation of the plane. \(P\) is the polarization degree (XDS’s FRACTION_OF_POLARIZATION is \((1+P)/2\)). It is not fitted, because a single dataset does not determine it, so it comes from the file where the file states it: a miniCBF # Polarization line and a d*TREK SOURCE_POLARZ both give the fraction \(f\), read as \(P = 2f - 1\) (so a laboratory tube’s 0.5 is unpolarized), and SOURCE_POLARZ also gives the plane’s normal, which sets the sign. Where the file says nothing (ADSC SMV, marCCD, NXmx) the default \(P = 0.99\), an undulator value, applies, with the plane horizontal. The plane, unlike the degree, is measured: the beam-stop pre-scan compares the background’s \(\cos 2\phi\) harmonic with the profile a polarized source gives it, and where the background clearly follows the other plane (correlation above 0.5 and at least 0.3 of a fully polarized source’s modulation, but under twice it, which no source can give) the stated degree is applied in that plane - to the shadow test and, from then on, to the integration and every other correction of the run. Elsewhere the plane stays as stated, so a run whose beam stop is not detected (--detect-beam-stop=off) keeps the stated one. The background is pooled over 9 x 9 pixels before the comparison, so that a sparse background - a fraction of a count per pixel over the frames read, as on a large photon-counting detector - still gives the sectors a level. The same decision is made for rotation sweeps and stills, and the log reports the correlation and the scale (Polarization plane:) on every run that detects the beam stop. Bending-magnet and wiggler beamlines are typically lower (0.8–0.95), and a known value for one should be passed with --polarization.

2.3 Background estimate for profiles

A background estimate is derived from the profile as its mean intensity over a fixed low-to-mid \(Q\) window (default \(2\pi/5\) to \(2\pi/3\) Å\(^{-1}\)). This background is used for monitoring and diagnostics; it is not the same as the local Bragg-spot background used in summation integration (§9.2).


3. Spot finding (strong pixels → Bragg spots)

Spot finding is a two-stage process:

  1. Strong-pixel selection using intensity and/or local signal-to-noise criteria.

  2. Connected-component labeling (CCL) to group strong pixels into candidate spots, followed by spot-level filtering and feature extraction.

3.1 Strong-pixel detection by local statistics

For each pixel \(i\) with value \(v_i\), consider a square window (nominally \(31\times 31\) pixels) around it. Let the window contain \(n\) valid pixels (excluding masked/bad/saturated), and define: \( \Sigma = \sum v,\qquad \Sigma_2 = \sum v^2. \)

To avoid biasing the local statistics by the test pixel itself, Jungfraujoch evaluates the pixel against the window with the pixel removed: \( \Sigma' = \Sigma - v_i,\quad \Sigma_2' = \Sigma_2 - v_i^2,\quad n' = n-1. \)

A variance-like quantity proportional to \(n'^2\) is formed: \( V = n'\Sigma_2' - (\Sigma')^2, \) and the deviation-from-mean quantity: \( \Delta = v_i n' - \Sigma'. \)

A pixel is considered strong if:

  • it is above a photon/count threshold, and

  • its window contains enough valid neighbours (more than 100), so the local statistics are meaningful, and

  • \(\Delta>0\), and

  • the squared deviation exceeds a scaled variance: \( \Delta^2 > V\cdot T^2, \) where \(T\) is the configured signal-to-noise threshold.

This is equivalent to a local z-score criterion but implemented in integer arithmetic to be robust and fast.

The test is applied in two passes over the image. The first is as described above. The second repeats it with every pixel found strong by the first excluded from the local background — it is treated exactly like a saturated pixel, so it contributes to no window it falls into and stays strong itself. This matters for any spot wide enough to reach into its own background box: on a single pass such a spot inflates the mean and variance it is then tested against, and its outer pixels fail the criterion. Excluding the core recovers them, so the spot is reported with its true extent rather than its brightest few pixels. Both the CPU and GPU implementations run these two passes and return the same spot list for the same frame.

Special cases:

  • saturated pixels can be forced to “strong” (useful for detecting overloaded Bragg spots),

  • invalid pixels are never strong.

3.2 Adaptive (self-calibrating) detection

The local-statistics test above needs a fixed photon/count threshold whose correct value depends on the background level, which varies between datasets. The adaptive mode (--adaptive-spots; the default in rugnux and in the viewer for both stills and rotation data, --no-adaptive-spots reverts) derives that threshold from each image’s own noise, per resolution ring, so no per-dataset value is needed. It admits more spots than the fixed threshold, including genuine reflections that belong to no indexed lattice; these are down-weighted rather than filtered in the per-image geometry fit (§7.4).

Pixels are binned into the same resolution rings as the azimuthal integrator (§2). For each ring a robust background is estimated in three passes: one plain pass over all valid pixels, then two \(\sigma\)-clipping passes that keep only pixels within \(\pm 3\sigma\) of the current ring mean (removing the Bragg peaks from the background estimate). This yields a per-ring background mean \(\mu_b\) and scatter \(\sigma_b\).

The ring’s detection threshold is the larger of two arms, \( t_b = \max\!\big(\;\mu_b + z\,\sqrt{\sigma_b^2 + \sigma_\mathrm{read}^2}\;,\;\; k_\mathrm{Poisson}(\mu_b, p)\;\big), \) where \(k_\mathrm{Poisson}(\mu_b,p)\) is the smallest count whose Poisson\((\mu_b)\) upper tail is \(\le p\). The Poisson arm is correct where the background is countable (a bright low-resolution ring gets a high threshold); the Gaussian arm — floored by a detector-level excess-noise constant \(\sigma_\mathrm{read}\) — takes over on near-empty high-resolution rings, where the Poisson arm degenerates to “one photon is significant” and would flood. The operating point \(p = E/N\) is set from a single portable knob \(E\), the expected number of false pixels tolerated per frame (--spot-false-pixels, default 100), with \(N\) the number of valid pixels. Because \(p\) and every \(\mu_b,\sigma_b\) come from the image itself, the same \(E\) lands a sensible photon threshold on strong and weak datasets alike, with no per-dataset tuning. Rings too sparse to characterise (fewer than ~40 pixels) fall back to a whole-frame background. A pixel is strong when \(v_i \ge t_b\) for its ring (saturated pixels are still forced strong); the strong pixels then feed the same CCL stage (§3.4). The ring threshold replaces the photon-count floor of §3.1; the local signal-to-noise test of §3.1 is still applied on top of it (unless --spot-sigma 0), so a strong pixel must pass both.

Because detection reads the pixel’s ring, a pixel that falls outside the azimuthal-integration \(q\) range has no ring and can never be strong: the integration range bounds what adaptive detection can see. Both upper limits are therefore optional and default to the detector itself — the azimuthal integration runs to the highest \(q\) any pixel of the detector reaches (--azim-max-q unset), and spot finding is not clipped in resolution (--spot-high-resolution unset), for rotation data as well as stills. Setting either one narrows detection accordingly — appropriate for weak, high-background data, where the spots admitted at the detector edge are dominated by noise.

Fused GPU engine. The per-ring reduction the adaptive threshold needs is the same reduction the azimuthal integrator performs. On the GPU path the two are fused into a single image pass (AdaptiveSpotFinderGPU): one reduction accumulates the corrected per-ring sums for the azimuthal profile (§2) and the raw per-ring statistics for the threshold, after which a light kernel flags the strong pixels. One GPU pass therefore replaces both the separate azimuthal-integration pass and the host-side adaptive spot-finding pass, at a small fraction of the CPU finder’s cost per frame and producing the same spot list and azimuthal profile. It is enabled by default in the offline rugnux path, the interactive viewer and the online receiver.

Online. spot_finding_settings in the REST API carries adaptive_threshold and false_pixels_per_frame, so the mode is reachable from the broker and from the web frontend as well as from rugnux and the viewer. It defaults to off online, unlike rugnux and the viewer, because the broker serves both workflows and only one of them can run it: spots are found in software on the DECTRIS/SIMPLON path, while the JUNGFRAU and EIGER workflows find them on the FPGA at its own fixed threshold - except the live stills analysis of a JUNGFRAU collection, which analyses the converted frames on the GPU and always uses the adaptive threshold. Setting adaptive_threshold on an FPGA workflow is otherwise accepted and ignored, so the same spot-finding settings can be shared across detectors.

3.3 Resolution and ice-ring handling

Spot finding can be restricted to a resolution range \([d_\mathrm{high}, d_\mathrm{low}]\) by masking pixels outside the range. Optionally, spots in identified ice-ring regions can be tagged so that subsequent indexing/refinement may include or exclude them (see §4 and §6).

A single per-image ice-ring score is derived from a radial profile: for each hexagonal-ice powder ring (see Where the ring positions come from below), the profile intensity at the ring is divided by a smooth background estimated from the whole profile — a running median of the non-ice bins, interpolated under each ring — and the strongest ring’s ratio is reported (1 = no ice, \(>1\) = ice above background). A whole-profile background is used rather than a couple of adjacent shoulder bins so the estimate is robust to the radial binning: at a coarse Q-spacing a local shoulder can be only ~1 bin and would double-count the ring’s own edge (offline processing defaults to a fine 0.01 Å⁻¹ spacing — in \(q = 2\pi/d\), like every \(q\) in this document (§1.2) — --azim-q-spacing, so the rings are well resolved). The reported quantity is the ice magnitude rather than a significance: with many photons any real ice ring is statistically significant, so significance does not discriminate.

The profile the score is read off is the peak-excluded one, not the plain azimuthal integration: where adaptive spot finding runs (§3.2 — the offline and viewer default), the score uses the sigma-clipped per-resolution-ring background that finder already computes for its threshold. This matters more than it sounds. A plain azimuthal profile is a per-ring mean, so a few strong low-resolution reflections landing in a ring’s bin raise it exactly as ice would; measured over a rotation battery, that alone ranked ice-free crystals above crystals that really are iced. An ice ring is azimuthally smooth and survives the sigma clip, while Bragg peaks do not, so on the clipped profile ice-free crystals sit near 1 and crystals with confirmed ice above 2. Only where no adaptive finder ran (the FPGA workflow) does the score fall back to the plain profile.

The radial profile sees ice only as a smooth powder ring. Ice in large crystallites diffracts as discrete spots, leaves the profile flat, and is invisible to the score above, so a second channel is read from the spot list itself: the spots found on the ice bands are counted against the spots found in the ice-free flanks \([w,2w)\) either side of each band, rescaled to the bands’ own \(q\) width (a flank landing on another ring is dropped with its width). The indicator is the ratio pooled over the run — per image the control is a handful of spots and the ratio means nothing — and it is taken before the spot-count filter, which orders ice spots last and would discard them first. The two channels barely overlap: smooth ice reads high on the profile and ~1 on the spots, textured ice the reverse, and a clean crystal ~1 on both. Both counts are stored per image (spot_count_ice_rings, spot_count_ice_control; HDF5 /entry/MX/peakCountIceRingRes, /entry/MX/peakCountIceRingControl).

Both channels are used offline as a gate on ice handling: unless the run reaches --ice-min-score (default 1.5) on the profile or --ice-min-spot-ratio (default 2.0) on the spots — --ice-min-spot-ratio 0 disables the spot channel, while --ice-min-score 0 leaves the gate always open — ice-ring flagging and the exclusion from the scale fit (§10.10) are skipped. The fixed bands cover 16–26 % of the unique reflections at typical resolutions whether or not the crystal has ice, and more than that on a detector reaching past 1.5 Å, so handling ice on a clean crystal is a pure loss. The flagging itself (--detect-ice-rings) defaults on for rotation data and off for stills unless the file says otherwise.

Where the ring positions come from. The eleven bands from 3.895 to 1.522 Å are the measured positions of Moreau, Atakisi & Thorne (Acta Cryst D77, 2021, 540–554). That list ends at 1.522 Å by its own scope — the paper states that hexagonal ice “has 11 diffraction rings between 4 and 1.5 Å resolution”, and its subject was detecting ice in deposited data rather than masking it — not because ice stops there. On a detector that reaches further, the rings it does not list are the ones left in the data.

The eight bands below it are calculated, since past that paper there is nothing measured to copy. Enumerating \(hkl\) from the ice Ih cell is not enough: ice Ih is \(P6_3/mmc\) with oxygen on \(4f\), and most of what enumeration emits is extinguished by the oxygen sublattice rather than by the space group — which is why (004) at 1.830 Å and (104) at 1.657 Å are missing from the measured list even though they lie inside its range and its reflection conditions allow them (for even \(l\) the \(4f\) structure factor carries a factor \(\cos 2\pi l z\) at every \(hk\), and \(z \approx 1/16\) kills \(l=4\) — \((104)\) along with \((004)\)). Structure factors are computed instead — oxygen only, the hydrogens being half-occupancy disordered and weak to X-rays — and the lines kept are those reaching 3 % of the strongest. That rule reproduces the measured eleven exactly, and every line it drops inside their range computes to zero, which is what makes it trustworthy below 1.522 Å. The cell is that of Röttger et al. (Acta Cryst B50, 1994, 644–648). The list stops at 1.170 Å because below it the calculated real lines fall to 2–3 % while the extinct ones rise to about 1 %, and an oxygen-only calculation cannot separate them any further.

One consequence is worth stating: the profile score is the strongest ring’s ratio, a maximum over the bands, so a longer list can only raise it. The gate at 1.5 is therefore read against a list of this length, and lengthening it again would need the gate re-checked.

Rings this sample actually shows. Hexagonal ice is the only phase whose rings can be named in advance, and it is not the only thing that powders: a shower of microcrystals around the crystal, or a salt out of the cryoprotectant, leaves the same textured rings at \(d\)-spacings no fixed list carries, and their spots are otherwise handed to the indexer as if they were this crystal’s. The rings are therefore also measured from the run’s own pre-scan spots — read off as what stands above the smooth fall-off of spot density with \(q\) — on every run, and reported whether or not anything acted on them (POWDER_* in the results report: the ring count, the fraction of the pre-scan’s spots they hold, and their \(d\)-spacings). The two lists are not the same list: a crystal can carry measured rings that are not ice beside those that are. A measured ring is set aside from indexing only where a first pass that found no lattice needs it set aside (§6); the fixed ice bands above are what the ice score, the scale fit and the resolution cut read.

A further optional safeguard removes isolated high-resolution “spur” spots by detecting large gaps in \(1/d\) (or \(q\)) space and discarding spots beyond the gap. This is intended for macromolecular diffraction where edge-of-detector backgrounds can be extremely low.

3.4 Connected-component labeling (CCL)

Strong pixels are grouped into connected components (adjacent strong pixels) using a CCL algorithm. Each component yields a candidate spot with:

  • centroid \((x,y)\) (often intensity-weighted),

  • pixel count (spot size),

  • integrated spot intensity proxy (sum of pixel values),

  • resolution \(d\) at the centroid (or mean over pixels),

  • and quality flags (e.g. ice-ring classification).

Spot-level filters include minimum/maximum pixel count and resolution limits.

The upper bound is on how large a round spot may be, not on how bright one may be. Under the self-calibrating threshold (§3.2) a component’s area above the contour grows as \(\sigma^2\ln(A/T)\) — without bound in the peak amplitude \(A\) — so an upper bound on pixel count alone becomes an intensity ceiling: measured on a strongly diffracting crystal, footprints run 3 px at 30–100 counts to 50 px above 10 000, four times the slope the fixed local-box test gives, and the old bound of 50 discarded the brightest reflections on every image. The bound is therefore 200 (the same as CrystFEL peakfinder8’s --max-pix-count; XDS has no such parameter at all and guards on shape instead, with SPOT_MAXIMUM-CENTROID), and a component above 50 pixels must in addition fill at least a fifth of the square its bounding box fits inside. A Bragg reflection is round and fills about half of that square however bright it is; an ice arc, a cosmic-ray track or a lit detector row fills a fifth or less, which is what an upper bound was ever protecting against. Below 50 pixels no shape is asked for, so everything accepted before still is. The shape test is inert on every dataset it has been measured on — it exists to bound the shape of what the larger size bound now admits, on data carrying arcs or tracks, not because the crystals measured here needed it. The test is integer arithmetic, so the host and the GPU extractor agree by construction.

The host implementation (StrongPixelSet::sparseccl) is the SparseCCL of the ACTS/traccc project: it runs over the strong pixels sorted row-major, uses a sliding window over the previous line and a union-find whose root is each component’s lowest index. On the GPU the same labelling runs on the device (SpotExtractorGPU): the packed strong-pixel bitmask is compacted into that same sorted list without leaving the card, each pixel finds its at most four earlier 8-neighbours by binary search, and a lock-free union-find with path halving labels them. Only the finished spot list — a few hundred entries — comes back to the host, instead of the whole bitmask (2.26 MB per frame at 18 MP). The two implementations produce the same components, in the same order, with the same pixel counts and intensities; tests/SpotExtractorGPUParityTest.cpp holds them to it. The device version is also insensitive to frame content: the host sliding window becomes quadratic when many pixels light up in one detector line — a hot module, or a diffraction ring where it runs tangent to a row — which costs tens to hundreds of milliseconds on such a frame, while the device version stays under a millisecond.

3.5 Adaptive per-image minimum spot size

The minimum-pixels-per-spot filter (§3.4) trades sensitivity against noise: a small value keeps faint one- or two-pixel spots — real signal on strong data, but detector noise on high-background frames — while a larger value keeps only well-formed spots. The best value is dataset-dependent, so for serial-stills indexing it can be chosen per image rather than fixed. The frame is scored at min-pix 2, 3 and 1, and the setting that maximises

\[ \frac{n_\mathrm{indexed}^2}{n_\mathrm{total}} \quad\text{(indexed-spot count weighted by indexed fraction)} \]

is kept; the frame is then integrated once at that min-pix. The lattice is searched for only once per frame: the indexer runs on the min-pix 2 list (on min-pix 3 where that does not index), and the lattice of the first list that indexes is then refined and scored on the other lists - the lists are one crystal seen at different min-pix, and where several index, the searches return the same lattice. De novo, the min-pix 1 list is searched on its own only where the min-pix 2 list holds enough spots to index (the viable-cell minimum): a frame with almost no spot of two pixels has only single pixels to offer, and the cells a free search fits to those were measured to be unrelated to the crystal’s. Against a known cell it is always searched - on sparse serial data such frames are real hits. The fraction factor discounts the extra spots a smaller min-pix admits unless the lattice actually explains them, so strong frames keep their real weak spots (extending resolution) while noise-flooded frames stay strict. Because min-pix filters the connected components after detection, strong-pixel detection AND the connected-component labelling both run once per frame, and the three attempts only repeat the spot-level filter; the azimuthal profile is the one that single detection pass computed. The winning attempt’s spot list is kept rather than re-extracted, so the frame that is integrated is exactly the frame that was scored. This is a stills-only, indexing-path option — rotation indexing builds one global lattice from all frames and keeps a fixed min-pix. In rugnux it is the default; giving an explicit --min-pix-per-spot pins a fixed value instead.

3.6 Predicting the resolution the merged data will reach

A per-image resolution estimate is read off the finished spot list. It predicts how far the merged data will reach, not how far the furthest spot on this image lies. Each non-ice spot is weighted by \(\sqrt{I}\) — the intensity is a summed photon count, so \(\sqrt{I}\) is its Poisson significance — the \(1/d^2\) is found beyond which a fraction \(f=0.30\) of that weight lies, and the estimate is that resolution taken \(2.25\times\) further in \(1/d\). It is deliberately not limited to what the detector records: the quantile sits in the middle of the fall-off, well inside the recorded range, so it goes on measuring the crystal where the detector stops before the diffraction does, and on such a run it reads finer than the detector corner. The dataset value is the median over images.

Both constants carry a mechanism. A quantile from the middle of the distribution measures the shape of the fall-off, which is the crystal’s own \(\exp(-B/2d^{2})\), where the extreme end of it measures where detection stops — a threshold that moves with the exposure and with how many reflections the unit cell puts on a frame. And merging averages many observations of each reflection, so intensities go on being measurable a fixed factor in \(1/d\) past the point at which one image’s spot finder still detects them; that factor is the \(2.25\). Both are calibrated on rotation data against the resolution at which per-shell CC1/2 falls through 0.30, and the estimate is good to about 0.2 Å there. It is a prediction and not a measurement of what a run achieved: nothing downstream is cut on it, and it is reported alone (Rugnux SPOT_RESOLUTION_ESTIMATE, and per image in the stream, the plots and HDF5).

\ No newline at end of file diff --git a/CPU_DATA_ANALYSIS_INDEXING.html b/CPU_DATA_ANALYSIS_INDEXING.html new file mode 100644 index 000000000..71de41eb3 --- /dev/null +++ b/CPU_DATA_ANALYSIS_INDEXING.html @@ -0,0 +1 @@ + Data analysis: indexing and geometry (§4–§7) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Data analysis: indexing and geometry (§4–§7)

Part of the CPU/GPU data-analysis reference; the section numbers are continuous across its parts.

4. Indexing overview

Indexing maps observed reciprocal-space vectors \(\mathbf{s}_i\) to a lattice such that: \( \mathbf{s}_i \approx h_i\mathbf{a}^* + k_i\mathbf{b}^* + l_i\mathbf{c}^*, \) with integer \((h_i,k_i,l_i)\).

Jungfraujoch supports two complementary indexing strategies:

  1. FFT-based indexing (Rossmann-type): does not require an a priori unit cell; suitable for unknown samples.

  2. Fast-feedback indexing (TORO-like): requires an approximate unit cell; optimized for speed and feedback (§4.3).

Both feed into a common robust refinement/selection stage which maximizes the number of inliers under an indexing tolerance, and which can return more than one lattice per image (multi-lattice indexing; see §5.4).

4.1 Indexed-spot decision (inlier test)

Given a trial lattice with direct basis vectors \(\mathbf{a},\mathbf{b},\mathbf{c}\) (used here as reciprocal-space dot-test vectors), fractional indices are estimated by: \( h_f = \mathbf{s}\cdot\mathbf{a},\quad k_f = \mathbf{s}\cdot\mathbf{b},\quad l_f = \mathbf{s}\cdot\mathbf{c}. \) Let \((h,k,l)=(\mathrm{round}(h_f),\mathrm{round}(k_f),\mathrm{round}(l_f))\) and define the fractional residual: \( \delta^2 = (h_f-h)^2 + (k_f-k)^2 + (l_f-l)^2. \) A spot is indexed if \(\delta^2 < \tau^2\), where \(\tau\) is the configured tolerance.

For indexed spots, the reciprocal lattice point \(\mathbf{p} = h\mathbf{a}^*+k\mathbf{b}^*+l\mathbf{c}^*\) is used to compute \(\Delta_\mathrm{Ewald}(\mathbf{p})\) (stored as a diagnostic and later used in profile-radius estimation).

A frame is taken to be this crystal’s when at least a fraction \(g = 0.20\) of its in-resolution, non-ice spots index. On rotation data that decision is what admits the frame to integration, so its denominator matters: every spot handed to it that is not a reflection of this crystal argues against the frame. Where it cannot do that job — a lattice whose pooled spots fall below \(g\) and which fewer than half the validation frames clear — every frame is integrated instead: the frames that clear \(g\) are then only the upper tail of the same sparse population, not the frames the crystal was in, and admitting them alone dropped most of a small-molecule sweep and its completeness with it.

That test decides a frame. Whether a rotation run has a lattice at all is decided on the spots instead. A frame count comes from serial crystallography, where each image is its own experiment; a rotation sweep is one crystal and one orientation matrix, its frames are not independent of each other, and what such a count mostly measures is how many spots happen to land on a frame — a sweep carrying four spots an image cannot reach a six-spot bar on three frames in four however right the lattice is. The refusal therefore compares the fraction of all spots in the sampled frames that the lattice explains against what the same lattice explains when each frame’s spots are put at another frame’s angle: same lattice, same spots, same detector, same refinement, with only the claim that these spots were seen at these angles removed. That difference is the evidence, and it carries no spots-per-frame number anywhere, so nothing has to be chosen for a crystal that diffracts weakly. Measured over a hundred datasets the permuted level never exceeds 2.6 % and the smallest true margin is seventeen points. --min-indexed-spots (default 6, floor 4 — four is where a lattice stops being fitted by any three spots) still sets the reported indexing rate and the count the first pass ranks candidate lattices by; every rescue and every arbiter still counts frames.

4.2 The spot budget

Only the strongest --max-spots spots of an image are kept (FilterSpotsByCount), and that budget therefore sets the denominator above. Detections are not all reflections — background structure, unlisted ice and detector artefacts are found too — so a budget deeper than an image’s reflections makes the test above a measurement of the background rather than of the crystal, and a larger budget can integrate fewer images.

rugnux measures the budget instead of fixing it. With the sweep’s lattice in hand, the first pass tallies the spots of a sample of frames by their rank in the intensity-ordered list: how many images carried a spot at that rank, and on how many of them it indexed. Weighting each indexed spot by \(1-g\) and each unindexed one by \(-g\) — the same weighting the frame test applies to the list as a whole — the running sum over ranks

\[ E(N) = n_\mathrm{indexed}(N) - g\, n_\mathrm{counted}(N) \]

rises exactly while the spots at that depth lie on the lattice more often than \(g\), and falls after. The budget is \(\arg\max_N E(N)\). Its meaning is “as deep into the list as the image is still showing reflections of this crystal”: deeper spots cannot help the frame test and can only push a frame towards rejection. On crystals whose spot lists are reflections all the way down the maximum is at the end of the list and the budget is unchanged.

The peak has to be one. Under the null — the spots lie on the lattice at the same rate at every depth — \(E\) is a driftless random walk in the counted spots, with per-spot variance \(g(1-g)\), and the maximum of such a walk is positive whatever the data; an \(\arg\max\) taken on its own would shorten every dataset, including one with nothing to shorten. What the budget acts on is the fall from the peak to the end of the list, \(E(N^*) - E(L)\), which is the maximum of the same walk read backwards; by the reflection principle its null law is \(P(\mathrm{fall} > z\sqrt{g(1-g)T}) = 2(1-\Phi(z))\) over \(T\) counted spots in all, so the search over ranks is already accounted for and no further multiple-comparison correction applies. The budget is taken only where the fall clears that bar at \(z = 3.29\), one false shortening in a thousand measurements; otherwise the whole list is kept.

4.3 Fast-feedback indexing (known unit cell)

The fast-feedback indexer (ffbidx, the TORO algorithm of Gasparotto et al. 2024) finds the orientation of a given cell on a single still by brute-force sampling. With the cell vectors \(\mathbf{v}_j\) and the spots \(\mathbf{s}_i\), and the per-spot term \(t(d) = \min(\max(d, 0.001), 0.3) + 0.1\) of the distance \(d\) to the nearest integer, a sample is scored \(\exp_2\!\big(\tfrac{1}{n}\sum_i \log_2 t(d_i)\big) - 0.1 - n_\mathrm{good}\), lower is better: the count of near-integer spots dominates, the mean term breaks ties.

  1. Candidate vectors. For each distinct cell-vector length \(L\), each of 32,768 Fibonacci directions \(\mathbf{u}\) on the half sphere is scored with \(d_i = |L\,\mathbf{u}\cdot\mathbf{s}_i - \mathrm{rint}(\cdot)|\) and \(n_\mathrm{good}\) the spots with \(d_i < 0.2\); the best 32 are kept.

  2. Vector refinement. Each candidate is refined by least squares against the spots within 0.1, 0.05, 0.025 and 0.01 of its integer projections, in four rounds (at least 6 spots each).

  3. Cells. The input cell is mirrored so that one of its vectors lies along a refined candidate (and along its negative), then rotated about it at 1,024 angles; each sample scores the three-index distance \(\sqrt{d_a^2+d_b^2+d_c^2}\) with \(n_\mathrm{good}\) the spots below 0.15. This runs for all three cell vectors, \(3 \times 64 \times 1024\) samples in all, and the best 32 cells go to the common refinement of §5.4.

Centred lattices. The indexer is given the Niggli-reduced primitive cell of the lattice, not the conventional cell of a centred space group (\(A\), \(B\), \(C\), \(I\), \(F\), \(R\)), and every lattice it finds is put back into the given conventional cell by the integer matrix between the two, so everything downstream sees the conventional basis. Given the conventional cell, the scoring above and the indexed-spot count of §5.4 work on the primitive lattice of that cell, 2-4 times denser than the crystal’s, and a wrong orientation that fits only the extra nodes scores as well as the true one: rhombohedral stills in the hexagonal setting came back about half obverse and half reverse, and orientations breaking a \(C\), \(I\) or \(F\) centring were accepted. Every node of the primitive cell is a possible reflection, so no centring condition is needed in the count. The reduction matters as well: the plain primitive cell of an elongated \(C\) cell has an angle outside the window the refinement accepts. A primitive space group, a cell given without a space group and the FFT indexers are unchanged.

The algorithm has two implementations with the same samples, scores and output: the GPU library (CUDA builds, when a GPU is visible) and an in-tree CPU port (FFBIDXIndexerCPU), which is used on machines without a GPU, under --no-gpu, and in builds without CUDA. The CPU port scores a block of samples against one spot at a time so the inner loop runs over samples and vectorises, and in step 3 separates the rotation about the candidate out of the per-spot terms, leaving four multiply-adds per sample and spot. Each frame is indexed on one thread; the frames run in parallel. The two implementations agree to rounding, not to the bit, so two near-equal samples can come out in either order.


5. FFT indexing (unknown unit cell)

FFT indexing follows the classical approach of Steller, Bolotovsky & Rossmann (1997), the one-dimensional form of the Fourier-transform indexing proposed by Bricogne (1986): detect dominant periodicities by projecting reciprocal-space points onto many directions and Fourier transforming the resulting 1D histograms.

5.1 Directional projections and histograms

Choose a set of unit vectors \(\{\mathbf{u}_d\}\) on a half-sphere (a near-uniform distribution generated via a golden-angle construction). For each direction \(d\), form a histogram in the scalar projection: \( t_{id} = \left|\mathbf{u}_d\cdot \mathbf{s}_i\right|. \)

Bin width is chosen approximately as: \( \Delta t \approx \frac{1}{2 L_\mathrm{max}}, \) where \(L_\mathrm{max}\) is the maximum expected real-space unit-cell edge (Å). The histogram extent is tied to the maximum \(q\) used (set by a high-resolution cutoff for indexing).

5.2 FFT peak picking and candidate vectors

For each direction, the FFT magnitude spectrum is computed; peaks correspond to periodicities along \(\mathbf{u}_d\). Each direction yields a candidate real-space length \(L\) chosen not by raw magnitude but by maximum prominence above a running-mean local background (subtracting the broad low-frequency envelope that otherwise dominates on weak or pink-beam frames), subject to \(L\ge L_\mathrm{min}\).

The running-mean background window keeps a constant width and is slid inward at the ends of the spectrum rather than truncated there, so a peak within half a window of either end — which is where the longest cells sit — is judged against as much background as any other. Both window bounds stay monotonically non-decreasing in the bin index, so the GPU kernel’s running sum is still valid.

The longest basis vector the transform can return is fft_max_unit_cell_A, since the histogram is sized from it and its last usable bin is that length; the shortest is fft_min_unit_cell_A (rugnux --fft-min-unit-cell, default 10 Å), below which a candidate is discarded. The defaults are unchanged (500 Å and 10 Å), but the accepted range for the maximum now reaches 1200 Å, and a reference cell given with -C moves both bounds on its own — up to reach a long axis, down to admit a small-molecule cell — since a cell the search cannot represent cannot be found by it. A de-novo rotation run asks the long end a second time as a long-axis hypothesis: the detector separates the rows of an axis of length \(L\) while their spacing near the beam, \(D\lambda/L\), exceeds the measured spot width, so wherever \(D\lambda/(p\,r_{80})\) (\(p\) the pixel size, \(r_{80}\) the pre-scan’s spot width) exceeds the standard bound, a coarse search (3.5 Å histogram) to that length, at most 1200 Å, offers its lattices. Each is re-indexed at full resolution with its cell as the reference, and the one putting the largest share of the pooled validation spots on itself beyond chance replaces the standing lattice where that share is significantly larger (the pooled-spot comparison the first pass uses for every competing lattice) — except an exact superlattice of the standing cell, for which the pooled count is biased and which is left to the supercell probe of the merge. It is asked of every such run, whatever the standing pass indexed: a wrong axis along a fine row still indexes most frames. Its searches are started ahead of the question - the coarse one beside the file centre’s schemes, the re-index of what it offers beside the beam-centre check - and the question then reads their answers from the indexer’s memo: this changes when they run, not what they find.

Candidate vectors are \(\mathbf{v}_d = L_d\,\mathbf{u}_d\).

A collinearity filter removes nearly parallel vectors (e.g. within 5°) and attempts to resolve harmonic ambiguity: shorter “fundamental” vectors may be preferred over longer harmonics if their peak magnitude is sufficiently strong relative to the dominant peak.

Rows shorter than the floor (rotation). The per-direction peak search starts at \(L_\mathrm{min}\), so a lattice row whose repeat is shorter — common in small molecules, absent in proteins — is reported at a multiple of itself past the floor, and a cell built from such rows is an exact integer supercell of the true one. The spots can tell a row from its multiple where the histogram cannot: summed at the row’s own length every spot is in phase whichever of the two it is, but at a whole fraction \(L/k\) of it only the spots of a lattice whose row that fraction is stay in phase. So on a rotation run every shortlisted row reported within \(3L_\mathrm{min}\) is asked, by a direct sum over the accumulated spots, at each \(L/k\) between 3 Å (the minimum cell of DIALS’ fft3d) and the floor, and the shortest fraction that keeps at least half the row’s amplitude replaces it. The cells of these rows are reduced and refined beside the standard ones, not instead of them, and ranked with them (§5.4): where a cell and its supercell index alike, the smaller is kept. Stills keep the standard search.

5.3 Lattice reduction and cell candidates

Triples of candidate vectors are combined to form candidate bases \((\mathbf{A},\mathbf{B},\mathbf{C})\), each reduced to its Niggli-reduced cell (Gruber-vector reduction) before comparison, and filtered by allowed length and angle ranges. Two passes are run: a standard pass forms shortest-vector triples from the ~30 strongest filtered directions; if the best cell then indexes fewer than half the spots, a widened fallback anchors the two shortest axes and lets the third range over up to ~60 candidate vectors (deduplicated by Niggli cell), catching large, elongated or superstructure cells the first pass misses.

A triple whose three vectors are coplanar is rejected before refinement. The length and angle filters cannot see it — any flat combination satisfies them — and a cell that flat has a metric determinant small enough for float to get its sign wrong, after which the guard against a negative argument to the square root places \(\mathbf{c}\) in the \(\mathbf{a}\)-\(\mathbf{b}\) plane, the reciprocal volume diverges and the solver reports a not-a-number Jacobian. The test is the volume fraction \(|V|/(|\mathbf{a}||\mathbf{b}||\mathbf{c}|)\), which must reach 0.02 — about 1.1° off flat, well below the flattest genuine candidate observed and far above where float loses the sign — and it is applied both where triples are produced and at the optimizer’s entry points.

A shortlist confined to one plane cannot close a cell at all, and the row it is missing is the plane normal. That is detected from the eigenvalue ratio of the shortlisted directions’ scatter matrix, and one further transform is then spent with the same direction count inside a narrow cap about the normal. More directions do not substitute for it: at the exact true direction a very long axis can still rank far below the shortlist cut, so for this rescue the obstacle is the ranking rather than the sampling, and a denser grid costs several times the device memory for the same answer.

Sampling has a limit of its own, and it binds well before the 1200 Å the accepted range for fft_max_unit_cell_A admits (§5.2). A direction off a real-space axis of length \(a\) by an angle \(\theta\) smears each projected lattice plane by about \(\theta/d_\mathrm{min}\) in the projection, so the planes (spacing \(1/a\)) stay resolved only while \(\theta \lesssim d_\mathrm{min}/(2a)\). The shipped grid of 16384 directions puts the nearest one within about 0.6° of any axis, which satisfies that bound only up to roughly 120–150 Å at typical indexing resolutions; a longer axis is not refused but returned as a plausible sub-cell or harmonic. Raising the maximum cell alone therefore does not extend the reach — the direction grid has to resolve the axis before the histogram can represent it.

5.4 Robust refinement and best-cell selection

Candidate bases are refined against observed spots using an iterative inlier‑focused least‑squares procedure (trimmed/contracting threshold). Candidates are then ranked:

  1. more indexed spots wins — unless two candidates index within ~10 % of each other, in which case

  2. the smaller-volume cell is preferred (when the volumes differ by more than ~5 %), avoiding a doubled supercell, then

  3. the smaller refinement score, then the spot count again.

Selection is not limited to a single lattice: after the best cell is accepted, further lattices are added as separate crystals provided fewer than ~40 % of their indexed spots overlap an already-accepted lattice (up to two extra by default), so split or multi-lattice crystals are indexed rather than discarded.

A candidate dropped only for its overlap with a lattice that contains it or is contained by it — an integer supercell or sub-cell, the rows of the larger cell integer combinations of the smaller’s — is kept nonetheless, after every cell the test accepts: that overlap is total by construction and says nothing about which of the two is the crystal’s. The rotation indexer refines these too and may choose one (a sub-cell that indexes as well, §5.2); the integer supercells of the cell it chooses are carried with it, so that the twin-composite test of the first pass, which asks whether a cell is the coincidence lattice of two twin domains, can also be asked of them when the search has offered a domain’s own cell. Kept cells are never taken as extra crystals: those must share the first lattice’s metric.

An optional reference unit cell (if supplied) restricts acceptance to cells within a relative distance tolerance in edge lengths (permutation-invariant).

5.5 Spindle alignment: the part of the blind cone symmetry cannot repair

A sweep about the spindle \(\hat{\mathbf{e}}\) never brings a reciprocal point closer than \(\theta_\mathrm{max}=\arcsin(\lambda/2d)\) to the axis onto the Ewald sphere, so a double cone of half-angle \(\theta_\mathrm{max}\) is missing from every resolution shell — each shell losing its own \(1-\cos\theta(d)\) — however long the sweep runs. Crystal symmetry normally repairs that loss by mapping the cone onto measured territory. It fails to when a symmetry axis lies inside the cone (the cone maps onto itself) — and, for a 2-fold, equally when the axis is perpendicular to the spindle, because the diad carries the cone onto its opposite lobe, which the sweep leaves just as unmeasured. Friedel never helps: the cone is double-sided. The loss is a coherent cap rather than a scatter of absences, so it costs a map more than the same percentage lost at random.

The per-image score asks how much of that cone the frame’s own orientation makes unrecoverable. The crystal’s short lattice rows are read off the FFT row shortlist of §5.2 (a symmetry axis is always a lattice row, and usually among the short ones), and each plausible direction is scored as if it carried a lone 2-fold:

\[ \text{spindle blind fraction} = \frac{2}{\pi}\left(\arccos x - x\sqrt{1-x^{2}}\right), \qquad x = \min(\beta,\,90^\circ-\beta)\,/\,\theta_\mathrm{max}, \]

where \(\beta\) is the direction’s miss-angle from the spindle. The fold of \(\beta\) about \(45^\circ\) is the diad geometry above: both ends of the range are the bad case, and the closed form reproduces a Monte Carlo of the true double-cone self-overlap to 0.004 at \(\theta_\mathrm{max}=15^\circ\) and 0.008 at \(25^\circ\) (past \(45^\circ\) it under-reports, by 0.05 at \(50^\circ\)). \(\theta_\mathrm{max}\) is taken from the geometric resolution of the setup — the detector corner at the recorded distance and wavelength — an upper bound on any sweep collected without moving the detector; the still’s own spot resolution would understate the cone on exactly the weak frames that mislead. The worst direction wins, and the directions scored are the strong in-window rows and the normals of their pairs — the normal to two lattice rows is itself a reciprocal-lattice row and a symmetry axis is parallel in both bases, so a lone 2-fold on an axis far beyond the length window (a long monoclinic unique axis) is still seen by direction. Nothing about the goniometer enters: the number describes the problem and leaves the remedy — a second sweep, a reorientation — to the beamline.

This is a worst-case bound under an assumption of no symmetry, not an estimate. A still cannot know the point group, so the nearest plausible row is scored as a lone 2-fold. An axis of order \(\geq 3\) perpendicular to the spindle in fact fully repairs the cone (measured unrepaired fraction 0.000 for orders 3, 4 and 6, against 1.000 for a diad), which a still cannot see, so the bound is deliberately pessimistic on higher-symmetry crystals — that is the intended trade, because the number exists as a trigger for beamline automation, not as a physical quantity a user interprets.

Trigger states. The stored quantity is the continuous score; automation reads it through three fixed states with nothing to tune (SpindleTrigger in SpindleBlindFraction.h): engage at score ≥ 0.5, don’t engage below, and cannot say when there is no value at all — too few spots, no shortlist, the consistency guard refused, the path never computed one. Automation must treat CANNOT SAY as ENGAGE: the error costs are asymmetric — a false negative is unrecoverable (one sweep is collected and the data stay short forever) while a false positive costs minutes of beamtime. Every transport keeps absence distinguishable from a measured zero (an absent CBOR key, a NaN in the HDF5 arrays, an absent optional after read-back). The 0.5 threshold is geometry, not tuning: the score is monotone in the folded miss-angle, so a threshold is a fold-angle gate, and 0.5 gates at \(\min(\beta,90^\circ-\beta) \le 0.404\,\theta_\mathrm{max}\); engaging on any overlap at all would gate at the cone edge, whose perpendicular band alone spans \(\sin\theta_\mathrm{max}\) of orientation space per row (26 % at \(15^\circ\)) and unions over a frame’s rows to well over half of all mountings — a trigger that always fires decides nothing.

Reach and honest rates. The score needs 60 spots (calibrated per crystal — 22 independent mounts — misses triple below it); below that, a frame that still indexed answers from the winning lattice’s shortest rows, and otherwise the state is cannot say. Because the bound is pessimistic by design, it engages on a substantial share of harmless mountings: a single strong row’s perpendicular band alone covers ~11 % of orientation space at the severe level (\(\theta_\mathrm{max}=15^\circ\)), and the union over a frame’s rows and pair normals reaches roughly a quarter to three quarters of random mountings depending on cone width and row count (measured 0.74 on a generic triclinic cell at \(15^\circ\) via the lattice path). That is accepted: the cheap error is the extra wedge. An earlier figure of ~1 % false alarms (AUC 0.948) came from a null of five decoy directions per frame — it shows the estimator does not hallucinate rows near arbitrary directions, which is worth knowing, but it is not a false-alarm rate over harmless mountings, which geometry forbids to be that low.

Offline, the guessing stops. Once rugnux has merged a rotation run it holds the measured point group and the exact indexed orientation, and the run-level number is computed exactly instead: the group’s proper rotations are applied to the blind double cone in the crystal’s actual orientation, and the fraction of unique reflections no operator can recover is reported as SPINDLE_LOST_UNIQUE_FRACTION in the processing report and /entry/MX/spindleLostUniqueFraction in the master file (the results report). That number clears or convicts a mounting the per-image bound can only be pessimistic about: a dihedral crystal with an in-plane diad on the spindle, or any cubic crystal in any orientation, loses nothing at all.



7. Geometry and lattice refinement

Refinement adjusts experimental geometry and crystal parameters to minimize discrepancies between observed spot reciprocal vectors and those predicted by a lattice model with integer indices.

7.1 Parameterization

The refinement jointly optimizes, depending on mode and constraints:

  • beam center \((x_\mathrm{beam}, y_\mathrm{beam})\),

  • detector distance \(D\),

  • detector tilt angles (two-angle model; third rotation often held at 0),

  • rotation axis direction (for rotation datasets),

  • crystal orientation (a global rotation),

  • unit-cell parameters, with constraints determined by inferred crystal system.

The detector distance is not refined against one crystal’s spots at all: the positional residual leaves it degenerate with the cell scale, so it is fitted elsewhere - by the rotation post-refinement, which frees it alongside the whole crystal and adds the distance-independent rocking-angle residual that breaks the degeneracy, and by the stills --refine-geometry bundle. Per image, the beam centre and the crystal orientation are refined, and the unit cell as well for stills. The first-pass rotation indexing refines the detector tilt and the rotation-axis direction too, against the spots accumulated across the sweep; everywhere else both are held fixed, because on a single crystal a tilt is absorbed almost exactly by the crystal orientation. A lighter orientation-only mode refines just the crystal orientation, for stills whose geometry is already trusted. It carries a weak small-rotation prior penalising the whole angle-axis vector (all three components, at a low weight); what it is there for is the poorly-determined out-of-plane component, which is the one the data barely constrain.

For higher symmetries, constraints are enforced, e.g.

  • cubic: \(a=b=c,\ \alpha=\beta=\gamma=90^\circ\),

  • tetragonal: \(a=b\),

  • hexagonal: \(a=b,\ \gamma=120^\circ\),

  • monoclinic (unique axis \(b\)): \(\alpha=\gamma=90^\circ\), \(\beta\) refined.

7.2 Residuals and objective

For each indexed spot assigned integer \((h,k,l)\), compute:

  • observed reciprocal vector \(\mathbf{s}_\mathrm{obs}\) from its detector position and current geometry,

  • predicted reciprocal vector \(\mathbf{s}_\mathrm{pred}(h,k,l;\ \text{lattice params})\).

Residual is: \( \mathbf{r} = \mathbf{s}_\mathrm{obs} - \mathbf{s}_\mathrm{pred}. \)

A non-linear least squares solver minimizes \(\sum \|\mathbf{r}\|^2\) over all selected inlier spots.

7.3 Rotation datasets: bringing observations to a common reference frame

For oscillation/rotation data, each image corresponds to a rotation angle \(\phi\) about an axis \(\mathbf{m}_2\). Observed reciprocal vectors are rotated “back to start” so that all images are refined in a single reference crystal frame: \( \mathbf{s}_\mathrm{obs,ref} = R(\phi)\,\mathbf{s}_\mathrm{obs}, \) where \(R(\phi)\) is the rotation by \(+\phi\) about the goniometer axis as stored in the file. The sign is a convention and it is load-bearing: rotating the observations forward by \(+\phi\) means the crystal itself turns by \(-\phi\) about that stored axis, i.e. \(R(\phi)\) is the inverse of the crystal’s own rotation from the reference orientation to frame \(\phi\). The same convention is why the unmerged-MTZ batch headers and the XDS geometry echo carry the axis negated relative to the input file (Rugnux ▸ the unmerged export) — a reimplementation that takes \(R(\phi)\) as the crystal rotation must use \(R(-\phi)\) here instead. The angle \(\phi\) is taken at the centre of each frame’s oscillation (the frame angle plus half the oscillation width).

7.4 Multi-stage tightening of inlier tolerance

Refinement is performed in stages with decreasing acceptance tolerance for including reflections (three stages, indexing tolerance \(0.3\to0.2\to0.1\)), which stabilizes convergence when starting from imperfect indexing and approximate geometry.

The loose first stage necessarily admits some spots that are not reflections of this lattice — the fraction of randomly placed spots inside a fractional-Miller tolerance \(t\) is \(\tfrac{4}{3}\pi t^3\), i.e. 11 % at \(t=0.3\) — and an unweighted fit lets them pull the orientation. Each residual is therefore weighted by how strong its spot is for its resolution: the frame’s spots are cut into equal-count resolution shells and each intensity is divided by its shell median, mapped to \(w^2=r/(1+r)\). The shell normalisation is what makes this safe — genuine high-resolution spots are legitimately weaker and carry the cell and distance information, so an un-normalised intensity weight would suppress exactly the spots the fit needs. The weight is a property of the spot and never of the current residual, so it does not depend on how far the geometry is from convergence.

A rotation frame’s refinement is restrained toward the sweep. A frame is integrated on the orientation and beam centre refined against its own spots, starting from the sweep’s geometry. Where the crystal really moves the refined orientation follows it, and integrating on it is what keeps such a sweep together. Where a frame has few or poorly placed spots the same fit can instead jump on its own, by up to a few degrees, which drops strong reflections out of prediction on the frame they peak on. So after the geometry pre-pass, which refines its frames freely, each integrated frame is fitted twice: freely, for the scale \(\sigma^2\) of its own weighted misses, and then from the sweep again with a Gaussian prior on how far it moves, minimising \(\sum_i w_i^2\|\mathbf{r}_i\|^2/\sigma^2 + \sum_k \theta_k^2/\tau_k^2\) over the orientation and beam-centre shifts \(\theta_k\) (the orientation’s as the three components of the rotation from the sweep’s orientation, so that its width means the same in every direction however the crystal sits in the laboratory). Both fits of such a frame are made with the spindle given, as over a sweep, so the beam centre’s component along the spindle - which on a single frame nearly trades against the orientation - carries the same weak restraint toward the start that it carries in the sweep refinement. The widths \(\tau\) - one for the orientation, one for the beam centre - are measured once per run on the pre-pass frames, as the root mean square of the seven-frame running median of the free shifts of the frames whose fit succeeded (a frame too sparse to fit keeps the sweep’s geometry, which is not a measurement of how far it moves) (the track’s smooth part, which a jump on one frame does not reach). The prior is centred on the sweep’s orientation in the metric the fit holds the cell to - the frame’s free-fit lattice turned to sit closest to the sweep’s - and the shifts are measured as rotations from it, so that a sweep lattice with a metric of its own (a free cell a few tenths of a degree off the symmetric one the fit holds) does not count its strain as a shift; and the orientation width is never narrower than the angle by which that best held orientation still misses the sweep lattice’s vectors, since that much each frame must be free to turn to fit its own part of the sweep. There is no gate: the data of each frame decide how far it moves, a frame with many well placed spots following a moving crystal and a sparse one staying near the sweep. Each frame is still refined on its own spots, independently of the others. The frames the first pass scores candidate lattices on and the pre-pass keep the free refinement of a single frame, without the spindle form as well as without the prior, so the lattice, the geometry the run refines and every decision the pre-pass takes do not depend on either, and stills are not affected.

The rotation chain commits its best round, not the round it stops on. After the winning candidate is selected, the refinement is run again — solve, re-accumulate the reciprocal-space cloud under the refined geometry, solve again — up to twenty times, and the loop stops on a test of the detector-tilt step. The chain is a trajectory and its last point is not always its best one: every solve ends by fitting only the spots inside its tightest gate, so a cell with a direction the data barely constrain (which is what a free cell whose metric is near a Bravais class has) can slide along it, pulling a core of spots tighter while the periphery falls out of the fit altogether. Measured on such a chain, the spots inside the tight gate rise over seventeen rounds while the spots inside the widest gate peak at round three and fall away — and round three is the round that merges at ISa 11.0 against 6.3 and \(R_\mathrm{meas}\) 0.148 against 0.213. Nothing the run consulted could see it: indexed fraction, validation frames, validation spots and the tight-gate count all prefer the overfitted end.

So every round is scored on the widest gate — the population the first pass selects on and the last pass does not fit, which makes it the one a converged solve is not optimising — and the best-scoring round is committed. Two conditions keep that from acting on noise. The score is a count of spots, so a lead of fewer than \(\sqrt{\text{count}}\) of them leaves the last round standing. And the round taken has to be the less distorted lattice as well as the better-fitting one: the lattice search (§6) is re-asked every round to measure how far the cell sits from the ideal metric of the class it matches (imposing that class is measured fatal — the snap puts almost everything outside the refinement’s own gate), and an earlier round is taken only when it matched the same class and sits closer to it. Same class is a precondition and not a precaution: the deviation is a fraction of whichever class’s tolerance admitted it, so two classes’ deviations are not the same quantity, and a round that matched no class reports zero, which means “nothing was asserted” rather than “undistorted”. A chain that has settled scores its rounds within a spot or two of each other and a symmetry-constrained solve holds its distortion at zero throughout, so the rule fires on neither: measured over 914 chains, an earlier round scores higher on 44 % of them and the committed round changes on 1 dataset in 54.

A tilt no mounting can have has to prove itself. The detector tilt is refined freely because on a sweep whose spots reach far enough in \(2\theta\) it is a measurement, and restraining it costs those crystals resolution and ISa. What makes it a measurement is the keystone — a tilted plane puts one side of the detector nearer and the other further, so the spots move by an amount that grows with their distance from the beam — and a first pass made of spots reaching a few degrees of \(2\theta\) sees a keystone of a pixel or two at most. To such a fit a tilt is a whole-pattern shift the beam centre imitates exactly, its size is whatever the centroids’ own systematics happen to prefer, and the value it commits then mispredicts the far corner of the detector by tens of pixels against an integration disc of a few, and the run can lose most of its resolution to it. For a tilt of a few tenths of a degree nothing in the spots says whether it is real — the held-out positional residual, the rocking angles and a re-fit at the header tilt are all equally insignificant on a crystal whose tilt is real and on one whose tilt is the artefact — so below what a mounting can be off square by the fit is trusted as before: a detector is mounted square to the beam to a fraction of a degree. A chain that has walked more than 1° from the tilt it started at has either measured nothing or found a detector the file misdescribes (a \(2\theta\) arm swung out that the file records as square), and at that size the spots do tell the two apart, because a real tilt of degrees has a keystone of tens of pixels over the spots the fit is made of and an artefact has none. So the candidate is refined again from where it started with the tilt held there — the beam centre takes the shift the tilt is equivalent to — and the two are judged as the rounds of one chain are, on the spots each indexes inside the wide gate: the walked tilt stands only when it leads by more than the count’s own noise. Held, not bounded — a box the fit lands on is the same wrong answer at a smaller size. The log says what the walked tilt would have moved the far corner by and how the two counts came out; where it was refused, the report’s REFINED_DETECTOR_TILT is the tilt the pass started at and REFUSED_DETECTOR_TILT the tilt the fit had walked to.

7.5 Rotation geometry post-refinement (two-pass)

The refinement above (§7.2) runs per image against that image’s spots. For rotation data an additional post-refinement (on by default; --rotation-no-postrefine disables it) improves the detector distance, beam centre and crystal cell/axis using all frames at once, then re-integrates:

  1. Pass 1 integrates, scales and merges at the header geometry — the first half of the sweep by default, but at least 120° of it, so a sweep up to 120° is pre-passed whole (--prepass-fraction, 1 for all of it). The first-pass indexing and the pre-scan have sampled the same part of the sweep, so nothing before pass 2 reads the rest of it - which is what lets a run that follows a collection still being written do all of this while the rest is collected; what pass 1 adds is integrated reflections for the post-refinement below, and half a sweep holds plenty of them while costing half the time. Its merge, post-refinement and smoothed mosaicity describe a sweep of those frames alone.

  2. From pass-1’s integrated reflections, the crystal and the detector are refined together over all its frames (Ceres, robust loss) in one joint fit, against both residuals at once:

    • the positional detector↔reciprocal residual at each partial’s observed spot, and

    • a distance-independent Ewald excitation residual at each reflection’s observed rocking centroid \(\phi_\mathrm{obs}\).

    Free: the crystal orientation, the unit cell (every parameter the crystal system leaves free, not one overall scale), the goniometer-axis direction, the detector distance and the beam centre. The positional residual on its own is degenerate with the cell scale — that is why this used to be split into a cell-scale step and a distance step — but the excitation residual does not involve the detector at all, so it fixes the absolute size of the reciprocal lattice and breaks the degeneracy inside the same problem. Splitting it instead cost accuracy twice over: pass 1 frees the whole lattice against a frozen distance, so the distortion it absorbs is anisotropic and no single scale can undo it; and whatever bias is left in that scale goes straight into the distance, which is only ever determined relative to the cell.

    The fit is cross-validated on a deterministic split of the reflections (an avalanche-mixed \(hkl\) hash, not a frame split and not an \(h+k+l\) parity, which would collide with a centering condition and leave the held-out half empty): fitted on one half, committed only if it lowers the held-out residual by more than that residual’s own noise (the standard errors of the two held-out means combined, the bar a round of the geometry walk has to clear) and its two families agree: the positional residual has to fall by more than its own noise, because the positions are the only evidence of the detector geometry a commit hands the next pass, and the excitation residual must not rise by more than its own noise, because it is the only evidence of the cell scale and the positional values outnumber it about three to one. That noise is the paired standard error — both geometries are read on the same held-out reflections, so what a change has to beat is the scatter of the change each reflection sees; bare signs stood here, and were a coin toss wherever a family did not move — and the move stays inside its bounds: every free cell angle within 1° and the beam centre within 15 px of the nearest centre anything already believes.

    The distance and the cell lengths are bounded one step at a time, not as a whole. One per cent was once a cap on the entire move, and as a cap it was the opposite of its job — a header is most worth correcting when it is most wrong, and a geometry genuinely several per cent out could never be reached (measured: a refused fit of 310.000 → 305.692 mm whose cell landed within 0.06 % of the deposited one). It is a trust region instead. The first solve is asked in the wide box around nominal exactly as before, so a fit that settles within one step commits unchanged; a fit that wants more is re-fitted as a walk of one-per-cent steps, each seeded where the last arrived and each required to lower the held-out residual, stopping where a step stops paying. A walk that uses every step it is allowed has not settled — it stopped because it ran out of steps, not because it arrived — and is refused, which is the runaway the cap stood in for, tested where it can be seen. A move of more than one step is additionally ratified by re-indexing at where it arrived: that is what separates the failure the cap was really aimed at (a second lattice, whose spots bias every cross-validation fold identically) from a wrong header, since a second lattice does not index better at the new geometry and a real distance error does.

    The geometry the run commits is re-fitted on all the reflections once the held-out half has approved it — a walk from where it arrived, one step wide; everything else from nominal in the wide box — and the bounds are asked again of that fit rather than only of the half that earned it. A move outside them leaves the geometry at nominal, as every other refusal does, and the refusal says so in the report (POSTREFINE_REFUSED, with what the fit wanted) rather than passing silently. Detector tilt is held fixed, being gauge-coupled to the crystal orientation on a single crystal.

    Whether the data determine the distance at all is asked, not assumed. At a detector far enough away that no reflection reaches more than a few degrees of \(2\theta\), a longer distance and a larger cell move every spot the same way to first order — the difference is of order \(\sin^2\theta\) of the spot’s own position, about 0.4 px rms per per cent of distance over a 2M detector at 820 mm against 2–3 px at the distances a crystal is usually collected at. The joint fit then finds a distance/cell pair that fits its own spot positions a little better than the header, commits it, and the pass re-integrated there finds the next pair: a walk along the degenerate direction that the realised residual never ratifies (measured on such a sweep: a header at 820 mm walked to 846 mm with the cell 3.3 % too large, the realised held-out residual flat at every round). So the same fit is asked once more with the distance held at the header, every other block as free as before — the nested hypothesis “the header distance is right” — and the two are compared on the one residual family that can tell them apart: the excitation residual. It never involves the detector, so it is blind to the distance itself; what it sees is the cell scale, and a held fit at a wrong header distance is forced into a wrong cell scale by the spot positions, which the rocking angles then refuse (measured: a header 1.4 % long leaves the held fit’s excitation residual seventeen times the free fit’s). Where freeing the distance lowers the held-out excitation residual below the held fit’s by more than that residual’s own standard error, the free fit is committed exactly as before; where it does not, the held fit is — header distance, refined beam, cell, orientation and axis — and the report says so (POSTREFINE_DISTANCE_HELD). The positional residual is deliberately not consulted for this: it is the family whose in-fit gain along the degenerate direction re-integration erases, and pooled with the excitation family it either drowns a decisive excitation gain in its own noise (a 54 % excitation gain read as 9 % pooled against a 9 % noise) or lends the degenerate direction a gain that is not there. Nothing is tuned here: the only input is the standard error of the residual itself, the same noise the geometry walk’s rounds have to beat. The wavelength is never refined on a single crystal for the same reason in its exact form: it scales the spot positions and the rocking angles identically to the cell, so no sweep can tell the two apart at any \(2\theta\).

  3. Pass 2 re-indexes de novo and re-integrates at the committed geometry. Only the detector distance and beam centre carry over: the refined cell, orientation and axis are what make the distance identifiable, but pass 2 re-indexes from scratch, so they are not propagated. Where the re-index finds a different lattice — the two compared on their Niggli-reduced primitive edges, within 2 %, so a symmetric setting is never told apart from its own primitive cell — pass 1’s lattice is scored at the refined geometry as a hypothesis of its own, and integrated when it indexes more validation frames; the same lattice found again is kept as the re-index refined it. The run likewise falls back to pass 1’s lattice where the re-index indexes too few frames, and integrates it at the refined geometry — and the cell is then scaled to the distance it will be used at, since a real-space cell is measured against the distance its spots were seen at, and carrying it across a distance change otherwise scales the whole cell by the ratio of the two. The orientation is untouched.

    Pass 2 measures the post-refinement again, and where it still moves the geometry the run walks: it re-indexes and re-integrates at what the fit asks for, and repeats. A round is kept only for what it realises, not for what the fit predicts, and it can realise a gain in two ways, either of which has to beat its own noise: a lower held-out residual (the standard errors of the two means combined), or a larger share of the validation spots on the lattice beyond chance (the binomial noise of the two shares, z = 3.29). The residual alone misses exactly the errors that cost resolution: it is dominated by the low-resolution reflections, where a distance and the cell scale that compensates it move every spot alike, and its centroids are taken inside a disc centred on the prediction, so they follow the prediction part of the way; the high-resolution validation spots are the first to leave the lattice (measured: 0.6 % of distance read 0.74 of the residual’s noise and 70.4 % against 58.1 % of the validation spots, and cost 0.07 Å of resolution). A move of a trust-region step or more starts the walk outright. A smaller one is first tried as two indexing probes on the validation frames — at the fit’s geometry and at the one in hand, each stopping once the lattice is scored — and pays for a re-integrated round only where the fit’s geometry scores higher. The run keeps the best round it reached.

The space group is determined after pass 2, on the geometry the run refined, and pass 1 does not search at all: a decision taken on the worse of the two passes and then carried forward is a constraint on the better one, and would have to be reconciled with what pass 2 later found. The guard that chooses which pass is written compares each pass’s first merge — \(P1\) on both sides, full resolution range, before the correction surfaces — which both passes produce anyway, so it never compares statistics computed in two different space groups. Where pass 1 integrated only part of the sweep, pass 2 is judged on a merge of its own integration of the same frames, made the same way, since a merge of more frames holds more reflections and more signal whatever the geometry. What it compares there is the signal each pass measured: the count of unique reflections merged at \(I/\sigma \ge 2\), less the count at \(I/\sigma \le -2\). An empty reflection is as likely to land in either tail, so the second count is the merge’s own measure of how much of the first is noise — which is what makes two passes on different lattices comparable: a pass on an \(n\)-fold supercell merges \(n\) times the reflections, most of them empty, and their noise alone once out-counted the crystal’s own lattice. Self-consistency cannot do this job — against an external arbiter the signal count named the more accurate geometry on 23 of 27 arm-dataset pairs where \(R_\mathrm{meas}\), \(CC_{1/2}\) and ISa managed 13, a coin flip — and that merge’s own \(CC_{1/2}\) least of all, being pooled over the whole range, uncut and uncorrected, so the shells with no signal in them dominate it and they are exactly the shells a geometry move disturbs (it reads 0.13 on a crystal whose data merge at 0.995). The refined pass is sent back only where it merges more unique reflections than its cell can hold, where it measured decisively less signal (10 %, and only where it covers no more of reciprocal space either — a wider integration disk pulls weak reflections in and dilutes the strong fraction without measuring less; between two lattices the reflection count of the smaller is scaled by the integer index of one in the other), or where it lost the axial rows the systematic absences are read off. One index-time veto remains and is keyed to pass 1’s lattice rather than its group: a centred pass-1 lattice against a primitive pass-2 one. A pass sent back is pass 1 as it was judged — its whole indexing result is reused, not indexed again de novo at the header geometry, which is a hypothesis nobody had judged.

Only pass 2 is written, as the canonical <prefix>_* output. Pass 1’s merge exists to give the guard something to judge pass 2 against, so it stops short of the parts of the merge that only fill in a file — the correction surfaces, the twinning and radiation-damage analyses, the R-free flags and the amplitudes — and writes no merged files of its own.

Goniometer rotation scale. A stage that turns further than it was commanded to leaves no trace in the file, because the stored \(\omega\) values are the commanded ones; the excess then presents as the crystal drifting, in this program and in others. The excitation residual already measures it without a new degree of freedom: it rotates by \(-\phi\,\mathbf{u}\) with \(\mathbf{u}\) an unnormalised 3-vector, so \(|\mathbf{u}|\) is the factor \(k\) by which the stage actually turned, and normalising the axis throws it away. Pass 1 fits \(k\) as a single parameter on its rocking events, with the crystal and the axis direction held at their committed values and the angle measured from the centre of the sweep. That fit under-reads a real error: it only sees the frames the stored angles still track, and a rate error is exactly what stops them tracking the rest. So it is not acted on directly. Between the passes, at the detector geometry pass 2 runs at, the lattice is indexed under the stored angles and under the fitted \(k\), and each is scored on the validation frames spread over the whole sweep, as the share of their spots it puts on the lattice beyond what it puts there at a wrong spindle angle. The fitted \(k\) is adopted only where it scores higher by more than the binomial noise of the two scores (z = 3.29); the run then integrates and post-refines at it, fits \(k\) again on top of it, and walks to the fixed point of the fit: once off the stored angles, a further step is refused only where the validation frames score it significantly worse, since a first pass indexes through a degree of drift late in the sweep and the frames can score two rates alike while integration at one of them loses half the signal. Where the run integrates pass 1’s own lattice at the adopted \(k\), that lattice (cell and orientation, the detector and axis held) is first refit at the angles the pass runs at, on the validation frames of the whole sweep, and kept where it indexes no fewer of them - a cell fitted at the stored angles has absorbed part of the rate error and would undo it. Otherwise the stored angles stand. The adopted \(k\) drives every later pass (prediction, integration, scaling and the reported oscillation) and is reported as GONIOMETER_ROTATION_SCALE, with GONIOMETER_ROTATION_SCALE_SUSPECT= TRUE. --rotation-scale <k> asserts a calibration and skips all of this.

7.6 Detector geometry from powder rings

Everything above fits the geometry to Bragg data, where the beam centre is the weakest parameter: it is gauge-coupled to the crystal orientation, which is why §7.5 bounds it to within 15 px of a centre something already believes rather than letting the spots place it freely. A powder ring has no orientation to be coupled to. Where it falls on the detector depends on the geometry and on nothing else, which makes a calibrant — LaB₆, silver behenate, CeO₂, silicon — or even ice an independent constraint on exactly the quantity Bragg data cannot pin.

The ring positions are matched to the observed rings and the geometry is refined (Ceres, five parameters: beam centre, distance, and the two detector tilts) so that the \(|s|\) predicted at each observed ring point matches the ring it belongs to. The two tilts can be held fixed (rugnux --no-refine-tilt, the viewer’s Refine detector tilt tick box), leaving a three-parameter fit: a tilt a downstream program cannot express is better left out of the fit than refined and then dropped, since the centre and the distance of a tilted fit have already absorbed it.

Calibrants. LaB₆, silver behenate, CeO₂ and silicon are held as unit cells and their rings enumerated from them. Ice is held as the hexagonal-ice ring positions of §3.3 instead — measured to 1.522 Å, calculated below it — because hexagonal ice is \(P6_3/mmc\) with oxygen on \(4f\) and enumerating \(hkl\) from its cell would emit rings the oxygen sublattice extinguishes. A calibrant is therefore a list of ring \(q\) values throughout, not a cell.

What a ring can and cannot determine. A ring is a conic centred on the beam, so a wrong centre makes its apparent radius oscillate once per turn, \(r(\phi)=R+\delta_x\cos\phi+\delta_y\sin\phi\), with the same amplitude on every ring. A detector tilt \(\beta\) produces a \(\cos\phi\) term too — not the \(\cos2\phi\) one might expect — but one that grows as the ring’s radius squared, \(r(\phi)=R+(R^2/F)(\beta_x\cos\phi+\beta_y\sin\phi)\); the true \(\cos2\phi\) term is \(O(R^3\beta^2/F^2)\), hundredths of a pixel. The two are therefore separated by how the amplitude scales with radius, which needs at least two rings — on a single ring they are exactly degenerate. None of this uses the calibrant’s \(d\)-spacings, so the centre is determined without assuming anything about the standard.

The distance is different: it follows from \(r=F\tan2\theta\) with \(\sin\theta=\lambda/2d\), so a fractional error in the lattice constant passes straight into it, and the \(\lambda\)–\(F\) pair is separated only by the curvature of \(\tan(2\arcsin(\lambda/2d))\) across the rings — \(\partial\ln r/\partial\ln F=1\) at every ring against \(\partial\ln r/\partial\ln\lambda=4\tan\theta/\sin4\theta\), which runs from about 1.05 at low angle to 1.43 at high. That lever collapses as the detector moves back and the rings crowd into small \(2\theta\), so distance is a short-distance measurement and the wavelength is better calibrated by other means.

Reading the rings. The ring points come from one of two measurements, both accumulated over every processed image rather than one. The default reads the azimuthally-binned profile (§2) summed over the run: for each ring and each azimuthal sector, the radial peak is fitted against a locally interpolated background and the measured \((q,\phi)\) mapped back through the current geometry to the pixel it came from. The alternative pools the spot lists, which samples each arc wherever the spot finder’s threshold happens to bite. The accumulated profile is the same size however many images went into it; the pooled spot list is capped, each image contributing an equal share.

A plain radial profile — one azimuthal sector — has averaged the ring over every direction and carries no centre at all, so the profile route requires at least four sectors and uses 32 by default. Sixteen to thirty-two are enough; beyond that the limit is the ring’s own texture, not counting statistics.

The extraction window around a ring is capped at half the gap to its neighbour, because the background under a peak is taken from the ends of that window: hexagonal ice has a triplet of rings (1.947, 1.916 and 1.882 Å) whose neighbours sit only 0.05–0.06 Å⁻¹ apart in \(q = 2\pi/d\), which a fixed window merges into a single peak. Where only one ring is in reach the two tilts are held at their input values rather than fitted, since on a single ring they are degenerate with the centre (above) and the fit would otherwise trade the centre away for them.

7.7 Stills: a given cell and the detector modules

A given cell is a prior. On stills a cell and a distance are degenerate near the beam - a spot’s radius fixes only their ratio - and are told apart only by the curvature of \(r=D\tan2\theta\) against \(\sin\theta\) at high angle. The stills geometry refinement therefore refines the beam centre, the distance and the cell together over the strong frames: the cell lengths and the angles its crystal system leaves free (the monoclinic \(\beta\), all three triclinic angles), each held to the given cell by a Gaussian prior of 1 % on a length and 1° on an angle, weighed against the spots’ scatter of about a pixel. On a bundle of strong frames the spots outweigh the prior wherever they determine the cell, so it decides only what they leave open. Holding the angles instead puts a wrong angle into the lengths and the distance: a monoclinic cell given with \(\beta\) 4° off was taken up as a cell and a distance both 4 % long. The log states how far the refined cell is from the one it started from (scale, each length, each angle) and how far the distance moved. A distance given with --detector-distance is held, and the cell alone takes up its error. Frames are matched to the given cell in any setting of the same lattice, and are described on its axes.

With -C the run always uses the cell given; the frames’ own evidence is reported, never acted on. Two warnings say where it disagrees with them, each with both numbers. Where the geometry refinement moves the cell’s shape (a length beyond the common scale, which trades with the distance) more than 3 % or an angle more than 3° from what was given. And where, at the centre and distance the stills geometry trial decides (§1.4), the cell the trial’s 96-frame sample indexes to de novo puts more than 1/0.9 times as many of its spots on the lattice as the cell given: the cell given may then be another crystal form than most of the frames, or a shape they do not have - the same lattice in a shape it does not have still indexes the frames, at a distance of its own, and merges far worse than the run without -C.

One crystal form. A sample can hold two crystal forms, and a known-cell indexer fits both to the given cell’s orientation search; their refined cells then fall into two volume populations, and merging both mixes two structures. The populations are the peaks of the histogram of \(v/v_\mathrm{given}-1\), each out to the valley on either side that separates it from another, with a bin that follows the spread of the data, so neither a population’s width nor its distance to the next is a fixed number. The frames merged are the population whose mean cell is nearest the given cell, judged first by its proportions - the ratios of its edges and the cosines of its angles, each frame’s cell put in the given cell’s order of axes - and by its size at a third of that weight. The volume alone does not say which population is the given cell’s: it scales with the detector distance the frames were refined at, and a start distance 2 % long put the other form of a two-form sample 4 % from the given cell in volume and its own form 5 % from it, while the proportions do not change with the distance. A run with one population has no such valley and keeps every frame. The log says how many frames were left out on either side. The stills geometry refinement fits on the same population: its sampled frames are filtered by it before the bundle and the module placement are formed, the population told from the strong frames (at least 20 indexed spots), whose cells show the valley between two forms where a weak frame’s cell spreads across it.

Without a given cell the same question is asked of the frames on the run’s own cell (within the indexing tolerance of it), whose two forms can lie inside that tolerance. Each frame’s cell is put on the run’s axes (of the orders of its axes, the one nearest the run’s cell, so two near-equal axes indexed the other way round compare alike), described by its edges as logarithms, and projected on the direction the cells spread along most, which is the direction between two forms where there are two. The angles are left out: a still’s refined angles carry the indexing more than the crystal - one form comes out with its monoclinic angle on one axis or another, or held at 90° - and spread more than two forms’ angles differ. The populations of that coordinate are found as above; the largest is merged, and the next, where it holds at least a tenth of the frames and its mean shape is at least 1 % from the major one’s (closer groups are one form whose cell drifts), is left out of the merge and reported (CELL_FORMS, see the report), with its cell to process it with -C. The cell written is the merged frames’ own, with or without a given cell.

Detector modules. Where the detector is described module by module (Module geometry), the same refinement places each module with enough spots on its frames’ lattices as a rigid block - a shift and an in-plane turn - where that predicts held-out spots better: the strong frames are split in half, each half fitted with the modules fixed and with them placed, and scored on the other. The placement is used if it predicts the held-out spots better as a whole, and then each module keeps its move only if the held-out spots on that module are predicted better; the others go back to where they were given and the placement is fitted again. On a detector of many modules the outer ones, reached only by a few strong high-resolution spots, are the ones this decides on. --panel-refine keeps every move without the tests, --panel-refine=off none. The placement starts from the beam, the distance and the cell fitted on the same frames with the modules held, each frame’s lattice taken from that fit, not from the file’s geometry: from a start off in distance and centre the search below moved every module by the centre’s error and the placement then pushed two modules of the second ring outwards, where the distance’s error had left their spots, and the distance settled 0.8 % long. The modules move only relative to one another: a gauge holds their spot-weighted mean shift, turn and outward push, and with the detector tilt refined also the two tilt-like gradients across the detector, at zero, so the beam centre, distance, tilt and crystal orientations carry what all modules share. A coarse search of each module’s position comes first, scored like the beam centre by the spots that land on a lattice. The placement is used from there on for a foreign multi-panel detector and for modules given as a CrystFEL .geom; for a JUNGFRAU master it is measured and reported only.

\ No newline at end of file diff --git a/CPU_DATA_ANALYSIS_INTEGRATION.html b/CPU_DATA_ANALYSIS_INTEGRATION.html new file mode 100644 index 000000000..4fc3b7d2f --- /dev/null +++ b/CPU_DATA_ANALYSIS_INTEGRATION.html @@ -0,0 +1 @@ + Data analysis: integration, scaling and merging (§8–§12) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Data analysis: integration, scaling and merging (§8–§12)

Part of the CPU/GPU data-analysis reference; the section numbers are continuous across its parts.

8. Reflection prediction

Jungfraujoch predicts reflection positions for integration by enumerating Miller indices within a resolution cutoff and accepting those that satisfy a diffraction condition model.

8.1 Enumerating reciprocal lattice points

For a maximum resolution \(d_\mathrm{min}\), accept \((h,k,l)\) such that: \( \lVert \mathbf{p}(h,k,l)\rVert^2 = \lVert h\mathbf{a}^* + k\mathbf{b}^* + l\mathbf{c}^*\rVert^2 \le \left(\frac{1}{d_\mathrm{min}}\right)^2. \)

8.2 Still prediction (excitation-error cutoff)

For still images, the diffracting condition is approximated by an excitation-error cutoff: \( \left|\Delta_\mathrm{Ewald}(\mathbf{p})\right| \le \Delta_\mathrm{cut}. \) Accepted reflections are projected to the detector by intersecting the diffracted direction \(\mathbf{S}=\mathbf{S}_0+\mathbf{p}\) with the detector plane, using the current geometry.

When the beam has a finite energy bandwidth, this window is broadened radially per reflection: the cutoff is combined in quadrature with a bandwidth smear, \(\sqrt{\Delta_\mathrm{cut}^2 + (3\,\sigma_\mathrm{bw})^2}\), where \(\sigma_\mathrm{bw}\propto|p_z|\) (the reciprocal-space depth along the beam, growing as \(\sim 1/d^2\)). This keeps high-resolution reflections — smeared by the bandwidth into radial streaks — from being clipped. The same \(\sigma_\mathrm{bw}\) is deconvolved from the measured profile radius (§11.1), so it is not double-counted.

The window follows the run’s rocking curve. A cutoff of twice a frame’s own profile radius (§11.1) is one width at every resolution, while the rocking curve widens with \(d^*\): it predicts many widths at low resolution, mostly empty, and cuts the curve at high resolution. So, with the stills partiality post-refinement on (the default, §10.2), a sample of the run - a tenth of its frames, at least 2000 - is first integrated with that cutoff, scaled against its own merge, and the run’s rocking curve measured on it as the merge measures it (§10.2): its width \(\sigma(d^*)\) and its centre, the radial scale. Every frame is then predicted through \(|\Delta_\mathrm{Ewald}| \le 2\,\sigma(d^*)\), with \(\Delta_\mathrm{Ewald}\) taken on the reciprocal lattice scaled by that radial scale, and the bandwidth term enters through \(\sigma(d^*)\) instead of the quadrature above. With --simple-stills the frame’s own cutoff stays.

8.3 Rotation prediction (Laue equation + partiality model)

For rotation/oscillation datasets, Jungfraujoch solves for rotation angles \(\phi\) where the rotated reciprocal lattice point satisfies the Ewald-sphere condition. In an XDS-like notation, define:

  • rotation axis unit vector \(\mathbf{m}_2\),

  • \(\mathbf{S}_0\) incident vector,

  • \(\mathbf{S}(\phi)=\mathbf{S}_0+\mathbf{p}(\phi)\).

A key quantity is: \( \zeta = \left|\mathbf{m}_2\cdot \mathbf{e}_1\right|,\quad \mathbf{e}_1 = \frac{\mathbf{S}\times \mathbf{S}_0}{\lVert \mathbf{S}\times \mathbf{S}_0\rVert}, \) which also appears in XDS as the Lorentz component linked to the rotation axis.

A Gaussian mosaicity model yields a partiality fraction over an oscillation width \(\Delta\phi\):

\( P(\phi;\sigma_M,\zeta,\Delta\phi) = \frac{1}{2}\left[\mathrm{erf}\!\left(\frac{\phi+\Delta\phi/2}{\sqrt{2}\,\sigma_M/\zeta}\right) - \mathrm{erf}\!\left(\frac{\phi-\Delta\phi/2}{\sqrt{2}\,\sigma_M/\zeta}\right)\right], \)

with mosaicity \(\sigma_M\) in radians.

Reflections are predicted if they meet minimum \(\zeta\) and mosaicity-window criteria, and their predicted detector coordinates fall on the active detector area.

8.4 Systematic absences (centering)

Systematic absences are applied at the centering level (prior to full space-group symmetry) when the space group is supplied by the user. With no user-fixed space group, prediction runs in \(P\) regardless of the centering the lattice search inferred: the centering-absent reflections are integrated so that the space-group search (§13) can confirm or disprove the centering from the measured intensities, and so that a missed superstructure shows up. For each centering symbol:

  • \(I\): absent if \(h+k+l\) odd,

  • \(A\): absent if \(k+l\) odd,

  • \(B\): absent if \(h+l\) odd,

  • \(C\): absent if \(h+k\) odd,

  • \(F\): absent if any of \(h+k, h+l, k+l\) is odd,

  • \(R\): absent if \((-h+k+l)\bmod 3 \ne 0\),

  • \(P\): no centering absences.


9. 2D Bragg integration (profile fitting over a three-ring ROI)

Jungfraujoch integrates each predicted reflection in the detector plane over a CrystFEL-inspired “three-ring” region of interest (§9.1). The default extraction is profile fitting (Kabsch; §9.3), which weights each pixel by a fitted spot profile and so recovers weak reflections far better than plain summation; plain box summation (§9.2) is retained as the seed for the profile and as a fallback. Both methods share the same ROI and background model, and emit the same per-reflection \((I,\sigma,\text{partiality},d)\), so scaling, the rotation combine (§10.6) and merging consume either unchanged.

9.1 Regions of interest

For each predicted reflection at \((x_p,y_p)\), define three radii:

  • \(r_1\): inner signal radius,

  • \(r_2\): inner background radius,

  • \(r_3\): outer background radius.

The defaults are \(4,6,13\) px for rotation data and \(6,8,14\) px for stills, which have a sparser pattern and can afford the wider ring. --integration-radius sets them by hand; on rotation data \(r_1\) is otherwise measured from the crystal’s own spots (§9.5).

Pixels are classified by their squared distance \(r^2=(x-x_p)^2+(y-y_p)^2\):

  • signal region: \(r^2 < r_1^2\),

  • background annulus: \(r_2^2 \le r^2 < r_3^2\).

Invalid pixels (masked/bad/saturated) are excluded from both sums. In addition, pixels lying inside the signal disk (\(r<r_2\)) of any other predicted reflection that puts at least 5 % of its flux on this frame (partiality \(\ge 0.05\)) are removed from this reflection’s background annulus, so a neighbouring spot cannot leak into the background estimate. Prediction reaches \(\pm4\sigma\) of the rocking curve, so on a finely sliced frame most predictions are the tails of reflections recorded on the frames either side; left in, they would fill every annulus of a dense pattern while the frame shows no spot there. A reflection whose annulus keeps five or fewer clean pixels is dropped. (Both the annulus and that exclusion become ellipses when the option below is used; with it off, which is the default, they are the circles just described.)

Radially elongated background ring (opt-in, --integration-stencil <k>, default 0). The three radii above are one triple for the whole run, identical for every reflection at every resolution. A reflection is not round, though: a finite bandwidth streaks it radially by \(\sigma_\mathrm{bw}=\text{bandwidth}\cdot R_\mathrm{px}\), with \(R_\mathrm{px}\) the distance from the beam centre — the same physical smear as §8.2’s and §11.1’s \(\sigma_\mathrm{bw}\), expressed here in detector pixels where those sections use reciprocal units; the two forms are never mixed in one formula. Throughout, \(\text{bandwidth}\) is the rms relative energy spread: the user-facing --bandwidth takes a FWHM (a DMM’s usual specification) and it is divided by 2.355 on input. On a radially smeared spot the fixed \(6\ldots13\) px ring therefore sits only \(\approx1.3\)–\(2.2\) radial \(\sigma\) from the centre — on the reflection’s own tails, which it then measures as background.

With \(k>0\) the background ring becomes an ellipse, elongated along the beam→reflection direction by \(k\sigma_\mathrm{bw}\). The radial semi-axes become \(r_2+k\sigma_\mathrm{bw}\) and \(r_3+k\sigma_\mathrm{bw}\); the tangential half-widths stay \(r_2\) and \(r_3\); and the growth is capped at \(2r_3\), which bounds what a mis-declared bandwidth can do to the bounding box. Pixels are then classified as

  • signal region: \(r^2 < r_1^2\) — a circle, unchanged,

  • background ring: \(r^2-q_\mathrm{in}\rho^2 \ge r_2^2\) and \(r^2-q_\mathrm{out}\rho^2 < r_3^2\),

where \(\rho\) is the pixel’s radial offset (its projection on the beam→reflection direction), \(g=\min(k\sigma_\mathrm{bw},\,2r_3)\) is the capped growth, and \(q=1-\big(r/(r+g)\big)^2\) for the boundary concerned. Written this way \(k=0\) gives \(q=0\) and both tests collapse onto \(r^2\) exactly in floating point, so the default classifies every pixel exactly as the circular stencil did. The neighbour exclusion above follows: each neighbour’s inner ellipse, taken in that neighbour’s own radial frame, is what is masked out of this reflection’s ring.

The width is the bandwidth streak alone, and deliberately not the profile’s full radial variance of §9.3, which also carries the sensor parallax and weak-spot capture terms. Those two are the only terms there are on a monochromatic beam, and widening the ring by them neither helps the crystals with clean high-resolution shells nor leaves the weak ones alone. The bandwidth streak, by contrast, is a measured elongation of the recorded spot — principal axis along the radius to within a couple of degrees, and azimuth-independent. Keeping only it also makes the option exactly inert on a monochromatic beam, where \(\sigma_\mathrm{bw}\) is zero.

Growing the ring also grows the neighbour exclusion, so on a crowded pattern fewer background pixels survive; a reflection left with too few is rejected outright. The loss is typically under 0.1% of reflections, but it is not structurally zero.

Only the ring moves. The signal disk \(r_1\) stays circular, deliberately: it sets \(n_S\), it sets \(\mathrm{var}(\hat b)\), it is the domain the profile width is learned over (§9.3), and with --integrator boxsum it drives the all-or-nothing “every signal pixel valid” acceptance gate (§9.2), so growing it would reject any box sum carrying a single bad pixel anywhere along a long streak. In the default gaussian mode \(r_1\) does not set the intensity at all — the fit grid, \(\lceil r_2\rceil\), does.

What a circular \(r_1\) loses is flux, and that loss is not a function of resolution alone: measured per reflection, it carries a directional component worth several Ų with a definite principal axis, on top of the isotropic part. Nor is there anything in the merge to absorb it. There is no per-shell scale, and there cannot usefully be one: every scale in §10 is fitted against a reference built from a reflection’s own symmetry equivalents, and equivalents share \(s^2\) exactly, so any function of \(s^2\) lies in the exact null space of the whole scaling model — a per-shell parameter would have zero residual to fit against. (XDS and DIALS have the same null space, for the same reason.) The isotropic part of the loss is instead degenerate with the overall Wilson \(B\) and is silently reported as part of it, so the reported WILSON_B / _reflns.B_iso_Wilson_estimate carries an \(r_1\)-dependent contribution: measured across a constant-ring-area radius sweep it falls monotonically as the disk grows, by 0.5 Ų on sharp strong data and by up to ~10 Ų on weak wide-spot data. What this costs the data is much less than what it costs the flux, because most of the loss is matched by a proportional \(\sigma\): it moves no CC\(_{1/2}\) and no \(R_\text{meas}\), and — to within a few hundredths of an ångström — no resolution cut.

Measured spot footprint (automatic). The radii above are chosen from spots at 5 Å, which at high X-ray energy sit close to the beam. Away from it a spot can grow several times wider — radially from the sensor’s parallax and the obliquity of the incidence, tangentially from the crystal’s azimuthal spread, which rotates the diffracted beam about the incident one and smears the spot along its ring. On small-molecule data at 20–25 keV the standard deviation grows from ~1 px near the beam to ~5 px at the detector edge: the \(r_1 = 4\) disk holds a quarter of the flux there, the \(6\ldots13\) px ring a third of it, and the profile widths learned inside \(r_1\) (§9.3) saturate near \(r_1^2/4\). So the pre-scan measures every spot it finds with a window that follows the spot — three of its own standard deviations, iterated and re-centred — separately along and across the radius, and tabulates the median widths \(\sigma_\rho,\sigma_\tau\) against the distance from the beam. Wherever \(3\max(\sigma_\rho,\sigma_\tau)>r_1\) the integrator then (i) starts the background ring at \(4\sigma\) along each axis, (ii) sums the reflection over the \(r_1\) disk and the \(4\sigma\) footprint ellipse, so the summation — the profile fit’s seed and its fallback — holds the spot rather than its core, and (iii) builds the per-reflection Gaussian at the measured widths on a grid grown to hold them. Where every spot fits the disk nothing is installed and the integration is unchanged bit for bit, which is the case for compact protein spots; like the measured radius, the footprint applies to the canonical pass and not to the geometry pre-pass, and a canonical pass whose wider rings the neighbours starve falls back to the settings without it. The reach is \(4\sigma\) rather than the \(3\sigma\) that decides whether a spot outgrew the disk because wide spots are not Gaussian: mosaic streaks and diffuse halos carry flux past \(3\sigma\), which a ring starting there reads as background. Judged by refining the published structures with SHELXL, it removes the intensity loss that grew with resolution on the small-molecule sets (rugnux/model intensity in the outermost shell 0.81–0.91 → 0.98–1.02).

Split reflections (automatic). A crystal made of slightly misaligned domains — the ferroelastic domains a crystal forms below a phase transition, or a cracked or split crystal — records each reflection as two or more compact spots on either side of the position the averaged lattice predicts, moving apart with resolution. The widths above are measured about each spot and so see compact spots; the \(r_1\) disk then holds the gap between them and the background ring lands on them, and the loss grows to almost everything at the detector edge. Once the geometry pre-pass has a lattice, every spot it indexes is compared with the predicted position of its own reflection on the same frame, and the mean square of that offset, along and across the radius and in the same distance bins, is added to the pre-scan widths. The table then describes the reflection rather than the spot, and the canonical pass integrates with it exactly as above. Where spots sit on their predictions it moves the widths by the prediction error alone (0.2–1 px on protein data, where no reflection then outgrows \(r_1\)); on an inorganic crystal measured below its ferroelectric transition, where every reflection off one zone is a doublet, the offsets reach 8–16 px at the edge, and SHELXL refinement of the published structure goes from \(R_1 = 0.27\) with a spurious extinction parameter to \(R_1 = 0.05\).

9.2 Box summation (seed and fallback)

Detector units and the gain. Frames are integrated in the units the file stores them in — photons for a photon-counting detector (and for a detector whose background resolves single photons, whose frames are read as whole photons), ADU for a CCD or an analogue XFEL detector whose file states no gain — with \(g\) detector units to a photon (\(g = 1\) for photon counting; measured on a few frames, or given with --gain; a \(g\) below 1, a CCD read out binned whose pixels scatter less than their mean through the point spread, is taken as 1). The gain enters only where a photon count is assumed: a pixel’s variance is \(g\) times its value, so every variance below is taken at \(g\); the background clip is \(\hat b + n\sqrt{g\,\max(\hat b, g)}\); the variance floors are one photon (\(g\) ADU for \(\sigma\), \(0.01g\) for the fit’s background term); and every reflection leaves the integrator divided by \(g\) — \(I\), \(\sigma\) and the background in photons — which is what the merge’s variance model assumes. Integrated this way a frame in ADU gives the reflections its photons would, the same stencil, clip and profile, rotation and stills alike. The spot finder’s threshold, the spot-width measurement and the hot- and dead-pixel tests take their photon terms at the same \(g\).

Let:

  • \(S = \sum I(x,y)\) over signal pixels,

  • \(n_S\) = number of valid signal pixels,

  • \(B = \sum I(x,y)\) over background pixels,

  • \(n_B\) = number of valid background pixels.

Background per pixel and integrated intensity: \( \hat{b} = \frac{B}{n_B},\qquad \hat{I} = S - n_S \hat{b}, \) with a Poisson-like uncertainty \(\sigma(\hat{I})=\max\!\big(1,\ r_\sigma\hat{I},\ \sqrt{S + n_S^2\,\mathrm{var}(\hat{b})}\big)\), i.e. \(\sqrt{S}\) floored both at 1 photon (the formula is in photons; on frames in ADU it is taken at the gain, above) and at a small fraction \(r_\sigma\) of the intensity. The second term under the root is the uncertainty of the background estimate itself: \(\hat b\) is measured from a finite number of ring pixels, \(\mathrm{var}(\hat b)=\hat b/n_B\), and it is subtracted \(n_S\) times over, so it enters squared. Omitting it understates the variance by \(1+n_S/n_B\) — 1.11 with the shipped circular stencil (\(n_S = 45\), \(n_B = 408\)) — and so understates \(\sigma\) by up to \(\sqrt{1+n_S/n_B} \approx 1.05\), a bound attained on background-limited (weak) reflections and falling towards 1 on strong ones, where \(S\) dominates; with an elongated ring \(n_B\) grows with resolution, so the factor is no longer one number for a run. The same term is carried into the profile fit (§9.3), where it adds \(\big(\sum P/v \,\big/ \sum P^2/v\big)^2\,\mathrm{var}(\hat b)\) — the square of \(\partial I/\partial\hat b\) for that fit; \(n_B\) is the count of pixels behind the final background value, so a clip or trim that discards ring pixels raises it. A box sum is accepted as “observed” only if all signal pixels were valid and \(n_B\) exceeds a minimum — it measures what is in the disk with no model of what should be there, so it cannot renormalise a disk it has lost pixels out of. The profile modes can, and do (§9.3). This box sum is the classical estimator; it is used directly with --integrator boxsum, and otherwise seeds the profile fit below, where \(S\) and \(n_S\) then count only the pixels that were actually read.

High-side clipped background (default on). Because \(\hat{I}=S-n_S\hat{b}\) is a small difference of large numbers for weak reflections, a per-pixel background bias \(\delta\hat{b}\) becomes a fractional intensity bias \(\approx n_S\,\delta\hat{b}/\hat{I}\) that grows as \(\hat{I}\) shrinks — worst at the resolution edge. A plain ring mean reads high there, because neighbour-spot wings that survive the signal-disk mask, tails and zingers are one-sided (positive) contaminants. The ring mean is therefore made robust: pixels above \(\hat{b}+n\sqrt{\hat{b}}\) (in photons; above) are rejected and the mean recomputed, with \(n=4\) (--background-clip; \(n=0\) disables), whatever the bandwidth. A clean Poisson ring is essentially unchanged by the cut (measured false-rejection rate 0.04–0.39 % at \(4\sigma\)), while a 40-pixel neighbour core at \(+100\) counts shifts the estimate by \(+0.009\) ct/px.

The clip cuts only the high tail, which matters: the symmetric trimmed mean it replaced (drop the lowest and highest fraction \(f\) of ring pixels, \(f=0.10\); still reachable with --background-trim, which switches the clip off) is not a consistent estimator of the mean of a right-skewed Poisson sample. It sits \(\approx0.1\) ct/px below the true mean at every level, and with \(n_S = 45\) signal pixels in the \(r_1\) disk that under-estimate adds \(\approx4.5\) counts to every partial — negligible at low resolution, but a large fraction of a partial in the outermost shell. The trim also collapses once contamination exceeds \(\approx10\,\%\) of the ring, where the clip does not. Note that removing a positive background bias lowers \(\langle I/\sigma\rangle\) and raises edge \(R_\text{meas}\), because both are inflated by information-free counts — so neither may be read as evidence against the change.

Both estimators are computed in the shared background pass, but only the trim reaches plain box summation: the high-side clip is skipped for --integrator boxsum, which therefore uses the plain ring mean unless --background-trim is given.

Radial background correction. A ring mean estimates the background under the signal disk correctly only if the background is flat there. The signal disk and the ring are concentric, so for a background that is linear in position \(\langle B\rangle_\mathrm{ring}=\langle B\rangle_\mathrm{disk}\) identically — a plane or gradient fit buys exactly nothing. The leading error is the curvature of the radial background, which is negligible on a smooth background but reaches tens of counts on a single reflection sitting on a sharp powder ring. That error is a kernel over radial offset, \( \delta \hat b \;=\; \textstyle\sum_k \kappa_k\, \bar B(r_0+k), \) with \(\kappa\) the annulus-minus-disk histogram of the stencil over radial offset, averaged over azimuth, and \(\bar B(r)\) the image’s own radial background curve. With the fixed circular stencil (\(k=0\), §9.1) that single kernel serves every reflection. An elongated ring does not: its radial-offset histogram depends on how far that particular reflection’s ring was grown, so \(\kappa\) becomes a small table of kernels, indexed by the growth rounded to whole pixels. The azimuthal average survives the change unaltered, because the stencil is rebuilt in the reflection’s own frame at each azimuth and so stays radially aligned: what is averaged over is the sub-pixel phase of the detector grid against the radius, which is what genuinely differs between reflections. Applying it costs one short dot product per reflection and no extra pixel reads; correcting the background scalar means the box sum, the profile fit and the non-signal variance all pick it up. The variance carried to the merge, \(\mathrm{var}_\mathrm{bkg} = g\,(n_S\hat b + n_S^2\,\mathrm{var}(\hat b))\), moves with the corrected \(\hat b\) in its first term — the Poisson share of the background under the disk — while \(\mathrm{var}(\hat b)\), the noise of the ring estimate, and \(\sigma\), taken from the counts in the disk, do not depend on a smooth curve and stay.

The curve \(\bar B(r)\) is the adaptive spot finder’s peak-excluded background per resolution ring of the whole frame (§3.2), one value per pixel of radius: every pixel of the frame, against the few dozen to few thousand reflections whose own rings would otherwise sample it. Where that curve is in use the ring’s high-side clip follows it: a ring pixel at radial offset \(u\) is clipped against the threshold plus the curve’s rise \(\bar B(r_0+u)-\bar B(r_0)\), in whole counts. On a background falling steeply away from the beam a flat threshold cuts the beam-side half of the ring as outliers and the background reads low — up to 150× too strong a low-resolution reflection on a binned CCD near the beam stop. With the frame’s curve the correction is not the kernel above but the curve itself averaged over the pixels the reflection actually reads: its mean over the ring pixels the clip kept minus its mean over the readable disk pixels, summed while the box is read anyway. The kernel is an average over a whole annulus, so it counts the curve wherever the ring has lost pixels — to the clip, to a neighbour’s signal, to a masked or shadowed pixel — and next to the beam-stop shadow, where the curve falls steeply into the shadow and the ring’s beam-side part is masked, that turned a correction of a few counts into tens and made low-resolution reflections near the stop read strongly negative. The curve is read at the \(2\theta\) of each reflection’s position — the radius \(F\tan 2\theta\) it is tabulated against, read off the geometry as the curve’s rings are — and not at its distance from the PONI, which on a tilted detector is a few pixels off exactly where the curve is steepest. Without a frame curve (fixed-threshold spot finding) the curve is accumulated from the clipped annulus pixels of the predicted reflections themselves, the kernel applies it, and the clip stays flat.

When it is applied. --background-radial takes on, off or auto; in Rugnux it is auto by default (the broker keeps it off), and auto is decided per run, in the pre-scan, on empty apertures — the same measurement that, on stills, also chooses how far the ring reaches (the \(r_3\), up to the one the run starts from, whose ring predicts the empty disk best). On a grid of apertures away from every found spot, the ring’s prediction of the empty disk is taken twice: plain, and with the correction applied exactly as the integrator applies it (the clip following the curve, and the curve’s mean over the ring pixels kept minus its mean over the disk). With nothing in the aperture each difference is the error the ring makes in a reflection’s background, noise plus bias. Rotation measures every stencil the spot width can give it (and the one it starts from, which the geometry pre-pass and the starvation guard return to) and reads the one it gets.

  • Stills have no other correction, so it is applied to every image of a run where it lowers the apertures’ mean square error at all.

  • Rotation has one: under auto, each image whose peak-excluded ice score (§3.3) reaches --ice-min-score is corrected, with the frame’s curve as on stills (the curve of the reflections’ own rings misses the narrow peak of a smooth ice ring). Correcting every image instead is chosen only where it takes at least 10 % of the apertures’ mean square error away: on photon-counting sweeps the apertures gain only a few percent and correcting every image costs ISa and anomalous signal; where it pays — the rings of home-source CCD frames, a smooth ice ring — they gain tens of percent. A run below the margin keeps the per-image ice correction, bit for bit.

The model is a function of radius alone, so it is applied only where that is true of the background. The per-image ice gate rests on this: smooth powder ice is a radial feature and is corrected; ice made of discrete crystallite spots — which the profile channel is blind to and the spot channel catches — leaves no smooth ring to model, and correcting it makes matters worse. Measured against a fixed atomic model, comparing ice bands with resolution-matched decoy bands carrying no ice: on a crystal with pure smooth ice the correction removes 43 % of the bands’ excess amplitude, and the improvement is 7× larger inside the bands than outside, which is its stated mechanism; on a crystal whose ice is textured the same correction increased the excess amplitude by half; on a clean crystal it is inert to four decimal places. A strongly polarised beam or panels of different response make the background non-radial too; the apertures see that as a ring the correction predicts worse, and a run where they do keeps it off. Auto engages only where a peak-excluded background exists (adaptive spot finding, §3.2) — a plain azimuthal profile carries the Bragg peaks and cannot support an absolute threshold, so without one auto leaves the correction off.

9.3 Profile-fitted extraction (default)

A fixed signal disk captures a width-dependent fraction of each spot, which puts a multiplicative floor on the per-observation precision of strong reflections and weights weak reflections poorly. Profile fitting removes this by extracting each intensity against a fitted spot shape, without needing reference intensities. Per frame:

  1. Seed. Box-sum every reflection (§9.2) to get a rough intensity and observed centroid, and select strong spots (significance \(\ge 5\)).

  2. Build the profile. For gaussian (the default) the width is taken per resolution shell from the measured second moments of the strong spots (shell-dependent because spot size grows with resolution). The moments are anisotropic: each strong spot’s pixels are rotated into its own radial/tangential frame before being accumulated, giving \(\sigma^2_r\) and \(\sigma^2_t\) separately. Stacking the spots in the detector frame instead — they sit at every azimuth — averages the two directions away, leaving only \(\sigma_r^2+\sigma_t^2\), so radial smearing is read back as a wider tangential spot. For empirical the profile is instead the averaged, background-subtracted pixel grid of the shell’s strong spots, accumulated in the detector frame on their rounded predicted positions. For gaussian only, the profile is then rebuilt for each reflection, centred on its sub-pixel predicted position (the noise-free geometric centre, not the observed centroid) and, where needed, elongated only along the radial direction (away from the beam centre) — because two effects stretch a spot radially but not tangentially:

    • a finite energy bandwidth smears each spot by \(\sigma_\mathrm{bw}=\text{bandwidth}\cdot R_\mathrm{px}\) (\(R_\mathrm{px}\) = distance from the beam centre, large at high resolution), and

    • sensor parallax — the depth over which a photon converts in a thick Si/CdTe sensor — adds a term \(\propto\tan^2(2\theta)\) (material- and energy-dependent), plus a small fixed weak-spot capture term.

    The two enter as a floor on the measured radial excess: \(\sigma^2_\mathrm{radial}=\sigma^2_t+\max\!\left(\sigma^2_r-\sigma^2_t,\ \sigma_\mathrm{bw}^2+c_\mathrm{par}\tan^2(2\theta)\right)\), tangential unchanged at \(\sigma^2_t\). The measured excess is what the signal disk can resolve; the analytic term takes over for a streak too long to be measured there. The Gaussian is built on a grid grown to hold the streak — capturing it without the tangential background an isotropic widening would add. The empirical profile keeps the fixed per-shell grid and gets none of this.

  3. Fit (Kabsch). With profile \(P\), background \(B\) and the shell variance model, the intensity and its uncertainty are \( I = \frac{\sum P\,(c-B)/v}{\sum P^2/v},\qquad \sigma = \sqrt{\frac{1}{\sum P^2/v}},\qquad v = \max\!\left(B + I\,P,\ \tfrac{1}{2}B\right), \) where \(c\) is the pixel value and the de-biased variance \(v\) (background plus model signal, rather than the down-fluctuating observed count) is iterated (a few passes). The plug-in \(I\) enters as it is: half-wave rectifying it, \(v=B+\max(I,0)P\), lets \(v\) — and with it the reported \(1/\sum P^2/v\) — respond only to upward fluctuations of a noisy estimate, which adds \(\approx0.4\,\sigma\sum P^3/(\sum P^2)^2\) to every \(\sigma\) whatever the count rate. That offset is invisible on strong reflections and a large fractional inflation on weak ones; the \(\tfrac12 B\) clamp keeps \(v\) positive without reintroducing it. As a guard, if the profile intensity runs away from the box-sum seed (by more than ~10 box-sum \(\sigma\)) it falls back to the seed, and the background term is floored at \(0.01\) ct/px — enough to keep \(P^2/v\) finite when the ring mean reads exactly zero, which a ring of \(n_B\) pixels cannot distinguish from any background below \(\approx1/n_B\). The rotation/excitation partiality is carried exactly as in the box-sum path.

Pixels the fit cannot use (MINPK). A profile fit is the amplitude of a normalised profile, so a pixel left out of the sum renormalises the estimator by construction: it costs information — \(\sum P^2/v\) shrinks and \(\sigma\) grows — but biases nothing. That is what keeps a reflection whose signal disk is cut by a mask, an untrusted region, a detector gap or an overload: those pixels are simply not read, and the fit is taken over the rest, exactly as the shared pixels of a crowded reflection are (--overlap exclude). The reflection is kept only while enough of the expected profile survives — at least --overlap-minpk of the profile mass that falls on the detector at all, default 0.75, which is XDS’s MINPK and dials’ valid_foreground_threshold. The complete reflections alone teach the profile, its resolution shells and their widths. --integrator boxsum has no profile to renormalise with and keeps the all-or-nothing rule of §9.2.

“Biases nothing” holds only while the profile model is exact. Lose the peak and the amplitude is set by the wings alone, so the result stops being a measurement of the reflection and becomes a measurement of how well the fitted shape describes it. The worst case is a pixel invalidated by the flux it saw — a detector’s per-frame overload marker: that pixel goes missing because the reflection was bright, so the loss concentrates on the strong low-resolution reflections that are the largest terms of \(R_\mathrm{meas}\), where the fit reads \(-50\%\) against the symmetry mates. MINPK cannot catch it, because it cuts on profile mass and the peak of a broad spot is a few percent of the mass. So a second condition applies alongside it, on any unreadable pixel whatever made it unreadable: no unreadable pixel may carry more than 0.9 of the profile’s own peak value. As a fraction of the peak rather than a radius in pixels, that scales with the spot — for a Gaussian it is a cut at \(\sqrt{-2\ln f}\,\sigma = 0.46\sigma\), the peak pixel alone where \(\sigma\) is 0.8 px and the crest of the ridge where the profile is a bandwidth streak — and it costs well under 0.1 % of the recovered observations.

The integrator is selected by --integrator boxsum|gaussian|empirical (default gaussian).

9.4 The prescaling correction

The deterministic per-reflection corrections are carried as three multiplicative factors. prescaling_corr holds the reciprocal Lorentz factor (rotation only — a still’s Lorentz factor is one) times the reciprocal polarization factor from the geometry-based term (§2.2), and nothing else: it is Lorentz x polarization, which is what LP means in every format the field reads. Beside it sit the two terms that describe what happened to the photon between leaving the sample and being counted, and that are kept apart from LP because detector response and beam/crystal geometry are different things: qe_corr, the sensor’s angle-dependent efficiency, and flight_corr, the medium in the flight path (§9.7). The total deterministic correction on a reflection is the product prescaling_corr * qe_corr * flight_corr, and every site that corrects an intensity — the integrator, the scaling fits, the merge ingest, the anisotropy analysis and the unmerged export — multiplies all three. None of them is a scale: the fitted per-image scale and the partiality are separate. The three reach the unmerged MTZ as its LP, QE and FLIGHT columns unchanged (QE and FLIGHT as divisors normalised to 1 at normal incidence), so raw counts are I / LP * QE * FLIGHT.

One term is deliberately not in it. The per-pixel solid angle, which the azimuthal profile does divide out (§2.2), is correctly absent here: a Bragg integration sums all the photons in a reflection, and how many pixels the detector happens to tile that footprint with does not change the count. Detector obliquity does stretch the footprint, and that enters as the parallax term of the spot-width variance rather than as an intensity scale.

9.5 Choosing the signal radius from the crystal’s own spots (rotation)

The three radii are one triple for the whole run, but on rotation data they are not a fixed constant: \(r_1\) is measured from how wide this crystal’s spots actually are (--adaptive-integration-radius, on by default, ignored when --integration-radius is given). On stills the same option measures instead how far the background ring should reach (§9.2, When it is applied).

Why \(r_1\) matters even though it does not set the intensity. In the default gaussian mode the intensity is a profile-fit amplitude over the grid \(\lceil r_2\rceil\) (§9.3), so \(r_1\) is not the integration domain. It is the aperture the profile width is learned over, and a second moment taken over a disk of radius \(a\) saturates at \(a^2/4\). At \(r_1 = 4\) the learned \(\sigma\) can therefore never exceed 2 px, and a crystal whose spots are broader than that is fitted with a profile the model cannot represent.

The measurement is independent of the integrator. It is made in the pre-scan, on the frames the beam-stop projection already reads, so it costs no extra frame reads and there is no feedback loop. On the spots the spot finder has already found, a spot is used only if it is clear of the detector edge and of the direct beam, has no neighbouring spot within 28 px, is one of the 40 strongest in its resolution band, sits on a fully readable disk, and reaches a signal-to-noise of 15 with its centroid within 2 px of the found position. For each surviving spot the background-subtracted encircled-flux curve is accumulated in 1-px annuli out to a fixed 14 px aperture and normalised at 8 px — an aperture that owes nothing to \(r_1\), \(r_2\) or \(r_3\).

Pooling. Spots are stratified into five resolution bands (2–3, 3–4.5, 4.5–7, 7–12, 12–30 Å), because a weak crystal’s strongest spots sit at high angle and a strong one’s at low angle. Each band with enough members contributes the radius at which its median curve reaches 0.80 of its normalised flux — \(r_{80}\) — at the band’s median \(d\). Those points are fitted by weighted least squares against \(1/d\) (the mosaic contribution to the detector footprint grows as \(1/d\)) and evaluated at a common 5 Å, then clamped to the range the bands actually measured so the fit never extrapolates.

The radius.

\[r_1 = \mathrm{clamp}\!\left(\mathrm{round}(2\,r_{80}),\ 4,\ 6\right),\qquad r_2 = r_1 + 2,\qquad r_3 = \sqrt{r_2^2 + 133}\]

The factor 2 is not fitted: for a Gaussian \(r_{80} = 1.794\,\sigma\), so \(r_1 = 2r_{80} = 3.59\,\sigma\), where the truncated second moment recovers 0.990 of \(\sigma^2\). The expression for \(r_3\) holds the background-ring area constant at its value for the shipped \(4,6,13\) (\(13^2 - 6^2 = 133\)) — a ring that shrank with the disk is what makes a bare --integration-radius worse than the default it replaces. The floor of 4 is that shipped default; the ceiling of 6 is pattern density, since \(r_2\) also drives the neighbour-ownership radius and the ring’s inner edge. At \(r_1 = 4\) the triple is bit-for-bit the shipped default, so a crystal with ordinary spots is left exactly where it was.

The sample grows until the answer settles. The frames are measured in tiers of stride 8, 4, 2, 1, each tier’s sample strictly containing the previous one, and the pooling is redone after each. Measuring stops when the new \(r_{80}\) is within 0.40 px of what the smaller sample said and is at least 0.25 px clear of both radii at which the rounding in \(r_1\) changes answer. Both conditions are load-bearing: clearance alone lets a small sample settle across a switch, and the step test alone lets it settle on one. Every frame of the sample is still read — the beam-stop mask and the beam centre are unchanged; what the tiers save is the decompression, preprocessing and spot finding the width measurement adds on top of the read.

It applies to the final pass only. A rotation run integrates twice (§7.5), and the widened radius is handed to the canonical second pass, not to the geometry pre-pass. The reason is that post-refinement takes its observed positions from the integrator, and an observed position is a first moment over the signal disk with the background still in it: a flat background adds nothing to the numerator but adds \(n\,b\) to the denominator, so every measured offset is pulled toward its prediction by \(I/(I + n b)\), and \(n\) nearly doubles between \(r_1 = 4\) and \(r_1 = 6\). A wider disk therefore under-corrects the geometry — enough, on a crystal whose metric is half a degree off orthorhombic, to flip the second pass’s de-novo Bravais choice.

The density guard. Widening \(r_1\) pushes \(r_2\), the ring’s inner edge, into the neighbours; a reflection whose ring is left with five or fewer clean pixels has no background and is dropped whole. The integrator counts the rings the neighbouring reflections would starve — every predicted neighbour, the rocking-curve tails the background itself does not exclude included, so the count measures the pattern’s density — apart from the ones the detector itself starves (module gaps, the beam stop, the resolution mask), a floor that reaches a couple of percent on some geometries and does not move with \(r_1\). Where the neighbour-driven count exceeds 1.13 % of the predicted reflections, the pattern is too dense for the widened radius and the final pass is integrated again at the fixed \(4,6,13\), reported as pass 3 of 3 with the reason in PASS_DECISION.

Every integration pass, adaptive or not, logs the radii it used together with the fraction of predicted reflections that lost their background ring, the fraction of rings the neighbouring predictions crowd, and the profile-fit fallback rate.


9.6 Measuring the bandwidth

A finite energy spread \(\sigma\) (\(\Delta\lambda/\lambda\), rms) smears a reflection along its own radius by \(2\tan\theta\,\sigma\) radians of \(2\theta\) and not at all across it. Most files do not state it — a multilayer monochromator is a beamline option, not a header field — so Rugnux reads it off the spots, on the same isolated strong spots the width of §9.5 is measured on (spot_width::EstimateBandwidth). The width settles on fewer spots than this slope needs, so the pre-scan keeps measuring spot shapes for the bandwidth alone until it holds 1000 of them or its sample runs out. For each spot, with \(u\) along the radius and \(v\) across it, the second moments about its centroid are

\[m_u = \tfrac1{12} + p_u + j_r^2\big(s^2 + 4\tan^2\theta\,\sigma^2\big),\qquad m_v = \tfrac1{12} + p_v + j_t^2 s^2,\]

with \(j_r\), \(j_t\) the exact pixels per radian of \(2\theta\) and of the angle across the scattering plane at that spot, \(s\) everything isotropic in angle (divergence, crystal size, mosaic spread), and \(p_u\), \(p_v\) the sensor parallax, fixed from the sensor’s physics: a photon converting at depth \(z\) (exponential with length \(L\cos\psi\) at angle \(\psi\) to the normal, truncated at the thickness) lands \(z\tan\psi\) along the ray’s in-plane direction. Then

\[y = (m_u - \tfrac1{12} - p_u) - (j_r/j_t)^2\,(m_v - \tfrac1{12} - p_v) = a + \sigma^2\,(2 j_r\tan\theta)^2\]

is a straight line whose slope is the bandwidth. It is fitted over eight equal-count bins of the abscissa, each a 20 %-trimmed mean weighted by its own scatter; the slope’s error is the spread of 200 bootstrap re-draws of the spots, inflated by the reduced \(\chi^2\) of the binned fit where the line fits worse than the scatter says, and the log calls the estimate significant at \(z>3\). It is a lower bound — mosaic spread seen along the radius subtracts — and a spread of cell edges is exactly degenerate with it, so what it measures is the effective radial broadening — which is what its consumers need.

A significant estimate is the run’s bandwidth, unless the file states one or --bandwidth is given (--bandwidth 0 forces a monochromatic beam); anything short of \(z>3\) leaves the beam monochromatic. From there it acts continuously, with no broadband mode: prediction and partiality (§8), the profile’s radial width (§9.3) and the background ring’s elongation (--integration-stencil, §9.1) all scale with it and are exactly what they were at zero bandwidth.

9.7 The flight path

A reflection leaving the sample at incidence angle \(\alpha\) to the detector normal reaches its pixel after \(D/\cos\alpha\) of flight rather than \(D\), so it crosses more of whatever fills the flight path than one arriving head-on and arrives attenuated. This is the same \(\cos\alpha\) geometry as the sensor crossing of §9.4, with the opposite sign: the sensor makes an oblique reflection read high, the medium makes it read low.

\[T(\alpha) = \exp\!\left(-\frac{D}{L\cos\alpha}\right), \qquad \text{correction to } I = \frac{T(0)}{T(\alpha)} = \exp\!\left[\frac{D}{L}\left(\frac{1}{\cos\alpha} - 1\right)\right]\]

with \(L = 1/\mu\) the attenuation length of the medium at the photon energy, from the same NIST tabulation the sensor uses. Nothing here is fitted: \(\mu\) is tabulated, and \(D\) and \(\lambda\) are stated by the file. Normalising at \(\alpha = 0\) divides out \(\exp(-D/L)\), a constant for the dataset that the fitted per-image scale absorbs; what is left is the only part of the flight path that is not degenerate with that scale.

For air, \(L\) falls steeply toward low energy — 8.2 m at 18 keV, 3.0 m at 12.4 keV, 0.089 m at 3.8 keV — and the size of the correction follows it:

photon energy

\(L\) (air)

\(D/L\) at 160 mm

correction at \(\alpha = 30°\)

at \(\alpha = 55°\)

18 keV

8.17 m

0.0196

+0.30 %

+1.5 %

12.4 keV

2.99 m

0.0535

+0.83 %

+4.1 %

8 keV

0.84 m

0.191

+3.0 %

+15 %

3.8 keV

0.089 m

1.80

×1.32

×3.8

Helium attenuates about 1/600 of air at 3.8 keV — two electrons an atom against nitrogen and oxygen, and a seventh of the density — which is exactly why long-wavelength stations use it. It is not vacuum, and is modelled rather than treated as one, though at these distances it is worth well under a per cent. Vacuum leaves every intensity untouched.

What it does to merged data

On an untilted detector \(\alpha\) is the scattering angle, so the correction is a pure function of resolution. It therefore cancels within a resolution shell and cannot move \(R_\mathrm{meas}\) or CC\(_{1/2}\) there; its whole effect on merged data is a shift in the Wilson \(B\). Friedel mates share \(2\theta\) and so receive an identical factor, which also means it cannot act on an anomalous difference at all. Both statements are quantitative predictions with no free parameter, and both are confirmed: the Wilson-\(B\) shift is reproduced to within 8 % on three datasets spanning an order of magnitude in \(D/L\), and where a pooled statistic does move, every resolution shell is unchanged and the pooled shift is reproduced by re-weighting alone.

That is what FLIGHT_PATH_WILSON_B in the results report quotes: the correction’s worth, in the one number it can move.

Why the medium is declared and not detected

No field of the NXmx application definition, and no field of any master file rugnux reads, describes the medium in the flight path — there is no air, helium, vacuum, flight-tube or pressure entry anywhere to detect it from.

Inferring it from the physics was considered and refuted. The natural idea is that air becomes unusable at low energy, so an implausibly low implied air transmission would mean helium; but in this corpus a confirmed helium station sits at 51 % implied transmission and a confirmed air station at 63 %. No criterion separates those two without being a threshold fitted between two points, so there is none.

rugnux therefore assumes air — which is what a beamline has unless it was built not to have one — and --flight-path helium|vacuum declares otherwise. Because that is an assumption made on the user’s behalf, the report states it (FLIGHT_PATH) together with what it was worth (FLIGHT_PATH_WILSON_B), and warns where it is worth enough to matter.


10. Scaling and merging

After per-image integration, Jungfraujoch scales observations and merges them into unique reflections. The design is intentionally compatible with XDS/XSCALE concepts, and handles both still and rotation data.

10.1 Observation model

For an observation \(j\) of a unique reflection \(h\) on image (or image group) \(i\), the predicted measured intensity is modeled as: \( I_{ij} \approx G_i \, L_{ij}\, P_{ij}\, I_h, \) where:

  • \(G_i\) is the image scale factor,

  • \(L_{ij}\) is the whole deterministic per-reflection correction of §9.4 - Lorentz x polarization, the sensor’s efficiency and the flight path together, not the LP term alone. Predictions carry its reciprocal split across three fields, so \(L = 1/(\texttt{prescaling\_corr} \cdot \texttt{qe\_corr} \cdot \texttt{flight\_corr})\) and the correction below is applied as a multiplication by their product; the scaling fits, the merge ingest and the anisotropy analysis all use the same three,

  • \(P_{ij}\) is a partiality term (model-dependent),

  • \(I_h\) is the merged (true) intensity parameter for that unique reflection.

A least-squares objective is minimized: \( \sum_{ij} \left(\frac{I_{ij}^{\mathrm{pred}} - I_{ij}^{\mathrm{obs}}}{\sigma_{ij}}\right)^2 \) solved by robust (Cauchy) weighted least squares, with optional post-fit smoothing of the per-frame scales for rotation series (§10.3).

10.2 Partiality models

The partiality applied is fixed by the data type and scaling stage, not chosen from a user menu:

  1. Rotation partiality (XDS-like; see §8.3), used for the per-frame scaling of rotation partials: \( P_{ij} = \frac{1}{2}\left[ \mathrm{erf}\!\left(\frac{\Delta\phi_{ij}+\Delta\phi/2}{\sqrt{2}\,\sigma_{M,i}/\zeta_{ij}}\right) - \mathrm{erf}\!\left(\frac{\Delta\phi_{ij}-\Delta\phi/2}{\sqrt{2}\,\sigma_{M,i}/\zeta_{ij}}\right) \right]. \) Here \(\Delta\phi_{ij}\) is observation \(j\)’s rocking offset from its exact Bragg angle on image \(i\), and the unsubscripted \(\Delta\phi\) is the oscillation width per frame — two different quantities that share a letter. The mosaicity \(\sigma_{M,i}\) is measured once per image at indexing (MLE, §11.2) and held fixed during scaling — only smoothed in frame order (§10.3), never re-refined (it is degenerate with the scale \(G\); §11.2).

  2. Unity (\(P_{ij}=1\)): used for the scale-on-fulls refit (§10.6), where each observation is already a complete reflection.

  3. Fixed: use the per-reflection partiality carried from prediction. Still/serial images are predicted with \(P=1\), so a single-pass stills scale is effectively unity/fixed — which is exactly what --simple-stills keeps. By default the stills path instead post-refines a physical partiality: a small per-crystal orientation tilt \((\delta\psi_x,\delta\psi_y)\) about the two axes perpendicular to the beam is refined against the running merge, and every reflection’s partiality is then recomputed analytically from the refined lattice through its excitation error \(\Delta_\mathrm{Ewald}=\big|\,|\mathbf{q}+\mathbf{S}_0|-1/\lambda\,\big|\) and a Gaussian width \(\sigma(d^*)\) — the run’s rocking width, measured once on the intensity-weighted excitation errors and shared by every crystal. It is measured per group of frames of similar prediction window (four per shell), each against its own window, the shell taking the median of the groups whose curve is narrower than their window, so the frames with the widest windows do not set it everywhere; and it is measured in eight shells of equal width in \(d^*\), made non-decreasing (pool-adjacent-violators, weighted by each shell’s summed signal) and interpolated linearly in \(d^*\) as a table. The three-term form \(\sigma^2=\gamma_0^2+(\gamma_e d^*)^2+(\mathrm{bw}\,|q_z|)^2\) — the reciprocal-lattice point’s own radius, the mosaic/divergence spread, and the bandwidth smear along the beam, in quadrature — is still fitted, sets the prediction window (§8.2) and stands in for the table where fewer than three shells are measurable. The curve is centred on the run’s radial scale of the reciprocal lattice — a wavelength or cell a little off, which the spot positions cannot see since they fix only \(\lambda d^*\) — measured from where the curve’s centre lies against \(d^{*2}\) and applied to \(\mathbf{q}\). Where the frames were predicted through the measured window (§8.2), the post-refinement uses that same curve rather than measuring it again; the curve is written to _process.h5 (/entry/MX/stillsRockingWidth*, stillsRadialScale), so --mode scale merges with it too. A tilt moves reflections on opposite sides of the Ewald sphere in opposite directions, so it reshapes the spatial pattern of partialities — a degree of freedom the per-image scale \(G\) does not have, and the reason the tilt is refined rather than a scalar partiality width, which would be degenerate with \(G\). Nothing is re-integrated (the integrated intensities are fixed); the tilt is hard-bounded at about 1° and held by a soft prior, so it stays inert on sparse or weak crystals. The cycle is merge → per-crystal tilt refinement (with \(G\) profiled out by the same robust Cauchy IRLS used for the per-frame scales, §10.3) → recompute \(P\) → re-merge, repeated a few times; the refined partiality is adopted on every crystal it was refined on. The per-crystal fits of \(G\) and of the tilt measure each residual against its expected variance at the model, background + counting + \((0.3\,I_\mathrm{model})^2\): a still’s strong reflections scatter about the model by tens of per cent, and in counting sigmas alone every strong reflection would be an outlier and the scale would be set by the weak ones.

Reflections below a minimum partiality are left out of the merge (--min-partiality, default 0.02 on rotation and 0.5 on stills): the empirical rocking curve of a still has a floor far out on its tail, from mis-oriented crystals, and dividing such an observation by a small model \(p\) makes it biased, not merely noisy. On stills this holds for the merges the scale and the partiality are refined against. The final merge, which has the fitted error model, takes every observation: the model’s partiality term \(c\,((1-p)/p)\,\langle I\rangle\) (§10.5) weights a low-partiality observation by what it is worth. A reflection - each Bijvoet hand under -A - is reported only if at least one of its observations reaches \(p \ge 0.2\); one seen only far out on its rocking curve rests on the partiality model alone. The error model is fitted on the observations at \(p \ge 0.2\).

An observation whose background variance is below zero is left out of the stills scale fits and merges, and the log counts them (Scaling: N observations on M frames are left out). Pixels counting photons cannot give one: it is what a background region reading below zero leaves, as when a detector module’s pedestal is off on a frame, and integration then floors the reflection’s \(\sigma\) at one photon while its net intensity, measured against the negative background, reaches thousands. Such an observation weighs a hundred times more than any real one, takes its reflection over in an unscaled merge, and every frame that sees that reflection and finds nothing there is fitted towards a scale of zero, below the floor of the per-frame scales (§10.3), and dropped. On a serial run where one module failed this way every 324th frame, always in the same residue of the frame number modulo 4, the frames of that residue lost about half of their number to the floor and those of the other residues next to none, so two halves of one run merged to CC1/2 0.28 and 0.78.

10.3 Smoothing of per-frame scales

The per-frame scales \(G_i\) are fit by robust (Cauchy) inverse-variance-weighted ratios; there is no explicit \(G\approx1\) prior. For rotation datasets, optional smoothing enforces the expectation that scale and mosaicity vary slowly across a sweep: after the per-frame fit, \(\log G_i\) (and the mosaicity) are replaced by a centred moving average over a window spanning a configurable rotation range (XDS DELPHI-like; --smooth-g, default 5° for rot3d, off otherwise). It is a post-fit smoothing pass, not a curvature penalty inside the least-squares objective. (The per-frame scale refitted on the combined fulls, §10.6, is smoothed differently: by a penalised smoother whose smoothness is chosen by cross-validation.)

The crystal orientation is smoothed the same way, and for the same reason. Geometry is re-refined independently on every frame against that frame’s spots alone — as few as a dozen on a sparse crystal — so the per-frame orientation carries a real slow drift (crystal slippage, up to ~1.3° across a sweep) on top of fit noise that scales with spots per frame. Before scaling, the per-frame lattices are de-rotated to a common reference, averaged in frame order, rotated back, and every partial’s \(\Delta\phi\) — hence its partiality — is recomputed from the smoothed lattice. The window is chosen per dataset by leave-one-out cross-validation (does a frame’s neighbours predict its orientation?) rather than fixed, because drift and noise both vary by two orders of magnitude between crystals; it is capped, because the per-frame fit also absorbs a real per-frame systematic that smoothing too wide destroys. Only frames that actually indexed take part: a frame that did not carries an all-zero lattice, which is finite and so passes a validity check written as a finite test, and would otherwise be both averaged into its neighbours’ orientation and scored in the cross-validation that picks the window. Refining less is not an alternative: with per-image refinement off the space group is lost on several crystals.

A per-frame scale enters every intensity as \(1/G\), so a frame whose fit is not determined by its data can amplify it without bound — and \(\sigma\) is amplified by the same factor, which makes it invisible to any \(\sigma\)-based outlier test. A fitted \(G\) far below the run’s median is therefore treated as undetermined rather than as a successful fit, both here and in the separate refit on the combined fulls (§10.6). The bound is a ratio to the run’s own median because \(G\) is not gauge-fixed: it and the merged means have an exact global multiplicative degeneracy, so no absolute value is meaningful.

10.4 Merging estimator

After refinement, corrected observations are formed: \( I^{\mathrm{corr}}_{ij} = \frac{I^{\mathrm{obs}}_{ij}}{G_i L_{ij} P_{ij}},\qquad \sigma^{\mathrm{corr}}_{ij} = \frac{\sigma^{\mathrm{obs}}_{ij}}{G_i L_{ij} P_{ij}}. \)

Unique intensities are merged by inverse-variance weighted mean: \( I_h = \frac{\sum_j w_j I^{\mathrm{corr}}_{ij}}{\sum_j w_j},\qquad w_j = \frac{1}{(\sigma^{\mathrm{corr}}_{ij})^2}. \)

The weights use an expected variance: the Poisson signal part of each \(\sigma^{\mathrm{corr}}_{ij}\) is rebuilt at the reflection’s merged \(\langle I\rangle\) rather than at that observation’s own intensity. Weighting by an observation’s own \(\sigma^2\) biases the inverse-variance mean low below about one photon, because an up-fluctuated observation gets a larger sigma and is then down-weighted too hard. The rotation combine already does this; for stills it is on by default, and --no-expected-variance-merge restores the observed-sigma weighting.

An internal-consistency term can inflate uncertainties when multiple observations are present, in the spirit of XSCALE.

Outlier rejection. Before merging, an observation farther than \(N\sigma\) from its reflection’s median is rejected (--reject-outliers; default 6 on rotation data and 10 on stills, whose partials scatter with heavier tails; 0 turns it off).

Several sweeps. Rotation sweeps given together are one dataset by default (--sweeps joint): each is scaled on its own, the sweeps are put on the axes of a reference sweep (the one reaching the finest resolution among those with a measured ISa, ties broken by the higher ISa) and merged in two levels, as XSCALE merges separately scaled inputs; --sweeps separate processes each alone. See RUGNUX_CLI.

10.5 Merging statistics

The shells are nine bins of equal width in \(1/d^2\), laid between the whole sphere (\(1/d^2 = 0\); the low-resolution limit --scaling-low-resolution bounds only the scale fit, so the coarsest reflections are merged too, and those the beam stop hides count as missing) or the declared range of --report-resolution, and the highest-resolution reflection the merge actually kept — XDS’s rule and XDS’s count, so at the same resolution limits the two programs’ tables have the same shell boundaries and can be read row for row. --resolution-shells changes the count; the binning rule does not change with it.

Per-shell and overall merging statistics are computed on corrected intensities, including:

  • number of observations and of unique reflections, and multiplicity,

  • mean \(I/\sigma(I)\),

  • \(R_\mathrm{meas}\) (the redundancy-independent Diederichs–Karplus form) from within‑HKL deviations,

  • \(\mathrm{CC}_{1/2}\), correlating two half-sets of equal size: an observation’s half is the parity of its rank among its own reflection’s observations, ordered by a key built from the raw Miller index and the peak frame. Every reflection measured more than once therefore contributes (a hash of the image alone leaves \(2^{1-n}\) of the multiplicity-\(n\) reflections entirely in one half, with no second mean to correlate), and because a rank is a property of the set rather than of the order it is walked in, a CUDA build and a JFJOCH_USE_CUDA=OFF build report the same \(\mathrm{CC}_{1/2}\) and the same \(\mathrm{CC}_\mathrm{anom}\). It is the split cctbx’s compute_cc_one_half — and phenix.merging_statistics through it — uses. The stills path balances its halves sequentially instead, in image order. When a reference dataset is supplied, \(\mathrm{CC}_\mathrm{ref}\) is reported beside it,

  • completeness against the reflections the cell and symmetry can give over that same declared range, so low-resolution terms lost to the beam stop, to a detector mask or to the low-resolution limit itself count as missing instead of leaving the denominator along with the data,

  • the anomalous signal-to-noise \(\mathrm{SigAno}\) and the half-set anomalous correlation \(\mathrm{CC}_\mathrm{anom}\) (below).

The error model is refined as \(\sigma_\mathrm{corr}^2 = a\,\sigma^2 + (b\,\langle I\rangle)^2\), with \(a\) set by the scatter of weak (counting-limited) reflections and \(b\) the intensity-proportional systematic scatter of the strong ones. On the rotation path, ISa is the asymptotic (\(I\to\infty\)) signal-to-noise — by definition the reproducibility limit of the strongest reflections (Diederichs, Acta Cryst. D66 (2010) 733) — and is read directly from the strong symmetry equivalents as the counting-subtracted fractional scatter of well-measured reflection groups (a robust median over strong groups; the \(I/\sigma\) threshold is relaxed on weak or radiation-damaged data that has few strong reflections), rather than as \(1/b\) of the whole-range fit, whose \(b\) is raised slightly by an intermediate-intensity excess and so understates the limit. The asymptotic value is report-only — nothing downstream reads it, and the merged \(\sigma\) is not floored at \(b|I|\) (that floor was removed). The per-observation \(\sigma_\mathrm{corr}\) (the merge weights) uses the whole-range \(a,b\). The stills path adds a partiality term, \(\sigma_\mathrm{corr}^2 = a\,\sigma^2 + (b\,\langle I\rangle)^2 + c^2\left(\frac{1-p}{p}\right)^2\langle I\rangle^2\), and reports no ISa: there \(1/b\) is the \(I/\sigma\) ceiling of one fully recorded still under the stills model - the same frames processed as a rotation sweep read several times higher - which describes the processing model more than the instrument and the crystal. It reports \(a\), \(b\) and \(c\) instead (ERROR_MODEL_A/B/C, _reflns.jfjoch_error_model_a/b/c); \(1/b\) is still used inside, by the space-group search.

\(a\) and \(b\) are reported in XDS’s convention, which is \(\sigma^2 = a(\sigma_0^2 + b I^2)\) with \(\mathrm{ISa}=1/\sqrt{ab}\), so the printed pair can be read straight against a CORRECT.LP. The internal fit keeps the form above; only the report converts, as \(b_\mathrm{XDS} = b^2/a\) (and on stills \(c_\mathrm{XDS} = c^2/a\)). Note that \(a\) is the same in both conventions and that the two ISa expressions are the same number, \(1/\sqrt{a\cdot b^2/a} = 1/b\) — so the rotation log prints two ISa, the whole-range \(1/b\) (XDS’s meaning) and the strong-reflection asymptote beside it, which can only ever be the more optimistic of the two. The mmCIF follows the same split: _reflns.jfjoch_diffrn_ISa is the whole-range value, directly comparable with a CORRECT.LP, and the asymptote is written separately as _reflns.jfjoch_diffrn_ISa_asymptotic, with _reflns.jfjoch_error_model_a and _b alongside so the number can be re-derived. Note that a file written before this change carries the asymptote under the plain ISa name. A third, unrelated \(b\) appears in the space-group search (§13.1); it is fitted with the \(\sigma^2\) coefficient held at 1 and its gate constants are calibrated in that convention.

Anomalous signal-to-noise (SigAno). The strength of the anomalous signal is reported per shell and overall as \(\mathrm{SigAno}=\langle|\Delta I|\rangle / \langle\sigma(\Delta I)\rangle\), where \(\Delta I = I(+)-I(-)\) over acentric reflections measured in both Bijvoet hands and \(\sigma(\Delta I)=\sqrt{\sigma_+^2+\sigma_-^2}\). It is computed from the full-multiplicity inverse-variance \(I(+)/I(-)\) split (the same one written to the output), i.e. from all observations rather than a half-set. For pure noise \(\mathrm{SigAno}\) approaches the half-normal value \(\sqrt{2/\pi}\approx0.8\), and it rises above \(1\) once a real anomalous difference is present. A half-set anomalous correlation (\(\mathrm{CC}_\mathrm{anom}\)) is reported beside it: \(\Delta I\) is formed once per half-set and the two are correlated over the acentric pairs where both hands split into two non-empty halves, per shell and overall as one correlation rather than a mean of shells. Unlike SigAno it is not a ratio against the error model, so an optimistic \(\sigma\) cannot inflate it. It has no floor either: subtracting the two Bijvoet hands cancels the large common intensity that keeps \(\mathrm{CC}_{1/2}\) non-negative, so on data with little anomalous signal and about two observations per mate it goes strongly negative. That is a property of the statistic and is reported as measured. It agrees with AIMLESS’s CCanom and phenix.merging_statistics’ cc_anom; XDS’s Anomal Corr is a different quantity and is not comparable with it — on the same observations it reads two to three times higher in the low shells. It also reads negative on strong data whose Bijvoet mates are recorded together (a symmetry axis along the spindle puts the mirror spot of the opposite hand on the same image): the error the two mates share is dealt to opposite halves half of the time and enters the two differences with opposite signs, so it is quoted with its number of pairs (CC_ANOM_PAIRS=) and never decided on. Beside it, measurability (Zwart (2005) Acta Cryst. D61, 1437–1448; phenix.xtriage) is the fraction of the acentric pairs measured in both hands with \(|\Delta I| \ge 3\sigma(\Delta I)\) and \(I \ge 3\sigma\) in each hand, per shell and overall (ANOM_MEASURABILITY=). \(\mathrm{CC}_\mathrm{anom}\) is a rotation-path statistic (the stills merge forms no half-set anomalous difference), and it is reported in the CCanom column of the printed merge-statistics table and as CC_ANOM= in the results report — not in the mmCIF. SigAno is emitted only when an anomalous split was made, using the standard PDBx items _reflns.pdbx_absDiff_over_sigma_anomalous (overall) and _reflns_shell.pdbx_absDiff_over_sigma_anomalous (per shell), and appears as the SigAno column of the same table. Where either could not be measured at all — a Friedel-merged run that split no Bijvoet pair, a shell too thin to split one in both hands — the table prints - and the results report writes no key, which is not the same statement as a value measured to be zero.

10.6 Rotation datasets: combining partials into fulls (3D integration)

In a rotation scan a reflection is recorded as a series of partials spread across the frames its rocking curve crosses. Merging those partials directly would force the merge error model to absorb the rocking-curve slicing as if it were measurement noise, capping the achievable \(I/\sigma\). For rotation data Jungfraujoch instead combines each reflection’s partials into a single full intensity first, then scales and merges the fulls — a 3D integration over the rocking curve.

The combine groups each reflection’s partials into rocking events (contiguous runs of frames) and reduces each event to one full:

  • De-biased weighted sum. Partials are combined by inverse-variance weighting, where each partial’s variance is its background-noise component plus the model signal shared across the event (Kabsch profile-fit form). Using the shared model signal rather than the individual down-fluctuating intensity stops weak partials from being over-weighted, which would otherwise inflate the merged error model. The weights depend on the full, so the estimate is iterated.

  • Captured fraction. The partiality summed over the event, \(f=\min(1,\sum_j p_j)\), measures how completely the rocking curve was sampled. A full whose curve was captured below a threshold (--min-captured-fraction, default 0.7 for rotation) is dropped — an event seen over only a small fraction of its curve is unreliable however many frames it spans. (The per-partial minimum-partiality cut of §10.2 still applies upstream, in the per-frame scaling.)

  • Per-image rejection (opt-in). A frame whose observations correlate poorly with the merged reference is not measuring the crystal being merged — it may be off-crystal, or on a different crystal where two lattices occupy separate regions of the sample. --min-image-cc drops such frames. It has no default: the per-frame correlation measures data quality as much as frame validity, and its typical level varies widely between datasets, so no single absolute bound is generally valid.

  • Capture-aware uncertainty. A full captured incompletely (\(f<1\)) is extrapolated and biased high. The unobserved fraction is charged as an extra systematic uncertainty, \(\sigma^2 \leftarrow \sigma^2 + \big(c\,(1-f)\,I\big)^2\), so the merge down-weights these extrapolated fulls and the error model treats their scatter as expected. The merge rebuilds every full’s variance at the reflection’s mean intensity (§10.4), and the capture term is rebuilt there too, as \(\big(c\,(1-f)\,\langle I\rangle\big)^2\). It is enabled by default for the rotation path.

  • Overloaded events. An event in which any partial had a saturated pixel in its signal disk — or a pixel unreadable on that frame alone, beyond the run’s pixel mask, which is how a detector that writes its error value for a pixel it could not count reports an overload — is dropped whole, as XDS drops an overloaded reflection. The brightest part of such a rocking curve is exactly what is missing, so neither the sum of the remaining partials nor their extrapolation by the partiality model measures the reflection: on a strongly diffracting small-molecule crystal these were the strongest low-order reflections, and they read 2–3× low. The integration keeps an overloaded partial, unfitted and flagged, only so that the event can be recognised; nothing else reads it. The count is OBSERVATIONS_REJECTED_OVERLOAD= in the report.

The fulls are then re-scaled in the XDS sense — a per-image scale refit directly on the complete reflections under the unity partiality model — and merged (§10.4).

Before the combine a per-frame scale can also be fitted on the partials themselves. That needs a frame to hold many rocking events caught at different points of their curves: within one rocking curve a change of scale and an error of the partiality model are the same thing, and on a finely sliced sparse sweep the fit takes one for the other. The rocking events per frame are the prior (the partials are scaled from 50 events per frame), but the counts of small-molecule sweeps (3–43) and proteins (5–900) overlap. So the first merge of a run that is not a space-group search can be made both ways, with the partials scaled and with the scale taken from the fulls alone, and the prior stands unless its merge has no resolved error model (\(b\) not resolved from zero: the strong equivalents do not agree to within a measurable systematic error) while the other merge has one. Where the prior is to scale the partials and that merge resolves its error model, the other cannot change the choice and is not made. The two ISa values are deliberately not compared beyond that: the partiality-model error a partial scale takes up is shared by symmetry mates measured at the same rocking geometry, so their agreement cannot see it — a small-molecule sweep with six events per frame read ISa 10.5 with its partials scaled against 8.7 from the fulls alone, and refined to \(R_1\) 0.105 against 0.062. The log states the choice and the ISa of every arm that was made. Because every merged observation is now a counting-statistics-limited full rather than a partiality-divided slice, the error model reaches a far higher asymptotic \(I/\sigma\).

How smooth that scale is over the rotation is left to the data rather than to a fixed window. Each round fits every frame on its own fulls against the current reference, giving a scale \(G_f\) and its information \(D_f=\sum w^2c^2\); the scale is then the curve \(x=\log G\) minimising \(\sum_f J_f\,(x_f-y_f)^2+\lambda\sum_f(\Delta^2 x)_f^2\), with \(y_f\) the frame’s own fit in log scale and \(J_f\) its information carried there — a penalised (Whittaker–Eilers) smoother, solved as a five-band linear system. \(\lambda\) is chosen by cross-validation: blocks of frames one rocking curve wide are left out in turn and predicted from the curve through the rest (neighbours closer than a rocking curve share their measurement, since a full sums those frames). A frame of hundreds of fulls is then followed frame by frame, a frame of two or three is carried by its neighbours, a stretch with none is bridged by a straight line, and a scale that falls a hundredfold over a few degrees — an absorbing crystal turning edge-on — is followed where a window would average across it. Once the curve settles, one free fit is shrunk toward it frame by frame by how much of each frame’s deviation its neighbour shares (the lag-1 covariance), which hands back a real per-frame systematic and discards fit noise.

Both per-frame scaling loops — on the partials and on the fulls — alternate between the references given the scales and the scales given the references, and converge linearly: a round typically removes only 5–15% of the remaining step, and 2% on the slowest sweeps. Each round is therefore Anderson-accelerated in \(\log G\) (type II, five rounds of history, each frame weighted by its observation count): the plain round’s scales are corrected by the combination of the last rounds’ steps that best cancels the current one, and the history is dropped whenever the set of fitted frames changes. Acceleration starts only once the plain step has fallen below \(10^{-2}\), and stops for the rest of the loop the first time the step grows: Anderson mixing models a map near its fixed point, and a loop further out, or one whose step grows, may be walking rather than converging - accelerated, it walks faster and ends somewhere else. This changes the path, not the fixed point. With it the loops are run to an rms step of \(10^{-5}\) in \(\log G\) - in fewer rounds than a plain loop took to \(10^{-3}\) - so the merge no longer depends on where a loop happened to stop.

After scale-fulls, five correction surfaces are fitted on the combined fulls (rotation path, on by default; disable all with --no-scaling-corrections), each an alternating multiplicative refinement of the per-full scale against the merged reference:

  • Decay. Radiation damage weakens later frames more at higher resolution — a resolution×time (Debye–Waller) systematic the resolution-flat per-image scale cannot capture. A single global relative-\(B\) rate is fitted, \(\ln(I_\mathrm{ref}/I_\mathrm{obs}) = 2\,(\mathrm{d}B/\mathrm{d}n)\,(n-\bar n)\,s^2\) (frame \(n\), \(s^2 = 1/4d^2\)), and folded into the scale. It engages only when the total relative-\(B\) over the run exceeds a physical floor (2 Ų); below that the decay is negligible and “correcting” it only spreads symmetry equivalents (same \(s^2\), different frames). An optional per-batch relative-\(B\) (--relative-b[=deg], off unless requested; 10°-of-rotation batches by default) extends the single global rate to a smooth \(B(n)\) curve — the same \(s^2\)-weighted decay fit solved independently over short frame batches, curvature-penalized so it cannot over-fit and cross-validated like the surfaces below — for crystals whose decay is non-linear in dose. Its cross-validation splits on ASU-group parity, not the frame parity the surfaces below use: a per-batch parameter owns whole frames and so cannot be scored on a held-out frame, whereas splitting the symmetry equivalents tests whether a batch’s \(B\) generalises to reflections it was not fitted on.

  • Absorption. A smooth multiplicative factor over the diffracted-beam direction expressed in the goniometer (crystal) frame: each full’s predicted detector position gives the lab diffracted direction, de-rotated by the spindle so a fixed crystal-frame direction is sampled at many rotation angles and its grid cell is well-determined. Negligible at hard X-rays / thin crystals; it matters at low photon energy.

  • Modulation (detector-plane flat-field). A smooth multiplicative factor over where each reflection lands on the detector (predicted \(x,y\)): symmetry-equivalents land at different positions as the crystal rotates, over-determining the surface. It absorbs detector-response and geometric systematics that inflate \(R_\mathrm{meas}\).

  • Absorption as spherical harmonics. The same crystal-frame absorption as a smooth function instead of a grid: the logarithm of the factor is a sum of real spherical harmonics of the de-rotated diffracted-beam direction, degrees 1 to 6 (48 terms; the incident-beam path depends on the rotation angle alone and is part of the per-image scale). It is fitted through 32 × 64 equal-solid-angle direction cells, one ridge-regularised least-squares step on the coefficients per round, with a prior of width 0.1/l on each degree-l coefficient. It is a candidate like the others and passes the same held-out test; the grid is then tested on what it left.

  • Time-dependent absorption. The same surface as Absorption, but over (rotation angle × detector position) instead of the crystal-frame direction alone. The two agree while the illuminated volume stays put — the incident path then depends only on the spindle angle, which the per-image scale already takes, and the exit path is fixed in the crystal frame. Once the diffracting volume drifts through the beam the exit path becomes a function of the spindle angle as well, and nothing time-independent describes it. Fitted on one rotation bin per 10° (at least 12) × a 10×10 equal-occupancy detector grid.

The surfaces overlap, so the order decides what is adopted: modulation first (every frame measures the static detector pattern, so its fine grid is the best determined), then time-dependent absorption, then the spherical-harmonic absorption, then the goniometer-frame grid, whose cells collect directions from the whole sweep and the whole resolution range and which, fitted first, takes up part of what the other two describe.

Each cell’s factor is fitted under a prior pull to 1 (a Gaussian prior of width 0.1 on its logarithm): a cell moves off 1 in proportion to the information its observations carry, so a cell with little signal stays near 1 instead of being fitted to its noise. Negative observations enter the fit as measured. On the detector-plane surfaces (modulation, time-dependent absorption) the component that is a function of resolution alone is projected out within resolution shells, since the symmetry equivalents of a reflection share one resolution and such a factor cannot be determined from them.

Each surface is cross-validated on the half-set agreement it is meant to improve: fitted on even-numbered frames and used to merge the odd ones, fitted on the odd frames and used to merge the even ones, and kept only if the correlation between the two half-set means, taken within resolution shells, rises above the same two halves merged with no surface. A shell is read only where it holds at least 50 reflection groups; on a small cell adjacent shells are pooled until each bin does, so a merge of a few hundred unique reflections is still judged. Each half is corrected by a surface it did not help to fit, so a surface fitted to noise lowers the correlation, and a correlation within a shell is blind to the resolution-dependent scale the surface cannot determine. The change is averaged over the shells on Fisher’s \(z = \operatorname{atanh}(CC)\), not on \(CC\): the strong shells, where a multiplicative error matters, sit at \(CC_{1/2} \approx 0.999\), where even a large reduction of the error moves \(CC\) in the fourth decimal, and averaged on \(CC\) itself the shells of pure noise beyond the reach of the data decide the sign.

Radiation-damage report (rotation, report-only). Independently of whether any decay correction is applied, Rugnux measures and reports the relative Debye–Waller \(B\) across the sweep: the per-image scale’s correlation to the merge and the per-image mosaicity versus frame (dose), together with a per-batch relative-\(B\) curve whose first→last change is a single headline number (measured before any decay correction, against the least-damaged early wedge). It is written to the log and to the merged mmCIF as a data-quality-vs-dose diagnostic and never alters the merged intensities — distinct from the decay correction above, which does fold into the scale.

Each batch’s \(B\) is fitted on resolution-shell means, not on single observations: \(\ln(I_\mathrm{ref}/I_\mathrm{obs})\) of one weak observation is unbounded and biased downwards — the observation appears in the response and in its own weight, and the logarithm needs \(I_\mathrm{obs} > 0\), which keeps only the upward half of the noise — and on decayed data that bias grows with dose until it reverses the sign of the answer. The shells are laid inside the range the run actually diffracted to, and the fit carries an intercept as well as a slope, so a batch that is merely dimmer than the run (an attenuated beam, a mis-fitted frame scale) is not reported as damage. A batch whose shells are too weak to fit, or whose solved value reaches the bound the smoothing solve clamps to, is reported as absent rather than as a number. The first→last headline is reported only where a straight line describes the curve: radiation damage is progressive, so a curve that dips and recovers is a disturbance rather than dose, and is left to the sweep-quality report (the results report) to name.

Frame disposition (rotation). After the correction surfaces are fitted, and on the corrected fulls, Rugnux measures ΔCC1/2 — the overall CC1/2 of the merged data with a group of images minus the CC1/2 without it, over the reflections that group touches — for each 10° batch of the sweep and for each stretch the sweep-quality diagnostic flagged. It is computed in the σ-τ form (no random half-dataset split, so the answer is the same every run), with each observation carrying the information \(\min(1, (G/G_\mathrm{ref})^2)\) of its frame’s scale against the typical one — the internal weighting of the automatic resolution cut (decisions §13.4), not part of the reported \(\mathrm{CC}_{1/2}\) — and with each reflection’s error variance taken from the observed scatter of its own observations rather than from the error model’s σ’s: a bad stretch claims the same σ’s as a good one, so an error-model estimate would read a batch that adds noise as a batch that adds precision, inverting the sign of the measurement. The leave-one-out is a subtraction of the group’s own \((n, \sum I, \sum I^2)\) from the per-reflection totals, so measuring a group costs one pass over its observations rather than a re-merge, and reflections the group holds the only observations of are excluded from both sides — the published statistic’s own restriction. Its standard error is reported beside it as that of a single CC1/2 on the same reflection count, \((1-CC^2)/\sqrt{n_\mathrm{refl}-3}\), and a ΔCC1/2 smaller than that says nothing; a group whose ΔCC1/2 is positive or near zero is not evidence of harm. A batch is removed only where its ΔCC1/2 is both several standard errors below zero (Fisher-transformed) and well below the run’s own per-batch distribution (median − 3 robust σ, measured once before anything is removed), and where the per-image CC to the merge — an independent channel, measured on the partials one frame at a time — also says the stretch agrees with the run worse than a typical frame does, because selecting frames by their disagreement with the merge and then reporting that the merge improved is circular; its edges are then slid frame by frame with the whole stretch re-measured at each position — so the range is located finely while the count of reflections the verdict rests on stays that of the stretch — the worst range is removed, the reference is re-formed and the scan repeats, never past a quarter of the sweep and never over a stretch narrower than one rocking event. The resulting per-frame merged / downgraded / rejected ledger is described in the results report.

10.7 R-free test-set flags

A fraction of the unique reflections (rfree_fraction, default 0.05) is flagged as a free (test) set, written to the output (MTZ FreeR_flag, mmCIF _refln.status = f, a text-HKL column) for model validation (§14) and for downstream refinement. The flag is a pure function of the reflection’s orbit under the lattice holohedry — the point group of the cell’s metric, found as twin laws are (Le Page two-folds within 3° obliquity, taking the lattice of the cell’s own basis vectors), which contains the merging group — together with its Friedel mate. Where the cell does not carry the merging group (a space group forced on a metric without it), the Friedel-merged (Laue) ASU index of the merging group is used instead. That gives four properties:

  • all symmetry- and Friedel-equivalent reflections share one flag — in particular a Bijvoet pair \(I(+)/I(-)\), kept as two separate merged rows in anomalous mode, is never split across the work and free sets (which would bias R-free);

  • twin-law mates share one flag too, since a twin law is a lattice symmetry the crystal lacks. Keyed on the merging group instead, nearly every free reflection’s twin mate lands in the working set, and in twin refinement the free reflection’s calculated intensity then carries the working-set fit. The same set is what phenix.refine generates by default (use_lattice_symmetry). It also makes the free set independent of the space group a file is merged in: the merged file and a re-merge in any subgroup, P1 included, carry one free set (nested, where the small-data floor below lifts the fraction of one of them more than another’s);

  • the free/work decision is a deterministic hash of that key, so the same reflection always lands in the same set — reproducible run-to-run and independent of the order in which observations were merged;

  • the hash depends only on the reflection index, not on this dataset’s resolution range or which reflections it happens to contain, so a uniform draw takes ~rfree_fraction of the distinct reflections free and — crucially — every dataset of one crystal form gets the same free set. That cross-dataset consistency is what a multi-dataset campaign (ensemble refinement, PanDDA) requires; a per-shell stratification tied to each dataset’s own \(d_\mathrm{min}\) would break it.

On small data, where rfree_fraction (default 0.05) would give too few test reflections for a statistically stable R-free (Brünger’s ~500–2000 rule), the fraction is floored so at least ~500 distinct reflections are free — capped at 10 % so a large test set never steals working data. For ordinary data this floor is inactive and the fraction stays flat at rfree_fraction, preserving the cross-dataset-identical property above; it only lifts the fraction on genuinely small datasets, where per-dataset R-free stability outweighs cross-dataset identity (and a shared reference set is the way to keep exact identity there).

When a reference (--reference: an MTZ, or a PDB structure-factor mmCIF, which is converted to one with _refln.status f/o becoming flag 0/1) carries a FreeR_flag column, its test set is imported instead: every merged reflection whose Laue-ASU index matches the reference takes the reference’s flag (reflections absent from the reference keep the hash flag). The match is made in the reference’s frame — on rotation data the merge is first put onto the reference’s axes, choosing among every description of the lattice on them (and every alternative indexing) by the intensity correlation with the reference — and only where the merge then matches it: an intensity CC of at least 0.5 over at least half of the merged reflections in the reference’s resolution range. Below that the reference is not the same crystal form on the same axes, its flags would land on unrelated reflections, and they are not imported (REFERENCE_MISMATCH). This lets a whole fragment-screening campaign inherit one shared free set from the apo/reference dataset. The CCP4/refmac convention (test set = flag 0, including the historical 0–19 form) is assumed, with the complement taken automatically if flag 0 would be the majority (a phenix-style file where 1 marks free).

10.8 French–Wilson amplitudes

The last step of the merge estimates a Bayesian structure-factor amplitude \(|F|\) for each unique reflection from its intensity \(I\) and error \(\sigma\), so the output carries amplitudes alongside intensities (a naïve \(\sqrt{\max(I,0)}\) turns every weak or negative measurement into a biased — or zero — amplitude). With the Wilson prior for the true intensity \(J\ge 0\) at that resolution,

\( P_\mathrm{acentric}(J) \propto e^{-J/\Sigma},\qquad P_\mathrm{centric}(J) \propto J^{-1/2}\,e^{-J/2\Sigma}, \)

and a Gaussian likelihood \(\mathcal{N}(I;J,\sigma^2)\), the posterior mean amplitude and its uncertainty are

\( \langle |F|\rangle = \frac{\int_0^\infty \sqrt{J}\,\mathcal{N}(I;J,\sigma^2)\,P(J)\,\mathrm{d}J}{\int_0^\infty \mathcal{N}(I;J,\sigma^2)\,P(J)\,\mathrm{d}J},\qquad \sigma_F = \sqrt{\langle J\rangle - \langle|F|\rangle^2}. \)

The prior mean is \(\Sigma = \varepsilon\,K_\mathrm{shell}\,a(\mathbf{h})\), where \(\varepsilon\) is the reflection’s epsilon (symmetry-enhancement) multiplicity, \(a(\mathbf{h}) = \exp(-\tfrac12\mathbf{s}^\mathsf{T}B\,\mathbf{s})\) carries the deviatoric anisotropy tensor \(B\) of §13.5 along the reflection’s own direction, and \(K_\mathrm{shell} = \sum I/\varepsilon \,/ \sum a\) over its resolution shell, so the priors of a shell still average to its measured Wilson mean. The amplitudes are first made with \(a = 1\) at the end of the merge and made again once the tensor has been fitted; only \(F\)/\(\sigma_F\) change, never an intensity. With an isotropic prior the weak direction of an anisotropic crystal gets a prior set mostly by the strong direction, which turns its noise into amplitude; for isotropic data the tensor is near zero and the prior reduces to the shell mean, so it is used whenever a tensor was fitted. A shell whose \(K\) is not positive takes that of the nearest lower-resolution shell. As in ctruncate, an intensity more than 3.7σ below zero gets no amplitude (the intensity is kept) and does not enter the shell mean. Strong reflections (\(I>20\sigma\)) short-circuit to \(|F|=\sqrt{I}\), where the French–Wilson bias is below 0.3%; a reflection with an unusable \(I/\sigma\) falls back to \(\sqrt{\max(I,0)}\). The integral is evaluated numerically with a log-shift for stability.

Amplitudes are written as MTZ F/SIGF (and F(+)/F(-)) and mmCIF _refln.F_meas_au/F_meas_sigma_au, alongside the intensity columns; the SHELX .hkl holds intensities only. The same \(|F|\) feed the model-validation step (§14), so the reflection file and the maps use one consistent set of amplitudes.

10.9 Reference data: fixing the space group and resolving the indexing ambiguity

A reference dataset (--reference, MTZ or SF-mmCIF) supplies known intensities for the same crystal form, and is used in two ways.

Fix the space group and cell. Unless overridden on the command line (-S for the space group, -C for the cell), the reference’s space group is adopted and its cell is used as the soft reference cell — indexing may still drift the cell within tolerance, so a small mismatch between reference and data is absorbed rather than rejected. This applies to both stills and rotation data.

Resolve the indexing (merohedral) ambiguity. When the lattice symmetry is higher than the crystal’s Laue symmetry (e.g. \(P3\), \(P4\), \(P6\), \(C2\)), more than one indexing of the same lattice is geometrically valid, and the two solutions produce different merged intensities that a self-consistent scale cannot tell apart — which of them is the reference’s own, only an external reference can say. The candidate reindexings are the identity together with the twin-law cosets of the metric symmetry (from the unit-cell metric and the Laue group); each is scored by the intensity correlation \(\mathrm{CC}_\mathrm{ref}\) of the reindexed merge against the reference, and the data are re-merged in the best-correlating indexing. The reindex is metric-preserving — only the \(hkl\) labels change, the cell is unchanged — and it is a no-op for a holohedral crystal, which has no twin laws (the lattice and Laue symmetry coincide). For rotation data this is done once, after the space group is determined, and the whole merge is then repeated in the chosen indexing. For stills, where each crystal is indexed independently and a merge of mixed indexings would average reflections that are not symmetry mates, it is decided per crystal: at integration time each image is put into the indexing whose partiality/Lorentz-corrected intensities correlate best with the reference (scale-invariant), and before the merge that correlation is weighed, crystal by crystal, beside the crystal’s agreement with all the others and its own cell, as described below. In neither workflow is the reference a scale target: both scale against their own data (§10.2), so \(\mathrm{ISa}\) and the merging statistics come from the data alone and no cross-dataset systematic is imported. A re-merge of stored reflections (--mode scale) makes the same choice, with or without a reference. Where there is no reference dataset but there is a model (--model), the reference intensities are computed from it instead - \(|F_\mathrm{model}|^2\) from the atomic structure factors with a flat bulk-solvent contribution at the standard constants (\(k_\mathrm{sol}=0.35\), \(B_\mathrm{sol}=46\) Å\(^2\)), which are not fitted because there are no observations yet. Nothing is scaled against them; they serve only to rank the candidate indexings, and the correlation that does the ranking is scale-invariant. This needs the cell and space group up front (-C / -S, as serial indexing wants anyway); on rotation data the same job is done after the merge, in §14.5, where a merge exists to fit the model to properly.

Serial stills without a reference or model. The data cannot say which indexing is the true one, but they can say which crystals are in the same one, and that is all a merge needs. Where the space group is fixed (-S) and its lattice admits alternative indexings, the crystals are made consistent with each other before anything is scaled, following Brehm & Diederichs (2014). Each crystal is compared on the square roots of its partiality- and Lorentz-corrected intensities, the sign kept: intensities follow the Wilson distribution, whose long tail lets a few very strong reflections dominate every product of two crystals, so that the strongest crystals settle among themselves and a group of them can hold one another in the wrong indexing against the weaker majority (on a large-cell serial run this left a fifth of the crystals in the wrong indexing); amplitudes have no such tail. They are put on the run’s mean and spread in their resolution shell (20 shells of equal reciprocal volume; a shell past the resolution the run reaches holds only noise and may have a mean of zero or below, so it is not divided by its mean), standardised within the crystal so that its unknown scale and offset drop out, and weighted by \(1/(1+(\sigma/s)^2)\), \(s\) being the crystal’s spread, so that a weak or barely recorded reflection counts for little. The agreement of two crystals is the sum of the products of these values over the reflections they share, and the objective is that agreement summed over every pair of crystals, each in the indexing assigned to it. That sum is \((|M|^2 - \mathrm{const})/2\) with \(M\) the per-reflection sum over all crystals, so a crystal’s agreement with all the others is one dot product with \(M\) less its own contribution: each crystal in turn takes the indexing in which that dot product is largest, \(M\) is updated, and the passes repeat until no more than one crystal in a thousand moves. A pass costs one read of the reflections, not one per pair of crystals, which is what keeps tens of thousands of crystals to seconds. The objective only grows, so it converges; it is started four times (once from the indexing as found, three times from a seeded random assignment) and the start that ends highest is kept, and of the equally consistent answers related by an overall relabelling the one the crystals’ cells favour together is taken (below) - where they say nothing, the one that moves the fewest crystals. The order of every floating-point sum is fixed (crystals in image order, sequential passes), so the result does not depend on the thread count. The run reports how clearly the crystals separated: for each crystal the correlation with the mean of all the others in its chosen indexing and in the best other one, compared by Fisher’s \(z\) in units of its standard error (\(\sqrt{2/(n-3)}\) for \(n\) shared reflections) — the median of that margin and the share of crystals above \(3\sigma\).

A twin law is only partly an ambiguity where the lattice is pseudo-merohedral: a crystal’s refined cell then also says something about which axis is which - but only as far as the run’s cell differs under the law by more than one crystal’s cell scatters, and a cell refined in the indexing it was found in carries a trace of that indexing whatever the truth (a cell refined under the monoclinic constraint keeps its right angles where the indexing put them, and the convention of an obtuse \(\beta\) is taken after indexing). Measured on a P2\(_1\) run with two axes 0.2% apart, a former rule that let the cells decide a law once 90% of them fitted better as indexed locked 95% of the crystals in the indexing they had been found in at random: every cell fitted better as indexed, by construction. So the cells are read as evidence of the same kind as the intensities - a log-likelihood of each indexing, added to the intensities’ for each crystal, never a lock. A crystal truly in indexing \(g\) has, as indexed, the run’s cell after the inverse of \(g\). Its cell is compared with that prediction by shape: the logarithm of each length less their mean (the operators keep the volume; the size carries the distance and wavelength errors, which move all axes together) and each angle’s distance from 90° (the obtuse convention cannot then carry the indexing); an angle the crystal’s refinement held at 90° or 120° was not measured and is left out, and a cell several crystals share to the last digit is the prior the refinement did not move, which says nothing. The scatter of each of these six quantities about the prediction is fitted on the run itself, by expectation-maximisation over the indexings, each equally likely - so a law is told apart by the cells exactly as far as their scatter allows, with no tolerance to set. A crystal’s intensities enter as \((n-3)(\zeta_\mathrm{right}-\zeta_\mathrm{wrong})\,\mathrm{atanh}(\mathrm{CC}_g)\) for each indexing \(g\), \(\mathrm{CC}_g\) being its correlation on \(n\) reflections with the mean of all the other crystals (or with the reference): Fisher’s \(z\) of a correlation has a variance of \(1/(n-3)\), so with \(z\) near \(\zeta_\mathrm{right}\) in the right indexing and \(\zeta_\mathrm{wrong}\) in a wrong one the log-odds of two indexings is \((n-3)(\zeta_\mathrm{right}-\zeta_\mathrm{wrong})(z_g-z_h)\); \(\zeta_\mathrm{right}\) is the run’s median \(z\) in the chosen indexing and \(\zeta_\mathrm{wrong}\) the median of each crystal’s mean \(z\) over the other indexings (not the best of them, which on weak crystals reads as high as the right one and would weigh the intensities down to nothing). Without a reference, the intensities alone first make the crystals consistent as above, the cells choose the overall relabelling, and then each crystal in turn - taken out of the running sums, as in the sweep, so that every decision is made against the others as they stand - takes the indexing of highest summed log-likelihood against the mean of all the others, until no more than one in a thousand moves. Only an operator that keeps the merge’s symmetry-equivalent reflections together is an overall relabelling: where the crystal’s Laue group is not normal in the lattice’s (a monoclinic crystal on a pseudo-tetragonal lattice), an operator that puts the two-fold on another axis would send crystals differing by the two-fold into different indexings and scramble a consistent answer, so it is never taken as one. With a reference, each crystal’s correlation with it is a log-likelihood of the same form (its weight from the run’s own separation of the best indexing from the others against the reference), and the reference and the cells together choose the overall relabelling, so that the merge is written in the reference’s indexing; the report gives the number of crystals put into another indexing than their correlation with the reference alone would. A crystal itself is decided by its agreement with the other crystals and its cell, not by the reference: a reference - a model’s intensities most of all - reads a weak crystal less clearly than the merge of all the others, and its correlation shares the crystal’s own noise with that agreement, so the two are not independent evidence. Measured against model truth on a pseudo-tetragonal P2\(_1\) run: 93% of the crystals the model can decide in the right indexing when each was decided on a model reference, 97% with the reference weighed in crystal by crystal, 99.5% with the reference fixing the indexing as a whole. The log gives the fitted scatter, per law the median log-likelihood by which a crystal’s cell favours the indexing it came in, and the number of crystals the cells moved against their intensities.

10.10 Ice rings at the scale and merge stages

Whatever the gate of §3.3 found, every written merge is also read for ice in its own intensities: for each hexagonal-ice ring the merged reflections in the ring’s core (\(|q - q_{\mathrm{ring}}| < 0.015\) Å\(^{-1}\)) and in its flanks (out to \(0.03\) Å\(^{-1}\)) are compared with a Wilson line fitted to the off-ring reflections within \(0.15\) Å\(^{-1}\) of the ring only, as the ratio of their mean intensity to the line and that ratio’s excess in standard errors of the band’s own scatter. A span so short in resolution cancels anisotropy and the curvature of the Wilson plot, which is what a z-score of a shell against a whole-dataset Wilson curve cannot do, and on the battery that z-score (phenix.xtriage’s ice test) flagged broad features of the Wilson plot on some thirty crystals with flat radial profiles, while this one did not. The rings are then fitted together as one ring system - an additive intensity in proportion to hexagonal ice’s line strengths - twice: the cores against the line, which is the size of the bias, and the cores against their own flanks, which decides. A ring is narrower than the flank offset, so it leaves a contrast between the two whichever way the integration bent it (a ring under the spots lifts the cores; a ring in the background annulus beside them depresses the cores and lifts the flanks - both are seen on the battery), while a feature of the Wilson plot broader than a ring moves core and flanks alike and cancels. The merge is read as carrying ice where the contrast stands at 5 sigma, either sign, over at least two rings (ICE_INTENSITY_Z). Where it fires on a run whose images showed no ring, the report warns and names the shells; the rings’ reflections are not set aside after the fact.

Where the gate of §3.3 has found ice, reflections falling within \(\pm w\) in \(q = 2\pi/d\) (§1.2) of a hexagonal-ice band (\(w=0.03\) Å\(^{-1}\) offline, about the measured ring half-width) are marked. Marked reflections are excluded where a model is fitted — the per-frame scale \(G\), the per-image correlation, and the \(P1\) merge the space-group search runs on — because ice contamination is a positive bias, not extra scatter, and a least-squares scale absorbs it into \(G\) and into the error-model \(b\), where it damages every other reflection on the same frame. They are also left out of the resolution-cut fit (§13.4), which is the one consumer that reads the merged reflections rather than the observations: an ice-flagged observation marks its merged reflection, on the rotation merge’s own accumulator (host and device alike) as well as on the stills one. The stills merge keeps them in the final merge. The rotation merge decides ring by ring, because what a ring does to its reflections differs between rings and between runs: it can bias them (up on the ring, where its powder intensity is under the spot; down on the flanks, where it is in the background ring), only add scatter, or leave them alone. Deleting every band unconditionally was implemented once and removed: on a crystal whose band was harmless it removed better-than-average reflections and 6 to 8 points of completeness in the affected shell for no measurable gain. So each ring is split into its core (\(|q-q_\mathrm{ring}|<0.01\) Å\(^{-1}\)) and its two flanks (out to \(w\)), and every band is compared with the off-ring merged reflections within \(0.02\) Å\(^{-2}\) of the ring in \(1/d^2\). Both are read against a log-linear Wilson fit of the mean intensity over those off-ring reflections (the fit behind the reported Wilson \(B\); over all off-ring reflections where the window cannot be fitted), as \(t=(I-I_\mathrm{exp})/\sqrt{\sigma^2+I_\mathrm{exp}^2}\), which has unit scatter whether a reflection is signal- or noise-dominated. A band whose mean \(t\) departs from its neighbours’ by more than 3 standard errors is rejected — a bias, which no larger \(\sigma\) would remove; one whose variance of \(t\) exceeds the neighbours’ by more than 3 standard errors of the log ratio (taken from the samples’ own kurtosis: Wilson intensities are far from Gaussian) is down-weighted, its excess variance added to each reflection’s own; the rest is merged as measured. A band of fewer than 20 reflections, or a ring with fewer than 50 neighbours, is merged. The decision is applied to the merge’s accumulators, so the written reflections, the shell table and the half-set \(\mathrm{CC}\) all see the same thing, and each band’s verdict is logged and reported (ICE_RING_BAND_nn, see the results report). It complements the radial background correction (§9), which removes most of the bias at its source: on 58 rotation crystals with ice and a model, it lowered the model’s R-free against merging every band on 26 and raised it on one, by 0.003.


11. Mosaicity and “profile radius” monitoring

11.1 Profile radius (intrinsic excitation-error width)

The “profile radius” is the intrinsic angular width of a reflection — crystal mosaicity plus beam divergence — estimated from the spread of \(\Delta_\mathrm{Ewald}\) over indexed spots, \( R \approx \sqrt{\tfrac{1}{N}\sum_i \Delta_{\mathrm{Ewald},i}^2}. \) When the beam has a finite energy bandwidth, that bandwidth smears each reflection radially by \(\sigma_\mathrm{bw}\approx \mathrm{bandwidth}\cdot\lambda/2d^2\) (largest at high resolution), which also broadens the measured \(\Delta_\mathrm{Ewald}\) spread. Since prediction re-applies the bandwidth term per reflection (§8.2), this contribution is deconvolved from the estimate — \(R^2 = \langle\Delta_\mathrm{Ewald}^2\rangle - \langle\sigma_\mathrm{bw}^2\rangle\) — so that \(R\) is the intrinsic width and bandwidth is not double-counted. Still predictions use an excitation-error cutoff proportional to \(R\) where the run’s rocking curve is not measured (--simple-stills, and the sample the curve is measured on; §8.2).

11.2 Mosaicity from rotation data

For rotation data the mosaicity \(\sigma_M\) is estimated by maximum likelihood from the rocking offsets \(\tau\) of indexed spots, using the XDS reflection-fraction model \(R(\tau;\sigma_M/\zeta)\) (Kabsch 2010): each spot’s exact Bragg angle is located near its frame, \(\zeta\) (the rotation-axis Lorentz component) is computed, and \(\sigma_M\) is chosen to maximize \(\sum_i \log R(\tau_i;\sigma_M/\zeta_i)\).

The \(\phi\) search window for the Bragg angle is set wider than the oscillation, so that reflections recorded at large rocking offset are included. These tail reflections carry most of the information about the mosaic width; a window limited to the oscillation range would truncate the \(\tau\) distribution and bias \(\sigma_M\) low.

The fit uses only the strongest 250 spots of an image, whatever the indexing spot budget (--max-spots) is. A spot is detected when \(I_\mathrm{full}R(\tau)\) clears the finder threshold, so selecting spots by intensity censors on \(R(\tau)\): a deeper list holds proportionally more large-\(\tau\) partially recorded spots and the fit widens with it. Left uncapped, \(\sigma_M\) therefore tracks the spot budget rather than the crystal — and since an over-wide mosaicity mis-states every partiality, the merge degrades sharply with it.

The estimated mosaicity feeds the rotation prediction (how many frames each reflection spans, §8.3) and the rotation partiality (§10.2). It is held fixed during scaling: in the per-image scale fit the mosaicity is degenerate with the scale \(G\) (both rescale the predicted intensity), so refining it there is unstable. A correct mosaicity matters because it controls both how much of each rocking curve is captured and the partiality used to form fulls (§10.6); too small a value truncates the captured curve and over-peaks the partiality, degrading the combined fulls.


12. Auxiliary statistics: ⟨I/σ(I)⟩ and Wilson plot

12.1 Per-shell ⟨I/σ(I)⟩

For monitoring integration quality, Jungfraujoch reports mean \(\langle I/\sigma(I)\rangle\) in a fixed number of resolution shells. Shelling is performed in \(1/d^2\) space (typical of crystallographic practice).

12.2 Wilson plot (B-factor proxy)

A Wilson-type analysis is computed by binning intensities by resolution and fitting: \( \langle I\rangle \propto \exp\!\left(-\frac{B}{2}\frac{1}{d^2}\right), \) i.e. \( \log \langle I\rangle = \mathrm{const} - \frac{B}{2}\left(\frac{1}{d^2}\right). \) A linear regression of \(\log\langle I\rangle\) vs \(1/d^2\) provides an estimate of \(B\), subject to basic quality checks (e.g. \(R^2\) threshold).

A dataset-wide Wilson \(B\) is also estimated over the merged reflections — restricted to the meaningful resolution range (skipping the low-resolution non-linear region below ~4 Å and shells past the signal limit \(\langle I/\sigma\rangle < 1\), so it is insensitive to how far the merged data extend) — and written to the merged mmCIF as _reflns.B_iso_Wilson_estimate (and reported as WILSON_B=), the analogue of XDS’s Wilson-line \(B\). It is diagnostic only and is not fed back into scaling. It is the XDS convention, not the CCP4/Phenix one, and the two are not comparable. The slope here is fitted to \(\log\langle I\rangle\) directly; TRUNCATE, ctruncate and phenix.xtriage fit \(\log(\langle I\rangle/\Sigma)\), dividing out \(\Sigma=\sum_j f_j^2(s)\), the falloff of the atomic form factors for an assumed composition. Leaving \(\Sigma\) in the slope inflates \(B\) by roughly 2 to 8 Ų (measured across in-house merges; the arithmetic gives +6.9 Ų over 4.0-1.5 Å for a generic protein), and the fitted range accounts for more still: against ctruncate and phenix.xtriage on the same merged files this number runs 10 to 36 Ų high, in the same direction every time - though those two disagree with each other by 7 to 16 Ų, so there is a band rather than a right answer. Read it as a relative quantity, comparable between Rugnux runs and against XDS, and do not compare it with a value quoted from a CCP4 or Phenix log. The same caveat applies to _reflns.B_iso_Wilson_estimate in the merged mmCIF, whose deposited values are conventionally the \(\Sigma\)-normalised kind. It is also where the flux the fixed integration disk clips lands: that loss is degenerate with an overall \(B\), so the reported number carries an \(r_1\)-dependent contribution and is not a property of the crystal alone (§9.1). The per-image estimate (used for the live radiation-damage plot) is accepted only when the fit is well-correlated and physically plausible (\(0 < B < 200\) Ų); on a bad frame (an indexing glitch, too few reflections) the Wilson line runs wildly steep, so an implausible \(B\) is reported as NaN rather than a spurious hundreds-of-Ų value.

\ No newline at end of file diff --git a/CPU_DATA_ANALYSIS_REFINEMENT.html b/CPU_DATA_ANALYSIS_REFINEMENT.html new file mode 100644 index 000000000..d0b2aba92 --- /dev/null +++ b/CPU_DATA_ANALYSIS_REFINEMENT.html @@ -0,0 +1 @@ + Data analysis: refinement of a placed model (§15) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Data analysis: refinement of a placed model (§15)

Part of the CPU/GPU data-analysis reference; the section numbers are continuous across its parts.

15. Restrained refinement of a placed model

Wherever a model is placed - it fits where it is (§14.8), or molecular replacement placed it (§14.10) - rugnux refines it against the merge it was placed on (--no-refine skips this). rugnux --mode refine runs the same refinement on a model and merged structure factors that already exist. How to use it, and what it writes, is in Models and reference data; its report keys are in The results report.

The refinement comes after every processing decision and changes none of them. Nothing it finds is read by the space-group search, the indexing choice, the resolution cut or the files <prefix>.mtz, <prefix>_model.cif and <prefix>_maps.mtz; R_WORK and R_FREE stay those of the model as placed (§14.3). What it produces is written beside them: the refined model, its map coefficients, the blobs of its difference map and the REFINE_ keys.

The library reads and writes no file. The model and the reflections come in, the refined model, its statistics and its map coefficients go out; the restraint dictionary is compiled into the binary (§15.4).

15.1 What is refined, and in what order

The model is taken as the refinement can use it: the first model of the file only, its hydrogens removed, and every B clamped to the range the refinement allows (2 Ų up to twice the model’s largest B, within 100-300 Ų). An atom’s anisotropic U (ANISOU, _atom_site_anisotrop) is kept. Where the model has TLS groups (_pdbx_refine_tls*, PDB REMARK 3) whose atoms bring no U of their own, their U is made from the groups, and the B column is read either as the total B (as phenix.refine writes it) or as the residual to the groups (as REFMAC writes it) - whichever of the two, and of the isotropic B as it stands, scores the lowest R-free on the model as given (REFINE_ADP_INPUT). Occupancies are kept as they are, and so are alternative conformations, each refined with its own restraints.

Two stages follow.

  1. Placement. Each chain of at least 50 non-water atoms is moved as a rigid body - an angle-axis rotation about its centroid, scaled by its rms radius so that a unit of rotation moves a typical atom by about an angstrom, and a translation - against the X-ray target (§15.2), by Ceres’ L-BFGS for 30 iterations. Then one B shift per residue. Each of the two is kept only where it lowers R-free by more than 0.001: a deposited model was refined atom by atom already, and moving its chains or shifting its B factors residue by residue then only makes it worse. The placement stage needs no dictionary.

  2. Restrained refinement. Every atom’s position and isotropic B, against the X-ray target and the geometry of the dictionary (§15.4-§15.5), in weight trials chosen by R-free (§15.7). Residues the dictionary does not describe, and residues with an atom it does not know, are held fixed: they stay in the structure factors, in the bulk-solvent mask and in the repulsions the refined atoms see, but they do not move. So do atoms of zero occupancy.

15.2 The X-ray target

The target is the maximum-likelihood amplitude target: for an acentric reflection the Rice distribution of the observed amplitude \(F_o\) given the model’s \(|F_\mathrm{model}|\), for a centric one its centric counterpart,

\[ -\ln L_\mathrm{acentric} = \ln\Sigma + \frac{F_o^2 + D^2|F_\mathrm{model}|^2}{\Sigma} - \ln I_0\!\left(\frac{2F_o D|F_\mathrm{model}|}{\Sigma}\right),\qquad -\ln L_\mathrm{centric} = \tfrac12\ln\Sigma + \frac{F_o^2 + D^2|F_\mathrm{model}|^2}{2\Sigma} - \ln\cosh\frac{F_o D|F_\mathrm{model}|}{\Sigma}, \]

(the terms that depend on neither the model nor the parameters left out) with \(D\) the fraction of the model that is right and \(\Sigma\) the variance that the rest of the structure and the measurement leave (§15.3), summed over the working reflections. \(\ln I_0\) and \(I_1/I_0\) are evaluated with the polynomial approximations of Abramowitz and Stegun, through the exponentially scaled form for large arguments so that nothing overflows. The amplitudes are the French-Wilson \(|F|\) of §10.8 - the ones the written reflection file carries - and the free reflections are those of §10.7.

\(F_\mathrm{model}\) is the model of §14.2,

\[ F_\mathrm{model} = k\,e^{-\mathbf{s}^\top\mathbf{B}\mathbf{s}/4}\left(F_\mathrm{calc} + k_\mathrm{sol}\,e^{-B_\mathrm{sol}s^2/4}\,F_\mathrm{mask}\right), \]

with the atoms’ \(F_\mathrm{calc}\) computed with the dictionary’s riding hydrogens included (§15.4), from the IT92 form factors: a single-atom ion (a metal or a halide the dictionary describes) as the ion its dictionary charge makes it - Mg²⁺ and Na⁺ 10 electrons, K⁺, Ca²⁺ and Cl⁻ 18 - every other atom as the neutral atom, whatever formal charge the file gives it (a carboxylate’s O⁻, a lysine’s N⁺); the refined model is written with those charges. The scale, the anisotropic B, the bulk solvent and the likelihood’s parameters are fitted at the start of each macro-cycle (§15.3) and held fixed while the minimiser runs; the mask is drawn for the model as it is at that point.

The gradient by the FFT method. The atoms’ density is placed on a grid with a Gaussian blur (the one REFMAC-compatible density calculation uses, chosen for the lowest B a macro-cycle can reach) and transformed once; the crystal’s symmetry is composed in reciprocal space from the transform of one copy, as for the rigid body (§14.8). The derivative of the target with respect to every structure factor, taken back to real space by one inverse transform through the adjoint of that composition, is a map; each atom’s derivatives with respect to \(x, y, z\) and \(B\) are that map summed against the derivatives of its own blurred density. One evaluation of the target and of the gradient of every atom thus costs a density gather, two FFTs and a gradient gather, whatever the number of atoms. The derivative of a riding hydrogen is passed to its parent.

15.3 Scale, bulk solvent and the likelihood parameters

Scale and solvent. The flat bulk-solvent mask is drawn with the REFMAC radii (probe 1.0 Å, shrink 0.8 Å) on a grid of its own, with a spacing of \(d_\mathrm{min}/3\) or 0.4 Å, whichever is finer (coarser only where a cell would need more than \(2^{26}\) points, and then never coarser than 0.75 Å nor than the density grid, which a cell that large uses for its mask). On the atoms’ density grid the shrink is lost at low resolution: at 3 Å its 1 Å step leaves no grid point within the shrink radius. \(k_\mathrm{sol}\) and \(B_\mathrm{sol}\) are searched over their physical range on the working reflections, and the overall scale and anisotropic B are fitted at each point of that search (§14.2) - at the points of its fine pass by robust least squares: iteratively reweighted (four reweightings), each reflection’s residual \(r = F_o - |F_\mathrm{model}|\) weighted by \(1/\sqrt{1 + (r/c)^2}\) with \(c\) the median \(|r|\) of the unweighted fit. The fit then minimises the pseudo-Huber loss \(\sum 2c^2\left(\sqrt{1 + (r/c)^2} - 1\right)\), quadratic for the bulk of the reflections and linear for the few a model cannot explain - a beam-stop shadow, an ice ring, a missing part of the model - which ordinary least squares would let set the scale of all the rest. When the B factors are refined, the overall isotropic part of the scale’s B is moved into the atoms (and into \(B_\mathrm{sol}\), so that \(F_\mathrm{model}\) stays as it is); left in the scale, it and the atoms’ B drift against each other as the B factors are refined.

With these three choices - riding hydrogens, the fine mask grid and the robust scale - the R-work and R-free of a model as given (REFINE_R_WORK_START, REFINE_R_FREE_START) agree with REFMAC 5.8’s 0-cycle values on the same model and data within 0.006 on depositions from 1.1 to 3.6 Å (tools/battery/refine_parity.py).

\(D\) and \(\Sigma\). The two parameters of the likelihood are fitted by maximum likelihood in resolution bins of the free set (100 free reflections to a bin, at most 30 bins; where the free set has fewer than 100 reflections, the working ones join it so that the likelihood still has a scale), and interpolated linearly in \(1/d^2\) between the bins’ centres:

  • \(\beta\) on the free reflections, as the whole spread of \(F_o\) about \(D F_\mathrm{model}\) with variance \(\varepsilon\beta\) - the measurement error included;

  • \(D\) then on the working reflections of the bin, with the variance \(\Sigma = \varepsilon\beta + 2\sigma^2\) for an acentric reflection and \(\varepsilon\beta + \sigma^2\) for a centric one, \(\sigma\) the amplitude’s own error.

\(\Sigma\) is also the variance of each reflection in the target. Where the measurement error is a large part of the spread - the weak high-resolution shells - it is counted twice, and \(D\) falls towards 0 there, with the figure of merit. This division of the two parameters between the working and the free set is the one REFMAC5 describes; measured on REFMAC 5.8’s own output it reproduces its \(D\) by bin and its overall figure of merit (the mean over the working reflections) to about 0.01 on most depositions.

15.4 The dictionary and the topology

The restraints are those of the CCP4 Monomer Library, a subset of which is compiled into rugnux (image_analysis/structure_refinement/monomers/, regenerated by update_monomers.py; nothing is read from disk, and $CLIBD is never consulted): the 20 standard amino acids and MSE; the DNA and RNA nucleotides (DA, DC, DG, DT, A, C, G, U); the modified nucleotides of tRNA and rRNA met most often - pseudouridine (PSU), 5-methylcytidine (5MC), 1-methyladenosine (1MA), the 2’-O-methyl nucleotides OMG, OMC and OMU, dihydrouridine (H2U), N2-methyl- and N2,N2-dimethylguanosine (2MG, M2G), 7-methylguanosine (7MG) and ribothymidine (5MU), polymer residues joined by the same backbone link; ATP, ADP, AMP, GTP, GDP and GMP; the cofactors NAD⁺ (NAD), NADH (NAI), NADP⁺ (NAP), NADPH (NDP), FAD, FMN, heme (HEM), heme C (HEC), S-adenosylmethionine (SAM) and S-adenosylhomocysteine (SAH), and dioxygen (OXY); DMSO; the PEG fragments PEG, PGE, PG4 and 1PE; glycerol, ethylene glycol, MPD, acetate, sulfate and phosphate; water; and the ions Na, K, Mg, Ca, Mn, Fe²⁺, Fe³⁺, Co, Ni, Cu, Zn, Cd, Cl, Br and I - 84 compounds - with the library’s links and modifications that apply to them (among them heme C’s two thioethers to its cysteines, HEC-CYS1 and HEC-CYS2, and the covalent links of heme and FAD to the protein) and the energy types those compounds use.

The model’s topology is built from it by GEMMI (prepare_topology): the links between residues (the peptide and cis-peptide, the nucleic-acid backbone, disulfides, and the model’s LINK records where the library describes them), the modifications those links imply, and per residue the bonds, angles, torsions, chiral volumes and planes. Torsions are restrained where the dictionary gives them an esd, except the main-chain φ/ψ and the sugar puckers it lists as alternatives. The dictionary’s hydrogens are added to every residue it describes (waters excepted), placed by GEMMI from the dictionary’s geometry and moved with their parents: they take part in the structure factors and in no restraint, and are placed again on their parents at every macro-cycle. The refined model is written with them.

15.5 Geometry, metal and B restraints

Every restraint is a squared normalised deviation, \(E = ((x - x_\mathrm{ideal})/\sigma)^2\), with its analytic derivatives:

  • bonds and angles, ideal and esd from the dictionary;

  • torsions, modulo the dictionary’s period, with derivatives in the form of Blondel and Karplus, free of the singularities of the arccos form;

  • chiral volumes \((\mathbf{a}_1 - \mathbf{c})\cdot((\mathbf{a}_2 - \mathbf{c})\times(\mathbf{a}_3 - \mathbf{c}))\), \(\sigma = 0.2\) ų;

  • planes: the distances of the atoms from their least-squares plane (the plane’s normal the smallest eigenvector of the atoms’ scatter, by Jacobi rotations); the plane is optimal, so the derivative of each distance carries no term from the plane moving;

  • repulsions of every pair of atoms closer than its contact distance, symmetry mates included, that no bond, angle or 1-4 relation joins and that are not alternative conformations of each other, with at least one of the two refinable: \(E = ((d_0 - d)/0.2\,\text{Å})^2\) below the contact distance \(d_0\) and nothing above it, \(d_0\) the sum of the energy types’ van der Waals radii, 2.6 Å where both atoms can hydrogen-bond and 1.9 Å between a metal and N, O or S. The list is rebuilt at every macro-cycle.

Special positions. An atom closer than 0.5 Å to one of its own symmetry images (the depositions put theirs within 0.03 Å of the site) is on a special position: the symmetry operations, each with its lattice translation, that take it onto itself are its site symmetry (Grosse-Kunstleve & Adams 2002). It is placed exactly on the site - the mean of its position and its images under the site symmetry - and its shifts are confined to the subspace those operations leave unchanged: the gradient is projected by the mean of their rotations (along a 2-fold or 4-fold axis, nowhere on a centre of inversion). Its occupancy is kept as given, the coinciding copies each counting it (0.25 on a 4-fold axis), it makes no contact with its own copies, each of its contacts is listed once rather than once per copy, and it moves with no rigid body.

Metal sites. A metal - an ion, or a metal atom of a ligand such as a heme’s iron - is restrained to the donor atoms (O, N or S) that the model’s LINK / _struct_conn records bind it to. Where the library has a link for the pair - its ZN-CYS, ZN-HISND, ZN-HISNE, FE-CYS, FE-HISND and FE-HISNE - that link is used as it is, with the modification it makes to the donor’s residue (the proton the bond replaces). Every other record becomes a link of one bond at the distance of the library’s own statistics of metal sites (its metals.json, carried as monomers/metals.cif) for the metal, the donor element and the site’s coordination number - but only where the model makes the contact an inner-sphere one: no further than that distance plus 0.33 Å (Mg-O 2.07 + 0.33 = 2.4 Å, the inner-sphere bound of Leonarski et al. 2017, the same margin for every metal). A record at an outer-sphere distance - deposited models carry many, a Mg “bonded” to a phosphate O at 2.9 Å, a Na to a water at 3.0 Å - would pull the ion onto that atom; it stays a contact instead. The coordination number is the number of records the metal has within its inner sphere, plus the bonds its own residue’s dictionary gives it (a heme iron’s four pyrrole nitrogens) - interpolated linearly between two tabulated coordination numbers (rows resting on at least 20 sites count; σ is the row’s standard deviation, at least 0.02 Å). Only the bond is restrained, not the angles at the metal. A contact without a record stays a repulsion, and a record to a symmetry mate is left out, as every bond to a symmetry mate is. Which records stay contacts is decided once, on the model as given: one topology serves the whole refinement, its solvent build included, so a record is not judged again on a distance the refinement has moved (a record at 2.50 Å refused, the ion slid to 2.39 Å, would have been taken). The records are written out with the refined model as they were read, without the names of the links made here. The rmsd of these bonds - with the dictionary’s own bonds of a metal within a ligand, a heme iron’s to its porphyrin - is reported apart from the covalent bonds’ (REFINE_RMSD_METAL_BONDS).

Anisotropic atoms. An atom’s U is held as its equivalent isotropic B and a traceless anisotropy, \(U = U_\mathrm{dev} + B/(8\pi^2)\,I\), so that everything that refines, restrains and bounds B works on an anisotropic atom as on an isotropic one, its shape held. Both engines grid it with its full U (an anisotropic Gaussian per form-factor term, cut at the radius of its widest axis) and give the target’s derivatives in its six U elements by the same FFT method: for \(\rho_q = a_q \exp(\mathbf{r}^T M_q \mathbf{r})\), \(M_q = -4\pi^2(8\pi^2 U + B_q + B_\mathrm{blur})^{-1}\), \(\partial\rho_q/\partial U = \rho_q\,(M_q + 2 M_q\mathbf{r}\,\mathbf{r}^T M_q)\). Every U stays positive definite: its smallest eigenvalue (as B) at least the cycle’s floor, its largest at most the ceiling of §15.1.

A TLS group gives each of its atoms \(U = T + A L A^T + A S + S^T A^T\) at \(\mathbf{r}\) from its origin, \(A = [[0, z, -y], [-z, 0, x], [y, -x, 0]]\) (Schomaker and Trueblood), plus a residual isotropic B per atom; its 20 parameters (the trace of S does not enter U) are refined against the X-ray target alone, the residual B held, with the derivatives by the chain rule from the atoms’ U derivatives (\(G\) for T, \(A^T G A\) for L, \(2 A^T G\) for S, \(G\) an atom’s symmetric matrix of derivatives). An atom refined with a U of its own is restrained, for each pair of bonded or angle-related atoms, by the rigid bond \(|(U_i - U_j)\mathbf{n}|^2/\sigma^2\), \(\sigma\) = 0.004 Ų along the line \(\mathbf{n}\) between them (the components SHELXL’s RIGU restrains), and by the similarity \(|U_i - U_j|^2/\sigma^2\), \(\sigma\) = 0.04 Ų (SIMU); an atom in no pair (a water, an ion) by \(|U - \mathrm{tr}(U)/3\,I|^2/\sigma^2\), \(\sigma\) = 0.1 Ų (ISOR).

B restraints. The B factors of two atoms are restrained to each other in proportion to their size, by the symmetric Kullback-Leibler divergence of two isotropic Gaussians of variances \(B_i\) and \(B_j\):

\[ E = \frac{(B_i - B_j)^2}{\kappa^2 B_i B_j}, \]

a difference restraint whose \(\sigma\) is \(\kappa\sqrt{B_iB_j}\), so that atoms of high B may differ more than atoms of low B. \(\kappa\) is 0.1 for bonded main-chain atoms and 0.133 for main-chain atoms bonded to a common atom, 0.2 and 0.3 for the side chains and the rest, and 0.5 for atoms within 4 Å of each other (waters among them, symmetry mates included) that no bond or angle relates. No atom’s B goes below 2 Ų or above the ceiling of §15.1.

NCS restraints. Where the model holds several copies of one molecule, they are found from the model alone: two polymer chains of one kind (protein, or nucleic acid) are copies where their sequences align with more than 15 residues identical and identical in 80% of the longer chain or more, and their C-alpha (P) atoms lie within 2.5 Å rms of each other after superposition - REFMAC5’s criterion, the identity taken on the longer chain. The same sequence in a conformation further away than that, such as a quasi-equivalent subunit of a virus capsid, is another molecule. In the residues aligned to a residue of the same name, the atoms of the same name correspond - not a hydrogen, not an alternative conformation, both refinable. Each copy is paired with the next of its molecule (and the last with the first, where there are three or more), and each pair is restrained locally, on its interatomic distances rather than on a superposition: every distance within a chain shorter than 4.2 Å in either copy, except those a bond or an angle of the dictionary already fixes, against the same distance in the other copy, with the robust loss of Geman and McClure,

\[ E = rac{(\Delta/\sigma)^2}{1 + (\Delta/0.5\, ext{Å})^2},\qquad \Delta = d_\mathrm{copy\,1} - d_\mathrm{copy\,2}, \]

the squared normalised difference where the two distances agree and never more than \((0.5\, ext{Å}/\sigma)^2\) where they do not. A region in which the copies really differ - a loop in a crystal contact, a side chain in another rotamer, a domain turned on a hinge - lets itself go as the refinement moves it, without a rule deciding in advance which residues to exclude, and rigid motions of whole regions cost nothing, since only distances within 4.2 Å are compared. Waters and ligands are not restrained, nor are B factors: the copies’ B factors are refined independently. Whether the restraints are used at all, and how tightly (\(\sigma\)), the weight trials decide (§15.7).

15.6 The minimiser

Positions and B factors are minimised in turn, each by an L-BFGS of rugnux’s own (RefinementMinimiser), with the two-loop recursion of Nocedal and of Liu and Nocedal, a memory of 20 pairs and a backtracking line search from the full step to sufficient decrease, its first trial moving no position by more than 0.3 Å and no B by more than 10 Ų. What sets it apart from a textbook L-BFGS:

  • Its memory is kept from one macro-cycle to the next. A macro-cycle is a few dozen iterations on a target whose scale and likelihood parameters were refitted in between; starting each from what the earlier ones learnt of the curvature, instead of from a steepest-descent step, is what lets two macro-cycles of a weight trial get as far as many restarted ones. Each weight trial starts with an empty memory.

  • The B steps are scaled by their curvature. The initial inverse Hessian of the B factors is a diagonal: the X-ray target’s curvature in each atom’s B - its shape from the likelihood’s curvature in \(|F_\mathrm{model}|\) and the atom’s own scattering, summed in resolution shells, calibrated once per trial against central differences of the gradient along a random \(\pm1\) direction - plus the B restraints’ curvature, each element at least a thousandth of the median. The positions take none: their restraints’ curvature is that of stiff bonds and angles, which move atoms together, and as a diagonal it slows the soft (torsion and X-ray) directions rather than scaling them.

The diagonal is rescaled at each iteration by the latest pair (Oren-Shanno scaling in that metric). A solve stops after its iteration budget (30 for the positions and 20 for the B factors per macro-cycle) or where an iteration lowers the target by less than \(10^{-7}\) of it.

15.7 The weights, decided by trial

The refined target is \(w\,T_\mathrm{X\text{-}ray} + E_\mathrm{geometry}\) for the positions and \(w_B\,T_\mathrm{X\text{-}ray} + E_B\) for the B factors. Rather than fixing \(w\) and \(w_B\) in advance, rugnux runs short refinements at several weights and keeps the one that does best on the free set - a weight chosen late, on the evidence, instead of early at a rule.

The starting weights balance the gradients: \(w_0 = |\nabla E_\mathrm{geometry}| / |\nabla T_\mathrm{X\text{-}ray}|\), the geometry’s gradient taken on the model shaken by 0.1 Å (a refined model’s geometry would give none), and \(w_{B,0}\) likewise from the B restraints on the B factors shaken by 20%. Each trial is two macro-cycles (the scale, solvent and likelihood refitted, then the positions, then the B factors) from where it starts. A trial is within bounds where its rmsd from the dictionary is at most 0.02 Å for bonds and 2° for angles; one trial displaces another where it is within bounds and its R-free is lower by more than 0.001 (differences smaller than that do not decide, and the trial listed first - on a ladder, the tighter geometry - is kept). The trials are:

  1. The ladder from the placed model: \(w = w_0 \times \{1/1024, 1/128, 1/16\}\), each with the B factors held and refined at \(w_{B,0}\) - six trials.

  2. The trajectory: up to eight steps, each a set of trials from where the last step ended - the weights as they are, and in turn the positions’ weight halved and doubled (halved because the geometry loosens at one weight as the model improves, until it leaves the bounds) or the B factors’ weight divided and multiplied by four. A step is taken while it lowers R-free or R-work by more than 0.001 and its R-free stays within 0.001 of the best so far, and the trajectory ends at its best step. On a deposited model, whose free set the depositor’s refinement has already fitted, R-work falls while R-free rises, and the trajectory ends where it began.

  3. The final ladder: the trajectory’s weights times \(\{1, 2\}\), kept where one displaces it (the weight halved was never kept on 55 refinements, and taking it away changed no choice).

  4. The displacement model, from where the weights ended (the B factors as they are: isotropic, or the model’s U held), each trial as long as a step on the positions where the weights ended, held - only the displacement parameters refine, so the trials differ in the displacement model alone; the model chosen then takes a step with the positions refined, kept where it displaces its trial (where the geometry is out of bounds there, which held positions cannot mend, each trial refines the positions too, a macro-cycle longer than a step): TLS groups with a residual B - the model’s own, one per chain of at least 50 refinable atoms, and the chains cut into 4, 8 and 16 contiguous segments of at least 10 residues as TLSMD cuts them (by dynamic programming over the least-squares fit of an isotropic TLS model, a quadratic B(r), to the refined B factors), each cut where it gives more groups than the one before; and a U per atom, at the U weight balanced as \(w_{B,0}\) is (on the U shaken by 20% of its B) times \(\{1/4, 1\}\). The cuts between one group per chain and the finest run only where the finest fits the free set better (lower \(-\ln L\)) than one per chain, and the U at its balanced weight only where the U at a quarter of it lowers R-free or \(-\ln L\) of the free reflections from where the weights ended; on 49 refinements of 33 structures neither the cuts’ rule nor leaving out the U weight \(\times 4\) changed a choice taken. A trial displaces the one before it (the first: where the weights ended) only where its geometry is within bounds and both its R-free (beyond the tie) and the \(-\ln L\) of the free reflections are lower: the free set tests the parameters a model adds, so the choice is made on the evidence of each run, not at a resolution (Merritt 2012). The refined U are written as ANISOU and the TLS groups as _pdbx_refine_tls* and REMARK 3 (REFINE_ADP_MODEL, REFINE_ANISO_ATOMS, REFINE_TLS_GROUPS). It is decided after the solvent build (§15.10), on the model with its solvent: a water a round put in refines a U of its own in the per-atom trial as every refinable atom does, and no TLS group holds a water.

  5. The model as given is the first candidate in order of trust: where the refinement does not displace it by the rule every trial is held to (its geometry within bounds and R-free lower beyond the tie), the model is written as it came, scaled to the data, and the solvent build’s edits are undone (REFINE_AS_GIVEN). What comes out is never worse on the free set than what went in. This holds only where the free set is free to the model as given: a model placed as given on a free set drawn by the run (in --mode refine, a file without free flags) has most likely been refined against those reflections, and its R-free as given does not compete.

Where the model has copies (§15.5), the NCS restraints are one more weight: every rung of the first ladder is run without them, and then with them at \(\sigma = 0.1\) Å at the B factors’ weight the rungs without chose (NCS moves the X-ray weight a rung up as often as not, the B factors’ choice it never changed on 39 refinements), and every step of the trajectory also tries them changed - switched on where they are off, and in turn tightened (\(\sigma\) halved) and loosened (\(\sigma\) doubled, off beyond 0.4 Å) where they are on. Listed after their twin without, the restraints are kept only where they lower R-free by more than the tie. A model without copies runs exactly the trials it ran before.

\(w\) never exceeds \(w_0/8\). The trials of one set run side by side - on one GPU, on several, or on the CPU’s threads - each from the same start and taking nothing from the one before it, so the result does not depend on how many run at once.

The refinement can be cut short from outside (the broker’s deadline or cancel, Ctrl+C): the check is made between the minimiser’s iterations and before every trial, the trials that finished are chosen among as usual, and the report says so. Cut before the first trial, the model is the placement’s.

15.8 Maps of the refined model

The refined model’s map coefficients, <prefix>_refined_maps.mtz, are \(2mF_o - DF_c\) and \(mF_o - DF_c\) as in §14.4, but with \(m\) and \(D\) those of the refinement’s own likelihood (§15.3) rather than the shell \(\sigma_A\) of §14.4, so the maps carry the weights the target was minimised with; \(m\) is \(I_1(X)/I_0(X)\), \(X = 2F_oD|F_\mathrm{model}|/\Sigma\), for an acentric reflection and \(\tanh(X/2)\) for a centric one. As in §14.4, the coefficients in the file have the overall anisotropy of the scale (the anisotropic part of \(k_\mathrm{total}\)) divided out, while the maps the refinement reads itself (the blob finder, the solvent audit) keep the observed scale. FWT/PHWT is filled at the reflections the data do not have with \(D|F_\mathrm{model}|\) and FWT_no_fill/PHWT_no_fill is not, as in §14.4; \(F_\mathrm{model}\) there is the refined model’s with the bulk solvent and scale of the last fit. Where the merge kept the Bijvoet pairs, the anomalous difference map is made on the refined model’s phases too, written in the same file as ANOM/PHANOM (as in <prefix>_maps.mtz; missing where a reflection has no Bijvoet pair), and read by the blob finder below.

15.9 Unexplained density: blobs

The \(mF_o - DF_c\) map of the refined model is searched for what the model leaves unexplained: the connected regions above 3 σ that peak above 4 σ, found by flood fill (GEMMI’s find_blobs_by_flood_fill, the method of Coot’s “unmodelled blobs”), each moved to the copy nearest the model and measured - peak, volume, the density integrated above the cutoff, the nearest atom, the polar (N, O) atoms at 2.4-3.4 Å and the N, O or S at 1.8-2.6 Å, and the anomalous map at its peak. Each gets one reading, by rules on what is measured:

Reading

Rule

MODEL_ERROR

within 1.6 Å of a model atom: the model’s own atom out of place, or a missing alternative conformation

ION

at least 1.8 Å from the model, and an anomalous peak of at least 4 σ, or two metal-like contacts and a peak of at least 8 σ

LIGAND

larger than 1.5 times a single atom’s blob at this resolution (a sphere of radius \(d_\mathrm{min}/2\)) and than 8 ų, at least 2.2 Å from the model

WATER

at least 2.2 Å from the model with at least one polar contact

UNASSIGNED

anything else

They are listed strongest first (by the integrated density) in <prefix>_blobs.json, and the five strongest in the report, each with the anomalous difference map’s height at its peak where there is that map. A blob read as LIGAND is density of ligand size where the model has nothing: a buffer molecule or an unmodelled side chain is that as well as the compound that was soaked. The readings point a person at the density; they do not identify a compound.

15.10 The solvent audit

Every water and every single-atom ion of the refined model (and, with --refine-score-only, of the model as given) is measured in its surroundings and its density and scored as each of water, Mg²⁺, Na⁺, K⁺, Ca²⁺ and Cl⁻ (NH₄⁺ is scored too, and only reported). The audit changes nothing; the solvent build below reads it to relabel sites. Both run only with --refine-solvent (off by default).

What is measured. The model’s N and O atoms around the site, symmetry mates included, counted in the coordination bands of Cat_Wiz - 1.9-2.3 Å (Mg-like), 2.3-2.6 Å (Na, Ca), 2.6-3.2 Å (K, water) - and in the clash shells 3.2-3.4 and 3.4-3.6 Å beyond them. Each neighbour is typed from the dictionary’s energy type (donor, acceptor or both) and from the chemistry of its residue: Lys NZ, Arg NE/NH1/NH2 and a polypeptide’s N-terminal N are positive; Asp/Glu carboxylate O, a C-terminal carboxylate and a nucleotide’s phosphate O are negative; His ring N and the Asn/Gln amide ends are both donor and acceptor, as the model’s orientation of them is a guess. Also measured: the shortest distance between two neighbours closer than 2.6 Å (the octahedron’s cis O…O), the nearest positive and negative group, the other ions within 4.2 and 6 Å, the bond-valence sum \(V = \sum_j q_j \exp((R_0 - d_j)/0.37)\) over the N and O within 3.5 Å for each cation (\(R_0\) of Brese & O’Keeffe, \(q_j\) the neighbour’s occupancy) with its normalised vector sum (CheckMyMetal’s nVECSUM), and the 2mFo-DFc, mFo-DFc and anomalous maps at the site, in their rms.

The electrons a site shows. The site’s own density is fitted to 2mFo-DFc with its neighbours’ held - a local real-space fit of one amplitude at a B tied to its surroundings: the map at points 0.3 Å apart within 1.0 Å of the site, put on the model’s scale, less the density the model’s other atoms put there (each atom’s IT92 density to the data’s resolution at its B, to 4.5 Å), against a water’s density (O with its two H) at the environment’s B (the mean B of the N and O within 3.5 Å, as CheckMyMetal compares a metal’s with its ligands’), least squares. The amplitude, in waters, is the electrons it shows, and counted apart from the neighbours’ that merge with it at moderate resolution. The map’s scale per model unit is the median, over the macromolecule’s C, N and O within 6 Å (or all of them where fewer than three are), of each atom’s height in the map over what the model puts there - not the waters’, whose occupancy is the model’s guess (the depositions’ waters show half the density their model gives). An ion - whose label’s restraints may hold it off its density - is read where that fit puts it, within 0.6 Å of its modelled position (its shell, bands and bond valences are measured from there); a water where it is modelled. On deposited models the ions typically read Mg 11, Na 10, Cl 19, K 21-23, Ca 22-26 and Zn 33, the waters 4-6.

The anomalous signal a site would show. For each species, f″ at the data’s wavelength (Cromer-Liberman, with the corrections of Kissel & Pratt, as GEMMI computes it) at the environment’s B, put on the scale of the anomalous map by least squares on the model’s S and P (at least three); without an anomalous map, or nothing to scale it by, the term is left out.

The score. For each species, a plain sum of terms in log units:

Term

What it is

first shell

the neighbours in the species’ band against the coordination number it holds (Mg 6, Na 5-6, K 6-10, Ca 6-8, Cl 3-5, NH₄⁺ 4), quadratic; for water only more than four, or none at all, costs; for Mg, Na, Ca and Cl a missing ligand costs little (0.5), as the model may simply not have that water - and a halide binds at hydrophobic surfaces too, with few donors or none (Dauter & Dauter 2001), where its electrons and its anomalous signal tell it from a water

distances

for Mg, each neighbour in the band against Mg-O 2.07 ± 0.04 Å, Mg-N 2.19 ± 0.08 Å; for the others, whose distances are spread over their bands, the band is all there is

contacts it does not make

2 per N or O closer than the species’ shell (closer than 2.9 Å for Cl), and for Mg per N or O in its exclusion zone 2.3-3.4 Å; for Mg and Ca 2 per first-shell purine N7 the site is more than 1.0 Å out of the plane of, or not 3.5-3.9 Å from the base’s O6 or N6 (Leonarski et al. 2017)

chemistry

a cation: 2 per donor-only neighbour in its shell and per positive group within 3.5 Å; Cl: 2 per acceptor-only neighbour and per negative group within 3.2 Å; water: 2 per hydrogen bond beyond two donated or two accepted (neighbours at 2.6-3.4 Å)

bond valence

for a cation, \(V\) against its charge \(z\), Gaussian with a spread of \(0.25z\) widened by the neighbours’ distance errors, and the vector sum against CheckMyMetal’s outlier bound 0.23

electrons

the electrons the site shows against those the species would (its density’s height over a water’s at the environment’s B: Mg²⁺ and Na⁺ about 11, K⁺, Ca²⁺ and Cl⁻ about 20) - an ion at full occupancy, a water as the model’s waters show (their median) - log-normal with the spread of the waters’ (an ion’s occupancy and order vary as much), at least that of the map’s calibration. A site as dense as a full 10-electron scatterer is so more than a typical water, as Echols et al. flag a light ion by a 2mFo-DFc above the waters’ mean; where the density is weak the term tells little, and the shell decides

anomalous

the anomalous map at the site against what the species would show, Gaussian in the map’s rms

A site bound to another cation (closer than 2.6 Å) shares that cation’s other ligands as neighbours - the cis waters of a Mg(H₂O)₆ are 2.9 Å apart - and those are left out of its score. Coordinate error: each atom’s is taken as its rms displacement \(\sqrt{B/8\pi^2}\) times \(d_\mathrm{min}/10\) Å (about 0.1 Å at B = 20 Ų and 2 Å); a neighbour’s band is widened by the error of the distance and its distance term is widened by it too, so that where the coordinates are poor the species’ shells overlap and the score stops telling them apart instead of telling them apart wrongly. The best of water, Mg, Na, K, Ca and Cl is reported, and AMBIGUOUS where the runner-up is within 2. The audit counts a site as disagreeing with its label where the best species is another one, not ambiguously.

Caveats. The refined model’s metal-site distances are restrained (§15.5) where its LINK records name the bonds, which pulls an ion’s shell towards the label it carries - the first pitfall of every survey of ions in the PDB; the local fit reads the ion where its density puts it, but its ligands stay where the restraints held them. --mode refine --refine-score-only audits the model as given instead. The species are the six above: a site denser than any of them (a cacodylate’s As, a heavier metal) is called the heaviest that fits worst least. Per site, everything above is in <prefix>_solvent.json (with electrons, b_env, peak_shift_A, anomalous_expected, n7_ligands, n7_off_plane); the counts are the REFINE_SOLVENT_ keys of the report.

The solvent build. Within the refinement, and to 2.8 Å (phenix.refine’s ordered-solvent limit), waters are built and removed and waters and ions relabelled, as phenix.refine builds waters within its macro-cycles. Where the weight trajectory (§15.7) ends, a round reads the maps and the audit of that model and changes its solvent; then the solvent alone - its waters and single-atom ions, the rest held - is refined at the weights the trajectory ended at (its B too, at its balanced weight where the trajectory held B, and 10 iterations a macro-cycle), and the round is kept where that lowers R-free; where it does not but the round as built does (refining the solvent alone can lose what its sites gained), it is kept as built; otherwise it is undone. The rest of the model goes on with its B factors held or refined as the trajectory had them. The rounds stop at one that changes nothing, at one undone, or after two (a third gains nothing measurable); the final ladder of §15.7 then refines what they kept with the rest. The atom list of a refinement is fixed - its engines are made for it - so the waters a round may add are in the model from the start as placeholders: one water each (as many as a fifteenth of the model’s heavy atoms, at least 64) at occupancy 0, which puts no density, no mask and no contact anywhere and is not refined until a round puts one at a peak; a water taken out goes to occupancy 0 the same way, and a relabelled site keeps its place. A round thus costs a map, an audit and a refinement of the solvent, so the build adds somewhat less than the refinement’s own time. --refine-score-only builds nothing, and the build and the audit run only with --refine-solvent (off by default).

  • Relabelled is a water or a single-atom ion (no alternative conformer) whose best-supported species is another one, not ambiguously - a water becomes an ion, an ion water or another ion - once per site. It takes the species’ residue name, element and atom name, and scatters as its ion (§15.2); its metal records go, and a metal gets a record for each N, O and S of its inner sphere in the model’s own copy (within the library’s distance plus 0.33 Å, at the coordination of those within an octahedral site’s), which the next refinement restrains as it restrains the model’s own (§15.5).

  • Candidates are the local maxima of mFo-DFc from 3 σ (phenix.refine’s peak cutoff), each symmetry-equivalent set once, moved to the copy nearest the model - the symmetry operator and lattice translation that put it closest to an atom of the model as written, so a water built there is written beside the model, not beside a symmetry mate or in another unit cell. A peak closer than 1.2 Å to a model atom is that atom’s own residual and is passed over.

  • Not solvent - reported in <prefix>_solvent.json with the reason, never filled: a peak 1.2-1.9 Å from a model atom (a missing or displaced atom); one beside a model atom (within 2.6 Å) that sits in mFo-DFc of -3 σ or lower (the atom is displaced); one within 3 Å of where a truncated residue’s missing atoms would be (an atom the dictionary bonds to an atom the model lacks); the centre of three or more other peaks at 1.3-1.7 Å (a tetrahedral group, sulfate or phosphate) or any peak with another 1.1-1.9 Å away (atoms of one molecule); elongated density (the rms length of the density above 3 σ within 1.6 Å along its longest axis over its shortest above 3); and 2mFo-DFc above every S and P of the model (a heavier atom).

  • A water is placed where the peak has a hydrogen-bond partner - an N or O that can donate or accept at 2.2-3.4 Å (phenix.refine’s 3.2 Å, widened for the coordinate error), a metal within 2.6 Å (its ligand), or a halide at 2.9-3.4 Å - and nothing closer than 2.2 Å to an N or O, nor than 3.0 Å to any other atom (Coot keeps waters 2.4-3.2 Å from the model; a little wider here for the peak’s position), strongest first, none within 2.2 Å of one already placed. It goes into a chain of waters of its own, as PDB and mmCIF entries keep them - chain W (or, where the model’s chain W holds more than waters, the first of X, Y, Z, V, U, … that does not), HOH residues numbered on from that chain’s last, a water entity and subchain of their own in the mmCIF - with occupancy 1 and the mean B of its partners. The model’s own waters stay where they were. A peak on a special position (§15.5) is placed exactly on it with occupancy 1 over the site’s multiplicity, its coinciding copies one water; one 0.5-2.2 Å from its own copy, which it would clash with, is refused.

  • Removed is any water whose mFo-DFc at its centre is -3 σ or lower (the cut Echols et al. use), and a water the build itself added that has no N, O or ion within 3.4 Å any more or whose B reached the refinement’s ceiling. phenix.refine’s other filter, 2mFo-DFc below 1 σ at a refined water, is not used: it raises R-free, on deposited waters and on the waters built here, and so does taking out deposited waters without a partner. A weak water still explains density, and a deposited one carries its depositor’s judgement.

REFINE_SOLVENT_ADDED and REFINE_SOLVENT_REMOVED count the waters added and still there and those of the model as given taken out, REFINE_SOLVENT_RELABELLED the sites relabelled (each, with its scores, in the report and the JSON); REFINE_SOLVENT_NOT_SOLVENT the not-solvent peaks of the final model’s difference map; REFINE_SOLVENT_BUILD_ROUNDS the rounds kept. The model as given (REFINE_R_FREE_START) and the placement stage are the first refinement’s; the refined model, its R-factors (the REFINE_SCORE_ terms with them), geometry, maps and blobs are the last kept round’s.

15.11 GPU and CPU

On a CUDA build the target, the gradient and the restraints are evaluated on the card - the density gather, cuFFT, the composition of the symmetry and the target per reflection, the adjoint through a CSR list, the inverse transform and one warp per atom for its gradient; the restraints in one kernel whose per-atom gradient slots are summed in a fixed order; the robust scale fit and the fine solvent mask on the card as well - with no floating-point atomics, so the result is the same from run to run. The weight trials of a set run on as many cards as there are, each trial on an engine of its own. Where the case does not fit the card’s budget, or with --no-gpu, or on a build without CUDA (macOS included: on the Apple GPU only the model density is put on the grid, §15.2, the rest has no Metal path), the CPU engine computes the same target, to rounding, several times more slowly (seconds on a GPU, typically 2-15 minutes on the CPU).

15.12 Twinned data

Where the lattice admits a twin law for the group the data are merged in - a rotation of the lattice’s metric symmetry (Le Page two-folds within 3° of obliquity, the search the free set is grouped by, §10.7) that the group lacks, one per coset of the group, with its square in the group so that it exchanges two domains - the placed model is refined a second time, against the data as twinned by the law, and the two refinements are compared. rugnux <file> does this on its own; nothing has to be given.

The target. A crystal twinned by law \(T\) at fraction \(\alpha\) records \((1-\alpha)I(\mathbf{h}) + \alpha I(T\mathbf{h})\) (Yeates 1997), so the model an observation is compared with is

\[ |F_\mathrm{twin}(\mathbf{h})| = k\,e^{-\mathbf{s}^\top\mathbf{B}\mathbf{s}/4}\sqrt{(1-\alpha)\,|F_\mathrm{calc}(\mathbf{h}) + F_\mathrm{sol}(\mathbf{h})|^2 + \alpha\,|F_\mathrm{calc}(T\mathbf{h}) + F_\mathrm{sol}(T\mathbf{h})|^2}, \]

and the target is the likelihood of §15.2 with \(|F_\mathrm{model}|\) replaced by \(|F_\mathrm{twin}|\), \(D\) and \(\Sigma\) fitted against it (§15.3). At \(\alpha = 0\) it is the untwinned target exactly. It is an approximation: a twinned amplitude is treated as Rice-distributed about \(D|F_\mathrm{twin}|\), while the distribution of a sum of two intensities is narrower; \(\Sigma\), fitted to the free set, absorbs that, and REFMAC5’s twinned-intensity likelihood (Murshudov et al. 2011) is the treatment this one simplifies. The mates \(T\mathbf{h}\) that were not observed are composed as rows of their own, with no observation: their structure factors come from the same transform, so a twinned evaluation costs no extra FFT, only one more kernel per evaluation on the GPU (the twinned term per reflection and the gather of its mates’ derivatives, through the converse of the mate table, as a three-fold of several domains is not an involution).

The fraction, the scale and the solvent are fitted inside the twin sum at every macro-cycle: the scale and the solvent as in §15.3, then \(\alpha\), then the scale and the solvent again against \(F_o\) detwinned by the model as it stands, \(F_o|F_\mathrm{model}(\mathbf{h})|/|F_\mathrm{twin}(\mathbf{h})|\) (at which scale the twinned model meets \(F_o\) as the untwinned one meets the detwinned \(F_o\)), then \(\alpha\) again. \(\alpha \in [0, 1/2]\) comes from the regression of \(F_o^2\), with an intercept, on the model’s intensities at \(\mathbf{h}\) and at \(T\mathbf{h}\), all normalised in resolution shells of 500 reflections: \(\alpha = b_{T\mathbf{h}}/(b_\mathbf{h} + b_{T\mathbf{h}})\), over the working reflections that are not their own mate. The expectation of \(F_o^2\) given the model, \(D^2|F_\mathrm{model}|^2 + \Sigma\), is linear in the two intensities, so an unrelated partner takes a coefficient of 0 however poor the model; a least-squares fit of the twinned amplitudes instead took a fraction of 0.16 for unrelated partners of one model at R-free 0.31, the average of two predictions being a better prediction than either.

The decision. The twinned refinement is kept where its fraction is above 0 and the law beats its own null on the free reflections by at least three standard errors - the null being the same twinned model at the same fraction with every reflection’s mate replaced by an unrelated reflection of the same resolution and of the same set (a free reflection’s by a free one, as a law’s are): what the averaging of two intensities buys whatever they are (it lifts a weak reflection’s model amplitude off zero). The comparison is paired, reflection by reflection, \(|F_o - |F_\mathrm{null}|| - |F_o - |F_\mathrm{twin}||\) over the free set, summed over each free twin pair (the two mates share their two \(F_\mathrm{calc}\), so they are one term, not two independent ones), its mean against its standard error (REFINE_TWIN_NULL_Z). The R-free of the twinned refinement against the untwinned one’s does not enter: two refinements of one model differ in R-free by a few thousandths from their trajectories alone, and any twin target lowers R by its averaging, so that comparison favours the twinned one with or without a twin. A pseudo-symmetry the model already carries (non-crystallographic symmetry parallel to the law) predicts \(I(T\mathbf{h}) \approx I(\mathbf{h})\), so the law changes nothing and is not taken for a twin.

The data’s own evidence. A lead of two to three standard errors is enough where the merge’s intensity statistics read twinned as well - the L-test itself below 0.44 (TWINNING_VERDICT INDICATED with ESTIMATED_TWIN_FRACTION_FROM L_TEST; not where only the second moment reads low, nor where a pseudo-translation leaves the L-test unreadable): two independent pieces of evidence, the data’s and the model’s, then agree. REFINE_TWIN_RULE says which rule decided. The data-side test is not made a gate - it misses twins a model sees, a pseudo-merohedral law or a near-perfect twin among them - only further evidence where the null alone is short. --mode refine has no merge statistics, so there the null alone decides.

The free set is closed under the lattice’s domains before either refinement, so that both use one free set and no law splits a group of twin-related reflections between the working and the free set (REFMAC5 does the same, Roversi et al. 2012). The groups are the orbits of the merged reflections under every domain operator of the lattice (below); an orbit the flags already keep in one set stays there, and a split one goes free with the probability of its own share of free flags, drawn by a hash of the orbit, so the free fraction stays what it was. A majority of each orbit’s flags would empty the free set where the flags were drawn on smaller orbits - a C-centred orthorhombic merge of a hexagonal metric, whose flags (§10.7) are drawn on the orthorhombic holohedry of the cell’s own basis vectors, lost three quarters of it that way. The free set rugnux draws is already closed for every law that is a rotation of the cell’s own basis vectors, and nothing moves; a law of a centred lattice that is not (its matrix fractional in the cell’s basis), or a free set --mode refine reads from a file, can be split, and the closure is what lets such a law be tested at all. REFINE_TWIN_FREE_CLOSED counts the reflections that changed set. A law still split (none is, after the closure, unless its mates fall outside the orbits the data have) is reported (REFINE_TWIN FREE_SET_SPLIT) rather than tested. Of several laws, the one the placed model asks the largest fraction of is refined. Each of the two refinements is a whole one - its solvent built (§15.10) and its displacement model chosen (§15.7) against its own target - and the decision is taken where they ended. --refine-score-only makes the same test on the model as given: it is scored against the data untwinned and twinned by the law, and the twinned score is taken by the same rule.

More than two domains. A lattice can hold more domains than two: a monoclinic crystal on a tetragonal metric four, on a hexagonal one six (Sultana et al. 2007; Roversi et al. 2012). Where the single law is taken and the lattice has more domain operators - every coset of the group in the lattice’s metric symmetry, whatever the operator’s order, three-folds included - a second rung refines every domain at once, each with its own fraction: \(|F_\mathrm{twin}(\mathbf{h})|^2 \propto a_0|U(\mathbf{h})|^2 + \sum_d a_d|U(T_d\mathbf{h})|^2\), \(a_0 = 1 - \sum_d a_d\), the fractions from the same intercept regression with one column per domain, a domain whose coefficient comes out negative taken out and the rest fitted again. It is taken where the added domains beat their own null - the same model with the added domains’ mates replaced by unrelated reflections and the adopted law’s kept - by three standard errors on the free set, summed over each twin group, and each added domain refines to a fraction of 0.05 or more (as REFMAC5 drops small domains, Murshudov et al. 2011); the domains under it are dropped and the rest refined again, and with none left the single law stands. REFINE_TWIN_MULTI (MULTI_TWINNED, MULTI_UNTWINNED) says what was decided, REFINE_TWIN_MULTI_DOMAINS the domains and their fractions; where MULTI_TWINNED, REFINE_TWIN_LAW lists every law and REFINE_TWIN_FRACTION is their sum, and every other REFINE_ key is of that refinement. The rung is not tried where the single law was refused: a twin that only several domains show at once is a symmetric one, whose single-law fraction is already large.

Maps. Against twinned data the map coefficients use \(F_o\) detwinned in proportion to the model’s own share of the twinned intensity, \(F_o|F_\mathrm{model}(\mathbf{h})|/|F_\mathrm{twin}(\mathbf{h})|\), and \(DF_c\) of the model’s own \(|F_\mathrm{model}(\mathbf{h})|\); FP in <prefix>_refined_maps.mtz is the detwinned amplitude.

The keys are REFINE_TWIN (NO_TWIN_LAW, FREE_SET_SPLIT, ZERO_FRACTION, UNTWINNED, TWINNED), REFINE_TWIN_LAW, REFINE_TWIN_FRACTION, REFINE_TWIN_R_WORK/_R_FREE, REFINE_TWIN_R_FREE_NULL, REFINE_TWIN_NULL_Z and REFINE_UNTWINNED_R_WORK/_R_FREE, the last five of the two refinements where they ended. Where REFINE_TWIN is TWINNED, every other REFINE_ key, REFINE_R_FREE_START and the REFINE_SCORE_ terms included, is of the twinned refinement.

15.13 Not yet

What the refinement does not do yet - each a known gap, not a design choice:

  • Custom ligands and other monomer libraries. Only the 84 compounds of §15.4 are restrained. Any other residue is held fixed (it stays in \(F_\mathrm{calc}\), the mask and the repulsions); no restraints are generated for a new ligand, and neither a user’s restraint CIF nor an external monomer library can be given.

  • TLS restraints: a TLS group’s T and L are not held positive semi-definite (only every atom’s total U is kept positive definite); the TLS groups are contiguous segments of one chain, never a domain made of several.

  • Global NCS and NCS of B factors: copies are restrained locally, on their interatomic distances (§15.5), never by a superposition, and their B factors are refined independently; ligands and waters are not restrained between copies.

  • Ion identification beyond the six species: waters and ions are relabelled among water, Mg²⁺, Na⁺, K⁺, Ca²⁺ and Cl⁻ (§15.10); NH₄⁺ is only reported, transition metals (Zn, Mn, …) are measured but never relabelled, and no ion is placed at a peak that is not a water first. A site’s hypotheses are compared by a local fit of its density, not by refining each in turn.

  • Alternative conformations and occupancies: existing conformers are refined in place; no occupancy is refined and no conformer is added.

  • Rotamer and peptide-flip search, and Ramachandran restraints.

  • Real-space refinement, and jelly-body or reference-model restraints.

  • A full Metal (Apple GPU) path: on macOS the model density is gathered on the GPU and the rest of the refinement runs on the CPU.

  • Validation beyond geometry: the report gives the bond and angle rmsd, the metal-bond rmsd and the number of clashes, not a MolProbity-style analysis (Ramachandran, rotamer and clashscore statistics).

References

  • R. C. Agarwal, “A new least-squares refinement technique based on the fast Fourier transform algorithm”, Acta Cryst. A34 (1978), 791-809 (the gradient by the FFT method, §15.2).

  • N. S. Pannu & R. J. Read, “Improved structure refinement through maximum likelihood”, Acta Cryst. A52 (1996), 659-668, and G. N. Murshudov, A. A. Vagin & E. J. Dodson, “Refinement of macromolecular structures by the maximum-likelihood method”, Acta Cryst. D53 (1997), 240-255 (the maximum-likelihood amplitude target and its figure of merit, §15.2, §15.8).

  • G. N. Murshudov, P. Skubák, A. A. Lebedev, N. S. Pannu, R. A. Steiner, R. A. Nicholls, M. D. Winn, F. Long & A. A. Vagin, “REFMAC5 for the refinement of macromolecular crystal structures”, Acta Cryst. D67 (2011), 355-367 (D from the working set and the variance from the free, §15.3; the Kullback-Leibler form of the B restraints, §15.5; the twinned refinement §15.12 simplifies, its twin laws pruned by fraction and its fractions refined by least squares).

  • R. J. Read, “Improved Fourier coefficients for maps using phases from partial structures with errors”, Acta Cryst. A42 (1986), 140-149 (the m, D weighting of the map coefficients, §15.8).

  • T. O. Yeates, “Detecting and overcoming crystal twinning”, Methods Enzymol. 276 (1997), 344-358 (the twinned intensity, §15.12).

  • A. A. Lebedev, A. A. Vagin & G. N. Murshudov, “Intensity statistics in twinned crystals with examples from the PDB”, Acta Cryst. D62 (2006), 83-95 (twin laws from the lattice’s metric, §15.12).

  • R. Herbst-Irmer & G. M. Sheldrick, “Refinement of twinned structures with SHELXL97”, Acta Cryst. B54 (1998), 443-449 (twinned refinement with the fraction refined beside the model, §15.12).

  • V. Y. Lunin & T. P. Skovoroda, “R-free likelihood-based estimates of errors for phases calculated from atomic models”, Acta Cryst. A51 (1995), 880-887, and V. Y. Lunin, P. V. Afonine & A. G. Urzhumtsev, “Likelihood-based refinement. I. Irremovable model errors”, Acta Cryst. A58 (2002), 270-282 (the likelihood’s parameters from the free set, §15.3).

  • J.-S. Jiang & A. T. Brünger, “Protein hydration observed by X-ray diffraction: solvation properties of penicillopepsin and neuraminidase crystal structures”, J. Mol. Biol. 243 (1994), 100-115, and A. Fokine & A. Urzhumtsev, “Flat bulk-solvent model: obtaining optimal parameters”, Acta Cryst. D58 (2002), 1387-1392 (the flat bulk-solvent mask and its parameters, §15.3).

  • P. V. Afonine, R. W. Grosse-Kunstleve & P. D. Adams, “A robust bulk-solvent correction and anisotropic scaling procedure”, Acta Cryst. D61 (2005), 850-855 (the grid search over the solvent parameters, §15.3).

  • P. J. Huber, “Robust estimation of a location parameter”, Ann. Math. Statist. 35 (1964), 73-101, and P. Charbonnier, L. Blanc-Féraud, G. Aubert & M. Barlaud, “Deterministic edge-preserving regularization in computed imaging”, IEEE Trans. Image Process. 6 (1997), 298-311 (the robust scale fit and its smooth, pseudo-Huber loss, §15.3).

  • A. A. Vagin, R. A. Steiner, A. A. Lebedev, L. Potterton, S. McNicholas, F. Long & G. N. Murshudov, “REFMAC5 dictionary: organization of prior chemical knowledge and guidelines for its use”, Acta Cryst. D60 (2004), 2184-2195 (the restraint dictionary, §15.4).

  • M. Wojdyr, “GEMMI: A library for structural biology”, J. Open Source Softw. 7 (2022), 4200 (the topology, the riding hydrogens and the blob search, §15.4, §15.9).

  • V. Schomaker & K. N. Trueblood, Acta Cryst. B24 (1968), 63-76, and M. D. Winn, M. N. Isupov & G. N. Murshudov, Acta Cryst. D57 (2001), 122-133 (TLS, and the B column total or residual to it, §15.1, §15.5); J. Painter & E. A. Merritt, Acta Cryst. D62 (2006), 439-450 (TLSMD’s segments, §15.7).

  • F. L. Hirshfeld, Acta Cryst. A32 (1976), 239-244, A. Thorn, B. Dittrich & G. M. Sheldrick, Acta Cryst. A68 (2012), 448-451, and G. M. Sheldrick, Acta Cryst. C71 (2015), 3-8 (the rigid-bond, similarity and isotropy restraints of anisotropic atoms, §15.5); E. A. Merritt, Acta Cryst. D68 (2012), 468-477 (the displacement model decided by test, §15.7).

  • A. Blondel & M. Karplus, “New formulation for derivatives of torsion angles and improper torsion angles in molecular mechanics: elimination of singularities”, J. Comput. Chem. 17 (1996), 1132-1141 (the torsion derivatives, §15.5).

  • M. M. Harding, “Geometry of metal-ligand interactions in proteins”, Acta Cryst. D57 (2001), 401-411, and “Small revisions to predicted distances around metal sites in proteins”, Acta Cryst. D62 (2006), 678-682; F. Leonarski, L. D’Ascenzo & P. Auffinger, “Mg2+ ions: do they bind to nucleobase nitrogens?”, Nucleic Acids Res. 45 (2017), 987-1004 (the metal-site distances, §15.5).

  • R. W. Grosse-Kunstleve & P. D. Adams, “Algorithms for deriving crystallographic space-group information. II. Treatment of special positions”, Acta Cryst. A58 (2002), 60-65 (the site symmetry and the constraint of an atom on a special position, §15.5).

  • D. T. Cromer & D. A. Liberman, “Anomalous dispersion calculations near to and on the long-wavelength side of an absorption edge”, Acta Cryst. A37 (1981), 267-268, and L. Kissel & R. H. Pratt, “Corrections to tabulated anomalous-scattering factors”, Acta Cryst. A46 (1990), 170-175 (f″ at the data’s wavelength, §15.10).

  • Z. Dauter & M. Dauter, “Entering a new phase: using solvent halide ions in protein structure determination”, Structure 9 (2001), R21-R26 (halides at sites with few donors, §15.10).

  • N. Echols et al., “Automated identification of elemental ions in macromolecular crystal structures”, Acta Cryst. D70 (2014), 1104-1114 (a light ion flagged by its density above the waters’, §15.10).

  • J. Nocedal, “Updating quasi-Newton matrices with limited storage”, Math. Comp. 35 (1980), 773-782, and D. C. Liu & J. Nocedal, “On the limited memory BFGS method for large scale optimization”, Math. Program. 45 (1989), 503-528 (the minimiser, §15.6).

  • A. T. Brünger, M. Karplus & G. A. Petsko, “Crystallographic refinement by simulated annealing: application to crambin”, Acta Cryst. A45 (1989), 50-61 (the starting weight from the ratio of the gradients, §15.7).

  • P. V. Afonine et al., “Towards automated crystallographic structure refinement with phenix.refine”, Acta Cryst. D68 (2012), 352-367 (weights chosen among refinements by R-free within geometry bounds, and the overall B moved into the atoms, §15.3, §15.7).

  • A. T. Brünger, “Free R value: a novel statistical quantity for assessing the accuracy of crystal structures”, Nature 355 (1992), 472-475 (R-free).

  • G. J. Kleywegt, “Use of non-crystallographic symmetry in protein structure refinement”, Acta Cryst. D52 (1996), 842-857; I. Usón, E. Pohl, T. R. Schneider, Z. Dauter, A. Schmidt, H.-J. Fritz & G. M. Sheldrick, “1.7 Å structure of the stabilized REIv mutant T39K. Application of local NCS restraints”, Acta Cryst. D55 (1999), 1158-1167; R. A. Nicholls, F. Long & G. N. Murshudov, “Low-resolution refinement tools in REFMAC5”, Acta Cryst. D68 (2012), 404-417; J. J. Headd et al., “Flexible torsion-angle noncrystallographic symmetry restraints for improved macromolecular structure refinement”, Acta Cryst. D70 (2014), 1346-1356 (local NCS restraints with a robust loss, decided by R-free, and Murshudov et al. 2011 above for the copies found by alignment, §15.5, §15.7).

  • P. Emsley, B. Lohkamp, W. G. Scott & K. Cowtan, “Features and development of Coot”, Acta Cryst. D66 (2010), 486-501 (unmodelled blobs, §15.9).

  • N. Naleem, A. Henning-Knechtel, S. Kirmizialtin & P. Auffinger, “Cat_Wiz: a stereochemistry-guided toolkit for locating, diagnosing, and annotating Mg2+ ions in RNA structures”, Nucleic Acids Res. 54 (2026), gkag120; F. Leonarski, L. D’Ascenzo & P. Auffinger, Nucleic Acids Res. 45 (2017), 987-1004 and RNA 25 (2019), 173-192; F. Leonarski, A. Henning-Knechtel, S. Kirmizialtin, E. Ennifar & P. Auffinger, Nucleic Acids Res. 53 (2025), gkae1148 (the coordination bands, distances and exclusion zone of the solvent audit, §15.10).

  • P. V. Afonine et al., “Towards automated crystallographic structure refinement with phenix.refine”, Acta Cryst. D68 (2012), 352-367, and P. Emsley, B. Lohkamp, W. G. Scott & K. Cowtan, “Features and development of Coot”, Acta Cryst. D66 (2010), 486-501 (the peak cutoff, the partner and clash distances and the resolution limit of the water build, §15.10).

  • N. Echols et al., “Automated identification of elemental ions in macromolecular crystal structures”, Acta Cryst. D70 (2014), 1104-1114, and N. Morshed, N. Echols & P. D. Adams, “Using support vector machines to improve elemental ion identification in macromolecular crystal structures”, Acta Cryst. D71 (2015), 1147-1158 (the ligand sphere and the halide rules, §15.10).

  • H. Zheng et al., “CheckMyMetal: a macromolecular metal-binding validation tool”, Acta Cryst. D73 (2017), 223-233 (the vector sum, §15.10); O. Carugo, “Buried chloride stereochemistry in the Protein Data Bank”, BMC Struct. Biol. 14 (2014), 19 (the chloride’s shell, §15.10).

  • I. D. Brown & D. Altermatt, Acta Cryst. B41 (1985), 244-247, and N. E. Brese & M. O’Keeffe, “Bond-valence parameters for solids”, Acta Cryst. B47 (1991), 192-197 (the bond-valence sums, §15.10).

  • M. Abramowitz & I. A. Stegun, Handbook of Mathematical Functions, National Bureau of Standards (1964), 9.8.1-9.8.4 (the Bessel functions of the target, §15.2).

The full citations, with DOIs, are in ACKNOWLEDGEMENT.md.

\ No newline at end of file diff --git a/DEPLOYMENT.html b/DEPLOYMENT.html new file mode 100644 index 000000000..39fc1dd0e --- /dev/null +++ b/DEPLOYMENT.html @@ -0,0 +1,43 @@ + Deployment — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Deployment

To deploy Jungfraujoch, one needs to follow these steps:

  1. Install main Jungfraujoch code and frontend web interface

  2. Flash the U55C FPGA card with a proper image and install Linux kernel driver

  3. Install Jungfraujoch writer

  4. Install Jungfraujoch image viewer (optional)

  5. Install Python OpenAPI client

rugnux, the offline analysis tool, is installed separately and independently of all of them — see Install Rugnux at the end of this page.

The installation procedure depends a lot on the operating system. For Red Hat Enterprise Linux 8/9, Rocky 8/9, Ubuntu 22.04/24.04 or compatible, installation can be done with prebuilt packages from the package repositories and is relatively straightforward. For other systems one needs to build software from source. Both ways will be presented. What each released package contains, and what it needs on the machine, is described in Release contents.

Install main Jungfraujoch code and frontend web interface

On RHEL 8/9 and Ubuntu systems the prebuilt jfjoch package from the repositories contains all the necessary software and the web interface.

On other OSes one needs to compile Jungfraujoch from source (from the repo directory):

$ mkdir build
+$ cd build
+$ cmake .. -DCMAKE_INSTALL_PREFIX=<directory to install>
+$ make
+$ sudo make install  
+

For manual installation, we recommend using a non-standard directory (like /opt/jfjoch), to facilitate upgrades and removal. For DKMS to manage kernel module sources it is necessary to copy driver sources to /usr/src/jfjoch-<VERSION> directory. This requires an extra CMake flag -DJFJOCH_INSTALL_DRIVER_SOURCE=ON.

Frontend web user interface has to be built separately with:

$ cd build
+$ make frontend
+

Frontend files (.html and .js) are placed in frontend/dist (outside of build/ directory!); make install copies that directory to <prefix>/share/jfjoch/frontend (default prefix /opt/jfjoch), and the broker serves whatever directory the frontend_directory of its configuration names.

Flash the U55C FPGA card with a proper image and install Linux kernel driver

Firmware flashing

  1. Check that the card is detected by OS with “lspci |grep Xilinx” and check the PCIe bus/device/function (BDF) number, 23:00.0 in this case:

$ lspci |grep Xilinx
+23:00.0 Processing accelerators: Xilinx Corporation Device 3450 (rev 2)
+

Note the device number 3450 that identifies Jungfraujoch device (Jungfraujoch pass is 3450 m above sea level) and rev 2 identifying release of the firmware.

  1. Check the speed of the card, that it is detected as PCIe Gen4x8 device (needs to be done as root, otherwise configuration details are not given):

$ sudo lspci -vv -s <PCIe slot number>
+23:00.0 Processing accelerators: Xilinx Corporation Device 3450
+(...)
+LnkSta:     Speed 16GT/s (ok), Width x8 (ok)
+(...)
+
  1. Download the MCS image from release files or build it using Vivado (WARNING! building time can be about 8 hours and doesn’t always reach correct timing).

  2. Flash the card with xbflash.qspi tool (part of Jungfraujoch). For fresh card use:

sudo xbflash.qspi --primary <path to MCS file> --card <PCIe slot from above> --bar-offset 0x1f06000 
+

For card that was already flashed with Jungfraujoch images:

sudo xbflash.qspi --primary <path to MCS file> --card <PCIe slot from above>
+

It is necessary to confirm the operation by pressing Y key or one can add --force option to avoid confirmation. It is safe to run multiple flashing processes in parallel for different cards, for example in separate screen sessions.

  1. Cold reboot:

sudo ipmitool chassis power cycle
+

Install PCIe driver

For the first run it is recommended to try the driver without installing it into the kernel directory:

$ cd fpga/pcie_driver
+$ make
+$ sudo insmod jfjoch.ko
+

Check with dmesg that the device was properly found:

$ dmesg |grep jfjoch
+[  431.624933] jfjoch 0000:23:00.0: enabling device (0140 -> 0142)
+[  431.919147] misc jfjoch0: Jungfraujoch FPGA loaded with FW build: 5610030a
+

If things work, it is recommended to install the driver with DKMS, so it is rebuilt for kernel updates. Install the prebuilt jfjoch-driver-dkms package from the Gitea package registry; on other systems follow the procedure in PCIe driver.

DKMS builds the module for the kernel it is being installed for rather than the running one, so a module built during a kernel update loads correctly after the reboot.

NOTE: In case the driver is included in the init RAM-disk image, it is necessary to rebuild the RAM-disk when the driver is updated:

$ sudo dracut -f
+

Configure network

Configure switch according to FPGA network guide - specifically set manual speed and turn off auto-negotiation for the port used to connect U55C card and connect card to switch.

Running Jungfraujoch software

Main Jungfraujoch service is called jfjoch_broker. It is responsible for handling data from FPGAs, doing processing, analysis, compression and sending images on ZeroMQ output. It is recommended to run the service as systemd service.

jfjoch_broker takes a JSON configuration file and, optionally, the HTTP port (default 5232). Example JSON files are placed in etc/ folder. JSON file format is also explained in the OpenAPI definition, as jfjoch_settings data structure.

When running the service can be accessed via HTTP interface from a web browser for configuration and monitoring.

Jungfraujoch automatically uses every GPU visible to the process and spreads the per-image work across all of them. To run more than one jfjoch_broker on a single machine, each confined to a disjoint subset of GPUs, set CUDA_VISIBLE_DEVICES; setting CUDA_DEVICE_ORDER=PCI_BUS_ID keeps the GPU indices stable across reboots. For example, two brokers on a 4-GPU host:

CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=0,1 jfjoch_broker broker_a.json 5232
+CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=2,3 jfjoch_broker broker_b.json 5233
+

To prepare the configuration file one also needs to reference calibration files: gain files for PSI JUNGFRAU and trim-bit files for PSI EIGER. These need to be obtained from the PSI Detector Group.

Card verification

To test that the FPGA board is working properly without access to a JUNGFRAU detector, you can use jfjoch_fpga_test tool. For example, to simulate a 10M pixel system with 4 FPGA cards and 200k images:

jfjoch_fpga_test ~/nextgendcu/ -m20 -s4 -i 200000
+

Or a 1M pixel system with one FPGA card:

jfjoch_fpga_test ~/nextgendcu/ -m2 -s1 -i 200000
+

Install Jungfraujoch writer

Jungfraujoch writer is an additional service that connects to the jfjoch_broker ZeroMQ interface and writes files according to NeXus/NXmx HDF5 standard.

At the moment it is better to have a separate machine, with access to a distributed file system, for writing images.

Writer can be installed with a dedicated RPM file or compiled from source. For compilation, you can use the following commands:

mkdir build
+cd build
+cmake -DJFJOCH_WRITER_ONLY=ON -DCMAKE_INSTALL_PREFIX=<directory to install> ..
+make jfjoch_writer
+

Install Jungfraujoch image viewer

The Jungfraujoch viewer is an X-ray diffraction image viewer optimized to open Jungfraujoch HDF5 files.

The viewer is a Qt application and it requires a recent version of the library, therefore it is an optional dependency.

To include it in the building of Jungfraujoch use -DJFJOCH_VIEWER_BUILD=ON directive for CMake:

mkdir build
+cd build
+cmake -DJFJOCH_VIEWER_BUILD=ON -DCMAKE_INSTALL_PREFIX=<directory to install> ..
+make jfjoch_viewer
+

Pre-built viewers for Windows and macOS, and a portable Linux archive, are on the download page — see Release contents and jfjoch_viewer.

Install Jungfraujoch Python client

Use pip:

pip install jfjoch-client
+

Install Rugnux (offline analysis)

rugnux is not part of the server stack and is installed independently of all of the above. It needs neither the broker, the writer, Qt nor a CUDA toolkit — only an NVIDIA driver if you want to use the GPU — and it does not have to run on the acquisition machine at all.

From the package repositories:

sudo dnf install rugnux          # RHEL / Rocky
+sudo apt install rugnux          # Ubuntu
+

Or, on a machine no repository covers, from the standalone archive:

mkdir -p /opt/rugnux-<version>
+tar xzf rugnux-<version>-linux-x86_64-cuda12.tgz -C /opt/rugnux-<version>
+/opt/rugnux-<version>/bin/rugnux
+

The archive has no top-level directory, so the -C is required. See Installing Rugnux for the Arm, Windows and macOS archives, the driver versions and building from source.

\ No newline at end of file diff --git a/DETECTORS.html b/DETECTORS.html new file mode 100644 index 000000000..02f77e0e9 --- /dev/null +++ b/DETECTORS.html @@ -0,0 +1 @@ + Supported detectors — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Supported detectors

PSI detectors

Jungfraujoch supports PSI JUNGFRAU and PSI EIGER detectors. Jungfraujoch controls the detector via slsDetectorPackage, which is statically compiled into its source code. The detector firmware must match the slsDetectorPackage version used in Jungfraujoch. The default is 8.0.2; 9.2.0 is built with the SLS9=ON CMake option and published in the slsdet9 package repositories. See PSI Detector group website for details.

DECTRIS detectors

Jungfraujoch can be used with DECTRIS detectors, as a data analysis tool. In this solution Jungfraujoch controls the Detector Control Unit (DCU) of the detector, and handles the output data stream of the DCU. This mode, called “lite” mode, doesn’t use FPGA boards, but mostly CPUs and GPUs for indexing. The mode is currently experimental and intended for low data rates (100 Hz).

\ No newline at end of file diff --git a/DETECTOR_GEOMETRY.html b/DETECTOR_GEOMETRY.html new file mode 100644 index 000000000..74272c8dc --- /dev/null +++ b/DETECTOR_GEOMETRY.html @@ -0,0 +1,2 @@ + Detector geometry — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Detector geometry

At the moment Jungfraujoch supports solely flat detectors. The default option is to place modules in their actual location relative to the detector frame. It is not recommended to place detector modules stacked.

The simplest case is a detector perpendicular to the beam. In this case it is enough to provide beam center, detector distance and wavelength.

For a more complex case, one can provide the detector tilt in the PyFAI convention. This convention uses Point Of Nominal Interaction (PONI) definition. Beam X and Y would correspond to the location on the detector, where beam from the sample is perpendicular to the detector surface and not to the actual direct beam location. Then tilt of the detector is defined with three rotation angles: rot1 (rotating detector right), rot2 (rotating detector downwards), rot3 (rotating detector clockwise). See PyFAI documentation for more details.

What a pixel coordinate means: (0, 0) is the centre of the first pixel

Pixel coordinates in Jungfraujoch and Rugnux are 0-based and pixel-centred: an integer coordinate is the centre of that pixel, so pixel i covers [i − 0.5, i + 0.5) and the sensor spans −0.5 … width − 0.5. A beam centre of 948.0 × 546.0 sits in the middle of pixel [546][948], not on any of its corners; 948.5 is the boundary between pixel 948 and 949.

This holds throughout the code: spot and reflection centroids are intensity-weighted sums of the integer pixel indices, the resolution and azimuthal-bin maps evaluate pixel (col, row) at exactly (col, row), and a fractional coordinate is turned back into a pixel index by rounding, not by truncation. The same convention applies to every coordinate the system exposes — the beam centre (beam_x_pxl/beam_y_pxl in the API and broker configuration, --beam-x/--beam-y in Rugnux, beam_center_x/beam_center_y in NXmx and in the CBOR stream), the spot and predicted-reflection positions written to HDF5, and the PONI reported by --mode calibration.

Other programs place the origin differently, and the difference is worth half a pixel — enough to matter when a geometry is copied between programs and then refined:

Convention

Beam centre equivalent to our x = 948.0

Jungfraujoch, Rugnux

948.0

XDS (ORGX/ORGY)

949.0 — also pixel-centred, but pixels are numbered from 1

Measured from the edge of the sensor, in length units — pyFAI (Poni2, fast axis), DIALS/dxtbx

(948.0 + 0.5) × pixel size, because the centre of pixel i is at (i + 0.5) × pixel size from the edge

pyFAI Poni1 (slow axis)

(height − 1 − y + 0.5) × pixel size — pyFAI measures the slow axis from the opposite edge, and the .poni declares orientation: 2 to say so

The .poni file written by rugnux --mode calibration is in pyFAI’s frame and so already carries that half pixel; the pixel values the same run reports are ours. Rot3 in that file is our rot3 negated and turned by 180°: the half turn sets the azimuthal reference, because pyFAI’s in-plane axes are the negatives of ours. It leaves 2θ untouched, so it moves only the azimuth.

Inside: two axis vectors; outside: rot1/rot2/rot3

Internally the detector plane is one orthogonal matrix whose columns are the fast axis (the laboratory direction of a +1 column step), the slow axis (+1 row step) and the normal (the sample→PONI direction). Every geometry calculation — resolution, azimuth, polarization, prediction, refinement — is that matrix applied to the offset of a pixel from the PONI.

rot1/rot2/rot3 remain the way the tilt is stated from outside, and the two views convert both ways: R = Rz(-rot3)·Rx(-rot2)·Ry(+rot1) in the internal frame, and back from the columns as

rot2 = asin(-slow.z)         rot1 = atan2(-fast.z, normal.z)         rot3 = atan2(slow.x, slow.y)
+

with rot2 in [-90°, 90°]. The angles are what is stored and what is written out, so a geometry given as angles comes back exactly as it was given.

What a miniCBF header states about the mounting

A PILATUS miniCBF gives the geometry twice. The # lines every writer produces carry the distance, the beam centre and the angles; some beamlines then append a CBF template block holding a full imgCIF axis table, which states the laboratory direction of the image’s fast and slow pixel directions, of the base goniometer axis, and of a 2theta arm where there is one. Where that table is present it is read, in preference to any assumption - it is the same information NXmx puts in fast_pixel_direction / slow_pixel_direction and the goniometer vector, in the form this format states it.

imgCIF’s laboratory frame has Z from the sample towards the source and Y opposite gravity, so it differs from the internal frame by a half turn about x - a rotation, not a mirror, so an axis carried through it turns the same way by the same angle.

There are two things a header can state that an assumption gets wrong by 90 degrees — an error no refinement recovers, and one the run’s axis-sign rescue cannot reach either, a quarter turn not being a sign:

  • the image mounted a quarter turn round, so its columns run vertically;

  • a spindle that turns about the vertical rather than the horizontal.

Where a header carries no axis table, a +SLOW on its # Oscillation_axis line still says the spindle runs along the image’s slow direction rather than its fast one. The axis name on that line is not usable - one header says X.CW +SLOW where its own table says the axis is Y - but the direction token is, and on the header that states both they agree.

A detector swung out on a 2theta arm

Chemical crystallography reaches high angle by swinging the detector out on a 2theta arm rather than by moving it closer. The arm turns the detector about the sample, so it changes nothing else: the distance is still measured along the detector normal, and the beam centre is still the point of normal incidence, which is where the arm’s own axis meets the detector and does not move. The swing is therefore exactly a PONI rotation, and the direct beam is what moves - by distance * tan(2theta), off the beam centre and often off the detector altogether.

Nothing has to be given for this: Rugnux takes it from the file. An NXmx master states the detector’s position as a depends_on chain of transformations, and the arm is one rotation in that chain - so the chain is followed, rather than a field of one particular name being looked for. A PILATUS miniCBF states it as # Detector_2theta, which turns about the same axis as the base spindle, the two being one axis on the four-circle geometry those headers describe.

Mirrored and quarter-turned detectors

On top of the continuous tilt the detector setup carries a discrete image orientation: whether the stored image is mirrored in Y, and how many multiples of 90° about the beam it is turned by. It is applied to the offset from the PONI before the tilt.

The distinction matters because these two operations are exact pixel remappings — an image can be shown the right way up without resampling anything — while an arbitrary in-plane rotation cannot. rot3 is therefore reserved for the genuinely arbitrary part: an in-plane angle is never decomposed into a quarter turn plus a residual, and the discrete part is set only where something states it (the detector configuration, --detector-mirror-y / --detector-quarter-turns, or the value a Jungfraujoch-written file records).

Both operations leave the distance from the PONI unchanged, so resolution, the solid-angle correction and anything else that needs only a radius are unaffected by them. Polarization is affected, and correctly so: it is computed from the azimuth in the laboratory, and what these operations change is which pixel index lands at which laboratory azimuth.

This is a different setting from mirror_y in the JSON configuration file (described below), which flips the module layout while the image is being assembled and so decides what the stored pixels are. The discrete image orientation changes no pixel at all.

Macromolecular crystallography convention for the vertical direction

One place of confusion is the convention to have point (0,0) of the detector in the top left corner of the detector, with Y values increasing downwards. This is also consistent with computer image formats.

However, other techniques (as well as internal operation of PSI X-ray detectors) might follow a convention where point (0,0) is in the bottom left corner and Y values increase upwards. Such a convention is used, for example, by PyFAI.

In general, the convention is controlled in Jungfraujoch with a setting in the JSON configuration file, which allows the detector to be mirrored in Y.

The convention in use is worth checking whenever a geometry is carried between programs.

\ No newline at end of file diff --git a/EXTERNAL_TEST_DATA.html b/EXTERNAL_TEST_DATA.html new file mode 100644 index 000000000..18f66066d --- /dev/null +++ b/EXTERNAL_TEST_DATA.html @@ -0,0 +1 @@ + External test data — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

External test data

Jungfraujoch is developed at the Swiss Light Source, but a data-reduction pipeline that only ever sees its own detectors is not tested. The datasets below were collected by other people, on detectors and in file formats we do not produce ourselves, and are used here to check that rugnux reads foreign files correctly and reduces them to sensible results. Most were collected at other facilities, thirteen on laboratory X-ray sources; a few come from SLS beamlines, where the data are still written by someone else’s detector and someone else’s acquisition system. Their authors published all of these for exactly this kind of reuse, and this page is where we credit them.

None of these data were collected by us. If you use any of them, cite the dataset DOI in the table below; the repositories themselves are cited in ACKNOWLEDGEMENT.

This page lists the rotation datasets. The serial (XFEL stills) datasets of the still battery are on External test data: serial crystallography.

The pan-facility test of the Rugnux paper is this collection as it stood for the paper’s battery run: 207 datasets, 201 of deposited PDB entries and six chemical-crystallography sets, from 26 synchrotrons and 10 laboratory sources. Datasets added since are listed here as well, so the counts on this page run a little higher than the paper’s.

Where the values come from

  • Source is the repository we downloaded from and that repository’s own citable DOI for the archive we took. Every DOI on this page was resolved before it was written down - against DataCite, which registers most of them; 6NEN’s DOI is registered with Crossref and the five XRDa DOIs with JaLC, and those were resolved through doi.org - and the identity of each dataset was taken from the repository’s record for the archive - not from our directory names.

  • Beamline, resolution, space group, cell and title are the values deposited with the PDB entry, read from the RCSB data API; the resolution is the entry’s refinement resolution (resolution_combined). They describe the published experiment. They are not our reprocessing results; no quantity measured by Jungfraujoch appears in the table.

  • Detector is read out of the image files themselves - the NXmx /entry/instrument/detector/description, the miniCBF # Detector: header, the marCCD instrument header or the SMV key block - which is authoritative where the PDB entry names a different detector.

  • Anything that could not be established from one of those sources is left blank.

  • Every row of the table is a row of the battery’s open arm (tools/battery/open.json) unless it is listed under Datasets in the table that are not in the battery, and every row of the open arm is in the table or under Datasets with no PDB entry. The manifest keeps the deposited values at full precision; tools/battery/doc_check.py checks that the two agree.

Datasets

PDB

Source

Facility / beamline

dmin (Å)

Space group

Unit cell a b c α β γ (Å, °)

Detector (from file)

Title

11IF

IRRMC 10.18430/M311IF

NSLS-II 19-ID

1.51

P 43

51.1 51.1 71.9 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal Structure of an exported phospholipid binding protein from Bordetella pertussis in complex with Di-palmitoyl-3-sn-phosphatidylethanolamine (DPPE), P43 form 2

2WNN

Zenodo 10.5281/zenodo.54568

Diamond I03

1.65

P 1 21 1

54.7 142.5 83.6 90.0 109.2 90.0

SMV, S/N 920

Structure of wild type E. coli N-acetylneuraminic acid lyase in complex with pyruvate in space group P21

2WNQ

Zenodo 10.5281/zenodo.54568

Diamond I04

1.80

P 1 21 1

54.6 142.8 84.5 90.0 109.0 90.0

SMV, S/N 921

Structure of the E192N mutant of E. coli N-acetylneuraminic acid lyase in space group P21

2WNZ

Zenodo 10.5281/zenodo.54568

Diamond I02

1.85

P 1 21 1

56.9 143.0 83.9 90.0 109.8 90.0

SMV, S/N 922

Structure of the E192N mutant of E. coli N-acetylneuraminic acid lyase in complex with pyruvate in space group P21 crystal form I

2XFW

Zenodo 10.5281/zenodo.54568

Diamond I02

1.65

P 1 21 1

78.1 116.5 83.7 90.0 118.0 90.0

SMV, S/N 922

Structure of the E192N mutant of E. coli N-acetylneuraminic acid lyase in complex with pyruvate in crystal form III

36GK

IRRMC 10.18430/M336GK

CLSI 08ID-1

2.28

I 2 2 2

120.6 189.5 199.7 90.0 90.0 90.0

Dectris Eiger 9M

D-GlcNAc-bound structure of Vibrio vulnificus putative carbohydrate binding module and split domain

3INP

IRRMC 10.18430/m33inp

APS 21-ID-F

2.05

F 41 3 2

224.1 224.1 224.1 90.0 90.0 90.0

marCCD, 225 mm plate

2.05 Angstrom Resolution Crystal Structure of D-ribulose-phosphate 3-epimerase from Francisella tularensis.

3KY7

IRRMC 10.18430/m33ky7

APS 21-ID-G

2.35

P 43 3 2

125.2 125.2 125.2 90.0 90.0 90.0

marCCD, 300 mm plate

2.35 Angstrom resolution crystal structure of a putative tRNA (guanine-7-)-methyltransferase (trmD) from Staphylococcus aureus subsp. aureus MRSA252

3MC4

IRRMC 10.18430/M33MC4

Home source, Rigaku MicroMax-007 HF

1.95

H 3

104.0 104.0 105.5 90.0 90.0 120.0

Rigaku Saturn 944+

Crystal structure of WW/RSP5/WWP domain: bacterial transferase hexapeptide repeat: serine O-Acetyltransferase from Brucella Melitensis

3MEB

IRRMC 10.18430/M33MEB

Home source, Rigaku MicroMax-007 HF

1.90

P 1 21 1

58.6 101.2 81.5 90.0 90.6 90.0

Rigaku Saturn 944

Structure of cytoplasmic aspartate aminotransferase from giardia lamblia

3P85

IRRMC 10.18430/M33P85

Home source, Rigaku FR-E+ SuperBright

1.90

P 63 2 2

127.3 127.3 72.9 90.0 90.0 120.0

Rigaku Saturn 944+

Crystal structure enoyl-coa hydratase from mycobacterium avium

3R6O

IRRMC 10.18430/M33R6O

Home source, Rigaku FR-E+ SuperBright

1.95

I 41

90.7 90.7 76.1 90.0 90.0 90.0

Rigaku Saturn 944+

Crystal structure of a probable 2-hydroxyhepta-2,4-diene-1, 7-dioateisomerase from Mycobacterium abscessus

4BWL

Zenodo 10.5281/zenodo.54568

Diamond I02

2.00

P 1 21 1

56.0 143.2 83.4 90.0 109.5 90.0

SMV, S/N 922

Structure of the Y137A mutant of E. coli N-acetylneuraminic acid lyase in complex with pyruvate, N-acetyl-D-mannosamine and N- acetylneuraminic acid

4MTK

SBGrid 10.15785/sbgrid/235

SLS X06SA

3.32

P 61

168.3 168.3 652.8 90.0 90.0 120.0

PILATUS 6M

Crystal structure of PA0091 VgrG1, the central spike of the Type VI Secretion System

4NWV

SBGrid 10.15785/sbgrid/9

APS 21-ID-D

3.25

I 2 2 2

402.2 369.9 410.5 90.0 90.0 90.0

Rayonix MX-300

Crystal structure of Orsay virus-like particle

4P8R

IRRMC 10.18430/m34p8r

APS 21-ID-F

2.20

P 65 2 2

86.7 86.7 701.4 90.0 90.0 120.0

Rayonix MX-225

Structure of a glycosomal glyceraldehyde 3-phosphate dehydrogenase from Trypanosoma brucei

5CC8

IRRMC 10.18430/M35CC8

Home source, Rigaku MicroMax-007 HF

1.75

P 21 21 2

87.1 93.8 72.5 90.0 90.0 90.0

Rigaku Saturn 944+

Structure of thiamine-monophosphate kinase from Acinetobacter baumannii in complex with AMPPNP

5EBI

MXRDR 10.18150/9887707

BESSY 14.2

1.09

P 1 21 1

35.7 44.1 35.7 90.0 120.0 90.0

marCCD, 225 mm plate

Crystal structure of a DNA-RNA chimera in complex with Ba2+ ions: a case of unusual multi-domain twinning

5EPE

IRRMC 10.18430/m3159c

APS 21-ID-G

1.90

F 2 3

157.5 157.5 157.5 90.0 90.0 90.0

Rayonix MX-300

Crystal structure of SAM-dependent methyltransferase from Thiobacillus denitrificans in complex with S-Adenosyl-L-homocysteine

5F6M

SBGrid 10.15785/sbgrid/201

SSRL BL11-1

1.10

P 21 21 21

54.8 58.5 67.4 90.0 90.0 90.0

PILATUS 6M

Isotropic Trypsin Model for Comparison of Diffuse Scattering

5J23

IRRMC 10.18430/M35J23

APS 21-ID-G

2.30

H 3

175.8 175.8 136.8 90.0 90.0 120.0

Rayonix MX-300

Crystal structure of NADPH-dependent glyoxylate/hydroxypyruvate reductase SMc04462 (SmGhrB) from Sinorhizobium meliloti in complex with 2’-phospho-ADP-ribose

5JK4

Zenodo 10.5281/zenodo.49859

ESRF ID14-2

1.10

P 1 21 1

37.7 77.9 56.3 90.0 102.1 90.0

ADSC Quantum 4

Phosphate-Binding Protein from Stenotrophomonas maltophilia.

5JVN

IRRMC 10.18430/m35jvn

ESRF ID29

2.90

P 6 2 2

249.4 249.4 84.1 90.0 90.0 120.0

PILATUS3 6M

C3-type pyruvate phosphate dikinase: intermediate state of the central domain in the swiveling mechanism

5KY6

MXRDR 10.18150/repod.1494374

BESSY 14.2

1.94

P 1 21 1

84.5 57.3 164.0 90.0 102.6 90.0

marCCD, 225 mm plate

Human muscle fructose-1,6-bisphosphate aldolase

5LZL

Zenodo 10.5281/zenodo.54757

Diamond I02

3.47

P 31 2 1

205.6 205.6 199.2 90.0 90.0 120.0

PILATUS 6M-F

Pyrobaculum calidifontis 5-aminolaevulinic acid dehydratase

5M17

Zenodo 10.5281/zenodo.4300323

Diamond I02

1.03

I 4

108.6 108.6 67.7 90.0 90.0 90.0

PILATUS 6M-F

Structure of the GH99 endo-alpha-mannanase from Bacteroides xylanisolvens in complex with mannose-alpha-1,3-1,2-dideoxymannose

5MLN

IRRMC 10.18430/m35mln

ESRF ID23-2

1.60

P 21 2 21

74.2 80.4 80.5 90.0 90.0 90.0

PILATUS3 2M

The crystal structure of alcohol dehydrogenase 10 from Candida magnoliae

5NW5

SBGrid 10.15785/sbgrid/446

SLS X06DA

6.50

P 21 21 21

92.1 169.8 390.2 90.0 90.0 90.0

PILATUS 2MF

Crystal structure of the Rif1 N-terminal domain (RIF1-NTD) from Saccharomyces cerevisiae in complex with DNA

5OJV

SBGrid 10.15785/sbgrid/475

ESRF ID30B

2.06

P 21 21 2

87.8 158.2 87.6 90.0 90.0 90.0

PILATUS 6M

Crystal structure of Mycolicibacterium hassiacum glucosylglycerate hydrolase (MhGgH) E419A variant in complex with mannosylglycerate

5REO

Zenodo 10.5281/zenodo.3730956

Diamond I04-1

1.88

C 1 2 1

112.4 52.6 44.4 90.0 103.0 90.0

PILATUS 6M-F

PanDDA analysis group deposition – Crystal Structure of SARS-CoV-2 main protease in complex with PCM-0102578

5SRC

IRRMC 10.18430/M35SRC

ALS 8.3.1

1.05

P 43

88.7 88.7 39.2 90.0 90.0 90.0

PILATUS3 6M

PanDDA analysis group deposition – Crystal structure of SARS-CoV-2 NSP3 macrodomain in complex with Z5198562500 - (R,R) and (R,S) isomers

5T39

SBGrid 10.15785/sbgrid/356

APS 21-ID-F

1.10

P 1 21 1

50.2 41.3 58.5 90.0 98.6 90.0

Rayonix MX-300

Crystal Structure of the N-terminal domain of EvdMO1 in the presence of SAH and D-fucose

5UTH

IRRMC 10.18430/M35UTH

Home source, Rigaku FR-E+ SuperBright

1.95

P 31 2 1

69.3 69.3 153.8 90.0 90.0 120.0

Rigaku Saturn 944+

Crystal structure of thioredoxin reductase from Mycobacterium smegmatis in complex with FAD

5VML

IRRMC 10.18430/M35VML

Home source, Rigaku FR-E+ SuperBright

1.70

P 42 21 2

66.3 66.3 115.3 90.0 90.0 90.0

Rigaku Saturn 944+

Crystal Structure of Acetoacetyl-CoA Reductase from Burkholderia Pseudomallei 1710b with bound NADP

6CDL

IRRMC 10.18430/m36cdl

APS 22-ID

1.25

P 21 21 2

58.3 85.9 46.1 90.0 90.0 90.0

marCCD, 300 mm plate

HIV-1 wild type protease with GRL-03214A, 6-5-5-ring fused umbrella-like tetrahydropyranofuran as the P2-ligand, a cyclopropylaminobenzothiazole as the P2’-ligand and 3,5-difluorophenylmethyl as the P1-ligand

6CEE

IRRMC 10.18430/M36CEE

Home source, Rigaku FR-E SuperBright

1.55

P 21 21 21

40.7 44.1 55.9 90.0 90.0 90.0

Rigaku Saturn A200

Crystal structure of fragment 3-(1-Methyl-2-oxo-1,2-dihydroquinoxalin-3-yl)propionic acid bound in the ubiquitin binding pocket of the HDAC6 zinc-finger domain

6CS9

SBGrid 10.15785/SBGRID/568

Australian Synchrotron MX2

1.85

P 1 21 1

32.9 25.5 40.2 90.0 98.6 90.0

ADSC Quantum 210r

Crystal structure of human beta-defensin 2 in complex with PIP2

6F3P

IRRMC 10.18430/M36F3P

APS 22-ID

1.35

C 1 2 1

142.9 85.7 112.0 90.0 122.2 90.0

marCCD, 300 mm plate

Crystal structure of S-adenosyl-L-homocysteine hydrolase from Pseudomonas aeruginosa in complex with 3’-deoxyadenosine and K+ cation

6FID

SBGrid 10.15785/sbgrid/541

ESRF ID30B

2.20

P 21 21 21

59.9 64.1 69.7 90.0 90.0 90.0

PILATUS3 6M

Bovine trypsin solved by S-SAD on ID30B

6FVZ

IRRMC 10.18430/m36fvz

ESRF ID23-2

1.80

C 2 2 2

131.2 222.8 86.5 90.0 90.0 90.0

PILATUS3 X 2M

Crystal structure of human monoamine oxidase B (MAO B) in complex with dimethylphenyl-chromone-carboxamide

6FWC

IRRMC 10.18430/m36fwc

ESRF MASSIF-3

1.70

C 2 2 2

131.7 222.1 86.3 90.0 90.0 90.0

PILATUS 2MF

Crystal structure of human monoamine oxidase B (MAO B) in complex with fluorophenyl-chromone-carboxamide

6G1F

Zenodo 10.5281/zenodo.1059413

Diamond I03

2.25

C 1 2 1

329.3 83.9 133.4 90.0 111.6 90.0

PILATUS3 6M

Crystal structure of D-phenylglycine aninotransferase (D-PhgAT) from Pseudomonas stutzeri with PLP internal aldimine

6GVK

Zenodo 10.5281/zenodo.1286854

ALBA XALOC

1.55

C 1 2 1

105.6 59.5 42.4 90.0 113.5 90.0

PILATUS 6M

Second pair of Fibronectin type III domains of integrin beta4 (T1663R mutant) bound to the bullous pemphigoid antigen BP230 (BPAG1e)

6H2P

IRRMC 10.18430/m36h2p

BESSY 14.1

1.48

C 2 2 21

103.5 107.1 216.5 90.0 90.0 90.0

PILATUS 6M

Crystal Structure of Arg184Gln mutant of Human Prolidase with Mn ions and Cacodylate ligand

6H5T

IRRMC 10.18430/m36h5t

BESSY 14.3

1.69

I 4 2 2

86.8 86.8 141.8 90.0 90.0 90.0

marCCD, 225 mm plate

Intersectin SH3A short isoform

6HV2

IRRMC 10.18430/m36hv2

SLS X06SA

1.71

P 61 2 2

68.9 68.9 133.6 90.0 90.0 120.0

Dectris Eiger 16M

MMP-13 in complex with the peptide IMISF

6HWJ

SBGrid 10.15785/sbgrid/614

ALBA XALOC

1.98

P 1 21 1

59.8 96.1 80.3 90.0 106.7 90.0

PILATUS 6M

Glucosamine kinase (crystal form A)

6I3J

IRRMC 10.18430/m36i3j

BESSY 14.1

2.59

F 2 2 2

134.4 203.8 226.7 90.0 90.0 90.0

marCCD, 225 mm plate

Bilirubin oxidase from Myrothecium verrucaria in complex with ferricyanide

6IU5

Zenodo 10.5281/zenodo.2532134

SPring-8 BL41XU

2.25

P 31

84.9 84.9 98.2 90.0 90.0 120.0

PILATUS3 6M

Crystal structure of cytoplasmic metal binding domain with zinc ions

6IU6

Zenodo 10.5281/zenodo.2532134

SPring-8 BL41XU

2.90

P 31

84.7 84.7 97.4 90.0 90.0 120.0

PILATUS3 6M

Crystal structure of cytoplasmic metal binding domain with nickel ions

6IU8

Zenodo 10.5281/zenodo.2532134

SPring-8 BL41XU

2.70

P 31

85.5 85.5 98.4 90.0 90.0 120.0

PILATUS3 6M

Crystal structure of cytoplasmic metal binding domain with cobalt ions

6IU9

Zenodo 10.5281/zenodo.2532134

SPring-8 BL41XU

3.00

P 31

85.3 85.3 97.6 90.0 90.0 120.0

PILATUS3 6M

Crystal structure of cytoplasmic metal binding domain with iron ions

6JGH

IRRMC 10.18430/m36jgh

SPring-8 BL44XU

0.94

P 21 21 21

50.6 62.5 68.2 90.0 90.0 90.0

marCCD, 300 mm plate

Crystal structure of the F99S/M153T/V163A/T203I variant of GFP at 0.94 A

6JGI

IRRMC 10.18430/m36jgi

SPring-8 BL44XU

0.85

P 21 21 21

50.9 62.4 69.2 90.0 90.0 90.0

marCCD, 300 mm plate

Crystal structure of the S65T/F99S/M153T/V163A variant of GFP at 0.85 A

6JGJ

IRRMC 10.18430/m36jgj

SPring-8 BL41XU

0.78

P 21 21 21

50.9 62.3 68.8 90.0 90.0 90.0

PILATUS3 300K

Crystal structure of the F99S/M153T/V163A/E222Q variant of GFP at 0.78 A

6MOJ

SBGrid 10.15785/sbgrid/620

ALS 5.0.1

2.43

I 41 2 2

130.4 130.4 293.5 90.0 90.0 90.0

PILATUS3 6M

Dimeric DARPin A_angle_R5 complex with EpoR

6NEN

UQ eSpace 10.14264/uql.2018.843

Australian Synchrotron MX2

2.15

P 3 1 2

105.5 105.5 35.1 90.0 90.0 120.0

SMV, S/N 928

Catalytic domain of Proteus mirabilis ScsC

6O2H

SBGrid 10.15785/sbgrid/747

CHESS F1

1.21

P 1

27.4 32.1 34.5 88.7 108.5 111.9

PILATUS3 6M

Hen lysozyme in triclinic space group at ambient temperature - diffuse scattering dataset

6OEL

SBGrid 10.15785/sbgrid/652

ALS 8.2.1

3.10

F 41 3 2

328.1 328.1 328.1 90.0 90.0 90.0

SMV, S/N 905

Engineered Fab bound to IL-4 receptor

6OQZ

IRRMC 10.18430/m3.irrmc.5324

Home source, Bruker rotating anode

1.60

I 2 2 2

92.9 97.9 102.7 90.0 90.0 90.0

Bruker SMART 6000

Crystal structure of glucose isomerase from non-merohedrally twinned crystals

6OR0

IRRMC 10.18430/m3.irrmc.5325

Home source, Bruker rotating anode

1.55

I 21 3

78.0 78.0 78.0 90.0 90.0 90.0

Bruker SMART 6000

Crystal structure of insulin from non-merohedrally twinned crystals

6OWW

Zenodo 10.5281/zenodo.2943248

ALS 8.3.1

3.84

P 1 21 1

85.8 86.0 214.3 90.0 89.9 90.0

PILATUS3 6M

Crystal structure of a Human Cardiac Calsequestrin Filament Complexed with Ytterbium

6P8J

SBGrid 10.15785/sbgrid/671

APS 24-ID-E

1.47

P 1 21 1

46.5 152.2 88.3 90.0 90.1 90.0

Dectris Eiger 16M

Structure of P. aeruginosa ATCC27853 CdnD D62N/D64N mutant bound to ATP

6P8P

SBGrid 10.15785/sbgrid/673

APS 24-ID-C

1.64

P 4

97.5 97.5 60.1 90.0 90.0 90.0

PILATUS 6M-F

Structure of P. aeruginosa ATCC27853 HORMA1

6PB3

SBGrid 10.15785/sbgrid/681

APS 24-ID-E

2.05

P 6

100.4 100.4 48.9 90.0 90.0 120.0

Dectris Eiger 16M

Structure of Rhizobiales Trip13

6PXB

SBGrid 10.15785/sbgrid/698

APS 24-ID-E

1.75

P 32

64.0 64.0 119.4 90.0 90.0 120.0

PILATUS 6M-F

N-Terminal SH2 domain of the p120RasGAP

6PXC

SBGrid 10.15785/sbgrid/699

APS 24-ID-E

1.60

I 2 2 2

44.2 64.8 87.2 90.0 90.0 90.0

PILATUS 6M-F

N-Terminal SH2 domain of the p120RasGAP bound to a p190RhoGAP phosphotyrosine peptide

6QAJ

SBGrid 10.15785/sbgrid/637

Diamond I03

2.90

C 2 2 21

59.8 169.3 374.5 90.0 90.0 90.0

PILATUS3 6M

Structure of the tripartite motif of KAP1/TRIM28

6R72

Zenodo 10.5281/zenodo.14894181

SOLEIL PROXIMA 2

3.95

P 1 21 1

117.8 110.8 155.6 90.0 93.2 90.0

Dectris Eiger 9M

Crystal structure of BmrA-E504A in an outward-facing conformation

6RLR

Zenodo 10.5281/zenodo.5886687

Diamond I04

2.00

P 1

40.0 40.0 63.6 80.4 76.3 68.2

Eiger 16M

Crystal structure of CD9 large extracellular loop

6RYM

Keele University 10.21252/xbsq-d621

SRS PX10.1 (Daresbury)

1.46

P 43

50.2 50.2 51.9 90.0 90.0 90.0

marCCD 165 mm

Structure of carbohydrate recognition domain with GlcNAc bound

6S1U

MXRDR 10.18150/repod.0005795

BESSY 14.2

1.90

P 1 21 1

51.6 29.4 85.5 90.0 103.8 90.0

marCCD, 225 mm plate

Crystal structure of dimeric M-PMV protease C7A/D26N/C106A mutant in complex with inhibitor

6TOC

Zenodo 10.5281/zenodo.3571040

SLS X06DA

1.85

P 42

31.5 31.5 81.6 90.0 90.0 90.0

PILATUS 2MF

Crystal structure of the oligomerisation domain of the transcription factor PHOSPHATE STARVATION RESPONSE 1 from Arabidopsis (crystal form 3).

6TTN

IRRMC 10.18430/m36ttn

BESSY 14.1

1.12

P 21 21 21

39.9 79.8 104.7 90.0 90.0 90.0

PILATUS 6M

N-terminally truncated hyoscyamine 6-hydroxylase (tH6H) in complex with N-oxalylglycine and hyoscyamine

6U7G

IRRMC 10.18430/m36u7g

APS 23-ID-B

2.35

P 1 21 1

99.6 98.7 147.5 90.0 104.6 90.0

Dectris Eiger 16M

HCoV-229E RBD Class V in complex with human APN

6UKF

IRRMC 10.18430/m36ukf

APS 22-ID

1.00

P 1 21 1

61.0 37.3 69.0 90.0 109.8 90.0

Dectris Eiger 16M

HhaI endonuclease in Complex with DNA at 1 Angstrom Resolution

6V2R

IRRMC 10.18430/m36v2r

Home source, Rigaku FR-E

1.60

P 41 21 2

40.2 40.2 83.1 90.0 90.0 90.0

Rigaku Saturn A200

Crystal Structure of chromodomain of CBX7 mutant V13A in complex with inhibitor UNC3866

6VWW

IRRMC 10.18430/m36vww

APS 19-ID

2.20

P 63

150.5 150.5 111.3 90.0 90.0 120.0

PILATUS3 6M

Crystal Structure of NSP15 Endoribonuclease from SARS CoV-2.

6W4H

IRRMC 10.18430/m36w4h

APS 21-ID-F

1.80

P 31 2 1

167.7 167.7 51.9 90.0 90.0 120.0

Rayonix MX-300

1.80 Angstrom Resolution Crystal Structure of NSP16 - NSP10 Complex from SARS-CoV-2

6W75

IRRMC 10.18430/m36w75

APS 21-ID-F

1.95

P 32 2 1

166.2 166.2 98.3 90.0 90.0 120.0

Rayonix MX-300

1.95 Angstrom Resolution Crystal Structure of NSP10 - NSP16 Complex from SARS-CoV-2

6WZO

SBGrid 10.15785/sbgrid/785

APS 24-ID-E

1.42

P 1

43.7 50.1 69.3 106.5 90.1 97.1

Dectris Eiger 16M

Structure of SARS-CoV-2 Nucleocapsid dimerization domain, P1 form

6YQF

IRRMC 10.18430/m36yqf

Diamond I24

3.33

P 21 21 2

42.7 59.7 156.5 90.0 90.0 90.0

PILATUS3 6M

Crystal structure of the SYCE2-TEX12 delta-Ctip complex in a 4:4 assembly

6Z8O

Zenodo 10.5281/zenodo.3873216

ESRF ID30B

2.20

P 1 21 1

63.7 97.0 121.3 90.0 104.7 90.0

Dectris Eiger 4M

Structure of [NiFeSe] hydrogenase G491A variant from Desulfovibrio vulgaris Hildenborough pressurized with Krypton gas - structure G491A-Kr

6Z9G

Zenodo 10.5281/zenodo.3874714

ESRF ID30B

1.76

P 1 21 1

120.3 93.8 127.0 90.0 105.2 90.0

Dectris Eiger 4M

Structure of [NiFeSe] hydrogenase G491A variant from Desulfovibrio vulgaris Hildenborough pressurized with Oxygen gas - structure G491A-O2

6ZE4

SBGrid 10.15785/sbgrid/806

BESSY 14.1

1.60

P 21 21 21

93.6 109.9 116.1 90.0 90.0 90.0

PILATUS 6M

FAD-dependent oxidoreductase from Chaetomium thermophilum in complex with fragment 4-oxo-N-[(1S)-1-(pyridin-3-yl)ethyl]-4-(thiophen-2-yl)butanamide

6ZQR

Keele University 10.21252/r2nx-0425

Diamond I02

1.93

P 4

113.6 113.6 44.1 90.0 90.0 90.0

SMV, S/N 922

Crystal structure of tetrameric fibrinogen-like recognition domain of FIBCD1 with GlcNAc ligand bound

6ZQY

Keele University 10.21252/hx7e-rd04

Diamond I04

1.85

P 4

119.3 119.3 44.2 90.0 90.0 90.0

SMV, S/N 921

Crystal structure of tetrameric fibrinogen-like recognition domain of FIBCD1 with Neu5Ac ligand bound

6ZR0

Keele University 10.21252/zcfy-cw20

Diamond I04

1.94

P 4

119.2 119.2 44.2 90.0 90.0 90.0

PILATUS 6M Prosport+

Crystal structure of tetrameric fibrinogen-like recognition domain of FIBCD1 with N-acetylalanine ligand bound

7ARR

MXRDR 10.18150/EM87YL

PETRA III, EMBL c/o DESY P13 (MX1)

1.10

P 1

30.9 32.1 43.1 114.2 91.9 109.9

PILATUS 6M-F

The de novo designed hybrid alpha/beta-miniprotein

7ATG

IRRMC 10.18430/m37atg

PETRA III, EMBL c/o DESY P13 (MX1)

0.60

P 21 21 21

18.0 31.0 43.9 90.0 90.0 90.0

PILATUS 6M-F

Crystal structure of Z-DNA in complex with putrescinium and potassium cations at ultrahigh-resolution

7BGT

MXRDR 10.18150/1HQGWO

BESSY 14.2

1.93

P 1

29.3 67.6 69.7 76.8 83.9 83.6

marCCD, 225 mm plate

Mason-Pfizer Monkey Virus Protease mutant C7A/D26N/C106A in complex with peptidomimetic inhibitor

7BGU

MXRDR 10.18150/C9DYSH

EMBL/DESY Hamburg (DORIS) X13

2.43

P 1

29.1 67.9 69.7 77.1 83.3 83.2

marCCD 165 mm

Mason-Pfizer Monkey Virus Protease mutant C7A/D26N/C106A in complex with peptidomimetic inhibitor

7D1M

IRRMC 10.18430/m37brr

SSRF BL17U1

1.35

P 1 21 1

55.5 99.0 59.6 90.0 108.5 90.0

Dectris Eiger 16M

CRYSTAL STRUCTURE OF THE SARS-CoV-2 MAIN PROTEASE COMPLEXED WITH GC376

7D98

XRDa 10.51093/xrd-00013

Photon Factory BL-1A

3.60

P 61 2 2

105.8 105.8 602.5 90.0 90.0 120.0

Dectris Eiger 4M

Crystal structure of full-length CbnR complexed with the target DNA complex

7DKP

IRRMC 10.18430/M37DKP

ESRF MASSIF-3

1.45

P 1 21 1

49.8 169.5 49.8 90.0 93.5 90.0

Dectris Eiger 4M

Crystal structure of E. coli Grx2 in complex with GSH at 1.45 A resolution

7K1L

IRRMC 10.18430/m37k1l

APS 19-ID

2.25

P 63

150.8 150.8 110.7 90.0 90.0 120.0

PILATUS3 6M

Crystal Structure of NSP15 Endoribonuclease from SARS CoV-2 in the Complex with Uridine-2’,3’-Vanadate

7KCN

IRRMC 10.18430/m37kcn

LNLS W01B-MX2

1.46

P 41 2 2

67.0 67.0 116.9 90.0 90.0 90.0

PILATUS 2M

Reconstructed ancestor of HIUases and Transthyretins

7L6J

IRRMC 10.18430/m37l6j

APS 21-ID-F

1.78

I 41 3 2

171.7 171.7 171.7 90.0 90.0 90.0

Rayonix MX-300

Crystal Structure of the Putative Hydrolase from Stenotrophomonas maltophilia

7L84

SBGrid 10.15785/sbgrid/816

APS 24-ID-C

1.70

P 43 21 2

79.3 79.3 37.8 90.0 90.0 90.0

PILATUS 6M-F

Hen Egg White Lysozyme by Native S-SAD at Room Temperature

7MZT

IRRMC 10.18430/m37mzt

APS 22-ID

4.07

P 21 21 2

113.6 97.0 108.3 90.0 90.0 90.0

Dectris Eiger 16M

Borrelia burgdorferi BBK32-C in complex with an autolytic fragment of human C1r at 4.1A

7N0I

SBGrid 10.15785/sbgrid/835

ALS 5.0.2

2.20

P 21 21 21

75.8 131.6 140.0 90.0 90.0 90.0

PILATUS3 6M

Structure of the SARS-CoV-2 N protein C-terminal domain bound to single-domain antibody E2

7N2S

SBGrid 10.15785/sbgrid/916

SSRL BL12-1

2.37

P 1 21 1

83.2 52.8 106.3 90.0 98.3 90.0

PILATUS 6M

AS3.1-PRPF3-HLA*B27

7ORR

IRRMC 10.18430/M37ORR

MAX IV BioMAX

1.79

I 21 3

105.9 105.9 105.9 90.0 90.0 90.0

Dectris Eiger 16M

Non-structural protein 10 (nsp10) from SARS CoV-2 in complex with fragment VT00022

7OS3

MXRDR 10.18150/74YTYQ

PETRA III, EMBL c/o DESY P13 (MX1)

2.18

P 21 21 21

78.2 91.0 105.8 90.0 90.0 90.0

PILATUS 6M-F

Crystal structure of Rhizobium etli inducible L-asparaginase ReAV solved by S-SAD (orthorhombic form START)

7OU1

MXRDR 10.18150/VQQIHQ

BESSY 14.3

1.65

P 1 21 1

77.9 91.3 114.2 90.0 97.1 90.0

marCCD, 225 mm plate

Crystal structure of Rhizobium etli inducible L-asparaginase ReAV (monoclinic form MP2)

7PH1

IRRMC 10.18430/M37PH1

BESSY 14.2

1.18

I 2 2 2

75.0 81.3 124.2 90.0 90.0 90.0

PILATUS3 2M

Trypsin in complex with BPTI mutant (2S)-2-amino-4-monofluorobutanoic acid

7PQ7

IRRMC 10.18430/M3.IRRMC.6072

ELETTRA 11.2C

1.55

C 1 2 1

120.9 51.7 75.5 90.0 125.1 90.0

PILATUS 6M

Crystal structure of Campylobacter jejuni DsbA1

7Q6J

Zenodo 10.5281/zenodo.4686876

PETRA III, DESY P11

2.20

P 21 21 21

72.7 115.9 116.2 90.0 90.0 90.0

PILATUS 6MF

Crystal structure of the human GDAP1 CMT2 mutant-H123R

7QIJ

SBGrid 10.15785/sbgrid/907

PETRA III, EMBL c/o DESY P13 (MX1)

4.10

P 21 21 21

143.5 324.9 369.4 90.0 90.0 90.0

PILATUS 6M-F

Complex of the Yersinia enterocolitica Type III secretion export gate YscV with substrate:chaperone complex YscX:YscY

7QIS

IRRMC 10.18430/M37QIS

BESSY 14.2

1.83

P 61

100.3 100.3 206.2 90.0 90.0 120.0

PILATUS3 2M

CRYSTAL STRUCTURE OF THE P1 difluoroethylglycine (DfeGly) BPTI MUTANT- BOVINE CHYMOTRYPSIN COMPLEX

7QT9

Zenodo 10.5281/zenodo.5836055

Diamond I24

2.43

I 1 2 1

45.2 54.5 115.7 90.0 101.1 90.0

PILATUS3 6M

Room temperature In-situ SARS-CoV-2 MPRO with bound Z4439011584

7RAA

SBGrid 10.15785/sbgrid/881

SSRL BL12-2

2.69

P 43 21 2

66.4 66.4 298.3 90.0 90.0 90.0

PILATUS 6M

Designed StabIL-2 seq15

7RIS

IRRMC 10.18430/M37RIS

APS 21-ID-D

1.72

P 32 2 1

44.5 44.5 189.9 90.0 90.0 120.0

Dectris Eiger 9M

Crystal structure of RPA3624, a beta-propeller lactonase from Rhodopseudomonas palustris, with active-site bound phosphate

7RJI

IRRMC 10.18430/M37RJI

LNLS W01B-MX2

1.71

H 3 2

83.0 83.0 124.8 90.0 90.0 120.0

PILATUS 2M

BthTX-II variant b, from Bothrops jararacussu venom, complexed with stearic acid

7T5T

SBGrid 10.15785/sbgrid/864

SSRL BL9-2

1.35

P 42 21 2

95.3 95.3 104.9 90.0 90.0 90.0

PILATUS 6M

Structure of Thauera sp. K11 CapP

7TCD

IRRMC 10.18430/m37tcd

SLS X06SA

1.70

C 1 2 1

138.5 47.9 78.1 90.0 107.6 90.0

Dectris Eiger 16M

LOV2-DARPIN fusion: D13

7YZX

IRRMC 10.18430/M37YZX

Diamond I24

1.90

P 63 2 2

169.4 169.4 141.8 90.0 90.0 120.0

PILATUS3 6M

ScpA from Streptococcus pyogenes, D783A mutant.

8A1A

IRRMC 10.18430/M38A1A

SLS X06SA

2.05

P 65

191.9 191.9 122.4 90.0 90.0 120.0

Dectris Eiger 16M

Structure of a leucinostatin derivative determined by host lattice display : L1F11V1 construct

8AGQ

IRRMC 10.18430/M38AGQ

SLS X06DA

1.09

C 1 2 1

89.9 55.4 54.8 90.0 113.5 90.0

PILATUS 2MF

Crystal structure of anthocyanin-related GSTF8 from Populus trichocarpa in complex with (-)-catechin and glutathione

8C3E

Zenodo 10.5281/zenodo.14555180

Home source, Rigaku PhotonJet-S

2.10

P 31 2 1

57.8 57.8 41.5 90.0 90.0 120.0

CrysAlisPro HPAD, 775 x 800

Engineered mini-protein LCB2 (blocking ligand of SARS-Cov-2 spike protein)

8DQB

IRRMC 10.18430/m38dqb

NSLS-II 19-ID

2.50

I 2 3

164.1 164.1 164.1 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal structure of 3-dehydroquinate dehydratase I from Klebsiella oxytoca (I23 Form)

8DYZ

SBGrid 10.15785/sbgrid/957

CHESS F1

1.27

P 43 21 2

79.6 79.6 38.3 90.0 90.0 90.0

PILATUS3 6M

Hen lysozyme in tetragonal space group at ambient temperature - diffuse scattering dataset

8DZ7

SBGrid 10.15785/sbgrid/958

CHESS F1

1.34

P 21 21 21

30.5 56.4 73.9 90.0 90.0 90.0

PILATUS3 6M

Hen lysozyme in orthorhombic space group at ambient temperature - diffuse scattering dataset

8EGN

IRRMC 10.18430/M38EGN

CLSI 08B1-1

1.95

P 21 21 21

71.7 75.2 109.8 90.0 90.0 90.0

PILATUS3 6M

Crystal Structure of UDP-N-acetylmuramate-L-alanine ligase (UDP-N-acetylmuramoyl-L-alanine synthetase, MurC) Pseudomonas aeruginosa in complex with ligand AZ-13643701

8IYA

IRRMC 10.18430/m38iya

SSRF BL02U1

2.43

C 1 2 1

102.7 50.1 109.2 90.0 91.8 90.0

Dectris EIGER2 Si 9M

Complex of SETDB1-derived peptide bound to UBE2E1

8K1G

IRRMC 10.18430/M38K1G

PAL/PLS 11C

2.09

I 4 2 2

182.0 182.0 80.7 90.0 90.0 90.0

PILATUS3 6M

Crystal structure of ethylene glycol-bound glycerol dehydrogenase from Klebsiella pneumoniae

8OIC

IRRMC 10.18430/m38oic

Diamond I04

2.80

P 1

73.1 94.7 120.6 105.1 90.0 93.8

Eiger 16M

Trichomonas vaginalis riboside hydrolase (His-tagged)

8OWM

MXRDR 10.18150/II5MT4

PETRA III, EMBL c/o DESY P13 (MX1)

1.70

P 1

95.5 95.6 95.8 90.4 93.6 117.8

Dectris Eiger 16M

Crystal structure of glutamate dehydrogenase 2 from Arabidopsis thaliana binding Ca, NAD and 2,2-dihydroxyglutarate

8PQD

IRRMC 10.18430/m38pqd

ESRF MASSIF-3

1.50

P 21 21 21

59.4 59.4 192.9 90.0 90.0 90.0

Dectris Eiger 4M

c-KIT kinase domain in complex with avapritinib derivative 10

8QAW

MXRDR 10.18150/INUP4Q

PETRA III, EMBL c/o DESY P13 (MX1)

1.55

H 3

137.7 137.7 265.9 90.0 90.0 120.0

Dectris Eiger 16M

Medicago truncatula HISN5 (IGPD) in complex with MN, IMD, EDO, FMT, GOL and TRS

8QJ5

IRRMC 10.18430/m38qj5

ELETTRA 11.2C

1.63

P 1 21 1

57.6 100.6 77.9 90.0 96.1 90.0

PILATUS 6M

Crystal structure of the Levansucrase beta from Pseudomonas syringae pv. actinidiae

8QQ7

Zenodo 10.5281/zenodo.14901515

ESRF MASSIF-1

3.62

P 64 2 2

146.0 146.0 153.6 90.0 90.0 120.0

PILATUS3 2M

Structure of SpNOX: a Bacterial NADPH oxidase

8R5R

IRRMC 10.18430/m38r5r

ESRF ID23-1

3.08

P 21 21 21

91.7 132.9 137.5 90.0 90.0 90.0

Dectris EIGER2 CdTe 16M

Structure of apo TDO with a bound inhibitor

8RUD

MXRDR 10.18150/RBG2F9

PETRA III, EMBL c/o DESY P13 (MX1)

2.10

P 1 21 1

78.1 91.4 114.5 90.0 96.9 90.0

Dectris Eiger 16M

Crystal structure of Rhizobium etli L-asparaginase ReAV K138A mutant

8S38

MXRDR 10.18150/CGLBVH

PETRA III, EMBL c/o DESY P13 (MX1)

1.89

I 21 21 21

95.4 163.1 219.0 90.0 90.0 90.0

PILATUS 6M-F

Crystal structure of Medicago truncatula glutamate dehydrogenase 2 in complex with citrate and NAD

8SA8

IRRMC 10.18430/M38SA8

NSLS-II 19-ID

1.30

I 1 2 1

87.9 131.5 165.4 90.0 104.5 90.0

Dectris EIGER2 Si 9M

Crystal Structure of Cystathionine beta lyase from Klebsiella aerogenes, Covalently bound and free PLP (I2 form)

8SQO

IRRMC 10.18430/m38sqo

NSLS-II 19-ID

1.55

P 4 3 2

112.9 112.9 112.9 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal Structure of Bacterioferritin (Bfr) from Brucella abortus (magnesium bound, F16L mutant)

8SQQ

IRRMC 10.18430/M38SQQ

NSLS-II 19-ID

2.25

F 4 3 2

171.5 171.5 171.5 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal Structure of Bacterioferritin (Bfr) from Brucella abortus (Apo Cubic Form 2, F16L mutant)

8SQT

IRRMC 10.18430/M38SQT

NSLS-II 19-ID

2.20

F 4 3 2

170.7 170.7 170.7 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal Structure of Bacterioferritin (Bfr) from Brucella abortus (iron bound, cubic form 2, F16L mutant)

8T7R

IRRMC 10.18430/M38T7R

APS 22-ID

3.84

C 1 2 1

357.1 259.6 255.4 90.0 133.1 90.0

Dectris Eiger 16M

Crystal structure of human leukocyte antigen A*0101 in complex with the Fab of alloreactive antibody E07

8THA

IRRMC 10.18430/m38tha

SSRL BL9-2

1.68

P 64

69.2 69.2 29.1 90.0 90.0 120.0

PILATUS 6M

1TEL, non-compressed, double-helical crystal form

8TYY

SBGrid 10.15785/sbgrid/1040

APS 24-ID-E

1.68

F 4 3 2

214.9 214.9 214.9 90.0 90.0 90.0

Dectris Eiger 16M

Structure of a bacterial Ubl-deubiquitinase complex (form 2)

8U0I

IRRMC 10.18430/m38u0i

ALS 8.2.1

1.54

P 43 21 2

50.3 50.3 90.6 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal structure of PA0012 complexed with cyclic-di-GMP from Pseudomonas aeruginosa

8V2T

Zenodo 10.5281/zenodo.10201899

NSLS X25

1.40

P 42 21 2

60.9 60.9 92.7 90.0 90.0 90.0

PILATUS 6M

Phosphoheptose isomerase GMHA from Burkholderia pseudomallei bound to inhibitor Mut148591

8V4J

Zenodo 10.5281/zenodo.10222807

NSLS X29A

1.31

P 42 21 2

61.0 61.0 92.4 90.0 90.0 90.0

ADSC Quantum 315

Phosphoheptose isomerase GMHA from Burkholderia pseudomallei bound to inhibitor Mut148233

8V4O

IRRMC 10.18430/m38v4o

NSLS-II 19-ID

2.70

P 61 2 2

139.5 139.5 545.0 90.0 90.0 120.0

Dectris EIGER2 Si 9M

Crystal structure of Acetyl-CoA synthetase 2 in complex with AMP from Candida albicans

8XBP

IRRMC 10.18430/M38XBP

SOLEIL PROXIMA 1

1.99

C 1 2 1

148.3 50.8 60.2 90.0 92.3 90.0

Dectris Eiger 16M

Crystal structure of AtNATA1 bound to Acetyl CoA

8XTE

SBGrid 10.15785/sbgrid/1101

SSRF BL19U1

1.99

P 32

208.8 208.8 67.2 90.0 90.0 120.0

PILATUS3 6M

Crystal structure of methyltransferase MpaG’ in complex with SAH and FDHMP

8XTF

SBGrid 10.15785/sbgrid/1102

SSRF BL02U1

2.13

H 3 2

211.8 211.8 67.4 90.0 90.0 120.0

Dectris EIGER2 Si 9M

Crystal structure of methyltransferase MpaG’ in complex with SAH and FDHMP-3C

8XTG

SBGrid 10.15785/sbgrid/1100

SSRF BL19U1

2.00

P 32

199.5 199.5 67.2 90.0 90.0 120.0

Crystal structure of methyltransferase MpaG’ in complex with SAH and DMMPA

8Y74

XRDa 10.51093/xrd-00227

SSRF BL02U1

1.90

C 1 2 1

125.8 76.6 87.1 90.0 92.4 90.0

Dectris EIGER2 Si 9M

Crystal structure of 9-mer peptide from H9N2 avian influenza virus in complex with BF2*0201

8YS9

IRRMC 10.18430/M38YS9

PAL/PLS 5C (4A)

1.46

P 21 21 21

71.0 77.7 83.2 90.0 90.0 90.0

Dectris Eiger 9M

Crystal structure of Phosphatidylethanolamine N-methyltransferase from R. thermophilum complexed with DMPE and SAH

9B22

IRRMC 10.18430/m39b22

NSLS-II 19-ID

1.30

P 1 21 1

39.8 92.7 57.7 90.0 91.7 90.0

Dectris EIGER2 Si 9M

Crystal structure of ADP-ribose diphosphatase from Klebsiella pneumoniae (ADP Ribose and AMP bound)

9BN8

IRRMC 10.18430/m39bn8

NSLS-II 19-ID

1.35

P 41

65.5 65.5 134.8 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal Structure of UDP-N-acetylmuramoylalanine–D-glutamate ligase (MurD) from E. coli in complex with UMA and inhibitor A19

9C18

Zenodo 10.5281/zenodo.11405662

NSLS-II 17-ID-1

1.90

P 1

41.9 42.0 60.2 84.1 87.2 63.7

Dectris EIGER1 Si 9M

Human biliverdin IX beta reductase in complex with NADP in space group P1

9CHW

SBGrid 10.15785/sbgrid/1124

APS 21-ID-F

2.16

P 61

98.7 98.7 82.1 90.0 90.0 120.0

Rayonix MX-300

Crystal structure of human polymerase eta with incoming dAMPnPP nucleotide opposite threofuranosyl thymidine in DNA template

9CRW

IRRMC 10.18430/m39crw

CLSI 08ID-1

2.49

P 1 21 1

84.0 104.6 118.8 90.0 93.4 90.0

Dectris Eiger 9M

Crystal structure of the Candida albicans kinesin-8 proximal tail domain

9E2T

SBGrid 10.15785/sbgrid/1148

SSRL BL12-1

2.28

P 1

75.5 78.1 101.2 94.6 103.4 114.5

Dectris EIGER2 Si 16M

Structure of a de novo designed interleukin-21 mimetic complex with IL-21R and IL-2Rg

9EA5

SBGrid 10.15785/sbgrid/1142

SSRL BL9-2

2.00

P 1 21 1

65.9 73.1 98.4 90.0 108.7 90.0

PILATUS 6M

Structure of Citrobacter BubCD D104A mutant

9FCF

MXRDR 10.18150/DGZKW3

PETRA III, EMBL c/o DESY P13 (MX1)

2.36

P 4

91.3 91.3 35.8 90.0 90.0 90.0

Dectris EIGER1 Si 16M

Medicago truncatula 5’-ProFAR isomerase (HISN3) D57N mutant in complex with ProFAR

9FCG

MXRDR 10.18150/LDLSBT

PETRA III, EMBL c/o DESY P13 (MX1)

1.54

P 4

87.8 87.8 35.6 90.0 90.0 90.0

Dectris EIGER1 Si 16M

Medicago truncatula 5’-ProFAR isomerase (HISN3) D57N mutant in complex with PrFAR

9FHC

Zenodo 10.5281/zenodo.11472085

SLS X06SA

2.20

I 2 3

227.5 227.5 227.5 90.0 90.0 90.0

marCCD, 225 mm plate

Crystallographic structure of AcrB V612F with bound minocycline

9GDJ

ESRF 10.15151/ESRF-DC-1848199439

ESRF ID23-1

1.47

P 41 21 2

123.9 123.9 126.4 90.0 90.0 90.0

Dectris EIGER2 CdTe 16M

C-Methyltransferase SgMT from Streptomyces griseoviridis

9GJX

IRRMC 10.18430/M39GJX

Diamond I04

2.40

P 1 21 1

76.8 115.8 103.8 90.0 110.3 90.0

Eiger 16M

Bacillus licheniformis nitroreductase

9GQG

ESRF 10.15151/ESRF-DC-1900353437

ESRF ID30B

2.00

P 32 2 1

48.2 48.2 188.0 90.0 90.0 120.0

Dectris EIGER2 Si 9M

The FK1 domain of FKBP51 in complex with the macrocyclic SAFit analog m5(10,7)-(E)-OH

9H0Q

Zenodo 10.5281/zenodo.13912326

SOLEIL PROXIMA 2

2.55

H 3 2

169.5 169.5 344.0 90.0 90.0 120.0

Dectris EIGER1 Si 9M

N terminal domain of BC2L-C lectin in complex with N-(beta-L-Fucopyranosyl)-biphenyl-3-carboxamide

9HNC

MXRDR 10.60884/0K7B68

PETRA III, EMBL c/o DESY P13 (MX1)

1.88

P 1 2 1

123.8 123.6 187.7 90.0 90.1 90.0

PILATUS 6M-F

Crystal structure of potassium-independent L-asparaginase from Phaseolus vulgaris (PvAIII, PvAspG2)

9HS7

IRRMC 10.18430/M39HS7

ALBA XALOC

1.70

P 65

65.4 65.4 88.8 90.0 90.0 120.0

PILATUS3 X 6M

Anti-HIV-1 chimeric miniprotein mimicking the N-terminal half of gp41 NHR with an extended region targeting the MPER

9I0A

IRRMC 10.18430/M39I0A

SOLEIL PROXIMA 1

2.22

P 21 21 2

75.2 98.7 208.6 90.0 90.0 90.0

Dectris Eiger 16M

CARM1 in complex with arg-aDMA analog

9I80

Zenodo 10.5281/zenodo.14844040

SOLEIL PROXIMA 1

1.95

P 41

81.2 81.2 165.0 90.0 90.0 90.0

Dectris Eiger 16M

LecA in complex with a tolcapone derivative glycomimetic

9IG7

IRRMC 10.18430/M39IG7

PETRA III, EMBL c/o DESY P13 (MX1)

2.60

P 21 21 2

111.5 153.5 69.0 90.0 90.0 90.0

Dectris EIGER1 Si 16M

KOD-H4 DNA polymerase mutant in a binary complex with DNA:DNA containing two AtNA nucleotides

9IH9

IRRMC 10.18430/M39IH9

ESRF MASSIF-3

1.70

C 1 2 1

78.8 133.9 82.3 90.0 101.4 90.0

Dectris EIGER1 Si 4M

KEAP1 complexed to linear peptide 6

9JQ9

IRRMC 10.18430/M39JQ9

Home source, Excillum MetalJet D2+

1.90

P 21 21 21

48.6 50.5 78.6 90.0 90.0 90.0

PILATUS3 1M

Crystal structure of Plasmoredoxin from Plasmodium falciparum a disulfide oxidoreductase protein unique to Plasmodium species

9JZO

IRRMC 10.18430/m39jzo

PAL/PLS 11C

1.40

P 1

41.6 43.1 54.2 113.0 90.1 118.2

PILATUS3 6M

Crystal structure of PHICD111_20024_EAD.

9KHR

Zenodo 10.5281/zenodo.14070468

RRCAT INDUS-2 PX-BL21

2.00

P 21 21 21

48.7 50.3 78.0 90.0 90.0 90.0

marCCD, 225 mm plate

Crystal structure of Plasmoredoxin, a disulfide oxidoreductase from Plasmodium falciparum crystallized in the presence of Dithiothreitol (DTT)

9LXL

Zenodo 10.5281/zenodo.15005358

SSRF BL17UM

2.19

P 41 21 2

76.8 76.8 225.3 90.0 90.0 90.0

EIGER2 S 16M

Crystal structure of GH29 family alpha-L-fucosidase from Fusarium proliferatum LE1

9MH4

IRRMC 10.18430/M39MH4

NSLS-II 19-ID

3.05

P 21 3

138.7 138.7 138.7 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal Structure of Bifunctional protein GlmU from Klebsiella aerogenes

9MIN

SBGrid 10.15785/sbgrid/1151

ALS 8.2.1

2.05

P 21 21 21

95.5 98.5 155.7 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Structure of a designed minibinder to NYESO1-A*02:01

9O0H

IRRMC 10.18430/M39O0H

SSRL BL12-2

2.24

P 21 21 21

55.2 65.5 112.9 90.0 90.0 90.0

Dectris EIGER2 Si 16M

The ubiquitin-associated domain of human thirty-eight negative kinase 1, fused to the 3TEL crystallization chaperone via a 2-glycine linker

9P7Q

IRRMC 10.18430/M39P7Q

SSRL BL12-1

2.21

C 1 2 1

97.0 45.0 72.1 90.0 105.1 90.0

Dectris EIGER2 Si 16M

273K human S-adenosylmethionine decarboxylase

9PBB

IRRMC 10.18430/M39PBB

SSRL BL12-1

2.17

C 1 2 1

97.4 45.9 72.2 90.0 105.0 90.0

Dectris EIGER2 Si 16M

293K human S-adenosylmethionine decarboxylase

9Q41

SBGrid 10.15785/sbgrid/1194

CHESS 7B2

1.95

C 2 2 21

118.6 133.7 82.4 90.0 90.0 90.0

Dectris EIGER2 Si 16M

Crystal Structure of Human Apo Spermidine Synthase

9Q66

SBGrid 10.15785/sbgrid/1208

NSLS-II 17-ID-1

2.01

P 1 21 1

105.9 67.3 158.0 90.0 99.1 90.0

Dectris EIGER1 Si 9M

Human prolyl endopeptidase (PREP) - complex with JP-4-1-7

9QVV

Zenodo 10.5281/zenodo.19456697

Diamond I03

2.72

I 2 2 2

120.1 123.8 123.8 90.0 90.0 90.0

Eiger 16M

Crystal structure of the 4CHRD domain of human chordin, mutant designed to abolish binding to sulphated glycosaminoglycans

9QW2

Keele University 10.21252/yzsx-0e16

Diamond I03

1.92

P 1 21 1

55.4 108.2 55.6 90.0 90.9 90.0

PILATUS3 6M

Crystal structure of human lung surfactant protein D trimeric fragment with bound synthetic HepII-HepI-PhosI ligand

9QW8

ESRF 10.15151/ESRF-DC-2127908021

ESRF ID23-1

1.80

P 1

35.6 35.6 100.9 86.5 84.2 72.5

Dectris EIGER2 CdTe 16M

FKBP12 in complex with bifunctional ligand 1ad and the first bromodomain of BRD4

9RCI

Zenodo 10.5281/zenodo.15615368

SOLEIL PROXIMA 2

1.66

P 1

35.9 39.3 100.9 98.3 90.3 90.1

Dectris Eiger 9M

Crystal Structure of Flap Endonuclease FEN1 with Compound 28

9RCS

XRDa 10.51093/xrd-00383

Diamond I24

3.01

P 1 21 1

70.0 78.8 82.3 90.0 88.6 90.0

Eiger 9M

Cardioderma bat coronavirus KY43 receptor binding domain in complex with human CEACAM6

9RP9

IRRMC 10.18430/M39RP9

SOLEIL PROXIMA 1

2.10

C 1 2 1

73.5 59.8 91.7 90.0 100.8 90.0

Dectris Eiger 16M

Crystal structure of mouse pVHL-ElonginB-ElonginC complex

9S02

MXRDR 10.60884/NRNGS4

MAX IV BioMAX

1.65

P 21 21 2

163.7 88.0 116.7 90.0 90.0 90.0

EIGER2 X 16M

PYCR1 in complex with 3-(2-thiazolyl)propionic acid

9SL0

IRRMC 10.18430/M39SL0

ESRF MASSIF-1

1.60

P 21 21 21

60.2 80.2 111.6 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal structure of HLA-A0201 in complex with peptide LLWNGPMAV

9T6S

SBGrid 10.15785/sbgrid/1260

ESRF ID30B

2.00

P 21 21 21

63.0 64.6 102.7 90.0 90.0 90.0

Dectris EIGER2 Si 9M

Crystal Structure of the Listeria monocytogenes CadC with Cadmium

9UPT

XRDa 10.51093/xrd-00191

NSRRC TPS 05A

2.37

P 6

158.3 158.3 54.0 90.0 90.0 120.0

SMV, S/N 930

Structure of AtBgl1A, a GH1 beta-Glucosidase from Acetivibrio thermocellus

9V16

XRDa 10.51093/xrd-00338

SPring-8 BL44XU

3.45

P 41 21 2

185.6 185.6 451.2 90.0 90.0 90.0

Dectris EIGER1 Si 16M

Crystal structure of E. coli glycogen phosphorylase N185A/R267E mutant in complex with AMP

9VX7

IRRMC 10.18430/M39VX7

PAL/PLS 5C (4A)

4.85

P 64

122.5 122.5 118.9 90.0 90.0 120.0

PILATUS3 6M

Transcription factor

9VYB

IRRMC 10.18430/M39VYB

PAL/PLS 5C (4A)

2.12

P 21 21 21

44.4 47.8 48.4 90.0 90.0 90.0

Dectris Eiger 9M

Antitoxin Phd

9W3Y

IRRMC 10.18430/M39W3Y

Photon Factory BL-1A

1.50

P 21 21 21

60.7 70.0 94.2 90.0 90.0 90.0

Dectris EIGER1 Si 4M

X-ray Crystal Structure of Pseudoazurin Met16Gly variant (Tris-HCl pH 7.6)

9YL4

Zenodo 10.5281/zenodo.17298261

APS 17-ID

3.70

P 21 21 21

95.8 111.3 403.0 90.0 90.0 90.0

PILATUS 6M

Crystal structure of PprA S-F filament from Deinococcus radiodurans

9YZK

IRRMC 10.18430/M39YZK

ALS 8.2.2

5.10

I 1 2 1

75.8 163.0 192.3 90.0 98.6 90.0

PILATUS3 S 2M

Isoreticular co-crystal 1 with symmetrical expanded duplex (42mer) containing insert sequence ACCCTTCTATGACCTACTCCA

9Z44

IRRMC 10.18430/M39Z44

ALS 8.2.1

7.20

I 1 2 1

73.5 127.7 141.2 90.0 92.0 90.0

Dectris EIGER2 Si 9M

Isoreticular co-crystal 1 with symmetrical expanded duplex (31mer) containing insert sequence CCCGGCCGGA and loaded with C-clamp domain

9Z72

SBGrid 10.15785/sbgrid/1239

SSRL BL9-2

2.38

P 31 2 1

59.2 59.2 426.2 90.0 90.0 120.0

Dectris EIGER2 Si 16M

Structure of V. cholerae CapS (form 1)

9ZLO

Zenodo 10.5281/zenodo.18652652

Australian Synchrotron MX2

2.00

P 21 21 21

38.4 90.0 107.0 90.0 90.0 90.0

Dectris EIGER1 Si 16M

Crystal structure of Proteus mirabilis UreE

9ZM0

IRRMC 10.18430/M39ZM0

NSLS-II 17-ID-1

2.10

P 1 21 1

50.4 30.1 91.2 90.0 97.1 90.0

Dectris EIGER1 Si 9M

Crystal structure of monomeric Atg23

9ZMU

IRRMC 10.18430/M39ZMU

NSLS-II 19-ID

1.98

P 65 2 2

47.8 47.8 492.6 90.0 90.0 120.0

Dectris EIGER2 Si 9M

Crystal structure of an Iole protein from Brucella melitensis (hexagonal P form)

The table holds 204 PDB entries. Eight more datasets, small-molecule / chemical-crystallography sets kept because they exercise short wavelengths, CdTe sensors, fine slicing and non-zero detector 2θ, have no PDB entry and are listed below.

Twelve datasets are in primitive, non-triclinic space groups with no screw axis - 6P8P, 6ZQR, 6ZQY, 6ZR0, 9FCF and 9FCG in P 4, 6PB3 and 9UPT in P 6, 5JVN in P 6 2 2, 6NEN in P 3 1 2, 8SQO in P 4 3 2 and 9HNC in P 1 2 1. They are negative controls for screw-axis detection: the correct answer for each has no systematic absences.

6Z9G is the collection’s only index-4 superstructure: its deposited cell is four times the sublattice a/2, b, c/2, and the four copies of each of its two entities are related by the XOR-closed trio of near-pure translations (1/2,0,0), (0,0,1/2) and (1/2,0,1/2). Every other pseudo-translation in the collection is index 2 or a setting artefact, so it is the one set that exercises a supercell of index greater than two.

Archives that are not a single sweep

Most rows above are a single continuous rotation. The archives described in this section are not, or needed special handling to obtain the images; their layout is read from the image files themselves, from the repository file listings and from the depositors’ own description of the record. Not every archive in the table has had its layout audited to this depth. Where an archive held more than one collection, only one is kept - the repository’s project page is not a reliable guide to this, because it describes the project rather than the tarball (7TCD’s page lists a 900-frame miniCBF sweep the archive does not contain).

6R72 - two collections on one crystal. The Zenodo record holds two complete 360° sweeps of 3600 × 0.1° frames taken from the same crystal: a helical collection, which produced the deposited structure, and a low-dose collection from a single position, which was not used for a deposition. The battery’s 6r72 row runs the low-dose collection (V-CK63-8-ld_1_master.h5, pinned) and scores it against the deposited space group and cell, which describe the same crystal; the deposited resolution belongs to the helical collection. The helical collection is in the archive but is not a battery row. The record also ships the authors’ XDS.INP.

The three CHESS depositions - wedges plus a measured background. Each crystal was rotated in 50° wedges of 500 × 0.1° frames and translated between wedges to spread the dose. Each crystal also has a rotation at 1° per frame taken with the crystal translated out of the beam, which the depositors include as a measured background and say can be matched to the diffraction frames by the phi value in the image header.

PDB

Crystals

Wedges per crystal

Background rotation

8DYZ

1

8

360 frames

8DZ7

2

4

200 frames per crystal

6O2H

4

1, 3, 2, 5 - 11 in all

50, 145, 95, 235 frames, one per crystal

Four archives added for facility coverage hold more than one sweep. One sweep is kept, and the row is pinned to it. 7BGU’s MXRDR record is one directory of 900 marCCD frames that are two sweeps with different oscillation widths: frames 1001-1674 (0.4°) are the row, frames 1675-1900 were moved to sweep2/ so the reader sees one sweep. 5JK4’s archive holds a high-resolution sweep of 185 frames (80 mm, 1°) and a low-resolution one of 93 frames (250 mm, 2°); the row is the high-resolution sweep. 6RYM’s zip holds two sweeps (jmp47a2_1, 70 frames; jmp47a2_2, 60 frames); the row is the first. 6GVK’s Zenodo record has three tarballs (set1-set3); only set1 (1800 miniCBF frames) was downloaded and is the row.

Seven IRRMC archives hold more than one collection. In six of them one sweep is kept and the rest were deleted, so a run over the data directory sees a single collection per dataset. 7RIS is the exception: its two sweeps are at different wavelengths and both are kept.

PDB

What the archive holds

Kept

6UKF

two sweeps on one crystal - 960 x 0.25° (240°) and 1440 x 0.25° (360°)

the 360° sweep

7DKP

two complete 360° sweeps on one crystal, 3° apart in ω

the first

9PBB

two overlapping 135° wedges of one crystal, 90 x 1.5° each

the first

8U0I

a 69-frame screening wedge and three 180° sweeps on three crystals

the first 180° sweep

36GK

two 360° sweeps of 1800 x 0.2° at the same geometry

the one the archive and DOI are named for

9CRW

a dose pair on one crystal 37 min apart - 0.025 s at 289 mm, 0.010 s at 276 mm

the 0.025 s sweep, whose 2.5 Å target matches the deposited 2.49 Å

7RIS

two crystals at two wavelengths - 1.53494 Å (Ho derivative) and 1.03329 Å (the deposited native)

both

Seventeen further archives hold more than one collection. Their layout was read from the image files and repository listings; one sweep is kept for a run over the data directory unless noted.

PDB / dataset

What the archive holds

Kept

5JVN

two 360° sweeps of one crystal, 3600 × 0.1° each (w1_3, w1_4)

the w1_3 sweep

6FID

two 360° sweeps of one crystal, 3600 × 0.1° each

the first

6IU8

a two-wavelength MAD pair, 720 × 0.5° each at 1.605 Å (low remote) and 1.740 Å (peak)

both - the pair is the point

7OS3

four 360° sweeps at λ 2.066 Å, 3600 × 0.1° each, from two crystal positions (pos2_1/2, pos3_1/2)

all four are kept as separate sweep directories pos*/

7L84

two ~720° helical sweeps, 1439 × 0.5° each at λ 1.892 Å, room temperature

the 301_helical_1 sweep

5M17

seven crystals in one tar (5M03/5M17/5MEL/5MC8/5M5D/5M3W/5LYR), one 1800-frame sweep each

only the 5M17 tar was downloaded

cytidine

six scans, three ω and three φ, at 2θ = 30° (I19-1 commissioning)

the 1800-frame φ scan

lalanine

four runs of the RODIN L-alanine deposition at 2θ = 20°

the 900-frame pgw240050_01 run

9E2T

one continuous sweep plus screening images

the 2700-frame sweep

8OWM

three MXRDR zips covering one 1800-frame sweep, plus a processed-data zip

the three sweep zips (proc zip skipped)

6OR0

four 900 × 0.2° Bruker .sfrm runs of one twinned crystal at 10 cm: ω scans at 2θ = 0° (01) and 35° (02), φ scans on the fixed-χ (54.74°) platform at 2θ = 0° (03) and 35° (04)

the 01 run (2θ = 0°): the header distance of these SMART 6000 frames is ~4% short of what the data give, which the distance refinement corrects on a 2θ = 0° run and not yet on a swung one

6OQZ

eleven .sfrm ω runs of 472-900 × 0.2° at 18 cm, 2θ = 10°, 25° and 45° (low, medium, high resolution) at different φ, plus two 5-frame runs at 2θ = 0° and the orientation-matrix runs gdri_MATRIX_*

the low-resolution 01 run (2θ = 10°), for the reason given for 6OR0; three crystals, the test set for multi-lattice integration

laspartic

seven Bruker-converted full-imgCIF kappa runs, φ (01, 1200 × 0.3°) and ω (02-07, 292-394 frames) at 2θ = -26.7°

the 1200-frame 01 φ run

onitroaniline

the same seven-run kappa layout (01 1200 × 0.3° φ, 02-07 ω), deposited twice: as Bruker .sfrm and as APEX’s full-imgCIF conversion of the same frames

the 01 run, read from the .sfrm files

7D98

one 250 × 0.5° miniCBF sweep (frames 11-260), plus four HDF5 masters that repeat frames 61-260 in 60-frame pieces

the miniCBF sweep; the HDF5 files stay beside it and the row is pinned

6H2P

two sweeps of one crystal, 1800 × 0.1° at 0.918 Å and 3600 × 0.1° at 1.893 Å (the Mn K edge)

both, as two battery rows, 6h2p_native and 6h2p_1p89A; the long-wavelength row has no deposited resolution to compare with

8C3E

four 0.5° ω scans of one crystal at different (φ, χ) settings, 56, 150, 150 and 50 frames (lcb2_8_newt_001 to _004)

the 150-frame _003 scan

Four archives needed special handling to obtain the images.

  • 5KY6 is served by MXRDR as 11 separate RAR archives, one folder of frames per archive, 50 frames per archive except the last, 564 frames in all. Reading them needs a RAR reader with RAR3 filter support: the official 7-Zip 7zz reads them, while the unrar-free and p7zip builds of Enterprise Linux 8 cannot.

  • 6NEN’s University of Queensland eSpace record blocks scripted download, so its archive was downloaded by hand in a browser.

  • 4P8R’s IRRMC tar holds one 800 × 0.2° sweep as per-frame .bz2 files, which rugnux does not read; they were decompressed with bunzip2 after extraction.

  • 2WNN, 2WNQ, 2WNZ, 2XFW and 4BWL are each served by the Zenodo record as two zips of 180 frames (<pdb>-images-1-180.zip, <pdb>-images-181-360.zip, or 2wnq-181-360.zip); both were extracted into one directory, which holds the one 360 × 0.5° sweep.

Multi-sweep battery rows

The opt-in multisweep arm of the battery (tools/battery/multisweep.json, see the battery README) gives rugnux several sweeps of the archives above at once and scores the one merge against the base row’s reference (7QT9, which has no single-sweep row, carries its own), plus which sweeps joined. It uses only sweeps that are on disk: for 6UKF, 7DKP, 9PBB, 8U0I and 36GK the second collection was deleted (above), so they have no row until it is downloaded again. Two-wavelength pairs (6IU8, 6H2P, 7RIS) are refused by rugnux as one dataset; 6IU8 is the row that checks it.

Row

Base row

Sweeps

What it covers

Expected

6or0_sweeps

open/6or0

4

one twinned crystal: omega and phi scans at 2theta 0 and 35 deg (swung detector, header distance ~4% short)

all join

6oqz_sweeps

open/6oqz

4

one crystal at 2theta 10, 25, 45 and 45 deg; multi-lattice; the header distance makes the low-2theta runs’ cell ~3% short

all join

lalanine_sweeps

open/lalanine

4

small molecule, four runs of one crystal at 2theta 20 deg

all join

laspartic_sweeps

open/laspartic

7

small molecule, seven kappa runs of one crystal (phi + six omega), sparse, twinned

all join

cytidine_omega

open/cytidine

3

small molecule, three omega scans at phi 0/120/240 at 2theta 30 deg

all join

8c3e_scans

open/8c3e

4

home source, four omega scans of one twinned crystal at different (phi, chi)

all join

8dyz_wedges

open/8dyz

4

one crystal, four of its eight 50 deg wedges, translated between wedges, room temperature, 1.27 A

all join

8dz7_crystals

open/8dz7

4

two crystals, two 50 deg wedges each, room temperature, 1.34 A

all join

6o2h_crystals

open/6o2h

4

four triclinic crystals, one 50 deg wedge each, room temperature, 1.21 A

all join

7qt9_crystals

open data, own reference

20

in-situ crystals at room temperature, twenty 20 deg wedges (the depositors merged them as 16 crystals), none complete alone

more than half join

7l84_helical

open/7l84

2

two ~720 deg helical sweeps of one crystal, S-SAD at 1.892 A, room temperature

all join

6fid_sweeps

open/6fid

2

two 360 deg sweeps of one crystal (aligned and random orientation), S-SAD at 2.066 A

all join

6iu8_mad

open/6iu8

2

keep separate: a two-wavelength MAD pair of one crystal - one dataset per wavelength

refused (keep separate)

lyso_x10sa_90deg_pair

inhouse/lyso_x10sa_90deg_1

2

two sweeps of one crystal at the same orientation, 42 s apart

all join

lyso_x10sa_two_crystals

inhouse/lyso_x10sa_90deg_1

2

keep separate: two lysozyme crystals of one form at one wavelength whose intensities differ (cells 1 % apart)

one left out (keep separate)

Datasets published as Raw Data Letters

Five of the datasets - 6R72, 8QQ7, 6RLR, laspartic and onitroaniline - were published as IUCrData Raw Data Letters, a format whose purpose is to make raw images citable and re-processable in their own right. The letters describe the collections and the difficulties in them, and are the reference for what the data are:

  • V. Zampieri, A. Vermot, M. Thepaut, I. Petit-Hartlein, F. Fieschi, P. Falson and V. Chaptal, “X-ray diffraction images for two membrane protein crystals presenting high anisotropy; the B. subtilis ABC transporter BmrA and the S. pneumoniae NADPH oxidase” (2025), IUCrData 10, x250591 doi:10.1107/S2414314625005917 - covers 6R72 and 8QQ7.

  • V. Neviani, M. Lutz, W. Oosterheert, P. Gros and L. Kroon-Batenburg, “Crystal structure of the second extracellular domain of human tetraspanin CD9: twinning and diffuse scattering” (2022), IUCrData 7, x220852 doi:10.1107/S2414314622008525 - covers 6RLR.

  • M. Lutz and L. Kroon-Batenburg, “Accurate intensity integration in the twinned γ-form of o-nitroaniline” (2022), IUCrData 7 doi:10.1107/S2414314622010598 - covers onitroaniline.

  • M. Lutz, “Twinned L-aspartic acid” (2025), IUCrData 10 doi:10.1107/S241431462500879X - covers laspartic: a twofold rotation about [100] with twin index 2 and obliquity 0.74°, whose coincidence lattice is the doubled cell first reported for the compound (Bernal, 1931).

The authors of the second letter also published their own reciprocal-space reconstruction of the 6RLR data as a separate Zenodo record, 10.5281/zenodo.6961763.

Twinned and pseudo-symmetric datasets

The rows below are twinned, or have a lattice metrically close to a higher symmetry than the crystal’s - the case where a data-reduction program is most easily led into the wrong point group. What is said here is read from the depositions and their cells, except where a sentence says otherwise; where the battery keeps further evidence for a row, it is in tools/battery/symmetry/<id>/.

The pathological-data series. 2WNN, 2WNQ, 2WNZ, 2XFW and 4BWL come from one Zenodo record, “A series of pathological macromolecular crystallography datasets with twinning and other lattice disorders” (10.5281/zenodo.54568), which was published for testing data-processing and refinement programs and is described in I. Campeotto, A. Lebedev, A. M. M. Schreurs, L. M. J. Kroon-Batenburg, E. Lowe, S. E. V. Phillips, G. N. Murshudov and A. R. Pearson, “Pathological macromolecular crystallographic data affected by twinning, partial-disorder and exhibiting multiple lattices for testing of data processing and refinement tools” (2018), Sci. Rep. 8, 14876 doi:10.1038/s41598-018-32962-6. All five are deposited in P 1 21 1 with c cos β ≈ -a/2, so the lattice is metrically C-centred orthorhombic, and the twin law four of them declare, -h,-k,h+l, is the two-fold that orthorhombic lattice adds:

PDB

Deposited twin fraction of -h,-k,h+l

4BWL

0.488

2WNQ

0.463

2WNN

0.334

2XFW

0.096

2WNZ

none declared

At a fraction near 0.5 the intensities have the symmetry of C 2 2 21, so these rows test whether a twinned P 21 crystal is reported as C 2 2 21. For 4BWL and 2WNQ, refining the deposited model in each candidate group keeps P 21, and no C 2 2 21 operator maps the deposited chains onto each other; neither row accepts C 2 2 21 as an alternative.

8C3E is a home-source dataset deposited in P 31 2 1 with no twin law declared, whose intensities, the depositor’s included, read Laue class 6/mmm in POINTLESS: the operator that makes 6/mmm out of -3m1 is a merohedral twin law of P 31 2 1, and refining the deposited model keeps P 31 2 1. The 75° scan also leaves the screw along c open; a run that names that axis as undetermined and offers the deposited group among its alternatives scores the row unscored (screw_undetermined, see tools/battery/README.md) rather than failed.

3MC4 and 3R6O carry a reference_mismatch note in the manifest: the uploaded frames are of a crystal twinned about 30% (law k,h,-l, seen also by XDS on the same frames), while the deposited data are of an untwinned crystal of the same form. The row is scored as usual; the note tells the reader of a report that the merged statistics are not expected to match the deposition’s.

Pseudo-symmetric cells. 6OWW (P 1 21 1, a ≈ b, β = 89.9°), 6P8J (P 1 21 1, β = 90.1°), 9QW2 (P 1 21 1, a ≈ c, β = 90.9°), 5OJV (P 21 21 2, a ≈ c), 7Q6J (P 21 21 21, b ≈ c) and 9QVV (I 2 2 2, b ≈ c) all have a deposited cell within a fraction of a degree or of an ångström of a higher lattice symmetry. 6OWW is one of the rows that accept an alternative answer, below.

Detector column for marCCD and SMV files

marCCD and SMV files name the detector differently - or not at all. A marCCD file names no model: its instrument header states the image dimensions and the pixel size, from which the plate size follows (3072 x 73.242 um = 225 mm, 4096 x 73.242 um = 300 mm), and its comment block a serial number; the LS-CAT beamlines additionally write detector='Rayonix MX-300 s/n 023' into the dataset comment. An ADSC-style SMV header names only a serial (DETECTOR_SN=930); a Rigaku d*TREK one names the model (CCD_DETECTOR_DESCRIPTION=Saturn944+), and that is what its row carries. For those rows the Detector column carries what the file itself establishes: the plate size (marCCD, 225 mm plate), the comment’s name where one is present (Rayonix MX-300), or the serial (SMV, S/N 930).

8C3E’s files are CBF written by CrysAlisPro’s HPAD export, whose header gives the image size (# Detector: 775 x 800) and no model; its row carries that (CrysAlisPro HPAD, 775 x 800). The PDB entry names the detector as a Rigaku HyPix-6000HE.

Deposited models and structure factors

All 204 PDB entries in the table are released, and RCSB reports released structure factors (status_code_sf = REL) for every one of them; the eight small-molecule datasets have none. A merged result from this pipeline can therefore be checked against the deposited model or against the deposited intensities.

Rows where our reduction and the deposition disagree

Seven of the battery’s rows are ones where rugnux does not reproduce the deposited space group or cell, and where we have looked at the disagreement closely enough to change how the row is scored. They are collected here because a scoring row that silently disagrees with a published entry is not something a reader should have to discover from the code.

These are open questions, not errors we are attributing to the PDB. A deposited entry was arrived at by someone who had something we do not: a model that had to refine, and usually more knowledge of the crystal than the images carry. Where we describe evidence below, it is evidence about what these images support, which is a narrower thing than what the crystal is. In every one of the symmetry rows the possibility that the crystal really has the lower symmetry, with a pseudo-symmetry too exact for any test available to us to see, remains live - see the limit at the end of this section.

How the manifest records it, in tools/battery/open.json:

  • ref always keeps the deposited values verbatim, so the deposition is never lost.

  • ref_alternatives lists the other answers the row accepts. Each one replaces the reference fields it names - a space group, a cell, or both - and the row passes if our answer matches any of the references, the deposited one included. Each must carry why; an alternative with no stated reason is a schema error, not a silent pass, so the mechanism cannot become a way to turn a failure into a pass quietly. This is how the six knife-edge rows below are recorded: we are not asserting that our answer is right, only that both descriptions are defensible and that picking either one is acceptable. The report counts these rows separately from ordinary passes and prints the reason, so a reader can see how many there are and judge each.

  • ref_override replaces the fields the battery scores against, with ref_override_why. It asserts a corrected reference, so it is for a reference we can show to be wrong about these images - 8XBP below - and not for a disagreement that is open.

  • unscored drops the row from scoring entirely. It is a last resort: it also loses a test that still works, which is why an open question is now recorded as accepted alternatives instead.

8XBP is a question about provenance, not about symmetry

8XBP is different in kind from the other six and should not be read alongside them. Nothing here concerns the deposited model or its space group. The question is whether the raw images uploaded with the entry are the same crystal the deposited cell describes: the master file records data_collection_date 2023-06-21 where the entry records a collection date of 2023-06-23, and the deposited b = 50.78 A is 2.0% away from the b these images give. Two independent signals, one of them nothing to do with our processing. The override replaces the cell with the one DIALS 3.29 indexes de novo on this master and keeps the deposited space group and resolution.

Four trigonal and tetragonal rows where we read a higher point group

PDB

Deposited

rugnux reads

Where it stands

6TOC

P 42

P 42 2 2

both acceptable; the refinement test is not unanimous

8XTE

P 32

P 31 2 1 / P 32 2 1

both acceptable; ours is the better supported

8XTG

P 32

P 31 2 1 / P 32 2 1

both acceptable; the deposition is the better supported

6PXB

P 32

P 31 1 2 / P 32 1 2

both acceptable; unresolved in either direction

All four accept either answer: the deposited group and the one we read both pass. None of them is a claim that the deposited assignment is wrong - each is a question we cannot close, and 8XTE and 8XTG do not lean the same way, so they should not be read in one voice. The two 8XT* rows were for a time scored against our own answer by editing the reference itself, with no reason recorded; the deposition is back in ref verbatim and the disagreement is stated here.

6TOC. The deposited asymmetric unit holds two chains, and they are related by the very two-fold the higher group adds, to 0.16 A C-alpha RMSD over 43 residues - coordinate error at the deposited 1.85 A. Merging in P 42 2 2 costs 0.0006 in Rmeas for 1.75 times the multiplicity, and correlates better with the deposited model than the P 42 merge does. POINTLESS, run independently on our own P1 merge, reads the same point group. The refinement test - refine in each candidate group and compare R-free, which is the one comparison not biased toward the group the deposited model was refined in - does not come out unanimous: ZANUDA 1.097 makes P 42 2 2 the better group at half the parameters and reports the deposited assignment incorrect, while an independent Refmac 5.8.0431 comparison on a symmetry-consistent free set makes P 42 the better one, by less than the spread between refinement protocols - the spread of the test exceeds the effect it is being asked to measure. Both answers are therefore accepted, with the refinement evidence recorded as split.

8XTE. The distinguishing test is the twin-immune centric zone: reflections that the higher group makes centric but the subgroup does not are their own twin mates, so a merohedral twin law cannot make them read centric. They read <|E^2-1|> = 0.946 +/- 0.012 against a centric expectation of 0.968 and an acentric one of 0.736. Re-refinement on a shared free set, with the twin law removed from both sides, favours the higher group. The deposited entry’s published R values are themselves reproducible only with a twin law the entry does not declare, at a twin fraction of 0.50 - and a 0.50-twinned target already has the symmetry in question. Of the four rows this is the one where the evidence most clearly favours what we read; it still cannot be closed, because the centric zone is the only test that speaks to it (see the limit below), so both answers are accepted.

8XTG. This row is genuinely open and is flagged as such in the manifest. Every correlation-based instrument we have - our own operator correlations, and POINTLESS on our P1 merge - reads the higher point group, but the centric-zone test, the only one of them that can separate real symmetry from pseudo-symmetry, reads <|E^2-1|> = 0.869 at -44.9 nats: between the two expectations, and on the wrong side. The L-test indicates a twin fraction near 0.20-0.26. Whether this crystal is partially twinned or purely pseudo-symmetric has not been established. Here the better-supported answer is the deposited one, which is the opposite of 8XTE: the two rows look alike in the table and are not alike in the evidence. Both answers are accepted.

6PXB. Both answers accepted rather than overridden, because the evidence does not settle either way. Our merge and POINTLESS both read a 312 point group, the added two-folds correlate at or above the level of the three-folds nobody disputes, and merging in the higher group lowers Rmeas at twice the multiplicity. Against that, the deposited asymmetric unit’s six chains pair under the added two-fold at 0.3-0.7 A, which is more than coordinate error at 1.75 A, and ZANUDA settles on a different trigonal supergroup - 321 rather than 312 - whose operators these data do not support. Neither answer is established in either direction, so both are accepted and the row still tests everything else about the set.

9RCI: two defensible descriptions of one lattice

This row is not about symmetry but about which cell describes the crystal. The Patterson has an off-origin peak at 62.5% of the origin, so a genuine translational NCS relates the two halves of the cell rugnux reports, and the deposited cell is that supercell’s (0, 1/2, 1/2)-centred sublattice to 0.17%. Both are correct descriptions of the same diffraction: one leaves the near-translation in the contents of a doubled cell, the other absorbs it into the lattice and indexes only the strong sublattice. Which one a program should prefer is a choice, not a measurement, so the row accepts either. The alternative cell recorded in the manifest is computed from the deposited cell alone (c’ = b + 2c, centring removed), not copied from our output, so it stays a statement about the deposition’s lattice.

6OWW: a monoclinic deposition whose intensities read tetragonal

6OWW is deposited in P 1 21 1 with eight chains, on a cell with a ≈ b and β = 89.9°. The deposited model nearly obeys the added operators: a four-fold to 0.13-0.16 Å and a two-fold to 0.10 Å, and its |Fc|2 correlate across the added 422 operators at 0.97-1.00. POINTLESS reads Laue class 4/mmm both on our observations and on the depositor’s amplitudes, and ZANUDA, refining the deposited model in each candidate group, prefers P 43 21 2 to P 21 on our data and on the depositor’s, with lower R-free each time. The row accepts P 41 21 2 (the enantiomorph pair is counted as one by the scorer) beside the deposited group. As with the trigonal and tetragonal rows above, an exact pseudo-symmetry would explain the same observations, so this is an accepted alternative and not a statement that the deposition is wrong.

The limit that applies to all five symmetry rows

A merohedral twin at a twin fraction of exactly 0.5 and a crystal that genuinely has the higher symmetry predict identical intensities. No amount of data and no refinement R separates them, and the same holds, approximately, for a pseudo-symmetry that is merely very exact. Every test described above measures how nearly a symmetry operator holds on these images; none of them can show that it holds exactly. Where the higher symmetry is right, merging in it gains multiplicity and completeness; where it is a pseudo-symmetry that close, merging in it costs nothing measurable either. That is why these rows are described as open questions, and why none of them should be read as a statement that a deposited model is wrong.

Battery rows whose id is not the PDB code

Battery id

PDB code in the table

Why

7brr

7D1M

The IRRMC archive and its DOI are published under 7BRR, which the PDB obsoleted on 2020-10-28 and replaced with 7D1M. The battery id, the directory and the DOI keep the archive’s own name; the deposited values are 7D1M’s.

6h2p_native

6H2P

the 0.918 Å sweep of the 6H2P archive, which the deposition’s resolution belongs to

6h2p_1p89A

6H2P

the 1.893 Å sweep of the same crystal; scored on the deposited space group and cell only

Datasets in the table that are not in the battery

PDB

Why

7QT9

Twenty 20° wedges (200 × 0.1°) of in-situ crystals at room temperature, none complete on its own: the dataset is a multi-sweep row (7qt9_crystals, below), not a single-sweep one.

9VX7

The uploaded sweep does not index in the deposited cell, with rugnux or with DIALS or XDS given that cell, while XDS indexes it de novo in a different cell; the deposited values cannot be scored against these images, so the row is not in the battery.

An archive that ships placeholder images

8AGQ’s data/ directory contains 30 files named ForBackgroundOnly_000NN.img alongside the 1800-frame sweep. They are not images: each is a 64-byte text file holding a path string. A reader that globs *.img will pick them up, so they are named here rather than silently left.

Datasets with no PDB entry

Dataset

Repository record

Why there is no PDB code

cuhf2

Zenodo record 10.5281/zenodo.6347466

a small-molecule dataset, not a PDB deposition

dnba

Zenodo record 10.5281/zenodo.1036416

a small-molecule dataset, not a PDB deposition

metformin

Zenodo record 10.5281/zenodo.20135265

a small-molecule dataset, not a PDB deposition

nidppe

Zenodo record 10.5281/zenodo.20041091

a small-molecule dataset, not a PDB deposition

cytidine

Zenodo record 10.5281/zenodo.33555

a small-molecule dataset, not a PDB deposition

lalanine

Zenodo record 10.5281/zenodo.11946282

a small-molecule dataset, not a PDB deposition

laspartic

Zenodo record 10.5281/zenodo.15432050

a small-molecule dataset, not a PDB deposition

onitroaniline

Zenodo record 10.5281/zenodo.7193538

a small-molecule dataset, not a PDB deposition

Six of the eight small-molecule sets have a published structure to check a run against. These are reference values from the literature, not results obtained here.

Dataset

Space group

Cell (A, deg)

T

Reference

dnba

C 1 2/c 1 (15)

20.2635 8.7575 9.6697 / 90 109.941 90

30 K

the Zenodo record’s own title and the xia2.html the depositors ship inside it, corroborated by COD 4510614/4510615 - Cryst. Growth Des. 13 (2013) 1861-1871 doi:10.1021/cg300906j

metformin

P 1 21/c 1 (14)

7.9104 13.8794 7.9310 / 90 114.606 90

100 K

the hydrochloride, form I; COD 2108029 - Acta Cryst. B73 (2017) 10-22 doi:10.1107/S2052520616017844

nidppe

P 1 21/c 1 (14)

11.2779 13.3386 15.8739 / 90 98.7953 90

150 K

COD 2012031 - Acta Cryst. C57 (2001) 690-693 doi:10.1107/S0108270101003961

cytidine

P 21 21 21 (19)

13.98 14.788 5.119 / 90 90 90

296 K

β-cytidine; COD 2001311 - D. L. Ward, Acta Cryst. C49 (1993) 1789-1792 doi:10.1107/S0108270193003464

lalanine

P 21 21 21 (19)

5.791 5.944 12.269 / 90 90 90

100 K

COD 2311261 - S. Parsons, H. D. Flack, T. Wagner, Acta Cryst. B69 (2013) 249-259 doi:10.1107/S2052519213010014

laspartic

P 1 21 1 (4)

5.1237 6.9197 7.6006 / 90 100.442 90

150 K

twin fractions 0.537/0.463; COD 1577465 - M. Lutz, IUCrData 10 (2025) doi:10.1107/S241431462500879X

onitroaniline has no cell here: the letter describing it could not be retrieved when the row was added, so a run on it is not scored against a reference.

cuhf2 has no confirmed cell. Its space group is published as P 4/n m m (Phys. Rev. B 81, 064422 (2010) doi:10.1103/PhysRevB.81.064422) but no numeric cell was located, so a run on it can be scored on the space group and not on the cell.

The collection in numbers

The collection was chosen to widen the spread of file formats, detectors, facilities and symmetries rather than to be easy to process. The counts below describe where it comes from; like everything else on this page, they are metadata about the depositions and their files, not measurements.

  • Repository, over the 212 datasets on this page (the 204 rows of the table and the eight small-molecule sets): IRRMC 97, Zenodo 45, SBGrid 40, MXRDR 16, Keele University 5, XRDa 5, ESRF 3, UQ eSpace 1.

  • Facility - counted from the facility part of the Facility / beamline column, the beamline ignored so that entries deposited with and without one count the same, over the 191 rows that name one: APS 29, Diamond 22, ESRF 19, NSLS-II 14, PETRA III 13, BESSY 12, SSRL 11, ALS 9, SLS 8, SPring-8 8, SOLEIL 7, SSRF 7, PAL/PLS 5, CHESS 4, ALBA 3, Australian Synchrotron 3, CLSI 3, ELETTRA 2, LNLS 2, MAX IV 2, NSLS 2, Photon Factory 2, and one each from NSRRC, RRCAT Indus-2, SRS Daresbury and EMBL/DESY Hamburg (DORIS) - 26 facilities. The other thirteen rows were collected on laboratory sources: eleven on rotating anodes, one on a liquid-metal jet and one on a sealed tube.

  • Crystal system, from the deposited space group of the 204 rows: monoclinic 54, orthorhombic 51, tetragonal 30, trigonal 22, hexagonal 20, cubic 14, triclinic 13.

  • Pink beam: none of these datasets was collected with pink beam. All 204 rows are deposited as SINGLE WAVELENGTH (_diffrn_radiation.pdbx_diffrn_protocol), and all but 5REO, which leaves the field blank, as monochromatic (pdbx_monochromatic_or_laue_m_l M); 9Q41 is the one row recorded with a multilayer rather than a crystal monochromator (CHESS Rh/B4C). The battery’s pink-beam data are in-house SLS measurements (tag pink-beam in tools/battery/inhouse.json), not on this page.

  • Long cell axes: sixteen rows have a deposited cell axis longer than 320 Å - 4P8R, 4MTK, 7D98, 8V4O, 9ZMU, 9V16, 9Z72, 4NWV, 9YL4, 5NW5, 6QAJ, 7QIJ, 8T7R, 9H0Q, 6G1F and 6OEL.

The marCCD, SMV, Bruker .sfrm, full-imgCIF and gzip-compressed miniCBF datasets are the reason rugnux reads those formats natively, and accepts the .img and numeric-suffix (.001) file names they arrive with.

Licences

Each dataset carries the licence of its own deposition, stated on the record page linked above. IRRMC and the SBGrid Data Bank both release under CC0 and both ask that the dataset’s own citation - its DOI - be used; the Zenodo records here are CC0 or CC BY 4.0, as each record states. None of these data are redistributed with Jungfraujoch; this page only records where they came from.

\ No newline at end of file diff --git a/EXTERNAL_TEST_DATA_STILLS.html b/EXTERNAL_TEST_DATA_STILLS.html new file mode 100644 index 000000000..9baacdb15 --- /dev/null +++ b/EXTERNAL_TEST_DATA_STILLS.html @@ -0,0 +1 @@ + External test data: serial crystallography (XFEL stills) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

External test data: serial crystallography (XFEL stills)

The serial datasets of the still battery (tools/battery/still_battery.py, manifest tools/battery/still_manifest.json). Like the rotation sets on External test data, they were collected by other people, on detectors and in file formats we do not produce ourselves, and published for exactly this kind of reuse. All of them come from the Coherent X-ray Imaging Data Bank (CXIDB). They are the eleven datasets of the Rugnux paper’s Extended Data Table 2, which gives the published results on them.

None of these data were collected by us. If you use any of them, cite the dataset DOI below and the paper of the entry.

Where the values come from

  • Dataset DOI: the CXIDB entry’s own DOI, resolved against DataCite before it was written down.

  • Space group, cell, resolution and R-free are the values deposited with the PDB entry, read from the RCSB data API. Every entry is a dark or ground state refined against observed data.

  • Images used are the frames in the files we use, counted in the files themselves. Where that is only part of the entry, the table says so and gives what the entry or the deposition holds.

Datasets

Set

CXIDB, dataset DOI

Facility / beamline

Detector, format

PDB

Space group, dmin (Å)

Paper

sacla243

243, 10.11577/17003933

SACLA BL2

MPCCD, 8 panels of 1024 x 512, 50 µm; Cheetah-SACLA HDF5

31JT

P 2 21 21, 1.63

Bibi, De Vrieze et al., J. Am. Chem. Soc. (2026)

sacla237

237, 10.11577/2999572

SACLA BL2

MPCCD; Cheetah-SACLA HDF5

9S06

P 21 21 21, 2.05

Rios-Santacruz et al., Nature (2026)

sacla236

236, 10.11577/3014306

SACLA BL2

MPCCD; Cheetah-SACLA HDF5

9V3D

P 43 21 2, 1.68

Kang et al., J. Appl. Cryst. (2026)

pal86

86, 10.11577/1502065

PAL-XFEL NCI

Rayonix MX225-HS, 1440 x 1440, 156 µm; Cheetah CXI

6IG7

P 61 2 2, 1.80

Park et al., Sci. Rep. (2019)

pal90

90, 10.11577/1511590

PAL-XFEL NCI

Rayonix MX225-HS; Cheetah CXI

6IRK

I 2 2 2, 1.75

Lee et al., Sci. Rep. (2019)

lcls222

222, 10.11577/2204603

LCLS MFX

Rayonix MX340-HS, 1920 x 1920, 177 µm; LCLS-I XTC

8TDQ

P 65 2 2, 1.65

Nguyen et al., J. Am. Chem. Soc. (2023)

lcls242_s, lcls242_t

242, 10.11577/3374214

LCLS MFX

Rayonix MX340-HS; LCLS-I XTC

9O4S (small cell), 9O4T (large cell)

P 1 21 1, 1.95

Wolff et al., bioRxiv (2026)

euxfel83

83, 10.11577/1464102

European XFEL SPB/SFX

AGIPD 1M, 16 modules of 512 x 128, 200 µm; Cheetah CXI

6GTH

P 32 2 1, 1.69

Wiedorn et al., Nat. Commun. (2018)

euxfel152

152, 10.11577/1660970

European XFEL SPB/SFX

AGIPD 1M; Cheetah CXI

6U57

I 2 3, 2.80

Echelmeier et al., Nat. Commun. (2020)

alvra103_int16

103, 10.11577/1650020

SwissFEL Alvra

JUNGFRAU 16M, 75 µm; SwissFEL HDF5, float32 keV (converted)

6S0L

C 2 2 21, 2.65

Nass et al., IUCrJ (2020)

alvra213_int16

213, 10.11577/2282689

SwissFEL Alvra

JUNGFRAU 4M, 75 µm; SwissFEL HDF5, float32 keV (converted)

8BKH (dark state)

P 1 21 1, 1.35

Barends et al., Nature (2024)

Every set of the manifest is in the table and every set in the table is in the manifest, with the same CXIDB entry, PDB entry, space group and dmin; tools/battery/doc_check.py checks this. The beamline of pal90 is the CXIDB entry’s (NCI); the PDB entry 6IRK records CSI.

How the battery runs them

Each set is one rugnux command, the way a serial user runs: the deposited cell and space group given (-C, -S), the wavelength where the files do not state it, --crystfel-geometry for the AGIPD and JUNGFRAU sets (the geometry file of the entry; the SACLA, PAL and LCLS files are placed without one), and the deposited model with --model, so that the report carries its R-free against the merge. The exact arguments are the args of each set in tools/battery/still_manifest.json; the stills section of the tutorial explains them.

The files we use

Paths are relative to the still data root of the site config (tools/battery/README.md). CXIDB serves https://cxidb.org/data/<entry>/...; most of it accepts HTTP range requests, so a broken download resumes with curl -C -.

Set

Files

Images used

Of the entry

Size

sacla243

sacla_243/raw_all/run*.h5: all 87 files of 243/Complete_dark/

52,151

all (the deposition’s 52,151)

198 GB

sacla237

sacla_237/raw/: the 18 files run130637-0 to run130642-2 of 237/SACLA_raw/2022Nov/dark_ref/

10,792

subset: 18 of about 1,000 dark_ref files, about 1.8% of ~600,000 hits

48 GB

sacla236

sacla_236/raw/: the 18 files run157084-0 to run157089-2 of 236/Data/lyso01-apo-bigXtal/

16,083

all (the deposition’s 16,083)

67 GB

pal86

pal_86/raw/, pal_86/raw_more/: CXIDB_86_themolysin_{2..25}_SFX_Nam.cxi (file 1 is truncated on the server and cannot be opened)

49,193

all but file 1 (24 of 25 files)

111 GB

pal90

pal_90/raw/: CXIDB_90-GI_SFX-filter-r00{01..14}-c00.cxi

79,805

all 14 filtered files of the entry

159 GB

lcls222

lcls_222/xtc/, lcls_222/xtc_more/: mfx/mfxlu5017/xtc/e1277-r0165-{s00-c00,s00-c01,s01-c00,s01-c01,s02-c00}.xtc (run 165, the substrate-bound state of 8TDQ)

8,534

subset: run 165 of the runs 165-168 behind 8TDQ

72 GB

lcls242_*

lcls_242/xtc/, lcls_242/xtc_more/: xtc/mfxl1013721-r0256 to r0267 streams (the two crystal forms are in every run; each set keeps its own form)

82,388

subset: runs 256-267 (47 of about 220 stream files; ~570 GB of ~3 TB)

~570 GB

euxfel83

euxfel_83/raw/: the 30 Cheetah hit files XFEL-r0243-c00.cxi to XFEL-r0292-c00.cxi (runs 243-254, 270-276, 278-281 and 286-292, the r<run>-blac/XFEL-r<run>-c00.cxi of the entry’s cheetah-calib-mar-v1/hdf5/ tree on the NERSC archive); euxfel_83/ref/agipd_mar18_v10.geom from the entry

14,445

all (the deposited stream’s 14,445)

25 GB

euxfel152

euxfel_152/raw/: all 221 Cheetah hit files XFEL2042-r0099-c00.cxi to XFEL2042-r0420-c00.cxi of XFEL2042-runs-cxi.tar (extracted with range requests on the tar members); euxfel_152/ref/kdo_embedded.geom, the geometry embedded in the header of the entry’s KDO8PS.stream

33,528

all the hit files of the entry’s tar; the deposited stream has 37,006 frames

53 GB

alvra103_int16

swissfel_103/conv/run*_int16.h5: int16 copies (see below) of 59 runs of the entry’s Raw_Files/<day>/a2a/run<N>.JF06T32V01.h5, run9 to run67 of 2018-08-07 and run1 to run3 of 2018-08-08 (named run0808_1 to _3); swissfel_103/ref/jf-16M.geom and the pixel mask swissfel_103/ref/run47.JF06T32V01.mask.h5 from the entry; the set reads swissfel_103/ref/jf-16M_mask.geom, a copy with mask_file pointed at that mask (see below)

53,734

subset: 59 runs of two days; the deposition indexed 199,136 of 2,251,787 images

172 GB of copies

alvra213_int16

swissfel_213/conv/march_dark_MbCO_II-March-06/data/dark/run_*_int16.h5: int16 copies (see below) of swissfel_213/raw/march_dark_MbCO_II-March-06/data/dark/run_*.JF06T08V01.h5, from march/march_dark_MbCO_II-March-06.tar.gz (425 GB; download it to disk and extract, a streamed extraction does not survive a broken connection); swissfel_213/ref/mbco_march.geom from the JUNGFRAU geometry template of 2019-MARCH-SwissFEL-MbCO-supplement.tar.gz; the pixel mask of run 243 (data/pixel_mask/ in the same tarball) is used for all runs, through swissfel_213/ref/mbco_march_mask.geom, a copy with mask_file pointed at it (see below)

28,428

all 23 dark runs with frames of the March 2019 series

46 GB of copies (430 GB of source)

The masks of the SwissFEL geometry files. rugnux takes the pixel masks and bad regions a CrystFEL geometry file names. The SwissFEL files name their mask with an absolute path on the facility’s disk, so each set reads a copy whose mask_file is relative to the copy’s own directory (a relative mask file is looked for in the working directory first, as CrystFEL does, then beside the geometry file): swissfel_103/ref/jf-16M_mask.geom is jf-16M.geom with mask_file = run47.JF06T32V01.mask.h5, and swissfel_213/ref/mbco_march_mask.geom is mbco_march.geom with mask_file = ../raw/march_dark_MbCO_II-March-06/data/pixel_mask/run_000243.JF06T08V01.mask.h5. Only that line differs.

The _int16 sets. The SwissFEL files store converted JUNGFRAU data as uncompressed float32 keV, 68 MB (JF16M) or 17 MB (JF4M) a frame, which caps reading at about 74 or 295 frames/s at 5 GB/s. The _int16 sets are copies with the same layout in which /data/data holds whole photons (keV divided by the photon energy, rounded) as int16 with bitshuffle/LZ4, about 25 times smaller. The battery runs only the copies: they merge to the same numbers as the float32 originals (rugnux measures the gain from the frames), and the originals are kept only as the source of the conversion and as a test of the format. Make them with tools/battery/still/float32_to_int16.py <in.h5> <out.h5> <photon energy keV> (h5py and hdf5plugin), into swissfel_103/conv/ (4.57 keV) and swissfel_213/conv/ (12.037 keV, keeping the tarball’s directory tree), named <input>_int16.h5. One MbCO dark run (run_000238) holds no frames and has no copy.

\ No newline at end of file diff --git a/FPGA.html b/FPGA.html new file mode 100644 index 000000000..6e0059cda --- /dev/null +++ b/FPGA.html @@ -0,0 +1,16 @@ + FPGA smartNIC — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FPGA smartNIC

See separate document for installation instructions.

Hardware

Currently supported FPGA is only Xilinx Alveo U55C.

See AMD/Xilinx webpage for card user guide (UG1469). According to the user guide:

Alveo data center accelerator cards are designed to be installed into a data center server, where controlled air flow provides direct cooling.
+

The card needs to be placed in a PCI Express (PCIe) Gen4 x8 slot, though mechanically slot has to accommodate x16 card. There is no need to connect additional power cable, as power of the card is not exceeding 75 W load available from PCIe edge connector. Current power estimation is about 30 W when idle and 45 W in operation. The card has built-in protection, which will cut power to the card if HBM temperature is above 120°C.

Two variants of the card are available:

  • 100g - this variant operates one port in 100 Gbit/s mode and should be used when connecting detector via a switch.

  • 8x10g - this variant operates both QSFP ports at 4x10 Gbit/s. QSFP+ (40 Gbit/s) transceivers and MTO/MTP harness cables are necessary. It is designed for detector directly connected to the Jungfraujoch server, without switch.

See network documentation for details of network.

Building firmware

The firmware build targets are generated by CMake only when vivado and vitis_hls are detected in the path, and the Vivado version has to match the one below precisely.

Xilinx Vivado

The following procedures require having AMD (Xilinx) Vivado and Vitis HLS toolsets version 2022.2 installed on the machine. Due to the nature of TCL scripts used to generate board designs Vivado version has to exactly match one provided above - specifically newer versions of Vivado will not work.

In addition to the Intellectual Property (IP) cores included in Vivado, two additional licenses are necessary:

  • Non-cost license for Ultrascale+ 100G core has to be requested from AMD/Xilinx website, see Xilinx website, to build 100g design.

  • A paid license for the 10G/25G Ethernet Subsystem for Ultrascale+ is necessary to build the 8x10g design. PSI received non-cost licenses from Xilinx University Program for the latter cores. Therefore, usage of bitstreams generated by PSI continuous integration pipeline for 8x10g is only allowed for non-commercial use.

HLS compilation

Make HLS routines:

mkdir build
+cd build
+cmake ..
+make hls
+

Synthesis

Create PCIe 100g bitstream with the following command:

mkdir build
+cd build
+cmake ..
+make pcie_100g
+

and 8x10g:

mkdir build
+cd build
+cmake ..
+make pcie_8x10g
+

When Vivado is not present

During CMake execution, the following executables: vivado and vitis_hls must be present in the path. If not, build targets will not be generated, and such or similar error message will show up:

$ make pcie_100g
+make: *** No rule to make target 'pcie_100g'.  Stop.
+

Firmware releases

The firmware is stable and is carried from version to version: the MCS files attached to a release are normally the ones from the release before it (see Release contents). When it does need to change, it is rebuilt with the targets above on a machine with Vivado.

Frame generator

The Jungfraujoch card is equipped with a frame generator. It allows simulating a JUNGFRAU detector without having access to such a system. It sits in parallel with the Ethernet MAC, so it is placed before the network stack and before any processing happening on the card. In the future a redirection will be possible to send the simulated stream through the 100G TX network link. Frame generator is written in HLS and controlled with AXI-Lite.

\ No newline at end of file diff --git a/FPGA_DATA_ANALYSIS.html b/FPGA_DATA_ANALYSIS.html new file mode 100644 index 000000000..f97c8be6c --- /dev/null +++ b/FPGA_DATA_ANALYSIS.html @@ -0,0 +1 @@ + FPGA data analysis — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FPGA data analysis

Jungfraujoch FPGA design has incorporated X-ray diffraction image analysis capabilities.

Pixel mask

Pixels can be masked. For each module a 32-bit map of pixels is loaded to FPGA, with non-zero value meaning masked pixels. According to this map, pixels will be assigned a special value (minimum number for signed types and maximum number for non-signed types) and will be excluded from subsequent analysis.

ADU histogram

Before conversion to photons/energy, an ADU histogram can be calculated for a module. This allows to preserve some signature of unconverted values. This is done on a module-basis and works with bins with 32 ADU width.

For EIGER this can be used as just a histogram procedure.

JUNGFRAU conversion

For JUNGFRAU, module images are converted from ADUs to an energy value and divided by a given number to give units of keV. Result of the operation is rounded to integers.

Pixel thresholding

Pixel range can be specified. Pixels below a minimum threshold will be assigned zero. Pixels above a maximum threshold will be assigned saturated pixel value (the largest number for a given bit-width and sign type). This is specifically designed to operate on unsummed frames, so frame-specific parameters (overload/noise) can be handled.

Frame summation

Frames can be summed together (on a per-module basis) in Jungfraujoch, with a limit of 256 frames added together.

Azimuthal integration

To implement azimuthal integration, FPGA is able to sum pixels based on a provided integration map and per-pixel corrections. This way Jungfraujoch implements azimuthal integration with solid angle and polarization corrections. Corrections were implemented according to formulas developed by Jensen et al. (J. Synchrotron Rad., 29, 1420-1428, 2022).

Given FPGA limitations, split-pixels cannot be implemented and number of bins is limited to 2048 per detector module. This way 2D azimuthal integration, as needed for example by SAS-TT, cannot be currently implemented with the FPGA card and needs to be done on a CPU. One needs to be careful with per-pixel corrections - their acceptable range is constrained by 16-bit fixed point integer implementation and is tuned for standard SAXS/WAXS range.

As with ROIs, azimuthal integration is also available on CPU through the shared analysis library, so it applies to both the FPGA-accelerated (JUNGFRAU/PSI) and the DECTRIS-driven (EIGER) workflows.

Spot finding

Jungfraujoch FPGA implements a built-in spot finder. Spot finder allows to apply the following criteria for finding strong pixels:

  1. Resolution criterion - pixels only within a provided resolution range can be considered as strong pixels (calculating resolution map needs to happen on CPU before data collection run).

  2. Bad pixels - pixels marked as bad, as well as chip edges and module edges are excluded from spot finding,

  3. Overloads - pixels marked as overloads on JUNGFRAU are always included in the strong pixel output, but are excluded for signal-to-noise ratio calculation,

  4. Pixel value - pixels above certain threshold value can be marked as strong,

  5. Signal-to-noise (SNR) ratio - pixels with SNR above a threshold can be marked as strong,

  6. Connected pixels - strong pixels can be discarded if they are “alone”, so their 8 directly neighboring pixels are not counted as strong pixels.

All the above criteria except the bad-pixel criterion are optional (can be turned off); only pixels that fulfill all enabled criteria are selected as strong pixels.

SNR ratio calculation

Signal-to-noise ratio is calculated for a rectangular area. In horizontal direction the area is fixed - line of 1024 pixels is divided into 32 areas each of 32 pixels. This is dictated by the data flow within the FPGA. In vertical direction the area is flexible - it is 15 lines above and below of the given pixel. Given the very large box size, approximations are made, for example that N ≈ N-1 in calculating standard deviation.

Region-of-interest (ROI) integration

There are 16 ROIs, and the ROI map holds a 16-bit mask per pixel, so a pixel can belong to any subset of them (including none). For each ROI, sum, sum of squares, max count, and number of valid pixels will be calculated. Jungfraujoch also calculates X and Y values weighted by pixel values, though this feature is not properly tested at the moment and not integrated in downstream analysis.

ROIs are not specific to the FPGA path. The same ROI definitions — box, circle, and azimuthal (Q-range with an optional φ-sector) — are also evaluated on CPU by the shared image_analysis/roi/ engine, so ROI statistics are produced both for the FPGA-accelerated JUNGFRAU/PSI workflow and for detectors driven through DECTRIS SIMPLON (e.g. EIGER), which have no FPGA acquisition path.

Pixel statistics

The following statistics are collected for each module:

  • Number of masked pixels

  • Number of saturated pixels (excl. masked)

  • Number of error pixels (excl. masked)

  • Sum of valid pixels in the module

  • Minimum value of valid pixels in the module

  • Maximum value of valid pixels in the module

Valid pixels are not masked, not saturated, not error pixels.

These are not specific to the FPGA path: the CPU and GPU image preprocessors of the shared image_analysis/ library collect the same statistics per image, for detectors driven through DECTRIS SIMPLON (e.g. EIGER) and for rugnux. There the sum excludes only the device mask (detector and calibration), not the hot pixels, the beam-stop shadow and the inactive pixels a run finds on its own frames.

Square root compression

Jungfraujoch FPGA includes lossy compression preserving counting statistic properties of X-ray image, while reducing bit width of an image. Scheme was described in Wakonig et al., J. Appl. Cryst., 53, 574-586, 2020. Pixel value X is replaced with round(sqrt(N*N*X)), i.e. round(N*sqrt(X)), where N is integer constant in range 1 to 16. N is what the host writes to the sqrtmult register; the FPGA squares it before multiplying the pixel value.

\ No newline at end of file diff --git a/FPGA_DESIGN.html b/FPGA_DESIGN.html new file mode 100644 index 000000000..c572a1fd7 --- /dev/null +++ b/FPGA_DESIGN.html @@ -0,0 +1 @@ + FPGA data flow — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FPGA data flow

The following steps are performed on FPGA (in the order of operation):

  1. UDP header decoding

  2. SLS detector header decoding

  3. State machine that controls data acquisition (start/stop/cancel)

  4. High-bandwidth memory cache to buffer network packets and reorder them to form full modules

  5. ADU histogram for JUNGFRAU

  6. Mask pixels from missing packets with special value

  7. Reorder lines for EIGER to form a proper module

  8. Mask pixels based on provided pixel mask

  9. JUNGFRAU conversion with gain and pedestal corrections

  10. Threshold: pixel values below a set minimum are zeroed, values above a set maximum saturated

  11. Frame summation (up to 256 frames)

  12. Integration according to predefined map (e.g., 1D azimuthal integration)

  13. Spot finding

  14. ROI calculation

  15. Image lossy compression using N*sqrt(pixel) values

  16. Send images, analysis results and metadata to host memory via PCI Express

Each step has a dedicated core, written in high-level synthesis. Exact operation of cores for data analysis is explained in dedicated document.

\ No newline at end of file diff --git a/FPGA_LICENSE.html b/FPGA_LICENSE.html new file mode 100644 index 000000000..6bc193d74 --- /dev/null +++ b/FPGA_LICENSE.html @@ -0,0 +1,7 @@ + FPGA license — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FPGA license

FPGA components of Jungfraujoch are licensed using OHL-S license. See full text below. The license is equivalent of GNU Public License with adaptations for hardware. See OHL webpage for details and FAQs.

CERN Open Hardware Licence Version 2 - Strongly Reciprocal

Preamble

CERN has developed this licence to promote collaboration among hardware designers and to provide a legal tool which supports the freedom to use, study, modify, share and distribute hardware designs and products based on those designs. Version 2 of the CERN Open Hardware Licence comes in three variants: CERN-OHL-P (permissive); and two reciprocal licences: CERN-OHL-W (weakly reciprocal) and this licence, CERN-OHL-S (strongly reciprocal).

The CERN-OHL-S is copyright CERN 2020. Anyone is welcome to use it, in unmodified form only.

Use of this Licence does not imply any endorsement by CERN of any Licensor or their designs nor does it imply any involvement by CERN in their development.

1 Definitions

1.1 ‘Licence’ means this CERN-OHL-S.

1.2 ‘Compatible Licence’ means

a) any earlier version of the CERN Open Hardware licence, or

b) any version of the CERN-OHL-S, or

c) any licence which permits You to treat the Source to which it applies as licensed under CERN-OHL-S provided that on Conveyance of any such Source, or any associated Product You treat the Source in question as being licensed under CERN-OHL-S.

1.3 ‘Source’ means information such as design materials or digital code which can be applied to Make or test a Product or to prepare a Product for use, Conveyance or sale, regardless of its medium or how it is expressed. It may include Notices.

1.4 ‘Covered Source’ means Source that is explicitly made available under this Licence.

1.5 ‘Product’ means any device, component, work or physical object, whether in finished or intermediate form, arising from the use, application or processing of Covered Source.

1.6 ‘Make’ means to create or configure something, whether by manufacture, assembly, compiling, loading or applying Covered Source or another Product or otherwise.

1.7 ‘Available Component’ means any part, sub-assembly, library or code which:

a) is licensed to You as Complete Source under a Compatible Licence; or

b) is available, at the time a Product or the Source containing it is first Conveyed, to You and any other prospective licensees

i) as a physical part with sufficient rights and information (including any configuration and programming files and information about its characteristics and interfaces) to enable it either to be Made itself, or to be sourced and used to Make the Product; or ii) as part of the normal distribution of a tool used to design or Make the Product.

1.8 ‘Complete Source’ means the set of all Source necessary to Make a Product, in the preferred form for making modifications, including necessary installation and interfacing information both for the Product, and for any included Available Components. If the format is proprietary, it must also be made available in a format (if the proprietary tool can create it) which is viewable with a tool available to potential licensees and licensed under a licence approved by the Free Software Foundation or the Open Source Initiative. Complete Source need not include the Source of any Available Component, provided that You include in the Complete Source sufficient information to enable a recipient to Make or source and use the Available Component to Make the Product.

1.9 ‘Source Location’ means a location where a Licensor has placed Covered Source, and which that Licensor reasonably believes will remain easily accessible for at least three years for anyone to obtain a digital copy.

1.10 ‘Notice’ means copyright, acknowledgement and trademark notices, Source Location references, modification notices (subsection 3.3(b)) and all notices that refer to this Licence and to the disclaimer of warranties that are included in the Covered Source.

1.11 ‘Licensee’ or ‘You’ means any person exercising rights under this Licence.

1.12 ‘Licensor’ means a natural or legal person who creates or modifies Covered Source. A person may be a Licensee and a Licensor at the same time.

1.13 ‘Convey’ means to communicate to the public or distribute.

2 Applicability

2.1 This Licence governs the use, copying, modification, Conveying of Covered Source and Products, and the Making of Products. By exercising any right granted under this Licence, You irrevocably accept these terms and conditions.

2.2 This Licence is granted by the Licensor directly to You, and shall apply worldwide and without limitation in time.

2.3 You shall not attempt to restrict by contract or otherwise the rights granted under this Licence to other Licensees.

2.4 This Licence is not intended to restrict fair use, fair dealing, or any other similar right.

3 Copying, Modifying and Conveying Covered Source

3.1 You may copy and Convey verbatim copies of Covered Source, in any medium, provided You retain all Notices.

3.2 You may modify Covered Source, other than Notices, provided that You irrevocably undertake to make that modified Covered Source available from a Source Location should You Convey a Product in circumstances where the recipient does not otherwise receive a copy of the modified Covered Source. In each case subsection 3.3 shall apply.

  You may only delete Notices if they are no longer applicable to
+  the corresponding Covered Source as modified by You and You may
+  add additional Notices applicable to Your modifications.
+  Including Covered Source in a larger work is modifying the
+  Covered Source, and the larger work becomes modified Covered
+  Source.
+

3.3 You may Convey modified Covered Source (with the effect that You shall also become a Licensor) provided that You:

a) retain Notices as required in subsection 3.2;

b) add a Notice to the modified Covered Source stating that You have modified it, with the date and brief description of how You have modified it;

c) add a Source Location Notice for the modified Covered Source if You Convey in circumstances where the recipient does not otherwise receive a copy of the modified Covered Source; and

d) license the modified Covered Source under the terms and conditions of this Licence (or, as set out in subsection 8.3, a later version, if permitted by the licence of the original Covered Source). Such modified Covered Source must be licensed as a whole, but excluding Available Components contained in it, which remain licensed under their own applicable licences.

4 Making and Conveying Products

You may Make Products, and/or Convey them, provided that You either provide each recipient with a copy of the Complete Source or ensure that each recipient is notified of the Source Location of the Complete Source. That Complete Source is Covered Source, and You must accordingly satisfy Your obligations set out in subsection 3.3. If specified in a Notice, the Product must visibly and securely display the Source Location on it or its packaging or documentation in the manner specified in that Notice.

5 Research and Development

You may Convey Covered Source, modified Covered Source or Products to a legal entity carrying out development, testing or quality assurance work on Your behalf provided that the work is performed on terms which prevent the entity from both using the Source or Products for its own internal purposes and Conveying the Source or Products or any modifications to them to any person other than You. Any modifications made by the entity shall be deemed to be made by You pursuant to subsection 3.2.

6 DISCLAIMER AND LIABILITY

6.1 DISCLAIMER OF WARRANTY – The Covered Source and any Products are provided ‘as is’ and any express or implied warranties, including, but not limited to, implied warranties of merchantability, of satisfactory quality, non-infringement of third party rights, and fitness for a particular purpose or use are disclaimed in respect of any Source or Product to the maximum extent permitted by law. The Licensor makes no representation that any Source or Product does not or will not infringe any patent, copyright, trade secret or other proprietary right. The entire risk as to the use, quality, and performance of any Source or Product shall be with You and not the Licensor. This disclaimer of warranty is an essential part of this Licence and a condition for the grant of any rights granted under this Licence.

6.2 EXCLUSION AND LIMITATION OF LIABILITY – The Licensor shall, to the maximum extent permitted by law, have no liability for direct, indirect, special, incidental, consequential, exemplary, punitive or other damages of any character including, without limitation, procurement of substitute goods or services, loss of use, data or profits, or business interruption, however caused and on any theory of contract, warranty, tort (including negligence), product liability or otherwise, arising in any way in relation to the Covered Source, modified Covered Source and/or the Making or Conveyance of a Product, even if advised of the possibility of such damages, and You shall hold the Licensor(s) free and harmless from any liability, costs, damages, fees and expenses, including claims by third parties, in relation to such use.

7 Patents

7.1 Subject to the terms and conditions of this Licence, each Licensor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in subsections 7.2 and 8.4) patent licence to Make, have Made, use, offer to sell, sell, import, and otherwise transfer the Covered Source and Products, where such licence applies only to those patent claims licensable by such Licensor that are necessarily infringed by exercising rights under the Covered Source as Conveyed by that Licensor.

7.2 If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Covered Source or a Product constitutes direct or contributory patent infringement, or You seek any declaration that a patent licensed to You under this Licence is invalid or unenforceable then any rights granted to You under this Licence shall terminate as of the date such process is initiated.

8 General

8.1 If any provisions of this Licence are or subsequently become invalid or unenforceable for any reason, the remaining provisions shall remain effective.

8.2 You shall not use any of the name (including acronyms and abbreviations), image, or logo by which the Licensor or CERN is known, except where needed to comply with section 3, or where the use is otherwise allowed by law. Any such permitted use shall be factual and shall not be made so as to suggest any kind of endorsement or implication of involvement by the Licensor or its personnel.

8.3 CERN may publish updated versions and variants of this Licence which it considers to be in the spirit of this version, but may differ in detail to address new problems or concerns. New versions will be published with a unique version number and a variant identifier specifying the variant. If the Licensor has specified that a given variant applies to the Covered Source without specifying a version, You may treat that Covered Source as being released under any version of the CERN-OHL with that variant. If no variant is specified, the Covered Source shall be treated as being released under CERN-OHL-S. The Licensor may also specify that the Covered Source is subject to a specific version of the CERN-OHL or any later version in which case You may apply this or any later version of CERN-OHL with the same variant identifier published by CERN.

8.4 This Licence shall terminate with immediate effect if You fail to comply with any of its terms and conditions.

8.5 However, if You cease all breaches of this Licence, then Your Licence from any Licensor is reinstated unless such Licensor has terminated this Licence by giving You, while You remain in breach, a notice specifying the breach and requiring You to cure it within 30 days, and You have failed to come into compliance in all material respects by the end of the 30 day period. Should You repeat the breach after receipt of a cure notice and subsequent reinstatement, this Licence will terminate immediately and permanently. Section 6 shall continue to apply after any termination.

8.6 This Licence shall not be enforceable except by a Licensor acting as such, and third party beneficiary rights are specifically excluded.

\ No newline at end of file diff --git a/FPGA_NETWORK.html b/FPGA_NETWORK.html new file mode 100644 index 000000000..3e546439a --- /dev/null +++ b/FPGA_NETWORK.html @@ -0,0 +1 @@ + FPGA network — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FPGA network

The U55C card is equipped with two network connectors - QSFP0 is the upper port and QSFP1 the lower port (when PCIe connector is on the bottom). The card FPGA design is offered in two variants 100g and 8x10g. These have different behavior regarding the network:

100g — this variant operates the QSFP0 port in 100 Gbit/s mode and should be used when connecting detector via a switch. QSFP28 transceivers are necessary.

8x10g — this variant operates both QSFP ports at 4x10 Gbit/s. QSFP+ (40 Gbit/s) transceivers and MTO/MTP harness cables are necessary. It is designed for detector directly connected to the Jungfraujoch server, without switch.

Transceivers

AMD doesn’t provide transceiver compatibility matrix for Alveo U55C. In our experience operating the card we haven’t seen issues with transceivers from various providers (FS.com, Mellanox, Finisar). We have also successfully operated card with correct direct attach cables instead of fiber optics. Given the card doesn’t support link training functionality of 100 Gbit/s ethernet, it could result in performance problems with copper cables, though we haven’t encountered such a situation.

Switch configuration

Special care has to be taken for switch operation, given the FPGA core doesn’t support auto-negotiation. It is necessary to configure switch port to fixed speed (100 Gbit/s or 10 Gbit/s) and to disable auto-negotiation. It is also necessary to enable jumbo frames (MTU of 9000).

Network LEDs

Each QSFP connector is equipped with green and orange LEDs. These LEDs are connected to Ethernet physical layer status port (rx_status). LED on corresponds to having a physical connection to a switch/computer/detector on the other side of the network. For 100 Gbit/s only green is used, for 8x10 Gbit/s green LEDs mean all ports connected, orange LEDs at least one of the ports connected.

Network stack

Each Ethernet link has its own basic network stack. Functionality for Ethernet/ARP/IPv4/ICMP is therefore separately handled for each port. Each link will get dedicated MAC address, and IPv4 addresses can be also assigned independently if needed.

The card will send gratuitous ARP messages every 5 seconds to keep its entry in switch MAC table. The card will also reply to ARP requests for its IP and to ICMP ping requests sent with the card IPv4 address. The card won’t respond to broadcast ICMP pings.

Each link can be put in direct mode. In this case destination Ethernet MAC and IPv4 addresses are not enforced for incoming UDP packets. This setting should be used for connecting detector modules directly to the FPGA card, so any detector module can be connected to any 10 Gbit/s link on the same card. Currently direct mode is turned OFF for 100g design and ON for 8x10g design. This can be manually adjusted for each link.

\ No newline at end of file diff --git a/FPGA_PCIE_DRIVER.html b/FPGA_PCIE_DRIVER.html new file mode 100644 index 000000000..3277c64db --- /dev/null +++ b/FPGA_PCIE_DRIVER.html @@ -0,0 +1,10 @@ + FPGA PCIe driver — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FPGA PCIe driver

Compilation

To compile the kernel module, type:

make
+

Installation

To install kernel module, you need to have root permissions and run:

sudo make install
+

Loading driver into kernel

After installing the kernel driver, it should be possible to insert it into the kernel via:

modprobe jfjoch
+

Ownership of the character devices

By default, character devices /dev/jfjoch<device number> are owned by root (user/group) and are not accessible by others. This means that jfjoch_broker must be running as superuser, which might not be optimal for security reasons in most cases. The behavior can be changed by creating udev rules. Create a file called /etc/udev/rules.d/99-jfjoch.rules with the following content:

KERNEL=="jfjoch*", OWNER="<UNIX username>", GROUP="<UNIX group>"
+

It is OK to provide only group, for example to make the devices accessible by group jungfrau:

KERNEL=="jfjoch*", GROUP="jungfrau"
+

DKMS

To avoid problems with updating the kernel, it is possible to use DKMS to autobuild Jungfraujoch kernel module, when new kernel is installed. For RHEL 8 it is well tested to use the RPM module built automatically from Jungfraujoch source. For other systems, it is necessary to follow the procedure below, though it is not well tested.

This first requires installing DKMS - for RHEL it is available via EPEL repository:

sudo dnf install dkms
+

Then use the script provided in the driver directory to copy driver code to DKMS directory:

./install_dkms.sh
+

If upgrading the driver, please first remove the current driver from DKMS system:

dkms remove jfjoch -v <version> --all
+

Driver parameters

Currently, there is one driver parameter nbuffers, that defines count of exchange buffers (see below). This can be adjusted in the modprobe operation, for example:

modprobe jfjoch nbuffers=1024
+

Exchange buffers

The parameter defines number of buffers used to exchange data between card and host application. Each buffer can hold one detector module (1024x512) in 16-bit or 32-bit mode + associated processing results and metadata. These buffers are used by both card-to-host and host-to-card operations.

Buffers use special allocation, as they are contiguous in physical address space, which helps the FPGA card to transfer all data associated with detector module in two DMA transfers (one data, one metadata). Useful buffer size is a bit more than 2 MiB, but given that kernel allocates physical memory in powers of two, 4 MiB is a safe number for one buffer size. A buffer can be mapped into user space by performing the mmap system call on the /dev/jfjoch<device number> character device.

Buffer count can be adjusted by setting nbuffers parameter. There are two considerations for setting optimal value:

  1. For card-to-host transfers, minimal value is roughly <number of threads in receiver> * <number of modules processed by thread; usually equal to number of modules per card>, this way each thread can have enough data for operation. Default thread count for Jungfraujoch receiver is 64.

  2. For host-to-card transfers, full detector calibration has to fit into memory and one buffer accommodates one calibration set for one module. So minimal count is <number of modules> * (3 + 3 * <number of storage cells>).

Based on both rules, optimal number is 512 buffers (2 GiB), though this can be adjusted for particular system and configuration.

Known problems

To avoid inconsistent behavior, this driver won’t load if release number differs between the kernel driver and FPGA card.

CMake file

While CMake file is present in the driver directory, it is only for the purpose of proper detection of the files in CLion IDE. It is not made for actual compilation of the kernel driver and should not be used for that purpose.

Character device access

For each FPGA device a character device is created called /dev/jfjoch<device number>. When the device is opened, two operations are possible:

  • mmap() to map exchange buffers

  • ioctl() to communicate with the card Interfacing should be done through the JungfraujochDevice class in fpga/host_library directory.

Sysfs access

Certain performance counters can be read through sysfs mechanism in the kernel. One needs to cat files in /sys/class/misc/jfjoch<device number>/ directory.

RHEL 9.5+ virtual memory flags

RedHat Enterprise Linux 9.5 backported the vm_flags_set interface from Linux kernel 6.3 while still reporting kernel version 5.14, so a plain kernel-version test picks the wrong branch and the build fails. This is now detected automatically from RHEL_RELEASE_CODE, so the module builds unaided on RHEL 9.5 and later and on the CentOS Stream, Rocky and AlmaLinux equivalents, as well as on distributions that have not backported it. No user action is needed. The HAVE_VM_FLAGS_SET environment variable that earlier releases required is obsolete; it is still honoured if set, but setting it is no longer necessary and the DKMS packaging never passed it anyway.

Which kernel DKMS builds for

The DKMS package builds the module for the kernel it is being installed for, not the one currently running, so a module built while a kernel update is being applied loads correctly after the reboot. Building by hand in fpga/pcie_driver/ still defaults to the running kernel; pass KDIR=/lib/modules/<version>/build (or KVER=<version>) to target another one.

\ No newline at end of file diff --git a/FPGA_SETTINGS.html b/FPGA_SETTINGS.html new file mode 100644 index 000000000..cc30460fa --- /dev/null +++ b/FPGA_SETTINGS.html @@ -0,0 +1 @@ + FPGA advanced reference — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FPGA advanced reference

Register map

FPGA setup can be done via registers:

Address

Bits

Meaning

Mode

Notes

0x000000 - 0x00FFFF

Reserved (in case using MicroBlaze in the future, this has to be reserved for internal memory)

0x010000

32

Action Control Register

Bit 0 - Action start

R/W

Bit 1 - Action idle

R

Bit 2 - Action cancel

R/W

cleared on reset or action start

Bit 3 - Clear network counters

R/W

cleared on reset

Bit 12:4 - Debug signals (see action_config.v for details)

R

Bit 16 - AXI Mailbox interrupt 0

R

0x010004

32

Reserved

-

0x010008

32

Reserved

-

0x01000C

32

GIT SHA1

R

0x010010

32

Reserved

R

0x010014

32

Reserved

R

0x010018

32

Jungfraujoch FPGA variant

R

0x01001C

32

Reserved

R

0x010020

32

Max. number of supported detector modules

R

constant

0x010024

32

Reserved

R

constant

0x010028

64

Pipeline stalls before writing to host memory

R

reset on action start

0x010030

64

Pipeline stalls before accessing HBM

R

reset on action start

0x010038

32

FIFO status (see action_config.v for details)

R

0x01003C

32

Size of single HBM channel in bytes (default value for the particular card)

R/W

should not be altered for standard operation

0x010040

64

Packets processed by the action

R

cleared on reset or action start

0x010048

64

Valid ethernet packets

R

cleared on reset

0x010050

64

Valid ICMP packets

R

cleared on reset

0x010058

64

Valid UDP packets

R

cleared on reset

0x010060

64

Valid detector packets processed by the card

R

cleared on reset

0x010068

64

Packets flagged as errors by CMAC

R

cleared on reset

0x010070

64

Pipeline stalls before data processing

R

reset on action start

0x010078

64

AXI-beats before accessing HBM

R

reset on action start

0x010080

64

AXI-beats before data processing

R

reset on action start

0x010088

64

AXI-beats before host writer

R

reset on action start

0x010090

64

Last encountered SwissFEL pulse ID

R

cleared on reset

0x010100

32

Spot finder photon count threshold

R/W

0x010104

32

Spot finder signal-to-noise ratio threshold (single-precision float)

R/W

0x010200

64

MAC address source for internal frame generator

R/W

network byte order

0x010208

32

IPv4 address source for internal frame generator

R/W

network byte order

0x01020C

32

Number of detector modules (value minus one: 0 => 1 module, 1 => 2 modules, etc.)

R/W

0x010210

32

Data collection mode

R/W

Bit 0 - Conversion to photons

Bit 1 - Output extend to 32-bit

Bit 2 - Output is unsigned integer

Bit 3 - Use sq. root lossy compression

Bit 7 - JUNGFRAU fixed G1 mode

Bit 8 - Set to zero values below threshold

Bit 31:16 - Data collection ID (carried with completions)

0x010214

32

Photon energy in keV (single-precision float)

R/W

0x010218

32

Number of frames expected in the data collection (defines termination condition)

R/W

0x01021C

32

Number of storage cells

R/W

0x010220

32

Summation on card (value minus one: 0 => summation of 1, 1 => summation of 2, etc.)

R/W

0x010224

32

Coefficient for sq. root compression (need to set bit in data collection mode to apply)

R/W

0x010228

32

Threshold minimum; values below are set to zero (need to set bit in data collection mode)

R/W

0x01022C

32

Threshold maximum; values above are set to the saturated value

R/W

0x030000 - 0x03FFFF

AXI Mailbox for Work Request / Work Completion

See Xilinx PG114 for register map

0x040000 - 0x04FFFF

QuadSPI flash

See Xilinx PG153 for register map

0x050000 - 0x05FFFF

Interrupt controller

See Xilinx PG099 for register map

0x060000 - 0x06FFFF

Load calibration (HLS)

0x070000 - 0x07FFFF

AXI Firewall

See Xilinx PG293 for register map

0x080000 - 0x08FFFF

Frame generator (HLS)

0x090000 - 0x09FFFF

PCIe DMA control

See Xilinx PG195 for register map

0x0A0000 - 0x0AFFFF

I2C clock generator

See Xilinx PG090 for register map

0x0C0000 - 0x0FFFFF

Xilinx Card Management Solution Subsystem

See Xilinx PG348 for register map

0x100000 - 0x10FFFF

MAC 10G / CMAC 100G

See Xilinx PG210/PG203 for register map

0x110000 - 0x11FFFF

MAC 10G

See Xilinx PG210 for register map

0x120000 - 0x12FFFF

MAC 10G

See Xilinx PG210 for register map

0x130000 - 0x13FFFF

MAC 10G

See Xilinx PG210 for register map

0x140000 - 0x14FFFF

MAC 10G

See Xilinx PG210 for register map

0x150000 - 0x15FFFF

MAC 10G

See Xilinx PG210 for register map

0x160000 - 0x16FFFF

MAC 10G

See Xilinx PG210 for register map

0x170000 - 0x17FFFF

MAC 10G

See Xilinx PG210 for register map

0x200000 - 0x20FFFF

Eth/IPv4 network stack for interface #0

0x210000 - 0x21FFFF

Eth/IPv4 network stack for interface #1

0x220000 - 0x22FFFF

Eth/IPv4 network stack for interface #2

0x230000 - 0x23FFFF

Eth/IPv4 network stack for interface #3

0x240000 - 0x24FFFF

Eth/IPv4 network stack for interface #4

0x250000 - 0x25FFFF

Eth/IPv4 network stack for interface #5

0x260000 - 0x26FFFF

Eth/IPv4 network stack for interface #6

0x270000 - 0x27FFFF

Eth/IPv4 network stack for interface #7

0x400000 - 0x47FFFF

64

Address table: decodes handles used by load_calibration and host_writer to DMA addresses

AXI Mailbox

AXI mailbox is used to send work request from host to action, and receive work completions. Messages are exchanged through AXI Mailbox IP from Xilinx (see Xilinx PG114).

Work request has the following structure:

Bit start

Bit end

Meaning

0

15

Work request ID (handle)

Work completion has the following structure:

Bit start

Bit end

Meaning

0

15

Work request ID (handle)

Special values:

65534 - start of data collection

65535 - end of data collection

16

31

Data collection ID

HBM memory

Interface number

Core

Meaning

0-1

jf_conversion

Gain factor G0

2-3

jf_conversion

Gain factor G1

4-5

jf_conversion

Gain factor G2

6-7

jf_conversion

Pedestal G0

8-9

jf_conversion

Pedestal G1

10-11

jf_conversion

Pedestal G2

12-13

integration

Integration map

14-15

integration

Integration weights

16-17

spot_finder_mask

Spot finder resolution

18-19

roi_calc

ROI calculation

20-21

frame_generator

Frame generator

22-27

load_from_hbm

Frame summation

\ No newline at end of file diff --git a/GPU_DATA_ANALYSIS.html b/GPU_DATA_ANALYSIS.html new file mode 100644 index 000000000..3003d4fb9 --- /dev/null +++ b/GPU_DATA_ANALYSIS.html @@ -0,0 +1 @@ + GPU data analysis — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

GPU data analysis

Jungfraujoch runs most of its crystallographic analysis on NVIDIA GPUs where one is present: the per-image loop of jfjoch_broker, jfjoch_viewer and rugnux, and most of rugnux’s dataset-level steps - the pre-scan, scaling and merging, model validation, molecular replacement and refinement. This page lists the GPU engines (all of them in .cu files under image_analysis/), with what each computes. The methods themselves are described once, in the CPU/GPU data analysis reference and its siblings, which each entry links to.

Every engine has a CPU counterpart that computes the same thing, and the CPU-only build (JFJOCH_USE_CUDA=OFF) runs the whole pipeline on it, the ffbidx indexer included (an in-tree CPU port of the library’s kernels). How closely the two agree is stated engine by engine below and in the source: where the arithmetic is integer, or the order of every sum is fixed to the host’s, the result is the same to the bit; where the GPU uses float distances, cuFFT for FFTW, or a different (fixed) summation order, the two agree to rounding. Every engine is deterministic on its own - no floating-point atomics decide a result - so the same input gives the same output on every run of a GPU build.

Getting the image onto the card

  • Bitshuffle+LZ4 decoder (BSLZ4DecoderGPU.cu) - decompresses the stored chunk on the device, so only the compressed bytes cross PCIe, and un-transposes it straight into the preprocessing step. The same pixels as the host decoder. The approach is Jon Wright’s (ESRF). §0

  • CBF byte-offset decoder (CBFDecoderGPU.cu) - decodes a miniCBF x-CBF_BYTE_OFFSET stream on the device into the same int32 pixels as the host decoder, refusing a stream that ends before the image does. §0

  • marCCD frames (ImagePreprocessorGPU.cu) - the stored 16-bit pixels are uploaded as they are and widened to int32 on the card, inside preprocessing. §0

  • Preprocessing (ImagePreprocessorGPU.cu, ImagePreprocessorBufferGPU.cu) - applies the pixel mask and flags error and saturated pixels, counting each and summing the rest, and keeps the preprocessed image on the device for every engine below; on request it gathers the pixels of the strong spots, or small squares around given positions, back to the host. Integer, so identical to the host. §1.6

Per image: profiles and spots

  • Azimuthal integration (AzIntEngineGPU.cu) - bins every pixel into its resolution (and optionally azimuth) bin with the geometric corrections applied and sums them, as a radial profile. Fixed-point sums, so the profile does not depend on the order the threads add in. §2

  • ROI integration (ROIIntegrationGPU.cu) - sums the pixels of user-defined detector regions of interest (box, circle, azimuthal), each pixel feeding any subset of them, on the EIGER/CPU path where the FPGA does not. Integer sums. FPGA: ROI integration

  • Local-statistics spot finder (ImageSpotFinderGPU.cu) - flags strong pixels by their signal-to-noise against a local box. §3.1

  • Adaptive spot finder (AdaptiveSpotFinderGPU.cu) - reduces the image into resolution rings once, and from that one pass gives both the azimuthal profile and each ring’s robust background, which sets the self-calibrating detection threshold; the result is intersected with the local test above. §3.2

  • Spot extractor (SpotExtractorGPU.cu) - joins the flagged pixels into connected components and sums each into a spot descriptor on the device, so only the spot list comes back. The same components, in the same order, as the host labelling (the sparse formulation of the ACTS/traccc project). §3.4

Pre-scan accumulators

These read a subset of the frames before processing starts, on every card at once, and are added together across cards; their sums are integers, so the split of the frames between the cards changes nothing.

  • Beam-stop projection and mask (ShadowAccumulatorGPU.cu, ShadowMaskGPU.cu) - accumulates the per-pixel maximum, sum and count of the raw counts straight from the compressed frames, then draws the beam-stop shadow mask from them, step for step as the host does. §1.5

  • Hot pixels (HotPixelsGPU.cu) - per frame, the ring-sector and ring order statistics, the levels made from them and the per-pixel counts of lit frames, from which persistently hot pixels are masked. Exact order statistics and integer sums: the host’s result to the bit. §1.6

  • Beam centre from the background (BeamCenterBackgroundGPU.cu) - bins the usable pixels about a trial centre and sums each cell, the two passes of the background-isotropy fit; the fit itself stays on the host. §1.4

  • Beam centre by FFT (BeamCenterFFTGPU.cu) - the self-convolutions that score every candidate centre at once, their combination into one score surface, and the shortlist of its peaks, with only the shortlist brought back. Runs on FFTW on the host instead where it would need more than half of the card’s total memory, decided before the card is touched and logged. §1.4

Indexing

  • FFT indexer (FFTIndexerGPU.cu) - projects the spots’ reciprocal-space vectors onto a dense set of directions, histograms each projection and transforms it with cuFFT, 4096 directions at a time, and picks each direction’s most prominent lattice peak; the candidate vectors then go to the host’s lattice reduction. cuFFT gives the same bits at any batch size, so the batching changes nothing but the memory held. A rotation run gives its indexers’ memory back to the card once a pass has done its last indexing. §5.1, §5.2

  • Fast-feedback indexer (ffbidx) - third-party, from the fast-feedback-indexer project (PSI); a known-cell indexer for serial stills, vendored in-tree (image_analysis/indexing/fast-feedback-indexer/). Its CPU counterpart is an in-tree port with the same samples and scores, agreeing to rounding. §4.3

Prediction and integration

  • Still prediction (BraggPredictionGPU.cu) - the reflections of a lattice within the excitation-error cutoff - or the window that follows the run’s rocking curve, centred on its radial scale - with their detector positions and per-reflection corrections. §8.2

  • Rotation prediction (BraggPredictionRotGPU.cu) - the reflections crossing the Ewald sphere within an image’s rotation range, with their rotation angle and partiality; they are ordered, and under a cap the best-recorded ones selected, on the device, in exactly the order the host gives. §8.3

  • Bragg integration (BraggIntegrationEngineGPU.cu) - for every predicted reflection: the three-ring regions and neighbour ownership, box summation, the per-shell profile learned from the strong spots and rebuilt per reflection, the radial background-curvature correction, and the profile fit. The profile fit is in single precision on both engines, in the same arithmetic, so the two differ only in summation order. §9.2, §9.3

Scaling and merging (rotation)

One engine (RotationScaleMergeGPU.cu) keeps every observation resident on the card for the whole scaling run; each per-group sum is a segmented reduction in a fixed order, so it is deterministic. Whether the scaling runs there at all is decided before any observation is on the card, from the card’s total memory: a set whose sort alone, or whose scaling (estimated from its observation and distinct-hkl counts once the sort has counted them), would take more than 80% of it scales on the CPU instead, with a warning in the log (RotationScaleMerge: ... scaling on the CPU instead). Judged on the total and not on what is free, the same input on the same card always takes the same path.

  • Ingest - the integrated reflections uploaded frame by frame, twice: first only what the sort and the resolution cut need, then, once the scaling is known to fit, the observations the cut kept, written straight to their place (the predicted detector positions stay on the host); the frame flux applied; the sort into raw-hkl runs and the resolution cut; the recomputed rotation angles (delta-phi), the rocking events relaid, and the partiality recomputed from the smoothed mosaicity. The same sort and cut as the host, to the bit. §10.2, §10.6

  • Per-frame scaling (ReduceGroupMeans, FitPerFrameG, UpdateCorr, SmoothCorr, the zeta and frame filters, PerFrameCC) - the reference intensity of every symmetry group, the per-frame scale fitted against it, its smoothing over the sweep, and the per-frame correlation behind --min-image-cc. §10.1, §10.3

  • Combine - each reflection’s partials summed into a full, with its capture fraction and variance; then the fulls’ own per-frame scale and its smoothing. §10.6

  • Correction surfaces - the decay, absorption and modulation surfaces’ terms, their reference and their least-squares sums over the fulls, on held-out subsets. §10.6

  • Merge - the inverse-variance merge (I(+)/I(-) and the mean), the half-sets for CC1/2, R_meas, the per-group scatter, the anomalous (Bijvoet) excess and the error-model samples. §10.4, §10.5

  • Error model (ErrorModelGPU.cu) - the binned fit of the error model’s a and b, the bin medians identical to the host’s; a and b can differ from the host fit in their last bits (summation order). §10.5

  • Wilson outliers (WilsonOutliersGPU.cu) - the per-observation Wilson-statistics rejection, the host’s result to the bit. §13.3

  • Pair sort (PairSortGPU.cu) - sorts the (deviation, weight) pairs of the outlier test’s weighted median; the same sequence as std::sort. §13.3

Model validation

The model’s structure factors and the rigid body run on the card where there is one, every part placed on it or on the CPU up front against one budget, 80% of the card’s total memory (§14.8); the GPU and CPU agree to rounding (float distances, cuFFT for FFTW, the crystal’s symmetry composed in reciprocal space instead of by symmetrizing the grid). On a machine with several cards, the rigid-body engines the first card has no room for go on the others, each against its own budget.

  • Model density (ModelDensityGPU.cu) - the density of one copy of the model’s atoms on a grid, as a gather over bricks of the grid, bit-identical from run to run. §14.1

  • Bulk-solvent mask (ModelMaskGPU.cu) - the solvent mask from every symmetry image of every atom, with island removal and the shrink, as gemmi computes it - on the density’s grid, or on one of its own at 0.75 A where the density’s is too coarse for the 0.8 A shrink to act. §14.2

  • Structure factors and maps (ModelStructureFactorsGPU.cu) - F_calc and F_mask from the two grids by cuFFT, composed over the group’s operators and read off at the data’s reflections; and the inverse transform of map coefficients into maps. §14.1, §14.4

  • Scale fit (ModelScaleGPU.cu) - the sums of the overall-scale, anisotropic-B and bulk-solvent fit over the reflections, in double and a fixed order, for many fits at once (the solvent grid, the null replicates); the Levenberg-Marquardt control stays on the host. Used where its engine fits the validation’s budget, the CPU fit otherwise. §14.2

  • Rigid body (RigidBodyGPU.cu) - the rigid-body target for a placement: the model moved, its F_calc and mask, the scale, the residuals and their Jacobian; used for the placement itself and for every replicate of the null. §14.8, §14.5

Molecular replacement

  • Molecular transform (MolecularReplacementGPU.cu, MapToFPhiGPU) - the Fourier transform of the search model’s density in a large box, by cuFFT, where its buffers fit the search’s budget (80% of the card, the search holding nothing else yet), kept only as far out as it is read.

  • Rotation function (MolecularReplacementGPU.cu) - for every trial orientation, the model’s intensities summed over the copies, normalised by resolution bin and correlated with the data’s normalised intensities.

  • Translation function (MolecularReplacementGPU.cu) - for each orientation, the function over every position in the cell, beside the copies already placed where there are any, and its mean, spread and highest point.

What of the search goes on the card is planned once per merge on the same budget as model validation’s, before the search starts (§14.10). On a machine with several cards, every other card holds a copy of the molecular transform where it fits, the rotation and translation functions are split over the cards by orientation, and the rigid-body engines are spread over them as in model validation; the result does not depend on how many cards there are.

The placements are then refined, scored and checked against their null with the rigid body and the structure factors above; the likelihood scoring runs on the host. The search is described in §14.10, its keys and decision rules in Molecular replacement.

Refinement

The restrained refinement of a placed model (§15) evaluates its target and its gradients on the card: one engine (RefinementGPU.cu, with the host half in RefinementGPU.cpp) keeps the reflections, the grids, the symmetry and the restraints resident, and per evaluation takes only the atoms’ positions up and one value and one gradient per atom back. Everything that depends on the cell, the group and the reflections - the grids, the operators, the adjoint’s lists - is worked out once on the host with gemmi when the engine is made. The GPU and CPU engines compute the same target to rounding (float distances and densities, cuFFT for FFTW, summation order); the GPU’s result is the same from run to run, as no sum of a result is a floating-point atomic: every per-point, per-reflection and per-atom sum is a gather in a fixed order, and every total a cub::DeviceReduce tree, whose order for a given size is fixed.

One evaluation - target and gradient of every atom - is a density gather, a forward and an inverse transform and a gradient gather, whatever the number of atoms (§15.2):

  • Density (ModelDensityGPU.cu, the gather of model validation) - the atoms’ blurred density of one copy of the model on the structure-factor grid. The grid is cut into bricks of 8^3 points; each atom’s box is counted against the bricks it touches, the counts scanned (cub::DeviceScan) into a list of (brick, atom) pairs, and the list sorted stably by brick (cub::DeviceRadixSort), so each brick holds its atoms in model order. One block per brick then stages its atoms in shared memory (128 at a time) and every point adds, in model order, each atom whose radius reaches it - no atomics, the grid the CPU walk’s to the bit for the same atoms. The pair count is the one wait inside an evaluation (it sizes the sort). The atoms’ density coefficients are uploaded again only where some atom’s B changed; the positions go up through a pinned buffer.

  • Forward transform - cuFFT r2c of the grid into its half-u spectrum, the plans made once per engine with an explicit work area.

  • Composition and target (compose_target_kernel, one thread per reflection) - F_calc of the reflection composed from the spectrum over the group’s operators (each operator’s phase exp(2 pi i h.t) computed exactly for the translation’s fraction, sums in double), times the centring count and the unblur; then, on the working reflections, F_model = k (F_calc + F_mask) with the macro-cycle’s scale, mask and D, Σ held on the card, the likelihood term -ln L of the reflection, and the coefficient conj(dT/dF) the derivative map is made of. The terms are summed by cub::DeviceReduce.

  • Adjoint of the composition (scatter_kernel, one thread per spectrum point) - the coefficients taken back onto the half-u spectrum as a gather, not a scatter: a CSR list made on the host at setup gives, for every spectrum point a (reflection, operator) term lands on, the terms in a fixed order, conjugated where they land as a Friedel mate and doubled onto the planes k_u = 0 and k_u = nu/2, which hold their own mates. Each point sums its terms in double and is written once.

  • Inverse transform - cuFFT c2r of that spectrum into the derivative map, on the density’s grid.

  • Atom gradient (atom_gradient_kernel, one warp per atom) - each atom’s dT/dx, dy, dz and dB: the derivative map summed against the derivatives of the atom’s five-Gaussian density over the same box and radius as the gather, the warp’s 32 lanes walking the box’s points in steps of 32 without an integer division (the box index stepped on, the wrap into the grid by one subtraction), and the lanes’ sums added in a fixed shuffle tree. The riding hydrogens’ derivatives are passed to their parents on the host.

Beside the X-ray target, and in the same submission:

  • Restraints (restraint_kernel, one thread per restraint) - bonds, angles, torsions, chirals, planes (up to 32 atoms), repulsions (with their symmetry image), metal links and B similarity (§15.5), each restraint writing its energy and its gradient into one slot per atom it involves; the energies summed by cub::DeviceReduce.

  • Slot gather (slot_gather_kernel, one thread per atom) - each atom’s restraint gradient, its slots summed in the order a CSR list gives. Two restraint sets are held (positions and B), set again when the repulsions and contacts are rebuilt.

EvaluateWithRestraints queues the X-ray evaluation, writes the restraints’ positions into a pinned buffer while the card works on it, queues the restraints behind it and waits once; the target, the restraint energy and both gradients come back into pinned buffers. The minimiser (L-BFGS) stays on the host.

Once per macro-cycle (§15.3):

  • F_calc and F_mask - the forward path above without the target, and the bulk-solvent mask drawn on the card (ModelMaskGPU.cu) on its own fine grid (d_min/3 or 0.4 A, whichever is finer, at most 2^26 points but never coarser than 0.75 A nor than the density’s grid), with a grid, spectrum and cuFFT plan of its own where that grid is not the density’s: one block per (atom, symmetry image) sets the points within the atom’s REFMAC radius, the islands are removed by a union-find labelling (integer atomicCAS, rooted at each component’s lowest index, so the partition does not depend on the order of the unions), and the shrink is two passes - the edge points marked, then each edge point’s stencil written as solvent. Every write is an idempotent store, so the mask is the same bit for bit from run to run; F_mask is read off at the reflections (fmask_kernel).

  • Robust scale fit (ModelScaleGPU.cu) - the k_sol/B_sol grid of fits, each fit’s overall scale and anisotropic B by gemmi’s Levenberg-Marquardt, many fits per launch: the sums over the reflections (the WSSR, J^T J and J^T r, in double) by a fixed launch shape of 48 blocks of 128 threads, a fixed shuffle tree within each warp and the blocks summed in order; the damping and the 7x7 solve stay on the host. The fine pass is robust: four rounds of residuals, weights 1/sqrt(1 + (r/c)^2) and the fit again, with c the median residual of the first round found on the card by a radix select (residual_median: the residuals are not negative, so their order is that of their bits, found a byte at a time in four passes of integer counts - the element std::nth_element puts at n/2). After a trial’s first macro-cycle the fit starts from the fine pass around the previous winner, skipping the coarse one. The fits go in batches of at most 32 (the coarse pass’s 88 in three, in grid order; a fit’s sums do not depend on the others in its batch), and the robust weights take the residuals’ place, so the engine holds about 300 bytes per reflection. Its stream has the card’s highest priority, so that the fit’s short, host-waited launches do not queue behind the long kernels of the other trials on the card.

  • D and Σ, the likelihood’s parameters, are fitted on the host (bin by bin, on all of the run’s threads).

Trials, cards and waits. The weight trials of one set (§15.7) run side by side, each on a slot of its own - a copy of the model, its topology and a refinement engine - as many slots as the largest set of trials has (six at the defaults), the ones beside the main one built on their own threads while the placement runs. The slots’ engines go on the cards in turn from the main one’s, each card taking engines while they fit its budget, so the first slots are on cards of their own and on a machine with several cards the trials are spread over all of them. The engines on one card share what does not change - the setup worked out on the host, the reflections’ tables, the adjoint’s lists and the phase table - and the bulk-solvent mask’s buffers (RefinementGPUCard). The working buffers of a transform - the grid, its spectrum, cuFFT’s work area, the mask’s own grid and spectrum - come in lanes (RefinementGPULane): a slot has a lane of its own where the card holds one more, and shares the least used lane otherwise, its engine taking the lane’s lock from its launches to their wait (an evaluation, F_calc, F_mask), so the lane runs one evaluation after another while its other slots do their host work - the minimiser, the gradients, the restraint lists. Lanes side by side keep a card busier (two evaluations at once on a T4 cost 9% more each than one); slots sharing a lane overlap more host work. The slots on a card share its scale-fit engine too, a fit waiting for the one before it. A slot whose engine cannot be made is left out rather than moved to the CPU, and the outcome does not depend on how many trials run at once or on which card. The engine waits on its stream through an event made with cudaEventBlockingSync (StreamWaiter), so a waiting trial sleeps instead of spinning a core - with six engines on one card the spinning took half of the refinement’s CPU time.

Memory. RefinementGPUEngine::DeviceBytes counts the engine’s reserve before anything is allocated: per atom (positions, boxes, densities, mask atoms, gradients), per reflection (scales, the row model, F_calc, F_mask, coefficients, terms), the gather’s pair reserve - sized for every atom at the largest B a refinement may reach with the widest blur - and the restraints: the records and gradient slots of the model’s two restraint sets as the refinement starts (the geometry with its repulsions and NCS restraints, and the B restraints), a quarter more for the contacts that come and go. RefinementGPUEngine::CardBytes counts the part the engines on a card share (the tables, the adjoint’s lists, the phases and the mask’s buffers), LaneBytes a lane. The engine goes on the card when the two, the scale-fit engine and what is already resident there (a merge still at work), are within 80% of the card’s total memory (with a lane); the trial slots are counted against the same budget, card by card - each one its engine’s own part and a lane where both fit, else its engine’s part alone, the first one on another card also the shared part and a scale-fit engine. On a large model (510k atoms with riding hydrogens, 3.1M reflections to 2.1 Å) an engine’s own part is 2.0 GB, a lane 1.5 GB, the shared part 1.7 GB and the scale-fit engine 0.9 GB: a 16 GB card takes three slots (three lanes; two where 80% of it is 12.5 GB), a 24 GB card five.

Falling back. Where the GPU cannot take the case (an atom’s box wider than the cell, more than 192 mask operators), where the engine is over the budget, or where CUDA fails while the engine is made, the refinement runs on the CPU engine, with a line in the log (Refinement: on the CPU - ...). --no-gpu and a build without CUDA take the CPU engine as well. The refinement has no Metal engine: on macOS it runs on the CPU.

Indicative timings (RTX 5080, -N 8, the refinement alone): a 5,000-atom model (half of it riding hydrogens) at 1.65 A with 31k reflections refines in about 1.3 s; a 4,500-atom model at 1.09 A with 92k reflections in about 2 s; a 50,000-atom model at 3.6 A with 51k reflections in about 7 s, of which the kernels take 5 s - there the density gather and the atom gradient (about 0.9 and 0.8 ms per evaluation, over a thousand evaluations) are half or more of the kernel time, the scale fit 10-25% (more at high resolution) and the fine mask 15-18% at low resolution. Inside a full rugnux --model run of a 5,000-atom model the refinement took 1.5 s of 8 s. The CPU engine (-N 8) takes about a minute and a half for a set the card refines in about 2 s.

Apple GPUs (Metal)

A macOS build has no CUDA, and three engines run on the Apple GPU instead (none under rugnux --no-gpu; where the GPU fails, the CPU takes over with a warning):

  • Bragg integration (BraggIntegrationEngineMetal.mm, .metal) - the CPU engine with its pixel work moved to the GPU: the neighbour mask, the ownership of shared pixels, the box summation’s walk over every reflection, the background clip and the single-precision profile fit. Everything computed in double and the profile learning stay on the CPU, as Apple GPUs have no double precision. The fit’s Gaussian uses an exp of our own (BraggExp.h) on both, as no GPU exp matches the CPU’s. The same result as the CPU engine to the bit, which a macOS CI step checks on every push; rugnux --no-gpu keeps it off the GPU, and so does --background-trim, whose trimmed mean has no Metal kernel. §9.2

  • Model density (ModelDensityMetal.mm, .metal) - the density of the model’s atoms on a grid, for model validation and molecular replacement, as a gather over bricks of the grid as under CUDA; the same grid as the CPU’s to the bit. §14.1

  • Molecular-replacement rotation function (MolecularReplacementMetal.mm, .metal) - the rotation function’s trial orientations scored from a copy of the molecular transform; equal to the CPU’s to rounding. §14.10

\ No newline at end of file diff --git a/HARDWARE.html b/HARDWARE.html new file mode 100644 index 000000000..9cd418e32 --- /dev/null +++ b/HARDWARE.html @@ -0,0 +1 @@ + Hardware requirements — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Hardware requirements

Operating Jungfraujoch requires the following:

  1. High performance server

  2. FPGA board(s) installed in the server

  3. (optionally) GPU boards

  4. (optionally) 100G switch to connect FPGA and the detector

Unfortunately, at the moment it is not possible to purchase server configuration from a major vendor that would include AMD FPGA boards. Therefore, the two have to be purchased separately. This might have impact on the warranty for the hardware and has to be clarified with the vendor. PSI only supports the system on the best effort basis and doesn’t take any responsibility for warranty limitations for operating FPGA boards in the server. Having said this - we didn’t encounter any hardware issues so far.

High performance server

PSI is using HPE DL380 Gen11 servers at the moment to operate Jungfraujoch systems. However, this is because of general preference for this vendor, there is no Jungfraujoch-specific reason to buy from this vendor. We do expect that system from any other vendor with similar specification should work as well.

At PSI, the configuration of HPE DL380 Gen11 used to operate 9M pixel detectors at 2 kHz is as follows:

  • 2 x Intel Xeon 8558P

  • 512 GB RAM

  • 2 x Nvidia L4 GPU (for indexing)

  • 1 x Nvidia ConnectX-6 200G ethernet/IB network (for outgoing traffic; this can be substituted according to facility needs)

  • Copper 1G/10G network

PCI slots

When ordering the system, check that it can accommodate enough PCIe cards. In case of our system we need to put at least seven PCIe cards: 4 x FPGA, 2 x GPU, 1 x network.

Note - for FPGA x8 lane electrically/x16 lane mechanically PCIe slots are OK.

FPGA

Jungfraujoch is built for AMD/Xilinx U55C (A-U55C-P00G-PQ-G) card. Other FPGA cards are currently not supported.

Single U55C card supports roughly 5 detector modules (2.5M pixels) at 2 kHz and 10 detector modules (5M pixels) at 1 kHz. For detectors operating at lower frame rates (e.g., 100 Hz) larger detectors can be supported by a single U55C card, though it requires using TX delay functionality in the detector.

GPUs

Running the fast-feedback indexer at the detector’s frame rate requires a graphics processing unit from Nvidia (without one it runs on the CPU, at a much lower rate). For practical reasons, i.e. power consumption and cost, we chose the inference-grade Nvidia L4 card. In the past we have also used T4 cards. So, in principle any recent CUDA compatible GPU should work. The server that runs Rugnux live on the EIGER2 16M at PXII-X10SA (the beamline test of the Rugnux paper) has two Xeon 8558P and four L4 cards.

Offline processing with rugnux has a requirement of its own, unrelated to the frame rate the acquisition side is sized for: one run wants 3-7 GB on the card and up to 14 GB of host RAM, so a server that also reprocesses data needs headroom beyond the online pipeline’s. The sizing table is in Installing Rugnux ▸ Memory.

Network switch

Small detectors (up to 4M pixel) can be in principle operated without switch. In this case one needs 8x10g variant of the Jungfraujoch FPGA image, which allows 4 JUNGFRAU modules (two 10 Gbit/s links each) to be connected directly to one U55C card.

Such configuration is however impractical for larger systems or more complex deployments, like multiple detectors operated from one Jungfraujoch server. In this case one needs a network switch.

We currently use Nvidia/Mellanox SN2100 switch, though there is no reason not to use other models/other vendors. A switch with only 100G ports must support splitting them into 4x10G ports to connect the detector.

\ No newline at end of file diff --git a/HDF5.html b/HDF5.html new file mode 100644 index 000000000..586c120cb --- /dev/null +++ b/HDF5.html @@ -0,0 +1,18 @@ + HDF5 / NeXus data format — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

HDF5 / NeXus data format

Jungfraujoch stores images and on-the-fly analysis results in HDF5 files that aim to be NXmx-compliant. On top of the NXmx application definition, Jungfraujoch records a substantial amount of derived metadata (spot finding, indexing, integration, azimuthal integration, per-image statistics, timing). These extra entries do not exist in NXmx and are documented here so that the layout is unambiguous and reusable.

This page documents the file layout and the data fields. The operational behaviour of the writer (running, republishing, file finalisation) is described in jfjoch_writer. The wire format that feeds the writer is described in CBOR messages; fields below frequently correspond one-to-one to CBOR message fields, and that document is a useful companion for their meaning.

1. Motivation: derived metadata and FAIR data

The goal of Jungfraujoch is not only to store high-throughput datasets efficiently, but to keep them findable, accessible, interoperable and reusable (FAIR). Jungfraujoch is used for both rotation macromolecular crystallography (single- and multi-crystal, including fine-sliced and helical scans) and serial crystallography (stills, grid scans); the same concerns apply to both:

  • Findability. Raw diffraction images carry almost no descriptive metadata about content. Quantities such as background level, number of diffraction spots, or indexing outcome let a user judge the quality and relevance of a dataset before inspecting the raw images.

  • Accessibility at scale. A single experiment can span tens to hundreds of terabytes. Standard retrieval (e.g. HTTP) makes a dataset available but not inspectable — users would otherwise have to download a large fraction of the data just to decide whether it is useful. Compact derived representations make discovery, assessment and reuse feasible.

Because Jungfraujoch couples acquisition with real-time analysis used to steer experiments, transparency and reproducibility of that analysis matter. As a minimum the writer therefore preserves spot-finding and indexing results together with the filters that were applied, and it can retain an unbiased, down-sampled reference set of unfiltered images for validation and reuse.

Two complementary layouts: per-image spots vs. a reflection table

Jungfraujoch stores analysis products in two shapes, matching how each is accessed.

Per-image spot finding / indexing. Spot finding and indexing are inherently image-centric — the natural query is “give me the spots for image n” — and this holds for serial stills and for rotation frames alike. For these products Jungfraujoch adopts a layout similar to the Coherent X-ray Imaging (CXI) data bank (Maia, 2012) and the convention understood by CrystFEL: spot properties (position, intensity, Miller index, …) are stored in fixed-size two-dimensional arrays indexed by image number, with each image allocated room for up to a predefined maximum number of spots. These dense arrays are addressed with ordinary HDF5 hyperslab reads, so the spots of a single image are retrieved without traversing variable-length structures. The cost is some storage overhead for unused slots (padded with sentinels), which is acceptable for the access pattern.

Integrated reflections. Integrated intensities are naturally a dataset-wide table, which is exactly the model of the NeXus NXreflections base class. This fits rotation crystallography well, and Jungfraujoch uses NXreflections for its integration results (see §4.2 below). We deliberately do not force spot finding/indexing into a single experiment-wide table: across the hundreds of thousands of patterns typical of serial — or fine-sliced rotation — experiments, that would require aggregating the whole experiment before the spots of one image can be read. We encourage the community to develop standardised NeXus application definitions for image-centric crystallography products that combine NeXus interoperability with the access patterns and scale of modern high-throughput experiments.

2. File layout

A run is written as one master file plus, depending on the format, one or more data files:

<prefix>_master.h5             # NXmx master file (metadata + links / virtual datasets)
+<prefix>_data_000001.h5        # data file: images + per-image analysis
+<prefix>_data_000002.h5
+...
+

The master file is produced by writer/HDF5NXmx.cpp; data files by writer/HDF5DataFile.cpp and its plugins (writer/HDF5DataFilePlugin*.cpp). Files are written to a temporary *.<random>.tmp name and renamed on successful close.

Three master-file variants exist (set via file_format):

Format

Value

Master ↔ data linking

NXmxLegacy

1

One external link in /entry/data per data file (data_000001, …). HDF5 1.8 compatible — works with Neggia/Durin XDS plugins and Albula 4.0.

NXmxVDS (default)

2

A single virtual dataset /entry/data/data spans all data files; spot finding, azimuthal integration and reflections are linked the same way. Requires HDF5 1.10 / Albula 4.1+.

NXmxIntegrated

3

No separate data files — images and all metadata live in one file. Equivalent in content to the VDS format.

In legacy/VDS mode, image-indexed analysis arrays live in the data files and are exposed in the master file through external links or virtual datasets; in integrated mode they are written directly into the single file.

Images are stored chunked (one image per chunk) and compressed with bitshuffle + LZ4 or bitshuffle + Zstd. Signed integer image datasets carry INTx_MIN as the HDF5 fill value (the “masked / no-data” sentinel); unsigned ones are left at HDF5’s own fill of 0, because every unsigned code is a legitimate count. In the master’s virtual dataset the fill is the error marker for both, so a data file missing beside a VDS master reads as masked rather than as zero counts.

Signed images and the Neggia XDS plugin. Neggia dispatches on the size of the pixel in bytes and always casts to an unsigned type, consulting the signedness of the data only for the pixel mask. A signed 16-bit image is therefore read wrongly: a count of -2 reaches XDS as 65534, and the -32768 error marker as 32768. Signed 32-bit happens to degrade safely, because every negative value ends up above INT32_MAX and is mapped to -1. Use the Jungfraujoch XDS plugin, or the Global Phasing build of Durin, for signed data — see Integration with MX data processing software.

Reprocessing output: <prefix>_process.h5

The offline reprocessing tool rugnux (rugnux/rugnux_cli.cpp) re-runs the full analysis pipeline (spot finding, indexing, refinement, integration, scaling) on an existing dataset and writes its results to a master file named <prefix>_process.h5. This file uses the integrated format, but instead of copying the images its /entry/data/data is a virtual dataset that links back to the original image files (hdf5_source_data → NXmx::LinkToData_ProcessingVDS). The result is a compact, self-describing companion file that holds all the derived analysis (everything in §4, including the XFEL pulse IDs of §4.8 when the input has them) plus a virtual view of the raw images — without duplicating terabytes of data.

This is a particularly FAIR-friendly artefact: it can be shared or archived alongside (or instead of) the raw data to convey what is in a dataset and how it was processed, while the /entry/data/data VDS still resolves to the original images when they are available. Where the input is anything but a single HDF5 master it could link to (several masters read as one, CBF, XTC, CXI, …), the file has no /entry/data/data at all - only the per-image analysis, which --mode scale reads all the same. rugnux can also process an equally-spaced subset of images (start/end/stride), producing a down-sampled reference set.

3. NXmx-standard content

The entries below are part of, or valid base classes for, the NXmx application definition. “NXmx” = listed in the application definition; “base” = a valid field of the relevant NeXus base class (NXdetector, NXsample, NXsource) but not in the NXmx required/recommended subset.

/entry (NXentry)

Field

Std

Notes

definition

NXmx

value "NXmx"

start_time

NXmx

arming time

end_time, end_time_estimated

NXmx

approximate end time

File-level HDF5 attributes file_name, file_time, HDF5_Version are also set.

/entry/source (NXsource), /entry/instrument (NXinstrument)

Field

Std

Units

source/name, source/type

NXmx / base

source/current

base

A

instrument/name

NXmx

/entry/instrument/beam (NXbeam)

Field

Std

Units

incident_wavelength

NXmx

angstrom

incident_wavelength_spread

NXmx

angstrom (only if polychromatic)

total_flux

NXmx

Hz

incident_beam_size

NXmx

m (two elements, x then y; written only when both beam sizes are given)

/entry/instrument/attenuator (NXattenuator)

Field

Std

attenuator_transmission

NXmx

/entry/instrument/detector (NXdetector)

Field

Std

Units

depends_on

NXmx

→ transformations/translation

beam_center_x, beam_center_y

NXmx

pixel (0.0 = centre of the first pixel, see DETECTOR_GEOMETRY). The PONI, not the direct beam - see below

distance

NXmx

m

count_time, frame_time

NXmx

s

sensor_thickness

NXmx

m

sensor_material

NXmx

description

NXmx

threshold_energy

NXmx

eV (EIGER; written only for a single channel)

x_pixel_size, y_pixel_size

base

m

serial_number

base

bit_depth_readout

NXmx

bit depth of the stored image, not of the detector electronics - see below

saturation_value

NXmx

highest valid value. Read inclusively by NXmx, by the DIALS trusted_range and by the XDS OVERLOAD parameter; a saturated pixel carries the value one above it

underload_value

NXmx

lowest valid value: 0 for an unsigned image, INTx_MIN + 1 for a signed one

flatfield_applied

NXmx

pixel_mask, pixel_mask_applied

NXmx

pixel_mask is [y, x], hard-linked from detectorSpecific/pixel_mask

countrate_correction_applied

NXmx

countrate_correction_lookup_table

NXmx

only when the detector sent one (DECTRIS)

virtual_pixel_interpolation_applied

NXmx

only when the detector reported it (DECTRIS)

number_of_cycles

base

frame-summation factor

Why bit_depth_readout is the image depth

NXmx defines only bit_depth_readout, “how many bits the electronics record per pixel”, and has no field for the depth of the image actually stored. The two differ whenever summation is used: the readout stays at the detector’s native width while the summed image must be wider to hold the sum.

Jungfraujoch writes the stored image depth into bit_depth_readout (and the identical value into the non-standard bit_depth_image). The electronic value is a constant of the detector and tells a data consumer nothing, whereas readers do use bit_depth_readout as the width of the stored pixel — DIALS, for instance, derives its masking markers from it and cannot read a 32-bit image without it. Writing the electronic value there would therefore mislead exactly in the case where the two differ.

Note that bit_depth_readout gives the width only. The sign is carried solely by the HDF5 element type of /entry/data/data (and, on the wire, by image_dtype); there is no NXmx field for it.

/entry/instrument/detector/transformations (NXtransformations)

The NXtransformations mechanism (the depends_on chain, transformation_type, vector, offset attributes) is standard. The axis names follow the PyFAI PONI convention chosen by Jungfraujoch (see DETECTOR_GEOMETRY):

Axis

Type

Units

Vector

Depends on

rot3

rotation

rad

(0, 0, -1)

.

rot2

rotation

rad

(1, 0, 0)

rot3

rot1

rotation

rad

(0, -1, 0)

rot2

translation

translation

m

unit vector along the sample→PONI direction

rot1

/entry/instrument/detector/depends_on is translation, and the module’s fast_pixel_direction, slow_pixel_direction and module_offset depend on it in turn. A chain is applied innermost-first, so reading it outwards the detector is placed at its distance and beam centre and then tilted about the sample — which is what makes a tilt pivot about the crystal rather than about the panel corner. The vector values are in NXmx’s McStas frame, which is Jungfraujoch’s internal frame with x and y negated.

The beam centre is encoded in translation (its offset from the sample), not only in the informational beam_center_x/beam_center_y fields. In a _process.h5 written by Rugnux these axes carry the refined detector geometry — the refined beam centre folds into translation and the refined tilt into rot1/rot2/rot3; the broker writes the user-provided geometry unchanged.

beam_center_x/beam_center_y is the PONI; direct_beam_x/direct_beam_y is the beam

beam_center_x/beam_center_y is the PONI - the foot of the perpendicular dropped from the sample onto the detector plane. On a tilted detector that is not where the undeflected beam lands: the two points are distance * tan(tilt) / pixel_size apart, which is around 8 px on a real in-house setup and grows with the distance.

Most programs that ask for “the beam centre” mean the point the beam lands on - XDS’s ORGX/ORGY among them - so Jungfraujoch writes that point out as well:

Dataset

Units

/entry/instrument/detector/detectorSpecific/direct_beam_x

pixel

/entry/instrument/detector/detectorSpecific/direct_beam_y

pixel

They are computed from the same beam centre, distance and rot1/rot2/rot3 written beside them, so the file cannot disagree with itself; on an untilted detector they equal beam_center_x/_y.

The provenance differs by which program wrote the file, though the field does not. In a master written by jfjoch_broker the geometry is the one the user stated, so direct_beam_x/_y is a statement about the user’s geometry; in a _process.h5 written by Rugnux it is the refined geometry, so it is a measurement. A user handing either to XDS should know which of the two they have.

/entry/instrument/detector/module (NXdetector_module)

Written for a detector whose image is one flat panel (e.g. an EIGER). A detector of several modules (a JUNGFRAU image assembled by Jungfraujoch, or an input whose modules are known) is written as module_0, module_1, … instead (next section), with no whole-image module beside them: NXmx readers such as DIALS/dxtbx take every NXdetector_module as one panel.

data_origin, data_size, fast_pixel_direction, slow_pixel_direction, module_offset — all NXmx (fast/slow_pixel_direction and module_offset carry transformation attributes). The two pixel-direction vectors carry the discrete image orientation (mirror in Y, multiples of 90° about the beam); for a detector that this system assembled itself, they are the McStas form of the internal +x and +y, i.e. (-1, 0, 0) and (0, -1, 0).

/entry/instrument/detector/module_<n> (NXdetector_module, one per module)

A master of a multi-module detector states its modules one by one, in the order the /entry/MX/peakPanel indices refer to. n is zero-padded to the width of the last index (module_0 … module_7, but module_00 … module_15), so that the groups sort by name in module order and DIALS panel n is module n; for an image Jungfraujoch assembled, each module is its box of the image, as imaged. Rugnux writes the placement of a detector’s modules, where a stills run placed them, into <prefix>_modules.h5 in the same layout, and reads the same groups back (--module-geometry, or a master that states its modules one by one). Masters written by releases up to 1.0.0-rc.181 may carry the whole-image module beside module_<n>; they read back the same way.

Field

Units / notes

data_origin

[row, column] of the module’s first pixel in the image (slowest index first)

data_size

[rows, columns] of the module

module_offset

translation (m) from the image’s pixel (0, 0) to the module’s first pixel; depends_on the detector’s transformations/translation

fast_pixel_direction, slow_pixel_direction

translation of one pixel (m) along the module’s columns and rows; depends_on the module’s module_offset

readout_fast_axis, readout_slow_axis

not NXmx: which way the module’s fast and slow readout axes run in the stored image (Xp, Xn, Yp, Yn); with the box they give its readout pixel 0, which names the module in a module placement (dataset_settings.module_placement)

Vectors are in the McStas frame. A pixel (row i, column j) of a module is at translation + module_offset + j * fast_pixel_direction + i * slow_pixel_direction, which is how DIALS/dxtbx reads it (one panel per module).

/entry/sample (NXsample)

Field

Std

Units / notes

name

NXmx

depends_on

NXmx

points at the innermost axis of the sample chain, or . for stills

temperature

NXmx

K

transformations/ (NXtransformations)

NXmx

the sample chain, written in mounting order; hard-linked as /entry/sample/goniometer

unit_cell

base

[a, b, c, α, β, γ]

unit_cell_esd

e.s.d.s of unit_cell, in its order [σa, σb, σc, σα, σβ, σγ] (Angstrom, degrees; zero for an angle the space group fixes); rotation runs analysed by rugnux, offline or in the broker

space_group_number

base

International Tables number

space_group

base

extended Hermann-Mauguin name, e.g. P 43 21 2, R 3:H — this is the field that carries the setting, and the one the reader takes the group from; the number alone always reads back as the reference setting

ub_matrix

base

[1, 3, 3], Angstrom⁻¹

grid_scan/ (NXcollection)

for a grid scan: snake_scan, vertical_scan (bool), n_fast (points along the fast direction), step_x, step_y [m]

The chain is written from the base outwards, so the innermost axis — the one depends_on names — is the one nearest the sample. It may hold, in that order: the grid-scan translations grid_scan_x and grid_scan_y, the spindle, and a Smargon head’s chi and phi. A grid scan and a goniometer axis are not alternatives; both can be present.

A grid scan is collected at a stationary spindle, and the angle it stood at is stated by sending the goniometer axis with a step of 0 — in dataset_settings.goniometer, or as the goniometer map of the CBOR start message. The angle is then written per image as omega (or whatever the axis is named) in the chain above, and read back by reader/. Send no axis and the spindle is still recorded, at 0: NXmx would allow a sample with no goniometer at all (depends_on = "."), but a sample chain of translations alone is not something readers accept, so the placeholder is written whether or not the angle is known. A 0 there means “nobody said”, not “the spindle was at 0”.

A Smargon head position is told apart from the spindle by the equipment_component attribute, which is "smargon" on chi and phi and absent on the spindle. This is load-bearing: a spindle can itself be named phi, and without the attribute a reader would take a head position for the scan axis. chi and phi are written with one value per image even though neither turns, because a reader takes the image count from the innermost axis of the chain: written as scalars, a still recorded at a head position would read back as a single image however many were collected.

For a rotation scan the goniometer axis carries, beyond the per-image angle array <axis>, the Jungfraujoch conveniences <axis>_end, scalar <axis>_range_average and <axis>_range_total, and for helical scans <axis>_helical_x/_y/_z.

/entry/data (NXdata)

data (3-D image stack, [n_images, y, x]) with image_nr_low / image_nr_high attributes. In legacy mode this group instead contains one external link data_000001, … per data file.

4. Extensions beyond NXmx

Everything in this section is outside the NXmx standard. Each group is declared with NX_class = NXcollection (the NeXus-sanctioned container for non-standardised content) unless noted. The per-image arrays are indexed by image number, padded to the run length and filled with a sentinel (NaN for floats, -1/0 for integer indices) where a quantity is absent.

4.1 /entry/MX — spot finding and indexing (CXI-style)

The flagship extension. Spot (“peak”) properties are stored as fixed-size [n_images, max_spots] arrays (CXI layout, recognised by CrystFEL); scalar-per-image quantities as [n_images] vectors. In legacy/VDS mode the per-spot arrays, nPeaks, peakPanel and the per-image lattices live in the data files and are linked/virtual-stacked into the master; the per-image vectors are copied into the master from the end message at finalisation (with strongPixels, beam_corr_x/y and bravaisLattice in the data files only).

Per-spot arrays [n_images, max_spots]:

Dataset

Units

Meaning

Indexing only

peakXPosRaw, peakYPosRaw

pixel

spot position (raw detector frame)

peakTotalIntensity

photons

spot intensity

peakIceRingRes

spot lies in an ice-ring resolution band (int8)

peakH, peakK, peakL

Miller indices of the (indexed) spot (int32)

✓

peakDistEwaldSphere

Å⁻¹

distance of the spot from the Ewald sphere

✓

peakIndexed

spot fits the indexing solution (int8)

✓

peakLattice

lattice the spot belongs to (int8, -1 = unindexed)

✓

peakPanel

panel the spot was found on (int16, -1 = none); written only for a detector with a panel table

Per-image vectors [n_images]:

Dataset

Units

Meaning

nPeaks

number of spots stored for the image (CXI, uint32)

strongPixels

strong-pixel count (first spot-finding stage)

peakCountUnfiltered

spots found before filtering

peakCountLowRes

low-resolution spots

peakCountIceRingRes

spots inside ice-ring bands

peakCountIceRingControl

spots in the ice-free flanks beside those bands, rescaled to their q width - the control for the count above (their ratio, pooled over the run, is the spot-based ice indicator)

peakCountIndexed

spots fitting the indexing solution

imageIndexed

image was indexed (0/1)

indexingLatticeCount

number of lattices found for the image

niggliClass

Niggli class of the indexed Bravais lattice (see International Tables for Crystallography A (2016), Vol. A, Table 3.1.3.1)

bravaisLattice

Bravais lattice short code, e.g. aP, mC, oF, tI, hP, hR, cF

profileRadius

Å⁻¹

crystal profile radius

mosaicity

deg

mosaicity estimate

bFactor

Ų

per-image B-factor estimate

resolutionEstimate

Å

resolution the merged data are predicted to reach, from this image’s spots alone

integratedReflections

number of integrated reflections

bkgEstimate

photons

mean background in the 3–5 Å resolution band

iceRingScore

ratio

strongest hexagonal-ice ring intensity over the smooth radial background (1 = no ice)

spindleBlindFraction

fraction (0-1)

how much of a rotation sweep’s blind cone this orientation makes unrecoverable, as a lone-2-fold worst-case bound; NaN = the frame could not be assessed, which automation must treat like a value at or above the 0.5 trigger, never as 0

beam_corr_x, beam_corr_y

pixel

beam-center correction applied during processing

imageScaleFactor

on-the-fly per-image scale factor g

imageScaleCC

on-the-fly scaling correlation coefficient

imageScaleMosaicity

deg

scaling-model mosaicity

sweepQuality

why this image’s stretch of the sweep was flagged — see below

frameDisposition

what became of this image’s observations in the merged data — see below

Per-image lattices: latticeIndexed [n_images, 9] (Å) — the real-space lattice (flattened 3×3); latticeIndexedExtra [n_images, max_extra_lattices, 9] (Å) — additional orientation variants.

Run-level summaries (written into the master /entry/MX at finalisation):

Dataset

Units

Meaning

indexing_algorithm

FFBIDX / FFT (CUDA) / FFT (FFTW)

geom_refinement_algorithm

beam_center / flex

rotationLatticeIndexed

Å

whole-run rotation-indexing lattice ([9])

rotationLatticeIndexedExtra

Å

additional whole-run lattices ([m, 9])

rotationLatticeNiggliClass

Niggli class of the run lattice

imageIndexedMean

mean indexing rate over the run

bkgEstimateMean

photons

mean background over the run

spindleBlindFractionMean

fraction (0-1)

mean spindleBlindFraction over the frames that had one

spindleLostUniqueFraction

fraction (0-1)

unique reflections (to the run’s resolution limit) the mounting made unmeasurable, exact under the measured point group and indexed orientation; offline (Rugnux) only

iceRingScoreMean

ratio

mean iceRingScore over the run — the single “how icy was this dataset” number (1 = no ice)

indexedLatticeCount

per-image lattice count summary (master). Note: data files use indexingLatticeCount; readers accept either.

reindexMatrix

change of basis from the setting the per-image data are in to the setting of /entry/sample/unit_cell ([9], int32, flattened 3×3, row major) — see below

stillsRockingWidthFormula

1/Å, rad, relative

stills: the run’s rocking width σ² = γ₀² + (γₑ d*)² + (σ_bw λ d*²/2)², as [γ₀, γₑ, σ_bw]; offline (Rugnux) only

stillsRadialScale

stills: the scale of the reciprocal lattice the rocking curve is centred on

stillsRockingWidthTableDstar, stillsRockingWidthTable

1/Å

stills: the rocking width σ measured against d* before the image pass, which the frames were predicted through (held beyond the first and last entry; the formula above is what the prediction window uses); the partiality post-refinement balances it against the merge, and --mode scale starts from this same curve instead of measuring another

stillsGivenUnitCell

Å, deg

stills: the cell given with -C, whose population of frames the merge kept ([6]); --mode scale leaves out the same frames

Reindex matrix. The per-image h, k, l and latticeIndexed are written as each image is processed, in the setting that image was indexed in. The space group is only settled afterwards, by the merge, and settling it can re-seat the lattice into the group’s conventional setting — so /entry/sample/unit_cell, /entry/sample/space_group_number and rotationLatticeIndexed can be in a different setting from the per-image data beside them. reindexMatrix M is the integral change of basis between the two: hkl_cell = M · hkl_written, and the same M takes each per-image lattice across (latticeIndexedExtra is not re-seated and stays as indexed). It is absent when the two settings are the same one, which is the identity — as it is on every file written before Rugnux recorded it. The Jungfraujoch reader applies it, so everything it hands out is already in the cell’s setting; a third-party reader that ignores it will index the reflections in the wrong frame whenever the dataset is present. Written by the offline rugnux path only — the broker never re-seats a lattice — and not carried on the CBOR stream, in the same way as the other offline-only fields.

A --model run can leave the merged reflection files (.mtz/.cif/.hkl) in a different frame from the _process.h5 beside them: the model settles the alternative indexing where nothing else did, and that choice is applied to the merged reflections as they are written. It also names the enantiomorph, but that is a change of space-group label only and moves no reflection. The process file is not rewritten — its per-image reflections went to disk as they were integrated — so it keeps the space group the run itself determined and stays self-consistent with its own data. The two frames describe the same measurements; an enantiomorphic pair merges identically, having the same Laue class and the same absences.

Sweep quality. sweepQuality [n_images] (uint8) says why the stretch of the sweep this image belongs to was flagged as delivering much less than the rest of the run: 0 means it was not, and any other value is a 1-based index into sweepQualityReasons, a string vector written beside it that carries the whole vocabulary, so the codes can be read without this source. The vocabulary is closed and stable — a code is never renamed and never reused — and currently reads no_diffraction, crystal_out_of_beam, weak_diffraction, loss_of_centring, radiation_damage, inconsistent_with_merge; the Rugnux results report defines what each one means. Both datasets are absent unless the sweep-quality diagnostic ran, which needs scaling and merging; their absence therefore means “not looked for”, not “every image clean”. Written by the offline rugnux path only — the broker does not merge — and not carried on the CBOR stream, in the same way as the other offline-only fields (reindexMatrix, the refined geometry). The condensed, dataset-wide form of the same finding is in <prefix>_report.txt.

Frame disposition. frameDisposition [n_images] (uint8) says what became of the image’s observations: a 0-based index into frameDispositionCodes, written beside it, which reads merged, downgraded, rejected. Where sweepQuality says what was seen over a stretch, this says what was done about it — a rejected image contributed nothing to the merged intensities. Same availability rule as sweepQuality: absent means the diagnostic never ran.

CrystFEL can read the spots directly with:

peak_list = /entry/MX
+peak_list_type = cxi
+

4.2 /entry/reflections — integrated reflections (NXreflections)

Integrated reflections - written where rugnux integrated the images (rugnux, or the broker’s rugnux live mode for serial collections; the broker’s own per-image analysis does not integrate) - are stored per image as /entry/reflections/image_NNNNNN groups, each declared NX_class = NXreflections. The columns map mostly onto the standard NXreflections base class:

Dataset

Units

NXreflections

Meaning

h, k, l

standard

Miller indices

d

Å

standard

resolution

int_sum

photons

standard

integrated intensity (summation)

int_err

photons

non-standard name

σ of the intensity (standard equivalent: int_sum_errors)

background_mean

photons

standard

mean background under the peak

background_variance

photons²

non-standard

non-signal part of σ², carried to the merge. Absent in files written before it existed; the reader then recovers it from σ² − I

predicted_x, predicted_y

pixel

name standard, units differ

predicted position. NXreflections predicted_x/_y are physical lengths; the pixel datasets are predicted_px_x/_y

observed_x, observed_y

pixel

name standard, units differ

observed centroid (pixels; standard pixel form is observed_px_x/_y)

observed_frame

standard

image number of the reflection

lp

standard

the Lorentz-polarization factor, stored as the reciprocal of the multiplier that is applied. Lorentz x polarization only, which is what the NXreflections name means; the sensor efficiency is qe, beside it

qe

extension

the sensor efficiency, in the same reciprocal convention as lp, so the whole correction applied to a raw count is 1/lp * 1/qe. Absent in files written before it existed; the reader then takes the whole of lp for Lorentz–polarization, which is what those files mean

flight

extension

the flight path between sample and pixel, in the same reciprocal convention as lp and qe, so the whole correction applied to a raw count is 1/lp * 1/qe * 1/flight. It runs the opposite way to qe — at most 1 where qe is at least 1 — because the medium attenuates an oblique reflection where the sensor favours it. Exactly 1 under --flight-path vacuum, and absent in files written before it existed; the reader then takes it as 1

partiality

standard

recorded fraction of the reflection

delta_phi

deg

extension

XDS Δφ: offset from the centre of the current frame

zeta

extension

Lorentz ζ factor (reciprocal-space geometry term)

image_scale_corr

extension

per-image scale correction; I_true = image_scale_corr · int_sum

excitation_error

Å⁻¹

extension

distance of the reflection from the Ewald sphere

observed

extension (uint8)

1 where the reflection was observed on the image

clipped

extension (uint8)

1 where the signal disk lost pixels to the mask or to saturation, so the intensity is the profile’s estimate over what remained; the merge does not let such a measurement testify against a larger one of the same reflection

overloaded

extension (uint8)

1 where a pixel of the signal disk was saturated; a rotation merge drops the whole rocking event, as XDS does

In the master file these per-image groups are exposed through /entry/reflections external links (VDS/integrated formats).

4.3 /entry/azint — azimuthal integration

Dataset

Shape

Units

Meaning

bin_to_q

[φ_bins, q_bins]

Å⁻¹

q value of each bin (its centre: arithmetic mean of the edges for linear bins, geometric mean for log10 bins)

bin_to_two_theta

[φ_bins, q_bins]

deg

2θ of each bin

bin_to_phi

[φ_bins, q_bins]

deg

azimuthal angle of each bin

image

[n_images, φ_bins, q_bins]

per-image integrated profile (NaN for empty bins)

image_std

[n_images, φ_bins, q_bins]

per-bin standard deviation

image_count

[n_images, φ_bins, q_bins]

pixels contributing per bin

map

[y, x]

pixel→bin mapping (master file only)

4.4 /entry/roi — regions of interest (per-image results)

/entry/roi/<roi_name> has one sub-group per configured ROI, holding the per-image result vectors [n_images]. These are written into the data files; in VDS mode they are exposed from the master file through virtual datasets, and in integrated mode they are in the single file. (In legacy mode they remain only in the data files.)

Dataset

Meaning

max

maximum pixel value in the ROI

sum

sum of pixel values

sum_sq

sum of squared pixel values

npixel

number of valid pixels

x, y

intensity-weighted centroid

4.4.1 /entry/roi_defs — ROI definitions (master file)

The dataset-wide ROI definitions (geometry, fixed for the whole acquisition) live in the master file under a separate /entry/roi_defs group — kept apart from /entry/roi above so that older readers, which iterate /entry/roi, are unaffected by these entries. One sub-group /entry/roi_defs/<roi_name> per ROI:

Dataset

Meaning

bit_index

which bit of roi_map (below) marks this ROI

type

box, circle or azim

min_x_pxl, max_x_pxl, min_y_pxl, max_y_pxl

box bounds (type box)

center_x_pxl, center_y_pxl, radius_pxl

circle (type circle)

q_min_recipA, q_max_recipA

Q range (type azim)

phi_min_deg, phi_max_deg

azimuthal-angle sector (type azim, omitted for a full ring)

/entry/roi_defs/roi_map [y, x] is a uint16 per-pixel bitmask: bit bit_index is set for every pixel belonging to that ROI, so an ROI’s footprint can be recovered exactly.

4.5 /entry/image — per-image pixel statistics

[n_images] vectors: max_value, min_value (viable min/max, excluding error/saturated pixels), error_pixels, saturated_pixels, pixel_sum. Surfaced in the master file under /entry/image. pixel_sum is the signed sum of the pixels that are not error, not saturated and not under the device mask (detector and calibration); a mask rugnux determines on the run’s own frames (hot pixels, beam-stop shadow, inactive pixels) does not change it. The FPGA computes it per module, and CPU/GPU analysis (e.g. EIGER) per image, on the assembled image, to the same definition.

4.6 /entry/profiling — per-image timing

[n_images] vectors in seconds: spotFindingTime, indexingTime, integrationTime, refinementTime, processingTime, braggPredictionTime, preprocessingTime, compressionTime, azIntTime, indexAnalysisTime, imageScaleTime.

4.7 /entry/detector — acquisition diagnostics (data file)

A convenience NXcollection in the data file (note: distinct from the standard /entry/instrument/detector). In integrated format the diagnostics below number are written under /entry/instrument/detector/detectorSpecific instead; timestamp, exptime and number stay here.

Dataset

Meaning

timestamp, exptime

per-image timestamp and exposure time

number

image number (original number if image rejection was used)

det_info

JUNGFRAU debug field

storage_cell_image

storage-cell number

rcv_delay, rcv_free_send_buffers

receiver internal diagnostics

packets_expected, packets_received

UDP packets per image

data_collection_efficiency_image

received / expected packet ratio

4.8 /entry/xfel — pulsed-source metadata

[n_images] vectors pulseID (uint64) and eventCode (uint32), written for pulsed sources (e.g. SwissFEL): the XFEL pulse ID and the event code of each image, as the detector’s timing receiver recorded them. A pulse ID of UINT64_MAX marks an image whose modules disagreed on it. They are written to the data files and, for a VDS master, mapped into the master as well.

In a _process.h5, /entry/xfel/pulseID and /entry/xfel/eventCode hold the IDs of the images processed, in the file’s own image order: entry i belongs to the image whose analysis is at index i (/entry/MX/...[i], /entry/reflections/image_<i>), the source image /entry/detector/number[i]. With a subset or a stride (-s/-e/--stride) only the processed images are there; several inputs read as one keep them only where every input has them.

4.9 Other collections

Path

Class

Content

/entry/instrument/detector/detectorSpecific

NXcollection

Dectris-style detector metadata + Jungfraujoch fields: x_pixels_in_detector, y_pixels_in_detector, nimages, ntrigger, nimages_collected, nimages_written, data_collection_efficiency, max_receiver_delay, storage_cell_number, storage_cell_delay [ns], software_git_commit, software_git_date, jfjoch_release, jfjoch_writer_release, summation_mode, detect_ice_rings, gain_file_names, data_reduction_factor_serialmx, adu_histogram/ (bin_width and one vector per storage cell), data_collection_efficiency_image, direct_beam_x, direct_beam_y, pixel_mask (hard-linked as /entry/instrument/detector/pixel_mask), storage_cell_image (VDS, with storage cells)

/entry/instrument/detector/calibration

NXcollection

per-channel pedestal / calibration images (bitshuffle-compressed)

/entry/instrument/fluorescence

NXcollection

XRF spectrum: energy [eV], data

/entry/user

NXcollection

scalar values supplied under header_appendix.hdf5

4.10 Non-standard fields inside the NXmx detector group

A few extension scalars are written inside the otherwise-standard /entry/instrument/detector group for compatibility with existing tooling:

Field

Units

Meaning

detector_distance

m

duplicate of distance (Dectris/Neggia compatibility)

detector_number

detector identifier (Dectris convention)

mirror_y (in detectorSpecific)

whether the stored image is mirrored in Y relative to the raw readout; true is the MX convention (row 0 at the top)

detector_orientation_mirror_y (in detectorSpecific)

whether the stored image is mirrored in Y relative to the frame rot1/rot2/rot3 are stated in — a different setting from mirror_y, and one that changes no pixel

detector_orientation_quarter_turns (in detectorSpecific)

multiples of 90° about the beam the stored image is turned by, relative to that same frame (0-3)

direct_beam_x, direct_beam_y (in detectorSpecific)

pixel

where the undeflected beam lands, as opposed to the PONI in beam_center_x/beam_center_y - see above

error_value

masked/error pixel sentinel: UINTx_MAX unsigned, INTx_MIN signed (NXmx has no equivalent). NXmx underload_value is written too: INTx_MIN + 1 for signed, 0 for unsigned

bit_depth_image

stored image bit depth (DECTRIS convention, not NXmx). Equal to bit_depth_readout where that is written, i.e. for unsigned images

acquisition_type

always triggered (Dectris convention)

jungfrau_conversion_applied

JUNGFRAU photon/keV conversion applied

jungfrau_conversion_factor

eV

conversion factor

geometry_transformation_applied

module→full-detector geometry applied

NeXus has no concept of a fill or no-data value — it expects bad pixels to be flagged in pixel_mask, which Jungfraujoch also writes. The in-band sentinel above is a DECTRIS compatibility convention: SIMPLON specifies that masked pixels are flagged with 2^bit_depth_image - 1.

For an unsigned image the sentinel and the saturation code are the same value, so a saturated pixel and a masked one cannot be told apart — the FPGA collapses both onto UINTx_MAX. Signed images keep them separate: INTx_MIN is the marker, INTx_MAX is saturation.

bit_depth_readout is written for unsigned images only. DIALS remaps the top two codes of 2^bit_depth_readout to -1 and -2 whenever the field is present, regardless of the pixel type: for an unsigned image those land below underload_value and are correctly masked, but for a signed one they land inside the trusted range and a saturated pixel would be integrated as a count of -2. Signed images are read correctly without the field; unsigned 32-bit cannot be read at all without it.

4.11 User-supplied metadata: header_appendix and image_appendix

Facilities frequently need to attach metadata that Jungfraujoch does not model explicitly. Two free-form JSON fields in the /start request (broker/jfjoch_api.yaml) provide this without any schema change; both accept any valid JSON:

Field

Carried in

Persisted to HDF5?

header_appendix

the start message, under user_data.user (see CBOR)

no — except the hdf5 sub-object (below)

image_appendix

every image message, as user_data

no

Both are forwarded verbatim through the ZeroMQ/CBOR stream to every downstream consumer (writer, republished analysis, viewers), so they are the recommended channel for facility- or beamline-specific provenance (proposal, operator, optics state, per-image trigger info, …) that has no dedicated API field.

Persisting selected values to HDF5. header_appendix is normally not written to the master file. As an exception, if it contains a key hdf5 whose value is a JSON object of scalars (strings and numbers — no arrays or nested objects), the writer stores each entry under /entry/user/<key>.

For example, a /start request containing:

{
+  "header_appendix": {
+    "proposal": "p20001",
+    "operator": "jdoe",
+    "hdf5": { "beamline": "X06SA", "ring_mode": "top-up", "attenuator_foils": 2 }
+  },
+  "image_appendix": { "trigger_source": "external" }
+}
+

forwards the whole header_appendix as user_data.user on the start message and {"trigger_source": "external"} as user_data on every image message, and writes three scalars into the master file:

/entry/user/beamline          = "X06SA"
+/entry/user/ring_mode         = "top-up"
+/entry/user/attenuator_foils  = 2
+

5. Notes

  • Units are written as the HDF5 units attribute on the dataset (e.g. m, eV, deg, Angstrom, Angstrom^-1, Angstrom^2, pixel, s).

  • Sentinels. Missing per-image values are NaN (floats) or -1/0 (integer indices); image pixels use INTx_MIN / UINTx_MAX.

  • Master vs data file. In legacy/VDS formats the analysis arrays physically live in the data files; the master file links to them (external links in legacy, virtual datasets in VDS). In the integrated format there are no data files and everything is in one place.

  • CXI / CrystFEL. /entry/MX follows the CXI peak-list convention; see CXI file format.

\ No newline at end of file diff --git a/IMAGE_STREAM.html b/IMAGE_STREAM.html new file mode 100644 index 000000000..aa10fb514 --- /dev/null +++ b/IMAGE_STREAM.html @@ -0,0 +1,30 @@ + Data streams — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Data streams

The Jungfraujoch process (jfjoch_broker) operates three outputs. All three can be operated/enabled independently. These are:

  • Image - all the images including metadata (ZeroMQ PUSH socket or custom TCP/IP socket)

  • Preview - images with metadata at a reduced frame rate (PUB socket)

  • Metadata - only metadata for all the images, bundled into packages (PUB socket)

Image stream

Images (with metadata) are serialized as CBOR image message. The stream will also include CBOR start message, calibration messages and end message with run metadata. Calibration messages (the JUNGFRAU pedestal and pedestal RMS, with save_calibration on) come only from the FPGA workflow; a DECTRIS stream carries no calibration, so none is forwarded for it.

If file_prefix is not provided for a data collection, images won’t be sent to image stream (or its HDF5/CBOR replacements).

Splitting image stream

Image stream can be split into multiple sockets to increase performance, in this case images will be split according to file number to which the image belongs. All sockets will forward start and end messages. Only the first socket will forward calibration messages and will be marked to write master file.

ZeroMQ image stream

This is using PUSH ZeroMQ socket(s). Multiple receivers must never be connected to one PUSH ZeroMQ socket. ZeroMQ will send the images in a round-robin basis to the receivers. In this case start and end messages will end up only with one receiver. Instead, Jungfraujoch feature of multiple sockets should be used. For ZeroMQ image stream, each writer connects to a different port.

Behavior is as following:

  • Start message is sent with timeout of 1s per socket. If within the time the message cannot be put in the outgoing queue or there is no connected puller, an exception is thrown — data collection is stopped with an error due to absence of a writer.

  • Calibration message is sent to the first socket only, with timeout of 1s.

  • Images are sent via a per-socket writer thread. If a send times out, the pusher switches to non-blocking mode for the remainder of the collection (images may be dropped).

  • End message is sent with timeout of 1s per socket. No exception is thrown on timeout, but a transmission error is recorded.

The format is generally interchangeable with DECTRIS Stream2 format.

ZeroMQ configuration

ZeroMQ image stream is configured in the broker JSON configuration file under the zeromq section (schema zeromq_settings):

{
+  "image_socket": ["tcp://192.168.0.1:9000", "tcp://192.168.0.1:9001"],
+  "send_watermark": 100,
+  "send_buffer_size": 67108864,
+  "writer_notification_socket": "tcp://192.168.0.1:*"
+}
+
  • image_socket: one or more PUSH socket addresses. Multiple entries split the image stream across sockets. Addresses follow ZeroMQ conventions (tcp://, ipc://). 0.0.0.0 binds on all network interfaces.

  • send_watermark (optional): ZeroMQ send high-water mark (number of outstanding messages per socket).

  • send_buffer_size (optional): OS-level send buffer size for the ZeroMQ socket.

  • writer_notification_socket (optional): see Writer notification socket below.

TCP/IP image stream

This is using TCP/IP socket(s) with a fixed binary frame header followed by payload bytes. This format was introduced to Jungfraujoch as an alternative to ZeroMQ image stream. It allows two-way communication between the data collection and the writer, and is therefore more robust than ZeroMQ.

For TCP/IP image stream, Jungfraujoch listens on a single TCP port and all writers connect to it. Connections are persistent — writers connect once and stay connected across multiple data collections. Jungfraujoch sends periodic KEEPALIVE frames when no data collection is active to detect dead connections; writers are expected to respond with a KEEPALIVE pong.

Using * as port number (e.g. tcp://127.0.0.1:*) is supported — the OS assigns a free port.

Payloads for PREFLIGHT, START, DATA, CALIBRATION and END frames are CBOR messages, equivalent in content to the ZeroMQ image stream messages.
ACK, CANCEL, KEEPALIVE and BUSY are control frames (no CBOR payload).

The data collection lifecycle on each connection follows: PREFLIGHT → START → CALIBRATION (socket 0 only) → DATA (repeated) → END

If a START ACK fails on any connection, Jungfraujoch sends CANCEL to all already-started connections and rolls back.

For each frame:

  1. Read one TcpFrameHeader (fixed size, 64-byte aligned).

  2. Validate magic (0x4A464A54 / "JFJT") and version (5). Both ends reject a frame of any other version, so writer and broker must be of the same release.

  3. Read payload_size bytes (if non-zero).

Pre-flight

Before a data collection is started - before the detector is armed - Jungfraujoch sends a PREFLIGHT frame on every connection and waits for its ACK. It carries the same CBOR start message a START would, and asks the writer one question: could this run be written? The writer checks the output path, creates the output directory, and checks that no output file is in the way; it opens nothing, writes nothing, and does not change its state. A run that would fail on the first file it wrote is therefore refused while refusing it is free, with the writer’s own message reported to the client by /start and /wait_until_running.

write_master_file is assigned exactly as it is for START (connection index 0), and the writer that owns the master file is the one that answers for the output files - the master and every data file the run will write, its siblings’ included.

The PREFLIGHT payload describes the run but carries none of the per-pixel arrays a START does - no pixel mask, no azimuthal-integration map, no ROI map - so it stays small: about 1.4 kB on a JUNGFRAU 9M, against about 540 kB for the START that follows.

A rejected PREFLIGHT is not fatal: nothing was started, so the connection stays usable and the next attempt (a different file prefix, or overwrite set) proceeds on it. The check cannot be exhaustive - a file created in the moment between the pre-flight and the start still fails at the start, and free space and quota are not inspected - so it lowers how often a run fails on its output, it does not remove the case.

When image stream is split into multiple connections:

  • START and END are sent on all connections,

  • CALIBRATION is sent only on connection 0,

  • DATA frames are distributed by file grouping: connection index = (image_number / images_per_file) % num_connections.

TCP/IP configuration

TCP/IP image stream is configured in the broker JSON configuration file under the tcp section (schema tcp_settings):

{
+  "image_socket": "tcp://192.168.0.1:9100",
+  "nwriters": 2,
+  "send_buffer_size": 67108864
+}
+
  • image_socket: listen address in tcp://<IP>:<port> format. 0.0.0.0 binds on all interfaces. * as port selects a random free port.

  • nwriters (optional): maximum number of simultaneous writer connections accepted.

  • send_buffer_size (optional): OS-level SO_SNDBUF size for accepted connections.

  • peer_liveness_timeout_ms (optional, default 15000): how long a send may block with no sign of life from the writer (no BUSY heartbeat, no ACK) before the connection is declared dead.

  • max_backpressure_timeout_ms (optional, default 60000): hard bound on backpressure - if no bytes can be sent for this long the connection is declared dead even while the writer keeps heartbeating.

ACK handling

ACK handling is mandatory for correct operation:

  • PREFLIGHT must be acknowledged (ack_for=PREFLIGHT) on each connection within 5 seconds, otherwise the collection is not started. A rejected pre-flight (OK clear) carries the reason as error text and does not break the connection.

  • START must be acknowledged (ACK with ack_for=START) on each connection within 5 seconds, otherwise collection start fails and a rollback is triggered.

  • END must be acknowledged (ack_for=END) on each connection for successful completion. There is no fixed deadline: the writer may still be flushing a backlog, so the broker waits as long as the writer shows signs of life (BUSY heartbeats, DATA ACKs) and gives up only after peer_liveness_timeout_ms (default 15 s) of silence.

  • CANCEL should be acknowledged during rollback paths (500ms timeout).

  • DATA should be acknowledged for every frame. A DATA ACK with FATAL flag set reports a downstream error (e.g. disk full) which is propagated to jfjoch_broker via Finalize(). A failed DATA ACK does not break the TCP connection on its own — data continues to flow.

  • CALIBRATION is not acknowledged at this time.

  • KEEPALIVE frames are not acknowledged via ACK; the writer responds with a KEEPALIVE pong frame instead.

Keepalive

When no data collection is active, Jungfraujoch sends KEEPALIVE frames approximately every 5 seconds on each persistent connection. Writers should respond with a KEEPALIVE frame (pong). OS-level TCP keepalive is also enabled (TCP_KEEPIDLE=30s, TCP_KEEPINTVL=10s, TCP_KEEPCNT=3) as a secondary safety net. Dead connections are automatically removed from the pool.

Zero-copy transmission

On Linux, large payload transmission (DATA and CALIBRATION frames) can use kernel TCP zero-copy (SO_ZEROCOPY/MSG_ZEROCOPY) when available. If the kernel does not support it or the socket option fails, transmission transparently falls back to normal send() behavior. Zero-copy completion notifications are processed by a dedicated per-connection thread.

Frame types

Value

Name

Purpose

1

START

Start-of-run metadata

2

DATA

One image payload

3

CALIBRATION

Calibration payload

4

END

End-of-run metadata

5

ACK

Acknowledgement / error reporting

6

CANCEL

Cancel run initialization/stream

7

KEEPALIVE

Connection liveness probe/pong

8

BUSY

Writer alive but stalled; carries its FIFO occupancy

9

PREFLIGHT

Dry run before a collection starts: can this run be written?

10

FILE_CLOSED

Not a frame of its own: the value of ack_for in a writer ACK reporting that a data file was closed and renamed into place (image_number = file number from 0, ack_processed_images = one past the highest image number it holds). The broker uses it to tell a reader following the collection which files it can read.

TCP frame header (TcpFrameHeader)

Field

Type

Description

magic

uint32_t

Protocol magic (0x4A464A54, "JFJT")

version

uint16_t

Protocol version (5)

type

uint16_t

Frame type (see table above)

image_number

uint64_t

Image index for DATA frames

payload_size

uint64_t

Number of payload bytes after header

socket_number

uint32_t

Connection index in split-stream mode

flags

uint32_t

ACK flags (OK, FATAL, HAS_ERROR_TEXT)

run_number

uint64_t

Run identifier

ack_processed_images

uint32_t

In ACK: number of images processed by receiver

ack_code

uint16_t

In ACK: error/status code

ack_for

uint16_t

In ACK: frame type being acknowledged

ack_fifo_occupancy

uint64_t

In ACK: occupancy of input FIFO in the jfjoch_writer

ack_fifo_max_occupancy

uint64_t

In ACK: max occupancy of input FIFO

The header is 64-byte aligned (alignas(64)).

ACK semantics

  • ACK frames use ack_for to indicate which frame type is acknowledged.

  • flags:

    • OK (bit 0): operation accepted/successful,

    • FATAL (bit 1): receiver reports unrecoverable error (primarily for DATA),

    • HAS_ERROR_TEXT (bit 2): ACK payload contains UTF-8 error text.

  • ack_code can be used to categorize errors:

Code

Name

Meaning

0

None

No error

1

StartFailed

START processing failed

2

DataWriteFailed

Image write failed

3

EndFailed

END processing failed

4

DiskQuotaExceeded

Disk quota exceeded

5

NoSpaceLeft

No space left on device

6

PermissionDenied

Permission denied

7

IoError

General I/O error

8

ProtocolError

Protocol-level error

Image stream replacement

Image stream can be replaced with direct HDF5 writer and CBOR dump image pushers, or it can be disabled by selecting “None” image pusher for all the measurements.

Writer notification socket

The writer notification socket is used only with ZeroMQ image stream. Since ZeroMQ is asynchronous, jfjoch_broker does not know whether messages were properly handled downstream (e.g. written to disk). The writer notification socket allows downstream code to report back.

For TCP/IP image stream, this mechanism is not needed — ACK frames provide synchronous feedback for each control and data frame.

To use writer notification socket, it has to be first enabled in the JSON configuration file of broker with writer_notification_socket entry:

{
+  "writer_notification_socket":"tcp://192.168.0.1:*"
+}
+

Such entry will create PULL socket on 192.168.0.1 network interface listening on one, random TCP port. When data processing is started, the image stream will send CBOR start message. This message will include information on writer_notification_zmq_addr, which needs to be used by downstream code. Since the start message must reference the address of jfjoch_broker host, notification socket should always listen on a particular network interface, and should not be configured with placeholder address 0.0.0.0. It is, however, OK to use placeholder :* for network port, as it will be substituted for the one chosen by ZeroMQ.

For every image stream socket, downstream code must send the following message to the PULL socket:

{
+  "run_number":135,
+  "run_name": "sample_1",
+  "socket_number": 1,
+  "processed_images":250,
+  "ok": true
+}
+

Here run_number, run_name and socket_number must match information from the start message. ok is boolean confirming if the writing process was OK. processed_images is number of images that were written/processed, this is to track how many images were ignored by non-blocking ZeroMQ procedures. If the writing failed, an error message can be included:

{
+  "run_number":135,
+  "run_name": "sample_1",
+  "socket_number": 1,
+  "processed_images": 0,
+  "ok": false,
+  "error": "Permission error"
+}
+

This way errors from the downstream code are propagated to jfjoch_broker.

If writer notification socket is configured, but downstream code doesn’t send proper notification, jfjoch_broker will time out after 60 seconds producing an error message.

Preview stream

Jungfraujoch can also send images (with metadata) at a reduced frame rate for preview purpose. Images are serialized as CBOR image message. The stream will also include CBOR start message and end message with run metadata.

This is using PUB socket with conflate option. I.e., only the last message is kept by ZeroMQ, so if receiver cannot cope with the messages, it will always receive the last generated message (no backlog). For this reason it is also recommended to use the same option on receiver side.

Given PUB socket properties, it is possible to connect multiple viewers to a single socket — all the viewers should receive all the images sent.

The dark frames of the mask sequence from a DECTRIS detector are no images for a viewer: nothing is sent on this stream for them, not even a start or end message.

Metadata stream

Jungfraujoch can also send pure metadata for the purpose of archiving such information. Metadata are serialized as CBOR metadata message. This is very similar to the image message, but excludes the image array, the spot list and the reflection list. As metadata are relatively small, to avoid large number of messages, Jungfraujoch bundles metadata of many images in one message: a bundle is cut every period_ms of the zeromq_metadata configuration and holds the images analysed since the last one. Order of images within bundle, as well as the size of the bundle, are not guaranteed, and two bundles cut close together can leave in either order; the end message is always last. The stream will also include CBOR start message and end message with run metadata. A disabled metadata stream keeps nothing, and the dark frames of the mask sequence from a DECTRIS detector send nothing on it, as on the preview stream.

This is using PUB socket with watermark, so there is some queuing of messages with ZeroMQ. Multiple receivers can be connected.

\ No newline at end of file diff --git a/JFJOCH_BROKER.html b/JFJOCH_BROKER.html new file mode 100644 index 000000000..ce7169143 --- /dev/null +++ b/JFJOCH_BROKER.html @@ -0,0 +1,124 @@ + jfjoch_broker — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

jfjoch_broker

jfjoch_broker is the main service for the Jungfraujoch application. It is responsible for:

  • Providing user interface via HTTP and OpenAPI

  • Configuring FPGA firmware

  • Building images from FPGA output and forwarding the results over ZeroMQ

External interfaces

Broker operates four external interfaces.

Image stream ZeroMQ PUSH socket with CBOR serialization is used to send images, metadata and processing results for writing or downstream processing. See details here.

Preview stream ZeroMQ PUB socket, as above but limited to subset of frames (1 image/s by default). See details here.

Metadata stream ZeroMQ PUB socket, contains metadata for all the images, with bundling. See details here.

Configuration, status and results interface HTTP/REST interface described in the OpenAPI format. Description of the API is presented in the OpenAPI specification.

A dataset can be protected: /start takes an optional tokens list, and while the current dataset has any, its statistics (/statistics/data_collection, /result/scan), buffered images (/image_buffer/*.cbor|jpeg|tiff) and plots (/preview/plot*) need Authorization: Bearer <token> and answer 401 otherwise; /statistics omits its measurement block instead. See Security.

/start also takes an optional module_placement: where the JUNGFRAU modules lie, as rugnux measures them on an earlier run. rugnux writes it as <prefix>_module_placement.json, a fragment of the dataset settings ({"module_placement": [...]}) to merge into the /start body. Each entry has eight required fields: it names its module as custom_geometry does - x0, y0 (the image position of its readout pixel 0) and fast_axis, slow_axis - but in the image as stored, after mirror_y (see below), and gives where the module lies on the detector plane (x0_plane, y0_plane, fast_step, slow_step). The first four identify the module, so the order does not matter, and a list that does not name exactly the detector’s modules (one left out, named twice, or not the detector’s) is refused with 400. The module count and the assembly are the configuration’s (custom_geometry below); the placement only moves the modules relative to one another, and goes into the start message, the master file’s module_NN groups and the broker’s analysis. See Module placement file.

Broker configuration

jfjoch_broker requires JSON configuration files. The file is described by OpenAPI structure jfjoch_settings defined in jfjoch_api.yaml file. It is recommended to go through example files in the etc/. In custom_geometry, a module’s x0, y0 are where its readout pixel 0 goes in the image, and fast_axis/slow_axis say which way its fast and slow readout axes run from there - in the image as assembled, before mirror_y. The module_placement of /start uses the same words, but in the image as stored, after mirror_y, because that is the only image a file reader (rugnux) sees. With mirror_y on the two differ by the mirror: for an image of height H, y0 (module_placement) = H - 1 - y0 (custom_geometry), x0 is the same, and Yp and Yn swap in fast_axis/slow_axis. With mirror_y off they are equal.

Example configuration (etc/broker_local.json, broker_eiger.json and broker_crmx.json are complete, runnable configurations; a detector takes either standard_geometry or custom_geometry, never both):

{
+  "pcie": [
+    {
+      "blk": "/dev/jfjoch0",
+      "ipv4": "10.1.1.7"
+    },
+    {
+      "blk": "/dev/jfjoch1",
+      "ipv4": "10.1.1.8"
+    }
+  ],
+  "zeromq": {
+    "send_watermark": 100,
+    "send_buffer_size": 1024,
+    "image_socket": [
+      "tcp://1.2.3.4:5000",
+      "tcp://1.2.3.4:5001"
+    ],
+    "writer_notification_socket": "tcp://1.3.4.6:7000"
+  },
+  "instrument": {
+    "source_name": "Swiss Light Source",
+    "source_type": "Synchrotron X-ray Source",
+    "instrument_name": "X06SA",
+    "pulsed_source": false,
+    "electron_source": false
+  },
+  "detector": [
+    {
+      "description": "EIGER 1M",
+      "serial_number": "E1M-01",
+      "type": "EIGER",
+      "high_voltage_V": 150,
+      "udp_interface_count": 1,
+      "module_sync": true,
+      "sensor_thickness_um": 320,
+      "calibration_file": [
+        "/opt/jfjoch/eiger/trim/e1m-01.sn001",
+        "/opt/jfjoch/eiger/trim/e1m-02.sn002"
+      ],
+      "trim_energies_eV": [
+        12400
+      ],
+      "hostname": [
+        "e1m-01",
+        "e1m-02"
+      ],
+      "readout_time_ns": 3000,
+      "sensor_material": "Si",
+      "tx_delay": [
+        0,1
+      ],
+      "base_data_ipv4_address": "10.10.10.50",
+      "custom_geometry": [
+        {
+          "x0": 0,
+          "y0": 0,
+          "fast_axis": "Xp",
+          "slow_axis": "Yp"
+        }
+      ],
+      "mirror_y": true
+    }
+  ],
+  "detector_settings": {
+    "frame_time_us": 450,
+    "count_time_us": 0,
+    "internal_frame_generator": false,
+    "internal_frame_generator_images": 1,
+    "detector_trigger_delay_ns": 0,
+    "timing": "auto",
+    "eiger_threshold_keV": 6.0,
+    "jungfrau_pedestal_g0_frames": 2000,
+    "jungfrau_pedestal_g1_frames": 300,
+    "jungfrau_pedestal_g2_frames": 300,
+    "jungfrau_pedestal_min_image_count": 128,
+    "jungfrau_storage_cell_count": 1,
+    "jungfrau_storage_cell_delay_ns": 5000,
+    "jungfrau_fixed_gain_g1": false,
+    "jungfrau_use_gain_hg0": false
+  },
+  "azim_int": {
+    "polarization_corr": true,
+    "solid_angle_corr": true,
+    "low_q_recipA": 0.01,
+    "q_spacing": 0.002
+  },
+  "image_format": {
+    "summation": true,
+    "geometry_transform": true,
+    "jungfrau_conversion": true,
+    "jungfrau_conversion_factor_keV": 0.001,
+    "bit_depth_image": 16,
+    "signed_output": true,
+    "mask_module_edges": true,
+    "mask_chip_edges": true,
+    "apply_mask": true,
+    "jungfrau_pedestal_g0_rms_limit": 100
+  },
+  "image_buffer_MiB": 2048,
+  "receiver_threads": 64,
+  "frontend_directory": "/usr/share/jfjoch/frontend",
+  "image_pusher": "ZeroMQ",
+  "zeromq_metadata": {
+    "enabled": true,
+    "period_ms": 1000,
+    "socket_address": "tcp://0.0.0.0:4357"
+  },
+  "zeromq_preview": {
+    "enabled": true,
+    "period_ms": 1000,
+    "socket_address": "tcp://0.0.0.0:4356"
+  }
+}
+

standard_geometry (nmodules, modules_in_row, gap_x, gap_y) is the alternative for a regular module grid. For an EIGER hostname lists two entries per module (one per half-module) and calibration_file is either a directory of trim files or one trim file per half-module, with the energies they were trimmed at in trim_energies_eV; for a JUNGFRAU both are one entry per module, the calibration being the gain maps. The polarization factor of the azimuthal integration is a dataset setting (/config/dataset, polarization_factor), not part of azim_int. The Q bins of azim_int are linear by default, set by q_spacing (0.01 Å⁻¹ when nothing is given) or by their number, q_bins - one or the other, not both. "q_binning": "log10" lays them out in equal steps of log10 Q instead (fine at low Q, coarse at high Q); it takes q_bins and refuses q_spacing. A GET returns the one that was set, so once q_bins (or log10) is configured the reply carries q_bins and no q_spacing, which a client generated before q_spacing became optional cannot parse.

Following a collection

A reader can process a collection while it is being written - rugnux does, given the path the master file will have and the broker’s address (rugnux <prefix>_master.h5 http://<broker>:<port>/), started any time after /start was accepted. The images still travel as files; the broker says which files exist. GET /live/events, protected by the dataset’s bearer tokens like the other dataset routes, streams server-sent events for the current collection from the moment /start accepted it: its history first, then every change. start comes first, once the start message is known - at once for a JUNGFRAU, when the detector sends its own for a DECTRIS - with that start message (CBOR, in base64); a reader builds the dataset from it. Then file (file number, file name relative to the collection’s root, first image, image count) for each data file a writer has closed and renamed into place, and end (images collected, and an error if any) once every writer has acknowledged the end, so the data files and the master file are in place - or, with an error, when the measurement ended any other way. A comment line every 10 s keeps the connection alive. One reader at a time; a second one gets 409.

The writers report each closed data file to the broker (TCP protocol version 5, an acknowledgement for FILE_CLOSED); the in-process HDF5 writer reports to it directly. The ZeroMQ writer has no way back to the broker, so with it the route answers 409.

Online analysis

Without rugnux live mode, and in the FPGA workflow also for a rotation collection with it, the broker analyses each image on its own: masking, summation, azimuthal and ROI integration, spot finding, and - with indexing on - indexing of the image and refinement of its geometry (geom_refinement_algorithm). A rotation collection is indexed image by image, as a serial one. The broker neither integrates Bragg reflections nor determines a lattice for the whole rotation sweep, so the reflections, the per-image B-factor and integrated-reflection count, and the rotation lattice are filled only where rugnux processed the data: by rugnux live mode (below) during the collection, or by rugnux from the written files. indexing_settings.rotation_indexing, rotation_indexing_min_angular_range_deg, rotation_indexing_angular_stride_deg and spot_finding_settings.quick_integration are deprecated: accepted, ignored, and returned at their old defaults. bragg_integration_settings apply to rugnux live mode.

The receiver of a run

Each run is taken by one receiver, chosen when it starts from the detector type, the detector mode, the goniometer and the rugnux live setting:

Input

Run

Receiver

What it does

FPGA cards (PSI JUNGFRAU, PSI EIGER)

every run

JFJochReceiverFPGA

the card’s converted pixels, spots, azimuthal and ROI sums into the image; summation on the host above what the card sums; indexing of each image; the calibration to the writer; pedestal runs into the pedestal and its RMS; with rugnux live on, a serial run analysed on the GPU after a rugnux pre-pass (see Serial collections)

DECTRIS stream

dark-mask sequence

JFJochReceiverDarkMask

the dark frames into the mask; nothing on any stream

DECTRIS stream

rugnux live off, or a rotation run the image buffer cannot hold

JFJochReceiverLite

each image on the GPU: masking, azimuthal and ROI integration, spot finding, indexing

DECTRIS stream

rugnux live on, rotation that fits the image buffer

JFJochReceiverRugnuxRotation

images forwarded as they come; rugnux reads the collection back from the image buffer and runs the whole pipeline

DECTRIS stream

rugnux live on, serial (or rotation with force_still)

JFJochReceiverRugnuxStills

a rugnux pre-pass on the first frames, then every frame analysed and integrated on the GPU and merged live

receiver_threads is the number of image threads. The Lite receiver uses at most 16 of them for a collection at 100 Hz or slower or of fewer than 256 images (each thread holds a GPU analysis of its own); the FPGA receiver takes four when it sums images on the host. The GPU FFT indexers and cuFFT plans the broker’s own indexing uses are built once and kept for the life of the process, and the ones built for earlier indexing settings are released when the settings change. azim_int.force_cpu moves the azimuthal integration of the FPGA workflow from the card to the host, which a profile with more bins than the card holds needs.

Rugnux live mode

With rugnux live mode on, collections from a DECTRIS detector are processed inside the broker while they arrive: rotation collections by rugnux, and serial (stills) collections on the GPU with the geometry and mask a rugnux pre-pass decided (see Serial collections below). In the FPGA workflow (PSI JUNGFRAU and EIGER) serial collections are analysed on the GPU after a pre-pass as well, with the differences given there; rotation collections run image by image, as with the mode off. It is off by default; the configuration file switches it on with "rugnux": {"enable": true, "reserved_cpus": 4}, where reserved_cpus is the number of CPU threads left to the receiver and the image pusher.

For a rotation collection, rugnux reads the images back from the broker’s image buffer, so the buffer must hold the whole collection - one slot per image. Where it holds fewer, the collection gets the per-image analysis of the mode off (spots, indexing, scan result); the live status reports it as skipped and the collection’s statistics carry a warning saying how many images the buffer holds against how many the collection has.

The results - the merged data, the map coefficients and, with a model, the placed model and its refinement - travel to the writer in the end message, which writes them beside the master file as <file_prefix>.mtz, <file_prefix>_maps.mtz, <file_prefix>_model.cif and <file_prefix>_model.pdb, and <file_prefix>_refined_model.cif (and .pdb), <file_prefix>_refined_maps.mtz and <file_prefix>_blobs.json, as rugnux names them, and the results report <file_prefix>_report.txt - the report rugnux writes for its runs. These files name both programs as the software that made them: the MTZ files in a HISTORY record beside Rugnux’s, the models in their _software loop (Rugnux, and Jungfraujoch for the data collection). An end message that would be too large for the pushers’ buffer (256 MiB) goes without them, with an error in the log and a warning in the live status; the collection itself is not affected.

The same settings are read with GET /config/rugnux and changed with PUT /config/rugnux. A model for molecular replacement and validation (PDB or mmCIF, optionally gzipped, at most 64 MiB) is uploaded as the raw file with PUT /config/rugnux/model (application/octet-stream; a larger body gets 413, an empty one or one that cannot be read as a model 400). The broker parses it at upload and keeps it in memory - nothing is written to disk - for every following collection until DELETE /config/rugnux/model removes it or another upload replaces it; a broker restart drops it. GET /config/rugnux reports whether a model is loaded and its size, never its contents. Changes are refused during a collection. Like the rest of the configuration these routes need no bearer token: they prepare the next collection and expose nothing of the current one.

Two more settings correspond to rugnux’s options, both off by default and turned off again by POST /initialize, as enable and the model are. refine_solvent (rugnux --refine-solvent) has the refinement of a placed model build the solvent as well: waters added at difference-map peaks and removed where the maps no longer hold them, waters and ions relabelled; model.refinement in /rugnux/status then carries waters_added and waters_removed. force_still (rugnux --force-still) sends a rotation collection from a DECTRIS detector the serial way: pre-pass, GPU analysis and stills merge (see Serial collections). The analysis takes the frames without the goniometer; the master file keeps it. It does not change the FPGA workflow.

The end message, and with it the end of the collection, waits for the analysis. deadline_s (default 60 s; 0 for no cutoff) bounds that wait: this long after the last image the analysis is cut. POST /cancel is the other way to cut it: while images still arrive it cancels the collection as with the mode off, and the analysis with it - the live status then ends with verdict CANCELLED and the images that came before the cancel; after the last image it ends only the analysis. A cut analysis gives what it has established: a pass that is past its images still merges and makes its outputs, the canonical pass cut among its images merges those it has read, only the placed model is left out, and any other pass cut short gives way to the last one that ran to its end. The end message goes out at once with that, and the live status records the cut (deadline or cancel) and when.

Where the uploaded model is placed, it is refined as rugnux refines it, after every decision of the run and before the end message - seconds on a GPU, minutes on a broker without one. A cut before it starts leaves it out, as the model; a cut while it runs cuts it short with what its finished weight trials found (model.refinement.cancelled). The refined model and its maps stay with the broker: the writer writes the placed model, as without refinement. GET /rugnux/status gives the refined R-work and R-free, the bond and angle rmsd, the time it took and the unexplained blobs of the refined difference map (model.refinement), and /rugnux/model.cif and /rugnux/map.ccp4 serve the refined model and its maps (stage=placed for the model as placed; the anomalous map is always on the placed model’s phases).

GET /rugnux/status reports the live run of the last collection, kept until the next one starts or POST /rugnux/clear (the “Clear” button of the “Rugnux live” page) puts it back to Idle, as before any collection - refused during a collection; the images and the collection’s plots are kept. It gives the state, the images received, the step it is on and how far into it, the steps so far with what each found, and once it is over the verdict, the summary, warnings and the time from the last image to every result written. shells carries the merging statistics by resolution shell - the rows of the shell table of <file_prefix>_report.txt, on the same shells: multiplicity, ⟨I/σ⟩, completeness, CC1/2, R_meas (rotation), R_split (serial), CCref (with reference data) and the R-free of the placed model as given (with a model), each absent where the run does not measure it - and shells_merge the merge they are of. A rotation run fills them when it is over; a serial one at each provisional merge and at the end, the R-free once the model step on that same merge has its result. A rotation run also leaves frame_scales, the per-image scale factor of the merge, and frame_ranges, the stretches of the sweep the merge downgraded or rejected (the report’s SWEEP section) with the reason it saw there - which frames rugnux left out, and why. The web frontend shows it on the dashboard and in its “Rugnux live” tab, which plots the shells against resolution and the collection image by image, changes the settings and uploads the model. It, /rugnux/model.cif and /rugnux/map.ccp4 need the dataset’s bearer token like the dataset routes (/statistics/data_collection, /image_buffer/*, /preview/plot*). GET /result/scan carries the rotation lattice, unit cell and Bravais symbol rugnux found. A collection in which rugnux finds no lattice still gets the spot count, resolution estimate and background of every image in GET /result/scan and the master file, marked as not indexed.

triage is the pathology checklist of the SUMMARY of <file_prefix>_report.txt, built from the same result, so the two always agree: one entry per condition the report lists (twinning, pseudo-symmetry, multiple lattices, ice and powder rings, anisotropy, completeness, sweep gaps, supercell, overloads, …), plus one for every other warning that fired (e.g. SCALING_NOT_CONVERGED). Each has the report’s label and words, the PATHOLOGY_FLAGS codes it stands for and the warnings behind it, and a severity: ok - looked for and not found; attention - its warning fired; serious - nothing usable came out (no lattice, or a merge without signal: the report’s verdict FAILED or UNUSABLE); not_measured - not looked for on this run. A rotation run fills it when it is over; a serial one at each provisional merge and at the end, each merge analysed for twinning, pseudo-translation and anisotropy as rugnux analyses its final merge, with the indexing ambiguity’s resolution (where the cell and space group admit one) as a row of its own. The serial merge has no pre-scan, so on serial data the powder, ice and multiple-lattice conditions are not_measured. The “Rugnux live” tab lists the conditions that fired first, in orange or red, then the green ones, with the report’s warnings on hover, and names the unmeasured ones in one line.

Serial collections (experimental)

Live processing of serial collections is experimental. With rugnux live mode on, a serial (non-rotation) collection from a DECTRIS detector, in the standard detector mode, is analysed frame by frame: the frames as the stream delivers them go to GPU spot finding, indexing and integration, with rugnux’s stills spot finder (adaptive threshold, single-pixel spots kept). Before any frame is analysed, the first 500 frames are run through rugnux, in memory, as rugnux --no-merge would run on them. That pre-pass decides the beam centre, refines the detector distance (where the dataset settings give a unit cell) and masks the beam-stop shadow and defective pixels; every frame of the collection is then analysed with that geometry and mask. The start message waits for the pre-pass, so it states them, and the end message carries the centre and distance used (refined_beam_center_x/y, refined_detector_distance_mm, CBOR). The broker’s own distance is taken as the beamline’s: unlike offline rugnux, the pre-pass does not search the whole distance range. It refines the centre and distance for a detector square to the beam, as the frames are then analysed. At a serial hit rate the distance needs the 500 frames to be refined at all: on fewer, too few index for the geometry refinement to run, and the stated distance is kept. The pre-pass holds and fits on at most half the slots of the image buffer (a slot is the size of an uncompressed frame), so a smaller buffer starts it on as many as that.

Where a unit cell is given and those frames are too few for the geometry fit (200 indexed frames), frames go on being held and the pre-pass runs again on all of them each time they have doubled, until the fit has its frames, half the image buffer or 2000 frames are held, or the collection ends; frames arriving during a run do not make the next one larger than that, so the last run stays short. The analysis starts when the pre-pass ends and catches up from the frames waiting, so it starts later on a low hit rate.

The geometry is fixed when the pre-pass ends and does not change during the collection, so every frame is analysed and merged at it and the radial profile has one binning throughout. Where the pre-pass could not refine it (too few of its frames indexed, as with a small image buffer, a low hit rate or a chip whose first frames are empty, or no unit cell given), the distance in the header is used for the whole run: this is a warning in the log and a note of the live status, and a wrong header distance then costs resolution and indexed frames.

Frames arriving during the pre-pass, or faster than the analysis, wait in the image buffer, in all its slots but one per analysis thread, kept for sending; a frame that finds it full is dropped and counted as for a full image buffer, so analysis slower than the frame rate costs frames, not memory. Where the writer lags behind, the analysis waits for slots to come back. A pre-pass that fails leaves the stated geometry and mask in use. Where the start message cannot be sent after the pre-pass (no writer listening) or the analysis cannot be set up, the collection ends with that error, reported by /status and /wait_till_done, and the next /start runs as usual.

The indexed frames are also merged, as rugnux --mode scale merges stills, in memory - in the consensus cell of the frames indexed by the first merge (the cell of the dataset settings only picks the frames that are merged) and the space group of the dataset settings (else P1). At half and at three quarters of the images the frames so far are merged beside the analysis, on 8 threads, and the result is reported as a provisional step note: crystals, resolution, CC1/2, R_split, completeness and ⟨I/σ⟩. The first of these merges scales and post-refines every crystal so far and decides the indexing ambiguity from the data; every crystal after it is placed in its indexing, scaled and post-refined against the latest of them as it arrives. After the last frame only the error model, the merge, the resolution cut and the statistics are left to do, on every thread - a few seconds for a chip of 160,000 frames on the full JUNGFRAU 8M, against about half a minute for the same merge made from nothing. The merged data travel to the writer in the end message, as for rotation (<file_prefix>.mtz), and the run’s step “Merge” carries the final statistics.

With an uploaded model, the model step runs on every one of these merges, as rugnux --mode scale --model places a model and rugnux --mode refine refines it: the model is placed by its rigid body where it fits the data as given - its indexing ambiguity probed by R-free, and the merge put in the model’s indexing - and by molecular replacement where it does not (or is a prediction); the 2mFo-DFc and mFo-DFc maps are made, and the placed model is refined, with the blobs of its difference map. Without a space group in the dataset settings the frames are merged in the model’s own, where the model’s cell is the consensus cell of the run on the same axes; otherwise the model is left out, with a warning in the live status saying why. The step on a provisional merge runs on a thread of its own, on 8 CPU threads and the GPU, beside the analysis and the merge, which do not wait for it: its result - the placed and the refined model, their maps, the scores - goes to the live status (model, /rugnux/model.cif, /rugnux/map.ccp4) as soon as it is made, so the density can be looked at while the collection goes on. A step still running when the next merge is made is cut (a refinement cut short keeps the weight trials it finished), and each step starts from the placement of the one before: the merge is put in the same indexing, and the model goes in where it was placed, with no null, indexing probe or search made again. After the last frame the step on the merge of the collection runs on every thread, and the end message waits for it until deadline_s after the last image; then it is cut as for rotation - the refinement first (cut short, or left out where it has not started), and a molecular replacement that has not started. The end message carries the merge in the model’s indexing (<file_prefix>.mtz), the map coefficients, the placed and the refined model, the refined maps and the blobs, written as for rotation; one that would not fit the pushers’ buffer goes without them. The GPU memory the analysis’s indexers hold for the broker’s life is counted against the card when the model step decides what goes on it. POST /cancel cuts it the same way, at any time (cut in /rugnux/status): the frames that came are still analysed and merged.

The frames wait in the image buffer compressed, and go on to the writer byte for byte, with their analysis. efficiency is the images received over the images expected; a stream has no module packets, so per-image collection efficiency, ADU histograms and pulse IDs are absent. The dark frames of the mask sequence stay outside this mode.

GET /rugnux/status reports such a run as three steps (pre-pass, GPU analysis, merge; with a model, the steps of the model on the merge of the collection after them) and a stills block: the pre-pass state and duration, the stated and decided beam centre and distance, the pixels masked, and the images analysed and indexed with the analysis rate. The “Rugnux live” page of the web frontend shows the same. tools/jfjoch_stills_gpu_replay replays a stored serial collection through the same analysis.

In the FPGA workflow (JUNGFRAU), a serial collection with rugnux live mode on is analysed by the receiver of the card (JFJochReceiverFPGA) with the pre-pass, the GPU analysis and the live merge described above, with three differences: the converted frames wait for the analysis in at most half of the image buffer’s slots, a frame that finds them taken is dropped, and there is no model step - an uploaded model is not placed or refined on these merges. The end message carries the merged data, as for a DECTRIS stream.

Setting up a local test for Jungfraujoch

For development, it is possible to set up a local installation of Jungfraujoch. This will work without FPGA installed in the computer and allows testing the Jungfraujoch software layer, including ZeroMQ streaming and file writing.

The workflow simulates FPGA behavior, by running high-level synthesis code on the CPU - the performance is therefore very low, as fixed-point calculations have a large performance penalty on the CPU. In the CPU simulation mode, one can simulate using only a single FPGA device.

To run the test:

Compile Jungfraujoch with frontend

mkdir build
+cd build
+cmake ..
+make jfjoch_broker
+make frontend
+

Alternatively, on a RHEL8 system, you can use the RPMs generated by the automated pipeline. The jfjoch package alone is enough. In this case - it is necessary to update etc/broker_local.json file with frontend path in /usr/share/jfjoch/frontend.

Start service

Start broker (the HTTP port is optional; the default is 5232, listening on all interfaces):

cd build/broker
+./jfjoch_broker ../../etc/broker_local.json 5232
+

Run tests

To run the test, a Python script is provided:

cd tests/test_data
+python jfjoch_broker_test.py
+

The script will initialize Jungfraujoch, import test image and start data collection.

Expected result

You can observe online data analysis by opening the following web page: http://localhost:5232. Also, a dataset with images should be written in the build/broker directory.

\ No newline at end of file diff --git a/JFJOCH_VIEWER.html b/JFJOCH_VIEWER.html new file mode 100644 index 000000000..1561b19a9 --- /dev/null +++ b/JFJOCH_VIEWER.html @@ -0,0 +1,9 @@ + jfjoch_viewer — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

jfjoch_viewer

jfjoch_viewer is the interactive desktop application of Jungfraujoch. It opens diffraction datasets, displays each image together with the analysis overlay (spots, predictions, azimuthal integration, per-image statistics), and can follow a live data collection by syncing with a running jfjoch_broker over its HTTP interface.

It is a standalone Qt 6 application, distributed pre-built for Linux, Windows and macOS on the download page, and for Linux also in the Jungfraujoch RPM/APT repositories — see Release contents for what each package contains and what it requires, and Deployment for how to install it. The macOS build needs macOS 13 (Ventura) or newer on an Apple Silicon Mac (M1 and newer; Intel Macs are not supported) and has no CUDA — see Release contents ▸ macOS.

Where it fits among the three analysis tools

Tool

Mode

Driven by

Output

jfjoch_broker

Online, real-time streaming analysis on FPGA + GPU

HTTP/REST + ZeroMQ

Live results and statistics, images streamed to jfjoch_writer

jfjoch_viewer

Interactive, on-screen exploration

Qt desktop application

On screen; a processing job can write the same files as rugnux

rugnux

Offline batch processing of a stored dataset

Command-line interface

.mtz/.cif/.hkl and the results report when merging (the default); _process.h5 with --no-merge or --write-process-h5

Functionality

  • Opens HDF5 files written by jfjoch_writer (*_master.h5) and the *_process.h5 files produced by rugnux. It also opens NXmx files written by DECTRIS detectors, though that path has had only limited testing.

  • Opens PILATUS miniCBF, marCCD and SMV rotation sweeps (the formats listed under Input formats). These store one frame per file, so naming any frame opens the whole sweep it belongs to. A raw frame carries the images and the geometry but no analysis results, so the spot, reflection and per-image plot panels stay empty until something is computed. A processing job on such a sweep writes the images into its _process.h5, and its run is shown from that file like a run of an HDF5 dataset; Original goes back to the sweep.

  • Runs an embedded data-processing pipeline — the same analysis code as the rest of Jungfraujoch — performing spot finding, indexing and integration on the displayed image, with the result drawn over it. This interactive analysis is not written anywhere.

  • Runs full processing jobs on the open dataset with Analyze dataset, on the same rugnux engine and off the GUI thread. The settings panel’s MX / AzInt / Calib toggle decides what a run does — full analysis, azimuthal integration only, or a detector calibration — over a chosen image range, optionally writing _process.h5 and the merged .mtz/.cif. A finished run becomes a selectable view of the dataset, so several processing runs can be compared against each other, and its merging statistics (or, for a calibration, its fitted geometry) open in their own window; the Processing panel lists the runs and reopens those results. The equivalent rugnux command line can also be copied out to run the same job on a cluster instead.

  • Detector calibration against a powder standard, on the Calib page: pick the calibrant (LaB6, AgBh, CeO2, Si, ice, or the open dataset’s own unit cell) and fit either the image on screen (Guess / Refine detector calibration) or the whole dataset (Analyze dataset, which writes a pyFAI <output prefix>.poni). The whole-dataset fit measures the rings either from the azimuthally-binned profile summed over the run (Rings, the default) or from the pooled spot lists (Spots), and reports PONI x/y, the two tilts and the distance against the header values. Judge it by the radial rms, not the beam-centre sigma: the sigma shrinks with the number of ring points, so a fit that sits a couple of pixels off every ring can still report a small one. Rings needs the run to be integrated in azimuthal sectors — with the AzInt page’s Azimuthal bins below 4 the calibration run raises it to 32, as rugnux --mode calibration does, and says so. Refine detector tilt is ticked by default and fits the two tilts along with the centre and the distance; unticking it holds them where they are, for a calibration meant for a program that cannot express a tilted detector (rugnux --no-refine-tilt). It applies to both buttons and to Analyze dataset.

  • Settings panel for the geometry, unit cell, spot finding, indexing, azimuthal integration, Bragg integration, scaling, powder calibration and a reference dataset — the same settings the CLI takes.

  • Auxiliary windows: image list, dataset metadata, spot list, reflection list, 2D azimuthal-integration image and calibration-image viewer; plus the Inspector (per-image statistics, image features, resolution rings, ROI statistics), the Magnifier below it (three zoom levels: ×64 and ×32 with the pixel values written on the pixels, ×10 without; Pop out moves it to a window of its own) and dataset-info charts.

  • The Inspector’s Image features section decides what the overlay draws — spots, predictions, saturated and highest pixels, the beam stop — including whether the non-indexed spots and the spots that fall on an ice ring are drawn at all.

  • User-mask editing: build a user mask interactively, load one from TIFF (replacing or adding to the current one), save it as TIFF, clear it, or upload it to a connected server.

  • Mouse-driven navigation of the image, the grid scan and the plots — see Mouse shortcuts below, which the viewer also shows under Help ▸ Mouse Shortcuts.

  • Help shows the mouse shortcuts, the acknowledgements and the third-party licenses.

  • Layout presets (View ▸ Image layout / Processing layout / Reset layout) rearrange the docks for looking at images or at processing results.

  • View ▸ Theme picks the light or the dark colour scheme, or Follow system. Following the system needs a desktop that tells Qt its scheme: macOS and Windows do, and so do GNOME and KDE sessions on Linux (elsewhere, QT_QPA_PLATFORMTHEME=xdgdesktopportal reaches the portal setting); a session Qt cannot read - a bare X server, ssh -X - counts as light. The choice is remembered across restarts, and the half-sun toolbar button toggles light and dark directly.

  • View ▸ Font size (or Ctrl++ / Ctrl+-) enlarges the text to 125 % or 150 %, on top of whatever scaling the desktop already applies, and the choice is remembered across restarts. The viewer also follows the desktop’s own text scaling or display scaling on its own; over ssh -X, where no settings daemon delivers it, launch as QT_SCALE_FACTOR=1.5 jfjoch_viewer instead.

A guided tour

Four views cover most of what the viewer is used for. The screenshots show the lysozyme reference sweep of the in-house test set and a raster scan.

Looking at an image

jfjoch_viewer <file> opens the file and shows its first image; File ▸ Open and the toolbar’s open button do the same, and File ▸ Open HTTP connects to a running jfjoch_broker instead.

The general view: diffraction image, inspector and dataset-info plot

The top toolbars step through the images (slider, first/previous/next/last, Jump and Sum for summing consecutive frames) and set the display (foreground limit, Auto contrast, HDR, colour map, font size, theme). The background limit has a slider of its own, shown from View ▸ Background slider or as soon as B + wheel raises it; Auto sets it back to zero. The image in the middle zooms with the wheel and pans by dragging; hovering shows the pixel position, its value and the resolution on the status bar. The Inspector on the right lists the dataset’s metadata and, once an image has been analysed, its spot count, background, indexing result and resolution estimate; the Magnifier under it follows the cursor while Shift is held. On a window too narrow for both, the inspector (with the magnifier) folds away and comes back when the window is widened again. The Dataset info dock at the bottom plots a per-image quantity over the whole sweep - background here; the combo offers spot counts, indexing results, scale factors and more once they exist - and Shift-hover on it loads the hovered image.

A grid scan

A raster scan opens on its two-dimensional map: each cell is one image, coloured by the metric chosen in the combo (spot count by default for a grid scan), so the crystal shows up as the bright region. Shift-hover or double-click a cell to load that image.

A grid scan on its map, with the spot count per position

The Grid button switches between the map and the per-image line plot; a grid scan remembers its own preferred plot, independently of the one used for rotation data.

Processing settings

The Processing dock on the left (the tab next to Files, or View ▸ Processing layout) holds every setting the analysis takes: geometry and unit cell, the goniometer, spot finding, indexing, Bragg integration, scaling, and the reference dataset (MTZ or structure-factor mmCIF) with an optional atomic model to validate the merged data against. The MX / AzInt / Calib switch selects the kind of analysis and its page.

The panel starts from the defaults of a bare rugnux <file>, which the viewer and the command line share, so an Analyze dataset run with nothing changed processes the data as rugnux would; the one intended difference is that the viewer writes _process.h5. Known unit cell starts unticked when a file is opened, and again when a run’s results are shown: the cell and space group the file or the run carries are filled in but not used until it is ticked (-C/-S), so a run determines the crystal from the data, as rugnux does. The azimuthal-integration settings apply to AzInt jobs only; an MX job integrates its profile (for the ice-ring score and the background estimate) with rugnux --mode mx’s defaults.

The Processing dock with the spot finding, indexing and reference sections open

Analyze image re-analyses the current image with these settings, now and on every change while it stays pressed; the inspector and the image overlays update at once.

Processing results

Analyze dataset runs the whole sweep through the same pipeline as rugnux (a job dialog takes the image range, the thread count and which files to write, and Copy command gives the equivalent command line for a cluster, leaving out -N, --max-spots and --integration-radius where the run left them to rugnux, so that the copy makes the same automatic choices). The Jobs dock follows the run.

A finished job: the jobs table and the merge statistics window

When it finishes, the job’s graph button opens the merge statistics (completeness, CC1/2, I/sigma per resolution shell, and the text report). The window names the space group with its screw axes subscripted and lists the crystal pathologies the report checks, one light each: green where the check was made and did not fire, red where it fired (its warning in the tooltip), grey where the data could not answer it. The dataset-info combo gains the per-image indexing result, mosaicity, integrated reflections and scale factors of that run, plotted next to the original file’s values.

Hardware

As with the rest of Jungfraujoch, serious performance requires an NVIDIA GPU. On systems with a GPU, use the CUDA build (a separate package variant everywhere: RPM/APT repository, .tgz and Windows installer) for the embedded indexing and integration; the non-CUDA build runs the same pipeline on the CPU at much lower throughput. The CUDA build also runs on a machine without a GPU — see Release contents ▸ CUDA and non-CUDA builds.

The CUDA build needs an NVIDIA driver on the host but no CUDA toolkit — 525.60.13 or newer for the CUDA 12 artefacts (RHEL 8 packages, portable Linux .tgz), 580.65.06 or newer on Linux and an R580 driver on Windows for the CUDA 13 ones (RHEL 9, Ubuntu, Windows installer). The Windows installer and the .tgz are CUDA 13 and CUDA 12 respectively, which also decides the oldest GPU they run on — a V100 needs the CUDA 12 .tgz. See Release contents ▸ GPU generations and the NVIDIA driver.

On a Mac there is no CUDA: the viewer runs the same pipeline on the CPU, with the FFTW indexer, like the non-CUDA build elsewhere, except Bragg integration, the model density and the molecular-replacement rotation function, which run on the Apple GPU through Metal.

Remote displays

The viewer detects a remote display session (ssh -X and the like) and limits how often panning, zooming and live playback repaint, since on such a link every repaint is shipped as pixels. The detection can be overridden in View ▸ Remote display mode or with JFJOCH_VIEWER_REMOTE=0/1. A VNC- or xpra-based remote desktop still transports the viewer far more efficiently than plain X11 forwarding.

Mouse shortcuts

The same list is available in the application under Help ▸ Mouse Shortcuts.

On macOS, Ctrl below means the Command key (⌘); right click is also Ctrl-click, and on a keyboard without them Home / End are Fn+← / Fn+→ and Page Up / Page Down are Fn+↑ / Fn+↓. The Mouse Shortcuts window shows the Mac keys directly.

Diffraction image

Action

Effect

Wheel

Zoom in / out, centred on the cursor

Shift + wheel

Move the foreground (upper contrast limit) in linear steps

Ctrl + wheel

Move the foreground in multiplicative steps (×1.15 per notch)

F held + wheel

Same as Shift + wheel, for as long as F is held

B held + wheel

Move the background (lower contrast limit) in linear steps, for as long as B is held; shows the background slider

A

Apply auto-contrast once (background back to zero); press it again to switch on continuous Auto

Home / End

Jump to the first / last image in the dataset

Page Up / Page Down

Step one image forward / back

Hover

Status bar shows the pixel position, its value and the resolution

Drag

Pan the image

Shift + move

Move the magnifier panel to the cursor; a frame shows the area it covers

Shift + drag

Draw a rectangular ROI

Shift + Ctrl + drag

Draw a circular ROI

Drag an ROI or its handle

Move or resize the selected ROI

Right click

Copy / save the image, fit to view, clear the ROI

Grid scan

Action

Effect

Hover

Status bar shows the image number, the grid position and its value

Shift + hover

Load the image under the cursor while moving over the grid

Double click

Load the image under the cursor

Other views

Action

Effect

2D azimuthal image: double click

Zoom the diffraction image on the corresponding detector position

Dataset-info plot: hover

Status bar shows the image number and the plotted value

Dataset-info plot: Shift + hover

Load the hovered image

Spot / reflection list: double click

Zoom the diffraction image on that spot or prediction

Image list: double click

Load that image

Opening data

  • File ▸ Open (Ctrl+O) — open a local HDF5 file, or any frame of a miniCBF, marCCD or SMV sweep.

  • File ▸ Open HTTP (Ctrl+H) — connect to a jfjoch_broker HTTP endpoint to follow a live collection. The dialog defaults to host localhost and port 8080; these defaults can be overridden with the environment variables JUNGFRAUJOCH_HTTP_HOST and JUNGFRAUJOCH_HTTP_PORT. The scheme box selects http:// or https:// (the latter for a broker behind a TLS proxy), and the Token field takes the dataset’s bearer token when the collection was started with one. The token can also come from JUNGFRAUJOCH_HTTP_TOKEN or from D-Bus (below); what is typed in the dialog overrides both, and nothing is stored between sessions. Without a valid token for a protected dataset the viewer shows nothing and says so on the status bar — no dialog, since a dataset changing hands is the normal reason.

  • Command line — jfjoch_viewer <file> opens a file (or an http://host:port URL) on start-up. --dbus <true|false> (-d) enables or disables the D-Bus interface (default: enabled); --help and --version behave as usual.

D-Bus interface

When enabled, the viewer registers the D-Bus interface ch.psi.jfjoch_viewer, so other processes can drive it. D-Bus is Linux only: the Windows and macOS builds have no D-Bus interface, and --dbus has no effect there.

  • LoadFile(filename, image_number=0, summation=1, token="") — open a file (or an http://host:port URL) and display the given image; a non-empty token is the bearer token of a protected broker dataset.

  • LoadImage(image_number, summation=1) — navigate to an image in the already-open dataset.

  • SetHttpToken(token) — set the dataset token without reloading; the next request carries it.

summation sums that many consecutive images before display. A repeated LoadFile call naming the file that is already open is cheap (it just navigates, like LoadImage) rather than reopening it, but a client stepping through images of a dataset it opened itself should still prefer LoadImage — it needs no filename and avoids the file-identity comparison.

Building from source on Windows

jfjoch_viewer is cross-platform: it builds on Windows 11 with MSVC and the full CUDA GPU path, and on macOS (see below). (The rest of Jungfraujoch — broker, receiver, FPGA host — is Linux-only.) A pre-built installer is published with every release, so building from source is only needed to develop or to change the build options. On Windows the build is automatically restricted to the viewer and the libraries it needs (JFJOCH_VIEWER_ONLY is forced on), and the remaining dependencies are fetched and built automatically (the first configure needs network access).

Verified toolchain — the same one the released installer is built with:

  • Windows 11

  • Visual Studio 2026 with the C++ (MSVC) toolset — required; CUDA on Windows builds through MSVC

  • CUDA Toolkit 13.3 (12.8 or newer is required) — for the GPU indexing/integration path

  • Qt 6.11 for MSVC (msvc2022_64), including the Qt Charts module — e.g. C:\Qt\6.11.1\msvc2022_64

  • CMake plus Ninja. The CMake that ships with Visual Studio is the simplest choice and works out of the box — it comes with the C++ workload, so there is nothing extra to install. Any recent standalone CMake (from cmake.org, or the one bundled with Qt in C:\Qt\Tools\CMake_64) works too.

  • Optional: NSIS to build the .exe installer.

Configure and build from an x64 Native Tools Command Prompt for VS 2026 (so cl, nvcc and ninja are on PATH):

cmake -G Ninja -B build-win -DCMAKE_BUILD_TYPE=Release ^
+  -DCMAKE_PREFIX_PATH="C:/Qt/6.11.1/msvc2022_64"
+cmake --build build-win --target jfjoch_viewer
+

Notes:

  • CMAKE_PREFIX_PATH (Qt) is the only required flag. Every other dependency, zlib and Eigen included, is downloaded and built by the configure itself, so nothing else has to be installed.

  • The CUDA toolchain is located automatically from the CUDA_PATH environment variable that the CUDA installer sets (or from nvcc on PATH). Pass -DCMAKE_CUDA_COMPILER=".../bin/nvcc.exe" only if nvcc is installed in a nonstandard location and is not found.

  • For a machine without an NVIDIA GPU, add -DJFJOCH_USE_CUDA=OFF: the viewer then runs the same pipeline on the CPU (FFTW indexer) at lower throughput.

To produce a self-contained installer (bundles the Qt runtime via windeployqt and — on the CUDA build — the cuFFT runtime DLL, so the target host needs neither Qt nor a CUDA toolkit), with NSIS installed:

cd build-win
+cpack
+

The NSIS generator is selected automatically on Windows (no -G needed). What comes out, and how the CUDA and CPU variants are named and told apart, is described in Release contents ▸ Windows installer.

Building from source on macOS

The viewer also builds on macOS, Apple Silicon only and without CUDA; as on Windows, the build is automatically restricted to the viewer and the libraries it needs (JFJOCH_VIEWER_ONLY is forced on) and fetches every other dependency itself. A pre-built disk image is published with every release, so building from source is only needed to develop or to change the build options.

Verified toolchain — the same one the released .dmg is built with:

  • An Apple Silicon Mac; the resulting app needs macOS 13 or newer, whatever the build machine runs

  • Xcode (Apple Clang)

  • Qt 6.11 for macOS, including the Qt Charts module — e.g. ~/Qt/6.11.2/macos from the Qt online installer

  • CMake (e.g. CMake.app from cmake.org, with /Applications/CMake.app/Contents/bin on PATH)

cmake -S . -B build-mac -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$HOME/Qt/6.11.2/macos
+cmake --build build-mac -j$(sysctl -n hw.ncpu) --target jfjoch_viewer
+open build-mac/viewer/jfjoch_viewer.app
+

As on Windows, CMAKE_PREFIX_PATH (Qt) is the only required flag. To produce the disk image — the Qt frameworks and the license notices copied into the app with macdeployqt, packed into jfjoch-viewer-<version>-macos-arm64.dmg — run cpack in the build directory. What comes out is described in Release contents ▸ macOS.

The released image is signed with the project’s Apple Developer ID and notarized by Apple. A build of your own is signed ad hoc, which runs on the machine that built it but is refused by Gatekeeper once downloaded. To sign with a Developer ID from your own keychain, configure with -DJFJOCH_MACOS_SIGNING_IDENTITY=<hash> before cpack, where the hash is the 40 hex digits security find-identity -v -p codesigning prints in front of the certificate’s name, then notarize and staple the image with tools/notarize_macos.sh build-mac/jfjoch-viewer-*.dmg (it needs notarytool credentials stored once on the machine; the script’s header says how).

\ No newline at end of file diff --git a/JFJOCH_WRITER.html b/JFJOCH_WRITER.html new file mode 100644 index 000000000..bb6104f86 --- /dev/null +++ b/JFJOCH_WRITER.html @@ -0,0 +1,71 @@ + jfjoch_writer — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

jfjoch_writer

jfjoch_writer is a NeXus-compliant HDF5 file writer.

Acknowledgements

Thanks to Zdenek Matej (MAX IV) and Felix Engelmann (MAX IV) for testing and multiple improvement suggestions.

Running directory

The writer needs to run in the base directory for writing files - file_prefix is always relative to the writer’s running directory. The writer detects and protects against basic security issues, like file_prefix starting with a slash, or starting with ../, or containing /../.

Usage

Writer needs to be started as a background service, with the following command:

jfjoch_writer {options} <address to connect via ZeroMQ to DCU>
+
+Options:
+-T        | --tcp                      Use raw TCP/IP instead of ZeroMQ
+-j<int>   | --nproc=<int>              Number of forks (only with -T)
+-d<path>  | --root_dir=<path>          Root directory for file writing (-R is a deprecated alias)
+-r<int>   | --zmq_repub_port=<int>     ZeroMQ port for PUSH socket to republish images
+-f<int>   | --zmq_file_port=<int>      ZeroMQ port for PUB socket for notifications on finalized files
+-w<int>   | --rcv_watermark=<int>      Receiving ZeroMQ socket watermark in messages (default = 10)
+-m<int>   | --rcv_ring_mb=<int>        Receive ring buffer in MB; holds images until written and republished (default = 2048)
+-W<int>   | --repub_watermark=<int>    Republish ZeroMQ socket watermark (default = 1000)
+-b<int>   | --rcv_buffer=<int>         Receiving TCP socket buffer in bytes (only with -T; disables autotuning, capped by net.core.rmem_max)
+-v        | --verbose                  Verbose output
+-h                                     This message
+

for example:

jfjoch_writer -d /data tcp://dcu-address:5400 
+

Memory

Every message the writer receives is placed in a ring buffer of a fixed size (-m, default 2048 MB, per writer process - -j 8 is eight rings) and stays there until it has been written to HDF5 and, if republish is on, republished. The ring is the writer’s memory budget for buffered images, and the peak use is printed at the end of every run. Size it as the number of images you can afford to have in flight times their compressed size: at 2048 MB that is some 250-500 JUNGFRAU 4M images but only 50-100 JUNGFRAU 9M images, so a 9M site will want more.

When the ring is full the writer stops reading from the socket and the sender has to wait. How long it is prepared to wait depends on the stream:

  • ZeroMQ. The socket queue fills up to its watermark (-w, a count of messages, kept small for that reason) and the broker’s send blocks for one second. After that the broker drops the image, logs the fact, and sends without waiting for the rest of the run, so every later image that finds the queue full is dropped too. A writer that stalls for longer than its ring covers therefore loses images on ZeroMQ; the ring has to be large enough for the stalls of the filesystem it writes to. (Before the ring the same stall was absorbed by queues of about 1500 messages, whatever their size - a budget nobody had chosen.)

  • TCP/IP. The broker sees the writer’s BUSY heartbeats and waits, giving up only after a minute in which not a single image was written.

Republish holds its own images in the same ring. Because the ring is reclaimed in arrival order, an image kept for a slow republish consumer would hold back everything received after it, so republish may hold at most a quarter of the ring; beyond that images are simply not republished, exactly as when its queue is full. A single message larger than the whole ring - a START or END message of a very long run - is held outside it.

Status and cancellation

When a data collection is finalized, each writer reports its outcome back to jfjoch_broker over the writer notification socket — a ZeroMQ address the broker passes in the START message (writer_notification_socket in the broker configuration) — as a JSON message with the socket number, run name and number, processed image count, throughput, and on failure an error string. That is how the broker learns that a writer could not write. On the TCP/IP image stream, failures additionally come back in-band as negative acknowledgements (see Data streams).

To stop a writer, send it SIGINT, SIGQUIT, SIGTERM or SIGHUP: it closes the HDF5 files it is writing and exits. This is only for the case where the broker was terminated or disconnected — it is not the normal way to end a data collection, which the broker finishes on its own.

Republish

Republish creates a PUSH socket on the writer, where all the messages are republished for further use by a data analysis pipeline. Republish is non-blocking, so if there is no receiver on other end or the sending queue is full - images won’t be republished. In case of START/END messages republishing will attempt sending for 100 ms, but if send times out it won’t be retried.

Republish functionality is optional, if republish port number is omitted this functionality is not enabled. It is available for ZeroMQ input only: with -T the option is refused.

Overwriting files

When jfjoch_writer creates a HDF5 file, it first adds suffix .<random>.tmp. Random value depends on current time-stamp and likely will be different from each file of the particular series. After file is all saved and closed, it is renamed to remove the suffix. By default, renaming won’t happen if this would overwrite existing file. However, this behavior can be changed by setting overwrite parameter to true in the file writer configuration.

When the overwrite conflict is reported

An existing output file is a fatal condition (unless overwrite is true). When it is detected depends on whether the transport between the broker and the writer has a back-channel to report the failure before acquisition starts:

  • Direct HDF5 pusher and TCP writer (back-channel available). The conflict is detected at start: the writer that owns the master file lists the output directory and refuses to start if the master file or any data file the run will write already exists (every writer of a run shares the directory, so one answers for all of them). The direct pusher raises the error in-process; the TCP writer returns a START-failure acknowledgement, and makes the same check earlier still, answering the broker’s PREFLIGHT (see IMAGE_STREAM) before the detector is armed. Either way the broker learns immediately and aborts the data collection before the detector is armed — no images are taken and nothing is written.

  • ZeroMQ writer (no back-channel). The ZeroMQ image stream is fire-and-forget: the writer has no way to tell the broker to stop, and the broker would keep streaming images regardless. The writer therefore does not fail at start. It writes the whole series to the .<random>.tmp files as usual and only fails at the final rename, leaving the .tmp files on disk. This is deliberate: the acquired images are preserved (in .tmp form) rather than being dropped by a writer that aborted mid-stream. Rename the .tmp files by hand, or re-run with overwrite set, to recover them.

Finalized files information

Creates PUB socket to inform about finalized data files. For each closed file, the socket will send a JSON message, with the following structure:

{
+  "filename": <string>: HDF5 data file name (relative to writer root directory),
+  "nimages": <int> number of images in the file (counting from 1!),
+  "file_number": <int> number of file within the acquisition,
+  "sample_name": <string> name of sample,
+  "run_name": <string> name of run,
+  "run_number": <int> number of run,
+  "experiment_group": <string> number of p-group / proposal (optional),
+  "user_data": <any json> user_data,
+  "beam_x_pxl": <float> beam center (X) in pixels,
+  "beam_y_pxl": <float> beam center (Y) in pixels,
+  "detector_distance_m": <float> detector distance in m,
+  "detector_height_pxl": <int> detector size (Y) in pixels,
+  "detector_width_pxl": <int> detector size (X) in pixels,
+  "incident_energy_eV": <float> photon energy of the X-ray beam,
+  "pixel_size_m": <float> pixel size in meter (assuming pixel X == Y),
+  "saturation": <int> this count and higher mean saturation,
+  "space_group_number": <int> space group number (optional),
+  "underload": <int> lowest valid count; anything below it is invalid,
+  "unit_cell": <optional> unit cell dimensions in Angstrom/degree {
+    "a": <float>, "b": <float>, "c": <float>,
+    "alpha": <float>, "beta": <float>, "gamma": <float>
+  },
+}
+

user_data is defined as header_appendix in the /start operation in the jfjoch_broker. Other metadata are also carried over from /start operation.

If the header_appendix is a string with valid JSON meaning, it will be embedded as JSON, otherwise it will be escaped as string. For example header_appendix of {"param1": "test1", "param2": ["test1", "test2"]}, then the example message will look as follows:

{
+  "filename": "dataset_name_data_000001.h5",
+  "nimages": 1000,
+  "file_number": 0,
+  "sample_name": "my_sample",
+  "run_name": "my_run",
+  "run_number": 25,
+  "experiment_group": "p00001",
+  "beam_x_pxl": 1200,
+  "beam_y_pxl": 1500,
+  "detector_distance_m": 0.155,
+  "detector_height_pxl": 2164,
+  "detector_width_pxl": 2068,
+  "incident_energy_eV": 12400.0,
+  "pixel_size_m": 7.5e-05,
+  "saturation": 32766,
+  "space_group_number": 96,
+  "underload": -32767,
+  "unit_cell": {
+    "a": 78.0,
+    "alpha": 90.0,
+    "b": 78.0,
+    "beta": 90.0,
+    "c": 39.0,
+    "gamma": 90.0
+  },
+  "user_data": {
+    "param1": "test1", 
+    "param2": ["test1", "test2"]
+  }
+}
+

Notifications for finalized files are optional, if notification port number is omitted this functionality is not enabled.

HDF5 file structure

Jungfraujoch writes NXmx-compliant HDF5, with substantial derived metadata (spot finding, indexing, integration, azimuthal integration, per-image statistics and timing) stored beyond the NXmx standard. The complete file layout — master vs data files, the three format variants (NXmxLegacy, NXmxVDS, NXmxIntegrated), every NXmx field that is populated and every Jungfraujoch extension — is documented in HDF5 / NeXus data format.

If data collection was configured with a header_appendix containing a key hdf5 whose value is a JSON object of numbers and strings, those entries are written to /entry/user.

Other formats (CBF and TIFF)

Jungfraujoch writes only NXmx HDF5. The CBF and TIFF values remain in the file-format enum for compatibility, but a request to write either format is rejected.

No file option(s)

There are two options to disable writing of files by the writer:

  • Setting file_prefix to empty string - this will disable sending files on ZeroMQ image socket.

  • Setting file format to NoFile - files are streamed over ZeroMQ socket, but jfjoch_writer will not write anything. This can be useful for debugging purposes, or if you only rely on republishing functionality of the jfjoch_writer

\ No newline at end of file diff --git a/JUNGFRAUJOCH.html b/JUNGFRAUJOCH.html new file mode 100644 index 000000000..a47dafdee --- /dev/null +++ b/JUNGFRAUJOCH.html @@ -0,0 +1 @@ + Jungfraujoch: data acquisition — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Jungfraujoch: data acquisition

Jungfraujoch is the data-acquisition and real-time analysis system for the PSI JUNGFRAU and EIGER detectors, and, through their detector control unit, for DECTRIS detectors. It takes the detector’s frames at the full frame rate, builds and analyses the images on the fly, and streams them out for writing, with a web interface and a REST API for the beamline. It is the streaming half of the software; Rugnux is the processing half (see Naming).

What runs where

Program

Role

jfjoch_broker

The central service: configures the detector and the FPGA cards, builds images from their output, runs the real-time analysis (masking, summation, spot finding, azimuthal and ROI integration, indexing on the GPU, compression), streams the images over ZeroMQ or TCP, and serves the HTTP/REST interface and the web frontend.

jfjoch_writer

Receives the image stream and writes NeXus/NXmx HDF5 files; usually on a separate machine with the file system.

FPGA smartNIC

AMD Alveo U55C cards with the Jungfraujoch firmware, one per few JUNGFRAU modules; they receive the detector’s UDP stream and run the first stages of the analysis in hardware. The DECTRIS path has no FPGA: the stream from the detector control unit goes through the same analysis on the CPU and GPU.

Web frontend

The browser interface served by the broker: detector state, live preview, plots of the on-line quality metrics, and the controls, including Rugnux live mode, which processes a rotation sweep while it is being collected.

Python client

pip install jfjoch-client: the REST API as a generated Python package, for beamline control software.

Viewer

Optional: the desktop viewer follows a live collection from the broker over HTTP.

The detectors, firmware and slsDetectorPackage versions the system is built against are in Supported detectors; the server, FPGA, GPU and switch it needs are in Hardware requirements.

Installing

Jungfraujoch runs on Linux servers: RHEL / Rocky 8 and 9 are the supported platforms, Ubuntu 22.04 / 24.04 experimental (Software requirements).

  • Packages. The package repositories carry jfjoch (broker, frontend, FPGA and detector tools), jfjoch-driver-dkms (the PCIe kernel module), jfjoch-writer and jfjoch-viewer, in CUDA and non-CUDA variants and per slsDetectorPackage version. The writer’s .rpm / .deb are also attached to every release, for a file-writing machine without the rest.

  • FPGA firmware. The .mcs images are attached to every release; the card is flashed once with xbflash.qspi and keeps its image across software upgrades.

  • From source. cmake and make from the repository, with every dependency fetched during the first configure; the frontend is built separately with make frontend.

Deployment is the step-by-step guide: packages or source, flashing the cards, the kernel driver, the network switch, the broker’s configuration file and running the services. Release contents says what each package contains and what it needs on the machine.

Reading the output

The broker streams images as CBOR messages compatible with the DECTRIS Stream2 protocol (Data streams, CBOR messages); the writer turns them into NXmx HDF5 (HDF5 / NeXus data format). Which downstream programs read which of the three HDF5 layouts, and the XDS plugin, are in Integration with MX software. The command-line tools shipped beside the services are listed in Tools.

How to cite

The primary citation for Jungfraujoch is F. Leonarski et al., “Jungfraujoch: hardware-accelerated data-acquisition system for kilohertz pixel-array X-ray detectors” (2023), J. Synchrotron Rad. 30, 227-234 doi:10.1107/S1600577522010268. For real-time serial crystallography and live indexing feedback cite also J. Duan et al., “Jungfraujoch: 38 GB s⁻¹ real-time serial crystallography – data acquisition and live indexing feedback” (2026), J. Appl. Cryst. 59, 1668-1677 doi:10.1107/S1600576726008083. The files jfjoch_writer writes from Rugnux live mode name both Jungfraujoch and Rugnux; cite the Rugnux paper too when you use them. All papers are on the Publications page.

\ No newline at end of file diff --git a/LICENSE.html b/LICENSE.html new file mode 100644 index 000000000..e0de28b8d --- /dev/null +++ b/LICENSE.html @@ -0,0 +1,20 @@ + License — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

License

Jungfraujoch software is licensed with GPLv3 license. Jungfraujoch FPGA is licensed with CERN OHL-S license (see FPGA license).

GNU GENERAL PUBLIC LICENSE

Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc. https://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The GNU General Public License is a free, copyleft license for software and other kinds of works.

The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program–to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.

To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.

For the developers’ and authors’ protection, the GPL clearly explains that there is no warranty for this free software. For both users’ and authors’ sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.

Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users’ freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.

Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS

  1. Definitions.

“This License” refers to version 3 of the GNU General Public License.

“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.

“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.

To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.

A “covered work” means either the unmodified Program or a work based on the Program.

To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.

To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.

An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.

  1. Source Code.

The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.

A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.

The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.

The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work’s System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.

The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.

The Corresponding Source for a work in source code form is that same work.

  1. Basic Permissions.

All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.

You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.

Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.

  1. Protecting Users’ Legal Rights From Anti-Circumvention Law.

No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.

When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties’ legal rights to forbid circumvention of technological measures.

  1. Conveying Verbatim Copies.

You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.

You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.

  1. Conveying Modified Source Versions.

You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:

a) The work must carry prominent notices stating that you modified it, and giving a relevant date.

b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.

c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.

d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.

A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.

  1. Conveying Non-Source Forms.

You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:

a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.

b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.

c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.

d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.

e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.

A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.

A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.

“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.

If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).

The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.

Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.

  1. Additional Terms.

“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.

When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.

Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:

a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or

b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or

c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or

d) Limiting the use for publicity purposes of names of licensors or authors of the material; or

e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or

f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.

All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.

If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.

Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.

  1. Termination.

You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).

However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.

  1. Acceptance Not Required for Having Copies.

You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.

  1. Automatic Licensing of Downstream Recipients.

Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.

An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.

You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.

  1. Patents.

A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.

A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.

Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.

In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.

If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient’s use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.

If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.

A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.

Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.

  1. No Surrender of Others’ Freedom.

If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.

  1. Use with the GNU Affero General Public License.

Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.

  1. Revised Versions of this License.

The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.

If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.

Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.

  1. Disclaimer of Warranty.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  1. Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

  1. Interpretation of Sections 15 and 16.

If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

<one line to give the program's name and a brief idea of what it does.>
+Copyright (C) <year>  <name of author>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+

Also add information on how to contact you by electronic and paper mail.

If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:

<program>  Copyright (C) <year>  <name of author>
+This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type `show c' for details.
+

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, your program’s commands might be different; for a GUI interface, you would use an “about box”.

You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see https://www.gnu.org/licenses/.

The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read https://www.gnu.org/licenses/why-not-lgpl.html.

Jungfraujoch exceptions to GPL

Additional permissions under section 7 of the GNU GPL version 3.

The copyright holders of Jungfraujoch grant the following additional permissions. They apply only to code whose copyright the Jungfraujoch copyright holders own; they do not and cannot change the license of third-party code.

  1. NVIDIA CUDA. The NVIDIA CUDA Toolkit libraries (the CUDA runtime, cuFFT and the other libraries distributed with the CUDA Toolkit) are treated as System Libraries for the purposes of this License, so a work linked with them may be conveyed without their Corresponding Source.

  2. FPGA simulation. Jungfraujoch software (GPL-3.0) may be linked with Jungfraujoch high-level synthesis code (CERN-OHL-S-2.0) to simulate the FPGA design on a CPU.

  3. OpenAPI definition. Client code generated from the OpenAPI definition file (jfjoch_api.yaml), or code that uses that file solely to interact with the Jungfraujoch API, may be distributed under terms of your choosing, without being subject to the requirements of the GNU GPL.

\ No newline at end of file diff --git a/NAMING.html b/NAMING.html new file mode 100644 index 000000000..d9f2bc9d3 --- /dev/null +++ b/NAMING.html @@ -0,0 +1 @@ + Naming — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Naming

The software is Swiss, and so are its names: both halves of the system are named after places in the Alps that are, in one way or another, about moving a lot of something up a steep mountain as efficiently as possible — usually by train. Throughput, in other words.

Part

Name

What it does

Streaming / acquisition

Jungfraujoch

Receives detector data at high data rates, runs the FPGA/GPU pipeline, and streams images out for writing.

Data processing

Rugnux

Crystallographic analysis of a stored dataset, or of a collection while it is written — indexing, integration, scaling and merging, and refinement of a given model (the rugnux tool).

Jungfraujoch

The Jungfraujoch is a high mountain col in the Bernese Alps, the saddle (Joch is German for “yoke” or “col”) between the peaks Jungfrau and Mönch, at 3,466 m. It is the site of the High Altitude Research Station Jungfraujoch, whose long-running atmospheric measurements are co-operated by the Paul Scherrer Institute — the same institute that develops this software and the JUNGFRAU detector.

The name is also a small piece of word-play. PSI’s JUNGFRAU detector and DECTRIS’s EIGER detector are both named after Bernese Alps peaks (the famous trio is Eiger, Mönch, Jungfrau). The Jungfraujoch — the pass between Jungfrau and Mönch — is where those two detector worlds meet.

And it fits the theme of the whole project: the Jungfraujoch is reached by the Jungfraubahn, whose terminus is the highest railway station in Europe (3,454 m, the “Top of Europe”). It is the closest you can get to that summit in a genuinely high-throughput way — by train, moving crowds up the mountain — which is exactly what the streaming side of this software does with detector frames.

Pronunciation (German): Jungfraujoch ≈ YUNG-frow-yokh. “Jung” as in young, “frau” rhymes with cow, and the final “joch” ends in the guttural ch of Scottish loch or German Bach — not a hard k.

Rugnux

Piz Rugnux is a mountain in the Rhaetian Alps of canton Graubünden, in south-eastern Switzerland. (Piz is the Romansh word for “peak”.) It rises above the Albula line of the Rhaetian Railway (Rhätische Bahn), part of the “Rhaetian Railway in the Albula / Bernina Landscapes” — a UNESCO World Heritage Site (Welterbe).

That stretch of line is a masterpiece of throughput engineering: to climb a great deal of altitude in very little horizontal distance, it corkscrews through a series of helical (spiral) tunnels looping back inside the mountains. It is, again, the Swiss art of getting an enormous amount up a steep mountain efficiently — the same idea the data-processing side of this software is built around: pushing a large volume of diffraction data through the analysis pipeline.

So the theme is consistent — Swiss mountains, trains, and throughput — while keeping the two subsystems clearly distinct: Jungfraujoch streams, Rugnux processes.

Pronunciation (Romansh): Piz Rugnux ≈ peets roo-NYOOKS. The “gn” is a soft palatal ñ, as in canyon or Italian gnocchi, not two separate sounds.

What is Romansh?

Romansh (Rumantsch) is the fourth national language of Switzerland, alongside German, French and Italian. It is a Romance language — a direct descendant of the spoken Latin left behind in the Alpine valleys — today spoken by only a few tens of thousands of people, almost all in the canton of Graubünden. It survives in several regional idioms, brought together in a standard form called Rumantsch Grischun. Naming the processing engine with a Romansh mountain is a small nod to the least-spoken but no-less-Swiss corner of the country.

\ No newline at end of file diff --git a/OPENAPI.html b/OPENAPI.html new file mode 100644 index 000000000..73047ae8c --- /dev/null +++ b/OPENAPI.html @@ -0,0 +1,2 @@ + OpenAPI — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

OpenAPI

OpenAPI specs

See document with detailed OpenAPI specs. The spec declares one security scheme, bearerAuth, on the endpoints that expose the current dataset; it applies only while the dataset was started with tokens (see Security).

Python client

Jungfraujoch is controlled with HTTP/REST interface defined with an OpenAPI specification. For convenience, we provide a Python client as the jfjoch-client PyPI package. To install the client you can use pip tool:

pip install jfjoch-client
+

See API reference from the OpenAPI generator.

\ No newline at end of file diff --git a/OPENAPI_SPECS.html b/OPENAPI_SPECS.html new file mode 100644 index 000000000..feb346dad --- /dev/null +++ b/OPENAPI_SPECS.html @@ -0,0 +1 @@ + OpenAPI specification — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/PIXEL_MASK.html b/PIXEL_MASK.html new file mode 100644 index 000000000..3802e3443 --- /dev/null +++ b/PIXEL_MASK.html @@ -0,0 +1,13 @@ + Pixel mask — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Pixel mask

Mask format

Jungfraujoch generally follows the NXmx format for the pixel mask. The pixel mask is a 32-bit unsigned integer array of the same size as the image. The conditions for masking a pixel are encoded by setting a particular bit to one. This makes it possible to record the reason why a pixel is included in the mask, and several reasons can be recorded for one pixel at the same time.

Bit values are set as follows:

Bit 0 - gap (pixel with no sensor)

Bit 1 - error pixel (for PSI JUNGFRAU: pixel doesn’t set proper gain during pedestal, for DECTRIS: pixel is part of detector pixel mask)

Bit 4 - noisy pixel (for PSI JUNGFRAU: pixel pedestal G0 RMS is over threshold, for DECTRIS: pixel was flagged with signal during dark data collection at initialization)

Bit 8 - user defined mask

Bit 9 - beam stop shadow (found by rugnux --detect-beam-stop, on by default; see Rugnux). Unlike the other bits this one belongs to the run that found it, not to the dataset: Rugnux clears it at the start of every run, so a mask read back from a file that carries one starts clear. The user mask (bit 8) is left alone.

Bit 10 - defective pixel found on the run’s own frames (rotation data from a counting sensor; see CPU data analysis §1.6): lit above its resolution ring on more frames than one reflection or chance explains, or holding the detector’s error value on most frames.

Bit 11 - outside a CCD’s active area, measured on the run’s own frames (see CPU data analysis §1.6).

Bit 30 - module edge (only for PSI systems)

Bit 31 - chip edge interpolated pixel (multipixel)

Custom user mask

Jungfraujoch allows a custom user mask to be uploaded. This happens in two steps. First create the mask in TIFF format:

import numpy as np
+import tifffile as tiff
+
+# Create an array matching a 2068 x 2164 (width x height) image: 2164 rows, 2068 columns
+array = np.zeros((2164, 2068), dtype=np.uint32)
+
+# Mark the pixel at column 400, row 300 with the value 1
+array[300, 400] = 1
+
+# Save the array as a TIFF file
+tiff.imwrite('mask.tiff', array)
+

Pixels with non-zero value in the TIFF file will be marked as belonging to the user mask (bit 8).

Then upload the mask to Jungfraujoch server:

curl -v http://<jfjoch_broker http address>/config/user_mask.tiff -XPUT --data-binary @mask.tiff
+
\ No newline at end of file diff --git a/PUBLICATIONS.html b/PUBLICATIONS.html new file mode 100644 index 000000000..5431e566e --- /dev/null +++ b/PUBLICATIONS.html @@ -0,0 +1 @@ + Publications — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Publications

How to cite

Rugnux — if you find Rugnux useful, please cite:

F. Leonarski and M. Wang, “Rugnux: from diffraction images to structure at synchrotrons and XFELs in one program” (2026), bioRxiv doi:10.64898/2026.10.24.761522.

Jungfraujoch — the primary citation is:

F. Leonarski, M. Brückner, C. Lopez-Cuenca, A. Mozzanica, H.-C. Stadler, Z. Matěj, A. Castellane, B. Mesnet, J. Wojdyla, B. Schmitt and M. Wang, “Jungfraujoch: hardware-accelerated data-acquisition system for kilohertz pixel-array X-ray detectors” (2023), J. Synchrotron Rad. 30, 227-234 doi:10.1107/S1600577522010268.

Work that relies on real-time serial crystallography, live indexing feedback or the system’s full data rate should also cite:

J. Duan, H.-C. Stadler, J. Nan, Z. Matěj, G. Gotthard, F. Dworkowski, M. Bjelčić, O. Aurelius, A. Mozzanica, S. Grimm, M. Burian, T. Ursby, M. Wang and F. Leonarski, “Jungfraujoch: 38 GB s⁻¹ real-time serial crystallography – data acquisition and live indexing feedback” (2026), J. Appl. Cryst. 59, 1668-1677 doi:10.1107/S1600576726008083.

Data collected with Jungfraujoch and processed with Rugnux in the broker (Rugnux live mode) come out of both programs, and the files jfjoch_writer writes from them name both: please cite both.

Rugnux

  • F. Leonarski and M. Wang, “Rugnux: from diffraction images to structure at synchrotrons and XFELs in one program” (2026), bioRxiv doi:10.64898/2026.10.24.761522.

Jungfraujoch

  • J. Duan, H.-C. Stadler, J. Nan, Z. Matěj, G. Gotthard, F. Dworkowski, M. Bjelčić, O. Aurelius, A. Mozzanica, S. Grimm, M. Burian, T. Ursby, M. Wang and F. Leonarski, “Jungfraujoch: 38 GB s⁻¹ real-time serial crystallography – data acquisition and live indexing feedback” (2026), J. Appl. Cryst. 59, 1668-1677 doi:10.1107/S1600576726008083 — the system at its full data rate, with live indexing feedback during serial data collection.

  • P. Gasparotto, L. Barba, H.-C. Stadler, G. Assmann, H. Mendonça, A. W. Ashton, M. Janousch, F. Leonarski and B. Béjar, “TORO Indexer: a PyTorch-based indexing algorithm for kilohertz serial crystallography” (2024), J. Appl. Cryst. 57, 931-944 doi:10.1107/S1600576724003182 — the GPU indexing algorithm behind Jungfraujoch’s real-time indexing.

  • F. Leonarski, J. Nan, Z. Matěj, Q. Bertrand, A. Furrer, I. Gorgisyan, M. Bjelčić, M. Kepa, H. Glover, V. Hinger, T. Eriksson, A. Cehovin, M. Eguiraun, P. Gasparotto, A. Mozzanica, T. Weinert, A. Gonzalez, J. Standfuss, M. Wang, T. Ursby and F. Dworkowski, “Kilohertz serial crystallography with the JUNGFRAU detector at a fourth-generation synchrotron source” (2023), IUCrJ 10, 729-737 doi:10.1107/S2052252523008618 — serial crystallography at 2 kHz with a JUNGFRAU 4M and Jungfraujoch at the BioMAX beamline of MAX IV.

  • F. Leonarski, M. Brückner, C. Lopez-Cuenca, A. Mozzanica, H.-C. Stadler, Z. Matěj, A. Castellane, B. Mesnet, J. Wojdyla, B. Schmitt and M. Wang, “Jungfraujoch: hardware-accelerated data-acquisition system for kilohertz pixel-array X-ray detectors” (2023), J. Synchrotron Rad. 30, 227-234 doi:10.1107/S1600577522010268 — the primary citation: the FPGA-accelerated acquisition system.

  • F. Leonarski, A. Mozzanica, M. Brückner, C. Lopez-Cuenca, S. Redford, L. Sala, A. Babic, H. Billich, O. Bunk, B. Schmitt and M. Wang, “JUNGFRAU detector for brighter x-ray sources: Solutions for IT and data science challenges in macromolecular crystallography” (2020), Struct. Dyn. 7, 014305 doi:10.1063/1.5143480 — the data handling problem of the JUNGFRAU detector that Jungfraujoch was designed to solve.

\ No newline at end of file diff --git a/PYTHON_CLIENT.html b/PYTHON_CLIENT.html new file mode 100644 index 000000000..0bd1637f2 --- /dev/null +++ b/PYTHON_CLIENT.html @@ -0,0 +1,6 @@ + OpenAPI Python client — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

OpenAPI Python client

The broker’s REST API has a generated Python client, published on PyPI as jfjoch-client and regenerated from broker/jfjoch_api.yaml by update_version.sh — the YAML is the single source of truth (see OpenAPI).

  • Client README — installation, quick start, and the index of every endpoint and model.

  • DefaultApi — the full endpoint reference, with a generated example per call.

A protected dataset (one started with tokens) is read with the token as the client’s bearer credential:

import jfjoch_client
+api = jfjoch_client.DefaultApi(jfjoch_client.ApiClient(
+    jfjoch_client.Configuration(host="http://localhost:5232", access_token="<token>")))
+api.post_start(jfjoch_client.DatasetSettings(..., tokens=["<token>"]))
+api.get_statistics_data_collection()   # sends Authorization: Bearer <token>
+

The per-model pages are generated as well and are linked from the two pages above. They are built with the site but kept out of the navigation sidebar on purpose — sixty generated reference pages would otherwise be most of it.

\ No newline at end of file diff --git a/RELEASE_CONTENTS.html b/RELEASE_CONTENTS.html new file mode 100644 index 000000000..c6c2b6a61 --- /dev/null +++ b/RELEASE_CONTENTS.html @@ -0,0 +1 @@ + Release contents — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

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; for the package-repository URLs see Linux package repositories.

Artefacts

Artefact

Distributed via

Contains

.rpm / .deb packages

package repositories

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, ...-linux-x86_64-cpu.tgz

Gitea release page

Portable Linux rugnux, 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, ...-win64-cpu.zip

Gitea release page

The same for Windows, plus the cuFFT DLL in the CUDA variant

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

jfjoch_xds_plugin-<version>-linux-x86_64.tgz

Gitea release page

XDS HDF5 read plugin (lib/libjfjoch_xds_plugin.so.<n>, built on RHEL 8) and its license notices; see Integration with MX software

jfjoch-client

PyPI and the Gitea PyPI index

Generated Python OpenAPI client

Documentation

Read the Docs 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) 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 build system sets no architecture flags of its own, 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 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 (the FFTW indexer and the CPU fast-feedback 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; Rugnux is tested on a DGX Spark (GB10).

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). 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.

macOS

The macOS artefacts are the jfjoch_viewer disk image and the rugnux .tgz; as on Windows, the rest of Jungfraujoch, including the XDS plugin, is Linux-only. Both are without CUDA — macOS has none, so indexing uses the FFTW indexer and the pipeline runs on the CPU, except Bragg integration, the model density and the molecular-replacement rotation function, which run on the Apple GPU through Metal — 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.

Both artefacts are signed with the project’s Apple Developer ID and notarized by Apple, so a downloaded copy opens like any other Mac application. The disk image carries its notarization ticket; the rugnux binary in the .tgz cannot (a bare executable has nowhere to staple one), so the first run of a freshly downloaded rugnux looks the ticket up online and needs an internet connection.

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.

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.

\ No newline at end of file diff --git a/REPOSITORIES.html b/REPOSITORIES.html new file mode 100644 index 000000000..80330978e --- /dev/null +++ b/REPOSITORIES.html @@ -0,0 +1,5 @@ + Linux package repositories — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Linux package repositories

For convenience, we are providing package repositories, in versions including and excluding CUDA linking. We recommend installing the Jungfraujoch viewer from a nocuda repository (published in the slsdet8 flavour only) and the remaining packages from a cuda12/cuda13 repository.

The repository name encodes two choices: the slsDetectorPackage version the packages were built against (slsdet8 = 8.0.2, slsdet9 = 9.2.0 — it must match the detector firmware) and whether CUDA is linked in. What ends up inside each package, and what it needs on the target machine, is described in Release contents.

RHEL based systems

For RHEL systems we provide the following repositories:

RHEL version

slsDetectorPackage

CUDA

Repository file

8.x

8.0.2

12.x

https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-cuda12.repo

8.x

9.2.0

12.x

https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet9-cuda12.repo

8.x

8.0.2

-

https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-nocuda.repo

9.x

8.0.2

13.x

https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet8-cuda13.repo

9.x

9.2.0

13.x

https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet9-cuda13.repo

9.x

8.0.2

-

https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet8-nocuda.repo

To install the repository, run:

dnf config-manager --add-repo https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-cuda12.repo
+

RPMs are signed by the Gitea package registry as they are uploaded. If your system cannot verify the signature, set gpgcheck=0 in the repository file or install with --nogpgcheck.

We provide the following packages in the repository:

  • jfjoch — broker, web frontend, FPGA and detector command-line tools

  • jfjoch-driver-dkms — PCIe kernel-module source, built by DKMS

  • jfjoch-writer — HDF5 writer service

  • jfjoch-viewer — desktop viewer and the XDS plugin

  • Rugnux — offline analysis CLI, independent of the acquisition stack

Note that rugnux is named without the jfjoch- prefix, matching the program and the release archive.

Ubuntu based systems

For Ubuntu systems, we also provide the following repositories:

sudo curl https://gitea.psi.ch/api/packages/mx/debian/repository.key -o /etc/apt/keyrings/gitea-mx.asc
+echo "deb [signed-by=/etc/apt/keyrings/gitea-mx.asc] https://gitea.psi.ch/api/packages/mx/debian $distribution $component" | sudo tee -a /etc/apt/sources.list.d/gitea.list
+sudo apt update
+

$distribution uses Ubuntu names jammy (22.04) and noble (24.04). $component can be set to either cuda13 or nocuda. Only slsDetectorPackage 8.0.2 is built for Ubuntu.

The same five packages as above are provided: jfjoch, jfjoch-driver-dkms, jfjoch-writer, jfjoch-viewer and rugnux.

Ubuntu packages currently undergo only very limited testing.

\ No newline at end of file diff --git a/RUGNUX.html b/RUGNUX.html new file mode 100644 index 000000000..56c62ce9d --- /dev/null +++ b/RUGNUX.html @@ -0,0 +1,61 @@ + Rugnux — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Rugnux

rugnux is the offline crystallographic data-analysis tool of Jungfraujoch — the data-processing half of the system (see Naming for where the name comes from). It takes a stored dataset from the diffraction images to merged data — spot finding, indexing, geometry refinement, Bragg integration, scaling and merging, written as .mtz/.cif/.hkl with the unmerged MTZ and the results report — and, with an atomic model, on to a refined structure and maps: the model is placed against the merge, refined, and written with its map coefficients and the difference-density blobs it leaves unexplained. The per-image _process.h5 is written only on request (--write-process-h5), or as the only output with --no-merge. A rotation run that finds no lattice still spot-finds every image and writes their per-image analysis there, then exits as failed.

It runs the same analysis code as the online and interactive tools, driven from the command line over files.

rugnux {<options>} <input.h5> {<input.h5>} [<broker URL>]
+

Run it with no arguments to print the usage.

Several Jungfraujoch/NXmx masters of stills, given one after another, are read as one run: their images are taken in the order given, indexed and merged together, and the log gives the indexing rate of each input beside the run’s. They must be one setup - the same detector, wavelength, distance and beam centre (to 0.1%, 0.1 mm and 1 pixel), since stills geometry refinement refines one geometry for all frames - and a pixel masked in any of them is masked for all. Stills in the other formats are given the same way, as all their files: rugnux run*.h5 (SACLA), rugnux *.cxi, rugnux *.xtc. Inputs are always files, read in the order given (a shell glob gives them sorted by name); a directory is refused. Rotation sweeps are not read together.

Given the URL of a jfjoch_broker (http://host:port/) and the path the master file will have, rugnux follows the broker’s current collection while it is being written: the data files are read as the broker reports them closed, processing starts on the first images, and the run ends with the images the collection delivered. A decision made early on a near tie is re-checked on all frames once the collection is complete. If the check gives a different answer, the run is repeated, so the result is that of the whole sweep. This is for rotation data and --mode mx; the collection’s token is read from JUNGFRAUJOCH_HTTP_TOKEN and sent only to the broker. With the master file already on disk, the URL is ignored.

Note. rugnux is under very active development. This page describes the tool and its options at a high level. Run rugnux with no arguments for its usage - how to run each mode and the basic options; every option is on Command-line options.

Quick start

Rugnux is one executable in an archive on the release page, https://gitea.psi.ch/mx/jungfraujoch/releases. On Linux x86-64 (the other platforms are on Download):

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
+

To process a dataset, give rugnux an output prefix and the dataset: its master file (HDF5), or any one image of a CBF, marCCD, SMV or SFRM sequence. The example is the 9ZLO dataset (10.8 GB, 19 files, CC-BY 4.0 on Zenodo): Proteus mirabilis UreE, 3600 EIGER images collected at the Australian Synchrotron.

mkdir -p demo/9zlo && cd demo
+for f in ASP0887_09_0114_master.h5 ASP0887_09_0114_data_0000{01..18}.h5; do curl -L -C - -o 9zlo/$f "https://zenodo.org/records/18652652/files/$f?download=1"; done
+rugnux -o 9zlo 9zlo/ASP0887_09_0114_master.h5
+

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 16-core CPU and an NVIDIA RTX 5080 the run takes 17 s with release 1.0.0-rc.183 (minutes with --no-gpu). 9zlo_report.txt then says: space group P 21 21 21, cell 38.363 89.746 106.871 90 90 90, resolution 68.7-1.57 A, completeness 99.7 %, multiplicity 12.7, R_meas 0.120, CC1/2 0.9994, I/sigma 11.6, ISa 23.6. A second run, another GPU or the CPU repeats the space group, the cell to 0.1 % and the resolution to one shell. The last digit of a statistic can differ.

With a model, the run goes on to place and refine it. The AlphaFold prediction of UreE is in this repository under tools/battery/models/, two files; the PAE file is read when it sits beside the model:

curl -L -O https://gitea.psi.ch/mx/jungfraujoch/raw/branch/main/tools/battery/models/AF-P17090-F1-model_v6.cif
+curl -L -O https://gitea.psi.ch/mx/jungfraujoch/raw/branch/main/tools/battery/models/AF-P17090-F1-predicted_aligned_error_v6.json
+rugnux -o 9zlo --model AF-P17090-F1-model_v6.cif 9zlo/ASP0887_09_0114_master.h5
+

Molecular replacement places the two copies (MR_DECISION= AGREES), refinement brings them to R-work / R-free 0.271 / 0.297 (the refined R factors can differ in the second decimal between builds), and 9zlo_refined_model.cif and 9zlo_refined_maps.mtz are written beside the merged data; the run takes 22 s. The paper’s times do not include the refinement; a current run’s do. Every file the run writes is listed under Output files and in A first run in detail; the other example datasets are in the repository’s top-level README.

The remaining options are for unusual data and for diagnosis. They are all listed under Command-line options. If a dataset only processes well with one of them, please report it and send the run’s _report.txt and _log.txt.

Rotation data

rugnux -o myrun dataset_master.h5          # NXmx / EIGER / Jungfraujoch master file
+rugnux -o myrun sweep_00001.cbf            # a CBF, marCCD or SMV sweep: name one of its frames
+

Serial stills

rugnux -o serial *_master.h5               # several NXmx masters of one setup, read as one run
+rugnux -o serial run*.h5                   # all the files of one dataset (SACLA); *.cxi, *.xtc alike
+

Inputs are always files, never a directory; a shell glob hands them over sorted by name, and they are read in that order and merged together. Without a cell the stills are indexed de novo.

Serial stills with a known cell, space group and a CrystFEL geometry file

rugnux -o serial -C 79,79,38,90,90,90 -S P43212 --crystfel-geometry detector.geom run*.h5
+

-C is the cell (a,b,c,alpha,beta,gamma), -S the space group as a symbol (P43212) or a number (96). With -S the run puts every crystal on one indexing where the space group admits two, from the data alone. --crystfel-geometry places the panels (and takes the masks it names) for HDF5/CXI input that does not place them itself. The wavelength and the detector distance come from the data files or the geometry file; only where neither states them add --wavelength <A> and --detector-distance <mm> (the distance is then held, not refined — without it a run with -C searches and refines it).

With a model

rugnux -o myrun dataset_master.h5 model.cif     # model and images in any order;
+rugnux -o myrun --model model.pdb dataset_master.h5   # or with --model
+

A model is told from the images by its contents (PDB, or mmCIF with atoms), gzipped or not. After merging it is placed — as a rigid body, or by molecular replacement where that does not place it or the model is a prediction (AlphaFold, ModelCIF) — then refined against the merge (restrained, maximum likelihood; seconds on a GPU, typically minutes on the CPU; --no-refine skips it) with its solvent as given; --refine-solvent (off by default, also with --mode refine) also rebuilds the solvent - waters added at difference peaks and removed from negative density, ions relabelled where their surroundings say so, each site audited - and the run writes the maps (σA-weighted 2mFo−DFc / mFo−DFc), the placed and refined model, and the blobs of difference density the model does not explain. R-work / R-free are in the report.

The model does not change the processing: the intensities, the cell and the resolution are the ones the data give without it. What it can change is the space group the files are labelled with: it names the hand of an enantiomorphic pair, which merged intensities cannot tell apart (see below). A different space group the molecular replacement prefers is never taken into the answer; it is written beside it as <prefix>_mr.mtz. The one further change is on serial stills with -C and -S in a space group that admits two indexings: there the model picks which of them the crystals are put on, so the merge comes out in the model’s indexing. Without a model the data resolve the ambiguity themselves, consistently but in an arbitrary one of the two. A reference reflection file (-z reference.mtz, also accepted as a positional input) does the same, and steers the processing from the start (see Models and reference data).

Output files

A rotation run that merges — the default — leaves these files next to each other:

myrun.mtz            merged intensities + French-Wilson amplitudes, for CCP4 / phenix
+myrun.cif            the same, as mmCIF - the self-describing format, and what to deposit
+myrun.hkl            the scaled observations unmerged, as SHELX HKLF 4 - for SHELXL, SHELXC / ANODE
+myrun.ins            the SHELX instructions to go with it: CELL, ZERR (the cell's e.s.d.s), LATT, SYMM
+myrun_unmerged.mtz   the observations unmerged, scaled by the merge, for pointless / aimless -
+                     the largest file of the run (--no-export-unmerged skips it)
+myrun_report.txt     what the run determined: cell, space group, statistics, warnings
+myrun_plot.txt       one row per image, for plotting how the crystal behaved over the sweep
+myrun_detector.jpg   the detector with the pixel mask and the beam-stop shadow drawn on it
+myrun_log.txt        the full timestamped log of the run (debug level)
+

With a model, beside them:

myrun_maps.mtz            map coefficients on the placed model (Coot and PyMOL open it as maps)
+myrun_model.cif / .pdb    the model as placed, in the cell and space group of myrun.mtz
+myrun_refined_model.cif   the refined model (and .pdb)
+myrun_refined_maps.mtz    map coefficients on the refined model
+myrun_blobs.json          the unexplained difference-density blobs
+myrun_solvent.json        with --refine-solvent: the refined model's waters and ions, each scored by its surroundings, and the waters the build added and removed
+

A stills run writes the same merged files (its .hkl holds the merged reflections) and, on a detector of several modules, serial_module_placement.json with where each module was placed (and serial_modules.h5 where the refinement moved some). Output files lists every file a run can write.

A run uses all the machine’s threads by default. -N limits the thread count, or raises the per-image loop’s default ceiling of 16 workers per GPU.

Read myrun_report.txt first: it says which space group was chosen and on what evidence, how far the data go, and anything that needs attention.

Terminal output

The terminal shows the run as numbered steps, each with one-line results and the time it took, the warnings among them, and a summary at the end; everything else goes to myrun_log.txt. A note’s time is how long the step ran since the line above it, and the rule under a step gives its total, so the steps add up to the wall time. Abridged:

Step 3  Indexing
+        ... beam centre kept: measured 7.5 px off, same lattice         1.36 s
+        ... lattice triclinic P: 28.56 35.34 63.56 106.0 90.3 90.3      0.00 s
+        ... 52/60 validation frames, 24% of their spots on it           0.00 s
+        ------------------------------------------------------- done in 1.36 s
+Step 4  Integration (geometry pre-pass), 1800 images
+        ... 1800 images, 836 per second                                 2.15 s
+        ------------------------------------------------------- done in 2.16 s
+   ...
+Step 9  Scaling and merging
+        ... merge in P1: 14464 unique                                   0.64 s
+        ... space group P 1 21 1 (No. 4)                                0.05 s
+        ... merge in P21: 16847 unique                                  0.26 s
+        ... resolution 1.57 A (CC1/2 fall-off at 1.64 A)                0.02 s
+        ------------------------------------------------------- done in 1.89 s
+   ...
+==============================================================================
+ Result        WARNINGS: Merged to 1.57 A in P 1 21 1. 3 conditions need
+               attention: SCALING_NOT_CONVERGED, MULTIPLE_LATTICES, ICE_RINGS.
+ Space group   P 1 21 1
+ Unit cell     35.337 28.465 62.937 90.000 105.824 90.000
+ Resolution    1.57 A written; the CC1/2 fall-off is fitted at 1.64 A
+ Signal        I/sigma 6.0   R_meas 17.2 %   CC1/2 0.995   ISa 10.2
+ Wall time     11.78 s
+==============================================================================
+ With any question about this run, send myrun_report.txt and myrun_log.txt.
+

On a terminal an integration pass draws a progress bar in place; written to a file or a pipe (a batch job’s log) every line starts with the time of day instead, there is no bar, and a long pass says how far it has got once a quarter. Warnings are marked !! and errors ** ERROR:; a warning that comes back from a later merge is shown once more on one line and then only counted. -v puts the whole log on the terminal in place of the steps. The log file carries what is needed to answer a question about a run without the data: version, build, GPU, threads, the command line, the header geometry, every decision with its numbers, and a timestamp on every line.

Notes on the defaults:

  • The reflection files are cut at the resolution where CC1/2 drops below 0.30. Every reflection file is resolution-trimmed automatically (--resolution-cutoff cc-logistic, one shell past the crossing); --resolution-cutoff off keeps the full measured range, --scaling-high-resolution fixes the limit by hand. If a Rugnux file reaches lower resolution than another program’s on the same data, this cutoff is usually the reason, not missing data.

  • Do not give -C or -S for rotation data. A known cell and space group are useful for serial data, where the ffbidx indexer needs a cell. On rotation data they often make low-symmetry cases worse. Let the cell and space group be determined from the data (see Rotation data). -S takes a Hermann-Mauguin symbol (P43212) or a space-group number (96), whichever is to hand.

  • -A is not needed for the anomalous signal. A rotation merge always keeps the Bijvoet split: a default run’s .mtz carries I(+)/I(-) beside IMEAN, its .hkl every observation at the index it was measured at, and the report gives SIGANO, CC_ANOM and the ANOM_* table (the same merge counted per hand, as an anomalous XDS run counts) on every run. On rotation data -A changes nothing in the processing, the files or the statistics; every decision is taken with Friedel mates merged, -A or not, and the report then only says FRIEDELS_LAW= FALSE. Serial stills are different: their merge keeps no split by default, and there -A is what creates one, merging each Bijvoet hand as a reflection of its own.

  • A model names the enantiomorph. Where the data accept the model — it is tested against a null of the same model in random orientations, and MODEL_FIT= in the report says the verdict — --model settles which of P41212 and P43212 the merged reflections are labelled with — a choice no merged intensity can make. It is a label and nothing more: the two groups have the same rotation operations, so no reflection moves, and in particular I(+) and I(-) are left exactly as measured. Whether the model agrees with the data about the hand is then a real question, and the anomalous difference map answers it — a run says so when the density at the model’s atoms comes out inverted.

  • -z and --model overlap but are not the same. A reference MTZ steers the processing from the start; a model scores the merge and settles the frame it is written in — where the data accept it; a model they reject changes nothing. Either resolves an indexing ambiguity in its own indexing. On serial data the ambiguity decides whether the merged intensities are usable at all; there the space group (-S) alone already lets the run make the crystals consistent from the data.

  • Small-molecule data need no extra options. Short axes, spots wider than the integration disk and glide-plane space groups are handled by default. myrun.hkl can be given directly to SHELXT / SHELXL (Small-molecule data).

  • --scaling-high-resolution <d>, where the resolution is already known, sharpens both the space-group search and the error model.

  • A run wants memory in proportion to what it integrates, not to the detector: up to about 14 GB of host RAM and 7 GB on the card for an ordinary sweep, both peaking in scaling and merging. Installing Rugnux ▸ Memory has the table and the two flags that lower it. A very large cell needs far more, and a CPU-only build most of all — tens of GB of host RAM (Very large unit cells).

  • When a run fails it exits non-zero and says why on the terminal; VERDICT= and the WARNING: lines of the report say what needs attention on a run that finished (The results report). A rotation run that indexes nothing most often has a wrong header: the beam centre is measured on every run, but the distance and the wavelength are indexed at the values stated — --detector-distance and --wavelength override them (--beam-x/--beam-y the centre); serial stills that index poorly want the cell (-C). A run that ends with Killed ran out of memory (Out of host memory). With any question about a run, send myrun_report.txt and myrun_log.txt.

  • Everything else is in Running Rugnux and the full Command-line options.

Manual pages

The manual is split into one page per topic:

  • Overview — the pipeline from images to merged data and, with a model, a refined structure, in order. Read this one first.

  • Download Rugnux — the archive for Linux, macOS and Windows, and the three commands that run it.

  • Installing Rugnux — packages, the release archive, GPU drivers, building from source, hardware.

  • Input formats — will it open your data: NXmx / EIGER masters, PILATUS miniCBF, marCCD and SMV (ADSC, Rigaku d*TREK) sweeps, one sweep per input, and serial XFEL stills from SACLA (Cheetah HDF5), Cheetah CXI single-panel files and LCLS-I XTC.

  • Running Rugnux — a first run in detail, rotation, serial and small-molecule data, and every file a run writes.

  • Rugnux with other programs — the reflection-file conventions, the unmerged export, and worked command lines for phenix, REFMAC, POINTLESS / AIMLESS, careless, Phaser, SHELXC/D/E and, for small molecules, SHELXT / SHELXL.

  • The results report — the KEY= value interface, sweep quality and the anisotropy section.

  • Command-line options — how to run each mode, and every option with what it does.

  • Advanced usage — reference data and the indexing ambiguity, model validation and re-merging.

  • Models and reference data — every model and reference option, and decision by decision what a model can and cannot change.

  • Detector calibration — the geometry from a calibrant’s powder rings (--mode calibration).

  • Measuring Rugnux — the validation battery, the REFMAC check, the timing benchmark, and how to take timings on another machine that compare with ours.

  • CPU/GPU data analysis — the algorithms behind all of it.

The three analysis tools

Tool

Mode

Driven by

Output

jfjoch_broker

Online, real-time streaming analysis on FPGA + GPU

HTTP/REST + ZeroMQ

Live results and statistics, images streamed to jfjoch_writer

jfjoch_viewer

Interactive, on-screen exploration

Qt desktop application

On screen; a processing job can write the same files as rugnux

rugnux

Offline batch processing of a stored dataset

Command-line interface

.mtz/.cif/.hkl and the report; _process.h5 with --no-merge or --write-process-h5

Use rugnux to re-analyse data after acquisition, to experiment with processing parameters, or to produce merged intensities for downstream structure solution.

How to cite

If you find Rugnux useful, please cite F. Leonarski and M. Wang, “Rugnux: from diffraction images to structure at synchrotrons and XFELs in one program” (2026), bioRxiv doi:10.64898/2026.10.24.761522. Rugnux prints this at startup and at the head of its report; the other papers are on the Publications page.

\ No newline at end of file diff --git a/RUGNUX_ADVANCED.html b/RUGNUX_ADVANCED.html new file mode 100644 index 000000000..f4ae88592 --- /dev/null +++ b/RUGNUX_ADVANCED.html @@ -0,0 +1,6 @@ + Advanced Rugnux — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Advanced Rugnux

The machinery behind a run that needs more than the defaults: external reference data, model validation and re-merging without re-integration; the option tables are on Command-line options.

Reference data and the indexing ambiguity

Reference data (-z)

-z reference.mtz supplies known intensities of the same crystal form — a previously merged dataset, or F-model amplitudes computed from a structure. The reference can equally be a PDB structure-factor file (-z 1abc-sf.cif, SF-mmCIF), gzipped or not; the format is taken from the file’s content. From an mmCIF the first merged reflection block with a usable column is read (the log names it), its columns under the MTZ labels gemmi cif2mtz gives them (IMEAN, FP, FC, …), and its R-free set from _refln.status (f free, o working), or from _refln.pdbx_r_free_flag where the status marks no test set. It is read once, before processing starts, and used for five things:

  • It fixes the space group and the unit cell the run works in, unless -S / -C override them. The cell is a soft reference: indexing may still drift within tolerance, so a small mismatch between reference and data is absorbed rather than rejected.

  • It fixes the axes the files are written on. The group is taken in the setting the reference is written in (P 2 21 21 stays P 2 21 21, not only “number 18”), and once the run has merged, every description of its lattice on the reference’s axes - axis permutations, sign flips, I- against C-centred - and every alternative indexing on top is correlated with the reference; the best one is re-merged and written. REFERENCE_OPERATOR= names the operator (h,k,l where the data were already on the reference’s axes), REFERENCE_CC= and REFERENCE_MATCHED_FRACTION= how well the result matches.

  • It resolves the indexing ambiguity (below) — the one thing the data cannot settle for themselves: which of the equivalent indexings is the reference’s own.

  • It hands over its R-free test set, where the file carries one, so every dataset of a campaign is scored on the same free reflections - in the reference’s frame, and only where the merge matches the reference (CC at least 0.5 over at least half of the merged reflections in its resolution range). A reference that does not is reported (REFERENCE_MISMATCH), and the merge keeps its own test set; REFERENCE_FREE_FLAGS_INHERITED= says which happened.

  • It reports CCref, the correlation of the merged intensities against the reference, in the statistics table. Stills only — the rotation merge never scores itself against the reference, and its table shows - in that column.

A reference is not a scale anchor. Both workflows scale against their own data — scaling images against a foreign dataset injects that dataset’s systematics — so -z never puts the reference’s errors into the intensities. --reference-column picks the column to read where the automatic choice (F-model, else IMEAN/I, else FP/FOBS/F) is not the right one.

An atomic model does not take part in the processing: --model is placed and validated after the merge, and a run with one merges exactly what a run without one does. A model that fits then sets the frame the merge is written in - the hand label, the setting and the indexing (see Validating against a model) - by relabelling it, never by re-merging.

The indexing ambiguity

Some crystals can be indexed in more than one way, each equally valid geometrically, and each giving different merged intensities. This happens whenever the lattice is more symmetric than the crystal: in P3, P4, P6, P31, C2 and their relatives (merohedral), and also where the cell is metrically more symmetric than the Laue class by accident (pseudo-merohedral, up to 2° of obliquity). The alternatives are related by the crystal’s twin laws — reindexing operators such as k,h,-l.

Nothing in the data says which solution is the true one: the merge is equally self-consistent either way, so which comes out is arbitrary. What that costs depends on the workflow:

  • Rotation. The whole sweep is one lattice, so the whole dataset lands in one indexing, picked at random. The merge itself is sound; it may simply be the other solution from an earlier dataset of the same crystal form, and the two cannot be combined, compared or phased against the same model.

  • Serial stills. Every crystal is indexed independently, so a run mixes both indexings into one merge. That is not a labelling matter — reflections that are not symmetry mates get averaged together, and CC1/2, Rmeas and the anomalous signal all degrade. The data can say which crystals are in the same indexing, though, and that is what a merge needs: with the space group given (-S) and no reference, Rugnux puts each crystal into the indexing in which it agrees best with all the others, before anything is scaled. This takes seconds for tens of thousands of crystals, and the report says how clearly the crystals separated (AMBIGUITY_SEPARATION_SIGMA=, AMBIGUITY_DECIDED_FRACTION=) and how many were moved (AMBIGUITY_REINDEXED=). The indexing the whole merge ends up in is still arbitrary against other data sets, exactly as on rotation data. On a pseudo-merohedral cell each crystal’s own refined cell also says something about which axis is which, as far as the run’s axes differ by more than one crystal’s cell scatters; it is weighed beside the intensities, crystal by crystal, and decides where they cannot.

Every run that merges tests for the ambiguity, and where it exists and nothing resolves it (serial stills whose space group was determined by the run rather than given), says so in the log and in the report’s warnings:

Indexing ambiguity: this cell / space group admits alternative indexing (reindex operator(s):
+-h,-k,l). Serial-stills crystals are indexed in one hand at random, and rugnux makes them consistent
+from the data only where the space group is given: here it was determined by the run, so the merge
+mixes the hands and CC1/2 is degraded. Giving the space group (-S) resolves it from the data; a
+reference MTZ (-z) or a model (--model, which needs -S here) resolves it against them.
+

Where something does resolve it, the run says so instead — Indexing ambiguity present (reindex operator(s): -h,-k,l); resolved against the supplied reference or ...; resolved from the data.

How to resolve it:

Situation

What to do

Rotation, a reference dataset exists

-z reference.mtz. Once the space group is settled, each candidate reindexing of the merged intensities is correlated with the reference and the best-correlating one is re-merged. Only the hkl labels change; the cell does not

Serial stills, a reference dataset exists

-z reference.mtz. The crystals are made consistent with each other as in the rows below, and the reference fixes the indexing the merge is written in. A crystal is decided by its agreement with all the others and its own cell rather than by the reference, which reads a weak crystal less clearly than the merge of all the others does: AMBIGUITY_DATA_DISAGREES= counts the crystals put elsewhere than the reference alone would

Rotation, only a model

--model model.pdb. The merged data are fitted to the model in each candidate indexing and the lowest R-free wins — provided the model first beats its random-orientation null (MODEL_FIT= ACCEPTED) and its lead over the runner-up beats the lead a random placement of the same model takes; the written reflections are then reindexed into it, so the file, the R-factors and the maps agree. Where either bar is missed the data keep the indexing they were merged in, and the report says by how much (MODEL_INDEXING_MARGIN_SIGMA). It is the data that are relabelled, never the model: every dataset of one crystal form processed against the same model comes out in that model’s indexing, so the reflection files and maps of a screening campaign compare directly. The relabelling is a proper rotation of the lattice, so the merging statistics are unchanged and I(+)/I(-) keep their hand

Serial stills, only a model, space group given (-S)

The crystals are made consistent with each other from the data alone, as in the row below - the model plays no part in the processing. Validation then fits the merge to the model in each candidate indexing, as for rotation data, and relabels the written reflections into the model’s indexing where it wins

Serial stills, neither, space group given (-S)

Nothing to do: the crystals are made consistent with each other from the data alone (INDEXING_AMBIGUITY_RESOLVED= data), in an indexing that is arbitrary against other data sets. A reference still settles the weakest crystals more reliably than the other crystals can, and puts the merge in its own indexing

Neither

The run warns and merges in whichever indexing it found: for rotation data a usable dataset in an arbitrary frame; for stills whose space group the run determined, a merge of mixed indexings, which looks like a perfect twin and can pass for higher symmetry than the crystal has. Run again with -S

Two things to know about where the choice lands:

  • --mode scale resolves it as the full run does. On stills with no reference MTZ it makes the crystals consistent from the data alone before merging; with -z the reference fixes the indexing of the whole, as in a full run with the reference - so one reference puts several runs, or both arms of a pump-probe run, in the same indexing. On rotation data, where the ambiguity is one choice for the whole dataset, --mode scale --model model.pdb does resolve it.

  • The choice reaches the written reflections, not only the R-factors and the maps: the merged .mtz / .cif / .hkl (and _unmerged.mtz, where it is asked for) are written in the indexing the model or the reference settled on, so the file can be refined against that model as it stands.

Two things the indexing ambiguity is not:

  • Not the enantiomorph. P41212 versus P43212 (or P31 versus P32) leaves the merged intensities unchanged, so no amount of data can choose between them and Rugnux never tries — the run reports the pair it cannot separate. A model the data accept names it (MODEL_FIT= ACCEPTED in the report), and the naming is a label only: the written reflections take the model’s space group, no reflection moves, and I(+)/I(-) stay exactly as measured — reindexing by the change of hand would flip every anomalous difference, so it is never done. Whether the model and the data really agree about the hand is answered afterwards by the anomalous difference map, which warns when the density at the model’s atoms comes out inverted. The _process.h5, whose per-image reflections were written as they were integrated, keeps the group the run determined and is left alone.

  • Not twinning. The twin laws are the same operators, but twinning is a property of the crystal — two orientations diffracting at once — and is reported separately in the report’s twinning section. A crystal can have an indexing ambiguity without being twinned, and usually is not.

The algorithms behind both are in CPU/GPU data analysis ▸ Reference data.

The setting the files are written in

The space-group search decides which axes carry the screws and the centring on the cell as it was indexed, whose axes are ordered by length. The files are then written in the standard setting, as XDS and POINTLESS write it (SETTING_SOURCE=STANDARD): P2221 and P21212 with the unique axis on c and a<b; the other orthorhombic groups a<=b<=c; C222 and C2221 with a<b; monoclinic b-unique, C-centred (never I2), least oblique with beta >= 90; triclinic keeps the reduced cell. So a crystal indexed as 52.51 87.87 137.72 in P 2 21 21 is written as 87.87 137.72 52.51 in P 21 21 2.

What the user gives takes precedence, in this order: a reference MTZ (-z, its own setting), a model that fits (--model, its setting), the axis order of a cell given with -C (SETTING_SOURCE=CELL), and the setting of a group given with -S by a non-standard symbol (-S "P 2 21 21", SETTING_SOURCE=SPACE_GROUP). A group given with -S is also placed on the axes its absences name before anything is merged, so -S 18 on a cell whose pure two-fold is its shortest axis puts the screws on the right rows.

The change is a relabelling made after every decision - nothing measured, and no decision, depends on it - and it is applied to everything the run writes: the merged .mtz/.cif/.hkl, _unmerged.mtz and the _process.h5 (whose per-image reflections carry the reindex matrix). SETTING_OPERATOR= gives it as a reindexing operator on the indices the space group was determined on, CCP4 style (k,l,h is h’=k, k’=l, l’=h); h,k,l where nothing moved.

Validating against a model (rugnux --model)

Which decisions a model can influence, and which it cannot, is set out decision by decision in Models and reference data.

Given an atomic model of the same structure, --model model.pdb scales the model structure factors to the merged amplitudes — fitting a flat bulk-solvent contribution and an overall anisotropic B — and reports R-work / R-free and the mean 2mFo−DFc density at the atom centres. Where the model is placed it also writes the map-coefficient MTZ <prefix>_maps.mtz next to the merged reflections (a model placed nowhere, MODEL_PLACEMENT=NOT_PLACED, gets no model or maps files): the σA-weighted 2mFo−DFc and mFo−DFc coefficients, which Coot and PyMOL open directly as maps. As phenix.refine and BUSTER write theirs, the coefficients have the data’s overall anisotropy divided out and the 2mFo−DFc map FWT/PHWT is filled with DFc at the reflections the data do not have; FWT_no_fill/PHWT_no_fill is the same map without them, and the difference map DELFWT/PHDELWT is never filled. Where the merge kept the Bijvoet split (a rotation merge always does), an anomalous difference map is made too, its coefficients in the same MTZ (ANOM/PHANOM): the report names its strongest sites (ANOMALOUS_SITE_01…10), the map’s mean height at the model’s anomalous scatterers - every atom from phosphorus up - as one number for the anomalous signal (ANOMALOUS_SCATTERER_MEAN_SIGMA), and the map’s peaks of 5 σ or more that no such atom of the model sits on (ANOMALOUS_UNEXPLAINED_PEAK_01…): an ion or a heavy atom the model leaves out, with its position and the model’s nearest atom. The model is not refined for these numbers (a placed model is refined afterwards, on the side - see Refinement); it is re-fractionalized into the data cell and then placed as one rigid body, so a deposited model from a crystal that is not quite isomorphous still sits where the density is. The placement runs on the GPU where there is one and on the CPU otherwise, with nothing to set; the two agree to rounding, not bit for bit.

The rigid body only moves a model that already sits near its place, so its placement is checked: the model counts as placed where its fit beats the same model refitted from random orientations (the null behind MODEL_FIT, below), in the answer’s merge or in the twin hypothesis’ one. An experimental model the rigid body does not place — a deposited structure of another crystal form, a model of a subgroup the data were merged above, a file with no crystal cell — is then searched for by molecular replacement: as many copies as the cell holds, in every space group the merge cannot tell apart and in the twin hypothesis’ subgroup (the search and its keys are in Molecular replacement). A predicted model — AlphaFold or ModelCIF, recognised from the file’s content (pLDDT in the B column) — has no placement of its own and goes to molecular replacement straight away, trimmed to the residues of pLDDT 70 and above and, where the AlphaFold DB’s predicted-aligned-error JSON sits beside it under its own name, cut into rigid domains. --mr <file> is --model with the rigid body skipped: molecular replacement straight away, whatever the model. The report says which way the model was placed, MODEL_PLACEMENT= RIGID_BODY, MR or NOT_PLACED; a model placed nowhere is a result, not a warning, and the reflection files are then what a run without a model writes. Where molecular replacement placed it, the R-factors, the maps and the placed model below are those of its placement. Molecular replacement is part of the full --mode mx run, rotation and serial stills alike; --mode scale (below) places the model by the rigid body alone.

A placed model changes two things in <prefix>.mtz/.cif/.hkl and nothing else: the enantiomorph label and, placed by the rigid body, the indexing ambiguity (molecular replacement relabels the hand, past the same anomalous check, and never reindexes). Where the model chooses another space group with the answer’s rotations, or the twin hypothesis’ subgroup, the answer’s files stay the run’s own and that merge is written beside them as <prefix>_mr.mtz/.cif — from the merge it was chosen on, with the twin law and fraction where it is the subgroup — together with the model as placed there, <prefix>_mr_model.pdb/.cif; the report names them (MODEL_CHOICE_FILE_PREFIX=, MODEL_CHOICE_SPACE_GROUP=).

Because the model moves, the input file no longer describes these maps, so the model as placed is written as <prefix>_model.cif — the input’s chains, residues, ligands, waters, B-factors, occupancies and anisotropic Us, at the coordinates the maps were computed from, in the same unit cell and space group as <prefix>.mtz beside it. The same coordinates are written as <prefix>_model.pdb as well, because the fragment-screening tools this file exists to feed take a PDB: PanDDA’s per-dataset input is <name>.pdb beside <name>.mtz, and dimple produces that same pair. (The PDB is skipped, with a log line, for a cell its fixed-width format cannot hold; the mmCIF is unconditional.) That is the file to open with the maps, and the one to hand to REFMAC5 or phenix.refine; its starting R-free is the R_FREE= the report quotes. Rugnux’s own refinement of it is written beside it as <prefix>_refined_model.cif with <prefix>_refined_maps.mtz (Refinement). (<prefix>.cif is the merged reflections — hence the separate name.)

Where the run also wrote a twin hypothesis — <prefix>_twin_<SG>.mtz/.cif, the same data merged in a subgroup with a twin law, written when the adopted space group may have absorbed one (see the twin hypothesis) — the model is scored against that merge as well, plainly and as twinned by the law, and the maps and <prefix>_model.cif come from whichever of the two merges the model fits better on R-free. The report says which (MAPS_FROM=) and gives the R-free of both. <prefix>.mtz and the space group are the run’s own either way; where the model also fits that merge against its null, it has chosen the subgroup, and the merge is written once more as <prefix>_mr.mtz/.cif (above). The maps and the model are written only for a model that was placed (MODEL_PLACEMENT= RIGID_BODY or MR): one the data rejected and molecular replacement did not place is no model of this crystal, and its coordinates and maps would read as a placement. Its R-factors stay in the report as the negative result.

The model may be PDB or mmCIF, gzipped or not, and the format is taken from the file’s own content rather than from its name — a model downloaded as .cif, .pdb, .ent or with no useful extension at all is read the same way. A model that cannot be read, or that has no atoms, no unit cell or no usable space group, does not fail the run: it is logged, and the results report carries a WARNING: Model validation did not run: … line, so a run that silently produced no R-free and no maps cannot be mistaken for one that was never given --model.

Either way the results report carries a 5. MODEL VALIDATION section: R_WORK= / R_FREE= with their reflection counts, R_MODEL_SHELL_SCALED= and MODEL_RADIAL_MISFIT= beside them (the R that compares between two runs, and why the other two do not — see RUGNUX_REPORT), the bulk-solvent and overall scale parameters, the mean 2mFo−DFc density at the atom centres, the reindexing operators the written reflections were brought into the model’s frame with, and MAPS_PREFIX=; or MODEL_VALIDATION= NOT_PERFORMED with MODEL_VALIDATION_REASON= when the model could not be used. A run given no --model has no such section at all.

It is a data-quality lens, independent of the internal statistics: R-free measures the merged intensities against external truth, where CC1/2 and Rmeas only measure them against themselves. It also settles the two things merged intensities alone cannot, in two different ways — though only where the data accept the model first: the same model is refitted, and re-placed, from random orientations about its own centroid, and the real fit has to beat that null (MODEL_FIT= in the report; §14.5). A model that fits no better than its own random placements decides nothing, and the reflection files are byte for byte what a run with no model would have written. The enantiomorph is a relabelling: data merged in P41212 against a P43212 model take the model’s space group as the label they are written under, with no reflection moved and I(+)/I(-) exactly as measured. A merohedral indexing ambiguity — when no reference MTZ has already fixed it — is a reindexing: the candidate with the lowest R-free is kept — where its lead over the runner-up beats the lead a random placement of the same model takes — and applied to the written reflections as well as to the R-factors and the maps; otherwise the data keep the indexing they were merged in. This is distinct from a model written in another description of the lattice — other axes, a different unique axis, I-centred where the run indexed C-centred — or in another point group: there the model is first put into the data’s description (MODEL_CHANGE_OF_BASIS=) to be scored. A model that asserts such a setting is then tested against its random placements like any other claim, and where it fits, the data move instead: the files are written in the model’s setting (SETTING_SOURCE=MODEL), and the validation is made once more on those axes so the maps and _model.pdb match them. Where it does not fit, the files stay in the standard setting. Validation runs before the reflection files, so the .mtz / .cif / .hkl come out in the model’s frame either way — reindexed where the ambiguity decided, and carrying the model’s space group where the hand was adopted. The log names the operator in each case, and for the indexing choice gives the winning R-free together with the runner-up.

Re-scaling and re-merging (rugnux --mode scale)

The scale mode re-scales and merges the already-integrated reflections stored in a _process.h5 file, without re-running spot finding or integration. Use it to re-merge quickly with a different space group, resolution limit, anomalous setting or outlier rejection. It reuses the same -o/-N/-s/-e/-S/-A/-z/--scaling-* options as the full run, and (unlike the full pipeline) does not run a space-group search: it merges in the space group and unit cell the file records, and -S / -C override them. A _process.h5 written before the group was stored carries none, and merges in P1 unless -S says otherwise.

A reference MTZ (-z) is accepted here on stills data, where it fixes the space group and cell, reports CCref and hands over its R-free flags; on rotation data the rotation scaler declines it and the run stops with a message saying so. --model works here as in a full run, except that the model is placed by the rigid body only: a model it does not place, or a prediction, is not searched for by molecular replacement, --mr is refused, and the placed model is not refined. On rotation data, where the indexing ambiguity is one choice for the whole dataset, it can settle the enantiomorph label and the indexing — under the same fit test as always — and the re-merged reflections are written in what it settled. On stills the re-merge is the full run’s own merge: the same frames (a given cell’s population, as /entry/MX/stillsGivenUnitCell records it), the same rocking curve, the same data-only resolution of the indexing ambiguity and the same scaling, so a _process.h5 merged again with the options it was written with reproduces the full run’s reflections (with a reference MTZ, the full run also lets the crystals’ own cells overrule the reference’s indexing before merging, which --mode scale does not).

Where the full run re-seated the lattice — the space group it settled on is in a different setting from the one each image was indexed in — the file records the change of basis as /entry/MX/reindexMatrix, and rugnux applies it on read, so the reflections and the stored cell describe the same frame. A file whose stored cell and reflections disagree stops with a message naming both cells and the exact -S/-C override to merge it in its own setting.

The merged mmCIF (<prefix>.cif)

The .cif follows the PDBx/mmCIF dictionary and holds one data block, data_sample: the merged reflections (_refln: I, F and the Bijvoet mates, with the free set in _refln.status) and what describes them - the cell and space group; _software with Rugnux named twice, once for data reduction and once for data scaling; the experiment as the input file states it (_diffrn.ambient_temp from the sample temperature, the wavelength, the source’s facility and beamline and its general class, the detector’s make and model in _diffrn_detector.type and its class in _diffrn_detector.detector, and the collection date from the NXmx start time); and the merging statistics overall (_reflns) and per shell (_reflns_shell): completeness, multiplicity, <I/σ(I)>, R_merge, R_meas, R_pim (? on a stills merge, where they mean nothing), CC1/2 and CC*, and SigAno where an anomalous split was made; on rotation data the cell carries its e.s.d.s (_cell.length_a_esd, …). A quantity the input does not state is left out rather than guessed. The unmerged observations are in the _unmerged.mtz and the .hkl (both scaled on a rotation merge), not in the .cif.

Items PDBx does not define — ISa, the error model, the twinning and anisotropy diagnostics, the refined distance and beam centre — are written under the jfjoch_ local prefix, which a dictionary check reports as unknown and a deposition ignores.

Provenance

Every reflection file says where it came from, so that it can be traced back without the report beside it:

  • the .cif names the Rugnux version in _software.version and the commit it was built from in _software.description, and the command line, the input file (absolute path) and the input’s identity under _jfjoch_provenance.command_line, .input_file and .input_identity;

  • the .mtz and the _unmerged.mtz carry the same in their HISTORY records (mtzdump prints them), each run on over further records where it is longer than the 80 characters of one.

The identity is the input file’s size and modification time — for an HDF5 data set, the master file’s — which tells two files of one name apart without reading the data. A collection followed from the broker is not a file here, and has none.

Command-line options

Every option, with what it does, is on its own page: Command-line options.

\ No newline at end of file diff --git a/RUGNUX_BENCHMARKING.html b/RUGNUX_BENCHMARKING.html new file mode 100644 index 000000000..3b5410bcb --- /dev/null +++ b/RUGNUX_BENCHMARKING.html @@ -0,0 +1,45 @@ + Measuring Rugnux: validation and timing — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Measuring Rugnux: validation and timing

This page is for anyone who has to say how well, or how fast, rugnux works on a machine: a colleague with a new GPU server, a laptop, a Mac, an ARM box, or an agent running there on someone’s behalf. It explains the two measurements the project uses, how to run them, how to read what they print, and how to take timings that can be compared with someone else’s. tools/battery/README.md in the source tree is the detailed guide to the runner itself: every option, the manifests, the scoring rules and the results.json schema. This page summarises it and does not replace it.

Two measurements, one runner

Everything goes through one script, tools/battery/battery.py. Do not write your own loop over datasets: numbers made by ad-hoc scripts have never been comparable with each other, which is why the old ones were retired.

  • The validation battery (battery.py run) processes a fixed list of rotation datasets and scores each answer against an independent reference. It answers is the result right, and as good as the reference. A full run takes hours.

  • The timing benchmark (battery.py timing) processes four sets, each started from a model that has to be placed by molecular replacement, so one short run exercises the whole pipeline and also checks that the answers are right. It answers how fast, on this machine. It takes minutes, and needs nothing on the machine but four open datasets.

Serial stills have a battery of their own, tools/battery/still_battery.py, on the public datasets of External test data: serial crystallography. It shares the site config, the verbs and the run-directory layout, but scores nothing about the lattice or the symmetry (a serial user gives the cell and the space group): each row says what the merge is worth (R_split, the deposited model’s R-free against it beside the deposition’s own) and what it cost. The README’s The still battery describes it.

The two are kept apart on purpose. A battery run reads hundreds of gigabytes once, so its wall clock mostly measures the disk and the page cache (see the page-cache trap). Use the battery to judge correctness and the timing benchmark, run under controlled conditions, to judge speed.

Setting up a machine

The runner needs Python 3.9 or newer with gemmi and numpy (pip install gemmi numpy), a rugnux binary, the datasets, and a site config: a small JSON file naming this machine’s data roots, where runs go, the GPU lock and the persisted baselines. tools/battery/site.example.json is the template. The runner looks for the config in --site PATH, then in $JFJOCH_BATTERY_SITE, then in tools/battery/site.json, which git ignores. --site is an option of the script itself, so it goes before the subcommand:

python3 tools/battery/battery.py --site /path/to/site.json run --rugnux build/rugnux/rugnux --tier smoke
+

A relative path in the site config (data roots, runs root, lock file, caches) is taken relative to the site config’s own directory, so a config shipped beside its data works wherever it is unpacked. A pdb_cache copied from another machine can be used as it is: the coordinates are looked up where the cache now is, not where its <entry>.json files say they were first fetched.

The data layout (<data root>/<set>/...) and where to get each arm’s data are in the README’s Getting the data. The open arm is public (each dataset’s DOI is in External test data); the in-house data come from the maintainers. The timing benchmark needs only four open dataset directories and the smallest site config there is (below); models, references and expected answers are all in the repository.

The validation battery

Arms and references

The battery has three arms, each scored against a reference that does not come from rugnux:

arm

datasets

scored against

open

public PDB depositions of raw diffraction data, plus a few published small-molecule sets

the deposition: its space group, cell and resolution

inhouse

standard test crystals (lysozyme, thaumatin, insulin, cytochrome C, myoglobin), small-molecule standards, and no-crystal controls

XDS, from the CORRECT.LP stored beside each dataset

private

user data

XDS, as in-house

Each set runs once, with one command per arm. The open arm runs rugnux -o p --no-export-unmerged --model <deposited coordinates> <input>. The XDS arms run rugnux -o p --no-export-unmerged [-A] --report-resolution <XDS d_min>,<XDS d_max> [--model <reference model>] <input>, with -A where XDS merged with Friedel’s law off. Neither --model nor --report-resolution changes the processing: the merged reflections, the resolution cut and every decision are the same with or without them (this has been checked bit for bit). So one run gives both what a user gets and the extra report sections that compare it with the reference.

Verdicts

Every set gets one verdict. Scoring asks four questions in order, and the first that fails decides: did it run, is the lattice right, is the symmetry right, and, on the XDS arms, is the merge as good as XDS’s?

  • pass: the lattice matches the reference (Niggli-reduced primitive cells: volume ratio 0.95 to 1.05, reduced edges within 2%) and so does the symmetry. On the open arm the space group is compared; on the XDS arms only the point group, because XDS never tests a screw axis. A group that the intensities cannot tell apart from the reference (same Laue class, same systematic absences) passes as indistinguishable_alternative. A row whose manifest lists a second defensible answer can pass as accepted_alternative. The report counts both kinds separately.

  • fail, with a cause: wrong lattice (lattice_halved, lattice_doubled, …), wrong symmetry (sym_under, sym_over, sym_screw, …), a reader or indexing failure, a timeout.

  • crash: rugnux was killed by a signal, its log shows Processing failed, a GPU fault, an uncaught exception, or a non-zero sanitizer summary. A crash fails the set whatever its report says.

  • unscored: a question the data cannot answer. Either there is no reference, or the hand of an enantiomorphic pair is in question, or a screw axis lies on a row the sweep never measured (and rugnux said so). This is not a pass, but it is not counted as a failure either.

  • not_run: the input is missing.

A no-crystal control passes only when rugnux reports no lattice. Data quality is reported, not scored: resolution, CC1/2, R_meas, ISa, completeness and the model R-factors are shown next to the reference’s values for a human to judge.

The like-for-like table

On the XDS arms, rugnux keeps its own resolution cut and the reference does not change it. --report-resolution adds a second statistics table (the REFRES_* keys of the report) made from the same merge but binned over XDS’s own range. That gives two separate answers. The own numbers say what a user gets. The reference-range numbers say whether rugnux’s merge is better than XDS’s over the same reflections. Where rugnux’s cut is coarser than XDS’s, the shells past it were never merged, so the completeness there measures coverage, not a drop in quality. The report marks those rows.

On the open arm the deposition gives only a space group, a cell and a resolution, so the data quality is judged from outside: R-free of the deposited model, from rugnux --model (a trend number, see below) and from the REFMAC check, and a per-shell correlation of the merge with the model beside the depositor’s own data (always on, needs no CCP4).

Running it

B="python3 tools/battery/battery.py --site /path/to/site.json"
+R=build/rugnux/rugnux
+
+$B run --rugnux $R --only 5reo,lyso_ref       # named sets
+$B run --rugnux $R --tier smoke               # readers, symmetry classes, known hard cases
+$B run --rugnux $R --tier ci                  # the routine regression check CI runs on every push
+$B run --rugnux $R                            # the full battery: open + inhouse
+$B run --rugnux $R --gpulock --model-check    # queued behind the site's GPU lock, with REFMAC
+

--threads N passes -N to rugnux, --extra "<args>" adds rugnux arguments to every set, --label names the run, and --baseline RUN|none picks the run the report is compared against. --gpulock puts every rugnux behind the command the site config names as gpulock (at PSI, a flock wrapper shared by every GPU job on the machine). A run made that way is marked “timing NOT a reference”, and so is a run that found another process on the GPU before a set.

run exits with status 1 when any set crashed or a ci-tier set failed. Other failures and every metric are reported, not judged.

The run directory

Each run gets a new directory <runs_root>/<YYYYMMDD-HHMM>_<rugnux git>_<label>/, which is never reused and is made read-only when the run finishes. It holds:

  • bin/rugnux: a copy of the exact binary that ran;

  • manifest.json: the options, the binary’s version and sha256, the build flags (read from the CMakeCache.txt above the binary, or from --build-dir), the host and its hardware, start and end;

  • results.json: one row per set, with the verdict, the cause, every number and the exact command;

  • report.md and report.html: the report;

  • work/<arm>/<set>/: what rugnux wrote, p_report.txt, p_log.txt, p.mtz and the rest, plus model_check/ when the REFMAC check ran.

The report opens with the build, host and hardware and whether timing counts. Then come any crashes, a summary per arm (pass, fail, crash, unscored, not run, median resolution gain, ISa, R_meas, time), tables per population, the like-for-like table and, if there is a baseline, every set that moved beyond noise.

Comparing runs

$B list                                   # runs, their state, the baselines
+$B compare RUN_A RUN_B [--all]            # every set whose verdict or numbers moved beyond noise
+$B compare RUN_A RUN_B --rerun-changed    # rerun the changed sets with A's binary
+

Verdicts are scored again whenever a run is read, with today’s rules and today’s references, so the two sides of a comparison are always scored the same way. The noise thresholds are a first guess. --rerun-changed measures the noise directly: a set that moves again under the same binary is noise, and one that reproduces is a real change.

Rules

  • Never start a full battery (no --only, no --tier) on a shared machine without the owner’s go-ahead. It takes hours and everything else on the machine competes with it. A full run takes the site lock, so two cannot overlap.

  • Judge a change against a persisted baseline run, never against a remembered number. The site config’s baseline names a complete run that the owner has blessed, and every new run is reported against it. Totals remembered from earlier runs have been off by a factor of three on the same sets.

  • Keep the manifests unchanged between the two runs you compare. A manifest change is committed on its own, and the baseline is run again with it.

  • Pool fixes. Run the full battery once on a branch that carries several fixes. For a single fix, run the sets it touches with --only, plus the smoke tier.

  • The private arm never leaves the machine. Its names, paths, cells and statistics go into no commit, issue, public report or pack sent elsewhere. A private run gets its own directory and report (report_PRIVATE.*), and the runner refuses to write it into the repository.

The REFMAC model check

R-free from rugnux --model is a trend number. R_FREE= is the placed model scored on rugnux’s own free set, with a deliberately simple scale model, so it shows how a set moves between runs, but it cannot be compared with the deposition’s R-free. rugnux then refines the placed model as well (REFINE_R_FREE=, recorded as rfree_refined in results.json, reported and never scored), still on its own free set, so that number is not comparable with the deposition’s either. --model-check adds an independent number that can be. It runs tools/battery/model_check.py on every open-arm set with a deposited X-ray model, after rugnux has finished, so it cannot influence the processing. It needs CCP4: the runner sources $CCP4_SETUP, by default /opt/xtal/ccp4-9/bin/ccp4.setup-sh, and calls the refmac5 found there (at PSI, CCP4 9.0 with REFMAC 5.8.0431).

What it does

For each set the check takes p.mtz (its F, SIGF and FreeR_flag columns) and the deposited entry (the mmCIF and, when deposited, the structure factors, downloaded from the RCSB into the site’s pdb_cache). Then it:

  1. Reads the published R-work, R-free and d_min from the entry’s _refine record, and skips entries that are not X-ray, have no deposited R-free, hold several models, or have more than 200 000 atoms. Strict-NCS copies the entry only describes by operators are generated.

  2. Finds the model’s setting. Every change of basis that maps the data’s lattice onto the model’s is tried; their Niggli cells are compared loosely, 5% on edges and 3° on angles. That covers an alternative setting, a centred-versus-primitive description and the merohedral indexing ambiguity. Each candidate is scored by the R between the reindexed amplitudes and the model’s |Fcalc| (gemmi, after an overall scale and B) on a mid-resolution shell, and the best one wins.

  3. Re-expresses the data in the deposited space group. The merge is expanded to P1 with rugnux’s own group, reindexed, reduced to the asymmetric unit of the deposited group (equivalents averaged with 1/σ² weights) and given the deposited cell. A space group rugnux called too high just splits equivalents apart here, and one it called too low averages them.

  4. Has REFMAC compute R-work and R-free of the model as deposited, at d_min_used = max(rugnux's d_min, deposited d_min), the lower of the two resolutions. The run is REFMAC’s rigid-body mode with one cycle, and the R-factors are those REFMAC prints for that cycle, before it applies any shift. REFMAC’s default bulk solvent and overall anisotropic scale are fitted, and nothing else. Rigid-body mode reads no restraint dictionary, so ligands, waters and hydrogens stay in. Only atoms of unknown element (UNX), which stop REFMAC and scatter nothing, are removed. Nothing is refined, by design. The data were moved into the model’s frame, so a rigid body has nothing to correct, and at low resolution REFMAC’s rigid body can walk a correct model away.

  5. Scores the depositor’s own structure factors the same way, as the baseline. The depositor’s data go through the same choice of setting, because they can sit on the other branch of an indexing ambiguity. Amplitudes are F_meas, else the mean of F(+) and F(−), else intensities converted by French-Wilson (ctruncate). Their free set comes from _refln.status or pdbx_r_free_flag. The depositor’s free flags are also carried over onto rugnux’s reflections.

  6. Uses twin refinement where the entry declares twinning (_pdbx_reflns_twin), for both data sets, because the published R-free is then a twinned one. The untwinned numbers are kept as well.

  7. Second protocol, refined on a shared free set. The same deposited model is refined against each data set at that set’s own resolution: 10 cycles of restrained refinement, automatic weight, isotropic B for every atom, twin refinement where declared. A ligand that the monomer library describes with different atoms is renamed so that REFMAC builds its restraints from the model. The free set is the depositor’s free reflections that are present in both data sets. Depositor free reflections outside that intersection are dropped from both, so neither refinement uses a free reflection as a work reflection.

The numbers

field in results.json

data

free set

read it as

refmac_rfree

rugnux

rugnux’s

close to a work R: most of rugnux’s free reflections were work reflections in the depositor’s refinement

refmac_rfree_depflags

rugnux

the depositor’s

the fair first-cycle number for rugnux’s data

refmac_rfree_depdata

the depositor’s

the depositor’s

the baseline: same model, same protocol, the data the model was refined against

refmac_rfree_ratio

refmac_rfree_depflags / refmac_rfree_depdata; below 1 means rugnux’s data fit the model better

refmac_refined_rfree_shared

rugnux

shared

the refined number for rugnux’s data

refmac_refined_rfree_shared_depdata

the depositor’s

shared

the same protocol on the depositor’s data

refmac_refined_ratio

their ratio; below 1 means rugnux’s data give the better refined model

refmac_status and refmac_reason say why a set has no numbers: not X-ray, too large, no deposited free set, a download that failed. The same applies to refmac_refined_reason for the second protocol. python3 tools/battery/model_check.py <p.mtz> <pdb id> --workdir DIR runs the check on one merge and prints every field, including the reindexing operators chosen for both data sets. battery.py recheck RUN reruns it on a finished run’s merges without running rugnux again.

Limits

  • The comparison favours the deposition. The model was refined against the depositor’s data, so those data start with an advantage. A ratio near 1 is a good result for rugnux.

  • refmac_rfree_depdata is not the published R-free. It comes from a different program (REFMAC, where the deposition often used PHENIX, whose resolution-binned scaling absorbs a falloff that REFMAC’s overall scale cannot) and from no refinement at all.

  • The data are given the deposited cell. A real cell difference between the two crystals is not modelled, and costs R. The check records it as cell_diff_pct.

  • The first-cycle numbers use the common resolution limit, so they say nothing about the shells only one data set reaches. The refined protocol uses each set’s own range, but its free set is limited to what both data sets measured.

  • The setting is chosen by agreement with the model. That is right for this purpose, but it means the check cannot referee rugnux’s own indexing choice where the model is ambiguous.

Cost

The check is opt-in because it is the expensive part. In a battery run on 2026-10-16, an open-arm set took about 2.5 minutes with the check, against well under a minute of rugnux. The refined protocol can take up to an hour on a large entry. Across a full battery, REFMAC accounts for most of the time, so add --model-check only when the R-free figures are the point, for example in a release battery or for a paper.

The timing benchmark

$B timing --rugnux $R [--benchmark standard|inhouse] [--threads N] [--label L] [--baseline RUN|none] [--extra=<rugnux args>] [--gpulock]
+

The benchmark runs a few sets. Each starts from a model that the run has to place by molecular replacement, so a single run times every stage: reading, pre-scan, indexing, integration, scaling, the space-group search, MR, model validation and the refinement of the placed model. It also checks that every answer is right.

--benchmark standard, the default, is the one to run on a new machine. It uses open data only: three EIGER 16M rotation sets of ordinary size and quality, and a virus capsid as the large case.

set

start model (--model)

what makes it hard

9zlo

the AlphaFold DB prediction of UreE (Proteus mirabilis), committed in tools/battery/models/

two copies to place, P2₁2₁2₁, 2.0 Å

9s02

the AlphaFold DB prediction of human PYCR1, also in models/

five copies, P2₁2₁2, 1.65 Å

9gjx

the AlphaFold DB prediction of a Bacillus licheniformis nitroreductase, also in models/

six copies, P2₁, 2.4 Å, the largest of the three datasets (37 GB)

4nwv

the deposited 4NWV (a virus capsid, I222, 45 chains once strict NCS is expanded), turned 30° and shifted by 12–25 Å along each axis (33 Å in all) by a fixed transform

the largest: too far off for the rigid body, so MR places the whole asymmetric unit

The paper’s Extended Data Table 1 is this benchmark on eleven computers, run with an earlier release that placed the model but did not refine it. A timing taken with a later release includes the refinement of the placed model and is not comparable with the table.

--benchmark inhouse is the benchmark as first set up, kept so that earlier runs stay comparable: the predictions of horse myoglobin (myob_x10sa, a prediction without heme) and bovine cytochrome c (cytc_x10sa: three copies related by a pseudo-translation; the data alone cannot tell P3₁21 from P3₂21, so the model must decide the hand), and the same 4nwv. Its two in-house datasets come from the maintainers.

The predictions are committed next to their predicted-aligned-error files, which rugnux uses to cut them into rigid domains. The deposited entries the placements are checked against are committed too (tools/battery/models/pdb/), and the moved 4NWV is made at run time from the committed 4NWV with the transform in tools/battery/timing.json. A timing run needs no pdb_cache and no network.

What a machine needs

Copy these directories under one open data root (sizes as unpacked; please cite the DOIs):

directory

size

source

9zlo/

11 GB

Zenodo 10.5281/zenodo.18652652

9s02/

11 GB

MX Raw Data Repository 10.60884/NRNGS4

9gjx/

37 GB

IRRMC 10.18430/M39GJX

4nwv/

16 GB

SBGrid Data Bank 10.15785/sbgrid/9

The paths inside each directory are the inputs of tools/battery/open.json (for example 9gjx/BlNTR_9gjx/data/SC6_1_master.h5), and External test data says what each archive holds. The site config needs only the runs root and that data root (tools/battery/site.timing.example.json):

{
+ "runs_root": "/path/to/runs",
+ "arms": {
+  "open": {"data_root": "/path/to/open"}
+ }
+}
+

and the run is

python3 tools/battery/battery.py --site /path/to/site.json timing --rugnux /path/to/rugnux
+

Python 3.9 or newer with gemmi and numpy is all the runner needs.

The checks

A set passes only when every check holds. The thresholds are in timing.json.

check

passes when

why

space_group

the battery’s own verdict on lattice and space group passes (the hand excepted)

the data’s own determination is right

placed

MODEL_PLACEMENT is MR

molecular replacement placed the model, and the R-factors, maps and model written are of that placement

mr_group

MR_SPACE_GROUP is the deposited group, hand included (P 21 21 21, P 21 21 2, P 1 21 1 and I 2 2 2 for standard; P 1 21 1 and P 32 2 1 for the two in-house sets)

the model settles the hand, so this is where a wrong enantiomorph shows

r_free

R_FREE ≤ 0.50 for the predictions, ≤ 0.35 for 4NWV

a random structure gives 0.586

confirmed

CC_MODEL_CONFIRMED_TO_D_MIN is not NONE

some shell’s CC(model, data) clears rugnux’s empirical null

placement_cc

the placed p_model.pdb and the reference model have correlated intensities, ≥ 0.30

see below

placement_cc is the one check that does not depend on rugnux’s own scores. It computes |F|² from the placed model and from the battery’s reference model for the set, each in its own cell and space group. It normalises each resolution shell to its mean, from 10 to 4 Å, and takes the best correlation over the changes of basis the two lattices allow. |F| is the same for every allowed origin and every symmetry copy, so no superposition is needed. A right placement correlates strongly (measured 0.55 to 0.96). A wrong placement gives 0.01 to 0.04, and the wrong hand gives about 0.2. This catches a placement that rugnux reports as right but is not.

Reading the output

The console prints one block per set: the verdict, rugnux’s wall time and the MR time, one line per check (ok or BAD, the value, the limit), and the step times. For example:

4nwv         pass  wall   167.2 s  MR 52.0 s
+    ok  space_group   I 2 2 2 (want I 2 2 2)
+    ok  placed        MR (want MR)
+    ...
+    Reading input 0.2, Pre-scan 4.6, Indexing 5.5, Integration (geometry pre-pass) 11.8, ...
+

The run directory is an ordinary one, so list, table, compare and keep all work on it. Its report.md opens with a Timing benchmark section: the checks per set, then a table with one row per step and one column per set. Each results.json row carries bench_verdict, bench_reason, bench_checks, mr_seconds and steps, the seconds per step. wall_s is rugnux’s own WALL_TIME, so time spent waiting for a GPU queue is not in it. The run exits with status 1 when a set fails a check or crashes. A wrong answer is a failure even when the time is good.

If the site config names a baseline_timing for the benchmark ({"standard": RUN, "inhouse": RUN}, earlier timing runs on this machine), the report is compared against it. Otherwise pass --baseline RUN. Compare timing runs only from the same machine and the same benchmark.

CPU only

$B timing --rugnux $R --extra=--no-gpu
+

This runs a CUDA build as if the machine had no GPU: CUDA is never touched and every step takes its CPU path. Write the option with =, because --extra --no-gpu makes Python’s argument parser take --no-gpu for an option of its own. Several options go in quotes: --extra="--no-gpu -N 8". A CPU run and a GPU run agree to rounding, not bit for bit, so their last digits can differ.

Taking timings that mean something

A wall-clock number is only useful if someone else can reproduce it and if two numbers can be compared. Each lesson below was learned by getting a timing wrong first.

Build like CI

The build system sets no -march and no LTO, so that each site can choose. CI and the released binaries are built with -march=x86-64-v3 -flto=auto on Linux x86 and /arch:AVX with MSVC on Windows. A plain cmake -DCMAKE_BUILD_TYPE=Release build is a baseline binary that nobody ships. GPU work runs at the same speed in it, but the CPU-bound phases (first-pass indexing, scaling and merging) are about 26% slower. A profile of that build also points at the wrong code: Eigen has no vectorised round below SSE4.1. For any CPU-side measurement, build with at least -DCMAKE_CXX_FLAGS="-march=x86-64-v3" -DCMAKE_C_FLAGS="-march=x86-64-v3". On ARM (a GB10 or a Grace) and on Apple Silicon, leave -march out: the default target already has NEON and a vectorised round. The runner records the flags in manifest.json, so always state them.

Do not time the first run after a build

The first runs straight after a build are not representative. On a Windows laptop on 2026-10-14, the runs started immediately after a 500-target build were 1.3 to 2 times slower in every phase: GPU image loop, file reads, everything. Rerun back to back, the same binaries matched to within a few percent. Let the machine settle (the build’s own I/O, antivirus scans of new binaries, a hot CPU on a laptop), then make a throw-away run first.

A quiet machine

On a shared machine, another job’s load makes wall-clock numbers and parallel-efficiency numbers meaningless: they measure the other job. Profiles that report shares of cycles (perf, Nsight) still show where the time goes, but not how long it took. If the numbers are the point, take the machine to yourself. Check uptime and nvidia-smi before and after, and say what else was running. On a laptop, plug it in and keep it in the same power mode: two back-to-back runs of 4nwv on the same binary on a Windows laptop differed by a quarter, with the growth spread over every CPU- and GPU-heavy step. That is thermals and power, not code. Treat such a spread as the machine’s noise.

Interleave: ABAB, not AB

One run of the old binary against one of the new says almost nothing. Run them interleaved, old, new, old, new, on the same two or three sets, in one session on a quiet machine, and compare the pairs. Slow drift (the page cache, thermals, another user) then affects both sides alike. Keep the old binary for this; the run directory’s bin/rugnux is one. Several minutes of ABAB have settled questions that a whole battery’s totals had answered wrongly, more than once.

The page cache

The battery and the benchmark read every image from disk. Whether those files are still in the operating system’s page cache can change a set’s time several-fold, with every result identical. On the PSI workstation, whose data disk is a 7200 rpm HDD, one 10 GB set took 15 s warm and 111 s cold. A whole battery once swung from 11 to 19 minutes only because a large job beforehand had pushed its data out of the cache. The signs are:

  • the slowdown scales with each set’s size on disk, not with its content;

  • it can be bimodal: the sets still cached are unchanged to the second, while the evicted ones are several times slower;

  • divide a set’s extra seconds by its size: if the result is the disk’s read speed, it is the disk;

  • rugnux reads the frames in each of its passes, and on a machine that can hold the set in RAM the later passes are always warm. A real regression slows them too, while a cold read slows only the first pass (compare the Integration (geometry pre-pass) step with Integration (refined geometry) in the log).

Either time warm runs (one throw-away run first, and enough RAM to hold the set) or time cold ones deliberately (on Linux, drop the file from the cache with posix_fadvise(POSIX_FADV_DONTNEED) or echo 1 > /proc/sys/vm/drop_caches). Either way, say which. A machine whose RAM is about the size of a set cannot keep it warm, so on a 16 GB Mac a 16 GB set always reads cold.

The GPU lock

On a machine where several people or agents share the GPUs, the site’s gpulock serialises the jobs. battery.py run --gpulock takes the lock for each rugnux separately, so other jobs can run between sets, and the run is marked “timing NOT a reference”. For a timing session, take the lock once around the whole session instead, so that nothing else gets in between your A and B runs:

flock /data/tmp/gpulock bash -c "
+  $B timing --rugnux old/rugnux --label A1
+  $B timing --rugnux new/rugnux --label B1
+  $B timing --rugnux old/rugnux --label A2
+  $B timing --rugnux new/rugnux --label B2"
+

(/data/tmp/gpulock is the lock file at PSI; use your site’s.)

The runner still checks for other processes on the GPU before each set (gpu_others in results.json). A machine without such a lock, a laptop for example, sets "gpulock": null and runs without --gpulock.

Report the hardware and the conditions

manifest.json records the CPU, cores and threads, RAM and GPUs on Linux. On Windows and macOS it may say “not recorded”, so write the hardware down yourself. A timing means nothing without: the machine (CPU, RAM, GPU and its memory, driver), the OS, the binary (git hash, sha256, build flags, compiler and CUDA version), -N if set, warm or cold data, what else was running, mains or battery power, and which runs are the first after a build.

Windows

  • Run the runner as python -X utf8 tools\battery\battery.py ..., because the report and the console table are UTF-8. Give --rugnux the path of rugnux.exe. The run directory gets its own copy of the binary, so any DLL it needs must be found on PATH.

  • WDDM can quietly page GPU memory to system RAM. A consumer or laptop card under Windows’ WDDM driver model does not fail an allocation that exceeds the card. It spills to “shared GPU memory” in system RAM, and the kernels touching it slow down several-fold with no error. rugnux decides between GPU and CPU from the card’s total memory (80% for scaling and the model fits), but memory held from earlier phases and the driver’s own reserve count too. During a run, watch Task Manager’s Dedicated and Shared GPU memory for the process: if the shared figure grows, the timing measures paging. On 2026-10-15 an 8 GB laptop card spent five times longer in model validation for this reason alone.

  • Windows has no flock and no process groups. The timing benchmark does not need them.

macOS

  • The macOS build has no CUDA. Bragg integration, the model density and the molecular-replacement rotation function run on the Apple GPU through Metal. Everything else runs on the CPU, so a Mac timing is mostly a CPU-bound timing. Molecular replacement in particular takes much longer than on a CUDA machine, as its translation function and rigid body stay on the CPU.

  • Memory is unified: CPU and GPU share it, and the OS compresses memory before it swaps. A 16 GB Mac can run the benchmark, but its biggest set comes close to the limit, so report both measures below.

Memory peaks

The battery does not record memory, so measure it next to a timing when it matters. Each row’s cmd in results.json is the exact command a set ran, so you can rerun that command by hand under a tool that measures:

  • Linux: /usr/bin/time -v <cmd> reports Maximum resident set size, which is VmHWM in /proc/<pid>/status while the process runs. RSS is not the same as live data: glibc keeps freed memory in its arenas, and pinned host buffers for the GPU count too. On one large set about 0.5 GB of the peak was memory freed but not yet returned to the system, and up to 2.4 GB on an older build.

  • macOS: /usr/bin/time -l <cmd> reports both the maximum RSS and the peak memory footprint, which includes compressed memory and GPU buffers and can be much larger. On 2026-10-16, 4nwv showed 9.1 GiB of RSS against about 22 GiB of footprint.

  • Windows: sample the process’s peak working set (PowerShell (Get-Process rugnux).PeakWorkingSet64) while it runs, and Task Manager’s dedicated and shared GPU memory.

  • GPU: nvidia-smi --query-gpu=memory.used --format=csv -lms 500 while the set runs. rugnux’s log also states each GPU-or-CPU decision with its numbers, for example Model validation: ... 4.42 GB held of a 6.84 GB budget, 80% of the card's 8.55 GB and ... scaling on the CPU instead. Quote those lines; they explain most surprises between machines.

Installing Rugnux ▸ Memory explains what sets the peak.

Per-step times: the TIMING lines

rugnux writes its full log to <prefix>_log.txt (p_log.txt in the battery) at debug level, and every timed section adds a line when it ends:

[2026-10-16 07:42:45.430] [rugnux] [debug] TIMING step Integration (geometry pre-pass), 500 images 11.800
+[2026-10-16 07:42:52.230] [Rugnux] [debug] TIMING merge P1 4.697
+

The TIMING step ... lines are the steps shown on the console, and they add up to the run’s wall time. These are what the benchmark tabulates. The other TIMING ... lines are nested sections inside a step (rsm ... sections inside merge ..., everything in a pass before its pass (...) line). tools/rugnux_timing.py p_log.txt tabulates them, and --all lists every section. For a rotation run the steps are, in order:

step

covers

Reading input

opening the master file, geometry and mask

Pre-scan

a projection of a sample of frames: beam stop, background beam centre, spot widths, defective pixels

Indexing

first-pass spot finding and lattice search on the first part of the sweep

Integration (geometry pre-pass), N images

integrating the first part of the sweep at the file’s geometry

Scaling and post-refinement

scaling that pre-pass and post-refining the detector geometry, cell and axis from it

Metric-symmetry check, Geometry check

only where needed: re-integration of a promoted lattice class, more geometry rounds

Indexing at the refined geometry

re-indexing with the refined geometry

Integration (refined geometry), N images

the whole sweep, every frame

Scaling and merging

combining partials, scaling, the space-group search, the resolution cut, merging

Analyses

twinning, anisotropy and the other report-only analyses

Model validation

--model only: structure factors, scale fits, rigid-body placement, maps

Molecular replacement

only where the rigid body did not place the model (always, in the timing benchmark)

Refinement

the placed model refined against the merge (wherever a model is placed, unless --no-refine)

Doubled-cell hypothesis

only where an index-2 superstructure qualifies: the doubled cell integrated and merged as well (Results report)

Writing files

MTZ, mmCIF, HKL, report

A step that is slower on one machine than on another points at the code, and a step that is slower everywhere at once points at the conditions. Send the whole step table, not only the total.

NVTX ranges for Nsight Systems

A CUDA build compiled with the NVTX headers (found next to nvcc; otherwise the configure says NVTX3 headers not found - NVTX ranges compiled out) opens an NVTX range for every console step (Step <n> <title>) and for every TIMING section, with the same names. An Nsight Systems trace therefore shows the pipeline by name above the CUDA kernels and copies:

nsys profile --trace=cuda,nvtx,osrt -o 4nwv_trace <the set's cmd from results.json>
+

Without a profiler attached, the ranges cost nothing.

What to send back

A remote measurement is only useful if the owner can compare it with the others. Send one archive (a “pack”) per session, named after the machine, the binary and the date, for example rugnux_<machine>_<git>_<YYYYMMDD>.tar.gz, laid out like this:

BRIEF.md
+runs/<n>_<what>/report.md          # unedited, as the runner wrote them
+runs/<n>_<what>/report.html
+runs/<n>_<what>/results.json
+runs/<n>_<what>/manifest.json
+runs/<n>_<what>/SOURCE_RUN.txt     # the run directory's original path
+runs/<n>_<what>/logs/<set>/{p_log.txt,p_report.txt,run.log}
+timing/                            # step tables, ABAB comparisons
+memory/                            # peak RSS / footprint / GPU memory samples, with how they were taken
+build/                             # the exact configure command (or CMakeCache.txt flags)
+

BRIEF.md comes first and should be short: the host and hardware, the OS, the binary (git, sha256, build flags, compiler, CUDA), the data (which pack, warm or cold), the conditions (quiet or shared, power, first run after a build), and then the results. Give a table per run, the step table of the slowest set, what changed against the previous pack from the same machine, and what is not explained yet together with the experiment that would explain it. Number the runs in the order they were made, and say which ones are not representative and why (1_ straight after the build, for example).

Leave out the maps, MTZ files and binaries unless they are asked for, since they are large and the logs and reports carry the numbers. Never edit a report.md or results.json: comment in the brief instead. If you had to patch the runner to make it work, include the patch and say so. A pack never contains anything from the private arm.

\ No newline at end of file diff --git a/RUGNUX_CALIBRATION.html b/RUGNUX_CALIBRATION.html new file mode 100644 index 000000000..4f93429bb --- /dev/null +++ b/RUGNUX_CALIBRATION.html @@ -0,0 +1,4 @@ + Detector calibration from powder rings (rugnux --mode calibration) — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Detector calibration from powder rings (rugnux --mode calibration)

The calibration mode determines the detector geometry — PONI x/y, the two tilts rot1/rot2 and the distance — from the powder rings of a calibrant, and writes it as a pyFAI <prefix>.poni file and a machine-readable <prefix>.json, alongside a printed report of how far each parameter moved from the header. Bragg data pin the beam centre worst (it is gauge-coupled to the crystal orientation); a powder ring has no orientation to be coupled to, so this is the measurement that fixes it.

rugnux --mode calibration --calibrant lab6 -o det LaB6_master.h5
+

What it writes

<prefix>.poni is for pyFAI and the tools that read its format. <prefix>.json is for everything else, and has two members:

  • dataset_settings — the geometry under the property names dataset_settings gives them in jfjoch_broker’s OpenAPI schema, and nothing else. It is a valid dataset_settings body as it stands, so it can be POSTed or merged into one without translating a field:

    curl -X POST -H 'Content-Type: application/json' \
    +     -d "$(jq -c .dataset_settings det.json)" http://broker:5232/start
    +

    beam_x_pxl/beam_y_pxl is the PONI, as everywhere in this system — on a tilted detector it is not where the direct beam lands. The three poni_rot*_rad are written whenever any of them is non-zero, and left out when all are zero: a body that omits them states a flat detector, so they travel together or not at all.

  • calibration — what the run knows about that geometry: the residual, the fit’s own sigmas and the correlation between the tilt and the beam centre, whether the tilt cleared its significance test or was declined and pinned, where the direct beam lands, and where the spots independently put the beam. A calibration that has gone wrong looks exactly like one that has not until those are read.

--calibrant takes lab6, agbh (silver behenate), ceo2, si or ice, case-insensitively. ice calibrates a real experiment against its own ice rings — no calibrant exposure needed — and is the one calibrant given as a list of measured ring positions rather than a unit cell: hexagonal ice is P63/mmc, so rings enumerated from its cell would include systematically absent ones. The others are cells with their reflection conditions (LaB6 primitive, CeO2 face-centred, Si with the diamond glide, AgBh triclinic). A standard that is not on the list is given by its unit cell instead: with -C the cell is the calibrant, its rings enumerated from the cell, with the absences of -S where that is given (taken as primitive where it is not). -S supplies symmetry absences only, so a standard whose extinctions come from its atomic basis — silicon’s 222 — is better named with --calibrant.

--calibration picks how the rings are measured, and both aggregate over every processed image — -s/-e/-t select which images:

  • rings (default) sums the (q × azimuth) azimuthal profile over every processed image into one map and fits the ring arcs in it. A powder ring is an arc, not a set of spots, and the summed profile measures it at every azimuth with all the run’s counts behind it. It needs the profile to be binned in azimuth, so this mode defaults --azim-phi-bins to 32.

  • spots pools the found spots of every processed image and fits those. It determines the centre from scratch (a Hough circle vote, which quantises it to a whole pixel) and then refines.

Both routes read the ring position out of a binned profile or a spot centroid, so the radial sampling matters: at a long detector distance the default 0.01 Å⁻¹ q bin is several pixels wide and quantises the rings route accordingly — pass a finer --azim-q-spacing there (the total q × azimuth bin count must stay under 65534).

The report prints the fitted geometry, the scatter of the ring points about the fitted rings and the standard error that implies on the centre. That error is formal: it measures the scatter of the points, not whether the rings themselves are trustworthy, so it stays small when a fit goes wrong for a structural reason — one visible ring, or ice that is textured rather than smooth.

A calibration is run because the header is in doubt, so a fit that quietly hands part of that header back has answered nothing — and it looks exactly like a fit that worked, down to the residual and the sigmas around it. calibration.converged in the JSON says which of the two a file is. It is false when the tilt was declined and pinned at a non-zero header value — the rings said they could not tell a tilt from a shift of the beam centre, and the angle written in its place has no more support than the one refused — or when the fit’s covariance never conditioned, so it cannot say what it determined. In either case Rugnux prints the reason, writes the .json with converged false and not_converged_reason beside it, exits non-zero, and writes no .poni: a PONI file states where the detector is and has no field in which to say that it does not know. A declined tilt over a header that states no tilt is not this — reporting no tilt is then exactly what the fit measured.

A .poni is refused for a second reason, whatever the fit found: a detector whose image orientation is not the identity — the stored image mirrored in Y, or turned by a multiple of 90° about the beam. That comes either from --detector-mirror-y / --detector-quarter-turns or from the file itself (a PILATUS miniCBF axis table, an NXmx module’s pixel directions). A PONI states the detector in five numbers — two offsets, a distance and three rotations — and has no field for how the image is stored, so one written here would describe a different geometry from the one that was measured. The run says so and exits non-zero.

--no-refine-tilt holds rot1/rot2 where the header put them and fits only the centre and the distance. The tilt is real and worth measuring, but a program that has nowhere to put one — XDS takes a detector normal to the beam — is better given a geometry that was measured with the tilt pinned than one that was measured tilted and then flattened, because in the tilted fit the centre and the distance have already absorbed the tilt.

Both the PONI (the point of normal incidence, which is what a .poni file stores) and the direct beam (where the beam lands, which is what most other programs call the beam centre) are printed. They differ by distance × tan(rot) once the detector is tilted, which on a 0.3° tilt at 300 mm is several pixels — enough to look like a disagreement with another program when there is none.

\ No newline at end of file diff --git a/RUGNUX_CLI.html b/RUGNUX_CLI.html new file mode 100644 index 000000000..2c963d64e --- /dev/null +++ b/RUGNUX_CLI.html @@ -0,0 +1,16 @@ + Command-line options — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Command-line options

rugnux run with no arguments prints a short usage: how to run each mode and the options most runs need. This page is the full reference behind it - every option the program accepts, with what it does. The program’s own usage message is the authority on behaviour; this page is kept consistent with it.

The same pages ship with the release archive, as share/doc/jfjoch_rugnux/html/ beside bin/, so they can be read without a network; this one is share/doc/jfjoch_rugnux/html/RUGNUX_CLI.html.

rugnux [options] <input> [<input> ...] [<broker URL>]
+

Running each mode

What a run does is chosen with --mode (default mx). Within mx, rotation and stills are not chosen by an option: a dataset whose goniometer axis turns is processed as a rotation sweep, one without a goniometer axis - or with an axis that stands still - as serial stills.

Rotation data (--mode mx, the default)

rugnux -o myrun dataset_master.h5              # NXmx / EIGER / Jungfraujoch master file
+rugnux -o myrun sweep_00001.cbf                # CBF, marCCD or SMV sweep: name one frame
+rugnux -o myrun dataset_master.h5 model.cif    # with a model (or --model model.cif)
+rugnux -o myrun x_master.h5 http://host:5232/  # follow a broker's collection while it is written
+rugnux -o myrun a_master.h5 b_master.h5        # several sweeps of one crystal, merged as one
+

Chosen when the file’s goniometer axis turns. Several sweeps can be given (below, Inputs). A model is placed (rigid body, or molecular replacement), refined and validated after merging; it does not change the processing decisions (Models and reference data).

Serial stills (--mode mx)

rugnux -o serial *_master.h5                                # several NXmx masters of one setup
+rugnux -o serial -C 79,79,38,90,90,90 -S P43212 run*.h5    # SACLA (Cheetah HDF5)
+rugnux -o serial -C 79,79,38,90,90,90 -S P43212 *.cxi      # Cheetah CXI
+rugnux -o serial -C 79,79,38,90,90,90 -S P43212 *.xtc      # LCLS-I XTC streams
+

Chosen when there is no goniometer axis or it does not turn; --force-still processes a rotation sweep as stills. Giving the known cell (-C) and space group (-S) is recommended for stills. Several inputs are one dataset, read in the order given. Without -C the stills are indexed de novo; a model is given as for rotation data (Still / serial data).

Refinement (--mode refine)

rugnux --mode refine -o refined data.mtz model.cif
+

Refines a model against merged data that already exist - an MTZ or a structure-factor mmCIF - and reads no images. The model is required, given among the inputs or with --model (Refining a model against structure factors).

Detector calibration (--mode calibration)

rugnux --mode calibration --calibrant lab6 -o det LaB6_master.h5
+

The detector geometry from a powder standard’s rings, written as det.poni (pyFAI) and det.json (Detector calibration).

Azimuthal integration (--mode azint)

rugnux --mode azint -o profiles dataset_master.h5
+

Azimuthal integration only - no spot finding, indexing or merging; writes profiles_process.h5. The binning is set by the azimuthal-integration options.

Re-merging (--mode scale)

rugnux -o myrun --write-process-h5 dataset_master.h5   # integrate and merge once
+rugnux --mode scale -o remerged -A myrun_process.h5    # re-merge (on stills, -A keeps the Bijvoet hands apart)
+

Re-scales and merges the reflections already integrated into a _process.h5, without re-running spot finding or integration (Re-scaling and re-merging).

Inputs

Inputs are files, never a directory, read in the order given (a shell glob gives them sorted by name). Several inputs are one stills dataset in --mode mx, or several rotation sweeps (below): all the files of one dataset - rugnux run*.h5 (SACLA), *.cxi, *.xtc (LCLS) - or several Jungfraujoch/NXmx masters of stills - or of rotation sweeps under --force-still - read as one run: their images one after another, merged together, with the indexing rate reported per master as well. Such masters must share the detector, wavelength, distance and beam centre. A grid scan an input holds (a fixed-target chip) is not carried into the run: several chips are not one grid, so the run has no grid map. Several inputs must be one format; any --mode other than mx, and following a broker, take one.

Several rotation sweeps are told apart from the files: one sweep per CBF/marCCD/SMV/SFRM file-name template (the name with its frame number taken out - any frame of a sweep names the whole sweep, so rugnux a_*.cbf is the one sweep a), one per rotation master. Only the inputs given are processed; other sweeps beside them are named in the log. A mix of rotation and stills masters is refused, and so are sweeps at different wavelengths, -s/-e with several sweeps, and --force-still with several sweeps of frame files (several masters under --force-still are one stills run, above). By default (--sweeps joint) the sweeps are one dataset, merged in two levels as XSCALE merges the data sets XDS made of each sweep: each sweep is processed on its own first - indexed, integrated, its partials combined and scaled, its space group determined - writing only its log <prefix>_s<k>_log.txt; the sweeps are then put on the axes of the best of them (the finest resolution of its own merge among the sweeps whose error model resolved an ISa, ties: the higher ISa) - the change of basis, an axis permutation or a twin law of the lattice, under which their merged intensities correlate best; where the lattice allows more than one indexing, which one each sweep takes is settled over all pairs of sweeps at once - and each is judged by its isomorphism ratio with it (see RUGNUX_REPORT): clearly about 1 it joins, clearly below it (another crystal) it is left out, and in between the merge decides - it joins unless it is shown to hurt: adding it raises the held-out residual of the others’ merge by more than 1%, two standard errors down (a sweep left out is named in the log). The crystal has one cell: a joined sweep whose own cell is more than 0.3% off that of the joined sweep reaching the finest resolution (where the cell is measured rather than the distance) is processed a second time, from the distance that would make the two cells agree, and that run replaces the first where its intensities agree better with that sweep’s (a lower held-out residual). Their fulls are scaled and merged together: a per-frame scale within each sweep, the sweeps’ dose order read from their relative B factors (not from the input order or the header times), a decay along that order or one B per sweep, whichever predicts held-out frames better, then the space-group search, the resolution cut and everything after it on the joint data, into <prefix>.*. The detector-dependent corrections (absorption and detector surfaces) are each sweep’s own. The unmerged MTZ holds the joint merge’s scaled observations in the batches of their own sweeps (sweep s of the merge: batches s * base + frame + 1, base the power of ten past the longest sweep), under the batch headers that sweep’s own run wrote; the report names each sweep in section 1b. SWEEPS. --sweeps separate processes each sweep alone instead, as if it were the only input, into <prefix>_s<k>_* (k = 1, 2, … in the order given).

What each format needs is in Input formats; serial XFEL stills are read without a geometry file where their own metadata places the detector (Serial XFEL inputs).

An atomic model and a reference reflection file can be given among the inputs, in any order, instead of --model and -z. Each file is told by its contents, not its name: an MTZ (the MTZ magic) or an mmCIF with a _refln or _diffrn_refln loop is reflections (-z; the input itself in --mode refine), a PDB file or an mmCIF with an _atom_site loop is a model (--model), anything else is images. An mmCIF holding both coordinates and reflections has to be given with --model or -z. At most one of each, also counting --model/--mr and -z; gzipped or not.

With a broker URL (http://host:port/) as the last argument and no input on disk yet, rugnux follows the broker’s current collection while it is written: the input must be the path its master file will have, the data files are read next to it as the broker reports them closed, and the run ends with the images the collection delivered. Rotation data, --mode mx only. The collection’s token is read from the environment variable JUNGFRAUJOCH_HTTP_TOKEN and sent only to the broker. With the input already on disk, the URL is ignored.

All options

General

Option

Description

-o, --output-prefix <txt>

Output file prefix (default: output)

-N, --threads <num>

Number of worker threads (default, and for any value ≤ 0: every CPU the run may use - its affinity and cgroup quota). Some stages take fewer, because past a point more workers make them slower: the per-image loop of --mode mx uses at most 16 per GPU unless -N was given a positive value, and first-pass spot finding and the beam-stop pre-scan have ceilings of their own that -N does not lift. On a small card the two ceilings, and the per-image loop’s 16 where -N was left at its default, come down to as many workers as keep their buffers (about 24 bytes per detector pixel each) within half of the card’s total memory. Scaling, merging and the space-group search use the full count

-s, --start-image <num>

First image to process (default: 0)

-e, --end-image <num>

End image number, exclusive: -s 0 -e 100 processes images 0-99 (default: all)

-t, --stride <num>

Process every n-th image (default: 1)

-v, --verbose

Show the whole log on the terminal in place of the steps; <prefix>_log.txt is written either way

--simulate-live <ms>

Read a stored input as the collection it was while being written: image i becomes readable (i+1)·ms ms after the start (0: all at once). The run takes the live path a broker URL takes, with the same result; for testing the live workflow without a broker. --mode mx only

--fast-live

With --simulate-live or a broker URL: run as the broker’s rugnux live mode does — every decision stands where it was first taken, nothing is re-checked or run again once the sweep is in, the integration radius is fixed, and SIGINT cuts the run to what it has established. A difficult crystal can come out worse

--sweeps joint|separate

Several rotation sweeps (see Inputs): joint (the default) merges them as one dataset into <prefix>.*; separate processes each alone into <prefix>_s<k>_*

--no-gpu

Run on the CPU only, as on a machine without a GPU, even where one is present: CUDA is not touched (nor, on macOS, the Apple GPU that Bragg integration, the model density and the molecular-replacement rotation function otherwise run on) and every GPU step takes its CPU path (-X FFT indexes with FFTW and -X FFBIDX with its CPU implementation; -X cuFFT is refused)

Mode

--mode <name> (default mx):

Value

Description

mx

Full analysis — spot finding, indexing, integration and merging

azint

Only azimuthal integration (no spot finding/indexing); writes <prefix>_process.h5

scale

Only re-scale/merge the already-integrated reflections in the input _process.h5 (no re-integration)

calibration

Determine the detector geometry from powder rings; writes <prefix>.poni and <prefix>.json

refine

Refine the --model against merged structure factors (an MTZ or a structure-factor mmCIF) and process nothing; see Refining a model against structure factors (--refine-score-only, --refine-d-min)

Refinement (--mode refine)

The columns are found, not named - amplitudes with their sigmas (F/SIGF, FP/SIGFP, …) where the file has them, else intensities (IMEAN/SIGIMEAN, I/SIGI, …) made into amplitudes by French-Wilson, else the mean of the anomalous pairs; the free set from a FreeR_flag-like column (0 the test set, or the minority value where 0 is the majority, as phenix writes it), drawn by rugnux where the file has none. The model is taken as placed in the data’s cell, and refined in the data’s space group.

Option

Description

--refine-score-only

Score the model as given and refine nothing: R-work/R-free, the scale, the bulk solvent, the likelihood and the geometry, each term under REFINE_SCORE_ (--developer prints them all); the twin test is the refinement’s (REFINE_TWIN)

--refine-d-min <num>

Leave out reflections finer than this (Å) Accepted 0.1-100.

Calibration (--mode calibration)

Option

Description

--calibrant <name>

Powder standard: lab6 | agbh | ceo2 | si | ice (default lab6, case-insensitive). A cell given with -C overrides it: that cell is the standard, its rings enumerated from the cell, with the absences of -S where given

--calibration <txt>

How the rings are measured: rings | spots (default rings; see Detector calibration). rings defaults --azim-phi-bins to 32

--no-refine-tilt

Do not refine the detector tilt: hold rot1/rot2 at the header value and fit only the beam centre and the distance, for a calibration handed to a program that cannot express a tilted detector (XDS). On stills it holds the tilt in the geometry refinement too

Detector mask

Option

Description

--detect-beam-stop[=N|off]

Find the beam stop and its holder in a projection of N images and add them to the pixel mask as bit 9, so nothing shadowed by them is integrated. On by default (60 images); =off disables. A reflection whose signal disk reaches into the shadow is not integrated: the rest of such a disk lies in the stop’s half-shadow and reads low. Pixels the finder reports that hold the detector’s no-data mark (a PILATUS gap) are masked as dead instead

Beam centre

Option

Description

--beam-center-check[=off]

Measure the beam centre from the isotropy of the scattered background on every run, report how far the file’s value is from it (against how right this geometry needs it to be), and on rotation data index a second first pass at the measured centre. The fit reads the projection --detect-beam-stop already builds, so it costs no extra frames. On by default; =off disables it, and with it the measured centre’s part in the post-refinement bound. The measured centre is adopted where the file’s centre indexes nothing and the measured one indexes a majority; where the two return cells related by an integer volume factor (2 to 4) and the pre-scan’s point-symmetry capture (where its margin is at least 1.5 %) lies nearer the measured centre - without an informative capture, where the measured centre’s cell, larger or smaller, carries materially more of the pooled validation spots against its own chance level, and otherwise the two centres are judged on the merge; and, on a two-pass run, where the first pass is run at both centres and the measured one merges better — done where the two give the same cell in different metric symmetries, where they agree only once less of each frame is read, and where they agree but lie further apart than the geometry absorbs and the file’s centre merges inconsistently in the lowest-resolution shell. Otherwise the file’s centre is kept. On stills, where there is no first pass, the file’s centre, the measured one and the point-symmetry capture’s are each indexed on a sample of frames and the one putting materially more spots on the lattice is taken; with -C, or after the geometry refinement has fitted a cell de novo, the detector distance is searched too (30-3000 mm, the file’s value one hypothesis). Still runs when --beam-x/--beam-y are given. See §1.4

Spot finding

Option

Description

--spot-sigma <num>

Noise sigma level for spot finding (default: 4.0)

--spot-threshold <num>

Photon-count threshold for spot finding (default: 10)

--adaptive-spots

Self-calibrating detection (default, stills and rotation alike): the strong-pixel threshold comes from each image’s own per-resolution-ring noise instead of the fixed --spot-threshold, so one setting adapts across datasets (no per-dataset --spot-threshold/--spot-sigma tuning)

--no-adaptive-spots

Turn adaptive detection off and use the fixed --spot-threshold / --spot-sigma finder

--spot-false-pixels <num>

Adaptive-detection operating point: expected noise pixels tolerated per frame (default: 100; implies --adaptive-spots). A run that finds no lattice at it is made again once at ten times it (SPOT_FALSE_PIXELS_LOOSENED in the report)

--spot-high-resolution <num>

High-resolution limit for spot finding, Å. Omitted (or 0): no resolution clipping — spot finding extends as far as the detector reaches, for rotation data as well as stills

--spot-low-resolution <num>

Low-resolution limit for spot finding, Å (default: 50; lower it, e.g. 24, to exclude the direct-beam halo on weak serial data; 0 removes the limit)

--min-pix-per-spot <num>

Minimum connected strong pixels per spot. If omitted, min-pix is chosen per image (stills indexing): the frame is scored at min-pix 2/3/1 (one lattice search per frame, refined on each list) and the one maximising indexed-spot count × indexed fraction is kept. Give an explicit value to force a fixed min-pix instead. On rotation data the default is a fixed 2.

--max-spots <num>

Maximum spots kept per image (the strongest ones) and handed to indexing. If omitted, the budget is measured on rotation data: the first pass reads how deep into an image’s spot list its spots still lie on the lattice it found, and the run keeps that many (never more than 1000). Give a value to pin it. Stills always use the fixed 1000.

--detect-ice-rings[=on|off]

Flag ice-ring spots (de-prioritised in indexing) and exclude ice-ring reflections from scaling; on rotation data the merge then decides ring by ring whether to merge, down-weight or reject them. Default: the master file’s detect_ice_rings, or — where the file carries no such key — on for rotation and off for stills

Azimuthal integration

The radial profile behind the per-image ice-ring score, and what --mode azint writes. Every q here is q = 2π/d, in Å⁻¹:

Option

Description

-q, --azim-q-spacing <num>

Q bin spacing, 1/Å, for linear binning (default: 0.01; finer resolves the narrow ice rings). Not together with --azim-q-bins

--azim-q-bins <num>

Number of Q bins between minimum and maximum Q, instead of a spacing. Required for --azim-q-binning log10

--azim-q-binning <txt>

How the Q bins are laid out: linear (equal steps in Q, the default) | log10 (equal steps in log10 Q: fine bins at low Q, coarse at high Q). --mode calibration needs linear

--azim-min-q <num>

Minimum Q, 1/Å

--azim-max-q <num>

Maximum Q, 1/Å. Omitted: integration extends to the highest Q the detector reaches. The adaptive spot finder shares these Q bins, so this also sets how far self-calibrating detection can see

--azim-phi-bins <num>

Number of azimuthal (phi) bins (default: 1)

--polarization-correction <on|off>

Enable/disable the azimuthal polarization correction

--solid-angle-correction <on|off>

Enable/disable the azimuthal solid-angle correction

Indexing

A dataset with a rotation goniometer axis is processed as rotation data (two-pass rotation indexing) by default; a dataset without one is processed as independent stills. --force-still overrides the former; the -R / --force-rotation-lattice flags request rotation explicitly and set the first pass’s image count or skip it with a given lattice.

The FFT search looks for cell axes between 10 Å (--fft-min-unit-cell) and a default longest axis of 500 Å, which has no flag of its own — a reference cell (-C) moves both bounds to cover the cell it names. On rotation data a lattice row shorter than the floor, down to 3 Å, is found under the multiple of it the search reports there, so a small-molecule cell below the 10 Å floor is indexed on its true axes rather than as a supercell of them. The long end is extended the same way: wherever the detector separates the lattice rows of an axis longer than 500 Å (distance × wavelength / (pixel × spot width)), a coarse search to that length, up to 1200 Å, offers its lattices as a further hypothesis, kept only where it puts more of the pooled validation spots on itself beyond chance. An axis beyond the search’s reach is not refused: the run returns a plausible shorter sub-cell or an axis harmonic and processes it happily, so a cell that comes out at a half or a third of the expected long axis should be read as this limit, not as the crystal. For very long axes the direction grid’s angular resolution binds well below 500 Å — see the analysis reference on FFT indexing.

Option

Description

--force-still

Treat a rotation (goniometer) dataset as independent stills instead of rotation; several masters are then read as one stills run

-X, --indexing-algorithm <txt>

Auto (default) | FFT | cuFFT | FFTW | FFBIDX | None, case-insensitive. FFT is the de-novo FFT search, on the GPU (cuFFT) where there is one and --no-gpu is not given, otherwise on the CPU (FFTW); cuFFT and FFTW name one implementation each; cuFFT needs a GPU and is refused without one. FFBIDX (known cell, -C) runs on the GPU where there is one and otherwise on the CPU. Auto takes FFBIDX on stills with a known cell, and FFT otherwise. FFBIDX without a cell (-C, or one from -z) resolves to None and indexes nothing, with no error. On rotation data -X is not consulted: the FFT search runs on the GPU where there is one and on the CPU otherwise, so Auto, FFT, cuFFT (with a GPU) and FFTW (without one, or under --no-gpu) are accepted and any other value stops the run at indexing; FFBIDX and None are for stills

-F

Short for -X FFT, kept for old command lines

-C, --unit-cell <cell>

Reference unit cell "a,b,c,alpha,beta,gamma" (required by ffbidx). On rotation data it also widens the FFT search to cover the cell given, at both ends: the longest axis looked for is raised to reach it, and --fft-min-unit-cell is lowered to admit it. A candidate that is an integer supercell of the cell given (a twin’s coincidence lattice, a row taken at a multiple of its length) is stepped down to it. On stills the run always uses it: the geometry refinement takes it as a prior (1 % on the lengths, 1° on the angles the crystal system leaves free), and the log warns - with both numbers - where the frames refine its shape more than 3 % / 3° away, or where a sample of frames indexed de novo puts materially more spots on the lattice than the cell given (§7.7)

--fft-min-unit-cell <num>

Shortest cell axis the FFT search accepts, Å (default: 10; accepted 5-40). A candidate with a shorter axis is discarded — but on rotation data a row shorter than the floor, down to 3 Å, is recognised under the multiple of it the search reports past the floor, so a small-molecule cell is indexed without this flag. -C lowers the floor on its own to cover the cell given. On stills a crystal below the floor cannot be indexed unless this is lowered

--min-indexed-spots <num>

Spots a frame must have on the lattice before it counts as indexed (default: 6, minimum 4). It sets the reported indexing rate and the count the rotation first pass ranks candidate lattices by; whether the run has a lattice at all is decided on the pooled spots instead (§4.1), and integration is not gated by it

-S, --space-group <num|symbol>

Space group number (96) or Hermann-Mauguin symbol (P43212) — for indexing and scaling. On serial stills whose group admits two indexings, it also lets the crystals be put on one from the data (the indexing ambiguity)

-r, --geom-refine <txt>

Geometry refinement: none | orientation | beam_and_lattice (default; on rotation data restrained toward the sweep’s geometry, §7.4) | flex (try all three per image, keep whichever indexes the most spots; alias multi)

-R, --two-pass-rotation[=num]

Two-pass offline rotation indexing (default for goniometer data; optional first-pass image count, default 100)

--force-rotation-lattice <vec>

Force rotation lattice (9 floats, Å), skipping the first pass

--rotation-no-postrefine

Rotation: disable the default-on two-pass geometry post-refine (see Rotation data)

--prepass-fraction <f>

Rotation: the two-pass geometry pre-pass integrates the first fraction f of the sweep, but at least 120° of it (0.05-1, default 0.5; 1 integrates the whole sweep twice). The second pass always integrates every frame. The pre-scan and the first-pass indexing sample the same part of the sweep

--refine-geometry[=N|off]

Stills: extra first pass that bundle-adjusts the shared beam/distance/cell from N strongly-indexed frames (default 200) then re-indexes; default ON for stills, a stationary goniometer axis counting as stills, =off disables. The cell’s lengths and the angles its crystal system leaves free are refined with the distance; the bundle anchors them on the reference cell (-C / -z) by a prior of 1 % / 1°; without one, on the cell most of the sampled frames index to de novo, which is used for the geometry steps only (the run is still indexed de novo)

--index-ice-rings[=on|off]

Index on the spots flagged as sitting on an ice ring too, instead of setting them aside (default: off; no effect without --detect-ice-rings, which does the flagging)

Indexer choice in brief: ffbidx (GPU or CPU) refines toward a known cell and is best for sparse serial stills; fft (GPU) / fftw (CPU) index de novo and suit strong rotation data. See the CPU/GPU data-analysis reference for the algorithms.

Scaling and merging

Option

Description

--no-merge

Skip scaling and merging, which are on by default; the per-image _process.h5 is then written instead of the merged files (_unmerged.mtz and the results report are still written)

-A, --anomalous

Serial stills: merge each Bijvoet hand as its own unique reflection, so the files carry I(+)/I(-) and multiplicity, completeness and ⟨I/σ⟩ are counted anomalously; without it a stills merge keeps no split. On rotation data it changes nothing: the merge always keeps the Bijvoet split, every decision is taken with Friedel mates merged, the files and the statistics are the same with and without it, and the report’s ANOM_* table counts the same merge per hand on every run; -A then only sets FRIEDELS_LAW= FALSE in the report (see Reflection-file conventions)

--scale-fulls / --no-scale-fulls

rot3d: refit a per-frame scale on the combined fulls (XDS order, Unity model); on by default for rotation data, off for stills

--smooth-g[=deg]

rot3d: smooth the per-frame scale G over a degree range before the 3D combine (XDS DELPHI-like; default 5° for rotation, 0 = off)

--no-scaling-corrections

rot3d: disable the default-on decay + absorption + modulation correction surfaces fitted on the fulls after scale-fulls

--relative-b[=deg]

rot3d: fit a per-batch relative-B beyond the single decay slope over deg-degree batches, cross-validated (default 10° when bare; off otherwise)

--simple-stills

Stills: treat every reflection as a full (p = 1, single-pass scale/merge) — disables the default-on physical partiality post-refinement

--live-checkpoints <f1>[,<f2>...]

--mode scale, stills (for developers): replay the stored frames in image order as the broker’s live merge of a serial collection merges them - a merge at each fraction of the images (e.g. 0.5,0.75), each crystal after the first checkpoint scaled, post-refined and placed in its indexing against the latest checkpoint’s merge as it comes, and after the last frame one merge of all of them without a scaling or post-refinement over the whole run. The log gives each checkpoint’s statistics and time, and the time of the merge after the last frame; the merge written is that last one. Without it --mode scale merges cold, as the broker does when no checkpoint is reached Each fraction 0.01-0.99.

--live-final-full

With --live-checkpoints: the merge after the last frame scales and post-refines every crystal over the whole run, as a cold merge does, instead of merging the crystals as they were prepared against the checkpoints - what the broker’s live merge would do with a full scaling pass at the end; its time is in the log beside the incremental one’s.

--no-expected-variance-merge

Stills: disable the default expected-variance merge weighting (which rebuilds each weak observation’s signal variance at the reflection mean to de-bias the inverse-variance merge); restores observed-sigma weighting

--capture-uncertainty <num>

Systematic sigma num·(1−captured fraction)·⟨I⟩: on rot3d fulls the share of the rocking curve not captured, on stills the share of each partial its partiality does not see (default: 1.0 for rotation, 0 otherwise)

--min-captured-fraction <num>

rot3d: drop a combined full whose rocking curve was captured below this fraction — edge-of-sweep truncated fulls (default: 0.7 for rotation, 0 otherwise; 0 = off)

--scaling-high-resolution <num>

High-resolution limit for scaling, Å — manual override (default: no limit; disables the automatic cutoff below) Accepted 0.1-1000.

--scaling-low-resolution <num>

Low-resolution limit of the scale fit, Å (default: 50, which is also XDS’s own default; 0 removes the limit). Reflections coarser than it are merged and written but kept out of every fit of the scale model: measured on a background the beam stop depresses, a few of them can bend the model enough to move the merged low-resolution intensities by tens of percent. Which of them are measured at all is the beam-stop mask’s decision - a reflection whose signal disk reaches the shadow is not integrated (--detect-beam-stop)

--resolution-cutoff <txt>

Automatic high-resolution cutoff for the written reflections and reported shells: cc-logistic | off (default: cc-logistic; ignored when --scaling-high-resolution is set)

--resolution-cc-target <num>

CC1/2 target defining the cc-logistic fall-off (default: 0.30)

--resolution-shells <num>

Number of resolution shells in the reported statistics table (default: 9). The bins are equal steps in 1/d² between the lowest- and highest-resolution reflection merged, which is XDS’s rule, and 9 is XDS’s count — so at the same resolution limits the two tables have the same shells and can be read row for row

--report-resolution <dmin>[,<dmax>]

Also report the merging statistics over this resolution range, Å (either order; dmax defaults to the run’s own low-resolution limit), as a second table beside the run’s own — the REFRES_* keys of the results report — binned from the same merged reflections, so a run can be read against another program’s table at that program’s range. Report-only: the cut, the scaling, the error model and every decision stay the run’s own, and shells finer than the run’s own limit are reported as not merged rather than filled from data the run did not keep Each limit 0.1-100000 Å; two equal values are refused.

--min-partiality <num>

Minimum partiality to accept a reflection (default: 0.02 for rotation, 0.5 for stills)

--ice-min-score <num>

Ice-presence gate: the measured per-run ice score (1 = no ice) a dataset must reach before any ice handling is applied — the flagging, the exclusion from scaling and the per-ring merge decision (default: 1.5; 0 = no gate). The fixed hexagonal bands cover 16–26 % of the unique reflections whether or not the crystal has ice, so handling ice on a clean crystal only costs completeness

--ice-min-spot-ratio <num>

The second ice-presence channel: found spots on the hexagonal rings over the same q width of ice-free flanks beside them (1 = spots spread evenly). Ice in large crystallites diffracts as discrete spots and leaves the radial profile flat, so --ice-min-score alone is blind to it (default: 2.0; 0 disables this channel)

--reject-outliers <num>

Per-observation outlier rejection, N σ from the per-reflection median (default: 6 for rotation, 10 for stills; 0 = off)

--min-image-cc <num>

Per-image CC limit, percent (default: no limit)

--search-min-zeta <num>

De-novo space-group search only: also search a merge of just the observations whose Lorentz geometry |ζ| reaches this, and report both answers (default: 0.85 for rotation, 0 = single search). Reflections crossing the Ewald sphere near-tangentially are measured worst and can make a real symmetry operator look like a twin law. Where the two searches disagree, the merge of all the observations decides — as it always has for the systematic absences

--mosaicity <num>

Diagnostic: fix the scaling mosaicity (°) instead of using the per-image seed

--scaling-iterations <num>

Cap on the per-frame scaling iterations; the loop stops earlier once the scales settle, and a merge that hits the cap is flagged SCALING_NOT_CONVERGED (default: 100)

-z, --reference <file>

Reference data of the same crystal form — an MTZ or a PDB structure-factor mmCIF (-sf.cif), gzipped or not, recognised by content; --reference-mtz is the same option: fixes the space group, its setting and the cell, resolves the indexing ambiguity, hands over the R-free set and reports CCref. Not a scale anchor

--free-flags <file>

Take only the R-free test set of this MTZ or structure-factor mmCIF - e.g. the deposited reflections of the --model - for the validation, the refinement and the merged files; nothing else of the file is used, so unlike -z it fixes no space group, cell or frame. Taken on the model’s axes where the merge matches the file’s intensities (R_FREE_FLAGS=, see Free set and model bias)

--reference-column <label>

Reference column to use, by MTZ label — an mmCIF under the labels gemmi cif2mtz gives it (default: auto — F-model, else IMEAN/I/…, else FP/FOBS/F)

--model <file>

Validate the merged intensities against this atomic model (PDB or mmCIF, gzipped or not; the format is taken from the file’s content) — R-work / R-free and maps (see Validating against a model). An experimental model is placed as a rigid body, and by molecular replacement where the rigid body does not place it; a prediction (AlphaFold or ModelCIF) goes to molecular replacement straight away (MODEL_PLACEMENT=). It also settles the frame the reflections are written in: the enantiomorph, and the indexing ambiguity where no -z did; another space group or the twin hypothesis’ subgroup it chooses is written beside the answer as <prefix>_mr.mtz/.cif. It does not change the processing: the merge is the same with and without it. A placed model is then refined against the merge it was placed on (<prefix>_refined_model.cif, <prefix>_refined_maps.mtz, <prefix>_blobs.json, REFINE_ keys) - seconds on a GPU, typically 2-15 minutes on the CPU - which decides nothing about the processing

--mr <file>

As --model, but placed by molecular replacement straight away, without trying the rigid body first: as many copies as the cell holds, in every space group the merge cannot tell apart and in the twin hypothesis’ subgroup. A prediction is trimmed to the residues of pLDDT 70 and above, and where the AlphaFold DB’s predicted-aligned-error JSON sits beside it under its own name it is cut into rigid domains; any other PDB or mmCIF is taken as an experimental structure, its polymer only (no waters, ligands, hydrogens or alternative conformers). A model of several chains is searched for as a whole and, beside it, one chain of each molecule in it by itself, and the better placement kept (MR_SEARCH_MODEL=). It may relabel the enantiomorph of the answer, and a different space group it chooses is written beside the answer as <prefix>_mr.mtz/.cif with the placed model <prefix>_mr_model.pdb. --mode mx only; not with --model

--no-refine

Do not refine the placed model (for debugging): by default a model that --model or --mr places is refined

--refine-solvent

Also build the solvent of the refined model: waters added at difference-map peaks and removed where the maps no longer hold them, waters and ions relabelled, and each site audited (the REFINE_SOLVENT_ keys and <prefix>_solvent.json). Off by default: the model is refined with its solvent as given, and the report says REFINE_SOLVENT=NOT_PERFORMED. Also with --mode refine

--no-refine-solvent

The default: no solvent build or audit (turns off an earlier --refine-solvent)

--write-process-h5

Also write the (large) _process.h5 when merging (default: only .mtz/.cif)

--developer

Write the full <prefix>_report.txt: the pipeline-internal keys and the long explanations the default report leaves out. Nothing is computed differently — the same report, rendered in full (see The results report)

--finalist-ledger

Report the full-resolution evidence for each space group the search considered, not only the one it adopted, and the twin-immune zone evidence of the adopted group’s 2-folds (report-only; the decision is unchanged). Both are read on a merge of the observations in P1 that only this option makes, so it costs one extra merge; rotation only, and not with a fixed centred -S

--export-unmerged

Write <prefix>_unmerged.mtz, an unmerged MTZ (POINTLESS column layout), for aimless / pointless. On by default whenever there is an output prefix. Rotation partials are summed into one full per reflection, and on a rotation merge I/SIGI are the merge’s own scaled fulls, those it rejected left out. Otherwise intensities carry the deterministic per-reflection corrections and nothing else — Lorentz and polarization in LP, sensor efficiency in QE, flight path in FLIGHT — while the partiality is not divided out and the per-image scale is not applied. Written in --mode mx and --mode scale, and with --no-merge. See The unmerged export

--no-export-unmerged

Do not write <prefix>_unmerged.mtz. It is the largest file a run produces, so a run whose observations are not going to another scaling program can skip it

--export-unmerged-partials

Write <prefix>_unmerged_partials.mtz, the integrated observations unscaled, each partial as its own row (one batch per image), for a reading program that sums and scales them itself (careless). Off by default, and independent of --export-unmerged

--export-observations

Stills diagnostic: write <prefix>_obs.mtz, every integrated observation of the written merge as one row - its signed excitation error, partiality, the run’s rocking width, raw I/σ and background, corrections, scale, the σ the merge weighted it with, the frame’s cell and orientation, and a bit for each merge test it fails (observations the merge drops included). Processing is unchanged

--dump-observations <file>

Diagnostic: write the unmerged fulls of every rotation 3D combine to <file> as text, for a comparison with XDS

Integration

Option

Description

--integrator <txt>

Spot integrator: gaussian (profile-fit, default) | empirical | boxsum (classical fallback)

--integration-radius <r>

Signal-box radius r1, or r1,r2,r3 (px). One value ⇒ r2=r1+2, r3=r1+4. Default: 4,6,13 on rotation data, 6,8,14 on stills (whose spots land wider), before --adaptive-integration-radius adjusts r1

--adaptive-integration-radius[=on|off]

Set the signal radius r1 from how wide this crystal’s spots actually are (default: on). On stills it measures instead how far the background ring should reach: on empty apertures of the pre-scan frames, the r3 (up to 14) whose ring best predicts the background under the signal disk. r1 is not the integration domain — that is the profile-fit grid — but it is the aperture the profile width is learned over, and a second moment over a disk of radius a saturates at a²/4, so at the default r1 = 4 the learned σ can never exceed 2 px and a broader spot is fitted with a profile the model cannot represent. The pre-scan reads r80, the radius holding 80 % of a spot’s flux, off isolated strong spots over a fixed 14 px aperture that owes nothing to r1, fits it against 1/d and evaluates it at 5 Å; then r1 = clamp(round(2·r80), 4, 6), r2 = r1 + 2, and r3 is taken so the r2..r3 background ring keeps the area it has at the default 4,6,13. The ceiling of 6 is pattern density: r2 also drives the neighbour-ownership radius and the ring’s inner edge, and past it a dense pattern starts losing reflections whose ring falls below six clean pixels. Ignored when --integration-radius is given. The widened radius applies to the final integration pass only — the two-pass geometry pre-pass keeps the radius the run started with, because the post-refinement fits the detector distance and beam to the observed reflection positions and those move with the signal disk. And where the widened radius leaves more than 1.1 % of the predicted reflections without a background ring — a pattern too dense for it — the final pass is re-integrated at the fixed 4 px radius, and the log says so. On compact spots it changes nothing; where the spots are wider it improves ⟨I/σ⟩ and R_meas

--integration-stencil <k>

Push the r2..r3 background ring out by k times the beam’s radial streak bandwidth·R_px, per reflection (default 0 = the fixed circular ring). A fixed ring otherwise ends up on a streaked reflection’s own tails at high resolution and measures them as background. Only the ring moves, and only radially — the r1 signal box stays a circle — and the growth is capped at 2·r3. The neighbour exclusion grows with it, so on a crowded pattern a few reflections can be left with too little background and dropped. On a monochromatic beam the streak is zero and this does nothing

--background-clip <n>

High-side clip of the background ring at mean + n·√mean (default 4, whatever the bandwidth; 0 = off). The default background estimator — it rejects neighbour cores and zingers without the symmetric trim’s Poisson skew bias. Ignored by --integrator boxsum

--background-trim <f>

Use a symmetric trimmed mean for the background ring instead of the clip, 0≤f<0.5. Switches --background-clip off. A symmetric trim is biased low on Poisson data and adds a few counts to every partial, so this is for comparison with older results only; 0 = plain ring mean. Rings holding more than 512 pixels use the plain mean, which the default radii never reach but wide ones do

--background-radial[=on|off|auto]

Correct the background ring for the curvature of the radial background (default auto). Disk and ring are concentric, so a background linear in position cancels between them and only curvature survives — which on a smooth ice ring can reach tens of counts on a single reflection. auto decides per run in the pre-scan, on empty apertures of the pre-scan frames: on stills it is applied to every image where it makes the ring predict the background of empty apertures better at all; on rotation data to every image where it takes at least 10 % of that error away, and otherwise only to images whose ice score shows a smooth powder ring (ice made of discrete crystallite spots leaves no such ring, and the correction makes the bias worse). Ignored by --integrator boxsum (no clip pass to take the curve from)

--integration-high-resolution <num>

High-resolution limit for prediction and integration. Omitted (or 0) means integration extends as far as the detector reaches — which is what the predictor can place on the detector anyway, since it rejects reflections that miss it. Set a value to integrate less than the detector offers

--max-hkl <n>

Predict reflections with |h|,|k|,|l| ≤ n (max 511). By default this is derived per crystal from the refined cell as ceil(max(a,b,c)/d_min) + 1, which is the exact bound: the predictor keeps only |q| ≤ 1/d_min and h = a·q, so no reflection can lie outside it and no candidate inside it is wasted on a shorter axis. Set it only to override that

--bandwidth <num>

Relative X-ray bandwidth FWHM (e.g. 0.01 for a 1% DMM). Default: the file’s value; where the file states none, the one the pre-scan measures from how much longer strong spots are along their radius than across it, used where it is significant; otherwise 0 (monochromatic). --bandwidth 0 forces a monochromatic beam

--overlap <txt>

What to do where two predicted reflections share signal pixels: off | reject | exclude (default exclude). A shared pixel belongs to the nearer centre; without this a crowded reflection reads high on a dense pattern. exclude drops the shared pixels from the profile fit, which renormalises itself, and keeps the reflection; reject instead drops the whole reflection when too little of its profile is cleanly its own. --integrator boxsum has no profile to renormalise, so only reject acts there

--overlap-minpk <f>

Least fraction of a reflection’s expected profile that must be usable for it to be kept (default 0.75, XDS MINPK). Governs both the fraction that must be readable — not masked, untrusted, in a gap or overloaded — in every profile mode, and, under --overlap reject, the fraction that must be cleanly its own. Under --integrator boxsum any unreadable pixel discards the disk outright and the reject fraction goes by disk area, which cuts harder

--flight-path <txt>

What the diffracted beam crosses between the sample and the detector: air (default) | helium | vacuum. A reflection arriving at angle α to the detector normal flies D/cos α instead of D, so it crosses more of the medium and reads low; the factor is exp(D/L·(1/cos α − 1)), with L the attenuation length of the medium from the NIST tabulation and D and λ as stated by the file — nothing in it is fitted. Nothing in NXmx, and no field of any master file Rugnux reads, describes the medium, so it cannot be auto-detected and is assumed; the report states which medium was assumed and what it was worth (FLIGHT_PATH, FLIGHT_PATH_WILSON_B). Nor can it be inferred from the implied transmission, which does not separate helium stations from air stations. In air the term is +1.5 % at α = 55° for 18 keV over 160 mm and several-fold below 5 keV, where stations use helium precisely because air is unusable; helium attenuates ~1/600 of air, and vacuum leaves intensities untouched he is accepted for helium.

--stills-window-sigmas <k>

Stills: half-width of the prediction window in units of the run’s measured rocking width - every frame predicts the reflections within k rocking widths of the Ewald sphere (default 2)

--prediction-mosaicity <num>

Diagnostic: fix the rocking width (deg) the prediction window opens to, leaving partiality on the per-image σ_M. The two are one number by default, so a σ_M that moves takes the integrated reflection population with it

Geometry overrides

Defaults are taken from the input file; override them to reprocess with a corrected geometry.

Option

Description

--beam-x <num>

Beam centre X (pixel). --beam-center-check still runs and can adopt its measured centre (§1.4)

--beam-y <num>

Beam centre Y (pixel). --beam-center-check still runs and can adopt its measured centre (§1.4)

--detector-distance <num>

Detector distance (mm). On stills it is then held: neither searched nor refined. Without it, stills search the distance and refine it with the cell - the reference cell (-C), or the one the frames index to de novo

--wavelength <num>

Wavelength (Å)

--pixel-size <num>

Pixel size (µm), for a file that does not state it (an XTC stream of an unknown camera)

--gain <num>

Detector units per photon, for input in detector units (SACLA, CXI, XTC, SMV, marCCD, SFRM, a CCD imgCIF and --crystfel-geometry input). Where the background resolves single photons (SACLA, CXI and --crystfel-geometry input) the frames are counted in whole photons as they are read; otherwise they are analysed in their own units and the gain enters where a photon count is assumed. The integrated intensities come out in photons either way. Default: measured on the background of a few frames (Serial XFEL inputs)

--saturation <num>

Pixel value from which a pixel is overloaded, in the units the frames are read in. Replaces the file’s limit and the one stills read off the frames

--crystfel-geometry <file>

Place the panels of an HDF5/CXI input by a CrystFEL geometry file instead of the file’s own metadata: module geometry, camera length, mask arrays and bad regions (optional; Serial XFEL inputs). Photon energy, camera length and - where the geometry names no mask array - the masks otherwise come from the data files (Cheetah CXI, SACLA) or the command line; gain and saturation are measured. Tilted panels, dimN layouts, per-panel data and detector shifts are refused

--module-geometry <file>

Where the detector’s modules are: an NXmx file with one NXdetector_module per module (what a run writes as <prefix>_modules.h5) or a CrystFEL geometry file whose panels are laid on the image. Overrides the input’s own

--module-placement <file.json>

Place the modules as a module placement file says (<prefix>_module_placement.json of an earlier run, the module_placement fragment of the broker’s dataset settings; Module placement file). Entries name modules by their readout pixel 0 and readout axes in the image as stored, after mirror_y (x0, y0, fast_axis, slow_axis: the words of the broker’s custom_geometry, which is before mirror_y); one that matches no module, one named twice, or a module left out, is an error

--panel-refine[=off|diagnose]

Stills on a detector of several modules: by default the geometry bundle adjustment places each module as a rigid block where that predicts held-out spots better - the whole placement must beat the given one, and each module keeps its move only where its own held-out spots are predicted better, the others staying where they were given. --panel-refine keeps every move the spots support, without these tests; =off keeps the modules as given (a CrystFEL .geom included). A placement used is written to <prefix>_modules.h5; on stills <prefix>_module_placement.json is written unless =off, also where every module was held. =diagnose also runs a set of tests on the placement and writes them to the log

--mask-good [<file>:]<dataset>[@<bits>] / --mask-bad [<file>:]<dataset>[@<bits>]

HDF5/CXI stills: a mask array in the frames’ stored layout, in <file> or in each data file; usable only where non-zero (or with all <bits>) / unusable where non-zero (or with any <bits>). Repeatable (Serial XFEL inputs)

--rot1 <num>

PONI detector rotation 1 (rad). On stills, --rot1 or --rot2 holds the tilt (not refined); without them stills refine the tilt where held-out frames agree

--rot2 <num>

PONI detector rotation 2 (rad)

--rot3 <num>

PONI detector rotation 3, about the beam (rad) — the one rugnux --mode calibration writes into its .poni, so a refined third rotation can be given straight back

--detector-mirror-y

The stored image is mirrored in Y relative to the frame the PONI angles are stated in

--detector-quarter-turns <0-3>

The stored image is turned by this many multiples of 90° about the beam relative to that same frame

--polarization <num>

Degree of polarization p (XDS FRACTION_OF_POLARIZATION = (1+p)/2), signed: positive for a horizontally polarized source, negative for a vertically polarized one; where the beam-stop pre-scan finds the background clearly suppressed in the other plane, the degree is applied in that plane instead. Default: what a miniCBF # Polarization line or a dTREK SOURCE_POLARZ states (a fraction f, read as p = 2f* − 1, so a laboratory tube’s 0.5 is unpolarized), and otherwise 0.99, an undulator value; bending-magnet and wiggler sources are typically lower (0.8–0.95), and neither ADSC SMV, marCCD nor NXmx files state it, so pass the beamline’s known value here

--rotation-scale <k>

Goniometer rotation scale: the stage turned k times the angle stored in the file (the commanded one). Applied to both passes, and overrides the scale Rugnux fits for itself Accepted 0.9-1.1.

\ No newline at end of file diff --git a/RUGNUX_DOWNLOAD.html b/RUGNUX_DOWNLOAD.html new file mode 100644 index 000000000..dedee814d --- /dev/null +++ b/RUGNUX_DOWNLOAD.html @@ -0,0 +1,7 @@ + Download Rugnux — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Download Rugnux

rugnux is one self-contained executable: no CUDA toolkit, no Qt, no service to run. Take the archive for your machine, unpack it into a directory of its own, and run it. The links point at the current release; the full list of what each release ships is on its release page.

Version 1.0.0-rc.186 · release notes · all releases

Linux

GPU, CUDA 12rugnux-1.0.0-rc.186-linux-x86_64-cuda12.tgz CPU onlyrugnux-1.0.0-rc.186-linux-x86_64-cpu.tgz Arm 64, GPU, CUDA 13rugnux-1.0.0-rc.186-linux-aarch64-cuda13.tgz

x86-64 with AVX2 (Intel Haswell / AMD Zen or newer), any distribution from RHEL 8 on. For the GPU: an NVIDIA driver, 525.60 or newer; no CUDA toolkit. Arm 64: NVIDIA GH200 and DGX Spark, glibc 2.39 or newer.

macOS

Apple Siliconrugnux-1.0.0-rc.186-macos-arm64-cpu.tgz

Apple Silicon (M1 or newer), macOS 13 Ventura or newer. CPU, with Bragg integration and molecular replacement on the Apple GPU; there is no CUDA on macOS. Intel Macs are not supported.

Windows

GPU, CUDA 13rugnux-1.0.0-rc.186-win64-cuda13.zip CPU onlyrugnux-1.0.0-rc.186-win64-cpu.zip

64-bit Windows with AVX (built and verified on Windows 11). For the GPU: an NVIDIA R580 driver or newer; no CUDA toolkit. Unpack the archive and run bin\rugnux.exe.

On a machine with an NVIDIA GPU take the GPU archive: it is the only one that uses the card, and it also runs on a machine without one (it reports zero CUDA devices and takes the CPU path). The CPU only archive is smaller and for machines that will never have a GPU. A V100 needs the CUDA 12 build; the CUDA 13 builds start at Turing (T4). The driver versions and the GPU generations each build covers are in Release contents.

After downloading

The archive has no top-level directory: it unpacks straight into bin/ and share/, so always give it a directory of its own.

mkdir -p ~/rugnux
+tar xzf rugnux-<version>-linux-x86_64-cuda12.tgz -C ~/rugnux      # Linux, macOS
+~/rugnux/bin/rugnux                                               # prints the usage
+

On Windows, extract the .zip into a folder and run bin\rugnux.exe from a terminal. On macOS the binary is signed and notarized; the first run of a freshly downloaded copy checks the notarization online.

Nothing is written outside that directory, nothing needs root, and several versions can sit side by side; to remove one, delete its directory. Put bin/ on your PATH to type rugnux rather than the full path, then:

rugnux dataset_master.h5
+

Rugnux takes it from there: what the run writes, what the terminal shows and the few options worth knowing.

Linux packages

On RHEL / Rocky 8 and 9 and Ubuntu 22.04 / 24.04, rugnux is also a package of its own in the package repositories, which keeps it current with the system’s package manager:

sudo dnf install rugnux          # RHEL / Rocky
+sudo apt install rugnux          # Ubuntu
+

The package depends on nothing from the acquisition side and installs /usr/bin/rugnux. The repository’s CUDA variant keeps cuFFT as a system dependency, where the archive above links it in; either works on the same machine.

From source

cmake -S . -B build -DJFJOCH_RUGNUX_ONLY=ON builds rugnux alone, on Linux, macOS and Windows, with every dependency fetched during the first configure. The flags that match the released binaries, and what a build needs on a Mac, are in Installing Rugnux ▸ Building from source.

Memory and hardware

A run wants host and GPU memory in proportion to the number of reflections it integrates, not to the detector: 16 GB of RAM and a 6 GB card for an ordinary sweep, 32 GB and 8 GB for the largest measured, and far more for a very large unit cell. The sizing table and the flags that lower it are in Installing Rugnux ▸ Memory.

\ No newline at end of file diff --git a/RUGNUX_FORMATS.html b/RUGNUX_FORMATS.html new file mode 100644 index 000000000..b8045d6e1 --- /dev/null +++ b/RUGNUX_FORMATS.html @@ -0,0 +1,9 @@ + Input formats — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Input formats

Which data rugnux opens, before anything is typed. The short answer: an HDF5 master (NXmx or DECTRIS, from any facility), a PILATUS miniCBF sweep, a marCCD sweep, an SMV sweep (ADSC or Rigaku d*TREK) or a Bruker SFRM sweep, and for serial stills the files of the XFEL pipelines (below) — nothing else is read, so any other format has to be converted to one of these first. An atomic model and a reference reflection file may be given among the inputs too, told from the images by their contents.

Input is files, never a directory: an HDF5 master file, or one frame of a PILATUS miniCBF, marCCD, SMV or SFRM sweep. For rotation data one input is one sweep of one crystal. Several sweeps of one crystal may be given at once — several rotation masters, or one frame of each frame-file sweep, all of one format and at one wavelength — and are then merged as one dataset by default: each sweep is processed on its own first and the sweeps are scaled and merged together, into <prefix>.*; --sweeps separate processes each alone instead, into <prefix>_s<k>_*. Multi-sweep processing is experimental and not fully tested; how the sweeps are told apart and joined is described under Inputs. Sweeps processed separately are merged downstream from their own _unmerged.mtz files (see Taking the data onward).

Stills are given as all the files of the dataset, which the shell expands from a glob and which are read in the order given: rugnux run1_master.h5 run2_master.h5 (or rugnux *_master.h5) for several Jungfraujoch/NXmx collections of one setup, rugnux run*.h5 for SACLA, rugnux *.cxi for a Cheetah CXI set and rugnux *.xtc for LCLS streams. Several files must all be of one format; a directory is refused.

  • HDF5 master (NXmx-based) — a file written by jfjoch_writer, a DECTRIS EIGER master, or an NXmx master written by another facility’s toolchain. Lengths are taken in the unit the file declares, the image size from the image array’s own shape, and each data file’s images at the path the master’s own link names, so masters that state single values as one-element arrays, compose their images as a virtual dataset over the master itself, or keep them somewhere other than /entry/data/data all open. Where the NXmx spellings are absent the pre-NXmx ones are tried, so a DECTRIS firmware 1.x master opens too, goniometer included. Images may be bitshuffle+LZ4/Zstd or the HDF Group’s plain LZ4 (filter 32004); any other filter is named in the error. The sample temperature (/entry/sample/temperature) is read in the unit the file declares - K, or Celsius (degC, C) converted to K; no declared unit means K, an unknown one is warned about and the temperature not read. It goes into the mmCIF (_diffrn.ambient_temp, K) and the SHELX .ins (TEMP, °C). The other formats record no sample temperature, so their runs write neither: SHELXL then assumes its default of 20 °C, and for a cryo-cooled crystal TEMP has to be added to the .ins by hand (see Small-molecule structures).

  • PILATUS miniCBF sweep — one frame per file, read natively with no conversion and no libcbf. Name any frame of the sweep and the whole sweep is processed: the frames are the ones matching that frame’s template (prefix plus digit count), so a directory holding two sweeps is not spliced into one crystal. The geometry, the rotation axis and the detector mounting come from the header, including the imgCIF axis table where the header carries one (see Detector geometry). A raw CBF carries no analysis results, so --mode scale — which re-scales the reflections stored in a _process.h5 — does not accept one. Gzipped frames (.cbf.gz) are read directly, with no decompression step: EMBL Hamburg’s beamlines write that form by default, and expanding a sweep first would double the disk it needs. The two forms count as separate sweeps.

  • marCCD sweep — what Rayonix MX-series and mar Mosaic detectors write, and what a decade of deposited CCD data is archived as: an uncompressed TIFF with the instrument header in the gap before the pixels. One frame per file, read natively. Naming a frame selects the sweep exactly as for miniCBF, under either naming scheme these detectors use — a numbered stem (xtal_1_00042.mccd) or the frame number as the file extension (D1.042). The distance, beam centre, pixel size, wavelength and the circle that turned come from the header; the rotation axis’ direction does not, because the format has nowhere to state it, so the run settles its sign from the data as it does for a miniCBF that carries no axis table. A CCD frame marks no untrusted pixels, so the sweep starts with nothing masked. Like a raw CBF, it carries no analysis results and --mode scale does not accept one.

  • SMV sweep — what ADSC Quantum detectors wrote and what Rayonix and others still write, so most archived CCD data from the 2000s is in this form: an ASCII KEY=value; block between braces, then the pixels. One frame per file, read natively, the sweep selected exactly as above. The beam centre it states is in millimetres and is converted here; its convention varies between writers, and a file that states it transposed indexes nothing until the run’s own beam-centre measurement replaces it, which it does automatically. The saturation value is read where the header states one (CCD_IMAGE_SATURATION or SATURATED_VALUE); where it does not, overloads are judged on the 16-bit container alone and the reader says so once per sweep. Rigaku d*TREK headers — what Saturn CCDs on rotating-anode home sources write, recognised by their DETECTOR_NAMES key — are read in their own vocabulary: the pixel size and the point of normal incidence from the spatial-distortion record, the image directions from the detector and distortion vectors (so a mirrored or turned image keeps its hand), the distance and the detector circles, including a swung 2θ arm, from the detector goniometer, the spindle and its angles from the rotation record, and the wavelength from the scan record. Pixel values above 32767 are the format’s encoded overflows and are expanded with the header’s compression ratio.

  • Bruker SFRM sweep — what SMART, PROTEUM and APEX write (.sfrm, header formats 86 and 100): one frame per file, read natively, the sweep selected as above; a Bruker collection directory holds one run per scan, and each run is its own sweep. The scan axis and the other circles (2θ, ω, φ, χ), the distance, beam centre, pixel size, wavelength and saturation come from the header; the overflow and underflow tables are expanded and the baseline offset subtracted. Like the other raw frames it carries no analysis results and --mode scale does not accept one.

Support for the CCD formats — marCCD, SMV and Bruker SFRM — is very limited and provided as-is; they are read so that a CCD sweep does not need a conversion step to be processed. Only the header fields named above are read, and the headers vary by site and vintage, so no promise is made that every writer’s dialect opens. The HDF5 and miniCBF paths are the maintained ones.

Serial XFEL inputs

Stills from the XFEL serial-crystallography pipelines are read straight from the files those pipelines write, without a geometry file. Each reader takes from the file what it states; what the file does not state is either measured by rugnux or given on the command line. Every run is read at one wavelength (the mean of the per-shot photon energies where the file states them), the beam centre is measured (the file’s centre, the background-isotropy measurement and the point-symmetry capture are indexed on a sample of frames and the best is kept), and a SACLA or CXI file that states no gain is read at the gain its background shows. Where the pixel values resolve single photons (a JUNGFRAU file in keV, an AGIPD file) the gain is the spacing of their photon peaks, so a baseline the file left in does not hide it, and the detector is a photon counter: its frames are counted in whole photons as they are read. Otherwise (a CCD, an MPCCD, a Rayonix) the gain is the background’s variance per unit mean and the frames are analysed in the units they are stored in: the gain enters only where a photon count is assumed (the spot finder’s threshold, the background clip, the integrated intensities’ variances, which come out in photons). --gain gives the value; the background still says which of the two the detector is. Float frames analysed in their own units are rounded to whole ones. The saturation level is read off the frames where the file states none.

Format

Read from the file

Measured by rugnux

Given on the command line

Cheetah HDF5 with per-shot groups and a panel table (/tag-N/data, sensors stacked in one frame, their placement in /metadata - as SACLA writes for the MPCCD)

the sensors’ positions and in-plane angles, pixel size, nominal camera length and pixel mask (/metadata); each shot’s photon energy

beam centre, gain, saturation; with a cell, the camera length (the stated one is nominal) and each sensor’s placement

nothing; --detector-distance to give the camera length

Cheetah CXI, single-panel detector (/entry_1/data_1/data, square frames, e.g. a Rayonix at PAL-XFEL)

pixel size, photon energy per shot, camera length, mask_shared

beam centre, gain, saturation; with a cell, the camera length

--detector-distance to hold a camera length

LCLS-I XTC, Rayonix (Camera::FrameV1 events; one or more streams)

photon energy per event (electron-beam record), pixel size (Rayonix model and binning), the camera’s pixel offset

beam centre, saturation; with a cell, the distance

--detector-distance without a cell (not recorded in XTC); --pixel-size/--wavelength only where the XTC lacks them

The SACLA sensor positions in /metadata are the detector’s nominal metrology, a few pixels from a per-beamtime refined geometry; the stills geometry refinement places each sensor as a module (see Module geometry).

What is refused, with a message rather than a wrong answer:

  • a Cheetah CXI file of a tiled detector (CSPAD, AGIPD, ePix, JUNGFRAU, MPCCD stored as a slab of panels): the file does not say where the panels lie;

  • multi-panel XTC (CSPAD, ePix, JUNGFRAU at LCLS), stored raw with per-module calibration, and an XTC stream holding images of the same size from two cameras;

  • unconverted detector data in general (raw ADC values with gain stages and pedestals);

  • per-shot wavelengths: they are averaged, never followed shot by shot;

  • files of one run that store their frames differently (size, type, compression) or place the sensors differently.

Damaged or compressed XTC images are left out, and so is a last event that a partly downloaded stream ends inside. An XFEL dataset that has already been assembled into single images in an NXmx master opens like any other HDF5 input.

--crystfel-geometry <file> places the panels of an HDF5/CXI input by a CrystFEL geometry file. Taken from it are the module geometry (panel pixel ranges, fast/slow directions, corners, pixel size, per-panel coffset, the frames’ data path), optionally the camera length, and the pixels to leave out: the mask arrays (mask, mask_file, mask_good, mask_bad, or up to eight as maskN_data, maskN_file, maskN_goodbits, maskN_badbits; a panel may state its own), the bad regions (bad*, a box in the laboratory plane or a pixel range on a panel), mask_edge_pixels and no_index. A mask dataset with one plane per frame, or with % in its path, is applied frame by frame. A relative mask_file is looked for in the working directory, as CrystFEL does, and then beside the geometry file. Where the geometry names mask arrays, the data file’s own (the CXI mask_shared and per-shot mask, a panel table’s /metadata/pixelmask) are not taken: the geometry says which bits matter. Everything else it may hold (gain, saturation, photon energy, value flags) is ignored, with a note in the log. DIALS .expt files are not read.

A mask array the data files do not hold themselves - e.g. a per-run pixel mask beside the frames - is given with --mask-good [<file>:]<dataset>[@<bits>] (a pixel is usable only where the array is non-zero, or has all of <bits>) or --mask-bad [<file>:]<dataset>[@<bits>] (unusable where non-zero, or where it has any of <bits>, e.g. @0xfeff), in the frames’ own layout, as stored. Without <file> the dataset is read from each data file - a per-frame mask stored beside the frames. Both may be given more than once, and add to the masks the data files or the geometry file state (the CXI mask_shared and per-shot mask, the /metadata/pixelmask of a panel-table file, a --crystfel-geometry file’s masks). A gain the background shows at or below one detector unit per photon is taken as one.

Module geometry

A detector of several modules is described module by module: where each module’s pixels are in the image rugnux reads, and where they really are on the detector plane. The modules come from an explicit geometry, never from the image:

  • an NXmx file with one NXdetector_module group per module (/entry/instrument/detector/module_0, module_1, …: what a run writes as <prefix>_modules.h5, and how the masters Jungfraujoch writes state a multi-module JUNGFRAU);

  • the panels the XFEL readers know (the SACLA sensors from /metadata, the panels of a --crystfel-geometry file); each panel is put on the image whole, at a whole pixel, and its fraction of a pixel and small turn are its placement;

  • --module-geometry <file>: an NXmx file with such groups (what a run writes as <prefix>_modules.h5) or a CrystFEL geometry file whose panels are laid on the image (fs = column, ss = row, corners relative to the beam). It replaces the input’s own modules - the way to give the module layout of a master written before the modules were recorded.

Spots are mapped from the image onto the plane, and predictions from the plane back onto the image for integration, so the image itself is never re-assembled. With a cell given, the stills geometry refinement can place each module with enough spots on its frames’ lattices as a rigid block (shift and in-plane turn; --panel-refine=off keeps them where they were given, a CrystFEL .geom’s panels included) where that predicts held-out spots better, module by module; modules move only relative to one another, the beam centre, distance and crystal orientations carrying what all of them share. The placement is used from there on, and written to <prefix>_modules.h5 (read back with --module-geometry); on stills of a detector of several modules <prefix>_module_placement.json is written whenever placement is not turned off - also where every module was held, as given being a placement too - read back with --module-placement and taken by the broker’s /start.

Module placement file (<prefix>_module_placement.json)

{
+  "module_placement": [
+    {"x0": 0, "y0": 1023, "fast_axis": "Xp", "slow_axis": "Yn",
+     "x0_plane": 0.31, "y0_plane": 1022.58,
+     "fast_step": [1.0, 0.0002], "slow_step": [0.0002, -1.0]},
+    ...
+  ]
+}
+

The file is a fragment of the broker’s dataset_settings (jfjoch_api.yaml, detector_module_placement), read and written through the same OpenAPI model the broker uses; the keys come in alphabetical order.

One entry per module, in pixels of the image as it is stored (for a JUNGFRAU: as the broker assembles it, after mirror_y; a pixel’s centre at its index):

  • x0, y0, fast_axis, slow_axis - the module’s readout pixel 0 (the first pixel of its fast/slow readout) as image x and y, and which way its fast and slow readout axes run in the image (Xp, Xn, Yp, Yn). They are the words of a broker’s custom_geometry, but in the stored image: with mirror_y on, y0 here is H - 1 - y0 there (H the image height) and Yp/Yn swap. For a module of a stored file they come from its NXmx module_NN group (data_origin, data_size, and the readout axes Jungfraujoch writes beside fast_pixel_direction/slow_pixel_direction; a group without them, or a panel of a CrystFEL geometry, is read along its own pixel array, Xp/Yp from its first pixel), or from how a reader turns a panel into the image. They name the module: entries match modules exactly by these four, not by their place in the list, and with the module size they give its box. rugnux’s log names modules the same way.

  • x0_plane, y0_plane, fast_step, slow_step - where the module lies on the detector plane: readout pixel (i, j) - i along the fast axis, j along the slow axis from pixel 0 - is at (x0_plane, y0_plane) + i fast_step + j slow_step. As assembled, x0_plane = x0, y0_plane = y0, and each step is the unit vector of its axis (Xp = [1, 0], Yn = [0, -1], …); the refinement’s fraction of a pixel and small turn are kept.

A placement is valid only for the image layout it was measured on. --module-placement <file> and /start refuse it, naming the module, where an entry matches no module of the image or a module has no entry - another detector size, other gaps, a binned image or a raw (unassembled) JUNGFRAU stream. The beam centre and distance are not in the file: they belong to each dataset (--beam-x, --detector-distance, or the /start settings), and the placement only moves the modules relative to one another.

With the broker, the file’s module_placement is merged into the /start dataset settings as it stands; /start answers 400 where it does not name exactly the detector’s modules. The image is still assembled as custom_geometry lays it out, at whole pixels; the placement goes into the start message and the master’s module_NN groups, and the broker’s own analysis uses it.

Spots are always found by rugnux itself, including for the two-pass rotation first pass — the spot lists a dataset may already carry were found online, at the acquisition’s threshold and with its ice-band spots already discarded, so reusing them would hide the spot-finding settings from the lattice search.

\ No newline at end of file diff --git a/RUGNUX_INSTALL.html b/RUGNUX_INSTALL.html new file mode 100644 index 000000000..90a439a60 --- /dev/null +++ b/RUGNUX_INSTALL.html @@ -0,0 +1,17 @@ + Installing Rugnux — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Installing Rugnux

rugnux is a single self-contained executable. It needs no CUDA toolkit, no Qt, and no Jungfraujoch service running anywhere; on a machine with an NVIDIA GPU it needs the NVIDIA driver, and without one it still runs on the CPU.

From the package repositories (RHEL / Rocky / Ubuntu)

On a distribution covered by the package repositories, rugnux is a package of its own:

sudo dnf install rugnux          # RHEL / Rocky 8 and 9
+sudo apt install rugnux          # Ubuntu 22.04 / 24.04
+

It installs /usr/bin/rugnux and depends on nothing from the acquisition side — no broker, no detector libraries, no Qt — so it can go on a machine that only processes data.

From the release archive

For a machine no package manager covers — or for Windows, macOS and Arm, which have no repository — take the archive for your architecture from the download page or the Gitea release page:

Archive

For

rugnux-<version>-linux-x86_64-cuda12.tgz

64-bit Intel/AMD Linux. Built on RHEL 8, so it runs on any newer Linux

rugnux-<version>-linux-aarch64-cuda13.tgz

64-bit Arm Linux — NVIDIA GH200 and DGX Spark. Built on Ubuntu 24.04, so it needs glibc 2.39 or newer. Tested on a DGX Spark (GB10)

rugnux-<version>-win64-cuda13.zip

64-bit Windows

rugnux-<version>-macos-arm64-cpu.tgz

macOS 13 (Ventura) or newer on Apple Silicon (M1 and newer). No CUDA on macOS: CPU, with Bragg integration, the model density and the molecular-replacement rotation function on the Apple GPU (Metal). Tested on an Apple M-series Mac mini. Intel Macs are not supported

The archive has no top-level directory — it unpacks straight into bin/ and share/. Always give tar a destination of its own, or it will scatter those into whatever directory you are in:

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
+/opt/rugnux-$VERSION/bin/rugnux            # prints the usage
+

The archive is 268 MB, about 45 s to download at 50 Mbit/s. Nothing else is installed.

What you get is:

bin/rugnux                                  the program
+share/doc/jfjoch_rugnux/LICENSE             GPLv3
+share/doc/jfjoch_rugnux/THIRD_PARTY_NOTICES.md
+share/doc/jfjoch_rugnux/ACKNOWLEDGEMENT.md
+share/doc/jfjoch_rugnux/licenses/           verbatim licence texts of the bundled dependencies
+

Nothing is written outside that directory, nothing needs root, and several versions can sit side by side. To remove it, delete the directory. Put bin/ on your PATH if you want to type rugnux rather than the full path.

macOS: the binary is signed with the project’s Apple Developer ID and notarized, so a .tgz downloaded with a browser runs without further steps; the first run of a freshly downloaded copy checks the notarization online. Unpacking into a directory under your home directory (~/rugnux-<version>) rather than /opt avoids needing sudo on a Mac.

Mixing the two. If a rugnux package is also installed, /usr/bin/rugnux will normally win on PATH. Put the archive’s bin/ first, or call it by its full path, to be sure which one you are running — rugnux prints its version on every run.

A first run

To check the installation, run the 9ZLO example of the Quick start: a 10.8 GB download from Zenodo, one command, about 20 s on a desktop GPU. The expected numbers are given there and in A first run in detail.

GPU support

The released Linux and Windows archives are CUDA builds (the macOS one is CPU-only). They need only an NVIDIA driver on the host — 525.60.13 or newer for the CUDA 12 archive, 580.65.06 or newer for the CUDA 13 ones — and no CUDA toolkit, because everything CUDA is linked statically. With no GPU or no driver, rugnux reports zero CUDA devices and falls back to the CPU path, which works but is far slower: the FFT search runs on FFTW and ffbidx on its CPU implementation, and the refinement of a placed model takes minutes rather than seconds. A V100 needs the CUDA 12 archive; which generations each build covers is in Release contents ▸ GPU generations and the NVIDIA driver.

Building from source

rugnux alone, without the server stack or Qt:

cmake -S . -B build -DJFJOCH_RUGNUX_ONLY=ON -DCMAKE_BUILD_TYPE=Release \
+      -DCMAKE_CXX_FLAGS="-march=x86-64-v3" -DCMAKE_C_FLAGS="-march=x86-64-v3"
+cmake --build build -j$(nproc) --target rugnux
+

On RHEL / Rocky 8 the system GCC 8 configures but cannot build it (CUB requires at least C++17): install gcc-toolset-13, run source /opt/rh/gcc-toolset-13/enable before cmake, and start from a fresh build directory if one was configured with GCC 8. The binary lands in build/rugnux/rugnux. No library has to come from the system: every dependency is downloaded and built during the first configure, which therefore needs network access. cmake --build build --target package produces the same .tgz the release ships. The build system sets no -march flag of its own, so a plain build is slower than the released one on the CPU-bound stages but gives the same results: floating-point contraction is off, so the x86 level a binary targets changes its speed and not its answer.

On a Mac (Apple Silicon), leave the two -march flags out — they name an x86 level; the Apple compiler’s default target is already the M1 — and use sysctl -n hw.ncpu for the job count. The build has no CUDA there and needs nothing installed beyond Xcode and CMake; its Bragg integration, the model density and the molecular-replacement rotation function run on the Apple GPU through Metal (GPU data analysis ▸ Apple GPUs).

Hardware

As with the rest of Jungfraujoch, serious performance requires an NVIDIA GPU. The CUDA build provides the GPU fast-feedback indexer (ffbidx) and the GPU FFT indexer (cufft); without CUDA ffbidx runs on its CPU implementation and -X fft on the CPU fftw indexer. With a GPU present most of the per-image pipeline runs on the device — bitshuffle+LZ4 decompression, miniCBF byte-offset decoding and marCCD widening, image preprocessing, azimuthal integration, spot finding, prediction and Bragg integration — as do the pre-scan (beam-stop mask, background beam-centre fit, spot widths, defective pixels; one accumulator per card), rotation scaling and merging from the ingest of the reflections onwards (sorting and the resolution cut included) with its correction surfaces, and --model: the structure factors, scale fits and rigid-body placement of the validation, the rotation and translation functions of molecular replacement, and the refinement of the placed model. The CPU implementations are the path where there is no GPU, and the two agree to rounding rather than bit for bit (parts of the scaling and the model fits round differently on the card), so a GPU and a CPU run can differ in the last digits of the merged data. The choice is automatic; a CUDA build runs on the CPU when told to (rugnux --no-gpu ...). The thread count (-N) governs the CPU side of all of it.

The released CUDA builds need only an NVIDIA driver on the host, no CUDA toolkit: 525.60.13 or newer for the CUDA 12 artefacts (RHEL 8 packages, the x86_64 rugnux archive) and 580.65.06 or newer for the CUDA 13 ones (RHEL 9, Ubuntu, the aarch64 and Windows rugnux archives). Which GPU generations each artefact supports — a V100 in particular works only with the CUDA 12 build — is in Release contents ▸ GPU generations and the NVIDIA driver.

Memory

A run’s memory is set by how many reflection observations it integrates, not by how many pixels the detector has. Measured at -N 6 over rotation sweeps of 1200-1800 frames:

Detector

Observations integrated

Host (peak RSS)

Device

1679 x 1475 (2.5 MP)

25 M

7.8 GB

3.8 GB

2527 x 2463 (6.2 MP)

13 M

4.9 GB

3.1 GB

3262 x 3108 (10.1 MP)

7 M

2.5 GB

3.0 GB

4371 x 4150 (18.1 MP)

13 M

4.3 GB

3.2 GB

4371 x 4150 (18.1 MP)

20 M

6.0 GB

4.4 GB

3262 x 3108 (10.1 MP)

50 M

14.2 GB

7.0 GB

Two sweeps on the same detector differ by a factor of five, so size the machine on the observation count rather than on the detector. As a rule, 0.6 GB + 0.3 GB of host memory per million observations, and 2.4 GB + 0.1 GB of device memory per million. The run reports what it actually integrated — RotationScaleMerge: ingested ... partial observations. 32 GB of host RAM and an 8 GB card cover every dataset in the table at -N 6; an ordinary sweep needs 16 GB and 6 GB. The device column is an upper bound.

Both peaks fall in scaling and merging, not in the per-image loop: the loop alone stays under 3.2 GB on the device at -N 6, whatever the detector. The stage that needs the most is the 3D combine.

-N multiplies the per-image loop only — about 8 bytes of device memory per detector pixel per worker on top of a fixed 2.6 GB, linear with no ceiling: an 18 MP sweep takes about 3 GB of device memory at -N 6 and 8 GB at -N 32. Host memory does not move with -N, and neither does the merge’s own device memory. Where several runs share one card, -N is the knob that decides how many fit.

To use less:

  • -N — the only flag that lowers the per-image loop’s device memory. Lowering it is what rescues a run on a card that is otherwise full.

  • --no-merge — roughly halves both peaks. It also gives up the merged output.

  • --no-export-unmerged does not save memory. <prefix>_unmerged.mtz is the largest file a run writes, but its observations are resident either way; the flag saves disk, not RAM.

Nothing measures the free memory on the card before allocating. The steps that can be too large for a card decide between GPU and CPU before they touch it, from the card’s total memory, so the same input on the same card always takes the same path: rotation scaling and merging runs on the CPU where it would take more than 80% of the card (and logs ... scaling on the CPU instead), --model validation and molecular replacement place each of their parts on the GPU or the CPU against a budget of 80% of the card, the beam-centre FFT runs on the CPU where it would take more than half of it, and on a small card the per-image workers are fewer. Past those decisions a run that does not fit degrades where it can — device decompression falls back to the host, the beam-stop projection falls back to the host, an indexer thread that cannot allocate reports the frame as not indexed — and fails the run otherwise, with Processing failed: CUDA (GPU) error (Failed to allocate device memory) and a non-zero exit status. A run is never silently short; it either completes or fails. On a GPU shared with another job, lower -N or wait for the card.

Very large unit cells

The rule above holds for the cells in that table, and a very large cell sits far beyond it. A long axis, a dense pattern and many frames multiply together: each frame predicts more reflections, each reflection is split over more frames, and tens of millions of partial observations are normal for a big cell. The 400 Å virus capsid of the README’s demo (PDB 4NWV) peaks at about 20 GB of host memory on a GPU build. A CPU-only build keeps in host RAM what a GPU build keeps on the card, so it is the one that needs the large machine. When such a set is too large for GPU scaling on the card, the run scales and merges it on the CPU instead, with a warning in the log — and then wants that much host memory for that step.

Out of host memory

Nothing estimates the host memory a run will need before it starts, so a set that does not fit runs until the memory is gone, and then ends in one of two ways.

Where the allocation is refused — under an address-space limit (ulimit -v, which some batch systems set), with strict overcommit, or for one request larger than the machine could ever grant — the run stops with

Processing failed: out of host memory (std::bad_alloc) - this data set needs more RAM than is available
+

and a non-zero exit status. The CUDA driver reserves a large address space of its own, so a GPU build under a tight ulimit -v can stop before reading anything, with CUDA (GPU) error (out of memory).

More often on Linux the allocation succeeds and the memory runs out as it is used. The kernel’s OOM killer then ends the process with SIGKILL, which no program can catch: the run stops with no message of its own, the shell prints Killed (exit status 137), and dmesg or the batch system’s log has an Out of memory: Killed process line. A job capped by a cgroup memory limit ends the same way. A run that disappears like this needs more RAM than the machine or the job was given, exactly as if it had said so. --no-merge lowers the host peak, as above; otherwise the run needs a larger machine.

\ No newline at end of file diff --git a/RUGNUX_INTEGRATION.html b/RUGNUX_INTEGRATION.html new file mode 100644 index 000000000..103fa97c5 --- /dev/null +++ b/RUGNUX_INTEGRATION.html @@ -0,0 +1,80 @@ + Rugnux with other programs — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Rugnux with other programs

What the reflection files promise to a reading program, and the minimum commands that get each downstream suite running on Rugnux output.

Reflection-file conventions

mmCIF. Standard items carry their standard meanings — _refln.intensity_meas / _intensity_sigma, the pdbx_I_plus/pdbx_I_minus and pdbx_F_plus/pdbx_F_minus anomalous pairs, _reflns.* and _reflns_shell.* for the merging statistics, _reflns.B_iso_Wilson_estimate for the Wilson B, and _cell.* / _diffrn_radiation_wavelength.wavelength for the geometry. On rotation data _cell.*_esd carries the cell’s standard uncertainties (. for a parameter the symmetry fixes) and _cell_measurement.reflns_used / theta_min / theta_max the reflections they were measured on (see Cell e.s.d.s).

Anything Rugnux reports that has no standard item is written under a jfjoch_ prefix, inside the standard category it belongs to. That is a deliberate choice: a reader that does not know these items ignores them, and one that does can find them without guessing.

item

meaning

_reflns.jfjoch_diffrn_ISa

Asymptotic I/σ in XDS’s sense: the whole-range 1/√(a·b) of the error model, so it can be read directly against a CORRECT.LP. Rotation only: a stills merge writes the error-model terms instead

_reflns.jfjoch_diffrn_ISa_asymptotic

The strong-reflection tier — the counting-subtracted scatter of well-measured groups. XDS has no equivalent, and it can only ever be the more optimistic of the two. Rotation path only

_reflns.jfjoch_error_model_a, _b

The error model in XDS’s convention, σ² = a(σ₀² + b·I²), so the ISa above is re-derivable from the file rather than taken on trust

_reflns.jfjoch_error_model_c

Stills only: the partiality term, σ² = a(σ₀² + b·I² + c·((1−p)/p)²·I²) with p the observation’s partiality

_reflns.jfjoch_second_moment_I

Twinning second moment ⟨I²⟩/⟨I⟩² — 2.00 untwinned, 1.50 for a perfect twin

_reflns.jfjoch_L_test_mean_abs_L, _L_test_mean_L_squared

Padilla–Yeates L-test. ⟨|L|⟩ is 0.500 untwinned / 0.375 for a perfect twin; ⟨L²⟩ is 0.333 / 0.200. Written only when the test found pairs

_reflns.jfjoch_radiation_damage_relative_B

Relative B from the first to the last rotation batch (Ų); positive is the usual direction, high-resolution intensity fading with dose

_jfjoch_radiation_damage_batch.*

Per-batch loop: id, rotation_start_deg, relative_B

_diffrn_detector.jfjoch_distance_mm, _jfjoch_beam_center_x_pxl, _jfjoch_beam_center_y_pxl

The refined detector geometry actually used, which is not otherwise recoverable from the reflection file

_reflns.pdbx_aniso_B_tensor_eigenvalue_1..3, _pdbx_aniso_B_tensor_eigenvector_*

The anisotropy tensor, eigen-decomposed. Eigenvalues are relative to the weakest direction (so the third is 0 and the first is the anisotropic ΔB), because only the deviatoric part is determined; eigenvectors are in the PDB orthogonalisation convention. Not written for a cubic Laue class, where symmetry forces ΔB to be zero

_reflns.jfjoch_aniso_delta_B, _jfjoch_aniso_delta_B_linear

The anisotropic ΔB, and the part of it that actually follows exp(−½ sᵀBs). The second is what the verdict is gated on

_reflns.jfjoch_aniso_d_min_1..3

Diffraction limit (Å) along each principal direction. A comment marks a value that is the edge of the measured data rather than the crystal’s own limit

_reflns.jfjoch_aniso_shape, _jfjoch_aniso_floor, _jfjoch_aniso_significance, _jfjoch_aniso_verdict

The resolution signature of the deficit, the data set’s own systematic-error floor, ΔBlinear over that floor, and the resulting verdict. Each carries its vocabulary as a comment

SHELX HKLF 4 (<prefix>.hkl). Fixed-format 3I4,2F8.2 — h k l I σ(I), terminated by a 0 0 0 record — which is what SHELXL, SHELXC, SHELXD and ANODE expect. It is written with a SHELX instruction file, <prefix>.ins, beside it: CELL, ZERR (Z and the cell’s e.s.d.s, measured on rotation runs and written as 0 where they were not, as on stills or in --mode scale; SHELXL stops with ** ZERR MISSING ** without the line), LATT and SYMM, and a placeholder SFAC/UNIT (see Small-molecule structures). No line is longer than the 80 characters SHELXL accepts. Two properties of the .hkl worth knowing before using it:

  • On rotation data it is unmerged: one record per full reflection (its partials summed), with the per-frame scale and every correction applied and the σ(I) the merge weighted it with, but not averaged with its symmetry equivalents, and at the index it was measured at — the chemical crystallographer’s convention, so SHELXL computes Rint and Rsigma itself and Friedel mates keep their own records. Observations the merge rejected as outliers or left out for an overloaded pixel, and those beyond its resolution cut, are not in the file. There is no batch number column (in HKLF 4 that selects a BASF scale factor). A stills run writes the merged reflections instead, Bijvoet mates at +hkl and -hkl.

  • Intensities are rescaled by a single global factor so the largest |I| or σ(I) is 9999.00: nothing overflows the F8.2 field, a negative intensity included. I and σ(I) share that factor, so every ratio — and therefore the anomalous signal — is untouched, but the absolute scale is not meaningful. This matters only if you intend to compare magnitudes with another file; SHELXC and ANODE use ratios alone.

MTZ (<prefix>.mtz). The CCP4 anomalous layout, with the column types CCP4 programs dispatch on:

H K L IMEAN SIGIMEAN I(+) SIGI(+) I(-) SIGI(-) F SIGF F(+) SIGF(+) F(-) SIGF(-) FreeR_flag
+H H H    J        Q    K       M    K       M  F    Q    G       L    G       L          I
+

F is the French–Wilson amplitude. The header carries the determined space group, the refined cell and the wavelength, on a dataset of its own behind the reserved HKL_base, which is where the MTZ format puts them. <prefix>_unmerged.mtz reads 1.54187 Å (CCP4’s Cu Kα default) under mtzinfo and is not wrong: its columns sit on HKL_base deliberately, as POINTLESS expects, and the wavelength AIMLESS and POINTLESS read is the per-batch one, which is correct. The Bijvoet columns are present on any rotation merge, with or without -A; a stills merge keeps the hands apart only under -A, and without it the file stops after F SIGF FreeR_flag.

There is deliberately no DANO/SIGDANO pair, the anomalous difference columns a CCP4 merged file usually carries. They are a restatement rather than a measurement: DANO is F(+) − F(-) and SIGDANO is √(σ(+)² + σ(−)²), the quadrature sum being the convention whether or not the two mates came from one scale model. Every program in the phasing routes below reads the Bijvoet columns directly and forms the difference itself, and CCP4’s own phasing engines prefer them: bp3 and afro want F+/SF+/F-/SF- and tell a user holding F/DANO to convert to that form, and mtz2sca ranks I(+/-) over F(+/-) over F/DANO. Where the pair is genuinely wanted — fft’s anomalous-difference Fourier takes a DANO label and has no other spelling — one command makes it, with the ISYM column that belongs beside it:

ctruncate -hklin myrun.mtz -hklout myrun_ct.mtz \
+    -colin '/*/*/[IMEAN,SIGIMEAN]' -colano '/*/*/[I(+),SIGI(+),I(-),SIGI(-)]'
+

The unmerged export

<prefix>_unmerged.mtz holds the observations unmerged, in the column layout POINTLESS writes and aimless, pointless, careless and iotbx.merging_statistics read. It is written by default, in --mode mx and --mode scale alike and with --no-merge as well, and it replaces nothing — Rugnux still writes its own merged files in the same run. It needs an output prefix (-o). It is the largest file a run produces, larger on a dense rotation dataset than the merged .mtz, .cif and .hkl put together, so a run that only wants the merged numbers — a regression battery, or a throughput pipeline — turns it off with --no-export-unmerged.

Use it to scale the data with a different program, to have pointless give an independent opinion on the space group, or to compare Rugnux’s merge against another one on identical input. Each sweep’s file is self-contained, so several of them can be handed to pointless and aimless as separate HKLINs to merge sweeps Rugnux processed separately (--sweeps separate).

Trap when combining a wild-carded series. For an HKLIN given with wild-cards, POINTLESS accepts the files in order and terminates acceptance at the first file out of chronological order, then merges what it kept and prints a plausible result. Its own keyword lifts the check — ALLOW OUTOFSEQUENCEFILES — or name each file as its own HKLIN, which is not a series; either way, check the file count in its log against the number you meant to give.

Columns. H K L M/ISYM BATCH I SIGI FRACTIONCALC XDET YDET ROT LP QE FLIGHT FLAG — POINTLESS’s own set down to FLAG, plus QE and FLIGHT (the sensor-efficiency and flight-path divisors described below; QE is DIALS’s column) — then four Rugnux extras, DELPHI (offset from the centre of the rocking curve), ZETA (the Lorentz geometry of that curve), BGMEAN and BGVAR (the background that was subtracted, and its variance). BATCH is the image ordinal plus one, and a batch header is written for every batch that carries an observation. M/ISYM records both the symmetry operation and the Friedel hand, so the index as measured is recoverable from the index as stored.

Header symmetry and order. The file’s MTZ header carries the space group the run determined (P1 where none was), and the rows are sorted on H K L M/ISYM BATCH — the order POINTLESS leaves an unmerged file in, and the order AIMLESS requires of its input — so both programs take the file directly.

Scaled, on a rotation merge. Where the merge ran on a rotation sweep, I and SIGI are those of the merge’s own fulls - every correction, the partiality and the scale applied, and the sigma the merge weighted the full by - as a scaling program’s unmerged output carries them, and a full the merge did not keep (an outlier, or past the resolution cut) is not written; FLAG is then 0 throughout. A program that merges this file reproduces Rugnux’s merge, and one that scales it again starts from the scaled data. The file’s title says scaled. Each row’s other columns are those of the event it was measured in, so the paragraphs below - which describe the unscaled file written otherwise (stills, --no-merge, and --export-unmerged-partials) - still hold for them, but not for I and SIGI. No SCALEUSED column is written: a full is a weighted combination of its partials, each on its own frame’s scale, so no one factor takes it back to their sum.

What has been applied to the intensities, and what has not (unscaled). I and SIGI carry the deterministic per-reflection corrections and nothing else. Three columns record them: LP is Lorentz x polarization; QE is the sensor’s quantum efficiency at the angle the diffracted beam meets the detector; and FLIGHT is the attenuation in the medium the reflection crossed on its way there. QE and FLIGHT are both divisors normalised to 1 at normal incidence, so raw counts are I / LP * QE * FLIGHT. They are applied because they are per-observation geometry that varies by more than two orders of magnitude across a sweep and no reader can reconstruct them. QE is at least 1 and FLIGHT at most 1: an oblique reflection crosses more sensor, which makes it read high, and more of the medium, which makes it read low. FLIGHT is a column of ones under --flight-path vacuum.

QE is kept out of LP because that is what the field means by LP: XDS’s RLP is Lorentz x polarization alone, and DIALS fills LP from lorentz/polarization only and writes QE as a separate column — a column of ones where it has no correction. Rugnux normalises QE to normal incidence where DIALS stores the un-normalised absorbed fraction; the two differ by a per-dataset constant, i.e. by an overall scale. Deliberately not applied: the partiality is not divided out (it is reported in FRACTIONCALC), and the per-image scale is not applied at all — those programs fit their own scale model, and handing them pre-scaled data would have them fit a correction to a correction. No resolution cut, outlier rejection or ice-ring filtering is applied either.

Partials. On a rotation run the partials of each reflection are summed into one full, using the same rule Rugnux’s own 3D combine uses — consecutive frames no more than two apart — and the full is written at the batch its rocking curve is centred on, with the summed rocking-curve fraction in FRACTIONCALC. An event that caught less of its rocking curve than --min-captured-fraction (or --min-partiality) is not written, and neither is one with an overloaded pixel on any of its frames, exactly as in the merge. Summing is the default because a downstream program’s own partial handling is far more conservative than Rugnux’s: given raw partials, AIMLESS accepts only a small fraction of the file; given summed fulls it uses essentially all of it. --export-unmerged-partials writes the unsummed form to <prefix>_unmerged_partials.mtz for a program that would rather sum them itself. Stills have no rocking events and are the same either way.

Systematic absences. Lattice-centring absences are not written; screw and glide absences are. Prediction runs in a primitive setting so that the space-group search can test the centring, but the interstitial reflections that leaves make a reading program take the lattice for primitive and demote the group. Screw and glide absences are kept because they are the evidence the space group was chosen on — deleting them would turn a reading program’s test into an assumption. XDS and DIALS draw the line in the same place.

Scan axis. The batch headers carry the goniometer axis negated relative to the one in the input file. This is not a correction to the file: Rugnux brings an observation made at angle φ back to zero by rotating it by +φ, so the crystal itself turns by −φ, and an MTZ batch header records the axis a batch’s own increasing PHI turns the crystal about. With the sign as exported, POINTLESS’s independently determined orientation matrix agrees with Rugnux’s.

Taking the data onward

The reflection files are inputs to other suites, and the handover has a few conventions worth one line each. These are the minimum commands that get each program running on Rugnux output.

phenix. The merged files carry both the mean intensity and the Bijvoet pairs, and a phenix program that has not said which it wants stops on the pair of them — from the MTZ and from the mmCIF alike, each listing its own format’s labels:

Sorry: Multiple equally suitable arrays of observed xray data found.
+
+Possible choices:
+  myrun.mtz:IMEAN,SIGIMEAN
+  myrun.mtz:I(+),SIGI(+),I(-),SIGI(-)
+

Two things are worth knowing before reading that as a fault in the file. The tie is between the two intensity arrays and nothing else: iotbx scores F/SIGF and F(+)/F(-) below them, so they are never in the running and writing amplitudes as well as intensities is not what causes this. And ctruncate’s own output ties in the same place — put any merged data through CCP4’s truncate step and phenix asks the same question of the result, because a mean intensity array and an anomalous one score equally whenever the calling program has expressed no preference. The only file change that removes the tie is dropping one of the two, and dropping the Bijvoet columns would take the anomalous signal — and the whole SHELX route — with it.

So the answer is a label. The parameter name differs by program, which is the part that catches people out:

phenix.xtriage myrun.mtz xray_data.obs_labels=IMEAN
+phenix.xtriage myrun.mtz "xray_data.obs_labels=I(+)"        # the Bijvoet array instead
+phenix.refine  model.pdb myrun.mtz miller_array.labels.name=IMEAN
+

IMEAN on its own is enough — the match is on a substring — and IMEAN,SIGIMEAN and the fully-qualified scaling.input.xray_data.obs_labels= work equally. Quote the anomalous one: the parentheses are shell syntax otherwise. The same behaviour appears on the mmCIF in that format’s own vocabulary, and a label from one format does not work on the other (Sorry: No matching array):

phenix.xtriage myrun.cif xray_data.obs_labels=intensity_meas
+phenix.xtriage myrun.cif xray_data.obs_labels=pdbx_I_plus
+

A program that states a preference needs none of this. phenix.hyss, phenix.find_peaks_holes, phenix.molprobity and the data import behind phenix.autosol ask for anomalous data by preference, which breaks the tie for them. phenix.hyss myrun.mtz n_sites=6 scattering_type=S opens the file with no labels given, reports Miller array info: myrun.mtz:I(+),SIGI(+),I(-),SIGI(-), and forms the anomalous differences itself.

The R-free convention. FreeR_flag is 0 = free, 1 = work — the CCP4 convention the column’s own name belongs to (5 % free by default). REFMAC5’s default FREE 0 reads it directly and phenix.refine detects the numbering on its own, so neither needs a keyword:

refmac5 XYZIN model.pdb HKLIN myrun.mtz XYZOUT refined.pdb HKLOUT refined.mtz <<eof
+LABIN FP=F SIGFP=SIGF FREE=FreeR_flag
+NCYC 10
+END
+eof
+

POINTLESS / AIMLESS. myrun_unmerged.mtz opens in both directly — it is sorted the way AIMLESS requires and its header carries the determined space group (see The unmerged export). Running pointless first remains the safe route, and its independent space-group opinion is what the file exists for:

pointless HKLIN myrun_unmerged.mtz HKLOUT sorted.mtz
+aimless   HKLIN sorted.mtz         HKLOUT scaled.mtz
+

Several sweeps of one crystal form go in as separate HKLINs to the same pointless run — that is how sweeps Rugnux processed separately (--sweeps separate) are merged.

careless wants unmerged, unscaled intensities carrying only the deterministic per-reflection corrections, with the partiality reported and not divided out - on a rotation merge that is --export-unmerged-partials (<prefix>_unmerged_partials.mtz), as <prefix>_unmerged.mtz is scaled there. Against its published examples, two renames: BG/SIGBG are called BGMEAN/BGVAR here and BGVAR is a variance, not a sigma. A QE column is present, as in DIALS output (normalised to 1 at normal incidence where DIALS stores the absorbed fraction — a per-dataset overall scale). Hobs/Kobs/Lobs are reconstructed from M/ISYM by reciprocalspaceship, and dHKL careless computes from the cell, so the metadata string that names this file’s columns is

careless mono --anomalous "BATCH,dHKL,Hobs,Kobs,Lobs,XDET,YDET,BGMEAN,BGVAR,LP,FRACTIONCALC" \
+    myrun_unmerged.mtz out/myrun
+

Molecular replacement and experimental phasing each get a section of their own below — Phaser and SHELXC/D/E. Both are where Rugnux stops and the next program starts, and both meet the one thing the merged intensities could not decide: which of several space groups the data are in.

iotbx.merging_statistics myrun_unmerged.mtz needs no arguments or label choices at all.

Molecular replacement with Phaser

rugnux places a model by molecular replacement only to decide what the merged data cannot decide by themselves - the space group, the hand, twinning (--model, --mr; see Validating against a model) - so Phaser is still the next program for anyone solving a structure with a search model. Both CCP4 and phenix ship it — phaser and phenix.phaser, Phaser 2.8.3 in both — and either takes the merged myrun.mtz as it is written.

No LABIN, no label choices. Phaser reads the cell, the space group and the resolution range out of the file and picks the intensity columns itself. Where phenix stops on a merged file because it cannot choose between two equally usable observation arrays (see above), Phaser simply announces what it took:

   Data read from mtz file: myrun.mtz
+   Space-Group Name (Hall Symbol): P 41 21 2 ( P 4abw 2nw)
+   Unit Cell:   78.06   78.06   37.70   90.00   90.00   90.00
+   Column Labels Selected: IMEAN SIGIMEAN
+   Resolution on Mtz file:  0.99 39.03
+

So the whole run is the model and the cell contents:

phaser <<eof
+MODE MR_AUTO
+HKLIN myrun.mtz
+ENSEMBLE model PDBFILE model.pdb IDENTITY 1.0
+COMPOSITION PROTEIN MW 14300 NUMBER 1
+SEARCH ENSEMBLE model NUMBER 1
+ROOT myrun_mr
+eof
+

Phaser reads the file without warnings. The one trap in that script has nothing to do with Rugnux: COMPOSITION PROTEIN SEQUENCE wants a file name, and given a chain identifier instead it fails with FILE OPENING ERROR: X before it reads anything. Use MW unless you have the sequence file to hand.

The space group is the interesting part. SPACE_GROUP_NAME in the results report is a scalar and reads like a determination, but it is one of the groups the absences allow, chosen by convention — section 2 says which others it could not separate, as SPACE_GROUP_ALTERNATIVES, and whether the hand is open, as SPACE_GROUP_ENANTIOMORPH= UNDETERMINED. Merged intensities never name a hand: an enantiomorphic pair has the same absences and the same Laue class. Phaser is one of the few programs that can settle it, because a wrong hand simply fails to place the model.

It does this without being asked. MODE MR_AUTO defaults to SGALTERNATIVE SELECT HAND, so the run above listed

   Space Group(s) to be tested:
+     P 43 21 2
+     P 41 21 2
+

and returned a single solution in P 43 21 2 — the hand opposite the one in the MTZ header. Nothing in the command asked for that. The space group of the solution is the answer, whichever hand the file happened to carry, and it is on the SOLU SPAC line of the .sol file and in the CRYST1 of the placed model.

When the alternative is not the hand, name it. SPACE_GROUP_ALTERNATIVES also carries screw variants that share a point group — I 2 3 and I 21 3 on a body-centred cubic lattice is the common one — and SGALTERNATIVE SELECT ALL searches every group Phaser derives from the input one by translation symmetry. On a P 41 21 2 input that is all eight of P 4 2 2 … P 43 21 2, at little extra cost; on an I 2 3 input it is I 2 3, I 21 3 and an origin-shifted I 2 3. To see the list a given file would produce without searching it, MODE CCA prints it and stops:

phaser <<eof
+MODE CCA
+HKLIN myrun.mtz
+COMPOSITION PROTEIN MW 14300 NUMBER 1
+ROOT myrun_cca
+eof
+

What Phaser cannot repair from this file is a wrong point group. SGALTERNATIVE moves within one, so a run whose report carries a non-NONE SPACE_GROUP_REFUSED_POINT_GROUP, or a point group you suspect is too high, has to be merged again rather than searched again — re-run Rugnux with -S set to the subgroup (-S 1 for P1), or merge myrun_unmerged.mtz through pointless.

mmCIF is not a route into Phaser. HKLIN myrun.cif stops at FILE OPENING ERROR: myrun.cif, in both the CCP4 and the phenix build — 2.8.3 reads MTZ only. Convert rather than look for a keyword:

gemmi cif2mtz myrun.cif fromcif.mtz
+

That file gives the same solution. Its amplitude columns come out as FP/SIGFP where Rugnux’s own MTZ writes F/SIGF, which matters only if you were naming columns by hand; the automatic choice is IMEAN/SIGIMEAN either way. Since Rugnux writes the MTZ and the mmCIF in the same run, the conversion is only worth knowing about for a file that arrived without its .mtz.

Small-molecule structures with SHELXT and SHELXL

A small-molecule sweep (see Small-molecule data) goes to SHELX as xtal.hkl, the rotation run’s scaled reflections unmerged, in HKLF 4, with the instruction file xtal.ins beside it. shelxt and shelxl come with CCP4 as well as with the SHELX distribution. The .ins is one file that both programs accept, and holds what the data determine:

TITL xtal in P 1 21/c 1
+REM Rugnux ...: CELL, ZERR, LATT and SYMM from the data.
+REM SFAC/UNIT are a placeholder, an organic formula at 18 A^3 per non-H atom:
+REM replace them with the real formula before refining with SHELXL.
+CELL 0.61993 11.46667 5.57668 12.66796 90.0000 111.7124 90.0000
+ZERR 4 0.00250 0.00067 0.00224 0.0000 0.0107 0.0000
+LATT 1
+SYMM -X,Y+1/2,-Z+1/2
+SFAC C H N O
+UNIT 29 29 6 7
+TEMP -173.1
+HKLF 4
+END
+
  • CELL is at the wavelength of the run, and ZERR carries Z and the cell’s standard uncertainties (see Cell e.s.d.s); Z assumes one formula unit per general position. Where the run did not measure the e.s.d.s (stills, --mode scale) they are written as 0 and a REM says so: SHELXL stops with ** ZERR MISSING ** without the line, and then puts no e.s.d.s on the cell of its CIF.

  • LATT and SYMM are the space group the report names.

  • SFAC and UNIT are a placeholder - an organic composition at 18 ų per non-hydrogen atom - since the cell contents are what only the user knows. For an organic compound SHELXT can work with it (it reports the formula it found, and assigns the elements itself), but anything with heavier or inorganic elements needs the real SFAC first: with the placeholder, SHELXT cannot place a metal it has no scattering factor for, and may run for a long time without solving a structure the right SFAC solves in a second.

  • TEMP is the sample temperature the data file records, in °C (see Input formats); SHELXL takes its starting U values and the CIF’s _diffrn_ambient_temperature from it. Where the file records none (CBF, the CCD formats) a REM line stands in its place, and SHELXL assumes 20 °C: add TEMP after UNIT by hand for a cooled crystal (TEMP -173 for 100 K).

  • No line is longer than the 80 characters SHELXL accepts.

Solving and refining, with the formula filled in (SFAC C H O, UNIT 24 32 28 for four molecules of C6H8O7):

cp xtal.hkl struct.hkl
+cp xtal.ins struct.ins      # then set SFAC / UNIT to the formula
+shelxt struct
+

SHELXT takes the Laue group and the lattice from LATT/SYMM and determines the space group itself, so where the report’s SPACE_GROUP_CENTRE= is NOT_DETERMINED its choice is a second opinion on the centre of symmetry. SHELXT writes its best solution as struct_a.res, with struct_a.hkl beside it in the setting it chose (and the cell, ZERR and TEMP carried across), and refinement continues from those:

cp struct_a.res struct_a.ins    # add ANIS (and the H atoms) as usual
+shelxl struct_a
+

At a synchrotron wavelength SHELXL also prints ** Warning: DISP instructions may be required for this wavelength **: it has f′ and f″ built in only for the laboratory wavelengths, so give one DISP line per SFAC element (after SFAC, before UNIT) with the values for the run’s wavelength, which GUI front ends such as Olex2 or ShelXle fill in, or accept the warning for light atoms at short wavelengths, where they are small.

What SHELXL makes of the file:

  • It merges the equivalents itself (MERG 2, its default) and prints R(int) and R(sigma) from them, which a merged file would hide. In a group without a centre of symmetry it keeps the Friedel opposites apart, so the absolute structure (the Flack parameter) comes from the same file, with no -A at processing.

  • The scale is arbitrary: the intensities were multiplied by one factor so the largest fits the F8.2 field. SHELXL refines its own overall scale, so nothing has to be done about it.

  • There is no batch column, which in HKLF 4 would select a BASF scale factor; the reflections are on one scale already.

  • What the merge rejected is not in the file: the outliers, and the measurements left out for an overloaded pixel (OBSERVATIONS_REJECTED_OVERLOAD= in the report). A crystal whose strongest low-order reflections were overloaded is missing them, and SHELXL cannot say so; the report can.

  • The resolution stops at the run’s cut, as in every written file. Run with --resolution-cutoff off to hand SHELXL everything the detector recorded.

Experimental phasing with SHELX

shelxc, shelxd and shelxe come with CCP4 (phenix does not ship them). The input is myrun.hkl, and it is the only one of the three reflection files that works: SHELXC 2016/1 reads XDS and SHELX formats, not MTZ, and SAD myrun.mtz gets ** Cannot open file myrun.mtz ** — after which SHELXC exits 0 and writes nothing, so a script has to check for the _fa.hkl it should have produced rather than trust the exit status.

Nothing has to be switched on to get the anomalous signal. A default rotation merge keeps the Bijvoet split, whether or not -A was given: myrun.mtz carries I(+)/I(-) and F(+)/F(-) beside the means, and myrun.hkl holds every observation unmerged at the index it was measured at, so SHELXC sees both hands. On rotation data -A changes nothing in the files or the merge; it only sets FRIEDELS_LAW= FALSE in the report. The one case with no anomalous signal at all is a stills run without -A, which merges the hands; there myrun.hkl holds means only and there is nothing for SHELXC to work with. myrun_unmerged.mtz is not part of this chain (it holds the observations, not merged intensities), so a run with --no-export-unmerged is not missing a file SHELX needs.

HKLF 4 carries no metadata, so the cell and the space group have to be repeated on the SHELXC command — take them from the CELL line of myrun.ins, or from UNIT_CELL_CONSTANTS and SPACE_GROUP_NAME in section 2 of the report, with the spaces taken out of the group’s name. (SHELXC also puts a wavelength in the CELL line of the .ins files it writes; that is its own 0.98 Å default, not anything read from the data, and neither SHELXD nor SHELXE uses it.) The whole chain, for a sulfur substructure — the cell and group here are tetragonal lysozyme’s, so substitute your own report’s:

shelxc sad <<eof
+SAD myrun.hkl
+CELL 79.0 79.0 38.0 90 90 90
+SPAG P41212
+FIND 10
+SFAC S
+MAXM 2
+eof
+shelxd sad_fa
+

SHELXC’s own table is the first look at whether this is worth continuing: <d"/σ> is about 0.80 where there is no anomalous signal, and a sulfur-SAD sweep worth pursuing reads well above 1 in its low-resolution shells.

SHELXD will separate space groups the merged intensities could not. Where the report names a pair the absences cannot separate (a body-centred cubic I 2 3 / I 21 3, for instance), run SHELXC and SHELXD once per candidate — same reflections, same FIND, only SPAG different. The substructure is where the screw axis shows itself, and the group with the clearly higher CC / CC(weak) / CFOM is the right one. This is the same handover as Phaser’s arrived at from the other side, and it is worth doing whenever SPACE_GROUP_ALTERNATIVES is not NONE — SHELXD takes seconds, and the pair of runs costs less than reprocessing anything.

SHELXE decides the hand, and says so. Run it twice, -i inverting the substructure. -s is the solvent fraction, -h says the substructure atoms belong to the native structure, as sulfur does, and -a turns on autotracing, which is what actually makes the two hands separate. The two runs write sad.pdb and sad_i.pdb, so they can share a directory:

shelxe sad sad_fa -h -s0.62 -m20 -a15 -q
+shelxe sad sad_fa -h -s0.62 -m20 -a15 -q -i
+

The hand that solves shows a clearly higher autotrace CC, pseudo-free CC and map contrast than the other; two hands that read alike are neither a discrimination nor a solution, and usually mean the sweep lacks the completeness and multiplicity sulfur phasing needs rather than that the file is at fault. Where the group is one of the 22 that come in enantiomorphic pairs, SHELXE makes the group change itself: the inverted run prints ** Space group converted to enantiomorph ** and writes the changed group into the CRYST1 of its traced model, so the answer is readable off the output file the same way it is off Phaser’s.

Comparing the geometry with XDS

The report states the geometry the result was integrated at in XDS’s convention, in its XDS GEOMETRY KEYWORDS section (see the results report), so it can be read straight across against the IDXREF.LP / CORRECT.LP of an XDS run on the same data, or pasted into XDS.INP:

# XDS.INP> ORGX= 1091.00  ORGY= 1137.00
+# XDS.INP> DETECTOR_DISTANCE= 75.000
+# XDS.INP> INCIDENT_BEAM_DIRECTION= 0 0 1  X-RAY_WAVELENGTH= 1.000000
+# XDS.INP> ROTATION_AXIS= 1.000000 0.000000 0.000000
+

The XDS plugin supplies image data only, so XDS refines its own geometry from XDS.INP - which is what makes the comparison worth having. The two laboratory frames coincide (x along increasing detector column, y along increasing row, z along the beam), so the numbers are directly comparable, and a tilt appears as the two detector axis vectors rather than as angles, which is how XDS reports it after refinement. Two things to keep in mind: ORGX/ORGY are 1-based, because XDS counts pixels from 1 and Jungfraujoch from 0; and they are the PONI, the same quantity Jungfraujoch’s beam centre is — so no correction is needed — but not the direct beam once the detector is tilted. ROTATION_AXIS is rugnux’s axis negated: rugnux turns the crystal by -phi about its axis, XDS by +phi, and with rugnux’s own sign IDXREF indexes only the chance floor of a mis-signed spindle. The detector axes appear only where the detector is tilted.

\ No newline at end of file diff --git a/RUGNUX_MODEL_AND_REFERENCE.html b/RUGNUX_MODEL_AND_REFERENCE.html new file mode 100644 index 000000000..c3cd312d3 --- /dev/null +++ b/RUGNUX_MODEL_AND_REFERENCE.html @@ -0,0 +1,2 @@ + Models and reference data — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Models and reference data

What Rugnux does with outside knowledge — an atomic model, a predicted model, a reference dataset, a cell or a space group you already know — and, decision by decision, what that knowledge is and is not allowed to change. The first section is the short version; the tables after it are the precise one; the rest walks through a run step by step.

In short

  • Rugnux needs nothing but the images. Indexing, the cell, the space group, the resolution cut, scaling, merging and the error model all come from the data. Everything on this page is optional.

  • A model (--model, --mr) does not change how your data are processed. The images are indexed, integrated, scaled and merged the same way with or without it, and the space group is determined before the model is used. The merged intensities and their sigmas in <prefix>.mtz are the same numbers either way.

  • The model can only relabel, and only if the data accept it. It is first tested against copies of itself placed in random orientations. A model that fits no better than those changes nothing at all: the reflection files are byte for byte what a run without a model writes. A model that does fit may change three labels in <prefix>.mtz: the hand of the space group (P4₁2₁2 against P4₃2₁2, which the intensities cannot tell apart), the indexing where the lattice allows two equally valid ones, and the axes the files are written on. No intensity is changed, no reflection is added or removed, and no other space group is ever taken.

  • A different space group chosen by the model goes to a separate file. If the model prefers another space group, or a twinned subgroup, that merge is written beside the answer as <prefix>_mr.mtz/.cif, with the model as placed there. <prefix>.mtz stays the data’s own answer.

  • A placed model is then refined, after every decision has been taken, and written beside the answer as <prefix>_refined_model.cif/.pdb with its maps (Refinement); --no-refine skips it. The refinement changes nothing else the run writes.

  • A reference dataset (-z) and a space group or cell you give (-S, -C) are different: they are taken as facts about the crystal. They fix the space group and the cell before processing, so with them the space group is yours, not the data’s.

  • Serial stills are no exception: the model is not used before the merge there either. The per-crystal indexing ambiguity is resolved from the data (and against -z where given), see Serial stills; the model only relabels the merged reflections into its own indexing afterwards, as on rotation data.

Every option that brings in a model or reference data

Option

What you give

What Rugnux uses it for

Can it change <prefix>.mtz?

(none)

—

Everything from the data

—

--model <file>

An atomic model, PDB or mmCIF, gzipped or not, recognised by content: an experimental structure or a prediction

Validation after the merge (R-work/R-free, CC(model, data), maps, the placed model); a rigid-body placement checked against a null, with molecular replacement where the rigid body does not place it, and straight away for a prediction; then refinement of the placed model (REFINE_ keys, <prefix>_refined_model.cif/.pdb, _refined_maps.mtz, _blobs.json), which decides nothing

Labels only (hand, indexing, axes), and only where the model fits. Other space groups → <prefix>_mr.*

--mr <file>

The same kinds of model

As --model, but molecular replacement straight away, without the rigid body. --mode mx only, not together with --model

Hand label only. Other space groups → <prefix>_mr.*

PAE file beside a prediction

AF-<id>-F1-predicted_aligned_error_v<n>.json next to AF-<id>-F1-model_v<n>.cif (read automatically, no option)

Cuts the prediction into rigid domains for molecular replacement

No (a domain alone can only confirm the answer’s group)

-z, --reference <file> (--reference-mtz)

Merged data of the same crystal form: an MTZ, or a PDB structure-factor mmCIF (-sf.cif)

Fixes the space group (in its own setting) and the cell (softly), puts the merge on its axes, resolves the indexing ambiguity, hands over its R-free set, reports CCref on stills. Never a scale anchor

Yes: the space group, the axes, the indexing and the free set are the reference’s

--reference-column <label>

An MTZ column label

Which column of the reference is read

Through -z only

--free-flags <file>

Merged data carrying an R-free set: an MTZ, or a structure-factor mmCIF - typically the deposited reflections of the --model

Its R-free set and nothing else: the model is validated and refined against it, on the model’s axes, where the merge matches the file’s intensities (R_FREE_FLAGS= FILE)

The free flags only

-S, --space-group

A space group

Fixes it: no space-group search

Yes: the group is yours (a fitting model may still relabel its hand)

-C, --unit-cell

A cell

Indexing looks for this cell (within tolerance); the FFT search range is widened to cover it; on stills the shared-geometry refinement anchors on it as a prior (without it, on the cell the frames index to), and warns, keeping it, where it puts materially fewer of a sample’s spots on the lattice than the frames indexed de novo

Yes: the cell, and the axis order the files are written in

--force-rotation-lattice

Nine numbers: a lattice

Skips the first-pass indexing and uses this lattice

Yes: the lattice

--report-resolution <dmin>[,<dmax>]

Another program’s resolution range

A second statistics table at that range (REFRES_*)

No — report only

Without the options. A model and a reference reflection file can also be given among the inputs, in any order: rugnux data_master.h5 model.cif, rugnux model.pdb.gz data_master.h5 ref.mtz. Each file is told by its contents, never its name: an MTZ (its MTZ magic) or an mmCIF with a _refln or _diffrn_refln loop (a PDB -sf.cif) is reference data, taken as -z - in --mode refine it is the input itself; a PDB file (a PDB record first, with an ATOM or HETATM record) or an mmCIF with an _atom_site loop is a model, taken as --model; anything else is images, for the readers. An mmCIF holding both coordinates and reflections is refused as ambiguous and has to be given with --model or -z. At most one model and one reference, counting --model/--mr and -z as well; gzipped files are read through.

-S, -C, -z and --force-rotation-lattice are assertions: Rugnux takes them as true and does not test them against a null. Use them when you know; leave them out to let the data decide (a de-novo run is the recommended default — see Running Rugnux). --model and --mr are hypotheses: Rugnux tests them, and what it lets them change is limited and stated below. In --mode calibration a cell given with -C names the calibrant instead (Detector calibration); nothing on this page applies there.

Four kinds of influence

Every decision and every output of a run falls in one of four classes. The decision table below uses these letters.

  • (a) Data only. Never influenced by any model. The same with and without --model/--mr.

  • (b) Model-informed label in <prefix>.mtz. A choice between alternatives the data cannot separate and that are all equally valid descriptions of the same measurement: the hand of an enantiomorphic pair, an indexing ambiguity, the setting (axes). The model may make it only after it has passed its null; the intensities do not change. Reported as SPACE_GROUP_ENANTIOMORPH= ASSUMED_FROM_MODEL, MODEL_DECISIONS_TAKEN=, MODEL_ENANTIOMORPH_ADOPTED=, MODEL_INDEXING_OPERATOR=, SETTING_SOURCE= MODEL, and the withdrawal of INDEXING_AMBIGUITY_OPERATORS=.

  • (c) Model-driven, separate files only. A choice the data could in principle make but did not make the model’s way: another space group with the same rotations (other screw axes), or the twin hypothesis’ subgroup. Written only as <prefix>_mr.mtz/.cif with <prefix>_mr_model.pdb/.cif (and named by MODEL_CHOICE_FILE_PREFIX=, MODEL_CHOICE_SPACE_GROUP=, MR_DECISION=). Never in <prefix>.mtz.

  • (d) Report-only model statistics. Numbers about the model against the data, which nothing in the pipeline acts on: R_WORK/R_FREE, R_MODEL_SHELL_SCALED, CC_MODEL_*, MODEL_FIT*, MODEL_PLACEMENT, the MR_* keys, the anomalous sites, the maps.

Decision by decision

“Reference” means -z. A dash means the option plays no part.

Decision

Without anything

With -S / -C

With -z

With --model / --mr

Class

Spot finding, beam centre, detector geometry

data

—

—

—

(a)

Indexing, lattice, cell

data (de novo)

your cell / lattice

the reference’s cell, softly

—

(a)

Integration

data

—

—

—

(a)

Scaling, error model, ISa

data

—

— (never a scale anchor)

—

(a)

Outlier rejection, frame disposition

data

—

—

—

(a)

Resolution cut

data (CC1/2 fall-off)

—

—

— (CC_MODEL_CONFIRMED_TO_D_MIN is reported, never used)

(a)

Point group, Laue class, centring

data (space-group search)

-S fixes it

the reference’s

—

(a)

Screw axes (space group within the point group)

data

-S

the reference’s

a different choice → <prefix>_mr.* only

(a) in p.mtz, (c) beside it

Hand (enantiomorph)

not decidable: SPACE_GROUP_ENANTIOMORPH= UNDETERMINED

GIVEN

GIVEN

relabelled to the model’s where it fits, past the anomalous veto: ASSUMED_FROM_MODEL

(b)

Indexing ambiguity (merohedral reindex)

arbitrary on rotation (INDEXING_AMBIGUITY_OPERATORS=); on stills with -S the crystals made consistent from the data, otherwise mixed (warning)

—

resolved against the reference

resolved by the model’s fit to the merge where its lead beats its null, rotation and stills alike. Never by molecular replacement

(b)

Setting (which axis is a, b, c)

standard setting

-C’s axis order; -S’s symbol

the reference’s

the model’s, where it fits and there is no -z (SETTING_SOURCE= MODEL)

(b)

Twinning check (L-test, twin laws)

data

—

—

—

(a)

Twin hypothesis <prefix>_twin_<SG>.*

data (when the group may have absorbed a twin law)

—

—

the model may also ask for this merge; written then only where the model chooses it

(a) / (c)

Anomalous signal, Friedel handling

data (-A)

—

—

— (the anomalous map is report-only, and the veto on the hand)

(a)

R-free test set

hash of the index

—

the reference’s flags, where it matches

— (drawn again on the model’s axes if the setting moved; never chosen by the model)

(a)

Merged intensities and sigmas in p.mtz

data

—

—

—

(a)

p.mtz space-group label

data

yours

the reference’s

hand relabel only

(b)

<prefix>_mr.mtz/.cif, <prefix>_mr_model.*

not written

—

—

another group or the twin subgroup the model chose

(c)

Maps, <prefix>_model.*, section 5 of the report

not written

—

—

always, whatever the verdict

(d)

Refinement, <prefix>_refined_*, <prefix>_blobs.json, REFINE_ keys

not written

—

—

where the model was placed (not with --no-refine)

(d)

A run with --model, step by step

  1. The file is read and classified. PDB or mmCIF, by content. A prediction — ModelCIF’s quality metrics, or no cell and one B value per residue between 0 and 100 (an AlphaFold file) — is told apart from an experimental structure (MR_MODEL_KIND=). A model that cannot be read does not fail the run; the report says MODEL_VALIDATION= NOT_PERFORMED and carries a warning.

  2. The data are processed without the model. Indexing, integration, scaling, the space-group search, the resolution cut, the error model, outlier rejection: none of them reads the model, on rotation data and serial stills alike. The only thing the model asks for here is one extra merge: the merge in a subgroup (the twin hypothesis) where the indexed lattice’s group was promoted by a metric re-ask, or where the model’s own group has fewer rotations than the adopted one — so that the model can be scored there. That merge is written only if the model chooses it.

  3. Rigid-body placement (experimental structures, not with --mr). The model is put into the data’s cell and refined as one rigid body on the working reflections; the step is kept only if it lowers R-free. A model written in another description of the lattice (other axes, other centring) is first put into the data’s (MODEL_CHANGE_OF_BASIS=).

  4. The null. The same model is turned to nine random orientations about its own centroid and placed the same way. The real fit has to beat them by 4.51 of their standard deviations on R-work (3σ allowing for the null being nine draws): MODEL_FIT= ACCEPTED, MODEL_FIT_SIGMA=. Otherwise REJECTED, and the model decides nothing. There is no fixed threshold on R (§14.5).

  5. What an accepted model may do (class b), applied to the reflections before they are written:

    • hand — where the data’s group is the enantiomorph of the model’s, the files take the model’s group as their label. No reflection moves and I(+)/I(-) stay as measured. Vetoed where the anomalous difference map read at the model’s atoms is inverted (warning MODEL_HAND, raised only for a placed model). Where the group was fixed with -S (or by the reference), the model’s hand replacing it is warned about (MODEL_SPACE_GROUP);

    • indexing — where the lattice admits alternative indexings and no -z already settled it, the candidate with the lowest R-free, if its lead over the runner-up beats the lead a random placement of the same model takes (MODEL_INDEXING_MARGIN_SIGMA= ≥ 3). The data are reindexed into the model’s frame, never the model into the data’s;

    • setting — a model written on other axes takes the files to its setting (SETTING_SOURCE= MODEL), so that reflections and coordinates can be used together.

  6. The twin hypothesis. Where a subgroup merge exists, the model is scored against it plainly and as twinned by its law. The maps come from whichever merge the model fits better on R-free (MAPS_FROM=). Where the model also fits there against its null, it has chosen the subgroup, and that merge is written again as <prefix>_mr.mtz/.cif (class c).

  7. Molecular replacement, for a prediction, with --mr, or for an experimental structure the rigid body did not place (in the answer’s merge or in the subgroup’s). As many copies as the cell most probably holds are searched for in every space group the merge cannot tell apart and in the twin hypothesis’ subgroup, and the choice has its own null. MR_DECISION= is one of: AGREES (the answer’s group — nothing changes); ENANTIOMORPH (the answer’s files take the hand label, past the same anomalous veto, else ENANTIOMORPH_VETOED); SPACE_GROUP or TWIN_SUBGROUP (written as <prefix>_mr.* only); UNDECIDED or NOT_PLACED (nothing is written). Molecular replacement never reindexes and never sets MODEL_FIT. Not placing a model is a result, not a warning (Molecular replacement).

  8. Validation and files. R-factors, CC(model, data), maps and the placed model are computed for the placement that was kept, against the merge it was chosen on, and written: <prefix>_maps.mtz (map coefficients), _model.cif/.pdb — or the <prefix>_mr_* equivalents where the choice was <prefix>_mr. A model placed nowhere (MODEL_PLACEMENT=NOT_PLACED) gets no model or maps files: its R-factors stay in the report as the negative result, but its coordinates and maps would read as a placement. A placed model is then refined (<prefix>_refined_model.cif/.pdb, _refined_maps.mtz, _blobs.json).

  9. The reflection files — <prefix>.mtz, .cif, .hkl, _unmerged.mtz — are written last, carrying only the class-(b) labels from step 5 and the hand from step 7.

MODEL_PLACEMENT= summarises steps 3–7: RIGID_BODY, MR or NOT_PLACED.

In --mode scale, --model is steps 3–5 only: the rigid body, its null, and the hand and indexing it may settle. There is no molecular replacement, no setting change, no twin hypothesis and no refinement, and --mr is refused.

Serial stills: the indexing ambiguity

On serial stills each crystal is indexed on its own, so where the lattice admits two indexings, each crystal lands in one of them at random and a merge averages reflections that are not equivalent. That has to be settled per crystal, before the merge. --model plays no part in it: intensities computed from a model are never used as the per-crystal reference, so a run with a model merges exactly what a run without one does. After the merge, the model is validated as in the steps above and may relabel the merged reflections into its own indexing.

A stills run given -S settles the same question from the data: it cannot say which indexing is the true one, but it can say which crystals share one, and puts each crystal into the indexing in which it agrees best with all the others, its own cell weighed beside that (INDEXING_AMBIGUITY_RESOLVED= data). Without -S - the space group then determined by the run, after the merge - nothing resolves it, and the run warns. With a reference MTZ, that same resolution runs and the reference fixes the indexing the merge is written in: AMBIGUITY_DATA_DISAGREES= in the report counts the crystals the data and their cells put into another indexing than the reference alone would.

The model and the space group

Spelled out, because this is the question that matters most:

  1. The space group in <prefix>.mtz is decided without the model — by the space-group search, or by you (-S, -z). The model is read after that decision.

  2. The model can change one thing about that group: its hand, between the two members of an enantiomorphic pair (P3₁/P3₂, P4₁2₁2/P4₃2₁2, P6₁22/P6₅22, …). The intensities are identical for both, so this is the one group choice no data can make; a model that fits carries chemical knowledge (the hand of its amino acids) the intensities do not. It is a label: no reflection moves. It applies to a group you gave with -S or -z too. The report says SPACE_GROUP_ENANTIOMORPH= ASSUMED_FROM_MODEL — assumed, not determined — also where the model simply agrees with the hand the run wrote.

  3. Everything else the model prefers goes beside the answer. Other screw axes with the same rotations (e.g. P2 against P2₁ where the absences did not decide), or the twin hypothesis’ subgroup: <prefix>_mr.mtz/.cif. The model never changes the point group, the lattice or the centring of <prefix>.mtz.

The safeguards behind 2 and 3:

  • The null. The model must beat its own random placements by 4.51 sd, rigid body and molecular replacement alike, before it may relabel anything or have a <prefix>_mr file written.

  • The anomalous veto. The hand is taken only where the anomalous difference map, read at the model’s atoms, is not inverted. The veto can act only where the merge kept the Bijvoet split — every rotation merge does; serial stills only with -A. R-free cannot see the hand at all.

  • The indexing margin. An indexing is taken only where the model’s preference beats what a randomly placed copy of it would show.

  • Molecular replacement’s own rules. Its choice of group has its own null (NULL_SIGMA); a placement must pack (CLASH, MATTHEWS); a choice that translational NCS could explain, or one where the merge’s own group was searched to fewer copies, is left UNDECIDED; a single domain of a prediction cut by its PAE can only confirm the answer’s group, never change it; a model of several chains is searched for as a whole and, beside it, one chain of each molecule by itself, and a chain replaces the whole only where it fits better by 0.03 in R-free or the whole was placed nowhere; in P1 the first copy’s origin is fixed and it counts only on its rotation function. The details are in Molecular replacement.

  • The wrong-model test. The validation battery checks that a model of an unrelated protein (similar size, unrelated sequence and fold, or the other hand) leaves the reflection data and every report key outside section 5 identical to a run without a model, is not accepted by the null, is not placed by molecular replacement and takes no decision (“The wrong-model null” in tools/battery/README.md).

Refinement

Giving a model is the opt-in: wherever the model is placed - it fits where it is, or molecular replacement placed it - rugnux refines it against the merge it was placed on; a model that is not placed is not refined. A run that should not spend the time is given no model; --no-refine skips the refinement of a placed model (for debugging). It takes seconds on a GPU and typically 2-15 minutes on the CPU (no GPU, or --no-gpu). Refinement comes after every processing decision and changes none of them: R_WORK, R_FREE and every other key outside REFINE_ stay those of the model as placed, and <prefix>.mtz, <prefix>_model.cif and <prefix>_maps.mtz are the same as they would be without it. The broker’s live mode refines an uploaded model in the same way (see Rugnux live mode).

What the dictionary restrains is fixed at build time: the 20 standard amino acids and MSE, the DNA/RNA nucleotides and the common modified RNA nucleotides (PSU, 5MC, 1MA, OMG, OMC, OMU, H2U, 2MG, M2G, 7MG, 5MU), ATP/ADP/AMP/GTP/GDP/GMP, the cofactors NAD, NAI, NAP, NDP, FAD, FMN, HEM, HEC, SAM and SAH, dioxygen (OXY), DMSO, PEG fragments (PEG, PGE, PG4, 1PE), glycerol, ethylene glycol, sulfate, phosphate, acetate, MPD, water and common ions (a subset of the CCP4 Monomer Library compiled into rugnux; nothing is read from disk). Any other residue is held fixed: it stays in the structure factors and the bulk-solvent mask, and the refined atoms are kept from clashing with it; REFINE_RESIDUES_FIXED_NAMES lists them. The dictionary’s hydrogens are added and ride on their parents. Metal ions, and the iron of a heme, are restrained to the donor atoms (O, N, S) the model’s LINK / _struct_conn records bind them to: by the dictionary’s own Zn and Fe links to Cys and His where they apply, otherwise at the library’s typical distance for the metal, the donor element and the number of such records of the ion (Mg-O 2.07 A, Na-O 2.42 A, K-O 2.82 A at their usual coordination), where the model’s distance is within 0.33 A of that (Mg-O up to 2.4 A); a record at an outer-sphere distance, a contact without a record, or one to a symmetry mate, is not restrained as a bond. The B factors of bonded atoms and of atoms in contact (waters included) are restrained to each other in proportion to their size. The weights of the X-ray term against the geometry and against that B restraint are chosen by R-free among short refinements whose bond and angle rmsd stay within 0.02 A and 2 degrees: three weights from the placed model, each with the B factors held and refined; then a trajectory of further short refinements from the best, each trying the weights as they are and changed, taken while R-free or R-work falls beyond 0.001 and R-free stays within 0.001 of its best; then a short final ladder, kept only where it lowers R-free beyond 0.001. The free set is the merge’s own, so the refined R-free judges the refinement against reflections it never fitted - but where the model was deposited, those reflections were most likely its depositor’s working reflections, and a refinement against new data then moves R-free up from the unrefined value rather than down. R_WORK/R_FREE of the model as given are never replaced. On a GPU a refinement takes seconds; the CPU engine computes the same and is several times slower.

How a model is scored. R-work, R-free and the likelihood target of every stage - the model as given (REFINE_R_WORK_START) as much as the refined one - come from one model of the structure factors, Fmodel = k exp(-sTBs/4) (Fcalc + ksol exp(-Bsols2/4) Fmask): the atoms with the dictionary’s riding hydrogens and their B made isotropic; a flat bulk solvent masked with the REFMAC radii (probe 1.0 A, shrink 0.8 A) on a grid of its own, at most 0.4 A apart, so that the shrink acts at any resolution; ksol and Bsol searched over the physical range on the working reflections, and the overall scale and anisotropic B fitted to them by robust least squares, so that a few reflections the model cannot explain (a beam-stop shadow, an ice ring, a missing part of the model) do not set the scale of the rest. On depositions from 1.1 to 3.6 A this gives REFMAC 5.8’s 0-cycle R-work and R-free on the same model and data within 0.006 (tools/battery/refine_parity.py runs the comparison; --refine-score-only prints each term under REFINE_SCORE_, see --mode refine).

The algorithms - the target and its gradient, the likelihood’s parameters, the restraints, the minimiser and the weight trials - are described in §15, and the keys in The results report.

What it does not do yet. The refinement is a first, automatic pass on a placed model, not a replacement for a refinement program. Not implemented yet:

  • custom ligands or a monomer library beyond the embedded compounds above: other residues are held fixed (they stay in Fcalc, the solvent mask and the clash terms), and no restraints are generated for a new ligand;

  • water building and ion relabelling by default: they are opt-in (--refine-solvent); without it the blobs only point at candidates;

  • occupancy refinement and new alternative conformations (existing ones are refined in place);

  • rotamer and peptide-flip search, Ramachandran restraints;

  • real-space refinement, jelly-body and reference-model restraints;

  • a full Metal (Apple GPU) path: on macOS only the model density is put on the grid on the GPU, the rest of the refinement runs on the CPU;

  • validation beyond the geometry’s rmsd and clash count: no MolProbity-style report.

TLS groups, anisotropic U (an ANISOU record is kept as the atom’s own U), NCS restraints and twin refinement are implemented and decided by the weight trials, see §15.

Refining a model against structure factors (rugnux --mode refine)

--mode refine refines a model against merged structure factors that already exist - processed elsewhere, a deposition’s, or a rugnux .mtz - and processes nothing:

rugnux --mode refine --model model.cif -o refined data.mtz
+

The input is an MTZ or a structure-factor mmCIF (as the PDB distributes them), gzipped or not, recognised by content; the model is PDB or mmCIF, taken as placed in the data’s cell and refined in the data’s space group. The columns are found, not named: amplitudes with their sigmas (F/SIGF, FP/SIGFP, FOBS, …; calculated amplitudes and map coefficients such as FC, FWT, DELFWT are passed over) where the file has them, else intensities (IMEAN/SIGIMEAN, I/SIGI, …) made into amplitudes by French-Wilson, else the mean of the anomalous pairs. The free set is read from a FreeR_flag-like column (flag 0 is the test set; where 0 marks the majority, as phenix and CNS write it, the minority value is; in a structure-factor mmCIF, _refln.status ‘f’ first); a file without one gets rugnux’s own 5 % set. Where a structure-factor mmCIF’s flags are classes (_refln.pdbx_r_free_flag 0-19), the class the file marks is not always the one the depositors held out, so the model as given is scored on each class: the mark is kept where the model fits that class worst or the test-set count the model file records (REMARK 3, _refine.ls_number_reflns_R_free) is nearest its count; otherwise the class the model fits worst is the test set where that count is nearest it, or where it is above the marked class by more than twice the scatter of the other classes’ R (REFINE_FREE_SET_SOURCE= STATUS|REMARK3_COUNT|WORST_FIT, REFINE_FREE_SET_CLASS). The refinement is the one run after a merge on a placed model, and writes the same files - <prefix>_refined_model.cif/.pdb, <prefix>_refined_maps.mtz, <prefix>_blobs.json - with the REFINE_ keys in <prefix>_report.txt, beside REFINE_FRENCH_WILSON= and REFINE_FREE_FLAGS= FILE|GENERATED saying what had to be made of the input.

Option

Description

--model <file>

The model (required; it can also be given among the inputs, told by content)

--refine-score-only

Score the model as given and refine nothing; every term of the score - R-work and R-free overall and in 20 resolution shells, the overall scale, B and anisotropic B, ksol and Bsol, the likelihood over the working and the free reflections and its figure of merit over the working reflections, and the geometry’s rmsd and rmsZ - under REFINE_SCORE_ keys (--developer prints them all). The twin test is the refinement’s: the model is scored against the data twinned by each law too, and the twinned score taken by the same rule (REFINE_TWIN)

--refine-d-min <A>

Leave out reflections finer than this

Free set and model bias

How the free set is made. Rugnux draws its own test set (5 %, raised towards about 500 reflections on small data but never above 10 %): each reflection’s flag is a hash of its index, taken over its orbit under the lattice’s metric symmetry, so symmetry mates, Friedel mates and twin-law mates share a flag, every dataset of one crystal form written on the same axes gets the same set, and the set does not depend on the space group a file is merged in (R-free test-set flags). The model plays no part in it. Where a fitting model moves the files to its setting, the set is drawn again on the new axes by the same rule; an indexing-ambiguity reindex leaves it unchanged, since twin-law mates share a flag. With -z, the reference’s flags are inherited where the merge matches it (REFERENCE_FREE_FLAGS_INHERITED=).

A model refined against these reflections. A set drawn here is free only for a model that was never refined against the crystal’s reflections. A deposited model, or one refined against an earlier dataset of the same crystal, has been fitted to every reflection, so its R-free on a fresh set reads close to its R-work - below it, sometimes - and a refinement from it reads no cross-validation at all. --free-flags <file> takes the test set of the reflections it was refined against (the deposited -sf.cif, or an MTZ) and nothing else from them: unlike -z it fixes no group, cell or frame and steers no processing. The flags are put on the merge once it is on the model’s axes, where the merge matches the file’s intensities as -z requires (CC at least 0.5 over at least half of its reflections); the validation is then made again on them, and the refinement and the merged files carry them. R_FREE_FLAGS= says which set R_FREE and the refinement used: DRAWN, REFERENCE (-z) or FILE.

What is fitted on which reflections. Everything fitted to place and scale the model — the overall scale, the anisotropic B, the bulk solvent, the rigid body — is fitted on the working reflections only. The free set is then used for a few discrete selections: whether the rigid-body step is kept, which indexing wins, and in molecular replacement which placement and which group. Each of those leaves R-free very slightly optimistic where it fires. For R_WORK/R_FREE the coordinates, B-factors and occupancies of the model are never refined; the refinement above refines them on the side, under REFINE_ keys of its own.

What R_FREE means here — and what it does not. It is the model as placed, scored on Rugnux’s free set: a check that the model fits these data, and a trend number between datasets of one campaign. It is not a refinement R-free, and it is not cross-validated against the model’s own history:

  • A deposited model was refined by its depositor against their working set. Rugnux’s free set is a different 5 %, so about 95 % of Rugnux’s free reflections were in the working set the model was refined on. R-free here therefore reads close to R-work, and it is optimistic in the usual model-bias sense.

  • To score a deposited model on its own test set, give its structure factors as the reference (-z 1abc-sf.cif): the depositor’s free flags are then inherited. But -z is an assertion — it also fixes the space group and the cell — so that is no longer a de-novo run.

  • A predicted model has not been refined against any diffraction data, so it carries no such memory; what remains is the selection effect above.

  • For comparing two runs against one model, read R_MODEL_SHELL_SCALED, not R_FREE (Comparing two runs).

What cannot leak, and what can. The model never enters the merged intensities, their sigmas, the choice of reflections, the resolution cut or the weights, so <prefix>.mtz carries no model bias in its numbers — only the class-(b) labels. The maps are model-phased, and carry the model bias any model-phased map carries: read the mFo−DFc map, and treat density that only the 2mFo−DFc map shows with the usual care. CC(model, data) is read in one direction only: a confirmed shell is evidence for the data, a weak shell says nothing about them, and nothing acts on it.

Practical guidance

When to give a model.

  • You have a structure of this crystal form (a fragment campaign, a ligand soak, a reference structure): give it with --model. You get maps, a placed model and Rugnux’s own first refinement of it, the indexing of every dataset brought into the model’s, and the hand fixed — the things that make a campaign’s files directly comparable. A wrong or rejected model costs a few seconds and changes nothing.

  • You have a structure of the same protein in another crystal form: --model too. The rigid body will not place it, and molecular replacement is tried automatically.

  • You have only a prediction (AlphaFold, ModelCIF): --model (or --mr). Download the PAE JSON with it and keep its AlphaFold DB file name, so it is cut into domains when the whole model does not place. A prediction is good for: confirming the space group, naming the hand where the data cannot, offering a twinned or lower-symmetry alternative where the data are ambiguous, and a first set of maps. It is not a refined model, and its R-factors read accordingly.

  • You have a previous dataset of the same crystal form and want the same indexing and free set: -z, not --model. It is the stronger tool for the indexing ambiguity and the only one that carries a free set over, but it pins the space group and cell.

  • You want to compare with another program’s statistics: --report-resolution, which changes nothing else.

Which file to use for what.

File

What it is

Use it for

<prefix>.mtz / .cif / .hkl

The answer: the data’s space group, with only the class-(b) labels from the model

Refinement, deposition, everything by default

<prefix>_model.cif / .pdb, <prefix>_maps.mtz

The model as placed, in the frame of <prefix>.mtz, and its map coefficients (Coot/PyMOL open them as maps); only where the model was placed (MODEL_PLACEMENT= RIGID_BODY or MR)

Starting refinement (REFMAC5, phenix.refine), PanDDA, Coot

<prefix>_refined_model.cif/.pdb, <prefix>_refined_maps.mtz, <prefix>_blobs.json

The placed model refined by rugnux, its map coefficients (with the anomalous difference map’s, ANOM/PHANOM, where the merge kept the Bijvoet pairs, as in <prefix>_maps.mtz), and the unexplained blobs of its difference map

A first look at the refined density and at what the model leaves unexplained; continuing refinement

<prefix>_twin_<SG>.mtz / .cif

The same data merged in a subgroup with a twin law — written from the data, model or not

Twin refinement, where you suspect the higher group absorbed a twin law

<prefix>_mr.mtz / .cif, <prefix>_mr_model.pdb / .cif, <prefix>_mr_* maps

The merge in the space group the model chose (MODEL_CHOICE_SPACE_GROUP=), and the model placed there

Refinement if you accept the model’s choice; compare R-free against the answer’s

<prefix>_mr and <prefix>_twin_<SG> can describe the same subgroup; the _mr file then also carries the model placed in it.

Reading section 5 of the report, in order:

  1. MODEL_VALIDATION= — did it run? If NOT_PERFORMED, MODEL_VALIDATION_REASON= says why.

  2. MODEL_PLACEMENT= — how the model was placed: RIGID_BODY, MR or NOT_PLACED.

  3. MODEL_FIT=, MODEL_FIT_SIGMA= — the rigid body’s verdict against its null. Absent where the rigid body was not tried (a prediction, --mr).

  4. MODEL_DECISIONS_TAKEN= — NONE means the reflection files are what a run without a model writes. Otherwise ENANTIOMORPH, INDEXING, both, or MR_ENANTIOMORPH, with MODEL_ENANTIOMORPH_ADOPTED= and MODEL_INDEXING_OPERATOR=.

  5. MODEL_CHOICE_FILE_PREFIX=, MODEL_CHOICE_SPACE_GROUP=, MR_DECISION= — whether a <prefix>_mr file was written, and in which group.

  6. R_WORK=, R_FREE=, CC_MODEL_CONFIRMED_TO_D_MIN=, the anomalous sites — how well the placed model describes the data (class d).

Outside section 5, SPACE_GROUP_ENANTIOMORPH= (UNDETERMINED, GIVEN or ASSUMED_FROM_MODEL), SETTING_SOURCE= and the presence or absence of INDEXING_AMBIGUITY_OPERATORS= say what the model did to the answer’s labels. Every key is described in The results report.

\ No newline at end of file diff --git a/RUGNUX_OVERVIEW.html b/RUGNUX_OVERVIEW.html new file mode 100644 index 000000000..7d9d57ff9 --- /dev/null +++ b/RUGNUX_OVERVIEW.html @@ -0,0 +1 @@ + Overview — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Overview

The map of a run, in the order it happens — one paragraph per stage, each linking into the data-analysis reference where the algorithm lives. The walk-through is a rotation run with the defaults; stills differences are at the end.

The rotation pipeline: pass 1 integrates half the sweep at the file's geometry, pass 2 the whole sweep at the refined one, and the better of the two goes on to the space group and the written merge; with a model, the placement and the refinement follow, deciding nothing

Open the dataset. The geometry, wavelength and goniometer come from the file (Input formats). A goniometer axis that turns makes it a rotation run; none, or one that stands still from frame to frame, makes it serial stills — nothing is asked of the user.

Pre-scan. A projection of frames (60 by default) spread over the first part of the sweep, the part the geometry pre-pass integrates, finds the beam-stop shadow and masks it (§1.5), masks pixels its frames show to be defective (§1.6), measures the beam centre from the isotropy of the scattered background and compares it with the file’s (§1.4), and reads how wide this crystal’s spots are, which sets the integration radius (§9.5), and how much longer they are along their radius than across it, which is the beam’s bandwidth where the file does not state one (§9.6), and how much wider still they grow away from the beam, which sets the integration footprint (§9.1). In a GPU build the pre-scan runs on the card.

Spots. Every image is decoded — on the GPU straight from the compressed chunk (§0) — and one fused pass computes the azimuthal profile and finds the spots against each image’s own per-resolution-ring noise (§2–§3). The ice-ring score is read off the same profile.

Indexing. The spots of a sample of frames are rotated back to a common crystal frame and the FFT search looks for periodicity over thousands of directions; candidate cells are Niggli-reduced, classified by Bravais lattice, refined both constrained and triclinic, and decided on how many validation frames each actually indexes (§4–§7). A lattice row shorter than the search’s 10 Å floor, as small-molecule cells have, is recognised under the multiple of it the search reports, down to 3 Å. The first pass is indexed a second time at the beam centre the pre-scan measured; the file’s centre is kept unless it indexes nothing, gives an axis harmonic of the measured centre’s lattice, or loses to it when both first passes are merged (§1.4). A failed pass triggers the discrete rescues — the rotation-axis sign, the first-pass depth ladder, the long-axis hypothesis — before anything is given up on.

First integration pass. At the geometry in the file, every frame of the first half of the sweep, at least 120° of it (--prepass-fraction) is predicted (§8) and profile-fit integrated (§9); partials are combined into fulls, scaled and merged (§10).

Geometry post-refinement. From those reflections the detector distance, beam centre and the cell scale / rotation axis are refined over all those frames at once, each step committed only if it improves a held-out residual (§7.5).

Second pass. The sweep is re-indexed de novo and re-integrated at the refined geometry; this pass is the canonical output, and a guard compares the two passes and keeps the better one (reported as PASS= / PASS_DECISION= in the report).

Space group. On the P1 merge of the final pass, the point group is scored operator by operator on resolution-normalised intensities and the screw axes, glide planes and centring are read from the systematic absences, with the centre of symmetry from the intensity distribution where the absences leave it open (§13.1); twinning and translational pseudo-symmetry are checked beside it (§13.2). CANNOT_DETERMINE and an enantiomorphic pair are real answers here, not evasions.

Scale and merge. In the determined group: per-frame scales, the cross-validated correction surfaces (decay, absorption, modulation), the error model and ISa, outlier rejection, the CC1/2-based resolution cut, the anisotropy description, French–Wilson amplitudes and the R-free flags (§10, §13.3–§13.5). Several rotation sweeps given together are merged as one dataset (--sweeps joint, the default).

Model: validation and molecular replacement. Only with a model (--model or --mr, PDB or mmCIF). With --model the model is placed as a rigid body and checked against a null; where that does not place it, or the model is a prediction, it is placed by molecular replacement instead, and --mr goes to molecular replacement straight away. The search places as many copies as the cell holds, in every space group the merge cannot tell apart and in the twin hypothesis’ subgroup; the placed model then gives R-work/R-free and σA-weighted maps. The model never changes how the data are processed (Model and reference, §14). It runs on every GPU of the machine, and on a Mac its model density and rotation function on the Apple GPU (GPU data analysis).

Model: refinement. A placed model is then refined against the merge it was placed on (--no-refine skips it): its chains as rigid bodies and B per residue where that lowers R-free, then every atom’s position and B by a restrained maximum-likelihood refinement whose weights are chosen by R-free in short trials run side by side; the refined model gives its own maps and the blobs of unexplained density. Like the validation it decides nothing - the merge, R_WORK/R_FREE and the placed model’s files stay as they were, and the refined results are written beside them under REFINE_ (Model and reference, §15). On a GPU it takes seconds, with the weight trials spread over every card (GPU data analysis).

Write. The merged .mtz / .cif / .hkl, the unmerged MTZ and the results report land next to each other (Output files); with a model, the maps and the placed model are written too, and beside them the refined model, its maps and its blobs; where molecular replacement chooses another space group or the twin hypothesis’ subgroup, that merge is written beside the answer as <prefix>_mr.mtz/.cif with the model placed there, <prefix>_mr_model.pdb.

Stills instead. Serial data skip the two-pass machinery: each image is indexed independently (with the known-cell ffbidx indexer where a cell is given), partiality comes from a per-crystal orientation-tilt post-refinement rather than a rocking curve, and where the lattice admits a merohedral indexing ambiguity the crystals are put into one indexing before the first merge: from the data alone, each crystal into the indexing in which it agrees best with all the others, where the space group is given (-S); or per image against a reference or a model, which then decides the indexing the merge is written in. Either way a crystal’s own refined cell is weighed beside its intensities, as far as the run’s cells tell the indexings apart (Advanced ▸ the indexing ambiguity). The input may be several files given together - Jungfraujoch masters, or the files an XFEL pipeline writes, read without a geometry file (Serial XFEL inputs). Before the images are processed the beam centre is decided on a sample of frames, the file’s against the measured ones, and the detector distance is refined there too, on a given unit cell or, without one, on the cell the frames index to; the cell is a starting point the frames refine, and only the frames of its crystal form are merged. With a cell, the geometry refinement places each detector module as well (§1.4, §7.7). The report adds R_split and a CC1/2 from frame half-sets, as CrystFEL computes them (Report).

The stills pipeline: the beam centre (and, with a cell, the distance and the module placement) decided on the frames first, every image indexed on its own, the crystals put into one indexing where the lattice admits two, then scaled and merged together; with a model, the placement and the refinement follow, deciding nothing

\ No newline at end of file diff --git a/RUGNUX_REPORT.html b/RUGNUX_REPORT.html new file mode 100644 index 000000000..6169761bb --- /dev/null +++ b/RUGNUX_REPORT.html @@ -0,0 +1,59 @@ + The results report — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

The results report

<prefix>_report.txt records what the run determined, next to the reflection files. It is written on every --mode mx and --mode scale run that has an output prefix — there is no option to enable or disable it. Two cases follow from that:

  • An empty output prefix (-o "", the “compute the statistics, persist nothing” mode) writes nothing, the report included.

  • --no-merge still writes a report. It determined an indexing and a geometry result, and those are recorded; the merging section then says MERGE= NOT_PERFORMED rather than being omitted, so the absence is a statement and not something a reader has to infer.

The report is never allowed to fail a run: if it cannot be written (unwritable path, full disk) the failure is logged as a warning and the run finishes normally.

Exit status. Rugnux exits 0 when the run completed — everything it determined, declined to determine (CANNOT_DETERMINE) or warned about is in the report — and non-zero when the run stopped: unreadable input, no usable lattice, a -S group the indexed lattice cannot host, an indexer that could not run. The reason goes to the terminal, and the report may not exist in that case — so a script branches on the exit status first and greps the report second.

Format

The model is XDS’s CORRECT.LP: prose and tables a crystallographer reads top to bottom, with a structure a script can consume without parsing prose. Every line is one of three kinds — a KEY= value data line, a # comment, or blank — so grep -v '^#' leaves the data alone (since REPORT_VERSION= 8; before that, comment lines had no prefix).

  • KEY= value assignment lines. Every number worth extracting is one, so a consumer gets it with a single grep '^ISA= ' and never has to read a sentence. Key names are stable.

  • # comment lines — everything else: the prose, the section banners, and the fixed-width tables (stable header row; the resolution shells, the space-group candidates, the sweep-quality ranges).

  • # WARNING: lines, one per finding, in plain English: # WARNING: Frames 500-600 out of beam (10.1 deg, scale 0.12 and CC 0.30 of the run, 2% scaled). grep '^# WARNING:' finds every one.

The worked examples on this page are shown with the leading # stripped for readability; in the file itself every such line starts with #.

A quantity the run did not measure writes no key at all, and the fixed-width tables print - in its place. There is one rule and no placeholders — no nan, and no 0.0% that reads as a measured total failure — so a consumer must treat an absent key as not measured rather than assume every key it knows about is present. A measured value always prints, including a negative one. The keys a script meets this on first are SIGANO= and CC_ANOM=: a rotation merge measures them whether or not -A was given, but where no Bijvoet pair could be split in both hands — a stills merge without -A, or too few pairs — the quantity does not exist and the key is absent; COMPLETENESS=, MULTIPLICITY=, I_OVER_SIGMA=, R_MEAS=, CC_HALF= and WILSON_B= follow the same rule.

R_MEAS= is the ordinary R_meas, every observation counted once, as XDS and AIMLESS count it - the one to set beside theirs. R_MEAS_WEIGHTED= (and REFRES_R_MEAS_WEIGHTED=) weights each observation as the merge weights it - by 1/sigma^2 under the error model - with each reflection’s weights normalised to their effective number, so where a reflection’s observations share one sigma it equals R_MEAS=. A stretch the crystal barely diffracted over is in the merge at the small weight its scaled-up counting error gives it, and is in R_MEAS_WEIGHTED= at that weight too, rather than setting the number with its noise; a large gap between the two says weak frames are kept at low weight. MULTIPLICITY= stays a count of observations.

CC_HALF= is the standard CC1/2, as XDS, Aimless and DIALS report it and as the mmCIF item _reflns.pdbx_CC_half defines it: the observations of each reflection are dealt into two half-sets, each half is averaged with 1/sigma^2 weights, and CC1/2 is the plain Pearson correlation of the two half-set means, every reflection counted alike. The same holds for REFRES_CC_HALF=, the CC1/2 and CC* columns of every shell table and the mmCIF. The automatic resolution cut is fitted to a different, internal form of CC1/2, in which a reflection measured only on frames the crystal barely diffracted on counts less (FITTED_RESOLUTION_INTERNAL); FITTED_RESOLUTION is read off the standard one. On a sweep without a weak stretch the two agree.

R_MERGE= and R_PIM= are the other two merging R-factors over the same observations as R_MEAS=: R_merge without the multiplicity correction, and the precision-indicating R_pim (Weiss, 2001), which falls as the multiplicity rises. CC_STAR= is CC* = sqrt(2 CC1/2 / (1 + CC1/2)) (Karplus & Diederichs, 2012), the estimated correlation of the merged data with the true signal; it is absent where CC1/2 is not positive. All three are also columns of the shell tables (R_merge, R_pim, CC*) and are written per shell into the merged mmCIF.

R_SPLIT= and CC_HALF_SPLIT= (and their REFRES_ forms) are written for stills only, with a “Serial statistics” table beside the shell table. Every frame’s observations go whole into one of two half-sets - as CrystFEL’s partialator deals out crystals - and R_split = (1/sqrt 2) sum|I_1 - I_2| / (1/2 sum (I_1 + I_2)) (White et al., 2012) and CC1/2 are taken over the reflections both halves measured, so both compare directly with CrystFEL’s compare_hkl. CC_HALF= deals each reflection’s observations out evenly instead, as XDS and cctbx do, and is the one the processing decides on; the two agree overall and can differ in a single shell.

R_MERGE=, R_MEAS=, R_PIM= and R_MEAS_WEIGHTED= are rotation statistics and a stills report has none of them, nor their REFRES_ forms or their columns in the shell tables (the mmCIF writes ? for them). On stills they would measure the scatter of partial observations scaled to full equivalents - hundreds of percent - not the error of the merged intensity. R_SPLIT=, CC_HALF=, CC_STAR=, CC_ANOM=, MULTIPLICITY= and I_OVER_SIGMA= are reported as on rotation.

OBSERVATIONS_REJECTED= counts the observations the merge’s outlier tests removed, and OBSERVATIONS_REJECTED_WILSON= the part of them the Wilson test took (each listed in the developer report). OBSERVATIONS_REJECTED_OVERLOAD= is separate from both: the rotation measurements left out because a pixel of the spot was overloaded on one of its frames, as XDS leaves out an overloaded reflection. Outlier rejection takes observations out of R_MEAS= and CC_HALF= too, so a run that rejects much scores better on both; read the counts beside them.

The first blocks of the report are the authorship, the acknowledgement and the citation: who wrote rugnux, its licence (GPLv3 — free to use for academic institutions and commercial companies alike) and where releases are published, then the credit to the X-ray research community whose methods rugnux implements and the open-source projects it is built on — both credited in ACKNOWLEDGEMENT.md beside LICENSE and THIRD_PARTY_NOTICES.md in the installed package, and the paper to cite when rugnux was useful (see Publications). rugnux prints the acknowledgement and the citation at startup as well.

REPORT_VERSION= is the format’s own version. Key names, table columns and the reason vocabulary below are an interface other software may depend on: they do not change without that number moving. Adding a key does not move it — a consumer that greps for what it needs is unaffected by one more line. It counts releases, not changes: it moves at most once per release, however many format changes that release carries, because a reader only ever meets the format that was released.

The header block above section 1 records how the result was produced: RUGNUX_VERSION= and RUGNUX_DOWNLOAD= (the release page of exactly that version), DATE=, INPUT_FILE= and OUTPUT_PREFIX=, plus

  • RUGNUX_GIT= — the commit the binary was built from, stamped at build time so it cannot go stale in a reconfigured tree; a -dirty suffix marks a build from uncommitted changes.

  • BUILD_CXX_FLAGS= — the compiler flags of the build (NONE for a plain configure). The build is set up so that the CPU level it targets (-march) does not change the results, only the speed; where two reports of one commit still disagree, this is the first line to compare.

  • COMMAND_LINE= — the invocation as one shell-ready line, arguments containing spaces quoted.

  • WALL_TIME= — the whole invocation in seconds. It covers everything the process did, opening the file and setting up included, so it is a little larger than the Processing time written to <prefix>_log.txt, which starts once the analysis does.

  • GPU_COUNT= and GPU= — how many GPUs were visible and what they are, e.g. GPU= 4x NVIDIA A100-SXM4-80GB; several models on one machine are listed as separate groups. GPU_COUNT= 0 appears on its own, with no GPU= line, when nothing was visible — which is the first thing to check when a run took far longer than expected. Rugnux prints the GPU at startup (Compute), before the run, so a missing GPU can be caught while there is still time to stop. On macOS, where the Apple GPU (Metal) is used only for Bragg integration and parts of model validation and molecular replacement, the report has GPU_COUNT= 0 and the startup line and the log name the Apple GPU instead.

Rates, per-image costs and progress remain on stdout only.

Sections, in order: the SUMMARY (below), then 1. DATA SET AND GEOMETRY, on a joint merge of several sweeps 1b. SWEEPS (below), 2. CRYSTAL, 3. MERGED DATA, 4. DIAGNOSTICS and, only where a model was given (--model, --mr, or a model file among the inputs), 5. MODEL VALIDATION - which also holds the keys of molecular replacement and of the refinement where they ran. A --mode refine report has one section, 1. REFINEMENT. The numbering is contiguous, and the fifth section appearing renumbers nothing; a stage that did not run states that inside its section — MERGE= NOT_PERFORMED — rather than the section disappearing.

SPOT_RESOLUTION_ESTIMATE= in section 1 is how far the merged data are expected to reach, read off the found spots alone — no lattice, no integration, no merge — so it is there on a run that never merges, and on a run that does it can be read against INCLUDE_RESOLUTION_RANGE in section 3. It is a prediction, good to about 0.2 Å on rotation data; nothing is cut on it. It is not limited to what the detector records: where it reads finer than the high-resolution end of INCLUDE_RESOLUTION_RANGE, the crystal diffracts past the corner and the run was detector-limited.

SPOT_FALSE_PIXELS_LOOSENED= in section 1 is there only on a run that found no lattice at the spot finder’s operating point (--spot-false-pixels, noise pixels tolerated a frame) and was made again at ten times it: the operating point the result was found at. On a weak sweep the default finds a handful of spots a frame, too few to index; ten times the noise pixels still leaves the spots mostly the crystal’s.

JFJOCH_DATASET_SETTINGS= in section 1 is the geometry the run integrated at — on a rotation run the post-refined one — written as the object jfjoch_broker takes it in: the four required properties of dataset_settings in broker/jfjoch_api.yaml, joined by the three poni_rot*_rad angles whenever any of them is non-zero (a body without them states a flat detector), on one line of valid JSON, so a refined beam centre and distance can go back to the instrument for the next collection without anyone retyping them.

JFJOCH_DATASET_SETTINGS= {"beam_x_pxl": 2078.24, "beam_y_pxl": 2233.92, "detector_distance_mm": 190.311, "incident_energy_keV": 12.4000}
+
grep '^JFJOCH_DATASET_SETTINGS=' out_report.txt | cut -d' ' -f2- > geometry.json
+

The beam centre in the file. Section 1 sets the file’s centre beside the two the run measured: FILE_DIRECT_BEAM= is where the input file puts the direct beam (its beam centre, under its own detector tilt), BACKGROUND_DIRECT_BEAM= where the scattered background puts it, with the fit’s sigma (the pre-scan’s beam-centre check), and BEAM_CENTRE_SHIFT= how far the centre the result was integrated at (DIRECT_BEAM=, the refined one on a rotation run) lies from the file’s, in pixels. BEAM_CENTRE_TOLERANCE= is how far this crystal on this geometry lets the centre be wrong - the displacement at which the accumulated reflections of the longest cell axis smear to 70% of their height, the number the log’s Beam centre check line states, here on the run’s own cell. Where the shift is more than three times that, a BEAM_CENTRE_OFF warning gives the file’s, the refined and the background centre, the difference in pixels and millimetres, and the value to correct the beamline (or the header) to: the run itself integrated at the refined centre, but every other program given the same file starts from the wrong one. A run that refined no centre (stills) is warned on the background alone, where its fit resolves the difference (three sigma) and the difference exceeds three times the tolerance, worded as a check. Between one and three times the tolerance the summary’s Beam centre line says so and recommends correcting the beamline value, without a warning - most headers are a few pixels off.

FILE_DIRECT_BEAM= 1564.31 1702.91
+BACKGROUND_DIRECT_BEAM= 1571.30 1699.85 0.62
+BEAM_CENTRE_SHIFT= 7.15
+BEAM_CENTRE_TOLERANCE= 3.49
+

XDS GEOMETRY KEYWORDS, the section after section 1, is the same geometry as the XDS.INP keywords that carry it, ready to paste into an XDS run: ORGX/ORGY (the PONI, numbered from 1 as XDS numbers pixels), DETECTOR_DISTANCE, the detector axes DIRECTION_OF_DETECTOR_X-AXIS/Y-AXIS where the detector is tilted (they carry the tilt), INCIDENT_BEAM_DIRECTION with X-RAY_WAVELENGTH, and ROTATION_AXIS - the axis the run integrated at, negated, because XDS turns the crystal the other way about the axis it is given (checked with XDS IDXREF). Geometry only: XDS determines the cell and the space group itself. The lines carry a fixed prefix, so

sed -n 's/^# XDS.INP> //p' myrun_report.txt
+

prints them as XDS reads them:

ORGX= 749.15  ORGY= 817.32
+DETECTOR_DISTANCE= 175.668
+DIRECTION_OF_DETECTOR_X-AXIS= 1.000000 0.000000 0.000444
+DIRECTION_OF_DETECTOR_Y-AXIS= 0.000000 1.000000 -0.000976
+INCIDENT_BEAM_DIRECTION= 0 0 1  X-RAY_WAVELENGTH= 0.918400
+ROTATION_AXIS= 1.000000 0.000000 0.000000
+

The conventions are XDS’s own (W. Kabsch, “XDS” (2010), Acta Cryst. D66, 125-132 doi:10.1107/S0907444909047337); this section is the one place the run states them.

Which pass. A rotation run integrates twice — once at the geometry in the input file (the first half of the sweep but at least 120°, --prepass-fraction), then the whole sweep again at the post-refined geometry — and can integrate a third time if a guard rejects the second pass. There is one report, for the pass that became the canonical output, and PASS= / PASS_DECISION= (--developer) in section 1 say which pass that is and on what evidence, so no number in the file is ambiguous about which geometry produced it.

Not in the report: timing, frame rates, thread counts, per-image progress and library banners. Those are process, not result, and stay on stdout.

The headline keys

The keys most scripts read, by section; the rest of this page explains the ones that need it.

key

meaning

EXPERIMENT_TYPE

ROTATION or STILLS (section 1)

IMAGES_PROCESSED, WAVELENGTH

Images the run read, and the wavelength (Å)

OSCILLATION_RANGE, STARTING_ANGLE, ROTATION_AXIS

Rotation only: the per-image rotation the run integrated at (deg: the file’s, scaled where the run adopted a goniometer rotation scale), the first image’s angle and the axis

DETECTOR_DISTANCE, BEAM_CENTRE, DETECTOR_TILT

The geometry the run integrated at (mm; the point of normal incidence in pixels; the three PONI rotations in degrees) - on a rotation run the post-refined one, not the header’s

DIRECT_BEAM

Where the direct beam meets the detector under that tilt (pixels)

LATTICE_FOUND, UNIT_CELL_CONSTANTS, CELL_ESD

Section 2: whether a lattice was found, the cell (a b c α β γ, Å and degrees) and its e.s.d.s (below)

CELL_FORMS, OTHER_CELL_FORM_*

Stills: whether the frames on the run’s cell were one crystal form or two, and the other one, left out of the merge (below)

SPACE_GROUP_NAME, SPACE_GROUP_NUMBER

The space group the files are written in (below)

MOSAICITY_DEG

Rotation only (below)

MERGE

Section 3: PERFORMED or NOT_PERFORMED (--no-merge)

INCLUDE_RESOLUTION_RANGE

dmax dmin of the written reflections (Å), as XDS’s keyword

FITTED_RESOLUTION

Where the fall-off of the standard CC1/2 (the CC_HALF of the shell table) crosses the --resolution-cc-target - the number to quote; absent where the curve is not a fall-off (a RESOLUTION_FIT warning says why)

FITTED_RESOLUTION_INTERNAL

Rotation only, internal: the crossing of the automatic cut’s own fit, which weights each reflection by the scale of the frames it was measured on so that a weak stretch of the sweep does not drag it in. The written range (INCLUDE_RESOLUTION_RANGE) is cut from this one; on a sweep without a weak stretch it equals FITTED_RESOLUTION

RESOLUTION_CUT_PLAIN

Diagnostic, rotation only: the limit the cut would have written from the fit on the standard CC1/2. Nothing is cut at it

UNIQUE_REFLECTIONS, TOTAL_OBSERVATIONS, COMPLETENESS, MULTIPLICITY

Over the written range; completeness in percent

I_OVER_SIGMA, R_MEAS, CC_HALF, WILSON_B

The overall merging statistics; the shell table beside them is in the comment lines. R_MEAS (and R_MERGE, R_PIM) rotation only, R_SPLIT stills only

SIGANO, CC_ANOM, CC_ANOM_PAIRS, ANOM_MEASURABILITY, FRIEDELS_LAW

The anomalous signal: SigAno, the half-set anomalous correlation over the written range (standard AIMLESS/phenix definition; it can read negative on strong data whose Bijvoet mates are recorded together, so it is quoted, not decided on) with the number of Bijvoet pairs behind it, phenix.xtriage’s measurability, and whether -A was given (FALSE with it). On rotation data the merge is the same either way, Friedel mates merged, and the ANOM_* keys count it per hand on every run; on stills FALSE means the hands were merged apart

ERROR_MODEL_A, ERROR_MODEL_B, ISA

The error model in XDS’s convention and ISa = 1/sqrt(a·b); ISA= undetermined where b is zero within its error, so 1/b would be noise. Rotation only for ISA

ISA_LOW, ISA_HIGH

Rotation data: the 95% interval of ISA from a bootstrap over the reflections (100 replicates, fixed draws). With ISA= undetermined, ISA_LOW alone is a lower bound: b reaches zero inside its interval, so only ISa ≥ ISA_LOW is measured. Both absent where there is no fit to resample (b out of reach of the data, or a on its bound) and on stills, which write no ISA. ISA_ASYMPTOTIC (--developer) is the ISa of the strong-reflection tier alone

ERROR_MODEL_C

Stills only: the partiality term of the stills error model, σ² = a(σ₀² + b·I² + c·((1−p)/p)²·I²) in the same convention. A stills report writes no ISA (below), and ERROR_MODEL_B= undetermined where b is zero within its error

R_WORK, R_FREE

Section 5: the model as placed against these data (below); the refined model’s are REFINE_R_WORK/REFINE_R_FREE

R_FREE_FLAGS

Section 5: the free set both are read on - DRAWN by this run, inherited from the -z REFERENCE, or from the --free-flags FILE

The stills error model

A stills merge reports its error model as its terms, ERROR_MODEL_A, ERROR_MODEL_B and ERROR_MODEL_C, with σ² = a(σ₀² + b·I² + c·((1−p)/p)²·I²), p being the partiality of the observation: b is the systematic error of a fully recorded still and c the error a partial one adds. It writes no ISA. On stills 1/sqrt(a·b) is the I/σ ceiling of a single still observation under the stills model - the same frames processed as a rotation sweep read several times higher - so it describes the processing model more than the instrument and the crystal, and read on CORRECT.LP’s scale it would call good serial data useless. The serial figures of merit are R_SPLIT=, CC_HALF= and CC_STAR=. The mmCIF follows: _reflns.jfjoch_error_model_c instead of _reflns.jfjoch_diffrn_ISa.

The summary, and what the run decided

The file opens with a SUMMARY section, above everything it summarises, so that a run that produced garbage and a run that produced a textbook data set do not read alike for their first three hundred lines.

  • VERDICT= is a closed vocabulary — OK, WARNINGS, UNUSABLE, FAILED. FAILED means no lattice was determined or the run was cancelled (a sample with no crystal in the beam ends here, with NO_LATTICE, and the run exits with status 1); UNUSABLE means the data merged but carry no usable signal; WARNINGS means something else needs attention; OK means nothing did. It is decided from the warnings the rest of the report produced, so it introduces no new analysis and cannot disagree with the sections below it.

  • VERDICT_TEXT= is one to three sentences of free text saying the same thing in English.

  • PATHOLOGY_FLAGS= is the type of each condition that fired, from a closed vocabulary, so a consumer switches on a code rather than parsing a sentence: NO_LATTICE, INDEXING_AMBIGUITY, SYMMETRY_AMBIGUITY, CENTERING_UNTESTED, UNUSABLE_MERGE, LOW_COMPLETENESS, SWEEP_GAPS, GONIO_SCALE, SPINDLE_CAP, ANISOTROPY, TWINNING, PSEUDO_TRANSLATION, LATTICE_TRANSLATION, MODEL_HAND, MODEL_NOT_VALIDATED, MODEL_SPACE_GROUP, REFERENCE_MISMATCH, CANCELLED, RESOLUTION_FIT, FLIGHT_PATH, GEOMETRY_NOT_CONVERGED, SCALING_NOT_CONVERGED, HARMONIC_CONTAMINATION, SUPERCELL_POSSIBLE, MULTIPLE_LATTICES, LATTICE_EXPLAINS_FEW_SPOTS, CELL_FORMS, ICE_RINGS, POWDER_RINGS, BEAM_CENTRE_OFF, OVERLOADS, OVERLAPS, SWEEP_LEFT_OUT. NONE when nothing fired. A code appears if and only if its warning fired, so the flags and the WARNING: lines are two renderings of one list. Thresholds are deliberately low: a warning is a prompt to check something, not a verdict, and some of them fire on data that turn out fine — the closed type for machinery, the open sentence for a person.

  • Below them, one line each, the facts a reader needs before reading further: space group, cell, mosaicity, the beam centre, the powder and ice rings, overloads, overlapping spots, multiple lattices, resolution, completeness, signal, anomalous signal, anisotropy, pseudo-symmetry, twinning, the indexing ambiguity of serial stills (Indexing ambiguity: how the data resolved it, in the terms of the AMBIGUITY_* keys below, or UNRESOLVED where the hands are mixed in the merge; the crystals left mis-indexed read in the merge as a twinned crystal population would, so a Twinning indication on stills points here), supercell, radiation damage and the sweep. The Anomalous line is decided by the model-phased anomalous difference map where a model was placed (its mean over the model’s anomalous scatterers, ANOMALOUS_SCATTERER_MEAN_SIGMA, and its strongest site or unexplained peak - section 5), and otherwise by the lowest shell’s SigAno against its noise floor of 0.80; it quotes the overall CC_ANOM but does not decide on it, which reads near zero or negative on strong sulfur signal and well above zero on data with no anomalous scatterer at all (a systematic Friedel difference reproduces between the half-sets as an anomalous one does). A line states a finding that is not a condition too - weak powder rings, a possible supercell no stronger than correct cells show, an arbitrary indexing choice (Indexing choice, a rotation sweep whose cell admits alternative indexing: one sweep is indexed consistently, so it matters only against other data; the operators are INDEXING_AMBIGUITY_OPERATORS= in section 2). On serial stills the same ambiguity mixes the hands in the merge. Where the space group was given (-S), the crystals are made consistent from their intensities against each other and their own cells, weighed together - and section 2 says so: INDEXING_AMBIGUITY_RESOLVED= data, AMBIGUITY_CRYSTALS= (the crystals that took part), AMBIGUITY_REINDEXED= (of them, the ones moved), AMBIGUITY_SEPARATION_SIGMA= (per crystal, how far its chosen indexing beats the best other one in correlation with all the other crystals, in sigma; the median) and AMBIGUITY_DECIDED_FRACTION= (the share of crystals decided at over 3 sigma). With a reference MTZ (-z) the reference fixes the indexing the merge is written in (INDEXING_AMBIGUITY_RESOLVED= reference); AMBIGUITY_CRYSTALS=, AMBIGUITY_SEPARATION_SIGMA= and AMBIGUITY_DECIDED_FRACTION= are given as above, and AMBIGUITY_DATA_DISAGREES= takes the place of AMBIGUITY_REINDEXED=: the crystals the data and their cells put into another indexing than the reference alone would. AMBIGUITY_TIME_S= (with --developer) is the time the resolution took. --mode scale resolves it the same way and writes the same keys. Where the space group was determined by the run instead, the mixed merge is an INDEXING_AMBIGUITY warning. INDEXING_RATE= - the share of frames the per-image indexer took - is a stills measure: a rotation run indexes the sweep as a whole, so there it is written only with --developer, and NO_LATTICE rests on whether the sweep was indexed.

  • WARNING_COUNT= and the WARNING: lines follow, in the same section. They are what they always were; they have moved from the bottom of the file to the top.

Then the numbered sections: 1. DATA SET AND GEOMETRY, 2. CRYSTAL, 3. MERGED DATA, 4. DIAGNOSTICS, and 5. MODEL VALIDATION only where a model was given.

Advice on the next collection

A warning says what is wrong with this data set; an advice says what to change at the next collection, and by how much. ADVICE= in the SUMMARY lists the advice given, as codes (NONE when there is none), and each has an Advice line among the summary’s facts - the same lines the CLI prints at the end of a run and the broker’s live status carries. Advice is given only where the evidence is firm and the gain worth a collection, so most runs carry none. Single rotation sweeps only: a joint merge of several sweeps gets none.

  • EXTEND_ROTATION - collect more degrees about the same spindle. Section 4 gives SWEEP_COVERAGE=, the percentage of the unique reflections to the signal limit (the completeness range of section 3) that the sweep as processed brought into reflecting position, in this crystal’s indexed orientation and point group, and SWEEP_COVERAGE_FULL_TURN=, the same for a full turn about this spindle. Both are geometry, exact up to the sampling of reciprocal space (well under 1 %); the merge’s completeness falls short of them by what the detector, the integration and the rejections lost. Advised when a full turn would add 5 % of the unique reflections or more; ADVICE_EXTEND_ROTATION_DEG= is the extension, continuing from the end of the sweep, that comes within 1 % of a full turn.

  • REORIENT_CRYSTAL - collect a second sweep with the crystal tilted against the spindle. Advised when SPINDLE_LOST_UNIQUE_FRACTION= (below) is 0.05 or more - the blind cone no length of sweep measures. ADVICE_REORIENT_TILT_DEG= is the least tilt of the second sweep’s spindle against the first that leaves under 1 % of the reciprocal space to the signal limit blind to both sweeps. It counts no symmetry, so it is enough for any point group, and it is the same in every direction of tilt (kappa, chi, or a re-mount).

Several sweeps merged as one

A run of several sweeps merged as one (--sweeps joint, the default with several rotation inputs, see Command-line options) describes the joint merge everywhere, and adds section 1b. SWEEPS; a run of one input has no such section and no such keys.

  • SWEEP_COUNT= the sweeps given, SWEEP_REFERENCE= the one (1-based) the others were put on the axes of - the one reaching the finest resolution among the sweeps whose error model resolved an ISa, ties broken by the higher ISa - and SWEEP_DECAY_MODEL= how the decay over the sweeps was modelled: dose-linear (a B rising along the dose order), per-sweep B (one B a sweep) or none, whichever predicted held-out frames better.

  • Per sweep k: SWEEP_k_INPUT=, SWEEP_k_IMAGES=, SWEEP_k_INCLUDED=; what the sweep gave processed on its own - SWEEP_k_SPACE_GROUP_ALONE=, SWEEP_k_CELL=, SWEEP_k_CC_HALF_ALONE=, SWEEP_k_COMPLETENESS_ALONE=, SWEEP_k_RESOLUTION_ALONE=; SWEEP_k_ISOMORPHISM_RATIO= / SWEEP_k_ISOMORPHISM_RATIO_SE=, whether it measures the reference sweep’s intensities: their correlation over what it would be for one set of intensities given each sweep’s own CC1/2 (CC_AB / (CC*_A CC*_B), Karplus & Diederichs 2012), on the reflections both have in the coarser half of their common range, with a bootstrap error - 0.997-1.001 for sweeps of one crystal or isomorphous crystals, 0.95-0.96 for non-isomorphous ones. SWEEP_k_DECISION= says what became of the sweep: reference (the sweep whose own merge reaches the finest resolution among those with an ISa, ties: the higher ISa, whose axes and cell the joint merge takes), isomorphous (ratio - 2 se >= 0.99: joined), not isomorphous (ratio + 2 se < 0.97: left out), doubtful: kept / doubtful: left out (in between, or too few common reflections for a ratio: decided on the merge), no axes (it could not be put on the reference’s axes) or no merge. For a doubtful sweep, SWEEP_k_HELD_OUT_CHANGE= / SWEEP_k_HELD_OUT_CHANGE_SE=: the median relative change of the held-out residual of the merge of the joined sweeps - each half of their observations predicted from the other half, without and with this sweep’s added, over the reflections it has, after a scale and B factor onto the reference - with its bootstrap error, and SWEEP_k_HELD_OUT_ADDED=, the unique reflections it adds to that merge; the sweep joins unless the change is above 1% two standard errors down; SWEEP_k_DISTANCE=, the detector distance its run ended at, and SWEEP_k_REPROCESSED_FROM= where the sweep was processed a second time (see RUGNUX_CLI): the distance its first run ended at; and, for a sweep in the joint merge, SWEEP_k_REINDEX_OP= (onto the reference’s axes) with SWEEP_k_REINDEX_CC= (the merged-intensity correlation under it), SWEEP_k_BATCH_FIRST= / SWEEP_k_BATCH_LAST= (its batches in the unmerged MTZ: sweep s of the merge is s * base + frame + 1, base the power of ten past the longest sweep), SWEEP_k_SCALE= (the median scale of its frames in the joint merge), SWEEP_k_RELATIVE_B= (its B against the joint merge, the least damaged sweep at 0), SWEEP_k_ISA= (the ISa of its own error model in the joint merge: each sweep’s observations are weighted under an error model fitted on their own scatter about the joint means, as XSCALE does per data set) and SWEEP_k_DOSE_RANK= (its place, from 1, in the dose order those B factors decide - not the order the sweeps were given in, nor their header times).

  • A sweep given but not merged - it gave no merge, could not be put on the reference’s axes, is not isomorphous, or was doubtful and hurt the merge - is named by a SWEEP_LEFT_OUT warning.

The reference-range table

--report-resolution <dmin>[,<dmax>] adds a second block of merging statistics to section 3, the REFRES_* keys and a second shell table, over the resolution range it is given rather than the range the run chose. It exists for comparison: another program’s table is at that program’s range, and running rugnux at that range (--scaling-high-resolution) is not the same run — the cut moves, and with it the symmetry decision and everything downstream of it. The reference table is instead the same merged reflections binned again, so nothing is processed differently whether or not it is asked for; the merged files and every decision are byte-for-byte the run’s own.

  • REFRES_RANGE= is the requested range (dmax dmin, as INCLUDE_RESOLUTION_RANGE; INF when the run has no low-resolution limit and none was given). REFRES_MEASURED_RANGE= is the coarsest and finest merged reflection that actually landed in it.

  • REFRES_COMPLETENESS=, REFRES_MULTIPLICITY=, REFRES_I_OVER_SIGMA=, REFRES_R_MEAS=, REFRES_CC_HALF=, REFRES_SIGANO=, REFRES_CC_ANOM=, REFRES_UNIQUE_REFLECTIONS= and REFRES_TOTAL_OBSERVATIONS= are the overall numbers over that range, under the same absent-when-unmeasured rule as their section-3 namesakes. REFRES_ISA= is the error model refitted on the reflections of this table alone, in XDS’s convention, so it reads against an ISa produced at that range; the table itself is merged under the run’s own model.

  • The table holds only what the run kept. Where the reference range is finer than the run’s own limit, the shells past that limit are empty by the run’s decision — it judged them to carry no signal and did not merge them — and are printed as past the run's own limit of X A: not merged (N possible) rather than as zeros; the shell the limit falls inside is marked. REFRES_SHELLS_PAST_LIMIT= counts those shells (0 when the range lies within the run’s own), so a consumer can tell not merged from a measured zero. REFRES_COMPLETENESS counts their reflections as missing; every other overall number is over the shells the run reached.

The shells are equal steps in 1/d² between the two bounds, as XDS’s are, so at XDS’s INCLUDE_RESOLUTION_RANGE the two tables read row for row.

The developer report

--developer renders the same report in full. The default report carries what a person deciding keep or recollect acts on; --developer adds the pipeline’s own internals — the anisotropy detection gate’s parameters, the space-group operator and candidate tables, the model-fit null, the sweep-quality internals, the twinning statistics measured before the search, and the long explanatory passages — plus advisories about the cut’s own behaviour that no user can act on.

Nothing is computed differently and nothing is lost by leaving the flag off: the report is built once, in full, and the flag selects how much of it is written. Every key the default report writes, --developer writes too.

The space group, and the Sohncke answer beside it

The space group lives in section 2: SPACE_GROUP_NAME= / SPACE_GROUP_NUMBER=, with SPACE_GROUP_ALTERNATIVES= naming the candidates the data could not separate — an enantiomorphic partner among them — and, on a group that has such a partner, SPACE_GROUP_ENANTIOMORPH= saying whether the hand is open (UNDETERMINED), asserted by the user (GIVEN), or taken from an accepted model (ASSUMED_FROM_MODEL).

Where the group written is a Sohncke group, SPACE_GROUP_ACHIRAL_ALTERNATIVES= names the groups with a mirror or an inversion centre that predict exactly the same absences (F 4 3 2 is written for rock salt; the line reads F -4 3 m | F m -3 m, and F m -3 m is the group the structure is refined in). They are not candidates the search weighed: a Sohncke group is written whenever nothing extinguished demands more, because a protein crystal can have no other, and nothing measured on intensities separates these from it. A sample that is not chiral - a salt, a small molecule - is refined in one of them, usually the centrosymmetric one. NONE where the Sohncke group has no such relative, or where a glide group was written.

SPACE_GROUP_SCREW_UNDETERMINED= names the axes whose screw these data could not decide at all, as one or more of a, b, c; when every screw the data could show was judged it reads NONE and, like the other keys whose answer is “nothing to report”, is written only with --developer. It fires when the axial row a screw lives on was never recorded — it lay in the spindle’s blind cone, or outside the resolution range — so nothing was measured that could confirm or refuse the screw. On such an axis SPACE_GROUP_NAME= is not an answer: the answer is that group or any of SPACE_GROUP_ALTERNATIVES, and no measurement in the run chooses between them. What is written to the .mtz/.cif/.hkl is unchanged — the member claiming no screw, because a reflection file must carry one group — and the report prints the axis, why the row could not be judged, and what the alternatives are. To settle it, record the missing row: a different crystal orientation, or a sweep that reaches it. With --developer the space-group section names the same axes in prose beside the per-zone screw table.

SETTING_OPERATOR= and SETTING_SOURCE= in section 2 say which axes the files are on: the reindexing operator from the axes the space group was determined on (CCP4 style, h,k,l where nothing moved) and what chose the setting - STANDARD, CELL (-C), SPACE_GROUP (a non-standard -S), MODEL (a --model that fits) or REFERENCE (-z). SPACE_GROUP_NAME, the cell and every file the run writes are in that setting (see The setting the files are written in).

SOHNCKE_SPACE_GROUP= in section 2 is written on every run whose space group was determined by the search; a run given its group with -S has no Sohncke candidate to name and omits the key. Where the search found a glide plane, SPACE_GROUP_NAME= names the group with it and this names the best group without - a crystal of chiral molecules, which is any protein, cannot have a glide plane or an inversion centre, so a reader who knows their sample is a protein reads this key and needs no second run. Where no glide was found the two keys read the same, deliberately: greppability is the point, and a key that appears only sometimes has to be tested for before it can be read.

SPACE_GROUP_CENTRE= says how the centre of symmetry of a glide group was settled; it is written only where a non-Sohncke group was adopted. IMPLIED_BY_ABSENCES - the group is centrosymmetric and no group without a centre predicts its absences (P2_1/c, Pbca, Ia-3d), so the screws and glides found imply the centre. ABSENT_BY_ABSENCES - the reverse (I-42d, Fdd2): no centrosymmetric group predicts these absences. NOT_DETERMINED - a group with exactly the same absences and the other answer exists (C2/c and Cc, Pnma and Pna2_1), and it is in SPACE_GROUP_ALTERNATIVES. Friedel’s law hides the centre from the symmetry of merged intensities, so the centrosymmetric group is written by default: a missed centre is the common error in small-molecule space-group assignment. ABSENT_BY_STATISTICS - the same situation, but the intensity distribution read acentric and the lattice ruled twinning out, so the group without a centre was written; CENTRE_TWINNING_EXCLUDED= says, for these two, whether the lattice ruled twinning out. Two non-centrosymmetric groups can also share absences (I-42d and I4_1md); the lowest-numbered is written and the other listed as the alternative.

CENTRE_STATISTICS_* are the intensity statistics behind that, read on every searched run on the general reflections - those no operator of the Laue class but the identity maps to themselves, which are centric exactly when the crystal is centrosymmetric; CENTRE_STATISTICS_REFLECTIONS= is how many there were. CENTRE_STATISTICS_L= is <|L|> (Padilla & Yeates; 0.5 acentric, 2/pi centric), CENTRE_STATISTICS_E2_MINUS_1= <|E^2-1|> (0.736 / 0.968) and CENTRE_STATISTICS_NZ01= N(0.1), the fraction with E^2 < 0.1 (0.095 / 0.248). Each has an _F beside it (CENTRE_STATISTICS_L_F=, _E2_MINUS_1_F=, _NZ01_F=) that places the statistic between the values the same reflections read when simulated acentric (0) and centric (1) with their own shell means and sigmas; CENTRE_STATISTICS_CONTROL_F= does the same for the reflections centric in every candidate, which must read centric. The statistics are written only where L-test pairs and control reflections were found. CENTRE_STATISTICS_VERDICT= is ACENTRIC when <|L|> reads _F <= 0.3 and the other two <= 0.5, NOT_APPLICABLE when any of the three falls outside -0.3..1.3 (a structure with a few heavy atoms on special positions reads beyond centric) or the control reads below 0.5, and INCONCLUSIVE otherwise. A twinned crystal reads acentric whether or not it has a centre, which is why the verdict decides only with twinning excluded by the lattice.

SPACE_GROUP_ENANTIOMORPH= in section 2 reads ASSUMED_FROM_MODEL when the hand written in the files is the model’s. Assumed, not determined: merged intensities cannot see the hand at all — |F| is invariant under the change of hand — so an accepted model asserts it out of prior chemical knowledge. It is only ever written where MODEL_FIT= ACCEPTED, and the anomalous difference map vetoes it outright where the map says the model and the data are in opposite hands. (Before REPORT_VERSION= 6 this value was spelled DETERMINED_FROM_MODEL and was emitted whenever a model file merely parsed.)

Sweep quality, the disposition, and their vocabularies

Section 4 lists the stretches of the sweep over which the crystal delivered much less than the rest of the run — the feedback a beamline control system needs to tell an operator that a crystal should be recentred or recollected — says what became of each of them, measures what keeping each one costs the merged intensities, and drops the stretches that cost too much.

SWEEP_QUALITY_STATUS= COMPUTED
+SWEEP_QUALITY_COUNT= 2
+SWEEP_QUALITY_REASONS= no_diffraction crystal_out_of_beam weak_diffraction loss_of_centring radiation_damage inconsistent_with_merge
+SWEEP_DISPOSITIONS= merged downgraded rejected
+FRAMES_MERGED= 1663
+FRAMES_DOWNGRADED= 101
+FRAMES_REJECTED= 36
+FRAMES_REJECTED_PCT= 2.00
+ROTATION_REJECTED_DEG= 3.6
+FRAMES_BLANK_START= 0
+FRAMES_BLANK_END= 0
+SWEEP_ROTATION= 180.0
+FLUX_PEAK_TO_TROUGH= 1.03
+SCALE_MODULATION_PEAK_TO_TROUGH= 1.00
+
+  FIRST_IMAGE   LAST_IMAGE   N_IMAGES  ROTATION  REASON                   SEVERITY   SCALE      CC   INDEXED  DISPOSITION  DELTA_CC_HALF  DELTA_CC_HALF_SE
+  -----------  -----------  ---------  --------  -----------------------  --------  ------  ------  --------  -----------  -------------  ----------------
+          500          600        101      10.1  crystal_out_of_beam          0.83    0.12    0.30      0.02  downgraded         +0.0004            0.0031
+          612          630         19       1.9  no_diffraction               0.98    0.02    0.00      0.00  rejected           -0.0481            0.0110
+  -----------  -----------  ---------  --------  -----------------------  --------  ------  ------  --------  -----------  -------------  ----------------
+

Of those keys, SWEEP_QUALITY_COUNT and the five disposition keys (FRAMES_MERGED, FRAMES_DOWNGRADED, FRAMES_REJECTED, FRAMES_REJECTED_PCT, ROTATION_REJECTED_DEG) and the two blank-end counts (FRAMES_BLANK_START, FRAMES_BLANK_END) are in the default report; SWEEP_QUALITY_STATUS, SWEEP_QUALITY_REASONS, SWEEP_DISPOSITIONS, SWEEP_ROTATION, FLUX_PEAK_TO_TROUGH and SCALE_MODULATION_PEAK_TO_TROUGH appear with --developer (the default report states in prose whether the diagnostic ran).

The three frame counts partition the sweep — every processed image is exactly one of them and they add up to the frame count — so FRAMES_REJECTED_PCT is the answer to “how much of this experiment was useless”. It is reported beside ROTATION_REJECTED_DEG on purpose: a percentage of frames moves when the same experiment is re-sliced, and a percentage of the rotation does not. The prose headline above the table states both.

Frames at either end of a rotation sweep that recorded no diffraction at all - a shutter that opened late or closed early, or a beam that went off - are left out before scaling and are not a degraded range: they raise no SWEEP_GAPS warning. FRAMES_BLANK_START and FRAMES_BLANK_END count them (they are also among FRAMES_REJECTED), and a prose line names them. A frame is blank when its reflections show no diffraction - as many stand more than 3 sigma above zero as below it, and that count is clearly below the run’s typical frame - and its background says the beam was off (nearer to none than to the run’s typical frame). A partly exposed frame recorded something and stays in; a crystal that has left the beam still scatters the beam into the background, so its frames stay too and are reported in the table above.

A SWEEP_GAPS warning is given, one per range, where the degraded ranges together cover at least 1 % of the sweep’s rotation; below that - a frame or two - they are in the table and the summary’s Sweep line, and the warning lines in --developer.

SWEEP_QUALITY_STATUS distinguishes COMPUTED (the diagnostic ran; a count of 0 means the sweep was clean throughout) from NOT_COMPUTED (it did not run — no scaling and merging, or stills data). A consumer must not read a missing table or a zero count as “clean” without checking it. SWEEP_QUALITY_REASONS lists the whole vocabulary this version can emit, so an unknown code is distinguishable from a missing one.

Reason code

Meaning

no_diffraction

The range recorded essentially no diffraction from the indexed lattice.

crystal_out_of_beam

Frames were lost: over the range a per-image scale could be fitted far less often than over the run.

weak_diffraction

The frames all still index, but with much less intensity — the cause was not determined.

loss_of_centring

One cycle of modulation per revolution: the crystal is off the rotation axis.

radiation_damage

The range runs to the end of a sweep whose quality was already decaying.

inconsistent_with_merge

The frames diffract as the run does, but their intensities do not agree with it — the only evidence is DELTA_CC_HALF, so the cause is not named.

The vocabulary is closed and stable: a code is never renamed, and never reused for a different meaning. New codes are only ever added, and adding one moves REPORT_VERSION at the next release.

The columns are: FIRST_IMAGE/LAST_IMAGE — inclusive, in processed-image ordinals (the numbering of <prefix>_plot.txt and of every other per-image array rugnux writes; with -s/--stride the source image is start + ordinal * stride); ROTATION — the width of the range in degrees; SEVERITY — the fraction of the run’s typical diffracting power missing over the range, 0 (as good as the run) to 1 (nothing at all); SCALE and CC — the range’s mean per-image scale and CC-to-merge relative to the run median; INDEXED — the fraction of the range’s frames that were scaled at all; DISPOSITION — what became of it; DELTA_CC_HALF and DELTA_CC_HALF_SE — what keeping it costs the merged intensities, and how precisely that is known. Every range also appears as a WARNING: sentence in the SUMMARY, with the same cost in words. A range is split where its disposition changes, so each row is wholly kept or wholly rejected.

The disposition column

Disposition

Meaning

merged

The frame’s observations are in the merged data at their own weight.

downgraded

They are in the merged data, but over a stretch the run itself flagged, carried at the reduced weight the frame’s own scale and sigmas give it. Nothing extra is subtracted: for weak-but-consistent data that reduced weight is the honest weight, and a second, invented per-frame weight would double-count with the σ’s.

rejected

Nothing of the frame reached the merge — because ΔCC1/2 convicted it, because an earlier guard dropped a frame whose scale had collapsed to an unusable number, or because the frame recorded nothing to drop in the first place. To a user asking how much of the experiment was useless these are the same answer, and the REASON column separates them.

DELTA_CC_HALF is ΔCC1/2: the overall CC1/2 of the merged data with the range minus the CC1/2 without it, evaluated over the reflections the range touches. Negative means keeping the range makes the merged intensities worse. It is computed in the σ-τ form — no random half-dataset split, so the same input gives the same answer every run — with each reflection’s error variance taken from the observed scatter of its own observations, not from the error model’s σ’s (a bad stretch claims the same σ’s as a good one, so an error-model estimate would read a stretch that adds noise as one that adds precision). It is a CC1/2 over the range’s own reflections, not over the whole dataset — a range that touches a few hundred reflections can carry a large ΔCC1/2 without the dataset’s headline CC1/2 moving by anything like as much. DELTA_CC_HALF_SE is the standard error of a CC1/2 on that many reflections, in the same units, and a ΔCC1/2 smaller than it says nothing.

A range is rejected only where ΔCC1/2 is both well below the rest of this run’s own batches and several standard errors below zero, and only where every frame in it is one the per-image channels call worse than the run’s typical frame — the scale and the CC to the merge, frame by frame and never as an average over the stretch, because an average cannot tell a uniformly bad stretch from a healthy arc lying beside a dead one. All three are needed: a healthy crystal merges at CC1/2 ≈ 0.999, where a harm of 0.001 in CC is already many standard errors, so significance alone convicts frames on clean data whose removal moves nothing; and ΔCC1/2 is itself measured against the merge, so removing whichever frames disagree with it most improves every agreement statistic whether or not anything was wrong with them — the decision has to be triggered by a channel that owes nothing to the merge, and only then confirmed by what the merge does. The test runs last, after the per-frame scale, the decay slope and the per-batch relative-B have been fitted, so it judges corrected data. The decision is taken over 10° batches — the same batches as the radiation-damage curve — and over those batches doubled, and doubled again, up to a quarter of the sweep: a defect much longer than a batch is invisible one batch at a time, because each batch inside it is judged against a merge that still contains the rest of the defect. Where the harm lies is then settled finely: each edge of the convicted stretch is slid frame by frame with the whole stretch re-measured at every position, so the range is reported where it actually lies rather than at the batch grid, and the reflection count the verdict rests on never shrinks with the edge. Each edge is then pulled back off any frame the per-image channels call normal, and what is left has to carry the verdict again on its own: a stretch that cannot be taken without healthy frames holds more than one thing and is not removed at all. A rejected stretch is never narrower than one rocking event, because the partials of one event are combined into the same intensities and inside it no frame can be judged apart from its neighbours. Never more than a quarter of the sweep is removed this way.

A stretch the per-image channels flagged — a range of this table, with neighbours closer than one rocking event joined — is then judged once more, taken whole, and here neither the quarter-sweep limit nor the run’s own batches apply: when the crystal dies half-way, or a second crystal or a slipped orientation takes over the second half of the sweep, the defect is most of the run, and the run’s own batches are no reference. The stretch is removed when keeping it lowers the plain CC1/2 (every reflection at weight 1, as the CC1/2 the report prints) by several standard errors, by at least 0.01, and by more than the spread of the batches neither channel flags (the same robust floor as above, measured on those batches alone; with fewer than three of them nothing is removed). The worst stretch goes first and the rest are measured again against what is left. Weak stretches that agree with the rest of the run — a crystal that leaves the beam and comes back — cost nothing on this measure and stay.

A stretch removed whole is then out of the data, not only out of this one merge: the per-frame scales, the correction surfaces and the error model it was judged on were all fitted with it in. So the first merge that may be written and removes one takes its frames’ reflections out — they are in no later merge and in no file written from the integrated reflections — and makes itself again from the start without them; the run’s own batches are then judged again on what is left, which can remove more. The stretch stays in this table at the scale, CC and ΔCC1/2 it was removed on. Its warning names it as the frames to process on their own (-s <first> -e <last + 1>, file images): it may be another crystal, radiation-damaged or dead data.

What ΔCC1/2 cannot do, because the report must not imply otherwise:

  • it says nothing about the cause: a shutter fault and a crystal that slipped have the identical signature, both integrating background, so the cause comes from the REASON column and never from the ΔCC1/2 itself;

  • a second lattice entering is invisible to it: those spots were never integrated, so they are not in the merged intensities it measures;

  • a centring drift that is pure attenuation reads ≈ 0. That is the right answer, not a blind spot: the data are weak but consistent, the σ’s already say so, and their ΔCC1/2 is the evidence that discarding them would cost completeness for nothing;

  • it is attributed to the frame carrying a rocking event’s peak partial, so it cannot resolve a single frame: a stretch narrower than one rocking event is never rejected, and the edges of a rejected stretch are soft to within half an event;

  • loss_of_centring needs ≥ 350° of sweep to be named at all. On a 90° sweep the same drift is still detected, only as crystal_out_of_beam or weak_diffraction — “cause not determined” here means this sweep cannot determine it, not that it is undeterminable.

The same finding is written per image into the _process.h5 as /entry/MX/sweepQuality and /entry/MX/frameDisposition, when one is written — see HDF5.

SPINDLE_SYMMETRY_AXIS_ANGLE_DEG= and SPINDLE_SYMMETRY_AXIS_ORDER= (--developer) in section 4 say how the crystal sat on the goniometer: the angle between the spindle and the nearest symmetry axis, and that axis’s order. They are descriptive: neither convicts nor clears the mounting on its own, because an aligned axis of any order maps the sweep’s blind cone onto itself while an axis near perpendicular does the same only when it is a lone 2-fold, and only the nearest axis is reported. (New in REPORT_VERSION= 7.)

SPINDLE_LOST_UNIQUE_FRACTION= in section 4 is the exact verdict the angle cannot give: the fraction (0-1, so 0.0300 means 3%) of unique reflections, to this run’s resolution limit, that the mounting made unmeasurable - the part of the sweep’s blind double cone that no operator of the measured point group maps onto measured territory, computed in the crystal’s actual indexed orientation. 0.0000 means the mounting cost nothing; the run warns when the group recovers less than half of the cone’s content. The same number is written to the master file as /entry/MX/spindleLostUniqueFraction, so a pipeline can read it from either output without parsing prose. Written on every rotation run that determined a space group and merged reflections.

Powder contamination

A crystalline phase other than the crystal, diffracting as rings among its reflections — hexagonal ice, a shower of microcrystals, a salt out of the cryoprotectant. It is measured on every run, in the pre-scan, from the spots found there, and reported whether or not anything acted on it: a user whose crystal sat in a powder is told so even where the run indexed perfectly well. Only hexagonal ice has rings that can be named in advance, so POWDER_RINGS_A is what this sample showed.

POWDER_RINGS_DETECTED= TRUE
+POWDER_RING_COUNT= 24
+POWDER_SPOT_FRACTION= 0.412
+POWDER_RINGS_SEPARABLE_TO= 2.31
+POWDER_RINGS_A= 3.897 3.671 3.447 ...
+POWDER_EXCLUDED_FROM_INDEXING= TRUE
+POWDER_INDEXING_D_MIN= 4.91
+

POWDER_RINGS_DETECTED is written on every merging run and is FALSE on nearly all of them; the rest of the keys appear only where rings were found. POWDER_SPOT_FRACTION is the share of the pre-scan’s spots the rings hold over the smooth fall-off around them — what the contaminant contributes, not what happens to lie in a ring band. POWDER_RINGS_SEPARABLE_TO is the resolution past which the rings crowd together too tightly to be told apart, and so the finest an indexing pass can be asked to trust on such a pattern; it is absent where they stay separable over the whole range, which is the ordinary case. POWDER_EXCLUDED_FROM_INDEXING says whether the run needed them left out to index at all (with POWDER_INDEXING_D_MIN the resolution the retried first pass used). Rings are detected far more often than they are excluded: exclusion happens only where a first pass found no usable lattice. POWDER_RINGS_ON_OWN_LATTICE counts the rings lying (within 1% of d) at d-spacings the indexed lattice itself diffracts at, and POWDER_RINGS_LATTICE_COVERAGE the share of the rings’ d range those d-spacings cover at that tolerance - what a match is worth. An ordinary small-molecule cell diffracts at nearly every d (coverage near 1: every ring matches, and the match says nothing); a tiny high-symmetry cell puts all of its own reflections, and those of every other grain and of any powder of the same phase, on a few d-spacings (coverage ~0.3), so where nearly every ring matches and the coverage is under 0.5 the POWDER_RINGS warning names the crystal’s own phase (more crystals, not a different one) rather than a contaminant. The rings are split between those on a hexagonal-ice position (POWDER_ICE_RING_COUNT=, POWDER_ICE_SPOT_FRACTION=) and the rest - a salt, microcrystals, another phase (POWDER_NON_ICE_SPOT_FRACTION=); the two fractions add up to POWDER_SPOT_FRACTION=. The summary’s Powder line gives both. A warning under the ICE_RINGS flag is given where the ice rings hold at least 5 % of the spots, and one under POWDER_RINGS where the other rings do.

Hexagonal ice is also measured by the merge itself, which leaves reflections on the ice rings out of scaling where it finds ice and, on rotation data, decides ring by ring what the merge does with them:

ICE_RINGS_DETECTED= TRUE
+ICE_RING_SCORE= 2.69
+ICE_SPOT_RATIO= 1.08
+ICE_REFLECTIONS_ON_RINGS_PCT= 25.7
+ICE_RING_BAND_01= 3.895 LOW_FLANK MERGE 42 -1.1 0.81
+ICE_RING_BAND_02= 3.895 CORE MERGE 52 +1.0 2.59
+ICE_RING_BAND_03= 3.895 HIGH_FLANK MERGE 43 -2.0 0.94
+ICE_RING_BAND_04= 2.249 CORE REJECT 135 -5.4 7.83
+

ICE_RING_SCORE= is the strongest ice ring over the smooth radial background (fine-grained ice that makes a smooth ring), ICE_SPOT_RATIO= the pile-up of found spots on the ring positions against the ice-free flanks beside them (ice in large crystallites); 1 is no ice on either. ICE_RINGS_DETECTED= is TRUE where either passes its gate (1.5 and 2.0), and ICE_REFLECTIONS_ON_RINGS_PCT= is then the share of the integrated reflections set aside from scaling. ICE_RING_BAND_nn= (rotation only) is one line per band of a ring - its core, within 0.01 Å\(^{-1}\) in \(q\) of the ring, and on each side an inner flank out to 0.02 and an outer one out to the flag width (a ring’s shoulder reaches into the inner flank, so it is judged apart from the outer): the ring’s \(d\) (Å), the band (CORE, LOW_FLANK, LOW_OUTER_FLANK, …), what the merge did with its reflections (MERGE, DOWN_WEIGHT, REJECT), how many merged reflections it holds, their bias against the off-ring reflections around the ring in standard errors, and the ratio of their variance to those reflections’ (both on intensities normalised by a local Wilson fit). A band is rejected where it is biased beyond 3 standard errors, down-weighted where it is only noisier beyond 3, and merged otherwise.

Ice is also looked for in the merged intensities themselves, on every written merge and whether or not the images showed a ring - a ring too weak or too diffuse for the radial profile still leaves the reflections on it too strong:

ICE_INTENSITY_Z= +8.4
+ICE_INTENSITY_BIAS_Z= +8.2
+ICE_INTENSITY_RINGS= 6
+ICE_INTENSITY_RING_01= 3.895 182 1.03 +1.2 1.02
+ICE_INTENSITY_RING_05= 2.249 551 1.31 +5.8 0.90
+

ICE_INTENSITY_RING_nn= is one line per hexagonal-ice ring the merge reaches: the ring’s \(d\) (Å), the merged reflections in its core (within 0.015 Å\(^{-1}\) in \(q\)), their mean intensity over a Wilson line fitted to the off-ring reflections within 0.15 Å\(^{-1}\) of the ring, that excess in standard errors of the core’s own scatter, and the same mean over the ring’s flanks (0.015-0.03 Å\(^{-1}\)). The comparison is local in resolution, so anisotropy and the curvature of the Wilson plot cancel, and a small cell with few reflections per band is not read as ice. ICE_INTENSITY_Z= fits the cores against their flanks over all rings as one hexagonal-ice ring system, in proportion to the known line strengths, in sigma: a ring is narrower than the flank offset, while a feature of the Wilson plot broader than one moves core and flanks alike and cancels, so a strong shell that happens to sit on one ring position does not pass as ice. Its sign says which way the integration bent the ring - positive where the ring under the spots lifted the cores, negative where the ring in the background annulus beside them depressed the cores and lifted the flanks. ICE_INTENSITY_BIAS_Z= fits the cores against the line instead, the size of the bias. The summary has an Ice line carrying both readings, and an ICE_RINGS warning prompts a look at the ice-ring shells where the merge found ice on the images, or where the intensities show the ring system at 5 sigma or more (either sign) over at least two rings although the images did not (one warning line, whichever measurement raised it). The measurement is described in CPU/GPU data analysis ▸ Resolution and ice-ring handling.

Overloads and overlapping spots

Two ways the measurement, rather than the crystal, cost reflections - each with what to change at the next collection. Both are in section 4, both have a summary line, and both warn at a low threshold.

OVERLOADED_REFLECTIONS= 1740
+OVERLOADED_REFLECTIONS_PCT= 0.017
+OVERLOADED_REFLECTIONS_LOW_RES_PCT= 0.418
+OVERLAPPED_REFLECTIONS_PCT= 11.10
+OVERLAPPED_REFLECTIONS_MAJOR_PCT= 0.44
+

(a strongly diffracting lysozyme sweep: an OVERLOADS warning, no OVERLAPS one)

OVERLOADED_REFLECTIONS= counts the integrated reflections - every frame’s partial, before the merge - with a saturated pixel in the signal disk (or one the detector could not count on that frame), and OVERLOADED_REFLECTIONS_PCT= their share. They are not measurements: the merge leaves them out (a rotation merge drops the whole rocking event, OBSERVATIONS_REJECTED_OVERLOAD= in section 3), and they are the strongest reflections the crystal gave, so they concentrate at low resolution; OVERLOADED_REFLECTIONS_LOW_RES_PCT= is their share among the reflections coarser than 4 Å. An OVERLOADS warning fires from 0.05% of all integrated reflections or 0.25% of those coarser than 4 Å, and recommends attenuating the beam or shortening the exposure (or a second, attenuated low-resolution sweep).

Stills are different: a still has no rocking event, and its overloaded observations are the fully recorded ones of the strongest reflections, so they are kept in the merge as a lower bound - the box sum with every saturated pixel at the saturation limit - and are not counted above. OVERLOADED_REFLECTIONS_KEPT= counts them and OVERLOADED_REFLECTIONS_KEPT_PCT= gives their share of the integrated reflections; the OVERLOADS warning fires from 0.05%.

OVERLAPPED_REFLECTIONS_PCT= is the share of the predicted reflections whose signal disk a nearer neighbour’s prediction takes pixels from, as the integrator’s overlap treatment (--overlap, default exclude) assigns them, and OVERLAPPED_REFLECTIONS_MAJOR_PCT= the share left with less than --overlap-minpk (default 75%) of the disk its own - the ones XDS’s MINPK would reject. Under exclude the shared pixels are left out of the profile fit, which keeps the reflection at a cost in precision. An OVERLAPS warning fires from 1% in the second number and recommends a longer detector distance, finer rotation slicing or a smaller beam. Neither key is written with --overlap off, which assigns no pixel to anyone.

Index-2 superstructure

On rotation data, section 4 reports whether the lattice the run adopted has intensity at half-integer positions it does not index. On 60 frames spread over the sweep, after each frame’s own integration, the lattice is predicted doubled along all three primitive axes and integrated to 3 Å; the reflections split into eight parity classes of h, k and l, of which 0 0 0 is the lattice itself and each of the other seven is one index-2 superstructure. The class read there is also followed out to the run’s own limit, counting only half-integer reflections that no lattice reflection on the same frame lies within the background radius of, each resolution shell against the median of the six other classes - which a single doubling leaves empty, so they measure what sits at a half-integer node without being a reflection. The log prints that table (Supercell probe to the limit).

SUPERCELL_CLASS= is the parity class with the most intensity over 20–3 Å. SUPERCELL_OCCUPANCY_PCT= is its mean intensity against the lattice’s own reflections on the same frames, and SUPERCELL_ROCK_PCT= (± SUPERCELL_ROCK_SE_PCT=) the part of it that follows the partiality the way a Bragg reflection does, from a fit I = a + b p over the class, on the same scale. SUPERCELL_I_OVER_SIGMA= is its mean I/σ. A class near zero on both is empty. One that is occupied and rocks holds reflections of a superstructure this cell does not index; SUPERCELL_DOUBLED_CELL= is the Niggli-reduced cell the lattice doubles to. One that is occupied but hardly rocks is diffuse or disordered intensity rather than Bragg reflections.

SUPERCELL_POSSIBLE= is TRUE where the class is measured (SUPERCELL_I_OVER_SIGMA= at least 0.5) and part of it rocks like Bragg reflections (SUPERCELL_ROCK_PCT= at least 2 %, three standard errors clear of zero). It says the doubled cell is there in the data, not that it is the cell to refine in: a crystal whose two halves are nearly alike (a pseudo-translation) is described by either cell, and spots of further lattice domains can land on the half-integer positions too. A TRUE is also a warning under the SUPERCELL_POSSIBLE flag, and the summary’s Supercell line carries the same advice.

Both cells merged. Where the class stands clear of the six empty ones out to the limit (in at least three shells where it is measured above its noise and most of its reflections are resolved from the lattice’s, at more than twice the strongest of them in standard errors) and grows significantly with resolution to a quarter of the lattice’s intensity or more in the finest shell both are measured in - the half cell holds at low resolution and not at high, the shape of a pseudo-translation breaking down - the run integrates and merges the doubled cell as well, on the same orientation and geometry, and decides with both merges in hand. The size of the class does not decide it - crystals deposited in the half cell carry classes as strong as one deposited in the doubled cell. The doubled cell is the answer where, in the doubled merge, one translation - half a cell plus a small offset, fitted over the class - modulates at least half of the added class in every resolution shell, so the two halves of the cell are one content displaced - and where the doubled merge is not more symmetric than the half cell’s, which a superstructure of it cannot be. A class that is there whatever the direction (copies that differ in content, twin domains, neighbouring reflections) keeps the half cell. It is also the answer where the class is not a superstructure of the half cell but part of its lattice: a quarter of the lattice’s intensity or more in every shell where it is measured, the coarsest included, so the half cell misses it at every resolution (the probe arm only; the doubled merge must again not be more symmetric). This is how the larger of two integer-related cells is adopted: the first pass keeps the smaller of such a pair, and the class the larger adds is read here. Where the doubled cell is that larger cell - one an indexing scheme of the run found as a lattice of its own - the translation test does not apply: the class growing to a quarter of the lattice’s intensity, or holding it at every resolution, decides it. The log also names every class that stands clear of its null; the classes a superstructure occupies form a group with 0 0 0, so where two do, their sum must as well - two that do not close mean the second is not the crystal’s, three that do describe an index-4 cell, which is reported and not merged. On a sweep too weak for the probe’s 60 frames to measure the lattice’s own reflections in any shell, the probe cannot read the rise; there the class only has to stand clear of the six empty ones, its z pooled over the shells from the coarsest down (at least two, a combined z of 5 and twice the strongest empty class’s pooled the same way), the doubled cell is merged, and the rise is read on the doubled merge instead - the added class against the lattice’s own mean intensity, shell by shell, with the same test - before the same symmetry test and the translation test decide. Such a sweep has too few added reflections to read the translation shell by shell (the probe arm needs at least 1000), so there the share it modulates is read over all shells at once and taken at its lower bound: it has to be at least half two standard errors down. DOUBLED_CELL_RISE_READ_ON= says which (PROBE or MERGE). DOUBLED_CELL_ADOPTED= says which was written as the answer and DOUBLED_CELL_DECISION= why; DOUBLED_CELL_OTHER_FILE= names the other hypothesis’s merged file (<prefix>_doubled.mtz, or <prefix>_halfcell.mtz where the doubled cell was adopted, with the rest of its files under the same prefix), and DOUBLED_CELL_OTHER_CELL=, DOUBLED_CELL_OTHER_SPACE_GROUP=, DOUBLED_CELL_OTHER_D_MIN=, DOUBLED_CELL_OTHER_CC_HALF= and, with --model, DOUBLED_CELL_OTHER_R_FREE= describe it. Compare the two in refinement.

Further lattices

On rotation data, once the first pass has its lattice, section 4 reports what the spots that lattice leaves over index to. Every spot of the spread and validation frames the main lattice takes is set aside; the rest, ice left out, go to a fresh rotation indexer. A lattice it finds is kept when the leftover validation spots sit on it far more often than they do with each frame’s spots displaced to another frame’s spindle angle - the null the first pass judges its own lattice against - by at least five standard deviations (EXTRA_LATTICE_<n>_Z=). Its spots are set aside in turn and the search goes on, up to three lattices. A lattice of the same cell within 1° of the main one is the main lattice’s own spots its tolerance missed, and is not listed. Nothing is decided on any of this: only the main lattice is integrated, whatever is found.

MAIN_LATTICE_SPOTS_PCT= and MAIN_LATTICE_INTENSITY_PCT= are the main lattice’s share of the non-ice spots of those frames and of their summed intensity; EXTRA_LATTICE_COUNT= is the number of lattices listed. For each, numbered from 1 in the order found:

  • EXTRA_LATTICE_<n>_KIND= — DOMAIN: the same cell, misoriented, over the whole sweep (a split crystal; more than 10° from the main lattice, the report calls it a second crystal); TWIN_DOMAIN: the same, turned by 180° (within 3°) — a non-merohedral twin domain; SEGMENTED: the same cell, with at least 60 % of its spots in 2 of 8 equal blocks of the sweep — the crystal in the beam changes along the rotation; RELATED_CELL: a cell whose volume is 1 to 8 times, or a 1/2 to 1/8 of, the main one’s — a question about the main cell (see the supercell keys above and the harmonic) rather than a second crystal; FOREIGN: an unrelated cell — a second crystal, or a main lattice that is not the crystal’s.

  • EXTRA_LATTICE_<n>_LATTICE= and EXTRA_LATTICE_<n>_CELL= — its crystal system, centring and conventional cell.

  • EXTRA_LATTICE_<n>_VOLUME_RATIO= — its reduced cell volume over the main one’s.

  • EXTRA_LATTICE_<n>_MISORIENTATION_DEG= — for the same cell only: the smallest rotation taking the main lattice onto it, over every basis whose metric matches, so a symmetry of the lattice is not read as a misorientation.

  • EXTRA_LATTICE_<n>_SPOTS_PCT=, EXTRA_LATTICE_<n>_INTENSITY_PCT= — its share of the non-ice spots and of their intensity.

  • EXTRA_LATTICE_<n>_SWEEP_CONCENTRATION= — the share of its spots in the 2 densest of 8 blocks of the sweep; 0.25 is uniform.

EXTRA_LATTICE_INTENSITY_PCT= sums the intensity share of the domains (DOMAIN, TWIN_DOMAIN, SEGMENTED); a RELATED_CELL or FOREIGN lattice is listed but not counted, since it is as often a wrong main lattice or tNCS as a second crystal, and MULTIPLE_LATTICES= is TRUE, with a warning under the MULTIPLE_LATTICES flag, where that sum is at least 10 % - the domains together, not the strongest alone. It is information, not a failure: a split crystal whose second domain is half as strong as the main one can still give data as good as XDS’s, since the domains’ reflections are only a problem where they overlap the main lattice’s. Look at the crystal, and at the result. The summary at the top of the report has a Multiple lattices line, none found where nothing was listed.

A warning under the LATTICE_EXPLAINS_FEW_SPOTS flag fires where MAIN_LATTICE_SPOTS_PCT= is under 50 and a listed lattice other than a domain (RELATED_CELL or FOREIGN) shares two of the main cell’s axes to 2 %. That is what the census of a cell with one axis wrong looks like - its spots along the missed row split into several leftover lattices with the same two axes and a different third - so check the cell. It also fires on correct cells whose leftover spots happen to line up along two of the axes.

Two crystal forms (stills)

A serial sample can hold two crystal forms of one protein whose cells are close enough to index on one cell. Merging both mixes two structures, so the merge keeps one form and leaves the other’s frames out (how the forms are told apart): without -C the major form, with -C the given cell’s. Section 2 then reports, on every stills run:

  • CELL_FORMS= — 1 or 2.

  • OTHER_CELL_FORM_FRAMES=, OTHER_CELL_FORM_FRACTION= — where there are two: the frames of the other form left out, and their share of the indexed frames on the run’s cell.

  • OTHER_CELL_FORM_CELL= — their mean cell, on the axes of the merged form’s cell.

A warning under the CELL_FORMS flag, the summary’s Crystal forms line and VERDICT_TEXT say so, with the -C to process the other form. UNIT_CELL_CONSTANTS= is the merged form’s own cell.

Cell e.s.d.s

CELL_ESD= (section 2, rotation only) is the standard uncertainty of each of the six numbers of UNIT_CELL_CONSTANTS=, in the units of that line (Å, degrees) - the number to set beside XDS’s E.S.D. OF CELL PARAMETERS in CORRECT.LP, and the one written as ZERR in the .ins and as _cell.*_esd in the mmCIF. A parameter the space group fixes (a right angle, γ = 120°) reads 0, and one it ties to another (b = a) has that one’s e.s.d.

It comes from the integrated observations the files are written from: every strong one (I > 3σ, unclipped, unsaturated, off the ice rings) gives 1/d at its observed centroid, which depends on the detector geometry but not on the crystal orientation, and q² = hᵀG*h is linear in the reciprocal metric G*. The components of G* the point group leaves free are fitted by least squares (one e.s.d. on q for every observation, those more than 4σ off rejected), the covariance is scaled by the goodness of fit and carried onto a, b, c, α, β, γ - CELL_ESD_LSQ=. Least-squares cell e.s.d.s are known to be too small (F. H. Herbstein, “How precise are measurements of unit-cell dimensions from single crystals?” (2000), Acta Cryst. B56, 547-557 doi:10.1107/S010876810000269X), as they see the scatter of the centroids and nothing that changes over the sweep, so the same fit is made on eight blocks of consecutive frames and the scatter of their cells, over √blocks, is CELL_ESD_BLOCKS= (where at least four blocks could be fitted; CELL_ESD_BLOCK_COUNT= says how many). CELL_ESD= is, per parameter, the larger of the two. CELL_ESD_REFLECTIONS= is the number of distinct reflections used and CELL_ESD_THETA_RANGE_DEG= their θ range, written as _cell_measurement.reflns_used, theta_min and theta_max in the mmCIF. With --developer, CELL_ESD_OBSERVATIONS= is the number of observations behind them and CELL_DSPACING_FIT= the cell the d-spacing fit itself returned.

The least-squares fit frees the detector distance alongside the metric (a cell scale moves every spacing in proportion, a distance by cos²θ·cos 2θ of that, so the spacings measure the distance by how their residuals curve with 2θ), and CELL_ESD_LSQ= is the metric’s e.s.d. with the distance free: the distance’s uncertainty, as far as the spacings measure it, carried onto the cell through their correlation - near 1 at low angle, where it can make this the larger of the two estimates. The block fits hold the distance, which is common to every block. Neither includes the wavelength, which scales the whole cell, nor a distance error the spacings cannot see, so the e.s.d. is a precision, not an accuracy. Stills runs have no cell e.s.d.: the crystals’ cells differ from one another by more than any one of them is measured to.

Mosaicity

MOSAICITY_DEG= (section 2, and a Mosaicity line in the summary) is the mosaic spread the merge computed partiality from, on rotation data: Kabsch’s σ_M, the standard deviation (not the FWHM) of a reflection’s rocking curve in degrees, in the same partiality model as XDS - so it is the number to set beside XDS’s REFLECTING_RANGE_E.S.D.: the value under SUGGESTED VALUES FOR INPUT PARAMETERS at the end of INTEGRATE.LP, which CORRECT.LP repeats. It typically reads about 0.9× that value. XDS’s per-image SIGMAR column and the per-block CRYSTAL MOSAICITY in INTEGRATE.LP are a different number - they run about 1.35× higher - and are not the comparison. It is fitted on every frame by maximum likelihood from the rocking offsets of that frame’s 250 strongest indexed spots, with the energy bandwidth taken out where the beam has one (XDS keeps it in), and smoothed in frame order; the value is the median over the frames, with MOSAICITY_DEG_P10= and MOSAICITY_DEG_P90= for its spread. The per-frame values are the sigma_M_deg column of _plot.txt.

Translational pseudo-symmetry

Two copies of the contents of the asymmetric unit related by a pure translation that is not a lattice vector. It is the pathology that most reliably breaks molecular replacement, because the modulation it puts on the intensities is not in the search model. Section 4 reports it beside twinning, because the two interact. The algorithm is in CPU/GPU data analysis ▸ Twinning and translational pseudo-symmetry.

TNCS_DETECTED= is TRUE, POSSIBLE, FALSE, INCONCLUSIVE or NOT_MEASURED. The last two are not FALSE: NOT_MEASURED means the merge has too few reflections in 20–5 Å to compute the statistic at all (or the cell is too small for a translation between molecules), INCONCLUSIVE means the Patterson was measured but too few acentric reflections remain to test whether the vector it names modulates the intensities. Neither is a statement that the crystal has no pseudo-symmetry.

A warning under the PSEUDO_TRANSLATION flag is given wherever TNCS_DETECTED= TRUE or POSSIBLE and no model was placed in the run. It quotes the Patterson peak (TNCS_PATTERSON_PEAK_PCT=) and the modulation the detection stands on (TNCS_MODULATION=, or TNCS_MODULATION_AVERAGED=), and asks for the vector to be declared to molecular replacement. Where the run placed a model (MODEL_PLACEMENT= MR or RIGID_BODY) that has been done - the copies are in the placed model - so the finding is reported in section 4 and on the summary’s pseudo-symmetry line, and raises no flag, as a noticeable anisotropy does.

TRUE is a vector that modulates the intensities and a Patterson peak at it of at least 20 % of the origin, the height at which molecular-replacement programs correct for a pseudo-translation (Phaser’s default, and the one phenix.xtriage flags). Below that nothing in the data tells a weak pseudo-translation from two rotated copies that look alike at 20–5 Å, and nothing downstream needs it; such a vector is noted (TNCS_MODULATES= TRUE) and not flagged.

  • TNCS_PATTERSON_PEAK_PCT= — the largest off-origin peak of the native Patterson over 20–5 Å, as a percentage of the origin peak, counting only peaks farther than 15 Å from any origin-equivalent lattice point. TNCS_PATTERSON_PEAK_Z= scores it against TNCS_PATTERSON_NULL_PCT=, the same map recomputed with the intensities permuted within resolution shells. The null is per dataset and not a table: the noise floor of this statistic runs from about 1 % on a large merge to about 18 % on a small one, so no fixed percentage separates the two populations.

  • TNCS_VECTOR= (fractional; TNCS_VECTOR_LENGTH= in Å) is the peak vector refined against the intensities, and TNCS_MODULATION_DEPTH_PCT= the depth of the modulation along it as a Patterson height - the amplitude a of ⟨E²⟩ = 1 + a cos 2πh·u fitted over every acentric reflection of the modulation population, times ⟨cos² 2πh·u⟩, which is what the Patterson of an untwinned crystal reads at u (a at a half-integer vector, a/2 at a general one); under a twin it is the height the crystal has rather than the diluted one the twinned Patterson shows. With TNCS_CLASSES= LATTICE_AVERAGED the fit is over the class averaged over the images Ru, and where the crystal’s own symmetry carries u to vectors other than ±u the copy pairs at those images count towards it too: it then reads above the Patterson peak at u itself, by up to the number of such images (about 3x for a pseudo-translation off the axes of a trigonal crystal). It is a size for the detection, not a Patterson height to quote, and the warning quotes the Patterson peak. On a small cell, or one whose low-resolution reflections were lost to overloads, the band is thin and this is the better measure of how much of the scattering the translation relates. TRUE needs either of the two to reach 20 %.

  • TNCS_MODULATES= — whether the vector modulates the intensities: TNCS_CORRELATION=, the correlation between E² and cos 2πh·u over the acentric reflections beyond 4 Å (or the 2000 lowest-resolution ones where fewer lie there), must stand five spreads above TNCS_CORRELATION_NULL=, the same search run on the intensities shuffled within their resolution shells (median and spread over 20 draws). E² is normalised, and shuffled, within each shell split by the reciprocal axis h lies closest to, so that anisotropy is not read as a modulation along a vector near a lattice point. TNCS_MODULATION= is the profile’s depth, the ratio of the strongest to the weakest phase-class mean of ⟨E²⟩, and TNCS_MODULATION_NULL= what the shuffled searches reach; descriptive, not the decision.

  • TNCS_CORRELATION_AVERAGED= / TNCS_MODULATION_AVERAGED= (and their _NULL) — written only where the Patterson peak is significant but the vector’s own modulation is not: the same test with each reflection’s class the mean of cos 2πh·Ru over the lattice’s rotations R (its symmetry and every twin law the metric admits), against the same permutation null. A symmetry operator or twin law that carries u to a vector other than ±u averages the vector’s own classes - a perfect twin does so by construction - and this is the test that still sees the modulation then. TNCS_CLASSES= (VECTOR or LATTICE_AVERAGED) says which of the two a detection stands on; the L-test partner steps then keep the class of every image Ru.

POSSIBLE is a peak of 20 % or more that these data cannot establish: too few reflections in the band for the permutation floor to lie far below it (a 30 Å cell has about 150 there) and no significant modulation. The hypothesis is reported with what it rests on rather than dropped.

The vector is refined on the whole data, in order of h, and is good to about 0.01 fractional.

TNCS_PSEUDO_CENTRED= and TNCS_SUBLATTICE= are separate claims and are deliberately not merged. A vector that is a rational translation 1/q of the cell means the crystal is pseudo-centred; the cell itself is not in question, because the suppressed class is weak rather than absent and a smaller cell would contradict it. Only TNCS_SUBLATTICE= NEAR_EXTINCT_CLASS — the suppressed class almost gone — says the reported cell may be a supercell.

UNDECLARED_LATTICE_TRANSLATION= is a different finding, and is reported instead of a pseudo-symmetry rather than as one: a translation at which the Patterson reaches at least 75 % of the origin, UNDECLARED_LATTICE_TRANSLATION_PCT=. Near 100 % the merged data are invariant under it, and a translation the data are invariant under is a lattice vector by definition — so the centring or the cell is wrong, not the packing; an undeclared centring reads 83-102 %. Every one is a warning under the LATTICE_TRANSLATION flag, asking to check the centring and the cell; below 90 % the warning also names the other reading, a very strong pseudo-translation that molecular replacement needs declared, which refinement in the cell tells apart. It is what a centred lattice merged in P1 looks like, which --mode scale on a file with no space group produces by design. The pseudo-symmetry search continues underneath it, so a real pseudo-translation sitting under an undeclared centring is still found.

L_TEST_VS_TNCS= says how the twinning L-test beside it coped. A pseudo-translation u biases ⟨|L|⟩ upwards unless the partner reflection at h + s shares its class, which happens exactly when s·u is an integer; a half-integer u — a pseudo-centering — is preserved by the ordinary axis step of 2 and reads UNAFFECTED. Where it is not, the steps are restricted to those that do preserve the class (REPAIRED), and where no step does, UNREADABLE says the statistic was dropped from the twin verdict in both directions: it can no longer indicate a twin, and it can no longer be read as proof that there is none. The second moment then decides alone.

TWINNING_VERDICT= is NO_INDICATION, INDICATED (⟨|L|⟩ below 0.44, the phenix.xtriage convention, or the second moment low, where the lattice admits a twin law for the group), SYMMETRY_SUSPECT (⟨|L|⟩ below 0.42 where the lattice admits no twin law - a false adopted operator gives the same distribution), NO_TWIN_LAW (⟨|L|⟩ between 0.42 and 0.44 where the lattice admits no twin law: not a twin in this group, so the group may be too high, or something other than twinning narrowed the distribution) or NOT_READABLE. Whether a twin law is possible is read off the cell - a rotation of the lattice’s metric, within 3° obliquity, that the group lacks - not off the Laue class, so a pseudo-merohedral monoclinic or orthorhombic lattice admits one and a general one does not. ⟨|L|⟩ has a physical range: 0.5 untwinned, 0.375 a perfect twin, whatever the law. Where it reads below 0.375, or above 0.55 (on this merge or on the one before the space-group search), no twin fraction explains it - the statistic is distorted, by tNCS, anisotropy, overlapping reflections of a very long cell, or too few reflections - and the verdict is NOT_READABLE, with no warning: it says nothing about twinning, nor about the space group. The same verdict, and no warning, where the statistics rest on fewer than 50 L-test pairs and fewer than 50 reflections for the second moment (a few dozen unique reflections, as a tiny cubic cell gives): ⟨|L|⟩ over N pairs is known to 0.29/√N, so below 50 neither reading separates the untwinned 0.5 from a perfect twin’s 0.375.

Both statistics are read on the resolution shells whose intensities are measured - at least 85% of a shell’s reflections at I/σ above 3, the cut phenix.xtriage applies to its twin tests - because noise moves ⟨|L|⟩ the way a twin does: a pair of noisy intensities kept at I > 0 reads below 0.5, and shells admitted on a mean I/σ of 1 pulled untwinned crystals into the twin band.

TWIN_LAW_n= lists every twin law the lattice admits for the group (an hkl operator in the data’s basis, the one a twin refinement takes), each with the number of reflection pairs it relates, their median disagreement H = |I₁−I₂|/(I₁+I₂), the twin fraction 0.5 − H that implies if only twinning makes the pairs agree (the pairs are the stronger reflections, and untwinned crystals read up to about 0.25 on it), their intensity-weighted R and the correlation of their normalised intensities. Where the space-group search refused a higher group on its twin-immune zone, TWIN_LAW= headlines the law of that list whose pairs agree best, at its own fraction, and the mmCIF carries it as _pdbx_reflns_twin.

The twin hypothesis (TWIN_SUBGROUP_*)

Where the adopted space group may have absorbed a twin law - a twin gate of the space-group search refused it and was overruled, or a group above P1 was adopted on data that read twin-like before the search (L_TEST_MEAN_ABS_L_BEFORE_SEARCH) - the run also writes the same observations merged in a subgroup, as <prefix>_twin_<SG>.mtz and .cif in the subgroup’s standard setting, to the same resolution and with the same free set as <prefix>.mtz, the twin law in the mmCIF’s _pdbx_reflns_twin. A near-perfect twin of the subgroup predicts the same intensities as the higher group, and a refinement program can only twin-refine data merged in the lower group, so the file is there to refine against with the law where a model prefers it. The answer’s files and keys do not depend on it. At most one is written.

key

meaning

TWIN_SUBGROUP_FILE

The file written, <prefix>_twin_<SG>.mtz (and .cif beside it)

TWIN_SUBGROUP_SPACE_GROUP

The subgroup, as written

TWIN_SUBGROUP_LAW

The twin law on that file’s axes, as an hkl triplet

TWIN_SUBGROUP_FRACTION

The law’s fraction from the disagreement of the pairs it relates (1/2 − median H, Yeates’ H test): a lower bound

TWIN_SUBGROUP_ALTERNATIVES

Other confirmed subgroups that qualified; -S merges in one

Diffraction anisotropy

Section 4 also reports how much the fall-off with resolution depends on direction, and whether that is established above the data set’s own systematic error. It runs automatically on every merging run — there is no flag — and it is a description only: no intensity is corrected, no reflection is removed on a directional criterion, and the merged data and the written reflection files do not depend on direction at all. The algorithm is in CPU/GPU data analysis ▸ Diffraction anisotropy.

Two different quantities are reported and they are not interchangeable. ANISOTROPY_DELTA_B is a rate — the range of the principal components of the anisotropy tensor, on the ordinary crystallographic B scale, so it is directly comparable with phenix.xtriage’s B_cart, ctruncate’s anisotropic B and AIMLESS’s anisotropic ΔB. ANISOTROPY_D_MIN_PRINCIPAL is where the signal actually runs out along each principal direction. A crystal can have a large ΔB and almost no spread in directional limit, or the reverse.

key

meaning

ANISOTROPY_VERDICT

DETECTED | NOT_DETECTED | CANNOT_DETERMINE

ANISOTROPY_FREE_DIRECTIONS

Deviatoric directions the Laue class allows — 5 triclinic, 3 monoclinic, 2 orthorhombic, 1 tetragonal/trigonal/hexagonal, 0 cubic

ANISOTROPY_DELTA_B

The anisotropic ΔB (Ų), fitted on intensities with nothing dropped

ANISOTROPY_DELTA_B_LINEAR

The part of it that follows exp(−½ sᵀBs). This is the number the verdict is gated on, and the report says which of the two it is quoting

ANISOTROPY_PRINCIPAL_B

The three principal components, relative to the weakest

ANISOTROPY_D_MIN_PRINCIPAL

Diffraction limit (Å) along each principal direction — where ⟨I/σ(I)⟩ in a 20° cone about it falls through 2

ANISOTROPY_D_MIN_CENSORED

One flag per direction. 1 means ⟨I/σ(I)⟩ never fell through 2, so the limit is the edge of the measured data, a bound and not a measurement. The prose marks it with a <

ANISOTROPY_D_MIN_SPREAD

Range of the three limits — itself a lower bound if any is censored

ANISOTROPY_D_MIN_RATIO

The weakest limit over the best. The grade is read on it — small below 1.125, noticeable below 1.25, STRONG from 1.25 (the WARNING: line) — a ratio rather than a spread in Å, so that it means the same at every resolution

ANISOTROPY_SHAPE

LINEAR (a real Debye–Waller B) | FLAT (the deficit does not follow a B at all, so ΔB may be an under-estimate) | CONVEX (grows faster than a B can) | UNDETERMINED (the verdict moved on rebinning)

ANISOTROPY_FLOOR, ANISOTROPY_SIGNIFICANCE

The data set’s own systematic-error floor (Ų) and ΔBlinear over it. Banded: below 2 not established, 2–3.5 marginal, above 3.5 established, above 5 strong

ANISOTROPY_DETECTION_LIMIT

The smallest ΔB that could have been established on these data. It is set by systematic error, not by counting, so it does not improve with more reflections or a longer exposure

ANISOTROPY_N_OBSERVATIONS, ANISOTROPY_FORBIDDEN_Z, ANISOTROPY_SIGMA_SYSTEMATIC

The unmerged observations the floor was measured on, that measurement against its own counting noise, and the floor before the counting part is added back

The default report carries ANISOTROPY_VERDICT, ANISOTROPY_DELTA_B, ANISOTROPY_D_MIN_PRINCIPAL, ANISOTROPY_D_MIN_SPREAD and ANISOTROPY_D_MIN_RATIO; the rest of this table — the detection gate’s own parameters — is written with --developer.

CANNOT_DETERMINE is a real answer, not an evasion. The verdict is not measured against counting statistics — real data carry systematic error far larger than that, and gating on counting error reports anisotropy on data sets that have none. Instead the data set measures its own systematic error in the tensor directions its Laue class forbids, where the true value is exactly zero whatever the crystal is. Where that measurement cannot be made, the run says so and gives the reason: a triclinic Laue class (no forbidden direction exists), an observed rotation under about 90°, merged data at the noise floor, a scale model carrying no dose term (--no-scaling-corrections), or no unmerged observations. A cubic Laue class is different again — symmetry forces ΔB to be exactly zero, and the run says that rather than reporting a measurement.

Where anisotropy is detected and the weakest directional limit is at least 1.25 times the best (ANISOTROPY_D_MIN_RATIO), a WARNING: line says so, since refinement and map interpretation should allow for it.

Comparing ΔB with other programs. Expect phenix.xtriage (and any amplitude-based tool) to report a smaller anisotropic B: it converts to amplitudes and drops the non-positive intensities, and fits one Wilson curve over the whole range, which flattens the fall-off exactly where a direction is weak. Measured over the battery against the model-free fall-off of ⟨I⟩ in cones about the principal directions, rugnux’s ΔB follows that fall-off, while xtriage’s eigenvalue range sits a quarter lower on a typical crystal and four to eight times lower on one whose weakest direction stops diffracting inside the measured range; its value also shrinks the further the written data extend past that direction’s limit. The directional limits are the comparison to make — they reproduce the ellipsoid of a STARANISO-processed deposition of the same crystal to within about 0.1 Å per axis.

Model validation

Section 5 appears only where a model was given (--model, --mr, or a model file among the inputs). It reports the supplied model against the merged data — R-factors, maps, anomalous sites — and, separately, whether the data accepted the model at all.

The two are not the same question, and the report keeps them apart. The R-factors, the maps and the rigid-body placement describe the model: they are computed and reported whatever the answer, because a model that does not belong to this crystal still has an R against it, and that is the negative result. MODEL_FIT= is the answer, and it is what governs whether the model was allowed to change anything about the written reflections.

There is no threshold on R behind it. What a model that explains nothing reaches against a given data set depends on its atom count and B-factors as much as on the data, so the same model is refitted — and re-placed as a rigid body, exactly as the real one is — from MODEL_FIT_NULL_REPLICATES random orientations about its own centroid, and MODEL_FIT_SIGMA is how far the real fit sits above that distribution. The statistic is R-work, not R-free - not because nothing is refined against the working set (the placement’s six parameters are), but because every null replicate is placed the same way, so what they buy is bought on both sides and cancels; and it is decided on an order of magnitude more reflections than R-free.

That null is built for every model the rigid body is tried on, whether or not it claims anything about the written reflections, because its answer is also whether the model was placed at all (MODEL_PLACEMENT=): a model the rigid body does not place against its null - in the answer’s merge or in the twin hypothesis’ one - is searched for by molecular replacement instead. MODEL_FIT is the rigid body’s verdict and only ever that; it is absent where no rigid body was tried (a prediction, --mr) or its null could not be built.

key

meaning

MODEL_VALIDATION

PERFORMED | NOT_PERFORMED | CELL_MISMATCH (both with MODEL_VALIDATION_REASON, and no R-factors). CELL_MISMATCH: no change of basis (an axis permutation, a sign flip, I- against C-centred) carries the model’s cell onto the data’s within 5% in each length and 3 deg in each angle, and the two primitive cells differ in volume by more than that allows, so the model is of another lattice - a cell of another volume, an axis of another length - and is not put into the data’s cell to be scored (a centred description of the same primitive cell is not caught here); the reason names both cells. It is reported here only, not as a warning: it is about the model given, and the data’s VERDICT, PATHOLOGY_FLAGS and WARNING_COUNT do not depend on it. Molecular replacement is still tried, as for any model that is not placed as given

MODEL_PLACEMENT

RIGID_BODY (the model fits against its null in the answer’s merge or the twin hypothesis’ one) | MR (placed by molecular replacement) | NOT_PLACED (placed nowhere: the R-factors below, where the rigid body was tried, are its rejected placement’s, kept as the negative result, and no <prefix>_model.cif/.pdb, _maps.mtz or refined files are written)

MODEL_FIT

ACCEPTED | REJECTED — the rigid body’s verdict: whether the model may decide anything. Absent where no rigid body was tried

MODEL_FIT_STATISTIC

What the verdict was taken on; R_WORK

MODEL_FIT_VALUE, MODEL_FIT_NULL_MEAN, MODEL_FIT_NULL_SD, MODEL_FIT_NULL_REPLICATES

The real fit, and the null of the same model in random orientations. Absent with MODEL_FIT

MODEL_FIT_SIGMA

The real fit above that null, in its sample standard deviations. Signed. ACCEPTED from +4.51: 3 σ of the null, allowing for its mean and spread being estimated from nine draws (Student’s t). Absent with MODEL_FIT

MODEL_DECISIONS_TAKEN

NONE | ENANTIOMORPH | INDEXING | ENANTIOMORPH+INDEXING (the rigid body) | MR_ENANTIOMORPH (molecular replacement, which never reindexes)

MODEL_ENANTIOMORPH_ADOPTED, MODEL_INDEXING_OPERATOR

The two decisions individually; x,y,z is no reindexing

MODEL_CHANGE_OF_BASIS, MODEL_SETTING_AS_READ

Present only where the model was written in another description of the lattice (other axes, other centring, or another point group) and was put into the data’s to be scored. Where such a model fits, the data are then written in the model’s setting instead (SETTING_SOURCE=MODEL) and these keys are absent, since the model no longer moves. An alternative indexing of the same point group is settled here only where a reference MTZ (-z) has already fixed the data’s indexing; otherwise the data are reindexed into the model’s, and that is MODEL_INDEXING_OPERATOR

MODEL_INDEXING_MARGIN, MODEL_INDEXING_MARGIN_NULL, MODEL_INDEXING_MARGIN_SIGMA

Present only where a merohedral ambiguity was probed. The winner’s lead over the runner-up in R-free, against the lead a random placement of the same model produces

Where a twin hypothesis was written (above), the model is scored against that merge too - as merged, and as twinned by its law at a fraction scanned on the working set - and the maps and the placed model come from whichever merge the model fits better on R-free. MAPS_FROM= says which (MERGE or TWIN_SUBGROUP_MERGE), beside TWIN_SUBGROUP_R_WORK, TWIN_SUBGROUP_R_FREE, and, as twinned, TWIN_SUBGROUP_R_WORK_TWINNED, TWIN_SUBGROUP_R_FREE_TWINNED and TWIN_SUBGROUP_MODEL_TWIN_FRACTION. R_WORK/R_FREE above stay the answer’s merge’s. The model chooses the maps only: it never changes the space group or <prefix>.mtz. Where it also fits there against its null, it has chosen the subgroup, and that merge is written once more as <prefix>_mr.mtz/.cif with the model as placed there (MODEL_CHOICE_FILE_PREFIX= and MODEL_CHOICE_SPACE_GROUP=, by either route). With a model, the twin hypothesis’ merge is also made where a metric re-ask promoted the indexed lattice’s group, or where the model’s group has fewer rotations than the adopted one; made for that reason alone, it is written and reported only where the model chooses it.

Symmetry hypotheses of a refused promotion. Where the search refused a higher point group, the adopted group is one of several hypotheses the merged intensities cannot separate: the adopted group untwinned or twinned by a law of the refused group outside it, and each other index-2 subgroup of the refused group perfectly twinned by a law of its coset - each of them merges into the refused group alike. The report lists them, on every run, as SYMMETRY_HYPOTHESES= (their number) and SYMMETRY_HYPOTHESIS_<n>= <group> | <law or NONE> | ADOPTED / ADOPTED_TWINNED / SIBLING_TWINNED | TESTED_BY_MODEL / UNTESTED (TESTED_BY_MODEL only where the model was placed, MODEL_PLACEMENT= RIGID_BODY or MR: a rejected model leaves these lines as a run without one writes them); a sibling’s group is named by its rotations alone (symmorphic), its screws left to the model. They cost nothing without a model. With --model, where the model’s own group is a sibling’s (it has the sibling’s rotations on the data’s axes), that sibling’s merge is the twin hypothesis the model is scored on, exactly as a subgroup’s above, and the model is refined in its own group there. With a model that has no group of its own (a prediction, or --mr with coordinates without a cell), every sibling’s merge is searched by molecular replacement beside the answer’s.

The placed model is refined as the merge’s group holds it: in the model’s own group where that has the merge’s rotations (so the screws the merge’s label leaves open are the model’s), and expanded into the merge’s group where the model’s group has more rotations (each symmetry image the merge’s group lacks becomes an independent copy). Where the model fits both the answer’s merge and the twin hypothesis’ within 0.03 in R-free before refinement, and each merge’s group holds the model whole that way, both are refined, each with its own twin decision (below), and the refined R-free decides which the model chooses: the rival replaces the validation’s choice only where it refines better by 0.01, what two refinements of one model differ by from their paths alone. MODEL_CHOICE_DECIDED_BY= is VALIDATION or REFINEMENT; the rival’s RIVAL_REFINE_SPACE_GROUP, RIVAL_REFINE_MERGE, RIVAL_REFINE_R_WORK, RIVAL_REFINE_R_FREE, RIVAL_REFINE_TWIN (with RIVAL_REFINE_TWIN_LAW) and RIVAL_REFINE_REPLACED stand beside the REFINE_ keys of the one kept. MODEL_CHOICE_TWIN_LAW= is the law the model’s choice file carries (NONE without one). The model’s choice is refined against its own files by either route, molecular replacement’s included.

The null’s own numbers — MODEL_FIT_STATISTIC, MODEL_FIT_VALUE, the MODEL_FIT_NULL_* keys and the MODEL_INDEXING_MARGIN* keys — are written with --developer; the default report carries the verdict (MODEL_FIT, MODEL_FIT_SIGMA, MODEL_DECISIONS_TAKEN and the two decisions).

The anomalous difference map

Where the merge kept the Bijvoet pairs, section 5 reads the anomalous difference map (F(+) - F(-) on the model’s phases, ANOM/PHANOM in <prefix>_maps.mtz) twice: at the model’s own atoms, which names what carries the signal, and at its own peaks, which finds what the model leaves out - an ion or a heavy atom that is not in the model, or one the model names as a lighter element (a water at a metal’s site).

key

meaning

ANOMALOUS_BIJVOET_PAIRS

The Bijvoet pairs the map is made from

ANOMALOUS_SCATTERERS, ANOMALOUS_SCATTERER_MEAN_SIGMA

The model’s atoms from phosphorus up (S, metals, Cl, I, …) and the map’s mean height at them, in its rms: one number for how much anomalous signal the data carry

ANOMALOUS_SITE_01…_10

The ten model atoms the map is highest at, with the height. A dataset with no anomalous signal still lists ten; their height, a few σ at most, says so

ANOMALOUS_UNEXPLAINED_PEAKS

How many peaks of the map, each symmetry copy once, reach 5 σ with no atom of the model from phosphorus up within 1.5 Å

ANOMALOUS_UNEXPLAINED_PEAK_01…

Each of them, highest first, at most ten: its height, its position (Å, Cartesian, the copy nearest the model) and the model’s nearest atom with its distance

Comparing two runs: R_MODEL_SHELL_SCALED

R_WORK and R_FREE describe this dataset against this model, and that is all they describe. They are not comparable with another run’s. The model is scaled to the data by an overall factor and a symmetry-constrained anisotropic B — a shape that can only bend one way with resolution, kept that way on purpose so that a batch of maps stays on one scale (see CPU_DATA_ANALYSIS_DECISIONS). Whatever the amplitudes’ own radial profile does that this shape cannot follow is then reported as R. Two reductions of one crystal whose merged amplitudes have different radial profiles therefore differ in R_FREE for a reason that has nothing to do with either fitting the model better, and by more than a real change in the data moves it.

R_MODEL_SHELL_SCALED is the same sum with that taken out: one free scale per resolution shell — the merge table’s own shells — fitted on the shell’s reflections, so only the agreement inside each shell is left. R_MODEL is the same sum without the per-shell scale, so the gap between the two is what the radial profile cost, and MODEL_RADIAL_MISFIT is the size of the rescale that closed it (the RMS of ln kshell about its mean). When the misfit moves between two runs, R_FREE between those two runs cannot be read; R_MODEL_SHELL_SCALED can.

Both R values are over all the reflections, not the free 5%. Nothing here is refined — the coordinates, the B-factors and the occupancies are the model’s own, and only the scale and the placement are fitted (the refinement that follows is reported apart, under REFINE_*) — so work and free estimate the same quantity, and the split buys no cross-validation while costing a factor of √20 in precision.

None of this touches the maps: the map coefficients and R_WORK / R_FREE are computed from the scale described above and are unchanged by these keys.

key

meaning

R_MODEL, R_MODEL_REFLECTIONS

R over every reflection, on the scale the maps use

R_MODEL_SHELL_SCALED

The same, with one free scale per resolution shell — the number to compare between runs

MODEL_RADIAL_MISFIT

How large that per-shell rescale had to be: RMS of its logarithm. Near zero means the maps’ own scale already described the radial profile, and then the two R values agree

CC(model, data)

Beside the R-factors, section 5 carries the correlation of the merged intensities with the placed, scaled model, |Fmodel|², by resolution shell. The shells are the merge table’s own, so a row here can be read straight across from that shell’s CC1/2 and Rmeas in section 3. It is a correlation of intensities, like CC1/2 and CCref beside it, and the observed value is the merged intensity itself rather than the French–Wilson |F|² the R-factors use — that amplitude is a posterior mean under a Wilson prior, which pulls a weak reflection towards its shell mean and would show up as correlation in exactly the outer shells this number is read in.

The model is placed and scaled with eleven parameters, so there is no work/free distinction to draw: the correlation is formed on all the reflections of a shell, not only the few hundred free ones. Both sides are divided by the reflection’s symmetry enhancement ε, which they share whatever the model.

key

meaning

CC_MODEL_OVERALL, CC_MODEL_REFLECTIONS

The correlation over every reflection in the table, and how many — the N column sums to it. Like any overall correlation it is shell-weighted and can take any value between the best shell and the worst; the table is what to read

CC_MODEL_CONFIRMED_TO_D_MIN

The finest shell that, together with the shell coarser than it, reaches 3 σ, or NONE. A lower bound on the useful resolution

the D_MIN / CC_MODEL / N / CC_NULL / SIGMA / I/I_MODEL / R_FREE table

Per shell: the correlation, the reflections it was formed on, its null, how far above the null it sits, the mean intensity over the scaled model’s, and the shell’s part of R_FREE - the same placed, scaled model over the free reflections in the shell (- where the shell has none)

The null. A correlation above zero is not evidence on its own. The data and a scaled model share everything that is smooth in reciprocal space — the falloff across a shell, the anisotropic B (fitted to these very data) and the bulk solvent — whatever the model is, so the deposited model of an unrelated protein correlates with the data at 10–15 σ by Fisher’s transform in most shells. CC_NULL is the correlation of the data at h with the model at h + d, averaged over the 26 nearest lattice offsets d: it keeps what is smooth and loses what the model knows of h itself. SIGMA is (atanh CC_MODEL − mean atanh) / sd over those 26, the sd never narrower than Fisher’s 1/√(N−3). A shell confirms only beside a coarser shell that does as well: one shell alone clears 3 σ by chance among a dozen, while signal runs on over neighbouring shells.

Read it in one direction only. A shell whose correlation is significantly above its null carries signal the model accounts for reflection by reflection, so CC_MODEL_CONFIRMED_TO_D_MIN is evidence for keeping more data. A shell whose correlation is near zero says nothing about the data: the model may be incomplete, in the wrong hand, or simply wrong for this crystal, and cutting on it would be cutting because the model is poor. Nothing in the pipeline acts on these numbers; they are reported and no more. This is the same asymmetry cryo-EM works under, where the half-map FSC sets the resolution and the model–map FSC only validates it.

A significantly negative correlation in a shell is worth chasing rather than ignoring: it cannot be signal, so it points at a systematic error — an indexing the model disagrees with, or an outer shell the scaling has mistreated.

MODEL_DECISIONS_TAKEN= NONE means the reflection files are byte for byte what a run with no model would have written — same space group, same indexing, same .mtz, .cif, .hkl and _unmerged.mtz. A rejected model is therefore safe to try: it costs the null’s compute and changes nothing else.

Molecular replacement

A --model is placed by molecular replacement where it has no placement of its own - a prediction - or where the rigid body did not place it (MODEL_PLACEMENT= above), and --mr <file> takes a model there straight away, without trying the rigid body first. It runs in a full --mode mx run, rotation and serial stills alike; --mode scale places a model by the rigid body only. The search’s keys (MR_*) and its table are in 5. MODEL VALIDATION. Where it places the model, the R-factors, the maps and CC(model, data) of that section are of its placement, validated against the merge it was chosen on with nothing left to decide (the maps <prefix>_mr_* where that merge is <prefix>_mr); MODEL_FIT stays the rigid body’s. Where it does not, they stay the rigid body’s. Not placing a model is a result, never a warning. What kind of model it is is read from the file (MR_MODEL_KIND=): a prediction - ModelCIF’s _ma_qa_metric, or no cell and one B value per residue from 0 to 100 (an AlphaFold PDB or mmCIF) - has its residues below pLDDT 70 removed and its B-factors made from the pLDDT; anything else is an experimental structure, taken as its polymer only (no waters, ligands, hydrogens or alternative conformers) with its own B-factors, and a coordinate error of 0.67 A (a prediction’s at pLDDT 90) for sigma_A. A model whose expected log-likelihood gain - the sum of sigma_A^4 / 2 over the search’s reflections, one copy being the part of the scattering the most probable copy number by Matthews makes it - is below 10 is not searched for (NOT_PLACED). Then a rotation function over the point group (6 deg sampling, 4-12 A, each of the 50 best peaks refined off the sampling), a translation function for those orientations in every space group the merge cannot tell apart, and the best three placements per group that pack through the rigid body, bulk solvent and R-free (to SCORE_D_MIN, 3 A or the data’s limit). Further copies follow one at a time, up to the largest copy number with a Matthews probability of 1% (COPIES_LIKELY: the most probable): the translation function again with the copies already placed as a known partial structure, its peaks ranked by the likelihood gain of the new copy beside them (peaks that lower the likelihood dropped), each new copy refined beside the others held fixed, and kept where it stands out (below), it packs and R-free drops by 0.01 (COPIES, and MR_COPIES= for the group chosen). The groups are searched side by side; with tNCS, every group that placed fewer copies than the best one is searched once more with the best one’s copies’ orientations tried first, and the better search kept.

The likelihood is the log-likelihood gain of the Rice/Woolfson distributions of E_obs given E_calc, with sigma_A falling off with the coordinate error the pLDDTs predict and its scale refined against the data, summed to 2.5 A (or the data’s limit, or the 20000 lowest-resolution reflections in a large cell). A copy stands out where its translation-function Z-score reaches 8, or - only where the copies placed are as many as the cell most probably holds - where its likelihood after the rigid body reaches a Z-score of 8 over the same copy in the same orientation at random positions (LLG_Z; taken only where TF_Z is below 8). That second way in is what places a single copy in a small cell, whose few reflections keep the translation function’s own Z-score low. In P1 the first copy sits at the origin, which no function of its position can single out; it stands out where its rotation-function Z-score (RF_Z) reaches 8.

Where the AlphaFold DB’s predicted-aligned-error file sits beside the model under its own name (AF-<id>-F1-model_v<n>.cif and AF-<id>-F1-predicted_aligned_error_v<n>.json), the prediction is cut into rigid domains by average linkage on the PAE (domains a mean 10 A apart, of 40 residues or more; MR_PAE_DOMAINS=; a prediction only). Where the whole model is placed nowhere, each domain is searched by itself, side by side; the domains placed have to agree, and a domain alone can only confirm the answer’s group (AGREES), never change it (UNDECIDED otherwise).

A model of several chains is searched for as a whole and, beside it, one chain of each molecule in it by itself (the most complete of the chains with the same residue at every number they share), since the crystal may hold the molecules in another arrangement than the model has them in - another crystal form, or a tNCS the model’s crystal did not have. The chain’s search places its own copies (COPIES) by the same rules. The whole model’s choice stands unless a chain’s search chose a placement better by 0.03 in R-free, or the whole model chose none; the chains that chose have to agree on the space group. MR_SEARCH_MODEL= names what the decision was made with: the whole model, a chain (chain A, or chain A, one of 2 alike) or a PAE domain; the table is that search’s.

The table has one row per group and merge. A row is PLACED where one of its copies stands out, at most 5% of the C-alpha atoms clash with another copy or a symmetry mate (CLASH), and one copy fits the cell (MATTHEWS: Vm below 1.5 A^3/Da). The null - the same model refitted from random orientations, each placed by the translation function as the search placed the real one (each copy turned about its own centroid where there are several, so that the copies keep their arrangement) - is built for the candidate the choice falls on; its R-work has to beat the null’s by 4.51 sd (NULL_SIGMA: 3 sd allowing for the null being nine draws, as MODEL_FIT_SIGMA), and one that does not is marked NULL and the choice falls on the next. A placement clashing over twice the limit is not refined. Translational NCS is looked for in the native Patterson (a peak off the lattice of a fifth of the origin’s): with it, a group whose screw axes the tNCS translation turns into the chosen group’s (or the chosen group’s enantiomorph) and whose search placed fewer copies leaves the choice UNDECIDED, since one copy beside a translated twin of itself fits the data no better than at random - unless the chosen copies, carried into that group as they are and refined there, fit worse by 0.03 in R-free: where the translation does make up the difference between the groups, the copies build the same crystal in both. The group the merge was made in, searched to fewer copies than the chosen one, leaves the choice UNDECIDED too, whether it packs or not (its enantiomorph excepted, which the hand check decides). Where the tNCS vector v is half a lattice vector, the reflections with h.v half-integral are weak, and a placement moved by (v + o) / 2 (o an origin shift of the group) fits the strong ones exactly as well: the candidate the choice falls on is compared with every such move of itself, refined and packing, by R-work and R-free together over the weak reflections alone: the best there is taken where its |F_obs - F_calc| on those reflections is lower than every other’s by 3 standard errors of the paired per-reflection difference, and the choice is UNDECIDED only where it is not. The rotation and translation functions, the rigid body and the structure factors the R-factors are taken on run on the GPU where there is one (MR_SEARCH_DEVICE=). MR_DECISION= is then:

  • AGREES - the placed group with the lowest R-free is the answer’s, ahead of every other group of the merge that packs by 0.03 in R-free (with tNCS, see above). A group within 0.03 that placed as many copies has as many parameters, so it is compared on every reflection, work and free: it is ruled out where the chosen placement’s |F_obs - F_calc| is lower by 3 standard errors of the paired difference;

  • ENANTIOMORPH - it is the answer’s enantiomorph, and the answer’s files take that label (a label only, as with --model; no reflection moves). It is taken only by the rule a --model’s enantiomorph is taken by: the model has to fit against its null (the choice already required that) and model validation’s anomalous difference map, read at the placed model’s atoms, must not be inverted (MR_HAND_CHECK=, MR_HAND_FIT_SIGMA=, MR_ANOMALOUS_INVERTED=). Where it is not, the decision reads ENANTIOMORPH_VETOED and the label stays;

  • SPACE_GROUP - another group with the answer’s rotations; written as <prefix>_mr.mtz/.cif from the answer’s merge, the reflections that group extinguishes left out;

  • TWIN_SUBGROUP - the twin hypothesis’ subgroup: either no group of the answer’s merge can hold the model at all (MATTHEWS/CLASH in every row) and a group of the subgroup can, or the twin comparison chose it. The comparison runs where the answer’s merge chose a group and the twin hypothesis’ merge is there: on that merge, against its data as twinned by its law (the fraction refined on the working set), the chosen placement with all its symmetry images - the group’s crystal read in the subgroup - is scored against the model searched for afresh in the subgroup; the subgroup is taken where its own placement leads by 0.03 in R-free and passes the subgroup’s own choice (its null, its lead over the subgroup’s other groups). Written as <prefix>_mr.mtz/.cif from the twin hypothesis’ merge, with its law and fraction. With a model, the twin hypothesis’ merge is made wherever a metric re-ask promoted the indexed lattice’s group, so that the comparison can run - and, where that is the only reason it was made, written and reported only where the model chooses it;

  • UNDECIDED or NOT_PLACED - nothing is written.

With SPACE_GROUP and TWIN_SUBGROUP the placed model is written as <prefix>_mr_model.pdb/.cif. Apart from the enantiomorph label, the answer’s own files are never changed by the model.

Refinement (REFINE_*)

Where a model was placed and refined (Refinement; the algorithms in §15), section 5. MODEL VALIDATION ends with the refinement’s keys. In --mode refine they make up the report’s only section, 1. REFINEMENT, after MODEL_FILE=, SPACE_GROUP=, WAVELENGTH= and what had to be made of the input. No key outside REFINE_ reads the refinement: R_WORK= and R_FREE= above stay the model as placed, and so does every decision of the run. Keys marked dev are written with --developer only.

key

meaning

REFINE

PERFORMED | NOT_PERFORMED (with REFINE_REASON)

REFINE_DEVICE, REFINE_SECONDS

dev. GPU or CPU, and the time the refinement took

REFINE_D_MIN

The finest reflection refined against, Å

REFINE_ADP_INPUT

How the model’s displacements were read (§15.1): isotropic, ANISOU (its atoms’ own U), or TLS, B total / TLS, B residual (U from its TLS groups, its B column the total or the residual)

REFINE_R_WORK_START, REFINE_R_FREE_START

The model as given, scored as the refinement scores (riding hydrogens, its U as read, the fine solvent mask, the robust scale): REFMAC’s 0-cycle R-factors to about 0.002 on the same model and data. Not R_WORK/R_FREE, which are the validation’s own scoring of the placed model

REFINE_RIGID_BODIES

The chains moved as rigid bodies, where that step was kept (0: not kept)

REFINE_R_WORK_PLACEMENT, REFINE_R_FREE_PLACEMENT

After the placement stage (rigid bodies, then one B per residue, each kept only where it lowers R-free)

REFINE_R_WORK, REFINE_R_FREE

After the restrained stage: the refined model, the one written as <prefix>_refined_model.cif

REFINE_AS_GIVEN

TRUE where no refinement lowered R-free beyond the tie of the model as given, which is then the model written (as given, scaled to the data)

REFINE_RMSD_BONDS, REFINE_RMSD_ANGLES

The refined model’s rmsd from the dictionary’s bonds (Å) and angles (°); the weight is chosen within 0.02 Å and 2°

REFINE_RMSD_METAL_BONDS

The rmsd of the metal-donor bonds made from the model’s LINK records (those within the metal’s inner sphere), apart from the covalent bonds. Present where there are any

REFINE_RMSD_BONDS_START, REFINE_RMSD_ANGLES_START

dev. The same for the model as given

REFINE_CLASHES

Pairs of atoms in the refined model more than 0.4 Å closer than their contact distance (symmetry mates included)

REFINE_XRAY_WEIGHT

dev. The X-ray weight of the positions that was kept

REFINE_NCS_GROUPS

Molecules present more than once in the model (copies found by sequence alignment, §15.5 of the refinement reference). Present only where there are any, as are the other REFINE_NCS_ keys

REFINE_NCS_COPIES

The chains of those molecules

REFINE_NCS_CHAINS

The copies by chain name, = between copies of one molecule, e.g. A=B=C D=E

REFINE_NCS_RESTRAINTS

dev. The local distance restraints between pairs of copies

REFINE_NCS_SIGMA

The NCS restraints’ sigma (Å) the weight trials kept; 0: they were not kept, and the copies were refined independently

REFINE_NCS_RMSD_START

The copies’ C-alpha (P) rmsd after superposition (Å), averaged over the pairs restrained, before the restrained stage

REFINE_NCS_RMSD

The same, refined

REFINE_NCS_RELEASED

Residues of the refined model in which the copies differ: more than half of their restraints beyond the release distance (0.5 Å)

REFINE_ADP_MODEL

The displacement model the free set chose (§15.7): isotropic, the model's U held, TLS, <n> groups (...) or anisotropic

REFINE_ANISO_ATOMS, REFINE_TLS_GROUPS

The atoms of the refined model with an anisotropic U (ANISOU), and its TLS groups

REFINE_ATOMS, REFINE_ATOMS_REFINED

The model’s atoms (hydrogens not counted) and those refined: the atoms of the residues the dictionary describes, with an occupancy above zero

REFINE_RESIDUES_FIXED, REFINE_RESIDUES_FIXED_NAMES

The residues the embedded dictionary does not describe, held fixed but kept in the structure factors, the solvent mask and the clash terms, and their names

REFINE_BULK_SOLVENT_K_SOL, REFINE_BULK_SOLVENT_B_SOL

dev. The flat bulk solvent of the refined model

REFINE_TWIN

The twin hypothesis (§15.12): NO_TWIN_LAW (the lattice admits none for the group), FREE_SET_SPLIT (the free set splits the law’s twin pairs; not tested), ZERO_FRACTION, UNTWINNED (tested, not better), TWINNED (the refined model and every other REFINE_ key are of the refinement against the twinned data), NOT_TESTED

REFINE_TWIN_LAW, REFINE_TWIN_FRACTION

The twin law tested (an hkl operator in the data’s basis) and the fraction it refined to

REFINE_TWIN_SPLIT_PAIRS

Where FREE_SET_SPLIT: the twin pairs with one member in the working and one in the free set

REFINE_TWIN_R_WORK, REFINE_TWIN_R_FREE, REFINE_UNTWINNED_R_WORK, REFINE_UNTWINNED_R_FREE

The twinned and the untwinned refinement, each where it ended (its solvent built)

REFINE_TWIN_R_FREE_NULL

The twinned model’s R-free at its fraction with every mate replaced by an unrelated reflection of the same resolution and set: what averaging alone buys, and the like-for-like comparison for REFINE_TWIN_R_FREE. REFINE_TWIN_FRACTION_NULL (dev) is the fraction those unrelated mates ask for, about 0

REFINE_TWIN_NULL_Z

The law’s lead over that null on the free reflections, paired reflection by reflection (a free twin pair as one term), in standard errors; TWINNED needs 3, or 2 where the data read twinned (REFINE_TWIN_RULE)

REFINE_TWIN_RULE

Where UNTWINNED or TWINNED, the rule that decided (§15.12): NULL (the null alone, at 3 standard errors) or NULL+LTEST (taken at 2-3 standard errors because the merge’s L-test reads twinned as well: TWINNING_VERDICT INDICATED with ESTIMATED_TWIN_FRACTION_FROM L_TEST). In --mode refine there are no merge statistics, and it is always NULL

REFINE_TWIN_FREE_CLOSED

Where any moved: the reflections that changed between the working and the free set when the free set was closed under the lattice’s twin domains before both refinements (§15.12)

REFINE_TWIN_MULTI

Where the single law was taken and the lattice has more domains: MULTI_TWINNED (every domain refined at once is the result: REFINE_TWIN_LAW then lists every law, ;-separated, and REFINE_TWIN_FRACTION is their sum) or MULTI_UNTWINNED (the single law stands)

REFINE_TWIN_MULTI_DOMAINS

The domains of that refinement and their fractions, law=fraction, ;-separated, the adopted law first; where MULTI_UNTWINNED because every added domain fell below 0.05, as they refined before being dropped

REFINE_TWIN_MULTI_R_WORK, REFINE_TWIN_MULTI_R_FREE, REFINE_TWIN_MULTI_R_FREE_NULL, REFINE_TWIN_MULTI_NULL_Z

Where the domains kept were refined: that refinement’s R factors, its null (the added domains’ mates unrelated, the adopted law’s kept) and the added domains’ lead over it in standard errors; MULTI_TWINNED needs 3

REFINE_BLOBS

The blobs of the refined mFo-DFc map (above 3 σ, peaking above 4 σ)

REFINE_BLOBS_LIGAND, REFINE_BLOBS_WATER, REFINE_BLOBS_ION, REFINE_BLOBS_MODEL_ERROR

How many of them are read as each (§15.9); the rest are unassigned

REFINE_SOLVENT

PERFORMED | NOT_PERFORMED: the solvent build and audit of the refined model, off unless --refine-solvent is given; the other REFINE_SOLVENT_ keys and <prefix>_solvent.json only where PERFORMED

REFINE_SOLVENT_SITES

The waters and single-atom ions of the refined model the solvent audit scored (§15.10)

REFINE_SOLVENT_LABELS, REFINE_SOLVENT_BEST

How many of them carry each label (HOH 265 MG 42), and how many each species is the best-supported one for

REFINE_SOLVENT_DISAGREE, REFINE_SOLVENT_AMBIGUOUS

The sites whose best-supported species is not their label (water, Mg, Na, K, Ca or Cl), not ambiguously; the sites where the runner-up is within 2 of the best

REFINE_SOLVENT_IONS, REFINE_SOLVENT_IONS_DISAGREE

The same for the sites not labelled water

REFINE_SOLVENT_ADDED

Waters the water build added and still in the refined model, in a chain of their own (W, HOH residues; CPU_DATA_ANALYSIS_REFINEMENT §15.10). Present where the build ran: --refine-solvent, a restrained refinement to 2.8 A, not --refine-score-only

REFINE_SOLVENT_REMOVED

Waters of the model as given that the build took out (mFo-DFc at -3 sigma or lower at the water)

REFINE_SOLVENT_RELABELLED

Waters and single-atom ions the build relabelled as another species (water, Mg, Na, K, Ca or Cl) where their surroundings and density support it, not ambiguously; each, with the scores, in the report’s prose and in <prefix>_solvent.json. Not with --no-refine-solvent

REFINE_SOLVENT_NOT_SOLVENT

Difference-map peaks of the final model that cannot be a single solvent atom (bonded to the model, beside a displaced atom, a truncated side chain, a cluster or elongated density, denser than S and P): reported, not filled; each with its reason in <prefix>_solvent.json

REFINE_SOLVENT_BUILD_ROUNDS

The build’s rounds kept (at most two, within the weight search), each kept where refining the solvent it changed lowered R-free

REFINE_SOLVENT_BUILD_SECONDS

The build’s time: its maps, audits and refinements of the solvent (REFINE_SECONDS includes it too)

A prose paragraph after the blob keys lists the five strongest blobs with their reading, peak, volume, position, nearest atom and, where the merge kept the Bijvoet pairs, the anomalous difference map’s height at the peak (in its rms: an ion that scatters anomalously stands out there, a water does not); all of them are in <prefix>_blobs.json, strongest first, one object per blob: kind, centroid (Å, Cartesian, the copy nearest the model), peak_sigma, volume_A3, score_sigma_A3 (the density above the cutoff integrated), nearest_atom, nearest_atom_distance_A, polar_contacts, metal_contacts and anomalous_sigma.

A second paragraph, after the solvent keys, lists the ions, label → best-supported species, their N and O in the bands 1.9-2.3/2.3-2.6/2.6-3.2 Å and their neighbours closer than 3.4 Å. Every site is in <prefix>_solvent.json, in model order, one object per site: label, chain, seqid, altloc, xyz, occupancy, b_iso, sigma_xyz_A (the coordinate error assumed), bands (N and O by distance), donors, acceptors, donor_acceptors (closer than 3.4 Å), min_ligand_distance_A, nearest_positive_A, nearest_negative_A, positive_within_3.5, negative_within_3.2, nearest_ion_A, ions_within_4.2, ions_within_6, bvs and nvecsum (per cation: MG, NA, K, CA), map_sigma, difference_sigma, anomalous_sigma (null where there is no such map), score (per species), best, ambiguous, agrees and neighbours. Where the water build ran, a build object follows: rounds, added, removed, not_solvent, stop (why it stopped), seconds, and edits, one per water added or removed in the rounds kept and per not-solvent peak of the final model: kind (ADDED, REMOVED, NOT_SOLVENT), round, site (the water’s name, empty for a peak), xyz, difference_sigma, map_sigma, b_iso, elongation and reason.

The score of the refined model follows - the model written out, so REFINE_SCORE_R_WORK and REFINE_SCORE_R_FREE are REFINE_R_WORK and REFINE_R_FREE (where the model was only scored, the model as given; REFINE_R_WORK_START and REFINE_RMSD_BONDS_START are where a refinement began) - every term under REFINE_SCORE_: REFINE_SCORE_R_WORK, REFINE_SCORE_R_FREE, REFINE_SCORE_N_WORK and REFINE_SCORE_N_FREE by default, and with --developer the overall scale (REFINE_SCORE_K_OVERALL), its isotropic and anisotropic B (REFINE_SCORE_B_ISO, REFINE_SCORE_B_ANISO: B11 B22 B33 B12 B13 B23 less the isotropic part, Cartesian), the bulk solvent (REFINE_SCORE_K_SOL, REFINE_SCORE_B_SOL) and the spacing of its mask grid (REFINE_SCORE_MASK_SPACING), the riding hydrogens (REFINE_SCORE_HYDROGENS), the likelihood over the working and the free reflections (REFINE_SCORE_NLL_WORK, REFINE_SCORE_NLL_FREE) and its mean figure of merit over the working reflections (REFINE_SCORE_FOM), the geometry’s rmsd and rmsZ (REFINE_SCORE_RMSD_BONDS, REFINE_SCORE_RMSZ_BONDS, REFINE_SCORE_RMSD_ANGLES, REFINE_SCORE_RMSZ_ANGLES, REFINE_SCORE_RMSD_METAL_BONDS, REFINE_SCORE_RMSD_BONDS_ALL for covalent and metal bonds together) and a table of R-work and R-free in 20 resolution shells. rugnux --mode refine --refine-score-only writes this score, of the model as given, and nothing else.

In --mode refine the input’s keys come first: REFINE_REFLECTIONS and REFINE_FREE_REFLECTIONS (those read, after any --refine-d-min), REFINE_FRENCH_WILSON (TRUE where the file had intensities only and the amplitudes were made by French-Wilson), REFINE_FREE_FLAGS (FILE, or GENERATED where the file had no free set and rugnux drew its own), REFINE_FREE_SET_SOURCE and REFINE_FREE_SET_CLASS (where a structure-factor mmCIF’s flags are classes: the class taken as the test set, and whether the file’s own mark (STATUS), the model file’s test-set count with the worst fit (REMARK3_COUNT) or the worst fit alone (WORST_FIT) chose it) and REFINE_D_MIN_LIMIT (the --refine-d-min given).

\ No newline at end of file diff --git a/RUGNUX_TUTORIAL.html b/RUGNUX_TUTORIAL.html new file mode 100644 index 000000000..596ab4cf5 --- /dev/null +++ b/RUGNUX_TUTORIAL.html @@ -0,0 +1,44 @@ + Running Rugnux — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Running Rugnux

A first run in detail

The Quick start command on the 9ZLO dataset, with the released rugnux binary installed as described there, is the whole of it:

rugnux -o 9zlo 9zlo/ASP0887_09_0114_master.h5
+

-o 9zlo is the prefix every output file is named from. The last argument is the dataset: its master file (HDF5, any of the formats under Input formats, not only one written by Jungfraujoch), or any one image of a CBF, marCCD, SMV or SFRM sequence. -N would set the worker-thread count, which otherwise follows the machine. Nothing is assumed about the crystal: the goniometer axis in the file tells Rugnux this is a rotation sweep, the unit cell comes from indexing the data, the space group from its systematic absences, and the resolution limit from where CC1/2 falls off. Progress, statistics and timing go to the terminal, and the output files land next to each other. Serial stills and a run with a model start the same way, with the stills’ files or the model added to the inputs (Quick start).

On 9ZLO the terminal ends with this summary (17 s with release 1.0.0-rc.183 on a desktop with a 16-core CPU and an NVIDIA RTX 5080, the files on a local SSD; the CPU alone takes minutes):

 Result        OK: Merged to 1.56 A in P 21 21 21. No warnings.
+ Space group   P 21 21 21
+ Unit cell     38.363 89.746 106.871 90.000 90.000 90.000
+ Resolution    1.56 A written; the CC1/2 fall-off is fitted at 1.64 A
+ Completeness  100.0 % to 1.66 A; 99.7 % over the full written range
+ Signal        I/sigma 11.6 R_meas 12.0 % CC1/2 0.999 ISa 23.6 (23.1-24.0)
+ Anomalous     no usable signal (SigAno 0.61 in the lowest shell (0.80 = none), CC_anom -0.16; no
+               model to read an anomalous map at)
+ Files         9zlo.cif 9zlo.hkl 9zlo.ins 9zlo.mtz 9zlo_detector.jpg
+               9zlo_log.txt 9zlo_plot.txt 9zlo_report.txt 9zlo_unmerged.mtz
+ Wall time     17.30 s
+

9zlo_report.txt is written for a person, top to bottom: it says which space group was chosen and on what evidence, how far the data go, and anything that needs attention. To pull one number out of it in a script, every value is a KEY= value line:

grep '^SPACE_GROUP_NUMBER= '        9zlo_report.txt
+grep '^SPACE_GROUP_NAME= '         9zlo_report.txt   # the setting, which the number does not name
+grep '^UNIT_CELL_CONSTANTS= '      9zlo_report.txt
+grep '^INCLUDE_RESOLUTION_RANGE= ' 9zlo_report.txt
+grep '^ISA= '                      9zlo_report.txt
+grep '^# WARNING:'                 9zlo_report.txt
+

On 9ZLO these give 19, P 21 21 21, 38.363 89.746 106.871 90.000 90.000 90.000, 68.727 1.565 and 23.57, with no warning; the deposited structure has the same space group, a cell within 0.5 % of this one, and 2.0 A as its resolution. A second run of the same command, or a run on another GPU or on the CPU, repeats the space group, the cell to 0.1 % and the resolution to one shell; the last digit of a statistic can differ.

With the AlphaFold prediction of the protein as the model (the Quick start’s second command, rugnux -o 9zlo --model AF-P17090-F1-model_v6.cif 9zlo/ASP0887_09_0114_master.h5) the run goes on to molecular replacement and refinement and takes 22 s (the paper’s Extended Data Table 1 times this dataset with an earlier release, which placed the model but did not refine it); MR_DECISION= AGREES says the two copies were placed and the merged data agree with the placement, and REFINE_R_WORK= 0.2707, REFINE_R_FREE= 0.2967 are the refined model’s R factors (they can differ in the second decimal between builds) (the deposited model, built and refined against these data, has an R-free of 0.219). The files the run writes are listed under Output files.

One caveat for a script reading those keys: where the space group is one of an enantiomorphic pair, SPACE_GROUP_NUMBER= / SPACE_GROUP_NAME= carry one member of the pair by convention, not by determination — the report says so beside them, in section 2, as SPACE_GROUP_ALTERNATIVES= naming the other hand and SPACE_GROUP_ENANTIOMORPH= UNDETERMINED. Treat the two hands as interchangeable until a model settles it: with --model, where the data accept the model (MODEL_FIT= ACCEPTED), the report carries MODEL_ENANTIOMORPH_ADOPTED= TRUE and the model’s group instead, and refining an isomorphous model against the wrong hand of the pair costs nothing subtler than an R factor near 0.55.

Useful variations, each independent of the others:

# tell it where the data really stop, if you already know - this sharpens the
+# space-group search and the error model
+rugnux -o myrun --scaling-high-resolution 1.4 dataset_master.h5
+
+# a quick look at the first 200 images only
+rugnux -o quicklook -e 200 dataset_master.h5
+
+# merge as usual, but also keep the per-image file so the data can be re-merged later
+rugnux -o myrun --write-process-h5 dataset_master.h5
+
+# skip the unmerged MTZ (written by default), when only the merged data is wanted
+rugnux -o myrun --no-export-unmerged dataset_master.h5
+
+# check the merged data against a known structure: R-work / R-free, maps and the
+# refined model (the model may also be given as a second input, without --model)
+rugnux -o myrun --model model.pdb dataset_master.h5
+

Re-merging does not re-read the images and takes seconds. Run once with --write-process-h5 to keep the per-image file. --mode scale then re-scales and re-merges the reflections in it:

rugnux -o myrun --write-process-h5 dataset_master.h5   # integrate and merge once
+rugnux --mode scale -o remerged --scaling-high-resolution 1.8 myrun_process.h5   # re-merge, here to 1.8 A
+

Use it to try a different resolution limit or outlier rejection without paying for integration again. The anomalous signal needs no option on rotation data: every merge keeps I(+) and I(-), and -A changes nothing there (on serial stills it is what keeps the hands apart). --mode scale merges in the space group and cell the file records, so the second command needs no -S. Note that --no-merge also writes a _process.h5, but a run that never merged never determined a space group either, so re-merging that file lands in P1 unless you pass -S yourself — --write-process-h5 is the one to use.

Rotation data

Index, integrate, scale and merge a rotation sweep, fully de novo:

rugnux rotation_master.h5 \
+    -o rotation_run \
+    --scaling-high-resolution 1.4
+

Because the dataset carries a rotation goniometer axis, it is processed as rotation data by default: two-pass rotation indexing (index the sweep once, then process every frame against that lattice) with the rot3d partiality model (rotation partials combined into 3D fulls). Scaling and merging run by default (for both rotation and stills; --no-merge turns them off); the unit cell is taken from the rotation indexer and the space group is determined from systematic absences, and both are written into the merged files.

Run fully de novo (no -C/-S) for the best result — supplying a cell or space group up front tends to degrade low-symmetry cases. A -S group whose Bravais lattice the crystal turns out not to have stops the run and names the cell that was indexed, rather than merging in a frame the reflections are not in; where the lattice does have that group’s setting, the reflections are reindexed into it. A primitive -S group on a lattice indexed as centred is the exception: it is merged as asked, with a warning. --scaling-high-resolution (set it to your expected resolution) sharpens both the space-group search and the error model. To tune the first pass use --two-pass-rotation=100 (or -R100 — the first-pass image count); to force the sweep to be treated as independent stills use --force-still.

By default a rotation run also post-refines the geometry in a second pass: the first pass integrates and merges the first half of the sweep (at least 120° of it) at the header geometry (--prepass-fraction 1 for all of it), then the detector distance + beam centre and the crystal cell / rotation-axis are refined against the merged fulls (cross-validated; the distance moves 1 % a step and a larger move is ratified by re-indexing, and the gauge-weak beam centre stays within 15 px of the centre the first pass ran at or of the run’s own measured centre, whichever is nearer), and the second pass re-indexes de novo and re-integrates at the refined geometry. The refined pass is the canonical <prefix>_* output; the header-geometry pass merges only to choose the space group and to judge the refined pass against, and writes no merged files of its own — no <prefix>_01.mtz, .cif or .hkl, and no _01_plot.txt or _01_detector.jpg. (Where a process file is asked for at all, with --no-merge or --write-process-h5, each pass still writes its own, so <prefix>_01_process.h5 appears beside <prefix>_process.h5.) Disable it with --rotation-no-postrefine.

After the per-frame scale-fulls step, rotation scaling applies three kinds of correction surface, on by default (--no-scaling-corrections disables all):

  • Decay — a global Debye–Waller relative-B over the run, for the radiation damage that weakens later frames more at high resolution (a resolution×time systematic the resolution-flat per-frame scale cannot remove). It only engages when the total relative-B exceeds a physical floor (2 Ų). An optional --relative-b[=deg] extends this single global rate to a smooth per-batch relative-B curve (default 10°-of-rotation batches when bare, off otherwise), cross-validated like the surfaces here, for crystals whose decay is non-linear in dose.

  • Absorption — a smooth multiplicative factor over the diffracted-beam direction in the goniometer frame (path length through the crystal), offered as a grid, as spherical harmonics and as a surface that also varies with the rotation angle. Negligible at hard X-rays / thin crystals; it matters at low photon energy and on strongly absorbing crystals. A smooth absorption error largely cancels among symmetry mates (little effect on the error model / ISa) but biases the intensities, so its benefit shows up in Rfree rather than in the merging statistics.

  • Modulation — a smooth multiplicative factor over the position where a reflection lands on the detector (a flat-field: detector-response and geometric systematics that vary across the detector plane). Symmetry-equivalents of one reflection land at different detector positions as the crystal rotates, which over-determines the surface. Because it lives in the detector frame (not the rotation) the same correction concept applies to stills. On a detector with a systematic it is the largest of the three, lowering Rmeas while holding or improving CC1/2 and the anomalous signal.

All of them are cross-validated — fitted on even-numbered frames and used to merge the odd ones, and the other way round, and kept only if the correlation between the two half-set means, within resolution shells, rises over the same halves merged without the surface. The score does not involve the sigmas, so a surface can never pass by merely reshaping them; where the systematic is absent the surface is a no-op rather than a source of added noise, which is why they are safe to leave on (§10.6).

Independently of any correction, a rotation run prints a radiation-damage report — the per-image scale correlation-to-merge and mosaicity versus dose, and the relative B-factor change over the run (first→last) together with a per-batch relative-B curve, also written to the merged mmCIF. It is a data-quality-vs-dose diagnostic and never alters the merged intensities. A batch whose data cannot support a measurement prints - instead of a value, and the first→last number is printed only where a straight line describes the curve — damage is progressive, so a curve that dips and recovers is a disturbance of the sweep, not dose, and the report says so and points at the sweep-quality section (RADIATION_DAMAGE_RELATIVE_B= NOT_A_TREND).

Still / serial data

A dataset with no goniometer axis, or one whose axis does not turn (e.g. a serial grid scan), is processed as independent stills automatically — no flag needed. A run spread over several files is given as all of them at once — several NXmx masters of one setup, or the files an XFEL pipeline writes (Serial XFEL inputs):

rugnux -o serial *_master.h5     # several NXmx masters, read and merged as one run
+rugnux -o serial run*.h5         # all the files of one stills dataset; *.cxi, *.xtc alike
+

Where the cell and space group are known, give them; where the detector’s panels are described by a CrystFEL geometry file, give that too:

rugnux -o serial -C 79,79,38,90,90,90 -S P43212 --crystfel-geometry detector.geom run*.h5
+

The wavelength and distance are read from the data or the geometry file; --wavelength and --detector-distance are only for files that state neither (a distance given there is held, not refined). A reference reflection file of the same crystal form (-z reference.mtz) or a model (model.pdb as a further input, or --model) can be added to any of these.

A crystal form with an indexing ambiguity — P3, P4, P6 and their relatives — needs the space group on the run that integrates: every crystal is indexed in one of the alternative indexings at random, and they are averaged together in the merge unless the crystals are put into one first. With -S given, the run does that from the data alone, making the crystals consistent with each other (INDEXING_AMBIGUITY_RESOLVED= data); a reference (-z) puts each image into the reference’s indexing instead, so that the merge also comes out in it (a --model relabels the finished merge into its indexing and changes nothing else). Without -S and without a reference, the mixed merge can look more symmetric than the crystal is, and the run warns.

ffbidx requires a known cell (-C) and is the indexer of choice for sparse serial stills; the default -X Auto picks it for stills whenever a cell is given, so there is no -X to set; without a cell the stills are indexed de novo. The self-calibrating spot finder is on by default for both workflows (--no-adaptive-spots turns it off), and for serial stills leave --min-pix-per-spot unset so it is chosen per image: this indexes more frames, and usually to higher resolution, than a fixed threshold and min-pix. (You can still pin a fixed threshold with --spot-sigma / --spot-threshold and a fixed min-pix with --min-pix-per-spot.) If a dataset does carry a goniometer axis but you want per-frame stills processing anyway, add --force-still.

Small-molecule data

A small-molecule rotation sweep is processed with the same command. No option marks it as small-molecule data:

rugnux -o xtal sweep_master.h5
+

The differences from protein data are handled automatically:

  • Short cell axes. The FFT search’s floor is 10 Å, but on a rotation run a row shorter than that, down to 3 Å, is recognised under the multiple of it the search reports, so a cell with short axes is indexed on its true axes.

  • Wide and split spots. Spots far from the beam, at the high energies small-molecule data are often taken at, grow several times wider than the integration disk, and a crystal of slightly misaligned domains records each reflection as two or more spots. The pre-scan measures how wide the spots and their offsets from the predicted positions are across the detector, and the integration follows that footprint wherever it outgrows the disk (§9.1); on compact spots nothing changes.

  • Sparse patterns. A lattice that explains too few spots on most frames to pass the per-frame test is integrated on every frame rather than only on the frames that happen to carry more spots (§4.1). Where a sweep has few reflections per frame, the per-frame scale may be taken from the full reflections alone instead of from the partials; the merge decides that from the data and the log says which it took (§10.6).

  • Overloads. A measurement of a reflection with an overloaded pixel on any of its frames is left out, as XDS leaves it out: its brightest part is the part that was not measured. On a strongly diffracting crystal these are the strongest low-order reflections, and OBSERVATIONS_REJECTED_OVERLOAD= in the report counts them. Many of them mean the sweep wants a weaker beam, not different processing.

  • Space group. The search names glide planes, and groups without a centre of symmetry as well as centrosymmetric ones. Where the absences cannot separate the two (C2/c and Cc, Pnma and Pna2₁), the centrosymmetric group is written and the other is listed in SPACE_GROUP_ALTERNATIVES=, unless the intensity statistics read acentric and the lattice rules twinning out; SPACE_GROUP_CENTRE= says which of these happened (see The results report). Structure solution and refinement settle it.

Two settings are worth a look before running. The default polarization is what a miniCBF or d*TREK header states, and otherwise --polarization 0.99, an undulator’s; a laboratory source is close to unpolarized, and neither ADSC SMV, marCCD nor NXmx files state it, so give the instrument’s value there. And the written reflections stop where CC1/2 falls off (the default --resolution-cutoff cc-logistic, the same cut for every file, .hkl included); --resolution-cutoff off keeps everything to the edge of the detector, for a refinement that weights the weak data itself.

The file for SHELX is xtal.hkl: on a rotation sweep it holds the scaled reflections unmerged, each at the index it was measured at, so SHELXL computes R(int) and R(sigma) itself and the Friedel opposites it needs for the absolute structure are all there — no -A is needed. How to take it into SHELXT and SHELXL is under Small-molecule structures with SHELXT and SHELXL. Absorption is corrected only by the empirical surface a rotation run fits and keeps where it helps (Rotation data); there is no correction from the crystal’s measured faces. --model is for macromolecular models and plays no part here.

Output files

Output (controlled by -o, --output-prefix, default output):

  • <prefix>_process.h5 — NXmx-compliant HDF5 with derived metadata (spots, indexing, integration, azimuthal integration, per-image statistics). See HDF5 / NeXus data format for the layout. Written by default only when not merging (i.e. under --no-merge); add --write-process-h5 to also write it when merging. It does not copy the images: /entry/data/data is a virtual dataset over the input files, so the input has to stay where it was for the pictures to be readable, and the pixel metadata (bit_depth_readout, underload_value, the dataset type) describes those files rather than the signed 32-bit container Rugnux processes in.

  • Merging is on by default (--no-merge disables it). The merged reflections are written in three formats — each has its uses downstream:

    • <prefix>.mtz — CCP4 MTZ for the CCP4 / phenix reflection tools. The columns are H K L IMEAN SIGIMEAN I(+) SIGI(+) I(-) SIGI(-) F SIGF F(+) SIGF(+) F(-) SIGF(-) FreeR_flag (F is the French–Wilson amplitude); the anomalous columns are present whenever any reflection carries a Bijvoet split — a rotation run always does, a stills run only with -A.

    • <prefix>.cif — mmCIF, for deposition and as the self-describing native format (also carries the merging statistics, ISa, twinning and radiation-damage indicators).

    • <prefix>.hkl — SHELX HKLF 4 text (h k l I σ(I), fixed 3I4,2F8.2), the direct input for SHELXL and SHELXC / ANODE / SHELXD. On rotation data it holds the scaled full reflections unmerged — every correction applied, symmetry equivalents not averaged, each at the index it was measured at — so SHELXL reports Rint and Rsigma itself and the anomalous signal is all there; stills runs write the merged reflections (Bijvoet mates at +hkl and -hkl). Intensities are put on a common scale so the largest value fits the fixed-width field, and the file ends with the 0 0 0 terminator record.

    • <prefix>.ins — the SHELX instructions to go with the .hkl: CELL at the wavelength, ZERR with the cell’s e.s.d.s, LATT and SYMM for the space group, and a placeholder SFAC/UNIT for the user to replace with the formula (see Small-molecule structures with SHELXT and SHELXL).

    All three carry the refined unit cell (from rotation indexing) and the space group determined from systematic absences (constrained to the indexed lattice symmetry).

  • <prefix>_unmerged.mtz — the integrated observations before merging, as an unmerged MTZ in POINTLESS’s column layout, so the data can be scaled and merged by aimless, pointless, careless or iotbx.merging_statistics instead of by Rugnux. Written by default, alongside the merged files and with --no-merge too; --no-export-unmerged skips it. See The unmerged export. --export-unmerged-partials writes <prefix>_unmerged_partials.mtz, one row per image, instead of summing.

  • With --model, the validation outputs land beside the files above: the map-coefficient MTZ <prefix>_maps.mtz (σA-weighted 2mFo−DFc and mFo−DFc; Coot and PyMOL open it directly as maps), and the model as placed against the data as <prefix>_model.cif and <prefix>_model.pdb — the coordinates that go with the maps, in the cell and space group of <prefix>.mtz. Mind the names: <prefix>.cif is merged reflections, <prefix>_model.cif is coordinates. The PDB is there because fragment-screening tools want a <name>.pdb beside a <name>.mtz — PanDDA’s per-dataset input layout, and the pair dimple produces — and it is skipped, with a log line, for a cell the PDB format cannot hold. See Validating against a model.

  • <prefix>_refined_model.cif / .pdb, <prefix>_refined_maps.mtz and <prefix>_blobs.json — where the model was placed, the model as rugnux refined it, its map coefficients and the blobs of density its difference map leaves unexplained; --no-refine skips them. See Refinement.

  • <prefix>_twin_<SG>.mtz / .cif — only where the chosen space group may have absorbed a twin law: the same data merged in a subgroup <SG>, with the twin law and its fraction, same resolution and free set as <prefix>.mtz, for refinement with that law. With --model, the maps come from whichever of the two merges the model fits better. See The twin hypothesis.

  • <prefix>_mr.mtz / .cif, with <prefix>_mr_model.pdb / .cif — only with --model (or --mr), where the model, placed as a rigid body or by molecular replacement, chooses another space group with the answer’s rotations or the twin hypothesis’ subgroup: that merge, labelled with the group the model chose, beside the run’s own answer, which is left as it was. See Validating against a model.

  • <prefix>_report.txt — the results report: what the run determined, in a form both a person and a beamline script can read. Written by every mx and scale run, next to the files above (an empty prefix, -o "", writes nothing). See The results report.

  • <prefix>_log.txt — the full timestamped log of the run, at debug level, written by every run with an output prefix; send it with the report when asking about a run.

  • <prefix>_modules.h5, <prefix>_module_placement.json — serial stills on a detector of several modules: where the geometry refinement placed each one (the .h5 only where it moved some; the JSON whenever placement is not off), readable back with --module-geometry / --module-placement (the JSON also by the broker’s /start, merged into its dataset settings; see Module geometry).

  • <prefix>_plot.txt — the per-image table, one row per processed image, whitespace-separated, with a single # legend line over its own columns so gnuplot plots it as it stands (plot '<prefix>_plot.txt' using 1:4). The columns are:

    Column

    Meaning

    image

    Processed-image ordinal, the numbering every per-image array rugnux writes uses; with -s/--stride the source image is start + ordinal * stride.

    angle_deg

    Spindle angle at mid-exposure.

    bkg

    Background estimate from the azimuthal profile (the bkgEstimate of the HDF5 file).

    resolution_A

    How far the image’s spots reach, from spot finding alone.

    spots

    Spots found.

    scale_G

    Per-image scale factor fitted by scaling.

    sigma_M_deg

    Mosaicity as the rocking-curve standard deviation σM in degrees — not a FWHM, and not XDS’s REFLECTING_RANGE. See the note below.

    cc_to_merge

    Correlation of the image’s own observations with the merged data.

    cc_n

    Observations that correlation was computed over; 0 where none was.

    merged

    1 where the image’s observations are in the merged data, 0 where they are not — an image that never indexed, one an earlier guard dropped, and one ΔCC1/2 convicted all read 0. nan on a run that merged nothing, --no-merge included, where the question has no answer.

    disposition

    The same answer graded, to plot directly: 1 merged, 0.5 downgraded (merged, but over a degraded stretch of the sweep), 0 rejected. 0.5 is a marker, not a weight — the merge applies no factor of its own to a downgraded frame, which is carried at the weight its own scale and sigmas give it. nan for an image that never got a scale and so never reached the merge, and on a run that merged nothing.

    A quantity nothing measured for an image is written nan, which gnuplot and numpy both skip; the columns never shift and a row is never left out. A stills run writes the table too, with nan in the columns a sweep would fill; --no-merge writes it with the scaling columns nan.

    Reading sigma_M_deg. It is fitted per image — a maximum-likelihood Gaussian rocking width over that image’s own indexed spots — but it is then smoothed in frame order over the same rotation window as the per-image scale (--smooth-g), and any frame too sparse to fit one of its own is given the run’s median. So the column varies only on the smoothing window’s scale, and on a weakly diffracting crystal it is close to, or exactly, a constant: that flatness is the honest statement that the run measured no per-frame variation, not a placeholder. The value is the one scaling used to recompute partialities. σM here is the width of a Gaussian rocking curve and nothing more — it is not a physical crystal mosaic spread, it absorbs beam divergence and every other source of angular spread, and it reads systematically low against XDS’s SIGMAR. Use it to see whether the run’s rocking width moves across the sweep, not as a number to quote.

  • <prefix>_detector.jpg — the detector as the run saw it, so the beam stop and the module gaps can be checked by eye. Rotation runs only, and only where --detect-beam-stop was left on (it is by default). The picture is the mean projection over the frames the beam-stop detection sampled — the very image it tested — coloured with jfjoch_viewer’s default map: white to indigo for the counts, grey for the module and chip gaps, coral for the shadow the run detected, and magenta for everything else the pixel mask holds. The scale saturates at eight times the median measured pixel, not at the brightest pixels, so the background spans the ramp and the Bragg spots clip: it is the background the picture is read for, since a shadow is a place the background is missing. A shadow drawn where the background is unbroken, or a dark patch the run left uncoloured, is visible at a glance; read it against the Beam stop shadow: N pixels ... line in the log.

Merged statistics (⟨I/σ⟩, CC1/2, completeness, …), the error model and timing are printed to the console. By default the written resolution is trimmed automatically where CC1/2 falls off (--resolution-cutoff cc-logistic, CC1/2 target 0.30); set --scaling-high-resolution to fix the limit by hand, or --resolution-cutoff off to keep the full range.

\ No newline at end of file diff --git a/SECURITY.html b/SECURITY.html new file mode 100644 index 000000000..b787832ae --- /dev/null +++ b/SECURITY.html @@ -0,0 +1 @@ + Security — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Security

Jungfraujoch is a data-acquisition and analysis system for X-ray detectors, designed to run inside a controlled facility network. This document describes what the software does and does not protect against, the current known limitations, and the authentication work in progress.

Threat model and scope

The security model targets a semi-trusted internal facility network. The concern is a peer on that network reaching a Jungfraujoch service with little or no effort — a mistyped host/port, a curious colleague, a mis-pointed script, a stray browser tab — not a determined attacker and not passive wire capture (which is the responsibility of the network layer: 802.1x, VLANs, facility infrastructure).

The asset that matters most is the confidentiality of live analysis data: the diffraction images and derived metadata (unit cell, resolution, spot counts, sample name) that reveal which sample is being measured. This matters for industrial and proprietary experiments. By contrast, acquisition control (start / stop / configure) is treated as low risk — scientists operate their own experiments and there is little to gain from restricting it.

Security is best-effort: measures that materially impede normal operation get turned off, so the design favours a few high-value, low-friction controls over comprehensive lockdown.

Out of scope. Jungfraujoch is not designed to be exposed to an untrusted network or the public internet. Do not do this.

1. Good practice — what is and is not protected

What you can secure (and should)

These controls work and a deployment should apply them (see also DEPLOYMENT.md):

  • Network isolation. Keep the broker and its data streams on a controlled segment. The broker ↔ writer ↔ receiver traffic should run on a dedicated back-end network, with the data-socket addresses pinned to that interface and the ports firewalled.

  • Reverse proxy for TLS. The broker speaks plain HTTP. To get HTTPS, put a reverse proxy (Apache / nginx) in front that terminates TLS and pin the broker to localhost behind it. The desktop viewer supports https:// endpoints — choose the scheme in the Open HTTP Connection dialog.

  • Filesystem confinement of written data. The writer creates NXmx HDF5 files on shared storage. Confidentiality of that data at rest is enforced by the filesystem: run the writer under a dedicated identity and use directory ownership / ACLs (and setgid) so that only the owning experiment can read its files.

  • Firewall the ZeroMQ ports. The image / preview / metadata / republish streams have no access control of their own (see below), so restrict who can reach those ports at the network layer.

What the software does NOT provide

The gaps are listed explicitly so a deployment does not assume protection that is not there:

  • No authentication or authorization in the broker. The HTTP/REST API currently has no login, token, or access control. Anyone who can reach the broker’s host and port has full read access (live images, unit cell, resolution, sample metadata) and full write access (start, cancel, reconfigure). Confidentiality currently depends entirely on network/firewall isolation. This is being addressed — see §3.

  • No transport encryption in the broker. The broker serves plain HTTP; there is no built-in TLS. Encryption must be provided by a reverse proxy.

  • No access control or encryption on the ZeroMQ streams. The preview, metadata, image, and republish streams are unauthenticated sockets. Any peer that can connect can subscribe to live data. For the image PUSH stream specifically, an accidental extra consumer does not merely eavesdrop — a PULL peer is load-balanced into the stream and will divert images away from the real writer.

  • No per-user isolation. The broker has no concept of users; it cannot separate one operator’s access from another’s.

  • No application-level audit trail of who accessed or changed what.

2. Known issues

#

Issue

Impact

Mitigation today

1

Broker HTTP API has no authentication for control, and read access is protected only per dataset

Anyone who can reach it can start / stop / configure; a dataset started without tokens is readable by anyone

Per-dataset bearer tokens (§3) for the read endpoints; network / firewall isolation for the rest

2

Broker binds all interfaces, plain HTTP

Reachable from anywhere routable; no encryption

Expose only on the trusted segment; TLS via reverse proxy

3

ZeroMQ preview / metadata / image / republish streams are unauthenticated and unencrypted

Live-data exfiltration; a rogue PULL on the image stream diverts/steals images

Firewall the ports; run only on the back-end network

4

Web frontend has no login

The bundled UI takes a dataset token (key button) but nothing identifies its user

Serve and reach it only on the trusted network

Input robustness. Services parse framed data from peers on the (trusted) data path. Hardening of untrusted-frame handling (size caps, overflow guards) is ongoing; these paths are not intended to face an untrusted network.

3. Authenticated read access — per-dataset bearer tokens

The confidential read endpoints are protected with a best-effort, low-friction scheme; acquisition control stays open.

How it works. /start accepts an optional list of tokens - plain strings, any number, all equivalent. A typical pair is one constant beamline secret and one secret minted for the experiment, so both the beamline staff and the experiment’s own users can open the data. While the current dataset has tokens, the endpoints below answer 401 unless the request carries Authorization: Bearer <one of them>; the 401 says nothing about the dataset. Every accepted /start replaces the previous tokens, so a run started without them is open, and the next run’s users cannot read this one. No endpoint returns the tokens; the broker only compares strings (constant-time) and keeps them in memory. Whoever runs /start hands the token to the viewers. An accepted /start also clears what the previous run left readable - its statistics, plots and buffered images - in the same step that installs the new tokens, so the previous run is never served under the new tokens, and the new run’s name never under the old ones. A refused /start (wrong state, invalid settings) changes nothing. /initialize drops the tokens together with everything they protected - the dataset’s settings, results, images, plots, live rugnux status and the record of its collection - so the broker is left as open and as empty as a freshly started one.

Endpoint

With tokens set

/statistics/data_collection (dataset name, unit cell, …)

401 without a token

/result/scan (dataset name, cell of a grid scan / rotation)

401 without a token

/image_buffer/start.cbor, /image_buffer/image.cbor, /image_buffer/image.jpeg, /image_buffer/image.tiff (the images and the start message)

401 without a token

/preview/plot, /preview/plot.bin (per-image plots, unit cell)

401 without a token

/live/events (the start message and the data files of the collection being written)

401 without a token

/rugnux/status (live rugnux run of the collection: cell, space group, results)

401 without a token

/rugnux/model.cif, /rugnux/map.ccp4 (the model placed by the live run and its maps)

401 without a token

/statistics (the aggregate the web UI polls)

200, but the measurement block is omitted

everything else (/status, /config/*, /start, /cancel, masks, pedestal, …)

open

Clients.

  • jfjoch_viewer - the token field of File ▸ Open HTTP (password echo), the JUNGFRAUJOCH_HTTP_TOKEN environment variable, or D-Bus (LoadFile(url, image, sum, token) / SetHttpToken(token)); the dialog overrides both. A 401 clears the display and puts a note on the status bar - no dialog, since a changed dataset is the normal reason.

  • Web frontend - the key button in the top bar; the token lives in the tab’s sessionStorage and is sent with the protected calls only. The start form has a field for the tokens of a new run.

  • Python client - Configuration(host=..., access_token="<token>").

  • rugnux following a collection from the broker - the JUNGFRAUJOCH_HTTP_TOKEN environment variable, sent only in the Authorization header and never written to its logs or reports.

  • Anything else - curl -H "Authorization: Bearer <token>" ....

What it does not do. The broker still speaks plain HTTP, so the token crosses the network in clear unless a TLS reverse proxy fronts the broker (§1); on a facility network this raises the bar from “type the IP” to “capture packets”, which is the aim. It does not authenticate users or control, does not touch the ZeroMQ streams (issue #3), and /status’s free-text message may still quote a path. Datasets of different users within one session are separated by their tokens alone; there is no long-lived login.

\ No newline at end of file diff --git a/SOFTWARE.html b/SOFTWARE.html new file mode 100644 index 000000000..8e2b79d59 --- /dev/null +++ b/SOFTWARE.html @@ -0,0 +1 @@ + Software requirements — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Software requirements

Operating system

Recommended operating system is Red Hat Enterprise Linux (RHEL) / Rocky Linux versions 8 or 9. For these operating systems we provide RPMs with pre-built binaries to simplify deployment. On an experimental basis we also build repositories for Ubuntu 22.04 and 24.04.

Running Jungfraujoch on Red Hat Enterprise Linux 7 is currently not tested and not recommended, but likely possible by providing some packages from external repositories.

Two programs additionally run on Windows 11: the desktop viewer jfjoch_viewer, shipped as a pre-built installer, and rugnux, the offline analysis CLI, shipped as a .zip. Both can be built from source with Visual Studio 2026 (MSVC) and CUDA 13.3 — the viewer additionally needs Qt 6.11; see jfjoch_viewer ▸ Building from source on Windows. The Windows artefacts bundle the Qt runtime (viewer only) and, on the CUDA builds, the cuFFT DLL, so end users need neither Qt nor a CUDA toolkit installed — only an NVIDIA GPU driver for the GPU path. On Linux the portable archives link CUDA entirely statically and so need nothing but the driver. rugnux is also built for 64-bit Arm Linux (GH200, DGX Spark). The rest of Jungfraujoch is Linux-only and x86-64-only. See Release contents for the CPU baseline and CUDA requirements of each released package.

Software dependencies

Required:

  • C++20 compiler and C++20 standard library: GCC 11 or newer (checked at configure time; on RHEL/Rocky 8 use gcc-toolset-13), or clang 14+ (Intel OneAPI and AMD AOCC also work)

  • CMake version 3.26 or newer + a build tool (GNU make or Ninja)

HDF5, libtiff, zlib and Eigen are downloaded and built automatically by CMake (see the note below), so none of them needs to be installed. Beyond the optional dependencies listed below, no third-party library has to be provided by the host.

Optional:

  • CUDA compiler version 12.8 or newer - required for the MX fast feedback indexer and GPU analysis

  • Node.js - to build the frontend

  • Qt version 6 (for jfjoch_viewer)

Many further dependencies (spdlog, Zstandard, HDF5, slsDetectorPackage, libzmq, libtiff, FFTW, Ceres with abseil, the fast feedback indexer, Catch2, …) are downloaded automatically by CMake and statically linked; building therefore requires network access on the first configure. zlib (as zlib-ng in its zlib-compatible mode) and Eigen are among them: a copy already on the machine is used instead if the configure is given -DZLIB_ROOT=<prefix> or -DEigen3_DIR=<dir>. Others are vendored directly in the source tree. The complete list of third-party components, with copyright holders, licenses and verbatim license texts, is in Third-party software notices and the licenses/ directory.

\ No newline at end of file diff --git a/SOFTWARE_INTEGRATION.html b/SOFTWARE_INTEGRATION.html new file mode 100644 index 000000000..7409e80d7 --- /dev/null +++ b/SOFTWARE_INTEGRATION.html @@ -0,0 +1,4 @@ + Integration with MX data processing software — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Integration with MX data processing software

Jungfraujoch writes NXmx HDF5 in three layouts (see HDF5 / NeXus data format), and not every downstream program reads all three. NXmxVDS is the default and the one to use unless a program specifically needs another.

NXmxLegacy

NXmxVDS (default)

NXmxIntegrated

Jungfraujoch XDS plugin

yes

yes

yes

Durin (PSI or Global Phasing build)

yes

yes

yes

Durin (Diamond, original)

yes

known bugs

known bugs

Neggia

yes

no — no virtual-dataset support

not tested

DIALS / xia2

only one data file

yes

yes

CrystFEL

yes

yes

yes

NXmxLegacy joins the data files to the master with external links, which is what DECTRIS’s filewriter-1 format did. Use it only for a program that needs it, and then keep the whole run in a single data file — see the DIALS section below.

XDS

XDS reads HDF5 through a plugin, named in XDS.INP:

LIB=/opt/xds/durin-plugin.so
+

We recommend the Durin plugin, from either of two sources:

Prefer either over the original Durin from Diamond Light Source, which has known bugs with non-DECTRIS files (virtual datasets and the single-file layout). Durin is the only third-party plugin that reads signed Jungfraujoch images correctly. Be aware that it does not act on every mask bit — in particular not on the user mask, the beam-stop shadow or module edges (see Which pixels are masked); where those matter, exclude the regions in XDS.INP (UNTRUSTED_RECTANGLE= and friends).

The other options:

  • Jungfraujoch XDS plugin — released for Linux (x86_64, built on RHEL 8) as jfjoch_xds_plugin-<version>-linux-x86_64.tgz on the Gitea release page, and also shipped inside the jfjoch_viewer RPM/APT packages. Extract the archive into a directory of its own; it holds the library (lib/libjfjoch_xds_plugin.so.<version>) and its license notices (share/doc/). It acts on every mask bit Jungfraujoch writes.

  • Neggia — github.com/dectris/neggia. No virtual-dataset support, so it cannot read the default layout. It also mis-reads signed 16-bit images: it dispatches on the pixel size in bytes and always casts to an unsigned type, so a count of -2 reaches XDS as 65534 and the -32768 error marker as 32768. Signed 32-bit degrades safely. Since JUNGFRAU in photon-counting conversion writes signed images by default, this affects the ordinary PSI case — do not use Neggia for it.

OVERLOAD must be set by hand

No XDS plugin — ours, Durin or Neggia — reads saturation_value from the file. XDS therefore takes its overload from OVERLOAD= in XDS.INP, and you must set it to the master file’s /entry/instrument/detector/saturation_value. XDS treats it inclusively: a pixel is overloaded when it exceeds OVERLOAD.

Signed images

MINIMUM_VALID_PIXEL_VALUE= may not be negative in current XDS, so a genuinely negative photon count — the reason signed output exists — cannot be declared valid. xia2 clamps the value to 0. There is no header field that changes this: if XDS is the target, consider collecting unsigned.

Which pixels are masked

The plugins do not all act on the same mask bits, so XDS and DIALS do not mask the same pixels. Measured with the Durin and Neggia builds Jungfraujoch is tested against:

mask bit

meaning

jfjoch plugin

Durin

Neggia

DIALS

0

module gap

yes

yes

yes

yes

1–4

error, noisy

yes

yes

yes

yes

8, 9, 10, 11

user mask, beam stop, defective, inactive

yes

no

no

yes

30

module edge

yes

no

no

yes

31

chip edge

yes

yes

no

yes

DIALS masks a pixel whenever any pixel_mask bit is set. Bits 30 and 31 mark pixels that are not defective but do not measure like the rest: a module-edge pixel is larger and reads high, and a chip-edge pixel is split from a larger one and at low counts reads low. On a JUNGFRAU with the default edge masking they are of order 2% of the detector, so a dataset processed through Neggia or Durin will not have used the same pixels as one processed through the Jungfraujoch plugin or DIALS.

A saturated pixel is passed to XDS with its value by all three plugins, so XDS flags it against OVERLOAD; only the error marker becomes an untrusted (negative) pixel.

DIALS

Tested regularly against DIALS (currently 3.27.0), including the xia2.ssx pipeline for serial crystallography.

  • Use NXmxVDS or NXmxIntegrated. With NXmxLegacy, DIALS reads only the first data file and reports a correspondingly short image count, without an error; if a goniometer is present it then fails on the frames past the first file. A legacy run that fits in one data file is read correctly — set images_per_file to cover the whole run.

  • Unsigned 32-bit images require bit_depth_readout, which Jungfraujoch writes. For signed images the field is deliberately omitted: DIALS remaps the top two codes of 2^bit_depth_readout, and on signed data those land inside the trusted range.

  • trusted_range is inclusive at both ends, and is taken from underload_value and saturation_value.

pyFAI

rugnux --mode calibration writes a .poni file describing the detector geometry — see Detector geometry and Rugnux.

  • It declares orientation, so it needs pyFAI 2024.01 or newer. An older pyFAI ignores the key and places the beam centre wrongly along the slow axis.

  • A .poni file carries geometry only. pyFAI does not learn the saturation value, the error marker or the pixel mask from it, and will happily integrate a masked pixel at UINTx_MAX as a count. Pass the marker and the mask at integration time:

    ai = pyFAI.load("calibration.poni")
    +res = ai.integrate1d(image, 1000, dummy=65535, delta_dummy=0.5, mask=pixel_mask != 0)
    +

    with dummy set to the master file’s /entry/instrument/detector/error_value for the stored pixel type, and pixel_mask read from /entry/instrument/detector/pixel_mask.

CrystFEL

Jungfraujoch files are compatible with CrystFEL. max_adu is inclusive — a pixel is bad when it exceeds the value — so set it from saturation_value.

\ No newline at end of file diff --git a/TECHNICAL.html b/TECHNICAL.html new file mode 100644 index 000000000..68a949b5a --- /dev/null +++ b/TECHNICAL.html @@ -0,0 +1 @@ + Technical reference — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/TESTS.html b/TESTS.html new file mode 100644 index 000000000..d34cf8a97 --- /dev/null +++ b/TESTS.html @@ -0,0 +1,12 @@ + Tests — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Tests

The unit and integration tests are written with Catch2 and collected into a single binary, tests/jfjoch_test. Build and run it with:

make -j$(nproc) jfjoch_test
+cd tests
+./jfjoch_test                 # everything
+./jfjoch_test "<test name>"   # one test case
+./jfjoch_test "[tag]"         # by tag
+

jfjoch_portable_test holds the cases tagged [portable]: the results that depend on the architecture, the compiler or the standard library (bitshuffle/LZ4, HDF5 read-back, CBF parsing, CPU spot finding, FFTW indexing, gemmi MTZ/CIF). It is built in every configuration, the viewer- and rugnux-only ones included (make jfjoch_portable_test), and is what the macOS and Windows CI jobs run.

There are also benchmark and hardware routines, each printing its own usage:

  • jfjoch_hdf5_test to measure HDF5 dataset writing speed (single threaded). It doubles as the generator of the HDF5 files used by the external-software tests below.

  • jfjoch_lite_perf_test to measure the CPU/GPU (“lite”) analysis path - spot finding, indexing and optional file writing.

  • jfjoch_fpga_test to test quality/performance of FPGA card(s) and software routines. With -H it runs the high-level-synthesis C model on the CPU, so no FPGA device is needed.

Out-of-space handling is covered separately by jfjoch_hdf5_enospc_test, run under the enospc_shim LD_PRELOAD module that makes writes fail with ENOSPC.

In addition, tests are executed to verify that datasets written by Jungfraujoch are readable by other MX software (see Integration with MX data processing software) - XDS through the Jungfraujoch, Durin and Neggia plugins, and DIALS xia2.ssx - for each of the NXmx layouts. Input files for these programs are placed in the tests/xds, tests/xds_durin, tests/xds_neggia and tests/crystfel folders. See .gitea/workflows/build_and_test.yml for the exact commands; the CrystFEL fixtures are run by hand rather than in the pipeline.

Judging a change to the analysis itself

The harnesses below run rugnux over stored datasets and score the result. None is part of CI - run them when a change plausibly moves merged results, not as a reflex. The public datasets the pipeline is exercised on, and the DOI to cite for each, are listed in External test data.

  • tools/battery/battery.py - the rotation battery, the one canonical way to judge a rotation change: public PDB depositions scored against the deposition, in-house standard crystals and no-crystal controls scored against XDS, and a local-only private arm. Its manifests, the run and compare protocol and the report are described in tools/battery/README.md. Each set runs once, with one command per arm; Measuring Rugnux explains the protocol, the REFMAC check and the timing benchmark, and how to take timings that compare.

  • tools/battery/still_battery.py - the still battery: public serial (XFEL stills) datasets run with their deposition’s cell and space group, each merge refined against the deposited model and reported beside the deposition’s R-free, with rugnux’s wall time and the input’s I/O floor. See “The still battery” in tools/battery/README.md.

  • tools/battery/still/rugnux_stills_ab.py - A/B comparison of argument sets on a fixed stills subset: what one change does to the merge, shell by shell. Takes its dataset list from outside the repository.

  • tools/battery/rugnux_anomalous.py - the anomalous-peak-height arbiter, below.

The anomalous-peak-height arbiter

A change that touches partiality - a mosaicity estimator, a rocking-curve model, a background change, anything that alters how partial reflections are weighted - cannot be judged by the statistics we normally reach for:

statistic

why it fails for this class of change

ISa, R_meas, error-model b

one measurement, not three; dominated by the low-resolution shells; not invariant to the uniform intensity rescale a partiality change produces

last-shell R_meas

moves with its denominator, i.e. the wrong way by construction

rugnux --model R-free

tracks its own zero-information floor, which moves ~22x more than R-free itself over the same sweep

per-shell agreement with XDS_ASCII.HKL

XDS never divides by partiality, so “divide less” moves us toward it mechanically; measured to put the optimum ~1.4x too low

Anomalous difference density at known scatterer sites has none of these problems. It is read in units of the map’s own sigma, so a uniform intensity rescale cancels exactly, and it is referenced to the structure rather than to another program’s partiality model.

tools/battery/rugnux_anomalous.py measures it: shelxc + anode -a (CCP4) on each arm’s merged reflections, against a model that is placed once and then held fixed. It reports, per dataset, the mean site height and the off-site noise floor, and, between arms, the paired per-site change.

# compare two arms (each a directory of <id>/<id>.hkl + .mtz)
+tools/battery/rugnux_anomalous.py --config <table>.json  base=<dir-A>  test=<dir-B>
+
+# a parameter scan: numeric labels turn the arms into a curve with a per-dataset optimum
+tools/battery/rugnux_anomalous.py --config <table>.json \
+    0.85='<scan>/{name}/s0p85.hkl' 1.00='<scan>/{name}/s1.hkl' 1.20='<scan>/{name}/s1p2.hkl'
+

An arm is a Rugnux output directory or a path template containing {name}. --place does the one-off model placement, --write-config-template prints the config skeleton, and ANODE results are cached under the config’s workdir (a full 9-dataset x 11-arm scan takes under a minute).

The gate. A dataset counts only if its reference arm shows top peak > 1.5x the highest off-site peak and at least 3 sites over 5 sigma. A dataset that fails is reported as EXCLUDED, never as a zero - the difference between two noise measurements is not a measurement.

Standing dataset set (2026-08): 8 datasets from 7 crystals - 114 site-measurements across the datasets, 108 distinct sulfur sites - all judged on native sulfur signal.

crystals

space group

photon energy

sites each

2

P41212

12.4, 16.0 keV

18

2 (lysozyme)

P43212

13.0, 5.0 keV

27

3 (4 datasets - one crystal contributes two energies)

cubic, I-centred

13.0, 6.0, 5.0, 5.0 keV

6

Report n as crystals, not datasets: two energies of one crystal are not two independent votes, and the tool prints both counts for that reason.

Traps this tool exists to encapsulate. Every one of them has already cost a working day:

  1. The phasing space group comes from the config, never from the merged file. I23 and I213 have identical systematic absences (I-centring already forces the screw condition), so no data can separate them, and phaser’s automatic space-group test only tries the enantiomorph - which for I23 is itself. Phasing an I-centred cubic case in the I23 that both Rugnux and XDS report gives TFZ 7-11 where the other member gives 30-50, and drops the mean site height by a factor 3-10 - enough to make four good datasets look signal-free. Thirteen classes of chiral space group are indistinguishable this way; --place tries every member of the class and reports each one’s LLG/TFZ.

  2. Place the model once, from a reference arm, and reuse it unchanged. Re-phasing per arm lets the model move and contaminates the comparison. Refining the placed model against the dataset’s own amplitudes is allowed (it lifts the peaks another 4-10%) as long as the same refined model is then used for every arm.

  3. The gate and the measurement must use the same model. Gating on one model and scoring the curve with another silently changes which datasets are in the set.

  4. The off-site floor skips special positions. A peak on the cell origin is a ripple of the calculated phases, not a sample of the background; leaving it in inflates the floor by several sigma and can turn a passing dataset into a failing one. Such peaks are reported in their own spec column rather than dropped silently.

Reading the result. Judge the paired per-site change, with its standard error, pooled over crystals. A per-dataset optimum whose arm does not beat the reference on the paired test is flagged not significant vs ref and must not be quoted as a preference; so must one sitting on the edge of the scanned grid (grid edge) - extend the grid instead.

\ No newline at end of file diff --git a/THIRD_PARTY_NOTICES.html b/THIRD_PARTY_NOTICES.html new file mode 100644 index 000000000..8e6731b12 --- /dev/null +++ b/THIRD_PARTY_NOTICES.html @@ -0,0 +1,2 @@ + Third-party software notices — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Third-party software notices

Jungfraujoch is licensed under GPL-3.0 (see LICENSE); the FPGA design is licensed under CERN-OHL-S-2.0 (see fpga/LICENSE). It builds on a number of third-party components, acknowledged below as required by their licenses.

This file is the human-readable manifest. The verbatim license texts live in the licenses/ directory (regenerate with bash licenses/COLLECT.sh). The frontend’s bundled JavaScript dependencies are listed separately in frontend/dist/THIRD_PARTY_LICENSES.txt, generated at build time (npm run licenses).

All licenses below are GPL-3.0-compatible, with one exception: the NVIDIA CUDA Toolkit is used under its own EULA (see the notes at the end of this file).

Fetched at build time and statically linked into the C++ binaries

These are downloaded by CMake (FetchContent / ExternalProject) during the first configure and linked into the Jungfraujoch executables.

Component

Version

Copyright

License (SPDX)

License text

spdlog

1.17.0

Gabi Melman

MIT

spdlog.txt

Zstandard

1.5.7

Meta Platforms, Inc.

BSD-3-Clause

zstd.txt

HDF5

2.2.0

The HDF Group; UIUC

BSD-3-Clause-style + Apache-2.0

hdf5.txt

slsDetectorPackage

8.0.2 / 9.2.0

PSI

LGPL-3.0-or-later

LGPL, GPL

cpp-httplib

0.56.0

Yuji Hirose

MIT

cpp-httplib.txt

libzmq (ZeroMQ)

4.3.5

iMatix and contributors

MPL-2.0

libzmq.txt

libtiff

4.7.2

Sam Leffler; SGI

libtiff (BSD-like)

libtiff.txt

FFTW

3.3.10

Matteo Frigo; MIT

GPL-2.0-or-later

fftw.txt

Ceres Solver

(pinned)

Google Inc. and contributors

BSD-3-Clause

ceres-solver.txt

Abseil

20250127 (required by Ceres)

Google Inc.

Apache-2.0

abseil.txt

Mbed TLS (with TF-PSA-Crypto)

4.2.0

The Mbed TLS Contributors

Apache-2.0 OR GPL-2.0-or-later (used under Apache-2.0)

mbedtls.txt, tf-psa-crypto.txt

Catch2

3.16.0

Catch2 Authors

BSL-1.0

catch2.txt

zlib-ng

2.3.3

Jean-loup Gailly and Mark Adler; the zlib-ng contributors

Zlib

zlib.txt

Eigen

3.4.1

Benoit Jacob, Gael Guennebaud and contributors

MPL-2.0 (+ BSD parts)

eigen.txt, README

Mbed TLS is fetched and statically linked only for viewer builds (JFJOCH_VIEWER_BUILD / JFJOCH_VIEWER_ONLY), where it is the TLS backend of jfjoch_viewer’s cpp-httplib client; the broker and writer never link it.

Catch2 is used only to build the test binary (jfjoch_test) and is not part of any shipped artifact; it is listed here for completeness.

zlib is supplied by zlib-ng built in its zlib-compatible mode (same zlib.h, same API and symbol names), so it is the zlib that HDF5, libtiff, cpp-httplib and GEMMI all link. It is built during the configure rather than added as a subproject; the licence is the zlib licence either way. Eigen is header-only: only its headers reach the binaries, and no Eigen CMake runs.

Vendored directly in the repository

These live in the source tree (see the path) rather than being fetched; traccc and the Ceres-derived minimiser are the exceptions - code adapted into first-party files rather than a vendored directory, see the notes at the end of this file.

Component

Path

Copyright

License (SPDX)

License text

nlohmann/json

include/nlohmann/

Niels Lohmann

MIT

nlohmann-json.txt

Macaron Base64

include/base64/

tomykaira

MIT

base64-macaron.txt

TinyCBOR

frame_serialize/tinycbor/

Intel Corporation

MIT

tinycbor.txt

Bitshuffle

compression/bitshuffle/

Kiyoshi Masui

MIT

bitshuffle.txt

Bitshuffle (h-perf)

compression/bitshuffle_hperf/

Kal Conley

Apache-2.0

bitshuffle-hperf.txt

LZ4

compression/lz4/

Yann Collet

BSD-2-Clause

lz4.txt

stb_image_write (v1.16, commit 31c1ad3)

preview/stb/

Sean Barrett

MIT OR Unlicense

stb_image_write.txt

HLS arbitrary-precision types

fpga/include/

Xilinx, Inc.

Apache-2.0

xilinx-hls-headers.txt

fast-feedback-indexer (commit a94fd4f)

image_analysis/indexing/fast-feedback-indexer/

PSI

BSD-3-Clause

fast-feedback-indexer.txt

GEMMI

gemmi_gph/

Global Phasing Ltd.

MPL-2.0

gemmi.txt

CCP4 Monomer Library (subset: restraint dictionary data)

image_analysis/structure_refinement/monomers/

CCP4 / the Monomer Library authors (Vagin et al.)

LGPL-3.0-only

ccp4-monomer-library.txt

Larch (its Cromer-Liberman routines, as GEMMI ports them)

gemmi_gph/fprime.cpp

Matthew Newville, The University of Chicago, et al.

MIT

larch.txt

PEGTL

gemmi_gph/gemmi/third_party/tao/

Dr. Colin Hirsch and Daniel Frey

MIT

pegtl.txt

sajson

gemmi_gph/gemmi/third_party/sajson.h

Chad Austin

MIT

sajson.txt

fast_float

gemmi_gph/gemmi/third_party/fast_float.h

The fast_float authors (Daniel Lemire et al.)

Apache-2.0 OR MIT OR BSL-1.0

fast-float.txt

half

gemmi_gph/gemmi/third_party/half.hpp

Christian Rau

MIT

half.txt

pocketfft

gemmi_gph/gemmi/third_party/pocketfft_hdronly.h

Max-Planck-Society; Peter Bell; MIT (FFTW-derived parts)

BSD-3-Clause

pocketfft.txt

tinydir

gemmi_gph/gemmi/third_party/tinydir.h

Cong Xu, Lautis Sun, Baudouin Feildel, Andargor

BSD-2-Clause

tinydir.txt

traccc (ACTS)

image_analysis/spot_finding/StrongPixelSet.cpp, SpotExtractorGPU.cu

CERN, for the benefit of the ACTS project

MPL-2.0

traccc.txt

fast-feedback-indexer (adapted)

image_analysis/indexing/FFBIDXIndexerCPU.cpp

PSI

BSD-3-Clause

fast-feedback-indexer.txt

Ceres Solver (adapted)

image_analysis/geom_refinement/LMSolver.h, LMSolver.cpp

Google Inc.

BSD-3-Clause

ceres-solver.txt

xbflash.qspi

tools/xbflash.qspi/

Xilinx / AMD

Apache-2.0

xbflash-qspi.txt

wingetopt

tools/wingetopt/

Todd C. Miller; The NetBSD Foundation

ISC AND BSD-2-Clause

wingetopt.txt

Data files in the repository

Not code and not linked into any binary: input files of the battery’s timing benchmark (tools/battery/timing.json), kept verbatim as downloaded.

Component

Path

Copyright

License (SPDX)

License text

AlphaFold Protein Structure Database predictions AF-P68082-F1, AF-P62894-F1, AF-P17090-F1, AF-P32322-F1 and AF-Q65MG6-F1 (v6), with their predicted aligned error

tools/battery/models/AF-*

DeepMind Technologies Limited; EMBL-EBI

CC-BY-4.0

alphafold-db.txt

wwPDB entries 4DC8, 4NWV, 9GJX, 9S02 and 9ZLO, deposited coordinates (mmCIF as the RCSB PDB serves them)

tools/battery/models/pdb/

the depositors; the wwPDB

CC0-1.0

wwPDB usage policy

The deposited entries are the reference models the benchmark’s placements are checked against, and 4NWV’s is also moved by a fixed transform at run time to make one start model.

Runtime libraries and SDKs (shipped in binaries, not in the source tree)

Component

Used by

License

Notice

Qt 6

jfjoch_viewer

LGPL-3.0

notice, LGPL-3.0

NVIDIA CUDA Toolkit (cudart, cuFFT)

CUDA builds

NVIDIA CUDA EULA

notice, EULA

Frontend (npm) dependencies

The React/TypeScript frontend (frontend/) bundles a large transitive tree of npm packages, overwhelmingly MIT/ISC/BSD/Apache-2.0 licensed. Their full notices are generated automatically:

cd frontend && npm run licenses     # writes dist/THIRD_PARTY_LICENSES.txt
+

The generated file is produced as part of the frontend build target and installed alongside the served frontend, so the shipped web UI carries its own attribution.

Notes on weak-copyleft and attribution-sensitive components

  • MPL-2.0 (Eigen, GEMMI, libzmq, traccc): file-level copyleft. GEMMI is vendored in gemmi_gph/ in trimmed form; libzmq and Eigen are fetched at build time (Eigen is header-only). The corresponding source is available from each project upstream.

  • GEMMI’s own bundled third-party headers — PEGTL, sajson, fast_float, half, pocketfft and tinydir, all under gemmi_gph/gemmi/third_party/ — are listed separately above rather than being absorbed into GEMMI’s row: they are other authors’ code under other licences (MIT, BSD and Apache/MIT/BSL), and GEMMI’s MPL-2.0 does not speak for them. Their terms are carried in the headers themselves rather than in LICENSE files, so the licenses/*.txt copies are kept by hand; only PEGTL ships a LICENSE, which COLLECT.sh copies.

  • traccc is the one entry that is not a vendored directory. Its sparse connected-component labelling enters two otherwise first-party files: StrongPixelSet.cpp adapts the SparseCCL source, and SpotExtractorGPU.cu follows the design of its GPU counterpart. MPL-2.0 is file-level, so both files name the origin at the top and are covered by licenses/traccc.txt. See ACKNOWLEDGEMENT.md for the citation.

  • Ceres Solver is also fetched and linked (table above); separately, LMSolver.h/.cpp re-implement its trust-region Levenberg-Marquardt minimiser, projected line search, polynomial step choice and sphere manifold for the crystal refinement, following its source. Both files name the origin at the top and are covered by licenses/ceres-solver.txt.

  • fast-feedback-indexer is also vendored and linked in CUDA builds (table above); separately, FFBIDXIndexerCPU.cpp ports its CUDA kernels to the CPU. The file names the origin at the top and is covered by licenses/fast-feedback-indexer.txt.

  • FFTW is GPL-2.0-or-later — compatible with, and absorbed by, this project’s GPL-3.0 license.

  • Apache-2.0 components: where upstream ships a NOTICE file, it is reproduced in the corresponding licenses/ text.

  • CCP4 Monomer Library (LGPL-3.0) is data, not code: the restraint dictionaries of the compounds rugnux’s refinement restrains, copied unmodified per compound into image_analysis/structure_refinement/monomers/ (links_and_mods.cif and ener_lib.cif cut down to the entries those compounds use, and the library’s metal-site distances of metals.json for its ions as metals.cif), with the library’s own COPYING. The build embeds them in the binary as text, and image_analysis/structure_refinement/monomers/update_monomers.py regenerates the subset from the upstream library, so the copy can be replaced by a user with a version of their own.

  • Qt (LGPL-3.0) and NVIDIA CUDA (EULA) carry redistribution conditions beyond a copyright notice; see their dedicated notice files. The verbatim LGPL-3.0 and CUDA EULA texts are bundled (licenses/Qt6-LGPL-3.0.txt, licenses/NVIDIA-CUDA-EULA.txt); the CUDA EULA is the one shipped with CUDA Toolkit 12.8 — replace it if you build against a different toolkit version.

\ No newline at end of file diff --git a/TOOLS.html b/TOOLS.html new file mode 100644 index 000000000..f885f21c0 --- /dev/null +++ b/TOOLS.html @@ -0,0 +1,13 @@ + Tools — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Tools

Besides the main services (jfjoch_broker, jfjoch_writer, jfjoch_viewer), the repository ships a number of command-line tools. Each prints its own usage when run without arguments (rugnux has no -h).

Data analysis

Rugnux

Offline CLI tool that runs the full crystallographic analysis pipeline (spot finding, indexing, integration, scaling/merging) on a stored HDF5 dataset, producing a _process.h5 file and, when merging, reflection files. Merging is on by default (--no-merge disables it). --mode picks what a run does: mx (the above, the default), azint (only azimuthal integration, no spot finding/indexing), scale (re-scale/merge the already-integrated reflections in a _process.h5 without re-integrating) or calibration (detector geometry from a calibrant’s powder rings, written as <prefix>.poni and <prefix>.json). See Rugnux.

rugnux installs on its own, as the rugnux package or as a standalone archive — see Installing Rugnux.

jfjoch_extract_hkl

Extracts reflections (HKL list) from a Jungfraujoch master file; can sum the same HKL across neighbouring images and compare against an XDS INTEGRATE.HKL reference. A developer utility: it is built from source but is not installed into any package.

jfjoch_recompress

Re-compresses /entry/data/data of a Jungfraujoch _data_NNNNNN.h5 file from bitshuffle/LZ4 to bitshuffle/Zstandard; every other object in the file is reproduced unchanged.

rugnux_refine_test

Runs the restrained refinement of a model against a rugnux merged MTZ without processing anything, for measuring the refinement on finished runs against another program on the same files. Prints the outcome and one JSON line for scripts.

FPGA / PCIe card management

jfjoch_pcie_status

Prints detailed status information about the card. Safe to run during data collection:

./jfjoch_pcie_status /dev/jfjoch0
+

jfjoch_pcie_net_cfg

Reads and modifies the network configuration of the card’s interfaces:

jfjoch_pcie_net_cfg <device name>
+     Read configuration for all network interfaces of a device
+jfjoch_pcie_net_cfg <device name> <if number>|fgen
+     Read configuration for a particular network interface / internal frame generator
+jfjoch_pcie_net_cfg <device name> <if number>|fgen ipv4 <IPv4 address>
+     Set IPv4 address for a particular network interface / internal frame generator
+jfjoch_pcie_net_cfg <device name> <if number>|fgen direct 0|1
+     Set direct mode for a particular network interface / internal frame generator
+jfjoch_pcie_net_cfg <device name> <if number>|fgen clear
+     Clear Ethernet counters for a particular network interface / internal frame generator
+

jfjoch_pcie_clear_net_counters

Resets the card’s Ethernet, UDP and ICMP packet counters (which otherwise run from power-on):

./jfjoch_pcie_clear_net_counters /dev/jfjoch0
+

Testing, benchmarking and simulation

jfjoch_udp_simulator

UDP packet simulator used to test the Jungfraujoch FPGA receiver.

jfjoch_fpga_test

Exercises and benchmarks the FPGA data path and receiver. With -H it runs the high-level synthesis C model on the CPU, so no FPGA device is required.

jfjoch_lite_perf_test

Performance test of the lite (CPU/GPU) analysis path — spot finding, indexing and optional file writing.

jfjoch_hdf5_test

Tests single-threaded HDF5 writer performance.

jfjoch_simplon_test

Minimal test client for a DECTRIS SIMPLON detector API.

jfjoch_stream2_replay

Replays a stored dataset as the image stream of a DECTRIS detector (a ZeroMQ PUSH socket the broker’s DECTRIS receiver connects to): start message, every image at the given rate, end message. With a stand-in for the detector’s control interface the broker then runs a real collection with no detector.

jfjoch_stills_gpu_replay

Replays the frames of a stored serial collection through the broker’s GPU analysis of converted JUNGFRAU frames: the pre-pass on the first images, then every frame analysed with the beam centre and mask it decided. Reports the pre-pass, the indexed fraction and the sustained rate.

\ No newline at end of file diff --git a/VERSIONING.html b/VERSIONING.html new file mode 100644 index 000000000..0145257fd --- /dev/null +++ b/VERSIONING.html @@ -0,0 +1 @@ + Semantic versioning — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Semantic versioning

Jungfraujoch is following semantic versioning. For this purpose we define public API as following:

  • OpenAPI configuration interface

  • CBOR serialization ZeroMQ stream

  • HDF5 file format

This means that a change in any of these formats must be accompanied by a version change - major version in case of breaking changes, minor version in case of feature expansion.

NOTE: FPGA design, PCIe driver, and internal libraries are not part of the public API and are considered internals of Jungfraujoch. Breaking changes in these components can happen without incrementing major version of the whole package. It will be marked in changelog.

\ No newline at end of file diff --git a/VIEWER_DOWNLOAD.html b/VIEWER_DOWNLOAD.html new file mode 100644 index 000000000..b0db08384 --- /dev/null +++ b/VIEWER_DOWNLOAD.html @@ -0,0 +1,4 @@ + Download the Jungfraujoch Viewer — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Download the Jungfraujoch Viewer

jfjoch_viewer is a standalone desktop application, pre-built for Linux, macOS and Windows with the Qt runtime included. The links point at the current release; the full list of what each release ships is on its release page.

Version 1.0.0-rc.186 · release notes · all releases

Linux

GPU, CUDA 12jfjoch_viewer-1.0.0-rc.186-linux-cuda12.tgz CPU onlyjfjoch_viewer-1.0.0-rc.186-linux-cpu.tgz

x86-64 with AVX2, any distribution from RHEL 8 on; a portable archive with the program, its desktop entry and icon. For the GPU: an NVIDIA driver, 525.60 or newer.

macOS

Apple Siliconjfjoch-viewer-1.0.0-rc.186-macos-arm64.dmg

Apple Silicon (M1 or newer), macOS 13 Ventura or newer. Signed and notarized disk image; drag the app to Applications. Intel Macs are not supported.

Windows

GPU, CUDA 13jfjoch-viewer-1.0.0-rc.186-win64-cuda13.exe CPU onlyjfjoch-viewer-1.0.0-rc.186-win64-cpu.exe

64-bit Windows with AVX (built and verified on Windows 11). An installer with the Qt runtime included. For the GPU: an NVIDIA R580 driver or newer; no CUDA toolkit.

On a machine with an NVIDIA GPU take the GPU build: its embedded spot finding, indexing and integration run on the card, and it also starts on a machine without one, on the CPU. The CPU only build runs the same pipeline at lower throughput and is the smaller download. A V100 needs the CUDA 12 build; the CUDA 13 builds start at Turing (T4) — see Release contents.

After downloading

Linux. The archive has no top-level directory, so unpack it into a directory of its own, then run the program from its bin/:

mkdir -p ~/jfjoch_viewer
+tar xzf jfjoch_viewer-<version>-linux-cuda12.tgz -C ~/jfjoch_viewer
+~/jfjoch_viewer/bin/jfjoch_viewer dataset_master.h5
+

The archive also carries the desktop entry, icon and D-Bus service file under share/, which the desktop picks up when the archive is unpacked into a prefix it searches, such as /usr/local. The Linux repositories carry the viewer as the jfjoch-viewer package as well (package repositories).

macOS. Open the disk image and drag jfjoch_viewer onto the Applications shortcut next to it. The image is signed and notarized by Apple, so it opens like any other application. Apple Silicon only; Intel Macs are not supported.

Windows. Run the installer. The CUDA and CPU variants share one install directory and replace each other, and are told apart in Add/Remove Programs as Jungfraujoch (CUDA) and Jungfraujoch (CPU).

Then File ▸ Open a Jungfraujoch or NXmx master file, a _process.h5 written by Rugnux, or any frame of a miniCBF, marCCD or SMV sweep; File ▸ Open HTTP follows a live collection from a running broker. jfjoch_viewer is the manual, with a guided tour of the four views most people use.

From source

The viewer builds on Linux, Windows (MSVC and CUDA) and macOS; Qt 6 is the one dependency that has to be installed first, everything else is fetched by the configure. See Building from source on Windows and on macOS; on Linux configure the full tree with -DJFJOCH_VIEWER_BUILD=ON (Deployment).

\ No newline at end of file diff --git a/WEB_FRONTEND.html b/WEB_FRONTEND.html new file mode 100644 index 000000000..0d8d594a3 --- /dev/null +++ b/WEB_FRONTEND.html @@ -0,0 +1 @@ + Web frontend — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Web frontend

Jungfraujoch is equipped with a React-based web frontend for a user-friendly experience. The frontend has the following features:

  • Presenting current state of the detector

  • Plotting results of online quality calculations

  • Showing live view images from the detector

  • JUNGFRAU calibration numbers

  • Configuring the detector, as well as pedestal/initialization operations

  • Rugnux live mode: the “Rugnux live” tab switches it on, sets its CPU threads and deadline, uploads the model, and follows the run’s steps; the dashboard shows the live run in a row of its own (see Rugnux live mode)

When the current dataset was started with tokens, the plots, the live preview and the measurement statistics need one of them: the key button in the top bar takes it (kept in the tab’s session storage only, cleared when the tab closes) and the start form has a field for the tokens of a new run. See Security.

The frontend is written in TypeScript. For details see the frontend/ directory.

\ No newline at end of file diff --git a/_images/rugnux_pipeline.svg b/_images/rugnux_pipeline.svg new file mode 100644 index 000000000..710f00e80 --- /dev/null +++ b/_images/rugnux_pipeline.svg @@ -0,0 +1,148 @@ + + + + +Per image(independent) + +Decode +bitshuffle/LZ4, CBF + +CUDA + +Azimuthal profile +noise, ice rings + +CUDA + +Spot finding +self-calibrating threshold + +CUDA + +Refine +beam centre, orientation + +autodiff + +Predict +Ewald crossing, partiality + +CUDA + +Integrate +2D profile fit + +Metal + +CUDA + + + + + + +Input +live, HDF5, CBF, SMV, marCCD + +Pre-scan +beam-stop shadow, beam centre, +spot widths + +tested + +CUDA + +frame sample + +every frame + +masks, spot widths + +Index +frame sample, 1D FFT + +tested + +autodiff + +CUDA + +Post-refine +distance, beam, cell, axis + +tested + +autodiff + +beam centre + +spots + +lattice + + +pass 1 + +pass 2, repeated while it gains + +Scale & merge (P1) +3D combine of partials + +CUDA + +Symmetry +space group, twinning, tNCS + +tested + +Scale & merge +in space group, resolution cut +decay, absorption, modulation + +tested + +CUDA + +Structure & map +placement or MR, σA maps + +tested + +Metal + +CUDA + +Refinement +restrained ML, +maps, blobs + +tested + +CUDA + +Report +MTZ, mmCIF, maps + + + + + + +without a model +with a model only - decides nothing +Whole dataset + +pass 2, or pass 1 if it merges better + +CUDA +CUDA kernel when a GPU is present + +Metal +also an Apple Metal kernel + +autodiff +derivatives by automatic differentiation + +tested +accepted only after a test against the data + \ No newline at end of file diff --git a/_images/rugnux_pipeline_stills.svg b/_images/rugnux_pipeline_stills.svg new file mode 100644 index 000000000..c9d20e2a3 --- /dev/null +++ b/_images/rugnux_pipeline_stills.svg @@ -0,0 +1,137 @@ + + + + +Per image(independent) + +Decode +bitshuffle/LZ4, CBF + +CUDA + +Azimuthal profile +noise per ring + +CUDA + +Spot finding +self-calibrating threshold + +CUDA + +Index +1D FFT, or ffbidx with a cell + +tested + +CUDA + +Refine +beam, orientation, cell + +autodiff + +Predict +excitation-error cutoff + +CUDA + +Integrate +2D profile fit + +Metal + +CUDA + + + + + + + +Input +HDF5, CXI, XTC, CBF, SMV + +Geometry +beam centre from the frames; +with a cell: distance, panels + +autodiff + +Pre-scan +beam-stop shadow, +bad pixels, saturation + +CUDA + +strong frames + + +every frame + +geometry + +masks + +Ambiguity +crystals reindexed alike: +from the data, or a +reference / model + +Scale & merge (P1) +consensus cell, crystal form, +per-image scale + +Symmetry +space group, twinning, tNCS + +tested + +Scale & merge +in space group, resolution cut +partiality, error model + +Structure & map +placement or MR, σA maps + +tested + +Metal + +CUDA + +Refinement +restrained ML, +maps, blobs + +tested + +CUDA + +Report +MTZ, mmCIF, maps + + + + + + + +without a model +with a model only - decides nothing +Whole dataset + +every crystal + +CUDA +CUDA kernel when a GPU is present + +Metal +also an Apple Metal kernel + +autodiff +derivatives by automatic differentiation + +tested +accepted only after a test against the data + \ No newline at end of file diff --git a/_images/viewer_general.png b/_images/viewer_general.png new file mode 100644 index 000000000..070689ec2 Binary files /dev/null and b/_images/viewer_general.png differ diff --git a/_images/viewer_grid_scan.png b/_images/viewer_grid_scan.png new file mode 100644 index 000000000..b890b640c Binary files /dev/null and b/_images/viewer_grid_scan.png differ diff --git a/_images/viewer_processing_results.png b/_images/viewer_processing_results.png new file mode 100644 index 000000000..c72547919 Binary files /dev/null and b/_images/viewer_processing_results.png differ diff --git a/_images/viewer_processing_settings.png b/_images/viewer_processing_settings.png new file mode 100644 index 000000000..cdf90427d Binary files /dev/null and b/_images/viewer_processing_settings.png differ diff --git a/_sources/ACKNOWLEDGEMENT.md.txt b/_sources/ACKNOWLEDGEMENT.md.txt new file mode 100644 index 000000000..0a8ddab27 --- /dev/null +++ b/_sources/ACKNOWLEDGEMENT.md.txt @@ -0,0 +1,946 @@ +# Acknowledgements + +How to cite Jungfraujoch and Rugnux, and the papers that describe them, is on the +[Publications](PUBLICATIONS.md) page. In short: + +- **Rugnux**: F. Leonarski and M. Wang, "Rugnux: from diffraction images to structure at synchrotrons + and XFELs in one program" (2026), bioRxiv + [doi:10.64898/2026.10.24.761522](https://doi.org/10.64898/2026.10.24.761522). +- **Jungfraujoch**: F. Leonarski, M. Brückner, C. Lopez-Cuenca, A. Mozzanica, H.-C. Stadler, + Z. Matěj, A. Castellane, B. Mesnet, J. Wojdyla, B. Schmitt and M. Wang, "Jungfraujoch: + hardware-accelerated data-acquisition system for kilohertz pixel-array X-ray detectors" (2023), + J. Synchrotron Rad. 30, 227-234 [doi:10.1107/S1600577522010268](https://doi.org/10.1107/S1600577522010268); + for real-time serial crystallography and live indexing feedback also J. Duan, H.-C. Stadler, + J. Nan et al., "Jungfraujoch: 38 GB s⁻¹ real-time serial crystallography – data acquisition and + live indexing feedback" (2026), J. Appl. Cryst. 59, 1668-1677 + [doi:10.1107/S1600576726008083](https://doi.org/10.1107/S1600576726008083). + +## Funding and support + +The project is supported by: +* Innosuisse via Innovation Project "NextGenDCU high data rate acquisition system for X-ray detectors in structural biology applications" (101.535.1 IP-ENG; Apr 2023 - Sep 2025). +* ETH Domain via Open Research Data Contribute project (Jan - Dec 2023). +* AMD University Program with donation of licenses of Ethernet IP cores and Vivado software. + +## Crystallographic methods adopted from other packages + +The analysis pipeline builds on methods first published, and in most cases first implemented, by +other crystallographic software. The code is Jungfraujoch's own; the methods are theirs, and are +acknowledged here, entry by entry: what was taken, from whom, and the citation. How rugnux uses each +method is described in the [data-analysis reference](CPU_DATA_ANALYSIS.md), not here. Where a +package's source was consulted this is said explicitly. Most of these packages are neither linked nor +vendored; the three that are - GEMMI, traccc and fast-feedback-indexer - also carry a licence +obligation, recorded in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). + +### Experimental geometry and physical corrections + +**[autoPROC](https://www.globalphasing.com/autoproc/)** — the principle, long argued for by Clemens +Vonrhein, that a pipeline does not take the experimental metadata it is given (beam centre, detector +geometry, goniometer axis) on trust but verifies it against the images and corrects it where it is +wrong, and with it that the beam centre is found from the images; the aim of a pipeline that takes the +decisions an expert would take and reports the evidence for each. C. Vonrhein, C. Flensburg, P. Keller, A. Sharff, O. Smart, W. Paciorek, T. Womack and G. Bricogne, "Data +processing and analysis with the autoPROC toolbox" (2011), Acta Cryst. D67, 293-302 +[doi:10.1107/S0907444911007773](https://doi.org/10.1107/S0907444911007773). + +**Sensor absorption and air path** — the attenuation coefficients of silicon, CdTe, dry air and +helium behind the oblique-incidence sensor efficiency, the parallax variance and the air-path +attenuation are the NIST tabulation. J. H. Hubbell and S. M. Seltzer, "Tables of X-Ray +Mass Attenuation Coefficients and Mass Energy-Absorption Coefficients from 1 keV to 20 MeV for +Elements Z = 1 to 92 and 48 Additional Substances of Dosimetric Interest" (1995, data updated 2004), +NIST Standard Reference Database 126 +[doi:10.18434/T4D01F](https://doi.org/10.18434/T4D01F). + +**Polarization correction** — the azimuthal polarization factor for a partially polarized +synchrotron source. R. Kahn, R. Fourme, A. Gadet, J. Janin, C. Dumas and D. Andre, "Macromolecular +crystallography with synchrotron radiation: photographic data collection and polarization +correction" (1982), J. Appl. Cryst. 15, 330-337 +[doi:10.1107/S0021889882012060](https://doi.org/10.1107/S0021889882012060). + +**Hexagonal-ice ring positions** — the eleven measured ring spacings from 3.895 to 1.522 Å. +D. W. Moreau, H. Atakisi and R. E. Thorne, "Ice in biomolecular cryocrystallography" (2021), Acta +Cryst. D77, 540-554 [doi:10.1107/S2059798321001170](https://doi.org/10.1107/S2059798321001170). +The bands below 1.522 Å are calculated here from ice Ih structure factors on the lattice constants +of K. Röttger, A. Endriss, J. Ihringer, S. Doyle and W. F. Kuhs, "Lattice constants and thermal +expansion of H2O and D2O ice Ih between 10 and 265 K" (1994), Acta Cryst. B50, 644-648 +[doi:10.1107/S0108768194004933](https://doi.org/10.1107/S0108768194004933). + +**Powder calibrants** — the silver behenate cell is T. C. Huang, H. Toraya, T. N. Blanton and Y. Wu, +"X-ray powder diffraction analysis of silver behenate, a possible low-angle diffraction standard" +(1993), J. Appl. Cryst. 26, 180-184 +[doi:10.1107/S0021889892009762](https://doi.org/10.1107/S0021889892009762); the CeO2 and silicon +cells are those of the NIST standard reference materials SRM 674b and SRM 640 (certificates, no DOI). + +### Spot finding + +**[CrystFEL](https://www.desy.de/~twhite/crystfel/)** — spot finding, the three-ring integration +region, the serial/stills processing model, and the per-frame indexing acceptance test +(`indexing_peak_check()` in `peaks.c`). T. A. White, R. A. Kirian, A. V. Martin, A. Aquila, K. Nass, +A. Barty and H. N. Chapman, "CrystFEL: a software suite for snapshot serial crystallography" (2012), +J. Appl. Cryst. 45, 335-341 [doi:10.1107/S0021889812002312](https://doi.org/10.1107/S0021889812002312). + +**Cheetah** — the per-resolution-ring background statistics with the Bragg peaks excluded by +iterated clipping, from peakfinder8. A. Barty, R. A. Kirian, F. R. N. C. Maia, M. Hantke, C. H. Yoon, +T. A. White and H. N. Chapman, "Cheetah: software for high-throughput reduction and analysis of +serial femtosecond X-ray diffraction data" (2014), J. Appl. Cryst. 47, 1118-1131 +[doi:10.1107/S1600576714007626](https://doi.org/10.1107/S1600576714007626). + +**Poisson significance threshold** — beyond the summation limit the Poisson quantile of the adaptive +spot-finding threshold is taken from the Cornish-Fisher expansion. E. A. Cornish and R. A. Fisher, +"Moments and cumulants in the specification of distributions" (1938), Rev. Int. Stat. Inst. 5, +307-320 [doi:10.2307/1400905](https://doi.org/10.2307/1400905). + +**GPU spot finder** — the CUDA spot finder was developed by Hans-Christian Stadler (PSI). + +**[traccc](https://github.com/acts-project/traccc)** — the sparse connected-component labelling +that groups strong pixels into spots: the CPU extractor adapts its SparseCCL source, the CUDA +extractor follows the design of its GPU counterpart (MPL-2.0; see +[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)). P. Gessinger, H. M. Gray, A. Krasznahorkay, +C. Leggett, J. Niermann, A. Salzburger, S. N. Swatman and B. Yeo, "traccc: GPU track reconstruction +library for HEP experiments" (2025), [arXiv:2505.22822](https://arxiv.org/abs/2505.22822). The +SparseCCL algorithm itself: A. Hennequin, B. Couturier, V. V. Gligorov and L. Lacassagne, "SparseCCL: +Connected Components Labeling and Analysis for sparse images" (2019), DASIP 2019, 65-70 +[doi:10.1109/DASIP48288.2019.9049184](https://doi.org/10.1109/DASIP48288.2019.9049184). + +**XDS and DISTL** — bounding a spot by its shape (how much of its bounding box it fills) rather than +by its size; the statistic is rugnux's own. XDS is cited under +[Integration and rotation geometry](#integration-and-rotation-geometry); Z. Zhang, N. K. Sauter, +H. van den Bedem, G. Snell and A. M. Deacon, "Automated diffraction image analysis and spot searching +for high-throughput crystal screening" (2006), J. Appl. Cryst. 39, 112-119 +[doi:10.1107/S0021889805040677](https://doi.org/10.1107/S0021889805040677). + +### Indexing + +**Fourier-transform indexing** — indexing with no prior knowledge of the cell by Fourier-transforming +the reciprocal-space positions of the spots, proposed as a three-dimensional transform; the de-novo +indexers (`-X fft`, `-X fftw`) use its one-dimensional projection form. G. Bricogne (1986), in +*Proceedings of the EEC Cooperative Workshop on Position-Sensitive Detector Software (Phase III)*, +LURE, Paris, p. 28 (a workshop proceedings without a DOI). + +**Rossmann FFT autoindexing** — projecting the reciprocal-space points onto many directions and +Fourier-transforming the 1D histograms. I. Steller, R. Bolotovsky and M. G. Rossmann, "An algorithm +for automatic indexing of oscillation images using Fourier analysis" (1997), J. Appl. Cryst. 30, +1036-1040 [doi:10.1107/S0021889897008777](https://doi.org/10.1107/S0021889897008777). + +**[MOSFLM](https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/)** — the practice of that algorithm, and +the post-refinement practice of which parameters are refined per image and which over a wedge. +H. R. Powell, "The Rossmann Fourier autoindexing algorithm in MOSFLM" (1999), Acta Cryst. D55, +1690-1695 [doi:10.1107/S0907444999009506](https://doi.org/10.1107/S0907444999009506); +A. G. W. Leslie and H. R. Powell, "Processing diffraction data with MOSFLM" (2007), in *Evolving +Methods for Macromolecular Crystallography*, NATO Science Series II, vol. 245, 41-51 +[doi:10.1007/978-1-4020-6316-9_4](https://doi.org/10.1007/978-1-4020-6316-9_4); +T. G. G. Battye, L. Kontogiannis, O. Johnson, H. R. Powell and A. G. W. Leslie, "iMOSFLM: a new +graphical interface for diffraction-image processing with MOSFLM" (2011), Acta Cryst. D67, 271-281 +[doi:10.1107/S0907444910048675](https://doi.org/10.1107/S0907444910048675); H. R. Powell, +T. G. G. Battye, L. Kontogiannis, O. Johnson and A. G. W. Leslie, "Integrating macromolecular X-ray +diffraction data with the graphical user interface iMosflm" (2017), Nat. Protoc. 12, 1310-1325 +[doi:10.1038/nprot.2017.037](https://doi.org/10.1038/nprot.2017.037). + +**[fast-feedback-indexer](https://github.com/paulscherrerinstitute/fast-feedback-indexer)** — the +known-cell indexer for serial stills (`-X ffbidx`), PSI's library linked at build time +(BSD-3-Clause; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)), implementing TORO. +P. Gasparotto, L. Barba, H.-C. Stadler, G. Assmann, H. Mendonça, A. W. Ashton, M. Janousch, +F. Leonarski and B. Béjar, "TORO Indexer: a PyTorch-based indexing algorithm for kilohertz serial +crystallography" (2024), J. Appl. Cryst. 57, 931-944 +[doi:10.1107/S1600576724003182](https://doi.org/10.1107/S1600576724003182). The CPU implementation +used without a GPU is a port of the library's CUDA kernels by H.-C. Stadler (PSI). + +### Cell reduction and lattice symmetry + +**[GEMMI](https://github.com/project-gemmi/gemmi)** — symmetry operations, unit-cell and +structure-factor machinery, and MTZ / XDS_ASCII I/O; vendored in `gemmi_gph/`, so it also carries a +licence obligation. M. Wojdyr, "GEMMI: A library for structural biology" (2022), J. Open Source +Softw. 7, 4200 [doi:10.21105/joss.04200](https://doi.org/10.21105/joss.04200). + +**Niggli reduction** — used through GEMMI's implementation. I. Křivý and B. Gruber, "A unified +algorithm for determining the reduced (Niggli) cell" (1976), Acta Cryst. A32, 297-298 +[doi:10.1107/S0567739476000636](https://doi.org/10.1107/S0567739476000636). The table of lattice +characters that maps a reduced cell to Bravais lattices and centrings follows International Tables +for Crystallography Vol. A, Table 9.2.5.1. + +**Numerically stable cell reduction** — the magnitude-scaled tolerance that decides the sign of a +structurally-zero scalar product. R. W. Grosse-Kunstleve, N. K. Sauter and P. D. Adams, "Numerically +stable algorithms for the computation of reduced unit cells" (2004), Acta Cryst. A60, 1-6 +[doi:10.1107/S010876730302186X](https://doi.org/10.1107/S010876730302186X). + +**Metric-symmetry search** — the obliquity of the 81 candidate two-folds of a reduced cell, and the +conventional axes derived from the rotation group found; the two-fold search is used through GEMMI. +Y. Le Page, "The derivation of the axes of the conventional unit cell from the dimensions of the +Buerger-reduced cell" (1982), J. Appl. Cryst. 15, 255-259 +[doi:10.1107/S0021889882011959](https://doi.org/10.1107/S0021889882011959). The step from the +two-folds found to a conventional cell, a centring and an integral change of basis follows +R. W. Grosse-Kunstleve, "Algorithms for deriving crystallographic space-group information" (1999), +Acta Cryst. A55, 383-395 [doi:10.1107/S0108767398010186](https://doi.org/10.1107/S0108767398010186). + +### Integration and rotation geometry + +**[XDS](https://xds.mr.mpg.de/)** — rotation geometry and notation, the reciprocal Lorentz and +partiality treatment, the maximum-likelihood mosaicity estimate, the `MINPK` criterion for a +reflection whose predicted profile is not cleanly its own, the intensity-based test for a centred +lattice, the recognition of shaded detector regions (`DEFPIX`), and the scaling correction surfaces +indexed by image number and detector region. W. Kabsch, "XDS" (2010), Acta Cryst. D66, 125-132 +[doi:10.1107/S0907444909047337](https://doi.org/10.1107/S0907444909047337); W. Kabsch, "Integration, +scaling, space-group assignment and post-refinement" (2010), Acta Cryst. D66, 133-144 +[doi:10.1107/S0907444909047374](https://doi.org/10.1107/S0907444909047374). + +**Profile fitting** — the Kabsch/Otwinowski iteration with reweighted, de-biased variances, from the +second XDS paper above and from Z. Otwinowski and W. Minor, "Processing of X-ray diffraction data +collected in oscillation mode" (1997), Methods Enzymol. 276, 307-326 +[doi:10.1016/S0076-6879(97)76066-X](https://doi.org/10.1016/S0076-6879%2897%2976066-X). + +**Two-dimensional integration** — integrating each image in the detector plane and only afterwards +combining a reflection's partials into a full, as against three-dimensional profile fitting through +the image stack, is the architecture of DENZO/SCALEPACK (Otwinowski and Minor, above) and MOSFLM +(cited under [Indexing](#indexing)). + +### Space group, twinning and pseudo-symmetry + +**[POINTLESS](https://www.ccp4.ac.uk/)** (CCP4) — the space-group search: scoring each candidate +rotation operator by the correlation of I(h) with I(Rh) on resolution-normalised intensities (E²); +the screw-axis test that scores a predicted-absent class against the rest of its own axial row and +lets confidence fall with the number of axial reflections instead of refusing below a count; and the +same test on a zone for a glide plane. P. Evans, "Scaling and assessment of data quality" (2006), +Acta Cryst. D62, 72-82 [doi:10.1107/S0907444905036693](https://doi.org/10.1107/S0907444905036693); +P. R. Evans, "An introduction to data reduction: space-group determination, scaling and intensity +statistics" (2011), Acta Cryst. D67, 282-292 +[doi:10.1107/S090744491003982X](https://doi.org/10.1107/S090744491003982X); P. R. Evans and +G. N. Murshudov, "How good are my data and what is the resolution?" (2013), Acta Cryst. D69, +1204-1214 [doi:10.1107/S0907444913000061](https://doi.org/10.1107/S0907444913000061); J. Agirre, +M. Atanasova, H. Bagdonas et al., "The CCP4 suite: integrative software for macromolecular +crystallography" (2023), Acta Cryst. D79, 449-461 +[doi:10.1107/S2059798323003595](https://doi.org/10.1107/S2059798323003595). + +**Centrosymmetric glide groups** — of two absence-equivalent glide groups the search writes the +centrosymmetric one (P2/c over Pc, C2/c over Cc), a missed inversion centre being the common error. +W. H. Baur and D. Kassner, "The perils of Cc: comparing the frequencies of falsely assigned space +groups with their general population" (1992), Acta Cryst. B48, 356-369 +[doi:10.1107/S0108768191014726](https://doi.org/10.1107/S0108768191014726). + +**Centre-of-symmetry statistics** — the acentric and centric intensity distributions and the +cumulative N(z) test built on them, read beside <|E^2-1|> and the L test. A. J. C. Wilson, "The +probability distribution of X-ray intensities" (1949), Acta Cryst. 2, 318-321 +[doi:10.1107/S0365110X49000813](https://doi.org/10.1107/S0365110X49000813); E. R. Howells, +D. C. Phillips and D. Rogers, "The probability distribution of X-ray intensities. II. Experimental +investigation and the X-ray detection of centres of symmetry" (1950), Acta Cryst. 3, 210-214 +[doi:10.1107/S0365110X50000513](https://doi.org/10.1107/S0365110X50000513). + +**Twinning L test** — the moments of L = (I1−I2)/(I1+I2) over pairs of neighbouring acentric +reflections against their untwinned and perfect-twin values; its robustness to pseudo-centering is +kept by the partner steps, which are restricted when a non-half-integer pseudo-translation is found. +J. E. Padilla and T. O. Yeates, "A statistic for local intensity differences: robustness to +anisotropy and pseudo-centering and utility for detecting twinning" (2003), Acta Cryst. D59, +1124-1130 [doi:10.1107/S0907444903007947](https://doi.org/10.1107/S0907444903007947). The +test's design - indicators on shell-normalised merged intensities, a twin law admitted within +3 degrees of obliquity - follows phenix.xtriage: Zwart, Grosse-Kunstleve and Adams (2005, cited under +[Data quality and anisotropy](#data-quality-and-anisotropy)); D. Liebschner, P. V. Afonine, +M. L. Baker et al., "Macromolecular structure determination using X-rays, neutrons and electrons: +recent developments in Phenix" (2019), Acta Cryst. D75, 861-877 +[doi:10.1107/S2059798319011471](https://doi.org/10.1107/S2059798319011471). + +**Twin fraction and twinned intensity** — the model (1−α) I(h) + α I(Th), and the fraction read +from the median of H = |I(h) − I(Th)|/(I(h) + I(Th)), uniform on [0, 1−2α]. T. O. Yeates, "Detecting +and overcoming crystal twinning" (1997), Methods Enzymol. 276, 344-358 +[doi:10.1016/S0076-6879(97)76068-3](https://doi.org/10.1016/S0076-6879%2897%2976068-3). + +**Twin refinement** — one fraction per domain operator of the lattice refined with the model, small +domains dropped, and twin-related reflections kept in one free set, as REFMAC5 does; the fractions +re-fitted by least squares at every cycle as REFMAC5 refines them, against an amplitude likelihood +with the twinned model amplitude in it (a simplification of REFMAC5's twinned-intensity target). +G. N. Murshudov, P. Skubák, A. A. Lebedev, N. S. Pannu, R. A. Steiner, R. A. Nicholls, M. D. Winn, +F. Long and A. A. Vagin, "REFMAC5 for the refinement of macromolecular crystal structures" (2011), +Acta Cryst. D67, 355-367 [doi:10.1107/S0907444911001314](https://doi.org/10.1107/S0907444911001314); +P. Roversi, E. Blanc, S. Johnson and S. M. Lea, "Tetartohedral twinning could happen to you too" +(2012), Acta Cryst. D68, 418-424 +[doi:10.1107/S0907444912006737](https://doi.org/10.1107/S0907444912006737); the six-domain case of +a monoclinic crystal on a hexagonal metric is K. A. Sultana, I. Alexeev, I. Kursula, P. Mäntsälä, +J. Niemi and G. Schneider, "Structure determination by multiwavelength anomalous diffraction of +aclacinomycin oxidoreductase: indications of multidomain pseudomerohedral twinning" (2007), Acta +Cryst. D63, 149-159 [doi:10.1107/S0907444906044271](https://doi.org/10.1107/S0907444906044271). +A twin fraction as a +parameter refined beside the model is SHELXL's BASF (rugnux re-fits it between cycles rather than in +the same least squares): R. Herbst-Irmer and G. M. Sheldrick, "Refinement of twinned structures with +SHELXL97" (1998), Acta Cryst. B54, 443-449 +[doi:10.1107/S0108768197018454](https://doi.org/10.1107/S0108768197018454). The twin laws come from +the lattice's metric: A. A. Lebedev, A. A. Vagin and G. N. Murshudov, "Intensity statistics in +twinned crystals with examples from the PDB" (2006), Acta Cryst. D62, 83-95 +[doi:10.1107/S0907444905036759](https://doi.org/10.1107/S0907444905036759). + +**Deciding pseudo-symmetry by refinement** — carrying the adopted group and the index-2 subgroups a +refused promotion leaves, each perfectly twinned by a law of its coset, to the model and deciding by +placing and refining it in each, rather than from intensity statistics. P. H. Zwart, +R. W. Grosse-Kunstleve, A. A. Lebedev, G. N. Murshudov and P. D. Adams, "Surprises and pitfalls +arising from (pseudo)symmetry" (2008), Acta Cryst. D64, 99-107 +[doi:10.1107/S090744490705531X](https://doi.org/10.1107/S090744490705531X); A. A. Lebedev and +M. N. Isupov, "Space-group and origin ambiguity in macromolecular structures with pseudo-symmetry +and its treatment with the program Zanuda" (2014), Acta Cryst. D70, 2430-2443 +[doi:10.1107/S1399004714014795](https://doi.org/10.1107/S1399004714014795). + +**Twinning by reticular merohedry** — a first-pass cell that is the coincidence lattice of two twin +domains (reticular merohedry or pseudo-merohedry of index up to 10, e.g. obverse/reverse +rhombohedral domains) is recognised by the nodes of neither domain being empty. The twin index is +Friedel's (G. Friedel, *Leçons de cristallographie*, 1926; no DOI); the split of the reflections into +those of one domain, of the other, of both and of neither, and the treatment of reticular +pseudo-merohedry (Herbst-Irmer and Sheldrick 1998, above), are Herbst-Irmer and Sheldrick's: +R. Herbst-Irmer and G. M. Sheldrick, "Refinement of obverse/reverse twins" (2002), Acta Cryst. B58, +477-481 [doi:10.1107/S0108768102001039](https://doi.org/10.1107/S0108768102001039). + +**Translational pseudo-symmetry** — the off-origin native-Patterson peak read as a pseudo-translation +between copies of the asymmetric unit, and the modulation it puts on the intensities, which the +axial systematic-absence test also scores against. The per-dataset permutation null for the peak, +the per-row estimate of the modulation depth, and its averaging over the lattice's rotations are +rugnux's own. R. J. Read, P. D. Adams and A. J. McCoy, "Intensity statistics in the presence of +translational noncrystallographic symmetry" (2013), Acta Cryst. D69, 176-183 +[doi:10.1107/S0907444912045374](https://doi.org/10.1107/S0907444912045374). A pseudo-translation +is declared at a Patterson peak of a fifth of the origin or more, Phaser's default (McCoy et al. +2007, cited under [Model placement and molecular replacement](#model-placement-and-molecular-replacement)). + +### Scaling and merging + +**[DIALS](https://dials.github.io/)** — the resolution cutoff from the CC1/2 fall-off, +per-observation outlier rejection at merge, the scaling error model, and the treatment of a +reflection whose background is contaminated; its published behaviour, and in places its source, +settled several choices here. G. Winter, D. G. Waterman, J. M. Parkhurst et al., "DIALS: +implementation and evaluation of a new integration package" (2018), Acta Cryst. D74, 85-97 +[doi:10.1107/S2059798317017235](https://doi.org/10.1107/S2059798317017235); D. G. Waterman, +G. Winter, R. J. Gildea et al., "Diffraction-geometry refinement in the DIALS framework" (2016), +Acta Cryst. D72, 558-575 [doi:10.1107/S2059798316002187](https://doi.org/10.1107/S2059798316002187); +J. Beilsten-Edmands, G. Winter, R. Gildea et al., "Scaling diffraction data in the DIALS software +package: algorithms and new approaches for multi-crystal scaling" (2020), Acta Cryst. D76, 385-399 +[doi:10.1107/S2059798320003198](https://doi.org/10.1107/S2059798320003198); J. M. Parkhurst, +G. Winter, D. G. Waterman et al., "Robust background modelling in DIALS" (2016), J. Appl. Cryst. 49, +1912-1921 [doi:10.1107/S1600576716013595](https://doi.org/10.1107/S1600576716013595). + +**Wilson outlier test** — judging an observation without symmetry mates against the acentric and +centric distributions of its shell, with the symmetry enhancement factor; rejecting only significant +observations, and keeping a reflection whose observations are all large, follows AIMLESS's EMAX test. +A. J. C. Wilson, "The probability distribution of X-ray intensities" (1949), Acta Cryst. 2, 318-321 +[doi:10.1107/S0365110X49000813](https://doi.org/10.1107/S0365110X49000813); P. Evans, "Scaling and +assessment of data quality" (2006), Acta Cryst. D62, 72-82 +[doi:10.1107/S0907444905036693](https://doi.org/10.1107/S0907444905036693). + +**Amplitudes from intensities** — the posterior-mean amplitude under the acentric and centric Wilson +priors. S. French and K. Wilson, "On the treatment of negative intensity observations" (1978), Acta +Cryst. A34, 517-525 [doi:10.1107/S0567739478001114](https://doi.org/10.1107/S0567739478001114). +Giving no amplitude to an intensity more than 3.7 sigma below zero, and scaling each reflection's +prior by the anisotropy tensor along its direction, follow CCP4's +[ctruncate](https://www.ccp4.ac.uk/) (C. Ballard and N. Stein), cited through the suite: +M. D. Winn, C. C. Ballard, K. D. Cowtan et al., "Overview of the CCP4 suite and current developments" +(2011), Acta Cryst. D67, 235-242 +[doi:10.1107/S0907444910045749](https://doi.org/10.1107/S0907444910045749). + +**Absorption as spherical harmonics** — the empirical absorption correction as a series of real +spherical harmonics of the beam directions in the crystal frame is Blessing's; its use as a +restrained scaling surface of the diffracted-beam direction follows SCALA and AIMLESS. R. H. Blessing, +"An empirical correction for absorption anisotropy" (1995), Acta Cryst. A51, 33-38 +[doi:10.1107/S0108767394005726](https://doi.org/10.1107/S0108767394005726); P. Evans, "Scaling and +assessment of data quality" (2006), Acta Cryst. D62, 72-82 +[doi:10.1107/S0907444905036693](https://doi.org/10.1107/S0907444905036693). + +**Per-frame scale smoothing** — the Whittaker smoother (a second-difference penalty, the smoothness +chosen by cross-validation) in Eilers's form. P. H. C. Eilers, "A perfect smoother" (2003), +Anal. Chem. 75, 3631-3636 [doi:10.1021/ac034173t](https://doi.org/10.1021/ac034173t); E. T. Whittaker, +"On a new method of graduation" (1923), Proc. Edinburgh Math. Soc. 41, 63-75 +[doi:10.1017/S0013091500077853](https://doi.org/10.1017/S0013091500077853). + +**Fisher's z-transformation** — averaging the change of the half-set CC1/2 over resolution shells on +atanh(CC) when the correction surfaces are cross-validated. R. A. Fisher, "Frequency distribution of +the values of the correlation coefficient in samples from an indefinitely large population" (1915), +Biometrika 10, 507-521 [doi:10.2307/2331838](https://doi.org/10.2307/2331838). + +**Frame disposition by delta-CC1/2** — the statistic in its sigma-tau form, the Fisher transformation +used to compare it, its standard error, and the rejection discipline (never remove a group whose +delta-CC1/2 is positive or near zero; remove a little, re-form the reference and repeat), whose +reference implementation is XDSCC12. G. Assmann, W. Brehm and K. Diederichs, "Identification of +rogue datasets in serial crystallography" (2016), J. Appl. Cryst. 49, 1021-1028 +[doi:10.1107/S1600576716005471](https://doi.org/10.1107/S1600576716005471); G. M. Assmann, M. Wang +and K. Diederichs, "Making a difference in multi-data-set crystallography: simple and deterministic +data-scaling/selection methods" (2020), Acta Cryst. D76, 636-652 +[doi:10.1107/S2059798320006348](https://doi.org/10.1107/S2059798320006348). Applying it at scaling, +to groups of images rather than whole datasets, follows DIALS (`dials.scale`): +J. Beilsten-Edmands, G. Winter, R. Gildea et al., "Scaling diffraction data in the DIALS software +package: algorithms and new approaches for multi-crystal scaling" (2020), Acta Cryst. D76, 385-399 +[doi:10.1107/S2059798320003198](https://doi.org/10.1107/S2059798320003198). + +**Reasons for a weak stretch of a sweep** — named in the field's own words: "loss of centring" after +autoPROC's "loss of centring during crystal rotation" (cited under +[Experimental geometry and physical corrections](#experimental-geometry-and-physical-corrections)), +and "crystal rotating out of the beam" after the HKL-2000 manual (HKL: Otwinowski and Minor 1997, +cited under [Integration and rotation geometry](#integration-and-rotation-geometry)). + +**Several sweeps merged as one** — each sweep's partials combined into fulls on their own, then the +fulls of all sweeps scaled together with per-sweep frame scales and a relative B, as XSCALE merges +data sets (W. Kabsch, "Integration, scaling, space-group assignment and post-refinement" (2010), +above). Ordering the sweeps by dose from their relative B follows K. Diederichs, "Some aspects of +quantitative analysis and correction of radiation damage" (2006), Acta Cryst. D62, 96-101 +[doi:10.1107/S0907444905031537](https://doi.org/10.1107/S0907444905031537). + +**Reference sweep of a joint merge** — the sweep whose own merge reaches the finest resolution, as +KAMO takes the data set of the smallest Wilson B. K. Yamashita, K. Hirata and M. Yamamoto, "KAMO: +towards automated data processing for microcrystals" (2018), Acta Cryst. D74, 441-449 +[doi:10.1107/S2059798318004576](https://doi.org/10.1107/S2059798318004576). + +### Serial data + +**Per-crystal post-refinement of stills** — refining per still the partiality parameters the spot +positions cannot pin (a small reorientation, the rocking width, the radial scale of the reciprocal +lattice) against the merged intensities, after PRIME and the mosaic-block model of Sauter et al. +M. Uervirojnangkoorn, O. B. Zeldin, A. Y. Lyubimov, J. Hattne, A. S. Brewster, N. K. Sauter, +A. T. Brunger and W. I. Weis, "Enabling X-ray free electron laser crystallography for challenging +biological systems from a limited number of crystals" (2015), eLife 4, e05421; N. K. Sauter, +J. Hattne, A. S. Brewster, N. Echols, P. H. Zwart and P. D. Adams, "Improved crystal orientation and +physical properties from single-shot XFEL stills" (2014), Acta Cryst. D70, 3299-3309 (DOIs not +verified here, so not given). + +**Indexing ambiguity without a reference** — putting each crystal into the indexing in which its +intensities agree best with all the others, iterated to convergence, the method CrystFEL's +`ambigator` also implements; rugnux measures the agreement as a product of standardised amplitudes +rather than a correlation. W. Brehm and K. Diederichs, "Breaking the indexing ambiguity in serial +crystallography" (2014), Acta Cryst. D70, 101-109 +[doi:10.1107/S1399004713025431](https://doi.org/10.1107/S1399004713025431). The same objective +settles the indexing of each sweep of a joint merge, decided over all pairs at once as dials.cosym +does: R. J. Gildea and G. Winter, "Determination of Patterson group symmetry from sparse +multi-crystal data sets in the presence of an indexing ambiguity" (2018), Acta Cryst. D74, 405-410 +[doi:10.1107/S2059798318002978](https://doi.org/10.1107/S2059798318002978). + +### Data quality and anisotropy + +**Data-quality statistics** — R_meas and R_pim, CC1/2 and CC\*, the per-shell CC(model, data), and +the reporting of I/sigma(I) follow the established conventions. K. Diederichs and P. A. Karplus, +"Improved R-factors for diffraction data analysis in macromolecular crystallography" (1997), +Nat. Struct. Biol. 4, 269-275 [doi:10.1038/nsb0497-269](https://doi.org/10.1038/nsb0497-269); +P. A. Karplus and K. Diederichs, "Linking crystallographic model and data quality" (2012), Science +336, 1030-1033 [doi:10.1126/science.1218231](https://doi.org/10.1126/science.1218231); M. S. Weiss, +"Global indicators of X-ray data quality" (2001), J. Appl. Cryst. 34, 130-135 +[doi:10.1107/S0021889800018227](https://doi.org/10.1107/S0021889800018227); K. Diederichs and +P. A. Karplus, "Better models by discarding data?" (2013), Acta Cryst. D69, 1215-1222 +[doi:10.1107/S0907444913001121](https://doi.org/10.1107/S0907444913001121). + +**Isomorphism of sweeps** — CC_AB / (CC\*_A CC\*_B) as the cosine of the angle between two data +sets, on which a joint merge decides whether a sweep joins. K. Diederichs, "Dissecting random and +systematic differences between noisy composite data sets" (2017), Acta Cryst. D73, 286-293 +[doi:10.1107/S2059798317000699](https://doi.org/10.1107/S2059798317000699). + +**Diffraction anisotropy** — the overall fall-off as a single anisotropic displacement tensor, its +symmetry constraints and the determinacy of its deviatoric part only: S. Sheriff and +W. A. Hendrickson, "Description of overall anisotropy in diffraction from macromolecular crystals" +(1987), Acta Cryst. A43, 118-121 +[doi:10.1107/S010876738709977X](https://doi.org/10.1107/S010876738709977X). Fitting it to the +intensity distribution with sigma(I) taken into account: A. N. Popov and G. P. Bourenkov, "Choice of +data-collection parameters based on statistic modelling" (2003), Acta Cryst. D59, 1145-1153 +[doi:10.1107/S0907444903008163](https://doi.org/10.1107/S0907444903008163). The directional +diffraction limits and the anisotropic deltaB reported as the range of the principal components +follow AIMLESS: P. R. Evans and G. N. Murshudov, "How good are my data and what is the resolution?" +(2013), Acta Cryst. D69, 1204-1214 +[doi:10.1107/S0907444913000061](https://doi.org/10.1107/S0907444913000061). That every run should +analyse and report its anisotropy is inspired by +[STARANISO](https://staraniso.globalphasing.org/): I. J. Tickle, C. Flensburg, P. Keller, +W. Paciorek, A. Sharff, C. Vonrhein and G. Bricogne (2016), STARANISO +([staraniso.globalphasing.org/cgi-bin/staraniso.cgi](https://staraniso.globalphasing.org/cgi-bin/staraniso.cgi)), +Cambridge, United Kingdom: Global Phasing Ltd. Rugnux reports the anisotropy; it corrects no +intensity and removes no reflection on a directional criterion. + +**Uncertainty conventions** — the IUCr Commission on Crystallographic Nomenclature's. +D. Schwarzenbach, S. C. Abrahams, H. D. Flack et al., "Statistical descriptors in crystallography: +Report of the IUCr Subcommittee on Statistical Descriptors" (1989), Acta Cryst. A45, 63-75 +[doi:10.1107/S0108767388009596](https://doi.org/10.1107/S0108767388009596); D. Schwarzenbach, +S. C. Abrahams, H. D. Flack, E. Prince and A. J. C. Wilson, "Statistical descriptors in +crystallography. II. Report of a Working Group on Expression of Uncertainty in Measurement" (1995), +Acta Cryst. A51, 565-569 [doi:10.1107/S0108767395002340](https://doi.org/10.1107/S0108767395002340). + +**Unit-cell e.s.d.s** — that the e.s.d.s of a least-squares cell fit are too small is Herbstein's +survey, which is why the cell is also fitted on blocks of consecutive frames. F. H. Herbstein, "How +precise are measurements of unit-cell dimensions from single crystals?" (2000), Acta Cryst. B56, +547-557 [doi:10.1107/S010876810000269X](https://doi.org/10.1107/S010876810000269X). + +**Measurability** — the fraction of acentric Bijvoet pairs significant at three sigma, reported +beside SigAno and CCanom, is phenix.xtriage's. P. H. Zwart, "Anomalous signal indicators in protein +crystallography" (2005), Acta Cryst. D61, 1437-1448 +[doi:10.1107/S0907444905023589](https://doi.org/10.1107/S0907444905023589). + +**Ice in the merged intensities** — reading ice off a merge's own intensities at the hexagonal-ice +ring positions, and the table of the rings' line strengths, are phenix.xtriage's; rugnux's comparison +is local in resolution where xtriage's is against the whole Wilson curve. P. H. Zwart, +R. W. Grosse-Kunstleve and P. D. Adams, "Xtriage and Fest: automatic assessment of X-ray data and +substructure structure factor estimation" (2005), CCP4 Newsletter on Protein Crystallography 43 (no +DOI). + +**Advice on the next collection** — the rotation a sweep needs and the blind region about the +spindle that a tilted second sweep recovers. Z. Dauter, "Data-collection strategies" (1999), Acta +Cryst. D55, 1703-1717 (DOI not verified here). + +### Model placement and molecular replacement + +**Bulk-solvent correction and overall scaling** — the flat bulk-solvent model, its starting values +and the physically meaningful range of its two parameters: A. Fokine and A. Urzhumtsev, "Flat +bulk-solvent model: obtaining optimal parameters" (2002), Acta Cryst. D58, 1387-1392 +[doi:10.1107/S0907444902010284](https://doi.org/10.1107/S0907444902010284). The mask (the region a +probe cannot reach, shrunk back), drawn with the radii REFMAC5 uses: J.-S. Jiang and A. T. Brünger, +"Protein hydration observed by X-ray diffraction: solvation properties of penicillopepsin and +neuraminidase crystal structures" (1994), J. Mol. Biol. 243, 100-115 +[doi:10.1006/jmbi.1994.1633](https://doi.org/10.1006/jmbi.1994.1633). The grid search over the +solvent pair with scale and anisotropic B refitted at each point: P. V. Afonine, +R. W. Grosse-Kunstleve and P. D. Adams, "A robust bulk-solvent correction and anisotropic scaling +procedure" (2005), Acta Cryst. D61, 850-855 +[doi:10.1107/S0907444905007894](https://doi.org/10.1107/S0907444905007894). The fit is unweighted, +as there and in REFMAC5: G. N. Murshudov, P. Skubak, A. A. Lebedev, N. S. Pannu, R. A. Steiner, +R. A. Nicholls, M. D. Winn, F. Long and A. A. Vagin, "REFMAC5 for the refinement of macromolecular +crystal structures" (2011), Acta Cryst. D67, 355-367 +[doi:10.1107/S0907444911001314](https://doi.org/10.1107/S0907444911001314). + +**sigma_A map coefficients** — the Rice and Woolfson likelihoods of |Fo| given |Fc| and sigma_A, the +figure of merit m and the scale D, and the bias-corrected coefficients 2mFo-DFc (acentric) and mFo +(centric). R. J. Read, "Improved Fourier coefficients for maps using phases from partial structures +with errors" (1986), Acta Cryst. A42, 140-149 +[doi:10.1107/S0108767386099622](https://doi.org/10.1107/S0108767386099622). + +**[ANODE](https://doi.org/10.1107/S0021889811041768)** — reading the anomalous difference map at the +atoms of a supplied model and reporting the strongest sites by name, instead of searching the map for +blobs. A. Thorn and G. M. Sheldrick, "ANODE: anomalous and heavy-atom density calculation" (2011), +J. Appl. Cryst. 44, 1285-1287 +[doi:10.1107/S0021889811041768](https://doi.org/10.1107/S0021889811041768). + +**Uniform random rotations** — the null a supplied model, and a molecular-replacement search, are +scored against draws rotations uniformly from SO(3) through a uniform random unit quaternion. +K. Shoemake, "Uniform Random Rotations", in *Graphics Gems III*, ed. D. Kirk, Academic Press (1992), +124-132 (no DOI). + +**Variable projection** — the rigid-body placement re-fits the overall scale at every step and folds +that re-fit into its Jacobian, in Kaufman's simplified form of Golub and Pereyra's derivative. +G. H. Golub and V. Pereyra, "The Differentiation of Pseudo-Inverses and Nonlinear Least Squares +Problems Whose Variables Separate" (1973), SIAM J. Numer. Anal. 10, 413-432 +[doi:10.1137/0710036](https://doi.org/10.1137/0710036); L. Kaufman, "A variable projection method +for solving separable nonlinear least squares problems" (1975), BIT 15, 49-57 +[doi:10.1007/BF01932995](https://doi.org/10.1007/BF01932995). + +**Predicted models** — `--model` (and `--mr`) place an AlphaFold prediction by molecular replacement. +J. Jumper, R. Evans, A. Pritzel et al., "Highly accurate protein structure prediction with +AlphaFold" (2021), Nature 596, 583-589 +[doi:10.1038/s41586-021-03819-2](https://doi.org/10.1038/s41586-021-03819-2); the models are those of +the AlphaFold Protein Structure Database: M. Varadi, S. Anyango, M. Deshpande et al., "AlphaFold +Protein Structure Database: massively expanding the structural coverage of protein-sequence space +with high-accuracy models" (2022), Nucleic Acids Res. 50, D439-D444 +[doi:10.1093/nar/gkab1061](https://doi.org/10.1093/nar/gkab1061). The model is prepared as +phenix.process_predicted_model prepares one (residues below pLDDT 70 removed, B factors from the +predicted coordinate error) and cut into rigid domains by its predicted aligned error: +R. D. Oeffner, T. Croll, C. Millán et al., "Putting AlphaFold models to work with +phenix.process_predicted_model and ISOLDE" (2022), Acta Cryst. D78, 1303-1314 +[doi:10.1107/S2059798322010026](https://doi.org/10.1107/S2059798322010026); the error itself is +AlphaFold's: J. Jumper, R. Evans, A. Pritzel et al., "Highly accurate protein structure prediction +with AlphaFold" (2021), Nature 596, 583-589 +[doi:10.1038/s41586-021-03819-2](https://doi.org/10.1038/s41586-021-03819-2). + +**Molecular replacement search** — scoring each orientation of the model by interpolating its +molecular transform, computed once by FFT, as AMoRe does: J. Navaza, "AMoRe: an automated package for +molecular replacement" (1994), Acta Cryst. A50, 157-163 +[doi:10.1107/S0108767393007597](https://doi.org/10.1107/S0108767393007597). The full-symmetry +translation function, all pairs of symmetry copies on one Fourier synthesis: R. A. Crowther and +D. M. Blow, "A method of positioning a known molecule in an unknown crystal structure" (1967), Acta +Cryst. 23, 544-548 [doi:10.1107/S0365110X67003172](https://doi.org/10.1107/S0365110X67003172). +A placement is a solution, as Phaser calls one, where its translation-function Z-score reaches 8: +A. J. McCoy, R. W. Grosse-Kunstleve, P. D. Adams, M. D. Winn, L. C. Storoni and R. J. Read, "Phaser +crystallographic software" (2007), J. Appl. Cryst. 40, 658-674 +[doi:10.1107/S0021889807021206](https://doi.org/10.1107/S0021889807021206). + +**Cell contents** — whether one copy fits the cell is read off the Matthews coefficient: +B. W. Matthews, "Solvent content of protein crystals" (1968), J. Mol. Biol. 33, 491-497 +[doi:10.1016/0022-2836(68)90205-2](https://doi.org/10.1016/0022-2836%2868%2990205-2); how many +copies to search for is weighed by its distribution over protein crystals: K. A. Kantardjieff and +B. Rupp, "Matthews coefficient probabilities: Improved estimates for unit cell contents of proteins, +DNA, and protein-nucleic acid complex crystals" (2003), Protein Sci. 12, 1865-1871 +[doi:10.1110/ps.0350503](https://doi.org/10.1110/ps.0350503). The placements of several copies are +compared by least-squares superposition: W. Kabsch, "A solution for the best rotation to relate two +sets of vectors" (1976), Acta Cryst. A32, 922-923 +[doi:10.1107/S0567739476001873](https://doi.org/10.1107/S0567739476001873). + +**Likelihood scoring of placements** — the log-likelihood gain from the Rice and Woolfson +distributions of the normalised amplitudes given the model's, with sigma_A falling off with resolution +for the model's expected coordinate error as Luzzati's D: V. Luzzati, "Traitement statistique des +erreurs dans la détermination des structures cristallines" (1952), Acta Cryst. 5, 802-810 +[doi:10.1107/S0365110X52002161](https://doi.org/10.1107/S0365110X52002161); R. J. Read, "Pushing the boundaries of molecular replacement with maximum +likelihood" (2001), Acta Cryst. D57, 1373-1382 +[doi:10.1107/S0907444901012471](https://doi.org/10.1107/S0907444901012471); the gain read as a +Z-score over the same orientation at other positions, as the likelihood-enhanced translation +function's is: A. J. McCoy, R. W. Grosse-Kunstleve, L. C. Storoni and R. J. Read, +"Likelihood-enhanced fast translation functions" (2005), Acta Cryst. D61, 458-464 +[doi:10.1107/S0907444905001617](https://doi.org/10.1107/S0907444905001617); and a model whose +expected log-likelihood gain is too small for a placement to stand out is not searched for: +A. J. McCoy, R. D. Oeffner, A. G. Wrobel, J. R. M. Ojala, K. Tryggvason, B. Lohkamp and R. J. Read, +"Ab initio solution of macromolecular crystal structures without direct methods" (2017), Proc. Natl. +Acad. Sci. USA 114, 3637-3641 [doi:10.1073/pnas.1701640114](https://doi.org/10.1073/pnas.1701640114). +Translational NCS is looked for in the native Patterson before the search, read as under +[Translational pseudo-symmetry](#space-group-twinning-and-pseudo-symmetry). The logarithm of the +Bessel function I0 is evaluated with the polynomial approximations of M. Abramowitz and I. A. Stegun, +"Handbook of Mathematical Functions" (1964), National Bureau of Standards, 9.8.1-9.8.2. + +### Structure refinement + +**Likelihood target** — the Rice distribution of an observed amplitude given the model's, and its +centric counterpart. N. S. Pannu and R. J. Read, "Improved structure refinement through maximum +likelihood" (1996), Acta Cryst. A52, 659-668 +[doi:10.1107/S0108767396004370](https://doi.org/10.1107/S0108767396004370); G. N. Murshudov, +A. A. Vagin and E. J. Dodson, "Refinement of macromolecular structures by the maximum-likelihood +method" (1997), Acta Cryst. D53, 240-255 +[doi:10.1107/S0907444996012255](https://doi.org/10.1107/S0907444996012255). Its parameters are fitted +in resolution bins, the variance on the free reflections and D on the working ones, as REFMAC5 +divides them (Murshudov et al. 2011, above); estimating them on free reflections follows +V. Y. Lunin and T. P. Skovoroda, "R-free likelihood-based estimates of errors for phases calculated +from atomic models" (1995), Acta Cryst. A51, 880-887 +[doi:10.1107/S010876739500688X](https://doi.org/10.1107/S010876739500688X); V. Y. Lunin, +P. V. Afonine and A. G. Urzhumtsev, "Likelihood-based refinement. I. Irremovable model errors" +(2002), Acta Cryst. A58, 270-282 +[doi:10.1107/S0108767302001046](https://doi.org/10.1107/S0108767302001046). + +**Gradients by FFT** — the derivatives of the target with respect to the structure factors +transformed into a map and summed against each atom's density derivatives. R. C. Agarwal, "A new +least-squares refinement technique based on the fast Fourier transform algorithm" (1978), Acta +Cryst. A34, 791-809 [doi:10.1107/S0567739478001618](https://doi.org/10.1107/S0567739478001618). + +**Minimiser** — L-BFGS (rugnux's own implementation). D. C. Liu and J. Nocedal, "On the limited +memory BFGS method for large scale optimization" (1989), Math. Program. 45, 503-528 +[doi:10.1007/BF01589116](https://doi.org/10.1007/BF01589116); its two-loop recursion: J. Nocedal, +"Updating quasi-Newton matrices with limited storage" (1980), Math. Comp. 35, 773-782 +[doi:10.1090/S0025-5718-1980-0572855-7](https://doi.org/10.1090/S0025-5718-1980-0572855-7). The +initial inverse Hessian is rescaled at each iteration by the latest pair, the self-scaling of +S. S. Oren and D. G. Luenberger, "Self-scaling variable metric (SSVM) algorithms. Part I" (1974), +Management Sci. 20, 845-862 [doi:10.1287/mnsc.20.5.845](https://doi.org/10.1287/mnsc.20.5.845), and +D. F. Shanno and K.-H. Phua, "Matrix conditioning and nonlinear optimization" (1978), Math. Program. +14, 149-160 [doi:10.1007/BF01588962](https://doi.org/10.1007/BF01588962). + +**Geometry restraints** — those of the CCP4 Monomer Library, a subset of which rugnux carries (see +[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)). A. A. Vagin, R. A. Steiner, A. A. Lebedev, +L. Potterton, S. McNicholas, F. Long and G. N. Murshudov, "REFMAC5 dictionary: organization of prior +chemical knowledge and guidelines for its use" (2004), Acta Cryst. D60, 2184-2195 +[doi:10.1107/S0907444904023510](https://doi.org/10.1107/S0907444904023510). They are applied +through GEMMI's topology (links, modifications, planes, chiral volumes, torsions): M. Wojdyr, "GEMMI: +A library for structural biology" (2022), J. Open Source Softw. 7, 4200 +[doi:10.21105/joss.04200](https://doi.org/10.21105/joss.04200). The torsion derivatives follow +A. Blondel and M. Karplus, "New formulation for derivatives of torsion angles and improper torsion +angles in molecular mechanics: elimination of singularities" (1996), J. Comput. Chem. 17, 1132-1141 +[doi:10.1002/(SICI)1096-987X(19960715)17:9<1132::AID-JCC5>3.0.CO;2-T](https://doi.org/10.1002/(SICI)1096-987X(19960715)17:9%3C1132::AID-JCC5%3E3.0.CO;2-T). + +**Riding hydrogens** — placed on their parent atoms by GEMMI's riding-hydrogen code, which follows +D. Liebschner, P. V. Afonine, A. G. Urzhumtsev and P. D. Adams, "Implementation of the riding +hydrogen model in CCTBX to support the next generation of X-ray and neutron joint refinement in +Phenix" (2020), Methods Enzymol. 634, 177-199 +[doi:10.1016/bs.mie.2020.01.007](https://doi.org/10.1016/bs.mie.2020.01.007). + +**B-factor restraints** — bonded atoms, and atoms in contact, restrained to each other in the +Kullback-Leibler form REFMAC5 uses (Murshudov et al. 2011, above); the divergence itself is +S. Kullback and R. A. Leibler's, "On information and sufficiency" (1951), Ann. Math. Statist. 22, +79-86 [doi:10.1214/aoms/1177729694](https://doi.org/10.1214/aoms/1177729694). The overall isotropic +B of the scale is moved into the atoms as phenix.refine moves it (Afonine et al. 2012, below). + +**Weights and R-free** — the weights of the X-ray term against the geometry and B restraints start +from the ratios of the gradients, as X-PLOR's crystallographic weight was first set: A. T. Brünger, +M. Karplus and G. A. Petsko, "Crystallographic refinement by simulated annealing: application to +crambin" (1989), Acta Cryst. A45, 50-61 +[doi:10.1107/S0108767388009195](https://doi.org/10.1107/S0108767388009195); and are chosen among +short refinements by R-free with the geometry held within bounds, as phenix.refine chooses them: +P. V. Afonine, R. W. Grosse-Kunstleve, N. Echols, J. J. Headd, N. W. Moriarty, M. Mustyakimov, +T. C. Terwilliger, A. Urzhumtsev, P. H. Zwart and P. D. Adams, "Towards automated crystallographic +structure refinement with phenix.refine" (2012), Acta Cryst. D68, 352-367 +[doi:10.1107/S0907444912001308](https://doi.org/10.1107/S0907444912001308). R-free itself: +A. T. Brünger, "Free R value: a novel statistical quantity for assessing the accuracy of crystal +structures" (1992), Nature 355, 472-475 [doi:10.1038/355472a0](https://doi.org/10.1038/355472a0). + +**Robust scaling of the model** — the overall scale and anisotropic B are fitted by iteratively +reweighted least squares with the pseudo-Huber weight. P. J. Huber, "Robust estimation of a location +parameter" (1964), Ann. Math. Statist. 35, 73-101 +[doi:10.1214/aoms/1177703732](https://doi.org/10.1214/aoms/1177703732), in the smooth form of +P. Charbonnier, L. Blanc-Féraud, G. Aubert and M. Barlaud, "Deterministic edge-preserving +regularization in computed imaging" (1997), IEEE Trans. Image Process. 6, 298-311 +[doi:10.1109/83.551699](https://doi.org/10.1109/83.551699). + +**Metal-site restraints** — the bonds of metal ions to the donor atoms the model's LINK records name +are restrained at the distances of the Monomer Library's own metal-site statistics (`metals.json`, +embedded as `monomers/metals.cif`), in line with the surveys of M. M. Harding, "Geometry of +metal-ligand interactions in proteins" (2001), Acta Cryst. D57, 401-411 +[doi:10.1107/S0907444900019168](https://doi.org/10.1107/S0907444900019168) and "Small revisions to +predicted distances around metal sites in proteins" (2006), Acta Cryst. D62, 678-682 +[doi:10.1107/S0907444906014594](https://doi.org/10.1107/S0907444906014594), and, for Mg²⁺, Na⁺ and +K⁺ at nucleic acids, F. Leonarski, L. D'Ascenzo and P. Auffinger, "Mg2+ ions: do they bind to +nucleobase nitrogens?" (2017), Nucleic Acids Res. 45, 987-1004 +[doi:10.1093/nar/gkw1175](https://doi.org/10.1093/nar/gkw1175). + +**Anisotropic displacements** — the TLS model of a rigid body's translation, libration and their +correlation: V. Schomaker and K. N. Trueblood, "On the rigid-body motion of molecules in crystals" +(1968), Acta Cryst. B24, 63-76 +[doi:10.1107/S0567740868001718](https://doi.org/10.1107/S0567740868001718); refined against the +likelihood with a residual B per atom, the B column read as total or residual, as in M. D. Winn, +M. N. Isupov and G. N. Murshudov, "Use of TLS parameters to model anisotropic displacements in +macromolecular refinement" (2001), Acta Cryst. D57, 122-133 +[doi:10.1107/S0907444900014736](https://doi.org/10.1107/S0907444900014736). The chains are cut into +TLS groups as TLSMD cuts them: J. Painter and E. A. Merritt, "Optimal description of a protein +structure in terms of multiple groups undergoing TLS motion" (2006), Acta Cryst. D62, 439-450 +[doi:10.1107/S0907444906005270](https://doi.org/10.1107/S0907444906005270). Atoms with a U of their +own are restrained by the rigid-bond postulate of F. L. Hirshfeld, "Can X-ray data distinguish +bonding effects from vibrational smearing?" (1976), Acta Cryst. A32, 239-244 +[doi:10.1107/S0567739476000533](https://doi.org/10.1107/S0567739476000533), in the form of SHELXL's +RIGU: A. Thorn, B. Dittrich and G. M. Sheldrick, "Enhanced rigid-bond restraints" (2012), Acta +Cryst. A68, 448-451 [doi:10.1107/S0108767312014535](https://doi.org/10.1107/S0108767312014535), +with SHELXL's SIMU and ISOR restraints as G. M. Sheldrick, "Crystal structure refinement with +SHELXL" (2015), Acta Cryst. C71, 3-8 +[doi:10.1107/S2053229614024218](https://doi.org/10.1107/S2053229614024218) documents them. Which +displacement model a refinement keeps is decided on the free set rather than by a rule of +resolution: E. A. Merritt, "To B or not to B: a question of resolution?" (2012), Acta Cryst. D68, +468-477 [doi:10.1107/S0907444911028320](https://doi.org/10.1107/S0907444911028320). + +**NCS restraints** — copies found by sequence alignment with REFMAC5's criterion (Murshudov et al. +2011, above) and restrained locally on pairs of corresponding interatomic distances under the +Geman-McClure loss, as REFMAC5's local NCS restraints are, with the distance range of +R. A. Nicholls, F. Long and G. N. Murshudov, "Low-resolution refinement tools in REFMAC5" (2012), +Acta Cryst. D68, 404-417 [doi:10.1107/S090744491105606X](https://doi.org/10.1107/S090744491105606X). +The superposition behind the rms criterion is GEMMI's QCP: D. L. Theobald, "Rapid calculation of +RMSDs using a quaternion-based characteristic polynomial" (2005), Acta Cryst. A61, 478-480 +[doi:10.1107/S0108767305015266](https://doi.org/10.1107/S0108767305015266); P. Liu, D. K. Agrafiotis +and D. L. Theobald, "Fast determination of the optimal rotational matrix for macromolecular +superpositions" (2010), J. Comput. Chem. 31, 1561-1563 +[doi:10.1002/jcc.21439](https://doi.org/10.1002/jcc.21439). +The case for local restraints over a superposition, decided by R-free: G. J. Kleywegt, "Use of +non-crystallographic symmetry in protein structure refinement" (1996), Acta Cryst. D52, 842-857 +[doi:10.1107/S0907444995016477](https://doi.org/10.1107/S0907444995016477); I. Usón, E. Pohl, +T. R. Schneider, Z. Dauter, A. Schmidt, H.-J. Fritz and G. M. Sheldrick, "1.7 Å structure of the +stabilized REIv mutant T39K. Application of local NCS restraints" (1999), Acta Cryst. D55, +1158-1167 [doi:10.1107/S0907444999003972](https://doi.org/10.1107/S0907444999003972); and +J. J. Headd, N. Echols, P. V. Afonine, N. W. Moriarty, R. J. Gildea and P. D. Adams, "Flexible +torsion-angle noncrystallographic symmetry restraints for improved macromolecular structure +refinement" (2014), Acta Cryst. D70, 1346-1356 +[doi:10.1107/S1399004714003277](https://doi.org/10.1107/S1399004714003277), whose comparison is why +the copies' B factors are refined independently. + +**Special positions** — an atom on a special position is kept on it, its shifts confined to the +subspace its site symmetry leaves unchanged. R. W. Grosse-Kunstleve and P. D. Adams, "Algorithms for +deriving crystallographic space-group information. II. Treatment of special positions" (2002), Acta +Cryst. A58, 60-65 [doi:10.1107/S0108767301016658](https://doi.org/10.1107/S0108767301016658). + +### Solvent, ions and unmodelled density + +**Unmodelled density** — the connected regions of the difference map above a cutoff, found by flood +fill as Coot's "unmodelled blobs" are, in GEMMI's implementation. P. Emsley, B. Lohkamp, W. G. Scott +and K. Cowtan, "Features and development of Coot" (2010), Acta Cryst. D66, 486-501 +[doi:10.1107/S0907444910007493](https://doi.org/10.1107/S0907444910007493). + +**Water build** — the documented ordered-solvent defaults of phenix.refine (difference-map peaks +from 3 σ, picking to 2.8 Å, waters added, filtered and refined between macro-cycles; Afonine et al. +2012, above); the distance band to the model, widened a little from the 2.4-3.2 Å Coot's Find Waters +keeps (Emsley et al. 2010, above); and the removal of a water in negative difference density at +-3 σ (Echols et al. 2014, below). + +**Ion stereochemistry** — the coordination bands, the Mg²⁺ exclusion zone and the clash shells of +the surveys of ions at nucleic acids by P. Auffinger's group. N. Naleem, A. Henning-Knechtel, +S. Kirmizialtin and P. Auffinger, "Cat_Wiz: a stereochemistry-guided toolkit for locating, +diagnosing, and annotating Mg2+ ions in RNA structures" (2026), Nucleic Acids Res. 54, gkag120 +[doi:10.1093/nar/gkag120](https://doi.org/10.1093/nar/gkag120); F. Leonarski, A. Henning-Knechtel, +S. Kirmizialtin, E. Ennifar and P. Auffinger, "Principles of ion binding to RNA inferred from the +analysis of a 1.55 Å resolution bacterial ribosome structure – Part I: Mg2+" (2025), Nucleic Acids +Res. 53, gkae1148 [doi:10.1093/nar/gkae1148](https://doi.org/10.1093/nar/gkae1148); F. Leonarski, +L. D'Ascenzo and P. Auffinger, "Nucleobase carbonyl groups are poor Mg2+ inner-sphere binders but +excellent monovalent ion binders—a critical PDB survey" (2019), RNA 25, 173-192 +[doi:10.1261/rna.068437.118](https://doi.org/10.1261/rna.068437.118); and their 2017 survey (above). +The score that combines the criteria is rugnux's own. + +**Ion identification** — the ligand sphere of the bond-valence sums, the reading of halides by their +donors, and telling a light ion from a water by its density: N. Echols, N. Morshed, P. V. Afonine, +A. J. McCoy, M. D. Miller, R. J. Read, J. S. Richardson, T. C. Terwilliger and P. D. Adams, +"Automated identification of elemental ions in macromolecular crystal structures" (2014), Acta Cryst. +D70, 1104-1114 [doi:10.1107/S1399004714001308](https://doi.org/10.1107/S1399004714001308); +N. Morshed, N. Echols and P. D. Adams, "Using support vector machines to improve elemental ion +identification in macromolecular crystal structures" (2015), Acta Cryst. D71, 1147-1158 +[doi:10.1107/S1399004715004241](https://doi.org/10.1107/S1399004715004241). The chloride's shell of +donors: O. Carugo, "Buried chloride stereochemistry in the Protein Data Bank" (2014), BMC Struct. +Biol. 14, 19 [doi:10.1186/s12900-014-0019-8](https://doi.org/10.1186/s12900-014-0019-8); halides at +hydrophobic surfaces: Z. Dauter and M. Dauter, "Entering a new phase: using solvent halide ions in +protein structure determination" (2001), Structure 9, R21-R26 +[doi:10.1016/S0969-2126(01)00565-2](https://doi.org/10.1016/S0969-2126(01)00565-2). + +**Bond-valence sums** — I. D. Brown and D. Altermatt, "Bond-valence parameters obtained from a +systematic analysis of the Inorganic Crystal Structure Database" (1985), Acta Cryst. B41, 244-247 +[doi:10.1107/S0108768185002063](https://doi.org/10.1107/S0108768185002063), with the R₀ of +N. E. Brese and M. O'Keeffe, "Bond-valence parameters for solids" (1991), Acta Cryst. B47, 192-197 +[doi:10.1107/S0108768190011041](https://doi.org/10.1107/S0108768190011041), as tabulated by +H. Zheng, K. M. Langner, G. P. Shields, J. Hou, M. Kowiel, F. H. Allen, G. Murshudov and W. Minor, +"Data mining of iron(II) and iron(III) bond-valence parameters, and their relevance for +macromolecular crystallography" (2017), Acta Cryst. D73, 316-325 +[doi:10.1107/S2059798317000584](https://doi.org/10.1107/S2059798317000584); weighted by occupancy +as P. Müller, S. Köpke and G. M. Sheldrick weight them, "Is the bond-valence method able to identify +metal atoms in protein structures?" (2003), Acta Cryst. D59, 32-37 +[doi:10.1107/S0907444902018000](https://doi.org/10.1107/S0907444902018000); the normalised vector +sum and its outlier bound are CheckMyMetal's: H. Zheng, D. R. Cooper, P. J. Porebski, +I. G. Shabalin, K. B. Handing and W. Minor, "CheckMyMetal: a macromolecular metal-binding validation +tool" (2017), Acta Cryst. D73, 223-233 +[doi:10.1107/S2059798317001061](https://doi.org/10.1107/S2059798317001061). + +**Anomalous scattering factors** — f″ at the data's wavelength, as GEMMI computes it (its port of +the Larch routines). D. T. Cromer and D. A. Liberman, "Anomalous dispersion calculations near to +and on the long-wavelength side of an absorption edge" (1981), Acta Cryst. A37, 267-268 +[doi:10.1107/S0567739481000600](https://doi.org/10.1107/S0567739481000600), with the corrections of +L. Kissel and R. H. Pratt, "Corrections to tabulated anomalous-scattering factors" (1990), Acta +Cryst. A46, 170-175 [doi:10.1107/S0108767389010718](https://doi.org/10.1107/S0108767389010718). + +## Software and computing methods + +**GPU decompression** — decoding bitshuffle+LZ4 images on the GPU rather than on the host follows +Jon Wright (ESRF): "Experiences with GPU decompression for bitshuffle + LZ4 data", HDF5 User Group +meeting (2021), and [bslz4decoders](https://github.com/jonwright/bslz4decoders). The CUDA kernels +are Jungfraujoch's own; the approach is his. + +**Parallel connected components** — removing the islands of the bulk-solvent mask on the GPU with a +parallel union-find. D. P. Playne and K. Hawick, "A New Algorithm for Parallel Connected-Component +Labelling on GPUs" (2018), IEEE Trans. Parallel Distrib. Syst. 29, 1217-1230 +[doi:10.1109/TPDS.2018.2799216](https://doi.org/10.1109/TPDS.2018.2799216). + +**Correctly rounded integer division** — the FFT indexer's GPU peak search divides by a reciprocal +multiplication corrected once by the exact remainder. P. W. Markstein, "Computation of elementary +functions on the IBM RISC System/6000 processor" (1990), IBM J. Res. Dev. 34, 111-119. + +**Anderson acceleration** — of the per-frame scaling loops of the rotation merge, in the type-II +form. H. F. Walker and P. Ni, "Anderson acceleration for fixed-point iterations" (2011), SIAM J. +Numer. Anal. 49, 1715-1735 [doi:10.1137/10078356X](https://doi.org/10.1137/10078356X), after +D. G. Anderson, "Iterative procedures for nonlinear integral equations" (1965), J. ACM 12, 547-560 +[doi:10.1145/321296.321305](https://doi.org/10.1145/321296.321305). + +**Bootstrap** — the interval reported for ISa. B. Efron, "Bootstrap methods: another look at the +jackknife" (1979), Ann. Statist. 7, 1-26 +[doi:10.1214/aos/1176344552](https://doi.org/10.1214/aos/1176344552). Its draws are Poisson weights +hashed with the SplitMix64 finaliser of G. L. Steele Jr., D. Lea and C. H. Flood, "Fast splittable +pseudorandom number generators" (2014), Proc. OOPSLA 2014, 453-472 +[doi:10.1145/2660193.2660195](https://doi.org/10.1145/2660193.2660195). + +**Error-free floating-point arithmetic** — the single-precision exp shared between the CPU and an +Apple GPU (`BraggExp.h`): the argument reduction of W. J. Cody and W. Waite, "Software Manual for the +Elementary Functions" (1980), Prentice-Hall; the exact product (with Veltkamp's split) and Fast2Sum +of T. J. Dekker, "A floating-point technique for extending the available precision" (1971), Numer. +Math. 18, 224-242; and the 2Sum of D. E. Knuth, "The Art of Computer Programming, Vol. 2: +Seminumerical Algorithms", section 4.2.2. + +**Colormaps** — Viridis, Magma and Inferno from Matplotlib, under its BSD-compatible license. +J. D. Hunter, "Matplotlib: A 2D graphics environment" (2007), Comput. Sci. Eng. 9, 90-95 +[doi:10.1109/MCSE.2007.55](https://doi.org/10.1109/MCSE.2007.55). + +**[Mol\*](https://molstar.org/)** — the web frontend's structure viewer. D. Sehnal, S. Bittrich, +M. Deshpande, R. Svobodová, K. Berka, V. Bazgier, S. Velankar, S. K. Burley, J. Koča and A. S. Rose, +"Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures" +(2021), Nucleic Acids Res. 49, W431-W437 [doi:10.1093/nar/gkab314](https://doi.org/10.1093/nar/gkab314). +Its setup follows the one Guillaume Gotthard (PSI) tuned for [AareDB](https://gitea.psi.ch/mx/aaredb), +the sample-management and data-pipeline system of the PSI MX beamlines: the Coot-style mouse +controls, the model representations and colours, and the display of the density maps. The virtual +trackball is a port of Coot's, itself a port of SGI's `trackball.c` by Gavin Bell. + +## File formats read from a published specification + +**CBF / imgCIF** — the native miniCBF reader implements the `x-CBF_BYTE_OFFSET` compression and the +imgCIF `_axis` table from the specification alone; no CBFlib or other CBF code is used. +H. J. Bernstein and A. P. Hammersley, "Specification of the Crystallographic Binary File +(CBF/imgCIF)" (2006), International Tables for Crystallography Vol. G, 37-43 +[doi:10.1107/97809553602060000729](https://doi.org/10.1107/97809553602060000729); +A. P. Hammersley, H. J. Bernstein and J. D. Westbrook, "Image dictionary (imgCIF)" (2006), +International Tables for Crystallography Vol. G, 444-458 +[doi:10.1107/97809553602060000746](https://doi.org/10.1107/97809553602060000746). + +**PILATUS count-rate clipping** — that the count-rate correction clips an over-range pixel to the +cutoff rather than flagging it, which is how the miniCBF reader tells a saturated pixel. P. Trueb, +C. Dejoie, M. Kobas, P. Pattison, D. J. Peake, V. Radicci, B. A. Sobott, D. A. Walko and +C. Broennimann, "Bunch mode specific rate corrections for PILATUS3 detectors" (2015), J. Synchrotron +Rad. 22, 701-707 [doi:10.1107/S1600577515003288](https://doi.org/10.1107/S1600577515003288). + +**d\*TREK SMV** — the SMV reader reads the d\*TREK header vocabulary of Rigaku's CrystalClear from +the headers themselves, interpreting the detector vectors as dxtbx does; no d\*TREK or dxtbx code is +used. J. W. Pflugrath, "The finer things in X-ray diffraction data collection" (1999), Acta Cryst. +D55, 1718-1725 [doi:10.1107/S090744499900935X](https://doi.org/10.1107/S090744499900935X); +[dxtbx](https://github.com/cctbx/dxtbx): J. M. Parkhurst, A. S. Brewster, L. Fuentes-Montero, +D. G. Waterman et al., "dxtbx: the diffraction experiment toolbox" (2014), J. Appl. Cryst. 47, +1459-1465 [doi:10.1107/S1600576714011996](https://doi.org/10.1107/S1600576714011996). + +## Public diffraction data used for testing + +In addition to in-house datasets collected at SLS 2.0, Jungfraujoch is tested against public +diffraction data collected on other people's beamlines, on detectors and in file formats we do not +produce ourselves. Every dataset used, the DOI to cite for it, and the deposition it belongs to are +listed in [EXTERNAL_TEST_DATA](EXTERNAL_TEST_DATA.md) and +[EXTERNAL_TEST_DATA_STILLS](EXTERNAL_TEST_DATA_STILLS.md); we thank the depositors, and the +repositories that make the data findable and citable. + +**[IRRMC](https://proteindiffraction.org/)**, the Integrated Resource for Reproducibility in +Macromolecular Crystallography (Minor lab, University of Virginia), is the source of the largest +share of them; it releases its data under CC0 and asks that the DOI of the dataset be cited. +M. Grabowski, K. M. Langner, M. Cymborowski, P. J. Porebski, P. Sroka, H. Zheng, D. R. Cooper, +M. D. Zimmerman, M.-A. Elsliger, S. K. Burley and W. Minor, "A public database of macromolecular +diffraction experiments" (2016), Acta Cryst. D72, 1181-1193 +[doi:10.1107/S2059798316014716](https://doi.org/10.1107/S2059798316014716); M. Grabowski, +M. Cymborowski, P. J. Porebski, T. Osinski, I. G. Shabalin, D. R. Cooper and W. Minor, "The +Integrated Resource for Reproducibility in Macromolecular Crystallography: Experiences of the first +four years" (2019), Struct. Dyn. 6, 064301 +[doi:10.1063/1.5128672](https://doi.org/10.1063/1.5128672). + +**[SBGrid Data Bank](https://data.sbgrid.org/)**, the structural biology community's data +publication service (SBGrid Consortium, Harvard Medical School). P. A. Meyer, S. Socias, J. Key, +E. Ransey, E. C. Tjon, A. Buschiazzo et al., "Data publication with the structural biology data grid +supports live analysis" (2016), Nat. Commun. 7, 10882 +[doi:10.1038/ncomms10882](https://doi.org/10.1038/ncomms10882). + +**[Zenodo](https://zenodo.org/)**, CERN's open repository, hosts datasets deposited there directly +by the groups that collected them. European Organization for Nuclear Research and OpenAIRE, +"Zenodo" (2013), CERN [doi:10.25495/7GXK-RD71](https://doi.org/10.25495/7GXK-RD71). The IUCrData +Raw Data Letters describing some of those deposits are cited on the +[EXTERNAL_TEST_DATA](EXTERNAL_TEST_DATA.md) page. + +**[CXIDB](https://cxidb.org/)**, the Coherent X-ray Imaging Data Bank, is the source of the serial +(XFEL stills) datasets. F. R. N. C. Maia, "The Coherent X-ray Imaging Data Bank" (2012), Nat. +Methods 9, 854-855 [doi:10.1038/nmeth.2110](https://doi.org/10.1038/nmeth.2110). + +**[MXRDR](https://mxrdr.icm.edu.pl/)**, the Macromolecular Xtallography Raw Data Repository +(ICM, University of Warsaw), releases its data under CC0 and asks that the DOI of the dataset be +cited. + +**[XRDa](https://xrda.pdbj.org/)**, the Xtal Raw Data Archive (Protein Data Bank Japan), publishes +raw diffraction images and mints a DOI for each, which it asks to be cited. It has no canonical +citation paper. + +**The [ESRF data portal](https://data.esrf.fr/)**, through which the European Synchrotron publishes +raw data under its data policy (CC BY 4.0, with the dataset DOI to be cited). R. Dimper, A. Götz, +A. De Maria, V. A. Solé, M. Chaillet and B. Lebayle, "ESRF Data Policy, Storage, and Services" +(2019), Synchrotron Rad. News 32, 7-12 +[doi:10.1080/08940886.2019.1608119](https://doi.org/10.1080/08940886.2019.1608119). + +**The [Keele University research data repository](https://researchdata.keele.ac.uk/)** and +**[UQ eSpace](https://espace.library.uq.edu.au/)** (The University of Queensland) host the raw +images of datasets deposited there by the groups that collected them; the dataset DOIs are cited on +the [EXTERNAL_TEST_DATA](EXTERNAL_TEST_DATA.md) page. + +**The [Protein Data Bank](https://www.rcsb.org/)** supplies, through the RCSB PDB data API, the +beamline, resolution, space group and unit cell quoted for each dataset, and the deposited +coordinates and structure factors of the public entries the refinement battery starts from. +H. M. Berman, J. Westbrook, Z. Feng, G. Gilliland, T. N. Bhat, H. Weissig, I. N. Shindyalov and +P. E. Bourne, "The Protein Data Bank" (2000), Nucleic Acids Res. 28, 235-242 +[doi:10.1093/nar/28.1.235](https://doi.org/10.1093/nar/28.1.235). + +**The [Crystallography Open Database](https://www.crystallography.net/cod/)** supplies the reference +cells of the small-molecule sets. S. Gražulis, D. Chateigner, R. T. Downs, A. F. T. Yokochi, +M. Quirós, L. Lutterotti, E. Manakova, J. Butkus, P. Moeck and A. Le Bail, "Crystallography Open +Database – an open-access collection of crystal structures" (2009), J. Appl. Cryst. 42, 726-729 +[doi:10.1107/S0021889809016690](https://doi.org/10.1107/S0021889809016690); S. Gražulis, +A. Daškevič, A. Merkys et al., "Crystallography Open Database (COD): an open-access collection of +crystal structures and platform for world-wide collaboration" (2012), Nucleic Acids Res. 40, +D420-D427 [doi:10.1093/nar/gkr900](https://doi.org/10.1093/nar/gkr900). + +**The [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/)** (EMBL-EBI and Google +DeepMind) supplies the start models of the battery's timing benchmark: the predictions of the +deposited entities of 9ZLO (AF-P17090-F1), 9S02 (AF-P32322-F1) and 9GJX (AF-Q65MG6-F1) and, for the +in-house benchmark, of horse myoglobin (AF-P68082-F1) and bovine cytochrome c (AF-P62894-F1), model +version 6, with their predicted aligned error, kept unmodified in `tools/battery/models/` under +CC BY 4.0. J. Jumper, R. Evans, A. Pritzel et al., "Highly accurate protein structure prediction +with AlphaFold" (2021), Nature 596, 583-589 +[doi:10.1038/s41586-021-03819-2](https://doi.org/10.1038/s41586-021-03819-2); M. Varadi, +S. Anyango, M. Deshpande et al., "AlphaFold Protein Structure Database: massively expanding the +structural coverage of protein-sequence space with high-accuracy models" (2022), Nucleic Acids Res. +50, D439-D444 [doi:10.1093/nar/gkab1061](https://doi.org/10.1093/nar/gkab1061); M. Varadi, +D. Bertoni, P. Magana et al., "AlphaFold Protein Structure Database in 2024: providing structure +coverage for over 214 million protein sequences" (2024), Nucleic Acids Res. 52, D368-D375 +[doi:10.1093/nar/gkad1011](https://doi.org/10.1093/nar/gkad1011). The large case of both benchmarks +is the deposited model of PDB entry 4NWV, moved away from its place. + +## Generative AI usage declaration + +Large language models were used extensively in developing this code. Jungfraujoch development was +supported with JetBrains AI (mostly GPT models) to refactor and verify particular code fragments. +Rugnux was developed with the assistance of Claude Code (mostly the Opus model). This documentation +was written with the assistance of Claude Opus and Fable models. diff --git a/_sources/CBOR.md.txt b/_sources/CBOR.md.txt new file mode 100644 index 000000000..4db4e409f --- /dev/null +++ b/_sources/CBOR.md.txt @@ -0,0 +1,397 @@ +# CBOR messages + +To communicate between the FPGA-equipped receiver system and the writers, +Jungfraujoch uses binary CBOR encoding with the tinycbor library (Intel). +The protocol is based on and compatible with [DECTRIS Stream2](https://github.com/dectris/documentation/tree/main/stream_v2). +There are minor differences at the moment: + +* LZ4 alone is not allowed; Bitshuffle+LZ4 and Bitshuffle+Zstandard are allowed +* A few fields are currently absent +* Extra fields are present beyond DECTRIS standard +* There are calibration and metadata messages defined beyond DECTRIS specification + +## Start message + +| Field name | Type | Description | Present in DECTRIS format | +|----------------------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------:| +| type | String | value "start" | X | +| magic_number | uint64 | Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver | | +| detector_distance | float | Detector distance \[m\] | | +| detector_translation | Array(float) | Detector translation vector \[m\] | X | +| beam_center_x | float | Beam center in X direction \[pixels\] | X | +| beam_center_y | float | Beam center in Y direction \[pixels\] | X | +| direct_beam_x | float (optional) | Where the undeflected beam lands on the detector, X \[pixels\]. Not the same point as `beam_center_x`, which is the PONI - the foot of the perpendicular from the sample - and separates from the beam position as soon as the detector is tilted. This is the number a program that asks for "the beam centre" (XDS `ORGX`, for one) wants | | +| direct_beam_y | float (optional) | Where the undeflected beam lands on the detector, Y \[pixels\] (XDS `ORGY`) | | +| countrate_correction_enabled | bool | Countrate correction enabled | X | +| countrate_correction_lookup_table | uint32 array (optional) | Maps a measured count c to its corrected value \[c\], as sent by a DECTRIS detector | X | +| flatfield_enabled | bool | Flatfield enabled | X | +| virtual_pixel_interpolation_enabled | bool (optional) | Virtual pixel interpolation enabled, as reported by a DECTRIS detector | X | +| number_of_images | uint64 | Number of images in the series | X | +| image_size_x | uint64 | Image width \[pixels\] | X | +| image_size_y | uint64 | Image height \[pixels\] | X | +| mirror_y | bool | Whether the assembled image is mirrored in Y relative to the detector's raw readout order. True is the MX convention - row 0 at the top of the detector seen from the sample - and is what absence of the key means | | +| detector_orientation_mirror_y | bool | Whether the assembled image is mirrored in Y relative to the frame the PONI angles are stated in. A different setting from `mirror_y` above, which is about the module layout; this one changes no pixel. Absence means false | | +| detector_orientation_quarter_turns | int | How many multiples of 90 degrees about the beam the assembled image is turned by, relative to the frame the PONI angles are stated in (0-3). Absence means 0 | | +| detector_modules | Array(object) (optional) | Panels: where the image's pixels lie on the detector plane the geometry describes. Each has `x0`, `y0`, `width`, `height` (int, the panel's box in the image) and `ox`, `oy`, `fx`, `fy`, `sx`, `sy` (double, plane pixels): image pixel (x, y) of the panel is at `(ox, oy) + (x - x0) (fx, fy) + (y - y0) (sx, sy)`; `fast_axis`, `slow_axis` (string `Xp`/`Xn`/`Yp`/`Yn`, optional, default `Xp`/`Yp`) say which way the panel's readout axes run in the image, naming it in a module placement. Absent for a flat detector, the image being the plane; spot and reflection positions are always plane coordinates | | +| incident_energy | float | X-ray energy \[eV\] | X | +| incident_wavelength | float | X-ray wavelength \[Angstrom\] | X | +| incident_wavelength_spread | float (optional) | FWHM of the X-ray wavelength distribution \[Angstrom\] (NXmx incident_wavelength_spread); omitted when the beam is monochromatic | | +| beam_size_x | float (optional) | Horizontal size of the X-ray beam at the sample \[m\] (first element of NXmx incident_beam_size) | | +| beam_size_y | float (optional) | Vertical size of the X-ray beam at the sample \[m\] (second element of NXmx incident_beam_size) | | +| frame_time | float | Frame time, if multiple frames per trigger \[s\] | X | +| count_time | float | Exposure time \[s\] | X | +| saturation_value | int64 | Maximum valid sample value | X | +| error_value | int64 (optional) | Value used in images to describe pixels that are in error state or missing | | +| pixel_size_x | float | Pixel width \[m\] | X | +| pixel_size_y | float | Pixel height \[m\] | X | +| sensor_thickness | float | Sensor thickness \[m\] | X | +| sensor_material | string | Sensor material | X | +| arm_date | date | Approximate date of arming | X | +| pixel_mask_enabled | bool | Pixel mask applied on images | X | +| detector_description | string | Name of the detector | X | +| detector_serial_number | string | Detector serial number | X | +| series_unique_id | string | Unique text ID of the series (run_name parameter) | X | +| series_id | uint64 | Unique numeric ID of the series (run_number parameter) | X | +| fluorescence | object (optional) | X-ray fluorescence spectrum collected at start | | +| - energy | Array(float) | Energy of measuring point \[eV\] | | +| - data | Array(float) | Fluorescence scan result `data` \[arbitrary units\]; must be strictly the same length as energy | | +| goniometer | Map | Definition of rotation axis (optional) | X | +| - `AXIS` | string | Rotation axis name (e.g. omega) - only one axis is supported in Jungfraujoch | X | +| - - increment | float | Rotation axis increment (per image) in degree \[deg\] | X | +| - - start | float | Rotation axis start angle \[deg\] | X | +| - - axis | Array(float) | Vector for the rotation axis | | +| - - helical_step | Array(float) | Translation for helical scan for 1 image \[m\] | | +| - - screening_wedge | Array(float) | Wedge for screening \[deg\] (increment would correspond to difference between screening points) | | +| grid_scan | object | Grid scan definition (optional). Send `goniometer` with it, `increment` 0, to state the angle the spindle stood at; without one the spindle is recorded at 0, meaning "nobody said" | | +| - n_fast | uint64 | Number of elements along fast axis | | +| - n_slow | uint64 | Number of elements along slow axis | | +| - step_x_axis | float | Step along X axis, can be negative \[m\] | | +| - step_y_axis | float | Step along Y axis, can be negative \[m\] | | +| - snake_scan | bool | Snake scan (rows alternate direction) | | +| - vertical_scan | bool | Vertical scan (enabled: fast direction = Y, disabled: fast direction = X) | | +| jungfrau_conversion_enabled | bool (optional) | Applying JUNGFRAU pixel conversion (to photons or keV) | | +| jungfrau_conversion_factor | float (optional) | Factor used for JUNGFRAU conversion \[eV\] | | +| geometry_transformation_enabled | bool (optional) | Transformation from detector module geometry (512x1024) to full detector geometry | | +| pixel_mask | Map(string -> Image) | Pixel mask - multiple in case of storage cells | X | +| channels | Array(string) | List of image channels | X | +| max_spot_count | uint64 | Maximum number of spots identified in spot finding | | +| max_extra_lattices | uint64 | Maximum number of extra lattices | | +| storage_cell_number | uint64 (optional) | Number of storage cells used by JUNGFRAU | | +| storage_cell_delay | Rational | Delay of storage cells in JUNGFRAU | | +| threshold_energy | Map(string -> float) | Per-channel threshold energy \[eV\] (map of channel name to value) | | +| image_dtype | string | Pixel type of the image data: `uint8`, `uint16`, `uint32` (DECTRIS), plus `int8`, `int16`, `int32` as a Jungfraujoch extension. Sole wire encoding of both the bit depth and the sign, and must agree with the per-image typed-array tag | X | +| unit_cell | object (optional) | Unit cell of the system: a, b, c \[angstrom\] and alpha, beta, gamma \[degree\] | | +| az_int_q_bin_count | uint64 | Number of azimuthal integration bins in the radial direction | | +| az_int_phi_bin_count | uint64 | Number of azimuthal integration bins in the phi angle direction | | +| az_int_bin_to_q | Array(float) | Q value for each azimuthal integration bin \[angstrom^-1\] | | +| az_int_bin_to_two_theta | Array(float) | Two theta angle value for each azimuthal integration bin \[deg\] | | +| az_int_bin_to_phi | Array(float) | Phi value for each azimuthal integration bin \[deg\] | | +| az_int_map | Image | Mapping between pixel and bin number | | +| summation | uint64 | Factor of frame summation | | +| user_data | string | JSON serialized to string that can contain the following fields (all fields are optional): | X | +| - file_prefix | string | File prefix | | +| - images_per_file | uint64 | Number of images written per file | | +| - images_per_trigger | uint64 | Number of images collected per trigger | | +| - source_name | string | Facility name | | +| - source_type | string | Type of X-ray source (use NXsource/type values, for example "Synchrotron X-ray Source" or "Free-Electron Laser") | | +| - instrument_name | string | Instrument name | | +| - sample_name | string | Name of the sample | | +| - user | any valid JSON | Value of header_appendix provided at collection start to Jungfraujoch | | +| - attenuator_transmission | float | Attenuator transmission \[\] | | +| - total_flux | float | Total flux \[ph/s\] | | +| - space_group_number | uint64 | Space group number | | +| - summation_mode | string | Summation mode (internal\|fpga\|cpu) | | +| - overwrite | bool | Overwrite existing HDF5 files | | +| - file_format | int | File writer format: 0 = only data files, 1 = NXmx legacy external links, 2 = NXmx VDS, 3 = NXmx integrated, 4 = CBF (retired; rejected), 5 = TIFF (retired; rejected), 6 = no file written | | +| - roi | Array(object) | ROI configurations; each has a `name` (the key of its `roi_integrals` entry and of `/entry/roi/` in HDF5) and is one of: | | +| | | type "box": xmin, xmax, ymin, ymax (numbers) | | +| | | type "circle": r, x, y (numbers) | | +| | | type "azim": qmin, qmax (numbers); optional phi_min, phi_max (numbers, deg) for an angular sector | | +| - gain_file_names | Array(string) | Names of JUNGFRAU gain files used for the current detector | | +| - write_master_file | bool | With multiple sockets, it selects which socket will provide master file | | +| - write_images | bool | Write images in the HDF5 file (if false, will only write metadata) | | +| - data_reduction_factor_serialmx | uint64 | Data reduction factor for serial MX | | +| - experiment_group | string | ID of instrument user, e.g., p-group (SLS/SwissFEL) or proposal number | | +| - jfjoch_release | string | Jungfraujoch release number | | +| - socket_number | uint64 | Number of ZeroMQ socket (on `jfjoch_broker` side) used for transmission | | +| - bit_depth_readout | uint64 | Bit depth of the **stored image** (see note below), copied to NXmx `bit_depth_readout` | | +| - underload_value | int64 | Lowest valid value; copied to NXmx `underload_value`. `0` for an unsigned image, `INTx_MIN + 1` for a signed one | | +| - writer_notification_zmq_addr | string | ZeroMQ address to inform `jfjoch_broker` about writers that finished operation | | +| - xfel_pulse_id | uint64 | Pulse IDs are recorded for images | | +| - ring_current_mA | float | Ring current at the start of the measurement | | +| - sample_temperature_K | float | Sample temperature \[K\] | | +| - detect_ice_rings | bool | Ice ring detection feature is enabled; absent where the dataset settings left it unset (rugnux then decides) | | +| - indexing_algorithm | string | Indexing algorithm used on-the-fly; allowed values: ffbidx, fft, fftw, none | | +| - geom_refinement_algorithm | string | Post-indexing detector geometry refinement algorithm; allowed values: none, beam_center | | +| - poni_rot1 | float | Tilt of the detector rot1 according to PyFAI PONI convention \[rad\] | | +| - poni_rot2 | float | Tilt of the detector rot2 according to PyFAI PONI convention \[rad\] | | +| - poni_rot3 | float | Tilt of the detector rot3 according to PyFAI PONI convention \[rad\] | | +| - smargon | object | Smargon head position, where one was given: `chi_deg`, `phi_deg` and the `chi_axis`, `phi_axis` vectors | | +| roi_map | Image | ROI bitmask per pixel (uint16, bit n = pixel belongs to ROI n); present when ROIs are defined | | + +See [DECTRIS documentation](https://github.com/dectris/documentation/tree/main/stream_v2) for definition of Image as MultiDimArray with optional compression. + +## Image message + +Every scalar of the image message is optional: a quantity that was not computed for the image is absent from the map, whatever the column below says. `spots[].panel`, `az_int_profile_std`, `indexing_extra_lattices` and `roi_integrals` are likewise present only where there is something to report; the reflection fields `qe` and `flight` are always written. + +| Field name | Type | Description | Present in DECTRIS format | Optional | +|-----------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------|:-------------------------:|:--------:| +| type | String | value "image" | X | | +| magic_number | uint64 | Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver | | | +| series_unique_id | string | Unique text ID of the series (run_name parameter) | X | | +| series_id | uint64 | Unique numeric ID of the series (run_number parameter) | X | | +| image_id | uint64 | Number of image within the series; for MX lossy compression this is sequential excluding removed frames | X | | +| original_image_id | uint64 | Number of image within the series; for MX lossy compression this includes removed frames in the count | | | +| real_time | Rational | Exposure time | X | | +| start_time | Rational | Exposure start time (highly approximate) | X | | +| end_time | Rational | Exposure end time (highly approximate) | X | | +| spots | Array(object) | Spots: | | | +| - x | float | observed position in x (pixels) | | | +| - y | float | observed position in y (pixels) | | | +| - I | float | intensity (photons) | | | +| - maxc | int64 | max count (photons) | | | +| - ice_ring | bool | spot in resolution range for ice rings | | | +| - indexed | bool | indexed solution | | | +| - latt | int64 | Lattice to which the peak belongs (negative number = not indexed) | | | +| - image | int64 | image number the spot belongs to | | | +| - panel | int64 (optional) | panel (index into `detector_modules`) the spot was found on; absent for a detector without a panel table | | | +| - h | int64 | Miller index (indexed spots only) | | | +| - k | int64 | Miller index (indexed spots only) | | | +| - l | int64 | Miller index (indexed spots only) | | | +| - dist_ewald | float | distance to Ewald sphere \[Angstrom^-1\] (indexed spots only) | | | +| reflections | Array(object) | Reflections: | | | +| - h | int64 | Miller index | | | +| - k | int64 | Miller index | | | +| - l | int64 | Miller index | | | +| - x | float | predicted position in x (pixels) | | | +| - y | float | predicted position in y (pixels) | | | +| - obs_x | float | observed position in x (pixels) | | | +| - obs_y | float | observed position in y (pixels) | | | +| - d | float | resolution \[Angstrom\] | | | +| - I | float | integrated intensity (photons) | | | +| - bkg | float | mean background value (photons) | | | +| - var_bkg | float | non-signal (background) part of sigma^2, carried to the merge (photons^2) | | | +| - sigma | float | standard deviation, estimated from counting statistics (photons) | | | +| - image | int64 | image number the reflection belongs to | | | +| - rp | float | Distance to Ewald sphere \[Angstrom^-1\] | | | +| - rlp | float | Reciprocal Lorentz-polarization factor: the multiplier taking the raw integrated count toward a quantity proportional to \|F\|^2. Lorentz x polarization only - a still has no Lorentz term, so there it is the polarization alone | | | +| - qe | float | Sensor efficiency at the reflection's angle of incidence, QE(0)/QE(alpha); <= 1, and 1 where the sensor is opaque or unknown. Carried beside `rlp`, not inside it: the total correction is `rlp * qe`. Optional | | | +| - flight | float | Attenuation of the reflection in the flight path between the sample and its pixel, normalised to normal incidence; >= 1, and exactly 1 for a vacuum path. Carried beside `rlp` and `qe`: the total correction is `rlp * qe * flight`. Optional | | | +| - partiality | float | Partiality of the reflection | | | +| - phi | float | phi angle from XDS: difference from middle of current frame, not absolute \[deg\] | | | +| - zeta | float | Lorentz zeta factor (reciprocal-space geometry term) | | | +| - image_scale_corr | float | Per-image scale correction; I_true = image_scale_corr * I | | | +| spot_count | uint64 | Spot count | | | +| spot_count_ice_rings | uint64 | Number of spots within identified rings (experimental) | | | +| spot_count_low_res | uint64 | Number of spots in low resolution (prior to filtering) | | | +| spot_count_indexed | uint64 | Number of spots which fit indexing solution within a given tolerance | | | +| az_int_profile | Array(float) | Azimuthal integration results, use az_int_bin_to_q from start message for legend | | | +| | | NaN is used for empty bins and has to be taken care by the receiver | | | +| az_int_profile_std | Array(float) | Standard deviation for azimuthal integration. (NaN for less than 2 samples) | | | +| az_int_profile_count | Array(uint64) | Number of pixels contributing to azimuthal bin | | | +| indexing_result | bool | Indexing successful | | | +| indexing_lattice_count | int64 | Number of indexing lattices found for this image | | | +| indexing_lattice | Array(9 * float) | Indexing result real lattice; present only if indexed | | X | +| indexing_extra_lattices | Array(Array(9*float)) | Additional indexed lattices (orientation variants); present only if found | | | +| indexing_unit_cell | object | Indexing result unit cell: a, b, c \[angstrom\] and alpha, beta, gamma \[degree\]; present only if indexed | | X | +| | | Unit cell is redundant to lattice - yet to simplify downstream programs to analyze results, both are provided | | | +| profile_radius | float | Profile radius of the image - describes distance of observed reflections from the Ewald sphere \[Angstrom^-1\] | | | +| integrated_reflections | int64 | Count of integrated reflections | | | +| mosaicity | float | Angular range of spots in image from a rotation scan \[degree\] | | | +| b_factor | float | Estimated B-factor (Angstrom^2) | | | +| compression_time | float | Time spent on compression/decompressing image \[s\] | | | +| preprocessing_time | float | Time spent on preparing the image for analysis \[s\] | | | +| azint_time | float | Time spent on azimuthal integration \[s\] | | | +| spot_finding_time | float | Time spent on spot finding \[s\] | | | +| indexing_time | float | Time spent on indexing \[s\] | | | +| refinement_time | float | Time spent on refinement of indexing solution and experimental geometry \[s\] | | | +| index_analysis_time | float | Time spent on analyzing indexing solution, calculating profile radius and mosaicity \[s\] | | | +| bragg_prediction_time | float | Time spent on predicting Bragg spots \[s\] | | | +| integration_time | float | Time spent on Bragg integration \[s\] | | | +| image_scale_time | float | Time spent on on-the-fly scaling \[s\] | | | +| processing_time | float | Total processing time \[s\] | | | +| xfel_pulse_id | uint64 | Bunch ID (for pulsed source, e.g., SwissFEL) | | X | +| xfel_event_code | uint64 | Event code (for pulsed source, e.g., SwissFEL) | | X | +| lattice_type | object | Bravais lattice classification of the indexing result (present only if available) | | X | +| - centering | string | One-letter centering code: P, A, B, C, I, F, or R | | | +| - niggli_class | int64 | Integer identifier for the Niggli-reduced Bravais class | | | +| - system | string | Crystal system: triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, cubic | | | +| jf_info | uint64 | Detector info field | | | +| receiver_aq_dev_delay | uint64 | Receiver internal delay | | | +| receiver_free_send_buf | uint64 | Receiver internal number of available buffer locations | | | +| receiver_buf_in_sending | uint64 | Receiver internal number of buffer locations currently in sending/writing | | | +| receiver_buf_in_preparation | uint64 | Receiver internal number of buffer locations currently in processing | | | +| storage_cell | uint64 | Storage cell number | | | +| saturated_pixel_count | uint64 | Saturated pixel count | | | +| pixel_sum | int64 | Sum of pixels, excl. device-masked, error and saturated (negative values included) | | | +| error_pixel_count | uint64 | Error pixel count | | | +| strong_pixel_count | uint64 | Strong pixel count (first stage of spot finding) | | | +| min_viable_pixel_value | int64 | Minimal pixel value, excl. error and saturation | | | +| max_viable_pixel_value | int64 | Maximal pixel value, excl. error and saturation | | | +| resolution_estimate | float | Resolution the merged data are predicted to reach, from this image's spots alone \[Angstrom\] | | X | +| data_collection_efficiency | float | Image collection efficiency \[\] | | | +| packets_expected | uint64 | Number of packets expected per image (in units of 2 kB) | | | +| packets_received | uint64 | Number of packets received per image (in units of 2 kB) | | | +| bkg_estimate | float | Mean value for pixels in resolution range from 3.0 to 5.0 A \[photons\] | | | +| ice_ring_score | float | Strongest hexagonal-ice ring intensity over the smooth radial background (1 = no ice) | | | +| spindle_blind_fraction | float | Fraction (0-1) of a rotation sweep's blind cone this orientation makes unrecoverable, as a lone-2-fold worst-case bound; >= 0.5 should engage a recovery protocol, and ABSENT means the frame could not be assessed, which automation must treat the same way | | | +| spot_count_ice_control | float | Spots in the ice-free flanks beside the hexagonal rings, rescaled to the ring bands' own q width (control for spot_count_ice_rings) | | | +| beam_corr_x | float | Beam center correction X applied during processing \[pixel\] | | X | +| beam_corr_y | float | Beam center correction Y applied during processing \[pixel\] | | X | +| image_scale_factor | float | Scaling result: Image scale factor (g) | | X | +| image_scale_mosaicity | float | Scaling result: Image scale mosaicity \[deg\] | | X | +| image_scale_cc | float | Scaling result: Image scale CC | | X | +| adu_histogram | Array(uint64) | ADU histogram | | | +| roi_integrals | Map(string -> object) | Results of ROI calculation, one entry per ROI keyed by its name | | X | +| - sum | int64 | Sum of pixels in ROI area \[photons\] | | | +| - sum_square | int64 | Sum of squares of pixels in ROI area \[photons\] | | | +| - pixels | uint64 | Valid pixels in ROI area | | | +| - max_count | int64 | Highest count in ROI area \[photons\] | | | +| - x_weighted_sum | int64 | ROI pixel X position multiplied by photon count \[photons * pixels\] | | | +| - y_weighted_sum | int64 | ROI pixel Y position multiplied by photon count \[photons * pixels\] | | | +| user_data | string | Optional user defined text information - this is image_appendix serialized to JSON format | X | | +| data | Map(string -> Image) | Image | X | | + +## Metadata message + +| Field name | Type | Description | Present in DECTRIS format | Optional | +|------------------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------|:-------------------------:|:--------:| +| type | String | value "metadata" | X | | +| magic_number | uint64 | Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver | | | +| series_unique_id | string | Unique text ID of the series (run_name parameter) | X | | +| series_id | uint64 | Unique numeric ID of the series (run_number parameter) | X | | +| images | Array(object) | Array of images (order and size of the array are not guaranteed) | X | | +| - ... | | Every field of the [image message](#image-message) except `spots`, `reflections` and `data` (the image itself), with the same names, types and optionality | | | + +## End message + +| Field name | Type | Description | Present in DECTRIS format | +|----------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------|:-------------------------:| +| type | String | value "end" | X | +| magic_number | uint64 | Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver | | +| series_unique_id | string | Unique text ID of the series (run_name parameter) | X | +| series_id | uint64 | Unique numeric ID of the series (run_number parameter) | X | +| end_date | string | Approximate end date | | +| max_image_number | uint64 | Number of image with the highest number; counted from 1 to distinguish zero images and one image | | +| transformations | Array(object) (optional) | Sample transformation chain in mounting order, base first. Each element mirrors a NeXus NXtransformations axis: `name`, `transformation_type` (`rotation`/`translation`), `units`, `vector`, `offset`, `depends_on` (the axis this one is mounted on, empty for the base), optional `equipment` and `equipment_component` (NXtransformations attributes; `equipment_component` is `smargon` on a head's `chi`/`phi`, which is how a reader tells them from the spindle), and `values` - a single number for an axis that does not move, otherwise one per image. An ARRAY because the order matters and a CBOR map has none. Optional: when absent the writer builds the same chain from the start message. It is in the END message because a producer may want to report positions that were **measured** rather than commanded, which are only known once the run is over | | +| images_collected | uint64 | Number of images collected | | +| images_sent_to_write | uint64 | Number of images sent to writer; if writer queues were full, it is possible this is less than images collected | | +| data_collection_efficiency | float | Overall network packets collected / network packets expected | | +| az_int_result | Map(text->Array(float)) | Azimuthal integration results, use az_int_bin_to_q from start message for legend | | +| adu_histogram | Map(text->Array(uint64)) | ADU values histogram | | +| adu_histogram_bin_width | uint64 | Width of bins in the above histogram \[ADU\] | | +| max_receiver_delay | uint64 | Internal performance of Jungfraujoch | | +| bkg_estimate | float | Mean background estimate for the whole run | | +| refined_beam_center_x | float | Beam centre X the frames were analysed at, where the analysis refined it \[pixel\] | | +| refined_beam_center_y | float | Beam centre Y the frames were analysed at, where the analysis refined it \[pixel\] | | +| refined_detector_distance_mm | float | Detector distance the frames were analysed at, where the analysis refined it \[mm\] | | +| spindle_blind_fraction | float | Run mean of the per-image spindle_blind_fraction, over the frames that had one | | +| spindle_lost_unique_fraction | float | Fraction (0-1) of unique reflections the mounting made unmeasurable, exact under the measured point group; offline (Rugnux) only | | +| indexing_rate | float | Mean indexing rate for the whole run | | +| unit_cell | object (optional) | Unit cell of the system, based on the actual experiment: a, b, c \[angstrom\] and alpha, beta, gamma \[degree\] | | +| unit_cell_esd | object (optional) | e.s.d.s of `unit_cell`, same layout: a, b, c \[angstrom\] and alpha, beta, gamma \[degree\]; rotation, offline (Rugnux) and in-broker analysis only | | +| space_group_name | string (optional) | The space group determined by the analysis, gemmi extended Hermann-Mauguin (carries the setting; what a reader should take) | | +| space_group_number | uint64 (optional) | Its International Tables number, beside the name for a reader written before the name existed | | +| rotation_lattice_type | object | Bravais lattice classification of the total rotation solution over the run, if available; same schema as `lattice_type` | | +| - centering | string | One-letter centering code: P, A, B, C, I, F, or R | | +| - niggli_class | int64 | Integer identifier for the Niggli-reduced Bravais class | | +| - system | string | Crystal system: triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, cubic | | +| rotation_lattice | Array(9 * float) | Real-space lattice basis, flattened 3x3 in row-major order | | +| rotation_extra_lattices | Array(Array(9*float)) | Additional indexed lattices (orientation variants); present only if found | | +| data_collection_efficiency_image | Array(float) | Per-image data collection efficiency. Missing values are encoded as 0 or 1 depending on producer context | | +| spot_count | Array(int32) | Per-image spot count | | +| spot_count_ice_ring | Array(int32) | Per-image number of spots within identified ice-ring resolution ranges | key is singular here; the per-image message uses `spot_count_ice_rings` | +| spot_count_low_res | Array(int32) | Per-image number of low-resolution spots | | +| spot_count_indexed | Array(int32) | Per-image number of spots fitting indexing solution | | +| image_indexed | Array(uint8) | Per-image indexing result; 0 = not indexed, nonzero = indexed | | +| v_bkg_estimate | Array(float) | Per-image background estimate | | +| v_spindle_blind_fraction | Array(float) | Per-image spindle_blind_fraction; NaN where the frame had no value (which is "cannot say", not zero) | | +| ice_ring_score | Array(float) | Per-image strongest ice-ring intensity over the smooth radial background (1 = no ice) | | +| spot_count_ice_control | Array(float) | Per-image spot count in the ice-free flanks beside the hexagonal rings, rescaled to the ring bands' q width | | +| ice_ring_score_mean | float | Mean ice-ring score for the whole run (1 = no ice) | | +| profile_radius | Array(float) | Per-image profile radius \[Angstrom^-1\] | | +| mosaicity | Array(float) | Per-image mosaicity \[degree\] | | +| bFactor | Array(float) | Per-image estimated B-factor \[Angstrom^2\] | | +| resolution_estimate | Array(float) | Per-image predicted merged resolution, from spots alone \[Angstrom\] | | +| min_viable_pixel_value | Array(int64) | Per-image minimum valid pixel value, excluding error/saturated pixels | | +| max_viable_pixel_value | Array(int64) | Per-image maximum valid pixel value, excluding error/saturated pixels | | +| saturated_pixel_count | Array(int32) | Per-image saturated pixel count | | +| error_pixel_count | Array(int32) | Per-image error pixel count | | +| image_scale_factor | Array(float) | Per-image scale factor, if scaling/merging was performed | | +| integrated_reflections | Array(int32) | Per-image count of integrated reflections | | +| indexed_lattice_count | Array(int32) | Per-image count of indexed lattices | | +| niggli_class | Array(uint8) | Per-image Niggli class identifier for indexed images; 0 if unavailable | | +| pixel_sum | Array(int64) | Per-image sum of pixels, excl. device-masked, error and saturated (0 for an image with no analysis) | | +| image_scale_mosaicity | Array(float) | Scaling result: Image scale mosaicity \[deg\] | | +| image_scale_cc | Array(float) | Scaling result: Image scale CC | | +| merged | object (optional) | Merged reflections of an in-broker analysis run, written by the writer as `.mtz`. An MTZ table (layout below) | | +| map_coefficients | object (optional) | Map coefficients of an in-broker analysis run, written as `_maps.mtz`. An MTZ table (layout below) | | +| placed_model | object (optional) | Atomic model placed against the data, written as `_model.cif` and `_model.pdb`. `name` (string), `unit_cell` (object, as above), `space_group_name` (the data's, gemmi extended H-M), `model_space_group_name` (the coordinates'), then one array per atom: `model_number`, `seq_num`, `charge` (int32), `chain`, `residue_name`, `atom_name`, `element` (Array(string)), `icode` (uint8, space where none), `het_flag` (uint8, `A`, `H` or 0 where unknown), `altloc` (uint8, 0 where none), `x`, `y`, `z` (double, Angstrom), `b_iso`, `occupancy` (float), `aniso` (float, 6 per atom: U11 U22 U33 U12 U13 U23; empty where no atom has one), `subchain`, `entity_id` (Array(string), mmCIF label_asym_id / label_entity_id), `label_seq` (int32, label_seq_id, INT32_MIN where none) - these three optional; `metadata_mmcif` (gzipped string, optional, see [Notes on gzipped text](#notes-on-gzipped-text)): the input model's metadata (entities, sequences, references, authors, software, secondary structure) as mmCIF categories without coordinates, parsed by the writer with gemmi | | +| refined_model | object (optional) | The placed model after refinement, written as `_refined_model.cif` and `_refined_model.pdb`; same layout as `placed_model` | | +| refined_map_coefficients | object (optional) | Map coefficients of the refined model, written as `_refined_maps.mtz`. An MTZ table (layout below) | | +| blobs | object (optional) | Unexplained blobs of the refined model's mFo-DFc map, strongest first, written as `_blobs.json`. One array per field, one entry per blob: `kind` (Array(string): `WATER`, `ION`, `LIGAND`, `MODEL_ERROR`, `UNASSIGNED`), `x`, `y`, `z` (double, centroid, Angstrom), `peak_sigma` (double, map rms), `volume` (double, Angstrom^3), `score` (double, sigma Angstrom^3), `nearest_atom` (Array(string)), `nearest_atom_distance` (double, Angstrom), `polar_contacts`, `metal_contacts` (int32), `anomalous_sigma` (double, 0 where there is no anomalous map) | | +| report | gzipped string (optional) | The in-broker analysis run's results report, written as `_report.txt`: the text `rugnux` writes as its own `_report.txt` (see [RUGNUX_REPORT](RUGNUX_REPORT.md)) | | + +End-message vector fields are optional. When present, they provide master-file summary data so readers can inspect scan-level and per-image analysis results without opening every linked data file. Missing optional per-image values are encoded by the producer as zero unless otherwise noted. + +An MTZ table (`merged`, `map_coefficients`, `refined_map_coefficients`) carries an MTZ file's content as the writer writes it, column by column: + +| Field name | Type | Description | +|------------------|---------------|------------------------------------------------------------------------------------------------------| +| title | string | MTZ title | +| unit_cell | object | a, b, c \[angstrom\] and alpha, beta, gamma \[degree\] | +| space_group_name | string | Space group, gemmi extended Hermann-Mauguin (keeps the setting) | +| history | Array(string) | MTZ HISTORY records | +| sort_order | Array(int32) | MTZ sort order, 5 entries | +| datasets | Array(object) | One per MTZ dataset: `project_name`, `crystal_name`, `dataset_name` (string), `wavelength` (float, Angstrom; 0 = not set) | +| columns | Array(object) | One per MTZ column: `label` (string), `type` (string, one character: the MTZ column type H, J, F, Q, I, ...), `dataset_id` (int), `values` (float typed array, one per row) | +| batches | Array(object) | One per image of unmerged data (empty for merged data): `number` (int), `title` (string), `ints` (int32), `floats` (float) - the MTZ batch header arrays - and `axes` (Array(string), goniostat axis names) | + +## Calibration message + +| Field name | Type | Description | Present in DECTRIS format | +|--------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------|:-------------------------:| +| type | String | value "calibration" | | +| magic_number | uint64 | Number used to describe version of the Jungfraujoch data interface - to allow to detect inconsistency between sender and receiver | | +| data | Map(string -> Image) | Calibration map (only single pedestal array per message) | | + +## User data +Facilities often need to forward more metadata than Jungfraujoch models explicitly. +For this reason two fields can be provided: `header_appendix` (sent with the start message) and `image_appendix` (sent with the image message). +To increase flexibility, both appendices can contain any valid JSON message. +These appendices are serialized into string and stored in CBOR messages as `user_data`. + +Notably for start message, `user_data` carries more information (non-DECTRIS compliant metadata, the fields listed above). +It is still a JSON text string; its member `user` holds the `header_appendix` defined in OpenAPI of Jungfraujoch. + +### Notes on images and compression + +- Images are encoded as DECTRIS MultiDimArray with typed array tags: + - For RGB: shape \[3, height, width\], type: u8 + - For grayscale: shape \[height, width\], type according to bit depth and sign (e.g., uint16 LE) +- Compression: + - Uncompressed: raw CBOR byte string + - Bitshuffle+LZ4: tag with \["bslz4", elem_size, bytes\] + - Bitshuffle+Zstandard: tag with \["bszstd", elem_size, bytes\]. The `BSHUF_ZSTD`, `BSHUF_ZSTD_RLE` and `BSHUF_ZSTD_RLE_HUFF` algorithms all travel under this tag, and a receiver decodes the tag as plain `BSHUF_ZSTD`. + - The start message's `pixel_mask`, `az_int_map` and `roi_map` are always Bitshuffle+LZ4. + +### Notes on gzipped text + +The long texts of the END message - `report` and the `metadata_mmcif` of `placed_model` and `refined_model` - are +sent gzipped (RFC 1952), under the same tag as compressed images: tag 56500 with \["gzip", 1, bytes\], `bytes` +being one gzip stream of the UTF-8 text. A reader that knows the tag also accepts a plain text string there. A +reader that does not know it finds a tag where it expects a text string and refuses the END message, rather than +writing the files without the text. + +### Notes on typed arrays + +Jungfraujoch uses RFC 8746-style typed byte-string tags for compact numeric arrays. + +Common tags used in this protocol include: + +- float32 little-endian arrays for `Array(float)` +- uint8 arrays for compact boolean/integer flags such as `image_indexed` +- int32 little-endian arrays for per-image counts +- int64 little-endian arrays for large per-image integer values +- uint64 little-endian arrays for histograms \ No newline at end of file diff --git a/_sources/CHANGELOG.md.txt b/_sources/CHANGELOG.md.txt new file mode 100644 index 000000000..ba8bae5e2 --- /dev/null +++ b/_sources/CHANGELOG.md.txt @@ -0,0 +1,1462 @@ +# Changelog +## 1.0.0 + +### 1.0.0-rc.186 + +* jfjoch_broker (experimental): Live Rugnux covers serial collections from DECTRIS detectors; a rotation collection too large for the image buffer falls back to standard per-image processing with a warning, and a stream that ends without its end message finishes the collection instead of hanging it. +* jfjoch_broker (experimental): Live Rugnux settings to build the solvent during refinement and to process a rotation collection as stills, a Clear action for the last result, a `_report.txt` for live rotation runs, R-free reported for the refined model, and ice-ring detection on by default for rotation as in the command line. +* jfjoch_broker (experimental): More complete and reproducible live serial merges, analysed for twinning, pseudo-translation and anisotropy, with merging statistics by resolution shell in the live status. +* jfjoch_writer: Live results with large models are written reliably; update jfjoch_writer together with jfjoch_broker (the data interface release is now 7, a mismatched writer refuses the run at its start). +* Rugnux: Several masters can be processed together with `--force-still`, including grid scans; more robust and faster merging of several sweeps; improved twinning, pseudo-translation, anisotropy, anomalous-signal and space-group decisions. +* Rugnux: Molecular replacement places the copies of a multi-copy solution together; the pseudo-translation warning quotes the Patterson peak and is not raised once a model is placed; the report advises on extending the rotation or reorienting the crystal where the coverage would gain from it. +* Web frontend: Light and dark modes, a phone layout, a hideable page list, a redesigned Rugnux live page with step-through of the Fo-Fc peaks in the structure view. +* jfjoch_viewer: A broker URL given on the command line follows the running collection. + +### 1.0.0-rc.185 + +* jfjoch_broker: The master file records the unit cell given for the collection, not the mean of the per-image refined cells; the redundant `input_unit_cell` is no longer written. + +### 1.0.0-rc.184 + +* Rugnux: Rotation processing recovers most of the speed lost since 1.0.0-rc.180; live processing in jfjoch_broker finishes sooner. +* Rugnux: More reliable rotation processing and indexing, including small molecules and supercells. +* Rugnux: More robust serial data and model refinement; molecular replacement handles multi-chain models. +* jfjoch_broker (experimental): Live serial processing keeps the detector geometry fixed for the whole run. +* jfjoch_broker: Pixel sum without an FPGA, a mask bit for inactive pixels, and several stability fixes. +* jfjoch_broker: Rotation indexing and quick integration moved to rugnux live mode; their API settings are deprecated and ignored. +* jfjoch_broker, Rugnux: Azimuthal integration can use logarithmic (log10) Q bins or a given number of bins, set from the API, the web interface and the Rugnux command line. +* jfjoch_viewer: Build and display fixes; the README is rewritten. + +### 1.0.0-rc.183 + +* jfjoch_broker (experimental): Serial data are merged live, with intermediate results during the collection. +* Rugnux: More robust processing of serial data, including CCD detectors. +* Rugnux: Parts of a rotation sweep that spoil the merge are removed automatically. +* Rugnux: Clearer maps, and anomalous peaks not explained by the model are reported. +* Rugnux: SHELX files work with SHELXL; XFEL pulse IDs are kept in `_process.h5`. +* Web frontend: Spot-finding settings change only when the user changes them. +* Rugnux: Faster processing. + +### 1.0.0-rc.182 + +* Rugnux: Fixed indexing of stills of a centred lattice with a known cell. +* jfjoch_broker (experimental): Live Rugnux processing of serial collections. +* Rugnux: Stills detector modules are placed from the data and written to `_module_placement.json`; `--panel-refine` replaces `--refine-modules`. +* Rugnux: More reliable rotation processing - indexing, monoclinic setting, space-group choice and refinement of multi-domain twins. + +### 1.0.0-rc.181 + +* Rugnux: Several rotation sweeps of one crystal are merged as one dataset (`rugnux a_master.h5 b_master.h5`), on a common indexing and cell, with a non-isomorphous sweep left out and reported; `--sweeps separate` processes each sweep on its own. Bruker `.sfrm` frames and imgCIF files with a full goniometer axis chain are read. +* Rugnux: More robust rotation processing - a retry with a more sensitive spot finder when no lattice is found, a self-consistent detector distance, long axes and doubled cells tested as hypotheses, a `-C` supercell multiple stepped down, and each ice ring merged, down-weighted or rejected on its own. +* Rugnux: Serial stills are merged with a partiality-aware error model, reported as `ERROR_MODEL_A/B/C` with no ISa or R_merge/R_meas/R_pim; runs without `-S` have an overall intensity scale about 0.86-0.88 times that of earlier versions, with unchanged statistics. A second crystal form is left out of the merge and reported, the indexing ambiguity is resolved more reliably, and `--model` no longer influences processing. +* Rugnux: The reported CC1/2 is the standard unweighted one, which can be lower than before on sweeps with weak frames; ISa comes with a 95% interval (`ISA_LOW`/`ISA_HIGH`). +* Rugnux: Model refinement adds anisotropic/TLS, local NCS and twin refinement where R-free supports them; building waters and relabelling ions is now off by default (`--refine-solvent` turns it on). +* NXmx: A detector of several modules is written as `module_0` ... `module_N` only, so DIALS reads each module as its own panel. +* Other: JPEG previews use a bundled encoder (libjpeg-turbo no longer needed), Rugnux prints how to cite it, and the release archives contain the HTML documentation. + +### 1.0.0-rc.180 + +* Rugnux: A placed model is refined by default - restrained maximum-likelihood refinement on the GPU (CPU without one), writing `_refined_model.cif`, `_refined_maps.mtz` and the difference-map blobs in `_blobs.json`; `--no-refine` skips it. +* Rugnux: `--mode refine` refines a model against merged structure factors from an MTZ or mmCIF file. +* Rugnux: The embedded restraint dictionary covers amino acids, nucleotides including common modified RNA nucleotides, common cofactors, crystallisation additives, waters and ions, with metal sites restrained from the model's LINK records. +* Rugnux: A model or reference file can be given among the inputs in any order, recognised by its contents. +* Rugnux: The geometry refinement algorithm option is now `-r, --geom-refine` (was `--refine`). +* Rugnux: Serial stills resolve the indexing ambiguity from the data when no model or reference is given, reject merge outliers by default, follow the run's measured rocking curve in prediction and partiality (also in `--mode scale`), and index reproducibly on the GPU. +* Rugnux: Reflections touching the beam-stop shadow are not integrated, reflections coarser than the low-resolution limit are merged and written (but kept out of the scale fit), and the polarisation plane is measured more reliably. +* Rugnux: Small-molecule runs report unit-cell e.s.d.s, in a SHELX `.ins` beside the `.hkl` and in the mmCIF. +* jfjoch_broker: Live Rugnux refines the uploaded model after placement; the web frontend's Rugnux live page has a hero panel with resolution, ISa, space group, placement and refined R-work/R-free, and its Mol* viewer shows the refined model and maps. +* Documentation: A new front page with download pages for Rugnux and the viewer, and the technical reference reorganised below it. +* Build: The fast-feedback indexer is part of the source tree instead of being downloaded at build time. + +### 1.0.0-rc.179 + +* Rugnux: Stills processing needs only the unit cell and space group beyond what the file records - detector distance, beam centre, tilt, panel placement, saturation level, gain and polarisation plane are found from the images - and is up to twice as fast. +* Rugnux: Stills can be indexed without a GPU, with a CPU implementation of the fast-feedback indexer (macOS, computers without a GPU). +* Rugnux: Rotation and stills data are integrated in the detector's own units with one gain model, improving data from CCD detectors. +* Web frontend: The Rugnux live page shows the placed model with its electron density and anomalous difference map in a Mol* viewer. + +### 1.0.0-rc.178 + +* Rugnux: Processes serial crystallography data from XFELs - SACLA (MPCCD), PAL-XFEL and European XFEL (CXI), LCLS (XTC) and SwissFEL Alvra (JUNGFRAU with a CrystFEL module geometry) - with several files or Jungfraujoch master files merged in one run (`rugnux *_master.h5`). +* Rugnux: Stills processing takes a known unit cell and space group as a starting point, finds the beam centre (and, with a cell, the detector distance) from the images, detects the saturation level in other facilities' files and refines the placement of individual detector panels. +* Rugnux: The stills report gives R_split and CC1/2 from frame half-sets, comparable with CrystFEL. +* jfjoch_viewer: Opens the same XFEL file formats. +* Validation: A stills battery checks Rugnux against deposited structures from SACLA, PAL-XFEL, LCLS, European XFEL and SwissFEL. +* Rugnux: More reliable convergence of rotation scaling, and live molecular replacement starts as soon as the model is uploaded. +* jfjoch_broker: Initialize clears the previous dataset's bearer tokens, image buffer and live Rugnux status, and a slow CUDA JIT cache is reported at start. + +### 1.0.0-rc.177 + +* jfjoch_broker: Faster live Rugnux analysis, with the GPU indexers prepared at the start of a collection and kept between collections; Rugnux no longer writes `.ccp4` maps (the map coefficients are in `_maps.mtz`). + +### 1.0.0-rc.176 + +* jfjoch_broker: Optional live Rugnux analysis of DECTRIS rotation collections inside the broker, with merged data, maps and the placed model written beside the master file, the rotation lattice in the scan result, and a "Rugnux live" tab and dashboard row in the web frontend. +* Rugnux: Faster processing, with molecular replacement and model validation spread over several GPUs and run on the Apple GPU on macOS. +* Rugnux: The polarization stated in miniCBF and d*TREK headers is used, twinned crystals' space groups are decided more reliably, and a run that finds no lattice still reports every image. + +### 1.0.0-rc.175 + +* Rugnux: Processes a collection live while jfjoch_broker writes it (`rugnux `). +* Rugnux: Processing starts on the first images and confirms its choices once all are in, so analysis can begin during collection. +* Rugnux: Faster processing, especially on servers with several GPUs and CPU sockets and on computers without a GPU (`--no-gpu`, macOS). +* Rugnux: Uses much less GPU memory, so large data sets stay on the GPU of smaller cards, and a data set too large for the card is processed on the CPU instead. +* Rugnux: On macOS, Bragg integration runs on the Apple GPU. +* Rugnux: Better handling of twinning and pseudo-symmetry, with the twin hypothesis written as `_twin_.mtz`, and a wrong `--model` no longer confirms the data or decides the hand. +* Rugnux: `--model` accepts predicted (AlphaFold) models and falls back to molecular replacement when the model is not placed as a rigid body (experimental `--mr` forces it), settling space group, hand and twinning and writing a different answer as `_mr.mtz`. +* Rugnux: Molecular replacement is faster and settles the space group in more cases with several copies in the asymmetric unit. +* Rugnux: Deposition-ready mmCIF, a richer report, and numbered steps on the terminal with the full log in `_log.txt`; `_P1.mtz`, `--estimate-beam-center` and `--beam-center-search` are removed. +* Rugnux: The beam-stop shadow is found correctly on tilted detectors. +* Rugnux: Stills files that record a stationary goniometer axis get the default stills geometry refinement. +* jfjoch_viewer: "Analyze dataset" uses the same defaults as a bare `rugnux `, and shows the results of processed CBF, marCCD and SMV sweeps. +* jfjoch_viewer: The Files panel refreshes on F5 and every few seconds, and the plot type and other selections stay put during live collection. +* jfjoch_writer: Memory stays bounded and old data files are closed efficiently on long runs, any failure ends the run in an error state the broker is told about, and the master file appears only after its data files; the ZeroMQ pusher logs when a stalled writer makes it drop images. +* Fixes: The TCP image pusher no longer blocks the broker's receiver, GPU out-of-memory failures stop with a clear message, and the XDS plugin masks module and chip edges. + +### 1.0.0-rc.174 + +* Rugnux: Performance improvements on GPU and CPU (more of the pre-scan and of scaling on the GPU, faster CPU spot finding and crystal refinement), with unchanged results. +* Rugnux: More robust processing - patches of persistently hot pixels are masked, an inconsistent merge triggers a retry at the measured beam centre, and builds targeting different CPU levels give the same results. +* Rugnux: Improved scaling and merging - reflections with an overloaded pixel are dropped, as in XDS, sparse rotation sweeps are scaled more reliably, and French-Wilson amplitudes use an anisotropic Wilson prior. +* Rugnux: Improved space-group determination - glide planes in groups without a centre of symmetry, screw axes from short or weak axial rows kept when a higher group is adopted, and more reliable decisions on twinned and pseudo-symmetric crystals. +* Rugnux: Improved small-molecule processing - spots that grow wider than the integration disk and split spots are integrated over their measured footprint, sparse lattices are integrated on every frame, and the `.hkl` file holds unmerged scaled reflections (SHELX HKLF 4). +* Rugnux: Reads Rigaku d*TREK SMV images (Saturn CCD), including detector 2theta and encoded pixel overflows; home-source (rotating-anode) datasets were added to the validation battery. +* jfjoch_viewer: Fixed processing failing at the end with "Wrong JPEG library version" on Linux; the merge window shows the space group with proper subscripts and a checklist of crystal pathologies. + +### 1.0.0-rc.173 + +* 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. + +### 1.0.0-rc.172 + +* Fixed `jfjoch_broker` cancelling every data collection with a CUDA "out of memory" error after long operation: GPU memory no longer leaks with each collection. +* Rugnux scales a rotation sweep until the per-frame scales settle instead of for a fixed three rounds, and says so when they did not - merged intensities, and the space group, resolution cut and frame rejection read off them, change accordingly; `--scaling-iterations` is now the cap on that loop (default 100). +* Rugnux places every frame of a marCCD, SMV or miniCBF series at the spindle angle its own header states, so a series with missing frames, or with angles written modulo 360, is no longer read at the wrong geometry or refused. +* Every rotation run writes two diagnostic files beside its reflections: `_detector.jpg`, the detector projection with the pixel mask and the detected beam-stop shadow drawn on it, and `_plot.txt`, one row per image. + +### 1.0.0-rc.171 + +* Rugnux: basic support for CCD images (marCCD, SMV) and for gzipped miniCBF. +* `jfjoch_viewer`: opens the CCD formats, and fixes to the dataset plots. +* Documentation updates. + +### 1.0.0-rc.170 + +* Fixed a `jfjoch_broker` crash during indexing: sorting no longer misbehaves on non-finite values, and GPU FFT indexer kernel launches are now error-checked. +* Rugnux needs about 40% less peak memory to scale, merge and post-refine rotation data, with identical results. +* `rugnux --model`: the placed coordinate file carries the space group its own coordinates obey, and says so when that is not the group the reflection files beside it carry. +* `jfjoch_viewer`: fixes in the dataset plots, inspector and layout; spot markers lose their black outline by default (a checkbox under "Image features" restores it) and the highest-pixel markers are white boxes around the pixel. + +### 1.0.0-rc.169 + +* Building Jungfraujoch no longer needs zlib or Eigen installed on the machine, and the dependencies the build fetches are pinned and updated to current releases. +* Rugnux: improvements in indexing, lattice selection and geometry post-refinement, which index crystals that previously returned no lattice and keep the better of the two geometries a run measures. +* Rugnux: improvements in beam-centre measurement, beam-stop detection and space-group determination. +* Rugnux: the unit cell reported with a determined space group now obeys that group - a cell whose symmetry was confirmed from the intensities is re-refined under it, and a cell the group cannot describe is reported with a warning rather than as it stands. +* Rugnux drops the stretches of a rotation sweep whose removal measurably improves the merged intensities and reports what became of every frame, and decides the resolution cut on the crystal's own diffraction rather than on its ice rings. +* The Rugnux results report is machine-readable - every line that is not `KEY= value` data starts with `#` - and states the build it was written by, its authorship and its terms of use (`REPORT_VERSION= 8`). +* `jfjoch_viewer`: improvements in the file manager (CBF frames beside HDF5 datasets, a remembered root), the dataset plots, the inspector and the image statistics, plus a settable font size, a view of the Rugnux results report, usable performance over a remote display (`ssh -X`) and a reset of all settings to defaults; the reciprocal-space window is removed. +* Broker fixes around DECTRIS collections and dark-mask calibration: re-initialising after a run that never started no longer freezes the broker, a cancelled calibration is abandoned instead of reported as done, and a collection whose start message never arrives ends by itself. + +### 1.0.0-rc.168 + +* Rugnux is substantially faster - a corpus of 145 rotation datasets processes in about two thirds of the time - with identical results. +* A crystal whose lattice looks more symmetric than it is because the beam centre is off is no longer processed on the wrong cell. +* Rugnux prints at startup, and writes at the foot of every results report, a short acknowledgement of the X-ray research community whose methods it implements and of the open-source projects it builds on; `ACKNOWLEDGEMENT.md` now ships in every package beside `LICENSE` and `THIRD_PARTY_NOTICES.md`. + +### 1.0.0-rc.167 + +* `rugnux --model` reports CC(model, data) - the correlation of the merged intensities with the placed, scaled model - by resolution shell, on the same shells as CC1/2, with the reflection count and a significance for each. +* `rugnux --model` fits the model's scale, anisotropic B and bulk-solvent parameters on the working reflections only, so the R-free it reports is measured against a model no free reflection helped scale. +* The bulk-solvent parameters of `rugnux --model` are searched over their physically meaningful range instead of being fitted without bounds, so a model is never scaled with a solvent term that has silently switched itself off. +* The rigid-body placement of `rugnux --model` uses the same bounded bulk solvent as the reported fit, so a model is no longer placed against a target carrying a solvent term with no physical meaning. +* `rugnux --model` puts the model into the data's own description of the lattice before placing it, so a model whose cell is written on other axes - I-centred where the run indexed C-centred, a different unique axis, a permuted orthorhombic cell - is placed rather than scored where it was read; `MODEL_CHANGE_OF_BASIS=` and `MODEL_SETTING_AS_READ=` report it when it happens. +* The Rugnux results report opens with a summary - `VERDICT=` (`OK`, `WARNINGS`, `UNUSABLE`, `FAILED`), `VERDICT_TEXT=`, `PATHOLOGY_FLAGS=` with one closed-vocabulary code per condition that warned, and the `WARNING:` lines, which used to close the file - and the sections after it are renumbered 1-5 with no gaps. +* `rugnux --developer` writes the full results report - the pipeline-internal keys and the long explanations the default report now leaves out - and `--finalist-ledger` adds the evidence for every space group the search considered, not only the one it adopted. +* The results report warns when the merged data carry no usable signal and when too little of reciprocal space was measured inside the fitted resolution, and omits `FITTED_RESOLUTION` where the CC1/2 curve it is fitted on never falls off. +* Rugnux detects translational pseudo-symmetry and reports it under the `PSEUDO_TRANSLATION` flag as `TNCS_DETECTED=` and the `TNCS_*` keys - a translation the merged data are exactly invariant under is reported as `UNDECLARED_LATTICE_TRANSLATION=` under `LATTICE_TRANSLATION` instead - and a detected pseudo-translation can no longer buy a false screw axis in the space-group search or hide a twin from the L-test (`L_TEST_VS_TNCS=`). +* The space-group search determines glide planes from zonal systematic absences, so a non-Sohncke space group such as P 2_1/c or Pbca is named where the run previously stopped at its Sohncke subgroup; `SOHNCKE_SPACE_GROUP=` carries the best Sohncke group beside it on every run that searched, and a centre of symmetry is never claimed. +* Where the cell metric carries more rotational symmetry than the Bravais class the indexer named, the extra rotations are put to the intensities and the space-group search is asked again on the metric's own cell - adopted only where the intensities confirm the higher symmetry - so a lattice that is nearly but not exactly hexagonal, or whose reduction landed in a sub-cell, still reaches its true point group. +* Systematic-absence calls rest on the evidence rather than on counts: a screw axis whose absent class the data show extinct is no longer refused because a handful of reflections in it read as present, and `SPACE_GROUP_ALTERNATIVES=` no longer drops a candidate that differs only on a zone the sweep never measured. +* A reference correlation measured on too few reflections is refused instead of scored zero, so a run given a reference MTZ is no longer reindexed on an operator that mapped almost everything outside the reference's coverage. +* A frame counts as indexed from 6 spots on its lattice rather than 9, so a weakly diffracting crystal whose frames cannot carry 9 is no longer refused the lattice it fits; `--min-indexed-spots` overrides it. +* `-C` accepts a known cell in any equivalent description - conventional or primitive, centred or not - instead of only the reduced primitive form, so a centred cell given the way it is published no longer makes the run report that it found no lattice. +* Each reflection is corrected for the sensor's quantum efficiency at the angle it meets the detector (attenuation lengths from the NIST tables, which also fixes the spot-width parallax term on CdTe) and for the attenuation of the flight path between the sample and its pixel; `--flight-path air|helium|vacuum` declares the medium - default air, since no file states it - and the report says what was assumed and what it was worth. The unmerged MTZ records the factors in new `QE` and `FLIGHT` columns beside `LP`, so raw counts are `I / LP * QE * FLIGHT`, and `_process.h5` in new optional `qe` and `flight` datasets. +* Rotation geometry post-refinement fits the crystal and the detector at once, against the observed spot positions and the observed rocking angles together, so the refined distance depends far less on how wrong the file's distance was. +* A coarsely sliced sweep integrates correctly: partials are joined into one rocking event by angle rather than by frame count, so two crossings of the Ewald sphere are no longer summed into one full, and at 0.5 degrees per image or coarser the per-frame geometry refinement accepts a spot whose miss the exposure's own rotation accounts for. +* `rugnux --mode scale` reports the detector tilt and direct beam of the geometry it re-scaled at, instead of zeros that read as a flat detector, and no longer warns that no image was indexed on a run whose lattice came from its input file. +* Every rotation run that determined a space group and merged reports what the mounting cost: `SPINDLE_LOST_UNIQUE_FRACTION=` is the fraction (0-1) of unique reflections the mounting made unmeasurable under the measured point group, also written to the master as `/entry/MX/spindleLostUniqueFraction` and what the mounting warning fires on; `SPINDLE_SYMMETRY_AXIS_ANGLE_DEG=` / `SPINDLE_SYMMETRY_AXIS_ORDER=` describe the mounting in the `--developer` report. +* Stills and grid scans carry a per-image `spindle_blind_fraction` - how much of a rotation sweep's blind cone this orientation would make unrecoverable, 0.5 and above calling for a second orientation - through the CBOR stream, HDF5 (`/entry/MX/spindleBlindFraction`), the plot and scan-result APIs, and the viewer and frontend plots; an absent value means the frame could not be assessed and is not a 0. +* `jfjoch_viewer` gains Help entries for the mouse shortcuts and the acknowledgements, and Inspector toggles that hide non-indexed spots and spots on ice rings. +* The results report's `REPORT_VERSION` is 7. + +### 1.0.0-rc.166 + +* `rugnux --model` treats the model as a hypothesis: it decides the enantiomorph and the indexing only where its R-work beats that of the same model in random orientations, and a model the data reject is still scored, placed and mapped, but leaves the reflection files byte for byte what a run with no model writes. +* `rugnux --model` places the model against the data as a rigid body before scoring it, writes sigma_A-weighted 2mFo-DFc and mFo-DFc maps in place of the unweighted 2Fo-Fc and Fo-Fc, and writes the model as it was placed - `_model.cif`, and `_model.pdb` where the PDB format can express the cell - in the cell and space group of the reflection files beside it. +* `rugnux` and `jfjoch_viewer` read PILATUS miniCBF sweeps natively, and open masters written at other facilities, including Eiger 1.x and third-party NXmx. +* `rugnux` determines the lattice and the space group more reliably - the true cell where the first pass offers a whole-number multiple of it, so a pseudo-translated crystal keeps its full-length axis and a small molecule is indexed on its own cell rather than a protein-sized one, and the point group, the setting and the systematic absences - and `-S` refuses or re-seats a fixed space group whose symmetry axes the indexed cell does not carry. +* `rugnux` measures the beam centre on every run and indexes with it when the file's value indexes nothing, refines only the detector-tilt component the data determine - a beam-centre error is no longer reported as a tilt - and places a detector swung out on a 2theta arm where the file says it stands. +* `rugnux` writes the unmerged MTZ by default, with a P1 merge beside it, a batch header for every image the observations span, and events kept to the same `--min-captured-fraction` as the merge, so a wrong space group can be re-merged in a scaling program without reprocessing. +* `rugnux` writes reflection files in the conventions downstream programs read: `FreeR_flag` is 0 for the test set and 1 for the working set - it was the other way round - the merged and P1 MTZ carry the reserved `HKL_base` dataset so a CCP4 program reads the wavelength instead of falling back to 1.54187 A, and the merged mmCIF marks the free set as `_refln.status` = `f`. +* The Rugnux results report carries the space groups the data cannot separate and the enantiomorph state, the model's verdict and what it was allowed to decide, the detector geometry measured and what a single sweep cannot determine, the resolution the CC1/2 fit reached, which reciprocal axis each anisotropic diffraction limit belongs to, and twinning measured before and after the space group was decided; `REPORT_VERSION` is 6, and `SPACE_GROUP_ENANTIOMORPH= DETERMINED_FROM_MODEL` is now `ASSUMED_FROM_MODEL`. +* `rugnux --mode calibration` writes `.json` beside the `.poni`, holding the geometry as a `jfjoch_broker` `dataset_settings` body, and refuses a fit that is not a measurement - no `.poni`, a non-zero exit, `converged` recorded in the `.json`; `--no-refine-tilt` holds the detector tilt at the file's value instead of zeroing it. +* A snake grid scan with a negative slow step and an even number of rows no longer has its positions mirrored along the fast axis in the HDF5 master and the grid map, so the positions recorded for that configuration change; `jfjoch_viewer` draws grid scan cells in the proportion of the scan steps, labels the merge-statistics plot over the range the axis is drawn on, and builds its powder-calibration ring list from the loaded dataset's space group as well as its cell, so a centred sample cell no longer scales the whole fit. +* The HDF5 master records `direct_beam_x`/`direct_beam_y` - where the undeflected beam lands, sent on the CBOR start message too - the beam size at the sample as `incident_beam_size` from the new `dataset_settings` `beam_size_x_um`/`beam_size_y_um`, and `/entry/MX/peakCountUnfiltered`; `dataset_settings` accepts any `smargon.chi_deg`, which was restricted to 0-90 degrees. +* Reported completeness counts the reflections the beam stop, a detector mask or the low-resolution limit kept out of the merge as missing: the denominator, and the resolution shells it is binned into, now span the run's declared resolution range rather than the range of the reflections that survived, so the innermost shell boundary moves and its numbers are not comparable with those of an earlier release. +* The Rugnux results report carries `CC_ANOM` beside `SIGANO`, overall and per shell: the anomalous difference measured from one half of the observations correlated against the same difference from the other half, which says whether there is an anomalous signal to phase on without depending on the error model. Reported on Friedel-merged runs too; it matches AIMLESS and phenix, and XDS's similarly named `Anomal Corr` is a different quantity. +* A quantity a Rugnux run did not measure is left out of the results report altogether instead of being written as `nan` - `SIGANO=` on a Friedel-merged run, which is the default, is the case a script meets first - and a merging-statistics shell prints `-` in its place. +* `FITTED_RESOLUTION=` in the results report is the resolution fit of the run's own merge rather than of the P1 cross-check, and the unmerged MTZ is written in the space-group setting the run adopted rather than in that setting's reference one. +* `rugnux --mode calibration` refuses to write a `.poni` for a detector whose stored image is mirrored or turned by a multiple of 90 degrees, the format having no field for it. +* CC1/2 is computed on half-sets of equal size, so every reflection measured more than once contributes to it, as in XDS and phenix.merging_statistics, and a CPU-only build now reports the same value as a CUDA one; reported CC1/2 values move slightly, most where multiplicity is low. +* The Rugnux manual is reorganised into task pages with a run overview and worked phenix / REFMAC5 / Phaser / SHELXC/D/E / POINTLESS-AIMLESS / careless examples, and the HDF5 and API documentation say how a grid scan records the angle its spindle stood at: the goniometer axis with a step of 0. + +### 1.0.0-rc.165 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* `rugnux --model` adopts the model's space group as a label where the data were merged in its enantiomorph, instead of reindexing the reflections - which swapped I(+) with I(-). +* `rugnux --model` warns, naming the atom, when the anomalous density at the model's atoms comes out inverted, which means the data and the model are in opposite hands. +* `rugnux --model` writes an anomalous difference map (`_anom.ccp4`) when the merge kept the Bijvoet split, and names the ten model atoms it peaks highest on as `ANOMALOUS_SITE_01`..`_10`. +* `MEAN_ATOM_DENSITY_SIGMA` is read from the map by cubic rather than linear interpolation and comes out around a tenth higher; it is no longer comparable with the figure earlier versions printed. +* `rugnux --model` reads an mmCIF coordinate file as well as a PDB one, gzipped or not, taking the format from the file's content rather than its name. +* A model `rugnux --model` cannot use is reported as a `WARNING:` line in the results report instead of only in the log. +* The Rugnux results report has a `10. MODEL VALIDATION` section when `--model` was given; `REPORT_VERSION` is 4, `WARNINGS` moves to section 11 and no existing key changed. +* The Rugnux results report records how the run was invoked, what it cost and what it ran on: `COMMAND_LINE=`, `WALL_TIME=` and `GPU_COUNT=` / `GPU=`. +* Rugnux says which GPUs it can see before it starts processing. +* `rugnux --export-unmerged` also writes `_unmerged.mtz` on a `--no-merge` run, and is ignored on a run with no output prefix instead of writing a file called `_unmerged.mtz`. +* `/start` asks the writer whether the run can be written before the detector is armed, so a run whose master file already exists, or whose output directory cannot be created, is refused up front with the writer's own message. This needs the TCP image stream or the built-in HDF5 writer; the ZeroMQ stream is unchanged. +* A calibration that fails goes to `Error` carrying the reason instead of `Inactive`, so `/wait_till_done` and `/wait_until_running` report it; a cancelled calibration still goes to `Inactive`. +* `/wait_till_done` answers 500 with the message when a collection ended in an error. A cancelled collection and a collection that only triggered a warning still answer 200. +* A pending start failure is discarded by `/cancel` and `/deactivate`, as it already was by `/start` and `/initialize`. +* `/scan_result` no longer reports the previous run's images after a collection that failed to start, or after `/deactivate`. +* The TCP image stream protocol version is 4. `jfjoch_writer` and `jfjoch_broker` have to be of the same release, as before. + +### 1.0.0-rc.164 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* Rugnux now tells you whether a crystal diffracts anisotropically and how far it reaches in each direction, without a second program: a new `9. DIFFRACTION ANISOTROPY` section in `_report.txt` and matching `_reflns.pdbx_aniso_B_tensor_*` / `_reflns.jfjoch_aniso_*` items in the merged mmCIF report the anisotropic deltaB, the diffraction limit along each principal direction, and a `NOT DETECTED` / `DETECTED` / `CANNOT DETERMINE` verdict measured against the data set's own systematic error. It is a description only - no intensity is corrected, no reflection is removed, and the merged data do not depend on direction. +* Rugnux can hand its integrated observations to another scaling program: `--export-unmerged` writes `_unmerged.mtz`, an unmerged MTZ readable by aimless, pointless, careless and `iotbx.merging_statistics`, in `--mode mx` and `--mode scale` alike. Each rotation reflection's partials are summed into one full; `--export-unmerged-partials` writes one row per image instead. Intensities carry the Lorentz-polarization factor and nothing else, since those programs scale the data themselves. Lattice-centring absences are not written; screw and glide absences are. +* Rugnux integrates crystals with broad spots better - where it changes anything, per-shell mean I/sigma improves by up to 31% and R_meas by up to 24% - because on rotation data the integration signal radius is now taken from the crystal's own measured spot width instead of a fixed 4 px. `--adaptive-integration-radius=off` restores the fixed radius and an explicit `--integration-radius` still overrides both. The widened radius applies to the final integration pass only, and a pattern too dense for it is re-integrated at 4 px with a note in the log. +* Rugnux discards fewer stills reflections for want of a background ring, improving per-shell R_meas over most of the signal-bearing range: the stills background ring now runs to 14 px instead of 12. The gain reverses in shells below a mean I/sigma of about 4. +* Rugnux determines the space group with thresholds that mean the same thing on a weak crystal as on a strong one: symmetry operators are scored on resolution-normalised intensities (E squared) instead of raw merged intensities, and a reflection counts as genuinely present on its counting significance instead of on the merged I/sigma, which saturates at the merge's own ISa. The search resolution cut is no longer able to move the answer, and the twin-law H bound moves from 1.70 to 1.85, which stops one class of correct high-symmetry assignment being refused as twinning. +* Rugnux says what the space-group search tested and what it could not: the twin-law disagreement H is printed for every operator together with the adopted point group's H ratio and its bound; alternatives that are not on the reported lattice are named with how their cell differs; and a lattice centring the data could not test - the crystal having been integrated on the primitive sub-cell, so the reflections it extinguishes were never measured - is marked `UNTESTED` and warned about where it is adopted, as coming from the lattice metric rather than from the intensities. +* Rugnux `--mode scale` re-merges a `_process.h5` in the right symmetry without being told it: the file now records the space group on every run - a two-pass rotation run wrote none before, so re-merging defaulted to P1 - together with the change of basis under `/entry/MX/reindexMatrix` where the lattice was re-seated, and `--mode scale` also reports the Wilson B-factor estimate instead of `WILSON_B= nan`. A file written before this stops with a message naming the two cells and the override to use, instead of failing inside the merge. A third-party reader of a `_process.h5` must apply `reindexMatrix` where it is present. +* Rugnux installs on its own, as a package called `rugnux` - `dnf install rugnux` or `apt install rugnux` - instead of arriving inside `jfjoch-viewer`. It pulls in none of the acquisition stack, so a machine that only processes data no longer has to carry the broker, the detector libraries or Qt to get it. Installing it over a `jfjoch-viewer` from rc.163 or earlier, which still owns `/usr/bin/rugnux`, upgrades cleanly rather than failing on the duplicate file. +* Rugnux is also a standalone download, built for arm64 as well as x86_64: `rugnux--linux-{x86_64|aarch64}-cuda.tgz` and `rugnux--win64-cuda.zip` on the release page, for machines that are not managed by a package manager. The aarch64 build targets GH200 and DGX Spark, and is untested on hardware. +* Every portable Linux binary is now a single self-contained file: cuFFT is linked statically instead of being shipped beside the executable and found through an rpath, so `rugnux` and `jfjoch_viewer` need nothing but an NVIDIA driver, and only to use the GPU. The `.rpm`/`.deb` continue to take cuFFT from the distribution. The developer utilities `jfjoch_extract_hkl` and `jfjoch_recompress` are no longer packaged anywhere. +* Jungfraujoch needs six fewer shared libraries on the machine - libopenblas and libmetis, and libgfortran, libquadmath, libgomp and libz behind them - because the Ceres LAPACK, METIS and SuiteSparse back-ends are no longer built. Nothing in the code ever selected them, and results are unchanged. +* The PCIe driver DKMS package builds for the kernel it is being installed for instead of the running one, so a module built while a kernel update is being applied loads after the reboot. +* The PCIe driver builds on RHEL 9.5 and later, and on their CentOS Stream, Rocky and AlmaLinux equivalents, where the `vm_flags` kernel interface was backported into the 5.14 kernel. +* A data collection started with `async_start` that fails to start - a writer refusing to overwrite an existing file, for instance - is reported as an error by `/wait_until_running` and `/wait_till_done` instead of as a timeout and a successful collection respectively. The error message is the one the writer gave. +* A calibration that is cancelled or that fails to collect its pedestals is no longer reported as a successful one. The broker goes to `Inactive` with an error message and has to be initialized again, instead of sitting in `Idle` looking ready to measure while holding partial pedestals - data collected in that state was silently mis-converted. +* A failed `/initialize` is reported to `/wait_until_running` and `/wait_till_done` as soon as it happens, instead of when their timeout expires. +* `space_group_number` accepts space groups up to 230 in the API schema, so cubic space groups can be recorded. The broker always accepted them; the generated clients rejected them before the request was sent. +* The results report's `REPORT_VERSION` is 3, two sections having been added. Existing key names and table columns are unchanged. +* The merged statistics table has **9** resolution shells instead of 10, which is what XDS reports. The bins were already XDS's - equal steps in 1/d^2 between the lowest- and the highest-resolution reflection the merge kept - so at the same resolution limits the two tables now have the same shell boundaries and can be read row for row. `--resolution-shells` sets a different count. +* `rugnux --model` now settles the frame the merged reflections are written in, not only the frame the R-factors and the maps are computed in: the `.mtz`/`.cif`/`.hkl` come out in the model's indexing, and where the data were merged in the model's enantiomorph they take the model's hand and space group - which on anomalous data puts I(+) and I(-) the right way round. The indexing choice is logged with the winning R-free and the runner-up, so a decision made within noise is visible. +* `rugnux --model` can resolve the indexing ambiguity of a **serial stills** run, which a model could not do before: structure factors computed from the model become the per-image reference, the same role a reference MTZ plays. It needs the cell and space group up front (`-C` / `-S`). Without one or the other, a merohedral serial run still merges both hands together and says so. +* The Rugnux documentation opens with a quick start - the default run, and runs with a reference MTZ, with a model, or with the space group and cell pinned - and explains the indexing ambiguity: what it costs on rotation and on serial data, and which of `-z` / `--model` resolves it in each case. The long reference pages now carry a table of contents. + +### 1.0.0-rc.163 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* Packaging: each package installs its license notices under a directory of its own - `share/doc/jfjoch_broker`, `share/doc/jfjoch_writer`, `share/doc/jfjoch_viewer`, `share/doc/jfjoch_driver_dkms` - instead of all of them into the shared `share/doc/jfjoch`, so `jfjoch` and `jfjoch-writer` can be upgraded one at a time instead of only together. + +### 1.0.0-rc.162 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +**Files written by Jungfraujoch now import correctly in DIALS, XDS and pyFAI.** A tilted detector, a grid scan, a still recorded at a goniometer position, and saturated or unreadable pixels were each described in a way that a third-party program acted on wrongly. If you process Jungfraujoch data outside Jungfraujoch, prefer this release to any earlier one. + +* HDF5: the detector tilt (`rot1`/`rot2`/`rot3`) is exported correctly in the NXmx transformation chain; untilted geometries are unaffected. +* HDF5: a still recorded at a goniometer position is no longer read back as a single image, and a grid scan records a stationary spindle so a program that requires a rotation axis can open it. +* HDF5: the sample transformation chain is written in mounting order, with a Smargon head position told apart from the spindle, one entry per image, `module_offset` as a float unit vector, and `offset_units` on every offset. +* HDF5: saturated, underloaded and unreadable pixels are described so a downstream program masks them - `saturation_value`, `underload_value`, `error_value` and `bit_depth_readout` are written correctly, and a data file missing next to a VDS master reads as the error marker rather than as zero counts. +* HDF5: the rotation axis is read back under whatever name it carries, and `mirror_y` records whether the assembled image is mirrored in Y relative to the detector's raw readout. +* A grid scan and a goniometer axis can both be set; they are no longer alternatives. +* `images_per_file` is chosen from the acquisition when it is not given: a rotation sweep of at most 20000 images goes into a single data file, a grid scan splits on whole fast-axis rows, and stills and serial keep 1000. +* The writer refuses a stream whose start message declares a different pixel format than its images carry, and a DECTRIS detector sending signed images is no longer declared unsigned. +* The image stream can carry the sample transformation chain (`transformations`, in the END message); a producer that does not send it gets the same chain built by the writer. +* Rugnux: fixing the space group with `-S` no longer prevents the lattice from being found - a lattice indexed in a different setting is reindexed into that group's own setting, and a run whose crystal does not have that group's lattice stops and names the cell it indexed as, rather than reporting statistics that cannot describe it. +* Rugnux: the per-image resolution estimate now predicts the resolution the merged data reach rather than the highest-resolution spot found, and is reported as `SPOT_RESOLUTION_ESTIMATE`. +* Rugnux: two runs of the same command on the same images produce the same merged intensities; the azimuthal profile written alongside them is not yet reproducible in the same way. +* Rugnux: the offline lattice refinement is bounded by iterations rather than by a wall clock, so a loaded machine can no longer refine to a different lattice; a live acquisition keeps its real-time bound. +* Rugnux: the detector-frame modulation correction is fitted on a grid spanning the detector, so whether it is applied no longer depends on how far integration reached. +* Rugnux: the geometry pre-pass no longer writes `_01.mtz`, `_01.cif`, `_01.hkl` and `_01_image.dat`; the refined second pass writes those files under ``, and that is the result to use. +* Rugnux: `_process.h5` describes the pixel format of the images it links to, and is written on a thread of its own. +* Rugnux: the detector geometry is also logged in XDS's convention (`ORGX`/`ORGY`, detector axis vectors, rotation axis), so it can be compared with an XDS refinement. +* Rugnux: an image integrated in pyFAI through the `.poni` file written by `--mode calibration` comes out with the correct azimuth, and the file declares pyFAI's `orientation`, which needs pyFAI 2024.01 or newer. Radial integration is unchanged. +* Rugnux: a rotation run is substantially faster throughout - beam-stop detection, first-pass indexing, geometry refinement, integration, scaling and merging - and observations outside the scaling resolution range are dropped as they are ingested. The refined geometry, the space group chosen and the merged statistics are unchanged. +* Faster spot finding and indexing, on the broker as well as in Rugnux; the spots found and the lattices indexed are unchanged. +* A run reserves substantially less GPU memory: nothing is allocated for buffers that are never read, and a worker builds only the engines it uses. +* Rugnux: with `-N` left at its default the per-image loop of `--mode mx` uses at most 16 workers per GPU, rather than one per hardware thread; an explicit `-N` is obeyed as given. +* CUDA 12 builds now contain device code for Volta, so the RHEL 8 packages and the portable Linux `.tgz` run on a V100; the CUDA 13 artefacts (RHEL 9, Ubuntu, Windows) remain Turing and newer. +* The build resolves a single Eigen for the whole project, and refuses to configure if Ceres picks up a different one; a build that mixed two Eigen versions was undefined behaviour and crashed at -O2. +* Documentation: a security page, and the supported GPU generations and minimum NVIDIA driver version of every released artefact. + +**Breaking change to OpenAPI** - regenerate the client (`jfjoch-client` 1.0.0-rc.162, `frontend/src/client`): +* `dataset_settings.images_per_file` is no longer `default: 1000` and no longer accepts `0`; it is optional, and its minimum is 1. A client sending `0` (previously "one file for the whole run") is now rejected - omit the field instead, which for a rotation sweep gives the same single file. +* `file_writer_format` now defaults to `NXmxVDS`, matching the server's own default and the layout recommended for DIALS, XDS and CrystFEL. A generated client that fills in schema defaults and does not set the format explicitly will write VDS masters where it previously wrote legacy ones; set `NXmxLegacy` explicitly to keep them. + +### 1.0.0-rc.161 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* **Rugnux: significantly better quality of results, and faster.** A large rework of integration, scaling, merging, geometry refinement and space-group determination, together with measurements the program previously made no attempt at - the direct beam before indexing, the beam stop, the goniometer rotation scale, and the stretches of a sweep the crystal did not deliver. A rotation dataset typically gains observations at better and R_meas, and every `mx` and `scale` run writes a `_report.txt` results report modelled on XDS's `CORRECT.LP`. Many defaults moved with it: spot detection is self-calibrating, beam-stop detection and rotation geometry post-refinement are on, resolution limits default to as far as the detector reaches, and ice-ring handling engages only where the crystal is measured to have ice. +* **jfjoch_viewer:** the beam-stop shadow, the detector calibration and the beam-centre measurement are reachable from "Analyze dataset"; the settings panel reports how the sample moved and how polarized the beam was; image rendering and interaction are faster. +* **Performance:** bitshuffle+LZ4 images are decoded on the GPU rather than on the host, with the bitshuffle inverse fused into preprocessing so the decompressed frame is never held in device memory. +* **Broker, writer, packaging and build:** image-slot lifetime and locking fixes, per-image datasets sized by the images actually written, the Debian/Ubuntu broker package renamed to `jfjoch`, and `image_analysis` compiling under MSVC again. + +**Breaking change to the Rugnux command line:** +* `--azint-only` and `--scale` are **removed**, replaced by `--mode azint` and `--mode scale`; the full pipeline is `--mode mx` and remains the default. A script passing the old flags now fails with the list of valid modes rather than silently running the wrong one. +* `-t`/`--stride` is **refused on rotation data**: skipping frames cuts every reflection's rocking curve, so the combined fulls and their partiality would be measured over frames the sweep never recorded. Select a contiguous range with `-s`/`-e` instead. `--mode azint` and `--force-still` still take a stride. + +**Breaking changes to OpenAPI** - regenerate the client (`jfjoch-client` 1.0.0-rc.161, `frontend/src/client`) or read the affected fields as optional: +* `image_scale_b` is removed from the `plot_type` enum, so a client requesting that plot now gets an error rather than a curve. +* `azim_int_settings.high_q_recipA`, `spot_finding_settings.high_resolution_limit` and `spot_finding_settings.low_resolution_limit` are no longer `required`. All three mean "no limit at that end" when unset and are omitted from the response instead of carrying a placeholder value, which raises in a client generated from an rc.160-or-earlier spec. A value of 0 is still accepted and means the same thing. + +**Breaking changes to the stored formats** - a consumer reading these fields must treat them as optional: +* The per-image image-scale B factor is no longer computed, so `/entry/MX/imageScaleBFactor` is absent from newly written HDF5 files and the corresponding key is absent from the CBOR DataMessage and END blocks. Files written by rc.160 and earlier still contain it and still open; nothing in the pipeline reads it any more. +* `_reflns.jfjoch_diffrn_ISa` now carries the whole-range `1/sqrt(a*b)` that XDS's ISa denotes, and the error-model `a` and `b` are reported in XDS's convention; the strong-reflection asymptote moves to `_reflns.jfjoch_diffrn_ISa_asymptotic`. **A file written by an earlier version carries the asymptote under the plain `ISa` name.** + +### 1.0.0-rc.160 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* Rugnux: Rotation **geometry post-refinement** is now on by default (`--rotation-no-postrefine` to disable; also a viewer checkbox). A first pass integrates at the header geometry, then the shared detector distance + beam centre and the crystal cell/goniometer-axis are post-refined over all frames (cross-validated, committed only for a small < 1 % move, with the gauge-weak beam centre restrained toward the header); a second pass re-indexes de novo and re-integrates at the refined geometry. The refined pass is the canonical `_*` output; the header-geometry pass is kept as `_01_*`. +* Rugnux: Optional per-batch **relative-B** correction for rotation (`--relative-b[=deg]`, default 10°-of-rotation batches when bare, off otherwise) - a cross-validated, curvature-smoothed resolution×dose correction beyond the single global decay slope. +* Rugnux: Always-on **radiation-damage report** for rotation - the per-image scale correlation-to-merge and mosaicity versus dose, plus the relative B-factor change over the run (first→last) as a scalar and a per-batch relative-B curve, printed to the log and written to the merged mmCIF. Report-only; it never alters the merge. +* Rugnux: De-novo space-group search ranks candidate lattice **centerings by net absences** (systematically-absent minus violating), not the gross absent count, fixing an over-centering of a genuinely C-centred lattice to F. +* Rugnux: Record the **producing software** (name and version) and the refined **detector distance and beam centre** in the merged mmCIF (and the software in the MTZ history). +* Bragg integration: Carry the box-sum observed centroid through the profile-fit path, so the observed spot centroid is emitted in every integrator mode. +* Rugnux: Report **ISa** as the counting-subtracted strong-reflection asymptote, not `1/b` of the whole-range fit; it also sets the merged-sigma floor. CC1/2, R-meas and per-obs sigmas unchanged. +* Frontend: Azimuthal-integration Q fields (Q spacing / Low Q / High Q) accept 5 decimals (was 3), matching the 1e-5 `q_spacing` minimum; number-field precision is now configurable. +* Rugnux: Add a dataset-wide **Wilson B-factor** estimate to the merged output (mmCIF, stats table, log); the per-image viewer Wilson B emits NaN for implausible fits. +* Rugnux: De-novo space-group search vetoes a merohedral-twin over-promotion whose systematic error-model `b` balloons past a calibrated bound (keeps R3 as R3, not R32). +* Rugnux: De-novo space-group search decides lattice **centering** from the strength (mean I/sigma) of the systematically-absent class, not a per-reflection violation count. +* Rugnux: Recover lattice **centering** on weak / low-energy data via a floor-independent test (rate of significant absent vs present reflections), fixing a missed I-centring at 5/13 keV. +* Rugnux: Report anomalous signal-to-noise **SigAno** = <|I(+)-I(-)|>/ per shell and overall (mmCIF PDBx items + stats-table column); anomalous merges only. +* Rugnux: De-novo space-group search recovers a genuine high-symmetry group on weak data with a broken sigma model by confirming on the systematic-`b` test alone (restores an F432 case). +* Rugnux: Print the adopted **space group and unit cell** as a one-line summary at the end of the run (de-novo or user-fixed `-S`). +* Rugnux: Score the radiation-damage **decay** cross-validation on a sigma-independent (R-meas-like) metric, so a spurious slope can't pass by reshaping sigmas. +* Rugnux: Fix de-novo rotation indexing committing a spurious axis-multiple supercell (collapsing to P1) via a cross-scheme smaller-cell tie-break on near-integer volume ratios. +* Rugnux: Widen refined-cell angle bounds to [30, 150] deg (rotation candidate and per-frame stills refinement); check refined angles against the reference cell. +* Rugnux: `-S`/`--space-group` now accepts a Hermann-Mauguin symbol (e.g. `P43212`) as well as a space-group number. +* Rugnux: Warn when the chosen cell/space group carries an indexing (merohedral) ambiguity needing a reference to resolve. +* Indexing: Requesting the FFTW (CPU) indexer on a GPU node now fails with a clear, actionable message (rotation always uses the GPU FFT indexer there). +* Rugnux: Stills `--refine-geometry[=N|off]` - first-pass bundle-adjust of beam/distance/cell then re-index (default ON with a reference cell); accepts reference `F`/`FP` columns. +* Rugnux: Per-image geometry refinement `-r flex` tries all three algorithms per image and keeps the best (old name `multi` kept as an alias). +* Rugnux: Experimental stills partiality `--still-partiality` (Gaussian excitation-error) and `--partiality-uncertainty ` down-weighting the least-complete partials. +* Rugnux: Default the stills Bragg-integration box to r=6 (integration radii 6, 8, 12). +* Rugnux: Self-referenced stills scale in a single pass (fixing a weak-data collapse); a reference MTZ (`-z`) fixes SG/cell/ambiguity but never anchors the scale (stills and rotation). +* Rugnux: Cap normalised intensity (E^2) on second-lattice overlaps in the de-novo space-group search, so strong overlaps don't skew the symmetry decision. +* Rugnux: Fix `--scale` on a self-contained `_process.h5` (stored reflections and error model reload correctly). +* Rugnux: Add `--spot-low-resolution ` (default 50 A) and `--min-pix-per-spot ` (default 2) to tune spot finding on weak serial data. +* jfjoch_viewer: Expose stills processing settings in the settings dock, rename geometry-refinement `multi` to `flex`, and refit the initial image on resize. +* jfjoch_writer: Remove the CBF and TIFF image writers - only NXmx HDF5 is written (all three layouts remain). +* Reader: Treat a negative `total_flux` in a stored dataset as unknown/absent rather than a valid flux. +* Packaging: Build the self-contained Linux viewer against a static libdbus with glib disabled; add parallel image-build and in-container viewer-verification scripts. +* Rugnux: Write anomalous data as a standard CCP4 anomalous MTZ (one row per reflection: `IMEAN`, `I(+)`/`I(-)`, `F`/`F(+)`/`F(-)`), readable by aimless/mtz2sca/ANODE. +* Rugnux: Always write merged reflections as both `.mtz` and `.cif`; the `--scaling-output` selector and text `.hkl` output are removed. +* Rugnux: Add a detector-plane **modulation** (flat-field) correction surface to rotation scaling (cross-validated, on by default; `--no-scaling-corrections` disables all), dropping R-meas. +* Rugnux: Add optional **stills detector-plane modulation** (`--stills-modulation`, default off) - the same cross-validated surface for the on-the-fly stills path. +* Bragg integration: Local background is now a **symmetric trimmed mean** of the ring (`--background-trim `, default 0.10; monochromatic), improving and resolution-edge CC1/2. + +### 1.0.0-rc.159 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* Rugnux: Add `--model model.pdb` - score the merged data against an atomic model and compute initial maps. It reports R-work/R-free (scaling the model to the observed amplitudes with an overall scale, an anisotropic B and a flat bulk solvent - the standard few-parameter model, so a batch of maps stays directly comparable) and writes 2Fo-Fc / Fo-Fc electron-density maps (CCP4) plus a map-coefficient MTZ. The structure itself is not refined; the model is only re-fractionalised into the data cell. +* Rugnux: The merged reflection output now carries French-Wilson amplitudes (|F| and its sigma) next to the intensities - MTZ `F`/`SIGF`, mmCIF `_refln.F_meas_au`, and the text HKL - computed with the correct centric/acentric Wilson prior and epsilon multiplicity, so a downstream program (e.g. phenix.refine) can refine against amplitudes. The intensity columns are unchanged. +* Rugnux: R-free test-set flags are now assigned deterministically and consistently across symmetry - a Bijvoet pair I(+)/I(-) is never split between the work and free sets, and the assignment is a reproducible per-hkl hash that depends only on the reflection index, so every dataset of one crystal form gets the same ~5% free set (what a multi-dataset campaign such as PanDDA needs). On small data the fraction is floored so the test set stays large enough for a stable R-free (~500 reflections, capped at 10%); it stays flat at 5% on ordinary data. When a reference MTZ carries a `FreeR_flag` column its test set is imported instead, letting a whole campaign inherit one shared free set. +* Rugnux: A reference MTZ (`--reference-mtz`) can now fix the space group and cell for rotation data too (previously rejected), without being used to scale - the rotation merge stays self-consistent. When the crystal has an indexing (merohedral) ambiguity - a lattice symmetry higher than its Laue symmetry, e.g. P3/P4/P6/C2 - the reference also resolves it: each candidate reindexing (identity plus the twin-law cosets of the metric symmetry) is scored by its intensity correlation against the reference and the data are re-merged in the best-correlating one. This is a metric-preserving relabelling of hkl (the cell is unchanged) and a no-op for a holohedral crystal (which has no twin laws). +* Rugnux: `--model` validation now aligns the data to the model before scoring - the observed reflections are reindexed into the model's enantiomorph when the two differ only by hand (indistinguishable from merged intensities). A merohedral indexing ambiguity is resolved against the reference MTZ when one is given (so a whole campaign shares one indexing convention); only with a model and no reference does validation fall back to fitting each candidate reindexing and keeping the lowest R-free. +* Rugnux: De-novo symmetry - recover a genuine high-symmetry group whose data are imperfectly scaled. Such a merge's within-orbit chi² lands just past the self-consistency bound (each real symmetry step adds a little systematic scatter), right where a merohedral twin also lands, so the chi² ratio alone cannot separate them. The candidate is now rescued when the extra intensity-proportional systematic error it invokes stays small relative to the confirmed subgroup - a genuine symmetry step gains multiplicity without inflating the merge error model's b, whereas a twin forces non-equivalent reflections together and b balloons. Fixes a cubic case (I23 instead of I222) with no change to any other crystal in the test battery, including the twins that must stay in their lower symmetry. +* Docs: Document the French-Wilson amplitude estimation, R-free flagging, reference-based space-group/ambiguity resolution, and model-based validation/maps in CPU_DATA_ANALYSIS.md. +* Frontend: The status-bar pill now shows a progress bar during detector calibration (previously only during measurement), and the calibration state and its button are labelled "Calibration"/"CALIBRATE" (the internal `Pedestal` state name is unchanged for back-compatibility). + +### 1.0.0-rc.158 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* Analysis: The azimuthal-integration solid-angle correction now follows the incidence angle to the detector normal (`cos^3` of that angle) instead of `cos^3(2*theta)`, so it is correct for a tilted detector and matches PyFAI `solidAngleArray` and MAX IV azint (unchanged for an untilted detector). Crystal geometry refinement (`XtalOptimizer`) no longer silently ignores an imported PONI `rot3` (rotation about the beam): it is applied as a fixed rotation in the residual so refinement stays consistent with the rest of the pipeline. Polarization and azimuthal binning already honoured `rot3` through the full PONI rotation. +* jfjoch_viewer: Open datasets on the WSL2/UNC filesystem (paths starting `\\`); write processing outputs next to the input file, with a Browse button and independent `_process.h5` / merged `.mtz`/`.cif` toggles; and show the determined space group in the merge-statistics window. +* jfjoch_viewer: Connect to a broker over `https` (an http/https selector in the connect dialog), and keep the HTTP connection alive across reads for faster live-follow. +* jfjoch_viewer: Time out stalled HTTP requests (5 s) so an unreachable broker cannot hang the reader thread, and drop the cached pixel mask when switching data source. +* Rugnux: Accept an absolute `-o` output prefix in offline processing. +* Rugnux: Faster two-pass rotation indexing - the first pass now runs its FFT indexing and geometry refinement in parallel (results unchanged). +* Rugnux: Rotation indexing now works on standard DECTRIS datasets that store no spots - the first pass finds spots itself instead of failing. +* Rugnux: De-novo symmetry robustness - don't over-promote a merohedral twin to the holohedral group (keep e.g. R3, not R32), make the intensity second-moment twinning statistic robust on weak/mis-integrated data, and don't flag twinning in holohedral Laue classes where no twin law can exist. +* jfjoch_writer: Fold the refined beam centre into the NXmx detector `translation` vector too (not only the informational `beam_center` fields), so a reprocessed `_process.h5` has a self-consistent refined geometry. +* Robustness: Harden size handling of untrusted input in TIFF reading and raw-TCP frames. +* Packaging: The self-contained Linux viewer `.tgz` now bundles cuFFT, so it runs without a system CUDA toolkit (`.deb`/`.rpm` are unchanged, distro-managed). +* Docs: Documentation updated to match the current analysis code and CLI. + +### 1.0.0-rc.157 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* Rugnux: Rebrand the offline data-processing subsystem as `rugnux` and consolidate all offline analysis into the single `rugnux` binary - `jfjoch_process` is now `rugnux`, the former `jfjoch_azint` is now `rugnux --azint-only`, and `jfjoch_scale` is now `rugnux --scale` (see the new docs/NAMING.md and docs/RUGNUX.md). Scaling and merging are on by default for rotation and stills (`--no-merge` disables them), replacing the previous opt-in `-M, --scale-merge`. +* Rugnux: CLI fixes - default `-N` to all hardware threads, parse numeric option arguments strictly (reject non-numeric or trailing input instead of silently yielding 0), require `--wavelength > 0`, and correct the reproduced command line and `--scale` reference-cell handling. +* Rugnux: De-novo space-group improvements - recover genuine high symmetry and centred Bravais lattices from intensities, add an automatic CC1/2 high-resolution cutoff, and report L-test twinning statistics. +* Rugnux: Index weakly-diffracting low-resolution rotation data that previously failed (e.g. F-cubic crystals that diffract only to ~4 A on a detector reaching ~1.5 A). The per-frame indexing gate now measures the indexed fraction only within the resolution range the lattice actually diffracts to, so the many sub-diffraction ice/noise spots no longer make the fraction floor unreachable; the two-pass first pass tries several image-sampling schemes (spread across the whole rotation vs a consecutive wedge whose native stride keeps a reflection's rocking curve continuous, letting the FFT resolve a long axis) and keeps the one that indexes the most frames; and the de-novo space-group search no longer discards all reflections (and crashes) when every resolution shell falls below = 1. +* Rugnux: Lower the low-resolution R-meas for strongly-diffracting rotation data - drop edge-of-sweep truncated fulls whose rocking curve was captured below `--min-captured-fraction` (default 0.7 for rotation), and report R-meas only over the observations kept by outlier rejection (matching XDS). The 0.7 default also strips the partiality-extrapolated fulls that dominate the intensity second moment on weakly-diffracting crystals, so the de-novo space-group search is no longer starved by the error-model I/sigma floor and recovers the correct symmetry (e.g. for F-centred cubic lattices that would otherwise be under-assigned). +* Rugnux: Write the refined geometry (beam, tilt, axis) to _process.h5 and place non-standard mmCIF items under a reserved `jfjoch` prefix. +* jfjoch_broker: Ordinary acquisition failures (receiver/writer/analysis problems, missed packets, writer disconnect) now return to the Idle state with an Error-severity message, so a run can be retried without an expensive re-initialisation; only failures that leave the detector in an undefined state (new JFJochCriticalException, e.g. PCIe/FPGA faults) go to the Error state and force re-initialisation. +* jfjoch_broker: A synchronous /start now reports its failure to the HTTP caller instead of returning HTTP 200, and an incomplete or truncated dataset (missing packets, writer disconnect) is reported as an error rather than a "reduce frame rate" warning. +* jfjoch_broker: Drop uncollected placeholder rows (number = -1) from the scan_result REST endpoint. +* jfjoch_broker: Fix the inverted per-image compression ratio reported by the Lite receiver (was compressed/uncompressed instead of uncompressed/compressed). +* jfjoch_broker: Bragg integration adds a quantization-noise variance floor with a box-sum fallback, and treats the type-maximum marker as an invalid pixel for unsigned image types. +* jfjoch_writer: Detect file-overwrite conflicts at start for back-channel transports, and reset the writer when end-of-collection finalisation fails. +* jfjoch_viewer: Preview overlays follow the geometry (resolution/ROI arcs, true beam centre, predictions, coral secondary-lattice spots, legend), add save-as-JPEG, and fix an HTTP live-follow memory leak. +* Frontend: Improved aesthetics and usability, and added in-browser pixel-mask and JUNGFRAU-pedestal visualisation. +* CI: Name the Windows installer jfjoch-viewer-* instead of jfjoch-*. + +### 1.0.0-rc.156 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* jfjoch_process: Major rotation (rot3d) data processing overhaul - robust profile-fit integration, Cauchy-loss scaling with optional absorption surface, de-novo indexing and space-group/centering determination fixes, and merging statistics + ISa in the mmCIF output. +* jfjoch_process: Bragg integration now runs on the GPU in the offline/non-FPGA workflow (one box-sum + profile-fit engine, GPU when available, CPU otherwise); the FPGA workflow integrates on the CPU directly from the assembled image. The previous standalone integrators are removed. +* jfjoch_process: Deterministic Bragg prediction - when more reflections are predicted than fit the output, they are ranked by distance to the Ewald sphere before truncation, so repeated runs produce identical reflections. +* jfjoch_process: Judge systematic absences by resolution-normalised intensity instead of I/sigma alone, so screw axes are no longer missed when the error model under-estimates sigma on weak axial reflections (e.g. the monoclinic 2_1 screw). +* jfjoch_process: GPU-accelerated rotation scaling and merging (RotationScaleMerge), substantially faster than the previous CPU path. +* jfjoch_process: Unify still and rotation processing on a single --force-still flag (replaces the -P partiality-model option); rotation is auto-detected from the goniometer and processed as rot3d two-pass by default, the default reflection output is mmCIF, and the experimental --reciprocal-profile option is removed. +* jfjoch_process: Add EXPERIMENTAL ice-ring detection (--detect-ice-rings) that excludes ice reflections from scaling. +* jfjoch_broker: The Bragg integration model (profile-fit Gaussian, empirical, or box-sum) is now selectable via the REST API (/config/bragg_integration) and the web frontend. +* jfjoch_broker: Write smargon chi/phi goniometer positions to NXmx; read sensor thickness/material from HDF5 metadata. +* jfjoch_writer: Don't write empty grid-scan position arrays when the dataset has no images. +* Compression: Add BSHUF_ZSTD_RLE_HUFF, make compression size-aware (drop frames that don't fit rather than aborting), and add the jfjoch_recompress tool. +* jfjoch_viewer: Report "Multiple lattices detected" and grey out "Analyze dataset" on a live connection. +* jfjoch_viewer: Frontend fixes - detector settings widget, panel/preview overflow, and navigation icons. +* CI: Build Windows (CUDA and non-CUDA) installers. +* CI: Ship jfjoch_viewer to the release as a Linux-agnostic .tgz. + +### 1.0.0-rc.155 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* jfjoch_process: Remove pixelrefine option (replaced with ProfileIntegrate2D) +* jfjoch_viewer: Some graphical improvements. +* jfjoch_viewer: Simplify and unify data analysis settings. +* jfjoch_writer: Add TCP keepalive to increase robustness if jfjoch_broker "dies" in the middle of data acquisition. + +### 1.0.0-rc.154 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* jfjoch_broker: Fix to TCP file pusher (remove kernel zero copy to improve reliability) + +### 1.0.0-rc.153 +This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use. + +* jfjoch_broker: Add EXPERIMENTAL pixelrefine mode for image processing +* jfjoch_broker: Allow to load user mask from 8-bit and 16-bit TIFF files +* jfjoch_broker: Add ROI calculation in non-FPGA workflow +* jfjoch_broker: Fixes to TCP image pusher +* jfjoch_broker: Remove NUMA bindings +* jfjoch_broker: Improvements to indexing +* jfjoch_broker: For PSI EIGER, trimming energies are taken from the detector configuration (now compulsory) instead of hardcoded values +* jfjoch_writer: Save ROI definitions and the per-pixel ROI bitmap in the master file; azimuthal ROIs support phi (angular) sectors +* jfjoch_viewer: Major redesign with dockable panels and saved layouts, plus on-canvas creation/move/resize of box, circle and azimuthal ROIs +* jfjoch_viewer: Run jfjoch_process reprocessing jobs from inside the GUI and overlay per-run results + +### 1.0.0-rc.152 +* jfjoch_broker: Fix bounds for azimuthal integration for Q spacing (allow Q of 1e-5) +* jfjoch_viewer: Adjust Q bounds for azimuthal integration +* jfjoch_azint: Add tool to do quick azimuthal integration + +### 1.0.0-rc.151 +* jfjoch_broker: For PSI EIGER detector allow to disable individual half-modules by putting empty hostname + +### 1.0.0-rc.150 +* jfjoch_broker: When in FPGA workflow (with PSI detectors) azimuthal integration might be forced to CPU - this will require more computational power, but it enables more integration bins and reports standard deviation of each bin. +* jfjoch_broker: Raise error if one is in FPGA flow and there are too many azimuthal integration bins. + +### 1.0.0-rc.149 +* XDS plugin: Fix HDF5 mutex to run on multiple processors + +### 1.0.0-rc.148 +This is an UNSTABLE release. The release has significant modifications for data processing - in case of troubles go back to 1.0.0-rc.144. + +* jfjoch_broker: Improve azimuthal integration (add calculation) +* jfjoch_broker: Fixes around indexing, aiming to handle multi-lattice crystals (work in progress, it is not fully integrated) +* jfjoch_writer: Save mean(I), stddev(I), and count(I) for each azimuthal bin + +### 1.0.0-rc.147 +This is an UNSTABLE release. The release has significant modifications for data processing - in case of troubles go back to 1.0.0-rc.144. + +* CI pipeline builds software with x86_64-v3 architecture, it should be compatible with practically all x86 hardware manufactured after 2015. +* jfjoch_viewer: Add reciprocal space viewer +* jfjoch_process: Two pass algorithm that does spot finding/indexing + integration of full dataset +* jfjoch_process: Improve logic for rotation indexer, to make execution more deterministic (still work in progress) + +### 1.0.0-rc.146 +This is an UNSTABLE release. The release has significant modifications for data processing - in case of troubles go back to 1.0.0-rc.144. + +* jfjoch_broker: Add a lattice-orientation-only refinement option, in addition to full refinement (beam center, lattice orientation, lattice dimension) +* jfjoch_process: Generate a dedicated file (_process.h5), which can be used as a replacement for the _master.h5 file for a reanalyzed dataset. +* jfjoch_process: Improve the performance of scaling and merging, implement on the fly scaling. +* jfjoch_writer: All final data analysis results are repopulated in the _master.h5 file. +* jfjoch_scale: Dedicated tool for rescaling/merging existing data. +* jfjoch_viewer: Fix bugs where pixel labels were displayed on a wrong pixel. + +WARNING! Scaling and merging are experimental at the moment, and may not provide reasonable results for the time being. + +### 1.0.0-rc.145 +This is an UNSTABLE release. The release has significant modifications for HDF5 writing logic - in case of troubles go back to 1.0.0-rc.144. + +* **Default HDF5 writing mode is with VDS, not soft-links** - this improves DIALS compatibility and makes format more future-proof, NXmx legacy format might be phased-out in the future. +* XDS plugin: Improve performance of VDS reading. +* jfjoch_writer: Significant improvement on how file systems I/O are handled through a dedicated pass-through VFD. +* jfjoch_writer: Clean-up of HDF5 routines to better handle issues. + +### 1.0.0-rc.144 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Improve performance of preview JPEG image generator at receiver startup (saving about 150 ms on measurement start for 16M) + +### 1.0.0-rc.143 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Avoid copying gain calibration together with DiffractionExperiment + +### 1.0.0-rc.142 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* Support for newer CUDA architectures (notably Blackwell); minimum CUDA version 12.8 +* Minor changes to jfjoch_process, jfjoch_fpga_test and jfjoch_lite_perf_test to make them more consistent + +### 1.0.0-rc.141 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Azimuthal integration mapping is generated with parallel computations, significantly reducing setup times +* frontend: Fix selection of FFTW in indexing settings + +### 1.0.0-rc.140 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: For DECTRIS detectors, ZeroMQ link is persistent, to save time for establishing new connection +* jfjoch_broker: Minor bug fixes for rare conditions +* jfjoch_process: Significantly improve performance + +### 1.0.0-rc.139 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Further reduce startup time for DECTRIS detectors by selectively modifying SIMPLON parameters on `/start` +* jfjoch_broker: Further reduce startup time for DECTRIS detectors by not setting beam center and detector distance via SIMPLON API on '/start' +* jfjoch_broker: Add an extra message to ZeroMQ puller ready to monitor Lite workflow preparation time +* jfjoch_broker: Image buffer configuration is postponed for Lite receiver flow till start message is received +* jfjoch_broker: Use nanoseconds internally for frame/image/readout time +* jfjoch_broker: Extra messages added for receiver operation (to be removed after debugging finished) +* jfjoch_broker: Improve profiling of different data analysis steps +* jfjoch_broker: Record integration reflection count +* jfjoch_broker: Fix bug where ZeroMQ preview frequency was confusing time units (micro vs. milliseconds) +* jfjoch_broker: Fix bug where '/wait_till_done' got deadlocked +* jfjoch_writer: Fix confusion between NaN and zero in floating-point datasets + +**Breaking changes**: detector definition is now using nanoseconds to define minimum frame time, minimum count time and readout time. + +### 1.0.0-rc.138 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Cleanup DECTRIS start-up code to enable a shorter start time +* jfjoch_broker: Allow for asynchronous start to allow overlapping detector configuration with other beamline preparations +* jfjoch_broker: Goniometer axis name is converted to lowercase +* jfjoch_broker: Fix bug, where wrong HTTP error codes were returned +* jfjoch_process: Improve sigma estimation during merging (K. Takaba) +* jfjoch_process: Modify spot finding thresholds + +### 1.0.0-rc.137 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Better track time for each operation in the processing stack +* jfjoch_broker: Rewrite preprocessing of diffraction images in the non-FPGA workflow to better use GPUs (work in progress) +* jfjoch_broker: Remove ROI calculation in the non-FPGA workflow (work in progress) +* jfjoch_viewer: Toolbar displays image number starting from 1 (instead of 0) + +### 1.0.0-rc.136 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Improve logic regarding indexing architecture and thread pools (work in progress). + +### 1.0.0-rc.135 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* Multiple small bug fixes scattered across the whole code base. (detected with GPT-5.4) +* jfjoch_viewer: Improve image render performance + +### 1.0.0-rc.134 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Add better locking for detector object - should help, when detector initialization takes too long +* jfjoch_writer: Enable writing single, integrated HDF5 file with both data and metadata +* XDS plugin: Add generation of Jungfraujoch plugin for XDS +* CI: Add tests with XDS and DIALS (`xia2.ssx`) + +### 1.0.0-rc.133 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.132. + +* jfjoch_broker: Use httplib for HTTP server instead of Pistache +* jfjoch_broker: Drop OpenSSL support +* jfjoch_broker: Base work for multi-lattice support in the future +* jfjoch_broker: Improve recording time of data analysis steps +* jfjoch_writer: Save per-image information about data analysis timing +* Update dependencies to more recent versions (spdlog, HDF5, Catch2, httplib) + +### 1.0.0-rc.132 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124. + +* Documentation: Fix equation rendering + +### 1.0.0-rc.131 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124. + +* jfjoch_broker: Fix bug in saving JUNGFRAU calibration (pedestal/pedestalRMS) +* jfjoch_viewer: Fix calibration (pedestal) images being open flipped +* jfjoch_process: Add space group detection (EXPERIMENTAL) + +### 1.0.0-rc.130 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124. + +* jfjoch_broker: Rotation indexer has two retries if it fails +* jfjoch_broker: Rotation indexer handles small number of rotation images (like test shot) +* jfjoch_broker: Integration calculates background mask based on R2 radius +* jfjoch_process: HDF5 files are not saved by default + +### 1.0.0-rc.129 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124. + +* jfjoch_broker: Significant improvements in TCP image socket, as a viable alternative for ZeroMQ sockets (only a single port on broker side, dynamically change number of writers, acknowledgments for written files) +* jfjoch_broker: Delta phi is calculated also for still data in Bragg prediction +* jfjoch_broker: Image pusher statistics are accessible via the REST interface +* jfjoch_writer: Supports TCP image socket and for these auto-forking option + +### 1.0.0-rc.128 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124. + +* jfjoch_broker: Handle properly reuse of image buffer locations +* jfjoch_broker: Fix bug in counting idle slots +* jfjoch_broker: Force obtuse angle for monoclinic cells +* jfjoch_process: Change scaling refinement tolerance + +### 1.0.0-rc.127 +This is an UNSTABLE release. The release has significant modifications and bug fixes, if things go wrong, it is better to revert to 1.0.0-rc.124. + +* jfjoch_broker: Default EIGER readout time is 20 microseconds +* jfjoch_broker: Multiple improvements regarding performance +* jfjoch_broker: Image buffer allows to track frames in preparation and sending +* jfjoch_broker: Dedicated thread for ZeroMQ transmission to better utilize the image buffer +* jfjoch_broker: Experimental implementation of transmission with raw TCP/IP sockets +* jfjoch_writer: Fixes regarding properly closing files in long data collections +* jfjoch_process: Scale & merge has been significantly improved, but it is not yet integrated into mainstream code + +### 1.0.0-rc.126 +This is an UNSTABLE release. If things go wrong with analysis, it is better to revert to 1.0.0-rc.124. + +* jfjoch_broker: Fix bug for monoclinic space groups being wrongly refined when beta is much different from 90 deg. + +### 1.0.0-rc.125 +This is an UNSTABLE release. This version adds scaling and merging. These are experimental at the moment, and should not be used for production analysis. +If things go wrong with analysis, it is better to revert to 1.0.0-rc.124. + +* jfjoch_broker: Improve logic on switching on/off spot finding +* jfjoch_broker: Increase maximum spot count for FFBIDX to 65536 +* jfjoch_broker: Increase default maximum unit cell for FFT to 500 A (could have performance impact, TBD) +* jfjoch_process: Add scaling and merging functionality - program is experimental at the moment and should not be used for production analysis +* jfjoch_viewer: Display partiality and reciprocal Lorentz-polarization correction for each reflection +* jfjoch_writer: Save more information about each reflection + +### 1.0.0-rc.124 +This is an UNSTABLE release. This version significantly rewrites code to predict reflection position and integrate them, +especially in case of rotation crystallography. If things go wrong with analysis, it is better to revert to 1.0.0-rc.123. + +* jfjoch_broker: Improve reflection position prediction and Bragg integration code. +* jfjoch_broker: Align with XDS way of calculating Lorentz correction and general notation. +* jfjoch_writer: Fix saving mosaicity properly in HDF5 file. +* jfjoch_viewer: Introduce high-dynamic range mode for images +* jfjoch_viewer: Ctrl+mouse wheel has exponential change in foreground (+/-15%) +* jfjoch_viewer: Zoom-in numbers have better readability + +### 1.0.0-rc.123 +This is an UNSTABLE release. + +* jfjoch_broker: Use newer version of Google Ceres for (potential) CUDA 13 compatibility +* jfjoch_broker: Improve performance of generating preview images, especially for large detectors (9M-16M) +* jfjoch_viewer: Improve performance of displaying images, especially for large detectors (9M-16M) +* jfjoch_viewer: Add more color schemes for better image readability +* HDF5: Common mutex for reading and writing HDF5 if both operations were to happen in the same executable +* HDF5: suppress warning if path (upstream group) doesn't exist when checking if leaf exists + +### 1.0.0-rc.122 +This is an UNSTABLE release. + +* jfjoch_broker: Add thresholding to prefer shorter vectors after FFT +* jfjoch_broker: Add experimental mosaicity estimation for rotation experiments (this is work in progress) +* jfjoch_broker: Update nlohmann::json to 3.12.0 +* jfjoch_viewer: Display file opening errors +* jfjoch_viewer: When loading files over DBus add retry/back-off till the file is available + +### 1.0.0-rc.121 +This is an UNSTABLE release. + +* jfjoch_broker: Report changes in the image buffer, so viewer doesn't reload constantly +* jfjoch_viewer: Improve performance of loading images +* jfjoch_viewer: Auto-throttle image loading in HTTP-sync / movie modes +* jfjoch_viewer: Auto-foreground calculated with histogram +* jfjoch_viewer: Fix rare segmentation fault + +### 1.0.0-rc.120 +This is an UNSTABLE release. + +* jfjoch_broker: Improve performance of binary plot export + +### 1.0.0-rc.119 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_broker: Add binary export of data analysis plots over OpenAPI +* jfjoch_broker: Minor fixes to HTTP error handling +* jfjoch_viewer: Prefer binary plots over JSON plots +* jfjoch_viewer: Change foreground with F button + wheel +* jfjoch_viewer: Change way how angles are displayed +* jfjoch_viewer: Display resolution of the mouse cursor in top left corner + +### 1.0.0-rc.118 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_viewer: Fix issue when HTTP sync silently disconnected when it was enabled when the broker was starting measurement. +* jfjoch_broker: Add protections on time of geometry optimization and reduce rotation recalculations + +### 1.0.0-rc.117 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_viewer: Add ROI results to the dataset info plots +* jfjoch_writer: Remove HTTP interface, as it is not needed/used at the moment + +### 1.0.0-rc.116 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_viewer: Add binning options in the context menu + +### 1.0.0-rc.115 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_broker: Default spot finding settings can be configured via config JSON +* jfjoch_viewer: FFT analysis of data in the dataset plot + +### 1.0.0-rc.114 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_broker: Fix generating JPEG images with resolution estimation + +### 1.0.0-rc.113 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_broker: Improve handling of rotation indexing +* jfjoch_broker: More information saved in CBOR end message (WIP) +* jfjoch_writer: Save rotation indexing lattice parameters and Niggli class +* jfjoch_viewer: Remove (for now) primitive cell information +* jfjoch_viewer: Use angle for dataset info plot for rotation scans + +### 1.0.0-rc.112 +This is an UNSTABLE release and not recommended for production use (please use rc.111 instead). + +* jfjoch_broker: Experimental rotation (3D) indexing +* jfjoch_broker: Minor fix to error in optimizer potentially returning NaN values + +### 1.0.0-rc.111 +This is an UNSTABLE release. + +* jfjoch_viewer: Remove 3D lattice viewer (not really useful at this moment) +* jfjoch_viewer: Fix auto contrast not refreshing image + +### 1.0.0-rc.110 +This is an UNSTABLE release. + +* jfjoch_broker: Add auto-contrast option for preview images +* Frontend: Add logo image +* jfjoch_viewer: Add logo image +* jfjoch_viewer: For image chart allow to set min value to zero +* jfjoch_viewer: For resolution estimation plots, visualization uses 1/d^2 as measure +* jfjoch_viewer: Add 3D unit cell visualization (experimental/WIP/not really there) +* Documentation: Add logo image + +### 1.0.0-rc.109 +This is an UNSTABLE release. + +* jfjoch_viewer: Add keyboard shortcuts and option to copy image to clipboard +* jfjoch_broker: Fix bit-width and exposure time for PSI EIGER detectors + +### 1.0.0-rc.108 +This is an UNSTABLE release. + +* jfjoch_viewer: Fix bug when resolution estimation/B-Factor/Profile radius were not set (NaN) +* jfjoch_viewer: Show spots is off by default, resolution ring mode is enabled by default +* jfjoch_viewer: Fit to window of image is now default when size of the grid changes + +### 1.0.0-rc.107 +This is an UNSTABLE release. + +* jfjoch_viewer: Minor polishing of new functionality +* jfjoch_broker: Use NaN for empty azimuthal bins + +### 1.0.0-rc.106 +This is an UNSTABLE release. + +* jfjoch_viewer: Allow for multiple dataset info plots +* jfjoch_viewer: Highlight current element in grid + +### 1.0.0-rc.105 +This is an UNSTABLE release. + +* jfjoch_viewer: Clean-up widgets slightly +* jfjoch_viewer: Limit right panel to 600 pixels +* jfjoch_viewer: Parse crystal symmetry type +* jfjoch_viewer: Grid scan view takes color map and can be fit to zoom + +### 1.0.0-rc.104 +This is an UNSTABLE release. + +* jfjoch_writer: Fix and improve the way grid scan geometry is saved (non-NXmx extension makes it way easier) +* jfjoch_viewer: Display grid scan results in 2D (work in progress) +* jfjoch_viewer: Improve auto-scaling on start of images (work in progress) +* jfjoch_viewer: Add B-factor and resolution estimate to the dataset info plots + +### 1.0.0-rc.103 +This is an UNSTABLE release. + +* jfjoch_viewer: Minor improvements to the viewer +* jfjoch_broker: Change behavior for modular detectors: coordinates of 0-th pixel can be now arbitrary and detector will be cropped to the smallest rectangle limited by module coordinates + +### 1.0.0-rc.102 +This is an UNSTABLE release. + +* jfjoch_viewer: Minor improvements to the viewer + +### 1.0.0-rc.101 +This is an UNSTABLE release. + +* jfjoch_viewer: Auto load is better handling change of states +* jfjoch_viewer: Fix DBus registration +* jfjoch_viewer: Handle charts better with vertical lines on hover and status bar update +* jfjoch_viewer: Calculate ROI in a more efficient way + +### 1.0.0-rc.100 +This is an UNSTABLE release. + +* jfjoch_viewer: Fix dbus registration +* jfjoch_viewer: Remove background slider for diffraction image +* jfjoch_viewer: Adjustments for 2D azimuthal image viewer + +### 1.0.0-rc.99 +This is an UNSTABLE release. + +* jfjoch_broker: Fix output during mask data collection + +### 1.0.0-rc.98 +This is an UNSTABLE release and not recommended for production use (please use rc.96 instead). + +* jfjoch_broker: For DECTRIS detectors fix dark data collection during initialization + +### 1.0.0-rc.97 +This is an UNSTABLE release and not recommended for production use (please use rc.96 instead). + +* jfjoch_broker: For DECTRIS detectors add dark data collection during initialization for bad pixel mask +* jfjoch_broker: Refactor of calibration logic for more clear code (likely to introduce problems) +* jfjoch_viewer: Add option to handle user pixel mask (experimental) +* jfjoch_viewer: More options for ROI +* jfjoch_viewer: Add window to display calibration + +### 1.0.0-rc.96 +This is an UNSTABLE release. + +* Fixes in CI pipeline +* jfjoch_broker: Remove PNG preview, no dependency on libpng +* jfjoch_writer: Fix UTC timestamp being generated wrong (mix between milli- and microseconds) +* jfjoch_viewer: Show data collection time in dataset tooltip +* jfjoch_viewer: Allow to choose the calibrant (presets for LaB6 and silver behenate) +* jfjoch_viewer: Auto foreground value +* Use external libjpeg-turbo and libtiff: simpler build stack, these are built and linked statically in automated Docker builds +* Remove OpenBLAS dependency + +### 1.0.0-rc.95 +This is an UNSTABLE release. + +* Fixes in CI pipeline +* Add git-lfs to Rocky8 docker image + +Previous releases (91-94) had a wrong FPGA image upload to Gitlab release. This is now solved. + +### 1.0.0-rc.94 +This is an UNSTABLE release. + +* FFTIndexer: Add limit on angles to avoid colinear vectors +* Docker images: Add 3D Qt +* Gitea: Fixes to the pipeline + +### 1.0.0-rc.93 +This is an UNSTABLE release. + +* CI: Fixes to Gitlab based pipeline +* PCIe driver: Fix PCIe revision being hex number + +### 1.0.0-rc.92 +This is an UNSTABLE release. + +* jfjoch_broker: Fix code that predicted Bragg reflections scattering back from the sample. + +### 1.0.0-rc.91 +This is an UNSTABLE release. This release introduces new features, which usually means these need more field testing before enough maturity. +For production use we recommend waiting for a future bug-fix release. + +* FPGA: Implement high pixel value threshold - pixels above the given value will be considered saturated +* jfjoch_broker: Spot finding and integration predictions are ported to a GPU +* jfjoch_broker: Estimate resolution +* jfjoch_broker: Lattice search +* jfjoch_broker: Many more improvements in image analysis + +### 1.0.0-rc.90 +This is an UNSTABLE release. + +* jfjoch_broker: for indexing min index spots for a viable cell can be changed via OpenAPI +* jfjoch_viewer: Optional auto-reanalyze images +* jfjoch_writer: Add option where no files at all are saved +* Documentation: improvements + +### 1.0.0-rc.89 +This is an UNSTABLE release. + +* jfjoch_broker: Fix resolution estimation code +* jfjoch_broker: Fix Wilson B-factor calculation code +* jfjoch_viewer: Improve display of plots +* jfjoch_viewer: Fix segmentation fault +* jfjoch_viewer: Display missing metadata when using HTTP +* jfjoch_viewer: Fix bug when opening the same file twice + +### 1.0.0-rc.88 +This is an UNSTABLE release. + +* jfjoch_viewer: Add resolution estimation to the image information +* jfjoch_broker: Minor changes to resolution estimate routine + +### 1.0.0-rc.87 +This is an UNSTABLE release. + +* jfjoch_viewer: Display more image metadata (angle / exposure time) +* jfjoch_viewer: Improve I/sigma and B-factor plots +* jfjoch_broker: Estimate resolution based on visible spots + +### 1.0.0-rc.86 +This is an UNSTABLE release. + +* jfjoch_broker: Update logic when initializing detector to make it a bit more resilient +* Gitea pipelines have nocuda option for all architectures + +### 1.0.0-rc.85 +This is an UNSTABLE release. + +* jfjoch_viewer: When using online view, dataset info plots are not switched back to the first category for each image +* jfjoch_viewer: Handle spot count better in dataset info plots +* jfjoch_viewer: Highlight spots in ice ring resolutions in cyan, when detection is enabled + +### 1.0.0-rc.84 +This is an UNSTABLE release. + +* jfjoch_broker: Write in log which detector is being initialized +* Changes to automated build system + +### 1.0.0-rc.83 +This is an UNSTABLE release. + +* jfjoch_viewer: Fix in generating preview image for signed data (wrong bit-width was assumed before) +* CI: Fix script to generate python client + +### 1.0.0-rc.82 +This is an UNSTABLE release. + +* jfjoch_viewer: Enable FFTW based indexing in viewer (very slow at the moment) +* Frontend: Minor fixes +* Build scripts: Minor fixes to FFTW + +### 1.0.0-rc.81 +This is an UNSTABLE release. This release introduces new features, which usually means these need more field testing before enough maturity. +For production use we recommend waiting for a future bug-fix release. + +* jfjoch_broker: Add option to detect ice rings, adjust width of ice ring and change of logic to exclude ice rings in indexing +* jfjoch_broker: Add FFTW based indexer for CPU only indexing +* jfjoch_broker: Enable saving X-ray fluorescence spectra +* jfjoch_writer: Write total spot count (before filtering) +* jfjoch_viewer: Add more information on source, sample, and button to show ice rings +* jfjoch_viewer: Enable data processing inside the viewer + +CI: Moving from Gitlab to Gitea at PSI + +### 1.0.0-rc.80 +This is an UNSTABLE release. + +* jfjoch_broker: Fix bug when wrong value for a plot (NaN or infinity) would lead to a null in a plot, which cannot be parsed by viewer + +### 1.0.0-rc.79 +This is an UNSTABLE release. + +* jfjoch_viewer: Fix bug when loading new dataset was creating a cascade of signals leading to poor performance +* jfjoch_writer: Save nimages_per_trigger in detectorSpecific + +### 1.0.0-rc.78 +This is an UNSTABLE release. + +* jfjoch_viewer: Using a single event loop (reading images is not in dedicated thread anymore) + +### 1.0.0-rc.77 +This is an UNSTABLE release. + +* jfjoch_viewer: Display detector and dataset settings with tooltips +* jfjoch_viewer: Clean excessive HDF5 warnings +* jfjoch_viewer: Display unit cell +* jfjoch_extract_hkl: Write a tool to extract reflection intensity from a dataset + +### 1.0.0-rc.76 +This is an UNSTABLE release. + +* jfjoch_broker: Increase predicted hkl to 100.0, use lighter math to exclude too-high resolution ones +* jfjoch_broker: Use standard deviation formula to find profile radius (not the one using median) +* jfjoch_writer: Save space group number (non-NXmx addition) in addition to name +* jfjoch_viewer: Fix the bug on reading space_group as string +* jfjoch_viewer: Add missing resolution labels on rings +* jfjoch_viewer: Remove Q value from the status bar + +### 1.0.0-rc.75 +This is an UNSTABLE release. + +* jfjoch_broker: EIGER2 missing minimum threshold - hardcoded to 2.7 keV for the time being + +### 1.0.0-rc.74 +This is an UNSTABLE release. + +* jfjoch_broker: Fix for EIGER UDP port settings (vertical half of the module missing) +* jfjoch_broker: Detector settings were not applied for EIGER/DECTRIS detector when changed after initialization + +### 1.0.0-rc.73 +This is an UNSTABLE release. + +* jfjoch_broker: Space group number treatment in OpenAPI was wrong, zero value is no longer allowed and no longer default + +### 1.0.0-rc.72 +This is an UNSTABLE release. +This release introduces new features, which usually means these need more field testing before enough maturity. +For production use we recommend waiting for a future bug-fix release. + +* jfjoch_broker: Refactor of indexing and geometry refinement code +* jfjoch_broker: Handle space group/centering in refinement code +* jfjoch_broker: Replace mosaicity with profile radius: refining the former is difficult with still images +* jfjoch_broker: There is no longer 0.5 pxl offset for spots-to-reciprocal-space conversion +* jfjoch_writer: Experimental saving of reflections +* jfjoch_writer: Save space group name as string +* jfjoch_viewer: Add profile radius and B-factor +* jfjoch_viewer: Show 4 digits for wavelength +* jfjoch_viewer: Match rings between calibrant and observation (will handle missing/wrong rings) +* FPGA: Use UDP destination port to distinguish between detector modules and data streams +* FPGA: Add experimental PTP core (PTP over L2, only Sync/Follow_up) +* FPGA driver: Fix for Linux kernel 6.12+ (thanks to Tim Gruene) + +### 1.0.0-rc.71 +This is an UNSTABLE release. + +* jfjoch_broker: Remove resolution estimation via machine learning +* jfjoch_broker: Harmonize code to analyze spot finding results (indexing/refinement/integration) between CPU and FPGA receivers +* jfjoch_viewer: Fix error when HDF5 files with indexing results couldn't be loaded on a machine without GPU + +### 1.0.0-rc.70 +This is an UNSTABLE release. +This release introduces new features (geometry refinement), which usually means these need more field testing before enough maturity. +For production use we recommend waiting for a future bug-fix release. + +* jfjoch_broker: Fix bug when PSI EIGER frame time was not set properly at the start of the measurement +* jfjoch_broker: Fix PONI rot2 angle rotating detector in a wrong direction (PyFAI convention is for this angle to rotate detector downwards) +* jfjoch_broker: Enable geometry refinement - first try (work in progress) +* jfjoch_viewer: Fix deadlock when opening HTTP connections +* jfjoch_viewer: Display rings as ellipses with detector tilt +* jfjoch_viewer: Add button to calibrate detector geometry based on LaB6 image +* jfjoch_writer: Save detector tilt angles (rot1, rot2, rot3) + +* Add Google Ceres a non-linear least-square optimization library to Jungfraujoch +* Add experimental detector calibration routines (for LaB6) +* Improve documentation on the ZeroMQ writer notification socket and detector geometry + +### 1.0.0-rc.69 +This is an UNSTABLE release. + +* jfjoch_viewer: Metadata can be modified for an open dataset (no option to save) +* jfjoch_viewer: Refactor multiple issues in the viewer regarding image reading code to allow for further developments +* jfjoch_viewer: Resolution rings not enabled by default +* jfjoch_broker: Handle properly PONI rotations in dataset settings though still not updated properly in the HDF5 file + +### 1.0.0-rc.68 +This is an UNSTABLE release. + +* jfjoch_broker: Temperature threshold can be changed for JUNGFRAU detector +* jfjoch_broker: Default detector settings can be configured for each detector separately +* jfjoch_broker: Refactor spot filtering code, max spot count can be modified for dataset settings +* jfjoch_broker: Refactor indexing refinement, make it the same for both FFBIDX and FFT indexing +* jfjoch_broker: Reference unit cell will be taken into account for FFT indexing to filter +* jfjoch_broker: Review PONI rotation angles and azimuthal angle conventions along with PyFAI + +### 1.0.0-rc.67 +This is an UNSTABLE release. + +* jfjoch_broker: Enable SSL +* jfjoch_broker: Wilson B-factor only provided if fit is relatively OK (R^2 > 0.3); this will be refined much more in the future + +### 1.0.0-rc.66 +This is an UNSTABLE release. + +* jfjoch_broker: Indexers operate as a thread pool +* jfjoch_viewer: Increase interval between loading images + fix too many verbose messages + +### 1.0.0-rc.65 +This is an UNSTABLE release. + +* jfjoch_broker: Print information regarding used image pushers +* jfjoch_viewer: Allow syncing with Jungfraujoch server +* OpenAPI: Clarify licensing terms in the file + +### 1.0.0-rc.64 +This is an UNSTABLE release. + +* jfjoch_broker: Fix issue in receiver light with very long preparation time for threads +* jfjoch_broker: Add verbose option +* jfjoch_broker: Don't trigger pedestal if critical settings are not changed when loading detector settings +* jfjoch_broker: Detector left in busy state when detector settings were improper +* jfjoch_viewer: Modify DBus interface to avoid loading same file and image 0 multiple times +* jfjoch_lite_perf_test: Add verbose option + +### 1.0.0-rc.63 +This is an UNSTABLE release. + +* jfjoch_broker: Save NX/NY for grid scan result +* jfjoch_broker: Add processing time to CBOR output and plot +* jfjoch_writer: Add processing time to data file + +### 1.0.0-rc.62 +This is an UNSTABLE release. + +* jfjoch_broker: Fix bug where low resolution spots were not counted properly +* jfjoch_broker: Spot count is provided prior to filtering of spots to max_spot_count +* jfjoch_broker: Add more spot count information to CBOR +* jfjoch_viewer: Fix issue with ROI drawing resulting in multiple overlapping rectangles + +### 1.0.0-rc.61 +This is an UNSTABLE release. + +* jfjoch_broker: Fix bug where FFT indexing could result in a very short or even zero length vector +* jfjoch_broker: Ice ring and indexed spot count enabled as plots and saved in grid scan results +* jfjoch_broker: High resolution limit for low res. spot counting can be adjusted + +### 1.0.0-rc.60 +This is an UNSTABLE release. + +* jfjoch_broker: Fix bug when the neural network inference client was busy and this status was never released +* jfjoch_broker: Revert the indexing threshold with distance from integer for Miller indices +* jfjoch_broker: Fix bug in scattering vector calculation, resulting in indexing not working outside 1.0 A X-ray wavelength + +### 1.0.0-rc.59 +This is an UNSTABLE release. + +* jfjoch_broker: Fix bug when broker was waiting for notification message before sending end message, resulting in deadlock. +* jfjoch_writer: Verbose option for debugging. + +### 1.0.0-rc.58 +This is an UNSTABLE release. + +* jfjoch_viewer: Fix memory leak +* jfjoch_writer: Add detector_number/serial_number to master file + +### 1.0.0-rc.57 +This is an UNSTABLE release. + +* jfjoch_broker: Fix bug when enabling ML resolution estimation was not possible +* jfjoch_viewer: "Movie" mode + +### 1.0.0-rc.56 +This is an UNSTABLE release. + +* jfjoch_broker: Fixing more bugs related to neural network inference for ML estimation + +### 1.0.0-rc.55 +This is an UNSTABLE release. + +* jfjoch_broker: Fixing minor bugs related to neural network inference for ML estimation + +### 1.0.0-rc.54 +This is an UNSTABLE release. + +* jfjoch_broker: Indexing with AUTO settings (FFBIDX if unit cell provided; FFT if not) +* jfjoch_broker: Don't remove shared memory area when deactivating detector +* jfjoch_writer: Save writer release +* jfjoch_viewer: Increase time for the messages in the status bar + +### 1.0.0-rc.53 +This is an UNSTABLE release. + +* PCIe driver: Imperfect solution for RHEL 9.5+ changes +* jfjoch_writer: Fix to angle containers for AutoProc compatibility +* jfjoch_fpga_test: Use consecutive number for devices, not interleaved + +### 1.0.0-rc.52 +This is an UNSTABLE release. + +* jfjoch_viewer: Use warmer colors to distinguish from AareGUI +* jfjoch_viewer: Minor adjustments to DBus setting image number +* jfjoch_broker: Fix in low resolution spot count plotting + +### 1.0.0-rc.51 +This is an UNSTABLE release. + +* jfjoch_broker: Send preview in PNG format +* jfjoch_broker: Provide count of spots in 50.0 - 5.0 A range +* jfjoch_broker: Provide ML resolution estimation in scan result +* jfjoch_broker: Allow removing beam center in web preview + +### 1.0.0-rc.50 +This is an UNSTABLE release. + +* The release fixes some of many bugs introduced in recent releases +* jfjoch_viewer: display predictions for indexed cells + +### 1.0.0-rc.49 +This is an UNSTABLE release. + +* jfjoch_broker: Add sample temperature (K) and ring current (mA) to metadata +* jfjoch_writer: For angle containers in NXmx add _end dataset, sample temp. and ring current + +### 1.0.0-rc.48 +This is an UNSTABLE release. + +* jfjoch_broker: fix the bug when a unit cell was not exported for a scan result. + +### 1.0.0-rc.47 +This is an UNSTABLE release. + +* jfjoch_viewer: fix dbus service path +* jfjoch_writer: fix CBF/TIFF writing + +### 1.0.0-rc.46 +This is an UNSTABLE release. + +* jfjoch_viewer: remove dependency on image analysis + +### 1.0.0-rc.45 +This is an UNSTABLE release. + +* jfjoch_broker: Detector list returns pixel size (mm) + +### 1.0.0-rc.44 +This is an UNSTABLE release. + +* jfjoch_broker: more general definition of scan result export + +Breaking changes: +* It removes additions to OpenAPI from 1.0.0-rc.43 +* It makes changes to the "unit_cell" definition in OpenAPI specs. It might be harmless in some languages and may result in errors in other implementations. + +### 1.0.0-rc.43 +This is an UNSTABLE release. + +* jfjoch_broker: Export grid scan results into a single data structure + +### 1.0.0-rc.42 +This is an UNSTABLE release. + +* jfjoch_broker: Add pixel_sum to CBOR output. +* jfjoch_broker: Changes to sigma estimation in QuickIntegrate routine +* jfjoch_writer: Save pixel_sum + +### 1.0.0-rc.41 +This is an UNSTABLE release. This release includes multiple new features, it should not be used in production at the moment. + +* jfjoch_broker: Estimate B-factor, mosaicity to evaluate crystal diffraction +* jfjoch_broker: Export GPU count via OpenAPI +* jfjoch_broker: Enable 2D azimuthal integration and PONI rotations for detector + +* FPGA: Increase the number of integration bins to 2048 + +### 1.0.0-rc.40 +This is an UNSTABLE release. This release includes multiple new features, it should not be used in production at the moment. + +* jfjoch_broker: Jungfraujoch supports grid scan metadata, including dedicated plotting schemes and NXmx structures +* jfjoch_broker: Improve metadata for rotation data collection +* jfjoch_broker: Better handling of plotting +* jfjoch_broker: FFT based indexing +* jfjoch_broker: Integration, first try, results not saved at the moment +* jfjoch_broker: Internal improvements in image handling + +* jfjoch_writer: Multiple adjustments adapt to changes in this release for new features +* jfjoch_writer: New state management model to improve clarity of error reporting + +* jfjoch_viewer: Remote control via DBus + +* Frontend: Multiple adjustments for new features +* Frontend: Grid scan plots + +WARNING! OpenAPI contains breaking changes in regard to plotting results, so care has to be taken. + +### 1.0.0-rc.39 +* FPGA: Bugfix for pixel masked for data analysis if summation was on +* jfjoch_viewer: Fix segmentation fault when cursor was outside of image + +### 1.0.0-rc.38 +* jfjoch_broker: Neural net model is not linked with C++ code due to deployment issues, it is rather distributed as python code, connected via REST +* jfjoch_broker: Neural net model can use all 4 quadrants of the detector +* jfjoch_broker: For EIGER image time can be provided through /start +* jfjoch_viewer: Add image list option +* jfjoch_viewer: Drawing circular ROIs with shift +* jfjoch_viewer: Enable image summation +* jfjoch_viewer: Image reader is significantly reworked, hopefully without affecting the viewer + +### 1.0.0-rc.37 +* jfjoch_broker: Make locking rules more flexible +* jfjoch_broker: Load mask via SIMPLON interface for DECTRIS detectors +* jfjoch_viewer: Add status bar + +### 1.0.0-rc.36 +This is an UNSTABLE release. Wait for a new version to use in a production environment. + +* jfjoch_broker: Support for Jungfraujoch Lite is enabled - software-based receiver for DECTRIS detectors (required a lot of refactoring, potentially leading to unstable code) +* jfjoch_broker: Enable Resonet support (ML-based diffraction resolution estimation) +* jfjoch_broker: Fix error in compression, where bitshuffle/LZ4 and bitshuffle/Zstd HDF5 headers were wrongly generated for 8-bit and 32-bit data +* jfjoch_writer: Increase buffering to 1000 images in the receiver +* jfjoch_writer: Images can be written as CBF or TIFF in addition to HDF5 + +### 1.0.0-rc.35 +This is an UNSTABLE release, not properly tested. Wait for a new version before using it in production. + +* jfjoch_broker: If module is delayed by more than 50 frames versus other modules, it will be ignored and receiver is not waiting. +* jfjoch_writer: Save EIGER energy threshold +* jfjoch_writer: Add `/entry/sample/goniometer` for compatibility with `eiger2cbf` program + +### 1.0.0-rc.34 +This is an UNSTABLE release - introducing new features, but not properly tested. Wait for a new version before using it in production. + +* jfjoch_broker: More consistency for file format definition (breaking change in API from 1.0.0-rc.31 for file writer settings) +* jfjoch_broker: For storage cells mask is logical sum of detector bad pixels for all storage cells +* jfjoch_broker: Handle situation when detector doesn't want to gracefully stop (to be tested) +* jfjoch_broker: Center-of-mass position and mean for ROI is added to available plots +* jfjoch_viewer: Can extract data analysis results from "legacy" format +* jfjoch_viewer: Display dataset name +* FPGA: Pixel mask is used for data analysis part even if it is not applied to pixels +* FPGA: Add pixel sum to module statistics +* FPGA: ROI number is reduced to 16, but pixel can belong to every defined ROI +* FPGA: Spot finder is back to full dynamic range (24-bit) +* FPGA: More debug features for internal FIFOs + +Known issues: +* ROI count flag was added to firmware. For the time being the flag will be wrongly set to 10 due to mismatch of FPGA build scripts. +* EIGER data acquisition has an issue that is currently debugged + +### 1.0.0-rc.33 +* jfjoch_broker: Fix issue with EIGER settings being loaded improperly + +### 1.0.0-rc.32 +* jfjoch_broker: Refactor code for azimuthal integration for further improvements +* jfjoch_broker: Minor fix for EIGER (trim energies are manually set for E9M, to be fixed properly later) +* jfjoch_writer: Fix too much verbose information +* FPGA: Minor fixes to spot finder (enable two-pass operation and limit number range to int20) + +### 1.0.0-rc.31 +This is UNSTABLE release - introducing many features, but still needs more testing. +Expecting soon to put bugfix release. + +* jfjoch_writer: Allow to enable overwriting existing files (not enabled by default) +* jfjoch_writer: Add new HDF5 master file format, which uses HDF5 virtual data sets and links processing results to data files (not enabled by default) +* jfjoch_viewer: Image viewer, early test version +* jfjoch_broker: Fixes to counting packets per dataset/image +* jfjoch_broker: Image buffer is accessible for outside to check images +* jfjoch_broker: error/saturated pixels and dedicated ROI "beam" can be tracked online +* jfjoch_broker: Fix bug in handling pedestal G1/G2 count time for JUNGFRAU +* jfjoch_broker: Fix bug in applying pixel mask interfering with pedestal calculation +* jfjoch_broker: Fix bug in EIGER initializing +* jfjoch_broker: Save maximum pixel value to HDF5 file and export as Web plot +* PCIe driver: Add PCIe link speed and width +* FPGA: Improve counting error/saturated/min/max pixels +* FPGA: Spot finder is gradual column-wise (15 columns up/down) and fixed row-wise (32 pixel boxes); previously it was fixed both column- and row-wise with 32x32 pixel areas +* FPGA: Require Vivado 2022.2 + +Warning: +There are breaking changes to HDF5 file format, renaming entries regarding image storage cell number and image collection efficiency. + +### 1.0.0-rc.30 +* jfjoch_writer: replace non-blocking with blocking operation on internal queues - less likely to "lose" images within the writer + +### 1.0.0-rc.29 +* jfjoch_broker: refactor logic regarding frame time and count time for more flexibility for EIGER and JUNGFRAU +* jfjoch_broker: readout time for EIGER is 3 us and JUNGFRAU is 20 us, this can be changed in input file +* jfjoch_broker: OpenAPI interface includes more ways to provide information on the status (error/warning/info) +* jfjoch_broker: ROIs handling via OpenAPI and frontend is more user friendly + +Warning - two breaking changes to OpenAPI: +* Handling of ROIs is through `/config/roi` path only for both circle and box ROIs, paths in `/roi` are no longer accessible +* `broker_status` structure introduced in 1.0.0-rc.28 has member `message` and not `error_message` to allow +handling info/warning messages as well + +### 1.0.0-rc.28 +* jfjoch_broker: save error message for initialization and data collection and provide these with OpenAPI +* jfjoch_broker: fixed issue when in error state, response to /wait_till_done was not compliant with OpenAPI specs +* jfjoch_test: remove header that failed when CUDA is absent during compilation +* frontend: add soft trigger button in data collection tab +* frontend: show error message when in error state +* CMake: add option to force compilation without CUDA (-DJFJOCH_USE_CUDA=OFF) + +### 1.0.0-rc.27 +* jfjoch_broker: add option to select electron source in instrument metadata, adapt wavelength calculation +* jfjoch_broker: update pistache web server version +* jfjoch_writer: minor changes to republish logic +* Improvements to documentation + +### 1.0.0-rc.26 +* jfjoch_broker: implement ZeroMQ stream for image metadata information +* jfjoch_broker: refactor ZeroMQ stream for preview: start/end messages always sent +* jfjoch_broker: add crystal lattice plots +* jfjoch_broker: remove empty bins from the plots +* jfjoch_broker: Fix bugs in ModuleSummation and MXAnalyzer for CPU "long" summation +* jfjoch_broker: Fix bug when mean background estimation / indexing rate were affected by previous experiment +* jfjoch_writer: fix missing "-w" parameter +* jfjoch_writer: temporary files have ".tmp" suffix +* jfjoch_writer: refactor logic for watermarks +* jfjoch_writer: report on internal FIFO utilization +* jfjoch_writer: clean-up naming for azimuthal integration and background estimate +* jfjoch_writer: write final background estimate and indexing rate in the master file +* tools/: remove unnecessary tools, make naming consistent +* CBOR: Add indexing rate and background estimate to end message +* CBOR: Clean-up documentation + +### 1.0.0-rc.25 + +* Updates to documentation +* License set to GPLv3 / OHL-S +* Fix bug in DiffractionExperiment::GetDefaultPlotBinning() - resulting in division by 0 if image time longer than 500ms +* Add information on JUNGFRAU conversion and geometry transformation to CBOR and HDF5 + +### 1.0.0-rc.24 + +New FPGA functionality: +* EIGER supports 8, 16 and 32-bit data input (for 8-bit mode at half performance; for 32-bit "real" depth is 23-bit + 1-bit signed) +* Output possible to 8, 16 and 32-bit data +* Threshold is applied before summation +* Pixel mask can be applied on FPGA +* Mark pixels with ADC content = 0 as bad pixels +* FPGA stores semantic version information (access via /sys/class/misc/jfjoch.../version) + +New software functionality: +* Long summation (above 256 frames) done on CPU +* Mechanism to save arbitrary data to HDF5 file +* ZeroMQ preview has option to send start message +* Rework pixel mask + add statistics displayed in web interface + +Bug fixes: +* Web frontend: Update preview image automatically during data acquisition +* jfjoch_broker: Error handling if CUDA driver is not installed +* jfjoch_broker: Correctly update progress during pedestal +* jfjoch_broker: Provide proper error when uploaded file is not a proper TIFF +* jfjoch_action_test: enable HLS simulation + +Documentation improvement and placement in a dedicated directory diff --git a/_sources/CPU_DATA_ANALYSIS.md.txt b/_sources/CPU_DATA_ANALYSIS.md.txt new file mode 100644 index 000000000..bfc7217c1 --- /dev/null +++ b/_sources/CPU_DATA_ANALYSIS.md.txt @@ -0,0 +1,126 @@ +# CPU-side crystallographic data analysis (Jungfraujoch) + +This document describes the crystallographic algorithms implemented in Jungfraujoch for **CPU**- and **GPU**-side real‑time and near‑real‑time data analysis. + +**Scope.** The pipeline covered here comprises: + +1. geometry mapping and corrections, +2. azimuthal integration (powder/radial profiles), +3. Bragg spot finding (strong pixels → connected components → spot descriptors), +4. indexing (still and rotation modes), +5. Bravais lattice / centering inference, +6. geometry and lattice refinement, +7. reflection prediction (still and rotation), +8. Bragg integration by either 2D box summation or profile fitting (Kabsch, reference-free), +9. scaling and merging, +10. merge-level error modelling, outlier rejection and the resolution cutoff, +11. space-group determination from the merged intensities (Laue group, screw axes, glide planes, centering, the centre of symmetry), the twinning check and the translational pseudo-symmetry check, +12. auxiliary statistics (Wilson plot, ⟨I/σ(I)⟩, CC1/2, CCref), +13. amplitude estimation (French–Wilson) and R-free test-set flagging, +14. optional model-based validation: rigid-body placement of a supplied model (molecular replacement where the rigid body does not place it, or for a predicted model), R-free against it, sigma_A-weighted 2mFo−DFc / mFo−DFc electron-density maps, and an anomalous difference map with the strongest anomalous sites named. +15. restrained refinement of the placed model (wherever a model is placed): rigid bodies and group B, then positions and B against a maximum-likelihood amplitude target with the dictionary's geometry, the X-ray weight chosen by R-free within geometry bounds, and the unexplained blobs of the refined difference map. + + +The reference is split into five parts, in pipeline order; the section numbers run continuously +across them and are the ones the rest of the documentation cites. + +- [From images to spots (§0–§3)](CPU_DATA_ANALYSIS_IMAGE.md) — device-side decoding, geometry and + reciprocal-space mapping, azimuthal integration, spot finding. +- [Indexing and geometry refinement (§4–§7)](CPU_DATA_ANALYSIS_INDEXING.md) — FFT and fast-feedback + indexing, the lattice search, geometry refinement, post-refinement, powder calibration, and the stills + geometry with a given cell and detector modules. +- [Prediction, integration, scaling and merging (§8–§12)](CPU_DATA_ANALYSIS_INTEGRATION.md) — + reflection prediction, profile-fitted integration, scaling, merging, mosaicity and the auxiliary + statistics. +- [Space group and validation (§13–§14)](CPU_DATA_ANALYSIS_DECISIONS.md) — the space-group search, + twinning and translational pseudo-symmetry, the resolution cutoff, diffraction anisotropy, + model-based validation and molecular replacement. +- [Refinement of a placed model (§15)](CPU_DATA_ANALYSIS_REFINEMENT.md) — the maximum-likelihood target and + its FFT gradient, the scale, bulk solvent and likelihood parameters, the dictionary and its restraints + (metal sites and B included), the minimiser, the weights chosen by trial, the refined maps and their + unexplained blobs, and what is not implemented yet. + +## References + +The methods draw on, and in places reimplement, solutions from: + +- W. Kabsch, “XDS”, *Acta Cryst.* **D66** (2010), 125–132 and related XDS papers (rotation geometry, partiality, scaling concepts). +- W. Kabsch, “Integration, scaling, space-group assignment and post-refinement”, *Acta Cryst.* **D66** (2010), 133–144 (mosaicity/partiality likelihood treatment; notation such as ζ and rotation factors). +- T. A. White et al., CrystFEL method papers (spot finding, three‑ring integration, serial/still diffraction processing concepts). +- J. Kieffer & J. P. Wright, "PyFAI: a Python library for high performance azimuthal integration on GPU", *Powder Diffraction* **28** (2013), S339-S350 (detector geometry definition, azimuthal integration) +- G. Bricogne, *Proceedings of the EEC Cooperative Workshop on Position-Sensitive Detector Software (Phase III)*, LURE, Paris (1986), p. 28 (Fourier-transform indexing, proposed as a three-dimensional transform; §5 uses its one-dimensional projection form). +- I. Steller, R. Bolotovsky & M. G. Rossmann, "An algorithm for automatic indexing of oscillation images using Fourier analysis", *J. Appl. Cryst.* **30** (1997), 1036-1040 (the projection/1D-FFT autoindexing algorithm of §5). +- H. Powell, "The Rossmann Fourier autoindexing algorithm in MOSFLM", *Acta Cryst.* **D55** (1999), 1690-1695 (the MOSFLM implementation of it, whose practice is followed) +- P. Gasparotto, L. Barba, H.-C. Stadler et al., "TORO Indexer: a PyTorch-based indexing algorithm for kilohertz serial crystallography", *J. Appl. Cryst.* **57** (2024), 931-944 (the algorithm of the `ffbidx` fast-feedback indexer, §4). +- I. Křivý & B. Gruber, "A unified algorithm for determining the reduced (Niggli) cell", *Acta Cryst.* **A32** (1976), 297-298, and International Tables for Crystallography Vol. A, Table 9.2.5.1 (the Niggli reduction and the lattice-character table of §5.3/§6). +- J. E. Padilla & T. O. Yeates, "A statistic for local intensity differences: robustness to anisotropy and pseudo-centering and utility for detecting twinning", *Acta Cryst.* **D59** (2003), 1124-1130 (the L test, §13.2). +- T. O. Yeates, "Detecting and overcoming crystal twinning", *Methods Enzymol.* **276** (1997), 344-358 (the twinned intensity model and the $H$ statistic behind the twin fraction of the twin hypothesis, §13.2, §14.9). +- A. J. C. Wilson, "The probability distribution of X-ray intensities", *Acta Cryst.* **2** (1949), 318-321, and E. R. Howells, D. C. Phillips & D. Rogers, "The probability distribution of X-ray intensities. II. Experimental investigation and the X-ray detection of centres of symmetry", *Acta Cryst.* **3** (1950), 210-214 (the acentric and centric intensity distributions behind the centre-of-symmetry statistics of §13.1 and the Wilson outlier test of §13.3). +- W. H. Baur & D. Kassner, "The perils of Cc: comparing the frequencies of falsely assigned space groups with their general population", *Acta Cryst.* **B48** (1992), 356-369 (writing the centrosymmetric group where the absences cannot decide the centre, §13.1). +- R. J. Read, P. D. Adams & A. J. McCoy, "Intensity statistics in the presence of translational noncrystallographic symmetry", *Acta Cryst.* **D69** (2013), 176-183 (the native-Patterson detection of translational pseudo-symmetry, and the intensity modulation it produces, which the axial-zone screw-absence test scores against). +- A. Barty, R. A. Kirian, F. R. N. C. Maia et al., "Cheetah: software for high-throughput reduction and analysis of serial femtosecond X-ray diffraction data", *J. Appl. Cryst.* **47** (2014), 1118-1131 (peakfinder8: the per-resolution-ring background statistics of §3.2). +- A. Hennequin, B. Couturier, V. V. Gligorov & L. Lacassagne, "SparseCCL: Connected Components Labeling and Analysis for sparse images", DASIP 2019, 65-70 (the connected-component labelling of §3.4, used via ACTS/traccc). +- S. French & K. Wilson, "On the treatment of negative intensity observations", *Acta Cryst.* **A34** (1978), 517-525 (Bayesian amplitude estimation from intensities), and CCP4's ctruncate (C. Ballard & N. Stein), whose anisotropic Wilson prior §10.8 follows, cited through M. D. Winn et al., "Overview of the CCP4 suite and current developments", *Acta Cryst.* **D67** (2011), 235-242. +- A. T. Brünger, "Free R value: a novel statistical quantity for assessing the accuracy of crystal structures", *Nature* **355** (1992), 472-475 (R-free cross-validation). +- P. H. C. Eilers, "A perfect smoother", *Anal. Chem.* **75** (2003), 3631-3636, after E. T. Whittaker, "On a new method of graduation", *Proc. Edinburgh Math. Soc.* **41** (1923), 63-75 (the penalised smoother of the fulls' per-frame scale, §10.6). +- H. F. Walker & P. Ni, "Anderson acceleration for fixed-point iterations", *SIAM J. Numer. Anal.* **49** (2011), 1715-1735, after D. G. Anderson, "Iterative procedures for nonlinear integral equations", *J. ACM* **12** (1965), 547-560 (the acceleration of the per-frame scaling loops, §10.6). +- R. A. Fisher, "Frequency distribution of the values of the correlation coefficient in samples from an indefinitely large population", *Biometrika* **10** (1915), 507-521 (the z-transformation on which the correction surfaces' held-out half-set CC1/2 is compared). +- R. C. Agarwal, "A new least-squares refinement technique based on the fast Fourier transform algorithm", *Acta Cryst.* **A34** (1978), 791-809 (the gradient of the refinement target, §15). +- N. S. Pannu & R. J. Read, "Improved structure refinement through maximum likelihood", *Acta Cryst.* **A52** (1996), 659-668, and G. N. Murshudov, A. A. Vagin & E. J. Dodson, "Refinement of macromolecular structures by the maximum-likelihood method", *Acta Cryst.* **D53** (1997), 240-255 (the maximum-likelihood amplitude target and the B restraints, §15). +- V. Y. Lunin & T. P. Skovoroda, "R-free likelihood-based estimates of errors for phases calculated from atomic models", *Acta Cryst.* **A51** (1995), 880-887 (the likelihood parameters from the free set, §15). +- A. A. Vagin et al., "REFMAC5 dictionary: organization of prior chemical knowledge and guidelines for its use", *Acta Cryst.* **D60** (2004), 2184-2195 (the restraint dictionary, §15). +- P. V. Afonine et al., "Towards automated crystallographic structure refinement with phenix.refine", *Acta Cryst.* **D68** (2012), 352-367 (the weight chosen among refinements by R-free, §15). +- D. C. Liu & J. Nocedal, "On the limited memory BFGS method for large scale optimization", *Math. Program.* **45** (1989), 503-528 (the minimiser, §15). +- J. Nocedal, "Updating quasi-Newton matrices with limited storage", *Math. Comp.* **35** (1980), 773-782 (the two-loop recursion of the minimiser, §15.6). +- G. N. Murshudov, P. Skubák, A. A. Lebedev et al., "REFMAC5 for the refinement of macromolecular crystal structures", *Acta Cryst.* **D67** (2011), 355-367 (the likelihood's D from the working set and its variance from the free, and the Kullback-Leibler B restraints, §15.3, §15.5). +- P. Roversi, E. Blanc, S. Johnson & S. M. Lea, "Tetartohedral twinning could happen to you too", *Acta Cryst.* **D68** (2012), 418-424 (twin refinement with more than two domains, and the free set closed under the twin domains, §15.12). +- K. A. Sultana, I. Alexeev, I. Kursula, P. Mäntsälä, J. Niemi & G. Schneider, "Structure determination by multiwavelength anomalous diffraction of aclacinomycin oxidoreductase: indications of multidomain pseudomerohedral twinning", *Acta Cryst.* **D63** (2007), 149-159 (a six-domain twin of a monoclinic crystal on a hexagonal metric, §15.12). +- A. T. Brünger, M. Karplus & G. A. Petsko, "Crystallographic refinement by simulated annealing: application to crambin", *Acta Cryst.* **A45** (1989), 50-61 (the starting weight from the ratio of the gradients, §15.7). +- P. J. Huber, "Robust estimation of a location parameter", *Ann. Math. Statist.* **35** (1964), 73-101, and P. Charbonnier, L. Blanc-Féraud, G. Aubert & M. Barlaud, "Deterministic edge-preserving regularization in computed imaging", *IEEE Trans. Image Process.* **6** (1997), 298-311 (the robust, pseudo-Huber scale fit of the refinement's score, §15.3). +- J.-S. Jiang & A. T. Brünger, "Protein hydration observed by X-ray diffraction", *J. Mol. Biol.* **243** (1994), 100-115 (the flat bulk-solvent mask, §14.2, §15.3). +- A. Blondel & M. Karplus, "New formulation for derivatives of torsion angles and improper torsion angles in molecular mechanics: elimination of singularities", *J. Comput. Chem.* **17** (1996), 1132-1141 (the torsion derivatives, §15.5). +- M. M. Harding, "Geometry of metal-ligand interactions in proteins", *Acta Cryst.* **D57** (2001), 401-411, and "Small revisions to predicted distances around metal sites in proteins", *Acta Cryst.* **D62** (2006), 678-682, and F. Leonarski, L. D'Ascenzo & P. Auffinger, "Mg2+ ions: do they bind to nucleobase nitrogens?", *Nucleic Acids Res.* **45** (2017), 987-1004 (the metal-site distances, §15.5). +- P. Emsley, B. Lohkamp, W. G. Scott & K. Cowtan, "Features and development of Coot", *Acta Cryst.* **D66** (2010), 486-501 (unmodelled blobs, §15.9). +- M. Wojdyr, "GEMMI: A library for structural biology", *J. Open Source Softw.* **7** (2022), 4200 (model / structure-factor / map machinery used in §14; the topology, riding hydrogens and blob search of §15). +- J. P. Wright, "Experiences with GPU decompression for bitshuffle + LZ4 data", HDF5 User Group meeting (2021), and [github.com/jonwright/bslz4decoders](https://github.com/jonwright/bslz4decoders) (device-side decoding of bitshuffle+LZ4 images, §0). +- A. Thorn & G. M. Sheldrick, "ANODE: anomalous and heavy-atom density calculation", *J. Appl. Cryst.* **44** (2011), 1285-1287 (anomalous difference density read at the model's sites). +- R. Kahn, R. Fourme, A. Gadet, J. Janin, C. Dumas & D. Andre, "Macromolecular crystallography with synchrotron radiation: photographic data collection and polarization correction", *J. Appl. Cryst.* **15** (1982), 330-337 (the azimuthal polarization factor of §2.2, applied to the azimuthal profile, the Bragg intensities and the ring background the beam-stop shadow test compares against). +- R. J. Read, "Improved Fourier coefficients for maps using phases from partial structures with errors", *Acta Cryst.* **A42** (1986), 140-149 (the sigma_A formalism and the m, D weighting of the map coefficients of §14.4). +- A. Fokine & A. Urzhumtsev, "Flat bulk-solvent model: obtaining optimal parameters", *Acta Cryst.* **D58** (2002), 1387-1392 (the flat bulk-solvent model, its optimal parameters and the range they are physically meaningful over, used when scaling a model to the data in §14). +- P. V. Afonine, R. W. Grosse-Kunstleve & P. D. Adams, "A robust bulk-solvent correction and anisotropic scaling procedure", *Acta Cryst.* **D61** (2005), 850-855 (the grid search over that range that fits k_sol and b_sol, with the overall scale and anisotropic B refitted at each grid point). +- K. Shoemake, "Uniform Random Rotations", in *Graphics Gems III*, ed. D. Kirk, Academic Press (1992), 124-132 (the uniform random rotations the model-fit null of §14.5 is built from). +- G. H. Golub & V. Pereyra, "The differentiation of pseudo-inverses and nonlinear least squares problems whose variables separate", *SIAM J. Numer. Anal.* **10** (1973), 413-432, and L. Kaufman, "A variable projection method for solving separable nonlinear least squares problems", *BIT* **15** (1975), 49-57 (the scale re-fit folded into the rigid-body Jacobian of §14.8). +- Z. Otwinowski & W. Minor, "Processing of X-ray diffraction data collected in oscillation mode", *Methods Enzymol.* **276** (1997), 307-326 (reweighted, de-biased profile-fit variances). +- G. Winter et al., "DIALS: implementation and evaluation of a new integration package", *Acta Cryst.* **D74** (2018), 85-97, and J. Beilsten-Edmands et al., *Acta Cryst.* **D76** (2020), 385-399 (CC1/2 resolution cutoff, merge outlier rejection, scaling error model). +- R. H. Blessing, "An empirical correction for absorption anisotropy", *Acta Cryst.* **A51** (1995), 33-38 (absorption as spherical harmonics of the beam directions). +- P. Evans, "Scaling and assessment of data quality", *Acta Cryst.* **D62** (2006), 72-82, and P. R. Evans, *Acta Cryst.* **D67** (2011), 282-292 (POINTLESS: operator-by-operator point-group scoring, and the axial-zone screw-absence test). +- A. G. W. Leslie & H. R. Powell, "Processing diffraction data with MOSFLM" (2007), NATO Science Series II **245**, 41-51 (post-refinement practice: what is refined per image and what over a wedge). +- D. W. Moreau, H. Atakisi & R. E. Thorne, "Ice in biomolecular cryocrystallography", *Acta Cryst.* **D77** (2021), 540-554 (measured hexagonal-ice ring positions, used by the ice-ring score, the ice flagging and the ice calibrant). +- K. Röttger, A. Endriss, J. Ihringer, S. Doyle & W. F. Kuhs, "Lattice constants and thermal expansion of H2O and D2O ice Ih between 10 and 265 K", *Acta Cryst.* **B50** (1994), 644-648 (the ice Ih cell the ring positions below 1.522 Å are calculated from). +- S. Sheriff & W. A. Hendrickson, "Description of overall anisotropy in diffraction from macromolecular crystals", *Acta Cryst.* **A43** (1987), 118-121 (the overall anisotropic B tensor and its symmetry constraints), and A. N. Popov & G. P. Bourenkov, "Choice of data-collection parameters based on statistic modelling", *Acta Cryst.* **D59** (2003), 1145-1153 (the sigma-aware estimation of the anisotropy of the observed intensity distribution, part of that paper's statistic modelling). +- I. J. Tickle, C. Flensburg, P. Keller, W. Paciorek, A. Sharff, C. Vonrhein & G. Bricogne, STARANISO (2016), Global Phasing Ltd, [staraniso.globalphasing.org](https://staraniso.globalphasing.org/cgi-bin/staraniso.cgi) (the inspiration for analysing and reporting diffraction anisotropy on every run, §13.5). +- C. Vonrhein, C. Flensburg, P. Keller et al., "Data processing and analysis with the autoPROC toolbox", *Acta Cryst.* **D67** (2011), 293-302 (the inspiration for not trusting header geometry and for finding the beam centre from the images, §1.4). +- P. R. Evans & G. N. Murshudov, "How good are my data and what is the resolution?", *Acta Cryst.* **D69** (2013), 1204-1214 (AIMLESS: the anisotropic deltaB as the range of the principal components, and diffraction limits from a cone about each principal direction). +- G. Assmann, W. Brehm & K. Diederichs, "Identification of rogue datasets in serial crystallography", *J. Appl. Cryst.* **49** (2016), 1021-1028, and G. M. Assmann, M. Wang & K. Diederichs, *Acta Cryst.* **D76** (2020), 636-652 (XDSCC12: sigma-tau CC1/2, delta-CC1/2, the Fisher transformation and the rejection discipline the frame disposition follows). +- W. Brehm & K. Diederichs, "Breaking the indexing ambiguity in serial crystallography", *Acta Cryst.* **D70** (2014), 101-109 (serial stills without a reference: each crystal put into the indexing in which it agrees best with all the others). +- K. Diederichs & P. A. Karplus, *Nat. Struct. Biol.* **4** (1997), 269-275, and P. A. Karplus & K. Diederichs, *Science* **336** (2012), 1030-1033 (R_meas / R_pim, CC1/2 and CC\*). +- M. S. Weiss, "Global indicators of X-ray data quality", *J. Appl. Cryst.* **34** (2001), 130-135 (R_pim). +- IUCr Commission on Crystallographic Nomenclature, "Statistical descriptors in crystallography", *Acta Cryst.* **A45** (1989), 63-75, and *Acta Cryst.* **A51** (1995), 565-569 (uncertainty conventions). +- J. Navaza, "AMoRe: an automated package for molecular replacement", *Acta Cryst.* **A50** (1994), 157-163 (the rotation function on an interpolated molecular transform, §14.10). +- R. A. Crowther & D. M. Blow, "A method of positioning a known molecule in an unknown crystal structure", *Acta Cryst.* **23** (1967), 544-548 (the full-symmetry translation function, §14.10). +- B. W. Matthews, "Solvent content of protein crystals", *J. Mol. Biol.* **33** (1968), 491-497, and K. A. Kantardjieff & B. Rupp, "Matthews coefficient probabilities", *Protein Sci.* **12** (2003), 1865-1871 (how many copies the cell holds, §14.10). +- R. J. Read, "Pushing the boundaries of molecular replacement with maximum likelihood", *Acta Cryst.* **D57** (2001), 1373-1382; A. J. McCoy, R. W. Grosse-Kunstleve, L. C. Storoni & R. J. Read, "Likelihood-enhanced fast translation functions", *Acta Cryst.* **D61** (2005), 458-464; A. J. McCoy et al., "Phaser crystallographic software", *J. Appl. Cryst.* **40** (2007), 658-674; A. J. McCoy et al., *Proc. Natl. Acad. Sci. USA* **114** (2017), 3637-3641 (the likelihood target, the solution criterion and the expected gain of molecular replacement, §14.10). +- R. D. Oeffner, T. Croll, C. Millán et al., "Putting AlphaFold models to work with phenix.process_predicted_model and ISOLDE", *Acta Cryst.* **D78** (2022), 1303-1314, and J. Jumper et al., "Highly accurate protein structure prediction with AlphaFold", *Nature* **596** (2021), 583-589 (preparing a predicted model for molecular replacement, §14.10). + +- E. A. Cornish & R. A. Fisher, "Moments and cumulants in the specification of distributions", *Rev. Int. Stat. Inst.* **5** (1938), 307-320 (the Poisson quantile of the adaptive spot-finding threshold beyond the summation limit). +- R. W. Grosse-Kunstleve, "Algorithms for deriving crystallographic space-group information", *Acta Cryst.* **A55** (1999), 383-395 (from Le Page's two-folds to a conventional cell, centring and change of basis, §13.1). +- T. C. Huang, H. Toraya, T. N. Blanton & Y. Wu, "X-ray powder diffraction analysis of silver behenate, a possible low-angle diffraction standard", *J. Appl. Cryst.* **26** (1993), 180-184 (the silver behenate calibrant cell, §7.6). +- P. Trueb, C. Dejoie, M. Kobas et al., "Bunch mode specific rate corrections for PILATUS3 detectors", *J. Synchrotron Rad.* **22** (2015), 701-707 (the count-rate correction clips an over-range pixel to the cutoff, §1.7). +- D. Liebschner, P. V. Afonine, M. L. Baker et al., "Macromolecular structure determination using X-rays, neutrons and electrons: recent developments in Phenix", *Acta Cryst.* **D75** (2019), 861-877 (phenix.xtriage, the model of the twinning test, §13.2). +- V. Luzzati, "Traitement statistique des erreurs dans la détermination des structures cristallines", *Acta Cryst.* **5** (1952), 802-810 (the fall-off of $\sigma_A$ with resolution for a model's coordinate error, Luzzati's $D$, in the likelihood of a placement, §14.10). +- D. Liebschner, P. V. Afonine, A. G. Urzhumtsev & P. D. Adams, "Implementation of the riding hydrogen model in CCTBX to support the next generation of X-ray and neutron joint refinement in Phenix", *Methods Enzymol.* **634** (2020), 177-199 (the riding hydrogens, placed by GEMMI's code, §15.2). +- D. L. Theobald, "Rapid calculation of RMSDs using a quaternion-based characteristic polynomial", *Acta Cryst.* **A61** (2005), 478-480, and P. Liu, D. K. Agrafiotis & D. L. Theobald, *J. Comput. Chem.* **31** (2010), 1561-1563 (the QCP superposition behind the NCS rms criterion, via GEMMI, §15.5). +- S. S. Oren & D. G. Luenberger, "Self-scaling variable metric (SSVM) algorithms. Part I", *Management Sci.* **20** (1974), 845-862, and D. F. Shanno & K.-H. Phua, "Matrix conditioning and nonlinear optimization", *Math. Program.* **14** (1978), 149-160 (the rescaling of the L-BFGS initial inverse Hessian by the latest pair, §15.6). + +(list is not exhaustive; the full citations, with DOIs, are in [ACKNOWLEDGEMENT.md](ACKNOWLEDGEMENT.md)) + diff --git a/_sources/CPU_DATA_ANALYSIS_DECISIONS.md.txt b/_sources/CPU_DATA_ANALYSIS_DECISIONS.md.txt new file mode 100644 index 000000000..fae331bb5 --- /dev/null +++ b/_sources/CPU_DATA_ANALYSIS_DECISIONS.md.txt @@ -0,0 +1,346 @@ +# Data analysis: space group and validation (§13–§14) + +Part of the [CPU/GPU data-analysis reference](CPU_DATA_ANALYSIS.md); the section numbers are continuous across its parts. + +```{contents} On this page +:local: +:depth: 2 +``` + + +## 13. Space-group determination and merge-level decisions + +### 13.1 Space-group determination + +When no space group is supplied, a POINTLESS-like search scores Laue-group symmetry (CC of $E^2(h)$ vs $E^2(Rh)$ — the intensities normalised by the mean of their own resolution shell — plus merge self-consistency) and detects screw/centering absences from the $P1$-merged intensities. Three tests weigh a promotion to higher symmetry, all aimed at the merohedral twin, whose twin law forces non-equivalent reflections together and so mimics symmetry: + +1. **Merge self-consistency** ($\chi^2$ under the candidate group, relative to the confirmed subgroup). On its own this is not sufficient: it is a ratio to an error model that moves with the *amount* of data — the parent's systematic term grows as $\sigma$ shrinks with $1/\sqrt{N}$, while a twin's is already saturated — so its verdict depends on how much data the search saw. +2. **Error-model $b$** (the intensity-proportional systematic). A genuine symmetry step gains multiplicity without inflating $b$; merging a twin law's extra operator inflates it. This is a **rescue and never a veto**: a $\chi^2$-borderline promotion whose $b$ stays close to the confirmed subgroup's is confirmed on it, which is what recovers a genuine high-symmetry group on imperfectly-scaled data, but it cannot demote a promotion that passed. The veto it once carried was removed. It was guarded by "$H$ could not be computed", so it could only ever act where the one statistic that discriminates here is blind, and what it compared there was not a measurement but the error-model bisection's own ceiling — which made a space group depend on the compiler flags, the same source refusing a correct $P2_12_12_1$ in one build and not in the other. No bound repairs it: genuine promotions have since been measured up to 5.8 where the bound was calibrated at 1.62 against a twin at 2.1, so the two populations have swapped sides. The case it was meant to catch — a merohedral twin too sparse for $H$ — is answered below it by the added-operator $R$ gate, whose reference is the global best rather than the parent. +3. **Operator disagreement**, a sigma-free statistic $H=\mathrm{median}\,|I_1-I_2|/(I_1+I_2)$, formed as the ratio of the operators a promotion *adds* to the parent's own, measured on the same reflections. Normalising against the parent divides out the systematic floor that symmetry mates carry on real data, which varies by crystal and by operator; a median is used because a twin perturbs every pair whereas a badly-measured minority perturbs only the tail. Where a candidate has several parents of the same order, it is judged against the worst of them, since a rival subgroup can itself contain the twin laws. + +The correlation is on **resolution-normalised** intensity $E^2 = I/\langle I\rangle(\text{shell})$, normalised over exactly the reflections the correlation pairs. Both members of a symmetry pair lie at the same $|s|$, so on raw $I$ the resolution fall-off is variance shared perfectly between the two arms and appears as a positive correlation for *any* pairing at all: a shell-matched random pairing — the exact null for a metrically-allowed false operator — scores a median 0.31 across the rotation battery, and on one crystal 0.53 — above the bound the correlation is tested against. That floor varies more from crystal to crystal (spread 0.46) than the whole true/false gap is wide (0.38), so an absolute bound on the raw statistic is a different test on every crystal; and it moves with the search resolution cut, which is what made that cut a symmetry-deciding parameter. Normalised, the floor has a median of 0.015, never exceeds 0.06, and barely moves with the cut. + +Both the correlation stage and the absence tests need to know whether a reflection is **genuinely present**, and that question is asked of its *counting* significance, not of the merged $I/\sigma$. A merged $\sigma$ carries the error model's intensity-proportional term, $\sigma^2 = a\,\sigma_0^2 + (b\,I)^2$, so merged $I/\sigma$ saturates — at $\mathrm{ISa}\sqrt{n}$ for a reflection observed $n$ times, and at $\mathrm{ISa}$ exactly for one observed once. Above that knee it stops rising with the intensity: on the weakest search merge of the rotation battery the $I/\sigma$ of every decile of $E^2$ reads 1.58–1.65 against an $\mathrm{ISa}$ of 1.70, so reflections an order of magnitude apart in real intensity report the same number. A single constant applied there demands anywhere between 2.2 and 11.9 in counting significance depending on the crystal. + +The nominal cut $T$ (default 3.0) is therefore converted once, using the ISa of the merge being searched. For a reflection observed once $\sigma_\text{counting}^2 = \sigma^2 - (b\,I)^2$, so $I/\sigma_\text{counting} \ge T$ is exactly + +$$\frac{I}{\sigma} \;\ge\; \frac{T}{\sqrt{1 + (T/\mathrm{ISa})^2}}$$ + +The converted cut lies strictly below $\mathrm{ISa}$ for every $\mathrm{ISa}$, so it is always reachable by the reflection the ceiling binds hardest, and it is within 1 % of $T$ on any merge with $\mathrm{ISa} \ge 21$ — a healthy merge is left exactly where it was. Multiplicity is taken as 1 deliberately rather than estimated, for the same reason. Where the merge reports no ISa (or $b = 0$) the cut is used as it stands. + +The candidates are enumerated in **every setting the refined cell can host**, not only in the settings the International Tables call the reference one. A setting is a statement about direction — $P112_1$ puts its $2_1$ on $c$ where $P12_11$ puts it on $b$, and both are space group 4 — so a search restricted to reference settings can only ever put a screw or a centring on the axis the convention chose, whatever the data say. Two things bound the widened set. The cell's own metric is asked once, when a point group's rotation set is chosen — a set whose rotations it does not host ($\alpha=\beta=90^\circ$ for a $2$-fold on $c$) is not offered — and every setting of a chosen set is then offered without asking again, because a cell refined free after integration sits a few tenths of a degree off $90^\circ$ and asking per setting kept only the reference one; and a candidate predicting exactly the absences another candidate already predicts is dropped as the same hypothesis under a second name. A non-reference setting is additionally refused when its centring class holds no reflection in this merge, since there is then nothing to confirm it with. Because the candidates of a point group all share its rotations, this cannot raise the symmetry: it decides *which axes* carry the screws and the centring, never how many operators there are. The setting found this way is the one the *decisions* are made in. The files are then written in the ITA standard setting (as XDS and POINTLESS write it: $P2_12_12$ with the pure axis on $c$ and $a, <|E²-1|> and N(0.1), each calibrated against acentric and centric intensities simulated with the reflections' own sigmas, every reading lies in the range a Wilson population can produce, the reflections centric in both groups read centric, and the lattice excludes twinning (the metric admits no rotation beyond the Laue class and no twin-domain lattice was found), because a twinned centrosymmetric crystal reads exactly like an untwinned acentric one. Between two groups without a centre, the lowest-numbered is written. + +The Lorentz factor $\zeta$ (§8.3) governs how well a reflection can be measured, so when the spindle lies in a plane of the lattice, an operator permuting the two in-plane axes samples a different mixture of measurement qualities than one that only flips signs. The search is therefore run a second time on a merge of only the well-measured observations (`--search-min-zeta`, rotation default 0.85), both answers are reported, and **where they disagree the merge of all the observations decides**. The filter discards 40–80 % of the observations, which can starve an operator correlation the full merge confirms and can equally leave an operator confirmed that the full merge refuses, so the decision — the point group as well as the absences, which live in the weak reflections the filter removes — rests on the arm with every observation behind it. A tie (same order, different symmetry) is reported with both candidates named, for trying in molecular replacement. + +Both search merges are cut in resolution where the data stop carrying signal: the shell means of $\langle I/\sigma\rangle$ are given their best non-increasing fit (pool-adjacent-violators, weighted by shell size) and the cut is where the **fit** drops under 1. Cutting at the first single shell to dip under 1 made the cut a coin toss on a merge whose $\langle I/\sigma\rangle$ is flat near 1: one crystal was cut at 0.85 Å or 1.19 Å depending on the compiler flags, and the coarser cut left its glide zones too few absences to be judged. The fit moves only as much as its input does, and on a profile that already falls monotonically the cut is unchanged. + +Both search merges also drop the **frames whose fitted per-frame scale came out below a tenth of the run median** — the stretches where the crystal was barely in the beam. The scale enters as $1/G$, so such a frame's intensities arrive amplified tenfold or more, with their $\sigma$ amplified by the identical factor and the scale's own error nowhere in it; the production merge survives that because a reflection in the determined symmetry is measured ten or twenty times and `--reject-outliers` removes the amplified observation, but the search merges in $P1$, where a reflection has two or three observations and no majority exists to call any of them an outlier. On a crystal that repeatedly left the beam over a full turn this cost the $422$ point group outright, its operators reading $0.08$–$0.38$ on a merge that gives $\mathrm{CC}_{1/2} = 96\,\%$ in that same point group once it is assumed. Like the $\zeta$ filter, this is a filter of the search passes alone — the production merge keeps every frame. + +**Screw axes** are scored **per axial zone**, not pooled over them. The conditions on $h00$, $0k0$ and $00l$ are independent, so their log-likelihoods add, and a zone that was never measured is allowed to **abstain** rather than to argue: pooling let one unmeasured row veto a confirmed one, and it read three genuine screws as weaker than two whenever the third row was shallow. A screw is claimed when its absence evidence reaches **8 nats**. The bound is set on the zones themselves, every single-axis candidate of a battery of rotation datasets labelled against the deposited group: a false zone with no violation reads at most +4 nats, a true one from +10, and the true zones below the former bound of 20 were all short rows — a $2_1$ along a monoclinic axis of 25–30 Å reaches four to six odd reflections inside the search's resolution range, which on weak data sit at a few per cent of their row rather than at zero. Two absences clear the bound if both read below about 2 % of their row. + +**A pseudo-translation is divided out before an axial absence is judged.** A translational pseudo-symmetry (§13.2) splits the reflections into two classes by the parity of the index along the translation, one systematically strong and the other systematically weak. Where the translation is half-integer along an axis, those two classes are exactly the absent class and the control class of a screw on that same axis, so the absence test would divide one by the other and pay the suppression twice — reading a class that is present but suppressed as extinct, and buying a screw the crystal does not have. The modulation is therefore measured along each axis from the intensities themselves — per axis, not pooled, since one row can be strongly modulated while its neighbours are not — and divided out of both the absence evidence and the violation count before the screw is scored. Only order-two screws are treated this way; a three-fold with a one-third translation is left unanswered rather than answered no. + +**The violation count can be deferred to the absences, one zone at a time.** A screw candidate is refused when too many of its predicted-absent reflections read as present — but on a strong axial row near the spindle those readings need not be structure factors at all: the same reflection can read far positive at one Ewald crossing and negative at the other, the directional smear tail of the strong reflections beside it. A zone whose per-reflection absence evidence clears the claim bar may therefore stand despite its count, since the likelihood has already priced those reflections in and still reads the class as extinct. The deferral is licensed **zone by zone** — the evidence is a group-level number while the count indicts particular zones, so an overwhelming genuine zone must not pay another zone's debts — and it is not available on a zone corrected for a measured pseudo-translation, where the corrected count is the one instrument the modulation does not reach. + +**Centering** is accepted when the systematically-absent class is weak relative to the present one by *either* of two floor-independent tests: its mean signed $I/\sigma$ well below the present mean, *or* its rate of individually-significant reflections well below the present class's own significant rate. The second test covers weak and low-energy data, where a positive intensity floor (background and profile leakage) lifts the absent class's mean $I/\sigma$ well above zero and, when the present class is itself weak, carries the plain mean ratio past its bound; a false centering fails both tests, its absent class being as strong as the present one. When several centerings pass they are ranked by a **Beta-tail likelihood** rather than by a count of net absences: a count lets a centering that extinguishes many more reflections out-rank one that violates far fewer, and the likelihood weighs the violations against the class each belongs to instead. The acceptance bounds above are unchanged by that ranking. + +**A confirmed promotion that is refused is decided by the twin-immune zone of its added operators, and only where that is undecided by merging under it.** The zone (§13.2) is the one reading that does not depend on the per-frame scales or on a reference operator: read on the all-observation P1 merge where the two search arms disagree, and on the adopted group's own merge at the remerge, an index-2 promotion whose calibrated zone evidence is acentric by 20 nats stays refused — on all observations, and the first added operator is recorded as the twin law — and one whose zone is centric by 20 nats is taken. Where the zone cannot decide (a higher index, no zone reflections in the shells with signal, within the margin, or an acentric control more compressed than a perfect twin's 0.541 — something other than a twin, the overlapping spots of a long axis, then compresses the zone too and a genuine one reads acentric), the merge is asked. Every gate that refuses a *confirmed* higher point group is a **ratio** — the added operators' disagreement against the parent's, or their $R$ against the best-agreeing operator anywhere — and both references are properties of how the crystal was mounted rather than of its symmetry. A 2-fold within a degree of the spindle records its mates on the same detector pixel half a turn later, so it carries no geometry-dependent systematic at all, and by being that clean it makes every other operator look bad against it; the best-agreeing operator can also be one of the operators under test, which collapses the ratio on worse data and raises it on better. So where a promotion is confirmed and then refused, the **merge** is asked instead of the ratio. Both groups are scaled and merged over one pinned resolution range — the adopted group's own cut — and the promotion is taken only if **neither $R_\mathrm{meas}$ nor ISa gets worse**. $R_\mathrm{meas}$ is multiplicity-corrected, so folding non-equivalent reflections together has to inflate it, and the error model is refitted per merge, so ISa says whether the extra multiplicity was bought with systematic disagreement. $CC_{1/2}$ and $\langle I/\sigma\rangle$ cannot arbitrate this: both *rise* on a false promotion too. Two details the comparison turns on: the refused point group's representative is primitive and symmorphic, so the arm merged under it takes the **adopted group's centring** — merged in the bare representative, a centred crystal is handed its centring-absent class as data, which inverts the decision — and the absence stage is asked of the adopted merge, so both arms carry the same absence classes and differ by the added rotations alone. That merge no longer holds the adopted group's screw-absent axial reflections, so the higher group also **keeps the screws the adopted group decided** — among the higher candidates the merge cannot separate, the one that predicts every such axial absence is taken — rather than the lowest-numbered one, which claims none. The cost is two extra merges, and only on a run that records a refusal, which is a few in a hundred. + +**On a merge that reads twinned, the search asks the zone itself.** A twin of an index-2 subgroup by exactly the operators a promotion adds defeats every agreement gate once its fraction is high — the added operators then agree like real ones — so where the P1 merge's $\langle|L|\rangle$ lies in the partial-twin band (0.375 to 0.44), the candidate is refused when the twin-immune zone of one of its index-2 subgroups reads acentric by 20 nats. That holds for a candidate that is the whole symmetry of its lattice too: the subgroup's twin law is one of the candidate's own operators, so a crystal in 4 twinned by $k,h,\bar{l}$ is exactly such a twin of 422. Below 0.375 something other than a twin compresses the intensities, the zones with them, and they are not read. A $P3_1$ crystal twinned at $\alpha \ge 0.4$ by its 321 law, whose 32 promotion every agreement gate passed, reads −230 nats there; a body-centred crystal in 4 twinned at about 0.3, promoted to 422 at an $H$ ratio of 1.51, −58 nats. Between two candidates of the same order the one whose own two-folds carry screw absences is preferred, but an axial row whose odd class a lattice centring extinguishes is not counted where the merge reads that centring in its general reflections: on a body-centred crystal every principal row reads extinct whatever the two-folds are, which would hand 222 the tie over 4. + +**A point group's own operators must agree with each other.** A point group is the claim that all of its operators are symmetries of one crystal, and a mixture of real and false operators has a specific shape: the real ones form a subgroup — the true group's intersection with the candidate — and everything outside it is false. The gate therefore reads the operators sorted by their $R$ against the merge, finds every prefix that closes into a subgroup, and takes the largest factor by which every operator outside such a subgroup reads worse than every operator inside it; above 3.2 the candidate is refused. A genuine group whose operators merely spread over a continuum — anisotropic systematic error spreads a cubic crystal's operators twofold — has no such gap. The earlier form, worst-agreeing over best-agreeing operator, divided by an extreme order statistic and refused a genuine $432$ as soon as one of its operators happened to agree unusually well. + +**A group that holds every rotation of its lattice is refused when merging under it narrows the L-test like a twin.** Every gate above compares the added operators with a reference, and a pseudo-symmetric structure or a twin defeats them all. For a candidate that holds every rotation its lattice admits no twin law exists, so intensities merged under it that read like a twin's are not a twin. The Padilla–Yeates $L$-test is read twice on the same pairs of the $P1$ merge — as measured, and with every intensity replaced by the mean of its orbit under the candidate — and the candidate is refused where the merged $\langle|L| +angle$ reads twin-like ($0.375 \le \langle|L| +angle < 0.44$) and the averaging closed a third or more of the gap from the unmerged value to 0.375. Genuine lattice-holohedral groups close 0.01–0.25 of it. A merge reading below 0.375 is not read: nothing a twin or a false operator does reaches that, so something else compresses the intensities. + +**The lattice class is re-asked where the metric knows more.** The Bravais class comes from Niggli reduction and a lattice-character lookup (§6), and that lookup can land short of the truth or beside it: near the Niggli type-I/type-II boundary it is decided by the last digits of the refined cell, and a lattice that is nearly but not exactly hexagonal matches the hexagonal character even when no point group that class can host carries the two-folds the data actually have. Two recoveries run, both settled by the intensities. Every rotation the cell metric can host beyond the named class — read off Le Page's two-fold search on the lattice itself, which measures each rotation's obliquity in a primitive basis and owes nothing to the character table — is put to the intensities as a single operator, scored exactly as the search scores its own operators, on the same reflection population and the same $E^2$ normalisation. And where the metric group is larger than the adopted class's holohedry, the merge is reindexed into the metric group's conventional cell and the space-group search is run again there, with every gate live; the reindex is committed only where the search in the new setting confirms a strictly higher point group *and* the centring the new cell describes, so a pseudo-symmetric metric leaves the answer already in hand standing. The same bound governs the test for a centred lattice that runs after a triclinic indexing: its candidate class comes from the character table, which names a class on looser tolerances, so the test runs only where Le Page finds every rotation of that class's holohedry within the run's obliquity bound. Otherwise the intensities could confirm only a pseudo-symmetry the lattice does not host, and the question is left to the Le Page re-ask. + +### 13.2 Twinning check, and translational pseudo-symmetry + +A Padilla–Yeates $L$-test ($\langle|L|\rangle$, $\langle L^2\rangle$ — 0.500 and 0.333 untwinned, 0.375 and 0.200 for a perfect twin) and the second moment $\langle I^2\rangle/\langle I\rangle^2$ (2.0 for untwinned acentric data, 1.5 for a perfect twin) are written to the merged mmCIF as a twinning diagnostic. Both are taken on intensities divided by their resolution-shell mean, over the shells whose intensities are measured (at least 85% of a shell's reflections at $I/\sigma > 3$, phenix.xtriage's cut for its twin tests; noise pulls $\langle|L|\rangle$ below 0.5 like a twin does), with Wilson outliers rejected; the $L$-test pairs are therefore compared on one scale even where two index steps span a steep fall-off, as in phenix.xtriage and ctruncate, and the selection is by shell, never by the individual reflection's $I/\sigma$, which would cut the weak tail and bias $\langle|L|\rangle$ down. The twin fraction is quoted from the statistic that carries the verdict — the $L$-test unless the call rests on the second moment alone — and a second moment is not turned into a fraction under a detected pseudo-translation, which inflates it. A twin law exists only where the **lattice** has a rotation the group lacks, so whether one is possible is read off the cell, not off the name of the Laue class: the lattice's two-folds are found as for the free set (Le Page, within 3° obliquity — GEMMI's `find_twin_laws`), and where none lies outside the group no twin is called. That covers the holohedral classes ($4/mmm$ on a tetragonal lattice, $6/mmm$, $m\bar{3}m$, $\bar{3}m$ on a rhombohedral one) and equally $mmm$ or $2/m$ on a lattice with no special metric, while a pseudo-merohedral $2/m$ or $mmm$ lattice — a monoclinic $\beta$ near 90°, a C-centred cell with $b \approx a\sqrt{3}$ — admits a law and stays eligible. The $L$-test is still read where no law is possible, for a different question: merging $I(h)$ with $I(Th)$ under a false operator $T$ gives $(I(h)+I(Th))/2$ whatever the twin fraction, which has the perfect-twin distribution, so $\langle|L|\rangle$ below 0.42 there is reported as **an adopted operator averaging unequal intensities** — the space group is too high, or a twin law was absorbed into the point group — a warning, never a change to the space group. A genuine operator leaves the untwinned 0.5. Reflections that overlap along a very long axis narrow the distribution the same way, which is one reason it stays a warning. The same numbers measured on the P1 merge the space-group search was given, before any point group was adopted, are reported beside them (`_BEFORE_SEARCH`), with that merge's own pseudo-translation declared and the reflections its lattice centring extinguishes left out. Between that bar and the twin band's 0.44 the verdict is `NO_TWIN_LAW`: the intensities read twin-like, but the lattice admits no law for the group, so they are not a twin in it — the group may be too high (a subgroup's twin law absorbed, or non-crystallographic symmetry taken for real), or something other than twinning narrowed the distribution. It is reported as such rather than as a twin that "needs a twin law" no refinement program could be given. + +**The twin hypothesis.** Where the adopted group may have absorbed a twin law — a twin gate of the search refused it and was overruled (§13.1), or a group above $P1$ was adopted on a merge that read twin-like before the search — the same observations are also merged in a subgroup and written beside the answer as `_twin_.mtz` / `.cif`, in the subgroup's standard setting, to the answer's resolution and with the answer's free set (each reflection takes the flag of the reflection of the answer's merge its orbit falls in, so twin mates share it). The subgroup is the one a decision named — the group a refused promotion was adopted over, or the indexed lattice's group a metric re-ask promoted from — and otherwise, among the index-2 subgroups of the adopted group that the search confirmed as point-group finalists, the one whose lost two-fold agrees worst with the intensities (lowest operator CC): the most likely twin law. One file is written; the other subgroups that qualified are named in the report. The law is in the mmCIF's `_pdbx_reflns_twin` with its fraction, from Yeates' $H$ on the pairs it relates in the subgroup merge — $H = |I(h)-I(Th)|/(I(h)+I(Th))$ is uniform on $[0, 1-2\alpha]$, so $\alpha = 1/2 - \mathrm{median}\,H$, a lower bound since measurement error only adds to $H$. Nothing the answer is made of depends on it: it is a second merge from the same scaled observations, and the answer's files are byte for byte what they are without it. Refinement programs want twinned data merged in the true lower group, never detwinned, which is why the file is the merge and not a correction of the answer; a near-perfect twin of a subgroup and the higher group predict the same intensities, so which of the two is the crystal is a question for a model (§14.9). + +Beside them, on rotation data with `--finalist-ledger`, the run reports **twin-immune zone evidence** for the operators the adopted point group adds over each of its index-2 subgroups, read on a full-resolution merge of the observations in P1 that the option makes for the purpose. Under a twin law $T$, $I_\mathrm{obs}(h)=(1-\alpha)I(h)+\alpha I(Th)$; a reflection whose twin mate is itself up to the subgroup and Friedel is untouched at every $\alpha$, and those are exactly the reflections centric in the group but acentric in the subgroup. They read centric ($\langle|E^2-1|\rangle = 0.968$) if the added operators are real and acentric (0.736) if they are a twin law or a pseudo-symmetry — the one intensity statistic that still separates the two at $\alpha = 0.5$, where every operator statistic reads "real". Each zone is normalised against its own mean in resolution bins (and within the two phase classes of a detected pseudo-translation), read only in shells with $\langle I/\sigma\rangle \ge 5$ because noise inflates every class towards centric, and reported with $n$, a standard error and the centric-over-acentric Wilson log-likelihood ratio in nats (both densities convolved with each reflection's measurement error), beside the acentric control. It is read absolutely, never as the difference to the control: a perfect twin's control (0.541) plus noise inflation would otherwise look like true symmetry. An absolute reading is only as good as the normalisation, though, and the acentric control certifies it: an acentric population reads $-0.130$ nats per reflection when the normalisation is right, and whatever the control reads above that is the normalisation's — anisotropy, a pseudo-translation, a pseudo-centring, noise all inflate every class towards centric alike — so the zone, normalised the same way, carries the same per reflection and the **calibrated** evidence has it taken off (a twinned control reads *below* the expectation, so nothing is taken off a twin). The centric side is read **twinned at the fraction the lattice's other operations show** by their own correlation — the strongest CC of a lattice rotation outside the group, relative to the mean CC of the group's own operators, inverted through $\rho = 2\alpha(1-\alpha)/((1-\alpha)^2+\alpha^2)$ — because a twin by another law reaches a genuine zone exactly as it reaches the control: a genuine 321 crystal twinned by a 622 law read its 2-folds at −206 nats against the untwinned centric density and +209 at that law's fraction of 0.07. The operators' own twin law cannot reach their zone, so the acentric side stays untwinned, and the control's expectation is taken at the same fraction. Measured, a 6/m crystal with a 67 Ų anisotropy read its control at $+0.10$ nats per reflection and the zone of a refused 622 the same, so the zone's $+124$ nats were the normalisation's; calibrated it reads $-115$, and genuine promotions keep $+200$ and above. The calibrated zone is what a refused promotion is decided on (above). It is an in-house method: published practice (Yeates' $H$-test, xtriage) excludes these reflections as uninformative about the twin fraction, and no published test was found that uses them positively; the one precedent here is a trigonal crystal whose twin-immune zone read centric and whose higher group was then confirmed by refinement. + +**Translational pseudo-symmetry** — two copies of the contents of the asymmetric unit related by a pure translation that is not a lattice vector — is looked for on every merging run, because it is the classic predictor of a failed molecular replacement, and because it raises the second moment where twinning lowers it, so each can mask the other's test. The detection is the native-Patterson route of Read, Adams & McCoy (see the [references](CPU_DATA_ANALYSIS.md#references)): the largest off-origin peak of a Patterson computed from the merged intensities over 20–5 Å, as a fraction of the origin peak, with the peak vector then refined against the intensity modulation it should produce — the correlation between $E^2$ and $\cos 2\pi\,\mathbf{h}\cdot\mathbf{u}$ over the acentric reflections beyond 4 Å (or the 2000 lowest-resolution ones where a small cell has fewer there). Both halves are scored against a null computed for the crystal at hand rather than against a fixed bound — both against the same intensities **permuted within resolution shells** — the peak against that map, the modulation against the same search made on the shuffled intensities and started where the search starts — because the noise floor of the peak statistic spans an order of magnitude across data sets, so no fixed percentage means the same thing twice. The shuffle leaves the reflection count and the $E^2$ distribution untouched and removes only the correlation between a reflection's intensity and $\mathbf{h}\cdot\mathbf{u}$, which is the thing the modulation claims to see; the shells are split by the reciprocal axis $\mathbf{h}$ lies closest to, so that anisotropy, which the spherical normalisation leaves in $E^2$ as a dependence on direction, is neither read as a modulation nor left out of the null, and the search stays 15 Å from every lattice point, where the phase would sort the reflections by exactly that direction. Re-running the greedy search from random starting vectors over the *same* intensities does not work as a control: a greedy search started anywhere walks into a real modulation's basin, so it measures the search **and** whatever modulation the crystal carries. A vector that modulates is a fact about the crystal; the **pseudo-translation reported** is the one molecular replacement has to be told about, and the programs that correct for it act on a Patterson peak of a fifth of the origin — read in the band, or as the Patterson height the modulation's depth gives at the vector, fitted over every reflection of the modulation population (undiluted by a twin; over classes averaged across the lattice's rotations it also counts the copy pairs at the other images of the vector, and reads above the Patterson at the vector itself), which on a small cell or one whose low-resolution reflections were lost to overloads is the better measure of how much of the scattering the translation relates. Below that nothing in the data tells a weak pseudo-translation from two rotated copies that look alike at 20–5 Å (over the deposited models of a 200-dataset corpus the models' own Pattersons read 18–80 % where a pseudo-translation is there and 4–15 % where it is not), and nothing downstream needs it, so it is noted and not flagged. A peak of that size the data cannot establish — a 30 Å cell has about 150 reflections in the band, where the noise floor is itself a fifth of the origin — is carried as `POSSIBLE` rather than dropped. A translation the merged data are **exactly** invariant under is reported as an undeclared lattice translation instead — a translation the data are exactly invariant under is a lattice vector by definition, so the centring or the cell is wrong, not the packing — and the pseudo-symmetry search continues underneath it, so a real pseudo-translation sitting under an undeclared centring is still found. The finding itself is report-only (the `TNCS_*` keys of `_report.txt`): it gates nothing and changes no reflection, no scale and no group — but the axial-absence test (§13.1) and the $L$-test here both correct themselves against the modulation it measures, and the vectors are carried onto the axes the files are written on when a model or a reference moves them after the analysis. + +**The $L$-test partners are chosen so a pseudo-translation cannot silence it.** The test compares each reflection with a partner a fixed index step away, and a pseudo-translation biases $\langle|L|\rangle$ upwards unless the partner shares its modulation class. The ordinary step of 2 preserves the class of a half-integer translation — the pseudo-centering the statistic's authors call it robust to — but not of one of a third, which inflates $\langle|L|\rangle$ past the bound that is read as evidence *against* twinning and silently loses the twin call on a crystal that has one. Where a pseudo-translation is detected, the partner steps are restricted to those that preserve its class; where no step does, the statistic is dropped from the twin verdict **in both directions** — it can no longer indicate a twin and can no longer be read as proof that there is none — and the second moment decides alone. `L_TEST_VS_TNCS=` in the report says which of the three happened. + +### 13.3 Outlier rejection + +Merging applies a per-observation median-based $N\sigma$ cut (`--reject-outliers`, default 6σ on rotation, 10σ on stills). On the rotation path the median is weighted by each full's counting variance taken at the reflection's **expected** intensity, as the merge weights are (§10.4): an observation's own Poisson variance falls with its own intensity, so own-variance weights hand the median to whichever equivalents came out low — on a strongly absorbing crystal, where some frames read equivalents ten to a hundred times down, the median sat on the absorbed ones and the test removed correct measurements far above it. The band about the median keeps the counting part linear, $\pm N\sigma_\text{counting}$, but takes the systematic part as a **factor**, $e^{\pm N s}$ about the expected intensity: the error model's systematic term is multiplicative — absorption, illuminated volume, a scale that is off — and as likely to be a factor $1/f$ as $f$, while a band symmetric in $I$ reaches far below the median and only a little above it once that term is large. $s$ is the spread of $\ln(I/\text{median})$ measured on the merge's own fulls (their weighted median of $|\ln(I/\text{median})|$, weighted by $(\langle I\rangle/\sigma_\text{counting})^2$ so the fulls whose ratio counting noise does not blur carry it), with the error model's $b$ as the fallback where it cannot be measured; to first order in $Ns$ the band is the linear one. The same $N\sigma$ cut is fed back into the error model: after an initial $a,b$ fit the parameters are re-fit once on the reflections that survive rejection (dropping any whose squared deviation exceeds $N^2\,[a\,\sigma^2 + (b\,\langle I\rangle)^2]$), so the calibrated errors describe the reflections that actually enter the merge rather than the pre-rejection pool. On **stills** the band is the plain linear one, $\pm N\sqrt{a\,\sigma^2 + (b\,\langle I\rangle)^2}$ about the median: a still's observations of one reflection are partials and per-crystal scales, many of them near zero, so the spread of $\ln(I/\text{median})$ is wide and a band drawn from it let through a powder grain or a neighbour's spot in the box at hundreds of $\sigma$ — on a high-multiplicity run a single such observation was a weak reflection's whole merged intensity, and they took the low-resolution shells' $\mathrm{CC}_{1/2}$ down to 0.6. The error model's $b$ is that spread as it is. $N$ is wider than on rotation because a still's partials scatter with heavier tails than the band's normal core; what has to go sits tens to hundreds of $\sigma$ out. + +The median needs three observations, so a reflection measured once or twice — typically one good observation and one artefact (a hot pixel, a zinger) after Friedel merging — is never tested by it, and an artefact that looks precise (thousands of counts, a small relative $\sigma$) can outweigh mates from weak frames and become the median itself. Every observation of the written merge is therefore also judged by **Wilson statistics**. Beyond 4 Å its $E^2 = I/(\varepsilon\,\langle I/\varepsilon\rangle_\mathrm{shell})$ is compared with a bound set by a budget of $\alpha = 0.01$ expected false rejections per dataset: with $N$ observations tested, $\ln(2N/\alpha)$ for acentrics and twice that for centrics, and the observation's lower confidence limit $I - z\sigma$ (with its own $\sigma$, and $z$ from the same budget) must exceed it, so noise in weak shells does not trigger it; a shell whose $\langle I\rangle$ is not itself established at that significance is not judged. The bound is widened by the tail scale of the dataset's own intensity distribution, measured on its well-measured observations (1 for a Wilson crystal; larger under a pseudo-translation or anisotropy). An improbable singleton is dropped; an improbable observation with company only when most of the reflection's other observations are probable and it disagrees with their mean beyond the errors — several large observations confirm each other. A Friedel mate does not confirm: an improbable observation of the exactly opposite indices is not counted as company at all. A spot of another lattice (a satellite crystal, a crystallite of salt or ice) that lands on a predicted reflection is the commonest large observation that is not the crystal's, and that lattice diffracts centrosymmetrically too: half a turn later the rotation brings $-h$ and the spot's own Friedel mate to the same mirrored detector position, so the two always arrive together and would otherwise vouch for each other. A probable Friedel mate still testifies against the observation. An observation whose signal disk lost pixels to the mask or to saturation is never counted as such a witness, since its profile estimate may be low: a strong reflection is not replaced by its clipped mate. The count is `OBSERVATIONS_REJECTED_WILSON=` in the report (included in `OBSERVATIONS_REJECTED=`), and the developer report lists each observation with its image and detector position. + +### 13.4 Automatic resolution cutoff + +By default the reported/written high-resolution limit is trimmed where $\mathrm{CC}_{1/2}$ falls off: a logistic is fitted to $\mathrm{CC}_{1/2}(s)$, and the limit is set **one tenth of the kept range in $s = 1/d$ past** the point where the fit crosses 0.30 — one shell of a ten-shell division, independent of the nine reported shells; deliberately "one shell too far", so weak-but-real data below the crossing are kept rather than discarded. The extension is measured over the range that is actually kept, not the full measured range, so a detector reaching far past where the crystal diffracts cannot inflate it. `--scaling-high-resolution` overrides the limit and `--resolution-cutoff off` disables it. + +**The fit runs on an internal, weighted $\mathrm{CC}_{1/2}$, not on the reported one.** An observation from a frame at scale $G$ below the run's typical scale $G_\mathrm{ref}$ was scaled up by $G_\mathrm{ref}/G$ and carries $(G_\mathrm{ref}/G)^2$ more counting variance than the same observation at the typical scale. On rotation each reflection's half-set pair therefore enters the fit's Pearson sums with a weight in $(0, 1]$: the variance its two half-set means would have had with every observation at the typical scale, over the variance they have. It is 1 on a sweep without a weak stretch, and small for a reflection measured only where the crystal barely diffracted, whose scaled-up noise would otherwise pull the curve down as much as a well-measured pair holds it up. The same per-frame factor sets the information each observation carries in the ΔCC1/2 frame ledger (§ frame disposition in [integration](CPU_DATA_ANALYSIS_INTEGRATION.md)), and the two-pass and beam-centre guards read this weighted form too. The **reported** $\mathrm{CC}_{1/2}$ — `CC_HALF`, `CC_STAR`, the shell tables and the mmCIF — is the standard one of XDS, Aimless and DIALS: the plain Pearson correlation of the $1/\sigma^2$-weighted half-set means, every reflection counted alike. Stills weight nothing in either. + +**Ice sits out of this fit, and only this fit.** A powder ring is reproducible: past the crystal's own limit the ice is still there and still the same in both half-sets, so the two halves agree *about the ring*, and a Pearson $\mathrm{CC}_{1/2}$ cannot tell that agreement from diffraction. Shells have been measured at $\mathrm{CC}_{1/2}=0.765$ where $\langle I/\sigma\rangle$ is $-0.1$ and $R_\mathrm{meas}$ is 470 %, inside the written range because the logistic was fitted through them; against archived references, runs whose frames carry ice were written a mean twelve per cent finer than the reference where runs without ice were written four per cent finer, and every over-claim past twenty per cent has rings. The same ring drags the curve the other way where the data are good — one shell of forty falling to 0.51 because the two strongest ice lines cross it, with the shells either side at 0.99 — which is a real defect of those reflections but narrower than the shell it defames. Both signs are the same cause and both leave the fit: the reflections flagged in §3.3 are still merged, written and counted in the shell table wherever the per-ring decision of §10.10 keeps them, and what changes is only that the resolution **decision** now reads the same curve that scaling, the error model and the space-group search already read. + +**A cut the shell table refutes is not quoted.** Two things keep the number inside what the bins show. The fitted crossing has to lie **inside the fitted bins**: on a real fall-off it sits between the last bin at the target and the first bin below it, with the extension bins to spare, and a crossing past the last fitted bin is an extrapolation of a fall-off these data never showed — the crossing is then read off the bins themselves, between the two that straddle the target. And no single resolution is quoted at all where the curve is not a fall-off: where $\mathrm{CC}_{1/2}$ never reaches the target in any shell, where the fit reads finer than the finest shell whose $\mathrm{CC}_{1/2}$ still reaches it, or where $\mathrm{CC}_{1/2}$ **climbs back over the target** after falling below it — a noise shell that climbs back is not the edge of the data. The report then says which of the three happened and points at the shell table instead. + +### 13.5 Diffraction anisotropy + +How fast the intensity falls off with resolution can depend on direction. Rugnux measures that and reports it. No intensity is corrected and no reflection is removed on a directional criterion; the one use of the tensor is the Wilson prior of the French–Wilson amplitudes (§10.8), so `F`/`SIGF` follow the fall-off along each reflection's direction while the intensities do not depend on direction at all. Treating anisotropy as something every run should analyse and report is inspired by STARANISO (see [Acknowledgements](ACKNOWLEDGEMENT.md)). + +**The tensor.** A deviatoric anisotropic displacement tensor is fitted to the merged intensities as + +$$\ln \langle I(\mathbf{s})\rangle = c(\text{shell}) - \tfrac{1}{2}\,\mathbf{s}^\mathsf{T} B\, \mathbf{s},\qquad \mathbf{s} = \text{reciprocal-space vector},\ |\mathbf{s}| = 1/d$$ + +(§10.6 and §14.2 write $s$ for $\sin\theta/\lambda = 1/2d$, so their $s^2 = 1/4d^2$; the two conventions give the same exponent $-(B/2)(1/d^2)$, and $B$ is the same $B$.) + +with one free constant per resolution shell, so every isotropic feature — the Wilson curve, an ice ring, a noise floor, a scaling error — is absorbed exactly and only the $\ell = 2$ angular part drives the tensor. For an isotropic $B$ this reduces to the ordinary Wilson plot, so $B$ here is the ordinary crystallographic ($B = 8\pi^2 U$) $B$, directly comparable with phenix.xtriage's `B_cart`, ctruncate's anisotropic $B$ eigenvalues and AIMLESS's anisotropic $\Delta B$. Only the deviatoric part is fitted: the isotropic part is degenerate with the overall scale. The tensor is constrained to the directions the Laue class allows — five free deviatoric parameters in triclinic, three in monoclinic, two in orthorhombic, one in tetragonal, trigonal and hexagonal, and **none at all in cubic**, where symmetry forces $\Delta B$ to be exactly zero. + +The fit is on **intensities, with no positivity cut**. Fitting amplitudes, or dropping non-positive intensities as an amplitude-based tool must, loses roughly 40% of the signal: in a direction that has died half the merged intensities are negative, so a positivity cut keeps only the positive noise excursions and flattens the fall-off exactly where the anisotropy is largest. + +That is not a small effect, and it is the whole of the difference from phenix.xtriage's `B_cart`. Measured over the battery against the model-free fall-off of $\langle I\rangle$ (negatives kept) in 20° cones about the principal directions: the tensor above reproduces that fall-off; xtriage's eigenvalue range is a quarter lower on a typical crystal (median ratio 1.36), and four to eight times lower on a crystal whose weakest direction stops diffracting inside the measured range — its positivity cut floors the dead direction at the noise's positive half, and its single Wilson curve over 11.2 Å to $d_\min$ averages the deficit over the shells beyond that direction's limit, so the value also shrinks as the written range extends past it (truncating one such data set at the fitted resolution raised xtriage's range by a third; a shell earlier, it doubled). Restricting the same cone fall-off to positive intensities reproduces xtriage's number. xtriage's own verdict, range over mean $B \ge 0.5$ with mean $B > 20$ (the Read et al. 2011 cutoffs), is blind on low-resolution data for a second reason: the mean $B$ it divides by is 100–180 Ų there, so a crystal whose weakest direction reaches 5.6 Å against 3.7 Å along the best scores "not significantly anisotropic". + +**The grade** — *measurable but small*, *noticeable*, *STRONG* (the warning) — is read on the directional limits, as the ratio of the weakest to the best (1.125 and 1.25), not as their spread in Å: the same spread is a 12% loss of resolution at 4 Å and a 33% one at 1.5 Å, and a spread graded every 4 Å crystal strong and a 1 Å crystal losing a third of its reach noticeable. The two ratios are the former 0.25 Å and 0.5 Å spreads read at 2 Å, so the bands keep their meaning where most data sit. The limits are the number to compare between programs: on the open-arm depositions that were processed with STARANISO, rugnux's limits reproduce the deposited ellipsoid to about 0.1 Å per axis and its axis ratio to a few per cent. + +**Two different quantities are reported, and they are not interchangeable.** $\Delta B$ (the range of the principal components) is a *rate*; the diffraction limit along each principal direction — where $\langle I/\sigma(I)\rangle$ in a 20° cone about that direction falls through 2, read by interpolation in $s^2$ over equal-count shells — is where the signal actually runs out. A crystal can have a large $\Delta B$ and almost no spread in directional limit, or the reverse. Where $\langle I/\sigma(I)\rangle$ never falls through 2 in a direction, the limit returned is the **edge of the measured data** rather than the crystal's own; such a direction is marked — with a `<` in the report, a 1 in `ANISOTROPY_D_MIN_CENSORED`, and a note in the mmCIF — so the spread is not read as a measurement when it is a lower bound. Both constants are AIMLESS's defaults (cone half-angle 20°, $\langle I/\sigma\rangle = 2$). The 2 is a per-direction diagnostic level only: the dataset-wide resolution cut (§13.4) is CC$_{1/2}$-based, and the two criteria are not interchangeable. + +**The resolution signature.** A genuine Debye–Waller $B$ makes the directional deficit a straight line through the origin in $s^2$. The per-shell $\ell = 2$ amplitude is therefore fitted against $s^2$ and the curve is classified: *linear* (a real $B$), *flat* (a deficit that does not follow $\exp(-\tfrac12 \mathbf{s}^\mathsf{T} B \mathbf{s})$ at all, so the fitted $\Delta B$ describes the data with the wrong functional form and may be an **under**-estimate), or *convex* (a deficit that grows faster than $s^2$, which a $B$ cannot do). The verdict is re-derived at 8 and at 16 shells, and reported as undetermined if it moves. + +**The verdict, and what it is measured against.** Whether an anisotropy is real is not decided against a counting-statistics error bar. Real data carry systematic error far larger than counting error, and gating on the latter reports anisotropy on datasets that have none. Instead the data set measures its own systematic error: in the tensor directions the Laue class *forbids*, the true tensor is exactly zero whatever the crystal is, so whatever is measured there is systematic. That measurement needs the unmerged observations — a merge has exact Laue symmetry by construction, and the forbidden directions are identically zero in it — so it is made on the scaled, rocking-curve-assembled observations. The counting part is subtracted, the counting error of the directions actually being tested is added back, and the result is the **floor**. What is tested against it is $\Delta B_\text{linear}$ — the part of the fall-off that actually follows $\exp(-\tfrac12\mathbf{s}^\mathsf{T}B\mathbf{s})$, clamped at zero — and **not** the headline $\Delta B$; the report names which of the two it is quoting. The ratio is banded: below 2 not established, 2–3.5 marginal, above 3.5 established, above 5 strong. The bands are calibrated against known ground truth — merging cubic crystals in proper subgroups of their own Laue class, where the true anisotropy is exactly zero — which puts the false-positive rate at 24 % at 2.0, 10 % at 3.5 and 5 % at 5.0. + +The report says **NOT DETECTED**, **DETECTED**, or **CANNOT DETERMINE**, and the third is a real answer rather than an evasion. It is returned when the Laue class is triclinic (no forbidden direction exists, so there is no internal measurement of the systematic error and no substitute for it), when the observed rotation range is under about 90° (a lab-fixed systematic then reaches several tensor directions instead of one), when the merged data are at the noise floor, when the scale model carried no dose term (an uncorrected dose ramp manufactures anisotropy that no significance test can see through), or when no unmerged observations were available. The smallest $\Delta B$ that could have been established on the data set is reported with the verdict; it is set by the systematic error rather than by counting, so it does **not** improve with more reflections or a longer exposure. + +A too-high space-group assignment is the one failure mode that is silent: real anisotropy is then pushed into the directions used to measure the systematic error, which inflates the floor and biases the answer towards reporting none. A caution says so, but only where that is actually indicated — a single free direction, no detection, **and** a forbidden-direction measurement far above its own counting noise — rather than on every tetragonal, trigonal and hexagonal data set. + +Everything lands in `_report.txt` section 4 (`ANISOTROPY_*` keys), in the printed statistics, and in the merged mmCIF: the eigen-decomposition of the tensor as the standard `_reflns.pdbx_aniso_B_tensor_*` items (relative to the weakest direction, since only the deviatoric part is determined), and the directional limits, the shape and the verdict under the `_reflns.jfjoch_aniso_*` local prefix. + +### 13.6 Practical notes and limitations + +- **Bragg integration is profile-fitted by default** (per-shell Gaussian profile, Kabsch extraction; §9.3), with plain box summation available as a fallback (`--integrator boxsum`). The profiles are built per frame from that frame's strong spots, which suits fast-feedback and serial/streaming use; a profile shared across many frames (as in full offline workflows) is not currently formed. +- **Space-group symmetry** beyond centering absences is not enforced during prediction/integration unless the space group is supplied and used downstream. +- **Resolution masking** is controllable, and so is every stage of ice-ring handling (§3.3, §10.10). None of it runs unless the crystal is measured to have ice, because the fixed bands are a fixed cost in unique reflections whether it does or not. +- **Rotation vs still modes** differ substantially in prediction and scaling: partiality is angle-driven in rotation data, while stills are predicted within an excitation-error window that follows the run's rocking curve (§8.2) and get their partiality from the default-on per-crystal tilt post-refinement (§10.2) — or unit partiality with `--simple-stills`. +- **Amplitudes and intensities.** The merged output carries both intensities (mmCIF `intensity_meas`, MTZ `IMEAN`/`SIGIMEAN`) and French–Wilson amplitudes (mmCIF `F_meas_au`, MTZ `F`/`SIGF`; §10.8), so a downstream program can refine against either. + +--- + +## 14. Model-based validation: R-free against a model and electron-density maps + +Offline (`rugnux --model model.pdb`) the merged data can be scored against a supplied atomic model and electron-density maps computed — enough to confirm that a model fits the data and to inspect the density. **The numbers of this section are those of the model as placed, not refined** - a placed model is refined afterwards by default (`--no-refine` skips it), on the side and deciding nothing (§15, [Refinement of a placed model](CPU_DATA_ANALYSIS_REFINEMENT.md)); the model is re-fractionalized into the data unit cell and then **placed as one rigid body** (§14.8) - or, where the rigid body does not place it and for a predicted model, by molecular replacement (§14.10) - and the observed amplitudes are the French–Wilson $|F|$ from §10.8, so the R-free and the maps use exactly the same amplitudes as the written reflection file. The model, structure-factor, bulk-solvent and FFT machinery is provided by GEMMI. + +### 14.1 Model structure factors + +The model electron density is sampled on a grid (IT92 X-ray form factors, with a Refmac-compatible Gaussian blur chosen for the grid spacing) and Fourier-transformed to structure factors $F_\mathrm{calc}(hkl)$ up to the data resolution. + +### 14.2 Bulk solvent and scaling + +A flat bulk-solvent mask around the model (the REFMAC radii, on the density's grid, or on one of its own at 0.75 Å where that grid is too coarse for the mask's 0.8 Å shrink to act) is transformed to $F_\mathrm{mask}$, and the model is scaled to the observed amplitudes by an overall least-squares fit of a scale $k$, an anisotropic $B$, and the flat-solvent parameters $k_\mathrm{sol}, B_\mathrm{sol}$: + +$ +F_\mathrm{model} = k\,e^{-\mathbf{h}^\top \mathbf{B}\,\mathbf{h}/4}\left(F_\mathrm{calc} + k_\mathrm{sol}\,e^{-B_\mathrm{sol}\,s^2}\,F_\mathrm{mask}\right),\quad s^2 = 1/4d^2. +$ + +This is the standard, few-parameter scaling model used by refinement programs. No free-form per-resolution-shell rescale is applied: such a rescale is dataset-specific and reshapes each map's radial amplitude profile differently, which would make maps from a multi-dataset campaign no longer directly comparable. + +That decision has a cost, and it is paid by the R-factors rather than by the maps. $k\exp(-\mathbf{s}^\mathsf{T} B \mathbf{s})$ can only bend one way with resolution, so whatever a dataset's radial amplitude profile does that this shape cannot follow is reported as R — which makes R a reading of *this* dataset and not a quantity comparable with another reduction of the same crystal. Both uses are wanted, so both are served, separately: the maps and `R_WORK` / `R_FREE` keep the scale above, and a second reading, `R_MODEL_SHELL_SCALED`, applies one free scale per resolution shell to the *same* fit and is reported beside them, with `MODEL_RADIAL_MISFIT` saying how much that rescale had to do. Nothing is written from the second reading; it never reaches a map, a map coefficient or a decision (§14.3, and RUGNUX_REPORT). + +The fit sees the **working reflections only**; the parameters it returns are then applied to every reflection, free ones included, so that R-free (§14.3) is computed against them. The parameters are few, but they are fitted by minimising the very sum R is made of, and a free reflection that helped choose them is no longer held out. + +### 14.3 R-work and R-free + +Crystallographic R-factors are reported over the work and free sets (the §10.7 flags): + +$ +R = \frac{\sum \big|\,|F_o| - |F_\mathrm{model}|\,\big|}{\sum |F_o|}, +$ + +with R-free the same sum restricted to the free set. Every parameter $F_\mathrm{model}$ carries — the scaling of §14.2 and the rigid-body placement of §14.8 alike — is fitted on the working set alone, so the free reflections are held out of the fit as well as out of the sum. Two choices are still *selected* with the free set rather than fitted to it, and both are single discrete decisions rather than continuous parameters: the rigid-body step is committed only if it lowers R-free (§14.8), and the alternative indexing of §14.6 is the candidate with the lowest R-free. Both are the conventional use of a test set to accept or reject a step; both leave R-free very slightly optimistic where they fire. + +### 14.4 Electron-density maps + +Two sets of map coefficients are formed with the model phases $\varphi_\mathrm{model}$, both $\sigma_A$ weighted: $2mF_o-DF_c$ and $mF_o-DF_c$. They are written as a map-coefficient MTZ (`_maps.mtz`: `FP`, `FC`, `PHIC`, `FWT`/`PHWT`, `FWT_no_fill`/`PHWT_no_fill`, `DELFWT`/`PHDELWT`, `FOM`, `FREE`, and where the merge kept the Bijvoet pairs `ANOM`/`PHANOM`, the anomalous difference map's coefficients), which Coot / PyMOL open directly as maps. The $2mF_o-DF_c$ coefficients are also inverse-Fourier-transformed to a real-space map internally, for the mean density at the atom centres. + +$\sigma_A$ is estimated by maximum likelihood **per resolution shell**, on the **free reflections only** — on the working set the model has been fitted to the data, so $\sigma_A$ would come out too high and the weighting would understate exactly the model error the map is meant to reveal. The shells are cut by equal reflection count, and it is the *number of shells* that is chosen from the size of the free set (about 50 free reflections to a shell, at most 20 shells), so no shell is thin by construction; a shell that still ends up with fewer than 10 free reflections takes the estimate made over the whole free set instead. Acentric and centric reflections enter with their own likelihoods (Rice and Woolfson respectively), and the epsilon factor is divided out before normalising both amplitudes to $\langle|E|^2\rangle = 1$ within the shell. The figure of merit is then $m = I_1(X)/I_0(X)$ with $X = 2\sigma_A|E_o||E_c|/(1-\sigma_A^2)$ for an acentric reflection and $m = \tanh(X/2)$ for a centric one, and $D = \sigma_A\sqrt{\Sigma_o/\Sigma_c}$ carries $F_c$ onto the observed amplitudes' scale. The $2F_o-F_c$ combination becomes $2mF_o - DF_c$ for acentric reflections and $mF_o$ for centric ones — a centric reflection's phase is either exactly right or 180° wrong, never in between — while the difference coefficient is $mF_o - DF_c$ throughout. The coefficients written to the MTZ then have the overall anisotropy of the scale divided out: each is divided by $\exp(-\tfrac14\,\mathbf{h}^T B^*_\mathrm{aniso}\mathbf{h})$, $B^*_\mathrm{aniso}$ the overall anisotropic *B* of §14.2 less its isotropic part, as phenix.refine does with its maps. Left in, the data's anisotropy stretches every atom along the weak direction; taken out, the map has the isotropic fall-off of the data and of the model. `FP` and `FC` stay on the observed scale, and the map read internally keeps it too. `FWT`/`PHWT` is **filled**: every reflection of the data's resolution range that the data do not have is added with $DF_c$, its expected value given the model, $D$ that of the observed reflection nearest in resolution - the convention of phenix.refine (`fill_missing_f_obs`) and BUSTER, which keeps the missing reflections from biasing the map towards zero. Those rows have `FP`, `FOM`, `FREE` and the difference coefficients missing. `FWT_no_fill`/`PHWT_no_fill` is the same $2mF_o-DF_c$ map on the observed reflections only (phenix's `2FOFCWT_no_fill`), and the difference map `DELFWT`/`PHDELWT` is never filled. + +$m$ and $D$ are estimated on each dataset separately, so two datasets of one crystal form get slightly different weights and their maps are to that extent no longer scaled identically — the same property §14.2 deliberately protects by refusing a free-form per-shell rescale. The two are not the same thing: the weighting never rescales $F_o$ and never touches the R-factors of §14.3, and the difference between two datasets' $\sigma_A$ curves is the difference in how well the model explains each of them, which is what a screening campaign is looking for. A PanDDA-style analysis consumes $2mF_o-DF_c$ maps and normalises each dataset's map against the ensemble before comparing them. The per-reflection `FOM` is written to the MTZ so the weighting can be read off and undone. + +### 14.5 Does the model fit? The null it is scored against + +A model supplied with `--model` is a **hypothesis about the crystal**, not an instruction. It is +always scaled, always placed (§14.8) and always scored, and its R-factors and maps are always +reported — but before it is allowed to change anything about the reflections that are written, the +data have to accept it. There are only two such things (§14.6); the same verdict also says whether the +rigid body placed the model at all (below). + +**No fixed threshold on R can decide that.** The classical acentric +random-structure value is $R = 0.586$ at unit scale, but the scale here is fitted to minimise the very +sum the R is made of, which pulls it to about 0.550; observed nulls on real data land at 0.60–0.62; +and the value moves with the *model* — its atom count and its B-factors — as much as with the data, so +a cut calibrated on one pair misjudges the next: an unrelated protein can reach a *lower* raw R-free +on one dataset than the correct model does on another. + +The only null that fits both the model and the data is therefore **made out of them**: the same model +is re-oriented at random about its own centroid and run through the identical path — the same scaling, +the same rigid-body placement, the same R — nine times, and the real fit is asked how far above the +resulting distribution it sits (`MODEL_FIT_SIGMA`, accepted at 4.51: see below). The replicates are placed as well +as fitted, or the comparison would be between a placed model and unplaced nulls and the margin would +be inflated by the placement rather than by the model. Measured on one rotation data set: the crystal's +own model +15.0σ, an unrelated protein +1.8σ, and the correct model rigidly rotated 90° −1.0σ. + +A replicate is a sample of the null only while it stays away from the model's own solution. A draw +within the rigid body's reach of an orientation equivalent to the model's — under the space group's +rotations or a twin law of the lattice — is drawn again before it is placed, and a replicate the +placement nevertheless carries to within that reach is drawn and placed again afterwards, each +replicate from a generator of its own so the result does not depend on the order the concurrent +replicates finish in. + +**R-work carries the decision, not R-free.** Nothing is refined against the working set here — the +scale has a handful of parameters (a scale, an anisotropic $B$ and two solvent terms) and the placement six — so R-work carries no optimism, and it has an order +of magnitude more reflections than R-free, and so that much more power to separate the two arms. R-free +is still reported, and is still what the placement of §14.8 is committed on, since that *is* a fit. + +What the verdict gates is exactly the two decisions of §14.6 that **rewrite the data**: the +space-group label and the indexing. It does not gate the R-factors, the maps or the rigid-body +placement, which are statements about the model and cannot corrupt a reflection. A rejected model +therefore leaves the written files byte for byte what a run with no model would have produced, and the +report says so beside the R it was rejected on: a negative result, not a failed run. + +**The null is built for every model the rigid body is tried on.** A model already in the data's group, +on a crystal with no merohedral ambiguity, claims nothing about the written reflections, but the null +is built for it too, because its verdict has a second use: it is what says whether the +rigid body placed the model at all, and a model it did not place - a deposited structure of another +crystal form, a model in a subgroup the data were merged above - is then searched for by molecular +replacement, which may only relabel the enantiomorph of the answer (past the anomalous veto) and writes +any other group it chooses beside it as `_mr`. The cost is the null's one to two seconds on every +run with a model. + +The count is nine, and it is the *spread* that sets it rather than the mean: the verdict is +(mean − real)/sd of the sample, the relative error on an sd from $n$ draws is $1/\sqrt{2(n-1)}$, and a +sample that happens to come out narrow is what turns a model that does not fit into one that appears +to: for an unrelated protein near the gate, the chance of reading over it on a different seed falls +from about a third at $n=3$ to a few percent at $n=9$. The gate itself allows for it: the intended cut is 3σ of the null (one-sided, 0.135 %), and a +new draw from a null known only through $n$ draws lies $t_{n-1}\sqrt{1+1/n}$ sample sds above their +mean at that probability — 4.51 for $n=9$. Read as if the sd were known, an unrelated model can pass +3σ against nine draws and fall to about 2σ against many more. Deposited models of their own crystal +read +7σ and up. The indexing lead (§14.6) stays at 3σ of its own null: it is only read for a model that has +passed this gate, and deposited models settle an indexing lead by +4σ and up. Nine is affordable only because the replicates run at once: the null costs the slowest of them +rather than their sum, and the slowest of nine is barely above the slowest of five. + +The null costs one full fit and one rigid-body placement per replicate. The replicates share nothing +— each is the same model under a different rotation, scored the same way — so each takes a copy of +the model and of its structure factors and they run **concurrently**, on the run's own thread budget +(`-N`); the real model is not touched by any of them. Measured on an idle machine, five replicates +cost 2.5 s together where running them one after another costs 10 s, on a `--mode scale` run that +merges in 2 s. What remains is the cost of the *slowest* replicate: how many placement evaluations an +orientation needs varies by nearly half between them, so the concurrency saturates around 4×, and +more threads than replicates buy nothing. The orientations are drawn up front, in order, from the +fixed seed, so replicate $i$ gets the same orientation whatever order the threads run in — a σ that +depended on the scheduling would not be a measurement. That is the price of the answer being a +measurement rather than a threshold. + +### 14.6 Aligning the data to the model: enantiomorph and indexing ambiguity + +The model fixes a definite hand and indexing, but the merged data need not share them, so before comparison the observed reflections are brought into the model's frame. + +- **Enantiomorph / screw.** When the data space group is the enantiomorph of the model's (e.g. data $P4_12_12$, model $P4_32_12$; or $P3_1/P3_2$), the two are **indistinguishable from merged intensities** — $|F_\mathrm{calc}|$ is invariant under the change of hand, so R-free cannot choose between them and probing would be meaningless. Where the model was accepted (§14.5), its group is therefore adopted as the **label** the reflections are written under, and the reflections themselves are left untouched. Where it was not, the label is left alone: adopting it is arithmetic on two group numbers, which a model that does not belong to this crystal can do exactly as readily as one that does, and the anomalous map of §14.7 vetoes it outright where it says the two are in opposite hands. The two groups of an enantiomorphic pair differ only in the translations of their operations: their rotations are identical, so they transform $hkl$ identically, share a reciprocal ASU, and assign the Bijvoet hands identically. The label carries no handedness, and there is nothing about it to undo. Reindexing by the change-of-hand operator — which is the inversion — would instead **swap $I(+)$ with $I(-)$**, flipping every anomalous difference on the strength of a label the space-group search itself reports as undetermined; where the model is genuinely the wrong enantiomorph for the crystal, it would manufacture agreement rather than reveal the mismatch. What does carry the hand is the indexing the data already have, from the diffraction geometry, and the anomalous differences that come with it. §14.7 is what tests them against the model. +- **Indexing (merohedral) ambiguity.** When the crystal has a merohedral ambiguity (§10.9), the observed intensities *do* differ between indexings, and the right one is chosen against the best available reference. **If a reference MTZ was supplied, the data were already reindexed to agree with it** (§10.9 — by the reference-intensity correlation, at the merge stage for rotation data or per image in stills scaling), and model validation keeps that authoritative choice. **Only with a model and no reference** does validation resolve the ambiguity itself, as a fallback: the scaled model is fit to each reindexing of the data (identity plus the twin-law cosets) and the one giving the **lowest R-free** is kept — but only where its lead over the runner-up beats the lead the *same model in a random orientation* takes, since a random model also picks a winner, and, as measured, by a comparable margin. Where it does not, the data keep the indexing they were merged in. The candidate operators are enumerated from the **data's** space group, not the model's: it is the observed intensities that are being relabelled, and asking the model's group enumerates nothing at all wherever the two differ. This matters for a multi-dataset campaign — a single shared reference fixes one indexing convention for every dataset, whereas an independent per-dataset lowest-R-free choice could send borderline datasets to different conventions. A no-op either way for a holohedral crystal (no twin laws). The two decisions then reach the written output differently, because only one of them moves reflections. The **ambiguity choice is applied to the merged reflections themselves** — and to the integrated observations behind the unmerged export — which are written after this step, so the reflection file, the R-factors and the maps describe one indexing. The **change of hand changes only the space group the files are written under** (the model's enantiomorph): no reflection moves, exactly as the first bullet says, so $I(+)$ and $I(-)$ stay as measured and §14.7's hand check remains a genuine test rather than an agreement manufactured by reindexing. The ambiguity choice is reported with that margin and with the null it was judged against, since the margin alone is what cannot say whether the data decided or the two came out within noise of each other. + +### 14.7 Anomalous difference map and the sites it names + +Where the merge kept the Bijvoet split (§10.5) — which a rotation merge does by default, whether or not the mates were averaged — an **anomalous difference map** is computed as well, with coefficients + +$ +\big(|F(+)| - |F(-)|\big)\, e^{i(\varphi_\mathrm{model} - \pi/2)}, +$ + +over the acentric reflections that have both hands (a centric reflection has no anomalous difference, only noise). Turning the model phase back by 90° is what makes the anomalous scattering, which is 90° out of phase with the normal scattering, add up in the real part: the map's peaks then sit on the anomalous scatterers. It is read here and not written out. Its hand is the one §14.6 settled: with the mates the wrong way round every peak becomes a trough, so a map of clean peaks is itself a check that the frame is right. + +Rather than searching the map for blobs and leaving a list of coordinates, the map is read **at the model's own atom centres** (hydrogens excluded — they scatter no anomalous signal), and the ten highest, in units of the map's r.m.s., are reported in the log and as `ANOMALOUS_SITE_01`…`ANOMALOUS_SITE_10` in the results report. Each site is therefore named — the atom, residue and chain it belongs to — which is what says *what* carries the signal, not just where it is. The reading is cubic, not linear: the map is sampled every $d_\mathrm{min}/3$, and a peak that sharp read by trilinear interpolation comes out up to a quarter low — unevenly enough to reorder the sites. This reading is the one ANODE reports. The same reading averaged over the model's **anomalous scatterers** — every atom from phosphorus ($Z = 15$) up: the S of Met and Cys, metals, Cl, I — is reported as `ANOMALOUS_SCATTERER_MEAN_SIGMA` (with their count, `ANOMALOUS_SCATTERERS`): one number for how much anomalous signal the merge carries, which does not depend on which ten atoms happen to come out on top. Below phosphorus (C, N, O, Na, Mg) $f''$ is a fraction of sulfur's at any wavelength these data are taken at, and counting those atoms would only dilute the mean with noise. Reading the map at the atoms cannot show a scatterer the model does not have, so the map's own peaks are searched as well (gemmi's flood fill, each symmetry copy once): every peak of 5 σ or more with no atom of the model from phosphorus up within 1.5 Å is reported as `ANOMALOUS_UNEXPLAINED_PEAK_01`… with its position and the model's nearest atom - an ion or a heavy atom left out of the model, or modelled as a lighter element. + +Because the map is built on the model's phases and the data's own indexing, it is also the only test of whether the two agree about the **hand** (§14.6). A model and a dataset in opposite hands turn every anomalous peak into a trough, so a map whose deepest hole at an atom is both deeper than $5\sigma$ and deeper than its highest peak says so, and the run reports it as a warning naming that atom. It is not repaired by reindexing: that would make the two agree by construction and destroy the evidence for which of the model and the data is in the wrong hand. Note that R-free cannot see this at all — a mirrored model gives R-free to four decimal places unchanged, and an exactly inverted anomalous map. + +The list is always ten entries long, so it is their height that carries the information: on a sulfur-SAD dataset the sulfurs fill the top of the list and are followed by a clear drop to the couple of sigma that is the map's noise, while a dataset with no anomalous signal has no such separation and lists ten unrelated atoms at noise level. A scatterer the **model does not contain** — a bound ion, a soaked heavy atom — is by construction invisible in the list, and takes the anomalous difference map itself, which rugnux does not write out. + +### 14.8 Rigid-body placement of the model + +Re-fractionalizing a model into the data cell puts it in the right box but not necessarily in the right place: a non-isomorphous cell squeezes the box without moving the body inside it, and the body's own position in the cell differs from crystal to crystal. Six parameters recover that — an angle-axis rotation about the model's own centroid, then a translation. Rotating about the centroid rather than the cell origin is what keeps the rotation from moving the body bodily, so the two triplets are close to independent. Parameters are carried as six lengths in ångström (the rotation vector multiplied by the model's r.m.s. radius), so a unit of each moves a typical atom by the same amount. + +It is **one** rigid body. A fragment-screening model arrives already solved and isomorphous, and what is being recovered is the crystal's movement, not the molecule's; splitting it into domains, or giving a bound ligand six parameters of its own, would refine against evidence these data do not separately carry — and the ligand is what the difference map is there to show, not to model away. + +The refinement walks a coarse-to-fine ladder, 6 Å → 4.5 Å → 3.5 Å, each zone starting from the previous one's answer. It stops at 3.5 Å because that is where rigid-body refinement is conventionally run and because the movement being recovered is a few tenths of an ångström, a tenth of that resolution; a finer zone costs $(1/d)^3$ in grid points and reflections for a placement it cannot meaningfully sharpen. Each evaluation recomputes $F_\mathrm{calc}$ and the solvent mask for the moved model **and re-fits the scale of §14.2** — otherwise the target would measure the scale as much as the placement, and the body would translate to repair a scale error instead of moving to where the density is. The minimiser is Levenberg–Marquardt on the amplitude residuals. $F_\mathrm{calc}$ is computed from **one copy** of the model, gridded without symmetrization and transformed once, and composed over the space group's operators, $F(\mathbf h) = n_\mathrm{cen}\sum_{(R,\mathbf t)} e^{2\pi i\,\mathbf h\cdot\mathbf t}\,F_1(\mathbf hR)$ — the transform of the symmetrized map, rearranged. That makes the derivative with respect to the translation exact and free ($F_1(\mathbf k)$ only picks up the phase $e^{2\pi i\,\mathbf s_\mathbf k\cdot\Delta}$). The rotation's three columns are forward differences, the step a fixed fraction of the zone's resolution, each needing only one copy gridded and transformed. The Jacobian holds the scale and the bulk-solvent mask at the evaluation's; the residuals keep both exact, and the scale re-fit is folded into the Jacobian by variable projection (Golub & Pereyra 1973, in Kaufman's 1975 form), so a step is judged on the target the evaluations actually compute. + +The refinement sees **only the working reflections**. The step is then committed only if it lowers **R-free**, computed at full resolution on the free set it never saw; otherwise the model is put back exactly where it was read and the maps are the ones it would have given. The whole addition costs about two seconds. Note that the origin is a gauge in some space groups — free in all three directions in $P1$, and along the unique axis in a polar group — so those components of the translation are undetermined; nothing is done about that beyond the Levenberg–Marquardt damping and the R-free gate, which between them make an undetermined direction harmless rather than unstable. + +Where a CUDA GPU is present, the refinement's target is evaluated on it: the same density, the same composition of $F_\mathrm{calc}$ from one copy of the model, the same bulk-solvent mask with its islands removed, the same scale fit and the same Jacobian, computed on the device, where a fit takes a fraction of a second rather than several seconds. The device is chosen once per validation, before anything is computed, and never revisited - the real fit and every replicate of the null of §14.5 on the same one. What goes on the GPU is decided for all parts at once, on one budget: 80% of the card's total memory (judged on the total, so the same input on the same machine always takes the same path), less what a merge still at work holds there. Every engine is reserved up front and kept to the end, so it is their sum that has to fit: the structure factors to the data's resolution (which also make the maps), one rigid-body engine, the null's structure factors to its coarser limit and one engine for the scale fits of §14.2 each take their place in that order where they still fit, and more rigid-body engines and then more scale-fit engines are added only within half of the budget: they change only how many fits run at once, and on a large cell, where one fit already fills the card, they buy little. A part that does not fit, or a cell too small for the GPU's gridding, runs on the CPU, as everything does where there is no GPU. A CUDA failure ends the validation, not the run: the validation reports why it did not finish, decides nothing, and the reflection files are those of a run without a model. The two agree to rounding and not bit for bit: the device measures distances in single precision and transforms with cuFFT instead of FFTW, and GEMMI's scale fit, whose stopping rule leaves it unconverged at about $10^{-4}$ of $|F|$, can respond to that rounding with a step of its own. A rigid-body step accepted or rejected on an R-free difference below about $5\cdot10^{-4}$ can therefore go either way between the two; every kernel is deterministic, so either one gives the same answer on every run. + +The rotation and translation actually taken are reported (`RIGID_BODY_ROTATION_DEG`, `RIGID_BODY_SHIFT_A`), together with the R-free before it (`R_FREE_BEFORE_RIGID_BODY`), so what the placement bought is visible. + +The coordinates **as placed** are written as `_model.cif`, and as `_model.pdb` where the PDB format can hold the cell (the fragment-screening tools the file feeds — PanDDA, and the pair dimple produces — take a PDB beside the MTZ), so there is a coordinate file that describes the maps: the input's chains, residues, ligands, waters, B-factors, occupancies and anisotropic $U$s, moved, in the same cell and space group as `.mtz`. Taking the frame from the written reflections rather than from the input model matters — §14.6 may have relabelled them to the model's enantiomorph, which is neither the data's original group nor, necessarily, the model's. It is written **whenever the maps are**, not only where the rigid-body step was committed: the model is re-fractionalized into the data cell and may be relabelled whatever the placement decided, so an unmoved model is still not the input file. Neither is written for a model placed nowhere (`MODEL_PLACEMENT=NOT_PLACED`: the null of §14.5 rejected it and molecular replacement did not place it): it is scored like any other and its R-factors are reported as the negative result, but coordinates and maps of it would read as a placement of a model that is not this crystal's. + +### 14.9 The twin hypothesis: which merge the maps come from + +Where the run wrote a twin hypothesis (§13.2), the model is scored against that merge too: as merged, and **as twinned** by its law — $|F_\mathrm{twin}(h)|^2 = (1-\alpha)|F_\mathrm{model}(h)|^2 + \alpha|F_\mathrm{model}(Th)|^2$ from the placed, scaled model, one overall scale refitted at each $\alpha$, $\alpha$ scanned from 0 to 0.5 in steps of 0.01 on the working set and R-free read at the chosen one. The placement, the anisotropic $B$ and the bulk solvent are those of the untwinned fit (§14.2, §14.8), so this is the same few-parameter comparison as §14.3, not a twin refinement. Against the answer's merge the model is scored as in §14.3, the subgroup model's structure factors simply read at each of the higher group's reflections. + +The maps and the placed model are then made from whichever merge the model fits better on R-free — the lower of the subgroup's plain and twinned R-free against the answer's — and the report says which (`MAPS_FROM=`) and with what R-free for each. The map coefficients are those of §14.4 against the chosen merge's amplitudes, not detwinned. **This chooses the maps, and never the answer**: the space group, the answer's reflection files and every number in the report outside the twin keys are what the run decided without the model, because a model can be wrong and the reflection files must not depend on one (§14.5). Where the model also fits the subgroup's merge against its own null (§14.5), it has chosen the subgroup, and that merge is written beside the answer as `_mr.mtz`/`.cif`, with the model as placed there. The structure factors come from the same GPU engine as §14.1 where there is a GPU. + +### 14.10 Molecular replacement: placing a model the rigid body cannot + +The rigid body of §14.8 only moves a model that already sits near its place. A model it does not +place - the null of §14.5 is not beaten in the answer's merge nor in the twin hypothesis' one - is +searched for from scratch, and so is a **predicted** model, which has no placement of its own, and any +model given with `--mr`. The kind of model is read from the file: a prediction (ModelCIF's +`_ma_qa_metric`, or no cell and one B value per residue between 0 and 100) is trimmed to the residues +of pLDDT 70 and above, its B-factors made from the pLDDT and its coordinate error from them (following +Oeffner et al., 2022), and cut into rigid domains where the AlphaFold DB's predicted-aligned-error file +sits beside it; anything else is an experimental structure, used as its polymer alone. + +The search is the classical one, scored by likelihood. A rotation function over the point group, its +best peaks refined off the sampling grid (following Navaza, 1994); for each orientation a full-symmetry +translation function computed as one Fourier synthesis (following Crowther & Blow, 1967), in **every +space group the merge cannot tell apart** and in the twin hypothesis' subgroup; and the best +placements of each group put through the rigid body, the bulk solvent and R-free. Further copies are +added one at a time, up to the copy number the cell can hold by its Matthews coefficient (Matthews, +1968; the probabilities of Kantardjieff & Rupp, 2003), each with the copies already placed as a known +partial structure and ranked by the log-likelihood gain of the Rice/Woolfson distributions of +$E_\mathrm{obs}$ given $E_\mathrm{calc}$, with $\sigma_A$ falling off with the coordinate error +(following Read, 2001, and McCoy et al., 2005 and 2007). A model whose expected gain (McCoy et al., +2017) is too small to be found is not searched for. A copy is kept where it stands out from the +translation function's own peaks, packs without clashing, and lowers R-free; in $P1$, where the first +copy's position is a gauge, it has to stand out in the rotation function instead. + +Translational NCS changes what the search can tell apart (Read, Adams & McCoy, 2013): with a +pseudo-translation, one copy beside a translated twin of itself fits the data as well in a group whose +screw axes the translation turns into the chosen group's, so such a choice is left undecided unless the +copies, carried into the other group and refined there, fit clearly worse; and where the vector is half +a lattice vector, the placement is compared with every move of itself the vector allows, each refined, +on the weak reflections it modulates, and left undecided only where the best is not ahead of every other +by 3 standard errors of the paired per-reflection difference there. A model of several chains is searched +for as a whole and, side by side, as one chain of each molecule in it: the chains of an experimental model +from another crystal form need not sit in this crystal as they sat in that one, and the whole model's +choice gives way to a chain's where the chain's fits better by the R-free margin. + +The choice between groups and merges is a hypothesis comparison like §14.5: the candidate the choice +falls on has to beat a null of the same model placed from random orientations, and lead the other +groups by a margin in R-free. Where another group is within that margin with as many copies placed, +the two have as many parameters, so the working reflections compare them as fairly as the free ones +and there are some twenty times as many: the other group is ruled out where the chosen placement's +$|F_\mathrm{obs}-F_\mathrm{calc}|$ is lower by 3 standard errors of the paired per-reflection +difference over every reflection to the scoring limit, and the choice is left undecided otherwise. +What the choice may do is limited exactly as for the rigid body, and +less: it may relabel the **enantiomorph** of the answer, past the anomalous check of §14.7, and never +reindexes; another group with the answer's rotations, or the twin hypothesis' subgroup, is written +beside the answer as `_mr.mtz`/`.cif` with the model as placed there, and the answer's own +files stay what the run decided. The rotation and translation functions, the rigid body and the +structure factors run on the GPU where there is one, decided for each merge before its search starts on +the budget of §14.8 (80% of the card's total memory, less what a merge still at work holds there): the +molecular transform, one rigid-body engine shared by every fit of the merge and the largest score engine +take their place in that order where they still fit, more rigid-body engines are added only within half +of the budget, and the score engines and the functions' working buffers share what is left, waiting for +each other rather than spilling past it. On the CPU the molecular transform's FFT is split over the +threads by columns and planes, each done by one plan, so its result does not depend on the thread +count. The keys, thresholds and table are described in +[the results report](RUGNUX_REPORT.md#molecular-replacement). diff --git a/_sources/CPU_DATA_ANALYSIS_IMAGE.md.txt b/_sources/CPU_DATA_ANALYSIS_IMAGE.md.txt new file mode 100644 index 000000000..ca528af07 --- /dev/null +++ b/_sources/CPU_DATA_ANALYSIS_IMAGE.md.txt @@ -0,0 +1,696 @@ +# Data analysis: from images to spots (§0–§3) + +Part of the [CPU/GPU data-analysis reference](CPU_DATA_ANALYSIS.md); the section numbers are continuous across its parts. + +```{contents} On this page +:local: +:depth: 2 +``` + + +## 0. Getting the image onto the GPU: device-side decoding + +HDF5 images mostly arrive bitshuffle+LZ4 compressed (HDF5 filter 32008), and everything from §1 onwards runs on +the GPU when one is present. Instead of decompressing on the host and uploading the image, the +compressed chunk is uploaded — a few MB rather than tens of MB — and decoded on the device. The +approach follows Jon Wright (ESRF); the kernels are Jungfraujoch's own. + +One kernel does the work: one CUDA block owns one bitshuffle block, from the compressed payload +through to finished pixels. + +1. **LZ4 into shared memory, one warp per bitshuffle block.** Blocks are independent, so the + parallelism is across them; within the warp every lane runs the same sequence parser over the + same bytes, and the literal and match copies are split across the 32 lanes so the stores + coalesce. An overlapping match is treated as a pattern of period `offset` sourced from bytes + that already precede the write position, which keeps it parallel rather than a serial byte loop; + `offset == 1` (a run of one repeated byte, the common case in sparse detector data) and + power-of-two offsets avoid the modulo altogether. Because the lanes cooperate on the copies, + each one is followed by `__syncwarp()` — a later match can read bytes another lane wrote, and + since Volta that ordering is not implicit. +2. **The bitshuffle inverse fused with preprocessing.** The whole CUDA block then reads that shared + buffer back: one thread owns one group of 8 elements across every byte-plane, so once it has + transposed its 8 bytes out of each plane it holds 8 complete elements — and it applies the pixel + mask, the error marker and the saturation cap and emits 8 finished `int32` pixels directly. + Nothing of the block reaches device memory but the pixels — neither the bitshuffled bytes nor the + decompressed image is ever materialised. For 8-bit images there is a single plane and the + assembly degenerates to a copy. + +Decoding into shared memory is worth more than the bandwidth it saves: an LZ4 match reads back bytes +written a few sequences earlier, so every copy step is a dependent round trip — tens of cycles in +shared memory against hundreds in device memory. It is paid for in residency, because the buffer +holds a whole bitshuffle block, and a block larger than 16 kB (larger than either writer this +pipeline reads produces) falls back to a pair of kernels instead, the first writing the shuffled +image to device memory and the second un-transposing and preprocessing out of it. + +The block offsets inside the container can only be discovered by reading the block lengths in +order, so that scan stays on the host. + +Two stored formats of other detectors also reach the card as the file stores them. A miniCBF frame's +`x-CBF_BYTE_OFFSET` stream is decoded on the device into the same `int32` image: the stream is cut +into short parts; for every byte offset a part can be entered at, one thread works out where the +decode leaves the part, how many pixels it emitted and their running sum; a scan composing those maps +gives every part its true entry and running value; and a second walk writes the pixels. A stream that +ends before the image is refused, as on the host. A marCCD frame's 16-bit pixels cross the bus at two +bytes each and are widened by the preprocessing kernel itself, which tests the error marker and the +saturation cap on the pixel's value, so a marCCD's 65535 - its saturation marker, not an error - is +treated exactly as in the `int32` image the host would have made. Both are staged through the +engine's own page-locked buffer, as the BSLZ4 chunks are; `.cbf.gz` is still inflated on the host. + +For the zstd variants (`BSHUF_ZSTD`, `BSHUF_ZSTD_RLE`, `BSHUF_ZSTD_RLE_HUFF`), and for other +uncompressed or float images, the pipeline decompresses on the host and uploads as before. The host +decoders are the CPU build's path, not a fallback: a frame the device refuses is not retried on the +host. + +The container arrives off the network or off disk and is not trusted. Everything checkable on the +host — declared sizes, the block scan, a block size that is not a multiple of 8 elements, a block +count the chunk could not hold, trailing bytes — is rejected before any work is queued; the kernel +additionally flags a block that did not decode to exactly its declared length, which becomes an +exception once the caller has synchronised. That last check matters because the decode buffers are +reused frame to frame: a block that stopped early would leave the *previous* image's most significant +byte-plane in place, which reads not as a missing corner but as real pixels several powers of two too +bright. + +## 1. Geometry, reciprocal-space mapping, and basic quantities + +### 1.1 Coordinate conventions + +For a pixel coordinate $(x,y)$ (in pixels), Jungfraujoch converts to a laboratory direction vector via: + +1. shift by the beam-centre pixel $(x_\mathrm{beam}, y_\mathrm{beam})$ — the **PONI**, pyFAI's point of normal incidence, which coincides with the direct-beam impact point only for an untilted detector (see [Detector geometry](DETECTOR_GEOMETRY.md)), +2. scale by pixel size $p$ (mm), +3. set detector distance $D$ (mm), +4. apply detector orientation rotation $R_\mathrm{det}$ (PyFAI-like parameterization). + +The unnormalized detector coordinate (mm) is: +$ +\mathbf{r}_\mathrm{det}(x,y) = +\begin{pmatrix} +(x-x_\mathrm{beam})p\\ +(y-y_\mathrm{beam})p\\ +D +\end{pmatrix}. +$ + +The lab-frame vector is: +$ +\mathbf{r}_\mathrm{lab} = R_\mathrm{det}\,\mathbf{r}_\mathrm{det}. +$ + +By this construction $(x_\mathrm{beam}, y_\mathrm{beam})$ maps to $(0,0,D)$ *before* the rotation — the point where the detector normal through the sample meets the detector — which is what makes it the PONI rather than the direct beam; the two differ by $D\tan(\mathrm{tilt})$ on a tilted detector. The laboratory frame is fixed the same way everywhere in the system: $+z$ along the beam propagation, $+x$ along increasing pixel **column** (the fast axis) and $+y$ along increasing pixel **row** (the slow axis) — a right-handed triple that coincides with XDS's laboratory frame, which is what makes the geometry echo of [Rugnux](RUGNUX_INTEGRATION.md#comparing-the-geometry-with-xds) directly comparable. The absolute hand of an indexing — and with it the Bijvoet hands of §14.6–§14.7 — follows from this convention. + +Let the incident wavevector magnitude be $k = 1/\lambda$ in Å$^{-1}$, and define: +$ +\mathbf{S}_0 = (0,0,k). +$ + +The **reciprocal-space scattering vector** associated with pixel $(x,y)$ is: +$ +\mathbf{s}(x,y) = k\,\frac{\mathbf{r}_\mathrm{lab}}{\lVert \mathbf{r}_\mathrm{lab}\rVert} - \mathbf{S}_0. +$ + +This $\mathbf{s}$ is the fundamental quantity used for spot finding (resolution filters), indexing, and refinement. + +### 1.2 Two-theta, azimuth, resolution and $q$ + +The scattering angle $2\theta$ is computed from $\mathbf{r}_\mathrm{lab}$ via: +$ +2\theta = \mathrm{atan2}\!\left(\sqrt{x_\mathrm{lab}^2 + y_\mathrm{lab}^2},\; z_\mathrm{lab}\right), +$ + +evaluated as a two-argument arctangent, so the mapping stays correct where a strongly tilted detector's far corner reaches past $2\theta = 90°$. + +Resolution (Å) at a pixel is: +$ +d = \frac{\lambda}{2\sin\theta}. +$ + +The magnitude $q = 2\pi/d$ is used for radial binning and ice-ring handling. + +### 1.3 Distance from the Ewald sphere + +For a reciprocal lattice point $\mathbf{p}$ (Å$^{-1}$), define: +$ +\Delta_\mathrm{Ewald}(\mathbf{p}) = \lVert \mathbf{p} + \mathbf{S}_0\rVert - k. +$ +Jungfraujoch uses $|\Delta_\mathrm{Ewald}|$ as an operational proxy for excitation error. This appears in: +- still prediction (accept if $|\Delta_\mathrm{Ewald}|\le \Delta_\mathrm{cut}$), +- profile radius estimation (see §11.1), +- still partiality option in scaling/merging (§10.2). + +### 1.4 The beam centre + +A run starts from the beam centre in the file, or from `--beam-x`/`--beam-y` where they are given. +Header centres are often typed rather than measured, and on rotation data a wrong one is not repaired +by anything downstream: the error is fixed in the laboratory frame, so accumulating a sweep smears +every reciprocal-lattice point around a circle, and a displacement $\delta p$ on the detector multiplies the FFT +amplitude at an axis of length $a$ by $J_0(2\pi\,\delta p\,a/(D\lambda))$. Past the first zero the +true axis is gone and its harmonic wins. Rugnux therefore measures the centre itself on every run and +treats the measurement as a second hypothesis to be tested against the file's, not as a replacement +for it. Distrusting the header and finding the centre from the images are ideas inspired by autoPROC +(see [Acknowledgements](ACKNOWLEDGEMENT.md)). The steps, in the order they run: + +| Step | Runs | Effect on the centre | +| --- | --- | --- | +| Header check | every run, before a frame is read | none; reported | +| Background measurement (`--beam-center-check`) | every run with the beam-stop pre-scan | none at this point; reported | +| Second first pass at the measured centre | rotation | adopts the measured centre in the cases listed below | +| Both centres judged on the merge | rotation, two-pass | adopts the measured centre where its first pass merges better | +| Post-refinement (§7.5) | rotation, two-pass | refines the centre from the integrated reflections, within 15 px | + +On most runs the measured centre is reported, the second first pass finds the same lattice at both +centres, and the run continues at the file's centre until post-refinement moves it. + +**What the file says.** Before any frame is read, a centre within one pixel of the geometric centre of +the detector, or a whole number of pixels in both coordinates, is reported as *a value written rather +than measured*, and a centre that lands on a masked pixel is a warning — a real beam does not sit on a +dead pixel or in a module gap. These lines change nothing. + +**Measured on every run (`--beam-center-check`, on by default).** The isotropy of the scattered +background places the point the beam lands on; the leverage is the curvature of the solvent ring. The +fit runs over the mean image the beam-stop pre-scan already builds (§1.5), with the opaque part of the +shadow masked, so it costs no frames of its own. For the same reason `--detect-beam-stop=off` leaves +nothing to measure it on, and the check then does nothing. + +The fit starts with a **whole-detector capture**. The centrosymmetry score of the projection about a +candidate centre $\mathbf{c}$, $\sum_\mathbf{x} I(\mathbf{x})\,I(2\mathbf{c}-\mathbf{x})$, is the +self-convolution $(I*I)(2\mathbf{c})$, so **one FFT pair scores every candidate centre on the +detector** at half-pixel spacing: the cost is $O(N\log N)$ and independent of how far the header is +from the truth. The surface scored is the 2D point inversion, which measures the same isotropic +background the walk below fits. The beam-stop shadow is blanked out of the scored image, a one-sided opaque +obstruction being a centrosymmetry defect in its own right. What comes back is a shortlist and a +margin, not a centre: the surface can be locally flat over tens of pixels, and the +peak-to-runner-up margin says so. A **local walk** is then seeded at the capture and refines it; where +it declines there it is started again from the file's centre, and only where neither start gives it +something to fit does the capture stand alone. The transforms run on the GPU where one is present and +they fit half of the card's total memory, and on FFTW otherwise, with everything that decides anything +shared between the two. + +The run log then carries: + +- `Beam centre capture:` the strongest point-symmetry centre and its margin (under about 3 % the + surface is flat). +- `Beam centre check: the file puts the direct beam at (x,y), the scattered background puts it at + (x,y) +- σ px - a difference of d px, against the t px this geometry asks the centre to be right to.` + The comparison is against the **direct beam**, not the PONI: `beam_x_pxl` is the point of normal + incidence, and the two part by $D\tan(\mathrm{rot})/p$ as soon as the detector is tilted, while the + background is centrosymmetric about where the beam lands. $t = 0.183\,D\lambda/(p\,a_\mathrm{max})$ + is the displacement at which the $J_0$ factor above has fallen to 0.70 for the longest axis of the + cell given with `-C` (200 Å where none is given); it runs from well under a pixel to several. It is + reported, not used as a gate: a centre change far smaller than $t$ can still decide between a cell + and its harmonic. +- One of three follow-ups: the difference is under three times the fit's σ (the file's centre is as + good as this measurement can tell); more than $t$ of it lies **across** the spindle, where it can cost + peaks or an axis; or it is a real difference, mostly **along** the spindle, where a wrong centre does + not announce itself. + +None of these lines moves the centre. What consumes the measurement is the second first pass below +(rotation runs) and the bound on the post-refinement. + +**The second first pass (rotation).** After the first pass — and after the rotation-axis sign rescue +below — the first pass is indexed **again at the measured centre**, however small the difference. A +trial centre gets its own azimuthal mapping, spot engines and spot cache: raw centroids do not move +with the centre, but *which spots are in the list* does (the resolution limit, the ice-ring flag, the +beam-stop mask and the strongest-$N$ ranking are all radial), and the starting centre's spots are +parked and restored so a trial that adopts nothing leaves the run as it was. + +The indexed frame count is **not** used to choose between two centres that both index: acceptance is a +fractional-Miller test, so a cell twice as long must place every spot twice as accurately to score the +same, and a halved axis can index *more* frames than the true cell. "Indexes" below means more than +half of the validation frames; "same lattice" means the same Bravais class with primitive volumes +within 2 %. The outcomes: + +1. **The file's centre indexes and the measured one does not.** The file's centre stands. +2. **Both index the same lattice.** The file's centre is kept, and the log says the difference does not + decide this crystal's cell. A centre off by about one reflection spacing still indexes the same cell, + with part of the sweep given indices one out, so where the two centres are further apart than both + $t$ and three σ of the fit, the measured centre is kept as a hypothesis for the merge (next + paragraph). +3. **Both index the same cell in a different Bravais class.** Whether the centre could have decided the + class is arithmetic: a shift of $n$ pixels of size $p$ moves an axis of length $a$ by $n\,p\,a/(D\lambda)$ + relative, and the lattice search holds an axis equality to 3 %. Where the shift is worth that much on + the pair of reduced-cell axes the equality compares, both centres are carried to the merge; otherwise + the file's centre and its class are kept. +4. **Both index, on different lattices.** Both cells are reported in a warning. Where the primitive + volumes differ by an integer factor of 2 to 4 — an axis harmonic, which a centre error along the + spindle produces — the choice is made first on the pre-scan's **point-symmetry capture**, a second + reading of the same background by an estimator that sees neither lattice: where its margin is at + least 1.5 % (below ~1 % its surface is flat and its peak can be anywhere), the centre nearer the + capture is taken with its cell. Otherwise it is made on the **pooled validation spots**: the + measured centre is adopted where its lattice, larger or smaller, beats chance and puts a share of + the spots on itself over its own wrong-spindle null that exceeds the file's by more than the + binomial noise of the two (z = 3.29). Where that does not adopt it, the file's centre is kept for + the first pass and, on a two-pass run, both centres are carried to the merge (next paragraph). + Whichever cell a centre brings, the long-axis and sub-lattice hypotheses then test it on its own + spots, so a centre is not refused for the harmonic it first indexed. +5. **The file's centre does not index.** Nothing defends it, so: + - where the measured centre indexes, it is **adopted**; + - where it does not, the rotation-axis sign is flipped **at the measured centre**, since each of the + two errors can hide the other; where that indexes, both are adopted; + - where it still does not, the first-pass depth ladder of §6 (how much of each frame the pass reads) + is run at **both** centres, so the centre moves only when it is the centre that pays. The measured + centre is adopted where its lean rung indexes and beats the file's; where both index the same + lattice once less of each frame is read, both centres are carried to the merge; where the file's + centre wins or ties, the depth was the problem and the file's centre stays; + - where nothing indexes at either centre, the pooled spots decide as in case 4; failing that, the + file's centre is put back, so a run that fails for some other reason fails at the geometry it was + given. + +**Both centres judged on the merge (rotation, two-pass).** Where case 3, 4 or 5 carried both centres, the +whole first pass is run again at the measured centre — with its own +post-refinement — and the two arms are compared on their search merges ($P1$, whole range, before the +correction surfaces). Where case 2 held a hypothesis, this is done only if the file's arm merges +inconsistently: $\mathrm{CC}_{1/2}$ below 0.9 in the lowest-resolution shell of its search merge, where +every reflection is strong and a consistent merge reads close to 1. The measured centre wins where: + +- both arms ended on the same lattice, and it merges **more reflections at $I/\sigma \ge 2$**, or its + lowest-shell $\mathrm{CC}_{1/2}$ is higher by more than 0.05; +- the arms ended on different lattices, and its search-merge $\mathrm{CC}_{1/2}$ is higher by more than + 0.05. + +Otherwise, or where the measured arm does not complete, the run keeps the file's centre. The log lines +are `Beam centre check: running the first pass again at the measured centre …` followed by +`… the run adopts the measured centre and the lattice it finds` or `the measured centre does not win`. + +**After a first pass that failed.** A rotation sweep leaves one further thing the input often cannot +settle, decided on the same count the rest of the first pass uses — the right answer indexes and the +wrong one does not. + +* **The rotation-axis sign.** A miniCBF header names the axis but gives no direction, and an NXmx + vector is only meaningful together with the detector mounting. So after a poor first pass the + opposite sign is tried and whichever indexes more validation frames is kept, the flipped one only + where its lattice also beats chance on the pooled spots (§4.1), so that one frame against none on a + sparse pattern cannot flip it. The decision holds for the rest of the run, and it flips the + **axis**, not the angles, because prediction reads the axis too. It runs before the second first + pass above and before the long-axis hypothesis, since with the sign wrong every candidate lattice is + wrong. + +**Post-refinement.** On a two-pass rotation run, whatever centre the first pass ends on is refined +together with the distance, cell, orientation and axis by the post-refinement of §7.5, and the second +pass is integrated there. The background measurement does not move that fit; it only widens where the +fit may go: the refined beam is committed only within 15 px of the **nearer** of the pass-1 centre and +the measured one (the measured one counting where its σ is within $\max(1\ \mathrm{px}, t)$), so a +header that is far out can still be corrected. Where the refined pass is judged worse, the run goes +back to the pass-1 geometry. + +**Stills.** There is no second first pass and no post-refinement on stills; the centre is decided +before the images are processed, as competing hypotheses tested on the data. Spots are found once on a +sample of frames spread over the run, and three centres are tried: the file's, the background +measurement above, and the point-symmetry capture (a second estimator, because the background one is +biased where a shadow - a sample-delivery tape, say - covers part of the scattering). Each re-indexes the +same spots and is scored by how many land on their frame's lattice; the file's centre is kept unless +another puts at least 1/0.9 as many there. Where a reference cell is given, or the stills geometry +refinement has fitted one de novo (below), the detector distance is a hypothesis too. The spots of the sample are found without resolution limits (a d-spacing depends on the +distance being checked) and spots piled up at one radius - a powder ring - are left out. A scan over +30-3000 mm in 2.5 % steps at every centre candidate finds the peaks, the strongest are looked at more +closely and a finer step about the best decides against the file's distance, which is kept unless the best +puts at least 1/0.9 as many spots on the lattice; a local grid of centres follows at the distance decided. +The range is in millimetres, not in multiples of the file's value, so a stated camera length that is +nominal or wrong does not limit where the search looks, and an input that states no distance (an XTC) is +searched too. The spot count is flat to a percent or two about the right distance, so with `-C` the same sample is also +indexed de novo at the distance decided: a frame's de novo cell takes up the distance's error in its scale, and +the distance at which the cell given has the volume of the frames' cell is taken where it puts at least 0.9 times +as many sampled spots on the lattice and lies more than half the 1 % fine step from the distance decided. The same +de novo cell, as a known cell, is the frames' evidence on the cell given (§7.7 of the indexing page). A distance +given with `--detector-distance` is held: it is neither searched nor refined. +Without a cell nothing is searched in distance: on its own a wrong distance indexes as a wrong cell, not +as fewer indexed spots. The stills geometry refinement, `--refine-geometry`, bundle-adjusts the +centre and the distance together with the cell over strongly indexed frames (§7.7); it is on by default for +all stills. Without a reference cell it anchors on the cell most of the sampled frames index to de novo +(the frames on it are the ones fitted), and that cell serves the geometry steps only: the run itself is +still indexed de novo. + +**What ends up in the output.** The report's `BEAM_CENTRE` (the PONI) and `DIRECT_BEAM` are the +geometry the result was integrated at, and so is `JFJOCH_DATASET_SETTINGS`; `POSTREFINE_BEAM_CENTRE` +gives the post-refinement's move as `before -> after`. Which of the steps above changed the centre, and +why, is in the run log only. + +**Options.** + +- `--beam-x`/`--beam-y` set the starting centre. The background check still runs and can still adopt the measured centre in the cases above; add + `--beam-center-check=off` to hold a typed centre until post-refinement. +- `--beam-center-check=off` skips the background measurement and the second first pass, and removes the + measured centre from the post-refinement bound. +- `--detect-beam-stop=off` removes the projection the background measurement is read from. +- `--rotation-no-postrefine` removes the post-refinement, and with it the merge-judged arms. + +### 1.5 Finding the beam stop + +The beam stop and its holder arm shadow part of the detector. A reflection behind them is attenuated +but otherwise ordinary — it integrates low, with a plausible $\sigma$, and no outlier test catches +it — so the shadow is found and masked instead. `--detect-beam-stop[=N|off]` (on by default, $N=60$ +frames) projects those frames to a per-pixel mean and maximum, and writes the result into +the pixel mask as bit 9, from where it excludes those pixels from every later stage. + +The shadow is a place where the background is *missing*, so it is found by comparing each pixel's +background against the background at the same $2\theta$. The mean is pooled over a small box first — +a single pixel of a sparse background carries too few counts to tell a shadow from a Poisson hole, +and the stop is much wider than the box — and the comparison is against the median of the pixel's own +ring, taken over the pixels not already excluded and iterated a few times so the shadow stays +out of the baseline it is measured against. A pixel is shadow when the ratio falls below 0.50 **and** +the deficit is significant against its own Poisson scatter, $\sqrt{2\,(E-N+N\ln(N/E))}$ over the pooled +counts, taken in photons (on a detector read in ADU the counts are divided by its gain, as the protected +reflection count of 25 photons is multiplied by it), with the pooled count taken as at least zero: on frames +taken with the shutter closed the pixels scatter about zero, and a pooled sum below zero is no deficit of photons. A ratio says nothing when the background behind it is a handful of photons, and it is that +significance that makes the comparison scale-free rather than tuned to one exposure: rebuilt from six +frames of a low-background sweep, the same ratio without it masks three quarters of the detector. The +index of dispersion does *not* do this job — it is 1.0 inside the shadow and 1.0 outside it, a +shadowed pixel being Poisson at a low rate and a lit one Poisson at a high rate — only the rate +relative to the ring separates them. + +A ring is a cone of constant $2\theta$, indexed by $D\tan 2\theta$ in pixels. On an untilted detector +that is a circle about the beam centre; on a tilted one — a swung $2\theta$ arm — it is not, and a circle +about the centre runs across the background's own fall-off with $2\theta$: at a 5° swing and 50 mm that +put a quarter of the detector in the shadow. + +Nothing assumes the stop and the beam are concentric, because only the per-ring comparison is used; a +ring lying wholly inside the stop has no unshadowed pixel for its median to find, which is exactly the +case where the comparison must fail. Such a ring is judged against what this detector's background +typically is — the median over the rings the walk is willing to judge — and is shadow in its entirety +when it falls far below that. Comparing it instead against the *largest* background further out reads +an ordinary background inside a strong ring as blocked, and the walk then runs out to that ring and +returns a filled disk of good detector with diffraction rings plainly visible inside it. + +**The rings are drawn about the centre the data measure, not the one the file claims.** Displacing the +centre costs nothing for tens of pixels and a great deal beyond: at 150 px out the comparison describes +the background's own radial fall-off rather than the hardware, and returns a tenth of the detector as +shadow with nothing blocking it — and header centres are wrong by that much. The centre is therefore +fitted from the same per-pixel mean the mask is computed from, before the mask is read, and named to +the finder; it costs no frame of its own. That first fit is itself biased by the shadow it has not yet +masked (on a sweep with a third of the detector behind a pin it landed 5 px out and called itself +0.40 px), and it does not have to be unbiased: the ring comparison does not notice tens of pixels, and +the centre the run *reports and consumes* is the second fit of §1.4, the one that runs after the mask +is loaded with the shadow out of the way. The order is fit, mask, fit, and only the second answer +leaves. Two rounds are enough, measured rather than assumed — on clean sweeps the two fits agree to +0.03 px, so a third would draw the same rings. + +**A ring is only flat once the polarization is divided out.** The comparison assumes the background is +flat around a ring with nothing in the beam, and it is not: a polarized source suppresses the +background in its own plane by the azimuthal factor of §2.2, a factor of three at $2\theta=55°$ and +four at $70°$ — several times the dip the test is looking for, so on a short-distance geometry the two +in-plane lobes of every outer ring read as shadow (measured: 5 % and 11 % of two detectors, with +nothing visible under either mask). The mean projection is therefore divided by that factor before the +ring comparison, and the Poisson deficit multiplies it back in so the significance is still the +significance of the counts that were recorded. The factor is the geometry's own, evaluated about the +centre just fitted rather than the one in the file, because the geometry is what knows where the +polarization plane lies once the detector is tilted, the stored image quarter-turned or the detector +rotated in its own plane. On a tilted detector the **solid angle** of a pixel varies along a ring too — +by tens of per cent at a 5° swing and 50 mm — so the mean is divided as well by the pixel's solid angle +over the one an untilted detector has at the same $2\theta$, $(D/l_z)^3$ with $l_z$ the pixel's distance along the beam, which is exactly 1 untilted; +the Poisson deficit multiplies that back in as it does the polarization. Detector response and air +absorption are functions of $2\theta$ alone, nearly enough, and the ring median absorbs them. + +What survives is then shaped into a region, and what makes it specific is **size**, not connection to +the beam. A shadow is cast by something physical and is correspondingly large, while the background +wanders a pixel or two at a time, so the connected components holding at least 2000 pixels, of which at least 200 deep (well below the +ring's level, not merely dim), are kept and the rest dropped; on a clean sweep that returns exactly one +such component — the beam stop — and a spurious candidate is at most a few dozen pixels. Requiring the region to touch the direct beam instead is written for +the stop and its holder arm; hardware standing in the beam further out — a pin, a loop — casts a +shadow that begins some way out in radius, with lit detector between it and the stop and no bridge +across the gap, and such a shadow would then go unmasked and be integrated as measured-and-near-zero. +The kept components are bridged across the module gaps the +holder arm crosses, grown outward through the partially shadowed penumbra — much wider for a pin than +for a stop edge — closed, and with the interior of the disk filled; the rings found lying wholly +inside the stop join the region after the size filter rather than being asked to be large themselves. + +Last, any pixel that ever recorded a real +reflection — a maximum over the frames well above background, in a cluster, so that a single-frame +zinger does not count — is given back, because a beam stop cannot have blocked a reflection that was +measured. + +Pixels the finder reports that hold the detector's no-data mark (a PILATUS module gap stored as $-1$) +are the darkest pixels there are, but they are not shadow: they are masked as dead (bit 10) instead, so +that the reported shadow share is the shadow's and the test below does not drop every reflection a module +gap clips. A mean of zero is not taken as dead, since a deep shadow on a still counts nothing. + +**A reflection whose signal disk reaches into the shadow is not integrated.** The profile fit keeps a +disk that lost pixels to the mask and fits the pixels that remain (§9.3), which is right for a gap or a +dead pixel but not for the shadow: the mask is drawn where the background is dimmed, and the Bragg +half-shadow does not end there, so the rest of such a disk is attenuated too - measured against the +symmetry mates, such observations read low by 12-60 %. The test is made where each image is integrated, +so rotation, stills, the `_process.h5` and `--mode scale` see the same reflections; with no shadow in the +mask (the broker) it does nothing. + +### 1.6 Defective pixels + +A pixel that reads high frame after frame, whatever the crystal does, is integrated into whichever +reflection's box it falls in; under rotation that is one pixel collecting a different reflection on +every frame that reaches it, and a merged intensity hundreds or thousands of times its shell mean, +carried by one or two observations the merge's outlier test cannot judge. The file's mask misses +such pixels on many detectors, so Rugnux measures them on +the pre-scan's own sample of frames on every run (the hot and unstable rules need a rotation, where a +reflection moves off a pixel and a defect does not; dead pixels and those holding the detector's error value +are measured on stills too) (`HotPixelFinder`, `image_analysis/hot_pixels/HotPixels.h`) and masks them as bit 10. +The frames are read a second time for it, once the beam-stop projection has measured where the +scattered background puts the beam: the rings have to be drawn about the true beam, and a file's +centre can be far enough out that a ring crosses the background's radial fall-off. + +On each frame a pixel is **lit** when it exceeds $b + 3.3\,\max(\sqrt{b}, 1.4826\,\mathrm{MAD}) + 2$, +with $b$ the larger of the median of its 2 px iso-$2\theta$ ring and of that ring's sixteenth in +azimuth, so ice and powder rings, the polarization dip and partial shadows set their own level. It +is **persistent** when it is lit on at least $\max(k_1, k_B)$ of the sampled frames: one reflection +stays on a pixel for $(\Delta\phi + w)/|\zeta|$ of rotation ($w = 5°$, a generous rocking width), +which covers fewer than $k_1 = 1 + \lceil (\Delta\phi + w)/(|\zeta|\,\delta) \rceil$ frames sampled +$\delta$ apart; and $k_B$ is the binomial bound, from the lit rate of the ring's other pixels, that +fewer than 0.01 pixels of the whole detector reach by chance. A persistent pixel is masked if it +reads on average at least ten times its ring and its mean excess is above the Poisson bound; a +weaker one cannot make an outlier. This holds for a patch of such pixels as for a lone one: a patch +lit through the whole sweep is stationary in the lab, so it is no reflection of the rotating +crystal, and a reflection crossing it would read the patch. Pixels holding the detector's error +value on most frames (already invalid on every frame, but not in the static mask) are masked with +them, as are dead pixels (reading at most half of their ring's level frame after frame), unstable ones (far +below zero on a twentieth of their frames - no photon makes a count negative) and pixels stuck at saturation. +A CCD (read with an offset, not Poisson) needs no rule of its own: its dead pixels read the offset, far below +any ring with background on it, and a hot one ten times its ring. One log line says how +many pixels were masked and why. + +**Outside a CCD's active area.** An input in detector units whose background shows no photon peaks (a +CCD, an image plate or another integrating detector read through an amplifier) has read noise on every +live pixel, so no live pixel reads the same value on all 16 frames the detector gain is +measured on. A pixel that does lies outside the active area - the corners of a round CCD, a border or seam +the detector's corrections leave at zero - and is masked as inactive (bit 11) before the run starts. A test that +compares a pixel with its own resolution ring cannot see such an area: beyond the circle of +a round CCD the whole ring reads zero. It is not made where the pixels that do vary read zero on 1 % or +more of their readings (counted photons, or a file cut at a threshold), since a pixel at zero on every +frame may then simply have had nothing to record. The beam-stop finder (§1.5) reads these pixels as the +input has them, because a CCD reads the deep shadow of a beam stop at one value too. + +### 1.7 The saturation level + +A detector that saturates clips every value beyond its ceiling down to it, so on a frame's bright tail - +the cores of Bragg peaks, which otherwise fall off steadily with value - the values pile up just below +where they stop. Where each pixel has its own ceiling (an ADC limit less that pixel's dark), the +pile-up is a band, and its lower edge is where clipping starts. A file's own statement of the limit is +often missing or wrong for detectors outside the facility that wrote it, so on stills Rugnux reads it +off the values: a histogram of pixel values on a sample of frames, binned on a log scale, and the +lowest bin that rises above the tail below it. Pixels from there on are treated as overloaded where that +level is below the file's; the file's is kept for a file Jungfraujoch wrote, whose limit is the +detector's own, and when `--saturation` is given. The log states both values. Where an XFEL file +states no limit at all, the reader holds the values to their integer type's range. + +--- + +## 2. Azimuthal integration (radial profiles) + +Azimuthal integration produces a radial profile $I(q)$ or $I(d)$ by histogramming pixels into radial bins. Pixels are **not split** across bins; each pixel contributes wholly to a single bin. By default the profile is purely radial (a single azimuthal bin), but the azimuth can optionally be split into up to 512 $\phi$ sectors (`azim_bins`, `--azim-phi-bins`), giving a **2D $q\times\phi$ profile** that exposes azimuthal anisotropy such as detector shadowing or sample texture. + +The $q$ bins run from the low to the high $q$ limit and are laid out in one of two ways. **Linear** (the default) gives bins of equal width in $q$, set either by the spacing (`q_spacing`, `--azim-q-spacing`) or by the number of bins (`q_bins`, `--azim-q-bins`); with a spacing that does not divide the range the last bin is cut at the high limit. **Logarithmic** (`q_binning` = `log10`, `--azim-q-binning log10`) gives $B_q$ bins equally spaced in $\log_{10} q$, with edges $q_i = q_\mathrm{low}\,(q_\mathrm{high}/q_\mathrm{low})^{i/B_q}$, so a bin's width grows in proportion to its $q$ — dense sampling where the features of small-angle scattering are, coarse sampling at high $q$; it needs the number of bins. The $q$ reported for a bin (`bin_to_q`) is its centre on the binning scale: the arithmetic mean of its edges for linear bins, the geometric mean for logarithmic ones. The adaptive spot finder and the ice-ring score read their per-ring background off these same bins, so coarse logarithmic bins at high $q$ coarsen them as well. + +### 2.1 Histogram estimator + +Let bin index $b(x,y)$ be precomputed from $q(x,y)$ (or equivalently from $d(x,y)$) and, when $\phi$ sectors are enabled, the azimuth $\phi(x,y)$ — so $b = b_q + b_\phi B_q$. For each bin $b$: + +- accumulate corrected intensity and its square: + $ + S_b = \sum_{(x,y):\,b(x,y)=b} I(x,y)\,C(x,y),\qquad + S^{(2)}_b = \sum I(x,y)^2\,C(x,y)^2, + $ +- and count: + $ + N_b = \#\{(x,y):\,b(x,y)=b \text{ and pixel is valid}\}. + $ + +The profile reports both the mean $\bar{I}_b = S_b / N_b$ (when $N_b>0$) and a per-bin sample standard deviation $\sigma_b = \sqrt{(S^{(2)}_b - S_b^2/N_b)/(N_b-1)}$ (a spread/error estimate for each radial point). Invalid pixels (masked, saturated, detector error codes) are excluded. + +### 2.2 Corrections applied + +Two standard corrections are available: + +**(i) Solid angle / geometric correction.** A flat pixel's solid angle falls off with the **incidence angle $\alpha$ between the scattered ray and the detector normal**. With the in-plane detector offsets $u=(x-x_\mathrm{beam})p$ and $v=(y-y_\mathrm{beam})p$ — measured from the PONI (§1.1), which is what the tilt-invariance below rests on — and detector distance $D$, +$ +\cos\alpha = \frac{D}{\sqrt{u^2+v^2+D^2}},\qquad +C_\Omega = \cos^3\alpha, +$ +applied — like the polarization term below — as a **divisor** (intensities are scaled by $1/\cos^3\alpha$), so pixels at oblique incidence, which subtend a smaller solid angle, are boosted. Because $\alpha$ is evaluated in the detector's own frame it is **invariant under detector tilt** ($\mathrm{rot1}/\mathrm{rot2}/\mathrm{rot3}$), matching PyFAI's `solidAngleArray` and MAX IV azint. It reduces to the commonly quoted $\cos^3(2\theta)$ form only for an untilted detector, where the incidence angle coincides with the scattering angle. + +**(ii) Polarization correction.** With polarization coefficient $P$ (beamline dependent) and azimuth $\phi$: +$ +C_\mathrm{pol}(2\theta,\phi) = +\frac{1}{2}\left(1+\cos^2(2\theta) - P\cos(2\phi)\left(1-\cos^2(2\theta)\right)\right), +$ +applied as a divisor to intensities (i.e. scale by $1/C_\mathrm{pol}$) when enabled. This is the +factor of Kahn *et al.* (1982); $\phi$ is the azimuth in the **lab** frame, so the correction follows +detector tilt and a swung-out $2\theta$ arm without further work. + +The **polarization plane** is taken to contain the lab $x$ axis — a horizontally polarized source. +A vertically polarized one is expressed by a **negative** $P$: flipping the sign of the $\cos 2\phi$ +term is exactly a $90^\circ$ rotation of the plane. $P$ is the polarization *degree* (XDS's +`FRACTION_OF_POLARIZATION` is $(1+P)/2$). It is not fitted, because a single dataset does not +determine it, so it comes from the file where the file states it: a miniCBF `# Polarization` line and +a d*TREK `SOURCE_POLARZ` both give the fraction $f$, read as $P = 2f - 1$ (so a laboratory tube's 0.5 +is unpolarized), and `SOURCE_POLARZ` also gives the plane's normal, which sets the sign. Where the file +says nothing (ADSC SMV, marCCD, NXmx) the default $P = 0.99$, an undulator value, applies, with the +plane horizontal. The **plane**, unlike the degree, is measured: the beam-stop pre-scan compares the +background's $\cos 2\phi$ harmonic with the profile a polarized source gives it, and where the background +clearly follows the other plane (correlation above 0.5 and at least 0.3 of a fully polarized source's +modulation, but under twice it, which no source can give) the stated degree is applied in that plane - to the shadow test and, from then on, to the +integration and every other correction of the run. Elsewhere the plane stays as stated, so a run whose +beam stop is not detected (`--detect-beam-stop=off`) keeps the stated one. The background is pooled +over 9 x 9 pixels before the comparison, so that a sparse background - a fraction of a count per pixel +over the frames read, as on a large photon-counting detector - still gives the sectors a level. The same +decision is made for rotation sweeps and stills, and the log reports the correlation and the scale +(`Polarization plane:`) on every run that detects the beam stop. Bending-magnet and wiggler +beamlines are typically lower (0.8–0.95), and a known value for one should be passed with +`--polarization`. + +### 2.3 Background estimate for profiles + +A background estimate is derived from the profile as its mean intensity over a fixed low-to-mid $Q$ window (default $2\pi/5$ to $2\pi/3$ Å$^{-1}$). This background is used for monitoring and diagnostics; it is **not** the same as the local Bragg-spot background used in summation integration (§9.2). + +--- + +## 3. Spot finding (strong pixels → Bragg spots) + +Spot finding is a two-stage process: + +1. **Strong-pixel selection** using intensity and/or local signal-to-noise criteria. +2. **Connected-component labeling (CCL)** to group strong pixels into candidate spots, followed by spot-level filtering and feature extraction. + +### 3.1 Strong-pixel detection by local statistics + +For each pixel $i$ with value $v_i$, consider a square window (nominally $31\times 31$ pixels) around it. Let the window contain $n$ valid pixels (excluding masked/bad/saturated), and define: +$ +\Sigma = \sum v,\qquad \Sigma_2 = \sum v^2. +$ + +To avoid biasing the local statistics by the test pixel itself, Jungfraujoch evaluates the pixel against the window with the pixel removed: +$ +\Sigma' = \Sigma - v_i,\quad \Sigma_2' = \Sigma_2 - v_i^2,\quad n' = n-1. +$ + +A variance-like quantity proportional to $n'^2$ is formed: +$ +V = n'\Sigma_2' - (\Sigma')^2, +$ +and the deviation-from-mean quantity: +$ +\Delta = v_i n' - \Sigma'. +$ + +A pixel is considered strong if: +- it is above a photon/count threshold, and +- its window contains enough valid neighbours (more than 100), so the local statistics are meaningful, and +- $\Delta>0$, and +- the squared deviation exceeds a scaled variance: + $ + \Delta^2 > V\cdot T^2, + $ + where $T$ is the configured signal-to-noise threshold. + +This is equivalent to a local z-score criterion but implemented in integer arithmetic to be robust and fast. + +The test is applied in **two passes** over the image. The first is as described above. The second repeats it with every pixel found strong by the first excluded from the local background — it is treated exactly like a saturated pixel, so it contributes to no window it falls into and stays strong itself. This matters for any spot wide enough to reach into its own background box: on a single pass such a spot inflates the mean and variance it is then tested against, and its outer pixels fail the criterion. Excluding the core recovers them, so the spot is reported with its true extent rather than its brightest few pixels. Both the CPU and GPU implementations run these two passes and return the same spot list for the same frame. + +Special cases: +- saturated pixels can be forced to “strong” (useful for detecting overloaded Bragg spots), +- invalid pixels are never strong. + +### 3.2 Adaptive (self-calibrating) detection + +The local-statistics test above needs a fixed photon/count threshold whose correct value depends on the background level, which varies between datasets. The **adaptive** mode (`--adaptive-spots`; the default in `rugnux` and in the viewer for both stills and rotation data, `--no-adaptive-spots` reverts) derives that threshold from each image's own noise, per resolution ring, so no per-dataset value is needed. It admits more spots than the fixed threshold, including genuine reflections that belong to no indexed lattice; these are down-weighted rather than filtered in the per-image geometry fit (§7.4). + +Pixels are binned into the same resolution rings as the azimuthal integrator (§2). For each ring a robust background is estimated in three passes: one plain pass over all valid pixels, then two $\sigma$-clipping passes that keep only pixels within $\pm 3\sigma$ of the current ring mean (removing the Bragg peaks from the background estimate). This yields a per-ring background mean $\mu_b$ and scatter $\sigma_b$. + +The ring's detection threshold is the larger of two arms, +$ +t_b = \max\!\big(\;\mu_b + z\,\sqrt{\sigma_b^2 + \sigma_\mathrm{read}^2}\;,\;\; k_\mathrm{Poisson}(\mu_b, p)\;\big), +$ +where $k_\mathrm{Poisson}(\mu_b,p)$ is the smallest count whose Poisson$(\mu_b)$ upper tail is $\le p$. The Poisson arm is correct where the background is countable (a bright low-resolution ring gets a high threshold); the Gaussian arm — floored by a detector-level excess-noise constant $\sigma_\mathrm{read}$ — takes over on near-empty high-resolution rings, where the Poisson arm degenerates to "one photon is significant" and would flood. The operating point $p = E/N$ is set from a single portable knob $E$, the expected number of false pixels tolerated per frame (`--spot-false-pixels`, default 100), with $N$ the number of valid pixels. Because $p$ and every $\mu_b,\sigma_b$ come from the image itself, the same $E$ lands a sensible photon threshold on strong and weak datasets alike, with no per-dataset tuning. Rings too sparse to characterise (fewer than ~40 pixels) fall back to a whole-frame background. A pixel is strong when $v_i \ge t_b$ for its ring (saturated pixels are still forced strong); the strong pixels then feed the same CCL stage (§3.4). The ring threshold replaces the photon-count floor of §3.1; the local signal-to-noise test of §3.1 is still applied on top of it (unless `--spot-sigma 0`), so a strong pixel must pass both. + +Because detection reads the pixel's ring, a pixel that falls outside the azimuthal-integration $q$ range has no ring and can never be strong: the integration range bounds what adaptive detection can see. Both upper limits are therefore optional and default to the detector itself — the azimuthal integration runs to the highest $q$ any pixel of the detector reaches (`--azim-max-q` unset), and spot finding is not clipped in resolution (`--spot-high-resolution` unset), for rotation data as well as stills. Setting either one narrows detection accordingly — appropriate for weak, high-background data, where the spots admitted at the detector edge are dominated by noise. + +**Fused GPU engine.** The per-ring reduction the adaptive threshold needs is the *same* reduction the azimuthal integrator performs. On the GPU path the two are fused into a single image pass (`AdaptiveSpotFinderGPU`): one reduction accumulates the corrected per-ring sums for the azimuthal profile (§2) *and* the raw per-ring statistics for the threshold, after which a light kernel flags the strong pixels. One GPU pass therefore replaces both the separate azimuthal-integration pass and the host-side adaptive spot-finding pass, at a small fraction of the CPU finder's cost per frame and producing the same spot list and azimuthal profile. It is enabled by default in the offline `rugnux` path, the interactive viewer and the online receiver. + +**Online.** `spot_finding_settings` in the REST API carries `adaptive_threshold` and `false_pixels_per_frame`, so the mode is reachable from the broker and from the web frontend as well as from `rugnux` and the viewer. It defaults to *off* online, unlike `rugnux` and the viewer, because the broker serves both workflows and only one of them can run it: spots are found in software on the DECTRIS/SIMPLON path, while the JUNGFRAU and EIGER workflows find them on the FPGA at its own fixed threshold - except the live stills analysis of a JUNGFRAU collection, which analyses the converted frames on the GPU and always uses the adaptive threshold. Setting `adaptive_threshold` on an FPGA workflow is otherwise accepted and ignored, so the same spot-finding settings can be shared across detectors. + +### 3.3 Resolution and ice-ring handling + +Spot finding can be restricted to a resolution range $[d_\mathrm{high}, d_\mathrm{low}]$ by masking pixels outside the range. Optionally, spots in identified ice-ring regions can be tagged so that subsequent indexing/refinement may include or exclude them (see §4 and §6). + +A single per-image **ice-ring score** is derived from a radial profile: for each hexagonal-ice powder ring (see *Where the ring positions come from* below), the profile intensity at the ring is divided by a smooth background estimated from the *whole* profile — a running median of the non-ice bins, interpolated under each ring — and the strongest ring's ratio is reported (1 = no ice, $>1$ = ice above background). A whole-profile background is used rather than a couple of adjacent shoulder bins so the estimate is robust to the radial binning: at a coarse Q-spacing a local shoulder can be only ~1 bin and would double-count the ring's own edge (offline processing defaults to a fine 0.01 Å⁻¹ spacing — in $q = 2\pi/d$, like every $q$ in this document (§1.2) — `--azim-q-spacing`, so the rings are well resolved). The reported quantity is the ice *magnitude* rather than a significance: with many photons any real ice ring is statistically significant, so significance does not discriminate. + +The profile the score is read off is the **peak-excluded** one, not the plain azimuthal integration: where adaptive spot finding runs (§3.2 — the offline and viewer default), the score uses the sigma-clipped per-resolution-ring background that finder already computes for its threshold. This matters more than it sounds. A plain azimuthal profile is a per-ring *mean*, so a few strong low-resolution reflections landing in a ring's bin raise it exactly as ice would; measured over a rotation battery, that alone ranked ice-free crystals above crystals that really are iced. An ice ring is azimuthally smooth and survives the sigma clip, while Bragg peaks do not, so on the clipped profile ice-free crystals sit near 1 and crystals with confirmed ice above 2. Only where no adaptive finder ran (the FPGA workflow) does the score fall back to the plain profile. + +The radial profile sees ice only as a **smooth powder ring**. Ice in large crystallites diffracts as discrete spots, leaves the profile flat, and is invisible to the score above, so a second channel is read from the spot list itself: the spots found on the ice bands are counted against the spots found in the ice-free flanks $[w,2w)$ either side of each band, rescaled to the bands' own $q$ width (a flank landing on another ring is dropped with its width). The indicator is the ratio pooled over the run — per image the control is a handful of spots and the ratio means nothing — and it is taken before the spot-count filter, which orders ice spots last and would discard them first. The two channels barely overlap: smooth ice reads high on the profile and ~1 on the spots, textured ice the reverse, and a clean crystal ~1 on both. Both counts are stored per image (`spot_count_ice_rings`, `spot_count_ice_control`; HDF5 `/entry/MX/peakCountIceRingRes`, `/entry/MX/peakCountIceRingControl`). + +Both channels are used offline as a **gate** on ice handling: unless the run reaches `--ice-min-score` (default 1.5) on the profile or `--ice-min-spot-ratio` (default 2.0) on the spots — `--ice-min-spot-ratio 0` disables the spot channel, while `--ice-min-score 0` leaves the gate always open — ice-ring flagging and the exclusion from the scale fit (§10.10) are skipped. The fixed bands cover 16–26 % of the unique reflections at typical resolutions whether or not the crystal has ice, and more than that on a detector reaching past 1.5 Å, so handling ice on a clean crystal is a pure loss. The flagging itself (`--detect-ice-rings`) defaults on for rotation data and off for stills unless the file says otherwise. + +**Where the ring positions come from.** The eleven bands from 3.895 to 1.522 Å are the *measured* positions of Moreau, Atakisi & Thorne (Acta Cryst D77, 2021, 540–554). That list ends at 1.522 Å by its own scope — the paper states that hexagonal ice "has 11 diffraction rings between 4 and 1.5 Å resolution", and its subject was detecting ice in deposited data rather than masking it — not because ice stops there. On a detector that reaches further, the rings it does not list are the ones left in the data. + +The eight bands below it are **calculated**, since past that paper there is nothing measured to copy. Enumerating $hkl$ from the ice Ih cell is not enough: ice Ih is $P6_3/mmc$ with oxygen on $4f$, and most of what enumeration emits is extinguished by the *oxygen sublattice* rather than by the space group — which is why (004) at 1.830 Å and (104) at 1.657 Å are missing from the measured list even though they lie inside its range and its reflection conditions allow them (for even $l$ the $4f$ structure factor carries a factor $\cos 2\pi l z$ at every $hk$, and $z \approx 1/16$ kills $l=4$ — $(104)$ along with $(004)$). Structure factors are computed instead — oxygen only, the hydrogens being half-occupancy disordered and weak to X-rays — and the lines kept are those reaching 3 % of the strongest. That rule **reproduces the measured eleven exactly**, and every line it drops inside their range computes to zero, which is what makes it trustworthy below 1.522 Å. The cell is that of Röttger *et al.* (Acta Cryst B50, 1994, 644–648). The list stops at 1.170 Å because below it the calculated real lines fall to 2–3 % while the extinct ones rise to about 1 %, and an oxygen-only calculation cannot separate them any further. + +One consequence is worth stating: the profile score is the **strongest** ring's ratio, a maximum over the bands, so a longer list can only raise it. The gate at 1.5 is therefore read against a list of this length, and lengthening it again would need the gate re-checked. + +**Rings this sample actually shows.** Hexagonal ice is the only phase whose rings can be named in +advance, and it is not the only thing that powders: a shower of microcrystals around the crystal, or a +salt out of the cryoprotectant, leaves the same textured rings at $d$-spacings no fixed list carries, +and their spots are otherwise handed to the indexer as if they were this crystal's. The rings are +therefore also **measured from the run's own pre-scan spots** — read off as what stands above the +smooth fall-off of spot density with $q$ — on every run, and reported whether or not anything acted on +them (`POWDER_*` in the results report: the ring count, the fraction of the pre-scan's spots they +hold, and their $d$-spacings). The two lists are not the same list: a crystal can carry measured rings +that are not ice beside those that are. A measured ring is set aside from indexing only where a +first pass that found no lattice needs it set aside (§6); the fixed ice bands above are what the ice +score, the scale fit and the resolution cut read. + +A further optional safeguard removes isolated high-resolution “spur” spots by detecting large gaps in $1/d$ (or $q$) space and discarding spots beyond the gap. This is intended for macromolecular diffraction where edge-of-detector backgrounds can be extremely low. + +### 3.4 Connected-component labeling (CCL) + +Strong pixels are grouped into connected components (adjacent strong pixels) using a CCL algorithm. Each component yields a candidate spot with: + +- centroid $(x,y)$ (often intensity-weighted), +- pixel count (spot size), +- integrated spot intensity proxy (sum of pixel values), +- resolution $d$ at the centroid (or mean over pixels), +- and quality flags (e.g. ice-ring classification). + +Spot-level filters include minimum/maximum pixel count and resolution limits. + +**The upper bound is on how large a *round* spot may be, not on how bright one may be.** Under the self-calibrating threshold (§3.2) a component's area above the contour grows as $\sigma^2\ln(A/T)$ — without bound in the peak amplitude $A$ — so an upper bound on pixel count alone becomes an *intensity ceiling*: measured on a strongly diffracting crystal, footprints run 3 px at 30–100 counts to 50 px above 10 000, four times the slope the fixed local-box test gives, and the old bound of 50 discarded the brightest reflections on every image. The bound is therefore 200 (the same as CrystFEL `peakfinder8`'s `--max-pix-count`; XDS has no such parameter at all and guards on shape instead, with `SPOT_MAXIMUM-CENTROID`), and a component above 50 pixels must in addition **fill at least a fifth of the square its bounding box fits inside**. A Bragg reflection is round and fills about half of that square however bright it is; an ice arc, a cosmic-ray track or a lit detector row fills a fifth or less, which is what an upper bound was ever protecting against. Below 50 pixels no shape is asked for, so everything accepted before still is. The shape test is inert on every dataset it has been measured on — it exists to bound the *shape* of what the larger size bound now admits, on data carrying arcs or tracks, not because the crystals measured here needed it. The test is integer arithmetic, so the host and the GPU extractor agree by construction. + +The host implementation (`StrongPixelSet::sparseccl`) is the SparseCCL of the ACTS/traccc project: it +runs over the strong pixels sorted row-major, uses a sliding window over the previous line and a +union-find whose root is each component's lowest index. On the GPU the same labelling runs **on the +device** (`SpotExtractorGPU`): the packed strong-pixel bitmask is compacted into that same sorted +list without leaving the card, each pixel finds its at most four earlier 8-neighbours by binary +search, and a lock-free union-find with path halving labels them. Only the finished spot list — a few +hundred entries — comes back to the host, instead of the whole bitmask (2.26 MB per frame at 18 MP). +The two implementations produce the same components, in the same order, with the same pixel counts +and intensities; `tests/SpotExtractorGPUParityTest.cpp` holds them to it. The device version is also +insensitive to frame content: the host sliding window becomes quadratic when many pixels light up in +one detector line — a hot module, or a diffraction ring where it runs tangent to a row — which costs +tens to hundreds of milliseconds on such a frame, while the device version stays under a millisecond. + +### 3.5 Adaptive per-image minimum spot size + +The minimum-pixels-per-spot filter (§3.4) trades sensitivity against noise: a small value keeps faint one- or two-pixel spots — real signal on strong data, but detector noise on high-background frames — while a larger value keeps only well-formed spots. The best value is dataset-dependent, so for serial-stills indexing it can be chosen **per image** rather than fixed. The frame is scored at min-pix 2, 3 and 1, and the setting that maximises + +$$ \frac{n_\mathrm{indexed}^2}{n_\mathrm{total}} \quad\text{(indexed-spot count weighted by indexed fraction)} $$ + +is kept; the frame is then integrated once at that min-pix. The lattice is searched for only once per frame: the indexer runs on the min-pix 2 list (on min-pix 3 where that does not index), and the lattice of the first list that indexes is then refined and scored on the other lists - the lists are one crystal seen at different min-pix, and where several index, the searches return the same lattice. De novo, the min-pix 1 list is searched on its own only where the min-pix 2 list holds enough spots to index (the viable-cell minimum): a frame with almost no spot of two pixels has only single pixels to offer, and the cells a free search fits to those were measured to be unrelated to the crystal's. Against a known cell it is always searched - on sparse serial data such frames are real hits. The fraction factor discounts the extra spots a smaller min-pix admits *unless the lattice actually explains them*, so strong frames keep their real weak spots (extending resolution) while noise-flooded frames stay strict. Because min-pix filters the connected components *after* detection, strong-pixel detection AND the connected-component labelling both run **once** per frame, and the three attempts only repeat the spot-level filter; the azimuthal profile is the one that single detection pass computed. The winning attempt's spot list is kept rather than re-extracted, so the frame that is integrated is exactly the frame that was scored. This is a **stills-only, indexing-path** option — rotation indexing builds one global lattice from all frames and keeps a fixed min-pix. In `rugnux` it is the default; giving an explicit `--min-pix-per-spot` pins a fixed value instead. + +### 3.6 Predicting the resolution the merged data will reach + +A per-image **resolution estimate** is read off the finished spot list. It predicts how far the *merged* data will reach, not how far the furthest spot on this image lies. Each non-ice spot is weighted by $\sqrt{I}$ — the intensity is a summed photon count, so $\sqrt{I}$ is its Poisson significance — the $1/d^2$ is found beyond which a fraction $f=0.30$ of that weight lies, and the estimate is that resolution taken $2.25\times$ further in $1/d$. It is deliberately **not** limited to what the detector records: the quantile sits in the middle of the fall-off, well inside the recorded range, so it goes on measuring the crystal where the detector stops before the diffraction does, and on such a run it reads finer than the detector corner. The dataset value is the median over images. + +Both constants carry a mechanism. A quantile from the middle of the distribution measures the *shape* of the fall-off, which is the crystal's own $\exp(-B/2d^{2})$, where the extreme end of it measures where detection stops — a threshold that moves with the exposure and with how many reflections the unit cell puts on a frame. And merging averages many observations of each reflection, so intensities go on being measurable a fixed factor in $1/d$ past the point at which one image's spot finder still detects them; that factor is the $2.25$. Both are calibrated on rotation data against the resolution at which per-shell CC1/2 falls through 0.30, and the estimate is good to about 0.2 Å there. It is a prediction and not a measurement of what a run achieved: nothing downstream is cut on it, and it is reported alone (Rugnux `SPOT_RESOLUTION_ESTIMATE`, and per image in the stream, the plots and HDF5). diff --git a/_sources/CPU_DATA_ANALYSIS_INDEXING.md.txt b/_sources/CPU_DATA_ANALYSIS_INDEXING.md.txt new file mode 100644 index 000000000..aa83b6b9a --- /dev/null +++ b/_sources/CPU_DATA_ANALYSIS_INDEXING.md.txt @@ -0,0 +1,493 @@ +# Data analysis: indexing and geometry (§4–§7) + +Part of the [CPU/GPU data-analysis reference](CPU_DATA_ANALYSIS.md); the section numbers are continuous across its parts. + +```{contents} On this page +:local: +:depth: 2 +``` + + +## 4. Indexing overview + +Indexing maps observed reciprocal-space vectors $\mathbf{s}_i$ to a lattice such that: +$ +\mathbf{s}_i \approx h_i\mathbf{a}^* + k_i\mathbf{b}^* + l_i\mathbf{c}^*, +$ +with integer $(h_i,k_i,l_i)$. + +Jungfraujoch supports two complementary indexing strategies: + +1. **FFT-based indexing** (Rossmann-type): does not require an a priori unit cell; suitable for unknown samples. +2. **Fast-feedback indexing** (TORO-like): requires an approximate unit cell; optimized for speed and feedback (§4.3). + +Both feed into a common robust refinement/selection stage which maximizes the number of inliers under an indexing tolerance, and which can return **more than one lattice** per image (multi-lattice indexing; see §5.4). + +### 4.1 Indexed-spot decision (inlier test) + +Given a trial lattice with direct basis vectors $\mathbf{a},\mathbf{b},\mathbf{c}$ (used here as reciprocal-space dot-test vectors), fractional indices are estimated by: +$ +h_f = \mathbf{s}\cdot\mathbf{a},\quad +k_f = \mathbf{s}\cdot\mathbf{b},\quad +l_f = \mathbf{s}\cdot\mathbf{c}. +$ +Let $(h,k,l)=(\mathrm{round}(h_f),\mathrm{round}(k_f),\mathrm{round}(l_f))$ and define the fractional residual: +$ +\delta^2 = (h_f-h)^2 + (k_f-k)^2 + (l_f-l)^2. +$ +A spot is indexed if $\delta^2 < \tau^2$, where $\tau$ is the configured tolerance. + +For indexed spots, the reciprocal lattice point $\mathbf{p} = h\mathbf{a}^*+k\mathbf{b}^*+l\mathbf{c}^*$ is used to compute $\Delta_\mathrm{Ewald}(\mathbf{p})$ (stored as a diagnostic and later used in profile-radius estimation). + +A frame is taken to be this crystal's when at least a fraction $g = 0.20$ of its in-resolution, non-ice spots index. On rotation data that decision is what admits the frame to integration, so its denominator matters: every spot handed to it that is not a reflection of this crystal argues against the frame. Where it cannot do that job — a lattice whose pooled spots fall below $g$ and which fewer than half the validation frames clear — every frame is integrated instead: the frames that clear $g$ are then only the upper tail of the same sparse population, not the frames the crystal was in, and admitting them alone dropped most of a small-molecule sweep and its completeness with it. + +That test decides a **frame**. Whether a rotation run has a lattice **at all** is decided on the spots instead. A frame count comes from serial crystallography, where each image is its own experiment; a rotation sweep is one crystal and one orientation matrix, its frames are not independent of each other, and what such a count mostly measures is how many spots happen to land on a frame — a sweep carrying four spots an image cannot reach a six-spot bar on three frames in four however right the lattice is. The refusal therefore compares the fraction of *all* spots in the sampled frames that the lattice explains against what the same lattice explains when each frame's spots are put at **another frame's angle**: same lattice, same spots, same detector, same refinement, with only the claim that these spots were seen at *these* angles removed. That difference is the evidence, and it carries no spots-per-frame number anywhere, so nothing has to be chosen for a crystal that diffracts weakly. Measured over a hundred datasets the permuted level never exceeds 2.6 % and the smallest true margin is seventeen points. `--min-indexed-spots` (default 6, floor 4 — four is where a lattice stops being fitted by any three spots) still sets the reported indexing rate and the count the first pass *ranks* candidate lattices by; every rescue and every arbiter still counts frames. + +### 4.2 The spot budget + +Only the strongest `--max-spots` spots of an image are kept (`FilterSpotsByCount`), and that budget therefore sets the denominator above. Detections are not all reflections — background structure, unlisted ice and detector artefacts are found too — so a budget deeper than an image's reflections makes the test above a measurement of the background rather than of the crystal, and a *larger* budget can integrate *fewer* images. + +rugnux measures the budget instead of fixing it. With the sweep's lattice in hand, the first pass tallies the spots of a sample of frames by their rank in the intensity-ordered list: how many images carried a spot at that rank, and on how many of them it indexed. Weighting each indexed spot by $1-g$ and each unindexed one by $-g$ — the same weighting the frame test applies to the list as a whole — the running sum over ranks + +$$ E(N) = n_\mathrm{indexed}(N) - g\, n_\mathrm{counted}(N) $$ + +rises exactly while the spots at that depth lie on the lattice more often than $g$, and falls after. The budget is $\arg\max_N E(N)$. Its meaning is "as deep into the list as the image is still showing reflections of this crystal": deeper spots cannot help the frame test and can only push a frame towards rejection. On crystals whose spot lists are reflections all the way down the maximum is at the end of the list and the budget is unchanged. + +The peak has to be one. Under the null — the spots lie on the lattice at the same rate at every depth — $E$ is a driftless random walk in the counted spots, with per-spot variance $g(1-g)$, and the maximum of such a walk is positive whatever the data; an $\arg\max$ taken on its own would shorten every dataset, including one with nothing to shorten. What the budget acts on is the fall from the peak to the end of the list, $E(N^*) - E(L)$, which is the maximum of the same walk read backwards; by the reflection principle its null law is $P(\mathrm{fall} > z\sqrt{g(1-g)T}) = 2(1-\Phi(z))$ over $T$ counted spots in all, so the search over ranks is already accounted for and no further multiple-comparison correction applies. The budget is taken only where the fall clears that bar at $z = 3.29$, one false shortening in a thousand measurements; otherwise the whole list is kept. + +### 4.3 Fast-feedback indexing (known unit cell) + +The fast-feedback indexer (`ffbidx`, the TORO algorithm of Gasparotto et al. 2024) finds the +orientation of a **given** cell on a single still by brute-force sampling. With the cell vectors +$\mathbf{v}_j$ and the spots $\mathbf{s}_i$, and the per-spot term +$t(d) = \min(\max(d, 0.001), 0.3) + 0.1$ of the distance $d$ to the nearest integer, a sample is +scored $\exp_2\!\big(\tfrac{1}{n}\sum_i \log_2 t(d_i)\big) - 0.1 - n_\mathrm{good}$, lower is better: +the count of near-integer spots dominates, the mean term breaks ties. + +1. **Candidate vectors.** For each distinct cell-vector length $L$, each of 32,768 Fibonacci + directions $\mathbf{u}$ on the half sphere is scored with $d_i = |L\,\mathbf{u}\cdot\mathbf{s}_i - + \mathrm{rint}(\cdot)|$ and $n_\mathrm{good}$ the spots with $d_i < 0.2$; the best 32 are kept. +2. **Vector refinement.** Each candidate is refined by least squares against the spots within + 0.1, 0.05, 0.025 and 0.01 of its integer projections, in four rounds (at least 6 spots each). +3. **Cells.** The input cell is mirrored so that one of its vectors lies along a refined candidate + (and along its negative), then rotated about it at 1,024 angles; each sample scores the three-index + distance $\sqrt{d_a^2+d_b^2+d_c^2}$ with $n_\mathrm{good}$ the spots below 0.15. This runs for all + three cell vectors, $3 \times 64 \times 1024$ samples in all, and the best 32 cells go to the + common refinement of §5.4. + +**Centred lattices.** The indexer is given the Niggli-reduced **primitive** cell of the lattice, not the +conventional cell of a centred space group ($A$, $B$, $C$, $I$, $F$, $R$), and every lattice it finds is put +back into the given conventional cell by the integer matrix between the two, so everything downstream sees the +conventional basis. Given the conventional cell, the scoring above and the indexed-spot count of §5.4 work on +the primitive lattice of that cell, 2-4 times denser than the crystal's, and a wrong orientation that fits only +the extra nodes scores as well as the true one: rhombohedral stills in the hexagonal setting came back about +half obverse and half reverse, and orientations breaking a $C$, $I$ or $F$ centring were accepted. Every node of +the primitive cell is a possible reflection, so no centring condition is needed in the count. The reduction +matters as well: the plain primitive cell of an elongated $C$ cell has an angle outside the window the +refinement accepts. A primitive space group, a cell given without a space group and the FFT indexers are +unchanged. + +The algorithm has two implementations with the same samples, scores and output: the GPU library +(CUDA builds, when a GPU is visible) and an in-tree CPU port (`FFBIDXIndexerCPU`), which is used on +machines without a GPU, under `--no-gpu`, and in builds without CUDA. The CPU port scores a block of +samples against one spot at a time so the inner loop runs over samples and vectorises, and in step 3 +separates the rotation about the candidate out of the per-spot terms, leaving four multiply-adds per +sample and spot. Each frame is indexed on one thread; the frames run in parallel. The two +implementations agree to rounding, not to the bit, so two near-equal samples can come out in either +order. + +--- + +## 5. FFT indexing (unknown unit cell) + +FFT indexing follows the classical approach of Steller, Bolotovsky & Rossmann (1997), the one-dimensional form of the Fourier-transform indexing proposed by Bricogne (1986): detect dominant periodicities by projecting reciprocal-space points onto many directions and Fourier transforming the resulting 1D histograms. + +### 5.1 Directional projections and histograms + +Choose a set of unit vectors $\{\mathbf{u}_d\}$ on a half-sphere (a near-uniform distribution generated via a golden-angle construction). For each direction $d$, form a histogram in the scalar projection: +$ +t_{id} = \left|\mathbf{u}_d\cdot \mathbf{s}_i\right|. +$ + +Bin width is chosen approximately as: +$ +\Delta t \approx \frac{1}{2 L_\mathrm{max}}, +$ +where $L_\mathrm{max}$ is the maximum expected real-space unit-cell edge (Å). The histogram extent is tied to the maximum $q$ used (set by a high-resolution cutoff for indexing). + +### 5.2 FFT peak picking and candidate vectors + +For each direction, the FFT magnitude spectrum is computed; peaks correspond to periodicities along $\mathbf{u}_d$. Each direction yields a candidate real-space length $L$ chosen **not** by raw magnitude but by **maximum prominence above a running-mean local background** (subtracting the broad low-frequency envelope that otherwise dominates on weak or pink-beam frames), subject to $L\ge L_\mathrm{min}$. + +The running-mean background window keeps a **constant width** and is slid inward at the ends of the spectrum rather than truncated there, so a peak within half a window of either end — which is where the longest cells sit — is judged against as much background as any other. Both window bounds stay monotonically non-decreasing in the bin index, so the GPU kernel's running sum is still valid. + +The longest basis vector the transform can return is `fft_max_unit_cell_A`, since the histogram is sized from it and its last usable bin *is* that length; the shortest is `fft_min_unit_cell_A` (`rugnux --fft-min-unit-cell`, default 10 Å), below which a candidate is discarded. The defaults are unchanged (500 Å and 10 Å), but the accepted range for the maximum now reaches 1200 Å, and a reference cell given with `-C` moves **both** bounds on its own — up to reach a long axis, down to admit a small-molecule cell — since a cell the search cannot represent cannot be found by it. A de-novo rotation run asks the long end a second time as a **long-axis hypothesis**: the detector separates the rows of an axis of length $L$ while their spacing near the beam, $D\lambda/L$, exceeds the measured spot width, so wherever $D\lambda/(p\,r_{80})$ ($p$ the pixel size, $r_{80}$ the pre-scan's spot width) exceeds the standard bound, a coarse search (3.5 Å histogram) to that length, at most 1200 Å, offers its lattices. Each is re-indexed at full resolution with its cell as the reference, and the one putting the largest share of the pooled validation spots on itself beyond chance replaces the standing lattice where that share is significantly larger (the pooled-spot comparison the first pass uses for every competing lattice) — except an exact superlattice of the standing cell, for which the pooled count is biased and which is left to the supercell probe of the merge. It is asked of every such run, whatever the standing pass indexed: a wrong axis along a fine row still indexes most frames. Its searches are started ahead of the question - the coarse one beside the file centre's schemes, the re-index of what it offers beside the beam-centre check - and the question then reads their answers from the indexer's memo: this changes when they run, not what they find. + +Candidate vectors are $\mathbf{v}_d = L_d\,\mathbf{u}_d$. + +A collinearity filter removes nearly parallel vectors (e.g. within 5°) and attempts to resolve harmonic ambiguity: shorter “fundamental” vectors may be preferred over longer harmonics if their peak magnitude is sufficiently strong relative to the dominant peak. + +**Rows shorter than the floor (rotation).** The per-direction peak search starts at $L_\mathrm{min}$, so a lattice row whose repeat is shorter — common in small molecules, absent in proteins — is reported at a multiple of itself past the floor, and a cell built from such rows is an exact integer supercell of the true one. The spots can tell a row from its multiple where the histogram cannot: summed at the row's own length every spot is in phase whichever of the two it is, but at a whole fraction $L/k$ of it only the spots of a lattice whose row that fraction is stay in phase. So on a rotation run every shortlisted row reported within $3L_\mathrm{min}$ is asked, by a direct sum over the accumulated spots, at each $L/k$ between 3 Å (the minimum cell of DIALS' fft3d) and the floor, and the shortest fraction that keeps at least half the row's amplitude replaces it. The cells of these rows are reduced and refined **beside** the standard ones, not instead of them, and ranked with them (§5.4): where a cell and its supercell index alike, the smaller is kept. Stills keep the standard search. + +### 5.3 Lattice reduction and cell candidates + +Triples of candidate vectors are combined to form candidate bases $(\mathbf{A},\mathbf{B},\mathbf{C})$, each reduced to its **Niggli-reduced cell** (Gruber-vector reduction) before comparison, and filtered by allowed length and angle ranges. Two passes are run: a standard pass forms shortest-vector triples from the ~30 strongest filtered directions; if the best cell then indexes fewer than half the spots, a **widened fallback** anchors the two shortest axes and lets the third range over up to ~60 candidate vectors (deduplicated by Niggli cell), catching large, elongated or superstructure cells the first pass misses. + +A triple whose three vectors are **coplanar** is rejected before refinement. The length and angle filters cannot see it — any flat combination satisfies them — and a cell that flat has a metric determinant small enough for `float` to get its *sign* wrong, after which the guard against a negative argument to the square root places $\mathbf{c}$ in the $\mathbf{a}$-$\mathbf{b}$ plane, the reciprocal volume diverges and the solver reports a not-a-number Jacobian. The test is the volume fraction $|V|/(|\mathbf{a}||\mathbf{b}||\mathbf{c}|)$, which must reach 0.02 — about 1.1° off flat, well below the flattest genuine candidate observed and far above where `float` loses the sign — and it is applied both where triples are produced and at the optimizer's entry points. + +A shortlist **confined to one plane** cannot close a cell at all, and the row it is missing is the plane normal. That is detected from the eigenvalue ratio of the shortlisted directions' scatter matrix, and one further transform is then spent with the same direction count inside a narrow cap about the normal. More directions do not substitute for it: at the exact true direction a very long axis can still rank far below the shortlist cut, so for **this** rescue the obstacle is the ranking rather than the sampling, and a denser grid costs several times the device memory for the same answer. + +Sampling has a limit of its own, and it binds well before the 1200 Å the accepted range for `fft_max_unit_cell_A` admits (§5.2). A direction off a real-space axis of length $a$ by an angle $\theta$ smears each projected lattice plane by about $\theta/d_\mathrm{min}$ in the projection, so the planes (spacing $1/a$) stay resolved only while $\theta \lesssim d_\mathrm{min}/(2a)$. The shipped grid of 16384 directions puts the nearest one within about 0.6° of any axis, which satisfies that bound only up to roughly 120–150 Å at typical indexing resolutions; a longer axis is not refused but returned as a plausible sub-cell or harmonic. Raising the maximum cell alone therefore does not extend the reach — the direction grid has to resolve the axis before the histogram can represent it. + +### 5.4 Robust refinement and best-cell selection + +Candidate bases are refined against observed spots using an iterative inlier‑focused least‑squares procedure (trimmed/contracting threshold). Candidates are then ranked: +1. more indexed spots wins — **unless** two candidates index within ~10 % of each other, in which case +2. the **smaller-volume** cell is preferred (when the volumes differ by more than ~5 %), avoiding a doubled supercell, then +3. the smaller refinement score, then the spot count again. + +Selection is **not limited to a single lattice**: after the best cell is accepted, further lattices are added as separate crystals provided fewer than ~40 % of their indexed spots overlap an already-accepted lattice (up to two extra by default), so split or multi-lattice crystals are indexed rather than discarded. + +A candidate dropped only for its overlap with a lattice that **contains** it or is contained by it — an integer supercell or sub-cell, the rows of the larger cell integer combinations of the smaller's — is kept nonetheless, after every cell the test accepts: that overlap is total by construction and says nothing about which of the two is the crystal's. The rotation indexer refines these too and may choose one (a sub-cell that indexes as well, §5.2); the integer supercells of the cell it chooses are carried with it, so that the twin-composite test of the first pass, which asks whether a cell is the coincidence lattice of two twin domains, can also be asked of them when the search has offered a domain's own cell. Kept cells are never taken as extra crystals: those must share the first lattice's metric. + +An optional reference unit cell (if supplied) restricts acceptance to cells within a relative distance tolerance in edge lengths (permutation-invariant). + +### 5.5 Spindle alignment: the part of the blind cone symmetry cannot repair + +A sweep about the spindle $\hat{\mathbf{e}}$ never brings a reciprocal point closer than +$\theta_\mathrm{max}=\arcsin(\lambda/2d)$ to the axis onto the Ewald sphere, so a double cone of +half-angle $\theta_\mathrm{max}$ is missing from every resolution shell — each shell losing its own +$1-\cos\theta(d)$ — however long the sweep runs. Crystal symmetry normally repairs that loss by +mapping the cone onto measured territory. It fails to when a symmetry axis lies inside the cone (the +cone maps onto itself) — and, for a **2-fold**, equally when the axis is perpendicular to the +spindle, because the diad carries the cone onto its opposite lobe, which the sweep leaves just as +unmeasured. Friedel never helps: the cone is double-sided. The loss is a coherent cap rather than a +scatter of absences, so it costs a map more than the same percentage lost at random. + +The per-image score asks how much of that cone the frame's own orientation makes unrecoverable. +The crystal's short lattice rows are read off the FFT row shortlist of §5.2 (a symmetry axis is +always a lattice row, and usually among the short ones), and each plausible direction is scored as +if it carried a lone 2-fold: + +$$ \text{spindle blind fraction} = \frac{2}{\pi}\left(\arccos x - x\sqrt{1-x^{2}}\right), +\qquad x = \min(\beta,\,90^\circ-\beta)\,/\,\theta_\mathrm{max}, $$ + +where $\beta$ is the direction's miss-angle from the spindle. The **fold** of $\beta$ about +$45^\circ$ is the diad geometry above: both ends of the range are the bad case, and the closed form +reproduces a Monte Carlo of the true double-cone self-overlap to 0.004 at +$\theta_\mathrm{max}=15^\circ$ and 0.008 at $25^\circ$ (past $45^\circ$ it under-reports, by 0.05 +at $50^\circ$). $\theta_\mathrm{max}$ is taken from the **geometric** resolution of the setup — the +detector corner at the recorded distance and wavelength — an upper bound on any sweep collected +without moving the detector; the still's own spot resolution would understate the cone on exactly the +weak frames that mislead. The worst direction wins, and the directions scored are the strong +in-window rows **and the normals of their pairs** — the normal to two lattice rows is itself a +reciprocal-lattice row and a symmetry axis is parallel in both bases, so a lone 2-fold on an axis far +beyond the length window (a long monoclinic unique axis) is still seen by direction. +Nothing about the goniometer enters: the number describes the problem and leaves the remedy — +a second sweep, a reorientation — to the beamline. + +**This is a worst-case bound under an assumption of no symmetry, not an estimate.** A still cannot +know the point group, so the nearest plausible row is scored as a lone 2-fold. An axis of order +$\geq 3$ perpendicular to the spindle in fact **fully repairs** the cone (measured unrepaired +fraction 0.000 for orders 3, 4 and 6, against 1.000 for a diad), which a still cannot see, so the +bound is deliberately pessimistic on higher-symmetry crystals — that is the intended trade, because +the number exists as a **trigger** for beamline automation, not as a physical quantity a user +interprets. + +**Trigger states.** The stored quantity is the continuous score; automation reads it through three +fixed states with nothing to tune (`SpindleTrigger` in `SpindleBlindFraction.h`): **engage** at +score ≥ 0.5, **don't engage** below, and **cannot say** when there is no value at all — too few +spots, no shortlist, the consistency guard refused, the path never computed one. **Automation must +treat CANNOT SAY as ENGAGE**: the error costs are asymmetric — a false negative is unrecoverable +(one sweep is collected and the data stay short forever) while a false positive costs minutes of +beamtime. Every transport keeps absence distinguishable from a measured zero (an absent CBOR key, a +NaN in the HDF5 arrays, an absent optional after read-back). The 0.5 threshold is geometry, not +tuning: the score is monotone in the folded miss-angle, so a threshold is a fold-angle gate, and 0.5 +gates at $\min(\beta,90^\circ-\beta) \le 0.404\,\theta_\mathrm{max}$; engaging on any overlap at +all would gate at the cone edge, whose perpendicular band alone spans $\sin\theta_\mathrm{max}$ of +orientation space per row (26 % at $15^\circ$) and unions over a frame's rows to well over half of +all mountings — a trigger that always fires decides nothing. + +**Reach and honest rates.** The score needs 60 spots (calibrated per crystal — 22 independent +mounts — misses triple below it); below that, a frame that still indexed answers from the winning +lattice's shortest rows, and otherwise the state is *cannot say*. Because the bound is pessimistic +by design, it engages on a substantial share of harmless mountings: a single strong row's +perpendicular band alone covers ~11 % of orientation space at the severe level +($\theta_\mathrm{max}=15^\circ$), and the union over a frame's rows and pair normals reaches +roughly a quarter to three quarters of random mountings depending on cone width and row count +(measured 0.74 on a generic triclinic cell at $15^\circ$ via the lattice path). That is accepted: +the cheap error is the extra wedge. An earlier figure of ~1 % false alarms (AUC 0.948) came from a +null of five *decoy directions per frame* — it shows the estimator does not hallucinate rows near +arbitrary directions, which is worth knowing, but it is **not** a false-alarm rate over harmless +mountings, which geometry forbids to be that low. + +**Offline, the guessing stops.** Once `rugnux` has merged a rotation run it holds the measured +point group and the exact indexed orientation, and the run-level number is computed exactly instead: +the group's proper rotations are applied to the blind double cone in the crystal's actual +orientation, and the fraction of unique reflections no operator can recover is reported as +`SPINDLE_LOST_UNIQUE_FRACTION` in the processing report and `/entry/MX/spindleLostUniqueFraction` in +the master file ([the results report](RUGNUX_REPORT.md)). That number clears or convicts a mounting the per-image +bound can only be pessimistic about: a dihedral crystal with an in-plane diad on the spindle, or any +cubic crystal in any orientation, loses nothing at all. + +--- + +## 6. Bravais lattice / centering inference (“lattice search”) + +If the space group is supplied by the user, its lattice constraints are assumed for refinement and subsequent processing. + +If not, Jungfraujoch attempts to infer the most plausible Bravais lattice type from the metric tensor after Niggli reduction: + +1. **Niggli reduction** is performed to obtain a reduced cell in $G^6$ representation (Gruber vector). +2. The reduced cell is compared against a list of Niggli classes corresponding to Bravais lattices and centerings. +3. The highest-symmetry class that matches within tolerances is selected (relative metric tolerance and angular tolerance). The list is walked in order of decreasing symmetry and the first class that fits is taken, so a class that only just fits can pre-empt a lower-symmetry one that fits exactly. + +The output includes: +- a conventional cell, +- crystal system (triclinic, monoclinic, …), +- centering symbol (one of $P, C, I, F, R$; the $A/B$ variants are not emitted here — they are handled only later as prediction absences, §8.4). + +This stage provides centering information used for systematic absences in prediction (§8.4) and for reporting. + +**A metric symmetry has to earn itself.** The class is chosen from the *unrefined* candidate against a fixed angular tolerance (3°), so a lattice that is pseudo-symmetric to a few tenths of a degree is promoted a class too far — and the constraint then snaps a real angle to the ideal one, which throws nearly every reflection of every frame outside tolerance. Measured on a monoclinic crystal pseudo-C-orthorhombic to 0.42°, the promoted cell indexed 2 of 60 frames where its own primitive cell indexed 39: the same lattice, $\mathbf{b}_{oC}=-(\mathbf{a}+2\mathbf{c})$, at exactly twice the volume. A more accurate candidate is more likely to be promoted, not less: a run escapes the promotion only when the raw candidate misses the tolerance window. + +The lookup can also land *short*: near the Niggli type-I/type-II boundary the character is decided by the last digits of the refined cell, and the class it names caps which point groups the space-group search enumerates. The metric-symmetry re-ask of §13.1 covers this — rotations the named class has no room for are put to the intensities directly, and where the metric group exceeds the class's holohedry the merge is reindexed into the metric cell and the search re-run there. + +The rotation first pass refines the **twelve** best candidate lattices rather than four. The pre-refinement indexed fraction is an unreliable ranking, so a correct cell can sit below several degenerate ones and never be refined at all. + +For rotation data the first pass therefore refines the constrained cell *and* an unconstrained (triclinic) one from the same spots — which it finds itself, over a sample spread across the first part of the sweep (the part the geometry pre-pass integrates), rather than reading what the acquisition wrote — and settles the two on how many of a fixed set of validation frames each actually indexes. The bar is a clear majority, not a margin. An unconstrained refinement holds no cell parameter fixed, so it can only index at least as many frames as the constrained one, and on genuine symmetry it indexes a few more — a percentage margin therefore demotes real lattices (measured: a genuine $I$-centred orthorhombic to $P1$). Only a constrained cell that fails outright while its unconstrained cell works distinguishes a false promotion. The intensities settle the space group later regardless (§13). + +A further hypothesis is weighed at the same point, by default. Where two first-pass answers +have primitive volumes in a small integer ratio (2–4×) and tie on the validation frames, the frame +count has saturated — a spurious axis multiple indexes every frame its true sub-cell does — and no +count of spots can settle the pair either: the larger lattice contains the smaller one, so it fits every +spot at least as well, whatever the crystal. The pass therefore keeps the **smaller** cell, whichever +scheme found it, and the larger one is decided where it can be, on integrated intensities: integrated on +the smaller cell, the reflections an index-2 multiple adds are one of the supercell probe's half-integer +classes, read against the six others as their null (see the +[report](RUGNUX_REPORT.md#index-2-superstructure)), and the doubled-cell hypothesis merges the larger +cell and adopts it where that class grows to a quarter of the lattice's intensity or holds it at every +resolution. An index-3 or index-4 pair is kept at its smaller cell and is not tested. A row shorter than the 10 Å +floor of §5.2 needs no hypothesis of its own: the search offers its cell directly (§5.2). + +The reverse is also tried on every rotation first pass, because the FFT can only offer the cells its peaks +build: two lattices seen together - a twin domain, a second crystal - build the cell that contains both, which +indexes every spot of either and so wins every frame count, and the true cell is then never offered. The +standing cell's sub-lattices of index 2, 3, 5 and 7, in its own orientation, are scored on the validation +frames, and one is adopted where the standing cell's extra nodes - the ones the sub-lattice drops - hold no +spots of their own beyond what a wrong spindle angle would put there, and the sub-lattice still indexes a +majority of the frames. It is asked again of each sub-lattice adopted, so a cell doubled along several axes +comes down to the true one a halving at a time; a real superstructure keeps its cell, because the class it +adds holds reflections. + +**A near tie is decided on every frame - from the start offline, late on a live run.** A run on a +stored file has the whole sweep from the start, so its first pass decides each near tie that later +frames could tip (the lattice, the indexing path, the beam centre, the spot-finding settings) on +validation frames from the whole sweep at once, with nothing to check again. A live run - one following +a collection that is still being written (`rugnux `, or `--simulate-live` on a +stored file) - cannot wait for frames that do not exist yet: its first pass decides on validation +frames from the start of the sweep, so it can act at once. Where one of those decisions was a near tie, +the pass is run again once every frame is in, on a copy of the run taken as it began and deciding on +the rest of the sweep too, and only where that re-check ends elsewhere is the whole run made again with +every near tie decided late; a run that found no lattice after carrying a near tie is made again +likewise. Both give the answer that deciding late throughout gives; the live run pays for it with the +re-checks, about a second each. The checks taken on the +pre-pass frames - the geometry walk's refits, the metric-symmetry arm and the pre-pass spot-crowding count - stay on those frames +in both modes, and their near ties are re-checked once every frame is in on both. + +**A first pass that ends with no usable lattice tries a leaner, shallower one.** A crystal sitting in +a crystalline powder floods the pass with spots that are not its own — measured, 2112 spots a frame +against the 80 a clean crystal on the same beamline gives — and the FFT then takes its cell out of the +powder shells. So the pass is retried over **how much of each frame it reads**: the strongest 30, 80, +200 or all spots an image, each at the file's resolution and at the resolutions a quarter and a half +of this sample's own spots lie coarser than, with the rings measured in §3.3 set aside where there are +any. The rungs are decided late, on the validation-frame count — the way the rotation-axis sign +already is — and one is adopted only on a win of a sixth of the frames. The same ladder is asked +inside the beam-centre check of §1.4, where a centre that is wrong and a spot list that is too deep +otherwise hide each other. + +A rung whose cell is an axis multiple of another rung's is not judged on its spots either: the ladder +takes its winner, and the class a larger cell would add is read on the integration, as above. + +**Note.** In ambiguous or special cases, forcing space group to $P1$ (no symmetry assumptions) is recommended. + +--- + +## 7. Geometry and lattice refinement + +Refinement adjusts experimental geometry and crystal parameters to minimize discrepancies between observed spot reciprocal vectors and those predicted by a lattice model with integer indices. + +### 7.1 Parameterization + +The refinement jointly optimizes, depending on mode and constraints: + +- beam center $(x_\mathrm{beam}, y_\mathrm{beam})$, +- detector distance $D$, +- detector tilt angles (two-angle model; third rotation often held at 0), +- rotation axis direction (for rotation datasets), +- crystal orientation (a global rotation), +- unit-cell parameters, with constraints determined by inferred crystal system. + +The detector distance is not refined against one crystal's spots at all: the positional residual leaves it degenerate with the cell scale, so it is fitted elsewhere - by the rotation post-refinement, which frees it alongside the whole crystal and adds the distance-independent rocking-angle residual that breaks the degeneracy, and by the stills `--refine-geometry` bundle. Per image, the beam centre and the crystal orientation are refined, and the unit cell as well for stills. The first-pass rotation indexing refines the detector tilt and the rotation-axis direction too, against the spots accumulated across the sweep; everywhere else both are held fixed, because on a single crystal a tilt is absorbed almost exactly by the crystal orientation. A lighter **orientation-only** mode refines just the crystal orientation, for stills whose geometry is already trusted. It carries a weak small-rotation prior penalising the whole angle-axis vector (all three components, at a low weight); what it is there for is the poorly-determined out-of-plane component, which is the one the data barely constrain. + +For higher symmetries, constraints are enforced, e.g. +- cubic: $a=b=c,\ \alpha=\beta=\gamma=90^\circ$, +- tetragonal: $a=b$, +- hexagonal: $a=b,\ \gamma=120^\circ$, +- monoclinic (unique axis $b$): $\alpha=\gamma=90^\circ$, $\beta$ refined. + +### 7.2 Residuals and objective + +For each indexed spot assigned integer $(h,k,l)$, compute: + +- observed reciprocal vector $\mathbf{s}_\mathrm{obs}$ from its detector position and current geometry, +- predicted reciprocal vector $\mathbf{s}_\mathrm{pred}(h,k,l;\ \text{lattice params})$. + +Residual is: +$ +\mathbf{r} = \mathbf{s}_\mathrm{obs} - \mathbf{s}_\mathrm{pred}. +$ + +A non-linear least squares solver minimizes $\sum \|\mathbf{r}\|^2$ over all selected inlier spots. + +### 7.3 Rotation datasets: bringing observations to a common reference frame + +For oscillation/rotation data, each image corresponds to a rotation angle $\phi$ about an axis $\mathbf{m}_2$. Observed reciprocal vectors are rotated “back to start” so that all images are refined in a single reference crystal frame: +$ +\mathbf{s}_\mathrm{obs,ref} = R(\phi)\,\mathbf{s}_\mathrm{obs}, +$ +where $R(\phi)$ is the rotation by $+\phi$ about the goniometer axis **as stored in the file**. The sign is a convention and it is load-bearing: rotating the observations forward by $+\phi$ means the crystal itself turns by $-\phi$ about that stored axis, i.e. $R(\phi)$ is the *inverse* of the crystal's own rotation from the reference orientation to frame $\phi$. The same convention is why the unmerged-MTZ batch headers and the XDS geometry echo carry the axis **negated** relative to the input file ([Rugnux ▸ the unmerged export](RUGNUX_INTEGRATION.md#the-unmerged-export)) — a reimplementation that takes $R(\phi)$ as the crystal rotation must use $R(-\phi)$ here instead. The angle $\phi$ is taken at the centre of each frame's oscillation (the frame angle plus half the oscillation width). + +### 7.4 Multi-stage tightening of inlier tolerance + +Refinement is performed in stages with decreasing acceptance tolerance for including reflections (three stages, indexing tolerance $0.3\to0.2\to0.1$), which stabilizes convergence when starting from imperfect indexing and approximate geometry. + +The loose first stage necessarily admits some spots that are not reflections of this lattice — the fraction of *randomly* placed spots inside a fractional-Miller tolerance $t$ is $\tfrac{4}{3}\pi t^3$, i.e. 11 % at $t=0.3$ — and an unweighted fit lets them pull the orientation. Each residual is therefore weighted by how strong its spot is **for its resolution**: the frame's spots are cut into equal-count resolution shells and each intensity is divided by its shell median, mapped to $w^2=r/(1+r)$. The shell normalisation is what makes this safe — genuine high-resolution spots are legitimately weaker and carry the cell and distance information, so an un-normalised intensity weight would suppress exactly the spots the fit needs. The weight is a property of the spot and never of the current residual, so it does not depend on how far the geometry is from convergence. + +**A rotation frame's refinement is restrained toward the sweep.** A frame is integrated on the orientation and beam centre refined against its own spots, starting from the sweep's geometry. Where the crystal really moves the refined orientation follows it, and integrating on it is what keeps such a sweep together. Where a frame has few or poorly placed spots the same fit can instead jump on its own, by up to a few degrees, which drops strong reflections out of prediction on the frame they peak on. So after the geometry pre-pass, which refines its frames freely, each integrated frame is fitted twice: freely, for the scale $\sigma^2$ of its own weighted misses, and then from the sweep again with a Gaussian prior on how far it moves, minimising $\sum_i w_i^2\|\mathbf{r}_i\|^2/\sigma^2 + \sum_k \theta_k^2/\tau_k^2$ over the orientation and beam-centre shifts $\theta_k$ (the orientation's as the three components of the rotation from the sweep's orientation, so that its width means the same in every direction however the crystal sits in the laboratory). Both fits of such a frame are made with the spindle given, as over a sweep, so the beam centre's component along the spindle - which on a single frame nearly trades against the orientation - carries the same weak restraint toward the start that it carries in the sweep refinement. The widths $\tau$ - one for the orientation, one for the beam centre - are measured once per run on the pre-pass frames, as the root mean square of the seven-frame running median of the free shifts of the frames whose fit succeeded (a frame too sparse to fit keeps the sweep's geometry, which is not a measurement of how far it moves) (the track's smooth part, which a jump on one frame does not reach). The prior is centred on the sweep's orientation in the metric the fit holds the cell to - the frame's free-fit lattice turned to sit closest to the sweep's - and the shifts are measured as rotations from it, so that a sweep lattice with a metric of its own (a free cell a few tenths of a degree off the symmetric one the fit holds) does not count its strain as a shift; and the orientation width is never narrower than the angle by which that best held orientation still misses the sweep lattice's vectors, since that much each frame must be free to turn to fit its own part of the sweep. There is no gate: the data of each frame decide how far it moves, a frame with many well placed spots following a moving crystal and a sparse one staying near the sweep. Each frame is still refined on its own spots, independently of the others. The frames the first pass scores candidate lattices on and the pre-pass keep the free refinement of a single frame, without the spindle form as well as without the prior, so the lattice, the geometry the run refines and every decision the pre-pass takes do not depend on either, and stills are not affected. + +**The rotation chain commits its best round, not the round it stops on.** After the winning candidate is selected, the refinement is run again — solve, re-accumulate the reciprocal-space cloud under the refined geometry, solve again — up to twenty times, and the loop stops on a test of the detector-tilt step. The chain is a trajectory and its last point is not always its best one: every solve ends by fitting only the spots inside its **tightest** gate, so a cell with a direction the data barely constrain (which is what a free cell whose metric is near a Bravais class has) can slide along it, pulling a core of spots tighter while the periphery falls out of the fit altogether. Measured on such a chain, the spots inside the tight gate rise over seventeen rounds while the spots inside the widest gate peak at round three and fall away — and round three is the round that merges at ISa 11.0 against 6.3 and $R_\mathrm{meas}$ 0.148 against 0.213. Nothing the run consulted could see it: indexed fraction, validation frames, validation spots and the tight-gate count all prefer the overfitted end. + +So every round is scored on the **widest** gate — the population the first pass selects on and the last pass does not fit, which makes it the one a converged solve is not optimising — and the best-scoring round is committed. Two conditions keep that from acting on noise. The score is a *count* of spots, so a lead of fewer than $\sqrt{\text{count}}$ of them leaves the last round standing. And the round taken has to be the less distorted lattice as well as the better-fitting one: the lattice search (§6) is re-asked every round to **measure** how far the cell sits from the ideal metric of the class it matches (imposing that class is measured fatal — the snap puts almost everything outside the refinement's own gate), and an earlier round is taken only when it matched the *same* class and sits closer to it. Same class is a precondition and not a precaution: the deviation is a fraction of whichever class's tolerance admitted it, so two classes' deviations are not the same quantity, and a round that matched no class reports zero, which means "nothing was asserted" rather than "undistorted". A chain that has settled scores its rounds within a spot or two of each other and a symmetry-constrained solve holds its distortion at zero throughout, so the rule fires on neither: measured over 914 chains, an earlier round scores higher on 44 % of them and the committed round changes on 1 dataset in 54. + +**A tilt no mounting can have has to prove itself.** The detector tilt is refined freely because on a sweep whose spots reach far enough in $2\theta$ it is a measurement, and restraining it costs those crystals resolution and ISa. What makes it a measurement is the *keystone* — a tilted plane puts one side of the detector nearer and the other further, so the spots move by an amount that grows with their distance from the beam — and a first pass made of spots reaching a few degrees of $2\theta$ sees a keystone of a pixel or two at most. To such a fit a tilt is a whole-pattern shift the beam centre imitates exactly, its size is whatever the centroids' own systematics happen to prefer, and the value it commits then mispredicts the far corner of the detector by tens of pixels against an integration disc of a few, and the run can lose most of its resolution to it. For a tilt of a few tenths of a degree nothing in the spots says whether it is real — the held-out positional residual, the rocking angles and a re-fit at the header tilt are all equally insignificant on a crystal whose tilt is real and on one whose tilt is the artefact — so below what a mounting can be off square by the fit is trusted as before: a detector is mounted square to the beam to a fraction of a degree. A chain that has walked more than 1° from the tilt it started at has either measured nothing or found a detector the file misdescribes (a $2\theta$ arm swung out that the file records as square), and at that size the spots *do* tell the two apart, because a real tilt of degrees has a keystone of tens of pixels over the spots the fit is made of and an artefact has none. So the candidate is refined again from where it started with the tilt held there — the beam centre takes the shift the tilt is equivalent to — and the two are judged as the rounds of one chain are, on the spots each indexes inside the wide gate: the walked tilt stands only when it leads by more than the count's own noise. Held, not bounded — a box the fit lands on is the same wrong answer at a smaller size. The log says what the walked tilt would have moved the far corner by and how the two counts came out; where it was refused, the report's `REFINED_DETECTOR_TILT` is the tilt the pass started at and `REFUSED_DETECTOR_TILT` the tilt the fit had walked to. + +### 7.5 Rotation geometry post-refinement (two-pass) + +The refinement above (§7.2) runs per image against that image's spots. For rotation data an additional **post-refinement** (on by default; `--rotation-no-postrefine` disables it) improves the detector distance, beam centre and crystal cell/axis using **all** frames at once, then re-integrates: + +1. **Pass 1** integrates, scales and merges at the header geometry — the first half of the sweep by default, but at least 120° of it, so a sweep up to 120° is pre-passed whole (`--prepass-fraction`, `1` for all of it). The first-pass indexing and the pre-scan have sampled the same part of the sweep, so nothing before pass 2 reads the rest of it - which is what lets a run that follows a collection still being written do all of this while the rest is collected; what pass 1 adds is integrated reflections for the post-refinement below, and half a sweep holds plenty of them while costing half the time. Its merge, post-refinement and smoothed mosaicity describe a sweep of those frames alone. +2. From pass-1's integrated reflections, the crystal and the detector are refined together over all its frames (Ceres, robust loss) in **one joint fit**, against both residuals at once: + - the **positional** detector↔reciprocal residual at each partial's observed spot, and + - a distance-independent **Ewald excitation** residual at each reflection's observed rocking centroid $\phi_\mathrm{obs}$. + + Free: the crystal orientation, the unit cell (every parameter the crystal system leaves free, not one overall scale), the goniometer-axis direction, the detector distance and the beam centre. The positional residual on its own *is* degenerate with the cell scale — that is why this used to be split into a cell-scale step and a distance step — but the excitation residual does not involve the detector at all, so it fixes the absolute size of the reciprocal lattice and breaks the degeneracy inside the same problem. Splitting it instead cost accuracy twice over: pass 1 frees the whole lattice against a frozen distance, so the distortion it absorbs is *anisotropic* and no single scale can undo it; and whatever bias is left in that scale goes straight into the distance, which is only ever determined relative to the cell. + + The fit is **cross-validated** on a deterministic split of the *reflections* (an avalanche-mixed $hkl$ hash, not a frame split and not an $h+k+l$ parity, which would collide with a centering condition and leave the held-out half empty): fitted on one half, committed only if it lowers the held-out residual by more than that residual's own noise (the standard errors of the two held-out means combined, the bar a round of the geometry walk has to clear) and its two families agree: the positional residual has to fall by more than its own noise, because the positions are the only evidence of the detector geometry a commit hands the next pass, and the excitation residual must not rise by more than its own noise, because it is the only evidence of the cell scale and the positional values outnumber it about three to one. That noise is the *paired* standard error — both geometries are read on the same held-out reflections, so what a change has to beat is the scatter of the change each reflection sees; bare signs stood here, and were a coin toss wherever a family did not move — and the move stays inside its bounds: every free cell angle within 1° and the beam centre within 15 px of the nearest centre anything already believes. + + The **distance and the cell lengths are bounded one step at a time, not as a whole**. One per cent was once a cap on the entire move, and as a cap it was the opposite of its job — a header is most worth correcting when it is most wrong, and a geometry genuinely several per cent out could never be reached (measured: a refused fit of 310.000 → 305.692 mm whose cell landed within 0.06 % of the deposited one). It is a **trust region** instead. The first solve is asked in the wide box around nominal exactly as before, so a fit that settles within one step commits unchanged; a fit that wants more is re-fitted as a *walk* of one-per-cent steps, each seeded where the last arrived and each required to lower the held-out residual, stopping where a step stops paying. A walk that uses every step it is allowed has not settled — it stopped because it ran out of steps, not because it arrived — and is refused, which is the runaway the cap stood in for, tested where it can be seen. A move of more than one step is additionally **ratified by re-indexing at where it arrived**: that is what separates the failure the cap was really aimed at (a second lattice, whose spots bias every cross-validation fold identically) from a wrong header, since a second lattice does not index better at the new geometry and a real distance error does. + + The geometry the run commits is re-fitted on all the reflections once the held-out half has approved it — a walk from where it arrived, one step wide; everything else from nominal in the wide box — and the bounds are asked again of that fit rather than only of the half that earned it. A move outside them leaves the geometry at nominal, as every other refusal does, and the refusal says so in the report (`POSTREFINE_REFUSED`, with what the fit wanted) rather than passing silently. Detector tilt is held fixed, being gauge-coupled to the crystal orientation on a single crystal. + + **Whether the data determine the distance at all is asked, not assumed.** At a detector far enough away that no reflection reaches more than a few degrees of $2\theta$, a longer distance and a larger cell move every spot the same way to first order — the difference is of order $\sin^2\theta$ of the spot's own position, about 0.4 px rms per per cent of distance over a 2M detector at 820 mm against 2–3 px at the distances a crystal is usually collected at. The joint fit then finds a distance/cell pair that fits its own spot positions a little better than the header, commits it, and the pass re-integrated there finds the next pair: a walk along the degenerate direction that the realised residual never ratifies (measured on such a sweep: a header at 820 mm walked to 846 mm with the cell 3.3 % too large, the realised held-out residual flat at every round). So the same fit is asked once more with the distance **held at the header**, every other block as free as before — the nested hypothesis "the header distance is right" — and the two are compared on the one residual family that can tell them apart: the **excitation** residual. It never involves the detector, so it is blind to the distance itself; what it sees is the cell scale, and a held fit at a wrong header distance is forced into a wrong cell scale by the spot positions, which the rocking angles then refuse (measured: a header 1.4 % long leaves the held fit's excitation residual seventeen times the free fit's). Where freeing the distance lowers the held-out excitation residual below the held fit's by more than that residual's own standard error, the free fit is committed exactly as before; where it does not, the held fit is — header distance, refined beam, cell, orientation and axis — and the report says so (`POSTREFINE_DISTANCE_HELD`). The positional residual is deliberately not consulted for this: it is the family whose in-fit gain along the degenerate direction re-integration erases, and pooled with the excitation family it either drowns a decisive excitation gain in its own noise (a 54 % excitation gain read as 9 % pooled against a 9 % noise) or lends the degenerate direction a gain that is not there. Nothing is tuned here: the only input is the standard error of the residual itself, the same noise the geometry walk's rounds have to beat. The wavelength is never refined on a single crystal for the same reason in its exact form: it scales the spot positions and the rocking angles identically to the cell, so no sweep can tell the two apart at any $2\theta$. +3. **Pass 2** re-indexes de novo and re-integrates at the committed geometry. Only the **detector distance and beam centre** carry over: the refined cell, orientation and axis are what make the distance identifiable, but pass 2 re-indexes from scratch, so they are not propagated. Where the re-index finds a **different** lattice — the two compared on their Niggli-reduced primitive edges, within 2 %, so a symmetric setting is never told apart from its own primitive cell — pass 1's lattice is scored at the refined geometry as a hypothesis of its own, and integrated when it indexes more validation frames; the same lattice found again is kept as the re-index refined it. The run likewise falls back to pass 1's lattice where the re-index indexes too few frames, and integrates it at the refined geometry — and the cell is then **scaled to the distance it will be used at**, since a real-space cell is measured against the distance its spots were seen at, and carrying it across a distance change otherwise scales the whole cell by the ratio of the two. The orientation is untouched. + + Pass 2 measures the post-refinement again, and where it still moves the geometry the run **walks**: it re-indexes and re-integrates at what the fit asks for, and repeats. A round is kept only for what it *realises*, not for what the fit predicts, and it can realise a gain in two ways, either of which has to beat its own noise: a lower held-out residual (the standard errors of the two means combined), or a larger share of the validation spots on the lattice beyond chance (the binomial noise of the two shares, z = 3.29). The residual alone misses exactly the errors that cost resolution: it is dominated by the low-resolution reflections, where a distance and the cell scale that compensates it move every spot alike, and its centroids are taken inside a disc centred on the prediction, so they follow the prediction part of the way; the high-resolution validation spots are the first to leave the lattice (measured: 0.6 % of distance read 0.74 of the residual's noise and 70.4 % against 58.1 % of the validation spots, and cost 0.07 Å of resolution). A move of a trust-region step or more starts the walk outright. A smaller one is first tried as two indexing probes on the validation frames — at the fit's geometry and at the one in hand, each stopping once the lattice is scored — and pays for a re-integrated round only where the fit's geometry scores higher. The run keeps the best round it reached. + +The space group is determined **after** pass 2, on the geometry the run refined, and pass 1 does not search at all: a decision taken on the worse of the two passes and then carried forward is a constraint on the better one, and would have to be reconciled with what pass 2 later found. The guard that chooses which pass is written compares each pass's **first** merge — $P1$ on both sides, full resolution range, before the correction surfaces — which both passes produce anyway, so it never compares statistics computed in two different space groups. Where pass 1 integrated only part of the sweep, pass 2 is judged on a merge of its own integration of the same frames, made the same way, since a merge of more frames holds more reflections and more signal whatever the geometry. What it compares there is the **signal each pass measured**: the count of unique reflections merged at $I/\sigma \ge 2$, less the count at $I/\sigma \le -2$. An empty reflection is as likely to land in either tail, so the second count is the merge's own measure of how much of the first is noise — which is what makes two passes on different lattices comparable: a pass on an $n$-fold supercell merges $n$ times the reflections, most of them empty, and their noise alone once out-counted the crystal's own lattice. Self-consistency cannot do this job — against an external arbiter the signal count named the more accurate geometry on 23 of 27 arm-dataset pairs where $R_\mathrm{meas}$, $CC_{1/2}$ and ISa managed 13, a coin flip — and that merge's own $CC_{1/2}$ least of all, being pooled over the whole range, uncut and uncorrected, so the shells with no signal in them dominate it and they are exactly the shells a geometry move disturbs (it reads 0.13 on a crystal whose data merge at 0.995). The refined pass is sent back only where it merges more unique reflections than its cell can hold, where it measured decisively less signal (10 %, and only where it covers no more of reciprocal space either — a wider integration disk pulls weak reflections in and dilutes the strong fraction without measuring less; between two lattices the reflection count of the smaller is scaled by the integer index of one in the other), or where it lost the axial rows the systematic absences are read off. One index-time veto remains and is keyed to pass 1's **lattice** rather than its group: a centred pass-1 lattice against a primitive pass-2 one. A pass sent back is pass 1 as it was judged — its whole indexing result is reused, not indexed again de novo at the header geometry, which is a hypothesis nobody had judged. + +Only pass 2 is written, as the canonical `_*` output. Pass 1's merge exists to give the guard something to judge pass 2 against, so it stops short of the parts of the merge that only fill in a file — the correction surfaces, the twinning and radiation-damage analyses, the R-free flags and the amplitudes — and writes no merged files of its own. + +**Goniometer rotation scale.** A stage that turns further than it was commanded to leaves no trace in the file, because the stored $\omega$ values *are* the commanded ones; the excess then presents as the crystal drifting, in this program and in others. The excitation residual already measures it without a new degree of freedom: it rotates by $-\phi\,\mathbf{u}$ with $\mathbf{u}$ an **unnormalised** 3-vector, so $|\mathbf{u}|$ is the factor $k$ by which the stage actually turned, and normalising the axis throws it away. Pass 1 fits $k$ as a single parameter on its rocking events, with the crystal and the axis direction held at their committed values and the angle measured from the centre of the sweep. That fit **under-reads** a real error: it only sees the frames the stored angles still track, and a rate error is exactly what stops them tracking the rest. So it is not acted on directly. Between the passes, at the detector geometry pass 2 runs at, the lattice is indexed under the stored angles and under the fitted $k$, and each is scored on the validation frames spread over the whole sweep, as the share of their spots it puts on the lattice beyond what it puts there at a wrong spindle angle. The fitted $k$ is adopted only where it scores higher by more than the binomial noise of the two scores (z = 3.29); the run then integrates and post-refines at it, fits $k$ again on top of it, and walks to the fixed point of the fit: once off the stored angles, a further step is refused only where the validation frames score it significantly worse, since a first pass indexes through a degree of drift late in the sweep and the frames can score two rates alike while integration at one of them loses half the signal. Where the run integrates pass 1's own lattice at the adopted $k$, that lattice (cell and orientation, the detector and axis held) is first refit at the angles the pass runs at, on the validation frames of the whole sweep, and kept where it indexes no fewer of them - a cell fitted at the stored angles has absorbed part of the rate error and would undo it. Otherwise the stored angles stand. The adopted $k$ drives every later pass (prediction, integration, scaling and the reported oscillation) and is reported as `GONIOMETER_ROTATION_SCALE`, with `GONIOMETER_ROTATION_SCALE_SUSPECT= TRUE`. `--rotation-scale ` asserts a calibration and skips all of this. + +### 7.6 Detector geometry from powder rings + +Everything above fits the geometry to *Bragg* data, where the beam centre is the weakest parameter: it is gauge-coupled to the crystal orientation, which is why §7.5 bounds it to within 15 px of a centre something already believes rather than letting the spots place it freely. A **powder ring has no orientation to be coupled to**. Where it falls on the detector depends on the geometry and on nothing else, which makes a calibrant — LaB₆, silver behenate, CeO₂, silicon — or even ice an independent constraint on exactly the quantity Bragg data cannot pin. + +The ring positions are matched to the observed rings and the geometry is refined (Ceres, five parameters: beam centre, distance, and the two detector tilts) so that the $|s|$ predicted at each observed ring point matches the ring it belongs to. The two tilts can be held fixed (`rugnux --no-refine-tilt`, the viewer's *Refine detector tilt* tick box), leaving a three-parameter fit: a tilt a downstream program cannot express is better left out of the fit than refined and then dropped, since the centre and the distance of a tilted fit have already absorbed it. + +**Calibrants.** LaB₆, silver behenate, CeO₂ and silicon are held as unit cells and their rings enumerated from them. Ice is held as the hexagonal-ice ring positions of §3.3 instead — measured to 1.522 Å, calculated below it — because hexagonal ice is $P6_3/mmc$ with oxygen on $4f$ and enumerating $hkl$ from its cell would emit rings the oxygen sublattice extinguishes. A calibrant is therefore a list of ring $q$ values throughout, not a cell. + +**What a ring can and cannot determine.** A ring is a conic centred on the beam, so a wrong centre makes its apparent radius oscillate once per turn, $r(\phi)=R+\delta_x\cos\phi+\delta_y\sin\phi$, with the **same amplitude on every ring**. A detector tilt $\beta$ produces a $\cos\phi$ term too — not the $\cos2\phi$ one might expect — but one that grows as the ring's radius *squared*, $r(\phi)=R+(R^2/F)(\beta_x\cos\phi+\beta_y\sin\phi)$; the true $\cos2\phi$ term is $O(R^3\beta^2/F^2)$, hundredths of a pixel. The two are therefore separated by how the amplitude scales with radius, which needs **at least two rings** — on a single ring they are exactly degenerate. None of this uses the calibrant's $d$-spacings, so the centre is determined without assuming anything about the standard. + +The **distance** is different: it follows from $r=F\tan2\theta$ with $\sin\theta=\lambda/2d$, so a fractional error in the lattice constant passes straight into it, and the $\lambda$–$F$ pair is separated only by the curvature of $\tan(2\arcsin(\lambda/2d))$ across the rings — $\partial\ln r/\partial\ln F=1$ at every ring against $\partial\ln r/\partial\ln\lambda=4\tan\theta/\sin4\theta$, which runs from about 1.05 at low angle to 1.43 at high. That lever collapses as the detector moves back and the rings crowd into small $2\theta$, so distance is a short-distance measurement and the wavelength is better calibrated by other means. + +**Reading the rings.** The ring points come from one of two measurements, both accumulated over **every processed image** rather than one. The default reads the **azimuthally-binned profile (§2) summed over the run**: for each ring and each azimuthal sector, the radial peak is fitted against a locally interpolated background and the measured $(q,\phi)$ mapped back through the current geometry to the pixel it came from. The alternative pools the **spot lists**, which samples each arc wherever the spot finder's threshold happens to bite. The accumulated profile is the same size however many images went into it; the pooled spot list is capped, each image contributing an equal share. + +A plain radial profile — one azimuthal sector — has averaged the ring over every direction and carries no centre at all, so the profile route requires at least four sectors and uses 32 by default. Sixteen to thirty-two are enough; beyond that the limit is the ring's own texture, not counting statistics. + +The extraction window around a ring is capped at half the gap to its neighbour, because the background under a peak is taken from the ends of that window: hexagonal ice has a triplet of rings (1.947, 1.916 and 1.882 Å) whose neighbours sit only 0.05–0.06 Å⁻¹ apart in $q = 2\pi/d$, which a fixed window merges into a single peak. Where only one ring is in reach the two tilts are held at their input values rather than fitted, since on a single ring they are degenerate with the centre (above) and the fit would otherwise trade the centre away for them. + +### 7.7 Stills: a given cell and the detector modules + +**A given cell is a prior.** On stills a cell and a distance are degenerate near the +beam - a spot's radius fixes only their ratio - and are told apart only by the curvature of +$r=D\tan2\theta$ against $\sin\theta$ at high angle. The stills geometry refinement therefore refines +the beam centre, the distance and the cell together over the strong frames: the cell lengths and the +angles its crystal system leaves free (the monoclinic $\beta$, all three triclinic angles), each held to +the given cell by a Gaussian prior of 1 % on a length and 1° on an angle, weighed against the spots' +scatter of about a pixel. On a bundle of strong frames the spots outweigh the prior wherever they +determine the cell, so it decides only what they leave open. Holding the angles instead puts a wrong +angle into the lengths and the distance: a monoclinic cell given with $\beta$ 4° off was taken up as a +cell and a distance both 4 % long. The log states how far the refined cell is from the one it started +from (scale, each length, each angle) and how far the distance moved. A distance given with +`--detector-distance` is held, and the cell alone takes up its error. Frames are matched to the given +cell in any setting of the same lattice, and are described on its axes. + +With `-C` the run always uses the cell given; the frames' own evidence is reported, never acted on. Two +warnings say where it disagrees with them, each with both numbers. Where the geometry refinement moves the cell's +shape (a length beyond the common scale, which trades with the distance) more than 3 % or an angle more than 3° +from what was given. And where, at the centre and distance the stills geometry trial decides (§1.4), the cell +the trial's 96-frame sample indexes to de novo puts more than 1/0.9 times as many of its spots on the lattice as +the cell given: the cell given may then be another crystal form than most of the frames, or a shape they do not +have - the same lattice in a shape it does not have still indexes the frames, at a distance of its own, and +merges far worse than the run without `-C`. + +**One crystal form.** A sample can hold two crystal forms, and a known-cell indexer fits both to the +given cell's orientation search; their refined cells then fall into two volume populations, and +merging both mixes two structures. The populations are the peaks of the histogram of +$v/v_\mathrm{given}-1$, each out to the valley on either side that separates it from another, with a bin +that follows the spread of the data, so neither a population's width nor its distance to the next is a +fixed number. The frames merged are the population whose mean cell is nearest the given cell, judged +first by its proportions - the ratios of its edges and the cosines of its angles, each frame's cell put +in the given cell's order of axes - and by its size at a third of that weight. The volume alone does not +say which population is the given cell's: it scales with the detector distance the frames were refined +at, and a start distance 2 % long put the other form of a two-form sample 4 % from the given cell in +volume and its own form 5 % from it, while the proportions do not change with the distance. A run with +one population has no such valley and keeps every frame. The log says how many frames were left out on either side. The stills +geometry refinement fits on the same population: its sampled frames are filtered by it before the bundle +and the module placement are formed, the population told from the strong frames (at least 20 indexed +spots), whose cells show the valley between two forms where a weak frame's cell spreads across it. + +Without a given cell the same question is asked of the frames on the run's own cell (within the +indexing tolerance of it), whose two forms can lie inside that tolerance. Each frame's cell is put on +the run's axes (of the orders of its axes, the one nearest the run's cell, so two near-equal axes indexed +the other way round compare alike), described by its edges as logarithms, and projected on the direction +the cells spread along most, which is the direction between two forms where there are two. The angles are +left out: a still's refined angles carry the indexing more than the crystal - one form comes out with its +monoclinic angle on one axis or another, or held at 90° - and spread more than two forms' angles differ. +The populations of that coordinate are found as above; the largest is merged, and the next, where it +holds at least a tenth of the frames and its mean shape is at least 1 % from the major one's (closer +groups are one form whose cell drifts), is left out of the merge and reported (`CELL_FORMS`, see the +report), with its cell to process it with `-C`. The cell written is the merged frames' own, with or +without a given cell. + +**Detector modules.** Where the detector is described module by module +([Module geometry](RUGNUX_FORMATS.md#module-geometry)), the same refinement places each module with +enough spots on its frames' lattices as a rigid block - a shift and an in-plane turn - where that +predicts held-out spots better: the strong frames are split in half, each half fitted with the modules +fixed and with them placed, and scored on the other. The placement is used if it predicts the held-out +spots better as a whole, and then each module keeps its move only if the held-out spots on that module +are predicted better; the others go back to where they were given and the placement is fitted again. +On a detector of many modules the outer ones, reached only by a few strong high-resolution spots, are +the ones this decides on. `--panel-refine` keeps every move without the tests, `--panel-refine=off` none. The placement starts from the beam, the distance and the cell fitted on the same frames with the modules held, +each frame's lattice taken from that fit, not from the file's geometry: from a start off in distance and centre +the search below moved every module by the centre's error and the placement then pushed two modules of the +second ring outwards, where the distance's error had left their spots, and the distance settled 0.8 % long. +The modules move only relative to one another: a +gauge holds their spot-weighted mean shift, turn and outward push, and with the detector tilt refined +also the two tilt-like gradients across the detector, at zero, so the beam centre, distance, tilt and +crystal orientations carry what all modules share. A coarse search of each module's position comes +first, scored like the beam centre by the spots that land on a lattice. The placement is used from +there on for a foreign multi-panel detector and for modules given as a CrystFEL `.geom`; for a JUNGFRAU +master it is measured and reported only. diff --git a/_sources/CPU_DATA_ANALYSIS_INTEGRATION.md.txt b/_sources/CPU_DATA_ANALYSIS_INTEGRATION.md.txt new file mode 100644 index 000000000..798b81943 --- /dev/null +++ b/_sources/CPU_DATA_ANALYSIS_INTEGRATION.md.txt @@ -0,0 +1,537 @@ +# Data analysis: integration, scaling and merging (§8–§12) + +Part of the [CPU/GPU data-analysis reference](CPU_DATA_ANALYSIS.md); the section numbers are continuous across its parts. + +```{contents} On this page +:local: +:depth: 2 +``` + + +## 8. Reflection prediction + +Jungfraujoch predicts reflection positions for integration by enumerating Miller indices within a resolution cutoff and accepting those that satisfy a diffraction condition model. + +### 8.1 Enumerating reciprocal lattice points + +For a maximum resolution $d_\mathrm{min}$, accept $(h,k,l)$ such that: +$ +\lVert \mathbf{p}(h,k,l)\rVert^2 = \lVert h\mathbf{a}^* + k\mathbf{b}^* + l\mathbf{c}^*\rVert^2 \le \left(\frac{1}{d_\mathrm{min}}\right)^2. +$ + +### 8.2 Still prediction (excitation-error cutoff) + +For still images, the diffracting condition is approximated by an excitation-error cutoff: +$ +\left|\Delta_\mathrm{Ewald}(\mathbf{p})\right| \le \Delta_\mathrm{cut}. +$ +Accepted reflections are projected to the detector by intersecting the diffracted direction $\mathbf{S}=\mathbf{S}_0+\mathbf{p}$ with the detector plane, using the current geometry. + +When the beam has a finite energy bandwidth, this window is **broadened radially per reflection**: the cutoff is combined in quadrature with a bandwidth smear, $\sqrt{\Delta_\mathrm{cut}^2 + (3\,\sigma_\mathrm{bw})^2}$, where $\sigma_\mathrm{bw}\propto|p_z|$ (the reciprocal-space depth along the beam, growing as $\sim 1/d^2$). This keeps high-resolution reflections — smeared by the bandwidth into radial streaks — from being clipped. The same $\sigma_\mathrm{bw}$ is deconvolved from the measured profile radius (§11.1), so it is not double-counted. + +**The window follows the run's rocking curve.** A cutoff of twice a frame's own profile radius (§11.1) is one width at every resolution, while the rocking curve widens with $d^*$: it predicts many widths at low resolution, mostly empty, and cuts the curve at high resolution. So, with the stills partiality post-refinement on (the default, §10.2), a sample of the run - a tenth of its frames, at least 2000 - is first integrated with that cutoff, scaled against its own merge, and the run's rocking curve measured on it as the merge measures it (§10.2): its width $\sigma(d^*)$ and its centre, the radial scale. Every frame is then predicted through $|\Delta_\mathrm{Ewald}| \le 2\,\sigma(d^*)$, with $\Delta_\mathrm{Ewald}$ taken on the reciprocal lattice scaled by that radial scale, and the bandwidth term enters through $\sigma(d^*)$ instead of the quadrature above. With `--simple-stills` the frame's own cutoff stays. + +### 8.3 Rotation prediction (Laue equation + partiality model) + +For rotation/oscillation datasets, Jungfraujoch solves for rotation angles $\phi$ where the rotated reciprocal lattice point satisfies the Ewald-sphere condition. In an XDS-like notation, define: + +- rotation axis unit vector $\mathbf{m}_2$, +- $\mathbf{S}_0$ incident vector, +- $\mathbf{S}(\phi)=\mathbf{S}_0+\mathbf{p}(\phi)$. + +A key quantity is: +$ +\zeta = \left|\mathbf{m}_2\cdot \mathbf{e}_1\right|,\quad +\mathbf{e}_1 = \frac{\mathbf{S}\times \mathbf{S}_0}{\lVert \mathbf{S}\times \mathbf{S}_0\rVert}, +$ +which also appears in XDS as the Lorentz component linked to the rotation axis. + +A Gaussian mosaicity model yields a partiality fraction over an oscillation width $\Delta\phi$: + +$ P(\phi;\sigma_M,\zeta,\Delta\phi) = \frac{1}{2}\left[\mathrm{erf}\!\left(\frac{\phi+\Delta\phi/2}{\sqrt{2}\,\sigma_M/\zeta}\right) - \mathrm{erf}\!\left(\frac{\phi-\Delta\phi/2}{\sqrt{2}\,\sigma_M/\zeta}\right)\right], $ + +with mosaicity $\sigma_M$ in radians. + +Reflections are predicted if they meet minimum $\zeta$ and mosaicity-window criteria, and their predicted detector coordinates fall on the active detector area. + +### 8.4 Systematic absences (centering) + +Systematic absences are applied at the centering level (prior to full space-group symmetry) **when the space group is supplied by the user**. With no user-fixed space group, prediction runs in $P$ regardless of the centering the lattice search inferred: the centering-absent reflections are integrated so that the space-group search (§13) can confirm or disprove the centering from the measured intensities, and so that a missed superstructure shows up. For each centering symbol: + +- $I$: absent if $h+k+l$ odd, +- $A$: absent if $k+l$ odd, +- $B$: absent if $h+l$ odd, +- $C$: absent if $h+k$ odd, +- $F$: absent if any of $h+k, h+l, k+l$ is odd, +- $R$: absent if $(-h+k+l)\bmod 3 \ne 0$, +- $P$: no centering absences. + +--- + +## 9. 2D Bragg integration (profile fitting over a three-ring ROI) + +Jungfraujoch integrates each predicted reflection in the detector plane over a CrystFEL-inspired “three-ring” region of interest (§9.1). The **default** extraction is **profile fitting** (Kabsch; §9.3), which weights each pixel by a fitted spot profile and so recovers weak reflections far better than plain summation; plain box summation (§9.2) is retained as the seed for the profile and as a fallback. Both methods share the same ROI and background model, and emit the same per-reflection $(I,\sigma,\text{partiality},d)$, so scaling, the rotation combine (§10.6) and merging consume either unchanged. + +### 9.1 Regions of interest + +For each predicted reflection at $(x_p,y_p)$, define three radii: + +- $r_1$: inner signal radius, +- $r_2$: inner background radius, +- $r_3$: outer background radius. + +The defaults are $4,6,13$ px for rotation data and $6,8,14$ px for stills, which have a sparser +pattern and can afford the wider ring. `--integration-radius` sets them by hand; on rotation data +$r_1$ is otherwise measured from the crystal's own spots (§9.5). + +Pixels are classified by their squared distance $r^2=(x-x_p)^2+(y-y_p)^2$: + +- **signal region:** $r^2 < r_1^2$, +- **background annulus:** $r_2^2 \le r^2 < r_3^2$. + +Invalid pixels (masked/bad/saturated) are excluded from both sums. In addition, pixels lying inside the signal disk ($r`, default 0).** The three radii above are one triple for the whole run, identical for every reflection at every resolution. A reflection is not round, though: a finite bandwidth streaks it radially by $\sigma_\mathrm{bw}=\text{bandwidth}\cdot R_\mathrm{px}$, with $R_\mathrm{px}$ the distance from the beam centre — the same physical smear as §8.2's and §11.1's $\sigma_\mathrm{bw}$, expressed here in detector pixels where those sections use reciprocal units; the two forms are never mixed in one formula. Throughout, $\text{bandwidth}$ is the **rms** relative energy spread: the user-facing `--bandwidth` takes a FWHM (a DMM's usual specification) and it is divided by 2.355 on input. On a radially smeared spot the fixed $6\ldots13$ px ring therefore sits only $\approx1.3$–$2.2$ radial $\sigma$ from the centre — on the reflection's own tails, which it then measures as background. + +With $k>0$ the **background ring becomes an ellipse**, elongated along the beam→reflection direction by $k\sigma_\mathrm{bw}$. The **radial** semi-axes become $r_2+k\sigma_\mathrm{bw}$ and $r_3+k\sigma_\mathrm{bw}$; the **tangential** half-widths stay $r_2$ and $r_3$; and the growth is capped at $2r_3$, which bounds what a mis-declared bandwidth can do to the bounding box. Pixels are then classified as + +- **signal region:** $r^2 < r_1^2$ — a circle, unchanged, +- **background ring:** $r^2-q_\mathrm{in}\rho^2 \ge r_2^2$ **and** $r^2-q_\mathrm{out}\rho^2 < r_3^2$, + +where $\rho$ is the pixel's radial offset (its projection on the beam→reflection direction), $g=\min(k\sigma_\mathrm{bw},\,2r_3)$ is the capped growth, and $q=1-\big(r/(r+g)\big)^2$ for the boundary concerned. Written this way $k=0$ gives $q=0$ and both tests collapse onto $r^2$ **exactly in floating point**, so the default classifies every pixel exactly as the circular stencil did. The neighbour exclusion above follows: each neighbour's **inner ellipse**, taken in that neighbour's own radial frame, is what is masked out of this reflection's ring. + +The width is the bandwidth streak alone, and deliberately **not** the profile's full radial variance of §9.3, which also carries the sensor parallax and weak-spot capture terms. Those two are the only terms there are on a monochromatic beam, and widening the ring by them neither helps the crystals with clean high-resolution shells nor leaves the weak ones alone. The bandwidth streak, by contrast, is a measured elongation of the recorded spot — principal axis along the radius to within a couple of degrees, and azimuth-independent. Keeping only it also makes the option exactly inert on a monochromatic beam, where $\sigma_\mathrm{bw}$ is zero. + +Growing the ring also grows the neighbour exclusion, so on a crowded pattern fewer background pixels survive; a reflection left with too few is rejected outright. The loss is typically under 0.1% of reflections, but it is not structurally zero. + +Only the ring moves. The signal disk $r_1$ stays circular, deliberately: it sets $n_S$, it sets $\mathrm{var}(\hat b)$, it is the domain the profile *width* is learned over (§9.3), and with `--integrator boxsum` it drives the all-or-nothing “every signal pixel valid” acceptance gate (§9.2), so growing it would reject any box sum carrying a single bad pixel anywhere along a long streak. In the default `gaussian` mode $r_1$ does not set the intensity at all — the fit grid, $\lceil r_2\rceil$, does. + +What a circular $r_1$ loses is flux, and that loss is **not** a function of resolution alone: measured per reflection, it carries a directional component worth several Ų with a definite principal axis, on top of the isotropic part. Nor is there anything in the merge to absorb it. There is **no per-shell scale**, and there cannot usefully be one: every scale in §10 is fitted against a reference built from a reflection's own symmetry equivalents, and equivalents share $s^2$ exactly, so any function of $s^2$ lies in the exact null space of the whole scaling model — a per-shell parameter would have zero residual to fit against. (XDS and DIALS have the same null space, for the same reason.) The isotropic part of the loss is instead degenerate with the overall Wilson $B$ and is silently reported as part of it, so **the reported `WILSON_B` / `_reflns.B_iso_Wilson_estimate` carries an $r_1$-dependent contribution**: measured across a constant-ring-area radius sweep it falls monotonically as the disk grows, by 0.5 Ų on sharp strong data and by up to ~10 Ų on weak wide-spot data. What this costs the *data* is much less than what it costs the flux, because most of the loss is matched by a proportional $\sigma$: it moves no CC$_{1/2}$ and no $R_\text{meas}$, and — to within a few hundredths of an ångström — no resolution cut. + +**Measured spot footprint (automatic).** The radii above are chosen from spots at 5 Å, which at high X-ray energy sit close to the beam. Away from it a spot can grow several times wider — radially from the sensor's parallax and the obliquity of the incidence, tangentially from the crystal's azimuthal spread, which rotates the diffracted beam about the incident one and smears the spot along its ring. On small-molecule data at 20–25 keV the standard deviation grows from ~1 px near the beam to ~5 px at the detector edge: the $r_1 = 4$ disk holds a quarter of the flux there, the $6\ldots13$ px ring a third of it, and the profile widths learned inside $r_1$ (§9.3) saturate near $r_1^2/4$. So the pre-scan measures every spot it finds with a window that follows the spot — three of its own standard deviations, iterated and re-centred — separately along and across the radius, and tabulates the median widths $\sigma_\rho,\sigma_\tau$ against the distance from the beam. Wherever $3\max(\sigma_\rho,\sigma_\tau)>r_1$ the integrator then (i) starts the background ring at $4\sigma$ along each axis, (ii) sums the reflection over the $r_1$ disk **and** the $4\sigma$ footprint ellipse, so the summation — the profile fit's seed and its fallback — holds the spot rather than its core, and (iii) builds the per-reflection Gaussian at the measured widths on a grid grown to hold them. Where every spot fits the disk nothing is installed and the integration is unchanged bit for bit, which is the case for compact protein spots; like the measured radius, the footprint applies to the canonical pass and not to the geometry pre-pass, and a canonical pass whose wider rings the neighbours starve falls back to the settings without it. The reach is $4\sigma$ rather than the $3\sigma$ that decides whether a spot outgrew the disk because wide spots are not Gaussian: mosaic streaks and diffuse halos carry flux past $3\sigma$, which a ring starting there reads as background. Judged by refining the published structures with SHELXL, it removes the intensity loss that grew with resolution on the small-molecule sets (rugnux/model intensity in the outermost shell 0.81–0.91 → 0.98–1.02). + +**Split reflections (automatic).** A crystal made of slightly misaligned domains — the ferroelastic domains a crystal forms below a phase transition, or a cracked or split crystal — records each reflection as two or more compact spots on either side of the position the averaged lattice predicts, moving apart with resolution. The widths above are measured about each spot and so see compact spots; the $r_1$ disk then holds the gap between them and the background ring lands on them, and the loss grows to almost everything at the detector edge. Once the geometry pre-pass has a lattice, every spot it indexes is compared with the predicted position of its own reflection on the same frame, and the mean square of that offset, along and across the radius and in the same distance bins, is added to the pre-scan widths. The table then describes the *reflection* rather than the spot, and the canonical pass integrates with it exactly as above. Where spots sit on their predictions it moves the widths by the prediction error alone (0.2–1 px on protein data, where no reflection then outgrows $r_1$); on an inorganic crystal measured below its ferroelectric transition, where every reflection off one zone is a doublet, the offsets reach 8–16 px at the edge, and SHELXL refinement of the published structure goes from $R_1 = 0.27$ with a spurious extinction parameter to $R_1 = 0.05$. + +### 9.2 Box summation (seed and fallback) + +**Detector units and the gain.** Frames are integrated in the units the file stores them in — photons +for a photon-counting detector (and for a detector whose background resolves single photons, whose +frames are read as whole photons), ADU for a CCD or an analogue XFEL detector whose file states no gain — with +$g$ detector units to a photon ($g = 1$ for photon counting; measured on a few frames, or given with +`--gain`; a $g$ below 1, a CCD read out binned whose pixels scatter less than their mean through the +point spread, is taken as 1). The gain enters only where a photon count is assumed: a pixel's variance +is $g$ times its value, so every variance below is taken at $g$; the background clip is +$\hat b + n\sqrt{g\,\max(\hat b, g)}$; the variance floors are one photon ($g$ ADU for $\sigma$, $0.01g$ +for the fit's background term); and every reflection leaves the integrator divided by $g$ — $I$, $\sigma$ +and the background in photons — which is what the merge's variance model assumes. Integrated this way a +frame in ADU gives the reflections its photons would, the same stencil, clip and profile, rotation and +stills alike. The spot finder's threshold, the spot-width measurement and the hot- and dead-pixel tests +take their photon terms at the same $g$. + +Let: +- $S = \sum I(x,y)$ over signal pixels, +- $n_S$ = number of valid signal pixels, +- $B = \sum I(x,y)$ over background pixels, +- $n_B$ = number of valid background pixels. + +Background per pixel and integrated intensity: +$ +\hat{b} = \frac{B}{n_B},\qquad +\hat{I} = S - n_S \hat{b}, +$ +with a Poisson-like uncertainty $\sigma(\hat{I})=\max\!\big(1,\ r_\sigma\hat{I},\ \sqrt{S + n_S^2\,\mathrm{var}(\hat{b})}\big)$, i.e. $\sqrt{S}$ floored both at 1 photon (the formula is in photons; on frames in ADU it is taken at the gain, above) and at a small fraction $r_\sigma$ of the intensity. The second term under the root is the **uncertainty of the background estimate itself**: $\hat b$ is measured from a finite number of ring pixels, $\mathrm{var}(\hat b)=\hat b/n_B$, and it is subtracted $n_S$ times over, so it enters squared. Omitting it understates the **variance** by $1+n_S/n_B$ — 1.11 with the shipped circular stencil ($n_S = 45$, $n_B = 408$) — and so understates $\sigma$ by up to $\sqrt{1+n_S/n_B} \approx 1.05$, a bound attained on background-limited (weak) reflections and falling towards 1 on strong ones, where $S$ dominates; with an elongated ring $n_B$ grows with resolution, so the factor is no longer one number for a run. The same term is carried into the profile fit (§9.3), where it adds $\big(\sum P/v \,\big/ \sum P^2/v\big)^2\,\mathrm{var}(\hat b)$ — the square of $\partial I/\partial\hat b$ for that fit; $n_B$ is the count of pixels behind the *final* background value, so a clip or trim that discards ring pixels raises it. A box sum is accepted as “observed” only if all signal pixels were valid and $n_B$ exceeds a minimum — it measures what is in the disk with no model of what should be there, so it cannot renormalise a disk it has lost pixels out of. The profile modes can, and do (§9.3). This box sum is the classical estimator; it is used directly with `--integrator boxsum`, and otherwise seeds the profile fit below, where $S$ and $n_S$ then count only the pixels that were actually read. + +**High-side clipped background (default on).** Because $\hat{I}=S-n_S\hat{b}$ is a small difference of large numbers for weak reflections, a per-pixel background bias $\delta\hat{b}$ becomes a *fractional* intensity bias $\approx n_S\,\delta\hat{b}/\hat{I}$ that grows as $\hat{I}$ shrinks — worst at the resolution edge. A plain ring mean reads high there, because neighbour-spot wings that survive the signal-disk mask, tails and zingers are one-sided (positive) contaminants. The ring mean is therefore made robust: pixels above $\hat{b}+n\sqrt{\hat{b}}$ (in photons; above) are rejected and the mean recomputed, with $n=4$ (`--background-clip`; $n=0$ disables), whatever the bandwidth. A clean Poisson ring is essentially unchanged by the cut (measured false-rejection rate 0.04–0.39 % at $4\sigma$), while a 40-pixel neighbour core at $+100$ counts shifts the estimate by $+0.009$ ct/px. + +The clip cuts only the high tail, which matters: the **symmetric** trimmed mean it replaced (drop the lowest and highest fraction $f$ of ring pixels, $f=0.10$; still reachable with `--background-trim`, which switches the clip off) is *not* a consistent estimator of the mean of a right-skewed Poisson sample. It sits $\approx0.1$ ct/px **below** the true mean at every level, and with $n_S = 45$ signal pixels in the $r_1$ disk that under-estimate adds $\approx4.5$ counts to **every** partial — negligible at low resolution, but a large fraction of a partial in the outermost shell. The trim also collapses once contamination exceeds $\approx10\,\%$ of the ring, where the clip does not. Note that removing a positive background bias *lowers* $\langle I/\sigma\rangle$ and *raises* edge $R_\text{meas}$, because both are inflated by information-free counts — so neither may be read as evidence against the change. + +Both estimators are computed in the shared background pass, but only the trim reaches plain box summation: the high-side clip is skipped for `--integrator boxsum`, which therefore uses the plain ring mean unless `--background-trim` is given. + +**Radial background correction.** A ring mean estimates the background *under* the signal disk correctly only if the background is flat there. The signal disk and the ring are concentric, so for a background that is **linear** in position $\langle B\rangle_\mathrm{ring}=\langle B\rangle_\mathrm{disk}$ identically — a plane or gradient fit buys exactly nothing. The leading error is the **curvature** of the radial background, which is negligible on a smooth background but reaches tens of counts on a single reflection sitting on a sharp powder ring. That error is a kernel over radial offset, +$ +\delta \hat b \;=\; \textstyle\sum_k \kappa_k\, \bar B(r_0+k), +$ +with $\kappa$ the annulus-minus-disk histogram of the stencil over radial offset, averaged over azimuth, and $\bar B(r)$ the image's own radial background curve. With the fixed circular stencil ($k=0$, §9.1) that single kernel serves every reflection. An elongated ring does not: its radial-offset histogram depends on how far that particular reflection's ring was grown, so $\kappa$ becomes a small table of kernels, indexed by the growth rounded to whole pixels. The azimuthal average survives the change unaltered, because the stencil is rebuilt in the reflection's own frame at each azimuth and so stays radially aligned: what is averaged over is the sub-pixel phase of the detector grid against the radius, which is what genuinely differs between reflections. Applying it costs one short dot product per reflection and no extra pixel reads; correcting the background *scalar* means the box sum, the profile fit and the non-signal variance all pick it up. The variance carried to the merge, $\mathrm{var}_\mathrm{bkg} = g\,(n_S\hat b + n_S^2\,\mathrm{var}(\hat b))$, moves with the corrected $\hat b$ in its first term — the Poisson share of the background *under the disk* — while $\mathrm{var}(\hat b)$, the noise of the ring estimate, and $\sigma$, taken from the counts in the disk, do not depend on a smooth curve and stay. + +The curve $\bar B(r)$ is the adaptive spot finder's peak-excluded background per resolution ring of the **whole frame** (§3.2), one value per pixel of radius: every pixel of the frame, against the few dozen to few thousand reflections whose own rings would otherwise sample it. Where that curve is in use the ring's **high-side clip follows it**: a ring pixel at radial offset $u$ is clipped against the threshold plus the curve's rise $\bar B(r_0+u)-\bar B(r_0)$, in whole counts. On a background falling steeply away from the beam a flat threshold cuts the beam-side half of the ring as outliers and the background reads low — up to 150× too strong a low-resolution reflection on a binned CCD near the beam stop. With the frame's curve the correction is not the kernel above but the curve itself averaged over the pixels the reflection actually reads: its mean over the ring pixels the clip kept minus its mean over the readable disk pixels, summed while the box is read anyway. The kernel is an average over a whole annulus, so it counts the curve wherever the ring has lost pixels — to the clip, to a neighbour's signal, to a masked or shadowed pixel — and next to the beam-stop shadow, where the curve falls steeply into the shadow and the ring's beam-side part is masked, that turned a correction of a few counts into tens and made low-resolution reflections near the stop read strongly negative. The curve is read at the $2\theta$ of each reflection's position — the radius $F\tan 2\theta$ it is tabulated against, read off the geometry as the curve's rings are — and not at its distance from the PONI, which on a tilted detector is a few pixels off exactly where the curve is steepest. Without a frame curve (fixed-threshold spot finding) the curve is accumulated from the clipped annulus pixels of the predicted reflections themselves, the kernel applies it, and the clip stays flat. + +**When it is applied.** `--background-radial` takes `on`, `off` or `auto`; in Rugnux it is **`auto` by default** (the broker keeps it off), and auto is decided **per run, in the pre-scan, on empty apertures** — the same measurement that, on stills, also chooses how far the ring reaches (the $r_3$, up to the one the run starts from, whose ring predicts the empty disk best). On a grid of apertures away from every found spot, the ring's prediction of the empty disk is taken twice: plain, and with the correction applied exactly as the integrator applies it (the clip following the curve, and the curve's mean over the ring pixels kept minus its mean over the disk). With nothing in the aperture each difference is the error the ring makes in a reflection's background, noise plus bias. Rotation measures every stencil the spot width can give it (and the one it starts from, which the geometry pre-pass and the starvation guard return to) and reads the one it gets. + +- **Stills** have no other correction, so it is applied to every image of a run where it lowers the apertures' mean square error at all. +- **Rotation** has one: under auto, each image whose peak-excluded ice score (§3.3) reaches `--ice-min-score` is corrected, with the frame's curve as on stills (the curve of the reflections' own rings misses the narrow peak of a smooth ice ring). Correcting **every** image instead is chosen only where it takes **at least 10 %** of the apertures' mean square error away: on photon-counting sweeps the apertures gain only a few percent and correcting every image costs ISa and anomalous signal; where it pays — the rings of home-source CCD frames, a smooth ice ring — they gain tens of percent. A run below the margin keeps the per-image ice correction, bit for bit. + +The model is a function of **radius alone**, so it is applied only where that is true of the background. The per-image ice gate rests on this: smooth powder ice *is* a radial feature and is corrected; ice made of discrete crystallite spots — which the profile channel is blind to and the spot channel catches — leaves no smooth ring to model, and correcting it makes matters worse. Measured against a fixed atomic model, comparing ice bands with resolution-matched decoy bands carrying no ice: on a crystal with pure smooth ice the correction removes **43 % of the bands' excess amplitude**, and the improvement is **7× larger inside the bands than outside**, which is its stated mechanism; on a crystal whose ice is textured the same correction *increased* the excess amplitude by half; on a clean crystal it is inert to four decimal places. A strongly polarised beam or panels of different response make the background non-radial too; the apertures see that as a ring the correction predicts *worse*, and a run where they do keeps it off. Auto engages only where a peak-excluded background exists (adaptive spot finding, §3.2) — a plain azimuthal profile carries the Bragg peaks and cannot support an absolute threshold, so without one auto leaves the correction off. + +### 9.3 Profile-fitted extraction (default) + +A fixed signal disk captures a *width-dependent* fraction of each spot, which puts a multiplicative floor on the per-observation precision of strong reflections and weights weak reflections poorly. Profile fitting removes this by extracting each intensity against a fitted spot shape, without needing reference intensities. Per frame: + +1. **Seed.** Box-sum every reflection (§9.2) to get a rough intensity and observed centroid, and select strong spots (significance $\ge 5$). +2. **Build the profile.** For `gaussian` (the default) the width is taken **per resolution shell** from the measured second moments of the strong spots (shell-dependent because spot size grows with resolution). The moments are **anisotropic**: each strong spot's pixels are rotated into its *own* radial/tangential frame before being accumulated, giving $\sigma^2_r$ and $\sigma^2_t$ separately. Stacking the spots in the detector frame instead — they sit at every azimuth — averages the two directions away, leaving only $\sigma_r^2+\sigma_t^2$, so radial smearing is read back as a wider *tangential* spot. For `empirical` the profile is instead the averaged, background-subtracted pixel grid of the shell's strong spots, accumulated in the detector frame on their **rounded predicted** positions. For `gaussian` only, the profile is then **rebuilt for each reflection**, centred on its **sub-pixel predicted position** (the noise-free geometric centre, not the observed centroid) and, where needed, **elongated only along the radial direction** (away from the beam centre) — because two effects stretch a spot radially but not tangentially: + - a finite energy **bandwidth** smears each spot by $\sigma_\mathrm{bw}=\text{bandwidth}\cdot R_\mathrm{px}$ ($R_\mathrm{px}$ = distance from the beam centre, large at high resolution), and + - sensor **parallax** — the depth over which a photon converts in a thick Si/CdTe sensor — adds a term $\propto\tan^2(2\theta)$ (material- and energy-dependent), plus a small fixed weak-spot capture term. + + The two enter as a floor on the measured radial excess: $\sigma^2_\mathrm{radial}=\sigma^2_t+\max\!\left(\sigma^2_r-\sigma^2_t,\ \sigma_\mathrm{bw}^2+c_\mathrm{par}\tan^2(2\theta)\right)$, tangential unchanged at $\sigma^2_t$. The measured excess is what the signal disk can resolve; the analytic term takes over for a streak too long to be measured there. The Gaussian is built on a grid grown to hold the streak — capturing it without the tangential background an isotropic widening would add. The `empirical` profile keeps the fixed per-shell grid and gets none of this. +3. **Fit (Kabsch).** With profile $P$, background $B$ and the shell variance model, the intensity and its uncertainty are +$ +I = \frac{\sum P\,(c-B)/v}{\sum P^2/v},\qquad +\sigma = \sqrt{\frac{1}{\sum P^2/v}},\qquad +v = \max\!\left(B + I\,P,\ \tfrac{1}{2}B\right), +$ +where $c$ is the pixel value and the de-biased variance $v$ (background plus model signal, rather than the down-fluctuating observed count) is iterated (a few passes). The plug-in $I$ enters **as it is**: half-wave rectifying it, $v=B+\max(I,0)P$, lets $v$ — and with it the reported $1/\sum P^2/v$ — respond only to *upward* fluctuations of a noisy estimate, which adds $\approx0.4\,\sigma\sum P^3/(\sum P^2)^2$ to every $\sigma$ whatever the count rate. That offset is invisible on strong reflections and a large fractional inflation on weak ones; the $\tfrac12 B$ clamp keeps $v$ positive without reintroducing it. As a guard, if the profile intensity runs away from the box-sum seed (by more than ~10 box-sum $\sigma$) it falls back to the seed, and the background term is floored at $0.01$ ct/px — enough to keep $P^2/v$ finite when the ring mean reads exactly zero, which a ring of $n_B$ pixels cannot distinguish from any background below $\approx1/n_B$. The rotation/excitation partiality is carried exactly as in the box-sum path. + +**Pixels the fit cannot use (MINPK).** A profile fit is the amplitude of a *normalised* profile, so a pixel left out of the sum renormalises the estimator by construction: it costs information — $\sum P^2/v$ shrinks and $\sigma$ grows — but biases nothing. That is what keeps a reflection whose signal disk is cut by a mask, an untrusted region, a detector gap or an overload: those pixels are simply not read, and the fit is taken over the rest, exactly as the shared pixels of a crowded reflection are (`--overlap exclude`). The reflection is kept only while enough of the expected profile survives — at least `--overlap-minpk` of the profile mass that falls on the detector at all, default 0.75, which is XDS's `MINPK` and dials' `valid_foreground_threshold`. The complete reflections alone teach the profile, its resolution shells and their widths. `--integrator boxsum` has no profile to renormalise with and keeps the all-or-nothing rule of §9.2. + +"Biases nothing" holds only while the profile *model* is exact. Lose the peak and the amplitude is set by the wings alone, so the result stops being a measurement of the reflection and becomes a measurement of how well the fitted shape describes it. The worst case is a pixel invalidated *by the flux it saw* — a detector's per-frame overload marker: that pixel goes missing **because** the reflection was bright, so the loss concentrates on the strong low-resolution reflections that are the largest terms of $R_\mathrm{meas}$, where the fit reads $-50\%$ against the symmetry mates. MINPK cannot catch it, because it cuts on profile *mass* and the peak of a broad spot is a few percent of the mass. So a second condition applies alongside it, on any unreadable pixel whatever made it unreadable: **no unreadable pixel may carry more than 0.9 of the profile's own peak value**. As a fraction of the peak rather than a radius in pixels, that scales with the spot — for a Gaussian it is a cut at $\sqrt{-2\ln f}\,\sigma = 0.46\sigma$, the peak pixel alone where $\sigma$ is 0.8 px and the crest of the ridge where the profile is a bandwidth streak — and it costs well under 0.1 % of the recovered observations. + +The integrator is selected by `--integrator boxsum|gaussian|empirical` (default `gaussian`). + +### 9.4 The prescaling correction + +The deterministic per-reflection corrections are carried as three multiplicative factors. `prescaling_corr` holds the reciprocal Lorentz factor (rotation only — a still's Lorentz factor is one) times the reciprocal polarization factor from the geometry-based term (§2.2), and nothing else: it is Lorentz x polarization, which is what `LP` means in every format the field reads. Beside it sit the two terms that describe what happened to the photon between leaving the sample and being counted, and that are kept apart from `LP` because detector response and beam/crystal geometry are different things: `qe_corr`, the sensor's angle-dependent efficiency, and `flight_corr`, the medium in the flight path (§9.7). The total deterministic correction on a reflection is the product `prescaling_corr * qe_corr * flight_corr`, and every site that corrects an intensity — the integrator, the scaling fits, the merge ingest, the anisotropy analysis and the unmerged export — multiplies all three. None of them is a scale: the fitted per-image scale and the partiality are separate. The three reach the unmerged MTZ as its `LP`, `QE` and `FLIGHT` columns unchanged (`QE` and `FLIGHT` as divisors normalised to 1 at normal incidence), so raw counts are `I / LP * QE * FLIGHT`. + +One term is deliberately **not** in it. The **per-pixel solid angle**, which the azimuthal profile +does divide out (§2.2), is correctly absent here: a Bragg integration sums all the photons in a +reflection, and how many pixels the detector happens to tile that footprint with does not change the +count. Detector obliquity does stretch the footprint, and that enters as the parallax term of the +spot-width variance rather than as an intensity scale. + +### 9.5 Choosing the signal radius from the crystal's own spots (rotation) + +The three radii are one triple for the whole run, but on rotation data they are not a fixed constant: $r_1$ is measured from how wide *this* crystal's spots actually are (`--adaptive-integration-radius`, on by default, ignored when `--integration-radius` is given). On stills the same option measures instead how far the background ring should reach (§9.2, *When it is applied*). + +**Why $r_1$ matters even though it does not set the intensity.** In the default `gaussian` mode the intensity is a profile-fit amplitude over the grid $\lceil r_2\rceil$ (§9.3), so $r_1$ is not the integration domain. It *is* the aperture the profile **width** is learned over, and a second moment taken over a disk of radius $a$ saturates at $a^2/4$. At $r_1 = 4$ the learned $\sigma$ can therefore never exceed 2 px, and a crystal whose spots are broader than that is fitted with a profile the model cannot represent. + +**The measurement is independent of the integrator.** It is made in the pre-scan, on the frames the beam-stop projection already reads, so it costs no extra frame reads and there is no feedback loop. On the spots the spot finder has already found, a spot is used only if it is clear of the detector edge and of the direct beam, has no neighbouring spot within 28 px, is one of the 40 strongest in its resolution band, sits on a fully readable disk, and reaches a signal-to-noise of 15 with its centroid within 2 px of the found position. For each surviving spot the background-subtracted **encircled-flux curve** is accumulated in 1-px annuli out to a fixed 14 px aperture and normalised at 8 px — an aperture that owes nothing to $r_1$, $r_2$ or $r_3$. + +**Pooling.** Spots are stratified into five resolution bands (2–3, 3–4.5, 4.5–7, 7–12, 12–30 Å), because a weak crystal's strongest spots sit at high angle and a strong one's at low angle. Each band with enough members contributes the radius at which its **median** curve reaches 0.80 of its normalised flux — $r_{80}$ — at the band's median $d$. Those points are fitted by weighted least squares against $1/d$ (the mosaic contribution to the detector footprint grows as $1/d$) and evaluated at a common 5 Å, then clamped to the range the bands actually measured so the fit never extrapolates. + +**The radius.** + +$$r_1 = \mathrm{clamp}\!\left(\mathrm{round}(2\,r_{80}),\ 4,\ 6\right),\qquad r_2 = r_1 + 2,\qquad r_3 = \sqrt{r_2^2 + 133}$$ + +The factor 2 is not fitted: for a Gaussian $r_{80} = 1.794\,\sigma$, so $r_1 = 2r_{80} = 3.59\,\sigma$, where the truncated second moment recovers 0.990 of $\sigma^2$. The expression for $r_3$ holds the **background-ring area constant** at its value for the shipped $4,6,13$ ($13^2 - 6^2 = 133$) — a ring that shrank with the disk is what makes a bare `--integration-radius` worse than the default it replaces. The floor of 4 is that shipped default; the ceiling of 6 is pattern density, since $r_2$ also drives the neighbour-ownership radius and the ring's inner edge. At $r_1 = 4$ the triple is bit-for-bit the shipped default, so a crystal with ordinary spots is left exactly where it was. + +**The sample grows until the answer settles.** The frames are measured in tiers of stride 8, 4, 2, 1, each tier's sample strictly containing the previous one, and the pooling is redone after each. Measuring stops when the new $r_{80}$ is within 0.40 px of what the smaller sample said **and** is at least 0.25 px clear of both radii at which the rounding in $r_1$ changes answer. Both conditions are load-bearing: clearance alone lets a small sample settle across a switch, and the step test alone lets it settle *on* one. Every frame of the sample is still read — the beam-stop mask and the beam centre are unchanged; what the tiers save is the decompression, preprocessing and spot finding the width measurement adds on top of the read. + +**It applies to the final pass only.** A rotation run integrates twice (§7.5), and the widened radius is handed to the canonical second pass, not to the geometry pre-pass. The reason is that post-refinement takes its observed positions from the integrator, and an observed position is a first moment over the signal disk with the background still in it: a flat background adds nothing to the numerator but adds $n\,b$ to the denominator, so every measured offset is pulled toward its prediction by $I/(I + n b)$, and $n$ nearly doubles between $r_1 = 4$ and $r_1 = 6$. A wider disk therefore *under*-corrects the geometry — enough, on a crystal whose metric is half a degree off orthorhombic, to flip the second pass's de-novo Bravais choice. + +**The density guard.** Widening $r_1$ pushes $r_2$, the ring's inner edge, into the neighbours; a reflection whose ring is left with five or fewer clean pixels has no background and is dropped whole. The integrator counts the rings the **neighbouring reflections** would starve — every predicted neighbour, the rocking-curve tails the background itself does not exclude included, so the count measures the pattern's density — apart from the ones the detector itself starves (module gaps, the beam stop, the resolution mask), a floor that reaches a couple of percent on some geometries and does not move with $r_1$. Where the neighbour-driven count exceeds 1.13 % of the predicted reflections, the pattern is too dense for the widened radius and the final pass is integrated again at the fixed $4,6,13$, reported as pass 3 of 3 with the reason in `PASS_DECISION`. + +Every integration pass, adaptive or not, logs the radii it used together with the fraction of predicted reflections that lost their background ring, the fraction of rings the neighbouring predictions crowd, and the profile-fit fallback rate. + +--- + +### 9.6 Measuring the bandwidth + +A finite energy spread $\sigma$ ($\Delta\lambda/\lambda$, rms) smears a reflection along its own radius by $2\tan\theta\,\sigma$ radians of $2\theta$ and not at all across it. Most files do not state it — a multilayer monochromator is a beamline option, not a header field — so Rugnux reads it off the spots, on the same isolated strong spots the width of §9.5 is measured on (`spot_width::EstimateBandwidth`). The width settles on fewer spots than this slope needs, so the pre-scan keeps measuring spot shapes for the bandwidth alone until it holds 1000 of them or its sample runs out. For each spot, with $u$ along the radius and $v$ across it, the second moments about its centroid are + +$$m_u = \tfrac1{12} + p_u + j_r^2\big(s^2 + 4\tan^2\theta\,\sigma^2\big),\qquad m_v = \tfrac1{12} + p_v + j_t^2 s^2,$$ + +with $j_r$, $j_t$ the exact pixels per radian of $2\theta$ and of the angle across the scattering plane at that spot, $s$ everything isotropic in angle (divergence, crystal size, mosaic spread), and $p_u$, $p_v$ the sensor parallax, fixed from the sensor's physics: a photon converting at depth $z$ (exponential with length $L\cos\psi$ at angle $\psi$ to the normal, truncated at the thickness) lands $z\tan\psi$ along the ray's in-plane direction. Then + +$$y = (m_u - \tfrac1{12} - p_u) - (j_r/j_t)^2\,(m_v - \tfrac1{12} - p_v) = a + \sigma^2\,(2 j_r\tan\theta)^2$$ + +is a straight line whose slope is the bandwidth. It is fitted over eight equal-count bins of the abscissa, each a 20 %-trimmed mean weighted by its own scatter; the slope's error is the spread of 200 bootstrap re-draws of the spots, inflated by the reduced $\chi^2$ of the binned fit where the line fits worse than the scatter says, and the log calls the estimate significant at $z>3$. It is a **lower bound** — mosaic spread seen along the radius subtracts — and a spread of cell edges is exactly degenerate with it, so what it measures is the effective radial broadening — which is what its consumers need. + +A significant estimate is the run's bandwidth, unless the file states one or `--bandwidth` is given (`--bandwidth 0` forces a monochromatic beam); anything short of $z>3$ leaves the beam monochromatic. From there it acts continuously, with no broadband mode: prediction and partiality (§8), the profile's radial width (§9.3) and the background ring's elongation (`--integration-stencil`, §9.1) all scale with it and are exactly what they were at zero bandwidth. + +### 9.7 The flight path + +A reflection leaving the sample at incidence angle $\alpha$ to the detector normal reaches its pixel +after $D/\cos\alpha$ of flight rather than $D$, so it crosses more of whatever fills the flight path +than one arriving head-on and arrives attenuated. This is the **same $\cos\alpha$ geometry as the +sensor crossing of §9.4, with the opposite sign**: the sensor makes an oblique reflection read high, +the medium makes it read low. + +$$T(\alpha) = \exp\!\left(-\frac{D}{L\cos\alpha}\right), \qquad +\text{correction to } I = \frac{T(0)}{T(\alpha)} = \exp\!\left[\frac{D}{L}\left(\frac{1}{\cos\alpha} - 1\right)\right]$$ + +with $L = 1/\mu$ the attenuation length of the medium at the photon energy, from the same NIST +tabulation the sensor uses. Nothing here is fitted: $\mu$ is tabulated, and $D$ and $\lambda$ are +stated by the file. Normalising at $\alpha = 0$ divides out $\exp(-D/L)$, a constant for the dataset +that the fitted per-image scale absorbs; what is left is the only part of the flight path that is not +degenerate with that scale. + +For **air**, $L$ falls steeply toward low energy — **8.2 m at 18 keV, 3.0 m at 12.4 keV, 0.089 m at +3.8 keV** — and the size of the correction follows it: + +| photon energy | $L$ (air) | $D/L$ at 160 mm | correction at $\alpha = 30°$ | at $\alpha = 55°$ | +| --- | --- | --- | --- | --- | +| 18 keV | 8.17 m | 0.0196 | +0.30 % | +1.5 % | +| 12.4 keV | 2.99 m | 0.0535 | +0.83 % | +4.1 % | +| 8 keV | 0.84 m | 0.191 | +3.0 % | +15 % | +| 3.8 keV | 0.089 m | 1.80 | ×1.32 | ×3.8 | + +**Helium** attenuates about 1/600 of air at 3.8 keV — two electrons an atom against nitrogen and +oxygen, and a seventh of the density — which is exactly why long-wavelength stations use it. It is +not vacuum, and is modelled rather than treated as one, though at these distances it is worth well +under a per cent. **Vacuum** leaves every intensity untouched. + +#### What it does to merged data + +On an **untilted** detector $\alpha$ is the scattering angle, so the correction is a pure function of +resolution. It therefore cancels within a resolution shell and cannot move $R_\mathrm{meas}$ or +CC$_{1/2}$ there; **its whole effect on merged data is a shift in the Wilson $B$**. Friedel mates +share $2\theta$ and so receive an identical factor, which also means it cannot act on an anomalous +difference at all. Both statements are quantitative predictions with no free parameter, and both are +confirmed: the Wilson-$B$ shift is reproduced to within 8 % on three datasets spanning an order of +magnitude in $D/L$, and where a pooled statistic does move, every resolution shell is unchanged and +the pooled shift is reproduced by re-weighting alone. + +That is what `FLIGHT_PATH_WILSON_B` in the results report quotes: the correction's worth, in the one +number it can move. + +#### Why the medium is declared and not detected + +**No field of the NXmx application definition, and no field of any master file `rugnux` reads, +describes the medium in the flight path** — there is no air, helium, vacuum, flight-tube or pressure +entry anywhere to detect it from. + +Inferring it from the physics was considered and **refuted**. The natural idea is that air becomes +unusable at low energy, so an implausibly low implied air transmission would mean helium; but in this +corpus a **confirmed helium** station sits at 51 % implied transmission and a **confirmed air** +station at 63 %. No criterion separates those two without being a threshold fitted between two +points, so there is none. + +`rugnux` therefore **assumes air** — which is what a beamline has unless it was built not to have one +— and `--flight-path helium|vacuum` declares otherwise. Because that is an assumption made on the +user's behalf, the report states it (`FLIGHT_PATH`) together with what it was worth +(`FLIGHT_PATH_WILSON_B`), and warns where it is worth enough to matter. + +--- + +## 10. Scaling and merging + +After per-image integration, Jungfraujoch scales observations and merges them into unique reflections. The design is intentionally compatible with XDS/XSCALE concepts, and handles both still and rotation data. + +### 10.1 Observation model + +For an observation $j$ of a unique reflection $h$ on image (or image group) $i$, the predicted measured intensity is modeled as: +$ +I_{ij} \approx G_i \, L_{ij}\, P_{ij}\, I_h, +$ +where: + +- $G_i$ is the image scale factor, +- $L_{ij}$ is the whole deterministic per-reflection correction of §9.4 - Lorentz x polarization, the sensor's efficiency and the flight path together, not the `LP` term alone. Predictions carry its **reciprocal** split across three fields, so $L = 1/(\texttt{prescaling\_corr} \cdot \texttt{qe\_corr} \cdot \texttt{flight\_corr})$ and the correction below is applied as a multiplication by their product; the scaling fits, the merge ingest and the anisotropy analysis all use the same three, +- $P_{ij}$ is a partiality term (model-dependent), +- $I_h$ is the merged (true) intensity parameter for that unique reflection. + +A least-squares objective is minimized: +$ +\sum_{ij} \left(\frac{I_{ij}^{\mathrm{pred}} - I_{ij}^{\mathrm{obs}}}{\sigma_{ij}}\right)^2 +$ +solved by robust (Cauchy) weighted least squares, with optional post-fit smoothing of the per-frame scales for rotation series (§10.3). + +### 10.2 Partiality models + +The partiality applied is fixed by the data type and scaling stage, not chosen from a user menu: + +1. **Rotation partiality** (XDS-like; see §8.3), used for the per-frame scaling of rotation partials: + $ + P_{ij} = \frac{1}{2}\left[ + \mathrm{erf}\!\left(\frac{\Delta\phi_{ij}+\Delta\phi/2}{\sqrt{2}\,\sigma_{M,i}/\zeta_{ij}}\right) - + \mathrm{erf}\!\left(\frac{\Delta\phi_{ij}-\Delta\phi/2}{\sqrt{2}\,\sigma_{M,i}/\zeta_{ij}}\right) + \right]. + $ + Here $\Delta\phi_{ij}$ is observation $j$'s rocking offset from its exact Bragg angle on image $i$, and the unsubscripted $\Delta\phi$ is the oscillation width per frame — two different quantities that share a letter. The mosaicity $\sigma_{M,i}$ is **measured once per image at indexing** (MLE, §11.2) and held fixed during scaling — only smoothed in frame order (§10.3), never re-refined (it is degenerate with the scale $G$; §11.2). + +2. **Unity** ($P_{ij}=1$): used for the scale-on-fulls refit (§10.6), where each observation is already a complete reflection. + +3. **Fixed**: use the per-reflection partiality carried from prediction. Still/serial images are predicted with $P=1$, so a single-pass stills scale is effectively unity/fixed — which is exactly what `--simple-stills` keeps. By default the stills path instead **post-refines a physical partiality**: a small per-crystal orientation tilt $(\delta\psi_x,\delta\psi_y)$ about the two axes perpendicular to the beam is refined against the running merge, and every reflection's partiality is then recomputed analytically from the refined lattice through its excitation error $\Delta_\mathrm{Ewald}=\big|\,|\mathbf{q}+\mathbf{S}_0|-1/\lambda\,\big|$ and a Gaussian width $\sigma(d^*)$ — the run's rocking width, measured once on the intensity-weighted excitation errors and shared by every crystal. It is measured per group of frames of similar prediction window (four per shell), each against its own window, the shell taking the median of the groups whose curve is narrower than their window, so the frames with the widest windows do not set it everywhere; and it is measured in eight shells of equal width in $d^*$, made non-decreasing (pool-adjacent-violators, weighted by each shell's summed signal) and interpolated linearly in $d^*$ as a table. The three-term form $\sigma^2=\gamma_0^2+(\gamma_e d^*)^2+(\mathrm{bw}\,|q_z|)^2$ — the reciprocal-lattice point's own radius, the mosaic/divergence spread, and the bandwidth smear along the beam, in quadrature — is still fitted, sets the prediction window (§8.2) and stands in for the table where fewer than three shells are measurable. The curve is centred on the run's **radial scale** of the reciprocal lattice — a wavelength or cell a little off, which the spot positions cannot see since they fix only $\lambda d^*$ — measured from where the curve's centre lies against $d^{*2}$ and applied to $\mathbf{q}$. Where the frames were predicted through the measured window (§8.2), the post-refinement uses that same curve rather than measuring it again; the curve is written to `_process.h5` (`/entry/MX/stillsRockingWidth*`, `stillsRadialScale`), so `--mode scale` merges with it too. A tilt moves reflections on opposite sides of the Ewald sphere in opposite directions, so it reshapes the *spatial* pattern of partialities — a degree of freedom the per-image scale $G$ does not have, and the reason the tilt is refined rather than a scalar partiality width, which would be degenerate with $G$. Nothing is re-integrated (the integrated intensities are fixed); the tilt is hard-bounded at about 1° and held by a soft prior, so it stays inert on sparse or weak crystals. The cycle is merge → per-crystal tilt refinement (with $G$ profiled out by the same robust Cauchy IRLS used for the per-frame scales, §10.3) → recompute $P$ → re-merge, repeated a few times; the refined partiality is adopted on every crystal it was refined on. The per-crystal fits of $G$ and of the tilt measure each residual against its expected variance at the model, background + counting + $(0.3\,I_\mathrm{model})^2$: a still's strong reflections scatter about the model by tens of per cent, and in counting sigmas alone every strong reflection would be an outlier and the scale would be set by the weak ones. + +Reflections below a minimum partiality are left out of the merge (`--min-partiality`, default 0.02 on rotation and 0.5 on stills): the empirical rocking curve of a still has a floor far out on its tail, from mis-oriented crystals, and dividing such an observation by a small model $p$ makes it biased, not merely noisy. On stills this holds for the merges the scale and the partiality are refined against. The final merge, which has the fitted error model, takes every observation: the model's partiality term $c\,((1-p)/p)\,\langle I\rangle$ (§10.5) weights a low-partiality observation by what it is worth. A reflection - each Bijvoet hand under `-A` - is reported only if at least one of its observations reaches $p \ge 0.2$; one seen only far out on its rocking curve rests on the partiality model alone. The error model is fitted on the observations at $p \ge 0.2$. + +An observation whose background variance is below zero is left out of the stills scale fits and merges, and the log counts them (`Scaling: N observations on M frames are left out`). Pixels counting photons cannot give one: it is what a background region reading below zero leaves, as when a detector module's pedestal is off on a frame, and integration then floors the reflection's $\sigma$ at one photon while its net intensity, measured against the negative background, reaches thousands. Such an observation weighs a hundred times more than any real one, takes its reflection over in an unscaled merge, and every frame that sees that reflection and finds nothing there is fitted towards a scale of zero, below the floor of the per-frame scales (§10.3), and dropped. On a serial run where one module failed this way every 324th frame, always in the same residue of the frame number modulo 4, the frames of that residue lost about half of their number to the floor and those of the other residues next to none, so two halves of one run merged to CC1/2 0.28 and 0.78. + +### 10.3 Smoothing of per-frame scales + +The per-frame scales $G_i$ are fit by robust (Cauchy) inverse-variance-weighted ratios; there is no explicit $G\approx1$ prior. For rotation datasets, optional smoothing enforces the expectation that scale and mosaicity vary slowly across a sweep: **after** the per-frame fit, $\log G_i$ (and the mosaicity) are replaced by a centred **moving average** over a window spanning a configurable rotation range (XDS DELPHI-like; `--smooth-g`, default 5° for rot3d, off otherwise). It is a post-fit smoothing pass, not a curvature penalty inside the least-squares objective. (The per-frame scale refitted on the combined fulls, §10.6, is smoothed differently: by a penalised smoother whose smoothness is chosen by cross-validation.) + +The **crystal orientation** is smoothed the same way, and for the same reason. Geometry is re-refined independently on every frame against that frame's spots alone — as few as a dozen on a sparse crystal — so the per-frame orientation carries a real slow drift (crystal slippage, up to ~1.3° across a sweep) on top of fit noise that scales with spots per frame. Before scaling, the per-frame lattices are de-rotated to a common reference, averaged in frame order, rotated back, and every partial's $\Delta\phi$ — hence its partiality — is recomputed from the smoothed lattice. The window is chosen per dataset by leave-one-out cross-validation (does a frame's neighbours predict its orientation?) rather than fixed, because drift and noise both vary by two orders of magnitude between crystals; it is capped, because the per-frame fit also absorbs a real per-frame systematic that smoothing too wide destroys. Only frames that actually indexed take part: a frame that did not carries an all-zero lattice, which is *finite* and so passes a validity check written as a finite test, and would otherwise be both averaged into its neighbours' orientation and scored in the cross-validation that picks the window. Refining *less* is not an alternative: with per-image refinement off the space group is lost on several crystals. + +A per-frame scale enters every intensity as $1/G$, so a frame whose fit is not determined by its data can amplify it without bound — and $\sigma$ is amplified by the same factor, which makes it invisible to any $\sigma$-based outlier test. A fitted $G$ far below the run's median is therefore treated as *undetermined* rather than as a successful fit, both here and in the separate refit on the combined fulls (§10.6). The bound is a ratio to the run's own median because $G$ is not gauge-fixed: it and the merged means have an exact global multiplicative degeneracy, so no absolute value is meaningful. + +### 10.4 Merging estimator + +After refinement, corrected observations are formed: +$ +I^{\mathrm{corr}}_{ij} = \frac{I^{\mathrm{obs}}_{ij}}{G_i L_{ij} P_{ij}},\qquad +\sigma^{\mathrm{corr}}_{ij} = \frac{\sigma^{\mathrm{obs}}_{ij}}{G_i L_{ij} P_{ij}}. +$ + +Unique intensities are merged by inverse-variance weighted mean: +$ +I_h = \frac{\sum_j w_j I^{\mathrm{corr}}_{ij}}{\sum_j w_j},\qquad +w_j = \frac{1}{(\sigma^{\mathrm{corr}}_{ij})^2}. +$ + +The weights use an **expected** variance: the Poisson signal part of each $\sigma^{\mathrm{corr}}_{ij}$ is rebuilt at the reflection's merged $\langle I\rangle$ rather than at that observation's own intensity. Weighting by an observation's own $\sigma^2$ biases the inverse-variance mean low below about one photon, because an up-fluctuated observation gets a larger sigma and is then down-weighted too hard. The rotation combine already does this; for stills it is on by default, and `--no-expected-variance-merge` restores the observed-sigma weighting. + +An internal-consistency term can inflate uncertainties when multiple observations are present, in the spirit of XSCALE. + +**Outlier rejection.** Before merging, an observation farther than $N\sigma$ from its reflection's median is rejected (`--reject-outliers`; default 6 on rotation data and 10 on stills, whose partials scatter with heavier tails; 0 turns it off). + +**Several sweeps.** Rotation sweeps given together are one dataset by default (`--sweeps joint`): each is scaled on its own, the sweeps are put on the axes of a reference sweep (the one reaching the finest resolution among those with a measured ISa, ties broken by the higher ISa) and merged in two levels, as XSCALE merges separately scaled inputs; `--sweeps separate` processes each alone. See [RUGNUX_CLI](RUGNUX_CLI.md#inputs). + +### 10.5 Merging statistics + +The shells are **nine bins of equal width in $1/d^2$**, laid between the whole sphere ($1/d^2 = 0$; the +low-resolution limit `--scaling-low-resolution` bounds only the scale fit, so the coarsest reflections are +merged too, and those the beam stop hides count as missing) or the declared range of `--report-resolution`, and the +highest-resolution reflection the merge actually kept — XDS's rule and XDS's count, so at the same +resolution limits the two programs' tables have the same shell boundaries and can be read row for +row. `--resolution-shells` changes the count; the binning rule does not change with it. + +Per-shell and overall merging statistics are computed on corrected intensities, including: +- number of observations and of unique reflections, and multiplicity, +- mean $I/\sigma(I)$, +- $R_\mathrm{meas}$ (the redundancy-independent Diederichs–Karplus form) from within‑HKL deviations, +- $\mathrm{CC}_{1/2}$, correlating two half-sets of **equal size**: an observation's half is the parity of its rank among its own reflection's observations, ordered by a key built from the raw Miller index and the peak frame. Every reflection measured more than once therefore contributes (a hash of the image alone leaves $2^{1-n}$ of the multiplicity-$n$ reflections entirely in one half, with no second mean to correlate), and because a rank is a property of the set rather than of the order it is walked in, a CUDA build and a `JFJOCH_USE_CUDA=OFF` build report the same $\mathrm{CC}_{1/2}$ and the same $\mathrm{CC}_\mathrm{anom}$. It is the split cctbx's `compute_cc_one_half` — and `phenix.merging_statistics` through it — uses. The stills path balances its halves sequentially instead, in image order. When a reference dataset is supplied, $\mathrm{CC}_\mathrm{ref}$ is reported beside it, +- completeness against the reflections the cell and symmetry can give over that same declared range, + so low-resolution terms lost to the beam stop, to a detector mask or to the low-resolution limit + itself count as missing instead of leaving the denominator along with the data, +- the anomalous signal-to-noise $\mathrm{SigAno}$ and the half-set anomalous correlation $\mathrm{CC}_\mathrm{anom}$ (below). + +The error model is refined as $\sigma_\mathrm{corr}^2 = a\,\sigma^2 + (b\,\langle I\rangle)^2$, with $a$ set by the scatter of weak (counting-limited) reflections and $b$ the intensity-proportional systematic scatter of the strong ones. On the **rotation** path, **ISa** is the asymptotic ($I\to\infty$) signal-to-noise — by definition the reproducibility limit of the strongest reflections (Diederichs, *Acta Cryst.* **D66** (2010) 733) — and is read directly from the strong symmetry equivalents as the counting-subtracted fractional scatter of well-measured reflection groups (a robust median over strong groups; the $I/\sigma$ threshold is relaxed on weak or radiation-damaged data that has few strong reflections), rather than as $1/b$ of the whole-range fit, whose $b$ is raised slightly by an intermediate-intensity excess and so understates the limit. The asymptotic value is **report-only** — nothing downstream reads it, and the merged $\sigma$ is not floored at $b|I|$ (that floor was removed). The per-observation $\sigma_\mathrm{corr}$ (the merge weights) uses the whole-range $a,b$. The **stills** path adds a partiality term, $\sigma_\mathrm{corr}^2 = a\,\sigma^2 + (b\,\langle I\rangle)^2 + c^2\left(\frac{1-p}{p}\right)^2\langle I\rangle^2$, and reports **no ISa**: there $1/b$ is the $I/\sigma$ ceiling of one fully recorded still under the stills model - the same frames processed as a rotation sweep read several times higher - which describes the processing model more than the instrument and the crystal. It reports $a$, $b$ and $c$ instead (`ERROR_MODEL_A/B/C`, `_reflns.jfjoch_error_model_a/b/c`); $1/b$ is still used inside, by the space-group search. + +$a$ and $b$ are **reported in XDS's convention**, which is $\sigma^2 = a(\sigma_0^2 + b I^2)$ with $\mathrm{ISa}=1/\sqrt{ab}$, so the printed pair can be read straight against a `CORRECT.LP`. The internal fit keeps the form above; only the report converts, as $b_\mathrm{XDS} = b^2/a$ (and on stills $c_\mathrm{XDS} = c^2/a$). Note that $a$ is the same in both conventions and that the two ISa expressions are the same number, $1/\sqrt{a\cdot b^2/a} = 1/b$ — so the rotation log prints **two** ISa, the whole-range $1/b$ (XDS's meaning) and the strong-reflection asymptote beside it, which can only ever be the more optimistic of the two. The mmCIF follows the same split: `_reflns.jfjoch_diffrn_ISa` is the whole-range value, directly comparable with a `CORRECT.LP`, and the asymptote is written separately as `_reflns.jfjoch_diffrn_ISa_asymptotic`, with `_reflns.jfjoch_error_model_a` and `_b` alongside so the number can be re-derived. Note that a file written before this change carries the *asymptote* under the plain `ISa` name. A third, unrelated $b$ appears in the space-group search (§13.1); it is fitted with the $\sigma^2$ coefficient held at 1 and its gate constants are calibrated in that convention. + +**Anomalous signal-to-noise (SigAno).** The strength of the anomalous signal is reported per shell and overall as $\mathrm{SigAno}=\langle|\Delta I|\rangle / \langle\sigma(\Delta I)\rangle$, where $\Delta I = I(+)-I(-)$ over acentric reflections measured in both Bijvoet hands and $\sigma(\Delta I)=\sqrt{\sigma_+^2+\sigma_-^2}$. It is computed from the **full-multiplicity** inverse-variance $I(+)/I(-)$ split (the same one written to the output), i.e. from all observations rather than a half-set. For pure noise $\mathrm{SigAno}$ approaches the half-normal value $\sqrt{2/\pi}\approx0.8$, and it rises above $1$ once a real anomalous difference is present. A half-set anomalous correlation ($\mathrm{CC}_\mathrm{anom}$) is reported beside it: $\Delta I$ is formed once per half-set and the two are correlated over the acentric pairs where **both** hands split into two non-empty halves, per shell and overall as one correlation rather than a mean of shells. Unlike SigAno it is not a ratio against the error model, so an optimistic $\sigma$ cannot inflate it. It has no floor either: subtracting the two Bijvoet hands cancels the large common intensity that keeps $\mathrm{CC}_{1/2}$ non-negative, so on data with little anomalous signal and about two observations per mate it goes strongly negative. That is a property of the statistic and is reported as measured. It agrees with AIMLESS's `CCanom` and `phenix.merging_statistics`' `cc_anom`; XDS's `Anomal Corr` is a **different quantity and is not comparable with it** — on the same observations it reads two to three times higher in the low shells. It also reads **negative on strong data whose Bijvoet mates are recorded together** (a symmetry axis along the spindle puts the mirror spot of the opposite hand on the same image): the error the two mates share is dealt to opposite halves half of the time and enters the two differences with opposite signs, so it is quoted with its number of pairs (`CC_ANOM_PAIRS=`) and never decided on. Beside it, **measurability** (Zwart (2005) Acta Cryst. D61, 1437–1448; `phenix.xtriage`) is the fraction of the acentric pairs measured in both hands with $|\Delta I| \ge 3\sigma(\Delta I)$ and $I \ge 3\sigma$ in each hand, per shell and overall (`ANOM_MEASURABILITY=`). $\mathrm{CC}_\mathrm{anom}$ is a rotation-path statistic (the stills merge forms no half-set anomalous difference), and it is reported in the `CCanom` column of the printed merge-statistics table and as `CC_ANOM=` in the results report — not in the mmCIF. SigAno is emitted only when an anomalous split was made, using the standard PDBx items `_reflns.pdbx_absDiff_over_sigma_anomalous` (overall) and `_reflns_shell.pdbx_absDiff_over_sigma_anomalous` (per shell), and appears as the `SigAno` column of the same table. Where either could not be measured at all — a Friedel-merged run that split no Bijvoet pair, a shell too thin to split one in both hands — the table prints `-` and the results report writes no key, which is not the same statement as a value measured to be zero. + +### 10.6 Rotation datasets: combining partials into fulls (3D integration) + +In a rotation scan a reflection is recorded as a series of *partials* spread across the frames its rocking curve crosses. Merging those partials directly would force the merge error model to absorb the rocking-curve slicing as if it were measurement noise, capping the achievable $I/\sigma$. For rotation data Jungfraujoch instead **combines** each reflection's partials into a single *full* intensity first, then scales and merges the fulls — a 3D integration over the rocking curve. + +The combine groups each reflection's partials into rocking events (contiguous runs of frames) and reduces each event to one full: + +- **De-biased weighted sum.** Partials are combined by inverse-variance weighting, where each partial's variance is its background-noise component plus the *model* signal shared across the event (Kabsch profile-fit form). Using the shared model signal rather than the individual down-fluctuating intensity stops weak partials from being over-weighted, which would otherwise inflate the merged error model. The weights depend on the full, so the estimate is iterated. +- **Captured fraction.** The partiality summed over the event, $f=\min(1,\sum_j p_j)$, measures how completely the rocking curve was sampled. A full whose curve was captured below a threshold (`--min-captured-fraction`, default 0.7 for rotation) is dropped — an event seen over only a small fraction of its curve is unreliable however many frames it spans. (The per-partial minimum-partiality cut of §10.2 still applies upstream, in the per-frame scaling.) +- **Per-image rejection (opt-in).** A frame whose observations correlate poorly with the merged reference is not measuring the crystal being merged — it may be off-crystal, or on a *different* crystal where two lattices occupy separate regions of the sample. `--min-image-cc` drops such frames. It has no default: the per-frame correlation measures data quality as much as frame validity, and its typical level varies widely between datasets, so no single absolute bound is generally valid. +- **Capture-aware uncertainty.** A full captured incompletely ($f<1$) is extrapolated and biased high. The unobserved fraction is charged as an extra systematic uncertainty, $\sigma^2 \leftarrow \sigma^2 + \big(c\,(1-f)\,I\big)^2$, so the merge down-weights these extrapolated fulls and the error model treats their scatter as expected. The merge rebuilds every full's variance at the reflection's mean intensity (§10.4), and the capture term is rebuilt there too, as $\big(c\,(1-f)\,\langle I\rangle\big)^2$. It is enabled by default for the rotation path. +- **Overloaded events.** An event in which any partial had a saturated pixel in its signal disk — or a pixel unreadable on that frame alone, beyond the run's pixel mask, which is how a detector that writes its error value for a pixel it could not count reports an overload — is dropped whole, as XDS drops an overloaded reflection. The brightest part of such a rocking curve is exactly what is missing, so neither the sum of the remaining partials nor their extrapolation by the partiality model measures the reflection: on a strongly diffracting small-molecule crystal these were the strongest low-order reflections, and they read 2–3× low. The integration keeps an overloaded partial, unfitted and flagged, only so that the event can be recognised; nothing else reads it. The count is `OBSERVATIONS_REJECTED_OVERLOAD=` in the report. + +The fulls are then re-scaled in the XDS sense — a per-image scale refit directly on the complete reflections under the unity partiality model — and merged (§10.4). + +Before the combine a per-frame scale can also be fitted on the partials themselves. That needs a frame to hold many rocking events caught at different points of their curves: within one rocking curve a change of scale and an error of the partiality model are the same thing, and on a finely sliced sparse sweep the fit takes one for the other. The rocking events per frame are the prior (the partials are scaled from 50 events per frame), but the counts of small-molecule sweeps (3–43) and proteins (5–900) overlap. So the first merge of a run that is not a space-group search can be made **both ways**, with the partials scaled and with the scale taken from the fulls alone, and the prior stands unless its merge has no resolved error model ($b$ not resolved from zero: the strong equivalents do not agree to within a measurable systematic error) while the other merge has one. Where the prior is to scale the partials and that merge resolves its error model, the other cannot change the choice and is not made. The two ISa values are deliberately not compared beyond that: the partiality-model error a partial scale takes up is shared by symmetry mates measured at the same rocking geometry, so their agreement cannot see it — a small-molecule sweep with six events per frame read ISa 10.5 with its partials scaled against 8.7 from the fulls alone, and refined to $R_1$ 0.105 against 0.062. The log states the choice and the ISa of every arm that was made. Because every merged observation is now a counting-statistics-limited full rather than a partiality-divided slice, the error model reaches a far higher asymptotic $I/\sigma$. + +How smooth that scale is over the rotation is left to the data rather than to a fixed window. Each round fits every frame on its own fulls against the current reference, giving a scale $G_f$ and its information $D_f=\sum w^2c^2$; the scale is then the curve $x=\log G$ minimising $\sum_f J_f\,(x_f-y_f)^2+\lambda\sum_f(\Delta^2 x)_f^2$, with $y_f$ the frame's own fit in log scale and $J_f$ its information carried there — a penalised (Whittaker–Eilers) smoother, solved as a five-band linear system. $\lambda$ is chosen by cross-validation: blocks of frames one rocking curve wide are left out in turn and predicted from the curve through the rest (neighbours closer than a rocking curve share their measurement, since a full sums those frames). A frame of hundreds of fulls is then followed frame by frame, a frame of two or three is carried by its neighbours, a stretch with none is bridged by a straight line, and a scale that falls a hundredfold over a few degrees — an absorbing crystal turning edge-on — is followed where a window would average across it. Once the curve settles, one free fit is shrunk toward it frame by frame by how much of each frame's deviation its neighbour shares (the lag-1 covariance), which hands back a real per-frame systematic and discards fit noise. + +Both per-frame scaling loops — on the partials and on the fulls — alternate between the references given the scales and the scales given the references, and converge linearly: a round typically removes only 5–15% of the remaining step, and 2% on the slowest sweeps. Each round is therefore Anderson-accelerated in $\log G$ (type II, five rounds of history, each frame weighted by its observation count): the plain round's scales are corrected by the combination of the last rounds' steps that best cancels the current one, and the history is dropped whenever the set of fitted frames changes. Acceleration starts only once the plain step has fallen below $10^{-2}$, and stops for the rest of the loop the first time the step grows: Anderson mixing models a map near its fixed point, and a loop further out, or one whose step grows, may be walking rather than converging - accelerated, it walks faster and ends somewhere else. This changes the path, not the fixed point. With it the loops are run to an rms step of $10^{-5}$ in $\log G$ - in fewer rounds than a plain loop took to $10^{-3}$ - so the merge no longer depends on where a loop happened to stop. + +After scale-fulls, five **correction surfaces** are fitted on the combined fulls (rotation path, **on by default**; disable all with `--no-scaling-corrections`), each an alternating multiplicative refinement of the per-full scale against the merged reference: + +- **Decay.** Radiation damage weakens later frames more at higher resolution — a resolution×time (Debye–Waller) systematic the resolution-flat per-image scale cannot capture. A single global relative-$B$ rate is fitted, $\ln(I_\mathrm{ref}/I_\mathrm{obs}) = 2\,(\mathrm{d}B/\mathrm{d}n)\,(n-\bar n)\,s^2$ (frame $n$, $s^2 = 1/4d^2$), and folded into the scale. It engages only when the total relative-$B$ over the run exceeds a physical floor (2 Ų); below that the decay is negligible and "correcting" it only spreads symmetry equivalents (same $s^2$, different frames). An optional **per-batch relative-$B$** (`--relative-b[=deg]`, off unless requested; 10°-of-rotation batches by default) extends the single global rate to a smooth $B(n)$ curve — the same $s^2$-weighted decay fit solved independently over short frame batches, curvature-penalized so it cannot over-fit and cross-validated like the surfaces below — for crystals whose decay is non-linear in dose. Its cross-validation splits on **ASU-group parity**, not the frame parity the surfaces below use: a per-batch parameter owns whole frames and so cannot be scored on a held-out frame, whereas splitting the symmetry equivalents tests whether a batch's $B$ generalises to reflections it was not fitted on. +- **Absorption.** A smooth multiplicative factor over the diffracted-beam direction expressed in the goniometer (crystal) frame: each full's predicted detector position gives the lab diffracted direction, de-rotated by the spindle so a fixed crystal-frame direction is sampled at many rotation angles and its grid cell is well-determined. Negligible at hard X-rays / thin crystals; it matters at low photon energy. +- **Modulation** (detector-plane flat-field). A smooth multiplicative factor over where each reflection lands on the detector (predicted $x,y$): symmetry-equivalents land at different positions as the crystal rotates, over-determining the surface. It absorbs detector-response and geometric systematics that inflate $R_\mathrm{meas}$. +- **Absorption as spherical harmonics.** The same crystal-frame absorption as a smooth function instead of a grid: the logarithm of the factor is a sum of real spherical harmonics of the de-rotated diffracted-beam direction, degrees 1 to 6 (48 terms; the incident-beam path depends on the rotation angle alone and is part of the per-image scale). It is fitted through 32 × 64 equal-solid-angle direction cells, one ridge-regularised least-squares step on the coefficients per round, with a prior of width 0.1/l on each degree-l coefficient. It is a candidate like the others and passes the same held-out test; the grid is then tested on what it left. +- **Time-dependent absorption.** The same surface as *Absorption*, but over (rotation angle × detector position) instead of the crystal-frame direction alone. The two agree while the illuminated volume stays put — the incident path then depends only on the spindle angle, which the per-image scale already takes, and the exit path is fixed in the crystal frame. Once the diffracting volume drifts through the beam the exit path becomes a function of the spindle angle as well, and nothing time-independent describes it. Fitted on one rotation bin per 10° (at least 12) × a 10×10 equal-occupancy detector grid. + +The surfaces overlap, so the order decides what is adopted: modulation first (every frame measures the static detector pattern, so its fine grid is the best determined), then time-dependent absorption, then the spherical-harmonic absorption, then the goniometer-frame grid, whose cells collect directions from the whole sweep and the whole resolution range and which, fitted first, takes up part of what the other two describe. + +Each cell's factor is fitted under a **prior pull to 1** (a Gaussian prior of width 0.1 on its logarithm): a cell moves off 1 in proportion to the information its observations carry, so a cell with little signal stays near 1 instead of being fitted to its noise. Negative observations enter the fit as measured. On the detector-plane surfaces (modulation, time-dependent absorption) the component that is a function of resolution alone is projected out within resolution shells, since the symmetry equivalents of a reflection share one resolution and such a factor cannot be determined from them. + +Each surface is **cross-validated** on the half-set agreement it is meant to improve: fitted on even-numbered frames and used to merge the odd ones, fitted on the odd frames and used to merge the even ones, and kept only if the correlation between the two half-set means, taken within resolution shells, rises above the same two halves merged with no surface. A shell is read only where it holds at least 50 reflection groups; on a small cell adjacent shells are pooled until each bin does, so a merge of a few hundred unique reflections is still judged. Each half is corrected by a surface it did not help to fit, so a surface fitted to noise lowers the correlation, and a correlation within a shell is blind to the resolution-dependent scale the surface cannot determine. The change is averaged over the shells on Fisher's $z = \operatorname{atanh}(CC)$, not on $CC$: the strong shells, where a multiplicative error matters, sit at $CC_{1/2} \approx 0.999$, where even a large reduction of the error moves $CC$ in the fourth decimal, and averaged on $CC$ itself the shells of pure noise beyond the reach of the data decide the sign. + +**Radiation-damage report (rotation, report-only).** Independently of whether any decay correction is applied, Rugnux measures and reports the relative Debye–Waller $B$ across the sweep: the per-image scale's correlation to the merge and the per-image mosaicity versus frame (dose), together with a per-batch relative-$B$ curve whose first→last change is a single headline number (measured before any decay correction, against the least-damaged early wedge). It is written to the log and to the merged mmCIF as a data-quality-vs-dose diagnostic and **never** alters the merged intensities — distinct from the decay correction above, which does fold into the scale. + +Each batch's $B$ is fitted on **resolution-shell means**, not on single observations: $\ln(I_\mathrm{ref}/I_\mathrm{obs})$ of one weak observation is unbounded and biased downwards — the observation appears in the response and in its own weight, and the logarithm needs $I_\mathrm{obs} > 0$, which keeps only the upward half of the noise — and on decayed data that bias grows with dose until it reverses the sign of the answer. The shells are laid inside the range the run actually diffracted to, and the fit carries an intercept as well as a slope, so a batch that is merely *dimmer* than the run (an attenuated beam, a mis-fitted frame scale) is not reported as damage. A batch whose shells are too weak to fit, or whose solved value reaches the bound the smoothing solve clamps to, is reported as **absent** rather than as a number. The first→last headline is reported only where a straight line describes the curve: radiation damage is progressive, so a curve that dips and recovers is a disturbance rather than dose, and is left to the sweep-quality report ([the results report](RUGNUX_REPORT.md)) to name. + +**Frame disposition (rotation).** After the correction surfaces are fitted, and on the corrected fulls, Rugnux measures **ΔCC1/2** — the overall CC1/2 of the merged data with a group of images minus the CC1/2 without it, over the reflections that group touches — for each 10° batch of the sweep and for each stretch the sweep-quality diagnostic flagged. It is computed in the σ-τ form (no random half-dataset split, so the answer is the same every run), with each observation carrying the information $\min(1, (G/G_\mathrm{ref})^2)$ of its frame's scale against the typical one — the internal weighting of the automatic resolution cut ([decisions](CPU_DATA_ANALYSIS_DECISIONS.md) §13.4), not part of the reported $\mathrm{CC}_{1/2}$ — and with each reflection's error variance taken from the **observed** scatter of its own observations rather than from the error model's σ's: a bad stretch claims the same σ's as a good one, so an error-model estimate would read a batch that adds noise as a batch that adds precision, inverting the sign of the measurement. The leave-one-out is a subtraction of the group's own $(n, \sum I, \sum I^2)$ from the per-reflection totals, so measuring a group costs one pass over its observations rather than a re-merge, and reflections the group holds the only observations of are excluded from both sides — the published statistic's own restriction. Its standard error is reported beside it as that of a single CC1/2 on the same reflection count, $(1-CC^2)/\sqrt{n_\mathrm{refl}-3}$, and a ΔCC1/2 smaller than that says nothing; a group whose ΔCC1/2 is positive or near zero is not evidence of harm. A batch is removed only where its ΔCC1/2 is **both** several standard errors below zero (Fisher-transformed) **and** well below the run's own per-batch distribution (median − 3 robust σ, measured once before anything is removed), **and** where the per-image CC to the merge — an independent channel, measured on the partials one frame at a time — also says the stretch agrees with the run worse than a typical frame does, because selecting frames by their disagreement with the merge and then reporting that the merge improved is circular; its edges are then slid frame by frame with the whole stretch re-measured at each position — so the range is located finely while the count of reflections the verdict rests on stays that of the stretch — the worst range is removed, the reference is re-formed and the scan repeats, never past a quarter of the sweep and never over a stretch narrower than one rocking event. The resulting per-frame `merged` / `downgraded` / `rejected` ledger is described in [the results report](RUGNUX_REPORT.md). + +### 10.7 R-free test-set flags + +A fraction of the unique reflections (`rfree_fraction`, default 0.05) is flagged as a **free (test) set**, written to the output (MTZ `FreeR_flag`, mmCIF `_refln.status` = `f`, a text-HKL column) for model validation (§14) and for downstream refinement. The flag is a pure function of the reflection's orbit under the **lattice holohedry** — the point group of the cell's metric, found as twin laws are (Le Page two-folds within 3° obliquity, taking the lattice of the cell's own basis vectors), which contains the merging group — together with its Friedel mate. Where the cell does not carry the merging group (a space group forced on a metric without it), the Friedel-merged (Laue) ASU index of the merging group is used instead. That gives four properties: + +- all symmetry- and Friedel-equivalent reflections share one flag — in particular a Bijvoet pair $I(+)/I(-)$, kept as two separate merged rows in anomalous mode, is **never split** across the work and free sets (which would bias R-free); +- **twin-law mates share one flag too**, since a twin law is a lattice symmetry the crystal lacks. Keyed on the merging group instead, nearly every free reflection's twin mate lands in the working set, and in twin refinement the free reflection's calculated intensity then carries the working-set fit. The same set is what phenix.refine generates by default (`use_lattice_symmetry`). It also makes the free set independent of the space group a file is merged in: the merged file and a re-merge in any subgroup, P1 included, carry one free set (nested, where the small-data floor below lifts the fraction of one of them more than another's); +- the free/work decision is a deterministic hash of that key, so the same reflection always lands in the same set — reproducible run-to-run and independent of the order in which observations were merged; +- the hash depends only on the reflection index, **not** on this dataset's resolution range or which reflections it happens to contain, so a uniform draw takes ~`rfree_fraction` of the distinct reflections free and — crucially — **every dataset of one crystal form gets the same free set**. That cross-dataset consistency is what a multi-dataset campaign (ensemble refinement, PanDDA) requires; a per-shell stratification tied to each dataset's own $d_\mathrm{min}$ would break it. + +On small data, where `rfree_fraction` (default 0.05) would give too few test reflections for a statistically stable R-free (Brünger's ~500–2000 rule), the fraction is **floored** so at least ~500 distinct reflections are free — capped at 10 % so a large test set never steals working data. For ordinary data this floor is inactive and the fraction stays flat at `rfree_fraction`, preserving the cross-dataset-identical property above; it only lifts the fraction on genuinely small datasets, where per-dataset R-free stability outweighs cross-dataset identity (and a shared reference set is the way to keep exact identity there). + +When a reference (`--reference`: an MTZ, or a PDB structure-factor mmCIF, which is converted to one with `_refln.status` `f`/`o` becoming flag 0/1) carries a `FreeR_flag` column, its test set is **imported** instead: every merged reflection whose Laue-ASU index matches the reference takes the reference's flag (reflections absent from the reference keep the hash flag). The match is made in the reference's frame — on rotation data the merge is first put onto the reference's axes, choosing among every description of the lattice on them (and every alternative indexing) by the intensity correlation with the reference — and only where the merge then matches it: an intensity CC of at least 0.5 over at least half of the merged reflections in the reference's resolution range. Below that the reference is not the same crystal form on the same axes, its flags would land on unrelated reflections, and they are not imported (`REFERENCE_MISMATCH`). This lets a whole fragment-screening campaign inherit one shared free set from the apo/reference dataset. The CCP4/refmac convention (test set = flag 0, including the historical 0–19 form) is assumed, with the complement taken automatically if flag 0 would be the majority (a phenix-style file where 1 marks free). + +### 10.8 French–Wilson amplitudes + +The last step of the merge estimates a Bayesian structure-factor amplitude $|F|$ for each unique reflection from its intensity $I$ and error $\sigma$, so the output carries amplitudes alongside intensities (a naïve $\sqrt{\max(I,0)}$ turns every weak or negative measurement into a biased — or zero — amplitude). With the Wilson prior for the true intensity $J\ge 0$ at that resolution, + +$ +P_\mathrm{acentric}(J) \propto e^{-J/\Sigma},\qquad +P_\mathrm{centric}(J) \propto J^{-1/2}\,e^{-J/2\Sigma}, +$ + +and a Gaussian likelihood $\mathcal{N}(I;J,\sigma^2)$, the posterior mean amplitude and its uncertainty are + +$ +\langle |F|\rangle = \frac{\int_0^\infty \sqrt{J}\,\mathcal{N}(I;J,\sigma^2)\,P(J)\,\mathrm{d}J}{\int_0^\infty \mathcal{N}(I;J,\sigma^2)\,P(J)\,\mathrm{d}J},\qquad +\sigma_F = \sqrt{\langle J\rangle - \langle|F|\rangle^2}. +$ + +The prior mean is $\Sigma = \varepsilon\,K_\mathrm{shell}\,a(\mathbf{h})$, where $\varepsilon$ is the reflection's epsilon (symmetry-enhancement) multiplicity, $a(\mathbf{h}) = \exp(-\tfrac12\mathbf{s}^\mathsf{T}B\,\mathbf{s})$ carries the deviatoric anisotropy tensor $B$ of §13.5 along the reflection's own direction, and $K_\mathrm{shell} = \sum I/\varepsilon \,/ \sum a$ over its resolution shell, so the priors of a shell still average to its measured Wilson mean. The amplitudes are first made with $a = 1$ at the end of the merge and made again once the tensor has been fitted; only $F$/$\sigma_F$ change, never an intensity. With an isotropic prior the weak direction of an anisotropic crystal gets a prior set mostly by the strong direction, which turns its noise into amplitude; for isotropic data the tensor is near zero and the prior reduces to the shell mean, so it is used whenever a tensor was fitted. A shell whose $K$ is not positive takes that of the nearest lower-resolution shell. As in `ctruncate`, an intensity more than 3.7σ below zero gets no amplitude (the intensity is kept) and does not enter the shell mean. Strong reflections ($I>20\sigma$) short-circuit to $|F|=\sqrt{I}$, where the French–Wilson bias is below 0.3%; a reflection with an unusable $I/\sigma$ falls back to $\sqrt{\max(I,0)}$. The integral is evaluated numerically with a log-shift for stability. + +Amplitudes are written as MTZ `F`/`SIGF` (and `F(+)`/`F(-)`) and mmCIF `_refln.F_meas_au`/`F_meas_sigma_au`, alongside the intensity columns; the SHELX `.hkl` holds intensities only. The **same** $|F|$ feed the model-validation step (§14), so the reflection file and the maps use one consistent set of amplitudes. + +### 10.9 Reference data: fixing the space group and resolving the indexing ambiguity + +A reference dataset (`--reference`, MTZ or SF-mmCIF) supplies known intensities for the same crystal form, and is used in two ways. + +**Fix the space group and cell.** Unless overridden on the command line (`-S` for the space group, `-C` for the cell), the reference's space group is adopted and its cell is used as the soft reference cell — indexing may still drift the cell within tolerance, so a small mismatch between reference and data is absorbed rather than rejected. This applies to both stills and rotation data. + +**Resolve the indexing (merohedral) ambiguity.** When the lattice symmetry is higher than the crystal's Laue symmetry (e.g. $P3$, $P4$, $P6$, $C2$), more than one indexing of the same lattice is geometrically valid, and the two solutions produce *different* merged intensities that a self-consistent scale cannot tell apart — which of them is the reference's own, only an external reference can say. The candidate reindexings are the identity together with the twin-law cosets of the metric symmetry (from the unit-cell metric and the Laue group); each is scored by the intensity correlation $\mathrm{CC}_\mathrm{ref}$ of the reindexed merge against the reference, and the data are re-merged in the best-correlating indexing. The reindex is **metric-preserving** — only the $hkl$ labels change, the cell is unchanged — and it is a no-op for a holohedral crystal, which has no twin laws (the lattice and Laue symmetry coincide). For rotation data this is done once, after the space group is determined, and the whole merge is then repeated in the chosen indexing. For stills, where each crystal is indexed independently and a merge of mixed indexings would average reflections that are not symmetry mates, it is decided **per crystal**: at integration time each image is put into the indexing whose partiality/Lorentz-corrected intensities correlate best with the reference (scale-invariant), and before the merge that correlation is weighed, crystal by crystal, beside the crystal's agreement with all the others and its own cell, as described below. In neither workflow is the reference a **scale** target: both scale against their own data (§10.2), so $\mathrm{ISa}$ and the merging statistics come from the data alone and no cross-dataset systematic is imported. A re-merge of stored reflections (`--mode scale`) makes the same choice, with or without a reference. Where there is no reference dataset but there is a **model** (`--model`), the reference intensities are computed from it instead - $|F_\mathrm{model}|^2$ from the atomic structure factors with a flat bulk-solvent contribution at the standard constants ($k_\mathrm{sol}=0.35$, $B_\mathrm{sol}=46$ Å$^2$), which are not fitted because there are no observations yet. Nothing is scaled against them; they serve only to rank the candidate indexings, and the correlation that does the ranking is scale-invariant. This needs the cell and space group up front (`-C` / `-S`, as serial indexing wants anyway); on rotation data the same job is done after the merge, in §14.5, where a merge exists to fit the model to properly. + +**Serial stills without a reference or model.** The data cannot say which indexing is the *true* one, but they can say which crystals are in the *same* one, and that is all a merge needs. Where the space group is fixed (`-S`) and its lattice admits alternative indexings, the crystals are made consistent with each other before anything is scaled, following Brehm & Diederichs (2014). Each crystal is compared on the square roots of its partiality- and Lorentz-corrected intensities, the sign kept: intensities follow the Wilson distribution, whose long tail lets a few very strong reflections dominate every product of two crystals, so that the strongest crystals settle among themselves and a group of them can hold one another in the wrong indexing against the weaker majority (on a large-cell serial run this left a fifth of the crystals in the wrong indexing); amplitudes have no such tail. They are put on the run's mean and spread in their resolution shell (20 shells of equal reciprocal volume; a shell past the resolution the run reaches holds only noise and may have a mean of zero or below, so it is not divided by its mean), standardised within the crystal so that its unknown scale and offset drop out, and weighted by $1/(1+(\sigma/s)^2)$, $s$ being the crystal's spread, so that a weak or barely recorded reflection counts for little. The agreement of two crystals is the sum of the products of these values over the reflections they share, and the objective is that agreement summed over every pair of crystals, each in the indexing assigned to it. That sum is $(|M|^2 - \mathrm{const})/2$ with $M$ the per-reflection sum over all crystals, so a crystal's agreement with all the others is one dot product with $M$ less its own contribution: each crystal in turn takes the indexing in which that dot product is largest, $M$ is updated, and the passes repeat until no more than one crystal in a thousand moves. A pass costs one read of the reflections, not one per pair of crystals, which is what keeps tens of thousands of crystals to seconds. The objective only grows, so it converges; it is started four times (once from the indexing as found, three times from a seeded random assignment) and the start that ends highest is kept, and of the equally consistent answers related by an overall relabelling the one the crystals' cells favour together is taken (below) - where they say nothing, the one that moves the fewest crystals. The order of every floating-point sum is fixed (crystals in image order, sequential passes), so the result does not depend on the thread count. The run reports how clearly the crystals separated: for each crystal the correlation with the mean of all the others in its chosen indexing and in the best other one, compared by Fisher's $z$ in units of its standard error ($\sqrt{2/(n-3)}$ for $n$ shared reflections) — the median of that margin and the share of crystals above $3\sigma$. + +A twin law is only partly an ambiguity where the lattice is pseudo-merohedral: a crystal's refined cell then also says something about which axis is which - but only as far as the run's cell differs under the law by more than one crystal's cell scatters, and a cell refined in the indexing it was found in carries a trace of that indexing whatever the truth (a cell refined under the monoclinic constraint keeps its right angles where the indexing put them, and the convention of an obtuse $\beta$ is taken after indexing). Measured on a P2$_1$ run with two axes 0.2% apart, a former rule that let the cells decide a law once 90% of them fitted better as indexed locked 95% of the crystals in the indexing they had been found in at random: every cell fitted better as indexed, by construction. So the cells are read as evidence of the same kind as the intensities - a log-likelihood of each indexing, added to the intensities' for each crystal, never a lock. A crystal truly in indexing $g$ has, as indexed, the run's cell after the inverse of $g$. Its cell is compared with that prediction by shape: the logarithm of each length less their mean (the operators keep the volume; the size carries the distance and wavelength errors, which move all axes together) and each angle's distance from 90° (the obtuse convention cannot then carry the indexing); an angle the crystal's refinement held at 90° or 120° was not measured and is left out, and a cell several crystals share to the last digit is the prior the refinement did not move, which says nothing. The scatter of each of these six quantities about the prediction is fitted on the run itself, by expectation-maximisation over the indexings, each equally likely - so a law is told apart by the cells exactly as far as their scatter allows, with no tolerance to set. A crystal's intensities enter as $(n-3)(\zeta_\mathrm{right}-\zeta_\mathrm{wrong})\,\mathrm{atanh}(\mathrm{CC}_g)$ for each indexing $g$, $\mathrm{CC}_g$ being its correlation on $n$ reflections with the mean of all the other crystals (or with the reference): Fisher's $z$ of a correlation has a variance of $1/(n-3)$, so with $z$ near $\zeta_\mathrm{right}$ in the right indexing and $\zeta_\mathrm{wrong}$ in a wrong one the log-odds of two indexings is $(n-3)(\zeta_\mathrm{right}-\zeta_\mathrm{wrong})(z_g-z_h)$; $\zeta_\mathrm{right}$ is the run's median $z$ in the chosen indexing and $\zeta_\mathrm{wrong}$ the median of each crystal's mean $z$ over the other indexings (not the best of them, which on weak crystals reads as high as the right one and would weigh the intensities down to nothing). Without a reference, the intensities alone first make the crystals consistent as above, the cells choose the overall relabelling, and then each crystal in turn - taken out of the running sums, as in the sweep, so that every decision is made against the others as they stand - takes the indexing of highest summed log-likelihood against the mean of all the others, until no more than one in a thousand moves. Only an operator that keeps the merge's symmetry-equivalent reflections together is an overall relabelling: where the crystal's Laue group is not normal in the lattice's (a monoclinic crystal on a pseudo-tetragonal lattice), an operator that puts the two-fold on another axis would send crystals differing by the two-fold into different indexings and scramble a consistent answer, so it is never taken as one. With a reference, each crystal's correlation with it is a log-likelihood of the same form (its weight from the run's own separation of the best indexing from the others against the reference), and the reference and the cells together choose the overall relabelling, so that the merge is written in the reference's indexing; the report gives the number of crystals put into another indexing than their correlation with the reference alone would. A crystal itself is decided by its agreement with the other crystals and its cell, not by the reference: a reference - a model's intensities most of all - reads a weak crystal less clearly than the merge of all the others, and its correlation shares the crystal's own noise with that agreement, so the two are not independent evidence. Measured against model truth on a pseudo-tetragonal P2$_1$ run: 93% of the crystals the model can decide in the right indexing when each was decided on a model reference, 97% with the reference weighed in crystal by crystal, 99.5% with the reference fixing the indexing as a whole. The log gives the fitted scatter, per law the median log-likelihood by which a crystal's cell favours the indexing it came in, and the number of crystals the cells moved against their intensities. + +### 10.10 Ice rings at the scale and merge stages + +Whatever the gate of §3.3 found, every written merge is also read for ice in its own intensities: for each hexagonal-ice ring the merged reflections in the ring's core ($|q - q_{\mathrm{ring}}| < 0.015$ Å$^{-1}$) and in its flanks (out to $0.03$ Å$^{-1}$) are compared with a Wilson line fitted to the off-ring reflections within $0.15$ Å$^{-1}$ of the ring only, as the ratio of their mean intensity to the line and that ratio's excess in standard errors of the band's own scatter. A span so short in resolution cancels anisotropy and the curvature of the Wilson plot, which is what a z-score of a shell against a whole-dataset Wilson curve cannot do, and on the battery that z-score (phenix.xtriage's ice test) flagged broad features of the Wilson plot on some thirty crystals with flat radial profiles, while this one did not. The rings are then fitted together as one ring system - an additive intensity in proportion to hexagonal ice's line strengths - twice: the cores against the line, which is the size of the bias, and the cores against their own flanks, which decides. A ring is narrower than the flank offset, so it leaves a contrast between the two whichever way the integration bent it (a ring under the spots lifts the cores; a ring in the background annulus beside them depresses the cores and lifts the flanks - both are seen on the battery), while a feature of the Wilson plot broader than a ring moves core and flanks alike and cancels. The merge is read as carrying ice where the contrast stands at 5 sigma, either sign, over at least two rings (`ICE_INTENSITY_Z`). Where it fires on a run whose images showed no ring, the report warns and names the shells; the rings' reflections are not set aside after the fact. + +Where the gate of §3.3 has found ice, reflections falling within $\pm w$ in $q = 2\pi/d$ (§1.2) of a hexagonal-ice band ($w=0.03$ Å$^{-1}$ offline, about the measured ring half-width) are marked. Marked reflections are **excluded where a model is fitted** — the per-frame scale $G$, the per-image correlation, and the $P1$ merge the space-group search runs on — because ice contamination is a *positive bias*, not extra scatter, and a least-squares scale absorbs it into $G$ and into the error-model $b$, where it damages every other reflection on the same frame. They are also left out of the **resolution-cut fit** (§13.4), which is the one consumer that reads the *merged* reflections rather than the observations: an ice-flagged observation marks its merged reflection, on the rotation merge's own accumulator (host and device alike) as well as on the stills one. The stills merge keeps them in the final merge. The **rotation merge decides ring by ring**, because what a ring does to its reflections differs between rings and between runs: it can bias them (up on the ring, where its powder intensity is under the spot; down on the flanks, where it is in the background ring), only add scatter, or leave them alone. Deleting every band unconditionally was implemented once and removed: on a crystal whose band was harmless it removed better-than-average reflections and 6 to 8 points of completeness in the affected shell for no measurable gain. So each ring is split into its **core** ($|q-q_\mathrm{ring}|<0.01$ Å$^{-1}$) and its two **flanks** (out to $w$), and every band is compared with the off-ring merged reflections within $0.02$ Å$^{-2}$ of the ring in $1/d^2$. Both are read against a log-linear **Wilson fit** of the mean intensity over those off-ring reflections (the fit behind the reported Wilson $B$; over all off-ring reflections where the window cannot be fitted), as $t=(I-I_\mathrm{exp})/\sqrt{\sigma^2+I_\mathrm{exp}^2}$, which has unit scatter whether a reflection is signal- or noise-dominated. A band whose mean $t$ departs from its neighbours' by more than 3 standard errors is **rejected** — a bias, which no larger $\sigma$ would remove; one whose variance of $t$ exceeds the neighbours' by more than 3 standard errors of the log ratio (taken from the samples' own kurtosis: Wilson intensities are far from Gaussian) is **down-weighted**, its excess variance added to each reflection's own; the rest is **merged** as measured. A band of fewer than 20 reflections, or a ring with fewer than 50 neighbours, is merged. The decision is applied to the merge's accumulators, so the written reflections, the shell table and the half-set $\mathrm{CC}$ all see the same thing, and each band's verdict is logged and reported (`ICE_RING_BAND_nn`, see the results report). It complements the radial background correction (§9), which removes most of the bias at its source: on 58 rotation crystals with ice and a model, it lowered the model's R-free against merging every band on 26 and raised it on one, by 0.003. + +--- + +## 11. Mosaicity and “profile radius” monitoring + +### 11.1 Profile radius (intrinsic excitation-error width) + +The “profile radius” is the intrinsic angular width of a reflection — crystal mosaicity plus beam divergence — estimated from the spread of $\Delta_\mathrm{Ewald}$ over indexed spots, +$ +R \approx \sqrt{\tfrac{1}{N}\sum_i \Delta_{\mathrm{Ewald},i}^2}. +$ +When the beam has a finite energy bandwidth, that bandwidth smears each reflection radially by $\sigma_\mathrm{bw}\approx \mathrm{bandwidth}\cdot\lambda/2d^2$ (largest at high resolution), which also broadens the measured $\Delta_\mathrm{Ewald}$ spread. Since prediction re-applies the bandwidth term per reflection (§8.2), this contribution is deconvolved from the estimate — $R^2 = \langle\Delta_\mathrm{Ewald}^2\rangle - \langle\sigma_\mathrm{bw}^2\rangle$ — so that $R$ is the intrinsic width and bandwidth is not double-counted. Still predictions use an excitation-error cutoff proportional to $R$ where the run's rocking curve is not measured (`--simple-stills`, and the sample the curve is measured on; §8.2). + +### 11.2 Mosaicity from rotation data + +For rotation data the mosaicity $\sigma_M$ is estimated by maximum likelihood from the rocking offsets $\tau$ of indexed spots, using the XDS reflection-fraction model $R(\tau;\sigma_M/\zeta)$ (Kabsch 2010): each spot's exact Bragg angle is located near its frame, $\zeta$ (the rotation-axis Lorentz component) is computed, and $\sigma_M$ is chosen to maximize $\sum_i \log R(\tau_i;\sigma_M/\zeta_i)$. + +The $\phi$ search window for the Bragg angle is set **wider than the oscillation**, so that reflections recorded at large rocking offset are included. These tail reflections carry most of the information about the mosaic width; a window limited to the oscillation range would truncate the $\tau$ distribution and bias $\sigma_M$ low. + +The fit uses only the **strongest 250 spots** of an image, whatever the indexing spot budget (`--max-spots`) is. A spot is detected when $I_\mathrm{full}R(\tau)$ clears the finder threshold, so selecting spots by intensity censors on $R(\tau)$: a deeper list holds proportionally more large-$\tau$ partially recorded spots and the fit widens with it. Left uncapped, $\sigma_M$ therefore tracks the spot budget rather than the crystal — and since an over-wide mosaicity mis-states every partiality, the merge degrades sharply with it. + +The estimated mosaicity feeds the rotation prediction (how many frames each reflection spans, §8.3) and the rotation partiality (§10.2). It is **held fixed during scaling**: in the per-image scale fit the mosaicity is degenerate with the scale $G$ (both rescale the predicted intensity), so refining it there is unstable. A correct mosaicity matters because it controls both how much of each rocking curve is captured and the partiality used to form fulls (§10.6); too small a value truncates the captured curve and over-peaks the partiality, degrading the combined fulls. + +--- + +## 12. Auxiliary statistics: ⟨I/σ(I)⟩ and Wilson plot + +### 12.1 Per-shell ⟨I/σ(I)⟩ + +For monitoring integration quality, Jungfraujoch reports mean $\langle I/\sigma(I)\rangle$ in a fixed number of resolution shells. Shelling is performed in $1/d^2$ space (typical of crystallographic practice). + +### 12.2 Wilson plot (B-factor proxy) + +A Wilson-type analysis is computed by binning intensities by resolution and fitting: +$ +\langle I\rangle \propto \exp\!\left(-\frac{B}{2}\frac{1}{d^2}\right), +$ +i.e. +$ +\log \langle I\rangle = \mathrm{const} - \frac{B}{2}\left(\frac{1}{d^2}\right). +$ +A linear regression of $\log\langle I\rangle$ vs $1/d^2$ provides an estimate of $B$, subject to basic quality checks (e.g. $R^2$ threshold). + +A **dataset-wide** Wilson $B$ is also estimated over the merged reflections — restricted to the meaningful resolution range (skipping the low-resolution non-linear region below ~4 Å and shells past the signal limit $\langle I/\sigma\rangle < 1$, so it is insensitive to how far the merged data extend) — and written to the merged mmCIF as `_reflns.B_iso_Wilson_estimate` (and reported as `WILSON_B=`), the analogue of XDS's Wilson-line $B$. It is diagnostic only and is not fed back into scaling. +**It is the XDS convention, not the CCP4/Phenix one, and the two are not comparable.** The slope here is fitted to $\log\langle I\rangle$ directly; TRUNCATE, `ctruncate` and `phenix.xtriage` fit $\log(\langle I\rangle/\Sigma)$, dividing out $\Sigma=\sum_j f_j^2(s)$, the falloff of the atomic form factors for an assumed composition. Leaving $\Sigma$ in the slope inflates $B$ by roughly 2 to 8 Ų (measured across in-house merges; the arithmetic gives +6.9 Ų over 4.0-1.5 Å for a generic protein), and the fitted range accounts for more still: against `ctruncate` and `phenix.xtriage` on the same merged files this number runs 10 to 36 Ų high, in the same direction every time - though those two disagree with each other by 7 to 16 Ų, so there is a band rather than a right answer. Read it as a relative quantity, comparable between Rugnux runs and against XDS, and do not compare it with a value quoted from a CCP4 or Phenix log. The same caveat applies to `_reflns.B_iso_Wilson_estimate` in the merged mmCIF, whose deposited values are conventionally the $\Sigma$-normalised kind. It is also where the flux the fixed integration disk clips lands: that loss is degenerate with an overall $B$, so the reported number carries an $r_1$-dependent contribution and is not a property of the crystal alone (§9.1). The **per-image** estimate (used for the live radiation-damage plot) is accepted only when the fit is well-correlated and physically plausible ($0 < B < 200$ Ų); on a bad frame (an indexing glitch, too few reflections) the Wilson line runs wildly steep, so an implausible $B$ is reported as NaN rather than a spurious hundreds-of-Ų value. diff --git a/_sources/CPU_DATA_ANALYSIS_REFINEMENT.md.txt b/_sources/CPU_DATA_ANALYSIS_REFINEMENT.md.txt new file mode 100644 index 000000000..b0a12e309 --- /dev/null +++ b/_sources/CPU_DATA_ANALYSIS_REFINEMENT.md.txt @@ -0,0 +1,687 @@ +# Data analysis: refinement of a placed model (§15) + +Part of the [CPU/GPU data-analysis reference](CPU_DATA_ANALYSIS.md); the section numbers are continuous across its parts. + +```{contents} On this page +:local: +:depth: 2 +``` + +## 15. Restrained refinement of a placed model + +Wherever a model is placed - it fits where it is (§14.8), or molecular replacement placed it (§14.10) - +rugnux refines it against the merge it was placed on (`--no-refine` skips this). `rugnux --mode refine` +runs the same refinement on a model and merged structure factors that already exist. How to use it, and +what it writes, is in [Models and reference data](RUGNUX_MODEL_AND_REFERENCE.md#refinement); its report +keys are in [The results report](RUGNUX_REPORT.md#refinement-refine_). + +The refinement comes **after every processing decision and changes none of them**. Nothing it finds is +read by the space-group search, the indexing choice, the resolution cut or the files `.mtz`, +`_model.cif` and `_maps.mtz`; `R_WORK` and `R_FREE` stay those of the model as placed +(§14.3). What it produces is written beside them: the refined model, its map coefficients, the blobs of its +difference map and the `REFINE_` keys. + +The library reads and writes no file. The model and the reflections come in, the refined model, its +statistics and its map coefficients go out; the restraint dictionary is compiled into the binary (§15.4). + +### 15.1 What is refined, and in what order + +The model is taken as the refinement can use it: the first model of the file only, its hydrogens removed, +and every B clamped to the range the refinement allows (2 Ų up to twice the model's largest B, within +100-300 Ų). An atom's anisotropic U (ANISOU, `_atom_site_anisotrop`) is kept. Where the model has TLS +groups (`_pdbx_refine_tls*`, PDB `REMARK 3`) whose atoms bring no U of their own, their U is made from the +groups, and the B column is read either as the total B (as phenix.refine writes it) or as the residual to the +groups (as REFMAC writes it) - whichever of the two, and of the isotropic B as it stands, scores the lowest +R-free on the model as given (`REFINE_ADP_INPUT`). Occupancies are kept as they are, and +so are alternative conformations, each refined with its own restraints. + +Two stages follow. + +1. **Placement.** Each chain of at least 50 non-water atoms is moved as a rigid body - an angle-axis + rotation about its centroid, scaled by its rms radius so that a unit of rotation moves a typical atom by + about an angstrom, and a translation - against the X-ray target (§15.2), by Ceres' L-BFGS for 30 + iterations. Then one B shift per residue. Each of the two is **kept only where it lowers R-free by more + than 0.001**: a deposited model was refined atom by atom already, and moving its chains or shifting its + B factors residue by residue then only makes it worse. The placement stage needs no dictionary. +2. **Restrained refinement.** Every atom's position and isotropic B, against the X-ray target and the + geometry of the dictionary (§15.4-§15.5), in weight trials chosen by R-free (§15.7). Residues the + dictionary does not describe, and residues with an atom it does not know, are **held fixed**: they stay + in the structure factors, in the bulk-solvent mask and in the repulsions the refined atoms see, but + they do not move. So do atoms of zero occupancy. + +### 15.2 The X-ray target + +The target is the maximum-likelihood amplitude target: for an acentric reflection the Rice distribution of +the observed amplitude $F_o$ given the model's $|F_\mathrm{model}|$, for a centric one its centric +counterpart, + +$$ +-\ln L_\mathrm{acentric} = \ln\Sigma + \frac{F_o^2 + D^2|F_\mathrm{model}|^2}{\Sigma} - \ln I_0\!\left(\frac{2F_o D|F_\mathrm{model}|}{\Sigma}\right),\qquad +-\ln L_\mathrm{centric} = \tfrac12\ln\Sigma + \frac{F_o^2 + D^2|F_\mathrm{model}|^2}{2\Sigma} - \ln\cosh\frac{F_o D|F_\mathrm{model}|}{\Sigma}, +$$ + +(the terms that depend on neither the model nor the parameters left out) with $D$ the fraction of the model that is right and $\Sigma$ the variance that the rest of the structure and +the measurement leave (§15.3), summed over the working reflections. $\ln I_0$ and $I_1/I_0$ are evaluated +with the polynomial approximations of Abramowitz and Stegun, through the exponentially scaled form for large +arguments so that nothing overflows. The amplitudes are the French-Wilson $|F|$ of §10.8 - the ones the +written reflection file carries - and the free reflections are those of §10.7. + +$F_\mathrm{model}$ is the model of §14.2, + +$$ +F_\mathrm{model} = k\,e^{-\mathbf{s}^\top\mathbf{B}\mathbf{s}/4}\left(F_\mathrm{calc} + k_\mathrm{sol}\,e^{-B_\mathrm{sol}s^2/4}\,F_\mathrm{mask}\right), +$$ + +with the atoms' $F_\mathrm{calc}$ computed with the dictionary's riding hydrogens included (§15.4), from the IT92 +form factors: a single-atom ion (a metal or a halide the dictionary describes) as the ion its dictionary charge +makes it - Mg²⁺ and Na⁺ 10 electrons, K⁺, Ca²⁺ and Cl⁻ 18 - every other atom as the neutral atom, whatever formal +charge the file gives it (a carboxylate's O⁻, a lysine's N⁺); the refined model is written with those charges. The +scale, the anisotropic B, the bulk solvent and the likelihood's parameters are fitted at the start of each +**macro-cycle** (§15.3) and held fixed while the minimiser runs; the mask is drawn for the model as it is +at that point. + +**The gradient by the FFT method.** The atoms' density is placed on a grid with a Gaussian blur (the one +REFMAC-compatible density calculation uses, chosen for the lowest B a macro-cycle can reach) and transformed +once; the crystal's symmetry is composed in reciprocal space from the transform of one copy, as for the rigid +body (§14.8). The derivative of the target with respect to every structure factor, taken back to real space +by one inverse transform through the adjoint of that composition, is a map; each atom's derivatives with +respect to $x, y, z$ and $B$ are that map summed against the derivatives of its own blurred density. One +evaluation of the target and of the gradient of every atom thus costs a density gather, two FFTs and a +gradient gather, whatever the number of atoms. The derivative of a riding hydrogen is passed to its parent. + +### 15.3 Scale, bulk solvent and the likelihood parameters + +**Scale and solvent.** The flat bulk-solvent mask is drawn with the REFMAC radii (probe 1.0 Å, shrink 0.8 Å) +on a grid of its own, with a spacing of $d_\mathrm{min}/3$ or 0.4 Å, whichever is finer (coarser only where +a cell would need more than $2^{26}$ points, and then never coarser than 0.75 Å nor than the density grid, +which a cell that large uses for its mask). On the atoms' density grid the shrink is lost at low +resolution: at 3 Å its 1 Å step leaves no grid point within the shrink radius. $k_\mathrm{sol}$ and +$B_\mathrm{sol}$ are searched over their physical range on the working reflections, and the overall scale +and anisotropic B are fitted at each point of that search (§14.2) - at the points of its fine pass by +**robust least squares**: +iteratively reweighted (four reweightings), each reflection's residual $r = F_o - |F_\mathrm{model}|$ +weighted by $1/\sqrt{1 + (r/c)^2}$ with $c$ the median $|r|$ of the unweighted fit. The fit then minimises +the pseudo-Huber loss $\sum 2c^2\left(\sqrt{1 + (r/c)^2} - 1\right)$, quadratic for the bulk of the +reflections and linear for the few a model cannot explain - a beam-stop shadow, an ice ring, a missing part +of the model - which ordinary least squares would let set the scale of all the rest. When the B factors +are refined, the overall isotropic part of the scale's B is moved into the atoms (and into $B_\mathrm{sol}$, +so that $F_\mathrm{model}$ stays as it is); left in the scale, it and the atoms' B drift against each other +as the B factors are refined. + +With these three choices - riding hydrogens, the fine mask grid and the robust scale - the R-work and +R-free of a model as given (`REFINE_R_WORK_START`, `REFINE_R_FREE_START`) agree with REFMAC 5.8's 0-cycle +values on the same model and data within 0.006 on depositions from 1.1 to 3.6 Å +(`tools/battery/refine_parity.py`). + +**$D$ and $\Sigma$.** The two parameters of the likelihood are fitted by maximum likelihood in resolution +bins of the free set (100 free reflections to a bin, at most 30 bins; where the free set has fewer than +100 reflections, the working ones join it so that the likelihood still has a scale), and interpolated +linearly in $1/d^2$ between the bins' centres: + +- $\beta$ on the **free** reflections, as the whole spread of $F_o$ about $D F_\mathrm{model}$ with variance + $\varepsilon\beta$ - the measurement error included; +- $D$ then on the **working** reflections of the bin, with the variance + $\Sigma = \varepsilon\beta + 2\sigma^2$ for an acentric reflection and $\varepsilon\beta + \sigma^2$ for a + centric one, $\sigma$ the amplitude's own error. + +$\Sigma$ is also the variance of each reflection in the target. Where the measurement error is a large part +of the spread - the weak high-resolution shells - it is counted twice, and $D$ falls towards 0 there, with +the figure of merit. This division of the two parameters between the working and the free set is the one +REFMAC5 describes; measured on REFMAC 5.8's own output it reproduces its $D$ by bin and its overall figure of +merit (the mean over the working reflections) to about 0.01 on most depositions. + +### 15.4 The dictionary and the topology + +The restraints are those of the **CCP4 Monomer Library**, a subset of which is compiled into rugnux +(`image_analysis/structure_refinement/monomers/`, regenerated by `update_monomers.py`; nothing is read from +disk, and `$CLIBD` is never consulted): the 20 standard amino acids and MSE; the DNA and RNA nucleotides +(DA, DC, DG, DT, A, C, G, U); the modified nucleotides of tRNA and rRNA met most often - pseudouridine (PSU), +5-methylcytidine (5MC), 1-methyladenosine (1MA), the 2'-O-methyl nucleotides OMG, OMC and OMU, dihydrouridine +(H2U), N2-methyl- and N2,N2-dimethylguanosine (2MG, M2G), 7-methylguanosine (7MG) and ribothymidine (5MU), polymer +residues joined by the same backbone link; ATP, ADP, AMP, GTP, GDP and GMP; the cofactors NAD⁺ (NAD), NADH (NAI), +NADP⁺ (NAP), NADPH (NDP), FAD, FMN, heme (HEM), heme C (HEC), S-adenosylmethionine (SAM) and +S-adenosylhomocysteine (SAH), and dioxygen (OXY); DMSO; the PEG fragments PEG, PGE, PG4 and 1PE; glycerol, +ethylene glycol, MPD, acetate, sulfate and phosphate; water; and the ions Na, K, Mg, Ca, Mn, Fe²⁺, Fe³⁺, Co, Ni, +Cu, Zn, Cd, Cl, Br and I - 84 compounds - with the library's links and modifications that apply to them (among +them heme C's two thioethers to its cysteines, HEC-CYS1 and HEC-CYS2, and the covalent links of heme and FAD to +the protein) and the energy types those compounds use. + +The model's topology is built from it by GEMMI (`prepare_topology`): the links between residues (the peptide +and cis-peptide, the nucleic-acid backbone, disulfides, and the model's LINK records where the library +describes them), the modifications those links imply, and per residue the bonds, angles, torsions, chiral +volumes and planes. Torsions are restrained where the dictionary gives them an esd, except the main-chain +φ/ψ and the sugar puckers it lists as alternatives. The dictionary's **hydrogens** are added to every +residue it describes (waters excepted), placed by GEMMI from the dictionary's geometry and moved with their +parents: they take part in the structure factors and in no restraint, and are placed again on their +parents at every macro-cycle. The refined model is written with them. + +### 15.5 Geometry, metal and B restraints + +Every restraint is a squared normalised deviation, $E = ((x - x_\mathrm{ideal})/\sigma)^2$, with its +analytic derivatives: + +- **bonds and angles**, ideal and esd from the dictionary; +- **torsions**, modulo the dictionary's period, with derivatives in the form of Blondel and Karplus, free of + the singularities of the arccos form; +- **chiral volumes** $(\mathbf{a}_1 - \mathbf{c})\cdot((\mathbf{a}_2 - \mathbf{c})\times(\mathbf{a}_3 - \mathbf{c}))$, + $\sigma = 0.2$ ų; +- **planes**: the distances of the atoms from their least-squares plane (the plane's normal the smallest + eigenvector of the atoms' scatter, by Jacobi rotations); the plane is optimal, so the derivative of each + distance carries no term from the plane moving; +- **repulsions** of every pair of atoms closer than its contact distance, symmetry mates included, that no + bond, angle or 1-4 relation joins and that are not alternative conformations of each other, with at least + one of the two refinable: $E = ((d_0 - d)/0.2\,\text{Å})^2$ below the contact distance $d_0$ and nothing + above it, $d_0$ the sum of the energy types' van der Waals radii, 2.6 Å where both atoms can hydrogen-bond + and 1.9 Å between a metal and N, O or S. The list is rebuilt at every macro-cycle. + +**Special positions.** An atom closer than 0.5 Å to one of its own symmetry images (the depositions put theirs +within 0.03 Å of the site) is on a special position: the symmetry operations, each with its lattice translation, +that take it onto itself are its site symmetry (Grosse-Kunstleve & Adams 2002). It is placed exactly on the site - +the mean of its position and its images under the site symmetry - and its shifts are confined to the subspace +those operations leave unchanged: the gradient is projected by the mean of their rotations (along a 2-fold or +4-fold axis, nowhere on a centre of inversion). Its occupancy is kept as given, the coinciding copies each +counting it (0.25 on a 4-fold axis), it makes no contact with its own copies, each of its contacts is listed +once rather than once per copy, and it moves with no rigid body. + +**Metal sites.** A metal - an ion, or a metal atom of a ligand such as a heme's iron - is restrained to the +donor atoms (O, N or S) that the model's LINK / `_struct_conn` records bind it to. Where the library has a link for the pair - its ZN-CYS, ZN-HISND, +ZN-HISNE, FE-CYS, FE-HISND and FE-HISNE - that link is used as it is, with the modification it makes to +the donor's residue (the proton the bond replaces). Every other record becomes a link of one bond at the +distance of the library's own statistics of metal sites (its `metals.json`, carried as `monomers/metals.cif`) +for the metal, the donor element and the site's coordination number - but only where the model makes the +contact an inner-sphere one: no further than that distance plus 0.33 Å (Mg-O 2.07 + 0.33 = 2.4 Å, the +inner-sphere bound of Leonarski et al. 2017, the same margin for every metal). A record at an outer-sphere +distance - deposited models carry many, a Mg "bonded" to a phosphate O at 2.9 Å, a Na to a water at 3.0 Å - +would pull the ion onto that atom; it stays a contact instead. The coordination number is the number of +records the metal has within its inner sphere, plus the bonds its own residue's dictionary gives it (a heme iron's four pyrrole nitrogens) - interpolated linearly between two tabulated coordination numbers (rows resting on at least 20 sites +count; σ is the row's standard deviation, at least 0.02 Å). Only the bond is restrained, not +the angles at the metal. A contact without a record stays a repulsion, and a record to a symmetry mate is +left out, as every bond to a symmetry mate is. Which records stay contacts is decided once, on the model as given: one topology serves the whole refinement, its +solvent build included, so a record is not judged again on a distance the refinement has moved (a record at 2.50 Å +refused, the ion slid to 2.39 Å, would have been taken). The records are written out with the refined model as they were +read, without the names of the links made here. The rmsd of these bonds - with the dictionary's own bonds of +a metal within a ligand, a heme iron's to its porphyrin - is reported apart from the covalent bonds' +(`REFINE_RMSD_METAL_BONDS`). + +**Anisotropic atoms.** An atom's U is held as its equivalent isotropic B and a traceless anisotropy, +$U = U_\mathrm{dev} + B/(8\pi^2)\,I$, so that everything that refines, restrains and bounds B works on an anisotropic +atom as on an isotropic one, its shape held. Both engines grid it with its full U (an anisotropic Gaussian per +form-factor term, cut at the radius of its widest axis) and give the target's derivatives in its six U elements by the +same FFT method: for $\rho_q = a_q \exp(\mathbf{r}^T M_q \mathbf{r})$, $M_q = -4\pi^2(8\pi^2 U + B_q + B_\mathrm{blur})^{-1}$, +$\partial\rho_q/\partial U = \rho_q\,(M_q + 2 M_q\mathbf{r}\,\mathbf{r}^T M_q)$. Every U stays positive definite: its +smallest eigenvalue (as B) at least the cycle's floor, its largest at most the ceiling of §15.1. + +A **TLS group** gives each of its atoms $U = T + A L A^T + A S + S^T A^T$ at $\mathbf{r}$ from its origin, +$A = [[0, z, -y], [-z, 0, x], [y, -x, 0]]$ (Schomaker and Trueblood), plus a residual isotropic B per atom; its 20 +parameters (the trace of S does not enter U) are refined against the X-ray target alone, the residual B held, with +the derivatives by the chain rule from the atoms' U derivatives ($G$ for T, $A^T G A$ for L, $2 A^T G$ for S, $G$ an +atom's symmetric matrix of derivatives). An atom refined with a **U of its own** is restrained, for each pair of +bonded or angle-related atoms, by the rigid bond $|(U_i - U_j)\mathbf{n}|^2/\sigma^2$, $\sigma$ = 0.004 Ų along the +line $\mathbf{n}$ between them (the components SHELXL's RIGU restrains), and by the similarity +$|U_i - U_j|^2/\sigma^2$, $\sigma$ = 0.04 Ų (SIMU); an atom in no pair (a water, an ion) by +$|U - \mathrm{tr}(U)/3\,I|^2/\sigma^2$, $\sigma$ = 0.1 Ų (ISOR). + +**B restraints.** The B factors of two atoms are restrained to each other in proportion to their size, by +the symmetric Kullback-Leibler divergence of two isotropic Gaussians of variances $B_i$ and $B_j$: + +$$ +E = \frac{(B_i - B_j)^2}{\kappa^2 B_i B_j}, +$$ + +a difference restraint whose $\sigma$ is $\kappa\sqrt{B_iB_j}$, so that atoms of high B may differ more than +atoms of low B. $\kappa$ is 0.1 for bonded main-chain atoms and 0.133 for main-chain atoms bonded to a +common atom, 0.2 and 0.3 for the side chains and the rest, and 0.5 for atoms within 4 Å of each other (waters +among them, symmetry mates included) that no bond or angle relates. No atom's B goes below 2 Ų or above +the ceiling of §15.1. + +**NCS restraints.** Where the model holds several copies of one molecule, they are found from the model alone: two +polymer chains of one kind (protein, or nucleic acid) are copies where their sequences align with more than 15 +residues identical and identical in 80% of the longer chain or more, and their C-alpha (P) atoms lie within 2.5 Å +rms of each other after superposition - REFMAC5's criterion, the identity taken on the longer chain. The same +sequence in a conformation further away than that, such as a quasi-equivalent subunit of a virus capsid, is another +molecule. In the residues aligned to a residue of the same name, the atoms of the same name correspond - not a +hydrogen, not an alternative conformation, both refinable. Each copy is paired with the next of its molecule (and the +last with the first, where there are three or more), and each pair is restrained **locally**, on its interatomic +distances rather than on a superposition: every distance within a chain shorter than 4.2 Å in either copy, except those a bond or an angle of the dictionary already fixes, against the same +distance in the other copy, with the robust loss of Geman and McClure, + +$$ +E = rac{(\Delta/\sigma)^2}{1 + (\Delta/0.5\, ext{Å})^2},\qquad \Delta = d_\mathrm{copy\,1} - d_\mathrm{copy\,2}, +$$ + +the squared normalised difference where the two distances agree and never more than $(0.5\, ext{Å}/\sigma)^2$ where +they do not. A region in which the copies really differ - a loop in a crystal contact, a side chain in another +rotamer, a domain turned on a hinge - lets itself go as the refinement moves it, without a rule deciding in advance +which residues to exclude, and rigid motions of whole regions cost nothing, since only distances within 4.2 Å are +compared. Waters and ligands are not restrained, nor are B factors: the copies' B factors are refined independently. +Whether the restraints are used at all, and how tightly ($\sigma$), the weight trials decide (§15.7). + +### 15.6 The minimiser + +Positions and B factors are minimised in turn, each by an L-BFGS of rugnux's own (`RefinementMinimiser`), +with the two-loop recursion of Nocedal and of Liu and Nocedal, a memory of 20 pairs and a backtracking line +search from the full step to sufficient decrease, its first trial moving no position by more than 0.3 Å and +no B by more than 10 Ų. What sets it apart from a textbook L-BFGS: + +- **Its memory is kept from one macro-cycle to the next.** A macro-cycle is a few dozen iterations on a target + whose scale and likelihood parameters were refitted in between; starting each from what the earlier ones + learnt of the curvature, instead of from a steepest-descent step, is what lets two macro-cycles of a + weight trial get as far as many restarted ones. Each weight trial starts with an empty memory. +- **The B steps are scaled by their curvature.** The initial inverse Hessian of the B factors is a + diagonal: the X-ray target's curvature in each atom's B - its shape from the likelihood's curvature in + $|F_\mathrm{model}|$ and the atom's own scattering, summed in resolution shells, calibrated once per trial + against central differences of the gradient along a random $\pm1$ direction - plus the B restraints' + curvature, each element at least a thousandth of the median. The positions take none: their restraints' + curvature is that of stiff bonds and angles, which move atoms together, and as a diagonal it slows the soft + (torsion and X-ray) directions rather than scaling them. + +The diagonal is rescaled at each iteration by the latest pair (Oren-Shanno scaling in that metric). A solve +stops after its iteration budget (30 for the positions and 20 for the B factors per macro-cycle) or where an +iteration lowers the target by less than $10^{-7}$ of it. + +### 15.7 The weights, decided by trial + +The refined target is $w\,T_\mathrm{X\text{-}ray} + E_\mathrm{geometry}$ for the positions and +$w_B\,T_\mathrm{X\text{-}ray} + E_B$ for the B factors. Rather than fixing $w$ and $w_B$ in advance, rugnux +runs **short refinements at several weights and keeps the one that does best on the free set** - a weight +chosen late, on the evidence, instead of early at a rule. + +The starting weights balance the gradients: $w_0 = |\nabla E_\mathrm{geometry}| / |\nabla T_\mathrm{X\text{-}ray}|$, +the geometry's gradient taken on the model shaken by 0.1 Å (a refined model's geometry would give none), and +$w_{B,0}$ likewise from the B restraints on the B factors shaken by 20%. Each **trial** is two macro-cycles +(the scale, solvent and likelihood refitted, then the positions, then the B factors) from where it starts. +A trial is **within bounds** where its rmsd from the dictionary is at most 0.02 Å for bonds and 2° for +angles; one trial **displaces** another where it is within bounds and its R-free is lower by more than 0.001 +(differences smaller than that do not decide, and the trial listed first - on a ladder, the tighter +geometry - is kept). The trials +are: + +1. **The ladder from the placed model**: $w = w_0 \times \{1/1024, 1/128, 1/16\}$, each with the B factors + held and refined at $w_{B,0}$ - six trials. +2. **The trajectory**: up to eight steps, each a set of trials from where the last step ended - the weights + as they are, and in turn the positions' weight halved and doubled (halved because the geometry loosens at + one weight as the model improves, until it leaves the bounds) or the B factors' weight divided and + multiplied by four. A step is taken while it lowers R-free or R-work by more than 0.001 and its R-free + stays within 0.001 of the best so far, and the trajectory ends at its best step. On a deposited model, + whose free set the depositor's refinement has already fitted, R-work falls while R-free rises, and the + trajectory ends where it began. +3. **The final ladder**: the trajectory's weights times $\{1, 2\}$, kept where one displaces it (the weight halved + was never kept on 55 refinements, and taking it away changed no choice). +4. **The displacement model**, from where the weights ended (the B factors as they are: isotropic, or the model's U + held), each trial as long as a step on the positions where the weights ended, held - only the displacement + parameters refine, so the trials differ in the displacement model alone; the model chosen then takes a step with + the positions refined, kept where it displaces its trial (where the geometry is out of bounds there, which held + positions cannot mend, each trial refines the positions too, a macro-cycle longer than a step): TLS groups with a residual B - the model's own, one per chain + of at least 50 refinable atoms, and the chains cut into 4, 8 and 16 contiguous segments of at least 10 residues + as TLSMD cuts them (by dynamic programming over the least-squares fit of an isotropic TLS model, a quadratic B(r), + to the refined B factors), each cut where it gives more groups than the one before; and a U per atom, at the U + weight balanced as $w_{B,0}$ is (on the U shaken by 20% of its B) times $\{1/4, 1\}$. The cuts between one group + per chain and the finest run only where the finest fits the free set better (lower $-\ln L$) than one per chain, + and the U at its balanced weight only where the U at a quarter of it lowers R-free or $-\ln L$ of the free + reflections from where the weights ended; on 49 refinements of 33 structures neither the cuts' rule nor leaving + out the U weight $\times 4$ changed a choice taken. A + trial displaces the one before it (the first: where the weights ended) only where its geometry is within bounds + and both its R-free (beyond the tie) and the $-\ln L$ of the free reflections are lower: the free set tests the + parameters a model adds, so the choice is made on the evidence of each run, not at a resolution (Merritt 2012). + The refined U are written as ANISOU and the TLS groups as `_pdbx_refine_tls*` and `REMARK 3` (`REFINE_ADP_MODEL`, + `REFINE_ANISO_ATOMS`, `REFINE_TLS_GROUPS`). It is decided after the solvent build (§15.10), on the model with its + solvent: a water a round put in refines a U of its own in the per-atom trial as every refinable atom does, and no + TLS group holds a water. +5. **The model as given** is the first candidate in order of trust: where the refinement does not displace it by the + rule every trial is held to (its geometry within bounds and R-free lower beyond the tie), the model is written as + it came, scaled to the data, and the solvent build's edits are undone (`REFINE_AS_GIVEN`). What comes out is never + worse on the free set than what went in. This holds only where the free set is free to the model as given: a model + placed as given on a free set drawn by the run (in `--mode refine`, a file without free flags) has + most likely been refined against those reflections, and its R-free as given does not compete. + +Where the model has copies (§15.5), the NCS restraints are one more weight: every rung of the first ladder is run +without them, and then with them at $\sigma = 0.1$ Å at the B factors' weight the rungs without chose (NCS moves the +X-ray weight a rung up as often as not, the B factors' choice it never changed on 39 refinements), and every step of +the trajectory also tries them changed - switched on where they are off, and in turn tightened ($\sigma$ halved) and +loosened ($\sigma$ doubled, off beyond 0.4 Å) where they are on. Listed after their twin without, the restraints are +kept only where they lower R-free by more than the tie. A model without copies runs exactly the trials it ran before. + +$w$ never exceeds $w_0/8$. The trials of one set run side by side - on one GPU, on several, or on the CPU's +threads - each from the same start and taking nothing from the one before it, so the result does not depend +on how many run at once. + +The refinement can be cut short from outside (the broker's deadline or cancel, Ctrl+C): the check is made +between the minimiser's iterations and before every trial, the trials that finished are chosen among as +usual, and the report says so. Cut before the first trial, the model is the placement's. + +### 15.8 Maps of the refined model + +The refined model's map coefficients, `_refined_maps.mtz`, are $2mF_o - DF_c$ and $mF_o - DF_c$ as in +§14.4, but with $m$ and $D$ those of the refinement's own likelihood (§15.3) rather than the shell +$\sigma_A$ of §14.4, so the maps carry the weights the target was minimised with; $m$ is +$I_1(X)/I_0(X)$, $X = 2F_oD|F_\mathrm{model}|/\Sigma$, for an acentric reflection and $\tanh(X/2)$ for a +centric one. As in §14.4, the coefficients in the file have the overall anisotropy of the scale (the anisotropic +part of $k_\mathrm{total}$) divided out, while the maps the refinement reads itself (the blob finder, the solvent +audit) keep the observed scale. `FWT`/`PHWT` is filled at the reflections the data do not have with $D|F_\mathrm{model}|$ +and `FWT_no_fill`/`PHWT_no_fill` is not, as in §14.4; $F_\mathrm{model}$ there is the refined model's with the bulk +solvent and scale of the last fit. Where the merge kept the Bijvoet pairs, the anomalous difference map is made on the refined +model's phases too, written in the same file as `ANOM`/`PHANOM` (as in `_maps.mtz`; missing where a +reflection has no Bijvoet pair), and read by the blob finder below. + +### 15.9 Unexplained density: blobs + +The $mF_o - DF_c$ map of the refined model is searched for what the model leaves unexplained: the connected +regions above 3 σ that peak above 4 σ, found by flood fill (GEMMI's `find_blobs_by_flood_fill`, the method +of Coot's "unmodelled blobs"), each moved to the copy nearest the model and measured - peak, volume, the +density integrated above the cutoff, the nearest atom, the polar (N, O) atoms at 2.4-3.4 Å and the N, O or S +at 1.8-2.6 Å, and the anomalous map at its peak. Each gets one reading, by rules on what is measured: + +| Reading | Rule | +|---|---| +| `MODEL_ERROR` | within 1.6 Å of a model atom: the model's own atom out of place, or a missing alternative conformation | +| `ION` | at least 1.8 Å from the model, and an anomalous peak of at least 4 σ, or two metal-like contacts and a peak of at least 8 σ | +| `LIGAND` | larger than 1.5 times a single atom's blob at this resolution (a sphere of radius $d_\mathrm{min}/2$) and than 8 ų, at least 2.2 Å from the model | +| `WATER` | at least 2.2 Å from the model with at least one polar contact | +| `UNASSIGNED` | anything else | + +They are listed strongest first (by the integrated density) in `_blobs.json`, and the five strongest +in the report, each with the anomalous difference map's height at its peak where there is that map. A blob +read as `LIGAND` is density of ligand size where the model has nothing: a buffer molecule or an unmodelled side +chain is that as well as the compound that was soaked. The readings point a +person at the density; they do not identify a compound. + +### 15.10 The solvent audit + +Every water and every single-atom ion of the refined model (and, with `--refine-score-only`, of the model as +given) is measured in its surroundings and its density and scored as each of water, Mg²⁺, Na⁺, K⁺, Ca²⁺ and Cl⁻ +(NH₄⁺ is scored too, and only reported). The audit changes nothing; the solvent build below reads it to relabel +sites. Both run only with `--refine-solvent` (off by default). + +**What is measured.** The model's N and O atoms around the site, symmetry mates included, counted in the +coordination bands of Cat_Wiz - 1.9-2.3 Å (Mg-like), 2.3-2.6 Å (Na, Ca), 2.6-3.2 Å (K, water) - and in the +clash shells 3.2-3.4 and 3.4-3.6 Å beyond them. Each neighbour is typed from the dictionary's energy type +(donor, acceptor or both) and from the chemistry of its residue: Lys NZ, Arg NE/NH1/NH2 and a polypeptide's +N-terminal N are positive; Asp/Glu carboxylate O, a C-terminal carboxylate and a nucleotide's phosphate O are +negative; His ring N and the Asn/Gln amide ends are both donor and acceptor, as the model's orientation of +them is a guess. Also measured: the shortest distance between two neighbours closer than 2.6 Å (the +octahedron's cis O…O), the nearest positive and negative group, the other ions within 4.2 and 6 Å, the +bond-valence sum $V = \sum_j q_j \exp((R_0 - d_j)/0.37)$ over the N and O within 3.5 Å for each cation +($R_0$ of Brese & O'Keeffe, $q_j$ the neighbour's occupancy) with its normalised vector sum (CheckMyMetal's +nVECSUM), and the 2mFo-DFc, mFo-DFc and anomalous maps at the site, in their rms. + +**The electrons a site shows.** The site's own density is fitted to 2mFo-DFc with its neighbours' held - a local +real-space fit of one amplitude at a B tied to its surroundings: the map at points 0.3 Å apart within 1.0 Å of the +site, put on the model's scale, less the density the model's other atoms put there (each atom's IT92 density to +the data's resolution at its B, to 4.5 Å), against a water's density (O with its two H) at the environment's B +(the mean B of the N and O within 3.5 Å, as CheckMyMetal compares a metal's with its ligands'), least squares. +The amplitude, in waters, is the electrons it shows, and counted apart from the neighbours' that merge with it at +moderate resolution. The map's scale per model unit is the median, over the macromolecule's C, N and O within +6 Å (or all of them where fewer than three are), of each atom's height in the map over what the model puts there - +not the waters', whose occupancy is the model's guess (the depositions' waters show half the density their model +gives). An **ion** - whose label's restraints may hold it off its density - is read where that fit puts it, +within 0.6 Å of its modelled position (its shell, bands and bond valences are measured from there); a water where +it is modelled. On deposited models the ions typically read Mg 11, Na 10, Cl 19, K 21-23, Ca 22-26 and +Zn 33, the waters 4-6. + +**The anomalous signal a site would show.** For each species, f″ at the data's wavelength (Cromer-Liberman, with +the corrections of Kissel & Pratt, as GEMMI computes it) at the environment's B, put on the scale of the anomalous +map by least squares on the model's S and P (at least three); without an anomalous map, or nothing to scale it +by, the term is left out. + +**The score.** For each species, a plain sum of terms in log units: + +| Term | What it is | +|---|---| +| first shell | the neighbours in the species' band against the coordination number it holds (Mg 6, Na 5-6, K 6-10, Ca 6-8, Cl 3-5, NH₄⁺ 4), quadratic; for water only more than four, or none at all, costs; for Mg, Na, Ca and Cl a missing ligand costs little (0.5), as the model may simply not have that water - and a halide binds at hydrophobic surfaces too, with few donors or none (Dauter & Dauter 2001), where its electrons and its anomalous signal tell it from a water | +| distances | for Mg, each neighbour in the band against Mg-O 2.07 ± 0.04 Å, Mg-N 2.19 ± 0.08 Å; for the others, whose distances are spread over their bands, the band is all there is | +| contacts it does not make | 2 per N or O closer than the species' shell (closer than 2.9 Å for Cl), and for Mg per N or O in its exclusion zone 2.3-3.4 Å; for Mg and Ca 2 per first-shell purine N7 the site is more than 1.0 Å out of the plane of, or not 3.5-3.9 Å from the base's O6 or N6 (Leonarski et al. 2017) | +| chemistry | a cation: 2 per donor-only neighbour in its shell and per positive group within 3.5 Å; Cl: 2 per acceptor-only neighbour and per negative group within 3.2 Å; water: 2 per hydrogen bond beyond two donated or two accepted (neighbours at 2.6-3.4 Å) | +| bond valence | for a cation, $V$ against its charge $z$, Gaussian with a spread of $0.25z$ widened by the neighbours' distance errors, and the vector sum against CheckMyMetal's outlier bound 0.23 | +| electrons | the electrons the site shows against those the species would (its density's height over a water's at the environment's B: Mg²⁺ and Na⁺ about 11, K⁺, Ca²⁺ and Cl⁻ about 20) - an ion at full occupancy, a water as the model's waters show (their median) - log-normal with the spread of the waters' (an ion's occupancy and order vary as much), at least that of the map's calibration. A site as dense as a full 10-electron scatterer is so more than a typical water, as Echols et al. flag a light ion by a 2mFo-DFc above the waters' mean; where the density is weak the term tells little, and the shell decides | +| anomalous | the anomalous map at the site against what the species would show, Gaussian in the map's rms | + +A site bound to another cation (closer than 2.6 Å) shares that cation's other ligands as neighbours - the +cis waters of a Mg(H₂O)₆ are 2.9 Å apart - and those are left out of its score. **Coordinate error**: each +atom's is taken as its rms displacement $\sqrt{B/8\pi^2}$ times $d_\mathrm{min}/10$ Å (about 0.1 Å at B = 20 Ų +and 2 Å); a neighbour's band is widened by the error of the distance and its distance term is widened by it +too, so that where the coordinates are poor the species' shells overlap and the score stops telling them +apart instead of telling them apart wrongly. The best of water, Mg, Na, K, Ca and Cl is reported, and +`AMBIGUOUS` where the runner-up is within 2. The audit counts a site as disagreeing with its label where +the best species is another one, not ambiguously. + +**Caveats.** The refined model's metal-site distances are restrained (§15.5) where its LINK records name +the bonds, which pulls an ion's shell towards the label it carries - the first pitfall of every survey of +ions in the PDB; the local fit reads the ion where its density puts it, but its ligands stay where the restraints +held them. `--mode refine --refine-score-only` audits the model as given instead. The species are the six above: +a site denser than any of them (a cacodylate's As, a heavier metal) is called the heaviest that fits worst least. +Per site, everything above is in `_solvent.json` (with `electrons`, `b_env`, `peak_shift_A`, +`anomalous_expected`, `n7_ligands`, `n7_off_plane`); the counts are the `REFINE_SOLVENT_` keys of the report. + +**The solvent build.** Within the refinement, and to 2.8 Å (phenix.refine's ordered-solvent limit), waters are built +and removed and waters and ions relabelled, as phenix.refine builds waters within its macro-cycles. Where the weight +trajectory (§15.7) ends, a round reads the maps and the audit of that model and changes its solvent; then the solvent +alone - its waters and single-atom ions, the rest held - is refined at the weights the trajectory ended at (its B +too, at its balanced weight where the trajectory held B, and 10 iterations a macro-cycle), and the round is kept +where that lowers R-free; where it does not but the round as built does (refining the solvent alone can lose what its +sites gained), it +is kept as built; otherwise it is undone. The rest of the model goes on with its B factors held or refined as the +trajectory had them. The rounds stop at one that changes nothing, at one undone, or after two (a third gains +nothing measurable); the final ladder of §15.7 then +refines what they kept with the rest. The atom list of a refinement is fixed - its engines are made for it - so the +waters a round may add are in the model from the start as placeholders: one water each (as many as a fifteenth of the +model's heavy atoms, at least 64) at occupancy 0, which puts no density, no mask and no contact anywhere and is not +refined until a round puts one at a peak; a water taken out goes to occupancy 0 the same way, and a relabelled site +keeps its place. A round thus costs a map, an audit and a refinement of the solvent, so the build adds +somewhat less than the refinement's own time. `--refine-score-only` builds nothing, and the build and the audit run only with `--refine-solvent` +(off by default). + +- *Relabelled* is a water or a single-atom ion (no alternative conformer) whose best-supported species is another + one, not ambiguously - a water becomes an ion, an ion water or another ion - once per site. It takes the + species' residue name, element and atom name, and scatters as its ion (§15.2); its metal records go, and a metal + gets a record for each N, O and S of its inner sphere in the model's own copy (within the library's distance plus + 0.33 Å, at the coordination of those within an octahedral site's), which the next refinement restrains as it + restrains the model's own (§15.5). + +- *Candidates* are the local maxima of mFo-DFc from 3 σ (phenix.refine's peak cutoff), each symmetry-equivalent + set once, moved to the copy nearest the model - the symmetry operator and lattice translation that put it + closest to an atom of the model as written, so a water built there is written beside the model, not beside a + symmetry mate or in another unit cell. A peak closer than 1.2 Å to a model atom is that atom's own + residual and is passed over. +- *Not solvent* - reported in `_solvent.json` with the reason, never filled: a peak 1.2-1.9 Å from a model + atom (a missing or displaced atom); one beside a model atom (within 2.6 Å) that sits in mFo-DFc of -3 σ or + lower (the atom is displaced); one within 3 Å of where a truncated residue's missing atoms would be (an atom the + dictionary bonds to an atom the model lacks); the centre of three or more other peaks at 1.3-1.7 Å (a + tetrahedral group, sulfate or phosphate) or any peak with another 1.1-1.9 Å away (atoms of one molecule); + elongated density (the rms length of the density above 3 σ within 1.6 Å along its longest axis over its shortest + above 3); and 2mFo-DFc above every S and P of the model (a heavier atom). +- *A water* is placed where the peak has a hydrogen-bond partner - an N or O that can donate or accept at + 2.2-3.4 Å (phenix.refine's 3.2 Å, widened for the coordinate error), a metal within 2.6 Å (its ligand), or a + halide at 2.9-3.4 Å - and nothing closer than 2.2 Å to an N or O, nor than 3.0 Å to any other atom (Coot keeps + waters 2.4-3.2 Å from the model; a little wider here for the peak's position), strongest first, none within + 2.2 Å of one already placed. It goes into a chain of waters of its own, as PDB and mmCIF entries keep them - + chain `W` (or, where the model's chain `W` holds more than waters, the first of `X`, `Y`, `Z`, `V`, `U`, ... that + does not), `HOH` + residues numbered on from that chain's last, a water entity and subchain of their own in the mmCIF - with + occupancy 1 and the mean B of its partners. The model's own waters stay where they were. A peak on a special position (§15.5) is placed exactly on it with + occupancy 1 over the site's multiplicity, its coinciding copies one water; one 0.5-2.2 Å from its own + copy, which it would clash with, is refused. +- *Removed* is any water whose mFo-DFc at its centre is -3 σ or lower (the cut Echols et al. use), and a water the + build itself added that has no N, O or ion within 3.4 Å any more or whose B reached the refinement's ceiling. + phenix.refine's other filter, 2mFo-DFc below 1 σ at a refined water, is not used: it raises R-free, on + deposited waters and on the waters built here, and so does taking out deposited waters without a + partner. A weak water still explains density, and a deposited one + carries its depositor's judgement. + +`REFINE_SOLVENT_ADDED` and `REFINE_SOLVENT_REMOVED` count the waters added and still there and those of the model +as given taken out, `REFINE_SOLVENT_RELABELLED` the sites relabelled (each, with its scores, in the report and the +JSON); `REFINE_SOLVENT_NOT_SOLVENT` the not-solvent peaks of the final model's difference map; +`REFINE_SOLVENT_BUILD_ROUNDS` the rounds kept. The model as given (`REFINE_R_FREE_START`) and the placement stage are the first refinement's; the refined model, its R-factors (the `REFINE_SCORE_` terms with them), geometry, maps and blobs are the last kept round's. + +### 15.11 GPU and CPU + +On a CUDA build the target, the gradient and the restraints are evaluated on the card - the density gather, +cuFFT, the composition of the symmetry and the target per reflection, the adjoint through a CSR list, the inverse transform and one warp per atom for its gradient; the restraints in one kernel whose +per-atom gradient slots are summed in a fixed order; the robust scale fit and the fine solvent mask on the +card as well - with no floating-point atomics, so the result is the same from run to run. The weight trials +of a set run on as many cards as there are, each trial on an engine of its own. Where the case does not fit +the card's budget, or with `--no-gpu`, or on a build without CUDA (macOS included: on the Apple GPU only the model +density is put on the grid, §15.2, the rest has no Metal path), the CPU engine computes the same target, to +rounding, several times more slowly (seconds on a GPU, typically 2-15 minutes on the CPU). + +### 15.12 Twinned data + +Where the lattice admits a **twin law** for the group the data are merged in - a rotation of the lattice's metric +symmetry (Le Page two-folds within 3° of obliquity, the search the free set is grouped by, §10.7) that the group +lacks, one per coset of the group, with its square in the group so that it exchanges two domains - the placed +model is refined a second time, against the data as twinned by the law, and the two refinements are compared. +`rugnux ` does this on its own; nothing has to be given. + +**The target.** A crystal twinned by law $T$ at fraction $\alpha$ records $(1-\alpha)I(\mathbf{h}) + \alpha I(T\mathbf{h})$ +(Yeates 1997), so the model an observation is compared with is + +$$ +|F_\mathrm{twin}(\mathbf{h})| = k\,e^{-\mathbf{s}^\top\mathbf{B}\mathbf{s}/4}\sqrt{(1-\alpha)\,|F_\mathrm{calc}(\mathbf{h}) + F_\mathrm{sol}(\mathbf{h})|^2 + \alpha\,|F_\mathrm{calc}(T\mathbf{h}) + F_\mathrm{sol}(T\mathbf{h})|^2}, +$$ + +and the target is the likelihood of §15.2 with $|F_\mathrm{model}|$ replaced by $|F_\mathrm{twin}|$, $D$ and $\Sigma$ +fitted against it (§15.3). At $\alpha = 0$ it is the untwinned target exactly. It is an approximation: a twinned +amplitude is treated as Rice-distributed about $D|F_\mathrm{twin}|$, while the distribution of a sum of two +intensities is narrower; $\Sigma$, fitted to the free set, absorbs that, and REFMAC5's twinned-intensity likelihood +(Murshudov et al. 2011) is the treatment this one simplifies. The mates $T\mathbf{h}$ that were not observed are +composed as rows of their own, with no observation: their structure factors come from the same transform, so a +twinned evaluation costs no extra FFT, only one more kernel per evaluation on the GPU (the twinned term per +reflection and the gather of its mates' derivatives, through the converse of the mate table, as a three-fold of +several domains is not an involution). + +**The fraction, the scale and the solvent** are fitted inside the twin sum at every macro-cycle: the scale and the +solvent as in §15.3, then $\alpha$, then the scale and the solvent again against $F_o$ detwinned by the model as it +stands, $F_o|F_\mathrm{model}(\mathbf{h})|/|F_\mathrm{twin}(\mathbf{h})|$ (at which scale the twinned model meets $F_o$ +as the untwinned one meets the detwinned $F_o$), then $\alpha$ again. $\alpha \in [0, 1/2]$ comes from the regression +of $F_o^2$, with an intercept, on the model's intensities at $\mathbf{h}$ and at $T\mathbf{h}$, all normalised in +resolution shells of 500 reflections: $\alpha = b_{T\mathbf{h}}/(b_\mathbf{h} + b_{T\mathbf{h}})$, over the working +reflections that are not their own mate. The expectation of $F_o^2$ given the model, $D^2|F_\mathrm{model}|^2 + \Sigma$, +is linear in the two intensities, so an unrelated partner takes a coefficient of 0 however poor the model; a +least-squares fit of the twinned amplitudes instead took a fraction of 0.16 for unrelated partners of one model at +R-free 0.31, the average of two predictions being a better prediction than either. + +**The decision.** The twinned refinement is kept where its fraction is above 0 and the law beats its own **null** +on the free reflections by at least three standard errors - the null being the same twinned model at the same +fraction with every reflection's mate replaced by an unrelated reflection of the same resolution and of the same +set (a free reflection's by a free one, as a law's are): what the averaging of two intensities buys whatever they +are (it lifts a weak reflection's model amplitude off zero). The comparison is paired, reflection by reflection, +$|F_o - |F_\mathrm{null}|| - |F_o - |F_\mathrm{twin}||$ over the free set, summed over each free twin pair (the two +mates share their two $F_\mathrm{calc}$, so they are one term, not two independent ones), its mean against its +standard error (`REFINE_TWIN_NULL_Z`). The R-free of the twinned refinement against the untwinned one's does not +enter: two refinements of one model differ in R-free by a few thousandths from their trajectories alone, and any +twin target lowers R by its averaging, so that comparison favours the twinned one with or without a twin. A pseudo-symmetry the model already carries (non-crystallographic +symmetry parallel to the law) predicts $I(T\mathbf{h}) \approx I(\mathbf{h})$, so the law changes nothing and is not +taken for a twin. + +**The data's own evidence.** A lead of two to three standard errors is enough where the merge's intensity statistics +read twinned as well - the L-test itself below 0.44 (`TWINNING_VERDICT` `INDICATED` with +`ESTIMATED_TWIN_FRACTION_FROM` `L_TEST`; not where only the second moment reads low, nor where a pseudo-translation +leaves the L-test unreadable): two independent pieces of evidence, the data's and the model's, then agree. +`REFINE_TWIN_RULE` says which rule decided. The data-side test is not made a gate - it misses twins a model sees, a +pseudo-merohedral law or a near-perfect twin among them - only further evidence where the null alone is short. +`--mode refine` has no merge statistics, so there the null alone decides. + +**The free set is closed under the lattice's domains** before either refinement, so that both use one free set +and no law splits a group of twin-related reflections between the working and the free set (REFMAC5 does the same, +Roversi et al. 2012). The groups are the orbits of the merged reflections under every domain operator of the lattice +(below); an orbit the flags already keep in one set stays there, and a split one goes free with the probability of its +own share of free flags, drawn by a hash of the orbit, so the free fraction stays what it was. A majority of each +orbit's flags would empty the free set where the flags were drawn on smaller orbits - a C-centred orthorhombic merge +of a hexagonal metric, whose flags (§10.7) are drawn on the orthorhombic holohedry of the cell's own basis vectors, lost +three quarters of it that way. The free set rugnux draws is already closed for every law that is a rotation of the +cell's own basis vectors, and nothing moves; a law of a centred lattice that is not (its matrix fractional in the +cell's basis), or a free set `--mode refine` reads from a file, can be split, and the closure is what lets such a law +be tested at all. `REFINE_TWIN_FREE_CLOSED` counts the reflections that changed set. A law still split (none is, +after the closure, unless its mates fall outside the orbits the data have) is reported (`REFINE_TWIN` +`FREE_SET_SPLIT`) rather than tested. Of several laws, the one the placed model asks the largest fraction of is refined. Each of the +two refinements is a whole one - its solvent built (§15.10) and its displacement model chosen (§15.7) against its +own target - and the decision is taken where they ended. `--refine-score-only` makes the same test on the model +as given: it is scored against the data untwinned and twinned by the law, and the twinned score is taken by the +same rule. + +**More than two domains.** A lattice can hold more domains than two: a monoclinic crystal on a tetragonal metric +four, on a hexagonal one six (Sultana et al. 2007; Roversi et al. 2012). Where the single law is taken and the lattice +has more domain operators - every coset of the group in the lattice's metric symmetry, whatever the operator's order, +three-folds included - a second rung refines every domain at once, each with its own fraction: +$|F_\mathrm{twin}(\mathbf{h})|^2 \propto a_0|U(\mathbf{h})|^2 + \sum_d a_d|U(T_d\mathbf{h})|^2$, $a_0 = 1 - \sum_d a_d$, +the fractions from the same intercept regression with one column per domain, a domain whose coefficient comes out +negative taken out and the rest fitted again. It is taken where the added domains beat **their own null** - the +same model with the added domains' mates replaced by unrelated reflections and the adopted law's kept - by three +standard errors on the free set, summed over each twin group, and each added domain refines to a fraction of 0.05 or +more (as REFMAC5 drops small domains, Murshudov et al. 2011); the domains under it are dropped and the rest refined +again, and with none left the single law stands. `REFINE_TWIN_MULTI` (`MULTI_TWINNED`, `MULTI_UNTWINNED`) says what +was decided, `REFINE_TWIN_MULTI_DOMAINS` the domains and their fractions; where `MULTI_TWINNED`, `REFINE_TWIN_LAW` +lists every law and `REFINE_TWIN_FRACTION` is their sum, and every other `REFINE_` key is of that refinement. The +rung is not tried where the single law was refused: a twin that only several domains show at once is a symmetric +one, whose single-law fraction is already large. + +**Maps.** Against twinned data the map coefficients use $F_o$ detwinned in proportion to the model's own share of +the twinned intensity, $F_o|F_\mathrm{model}(\mathbf{h})|/|F_\mathrm{twin}(\mathbf{h})|$, and $DF_c$ of the model's own +$|F_\mathrm{model}(\mathbf{h})|$; `FP` in `_refined_maps.mtz` is the detwinned amplitude. + +The keys are `REFINE_TWIN` (`NO_TWIN_LAW`, `FREE_SET_SPLIT`, `ZERO_FRACTION`, `UNTWINNED`, `TWINNED`), +`REFINE_TWIN_LAW`, `REFINE_TWIN_FRACTION`, `REFINE_TWIN_R_WORK`/`_R_FREE`, `REFINE_TWIN_R_FREE_NULL`, `REFINE_TWIN_NULL_Z` and +`REFINE_UNTWINNED_R_WORK`/`_R_FREE`, the last five of the two refinements where they ended. Where `REFINE_TWIN` is `TWINNED`, every +other `REFINE_` key, `REFINE_R_FREE_START` and the `REFINE_SCORE_` terms included, is of the twinned refinement. + +### 15.13 Not yet + +What the refinement does not do yet - each a known gap, not a design choice: + +- **Custom ligands and other monomer libraries.** Only the 84 compounds of §15.4 are restrained. Any other + residue is held fixed (it stays in $F_\mathrm{calc}$, the mask and the repulsions); no restraints are + generated for a new ligand, and neither a user's restraint CIF nor an external monomer library can be given. +- **TLS restraints**: a TLS group's T and L are not held positive semi-definite (only every atom's total U is kept + positive definite); the TLS groups are contiguous segments of one chain, never a domain made of several. +- **Global NCS and NCS of B factors**: copies are restrained locally, on their interatomic distances (§15.5), + never by a superposition, and their B factors are refined independently; ligands and waters are not restrained + between copies. +- **Ion identification beyond the six species**: waters and ions are relabelled among water, Mg²⁺, Na⁺, K⁺, Ca²⁺ + and Cl⁻ (§15.10); NH₄⁺ is only reported, transition metals (Zn, Mn, ...) are measured but never relabelled, and no + ion is placed at a peak that is not a water first. A site's hypotheses are compared by a local fit of its + density, not by refining each in turn. +- **Alternative conformations and occupancies**: existing conformers are refined in place; no occupancy is + refined and no conformer is added. +- **Rotamer and peptide-flip search**, and **Ramachandran restraints**. +- **Real-space refinement**, and **jelly-body or reference-model restraints**. +- **A full Metal (Apple GPU) path**: on macOS the model density is gathered on the GPU and the rest of the + refinement runs on the CPU. +- **Validation beyond geometry**: the report gives the bond and angle rmsd, the metal-bond rmsd and the + number of clashes, not a MolProbity-style analysis (Ramachandran, rotamer and clashscore statistics). + +## References + +- R. C. Agarwal, "A new least-squares refinement technique based on the fast Fourier transform algorithm", *Acta Cryst.* **A34** (1978), 791-809 (the gradient by the FFT method, §15.2). +- N. S. Pannu & R. J. Read, "Improved structure refinement through maximum likelihood", *Acta Cryst.* **A52** (1996), 659-668, and G. N. Murshudov, A. A. Vagin & E. J. Dodson, "Refinement of macromolecular structures by the maximum-likelihood method", *Acta Cryst.* **D53** (1997), 240-255 (the maximum-likelihood amplitude target and its figure of merit, §15.2, §15.8). +- G. N. Murshudov, P. Skubák, A. A. Lebedev, N. S. Pannu, R. A. Steiner, R. A. Nicholls, M. D. Winn, F. Long & A. A. Vagin, "REFMAC5 for the refinement of macromolecular crystal structures", *Acta Cryst.* **D67** (2011), 355-367 (D from the working set and the variance from the free, §15.3; the Kullback-Leibler form of the B restraints, §15.5; the twinned refinement §15.12 simplifies, its twin laws pruned by fraction and its fractions refined by least squares). +- R. J. Read, "Improved Fourier coefficients for maps using phases from partial structures with errors", *Acta Cryst.* **A42** (1986), 140-149 (the m, D weighting of the map coefficients, §15.8). +- T. O. Yeates, "Detecting and overcoming crystal twinning", *Methods Enzymol.* **276** (1997), 344-358 (the twinned intensity, §15.12). +- A. A. Lebedev, A. A. Vagin & G. N. Murshudov, "Intensity statistics in twinned crystals with examples from the PDB", *Acta Cryst.* **D62** (2006), 83-95 (twin laws from the lattice's metric, §15.12). +- R. Herbst-Irmer & G. M. Sheldrick, "Refinement of twinned structures with SHELXL97", *Acta Cryst.* **B54** (1998), 443-449 (twinned refinement with the fraction refined beside the model, §15.12). +- V. Y. Lunin & T. P. Skovoroda, "R-free likelihood-based estimates of errors for phases calculated from atomic models", *Acta Cryst.* **A51** (1995), 880-887, and V. Y. Lunin, P. V. Afonine & A. G. Urzhumtsev, "Likelihood-based refinement. I. Irremovable model errors", *Acta Cryst.* **A58** (2002), 270-282 (the likelihood's parameters from the free set, §15.3). +- J.-S. Jiang & A. T. Brünger, "Protein hydration observed by X-ray diffraction: solvation properties of penicillopepsin and neuraminidase crystal structures", *J. Mol. Biol.* **243** (1994), 100-115, and A. Fokine & A. Urzhumtsev, "Flat bulk-solvent model: obtaining optimal parameters", *Acta Cryst.* **D58** (2002), 1387-1392 (the flat bulk-solvent mask and its parameters, §15.3). +- P. V. Afonine, R. W. Grosse-Kunstleve & P. D. Adams, "A robust bulk-solvent correction and anisotropic scaling procedure", *Acta Cryst.* **D61** (2005), 850-855 (the grid search over the solvent parameters, §15.3). +- P. J. Huber, "Robust estimation of a location parameter", *Ann. Math. Statist.* **35** (1964), 73-101, and P. Charbonnier, L. Blanc-Féraud, G. Aubert & M. Barlaud, "Deterministic edge-preserving regularization in computed imaging", *IEEE Trans. Image Process.* **6** (1997), 298-311 (the robust scale fit and its smooth, pseudo-Huber loss, §15.3). +- A. A. Vagin, R. A. Steiner, A. A. Lebedev, L. Potterton, S. McNicholas, F. Long & G. N. Murshudov, "REFMAC5 dictionary: organization of prior chemical knowledge and guidelines for its use", *Acta Cryst.* **D60** (2004), 2184-2195 (the restraint dictionary, §15.4). +- M. Wojdyr, "GEMMI: A library for structural biology", *J. Open Source Softw.* **7** (2022), 4200 (the topology, the riding hydrogens and the blob search, §15.4, §15.9). +- V. Schomaker & K. N. Trueblood, *Acta Cryst.* **B24** (1968), 63-76, and M. D. Winn, M. N. Isupov & G. N. Murshudov, *Acta Cryst.* **D57** (2001), 122-133 (TLS, and the B column total or residual to it, §15.1, §15.5); J. Painter & E. A. Merritt, *Acta Cryst.* **D62** (2006), 439-450 (TLSMD's segments, §15.7). +- F. L. Hirshfeld, *Acta Cryst.* **A32** (1976), 239-244, A. Thorn, B. Dittrich & G. M. Sheldrick, *Acta Cryst.* **A68** (2012), 448-451, and G. M. Sheldrick, *Acta Cryst.* **C71** (2015), 3-8 (the rigid-bond, similarity and isotropy restraints of anisotropic atoms, §15.5); E. A. Merritt, *Acta Cryst.* **D68** (2012), 468-477 (the displacement model decided by test, §15.7). +- A. Blondel & M. Karplus, "New formulation for derivatives of torsion angles and improper torsion angles in molecular mechanics: elimination of singularities", *J. Comput. Chem.* **17** (1996), 1132-1141 (the torsion derivatives, §15.5). +- M. M. Harding, "Geometry of metal-ligand interactions in proteins", *Acta Cryst.* **D57** (2001), 401-411, and "Small revisions to predicted distances around metal sites in proteins", *Acta Cryst.* **D62** (2006), 678-682; F. Leonarski, L. D'Ascenzo & P. Auffinger, "Mg2+ ions: do they bind to nucleobase nitrogens?", *Nucleic Acids Res.* **45** (2017), 987-1004 (the metal-site distances, §15.5). +- R. W. Grosse-Kunstleve & P. D. Adams, "Algorithms for deriving crystallographic space-group information. II. Treatment of special positions", *Acta Cryst.* **A58** (2002), 60-65 (the site symmetry and the constraint of an atom on a special position, §15.5). +- D. T. Cromer & D. A. Liberman, "Anomalous dispersion calculations near to and on the long-wavelength side of an absorption edge", *Acta Cryst.* **A37** (1981), 267-268, and L. Kissel & R. H. Pratt, "Corrections to tabulated anomalous-scattering factors", *Acta Cryst.* **A46** (1990), 170-175 (f″ at the data's wavelength, §15.10). +- Z. Dauter & M. Dauter, "Entering a new phase: using solvent halide ions in protein structure determination", *Structure* **9** (2001), R21-R26 (halides at sites with few donors, §15.10). +- N. Echols et al., "Automated identification of elemental ions in macromolecular crystal structures", *Acta Cryst.* **D70** (2014), 1104-1114 (a light ion flagged by its density above the waters', §15.10). +- J. Nocedal, "Updating quasi-Newton matrices with limited storage", *Math. Comp.* **35** (1980), 773-782, and D. C. Liu & J. Nocedal, "On the limited memory BFGS method for large scale optimization", *Math. Program.* **45** (1989), 503-528 (the minimiser, §15.6). +- A. T. Brünger, M. Karplus & G. A. Petsko, "Crystallographic refinement by simulated annealing: application to crambin", *Acta Cryst.* **A45** (1989), 50-61 (the starting weight from the ratio of the gradients, §15.7). +- P. V. Afonine et al., "Towards automated crystallographic structure refinement with phenix.refine", *Acta Cryst.* **D68** (2012), 352-367 (weights chosen among refinements by R-free within geometry bounds, and the overall B moved into the atoms, §15.3, §15.7). +- A. T. Brünger, "Free R value: a novel statistical quantity for assessing the accuracy of crystal structures", *Nature* **355** (1992), 472-475 (R-free). +- G. J. Kleywegt, "Use of non-crystallographic symmetry in protein structure refinement", *Acta Cryst.* **D52** (1996), 842-857; I. Usón, E. Pohl, T. R. Schneider, Z. Dauter, A. Schmidt, H.-J. Fritz & G. M. Sheldrick, "1.7 Å structure of the stabilized REIv mutant T39K. Application of local NCS restraints", *Acta Cryst.* **D55** (1999), 1158-1167; R. A. Nicholls, F. Long & G. N. Murshudov, "Low-resolution refinement tools in REFMAC5", *Acta Cryst.* **D68** (2012), 404-417; J. J. Headd et al., "Flexible torsion-angle noncrystallographic symmetry restraints for improved macromolecular structure refinement", *Acta Cryst.* **D70** (2014), 1346-1356 (local NCS restraints with a robust loss, decided by R-free, and Murshudov et al. 2011 above for the copies found by alignment, §15.5, §15.7). +- P. Emsley, B. Lohkamp, W. G. Scott & K. Cowtan, "Features and development of Coot", *Acta Cryst.* **D66** (2010), 486-501 (unmodelled blobs, §15.9). +- N. Naleem, A. Henning-Knechtel, S. Kirmizialtin & P. Auffinger, "Cat_Wiz: a stereochemistry-guided toolkit for locating, diagnosing, and annotating Mg2+ ions in RNA structures", *Nucleic Acids Res.* **54** (2026), gkag120; F. Leonarski, L. D'Ascenzo & P. Auffinger, *Nucleic Acids Res.* **45** (2017), 987-1004 and *RNA* **25** (2019), 173-192; F. Leonarski, A. Henning-Knechtel, S. Kirmizialtin, E. Ennifar & P. Auffinger, *Nucleic Acids Res.* **53** (2025), gkae1148 (the coordination bands, distances and exclusion zone of the solvent audit, §15.10). +- P. V. Afonine et al., "Towards automated crystallographic structure refinement with phenix.refine", *Acta Cryst.* **D68** (2012), 352-367, and P. Emsley, B. Lohkamp, W. G. Scott & K. Cowtan, "Features and development of Coot", *Acta Cryst.* **D66** (2010), 486-501 (the peak cutoff, the partner and clash distances and the resolution limit of the water build, §15.10). +- N. Echols et al., "Automated identification of elemental ions in macromolecular crystal structures", *Acta Cryst.* **D70** (2014), 1104-1114, and N. Morshed, N. Echols & P. D. Adams, "Using support vector machines to improve elemental ion identification in macromolecular crystal structures", *Acta Cryst.* **D71** (2015), 1147-1158 (the ligand sphere and the halide rules, §15.10). +- H. Zheng et al., "CheckMyMetal: a macromolecular metal-binding validation tool", *Acta Cryst.* **D73** (2017), 223-233 (the vector sum, §15.10); O. Carugo, "Buried chloride stereochemistry in the Protein Data Bank", *BMC Struct. Biol.* **14** (2014), 19 (the chloride's shell, §15.10). +- I. D. Brown & D. Altermatt, *Acta Cryst.* **B41** (1985), 244-247, and N. E. Brese & M. O'Keeffe, "Bond-valence parameters for solids", *Acta Cryst.* **B47** (1991), 192-197 (the bond-valence sums, §15.10). +- M. Abramowitz & I. A. Stegun, *Handbook of Mathematical Functions*, National Bureau of Standards (1964), 9.8.1-9.8.4 (the Bessel functions of the target, §15.2). + +The full citations, with DOIs, are in [ACKNOWLEDGEMENT.md](ACKNOWLEDGEMENT.md). diff --git a/_sources/DEPLOYMENT.md.txt b/_sources/DEPLOYMENT.md.txt new file mode 100644 index 000000000..b940e01f8 --- /dev/null +++ b/_sources/DEPLOYMENT.md.txt @@ -0,0 +1,202 @@ +# Deployment + +To deploy Jungfraujoch, one needs to follow these steps: + +1. Install main Jungfraujoch code and frontend web interface +2. Flash the U55C FPGA card with a proper image and install Linux kernel driver +3. Install Jungfraujoch writer +4. Install Jungfraujoch image viewer (optional) +5. Install Python OpenAPI client + +[`rugnux`](RUGNUX.md), the offline analysis tool, is installed separately and independently of +all of them — see [Install Rugnux](#install-rugnux-offline-analysis) at the end of this page. + +The installation procedure depends a lot on the operating system. For Red Hat Enterprise Linux 8/9, Rocky 8/9, +Ubuntu 22.04/24.04 or compatible, installation can be done with prebuilt packages from the +[package repositories](REPOSITORIES.md) and is relatively straightforward. For other systems one needs +to build software from source. Both ways will be presented. What each released package contains, and +what it needs on the machine, is described in [Release contents](RELEASE_CONTENTS.md). + + +## Install main Jungfraujoch code and frontend web interface + +On RHEL 8/9 and Ubuntu systems the prebuilt `jfjoch` package from the [repositories](REPOSITORIES.md) contains all the necessary software and the web interface. + +On other OSes one needs to compile Jungfraujoch from source (from the repo directory): +``` +$ mkdir build +$ cd build +$ cmake .. -DCMAKE_INSTALL_PREFIX= +$ make +$ sudo make install +``` +For manual installation, we recommend using a non-standard directory (like `/opt/jfjoch`), to facilitate upgrades and removal. +For DKMS to manage kernel module sources it is necessary to copy driver sources to `/usr/src/jfjoch-` directory. This requires an extra CMake flag `-DJFJOCH_INSTALL_DRIVER_SOURCE=ON`. + +Frontend web user interface has to be built separately with: +``` +$ cd build +$ make frontend +``` +Frontend files (.html and .js) are placed in `frontend/dist` (outside of `build/` directory!); `make install` copies that directory to `/share/jfjoch/frontend` (default prefix `/opt/jfjoch`), and the broker serves whatever directory the `frontend_directory` of its configuration names. + +## Flash the U55C FPGA card with a proper image and install Linux kernel driver + +### Firmware flashing +1. Check that the card is detected by OS with "lspci |grep Xilinx" and check the PCIe bus/device/function (BDF) number, `23:00.0` in this case: +``` +$ lspci |grep Xilinx +23:00.0 Processing accelerators: Xilinx Corporation Device 3450 (rev 2) +``` +Note the device number `3450` that identifies Jungfraujoch device (Jungfraujoch pass is 3450 m above sea level) and `rev 2` identifying release of the firmware. + +2. Check the speed of the card, that it is detected as PCIe Gen4x8 device (needs to be done as root, otherwise configuration details are not given): +``` +$ sudo lspci -vv -s +23:00.0 Processing accelerators: Xilinx Corporation Device 3450 +(...) +LnkSta: Speed 16GT/s (ok), Width x8 (ok) +(...) +``` + +3. Download the MCS image from release files or build it using Vivado (WARNING! building time can be about 8 hours and doesn't always reach correct timing). +4. Flash the card with `xbflash.qspi` tool (part of Jungfraujoch). For fresh card use: +``` +sudo xbflash.qspi --primary --card --bar-offset 0x1f06000 +``` +For card that was already flashed with Jungfraujoch images: + +``` +sudo xbflash.qspi --primary --card +``` +It is necessary to confirm the operation by pressing `Y` key or one can add `--force` option to avoid confirmation. +It is safe to run multiple flashing processes in parallel for different cards, for example in separate screen sessions. + +5. Cold reboot: +``` +sudo ipmitool chassis power cycle +``` + +### Install PCIe driver + +For the first run it is recommended to try the driver without installing it into the kernel directory: +``` +$ cd fpga/pcie_driver +$ make +$ sudo insmod jfjoch.ko +``` + +Check with `dmesg` that the device was properly found: +``` +$ dmesg |grep jfjoch +[ 431.624933] jfjoch 0000:23:00.0: enabling device (0140 -> 0142) +[ 431.919147] misc jfjoch0: Jungfraujoch FPGA loaded with FW build: 5610030a +``` + +If things work, it is recommended to install the driver with DKMS, so it is rebuilt for kernel updates. +Install the prebuilt `jfjoch-driver-dkms` package from the +[Gitea package registry](REPOSITORIES.md); on other systems follow the procedure in +[PCIe driver](FPGA_PCIE_DRIVER.md). + +DKMS builds the module for the kernel it is being installed for rather than the running one, so a +module built during a kernel update loads correctly after the reboot. + +NOTE: In case the driver is included in the init RAM-disk image, it is necessary to rebuild the RAM-disk when the driver is updated: +``` +$ sudo dracut -f +``` +### Configure network +Configure switch according to [FPGA network guide](FPGA_NETWORK.md) - specifically set manual speed and turn off auto-negotiation +for the port used to connect U55C card and connect card to switch. + +## Running Jungfraujoch software +Main Jungfraujoch service is called `jfjoch_broker`. It is responsible for handling data from FPGAs, doing processing, analysis, compression and sending images on ZeroMQ output. +It is recommended to run the service as `systemd` service. + +`jfjoch_broker` takes a JSON configuration file and, optionally, the HTTP port (default 5232). +Example JSON files are placed in `etc/` folder. JSON file format is also explained in the OpenAPI definition, as `jfjoch_settings` data structure. + +When running the service can be accessed via HTTP interface from a web browser for configuration and monitoring. + +Jungfraujoch automatically uses every GPU visible to the process and spreads the per-image work across all of them. To run more than one `jfjoch_broker` on a single machine, each confined to a disjoint subset of GPUs, set `CUDA_VISIBLE_DEVICES`; setting `CUDA_DEVICE_ORDER=PCI_BUS_ID` keeps the GPU indices stable across reboots. For example, two brokers on a 4-GPU host: +``` +CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=0,1 jfjoch_broker broker_a.json 5232 +CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=2,3 jfjoch_broker broker_b.json 5233 +``` + +To prepare the configuration file one also needs to reference calibration files: gain files for PSI JUNGFRAU and trim-bit files for PSI EIGER. +These need to be obtained from the PSI Detector Group. + +## Card verification + +To test that the FPGA board is working properly without access to a JUNGFRAU detector, you can use `jfjoch_fpga_test` tool. +For example, to simulate a 10M pixel system with 4 FPGA cards and 200k images: +``` +jfjoch_fpga_test ~/nextgendcu/ -m20 -s4 -i 200000 +``` +Or a 1M pixel system with one FPGA card: +``` +jfjoch_fpga_test ~/nextgendcu/ -m2 -s1 -i 200000 +``` + +## Install Jungfraujoch writer +Jungfraujoch writer is an additional service that connects to the `jfjoch_broker` ZeroMQ interface and writes files according to NeXus/NXmx HDF5 standard. + +At the moment it is better to have a separate machine, with access to a distributed file system, for writing images. + +Writer can be installed with a dedicated RPM file or compiled from source. For compilation, you can use the following commands: +``` +mkdir build +cd build +cmake -DJFJOCH_WRITER_ONLY=ON -DCMAKE_INSTALL_PREFIX= .. +make jfjoch_writer +``` + +## Install Jungfraujoch image viewer +The Jungfraujoch viewer is an X-ray diffraction image viewer optimized to open Jungfraujoch HDF5 files. + +The viewer is a Qt application and it requires a recent version of the library, therefore it is an optional dependency. + +To include it in the building of Jungfraujoch use `-DJFJOCH_VIEWER_BUILD=ON` directive for CMake: +``` +mkdir build +cd build +cmake -DJFJOCH_VIEWER_BUILD=ON -DCMAKE_INSTALL_PREFIX= .. +make jfjoch_viewer +``` + +Pre-built viewers for Windows and macOS, and a portable Linux archive, are on the +[download page](VIEWER_DOWNLOAD.md) — see [Release contents](RELEASE_CONTENTS.md) and +[jfjoch_viewer](JFJOCH_VIEWER.md). + + +## Install Jungfraujoch Python client +Use pip: +```shell +pip install jfjoch-client +``` + +## Install Rugnux (offline analysis) + +`rugnux` is not part of the server stack and is installed independently of all of the above. It +needs neither the broker, the writer, Qt nor a CUDA toolkit — only an NVIDIA driver if you want to +use the GPU — and it does not have to run on the acquisition machine at all. + +From the [package repositories](REPOSITORIES.md): + +``` +sudo dnf install rugnux # RHEL / Rocky +sudo apt install rugnux # Ubuntu +``` + +Or, on a machine no repository covers, from the standalone archive: + +``` +mkdir -p /opt/rugnux- +tar xzf rugnux--linux-x86_64-cuda12.tgz -C /opt/rugnux- +/opt/rugnux-/bin/rugnux +``` + +The archive has no top-level directory, so the `-C` is required. See +[Installing Rugnux](RUGNUX_INSTALL.md) for the Arm, Windows and macOS archives, the driver +versions and building from source. \ No newline at end of file diff --git a/_sources/DETECTORS.md.txt b/_sources/DETECTORS.md.txt new file mode 100644 index 000000000..bed139b03 --- /dev/null +++ b/_sources/DETECTORS.md.txt @@ -0,0 +1,15 @@ +# Supported detectors + +## PSI detectors +Jungfraujoch supports PSI JUNGFRAU and PSI EIGER detectors. Jungfraujoch controls the detector via `slsDetectorPackage`, which is statically compiled into its source code. +The detector firmware must match the `slsDetectorPackage` version used in Jungfraujoch. +The default is 8.0.2; 9.2.0 is built with the `SLS9=ON` CMake option and published in the `slsdet9` +[package repositories](REPOSITORIES.md). +See [PSI Detector group website](https://www.psi.ch/en/lxn/software-releases) for details. + +## DECTRIS detectors + +Jungfraujoch can be used with DECTRIS detectors, as a data analysis tool. +In this solution Jungfraujoch controls the Detector Control Unit (DCU) of the detector, and handles the output data stream of the DCU. +This mode, called "lite" mode, doesn't use FPGA boards, but mostly CPUs and GPUs for indexing. +The mode is currently experimental and intended for low data rates (100 Hz). diff --git a/_sources/DETECTOR_GEOMETRY.md.txt b/_sources/DETECTOR_GEOMETRY.md.txt new file mode 100644 index 000000000..f51440b90 --- /dev/null +++ b/_sources/DETECTOR_GEOMETRY.md.txt @@ -0,0 +1,133 @@ +# Detector geometry + +At the moment Jungfraujoch supports solely flat detectors. The default option is to place modules in their actual location +relative to the detector frame. It is not recommended to place detector modules stacked. + +The simplest case is a detector perpendicular to the beam. In this case it is enough to provide beam center, detector distance +and wavelength. + +For a more complex case, one can provide the detector tilt in the PyFAI convention. +This convention uses Point Of Nominal Interaction (PONI) definition. Beam X and Y would correspond to the location on the detector, +where beam from the sample is perpendicular to the detector surface and not to the actual direct beam location. Then tilt of the detector +is defined with three rotation angles: `rot1` (rotating detector right), `rot2` (rotating detector downwards), `rot3` (rotating detector clockwise). +See [PyFAI documentation](https://pyfai.readthedocs.io/en/stable/) for more details. + +## What a pixel coordinate means: (0, 0) is the centre of the first pixel + +Pixel coordinates in Jungfraujoch and Rugnux are **0-based and pixel-centred**: an integer coordinate +is the *centre* of that pixel, so pixel *i* covers [*i* − 0.5, *i* + 0.5) and the sensor spans +−0.5 … width − 0.5. A beam centre of 948.0 × 546.0 sits in the middle of pixel [546][948], not on any +of its corners; 948.5 is the boundary between pixel 948 and 949. + +This holds throughout the code: spot and reflection centroids are intensity-weighted sums of the +integer pixel indices, the resolution and azimuthal-bin maps evaluate pixel (col, row) at exactly +(col, row), and a fractional coordinate is turned back into a pixel index by rounding, not by +truncation. The same convention applies to every coordinate the system exposes — the beam centre +(`beam_x_pxl`/`beam_y_pxl` in the API and broker configuration, `--beam-x`/`--beam-y` in Rugnux, +`beam_center_x`/`beam_center_y` in NXmx and in the CBOR stream), the spot and predicted-reflection +positions written to HDF5, and the PONI reported by `--mode calibration`. + +Other programs place the origin differently, and the difference is worth half a pixel — enough to +matter when a geometry is copied between programs and then refined: + +| Convention | Beam centre equivalent to our *x* = 948.0 | +|---|---| +| Jungfraujoch, Rugnux | 948.0 | +| XDS (`ORGX`/`ORGY`) | 949.0 — also pixel-centred, but pixels are numbered from 1 | +| Measured from the edge of the sensor, in length units — pyFAI (`Poni2`, fast axis), DIALS/dxtbx | (948.0 + 0.5) × pixel size, because the centre of pixel *i* is at (*i* + 0.5) × pixel size from the edge | +| pyFAI `Poni1` (slow axis) | (height − 1 − *y* + 0.5) × pixel size — pyFAI measures the slow axis from the opposite edge, and the `.poni` declares `orientation: 2` to say so | + +The `.poni` file written by `rugnux --mode calibration` is in pyFAI's frame and so already carries +that half pixel; the pixel values the same run reports are ours. `Rot3` in that file is our rot3 +negated and turned by 180°: the half turn sets the azimuthal reference, because pyFAI's in-plane axes +are the negatives of ours. It leaves 2θ untouched, so it moves only the azimuth. + +## Inside: two axis vectors; outside: rot1/rot2/rot3 + +Internally the detector plane is one orthogonal matrix whose columns are the **fast axis** (the +laboratory direction of a +1 column step), the **slow axis** (+1 row step) and the **normal** (the +sample→PONI direction). Every geometry calculation — resolution, azimuth, polarization, prediction, +refinement — is that matrix applied to the offset of a pixel from the PONI. + +`rot1`/`rot2`/`rot3` remain the way the tilt is stated from outside, and the two views convert both +ways: `R = Rz(-rot3)·Rx(-rot2)·Ry(+rot1)` in the internal frame, and back from the columns as + +``` +rot2 = asin(-slow.z) rot1 = atan2(-fast.z, normal.z) rot3 = atan2(slow.x, slow.y) +``` + +with `rot2` in [-90°, 90°]. The angles are what is stored and what is written out, so a geometry +given as angles comes back exactly as it was given. + +## What a miniCBF header states about the mounting + +A PILATUS miniCBF gives the geometry twice. The `# ` lines every writer produces carry the distance, the +beam centre and the angles; some beamlines then append a CBF template block holding a full **imgCIF axis +table**, which states the laboratory direction of the image's fast and slow pixel directions, of the base +goniometer axis, and of a 2theta arm where there is one. Where that table is present it is read, in +preference to any assumption - it is the same information NXmx puts in `fast_pixel_direction` / +`slow_pixel_direction` and the goniometer `vector`, in the form this format states it. + +imgCIF's laboratory frame has Z from the sample towards the source and Y opposite gravity, so it differs +from the internal frame by a half turn about x - a rotation, not a mirror, so an axis carried through it +turns the same way by the same angle. + +There are two things a header can state that an assumption gets wrong by 90 degrees — an error no +refinement recovers, and one the run's axis-sign rescue cannot reach either, a quarter turn not +being a sign: + +* the image mounted a quarter turn round, so its columns run vertically; +* a spindle that turns about the **vertical** rather than the horizontal. + +Where a header carries no axis table, a `+SLOW` on its `# Oscillation_axis` line still says the spindle +runs along the image's slow direction rather than its fast one. The axis *name* on that line is not +usable - one header says `X.CW +SLOW` where its own table says the axis is Y - but the direction token is, +and on the header that states both they agree. + +## A detector swung out on a 2theta arm + +Chemical crystallography reaches high angle by swinging the detector out on a 2theta arm rather than by +moving it closer. The arm turns the detector about the sample, so it changes nothing else: the distance +is still measured along the detector normal, and the beam centre is still the point of normal incidence, +which is where the arm's own axis meets the detector and does not move. The swing is therefore exactly a +PONI rotation, and the direct beam is what moves - by `distance * tan(2theta)`, off the beam centre and +often off the detector altogether. + +Nothing has to be given for this: Rugnux takes it from the file. An NXmx master states the detector's +position as a `depends_on` chain of transformations, and the arm is one rotation in that chain - so the +chain is followed, rather than a field of one particular name being looked for. A PILATUS miniCBF states +it as `# Detector_2theta`, which turns about the same axis as the base spindle, the two being one axis on +the four-circle geometry those headers describe. + +## Mirrored and quarter-turned detectors + +On top of the continuous tilt the detector setup carries a **discrete image orientation**: whether the +stored image is mirrored in Y, and how many multiples of 90° about the beam it is turned by. It is +applied to the offset from the PONI before the tilt. + +The distinction matters because these two operations are exact pixel remappings — an image can be +shown the right way up without resampling anything — while an arbitrary in-plane rotation cannot. +`rot3` is therefore reserved for the genuinely arbitrary part: an in-plane angle is **never** +decomposed into a quarter turn plus a residual, and the discrete part is set only where something +states it (the detector configuration, `--detector-mirror-y` / `--detector-quarter-turns`, or the +value a Jungfraujoch-written file records). + +Both operations leave the distance from the PONI unchanged, so resolution, the solid-angle correction +and anything else that needs only a radius are unaffected by them. Polarization *is* affected, and +correctly so: it is computed from the azimuth in the **laboratory**, and what these operations change +is which pixel index lands at which laboratory azimuth. + +This is a different setting from `mirror_y` in the JSON configuration file (described below), which flips the +**module layout** while the image is being assembled and so decides what the stored pixels are. The +discrete image orientation changes no pixel at all. + +## Macromolecular crystallography convention for the vertical direction +One place of confusion is the convention to have point (0,0) of the detector in the top left corner of the detector, +with Y values increasing downwards. This is also consistent with computer image formats. + +However, other techniques (as well as internal operation of PSI X-ray detectors) might follow a convention where point (0,0) +is in the bottom left corner and Y values increase upwards. Such a convention is used, for example, by PyFAI. + +In general, the convention is controlled in Jungfraujoch with a setting in the JSON configuration file, which allows the detector to be mirrored in Y. + +The convention in use is worth checking whenever a geometry is carried between programs. \ No newline at end of file diff --git a/_sources/EXTERNAL_TEST_DATA.md.txt b/_sources/EXTERNAL_TEST_DATA.md.txt new file mode 100644 index 000000000..845a73aec --- /dev/null +++ b/_sources/EXTERNAL_TEST_DATA.md.txt @@ -0,0 +1,723 @@ +# External test data + +Jungfraujoch is developed at the Swiss Light Source, but a data-reduction pipeline that only +ever sees its own detectors is not tested. The datasets below were collected by other people, +on detectors and in file formats we do not produce ourselves, and are used here to check that +`rugnux` reads foreign files correctly and reduces them to sensible results. Most were collected +at other facilities, thirteen on laboratory X-ray sources; a few come from SLS beamlines, where the data are still written by someone +else's detector and someone else's acquisition system. Their authors published all of these for +exactly this kind of reuse, and this page is where we credit them. + +**None of these data were collected by us.** If you use any of them, cite the dataset DOI in +the table below; the repositories themselves are cited in +[ACKNOWLEDGEMENT](ACKNOWLEDGEMENT.md). + +This page lists the rotation datasets. The serial (XFEL stills) datasets of the still battery are on +[External test data: serial crystallography](EXTERNAL_TEST_DATA_STILLS.md). + +The pan-facility test of the Rugnux paper is this collection as it stood for the paper's battery +run: 207 datasets, 201 of deposited PDB entries and six chemical-crystallography sets, from 26 +synchrotrons and 10 laboratory sources. Datasets added since are listed here as well, so the counts +on this page run a little higher than the paper's. + +## Where the values come from + +- **Source** is the repository we downloaded from and that repository's own citable DOI for + the archive we took. Every DOI on this page was resolved before it was written down - against + DataCite, which registers most of them; 6NEN's DOI is registered with Crossref and the five XRDa + DOIs with JaLC, and those were resolved through doi.org - and the identity of each dataset was + taken from the repository's record for the archive - not from our directory names. +- **Beamline, resolution, space group, cell and title are the values deposited with the PDB + entry**, read from the RCSB data API; the resolution is the entry's refinement resolution + (`resolution_combined`). They describe the published experiment. They are *not* our + reprocessing results; no quantity measured by Jungfraujoch appears in the table. +- **Detector is read out of the image files themselves** - the NXmx + `/entry/instrument/detector/description`, the miniCBF `# Detector:` header, the marCCD + instrument header or the SMV key block - which is authoritative where the PDB entry names a + different detector. +- Anything that could not be established from one of those sources is left blank. +- **Every row of the table is a row of the battery's open arm** (`tools/battery/open.json`) + unless it is listed under + [Datasets in the table that are not in the battery](#datasets-in-the-table-that-are-not-in-the-battery), + and every row of the open arm is in the table or under + [Datasets with no PDB entry](#datasets-with-no-pdb-entry). The manifest keeps the deposited + values at full precision; `tools/battery/doc_check.py` checks that the two agree. + +## Datasets + +| PDB | Source | Facility / beamline | dmin (Å) | Space group | Unit cell a b c α β γ (Å, °) | Detector (from file) | Title | +|---|---|---|---|---|---|---|---| +| [11IF](https://www.rcsb.org/structure/11IF) | IRRMC [10.18430/M311IF](https://doi.org/10.18430/M311IF) | NSLS-II 19-ID | 1.51 | P 43 | 51.1 51.1 71.9 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of an exported phospholipid binding protein from Bordetella pertussis in complex with Di-palmitoyl-3-sn-phosphatidylethanolamine (DPPE), P43 form 2 | +| [2WNN](https://www.rcsb.org/structure/2WNN) | Zenodo [10.5281/zenodo.54568](https://doi.org/10.5281/zenodo.54568) | Diamond I03 | 1.65 | P 1 21 1 | 54.7 142.5 83.6 90.0 109.2 90.0 | SMV, S/N 920 | Structure of wild type E. coli N-acetylneuraminic acid lyase in complex with pyruvate in space group P21 | +| [2WNQ](https://www.rcsb.org/structure/2WNQ) | Zenodo [10.5281/zenodo.54568](https://doi.org/10.5281/zenodo.54568) | Diamond I04 | 1.80 | P 1 21 1 | 54.6 142.8 84.5 90.0 109.0 90.0 | SMV, S/N 921 | Structure of the E192N mutant of E. coli N-acetylneuraminic acid lyase in space group P21 | +| [2WNZ](https://www.rcsb.org/structure/2WNZ) | Zenodo [10.5281/zenodo.54568](https://doi.org/10.5281/zenodo.54568) | Diamond I02 | 1.85 | P 1 21 1 | 56.9 143.0 83.9 90.0 109.8 90.0 | SMV, S/N 922 | Structure of the E192N mutant of E. coli N-acetylneuraminic acid lyase in complex with pyruvate in space group P21 crystal form I | +| [2XFW](https://www.rcsb.org/structure/2XFW) | Zenodo [10.5281/zenodo.54568](https://doi.org/10.5281/zenodo.54568) | Diamond I02 | 1.65 | P 1 21 1 | 78.1 116.5 83.7 90.0 118.0 90.0 | SMV, S/N 922 | Structure of the E192N mutant of E. coli N-acetylneuraminic acid lyase in complex with pyruvate in crystal form III | +| [36GK](https://www.rcsb.org/structure/36GK) | IRRMC [10.18430/M336GK](https://doi.org/10.18430/M336GK) | CLSI 08ID-1 | 2.28 | I 2 2 2 | 120.6 189.5 199.7 90.0 90.0 90.0 | Dectris Eiger 9M | D-GlcNAc-bound structure of Vibrio vulnificus putative carbohydrate binding module and split domain | +| [3INP](https://www.rcsb.org/structure/3INP) | IRRMC [10.18430/m33inp](https://doi.org/10.18430/m33inp) | APS 21-ID-F | 2.05 | F 41 3 2 | 224.1 224.1 224.1 90.0 90.0 90.0 | marCCD, 225 mm plate | 2.05 Angstrom Resolution Crystal Structure of D-ribulose-phosphate 3-epimerase from Francisella tularensis. | +| [3KY7](https://www.rcsb.org/structure/3KY7) | IRRMC [10.18430/m33ky7](https://doi.org/10.18430/m33ky7) | APS 21-ID-G | 2.35 | P 43 3 2 | 125.2 125.2 125.2 90.0 90.0 90.0 | marCCD, 300 mm plate | 2.35 Angstrom resolution crystal structure of a putative tRNA (guanine-7-)-methyltransferase (trmD) from Staphylococcus aureus subsp. aureus MRSA252 | +| [3MC4](https://www.rcsb.org/structure/3MC4) | IRRMC [10.18430/M33MC4](https://doi.org/10.18430/M33MC4) | Home source, Rigaku MicroMax-007 HF | 1.95 | H 3 | 104.0 104.0 105.5 90.0 90.0 120.0 | Rigaku Saturn 944+ | Crystal structure of WW/RSP5/WWP domain: bacterial transferase hexapeptide repeat: serine O-Acetyltransferase from Brucella Melitensis | +| [3MEB](https://www.rcsb.org/structure/3MEB) | IRRMC [10.18430/M33MEB](https://doi.org/10.18430/M33MEB) | Home source, Rigaku MicroMax-007 HF | 1.90 | P 1 21 1 | 58.6 101.2 81.5 90.0 90.6 90.0 | Rigaku Saturn 944 | Structure of cytoplasmic aspartate aminotransferase from giardia lamblia | +| [3P85](https://www.rcsb.org/structure/3P85) | IRRMC [10.18430/M33P85](https://doi.org/10.18430/M33P85) | Home source, Rigaku FR-E+ SuperBright | 1.90 | P 63 2 2 | 127.3 127.3 72.9 90.0 90.0 120.0 | Rigaku Saturn 944+ | Crystal structure enoyl-coa hydratase from mycobacterium avium | +| [3R6O](https://www.rcsb.org/structure/3R6O) | IRRMC [10.18430/M33R6O](https://doi.org/10.18430/M33R6O) | Home source, Rigaku FR-E+ SuperBright | 1.95 | I 41 | 90.7 90.7 76.1 90.0 90.0 90.0 | Rigaku Saturn 944+ | Crystal structure of a probable 2-hydroxyhepta-2,4-diene-1, 7-dioateisomerase from Mycobacterium abscessus | +| [4BWL](https://www.rcsb.org/structure/4BWL) | Zenodo [10.5281/zenodo.54568](https://doi.org/10.5281/zenodo.54568) | Diamond I02 | 2.00 | P 1 21 1 | 56.0 143.2 83.4 90.0 109.5 90.0 | SMV, S/N 922 | Structure of the Y137A mutant of E. coli N-acetylneuraminic acid lyase in complex with pyruvate, N-acetyl-D-mannosamine and N- acetylneuraminic acid | +| [4MTK](https://www.rcsb.org/structure/4MTK) | SBGrid [10.15785/sbgrid/235](https://doi.org/10.15785/sbgrid/235) | SLS X06SA | 3.32 | P 61 | 168.3 168.3 652.8 90.0 90.0 120.0 | PILATUS 6M | Crystal structure of PA0091 VgrG1, the central spike of the Type VI Secretion System | +| [4NWV](https://www.rcsb.org/structure/4NWV) | SBGrid [10.15785/sbgrid/9](https://doi.org/10.15785/sbgrid/9) | APS 21-ID-D | 3.25 | I 2 2 2 | 402.2 369.9 410.5 90.0 90.0 90.0 | Rayonix MX-300 | Crystal structure of Orsay virus-like particle | +| [4P8R](https://www.rcsb.org/structure/4P8R) | IRRMC [10.18430/m34p8r](https://doi.org/10.18430/m34p8r) | APS 21-ID-F | 2.20 | P 65 2 2 | 86.7 86.7 701.4 90.0 90.0 120.0 | Rayonix MX-225 | Structure of a glycosomal glyceraldehyde 3-phosphate dehydrogenase from Trypanosoma brucei | +| [5CC8](https://www.rcsb.org/structure/5CC8) | IRRMC [10.18430/M35CC8](https://doi.org/10.18430/M35CC8) | Home source, Rigaku MicroMax-007 HF | 1.75 | P 21 21 2 | 87.1 93.8 72.5 90.0 90.0 90.0 | Rigaku Saturn 944+ | Structure of thiamine-monophosphate kinase from Acinetobacter baumannii in complex with AMPPNP | +| [5EBI](https://www.rcsb.org/structure/5EBI) | MXRDR [10.18150/9887707](https://doi.org/10.18150/9887707) | BESSY 14.2 | 1.09 | P 1 21 1 | 35.7 44.1 35.7 90.0 120.0 90.0 | marCCD, 225 mm plate | Crystal structure of a DNA-RNA chimera in complex with Ba2+ ions: a case of unusual multi-domain twinning | +| [5EPE](https://www.rcsb.org/structure/5EPE) | IRRMC [10.18430/m3159c](https://doi.org/10.18430/m3159c) | APS 21-ID-G | 1.90 | F 2 3 | 157.5 157.5 157.5 90.0 90.0 90.0 | Rayonix MX-300 | Crystal structure of SAM-dependent methyltransferase from Thiobacillus denitrificans in complex with S-Adenosyl-L-homocysteine | +| [5F6M](https://www.rcsb.org/structure/5F6M) | SBGrid [10.15785/sbgrid/201](https://doi.org/10.15785/sbgrid/201) | SSRL BL11-1 | 1.10 | P 21 21 21 | 54.8 58.5 67.4 90.0 90.0 90.0 | PILATUS 6M | Isotropic Trypsin Model for Comparison of Diffuse Scattering | +| [5J23](https://www.rcsb.org/structure/5J23) | IRRMC [10.18430/M35J23](https://doi.org/10.18430/M35J23) | APS 21-ID-G | 2.30 | H 3 | 175.8 175.8 136.8 90.0 90.0 120.0 | Rayonix MX-300 | Crystal structure of NADPH-dependent glyoxylate/hydroxypyruvate reductase SMc04462 (SmGhrB) from Sinorhizobium meliloti in complex with 2'-phospho-ADP-ribose | +| [5JK4](https://www.rcsb.org/structure/5JK4) | Zenodo [10.5281/zenodo.49859](https://doi.org/10.5281/zenodo.49859) | ESRF ID14-2 | 1.10 | P 1 21 1 | 37.7 77.9 56.3 90.0 102.1 90.0 | ADSC Quantum 4 | Phosphate-Binding Protein from Stenotrophomonas maltophilia. | +| [5JVN](https://www.rcsb.org/structure/5JVN) | IRRMC [10.18430/m35jvn](https://doi.org/10.18430/m35jvn) | ESRF ID29 | 2.90 | P 6 2 2 | 249.4 249.4 84.1 90.0 90.0 120.0 | PILATUS3 6M | C3-type pyruvate phosphate dikinase: intermediate state of the central domain in the swiveling mechanism | +| [5KY6](https://www.rcsb.org/structure/5KY6) | MXRDR [10.18150/repod.1494374](https://doi.org/10.18150/repod.1494374) | BESSY 14.2 | 1.94 | P 1 21 1 | 84.5 57.3 164.0 90.0 102.6 90.0 | marCCD, 225 mm plate | Human muscle fructose-1,6-bisphosphate aldolase | +| [5LZL](https://www.rcsb.org/structure/5LZL) | Zenodo [10.5281/zenodo.54757](https://doi.org/10.5281/zenodo.54757) | Diamond I02 | 3.47 | P 31 2 1 | 205.6 205.6 199.2 90.0 90.0 120.0 | PILATUS 6M-F | Pyrobaculum calidifontis 5-aminolaevulinic acid dehydratase | +| [5M17](https://www.rcsb.org/structure/5M17) | Zenodo [10.5281/zenodo.4300323](https://doi.org/10.5281/zenodo.4300323) | Diamond I02 | 1.03 | I 4 | 108.6 108.6 67.7 90.0 90.0 90.0 | PILATUS 6M-F | Structure of the GH99 endo-alpha-mannanase from Bacteroides xylanisolvens in complex with mannose-alpha-1,3-1,2-dideoxymannose | +| [5MLN](https://www.rcsb.org/structure/5MLN) | IRRMC [10.18430/m35mln](https://doi.org/10.18430/m35mln) | ESRF ID23-2 | 1.60 | P 21 2 21 | 74.2 80.4 80.5 90.0 90.0 90.0 | PILATUS3 2M | The crystal structure of alcohol dehydrogenase 10 from Candida magnoliae | +| [5NW5](https://www.rcsb.org/structure/5NW5) | SBGrid [10.15785/sbgrid/446](https://doi.org/10.15785/sbgrid/446) | SLS X06DA | 6.50 | P 21 21 21 | 92.1 169.8 390.2 90.0 90.0 90.0 | PILATUS 2MF | Crystal structure of the Rif1 N-terminal domain (RIF1-NTD) from Saccharomyces cerevisiae in complex with DNA | +| [5OJV](https://www.rcsb.org/structure/5OJV) | SBGrid [10.15785/sbgrid/475](https://doi.org/10.15785/sbgrid/475) | ESRF ID30B | 2.06 | P 21 21 2 | 87.8 158.2 87.6 90.0 90.0 90.0 | PILATUS 6M | Crystal structure of Mycolicibacterium hassiacum glucosylglycerate hydrolase (MhGgH) E419A variant in complex with mannosylglycerate | +| [5REO](https://www.rcsb.org/structure/5REO) | Zenodo [10.5281/zenodo.3730956](https://doi.org/10.5281/zenodo.3730956) | Diamond I04-1 | 1.88 | C 1 2 1 | 112.4 52.6 44.4 90.0 103.0 90.0 | PILATUS 6M-F | PanDDA analysis group deposition -- Crystal Structure of SARS-CoV-2 main protease in complex with PCM-0102578 | +| [5SRC](https://www.rcsb.org/structure/5SRC) | IRRMC [10.18430/M35SRC](https://doi.org/10.18430/M35SRC) | ALS 8.3.1 | 1.05 | P 43 | 88.7 88.7 39.2 90.0 90.0 90.0 | PILATUS3 6M | PanDDA analysis group deposition -- Crystal structure of SARS-CoV-2 NSP3 macrodomain in complex with Z5198562500 - (R,R) and (R,S) isomers | +| [5T39](https://www.rcsb.org/structure/5T39) | SBGrid [10.15785/sbgrid/356](https://doi.org/10.15785/sbgrid/356) | APS 21-ID-F | 1.10 | P 1 21 1 | 50.2 41.3 58.5 90.0 98.6 90.0 | Rayonix MX-300 | Crystal Structure of the N-terminal domain of EvdMO1 in the presence of SAH and D-fucose | +| [5UTH](https://www.rcsb.org/structure/5UTH) | IRRMC [10.18430/M35UTH](https://doi.org/10.18430/M35UTH) | Home source, Rigaku FR-E+ SuperBright | 1.95 | P 31 2 1 | 69.3 69.3 153.8 90.0 90.0 120.0 | Rigaku Saturn 944+ | Crystal structure of thioredoxin reductase from Mycobacterium smegmatis in complex with FAD | +| [5VML](https://www.rcsb.org/structure/5VML) | IRRMC [10.18430/M35VML](https://doi.org/10.18430/M35VML) | Home source, Rigaku FR-E+ SuperBright | 1.70 | P 42 21 2 | 66.3 66.3 115.3 90.0 90.0 90.0 | Rigaku Saturn 944+ | Crystal Structure of Acetoacetyl-CoA Reductase from Burkholderia Pseudomallei 1710b with bound NADP | +| [6CDL](https://www.rcsb.org/structure/6CDL) | IRRMC [10.18430/m36cdl](https://doi.org/10.18430/m36cdl) | APS 22-ID | 1.25 | P 21 21 2 | 58.3 85.9 46.1 90.0 90.0 90.0 | marCCD, 300 mm plate | HIV-1 wild type protease with GRL-03214A, 6-5-5-ring fused umbrella-like tetrahydropyranofuran as the P2-ligand, a cyclopropylaminobenzothiazole as the P2'-ligand and 3,5-difluorophenylmethyl as the P1-ligand | +| [6CEE](https://www.rcsb.org/structure/6CEE) | IRRMC [10.18430/M36CEE](https://doi.org/10.18430/M36CEE) | Home source, Rigaku FR-E SuperBright | 1.55 | P 21 21 21 | 40.7 44.1 55.9 90.0 90.0 90.0 | Rigaku Saturn A200 | Crystal structure of fragment 3-(1-Methyl-2-oxo-1,2-dihydroquinoxalin-3-yl)propionic acid bound in the ubiquitin binding pocket of the HDAC6 zinc-finger domain | +| [6CS9](https://www.rcsb.org/structure/6CS9) | SBGrid [10.15785/SBGRID/568](https://doi.org/10.15785/SBGRID/568) | Australian Synchrotron MX2 | 1.85 | P 1 21 1 | 32.9 25.5 40.2 90.0 98.6 90.0 | ADSC Quantum 210r | Crystal structure of human beta-defensin 2 in complex with PIP2 | +| [6F3P](https://www.rcsb.org/structure/6F3P) | IRRMC [10.18430/M36F3P](https://doi.org/10.18430/M36F3P) | APS 22-ID | 1.35 | C 1 2 1 | 142.9 85.7 112.0 90.0 122.2 90.0 | marCCD, 300 mm plate | Crystal structure of S-adenosyl-L-homocysteine hydrolase from Pseudomonas aeruginosa in complex with 3'-deoxyadenosine and K+ cation | +| [6FID](https://www.rcsb.org/structure/6FID) | SBGrid [10.15785/sbgrid/541](https://doi.org/10.15785/sbgrid/541) | ESRF ID30B | 2.20 | P 21 21 21 | 59.9 64.1 69.7 90.0 90.0 90.0 | PILATUS3 6M | Bovine trypsin solved by S-SAD on ID30B | +| [6FVZ](https://www.rcsb.org/structure/6FVZ) | IRRMC [10.18430/m36fvz](https://doi.org/10.18430/m36fvz) | ESRF ID23-2 | 1.80 | C 2 2 2 | 131.2 222.8 86.5 90.0 90.0 90.0 | PILATUS3 X 2M | Crystal structure of human monoamine oxidase B (MAO B) in complex with dimethylphenyl-chromone-carboxamide | +| [6FWC](https://www.rcsb.org/structure/6FWC) | IRRMC [10.18430/m36fwc](https://doi.org/10.18430/m36fwc) | ESRF MASSIF-3 | 1.70 | C 2 2 2 | 131.7 222.1 86.3 90.0 90.0 90.0 | PILATUS 2MF | Crystal structure of human monoamine oxidase B (MAO B) in complex with fluorophenyl-chromone-carboxamide | +| [6G1F](https://www.rcsb.org/structure/6G1F) | Zenodo [10.5281/zenodo.1059413](https://doi.org/10.5281/zenodo.1059413) | Diamond I03 | 2.25 | C 1 2 1 | 329.3 83.9 133.4 90.0 111.6 90.0 | PILATUS3 6M | Crystal structure of D-phenylglycine aninotransferase (D-PhgAT) from Pseudomonas stutzeri with PLP internal aldimine | +| [6GVK](https://www.rcsb.org/structure/6GVK) | Zenodo [10.5281/zenodo.1286854](https://doi.org/10.5281/zenodo.1286854) | ALBA XALOC | 1.55 | C 1 2 1 | 105.6 59.5 42.4 90.0 113.5 90.0 | PILATUS 6M | Second pair of Fibronectin type III domains of integrin beta4 (T1663R mutant) bound to the bullous pemphigoid antigen BP230 (BPAG1e) | +| [6H2P](https://www.rcsb.org/structure/6H2P) | IRRMC [10.18430/m36h2p](https://doi.org/10.18430/m36h2p) | BESSY 14.1 | 1.48 | C 2 2 21 | 103.5 107.1 216.5 90.0 90.0 90.0 | PILATUS 6M | Crystal Structure of Arg184Gln mutant of Human Prolidase with Mn ions and Cacodylate ligand | +| [6H5T](https://www.rcsb.org/structure/6H5T) | IRRMC [10.18430/m36h5t](https://doi.org/10.18430/m36h5t) | BESSY 14.3 | 1.69 | I 4 2 2 | 86.8 86.8 141.8 90.0 90.0 90.0 | marCCD, 225 mm plate | Intersectin SH3A short isoform | +| [6HV2](https://www.rcsb.org/structure/6HV2) | IRRMC [10.18430/m36hv2](https://doi.org/10.18430/m36hv2) | SLS X06SA | 1.71 | P 61 2 2 | 68.9 68.9 133.6 90.0 90.0 120.0 | Dectris Eiger 16M | MMP-13 in complex with the peptide IMISF | +| [6HWJ](https://www.rcsb.org/structure/6HWJ) | SBGrid [10.15785/sbgrid/614](https://doi.org/10.15785/sbgrid/614) | ALBA XALOC | 1.98 | P 1 21 1 | 59.8 96.1 80.3 90.0 106.7 90.0 | PILATUS 6M | Glucosamine kinase (crystal form A) | +| [6I3J](https://www.rcsb.org/structure/6I3J) | IRRMC [10.18430/m36i3j](https://doi.org/10.18430/m36i3j) | BESSY 14.1 | 2.59 | F 2 2 2 | 134.4 203.8 226.7 90.0 90.0 90.0 | marCCD, 225 mm plate | Bilirubin oxidase from Myrothecium verrucaria in complex with ferricyanide | +| [6IU5](https://www.rcsb.org/structure/6IU5) | Zenodo [10.5281/zenodo.2532134](https://doi.org/10.5281/zenodo.2532134) | SPring-8 BL41XU | 2.25 | P 31 | 84.9 84.9 98.2 90.0 90.0 120.0 | PILATUS3 6M | Crystal structure of cytoplasmic metal binding domain with zinc ions | +| [6IU6](https://www.rcsb.org/structure/6IU6) | Zenodo [10.5281/zenodo.2532134](https://doi.org/10.5281/zenodo.2532134) | SPring-8 BL41XU | 2.90 | P 31 | 84.7 84.7 97.4 90.0 90.0 120.0 | PILATUS3 6M | Crystal structure of cytoplasmic metal binding domain with nickel ions | +| [6IU8](https://www.rcsb.org/structure/6IU8) | Zenodo [10.5281/zenodo.2532134](https://doi.org/10.5281/zenodo.2532134) | SPring-8 BL41XU | 2.70 | P 31 | 85.5 85.5 98.4 90.0 90.0 120.0 | PILATUS3 6M | Crystal structure of cytoplasmic metal binding domain with cobalt ions | +| [6IU9](https://www.rcsb.org/structure/6IU9) | Zenodo [10.5281/zenodo.2532134](https://doi.org/10.5281/zenodo.2532134) | SPring-8 BL41XU | 3.00 | P 31 | 85.3 85.3 97.6 90.0 90.0 120.0 | PILATUS3 6M | Crystal structure of cytoplasmic metal binding domain with iron ions | +| [6JGH](https://www.rcsb.org/structure/6JGH) | IRRMC [10.18430/m36jgh](https://doi.org/10.18430/m36jgh) | SPring-8 BL44XU | 0.94 | P 21 21 21 | 50.6 62.5 68.2 90.0 90.0 90.0 | marCCD, 300 mm plate | Crystal structure of the F99S/M153T/V163A/T203I variant of GFP at 0.94 A | +| [6JGI](https://www.rcsb.org/structure/6JGI) | IRRMC [10.18430/m36jgi](https://doi.org/10.18430/m36jgi) | SPring-8 BL44XU | 0.85 | P 21 21 21 | 50.9 62.4 69.2 90.0 90.0 90.0 | marCCD, 300 mm plate | Crystal structure of the S65T/F99S/M153T/V163A variant of GFP at 0.85 A | +| [6JGJ](https://www.rcsb.org/structure/6JGJ) | IRRMC [10.18430/m36jgj](https://doi.org/10.18430/m36jgj) | SPring-8 BL41XU | 0.78 | P 21 21 21 | 50.9 62.3 68.8 90.0 90.0 90.0 | PILATUS3 300K | Crystal structure of the F99S/M153T/V163A/E222Q variant of GFP at 0.78 A | +| [6MOJ](https://www.rcsb.org/structure/6MOJ) | SBGrid [10.15785/sbgrid/620](https://doi.org/10.15785/sbgrid/620) | ALS 5.0.1 | 2.43 | I 41 2 2 | 130.4 130.4 293.5 90.0 90.0 90.0 | PILATUS3 6M | Dimeric DARPin A_angle_R5 complex with EpoR | +| [6NEN](https://www.rcsb.org/structure/6NEN) | UQ eSpace [10.14264/uql.2018.843](https://doi.org/10.14264/uql.2018.843) | Australian Synchrotron MX2 | 2.15 | P 3 1 2 | 105.5 105.5 35.1 90.0 90.0 120.0 | SMV, S/N 928 | Catalytic domain of Proteus mirabilis ScsC | +| [6O2H](https://www.rcsb.org/structure/6O2H) | SBGrid [10.15785/sbgrid/747](https://doi.org/10.15785/sbgrid/747) | CHESS F1 | 1.21 | P 1 | 27.4 32.1 34.5 88.7 108.5 111.9 | PILATUS3 6M | Hen lysozyme in triclinic space group at ambient temperature - diffuse scattering dataset | +| [6OEL](https://www.rcsb.org/structure/6OEL) | SBGrid [10.15785/sbgrid/652](https://doi.org/10.15785/sbgrid/652) | ALS 8.2.1 | 3.10 | F 41 3 2 | 328.1 328.1 328.1 90.0 90.0 90.0 | SMV, S/N 905 | Engineered Fab bound to IL-4 receptor | +| [6OQZ](https://www.rcsb.org/structure/6OQZ) | IRRMC [10.18430/m3.irrmc.5324](https://doi.org/10.18430/m3.irrmc.5324) | Home source, Bruker rotating anode | 1.60 | I 2 2 2 | 92.9 97.9 102.7 90.0 90.0 90.0 | Bruker SMART 6000 | Crystal structure of glucose isomerase from non-merohedrally twinned crystals | +| [6OR0](https://www.rcsb.org/structure/6OR0) | IRRMC [10.18430/m3.irrmc.5325](https://doi.org/10.18430/m3.irrmc.5325) | Home source, Bruker rotating anode | 1.55 | I 21 3 | 78.0 78.0 78.0 90.0 90.0 90.0 | Bruker SMART 6000 | Crystal structure of insulin from non-merohedrally twinned crystals | +| [6OWW](https://www.rcsb.org/structure/6OWW) | Zenodo [10.5281/zenodo.2943248](https://doi.org/10.5281/zenodo.2943248) | ALS 8.3.1 | 3.84 | P 1 21 1 | 85.8 86.0 214.3 90.0 89.9 90.0 | PILATUS3 6M | Crystal structure of a Human Cardiac Calsequestrin Filament Complexed with Ytterbium | +| [6P8J](https://www.rcsb.org/structure/6P8J) | SBGrid [10.15785/sbgrid/671](https://doi.org/10.15785/sbgrid/671) | APS 24-ID-E | 1.47 | P 1 21 1 | 46.5 152.2 88.3 90.0 90.1 90.0 | Dectris Eiger 16M | Structure of P. aeruginosa ATCC27853 CdnD D62N/D64N mutant bound to ATP | +| [6P8P](https://www.rcsb.org/structure/6P8P) | SBGrid [10.15785/sbgrid/673](https://doi.org/10.15785/sbgrid/673) | APS 24-ID-C | 1.64 | P 4 | 97.5 97.5 60.1 90.0 90.0 90.0 | PILATUS 6M-F | Structure of P. aeruginosa ATCC27853 HORMA1 | +| [6PB3](https://www.rcsb.org/structure/6PB3) | SBGrid [10.15785/sbgrid/681](https://doi.org/10.15785/sbgrid/681) | APS 24-ID-E | 2.05 | P 6 | 100.4 100.4 48.9 90.0 90.0 120.0 | Dectris Eiger 16M | Structure of Rhizobiales Trip13 | +| [6PXB](https://www.rcsb.org/structure/6PXB) | SBGrid [10.15785/sbgrid/698](https://doi.org/10.15785/sbgrid/698) | APS 24-ID-E | 1.75 | P 32 | 64.0 64.0 119.4 90.0 90.0 120.0 | PILATUS 6M-F | N-Terminal SH2 domain of the p120RasGAP | +| [6PXC](https://www.rcsb.org/structure/6PXC) | SBGrid [10.15785/sbgrid/699](https://doi.org/10.15785/sbgrid/699) | APS 24-ID-E | 1.60 | I 2 2 2 | 44.2 64.8 87.2 90.0 90.0 90.0 | PILATUS 6M-F | N-Terminal SH2 domain of the p120RasGAP bound to a p190RhoGAP phosphotyrosine peptide | +| [6QAJ](https://www.rcsb.org/structure/6QAJ) | SBGrid [10.15785/sbgrid/637](https://doi.org/10.15785/sbgrid/637) | Diamond I03 | 2.90 | C 2 2 21 | 59.8 169.3 374.5 90.0 90.0 90.0 | PILATUS3 6M | Structure of the tripartite motif of KAP1/TRIM28 | +| [6R72](https://www.rcsb.org/structure/6R72) | Zenodo [10.5281/zenodo.14894181](https://doi.org/10.5281/zenodo.14894181) | SOLEIL PROXIMA 2 | 3.95 | P 1 21 1 | 117.8 110.8 155.6 90.0 93.2 90.0 | Dectris Eiger 9M | Crystal structure of BmrA-E504A in an outward-facing conformation | +| [6RLR](https://www.rcsb.org/structure/6RLR) | Zenodo [10.5281/zenodo.5886687](https://doi.org/10.5281/zenodo.5886687) | Diamond I04 | 2.00 | P 1 | 40.0 40.0 63.6 80.4 76.3 68.2 | Eiger 16M | Crystal structure of CD9 large extracellular loop | +| [6RYM](https://www.rcsb.org/structure/6RYM) | Keele University [10.21252/xbsq-d621](https://doi.org/10.21252/xbsq-d621) | SRS PX10.1 (Daresbury) | 1.46 | P 43 | 50.2 50.2 51.9 90.0 90.0 90.0 | marCCD 165 mm | Structure of carbohydrate recognition domain with GlcNAc bound | +| [6S1U](https://www.rcsb.org/structure/6S1U) | MXRDR [10.18150/repod.0005795](https://doi.org/10.18150/repod.0005795) | BESSY 14.2 | 1.90 | P 1 21 1 | 51.6 29.4 85.5 90.0 103.8 90.0 | marCCD, 225 mm plate | Crystal structure of dimeric M-PMV protease C7A/D26N/C106A mutant in complex with inhibitor | +| [6TOC](https://www.rcsb.org/structure/6TOC) | Zenodo [10.5281/zenodo.3571040](https://doi.org/10.5281/zenodo.3571040) | SLS X06DA | 1.85 | P 42 | 31.5 31.5 81.6 90.0 90.0 90.0 | PILATUS 2MF | Crystal structure of the oligomerisation domain of the transcription factor PHOSPHATE STARVATION RESPONSE 1 from Arabidopsis (crystal form 3). | +| [6TTN](https://www.rcsb.org/structure/6TTN) | IRRMC [10.18430/m36ttn](https://doi.org/10.18430/m36ttn) | BESSY 14.1 | 1.12 | P 21 21 21 | 39.9 79.8 104.7 90.0 90.0 90.0 | PILATUS 6M | N-terminally truncated hyoscyamine 6-hydroxylase (tH6H) in complex with N-oxalylglycine and hyoscyamine | +| [6U7G](https://www.rcsb.org/structure/6U7G) | IRRMC [10.18430/m36u7g](https://doi.org/10.18430/m36u7g) | APS 23-ID-B | 2.35 | P 1 21 1 | 99.6 98.7 147.5 90.0 104.6 90.0 | Dectris Eiger 16M | HCoV-229E RBD Class V in complex with human APN | +| [6UKF](https://www.rcsb.org/structure/6UKF) | IRRMC [10.18430/m36ukf](https://doi.org/10.18430/m36ukf) | APS 22-ID | 1.00 | P 1 21 1 | 61.0 37.3 69.0 90.0 109.8 90.0 | Dectris Eiger 16M | HhaI endonuclease in Complex with DNA at 1 Angstrom Resolution | +| [6V2R](https://www.rcsb.org/structure/6V2R) | IRRMC [10.18430/m36v2r](https://doi.org/10.18430/m36v2r) | Home source, Rigaku FR-E | 1.60 | P 41 21 2 | 40.2 40.2 83.1 90.0 90.0 90.0 | Rigaku Saturn A200 | Crystal Structure of chromodomain of CBX7 mutant V13A in complex with inhibitor UNC3866 | +| [6VWW](https://www.rcsb.org/structure/6VWW) | IRRMC [10.18430/m36vww](https://doi.org/10.18430/m36vww) | APS 19-ID | 2.20 | P 63 | 150.5 150.5 111.3 90.0 90.0 120.0 | PILATUS3 6M | Crystal Structure of NSP15 Endoribonuclease from SARS CoV-2. | +| [6W4H](https://www.rcsb.org/structure/6W4H) | IRRMC [10.18430/m36w4h](https://doi.org/10.18430/m36w4h) | APS 21-ID-F | 1.80 | P 31 2 1 | 167.7 167.7 51.9 90.0 90.0 120.0 | Rayonix MX-300 | 1.80 Angstrom Resolution Crystal Structure of NSP16 - NSP10 Complex from SARS-CoV-2 | +| [6W75](https://www.rcsb.org/structure/6W75) | IRRMC [10.18430/m36w75](https://doi.org/10.18430/m36w75) | APS 21-ID-F | 1.95 | P 32 2 1 | 166.2 166.2 98.3 90.0 90.0 120.0 | Rayonix MX-300 | 1.95 Angstrom Resolution Crystal Structure of NSP10 - NSP16 Complex from SARS-CoV-2 | +| [6WZO](https://www.rcsb.org/structure/6WZO) | SBGrid [10.15785/sbgrid/785](https://doi.org/10.15785/sbgrid/785) | APS 24-ID-E | 1.42 | P 1 | 43.7 50.1 69.3 106.5 90.1 97.1 | Dectris Eiger 16M | Structure of SARS-CoV-2 Nucleocapsid dimerization domain, P1 form | +| [6YQF](https://www.rcsb.org/structure/6YQF) | IRRMC [10.18430/m36yqf](https://doi.org/10.18430/m36yqf) | Diamond I24 | 3.33 | P 21 21 2 | 42.7 59.7 156.5 90.0 90.0 90.0 | PILATUS3 6M | Crystal structure of the SYCE2-TEX12 delta-Ctip complex in a 4:4 assembly | +| [6Z8O](https://www.rcsb.org/structure/6Z8O) | Zenodo [10.5281/zenodo.3873216](https://doi.org/10.5281/zenodo.3873216) | ESRF ID30B | 2.20 | P 1 21 1 | 63.7 97.0 121.3 90.0 104.7 90.0 | Dectris Eiger 4M | Structure of [NiFeSe] hydrogenase G491A variant from Desulfovibrio vulgaris Hildenborough pressurized with Krypton gas - structure G491A-Kr | +| [6Z9G](https://www.rcsb.org/structure/6Z9G) | Zenodo [10.5281/zenodo.3874714](https://doi.org/10.5281/zenodo.3874714) | ESRF ID30B | 1.76 | P 1 21 1 | 120.3 93.8 127.0 90.0 105.2 90.0 | Dectris Eiger 4M | Structure of [NiFeSe] hydrogenase G491A variant from Desulfovibrio vulgaris Hildenborough pressurized with Oxygen gas - structure G491A-O2 | +| [6ZE4](https://www.rcsb.org/structure/6ZE4) | SBGrid [10.15785/sbgrid/806](https://doi.org/10.15785/sbgrid/806) | BESSY 14.1 | 1.60 | P 21 21 21 | 93.6 109.9 116.1 90.0 90.0 90.0 | PILATUS 6M | FAD-dependent oxidoreductase from Chaetomium thermophilum in complex with fragment 4-oxo-N-[(1S)-1-(pyridin-3-yl)ethyl]-4-(thiophen-2-yl)butanamide | +| [6ZQR](https://www.rcsb.org/structure/6ZQR) | Keele University [10.21252/r2nx-0425](https://doi.org/10.21252/r2nx-0425) | Diamond I02 | 1.93 | P 4 | 113.6 113.6 44.1 90.0 90.0 90.0 | SMV, S/N 922 | Crystal structure of tetrameric fibrinogen-like recognition domain of FIBCD1 with GlcNAc ligand bound | +| [6ZQY](https://www.rcsb.org/structure/6ZQY) | Keele University [10.21252/hx7e-rd04](https://doi.org/10.21252/hx7e-rd04) | Diamond I04 | 1.85 | P 4 | 119.3 119.3 44.2 90.0 90.0 90.0 | SMV, S/N 921 | Crystal structure of tetrameric fibrinogen-like recognition domain of FIBCD1 with Neu5Ac ligand bound | +| [6ZR0](https://www.rcsb.org/structure/6ZR0) | Keele University [10.21252/zcfy-cw20](https://doi.org/10.21252/zcfy-cw20) | Diamond I04 | 1.94 | P 4 | 119.2 119.2 44.2 90.0 90.0 90.0 | PILATUS 6M Prosport+ | Crystal structure of tetrameric fibrinogen-like recognition domain of FIBCD1 with N-acetylalanine ligand bound | +| [7ARR](https://www.rcsb.org/structure/7ARR) | MXRDR [10.18150/EM87YL](https://doi.org/10.18150/EM87YL) | PETRA III, EMBL c/o DESY P13 (MX1) | 1.10 | P 1 | 30.9 32.1 43.1 114.2 91.9 109.9 | PILATUS 6M-F | The de novo designed hybrid alpha/beta-miniprotein | +| [7ATG](https://www.rcsb.org/structure/7ATG) | IRRMC [10.18430/m37atg](https://doi.org/10.18430/m37atg) | PETRA III, EMBL c/o DESY P13 (MX1) | 0.60 | P 21 21 21 | 18.0 31.0 43.9 90.0 90.0 90.0 | PILATUS 6M-F | Crystal structure of Z-DNA in complex with putrescinium and potassium cations at ultrahigh-resolution | +| [7BGT](https://www.rcsb.org/structure/7BGT) | MXRDR [10.18150/1HQGWO](https://doi.org/10.18150/1HQGWO) | BESSY 14.2 | 1.93 | P 1 | 29.3 67.6 69.7 76.8 83.9 83.6 | marCCD, 225 mm plate | Mason-Pfizer Monkey Virus Protease mutant C7A/D26N/C106A in complex with peptidomimetic inhibitor | +| [7BGU](https://www.rcsb.org/structure/7BGU) | MXRDR [10.18150/C9DYSH](https://doi.org/10.18150/C9DYSH) | EMBL/DESY Hamburg (DORIS) X13 | 2.43 | P 1 | 29.1 67.9 69.7 77.1 83.3 83.2 | marCCD 165 mm | Mason-Pfizer Monkey Virus Protease mutant C7A/D26N/C106A in complex with peptidomimetic inhibitor | +| [7D1M](https://www.rcsb.org/structure/7D1M) | IRRMC [10.18430/m37brr](https://doi.org/10.18430/m37brr) | SSRF BL17U1 | 1.35 | P 1 21 1 | 55.5 99.0 59.6 90.0 108.5 90.0 | Dectris Eiger 16M | CRYSTAL STRUCTURE OF THE SARS-CoV-2 MAIN PROTEASE COMPLEXED WITH GC376 | +| [7D98](https://www.rcsb.org/structure/7D98) | XRDa [10.51093/xrd-00013](https://doi.org/10.51093/xrd-00013) | Photon Factory BL-1A | 3.60 | P 61 2 2 | 105.8 105.8 602.5 90.0 90.0 120.0 | Dectris Eiger 4M | Crystal structure of full-length CbnR complexed with the target DNA complex | +| [7DKP](https://www.rcsb.org/structure/7DKP) | IRRMC [10.18430/M37DKP](https://doi.org/10.18430/M37DKP) | ESRF MASSIF-3 | 1.45 | P 1 21 1 | 49.8 169.5 49.8 90.0 93.5 90.0 | Dectris Eiger 4M | Crystal structure of E. coli Grx2 in complex with GSH at 1.45 A resolution | +| [7K1L](https://www.rcsb.org/structure/7K1L) | IRRMC [10.18430/m37k1l](https://doi.org/10.18430/m37k1l) | APS 19-ID | 2.25 | P 63 | 150.8 150.8 110.7 90.0 90.0 120.0 | PILATUS3 6M | Crystal Structure of NSP15 Endoribonuclease from SARS CoV-2 in the Complex with Uridine-2',3'-Vanadate | +| [7KCN](https://www.rcsb.org/structure/7KCN) | IRRMC [10.18430/m37kcn](https://doi.org/10.18430/m37kcn) | LNLS W01B-MX2 | 1.46 | P 41 2 2 | 67.0 67.0 116.9 90.0 90.0 90.0 | PILATUS 2M | Reconstructed ancestor of HIUases and Transthyretins | +| [7L6J](https://www.rcsb.org/structure/7L6J) | IRRMC [10.18430/m37l6j](https://doi.org/10.18430/m37l6j) | APS 21-ID-F | 1.78 | I 41 3 2 | 171.7 171.7 171.7 90.0 90.0 90.0 | Rayonix MX-300 | Crystal Structure of the Putative Hydrolase from Stenotrophomonas maltophilia | +| [7L84](https://www.rcsb.org/structure/7L84) | SBGrid [10.15785/sbgrid/816](https://doi.org/10.15785/sbgrid/816) | APS 24-ID-C | 1.70 | P 43 21 2 | 79.3 79.3 37.8 90.0 90.0 90.0 | PILATUS 6M-F | Hen Egg White Lysozyme by Native S-SAD at Room Temperature | +| [7MZT](https://www.rcsb.org/structure/7MZT) | IRRMC [10.18430/m37mzt](https://doi.org/10.18430/m37mzt) | APS 22-ID | 4.07 | P 21 21 2 | 113.6 97.0 108.3 90.0 90.0 90.0 | Dectris Eiger 16M | Borrelia burgdorferi BBK32-C in complex with an autolytic fragment of human C1r at 4.1A | +| [7N0I](https://www.rcsb.org/structure/7N0I) | SBGrid [10.15785/sbgrid/835](https://doi.org/10.15785/sbgrid/835) | ALS 5.0.2 | 2.20 | P 21 21 21 | 75.8 131.6 140.0 90.0 90.0 90.0 | PILATUS3 6M | Structure of the SARS-CoV-2 N protein C-terminal domain bound to single-domain antibody E2 | +| [7N2S](https://www.rcsb.org/structure/7N2S) | SBGrid [10.15785/sbgrid/916](https://doi.org/10.15785/sbgrid/916) | SSRL BL12-1 | 2.37 | P 1 21 1 | 83.2 52.8 106.3 90.0 98.3 90.0 | PILATUS 6M | AS3.1-PRPF3-HLA*B27 | +| [7ORR](https://www.rcsb.org/structure/7ORR) | IRRMC [10.18430/M37ORR](https://doi.org/10.18430/M37ORR) | MAX IV BioMAX | 1.79 | I 21 3 | 105.9 105.9 105.9 90.0 90.0 90.0 | Dectris Eiger 16M | Non-structural protein 10 (nsp10) from SARS CoV-2 in complex with fragment VT00022 | +| [7OS3](https://www.rcsb.org/structure/7OS3) | MXRDR [10.18150/74YTYQ](https://doi.org/10.18150/74YTYQ) | PETRA III, EMBL c/o DESY P13 (MX1) | 2.18 | P 21 21 21 | 78.2 91.0 105.8 90.0 90.0 90.0 | PILATUS 6M-F | Crystal structure of Rhizobium etli inducible L-asparaginase ReAV solved by S-SAD (orthorhombic form START) | +| [7OU1](https://www.rcsb.org/structure/7OU1) | MXRDR [10.18150/VQQIHQ](https://doi.org/10.18150/VQQIHQ) | BESSY 14.3 | 1.65 | P 1 21 1 | 77.9 91.3 114.2 90.0 97.1 90.0 | marCCD, 225 mm plate | Crystal structure of Rhizobium etli inducible L-asparaginase ReAV (monoclinic form MP2) | +| [7PH1](https://www.rcsb.org/structure/7PH1) | IRRMC [10.18430/M37PH1](https://doi.org/10.18430/M37PH1) | BESSY 14.2 | 1.18 | I 2 2 2 | 75.0 81.3 124.2 90.0 90.0 90.0 | PILATUS3 2M | Trypsin in complex with BPTI mutant (2S)-2-amino-4-monofluorobutanoic acid | +| [7PQ7](https://www.rcsb.org/structure/7PQ7) | IRRMC [10.18430/M3.IRRMC.6072](https://doi.org/10.18430/M3.IRRMC.6072) | ELETTRA 11.2C | 1.55 | C 1 2 1 | 120.9 51.7 75.5 90.0 125.1 90.0 | PILATUS 6M | Crystal structure of Campylobacter jejuni DsbA1 | +| [7Q6J](https://www.rcsb.org/structure/7Q6J) | Zenodo [10.5281/zenodo.4686876](https://doi.org/10.5281/zenodo.4686876) | PETRA III, DESY P11 | 2.20 | P 21 21 21 | 72.7 115.9 116.2 90.0 90.0 90.0 | PILATUS 6MF | Crystal structure of the human GDAP1 CMT2 mutant-H123R | +| [7QIJ](https://www.rcsb.org/structure/7QIJ) | SBGrid [10.15785/sbgrid/907](https://doi.org/10.15785/sbgrid/907) | PETRA III, EMBL c/o DESY P13 (MX1) | 4.10 | P 21 21 21 | 143.5 324.9 369.4 90.0 90.0 90.0 | PILATUS 6M-F | Complex of the Yersinia enterocolitica Type III secretion export gate YscV with substrate:chaperone complex YscX:YscY | +| [7QIS](https://www.rcsb.org/structure/7QIS) | IRRMC [10.18430/M37QIS](https://doi.org/10.18430/M37QIS) | BESSY 14.2 | 1.83 | P 61 | 100.3 100.3 206.2 90.0 90.0 120.0 | PILATUS3 2M | CRYSTAL STRUCTURE OF THE P1 difluoroethylglycine (DfeGly) BPTI MUTANT- BOVINE CHYMOTRYPSIN COMPLEX | +| [7QT9](https://www.rcsb.org/structure/7QT9) | Zenodo [10.5281/zenodo.5836055](https://doi.org/10.5281/zenodo.5836055) | Diamond I24 | 2.43 | I 1 2 1 | 45.2 54.5 115.7 90.0 101.1 90.0 | PILATUS3 6M | Room temperature In-situ SARS-CoV-2 MPRO with bound Z4439011584 | +| [7RAA](https://www.rcsb.org/structure/7RAA) | SBGrid [10.15785/sbgrid/881](https://doi.org/10.15785/sbgrid/881) | SSRL BL12-2 | 2.69 | P 43 21 2 | 66.4 66.4 298.3 90.0 90.0 90.0 | PILATUS 6M | Designed StabIL-2 seq15 | +| [7RIS](https://www.rcsb.org/structure/7RIS) | IRRMC [10.18430/M37RIS](https://doi.org/10.18430/M37RIS) | APS 21-ID-D | 1.72 | P 32 2 1 | 44.5 44.5 189.9 90.0 90.0 120.0 | Dectris Eiger 9M | Crystal structure of RPA3624, a beta-propeller lactonase from Rhodopseudomonas palustris, with active-site bound phosphate | +| [7RJI](https://www.rcsb.org/structure/7RJI) | IRRMC [10.18430/M37RJI](https://doi.org/10.18430/M37RJI) | LNLS W01B-MX2 | 1.71 | H 3 2 | 83.0 83.0 124.8 90.0 90.0 120.0 | PILATUS 2M | BthTX-II variant b, from Bothrops jararacussu venom, complexed with stearic acid | +| [7T5T](https://www.rcsb.org/structure/7T5T) | SBGrid [10.15785/sbgrid/864](https://doi.org/10.15785/sbgrid/864) | SSRL BL9-2 | 1.35 | P 42 21 2 | 95.3 95.3 104.9 90.0 90.0 90.0 | PILATUS 6M | Structure of Thauera sp. K11 CapP | +| [7TCD](https://www.rcsb.org/structure/7TCD) | IRRMC [10.18430/m37tcd](https://doi.org/10.18430/m37tcd) | SLS X06SA | 1.70 | C 1 2 1 | 138.5 47.9 78.1 90.0 107.6 90.0 | Dectris Eiger 16M | LOV2-DARPIN fusion: D13 | +| [7YZX](https://www.rcsb.org/structure/7YZX) | IRRMC [10.18430/M37YZX](https://doi.org/10.18430/M37YZX) | Diamond I24 | 1.90 | P 63 2 2 | 169.4 169.4 141.8 90.0 90.0 120.0 | PILATUS3 6M | ScpA from Streptococcus pyogenes, D783A mutant. | +| [8A1A](https://www.rcsb.org/structure/8A1A) | IRRMC [10.18430/M38A1A](https://doi.org/10.18430/M38A1A) | SLS X06SA | 2.05 | P 65 | 191.9 191.9 122.4 90.0 90.0 120.0 | Dectris Eiger 16M | Structure of a leucinostatin derivative determined by host lattice display : L1F11V1 construct | +| [8AGQ](https://www.rcsb.org/structure/8AGQ) | IRRMC [10.18430/M38AGQ](https://doi.org/10.18430/M38AGQ) | SLS X06DA | 1.09 | C 1 2 1 | 89.9 55.4 54.8 90.0 113.5 90.0 | PILATUS 2MF | Crystal structure of anthocyanin-related GSTF8 from Populus trichocarpa in complex with (-)-catechin and glutathione | +| [8C3E](https://www.rcsb.org/structure/8C3E) | Zenodo [10.5281/zenodo.14555180](https://doi.org/10.5281/zenodo.14555180) | Home source, Rigaku PhotonJet-S | 2.10 | P 31 2 1 | 57.8 57.8 41.5 90.0 90.0 120.0 | CrysAlisPro HPAD, 775 x 800 | Engineered mini-protein LCB2 (blocking ligand of SARS-Cov-2 spike protein) | +| [8DQB](https://www.rcsb.org/structure/8DQB) | IRRMC [10.18430/m38dqb](https://doi.org/10.18430/m38dqb) | NSLS-II 19-ID | 2.50 | I 2 3 | 164.1 164.1 164.1 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal structure of 3-dehydroquinate dehydratase I from Klebsiella oxytoca (I23 Form) | +| [8DYZ](https://www.rcsb.org/structure/8DYZ) | SBGrid [10.15785/sbgrid/957](https://doi.org/10.15785/sbgrid/957) | CHESS F1 | 1.27 | P 43 21 2 | 79.6 79.6 38.3 90.0 90.0 90.0 | PILATUS3 6M | Hen lysozyme in tetragonal space group at ambient temperature - diffuse scattering dataset | +| [8DZ7](https://www.rcsb.org/structure/8DZ7) | SBGrid [10.15785/sbgrid/958](https://doi.org/10.15785/sbgrid/958) | CHESS F1 | 1.34 | P 21 21 21 | 30.5 56.4 73.9 90.0 90.0 90.0 | PILATUS3 6M | Hen lysozyme in orthorhombic space group at ambient temperature - diffuse scattering dataset | +| [8EGN](https://www.rcsb.org/structure/8EGN) | IRRMC [10.18430/M38EGN](https://doi.org/10.18430/M38EGN) | CLSI 08B1-1 | 1.95 | P 21 21 21 | 71.7 75.2 109.8 90.0 90.0 90.0 | PILATUS3 6M | Crystal Structure of UDP-N-acetylmuramate-L-alanine ligase (UDP-N-acetylmuramoyl-L-alanine synthetase, MurC) Pseudomonas aeruginosa in complex with ligand AZ-13643701 | +| [8IYA](https://www.rcsb.org/structure/8IYA) | IRRMC [10.18430/m38iya](https://doi.org/10.18430/m38iya) | SSRF BL02U1 | 2.43 | C 1 2 1 | 102.7 50.1 109.2 90.0 91.8 90.0 | Dectris EIGER2 Si 9M | Complex of SETDB1-derived peptide bound to UBE2E1 | +| [8K1G](https://www.rcsb.org/structure/8K1G) | IRRMC [10.18430/M38K1G](https://doi.org/10.18430/M38K1G) | PAL/PLS 11C | 2.09 | I 4 2 2 | 182.0 182.0 80.7 90.0 90.0 90.0 | PILATUS3 6M | Crystal structure of ethylene glycol-bound glycerol dehydrogenase from Klebsiella pneumoniae | +| [8OIC](https://www.rcsb.org/structure/8OIC) | IRRMC [10.18430/m38oic](https://doi.org/10.18430/m38oic) | Diamond I04 | 2.80 | P 1 | 73.1 94.7 120.6 105.1 90.0 93.8 | Eiger 16M | Trichomonas vaginalis riboside hydrolase (His-tagged) | +| [8OWM](https://www.rcsb.org/structure/8OWM) | MXRDR [10.18150/II5MT4](https://doi.org/10.18150/II5MT4) | PETRA III, EMBL c/o DESY P13 (MX1) | 1.70 | P 1 | 95.5 95.6 95.8 90.4 93.6 117.8 | Dectris Eiger 16M | Crystal structure of glutamate dehydrogenase 2 from Arabidopsis thaliana binding Ca, NAD and 2,2-dihydroxyglutarate | +| [8PQD](https://www.rcsb.org/structure/8PQD) | IRRMC [10.18430/m38pqd](https://doi.org/10.18430/m38pqd) | ESRF MASSIF-3 | 1.50 | P 21 21 21 | 59.4 59.4 192.9 90.0 90.0 90.0 | Dectris Eiger 4M | c-KIT kinase domain in complex with avapritinib derivative 10 | +| [8QAW](https://www.rcsb.org/structure/8QAW) | MXRDR [10.18150/INUP4Q](https://doi.org/10.18150/INUP4Q) | PETRA III, EMBL c/o DESY P13 (MX1) | 1.55 | H 3 | 137.7 137.7 265.9 90.0 90.0 120.0 | Dectris Eiger 16M | Medicago truncatula HISN5 (IGPD) in complex with MN, IMD, EDO, FMT, GOL and TRS | +| [8QJ5](https://www.rcsb.org/structure/8QJ5) | IRRMC [10.18430/m38qj5](https://doi.org/10.18430/m38qj5) | ELETTRA 11.2C | 1.63 | P 1 21 1 | 57.6 100.6 77.9 90.0 96.1 90.0 | PILATUS 6M | Crystal structure of the Levansucrase beta from Pseudomonas syringae pv. actinidiae | +| [8QQ7](https://www.rcsb.org/structure/8QQ7) | Zenodo [10.5281/zenodo.14901515](https://doi.org/10.5281/zenodo.14901515) | ESRF MASSIF-1 | 3.62 | P 64 2 2 | 146.0 146.0 153.6 90.0 90.0 120.0 | PILATUS3 2M | Structure of SpNOX: a Bacterial NADPH oxidase | +| [8R5R](https://www.rcsb.org/structure/8R5R) | IRRMC [10.18430/m38r5r](https://doi.org/10.18430/m38r5r) | ESRF ID23-1 | 3.08 | P 21 21 21 | 91.7 132.9 137.5 90.0 90.0 90.0 | Dectris EIGER2 CdTe 16M | Structure of apo TDO with a bound inhibitor | +| [8RUD](https://www.rcsb.org/structure/8RUD) | MXRDR [10.18150/RBG2F9](https://doi.org/10.18150/RBG2F9) | PETRA III, EMBL c/o DESY P13 (MX1) | 2.10 | P 1 21 1 | 78.1 91.4 114.5 90.0 96.9 90.0 | Dectris Eiger 16M | Crystal structure of Rhizobium etli L-asparaginase ReAV K138A mutant | +| [8S38](https://www.rcsb.org/structure/8S38) | MXRDR [10.18150/CGLBVH](https://doi.org/10.18150/CGLBVH) | PETRA III, EMBL c/o DESY P13 (MX1) | 1.89 | I 21 21 21 | 95.4 163.1 219.0 90.0 90.0 90.0 | PILATUS 6M-F | Crystal structure of Medicago truncatula glutamate dehydrogenase 2 in complex with citrate and NAD | +| [8SA8](https://www.rcsb.org/structure/8SA8) | IRRMC [10.18430/M38SA8](https://doi.org/10.18430/M38SA8) | NSLS-II 19-ID | 1.30 | I 1 2 1 | 87.9 131.5 165.4 90.0 104.5 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of Cystathionine beta lyase from Klebsiella aerogenes, Covalently bound and free PLP (I2 form) | +| [8SQO](https://www.rcsb.org/structure/8SQO) | IRRMC [10.18430/m38sqo](https://doi.org/10.18430/m38sqo) | NSLS-II 19-ID | 1.55 | P 4 3 2 | 112.9 112.9 112.9 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of Bacterioferritin (Bfr) from Brucella abortus (magnesium bound, F16L mutant) | +| [8SQQ](https://www.rcsb.org/structure/8SQQ) | IRRMC [10.18430/M38SQQ](https://doi.org/10.18430/M38SQQ) | NSLS-II 19-ID | 2.25 | F 4 3 2 | 171.5 171.5 171.5 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of Bacterioferritin (Bfr) from Brucella abortus (Apo Cubic Form 2, F16L mutant) | +| [8SQT](https://www.rcsb.org/structure/8SQT) | IRRMC [10.18430/M38SQT](https://doi.org/10.18430/M38SQT) | NSLS-II 19-ID | 2.20 | F 4 3 2 | 170.7 170.7 170.7 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of Bacterioferritin (Bfr) from Brucella abortus (iron bound, cubic form 2, F16L mutant) | +| [8T7R](https://www.rcsb.org/structure/8T7R) | IRRMC [10.18430/M38T7R](https://doi.org/10.18430/M38T7R) | APS 22-ID | 3.84 | C 1 2 1 | 357.1 259.6 255.4 90.0 133.1 90.0 | Dectris Eiger 16M | Crystal structure of human leukocyte antigen A*0101 in complex with the Fab of alloreactive antibody E07 | +| [8THA](https://www.rcsb.org/structure/8THA) | IRRMC [10.18430/m38tha](https://doi.org/10.18430/m38tha) | SSRL BL9-2 | 1.68 | P 64 | 69.2 69.2 29.1 90.0 90.0 120.0 | PILATUS 6M | 1TEL, non-compressed, double-helical crystal form | +| [8TYY](https://www.rcsb.org/structure/8TYY) | SBGrid [10.15785/sbgrid/1040](https://doi.org/10.15785/sbgrid/1040) | APS 24-ID-E | 1.68 | F 4 3 2 | 214.9 214.9 214.9 90.0 90.0 90.0 | Dectris Eiger 16M | Structure of a bacterial Ubl-deubiquitinase complex (form 2) | +| [8U0I](https://www.rcsb.org/structure/8U0I) | IRRMC [10.18430/m38u0i](https://doi.org/10.18430/m38u0i) | ALS 8.2.1 | 1.54 | P 43 21 2 | 50.3 50.3 90.6 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal structure of PA0012 complexed with cyclic-di-GMP from Pseudomonas aeruginosa | +| [8V2T](https://www.rcsb.org/structure/8V2T) | Zenodo [10.5281/zenodo.10201899](https://doi.org/10.5281/zenodo.10201899) | NSLS X25 | 1.40 | P 42 21 2 | 60.9 60.9 92.7 90.0 90.0 90.0 | PILATUS 6M | Phosphoheptose isomerase GMHA from Burkholderia pseudomallei bound to inhibitor Mut148591 | +| [8V4J](https://www.rcsb.org/structure/8V4J) | Zenodo [10.5281/zenodo.10222807](https://doi.org/10.5281/zenodo.10222807) | NSLS X29A | 1.31 | P 42 21 2 | 61.0 61.0 92.4 90.0 90.0 90.0 | ADSC Quantum 315 | Phosphoheptose isomerase GMHA from Burkholderia pseudomallei bound to inhibitor Mut148233 | +| [8V4O](https://www.rcsb.org/structure/8V4O) | IRRMC [10.18430/m38v4o](https://doi.org/10.18430/m38v4o) | NSLS-II 19-ID | 2.70 | P 61 2 2 | 139.5 139.5 545.0 90.0 90.0 120.0 | Dectris EIGER2 Si 9M | Crystal structure of Acetyl-CoA synthetase 2 in complex with AMP from Candida albicans | +| [8XBP](https://www.rcsb.org/structure/8XBP) | IRRMC [10.18430/M38XBP](https://doi.org/10.18430/M38XBP) | SOLEIL PROXIMA 1 | 1.99 | C 1 2 1 | 148.3 50.8 60.2 90.0 92.3 90.0 | Dectris Eiger 16M | Crystal structure of AtNATA1 bound to Acetyl CoA | +| [8XTE](https://www.rcsb.org/structure/8XTE) | SBGrid [10.15785/sbgrid/1101](https://doi.org/10.15785/sbgrid/1101) | SSRF BL19U1 | 1.99 | P 32 | 208.8 208.8 67.2 90.0 90.0 120.0 | PILATUS3 6M | Crystal structure of methyltransferase MpaG' in complex with SAH and FDHMP | +| [8XTF](https://www.rcsb.org/structure/8XTF) | SBGrid [10.15785/sbgrid/1102](https://doi.org/10.15785/sbgrid/1102) | SSRF BL02U1 | 2.13 | H 3 2 | 211.8 211.8 67.4 90.0 90.0 120.0 | Dectris EIGER2 Si 9M | Crystal structure of methyltransferase MpaG' in complex with SAH and FDHMP-3C | +| [8XTG](https://www.rcsb.org/structure/8XTG) | SBGrid [10.15785/sbgrid/1100](https://doi.org/10.15785/sbgrid/1100) | SSRF BL19U1 | 2.00 | P 32 | 199.5 199.5 67.2 90.0 90.0 120.0 | | Crystal structure of methyltransferase MpaG' in complex with SAH and DMMPA | +| [8Y74](https://www.rcsb.org/structure/8Y74) | XRDa [10.51093/xrd-00227](https://doi.org/10.51093/xrd-00227) | SSRF BL02U1 | 1.90 | C 1 2 1 | 125.8 76.6 87.1 90.0 92.4 90.0 | Dectris EIGER2 Si 9M | Crystal structure of 9-mer peptide from H9N2 avian influenza virus in complex with BF2*0201 | +| [8YS9](https://www.rcsb.org/structure/8YS9) | IRRMC [10.18430/M38YS9](https://doi.org/10.18430/M38YS9) | PAL/PLS 5C (4A) | 1.46 | P 21 21 21 | 71.0 77.7 83.2 90.0 90.0 90.0 | Dectris Eiger 9M | Crystal structure of Phosphatidylethanolamine N-methyltransferase from R. thermophilum complexed with DMPE and SAH | +| [9B22](https://www.rcsb.org/structure/9B22) | IRRMC [10.18430/m39b22](https://doi.org/10.18430/m39b22) | NSLS-II 19-ID | 1.30 | P 1 21 1 | 39.8 92.7 57.7 90.0 91.7 90.0 | Dectris EIGER2 Si 9M | Crystal structure of ADP-ribose diphosphatase from Klebsiella pneumoniae (ADP Ribose and AMP bound) | +| [9BN8](https://www.rcsb.org/structure/9BN8) | IRRMC [10.18430/m39bn8](https://doi.org/10.18430/m39bn8) | NSLS-II 19-ID | 1.35 | P 41 | 65.5 65.5 134.8 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of UDP-N-acetylmuramoylalanine--D-glutamate ligase (MurD) from E. coli in complex with UMA and inhibitor A19 | +| [9C18](https://www.rcsb.org/structure/9C18) | Zenodo [10.5281/zenodo.11405662](https://doi.org/10.5281/zenodo.11405662) | NSLS-II 17-ID-1 | 1.90 | P 1 | 41.9 42.0 60.2 84.1 87.2 63.7 | Dectris EIGER1 Si 9M | Human biliverdin IX beta reductase in complex with NADP in space group P1 | +| [9CHW](https://www.rcsb.org/structure/9CHW) | SBGrid [10.15785/sbgrid/1124](https://doi.org/10.15785/sbgrid/1124) | APS 21-ID-F | 2.16 | P 61 | 98.7 98.7 82.1 90.0 90.0 120.0 | Rayonix MX-300 | Crystal structure of human polymerase eta with incoming dAMPnPP nucleotide opposite threofuranosyl thymidine in DNA template | +| [9CRW](https://www.rcsb.org/structure/9CRW) | IRRMC [10.18430/m39crw](https://doi.org/10.18430/m39crw) | CLSI 08ID-1 | 2.49 | P 1 21 1 | 84.0 104.6 118.8 90.0 93.4 90.0 | Dectris Eiger 9M | Crystal structure of the Candida albicans kinesin-8 proximal tail domain | +| [9E2T](https://www.rcsb.org/structure/9E2T) | SBGrid [10.15785/sbgrid/1148](https://doi.org/10.15785/sbgrid/1148) | SSRL BL12-1 | 2.28 | P 1 | 75.5 78.1 101.2 94.6 103.4 114.5 | Dectris EIGER2 Si 16M | Structure of a de novo designed interleukin-21 mimetic complex with IL-21R and IL-2Rg | +| [9EA5](https://www.rcsb.org/structure/9EA5) | SBGrid [10.15785/sbgrid/1142](https://doi.org/10.15785/sbgrid/1142) | SSRL BL9-2 | 2.00 | P 1 21 1 | 65.9 73.1 98.4 90.0 108.7 90.0 | PILATUS 6M | Structure of Citrobacter BubCD D104A mutant | +| [9FCF](https://www.rcsb.org/structure/9FCF) | MXRDR [10.18150/DGZKW3](https://doi.org/10.18150/DGZKW3) | PETRA III, EMBL c/o DESY P13 (MX1) | 2.36 | P 4 | 91.3 91.3 35.8 90.0 90.0 90.0 | Dectris EIGER1 Si 16M | Medicago truncatula 5'-ProFAR isomerase (HISN3) D57N mutant in complex with ProFAR | +| [9FCG](https://www.rcsb.org/structure/9FCG) | MXRDR [10.18150/LDLSBT](https://doi.org/10.18150/LDLSBT) | PETRA III, EMBL c/o DESY P13 (MX1) | 1.54 | P 4 | 87.8 87.8 35.6 90.0 90.0 90.0 | Dectris EIGER1 Si 16M | Medicago truncatula 5'-ProFAR isomerase (HISN3) D57N mutant in complex with PrFAR | +| [9FHC](https://www.rcsb.org/structure/9FHC) | Zenodo [10.5281/zenodo.11472085](https://doi.org/10.5281/zenodo.11472085) | SLS X06SA | 2.20 | I 2 3 | 227.5 227.5 227.5 90.0 90.0 90.0 | marCCD, 225 mm plate | Crystallographic structure of AcrB V612F with bound minocycline | +| [9GDJ](https://www.rcsb.org/structure/9GDJ) | ESRF [10.15151/ESRF-DC-1848199439](https://doi.org/10.15151/ESRF-DC-1848199439) | ESRF ID23-1 | 1.47 | P 41 21 2 | 123.9 123.9 126.4 90.0 90.0 90.0 | Dectris EIGER2 CdTe 16M | C-Methyltransferase SgMT from Streptomyces griseoviridis | +| [9GJX](https://www.rcsb.org/structure/9GJX) | IRRMC [10.18430/M39GJX](https://doi.org/10.18430/M39GJX) | Diamond I04 | 2.40 | P 1 21 1 | 76.8 115.8 103.8 90.0 110.3 90.0 | Eiger 16M | Bacillus licheniformis nitroreductase | +| [9GQG](https://www.rcsb.org/structure/9GQG) | ESRF [10.15151/ESRF-DC-1900353437](https://doi.org/10.15151/ESRF-DC-1900353437) | ESRF ID30B | 2.00 | P 32 2 1 | 48.2 48.2 188.0 90.0 90.0 120.0 | Dectris EIGER2 Si 9M | The FK1 domain of FKBP51 in complex with the macrocyclic SAFit analog m5(10,7)-(E)-OH | +| [9H0Q](https://www.rcsb.org/structure/9H0Q) | Zenodo [10.5281/zenodo.13912326](https://doi.org/10.5281/zenodo.13912326) | SOLEIL PROXIMA 2 | 2.55 | H 3 2 | 169.5 169.5 344.0 90.0 90.0 120.0 | Dectris EIGER1 Si 9M | N terminal domain of BC2L-C lectin in complex with N-(beta-L-Fucopyranosyl)-biphenyl-3-carboxamide | +| [9HNC](https://www.rcsb.org/structure/9HNC) | MXRDR [10.60884/0K7B68](https://doi.org/10.60884/0K7B68) | PETRA III, EMBL c/o DESY P13 (MX1) | 1.88 | P 1 2 1 | 123.8 123.6 187.7 90.0 90.1 90.0 | PILATUS 6M-F | Crystal structure of potassium-independent L-asparaginase from Phaseolus vulgaris (PvAIII, PvAspG2) | +| [9HS7](https://www.rcsb.org/structure/9HS7) | IRRMC [10.18430/M39HS7](https://doi.org/10.18430/M39HS7) | ALBA XALOC | 1.70 | P 65 | 65.4 65.4 88.8 90.0 90.0 120.0 | PILATUS3 X 6M | Anti-HIV-1 chimeric miniprotein mimicking the N-terminal half of gp41 NHR with an extended region targeting the MPER | +| [9I0A](https://www.rcsb.org/structure/9I0A) | IRRMC [10.18430/M39I0A](https://doi.org/10.18430/M39I0A) | SOLEIL PROXIMA 1 | 2.22 | P 21 21 2 | 75.2 98.7 208.6 90.0 90.0 90.0 | Dectris Eiger 16M | CARM1 in complex with arg-aDMA analog | +| [9I80](https://www.rcsb.org/structure/9I80) | Zenodo [10.5281/zenodo.14844040](https://doi.org/10.5281/zenodo.14844040) | SOLEIL PROXIMA 1 | 1.95 | P 41 | 81.2 81.2 165.0 90.0 90.0 90.0 | Dectris Eiger 16M | LecA in complex with a tolcapone derivative glycomimetic | +| [9IG7](https://www.rcsb.org/structure/9IG7) | IRRMC [10.18430/M39IG7](https://doi.org/10.18430/M39IG7) | PETRA III, EMBL c/o DESY P13 (MX1) | 2.60 | P 21 21 2 | 111.5 153.5 69.0 90.0 90.0 90.0 | Dectris EIGER1 Si 16M | KOD-H4 DNA polymerase mutant in a binary complex with DNA:DNA containing two AtNA nucleotides | +| [9IH9](https://www.rcsb.org/structure/9IH9) | IRRMC [10.18430/M39IH9](https://doi.org/10.18430/M39IH9) | ESRF MASSIF-3 | 1.70 | C 1 2 1 | 78.8 133.9 82.3 90.0 101.4 90.0 | Dectris EIGER1 Si 4M | KEAP1 complexed to linear peptide 6 | +| [9JQ9](https://www.rcsb.org/structure/9JQ9) | IRRMC [10.18430/M39JQ9](https://doi.org/10.18430/M39JQ9) | Home source, Excillum MetalJet D2+ | 1.90 | P 21 21 21 | 48.6 50.5 78.6 90.0 90.0 90.0 | PILATUS3 1M | Crystal structure of Plasmoredoxin from Plasmodium falciparum a disulfide oxidoreductase protein unique to Plasmodium species | +| [9JZO](https://www.rcsb.org/structure/9JZO) | IRRMC [10.18430/m39jzo](https://doi.org/10.18430/m39jzo) | PAL/PLS 11C | 1.40 | P 1 | 41.6 43.1 54.2 113.0 90.1 118.2 | PILATUS3 6M | Crystal structure of PHICD111_20024_EAD. | +| [9KHR](https://www.rcsb.org/structure/9KHR) | Zenodo [10.5281/zenodo.14070468](https://doi.org/10.5281/zenodo.14070468) | RRCAT INDUS-2 PX-BL21 | 2.00 | P 21 21 21 | 48.7 50.3 78.0 90.0 90.0 90.0 | marCCD, 225 mm plate | Crystal structure of Plasmoredoxin, a disulfide oxidoreductase from Plasmodium falciparum crystallized in the presence of Dithiothreitol (DTT) | +| [9LXL](https://www.rcsb.org/structure/9LXL) | Zenodo [10.5281/zenodo.15005358](https://doi.org/10.5281/zenodo.15005358) | SSRF BL17UM | 2.19 | P 41 21 2 | 76.8 76.8 225.3 90.0 90.0 90.0 | EIGER2 S 16M | Crystal structure of GH29 family alpha-L-fucosidase from Fusarium proliferatum LE1 | +| [9MH4](https://www.rcsb.org/structure/9MH4) | IRRMC [10.18430/M39MH4](https://doi.org/10.18430/M39MH4) | NSLS-II 19-ID | 3.05 | P 21 3 | 138.7 138.7 138.7 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of Bifunctional protein GlmU from Klebsiella aerogenes | +| [9MIN](https://www.rcsb.org/structure/9MIN) | SBGrid [10.15785/sbgrid/1151](https://doi.org/10.15785/sbgrid/1151) | ALS 8.2.1 | 2.05 | P 21 21 21 | 95.5 98.5 155.7 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Structure of a designed minibinder to NYESO1-A*02:01 | +| [9O0H](https://www.rcsb.org/structure/9O0H) | IRRMC [10.18430/M39O0H](https://doi.org/10.18430/M39O0H) | SSRL BL12-2 | 2.24 | P 21 21 21 | 55.2 65.5 112.9 90.0 90.0 90.0 | Dectris EIGER2 Si 16M | The ubiquitin-associated domain of human thirty-eight negative kinase 1, fused to the 3TEL crystallization chaperone via a 2-glycine linker | +| [9P7Q](https://www.rcsb.org/structure/9P7Q) | IRRMC [10.18430/M39P7Q](https://doi.org/10.18430/M39P7Q) | SSRL BL12-1 | 2.21 | C 1 2 1 | 97.0 45.0 72.1 90.0 105.1 90.0 | Dectris EIGER2 Si 16M | 273K human S-adenosylmethionine decarboxylase | +| [9PBB](https://www.rcsb.org/structure/9PBB) | IRRMC [10.18430/M39PBB](https://doi.org/10.18430/M39PBB) | SSRL BL12-1 | 2.17 | C 1 2 1 | 97.4 45.9 72.2 90.0 105.0 90.0 | Dectris EIGER2 Si 16M | 293K human S-adenosylmethionine decarboxylase | +| [9Q41](https://www.rcsb.org/structure/9Q41) | SBGrid [10.15785/sbgrid/1194](https://doi.org/10.15785/sbgrid/1194) | CHESS 7B2 | 1.95 | C 2 2 21 | 118.6 133.7 82.4 90.0 90.0 90.0 | Dectris EIGER2 Si 16M | Crystal Structure of Human Apo Spermidine Synthase | +| [9Q66](https://www.rcsb.org/structure/9Q66) | SBGrid [10.15785/sbgrid/1208](https://doi.org/10.15785/sbgrid/1208) | NSLS-II 17-ID-1 | 2.01 | P 1 21 1 | 105.9 67.3 158.0 90.0 99.1 90.0 | Dectris EIGER1 Si 9M | Human prolyl endopeptidase (PREP) - complex with JP-4-1-7 | +| [9QVV](https://www.rcsb.org/structure/9QVV) | Zenodo [10.5281/zenodo.19456697](https://doi.org/10.5281/zenodo.19456697) | Diamond I03 | 2.72 | I 2 2 2 | 120.1 123.8 123.8 90.0 90.0 90.0 | Eiger 16M | Crystal structure of the 4CHRD domain of human chordin, mutant designed to abolish binding to sulphated glycosaminoglycans | +| [9QW2](https://www.rcsb.org/structure/9QW2) | Keele University [10.21252/yzsx-0e16](https://doi.org/10.21252/yzsx-0e16) | Diamond I03 | 1.92 | P 1 21 1 | 55.4 108.2 55.6 90.0 90.9 90.0 | PILATUS3 6M | Crystal structure of human lung surfactant protein D trimeric fragment with bound synthetic HepII-HepI-PhosI ligand | +| [9QW8](https://www.rcsb.org/structure/9QW8) | ESRF [10.15151/ESRF-DC-2127908021](https://doi.org/10.15151/ESRF-DC-2127908021) | ESRF ID23-1 | 1.80 | P 1 | 35.6 35.6 100.9 86.5 84.2 72.5 | Dectris EIGER2 CdTe 16M | FKBP12 in complex with bifunctional ligand 1ad and the first bromodomain of BRD4 | +| [9RCI](https://www.rcsb.org/structure/9RCI) | Zenodo [10.5281/zenodo.15615368](https://doi.org/10.5281/zenodo.15615368) | SOLEIL PROXIMA 2 | 1.66 | P 1 | 35.9 39.3 100.9 98.3 90.3 90.1 | Dectris Eiger 9M | Crystal Structure of Flap Endonuclease FEN1 with Compound 28 | +| [9RCS](https://www.rcsb.org/structure/9RCS) | XRDa [10.51093/xrd-00383](https://doi.org/10.51093/xrd-00383) | Diamond I24 | 3.01 | P 1 21 1 | 70.0 78.8 82.3 90.0 88.6 90.0 | Eiger 9M | Cardioderma bat coronavirus KY43 receptor binding domain in complex with human CEACAM6 | +| [9RP9](https://www.rcsb.org/structure/9RP9) | IRRMC [10.18430/M39RP9](https://doi.org/10.18430/M39RP9) | SOLEIL PROXIMA 1 | 2.10 | C 1 2 1 | 73.5 59.8 91.7 90.0 100.8 90.0 | Dectris Eiger 16M | Crystal structure of mouse pVHL-ElonginB-ElonginC complex | +| [9S02](https://www.rcsb.org/structure/9S02) | MXRDR [10.60884/NRNGS4](https://doi.org/10.60884/NRNGS4) | MAX IV BioMAX | 1.65 | P 21 21 2 | 163.7 88.0 116.7 90.0 90.0 90.0 | EIGER2 X 16M | PYCR1 in complex with 3-(2-thiazolyl)propionic acid | +| [9SL0](https://www.rcsb.org/structure/9SL0) | IRRMC [10.18430/M39SL0](https://doi.org/10.18430/M39SL0) | ESRF MASSIF-1 | 1.60 | P 21 21 21 | 60.2 80.2 111.6 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal structure of HLA-A0201 in complex with peptide LLWNGPMAV | +| [9T6S](https://www.rcsb.org/structure/9T6S) | SBGrid [10.15785/sbgrid/1260](https://doi.org/10.15785/sbgrid/1260) | ESRF ID30B | 2.00 | P 21 21 21 | 63.0 64.6 102.7 90.0 90.0 90.0 | Dectris EIGER2 Si 9M | Crystal Structure of the Listeria monocytogenes CadC with Cadmium | +| [9UPT](https://www.rcsb.org/structure/9UPT) | XRDa [10.51093/xrd-00191](https://doi.org/10.51093/xrd-00191) | NSRRC TPS 05A | 2.37 | P 6 | 158.3 158.3 54.0 90.0 90.0 120.0 | SMV, S/N 930 | Structure of AtBgl1A, a GH1 beta-Glucosidase from Acetivibrio thermocellus | +| [9V16](https://www.rcsb.org/structure/9V16) | XRDa [10.51093/xrd-00338](https://doi.org/10.51093/xrd-00338) | SPring-8 BL44XU | 3.45 | P 41 21 2 | 185.6 185.6 451.2 90.0 90.0 90.0 | Dectris EIGER1 Si 16M | Crystal structure of E. coli glycogen phosphorylase N185A/R267E mutant in complex with AMP | +| [9VX7](https://www.rcsb.org/structure/9VX7) | IRRMC [10.18430/M39VX7](https://doi.org/10.18430/M39VX7) | PAL/PLS 5C (4A) | 4.85 | P 64 | 122.5 122.5 118.9 90.0 90.0 120.0 | PILATUS3 6M | Transcription factor | +| [9VYB](https://www.rcsb.org/structure/9VYB) | IRRMC [10.18430/M39VYB](https://doi.org/10.18430/M39VYB) | PAL/PLS 5C (4A) | 2.12 | P 21 21 21 | 44.4 47.8 48.4 90.0 90.0 90.0 | Dectris Eiger 9M | Antitoxin Phd | +| [9W3Y](https://www.rcsb.org/structure/9W3Y) | IRRMC [10.18430/M39W3Y](https://doi.org/10.18430/M39W3Y) | Photon Factory BL-1A | 1.50 | P 21 21 21 | 60.7 70.0 94.2 90.0 90.0 90.0 | Dectris EIGER1 Si 4M | X-ray Crystal Structure of Pseudoazurin Met16Gly variant (Tris-HCl pH 7.6) | +| [9YL4](https://www.rcsb.org/structure/9YL4) | Zenodo [10.5281/zenodo.17298261](https://doi.org/10.5281/zenodo.17298261) | APS 17-ID | 3.70 | P 21 21 21 | 95.8 111.3 403.0 90.0 90.0 90.0 | PILATUS 6M | Crystal structure of PprA S-F filament from Deinococcus radiodurans | +| [9YZK](https://www.rcsb.org/structure/9YZK) | IRRMC [10.18430/M39YZK](https://doi.org/10.18430/M39YZK) | ALS 8.2.2 | 5.10 | I 1 2 1 | 75.8 163.0 192.3 90.0 98.6 90.0 | PILATUS3 S 2M | Isoreticular co-crystal 1 with symmetrical expanded duplex (42mer) containing insert sequence ACCCTTCTATGACCTACTCCA | +| [9Z44](https://www.rcsb.org/structure/9Z44) | IRRMC [10.18430/M39Z44](https://doi.org/10.18430/M39Z44) | ALS 8.2.1 | 7.20 | I 1 2 1 | 73.5 127.7 141.2 90.0 92.0 90.0 | Dectris EIGER2 Si 9M | Isoreticular co-crystal 1 with symmetrical expanded duplex (31mer) containing insert sequence CCCGGCCGGA and loaded with C-clamp domain | +| [9Z72](https://www.rcsb.org/structure/9Z72) | SBGrid [10.15785/sbgrid/1239](https://doi.org/10.15785/sbgrid/1239) | SSRL BL9-2 | 2.38 | P 31 2 1 | 59.2 59.2 426.2 90.0 90.0 120.0 | Dectris EIGER2 Si 16M | Structure of V. cholerae CapS (form 1) | +| [9ZLO](https://www.rcsb.org/structure/9ZLO) | Zenodo [10.5281/zenodo.18652652](https://doi.org/10.5281/zenodo.18652652) | Australian Synchrotron MX2 | 2.00 | P 21 21 21 | 38.4 90.0 107.0 90.0 90.0 90.0 | Dectris EIGER1 Si 16M | Crystal structure of Proteus mirabilis UreE | +| [9ZM0](https://www.rcsb.org/structure/9ZM0) | IRRMC [10.18430/M39ZM0](https://doi.org/10.18430/M39ZM0) | NSLS-II 17-ID-1 | 2.10 | P 1 21 1 | 50.4 30.1 91.2 90.0 97.1 90.0 | Dectris EIGER1 Si 9M | Crystal structure of monomeric Atg23 | +| [9ZMU](https://www.rcsb.org/structure/9ZMU) | IRRMC [10.18430/M39ZMU](https://doi.org/10.18430/M39ZMU) | NSLS-II 19-ID | 1.98 | P 65 2 2 | 47.8 47.8 492.6 90.0 90.0 120.0 | Dectris EIGER2 Si 9M | Crystal structure of an Iole protein from Brucella melitensis (hexagonal P form) | + +The table holds 204 PDB entries. Eight more datasets, small-molecule / chemical-crystallography +sets kept because they exercise short wavelengths, CdTe sensors, fine slicing and non-zero +detector 2θ, have no PDB entry and are listed [below](#datasets-with-no-pdb-entry). + +Twelve datasets are in primitive, non-triclinic space groups with no screw axis - 6P8P, 6ZQR, +6ZQY, 6ZR0, 9FCF and 9FCG in P 4, 6PB3 and 9UPT in P 6, 5JVN in P 6 2 2, 6NEN in P 3 1 2, 8SQO in +P 4 3 2 and 9HNC in P 1 2 1. They are negative controls for screw-axis detection: the correct +answer for each has no systematic absences. + +6Z9G is the collection's only index-4 superstructure: its deposited cell is four times the +sublattice a/2, b, c/2, and the four copies of each of its two entities are related by the +XOR-closed trio of near-pure translations (1/2,0,0), (0,0,1/2) and (1/2,0,1/2). Every other +pseudo-translation in the collection is index 2 or a setting artefact, so it is the one set that +exercises a supercell of index greater than two. + +## Archives that are not a single sweep + +Most rows above are a single continuous rotation. The archives described in this section are +not, or needed special handling to obtain the images; their layout is read from the image files +themselves, from the repository file listings and from the depositors' own description of the +record. Not every archive in the table has had its layout audited to this depth. Where an archive +held more than one collection, only one is kept - +the repository's project page is not a reliable guide to this, because it describes the project +rather than the tarball (7TCD's page lists a 900-frame miniCBF sweep the archive does not +contain). + +**6R72 - two collections on one crystal.** The Zenodo record holds two complete 360° sweeps of +3600 × 0.1° frames taken from the same crystal: a helical collection, which produced the +deposited structure, and a low-dose collection from a single position, which was not used for a +deposition. The battery's `6r72` row runs the **low-dose** collection (`V-CK63-8-ld_1_master.h5`, +pinned) and scores it against the deposited space group and cell, which describe the same crystal; +the deposited resolution belongs to the helical collection. The helical collection is in the +archive but is not a battery row. The record also ships the authors' `XDS.INP`. + +**The three CHESS depositions - wedges plus a measured background.** Each crystal was rotated in +50° wedges of 500 × 0.1° frames and translated between wedges to spread the dose. Each crystal +also has a rotation at 1° per frame taken with the crystal translated out of the beam, which the +depositors include as a measured background and say can be matched to the diffraction frames by +the `phi` value in the image header. + +| PDB | Crystals | Wedges per crystal | Background rotation | +|---|---|---|---| +| 8DYZ | 1 | 8 | 360 frames | +| 8DZ7 | 2 | 4 | 200 frames per crystal | +| 6O2H | 4 | 1, 3, 2, 5 - 11 in all | 50, 145, 95, 235 frames, one per crystal | + +**Four archives added for facility coverage hold more than one sweep.** One sweep is kept, and +the row is pinned to it. 7BGU's MXRDR record is one directory of 900 marCCD frames that are two +sweeps with different oscillation widths: frames 1001-1674 (0.4°) are the row, frames 1675-1900 +were moved to `sweep2/` so the reader sees one sweep. 5JK4's archive holds a high-resolution +sweep of 185 frames (80 mm, 1°) and a low-resolution one of 93 frames (250 mm, 2°); the row is +the high-resolution sweep. 6RYM's zip holds two sweeps (`jmp47a2_1`, 70 frames; `jmp47a2_2`, 60 +frames); the row is the first. 6GVK's Zenodo record has three tarballs (`set1`-`set3`); only +`set1` (1800 miniCBF frames) was downloaded and is the row. + +**Seven IRRMC archives hold more than one collection.** In six of them one sweep is kept and +the rest were deleted, so a run over the data directory sees a single collection per dataset. +7RIS is the exception: its two sweeps are at different wavelengths and both are kept. + +| PDB | What the archive holds | Kept | +|---|---|---| +| 6UKF | two sweeps on one crystal - 960 x 0.25° (240°) and 1440 x 0.25° (360°) | the 360° sweep | +| 7DKP | two complete 360° sweeps on one crystal, 3° apart in ω | the first | +| 9PBB | two overlapping 135° wedges of one crystal, 90 x 1.5° each | the first | +| 8U0I | a 69-frame screening wedge and three 180° sweeps on three crystals | the first 180° sweep | +| 36GK | two 360° sweeps of 1800 x 0.2° at the same geometry | the one the archive and DOI are named for | +| 9CRW | a dose pair on one crystal 37 min apart - 0.025 s at 289 mm, 0.010 s at 276 mm | the 0.025 s sweep, whose 2.5 Å target matches the deposited 2.49 Å | +| 7RIS | two crystals at two wavelengths - 1.53494 Å (Ho derivative) and 1.03329 Å (the deposited native) | **both** | + +**Seventeen further archives hold more than one collection.** Their layout was read from the +image files and repository listings; one sweep is kept for a run over the data directory unless +noted. + +| PDB / dataset | What the archive holds | Kept | +|---|---|---| +| 5JVN | two 360° sweeps of one crystal, 3600 × 0.1° each (`w1_3`, `w1_4`) | the `w1_3` sweep | +| 6FID | two 360° sweeps of one crystal, 3600 × 0.1° each | the first | +| 6IU8 | a two-wavelength MAD pair, 720 × 0.5° each at 1.605 Å (low remote) and 1.740 Å (peak) | **both** - the pair is the point | +| 7OS3 | four 360° sweeps at λ 2.066 Å, 3600 × 0.1° each, from two crystal positions (`pos2_1/2`, `pos3_1/2`) | all four are kept as separate sweep directories `pos*/` | +| 7L84 | two ~720° helical sweeps, 1439 × 0.5° each at λ 1.892 Å, room temperature | the `301_helical_1` sweep | +| 5M17 | seven crystals in one tar (5M03/5M17/5MEL/5MC8/5M5D/5M3W/5LYR), one 1800-frame sweep each | only the 5M17 tar was downloaded | +| cytidine | six scans, three ω and three φ, at 2θ = 30° (I19-1 commissioning) | the 1800-frame φ scan | +| lalanine | four runs of the RODIN L-alanine deposition at 2θ = 20° | the 900-frame `pgw240050_01` run | +| 9E2T | one continuous sweep plus screening images | the 2700-frame sweep | +| 8OWM | three MXRDR zips covering one 1800-frame sweep, plus a processed-data zip | the three sweep zips (proc zip skipped) | +| 6OR0 | four 900 × 0.2° Bruker `.sfrm` runs of one twinned crystal at 10 cm: ω scans at 2θ = 0° (`01`) and 35° (`02`), φ scans on the fixed-χ (54.74°) platform at 2θ = 0° (`03`) and 35° (`04`) | the `01` run (2θ = 0°): the header distance of these SMART 6000 frames is ~4% short of what the data give, which the distance refinement corrects on a 2θ = 0° run and not yet on a swung one | +| 6OQZ | eleven `.sfrm` ω runs of 472-900 × 0.2° at 18 cm, 2θ = 10°, 25° and 45° (low, medium, high resolution) at different φ, plus two 5-frame runs at 2θ = 0° and the orientation-matrix runs `gdri_MATRIX_*` | the low-resolution `01` run (2θ = 10°), for the reason given for 6OR0; three crystals, the test set for multi-lattice integration | +| laspartic | seven Bruker-converted full-imgCIF kappa runs, φ (`01`, 1200 × 0.3°) and ω (`02`-`07`, 292-394 frames) at 2θ = -26.7° | the 1200-frame `01` φ run | +| onitroaniline | the same seven-run kappa layout (`01` 1200 × 0.3° φ, `02`-`07` ω), deposited twice: as Bruker `.sfrm` and as APEX's full-imgCIF conversion of the same frames | the `01` run, read from the `.sfrm` files | +| 7D98 | one 250 × 0.5° miniCBF sweep (frames 11-260), plus four HDF5 masters that repeat frames 61-260 in 60-frame pieces | the miniCBF sweep; the HDF5 files stay beside it and the row is pinned | +| 6H2P | two sweeps of one crystal, 1800 × 0.1° at 0.918 Å and 3600 × 0.1° at 1.893 Å (the Mn K edge) | **both**, as two battery rows, `6h2p_native` and `6h2p_1p89A`; the long-wavelength row has no deposited resolution to compare with | +| 8C3E | four 0.5° ω scans of one crystal at different (φ, χ) settings, 56, 150, 150 and 50 frames (`lcb2_8_newt_001` to `_004`) | the 150-frame `_003` scan | + +**Four archives needed special handling to obtain the images.** + +- **5KY6** is served by MXRDR as 11 separate RAR archives, one folder of frames per archive, 50 + frames per archive except the last, 564 frames in all. Reading them needs a RAR reader with + RAR3 filter support: the official 7-Zip `7zz` reads them, while the unrar-free and p7zip builds + of Enterprise Linux 8 cannot. +- **6NEN**'s University of Queensland eSpace record blocks scripted download, so its archive was + downloaded by hand in a browser. +- **4P8R**'s IRRMC tar holds one 800 × 0.2° sweep as per-frame `.bz2` files, which rugnux does + not read; they were decompressed with `bunzip2` after extraction. +- **2WNN, 2WNQ, 2WNZ, 2XFW and 4BWL** are each served by the Zenodo record as two zips of 180 + frames (`-images-1-180.zip`, `-images-181-360.zip`, or `2wnq-181-360.zip`); both were + extracted into one directory, which holds the one 360 × 0.5° sweep. + +## Multi-sweep battery rows + +The opt-in `multisweep` arm of the battery (`tools/battery/multisweep.json`, see the +[battery README](../tools/battery/README.md#multi-sweep-rows-the-multisweep-arm-opt-in)) gives +rugnux several sweeps of the archives above at once and scores the one merge against the base +row's reference (7QT9, which has no single-sweep row, carries its own), plus which sweeps joined. +It uses only sweeps that are on disk: for 6UKF, 7DKP, +9PBB, 8U0I and 36GK the second collection was deleted (above), so they have no row until it is +downloaded again. Two-wavelength pairs (6IU8, 6H2P, 7RIS) are refused by rugnux as one dataset; +6IU8 is the row that checks it. + +| Row | Base row | Sweeps | What it covers | Expected | +|---|---|---|---|---| +| `6or0_sweeps` | open/6or0 | 4 | one twinned crystal: omega and phi scans at 2theta 0 and 35 deg (swung detector, header distance ~4% short) | all join | +| `6oqz_sweeps` | open/6oqz | 4 | one crystal at 2theta 10, 25, 45 and 45 deg; multi-lattice; the header distance makes the low-2theta runs' cell ~3% short | all join | +| `lalanine_sweeps` | open/lalanine | 4 | small molecule, four runs of one crystal at 2theta 20 deg | all join | +| `laspartic_sweeps` | open/laspartic | 7 | small molecule, seven kappa runs of one crystal (phi + six omega), sparse, twinned | all join | +| `cytidine_omega` | open/cytidine | 3 | small molecule, three omega scans at phi 0/120/240 at 2theta 30 deg | all join | +| `8c3e_scans` | open/8c3e | 4 | home source, four omega scans of one twinned crystal at different (phi, chi) | all join | +| `8dyz_wedges` | open/8dyz | 4 | one crystal, four of its eight 50 deg wedges, translated between wedges, room temperature, 1.27 A | all join | +| `8dz7_crystals` | open/8dz7 | 4 | two crystals, two 50 deg wedges each, room temperature, 1.34 A | all join | +| `6o2h_crystals` | open/6o2h | 4 | four triclinic crystals, one 50 deg wedge each, room temperature, 1.21 A | all join | +| `7qt9_crystals` | open data, own reference | 20 | in-situ crystals at room temperature, twenty 20 deg wedges (the depositors merged them as 16 crystals), none complete alone | more than half join | +| `7l84_helical` | open/7l84 | 2 | two ~720 deg helical sweeps of one crystal, S-SAD at 1.892 A, room temperature | all join | +| `6fid_sweeps` | open/6fid | 2 | two 360 deg sweeps of one crystal (aligned and random orientation), S-SAD at 2.066 A | all join | +| `6iu8_mad` | open/6iu8 | 2 | keep separate: a two-wavelength MAD pair of one crystal - one dataset per wavelength | refused (keep separate) | +| `lyso_x10sa_90deg_pair` | inhouse/lyso_x10sa_90deg_1 | 2 | two sweeps of one crystal at the same orientation, 42 s apart | all join | +| `lyso_x10sa_two_crystals` | inhouse/lyso_x10sa_90deg_1 | 2 | keep separate: two lysozyme crystals of one form at one wavelength whose intensities differ (cells 1 % apart) | one left out (keep separate) | + +## Datasets published as Raw Data Letters + +Five of the datasets - 6R72, 8QQ7, 6RLR, laspartic and onitroaniline - were published as IUCrData Raw Data Letters, a +format whose purpose is to make raw images citable and re-processable in their own right. The +letters describe the collections and the difficulties in them, and are the reference for what the +data are: + +- V. Zampieri, A. Vermot, M. Thepaut, I. Petit-Hartlein, F. Fieschi, P. Falson and V. Chaptal, + "X-ray diffraction images for two membrane protein crystals presenting high anisotropy; the + *B. subtilis* ABC transporter BmrA and the *S. pneumoniae* NADPH oxidase" (2025), IUCrData 10, + x250591 [doi:10.1107/S2414314625005917](https://doi.org/10.1107/S2414314625005917) - covers + 6R72 and 8QQ7. +- V. Neviani, M. Lutz, W. Oosterheert, P. Gros and L. Kroon-Batenburg, "Crystal structure of the + second extracellular domain of human tetraspanin CD9: twinning and diffuse scattering" (2022), + IUCrData 7, x220852 + [doi:10.1107/S2414314622008525](https://doi.org/10.1107/S2414314622008525) - covers 6RLR. + +- M. Lutz and L. Kroon-Batenburg, "Accurate intensity integration in the twinned γ-form of + *o*-nitroaniline" (2022), IUCrData 7 + [doi:10.1107/S2414314622010598](https://doi.org/10.1107/S2414314622010598) - covers + onitroaniline. +- M. Lutz, "Twinned L-aspartic acid" (2025), IUCrData 10 + [doi:10.1107/S241431462500879X](https://doi.org/10.1107/S241431462500879X) - covers laspartic: + a twofold rotation about [100] with twin index 2 and obliquity 0.74°, whose coincidence lattice + is the doubled cell first reported for the compound (Bernal, 1931). + +The authors of the second letter also published their own reciprocal-space reconstruction of the +6RLR data as a separate Zenodo record, +[10.5281/zenodo.6961763](https://doi.org/10.5281/zenodo.6961763). + +## Twinned and pseudo-symmetric datasets + +The rows below are twinned, or have a lattice metrically close to a higher symmetry than the +crystal's - the case where a data-reduction program is most easily led into the wrong point group. +What is said here is read from the depositions and their cells, except where a sentence says +otherwise; where the battery keeps further evidence for a row, it is in +`tools/battery/symmetry//`. + +**The pathological-data series.** 2WNN, 2WNQ, 2WNZ, 2XFW and 4BWL come from one Zenodo record, +"A series of pathological macromolecular crystallography datasets with twinning and other lattice +disorders" ([10.5281/zenodo.54568](https://doi.org/10.5281/zenodo.54568)), which was published +for testing data-processing and refinement programs and is described in I. Campeotto, A. Lebedev, +A. M. M. Schreurs, L. M. J. Kroon-Batenburg, E. Lowe, S. E. V. Phillips, G. N. Murshudov and +A. R. Pearson, "Pathological macromolecular crystallographic data affected by twinning, +partial-disorder and exhibiting multiple lattices for testing of data processing and refinement +tools" (2018), Sci. Rep. 8, 14876 +[doi:10.1038/s41598-018-32962-6](https://doi.org/10.1038/s41598-018-32962-6). All five are +deposited in P 1 21 1 with c cos β ≈ -a/2, so the lattice is metrically C-centred orthorhombic, +and the twin law four of them declare, -h,-k,h+l, is the two-fold that orthorhombic lattice adds: + +| PDB | Deposited twin fraction of -h,-k,h+l | +|---|---| +| 4BWL | 0.488 | +| 2WNQ | 0.463 | +| 2WNN | 0.334 | +| 2XFW | 0.096 | +| 2WNZ | none declared | + +At a fraction near 0.5 the intensities have the symmetry of C 2 2 21, so these rows +test whether a twinned P 21 crystal is reported as C 2 2 21. For 4BWL and +2WNQ, refining the deposited model in each candidate group keeps P 21, and no +C 2 2 21 operator maps the deposited chains onto each other; neither row accepts +C 2 2 21 as an alternative. + +**8C3E** is a home-source dataset deposited in P 31 2 1 with no twin law declared, +whose intensities, the depositor's included, read Laue class 6/mmm in POINTLESS: the operator that makes +6/mmm out of -3m1 is a merohedral twin law of P 31 2 1, and refining the deposited +model keeps P 31 2 1. The 75° scan also leaves the screw along c open; a run that +names that axis as undetermined and offers the deposited group among its alternatives scores the +row `unscored` (`screw_undetermined`, see `tools/battery/README.md`) rather than failed. + +**3MC4 and 3R6O** carry a `reference_mismatch` note in the manifest: the uploaded frames are of a +crystal twinned about 30% (law k,h,-l, seen also by XDS on the same frames), while the deposited +data are of an untwinned crystal of the same form. The row is scored as usual; the note tells the +reader of a report that the merged statistics are not expected to match the deposition's. + +**Pseudo-symmetric cells.** 6OWW (P 1 21 1, a ≈ b, β = 89.9°), 6P8J (P 1 21 1, β = 90.1°), +9QW2 (P 1 21 1, a ≈ c, β = 90.9°), 5OJV (P 21 21 2, a ≈ c), 7Q6J (P 21 21 21, b ≈ c) and 9QVV +(I 2 2 2, b ≈ c) all have a deposited cell within a fraction of a degree or of an ångström of a +higher lattice symmetry. 6OWW is one of the rows that accept an alternative answer, below. + +## Detector column for marCCD and SMV files + +marCCD and SMV files name the detector differently - or not at all. A marCCD file names no model: +its instrument header states the image dimensions and the pixel size, from which the plate size +follows (3072 x 73.242 um = 225 mm, 4096 x 73.242 um = 300 mm), and its comment block a serial +number; the LS-CAT beamlines additionally write `detector='Rayonix MX-300 s/n 023'` into the +dataset comment. An ADSC-style SMV header names only a serial (`DETECTOR_SN=930`); a Rigaku d*TREK one names the +model (`CCD_DETECTOR_DESCRIPTION=Saturn944+`), and that is what its row carries. For those rows the +Detector column carries what the file itself establishes: the plate size (`marCCD, 225 mm +plate`), the comment's name where one is present (`Rayonix MX-300`), or the serial (`SMV, S/N +930`). + +8C3E's files are CBF written by CrysAlisPro's HPAD export, whose header gives the image size +(`# Detector: 775 x 800`) and no model; its row carries that (`CrysAlisPro HPAD, 775 x 800`). +The PDB entry names the detector as a Rigaku HyPix-6000HE. + +## Deposited models and structure factors + +All 204 PDB entries in the table are released, and RCSB reports released structure factors +(`status_code_sf = REL`) for every one of them; the eight small-molecule datasets have none. A merged +result from this pipeline can therefore be checked against the deposited model or against the +deposited intensities. + +## Rows where our reduction and the deposition disagree + +Seven of the battery's rows are ones where `rugnux` does not reproduce the deposited space group or +cell, and where we have looked at the disagreement closely enough to change how the row is +scored. They are collected here because a scoring row that silently disagrees with a published +entry is not something a reader should have to discover from the code. + +**These are open questions, not errors we are attributing to the PDB.** A deposited entry was +arrived at by someone who had something we do not: a model that had to refine, and usually more +knowledge of the crystal than the images carry. Where we describe evidence below, it is evidence +about *what these images support*, which is a narrower thing than what the crystal is. In every +one of the symmetry rows the possibility that the crystal really has the lower symmetry, with a +pseudo-symmetry too exact for any test available to us to see, remains live - see the limit at +the end of this section. + +How the manifest records it, in `tools/battery/open.json`: + +- `ref` always keeps the deposited values verbatim, so the deposition is never lost. +- `ref_alternatives` lists the *other* answers the row accepts. Each one replaces the reference + fields it names - a space group, a cell, or both - and the row passes if our answer matches any + of the references, the deposited one included. Each must carry `why`; an alternative with no + stated reason is a schema error, not a silent pass, so the mechanism cannot become a way to + turn a failure into a pass quietly. This is how the six knife-edge rows below are recorded: + we are not asserting that our answer is right, only that both descriptions are defensible and + that picking either one is acceptable. The report counts these rows separately from ordinary + passes and prints the reason, so a reader can see how many there are and judge each. +- `ref_override` replaces the fields the battery scores against, with `ref_override_why`. It + *asserts* a corrected reference, so it is for a reference we can show to be wrong about these + images - 8XBP below - and not for a disagreement that is open. +- `unscored` drops the row from scoring entirely. It is a last resort: it also loses a test that + still works, which is why an open question is now recorded as accepted alternatives instead. + +### 8XBP is a question about provenance, not about symmetry + +8XBP is different in kind from the other six and should not be read alongside them. Nothing +here concerns the deposited model or its space group. The question is whether the raw images +uploaded with the entry are the same crystal the deposited cell describes: the master file +records `data_collection_date` 2023-06-21 where the entry records a collection date of +2023-06-23, and the deposited *b* = 50.78 A is 2.0% away from the *b* these images give. Two +independent signals, one of them nothing to do with our processing. The override replaces the +cell with the one DIALS 3.29 indexes de novo on this master and keeps the deposited space group +and resolution. + +### Four trigonal and tetragonal rows where we read a higher point group + +| PDB | Deposited | `rugnux` reads | Where it stands | +|---|---|---|---| +| 6TOC | P 42 | P 42 2 2 | both acceptable; the refinement test is not unanimous | +| 8XTE | P 32 | P 31 2 1 / P 32 2 1 | both acceptable; ours is the better supported | +| 8XTG | P 32 | P 31 2 1 / P 32 2 1 | both acceptable; the **deposition** is the better supported | +| 6PXB | P 32 | P 31 1 2 / P 32 1 2 | both acceptable; unresolved in either direction | + +All four accept either answer: the deposited group and the one we read both pass. None of them +is a claim that the deposited assignment is wrong - each is a question we cannot close, and 8XTE +and 8XTG do not lean the same way, so they should not be read in one voice. The two 8XT* rows +were for a time scored against our own answer by editing the reference itself, with no reason +recorded; the deposition is back in `ref` verbatim and the disagreement is stated here. + +**6TOC.** The deposited asymmetric unit holds two chains, and they are related by the very +two-fold the higher group adds, to 0.16 A C-alpha RMSD over 43 residues - coordinate error at +the deposited 1.85 A. Merging in P 42 2 2 costs 0.0006 in Rmeas for 1.75 +times the multiplicity, and correlates better with the deposited model than the P 42 +merge does. POINTLESS, run independently on our own P1 merge, reads the same point group. The +refinement test - refine in each candidate group and compare R-free, which is the one comparison +not biased toward the group the deposited model was refined in - does **not** come out +unanimous: ZANUDA 1.097 makes P 42 2 2 the better group at half the parameters and +reports the deposited assignment incorrect, while an independent Refmac 5.8.0431 comparison on a +symmetry-consistent free set makes P 42 the better one, by less than the spread +between refinement protocols - the spread of the test exceeds the effect it is being asked to +measure. Both answers are therefore accepted, with the refinement evidence recorded as split. + +**8XTE.** The distinguishing test is the twin-immune centric zone: reflections that the higher +group makes centric but the subgroup does not are their own twin mates, so a merohedral twin law +cannot make them read centric. They read `<|E^2-1|>` = 0.946 +/- 0.012 against a centric +expectation of 0.968 and an acentric one of 0.736. Re-refinement on a shared free set, with the +twin law removed from both sides, favours the higher group. The deposited entry's published R +values are themselves reproducible only with a twin law the entry does not declare, at a twin +fraction of 0.50 - and a 0.50-twinned target already has the symmetry in question. Of the four +rows this is the one where the evidence most clearly favours what we read; it still cannot be +closed, because the centric zone is the only test that speaks to it (see the limit below), so +both answers are accepted. + +**8XTG.** This row is genuinely open and is flagged as such in the manifest. Every +correlation-based instrument we have - our own operator correlations, and POINTLESS on our P1 +merge - reads the higher point group, but the centric-zone test, the only one of them that can +separate real symmetry from pseudo-symmetry, reads `<|E^2-1|>` = 0.869 at -44.9 nats: between +the two expectations, and on the wrong side. The L-test indicates a twin fraction near 0.20-0.26. +Whether this crystal is partially twinned or purely pseudo-symmetric has not been established. +Here the better-supported answer is the deposited one, which is the opposite of 8XTE: the two +rows look alike in the table and are not alike in the evidence. Both answers are accepted. + +**6PXB.** Both answers accepted rather than overridden, because the evidence does not settle +either way. Our +merge and POINTLESS both read a 312 point group, the added two-folds correlate at or above the +level of the three-folds nobody disputes, and merging in the higher group *lowers* +Rmeas at twice the multiplicity. Against that, the deposited asymmetric unit's six +chains pair under the added two-fold at 0.3-0.7 A, which is more than coordinate error at 1.75 A, +and ZANUDA settles on a different trigonal supergroup - 321 rather than 312 - whose operators +these data do not support. Neither answer is established in either direction, so both are +accepted and the row still tests everything else about the set. + +### 9RCI: two defensible descriptions of one lattice + +This row is not about symmetry but about which cell describes the crystal. The Patterson +has an off-origin peak at 62.5% of the origin, so a genuine translational NCS relates the two +halves of the cell `rugnux` reports, and the deposited cell is that supercell's +(0, 1/2, 1/2)-centred sublattice to 0.17%. Both are correct descriptions of the same diffraction: +one leaves the near-translation in the contents of a doubled cell, the other absorbs it into the +lattice and indexes only the strong sublattice. Which one a program should prefer is a choice, +not a measurement, so the row accepts either. The alternative cell recorded in the manifest is +computed from the deposited cell alone (c' = b + 2c, centring removed), not copied from our +output, so it stays a statement about the deposition's lattice. + +### 6OWW: a monoclinic deposition whose intensities read tetragonal + +6OWW is deposited in P 1 21 1 with eight chains, on a cell with a ≈ b and β = 89.9°. +The deposited model nearly obeys the added operators: a four-fold to 0.13-0.16 Å and a two-fold +to 0.10 Å, and its |Fc|2 correlate across the added 422 operators at +0.97-1.00. POINTLESS reads Laue class 4/mmm both on our observations and on the depositor's +amplitudes, and ZANUDA, refining the deposited model in each candidate group, prefers +P 43 21 2 to P 21 on our data and on the depositor's, with lower +R-free each time. The row accepts P 41 21 2 (the enantiomorph pair is +counted as one by the scorer) beside the deposited group. As with the trigonal and tetragonal rows +above, an exact pseudo-symmetry would explain the same observations, so this is an accepted +alternative and not a statement that the deposition is wrong. + +### The limit that applies to all five symmetry rows + +A merohedral twin at a twin fraction of exactly 0.5 and a crystal that genuinely has the higher +symmetry predict **identical** intensities. No amount of data and no refinement R separates them, +and the same holds, approximately, for a pseudo-symmetry that is merely very exact. Every test +described above measures how nearly a symmetry operator holds on these images; none of them can +show that it holds exactly. Where the higher symmetry is right, merging in it gains multiplicity +and completeness; where it is a pseudo-symmetry that close, merging in it costs nothing +measurable either. That is why these rows are described as open questions, and why none of them +should be read as a statement that a deposited model is wrong. + +## Battery rows whose id is not the PDB code + +| Battery id | PDB code in the table | Why | +|---|---|---| +| `7brr` | 7D1M | The IRRMC archive and its DOI are published under 7BRR, which the PDB obsoleted on 2020-10-28 and replaced with 7D1M. The battery id, the directory and the DOI keep the archive's own name; the deposited values are 7D1M's. | +| `6h2p_native` | 6H2P | the 0.918 Å sweep of the 6H2P archive, which the deposition's resolution belongs to | +| `6h2p_1p89A` | 6H2P | the 1.893 Å sweep of the same crystal; scored on the deposited space group and cell only | + +## Datasets in the table that are not in the battery + +| PDB | Why | +|---|---| +| 7QT9 | Twenty 20° wedges (200 × 0.1°) of in-situ crystals at room temperature, none complete on its own: the dataset is a multi-sweep row (`7qt9_crystals`, below), not a single-sweep one. | +| 9VX7 | The uploaded sweep does not index in the deposited cell, with `rugnux` or with DIALS or XDS given that cell, while XDS indexes it de novo in a different cell; the deposited values cannot be scored against these images, so the row is not in the battery. | + +## An archive that ships placeholder images + +8AGQ's `data/` directory contains 30 files named `ForBackgroundOnly_000NN.img` alongside the +1800-frame sweep. They are not images: each is a 64-byte text file holding a path string. A +reader that globs `*.img` will pick them up, so they are named here rather than silently left. + +## Datasets with no PDB entry + +| Dataset | Repository record | Why there is no PDB code | +|---|---|---| +| `cuhf2` | Zenodo record 10.5281/zenodo.6347466 | a small-molecule dataset, not a PDB deposition | +| `dnba` | Zenodo record 10.5281/zenodo.1036416 | a small-molecule dataset, not a PDB deposition | +| `metformin` | Zenodo record 10.5281/zenodo.20135265 | a small-molecule dataset, not a PDB deposition | +| `nidppe` | Zenodo record 10.5281/zenodo.20041091 | a small-molecule dataset, not a PDB deposition | +| `cytidine` | Zenodo record 10.5281/zenodo.33555 | a small-molecule dataset, not a PDB deposition | +| `lalanine` | Zenodo record 10.5281/zenodo.11946282 | a small-molecule dataset, not a PDB deposition | +| `laspartic` | Zenodo record 10.5281/zenodo.15432050 | a small-molecule dataset, not a PDB deposition | +| `onitroaniline` | Zenodo record 10.5281/zenodo.7193538 | a small-molecule dataset, not a PDB deposition | + +Six of the eight small-molecule sets have a published structure to check a run against. These are +reference values from the literature, not results obtained here. + +| Dataset | Space group | Cell (A, deg) | T | Reference | +|---|---|---|---|---| +| `dnba` | `C 1 2/c 1` (15) | 20.2635 8.7575 9.6697 / 90 109.941 90 | 30 K | the Zenodo record's own title and the `xia2.html` the depositors ship inside it, corroborated by COD 4510614/4510615 - Cryst. Growth Des. **13** (2013) 1861-1871 [doi:10.1021/cg300906j](https://doi.org/10.1021/cg300906j) | +| `metformin` | `P 1 21/c 1` (14) | 7.9104 13.8794 7.9310 / 90 114.606 90 | 100 K | the hydrochloride, form I; COD 2108029 - Acta Cryst. B**73** (2017) 10-22 [doi:10.1107/S2052520616017844](https://doi.org/10.1107/S2052520616017844) | +| `nidppe` | `P 1 21/c 1` (14) | 11.2779 13.3386 15.8739 / 90 98.7953 90 | 150 K | COD 2012031 - Acta Cryst. C**57** (2001) 690-693 [doi:10.1107/S0108270101003961](https://doi.org/10.1107/S0108270101003961) | +| `cytidine` | `P 21 21 21` (19) | 13.98 14.788 5.119 / 90 90 90 | 296 K | β-cytidine; COD 2001311 - D. L. Ward, Acta Cryst. C**49** (1993) 1789-1792 [doi:10.1107/S0108270193003464](https://doi.org/10.1107/S0108270193003464) | +| `lalanine` | `P 21 21 21` (19) | 5.791 5.944 12.269 / 90 90 90 | 100 K | COD 2311261 - S. Parsons, H. D. Flack, T. Wagner, Acta Cryst. B**69** (2013) 249-259 [doi:10.1107/S2052519213010014](https://doi.org/10.1107/S2052519213010014) | +| `laspartic` | `P 1 21 1` (4) | 5.1237 6.9197 7.6006 / 90 100.442 90 | 150 K | twin fractions 0.537/0.463; COD 1577465 - M. Lutz, IUCrData **10** (2025) [doi:10.1107/S241431462500879X](https://doi.org/10.1107/S241431462500879X) | + +`onitroaniline` has no cell here: the letter describing it could not be retrieved when the row was +added, so a run on it is not scored against a reference. + +`cuhf2` has no confirmed cell. Its space group is published as `P 4/n m m` (Phys. Rev. B **81**, +064422 (2010) [doi:10.1103/PhysRevB.81.064422](https://doi.org/10.1103/PhysRevB.81.064422)) but no +numeric cell was located, so a run on it can be scored on the space group and not on the cell. + +## The collection in numbers + +The collection was chosen to widen the spread of file formats, detectors, facilities and +symmetries rather than to be easy to process. The counts below describe where it comes from; +like everything else on this page, they are metadata about the depositions and their files, not +measurements. + +- **Repository**, over the 212 datasets on this page (the 204 rows of the table and the eight + small-molecule sets): IRRMC 97, Zenodo 45, SBGrid 40, MXRDR 16, Keele University 5, XRDa 5, + ESRF 3, UQ eSpace 1. +- **Facility** - counted from the facility part of the Facility / beamline column, the beamline + ignored so that entries deposited with and without one count the same, over the 191 rows that + name one: APS 29, Diamond 22, ESRF 19, NSLS-II 14, PETRA III 13, BESSY 12, SSRL 11, ALS 9, + SLS 8, SPring-8 8, SOLEIL 7, SSRF 7, PAL/PLS 5, CHESS 4, ALBA 3, Australian Synchrotron 3, + CLSI 3, ELETTRA 2, LNLS 2, MAX IV 2, NSLS 2, Photon Factory 2, and one each from NSRRC, + RRCAT Indus-2, SRS Daresbury and EMBL/DESY Hamburg (DORIS) - 26 facilities. The other thirteen + rows were collected on laboratory sources: eleven on rotating anodes, one on a liquid-metal jet + and one on a sealed tube. +- **Crystal system, from the deposited space group of the 204 rows:** monoclinic 54, + orthorhombic 51, tetragonal 30, trigonal 22, hexagonal 20, cubic 14, triclinic 13. +- **Pink beam:** none of these datasets was collected with pink beam. All 204 rows are deposited + as `SINGLE WAVELENGTH` (`_diffrn_radiation.pdbx_diffrn_protocol`), and all but 5REO, which + leaves the field blank, as monochromatic (`pdbx_monochromatic_or_laue_m_l` `M`); 9Q41 is the + one row recorded with a multilayer rather than a crystal monochromator (CHESS Rh/B4C). The + battery's pink-beam data are in-house SLS measurements (tag `pink-beam` in + `tools/battery/inhouse.json`), not on this page. +- **Long cell axes:** sixteen rows have a deposited cell axis longer than 320 Å - 4P8R, + 4MTK, 7D98, 8V4O, 9ZMU, 9V16, 9Z72, 4NWV, 9YL4, 5NW5, 6QAJ, 7QIJ, 8T7R, 9H0Q, 6G1F and 6OEL. + +The marCCD, SMV, Bruker `.sfrm`, full-imgCIF and gzip-compressed miniCBF datasets are the reason rugnux reads those formats +natively, and accepts the `.img` and numeric-suffix (`.001`) file names they arrive with. + +## Licences + +Each dataset carries the licence of its own deposition, stated on the record page linked +above. IRRMC and the SBGrid Data Bank both release under CC0 and both ask that the dataset's +own citation - its DOI - be used; the Zenodo records here are CC0 or CC BY 4.0, as each +record states. None of these data are redistributed with Jungfraujoch; this page only records +where they came from. diff --git a/_sources/EXTERNAL_TEST_DATA_STILLS.md.txt b/_sources/EXTERNAL_TEST_DATA_STILLS.md.txt new file mode 100644 index 000000000..d9e62a2f7 --- /dev/null +++ b/_sources/EXTERNAL_TEST_DATA_STILLS.md.txt @@ -0,0 +1,87 @@ +# External test data: serial crystallography (XFEL stills) + +The serial datasets of the still battery (`tools/battery/still_battery.py`, manifest +`tools/battery/still_manifest.json`). Like the rotation sets on +[External test data](EXTERNAL_TEST_DATA.md), they were collected by other people, on detectors and in +file formats we do not produce ourselves, and published for exactly this kind of reuse. All of them +come from the [Coherent X-ray Imaging Data Bank](https://cxidb.org) (CXIDB). They are the eleven +datasets of the Rugnux paper's Extended Data Table 2, which gives the published results on them. + +**None of these data were collected by us.** If you use any of them, cite the dataset DOI below and +the paper of the entry. + +## Where the values come from + +- **Dataset DOI**: the CXIDB entry's own DOI, resolved against DataCite before it was written down. +- **Space group, cell, resolution and R-free** are the values deposited with the PDB entry, read from + the RCSB data API. Every entry is a dark or ground state refined against observed data. +- **Images used** are the frames in the files we use, counted in the files themselves. Where that is + only part of the entry, the table says so and gives what the entry or the deposition holds. + +## Datasets + +| Set | CXIDB, dataset DOI | Facility / beamline | Detector, format | PDB | Space group, dmin (Å) | Paper | +|---|---|---|---|---|---|---| +| `sacla243` | [243](https://cxidb.org/id-243.html), [10.11577/17003933](https://doi.org/10.11577/17003933) | SACLA BL2 | MPCCD, 8 panels of 1024 x 512, 50 µm; Cheetah-SACLA HDF5 | [31JT](https://www.rcsb.org/structure/31JT) | P 2 21 21, 1.63 | Bibi, De Vrieze et al., J. Am. Chem. Soc. (2026) | +| `sacla237` | [237](https://cxidb.org/id-237.html), [10.11577/2999572](https://doi.org/10.11577/2999572) | SACLA BL2 | MPCCD; Cheetah-SACLA HDF5 | [9S06](https://www.rcsb.org/structure/9S06) | P 21 21 21, 2.05 | Rios-Santacruz et al., Nature (2026) | +| `sacla236` | [236](https://cxidb.org/id-236.html), [10.11577/3014306](https://doi.org/10.11577/3014306) | SACLA BL2 | MPCCD; Cheetah-SACLA HDF5 | [9V3D](https://www.rcsb.org/structure/9V3D) | P 43 21 2, 1.68 | Kang et al., J. Appl. Cryst. (2026) | +| `pal86` | [86](https://cxidb.org/id-86.html), [10.11577/1502065](https://doi.org/10.11577/1502065) | PAL-XFEL NCI | Rayonix MX225-HS, 1440 x 1440, 156 µm; Cheetah CXI | [6IG7](https://www.rcsb.org/structure/6IG7) | P 61 2 2, 1.80 | Park et al., Sci. Rep. (2019) | +| `pal90` | [90](https://cxidb.org/id-90.html), [10.11577/1511590](https://doi.org/10.11577/1511590) | PAL-XFEL NCI | Rayonix MX225-HS; Cheetah CXI | [6IRK](https://www.rcsb.org/structure/6IRK) | I 2 2 2, 1.75 | Lee et al., Sci. Rep. (2019) | +| `lcls222` | [222](https://cxidb.org/id-222.html), [10.11577/2204603](https://doi.org/10.11577/2204603) | LCLS MFX | Rayonix MX340-HS, 1920 x 1920, 177 µm; LCLS-I XTC | [8TDQ](https://www.rcsb.org/structure/8TDQ) | P 65 2 2, 1.65 | Nguyen et al., J. Am. Chem. Soc. (2023) | +| `lcls242_s`, `lcls242_t` | [242](https://cxidb.org/id-242.html), [10.11577/3374214](https://doi.org/10.11577/3374214) | LCLS MFX | Rayonix MX340-HS; LCLS-I XTC | [9O4S](https://www.rcsb.org/structure/9O4S) (small cell), [9O4T](https://www.rcsb.org/structure/9O4T) (large cell) | P 1 21 1, 1.95 | Wolff et al., bioRxiv (2026) | +| `euxfel83` | [83](https://cxidb.org/id-83.html), [10.11577/1464102](https://doi.org/10.11577/1464102) | European XFEL SPB/SFX | AGIPD 1M, 16 modules of 512 x 128, 200 µm; Cheetah CXI | [6GTH](https://www.rcsb.org/structure/6GTH) | P 32 2 1, 1.69 | Wiedorn et al., Nat. Commun. (2018) | +| `euxfel152` | [152](https://cxidb.org/id-152.html), [10.11577/1660970](https://doi.org/10.11577/1660970) | European XFEL SPB/SFX | AGIPD 1M; Cheetah CXI | [6U57](https://www.rcsb.org/structure/6U57) | I 2 3, 2.80 | Echelmeier et al., Nat. Commun. (2020) | +| `alvra103_int16` | [103](https://cxidb.org/id-103.html), [10.11577/1650020](https://doi.org/10.11577/1650020) | SwissFEL Alvra | JUNGFRAU 16M, 75 µm; SwissFEL HDF5, float32 keV (converted) | [6S0L](https://www.rcsb.org/structure/6S0L) | C 2 2 21, 2.65 | Nass et al., IUCrJ (2020) | +| `alvra213_int16` | [213](https://cxidb.org/id-213.html), [10.11577/2282689](https://doi.org/10.11577/2282689) | SwissFEL Alvra | JUNGFRAU 4M, 75 µm; SwissFEL HDF5, float32 keV (converted) | [8BKH](https://www.rcsb.org/structure/8BKH) (dark state) | P 1 21 1, 1.35 | Barends et al., Nature (2024) | + +Every set of the manifest is in the table and every set in the table is in the manifest, with the +same CXIDB entry, PDB entry, space group and dmin; `tools/battery/doc_check.py` checks +this. The beamline of `pal90` is the CXIDB entry's (NCI); the PDB entry 6IRK records CSI. + +## How the battery runs them + +Each set is one rugnux command, the way a serial user runs: the deposited cell and space group given +(`-C`, `-S`), the wavelength where the files do not state it, `--crystfel-geometry` for the AGIPD and +JUNGFRAU sets (the geometry file of the entry; the SACLA, PAL and LCLS files are placed without one), +and the deposited model with `--model`, so that the report carries its R-free against the merge. The +exact arguments are the `args` of each set in `tools/battery/still_manifest.json`; the +[stills section of the tutorial](RUGNUX_TUTORIAL.md#still--serial-data) explains them. + +## The files we use + +Paths are relative to the still data root of the site config (`tools/battery/README.md`). CXIDB +serves `https://cxidb.org/data//...`; most of it accepts HTTP range requests, so a +broken download resumes with `curl -C -`. + +| Set | Files | Images used | Of the entry | Size | +|---|---|---|---|---| +| `sacla243` | `sacla_243/raw_all/run*.h5`: all 87 files of `243/Complete_dark/` | 52,151 | all (the deposition's 52,151) | 198 GB | +| `sacla237` | `sacla_237/raw/`: the 18 files `run130637-0` to `run130642-2` of `237/SACLA_raw/2022Nov/dark_ref/` | 10,792 | **subset**: 18 of about 1,000 `dark_ref` files, about 1.8% of ~600,000 hits | 48 GB | +| `sacla236` | `sacla_236/raw/`: the 18 files `run157084-0` to `run157089-2` of `236/Data/lyso01-apo-bigXtal/` | 16,083 | all (the deposition's 16,083) | 67 GB | +| `pal86` | `pal_86/raw/`, `pal_86/raw_more/`: `CXIDB_86_themolysin_{2..25}_SFX_Nam.cxi` (file 1 is truncated on the server and cannot be opened) | 49,193 | all but file 1 (24 of 25 files) | 111 GB | +| `pal90` | `pal_90/raw/`: `CXIDB_90-GI_SFX-filter-r00{01..14}-c00.cxi` | 79,805 | all 14 filtered files of the entry | 159 GB | +| `lcls222` | `lcls_222/xtc/`, `lcls_222/xtc_more/`: `mfx/mfxlu5017/xtc/e1277-r0165-{s00-c00,s00-c01,s01-c00,s01-c01,s02-c00}.xtc` (run 165, the substrate-bound state of 8TDQ) | 8,534 | **subset**: run 165 of the runs 165-168 behind 8TDQ | 72 GB | +| `lcls242_*` | `lcls_242/xtc/`, `lcls_242/xtc_more/`: `xtc/mfxl1013721-r0256` to `r0267` streams (the two crystal forms are in every run; each set keeps its own form) | 82,388 | **subset**: runs 256-267 (47 of about 220 stream files; ~570 GB of ~3 TB) | ~570 GB | +| `euxfel83` | `euxfel_83/raw/`: the 30 Cheetah hit files `XFEL-r0243-c00.cxi` to `XFEL-r0292-c00.cxi` (runs 243-254, 270-276, 278-281 and 286-292, the `r-blac/XFEL-r-c00.cxi` of the entry's `cheetah-calib-mar-v1/hdf5/` tree on the NERSC archive); `euxfel_83/ref/agipd_mar18_v10.geom` from the entry | 14,445 | all (the deposited stream's 14,445) | 25 GB | +| `euxfel152` | `euxfel_152/raw/`: all 221 Cheetah hit files `XFEL2042-r0099-c00.cxi` to `XFEL2042-r0420-c00.cxi` of `XFEL2042-runs-cxi.tar` (extracted with range requests on the tar members); `euxfel_152/ref/kdo_embedded.geom`, the geometry embedded in the header of the entry's `KDO8PS.stream` | 33,528 | all the hit files of the entry's tar; the deposited stream has 37,006 frames | 53 GB | +| `alvra103_int16` | `swissfel_103/conv/run*_int16.h5`: int16 copies (see below) of 59 runs of the entry's `Raw_Files//a2a/run.JF06T32V01.h5`, `run9` to `run67` of 2018-08-07 and `run1` to `run3` of 2018-08-08 (named `run0808_1` to `_3`); `swissfel_103/ref/jf-16M.geom` and the pixel mask `swissfel_103/ref/run47.JF06T32V01.mask.h5` from the entry; the set reads `swissfel_103/ref/jf-16M_mask.geom`, a copy with `mask_file` pointed at that mask (see below) | 53,734 | **subset**: 59 runs of two days; the deposition indexed 199,136 of 2,251,787 images | 172 GB of copies | +| `alvra213_int16` | `swissfel_213/conv/march_dark_MbCO_II-March-06/data/dark/run_*_int16.h5`: int16 copies (see below) of `swissfel_213/raw/march_dark_MbCO_II-March-06/data/dark/run_*.JF06T08V01.h5`, from `march/march_dark_MbCO_II-March-06.tar.gz` (425 GB; download it to disk and extract, a streamed extraction does not survive a broken connection); `swissfel_213/ref/mbco_march.geom` from the JUNGFRAU geometry template of `2019-MARCH-SwissFEL-MbCO-supplement.tar.gz`; the pixel mask of run 243 (`data/pixel_mask/` in the same tarball) is used for all runs, through `swissfel_213/ref/mbco_march_mask.geom`, a copy with `mask_file` pointed at it (see below) | 28,428 | all 23 dark runs with frames of the March 2019 series | 46 GB of copies (430 GB of source) | + +**The masks of the SwissFEL geometry files.** rugnux takes the pixel masks and bad regions a CrystFEL +geometry file names. The SwissFEL files name their mask with an absolute path on the facility's disk, +so each set reads a copy whose `mask_file` is relative to the copy's own directory (a relative mask +file is looked for in the working directory first, as CrystFEL does, then beside the geometry file): +`swissfel_103/ref/jf-16M_mask.geom` is `jf-16M.geom` with `mask_file = run47.JF06T32V01.mask.h5`, and +`swissfel_213/ref/mbco_march_mask.geom` is `mbco_march.geom` with +`mask_file = ../raw/march_dark_MbCO_II-March-06/data/pixel_mask/run_000243.JF06T08V01.mask.h5`. Only +that line differs. + +**The `_int16` sets.** The SwissFEL files store converted JUNGFRAU data as uncompressed float32 keV, +68 MB (JF16M) or 17 MB (JF4M) a frame, which caps reading at about 74 or 295 frames/s at 5 GB/s. The +`_int16` sets are copies with the same layout in which `/data/data` holds whole photons (keV divided +by the photon energy, rounded) as int16 with bitshuffle/LZ4, about 25 times smaller. The battery runs only the +copies: they merge to the same numbers as the float32 originals (rugnux measures the gain from the +frames), and the originals are kept only as the source of the conversion and as a test of the format. Make them with +`tools/battery/still/float32_to_int16.py ` (h5py and hdf5plugin), +into `swissfel_103/conv/` (4.57 keV) and `swissfel_213/conv/` (12.037 keV, keeping the tarball's +directory tree), named `_int16.h5`. One MbCO dark run (`run_000238`) holds no frames and has no copy. diff --git a/_sources/FPGA.md.txt b/_sources/FPGA.md.txt new file mode 100644 index 000000000..1a4a0c9b4 --- /dev/null +++ b/_sources/FPGA.md.txt @@ -0,0 +1,83 @@ +# FPGA smartNIC + +See separate document for [installation instructions](DEPLOYMENT.md). + +## Hardware +Currently supported FPGA is only **Xilinx Alveo U55C**. + +See AMD/Xilinx webpage for [card user guide (UG1469)](https://docs.xilinx.com/r/en-US/ug1469-alveo-u55c). +According to the user guide: +``` +Alveo data center accelerator cards are designed to be installed into a data center server, where controlled air flow provides direct cooling. +``` + +The card needs to be placed in a PCI Express (PCIe) Gen4 x8 slot, though mechanically slot has to accommodate x16 card. +There is no need to connect additional power cable, as power of the card is not exceeding 75 W load available from PCIe edge connector. +Current power estimation is about 30 W when idle and 45 W in operation. The card has built-in protection, which will cut power to the card if HBM temperature is above 120°C. + +Two variants of the card are available: +* `100g` - this variant operates one port in 100 Gbit/s mode and should be used when connecting detector via a switch. +* `8x10g` - this variant operates both QSFP ports at 4x10 Gbit/s. QSFP+ (40 Gbit/s) transceivers and MTO/MTP harness cables +are necessary. It is designed for detector directly connected to the Jungfraujoch server, without switch. + +See [network documentation](FPGA_NETWORK.md) for details of network. + +## Building firmware +The firmware build targets are generated by CMake only when `vivado` and `vitis_hls` are detected in +the path, and the Vivado version has to match the one below precisely. + +### Xilinx Vivado +The following procedures require having AMD (Xilinx) Vivado and Vitis HLS toolsets version **2022.2** installed on the machine. +Due to the nature of TCL scripts used to generate board designs Vivado version has to exactly match one provided above - +specifically newer versions of Vivado will not work. + +In addition to the Intellectual Property (IP) cores included in Vivado, two additional licenses are necessary: +* Non-cost license for Ultrascale+ 100G core has to be requested from AMD/Xilinx website, see [Xilinx website](https://www.xilinx.com/products/intellectual-property/cmac_usplus.html), to build `100g` design. +* A paid license for the 10G/25G Ethernet Subsystem for Ultrascale+ is necessary to build the `8x10g` design. +PSI received non-cost licenses from Xilinx University Program for the latter cores. Therefore, usage of bitstreams +generated by PSI continuous integration pipeline for `8x10g` is only allowed for non-commercial use. + +### HLS compilation +Make HLS routines: +``` +mkdir build +cd build +cmake .. +make hls +``` + +### Synthesis +Create PCIe `100g` bitstream with the following command: +``` +mkdir build +cd build +cmake .. +make pcie_100g +``` +and `8x10g`: +``` +mkdir build +cd build +cmake .. +make pcie_8x10g +``` +### When Vivado is not present + +During CMake execution, the following executables: `vivado` and `vitis_hls` must be present in the path. +If not, build targets will not be generated, and such or similar error message will show up: +``` +$ make pcie_100g +make: *** No rule to make target 'pcie_100g'. Stop. +``` + +### Firmware releases +The firmware is stable and is carried from version to version: the MCS files attached to a release +are normally the ones from the release before it (see [Release contents](RELEASE_CONTENTS.md)). When +it does need to change, it is rebuilt with the targets above on a machine with Vivado. + +## Frame generator + +The Jungfraujoch card is equipped with a frame generator. It allows simulating a JUNGFRAU detector without having access to such a system. +It sits in parallel with the Ethernet MAC, so it is placed before the network stack and before any processing happening on the card. +In the future a redirection will be possible to send the simulated stream through the 100G TX network link. +Frame generator is written in HLS and controlled with AXI-Lite. \ No newline at end of file diff --git a/_sources/FPGA_DATA_ANALYSIS.md.txt b/_sources/FPGA_DATA_ANALYSIS.md.txt new file mode 100644 index 000000000..23738a0af --- /dev/null +++ b/_sources/FPGA_DATA_ANALYSIS.md.txt @@ -0,0 +1,89 @@ +# FPGA data analysis + +Jungfraujoch FPGA design has incorporated X-ray diffraction image analysis capabilities. + +## Pixel mask +Pixels can be masked. For each module a 32-bit map of pixels is loaded to FPGA, with non-zero value meaning masked pixels. +According to this map, pixels will be assigned a special value (minimum number for signed types and maximum number for non-signed types) +and will be excluded from subsequent analysis. + +## ADU histogram +Before conversion to photons/energy, an ADU histogram can be calculated for a module. This allows to preserve some signature +of unconverted values. This is done on a module-basis and works with bins with 32 ADU width. + +For EIGER this can be used as just a histogram procedure. + +## JUNGFRAU conversion +For JUNGFRAU, module images are converted from ADUs to an energy value and divided by a given number to give units of keV. +Result of the operation is rounded to integers. + +## Pixel thresholding +Pixel range can be specified. +Pixels below a minimum threshold will be assigned zero. +Pixels above a maximum threshold will be assigned saturated pixel value (the largest number for a given bit-width and sign type). +This is specifically designed to operate on unsummed frames, so frame-specific parameters (overload/noise) can be handled. + +## Frame summation +Frames can be summed together (on a per-module basis) in Jungfraujoch, with a limit of 256 frames added together. + +## Azimuthal integration +To implement azimuthal integration, FPGA is able to sum pixels based on a provided integration map and per-pixel corrections. +This way Jungfraujoch implements azimuthal integration with solid angle and polarization corrections. +Corrections were implemented according to formulas developed by [Jensen et al. (J. Synchrotron Rad., 29, 1420-1428, 2022)](https://journals.iucr.org/s/issues/2022/06/00/fv5148/). + +Given FPGA limitations, split-pixels cannot be implemented and number of bins is limited to 2048 per detector module. +This way 2D azimuthal integration, as needed for example by SAS-TT, cannot be currently implemented with the FPGA card and needs to be done on a CPU. +One needs to be careful with per-pixel corrections - their acceptable range is constrained by 16-bit fixed point integer implementation +and is tuned for standard SAXS/WAXS range. + +As with ROIs, azimuthal integration is also available on CPU through the shared analysis library, +so it applies to both the FPGA-accelerated (JUNGFRAU/PSI) and the DECTRIS-driven (EIGER) workflows. + +## Spot finding +Jungfraujoch FPGA implements a built-in spot finder. Spot finder allows to apply the following criteria for finding strong pixels: +1. Resolution criterion - pixels only within a provided resolution range can be considered as strong pixels (calculating resolution map needs to happen on CPU before data collection run). +2. Bad pixels - pixels marked as bad, as well as chip edges and module edges are excluded from spot finding, +3. Overloads - pixels marked as overloads on JUNGFRAU are always included in the strong pixel output, but are excluded for signal-to-noise ratio calculation, +4. Pixel value - pixels above certain threshold value can be marked as strong, +5. Signal-to-noise (SNR) ratio - pixels with SNR above a threshold can be marked as strong, +6. Connected pixels - strong pixels can be discarded if they are "alone", so their 8 directly neighboring pixels are not counted as strong pixels. + +All the above criteria except the bad-pixel criterion are optional (can be turned off); only pixels that fulfill all enabled criteria are selected as strong pixels. + +### SNR ratio calculation +Signal-to-noise ratio is calculated for a rectangular area. +In horizontal direction the area is fixed - line of 1024 pixels is divided into 32 areas each of 32 pixels. +This is dictated by the data flow within the FPGA. +In vertical direction the area is flexible - it is 15 lines above and below of the given pixel. +Given the very large box size, approximations are made, for example that `N ≈ N-1` in calculating standard deviation. + +## Region-of-interest (ROI) integration +There are 16 ROIs, and the ROI map holds a 16-bit mask per pixel, so a pixel can belong to any subset of them (including none). For each ROI, sum, sum of squares, max count, and number of valid pixels will be calculated. +Jungfraujoch also calculates X and Y values weighted by pixel values, though this feature is not properly tested at the moment and not integrated in downstream analysis. + +ROIs are not specific to the FPGA path. The same ROI definitions — box, circle, and azimuthal +(Q-range with an optional φ-sector) — are also evaluated on CPU by the shared `image_analysis/roi/` +engine, so ROI statistics are produced both for the FPGA-accelerated JUNGFRAU/PSI workflow and for +detectors driven through DECTRIS SIMPLON (e.g. EIGER), which have no FPGA acquisition path. + +## Pixel statistics +The following statistics are collected for each module: +* Number of masked pixels +* Number of saturated pixels (excl. masked) +* Number of error pixels (excl. masked) +* Sum of valid pixels in the module +* Minimum value of valid pixels in the module +* Maximum value of valid pixels in the module + +Valid pixels are not masked, not saturated, not error pixels. + +These are not specific to the FPGA path: the CPU and GPU image preprocessors of the shared +`image_analysis/` library collect the same statistics per image, for detectors driven through +DECTRIS SIMPLON (e.g. EIGER) and for rugnux. There the sum excludes only the device mask (detector and +calibration), not the hot pixels, the beam-stop shadow and the inactive pixels a run finds on its own frames. + +## Square root compression +Jungfraujoch FPGA includes lossy compression preserving counting statistic properties of X-ray image, while reducing bit width of an image. +Scheme was described in [Wakonig et al., J. Appl. Cryst., 53, 574-586, 2020](https://doi.org/10.1107/S1600576720001776). +Pixel value `X` is replaced with `round(sqrt(N*N*X))`, i.e. `round(N*sqrt(X))`, where `N` is integer constant in range 1 to 16. +`N` is what the host writes to the `sqrtmult` register; the FPGA squares it before multiplying the pixel value. diff --git a/_sources/FPGA_DESIGN.md.txt b/_sources/FPGA_DESIGN.md.txt new file mode 100644 index 000000000..be7e1285c --- /dev/null +++ b/_sources/FPGA_DESIGN.md.txt @@ -0,0 +1,22 @@ +# FPGA data flow + +The following steps are performed on FPGA (in the order of operation): + +1. UDP header decoding +2. SLS detector header decoding +3. State machine that controls data acquisition (start/stop/cancel) +4. High-bandwidth memory cache to buffer network packets and reorder them to form full modules +5. ADU histogram for JUNGFRAU +6. Mask pixels from missing packets with special value +7. Reorder lines for EIGER to form a proper module +8. Mask pixels based on provided pixel mask +9. JUNGFRAU conversion with gain and pedestal corrections +10. Threshold: pixel values below a set minimum are zeroed, values above a set maximum saturated +11. Frame summation (up to 256 frames) +12. Integration according to predefined map (e.g., 1D azimuthal integration) +13. Spot finding +14. ROI calculation +15. Image lossy compression using N*sqrt(pixel) values +16. Send images, analysis results and metadata to host memory via PCI Express + +Each step has a dedicated core, written in high-level synthesis. Exact operation of cores for data analysis is explained in dedicated [document](FPGA_DATA_ANALYSIS.md). \ No newline at end of file diff --git a/_sources/FPGA_LICENSE.md.txt b/_sources/FPGA_LICENSE.md.txt new file mode 100644 index 000000000..540a96050 --- /dev/null +++ b/_sources/FPGA_LICENSE.md.txt @@ -0,0 +1,295 @@ +# FPGA license + +FPGA components of Jungfraujoch are licensed using OHL-S license. See full text below. +The license is equivalent of GNU Public License with adaptations for hardware. +See [OHL webpage](https://ohwr.org/project/cernohl/-/wikis/Documents/CERN-OHL-version-2) for details and FAQs. + +## CERN Open Hardware Licence Version 2 - Strongly Reciprocal + + +Preamble + +CERN has developed this licence to promote collaboration among +hardware designers and to provide a legal tool which supports the +freedom to use, study, modify, share and distribute hardware designs +and products based on those designs. Version 2 of the CERN Open +Hardware Licence comes in three variants: CERN-OHL-P (permissive); and +two reciprocal licences: CERN-OHL-W (weakly reciprocal) and this +licence, CERN-OHL-S (strongly reciprocal). + +The CERN-OHL-S is copyright CERN 2020. Anyone is welcome to use it, in +unmodified form only. + +Use of this Licence does not imply any endorsement by CERN of any +Licensor or their designs nor does it imply any involvement by CERN in +their development. + + +1 Definitions + +1.1 'Licence' means this CERN-OHL-S. + +1.2 'Compatible Licence' means + +a) any earlier version of the CERN Open Hardware licence, or + +b) any version of the CERN-OHL-S, or + +c) any licence which permits You to treat the Source to which + it applies as licensed under CERN-OHL-S provided that on + Conveyance of any such Source, or any associated Product You + treat the Source in question as being licensed under + CERN-OHL-S. + +1.3 'Source' means information such as design materials or digital +code which can be applied to Make or test a Product or to +prepare a Product for use, Conveyance or sale, regardless of its +medium or how it is expressed. It may include Notices. + +1.4 'Covered Source' means Source that is explicitly made available +under this Licence. + +1.5 'Product' means any device, component, work or physical object, +whether in finished or intermediate form, arising from the use, +application or processing of Covered Source. + +1.6 'Make' means to create or configure something, whether by +manufacture, assembly, compiling, loading or applying Covered +Source or another Product or otherwise. + +1.7 'Available Component' means any part, sub-assembly, library or +code which: + +a) is licensed to You as Complete Source under a Compatible + Licence; or + +b) is available, at the time a Product or the Source containing + it is first Conveyed, to You and any other prospective + licensees + +i) as a physical part with sufficient rights and + information (including any configuration and + programming files and information about its + characteristics and interfaces) to enable it either to + be Made itself, or to be sourced and used to Make the + Product; or +ii) as part of the normal distribution of a tool used to + design or Make the Product. + +1.8 'Complete Source' means the set of all Source necessary to Make +a Product, in the preferred form for making modifications, +including necessary installation and interfacing information +both for the Product, and for any included Available Components. +If the format is proprietary, it must also be made available in +a format (if the proprietary tool can create it) which is +viewable with a tool available to potential licensees and +licensed under a licence approved by the Free Software +Foundation or the Open Source Initiative. Complete Source need +not include the Source of any Available Component, provided that +You include in the Complete Source sufficient information to +enable a recipient to Make or source and use the Available +Component to Make the Product. + +1.9 'Source Location' means a location where a Licensor has placed +Covered Source, and which that Licensor reasonably believes will +remain easily accessible for at least three years for anyone to +obtain a digital copy. + +1.10 'Notice' means copyright, acknowledgement and trademark notices, +Source Location references, modification notices (subsection +3.3(b)) and all notices that refer to this Licence and to the +disclaimer of warranties that are included in the Covered +Source. + +1.11 'Licensee' or 'You' means any person exercising rights under +this Licence. + +1.12 'Licensor' means a natural or legal person who creates or +modifies Covered Source. A person may be a Licensee and a +Licensor at the same time. + +1.13 'Convey' means to communicate to the public or distribute. + + +2 Applicability + +2.1 This Licence governs the use, copying, modification, Conveying +of Covered Source and Products, and the Making of Products. By +exercising any right granted under this Licence, You irrevocably +accept these terms and conditions. + +2.2 This Licence is granted by the Licensor directly to You, and +shall apply worldwide and without limitation in time. + +2.3 You shall not attempt to restrict by contract or otherwise the +rights granted under this Licence to other Licensees. + +2.4 This Licence is not intended to restrict fair use, fair dealing, +or any other similar right. + + +3 Copying, Modifying and Conveying Covered Source + +3.1 You may copy and Convey verbatim copies of Covered Source, in +any medium, provided You retain all Notices. + +3.2 You may modify Covered Source, other than Notices, provided that +You irrevocably undertake to make that modified Covered Source +available from a Source Location should You Convey a Product in +circumstances where the recipient does not otherwise receive a +copy of the modified Covered Source. In each case subsection 3.3 +shall apply. + + You may only delete Notices if they are no longer applicable to + the corresponding Covered Source as modified by You and You may + add additional Notices applicable to Your modifications. + Including Covered Source in a larger work is modifying the + Covered Source, and the larger work becomes modified Covered + Source. + +3.3 You may Convey modified Covered Source (with the effect that You +shall also become a Licensor) provided that You: + +a) retain Notices as required in subsection 3.2; + +b) add a Notice to the modified Covered Source stating that You + have modified it, with the date and brief description of how + You have modified it; + +c) add a Source Location Notice for the modified Covered Source + if You Convey in circumstances where the recipient does not + otherwise receive a copy of the modified Covered Source; and + +d) license the modified Covered Source under the terms and + conditions of this Licence (or, as set out in subsection + 8.3, a later version, if permitted by the licence of the + original Covered Source). Such modified Covered Source must + be licensed as a whole, but excluding Available Components + contained in it, which remain licensed under their own + applicable licences. + + +4 Making and Conveying Products + +You may Make Products, and/or Convey them, provided that You either +provide each recipient with a copy of the Complete Source or ensure +that each recipient is notified of the Source Location of the Complete +Source. That Complete Source is Covered Source, and You must +accordingly satisfy Your obligations set out in subsection 3.3. If +specified in a Notice, the Product must visibly and securely display +the Source Location on it or its packaging or documentation in the +manner specified in that Notice. + + +5 Research and Development + +You may Convey Covered Source, modified Covered Source or Products to +a legal entity carrying out development, testing or quality assurance +work on Your behalf provided that the work is performed on terms which +prevent the entity from both using the Source or Products for its own +internal purposes and Conveying the Source or Products or any +modifications to them to any person other than You. Any modifications +made by the entity shall be deemed to be made by You pursuant to +subsection 3.2. + + +6 DISCLAIMER AND LIABILITY + +6.1 DISCLAIMER OF WARRANTY -- The Covered Source and any Products +are provided 'as is' and any express or implied warranties, +including, but not limited to, implied warranties of +merchantability, of satisfactory quality, non-infringement of +third party rights, and fitness for a particular purpose or use +are disclaimed in respect of any Source or Product to the +maximum extent permitted by law. The Licensor makes no +representation that any Source or Product does not or will not +infringe any patent, copyright, trade secret or other +proprietary right. The entire risk as to the use, quality, and +performance of any Source or Product shall be with You and not +the Licensor. This disclaimer of warranty is an essential part +of this Licence and a condition for the grant of any rights +granted under this Licence. + +6.2 EXCLUSION AND LIMITATION OF LIABILITY -- The Licensor shall, to +the maximum extent permitted by law, have no liability for +direct, indirect, special, incidental, consequential, exemplary, +punitive or other damages of any character including, without +limitation, procurement of substitute goods or services, loss of +use, data or profits, or business interruption, however caused +and on any theory of contract, warranty, tort (including +negligence), product liability or otherwise, arising in any way +in relation to the Covered Source, modified Covered Source +and/or the Making or Conveyance of a Product, even if advised of +the possibility of such damages, and You shall hold the +Licensor(s) free and harmless from any liability, costs, +damages, fees and expenses, including claims by third parties, +in relation to such use. + + +7 Patents + +7.1 Subject to the terms and conditions of this Licence, each +Licensor hereby grants to You a perpetual, worldwide, +non-exclusive, no-charge, royalty-free, irrevocable (except as +stated in subsections 7.2 and 8.4) patent licence to Make, have +Made, use, offer to sell, sell, import, and otherwise transfer +the Covered Source and Products, where such licence applies only +to those patent claims licensable by such Licensor that are +necessarily infringed by exercising rights under the Covered +Source as Conveyed by that Licensor. + +7.2 If You institute patent litigation against any entity (including +a cross-claim or counterclaim in a lawsuit) alleging that the +Covered Source or a Product constitutes direct or contributory +patent infringement, or You seek any declaration that a patent +licensed to You under this Licence is invalid or unenforceable +then any rights granted to You under this Licence shall +terminate as of the date such process is initiated. + + +8 General + +8.1 If any provisions of this Licence are or subsequently become +invalid or unenforceable for any reason, the remaining +provisions shall remain effective. + +8.2 You shall not use any of the name (including acronyms and +abbreviations), image, or logo by which the Licensor or CERN is +known, except where needed to comply with section 3, or where +the use is otherwise allowed by law. Any such permitted use +shall be factual and shall not be made so as to suggest any kind +of endorsement or implication of involvement by the Licensor or +its personnel. + +8.3 CERN may publish updated versions and variants of this Licence +which it considers to be in the spirit of this version, but may +differ in detail to address new problems or concerns. New +versions will be published with a unique version number and a +variant identifier specifying the variant. If the Licensor has +specified that a given variant applies to the Covered Source +without specifying a version, You may treat that Covered Source +as being released under any version of the CERN-OHL with that +variant. If no variant is specified, the Covered Source shall be +treated as being released under CERN-OHL-S. The Licensor may +also specify that the Covered Source is subject to a specific +version of the CERN-OHL or any later version in which case You +may apply this or any later version of CERN-OHL with the same +variant identifier published by CERN. + +8.4 This Licence shall terminate with immediate effect if You fail +to comply with any of its terms and conditions. + +8.5 However, if You cease all breaches of this Licence, then Your +Licence from any Licensor is reinstated unless such Licensor has +terminated this Licence by giving You, while You remain in +breach, a notice specifying the breach and requiring You to cure +it within 30 days, and You have failed to come into compliance +in all material respects by the end of the 30 day period. Should +You repeat the breach after receipt of a cure notice and +subsequent reinstatement, this Licence will terminate +immediately and permanently. Section 6 shall continue to apply +after any termination. + +8.6 This Licence shall not be enforceable except by a Licensor +acting as such, and third party beneficiary rights are +specifically excluded. \ No newline at end of file diff --git a/_sources/FPGA_NETWORK.md.txt b/_sources/FPGA_NETWORK.md.txt new file mode 100644 index 000000000..c26c4c1a7 --- /dev/null +++ b/_sources/FPGA_NETWORK.md.txt @@ -0,0 +1,39 @@ +# FPGA network + +The U55C card is equipped with two network connectors - QSFP0 is the upper port and QSFP1 the lower port (when PCIe connector is on the bottom). +The card FPGA design is offered in two variants `100g` and `8x10g`. These have different behavior regarding the network: + +`100g` — this variant operates the QSFP0 port in 100 Gbit/s mode and should be used when connecting detector via a **switch**. +QSFP28 transceivers are necessary. + +`8x10g` — this variant operates both QSFP ports at 4x10 Gbit/s. QSFP+ (40 Gbit/s) transceivers and MTO/MTP harness cables +are necessary. It is designed for **detector directly connected** to the Jungfraujoch server, without switch. + +## Transceivers +AMD doesn't provide transceiver compatibility matrix for Alveo U55C. +In our experience operating the card we haven't seen issues with transceivers from various providers (FS.com, Mellanox, Finisar). +We have also successfully operated card with correct direct attach cables instead of fiber optics. Given the card doesn't +support link training functionality of 100 Gbit/s ethernet, it could result in performance problems with copper cables, though we haven't +encountered such a situation. + +## Switch configuration +Special care has to be taken for switch operation, given the FPGA core doesn't support auto-negotiation. It is necessary to configure switch port +to fixed speed (100 Gbit/s or 10 Gbit/s) and to disable auto-negotiation. It is also necessary to enable jumbo frames (MTU of 9000). + +## Network LEDs +Each QSFP connector is equipped with green and orange LEDs. These LEDs are connected to Ethernet physical layer status port (rx_status). +LED on corresponds to having a physical connection to a switch/computer/detector on the other side of the network. +For 100 Gbit/s only green is used, for 8x10 Gbit/s green LEDs mean all ports connected, orange LEDs at least one of the ports connected. + +## Network stack +Each Ethernet link has its own basic network stack. Functionality for Ethernet/ARP/IPv4/ICMP is therefore separately handled for each port. +Each link will get dedicated MAC address, and IPv4 addresses can be also assigned independently if needed. + +The card will send gratuitous ARP messages every 5 seconds to keep its entry in switch MAC table. +The card will also reply to ARP requests for its IP and to ICMP ping requests sent with the card IPv4 address. +The card won't respond to broadcast ICMP pings. + +Each link can be put in `direct` mode. In this case destination Ethernet MAC and IPv4 addresses are not enforced for incoming UDP packets. +This setting should be used for connecting detector modules directly to the FPGA card, so any detector module can be connected to any +10 Gbit/s link on the same card. Currently `direct` mode is turned OFF for `100g` design and ON for `8x10g` design. +This can be manually adjusted for each link. \ No newline at end of file diff --git a/_sources/FPGA_PCIE_DRIVER.md.txt b/_sources/FPGA_PCIE_DRIVER.md.txt new file mode 100644 index 000000000..c5f56f230 --- /dev/null +++ b/_sources/FPGA_PCIE_DRIVER.md.txt @@ -0,0 +1,103 @@ +# FPGA PCIe driver + +## Compilation +To compile the kernel module, type: +``` +make +``` + +## Installation +To install kernel module, you need to have root permissions and run: +``` +sudo make install +``` + +## Loading driver into kernel +After installing the kernel driver, it should be possible to insert it into the kernel via: +``` +modprobe jfjoch +``` + +## Ownership of the character devices +By default, character devices `/dev/jfjoch` are owned by root (user/group) and are not accessible by others. +This means that `jfjoch_broker` must be running as superuser, which might not be optimal for security reasons in most cases. +The behavior can be changed by creating `udev` rules. Create a file called `/etc/udev/rules.d/99-jfjoch.rules` +with the following content: +``` +KERNEL=="jfjoch*", OWNER="", GROUP="" +``` +It is OK to provide only group, for example to make the devices accessible by group `jungfrau`: +``` +KERNEL=="jfjoch*", GROUP="jungfrau" +``` + +## DKMS +To avoid problems with updating the kernel, it is possible to use DKMS to autobuild Jungfraujoch kernel +module, when new kernel is installed. For RHEL 8 it is well tested to use the RPM module built automatically from Jungfraujoch source. +For other systems, it is necessary to follow the procedure below, though it is not well tested. + +This first requires installing DKMS - for RHEL it is available via EPEL repository: +``` +sudo dnf install dkms +``` +Then use the script provided in the driver directory to copy driver code to DKMS directory: +``` +./install_dkms.sh +``` +If upgrading the driver, please first remove the current driver from DKMS system: +``` +dkms remove jfjoch -v --all +``` + +## Driver parameters +Currently, there is one driver parameter `nbuffers`, that defines count of exchange buffers (see below). +This can be adjusted in the modprobe operation, for example: +``` +modprobe jfjoch nbuffers=1024 +``` + +## Exchange buffers +The parameter defines number of buffers used to exchange data between card and host application. +Each buffer can hold one detector module (1024x512) in 16-bit or 32-bit mode + associated processing results and metadata. +These buffers are used by both card-to-host and host-to-card operations. + +Buffers use special allocation, as they are contiguous in physical address space, which helps the FPGA card to transfer all +data associated with detector module in two DMA transfers (one data, one metadata). +Useful buffer size is a bit more than 2 MiB, but given that kernel allocates physical memory in powers of two, **4 MiB** is a safe number for one buffer size. +A buffer can be mapped into user space by performing the `mmap` system call on the `/dev/jfjoch` character device. + +Buffer count can be adjusted by setting `nbuffers` parameter. There are two considerations for setting optimal value: +1. For card-to-host transfers, minimal value is roughly +` * `, +this way each thread can have enough data for operation. Default thread count for Jungfraujoch receiver is 64. +2. For host-to-card transfers, full detector calibration has to fit into memory and one buffer accommodates one calibration set for one module. +So minimal count is ` * (3 + 3 * )`. + +Based on both rules, optimal number is 512 buffers (2 GiB), though this can be adjusted for particular system and configuration. + +## Known problems +To avoid inconsistent behavior, this driver won't load if release number differs between the kernel driver and FPGA card. + +## CMake file +While CMake file is present in the driver directory, it is only for the purpose of proper detection of the files in CLion IDE. +It is not made for actual compilation of the kernel driver and should not be used for that purpose. + +## Character device access +For each FPGA device a character device is created called `/dev/jfjoch`. +When the device is opened, two operations are possible: +* `mmap()` to map exchange buffers +* `ioctl()` to communicate with the card +Interfacing should be done through the JungfraujochDevice class in `fpga/host_library` directory. + +## Sysfs access +Certain performance counters can be read through sysfs mechanism in the kernel. +One needs to `cat` files in `/sys/class/misc/jfjoch/` directory. + +## RHEL 9.5+ virtual memory flags +RedHat Enterprise Linux 9.5 backported the `vm_flags_set` interface from Linux kernel 6.3 while still reporting kernel version 5.14, so a plain kernel-version test picks the wrong branch and the build fails. +This is now detected automatically from `RHEL_RELEASE_CODE`, so the module builds unaided on RHEL 9.5 and later and on the CentOS Stream, Rocky and AlmaLinux equivalents, as well as on distributions that have not backported it. +**No user action is needed.** The `HAVE_VM_FLAGS_SET` environment variable that earlier releases required is obsolete; it is still honoured if set, but setting it is no longer necessary and the DKMS packaging never passed it anyway. + +## Which kernel DKMS builds for +The DKMS package builds the module for the kernel it is being **installed for**, not the one currently running, so a module built while a kernel update is being applied loads correctly after the reboot. +Building by hand in `fpga/pcie_driver/` still defaults to the running kernel; pass `KDIR=/lib/modules//build` (or `KVER=`) to target another one. diff --git a/_sources/FPGA_SETTINGS.md.txt b/_sources/FPGA_SETTINGS.md.txt new file mode 100644 index 000000000..079650630 --- /dev/null +++ b/_sources/FPGA_SETTINGS.md.txt @@ -0,0 +1,122 @@ +# FPGA advanced reference +## Register map +FPGA setup can be done via registers: + +| Address | Bits | Meaning | Mode | Notes | +|---------------------|------|------------------------------------------------------------------------------------------------|:-----|----------------------------------------------| +| 0x000000 - 0x00FFFF | | Reserved (in case using MicroBlaze in the future, this has to be reserved for internal memory) | | | +| 0x010000 | 32 | Action Control Register | | | +| | | Bit 0 - Action start | R/W | | +| | | Bit 1 - Action idle | R | | +| | | Bit 2 - Action cancel | R/W | cleared on reset or action start | +| | | Bit 3 - Clear network counters | R/W | cleared on reset | +| | | Bit 12:4 - Debug signals (see action_config.v for details) | R | | +| | | Bit 16 - AXI Mailbox interrupt 0 | R | | +| 0x010004 | 32 | Reserved | - | | +| 0x010008 | 32 | Reserved | - | | +| 0x01000C | 32 | GIT SHA1 | R | | +| 0x010010 | 32 | Reserved | R | | +| 0x010014 | 32 | Reserved | R | | +| 0x010018 | 32 | Jungfraujoch FPGA variant | R | | +| 0x01001C | 32 | Reserved | R | | +| 0x010020 | 32 | Max. number of supported detector modules | R | constant | +| 0x010024 | 32 | Reserved | R | constant | +| 0x010028 | 64 | Pipeline stalls before writing to host memory | R | reset on action start | +| 0x010030 | 64 | Pipeline stalls before accessing HBM | R | reset on action start | +| 0x010038 | 32 | FIFO status (see action_config.v for details) | R | | +| 0x01003C | 32 | Size of single HBM channel in bytes (default value for the particular card) | R/W | should not be altered for standard operation | +| 0x010040 | 64 | Packets processed by the action | R | cleared on reset or action start | +| 0x010048 | 64 | Valid ethernet packets | R | cleared on reset | +| 0x010050 | 64 | Valid ICMP packets | R | cleared on reset | +| 0x010058 | 64 | Valid UDP packets | R | cleared on reset | +| 0x010060 | 64 | Valid detector packets processed by the card | R | cleared on reset | +| 0x010068 | 64 | Packets flagged as errors by CMAC | R | cleared on reset | +| 0x010070 | 64 | Pipeline stalls before data processing | R | reset on action start | +| 0x010078 | 64 | AXI-beats before accessing HBM | R | reset on action start | +| 0x010080 | 64 | AXI-beats before data processing | R | reset on action start | +| 0x010088 | 64 | AXI-beats before host writer | R | reset on action start | +| 0x010090 | 64 | Last encountered SwissFEL pulse ID | R | cleared on reset | +| 0x010100 | 32 | Spot finder photon count threshold | R/W | | +| 0x010104 | 32 | Spot finder signal-to-noise ratio threshold (single-precision float) | R/W | | +| 0x010200 | 64 | MAC address source for internal frame generator | R/W | network byte order | +| 0x010208 | 32 | IPv4 address source for internal frame generator | R/W | network byte order | +| 0x01020C | 32 | Number of detector modules (value minus one: 0 => 1 module, 1 => 2 modules, etc.) | R/W | | +| 0x010210 | 32 | Data collection mode | R/W | | +| | | Bit 0 - Conversion to photons | | | +| | | Bit 1 - Output extend to 32-bit | | | +| | | Bit 2 - Output is unsigned integer | | | +| | | Bit 3 - Use sq. root lossy compression | | | +| | | Bit 7 - JUNGFRAU fixed G1 mode | | | +| | | Bit 8 - Set to zero values below threshold | | | +| | | Bit 31:16 - Data collection ID (carried with completions) | | | +| 0x010214 | 32 | Photon energy in keV (single-precision float) | R/W | | +| 0x010218 | 32 | Number of frames expected in the data collection (defines termination condition) | R/W | | +| 0x01021C | 32 | Number of storage cells | R/W | | +| 0x010220 | 32 | Summation on card (value minus one: 0 => summation of 1, 1 => summation of 2, etc.) | R/W | | +| 0x010224 | 32 | Coefficient for sq. root compression (need to set bit in data collection mode to apply) | R/W | | +| 0x010228 | 32 | Threshold minimum; values below are set to zero (need to set bit in data collection mode) | R/W | | +| 0x01022C | 32 | Threshold maximum; values above are set to the saturated value | R/W | | +| 0x030000 - 0x03FFFF | | AXI Mailbox for Work Request / Work Completion | | See Xilinx PG114 for register map | +| 0x040000 - 0x04FFFF | | QuadSPI flash | | See Xilinx PG153 for register map | +| 0x050000 - 0x05FFFF | | Interrupt controller | | See Xilinx PG099 for register map | +| 0x060000 - 0x06FFFF | | Load calibration (HLS) | | | +| 0x070000 - 0x07FFFF | | AXI Firewall | | See Xilinx PG293 for register map | +| 0x080000 - 0x08FFFF | | Frame generator (HLS) | | | +| 0x090000 - 0x09FFFF | | PCIe DMA control | | See Xilinx PG195 for register map | +| 0x0A0000 - 0x0AFFFF | | I2C clock generator | | See Xilinx PG090 for register map | +| 0x0C0000 - 0x0FFFFF | | Xilinx Card Management Solution Subsystem | | See Xilinx PG348 for register map | +| 0x100000 - 0x10FFFF | | MAC 10G / CMAC 100G | | See Xilinx PG210/PG203 for register map | +| 0x110000 - 0x11FFFF | | MAC 10G | | See Xilinx PG210 for register map | +| 0x120000 - 0x12FFFF | | MAC 10G | | See Xilinx PG210 for register map | +| 0x130000 - 0x13FFFF | | MAC 10G | | See Xilinx PG210 for register map | +| 0x140000 - 0x14FFFF | | MAC 10G | | See Xilinx PG210 for register map | +| 0x150000 - 0x15FFFF | | MAC 10G | | See Xilinx PG210 for register map | +| 0x160000 - 0x16FFFF | | MAC 10G | | See Xilinx PG210 for register map | +| 0x170000 - 0x17FFFF | | MAC 10G | | See Xilinx PG210 for register map | +| 0x200000 - 0x20FFFF | | Eth/IPv4 network stack for interface #0 | | | +| 0x210000 - 0x21FFFF | | Eth/IPv4 network stack for interface #1 | | | +| 0x220000 - 0x22FFFF | | Eth/IPv4 network stack for interface #2 | | | +| 0x230000 - 0x23FFFF | | Eth/IPv4 network stack for interface #3 | | | +| 0x240000 - 0x24FFFF | | Eth/IPv4 network stack for interface #4 | | | +| 0x250000 - 0x25FFFF | | Eth/IPv4 network stack for interface #5 | | | +| 0x260000 - 0x26FFFF | | Eth/IPv4 network stack for interface #6 | | | +| 0x270000 - 0x27FFFF | | Eth/IPv4 network stack for interface #7 | | | +| 0x400000 - 0x47FFFF | 64 | Address table: decodes handles used by load_calibration and host_writer to DMA addresses | | | + +## AXI Mailbox + +AXI mailbox is used to send work request from host to action, and receive work completions. +Messages are exchanged through AXI Mailbox IP from Xilinx (see Xilinx PG114). + +Work request has the following structure: + +| Bit start | Bit end | Meaning | +|-----------|---------|----------------------------------------------------| +| 0 | 15 | Work request ID (handle) | + +Work completion has the following structure: + +| Bit start | Bit end | Meaning | +|-----------|---------|----------------------------------| +| 0 | 15 | Work request ID (handle) | +| | | Special values: | +| | | 65534 - start of data collection | +| | | 65535 - end of data collection | +| 16 | 31 | Data collection ID | + +## HBM memory + +| Interface number | Core | Meaning | +|------------------|------------------|---------------------------------------------| +| 0-1 | jf_conversion | Gain factor G0 | +| 2-3 | jf_conversion | Gain factor G1 | +| 4-5 | jf_conversion | Gain factor G2 | +| 6-7 | jf_conversion | Pedestal G0 | +| 8-9 | jf_conversion | Pedestal G1 | +| 10-11 | jf_conversion | Pedestal G2 | +| 12-13 | integration | Integration map | +| 14-15 | integration | Integration weights | +| 16-17 | spot_finder_mask | Spot finder resolution | +| 18-19 | roi_calc | ROI calculation | +| 20-21 | frame_generator | Frame generator | +| 22-27 | load_from_hbm | Frame summation | diff --git a/_sources/GPU_DATA_ANALYSIS.md.txt b/_sources/GPU_DATA_ANALYSIS.md.txt new file mode 100644 index 000000000..82343dbdb --- /dev/null +++ b/_sources/GPU_DATA_ANALYSIS.md.txt @@ -0,0 +1,364 @@ +# GPU data analysis + +Jungfraujoch runs most of its crystallographic analysis on NVIDIA GPUs where one is present: the +per-image loop of `jfjoch_broker`, `jfjoch_viewer` and `rugnux`, and most of `rugnux`'s +dataset-level steps - the pre-scan, scaling and merging, model validation, molecular replacement and +refinement. +This page lists the GPU engines (all of them in `.cu` files under `image_analysis/`), with what each +computes. The methods themselves are described once, in the +[CPU/GPU data analysis](CPU_DATA_ANALYSIS.md) reference and its siblings, which each entry links to. + +**Every engine has a CPU counterpart** that computes the same thing, and the CPU-only build +(`JFJOCH_USE_CUDA=OFF`) runs the whole pipeline on it, the `ffbidx` indexer included (an in-tree +CPU port of the library's kernels). How closely the two agree is stated engine by +engine below and in the source: where the arithmetic is integer, or the order of every sum is fixed to +the host's, the result is the same to the bit; where the GPU uses float distances, cuFFT for FFTW, or a +different (fixed) summation order, the two agree to rounding. Every engine is deterministic on its +own - no floating-point atomics decide a result - so the same input gives the same output on every +run of a GPU build. + +## Getting the image onto the card + +- **Bitshuffle+LZ4 decoder** (`BSLZ4DecoderGPU.cu`) - decompresses the stored chunk on the device, so + only the compressed bytes cross PCIe, and un-transposes it straight into the preprocessing step. + The same pixels as the host decoder. The approach is Jon Wright's (ESRF). + [§0](CPU_DATA_ANALYSIS_IMAGE.md#0-getting-the-image-onto-the-gpu-device-side-decoding) +- **CBF byte-offset decoder** (`CBFDecoderGPU.cu`) - decodes a miniCBF `x-CBF_BYTE_OFFSET` stream on + the device into the same int32 pixels as the host decoder, refusing a stream that ends before the + image does. [§0](CPU_DATA_ANALYSIS_IMAGE.md#0-getting-the-image-onto-the-gpu-device-side-decoding) +- **marCCD frames** (`ImagePreprocessorGPU.cu`) - the stored 16-bit pixels are uploaded as they are + and widened to int32 on the card, inside preprocessing. + [§0](CPU_DATA_ANALYSIS_IMAGE.md#0-getting-the-image-onto-the-gpu-device-side-decoding) +- **Preprocessing** (`ImagePreprocessorGPU.cu`, `ImagePreprocessorBufferGPU.cu`) - applies the pixel + mask and flags error and saturated pixels, counting each and summing the rest, and keeps the + preprocessed image on the device for every engine below; on request it gathers the pixels of the + strong spots, or small squares around given positions, back to the host. Integer, so identical to the host. + [§1.6](CPU_DATA_ANALYSIS_IMAGE.md#16-defective-pixels) + +## Per image: profiles and spots + +- **Azimuthal integration** (`AzIntEngineGPU.cu`) - bins every pixel into its resolution (and + optionally azimuth) bin with the geometric corrections applied and sums them, as a radial profile. + Fixed-point sums, so the profile does not depend on the order the threads add in. + [§2](CPU_DATA_ANALYSIS_IMAGE.md#2-azimuthal-integration-radial-profiles) +- **ROI integration** (`ROIIntegrationGPU.cu`) - sums the pixels of user-defined detector regions of + interest (box, circle, azimuthal), each pixel feeding any subset of them, on the EIGER/CPU path where + the FPGA does not. Integer sums. [FPGA: ROI integration](FPGA_DATA_ANALYSIS.md#region-of-interest-roi-integration) +- **Local-statistics spot finder** (`ImageSpotFinderGPU.cu`) - flags strong pixels by their + signal-to-noise against a local box. [§3.1](CPU_DATA_ANALYSIS_IMAGE.md#31-strong-pixel-detection-by-local-statistics) +- **Adaptive spot finder** (`AdaptiveSpotFinderGPU.cu`) - reduces the image into resolution rings + once, and from that one pass gives both the azimuthal profile and each ring's robust background, + which sets the self-calibrating detection threshold; the result is intersected with the local test + above. [§3.2](CPU_DATA_ANALYSIS_IMAGE.md#32-adaptive-self-calibrating-detection) +- **Spot extractor** (`SpotExtractorGPU.cu`) - joins the flagged pixels into connected components and + sums each into a spot descriptor on the device, so only the spot list comes back. The same + components, in the same order, as the host labelling (the sparse formulation of the ACTS/traccc + project). [§3.4](CPU_DATA_ANALYSIS_IMAGE.md#34-connected-component-labeling-ccl) + +## Pre-scan accumulators + +These read a subset of the frames before processing starts, on every card at once, and are added +together across cards; their sums are integers, so the split of the frames between the cards changes +nothing. + +- **Beam-stop projection and mask** (`ShadowAccumulatorGPU.cu`, `ShadowMaskGPU.cu`) - accumulates the + per-pixel maximum, sum and count of the raw counts straight from the compressed frames, then draws + the beam-stop shadow mask from them, step for step as the host does. + [§1.5](CPU_DATA_ANALYSIS_IMAGE.md#15-finding-the-beam-stop) +- **Hot pixels** (`HotPixelsGPU.cu`) - per frame, the ring-sector and ring order statistics, the levels + made from them and the per-pixel counts of lit frames, from which persistently hot pixels are masked. + Exact order statistics and integer sums: the host's result to the bit. + [§1.6](CPU_DATA_ANALYSIS_IMAGE.md#16-defective-pixels) +- **Beam centre from the background** (`BeamCenterBackgroundGPU.cu`) - bins the usable pixels about + a trial centre and sums each cell, the two passes of the background-isotropy fit; the fit itself + stays on the host. [§1.4](CPU_DATA_ANALYSIS_IMAGE.md#14-the-beam-centre) +- **Beam centre by FFT** (`BeamCenterFFTGPU.cu`) - the self-convolutions that score every candidate + centre at once, their combination into one score surface, and the shortlist of its peaks, with only + the shortlist brought back. Runs on FFTW on the host instead where it would need more than half of + the card's total memory, decided before the card is touched and logged. + [§1.4](CPU_DATA_ANALYSIS_IMAGE.md#14-the-beam-centre) + +## Indexing + +- **FFT indexer** (`FFTIndexerGPU.cu`) - projects the spots' reciprocal-space vectors onto a dense set + of directions, histograms each projection and transforms it with cuFFT, 4096 directions at a time, + and picks each direction's most prominent lattice peak; the candidate vectors then go to the host's + lattice reduction. cuFFT gives the same bits at any batch size, so the batching changes nothing but + the memory held. A rotation run gives its indexers' memory back to the card once a pass has done its + last indexing. + [§5.1](CPU_DATA_ANALYSIS_INDEXING.md#51-directional-projections-and-histograms), + [§5.2](CPU_DATA_ANALYSIS_INDEXING.md#52-fft-peak-picking-and-candidate-vectors) +- **Fast-feedback indexer** (`ffbidx`) - third-party, from the fast-feedback-indexer project (PSI); a + known-cell indexer for serial stills, vendored in-tree (`image_analysis/indexing/fast-feedback-indexer/`). Its CPU counterpart is an in-tree port with + the same samples and scores, agreeing to rounding. + [§4.3](CPU_DATA_ANALYSIS_INDEXING.md#43-fast-feedback-indexing-known-unit-cell) + +## Prediction and integration + +- **Still prediction** (`BraggPredictionGPU.cu`) - the reflections of a lattice within the + excitation-error cutoff - or the window that follows the run's rocking curve, centred on its radial + scale - with their detector positions and per-reflection corrections. + [§8.2](CPU_DATA_ANALYSIS_INTEGRATION.md#82-still-prediction-excitation-error-cutoff) +- **Rotation prediction** (`BraggPredictionRotGPU.cu`) - the reflections crossing the Ewald sphere + within an image's rotation range, with their rotation angle and partiality; they are ordered, and + under a cap the best-recorded ones selected, on the device, in exactly the order the host gives. + [§8.3](CPU_DATA_ANALYSIS_INTEGRATION.md#83-rotation-prediction-laue-equation--partiality-model) +- **Bragg integration** (`BraggIntegrationEngineGPU.cu`) - for every predicted reflection: the + three-ring regions and neighbour ownership, box summation, the per-shell profile learned from the + strong spots and rebuilt per reflection, the radial background-curvature correction, and the profile + fit. The profile fit is in single precision on both engines, in the same arithmetic, so the two + differ only in summation order. + [§9.2](CPU_DATA_ANALYSIS_INTEGRATION.md#92-box-summation-seed-and-fallback), + [§9.3](CPU_DATA_ANALYSIS_INTEGRATION.md#93-profile-fitted-extraction-default) + +## Scaling and merging (rotation) + +One engine (`RotationScaleMergeGPU.cu`) keeps every observation resident on the card for the whole +scaling run; each per-group sum is a segmented reduction in a fixed order, so it is deterministic. +Whether the scaling runs there at all is decided before any observation is on the card, from the +card's total memory: a set whose sort alone, or whose scaling (estimated from its observation and +distinct-hkl counts once the sort has counted them), would take more than 80% of it scales on the CPU +instead, with a warning in the log (`RotationScaleMerge: ... scaling on the CPU instead`). Judged on the +total and not on what is free, the same input on the same card always takes the same path. + +- **Ingest** - the integrated reflections uploaded frame by frame, twice: first only what the sort and + the resolution cut need, then, once the scaling is known to fit, the observations the cut kept, + written straight to their place (the predicted detector positions stay on the host); the + frame flux applied; the sort into raw-hkl runs and the resolution cut; the recomputed rotation angles + (delta-phi), the rocking events relaid, and the partiality recomputed from the smoothed mosaicity. + The same sort and cut as the host, to the bit. + [§10.2](CPU_DATA_ANALYSIS_INTEGRATION.md#102-partiality-models), + [§10.6](CPU_DATA_ANALYSIS_INTEGRATION.md#106-rotation-datasets-combining-partials-into-fulls-3d-integration) +- **Per-frame scaling** (`ReduceGroupMeans`, `FitPerFrameG`, `UpdateCorr`, `SmoothCorr`, the zeta and + frame filters, `PerFrameCC`) - the reference intensity of every symmetry group, the per-frame scale + fitted against it, its smoothing over the sweep, and the per-frame correlation behind + `--min-image-cc`. [§10.1](CPU_DATA_ANALYSIS_INTEGRATION.md#101-observation-model), + [§10.3](CPU_DATA_ANALYSIS_INTEGRATION.md#103-smoothing-of-per-frame-scales) +- **Combine** - each reflection's partials summed into a full, with its capture fraction and + variance; then the fulls' own per-frame scale and its smoothing. + [§10.6](CPU_DATA_ANALYSIS_INTEGRATION.md#106-rotation-datasets-combining-partials-into-fulls-3d-integration) +- **Correction surfaces** - the decay, absorption and modulation surfaces' terms, their reference and + their least-squares sums over the fulls, on held-out subsets. + [§10.6](CPU_DATA_ANALYSIS_INTEGRATION.md#106-rotation-datasets-combining-partials-into-fulls-3d-integration) +- **Merge** - the inverse-variance merge (I(+)/I(-) and the mean), the half-sets for CC1/2, R_meas, + the per-group scatter, the anomalous (Bijvoet) excess and the error-model samples. + [§10.4](CPU_DATA_ANALYSIS_INTEGRATION.md#104-merging-estimator), + [§10.5](CPU_DATA_ANALYSIS_INTEGRATION.md#105-merging-statistics) +- **Error model** (`ErrorModelGPU.cu`) - the binned fit of the error model's a and b, the bin medians + identical to the host's; a and b can differ from the host fit in their last bits (summation order). + [§10.5](CPU_DATA_ANALYSIS_INTEGRATION.md#105-merging-statistics) +- **Wilson outliers** (`WilsonOutliersGPU.cu`) - the per-observation Wilson-statistics rejection, + the host's result to the bit. [§13.3](CPU_DATA_ANALYSIS_DECISIONS.md#133-outlier-rejection) +- **Pair sort** (`PairSortGPU.cu`) - sorts the (deviation, weight) pairs of the outlier test's + weighted median; the same sequence as `std::sort`. + [§13.3](CPU_DATA_ANALYSIS_DECISIONS.md#133-outlier-rejection) + +## Model validation + +The model's structure factors and the rigid body run on the card where there is one, every part +placed on it or on the CPU up front against one budget, 80% of the card's total memory +([§14.8](CPU_DATA_ANALYSIS_DECISIONS.md#148-rigid-body-placement-of-the-model)); the GPU and CPU +agree to rounding (float distances, cuFFT for FFTW, the crystal's symmetry composed in reciprocal +space instead of by symmetrizing the grid). On a machine with several cards, the rigid-body engines +the first card has no room for go on the others, each against its own budget. + +- **Model density** (`ModelDensityGPU.cu`) - the density of one copy of the model's atoms on a grid, + as a gather over bricks of the grid, bit-identical from run to run. + [§14.1](CPU_DATA_ANALYSIS_DECISIONS.md#141-model-structure-factors) +- **Bulk-solvent mask** (`ModelMaskGPU.cu`) - the solvent mask from every symmetry image of every + atom, with island removal and the shrink, as gemmi computes it - on the density's grid, or on one of its + own at 0.75 A where the density's is too coarse for the 0.8 A shrink to act. + [§14.2](CPU_DATA_ANALYSIS_DECISIONS.md#142-bulk-solvent-and-scaling) +- **Structure factors and maps** (`ModelStructureFactorsGPU.cu`) - F_calc and F_mask from the two grids + by cuFFT, composed over the group's operators and read off at the data's reflections; and the + inverse transform of map coefficients into maps. + [§14.1](CPU_DATA_ANALYSIS_DECISIONS.md#141-model-structure-factors), + [§14.4](CPU_DATA_ANALYSIS_DECISIONS.md#144-electron-density-maps) +- **Scale fit** (`ModelScaleGPU.cu`) - the sums of the overall-scale, anisotropic-B and bulk-solvent + fit over the reflections, in double and a fixed order, for many fits at once (the solvent grid, the + null replicates); the Levenberg-Marquardt control stays on the host. Used where its engine fits the + validation's budget, the CPU fit otherwise. + [§14.2](CPU_DATA_ANALYSIS_DECISIONS.md#142-bulk-solvent-and-scaling) +- **Rigid body** (`RigidBodyGPU.cu`) - the rigid-body target for a placement: the model moved, its + F_calc and mask, the scale, the residuals and their Jacobian; used for the placement itself and for + every replicate of the null. [§14.8](CPU_DATA_ANALYSIS_DECISIONS.md#148-rigid-body-placement-of-the-model), + [§14.5](CPU_DATA_ANALYSIS_DECISIONS.md#145-does-the-model-fit-the-null-it-is-scored-against) + +## Molecular replacement + +- **Molecular transform** (`MolecularReplacementGPU.cu`, `MapToFPhiGPU`) - the Fourier transform of + the search model's density in a large box, by cuFFT, where its buffers fit the search's budget (80% of + the card, the search holding nothing else yet), kept only as far out as it is read. +- **Rotation function** (`MolecularReplacementGPU.cu`) - for every trial orientation, the model's + intensities summed over the copies, normalised by resolution bin and correlated with the data's + normalised intensities. +- **Translation function** (`MolecularReplacementGPU.cu`) - for each orientation, the function over + every position in the cell, beside the copies already placed where there are any, and its mean, + spread and highest point. + +What of the search goes on the card is planned once per merge on the same budget as model +validation's, before the search starts +([§14.10](CPU_DATA_ANALYSIS_DECISIONS.md#1410-molecular-replacement-placing-a-model-the-rigid-body-cannot)). +On a machine with several cards, every other card holds a copy of the molecular transform where it +fits, the rotation and translation functions are split over the cards by orientation, and the +rigid-body engines are spread over them as in model validation; the result does not depend on how +many cards there are. + +The placements are then refined, scored and checked against their null with the rigid body and the +structure factors above; the likelihood scoring runs on the host. The search is described in +[§14.10](CPU_DATA_ANALYSIS_DECISIONS.md#1410-molecular-replacement-placing-a-model-the-rigid-body-cannot), its keys and decision rules in +[Molecular replacement](RUGNUX_REPORT.md#molecular-replacement). + +## Refinement + +The restrained refinement of a placed model ([§15](CPU_DATA_ANALYSIS_REFINEMENT.md)) evaluates its target and +its gradients on the card: one engine (`RefinementGPU.cu`, with the host half in `RefinementGPU.cpp`) keeps the +reflections, the grids, the symmetry and the restraints resident, and per evaluation takes only the atoms' +positions up and one value and one gradient per atom back. Everything that depends on the cell, the group and +the reflections - the grids, the operators, the adjoint's lists - is worked out once on the host with gemmi when +the engine is made. The GPU and CPU engines compute the same target to rounding (float distances and densities, +cuFFT for FFTW, summation order); the GPU's result is the same from run to run, as no sum of a result is a +floating-point atomic: every per-point, per-reflection and per-atom sum is a gather in a fixed order, and every +total a `cub::DeviceReduce` tree, whose order for a given size is fixed. + +One evaluation - target and gradient of every atom - is a density gather, a forward and an inverse transform +and a gradient gather, whatever the number of atoms +([§15.2](CPU_DATA_ANALYSIS_REFINEMENT.md#152-the-x-ray-target)): + +- **Density** (`ModelDensityGPU.cu`, the gather of model validation) - the atoms' blurred density of one copy + of the model on the structure-factor grid. The grid is cut into bricks of 8^3 points; each atom's box is + counted against the bricks it touches, the counts scanned (`cub::DeviceScan`) into a list of (brick, atom) + pairs, and the list sorted stably by brick (`cub::DeviceRadixSort`), so each brick holds its atoms in model + order. One block per brick then stages its atoms in shared memory (128 at a time) and every point adds, in + model order, each atom whose radius reaches it - no atomics, the grid the CPU walk's to the bit for the same + atoms. The pair count is the one wait inside an evaluation (it sizes the sort). The atoms' density + coefficients are uploaded again only where some atom's B changed; the positions go up through a pinned buffer. +- **Forward transform** - cuFFT r2c of the grid into its half-u spectrum, the plans made once per engine with an + explicit work area. +- **Composition and target** (`compose_target_kernel`, one thread per reflection) - F_calc of the reflection + composed from the spectrum over the group's operators (each operator's phase exp(2 pi i h.t) computed exactly + for the translation's fraction, sums in double), times the centring count and the unblur; then, on the working + reflections, F_model = k (F_calc + F_mask) with the macro-cycle's scale, mask and D, Σ held on the card, the + likelihood term -ln L of the reflection, and the coefficient conj(dT/dF) the derivative map is made of. + The terms are summed by `cub::DeviceReduce`. +- **Adjoint of the composition** (`scatter_kernel`, one thread per spectrum point) - the coefficients taken back + onto the half-u spectrum as a gather, not a scatter: a CSR list made on the host at setup gives, for every + spectrum point a (reflection, operator) term lands on, the terms in a fixed order, conjugated where they land + as a Friedel mate and doubled onto the planes k_u = 0 and k_u = nu/2, which hold their own mates. Each point + sums its terms in double and is written once. +- **Inverse transform** - cuFFT c2r of that spectrum into the derivative map, on the density's grid. +- **Atom gradient** (`atom_gradient_kernel`, one warp per atom) - each atom's dT/dx, dy, dz and dB: the derivative + map summed against the derivatives of the atom's five-Gaussian density over the same box and radius as the + gather, the warp's 32 lanes walking the box's points in steps of 32 without an integer division (the box index + stepped on, the wrap into the grid by one subtraction), and the lanes' sums added in a fixed shuffle tree. + The riding hydrogens' derivatives are passed to their parents on the host. + +Beside the X-ray target, and in the same submission: + +- **Restraints** (`restraint_kernel`, one thread per restraint) - bonds, angles, torsions, chirals, planes (up to + 32 atoms), repulsions (with their symmetry image), metal links and B similarity + ([§15.5](CPU_DATA_ANALYSIS_REFINEMENT.md#155-geometry-metal-and-b-restraints)), each restraint writing its + energy and its gradient into one slot per atom it involves; the energies summed by `cub::DeviceReduce`. +- **Slot gather** (`slot_gather_kernel`, one thread per atom) - each atom's restraint gradient, its slots summed + in the order a CSR list gives. Two restraint sets are held (positions and B), set again when the repulsions + and contacts are rebuilt. + +`EvaluateWithRestraints` queues the X-ray evaluation, writes the restraints' positions into a pinned buffer +while the card works on it, queues the restraints behind it and waits once; the target, the restraint energy +and both gradients come back into pinned buffers. The minimiser (L-BFGS) stays on the host. + +Once per macro-cycle ([§15.3](CPU_DATA_ANALYSIS_REFINEMENT.md#153-scale-bulk-solvent-and-the-likelihood-parameters)): + +- **F_calc and F_mask** - the forward path above without the target, and the bulk-solvent mask drawn on the card + (`ModelMaskGPU.cu`) on **its own fine grid** (d_min/3 or 0.4 A, whichever is finer, at most 2^26 points but never coarser than 0.75 A nor than the + density's grid), + with a grid, spectrum and cuFFT plan of its own where that grid is not the density's: one block per + (atom, symmetry image) sets the points within the atom's REFMAC radius, the islands are removed by a + union-find labelling (integer `atomicCAS`, rooted at each component's lowest index, so the partition does not + depend on the order of the unions), and the shrink is two passes - the edge points marked, then each edge + point's stencil written as solvent. Every write is an idempotent store, so the mask is the same bit for bit + from run to run; F_mask is read off at the reflections (`fmask_kernel`). +- **Robust scale fit** (`ModelScaleGPU.cu`) - the k_sol/B_sol grid of fits, each fit's overall scale and + anisotropic B by gemmi's Levenberg-Marquardt, many fits per launch: the sums over the reflections (the WSSR, + J^T J and J^T r, in double) by a fixed launch shape of 48 blocks of 128 threads, a fixed shuffle tree within + each warp and the blocks summed in order; the damping and the 7x7 solve stay on the host. The fine pass is + robust: four rounds of residuals, weights 1/sqrt(1 + (r/c)^2) and the fit again, with c the median residual + of the first round found **on the card** by a radix select (`residual_median`: the residuals are not negative, + so their order is that of their bits, found a byte at a time in four passes of integer counts - the element + `std::nth_element` puts at n/2). After a trial's first macro-cycle the fit starts from the fine pass around the + previous winner, skipping the coarse one. The fits go in batches of at most 32 (the coarse pass's 88 in three, in + grid order; a fit's sums do not depend on the others in its batch), and the robust weights take the residuals' + place, so the engine holds about 300 bytes per reflection. Its stream has the card's highest priority, so that the fit's short, + host-waited launches do not queue behind the long kernels of the other trials on the card. +- **D and Σ**, the likelihood's parameters, are fitted on the host (bin by bin, on all of the run's threads). + +**Trials, cards and waits.** The weight trials of one set +([§15.7](CPU_DATA_ANALYSIS_REFINEMENT.md#157-the-weights-decided-by-trial)) run side by side, each on a slot of +its own - a copy of the model, its topology and a refinement engine - as many slots as the +largest set of trials has (six at the defaults), the ones beside the main one built on +their own threads while the placement runs. The slots' engines go on the cards in +turn from the main one's, each card taking engines while they fit its budget, so the first slots are on cards of +their own and on a machine with several cards the trials are spread over all of them. The engines on one card +share what does not change - the setup worked out on the host, the reflections' tables, the adjoint's lists and +the phase table - and the bulk-solvent mask's buffers (`RefinementGPUCard`). The working buffers of a transform - +the grid, its spectrum, cuFFT's work area, the mask's own grid and spectrum - come in lanes (`RefinementGPULane`): +a slot has a lane of its own where the card holds one more, and shares the least used lane otherwise, its engine +taking the lane's lock from its launches to their wait (an evaluation, F_calc, F_mask), so the lane runs one +evaluation after another while its other slots do their host work - the minimiser, the gradients, the restraint +lists. Lanes side by side keep a card busier (two evaluations at once on a T4 cost 9% more each than one); slots +sharing a lane overlap more host work. The slots on a card share its scale-fit engine too, a fit waiting for the +one before it. A slot whose engine cannot be made is left out rather than moved to the +CPU, and the outcome does not depend on how many trials run at once or on which card. The engine waits on its +stream through an event made with `cudaEventBlockingSync` (`StreamWaiter`), so a waiting trial sleeps instead of +spinning a core - with six engines on one card the spinning took half of the refinement's CPU time. + +**Memory.** `RefinementGPUEngine::DeviceBytes` counts the engine's reserve before anything is allocated: per atom +(positions, boxes, densities, mask atoms, gradients), per reflection (scales, the row model, F_calc, F_mask, +coefficients, terms), the gather's pair reserve - sized for every atom at the largest B a refinement may +reach with the widest blur - and the restraints: the records and gradient slots of the model's two restraint sets +as the refinement starts (the geometry with its repulsions and NCS restraints, and the B restraints), a quarter more +for the contacts that come and go. `RefinementGPUEngine::CardBytes` counts the part the engines on a card share +(the tables, the adjoint's lists, the phases and the mask's buffers), `LaneBytes` a lane. The engine goes on the +card when the two, the scale-fit engine and what is already resident there (a merge still at work), are within +80% of the card's total memory (with a lane); the trial slots are counted against the same budget, card by card - +each one its engine's own part and a lane where both fit, else its engine's part alone, the first one on another +card also the shared part and a scale-fit engine. On a large model (510k atoms with riding hydrogens, 3.1M +reflections to 2.1 Å) an engine's own part is 2.0 GB, a lane 1.5 GB, the shared part 1.7 GB and the scale-fit +engine 0.9 GB: a 16 GB card takes three slots (three lanes; two where 80% of it is 12.5 GB), a 24 GB card five. + +**Falling back.** Where the GPU cannot take the case (an atom's box wider than the cell, more than 192 mask +operators), where the engine is over the budget, or where CUDA fails while the +engine is made, the refinement runs on the CPU engine, with a line in the log (`Refinement: on the CPU - ...`). +`--no-gpu` and a build without CUDA take the CPU engine as well. The refinement has no Metal engine: on macOS it +runs on the CPU. + +**Indicative timings** (RTX 5080, `-N 8`, the refinement alone): a 5,000-atom model (half of it riding +hydrogens) at 1.65 A with 31k reflections refines in about 1.3 s; a 4,500-atom model at 1.09 A with 92k +reflections in about 2 s; a 50,000-atom model at 3.6 A with 51k reflections in about 7 s, of which the kernels +take 5 s - there the density gather and the atom gradient (about 0.9 and 0.8 ms per evaluation, over a thousand +evaluations) are half or more of the kernel time, the scale fit 10-25% (more at high resolution) and the fine +mask 15-18% at low resolution. Inside a full `rugnux --model` run of a 5,000-atom model the refinement took +1.5 s of 8 s. The CPU engine (`-N 8`) takes about a minute and a half for a set the card refines in about 2 s. + +## Apple GPUs (Metal) + +A macOS build has no CUDA, and three engines run on the Apple GPU instead (none under +`rugnux --no-gpu`; where the GPU fails, the CPU takes over with a warning): + +- **Bragg integration** (`BraggIntegrationEngineMetal.mm`, `.metal`) - the CPU engine with its + pixel work moved to the GPU: the neighbour mask, the ownership of shared pixels, the box + summation's walk over every reflection, the background clip and the single-precision profile fit. + Everything computed in double and the profile learning stay on the CPU, as Apple GPUs have no + double precision. The fit's Gaussian uses an exp of our own (`BraggExp.h`) on both, as no GPU exp + matches the CPU's. The same result as the CPU engine **to the bit**, which a macOS CI step checks on + every push; `rugnux --no-gpu` keeps it off the GPU, and so does `--background-trim`, whose trimmed + mean has no Metal kernel. + [§9.2](CPU_DATA_ANALYSIS_INTEGRATION.md#92-box-summation-seed-and-fallback) +- **Model density** (`ModelDensityMetal.mm`, `.metal`) - the density of the model's atoms on a grid, + for model validation and molecular replacement, as a gather over bricks of the grid as under CUDA; + the same grid as the CPU's **to the bit**. + [§14.1](CPU_DATA_ANALYSIS_DECISIONS.md#141-model-structure-factors) +- **Molecular-replacement rotation function** (`MolecularReplacementMetal.mm`, `.metal`) - the + rotation function's trial orientations scored from a copy of the molecular transform; equal to the + CPU's to rounding. + [§14.10](CPU_DATA_ANALYSIS_DECISIONS.md#1410-molecular-replacement-placing-a-model-the-rigid-body-cannot) diff --git a/_sources/HARDWARE.md.txt b/_sources/HARDWARE.md.txt new file mode 100644 index 000000000..2b9eee8c1 --- /dev/null +++ b/_sources/HARDWARE.md.txt @@ -0,0 +1,63 @@ +# Hardware requirements +Operating Jungfraujoch requires the following: + +1. High performance server +2. FPGA board(s) installed in the server +3. (optionally) GPU boards +4. (optionally) 100G switch to connect FPGA and the detector + +Unfortunately, at the moment it is not possible to purchase server configuration from a major vendor that would include +AMD FPGA boards. Therefore, the two have to be purchased separately. This might have impact on the warranty for the hardware +and has to be clarified with the vendor. PSI only supports the system on the best effort basis and doesn't take any responsibility +for warranty limitations for operating FPGA boards in the server. Having said this - we didn't encounter any hardware issues so far. + +## High performance server +PSI is using HPE DL380 Gen11 servers at the moment to operate Jungfraujoch systems. However, this is because of general +preference for this vendor, there is no Jungfraujoch-specific reason to buy from this vendor. We do expect that system +from any other vendor with similar specification should work as well. + +At PSI, the configuration of HPE DL380 Gen11 used to operate 9M pixel detectors at 2 kHz is as follows: +* 2 x Intel Xeon 8558P +* 512 GB RAM +* 2 x Nvidia L4 GPU (for indexing) +* 1 x Nvidia ConnectX-6 200G ethernet/IB network (for outgoing traffic; this can be substituted according to facility needs) +* Copper 1G/10G network + +### PCI slots +When ordering the system, check that it can accommodate enough PCIe cards. +In case of our system we need to put at least seven PCIe cards: 4 x FPGA, 2 x GPU, 1 x network. + +Note - for FPGA x8 lane electrically/x16 lane mechanically PCIe slots are OK. + +## FPGA +Jungfraujoch is built for [AMD/Xilinx U55C](https://www.amd.com/en/products/accelerators/alveo/u55c/a-u55c-p00g-pq-g.html) +(A-U55C-P00G-PQ-G) card. Other FPGA cards are currently not supported. + +Single U55C card supports roughly 5 detector modules (2.5M pixels) at 2 kHz and 10 detector modules (5M pixels) at 1 kHz. +For detectors operating at lower frame rates (e.g., 100 Hz) larger detectors can be supported by a single U55C card, though it requires +using TX delay functionality in the detector. + +## GPUs +Running the fast-feedback indexer at the detector's frame rate requires a graphics processing unit from Nvidia +(without one it runs on the CPU, at a much lower rate). +For practical reasons, i.e. power consumption and cost, we chose the inference-grade Nvidia L4 card. +In the past we have also used T4 cards. So, in principle any recent CUDA compatible GPU should work. +The server that runs Rugnux live on the EIGER2 16M at PXII-X10SA (the beamline test of the Rugnux +paper) has two Xeon 8558P and four L4 cards. + +Offline processing with [`rugnux`](RUGNUX.md) has a requirement of its own, unrelated to the frame +rate the acquisition side is sized for: one run wants 3-7 GB on the card and up to 14 GB of host +RAM, so a server that also reprocesses data needs headroom beyond the online pipeline's. The +sizing table is in [Installing Rugnux ▸ Memory](RUGNUX_INSTALL.md#memory). + +## Network switch +Small detectors (up to 4M pixel) can be in principle operated without switch. In this case one needs `8x10g` variant +of the Jungfraujoch FPGA image, which allows 4 JUNGFRAU modules (two 10 Gbit/s links each) to be connected directly to one U55C card. + +Such configuration is however +impractical for larger systems or more complex deployments, like multiple detectors operated from one Jungfraujoch server. +In this case one needs a network switch. + +We currently use Nvidia/Mellanox SN2100 switch, though there is no reason not to use other models/other vendors. +A switch with only 100G ports must support splitting them into 4x10G ports to connect the detector. + diff --git a/_sources/HDF5.md.txt b/_sources/HDF5.md.txt new file mode 100644 index 000000000..ddbc515dd --- /dev/null +++ b/_sources/HDF5.md.txt @@ -0,0 +1,690 @@ +# HDF5 / NeXus data format + +Jungfraujoch stores images and on-the-fly analysis results in HDF5 files that aim to be +[NXmx](https://manual.nexusformat.org/classes/applications/NXmx.html)-compliant. On top of the +NXmx application definition, Jungfraujoch records a substantial amount of *derived* metadata +(spot finding, indexing, integration, azimuthal integration, per-image statistics, timing). These +extra entries do not exist in NXmx and are documented here so that the layout is unambiguous and +reusable. + +This page documents the **file layout and the data fields**. The operational behaviour of the +writer (running, republishing, file finalisation) is described in +[jfjoch_writer](JFJOCH_WRITER.md). The wire format that feeds the writer is described in +[CBOR messages](CBOR.md); fields below frequently correspond one-to-one to CBOR message fields, and +that document is a useful companion for their meaning. + +```{contents} On this page +:local: +:depth: 2 +``` + +## 1. Motivation: derived metadata and FAIR data + +The goal of Jungfraujoch is not only to store high-throughput datasets efficiently, but to keep +them findable, accessible, interoperable and reusable (FAIR). Jungfraujoch is used for both +**rotation** macromolecular crystallography (single- and multi-crystal, including fine-sliced and +helical scans) and **serial** crystallography (stills, grid scans); the same concerns apply to both: + +* **Findability.** Raw diffraction images carry almost no descriptive metadata about *content*. + Quantities such as background level, number of diffraction spots, or indexing outcome let a user + judge the quality and relevance of a dataset *before* inspecting the raw images. +* **Accessibility at scale.** A single experiment can span tens to hundreds of terabytes. Standard + retrieval (e.g. HTTP) makes a dataset *available* but not *inspectable* — users would otherwise + have to download a large fraction of the data just to decide whether it is useful. Compact + derived representations make discovery, assessment and reuse feasible. + +Because Jungfraujoch couples acquisition with real-time analysis used to *steer* experiments, +transparency and reproducibility of that analysis matter. As a minimum the writer therefore +preserves spot-finding and indexing results together with the filters that were applied, and it can +retain an unbiased, down-sampled reference set of unfiltered images for validation and reuse. + +### Two complementary layouts: per-image spots vs. a reflection table + +Jungfraujoch stores analysis products in two shapes, matching how each is accessed. + +**Per-image spot finding / indexing.** Spot finding and indexing are inherently *image-centric* — +the natural query is "give me the spots for image *n*" — and this holds for serial stills and for +rotation frames alike. For these products Jungfraujoch adopts a layout similar to the +[Coherent X-ray Imaging (CXI) data bank](https://www.cxidb.org) (Maia, 2012) and the convention +understood by [CrystFEL](https://www.desy.de/~twhite/crystfel/): spot properties (position, +intensity, Miller index, …) are stored in fixed-size two-dimensional arrays indexed by image number, +with each image allocated room for up to a predefined maximum number of spots. These dense arrays +are addressed with ordinary HDF5 hyperslab reads, so the spots of a single image are retrieved +without traversing variable-length structures. The cost is some storage overhead for unused slots +(padded with sentinels), which is acceptable for the access pattern. + +**Integrated reflections.** Integrated intensities are naturally a *dataset-wide* table, which is +exactly the model of the NeXus +[NXreflections](https://manual.nexusformat.org/classes/base_classes/NXreflections.html) base class. +This fits rotation crystallography well, and Jungfraujoch uses NXreflections for its integration +results (see §4.2 below). We deliberately do *not* force spot finding/indexing into a single +experiment-wide table: across the hundreds of thousands of patterns typical of serial — or +fine-sliced rotation — experiments, that would require aggregating the whole experiment before the +spots of one image can be read. We encourage the community to develop standardised NeXus application +definitions for image-centric crystallography products that combine NeXus interoperability with the +access patterns and scale of modern high-throughput experiments. + +## 2. File layout + +A run is written as one **master file** plus, depending on the format, one or more **data files**: + +``` +_master.h5 # NXmx master file (metadata + links / virtual datasets) +_data_000001.h5 # data file: images + per-image analysis +_data_000002.h5 +... +``` + +The master file is produced by `writer/HDF5NXmx.cpp`; data files by `writer/HDF5DataFile.cpp` and +its plugins (`writer/HDF5DataFilePlugin*.cpp`). Files are written to a temporary `*..tmp` +name and renamed on successful close. + +Three master-file variants exist (set via `file_format`): + +| Format | Value | Master ↔ data linking | +|--------|:-----:|------------------------| +| **NXmxLegacy** | 1 | One external link in `/entry/data` per data file (`data_000001`, …). HDF5 1.8 compatible — works with Neggia/Durin XDS plugins and Albula 4.0. | +| **NXmxVDS** (default) | 2 | A single virtual dataset `/entry/data/data` spans all data files; spot finding, azimuthal integration and reflections are linked the same way. Requires HDF5 1.10 / Albula 4.1+. | +| **NXmxIntegrated** | 3 | No separate data files — images and all metadata live in one file. Equivalent in content to the VDS format. | + +In legacy/VDS mode, image-indexed analysis arrays live in the **data files** and are exposed in the +master file through external links or virtual datasets; in integrated mode they are written +directly into the single file. + +Images are stored chunked (one image per chunk) and compressed with bitshuffle + LZ4 or +bitshuffle + Zstd. Signed integer image datasets carry `INTx_MIN` as the HDF5 fill value (the +"masked / no-data" sentinel); unsigned ones are left at HDF5's own fill of 0, because every unsigned +code is a legitimate count. In the master's virtual dataset the fill is the error marker for both, +so a data file missing beside a VDS master reads as masked rather than as zero counts. + +> **Signed images and the Neggia XDS plugin.** Neggia dispatches on the size of the pixel in bytes +> and always casts to an unsigned type, consulting the signedness of the data only for the pixel +> mask. A **signed 16-bit** image is therefore read wrongly: a count of `-2` reaches XDS as `65534`, +> and the `-32768` error marker as `32768`. Signed 32-bit happens to degrade safely, because every +> negative value ends up above `INT32_MAX` and is mapped to `-1`. Use the Jungfraujoch XDS plugin, +> or the Global Phasing build of Durin, for signed data — see +> [Integration with MX data processing software](SOFTWARE_INTEGRATION.md). + +### Reprocessing output: `_process.h5` + +The offline reprocessing tool [`rugnux`](TOOLS.md) (`rugnux/rugnux_cli.cpp`) re-runs the +full analysis pipeline (spot finding, indexing, refinement, integration, scaling) on an existing +dataset and writes its results to a master file named **`_process.h5`**. This file uses the +**integrated** format, but instead of copying the images its `/entry/data/data` is a *virtual +dataset that links back to the original image files* (`hdf5_source_data` → +`NXmx::LinkToData_ProcessingVDS`). The result is a compact, self-describing companion file that +holds *all* the derived analysis (everything in §4, including the XFEL pulse IDs of §4.8 when the +input has them) plus a virtual view +of the raw images — without duplicating terabytes of data. + +This is a particularly FAIR-friendly artefact: it can be shared or archived alongside (or instead +of) the raw data to convey what is in a dataset and how it was processed, while the `/entry/data/data` +VDS still resolves to the original images when they are available. Where the input is anything but a +single HDF5 master it could link to (several masters read as one, CBF, XTC, CXI, ...), the file has no +`/entry/data/data` at all - only the per-image analysis, which `--mode scale` reads all the same. `rugnux` can also process +an equally-spaced *subset* of images (start/end/stride), producing a down-sampled reference set. + +## 3. NXmx-standard content + +The entries below are part of, or valid base classes for, the +[NXmx](https://manual.nexusformat.org/classes/applications/NXmx.html) application definition. +"NXmx" = listed in the application definition; "base" = a valid field of the relevant NeXus base +class (`NXdetector`, `NXsample`, `NXsource`) but not in the NXmx required/recommended subset. + +### `/entry` (NXentry) + +| Field | Std | Notes | +|-------|:---:|-------| +| `definition` | NXmx | value `"NXmx"` | +| `start_time` | NXmx | arming time | +| `end_time`, `end_time_estimated` | NXmx | approximate end time | + +File-level HDF5 attributes `file_name`, `file_time`, `HDF5_Version` are also set. + +### `/entry/source` (NXsource), `/entry/instrument` (NXinstrument) + +| Field | Std | Units | +|-------|:---:|-------| +| `source/name`, `source/type` | NXmx / base | | +| `source/current` | base | A | +| `instrument/name` | NXmx | | + +### `/entry/instrument/beam` (NXbeam) + +| Field | Std | Units | +|-------|:---:|-------| +| `incident_wavelength` | NXmx | angstrom | +| `incident_wavelength_spread` | NXmx | angstrom (only if polychromatic) | +| `total_flux` | NXmx | Hz | +| `incident_beam_size` | NXmx | m (two elements, x then y; written only when both beam sizes are given) | + +### `/entry/instrument/attenuator` (NXattenuator) + +| Field | Std | +|-------|:---:| +| `attenuator_transmission` | NXmx | + +### `/entry/instrument/detector` (NXdetector) + +| Field | Std | Units | +|-------|:---:|-------| +| `depends_on` | NXmx | → `transformations/translation` | +| `beam_center_x`, `beam_center_y` | NXmx | pixel (0.0 = centre of the first pixel, see [DETECTOR_GEOMETRY](DETECTOR_GEOMETRY.md)). The **PONI**, not the direct beam - see below | +| `distance` | NXmx | m | +| `count_time`, `frame_time` | NXmx | s | +| `sensor_thickness` | NXmx | m | +| `sensor_material` | NXmx | | +| `description` | NXmx | | +| `threshold_energy` | NXmx | eV (EIGER; written only for a single channel) | +| `x_pixel_size`, `y_pixel_size` | base | m | +| `serial_number` | base | | +| `bit_depth_readout` | NXmx | bit depth of the **stored image**, not of the detector electronics - see below | +| `saturation_value` | NXmx | highest valid value. Read inclusively by NXmx, by the DIALS `trusted_range` and by the XDS `OVERLOAD` parameter; a saturated pixel carries the value one above it | +| `underload_value` | NXmx | lowest valid value: `0` for an unsigned image, `INTx_MIN + 1` for a signed one | +| `flatfield_applied` | NXmx | | +| `pixel_mask`, `pixel_mask_applied` | NXmx | `pixel_mask` is `[y, x]`, hard-linked from `detectorSpecific/pixel_mask` | +| `countrate_correction_applied` | NXmx | | +| `countrate_correction_lookup_table` | NXmx | only when the detector sent one (DECTRIS) | +| `virtual_pixel_interpolation_applied` | NXmx | only when the detector reported it (DECTRIS) | +| `number_of_cycles` | base | frame-summation factor | + +#### Why `bit_depth_readout` is the image depth + +NXmx defines only `bit_depth_readout`, "how many bits the electronics record per pixel", and has no +field for the depth of the image actually stored. The two differ whenever summation is used: the +readout stays at the detector's native width while the summed image must be wider to hold the sum. + +Jungfraujoch writes the **stored image depth** into `bit_depth_readout` (and the identical value +into the non-standard `bit_depth_image`). The electronic value is a constant of the detector and +tells a data consumer nothing, whereas readers do use `bit_depth_readout` as the width of the +stored pixel — DIALS, for instance, derives its masking markers from it and cannot read a 32-bit +image without it. Writing the electronic value there would therefore mislead exactly in the case +where the two differ. + +Note that `bit_depth_readout` gives the width only. The **sign** is carried solely by the HDF5 +element type of `/entry/data/data` (and, on the wire, by `image_dtype`); there is no NXmx field for +it. + +### `/entry/instrument/detector/transformations` (NXtransformations) + +The NXtransformations *mechanism* (the `depends_on` chain, `transformation_type`, `vector`, +`offset` attributes) is standard. The axis **names** follow the PyFAI PONI convention chosen by +Jungfraujoch (see [DETECTOR_GEOMETRY](DETECTOR_GEOMETRY.md)): + +| Axis | Type | Units | Vector | Depends on | +|------|------|-------|--------|-----------| +| `rot3` | rotation | rad | `(0, 0, -1)` | `.` | +| `rot2` | rotation | rad | `(1, 0, 0)` | `rot3` | +| `rot1` | rotation | rad | `(0, -1, 0)` | `rot2` | +| `translation` | translation | m | unit vector along the sample→PONI direction | `rot1` | + +`/entry/instrument/detector/depends_on` is `translation`, and the module's `fast_pixel_direction`, +`slow_pixel_direction` and `module_offset` depend on it in turn. A chain is applied innermost-first, +so reading it outwards the detector is placed at its distance and beam centre and *then* tilted about +the sample — which is what makes a tilt pivot about the crystal rather than about the panel corner. +The `vector` values are in NXmx's **McStas** frame, which is Jungfraujoch's internal frame with x and +y negated. + +The beam centre is encoded in `translation` (its offset from the sample), not only in the +informational `beam_center_x`/`beam_center_y` fields. In a `_process.h5` written by Rugnux these axes +carry the **refined** detector geometry — the refined beam centre folds into `translation` and the +refined tilt into `rot1`/`rot2`/`rot3`; the broker writes the user-provided geometry unchanged. + +#### `beam_center_x`/`beam_center_y` is the PONI; `direct_beam_x`/`direct_beam_y` is the beam + +`beam_center_x`/`beam_center_y` is the **PONI** - the foot of the perpendicular dropped from the +sample onto the detector plane. On a tilted detector that is *not* where the undeflected beam lands: +the two points are `distance * tan(tilt) / pixel_size` apart, which is around 8 px on a real in-house +setup and grows with the distance. + +Most programs that ask for "the beam centre" mean the point the beam lands on - XDS's `ORGX`/`ORGY` +among them - so Jungfraujoch writes that point out as well: + +| Dataset | Units | +|---------|-------| +| `/entry/instrument/detector/detectorSpecific/direct_beam_x` | pixel | +| `/entry/instrument/detector/detectorSpecific/direct_beam_y` | pixel | + +They are computed from the same beam centre, distance and `rot1`/`rot2`/`rot3` written beside them, +so the file cannot disagree with itself; on an untilted detector they equal `beam_center_x`/`_y`. + +The *provenance* differs by which program wrote the file, though the field does not. In a master +written by `jfjoch_broker` the geometry is the one the user stated, so `direct_beam_x`/`_y` is a +statement about the user's geometry; in a `_process.h5` written by Rugnux it is the refined geometry, +so it is a measurement. A user handing either to XDS should know which of the two they have. + +### `/entry/instrument/detector/module` (NXdetector_module) + +Written for a detector whose image is one flat panel (e.g. an EIGER). A detector of several modules +(a JUNGFRAU image assembled by Jungfraujoch, or an input whose modules are known) is written as +`module_0`, `module_1`, ... instead (next section), with no whole-image `module` beside them: NXmx +readers such as DIALS/dxtbx take every `NXdetector_module` as one panel. + +`data_origin`, `data_size`, `fast_pixel_direction`, `slow_pixel_direction`, `module_offset` — all +NXmx (`fast/slow_pixel_direction` and `module_offset` carry transformation attributes). The two +pixel-direction vectors carry the discrete image orientation (mirror in Y, multiples of 90° about the +beam); for a detector that this system assembled itself, they are the McStas form of the internal +x and ++y, i.e. `(-1, 0, 0)` and `(0, -1, 0)`. + +### `/entry/instrument/detector/module_` (NXdetector_module, one per module) + +A master of a multi-module detector states its modules one by one, in the order the `/entry/MX/peakPanel` +indices refer to. *n* is zero-padded to the width of the last index (`module_0` ... `module_7`, but +`module_00` ... `module_15`), so that the groups sort by name in module order and DIALS panel *n* is +module *n*; for an image Jungfraujoch assembled, each module is +its box of the image, as imaged. Rugnux writes the placement of a detector's modules, where a stills run +placed them, into `_modules.h5` in the same layout, and reads the same groups back +(`--module-geometry`, or a master that states its modules one by one). Masters written by releases up to +1.0.0-rc.181 may carry the whole-image `module` beside `module_`; they read back the same way. + +| Field | Units / notes | +|-------|-------| +| `data_origin` | `[row, column]` of the module's first pixel in the image (slowest index first) | +| `data_size` | `[rows, columns]` of the module | +| `module_offset` | translation (m) from the image's pixel (0, 0) to the module's first pixel; `depends_on` the detector's `transformations/translation` | +| `fast_pixel_direction`, `slow_pixel_direction` | translation of one pixel (m) along the module's columns and rows; `depends_on` the module's `module_offset` | +| `readout_fast_axis`, `readout_slow_axis` | not NXmx: which way the module's fast and slow readout axes run in the stored image (`Xp`, `Xn`, `Yp`, `Yn`); with the box they give its readout pixel 0, which names the module in a module placement (`dataset_settings.module_placement`) | + +Vectors are in the McStas frame. A pixel (row i, column j) of a module is at +`translation + module_offset + j * fast_pixel_direction + i * slow_pixel_direction`, which is how +DIALS/dxtbx reads it (one panel per module). + +### `/entry/sample` (NXsample) + +| Field | Std | Units / notes | +|-------|:---:|-------| +| `name` | NXmx | | +| `depends_on` | NXmx | points at the innermost axis of the sample chain, or `.` for stills | +| `temperature` | NXmx | K | +| `transformations/` (NXtransformations) | NXmx | the sample chain, written in mounting order; hard-linked as `/entry/sample/goniometer` | +| `unit_cell` | base | `[a, b, c, α, β, γ]` | +| `unit_cell_esd` | | e.s.d.s of `unit_cell`, in its order `[σa, σb, σc, σα, σβ, σγ]` (Angstrom, degrees; zero for an angle the space group fixes); rotation runs analysed by rugnux, offline or in the broker | +| `space_group_number` | base | International Tables number | +| `space_group` | base | extended Hermann-Mauguin name, e.g. `P 43 21 2`, `R 3:H` — this is the field that carries the **setting**, and the one the reader takes the group from; the number alone always reads back as the reference setting | +| `ub_matrix` | base | `[1, 3, 3]`, Angstrom⁻¹ | +| `grid_scan/` (NXcollection) | | for a grid scan: `snake_scan`, `vertical_scan` (bool), `n_fast` (points along the fast direction), `step_x`, `step_y` [m] | + +The chain is written from the base outwards, so the innermost axis — the one `depends_on` names — is +the one nearest the sample. It may hold, in that order: the grid-scan translations `grid_scan_x` and +`grid_scan_y`, the spindle, and a Smargon head's `chi` and `phi`. A grid scan and a goniometer axis +are **not** alternatives; both can be present. + +A **grid scan is collected at a stationary spindle, and the angle it stood at is stated by sending +the goniometer axis with a step of 0** — in `dataset_settings.goniometer`, or as the `goniometer` +map of the CBOR start message. The angle is then written per image as `omega` (or whatever the axis +is named) in the chain above, and read back by `reader/`. Send no axis and the spindle is still +recorded, at 0: NXmx would allow a sample with no goniometer at all (`depends_on = "."`), but a +sample chain of translations alone is not something readers accept, so the placeholder is written +whether or not the angle is known. **A 0 there means "nobody said", not "the spindle was at 0".** + +A **Smargon head position is told apart from the spindle** by the `equipment_component` attribute, +which is `"smargon"` on `chi` and `phi` and absent on the spindle. This is load-bearing: a spindle can +itself be named `phi`, and without the attribute a reader would take a head position for the scan +axis. `chi` and `phi` are written with one value per image even though neither turns, because a +reader takes the image count from the innermost axis of the chain: written as scalars, a still +recorded at a head position would read back as a single image however many were collected. + +For a rotation scan the goniometer axis carries, beyond the per-image angle array ``, the +Jungfraujoch conveniences `_end`, scalar `_range_average` and `_range_total`, and +for helical scans `_helical_x/_y/_z`. + +### `/entry/data` (NXdata) + +`data` (3-D image stack, `[n_images, y, x]`) with `image_nr_low` / `image_nr_high` attributes. +In legacy mode this group instead contains one external link `data_000001`, … per data file. + +## 4. Extensions beyond NXmx + +Everything in this section is **outside the NXmx standard**. Each group is declared with +`NX_class = NXcollection` (the NeXus-sanctioned container for non-standardised content) unless noted. +The per-image arrays are indexed by image number, padded to the run length and filled with a +sentinel (`NaN` for floats, `-1`/`0` for integer indices) where a quantity is absent. + +### 4.1 `/entry/MX` — spot finding and indexing (CXI-style) + +The flagship extension. Spot ("peak") properties are stored as fixed-size `[n_images, max_spots]` +arrays (CXI layout, recognised by CrystFEL); scalar-per-image quantities as `[n_images]` vectors. +In legacy/VDS mode the per-spot arrays, `nPeaks`, `peakPanel` and the per-image lattices live in the +data files and are linked/virtual-stacked into the master; the per-image vectors are copied into the +master from the end message at finalisation (with `strongPixels`, `beam_corr_x/y` and `bravaisLattice` +in the data files only). + +**Per-spot arrays `[n_images, max_spots]`:** + +| Dataset | Units | Meaning | Indexing only | +|---------|-------|---------|:---:| +| `peakXPosRaw`, `peakYPosRaw` | pixel | spot position (raw detector frame) | | +| `peakTotalIntensity` | photons | spot intensity | | +| `peakIceRingRes` | | spot lies in an ice-ring resolution band (int8) | | +| `peakH`, `peakK`, `peakL` | | Miller indices of the (indexed) spot (int32) | ✓ | +| `peakDistEwaldSphere` | Å⁻¹ | distance of the spot from the Ewald sphere | ✓ | +| `peakIndexed` | | spot fits the indexing solution (int8) | ✓ | +| `peakLattice` | | lattice the spot belongs to (int8, `-1` = unindexed) | ✓ | +| `peakPanel` | | panel the spot was found on (int16, `-1` = none); written only for a detector with a panel table | | + +**Per-image vectors `[n_images]`:** + +| Dataset | Units | Meaning | +|---------|-------|---------| +| `nPeaks` | | number of spots stored for the image (CXI, uint32) | +| `strongPixels` | | strong-pixel count (first spot-finding stage) | +| `peakCountUnfiltered` | | spots found before filtering | +| `peakCountLowRes` | | low-resolution spots | +| `peakCountIceRingRes` | | spots inside ice-ring bands | +| `peakCountIceRingControl` | | spots in the ice-free flanks beside those bands, rescaled to their q width - the control for the count above (their ratio, pooled over the run, is the spot-based ice indicator) | +| `peakCountIndexed` | | spots fitting the indexing solution | +| `imageIndexed` | | image was indexed (0/1) | +| `indexingLatticeCount` | | number of lattices found for the image | +| `niggliClass` | | Niggli class of the indexed Bravais lattice (see *International Tables for Crystallography A* (2016), Vol. A, [Table 3.1.3.1](https://onlinelibrary.wiley.com/iucr/itc/Ac/ch3o1v0001/table3o1o3o1.pdf)) | +| `bravaisLattice` | | Bravais lattice short code, e.g. `aP`, `mC`, `oF`, `tI`, `hP`, `hR`, `cF` | +| `profileRadius` | Å⁻¹ | crystal profile radius | +| `mosaicity` | deg | mosaicity estimate | +| `bFactor` | Ų | per-image B-factor estimate | +| `resolutionEstimate` | Å | resolution the merged data are predicted to reach, from this image's spots alone | +| `integratedReflections` | | number of integrated reflections | +| `bkgEstimate` | photons | mean background in the 3–5 Å resolution band | +| `iceRingScore` | ratio | strongest hexagonal-ice ring intensity over the smooth radial background (1 = no ice) | +| `spindleBlindFraction` | fraction (0-1) | how much of a rotation sweep's blind cone this orientation makes unrecoverable, as a lone-2-fold worst-case bound; NaN = the frame could not be assessed, which automation must treat like a value at or above the 0.5 trigger, never as 0 | +| `beam_corr_x`, `beam_corr_y` | pixel | beam-center correction applied during processing | +| `imageScaleFactor` | | on-the-fly per-image scale factor *g* | +| `imageScaleCC` | | on-the-fly scaling correlation coefficient | +| `imageScaleMosaicity` | deg | scaling-model mosaicity | +| `sweepQuality` | | why this image's stretch of the sweep was flagged — see below | +| `frameDisposition` | | what became of this image's observations in the merged data — see below | + +**Per-image lattices:** `latticeIndexed` `[n_images, 9]` (Å) — the real-space lattice (flattened +3×3); `latticeIndexedExtra` `[n_images, max_extra_lattices, 9]` (Å) — additional orientation +variants. + +**Run-level summaries** (written into the master `/entry/MX` at finalisation): + +| Dataset | Units | Meaning | +|---------|-------|---------| +| `indexing_algorithm` | | `FFBIDX` / `FFT (CUDA)` / `FFT (FFTW)` | +| `geom_refinement_algorithm` | | `beam_center` / `flex` | +| `rotationLatticeIndexed` | Å | whole-run rotation-indexing lattice (`[9]`) | +| `rotationLatticeIndexedExtra` | Å | additional whole-run lattices (`[m, 9]`) | +| `rotationLatticeNiggliClass` | | Niggli class of the run lattice | +| `imageIndexedMean` | | mean indexing rate over the run | +| `bkgEstimateMean` | photons | mean background over the run | +| `spindleBlindFractionMean` | fraction (0-1) | mean `spindleBlindFraction` over the frames that had one | +| `spindleLostUniqueFraction` | fraction (0-1) | unique reflections (to the run's resolution limit) the mounting made unmeasurable, exact under the measured point group and indexed orientation; offline (Rugnux) only | +| `iceRingScoreMean` | ratio | mean `iceRingScore` over the run — the single "how icy was this dataset" number (1 = no ice) | +| `indexedLatticeCount` | | per-image lattice count summary (master). *Note: data files use `indexingLatticeCount`; readers accept either.* | +| `reindexMatrix` | | change of basis from the setting the per-image data are in to the setting of `/entry/sample/unit_cell` (`[9]`, `int32`, flattened 3×3, row major) — see below | +| `stillsRockingWidthFormula` | 1/Å, rad, relative | stills: the run's rocking width σ² = γ₀² + (γₑ d\*)² + (σ_bw λ d\*²/2)², as `[γ₀, γₑ, σ_bw]`; offline (Rugnux) only | +| `stillsRadialScale` | | stills: the scale of the reciprocal lattice the rocking curve is centred on | +| `stillsRockingWidthTableDstar`, `stillsRockingWidthTable` | 1/Å | stills: the rocking width σ measured against d\* before the image pass, which the frames were predicted through (held beyond the first and last entry; the formula above is what the prediction window uses); the partiality post-refinement balances it against the merge, and `--mode scale` starts from this same curve instead of measuring another | +| `stillsGivenUnitCell` | Å, deg | stills: the cell given with `-C`, whose population of frames the merge kept (`[6]`); `--mode scale` leaves out the same frames | + +**Reindex matrix.** The per-image `h`, `k`, `l` and `latticeIndexed` are written as each image is +processed, in the setting that image was *indexed* in. The space group is only settled afterwards, by +the merge, and settling it can re-seat the lattice into the group's conventional setting — so +`/entry/sample/unit_cell`, `/entry/sample/space_group_number` and `rotationLatticeIndexed` can be in a +different setting from the per-image data beside them. `reindexMatrix` **M** is the integral change of +basis between the two: `hkl_cell = M · hkl_written`, and the same **M** takes each per-image lattice +across (`latticeIndexedExtra` is not re-seated and stays as indexed). It is **absent** when the two +settings are the same one, which is the identity — as it is on every file written before Rugnux +recorded it. The Jungfraujoch reader applies it, so everything it hands out is already in the cell's +setting; a third-party reader that ignores it will index the reflections in the wrong frame whenever +the dataset is present. Written by the offline `rugnux` path only — the broker never re-seats a +lattice — and not carried on the CBOR stream, in the same way as the other offline-only fields. + +A `--model` run can leave the merged reflection files (`.mtz`/`.cif`/`.hkl`) in a *different* frame +from the `_process.h5` beside them: the model settles the alternative indexing where nothing else +did, and that choice is applied to the merged reflections as they are written. It also names the +enantiomorph, but that is a change of space-group label only and moves no reflection. +The process file is not rewritten — its per-image reflections went to disk as they were integrated — +so it keeps the space group the run itself determined and stays self-consistent with its own data. +The two frames describe the same measurements; an enantiomorphic pair merges identically, having the +same Laue class and the same absences. + +**Sweep quality.** `sweepQuality` `[n_images]` (`uint8`) says why the stretch of the sweep this +image belongs to was flagged as delivering much less than the rest of the run: **0** means it was +not, and any other value is a **1-based index into `sweepQualityReasons`**, a string vector written +beside it that carries the whole vocabulary, so the codes can be read without this source. The +vocabulary is closed and stable — a code is never renamed and never reused — and currently reads +`no_diffraction`, `crystal_out_of_beam`, `weak_diffraction`, `loss_of_centring`, `radiation_damage`, +`inconsistent_with_merge`; +[the Rugnux results report](RUGNUX_REPORT.md#sweep-quality-the-disposition-and-their-vocabularies) +defines what each one means. Both datasets are **absent** unless the sweep-quality diagnostic ran, +which needs scaling and merging; their absence therefore means "not looked for", *not* "every image +clean". Written by the offline `rugnux` path only — the broker does not merge — and not carried on the +CBOR stream, in the same way as the other offline-only fields (`reindexMatrix`, the refined +geometry). The condensed, dataset-wide form of the same +finding is in `_report.txt`. + +**Frame disposition.** `frameDisposition` `[n_images]` (`uint8`) says what became of the image's +observations: a **0-based index into `frameDispositionCodes`**, written beside it, which reads +`merged`, `downgraded`, `rejected`. Where `sweepQuality` says what was *seen* over a stretch, this +says what was *done* about it — a `rejected` image contributed nothing to the merged intensities. +Same availability rule as `sweepQuality`: absent means the diagnostic never ran. + +CrystFEL can read the spots directly with: + +``` +peak_list = /entry/MX +peak_list_type = cxi +``` + +### 4.2 `/entry/reflections` — integrated reflections (NXreflections) + +Integrated reflections - written where rugnux integrated the images (rugnux, or the broker's rugnux live mode for +serial collections; the broker's own per-image analysis does not integrate) - are stored **per image** as +`/entry/reflections/image_NNNNNN` groups, each declared `NX_class = NXreflections`. The columns map +mostly onto the standard +[NXreflections](https://manual.nexusformat.org/classes/base_classes/NXreflections.html) base class: + +| Dataset | Units | NXreflections | Meaning | +|---------|-------|:-------------:|---------| +| `h`, `k`, `l` | | standard | Miller indices | +| `d` | Å | standard | resolution | +| `int_sum` | photons | standard | integrated intensity (summation) | +| `int_err` | photons | non-standard name | σ of the intensity (standard equivalent: `int_sum_errors`) | +| `background_mean` | photons | standard | mean background under the peak | +| `background_variance` | photons² | non-standard | non-signal part of σ², carried to the merge. Absent in files written before it existed; the reader then recovers it from σ² − I | +| `predicted_x`, `predicted_y` | pixel | name standard, units differ | predicted position. NXreflections `predicted_x/_y` are *physical* lengths; the pixel datasets are `predicted_px_x/_y` | +| `observed_x`, `observed_y` | pixel | name standard, units differ | observed centroid (pixels; standard pixel form is `observed_px_x/_y`) | +| `observed_frame` | | standard | image number of the reflection | +| `lp` | | standard | the Lorentz-polarization factor, stored as the reciprocal of the multiplier that is applied. Lorentz x polarization only, which is what the NXreflections name means; the sensor efficiency is `qe`, beside it | +| `qe` | | **extension** | the sensor efficiency, in the same reciprocal convention as `lp`, so the whole correction applied to a raw count is `1/lp * 1/qe`. Absent in files written before it existed; the reader then takes the whole of `lp` for Lorentz–polarization, which is what those files mean | +| `flight` | | **extension** | the flight path between sample and pixel, in the same reciprocal convention as `lp` and `qe`, so the whole correction applied to a raw count is `1/lp * 1/qe * 1/flight`. It runs the opposite way to `qe` — at most 1 where `qe` is at least 1 — because the medium attenuates an oblique reflection where the sensor favours it. Exactly 1 under `--flight-path vacuum`, and absent in files written before it existed; the reader then takes it as 1 | +| `partiality` | | standard | recorded fraction of the reflection | +| `delta_phi` | deg | **extension** | XDS Δφ: offset from the centre of the current frame | +| `zeta` | | **extension** | Lorentz ζ factor (reciprocal-space geometry term) | +| `image_scale_corr` | | **extension** | per-image scale correction; `I_true = image_scale_corr · int_sum` | +| `excitation_error` | Å⁻¹ | **extension** | distance of the reflection from the Ewald sphere | +| `observed` | | **extension** (uint8) | 1 where the reflection was observed on the image | +| `clipped` | | **extension** (uint8) | 1 where the signal disk lost pixels to the mask or to saturation, so the intensity is the profile's estimate over what remained; the merge does not let such a measurement testify against a larger one of the same reflection | +| `overloaded` | | **extension** (uint8) | 1 where a pixel of the signal disk was saturated; a rotation merge drops the whole rocking event, as XDS does | + +In the master file these per-image groups are exposed through `/entry/reflections` external links +(VDS/integrated formats). + +### 4.3 `/entry/azint` — azimuthal integration + +| Dataset | Shape | Units | Meaning | +|---------|-------|-------|---------| +| `bin_to_q` | `[φ_bins, q_bins]` | Å⁻¹ | q value of each bin (its centre: arithmetic mean of the edges for linear bins, geometric mean for log10 bins) | +| `bin_to_two_theta` | `[φ_bins, q_bins]` | deg | 2θ of each bin | +| `bin_to_phi` | `[φ_bins, q_bins]` | deg | azimuthal angle of each bin | +| `image` | `[n_images, φ_bins, q_bins]` | | per-image integrated profile (NaN for empty bins) | +| `image_std` | `[n_images, φ_bins, q_bins]` | | per-bin standard deviation | +| `image_count` | `[n_images, φ_bins, q_bins]` | | pixels contributing per bin | +| `map` | `[y, x]` | | pixel→bin mapping (master file only) | + +### 4.4 `/entry/roi` — regions of interest (per-image results) + +`/entry/roi/` has one sub-group per configured ROI, holding the **per-image result +vectors** `[n_images]`. These are written into the data files; in VDS mode they are exposed from +the master file through virtual datasets, and in integrated mode they are in the single file. +(In legacy mode they remain only in the data files.) + +| Dataset | Meaning | +|---------|---------| +| `max` | maximum pixel value in the ROI | +| `sum` | sum of pixel values | +| `sum_sq` | sum of squared pixel values | +| `npixel` | number of valid pixels | +| `x`, `y` | intensity-weighted centroid | + +#### 4.4.1 `/entry/roi_defs` — ROI definitions (master file) + +The **dataset-wide ROI definitions** (geometry, fixed for the whole acquisition) live in the +master file under a *separate* `/entry/roi_defs` group — kept apart from `/entry/roi` above so +that older readers, which iterate `/entry/roi`, are unaffected by these entries. One sub-group +`/entry/roi_defs/` per ROI: + +| Dataset | Meaning | +|---------|---------| +| `bit_index` | which bit of `roi_map` (below) marks this ROI | +| `type` | `box`, `circle` or `azim` | +| `min_x_pxl`, `max_x_pxl`, `min_y_pxl`, `max_y_pxl` | box bounds (type `box`) | +| `center_x_pxl`, `center_y_pxl`, `radius_pxl` | circle (type `circle`) | +| `q_min_recipA`, `q_max_recipA` | Q range (type `azim`) | +| `phi_min_deg`, `phi_max_deg` | azimuthal-angle sector (type `azim`, omitted for a full ring) | + +`/entry/roi_defs/roi_map` `[y, x]` is a `uint16` per-pixel bitmask: bit `bit_index` is set for +every pixel belonging to that ROI, so an ROI's footprint can be recovered exactly. + +### 4.5 `/entry/image` — per-image pixel statistics + +`[n_images]` vectors: `max_value`, `min_value` (viable min/max, excluding error/saturated pixels), +`error_pixels`, `saturated_pixels`, `pixel_sum`. Surfaced in the master file under `/entry/image`. +`pixel_sum` is the signed sum of the pixels that are not error, not saturated and not under the +device mask (detector and calibration); a mask rugnux determines on the run's own frames (hot pixels, +beam-stop shadow, inactive pixels) does not change it. The FPGA computes it per module, and CPU/GPU analysis (e.g. +EIGER) per image, on the assembled image, to the same definition. + +### 4.6 `/entry/profiling` — per-image timing + +`[n_images]` vectors in seconds: `spotFindingTime`, `indexingTime`, `integrationTime`, +`refinementTime`, `processingTime`, `braggPredictionTime`, `preprocessingTime`, `compressionTime`, +`azIntTime`, `indexAnalysisTime`, `imageScaleTime`. + +### 4.7 `/entry/detector` — acquisition diagnostics (data file) + +A convenience NXcollection in the data file (note: distinct from the standard +`/entry/instrument/detector`). In **integrated** format the diagnostics below `number` are written under +`/entry/instrument/detector/detectorSpecific` instead; `timestamp`, `exptime` and `number` stay here. + +| Dataset | Meaning | +|---------|---------| +| `timestamp`, `exptime` | per-image timestamp and exposure time | +| `number` | image number (original number if image rejection was used) | +| `det_info` | JUNGFRAU debug field | +| `storage_cell_image` | storage-cell number | +| `rcv_delay`, `rcv_free_send_buffers` | receiver internal diagnostics | +| `packets_expected`, `packets_received` | UDP packets per image | +| `data_collection_efficiency_image` | received / expected packet ratio | + +### 4.8 `/entry/xfel` — pulsed-source metadata + +`[n_images]` vectors `pulseID` (uint64) and `eventCode` (uint32), written for pulsed sources (e.g. +SwissFEL): the XFEL pulse ID and the event code of each image, as the detector's timing receiver +recorded them. A pulse ID of `UINT64_MAX` marks an image whose modules disagreed on it. They are written to +the data files and, for a VDS master, mapped into the master as well. + +In a `_process.h5`, `/entry/xfel/pulseID` and `/entry/xfel/eventCode` hold the IDs of the images +processed, in the file's own image order: entry `i` belongs to the image whose analysis is at index `i` +(`/entry/MX/...[i]`, `/entry/reflections/image_`), the source image `/entry/detector/number[i]`. With +a subset or a stride (`-s`/`-e`/`--stride`) only the processed images are there; several inputs read as +one keep them only where every input has them. + +### 4.9 Other collections + +| Path | Class | Content | +|------|-------|---------| +| `/entry/instrument/detector/detectorSpecific` | NXcollection | Dectris-style detector metadata + Jungfraujoch fields: `x_pixels_in_detector`, `y_pixels_in_detector`, `nimages`, `ntrigger`, `nimages_collected`, `nimages_written`, `data_collection_efficiency`, `max_receiver_delay`, `storage_cell_number`, `storage_cell_delay` [ns], `software_git_commit`, `software_git_date`, `jfjoch_release`, `jfjoch_writer_release`, `summation_mode`, `detect_ice_rings`, `gain_file_names`, `data_reduction_factor_serialmx`, `adu_histogram/` (`bin_width` and one vector per storage cell), `data_collection_efficiency_image`, `direct_beam_x`, `direct_beam_y`, `pixel_mask` (hard-linked as `/entry/instrument/detector/pixel_mask`), `storage_cell_image` (VDS, with storage cells) | +| `/entry/instrument/detector/calibration` | NXcollection | per-channel pedestal / calibration images (bitshuffle-compressed) | +| `/entry/instrument/fluorescence` | NXcollection | XRF spectrum: `energy` [eV], `data` | +| `/entry/user` | NXcollection | scalar values supplied under `header_appendix.hdf5` | + +### 4.10 Non-standard fields inside the NXmx detector group + +A few extension scalars are written *inside* the otherwise-standard `/entry/instrument/detector` +group for compatibility with existing tooling: + +| Field | Units | Meaning | +|-------|-------|---------| +| `detector_distance` | m | duplicate of `distance` (Dectris/Neggia compatibility) | +| `detector_number` | | detector identifier (Dectris convention) | +| `mirror_y` (in `detectorSpecific`) | | whether the stored image is mirrored in Y relative to the raw readout; true is the MX convention (row 0 at the top) | +| `detector_orientation_mirror_y` (in `detectorSpecific`) | | whether the stored image is mirrored in Y relative to the frame `rot1`/`rot2`/`rot3` are stated in — a different setting from `mirror_y`, and one that changes no pixel | +| `detector_orientation_quarter_turns` (in `detectorSpecific`) | | multiples of 90° about the beam the stored image is turned by, relative to that same frame (0-3) | +| `direct_beam_x`, `direct_beam_y` (in `detectorSpecific`) | pixel | where the undeflected beam lands, as opposed to the PONI in `beam_center_x`/`beam_center_y` - see above | +| `error_value` | | masked/error pixel sentinel: `UINTx_MAX` unsigned, `INTx_MIN` signed (NXmx has no equivalent). NXmx `underload_value` is written too: `INTx_MIN + 1` for signed, `0` for unsigned | +| `bit_depth_image` | | stored image bit depth (DECTRIS convention, not NXmx). Equal to `bit_depth_readout` where that is written, i.e. for unsigned images | +| `acquisition_type` | | always `triggered` (Dectris convention) | +| `jungfrau_conversion_applied` | | JUNGFRAU photon/keV conversion applied | +| `jungfrau_conversion_factor` | eV | conversion factor | +| `geometry_transformation_applied` | | module→full-detector geometry applied | + +NeXus has no concept of a fill or no-data value — it expects bad pixels to be flagged in `pixel_mask`, +which Jungfraujoch also writes. The in-band sentinel above is a DECTRIS compatibility convention: +SIMPLON specifies that masked pixels are flagged with `2^bit_depth_image - 1`. + +For an **unsigned** image the sentinel and the saturation code are the same value, so a saturated +pixel and a masked one cannot be told apart — the FPGA collapses both onto `UINTx_MAX`. Signed +images keep them separate: `INTx_MIN` is the marker, `INTx_MAX` is saturation. + +`bit_depth_readout` is written for **unsigned** images only. DIALS remaps the top two codes of +`2^bit_depth_readout` to `-1` and `-2` whenever the field is present, regardless of the pixel type: +for an unsigned image those land below `underload_value` and are correctly masked, but for a signed +one they land inside the trusted range and a saturated pixel would be integrated as a count of `-2`. +Signed images are read correctly without the field; unsigned 32-bit cannot be read at all without it. + +### 4.11 User-supplied metadata: `header_appendix` and `image_appendix` + +Facilities frequently need to attach metadata that Jungfraujoch does not model explicitly. Two +free-form JSON fields in the `/start` request (`broker/jfjoch_api.yaml`) provide this without any +schema change; both accept *any valid JSON*: + +| Field | Carried in | Persisted to HDF5? | +|-------|-----------|--------------------| +| `header_appendix` | the **start** message, under `user_data.user` (see [CBOR](CBOR.md)) | no — except the `hdf5` sub-object (below) | +| `image_appendix` | **every image** message, as `user_data` | no | + +Both are forwarded verbatim through the ZeroMQ/CBOR stream to every downstream consumer (writer, +republished analysis, viewers), so they are the recommended channel for facility- or +beamline-specific provenance (proposal, operator, optics state, per-image trigger info, …) that has +no dedicated API field. + +**Persisting selected values to HDF5.** `header_appendix` is normally *not* written to the master +file. As an exception, if it contains a key `hdf5` whose value is a JSON object of scalars (strings +and numbers — no arrays or nested objects), the writer stores each entry under `/entry/user/`. + +For example, a `/start` request containing: + +```json +{ + "header_appendix": { + "proposal": "p20001", + "operator": "jdoe", + "hdf5": { "beamline": "X06SA", "ring_mode": "top-up", "attenuator_foils": 2 } + }, + "image_appendix": { "trigger_source": "external" } +} +``` + +forwards the whole `header_appendix` as `user_data.user` on the start message and +`{"trigger_source": "external"}` as `user_data` on every image message, and writes three scalars +into the master file: + +``` +/entry/user/beamline = "X06SA" +/entry/user/ring_mode = "top-up" +/entry/user/attenuator_foils = 2 +``` + +## 5. Notes + +* **Units** are written as the HDF5 `units` attribute on the dataset (e.g. `m`, `eV`, `deg`, + `Angstrom`, `Angstrom^-1`, `Angstrom^2`, `pixel`, `s`). +* **Sentinels.** Missing per-image values are `NaN` (floats) or `-1`/`0` (integer indices); image + pixels use `INTx_MIN` / `UINTx_MAX`. +* **Master vs data file.** In legacy/VDS formats the analysis arrays physically live in the data + files; the master file links to them (external links in legacy, virtual datasets in VDS). In the + integrated format there are no data files and everything is in one place. +* **CXI / CrystFEL.** `/entry/MX` follows the CXI peak-list convention; see + [CXI file format](https://raw.githubusercontent.com/cxidb/CXI/master/cxi_file_format.pdf). diff --git a/_sources/IMAGE_STREAM.md.txt b/_sources/IMAGE_STREAM.md.txt new file mode 100644 index 000000000..a74acc90d --- /dev/null +++ b/_sources/IMAGE_STREAM.md.txt @@ -0,0 +1,259 @@ + +# Data streams + +The Jungfraujoch process (`jfjoch_broker`) operates three outputs. +All three can be operated/enabled independently. +These are: +* **Image** - all the images including metadata (ZeroMQ PUSH socket or custom TCP/IP socket) +* **Preview** - images with metadata at a reduced frame rate (PUB socket) +* **Metadata** - only metadata for all the images, bundled into packages (PUB socket) + +## Image stream +Images (with metadata) are serialized as CBOR [image message](CBOR.md#image-message). +The stream will also include CBOR [start message](CBOR.md#start-message), [calibration messages](CBOR.md#calibration-message) and [end message](CBOR.md#end-message) with run metadata. +Calibration messages (the JUNGFRAU pedestal and pedestal RMS, with `save_calibration` on) come only from the +FPGA workflow; a DECTRIS stream carries no calibration, so none is forwarded for it. + +If `file_prefix` is not provided for a data collection, images won't be sent to image stream (or its HDF5/CBOR replacements). + +### Splitting image stream +Image stream can be split into multiple sockets to increase performance, in this case images will be split according to file number to which the image belongs. +All sockets will forward start and end messages. Only the first socket will forward calibration messages and will be marked to write master file. + +### ZeroMQ image stream +This is using PUSH ZeroMQ socket(s). +Multiple receivers must never be connected to one PUSH ZeroMQ socket. +ZeroMQ will send the images in a round-robin basis to the receivers. +In this case start and end messages will end up only with one receiver. +Instead, Jungfraujoch feature of multiple sockets should be used. +For ZeroMQ image stream, each writer connects to a different port. + +Behavior is as following: +* Start message is sent with timeout of 1s per socket. If within the time the message cannot be put in the outgoing queue or there is no connected puller, an exception is thrown — data collection is stopped with an error due to absence of a writer. +* Calibration message is sent to the first socket only, with timeout of 1s. +* Images are sent via a per-socket writer thread. If a send times out, the pusher switches to non-blocking mode for the remainder of the collection (images may be dropped). +* End message is sent with timeout of 1s per socket. No exception is thrown on timeout, but a transmission error is recorded. + +The format is generally interchangeable with DECTRIS Stream2 format. + +#### ZeroMQ configuration + +ZeroMQ image stream is configured in the broker JSON configuration file under the `zeromq` section (schema `zeromq_settings`): +```json +{ + "image_socket": ["tcp://192.168.0.1:9000", "tcp://192.168.0.1:9001"], + "send_watermark": 100, + "send_buffer_size": 67108864, + "writer_notification_socket": "tcp://192.168.0.1:*" +} +``` + +- `image_socket`: one or more PUSH socket addresses. Multiple entries split the image stream across sockets. Addresses follow ZeroMQ conventions (`tcp://`, `ipc://`). `0.0.0.0` binds on all network interfaces. +- `send_watermark` (optional): ZeroMQ send high-water mark (number of outstanding messages per socket). +- `send_buffer_size` (optional): OS-level send buffer size for the ZeroMQ socket. +- `writer_notification_socket` (optional): see [Writer notification socket](#writer-notification-socket) below. + +### TCP/IP image stream +This is using TCP/IP socket(s) with a fixed binary frame header followed by payload bytes. +This format was introduced to Jungfraujoch as an alternative to ZeroMQ image stream. It allows two-way communication +between the data collection and the writer, and is therefore more robust than ZeroMQ. + +For TCP/IP image stream, Jungfraujoch **listens** on a single TCP port and all writers **connect** to it. Connections are persistent — writers connect once and stay connected across multiple data collections. Jungfraujoch sends periodic `KEEPALIVE` frames when no data collection is active to detect dead connections; writers are expected to respond with a `KEEPALIVE` pong. + +Using `*` as port number (e.g. `tcp://127.0.0.1:*`) is supported — the OS assigns a free port. + +Payloads for `PREFLIGHT`, `START`, `DATA`, `CALIBRATION` and `END` frames are CBOR messages, equivalent in content to the ZeroMQ image stream messages. +`ACK`, `CANCEL`, `KEEPALIVE` and `BUSY` are control frames (no CBOR payload). + +The data collection lifecycle on each connection follows: +`PREFLIGHT` → `START` → `CALIBRATION` (socket 0 only) → `DATA` (repeated) → `END` + +If a `START` ACK fails on any connection, Jungfraujoch sends `CANCEL` to all already-started connections and rolls back. + +For each frame: +1. Read one `TcpFrameHeader` (fixed size, 64-byte aligned). +2. Validate `magic` (`0x4A464A54` / `"JFJT"`) and `version` (`5`). Both ends reject a frame of any other version, so writer and broker must be of the same release. +3. Read `payload_size` bytes (if non-zero). + +#### Pre-flight + +Before a data collection is started - before the detector is armed - Jungfraujoch sends a `PREFLIGHT` frame on every connection and waits for its ACK. It carries the same CBOR start message a `START` would, and asks the writer one question: could this run be written? The writer checks the output path, creates the output directory, and checks that no output file is in the way; it opens nothing, writes nothing, and does not change its state. A run that would fail on the first file it wrote is therefore refused while refusing it is free, with the writer's own message reported to the client by `/start` and `/wait_until_running`. + +`write_master_file` is assigned exactly as it is for `START` (connection index 0), and the writer that owns the master file is the one that answers for the output files - the master and every data file the run will write, its siblings' included. + +The `PREFLIGHT` payload describes the run but carries none of the per-pixel arrays a `START` does - no pixel mask, no azimuthal-integration map, no ROI map - so it stays small: about 1.4 kB on a JUNGFRAU 9M, against about 540 kB for the `START` that follows. + +A rejected `PREFLIGHT` is **not** fatal: nothing was started, so the connection stays usable and the next attempt (a different file prefix, or `overwrite` set) proceeds on it. The check cannot be exhaustive - a file created in the moment between the pre-flight and the start still fails at the start, and free space and quota are not inspected - so it lowers how often a run fails on its output, it does not remove the case. + +When image stream is split into multiple connections: +- `START` and `END` are sent on all connections, +- `CALIBRATION` is sent only on connection 0, +- `DATA` frames are distributed by file grouping: connection index = `(image_number / images_per_file) % num_connections`. + +#### TCP/IP configuration + +TCP/IP image stream is configured in the broker JSON configuration file under the `tcp` section (schema `tcp_settings`): +```json +{ + "image_socket": "tcp://192.168.0.1:9100", + "nwriters": 2, + "send_buffer_size": 67108864 +} +``` + +- `image_socket`: listen address in `tcp://:` format. `0.0.0.0` binds on all interfaces. `*` as port selects a random free port. +- `nwriters` (optional): maximum number of simultaneous writer connections accepted. +- `send_buffer_size` (optional): OS-level `SO_SNDBUF` size for accepted connections. +- `peer_liveness_timeout_ms` (optional, default 15000): how long a send may block with no sign of life from the writer (no `BUSY` heartbeat, no ACK) before the connection is declared dead. +- `max_backpressure_timeout_ms` (optional, default 60000): hard bound on backpressure - if no bytes can be sent for this long the connection is declared dead even while the writer keeps heartbeating. + +#### ACK handling + +ACK handling is mandatory for correct operation: +- `PREFLIGHT` **must** be acknowledged (`ack_for=PREFLIGHT`) on each connection within 5 seconds, otherwise the collection is not started. A rejected pre-flight (`OK` clear) carries the reason as error text and does not break the connection. +- `START` **must** be acknowledged (`ACK` with `ack_for=START`) on each connection within 5 seconds, otherwise collection start fails and a rollback is triggered. +- `END` **must** be acknowledged (`ack_for=END`) on each connection for successful completion. There is no fixed deadline: the writer may still be flushing a backlog, so the broker waits as long as the writer shows signs of life (`BUSY` heartbeats, `DATA` ACKs) and gives up only after `peer_liveness_timeout_ms` (default 15 s) of silence. +- `CANCEL` should be acknowledged during rollback paths (500ms timeout). +- `DATA` should be acknowledged for every frame. A `DATA` ACK with `FATAL` flag set reports a downstream error (e.g. disk full) which is propagated to `jfjoch_broker` via `Finalize()`. A failed `DATA` ACK does **not** break the TCP connection on its own — data continues to flow. +- `CALIBRATION` is not acknowledged at this time. +- `KEEPALIVE` frames are not acknowledged via ACK; the writer responds with a `KEEPALIVE` pong frame instead. + +#### Keepalive + +When no data collection is active, Jungfraujoch sends `KEEPALIVE` frames approximately every 5 seconds on each persistent connection. Writers should respond with a `KEEPALIVE` frame (pong). OS-level TCP keepalive is also enabled (`TCP_KEEPIDLE=30s`, `TCP_KEEPINTVL=10s`, `TCP_KEEPCNT=3`) as a secondary safety net. Dead connections are automatically removed from the pool. + +#### Zero-copy transmission + +On Linux, large payload transmission (`DATA` and `CALIBRATION` frames) can use kernel TCP zero-copy (`SO_ZEROCOPY`/`MSG_ZEROCOPY`) when available. If the kernel does not support it or the socket option fails, transmission transparently falls back to normal `send()` behavior. Zero-copy completion notifications are processed by a dedicated per-connection thread. + +#### Frame types + +| Value | Name | Purpose | +|---:|---|---| +| 1 | `START` | Start-of-run metadata | +| 2 | `DATA` | One image payload | +| 3 | `CALIBRATION` | Calibration payload | +| 4 | `END` | End-of-run metadata | +| 5 | `ACK` | Acknowledgement / error reporting | +| 6 | `CANCEL` | Cancel run initialization/stream | +| 7 | `KEEPALIVE` | Connection liveness probe/pong | +| 8 | `BUSY` | Writer alive but stalled; carries its FIFO occupancy | +| 9 | `PREFLIGHT` | Dry run before a collection starts: can this run be written? | +| 10 | `FILE_CLOSED` | Not a frame of its own: the value of `ack_for` in a writer `ACK` reporting that a data file was closed and renamed into place (`image_number` = file number from 0, `ack_processed_images` = one past the highest image number it holds). The broker uses it to tell a reader following the collection which files it can read. | + +#### TCP frame header (`TcpFrameHeader`) + +| Field | Type | Description | +|--------------------------|---|----------------------------------------------------------| +| `magic` | `uint32_t` | Protocol magic (`0x4A464A54`, `"JFJT"`) | +| `version` | `uint16_t` | Protocol version (`5`) | +| `type` | `uint16_t` | Frame type (see table above) | +| `image_number` | `uint64_t` | Image index for `DATA` frames | +| `payload_size` | `uint64_t` | Number of payload bytes after header | +| `socket_number` | `uint32_t` | Connection index in split-stream mode | +| `flags` | `uint32_t` | ACK flags (`OK`, `FATAL`, `HAS_ERROR_TEXT`) | +| `run_number` | `uint64_t` | Run identifier | +| `ack_processed_images` | `uint32_t` | In `ACK`: number of images processed by receiver | +| `ack_code` | `uint16_t` | In `ACK`: error/status code | +| `ack_for` | `uint16_t` | In `ACK`: frame type being acknowledged | +| `ack_fifo_occupancy` | `uint64_t` | In `ACK`: occupancy of input FIFO in the `jfjoch_writer` | +| `ack_fifo_max_occupancy` | `uint64_t` | In `ACK`: max occupancy of input FIFO | + +The header is 64-byte aligned (`alignas(64)`). + +#### ACK semantics + +- `ACK` frames use `ack_for` to indicate which frame type is acknowledged. +- `flags`: + - `OK` (bit 0): operation accepted/successful, + - `FATAL` (bit 1): receiver reports unrecoverable error (primarily for `DATA`), + - `HAS_ERROR_TEXT` (bit 2): ACK payload contains UTF-8 error text. +- `ack_code` can be used to categorize errors: + +| Code | Name | Meaning | +|---:|---|---| +| 0 | `None` | No error | +| 1 | `StartFailed` | START processing failed | +| 2 | `DataWriteFailed` | Image write failed | +| 3 | `EndFailed` | END processing failed | +| 4 | `DiskQuotaExceeded` | Disk quota exceeded | +| 5 | `NoSpaceLeft` | No space left on device | +| 6 | `PermissionDenied` | Permission denied | +| 7 | `IoError` | General I/O error | +| 8 | `ProtocolError` | Protocol-level error | + +### Image stream replacement +Image stream can be replaced with direct HDF5 writer and CBOR dump image pushers, or it can be disabled by selecting "None" image pusher for all the measurements. + +## Writer notification socket +The writer notification socket is used **only with ZeroMQ image stream**. Since ZeroMQ is asynchronous, `jfjoch_broker` does not know whether messages were properly handled downstream (e.g. written to disk). The writer notification socket allows downstream code to report back. + +For TCP/IP image stream, this mechanism is not needed — ACK frames provide synchronous feedback for each control and data frame. + +To use writer notification socket, it has to be first enabled in the JSON configuration file of broker with `writer_notification_socket` entry: +```json +{ + "writer_notification_socket":"tcp://192.168.0.1:*" +} +``` +Such entry will create PULL socket on `192.168.0.1` network interface listening on one, random TCP port. When data processing is started, the +image stream will send CBOR [start message](CBOR.md#start-message). This message will include information on `writer_notification_zmq_addr`, +which needs to be used by downstream code. Since the start message must reference the address of `jfjoch_broker` host, notification +socket should always listen on a particular network interface, and should not be configured with placeholder address `0.0.0.0`. It is, however, OK +to use placeholder `:*` for network port, as it will be substituted for the one chosen by ZeroMQ. + +For every image stream socket, downstream code must send the following message to the PULL socket: +```json +{ + "run_number":135, + "run_name": "sample_1", + "socket_number": 1, + "processed_images":250, + "ok": true +} +``` +Here `run_number`, `run_name` and `socket_number` must match information from the start message. +`ok` is boolean confirming if the writing process was OK. +`processed_images` is number of images that were written/processed, this is to track how many images were ignored by non-blocking ZeroMQ procedures. +If the writing failed, an error message can be included: +```json +{ + "run_number":135, + "run_name": "sample_1", + "socket_number": 1, + "processed_images": 0, + "ok": false, + "error": "Permission error" +} +``` +This way errors from the downstream code are propagated to `jfjoch_broker`. + +If writer notification socket is configured, but downstream code doesn't send proper notification, `jfjoch_broker` will time out after 60 seconds producing an error message. + +## Preview stream +Jungfraujoch can also send images (with metadata) at a reduced frame rate for preview purpose. +Images are serialized as CBOR [image message](CBOR.md#image-message). +The stream will also include CBOR [start message](CBOR.md#start-message) and [end message](CBOR.md#end-message) with run metadata. + +This is using PUB socket with conflate option. I.e., only the last message is kept by ZeroMQ, so if receiver cannot cope +with the messages, it will always receive the last generated message (no backlog). +For this reason it is also recommended to use the same option on receiver side. + +Given PUB socket properties, it is possible to connect multiple viewers to a single socket --- all the viewers should receive all the images sent. + +The dark frames of the mask sequence from a DECTRIS detector are no images for a viewer: nothing is sent on +this stream for them, not even a start or end message. + +## Metadata stream +Jungfraujoch can also send pure metadata for the purpose of archiving such information. +Metadata are serialized as CBOR [metadata message](CBOR.md#metadata-message). +This is very similar to the image message, but excludes the image array, the spot list and the reflection list. +As metadata are relatively small, to avoid large number of messages, Jungfraujoch bundles metadata of many images in one message: +a bundle is cut every `period_ms` of the `zeromq_metadata` configuration and holds the images analysed since the last one. +Order of images within bundle, as well as the size of the bundle, are not guaranteed, and two bundles cut +close together can leave in either order; the end message is always last. +The stream will also include CBOR [start message](CBOR.md#start-message) and [end message](CBOR.md#end-message) with run metadata. +A disabled metadata stream keeps nothing, and the dark frames of the mask sequence from a DECTRIS detector +send nothing on it, as on the preview stream. + +This is using PUB socket with watermark, so there is some queuing of messages with ZeroMQ. Multiple receivers can be connected. \ No newline at end of file diff --git a/_sources/JFJOCH_BROKER.md.txt b/_sources/JFJOCH_BROKER.md.txt new file mode 100644 index 000000000..f50df98d3 --- /dev/null +++ b/_sources/JFJOCH_BROKER.md.txt @@ -0,0 +1,464 @@ +# jfjoch_broker + +`jfjoch_broker` is the main service for the Jungfraujoch application. It is responsible for: + +* Providing user interface via HTTP and OpenAPI +* Configuring FPGA firmware +* Building images from FPGA output and forwarding the results over ZeroMQ + +## External interfaces +Broker operates four external interfaces. + +**Image stream** ZeroMQ PUSH socket with CBOR serialization is used to send images, metadata and processing results for writing or downstream +processing. See details [here](IMAGE_STREAM.md#image-stream). + +**Preview stream** ZeroMQ PUB socket, as above but limited to subset of frames (1 image/s by default). See details [here](IMAGE_STREAM.md#preview-stream). + +**Metadata stream** ZeroMQ PUB socket, contains metadata for all the images, with bundling. See details [here](IMAGE_STREAM.md#metadata-stream). + +**Configuration, status and results interface** HTTP/REST interface described in the OpenAPI format. +Description of the API is presented in the [OpenAPI specification](OPENAPI_SPECS.rst). + +A dataset can be protected: `/start` takes an optional `tokens` list, and while the current dataset +has any, its statistics (`/statistics/data_collection`, `/result/scan`), buffered images +(`/image_buffer/*.cbor|jpeg|tiff`) and plots (`/preview/plot*`) need `Authorization: Bearer ` +and answer `401` otherwise; `/statistics` omits its `measurement` block instead. See +[Security](SECURITY.md#3-authenticated-read-access--per-dataset-bearer-tokens). + +`/start` also takes an optional `module_placement`: where the JUNGFRAU modules lie, as `rugnux` +measures them on an earlier run. rugnux writes it as `_module_placement.json`, a fragment of the +dataset settings (`{"module_placement": [...]}`) to merge into the `/start` body. Each entry has eight +required fields: it names its module as `custom_geometry` does - `x0`, `y0` (the image position of its +readout pixel 0) and `fast_axis`, `slow_axis` - but in the image as stored, after `mirror_y` (see below), +and gives where the module lies on the detector plane (`x0_plane`, `y0_plane`, `fast_step`, `slow_step`). +The first four identify the module, so the order does not matter, and a list that does not name exactly +the detector's modules (one left out, +named twice, or not the detector's) is refused with `400`. The module count and the assembly are the +configuration's (`custom_geometry` below); the placement only moves the modules relative to one another, +and goes into the start message, the master file's `module_NN` groups and the broker's analysis. See +[Module placement file](RUGNUX_FORMATS.md#module-placement-file-prefix_module_placementjson). + +## Broker configuration +`jfjoch_broker` requires JSON configuration files. The file is described by OpenAPI structure `jfjoch_settings` defined in `jfjoch_api.yaml` file. +It is recommended to go through example files in the `etc/`. +In `custom_geometry`, a module's `x0`, `y0` are where its readout pixel 0 goes in the image, and +`fast_axis`/`slow_axis` say which way its fast and slow readout axes run from there - in the image as +assembled, **before** `mirror_y`. The `module_placement` of `/start` uses the same words, but in the image +as stored, **after** `mirror_y`, because that is the only image a file reader (rugnux) sees. With `mirror_y` +on the two differ by the mirror: for an image of height H, `y0` (module_placement) = H - 1 - `y0` +(custom_geometry), `x0` is the same, and `Yp` and `Yn` swap in `fast_axis`/`slow_axis`. With `mirror_y` +off they are equal. + +Example configuration (`etc/broker_local.json`, `broker_eiger.json` and `broker_crmx.json` are +complete, runnable configurations; a detector takes either `standard_geometry` or `custom_geometry`, +never both): + +```json +{ + "pcie": [ + { + "blk": "/dev/jfjoch0", + "ipv4": "10.1.1.7" + }, + { + "blk": "/dev/jfjoch1", + "ipv4": "10.1.1.8" + } + ], + "zeromq": { + "send_watermark": 100, + "send_buffer_size": 1024, + "image_socket": [ + "tcp://1.2.3.4:5000", + "tcp://1.2.3.4:5001" + ], + "writer_notification_socket": "tcp://1.3.4.6:7000" + }, + "instrument": { + "source_name": "Swiss Light Source", + "source_type": "Synchrotron X-ray Source", + "instrument_name": "X06SA", + "pulsed_source": false, + "electron_source": false + }, + "detector": [ + { + "description": "EIGER 1M", + "serial_number": "E1M-01", + "type": "EIGER", + "high_voltage_V": 150, + "udp_interface_count": 1, + "module_sync": true, + "sensor_thickness_um": 320, + "calibration_file": [ + "/opt/jfjoch/eiger/trim/e1m-01.sn001", + "/opt/jfjoch/eiger/trim/e1m-02.sn002" + ], + "trim_energies_eV": [ + 12400 + ], + "hostname": [ + "e1m-01", + "e1m-02" + ], + "readout_time_ns": 3000, + "sensor_material": "Si", + "tx_delay": [ + 0,1 + ], + "base_data_ipv4_address": "10.10.10.50", + "custom_geometry": [ + { + "x0": 0, + "y0": 0, + "fast_axis": "Xp", + "slow_axis": "Yp" + } + ], + "mirror_y": true + } + ], + "detector_settings": { + "frame_time_us": 450, + "count_time_us": 0, + "internal_frame_generator": false, + "internal_frame_generator_images": 1, + "detector_trigger_delay_ns": 0, + "timing": "auto", + "eiger_threshold_keV": 6.0, + "jungfrau_pedestal_g0_frames": 2000, + "jungfrau_pedestal_g1_frames": 300, + "jungfrau_pedestal_g2_frames": 300, + "jungfrau_pedestal_min_image_count": 128, + "jungfrau_storage_cell_count": 1, + "jungfrau_storage_cell_delay_ns": 5000, + "jungfrau_fixed_gain_g1": false, + "jungfrau_use_gain_hg0": false + }, + "azim_int": { + "polarization_corr": true, + "solid_angle_corr": true, + "low_q_recipA": 0.01, + "q_spacing": 0.002 + }, + "image_format": { + "summation": true, + "geometry_transform": true, + "jungfrau_conversion": true, + "jungfrau_conversion_factor_keV": 0.001, + "bit_depth_image": 16, + "signed_output": true, + "mask_module_edges": true, + "mask_chip_edges": true, + "apply_mask": true, + "jungfrau_pedestal_g0_rms_limit": 100 + }, + "image_buffer_MiB": 2048, + "receiver_threads": 64, + "frontend_directory": "/usr/share/jfjoch/frontend", + "image_pusher": "ZeroMQ", + "zeromq_metadata": { + "enabled": true, + "period_ms": 1000, + "socket_address": "tcp://0.0.0.0:4357" + }, + "zeromq_preview": { + "enabled": true, + "period_ms": 1000, + "socket_address": "tcp://0.0.0.0:4356" + } +} +``` + +`standard_geometry` (`nmodules`, `modules_in_row`, `gap_x`, `gap_y`) is the alternative for a regular +module grid. For an EIGER `hostname` lists two entries per module (one per half-module) and +`calibration_file` is either a directory of trim files or one trim file per half-module, with the energies +they were trimmed at in `trim_energies_eV`; for a JUNGFRAU both are one entry per module, the +calibration being the gain maps. The polarization factor of the azimuthal integration is a dataset +setting (`/config/dataset`, `polarization_factor`), not part of `azim_int`. The Q bins of `azim_int` +are linear by default, set by `q_spacing` (0.01 Å⁻¹ when nothing is given) or by their number, +`q_bins` - one or the other, not both. `"q_binning": "log10"` lays them out in equal steps of +log10 Q instead (fine at low Q, coarse at high Q); it takes `q_bins` and refuses `q_spacing`. +A GET returns the one that was set, so once `q_bins` (or log10) is configured the reply carries +`q_bins` and no `q_spacing`, which a client generated before `q_spacing` became optional cannot parse. + +## Following a collection + +A reader can process a collection while it is being written - rugnux does, given the path the master +file will have and the broker's address (`rugnux _master.h5 http://:/`), started +any time after `/start` was accepted. The images still travel as files; the broker says which files +exist. `GET /live/events`, protected by the dataset's bearer tokens like the other dataset routes, +streams server-sent events for the current collection from the moment `/start` accepted it: its +history first, then every change. `start` comes first, once the start message is known - at once +for a JUNGFRAU, when the detector sends its own for a DECTRIS - with that start message (CBOR, in +base64); a reader builds the dataset from it. Then `file` (file number, file name relative to the +collection's root, first image, image count) for each data file a writer has closed and renamed into +place, and `end` (images collected, and an error if any) once every writer has acknowledged the end, +so the data files and the master file are in place - or, with an error, when the measurement ended +any other way. A comment line every 10 s keeps the connection alive. One reader at a time; a second +one gets 409. + +The writers report each closed data file to the broker (TCP protocol version 5, an acknowledgement +for `FILE_CLOSED`); the in-process HDF5 writer reports to it directly. The ZeroMQ writer has no way +back to the broker, so with it the route answers 409. + +## Online analysis + +Without rugnux live mode, and in the FPGA workflow also for a rotation collection with it, the broker analyses each +image on its own: masking, summation, azimuthal and ROI integration, spot finding, and - with indexing on - indexing +of the image and refinement of its geometry (`geom_refinement_algorithm`). A rotation collection is indexed image by image, as a serial +one. The broker neither integrates Bragg reflections nor determines a lattice for the whole rotation sweep, so the +reflections, the per-image B-factor and integrated-reflection count, and the rotation lattice are filled only where +rugnux processed the data: by rugnux live mode (below) during the collection, or by `rugnux` from the written files. +`indexing_settings.rotation_indexing`, `rotation_indexing_min_angular_range_deg`, +`rotation_indexing_angular_stride_deg` and `spot_finding_settings.quick_integration` are deprecated: accepted, ignored, +and returned at their old defaults. `bragg_integration_settings` apply to rugnux live mode. + +### The receiver of a run + +Each run is taken by one receiver, chosen when it starts from the detector type, the detector mode, the +goniometer and the rugnux live setting: + +| Input | Run | Receiver | What it does | +|---|---|---|---| +| FPGA cards (PSI JUNGFRAU, PSI EIGER) | every run | `JFJochReceiverFPGA` | the card's converted pixels, spots, azimuthal and ROI sums into the image; summation on the host above what the card sums; indexing of each image; the calibration to the writer; pedestal runs into the pedestal and its RMS; with rugnux live on, a serial run analysed on the GPU after a rugnux pre-pass (see [Serial collections](#serial-collections-experimental)) | +| DECTRIS stream | dark-mask sequence | `JFJochReceiverDarkMask` | the dark frames into the mask; nothing on any stream | +| DECTRIS stream | rugnux live off, or a rotation run the image buffer cannot hold | `JFJochReceiverLite` | each image on the GPU: masking, azimuthal and ROI integration, spot finding, indexing | +| DECTRIS stream | rugnux live on, rotation that fits the image buffer | `JFJochReceiverRugnuxRotation` | images forwarded as they come; rugnux reads the collection back from the image buffer and runs the whole pipeline | +| DECTRIS stream | rugnux live on, serial (or rotation with `force_still`) | `JFJochReceiverRugnuxStills` | a rugnux pre-pass on the first frames, then every frame analysed and integrated on the GPU and merged live | + +`receiver_threads` is the number of image threads. The Lite receiver uses at most 16 of them for a +collection at 100 Hz or slower or of fewer than 256 images (each thread holds a GPU analysis of its +own); the FPGA receiver takes four when it sums images on the host. The GPU FFT indexers and cuFFT +plans the broker's own indexing uses are built once and kept for the life of the process, and the ones +built for earlier indexing settings are released when the settings change. `azim_int.force_cpu` +moves the azimuthal integration of the FPGA workflow from the card to the host, which a profile with +more bins than the card holds needs. + +## Rugnux live mode + +With rugnux live mode on, collections from a DECTRIS detector are processed inside the broker while they +arrive: rotation collections by rugnux, and serial (stills) collections on the GPU with the geometry and mask a +rugnux pre-pass decided (see [Serial collections](#serial-collections-experimental) below). In the FPGA workflow +(PSI JUNGFRAU and EIGER) serial collections are analysed on the GPU after a pre-pass as well, with the differences +given there; rotation collections run image by image, as with the mode off. It is off by default; the +configuration file switches it on with +`"rugnux": {"enable": true, "reserved_cpus": 4}`, where `reserved_cpus` is the number of CPU threads +left to the receiver and the image pusher. + +For a rotation collection, rugnux reads the images back from the broker's image buffer, so the buffer must hold the whole +collection - one slot per image. Where it holds fewer, the collection gets the per-image analysis of +the mode off (spots, indexing, scan result); the live status reports it as skipped and the collection's +statistics carry a warning saying how many images the buffer holds against how many the collection has. + +The results - the merged data, the map coefficients and, with a model, the placed model and its +refinement - travel to the writer in the end message, which writes them beside the master file as +`.mtz`, `_maps.mtz`, `_model.cif` and `_model.pdb`, +and `_refined_model.cif` (and `.pdb`), `_refined_maps.mtz` and +`_blobs.json`, as rugnux names them, and the results report `_report.txt` - the +report `rugnux` writes for its runs. These files name both programs as the software that +made them: the MTZ files in a HISTORY record beside Rugnux's, the models in their `_software` loop +(Rugnux, and Jungfraujoch for the data collection). An end message +that would be too large for the pushers' buffer (256 MiB) goes without them, with an error in the log +and a warning in the live status; the collection itself is not affected. + +The same settings are read with `GET /config/rugnux` and changed with `PUT /config/rugnux`. A model +for molecular replacement and validation (PDB or mmCIF, optionally gzipped, at most 64 MiB) is +uploaded as the raw file with `PUT /config/rugnux/model` (`application/octet-stream`; a larger body +gets `413`, an empty one or one that cannot be read as a model `400`). The broker parses it at upload +and keeps it in memory - nothing is written to disk - for every following collection until +`DELETE /config/rugnux/model` removes it or another upload replaces it; a broker restart drops it. +`GET /config/rugnux` reports whether a model is loaded and its size, never its contents. Changes are +refused during a collection. Like the rest of the configuration these routes need no bearer token: +they prepare the next collection and expose nothing of the current one. + +Two more settings correspond to rugnux's options, both off by default and turned off again by +`POST /initialize`, as `enable` and the model are. `refine_solvent` (`rugnux --refine-solvent`) has the refinement of +a placed model build the solvent as well: waters added at difference-map peaks and removed where the maps no longer +hold them, waters and ions relabelled; `model.refinement` in `/rugnux/status` then carries `waters_added` and +`waters_removed`. `force_still` (`rugnux --force-still`) sends a rotation collection from a DECTRIS detector the +serial way: pre-pass, GPU analysis and stills merge (see [Serial collections](#serial-collections-experimental)). +The analysis takes the frames without the goniometer; the master file keeps it. It does not change the FPGA workflow. + +The end message, and with it the end of the collection, waits for the analysis. `deadline_s` (default +60 s; 0 for no cutoff) bounds that wait: this long after the last image the analysis is cut. `POST /cancel` is +the other way to cut it: while images still arrive it cancels the collection as with the mode off, +and the analysis with it - the live status then ends with verdict `CANCELLED` and the images that came before +the cancel; after the last image it ends only the analysis. A cut analysis gives what it +has established: a pass that is past its images still merges and makes its outputs, the canonical pass +cut among its images merges those it has read, only the placed model is left out, and +any other pass cut short gives way to the last one that ran to its end. The end message goes out at +once with that, and the live status records the cut (`deadline` or `cancel`) and when. + +Where the uploaded model is placed, it is refined as `rugnux` refines it, after every decision of the run +and before the end message - seconds on a GPU, minutes on a broker without one. A cut before it starts leaves it out, as the model; a +cut while it runs cuts it short with what its finished weight trials found (`model.refinement.cancelled`). The refined model and its maps stay with the broker: the +writer writes the placed model, as without refinement. `GET /rugnux/status` gives the refined R-work and +R-free, the bond and angle rmsd, the time it took and the unexplained blobs of the refined difference map +(`model.refinement`), and `/rugnux/model.cif` and `/rugnux/map.ccp4` serve the refined model and its maps +(`stage=placed` for the model as placed; the anomalous map is always on the placed model's phases). + +`GET /rugnux/status` reports the live run of the last collection, kept until the next one starts or +`POST /rugnux/clear` (the "Clear" button of the "Rugnux live" page) puts it back to `Idle`, as before any +collection - refused during a collection; the images and the collection's plots are kept. It gives the +state, the images received, the step it is on and how far into it, the steps so far with what each +found, and once it is over the verdict, the summary, warnings and the time from the last image to +every result written. `shells` carries the merging statistics by resolution shell - the rows of the shell +table of `_report.txt`, on the same shells: multiplicity, ⟨I/σ⟩, completeness, CC1/2, R_meas +(rotation), R_split (serial), CCref (with reference data) and the R-free of the placed model as given (with a +model), each absent where the run does not measure it - and `shells_merge` the merge they are of. A rotation +run fills them when it is over; a serial one at each provisional merge and at the end, the R-free once the model +step on that same merge has its result. A rotation run also leaves `frame_scales`, the per-image scale factor of +the merge, and `frame_ranges`, the stretches of the sweep the merge downgraded or rejected (the report's SWEEP +section) with the reason it saw there - which frames rugnux left out, and why. The web frontend shows it on the +dashboard and in its "Rugnux live" tab, which plots the shells against resolution and the collection image by +image, changes the settings and uploads the model. It, `/rugnux/model.cif` and `/rugnux/map.ccp4` need the dataset's bearer token +like the dataset routes (`/statistics/data_collection`, `/image_buffer/*`, `/preview/plot*`). `GET /result/scan` carries the rotation lattice, unit cell and Bravais symbol +rugnux found. A collection in which rugnux finds no lattice still gets the spot count, resolution +estimate and background of every image in `GET /result/scan` and the master file, marked as not indexed. + +`triage` is the pathology checklist of the SUMMARY of `_report.txt`, built from the same result, so +the two always agree: one entry per condition the report lists (twinning, pseudo-symmetry, multiple lattices, +ice and powder rings, anisotropy, completeness, sweep gaps, supercell, overloads, ...), plus one for every +other warning that fired (e.g. `SCALING_NOT_CONVERGED`). Each has the report's label and words, the +`PATHOLOGY_FLAGS` codes it stands for and the warnings behind it, and a `severity`: `ok` - looked for and not +found; `attention` - its warning fired; `serious` - nothing usable came out (no lattice, or a merge without +signal: the report's verdict FAILED or UNUSABLE); `not_measured` - not looked for on this run. A rotation run +fills it when it is over; a serial one at each provisional merge and at the end, each merge analysed for +twinning, pseudo-translation and anisotropy as `rugnux` analyses its final merge, with the indexing ambiguity's +resolution (where the cell and space group admit one) as a row of its own. The serial merge has no pre-scan, +so on serial data the powder, ice and multiple-lattice conditions are `not_measured`. The "Rugnux live" tab +lists the conditions that fired first, in orange or red, then the green ones, with the report's warnings on +hover, and names the unmeasured ones in one line. + +### Serial collections (experimental) + +Live processing of serial collections is **experimental**. With rugnux live mode on, a serial +(non-rotation) collection from a DECTRIS detector, in the standard detector mode, is analysed frame by frame: the +frames as the stream delivers them go to GPU spot finding, indexing and integration, with rugnux's stills spot +finder (adaptive threshold, single-pixel spots kept). Before any frame is analysed, the first +500 frames are run through rugnux, in memory, as `rugnux --no-merge` would run on them. That pre-pass +decides the beam centre, refines the detector distance (where the dataset settings give a unit cell) and +masks the beam-stop shadow and defective pixels; every frame of the collection is then analysed with that +geometry and mask. The start message waits for the pre-pass, so it states them, and the end message carries +the centre and distance used (`refined_beam_center_x/y`, `refined_detector_distance_mm`, +[CBOR](CBOR.md)). The broker's own distance is taken as the beamline's: unlike offline rugnux, the pre-pass +does not search the whole distance range. It refines the centre and distance for a detector square to the +beam, as the frames are then analysed. At a serial hit rate the distance needs the 500 frames to be refined at +all: on fewer, too few index for the geometry refinement to run, and the stated distance is kept. The pre-pass +holds and fits on at most half the slots of the image buffer (a slot is the size of an uncompressed +frame), so a smaller buffer starts it on as many as that. + +Where a unit cell is given and those frames are too few for the geometry fit (200 indexed frames), frames go on +being held and the pre-pass runs again on all of them each time they have doubled, until the fit has its frames, half +the image buffer or 2000 frames are held, or the collection ends; frames arriving during a run do not make the next +one larger than that, so the last run stays short. The analysis starts when the pre-pass ends and catches up from the +frames waiting, so it starts later on a low hit rate. + +The geometry is fixed when the pre-pass ends and does not change during the collection, so every frame is analysed +and merged at it and the radial profile has one binning throughout. Where the pre-pass could not refine it (too few +of its frames indexed, as with a small image buffer, a low hit rate or a chip whose first frames are empty, or no unit +cell given), the distance in the header is used for the whole run: this is a warning in the log and a note of the +live status, and a wrong header distance then costs resolution and indexed frames. + +Frames arriving during the pre-pass, or faster than the analysis, wait in the image buffer, in all its slots but +one per analysis thread, kept for sending; a frame that finds it full is dropped and counted as for a full image +buffer, so analysis slower than the frame rate costs frames, not memory. Where the writer lags behind, the analysis +waits for slots to come back. A pre-pass that fails leaves the stated geometry and +mask in use. Where the start message cannot be sent after the pre-pass (no writer listening) or the analysis +cannot be set up, the collection ends with that error, reported by `/status` and `/wait_till_done`, and the +next `/start` runs as usual. + +The indexed frames are also merged, as `rugnux --mode scale` merges stills, in memory - in the consensus cell +of the frames indexed by the first merge (the cell of the dataset settings only picks the frames that are +merged) and the space group of the dataset settings (else P1). +At half and at three quarters of the images the frames so far are merged beside the analysis, on 8 threads, and +the result is reported as a provisional step note: crystals, resolution, CC1/2, R_split, completeness and +⟨I/σ⟩. The first of these merges scales and post-refines every crystal so far and decides the indexing +ambiguity from the data; every crystal after it is placed in its indexing, scaled and post-refined against +the latest of them as it arrives. After the last frame only the error model, the merge, the resolution cut +and the statistics are left to do, on every thread - a few seconds for a chip of 160,000 frames on the full +JUNGFRAU 8M, against about half a minute for the same merge made from nothing. The merged data travel to the +writer in the end message, as for rotation (`.mtz`), and the run's step "Merge" carries the +final statistics. + +With an uploaded model, the model step runs on every one of these merges, as `rugnux --mode scale --model` +places a model and `rugnux --mode refine` refines it: the model is placed by its rigid body where it fits the +data as given - its indexing ambiguity probed by R-free, and the merge put in the model's indexing - and by +molecular replacement where it does not (or is a prediction); the 2mFo-DFc and mFo-DFc maps are made, and the +placed model is refined, with the blobs of its difference map. Without a space group in the dataset settings +the frames are merged in the model's own, where the model's cell is the consensus cell of the run on the same +axes; otherwise the model is left out, with a warning in the live status saying why. The step on a provisional +merge runs on a thread of its own, on 8 CPU threads and the GPU, beside the analysis and the merge, which do not +wait for it: its result - the placed and the refined model, their maps, the scores - goes to the live status +(`model`, `/rugnux/model.cif`, `/rugnux/map.ccp4`) as soon as it is made, so the density can be looked at while +the collection goes on. A step still running when the next merge is made is cut (a refinement cut short keeps +the weight trials it finished), and each step starts from the placement of the one before: the merge is put in +the same indexing, and the model goes in where it was placed, with no null, indexing probe or search made again. +After the last frame the step on the merge of the collection runs on every thread, and the end message waits +for it until `deadline_s` after the last image; then it is cut as for rotation - the refinement first (cut +short, or left out where it has not started), and a molecular replacement that has not started. The end message +carries the merge in the model's indexing (`.mtz`), the map coefficients, the placed and the +refined model, the refined maps and the blobs, written as for rotation; one that would not fit the pushers' +buffer goes without them. The GPU memory the analysis's indexers hold for the broker's life is counted against +the card when the model step decides what goes on it. `POST /cancel` cuts it +the same way, at any time (`cut` in `/rugnux/status`): the frames that came are still analysed and merged. + +The frames wait in the image buffer compressed, and go on to the writer byte for byte, with their analysis. `efficiency` is the +images received over the images expected; a stream has no module packets, so per-image collection +efficiency, ADU histograms and pulse IDs are absent. The dark frames of the mask sequence stay outside this mode. + +`GET /rugnux/status` reports such a run as three steps (pre-pass, GPU analysis, merge; with a model, the steps of +the model on the merge of the collection after them) and a `stills` block: the +pre-pass state and duration, the stated and decided beam centre and distance, the pixels masked, and the +images analysed and indexed with the analysis rate. The "Rugnux live" page of the web frontend shows the +same. `tools/jfjoch_stills_gpu_replay` replays a stored serial collection through the same analysis. + +In the FPGA workflow (JUNGFRAU), a serial collection with rugnux live mode on is analysed by the receiver of the +card (`JFJochReceiverFPGA`) with the pre-pass, the GPU analysis and the live merge described above, with three +differences: the converted frames wait for the analysis in at most half of the image buffer's slots, a frame that +finds them taken is dropped, and there is no model step - an uploaded model is not placed or refined on these +merges. The end message carries the merged data, as for a DECTRIS stream. + +## Setting up a local test for Jungfraujoch +For development, it is possible to set up a local installation of Jungfraujoch. +This will work without FPGA installed in the computer and allows testing the Jungfraujoch software layer, including +ZeroMQ streaming and file writing. + +The workflow simulates FPGA behavior, by running high-level synthesis code on the CPU - the performance is therefore +very low, as fixed-point calculations have a large performance penalty on the CPU. In the CPU simulation mode, one can simulate +using only a single FPGA device. + +To run the test: + +### Compile Jungfraujoch with frontend +``` +mkdir build +cd build +cmake .. +make jfjoch_broker +make frontend +``` +Alternatively, on a RHEL8 system, you can use the RPMs generated by the automated pipeline. +The `jfjoch` package alone is enough. +In this case - it is necessary to update `etc/broker_local.json` file with frontend path in `/usr/share/jfjoch/frontend`. + +### Start service +Start broker (the HTTP port is optional; the default is 5232, listening on all interfaces): +``` +cd build/broker +./jfjoch_broker ../../etc/broker_local.json 5232 +``` + +### Run tests +To run the test, a Python script is provided: +``` +cd tests/test_data +python jfjoch_broker_test.py +``` +The script will initialize Jungfraujoch, import test image and start data collection. + +### Expected result +You can observe online data analysis by opening the following web page: [http://localhost:5232](http://localhost:5232). +Also, a dataset with images should be written in the `build/broker` directory. + diff --git a/_sources/JFJOCH_VIEWER.md.txt b/_sources/JFJOCH_VIEWER.md.txt new file mode 100644 index 000000000..7103a42e2 --- /dev/null +++ b/_sources/JFJOCH_VIEWER.md.txt @@ -0,0 +1,355 @@ +# jfjoch_viewer + +`jfjoch_viewer` is the **interactive** desktop application of Jungfraujoch. It opens diffraction +datasets, displays each image together with the analysis overlay (spots, predictions, azimuthal +integration, per-image statistics), and can follow a live data collection by syncing with a +running [`jfjoch_broker`](JFJOCH_BROKER.md) over its HTTP interface. + +It is a standalone Qt 6 application, distributed pre-built for **Linux, Windows and macOS** on the +[download page](VIEWER_DOWNLOAD.md), and for Linux also in the Jungfraujoch RPM/APT repositories — see +[Release contents](RELEASE_CONTENTS.md) for what each package contains and what it requires, and +[Deployment](DEPLOYMENT.md) for how to install it. The macOS build needs **macOS 13 (Ventura) or +newer on an Apple Silicon Mac** (M1 and newer; Intel Macs are not supported) and has no CUDA — see +[Release contents ▸ macOS](RELEASE_CONTENTS.md#macos). + +## Where it fits among the three analysis tools + +| Tool | Mode | Driven by | Output | +| --- | --- | --- | --- | +| [`jfjoch_broker`](JFJOCH_BROKER.md) | Online, real-time streaming analysis on FPGA + GPU | HTTP/REST + ZeroMQ | Live results and statistics, images streamed to [`jfjoch_writer`](JFJOCH_WRITER.md) | +| **`jfjoch_viewer`** | **Interactive, on-screen exploration** | **Qt desktop application** | **On screen; a processing job can write the same files as `rugnux`** | +| [`rugnux`](RUGNUX.md) | Offline batch processing of a stored dataset | Command-line interface | `.mtz`/`.cif`/`.hkl` and the results report when merging (the default); `_process.h5` with `--no-merge` or `--write-process-h5` | + +## Functionality + +- Opens HDF5 files written by [`jfjoch_writer`](JFJOCH_WRITER.md) (`*_master.h5`) and the + `*_process.h5` files produced by [`rugnux`](RUGNUX.md). It also opens NXmx files + written by DECTRIS detectors, though that path has had only limited testing. +- Opens PILATUS miniCBF, marCCD and SMV rotation sweeps (the formats listed under + [Input formats](RUGNUX_FORMATS.md)). These store one frame per file, so naming any frame opens + the whole sweep it belongs to. A raw frame carries the images and the geometry but no analysis + results, so the spot, reflection and per-image plot panels stay empty until something is computed. + A processing job on such a sweep writes the images into its `_process.h5`, and its run is shown from + that file like a run of an HDF5 dataset; *Original* goes back to the sweep. +- Runs an **embedded data-processing pipeline** — the same analysis code as the rest of + Jungfraujoch — performing spot finding, indexing and integration on the displayed image, with the + result drawn over it. This interactive analysis is not written anywhere. +- Runs **full processing jobs** on the open dataset with *Analyze dataset*, on the same + [`rugnux`](RUGNUX.md) engine and off the GUI thread. The settings panel's **MX / AzInt / Calib** + toggle decides what a run does — full analysis, azimuthal integration only, or a detector + calibration — over a chosen image range, optionally writing `_process.h5` and the merged + `.mtz`/`.cif`. A finished run becomes a selectable view of the dataset, so several processing runs + can be compared against each other, and its merging statistics (or, for a calibration, its fitted + geometry) open in their own window; the *Processing* panel lists the runs and reopens those + results. The equivalent `rugnux` command line can also be copied out to run the same job on a + cluster instead. +- **Detector calibration** against a powder standard, on the *Calib* page: pick the calibrant + (`LaB6`, `AgBh`, `CeO2`, `Si`, `ice`, or the open dataset's own unit cell) and fit either the image + on screen (*Guess* / *Refine detector calibration*) or the whole dataset (*Analyze dataset*, which + writes a pyFAI `.poni`). The whole-dataset fit measures the rings either from the + azimuthally-binned profile summed over the run (*Rings*, the default) or from the pooled spot lists + (*Spots*), and reports PONI x/y, the two tilts and the distance against the header values. Judge it + by the **radial rms**, not the beam-centre sigma: the sigma shrinks with the number of ring points, + so a fit that sits a couple of pixels off every ring can still report a small one. *Rings* needs + the run to be integrated in azimuthal sectors — with the AzInt page's *Azimuthal bins* below 4 the + calibration run raises it to 32, as `rugnux --mode calibration` does, and says so. + *Refine detector tilt* is ticked by default and fits the two tilts along with the centre and the + distance; unticking it holds them where they are, for a calibration meant for a program that + cannot express a tilted detector (`rugnux --no-refine-tilt`). It applies to both buttons and to + *Analyze dataset*. +- **Settings** panel for the geometry, unit cell, spot finding, indexing, azimuthal integration, + Bragg integration, scaling, powder calibration and a reference dataset — the same settings the + CLI takes. +- Auxiliary windows: image list, dataset metadata, spot list, reflection list, + 2D azimuthal-integration image and calibration-image viewer; plus the + *Inspector* (per-image statistics, image features, resolution rings, ROI statistics), the + *Magnifier* below it (three zoom levels: ×64 and ×32 with the pixel values written on the pixels, + ×10 without; *Pop out* moves it to a window of its own) and dataset-info charts. +- The *Inspector*'s **Image features** section decides what the overlay draws — spots, predictions, + saturated and highest pixels, the beam stop — including whether the non-indexed spots and the + spots that fall on an ice ring are drawn at all. +- User-mask editing: build a user mask interactively, load one from TIFF (replacing or adding to the + current one), save it as TIFF, clear it, or upload it to a connected server. +- Mouse-driven navigation of the image, the grid scan and the plots — see + [Mouse shortcuts](#mouse-shortcuts) below, which the viewer also shows under *Help ▸ Mouse + Shortcuts*. +- *Help* shows the mouse shortcuts, the [acknowledgements](ACKNOWLEDGEMENT.md) and the third-party + licenses. +- Layout presets (*View ▸ Image layout / Processing layout / Reset layout*) rearrange the docks for + looking at images or at processing results. +- *View ▸ Theme* picks the light or the dark colour scheme, or *Follow system*. Following the + system needs a desktop that tells Qt its scheme: macOS and Windows do, and so do GNOME and KDE + sessions on Linux (elsewhere, `QT_QPA_PLATFORMTHEME=xdgdesktopportal` reaches the portal + setting); a session Qt cannot read - a bare X server, `ssh -X` - counts as light. The choice is + remembered across restarts, and the half-sun toolbar button toggles light and dark directly. +- *View ▸ Font size* (or `Ctrl`+`+` / `Ctrl`+`-`) enlarges the text to 125 % or 150 %, on top of + whatever scaling the desktop already applies, and the choice is remembered across restarts. The + viewer also follows the desktop's own text scaling or display scaling on its own; over `ssh -X`, + where no settings daemon delivers it, launch as `QT_SCALE_FACTOR=1.5 jfjoch_viewer` instead. + +## A guided tour + +Four views cover most of what the viewer is used for. The screenshots show the lysozyme reference +sweep of the in-house test set and a raster scan. + +### Looking at an image + +`jfjoch_viewer ` opens the file and shows its first image; **File ▸ Open** and the toolbar's +open button do the same, and **File ▸ Open HTTP** connects to a running `jfjoch_broker` instead. + +![The general view: diffraction image, inspector and dataset-info plot](images/viewer_general.png) + +The top toolbars step through the images (slider, first/previous/next/last, `Jump` and `Sum` for +summing consecutive frames) and set the display (foreground limit, `Auto` contrast, HDR, colour +map, font size, theme). The background limit has a slider of its own, shown from *View ▸ +Background slider* or as soon as `B` + wheel raises it; `Auto` sets it back to zero. The image in the middle zooms with the wheel and +pans by dragging; hovering shows the pixel position, its value and the resolution on the status +bar. The **Inspector** on the right lists the dataset's metadata and, once an image has been +analysed, its spot count, background, indexing result and resolution estimate; the **Magnifier** +under it follows the cursor while `Shift` is held. On a window too narrow for both, the inspector (with the magnifier) folds +away and comes back when the window is widened again. The **Dataset info** dock at the bottom plots a per-image quantity +over the whole sweep - background here; the combo offers spot counts, indexing results, scale +factors and more once they exist - and `Shift`-hover on it loads the hovered image. + +### A grid scan + +A raster scan opens on its two-dimensional map: each cell is one image, coloured by the metric +chosen in the combo (spot count by default for a grid scan), so the crystal shows up as the bright +region. `Shift`-hover or double-click a cell to load that image. + +![A grid scan on its map, with the spot count per position](images/viewer_grid_scan.png) + +The **Grid** button switches between the map and the per-image line plot; a grid scan remembers +its own preferred plot, independently of the one used for rotation data. + +### Processing settings + +The **Processing** dock on the left (the tab next to **Files**, or **View ▸ Processing layout**) +holds every setting the analysis takes: geometry and unit cell, the goniometer, spot finding, +indexing, Bragg integration, scaling, and the reference dataset (MTZ or structure-factor mmCIF) +with an optional atomic model to validate the merged data against. The MX / AzInt / Calib switch +selects the kind of analysis and its page. + +The panel starts from the defaults of a bare `rugnux `, which the viewer and the command line +share, so an *Analyze dataset* run with nothing changed processes the data as `rugnux` would; the one +intended difference is that the viewer writes `_process.h5`. **Known unit cell** starts unticked when +a file is opened, and again when a run's results are shown: the cell and space group the file or the +run carries are filled in but not used until it is ticked (`-C`/`-S`), so a run determines the crystal +from the data, as `rugnux` does. The azimuthal-integration settings apply to AzInt jobs only; an MX job +integrates its profile (for the ice-ring score and the background estimate) with `rugnux --mode mx`'s +defaults. + +![The Processing dock with the spot finding, indexing and reference sections open](images/viewer_processing_settings.png) + +**Analyze image** re-analyses the current image with these settings, now and on every change +while it stays pressed; the inspector and the image overlays update at once. + +### Processing results + +**Analyze dataset** runs the whole sweep through the same pipeline as `rugnux` (a job dialog +takes the image range, the thread count and which files to write, and **Copy command** gives the +equivalent command line for a cluster, leaving out `-N`, `--max-spots` and `--integration-radius` +where the run left them to `rugnux`, so that the copy makes the same automatic choices). The +**Jobs** dock follows the run. + +![A finished job: the jobs table and the merge statistics window](images/viewer_processing_results.png) + +When it finishes, the job's graph button opens the merge statistics (completeness, CC1/2, I/sigma +per resolution shell, and the text report). The window names the space group with its screw axes +subscripted and lists the crystal pathologies the report checks, one light each: green where the +check was made and did not fire, red where it fired (its warning in the tooltip), grey where the data +could not answer it. The dataset-info combo gains the per-image +indexing result, mosaicity, integrated reflections and scale factors of that run, plotted next to +the original file's values. + +## Hardware + +As with the rest of Jungfraujoch, **serious performance requires an NVIDIA GPU**. On systems with a +GPU, use the CUDA build (a separate package variant everywhere: RPM/APT repository, `.tgz` and +Windows installer) for the embedded indexing and integration; the non-CUDA build runs the same +pipeline on the CPU at much lower throughput. The CUDA build also runs on a machine without a GPU — +see [Release contents ▸ CUDA and non-CUDA builds](RELEASE_CONTENTS.md#cuda-and-non-cuda-builds). + +The CUDA build needs an NVIDIA **driver** on the host but no CUDA toolkit — 525.60.13 or newer for +the CUDA 12 artefacts (RHEL 8 packages, portable Linux `.tgz`), 580.65.06 or newer on Linux and an +R580 driver on Windows for the CUDA 13 ones (RHEL 9, Ubuntu, Windows installer). The Windows +installer and the `.tgz` are CUDA 13 and CUDA 12 respectively, which also decides the oldest GPU +they run on — a V100 needs the CUDA 12 `.tgz`. See +[Release contents ▸ GPU generations and the NVIDIA driver](RELEASE_CONTENTS.md#gpu-generations-and-the-nvidia-driver). + +On a Mac there is no CUDA: the viewer runs the same pipeline on the CPU, with the FFTW indexer, like +the non-CUDA build elsewhere, except Bragg integration, the model density and the molecular-replacement +rotation function, which run on the Apple GPU through Metal. + +### Remote displays + +The viewer detects a remote display session (`ssh -X` and the like) and limits how often panning, +zooming and live playback repaint, since on such a link every repaint is shipped as pixels. The +detection can be overridden in *View ▸ Remote display mode* or with `JFJOCH_VIEWER_REMOTE=0`/`1`. +A VNC- or xpra-based remote desktop still transports the viewer far more efficiently than plain +X11 forwarding. + +## Mouse shortcuts + +The same list is available in the application under **Help ▸ Mouse Shortcuts**. + +On macOS, `Ctrl` below means the Command key (`⌘`); right click is also `Ctrl`-click, and on a +keyboard without them `Home` / `End` are `Fn`+`←` / `Fn`+`→` and `Page Up` / `Page Down` are +`Fn`+`↑` / `Fn`+`↓`. The Mouse Shortcuts window shows the Mac keys directly. + +### Diffraction image + +| Action | Effect | +| --- | --- | +| Wheel | Zoom in / out, centred on the cursor | +| `Shift` + wheel | Move the foreground (upper contrast limit) in linear steps | +| `Ctrl` + wheel | Move the foreground in multiplicative steps (×1.15 per notch) | +| `F` held + wheel | Same as `Shift` + wheel, for as long as `F` is held | +| `B` held + wheel | Move the background (lower contrast limit) in linear steps, for as long as `B` is held; shows the background slider | +| `A` | Apply auto-contrast once (background back to zero); press it again to switch on continuous Auto | +| `Home` / `End` | Jump to the first / last image in the dataset | +| `Page Up` / `Page Down` | Step one image forward / back | +| Hover | Status bar shows the pixel position, its value and the resolution | +| Drag | Pan the image | +| `Shift` + move | Move the magnifier panel to the cursor; a frame shows the area it covers | +| `Shift` + drag | Draw a rectangular ROI | +| `Shift` + `Ctrl` + drag | Draw a circular ROI | +| Drag an ROI or its handle | Move or resize the selected ROI | +| Right click | Copy / save the image, fit to view, clear the ROI | + +### Grid scan + +| Action | Effect | +| --- | --- | +| Hover | Status bar shows the image number, the grid position and its value | +| `Shift` + hover | Load the image under the cursor while moving over the grid | +| Double click | Load the image under the cursor | + +### Other views + +| Action | Effect | +| --- | --- | +| 2D azimuthal image: double click | Zoom the diffraction image on the corresponding detector position | +| Dataset-info plot: hover | Status bar shows the image number and the plotted value | +| Dataset-info plot: `Shift` + hover | Load the hovered image | +| Spot / reflection list: double click | Zoom the diffraction image on that spot or prediction | +| Image list: double click | Load that image | + +## Opening data + +- **File ▸ Open** (`Ctrl+O`) — open a local HDF5 file, or any frame of a miniCBF, marCCD or SMV sweep. +- **File ▸ Open HTTP** (`Ctrl+H`) — connect to a `jfjoch_broker` HTTP endpoint to follow a live + collection. The dialog defaults to host `localhost` and port `8080`; these defaults can be + overridden with the environment variables `JUNGFRAUJOCH_HTTP_HOST` and `JUNGFRAUJOCH_HTTP_PORT`. + The scheme box selects `http://` or `https://` (the latter for a broker behind a TLS proxy), and + the **Token** field takes the dataset's bearer token when the collection was started with one. + The token can also come from `JUNGFRAUJOCH_HTTP_TOKEN` or from D-Bus (below); what is typed in the + dialog overrides both, and nothing is stored between sessions. Without a valid token for a + protected dataset the viewer shows nothing and says so on the status bar — no dialog, since a + dataset changing hands is the normal reason. +- **Command line** — `jfjoch_viewer ` opens a file (or an `http://host:port` URL) on + start-up. `--dbus ` (`-d`) enables or disables the D-Bus interface (default: enabled); + `--help` and `--version` behave as usual. + +## D-Bus interface + +When enabled, the viewer registers the D-Bus interface `ch.psi.jfjoch_viewer`, so other processes +can drive it. D-Bus is **Linux only**: the Windows and macOS builds have no D-Bus interface, and +`--dbus` has no effect there. + +- `LoadFile(filename, image_number=0, summation=1, token="")` — open a file (or an + `http://host:port` URL) and display the given image; a non-empty `token` is the bearer token of a + protected broker dataset. +- `LoadImage(image_number, summation=1)` — navigate to an image in the already-open dataset. +- `SetHttpToken(token)` — set the dataset token without reloading; the next request carries it. + +`summation` sums that many consecutive images before display. A repeated `LoadFile` call naming the +file that is already open is cheap (it just navigates, like `LoadImage`) rather than reopening it, +but a client stepping through images of a dataset it opened itself should still prefer `LoadImage` — +it needs no filename and avoids the file-identity comparison. + +## Building from source on Windows + +`jfjoch_viewer` is cross-platform: it builds on Windows 11 with MSVC and the full CUDA GPU path, and +on macOS (see [below](#building-from-source-on-macos)). (The rest of Jungfraujoch — broker, receiver, FPGA host — is +Linux-only.) A pre-built installer is published with every release, so building from source is only +needed to develop or to change the build options. On Windows the build is automatically restricted +to the viewer and the libraries it needs (`JFJOCH_VIEWER_ONLY` is forced on), and the remaining +dependencies are fetched and built automatically (the first configure needs network access). + +Verified toolchain — the same one the released installer is built with: + +- Windows 11 +- Visual Studio 2026 with the C++ (MSVC) toolset — required; CUDA on Windows builds through MSVC +- CUDA Toolkit 13.3 (12.8 or newer is required) — for the GPU indexing/integration path +- Qt 6.11 for MSVC (`msvc2022_64`), including the **Qt Charts** module — e.g. `C:\Qt\6.11.1\msvc2022_64` +- CMake plus Ninja. The CMake that ships with Visual Studio is the simplest choice and works out of + the box — it comes with the C++ workload, so there is nothing extra to install. Any recent + standalone CMake (from cmake.org, or the one bundled with Qt in `C:\Qt\Tools\CMake_64`) works too. +- Optional: [NSIS](https://nsis.sourceforge.io) to build the `.exe` installer. + +Configure and build from an **x64 Native Tools Command Prompt for VS 2026** (so `cl`, `nvcc` and +`ninja` are on `PATH`): + +``` +cmake -G Ninja -B build-win -DCMAKE_BUILD_TYPE=Release ^ + -DCMAKE_PREFIX_PATH="C:/Qt/6.11.1/msvc2022_64" +cmake --build build-win --target jfjoch_viewer +``` + +Notes: + +- `CMAKE_PREFIX_PATH` (Qt) is the only required flag. Every other dependency, zlib and Eigen + included, is downloaded and built by the configure itself, so nothing else has to be installed. +- The CUDA toolchain is located automatically from the `CUDA_PATH` environment variable that the + CUDA installer sets (or from `nvcc` on `PATH`). Pass `-DCMAKE_CUDA_COMPILER=".../bin/nvcc.exe"` + only if `nvcc` is installed in a nonstandard location and is not found. +- For a machine without an NVIDIA GPU, add `-DJFJOCH_USE_CUDA=OFF`: the viewer then runs the same + pipeline on the CPU (FFTW indexer) at lower throughput. + +To produce a self-contained installer (bundles the Qt runtime via `windeployqt` and — on the CUDA +build — the cuFFT runtime DLL, so the target host needs neither Qt nor a CUDA toolkit), with NSIS +installed: + +``` +cd build-win +cpack +``` + +The NSIS generator is selected automatically on Windows (no `-G` needed). What comes out, and how +the CUDA and CPU variants are named and told apart, is described in +[Release contents ▸ Windows installer](RELEASE_CONTENTS.md#windows-installer). + +## Building from source on macOS + +The viewer also builds on macOS, **Apple Silicon only** and without CUDA; as on Windows, the build +is automatically restricted to the viewer and the libraries it needs (`JFJOCH_VIEWER_ONLY` is forced +on) and fetches every other dependency itself. A pre-built disk image is published with every +release, so building from source is only needed to develop or to change the build options. + +Verified toolchain — the same one the released `.dmg` is built with: + +- An Apple Silicon Mac; the resulting app needs macOS 13 or newer, whatever the build machine runs +- Xcode (Apple Clang) +- Qt 6.11 for macOS, including the **Qt Charts** module — e.g. `~/Qt/6.11.2/macos` from the Qt + online installer +- CMake (e.g. `CMake.app` from cmake.org, with `/Applications/CMake.app/Contents/bin` on `PATH`) + +``` +cmake -S . -B build-mac -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$HOME/Qt/6.11.2/macos +cmake --build build-mac -j$(sysctl -n hw.ncpu) --target jfjoch_viewer +open build-mac/viewer/jfjoch_viewer.app +``` + +As on Windows, `CMAKE_PREFIX_PATH` (Qt) is the only required flag. To produce the disk image — the +Qt frameworks and the license notices copied into the app with `macdeployqt`, packed into +`jfjoch-viewer--macos-arm64.dmg` — run `cpack` in the build directory. What comes out is +described in [Release contents ▸ macOS](RELEASE_CONTENTS.md#macos). + +The released image is signed with the project's Apple Developer ID and notarized by Apple. A build of +your own is signed ad hoc, which runs on the machine that built it but is refused by Gatekeeper once +downloaded. To sign with a Developer ID from your own keychain, configure with +`-DJFJOCH_MACOS_SIGNING_IDENTITY=` before `cpack`, where the hash is the 40 hex digits +`security find-identity -v -p codesigning` prints in front of the certificate's name, then notarize +and staple the image with `tools/notarize_macos.sh build-mac/jfjoch-viewer-*.dmg` (it needs +notarytool credentials stored once on the machine; the script's header says how). diff --git a/_sources/JFJOCH_WRITER.md.txt b/_sources/JFJOCH_WRITER.md.txt new file mode 100644 index 000000000..cfda321aa --- /dev/null +++ b/_sources/JFJOCH_WRITER.md.txt @@ -0,0 +1,200 @@ +# jfjoch_writer + +`jfjoch_writer` is a NeXus-compliant HDF5 file writer. + +## Acknowledgements +Thanks to Zdenek Matej (MAX IV) and Felix Engelmann (MAX IV) for testing and multiple improvement +suggestions. + +## Running directory +The writer needs to run in the base directory for writing files - `file_prefix` is always relative to the writer's running directory. +The writer detects and protects against basic security issues, like `file_prefix` starting with a slash, or starting with `../`, or containing `/../`. + +## Usage +Writer needs to be started as a background service, with the following command: +``` +jfjoch_writer {options}
+ +Options: +-T | --tcp Use raw TCP/IP instead of ZeroMQ +-j | --nproc= Number of forks (only with -T) +-d | --root_dir= Root directory for file writing (-R is a deprecated alias) +-r | --zmq_repub_port= ZeroMQ port for PUSH socket to republish images +-f | --zmq_file_port= ZeroMQ port for PUB socket for notifications on finalized files +-w | --rcv_watermark= Receiving ZeroMQ socket watermark in messages (default = 10) +-m | --rcv_ring_mb= Receive ring buffer in MB; holds images until written and republished (default = 2048) +-W | --repub_watermark= Republish ZeroMQ socket watermark (default = 1000) +-b | --rcv_buffer= Receiving TCP socket buffer in bytes (only with -T; disables autotuning, capped by net.core.rmem_max) +-v | --verbose Verbose output +-h This message +``` +for example: +``` +jfjoch_writer -d /data tcp://dcu-address:5400 +``` + +## Memory +Every message the writer receives is placed in a ring buffer of a fixed size (`-m`, default 2048 MB, +per writer process - `-j 8` is eight rings) and stays there until it has been written to HDF5 and, if +republish is on, republished. The ring is the writer's memory budget for buffered images, and the +peak use is printed at the end of every run. Size it as the number of images you can afford to have +in flight times their compressed size: at 2048 MB that is some 250-500 JUNGFRAU 4M images but only +50-100 JUNGFRAU 9M images, so a 9M site will want more. + +When the ring is full the writer stops reading from the socket and the sender has to wait. How long +it is prepared to wait depends on the stream: + +- **ZeroMQ.** The socket queue fills up to its watermark (`-w`, a count of messages, kept small for + that reason) and the broker's send blocks for one second. After that the broker drops the image, + logs the fact, and sends without waiting for the rest of the run, so every later image that finds + the queue full is dropped too. A writer that stalls for longer than its ring covers therefore + loses images on ZeroMQ; the ring has to be large enough for the stalls of the filesystem it writes + to. (Before the ring the same stall was absorbed by queues of about 1500 messages, whatever their + size - a budget nobody had chosen.) +- **TCP/IP.** The broker sees the writer's BUSY heartbeats and waits, giving up only after a minute + in which not a single image was written. + +Republish holds its own images in the same ring. Because the ring is reclaimed in arrival order, an +image kept for a slow republish consumer would hold back everything received after it, so republish +may hold at most a quarter of the ring; beyond that images are simply not republished, exactly as +when its queue is full. A single message larger than the whole ring - a START or END message of a +very long run - is held outside it. + +## Status and cancellation +When a data collection is finalized, each writer reports its outcome back to `jfjoch_broker` over +the writer notification socket — a ZeroMQ address the broker passes in the START message +(`writer_notification_socket` in the broker configuration) — as a JSON message with the socket +number, run name and number, processed image count, throughput, and on failure an error string. +That is how the broker learns that a writer could not write. On the TCP/IP image stream, failures +additionally come back in-band as negative acknowledgements +(see [Data streams](IMAGE_STREAM.md#tcpip-image-stream)). + +To stop a writer, send it `SIGINT`, `SIGQUIT`, `SIGTERM` or `SIGHUP`: it closes the HDF5 files it is +writing and exits. This is only for the case where the broker was terminated or disconnected — it is +not the normal way to end a data collection, which the broker finishes on its own. + +## Republish +Republish creates a PUSH socket on the writer, where all the messages are republished for further use by a data analysis pipeline. +Republish is non-blocking, so if there is no receiver on other end or the sending queue is full - images won't be republished. +In case of START/END messages republishing will attempt sending for 100 ms, but if send times out it won't be retried. + +Republish functionality is optional, if republish port number is omitted this functionality is not enabled. It is available for ZeroMQ input only: with `-T` the option is refused. + +## Overwriting files +When `jfjoch_writer` creates a HDF5 file, it first adds suffix `..tmp`. +Random value depends on current time-stamp and likely will be different from each file of the particular series. +After file is all saved and closed, it is renamed to remove the suffix. +By default, renaming won't happen if this would overwrite existing file. +However, this behavior can be changed by setting `overwrite` parameter to true in the file writer configuration. + +### When the overwrite conflict is reported +An existing output file is a fatal condition (unless `overwrite` is true). *When* it is detected +depends on whether the transport between the broker and the writer has a back-channel to report the +failure before acquisition starts: + +* **Direct HDF5 pusher and TCP writer (back-channel available).** The conflict is detected at + **start**: the writer that owns the master file lists the output directory and refuses to start + if the master file or any data file the run will write already exists (every writer of a run + shares the directory, so one answers for all of them). The direct pusher raises the error + in-process; the TCP writer returns a START-failure acknowledgement, and makes the same check + earlier still, answering the broker's `PREFLIGHT` (see + [IMAGE_STREAM](IMAGE_STREAM.md#pre-flight)) before the detector is armed. Either way the broker + learns immediately and aborts the data collection *before* the detector is armed — no images are + taken and nothing is written. +* **ZeroMQ writer (no back-channel).** The ZeroMQ image stream is fire-and-forget: the writer has no + way to tell the broker to stop, and the broker would keep streaming images regardless. The writer + therefore does **not** fail at start. It writes the whole series to the `..tmp` files as + usual and only fails at the final rename, leaving the `.tmp` files on disk. This is deliberate: the + acquired images are preserved (in `.tmp` form) rather than being dropped by a writer that aborted + mid-stream. Rename the `.tmp` files by hand, or re-run with `overwrite` set, to recover them. + +## Finalized files information +Creates PUB socket to inform about finalized data files. For each closed file, the socket will send a JSON message, with the following structure: + +``` +{ + "filename": : HDF5 data file name (relative to writer root directory), + "nimages": number of images in the file (counting from 1!), + "file_number": number of file within the acquisition, + "sample_name": name of sample, + "run_name": name of run, + "run_number": number of run, + "experiment_group": number of p-group / proposal (optional), + "user_data": user_data, + "beam_x_pxl": beam center (X) in pixels, + "beam_y_pxl": beam center (Y) in pixels, + "detector_distance_m": detector distance in m, + "detector_height_pxl": detector size (Y) in pixels, + "detector_width_pxl": detector size (X) in pixels, + "incident_energy_eV": photon energy of the X-ray beam, + "pixel_size_m": pixel size in meter (assuming pixel X == Y), + "saturation": this count and higher mean saturation, + "space_group_number": space group number (optional), + "underload": lowest valid count; anything below it is invalid, + "unit_cell": unit cell dimensions in Angstrom/degree { + "a": , "b": , "c": , + "alpha": , "beta": , "gamma": + }, +} +``` +`user_data` is defined as `header_appendix` in the `/start` operation in the `jfjoch_broker`. +Other metadata are also carried over from `/start` operation. + +If the `header_appendix` is a string with valid JSON meaning, it will be embedded as JSON, otherwise it will be escaped as string. +For example `header_appendix` of `{"param1": "test1", "param2": ["test1", "test2"]}`, then the example message will look as follows: +```json +{ + "filename": "dataset_name_data_000001.h5", + "nimages": 1000, + "file_number": 0, + "sample_name": "my_sample", + "run_name": "my_run", + "run_number": 25, + "experiment_group": "p00001", + "beam_x_pxl": 1200, + "beam_y_pxl": 1500, + "detector_distance_m": 0.155, + "detector_height_pxl": 2164, + "detector_width_pxl": 2068, + "incident_energy_eV": 12400.0, + "pixel_size_m": 7.5e-05, + "saturation": 32766, + "space_group_number": 96, + "underload": -32767, + "unit_cell": { + "a": 78.0, + "alpha": 90.0, + "b": 78.0, + "beta": 90.0, + "c": 39.0, + "gamma": 90.0 + }, + "user_data": { + "param1": "test1", + "param2": ["test1", "test2"] + } +} +``` + +Notifications for finalized files are optional, if notification port number is omitted this functionality is not enabled. + +## HDF5 file structure + +Jungfraujoch writes NXmx-compliant HDF5, with substantial derived metadata (spot finding, indexing, +integration, azimuthal integration, per-image statistics and timing) stored *beyond* the NXmx +standard. The complete file layout — master vs data files, the three format variants +(`NXmxLegacy`, `NXmxVDS`, `NXmxIntegrated`), every NXmx field that is populated and every +Jungfraujoch extension — is documented in [HDF5 / NeXus data format](HDF5.md). + +If data collection was configured with a `header_appendix` containing a key `hdf5` whose value is a +JSON object of numbers and strings, those entries are written to `/entry/user`. + +## Other formats (CBF and TIFF) +Jungfraujoch writes only NXmx HDF5. The `CBF` and `TIFF` values remain in the file-format enum for +compatibility, but a request to write either format is rejected. + +## No file option(s) +There are two options to disable writing of files by the writer: +* Setting `file_prefix` to empty string - this will disable sending files on ZeroMQ image socket. +* Setting file format to `NoFile` - files are streamed over ZeroMQ socket, but `jfjoch_writer` will not write anything. +This can be useful for debugging purposes, or if you only rely on republishing functionality of the `jfjoch_writer` \ No newline at end of file diff --git a/_sources/JUNGFRAUJOCH.md.txt b/_sources/JUNGFRAUJOCH.md.txt new file mode 100644 index 000000000..b2a1a6ebf --- /dev/null +++ b/_sources/JUNGFRAUJOCH.md.txt @@ -0,0 +1,63 @@ +# Jungfraujoch: data acquisition + +Jungfraujoch is the data-acquisition and real-time analysis system for the PSI **JUNGFRAU** and +**EIGER** detectors, and, through their detector control unit, for DECTRIS detectors. It takes +the detector's frames at the full frame rate, builds and analyses the images on the fly, and +streams them out for writing, with a web interface and a REST API for the beamline. It is the streaming half of the software; [Rugnux](RUGNUX.md) is the +processing half (see [Naming](NAMING.md)). + +## What runs where + +| Program | Role | +| --- | --- | +| [`jfjoch_broker`](JFJOCH_BROKER.md) | The central service: configures the detector and the FPGA cards, builds images from their output, runs the real-time analysis (masking, summation, spot finding, azimuthal and ROI integration, indexing on the GPU, compression), streams the images over ZeroMQ or TCP, and serves the HTTP/REST interface and the [web frontend](WEB_FRONTEND.md). | +| [`jfjoch_writer`](JFJOCH_WRITER.md) | Receives the image stream and writes NeXus/NXmx HDF5 files; usually on a separate machine with the file system. | +| [FPGA smartNIC](FPGA.md) | AMD Alveo U55C cards with the Jungfraujoch firmware, one per few JUNGFRAU modules; they receive the detector's UDP stream and run the first stages of the analysis in hardware. The DECTRIS path has no FPGA: the stream from the detector control unit goes through the same analysis on the CPU and GPU. | +| [Web frontend](WEB_FRONTEND.md) | The browser interface served by the broker: detector state, live preview, plots of the on-line quality metrics, and the controls, including [Rugnux live mode](JFJOCH_BROKER.md#rugnux-live-mode), which processes a rotation sweep while it is being collected. | +| [Python client](PYTHON_CLIENT.md) | `pip install jfjoch-client`: the REST API as a generated Python package, for beamline control software. | +| [Viewer](JFJOCH_VIEWER.md) | Optional: the desktop viewer follows a live collection from the broker over HTTP. | + +The detectors, firmware and `slsDetectorPackage` versions the system is built against are in +[Supported detectors](DETECTORS.md); the server, FPGA, GPU and switch it needs are in +[Hardware requirements](HARDWARE.md). + +## Installing + +Jungfraujoch runs on Linux servers: RHEL / Rocky 8 and 9 are the supported platforms, Ubuntu +22.04 / 24.04 experimental ([Software requirements](SOFTWARE.md)). + +- **Packages.** The [package repositories](REPOSITORIES.md) carry `jfjoch` (broker, frontend, + FPGA and detector tools), `jfjoch-driver-dkms` (the PCIe kernel module), `jfjoch-writer` and + `jfjoch-viewer`, in CUDA and non-CUDA variants and per `slsDetectorPackage` version. The writer's + `.rpm` / `.deb` are also attached to every + [release](https://gitea.psi.ch/mx/jungfraujoch/releases), for a file-writing machine without + the rest. +- **FPGA firmware.** The `.mcs` images are attached to every release; the card is flashed once + with `xbflash.qspi` and keeps its image across software upgrades. +- **From source.** `cmake` and `make` from the repository, with every dependency fetched during + the first configure; the frontend is built separately with `make frontend`. + +[Deployment](DEPLOYMENT.md) is the step-by-step guide: packages or source, flashing the cards, +the kernel driver, the network switch, the broker's configuration file and running the services. +[Release contents](RELEASE_CONTENTS.md) says what each package contains and what it needs on the +machine. + +## Reading the output + +The broker streams images as CBOR messages compatible with the DECTRIS Stream2 protocol +([Data streams](IMAGE_STREAM.md), [CBOR messages](CBOR.md)); the writer turns them into NXmx HDF5 +([HDF5 / NeXus data format](HDF5.md)). Which downstream programs read which of the three HDF5 +layouts, and the XDS plugin, are in [Integration with MX software](SOFTWARE_INTEGRATION.md). The +command-line tools shipped beside the services are listed in [Tools](TOOLS.md). + +## How to cite + +The primary citation for Jungfraujoch is F. Leonarski et al., "Jungfraujoch: hardware-accelerated +data-acquisition system for kilohertz pixel-array X-ray detectors" (2023), J. Synchrotron Rad. 30, +227-234 [doi:10.1107/S1600577522010268](https://doi.org/10.1107/S1600577522010268). For real-time +serial crystallography and live indexing feedback cite also J. Duan et al., "Jungfraujoch: +38 GB s⁻¹ real-time serial crystallography – data acquisition and live indexing feedback" (2026), +J. Appl. Cryst. 59, 1668-1677 [doi:10.1107/S1600576726008083](https://doi.org/10.1107/S1600576726008083). +The files `jfjoch_writer` writes from Rugnux live mode name both Jungfraujoch and Rugnux; cite the +[Rugnux paper](PUBLICATIONS.md#rugnux) too when you use them. All papers are on the +[Publications](PUBLICATIONS.md) page. diff --git a/_sources/LICENSE.md.txt b/_sources/LICENSE.md.txt new file mode 100644 index 000000000..b5ae8c25b --- /dev/null +++ b/_sources/LICENSE.md.txt @@ -0,0 +1,699 @@ +# License + +Jungfraujoch software is licensed with GPLv3 license. +Jungfraujoch FPGA is licensed with CERN OHL-S license (see [FPGA license](FPGA_LICENSE.md)). + +## GNU GENERAL PUBLIC LICENSE +Version 3, 29 June 2007 + +Copyright (C) 2007 Free Software Foundation, Inc. +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. + +### Preamble + +The GNU General Public License is a free, copyleft license for +software and other kinds of works. + +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + +When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + +Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and +modification follow. + +### TERMS AND CONDITIONS + +0. Definitions. + +"This License" refers to version 3 of the GNU General Public License. + +"Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + +"The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + +To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + +A "covered work" means either the unmodified Program or a work based +on the Program. + +To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + +An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +1. Source Code. + +The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + +A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + +The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + +The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + +The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + +The Corresponding Source for a work in source code form is that +same work. + +2. Basic Permissions. + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + +3. Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + +4. Conveying Verbatim Copies. + +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +5. Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + +a) The work must carry prominent notices stating that you modified +it, and giving a relevant date. + +b) The work must carry prominent notices stating that it is +released under this License and any conditions added under section +7. This requirement modifies the requirement in section 4 to +"keep intact all notices". + +c) You must license the entire work, as a whole, under this +License to anyone who comes into possession of a copy. This +License will therefore apply, along with any applicable section 7 +additional terms, to the whole of the work, and all its parts, +regardless of how they are packaged. This License gives no +permission to license the work in any other way, but it does not +invalidate such permission if you have separately received it. + +d) If the work has interactive user interfaces, each must display +Appropriate Legal Notices; however, if the Program has interactive +interfaces that do not display Appropriate Legal Notices, your +work need not make them do so. + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +6. Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + +a) Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by the +Corresponding Source fixed on a durable physical medium +customarily used for software interchange. + +b) Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by a +written offer, valid for at least three years and valid for as +long as you offer spare parts or customer support for that product +model, to give anyone who possesses the object code either (1) a +copy of the Corresponding Source for all the software in the +product that is covered by this License, on a durable physical +medium customarily used for software interchange, for a price no +more than your reasonable cost of physically performing this +conveying of source, or (2) access to copy the +Corresponding Source from a network server at no charge. + +c) Convey individual copies of the object code with a copy of the +written offer to provide the Corresponding Source. This +alternative is allowed only occasionally and noncommercially, and +only if you received the object code with such an offer, in accord +with subsection 6b. + +d) Convey the object code by offering access from a designated +place (gratis or for a charge), and offer equivalent access to the +Corresponding Source in the same way through the same place at no +further charge. You need not require recipients to copy the +Corresponding Source along with the object code. If the place to +copy the object code is a network server, the Corresponding Source +may be on a different server (operated by you or a third party) +that supports equivalent copying facilities, provided you maintain +clear directions next to the object code saying where to find the +Corresponding Source. Regardless of what server hosts the +Corresponding Source, you remain obligated to ensure that it is +available for as long as needed to satisfy these requirements. + +e) Convey the object code using peer-to-peer transmission, provided +you inform other peers where the object code and Corresponding +Source of the work are being offered to the general public at no +charge under subsection 6d. + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + +A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + +"Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +7. Additional Terms. + +"Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + +a) Disclaiming warranty or limiting liability differently from the +terms of sections 15 and 16 of this License; or + +b) Requiring preservation of specified reasonable legal notices or +author attributions in that material or in the Appropriate Legal +Notices displayed by works containing it; or + +c) Prohibiting misrepresentation of the origin of that material, or +requiring that modified versions of such material be marked in +reasonable ways as different from the original version; or + +d) Limiting the use for publicity purposes of names of licensors or +authors of the material; or + +e) Declining to grant rights under trademark law for use of some +trade names, trademarks, or service marks; or + +f) Requiring indemnification of licensors and authors of that +material by anyone who conveys the material (or modified versions of +it) with contractual assumptions of liability to the recipient, for +any liability that these contractual assumptions directly impose on +those licensors and authors. + +All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + +8. Termination. + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +9. Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +10. Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +11. Patents. + +A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + +A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + +A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +12. No Surrender of Others' Freedom. + +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + +13. Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +14. Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + +If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +15. Disclaimer of Warranty. + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +16. Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + +17. Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS + +### How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + +To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w` and `show c` should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + +You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + +The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. + + +## Jungfraujoch exceptions to GPL + +Additional permissions under section 7 of the GNU GPL version 3. + +The copyright holders of Jungfraujoch grant the following additional permissions. They apply only +to code whose copyright the Jungfraujoch copyright holders own; they do not and cannot change the +license of third-party code. + +1. NVIDIA CUDA. The NVIDIA CUDA Toolkit libraries (the CUDA runtime, cuFFT and the other libraries + distributed with the CUDA Toolkit) are treated as System Libraries for the purposes of this + License, so a work linked with them may be conveyed without their Corresponding Source. + +2. FPGA simulation. Jungfraujoch software (GPL-3.0) may be linked with Jungfraujoch high-level + synthesis code (CERN-OHL-S-2.0) to simulate the FPGA design on a CPU. + +3. OpenAPI definition. Client code generated from the OpenAPI definition file (jfjoch_api.yaml), or + code that uses that file solely to interact with the Jungfraujoch API, may be distributed under + terms of your choosing, without being subject to the requirements of the GNU GPL. diff --git a/_sources/NAMING.md.txt b/_sources/NAMING.md.txt new file mode 100644 index 000000000..ce6cce2ed --- /dev/null +++ b/_sources/NAMING.md.txt @@ -0,0 +1,60 @@ +# Naming + +The software is Swiss, and so are its names: both halves of the system are named after +places in the Alps that are, in one way or another, about moving a *lot* of something up a +steep mountain as efficiently as possible — usually by train. Throughput, in other words. + +| Part | Name | What it does | +| --- | --- | --- | +| Streaming / acquisition | **Jungfraujoch** | Receives detector data at high data rates, runs the FPGA/GPU pipeline, and streams images out for writing. | +| Data processing | **Rugnux** | Crystallographic analysis of a stored dataset, or of a collection while it is written — indexing, integration, scaling and merging, and refinement of a given model (the [`rugnux`](RUGNUX.md) tool). | + +## Jungfraujoch + +The **Jungfraujoch** is a high mountain col in the Bernese Alps, the saddle (*Joch* is German +for "yoke" or "col") between the peaks **Jungfrau** and **Mönch**, at 3,466 m. It is the site of +the [High Altitude Research Station Jungfraujoch](https://www.hfsjg.ch/), whose long-running +atmospheric measurements are **co-operated by the Paul Scherrer Institute** — the same institute +that develops this software and the JUNGFRAU detector. + +The name is also a small piece of word-play. PSI's **JUNGFRAU** detector and DECTRIS's **EIGER** +detector are both named after Bernese Alps peaks (the famous trio is *Eiger*, *Mönch*, *Jungfrau*). +The Jungfraujoch — the pass *between* Jungfrau and Mönch — is where those two detector worlds meet. + +And it fits the theme of the whole project: the Jungfraujoch is reached by the **Jungfraubahn**, +whose terminus is the **highest railway station in Europe** (3,454 m, the "Top of Europe"). It is +the closest you can get to that summit in a genuinely *high-throughput* way — by train, moving +crowds up the mountain — which is exactly what the streaming side of this software does with +detector frames. + +**Pronunciation (German):** *Jungfraujoch* ≈ **YUNG-frow-yokh**. +"Jung" as in *young*, "frau" rhymes with *cow*, and the final "joch" ends in the guttural *ch* of +Scottish *loch* or German *Bach* — not a hard *k*. + +## Rugnux + +**Piz Rugnux** is a mountain in the Rhaetian Alps of canton Graubünden, in south-eastern +Switzerland. (*Piz* is the Romansh word for "peak".) It rises above the **Albula line** of the +**Rhaetian Railway** (*Rhätische Bahn*), part of the "Rhaetian Railway in the Albula / Bernina +Landscapes" — a **UNESCO World Heritage Site** (*Welterbe*). + +That stretch of line is a masterpiece of throughput engineering: to climb a great deal of altitude +in very little horizontal distance, it corkscrews through a series of **helical (spiral) tunnels** +looping back inside the mountains. It is, again, the Swiss art of getting an enormous amount up a +steep mountain efficiently — the same idea the data-processing side of this software is built +around: pushing a large volume of diffraction data through the analysis pipeline. + +So the theme is consistent — **Swiss mountains, trains, and throughput** — while keeping the two +subsystems clearly distinct: *Jungfraujoch* streams, *Rugnux* processes. + +**Pronunciation (Romansh):** *Piz Rugnux* ≈ **peets roo-NYOOKS**. +The "gn" is a soft palatal *ñ*, as in *canyon* or Italian *gnocchi*, not two separate sounds. + +## What is Romansh? + +**Romansh** (*Rumantsch*) is the **fourth national language of Switzerland**, alongside German, +French and Italian. It is a Romance language — a direct descendant of the spoken Latin left behind +in the Alpine valleys — today spoken by only a few tens of thousands of people, almost all in the +canton of Graubünden. It survives in several regional idioms, brought together in a standard form +called *Rumantsch Grischun*. Naming the processing engine with a Romansh mountain is a small nod to +the least-spoken but no-less-Swiss corner of the country. diff --git a/_sources/OPENAPI.md.txt b/_sources/OPENAPI.md.txt new file mode 100644 index 000000000..1eaa1fba3 --- /dev/null +++ b/_sources/OPENAPI.md.txt @@ -0,0 +1,15 @@ +# OpenAPI +## OpenAPI specs + +See document with detailed [OpenAPI specs](OPENAPI_SPECS.rst). The spec declares one security +scheme, `bearerAuth`, on the endpoints that expose the current dataset; it applies only while the +dataset was started with `tokens` (see [Security](SECURITY.md)). + +## Python client +Jungfraujoch is controlled with HTTP/REST interface defined with an OpenAPI specification. +For convenience, we provide a Python client as the [jfjoch-client](https://pypi.org/project/jfjoch-client/) PyPI package. +To install the client you can use `pip` tool: +``` +pip install jfjoch-client +``` +See [API reference from the OpenAPI generator](python_client/README.md). \ No newline at end of file diff --git a/_sources/OPENAPI_SPECS.rst.txt b/_sources/OPENAPI_SPECS.rst.txt new file mode 100644 index 000000000..15bf4e7f6 --- /dev/null +++ b/_sources/OPENAPI_SPECS.rst.txt @@ -0,0 +1,4 @@ +OpenAPI specification +===================== + +See document with detailed `OpenAPI specs <_static/redoc-static.html>`_ generated with Redocly. \ No newline at end of file diff --git a/_sources/PIXEL_MASK.md.txt b/_sources/PIXEL_MASK.md.txt new file mode 100644 index 000000000..efd1dc077 --- /dev/null +++ b/_sources/PIXEL_MASK.md.txt @@ -0,0 +1,58 @@ +# Pixel mask + +## Mask format + +Jungfraujoch generally follows the [NXmx format](https://manual.nexusformat.org/classes/applications/NXmx.html) for the pixel mask. +The pixel mask is a 32-bit unsigned integer array of the same size as the image. +The conditions for masking a pixel are encoded by setting a particular bit to one. This makes it possible to record the reason why a pixel is included in the mask, and several reasons can be recorded for one pixel at the same time. + +Bit values are set as follows: + +Bit 0 - gap (pixel with no sensor) + +Bit 1 - error pixel (for PSI JUNGFRAU: pixel doesn't set proper gain during pedestal, for DECTRIS: pixel is part of detector pixel mask) + +Bit 4 - noisy pixel (for PSI JUNGFRAU: pixel pedestal G0 RMS is over threshold, for DECTRIS: pixel was flagged with signal during dark data collection at initialization) + +Bit 8 - user defined mask + +Bit 9 - beam stop shadow (found by `rugnux --detect-beam-stop`, on by default; see [Rugnux](RUGNUX.md)). +Unlike the other bits this one belongs to the run that found it, not to the dataset: Rugnux clears it +at the start of every run, so a mask read back from a file that carries one starts clear. The user +mask (bit 8) is left alone. + +Bit 10 - defective pixel found on the run's own frames (rotation data from a counting sensor; see +[CPU data analysis §1.6](CPU_DATA_ANALYSIS_IMAGE.md)): lit above its resolution ring on more frames +than one reflection or chance explains, or holding the detector's error value on most frames. + +Bit 11 - outside a CCD's active area, measured on the run's own frames (see +[CPU data analysis §1.6](CPU_DATA_ANALYSIS_IMAGE.md)). + +Bit 30 - module edge (only for PSI systems) + +Bit 31 - chip edge interpolated pixel (multipixel) + +## Custom user mask + +Jungfraujoch allows a custom user mask to be uploaded. This happens in two steps. First create the mask in TIFF format: + +```python +import numpy as np +import tifffile as tiff + +# Create an array matching a 2068 x 2164 (width x height) image: 2164 rows, 2068 columns +array = np.zeros((2164, 2068), dtype=np.uint32) + +# Mark the pixel at column 400, row 300 with the value 1 +array[300, 400] = 1 + +# Save the array as a TIFF file +tiff.imwrite('mask.tiff', array) +``` + +Pixels with non-zero value in the TIFF file will be marked as belonging to the user mask (bit 8). + +Then upload the mask to Jungfraujoch server: +```shell +curl -v http:///config/user_mask.tiff -XPUT --data-binary @mask.tiff +``` diff --git a/_sources/PUBLICATIONS.md.txt b/_sources/PUBLICATIONS.md.txt new file mode 100644 index 000000000..a73883ecf --- /dev/null +++ b/_sources/PUBLICATIONS.md.txt @@ -0,0 +1,64 @@ +# Publications + +## How to cite + +**Rugnux** — if you find Rugnux useful, please cite: + +F. Leonarski and M. Wang, "Rugnux: from diffraction images to structure at synchrotrons and XFELs in +one program" (2026), bioRxiv [doi:10.64898/2026.10.24.761522](https://doi.org/10.64898/2026.10.24.761522). + +**Jungfraujoch** — the primary citation is: + +F. Leonarski, M. Brückner, C. Lopez-Cuenca, A. Mozzanica, H.-C. Stadler, Z. Matěj, A. Castellane, +B. Mesnet, J. Wojdyla, B. Schmitt and M. Wang, "Jungfraujoch: hardware-accelerated data-acquisition +system for kilohertz pixel-array X-ray detectors" (2023), J. Synchrotron Rad. 30, 227-234 +[doi:10.1107/S1600577522010268](https://doi.org/10.1107/S1600577522010268). + +Work that relies on real-time serial crystallography, live indexing feedback or the system's +full data rate should also cite: + +J. Duan, H.-C. Stadler, J. Nan, Z. Matěj, G. Gotthard, F. Dworkowski, M. Bjelčić, O. Aurelius, +A. Mozzanica, S. Grimm, M. Burian, T. Ursby, M. Wang and F. Leonarski, "Jungfraujoch: 38 GB s⁻¹ +real-time serial crystallography – data acquisition and live indexing feedback" (2026), +J. Appl. Cryst. 59, 1668-1677 +[doi:10.1107/S1600576726008083](https://doi.org/10.1107/S1600576726008083). + +Data collected with Jungfraujoch and processed with Rugnux in the broker (Rugnux live mode) come out +of both programs, and the files `jfjoch_writer` writes from them name both: please cite both. + +## Rugnux + +- F. Leonarski and M. Wang, "Rugnux: from diffraction images to structure at synchrotrons and XFELs + in one program" (2026), bioRxiv + [doi:10.64898/2026.10.24.761522](https://doi.org/10.64898/2026.10.24.761522). + +## Jungfraujoch + +- J. Duan, H.-C. Stadler, J. Nan, Z. Matěj, G. Gotthard, F. Dworkowski, M. Bjelčić, O. Aurelius, + A. Mozzanica, S. Grimm, M. Burian, T. Ursby, M. Wang and F. Leonarski, "Jungfraujoch: 38 GB s⁻¹ + real-time serial crystallography – data acquisition and live indexing feedback" (2026), + J. Appl. Cryst. 59, 1668-1677 + [doi:10.1107/S1600576726008083](https://doi.org/10.1107/S1600576726008083) — the system at its + full data rate, with live indexing feedback during serial data collection. +- P. Gasparotto, L. Barba, H.-C. Stadler, G. Assmann, H. Mendonça, A. W. Ashton, M. Janousch, + F. Leonarski and B. Béjar, "TORO Indexer: a PyTorch-based indexing algorithm for kilohertz serial + crystallography" (2024), J. Appl. Cryst. 57, 931-944 + [doi:10.1107/S1600576724003182](https://doi.org/10.1107/S1600576724003182) — the GPU indexing + algorithm behind Jungfraujoch's real-time indexing. +- F. Leonarski, J. Nan, Z. Matěj, Q. Bertrand, A. Furrer, I. Gorgisyan, M. Bjelčić, M. Kepa, + H. Glover, V. Hinger, T. Eriksson, A. Cehovin, M. Eguiraun, P. Gasparotto, A. Mozzanica, + T. Weinert, A. Gonzalez, J. Standfuss, M. Wang, T. Ursby and F. Dworkowski, "Kilohertz serial + crystallography with the JUNGFRAU detector at a fourth-generation synchrotron source" (2023), + IUCrJ 10, 729-737 [doi:10.1107/S2052252523008618](https://doi.org/10.1107/S2052252523008618) — + serial crystallography at 2 kHz with a JUNGFRAU 4M and Jungfraujoch at the BioMAX beamline of + MAX IV. +- F. Leonarski, M. Brückner, C. Lopez-Cuenca, A. Mozzanica, H.-C. Stadler, Z. Matěj, A. Castellane, + B. Mesnet, J. Wojdyla, B. Schmitt and M. Wang, "Jungfraujoch: hardware-accelerated + data-acquisition system for kilohertz pixel-array X-ray detectors" (2023), J. Synchrotron Rad. + 30, 227-234 [doi:10.1107/S1600577522010268](https://doi.org/10.1107/S1600577522010268) — the + primary citation: the FPGA-accelerated acquisition system. +- F. Leonarski, A. Mozzanica, M. Brückner, C. Lopez-Cuenca, S. Redford, L. Sala, A. Babic, + H. Billich, O. Bunk, B. Schmitt and M. Wang, "JUNGFRAU detector for brighter x-ray sources: + Solutions for IT and data science challenges in macromolecular crystallography" (2020), + Struct. Dyn. 7, 014305 [doi:10.1063/1.5143480](https://doi.org/10.1063/1.5143480) — the data + handling problem of the JUNGFRAU detector that Jungfraujoch was designed to solve. diff --git a/_sources/PYTHON_CLIENT.md.txt b/_sources/PYTHON_CLIENT.md.txt new file mode 100644 index 000000000..9f0b74b21 --- /dev/null +++ b/_sources/PYTHON_CLIENT.md.txt @@ -0,0 +1,34 @@ +# OpenAPI Python client + +The broker's REST API has a generated Python client, published on PyPI as +[`jfjoch-client`](https://pypi.org/project/jfjoch-client/) and regenerated from +`broker/jfjoch_api.yaml` by `update_version.sh` — the YAML is the single source of truth +(see [OpenAPI](OPENAPI.md)). + +- [Client README](python_client/README.md) — installation, quick start, and the index of every + endpoint and model. +- [DefaultApi](python_client/docs/DefaultApi.md) — the full endpoint reference, with a generated + example per call. + +A protected dataset (one started with `tokens`) is read with the token as the client's bearer +credential: + +```python +import jfjoch_client +api = jfjoch_client.DefaultApi(jfjoch_client.ApiClient( + jfjoch_client.Configuration(host="http://localhost:5232", access_token=""))) +api.post_start(jfjoch_client.DatasetSettings(..., tokens=[""])) +api.get_statistics_data_collection() # sends Authorization: Bearer +``` + +The per-model pages are generated as well and are linked from the two pages above. They are built +with the site but kept out of the navigation sidebar on purpose — sixty generated reference pages +would otherwise be most of it. + +```{toctree} +:hidden: +:glob: + +python_client/README +python_client/docs/* +``` diff --git a/_sources/RELEASE_CONTENTS.md.txt b/_sources/RELEASE_CONTENTS.md.txt new file mode 100644 index 000000000..072c31e38 --- /dev/null +++ b/_sources/RELEASE_CONTENTS.md.txt @@ -0,0 +1,193 @@ +# 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--linux-cuda.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--win64-cuda.exe`, `...-win64-cpu.exe` | Gitea release page | Windows installer for `jfjoch_viewer`, plus the Qt runtime | +| `jfjoch-viewer--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--linux-x86_64-cuda.tgz`, `...-linux-x86_64-cpu.tgz` | Gitea release page | Portable Linux [`rugnux`](RUGNUX.md), the offline analysis CLI, and the license notices. One executable | +| `rugnux--linux-aarch64-cuda.tgz` | Gitea release page | The same, cross-built for 64-bit Arm — NVIDIA GH200 and DGX Spark | +| `rugnux--win64-cuda.zip`, `...-win64-cpu.zip` | Gitea release page | The same for Windows, plus the cuFFT DLL in the CUDA variant | +| `rugnux--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 | +| `jfjoch_xds_plugin--linux-x86_64.tgz` | Gitea release page | XDS HDF5 read plugin (`lib/libjfjoch_xds_plugin.so.`, built on RHEL 8) and its license notices; 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 build system sets no architecture flags of its own, 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-`) +rather than into a working directory. + +## CUDA and non-CUDA builds + +Every Linux and Windows binary artefact is released in **two variants**, `cuda` 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 (the FFTW indexer and the CPU fast-feedback 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; Rugnux is tested on a DGX Spark (GB10). + +**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--win64-cuda.exe` | `Jungfraujoch (CUDA)` | +| CPU-only | `jfjoch-viewer--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, including the XDS plugin, is Linux-only. Both are **without CUDA** — macOS has none, so indexing uses the FFTW indexer and the pipeline runs +on the CPU, except Bragg integration, the model density and the molecular-replacement rotation +function, which run on the Apple GPU through Metal — 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--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. + +Both artefacts are signed with the project's Apple Developer ID and **notarized by Apple**, so a +downloaded copy opens like any other Mac application. The disk image carries its notarization ticket; +the `rugnux` binary in the `.tgz` cannot (a bare executable has nowhere to staple one), so the first +run of a freshly downloaded `rugnux` looks the ticket up online and needs an internet connection. + +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). diff --git a/_sources/REPOSITORIES.md.txt b/_sources/REPOSITORIES.md.txt new file mode 100644 index 000000000..3cac87d42 --- /dev/null +++ b/_sources/REPOSITORIES.md.txt @@ -0,0 +1,56 @@ +# Linux package repositories +For convenience, we are providing package repositories, in versions including and excluding CUDA linking. +We recommend installing the Jungfraujoch viewer from a `nocuda` repository (published in the `slsdet8` flavour only) and the remaining packages from a `cuda12`/`cuda13` repository. + +The repository name encodes two choices: the [slsDetectorPackage](DETECTORS.md) version the packages +were built against (`slsdet8` = 8.0.2, `slsdet9` = 9.2.0 — it must match the detector firmware) and +whether CUDA is linked in. What ends up inside each package, and what it needs on the target +machine, is described in [Release contents](RELEASE_CONTENTS.md). + +## RHEL based systems + +For RHEL systems we provide the following repositories: + +| RHEL version | slsDetectorPackage | CUDA | Repository file | +|--------------|--------------------|------|------------------------------------------------------------------------| +| 8.x | 8.0.2 | 12.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-cuda12.repo | +| 8.x | 9.2.0 | 12.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet9-cuda12.repo | +| 8.x | 8.0.2 | - | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-nocuda.repo | +| 9.x | 8.0.2 | 13.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet8-cuda13.repo | +| 9.x | 9.2.0 | 13.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet9-cuda13.repo | +| 9.x | 8.0.2 | - | https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet8-nocuda.repo | + +To install the repository, run: + +```bash +dnf config-manager --add-repo https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-cuda12.repo +``` +RPMs are signed by the Gitea package registry as they are uploaded. If your system cannot verify the +signature, set `gpgcheck=0` in the repository file or install with `--nogpgcheck`. + +We provide the following packages in the repository: +* jfjoch — broker, web frontend, FPGA and detector command-line tools +* jfjoch-driver-dkms — PCIe kernel-module source, built by DKMS +* jfjoch-writer — HDF5 writer service +* jfjoch-viewer — desktop viewer and the XDS plugin +* Rugnux — [offline analysis CLI](RUGNUX.md), independent of the acquisition stack + +Note that `rugnux` is named without the `jfjoch-` prefix, matching the program and the release +archive. + +## Ubuntu based systems + +For Ubuntu systems, we also provide the following repositories: +``` +sudo curl https://gitea.psi.ch/api/packages/mx/debian/repository.key -o /etc/apt/keyrings/gitea-mx.asc +echo "deb [signed-by=/etc/apt/keyrings/gitea-mx.asc] https://gitea.psi.ch/api/packages/mx/debian $distribution $component" | sudo tee -a /etc/apt/sources.list.d/gitea.list +sudo apt update +``` + +`$distribution` uses Ubuntu names `jammy` (22.04) and `noble` (24.04). `$component` can be set to either `cuda13` or `nocuda`. +Only slsDetectorPackage 8.0.2 is built for Ubuntu. + +The same five packages as above are provided: `jfjoch`, `jfjoch-driver-dkms`, `jfjoch-writer`, +`jfjoch-viewer` and `rugnux`. + +Ubuntu packages currently undergo only very limited testing. diff --git a/_sources/RUGNUX.md.txt b/_sources/RUGNUX.md.txt new file mode 100644 index 000000000..b426e829a --- /dev/null +++ b/_sources/RUGNUX.md.txt @@ -0,0 +1,354 @@ +# Rugnux + +`rugnux` is the **offline** crystallographic data-analysis tool of Jungfraujoch — the +data-processing half of the system (see [Naming](NAMING.md) for where the name comes from). It takes +a stored dataset from the diffraction images to merged data — spot finding, indexing, geometry +refinement, Bragg integration, scaling and merging, written as `.mtz`/`.cif`/`.hkl` with the +unmerged MTZ and the results report — and, with an atomic model, on to a refined structure and maps: +the model is placed against the merge, refined, and written with its map coefficients and the +difference-density blobs it leaves unexplained. The per-image `_process.h5` is written only on +request (`--write-process-h5`), or as the only output with `--no-merge`. A rotation run that finds +no lattice still spot-finds every image and writes their per-image analysis there, then exits as +failed. + +It runs the *same* analysis code as the online and interactive tools, driven from the command line +over files. + +``` +rugnux {} {} [] +``` + +Run it with no arguments to print the usage. + +Several Jungfraujoch/NXmx masters of stills, given one after another, are read as one run: their +images are taken in the order given, indexed and merged together, and the log gives the indexing +rate of each input beside the run's. They must be one setup - the same detector, wavelength, +distance and beam centre (to 0.1%, 0.1 mm and 1 pixel), since stills geometry refinement refines +one geometry for all frames - and a pixel masked in any of them is masked for all. Stills in the +other formats are given the same way, as all their files: `rugnux run*.h5` (SACLA), `rugnux *.cxi`, +`rugnux *.xtc`. Inputs are always files, read in the order given (a shell glob gives them sorted by +name); a directory is refused. Rotation sweeps are not read together. + +Given the URL of a `jfjoch_broker` (`http://host:port/`) and the path the master file *will* have, +`rugnux` follows the broker's current collection while it is being written: the data files are read +as the broker reports them closed, processing starts on the first images, and the run ends with the +images the collection delivered. A decision made early on a near tie is re-checked on all frames +once the collection is complete. If the check gives a different answer, the run is repeated, so +the result is that of the whole sweep. This is for rotation data and `--mode mx`; the collection's token is read from +`JUNGFRAUJOCH_HTTP_TOKEN` and sent only to the broker. With the master file already on disk, the URL +is ignored. + +> **Note.** `rugnux` is under very active development. This page describes the tool and +> its options at a high level. Run `rugnux` with no arguments for its usage - how to run each mode +> and the basic options; every option is on [Command-line options](RUGNUX_CLI.md). + +```{contents} On this page +:local: +:depth: 2 +``` + +## Quick start + +Rugnux is one executable in an archive on the release page, https://gitea.psi.ch/mx/jungfraujoch/releases. +On Linux x86-64 (the other platforms are on [Download](RUGNUX_DOWNLOAD.md)): + +``` +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 +``` + +To process a dataset, give `rugnux` an output prefix and the dataset: its master file (HDF5), or any +one image of a CBF, marCCD, SMV or SFRM sequence. The example is the 9ZLO dataset (10.8 GB, 19 files, +CC-BY 4.0 on Zenodo): *Proteus mirabilis* UreE, 3600 EIGER images collected at the Australian +Synchrotron. + +``` +mkdir -p demo/9zlo && cd demo +for f in ASP0887_09_0114_master.h5 ASP0887_09_0114_data_0000{01..18}.h5; do curl -L -C - -o 9zlo/$f "https://zenodo.org/records/18652652/files/$f?download=1"; done +rugnux -o 9zlo 9zlo/ASP0887_09_0114_master.h5 +``` + +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 +16-core CPU and an NVIDIA RTX 5080 the run takes 17 s with release 1.0.0-rc.183 (minutes +with `--no-gpu`). `9zlo_report.txt` then says: space group P 21 21 21, cell 38.363 89.746 106.871 +90 90 90, resolution 68.7-1.57 A, completeness 99.7 %, multiplicity 12.7, R_meas 0.120, CC1/2 +0.9994, I/sigma 11.6, ISa 23.6. A second run, another GPU or the CPU repeats the space group, the +cell to 0.1 % and the resolution to one shell. The last digit of a statistic can differ. + +With a model, the run goes on to place and refine it. The AlphaFold prediction of UreE is in this +repository under `tools/battery/models/`, two files; the PAE file is read when it sits beside the +model: + +``` +curl -L -O https://gitea.psi.ch/mx/jungfraujoch/raw/branch/main/tools/battery/models/AF-P17090-F1-model_v6.cif +curl -L -O https://gitea.psi.ch/mx/jungfraujoch/raw/branch/main/tools/battery/models/AF-P17090-F1-predicted_aligned_error_v6.json +rugnux -o 9zlo --model AF-P17090-F1-model_v6.cif 9zlo/ASP0887_09_0114_master.h5 +``` + +Molecular replacement places the two copies (`MR_DECISION= AGREES`), refinement brings them to +R-work / R-free 0.271 / 0.297 (the refined R factors can differ in the second decimal between +builds), and `9zlo_refined_model.cif` and `9zlo_refined_maps.mtz` are written beside the merged +data; the run takes 22 s. The paper's times do not include the refinement; a current run's do. +Every file the run writes is listed under +[Output files](#output-files) and in [A first run in detail](RUGNUX_TUTORIAL.md#a-first-run-in-detail); +the other example datasets are in the repository's top-level README. + +The remaining options are for unusual data and for diagnosis. They are all listed under +[Command-line options](RUGNUX_CLI.md). If a dataset only processes well with one of them, please +report it and send the run's `_report.txt` and `_log.txt`. + +### Rotation data + +``` +rugnux -o myrun dataset_master.h5 # NXmx / EIGER / Jungfraujoch master file +rugnux -o myrun sweep_00001.cbf # a CBF, marCCD or SMV sweep: name one of its frames +``` + +### Serial stills + +``` +rugnux -o serial *_master.h5 # several NXmx masters of one setup, read as one run +rugnux -o serial run*.h5 # all the files of one dataset (SACLA); *.cxi, *.xtc alike +``` + +Inputs are always files, never a directory; a shell glob hands them over sorted by name, and they are +read in that order and merged together. Without a cell the stills are indexed de novo. + +### Serial stills with a known cell, space group and a CrystFEL geometry file + +``` +rugnux -o serial -C 79,79,38,90,90,90 -S P43212 --crystfel-geometry detector.geom run*.h5 +``` + +`-C` is the cell (`a,b,c,alpha,beta,gamma`), `-S` the space group as a symbol (`P43212`) or a number +(`96`). With `-S` the run puts every crystal on one indexing where the space group admits two, from +the data alone. `--crystfel-geometry` places the panels (and takes the masks it names) for HDF5/CXI +input that does not place them itself. The wavelength and the detector distance come from the data +files or the geometry file; only where neither states them add `--wavelength ` and +`--detector-distance ` (the distance is then held, not refined — without it a run with `-C` +searches and refines it). + +### With a model + +``` +rugnux -o myrun dataset_master.h5 model.cif # model and images in any order; +rugnux -o myrun --model model.pdb dataset_master.h5 # or with --model +``` + +A model is told from the images by its contents (PDB, or mmCIF with atoms), gzipped or not. After +merging it is **placed** — as a rigid body, or by molecular replacement where that does not place it or +the model is a prediction (AlphaFold, ModelCIF) — then **refined** against the merge (restrained, +maximum likelihood; seconds on a GPU, typically minutes on the CPU; `--no-refine` skips it) with +its solvent as given; `--refine-solvent` (off by default, also with `--mode refine`) also rebuilds +the solvent - waters added at difference peaks and removed from negative density, ions relabelled +where their surroundings say so, each site audited - and the run writes the maps (σA-weighted 2mFo−DFc / mFo−DFc), the placed and refined model, and +the blobs of difference density the model does not explain. R-work / R-free are in the report. + +The model **does not change the processing**: the intensities, the cell and the resolution are the +ones the data give without it. What it can change is the space group the files are labelled with: +it names the hand of an enantiomorphic pair, which merged intensities cannot tell apart (see below). +A different space group the molecular replacement prefers is never taken into the answer; it is +written beside it as `_mr.mtz`. The one further change is on serial stills with `-C` and +`-S` in a space group that admits two indexings: there the model picks which of them the crystals +are put on, so the merge comes out in the model's indexing. Without a model the data resolve the +ambiguity themselves, consistently but in an arbitrary one of the two. A reference reflection file +(`-z reference.mtz`, also accepted as a positional input) does the same, and steers the processing +from the start (see [Models and reference data](RUGNUX_MODEL_AND_REFERENCE.md)). + +### Output files + +A rotation run that merges — the default — leaves these files next to each other: + +``` +myrun.mtz merged intensities + French-Wilson amplitudes, for CCP4 / phenix +myrun.cif the same, as mmCIF - the self-describing format, and what to deposit +myrun.hkl the scaled observations unmerged, as SHELX HKLF 4 - for SHELXL, SHELXC / ANODE +myrun.ins the SHELX instructions to go with it: CELL, ZERR (the cell's e.s.d.s), LATT, SYMM +myrun_unmerged.mtz the observations unmerged, scaled by the merge, for pointless / aimless - + the largest file of the run (--no-export-unmerged skips it) +myrun_report.txt what the run determined: cell, space group, statistics, warnings +myrun_plot.txt one row per image, for plotting how the crystal behaved over the sweep +myrun_detector.jpg the detector with the pixel mask and the beam-stop shadow drawn on it +myrun_log.txt the full timestamped log of the run (debug level) +``` + +With a model, beside them: + +``` +myrun_maps.mtz map coefficients on the placed model (Coot and PyMOL open it as maps) +myrun_model.cif / .pdb the model as placed, in the cell and space group of myrun.mtz +myrun_refined_model.cif the refined model (and .pdb) +myrun_refined_maps.mtz map coefficients on the refined model +myrun_blobs.json the unexplained difference-density blobs +myrun_solvent.json with --refine-solvent: the refined model's waters and ions, each scored by its surroundings, and the waters the build added and removed +``` + +A stills run writes the same merged files (its `.hkl` holds the merged reflections) and, on a +detector of several modules, `serial_module_placement.json` with where each module was placed (and +`serial_modules.h5` where the refinement moved some). +[Output files](RUGNUX_TUTORIAL.md#output-files) lists every file a run can write. + +A run uses all the machine's threads by default. `-N` limits the thread count, or raises the +per-image loop's default ceiling of 16 workers per GPU. + +Read `myrun_report.txt` first: it says which space group was chosen and on what evidence, how far +the data go, and anything that needs attention. + +### Terminal output + +The terminal shows the run as numbered steps, each with one-line results and the time it took, the +warnings among them, and a summary at the end; everything else goes to `myrun_log.txt`. A note's +time is how long the step ran since the line above it, and the rule under a step gives its total, so +the steps add up to the wall time. Abridged: + +``` +Step 3 Indexing + ... beam centre kept: measured 7.5 px off, same lattice 1.36 s + ... lattice triclinic P: 28.56 35.34 63.56 106.0 90.3 90.3 0.00 s + ... 52/60 validation frames, 24% of their spots on it 0.00 s + ------------------------------------------------------- done in 1.36 s +Step 4 Integration (geometry pre-pass), 1800 images + ... 1800 images, 836 per second 2.15 s + ------------------------------------------------------- done in 2.16 s + ... +Step 9 Scaling and merging + ... merge in P1: 14464 unique 0.64 s + ... space group P 1 21 1 (No. 4) 0.05 s + ... merge in P21: 16847 unique 0.26 s + ... resolution 1.57 A (CC1/2 fall-off at 1.64 A) 0.02 s + ------------------------------------------------------- done in 1.89 s + ... +============================================================================== + Result WARNINGS: Merged to 1.57 A in P 1 21 1. 3 conditions need + attention: SCALING_NOT_CONVERGED, MULTIPLE_LATTICES, ICE_RINGS. + Space group P 1 21 1 + Unit cell 35.337 28.465 62.937 90.000 105.824 90.000 + Resolution 1.57 A written; the CC1/2 fall-off is fitted at 1.64 A + Signal I/sigma 6.0 R_meas 17.2 % CC1/2 0.995 ISa 10.2 + Wall time 11.78 s +============================================================================== + With any question about this run, send myrun_report.txt and myrun_log.txt. +``` + +On a terminal an integration pass draws a progress bar in place; written to a file or a pipe (a +batch job's log) every line starts with the time of day instead, there is no bar, and a long pass +says how far it has got once a quarter. Warnings are marked `!!` and errors `** ERROR:`; a warning +that comes back from a later merge is shown once more on one line and then only counted. `-v` puts +the whole log on the terminal in place of the steps. The log file carries what is needed to answer a +question about a run without the data: version, build, GPU, threads, the command line, the header +geometry, every decision with its numbers, and a timestamp on every line. + +Notes on the defaults: + +- **The reflection files are cut at the resolution where CC1/2 drops below 0.30.** Every reflection file is + resolution-trimmed automatically (`--resolution-cutoff cc-logistic`, one shell past the crossing); + `--resolution-cutoff off` keeps the full measured range, `--scaling-high-resolution` fixes the + limit by hand. If a Rugnux file reaches lower resolution than another program's on the same data, + this cutoff is usually the reason, not missing data. +- **Do not give `-C` or `-S` for rotation data.** A known cell and space group are useful for + serial data, where the `ffbidx` indexer needs a cell. On rotation data they often make + low-symmetry cases worse. Let the cell and space group be determined from the data + (see [Rotation data](RUGNUX_TUTORIAL.md#rotation-data)). `-S` takes a Hermann-Mauguin symbol (`P43212`) or a + space-group number (`96`), whichever is to hand. +- **`-A` is not needed for the anomalous signal.** A rotation merge always keeps the Bijvoet split: a + default run's `.mtz` carries `I(+)`/`I(-)` beside `IMEAN`, its `.hkl` every observation at the index + it was measured at, and the report gives `SIGANO`, `CC_ANOM` and the `ANOM_*` table (the same merge + counted per hand, as an anomalous XDS run counts) on every run. On rotation data `-A` changes + nothing in the processing, the files or the statistics; every decision is taken with Friedel mates + merged, `-A` or not, and the report then only says `FRIEDELS_LAW= FALSE`. Serial stills are + different: their merge keeps no split by default, and there `-A` is what creates one, merging each + Bijvoet hand as a reflection of its own. +- **A model names the enantiomorph.** Where the data accept the model — it is tested against a + null of the same model in random orientations, and `MODEL_FIT=` in the report says the verdict — + `--model` settles which of P41212 and P43212 the merged + reflections are *labelled* with — a choice no merged intensity can make. It is a label and nothing + more: the two groups have the same rotation operations, so no reflection moves, and in particular + I(+) and I(-) are left exactly as measured. Whether the model agrees with the data about the hand + is then a real question, and the anomalous difference map answers it — a run says so when the + density at the model's atoms comes out inverted. +- **`-z` and `--model` overlap but are not the same.** A reference MTZ steers the processing from + the start; a model scores the merge and settles the frame it is written in — where the data + accept it; a model they reject changes nothing. Either resolves an + [indexing ambiguity](RUGNUX_ADVANCED.md#the-indexing-ambiguity) in its own indexing. On serial data the + ambiguity decides whether the merged intensities are usable at all; there the space group (`-S`) alone + already lets the run make the crystals consistent from the data. +- **Small-molecule data need no extra options.** Short axes, spots wider than the integration disk + and glide-plane space groups are handled by default. `myrun.hkl` can be given directly to SHELXT / + SHELXL ([Small-molecule data](RUGNUX_TUTORIAL.md#small-molecule-data)). +- **`--scaling-high-resolution `**, where the resolution is already known, sharpens both the + space-group search and the error model. +- **A run wants memory in proportion to what it integrates**, not to the detector: up to about + 14 GB of host RAM and 7 GB on the card for an ordinary sweep, both peaking in scaling and + merging. [Installing Rugnux ▸ Memory](RUGNUX_INSTALL.md#memory) has the table and the two + flags that lower it. A very large cell needs far more, and a CPU-only build most of all — tens of + GB of host RAM ([Very large unit cells](RUGNUX_INSTALL.md#very-large-unit-cells)). +- **When a run fails** it exits non-zero and says why on the terminal; `VERDICT=` and the `WARNING:` + lines of the report say what needs attention on a run that finished + ([The results report](RUGNUX_REPORT.md#the-summary-and-what-the-run-decided)). A rotation run that indexes + nothing most often has a wrong header: the beam centre is measured on every run, but the distance + and the wavelength are indexed at the values stated — `--detector-distance` and `--wavelength` override them + (`--beam-x`/`--beam-y` the centre); serial stills that index poorly want the cell (`-C`). A run that ends + with `Killed` ran out of memory ([Out of host memory](RUGNUX_INSTALL.md#out-of-host-memory)). + With any question about a run, send `myrun_report.txt` and `myrun_log.txt`. +- Everything else is in [Running Rugnux](RUGNUX_TUTORIAL.md#running-rugnux) and the full + [Command-line options](RUGNUX_CLI.md). + + +## Manual pages + +The manual is split into one page per topic: + +- [Overview](RUGNUX_OVERVIEW.md) — the pipeline from images to merged data and, with a model, a refined structure, + in order. Read this one first. +- [Download Rugnux](RUGNUX_DOWNLOAD.md) — the archive for Linux, macOS and Windows, and the + three commands that run it. +- [Installing Rugnux](RUGNUX_INSTALL.md) — packages, the release archive, GPU drivers, building + from source, hardware. +- [Input formats](RUGNUX_FORMATS.md) — will it open your data: NXmx / EIGER masters, PILATUS + miniCBF, marCCD and SMV (ADSC, Rigaku d\*TREK) sweeps, one sweep per input, and serial XFEL stills + from SACLA (Cheetah HDF5), Cheetah CXI single-panel files and LCLS-I XTC. +- [Running Rugnux](RUGNUX_TUTORIAL.md) — a first run in detail, rotation, serial and small-molecule + data, and every file a run writes. +- [Rugnux with other programs](RUGNUX_INTEGRATION.md) — the reflection-file conventions, the + unmerged export, and worked command lines for phenix, REFMAC, POINTLESS / AIMLESS, careless, + Phaser, SHELXC/D/E and, for small molecules, SHELXT / SHELXL. +- [The results report](RUGNUX_REPORT.md) — the `KEY= value` interface, sweep quality and the + anisotropy section. +- [Command-line options](RUGNUX_CLI.md) — how to run each mode, and every option with what it + does. +- [Advanced usage](RUGNUX_ADVANCED.md) — reference data and the indexing ambiguity, model + validation and re-merging. +- [Models and reference data](RUGNUX_MODEL_AND_REFERENCE.md) — every model and reference option, + and decision by decision what a model can and cannot change. +- [Detector calibration](RUGNUX_CALIBRATION.md) — the geometry from a calibrant's powder rings + (`--mode calibration`). +- [Measuring Rugnux](RUGNUX_BENCHMARKING.md) — the validation battery, the REFMAC check, the timing + benchmark, and how to take timings on another machine that compare with ours. +- [CPU/GPU data analysis](CPU_DATA_ANALYSIS.md) — the algorithms behind all of it. + +## The three analysis tools + +| Tool | Mode | Driven by | Output | +| --- | --- | --- | --- | +| [`jfjoch_broker`](JFJOCH_BROKER.md) | Online, real-time streaming analysis on FPGA + GPU | HTTP/REST + ZeroMQ | Live results and statistics, images streamed to [`jfjoch_writer`](JFJOCH_WRITER.md) | +| [`jfjoch_viewer`](JFJOCH_VIEWER.md) | Interactive, on-screen exploration | Qt desktop application | On screen; a processing job can write the same files as `rugnux` | +| **`rugnux`** | **Offline batch processing of a stored dataset** | **Command-line interface** | **`.mtz`/`.cif`/`.hkl` and the report; `_process.h5` with `--no-merge` or `--write-process-h5`** | + +Use `rugnux` to re-analyse data after acquisition, to experiment with processing +parameters, or to produce merged intensities for downstream structure solution. + + +## How to cite + +If you find Rugnux useful, please cite F. Leonarski and M. Wang, "Rugnux: from diffraction images to +structure at synchrotrons and XFELs in one program" (2026), bioRxiv +[doi:10.64898/2026.10.24.761522](https://doi.org/10.64898/2026.10.24.761522). Rugnux prints this at +startup and at the head of its report; the other papers are on the [Publications](PUBLICATIONS.md) +page. diff --git a/_sources/RUGNUX_ADVANCED.md.txt b/_sources/RUGNUX_ADVANCED.md.txt new file mode 100644 index 000000000..9d8e23b80 --- /dev/null +++ b/_sources/RUGNUX_ADVANCED.md.txt @@ -0,0 +1,350 @@ +# Advanced Rugnux + +The machinery behind a run that needs more than the defaults: external reference data, model +validation and re-merging without re-integration; the option tables are on [Command-line options](RUGNUX_CLI.md). + +```{contents} On this page +:local: +:depth: 2 +``` + +## Reference data and the indexing ambiguity + +### Reference data (`-z`) + +`-z reference.mtz` supplies **known intensities of the same crystal form** — a previously merged +dataset, or `F-model` amplitudes computed from a structure. The reference can equally be a PDB +structure-factor file (`-z 1abc-sf.cif`, SF-mmCIF), gzipped or not; the format is taken from the +file's content. From an mmCIF the first merged reflection block with a usable column is read (the log +names it), its columns under the MTZ labels `gemmi cif2mtz` gives them (`IMEAN`, `FP`, `FC`, …), and +its R-free set from `_refln.status` (`f` free, `o` working), or from `_refln.pdbx_r_free_flag` where +the status marks no test set. It is read once, before processing starts, and used for five things: + +- **It fixes the space group and the unit cell** the run works in, unless `-S` / `-C` override them. + The cell is a *soft* reference: indexing may still drift within tolerance, so a small mismatch + between reference and data is absorbed rather than rejected. +- **It fixes the axes the files are written on.** The group is taken in the setting the reference + is written in (P 2 21 21 stays P 2 21 21, not only "number 18"), and once the run has merged, every + description of its lattice on the reference's axes - axis permutations, sign flips, I- against + C-centred - and every alternative indexing on top is correlated with the reference; the best one is + re-merged and written. `REFERENCE_OPERATOR=` names the operator (`h,k,l` where the data were + already on the reference's axes), `REFERENCE_CC=` and `REFERENCE_MATCHED_FRACTION=` how well the + result matches. +- **It resolves the indexing ambiguity** (below) — the one thing the data cannot settle for + themselves: which of the equivalent indexings is the reference's own. +- **It hands over its R-free test set**, where the file carries one, so every dataset of a campaign + is scored on the same free reflections - in the reference's frame, and only where the merge + matches the reference (CC at least 0.5 over at least half of the merged reflections in its + resolution range). A reference that does not is reported (`REFERENCE_MISMATCH`), and the merge keeps + its own test set; `REFERENCE_FREE_FLAGS_INHERITED=` says which happened. +- **It reports CCref**, the correlation of the merged intensities against the reference, + in the statistics table. Stills only — the rotation merge never scores itself against the + reference, and its table shows `-` in that column. + +A reference is **not** a scale anchor. Both workflows scale against their own data — scaling images +against a foreign dataset injects that dataset's systematics — so `-z` never puts the reference's +errors into the intensities. `--reference-column` picks the column to read where the automatic +choice (`F-model`, else `IMEAN`/`I`, else `FP`/`FOBS`/`F`) is not the right one. + +An atomic model does not take part in the processing: `--model` is placed and validated after the merge, +and a run with one merges exactly what a run without one does. A model that fits then sets the frame the +merge is written in - the hand label, the setting and the indexing (see +[Validating against a model](#validating-against-a-model-rugnux---model)) - by relabelling it, never by re-merging. + +### The indexing ambiguity + +Some crystals can be indexed in **more than one way, each equally valid geometrically, and each +giving different merged intensities**. This happens whenever the lattice is more symmetric than the +crystal: in P3, P4, P6, P31, C2 and their relatives (*merohedral*), and also where the +cell is metrically more symmetric than the Laue class by accident (*pseudo-merohedral*, up to 2° of +obliquity). The alternatives are related by the crystal's **twin laws** — reindexing operators such +as `k,h,-l`. + +Nothing in the data says which solution is the *true* one: the merge is equally self-consistent +either way, so which comes out is arbitrary. What that costs depends on the workflow: + +- **Rotation.** The whole sweep is one lattice, so the whole dataset lands in one indexing, picked + at random. The merge itself is sound; it may simply be the *other* solution from an earlier + dataset of the same crystal form, and the two cannot be combined, compared or phased against the + same model. +- **Serial stills.** Every crystal is indexed independently, so a run mixes both indexings into one + merge. That is not a labelling matter — reflections that are not symmetry mates get averaged + together, and CC1/2, Rmeas and the anomalous signal all degrade. The data *can* say + which crystals are in the same indexing, though, and that is what a merge needs: with the space + group given (`-S`) and no reference, Rugnux puts each crystal into the indexing in which it agrees + best with all the others, before anything is scaled. This takes seconds for tens of thousands of + crystals, and the report says how clearly the crystals separated (`AMBIGUITY_SEPARATION_SIGMA=`, + `AMBIGUITY_DECIDED_FRACTION=`) and how many were moved (`AMBIGUITY_REINDEXED=`). The indexing the + whole merge ends up in is still arbitrary against other data sets, exactly as on rotation data. + On a pseudo-merohedral cell each crystal's own refined cell also says something about which axis is + which, as far as the run's axes differ by more than one crystal's cell scatters; it is weighed + beside the intensities, crystal by crystal, and decides where they cannot. + +Every run that merges tests for the ambiguity, and where it exists and nothing resolves it (serial +stills whose space group was determined by the run rather than given), says so in the log and in the +report's warnings: + +``` +Indexing ambiguity: this cell / space group admits alternative indexing (reindex operator(s): +-h,-k,l). Serial-stills crystals are indexed in one hand at random, and rugnux makes them consistent +from the data only where the space group is given: here it was determined by the run, so the merge +mixes the hands and CC1/2 is degraded. Giving the space group (-S) resolves it from the data; a +reference MTZ (-z) or a model (--model, which needs -S here) resolves it against them. +``` + +Where something does resolve it, the run says so instead — `Indexing ambiguity present (reindex +operator(s): -h,-k,l); resolved against the supplied reference` or `...; resolved from the data`. + +How to resolve it: + +| Situation | What to do | +| --- | --- | +| **Rotation**, a reference dataset exists | `-z reference.mtz`. Once the space group is settled, each candidate reindexing of the merged intensities is correlated with the reference and the best-correlating one is re-merged. Only the *hkl* labels change; the cell does not | +| **Serial stills**, a reference dataset exists | `-z reference.mtz`. The crystals are made consistent with each other as in the rows below, and the reference fixes the indexing the merge is written in. A crystal is decided by its agreement with all the others and its own cell rather than by the reference, which reads a weak crystal less clearly than the merge of all the others does: `AMBIGUITY_DATA_DISAGREES=` counts the crystals put elsewhere than the reference alone would | +| **Rotation**, only a model | `--model model.pdb`. The merged data are fitted to the model in each candidate indexing and the lowest R-free wins — provided the model first beats its random-orientation null (`MODEL_FIT= ACCEPTED`) and its lead over the runner-up beats the lead a random placement of the same model takes; the written reflections are then reindexed into it, so the file, the R-factors and the maps agree. Where either bar is missed the data keep the indexing they were merged in, and the report says by how much (`MODEL_INDEXING_MARGIN_SIGMA`). It is the **data** that are relabelled, never the model: every dataset of one crystal form processed against the same model comes out in that model's indexing, so the reflection files and maps of a screening campaign compare directly. The relabelling is a proper rotation of the lattice, so the merging statistics are unchanged and I(+)/I(-) keep their hand | +| **Serial stills**, only a model, space group given (`-S`) | The crystals are made consistent with each other from the data alone, as in the row below - the model plays no part in the processing. Validation then fits the merge to the model in each candidate indexing, as for rotation data, and relabels the written reflections into the model's indexing where it wins | +| **Serial stills**, neither, space group given (`-S`) | Nothing to do: the crystals are made consistent with each other from the data alone (`INDEXING_AMBIGUITY_RESOLVED= data`), in an indexing that is arbitrary against other data sets. A reference still settles the weakest crystals more reliably than the other crystals can, and puts the merge in its own indexing | +| Neither | The run warns and merges in whichever indexing it found: for rotation data a usable dataset in an arbitrary frame; for stills whose space group the run determined, a merge of mixed indexings, which looks like a perfect twin and can pass for higher symmetry than the crystal has. Run again with `-S` | + +Two things to know about where the choice lands: + +- **`--mode scale` resolves it as the full run does.** On stills with no reference MTZ it makes the + crystals consistent from the data alone before merging; with `-z` the reference fixes the indexing of + the whole, as in a full run with the reference - so one reference puts several runs, or both arms of a pump-probe run, in + the same indexing. On rotation data, where + the ambiguity is one choice for the whole dataset, `--mode scale --model model.pdb` does resolve it. +- **The choice reaches the written reflections**, not only the R-factors and the maps: the merged + `.mtz` / `.cif` / `.hkl` (and `_unmerged.mtz`, where it is asked for) are written in the indexing + the model or the reference settled on, so the file can be refined against that model as it stands. + +Two things the indexing ambiguity is **not**: + +- **Not the enantiomorph.** P41212 versus P43212 (or + P31 versus P32) leaves the merged intensities *unchanged*, so no amount of + data can choose between them and Rugnux never tries — the run reports the pair it cannot separate. + A model the data accept names it (`MODEL_FIT= ACCEPTED` in the report), and the naming is a + label only: the written reflections take + the model's space group, no reflection moves, and I(+)/I(-) stay exactly as measured — reindexing + by the change of hand would flip every anomalous difference, so it is never done. Whether the + model and the data really agree about the hand is answered afterwards by the anomalous difference + map, which warns when the density at the model's atoms comes out inverted. The + `_process.h5`, whose per-image reflections were written as they were integrated, keeps the group + the run determined and is left alone. +- **Not twinning.** The twin laws are the same operators, but twinning is a property of the crystal + — two orientations diffracting at once — and is reported separately in the report's twinning + section. A crystal can have an indexing ambiguity without being twinned, and usually is not. + +The algorithms behind both are in +[CPU/GPU data analysis ▸ Reference data](CPU_DATA_ANALYSIS_INTEGRATION.md#109-reference-data-fixing-the-space-group-and-resolving-the-indexing-ambiguity). + +## The setting the files are written in + +The space-group search decides which axes carry the screws and the centring on the cell as it was +indexed, whose axes are ordered by length. The files are then written in the **standard setting**, +as XDS and POINTLESS write it (`SETTING_SOURCE=STANDARD`): P2221 and P21212 with the unique axis on +c and a= 90; triclinic keeps the reduced cell. So a crystal +indexed as 52.51 87.87 137.72 in P 2 21 21 is written as 87.87 137.72 52.51 in P 21 21 2. + +What the user gives takes precedence, in this order: a reference MTZ (`-z`, its own setting), a +model that fits (`--model`, its setting), the axis order of a cell given with `-C` +(`SETTING_SOURCE=CELL`), and the setting of a group given with `-S` by a non-standard symbol +(`-S "P 2 21 21"`, `SETTING_SOURCE=SPACE_GROUP`). A group given with `-S` is also placed on the axes +its absences name before anything is merged, so `-S 18` on a cell whose pure two-fold is its shortest +axis puts the screws on the right rows. + +The change is a relabelling made after every decision - nothing measured, and no decision, depends +on it - and it is applied to everything the run writes: the merged `.mtz`/`.cif`/`.hkl`, +`_unmerged.mtz` and the `_process.h5` (whose per-image reflections carry the reindex +matrix). `SETTING_OPERATOR=` gives it as a reindexing operator on the indices the space group was +determined on, CCP4 style (`k,l,h` is h'=k, k'=l, l'=h); `h,k,l` where nothing moved. + +## Validating against a model (`rugnux --model`) + +Which decisions a model can influence, and which it cannot, is set out decision by decision in +[Models and reference data](RUGNUX_MODEL_AND_REFERENCE.md). + +Given an atomic model of the same structure, `--model model.pdb` scales the model structure +factors to the merged amplitudes — fitting a flat bulk-solvent contribution and an overall +anisotropic *B* — and reports **R-work / R-free** and the mean 2mFo−DFc density at the atom centres. +Where the model is placed it also writes the map-coefficient MTZ `_maps.mtz` next to the merged +reflections (a model placed nowhere, `MODEL_PLACEMENT=NOT_PLACED`, gets no model or maps files): the +σA-weighted 2mFo−DFc and mFo−DFc coefficients, which Coot and PyMOL open directly as +maps. As phenix.refine and BUSTER write theirs, the coefficients have the data's overall anisotropy divided out and +the 2mFo−DFc map `FWT`/`PHWT` is filled with DFc at the reflections the data do not have; `FWT_no_fill`/`PHWT_no_fill` +is the same map without them, and the difference map `DELFWT`/`PHDELWT` is never filled. Where the merge kept the Bijvoet split (a rotation merge always does), an anomalous +difference map is made too, its coefficients in the same MTZ (`ANOM`/`PHANOM`): the report names its +strongest sites (`ANOMALOUS_SITE_01`…`10`), the map's mean height at the model's anomalous scatterers - +every atom from phosphorus up - as one number for the anomalous signal (`ANOMALOUS_SCATTERER_MEAN_SIGMA`), +and the map's peaks of 5 σ or more that no such atom of the model sits on (`ANOMALOUS_UNEXPLAINED_PEAK_01`…): +an ion or a heavy atom the model leaves out, with its position and the model's nearest atom. +The model is not refined for these numbers (a placed model is refined afterwards, on the side - see +[Refinement](RUGNUX_MODEL_AND_REFERENCE.md#refinement)); it is re-fractionalized into +the data cell and then placed as **one rigid body**, so a deposited model from a crystal that is not +quite isomorphous still sits where the density is. The placement runs on the GPU where there is one +and on the CPU otherwise, with nothing to set; the two agree to rounding, not bit for bit. + +The rigid body only moves a model that already sits near its place, so its placement is **checked**: +the model counts as placed where its fit beats the same model refitted from random orientations (the +null behind `MODEL_FIT`, below), in the answer's merge or in the twin hypothesis' one. An experimental +model the rigid body does not place — a deposited structure of another crystal form, a model of a +subgroup the data were merged above, a file with no crystal cell — is then searched for by +**molecular replacement**: as many copies as the cell holds, in every space group the merge cannot tell +apart and in the twin hypothesis' subgroup (the search and its keys are in +[Molecular replacement](RUGNUX_REPORT.md#molecular-replacement)). A **predicted** model — AlphaFold or +ModelCIF, recognised from the file's content (pLDDT in the B column) — has no placement of its own and +goes to molecular replacement straight away, trimmed to the residues of pLDDT 70 and above and, where +the AlphaFold DB's predicted-aligned-error JSON sits beside it under its own name, cut into rigid +domains. `--mr ` is `--model` with the rigid body skipped: molecular replacement straight away, +whatever the model. The report says which way the model was placed, `MODEL_PLACEMENT=` `RIGID_BODY`, +`MR` or `NOT_PLACED`; a model placed nowhere is a result, not a warning, and the reflection files are +then what a run without a model writes. Where molecular replacement placed it, the R-factors, the maps +and the placed model below are those of its placement. Molecular replacement is part of the full +`--mode mx` run, rotation and serial stills alike; `--mode scale` (below) places the model by the +rigid body alone. + +A placed model changes two things in `.mtz`/`.cif`/`.hkl` and nothing else: the +**enantiomorph** label and, placed by the rigid body, the +[indexing ambiguity](#the-indexing-ambiguity) (molecular replacement relabels the hand, past the same +anomalous check, and never reindexes). Where the model chooses **another space group** with the +answer's rotations, or the **twin hypothesis' subgroup**, the answer's files stay the run's own and that +merge is written beside them as `_mr.mtz`/`.cif` — from the merge it was chosen on, with the +twin law and fraction where it is the subgroup — together with the model as placed there, +`_mr_model.pdb`/`.cif`; the report names them (`MODEL_CHOICE_FILE_PREFIX=`, +`MODEL_CHOICE_SPACE_GROUP=`). + +Because the model moves, the input file no longer describes these maps, so the model **as placed** is +written as `_model.cif` — the input's chains, residues, ligands, waters, B-factors, +occupancies and anisotropic *U*s, at the coordinates the maps were computed from, in the same unit +cell and space group as `.mtz` beside it. The same coordinates are written as +`_model.pdb` as well, because the fragment-screening tools this file exists to feed take a +PDB: PanDDA's per-dataset input is `.pdb` beside `.mtz`, and dimple produces that same +pair. (The PDB is skipped, with a log line, for a cell its fixed-width format cannot hold; the mmCIF +is unconditional.) That is the file to open with the maps, and the one +to hand to REFMAC5 or `phenix.refine`; its starting R-free is the `R_FREE=` the report quotes. +Rugnux's own refinement of it is written beside it as `_refined_model.cif` with +`_refined_maps.mtz` ([Refinement](RUGNUX_MODEL_AND_REFERENCE.md#refinement)). +(`.cif` is the merged **reflections** — hence the separate name.) + +Where the run also wrote a **twin hypothesis** — `_twin_.mtz`/`.cif`, the same data merged +in a subgroup with a twin law, written when the adopted space group may have absorbed one (see +[the twin hypothesis](RUGNUX_REPORT.md#the-twin-hypothesis-twin_subgroup_)) — the model is scored +against that merge as well, plainly and as twinned by the law, and the maps and `_model.cif` +come from whichever of the two merges the model fits better on R-free. The report says which +(`MAPS_FROM=`) and gives the R-free of both. `.mtz` and the space group are the run's own +either way; where the model also fits that merge against its null, it has chosen the subgroup, and the +merge is written once more as `_mr.mtz`/`.cif` (above). The maps and the model are written +only for a model that was placed (`MODEL_PLACEMENT=` `RIGID_BODY` or `MR`): one the data rejected and +molecular replacement did not place is no model of this crystal, and its coordinates and maps would read +as a placement. Its R-factors stay in the report as the negative result. + +The model may be **PDB or mmCIF**, gzipped or not, and the format is taken from the file's own +content rather than from its name — a model downloaded as `.cif`, `.pdb`, `.ent` or with no useful +extension at all is read the same way. A model that cannot be read, or that has no atoms, no unit +cell or no usable space group, does not fail the run: it is logged, and the results report carries a +`WARNING: Model validation did not run: …` line, so a run that silently produced no R-free and no +maps cannot be mistaken for one that was never given `--model`. + +Either way the results report carries a **`5. MODEL VALIDATION`** section: `R_WORK=` / `R_FREE=` +with their reflection counts, `R_MODEL_SHELL_SCALED=` and `MODEL_RADIAL_MISFIT=` beside them (the R +that compares between two runs, and why the other two do not — see +[RUGNUX_REPORT](RUGNUX_REPORT.md)), the bulk-solvent and overall scale parameters, the mean 2mFo−DFc density +at the atom centres, the reindexing operators the written reflections were brought into the model's +frame with, and `MAPS_PREFIX=`; or `MODEL_VALIDATION= NOT_PERFORMED` with +`MODEL_VALIDATION_REASON=` when the model could not be used. A run given no `--model` has no such +section at all. + +It is a *data-quality lens*, independent of the internal statistics: R-free measures the merged +intensities against external truth, where CC1/2 and Rmeas only measure them against +themselves. It also settles the two things merged intensities alone cannot, in two different ways — +though only where the data **accept the model first**: the same model is refitted, and re-placed, from +random orientations about its own centroid, and the real fit has to beat that null (`MODEL_FIT=` in +the report; [§14.5](CPU_DATA_ANALYSIS_DECISIONS.md#145-does-the-model-fit-the-null-it-is-scored-against)). +A model that fits no better than its own random placements decides nothing, and the reflection files +are byte for byte what a run with no model would have written. The +enantiomorph is a **relabelling**: data merged in P41212 against a +P43212 model take the model's space group as the label they are written +under, with no reflection moved and I(+)/I(-) exactly as measured. A merohedral +[indexing ambiguity](#the-indexing-ambiguity) — when no reference MTZ has already fixed it — is a +**reindexing**: the candidate with the lowest R-free is kept — where its lead over the runner-up +beats the lead a random placement of the same model takes — and applied to the **written +reflections** as well as to the R-factors and the maps; otherwise the data keep the indexing they +were merged in. This is distinct from a model written in another *description* of the lattice — other +axes, a different unique axis, I-centred where the run indexed C-centred — or in another point group: +there the model is first put into the data's description (`MODEL_CHANGE_OF_BASIS=`) to be scored. +A model that asserts such a setting is then tested against its random placements like any other +claim, and where it **fits**, the data move instead: the files are written in the model's setting +(`SETTING_SOURCE=MODEL`), and the validation is made once more on those axes so the maps and +`_model.pdb` match them. Where it does not fit, the files stay in the standard setting. +Validation runs before the reflection +files, so the `.mtz` / `.cif` / `.hkl` come out in the model's frame either way — reindexed where +the ambiguity decided, and carrying the model's space group where the hand was adopted. The log names the operator in each case, and for the indexing choice gives the winning +R-free together with the runner-up. + +## Re-scaling and re-merging (`rugnux --mode scale`) + +The `scale` mode re-scales and merges the *already-integrated* reflections stored in a +`_process.h5` file, without re-running spot finding or integration. Use it to re-merge quickly with a +different space group, resolution limit, anomalous setting or outlier rejection. It reuses the same +`-o/-N/-s/-e/-S/-A/-z/--scaling-*` options as the full run, and (unlike the full pipeline) does +not run a space-group search: it merges in the space group and unit cell the file records, and `-S` +/ `-C` override them. A `_process.h5` written before the group was stored carries none, and merges +in P1 unless `-S` says otherwise. + +A reference MTZ (`-z`) is accepted here on **stills** data, where it fixes the space group and cell, +reports CCref and hands over its R-free flags; on rotation data the rotation scaler +declines it and the run stops with a message saying so. `--model` works here as in a full run, except +that the model is placed by the rigid body only: a model it does not place, or a prediction, is not +searched for by molecular replacement, `--mr` is refused, and the placed model is not refined. On rotation data, where the +[indexing ambiguity](#the-indexing-ambiguity) is one choice for the whole dataset, it can settle the +enantiomorph label and the indexing — under the same fit test as always — and the re-merged reflections are written in what it settled. On +stills the re-merge is the full run's own merge: the same frames (a given cell's population, as +`/entry/MX/stillsGivenUnitCell` records it), the same rocking curve, the same data-only resolution of +the indexing ambiguity and the same scaling, so a +`_process.h5` merged again with the options it was written with reproduces the full run's reflections +(with a reference MTZ, the full run also lets the crystals' own cells overrule the reference's indexing +before merging, which `--mode scale` does not). + +Where the full run re-seated the lattice — the space group it settled on is in a different setting +from the one each image was indexed in — the file records the change of basis as +`/entry/MX/reindexMatrix`, and `rugnux` applies it on read, so the reflections and the stored cell +describe the same frame. A file whose stored cell and reflections disagree stops with a message +naming both cells and the exact `-S`/`-C` override to merge it in its own setting. + +## The merged mmCIF (`.cif`) + +The `.cif` follows the PDBx/mmCIF dictionary and holds one data block, `data_sample`: the merged +reflections (`_refln`: I, F and the Bijvoet mates, with the free set in `_refln.status`) and what +describes them - the cell and space group; `_software` with Rugnux named twice, once for +`data reduction` and once for `data scaling`; the experiment as the input file states it +(`_diffrn.ambient_temp` from the sample temperature, the wavelength, the source's facility and +beamline and its general class, the detector's make and model in `_diffrn_detector.type` and its +class in `_diffrn_detector.detector`, and the collection date from the NXmx start time); and the +merging statistics overall (`_reflns`) and per shell (`_reflns_shell`): completeness, multiplicity, +, R_merge, R_meas, R_pim (`?` on a stills merge, where they mean nothing), CC1/2 and CC\*, and SigAno where an anomalous split was made; on rotation data the cell carries +its e.s.d.s (`_cell.length_a_esd`, …). A +quantity the input does not state is left out rather than guessed. The unmerged observations are in +the `_unmerged.mtz` and the `.hkl` (both scaled on a rotation merge), not in the `.cif`. + +Items PDBx does not define — ISa, the error model, the twinning and anisotropy diagnostics, the +refined distance and beam centre — are written under the `jfjoch_` local prefix, which a dictionary +check reports as unknown and a deposition ignores. + +### Provenance + +Every reflection file says where it came from, so that it can be traced back without the report +beside it: + +- the **`.cif`** names the Rugnux version in `_software.version` and the commit it was built from in + `_software.description`, and the command line, the input file (absolute path) and the input's + identity under `_jfjoch_provenance.command_line`, `.input_file` and `.input_identity`; +- the **`.mtz`** and the **`_unmerged.mtz`** carry the same in their `HISTORY` records (`mtzdump` + prints them), each run on over further records where it is longer than the 80 characters of one. + +The identity is the input file's size and modification time — for an HDF5 data set, the master +file's — which tells two files of one name apart without reading the data. A collection followed from +the broker is not a file here, and has none. + +## Command-line options + +Every option, with what it does, is on its own page: [Command-line options](RUGNUX_CLI.md). diff --git a/_sources/RUGNUX_BENCHMARKING.md.txt b/_sources/RUGNUX_BENCHMARKING.md.txt new file mode 100644 index 000000000..091d8fbc0 --- /dev/null +++ b/_sources/RUGNUX_BENCHMARKING.md.txt @@ -0,0 +1,640 @@ +# Measuring Rugnux: validation and timing + +This page is for anyone who has to say how well, or how fast, `rugnux` works on a machine: a +colleague with a new GPU server, a laptop, a Mac, an ARM box, or an agent running there on someone's +behalf. It explains the two measurements the project uses, how to run them, how to read what they +print, and how to take timings that can be compared with someone else's. `tools/battery/README.md` +in the source tree is the detailed guide to the runner itself: every option, the manifests, the +scoring rules and the `results.json` schema. This page summarises it and does not replace it. + +```{contents} On this page +:local: +:depth: 2 +``` + +## Two measurements, one runner + +Everything goes through one script, `tools/battery/battery.py`. Do not write your own loop over +datasets: numbers made by ad-hoc scripts have never been comparable with each other, which is why +the old ones were retired. + +- **The validation battery** (`battery.py run`) processes a fixed list of rotation datasets and + scores each answer against an independent reference. It answers *is the result right, and as + good as the reference*. A full run takes hours. +- **The timing benchmark** (`battery.py timing`) processes four sets, each started from a model + that has to be placed by molecular replacement, so one short run exercises the whole pipeline + and also checks that the answers are right. It answers *how fast, on this machine*. It takes + minutes, and needs nothing on the machine but four open datasets. + +Serial stills have a battery of their own, `tools/battery/still_battery.py`, on the public datasets +of [External test data: serial crystallography](EXTERNAL_TEST_DATA_STILLS.md). It shares the site +config, the verbs and the run-directory layout, but scores nothing about the lattice or the symmetry +(a serial user gives the cell and the space group): each row says what the merge is worth (R_split, +the deposited model's R-free against it beside the deposition's own) and what it cost. The README's +*The still battery* describes it. + +The two are kept apart on purpose. A battery run reads hundreds of gigabytes once, so its wall clock +mostly measures the disk and the page cache (see [the page-cache trap](#the-page-cache)). Use the +battery to judge correctness and the timing benchmark, run under controlled conditions, to judge +speed. + +### Setting up a machine + +The runner needs Python 3.9 or newer with `gemmi` and `numpy` (`pip install gemmi numpy`), a +`rugnux` binary, the datasets, and a **site config**: a small JSON file naming this machine's data +roots, where runs go, the GPU lock and the persisted baselines. `tools/battery/site.example.json` is +the template. The runner looks for the config in `--site PATH`, then in `$JFJOCH_BATTERY_SITE`, +then in `tools/battery/site.json`, which git ignores. `--site` is an option of the script itself, +so it goes **before** the subcommand: + +``` +python3 tools/battery/battery.py --site /path/to/site.json run --rugnux build/rugnux/rugnux --tier smoke +``` + +A relative path in the site config (data roots, runs root, lock file, caches) is taken relative to +the site config's own directory, so a config shipped beside its data works wherever it is unpacked. +A `pdb_cache` copied from another machine can be used as it is: the coordinates are looked up where +the cache now is, not where its `.json` files say they were first fetched. + +The data layout (`//...`) and where to get each arm's data are in the README's +*Getting the data*. The open arm is public (each dataset's DOI is in +[External test data](EXTERNAL_TEST_DATA.md)); the in-house data come from the maintainers. The +timing benchmark needs only four open dataset directories and the smallest site config there is +([below](#what-a-machine-needs)); models, references and expected answers are all in the repository. + +## The validation battery + +### Arms and references + +The battery has three **arms**, each scored against a reference that does not come from `rugnux`: + +| arm | datasets | scored against | +|---|---|---| +| open | public PDB depositions of raw diffraction data, plus a few published small-molecule sets | the deposition: its space group, cell and resolution | +| inhouse | standard test crystals (lysozyme, thaumatin, insulin, cytochrome C, myoglobin), small-molecule standards, and no-crystal controls | XDS, from the `CORRECT.LP` stored beside each dataset | +| private | user data | XDS, as in-house | + +Each set runs **once**, with one command per arm. The open arm runs +`rugnux -o p --no-export-unmerged --model `. The XDS arms run +`rugnux -o p --no-export-unmerged [-A] --report-resolution , [--model ] `, +with `-A` where XDS merged with Friedel's law off. Neither `--model` nor `--report-resolution` +changes the processing: the merged reflections, the resolution cut and every decision are the same +with or without them (this has been checked bit for bit). So one run gives both what a user gets +and the extra report sections that compare it with the reference. + +### Verdicts + +Every set gets one verdict. Scoring asks four questions in order, and the first that fails decides: +did it run, is the lattice right, is the symmetry right, and, on the XDS arms, is the merge as good +as XDS's? + +- **pass**: the lattice matches the reference (Niggli-reduced primitive cells: volume ratio 0.95 to + 1.05, reduced edges within 2%) and so does the symmetry. On the open arm the space group is + compared; on the XDS arms only the point group, because XDS never tests a screw axis. A group + that the intensities cannot tell apart from the reference (same Laue class, same systematic + absences) passes as `indistinguishable_alternative`. A row whose manifest lists a second + defensible answer can pass as `accepted_alternative`. The report counts both kinds separately. +- **fail**, with a `cause`: wrong lattice (`lattice_halved`, `lattice_doubled`, ...), wrong + symmetry (`sym_under`, `sym_over`, `sym_screw`, ...), a reader or indexing failure, a timeout. +- **crash**: rugnux was killed by a signal, its log shows `Processing failed`, a GPU fault, an + uncaught exception, or a non-zero sanitizer summary. A crash fails the set whatever its report + says. +- **unscored**: a question the data cannot answer. Either there is no reference, or the hand of an + enantiomorphic pair is in question, or a screw axis lies on a row the sweep never measured (and + rugnux said so). This is not a pass, but it is not counted as a failure either. +- **not_run**: the input is missing. + +A no-crystal control passes only when rugnux reports no lattice. **Data quality is reported, not +scored**: resolution, CC1/2, R_meas, ISa, completeness and the model R-factors are shown next to +the reference's values for a human to judge. + +### The like-for-like table + +On the XDS arms, rugnux keeps its own resolution cut and the reference does not change it. +`--report-resolution` adds a second statistics table (the `REFRES_*` keys of the report) made from +the same merge but binned over XDS's own range. That gives two separate answers. The own numbers say +what a user gets. The reference-range numbers say whether rugnux's merge is better than XDS's over +the same reflections. Where rugnux's cut is coarser than XDS's, the shells past it were never +merged, so the completeness there measures **coverage**, not a drop in quality. The report marks +those rows. + +On the open arm the deposition gives only a space group, a cell and a resolution, so the data +quality is judged from outside: R-free of the deposited model, from `rugnux --model` (a trend number, +see below) and from the REFMAC check, and a per-shell correlation of the merge with the model beside +the depositor's own data (always on, needs no CCP4). + +### Running it + +``` +B="python3 tools/battery/battery.py --site /path/to/site.json" +R=build/rugnux/rugnux + +$B run --rugnux $R --only 5reo,lyso_ref # named sets +$B run --rugnux $R --tier smoke # readers, symmetry classes, known hard cases +$B run --rugnux $R --tier ci # the routine regression check CI runs on every push +$B run --rugnux $R # the full battery: open + inhouse +$B run --rugnux $R --gpulock --model-check # queued behind the site's GPU lock, with REFMAC +``` + +`--threads N` passes `-N` to rugnux, `--extra ""` adds rugnux arguments to every set, +`--label` names the run, and `--baseline RUN|none` picks the run the report is compared against. +`--gpulock` puts every rugnux behind the command the site config names as `gpulock` (at PSI, a +`flock` wrapper shared by every GPU job on the machine). A run made that way is marked +"timing NOT a reference", and so is a run that found another process on the GPU before a set. + +`run` exits with status 1 when any set crashed or a ci-tier set failed. Other failures and every +metric are reported, not judged. + +### The run directory + +Each run gets a new directory `/__ + + + + diff --git a/_static/searchtools.js b/_static/searchtools.js new file mode 100644 index 000000000..2c774d17a --- /dev/null +++ b/_static/searchtools.js @@ -0,0 +1,632 @@ +/* + * Sphinx JavaScript utilities for the full-text search. + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename, kind] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename, kind] = item; + + let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + listItem.classList.add(`kind-${kind}`); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + SearchResultKind.title, + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + SearchResultKind.index, + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + SearchResultKind.object, + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + SearchResultKind.text, + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/_static/sphinx_highlight.js b/_static/sphinx_highlight.js new file mode 100644 index 000000000..8a96c69a1 --- /dev/null +++ b/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/_static/stylesheets/application-fixes.css b/_static/stylesheets/application-fixes.css new file mode 100644 index 000000000..bbe6ad0e7 --- /dev/null +++ b/_static/stylesheets/application-fixes.css @@ -0,0 +1 @@ +@charset "utf-8";.md-nav--primary ul,.md-nav--primary ul li ul,.md-nav--secondary ul,.md-nav--secondary ul li ul{margin:0;padding:0;list-style:none}.md-nav--primary ul li,.md-nav--primary ul li ul li,.md-nav--secondary ul li,.md-nav--secondary ul li ul li{padding:0 .6rem}.md-nav--primary a.reference,.md-nav--secondary a.reference{display:block;margin-top:.625em;transition:color .125s;text-overflow:ellipsis;cursor:pointer;overflow:hidden}.md-typeset td p,.md-typeset th p{margin:0}.md-typeset .admonition,.md-typeset details{font-size:.8rem}.classifier:before{font-style:normal;margin:.5em;content:":"}dl.footnote>dt,dl.citation>dt{float:left}code.xref{background-color:transparent;font-weight:bold}table.docutils{width:100%}.longtable tr td:first-child{width:50%;white-space:nowrap}dt:target{margin-top:-3.55rem;padding-top:3.45rem}.md-typeset code{margin:0}ul.search li div.context{color:#888;margin:2px 0 0 30px;text-align:left}span.highlighted{background-color:#fbe54e}p.rubric{margin-top:1rem;font-weight:bold}dl.field-list>dt{font-weight:bold;word-break:break-word;padding-left:.5em;padding-right:5px}table.longtable{border-collapse:collapse}.longtable tr{border:solid;border-width:1px 0}.longtable tr:first-child{border-top:none}.md-tabs code,kbd,pre,.md-footer-nav code,kbd,pre{color:#fff}.toctree-wrapper.compound li{list-style:none;padding:0;margin:0 0 .1rem .2rem}table.indextable.genindextable li{margin:0 .5rem}table.indextable.genindextable li ul li{list-style:none}p.highlight-link{margin:.625rem 0 0 0}table.longtable.docutils.align-default{width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch}@media only screen and (max-width:40em){table.longtable.docutils.align-default{display:block}.longtable.docutils.align-default td{padding-right:1rem}}.md-nav__extra_link:after{font-family:Material Icons;font-style:normal;font-variant:normal;font-weight:400;line-height:1;text-transform:none;white-space:nowrap;speak:none;word-wrap:normal;direction:ltr}.md-nav__extra_link{display:block;margin-top:.625em;transition:color .125s;text-overflow:ellipsis;cursor:pointer;overflow:hidden}.md-nav__extra_link:active{color:#3f51b5}.md-nav__extra_link:focus,.md-nav__extra_link:hover{color:#536dfe}@media only screen and (max-width:76.1875em){.md-nav--primary .md-nav--secondary .md-nav__extra_link{position:static}.md-nav--primary .md-nav--secondary .md-nav .md-nav__extra_link{padding-left:1.4rem}.md-nav--primary .md-nav--secondary .md-nav .md-nav .md-nav .md-nav__extra_link{padding-left:2.6rem}}[data-md-color-primary=red] .md-nav__extra_link:active{color:#ef5350}[data-md-color-primary=red] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=pink] .md-nav__extra_link:active{color:#e91e63}[data-md-color-primary=pink] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=purple] .md-nav__extra_link:active{color:#ab47bc}[data-md-color-primary=purple] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=deep-purple] .md-nav__extra_link:active{color:#7e57c2}[data-md-color-primary=deep-purple] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=indigo] .md-nav__extra_link:active{color:#3f51b5}[data-md-color-primary=indigo] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=blue] .md-nav__extra_link:active{color:#2196f3}[data-md-color-primary=blue] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=light-blue] .md-nav__extra_link:active{color:#03a9f4}[data-md-color-primary=light-blue] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=cyan] .md-nav__extra_link:active{color:#00bcd4}[data-md-color-primary=cyan] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=teal] .md-nav__extra_link:active{color:#009688}[data-md-color-primary=teal] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=green] .md-nav__extra_link:active{color:#4caf50}[data-md-color-primary=green] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=light-green] .md-nav__extra_link:active{color:#7cb342}[data-md-color-primary=light-green] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=lime] .md-nav__extra_link:active{color:#c0ca33}[data-md-color-primary=lime] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=yellow] .md-nav__extra_link:active{color:#f9a825}[data-md-color-primary=yellow] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=amber] .md-nav__extra_link:active{color:#ffa000}[data-md-color-primary=amber] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=orange] .md-nav__extra_link:active{color:#fb8c00}[data-md-color-primary=orange] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=deep-orange] .md-nav__extra_link:active{color:#ff7043}[data-md-color-primary=deep-orange] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=brown] .md-nav__extra_link:active{color:#795548}[data-md-color-primary=brown] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=grey] .md-nav__extra_link:active{color:#757575}[data-md-color-primary=grey] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-primary=blue-grey] .md-nav__extra_link:active{color:#546e7a}[data-md-color-primary=blue-grey] .md-nav__item--nested>.md-nav__extra_link{color:inherit}[data-md-color-accent=red] .md-nav__extra_link:focus,[data-md-color-accent=red] .md-nav__extra_link:hover{color:#ff1744}[data-md-color-accent=pink] .md-nav__extra_link:focus,[data-md-color-accent=pink] .md-nav__extra_link:hover{color:#f50057}[data-md-color-accent=purple] .md-nav__extra_link:focus,[data-md-color-accent=purple] .md-nav__extra_link:hover{color:#e040fb}[data-md-color-accent=deep-purple] .md-nav__extra_link:focus,[data-md-color-accent=deep-purple] .md-nav__extra_link:hover{color:#7c4dff}[data-md-color-accent=indigo] .md-nav__extra_link:focus,[data-md-color-accent=indigo] .md-nav__extra_link:hover{color:#536dfe}[data-md-color-accent=blue] .md-nav__extra_link:focus,[data-md-color-accent=blue] .md-nav__extra_link:hover{color:#448aff}[data-md-color-accent=light-blue] .md-nav__extra_link:focus,[data-md-color-accent=light-blue] .md-nav__extra_link:hover{color:#0091ea}[data-md-color-accent=cyan] .md-nav__extra_link:focus,[data-md-color-accent=cyan] .md-nav__extra_link:hover{color:#00b8d4}[data-md-color-accent=teal] .md-nav__extra_link:focus,[data-md-color-accent=teal] .md-nav__extra_link:hover{color:#00bfa5}[data-md-color-accent=green] .md-nav__extra_link:focus,[data-md-color-accent=green] .md-nav__extra_link:hover{color:#00c853}[data-md-color-accent=light-green] .md-nav__extra_link:focus,[data-md-color-accent=light-green] .md-nav__extra_link:hover{color:#64dd17}[data-md-color-accent=lime] .md-nav__extra_link:focus,[data-md-color-accent=lime] .md-nav__extra_link:hover{color:#aeea00}[data-md-color-accent=yellow] .md-nav__extra_link:focus,[data-md-color-accent=yellow] .md-nav__extra_link:hover{color:#ffd600}[data-md-color-accent=amber] .md-nav__extra_link:focus,[data-md-color-accent=amber] .md-nav__extra_link:hover{color:#ffab00}[data-md-color-accent=orange] .md-nav__extra_link:focus,[data-md-color-accent=orange] .md-nav__extra_link:hover{color:#ff9100}[data-md-color-accent=deep-orange] .md-nav__extra_link:focus,[data-md-color-accent=deep-orange] .md-nav__extra_link:hover{color:#ff6e40}div.rendered_html table{font-size:.8rem !important}.md-nav span.caption{font-weight:700;pointer-events:none}.md-nav span.caption:hover,.md-nav span.caption:active{color:#000}.md-typeset img.align-right{clear:right;float:right;margin-left:1em}.md-typeset img.align-center{display:block;margin-left:auto;margin-right:auto}dl.citation dt span.brackets{margin-right:.3rem} \ No newline at end of file diff --git a/_static/stylesheets/application-palette.css b/_static/stylesheets/application-palette.css new file mode 100644 index 000000000..4623f093c --- /dev/null +++ b/_static/stylesheets/application-palette.css @@ -0,0 +1 @@ +@charset "utf-8";button[data-md-color-accent],button[data-md-color-primary]{width:6.5rem;margin-bottom:.2rem;padding:1.2rem .4rem .2rem;transition:background-color .25s,opacity .25s;border-radius:.1rem;color:#fff;font-size:.64rem;text-align:left;cursor:pointer}button[data-md-color-accent]:hover,button[data-md-color-primary]:hover{opacity:.75}button[data-md-color-primary=red]{background-color:#ef5350}[data-md-color-primary=red] .md-typeset a{color:#ef5350}[data-md-color-primary=red] .md-header,[data-md-color-primary=red] .md-hero{background-color:#ef5350}[data-md-color-primary=red] .md-nav__link--active,[data-md-color-primary=red] .md-nav__link:active{color:#ef5350}[data-md-color-primary=red] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=pink]{background-color:#e91e63}[data-md-color-primary=pink] .md-typeset a{color:#e91e63}[data-md-color-primary=pink] .md-header,[data-md-color-primary=pink] .md-hero{background-color:#e91e63}[data-md-color-primary=pink] .md-nav__link--active,[data-md-color-primary=pink] .md-nav__link:active{color:#e91e63}[data-md-color-primary=pink] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=purple]{background-color:#ab47bc}[data-md-color-primary=purple] .md-typeset a{color:#ab47bc}[data-md-color-primary=purple] .md-header,[data-md-color-primary=purple] .md-hero{background-color:#ab47bc}[data-md-color-primary=purple] .md-nav__link--active,[data-md-color-primary=purple] .md-nav__link:active{color:#ab47bc}[data-md-color-primary=purple] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=deep-purple]{background-color:#7e57c2}[data-md-color-primary=deep-purple] .md-typeset a{color:#7e57c2}[data-md-color-primary=deep-purple] .md-header,[data-md-color-primary=deep-purple] .md-hero{background-color:#7e57c2}[data-md-color-primary=deep-purple] .md-nav__link--active,[data-md-color-primary=deep-purple] .md-nav__link:active{color:#7e57c2}[data-md-color-primary=deep-purple] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=indigo]{background-color:#3f51b5}[data-md-color-primary=indigo] .md-typeset a{color:#3f51b5}[data-md-color-primary=indigo] .md-header,[data-md-color-primary=indigo] .md-hero{background-color:#3f51b5}[data-md-color-primary=indigo] .md-nav__link--active,[data-md-color-primary=indigo] .md-nav__link:active{color:#3f51b5}[data-md-color-primary=indigo] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=blue]{background-color:#2196f3}[data-md-color-primary=blue] .md-typeset a{color:#2196f3}[data-md-color-primary=blue] .md-header,[data-md-color-primary=blue] .md-hero{background-color:#2196f3}[data-md-color-primary=blue] .md-nav__link--active,[data-md-color-primary=blue] .md-nav__link:active{color:#2196f3}[data-md-color-primary=blue] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=light-blue]{background-color:#03a9f4}[data-md-color-primary=light-blue] .md-typeset a{color:#03a9f4}[data-md-color-primary=light-blue] .md-header,[data-md-color-primary=light-blue] .md-hero{background-color:#03a9f4}[data-md-color-primary=light-blue] .md-nav__link--active,[data-md-color-primary=light-blue] .md-nav__link:active{color:#03a9f4}[data-md-color-primary=light-blue] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=cyan]{background-color:#00bcd4}[data-md-color-primary=cyan] .md-typeset a{color:#00bcd4}[data-md-color-primary=cyan] .md-header,[data-md-color-primary=cyan] .md-hero{background-color:#00bcd4}[data-md-color-primary=cyan] .md-nav__link--active,[data-md-color-primary=cyan] .md-nav__link:active{color:#00bcd4}[data-md-color-primary=cyan] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=teal]{background-color:#009688}[data-md-color-primary=teal] .md-typeset a{color:#009688}[data-md-color-primary=teal] .md-header,[data-md-color-primary=teal] .md-hero{background-color:#009688}[data-md-color-primary=teal] .md-nav__link--active,[data-md-color-primary=teal] .md-nav__link:active{color:#009688}[data-md-color-primary=teal] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=green]{background-color:#4caf50}[data-md-color-primary=green] .md-typeset a{color:#4caf50}[data-md-color-primary=green] .md-header,[data-md-color-primary=green] .md-hero{background-color:#4caf50}[data-md-color-primary=green] .md-nav__link--active,[data-md-color-primary=green] .md-nav__link:active{color:#4caf50}[data-md-color-primary=green] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=light-green]{background-color:#7cb342}[data-md-color-primary=light-green] .md-typeset a{color:#7cb342}[data-md-color-primary=light-green] .md-header,[data-md-color-primary=light-green] .md-hero{background-color:#7cb342}[data-md-color-primary=light-green] .md-nav__link--active,[data-md-color-primary=light-green] .md-nav__link:active{color:#7cb342}[data-md-color-primary=light-green] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=lime]{background-color:#c0ca33}[data-md-color-primary=lime] .md-typeset a{color:#c0ca33}[data-md-color-primary=lime] .md-header,[data-md-color-primary=lime] .md-hero{background-color:#c0ca33}[data-md-color-primary=lime] .md-nav__link--active,[data-md-color-primary=lime] .md-nav__link:active{color:#c0ca33}[data-md-color-primary=lime] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=yellow]{background-color:#f9a825}[data-md-color-primary=yellow] .md-typeset a{color:#f9a825}[data-md-color-primary=yellow] .md-header,[data-md-color-primary=yellow] .md-hero{background-color:#f9a825}[data-md-color-primary=yellow] .md-nav__link--active,[data-md-color-primary=yellow] .md-nav__link:active{color:#f9a825}[data-md-color-primary=yellow] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=amber]{background-color:#ffa000}[data-md-color-primary=amber] .md-typeset a{color:#ffa000}[data-md-color-primary=amber] .md-header,[data-md-color-primary=amber] .md-hero{background-color:#ffa000}[data-md-color-primary=amber] .md-nav__link--active,[data-md-color-primary=amber] .md-nav__link:active{color:#ffa000}[data-md-color-primary=amber] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=orange]{background-color:#fb8c00}[data-md-color-primary=orange] .md-typeset a{color:#fb8c00}[data-md-color-primary=orange] .md-header,[data-md-color-primary=orange] .md-hero{background-color:#fb8c00}[data-md-color-primary=orange] .md-nav__link--active,[data-md-color-primary=orange] .md-nav__link:active{color:#fb8c00}[data-md-color-primary=orange] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=deep-orange]{background-color:#ff7043}[data-md-color-primary=deep-orange] .md-typeset a{color:#ff7043}[data-md-color-primary=deep-orange] .md-header,[data-md-color-primary=deep-orange] .md-hero{background-color:#ff7043}[data-md-color-primary=deep-orange] .md-nav__link--active,[data-md-color-primary=deep-orange] .md-nav__link:active{color:#ff7043}[data-md-color-primary=deep-orange] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=brown]{background-color:#795548}[data-md-color-primary=brown] .md-typeset a{color:#795548}[data-md-color-primary=brown] .md-header,[data-md-color-primary=brown] .md-hero{background-color:#795548}[data-md-color-primary=brown] .md-nav__link--active,[data-md-color-primary=brown] .md-nav__link:active{color:#795548}[data-md-color-primary=brown] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=grey]{background-color:#757575}[data-md-color-primary=grey] .md-typeset a{color:#757575}[data-md-color-primary=grey] .md-header,[data-md-color-primary=grey] .md-hero{background-color:#757575}[data-md-color-primary=grey] .md-nav__link--active,[data-md-color-primary=grey] .md-nav__link:active{color:#757575}[data-md-color-primary=grey] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=blue-grey]{background-color:#546e7a}[data-md-color-primary=blue-grey] .md-typeset a{color:#546e7a}[data-md-color-primary=blue-grey] .md-header,[data-md-color-primary=blue-grey] .md-hero{background-color:#546e7a}[data-md-color-primary=blue-grey] .md-nav__link--active,[data-md-color-primary=blue-grey] .md-nav__link:active{color:#546e7a}[data-md-color-primary=blue-grey] .md-nav__item--nested>.md-nav__link{color:inherit}button[data-md-color-primary=white]{box-shadow:inset 0 0 .05rem rgba(0,0,0,.54)}[data-md-color-primary=white] .md-header,[data-md-color-primary=white] .md-hero,button[data-md-color-primary=white]{background-color:#fff;color:rgba(0,0,0,.87)}[data-md-color-primary=white] .md-hero--expand{border-bottom:.05rem solid rgba(0,0,0,.07)}button[data-md-color-accent=red]{background-color:#ff1744}[data-md-color-accent=red] .md-typeset a:active,[data-md-color-accent=red] .md-typeset a:hover{color:#ff1744}[data-md-color-accent=red] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=red] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#ff1744}[data-md-color-accent=red] .md-nav__link:focus,[data-md-color-accent=red] .md-nav__link:hover,[data-md-color-accent=red] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=red] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=red] .md-typeset .md-clipboard:active:before,[data-md-color-accent=red] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=red] .md-typeset [id] .headerlink:focus,[data-md-color-accent=red] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=red] .md-typeset [id]:target .headerlink{color:#ff1744}[data-md-color-accent=red] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ff1744}[data-md-color-accent=red] .md-search-result__link:hover,[data-md-color-accent=red] .md-search-result__link[data-md-state=active]{background-color:rgba(255,23,68,.1)}[data-md-color-accent=red] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ff1744}[data-md-color-accent=red] .md-source-file:hover:before{background-color:#ff1744}button[data-md-color-accent=pink]{background-color:#f50057}[data-md-color-accent=pink] .md-typeset a:active,[data-md-color-accent=pink] .md-typeset a:hover{color:#f50057}[data-md-color-accent=pink] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=pink] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#f50057}[data-md-color-accent=pink] .md-nav__link:focus,[data-md-color-accent=pink] .md-nav__link:hover,[data-md-color-accent=pink] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=pink] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=pink] .md-typeset .md-clipboard:active:before,[data-md-color-accent=pink] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=pink] .md-typeset [id] .headerlink:focus,[data-md-color-accent=pink] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=pink] .md-typeset [id]:target .headerlink{color:#f50057}[data-md-color-accent=pink] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#f50057}[data-md-color-accent=pink] .md-search-result__link:hover,[data-md-color-accent=pink] .md-search-result__link[data-md-state=active]{background-color:rgba(245,0,87,.1)}[data-md-color-accent=pink] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#f50057}[data-md-color-accent=pink] .md-source-file:hover:before{background-color:#f50057}button[data-md-color-accent=purple]{background-color:#e040fb}[data-md-color-accent=purple] .md-typeset a:active,[data-md-color-accent=purple] .md-typeset a:hover{color:#e040fb}[data-md-color-accent=purple] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=purple] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#e040fb}[data-md-color-accent=purple] .md-nav__link:focus,[data-md-color-accent=purple] .md-nav__link:hover,[data-md-color-accent=purple] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=purple] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=purple] .md-typeset .md-clipboard:active:before,[data-md-color-accent=purple] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=purple] .md-typeset [id] .headerlink:focus,[data-md-color-accent=purple] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=purple] .md-typeset [id]:target .headerlink{color:#e040fb}[data-md-color-accent=purple] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#e040fb}[data-md-color-accent=purple] .md-search-result__link:hover,[data-md-color-accent=purple] .md-search-result__link[data-md-state=active]{background-color:rgba(224,64,251,.1)}[data-md-color-accent=purple] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#e040fb}[data-md-color-accent=purple] .md-source-file:hover:before{background-color:#e040fb}button[data-md-color-accent=deep-purple]{background-color:#7c4dff}[data-md-color-accent=deep-purple] .md-typeset a:active,[data-md-color-accent=deep-purple] .md-typeset a:hover{color:#7c4dff}[data-md-color-accent=deep-purple] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=deep-purple] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#7c4dff}[data-md-color-accent=deep-purple] .md-nav__link:focus,[data-md-color-accent=deep-purple] .md-nav__link:hover,[data-md-color-accent=deep-purple] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=deep-purple] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=deep-purple] .md-typeset .md-clipboard:active:before,[data-md-color-accent=deep-purple] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=deep-purple] .md-typeset [id] .headerlink:focus,[data-md-color-accent=deep-purple] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=deep-purple] .md-typeset [id]:target .headerlink{color:#7c4dff}[data-md-color-accent=deep-purple] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#7c4dff}[data-md-color-accent=deep-purple] .md-search-result__link:hover,[data-md-color-accent=deep-purple] .md-search-result__link[data-md-state=active]{background-color:rgba(124,77,255,.1)}[data-md-color-accent=deep-purple] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#7c4dff}[data-md-color-accent=deep-purple] .md-source-file:hover:before{background-color:#7c4dff}button[data-md-color-accent=indigo]{background-color:#536dfe}[data-md-color-accent=indigo] .md-typeset a:active,[data-md-color-accent=indigo] .md-typeset a:hover{color:#536dfe}[data-md-color-accent=indigo] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=indigo] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#536dfe}[data-md-color-accent=indigo] .md-nav__link:focus,[data-md-color-accent=indigo] .md-nav__link:hover,[data-md-color-accent=indigo] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=indigo] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=indigo] .md-typeset .md-clipboard:active:before,[data-md-color-accent=indigo] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=indigo] .md-typeset [id] .headerlink:focus,[data-md-color-accent=indigo] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=indigo] .md-typeset [id]:target .headerlink{color:#536dfe}[data-md-color-accent=indigo] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#536dfe}[data-md-color-accent=indigo] .md-search-result__link:hover,[data-md-color-accent=indigo] .md-search-result__link[data-md-state=active]{background-color:rgba(83,109,254,.1)}[data-md-color-accent=indigo] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#536dfe}[data-md-color-accent=indigo] .md-source-file:hover:before{background-color:#536dfe}button[data-md-color-accent=blue]{background-color:#448aff}[data-md-color-accent=blue] .md-typeset a:active,[data-md-color-accent=blue] .md-typeset a:hover{color:#448aff}[data-md-color-accent=blue] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=blue] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#448aff}[data-md-color-accent=blue] .md-nav__link:focus,[data-md-color-accent=blue] .md-nav__link:hover,[data-md-color-accent=blue] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=blue] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=blue] .md-typeset .md-clipboard:active:before,[data-md-color-accent=blue] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=blue] .md-typeset [id] .headerlink:focus,[data-md-color-accent=blue] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=blue] .md-typeset [id]:target .headerlink{color:#448aff}[data-md-color-accent=blue] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#448aff}[data-md-color-accent=blue] .md-search-result__link:hover,[data-md-color-accent=blue] .md-search-result__link[data-md-state=active]{background-color:rgba(68,138,255,.1)}[data-md-color-accent=blue] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#448aff}[data-md-color-accent=blue] .md-source-file:hover:before{background-color:#448aff}button[data-md-color-accent=light-blue]{background-color:#0091ea}[data-md-color-accent=light-blue] .md-typeset a:active,[data-md-color-accent=light-blue] .md-typeset a:hover{color:#0091ea}[data-md-color-accent=light-blue] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=light-blue] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#0091ea}[data-md-color-accent=light-blue] .md-nav__link:focus,[data-md-color-accent=light-blue] .md-nav__link:hover,[data-md-color-accent=light-blue] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=light-blue] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=light-blue] .md-typeset .md-clipboard:active:before,[data-md-color-accent=light-blue] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=light-blue] .md-typeset [id] .headerlink:focus,[data-md-color-accent=light-blue] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=light-blue] .md-typeset [id]:target .headerlink{color:#0091ea}[data-md-color-accent=light-blue] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#0091ea}[data-md-color-accent=light-blue] .md-search-result__link:hover,[data-md-color-accent=light-blue] .md-search-result__link[data-md-state=active]{background-color:rgba(0,145,234,.1)}[data-md-color-accent=light-blue] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#0091ea}[data-md-color-accent=light-blue] .md-source-file:hover:before{background-color:#0091ea}button[data-md-color-accent=cyan]{background-color:#00b8d4}[data-md-color-accent=cyan] .md-typeset a:active,[data-md-color-accent=cyan] .md-typeset a:hover{color:#00b8d4}[data-md-color-accent=cyan] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=cyan] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#00b8d4}[data-md-color-accent=cyan] .md-nav__link:focus,[data-md-color-accent=cyan] .md-nav__link:hover,[data-md-color-accent=cyan] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=cyan] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=cyan] .md-typeset .md-clipboard:active:before,[data-md-color-accent=cyan] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=cyan] .md-typeset [id] .headerlink:focus,[data-md-color-accent=cyan] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=cyan] .md-typeset [id]:target .headerlink{color:#00b8d4}[data-md-color-accent=cyan] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#00b8d4}[data-md-color-accent=cyan] .md-search-result__link:hover,[data-md-color-accent=cyan] .md-search-result__link[data-md-state=active]{background-color:rgba(0,184,212,.1)}[data-md-color-accent=cyan] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#00b8d4}[data-md-color-accent=cyan] .md-source-file:hover:before{background-color:#00b8d4}button[data-md-color-accent=teal]{background-color:#00bfa5}[data-md-color-accent=teal] .md-typeset a:active,[data-md-color-accent=teal] .md-typeset a:hover{color:#00bfa5}[data-md-color-accent=teal] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=teal] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#00bfa5}[data-md-color-accent=teal] .md-nav__link:focus,[data-md-color-accent=teal] .md-nav__link:hover,[data-md-color-accent=teal] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=teal] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=teal] .md-typeset .md-clipboard:active:before,[data-md-color-accent=teal] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=teal] .md-typeset [id] .headerlink:focus,[data-md-color-accent=teal] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=teal] .md-typeset [id]:target .headerlink{color:#00bfa5}[data-md-color-accent=teal] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#00bfa5}[data-md-color-accent=teal] .md-search-result__link:hover,[data-md-color-accent=teal] .md-search-result__link[data-md-state=active]{background-color:rgba(0,191,165,.1)}[data-md-color-accent=teal] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#00bfa5}[data-md-color-accent=teal] .md-source-file:hover:before{background-color:#00bfa5}button[data-md-color-accent=green]{background-color:#00c853}[data-md-color-accent=green] .md-typeset a:active,[data-md-color-accent=green] .md-typeset a:hover{color:#00c853}[data-md-color-accent=green] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=green] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#00c853}[data-md-color-accent=green] .md-nav__link:focus,[data-md-color-accent=green] .md-nav__link:hover,[data-md-color-accent=green] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=green] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=green] .md-typeset .md-clipboard:active:before,[data-md-color-accent=green] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=green] .md-typeset [id] .headerlink:focus,[data-md-color-accent=green] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=green] .md-typeset [id]:target .headerlink{color:#00c853}[data-md-color-accent=green] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#00c853}[data-md-color-accent=green] .md-search-result__link:hover,[data-md-color-accent=green] .md-search-result__link[data-md-state=active]{background-color:rgba(0,200,83,.1)}[data-md-color-accent=green] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#00c853}[data-md-color-accent=green] .md-source-file:hover:before{background-color:#00c853}button[data-md-color-accent=light-green]{background-color:#64dd17}[data-md-color-accent=light-green] .md-typeset a:active,[data-md-color-accent=light-green] .md-typeset a:hover{color:#64dd17}[data-md-color-accent=light-green] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=light-green] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#64dd17}[data-md-color-accent=light-green] .md-nav__link:focus,[data-md-color-accent=light-green] .md-nav__link:hover,[data-md-color-accent=light-green] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=light-green] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=light-green] .md-typeset .md-clipboard:active:before,[data-md-color-accent=light-green] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=light-green] .md-typeset [id] .headerlink:focus,[data-md-color-accent=light-green] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=light-green] .md-typeset [id]:target .headerlink{color:#64dd17}[data-md-color-accent=light-green] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#64dd17}[data-md-color-accent=light-green] .md-search-result__link:hover,[data-md-color-accent=light-green] .md-search-result__link[data-md-state=active]{background-color:rgba(100,221,23,.1)}[data-md-color-accent=light-green] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#64dd17}[data-md-color-accent=light-green] .md-source-file:hover:before{background-color:#64dd17}button[data-md-color-accent=lime]{background-color:#aeea00}[data-md-color-accent=lime] .md-typeset a:active,[data-md-color-accent=lime] .md-typeset a:hover{color:#aeea00}[data-md-color-accent=lime] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=lime] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#aeea00}[data-md-color-accent=lime] .md-nav__link:focus,[data-md-color-accent=lime] .md-nav__link:hover,[data-md-color-accent=lime] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=lime] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=lime] .md-typeset .md-clipboard:active:before,[data-md-color-accent=lime] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=lime] .md-typeset [id] .headerlink:focus,[data-md-color-accent=lime] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=lime] .md-typeset [id]:target .headerlink{color:#aeea00}[data-md-color-accent=lime] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#aeea00}[data-md-color-accent=lime] .md-search-result__link:hover,[data-md-color-accent=lime] .md-search-result__link[data-md-state=active]{background-color:rgba(174,234,0,.1)}[data-md-color-accent=lime] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#aeea00}[data-md-color-accent=lime] .md-source-file:hover:before{background-color:#aeea00}button[data-md-color-accent=yellow]{background-color:#ffd600}[data-md-color-accent=yellow] .md-typeset a:active,[data-md-color-accent=yellow] .md-typeset a:hover{color:#ffd600}[data-md-color-accent=yellow] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=yellow] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#ffd600}[data-md-color-accent=yellow] .md-nav__link:focus,[data-md-color-accent=yellow] .md-nav__link:hover,[data-md-color-accent=yellow] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=yellow] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=yellow] .md-typeset .md-clipboard:active:before,[data-md-color-accent=yellow] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=yellow] .md-typeset [id] .headerlink:focus,[data-md-color-accent=yellow] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=yellow] .md-typeset [id]:target .headerlink{color:#ffd600}[data-md-color-accent=yellow] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ffd600}[data-md-color-accent=yellow] .md-search-result__link:hover,[data-md-color-accent=yellow] .md-search-result__link[data-md-state=active]{background-color:rgba(255,214,0,.1)}[data-md-color-accent=yellow] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ffd600}[data-md-color-accent=yellow] .md-source-file:hover:before{background-color:#ffd600}button[data-md-color-accent=amber]{background-color:#ffab00}[data-md-color-accent=amber] .md-typeset a:active,[data-md-color-accent=amber] .md-typeset a:hover{color:#ffab00}[data-md-color-accent=amber] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=amber] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#ffab00}[data-md-color-accent=amber] .md-nav__link:focus,[data-md-color-accent=amber] .md-nav__link:hover,[data-md-color-accent=amber] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=amber] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=amber] .md-typeset .md-clipboard:active:before,[data-md-color-accent=amber] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=amber] .md-typeset [id] .headerlink:focus,[data-md-color-accent=amber] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=amber] .md-typeset [id]:target .headerlink{color:#ffab00}[data-md-color-accent=amber] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ffab00}[data-md-color-accent=amber] .md-search-result__link:hover,[data-md-color-accent=amber] .md-search-result__link[data-md-state=active]{background-color:rgba(255,171,0,.1)}[data-md-color-accent=amber] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ffab00}[data-md-color-accent=amber] .md-source-file:hover:before{background-color:#ffab00}button[data-md-color-accent=orange]{background-color:#ff9100}[data-md-color-accent=orange] .md-typeset a:active,[data-md-color-accent=orange] .md-typeset a:hover{color:#ff9100}[data-md-color-accent=orange] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=orange] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#ff9100}[data-md-color-accent=orange] .md-nav__link:focus,[data-md-color-accent=orange] .md-nav__link:hover,[data-md-color-accent=orange] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=orange] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=orange] .md-typeset .md-clipboard:active:before,[data-md-color-accent=orange] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=orange] .md-typeset [id] .headerlink:focus,[data-md-color-accent=orange] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=orange] .md-typeset [id]:target .headerlink{color:#ff9100}[data-md-color-accent=orange] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ff9100}[data-md-color-accent=orange] .md-search-result__link:hover,[data-md-color-accent=orange] .md-search-result__link[data-md-state=active]{background-color:rgba(255,145,0,.1)}[data-md-color-accent=orange] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ff9100}[data-md-color-accent=orange] .md-source-file:hover:before{background-color:#ff9100}button[data-md-color-accent=deep-orange]{background-color:#ff6e40}[data-md-color-accent=deep-orange] .md-typeset a:active,[data-md-color-accent=deep-orange] .md-typeset a:hover{color:#ff6e40}[data-md-color-accent=deep-orange] .md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,[data-md-color-accent=deep-orange] .md-typeset pre code::-webkit-scrollbar-thumb:hover{background-color:#ff6e40}[data-md-color-accent=deep-orange] .md-nav__link:focus,[data-md-color-accent=deep-orange] .md-nav__link:hover,[data-md-color-accent=deep-orange] .md-typeset .footnote li:hover .footnote-backref:hover,[data-md-color-accent=deep-orange] .md-typeset .footnote li:target .footnote-backref,[data-md-color-accent=deep-orange] .md-typeset .md-clipboard:active:before,[data-md-color-accent=deep-orange] .md-typeset .md-clipboard:hover:before,[data-md-color-accent=deep-orange] .md-typeset [id] .headerlink:focus,[data-md-color-accent=deep-orange] .md-typeset [id]:hover .headerlink:hover,[data-md-color-accent=deep-orange] .md-typeset [id]:target .headerlink{color:#ff6e40}[data-md-color-accent=deep-orange] .md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ff6e40}[data-md-color-accent=deep-orange] .md-search-result__link:hover,[data-md-color-accent=deep-orange] .md-search-result__link[data-md-state=active]{background-color:rgba(255,110,64,.1)}[data-md-color-accent=deep-orange] .md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#ff6e40}[data-md-color-accent=deep-orange] .md-source-file:hover:before{background-color:#ff6e40}@media only screen and (max-width:59.9375em){[data-md-color-primary=red] .md-nav__source{background-color:rgba(190,66,64,.9675)}[data-md-color-primary=pink] .md-nav__source{background-color:rgba(185,24,79,.9675)}[data-md-color-primary=purple] .md-nav__source{background-color:rgba(136,57,150,.9675)}[data-md-color-primary=deep-purple] .md-nav__source{background-color:rgba(100,69,154,.9675)}[data-md-color-primary=indigo] .md-nav__source{background-color:rgba(50,64,144,.9675)}[data-md-color-primary=blue] .md-nav__source{background-color:rgba(26,119,193,.9675)}[data-md-color-primary=light-blue] .md-nav__source{background-color:rgba(2,134,194,.9675)}[data-md-color-primary=cyan] .md-nav__source{background-color:rgba(0,150,169,.9675)}[data-md-color-primary=teal] .md-nav__source{background-color:rgba(0,119,108,.9675)}[data-md-color-primary=green] .md-nav__source{background-color:rgba(60,139,64,.9675)}[data-md-color-primary=light-green] .md-nav__source{background-color:rgba(99,142,53,.9675)}[data-md-color-primary=lime] .md-nav__source{background-color:rgba(153,161,41,.9675)}[data-md-color-primary=yellow] .md-nav__source{background-color:rgba(198,134,29,.9675)}[data-md-color-primary=amber] .md-nav__source{background-color:rgba(203,127,0,.9675)}[data-md-color-primary=orange] .md-nav__source{background-color:rgba(200,111,0,.9675)}[data-md-color-primary=deep-orange] .md-nav__source{background-color:rgba(203,89,53,.9675)}[data-md-color-primary=brown] .md-nav__source{background-color:rgba(96,68,57,.9675)}[data-md-color-primary=grey] .md-nav__source{background-color:rgba(93,93,93,.9675)}[data-md-color-primary=blue-grey] .md-nav__source{background-color:rgba(67,88,97,.9675)}[data-md-color-primary=white] .md-nav__source{background-color:rgba(0,0,0,.07);color:rgba(0,0,0,.87)}}@media only screen and (max-width:76.1875em){html [data-md-color-primary=red] .md-nav--primary .md-nav__title--site{background-color:#ef5350}html [data-md-color-primary=pink] .md-nav--primary .md-nav__title--site{background-color:#e91e63}html [data-md-color-primary=purple] .md-nav--primary .md-nav__title--site{background-color:#ab47bc}html [data-md-color-primary=deep-purple] .md-nav--primary .md-nav__title--site{background-color:#7e57c2}html [data-md-color-primary=indigo] .md-nav--primary .md-nav__title--site{background-color:#3f51b5}html [data-md-color-primary=blue] .md-nav--primary .md-nav__title--site{background-color:#2196f3}html [data-md-color-primary=light-blue] .md-nav--primary .md-nav__title--site{background-color:#03a9f4}html [data-md-color-primary=cyan] .md-nav--primary .md-nav__title--site{background-color:#00bcd4}html [data-md-color-primary=teal] .md-nav--primary .md-nav__title--site{background-color:#009688}html [data-md-color-primary=green] .md-nav--primary .md-nav__title--site{background-color:#4caf50}html [data-md-color-primary=light-green] .md-nav--primary .md-nav__title--site{background-color:#7cb342}html [data-md-color-primary=lime] .md-nav--primary .md-nav__title--site{background-color:#c0ca33}html [data-md-color-primary=yellow] .md-nav--primary .md-nav__title--site{background-color:#f9a825}html [data-md-color-primary=amber] .md-nav--primary .md-nav__title--site{background-color:#ffa000}html [data-md-color-primary=orange] .md-nav--primary .md-nav__title--site{background-color:#fb8c00}html [data-md-color-primary=deep-orange] .md-nav--primary .md-nav__title--site{background-color:#ff7043}html [data-md-color-primary=brown] .md-nav--primary .md-nav__title--site{background-color:#795548}html [data-md-color-primary=grey] .md-nav--primary .md-nav__title--site{background-color:#757575}html [data-md-color-primary=blue-grey] .md-nav--primary .md-nav__title--site{background-color:#546e7a}html [data-md-color-primary=white] .md-nav--primary .md-nav__title--site{background-color:#fff;color:rgba(0,0,0,.87)}[data-md-color-primary=white] .md-hero{border-bottom:.05rem solid rgba(0,0,0,.07)}}@media only screen and (min-width:76.25em){[data-md-color-primary=red] .md-tabs{background-color:#ef5350}[data-md-color-primary=pink] .md-tabs{background-color:#e91e63}[data-md-color-primary=purple] .md-tabs{background-color:#ab47bc}[data-md-color-primary=deep-purple] .md-tabs{background-color:#7e57c2}[data-md-color-primary=indigo] .md-tabs{background-color:#3f51b5}[data-md-color-primary=blue] .md-tabs{background-color:#2196f3}[data-md-color-primary=light-blue] .md-tabs{background-color:#03a9f4}[data-md-color-primary=cyan] .md-tabs{background-color:#00bcd4}[data-md-color-primary=teal] .md-tabs{background-color:#009688}[data-md-color-primary=green] .md-tabs{background-color:#4caf50}[data-md-color-primary=light-green] .md-tabs{background-color:#7cb342}[data-md-color-primary=lime] .md-tabs{background-color:#c0ca33}[data-md-color-primary=yellow] .md-tabs{background-color:#f9a825}[data-md-color-primary=amber] .md-tabs{background-color:#ffa000}[data-md-color-primary=orange] .md-tabs{background-color:#fb8c00}[data-md-color-primary=deep-orange] .md-tabs{background-color:#ff7043}[data-md-color-primary=brown] .md-tabs{background-color:#795548}[data-md-color-primary=grey] .md-tabs{background-color:#757575}[data-md-color-primary=blue-grey] .md-tabs{background-color:#546e7a}[data-md-color-primary=white] .md-tabs{border-bottom:.05rem solid rgba(0,0,0,.07);background-color:#fff;color:rgba(0,0,0,.87)}}@media only screen and (min-width:60em){[data-md-color-primary=white] .md-search__input{background-color:rgba(0,0,0,.07)}[data-md-color-primary=white] .md-search__input::-webkit-input-placeholder{color:rgba(0,0,0,.54)}[data-md-color-primary=white] .md-search__input:-ms-input-placeholder{color:rgba(0,0,0,.54)}[data-md-color-primary=white] .md-search__input::-ms-input-placeholder{color:rgba(0,0,0,.54)}[data-md-color-primary=white] .md-search__input::placeholder{color:rgba(0,0,0,.54)}} \ No newline at end of file diff --git a/_static/stylesheets/application.css b/_static/stylesheets/application.css new file mode 100644 index 000000000..b5c5df3bd --- /dev/null +++ b/_static/stylesheets/application.css @@ -0,0 +1 @@ +@charset "UTF-8";html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}html{-webkit-text-size-adjust:none;-moz-text-size-adjust:none;-ms-text-size-adjust:none;text-size-adjust:none}body{margin:0}hr{overflow:visible;box-sizing:content-box}a{-webkit-text-decoration-skip:objects}a,button,input,label{-webkit-tap-highlight-color:transparent}a{color:inherit;text-decoration:none}small,sub,sup{font-size:80%}sub,sup{position:relative;line-height:0;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}table{border-collapse:separate;border-spacing:0}td,th{font-weight:400;vertical-align:top}button{margin:0;padding:0;border:0;outline-style:none;background:transparent;font-size:inherit}input{border:0;outline:0}.md-clipboard:before,.md-icon,.md-nav__button,.md-nav__link:after,.md-nav__title:before,.md-search-result__article--document:before,.md-source-file:before,.md-typeset .admonition>.admonition-title:before,.md-typeset .admonition>summary:before,.md-typeset .critic.comment:before,.md-typeset .footnote-backref,.md-typeset .task-list-control .task-list-indicator:before,.md-typeset details>.admonition-title:before,.md-typeset details>summary:before,.md-typeset summary:after{font-family:Material Icons;font-style:normal;font-variant:normal;font-weight:400;line-height:1;text-transform:none;white-space:nowrap;speak:none;word-wrap:normal;direction:ltr}.md-content__icon,.md-footer-nav__button,.md-header-nav__button,.md-nav__button,.md-nav__title:before,.md-search-result__article--document:before{display:inline-block;margin:.2rem;padding:.4rem;font-size:1.2rem;cursor:pointer}.md-icon--arrow-back:before{content:""}.md-icon--arrow-forward:before{content:""}.md-icon--menu:before{content:""}.md-icon--search:before{content:""}[dir=rtl] .md-icon--arrow-back:before{content:""}[dir=rtl] .md-icon--arrow-forward:before{content:""}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}body,input{color:rgba(0,0,0,.87);-webkit-font-feature-settings:"kern","liga";font-feature-settings:"kern","liga";font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{color:rgba(0,0,0,.87);-webkit-font-feature-settings:"kern";font-feature-settings:"kern";font-family:"Roboto Mono","Courier New",Courier,monospace}.md-typeset{font-size:.8rem;line-height:1.6;-webkit-print-color-adjust:exact}.md-typeset blockquote,.md-typeset ol,.md-typeset p,.md-typeset ul{margin:1em 0}.md-typeset h1{margin:0 0 2rem;color:rgba(0,0,0,.54);font-size:1.5625rem;line-height:1.3}.md-typeset h1,.md-typeset h2{font-weight:300;letter-spacing:-.01em}.md-typeset h2{margin:2rem 0 .8rem;font-size:1.25rem;line-height:1.4}.md-typeset h3{margin:1.6rem 0 .8rem;font-size:1rem;font-weight:400;letter-spacing:-.01em;line-height:1.5}.md-typeset h2+h3{margin-top:.8rem}.md-typeset h4{font-size:.8rem}.md-typeset h4,.md-typeset h5,.md-typeset h6{margin:.8rem 0;font-weight:700;letter-spacing:-.01em}.md-typeset h5,.md-typeset h6{color:rgba(0,0,0,.54);font-size:.64rem}.md-typeset h5{text-transform:uppercase}.md-typeset hr{margin:1.5em 0;border-bottom:.05rem dotted rgba(0,0,0,.26)}.md-typeset a{color:#3f51b5;word-break:break-word}.md-typeset a,.md-typeset a:before{transition:color .125s}.md-typeset a:active,.md-typeset a:hover{color:#536dfe}.md-typeset code,.md-typeset pre{background-color:hsla(0,0%,92.5%,.5);color:#37474f;font-size:85%;direction:ltr}.md-typeset code{margin:0 .29412em;padding:.07353em 0;border-radius:.1rem;word-break:break-word;-webkit-box-decoration-break:clone;box-decoration-break:clone}.md-typeset h1 code,.md-typeset h2 code,.md-typeset h3 code,.md-typeset h4 code,.md-typeset h5 code,.md-typeset h6 code{margin:0;background-color:transparent;box-shadow:none}.md-typeset a>code{margin:inherit;padding:inherit;border-radius:initial;background-color:inherit;color:inherit;box-shadow:none}.md-typeset pre{position:relative;margin:1em 0;border-radius:.1rem;line-height:1.4;-webkit-overflow-scrolling:touch}.md-typeset pre>code{margin:0;padding:.525rem .6rem;background-color:transparent;font-size:inherit;box-shadow:none;-webkit-box-decoration-break:slice;box-decoration-break:slice;overflow:auto}.md-typeset pre>code::-webkit-scrollbar{width:.2rem;height:.2rem}.md-typeset pre>code::-webkit-scrollbar-thumb{background-color:rgba(0,0,0,.26)}.md-typeset pre>code::-webkit-scrollbar-thumb:hover{background-color:#536dfe}.md-typeset kbd{padding:0 .29412em;border-radius:.15rem;border:.05rem solid #c9c9c9;border-bottom-color:#bcbcbc;background-color:#fcfcfc;color:#555;font-size:85%;box-shadow:0 .05rem 0 #b0b0b0;word-break:break-word}.md-typeset mark{margin:0 .25em;padding:.0625em 0;border-radius:.1rem;background-color:rgba(255,235,59,.5);box-shadow:.25em 0 0 rgba(255,235,59,.5),-.25em 0 0 rgba(255,235,59,.5);word-break:break-word;-webkit-box-decoration-break:clone;box-decoration-break:clone}.md-typeset abbr{border-bottom:.05rem dotted rgba(0,0,0,.54);text-decoration:none;cursor:help}.md-typeset small{opacity:.75}.md-typeset sub,.md-typeset sup{margin-left:.07812em}[dir=rtl] .md-typeset sub,[dir=rtl] .md-typeset sup{margin-right:.07812em;margin-left:0}.md-typeset blockquote{padding-left:.6rem;border-left:.2rem solid rgba(0,0,0,.26);color:rgba(0,0,0,.54)}[dir=rtl] .md-typeset blockquote{padding-right:.6rem;padding-left:0;border-right:.2rem solid rgba(0,0,0,.26);border-left:initial}.md-typeset ul{list-style-type:disc}.md-typeset ol,.md-typeset ul{margin-left:.625em;padding:0}[dir=rtl] .md-typeset ol,[dir=rtl] .md-typeset ul{margin-right:.625em;margin-left:0}.md-typeset ol ol,.md-typeset ul ol{list-style-type:lower-alpha}.md-typeset ol ol ol,.md-typeset ul ol ol{list-style-type:lower-roman}.md-typeset ol li,.md-typeset ul li{margin-bottom:.5em;margin-left:1.25em}[dir=rtl] .md-typeset ol li,[dir=rtl] .md-typeset ul li{margin-right:1.25em;margin-left:0}.md-typeset ol li blockquote,.md-typeset ol li p,.md-typeset ul li blockquote,.md-typeset ul li p{margin:.5em 0}.md-typeset ol li:last-child,.md-typeset ul li:last-child{margin-bottom:0}.md-typeset ol li ol,.md-typeset ol li ul,.md-typeset ul li ol,.md-typeset ul li ul{margin:.5em 0 .5em .625em}[dir=rtl] .md-typeset ol li ol,[dir=rtl] .md-typeset ol li ul,[dir=rtl] .md-typeset ul li ol,[dir=rtl] .md-typeset ul li ul{margin-right:.625em;margin-left:0}.md-typeset dd{margin:1em 0 1em 1.875em}[dir=rtl] .md-typeset dd{margin-right:1.875em;margin-left:0}.md-typeset iframe,.md-typeset img,.md-typeset svg{max-width:100%}.md-typeset table:not([class]){box-shadow:0 2px 2px 0 rgba(0,0,0,.14),0 1px 5px 0 rgba(0,0,0,.12),0 3px 1px -2px rgba(0,0,0,.2);display:inline-block;max-width:100%;border-radius:.1rem;font-size:.64rem;overflow:auto;-webkit-overflow-scrolling:touch}.md-typeset table:not([class])+*{margin-top:1.5em}.md-typeset table:not([class]) td:not([align]),.md-typeset table:not([class]) th:not([align]){text-align:left}[dir=rtl] .md-typeset table:not([class]) td:not([align]),[dir=rtl] .md-typeset table:not([class]) th:not([align]){text-align:right}.md-typeset table:not([class]) th{min-width:5rem;padding:.6rem .8rem;background-color:rgba(0,0,0,.54);color:#fff;vertical-align:top}.md-typeset table:not([class]) td{padding:.6rem .8rem;border-top:.05rem solid rgba(0,0,0,.07);vertical-align:top}.md-typeset table:not([class]) tr{transition:background-color .125s}.md-typeset table:not([class]) tr:hover{background-color:rgba(0,0,0,.035);box-shadow:inset 0 .05rem 0 #fff}.md-typeset table:not([class]) tr:first-child td{border-top:0}.md-typeset table:not([class]) a{word-break:normal}.md-typeset__scrollwrap{margin:1em -.8rem;overflow-x:auto;-webkit-overflow-scrolling:touch}.md-typeset .md-typeset__table{display:inline-block;margin-bottom:.5em;padding:0 .8rem}.md-typeset .md-typeset__table table{display:table;width:100%;margin:0;overflow:hidden}html{font-size:125%;overflow-x:hidden}body,html{height:100%}body{position:relative;font-size:.5rem}hr{display:block;height:.05rem;padding:0;border:0}.md-svg{display:none}.md-grid{max-width:73rem;margin-right:auto;margin-left:auto}.md-container,.md-main{overflow:auto}.md-container{display:table;width:100%;height:100%;padding-top:2.4rem;table-layout:fixed}.md-main{display:table-row;height:100%}.md-main__inner{height:100%;padding-top:1.5rem;padding-bottom:.05rem}.md-toggle{display:none}.md-overlay{position:fixed;top:0;width:0;height:0;transition:width 0 .25s,height 0 .25s,opacity .25s;background-color:rgba(0,0,0,.54);opacity:0;z-index:3}.md-flex{display:table}.md-flex__cell{display:table-cell;position:relative;vertical-align:top}.md-flex__cell--shrink{width:0}.md-flex__cell--stretch{display:table;width:100%;table-layout:fixed}.md-flex__ellipsis{display:table-cell;text-overflow:ellipsis;white-space:nowrap;overflow:hidden}.md-skip{position:fixed;width:.05rem;height:.05rem;margin:.5rem;padding:.3rem .5rem;-webkit-transform:translateY(.4rem);transform:translateY(.4rem);border-radius:.1rem;background-color:rgba(0,0,0,.87);color:#fff;font-size:.64rem;opacity:0;overflow:hidden}.md-skip:focus{width:auto;height:auto;clip:auto;-webkit-transform:translateX(0);transform:translateX(0);transition:opacity .175s 75ms,-webkit-transform .25s cubic-bezier(.4,0,.2,1);transition:transform .25s cubic-bezier(.4,0,.2,1),opacity .175s 75ms;transition:transform .25s cubic-bezier(.4,0,.2,1),opacity .175s 75ms,-webkit-transform .25s cubic-bezier(.4,0,.2,1);opacity:1;z-index:10}@page{margin:25mm}.md-clipboard{position:absolute;top:.3rem;right:.3rem;width:1.4rem;height:1.4rem;border-radius:.1rem;font-size:.8rem;cursor:pointer;z-index:1;-webkit-backface-visibility:hidden;backface-visibility:hidden}.md-clipboard:before{transition:color .25s,opacity .25s;color:rgba(0,0,0,.07);content:"\E14D"}.codehilite:hover .md-clipboard:before,.md-typeset .highlight:hover .md-clipboard:before,pre:hover .md-clipboard:before{color:rgba(0,0,0,.54)}.md-clipboard:focus:before,.md-clipboard:hover:before{color:#536dfe}.md-clipboard__message{display:block;position:absolute;top:0;right:1.7rem;padding:.3rem .5rem;-webkit-transform:translateX(.4rem);transform:translateX(.4rem);transition:opacity .175s,-webkit-transform .25s cubic-bezier(.9,.1,.9,0);transition:transform .25s cubic-bezier(.9,.1,.9,0),opacity .175s;transition:transform .25s cubic-bezier(.9,.1,.9,0),opacity .175s,-webkit-transform .25s cubic-bezier(.9,.1,.9,0);border-radius:.1rem;background-color:rgba(0,0,0,.54);color:#fff;font-size:.64rem;white-space:nowrap;opacity:0;pointer-events:none}.md-clipboard__message--active{-webkit-transform:translateX(0);transform:translateX(0);transition:opacity .175s 75ms,-webkit-transform .25s cubic-bezier(.4,0,.2,1);transition:transform .25s cubic-bezier(.4,0,.2,1),opacity .175s 75ms;transition:transform .25s cubic-bezier(.4,0,.2,1),opacity .175s 75ms,-webkit-transform .25s cubic-bezier(.4,0,.2,1);opacity:1;pointer-events:auto}.md-clipboard__message:before{content:attr(aria-label)}.md-clipboard__message:after{display:block;position:absolute;top:50%;right:-.2rem;width:0;margin-top:-.2rem;border-color:transparent rgba(0,0,0,.54);border-style:solid;border-width:.2rem 0 .2rem .2rem;content:""}.md-content__inner{margin:0 .8rem 1.2rem;padding-top:.6rem}.md-content__inner:before{display:block;height:.4rem;content:""}.md-content__inner>:last-child{margin-bottom:0}.md-content__icon{position:relative;margin:.4rem 0;padding:0;float:right}.md-typeset .md-content__icon{color:rgba(0,0,0,.26)}.md-header{position:fixed;top:0;right:0;left:0;height:2.4rem;transition:background-color .25s,color .25s;background-color:#3f51b5;color:#fff;box-shadow:none;z-index:2;-webkit-backface-visibility:hidden;backface-visibility:hidden}.no-js .md-header{transition:none;box-shadow:none}.md-header[data-md-state=shadow]{transition:background-color .25s,color .25s,box-shadow .25s;box-shadow:0 0 .2rem rgba(0,0,0,.1),0 .2rem .4rem rgba(0,0,0,.2)}.md-header-nav{padding:0 .2rem}.md-header-nav__button{position:relative;transition:opacity .25s;z-index:1}.md-header-nav__button:hover{opacity:.7}.md-header-nav__button.md-logo *{display:block}.no-js .md-header-nav__button.md-icon--search{display:none}.md-header-nav__topic{display:block;position:absolute;transition:opacity .15s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .15s;transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .15s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);text-overflow:ellipsis;white-space:nowrap;overflow:hidden}.md-header-nav__topic+.md-header-nav__topic{-webkit-transform:translateX(1.25rem);transform:translateX(1.25rem);transition:opacity .15s,-webkit-transform .4s cubic-bezier(1,.7,.1,.1);transition:transform .4s cubic-bezier(1,.7,.1,.1),opacity .15s;transition:transform .4s cubic-bezier(1,.7,.1,.1),opacity .15s,-webkit-transform .4s cubic-bezier(1,.7,.1,.1);opacity:0;z-index:-1;pointer-events:none}[dir=rtl] .md-header-nav__topic+.md-header-nav__topic{-webkit-transform:translateX(-1.25rem);transform:translateX(-1.25rem)}.no-js .md-header-nav__topic{position:static}.no-js .md-header-nav__topic+.md-header-nav__topic{display:none}.md-header-nav__title{padding:0 1rem;font-size:.9rem;line-height:2.4rem}.md-header-nav__title[data-md-state=active] .md-header-nav__topic{-webkit-transform:translateX(-1.25rem);transform:translateX(-1.25rem);transition:opacity .15s,-webkit-transform .4s cubic-bezier(1,.7,.1,.1);transition:transform .4s cubic-bezier(1,.7,.1,.1),opacity .15s;transition:transform .4s cubic-bezier(1,.7,.1,.1),opacity .15s,-webkit-transform .4s cubic-bezier(1,.7,.1,.1);opacity:0;z-index:-1;pointer-events:none}[dir=rtl] .md-header-nav__title[data-md-state=active] .md-header-nav__topic{-webkit-transform:translateX(1.25rem);transform:translateX(1.25rem)}.md-header-nav__title[data-md-state=active] .md-header-nav__topic+.md-header-nav__topic{-webkit-transform:translateX(0);transform:translateX(0);transition:opacity .15s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .15s;transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .15s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);opacity:1;z-index:0;pointer-events:auto}.md-header-nav__source{display:none}.md-hero{transition:background .25s;background-color:#3f51b5;color:#fff;font-size:1rem;overflow:hidden}.md-hero__inner{margin-top:1rem;padding:.8rem .8rem .4rem;transition:opacity .25s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .25s;transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .25s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);transition-delay:.1s}[data-md-state=hidden] .md-hero__inner{pointer-events:none;-webkit-transform:translateY(.625rem);transform:translateY(.625rem);transition:opacity .1s 0,-webkit-transform 0 .4s;transition:transform 0 .4s,opacity .1s 0;transition:transform 0 .4s,opacity .1s 0,-webkit-transform 0 .4s;opacity:0}.md-hero--expand .md-hero__inner{margin-bottom:1.2rem}.md-footer-nav{background-color:rgba(0,0,0,.87);color:#fff}.md-footer-nav__inner{padding:.2rem;overflow:auto}.md-footer-nav__link{padding-top:1.4rem;padding-bottom:.4rem;transition:opacity .25s}.md-footer-nav__link:hover{opacity:.7}.md-footer-nav__link--prev{width:25%;float:left}[dir=rtl] .md-footer-nav__link--prev{float:right}.md-footer-nav__link--next{width:75%;float:right;text-align:right}[dir=rtl] .md-footer-nav__link--next{float:left;text-align:left}.md-footer-nav__button{transition:background .25s}.md-footer-nav__title{position:relative;padding:0 1rem;font-size:.9rem;line-height:2.4rem}.md-footer-nav__direction{position:absolute;right:0;left:0;margin-top:-1rem;padding:0 1rem;color:hsla(0,0%,100%,.7);font-size:.75rem}.md-footer-meta{background-color:rgba(0,0,0,.895)}.md-footer-meta__inner{padding:.2rem;overflow:auto}html .md-footer-meta.md-typeset a{color:hsla(0,0%,100%,.7)}html .md-footer-meta.md-typeset a:focus,html .md-footer-meta.md-typeset a:hover{color:#fff}.md-footer-copyright{margin:0 .6rem;padding:.4rem 0;color:hsla(0,0%,100%,.3);font-size:.64rem}.md-footer-copyright__highlight{color:hsla(0,0%,100%,.7)}.md-footer-social{margin:0 .4rem;padding:.2rem 0 .6rem}.md-footer-social__link{display:inline-block;width:1.6rem;height:1.6rem;font-size:.8rem;text-align:center}.md-footer-social__link:before{line-height:1.9}.md-nav{font-size:.7rem;line-height:1.3}.md-nav__title{display:block;padding:0 .6rem;font-weight:700;text-overflow:ellipsis;overflow:hidden}.md-nav__title:before{display:none;content:"\E5C4"}[dir=rtl] .md-nav__title:before{content:"\E5C8"}.md-nav__title .md-nav__button{display:none}.md-nav__list{margin:0;padding:0;list-style:none}.md-nav__item{padding:0 .6rem}.md-nav__item:last-child{padding-bottom:.6rem}.md-nav__item .md-nav__item{padding-right:0}[dir=rtl] .md-nav__item .md-nav__item{padding-right:.6rem;padding-left:0}.md-nav__item .md-nav__item:last-child{padding-bottom:0}.md-nav__button img{width:100%;height:auto}.md-nav__link{display:block;margin-top:.625em;transition:color .125s;text-overflow:ellipsis;cursor:pointer;overflow:hidden}.md-nav__item--nested>.md-nav__link:after{content:"\E313"}html .md-nav__link[for=__toc],html .md-nav__link[for=__toc]+.md-nav__link:after,html .md-nav__link[for=__toc]~.md-nav{display:none}.md-nav__link[data-md-state=blur]{color:rgba(0,0,0,.54)}.md-nav__link--active,.md-nav__link:active{color:#3f51b5}.md-nav__item--nested>.md-nav__link{color:inherit}.md-nav__link:focus,.md-nav__link:hover{color:#536dfe}.md-nav__source,.no-js .md-search{display:none}.md-search__overlay{opacity:0;z-index:1}.md-search__form{position:relative}.md-search__input{position:relative;padding:0 2.2rem 0 3.6rem;text-overflow:ellipsis;z-index:2}[dir=rtl] .md-search__input{padding:0 3.6rem 0 2.2rem}.md-search__input::-webkit-input-placeholder{transition:color .25s cubic-bezier(.1,.7,.1,1)}.md-search__input:-ms-input-placeholder{transition:color .25s cubic-bezier(.1,.7,.1,1)}.md-search__input::-ms-input-placeholder{transition:color .25s cubic-bezier(.1,.7,.1,1)}.md-search__input::placeholder{transition:color .25s cubic-bezier(.1,.7,.1,1)}.md-search__input::-webkit-input-placeholder,.md-search__input~.md-search__icon{color:rgba(0,0,0,.54)}.md-search__input:-ms-input-placeholder,.md-search__input~.md-search__icon{color:rgba(0,0,0,.54)}.md-search__input::-ms-input-placeholder,.md-search__input~.md-search__icon{color:rgba(0,0,0,.54)}.md-search__input::placeholder,.md-search__input~.md-search__icon{color:rgba(0,0,0,.54)}.md-search__input::-ms-clear{display:none}.md-search__icon{position:absolute;transition:color .25s cubic-bezier(.1,.7,.1,1),opacity .25s;font-size:1.2rem;cursor:pointer;z-index:2}.md-search__icon:hover{opacity:.7}.md-search__icon[for=__search]{top:.3rem;left:.5rem}[dir=rtl] .md-search__icon[for=__search]{right:.5rem;left:auto}.md-search__icon[for=__search]:before{content:"\E8B6"}.md-search__icon[type=reset]{top:.3rem;right:.5rem;-webkit-transform:scale(.125);transform:scale(.125);transition:opacity .15s,-webkit-transform .15s cubic-bezier(.1,.7,.1,1);transition:transform .15s cubic-bezier(.1,.7,.1,1),opacity .15s;transition:transform .15s cubic-bezier(.1,.7,.1,1),opacity .15s,-webkit-transform .15s cubic-bezier(.1,.7,.1,1);opacity:0}[dir=rtl] .md-search__icon[type=reset]{right:auto;left:.5rem}[data-md-toggle=search]:checked~.md-header .md-search__input:valid~.md-search__icon[type=reset]{-webkit-transform:scale(1);transform:scale(1);opacity:1}[data-md-toggle=search]:checked~.md-header .md-search__input:valid~.md-search__icon[type=reset]:hover{opacity:.7}.md-search__output{position:absolute;width:100%;border-radius:0 0 .1rem .1rem;overflow:hidden;z-index:1}.md-search__scrollwrap{height:100%;background-color:#fff;box-shadow:inset 0 .05rem 0 rgba(0,0,0,.07);overflow-y:auto;-webkit-overflow-scrolling:touch}.md-search-result{color:rgba(0,0,0,.87);word-break:break-word}.md-search-result__meta{padding:0 .8rem;background-color:rgba(0,0,0,.07);color:rgba(0,0,0,.54);font-size:.64rem;line-height:1.8rem}.md-search-result__list{margin:0;padding:0;border-top:.05rem solid rgba(0,0,0,.07);list-style:none}.md-search-result__item{box-shadow:0 -.05rem 0 rgba(0,0,0,.07)}.md-search-result__link{display:block;transition:background .25s;outline:0;overflow:hidden}.md-search-result__link:hover,.md-search-result__link[data-md-state=active]{background-color:rgba(83,109,254,.1)}.md-search-result__link:hover .md-search-result__article:before,.md-search-result__link[data-md-state=active] .md-search-result__article:before{opacity:.7}.md-search-result__link:last-child .md-search-result__teaser{margin-bottom:.6rem}.md-search-result__article{position:relative;padding:0 .8rem;overflow:auto}.md-search-result__article--document:before{position:absolute;left:0;margin:.1rem;transition:opacity .25s;color:rgba(0,0,0,.54);content:"\E880"}[dir=rtl] .md-search-result__article--document:before{right:0;left:auto}.md-search-result__article--document .md-search-result__title{margin:.55rem 0;font-size:.8rem;font-weight:400;line-height:1.4}.md-search-result__title{margin:.5em 0;font-size:.64rem;font-weight:700;line-height:1.4}.md-search-result__teaser{display:-webkit-box;max-height:1.65rem;margin:.5em 0;color:rgba(0,0,0,.54);font-size:.64rem;line-height:1.4;text-overflow:ellipsis;overflow:hidden;-webkit-line-clamp:2}.md-search-result em{font-style:normal;font-weight:700;text-decoration:underline}.md-sidebar{position:absolute;width:12.1rem;padding:1.2rem 0;overflow:hidden}.md-sidebar[data-md-state=lock]{position:fixed;top:2.4rem}.md-sidebar--secondary{display:none}.md-sidebar__scrollwrap{max-height:100%;margin:0 .2rem;overflow-y:auto;-webkit-backface-visibility:hidden;backface-visibility:hidden}.md-sidebar__scrollwrap::-webkit-scrollbar{width:.2rem;height:.2rem}.md-sidebar__scrollwrap::-webkit-scrollbar-thumb{background-color:rgba(0,0,0,.26)}.md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#536dfe}.rst-versions{font-size:.85rem}@-webkit-keyframes md-source__facts--done{0%{height:0}to{height:.65rem}}@keyframes md-source__facts--done{0%{height:0}to{height:.65rem}}@-webkit-keyframes md-source__fact--done{0%{-webkit-transform:translateY(100%);transform:translateY(100%);opacity:0}50%{opacity:0}to{-webkit-transform:translateY(0);transform:translateY(0);opacity:1}}@keyframes md-source__fact--done{0%{-webkit-transform:translateY(100%);transform:translateY(100%);opacity:0}50%{opacity:0}to{-webkit-transform:translateY(0);transform:translateY(0);opacity:1}}.md-source{display:block;padding-right:.6rem;transition:opacity .25s;font-size:.65rem;line-height:1.2;white-space:nowrap}[dir=rtl] .md-source{padding-right:0;padding-left:.6rem}.md-source:hover{opacity:.7}.md-source:after,.md-source__icon{display:inline-block;height:2.4rem;content:"";vertical-align:middle}.md-source__icon{width:2.4rem}.md-source__icon svg{width:1.2rem;height:1.2rem;margin-top:.6rem;margin-left:.6rem}[dir=rtl] .md-source__icon svg{margin-right:.6rem;margin-left:0}.md-source__icon+.md-source__repository{margin-left:-2rem;padding-left:2rem}[dir=rtl] .md-source__icon+.md-source__repository{margin-right:-2rem;margin-left:0;padding-right:2rem;padding-left:0}.md-source__repository{display:inline-block;max-width:100%;margin-left:.6rem;font-weight:700;text-overflow:ellipsis;overflow:hidden;vertical-align:middle}.md-source__facts{margin:0;padding:0;font-size:.55rem;font-weight:700;list-style-type:none;opacity:.75;overflow:hidden}[data-md-state=done] .md-source__facts{-webkit-animation:md-source__facts--done .25s ease-in;animation:md-source__facts--done .25s ease-in}.md-source__fact{float:left}[dir=rtl] .md-source__fact{float:right}[data-md-state=done] .md-source__fact{-webkit-animation:md-source__fact--done .4s ease-out;animation:md-source__fact--done .4s ease-out}.md-source__fact:before{margin:0 .1rem;content:"\00B7"}.md-source__fact:first-child:before{display:none}.md-source-file{display:inline-block;margin:1em .5em 1em 0;padding-right:.25rem;border-radius:.1rem;background-color:rgba(0,0,0,.07);font-size:.64rem;list-style-type:none;cursor:pointer;overflow:hidden}.md-source-file:before{display:inline-block;margin-right:.25rem;padding:.25rem;background-color:rgba(0,0,0,.26);color:#fff;font-size:.8rem;content:"\E86F";vertical-align:middle}html .md-source-file{transition:background .4s,color .4s,box-shadow .4s cubic-bezier(.4,0,.2,1)}html .md-source-file:before{transition:inherit}html body .md-typeset .md-source-file{color:rgba(0,0,0,.54)}.md-source-file:hover{box-shadow:0 0 8px rgba(0,0,0,.18),0 8px 16px rgba(0,0,0,.36)}.md-source-file:hover:before{background-color:#536dfe}.md-tabs{width:100%;transition:background .25s;background-color:#3f51b5;color:#fff;overflow:auto}.md-tabs__list{margin:0 0 0 .2rem;padding:0;list-style:none;white-space:nowrap}.md-tabs__item{display:inline-block;height:2.4rem;padding-right:.6rem;padding-left:.6rem}.md-tabs__link{display:block;margin-top:.8rem;transition:opacity .25s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .25s;transition:transform .4s cubic-bezier(.1,.7,.1,1),opacity .25s,-webkit-transform .4s cubic-bezier(.1,.7,.1,1);font-size:.7rem;opacity:.7}.md-tabs__link--active,.md-tabs__link:hover{color:inherit;opacity:1}.md-tabs__item:nth-child(2) .md-tabs__link{transition-delay:.02s}.md-tabs__item:nth-child(3) .md-tabs__link{transition-delay:.04s}.md-tabs__item:nth-child(4) .md-tabs__link{transition-delay:.06s}.md-tabs__item:nth-child(5) .md-tabs__link{transition-delay:.08s}.md-tabs__item:nth-child(6) .md-tabs__link{transition-delay:.1s}.md-tabs__item:nth-child(7) .md-tabs__link{transition-delay:.12s}.md-tabs__item:nth-child(8) .md-tabs__link{transition-delay:.14s}.md-tabs__item:nth-child(9) .md-tabs__link{transition-delay:.16s}.md-tabs__item:nth-child(10) .md-tabs__link{transition-delay:.18s}.md-tabs__item:nth-child(11) .md-tabs__link{transition-delay:.2s}.md-tabs__item:nth-child(12) .md-tabs__link{transition-delay:.22s}.md-tabs__item:nth-child(13) .md-tabs__link{transition-delay:.24s}.md-tabs__item:nth-child(14) .md-tabs__link{transition-delay:.26s}.md-tabs__item:nth-child(15) .md-tabs__link{transition-delay:.28s}.md-tabs__item:nth-child(16) .md-tabs__link{transition-delay:.3s}.md-tabs[data-md-state=hidden]{pointer-events:none}.md-tabs[data-md-state=hidden] .md-tabs__link{-webkit-transform:translateY(50%);transform:translateY(50%);transition:color .25s,opacity .1s,-webkit-transform 0 .4s;transition:color .25s,transform 0 .4s,opacity .1s;transition:color .25s,transform 0 .4s,opacity .1s,-webkit-transform 0 .4s;opacity:0}.md-typeset .admonition,.md-typeset details{box-shadow:0 2px 2px 0 rgba(0,0,0,.14),0 1px 5px 0 rgba(0,0,0,.12),0 3px 1px -2px rgba(0,0,0,.2);position:relative;margin:1.5625em 0;padding:0 .6rem;border-left:.2rem solid #448aff;border-radius:.1rem;font-size:.64rem;overflow:auto}[dir=rtl] .md-typeset .admonition,[dir=rtl] .md-typeset details{border-right:.2rem solid #448aff;border-left:none}html .md-typeset .admonition>:last-child,html .md-typeset details>:last-child{margin-bottom:.6rem}.md-typeset .admonition .admonition,.md-typeset .admonition details,.md-typeset details .admonition,.md-typeset details details{margin:1em 0}.md-typeset .admonition>.admonition-title,.md-typeset .admonition>summary,.md-typeset details>.admonition-title,.md-typeset details>summary{margin:0 -.6rem;padding:.4rem .6rem .4rem 2rem;border-bottom:.05rem solid rgba(68,138,255,.1);background-color:rgba(68,138,255,.1);font-weight:700}[dir=rtl] .md-typeset .admonition>.admonition-title,[dir=rtl] .md-typeset .admonition>summary,[dir=rtl] .md-typeset details>.admonition-title,[dir=rtl] .md-typeset details>summary{padding:.4rem 2rem .4rem .6rem}.md-typeset .admonition>.admonition-title:last-child,.md-typeset .admonition>summary:last-child,.md-typeset details>.admonition-title:last-child,.md-typeset details>summary:last-child{margin-bottom:0}.md-typeset .admonition>.admonition-title:before,.md-typeset .admonition>summary:before,.md-typeset details>.admonition-title:before,.md-typeset details>summary:before{position:absolute;left:.6rem;color:#448aff;font-size:1rem;content:"\E3C9"}[dir=rtl] .md-typeset .admonition>.admonition-title:before,[dir=rtl] .md-typeset .admonition>summary:before,[dir=rtl] .md-typeset details>.admonition-title:before,[dir=rtl] .md-typeset details>summary:before{right:.6rem;left:auto}.md-typeset .admonition.abstract,.md-typeset .admonition.summary,.md-typeset .admonition.tldr,.md-typeset details.abstract,.md-typeset details.summary,.md-typeset details.tldr{border-left-color:#00b0ff}[dir=rtl] .md-typeset .admonition.abstract,[dir=rtl] .md-typeset .admonition.summary,[dir=rtl] .md-typeset .admonition.tldr,[dir=rtl] .md-typeset details.abstract,[dir=rtl] .md-typeset details.summary,[dir=rtl] .md-typeset details.tldr{border-right-color:#00b0ff}.md-typeset .admonition.abstract>.admonition-title,.md-typeset .admonition.abstract>summary,.md-typeset .admonition.summary>.admonition-title,.md-typeset .admonition.summary>summary,.md-typeset .admonition.tldr>.admonition-title,.md-typeset .admonition.tldr>summary,.md-typeset details.abstract>.admonition-title,.md-typeset details.abstract>summary,.md-typeset details.summary>.admonition-title,.md-typeset details.summary>summary,.md-typeset details.tldr>.admonition-title,.md-typeset details.tldr>summary{border-bottom-color:rgba(0,176,255,.1);background-color:rgba(0,176,255,.1)}.md-typeset .admonition.abstract>.admonition-title:before,.md-typeset .admonition.abstract>summary:before,.md-typeset .admonition.summary>.admonition-title:before,.md-typeset .admonition.summary>summary:before,.md-typeset .admonition.tldr>.admonition-title:before,.md-typeset .admonition.tldr>summary:before,.md-typeset details.abstract>.admonition-title:before,.md-typeset details.abstract>summary:before,.md-typeset details.summary>.admonition-title:before,.md-typeset details.summary>summary:before,.md-typeset details.tldr>.admonition-title:before,.md-typeset details.tldr>summary:before{color:#00b0ff;content:""}.md-typeset .admonition.info,.md-typeset .admonition.todo,.md-typeset details.info,.md-typeset details.todo{border-left-color:#00b8d4}[dir=rtl] .md-typeset .admonition.info,[dir=rtl] .md-typeset .admonition.todo,[dir=rtl] .md-typeset details.info,[dir=rtl] .md-typeset details.todo{border-right-color:#00b8d4}.md-typeset .admonition.info>.admonition-title,.md-typeset .admonition.info>summary,.md-typeset .admonition.todo>.admonition-title,.md-typeset .admonition.todo>summary,.md-typeset details.info>.admonition-title,.md-typeset details.info>summary,.md-typeset details.todo>.admonition-title,.md-typeset details.todo>summary{border-bottom-color:rgba(0,184,212,.1);background-color:rgba(0,184,212,.1)}.md-typeset .admonition.info>.admonition-title:before,.md-typeset .admonition.info>summary:before,.md-typeset .admonition.todo>.admonition-title:before,.md-typeset .admonition.todo>summary:before,.md-typeset details.info>.admonition-title:before,.md-typeset details.info>summary:before,.md-typeset details.todo>.admonition-title:before,.md-typeset details.todo>summary:before{color:#00b8d4;content:""}.md-typeset .admonition.hint,.md-typeset .admonition.important,.md-typeset .admonition.tip,.md-typeset details.hint,.md-typeset details.important,.md-typeset details.tip{border-left-color:#00bfa5}[dir=rtl] .md-typeset .admonition.hint,[dir=rtl] .md-typeset .admonition.important,[dir=rtl] .md-typeset .admonition.tip,[dir=rtl] .md-typeset details.hint,[dir=rtl] .md-typeset details.important,[dir=rtl] .md-typeset details.tip{border-right-color:#00bfa5}.md-typeset .admonition.hint>.admonition-title,.md-typeset .admonition.hint>summary,.md-typeset .admonition.important>.admonition-title,.md-typeset .admonition.important>summary,.md-typeset .admonition.tip>.admonition-title,.md-typeset .admonition.tip>summary,.md-typeset details.hint>.admonition-title,.md-typeset details.hint>summary,.md-typeset details.important>.admonition-title,.md-typeset details.important>summary,.md-typeset details.tip>.admonition-title,.md-typeset details.tip>summary{border-bottom-color:rgba(0,191,165,.1);background-color:rgba(0,191,165,.1)}.md-typeset .admonition.hint>.admonition-title:before,.md-typeset .admonition.hint>summary:before,.md-typeset .admonition.important>.admonition-title:before,.md-typeset .admonition.important>summary:before,.md-typeset .admonition.tip>.admonition-title:before,.md-typeset .admonition.tip>summary:before,.md-typeset details.hint>.admonition-title:before,.md-typeset details.hint>summary:before,.md-typeset details.important>.admonition-title:before,.md-typeset details.important>summary:before,.md-typeset details.tip>.admonition-title:before,.md-typeset details.tip>summary:before{color:#00bfa5;content:""}.md-typeset .admonition.check,.md-typeset .admonition.done,.md-typeset .admonition.success,.md-typeset details.check,.md-typeset details.done,.md-typeset details.success{border-left-color:#00c853}[dir=rtl] .md-typeset .admonition.check,[dir=rtl] .md-typeset .admonition.done,[dir=rtl] .md-typeset .admonition.success,[dir=rtl] .md-typeset details.check,[dir=rtl] .md-typeset details.done,[dir=rtl] .md-typeset details.success{border-right-color:#00c853}.md-typeset .admonition.check>.admonition-title,.md-typeset .admonition.check>summary,.md-typeset .admonition.done>.admonition-title,.md-typeset .admonition.done>summary,.md-typeset .admonition.success>.admonition-title,.md-typeset .admonition.success>summary,.md-typeset details.check>.admonition-title,.md-typeset details.check>summary,.md-typeset details.done>.admonition-title,.md-typeset details.done>summary,.md-typeset details.success>.admonition-title,.md-typeset details.success>summary{border-bottom-color:rgba(0,200,83,.1);background-color:rgba(0,200,83,.1)}.md-typeset .admonition.check>.admonition-title:before,.md-typeset .admonition.check>summary:before,.md-typeset .admonition.done>.admonition-title:before,.md-typeset .admonition.done>summary:before,.md-typeset .admonition.success>.admonition-title:before,.md-typeset .admonition.success>summary:before,.md-typeset details.check>.admonition-title:before,.md-typeset details.check>summary:before,.md-typeset details.done>.admonition-title:before,.md-typeset details.done>summary:before,.md-typeset details.success>.admonition-title:before,.md-typeset details.success>summary:before{color:#00c853;content:""}.md-typeset .admonition.faq,.md-typeset .admonition.help,.md-typeset .admonition.question,.md-typeset details.faq,.md-typeset details.help,.md-typeset details.question{border-left-color:#64dd17}[dir=rtl] .md-typeset .admonition.faq,[dir=rtl] .md-typeset .admonition.help,[dir=rtl] .md-typeset .admonition.question,[dir=rtl] .md-typeset details.faq,[dir=rtl] .md-typeset details.help,[dir=rtl] .md-typeset details.question{border-right-color:#64dd17}.md-typeset .admonition.faq>.admonition-title,.md-typeset .admonition.faq>summary,.md-typeset .admonition.help>.admonition-title,.md-typeset .admonition.help>summary,.md-typeset .admonition.question>.admonition-title,.md-typeset .admonition.question>summary,.md-typeset details.faq>.admonition-title,.md-typeset details.faq>summary,.md-typeset details.help>.admonition-title,.md-typeset details.help>summary,.md-typeset details.question>.admonition-title,.md-typeset details.question>summary{border-bottom-color:rgba(100,221,23,.1);background-color:rgba(100,221,23,.1)}.md-typeset .admonition.faq>.admonition-title:before,.md-typeset .admonition.faq>summary:before,.md-typeset .admonition.help>.admonition-title:before,.md-typeset .admonition.help>summary:before,.md-typeset .admonition.question>.admonition-title:before,.md-typeset .admonition.question>summary:before,.md-typeset details.faq>.admonition-title:before,.md-typeset details.faq>summary:before,.md-typeset details.help>.admonition-title:before,.md-typeset details.help>summary:before,.md-typeset details.question>.admonition-title:before,.md-typeset details.question>summary:before{color:#64dd17;content:""}.md-typeset .admonition.attention,.md-typeset .admonition.caution,.md-typeset .admonition.warning,.md-typeset details.attention,.md-typeset details.caution,.md-typeset details.warning{border-left-color:#ff9100}[dir=rtl] .md-typeset .admonition.attention,[dir=rtl] .md-typeset .admonition.caution,[dir=rtl] .md-typeset .admonition.warning,[dir=rtl] .md-typeset details.attention,[dir=rtl] .md-typeset details.caution,[dir=rtl] .md-typeset details.warning{border-right-color:#ff9100}.md-typeset .admonition.attention>.admonition-title,.md-typeset .admonition.attention>summary,.md-typeset .admonition.caution>.admonition-title,.md-typeset .admonition.caution>summary,.md-typeset .admonition.warning>.admonition-title,.md-typeset .admonition.warning>summary,.md-typeset details.attention>.admonition-title,.md-typeset details.attention>summary,.md-typeset details.caution>.admonition-title,.md-typeset details.caution>summary,.md-typeset details.warning>.admonition-title,.md-typeset details.warning>summary{border-bottom-color:rgba(255,145,0,.1);background-color:rgba(255,145,0,.1)}.md-typeset .admonition.attention>.admonition-title:before,.md-typeset .admonition.attention>summary:before,.md-typeset .admonition.caution>.admonition-title:before,.md-typeset .admonition.caution>summary:before,.md-typeset .admonition.warning>.admonition-title:before,.md-typeset .admonition.warning>summary:before,.md-typeset details.attention>.admonition-title:before,.md-typeset details.attention>summary:before,.md-typeset details.caution>.admonition-title:before,.md-typeset details.caution>summary:before,.md-typeset details.warning>.admonition-title:before,.md-typeset details.warning>summary:before{color:#ff9100;content:""}.md-typeset .admonition.fail,.md-typeset .admonition.failure,.md-typeset .admonition.missing,.md-typeset details.fail,.md-typeset details.failure,.md-typeset details.missing{border-left-color:#ff5252}[dir=rtl] .md-typeset .admonition.fail,[dir=rtl] .md-typeset .admonition.failure,[dir=rtl] .md-typeset .admonition.missing,[dir=rtl] .md-typeset details.fail,[dir=rtl] .md-typeset details.failure,[dir=rtl] .md-typeset details.missing{border-right-color:#ff5252}.md-typeset .admonition.fail>.admonition-title,.md-typeset .admonition.fail>summary,.md-typeset .admonition.failure>.admonition-title,.md-typeset .admonition.failure>summary,.md-typeset .admonition.missing>.admonition-title,.md-typeset .admonition.missing>summary,.md-typeset details.fail>.admonition-title,.md-typeset details.fail>summary,.md-typeset details.failure>.admonition-title,.md-typeset details.failure>summary,.md-typeset details.missing>.admonition-title,.md-typeset details.missing>summary{border-bottom-color:rgba(255,82,82,.1);background-color:rgba(255,82,82,.1)}.md-typeset .admonition.fail>.admonition-title:before,.md-typeset .admonition.fail>summary:before,.md-typeset .admonition.failure>.admonition-title:before,.md-typeset .admonition.failure>summary:before,.md-typeset .admonition.missing>.admonition-title:before,.md-typeset .admonition.missing>summary:before,.md-typeset details.fail>.admonition-title:before,.md-typeset details.fail>summary:before,.md-typeset details.failure>.admonition-title:before,.md-typeset details.failure>summary:before,.md-typeset details.missing>.admonition-title:before,.md-typeset details.missing>summary:before{color:#ff5252;content:""}.md-typeset .admonition.danger,.md-typeset .admonition.error,.md-typeset details.danger,.md-typeset details.error{border-left-color:#ff1744}[dir=rtl] .md-typeset .admonition.danger,[dir=rtl] .md-typeset .admonition.error,[dir=rtl] .md-typeset details.danger,[dir=rtl] .md-typeset details.error{border-right-color:#ff1744}.md-typeset .admonition.danger>.admonition-title,.md-typeset .admonition.danger>summary,.md-typeset .admonition.error>.admonition-title,.md-typeset .admonition.error>summary,.md-typeset details.danger>.admonition-title,.md-typeset details.danger>summary,.md-typeset details.error>.admonition-title,.md-typeset details.error>summary{border-bottom-color:rgba(255,23,68,.1);background-color:rgba(255,23,68,.1)}.md-typeset .admonition.danger>.admonition-title:before,.md-typeset .admonition.danger>summary:before,.md-typeset .admonition.error>.admonition-title:before,.md-typeset .admonition.error>summary:before,.md-typeset details.danger>.admonition-title:before,.md-typeset details.danger>summary:before,.md-typeset details.error>.admonition-title:before,.md-typeset details.error>summary:before{color:#ff1744;content:""}.md-typeset .admonition.bug,.md-typeset details.bug{border-left-color:#f50057}[dir=rtl] .md-typeset .admonition.bug,[dir=rtl] .md-typeset details.bug{border-right-color:#f50057}.md-typeset .admonition.bug>.admonition-title,.md-typeset .admonition.bug>summary,.md-typeset details.bug>.admonition-title,.md-typeset details.bug>summary{border-bottom-color:rgba(245,0,87,.1);background-color:rgba(245,0,87,.1)}.md-typeset .admonition.bug>.admonition-title:before,.md-typeset .admonition.bug>summary:before,.md-typeset details.bug>.admonition-title:before,.md-typeset details.bug>summary:before{color:#f50057;content:""}.md-typeset .admonition.example,.md-typeset details.example{border-left-color:#651fff}[dir=rtl] .md-typeset .admonition.example,[dir=rtl] .md-typeset details.example{border-right-color:#651fff}.md-typeset .admonition.example>.admonition-title,.md-typeset .admonition.example>summary,.md-typeset details.example>.admonition-title,.md-typeset details.example>summary{border-bottom-color:rgba(101,31,255,.1);background-color:rgba(101,31,255,.1)}.md-typeset .admonition.example>.admonition-title:before,.md-typeset .admonition.example>summary:before,.md-typeset details.example>.admonition-title:before,.md-typeset details.example>summary:before{color:#651fff;content:""}.md-typeset .admonition.cite,.md-typeset .admonition.quote,.md-typeset details.cite,.md-typeset details.quote{border-left-color:#9e9e9e}[dir=rtl] .md-typeset .admonition.cite,[dir=rtl] .md-typeset .admonition.quote,[dir=rtl] .md-typeset details.cite,[dir=rtl] .md-typeset details.quote{border-right-color:#9e9e9e}.md-typeset .admonition.cite>.admonition-title,.md-typeset .admonition.cite>summary,.md-typeset .admonition.quote>.admonition-title,.md-typeset .admonition.quote>summary,.md-typeset details.cite>.admonition-title,.md-typeset details.cite>summary,.md-typeset details.quote>.admonition-title,.md-typeset details.quote>summary{border-bottom-color:hsla(0,0%,62%,.1);background-color:hsla(0,0%,62%,.1)}.md-typeset .admonition.cite>.admonition-title:before,.md-typeset .admonition.cite>summary:before,.md-typeset .admonition.quote>.admonition-title:before,.md-typeset .admonition.quote>summary:before,.md-typeset details.cite>.admonition-title:before,.md-typeset details.cite>summary:before,.md-typeset details.quote>.admonition-title:before,.md-typeset details.quote>summary:before{color:#9e9e9e;content:""}.codehilite .o,.codehilite .ow,.highlight .o,.highlight .ow{color:inherit}.codehilite .ge,.highlight .ge{color:#000}.codehilite .gr,.highlight .gr{color:#a00}.codehilite .gh,.highlight .gh{color:#999}.codehilite .go,.highlight .go{color:#888}.codehilite .gp,.highlight .gp{color:#555}.codehilite .gs,.highlight .gs{color:inherit}.codehilite .gu,.highlight .gu{color:#aaa}.codehilite .gt,.highlight .gt{color:#a00}.codehilite .gd,.highlight .gd{background-color:#fdd}.codehilite .gi,.highlight .gi{background-color:#dfd}.codehilite .k,.highlight .k{color:#3b78e7}.codehilite .kc,.highlight .kc{color:#a71d5d}.codehilite .kd,.codehilite .kn,.highlight .kd,.highlight .kn{color:#3b78e7}.codehilite .kp,.highlight .kp{color:#a71d5d}.codehilite .kr,.codehilite .kt,.highlight .kr,.highlight .kt{color:#3e61a2}.codehilite .c,.codehilite .cm,.highlight .c,.highlight .cm{color:#999}.codehilite .cp,.highlight .cp{color:#666}.codehilite .c1,.codehilite .ch,.codehilite .cs,.highlight .c1,.highlight .ch,.highlight .cs{color:#999}.codehilite .na,.codehilite .nb,.highlight .na,.highlight .nb{color:#c2185b}.codehilite .bp,.highlight .bp{color:#3e61a2}.codehilite .nc,.highlight .nc{color:#c2185b}.codehilite .no,.highlight .no{color:#3e61a2}.codehilite .nd,.codehilite .ni,.highlight .nd,.highlight .ni{color:#666}.codehilite .ne,.codehilite .nf,.highlight .ne,.highlight .nf{color:#c2185b}.codehilite .nl,.highlight .nl{color:#3b5179}.codehilite .nn,.highlight .nn{color:#ec407a}.codehilite .nt,.highlight .nt{color:#3b78e7}.codehilite .nv,.codehilite .vc,.codehilite .vg,.codehilite .vi,.highlight .nv,.highlight .vc,.highlight .vg,.highlight .vi{color:#3e61a2}.codehilite .nx,.highlight .nx{color:#ec407a}.codehilite .il,.codehilite .m,.codehilite .mf,.codehilite .mh,.codehilite .mi,.codehilite .mo,.highlight .il,.highlight .m,.highlight .mf,.highlight .mh,.highlight .mi,.highlight .mo{color:#e74c3c}.codehilite .s,.codehilite .sb,.codehilite .sc,.highlight .s,.highlight .sb,.highlight .sc{color:#0d904f}.codehilite .sd,.highlight .sd{color:#999}.codehilite .s2,.highlight .s2{color:#0d904f}.codehilite .se,.codehilite .sh,.codehilite .si,.codehilite .sx,.highlight .se,.highlight .sh,.highlight .si,.highlight .sx{color:#183691}.codehilite .sr,.highlight .sr{color:#009926}.codehilite .s1,.codehilite .ss,.highlight .s1,.highlight .ss{color:#0d904f}.codehilite .err,.highlight .err{color:#a61717}.codehilite .w,.highlight .w{color:transparent}.codehilite .hll,.highlight .hll{display:block;margin:0 -.6rem;padding:0 .6rem;background-color:rgba(255,235,59,.5)}.md-typeset .codehilite,.highlight{position:relative;margin:1em 0;padding:0;border-radius:.1rem;background-color:hsla(0,0%,92.5%,.5);color:#37474f;line-height:1.4;-webkit-overflow-scrolling:touch}.md-typeset .codehilite code,.md-typeset .codehilite pre,.highlight code,.highlight pre{display:block;margin:0;padding:.525rem .6rem;background-color:transparent;overflow:auto;vertical-align:top}.md-typeset .codehilite code::-webkit-scrollbar,.md-typeset .codehilite pre::-webkit-scrollbar,.highlight code::-webkit-scrollbar,.highlight pre::-webkit-scrollbar{width:.2rem;height:.2rem}.md-typeset .codehilite code::-webkit-scrollbar-thumb,.md-typeset .codehilite pre::-webkit-scrollbar-thumb,.highlight code::-webkit-scrollbar-thumb,.highlight pre::-webkit-scrollbar-thumb{background-color:rgba(0,0,0,.26)}.md-typeset .codehilite code::-webkit-scrollbar-thumb:hover,.md-typeset .codehilite pre::-webkit-scrollbar-thumb:hover,.highlight code::-webkit-scrollbar-thumb:hover,.highlight pre::-webkit-scrollbar-thumb:hover{background-color:#536dfe}.md-typeset pre.codehilite,.md-typeset pre.highlight{overflow:visible}.md-typeset pre.codehilite code,.md-typeset pre.highlight code{display:block;padding:.525rem .6rem;overflow:auto}.md-typeset .codehilitetable,.md-typeset .highlighttable{display:block;margin:1em 0;border-radius:.2em;font-size:.8rem;overflow:hidden}.md-typeset .codehilitetable tbody,.md-typeset .codehilitetable td,.md-typeset .highlighttable tbody,.md-typeset .highlighttable td{display:block;padding:0}.md-typeset .codehilitetable tr,.md-typeset .highlighttable tr{display:flex}.md-typeset .codehilitetable .codehilite,.md-typeset .codehilitetable .highlight,.md-typeset .codehilitetable .linenodiv,.md-typeset .highlighttable .codehilite,.md-typeset .highlighttable .highlight,.md-typeset .highlighttable .linenodiv{margin:0;border-radius:0}.md-typeset .codehilitetable .linenodiv,.md-typeset .highlighttable .linenodiv{padding:.525rem .6rem}.md-typeset .codehilitetable .linenos,.md-typeset .highlighttable .linenos{background-color:rgba(0,0,0,.07);color:rgba(0,0,0,.26);-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.md-typeset .codehilitetable .linenos pre,.md-typeset .highlighttable .linenos pre{margin:0;padding:0;background-color:transparent;color:inherit;text-align:right}.md-typeset .codehilitetable .code,.md-typeset .highlighttable .code{flex:1;overflow:hidden}.md-typeset>.codehilitetable,.md-typeset>.highlighttable{box-shadow:none}.md-typeset [id^="fnref:"]{display:inline-block}.md-typeset [id^="fnref:"]:target{margin-top:-3.8rem;padding-top:3.8rem;pointer-events:none}.md-typeset [id^="fn:"]:before{display:none;height:0;content:""}.md-typeset [id^="fn:"]:target:before{display:block;margin-top:-3.5rem;padding-top:3.5rem;pointer-events:none}.md-typeset .footnote{color:rgba(0,0,0,.54);font-size:.64rem}.md-typeset .footnote ol{margin-left:0}.md-typeset .footnote li{transition:color .25s}.md-typeset .footnote li:target{color:rgba(0,0,0,.87)}.md-typeset .footnote li :first-child{margin-top:0}.md-typeset .footnote li:hover .footnote-backref,.md-typeset .footnote li:target .footnote-backref{-webkit-transform:translateX(0);transform:translateX(0);opacity:1}.md-typeset .footnote li:hover .footnote-backref:hover,.md-typeset .footnote li:target .footnote-backref{color:#536dfe}.md-typeset .footnote-ref{display:inline-block;pointer-events:auto}.md-typeset .footnote-ref:before{display:inline;margin:0 .2em;border-left:.05rem solid rgba(0,0,0,.26);font-size:1.25em;content:"";vertical-align:-.25rem}.md-typeset .footnote-backref{display:inline-block;-webkit-transform:translateX(.25rem);transform:translateX(.25rem);transition:color .25s,opacity .125s .125s,-webkit-transform .25s .125s;transition:transform .25s .125s,color .25s,opacity .125s .125s;transition:transform .25s .125s,color .25s,opacity .125s .125s,-webkit-transform .25s .125s;color:rgba(0,0,0,.26);font-size:0;opacity:0;vertical-align:text-bottom}[dir=rtl] .md-typeset .footnote-backref{-webkit-transform:translateX(-.25rem);transform:translateX(-.25rem)}.md-typeset .footnote-backref:before{display:inline-block;font-size:.8rem;content:"\E31B"}[dir=rtl] .md-typeset .footnote-backref:before{-webkit-transform:scaleX(-1);transform:scaleX(-1)}.md-typeset .headerlink{display:inline-block;margin-left:.5rem;-webkit-transform:translateY(.25rem);transform:translateY(.25rem);transition:color .25s,opacity .125s .25s,-webkit-transform .25s .25s;transition:transform .25s .25s,color .25s,opacity .125s .25s;transition:transform .25s .25s,color .25s,opacity .125s .25s,-webkit-transform .25s .25s;opacity:0}[dir=rtl] .md-typeset .headerlink{margin-right:.5rem;margin-left:0}html body .md-typeset .headerlink{color:rgba(0,0,0,.26)}.md-typeset h1[id]:before{display:block;margin-top:-9px;padding-top:9px;content:""}.md-typeset h1[id]:target:before{margin-top:-3.45rem;padding-top:3.45rem}.md-typeset h1[id] .headerlink:focus,.md-typeset h1[id]:hover .headerlink,.md-typeset h1[id]:target .headerlink{-webkit-transform:translate(0);transform:translate(0);opacity:1}.md-typeset h1[id] .headerlink:focus,.md-typeset h1[id]:hover .headerlink:hover,.md-typeset h1[id]:target .headerlink{color:#536dfe}.md-typeset h2[id]:before{display:block;margin-top:-8px;padding-top:8px;content:""}.md-typeset h2[id]:target:before{margin-top:-3.4rem;padding-top:3.4rem}.md-typeset h2[id] .headerlink:focus,.md-typeset h2[id]:hover .headerlink,.md-typeset h2[id]:target .headerlink{-webkit-transform:translate(0);transform:translate(0);opacity:1}.md-typeset h2[id] .headerlink:focus,.md-typeset h2[id]:hover .headerlink:hover,.md-typeset h2[id]:target .headerlink{color:#536dfe}.md-typeset h3[id]:before{display:block;margin-top:-9px;padding-top:9px;content:""}.md-typeset h3[id]:target:before{margin-top:-3.45rem;padding-top:3.45rem}.md-typeset h3[id] .headerlink:focus,.md-typeset h3[id]:hover .headerlink,.md-typeset h3[id]:target .headerlink{-webkit-transform:translate(0);transform:translate(0);opacity:1}.md-typeset h3[id] .headerlink:focus,.md-typeset h3[id]:hover .headerlink:hover,.md-typeset h3[id]:target .headerlink{color:#536dfe}.md-typeset h4[id]:before{display:block;margin-top:-9px;padding-top:9px;content:""}.md-typeset h4[id]:target:before{margin-top:-3.45rem;padding-top:3.45rem}.md-typeset h4[id] .headerlink:focus,.md-typeset h4[id]:hover .headerlink,.md-typeset h4[id]:target .headerlink{-webkit-transform:translate(0);transform:translate(0);opacity:1}.md-typeset h4[id] .headerlink:focus,.md-typeset h4[id]:hover .headerlink:hover,.md-typeset h4[id]:target .headerlink{color:#536dfe}.md-typeset h5[id]:before{display:block;margin-top:-11px;padding-top:11px;content:""}.md-typeset h5[id]:target:before{margin-top:-3.55rem;padding-top:3.55rem}.md-typeset h5[id] .headerlink:focus,.md-typeset h5[id]:hover .headerlink,.md-typeset h5[id]:target .headerlink{-webkit-transform:translate(0);transform:translate(0);opacity:1}.md-typeset h5[id] .headerlink:focus,.md-typeset h5[id]:hover .headerlink:hover,.md-typeset h5[id]:target .headerlink{color:#536dfe}.md-typeset h6[id]:before{display:block;margin-top:-11px;padding-top:11px;content:""}.md-typeset h6[id]:target:before{margin-top:-3.55rem;padding-top:3.55rem}.md-typeset h6[id] .headerlink:focus,.md-typeset h6[id]:hover .headerlink,.md-typeset h6[id]:target .headerlink{-webkit-transform:translate(0);transform:translate(0);opacity:1}.md-typeset h6[id] .headerlink:focus,.md-typeset h6[id]:hover .headerlink:hover,.md-typeset h6[id]:target .headerlink{color:#536dfe}.md-typeset .MJXc-display{margin:.75em 0;padding:.75em 0;overflow:auto;-webkit-overflow-scrolling:touch}.md-typeset .MathJax_CHTML{outline:0}.md-typeset .critic.comment,.md-typeset del.critic,.md-typeset ins.critic{margin:0 .25em;padding:.0625em 0;border-radius:.1rem;-webkit-box-decoration-break:clone;box-decoration-break:clone}.md-typeset del.critic{background-color:#fdd;box-shadow:.25em 0 0 #fdd,-.25em 0 0 #fdd}.md-typeset ins.critic{background-color:#dfd;box-shadow:.25em 0 0 #dfd,-.25em 0 0 #dfd}.md-typeset .critic.comment{background-color:hsla(0,0%,92.5%,.5);color:#37474f;box-shadow:.25em 0 0 hsla(0,0%,92.5%,.5),-.25em 0 0 hsla(0,0%,92.5%,.5)}.md-typeset .critic.comment:before{padding-right:.125em;color:rgba(0,0,0,.26);content:"\E0B7";vertical-align:-.125em}.md-typeset .critic.block{display:block;margin:1em 0;padding-right:.8rem;padding-left:.8rem;box-shadow:none}.md-typeset .critic.block :first-child{margin-top:.5em}.md-typeset .critic.block :last-child{margin-bottom:.5em}.md-typeset details{display:block;padding-top:0}.md-typeset details[open]>summary:after{-webkit-transform:rotate(180deg);transform:rotate(180deg)}.md-typeset details:not([open]){padding-bottom:0}.md-typeset details:not([open])>summary{border-bottom:none}.md-typeset details summary{padding-right:2rem}[dir=rtl] .md-typeset details summary{padding-left:2rem}.no-details .md-typeset details:not([open])>*{display:none}.no-details .md-typeset details:not([open]) summary{display:block}.md-typeset summary{display:block;outline:none;cursor:pointer}.md-typeset summary::-webkit-details-marker{display:none}.md-typeset summary:after{position:absolute;top:.4rem;right:.6rem;color:rgba(0,0,0,.26);font-size:1rem;content:"\E313"}[dir=rtl] .md-typeset summary:after{right:auto;left:.6rem}.md-typeset .emojione{width:1rem;vertical-align:text-top}.md-typeset code.codehilite,.md-typeset code.highlight{margin:0 .29412em;padding:.07353em 0}.md-typeset .superfences-content{display:none;order:99;width:100%;background-color:#fff}.md-typeset .superfences-content>*{margin:0;border-radius:0}.md-typeset .superfences-tabs{display:flex;position:relative;flex-wrap:wrap;margin:1em 0;border:.05rem solid rgba(0,0,0,.07);border-radius:.2em}.md-typeset .superfences-tabs>input{display:none}.md-typeset .superfences-tabs>input:checked+label{font-weight:700}.md-typeset .superfences-tabs>input:checked+label+.superfences-content{display:block}.md-typeset .superfences-tabs>label{width:auto;padding:.6rem;transition:color .125s;font-size:.64rem;cursor:pointer}html .md-typeset .superfences-tabs>label:hover{color:#536dfe}.md-typeset .task-list-item{position:relative;list-style-type:none}.md-typeset .task-list-item [type=checkbox]{position:absolute;top:.45em;left:-2em}[dir=rtl] .md-typeset .task-list-item [type=checkbox]{right:-2em;left:auto}.md-typeset .task-list-control .task-list-indicator:before{position:absolute;top:.15em;left:-1.25em;color:rgba(0,0,0,.26);font-size:1.25em;content:"\E835";vertical-align:-.25em}[dir=rtl] .md-typeset .task-list-control .task-list-indicator:before{right:-1.25em;left:auto}.md-typeset .task-list-control [type=checkbox]:checked+.task-list-indicator:before{content:"\E834"}.md-typeset .task-list-control [type=checkbox]{opacity:0;z-index:-1}@media print{.md-typeset a:after{color:rgba(0,0,0,.54);content:" [" attr(href) "]"}.md-typeset code,.md-typeset pre{white-space:pre-wrap}.md-typeset code{box-shadow:none;-webkit-box-decoration-break:initial;box-decoration-break:slice}.md-clipboard,.md-content__icon,.md-footer,.md-header,.md-sidebar,.md-tabs,.md-typeset .headerlink{display:none}}@media only screen and (max-width:44.9375em){.md-typeset pre{margin:1em -.8rem;border-radius:0}.md-typeset pre>code{padding:.525rem .8rem}.md-footer-nav__link--prev .md-footer-nav__title{display:none}.md-search-result__teaser{max-height:2.5rem;-webkit-line-clamp:3}.codehilite .hll,.md-typeset .highlight .hll{margin:0 -.8rem;padding:0 .8rem}.md-typeset>.codehilite,.md-typeset>.highlight{margin:1em -.8rem;border-radius:0}.md-typeset>.codehilite code,.md-typeset>.codehilite pre,.md-typeset>.highlight code,.md-typeset>.highlight pre{padding:.525rem .8rem}.md-typeset>.codehilitetable,.md-typeset>.highlighttable{margin:1em -.8rem;border-radius:0}.md-typeset>.codehilitetable .codehilite>code,.md-typeset>.codehilitetable .codehilite>pre,.md-typeset>.codehilitetable .highlight>code,.md-typeset>.codehilitetable .highlight>pre,.md-typeset>.codehilitetable .linenodiv,.md-typeset>.highlighttable .codehilite>code,.md-typeset>.highlighttable .codehilite>pre,.md-typeset>.highlighttable .highlight>code,.md-typeset>.highlighttable .highlight>pre,.md-typeset>.highlighttable .linenodiv{padding:.5rem .8rem}.md-typeset>p>.MJXc-display{margin:.75em -.8rem;padding:.25em .8rem}.md-typeset>.superfences-tabs{margin:1em -.8rem;border:0;border-top:.05rem solid rgba(0,0,0,.07);border-radius:0}.md-typeset>.superfences-tabs code,.md-typeset>.superfences-tabs pre{padding:.525rem .8rem}}@media only screen and (min-width:100em){html{font-size:137.5%}}@media only screen and (min-width:125em){html{font-size:150%}}@media only screen and (max-width:59.9375em){body[data-md-state=lock]{overflow:hidden}.ios body[data-md-state=lock] .md-container{display:none}html .md-nav__link[for=__toc]{display:block;padding-right:2.4rem}html .md-nav__link[for=__toc]:after{color:inherit;content:"\E8DE"}html .md-nav__link[for=__toc]+.md-nav__link{display:none}html .md-nav__link[for=__toc]~.md-nav{display:flex}html [dir=rtl] .md-nav__link{padding-right:.8rem;padding-left:2.4rem}.md-nav__source{display:block;padding:0 .2rem;background-color:rgba(50,64,144,.9675);color:#fff}.md-search__overlay{position:absolute;top:.2rem;left:.2rem;width:1.8rem;height:1.8rem;-webkit-transform-origin:center;transform-origin:center;transition:opacity .2s .2s,-webkit-transform .3s .1s;transition:transform .3s .1s,opacity .2s .2s;transition:transform .3s .1s,opacity .2s .2s,-webkit-transform .3s .1s;border-radius:1rem;background-color:#fff;overflow:hidden;pointer-events:none}[dir=rtl] .md-search__overlay{right:.2rem;left:auto}[data-md-toggle=search]:checked~.md-header .md-search__overlay{transition:opacity .1s,-webkit-transform .4s;transition:transform .4s,opacity .1s;transition:transform .4s,opacity .1s,-webkit-transform .4s;opacity:1}.md-search__inner{position:fixed;top:0;left:100%;width:100%;height:100%;-webkit-transform:translateX(5%);transform:translateX(5%);transition:right 0 .3s,left 0 .3s,opacity .15s .15s,-webkit-transform .15s cubic-bezier(.4,0,.2,1) .15s;transition:right 0 .3s,left 0 .3s,transform .15s cubic-bezier(.4,0,.2,1) .15s,opacity .15s .15s;transition:right 0 .3s,left 0 .3s,transform .15s cubic-bezier(.4,0,.2,1) .15s,opacity .15s .15s,-webkit-transform .15s cubic-bezier(.4,0,.2,1) .15s;opacity:0;z-index:2}[data-md-toggle=search]:checked~.md-header .md-search__inner{left:0;-webkit-transform:translateX(0);transform:translateX(0);transition:right 0 0,left 0 0,opacity .15s .15s,-webkit-transform .15s cubic-bezier(.1,.7,.1,1) .15s;transition:right 0 0,left 0 0,transform .15s cubic-bezier(.1,.7,.1,1) .15s,opacity .15s .15s;transition:right 0 0,left 0 0,transform .15s cubic-bezier(.1,.7,.1,1) .15s,opacity .15s .15s,-webkit-transform .15s cubic-bezier(.1,.7,.1,1) .15s;opacity:1}[dir=rtl] [data-md-toggle=search]:checked~.md-header .md-search__inner{right:0;left:auto}html [dir=rtl] .md-search__inner{right:100%;left:auto;-webkit-transform:translateX(-5%);transform:translateX(-5%)}.md-search__input{width:100%;height:2.4rem;font-size:.9rem}.md-search__icon[for=__search]{top:.6rem;left:.8rem}.md-search__icon[for=__search][for=__search]:before{content:"\E5C4"}[dir=rtl] .md-search__icon[for=__search][for=__search]:before{content:"\E5C8"}.md-search__icon[type=reset]{top:.6rem;right:.8rem}.md-search__output{top:2.4rem;bottom:0}.md-search-result__article--document:before{display:none}}@media only screen and (max-width:76.1875em){[data-md-toggle=drawer]:checked~.md-overlay{width:100%;height:100%;transition:width 0,height 0,opacity .25s;opacity:1}.md-header-nav__button.md-icon--home,.md-header-nav__button.md-logo{display:none}.md-hero__inner{margin-top:2.4rem;margin-bottom:1.2rem}.md-nav{background-color:#fff}.md-nav--primary,.md-nav--primary .md-nav{display:flex;position:absolute;top:0;right:0;left:0;flex-direction:column;height:100%;z-index:1}.md-nav--primary .md-nav__item,.md-nav--primary .md-nav__title{font-size:.8rem;line-height:1.5}html .md-nav--primary .md-nav__title{position:relative;height:5.6rem;padding:3rem .8rem .2rem;background-color:rgba(0,0,0,.07);color:rgba(0,0,0,.54);font-weight:400;line-height:2.4rem;white-space:nowrap;cursor:pointer}html .md-nav--primary .md-nav__title:before{display:block;position:absolute;top:.2rem;left:.2rem;width:2rem;height:2rem;color:rgba(0,0,0,.54)}html .md-nav--primary .md-nav__title~.md-nav__list{background-color:#fff;box-shadow:inset 0 .05rem 0 rgba(0,0,0,.07)}html .md-nav--primary .md-nav__title~.md-nav__list>.md-nav__item:first-child{border-top:0}html .md-nav--primary .md-nav__title--site{position:relative;background-color:#3f51b5;color:#fff}html .md-nav--primary .md-nav__title--site .md-nav__button{display:block;position:absolute;top:.2rem;left:.2rem;width:3.2rem;height:3.2rem;font-size:2.4rem}html .md-nav--primary .md-nav__title--site:before{display:none}html [dir=rtl] .md-nav--primary .md-nav__title--site .md-nav__button,html [dir=rtl] .md-nav--primary .md-nav__title:before{right:.2rem;left:auto}.md-nav--primary .md-nav__list{flex:1;overflow-y:auto}.md-nav--primary .md-nav__item{padding:0;border-top:.05rem solid rgba(0,0,0,.07)}[dir=rtl] .md-nav--primary .md-nav__item{padding:0}.md-nav--primary .md-nav__item--nested>.md-nav__link{padding-right:2.4rem}[dir=rtl] .md-nav--primary .md-nav__item--nested>.md-nav__link{padding-right:.8rem;padding-left:2.4rem}.md-nav--primary .md-nav__item--nested>.md-nav__link:after{content:"\E315"}[dir=rtl] .md-nav--primary .md-nav__item--nested>.md-nav__link:after{content:"\E314"}.md-nav--primary .md-nav__link{position:relative;margin-top:0;padding:.6rem .8rem}.md-nav--primary .md-nav__link:after{position:absolute;top:50%;right:.6rem;margin-top:-.6rem;color:inherit;font-size:1.2rem}[dir=rtl] .md-nav--primary .md-nav__link:after{right:auto;left:.6rem}.md-nav--primary .md-nav--secondary .md-nav__link{position:static}.md-nav--primary .md-nav--secondary .md-nav{position:static;background-color:transparent}.md-nav--primary .md-nav--secondary .md-nav .md-nav__link{padding-left:1.4rem}[dir=rtl] .md-nav--primary .md-nav--secondary .md-nav .md-nav__link{padding-right:1.4rem;padding-left:0}.md-nav--primary .md-nav--secondary .md-nav .md-nav .md-nav__link{padding-left:2rem}[dir=rtl] .md-nav--primary .md-nav--secondary .md-nav .md-nav .md-nav__link{padding-right:2rem;padding-left:0}.md-nav--primary .md-nav--secondary .md-nav .md-nav .md-nav .md-nav__link{padding-left:2.6rem}[dir=rtl] .md-nav--primary .md-nav--secondary .md-nav .md-nav .md-nav .md-nav__link{padding-right:2.6rem;padding-left:0}.md-nav--primary .md-nav--secondary .md-nav .md-nav .md-nav .md-nav .md-nav__link{padding-left:3.2rem}[dir=rtl] .md-nav--primary .md-nav--secondary .md-nav .md-nav .md-nav .md-nav .md-nav__link{padding-right:3.2rem;padding-left:0}.md-nav__toggle~.md-nav{display:flex;-webkit-transform:translateX(100%);transform:translateX(100%);transition:opacity .125s .05s,-webkit-transform .25s cubic-bezier(.8,0,.6,1);transition:transform .25s cubic-bezier(.8,0,.6,1),opacity .125s .05s;transition:transform .25s cubic-bezier(.8,0,.6,1),opacity .125s .05s,-webkit-transform .25s cubic-bezier(.8,0,.6,1);opacity:0}[dir=rtl] .md-nav__toggle~.md-nav{-webkit-transform:translateX(-100%);transform:translateX(-100%)}.no-csstransforms3d .md-nav__toggle~.md-nav{display:none}.md-nav__toggle:checked~.md-nav{-webkit-transform:translateX(0);transform:translateX(0);transition:opacity .125s .125s,-webkit-transform .25s cubic-bezier(.4,0,.2,1);transition:transform .25s cubic-bezier(.4,0,.2,1),opacity .125s .125s;transition:transform .25s cubic-bezier(.4,0,.2,1),opacity .125s .125s,-webkit-transform .25s cubic-bezier(.4,0,.2,1);opacity:1}.no-csstransforms3d .md-nav__toggle:checked~.md-nav{display:flex}.md-sidebar--primary{position:fixed;top:0;left:-12.1rem;width:12.1rem;height:100%;-webkit-transform:translateX(0);transform:translateX(0);transition:box-shadow .25s,-webkit-transform .25s cubic-bezier(.4,0,.2,1);transition:transform .25s cubic-bezier(.4,0,.2,1),box-shadow .25s;transition:transform .25s cubic-bezier(.4,0,.2,1),box-shadow .25s,-webkit-transform .25s cubic-bezier(.4,0,.2,1);background-color:#fff;z-index:3}[dir=rtl] .md-sidebar--primary{right:-12.1rem;left:auto}.no-csstransforms3d .md-sidebar--primary{display:none}[data-md-toggle=drawer]:checked~.md-container .md-sidebar--primary{box-shadow:0 8px 10px 1px rgba(0,0,0,.14),0 3px 14px 2px rgba(0,0,0,.12),0 5px 5px -3px rgba(0,0,0,.4);-webkit-transform:translateX(12.1rem);transform:translateX(12.1rem)}[dir=rtl] [data-md-toggle=drawer]:checked~.md-container .md-sidebar--primary{-webkit-transform:translateX(-12.1rem);transform:translateX(-12.1rem)}.no-csstransforms3d [data-md-toggle=drawer]:checked~.md-container .md-sidebar--primary{display:block}.md-sidebar--primary .md-sidebar__scrollwrap{overflow:hidden;position:absolute;top:0;right:0;bottom:0;left:0;margin:0}.md-tabs{display:none}}@media only screen and (min-width:60em){.md-content{margin-right:12.1rem}[dir=rtl] .md-content{margin-right:0;margin-left:12.1rem}.md-header-nav__button.md-icon--search{display:none}.md-header-nav__source{display:block;width:11.7rem;max-width:11.7rem;padding-right:.6rem}[dir=rtl] .md-header-nav__source{padding-right:0;padding-left:.6rem}.md-search{padding:.2rem}.md-search__overlay{position:fixed;top:0;left:0;width:0;height:0;transition:width 0 .25s,height 0 .25s,opacity .25s;background-color:rgba(0,0,0,.54);cursor:pointer}[dir=rtl] .md-search__overlay{right:0;left:auto}[data-md-toggle=search]:checked~.md-header .md-search__overlay{width:100%;height:100%;transition:width 0,height 0,opacity .25s;opacity:1}.md-search__inner{position:relative;width:11.5rem;margin-right:.8rem;padding:.1rem 0;float:right;transition:width .25s cubic-bezier(.1,.7,.1,1)}[dir=rtl] .md-search__inner{margin-right:0;margin-left:.8rem;float:left}.md-search__form,.md-search__input{border-radius:.1rem}.md-search__input{width:100%;height:1.8rem;padding-left:2.2rem;transition:background-color .25s cubic-bezier(.1,.7,.1,1),color .25s cubic-bezier(.1,.7,.1,1);background-color:rgba(0,0,0,.26);color:inherit;font-size:.8rem}[dir=rtl] .md-search__input{padding-right:2.2rem}.md-search__input+.md-search__icon{color:inherit}.md-search__input::-webkit-input-placeholder{color:hsla(0,0%,100%,.7)}.md-search__input:-ms-input-placeholder{color:hsla(0,0%,100%,.7)}.md-search__input::-ms-input-placeholder{color:hsla(0,0%,100%,.7)}.md-search__input::placeholder{color:hsla(0,0%,100%,.7)}.md-search__input:hover{background-color:hsla(0,0%,100%,.12)}[data-md-toggle=search]:checked~.md-header .md-search__input{border-radius:.1rem .1rem 0 0;background-color:#fff;color:rgba(0,0,0,.87);text-overflow:clip}[data-md-toggle=search]:checked~.md-header .md-search__input+.md-search__icon,[data-md-toggle=search]:checked~.md-header .md-search__input::-webkit-input-placeholder{color:rgba(0,0,0,.54)}[data-md-toggle=search]:checked~.md-header .md-search__input+.md-search__icon,[data-md-toggle=search]:checked~.md-header .md-search__input:-ms-input-placeholder{color:rgba(0,0,0,.54)}[data-md-toggle=search]:checked~.md-header .md-search__input+.md-search__icon,[data-md-toggle=search]:checked~.md-header .md-search__input::-ms-input-placeholder{color:rgba(0,0,0,.54)}[data-md-toggle=search]:checked~.md-header .md-search__input+.md-search__icon,[data-md-toggle=search]:checked~.md-header .md-search__input::placeholder{color:rgba(0,0,0,.54)}.md-search__output{top:1.9rem;transition:opacity .4s;opacity:0}[data-md-toggle=search]:checked~.md-header .md-search__output{box-shadow:0 6px 10px 0 rgba(0,0,0,.14),0 1px 18px 0 rgba(0,0,0,.12),0 3px 5px -1px rgba(0,0,0,.4);opacity:1}.md-search__scrollwrap{max-height:0}[data-md-toggle=search]:checked~.md-header .md-search__scrollwrap{max-height:75vh}.md-search__scrollwrap::-webkit-scrollbar{width:.2rem;height:.2rem}.md-search__scrollwrap::-webkit-scrollbar-thumb{background-color:rgba(0,0,0,.26)}.md-search__scrollwrap::-webkit-scrollbar-thumb:hover{background-color:#536dfe}.md-search-result__meta{padding-left:2.2rem}[dir=rtl] .md-search-result__meta{padding-right:2.2rem;padding-left:0}.md-search-result__article{padding-left:2.2rem}[dir=rtl] .md-search-result__article{padding-right:2.2rem;padding-left:.8rem}.md-sidebar--secondary{display:block;margin-left:100%;-webkit-transform:translate(-100%);transform:translate(-100%)}[dir=rtl] .md-sidebar--secondary{margin-right:100%;margin-left:0;-webkit-transform:translate(100%);transform:translate(100%)}}@media only screen and (min-width:88.25em){.md-sidebar--secondary{margin-left:73rem}[dir=rtl] .md-sidebar--secondary{margin-right:73rem;margin-left:0}}@media only screen and (min-width:76.25em){.md-content{margin-left:12.1rem}[dir=rtl] .md-content{margin-right:12.1rem}.md-content__inner{margin-right:1.2rem;margin-left:1.2rem}.md-header-nav__button.md-icon--menu{display:none}.md-nav[data-md-state=animate]{transition:max-height .25s cubic-bezier(.86,0,.07,1)}.md-nav__toggle~.md-nav{max-height:0;overflow:hidden}.no-js .md-nav__toggle~.md-nav{display:none}.md-nav[data-md-state=expand],.md-nav__toggle:checked~.md-nav{max-height:100%}.no-js .md-nav[data-md-state=expand],.no-js .md-nav__toggle:checked~.md-nav{display:block}.md-nav__item--nested>.md-nav>.md-nav__title{display:none}.md-nav__item--nested>.md-nav__link:after{display:inline-block;-webkit-transform-origin:.45em .45em;transform-origin:.45em .45em;-webkit-transform-style:preserve-3d;transform-style:preserve-3d;vertical-align:-.125em}.js .md-nav__item--nested>.md-nav__link:after{transition:-webkit-transform .4s;transition:transform .4s;transition:transform .4s,-webkit-transform .4s}.md-nav__item--nested .md-nav__toggle:checked~.md-nav__link:after{-webkit-transform:rotateX(180deg);transform:rotateX(180deg)}.md-search__inner{margin-right:1.2rem}[dir=rtl] .md-search__inner{margin-left:1.2rem}.md-search__scrollwrap,[data-md-toggle=search]:checked~.md-header .md-search__inner{width:34.4rem}.md-tabs~.md-main .md-nav--primary>.md-nav__list>.md-nav__item--nested{font-size:0;visibility:hidden}.md-tabs--active~.md-main .md-nav--primary .md-nav__title{display:block;padding:0}.md-tabs--active~.md-main .md-nav--primary .md-nav__title--site{display:none}.no-js .md-tabs--active~.md-main .md-nav--primary .md-nav{display:block}.md-tabs--active~.md-main .md-nav--primary>.md-nav__list>.md-nav__item{font-size:0;visibility:hidden}.md-tabs--active~.md-main .md-nav--primary>.md-nav__list>.md-nav__item--nested{display:none;font-size:.7rem;overflow:auto;visibility:visible}.md-tabs--active~.md-main .md-nav--primary>.md-nav__list>.md-nav__item--nested>.md-nav__link{display:none}.md-tabs--active~.md-main .md-nav--primary>.md-nav__list>.md-nav__item--active{display:block}.md-tabs--active~.md-main .md-nav[data-md-level=1]{max-height:none;overflow:visible}.md-tabs--active~.md-main .md-nav[data-md-level=1]>.md-nav__list>.md-nav__item{padding-left:0}.md-tabs--active~.md-main .md-nav[data-md-level=1] .md-nav .md-nav__title{display:none}}@media only screen and (min-width:45em){.md-footer-nav__link{width:50%}.md-footer-copyright{max-width:75%;float:left}[dir=rtl] .md-footer-copyright{float:right}.md-footer-social{padding:.6rem 0;float:right}[dir=rtl] .md-footer-social{float:left}}@media only screen and (max-width:29.9375em){[data-md-toggle=search]:checked~.md-header .md-search__overlay{-webkit-transform:scale(45);transform:scale(45)}}@media only screen and (min-width:30em) and (max-width:44.9375em){[data-md-toggle=search]:checked~.md-header .md-search__overlay{-webkit-transform:scale(60);transform:scale(60)}}@media only screen and (min-width:45em) and (max-width:59.9375em){[data-md-toggle=search]:checked~.md-header .md-search__overlay{-webkit-transform:scale(75);transform:scale(75)}}@media only screen and (min-width:60em) and (max-width:76.1875em){.md-search__scrollwrap,[data-md-toggle=search]:checked~.md-header .md-search__inner{width:23.4rem}.md-search-result__teaser{max-height:2.5rem;-webkit-line-clamp:3}} \ No newline at end of file diff --git a/documentation.html b/documentation.html new file mode 100644 index 000000000..78cf39179 --- /dev/null +++ b/documentation.html @@ -0,0 +1,2 @@ + Documentation — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Documentation

The manuals and reference of Jungfraujoch and Rugnux, open-source software from the Paul Scherrer Institute for X-ray diffraction data. The front page has the overview and the downloads; this page is the map of the documentation.

Data processing

Rugnux

Processes a stored macromolecular diffraction dataset, a rotation sweep or serial stills, from the images to merged data: spot finding, indexing, integration, scaling and merging, with the space group, cell and resolution decided from the data and a report that says on what evidence. Given an atomic model it goes on to a refined structure and maps: the model is placed (rigid body or molecular replacement) and refined against the merge. One command, no parameters.

rugnux <diffraction image file>
+rugnux <diffraction image file> <CIF/PDB model file>

Linux · macOS · Windows · fast on an NVIDIA GPU, works without one

Desktop application

Jungfraujoch Viewer

Shows what is in a diffraction dataset: every image with its spots, predictions and resolution rings, per-image statistics over the sweep, grid-scan maps, and the same processing pipeline as Rugnux, run from a settings panel on the open file. Follows a live collection from a running Jungfraujoch broker.

Linux · macOS · Windows · Qt 6

Data acquisition

Jungfraujoch

The data-acquisition and real-time analysis system for the PSI JUNGFRAU and EIGER detectors, and for DECTRIS detectors through their control unit: an FPGA and GPU pipeline that takes the detector's frames at full rate, analyses them on the fly, streams them to the NXmx HDF5 writer and serves a web interface and REST API to the beamline.

Linux servers · AMD Alveo U55C FPGA · NVIDIA GPUs

Licence. Rugnux, the viewer and the Jungfraujoch services are free software under the GNU General Public License v3; the FPGA design is released under the CERN Open Hardware Licence v2, strongly reciprocal. Both let anyone, in academia or industry, use, study and modify the software and the hardware design at no charge, commercial use included; what they ask is that a modified version which is passed on is shared under the same terms. The released binaries bundle third-party components under GPL-compatible licences, and the CUDA builds the NVIDIA CUDA runtime under NVIDIA’s own EULA: see the third-party notices.

All pages

Everything a user of Rugnux or the viewer needs comes first; the technical reference holds the algorithms, the file formats and streams, the interfaces and the FPGA design. The names are explained in Naming, the releases in the changelog, and how to cite the software in Publications.

\ No newline at end of file diff --git a/genindex.html b/genindex.html new file mode 100644 index 000000000..2e2193ce8 --- /dev/null +++ b/genindex.html @@ -0,0 +1 @@ + Index — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/hero_live_dark.webp b/hero_live_dark.webp new file mode 100644 index 000000000..1049b993d Binary files /dev/null and b/hero_live_dark.webp differ diff --git a/hero_live_light.webp b/hero_live_light.webp new file mode 100644 index 000000000..88eac6406 Binary files /dev/null and b/hero_live_light.webp differ diff --git a/index.html b/index.html new file mode 100644 index 000000000..6a3d7d5d4 --- /dev/null +++ b/index.html @@ -0,0 +1,255 @@ + + + + + + +Jungfraujoch and Rugnux: X-ray diffraction data, from the detector to merged data and structures + + + + + + + +
+ Jungfraujoch + + + +
+ +
+ +
+
+ A diffraction image beside the placed model in its electron density, over the timeline of the live analysis: the detector lane of an 18 s collection and the Rugnux lane ending 4.9 s after the last image + +
Cytochrome C at SLS X10SA: 1800 images at 100 Hz, merged and the AlphaFold model placed 4.9 s after the last image
+
+
+

Paul Scherrer Institute · open source

+

From the detector to merged data and structures.

+

Software for X-ray diffraction data: Rugnux takes a stored + dataset from the images to merged data with one command, and with a model on to a + structure and maps; the Viewer shows what is in it, and + Jungfraujoch acquires it from the detector at full speed.

+

All three are in user operation at the MX beamlines of the Swiss Light Source SLS 2.0.

+ +

rugnux <diffraction image file>rugnux <diffraction image file> <CIF/PDB model file>

+
+
+ +
+
+ +
+

Data processing

+

Rugnux

+

Takes a macromolecular diffraction dataset, a synchrotron rotation sweep or XFEL serial stills, from the + images to merged data: spot finding, indexing, integration, scaling and merging, with the + space group, cell and resolution decided from the data and a report that says on what + evidence. Writes .mtz, .cif and .hkl for the programs + that come next. Given an atomic model it goes on to a structure: the model is placed + (as a rigid body or by molecular replacement) and refined, and the maps and the unexplained + difference-density blobs are written beside it. Validated on public data: + over 200 rotation datasets and + eleven XFEL serial datasets.

+

Linux · macOS · Windows · command line · fast on an NVIDIA GPU, works without one

+ +
+ +
+

Desktop application

+

Jungfraujoch Viewer

+

Shows what is in a dataset: every image with its spots, predictions and resolution rings, + per-image statistics over the sweep, grid-scan maps, and the same processing pipeline as + Rugnux, run from a settings panel on the open file. Follows a live collection from a running + Jungfraujoch broker.

+

Linux · macOS · Windows · Qt 6

+ +
+ +
+

Data acquisition

+

Jungfraujoch

+

The acquisition and real-time analysis system for the PSI JUNGFRAU and EIGER detectors, + and for DECTRIS detectors through their control unit: an FPGA and GPU pipeline that takes + the detector's frames at full rate, analyses them on the fly, streams them to the NXmx HDF5 + writer and serves a web interface and REST API to the beamline.

+

Linux servers · AMD Alveo U55C FPGA · NVIDIA GPUs

+ +
+ +
+
+ +
+
+

Download

+

Pre-built, signed where the platform asks for it, nothing to install beside them. +

+
+ +
+

Rugnux

+

One self-contained executable. Unpack the archive into a directory of its own and run + bin/rugnux; no CUDA toolkit, no Qt, no service. On a machine with an NVIDIA GPU + take the GPU build, which also runs without one. Details, packages and building from source.

+
+

Version 1.0.0-rc.186 · release notes · all releases

+
+

Linux

+GPU, CUDA 12rugnux-1.0.0-rc.186-linux-x86_64-cuda12.tgz +CPU onlyrugnux-1.0.0-rc.186-linux-x86_64-cpu.tgz +Arm 64, GPU, CUDA 13rugnux-1.0.0-rc.186-linux-aarch64-cuda13.tgz +

x86-64 with AVX2 (Intel Haswell / AMD Zen or newer), any distribution from RHEL 8 on. For the GPU: an NVIDIA driver, 525.60 or newer; no CUDA toolkit. Arm 64: NVIDIA GH200 and DGX Spark, glibc 2.39 or newer.

+

macOS

+Apple Siliconrugnux-1.0.0-rc.186-macos-arm64-cpu.tgz +

Apple Silicon (M1 or newer), macOS 13 Ventura or newer. CPU, with Bragg integration and molecular replacement on the Apple GPU; there is no CUDA on macOS. Intel Macs are not supported.

+

Windows

+GPU, CUDA 13rugnux-1.0.0-rc.186-win64-cuda13.zip +CPU onlyrugnux-1.0.0-rc.186-win64-cpu.zip +

64-bit Windows with AVX (built and verified on Windows 11). For the GPU: an NVIDIA R580 driver or newer; no CUDA toolkit. Unpack the archive and run bin\rugnux.exe.

+

+
+ +
+

Jungfraujoch Viewer

+

A desktop application with the Qt runtime included: a portable archive on Linux, a + notarized disk image on macOS, an installer on Windows. Details and building from source.

+
+

Version 1.0.0-rc.186 · release notes · all releases

+
+

Linux

+GPU, CUDA 12jfjoch_viewer-1.0.0-rc.186-linux-cuda12.tgz +CPU onlyjfjoch_viewer-1.0.0-rc.186-linux-cpu.tgz +

x86-64 with AVX2, any distribution from RHEL 8 on; a portable archive with the program, its desktop entry and icon. For the GPU: an NVIDIA driver, 525.60 or newer.

+

macOS

+Apple Siliconjfjoch-viewer-1.0.0-rc.186-macos-arm64.dmg +

Apple Silicon (M1 or newer), macOS 13 Ventura or newer. Signed and notarized disk image; drag the app to Applications. Intel Macs are not supported.

+

Windows

+GPU, CUDA 13jfjoch-viewer-1.0.0-rc.186-win64-cuda13.exe +CPU onlyjfjoch-viewer-1.0.0-rc.186-win64-cpu.exe +

64-bit Windows with AVX (built and verified on Windows 11). An installer with the Qt runtime included. For the GPU: an NVIDIA R580 driver or newer; no CUDA toolkit.

+

+
+ +
+

Jungfraujoch, the acquisition system

+

Installed on the beamline's Linux servers from the RPM and APT + repositories (jfjoch, jfjoch-writer, jfjoch-driver-dkms, + jfjoch-viewer, rugnux), with the FPGA firmware and the writer's + packages attached to every release. + Deployment is the step-by-step guide; Release contents says what each package needs on the machine.

+
+
+ +
+
+

Publications

+

The papers that describe the software, and the references to cite for it. All are open + access. All publications →

+
+ +
+ + + + + +
+
+ +
First page · CC BY 4.0
+
+
+

Jungfraujoch · live serial crystallography

+

Jungfraujoch: 38 GB s−1 real-time serial crystallography – data acquisition and live indexing feedback

+

J. Duan, H.-C. Stadler, J. Nan, Z. Matěj, G. Gotthard, F. Dworkowski, M. Bjelčić, O. Aurelius, + A. Mozzanica, S. Grimm, M. Burian, T. Ursby, M. Wang and F. Leonarski

+

J. Appl. Cryst. 59, 1668–1677 (2026) · + doi:10.1107/S1600576726008083

+

To cite as well for the 38 GB s−1 acquisition and the live + indexing feedback.

+
+
+ +
+
+ +
+

Free to use, in academia and industry

+

Rugnux, the viewer and the Jungfraujoch services are free software under the + GNU General Public License v3; the FPGA design is released under the + CERN Open Hardware Licence v2, strongly reciprocal. Both let + anyone use, study and modify the software and the hardware design at no charge, commercial use + included; modified versions that are distributed must be released under the same licence. The released binaries bundle third-party components under GPL-compatible licences, and the + CUDA builds the NVIDIA CUDA runtime under NVIDIA's EULA: see the + third-party notices.

+

The software builds on decades of developments in the crystallographic community (see the + acknowledgements), taken further in one GPU-accelerated program + whose automated decisions are validated against the diffraction data; it was developed with the + help of generative AI (Claude Opus, Anthropic).

+
+ +
+ + + + + + + diff --git a/landing.css b/landing.css new file mode 100644 index 000000000..88dd3156b --- /dev/null +++ b/landing.css @@ -0,0 +1 @@ +@charset "utf-8"; :root{--bg:#fbfbfd;--bg-raised:#fff;--bg-tint:#eef0fa;--fg:#1b1d2a;--fg-muted:#5b6072;--line:rgba(27,29,42,0.12);--primary:#3949ab;--primary-strong:#2c3a8f;--primary-soft:rgba(57,73,171,0.1);--on-primary:#fff;--accent:#e9a23b;--accent-soft:rgba(233,162,59,0.16);--shadow:0 1px 2px rgba(27,29,42,0.06),0 8px 24px rgba(27,29,42,0.06)}@media (prefers-color-scheme:dark){:root:not([data-theme=light]){--bg:#11131c;--bg-raised:#181b27;--bg-tint:#1d2130;--fg:#e8e9f1;--fg-muted:#9ea3b8;--line:rgba(232,233,241,0.12);--primary:#8e9dff;--primary-strong:#aab5ff;--primary-soft:rgba(142,157,255,0.14);--on-primary:#0d1030;--accent:#f0b65b;--accent-soft:rgba(240,182,91,0.16);--shadow:0 1px 2px rgba(0,0,0,0.4),0 8px 24px rgba(0,0,0,0.35)}}:root[data-theme=dark]{--bg:#11131c;--bg-raised:#181b27;--bg-tint:#1d2130;--fg:#e8e9f1;--fg-muted:#9ea3b8;--line:rgba(232,233,241,0.12);--primary:#8e9dff;--primary-strong:#aab5ff;--primary-soft:rgba(142,157,255,0.14);--on-primary:#0d1030;--accent:#f0b65b;--accent-soft:rgba(240,182,91,0.16);--shadow:0 1px 2px rgba(0,0,0,0.4),0 8px 24px rgba(0,0,0,0.35)}*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;-webkit-font-smoothing:antialiased}a{color:var(--primary);text-decoration:none}a:hover{color:var(--primary-strong);text-decoration:underline}code{font-family:"SFMono-Regular",Menlo,Consolas,"Roboto Mono",monospace;font-size:.92em;background:var(--primary-soft);padding:.1em .35em;border-radius:4px}h1,h2,h3{line-height:1.2;letter-spacing:-0.01em;margin:0}main>section,.top,.foot{max-width:1120px;margin:0 auto;padding:0 24px}.top{display:flex;align-items:center;gap:24px;padding-top:18px;padding-bottom:18px}.brand{display:inline-flex;align-items:center;gap:10px;color:var(--fg);font-weight:600;font-size:1.05em}.brand:hover{text-decoration:none}.brand img{display:block}.top__nav{display:flex;gap:22px;margin-left:auto;font-weight:500}.top__nav a{color:var(--fg-muted)}.top__nav a:hover{color:var(--primary);text-decoration:none}.theme-toggle{display:inline-flex;align-items:center;justify-content:center;width:38px;height:38px;border:1px solid var(--line);border-radius:50%;background:var(--bg-raised);color:var(--fg-muted);cursor:pointer}.theme-toggle:hover{color:var(--primary);border-color:var(--primary)}.psi-logo{display:inline-flex}.psi-logo img{display:block}:root[data-theme=dark] .psi-logo img{filter:invert(1)}@media (prefers-color-scheme:dark){:root:not([data-theme=light]) .psi-logo img{filter:invert(1)}}.theme-toggle__moon{display:none}:root[data-theme=dark] .theme-toggle__sun{display:none}:root[data-theme=dark] .theme-toggle__moon{display:block}@media (prefers-color-scheme:dark){:root:not([data-theme=light]) .theme-toggle__sun{display:none}:root:not([data-theme=light]) .theme-toggle__moon{display:block}}.hero{position:relative;display:grid;grid-template-columns:minmax(0,1fr) minmax(0,560px);align-items:center;gap:32px;padding-top:56px;padding-bottom:64px}.hero__art{grid-column:2;grid-row:1;width:100%;max-width:560px;justify-self:end;margin:0}.hero__art img{display:block;width:100%;height:auto}.hero__art .hero__art-dark{display:none}:root[data-theme=dark] .hero__art .hero__art-light{display:none}:root[data-theme=dark] .hero__art .hero__art-dark{display:block}@media (prefers-color-scheme:dark){:root:not([data-theme=light]) .hero__art .hero__art-light{display:none}:root:not([data-theme=light]) .hero__art .hero__art-dark{display:block}}.hero__art figcaption{margin-top:10px;font-size:.78em;color:var(--fg-muted);text-align:right}.hero__text{grid-column:1;grid-row:1;max-width:600px}.eyebrow{margin:0 0 14px;font-size:.78em;font-weight:700;letter-spacing:.1em;text-transform:uppercase;color:var(--primary)}.hero h1{font-size:clamp(2.1rem,4.6vw,3.4rem);font-weight:700;letter-spacing:-0.025em;margin-bottom:18px}.lede{font-size:1.2em;color:var(--fg-muted);margin:0 0 14px}.hero__ops{color:var(--fg-muted);margin:0 0 26px}.lede strong{color:var(--fg);font-weight:600}.hero__actions{display:flex;flex-wrap:wrap;gap:12px;margin-bottom:26px}.btn{display:inline-block;padding:11px 20px;border-radius:8px;font-weight:600;border:1px solid transparent;transition:transform .12s,box-shadow .12s,background .12s}.btn:hover{text-decoration:none;transform:translateY(-1px)}.btn--primary{background:var(--primary);color:var(--on-primary);box-shadow:var(--shadow)}.btn--primary:hover{background:var(--primary-strong);color:var(--on-primary)}.btn--ghost{border-color:var(--line);color:var(--fg);background:var(--bg-raised)}.btn--ghost:hover{border-color:var(--primary);color:var(--primary)}.hero__run{display:flex;flex-direction:column;align-items:flex-start;gap:8px;margin:0;font-size:.95em}.hero__run code{font-size:1em;padding:.35em .7em;max-width:100%;overflow-wrap:anywhere}.programs{padding-bottom:56px}.programs__grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:20px}.program{display:flex;flex-direction:column;padding:24px 24px 20px;border:1px solid var(--line);border-radius:14px;background:var(--bg-raised);box-shadow:var(--shadow)}.program__kicker{margin:0 0 8px;font-size:.74em;font-weight:700;letter-spacing:.1em;text-transform:uppercase;color:var(--primary)}.program h2{font-size:1.45em;font-weight:650;margin-bottom:12px}.program>p:not([class]){margin:0 0 14px;color:var(--fg);flex:1 1 auto}.program__meta{margin:0 0 14px;font-size:.82em;color:var(--fg-muted)}.program__links{margin:0;padding-top:14px;border-top:1px solid var(--line);display:flex;flex-wrap:wrap;gap:6px 18px;font-weight:500}.program__links a:first-child{font-weight:700}.download{padding-top:48px;padding-bottom:24px;border-top:1px solid var(--line)}.download__head{max-width:640px;margin-bottom:28px}.download__head h2{font-size:2em;font-weight:700;margin-bottom:10px}.download__head p{margin:0;color:var(--fg-muted);font-size:1.05em}.download__head [data-os-note]:not(:empty){color:var(--fg);font-weight:500}.download__program{margin-bottom:36px}.download__program h3{font-size:1.3em;font-weight:650;margin-bottom:8px}.download__program>p{margin:0 0 16px;max-width:720px;color:var(--fg-muted)}.download__program--text>p{color:var(--fg)}.jfj-dl__release{margin:0 0 14px;font-size:.95em;color:var(--fg-muted)}.jfj-dl__release strong{color:var(--fg)}.jfj-dl__grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(250px,1fr));gap:16px}.jfj-dl__card{position:relative;padding:18px 18px 8px;border:1px solid var(--line);border-radius:12px;background:var(--bg-raised)}.jfj-dl__card.is-yours{border-color:var(--accent);box-shadow:0 0 0 3px var(--accent-soft),var(--shadow)}.jfj-dl__card.is-yours::after{content:"Your system";position:absolute;top:-11px;right:14px;padding:2px 10px;border-radius:999px;background:var(--accent);color:#1b1d2a;font-size:.72em;font-weight:700;letter-spacing:.04em}.jfj-dl__platform{font-size:1.1em;font-weight:650;margin-bottom:12px}a.jfj-dl__btn{display:block;margin-bottom:10px;padding:10px 14px;border:1px solid var(--primary);border-radius:8px;background:var(--primary);color:var(--on-primary);font-weight:600;line-height:1.3;transition:background .12s,box-shadow .12s}a.jfj-dl__btn:hover{text-decoration:none;background:var(--primary-strong);box-shadow:var(--shadow);color:var(--on-primary)}a.jfj-dl__btn--secondary{background:transparent;color:var(--primary)}a.jfj-dl__btn--secondary:hover{background:var(--primary-soft);color:var(--primary-strong)}a.jfj-dl__btn--missing,a.jfj-dl__btn--missing:hover{background:transparent;border-style:dashed;border-color:var(--line);color:var(--fg-muted);box-shadow:none;cursor:default}.jfj-dl__file{display:block;margin-top:2px;font-family:"SFMono-Regular",Menlo,Consolas,"Roboto Mono",monospace;font-size:.74em;font-weight:400;opacity:.85;word-break:break-all}.jfj-dl__req{margin:6px 0 8px;font-size:.82em;line-height:1.45;color:var(--fg-muted)}.jfj-dl__note{margin:10px 0 0;font-size:.82em;color:var(--fg-muted)}.jfj-dl__note:empty{display:none}.papers{padding-top:48px;padding-bottom:48px;border-top:1px solid var(--line)}.papers__head{max-width:640px;margin-bottom:28px}.papers__head h2{font-size:2em;font-weight:700;margin-bottom:10px}.papers__head p{margin:0;color:var(--fg-muted);font-size:1.05em}.papers__all{font-weight:600;white-space:nowrap}.papers__grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,300px),1fr));gap:20px}.paper{display:grid;grid-template-columns:minmax(0,1fr);align-content:start;gap:20px;padding:22px;border:1px solid var(--line);border-radius:14px;background:var(--bg-raised);box-shadow:var(--shadow)}.paper__page{margin:0;width:200px}.paper__page>a{display:block;transition:transform .12s}.paper__page>a:hover{transform:translateY(-2px)}.paper__page img{display:block;width:100%;height:auto;aspect-ratio:200 / 261;object-fit:contain;background:#fff;border:1px solid var(--line);border-radius:3px;box-shadow:var(--shadow)}.paper__page figcaption{margin-top:6px;font-size:.72em;color:var(--fg-muted)}.paper__text{min-width:0}.paper__kicker{margin:0 0 8px;font-size:.74em;font-weight:700;letter-spacing:.1em;text-transform:uppercase;color:var(--primary)}.paper h3{font-size:1.2em;font-weight:650;margin-bottom:10px}.paper h3 a{color:var(--fg)}.paper h3 a:hover{color:var(--primary)}.paper h3 sup,.paper__cite sup{font-size:.7em;line-height:0}.paper__authors{margin:0 0 6px;font-size:.92em}.paper__venue{margin:0 0 12px;font-size:.92em;color:var(--fg-muted)}.paper__venue a{overflow-wrap:anywhere}.paper__cite{margin:0;padding-top:12px;border-top:1px solid var(--line);font-size:.85em;color:var(--fg-muted)}.licence{padding-top:40px;padding-bottom:48px;border-top:1px solid var(--line)}.licence h2{font-size:1.5em;font-weight:650;margin-bottom:12px}.licence p{margin:0 0 12px;max-width:760px;color:var(--fg-muted)}.foot{padding-top:24px;padding-bottom:40px;border-top:1px solid var(--line);font-size:.88em;color:var(--fg-muted)}.foot p{margin:0 0 6px}@media (max-width:760px){body{font-size:15px}.top{gap:14px;flex-wrap:wrap}.top__nav{gap:8px 14px;flex-wrap:wrap;margin-left:0;order:3;width:100%;font-size:.95em}.theme-toggle{margin-left:auto}.hero{grid-template-columns:1fr;padding-top:28px;padding-bottom:40px}.hero__art{grid-column:1;grid-row:1;max-width:360px;justify-self:center}.hero__art figcaption{text-align:center}.hero__text{grid-row:2}.programs__grid{grid-template-columns:1fr}}@media (max-width:520px){.paper{gap:18px;padding:18px}.paper__page{width:180px}} \ No newline at end of file diff --git a/landing.js b/landing.js new file mode 100644 index 000000000..ba94b5979 --- /dev/null +++ b/landing.js @@ -0,0 +1,29 @@ +// The front page: theme toggle and the download section's +// "your system" highlight. The download buttons themselves are repointed at the newest release by +// _static/jfjoch_downloads.js, shared with the Sphinx download pages. +(function () { + // ---- theme: follows the system until the toggle is used, then remembered ----------------- + var root = document.documentElement; + var toggle = document.querySelector(".theme-toggle"); + function isDark() { + var set = root.getAttribute("data-theme"); + if (set) return set === "dark"; + return window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches; + } + if (toggle) toggle.addEventListener("click", function () { + var next = isDark() ? "light" : "dark"; + root.setAttribute("data-theme", next); + try { localStorage.setItem("jfj-theme", next); } catch (e) {} + }); + + // ---- "your system": highlight the platform the browser runs on ---------------------------- + var ua = navigator.userAgent || "", platform = navigator.platform || ""; + var os = /Windows/.test(ua) ? "windows" : /Mac/.test(platform) || /Macintosh/.test(ua) ? "macos" : + /Linux|X11/.test(platform + ua) && !/Android/.test(ua) ? "linux" : null; + if (os) { + document.querySelectorAll('.jfj-dl__card[data-platform="' + os + '"]').forEach(function (c) { c.classList.add("is-yours"); }); + var note = document.querySelector("[data-os-note]"); + var names = { windows: "Windows", macos: "macOS", linux: "Linux" }; + if (note) note.textContent = "The " + names[os] + " builds are marked for you."; + } +})(); diff --git a/objects.inv b/objects.inv new file mode 100644 index 000000000..6ef99feca Binary files /dev/null and b/objects.inv differ diff --git a/paper_jac.webp b/paper_jac.webp new file mode 100644 index 000000000..e334dcff3 Binary files /dev/null and b/paper_jac.webp differ diff --git a/paper_jsr.webp b/paper_jsr.webp new file mode 100644 index 000000000..132c2ce00 Binary files /dev/null and b/paper_jsr.webp differ diff --git a/paper_rugnux_fig.webp b/paper_rugnux_fig.webp new file mode 100644 index 000000000..4b24f4415 Binary files /dev/null and b/paper_rugnux_fig.webp differ diff --git a/psi.png b/psi.png new file mode 100644 index 000000000..49bbde890 Binary files /dev/null and b/psi.png differ diff --git a/python_client/README.html b/python_client/README.html new file mode 100644 index 000000000..a6ebb9de6 --- /dev/null +++ b/python_client/README.html @@ -0,0 +1,29 @@ + jfjoch-client — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

jfjoch-client

API to control Jungfraujoch developed by the Paul Scherrer Institute (Switzerland). Jungfraujoch is a data acquisition and analysis system for pixel array detectors, primarly PSI JUNGFRAU. Jungfraujoch uses FPGA boards to acquire data at high data rates.

License Clarification

While this API definition is licensed under GPL-3.0, the GPL copyleft provisions do not apply when this file is used solely to generate OpenAPI clients or when implementing applications that interact with the API. Generated client code and applications using this API definition are not subject to the GPL license requirements and may be distributed under terms of your choosing.

This exception is similar in spirit to the Linux Kernel’s approach to userspace API headers and the GCC Runtime Library Exception. The Linux Kernel developers have explicitly stated that user programs that merely use the kernel interfaces (syscalls, ioctl definitions, etc.) are not derivative works of the kernel and are not subject to the terms of the GPL.

This exception is intended to allow wider use of this API specification without imposing GPL requirements on applications that merely interact with the API, regardless of whether they communicate through network calls or other mechanisms.

This Python package is automatically generated by the OpenAPI Generator project:

  • API version: 1.0.0-rc.186

  • Package version: 1.0.0-rc.186

  • Generator version: 7.20.0

  • Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements.

Python 3.9+

Installation & Usage

pip install

If the python package is hosted on a repository, you can install directly using:

pip install git+https://gitea.psi.ch/mx/jungfraujoch.git
+

(you may need to run pip with root permission: sudo pip install git+https://gitea.psi.ch/mx/jungfraujoch.git)

Then import the package:

import jfjoch_client
+

Setuptools

Install via Setuptools.

python setup.py install --user
+

(or sudo python setup.py install to install the package for all users)

Then import the package:

import jfjoch_client
+

Tests

Execute pytest to run the tests.

Getting Started

Please follow the installation procedure and then run the following:


+import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Cancel running data collection
+        api_instance.cancel_post()
+    except ApiException as e:
+        print("Exception when calling DefaultApi->cancel_post: %s\n" % e)
+
+

Documentation for API Endpoints

All URIs are relative to http://localhost:5232

Class

Method

HTTP request

Description

DefaultApi

cancel_post

POST /cancel

Cancel running data collection

DefaultApi

config_azim_int_get

GET /config/azim_int

Get azimuthal integration configuration

DefaultApi

config_azim_int_put

PUT /config/azim_int

Configure azimuthal integration

DefaultApi

config_bragg_integration_get

GET /config/bragg_integration

Get Bragg integration configuration

DefaultApi

config_bragg_integration_put

PUT /config/bragg_integration

Change Bragg integration settings

DefaultApi

config_dark_mask_get

GET /config/dark_mask

Get settings for dark data collection to calculate mask

DefaultApi

config_dark_mask_put

PUT /config/dark_mask

Set configuration for dark data collection to calculate mask

DefaultApi

config_detector_get

GET /config/detector

Get detector configuration

DefaultApi

config_detector_put

PUT /config/detector

Change detector configuration

DefaultApi

config_file_writer_get

GET /config/file_writer

Get file writer settings

DefaultApi

config_file_writer_put

PUT /config/file_writer

Change file writer settings

DefaultApi

config_image_format_conversion_post

POST /config/image_format/conversion

Configure format for data collection with full conversion

DefaultApi

config_image_format_get

GET /config/image_format

Get image output format

DefaultApi

config_image_format_put

PUT /config/image_format

Change image output format

DefaultApi

config_image_format_raw_post

POST /config/image_format/raw

Configure format for raw data collection

DefaultApi

config_indexing_get

GET /config/indexing

Get indexing configuration

DefaultApi

config_indexing_put

PUT /config/indexing

Change indexing algorithm settings

DefaultApi

config_instrument_get

GET /config/instrument

Get instrument metadata

DefaultApi

config_instrument_put

PUT /config/instrument

Change instrument metadata

DefaultApi

config_internal_generator_image_put

PUT /config/internal_generator_image

Load binary image for internal FPGA generator

DefaultApi

config_internal_generator_image_tiff_put

PUT /config/internal_generator_image.tiff

Load TIFF image for internal FPGA generator

DefaultApi

config_mask_get

GET /config/mask

Get mask of the detector (binary)

DefaultApi

config_mask_tiff_get

GET /config/mask.tiff

Get mask of the detector (TIFF)

DefaultApi

config_roi_get

GET /config/roi

Get ROI definitions

DefaultApi

config_roi_put

PUT /config/roi

Upload ROI definitions

DefaultApi

config_rugnux_get

GET /config/rugnux

Get rugnux live mode settings and model status

DefaultApi

config_rugnux_model_delete

DELETE /config/rugnux/model

Remove the model used by rugnux live mode

DefaultApi

config_rugnux_model_put

PUT /config/rugnux/model

Upload the model used by rugnux live mode

DefaultApi

config_rugnux_put

PUT /config/rugnux

Change rugnux live mode settings

DefaultApi

config_select_detector_get

GET /config/select_detector

List available detectors

DefaultApi

config_select_detector_put

PUT /config/select_detector

Select detector

DefaultApi

config_spot_finding_get

GET /config/spot_finding

Get data processing configuration

DefaultApi

config_spot_finding_put

PUT /config/spot_finding

Configure spot finding

DefaultApi

config_user_mask_get

GET /config/user_mask

Detector must be Initialized. Get user mask of the detector (binary)

DefaultApi

config_user_mask_put

PUT /config/user_mask

Upload user mask of the detector (binary)

DefaultApi

config_user_mask_tiff_get

GET /config/user_mask.tiff

Detector must be Initialized. Get user mask of the detector (TIFF)

DefaultApi

config_user_mask_tiff_put

PUT /config/user_mask.tiff

Upload user mask of the detector

DefaultApi

config_zeromq_metadata_get

GET /config/zeromq_metadata

Get ZeroMQ metadata socket settings

DefaultApi

config_zeromq_metadata_put

PUT /config/zeromq_metadata

Set ZeroMQ metadata settings

DefaultApi

config_zeromq_preview_get

GET /config/zeromq_preview

Get ZeroMQ preview settings

DefaultApi

config_zeromq_preview_put

PUT /config/zeromq_preview

Set ZeroMQ preview settings

DefaultApi

deactivate_post

POST /deactivate

Prepare detector to turn off

DefaultApi

detector_status_get

GET /detector/status

Get detector status

DefaultApi

fpga_status_get

GET /fpga_status

Get status of FPGA devices

DefaultApi

image_buffer_clear_post

POST /image_buffer/clear

Clear image buffer

DefaultApi

image_buffer_image_cbor_get

GET /image_buffer/image.cbor

Get image message in CBOR format

DefaultApi

image_buffer_image_jpeg_get

GET /image_buffer/image.jpeg

Get preview image in JPEG format using custom settings

DefaultApi

image_buffer_image_tiff_get

GET /image_buffer/image.tiff

Get preview image in TIFF format

DefaultApi

image_buffer_start_cbor_get

GET /image_buffer/start.cbor

Get Start message in CBOR format

DefaultApi

image_buffer_status_get

GET /image_buffer/status

Get status of the image buffers

DefaultApi

image_pusher_status_get

GET /image_pusher/status

Get status of image pusher

DefaultApi

initialize_post

POST /initialize

Initialize detector and data acquisition

DefaultApi

live_events_get

GET /live/events

Event stream of the collection, for a reader following it

DefaultApi

pedestal_post

POST /pedestal

Collect dark current for the detector

DefaultApi

preview_pedestal_tiff_get

GET /preview/pedestal.tiff

Get pedestal in TIFF format

DefaultApi

preview_plot_bin_get

GET /preview/plot.bin

Generate 1D plot from Jungfraujoch and send in raw binary format. Data are provided as (32-bit) float binary array. This format doesn’t transmit information about X-axis, only values, so it is of limited use for azimuthal integration.

DefaultApi

preview_plot_get

GET /preview/plot

Generate 1D plot from Jungfraujoch

DefaultApi

result_scan_get

GET /result/scan

Get full scan result

DefaultApi

rugnux_clear_post

POST /rugnux/clear

Clear the live rugnux result of the last collection

DefaultApi

rugnux_map_ccp4_get

GET /rugnux/map.ccp4

Get an electron-density map of the last rugnux live run

DefaultApi

rugnux_model_cif_get

GET /rugnux/model.cif

Get the model as placed by the last rugnux live run

DefaultApi

rugnux_status_get

GET /rugnux/status

Get live rugnux processing status of the last collection

DefaultApi

start_post

POST /start

Start detector

DefaultApi

statistics_calibration_get

GET /statistics/calibration

Get calibration statistics

DefaultApi

statistics_data_collection_get

GET /statistics/data_collection

Get data collection statistics

DefaultApi

statistics_get

GET /statistics

Get general statistics

DefaultApi

status_get

GET /status

Get Jungfraujoch status

DefaultApi

trigger_post

POST /trigger

Send soft trigger to the detector

DefaultApi

version_get

GET /version

Get Jungfraujoch version of jfjoch_broker

DefaultApi

wait_till_done_post

POST /wait_till_done

Wait for acquisition done

DefaultApi

wait_until_running_post

POST /wait_until_running

Wait for acquisition running

DefaultApi

xfel_event_code_get

GET /xfel/event_code

Return XFEL event codes for the current data acquisition

DefaultApi

xfel_pulse_id_get

GET /xfel/pulse_id

Return XFEL pulse IDs for the current data acquisition

Documentation For Models

Documentation For Authorization

Authentication schemes defined for the API:

bearerAuth

  • Type: Bearer authentication

Author

filip.leonarski@psi.ch

\ No newline at end of file diff --git a/python_client/docs/AzimIntSettings.html b/python_client/docs/AzimIntSettings.html new file mode 100644 index 000000000..adaccecbc --- /dev/null +++ b/python_client/docs/AzimIntSettings.html @@ -0,0 +1,14 @@ + AzimIntSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

AzimIntSettings

Properties

Name

Type

Description

Notes

polarization_corr

bool

Apply polarization correction for azimuthal integration (polarization factor must be configured in dataset settings)

[default to True]

solid_angle_corr

bool

Apply solid angle correction for azimuthal integration

[default to True]

high_q_recip_a

float

Upper q limit of the azimuthal integration [1/Angstrom]. Optional: if omitted, the integration (and the adaptive spot detection that shares these q bins) extends to the highest q the detector reaches.

[optional]

low_q_recip_a

float

q_spacing

float

Width of a Q bin [1/Angstrom], for linear binning only. Linear binning takes either this or `q_bins`, not both; with neither, the spacing is 0.01 1/Angstrom.

[optional]

q_bins

int

Number of Q bins between low and high Q. Required for `log10` binning; for `linear` binning an alternative to `q_spacing`.

[optional]

q_binning

QBinning

[optional] [default to QBinning.LINEAR]

azimuthal_bins

int

Numer of azimuthal (phi) bins; 1 = standard 1D azimuthal integration

[optional] [default to 1]

force_cpu

bool

Force CPU processing of azimuthal integration in the FPGA data acquisition workflow. This allows to extend number of azimuthal integration bins, as well as to calculate standard deviation of the azimuthal integration results.

[optional] [default to False]

Example

from jfjoch_client.models.azim_int_settings import AzimIntSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of AzimIntSettings from a JSON string
+azim_int_settings_instance = AzimIntSettings.from_json(json)
+# print the JSON string representation of the object
+print(AzimIntSettings.to_json())
+
+# convert the object into a dict
+azim_int_settings_dict = azim_int_settings_instance.to_dict()
+# create an instance of AzimIntSettings from a dict
+azim_int_settings_from_dict = AzimIntSettings.from_dict(azim_int_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/BraggIntegrationSettings.html b/python_client/docs/BraggIntegrationSettings.html new file mode 100644 index 000000000..598367f48 --- /dev/null +++ b/python_client/docs/BraggIntegrationSettings.html @@ -0,0 +1,14 @@ + BraggIntegrationSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

BraggIntegrationSettings

Settings for Bragg spot integration, used by rugnux live (the Lite and FPGA workflows do not integrate)

Properties

Name

Type

Description

Notes

integration_model

IntegrationModel

[default to IntegrationModel.PROFILEGAUSSIAN]

max_hkl

int

How far the Bragg predictor walks the lattice: reflections with

h

Example

from jfjoch_client.models.bragg_integration_settings import BraggIntegrationSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of BraggIntegrationSettings from a JSON string
+bragg_integration_settings_instance = BraggIntegrationSettings.from_json(json)
+# print the JSON string representation of the object
+print(BraggIntegrationSettings.to_json())
+
+# convert the object into a dict
+bragg_integration_settings_dict = bragg_integration_settings_instance.to_dict()
+# create an instance of BraggIntegrationSettings from a dict
+bragg_integration_settings_from_dict = BraggIntegrationSettings.from_dict(bragg_integration_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/BrokerStatus.html b/python_client/docs/BrokerStatus.html new file mode 100644 index 000000000..5f0764800 --- /dev/null +++ b/python_client/docs/BrokerStatus.html @@ -0,0 +1,14 @@ + BrokerStatus — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

BrokerStatus

Properties

Name

Type

Description

Notes

state

str

progress

float

Progress of data collection (only available if receiving is running)

[optional]

message

str

Message to display besides state of the jfjoch_broker; mostly used for errors and warnings This matters especially for async functions (start/initialize), where API won’t return reason for the error during async operation.

[optional]

message_severity

str

Level of the message to display

[optional] [default to ‘error’]

gpu_count

int

Number of installed GPUs

[optional]

broker_version

str

Version of the jfjoch_broker

[optional]

Example

from jfjoch_client.models.broker_status import BrokerStatus
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of BrokerStatus from a JSON string
+broker_status_instance = BrokerStatus.from_json(json)
+# print the JSON string representation of the object
+print(BrokerStatus.to_json())
+
+# convert the object into a dict
+broker_status_dict = broker_status_instance.to_dict()
+# create an instance of BrokerStatus from a dict
+broker_status_from_dict = BrokerStatus.from_dict(broker_status_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/CalibrationStatisticsInner.html b/python_client/docs/CalibrationStatisticsInner.html new file mode 100644 index 000000000..1e86e6d06 --- /dev/null +++ b/python_client/docs/CalibrationStatisticsInner.html @@ -0,0 +1,14 @@ + CalibrationStatisticsInner — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

CalibrationStatisticsInner

Properties

Name

Type

Description

Notes

module_number

int

storage_cell_number

int

pedestal_g0_mean

float

pedestal_g1_mean

float

pedestal_g2_mean

float

gain_g0_mean

float

gain_g1_mean

float

gain_g2_mean

float

masked_pixels

int

Example

from jfjoch_client.models.calibration_statistics_inner import CalibrationStatisticsInner
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of CalibrationStatisticsInner from a JSON string
+calibration_statistics_inner_instance = CalibrationStatisticsInner.from_json(json)
+# print the JSON string representation of the object
+print(CalibrationStatisticsInner.to_json())
+
+# convert the object into a dict
+calibration_statistics_inner_dict = calibration_statistics_inner_instance.to_dict()
+# create an instance of CalibrationStatisticsInner from a dict
+calibration_statistics_inner_from_dict = CalibrationStatisticsInner.from_dict(calibration_statistics_inner_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DarkMaskSettings.html b/python_client/docs/DarkMaskSettings.html new file mode 100644 index 000000000..81b4f61e3 --- /dev/null +++ b/python_client/docs/DarkMaskSettings.html @@ -0,0 +1,14 @@ + DarkMaskSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DarkMaskSettings

Settings for collection of dark images to be used for mask calculation

Properties

Name

Type

Description

Notes

detector_threshold_ke_v

float

Energy threshold for dark image collection

[default to 3.5]

frame_time_us

int

Time between frames for dark image collection

[default to 10000]

number_of_frames

int

Number of frames for dark image collection; zero means no dark collection

[default to 1000]

max_allowed_pixel_count

int

Maximum count in a pixel considered normal (not-masked)

[default to 1]

max_frames_with_signal

int

Maximum number of frames with signal in a pixel considered normal (not-masked)

[default to 10]

Example

from jfjoch_client.models.dark_mask_settings import DarkMaskSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DarkMaskSettings from a JSON string
+dark_mask_settings_instance = DarkMaskSettings.from_json(json)
+# print the JSON string representation of the object
+print(DarkMaskSettings.to_json())
+
+# convert the object into a dict
+dark_mask_settings_dict = dark_mask_settings_instance.to_dict()
+# create an instance of DarkMaskSettings from a dict
+dark_mask_settings_from_dict = DarkMaskSettings.from_dict(dark_mask_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DatasetSettings.html b/python_client/docs/DatasetSettings.html new file mode 100644 index 000000000..3a10483c2 --- /dev/null +++ b/python_client/docs/DatasetSettings.html @@ -0,0 +1,14 @@ + DatasetSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DatasetSettings

Properties

Name

Type

Description

Notes

images_per_trigger

int

For standard synchrotron data collection - this is number of images collected per one TTL trigger For XFEL (pulsed source) - this number is ignored and set to 1 For storage cell mode - this number is ignored and set to number of storage cells

[optional] [default to 1]

ntrigger

int

Number of TTL trigger that the detector is expected to receive during data collection

[optional] [default to 1]

image_time_us

int

Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved.

[optional]

beam_x_pxl

float

/entry/detector/beam_center_x in NXmx Beam center in X direction [pixels]

beam_y_pxl

float

/entry/detector/beam_center_y in NXmx Beam center in X direction [pixels]

detector_distance_mm

float

/entry/detector/distance in NXmx Detector distance [mm]

incident_energy_ke_v

float

Used to calculate /entry/beam/incident_wavelength in NXmx Incident particle (photon, electron) energy in keV

file_prefix

str

Prefix for filenames. If left empty, no file will be saved.

[optional] [default to ‘’]

images_per_file

int

Number of images in a single HDF5 data file, taken literally when given. If omitted, it is chosen from the acquisition: a rotation sweep of at most 20000 images goes into a single data file, so the dataset stays readable by programs that follow only the first data file of a legacy master; a grid scan is split on a whole number of fast-axis rows; anything else (stills, serial) uses 1000.

[optional]

space_group_number

int

Number of space group for the crystal. Currently used solely as metadata, not relevant for image processing done in Jungfraujoch.

[optional]

sample_name

str

/entry/sample/name in NXmx Sample name

[optional] [default to ‘’]

compression

str

Compression type for the images transferred over ZeroMQ and saved to HDF5 file.

[optional] [default to ‘bslz4’]

total_flux

float

/entry/beam/total_flux in NXmx Flux incident on beam plane in photons per second. In other words this is the flux integrated over area. [photons/s]

[optional]

transmission

float

/entry/instrument/attenuator/attenuator_transmission Transmission of attenuator (filter) [no units]

[optional]

beam_size_x_um

float

First element of /entry/instrument/beam/incident_beam_size in NXmx Horizontal size of the X-ray beam where it meets the sample - the FWHM of a focused beam, the full width of a slit-defined one. [um]

[optional]

beam_size_y_um

float

Second element of /entry/instrument/beam/incident_beam_size in NXmx Vertical size of the X-ray beam where it meets the sample. [um]

[optional]

goniometer

RotationAxis

[optional]

grid_scan

GridScan

[optional]

header_appendix

object

Header appendix, added as user_data/user to start ZeroMQ message (can be any valid JSON) In general, it is not saved in HDF5 file. However, if values are placed in &quot;hdf5&quot; object, `jfjoch_writer` will write them in /entry/user of the HDF5 file. This applies solely to string and number (double floating-point). No arrays/sub-objects is allowed. For example {&quot;hdf5&quot;: {&quot;val1&quot;:1, &quot;val2&quot;:&quot;xyz&quot;}}, will write /entry/user/val1 and /entry/user/val2.

[optional]

image_appendix

object

Image appendix, added as user_data to image ZeroMQ message (can be any valid JSON) Not saved in HDF5 file

[optional]

data_reduction_factor_serialmx

float

Rate at which non-indexed images are accepted to be forwarded to writer. Value of 1.0 (default) means that all images are written. Values below zero mean that non-indexed images will be accepted with a given probability.

[optional] [default to 1.0]

pixel_value_low_threshold

int

Set all counts lower than the value to zero. When the value is set, negative numbers other than error pixel value are always set to zero. Setting to zero is equivalent to turning the option off.

[optional]

run_number

int

Number of run within an experimental session. Transferred over CBOR stream as &quot;series ID&quot;, though not saved in HDF5 file. It is highly recommended to keep this number unique for each data collection during experimental series. If not provided, the number will be automatically incremented.

[optional]

run_name

str

Unique ID of run. Transferred over CBOR stream as &quot;unique series ID&quot;, though not saved in HDF5 file. It is highly recommended to keep this name unique for each data collection during experimental series. If not provided, the name will be automatically generated as number + colon + file_prefix.

[optional]

experiment_group

str

Name of group owning the data (e.g. p-group or proposal number). Transferred over CBOR stream, though not saved in HDF5 file.

[optional]

poisson_compression

int

Enable lossy compression of pixel values that preserves Poisson statistics. Requires to provide a numerical factor SQ. Pixel value P will be transformed to round(sqrt(P) * SQ), with rounding to the closest integer. Compression is turned off if the value is missing or it is set to zero.

[optional]

write_nxmx_hdf5_master

bool

Write NXmx formatted HDF5 master file. Recommended to use for macromolecular crystallography experiments and to turn off for other experiments.

[optional] [default to True]

save_calibration

bool

Forward image calibration (at the moment pedestal and pedestal RMS for JUNGFRAU) using the ZeroMQ stream to writer. If parameter is not provided calibration will be saved only if more than 4 images are recorded.

[optional]

polarization_factor

float

Polarization factor for integration; 1.0 is horizontal polarization; -1.0 is vertical polarization

[optional]

ring_current_m_a

float

Ring current at the beginning of the data collection

[optional]

sample_temperature_k

float

Sample temperature in Kelvin

[optional]

poni_rot1_rad

float

PONI angle rot1 (see PyFAI documentation for details) in radians

[optional] [default to 0.0]

poni_rot2_rad

float

PONI angle rot2 (see PyFAI documentation for details) in radians

[optional] [default to 0.0]

poni_rot3_rad

float

PONI angle rot3 (see PyFAI documentation for details) in radians

[optional] [default to 0.0]

unit_cell

UnitCell

[optional]

spot_finding

bool

Enable spot finding and save spots

[optional] [default to True]

smargon

DatasetSettingsSmargon

[optional]

max_spot_count

int

Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected

[optional] [default to 250]

detect_ice_rings

bool

Flag spots as ice rings and reduce their effect on indexing. Left out, the broker’s own spot finding treats no spot as an ice ring, rugnux live decides as a bare `rugnux` would (on for a rotation sweep, off for stills), and the master file carries no `detect_ice_rings`.

[optional]

async_start

bool

When set to true, `/start` will not wait for detector and Jungfraujoch to be ready for the measurement.

[optional] [default to False]

module_placement

List[DetectorModulePlacement]

Where the detector’s modules lie for this dataset, as rugnux measures them: rugnux writes `<prefix>_module_placement.json`, which holds exactly this field, to be merged into the dataset settings. Each entry names its module by its readout pixel 0 and readout axes in the stored image (`x0`, `y0`, `fast_axis`, `slow_axis`, after `mirror_y`; see `detector_module_placement`), in any order; every module must be named once, and only modules of the detector, else `/start` fails with 400. The image is assembled as configured (`custom_geometry`); the placement goes into the start message and the NXmx `module_NN` groups, and the analysis takes it. Omitted or empty: modules as assembled.

[optional]

tokens

List[str]

Bearer tokens that protect this dataset: any number, all equivalent (e.g. a beamline secret and a dataset-specific user secret). While set, the endpoints marked with the `bearerAuth` security scheme require `Authorization: Bearer <token>` and answer 401 otherwise. Every accepted `/start` replaces the previous dataset’s tokens; omitted or empty means no protection. Never returned by any endpoint.

[optional]

xray_fluorescence_spectrum

DatasetSettingsXrayFluorescenceSpectrum

[optional]

Example

from jfjoch_client.models.dataset_settings import DatasetSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DatasetSettings from a JSON string
+dataset_settings_instance = DatasetSettings.from_json(json)
+# print the JSON string representation of the object
+print(DatasetSettings.to_json())
+
+# convert the object into a dict
+dataset_settings_dict = dataset_settings_instance.to_dict()
+# create an instance of DatasetSettings from a dict
+dataset_settings_from_dict = DatasetSettings.from_dict(dataset_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DatasetSettingsSmargon.html b/python_client/docs/DatasetSettingsSmargon.html new file mode 100644 index 000000000..1c0adba2a --- /dev/null +++ b/python_client/docs/DatasetSettingsSmargon.html @@ -0,0 +1,14 @@ + DatasetSettingsSmargon — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DatasetSettingsSmargon

Geometry of Smargon goniometer at SLS 2.0 / MX beamlines. Assuming that Smargon is used as static positioner and not moving during the scan, allowing to reconstruct geometry.

Properties

Name

Type

Description

Notes

phi_deg

float

Phi angle in degrees

chi_deg

float

Chi angle in degrees

phi_axis

List[float]

Phi rotation axis

[optional] [default to [1,0,0]]

chi_axis

List[float]

Chi rotation axis

[optional] [default to [0,0,1]]

Example

from jfjoch_client.models.dataset_settings_smargon import DatasetSettingsSmargon
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DatasetSettingsSmargon from a JSON string
+dataset_settings_smargon_instance = DatasetSettingsSmargon.from_json(json)
+# print the JSON string representation of the object
+print(DatasetSettingsSmargon.to_json())
+
+# convert the object into a dict
+dataset_settings_smargon_dict = dataset_settings_smargon_instance.to_dict()
+# create an instance of DatasetSettingsSmargon from a dict
+dataset_settings_smargon_from_dict = DatasetSettingsSmargon.from_dict(dataset_settings_smargon_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DatasetSettingsXrayFluorescenceSpectrum.html b/python_client/docs/DatasetSettingsXrayFluorescenceSpectrum.html new file mode 100644 index 000000000..b5f0800b0 --- /dev/null +++ b/python_client/docs/DatasetSettingsXrayFluorescenceSpectrum.html @@ -0,0 +1,14 @@ + DatasetSettingsXrayFluorescenceSpectrum — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DatasetSettingsXrayFluorescenceSpectrum

Properties

Name

Type

Description

Notes

energy_e_v

List[float]

X-ray fluorescence scan energy for each measurement point

data

List[float]

X-ray fluorescence scan result in arbitrary units; must be exactly the same length, as energy_eV

Example

from jfjoch_client.models.dataset_settings_xray_fluorescence_spectrum import DatasetSettingsXrayFluorescenceSpectrum
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DatasetSettingsXrayFluorescenceSpectrum from a JSON string
+dataset_settings_xray_fluorescence_spectrum_instance = DatasetSettingsXrayFluorescenceSpectrum.from_json(json)
+# print the JSON string representation of the object
+print(DatasetSettingsXrayFluorescenceSpectrum.to_json())
+
+# convert the object into a dict
+dataset_settings_xray_fluorescence_spectrum_dict = dataset_settings_xray_fluorescence_spectrum_instance.to_dict()
+# create an instance of DatasetSettingsXrayFluorescenceSpectrum from a dict
+dataset_settings_xray_fluorescence_spectrum_from_dict = DatasetSettingsXrayFluorescenceSpectrum.from_dict(dataset_settings_xray_fluorescence_spectrum_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DefaultApi.html b/python_client/docs/DefaultApi.html new file mode 100644 index 000000000..4c6ae7cab --- /dev/null +++ b/python_client/docs/DefaultApi.html @@ -0,0 +1,1813 @@ + jfjoch_client.DefaultApi — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

jfjoch_client.DefaultApi

All URIs are relative to http://localhost:5232

Method

HTTP request

Description

cancel_post

POST /cancel

Cancel running data collection

config_azim_int_get

GET /config/azim_int

Get azimuthal integration configuration

config_azim_int_put

PUT /config/azim_int

Configure azimuthal integration

config_bragg_integration_get

GET /config/bragg_integration

Get Bragg integration configuration

config_bragg_integration_put

PUT /config/bragg_integration

Change Bragg integration settings

config_dark_mask_get

GET /config/dark_mask

Get settings for dark data collection to calculate mask

config_dark_mask_put

PUT /config/dark_mask

Set configuration for dark data collection to calculate mask

config_detector_get

GET /config/detector

Get detector configuration

config_detector_put

PUT /config/detector

Change detector configuration

config_file_writer_get

GET /config/file_writer

Get file writer settings

config_file_writer_put

PUT /config/file_writer

Change file writer settings

config_image_format_conversion_post

POST /config/image_format/conversion

Configure format for data collection with full conversion

config_image_format_get

GET /config/image_format

Get image output format

config_image_format_put

PUT /config/image_format

Change image output format

config_image_format_raw_post

POST /config/image_format/raw

Configure format for raw data collection

config_indexing_get

GET /config/indexing

Get indexing configuration

config_indexing_put

PUT /config/indexing

Change indexing algorithm settings

config_instrument_get

GET /config/instrument

Get instrument metadata

config_instrument_put

PUT /config/instrument

Change instrument metadata

config_internal_generator_image_put

PUT /config/internal_generator_image

Load binary image for internal FPGA generator

config_internal_generator_image_tiff_put

PUT /config/internal_generator_image.tiff

Load TIFF image for internal FPGA generator

config_mask_get

GET /config/mask

Get mask of the detector (binary)

config_mask_tiff_get

GET /config/mask.tiff

Get mask of the detector (TIFF)

config_roi_get

GET /config/roi

Get ROI definitions

config_roi_put

PUT /config/roi

Upload ROI definitions

config_rugnux_get

GET /config/rugnux

Get rugnux live mode settings and model status

config_rugnux_model_delete

DELETE /config/rugnux/model

Remove the model used by rugnux live mode

config_rugnux_model_put

PUT /config/rugnux/model

Upload the model used by rugnux live mode

config_rugnux_put

PUT /config/rugnux

Change rugnux live mode settings

config_select_detector_get

GET /config/select_detector

List available detectors

config_select_detector_put

PUT /config/select_detector

Select detector

config_spot_finding_get

GET /config/spot_finding

Get data processing configuration

config_spot_finding_put

PUT /config/spot_finding

Configure spot finding

config_user_mask_get

GET /config/user_mask

Detector must be Initialized. Get user mask of the detector (binary)

config_user_mask_put

PUT /config/user_mask

Upload user mask of the detector (binary)

config_user_mask_tiff_get

GET /config/user_mask.tiff

Detector must be Initialized. Get user mask of the detector (TIFF)

config_user_mask_tiff_put

PUT /config/user_mask.tiff

Upload user mask of the detector

config_zeromq_metadata_get

GET /config/zeromq_metadata

Get ZeroMQ metadata socket settings

config_zeromq_metadata_put

PUT /config/zeromq_metadata

Set ZeroMQ metadata settings

config_zeromq_preview_get

GET /config/zeromq_preview

Get ZeroMQ preview settings

config_zeromq_preview_put

PUT /config/zeromq_preview

Set ZeroMQ preview settings

deactivate_post

POST /deactivate

Prepare detector to turn off

detector_status_get

GET /detector/status

Get detector status

fpga_status_get

GET /fpga_status

Get status of FPGA devices

image_buffer_clear_post

POST /image_buffer/clear

Clear image buffer

image_buffer_image_cbor_get

GET /image_buffer/image.cbor

Get image message in CBOR format

image_buffer_image_jpeg_get

GET /image_buffer/image.jpeg

Get preview image in JPEG format using custom settings

image_buffer_image_tiff_get

GET /image_buffer/image.tiff

Get preview image in TIFF format

image_buffer_start_cbor_get

GET /image_buffer/start.cbor

Get Start message in CBOR format

image_buffer_status_get

GET /image_buffer/status

Get status of the image buffers

image_pusher_status_get

GET /image_pusher/status

Get status of image pusher

initialize_post

POST /initialize

Initialize detector and data acquisition

live_events_get

GET /live/events

Event stream of the collection, for a reader following it

pedestal_post

POST /pedestal

Collect dark current for the detector

preview_pedestal_tiff_get

GET /preview/pedestal.tiff

Get pedestal in TIFF format

preview_plot_bin_get

GET /preview/plot.bin

Generate 1D plot from Jungfraujoch and send in raw binary format. Data are provided as (32-bit) float binary array. This format doesn’t transmit information about X-axis, only values, so it is of limited use for azimuthal integration.

preview_plot_get

GET /preview/plot

Generate 1D plot from Jungfraujoch

result_scan_get

GET /result/scan

Get full scan result

rugnux_clear_post

POST /rugnux/clear

Clear the live rugnux result of the last collection

rugnux_map_ccp4_get

GET /rugnux/map.ccp4

Get an electron-density map of the last rugnux live run

rugnux_model_cif_get

GET /rugnux/model.cif

Get the model as placed by the last rugnux live run

rugnux_status_get

GET /rugnux/status

Get live rugnux processing status of the last collection

start_post

POST /start

Start detector

statistics_calibration_get

GET /statistics/calibration

Get calibration statistics

statistics_data_collection_get

GET /statistics/data_collection

Get data collection statistics

statistics_get

GET /statistics

Get general statistics

status_get

GET /status

Get Jungfraujoch status

trigger_post

POST /trigger

Send soft trigger to the detector

version_get

GET /version

Get Jungfraujoch version of jfjoch_broker

wait_till_done_post

POST /wait_till_done

Wait for acquisition done

wait_until_running_post

POST /wait_until_running

Wait for acquisition running

xfel_event_code_get

GET /xfel/event_code

Return XFEL event codes for the current data acquisition

xfel_pulse_id_get

GET /xfel/pulse_id

Return XFEL pulse IDs for the current data acquisition

cancel_post

cancel_post()

Cancel running data collection

Command will inform FPGA network card to stop pedestal or data collection at the current stage. Any frame that is currently being processed by CPU will be finished and sent to writer. Given the command is making sure to gracefully stop data acquisition and detector, it might take some time to switch back after command finished to Idle state.

With rugnux live mode (/config/rugnux) the command also cuts the rugnux analysis, during the collection or after its last image alike: the collection ends with what the analysis has established (see cut in /rugnux/status). After the last image the collection itself is complete and is not marked as cancelled.

If data collection is not running, the command has no effect.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Cancel running data collection
+        api_instance.cancel_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->cancel_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: Not defined

HTTP response details

Status code

Description

Response headers

200

Cancel request sent to FPGAs (or ignored, as data collection is not running)

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_azim_int_get

AzimIntSettings config_azim_int_get()

Get azimuthal integration configuration

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.azim_int_settings import AzimIntSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get azimuthal integration configuration
+        api_response = api_instance.config_azim_int_get()
+        print("The response of DefaultApi->config_azim_int_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_azim_int_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

AzimIntSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_azim_int_put

config_azim_int_put(azim_int_settings=azim_int_settings)

Configure azimuthal integration

Can be done when detector is Inactive or Idle

Example

import jfjoch_client
+from jfjoch_client.models.azim_int_settings import AzimIntSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    azim_int_settings = jfjoch_client.AzimIntSettings() # AzimIntSettings |  (optional)
+
+    try:
+        # Configure azimuthal integration
+        api_instance.config_azim_int_put(azim_int_settings=azim_int_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_azim_int_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

azim_int_settings

AzimIntSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_bragg_integration_get

BraggIntegrationSettings config_bragg_integration_get()

Get Bragg integration configuration

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.bragg_integration_settings import BraggIntegrationSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get Bragg integration configuration
+        api_response = api_instance.config_bragg_integration_get()
+        print("The response of DefaultApi->config_bragg_integration_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_bragg_integration_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

BraggIntegrationSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_bragg_integration_put

config_bragg_integration_put(bragg_integration_settings=bragg_integration_settings)

Change Bragg integration settings

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.models.bragg_integration_settings import BraggIntegrationSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    bragg_integration_settings = jfjoch_client.BraggIntegrationSettings() # BraggIntegrationSettings |  (optional)
+
+    try:
+        # Change Bragg integration settings
+        api_instance.config_bragg_integration_put(bragg_integration_settings=bragg_integration_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_bragg_integration_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

bragg_integration_settings

BraggIntegrationSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_dark_mask_get

DarkMaskSettings config_dark_mask_get()

Get settings for dark data collection to calculate mask

Example

import jfjoch_client
+from jfjoch_client.models.dark_mask_settings import DarkMaskSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get settings for dark data collection to calculate mask
+        api_response = api_instance.config_dark_mask_get()
+        print("The response of DefaultApi->config_dark_mask_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_dark_mask_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

DarkMaskSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_dark_mask_put

config_dark_mask_put(dark_mask_settings=dark_mask_settings)

Set configuration for dark data collection to calculate mask

This is only possible when operating DECTRIS detectors at the moment; it will be also available for PSI EIGER at some point. This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.models.dark_mask_settings import DarkMaskSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    dark_mask_settings = jfjoch_client.DarkMaskSettings() # DarkMaskSettings |  (optional)
+
+    try:
+        # Set configuration for dark data collection to calculate mask
+        api_instance.config_dark_mask_put(dark_mask_settings=dark_mask_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_dark_mask_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

dark_mask_settings

DarkMaskSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_detector_get

DetectorSettings config_detector_get()

Get detector configuration

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.detector_settings import DetectorSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get detector configuration
+        api_response = api_instance.config_detector_get()
+        print("The response of DefaultApi->config_detector_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_detector_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

DetectorSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_detector_put

config_detector_put(detector_settings=detector_settings)

Change detector configuration

Detector settings are ones that have effect on calibration, i.e., pedestal has to be collected again after changing these settings. This can only be done when detector is Idle, Error or Inactive states. If detector is in Idle state , pedestal procedure will be executed automatically - there must be no X-rays on the detector during the operation. If detector is in Inactive or Error states, new settings will be saved, but no calibration will be executed.

Example

import jfjoch_client
+from jfjoch_client.models.detector_settings import DetectorSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    detector_settings = jfjoch_client.DetectorSettings() # DetectorSettings |  (optional)
+
+    try:
+        # Change detector configuration
+        api_instance.config_detector_put(detector_settings=detector_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_detector_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

detector_settings

DetectorSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_file_writer_get

FileWriterSettings config_file_writer_get()

Get file writer settings

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.file_writer_settings import FileWriterSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get file writer settings
+        api_response = api_instance.config_file_writer_get()
+        print("The response of DefaultApi->config_file_writer_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_file_writer_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

FileWriterSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_file_writer_put

config_file_writer_put(file_writer_settings=file_writer_settings)

Change file writer settings

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.models.file_writer_settings import FileWriterSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    file_writer_settings = jfjoch_client.FileWriterSettings() # FileWriterSettings |  (optional)
+
+    try:
+        # Change file writer settings
+        api_instance.config_file_writer_put(file_writer_settings=file_writer_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_file_writer_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

file_writer_settings

FileWriterSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_image_format_conversion_post

config_image_format_conversion_post()

Configure format for data collection with full conversion

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Configure format for data collection with full conversion
+        api_instance.config_image_format_conversion_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_image_format_conversion_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_image_format_get

ImageFormatSettings config_image_format_get()

Get image output format

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.image_format_settings import ImageFormatSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get image output format
+        api_response = api_instance.config_image_format_get()
+        print("The response of DefaultApi->config_image_format_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_image_format_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

ImageFormatSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_image_format_put

config_image_format_put(image_format_settings=image_format_settings)

Change image output format

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.models.image_format_settings import ImageFormatSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    image_format_settings = jfjoch_client.ImageFormatSettings() # ImageFormatSettings |  (optional)
+
+    try:
+        # Change image output format
+        api_instance.config_image_format_put(image_format_settings=image_format_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_image_format_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

image_format_settings

ImageFormatSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_image_format_raw_post

config_image_format_raw_post()

Configure format for raw data collection

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Configure format for raw data collection
+        api_instance.config_image_format_raw_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_image_format_raw_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_indexing_get

IndexingSettings config_indexing_get()

Get indexing configuration

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.indexing_settings import IndexingSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get indexing configuration
+        api_response = api_instance.config_indexing_get()
+        print("The response of DefaultApi->config_indexing_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_indexing_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

IndexingSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_indexing_put

config_indexing_put(indexing_settings=indexing_settings)

Change indexing algorithm settings

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.models.indexing_settings import IndexingSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    indexing_settings = jfjoch_client.IndexingSettings() # IndexingSettings |  (optional)
+
+    try:
+        # Change indexing algorithm settings
+        api_instance.config_indexing_put(indexing_settings=indexing_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_indexing_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

indexing_settings

IndexingSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_instrument_get

InstrumentMetadata config_instrument_get()

Get instrument metadata

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.instrument_metadata import InstrumentMetadata
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get instrument metadata
+        api_response = api_instance.config_instrument_get()
+        print("The response of DefaultApi->config_instrument_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_instrument_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

InstrumentMetadata

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_instrument_put

config_instrument_put(instrument_metadata=instrument_metadata)

Change instrument metadata

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.models.instrument_metadata import InstrumentMetadata
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    instrument_metadata = jfjoch_client.InstrumentMetadata() # InstrumentMetadata |  (optional)
+
+    try:
+        # Change instrument metadata
+        api_instance.config_instrument_put(instrument_metadata=instrument_metadata)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_instrument_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

instrument_metadata

InstrumentMetadata

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_internal_generator_image_put

config_internal_generator_image_put(id=id, body=body)

Load binary image for internal FPGA generator

Load image for internal FPGA generator. This can only happen in Idle state of the detector. Requires binary blob with 16-bit integer numbers of size of detector in raw/converted coordinates (depending on detector settings).

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    id = 56 # int | Image id to upload (optional)
+    body = None # bytearray |  (optional)
+
+    try:
+        # Load binary image for internal FPGA generator
+        api_instance.config_internal_generator_image_put(id=id, body=body)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_internal_generator_image_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

id

int

Image id to upload

[optional]

body

bytearray

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/octet-stream

  • Accept: text/plain

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_internal_generator_image_tiff_put

config_internal_generator_image_tiff_put(id=id, body=body)

Load TIFF image for internal FPGA generator

Load image for internal FPGA generator. This can only happen in Idle state of the detector. Requires TIFF with 16-bit integer numbers of size of detector in raw/converted coordinates (depending on detector settings).

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    id = 56 # int | Image ID to upload (optional)
+    body = None # bytearray |  (optional)
+
+    try:
+        # Load TIFF image for internal FPGA generator
+        api_instance.config_internal_generator_image_tiff_put(id=id, body=body)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_internal_generator_image_tiff_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

id

int

Image ID to upload

[optional]

body

bytearray

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: image/tiff

  • Accept: text/plain

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_mask_get

bytearray config_mask_get()

Get mask of the detector (binary)

Detector must be Initialized. Get full pixel mask of the detector. See NXmx standard for meaning of pixel values.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get mask of the detector (binary)
+        api_response = api_instance.config_mask_get()
+        print("The response of DefaultApi->config_mask_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_mask_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

bytearray

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/octet-stream

HTTP response details

Status code

Description

Response headers

200

Binary array (4 byte; unsigned)

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_mask_tiff_get

bytearray config_mask_tiff_get()

Get mask of the detector (TIFF)

Should be in Idle state. Get full pixel mask of the detector See NXmx standard for meaning of pixel values

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get mask of the detector (TIFF)
+        api_response = api_instance.config_mask_tiff_get()
+        print("The response of DefaultApi->config_mask_tiff_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_mask_tiff_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

bytearray

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: image/tiff

HTTP response details

Status code

Description

Response headers

200

Pixel mask in TIFF format (4 byte; unsigned)

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_roi_get

RoiDefinitions config_roi_get()

Get ROI definitions

Example

import jfjoch_client
+from jfjoch_client.models.roi_definitions import RoiDefinitions
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get ROI definitions
+        api_response = api_instance.config_roi_get()
+        print("The response of DefaultApi->config_roi_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_roi_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

RoiDefinitions

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_roi_put

config_roi_put(roi_definitions=roi_definitions)

Upload ROI definitions

Example

import jfjoch_client
+from jfjoch_client.models.roi_definitions import RoiDefinitions
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    roi_definitions = jfjoch_client.RoiDefinitions() # RoiDefinitions |  (optional)
+
+    try:
+        # Upload ROI definitions
+        api_instance.config_roi_put(roi_definitions=roi_definitions)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_roi_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

roi_definitions

RoiDefinitions

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_rugnux_get

RugnuxStatus config_rugnux_get()

Get rugnux live mode settings and model status

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.rugnux_status import RugnuxStatus
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get rugnux live mode settings and model status
+        api_response = api_instance.config_rugnux_get()
+        print("The response of DefaultApi->config_rugnux_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_rugnux_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

RugnuxStatus

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_rugnux_model_delete

config_rugnux_model_delete()

Remove the model used by rugnux live mode

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Remove the model used by rugnux live mode
+        api_instance.config_rugnux_model_delete()
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_rugnux_model_delete: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

All good

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_rugnux_model_put

config_rugnux_model_put(body=body)

Upload the model used by rugnux live mode

This can only be done when detector is Idle, Error or Inactive states. The model (PDB or mmCIF, optionally gzipped; at most 64 MiB) is used for molecular replacement and validation of every following rugnux live collection, until it is removed with DELETE /config/rugnux/model or replaced by another upload.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    body = None # bytearray |  (optional)
+
+    try:
+        # Upload the model used by rugnux live mode
+        api_instance.config_rugnux_model_put(body=body)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_rugnux_model_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

body

bytearray

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/octet-stream

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

All good

-

400

Empty body, or not a model that can be read (PDB or mmCIF, optionally gzipped)

-

413

Model larger than 64 MiB

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_rugnux_put

config_rugnux_put(rugnux_settings=rugnux_settings)

Change rugnux live mode settings

This can only be done when detector is Idle, Error or Inactive states.

Example

import jfjoch_client
+from jfjoch_client.models.rugnux_settings import RugnuxSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    rugnux_settings = jfjoch_client.RugnuxSettings() # RugnuxSettings |  (optional)
+
+    try:
+        # Change rugnux live mode settings
+        api_instance.config_rugnux_put(rugnux_settings=rugnux_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_rugnux_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

rugnux_settings

RugnuxSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_select_detector_get

DetectorList config_select_detector_get()

List available detectors

Configured detectors that can be selected by used

Example

import jfjoch_client
+from jfjoch_client.models.detector_list import DetectorList
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # List available detectors
+        api_response = api_instance.config_select_detector_get()
+        print("The response of DefaultApi->config_select_detector_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_select_detector_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

DetectorList

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_select_detector_put

config_select_detector_put(detector_selection=detector_selection)

Select detector

Jungfraujoch allows to control multiple detectors and/or region-of-interests. The command allows to choose one detector from the list (ID has to be consistent with one provided by GET response). Changing detector will set detector to Inactive state and will require reinitialization.

Example

import jfjoch_client
+from jfjoch_client.models.detector_selection import DetectorSelection
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    detector_selection = jfjoch_client.DetectorSelection() # DetectorSelection |  (optional)
+
+    try:
+        # Select detector
+        api_instance.config_select_detector_put(detector_selection=detector_selection)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_select_detector_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

detector_selection

DetectorSelection

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_spot_finding_get

SpotFindingSettings config_spot_finding_get()

Get data processing configuration

Can be done anytime

Example

import jfjoch_client
+from jfjoch_client.models.spot_finding_settings import SpotFindingSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get data processing configuration
+        api_response = api_instance.config_spot_finding_get()
+        print("The response of DefaultApi->config_spot_finding_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_spot_finding_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

SpotFindingSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_spot_finding_put

config_spot_finding_put(spot_finding_settings=spot_finding_settings)

Configure spot finding

Can be done anytime, also while data collection is running

Example

import jfjoch_client
+from jfjoch_client.models.spot_finding_settings import SpotFindingSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    spot_finding_settings = jfjoch_client.SpotFindingSettings() # SpotFindingSettings |  (optional)
+
+    try:
+        # Configure spot finding
+        api_instance.config_spot_finding_put(spot_finding_settings=spot_finding_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_spot_finding_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

spot_finding_settings

SpotFindingSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_user_mask_get

bytearray config_user_mask_get()

Detector must be Initialized. Get user mask of the detector (binary)

Get user pixel mask of the detector in the actual detector coordinates: 0 - good pixel, 1 - masked

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Detector must be Initialized. Get user mask of the detector (binary) 
+        api_response = api_instance.config_user_mask_get()
+        print("The response of DefaultApi->config_user_mask_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_user_mask_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

bytearray

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/octet-stream

HTTP response details

Status code

Description

Response headers

200

User mask in binary format (4 byte; unsigned)

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_user_mask_put

config_user_mask_put(body=body)

Upload user mask of the detector (binary)

Should be in Idle state. Upload user mask of the detector - this is for example to account for beam stop shadow or misbehaving regions. If detector is conversion mode the mask can be both in raw (1024x512; stacked modules) or converted coordinates. In the latter case - module gaps are ignored and don’t need to be assigned value. Mask is expected as binary array (4-byte; unsigned). 0 - good pixel, other value - masked User mask is stored in NXmx pixel mask (bit 8), as well as used in spot finding and azimuthal integration.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    body = None # bytearray |  (optional)
+
+    try:
+        # Upload user mask of the detector (binary)
+        api_instance.config_user_mask_put(body=body)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_user_mask_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

body

bytearray

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/octet-stream

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

All good

-

400

Mask is not 4-byte unsigned integer array or empty body

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_user_mask_tiff_get

bytearray config_user_mask_tiff_get()

Detector must be Initialized. Get user mask of the detector (TIFF)

Get user pixel mask of the detector in the actual detector coordinates: 0 - good pixel, 1 - masked

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Detector must be Initialized. Get user mask of the detector (TIFF) 
+        api_response = api_instance.config_user_mask_tiff_get()
+        print("The response of DefaultApi->config_user_mask_tiff_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_user_mask_tiff_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

bytearray

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: image/tiff

HTTP response details

Status code

Description

Response headers

200

User mask in TIFF format (4 byte; unsigned)

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_user_mask_tiff_put

config_user_mask_tiff_put(body=body)

Upload user mask of the detector

Should be in Idle state. Upload user mask of the detector - this is for example to account for beam stop shadow or misbehaving regions. If detector is conversion mode the mask can be both in raw (1024x512; stacked modules) or converted coordinates. In the latter case - module gaps are ignored and don’t need to be assigned value. Mask is expected as a single-channel TIFF (8-, 16- or 32-bit integer, signed or unsigned). 0 - good pixel, other value - masked User mask is stored in NXmx pixel mask (bit 8), as well as used in spot finding and azimuthal integration. User mask is not automatically applied - i.e. pixels with user mask will have a valid pixel value in the images.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    body = None # bytearray |  (optional)
+
+    try:
+        # Upload user mask of the detector
+        api_instance.config_user_mask_tiff_put(body=body)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_user_mask_tiff_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

body

bytearray

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: image/tiff

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

All good

-

400

Not a valid single-channel TIFF or size doesn’t match the detector

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_zeromq_metadata_get

ZeromqMetadataSettings config_zeromq_metadata_get()

Get ZeroMQ metadata socket settings

Example

import jfjoch_client
+from jfjoch_client.models.zeromq_metadata_settings import ZeromqMetadataSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get ZeroMQ metadata socket settings
+        api_response = api_instance.config_zeromq_metadata_get()
+        print("The response of DefaultApi->config_zeromq_metadata_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_zeromq_metadata_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

ZeromqMetadataSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_zeromq_metadata_put

config_zeromq_metadata_put(zeromq_metadata_settings=zeromq_metadata_settings)

Set ZeroMQ metadata settings

Jungfraujoch can generate metadata message stream on ZeroMQ PUB socket. This stream covers all images. Here settings of the socket can be adjusted. While the data structure contains also socket_address, this cannot be changed via HTTP and is ignore in PUT request.

Example

import jfjoch_client
+from jfjoch_client.models.zeromq_metadata_settings import ZeromqMetadataSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    zeromq_metadata_settings = jfjoch_client.ZeromqMetadataSettings() # ZeromqMetadataSettings |  (optional)
+
+    try:
+        # Set ZeroMQ metadata settings
+        api_instance.config_zeromq_metadata_put(zeromq_metadata_settings=zeromq_metadata_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_zeromq_metadata_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

zeromq_metadata_settings

ZeromqMetadataSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_zeromq_preview_get

ZeromqPreviewSettings config_zeromq_preview_get()

Get ZeroMQ preview settings

Example

import jfjoch_client
+from jfjoch_client.models.zeromq_preview_settings import ZeromqPreviewSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get ZeroMQ preview settings
+        api_response = api_instance.config_zeromq_preview_get()
+        print("The response of DefaultApi->config_zeromq_preview_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_zeromq_preview_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

ZeromqPreviewSettings

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

config_zeromq_preview_put

config_zeromq_preview_put(zeromq_preview_settings=zeromq_preview_settings)

Set ZeroMQ preview settings

Jungfraujoch can generate preview message stream on ZeroMQ SUB socket. Here settings of the socket can be adjusted. While the data structure contains also socket_address, this cannot be changed via HTTP and is ignore in PUT request. Options set with this PUT request have no effect on HTTP based preview.

Example

import jfjoch_client
+from jfjoch_client.models.zeromq_preview_settings import ZeromqPreviewSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    zeromq_preview_settings = jfjoch_client.ZeromqPreviewSettings() # ZeromqPreviewSettings |  (optional)
+
+    try:
+        # Set ZeroMQ preview settings
+        api_instance.config_zeromq_preview_put(zeromq_preview_settings=zeromq_preview_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->config_zeromq_preview_put: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

zeromq_preview_settings

ZeromqPreviewSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

deactivate_post

deactivate_post()

Prepare detector to turn off

Should be in Idle or Error state. Command deactivates data acquisition and turns off detector high voltage and ASIC. Should be used always before turning off power from the detector.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Prepare detector to turn off
+        api_instance.deactivate_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->deactivate_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Detector ready to turn off

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

detector_status_get

DetectorStatus detector_status_get()

Get detector status

Status of the JUNGFRAU detector

Example

import jfjoch_client
+from jfjoch_client.models.detector_status import DetectorStatus
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get detector status
+        api_response = api_instance.detector_status_get()
+        print("The response of DefaultApi->detector_status_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->detector_status_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

DetectorStatus

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json, text/plain

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

404

Running in &quot;simulator&quot; mode - no detector present

-

500

Error encountered when trying to read status

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

fpga_status_get

List[FpgaStatusInner] fpga_status_get()

Get status of FPGA devices

Example

import jfjoch_client
+from jfjoch_client.models.fpga_status_inner import FpgaStatusInner
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get status of FPGA devices
+        api_response = api_instance.fpga_status_get()
+        print("The response of DefaultApi->fpga_status_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->fpga_status_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

List[FpgaStatusInner]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

image_buffer_clear_post

image_buffer_clear_post()

Clear image buffer

Turns off image buffer for the last data collection. Can be only run when Jungfraujoch is not collecting data.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Clear image buffer
+        api_instance.image_buffer_clear_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->image_buffer_clear_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Done

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

image_buffer_image_cbor_get

bytearray image_buffer_image_cbor_get(id=id)

Get image message in CBOR format

Contains full image data and metadata. The image must come from the latest data collection.

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    id = -1 # int | Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer (optional) (default to -1)
+
+    try:
+        # Get image message in CBOR format
+        api_response = api_instance.image_buffer_image_cbor_get(id=id)
+        print("The response of DefaultApi->image_buffer_image_cbor_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->image_buffer_image_cbor_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

id

int

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

[optional] [default to -1]

Return type

bytearray

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, application/cbor, application/json

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Return image message

-

404

Image not present in the buffer - either not yet measured or already replaced by a next image.

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

image_buffer_image_jpeg_get

bytearray image_buffer_image_jpeg_get(id=id, show_user_mask=show_user_mask, show_roi=show_roi, show_spots=show_spots, show_predictions=show_predictions, show_beam_center=show_beam_center, saturation=saturation, jpeg_quality=jpeg_quality, show_res_ring=show_res_ring, color=color, show_res_est=show_res_est)

Get preview image in JPEG format using custom settings

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    id = -1 # int | Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer (optional) (default to -1)
+    show_user_mask = False # bool | Show user mask (optional) (default to False)
+    show_roi = False # bool | Show ROI areas on the image (optional) (default to False)
+    show_spots = True # bool | Show spot finding results on the image (optional) (default to True)
+    show_predictions = False # bool | Show Bragg spot predictions on the image (if available for the image) (optional) (default to False)
+    show_beam_center = True # bool | Show beam center on the image (optional) (default to True)
+    saturation = 3.4 # float | Saturation value to set contrast in the preview image; if not provided, then autocontrast procedure is used (optional)
+    jpeg_quality = 100 # int | Quality of JPEG image (100 - highest; 0 - lowest) (optional) (default to 100)
+    show_res_ring = 0.1 # float | Show resolution ring, provided in Angstrom (optional) (default to 0.1)
+    color = indigo # str | Color scale for preview image (optional) (default to indigo)
+    show_res_est = False # bool | Show resolution estimation as a ring (optional) (default to False)
+
+    try:
+        # Get preview image in JPEG format using custom settings
+        api_response = api_instance.image_buffer_image_jpeg_get(id=id, show_user_mask=show_user_mask, show_roi=show_roi, show_spots=show_spots, show_predictions=show_predictions, show_beam_center=show_beam_center, saturation=saturation, jpeg_quality=jpeg_quality, show_res_ring=show_res_ring, color=color, show_res_est=show_res_est)
+        print("The response of DefaultApi->image_buffer_image_jpeg_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->image_buffer_image_jpeg_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

id

int

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

[optional] [default to -1]

show_user_mask

bool

Show user mask

[optional] [default to False]

show_roi

bool

Show ROI areas on the image

[optional] [default to False]

show_spots

bool

Show spot finding results on the image

[optional] [default to True]

show_predictions

bool

Show Bragg spot predictions on the image (if available for the image)

[optional] [default to False]

show_beam_center

bool

Show beam center on the image

[optional] [default to True]

saturation

float

Saturation value to set contrast in the preview image; if not provided, then autocontrast procedure is used

[optional]

jpeg_quality

int

Quality of JPEG image (100 - highest; 0 - lowest)

[optional] [default to 100]

show_res_ring

float

Show resolution ring, provided in Angstrom

[optional] [default to 0.1]

color

str

Color scale for preview image

[optional] [default to indigo]

show_res_est

bool

Show resolution estimation as a ring

[optional] [default to False]

Return type

bytearray

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, image/jpeg, application/json

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Preview image

-

404

Image not present in the buffer - either not yet measured or already replaced by a next image.

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

image_buffer_image_tiff_get

bytearray image_buffer_image_tiff_get(id=id)

Get preview image in TIFF format

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    id = -1 # int | Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer (optional) (default to -1)
+
+    try:
+        # Get preview image in TIFF format
+        api_response = api_instance.image_buffer_image_tiff_get(id=id)
+        print("The response of DefaultApi->image_buffer_image_tiff_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->image_buffer_image_tiff_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

id

int

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

[optional] [default to -1]

Return type

bytearray

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, image/tiff

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Preview image

-

404

No preview image recorded so far

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

image_buffer_start_cbor_get

bytearray image_buffer_start_cbor_get()

Get Start message in CBOR format

Contains metadata for a dataset (e.g., experimental geometry)

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get Start message in CBOR format
+        api_response = api_instance.image_buffer_start_cbor_get()
+        print("The response of DefaultApi->image_buffer_start_cbor_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->image_buffer_start_cbor_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

bytearray

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, application/cbor, application/json

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Return start message

-

404

No measurement so far

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

image_buffer_status_get

ImageBufferStatus image_buffer_status_get()

Get status of the image buffers

Can be run at any stage of Jungfraujoch operation, including during data collection. The status of the image buffer is volatile during data collection - if data collection goes for more images than available buffer slots, then image might be replaced in the buffer between calling /images and /image.cbor.

Example

import jfjoch_client
+from jfjoch_client.models.image_buffer_status import ImageBufferStatus
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get status of the image buffers
+        api_response = api_instance.image_buffer_status_get()
+        print("The response of DefaultApi->image_buffer_status_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->image_buffer_status_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

ImageBufferStatus

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Done

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

image_pusher_status_get

ImagePusherStatus image_pusher_status_get()

Get status of image pusher

Example

import jfjoch_client
+from jfjoch_client.models.image_pusher_status import ImagePusherStatus
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get status of image pusher
+        api_response = api_instance.image_pusher_status_get()
+        print("The response of DefaultApi->image_pusher_status_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->image_pusher_status_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

ImagePusherStatus

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json, text/plain

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

500

Error encountered when trying to read status

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

initialize_post

initialize_post()

Initialize detector and data acquisition

Should be used in two cases:

  • Detector is in Inactive state

  • Detector is in Error state X-ray shutter must be closed. This operation will reconfigure network interface of the detector. During operation of the detector it is recommended to use the POST /pedestal operation instead. If storage cells are used, the execution time might be few minutes. It also clears the image buffer, the previous collection’s plots and live rugnux status, disables live rugnux analysis and removes the rugnux model. It drops the previous dataset’s bearer tokens and resets its settings, so nothing of that dataset stays readable.

This is async function - one needs to use POST /wait_till_done to ensure operation is done.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Initialize detector and data acquisition
+        api_instance.initialize_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->initialize_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Initialization started

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

live_events_get

str live_events_get()

Event stream of the collection, for a reader following it

Server-sent events (text/event-stream) for the current collection, from the moment /start has accepted it: first its whole history, then every change, until it ends or a new collection begins. Only one reader at a time. Events, each with a JSON data line:

  • start {run_number, run_name, file_prefix, number_of_images, images_per_file, cbor} - first, once the start message is known: at once for a JUNGFRAU, when the detector sends its own for a DECTRIS. cbor is the start message the writer of the master file received, CBOR in base64; a reader builds the dataset from it;

  • file {file_number, file, first_image, image_count} - a data file closed and renamed into place; file is relative to the collection’s root, as the writer named it;

  • end {images, error?} - every writer acknowledged the end: the data files and the master file are in place; images is the number of images collected. Also sent, with error, when the measurement ends any other way - before the start message, for one. The stream then closes;

  • superseded {run_number} - a new collection began. The stream then closes. A comment line (: keepalive) every 10 s when nothing happens.

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Event stream of the collection, for a reader following it
+        api_response = api_instance.live_events_get()
+        print("The response of DefaultApi->live_events_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->live_events_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

str

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/event-stream, text/plain

HTTP response details

Status code

Description

Response headers

200

Event stream

-

401

The current dataset is protected and no valid bearer token was presented.

-

404

No collection has started

-

409

Another reader is following the collection, or the image pusher does not report closed data files

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

pedestal_post

pedestal_post()

Collect dark current for the detector

Updates calibration of the JUNGFRAU detector. Must be in Idle state.

X-ray shutter must be closed. Recommended to run once per hour for long integration times (> 100 us).

This is async function - one needs to use POST /wait_till_done to ensure operation is done.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Collect dark current for the detector
+        api_instance.pedestal_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->pedestal_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

preview_pedestal_tiff_get

bytearray preview_pedestal_tiff_get(gain_level, sc=sc)

Get pedestal in TIFF format

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    gain_level = 56 # int | Gain level (0, 1, 2)
+    sc = 56 # int | Storage cell number (optional)
+
+    try:
+        # Get pedestal in TIFF format
+        api_response = api_instance.preview_pedestal_tiff_get(gain_level, sc=sc)
+        print("The response of DefaultApi->preview_pedestal_tiff_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->preview_pedestal_tiff_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

gain_level

int

Gain level (0, 1, 2)

sc

int

Storage cell number

[optional]

Return type

bytearray

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: image/tiff

HTTP response details

Status code

Description

Response headers

200

Calibration image

-

400

Invalid gain level or storage cell number

-

404

No calibration recorded so far

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

preview_plot_bin_get

bytearray preview_plot_bin_get(type, roi=roi)

Generate 1D plot from Jungfraujoch and send in raw binary format. Data are provided as (32-bit) float binary array. This format doesn’t transmit information about X-axis, only values, so it is of limited use for azimuthal integration.

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    type = 'type_example' # str | Type of requested plot
+    roi = 'roi_example' # str | Name of ROI for which plot is requested (optional)
+
+    try:
+        # Generate 1D plot from Jungfraujoch and send in raw binary format. Data are provided as (32-bit) float binary array. This format doesn't transmit information about X-axis, only values, so it is of limited use for azimuthal integration. 
+        api_response = api_instance.preview_plot_bin_get(type, roi=roi)
+        print("The response of DefaultApi->preview_plot_bin_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->preview_plot_bin_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

type

str

Type of requested plot

roi

str

Name of ROI for which plot is requested

[optional]

Return type

bytearray

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, application/octet-stream

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Everything OK.

-

400

Input parsing or validation error

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

preview_plot_get

Plots preview_plot_get(type, binning=binning, fill=fill, experimental_coord=experimental_coord, azint_unit=azint_unit)

Generate 1D plot from Jungfraujoch

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.models.plots import Plots
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    type = 'type_example' # str | Type of requested plot
+    binning = 1 # int | Binning of frames for the plot (0 = default binning) (optional) (default to 1)
+    fill = 3.4 # float | Fill value for elements that were missed during data collection  (optional)
+    experimental_coord = False # bool | If measurement has goniometer axis defined, plot X-axis will represent rotation angle If measurement has grid scan defined, plot X-axis and Y-axis will represent grid position, Z will be used as the final value For still measurement the number is ignored  (optional) (default to False)
+    azint_unit = Q_recipA # str | Unit used for azim int.  (optional) (default to Q_recipA)
+
+    try:
+        # Generate 1D plot from Jungfraujoch
+        api_response = api_instance.preview_plot_get(type, binning=binning, fill=fill, experimental_coord=experimental_coord, azint_unit=azint_unit)
+        print("The response of DefaultApi->preview_plot_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->preview_plot_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

type

str

Type of requested plot

binning

int

Binning of frames for the plot (0 = default binning)

[optional] [default to 1]

fill

float

Fill value for elements that were missed during data collection

[optional]

experimental_coord

bool

If measurement has goniometer axis defined, plot X-axis will represent rotation angle If measurement has grid scan defined, plot X-axis and Y-axis will represent grid position, Z will be used as the final value For still measurement the number is ignored

[optional] [default to False]

azint_unit

str

Unit used for azim int.

[optional] [default to Q_recipA]

Return type

Plots

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Everything OK.

-

400

Input parsing or validation error

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

result_scan_get

ScanResult result_scan_get()

Get full scan result

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.models.scan_result import ScanResult
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get full scan result
+        api_response = api_instance.result_scan_get()
+        print("The response of DefaultApi->result_scan_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->result_scan_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

ScanResult

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Everything OK.

-

404

No grid scan recorded

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

rugnux_clear_post

rugnux_clear_post()

Clear the live rugnux result of the last collection

Puts /rugnux/status back to Idle with nothing of the last run - its merge, model, maps, steps and notes - as before any collection. The collection’s images, plots and the rugnux live settings are kept. Can be only run when Jungfraujoch is not collecting data.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Clear the live rugnux result of the last collection
+        api_instance.rugnux_clear_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->rugnux_clear_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Done

-

500

Error within Jungfraujoch code - see output message (`WrongDAQState` during a collection).

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

rugnux_map_ccp4_get

bytearray rugnux_map_ccp4_get(type=type, stage=stage)

Get an electron-density map of the last rugnux live run

The map of the placed model (/rugnux/model.cif) in CCP4 format (mode 2, float), made from the map coefficients written to _maps.mtz (FWT/PHWT, DELFWT/PHDELWT, ANOM/PHANOM). It covers one unit cell centred on the model - along an axis where the model reaches further than the cell, the model plus 5 A instead - sampled every d_min/3; the mean and RMS in its header are those of the unit cell, so contour levels in sigma are the usual ones. Where the run refined the model, the 2mFo-DFc and mFo-DFc maps are the refined model’s unless asked for stage=placed; the anomalous map stays on the placed model’s phases.

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    type = 2fofc # str | `2fofc`: the 2mFo-DFc map; `fofc`: the mFo-DFc difference map; `anom`: the anomalous difference map, (F(+) - F(-)) on the model phases less 90 degrees, where the merge kept the Bijvoet pairs (`anomalous_map` in `/rugnux/status`)  (optional) (default to 2fofc)
+    stage = 'stage_example' # str | `placed`: the model as placed; `refined`: the model refined (`refined_model` in `/rugnux/status`). Default: the refined model where there is one, otherwise the placed one.  (optional)
+
+    try:
+        # Get an electron-density map of the last rugnux live run
+        api_response = api_instance.rugnux_map_ccp4_get(type=type, stage=stage)
+        print("The response of DefaultApi->rugnux_map_ccp4_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->rugnux_map_ccp4_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

type

str

`2fofc`: the 2mFo-DFc map; `fofc`: the mFo-DFc difference map; `anom`: the anomalous difference map, (F(+) - F(-)) on the model phases less 90 degrees, where the merge kept the Bijvoet pairs (`anomalous_map` in `/rugnux/status`)

[optional] [default to 2fofc]

stage

str

`placed`: the model as placed; `refined`: the model refined (`refined_model` in `/rugnux/status`). Default: the refined model where there is one, otherwise the placed one.

[optional]

Return type

bytearray

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/octet-stream, text/plain

HTTP response details

Status code

Description

Response headers

200

Map

-

400

Unknown map type or stage

-

401

The current dataset is protected and no valid bearer token was presented.

-

404

The last rugnux live run placed no model or made no maps, or (`anom`) has no Bijvoet pairs, or (`stage=refined`) refined none

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

rugnux_model_cif_get

bytearray rugnux_model_cif_get(stage=stage)

Get the model as placed by the last rugnux live run

The model placed against the data by molecular replacement or validation, as mmCIF - the same text as the _model.cif file written beside the data: the data’s cell and space group, with the input model’s own metadata (entities, sequences, references, authors, software) kept. Kept as long as /rugnux/status. Where the run refined the model, the refined model unless asked for stage=placed.

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    stage = 'stage_example' # str | `placed`: the model as placed; `refined`: the model refined (`refined_model` in `/rugnux/status`). Default: the refined model where there is one, otherwise the placed one.  (optional)
+
+    try:
+        # Get the model as placed by the last rugnux live run
+        api_response = api_instance.rugnux_model_cif_get(stage=stage)
+        print("The response of DefaultApi->rugnux_model_cif_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->rugnux_model_cif_get: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

stage

str

`placed`: the model as placed; `refined`: the model refined (`refined_model` in `/rugnux/status`). Default: the refined model where there is one, otherwise the placed one.

[optional]

Return type

bytearray

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: chemical/x-mmcif, text/plain

HTTP response details

Status code

Description

Response headers

200

Placed model

-

400

Unknown stage

-

401

The current dataset is protected and no valid bearer token was presented.

-

404

The last rugnux live run placed no model, or (`stage=refined`) refined none

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

rugnux_status_get

RugnuxLiveStatus rugnux_status_get()

Get live rugnux processing status of the last collection

Can be done anytime

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.models.rugnux_live_status import RugnuxLiveStatus
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get live rugnux processing status of the last collection
+        api_response = api_instance.rugnux_status_get()
+        print("The response of DefaultApi->rugnux_status_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->rugnux_status_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

RugnuxLiveStatus

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

start_post

start_post(dataset_settings=dataset_settings)

Start detector

Start data acquisition. Detector must be in Idle state. Default behavior is for the call to block until detector is ready to accept soft/TTL triggers. However, this behavior can be changed by settings async_start to true in the request body, in which case the call will return immediately and one needs to use /wait_until_running to ensure detector is ready to run. Optional tokens protect the dataset: while set, its statistics, buffered images and plots require Authorization: Bearer <token>.

Example

import jfjoch_client
+from jfjoch_client.models.dataset_settings import DatasetSettings
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    dataset_settings = jfjoch_client.DatasetSettings() # DatasetSettings |  (optional)
+
+    try:
+        # Start detector
+        api_instance.start_post(dataset_settings=dataset_settings)
+    except Exception as e:
+        print("Exception when calling DefaultApi->start_post: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

dataset_settings

DatasetSettings

[optional]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

400

Input parsing or validation error

-

500

Error within Jungfraujoch code - see output message.

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

statistics_calibration_get

List[CalibrationStatisticsInner] statistics_calibration_get()

Get calibration statistics

Statistics are provided for each module/storage cell separately

Example

import jfjoch_client
+from jfjoch_client.models.calibration_statistics_inner import CalibrationStatisticsInner
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get calibration statistics
+        api_response = api_instance.statistics_calibration_get()
+        print("The response of DefaultApi->statistics_calibration_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->statistics_calibration_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

List[CalibrationStatisticsInner]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

statistics_data_collection_get

MeasurementStatistics statistics_data_collection_get()

Get data collection statistics

Results of the last data collection (dataset name, unit cell, …)

Example

  • Bearer Authentication (bearerAuth):

import jfjoch_client
+from jfjoch_client.models.measurement_statistics import MeasurementStatistics
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
+
+# Configure Bearer authorization: bearerAuth
+configuration = jfjoch_client.Configuration(
+    access_token = os.environ["BEARER_TOKEN"]
+)
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get data collection statistics
+        api_response = api_instance.statistics_data_collection_get()
+        print("The response of DefaultApi->statistics_data_collection_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->statistics_data_collection_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

MeasurementStatistics

Authorization

bearerAuth

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain, application/json

HTTP response details

Status code

Description

Response headers

401

The current dataset is protected and no valid bearer token was presented.

-

200

Everything OK

-

404

No data collection performed so far

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

statistics_get

JfjochStatistics statistics_get()

Get general statistics

measurement is omitted unless the request carries a valid bearer token for a protected dataset (see tokens in /start).

Example

import jfjoch_client
+from jfjoch_client.models.jfjoch_statistics import JfjochStatistics
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get general statistics
+        api_response = api_instance.statistics_get()
+        print("The response of DefaultApi->statistics_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->statistics_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

JfjochStatistics

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

status_get

BrokerStatus status_get()

Get Jungfraujoch status

Status of the data acquisition

Example

import jfjoch_client
+from jfjoch_client.models.broker_status import BrokerStatus
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get Jungfraujoch status
+        api_response = api_instance.status_get()
+        print("The response of DefaultApi->status_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->status_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

BrokerStatus

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Everything OK

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

trigger_post

trigger_post()

Send soft trigger to the detector

Generate soft trigger

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Send soft trigger to the detector
+        api_instance.trigger_post()
+    except Exception as e:
+        print("Exception when calling DefaultApi->trigger_post: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: Not defined

HTTP response details

Status code

Description

Response headers

200

Trigger sent

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

version_get

str version_get()

Get Jungfraujoch version of jfjoch_broker

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Get Jungfraujoch version of jfjoch_broker
+        api_response = api_instance.version_get()
+        print("The response of DefaultApi->version_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->version_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

str

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: text/plain

HTTP response details

Status code

Description

Response headers

200

Release number of Jungfraujoch

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

wait_till_done_post

wait_till_done_post(timeout=timeout)

Wait for acquisition done

Block execution of external script till initialization, data collection or pedestal is finished. Running this command does not affect (cancel) running data collection, it is only to ensure synchronous execution of other software.

To not block web server for a indefinite period of time, the procedure is provided with a timeout. Extending timeout is possible, but requires to ensure safety that client will not close the connection and retry the connection.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    timeout = 60 # int | Timeout in seconds (0 == immediate response) (optional) (default to 60)
+
+    try:
+        # Wait for acquisition done
+        api_instance.wait_till_done_post(timeout=timeout)
+    except Exception as e:
+        print("Exception when calling DefaultApi->wait_till_done_post: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

timeout

int

Timeout in seconds (0 == immediate response)

[optional] [default to 60]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Detector in `Idle` state, another data collection can start immediately. The operation that finished either succeeded, was cancelled, or ended with a warning.

-

400

Timeout parameter out of bounds

-

500

Error within Jungfraujoch code, or the operation that finished ended in an error - missing packets, or a writer that could not write - see output message. A cancelled data collection is not an error.

-

502

Detector is inactive mode

-

504

Timeout reached, need to restart operation

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

wait_until_running_post

wait_until_running_post(timeout=timeout)

Wait for acquisition running

Block execution of external script till detector and Jungfraujoch are ready to collect data. To not block web server for a indefinite period of time, the procedure is provided with a timeout. Extending timeout is possible, but requires to ensure safety that client will not close the connection and retry the connection.

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+    timeout = 60 # int | Timeout in seconds (0 == immediate response) (optional) (default to 60)
+
+    try:
+        # Wait for acquisition running
+        api_instance.wait_until_running_post(timeout=timeout)
+    except Exception as e:
+        print("Exception when calling DefaultApi->wait_until_running_post: %s\n" % e)
+

Parameters

Name

Type

Description

Notes

timeout

int

Timeout in seconds (0 == immediate response)

[optional] [default to 60]

Return type

void (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Detector in `Measuring` state

-

400

Timeout parameter out of bounds

-

500

Error within Jungfraujoch code - see output message.

-

502

Detector is inactive mode

-

504

Timeout reached, need to restart operation

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

xfel_event_code_get

List[int] xfel_event_code_get()

Return XFEL event codes for the current data acquisition

Return array of XFEL event codes

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Return XFEL event codes for the current data acquisition
+        api_response = api_instance.xfel_event_code_get()
+        print("The response of DefaultApi->xfel_event_code_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->xfel_event_code_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

List[int]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Event codes collected

-

404

Not in XFEL mode or no acquisition recorded

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

xfel_pulse_id_get

List[int] xfel_pulse_id_get()

Return XFEL pulse IDs for the current data acquisition

Return array of XFEL pulse IDs - (-1) if image not recorded

Example

import jfjoch_client
+from jfjoch_client.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost:5232
+# See configuration.py for a list of all supported configuration parameters.
+configuration = jfjoch_client.Configuration(
+    host = "http://localhost:5232"
+)
+
+
+# Enter a context with an instance of the API client
+with jfjoch_client.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = jfjoch_client.DefaultApi(api_client)
+
+    try:
+        # Return XFEL pulse IDs for the current data acquisition
+        api_response = api_instance.xfel_pulse_id_get()
+        print("The response of DefaultApi->xfel_pulse_id_get:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling DefaultApi->xfel_pulse_id_get: %s\n" % e)
+

Parameters

This endpoint does not need any parameter.

Return type

List[int]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined

  • Accept: application/json

HTTP response details

Status code

Description

Response headers

200

Pulse ID collected

-

404

Not in XFEL mode or no acquisition recorded

-

[Back to top] [Back to API list] [Back to Model list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/Detector.html b/python_client/docs/Detector.html new file mode 100644 index 000000000..9372dc232 --- /dev/null +++ b/python_client/docs/Detector.html @@ -0,0 +1,14 @@ + Detector — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Detector

Properties

Name

Type

Description

Notes

description

str

serial_number

str

[optional] [default to ‘Unknown’]

type

DetectorType

[optional]

high_voltage_v

int

[optional] [default to 0]

udp_interface_count

int

[optional] [default to 1]

module_sync

bool

Use module 0 as master for timing. Only applies to JUNGFRAU detector (this cannot be turned off for EIGER).

[optional] [default to True]

sensor_thickness_um

float

[optional] [default to 320]

readout_time_ns

int

Minimum difference between frame time and count time in nanoseconds Defaults are 3’000 ns for EIGER and 20’000 ns for JUNGFRAU

[optional]

min_count_time_ns

int

Minimum count time available for the detector.

[optional]

min_frame_time_ns

int

Minimum frame time available for the detector.

[optional]

calibration_file

List[str]

Can be empty for all detectors - default calibration used. For JUNGFRAU: list of gain files, one entry per module. For EIGER: one directory (with detector settings) or list of trim bit files, one entry per half-module.

[optional]

trim_energies_e_v

List[int]

List of energies at which trimming calibration is provided. Only needed for PSI EIGER and compulsory in this case

[optional]

hostname

List[str]

Hostnames of the detector modules: one entry per module for JUNGFRAU, two per module for EIGER (one per half-module). Either empty or the full list.

[optional]

sensor_material

str

[optional] [default to ‘Si’]

tx_delay

List[int]

[optional]

base_data_ipv4_address

str

[optional]

standard_geometry

StandardDetectorGeometry

[optional]

custom_geometry

List[DetectorModule]

[optional]

roi_mode

str

ROI setting for DECTRIS detectors

[optional] [default to ‘’]

mirror_y

bool

Mirror detector in Y direction to account for MX convention of (0,0) point in top left corner

[optional] [default to True]

temp_thresold_deg_c

int

Temperature threshold for JUNGFRAU detector modules

[optional] [default to 55]

default_settings

DetectorSettings

[optional]

Example

from jfjoch_client.models.detector import Detector
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of Detector from a JSON string
+detector_instance = Detector.from_json(json)
+# print the JSON string representation of the object
+print(Detector.to_json())
+
+# convert the object into a dict
+detector_dict = detector_instance.to_dict()
+# create an instance of Detector from a dict
+detector_from_dict = Detector.from_dict(detector_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorList.html b/python_client/docs/DetectorList.html new file mode 100644 index 000000000..ec27fb8b2 --- /dev/null +++ b/python_client/docs/DetectorList.html @@ -0,0 +1,14 @@ + DetectorList — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DetectorList

Properties

Name

Type

Description

Notes

detectors

List[DetectorListElement]

current_id

int

Example

from jfjoch_client.models.detector_list import DetectorList
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DetectorList from a JSON string
+detector_list_instance = DetectorList.from_json(json)
+# print the JSON string representation of the object
+print(DetectorList.to_json())
+
+# convert the object into a dict
+detector_list_dict = detector_list_instance.to_dict()
+# create an instance of DetectorList from a dict
+detector_list_from_dict = DetectorList.from_dict(detector_list_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorListElement.html b/python_client/docs/DetectorListElement.html new file mode 100644 index 000000000..e0c265b5f --- /dev/null +++ b/python_client/docs/DetectorListElement.html @@ -0,0 +1,14 @@ + DetectorListElement — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DetectorListElement

Properties

Name

Type

Description

Notes

id

int

description

str

serial_number

str

base_ipv4_addr

str

udp_interface_count

int

Number of UDP interfaces per detector module

nmodules

int

width

int

height

int

pixel_size_mm

float

[optional]

readout_time_ns

int

min_frame_time_ns

int

min_count_time_ns

int

type

DetectorType

[optional]

Example

from jfjoch_client.models.detector_list_element import DetectorListElement
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DetectorListElement from a JSON string
+detector_list_element_instance = DetectorListElement.from_json(json)
+# print the JSON string representation of the object
+print(DetectorListElement.to_json())
+
+# convert the object into a dict
+detector_list_element_dict = detector_list_element_instance.to_dict()
+# create an instance of DetectorListElement from a dict
+detector_list_element_from_dict = DetectorListElement.from_dict(detector_list_element_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorModule.html b/python_client/docs/DetectorModule.html new file mode 100644 index 000000000..c40317508 --- /dev/null +++ b/python_client/docs/DetectorModule.html @@ -0,0 +1,14 @@ + DetectorModule — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DetectorModule

One module of custom_geometry: where its readout pixel 0 goes in the assembled image and which way its fast and slow readout axes run there. Frame: custom_geometry is BEFORE mirror_y (the image as assembled from the readout); module_placement is AFTER mirror_y (the image as stored, the only one a file reader sees). Same words in both: x0/y0 is the image position of the module’s readout pixel 0 and fast_axis/slow_axis say which way its fast and slow readout axes run in the image. With mirror_y on, a module’s entry differs between the two by the mirror: for an image of height H, y0 (module_placement) = H - 1 - y0 (custom_geometry), x0 is the same, and Yp and Yn swap in fast_axis/slow_axis. With mirror_y off they are equal.

Properties

Name

Type

Description

Notes

x0

float

Image x of the module’s readout pixel 0, before mirror_y

y0

float

Image y of the module’s readout pixel 0, before mirror_y

fast_axis

DetectorModuleDirection

slow_axis

DetectorModuleDirection

Example

from jfjoch_client.models.detector_module import DetectorModule
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DetectorModule from a JSON string
+detector_module_instance = DetectorModule.from_json(json)
+# print the JSON string representation of the object
+print(DetectorModule.to_json())
+
+# convert the object into a dict
+detector_module_dict = detector_module_instance.to_dict()
+# create an instance of DetectorModule from a dict
+detector_module_from_dict = DetectorModule.from_dict(detector_module_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorModuleDirection.html b/python_client/docs/DetectorModuleDirection.html new file mode 100644 index 000000000..72626e508 --- /dev/null +++ b/python_client/docs/DetectorModuleDirection.html @@ -0,0 +1 @@ + DetectorModuleDirection — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/DetectorModulePlacement.html b/python_client/docs/DetectorModulePlacement.html new file mode 100644 index 000000000..766db555e --- /dev/null +++ b/python_client/docs/DetectorModulePlacement.html @@ -0,0 +1,14 @@ + DetectorModulePlacement — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DetectorModulePlacement

One module of the image and where it lies on the detector plane, as rugnux measures it. Frame: custom_geometry is BEFORE mirror_y (the image as assembled from the readout); module_placement is AFTER mirror_y (the image as stored, the only one a file reader sees). Same words in both: x0/y0 is the image position of the module’s readout pixel 0 and fast_axis/slow_axis say which way its fast and slow readout axes run in the image. With mirror_y on, a module’s entry differs between the two by the mirror: for an image of height H, y0 (module_placement) = H - 1 - y0 (custom_geometry), x0 is the same, and Yp and Yn swap in fast_axis/slow_axis. With mirror_y off they are equal. x0, y0, fast_axis and slow_axis identify the module, whatever the order of the entries, and with the module size they give its box in the image. The plane is in image pixels (a pixel’s centre at its index): readout pixel (i, j) - i along the fast axis, j along the slow axis from pixel 0 - lies on it at (x0_plane, y0_plane) + i fast_step + j slow_step. As assembled: x0_plane = x0, y0_plane = y0, and each step is the unit vector of its axis (Xp = [1, 0], Xn = [-1, 0], Yp = [0, 1], Yn = [0, -1]).

Properties

Name

Type

Description

Notes

x0

int

Image x of the module’s readout pixel 0, after mirror_y

y0

int

Image y of the module’s readout pixel 0, after mirror_y

fast_axis

DetectorModuleDirection

slow_axis

DetectorModuleDirection

x0_plane

float

Plane x of readout pixel 0, in image pixels

y0_plane

float

Plane y of readout pixel 0, in image pixels

fast_step

List[float]

Plane displacement (x, y) for one pixel along the fast readout axis

slow_step

List[float]

Plane displacement (x, y) for one pixel along the slow readout axis

Example

from jfjoch_client.models.detector_module_placement import DetectorModulePlacement
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DetectorModulePlacement from a JSON string
+detector_module_placement_instance = DetectorModulePlacement.from_json(json)
+# print the JSON string representation of the object
+print(DetectorModulePlacement.to_json())
+
+# convert the object into a dict
+detector_module_placement_dict = detector_module_placement_instance.to_dict()
+# create an instance of DetectorModulePlacement from a dict
+detector_module_placement_from_dict = DetectorModulePlacement.from_dict(detector_module_placement_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorPowerState.html b/python_client/docs/DetectorPowerState.html new file mode 100644 index 000000000..9f5852ab1 --- /dev/null +++ b/python_client/docs/DetectorPowerState.html @@ -0,0 +1 @@ + DetectorPowerState — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/DetectorSelection.html b/python_client/docs/DetectorSelection.html new file mode 100644 index 000000000..3a1cc9e08 --- /dev/null +++ b/python_client/docs/DetectorSelection.html @@ -0,0 +1,14 @@ + DetectorSelection — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DetectorSelection

Properties

Name

Type

Description

Notes

id

int

Example

from jfjoch_client.models.detector_selection import DetectorSelection
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DetectorSelection from a JSON string
+detector_selection_instance = DetectorSelection.from_json(json)
+# print the JSON string representation of the object
+print(DetectorSelection.to_json())
+
+# convert the object into a dict
+detector_selection_dict = detector_selection_instance.to_dict()
+# create an instance of DetectorSelection from a dict
+detector_selection_from_dict = DetectorSelection.from_dict(detector_selection_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorSettings.html b/python_client/docs/DetectorSettings.html new file mode 100644 index 000000000..f372e62a2 --- /dev/null +++ b/python_client/docs/DetectorSettings.html @@ -0,0 +1,14 @@ + DetectorSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DetectorSettings

Properties

Name

Type

Description

Notes

frame_time_us

int

Interval between consecutive frames. This is internal frame time for the JUNGFRAU detector, image time has to be integer multiply of this number. For EIGER detector this is default frame time, not used otherwise

count_time_us

int

Integration time of the detector. If not provided count time will be set to maximum value for a given frame time.

[optional]

internal_frame_generator

bool

Use internal frame generator in FPGA instead of getting data from a real detector

[optional] [default to False]

internal_frame_generator_images

int

Number of images stored in the internal frame generator.

[optional] [default to 1]

detector_trigger_delay_ns

int

Delay between TTL trigger and acquisition start [ns]

[optional] [default to 0]

timing

DetectorTiming

[optional] [default to DetectorTiming.TRIGGER]

eiger_threshold_ke_v

float

Threshold for the PSI EIGER detector and all DECTRIS detectors. If value is provided, it will be used for all subsequent acquisitions, irrespective of beam energy. If value is not provided, threshold will be determined on start of acquisition as half of incident energy. This might lead to increased start time.

[optional]

eiger_bit_depth

int

Bit depth of PSI EIGER read-out. This is If value is not provided, depth will be determined based on the image time: * Exposure time < 500 microseconds depth of 8 bit will be used, * 500 <= exposure time < 2622 microseconds depth of 16 bit will be used * Exposure time >= 2622 microseconds depth of 32 bit will be used.

[optional]

jungfrau_pedestal_g0_frames

int

[optional] [default to 2000]

jungfrau_pedestal_g1_frames

int

[optional] [default to 300]

jungfrau_pedestal_g2_frames

int

[optional] [default to 300]

jungfrau_pedestal_min_image_count

int

Minimum number of collected images for pedestal to consider it viable

[optional] [default to 128]

jungfrau_storage_cell_count

int

[optional] [default to 1]

jungfrau_storage_cell_delay_ns

int

Delay between two storage cells [ns]

[optional] [default to 5000]

jungfrau_fixed_gain_g1

bool

Fix gain to G1 (can be useful for storage cells)

[optional] [default to False]

jungfrau_use_gain_hg0

bool

Use high G0 (for low energy applications)

[optional] [default to False]

Example

from jfjoch_client.models.detector_settings import DetectorSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DetectorSettings from a JSON string
+detector_settings_instance = DetectorSettings.from_json(json)
+# print the JSON string representation of the object
+print(DetectorSettings.to_json())
+
+# convert the object into a dict
+detector_settings_dict = detector_settings_instance.to_dict()
+# create an instance of DetectorSettings from a dict
+detector_settings_from_dict = DetectorSettings.from_dict(detector_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorState.html b/python_client/docs/DetectorState.html new file mode 100644 index 000000000..58f7081bc --- /dev/null +++ b/python_client/docs/DetectorState.html @@ -0,0 +1 @@ + DetectorState — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/DetectorStatus.html b/python_client/docs/DetectorStatus.html new file mode 100644 index 000000000..3804cd085 --- /dev/null +++ b/python_client/docs/DetectorStatus.html @@ -0,0 +1,14 @@ + DetectorStatus — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

DetectorStatus

Properties

Name

Type

Description

Notes

state

DetectorState

powerchip

DetectorPowerState

server_version

str

Detector server (on read-out boards) version

number_of_triggers_left

int

Remaining triggers to the detector (max of all modules)

fpga_temp_deg_c

List[int]

Temperature of detector FPGAs

high_voltage_v

List[int]

High voltage for detector modules

Example

from jfjoch_client.models.detector_status import DetectorStatus
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of DetectorStatus from a JSON string
+detector_status_instance = DetectorStatus.from_json(json)
+# print the JSON string representation of the object
+print(DetectorStatus.to_json())
+
+# convert the object into a dict
+detector_status_dict = detector_status_instance.to_dict()
+# create an instance of DetectorStatus from a dict
+detector_status_from_dict = DetectorStatus.from_dict(detector_status_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/DetectorTiming.html b/python_client/docs/DetectorTiming.html new file mode 100644 index 000000000..e570f64cf --- /dev/null +++ b/python_client/docs/DetectorTiming.html @@ -0,0 +1 @@ + DetectorTiming — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/DetectorType.html b/python_client/docs/DetectorType.html new file mode 100644 index 000000000..d3f88e452 --- /dev/null +++ b/python_client/docs/DetectorType.html @@ -0,0 +1 @@ + DetectorType — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/ErrorMessage.html b/python_client/docs/ErrorMessage.html new file mode 100644 index 000000000..7c15b6606 --- /dev/null +++ b/python_client/docs/ErrorMessage.html @@ -0,0 +1,14 @@ + ErrorMessage — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ErrorMessage

Properties

Name

Type

Description

Notes

msg

str

Human readable message

reason

str

Enumerate field for automated analysis

Example

from jfjoch_client.models.error_message import ErrorMessage
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ErrorMessage from a JSON string
+error_message_instance = ErrorMessage.from_json(json)
+# print the JSON string representation of the object
+print(ErrorMessage.to_json())
+
+# convert the object into a dict
+error_message_dict = error_message_instance.to_dict()
+# create an instance of ErrorMessage from a dict
+error_message_from_dict = ErrorMessage.from_dict(error_message_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/FileWriterFormat.html b/python_client/docs/FileWriterFormat.html new file mode 100644 index 000000000..e57b86627 --- /dev/null +++ b/python_client/docs/FileWriterFormat.html @@ -0,0 +1 @@ + FileWriterFormat — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FileWriterFormat

NoFileWritten - no files are written at all NXmxOnlyData - only data files are written, no master file NXmxLegacy - legacy format with soft links to data files in the master file; necessary for DECTRIS Albula 4.0 and DECTRIS Neggia NXmxVDS - newer format with virtual dataset linking data files in the master file, also includes better metadata handling NXmxIntegrated - single HDF5 per dataset CBF - DEPRECATED, no longer supported; kept for back compatibility only. Requests using this value are rejected. Only HDF5 formats are written. TIFF - DEPRECATED, no longer supported; kept for back compatibility only. Requests using this value are rejected. Only HDF5 formats are written.

Enum

  • NXMXONLYDATA (value: 'NXmxOnlyData')

  • NXMXLEGACY (value: 'NXmxLegacy')

  • NXMXVDS (value: 'NXmxVDS')

  • NXMXINTEGRATED (value: 'NXmxIntegrated')

  • CBF (value: 'CBF')

  • TIFF (value: 'TIFF')

  • NOFILEWRITTEN (value: 'NoFileWritten')

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/FileWriterSettings.html b/python_client/docs/FileWriterSettings.html new file mode 100644 index 000000000..87f87c196 --- /dev/null +++ b/python_client/docs/FileWriterSettings.html @@ -0,0 +1,14 @@ + FileWriterSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FileWriterSettings

Properties

Name

Type

Description

Notes

overwrite

bool

Inform jfjoch_write to overwrite existing files. Otherwise files would be saved with .h5.{timestamp}.tmp suffix.

[optional] [default to False]

format

FileWriterFormat

[optional] [default to FileWriterFormat.NXMXVDS]

Example

from jfjoch_client.models.file_writer_settings import FileWriterSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of FileWriterSettings from a JSON string
+file_writer_settings_instance = FileWriterSettings.from_json(json)
+# print the JSON string representation of the object
+print(FileWriterSettings.to_json())
+
+# convert the object into a dict
+file_writer_settings_dict = file_writer_settings_instance.to_dict()
+# create an instance of FileWriterSettings from a dict
+file_writer_settings_from_dict = FileWriterSettings.from_dict(file_writer_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/FpgaStatusInner.html b/python_client/docs/FpgaStatusInner.html new file mode 100644 index 000000000..65c91432d --- /dev/null +++ b/python_client/docs/FpgaStatusInner.html @@ -0,0 +1,14 @@ + FpgaStatusInner — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

FpgaStatusInner

Properties

Name

Type

Description

Notes

pci_dev_id

str

serial_number

str

fw_version

str

base_mac_addr

str

eth_link_count

int

eth_link_status

int

power_usage_w

float

fpga_temp_c

float

hbm_temp_c

float

packets_udp

int

packets_sls

int

idle

bool

pcie_link_speed

int

PCIe link speed measured by generation (expected value is 4 == PCIe Gen4)

pcie_link_width

int

PCIe link width (expected value is 8 == x8)

Example

from jfjoch_client.models.fpga_status_inner import FpgaStatusInner
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of FpgaStatusInner from a JSON string
+fpga_status_inner_instance = FpgaStatusInner.from_json(json)
+# print the JSON string representation of the object
+print(FpgaStatusInner.to_json())
+
+# convert the object into a dict
+fpga_status_inner_dict = fpga_status_inner_instance.to_dict()
+# create an instance of FpgaStatusInner from a dict
+fpga_status_inner_from_dict = FpgaStatusInner.from_dict(fpga_status_inner_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/GeomRefinementAlgorithm.html b/python_client/docs/GeomRefinementAlgorithm.html new file mode 100644 index 000000000..f747161bf --- /dev/null +++ b/python_client/docs/GeomRefinementAlgorithm.html @@ -0,0 +1 @@ + GeomRefinementAlgorithm — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

GeomRefinementAlgorithm

Selection of an post-indexing least-square diffraction geometry refinement algorithm used by Jungfraujoch. BeamCenter - This option is refining both beam center and lattice (restricted to a chosen/detected Bravais lattice). OrientationOnly - This option is refining only orientation of the lattice. Flex - Tries all per-image refinements and keeps whichever indexes the most spots, letting the pipeline decide (the rugnux flex mode).

Enum

  • BEAMCENTER (value: 'BeamCenter')

  • ORIENTATIONONLY (value: 'OrientationOnly')

  • FLEX (value: 'Flex')

  • NONE (value: 'None')

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/GridScan.html b/python_client/docs/GridScan.html new file mode 100644 index 000000000..d48dbc3c0 --- /dev/null +++ b/python_client/docs/GridScan.html @@ -0,0 +1,14 @@ + GridScan — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

GridScan

Definition of a grid scan. Combine it with a goniometer axis to state the angle the spindle stood at: send goniometer with step 0 and the start angle of the grid scan, and that angle is written per image into the NXmx sample transformation chain. Without one the spindle is recorded at 0, which says that nobody stated an angle rather than that the spindle stood at 0.

Properties

Name

Type

Description

Notes

n_fast

int

Number of elements in the fast direction

step_x_um

float

Step in grid along the fast direction. Can be negative. Positive number: left to right Negative number: right to left

step_y_um

float

Step in grid along the slow direction. Can be negative. Positive number: top to bottom Negative number: bottom to top

vertical

bool

If disabled: fast direction = X, slow direction = Y If enabled: fast direction = Y, slow direction = X

[optional] [default to False]

snake

bool

Flip fast direction for every second row

[optional] [default to False]

Example

from jfjoch_client.models.grid_scan import GridScan
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of GridScan from a JSON string
+grid_scan_instance = GridScan.from_json(json)
+# print the JSON string representation of the object
+print(GridScan.to_json())
+
+# convert the object into a dict
+grid_scan_dict = grid_scan_instance.to_dict()
+# create an instance of GridScan from a dict
+grid_scan_from_dict = GridScan.from_dict(grid_scan_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ImageBufferStatus.html b/python_client/docs/ImageBufferStatus.html new file mode 100644 index 000000000..bd77fc02f --- /dev/null +++ b/python_client/docs/ImageBufferStatus.html @@ -0,0 +1,14 @@ + ImageBufferStatus — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ImageBufferStatus

Properties

Name

Type

Description

Notes

min_image_number

int

Smallest image number available in the buffer

max_image_number

int

Largest image number available in the buffer

image_numbers

List[int]

Image numbers currently present in the buffer.

total_slots

int

Number of slots in the image buffer. This number, compared to number of images in data collection and frame rate will determine &quot;retention&quot; rate of the image buffer.

available_slots

int

Slots available for the data collection

in_preparation_slots

int

Number of slots in the image buffer that are currently in preparation for sending.

in_sending_slots

int

Number of slots in the image buffer that are currently sending/writing data.

current_counter

int

Counter of changes in the image buffer - either new start message or new image added. For optimization one can only load new images/datasets from the HTTP if this value changes. Counter is optional as it was not implemented in older versions to avoid breaking change

[optional]

Example

from jfjoch_client.models.image_buffer_status import ImageBufferStatus
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ImageBufferStatus from a JSON string
+image_buffer_status_instance = ImageBufferStatus.from_json(json)
+# print the JSON string representation of the object
+print(ImageBufferStatus.to_json())
+
+# convert the object into a dict
+image_buffer_status_dict = image_buffer_status_instance.to_dict()
+# create an instance of ImageBufferStatus from a dict
+image_buffer_status_from_dict = ImageBufferStatus.from_dict(image_buffer_status_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ImageFormatSettings.html b/python_client/docs/ImageFormatSettings.html new file mode 100644 index 000000000..cb6e91a3a --- /dev/null +++ b/python_client/docs/ImageFormatSettings.html @@ -0,0 +1,14 @@ + ImageFormatSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ImageFormatSettings

Properties

Name

Type

Description

Notes

summation

bool

Enable summation of images to a given image_time If disabled images are saved according to original detector speed, but image count is adjusted

geometry_transform

bool

Place module read-out into their location on composed detector and extend multipixels

jungfrau_conversion

bool

Convert pixel value in ADU to photon counts/energy Only affects JUNGFRAU detector

jungfrau_conversion_factor_ke_v

float

Used to convert energy deposited into pixel to counts If not provided incident_energy_keV is used

[optional]

bit_depth_image

int

Bit depth of resulting image (it doesn’t affect the detector read-out value) If not provided value is adjusted automatically

[optional]

signed_output

bool

Controls if pixels have signed output If not provided value is adjusted automatically

[optional]

mask_module_edges

bool

Mask 1 pixel on the module boundary

[default to True]

mask_chip_edges

bool

Mask multipixels on chip boundary

[default to True]

jungfrau_mask_pixels_without_g0

bool

JUNGFRAU: mask pixels that don’t operate in G0, but do operate in G1 and G1. This should be turned off for cases, where detector is operated at room temperature with long exposure time.

[optional] [default to True]

apply_mask

bool

Masked pixels are set to special value in the images produced by Jungfraujoch

[default to False]

jungfrau_pedestal_g0_rms_limit

int

Pixels with pedestal G0 RMS above the threshold are marked as masked pixels

[optional] [default to 100]

Example

from jfjoch_client.models.image_format_settings import ImageFormatSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ImageFormatSettings from a JSON string
+image_format_settings_instance = ImageFormatSettings.from_json(json)
+# print the JSON string representation of the object
+print(ImageFormatSettings.to_json())
+
+# convert the object into a dict
+image_format_settings_dict = image_format_settings_instance.to_dict()
+# create an instance of ImageFormatSettings from a dict
+image_format_settings_from_dict = ImageFormatSettings.from_dict(image_format_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ImagePusherStatus.html b/python_client/docs/ImagePusherStatus.html new file mode 100644 index 000000000..07186a6f8 --- /dev/null +++ b/python_client/docs/ImagePusherStatus.html @@ -0,0 +1,14 @@ + ImagePusherStatus — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ImagePusherStatus

Informs about status of the image pusher.

Properties

Name

Type

Description

Notes

pusher_type

ImagePusherType

[default to ImagePusherType.NONE]

addr

List[str]

List of addresses of image pushers. For HDF5 socket - no addresses will be returned. For ZeroMQ - list of addresses for each socket will be provided. For TCP/IP - single address to connect all writers will be provided.

connected_writers

int

Number of connected writers For ZeroMQ image socket: number is constant For TCP/IP image socket: number is updated live during operation

images_written

int

Number of images written to the image socket. This number is updated live during operation for TCP/IP image socket and direct HDF5 writer. It is updated at the end of experiment for ZeroMQ image socket.

[optional]

images_write_error

int

Number of images that could not be written to the image socket. This number is updated live during operation for TCP/IP image socket. No other socket use it.

[optional]

writer_fifo_utilization

List[int]

Utilization of internal writer FIFO. This number is updated live during operation for TCP/IP image socket. No other socket use it.

[optional]

Example

from jfjoch_client.models.image_pusher_status import ImagePusherStatus
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ImagePusherStatus from a JSON string
+image_pusher_status_instance = ImagePusherStatus.from_json(json)
+# print the JSON string representation of the object
+print(ImagePusherStatus.to_json())
+
+# convert the object into a dict
+image_pusher_status_dict = image_pusher_status_instance.to_dict()
+# create an instance of ImagePusherStatus from a dict
+image_pusher_status_from_dict = ImagePusherStatus.from_dict(image_pusher_status_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ImagePusherType.html b/python_client/docs/ImagePusherType.html new file mode 100644 index 000000000..f24f33e35 --- /dev/null +++ b/python_client/docs/ImagePusherType.html @@ -0,0 +1 @@ + ImagePusherType — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/IndexingAlgorithm.html b/python_client/docs/IndexingAlgorithm.html new file mode 100644 index 000000000..60bda3160 --- /dev/null +++ b/python_client/docs/IndexingAlgorithm.html @@ -0,0 +1 @@ + IndexingAlgorithm — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/IndexingSettings.html b/python_client/docs/IndexingSettings.html new file mode 100644 index 000000000..86dad42ef --- /dev/null +++ b/python_client/docs/IndexingSettings.html @@ -0,0 +1,14 @@ + IndexingSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

IndexingSettings

Settings for crystallography indexing

Properties

Name

Type

Description

Notes

algorithm

IndexingAlgorithm

[default to IndexingAlgorithm.FFBIDX]

fft_max_unit_cell_a

float

Largest unit cell to be indexed by FFT algorithm; parameter value affects execution time of FFT

[default to 250]

fft_min_unit_cell_a

float

Smallest unit cell to be indexed by FFT algorithm; parameter value affects execution time of FFT

[default to 10.0]

fft_high_resolution_a

float

Sets how finely the FFT samples each search direction: it fixes the extent of the projection histogram, and with it the transform size, so it affects execution time and memory of FFT. It does NOT filter spots - every spot is projected whatever its resolution, so raising it does not make the transform see a coarser subset of the data. There is also correlation between smallest unit cell and this value, which need to be checked for very small systems.

[default to 2.0]

fft_num_vectors

int

Number of search directions for the FFT algorithm; parameter value affects execution time of FFT.

[default to 16384]

tolerance

float

Acceptance tolerance for spots after the indexing run - the larger the number, the more spots will be accepted

thread_count

int

Thread count for indexing algorithm

geom_refinement_algorithm

GeomRefinementAlgorithm

unit_cell_dist_tolerance

float

Relative distance tolerance for unit cell vs. reference; Lattices outside given tolerance will be ignored

[default to 0.05]

viable_cell_min_spots

int

Minimum number of indexed spots required for a cell to be considered viable

[default to 10]

index_ice_rings

bool

Include spots marked as ice rings in the indexing run. If `dataset_settings` doesn’t have `detect_ice_rings` on, this option will have no effect on processing.

[default to False]

rotation_indexing

bool

Ignored: accepted on input and always returned as false; will be removed in a future release. The Lite and FPGA workflows index each image on its own, rotation or not; rotation indexing is done by rugnux live.

[optional] [default to False]

rotation_indexing_min_angular_range_deg

float

Ignored, as `rotation_indexing`; always returned as 20.0.

[optional] [default to 20.0]

rotation_indexing_angular_stride_deg

float

Ignored, as `rotation_indexing`; always returned as 0.5.

[optional] [default to 0.5]

blocking

bool

Indexing in Jungfraujoch goes with a dedicated thread pool. If set to false, the thread pool is non-blocking, i.e. if there are no threads available, image indexing will be skipped. This option is recommended for real-time processing at high frame rates. If set to true, the thread pool will block until a thread is available.

[default to True]

Example

from jfjoch_client.models.indexing_settings import IndexingSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of IndexingSettings from a JSON string
+indexing_settings_instance = IndexingSettings.from_json(json)
+# print the JSON string representation of the object
+print(IndexingSettings.to_json())
+
+# convert the object into a dict
+indexing_settings_dict = indexing_settings_instance.to_dict()
+# create an instance of IndexingSettings from a dict
+indexing_settings_from_dict = IndexingSettings.from_dict(indexing_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/InstrumentMetadata.html b/python_client/docs/InstrumentMetadata.html new file mode 100644 index 000000000..babc39bc6 --- /dev/null +++ b/python_client/docs/InstrumentMetadata.html @@ -0,0 +1,14 @@ + InstrumentMetadata — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

InstrumentMetadata

Metadata for a measurement instrument

Properties

Name

Type

Description

Notes

source_name

str

source_type

str

Type of radiation source. NXmx gives a fixed dictionary, though Jungfraujoch is not enforcing compliance. https://manual.nexusformat.org/classes/base_classes/NXsource.html#nxsource NXsource allows the following: Spallation Neutron Source Pulsed Reactor Neutron Source Reactor Neutron Source Synchrotron X-ray Source Pulsed Muon Source Rotating Anode X-ray Fixed Tube X-ray UV Laser Free-Electron Laser Optical Laser Ion Source UV Plasma Source Metal Jet X-ray

[optional] [default to ‘’]

instrument_name

str

pulsed_source

bool

Settings specific to XFEL (e.g., every image has to come from TTL trigger, save pulse ID and event code)

[optional] [default to False]

electron_source

bool

Settings specific to electron source (e.g., wavelength definition)

[optional] [default to False]

Example

from jfjoch_client.models.instrument_metadata import InstrumentMetadata
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of InstrumentMetadata from a JSON string
+instrument_metadata_instance = InstrumentMetadata.from_json(json)
+# print the JSON string representation of the object
+print(InstrumentMetadata.to_json())
+
+# convert the object into a dict
+instrument_metadata_dict = instrument_metadata_instance.to_dict()
+# create an instance of InstrumentMetadata from a dict
+instrument_metadata_from_dict = InstrumentMetadata.from_dict(instrument_metadata_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/IntegrationModel.html b/python_client/docs/IntegrationModel.html new file mode 100644 index 000000000..c9e60c78d --- /dev/null +++ b/python_client/docs/IntegrationModel.html @@ -0,0 +1 @@ + IntegrationModel — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

IntegrationModel

Bragg spot integration model. ProfileGaussian - profile fit with a measured-width Gaussian (Kabsch-style), the default; more accurate intensities than box summation. ProfileEmpirical - profile fit with a per-resolution-shell empirical profile learned from strong spots. BoxSum - classical uniform box summation minus a ring-mean background; the simpler, faster fallback.

Enum

  • PROFILEGAUSSIAN (value: 'ProfileGaussian')

  • PROFILEEMPIRICAL (value: 'ProfileEmpirical')

  • BOXSUM (value: 'BoxSum')

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/JfjochSettings.html b/python_client/docs/JfjochSettings.html new file mode 100644 index 000000000..25fef1787 --- /dev/null +++ b/python_client/docs/JfjochSettings.html @@ -0,0 +1,14 @@ + JfjochSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

JfjochSettings

Default settings for Jungfraujoch software. This structure is used to provide default settings using configuration JSON file and is not used in HTTP.

Properties

Name

Type

Description

Notes

pcie

List[PcieDevicesInner]

[optional]

zeromq

ZeromqSettings

[optional]

tcp

TcpSettings

[optional]

instrument

InstrumentMetadata

[optional]

file_writer

FileWriterSettings

[optional]

detector

List[Detector]

indexing

IndexingSettings

[optional]

bragg_integration

BraggIntegrationSettings

[optional]

detector_settings

DetectorSettings

[optional]

azim_int

AzimIntSettings

[optional]

image_format

ImageFormatSettings

[optional]

image_buffer_mi_b

int

Size of internal buffer in MiB for images before they are sent to a stream

[optional] [default to 2048]

verbose

bool

Print extra debug information

[optional] [default to False]

receiver_threads

int

Number of threads used by the receiver

[optional] [default to 64]

numa_policy

str

Ignored value

[optional]

frontend_directory

str

Location of built JavaScript web frontend

spot_finding

SpotFindingSettings

[optional]

image_pusher

ImagePusherType

[default to ImagePusherType.NONE]

zeromq_preview

ZeromqPreviewSettings

[optional]

zeromq_metadata

ZeromqMetadataSettings

[optional]

dark_mask

DarkMaskSettings

[optional]

rugnux

RugnuxSettings

[optional]

Example

from jfjoch_client.models.jfjoch_settings import JfjochSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of JfjochSettings from a JSON string
+jfjoch_settings_instance = JfjochSettings.from_json(json)
+# print the JSON string representation of the object
+print(JfjochSettings.to_json())
+
+# convert the object into a dict
+jfjoch_settings_dict = jfjoch_settings_instance.to_dict()
+# create an instance of JfjochSettings from a dict
+jfjoch_settings_from_dict = JfjochSettings.from_dict(jfjoch_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/JfjochStatistics.html b/python_client/docs/JfjochStatistics.html new file mode 100644 index 000000000..689273b82 --- /dev/null +++ b/python_client/docs/JfjochStatistics.html @@ -0,0 +1,14 @@ + JfjochStatistics — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

JfjochStatistics

Pool statistics for Jungfraujoch to reduce transfers between frontend and jfjoch_broker

Properties

Name

Type

Description

Notes

detector

DetectorStatus

[optional]

detector_list

DetectorList

[optional]

detector_settings

DetectorSettings

[optional]

image_format_settings

ImageFormatSettings

[optional]

instrument_metadata

InstrumentMetadata

[optional]

file_writer_settings

FileWriterSettings

[optional]

data_processing_settings

SpotFindingSettings

[optional]

measurement

MeasurementStatistics

[optional]

broker

BrokerStatus

[optional]

fpga

List[FpgaStatusInner]

[optional]

calibration

List[CalibrationStatisticsInner]

[optional]

zeromq_preview

ZeromqPreviewSettings

[optional]

zeromq_metadata

ZeromqMetadataSettings

[optional]

dark_mask

DarkMaskSettings

[optional]

pixel_mask

PixelMaskStatistics

[optional]

roi

RoiDefinitions

[optional]

az_int

AzimIntSettings

[optional]

buffer

ImageBufferStatus

[optional]

indexing

IndexingSettings

[optional]

bragg_integration

BraggIntegrationSettings

[optional]

image_pusher

ImagePusherStatus

[optional]

Example

from jfjoch_client.models.jfjoch_statistics import JfjochStatistics
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of JfjochStatistics from a JSON string
+jfjoch_statistics_instance = JfjochStatistics.from_json(json)
+# print the JSON string representation of the object
+print(JfjochStatistics.to_json())
+
+# convert the object into a dict
+jfjoch_statistics_dict = jfjoch_statistics_instance.to_dict()
+# create an instance of JfjochStatistics from a dict
+jfjoch_statistics_from_dict = JfjochStatistics.from_dict(jfjoch_statistics_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/MeasurementStatistics.html b/python_client/docs/MeasurementStatistics.html new file mode 100644 index 000000000..557c2d08e --- /dev/null +++ b/python_client/docs/MeasurementStatistics.html @@ -0,0 +1,14 @@ + MeasurementStatistics — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

MeasurementStatistics

Properties

Name

Type

Description

Notes

file_prefix

str

[optional]

run_number

int

Number of data collection run. This can be either automatically incremented or provided externally for each data collection.

[optional]

experiment_group

str

Name of group owning the data (e.g. p-group or proposal number).

[optional]

images_expected

int

[optional]

images_collected

int

Images collected by the receiver. This number will be lower than images expected if there were issues with data collection performance.

[optional]

images_sent

int

Images sent to the writer. The value does not include images discarded by lossy compression filter and images not forwarded due to full ZeroMQ queue.

[optional]

images_written

int

Images successfully written to disk. The value is live updated for TCP/IP socket and direct HDF5 writer, while for ZeroMQ it is only updated at the end of experiment.

[optional]

images_discarded_lossy_compression

int

Images discarded by the lossy compression filter

[optional]

max_image_number_sent

int

[optional]

collection_efficiency

float

[optional]

compression_ratio

float

[optional]

cancelled

bool

[optional]

max_receiver_delay

int

[optional]

indexing_rate

float

[optional]

detector_width

int

[optional]

detector_height

int

[optional]

detector_pixel_depth

int

[optional]

bkg_estimate

float

[optional]

unit_cell

str

[optional]

error_pixels

float

Moving average of 1000 images counting number of error pixels on the detector

[optional]

saturated_pixels

float

Moving average of 1000 images counting number of saturated pixels on the detector

[optional]

roi_beam_pixels

float

If there is an ROI defined with name &quot;beam&quot;, this number will hold moving average of 1000 images for number of valid pixels within this ROI

[optional]

roi_beam_sum

float

If there is an ROI defined with name &quot;beam&quot;, this number will hold moving average of 1000 images for sum of valid pixels within this ROI

[optional]

Example

from jfjoch_client.models.measurement_statistics import MeasurementStatistics
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of MeasurementStatistics from a JSON string
+measurement_statistics_instance = MeasurementStatistics.from_json(json)
+# print the JSON string representation of the object
+print(MeasurementStatistics.to_json())
+
+# convert the object into a dict
+measurement_statistics_dict = measurement_statistics_instance.to_dict()
+# create an instance of MeasurementStatistics from a dict
+measurement_statistics_from_dict = MeasurementStatistics.from_dict(measurement_statistics_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/PcieDevicesInner.html b/python_client/docs/PcieDevicesInner.html new file mode 100644 index 000000000..49980d3fd --- /dev/null +++ b/python_client/docs/PcieDevicesInner.html @@ -0,0 +1,14 @@ + PcieDevicesInner — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

PcieDevicesInner

Properties

Name

Type

Description

Notes

blk

str

Block device name

ipv4

str

IPv4 address of the block device

[optional]

Example

from jfjoch_client.models.pcie_devices_inner import PcieDevicesInner
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of PcieDevicesInner from a JSON string
+pcie_devices_inner_instance = PcieDevicesInner.from_json(json)
+# print the JSON string representation of the object
+print(PcieDevicesInner.to_json())
+
+# convert the object into a dict
+pcie_devices_inner_dict = pcie_devices_inner_instance.to_dict()
+# create an instance of PcieDevicesInner from a dict
+pcie_devices_inner_from_dict = PcieDevicesInner.from_dict(pcie_devices_inner_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/PixelMaskStatistics.html b/python_client/docs/PixelMaskStatistics.html new file mode 100644 index 000000000..701a21dd4 --- /dev/null +++ b/python_client/docs/PixelMaskStatistics.html @@ -0,0 +1,14 @@ + PixelMaskStatistics — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

PixelMaskStatistics

Properties

Name

Type

Description

Notes

user_mask

int

Number of pixels masked using the user mask

[optional]

too_high_pedestal_rms

int

Number of pixels with G0 pedestal RMS higher than provided threshold

[optional]

wrong_gain

int

Number of pixels that show wrong gain level during the pedestal procedure

[optional]

Example

from jfjoch_client.models.pixel_mask_statistics import PixelMaskStatistics
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of PixelMaskStatistics from a JSON string
+pixel_mask_statistics_instance = PixelMaskStatistics.from_json(json)
+# print the JSON string representation of the object
+print(PixelMaskStatistics.to_json())
+
+# convert the object into a dict
+pixel_mask_statistics_dict = pixel_mask_statistics_instance.to_dict()
+# create an instance of PixelMaskStatistics from a dict
+pixel_mask_statistics_from_dict = PixelMaskStatistics.from_dict(pixel_mask_statistics_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/Plot.html b/python_client/docs/Plot.html new file mode 100644 index 000000000..3c0386a91 --- /dev/null +++ b/python_client/docs/Plot.html @@ -0,0 +1,14 @@ + Plot — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Plot

x and y coordinates for plotting, it is OK to assume that both arrays have the same size; layout is optimized for Plotly

Properties

Name

Type

Description

Notes

title

str

[default to ‘’]

x

List[float]

y

List[Optional[float]]

z

List[Optional[float]]

[optional]

Example

from jfjoch_client.models.plot import Plot
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of Plot from a JSON string
+plot_instance = Plot.from_json(json)
+# print the JSON string representation of the object
+print(Plot.to_json())
+
+# convert the object into a dict
+plot_dict = plot_instance.to_dict()
+# create an instance of Plot from a dict
+plot_from_dict = Plot.from_dict(plot_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/PlotUnitX.html b/python_client/docs/PlotUnitX.html new file mode 100644 index 000000000..845be7689 --- /dev/null +++ b/python_client/docs/PlotUnitX.html @@ -0,0 +1 @@ + PlotUnitX — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/Plots.html b/python_client/docs/Plots.html new file mode 100644 index 000000000..2b5cbeaad --- /dev/null +++ b/python_client/docs/Plots.html @@ -0,0 +1,14 @@ + Plots — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

Plots

Properties

Name

Type

Description

Notes

title

str

[optional]

unit_x

PlotUnitX

[default to PlotUnitX.IMAGE_NUMBER]

size_x

float

Max X range of the plot

[optional]

size_y

float

Max Y range of the plot

[optional]

plot

List[Plot]

Example

from jfjoch_client.models.plots import Plots
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of Plots from a JSON string
+plots_instance = Plots.from_json(json)
+# print the JSON string representation of the object
+print(Plots.to_json())
+
+# convert the object into a dict
+plots_dict = plots_instance.to_dict()
+# create an instance of Plots from a dict
+plots_from_dict = Plots.from_dict(plots_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/PowderCalibrationFitSigma.html b/python_client/docs/PowderCalibrationFitSigma.html new file mode 100644 index 000000000..431a69bd1 --- /dev/null +++ b/python_client/docs/PowderCalibrationFitSigma.html @@ -0,0 +1,14 @@ + PowderCalibrationFitSigma — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

PowderCalibrationFitSigma

What the powder ring fit knows about its own answer, from the covariance of the converged problem. Each sigma is in its parameter’s own unit and is scaled by the residual scatter of that fit, so it is the usual “how far could this move before the fit got visibly worse”. The two correlations are the ones that matter: a tilt and a beam-centre shift both displace a ring’s radius as cos(phi) and are told apart only by how that amplitude grows with the ring’s radius, so as the rings run out the pair stops being separable and these approach 1. The rotation sigmas and the correlations are absent when the tilt was not a free parameter.

Properties

Name

Type

Description

Notes

beam_x_pxl

float

Standard error of the fitted PONI x [pixels]

[optional]

beam_y_pxl

float

Standard error of the fitted PONI y [pixels]

[optional]

detector_distance_mm

float

Standard error of the fitted detector distance [mm]

[optional]

poni_rot1_rad

float

Standard error of the fitted rot1 [rad]

[optional]

poni_rot2_rad

float

Standard error of the fitted rot2 [rad]

[optional]

correlation_beam_x_rot1

float

Correlation between the fitted PONI x and rot1, -1 to 1

[optional]

correlation_beam_y_rot2

float

Correlation between the fitted PONI y and rot2, -1 to 1

[optional]

Example

from jfjoch_client.models.powder_calibration_fit_sigma import PowderCalibrationFitSigma
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of PowderCalibrationFitSigma from a JSON string
+powder_calibration_fit_sigma_instance = PowderCalibrationFitSigma.from_json(json)
+# print the JSON string representation of the object
+print(PowderCalibrationFitSigma.to_json())
+
+# convert the object into a dict
+powder_calibration_fit_sigma_dict = powder_calibration_fit_sigma_instance.to_dict()
+# create an instance of PowderCalibrationFitSigma from a dict
+powder_calibration_fit_sigma_from_dict = PowderCalibrationFitSigma.from_dict(powder_calibration_fit_sigma_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/PowderCalibrationOutput.html b/python_client/docs/PowderCalibrationOutput.html new file mode 100644 index 000000000..8d9b22864 --- /dev/null +++ b/python_client/docs/PowderCalibrationOutput.html @@ -0,0 +1,100 @@ + PowderCalibrationOutput — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

PowderCalibrationOutput

The result of a powder-ring detector calibration - what rugnux –mode calibration writes as .json, and what a calibration run over the image buffer would return. dataset_settings holds the geometry and nothing else, under the property names this API gives them, so it can be POSTed or merged without translating a field. Its beam_x_pxl/beam_y_pxl is the PONI, the foot of the perpendicular from the sample; where the beam actually lands is calibration.direct_beam_x_pxl. The poni_rot*_rad are present whenever any of them is non-zero and absent when all are zero, since a body omitting them states a FLAT detector rather than an unstated one.

+
+

Properties

+ + +

Name

+

Type

+

Description

+

Notes

+ + + +

dataset_settings

+

DatasetSettings

+

+

+ +

calibration

+

PowderCalibrationQuality

+

+

[optional]

+ +

jfjoch_version

+

str

+

Version of the program that produced this

+

[optional]

+ + +
+
+
+

Example

+
from jfjoch_client.models.powder_calibration_output import PowderCalibrationOutput
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of PowderCalibrationOutput from a JSON string
+powder_calibration_output_instance = PowderCalibrationOutput.from_json(json)
+# print the JSON string representation of the object
+print(PowderCalibrationOutput.to_json())
+
+# convert the object into a dict
+powder_calibration_output_dict = powder_calibration_output_instance.to_dict()
+# create an instance of PowderCalibrationOutput from a dict
+powder_calibration_output_from_dict = PowderCalibrationOutput.from_dict(powder_calibration_output_dict)
+
+
+

[Back to Model list] [Back to API list] [Back to README]

+
+
+ + +
+
+
+
+
+ + + \ No newline at end of file diff --git a/python_client/docs/PowderCalibrationQuality.html b/python_client/docs/PowderCalibrationQuality.html new file mode 100644 index 000000000..dcc316ae8 --- /dev/null +++ b/python_client/docs/PowderCalibrationQuality.html @@ -0,0 +1,14 @@ + PowderCalibrationQuality — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

PowderCalibrationQuality

What a powder calibration knows about the geometry it produced. A calibration that has gone wrong - the wrong standard named, a header too far out for the rings to be found - looks exactly like one that has not until these are read.

Properties

Name

Type

Description

Notes

converged

bool

Whether the geometry beside this is a measurement of the data at all. False means at least one of its parameters was carried over from the input file rather than fitted - which looks exactly like a good fit in every other field here - and see not_converged_reason for which. rugnux –mode calibration writes no .poni file in that case, a PONI file having no field in which to say it, and exits non-zero.

[optional]

not_converged_reason

str

What made converged false, in words. Absent when the calibration converged.

[optional]

calibrant

str

The powder standard the rings were fitted to, or the unit cell given in its place

[optional]

method

str

How the rings were measured. rings fits the arcs of the run-summed (q x azimuth) azimuthal profile; spots fits the pooled per-image spot lists.

[optional]

ring_points

int

Ring measurements the fit used

[optional]

rms_radial_pxl

float

Scatter of those measurements about the fitted rings, as a radial distance [pixels]. The single number that separates a calibration that worked from one that did not.

[optional]

beam_sigma_pxl

float

Standard error the scatter implies on the beam centre [pixels], for a ring of that many points. See powder_calibration_fit_sigma for what the fit itself says, which is not the same and is the larger of the two whenever the tilt is poorly separated.

[optional]

direct_beam_x_pxl

float

Where the direct beam lands [pixels]. NOT dataset_settings.beam_x_pxl, which is the PONI: the two part company by distance*tan(tilt)/pixel as soon as the detector is tilted.

[optional]

direct_beam_y_pxl

float

Where the direct beam lands, y [pixels]

[optional]

header_distance_mm

float

The detector distance the input file declared, for comparison [mm]

[optional]

ring_seed_distance_mm

float

The distance measured from the ring radii before the fit ran [mm]. It is taken from the radii, the wavelength and the pixel size alone, so a large gap from header_distance_mm is the answer to the question the calibration was run to ask. Absent when the profile showed too few rings to fix a scale.

[optional]

tilt_refined

bool

Whether the reported rot1/rot2 were measured by this fit. False means they were declined and pinned at the input file’s values, because the rings could not separate a tilt from a shift of the beam centre.

[optional]

tilt_significance

float

How many of its own sigmas the fitted tilt stands from zero. Below about 3 it is not a measurement of a tilt but of a beam-centre shift, and the tilt is declined. Passing does not certify a tilt: that estimator is limited by systematics rather than by this sigma.

[optional]

fit_sigma

PowderCalibrationFitSigma

[optional]

spot_cross_check

PowderCalibrationSpotCheck

[optional]

Example

from jfjoch_client.models.powder_calibration_quality import PowderCalibrationQuality
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of PowderCalibrationQuality from a JSON string
+powder_calibration_quality_instance = PowderCalibrationQuality.from_json(json)
+# print the JSON string representation of the object
+print(PowderCalibrationQuality.to_json())
+
+# convert the object into a dict
+powder_calibration_quality_dict = powder_calibration_quality_instance.to_dict()
+# create an instance of PowderCalibrationQuality from a dict
+powder_calibration_quality_from_dict = PowderCalibrationQuality.from_dict(powder_calibration_quality_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/PowderCalibrationSpotCheck.html b/python_client/docs/PowderCalibrationSpotCheck.html new file mode 100644 index 000000000..0d4b24271 --- /dev/null +++ b/python_client/docs/PowderCalibrationSpotCheck.html @@ -0,0 +1,14 @@ + PowderCalibrationSpotCheck — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

PowderCalibrationSpotCheck

Where the circle through the found spots puts the beam, and how far that is from the geometry actually fitted. An independent cross-check: it reads nothing from the file’s own geometry, so it holds where the summed azimuthal profile does not - a profile binned about a badly wrong centre shows each ring smeared across its sectors, and a fit on it converges on the wrong answer without saying so. Two methods sharing no assumption, so the disagreement is the statement. Absent when no spots were available.

Properties

Name

Type

Description

Notes

beam_x_pxl

float

Beam centre x the spots vote for [pixels]

[optional]

beam_y_pxl

float

Beam centre y the spots vote for [pixels]

[optional]

detector_distance_mm

float

Detector distance the spots imply [mm]

[optional]

disagreement_pxl

float

Distance between the spots’ beam centre and the fitted one [pixels]

[optional]

Example

from jfjoch_client.models.powder_calibration_spot_check import PowderCalibrationSpotCheck
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of PowderCalibrationSpotCheck from a JSON string
+powder_calibration_spot_check_instance = PowderCalibrationSpotCheck.from_json(json)
+# print the JSON string representation of the object
+print(PowderCalibrationSpotCheck.to_json())
+
+# convert the object into a dict
+powder_calibration_spot_check_dict = powder_calibration_spot_check_instance.to_dict()
+# create an instance of PowderCalibrationSpotCheck from a dict
+powder_calibration_spot_check_from_dict = PowderCalibrationSpotCheck.from_dict(powder_calibration_spot_check_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/QBinning.html b/python_client/docs/QBinning.html new file mode 100644 index 000000000..0296930d5 --- /dev/null +++ b/python_client/docs/QBinning.html @@ -0,0 +1 @@ + QBinning — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/python_client/docs/RoiAzimList.html b/python_client/docs/RoiAzimList.html new file mode 100644 index 000000000..8b6cfd605 --- /dev/null +++ b/python_client/docs/RoiAzimList.html @@ -0,0 +1,14 @@ + RoiAzimList — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RoiAzimList

List of azimuthal ROIs

Properties

Name

Type

Description

Notes

rois

List[RoiAzimuthal]

[optional]

Example

from jfjoch_client.models.roi_azim_list import RoiAzimList
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RoiAzimList from a JSON string
+roi_azim_list_instance = RoiAzimList.from_json(json)
+# print the JSON string representation of the object
+print(RoiAzimList.to_json())
+
+# convert the object into a dict
+roi_azim_list_dict = roi_azim_list_instance.to_dict()
+# create an instance of RoiAzimList from a dict
+roi_azim_list_from_dict = RoiAzimList.from_dict(roi_azim_list_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RoiAzimuthal.html b/python_client/docs/RoiAzimuthal.html new file mode 100644 index 000000000..dec4a9b11 --- /dev/null +++ b/python_client/docs/RoiAzimuthal.html @@ -0,0 +1,14 @@ + RoiAzimuthal — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RoiAzimuthal

ROI as Q-range (or resolution range), optionally restricted to an azimuthal-angle sector

Properties

Name

Type

Description

Notes

name

str

Name for the ROI; used in the plots

q_min_recip_a

float

Minimum Q-range for the ROI

q_max_recip_a

float

Maximum Q-range for the ROI

phi_min_deg

float

Lower azimuthal-angle bound of the sector [degrees]. Optional: provide both phi_min_deg and phi_max_deg to restrict the ROI to an angular sector, or omit both for a full ring. A sector with phi_min_deg > phi_max_deg wraps across 0.

[optional]

phi_max_deg

float

Upper azimuthal-angle bound of the sector [degrees]. Optional; see phi_min_deg.

[optional]

Example

from jfjoch_client.models.roi_azimuthal import RoiAzimuthal
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RoiAzimuthal from a JSON string
+roi_azimuthal_instance = RoiAzimuthal.from_json(json)
+# print the JSON string representation of the object
+print(RoiAzimuthal.to_json())
+
+# convert the object into a dict
+roi_azimuthal_dict = roi_azimuthal_instance.to_dict()
+# create an instance of RoiAzimuthal from a dict
+roi_azimuthal_from_dict = RoiAzimuthal.from_dict(roi_azimuthal_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RoiBox.html b/python_client/docs/RoiBox.html new file mode 100644 index 000000000..08ffe849e --- /dev/null +++ b/python_client/docs/RoiBox.html @@ -0,0 +1,14 @@ + RoiBox — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RoiBox

Box ROI

Properties

Name

Type

Description

Notes

name

str

Name for the ROI; used in the plots

min_x_pxl

int

Lower bound (inclusive) in X coordinate for the box

max_x_pxl

int

Upper bound (inclusive) in X coordinate for the box

min_y_pxl

int

Lower bound (inclusive) in Y coordinate for the box

max_y_pxl

int

Upper bound (inclusive) in Y coordinate for the box

Example

from jfjoch_client.models.roi_box import RoiBox
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RoiBox from a JSON string
+roi_box_instance = RoiBox.from_json(json)
+# print the JSON string representation of the object
+print(RoiBox.to_json())
+
+# convert the object into a dict
+roi_box_dict = roi_box_instance.to_dict()
+# create an instance of RoiBox from a dict
+roi_box_from_dict = RoiBox.from_dict(roi_box_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RoiBoxList.html b/python_client/docs/RoiBoxList.html new file mode 100644 index 000000000..940bb5b2d --- /dev/null +++ b/python_client/docs/RoiBoxList.html @@ -0,0 +1,14 @@ + RoiBoxList — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RoiBoxList

List of box ROIs

Properties

Name

Type

Description

Notes

rois

List[RoiBox]

[optional]

Example

from jfjoch_client.models.roi_box_list import RoiBoxList
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RoiBoxList from a JSON string
+roi_box_list_instance = RoiBoxList.from_json(json)
+# print the JSON string representation of the object
+print(RoiBoxList.to_json())
+
+# convert the object into a dict
+roi_box_list_dict = roi_box_list_instance.to_dict()
+# create an instance of RoiBoxList from a dict
+roi_box_list_from_dict = RoiBoxList.from_dict(roi_box_list_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RoiCircle.html b/python_client/docs/RoiCircle.html new file mode 100644 index 000000000..21ed80ea0 --- /dev/null +++ b/python_client/docs/RoiCircle.html @@ -0,0 +1,14 @@ + RoiCircle — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RoiCircle

Circular ROI

Properties

Name

Type

Description

Notes

name

str

Name for the ROI; used in the plots

center_x_pxl

float

X coordinate of center of the circle [pixels]

center_y_pxl

float

Y coordinate of center of the circle [pixels]

radius_pxl

float

Radius of the circle [pixels]

Example

from jfjoch_client.models.roi_circle import RoiCircle
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RoiCircle from a JSON string
+roi_circle_instance = RoiCircle.from_json(json)
+# print the JSON string representation of the object
+print(RoiCircle.to_json())
+
+# convert the object into a dict
+roi_circle_dict = roi_circle_instance.to_dict()
+# create an instance of RoiCircle from a dict
+roi_circle_from_dict = RoiCircle.from_dict(roi_circle_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RoiCircleList.html b/python_client/docs/RoiCircleList.html new file mode 100644 index 000000000..d7578a727 --- /dev/null +++ b/python_client/docs/RoiCircleList.html @@ -0,0 +1,14 @@ + RoiCircleList — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RoiCircleList

List of circular ROIs

Properties

Name

Type

Description

Notes

rois

List[RoiCircle]

Example

from jfjoch_client.models.roi_circle_list import RoiCircleList
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RoiCircleList from a JSON string
+roi_circle_list_instance = RoiCircleList.from_json(json)
+# print the JSON string representation of the object
+print(RoiCircleList.to_json())
+
+# convert the object into a dict
+roi_circle_list_dict = roi_circle_list_instance.to_dict()
+# create an instance of RoiCircleList from a dict
+roi_circle_list_from_dict = RoiCircleList.from_dict(roi_circle_list_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RoiDefinitions.html b/python_client/docs/RoiDefinitions.html new file mode 100644 index 000000000..85897c7d5 --- /dev/null +++ b/python_client/docs/RoiDefinitions.html @@ -0,0 +1,14 @@ + RoiDefinitions — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RoiDefinitions

ROI defintions

Properties

Name

Type

Description

Notes

box

RoiBoxList

circle

RoiCircleList

azim

RoiAzimList

Example

from jfjoch_client.models.roi_definitions import RoiDefinitions
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RoiDefinitions from a JSON string
+roi_definitions_instance = RoiDefinitions.from_json(json)
+# print the JSON string representation of the object
+print(RoiDefinitions.to_json())
+
+# convert the object into a dict
+roi_definitions_dict = roi_definitions_instance.to_dict()
+# create an instance of RoiDefinitions from a dict
+roi_definitions_from_dict = RoiDefinitions.from_dict(roi_definitions_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RotationAxis.html b/python_client/docs/RotationAxis.html new file mode 100644 index 000000000..3a479ccea --- /dev/null +++ b/python_client/docs/RotationAxis.html @@ -0,0 +1,14 @@ + RotationAxis — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RotationAxis

Definition of a crystal rotation axis

Properties

Name

Type

Description

Notes

name

str

Name of rotation axis (e.g., omega, phi)

[optional] [default to ‘omega’]

step

float

Angle step (per image) in degrees. 0 for an axis that does not turn: the axis then records the angle the spindle stood at, which is how a grid scan or a set of stills states its head position.

start

float

Start angle in degrees

[optional] [default to 0]

vector

List[float]

Rotation axis

helical_step_um

List[float]

Translation (per image) for helical scan

[optional]

screening_wedge_deg

float

Wedge angle value; used if rotation per image is smaller than increment between images (so particularly in screening)

[optional]

Example

from jfjoch_client.models.rotation_axis import RotationAxis
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RotationAxis from a JSON string
+rotation_axis_instance = RotationAxis.from_json(json)
+# print the JSON string representation of the object
+print(RotationAxis.to_json())
+
+# convert the object into a dict
+rotation_axis_dict = rotation_axis_instance.to_dict()
+# create an instance of RotationAxis from a dict
+rotation_axis_from_dict = RotationAxis.from_dict(rotation_axis_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveBlob.html b/python_client/docs/RugnuxLiveBlob.html new file mode 100644 index 000000000..d2b7e55a0 --- /dev/null +++ b/python_client/docs/RugnuxLiveBlob.html @@ -0,0 +1,14 @@ + RugnuxLiveBlob — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveBlob

A blob of positive mFo-DFc density the refined model leaves unexplained, with its likely reading: a rule on what is measured, to point a person at the density - not an identification.

Properties

Name

Type

Description

Notes

kind

str

x

float

Centroid, Cartesian Angstrom, in the frame of the refined model (`/rugnux/model.cif`)

y

float

z

float

peak_sigma

float

The highest point, in map sigma

volume_a3

float

Volume above 3 sigma, in cubic Angstrom

nearest_atom

str

e.g. &quot;OG1 THR A42&quot;

nearest_atom_distance_a

float

Absent where no atom is within 12 Angstrom

[optional]

Example

from jfjoch_client.models.rugnux_live_blob import RugnuxLiveBlob
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveBlob from a JSON string
+rugnux_live_blob_instance = RugnuxLiveBlob.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveBlob.to_json())
+
+# convert the object into a dict
+rugnux_live_blob_dict = rugnux_live_blob_instance.to_dict()
+# create an instance of RugnuxLiveBlob from a dict
+rugnux_live_blob_from_dict = RugnuxLiveBlob.from_dict(rugnux_live_blob_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveFrameRange.html b/python_client/docs/RugnuxLiveFrameRange.html new file mode 100644 index 000000000..d632e3f75 --- /dev/null +++ b/python_client/docs/RugnuxLiveFrameRange.html @@ -0,0 +1,14 @@ + RugnuxLiveFrameRange — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveFrameRange

A stretch of a rotation sweep the merge did not take at face value: downgraded (merged at the reduced weight its own scale and sigmas give it) or rejected (nothing of it reached the merge), with the reason the sweep-quality diagnostic saw - the lines of the report’s SWEEP section.

Properties

Name

Type

Description

Notes

first_image

int

First image of the stretch, inclusive, numbered as the collection’s images

last_image

int

Last image of the stretch, inclusive

disposition

str

reason

str

What was seen over the stretch, e.g. &quot;out of beam&quot;, &quot;no diffraction&quot;, &quot;radiation damage&quot;

Example

from jfjoch_client.models.rugnux_live_frame_range import RugnuxLiveFrameRange
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveFrameRange from a JSON string
+rugnux_live_frame_range_instance = RugnuxLiveFrameRange.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveFrameRange.to_json())
+
+# convert the object into a dict
+rugnux_live_frame_range_dict = rugnux_live_frame_range_instance.to_dict()
+# create an instance of RugnuxLiveFrameRange from a dict
+rugnux_live_frame_range_from_dict = RugnuxLiveFrameRange.from_dict(rugnux_live_frame_range_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveModel.html b/python_client/docs/RugnuxLiveModel.html new file mode 100644 index 000000000..e6b2c852a --- /dev/null +++ b/python_client/docs/RugnuxLiveModel.html @@ -0,0 +1,14 @@ + RugnuxLiveModel — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveModel

What the run made of the model it was given, as the report’s MODEL VALIDATION section states it. The R-factors here are those of the placed model with its own coordinates and B factors; what refinement made of it is in refinement. A value that is absent was not computed - the model was not placed, or not by molecular replacement.

Properties

Name

Type

Description

Notes

placement

str

RIGID_BODY (the model fits where it is), MR (molecular replacement placed it) or NOT_PLACED

model_name

str

predicted

bool

Searched for as a predicted model

reason

str

Why the model could not be searched for or validated; empty otherwise

r_work

float

[optional]

r_free

float

[optional]

cc_model

float

Correlation of the merged intensities with the placed model’s, over all reflections

[optional]

fit_sigma

float

How far R-work stands below that of the same model in random orientations, in standard deviations

[optional]

map_atom_sigma

float

Mean 2mFo-DFc value at the atom centres, in map sigma

[optional]

rigid_body_angle_deg

float

[optional]

rigid_body_shift_a

float

[optional]

mr_decision

str

Molecular replacement’s decision (AGREES, ENANTIOMORPH, SPACE_GROUP, TWIN_SUBGROUP, or why it placed nothing); empty where it did not run

mr_space_group

str

The group molecular replacement placed the model in; empty where it placed none

copies

int

Copies placed by molecular replacement

[optional]

tf_z

float

Translation-function Z-score, the highest of the copies’

[optional]

rf_z

float

Rotation-function Z-score of the first copy’s orientation

[optional]

llg_z

float

Likelihood Z-score after the rigid body, where a copy’s translation function did not stand out

[optional]

mr_d_min

float

High-resolution limit of the molecular-replacement search, in Angstrom

[optional]

anomalous_site

str

Atom with the strongest anomalous difference density, e.g. &quot;SG CYS A7&quot;; empty where there is no anomalous map

anomalous_site_sigma

float

Anomalous difference density at that atom, in map sigma

[optional]

refinement

RugnuxLiveRefinement

[optional]

Example

from jfjoch_client.models.rugnux_live_model import RugnuxLiveModel
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveModel from a JSON string
+rugnux_live_model_instance = RugnuxLiveModel.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveModel.to_json())
+
+# convert the object into a dict
+rugnux_live_model_dict = rugnux_live_model_instance.to_dict()
+# create an instance of RugnuxLiveModel from a dict
+rugnux_live_model_from_dict = RugnuxLiveModel.from_dict(rugnux_live_model_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveRefinement.html b/python_client/docs/RugnuxLiveRefinement.html new file mode 100644 index 000000000..d7e967219 --- /dev/null +++ b/python_client/docs/RugnuxLiveRefinement.html @@ -0,0 +1,14 @@ + RugnuxLiveRefinement — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveRefinement

The placed model refined against the merge it was placed on, as the report’s REFINE_ keys state it. Set where a placed model was refined or its refinement failed; absent where the model was not placed or refinement was skipped. On a machine without a GPU it runs on the CPU, slower, and the run’s deadline or cancel can cut it.

Properties

Name

Type

Description

Notes

performed

bool

Refinement ran; false with `reason` where it failed

cancelled

bool

The deadline or a cancel cut the refinement short: the weight trials that ran were chosen among, the rest left out (cut before the first, the model is the placement’s)

reason

str

Why refinement did not run to the end; empty otherwise

on_gpu

bool

seconds

float

Wall time of the refinement

r_work

float

R-work of the refined model (after the restrained stage, else after the rigid body and grouped B)

[optional]

r_free

float

R-free of the refined model, on the same reflections as `r_work`

[optional]

rmsd_bonds_a

float

RMS deviation of the bond lengths from the dictionary, where the restrained stage ran

[optional]

rmsd_angles_deg

float

RMS deviation of the bond angles from the dictionary, where the restrained stage ran

[optional]

blob_count

int

Unexplained blobs of the refined model’s mFo-DFc map (above 3 sigma, peaking above 4)

waters_added

int

Where the solvent was built (`refine_solvent`), the waters it added that are still in the model

[optional]

waters_removed

int

Where the solvent was built (`refine_solvent`), the waters of the model as given it took out

[optional]

blobs

List[RugnuxLiveBlob]

The strongest blobs, at most 50, strongest first

Example

from jfjoch_client.models.rugnux_live_refinement import RugnuxLiveRefinement
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveRefinement from a JSON string
+rugnux_live_refinement_instance = RugnuxLiveRefinement.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveRefinement.to_json())
+
+# convert the object into a dict
+rugnux_live_refinement_dict = rugnux_live_refinement_instance.to_dict()
+# create an instance of RugnuxLiveRefinement from a dict
+rugnux_live_refinement_from_dict = RugnuxLiveRefinement.from_dict(rugnux_live_refinement_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveShell.html b/python_client/docs/RugnuxLiveShell.html new file mode 100644 index 000000000..33f5e3974 --- /dev/null +++ b/python_client/docs/RugnuxLiveShell.html @@ -0,0 +1,14 @@ + RugnuxLiveShell — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveShell

A resolution shell of the merge: a row of the shell table of _report.txt, with R_split from its serial statistics and R-free from its MODEL VALIDATION, on the same shells. Fractions, not percent. A quantity not measured for this shell or this run is absent.

Properties

Name

Type

Description

Notes

d_min

float

High-resolution limit of the shell, in Angstrom (the row label of the report’s table)

d_max

float

Low-resolution limit of the shell, in Angstrom

n_obs

int

Observations merged

n_unique

int

Unique reflections

completeness

float

[optional]

multiplicity

float

[optional]

i_over_sigma

float

Mean I/sigma(I) of the merged reflections

[optional]

r_meas

float

Rotation only, as in the report

[optional]

cc_half

float

CC1/2 of the shell table

[optional]

cc_ref

float

CC against the reference data, where reference data were given

[optional]

r_split

float

Serial data only, with every frame whole in one half-set

[optional]

r_free

float

R-free of the placed model (as given, not refined) over the shell’s free reflections

[optional]

Example

from jfjoch_client.models.rugnux_live_shell import RugnuxLiveShell
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveShell from a JSON string
+rugnux_live_shell_instance = RugnuxLiveShell.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveShell.to_json())
+
+# convert the object into a dict
+rugnux_live_shell_dict = rugnux_live_shell_instance.to_dict()
+# create an instance of RugnuxLiveShell from a dict
+rugnux_live_shell_from_dict = RugnuxLiveShell.from_dict(rugnux_live_shell_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveStatus.html b/python_client/docs/RugnuxLiveStatus.html new file mode 100644 index 000000000..84ff2bc7a --- /dev/null +++ b/python_client/docs/RugnuxLiveStatus.html @@ -0,0 +1,14 @@ + RugnuxLiveStatus — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveStatus

Live rugnux processing of the last collection; kept until the next collection starts, POST /rugnux/clear or POST /initialize. Times are taken when the image puller received a message, and are in seconds since the first image (before it arrives, since now). The frame rate is (images_received - 1) / last_image_s.

Properties

Name

Type

Description

Notes

state

str

placed_model

bool

The run placed the model: it can be fetched from `/rugnux/model.cif` and its maps from `/rugnux/map.ccp4`.

refined_model

bool

The run refined the placed model: `/rugnux/model.cif` and `/rugnux/map.ccp4` serve the refined model and its maps unless asked for `stage=placed`.

anomalous_map

bool

The merge kept the Bijvoet pairs, so with the placed model there is an anomalous difference map (`/rugnux/map.ccp4?type=anom`).

anomalous_signal

bool

The merged data carry usable anomalous signal (the summary’s &quot;Anomalous&quot; row says so)

model

RugnuxLiveModel

[optional]

stills

RugnuxLiveStills

[optional]

shells_merge

str

Which merge `shells` are of - &quot;the collection&quot;, or on serial data a provisional merge such as &quot;50% of the images (provisional)&quot;; absent until there is a merge

[optional]

shells

List[RugnuxLiveShell]

Merging statistics by resolution shell of the latest merge, coarse to fine, as the shell table of `_report.txt`. Rotation: once the run is over; serial: at each provisional merge and at the end. `overall` is the same table’s &quot;Overall&quot; row (whole-merge completeness, multiplicity, I/sigma, CC1/2, R_meas or R_split, CCref, and the overall R-free of the model validated on it), present with `shells`.

[optional]

overall

RugnuxLiveShell

[optional]

frame_scales

List[float]

Rotation, once the run is over: the per-image scale factor of the merge, one entry per image of the collection in its order, 0 where the image got none (not indexed, or rejected). Absent on serial data and until there is a merge.

[optional]

frame_ranges

List[RugnuxLiveFrameRange]

Rotation, once the run is over: the stretches of the sweep the merge downgraded or rejected, in order; every image outside them is merged at its own weight. Absent on serial data and until there is a merge; empty where the whole sweep was merged.

[optional]

space_group

str

Space group of the result (the summary’s &quot;Space group&quot; row); absent until the run is over

[optional]

d_min

float

High-resolution limit of the merge, in Angstrom; absent until the run is over, or without a merge

[optional]

isa

float

ISa of the error model; absent until the run is over, or where it was not determined

[optional]

probe

str

Answer of the early lattice probe on the first 60 degrees; empty until it answers, and the run’s own lattice once the run has indexed

probe_s

float

When the probe answered (or the run indexed), since the first image

[optional]

start_to_first_image_s

float

From the START message to the first image; set once the first image arrives

[optional]

message

str

Why the run failed or was skipped

images_expected

int

expected_collection_s

float

How long the collection is set up to take - images_expected times the image time; absent if not known

[optional]

images_received

int

elapsed_s

float

step_progress

float

Fraction of the current pass’s images

[optional]

steps

List[RugnuxLiveStep]

last_image_s

float

When the last image arrived, since the first image; set once the collection is over

[optional]

cut

str

Empty, or why the analysis was cut: `deadline` (`deadline_s` after the last image) or `cancel` (`POST /cancel`). The end message then carried what was established at the cut.

[optional]

cut_s

float

When the analysis was cut, since the first image

[optional]

last_image_to_written_s

float

From the last image received to all results written

[optional]

verdict

str

OK, WARNINGS, UNUSABLE, FAILED or CANCELLED; empty until the run is over

verdict_text

str

summary

List[RugnuxSummaryRow]

warnings

List[str]

triage

List[RugnuxTriageItem]

The pathology checklist of the report, in its order. Rotation: once the run is over; serial: at each provisional merge and at the end. Absent until there is one.

[optional]

Example

from jfjoch_client.models.rugnux_live_status import RugnuxLiveStatus
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveStatus from a JSON string
+rugnux_live_status_instance = RugnuxLiveStatus.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveStatus.to_json())
+
+# convert the object into a dict
+rugnux_live_status_dict = rugnux_live_status_instance.to_dict()
+# create an instance of RugnuxLiveStatus from a dict
+rugnux_live_status_from_dict = RugnuxLiveStatus.from_dict(rugnux_live_status_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveStep.html b/python_client/docs/RugnuxLiveStep.html new file mode 100644 index 000000000..6e8ea9d57 --- /dev/null +++ b/python_client/docs/RugnuxLiveStep.html @@ -0,0 +1,14 @@ + RugnuxLiveStep — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveStep

Properties

Name

Type

Description

Notes

title

str

started_s

float

Start of the step, since the first image (negative if before it)

duration_s

float

Set once the next step starts or the run ends

[optional]

notes

List[str]

What the step found (e.g. lattice, space group)

Example

from jfjoch_client.models.rugnux_live_step import RugnuxLiveStep
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveStep from a JSON string
+rugnux_live_step_instance = RugnuxLiveStep.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveStep.to_json())
+
+# convert the object into a dict
+rugnux_live_step_dict = rugnux_live_step_instance.to_dict()
+# create an instance of RugnuxLiveStep from a dict
+rugnux_live_step_from_dict = RugnuxLiveStep.from_dict(rugnux_live_step_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxLiveStills.html b/python_client/docs/RugnuxLiveStills.html new file mode 100644 index 000000000..b2880fac0 --- /dev/null +++ b/python_client/docs/RugnuxLiveStills.html @@ -0,0 +1,14 @@ + RugnuxLiveStills — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxLiveStills

Serial frames analysed on the GPU: the pre-pass on the first images (the beam centre, distance and mask the whole collection is analysed with), and the analysis since.

Properties

Name

Type

Description

Notes

prepass

str

Holding the first images, running on them, or done (Failed - the stated geometry and mask are used)

images_held

int

Images held for the pre-pass

images_needed

int

Images the pre-pass runs on

prepass_s

float

How long the pre-pass took

[optional]

file_beam_x_pxl

float

file_beam_y_pxl

float

file_distance_mm

float

beam_x_pxl

float

Beam centre the pre-pass decided (where the beam lands)

[optional]

beam_y_pxl

float

[optional]

distance_mm

float

Detector distance the pre-pass decided

[optional]

shadow_pixels

int

Pixels masked as the beam-stop shadow

[optional]

bad_pixels

int

Pixels masked as defective (hot, dead, error value)

[optional]

images_analysed

int

images_indexed

int

analysis_rate_hz

float

Images analysed per second since the pre-pass

[optional]

Example

from jfjoch_client.models.rugnux_live_stills import RugnuxLiveStills
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxLiveStills from a JSON string
+rugnux_live_stills_instance = RugnuxLiveStills.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxLiveStills.to_json())
+
+# convert the object into a dict
+rugnux_live_stills_dict = rugnux_live_stills_instance.to_dict()
+# create an instance of RugnuxLiveStills from a dict
+rugnux_live_stills_from_dict = RugnuxLiveStills.from_dict(rugnux_live_stills_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxSettings.html b/python_client/docs/RugnuxSettings.html new file mode 100644 index 000000000..92d8a4669 --- /dev/null +++ b/python_client/docs/RugnuxSettings.html @@ -0,0 +1,14 @@ + RugnuxSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxSettings

Rugnux live mode: rotation collections from a DECTRIS detector are processed by rugnux inside the broker while they arrive, and the merged result is sent to the writer. Serial collections, from a DECTRIS detector or converted by the FPGA (JUNGFRAU), are analysed on the GPU after a pre-pass on their first images that decides the beam centre, distance and mask (stills in /rugnux/status), and merged as they go.

Properties

Name

Type

Description

Notes

enable

bool

Process DECTRIS rotation collections with rugnux live, and serial collections on the GPU after a pre-pass

[optional] [default to False]

reserved_cpus

int

CPU threads left to the receiver and the image pusher while rugnux runs

[optional] [default to 4]

deadline_s

float

Fixed cutoff: this long after the last image the analysis is cut, and the collection ends with what it has established (as `POST /cancel` after the last image does). 0 means no cutoff.

[optional] [default to 60.0]

refine_solvent

bool

With a model: the refinement also builds the solvent - waters added at difference-map peaks and removed where the maps no longer hold them, waters and ions relabelled (as `rugnux –refine-solvent`). Reset to false by `POST /initialize`.

[optional] [default to False]

force_still

bool

Process DECTRIS rotation collections as stills, on the serial path (pre-pass, GPU analysis, stills merge), as `rugnux –force-still` does. The written file keeps its goniometer. Reset to false by `POST /initialize`.

[optional] [default to False]

Example

from jfjoch_client.models.rugnux_settings import RugnuxSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxSettings from a JSON string
+rugnux_settings_instance = RugnuxSettings.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxSettings.to_json())
+
+# convert the object into a dict
+rugnux_settings_dict = rugnux_settings_instance.to_dict()
+# create an instance of RugnuxSettings from a dict
+rugnux_settings_from_dict = RugnuxSettings.from_dict(rugnux_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxStatus.html b/python_client/docs/RugnuxStatus.html new file mode 100644 index 000000000..bb75a7593 --- /dev/null +++ b/python_client/docs/RugnuxStatus.html @@ -0,0 +1,14 @@ + RugnuxStatus — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxStatus

Properties

Name

Type

Description

Notes

enable

bool

Rugnux live mode is enabled

reserved_cpus

int

CPU threads left to the receiver and the image pusher while rugnux runs

deadline_s

float

Seconds after the last image at which the analysis is cut; 0 means no cutoff

[optional]

refine_solvent

bool

The refinement of a placed model also builds the solvent

force_still

bool

DECTRIS rotation collections are processed as stills

model_loaded

bool

A model was uploaded with `PUT /config/rugnux/model`

model_size_bytes

int

Size of the uploaded model file

[optional]

Example

from jfjoch_client.models.rugnux_status import RugnuxStatus
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxStatus from a JSON string
+rugnux_status_instance = RugnuxStatus.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxStatus.to_json())
+
+# convert the object into a dict
+rugnux_status_dict = rugnux_status_instance.to_dict()
+# create an instance of RugnuxStatus from a dict
+rugnux_status_from_dict = RugnuxStatus.from_dict(rugnux_status_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxSummaryRow.html b/python_client/docs/RugnuxSummaryRow.html new file mode 100644 index 000000000..1653396df --- /dev/null +++ b/python_client/docs/RugnuxSummaryRow.html @@ -0,0 +1,14 @@ + RugnuxSummaryRow — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxSummaryRow

Properties

Name

Type

Description

Notes

label

str

value

str

Example

from jfjoch_client.models.rugnux_summary_row import RugnuxSummaryRow
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxSummaryRow from a JSON string
+rugnux_summary_row_instance = RugnuxSummaryRow.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxSummaryRow.to_json())
+
+# convert the object into a dict
+rugnux_summary_row_dict = rugnux_summary_row_instance.to_dict()
+# create an instance of RugnuxSummaryRow from a dict
+rugnux_summary_row_from_dict = RugnuxSummaryRow.from_dict(rugnux_summary_row_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/RugnuxTriageItem.html b/python_client/docs/RugnuxTriageItem.html new file mode 100644 index 000000000..f2d6d47fd --- /dev/null +++ b/python_client/docs/RugnuxTriageItem.html @@ -0,0 +1,14 @@ + RugnuxTriageItem — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

RugnuxTriageItem

A line of the pathology checklist of _report.txt (its SUMMARY), in the report’s words. ok: looked for and not found; attention: its warning fired (its codes are in the report’s PATHOLOGY_FLAGS); serious: a pathology that leaves no result to use - no lattice, or a merge without signal (the report’s verdict FAILED or UNUSABLE); not_measured: it could not be looked for on this run.

Properties

Name

Type

Description

Notes

label

str

Name of the condition, e.g. &quot;Twinning&quot; - the summary row’s label

codes

List[str]

The PATHOLOGY_FLAGS codes the line stands for, e.g. TWINNING

severity

str

text

str

The summary row’s own words; empty where it has none

detail

str

The report’s warnings that fired for it, one per line; absent where none fired

[optional]

Example

from jfjoch_client.models.rugnux_triage_item import RugnuxTriageItem
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of RugnuxTriageItem from a JSON string
+rugnux_triage_item_instance = RugnuxTriageItem.from_json(json)
+# print the JSON string representation of the object
+print(RugnuxTriageItem.to_json())
+
+# convert the object into a dict
+rugnux_triage_item_dict = rugnux_triage_item_instance.to_dict()
+# create an instance of RugnuxTriageItem from a dict
+rugnux_triage_item_from_dict = RugnuxTriageItem.from_dict(rugnux_triage_item_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ScanResult.html b/python_client/docs/ScanResult.html new file mode 100644 index 000000000..0e2ba22c1 --- /dev/null +++ b/python_client/docs/ScanResult.html @@ -0,0 +1,14 @@ + ScanResult — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ScanResult

Results of a scan

Properties

Name

Type

Description

Notes

file_prefix

str

[optional]

rotation_unit_cell

UnitCell

[optional]

rotation_crystal_lattice

List[float]

Real-space crystal lattice 3D vectors in Angstrom. Order is 1st vector (x,y,z), 2nd vector (x,y,z) and 3rd vector (x,y,z)

[optional]

rotation_bravais

str

Bravais lattice type of the global rotation-indexing solution: crystal-system letter + centering, e.g. &quot;tP&quot;, &quot;oC&quot;, &quot;cF&quot;, &quot;hR&quot;, &quot;mP&quot;. Empty if not determined.

[optional]

images

List[ScanResultImagesInner]

Example

from jfjoch_client.models.scan_result import ScanResult
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ScanResult from a JSON string
+scan_result_instance = ScanResult.from_json(json)
+# print the JSON string representation of the object
+print(ScanResult.to_json())
+
+# convert the object into a dict
+scan_result_dict = scan_result_instance.to_dict()
+# create an instance of ScanResult from a dict
+scan_result_from_dict = ScanResult.from_dict(scan_result_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ScanResultImagesInner.html b/python_client/docs/ScanResultImagesInner.html new file mode 100644 index 000000000..3471103b8 --- /dev/null +++ b/python_client/docs/ScanResultImagesInner.html @@ -0,0 +1,14 @@ + ScanResultImagesInner — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ScanResultImagesInner

Properties

Name

Type

Description

Notes

efficiency

float

number

int

Detector image number for a given cell

nx

int

Cell position in X for grid scan

[optional]

ny

int

Cell position in Y for grid scan

[optional]

angle

float

Rotation angle associated with the image

[optional]

bkg

float

Background estimate

[optional]

spindle_blind

float

Fraction (0-1) of a rotation sweep’s blind double cone that this orientation makes unrecoverable, assuming the nearest plausible lattice row is a lone 2-fold (a worst-case bound, not an estimate). At 0.5 and above a recovery protocol (second sweep, reorientation) should engage. Absent means the frame could not be assessed, which automation must treat the same as above threshold - it is not a zero.

[optional]

spots

int

Spot count

[optional]

spots_low_res

int

Spot count in low resolution range

[optional]

spots_indexed

int

Spot count within indexing tolerance

[optional]

spots_ice

int

Spot count within common ice ring resolutions

[optional]

ice

float

Strongest hexagonal-ice ring intensity over the smooth radial background (1 = no ice)

[optional]

index

int

Indexing solution

[optional]

latt_count

int

Indexing lattice count

[optional]

pr

float

Profile radius, i.e. how far reflections are from the Ewald sphere

[optional]

b

float

B-Factor estimate

[optional]

uc

UnitCell

[optional]

xfel_pulseid

int

XFEL pulse ID

[optional]

pixel_sum

int

Total sum of all pixels

[optional]

max

int

Max viable pixel

[optional]

sat

int

Number of saturated pixels

[optional]

err

int

Number of error pixels

[optional]

res

float

Diffraction resolution estimate

[optional]

Example

from jfjoch_client.models.scan_result_images_inner import ScanResultImagesInner
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ScanResultImagesInner from a JSON string
+scan_result_images_inner_instance = ScanResultImagesInner.from_json(json)
+# print the JSON string representation of the object
+print(ScanResultImagesInner.to_json())
+
+# convert the object into a dict
+scan_result_images_inner_dict = scan_result_images_inner_instance.to_dict()
+# create an instance of ScanResultImagesInner from a dict
+scan_result_images_inner_from_dict = ScanResultImagesInner.from_dict(scan_result_images_inner_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/SpotFindingSettings.html b/python_client/docs/SpotFindingSettings.html new file mode 100644 index 000000000..ff52a7973 --- /dev/null +++ b/python_client/docs/SpotFindingSettings.html @@ -0,0 +1,14 @@ + SpotFindingSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

SpotFindingSettings

Properties

Name

Type

Description

Notes

enable

bool

Enable spot finding. This is temporary setting, i.e. can be changed anytime during data collection. Even if disabled spot finding information will still be send and written, though always with zero spots.

[default to True]

indexing

bool

Enable indexing. This is temporary setting, i.e. can be changed anytime during data collection.

[default to True]

signal_to_noise_threshold

float

photon_count_threshold

int

min_pix_per_spot

int

max_pix_per_spot

int

high_resolution_limit

float

High resolution limit for spot finding [Angstrom]. Optional: if omitted, spot finding extends as far as the detector reaches, i.e. the detection is not clipped in resolution.

[optional]

low_resolution_limit

float

Low resolution limit for spot finding [Angstrom]. Optional: if omitted, spot finding is not clipped at the low-resolution end. A value of 0 is accepted and means the same thing.

[optional]

high_resolution_limit_for_spot_count_low_res

float

High resolution threshold to consider spot &quot;low resolution&quot; [Angstrom]

quick_integration

bool

Ignored: accepted on input and always returned as false; will be removed in a future release. The Lite and FPGA workflows index images but do not integrate them; integration is done by rugnux live.

[optional] [default to False]

ice_ring_width_q_recip_a

float

Half-width of the ice ring band in q (1/A). Matches the offline default in image_analysis/spot_finding/SpotFindingSettings.h, which was set from a measured ring FWHM of ~0.06; the two must agree or the same data gets a narrower ice band online.

[default to 0.03]

high_res_gap_q_recip_a

float

This parameter is used to remove spurious spots at a very high resolution, that sometimes appear due to very low background close to the edge of the detector. If there is a gap in (1/d)-space between spots of at least this size, spots on the side of the gap with high resolution will be discarded. This is optional parameter. This option should be turned OFF for small molecule datasets or for crystals with very low mosaicity, when it is expected to see only few spots in any case.

[optional] [default to 1.5]

adaptive_threshold

bool

Self-calibrating spot detection: replace the fixed photon_count_threshold by a per-resolution-ring threshold derived from each image’s own noise, so the same setting works across datasets without per-dataset tuning. photon_count_threshold is then ignored and false_pixels_per_frame sets the operating point instead. Used only on detectors whose images are analysed in software (the DECTRIS/SIMPLON workflow). The JUNGFRAU and EIGER workflows find spots on the FPGA, which applies its own fixed threshold; there the setting is accepted and ignored, so the same settings can be shared across detectors.

[optional] [default to False]

false_pixels_per_frame

float

Operating point of the adaptive threshold: the number of noise pixels tolerated per frame. About 100 suits a multi-megapixel detector. Ignored unless adaptive_threshold is set.

[optional] [default to 100.0]

Example

from jfjoch_client.models.spot_finding_settings import SpotFindingSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of SpotFindingSettings from a JSON string
+spot_finding_settings_instance = SpotFindingSettings.from_json(json)
+# print the JSON string representation of the object
+print(SpotFindingSettings.to_json())
+
+# convert the object into a dict
+spot_finding_settings_dict = spot_finding_settings_instance.to_dict()
+# create an instance of SpotFindingSettings from a dict
+spot_finding_settings_from_dict = SpotFindingSettings.from_dict(spot_finding_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/StandardDetectorGeometry.html b/python_client/docs/StandardDetectorGeometry.html new file mode 100644 index 000000000..7180752de --- /dev/null +++ b/python_client/docs/StandardDetectorGeometry.html @@ -0,0 +1,14 @@ + StandardDetectorGeometry — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

StandardDetectorGeometry

Regular rectangular geometry, first module is in the bottom left corner of the detector

Properties

Name

Type

Description

Notes

nmodules

int

Number of modules in the detector

gap_x

int

Gap size in X direction [pixels]

[optional] [default to 8]

gap_y

int

Gap size in Y direction [pixels]

[optional] [default to 36]

modules_in_row

int

Number of modules in one row

[optional] [default to 1]

Example

from jfjoch_client.models.standard_detector_geometry import StandardDetectorGeometry
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of StandardDetectorGeometry from a JSON string
+standard_detector_geometry_instance = StandardDetectorGeometry.from_json(json)
+# print the JSON string representation of the object
+print(StandardDetectorGeometry.to_json())
+
+# convert the object into a dict
+standard_detector_geometry_dict = standard_detector_geometry_instance.to_dict()
+# create an instance of StandardDetectorGeometry from a dict
+standard_detector_geometry_from_dict = StandardDetectorGeometry.from_dict(standard_detector_geometry_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/TcpSettings.html b/python_client/docs/TcpSettings.html new file mode 100644 index 000000000..8f8be21d7 --- /dev/null +++ b/python_client/docs/TcpSettings.html @@ -0,0 +1,14 @@ + TcpSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

TcpSettings

TCP image stream configuration for Jungfraujoch software. This structure is used to provide default settings using configuration JSON file and is not used in HTTP.

Properties

Name

Type

Description

Notes

send_buffer_size

int

Send buffer size for TCP/IP socket

[optional]

image_socket

str

tcp://<IP address>:<port> 0.0.0.0 instead of IP address is accepted and means listening on all network interfaces

nwriters

int

Number of TCP/IP writers to be used for streaming images

[optional] [default to 32]

peer_liveness_timeout_ms

int

Max time (in milliseconds) a send may block with no sign of life from the writer (no BUSY heartbeat or ACK) before the connection is declared dead. Optional; the built-in default is used when unset.

[optional]

max_backpressure_timeout_ms

int

Hard upper bound (in milliseconds) on backpressure: if no bytes can be sent to the writer for this long the connection is declared dead even while the writer keeps heartbeating, so a wedged writer cannot block the run or its finalization. Optional; the built-in default is used when unset.

[optional]

Example

from jfjoch_client.models.tcp_settings import TcpSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of TcpSettings from a JSON string
+tcp_settings_instance = TcpSettings.from_json(json)
+# print the JSON string representation of the object
+print(TcpSettings.to_json())
+
+# convert the object into a dict
+tcp_settings_dict = tcp_settings_instance.to_dict()
+# create an instance of TcpSettings from a dict
+tcp_settings_from_dict = TcpSettings.from_dict(tcp_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/UnitCell.html b/python_client/docs/UnitCell.html new file mode 100644 index 000000000..6eae36543 --- /dev/null +++ b/python_client/docs/UnitCell.html @@ -0,0 +1,14 @@ + UnitCell — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

UnitCell

Unit cell parameters. Necessary to run indexing. Units of angstrom and degree

Properties

Name

Type

Description

Notes

a

float

b

float

c

float

alpha

float

beta

float

gamma

float

Example

from jfjoch_client.models.unit_cell import UnitCell
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of UnitCell from a JSON string
+unit_cell_instance = UnitCell.from_json(json)
+# print the JSON string representation of the object
+print(UnitCell.to_json())
+
+# convert the object into a dict
+unit_cell_dict = unit_cell_instance.to_dict()
+# create an instance of UnitCell from a dict
+unit_cell_from_dict = UnitCell.from_dict(unit_cell_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ZeromqMetadataSettings.html b/python_client/docs/ZeromqMetadataSettings.html new file mode 100644 index 000000000..4bf952e36 --- /dev/null +++ b/python_client/docs/ZeromqMetadataSettings.html @@ -0,0 +1,14 @@ + ZeromqMetadataSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ZeromqMetadataSettings

Properties

Name

Type

Description

Notes

enabled

bool

ZeroMQ metadata socket is enabled.

[default to True]

period_ms

int

Period for generating metadata package sent to the ZeroMQ interface in milliseconds.

[default to 1000]

socket_address

str

PUB ZeroMQ socket for image metadata information. Image metadata are serialized using CBOR. Address follows ZeroMQ convention for sockets - in practice ipc://<socket file> and tcp://<IP address>:<port> sockets are OK. 0.0.0.0 instead of IP address is accepted and means listening on all network interfaces.

[optional]

Example

from jfjoch_client.models.zeromq_metadata_settings import ZeromqMetadataSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ZeromqMetadataSettings from a JSON string
+zeromq_metadata_settings_instance = ZeromqMetadataSettings.from_json(json)
+# print the JSON string representation of the object
+print(ZeromqMetadataSettings.to_json())
+
+# convert the object into a dict
+zeromq_metadata_settings_dict = zeromq_metadata_settings_instance.to_dict()
+# create an instance of ZeromqMetadataSettings from a dict
+zeromq_metadata_settings_from_dict = ZeromqMetadataSettings.from_dict(zeromq_metadata_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ZeromqPreviewSettings.html b/python_client/docs/ZeromqPreviewSettings.html new file mode 100644 index 000000000..12e3a67d9 --- /dev/null +++ b/python_client/docs/ZeromqPreviewSettings.html @@ -0,0 +1,14 @@ + ZeromqPreviewSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ZeromqPreviewSettings

Properties

Name

Type

Description

Notes

enabled

bool

ZeroMQ preview socket is enabled.

[default to True]

period_ms

int

Period for generating preview image sent to the ZeroMQ interface in milliseconds. Default is 1 second. If set to zero, all images will be sent ZeroMQ (should be used only in case of relatively slow data collection). This has no effect on HTTP based preview, which updates always at rate of 1 second.

[default to 1000]

socket_address

str

PUB ZeroMQ socket for preview images. This socket operates at a reduced frame rate. Images are serialized using CBOR. Address follows ZeroMQ convention for sockets - in practice ipc://<socket file> and tcp://<IP address>:<port> sockets are OK. 0.0.0.0 instead of IP address is accepted and means listening on all network interfaces.

[optional]

Example

from jfjoch_client.models.zeromq_preview_settings import ZeromqPreviewSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ZeromqPreviewSettings from a JSON string
+zeromq_preview_settings_instance = ZeromqPreviewSettings.from_json(json)
+# print the JSON string representation of the object
+print(ZeromqPreviewSettings.to_json())
+
+# convert the object into a dict
+zeromq_preview_settings_dict = zeromq_preview_settings_instance.to_dict()
+# create an instance of ZeromqPreviewSettings from a dict
+zeromq_preview_settings_from_dict = ZeromqPreviewSettings.from_dict(zeromq_preview_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/python_client/docs/ZeromqSettings.html b/python_client/docs/ZeromqSettings.html new file mode 100644 index 000000000..bfa981682 --- /dev/null +++ b/python_client/docs/ZeromqSettings.html @@ -0,0 +1,14 @@ + ZeromqSettings — Jungfraujoch 1.0.0-rc.186 documentation Skip to content

ZeromqSettings

ZeroMQ configuration for Jungfraujoch software. This structure is used to provide default settings using configuration JSON file and is not used in HTTP.

Properties

Name

Type

Description

Notes

send_watermark

int

Watermark for ZeroMQ send queue (number of outstanding messages queued on Jungfraujoch server per queue)

[optional] [default to 100]

send_buffer_size

int

Send buffer size for ZeroMQ socket

[optional]

image_socket

List[str]

PUSH ZeroMQ socket for images. In case multiple sockets are provided, images are streamed over multiple sockets. Images are serialized using CBOR. Address follows ZeroMQ convention for sockets - in practice ipc://<socket file> and tpc://<IP address>:<port> sockets are OK. 0.0.0.0 instead of IP address is accepted and means listening on all network interfaces.

[optional]

writer_notification_socket

str

PULL ZeroMQ socket for notifications from writer that it finished operation. This allows Jungfraujoch to operate in a synchronous manner, with end of acquisition being also end of writing. Address follows ZeroMQ convention for sockets - in practice ipc://<socket file> and tpc://<IP address>:<port> sockets are OK. 0.0.0.0 instead of IP address should be avoided, as this socket address is forwarded to the writer process via START ZerOMQ message and in case of multiple ineterfaces the address might be ambigous. Using * (star) instead of port number is allowed and it means a random free port number.

[optional]

Example

from jfjoch_client.models.zeromq_settings import ZeromqSettings
+
+# TODO update the JSON string below
+json = "{}"
+# create an instance of ZeromqSettings from a JSON string
+zeromq_settings_instance = ZeromqSettings.from_json(json)
+# print the JSON string representation of the object
+print(ZeromqSettings.to_json())
+
+# convert the object into a dict
+zeromq_settings_dict = zeromq_settings_instance.to_dict()
+# create an instance of ZeromqSettings from a dict
+zeromq_settings_from_dict = ZeromqSettings.from_dict(zeromq_settings_dict)
+

[Back to Model list] [Back to API list] [Back to README]

\ No newline at end of file diff --git a/search.html b/search.html new file mode 100644 index 000000000..32fa55ff8 --- /dev/null +++ b/search.html @@ -0,0 +1 @@ + Search — Jungfraujoch 1.0.0-rc.186 documentation Skip to content
\ No newline at end of file diff --git a/searchindex.js b/searchindex.js new file mode 100644 index 000000000..cd85157e8 --- /dev/null +++ b/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"alltitles": {"/entry (NXentry)": [[23, "entry-nxentry"]], "/entry/data (NXdata)": [[23, "entry-data-nxdata"]], "/entry/instrument/attenuator (NXattenuator)": [[23, "entry-instrument-attenuator-nxattenuator"]], "/entry/instrument/beam (NXbeam)": [[23, "entry-instrument-beam-nxbeam"]], "/entry/instrument/detector (NXdetector)": [[23, "entry-instrument-detector-nxdetector"]], "/entry/instrument/detector/module (NXdetector_module)": [[23, "entry-instrument-detector-module-nxdetector-module"]], "/entry/instrument/detector/module_ (NXdetector_module, one per module)": [[23, "entry-instrument-detector-module-n-nxdetector-module-one-per-module"]], "/entry/instrument/detector/transformations (NXtransformations)": [[23, "entry-instrument-detector-transformations-nxtransformations"]], "/entry/sample (NXsample)": [[23, "entry-sample-nxsample"]], "/entry/source (NXsource), /entry/instrument (NXinstrument)": [[23, "entry-source-nxsource-entry-instrument-nxinstrument"]], "0. Getting the image onto the GPU: device-side decoding": [[5, "getting-the-image-onto-the-gpu-device-side-decoding"]], "1. Geometry, reciprocal-space mapping, and basic quantities": [[5, "geometry-reciprocal-space-mapping-and-basic-quantities"]], "1. Good practice \u2014 what is and is not protected": [[51, "good-practice-what-is-and-is-not-protected"]], "1. Motivation: derived metadata and FAIR data": [[23, "motivation-derived-metadata-and-fair-data"]], "1.0.0": [[2, "id1"]], "1.0.0-rc.100": [[2, "rc-100"]], "1.0.0-rc.101": [[2, "rc-101"]], "1.0.0-rc.102": [[2, "rc-102"]], "1.0.0-rc.103": [[2, "rc-103"]], "1.0.0-rc.104": [[2, "rc-104"]], "1.0.0-rc.105": [[2, "rc-105"]], "1.0.0-rc.106": [[2, "rc-106"]], "1.0.0-rc.107": [[2, "rc-107"]], "1.0.0-rc.108": [[2, "rc-108"]], "1.0.0-rc.109": [[2, "rc-109"]], "1.0.0-rc.110": [[2, "rc-110"]], "1.0.0-rc.111": [[2, "rc-111"]], "1.0.0-rc.112": [[2, "rc-112"]], "1.0.0-rc.113": [[2, "rc-113"]], "1.0.0-rc.114": [[2, "rc-114"]], "1.0.0-rc.115": [[2, "rc-115"]], "1.0.0-rc.116": [[2, "rc-116"]], "1.0.0-rc.117": [[2, "rc-117"]], "1.0.0-rc.118": [[2, "rc-118"]], "1.0.0-rc.119": [[2, "rc-119"]], "1.0.0-rc.120": [[2, "rc-120"]], "1.0.0-rc.121": [[2, "rc-121"]], "1.0.0-rc.122": [[2, "rc-122"]], "1.0.0-rc.123": [[2, "rc-123"]], "1.0.0-rc.124": [[2, "rc-124"]], "1.0.0-rc.125": [[2, "rc-125"]], "1.0.0-rc.126": [[2, "rc-126"]], "1.0.0-rc.127": [[2, "rc-127"]], "1.0.0-rc.128": [[2, "rc-128"]], "1.0.0-rc.129": [[2, "rc-129"]], "1.0.0-rc.130": [[2, "rc-130"]], "1.0.0-rc.131": [[2, "rc-131"]], "1.0.0-rc.132": [[2, "rc-132"]], "1.0.0-rc.133": [[2, "rc-133"]], "1.0.0-rc.134": [[2, "rc-134"]], "1.0.0-rc.135": [[2, "rc-135"]], "1.0.0-rc.136": [[2, "rc-136"]], "1.0.0-rc.137": [[2, "rc-137"]], "1.0.0-rc.138": [[2, "rc-138"]], "1.0.0-rc.139": [[2, "rc-139"]], "1.0.0-rc.140": [[2, "rc-140"]], "1.0.0-rc.141": [[2, "rc-141"]], "1.0.0-rc.142": [[2, "rc-142"]], "1.0.0-rc.143": [[2, "rc-143"]], "1.0.0-rc.144": [[2, "rc-144"]], "1.0.0-rc.145": [[2, "rc-145"]], "1.0.0-rc.146": [[2, "rc-146"]], "1.0.0-rc.147": [[2, "rc-147"]], "1.0.0-rc.148": [[2, "rc-148"]], "1.0.0-rc.149": [[2, "rc-149"]], "1.0.0-rc.150": [[2, "rc-150"]], "1.0.0-rc.151": [[2, "rc-151"]], "1.0.0-rc.152": [[2, "rc-152"]], "1.0.0-rc.153": [[2, "rc-153"]], "1.0.0-rc.154": [[2, "rc-154"]], "1.0.0-rc.155": [[2, "rc-155"]], "1.0.0-rc.156": [[2, "rc-156"]], "1.0.0-rc.157": [[2, "rc-157"]], "1.0.0-rc.158": [[2, "rc-158"]], "1.0.0-rc.159": [[2, "rc-159"]], "1.0.0-rc.160": [[2, "rc-160"]], "1.0.0-rc.161": [[2, "rc-161"]], "1.0.0-rc.162": [[2, "rc-162"]], "1.0.0-rc.163": [[2, "rc-163"]], "1.0.0-rc.164": [[2, "rc-164"]], "1.0.0-rc.165": [[2, "rc-165"]], "1.0.0-rc.166": [[2, "rc-166"]], "1.0.0-rc.167": [[2, "rc-167"]], "1.0.0-rc.168": [[2, "rc-168"]], "1.0.0-rc.169": [[2, "rc-169"]], "1.0.0-rc.170": [[2, "rc-170"]], "1.0.0-rc.171": [[2, "rc-171"]], "1.0.0-rc.172": [[2, "rc-172"]], "1.0.0-rc.173": [[2, "rc-173"]], "1.0.0-rc.174": [[2, "rc-174"]], "1.0.0-rc.175": [[2, "rc-175"]], "1.0.0-rc.176": [[2, "rc-176"]], "1.0.0-rc.177": [[2, "rc-177"]], "1.0.0-rc.178": [[2, "rc-178"]], "1.0.0-rc.179": [[2, "rc-179"]], "1.0.0-rc.180": [[2, "rc-180"]], "1.0.0-rc.181": [[2, "rc-181"]], "1.0.0-rc.182": [[2, "rc-182"]], "1.0.0-rc.183": [[2, "rc-183"]], "1.0.0-rc.184": [[2, "rc-184"]], "1.0.0-rc.185": [[2, "rc-185"]], "1.0.0-rc.186": [[2, "rc-186"]], "1.0.0-rc.24": [[2, "rc-24"]], "1.0.0-rc.25": [[2, "rc-25"]], "1.0.0-rc.26": [[2, "rc-26"]], "1.0.0-rc.27": [[2, "rc-27"]], "1.0.0-rc.28": [[2, "rc-28"]], "1.0.0-rc.29": [[2, "rc-29"]], "1.0.0-rc.30": [[2, "rc-30"]], "1.0.0-rc.31": [[2, "rc-31"]], "1.0.0-rc.32": [[2, "rc-32"]], "1.0.0-rc.33": [[2, "rc-33"]], "1.0.0-rc.34": [[2, "rc-34"]], "1.0.0-rc.35": [[2, "rc-35"]], "1.0.0-rc.36": [[2, "rc-36"]], "1.0.0-rc.37": [[2, "rc-37"]], "1.0.0-rc.38": [[2, "rc-38"]], "1.0.0-rc.39": [[2, "rc-39"]], "1.0.0-rc.40": [[2, "rc-40"]], "1.0.0-rc.41": [[2, "rc-41"]], "1.0.0-rc.42": [[2, "rc-42"]], "1.0.0-rc.43": [[2, "rc-43"]], "1.0.0-rc.44": [[2, "rc-44"]], "1.0.0-rc.45": [[2, "rc-45"]], "1.0.0-rc.46": [[2, "rc-46"]], "1.0.0-rc.47": [[2, "rc-47"]], "1.0.0-rc.48": [[2, "rc-48"]], "1.0.0-rc.49": [[2, "rc-49"]], "1.0.0-rc.50": [[2, "rc-50"]], "1.0.0-rc.51": [[2, "rc-51"]], "1.0.0-rc.52": [[2, "rc-52"]], "1.0.0-rc.53": [[2, "rc-53"]], "1.0.0-rc.54": [[2, "rc-54"]], "1.0.0-rc.55": [[2, "rc-55"]], "1.0.0-rc.56": [[2, "rc-56"]], "1.0.0-rc.57": [[2, "rc-57"]], "1.0.0-rc.58": [[2, "rc-58"]], "1.0.0-rc.59": [[2, "rc-59"]], "1.0.0-rc.60": [[2, "rc-60"]], "1.0.0-rc.61": [[2, "rc-61"]], "1.0.0-rc.62": [[2, "rc-62"]], "1.0.0-rc.63": [[2, "rc-63"]], "1.0.0-rc.64": [[2, "rc-64"]], "1.0.0-rc.65": [[2, "rc-65"]], "1.0.0-rc.66": [[2, "rc-66"]], "1.0.0-rc.67": [[2, "rc-67"]], "1.0.0-rc.68": [[2, "rc-68"]], "1.0.0-rc.69": [[2, "rc-69"]], "1.0.0-rc.70": [[2, "rc-70"]], "1.0.0-rc.71": [[2, "rc-71"]], "1.0.0-rc.72": [[2, "rc-72"]], "1.0.0-rc.73": [[2, "rc-73"]], "1.0.0-rc.74": [[2, "rc-74"]], "1.0.0-rc.75": [[2, "rc-75"]], "1.0.0-rc.76": [[2, "rc-76"]], "1.0.0-rc.77": [[2, "rc-77"]], "1.0.0-rc.78": [[2, "rc-78"]], "1.0.0-rc.79": [[2, "rc-79"]], "1.0.0-rc.80": [[2, "rc-80"]], "1.0.0-rc.81": [[2, "rc-81"]], "1.0.0-rc.82": [[2, "rc-82"]], "1.0.0-rc.83": [[2, "rc-83"]], "1.0.0-rc.84": [[2, "rc-84"]], "1.0.0-rc.85": [[2, "rc-85"]], "1.0.0-rc.86": [[2, "rc-86"]], "1.0.0-rc.87": [[2, "rc-87"]], "1.0.0-rc.88": [[2, "rc-88"]], "1.0.0-rc.89": [[2, "rc-89"]], "1.0.0-rc.90": [[2, "rc-90"]], "1.0.0-rc.91": [[2, "rc-91"]], "1.0.0-rc.92": [[2, "rc-92"]], "1.0.0-rc.93": [[2, "rc-93"]], "1.0.0-rc.94": [[2, "rc-94"]], "1.0.0-rc.95": [[2, "rc-95"]], "1.0.0-rc.96": [[2, "rc-96"]], "1.0.0-rc.97": [[2, "rc-97"]], "1.0.0-rc.98": [[2, "rc-98"]], "1.0.0-rc.99": [[2, "rc-99"]], "1.1 Coordinate conventions": [[5, "coordinate-conventions"]], "1.2 Two-theta, azimuth, resolution and q": [[5, "two-theta-azimuth-resolution-and-q"]], "1.3 Distance from the Ewald sphere": [[5, "distance-from-the-ewald-sphere"]], "1.4 The beam centre": [[5, "the-beam-centre"]], "1.5 Finding the beam stop": [[5, "finding-the-beam-stop"]], "1.6 Defective pixels": [[5, "defective-pixels"]], "1.7 The saturation level": [[5, "the-saturation-level"]], "10. Scaling and merging": [[7, "scaling-and-merging"]], "10.1 Observation model": [[7, "observation-model"]], "10.10 Ice rings at the scale and merge stages": [[7, "ice-rings-at-the-scale-and-merge-stages"]], "10.2 Partiality models": [[7, "partiality-models"]], "10.3 Smoothing of per-frame scales": [[7, "smoothing-of-per-frame-scales"]], "10.4 Merging estimator": [[7, "merging-estimator"]], "10.5 Merging statistics": [[7, "merging-statistics"]], "10.6 Rotation datasets: combining partials into fulls (3D integration)": [[7, "rotation-datasets-combining-partials-into-fulls-3d-integration"]], "10.7 R-free test-set flags": [[7, "r-free-test-set-flags"]], "10.8 French\u2013Wilson amplitudes": [[7, "frenchwilson-amplitudes"]], "10.9 Reference data: fixing the space group and resolving the indexing ambiguity": [[7, "reference-data-fixing-the-space-group-and-resolving-the-indexing-ambiguity"]], "11. Mosaicity and \u201cprofile radius\u201d monitoring": [[7, "mosaicity-and-profile-radius-monitoring"]], "11.1 Profile radius (intrinsic excitation-error width)": [[7, "profile-radius-intrinsic-excitation-error-width"]], "11.2 Mosaicity from rotation data": [[7, "mosaicity-from-rotation-data"]], "12. Auxiliary statistics: \u27e8I/\u03c3(I)\u27e9 and Wilson plot": [[7, "auxiliary-statistics-i-i-and-wilson-plot"]], "12.1 Per-shell \u27e8I/\u03c3(I)\u27e9": [[7, "per-shell-i-i"]], "12.2 Wilson plot (B-factor proxy)": [[7, "wilson-plot-b-factor-proxy"]], "13. Space-group determination and merge-level decisions": [[4, "space-group-determination-and-merge-level-decisions"]], "13.1 Space-group determination": [[4, "space-group-determination"]], "13.2 Twinning check, and translational pseudo-symmetry": [[4, "twinning-check-and-translational-pseudo-symmetry"]], "13.3 Outlier rejection": [[4, "outlier-rejection"]], "13.4 Automatic resolution cutoff": [[4, "automatic-resolution-cutoff"]], "13.5 Diffraction anisotropy": [[4, "diffraction-anisotropy"]], "13.6 Practical notes and limitations": [[4, "practical-notes-and-limitations"]], "14. Model-based validation: R-free against a model and electron-density maps": [[4, "model-based-validation-r-free-against-a-model-and-electron-density-maps"]], "14.1 Model structure factors": [[4, "model-structure-factors"]], "14.10 Molecular replacement: placing a model the rigid body cannot": [[4, "molecular-replacement-placing-a-model-the-rigid-body-cannot"]], "14.2 Bulk solvent and scaling": [[4, "bulk-solvent-and-scaling"]], "14.3 R-work and R-free": [[4, "r-work-and-r-free"]], "14.4 Electron-density maps": [[4, "electron-density-maps"]], "14.5 Does the model fit? The null it is scored against": [[4, "does-the-model-fit-the-null-it-is-scored-against"]], "14.6 Aligning the data to the model: enantiomorph and indexing ambiguity": [[4, "aligning-the-data-to-the-model-enantiomorph-and-indexing-ambiguity"]], "14.7 Anomalous difference map and the sites it names": [[4, "anomalous-difference-map-and-the-sites-it-names"]], "14.8 Rigid-body placement of the model": [[4, "rigid-body-placement-of-the-model"]], "14.9 The twin hypothesis: which merge the maps come from": [[4, "the-twin-hypothesis-which-merge-the-maps-come-from"]], "15. Restrained refinement of a placed model": [[8, "restrained-refinement-of-a-placed-model"]], "15.1 What is refined, and in what order": [[8, "what-is-refined-and-in-what-order"]], "15.10 The solvent audit": [[8, "the-solvent-audit"]], "15.11 GPU and CPU": [[8, "gpu-and-cpu"]], "15.12 Twinned data": [[8, "twinned-data"]], "15.13 Not yet": [[8, "not-yet"]], "15.2 The X-ray target": [[8, "the-x-ray-target"]], "15.3 Scale, bulk solvent and the likelihood parameters": [[8, "scale-bulk-solvent-and-the-likelihood-parameters"]], "15.4 The dictionary and the topology": [[8, "the-dictionary-and-the-topology"]], "15.5 Geometry, metal and B restraints": [[8, "geometry-metal-and-b-restraints"]], "15.6 The minimiser": [[8, "the-minimiser"]], "15.7 The weights, decided by trial": [[8, "the-weights-decided-by-trial"]], "15.8 Maps of the refined model": [[8, "maps-of-the-refined-model"]], "15.9 Unexplained density: blobs": [[8, "unexplained-density-blobs"]], "2. Azimuthal integration (radial profiles)": [[5, "azimuthal-integration-radial-profiles"]], "2. File layout": [[23, "file-layout"]], "2. Known issues": [[51, "known-issues"]], "2.1 Histogram estimator": [[5, "histogram-estimator"]], "2.2 Corrections applied": [[5, "corrections-applied"]], "2.3 Background estimate for profiles": [[5, "background-estimate-for-profiles"]], "3. Authenticated read access \u2014 per-dataset bearer tokens": [[51, "authenticated-read-access-per-dataset-bearer-tokens"]], "3. NXmx-standard content": [[23, "nxmx-standard-content"]], "3. Spot finding (strong pixels \u2192 Bragg spots)": [[5, "spot-finding-strong-pixels-bragg-spots"]], "3.1 Strong-pixel detection by local statistics": [[5, "strong-pixel-detection-by-local-statistics"]], "3.2 Adaptive (self-calibrating) detection": [[5, "adaptive-self-calibrating-detection"]], "3.3 Resolution and ice-ring handling": [[5, "resolution-and-ice-ring-handling"]], "3.4 Connected-component labeling (CCL)": [[5, "connected-component-labeling-ccl"]], "3.5 Adaptive per-image minimum spot size": [[5, "adaptive-per-image-minimum-spot-size"]], "3.6 Predicting the resolution the merged data will reach": [[5, "predicting-the-resolution-the-merged-data-will-reach"]], "4. Extensions beyond NXmx": [[23, "extensions-beyond-nxmx"]], "4. Indexing overview": [[6, "indexing-overview"]], "4.1 /entry/MX \u2014 spot finding and indexing (CXI-style)": [[23, "entry-mx-spot-finding-and-indexing-cxi-style"]], "4.1 Indexed-spot decision (inlier test)": [[6, "indexed-spot-decision-inlier-test"]], "4.10 Non-standard fields inside the NXmx detector group": [[23, "non-standard-fields-inside-the-nxmx-detector-group"]], "4.11 User-supplied metadata: header_appendix and image_appendix": [[23, "user-supplied-metadata-header-appendix-and-image-appendix"]], "4.2 /entry/reflections \u2014 integrated reflections (NXreflections)": [[23, "entry-reflections-integrated-reflections-nxreflections"]], "4.2 The spot budget": [[6, "the-spot-budget"]], "4.3 /entry/azint \u2014 azimuthal integration": [[23, "entry-azint-azimuthal-integration"]], "4.3 Fast-feedback indexing (known unit cell)": [[6, "fast-feedback-indexing-known-unit-cell"]], "4.4 /entry/roi \u2014 regions of interest (per-image results)": [[23, "entry-roi-regions-of-interest-per-image-results"]], "4.4.1 /entry/roi_defs \u2014 ROI definitions (master file)": [[23, "entry-roi-defs-roi-definitions-master-file"]], "4.5 /entry/image \u2014 per-image pixel statistics": [[23, "entry-image-per-image-pixel-statistics"]], "4.6 /entry/profiling \u2014 per-image timing": [[23, "entry-profiling-per-image-timing"]], "4.7 /entry/detector \u2014 acquisition diagnostics (data file)": [[23, "entry-detector-acquisition-diagnostics-data-file"]], "4.8 /entry/xfel \u2014 pulsed-source metadata": [[23, "entry-xfel-pulsed-source-metadata"]], "4.9 Other collections": [[23, "other-collections"]], "5. FFT indexing (unknown unit cell)": [[6, "fft-indexing-unknown-unit-cell"]], "5. Notes": [[23, "notes"]], "5.1 Directional projections and histograms": [[6, "directional-projections-and-histograms"]], "5.2 FFT peak picking and candidate vectors": [[6, "fft-peak-picking-and-candidate-vectors"]], "5.3 Lattice reduction and cell candidates": [[6, "lattice-reduction-and-cell-candidates"]], "5.4 Robust refinement and best-cell selection": [[6, "robust-refinement-and-best-cell-selection"]], "5.5 Spindle alignment: the part of the blind cone symmetry cannot repair": [[6, "spindle-alignment-the-part-of-the-blind-cone-symmetry-cannot-repair"]], "6. Bravais lattice / centering inference (\u201clattice search\u201d)": [[6, "bravais-lattice-centering-inference-lattice-search"]], "6OWW: a monoclinic deposition whose intensities read tetragonal": [[12, "oww-a-monoclinic-deposition-whose-intensities-read-tetragonal"]], "7. Geometry and lattice refinement": [[6, "geometry-and-lattice-refinement"]], "7.1 Parameterization": [[6, "parameterization"]], "7.2 Residuals and objective": [[6, "residuals-and-objective"]], "7.3 Rotation datasets: bringing observations to a common reference frame": [[6, "rotation-datasets-bringing-observations-to-a-common-reference-frame"]], "7.4 Multi-stage tightening of inlier tolerance": [[6, "multi-stage-tightening-of-inlier-tolerance"]], "7.5 Rotation geometry post-refinement (two-pass)": [[6, "rotation-geometry-post-refinement-two-pass"]], "7.6 Detector geometry from powder rings": [[6, "detector-geometry-from-powder-rings"]], "7.7 Stills: a given cell and the detector modules": [[6, "stills-a-given-cell-and-the-detector-modules"]], "8. Reflection prediction": [[7, "reflection-prediction"]], "8.1 Enumerating reciprocal lattice points": [[7, "enumerating-reciprocal-lattice-points"]], "8.2 Still prediction (excitation-error cutoff)": [[7, "still-prediction-excitation-error-cutoff"]], "8.3 Rotation prediction (Laue equation + partiality model)": [[7, "rotation-prediction-laue-equation-partiality-model"]], "8.4 Systematic absences (centering)": [[7, "systematic-absences-centering"]], "8XBP is a question about provenance, not about symmetry": [[12, "xbp-is-a-question-about-provenance-not-about-symmetry"]], "9. 2D Bragg integration (profile fitting over a three-ring ROI)": [[7, "d-bragg-integration-profile-fitting-over-a-three-ring-roi"]], "9.1 Regions of interest": [[7, "regions-of-interest"]], "9.2 Box summation (seed and fallback)": [[7, "box-summation-seed-and-fallback"]], "9.3 Profile-fitted extraction (default)": [[7, "profile-fitted-extraction-default"]], "9.4 The prescaling correction": [[7, "the-prescaling-correction"]], "9.5 Choosing the signal radius from the crystal\u2019s own spots (rotation)": [[7, "choosing-the-signal-radius-from-the-crystals-own-spots-rotation"]], "9.6 Measuring the bandwidth": [[7, "measuring-the-bandwidth"]], "9.7 The flight path": [[7, "the-flight-path"]], "9RCI: two defensible descriptions of one lattice": [[12, "rci-two-defensible-descriptions-of-one-lattice"]], "A detector swung out on a 2theta arm": [[11, "a-detector-swung-out-on-a-2theta-arm"]], "A first run": [[45, "a-first-run"]], "A first run in detail": [[50, "a-first-run-in-detail"]], "A grid scan": [[26, "a-grid-scan"]], "A guided tour": [[26, "a-guided-tour"]], "A quiet machine": [[40, "a-quiet-machine"]], "A run with --model, step by step": [[47, "a-run-with-model-step-by-step"]], "ACK handling": [[24, "ack-handling"]], "ACK semantics": [[24, "ack-semantics"]], "ADU histogram": [[15, "adu-histogram"]], "AXI Mailbox": [[20, "axi-mailbox"]], "Acknowledgements": [[0, null], [27, "acknowledgements"]], "Advanced Rugnux": [[39, null]], "Advice on the next collection": [[49, "advice-on-the-next-collection"]], "After downloading": [[43, "after-downloading"], [59, "after-downloading"]], "All options": [[42, "all-options"]], "All pages": [[61, "all-pages"]], "An archive that ships placeholder images": [[12, "an-archive-that-ships-placeholder-images"]], "Apple GPUs (Metal)": [[21, "apple-gpus-metal"]], "Archives that are not a single sweep": [[12, "archives-that-are-not-a-single-sweep"]], "Arms and references": [[40, "arms-and-references"]], "Artefacts": [[36, "artefacts"]], "Author": [[62, "author"]], "Authorization": [[71, "authorization"], [71, "id4"], [71, "id10"], [71, "id16"], [71, "id22"], [71, "id28"], [71, "id34"], [71, "id40"], [71, "id46"], [71, "id52"], [71, "id58"], [71, "id64"], [71, "id70"], [71, "id76"], [71, "id82"], [71, "id88"], [71, "id94"], [71, "id100"], [71, "id106"], [71, "id112"], [71, "id118"], [71, "id124"], [71, "id130"], [71, "id136"], [71, "id142"], [71, "id148"], [71, "id154"], [71, "id160"], [71, "id166"], [71, "id172"], [71, "id178"], [71, "id184"], [71, "id190"], [71, "id196"], [71, "id202"], [71, "id208"], [71, "id214"], [71, "id220"], [71, "id226"], [71, "id232"], [71, "id238"], [71, "id244"], [71, "id250"], [71, "id256"], [71, "id262"], [71, "id268"], [71, "id274"], [71, "id280"], [71, "id286"], [71, "id292"], [71, "id298"], [71, "id304"], [71, "id310"], [71, "id316"], [71, "id322"], [71, "id328"], [71, "id334"], [71, "id340"], [71, "id346"], [71, "id352"], [71, "id358"], [71, "id364"], [71, "id370"], [71, "id376"], [71, "id382"], [71, "id388"], [71, "id394"], [71, "id400"], [71, "id406"], [71, "id412"], [71, "id418"], [71, "id424"], [71, "id430"]], "AzimIntSettings": [[63, null]], "Azimuthal integration": [[15, "azimuthal-integration"], [42, "azimuthal-integration"]], "Azimuthal integration (--mode azint)": [[42, "azimuthal-integration-mode-azint"]], "Battery rows whose id is not the PDB code": [[12, "battery-rows-whose-id-is-not-the-pdb-code"]], "Beam centre": [[42, "beam-centre"]], "BraggIntegrationSettings": [[64, null]], "Broker configuration": [[25, "broker-configuration"]], "BrokerStatus": [[65, null]], "Build like CI": [[40, "build-like-ci"]], "Building firmware": [[14, "building-firmware"]], "Building from source": [[45, "building-from-source"]], "Building from source on Windows": [[26, "building-from-source-on-windows"]], "Building from source on macOS": [[26, "building-from-source-on-macos"]], "CBOR messages": [[1, null]], "CC(model, data)": [[49, "cc-model-data"]], "CERN Open Hardware Licence Version 2 - Strongly Reciprocal": [[17, "cern-open-hardware-licence-version-2-strongly-reciprocal"]], "CMake file": [[19, "cmake-file"]], "CPU instruction set": [[36, "cpu-instruction-set"]], "CPU only": [[40, "cpu-only"]], "CPU-side crystallographic data analysis (Jungfraujoch)": [[3, null]], "CUDA and non-CUDA builds": [[36, "cuda-and-non-cuda-builds"]], "Calibration (--mode calibration)": [[42, "calibration-mode-calibration"]], "Calibration message": [[1, "calibration-message"]], "CalibrationStatisticsInner": [[66, null]], "Card verification": [[9, "card-verification"]], "Cell e.s.d.s": [[49, "cell-e-s-d-s"]], "Cell reduction and lattice symmetry": [[0, "cell-reduction-and-lattice-symmetry"]], "Changelog": [[2, null]], "Character device access": [[19, "character-device-access"]], "Command-line options": [[39, "command-line-options"], [42, null]], "Comparing runs": [[40, "comparing-runs"]], "Comparing the geometry with XDS": [[46, "comparing-the-geometry-with-xds"]], "Comparing two runs: R_MODEL_SHELL_SCALED": [[49, "comparing-two-runs-r-model-shell-scaled"]], "Compilation": [[19, "compilation"]], "Compile Jungfraujoch with frontend": [[25, "compile-jungfraujoch-with-frontend"]], "Configure network": [[9, "configure-network"]], "Cost": [[40, "cost"]], "CrystFEL": [[53, "crystfel"]], "Crystallographic methods adopted from other packages": [[0, "crystallographic-methods-adopted-from-other-packages"]], "Custom user mask": [[33, "custom-user-mask"]], "D-Bus interface": [[26, "d-bus-interface"]], "DECTRIS detectors": [[10, "dectris-detectors"]], "DIALS": [[53, "dials"]], "DKMS": [[19, "dkms"]], "DarkMaskSettings": [[67, null]], "Data analysis": [[54, null], [57, "data-analysis"]], "Data analysis: from images to spots (\u00a70\u2013\u00a73)": [[5, null]], "Data analysis: indexing and geometry (\u00a74\u2013\u00a77)": [[6, null]], "Data analysis: integration, scaling and merging (\u00a78\u2013\u00a712)": [[7, null]], "Data analysis: refinement of a placed model (\u00a715)": [[8, null]], "Data analysis: space group and validation (\u00a713\u2013\u00a714)": [[4, null]], "Data files in the repository": [[56, "data-files-in-the-repository"]], "Data quality and anisotropy": [[0, "data-quality-and-anisotropy"]], "Data streams": [[24, null]], "DatasetSettings": [[68, null]], "DatasetSettingsSmargon": [[69, null]], "DatasetSettingsXrayFluorescenceSpectrum": [[70, null]], "Datasets": [[12, "datasets"], [13, "datasets"]], "Datasets in the table that are not in the battery": [[12, "datasets-in-the-table-that-are-not-in-the-battery"]], "Datasets published as Raw Data Letters": [[12, "datasets-published-as-raw-data-letters"]], "Datasets with no PDB entry": [[12, "datasets-with-no-pdb-entry"]], "Decision by decision": [[47, "decision-by-decision"]], "Deployment": [[9, null]], "Deposited models and structure factors": [[12, "deposited-models-and-structure-factors"]], "Detector": [[72, null]], "Detector calibration (--mode calibration)": [[42, "detector-calibration-mode-calibration"]], "Detector calibration from powder rings (rugnux --mode calibration)": [[41, null]], "Detector column for marCCD and SMV files": [[12, "detector-column-for-marccd-and-smv-files"]], "Detector geometry": [[11, null]], "Detector mask": [[42, "detector-mask"]], "DetectorList": [[73, null]], "DetectorListElement": [[74, null]], "DetectorModule": [[75, null]], "DetectorModuleDirection": [[76, null]], "DetectorModulePlacement": [[77, null]], "DetectorPowerState": [[78, null]], "DetectorSelection": [[79, null]], "DetectorSettings": [[80, null]], "DetectorState": [[81, null]], "DetectorStatus": [[82, null]], "DetectorTiming": [[83, null]], "DetectorType": [[84, null]], "Development": [[54, null]], "Diffraction anisotropy": [[49, "diffraction-anisotropy"]], "Diffraction image": [[26, "diffraction-image"]], "Do not time the first run after a build": [[40, "do-not-time-the-first-run-after-a-build"]], "Documentation": [[61, null]], "Documentation For Authorization": [[62, "documentation-for-authorization"]], "Documentation For Models": [[62, "documentation-for-models"]], "Documentation for API Endpoints": [[62, "documentation-for-api-endpoints"]], "Download Rugnux": [[43, null]], "Download the Jungfraujoch Viewer": [[59, null]], "Driver parameters": [[19, "driver-parameters"]], "End message": [[1, "end-message"]], "Enum": [[76, "enum"], [78, "enum"], [81, "enum"], [83, "enum"], [84, "enum"], [86, "enum"], [89, "enum"], [94, "enum"], [95, "enum"], [98, "enum"], [105, "enum"], [111, "enum"]], "ErrorMessage": [[85, null]], "Every option that brings in a model or reference data": [[47, "every-option-that-brings-in-a-model-or-reference-data"]], "Example": [[63, "example"], [64, "example"], [65, "example"], [66, "example"], [67, "example"], [68, "example"], [69, "example"], [70, "example"], [71, "example"], [71, "id1"], [71, "id7"], [71, "id13"], [71, "id19"], [71, "id25"], [71, "id31"], [71, "id37"], [71, "id43"], [71, "id49"], [71, "id55"], [71, "id61"], [71, "id67"], [71, "id73"], [71, "id79"], [71, "id85"], [71, "id91"], [71, "id97"], [71, "id103"], [71, "id109"], [71, "id115"], [71, "id121"], [71, "id127"], [71, "id133"], [71, "id139"], [71, "id145"], [71, "id151"], [71, "id157"], [71, "id163"], [71, "id169"], [71, "id175"], [71, "id181"], [71, "id187"], [71, "id193"], [71, "id199"], [71, "id205"], [71, "id211"], [71, "id217"], [71, "id223"], [71, "id229"], [71, "id235"], [71, "id241"], [71, "id247"], [71, "id253"], [71, "id259"], [71, "id265"], [71, "id271"], [71, "id277"], [71, "id283"], [71, "id289"], [71, "id295"], [71, "id301"], [71, "id307"], [71, "id313"], [71, "id319"], [71, "id325"], [71, "id331"], [71, "id337"], [71, "id343"], [71, "id349"], [71, "id355"], [71, "id361"], [71, "id367"], [71, "id373"], [71, "id379"], [71, "id385"], [71, "id391"], [71, "id397"], [71, "id403"], [71, "id409"], [71, "id415"], [71, "id421"], [71, "id427"], [72, "example"], [73, "example"], [74, "example"], [75, "example"], [77, "example"], [79, "example"], [80, "example"], [82, "example"], [85, "example"], [87, "example"], [88, "example"], [90, "example"], [91, "example"], [92, "example"], [93, "example"], [96, "example"], [97, "example"], [99, "example"], [100, "example"], [101, "example"], [102, "example"], [103, "example"], [104, "example"], [106, "example"], [107, "example"], [108, "example"], [109, "example"], [110, "example"], [112, "example"], [113, "example"], [114, "example"], [115, "example"], [116, "example"], [117, "example"], [118, "example"], [119, "example"], [120, "example"], [121, "example"], [122, "example"], [123, "example"], [124, "example"], [125, "example"], [126, "example"], [127, "example"], [128, "example"], [129, "example"], [130, "example"], [131, "example"], [132, "example"], [133, "example"], [134, "example"], [135, "example"], [136, "example"], [137, "example"], [138, "example"], [139, "example"], [140, "example"]], "Exchange buffers": [[19, "exchange-buffers"]], "Expected result": [[25, "expected-result"]], "Experimental geometry and physical corrections": [[0, "experimental-geometry-and-physical-corrections"]], "Experimental phasing with SHELX": [[46, "experimental-phasing-with-shelx"]], "External interfaces": [[25, "external-interfaces"]], "External test data": [[12, null]], "External test data: serial crystallography (XFEL stills)": [[13, null]], "FPGA": [[22, "fpga"]], "FPGA / PCIe card management": [[57, "fpga-pcie-card-management"]], "FPGA PCIe driver": [[19, null]], "FPGA advanced reference": [[20, null]], "FPGA data analysis": [[15, null]], "FPGA data flow": [[16, null]], "FPGA license": [[17, null]], "FPGA network": [[18, null]], "FPGA smartNIC": [[14, null]], "Fetched at build time and statically linked into the C++ binaries": [[56, "fetched-at-build-time-and-statically-linked-into-the-c-binaries"]], "File formats read from a published specification": [[0, "file-formats-read-from-a-published-specification"]], "FileWriterFormat": [[86, null]], "FileWriterSettings": [[87, null]], "Finalized files information": [[27, "finalized-files-information"]], "Firmware flashing": [[9, "firmware-flashing"]], "Firmware releases": [[14, "firmware-releases"]], "Flash the U55C FPGA card with a proper image and install Linux kernel driver": [[9, "flash-the-u55c-fpga-card-with-a-proper-image-and-install-linux-kernel-driver"]], "Following a collection": [[25, "following-a-collection"]], "Format": [[49, "format"]], "Formats and interfaces": [[54, null]], "Four kinds of influence": [[47, "four-kinds-of-influence"]], "Four trigonal and tetragonal rows where we read a higher point group": [[12, "four-trigonal-and-tetragonal-rows-where-we-read-a-higher-point-group"]], "FpgaStatusInner": [[88, null]], "Frame generator": [[14, "frame-generator"]], "Frame summation": [[15, "frame-summation"]], "Frame types": [[24, "frame-types"]], "Free set and model bias": [[47, "free-set-and-model-bias"]], "From source": [[43, "from-source"], [59, "from-source"]], "From the package repositories (RHEL / Rocky / Ubuntu)": [[45, "from-the-package-repositories-rhel-rocky-ubuntu"]], "From the release archive": [[45, "from-the-release-archive"]], "Frontend (npm) dependencies": [[56, "frontend-npm-dependencies"]], "Functionality": [[26, "functionality"]], "Funding and support": [[0, "funding-and-support"]], "Further lattices": [[49, "further-lattices"]], "GNU GENERAL PUBLIC LICENSE": [[29, "gnu-general-public-license"]], "GPU data analysis": [[21, null]], "GPU generations and the NVIDIA driver": [[36, "gpu-generations-and-the-nvidia-driver"]], "GPU support": [[45, "gpu-support"]], "GPUs": [[22, "gpus"]], "General": [[42, "general"]], "Generative AI usage declaration": [[0, "generative-ai-usage-declaration"]], "GeomRefinementAlgorithm": [[89, null]], "Geometry overrides": [[42, "geometry-overrides"]], "Getting Started": [[62, "getting-started"]], "Getting the image onto the card": [[21, "getting-the-image-onto-the-card"]], "Grid scan": [[26, "grid-scan"]], "GridScan": [[90, null]], "HBM memory": [[20, "hbm-memory"]], "HDF5 / NeXus data format": [[23, null]], "HDF5 file structure": [[27, "hdf5-file-structure"]], "HLS compilation": [[14, "hls-compilation"]], "HTTP request headers": [[71, "http-request-headers"], [71, "id5"], [71, "id11"], [71, "id17"], [71, "id23"], [71, "id29"], [71, "id35"], [71, "id41"], [71, "id47"], [71, "id53"], [71, "id59"], [71, "id65"], [71, "id71"], [71, "id77"], [71, "id83"], [71, "id89"], [71, "id95"], [71, "id101"], [71, "id107"], [71, "id113"], [71, "id119"], [71, "id125"], [71, "id131"], [71, "id137"], [71, "id143"], [71, "id149"], [71, "id155"], [71, "id161"], [71, "id167"], [71, "id173"], [71, "id179"], [71, "id185"], [71, "id191"], [71, "id197"], [71, "id203"], [71, "id209"], [71, "id215"], [71, "id221"], [71, "id227"], [71, "id233"], [71, "id239"], [71, "id245"], [71, "id251"], [71, "id257"], [71, "id263"], [71, "id269"], [71, "id275"], [71, "id281"], [71, "id287"], [71, "id293"], [71, "id299"], [71, "id305"], [71, "id311"], [71, "id317"], [71, "id323"], [71, "id329"], [71, "id335"], [71, "id341"], [71, "id347"], [71, "id353"], [71, "id359"], [71, "id365"], [71, "id371"], [71, "id377"], [71, "id383"], [71, "id389"], [71, "id395"], [71, "id401"], [71, "id407"], [71, "id413"], [71, "id419"], [71, "id425"], [71, "id431"]], "HTTP response details": [[71, "http-response-details"], [71, "id6"], [71, "id12"], [71, "id18"], [71, "id24"], [71, "id30"], [71, "id36"], [71, "id42"], [71, "id48"], [71, "id54"], [71, "id60"], [71, "id66"], [71, "id72"], [71, "id78"], [71, "id84"], [71, "id90"], [71, "id96"], [71, "id102"], [71, "id108"], [71, "id114"], [71, "id120"], [71, "id126"], [71, "id132"], [71, "id138"], [71, "id144"], [71, "id150"], [71, "id156"], [71, "id162"], [71, "id168"], [71, "id174"], [71, "id180"], [71, "id186"], [71, "id192"], [71, "id198"], [71, "id204"], [71, "id210"], [71, "id216"], [71, "id222"], [71, "id228"], [71, "id234"], [71, "id240"], [71, "id246"], [71, "id252"], [71, "id258"], [71, "id264"], [71, "id270"], [71, "id276"], [71, "id282"], [71, "id288"], [71, "id294"], [71, "id300"], [71, "id306"], [71, "id312"], [71, "id318"], [71, "id324"], [71, "id330"], [71, "id336"], [71, "id342"], [71, "id348"], [71, "id354"], [71, "id360"], [71, "id366"], [71, "id372"], [71, "id378"], [71, "id384"], [71, "id390"], [71, "id396"], [71, "id402"], [71, "id408"], [71, "id414"], [71, "id420"], [71, "id426"], [71, "id432"]], "Hardware": [[14, "hardware"], [26, "hardware"], [45, "hardware"]], "Hardware and FPGA": [[54, null]], "Hardware requirements": [[22, null]], "High performance server": [[22, "high-performance-server"]], "How the battery runs them": [[13, "how-the-battery-runs-them"]], "How to Apply These Terms to Your New Programs": [[29, "how-to-apply-these-terms-to-your-new-programs"]], "How to cite": [[28, "how-to-cite"], [34, "how-to-cite"], [38, "how-to-cite"]], "Image message": [[1, "image-message"]], "Image stream": [[24, "image-stream"]], "Image stream replacement": [[24, "image-stream-replacement"]], "ImageBufferStatus": [[91, null]], "ImageFormatSettings": [[92, null]], "ImagePusherStatus": [[93, null]], "ImagePusherType": [[94, null]], "In short": [[47, "in-short"]], "Index-2 superstructure": [[49, "index-2-superstructure"]], "Indexing": [[0, "indexing"], [21, "indexing"], [42, "indexing"]], "IndexingAlgorithm": [[95, null]], "IndexingSettings": [[96, null]], "Input formats": [[44, null]], "Inputs": [[42, "inputs"]], "Inside: two axis vectors; outside: rot1/rot2/rot3": [[11, "inside-two-axis-vectors-outside-rot1-rot2-rot3"]], "Install Jungfraujoch Python client": [[9, "install-jungfraujoch-python-client"]], "Install Jungfraujoch image viewer": [[9, "install-jungfraujoch-image-viewer"]], "Install Jungfraujoch writer": [[9, "install-jungfraujoch-writer"]], "Install PCIe driver": [[9, "install-pcie-driver"]], "Install Rugnux (offline analysis)": [[9, "install-rugnux-offline-analysis"]], "Install main Jungfraujoch code and frontend web interface": [[9, "install-main-jungfraujoch-code-and-frontend-web-interface"]], "Installation": [[19, "installation"]], "Installation & Usage": [[62, "installation-usage"]], "Installing": [[28, "installing"]], "Installing Rugnux": [[45, null]], "InstrumentMetadata": [[97, null]], "Integration": [[42, "integration"]], "Integration and rotation geometry": [[0, "integration-and-rotation-geometry"]], "Integration with MX data processing software": [[53, null]], "IntegrationModel": [[98, null]], "Interleave: ABAB, not AB": [[40, "interleave-abab-not-ab"]], "JUNGFRAU conversion": [[15, "jungfrau-conversion"]], "JfjochSettings": [[99, null]], "JfjochStatistics": [[100, null]], "Judging a change to the analysis itself": [[55, "judging-a-change-to-the-analysis-itself"]], "Jungfraujoch": [[30, "jungfraujoch"], [34, "jungfraujoch"], [61, null]], "Jungfraujoch Viewer": [[61, null]], "Jungfraujoch exceptions to GPL": [[29, "jungfraujoch-exceptions-to-gpl"]], "Jungfraujoch: data acquisition": [[28, null]], "Keepalive": [[24, "keepalive"]], "Known problems": [[19, "known-problems"]], "Licences": [[12, "licences"]], "License": [[29, null]], "License Clarification": [[62, "license-clarification"]], "Licenses": [[36, "licenses"]], "Limits": [[40, "limits"]], "Linux package repositories": [[37, null]], "Linux packages": [[43, "linux-packages"]], "Loading driver into kernel": [[19, "loading-driver-into-kernel"]], "Looking at an image": [[26, "looking-at-an-image"]], "Macromolecular crystallography convention for the vertical direction": [[11, "macromolecular-crystallography-convention-for-the-vertical-direction"]], "Manual pages": [[38, "manual-pages"]], "Mask format": [[33, "mask-format"]], "MeasurementStatistics": [[101, null]], "Measuring Rugnux: validation and timing": [[40, null]], "Memory": [[27, "memory"], [45, "memory"]], "Memory and hardware": [[43, "memory-and-hardware"]], "Memory peaks": [[40, "memory-peaks"]], "Metadata message": [[1, "metadata-message"]], "Metadata stream": [[24, "metadata-stream"]], "Mirrored and quarter-turned detectors": [[11, "mirrored-and-quarter-turned-detectors"]], "Mode": [[42, "mode"]], "Model placement and molecular replacement": [[0, "model-placement-and-molecular-replacement"]], "Model validation": [[21, "model-validation"], [49, "model-validation"]], "Models and reference data": [[47, null]], "Module geometry": [[44, "module-geometry"]], "Module placement file (_module_placement.json)": [[44, "module-placement-file-prefix-module-placement-json"]], "Molecular replacement": [[21, "molecular-replacement"], [49, "molecular-replacement"]], "Molecular replacement with Phaser": [[46, "molecular-replacement-with-phaser"]], "Mosaicity": [[49, "mosaicity"]], "Mouse shortcuts": [[26, "mouse-shortcuts"]], "Multi-sweep battery rows": [[12, "multi-sweep-battery-rows"]], "NVTX ranges for Nsight Systems": [[40, "nvtx-ranges-for-nsight-systems"]], "Naming": [[30, null]], "Network LEDs": [[18, "network-leds"]], "Network stack": [[18, "network-stack"]], "Network switch": [[22, "network-switch"]], "No file option(s)": [[27, "no-file-option-s"]], "Notes on gzipped text": [[1, "notes-on-gzipped-text"]], "Notes on images and compression": [[1, "notes-on-images-and-compression"]], "Notes on typed arrays": [[1, "notes-on-typed-arrays"]], "Notes on weak-copyleft and attribution-sensitive components": [[56, "notes-on-weak-copyleft-and-attribution-sensitive-components"]], "OVERLOAD must be set by hand": [[53, "overload-must-be-set-by-hand"]], "On this page": [[4, "on-this-page"], [5, "on-this-page"], [6, "on-this-page"], [7, "on-this-page"], [8, "on-this-page"], [23, "on-this-page"], [38, "on-this-page"], [39, "on-this-page"], [40, "on-this-page"], [42, "on-this-page"], [45, "on-this-page"], [46, "on-this-page"], [47, "on-this-page"], [49, "on-this-page"], [50, "on-this-page"]], "Online analysis": [[25, "online-analysis"]], "OpenAPI": [[31, null]], "OpenAPI Python client": [[35, null]], "OpenAPI specification": [[32, null]], "OpenAPI specs": [[31, "openapi-specs"]], "Opening data": [[26, "opening-data"]], "Operating system": [[52, "operating-system"]], "Operating-system floor": [[36, "operating-system-floor"]], "Other formats (CBF and TIFF)": [[27, "other-formats-cbf-and-tiff"]], "Other views": [[26, "other-views"]], "Out of host memory": [[45, "out-of-host-memory"]], "Output files": [[38, "output-files"], [50, "output-files"]], "Overloads and overlapping spots": [[49, "overloads-and-overlapping-spots"]], "Overview": [[48, null]], "Overwriting files": [[27, "overwriting-files"]], "Ownership of the character devices": [[19, "ownership-of-the-character-devices"]], "PCI slots": [[22, "pci-slots"]], "PSI detectors": [[10, "psi-detectors"]], "Parameters": [[71, "parameters"], [71, "id2"], [71, "id8"], [71, "id14"], [71, "id20"], [71, "id26"], [71, "id32"], [71, "id38"], [71, "id44"], [71, "id50"], [71, "id56"], [71, "id62"], [71, "id68"], [71, "id74"], [71, "id80"], [71, "id86"], [71, "id92"], [71, "id98"], [71, "id104"], [71, "id110"], [71, "id116"], [71, "id122"], [71, "id128"], [71, "id134"], [71, "id140"], [71, "id146"], [71, "id152"], [71, "id158"], [71, "id164"], [71, "id170"], [71, "id176"], [71, "id182"], [71, "id188"], [71, "id194"], [71, "id200"], [71, "id206"], [71, "id212"], [71, "id218"], [71, "id224"], [71, "id230"], [71, "id236"], [71, "id242"], [71, "id248"], [71, "id254"], [71, "id260"], [71, "id266"], [71, "id272"], [71, "id278"], [71, "id284"], [71, "id290"], [71, "id296"], [71, "id302"], [71, "id308"], [71, "id314"], [71, "id320"], [71, "id326"], [71, "id332"], [71, "id338"], [71, "id344"], [71, "id350"], [71, "id356"], [71, "id362"], [71, "id368"], [71, "id374"], [71, "id380"], [71, "id386"], [71, "id392"], [71, "id398"], [71, "id404"], [71, "id410"], [71, "id416"], [71, "id422"], [71, "id428"]], "PcieDevicesInner": [[102, null]], "Per image: profiles and spots": [[21, "per-image-profiles-and-spots"]], "Per-step times: the TIMING lines": [[40, "per-step-times-the-timing-lines"]], "Pixel mask": [[15, "pixel-mask"], [33, null]], "Pixel statistics": [[15, "pixel-statistics"]], "Pixel thresholding": [[15, "pixel-thresholding"]], "PixelMaskStatistics": [[103, null]], "Plot": [[104, null]], "PlotUnitX": [[105, null]], "Plots": [[106, null]], "Powder contamination": [[49, "powder-contamination"]], "PowderCalibrationFitSigma": [[107, null]], "PowderCalibrationOutput": [[108, null]], "PowderCalibrationQuality": [[109, null]], "PowderCalibrationSpotCheck": [[110, null]], "Practical guidance": [[47, "practical-guidance"]], "Pre-flight": [[24, "pre-flight"]], "Pre-scan accumulators": [[21, "pre-scan-accumulators"]], "Preamble": [[29, "preamble"]], "Prediction and integration": [[21, "prediction-and-integration"]], "Preview stream": [[24, "preview-stream"]], "Processing results": [[26, "processing-results"]], "Processing settings": [[26, "processing-settings"]], "Project": [[61, null]], "Properties": [[63, "properties"], [64, "properties"], [65, "properties"], [66, "properties"], [67, "properties"], [68, "properties"], [69, "properties"], [70, "properties"], [72, "properties"], [73, "properties"], [74, "properties"], [75, "properties"], [77, "properties"], [79, "properties"], [80, "properties"], [82, "properties"], [85, "properties"], [87, "properties"], [88, "properties"], [90, "properties"], [91, "properties"], [92, "properties"], [93, "properties"], [96, "properties"], [97, "properties"], [99, "properties"], [100, "properties"], [101, "properties"], [102, "properties"], [103, "properties"], [104, "properties"], [106, "properties"], [107, "properties"], [108, "properties"], [109, "properties"], [110, "properties"], [112, "properties"], [113, "properties"], [114, "properties"], [115, "properties"], [116, "properties"], [117, "properties"], [118, "properties"], [119, "properties"], [120, "properties"], [121, "properties"], [122, "properties"], [123, "properties"], [124, "properties"], [125, "properties"], [126, "properties"], [127, "properties"], [128, "properties"], [129, "properties"], [130, "properties"], [131, "properties"], [132, "properties"], [133, "properties"], [134, "properties"], [135, "properties"], [136, "properties"], [137, "properties"], [138, "properties"], [139, "properties"], [140, "properties"]], "Provenance": [[39, "provenance"]], "Public diffraction data used for testing": [[0, "public-diffraction-data-used-for-testing"]], "Publications": [[34, null]], "Python client": [[31, "python-client"]], "QBinning": [[111, null]], "Quick start": [[38, "quick-start"]], "RHEL 9.5+ virtual memory flags": [[19, "rhel-9-5-virtual-memory-flags"]], "RHEL based systems": [[37, "rhel-based-systems"]], "Re-merging (--mode scale)": [[42, "re-merging-mode-scale"]], "Re-scaling and re-merging (rugnux --mode scale)": [[39, "re-scaling-and-re-merging-rugnux-mode-scale"]], "Reading the output": [[28, "reading-the-output"], [40, "reading-the-output"]], "Recommended deployment checklist": [[51, "recommended-deployment-checklist"]], "Reference": [[61, null]], "Reference data (-z)": [[39, "reference-data-z"]], "Reference data and the indexing ambiguity": [[39, "reference-data-and-the-indexing-ambiguity"]], "References": [[3, "references"], [8, "references"]], "Refinement": [[21, "refinement"], [47, "refinement"]], "Refinement (--mode refine)": [[42, "refinement-mode-refine"], [42, "id1"]], "Refinement (REFINE_*)": [[49, "refinement-refine"]], "Refining a model against structure factors (rugnux --mode refine)": [[47, "refining-a-model-against-structure-factors-rugnux-mode-refine"]], "Reflection-file conventions": [[46, "reflection-file-conventions"]], "Region-of-interest (ROI) integration": [[15, "region-of-interest-roi-integration"]], "Register map": [[20, "register-map"]], "Related pages": [[47, "related-pages"]], "Release contents": [[36, null]], "Remote displays": [[26, "remote-displays"]], "Report the hardware and the conditions": [[40, "report-the-hardware-and-the-conditions"]], "Reprocessing output: _process.h5": [[23, "reprocessing-output-prefix-process-h5"]], "Republish": [[27, "republish"]], "Requirements.": [[62, "requirements"]], "Return type": [[71, "return-type"], [71, "id3"], [71, "id9"], [71, "id15"], [71, "id21"], [71, "id27"], [71, "id33"], [71, "id39"], [71, "id45"], [71, "id51"], [71, "id57"], [71, "id63"], [71, "id69"], [71, "id75"], [71, "id81"], [71, "id87"], [71, "id93"], [71, "id99"], [71, "id105"], [71, "id111"], [71, "id117"], [71, "id123"], [71, "id129"], [71, "id135"], [71, "id141"], [71, "id147"], [71, "id153"], [71, "id159"], [71, "id165"], [71, "id171"], [71, "id177"], [71, "id183"], [71, "id189"], [71, "id195"], [71, "id201"], [71, "id207"], [71, "id213"], [71, "id219"], [71, "id225"], [71, "id231"], [71, "id237"], [71, "id243"], [71, "id249"], [71, "id255"], [71, "id261"], [71, "id267"], [71, "id273"], [71, "id279"], [71, "id285"], [71, "id291"], [71, "id297"], [71, "id303"], [71, "id309"], [71, "id315"], [71, "id321"], [71, "id327"], [71, "id333"], [71, "id339"], [71, "id345"], [71, "id351"], [71, "id357"], [71, "id363"], [71, "id369"], [71, "id375"], [71, "id381"], [71, "id387"], [71, "id393"], [71, "id399"], [71, "id405"], [71, "id411"], [71, "id417"], [71, "id423"], [71, "id429"]], "RoiAzimList": [[112, null]], "RoiAzimuthal": [[113, null]], "RoiBox": [[114, null]], "RoiBoxList": [[115, null]], "RoiCircle": [[116, null]], "RoiCircleList": [[117, null]], "RoiDefinitions": [[118, null]], "Rotation data": [[38, "rotation-data"], [50, "rotation-data"]], "Rotation data (--mode mx, the default)": [[42, "rotation-data-mode-mx-the-default"]], "RotationAxis": [[119, null]], "Rows where our reduction and the deposition disagree": [[12, "rows-where-our-reduction-and-the-deposition-disagree"]], "Rugnux": [[30, "rugnux"], [34, "rugnux"], [38, null], [57, "rugnux"], [61, null]], "Rugnux live mode": [[25, "rugnux-live-mode"]], "Rugnux with other programs": [[46, null]], "RugnuxLiveBlob": [[120, null]], "RugnuxLiveFrameRange": [[121, null]], "RugnuxLiveModel": [[122, null]], "RugnuxLiveRefinement": [[123, null]], "RugnuxLiveShell": [[124, null]], "RugnuxLiveStatus": [[125, null]], "RugnuxLiveStep": [[126, null]], "RugnuxLiveStills": [[127, null]], "RugnuxSettings": [[128, null]], "RugnuxStatus": [[129, null]], "RugnuxSummaryRow": [[130, null]], "RugnuxTriageItem": [[131, null]], "Rules": [[40, "rules"]], "Run tests": [[25, "run-tests"]], "Running Jungfraujoch software": [[9, "running-jungfraujoch-software"]], "Running Rugnux": [[50, null]], "Running directory": [[27, "running-directory"]], "Running each mode": [[42, "running-each-mode"]], "Running it": [[40, "running-it"]], "Runtime libraries and SDKs (shipped in binaries, not in the source tree)": [[56, "runtime-libraries-and-sdks-shipped-in-binaries-not-in-the-source-tree"]], "SNR ratio calculation": [[15, "snr-ratio-calculation"]], "Scaling and merging": [[0, "scaling-and-merging"], [42, "scaling-and-merging"]], "Scaling and merging (rotation)": [[21, "scaling-and-merging-rotation"]], "ScanResult": [[132, null]], "ScanResultImagesInner": [[133, null]], "Security": [[51, null]], "Semantic versioning": [[58, null]], "Serial XFEL inputs": [[44, "serial-xfel-inputs"]], "Serial collections (experimental)": [[25, "serial-collections-experimental"]], "Serial data": [[0, "serial-data"]], "Serial stills": [[38, "serial-stills"]], "Serial stills (--mode mx)": [[42, "serial-stills-mode-mx"]], "Serial stills with a known cell, space group and a CrystFEL geometry file": [[38, "serial-stills-with-a-known-cell-space-group-and-a-crystfel-geometry-file"]], "Serial stills: the indexing ambiguity": [[47, "serial-stills-the-indexing-ambiguity"]], "Setting up a local test for Jungfraujoch": [[25, "setting-up-a-local-test-for-jungfraujoch"]], "Setting up a machine": [[40, "setting-up-a-machine"]], "Setuptools": [[62, "setuptools"]], "Several sweeps merged as one": [[49, "several-sweeps-merged-as-one"]], "Signed images": [[53, "signed-images"]], "Small-molecule data": [[50, "small-molecule-data"]], "Small-molecule structures with SHELXT and SHELXL": [[46, "small-molecule-structures-with-shelxt-and-shelxl"]], "Software and computing methods": [[0, "software-and-computing-methods"]], "Software dependencies": [[52, "software-dependencies"]], "Software requirements": [[52, null]], "Solvent, ions and unmodelled density": [[0, "solvent-ions-and-unmodelled-density"]], "Space group, twinning and pseudo-symmetry": [[0, "space-group-twinning-and-pseudo-symmetry"]], "Splitting image stream": [[24, "splitting-image-stream"]], "Spot finding": [[0, "spot-finding"], [15, "spot-finding"], [42, "spot-finding"]], "SpotFindingSettings": [[134, null]], "Square root compression": [[15, "square-root-compression"]], "StandardDetectorGeometry": [[135, null]], "Start message": [[1, "start-message"]], "Start service": [[25, "start-service"]], "Status and cancellation": [[27, "status-and-cancellation"]], "Still / serial data": [[50, "still-serial-data"]], "Structure refinement": [[0, "structure-refinement"]], "Supported detectors": [[10, null]], "Sweep quality, the disposition, and their vocabularies": [[49, "sweep-quality-the-disposition-and-their-vocabularies"]], "Switch configuration": [[18, "switch-configuration"]], "Synthesis": [[14, "synthesis"]], "Sysfs access": [[19, "sysfs-access"]], "TCP frame header (TcpFrameHeader)": [[24, "tcp-frame-header-tcpframeheader"]], "TCP/IP configuration": [[24, "tcp-ip-configuration"]], "TCP/IP image stream": [[24, "tcp-ip-image-stream"]], "TERMS AND CONDITIONS": [[29, "terms-and-conditions"]], "Taking the data onward": [[46, "taking-the-data-onward"]], "Taking timings that mean something": [[40, "taking-timings-that-mean-something"]], "TcpSettings": [[136, null]], "Technical reference": [[54, null]], "Terminal output": [[38, "terminal-output"]], "Testing, benchmarking and simulation": [[57, "testing-benchmarking-and-simulation"]], "Tests": [[55, null], [62, "tests"]], "The GPU lock": [[40, "the-gpu-lock"]], "The REFMAC model check": [[40, "the-refmac-model-check"]], "The anomalous difference map": [[49, "the-anomalous-difference-map"]], "The anomalous-peak-height arbiter": [[55, "the-anomalous-peak-height-arbiter"]], "The checks": [[40, "the-checks"]], "The collection in numbers": [[12, "the-collection-in-numbers"]], "The developer report": [[49, "the-developer-report"]], "The disposition column": [[49, "the-disposition-column"]], "The files we use": [[13, "the-files-we-use"]], "The headline keys": [[49, "the-headline-keys"]], "The indexing ambiguity": [[39, "the-indexing-ambiguity"]], "The like-for-like table": [[40, "the-like-for-like-table"]], "The limit that applies to all five symmetry rows": [[12, "the-limit-that-applies-to-all-five-symmetry-rows"]], "The merged mmCIF (.cif)": [[39, "the-merged-mmcif-prefix-cif"]], "The model and the space group": [[47, "the-model-and-the-space-group"]], "The numbers": [[40, "the-numbers"]], "The page cache": [[40, "the-page-cache"]], "The receiver of a run": [[25, "the-receiver-of-a-run"]], "The reference-range table": [[49, "the-reference-range-table"]], "The results report": [[49, null]], "The run directory": [[40, "the-run-directory"]], "The setting the files are written in": [[39, "the-setting-the-files-are-written-in"]], "The space group, and the Sohncke answer beside it": [[49, "the-space-group-and-the-sohncke-answer-beside-it"]], "The stills error model": [[49, "the-stills-error-model"]], "The summary, and what the run decided": [[49, "the-summary-and-what-the-run-decided"]], "The three analysis tools": [[38, "the-three-analysis-tools"]], "The timing benchmark": [[40, "the-timing-benchmark"]], "The twin hypothesis (TWIN_SUBGROUP_*)": [[49, "the-twin-hypothesis-twin-subgroup"]], "The unmerged export": [[46, "the-unmerged-export"]], "The validation battery": [[40, "the-validation-battery"]], "Third-party software notices": [[56, null]], "Threat model and scope": [[51, "threat-model-and-scope"]], "Tools": [[57, null]], "Transceivers": [[18, "transceivers"]], "Translational pseudo-symmetry": [[49, "translational-pseudo-symmetry"]], "Twinned and pseudo-symmetric datasets": [[12, "twinned-and-pseudo-symmetric-datasets"]], "Two complementary layouts: per-image spots vs. a reflection table": [[23, "two-complementary-layouts-per-image-spots-vs-a-reflection-table"]], "Two crystal forms (stills)": [[49, "two-crystal-forms-stills"]], "Two measurements, one runner": [[40, "two-measurements-one-runner"]], "Ubuntu based systems": [[37, "ubuntu-based-systems"]], "UnitCell": [[137, null]], "Usage": [[27, "usage"]], "User data": [[1, "user-data"]], "Validating against a model (rugnux --model)": [[39, "validating-against-a-model-rugnux-model"]], "Vendored directly in the repository": [[56, "vendored-directly-in-the-repository"]], "Verdicts": [[40, "verdicts"]], "Very large unit cells": [[45, "very-large-unit-cells"]], "Web frontend": [[60, null]], "What a machine needs": [[40, "what-a-machine-needs"]], "What a miniCBF header states about the mounting": [[11, "what-a-minicbf-header-states-about-the-mounting"]], "What a pixel coordinate means: (0, 0) is the centre of the first pixel": [[11, "what-a-pixel-coordinate-means-0-0-is-the-centre-of-the-first-pixel"]], "What is Romansh?": [[30, "what-is-romansh"]], "What it does": [[40, "what-it-does"]], "What it does to merged data": [[7, "what-it-does-to-merged-data"]], "What it writes": [[41, "what-it-writes"]], "What runs where": [[28, "what-runs-where"]], "What the software does NOT provide": [[51, "what-the-software-does-not-provide"]], "What to send back": [[40, "what-to-send-back"]], "What you can secure (and should)": [[51, "what-you-can-secure-and-should"]], "When Vivado is not present": [[14, "when-vivado-is-not-present"]], "When the overwrite conflict is reported": [[27, "when-the-overwrite-conflict-is-reported"]], "Where it fits among the three analysis tools": [[26, "where-it-fits-among-the-three-analysis-tools"]], "Where the values come from": [[12, "where-the-values-come-from"], [13, "where-the-values-come-from"]], "Which kernel DKMS builds for": [[19, "which-kernel-dkms-builds-for"]], "Which pixels are masked": [[53, "which-pixels-are-masked"]], "Why bit_depth_readout is the image depth": [[23, "why-bit-depth-readout-is-the-image-depth"]], "Why the medium is declared and not detected": [[7, "why-the-medium-is-declared-and-not-detected"]], "Windows": [[40, "windows"]], "Windows installer": [[36, "windows-installer"]], "With a model": [[38, "with-a-model"]], "Writer notification socket": [[24, "writer-notification-socket"]], "XDS": [[53, "xds"]], "Xilinx Vivado": [[14, "xilinx-vivado"]], "Zero-copy transmission": [[24, "zero-copy-transmission"]], "ZeroMQ configuration": [[24, "zeromq-configuration"]], "ZeroMQ image stream": [[24, "zeromq-image-stream"]], "ZeromqMetadataSettings": [[138, null]], "ZeromqPreviewSettings": [[139, null]], "ZeromqSettings": [[140, null]], "beam_center_x/beam_center_y is the PONI; direct_beam_x/direct_beam_y is the beam": [[23, "beam-center-x-beam-center-y-is-the-poni-direct-beam-x-direct-beam-y-is-the-beam"]], "bearerAuth": [[62, "bearerauth"]], "cancel_post": [[71, "cancel-post"]], "config_azim_int_get": [[71, "config-azim-int-get"]], "config_azim_int_put": [[71, "config-azim-int-put"]], "config_bragg_integration_get": [[71, "config-bragg-integration-get"]], "config_bragg_integration_put": [[71, "config-bragg-integration-put"]], "config_dark_mask_get": [[71, "config-dark-mask-get"]], "config_dark_mask_put": [[71, "config-dark-mask-put"]], "config_detector_get": [[71, "config-detector-get"]], "config_detector_put": [[71, "config-detector-put"]], "config_file_writer_get": [[71, "config-file-writer-get"]], "config_file_writer_put": [[71, "config-file-writer-put"]], "config_image_format_conversion_post": [[71, "config-image-format-conversion-post"]], "config_image_format_get": [[71, "config-image-format-get"]], "config_image_format_put": [[71, "config-image-format-put"]], "config_image_format_raw_post": [[71, "config-image-format-raw-post"]], "config_indexing_get": [[71, "config-indexing-get"]], "config_indexing_put": [[71, "config-indexing-put"]], "config_instrument_get": [[71, "config-instrument-get"]], "config_instrument_put": [[71, "config-instrument-put"]], "config_internal_generator_image_put": [[71, "config-internal-generator-image-put"]], "config_internal_generator_image_tiff_put": [[71, "config-internal-generator-image-tiff-put"]], "config_mask_get": [[71, "config-mask-get"]], "config_mask_tiff_get": [[71, "config-mask-tiff-get"]], "config_roi_get": [[71, "config-roi-get"]], "config_roi_put": [[71, "config-roi-put"]], "config_rugnux_get": [[71, "config-rugnux-get"]], "config_rugnux_model_delete": [[71, "config-rugnux-model-delete"]], "config_rugnux_model_put": [[71, "config-rugnux-model-put"]], "config_rugnux_put": [[71, "config-rugnux-put"]], "config_select_detector_get": [[71, "config-select-detector-get"]], "config_select_detector_put": [[71, "config-select-detector-put"]], "config_spot_finding_get": [[71, "config-spot-finding-get"]], "config_spot_finding_put": [[71, "config-spot-finding-put"]], "config_user_mask_get": [[71, "config-user-mask-get"]], "config_user_mask_put": [[71, "config-user-mask-put"]], "config_user_mask_tiff_get": [[71, "config-user-mask-tiff-get"]], "config_user_mask_tiff_put": [[71, "config-user-mask-tiff-put"]], "config_zeromq_metadata_get": [[71, "config-zeromq-metadata-get"]], "config_zeromq_metadata_put": [[71, "config-zeromq-metadata-put"]], "config_zeromq_preview_get": [[71, "config-zeromq-preview-get"]], "config_zeromq_preview_put": [[71, "config-zeromq-preview-put"]], "deactivate_post": [[71, "deactivate-post"]], "detector_status_get": [[71, "detector-status-get"]], "fpga_status_get": [[71, "fpga-status-get"]], "image_buffer_clear_post": [[71, "image-buffer-clear-post"]], "image_buffer_image_cbor_get": [[71, "image-buffer-image-cbor-get"]], "image_buffer_image_jpeg_get": [[71, "image-buffer-image-jpeg-get"]], "image_buffer_image_tiff_get": [[71, "image-buffer-image-tiff-get"]], "image_buffer_start_cbor_get": [[71, "image-buffer-start-cbor-get"]], "image_buffer_status_get": [[71, "image-buffer-status-get"]], "image_pusher_status_get": [[71, "image-pusher-status-get"]], "initialize_post": [[71, "initialize-post"]], "jfjoch-client": [[62, null]], "jfjoch_broker": [[25, null]], "jfjoch_client.DefaultApi": [[71, null]], "jfjoch_extract_hkl": [[57, "jfjoch-extract-hkl"]], "jfjoch_fpga_test": [[57, "jfjoch-fpga-test"]], "jfjoch_hdf5_test": [[57, "jfjoch-hdf5-test"]], "jfjoch_lite_perf_test": [[57, "jfjoch-lite-perf-test"]], "jfjoch_pcie_clear_net_counters": [[57, "jfjoch-pcie-clear-net-counters"]], "jfjoch_pcie_net_cfg": [[57, "jfjoch-pcie-net-cfg"]], "jfjoch_pcie_status": [[57, "jfjoch-pcie-status"]], "jfjoch_recompress": [[57, "jfjoch-recompress"]], "jfjoch_simplon_test": [[57, "jfjoch-simplon-test"]], "jfjoch_stills_gpu_replay": [[57, "jfjoch-stills-gpu-replay"]], "jfjoch_stream2_replay": [[57, "jfjoch-stream2-replay"]], "jfjoch_udp_simulator": [[57, "jfjoch-udp-simulator"]], "jfjoch_viewer": [[26, null]], "jfjoch_writer": [[27, null]], "live_events_get": [[71, "live-events-get"]], "macOS": [[36, "macos"], [40, "macos"]], "pedestal_post": [[71, "pedestal-post"]], "pip install": [[62, "pip-install"]], "preview_pedestal_tiff_get": [[71, "preview-pedestal-tiff-get"]], "preview_plot_bin_get": [[71, "preview-plot-bin-get"]], "preview_plot_get": [[71, "preview-plot-get"]], "pyFAI": [[53, "pyfai"]], "result_scan_get": [[71, "result-scan-get"]], "rugnux_clear_post": [[71, "rugnux-clear-post"]], "rugnux_map_ccp4_get": [[71, "rugnux-map-ccp4-get"]], "rugnux_model_cif_get": [[71, "rugnux-model-cif-get"]], "rugnux_refine_test": [[57, "rugnux-refine-test"]], "rugnux_status_get": [[71, "rugnux-status-get"]], "start_post": [[71, "start-post"]], "statistics_calibration_get": [[71, "statistics-calibration-get"]], "statistics_data_collection_get": [[71, "statistics-data-collection-get"]], "statistics_get": [[71, "statistics-get"]], "status_get": [[71, "status-get"]], "trigger_post": [[71, "trigger-post"]], "version_get": [[71, "version-get"]], "wait_till_done_post": [[71, "wait-till-done-post"]], "wait_until_running_post": [[71, "wait-until-running-post"]], "xfel_event_code_get": [[71, "xfel-event-code-get"]], "xfel_pulse_id_get": [[71, "xfel-pulse-id-get"]]}, "docnames": ["ACKNOWLEDGEMENT", "CBOR", "CHANGELOG", "CPU_DATA_ANALYSIS", "CPU_DATA_ANALYSIS_DECISIONS", "CPU_DATA_ANALYSIS_IMAGE", "CPU_DATA_ANALYSIS_INDEXING", "CPU_DATA_ANALYSIS_INTEGRATION", "CPU_DATA_ANALYSIS_REFINEMENT", "DEPLOYMENT", "DETECTORS", "DETECTOR_GEOMETRY", "EXTERNAL_TEST_DATA", "EXTERNAL_TEST_DATA_STILLS", "FPGA", "FPGA_DATA_ANALYSIS", "FPGA_DESIGN", "FPGA_LICENSE", "FPGA_NETWORK", "FPGA_PCIE_DRIVER", "FPGA_SETTINGS", "GPU_DATA_ANALYSIS", "HARDWARE", "HDF5", "IMAGE_STREAM", "JFJOCH_BROKER", "JFJOCH_VIEWER", "JFJOCH_WRITER", "JUNGFRAUJOCH", "LICENSE", "NAMING", "OPENAPI", "OPENAPI_SPECS", "PIXEL_MASK", "PUBLICATIONS", "PYTHON_CLIENT", "RELEASE_CONTENTS", "REPOSITORIES", "RUGNUX", "RUGNUX_ADVANCED", "RUGNUX_BENCHMARKING", "RUGNUX_CALIBRATION", "RUGNUX_CLI", "RUGNUX_DOWNLOAD", "RUGNUX_FORMATS", "RUGNUX_INSTALL", "RUGNUX_INTEGRATION", "RUGNUX_MODEL_AND_REFERENCE", "RUGNUX_OVERVIEW", "RUGNUX_REPORT", "RUGNUX_TUTORIAL", "SECURITY", "SOFTWARE", "SOFTWARE_INTEGRATION", "TECHNICAL", "TESTS", "THIRD_PARTY_NOTICES", "TOOLS", "VERSIONING", "VIEWER_DOWNLOAD", "WEB_FRONTEND", "documentation", "python_client/README", "python_client/docs/AzimIntSettings", "python_client/docs/BraggIntegrationSettings", "python_client/docs/BrokerStatus", "python_client/docs/CalibrationStatisticsInner", "python_client/docs/DarkMaskSettings", "python_client/docs/DatasetSettings", "python_client/docs/DatasetSettingsSmargon", "python_client/docs/DatasetSettingsXrayFluorescenceSpectrum", "python_client/docs/DefaultApi", "python_client/docs/Detector", "python_client/docs/DetectorList", "python_client/docs/DetectorListElement", "python_client/docs/DetectorModule", "python_client/docs/DetectorModuleDirection", "python_client/docs/DetectorModulePlacement", "python_client/docs/DetectorPowerState", "python_client/docs/DetectorSelection", "python_client/docs/DetectorSettings", "python_client/docs/DetectorState", "python_client/docs/DetectorStatus", "python_client/docs/DetectorTiming", "python_client/docs/DetectorType", "python_client/docs/ErrorMessage", "python_client/docs/FileWriterFormat", "python_client/docs/FileWriterSettings", "python_client/docs/FpgaStatusInner", "python_client/docs/GeomRefinementAlgorithm", "python_client/docs/GridScan", "python_client/docs/ImageBufferStatus", "python_client/docs/ImageFormatSettings", "python_client/docs/ImagePusherStatus", "python_client/docs/ImagePusherType", "python_client/docs/IndexingAlgorithm", "python_client/docs/IndexingSettings", "python_client/docs/InstrumentMetadata", "python_client/docs/IntegrationModel", "python_client/docs/JfjochSettings", "python_client/docs/JfjochStatistics", "python_client/docs/MeasurementStatistics", "python_client/docs/PcieDevicesInner", "python_client/docs/PixelMaskStatistics", "python_client/docs/Plot", "python_client/docs/PlotUnitX", "python_client/docs/Plots", "python_client/docs/PowderCalibrationFitSigma", "python_client/docs/PowderCalibrationOutput", "python_client/docs/PowderCalibrationQuality", "python_client/docs/PowderCalibrationSpotCheck", "python_client/docs/QBinning", "python_client/docs/RoiAzimList", "python_client/docs/RoiAzimuthal", "python_client/docs/RoiBox", "python_client/docs/RoiBoxList", "python_client/docs/RoiCircle", "python_client/docs/RoiCircleList", "python_client/docs/RoiDefinitions", "python_client/docs/RotationAxis", "python_client/docs/RugnuxLiveBlob", "python_client/docs/RugnuxLiveFrameRange", "python_client/docs/RugnuxLiveModel", "python_client/docs/RugnuxLiveRefinement", "python_client/docs/RugnuxLiveShell", "python_client/docs/RugnuxLiveStatus", "python_client/docs/RugnuxLiveStep", "python_client/docs/RugnuxLiveStills", "python_client/docs/RugnuxSettings", "python_client/docs/RugnuxStatus", "python_client/docs/RugnuxSummaryRow", "python_client/docs/RugnuxTriageItem", "python_client/docs/ScanResult", "python_client/docs/ScanResultImagesInner", "python_client/docs/SpotFindingSettings", "python_client/docs/StandardDetectorGeometry", "python_client/docs/TcpSettings", "python_client/docs/UnitCell", "python_client/docs/ZeromqMetadataSettings", "python_client/docs/ZeromqPreviewSettings", "python_client/docs/ZeromqSettings"], "envversion": {"sphinx": 64, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2}, "filenames": ["ACKNOWLEDGEMENT.md", "CBOR.md", "CHANGELOG.md", "CPU_DATA_ANALYSIS.md", "CPU_DATA_ANALYSIS_DECISIONS.md", "CPU_DATA_ANALYSIS_IMAGE.md", "CPU_DATA_ANALYSIS_INDEXING.md", "CPU_DATA_ANALYSIS_INTEGRATION.md", "CPU_DATA_ANALYSIS_REFINEMENT.md", "DEPLOYMENT.md", "DETECTORS.md", "DETECTOR_GEOMETRY.md", "EXTERNAL_TEST_DATA.md", "EXTERNAL_TEST_DATA_STILLS.md", "FPGA.md", "FPGA_DATA_ANALYSIS.md", "FPGA_DESIGN.md", "FPGA_LICENSE.md", "FPGA_NETWORK.md", "FPGA_PCIE_DRIVER.md", "FPGA_SETTINGS.md", "GPU_DATA_ANALYSIS.md", "HARDWARE.md", "HDF5.md", "IMAGE_STREAM.md", "JFJOCH_BROKER.md", "JFJOCH_VIEWER.md", "JFJOCH_WRITER.md", "JUNGFRAUJOCH.md", "LICENSE.md", "NAMING.md", "OPENAPI.md", "OPENAPI_SPECS.rst", "PIXEL_MASK.md", "PUBLICATIONS.md", "PYTHON_CLIENT.md", "RELEASE_CONTENTS.md", "REPOSITORIES.md", "RUGNUX.md", "RUGNUX_ADVANCED.md", "RUGNUX_BENCHMARKING.md", "RUGNUX_CALIBRATION.md", "RUGNUX_CLI.md", "RUGNUX_DOWNLOAD.md", "RUGNUX_FORMATS.md", "RUGNUX_INSTALL.md", "RUGNUX_INTEGRATION.md", "RUGNUX_MODEL_AND_REFERENCE.md", "RUGNUX_OVERVIEW.md", "RUGNUX_REPORT.md", "RUGNUX_TUTORIAL.md", "SECURITY.md", "SOFTWARE.md", "SOFTWARE_INTEGRATION.md", "TECHNICAL.md", "TESTS.md", "THIRD_PARTY_NOTICES.md", "TOOLS.md", "VERSIONING.md", "VIEWER_DOWNLOAD.md", "WEB_FRONTEND.md", "documentation.rst", "python_client/README.md", "python_client/docs/AzimIntSettings.md", "python_client/docs/BraggIntegrationSettings.md", "python_client/docs/BrokerStatus.md", "python_client/docs/CalibrationStatisticsInner.md", "python_client/docs/DarkMaskSettings.md", "python_client/docs/DatasetSettings.md", "python_client/docs/DatasetSettingsSmargon.md", "python_client/docs/DatasetSettingsXrayFluorescenceSpectrum.md", "python_client/docs/DefaultApi.md", "python_client/docs/Detector.md", "python_client/docs/DetectorList.md", "python_client/docs/DetectorListElement.md", "python_client/docs/DetectorModule.md", "python_client/docs/DetectorModuleDirection.md", "python_client/docs/DetectorModulePlacement.md", "python_client/docs/DetectorPowerState.md", "python_client/docs/DetectorSelection.md", "python_client/docs/DetectorSettings.md", "python_client/docs/DetectorState.md", "python_client/docs/DetectorStatus.md", "python_client/docs/DetectorTiming.md", "python_client/docs/DetectorType.md", "python_client/docs/ErrorMessage.md", "python_client/docs/FileWriterFormat.md", "python_client/docs/FileWriterSettings.md", "python_client/docs/FpgaStatusInner.md", "python_client/docs/GeomRefinementAlgorithm.md", "python_client/docs/GridScan.md", "python_client/docs/ImageBufferStatus.md", "python_client/docs/ImageFormatSettings.md", "python_client/docs/ImagePusherStatus.md", "python_client/docs/ImagePusherType.md", "python_client/docs/IndexingAlgorithm.md", "python_client/docs/IndexingSettings.md", "python_client/docs/InstrumentMetadata.md", "python_client/docs/IntegrationModel.md", "python_client/docs/JfjochSettings.md", "python_client/docs/JfjochStatistics.md", "python_client/docs/MeasurementStatistics.md", "python_client/docs/PcieDevicesInner.md", "python_client/docs/PixelMaskStatistics.md", "python_client/docs/Plot.md", "python_client/docs/PlotUnitX.md", "python_client/docs/Plots.md", "python_client/docs/PowderCalibrationFitSigma.md", "python_client/docs/PowderCalibrationOutput.md", "python_client/docs/PowderCalibrationQuality.md", "python_client/docs/PowderCalibrationSpotCheck.md", "python_client/docs/QBinning.md", "python_client/docs/RoiAzimList.md", "python_client/docs/RoiAzimuthal.md", "python_client/docs/RoiBox.md", "python_client/docs/RoiBoxList.md", "python_client/docs/RoiCircle.md", "python_client/docs/RoiCircleList.md", "python_client/docs/RoiDefinitions.md", "python_client/docs/RotationAxis.md", "python_client/docs/RugnuxLiveBlob.md", "python_client/docs/RugnuxLiveFrameRange.md", "python_client/docs/RugnuxLiveModel.md", "python_client/docs/RugnuxLiveRefinement.md", "python_client/docs/RugnuxLiveShell.md", "python_client/docs/RugnuxLiveStatus.md", "python_client/docs/RugnuxLiveStep.md", "python_client/docs/RugnuxLiveStills.md", "python_client/docs/RugnuxSettings.md", "python_client/docs/RugnuxStatus.md", "python_client/docs/RugnuxSummaryRow.md", "python_client/docs/RugnuxTriageItem.md", "python_client/docs/ScanResult.md", "python_client/docs/ScanResultImagesInner.md", "python_client/docs/SpotFindingSettings.md", "python_client/docs/StandardDetectorGeometry.md", "python_client/docs/TcpSettings.md", "python_client/docs/UnitCell.md", "python_client/docs/ZeromqMetadataSettings.md", "python_client/docs/ZeromqPreviewSettings.md", "python_client/docs/ZeromqSettings.md"], "indexentries": {}, "objects": {}, "objnames": {}, "objtypes": {}, "terms": {"": [0, 1, 2, 3, 4, 5, 6, 8, 9, 11, 12, 13, 14, 17, 18, 21, 22, 23, 24, 25, 26, 28, 29, 30, 33, 34, 35, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 50, 51, 53, 55, 56, 57, 60, 61, 62, 68, 71, 75, 77, 107, 109, 110, 121, 122, 123, 124, 125, 131, 133, 134], "0": [0, 1, 3, 4, 6, 7, 8, 9, 10, 12, 13, 20, 21, 23, 24, 25, 26, 27, 29, 33, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 53, 54, 55, 56, 57, 59, 62, 63, 68, 69, 71, 72, 75, 77, 80, 86, 90, 96, 113, 119, 125, 128, 129, 133, 134, 136, 138, 139, 140], "00": [9, 12, 38, 46, 49, 55], "000": [5, 6, 13, 21, 25, 38, 40, 46, 50, 72], "0000": [9, 46, 49], "000000": [46, 49], "00013": 12, "0002": 44, "0004": 49, "000444": 49, "0005795": 12, "0006": 12, "00067": 46, "000976": 49, "001": [6, 8, 12, 25, 47, 49], "0019": 0, "00191": 12, "002": [25, 49], "0022": 0, "00224": 46, "00227": 12, "00250": 46, "003": 7, "0031": 49, "00338": 12, "00383": 12, "004": [5, 6, 8], "00565": 0, "006": [8, 13, 47], "007": [0, 12], "008": 6, "009": 7, "00l": 4, "01": [0, 2, 4, 5, 6, 7, 8, 12, 13, 25, 38, 40, 41, 42, 49, 53, 63], "010": 12, "0101": 12, "0102578": 12, "0107": 46, "0110": 49, "012": 12, "014": 0, "0140": 9, "0142": 9, "014305": 34, "015": [4, 7, 49], "017": 49, "018": 12, "0196": 7, "01g": 7, "02": [6, 7, 8, 12, 25, 36, 38, 42, 47, 49], "0201": 12, "021": 0, "023": 12, "024": 6, "025": [6, 12], "03": [5, 7, 8, 12, 46, 47, 49, 134], "0300": 49, "03214a": 12, "03329": 12, "0350503": 0, "037": [0, 13], "03819": 0, "04": [7, 8, 9, 12, 28, 36, 37, 40, 43, 45, 52], "042": 44, "04200": 0, "0425": 12, "0431": [12, 40], "0481": 49, "05": [5, 6, 7, 8, 12, 13, 27, 38, 40, 42, 49, 96], "0535": 7, "0572855": 0, "05a": 12, "06": [4, 6, 12, 13, 26, 36, 45, 46, 134], "062": 7, "064301": 0, "064422": 12, "066": 12, "068437": 0, "07": [4, 6, 8, 12, 13, 40, 47], "0710036": 0, "08": [4, 8, 12, 13, 36, 49, 55], "083": 13, "089": 7, "08940886": 0, "08b1": 12, "08id": 12, "09": [12, 21], "095": 49, "096": 12, "097": 12, "0e16": 12, "0k0": 4, "0k7b68": 12, "0x000000": 20, "0x00ffff": 20, "0x010000": 20, "0x010004": 20, "0x010008": 20, "0x01000c": 20, "0x010010": 20, "0x010014": 20, "0x010018": 20, "0x01001c": 20, "0x010020": 20, "0x010024": 20, "0x010028": 20, "0x010030": 20, "0x010038": 20, "0x01003c": 20, "0x010040": 20, "0x010048": 20, "0x010050": 20, "0x010058": 20, "0x010060": 20, "0x010068": 20, "0x010070": 20, "0x010078": 20, "0x010080": 20, "0x010088": 20, "0x010090": 20, "0x010100": 20, "0x010104": 20, "0x010200": 20, "0x010208": 20, "0x01020c": 20, "0x010210": 20, "0x010214": 20, "0x010218": 20, "0x01021c": 20, "0x010220": 20, "0x010224": 20, "0x010228": 20, "0x01022c": 20, "0x030000": 20, "0x03ffff": 20, "0x040000": 20, "0x04ffff": 20, "0x050000": 20, "0x05ffff": 20, "0x060000": 20, "0x06ffff": 20, "0x070000": 20, "0x07ffff": 20, "0x080000": 20, "0x08ffff": 20, "0x090000": 20, "0x09ffff": 20, "0x0a0000": 20, "0x0affff": 20, "0x0c0000": 20, "0x0fffff": 20, "0x100000": 20, "0x10ffff": 20, "0x110000": 20, "0x11ffff": 20, "0x120000": 20, "0x12ffff": 20, "0x130000": 20, "0x13ffff": 20, "0x140000": 20, "0x14ffff": 20, "0x150000": 20, "0x15ffff": 20, "0x160000": 20, "0x16ffff": 20, "0x170000": 20, "0x17ffff": 20, "0x1f06000": 9, "0x200000": 20, "0x20ffff": 20, "0x210000": 20, "0x21ffff": 20, "0x220000": 20, "0x22ffff": 20, "0x230000": 20, "0x23ffff": 20, "0x240000": 20, "0x24ffff": 20, "0x250000": 20, "0x25ffff": 20, "0x260000": 20, "0x26ffff": 20, "0x270000": 20, "0x27ffff": 20, "0x400000": 20, "0x47ffff": 20, "0x4a464a54": 24, "0xfeff": 44, "0\u03c3": 4, "1": [0, 1, 3, 9, 11, 12, 13, 15, 17, 20, 21, 22, 24, 25, 26, 27, 29, 33, 34, 36, 38, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50, 53, 55, 56, 57, 59, 62, 63, 67, 68, 69, 71, 72, 75, 77, 80, 92, 107, 125, 133, 134, 135, 139], "10": [0, 2, 3, 5, 6, 12, 13, 17, 18, 20, 21, 22, 24, 25, 26, 27, 28, 29, 33, 34, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 53, 55, 56, 67, 71, 96], "100": [0, 3, 4, 5, 7, 8, 10, 12, 14, 18, 22, 24, 25, 27, 36, 42, 44, 46, 47, 49, 50, 71, 92, 134, 140], "1000": [2, 7, 25, 27, 42, 49, 53, 67, 68, 101, 138, 139], "10000": 67, "100000": 42, "1001": 12, "1002": 0, "1004": [0, 3, 8], "1006": 0, "1007": 0, "10078356x": 0, "100g": [14, 18, 20, 22], "101": [0, 3, 8, 12, 49], "1016": 0, "1017": 0, "102": [12, 49], "10201899": 12, "1021": [0, 3, 12], "1022": 44, "10222807": 12, "1023": 44, "1024": [6, 8, 13, 15, 19, 25], "1024x512": [19, 71], "1028": [0, 3], "103": [12, 13], "1030": [0, 3], "1033": [0, 3], "1036": [0, 3], "1036416": 12, "1038": [0, 12], "104": [5, 12], "1040": [0, 3, 12], "105": [7, 12, 38], "1059413": 12, "106": [12, 38, 50], "1063": [0, 34], "107": [0, 12], "1073": 0, "108": [12, 55], "1080": 0, "10882": 0, "109": [0, 3, 12], "1090": 0, "1091": 46, "1093": 0, "1096": 0, "10g": [14, 20, 22], "10m": 9, "10\u03c3": 4, "11": [2, 4, 5, 6, 12, 17, 20, 26, 29, 33, 36, 38, 40, 43, 46, 49, 50, 52, 53, 55, 59], "110": 12, "1100": 12, "1101": 12, "1102": 12, "1103": 12, "1104": [0, 8], "1107": [0, 12, 28, 34, 49], "1109": 0, "111": [0, 12, 13, 40, 46], "1110": 0, "1114": [0, 8], "1118": [0, 3], "112": [0, 12], "1124": [0, 3, 12], "1126": 0, "113": 12, "1130": [0, 3], "1131": [0, 3], "1132": [0, 3, 8], "1137": [0, 46], "114": [0, 3, 12, 55], "11405662": 12, "1141": [0, 3, 8], "1142": 12, "1145": [0, 3], "1147": [0, 8], "11472085": 12, "1148": 12, "115": [0, 3, 4, 8, 12], "1151": 12, "1153": [0, 3], "11577": 13, "1158": [0, 8], "116": 12, "1167": [0, 8], "117": 12, "1176344552": 0, "1177703732": 0, "1177729694": 0, "118": [0, 3, 12], "1181": 0, "1186": 0, "119": [0, 12], "1193": 0, "1194": 12, "11946282": 12, "11c": 12, "11if": 12, "12": [0, 2, 3, 4, 5, 12, 13, 17, 20, 21, 26, 36, 37, 38, 40, 43, 45, 46, 49, 50, 52, 54, 55, 56, 59, 120], "120": [6, 7, 12, 14, 36, 38, 42, 48, 49, 50], "1200": [6, 12, 27, 42, 45], "1204": [0, 3], "1208": 12, "121": [0, 3, 12, 36], "1214": [0, 3], "1215": 0, "1217": 0, "1218231": 0, "122": [0, 8, 12], "1222": 0, "123": 12, "1230": 0, "1237": 12, "1239": 12, "124": [0, 3, 4, 12], "12400": [25, 27], "125": [0, 3, 4, 12, 26, 49], "126": [0, 12], "1260": 12, "1261": 0, "127": [12, 24], "128": [8, 13, 21, 25, 80], "1285": [0, 3], "1286854": 12, "1287": [0, 3], "12jfjoch_view": 59, "12rugnux": 43, "13": [2, 3, 6, 7, 12, 17, 20, 21, 26, 29, 36, 37, 42, 43, 45, 47, 48, 52, 54, 55, 59], "130": [0, 3, 4, 12], "1303": [0, 3], "131": 12, "1310": 0, "1314": [0, 3], "132": [0, 3, 12, 49], "1325": 0, "133": [0, 3, 7, 8, 12], "134": 12, "1346": [0, 8], "135": [0, 3, 4, 12, 24, 49], "1356": [0, 8], "136": [12, 13], "13643701": 12, "137": [12, 39, 45], "1373": [0, 3], "138": 12, "1382": [0, 3], "1387": [0, 3, 8], "139": 12, "13912326": 12, "1392": [0, 3, 8], "13jfjoch": 59, "13rugnux": 43, "14": [0, 2, 3, 5, 7, 8, 12, 13, 19, 20, 21, 22, 38, 39, 40, 42, 45, 47, 48, 52, 54], "140": [0, 3, 8, 12], "1400905": 0, "14070468": 12, "141": 12, "142": 12, "1420": 15, "14264": 12, "1428": 15, "143": 12, "14300": 46, "1437": [0, 7], "1439": 12, "144": [0, 3], "1440": [12, 13], "14464": 38, "1448": [0, 7], "145": 12, "14555180": 12, "1459": 0, "146": 12, "1464102": 13, "1465": 0, "147": 12, "1475": 45, "148": [6, 12], "14844040": 12, "14876": 12, "14894181": 12, "149": [0, 3, 8], "14901515": 12, "1494374": 12, "15": [0, 2, 3, 4, 5, 6, 7, 12, 15, 20, 21, 24, 26, 29, 38, 40, 42, 47, 48, 49, 50, 54], "150": [4, 5, 6, 7, 12, 25, 26, 49], "1500": 27, "15000": 24, "15005358": 12, "1502065": 13, "151": 13, "1511590": 13, "15151": 12, "152": [12, 13], "153": 12, "15432050": 12, "155": [12, 27], "156": [12, 13], "1561": [0, 3], "15615368": 12, "1563": [0, 3], "1564": 49, "157": [0, 3, 12], "1571": 49, "1577465": 12, "15785": [12, 40], "158": 12, "159": [0, 3, 13], "16": [2, 4, 5, 7, 8, 12, 13, 15, 19, 20, 21, 23, 25, 29, 38, 40, 42, 43, 44, 45, 50, 53, 55, 56, 71, 80], "160": [0, 3, 7, 25, 42], "1608119": 0, "163": [0, 3, 12], "1633": 0, "16384": [6, 96], "164": 12, "165": [12, 13], "1650020": 13, "166": 12, "1660970": 13, "1663": 49, "1668": [0, 28, 34], "167": [12, 40], "1674": 12, "1675": 12, "1677": [0, 28, 34], "1679": 45, "168": [12, 13, 24], "16847": 38, "169": 12, "1690": [0, 3], "1695": [0, 3], "1699": 49, "16gt": 9, "16m": [2, 12, 13, 22, 40], "16m_mask": 13, "17": [0, 3, 7, 8, 12, 13, 20, 38, 45, 50, 56], "170": [0, 5, 8, 12], "17003933": 13, "1701640114": 0, "1702": 49, "1703": 0, "171": 12, "1710b": 12, "1715": [0, 3], "1717": 0, "1718": 0, "172": 13, "1725": 0, "17298261": 12, "173": [0, 8, 46], "1735": [0, 3], "1740": 49, "175": [0, 8, 12, 49], "176": [0, 3], "177": [0, 3, 13], "1789": 12, "1792": 12, "18": [0, 4, 5, 7, 8, 12, 13, 20, 21, 38, 39, 42, 45, 46, 49, 55], "180": [0, 3, 4, 11, 12, 49], "1800": [12, 38, 45], "181": [12, 23], "18150": 12, "182": [12, 49], "183": [0, 3, 5, 38, 50], "184": [0, 3, 38, 45], "18430": [12, 40], "18434": 0, "1848199439": 12, "185": 12, "186": [43, 59, 62], "1861": 12, "1865": [0, 3], "18652652": [12, 38, 40], "187": 12, "1871": [0, 3, 12], "188": 12, "189": 12, "19": [0, 4, 7, 8, 12, 20, 38, 40, 47, 49, 50], "190": 49, "1900": 12, "1900353437": 12, "191": [7, 12], "1912": 0, "1915": [0, 3], "192": [0, 8, 12, 21, 24], "1920": 13, "1921": 0, "1923": [0, 3], "1926": 0, "193": 13, "1931": 12, "1938": [0, 3], "19456697": 12, "1949": [0, 3], "1950": [0, 3], "1951": 0, "1952": [0, 1, 3], "1964": [0, 3, 8], "1965": [0, 3], "1967": [0, 3, 4], "1968": [0, 3, 4, 8], "197": [0, 8], "1971": 0, "1973": [0, 3, 4], "1974": [0, 3], "1975": [0, 3, 4], "1976": [0, 3, 8], "1978": [0, 3, 8], "1979": 0, "198": 13, "1980": [0, 3, 8], "1981": [0, 8], "1982": [0, 3, 5], "1985": [0, 8], "1986": [0, 3, 6, 8], "1987": [0, 3], "1989": [0, 3, 8], "199": [0, 3, 12, 13], "1990": [0, 8], "1991": [0, 8], "1992": [0, 3, 4, 8], "1993": [0, 3, 12], "1994": [0, 3, 4, 5, 8], "1995": [0, 3, 8], "1996": [0, 3, 8, 29], "19960715": 0, "1997": [0, 3, 6, 8], "1998": [0, 8], "1999": [0, 3, 8], "1_": 40, "1a": 12, "1abc": [39, 47], "1ad": 12, "1b": [42, 49], "1d": [0, 3, 6, 16, 62, 63, 71], "1e": 2, "1g": 22, "1hqgwo": 12, "1m": [9, 12, 13, 21, 25], "1ma": [8, 47], "1pe": [8, 47], "1st": 132, "1tel": 12, "1x": 51, "2": [0, 1, 2, 3, 9, 10, 11, 12, 13, 14, 19, 20, 21, 22, 24, 25, 26, 29, 34, 36, 37, 38, 39, 40, 42, 43, 45, 46, 47, 48, 50, 53, 55, 56, 69, 71, 96, 124, 125, 133], "20": [0, 2, 3, 4, 6, 7, 8, 12, 20, 29, 44, 45, 46, 47, 49, 52, 55, 62, 72, 96], "200": [2, 4, 5, 6, 7, 12, 13, 25, 40, 42, 46, 50, 51, 71], "2000": [0, 4, 5, 7, 25, 44, 49, 80], "20000": [2, 49, 68], "200000": 9, "2001": [0, 3, 4, 8, 12, 49], "2001311": 12, "2002": [0, 3, 8], "2003": [0, 3, 4], "2004": [0, 3, 8], "20041091": 12, "2005": [0, 3, 4, 7, 8], "2006": [0, 3, 8], "2007": [0, 3, 4, 8, 29], "2008": 0, "2009": 0, "200g": 22, "200k": 9, "201": 12, "2010": [0, 3, 7, 8, 12, 49], "2011": [0, 3, 4, 8, 36], "2012": [0, 3, 8, 23, 49], "2012031": 12, "2013": [0, 3, 4, 12, 36], "20135265": 12, "2014": [0, 3, 7, 8], "2015": [0, 2, 3, 8], "2016": [0, 3, 23, 46], "2017": [0, 3, 4, 8, 12, 36], "2018": [0, 3, 12, 13], "2019": [0, 3, 8, 13], "2020": [0, 3, 12, 13, 15, 17, 34], "2021": [0, 3, 5], "2022": [0, 2, 3, 4, 8, 12, 14, 15], "2022nov": 13, "2023": [0, 12, 13, 28, 34], "2024": [0, 2, 3, 6, 13, 34, 53], "2025": [0, 8, 12], "20250127": 56, "2026": [0, 8, 13, 26, 28, 34, 36, 38, 40, 52, 55], "203": 12, "204": 12, "2048": [2, 15, 25, 27, 99], "205": 12, "206": [4, 12], "2068": [27, 33], "207": 12, "2078": 49, "208": 12, "209": 4, "21": [4, 8, 12, 13, 20, 23, 38, 39, 40, 46, 50], "210": [0, 3], "2108029": 12, "210r": 12, "211": 12, "2110": 0, "21105": 0, "2112": 6, "212": 12, "21252": 12, "2126": 0, "2127908021": 12, "213": [6, 13], "214": [0, 3, 12], "21439": 0, "216": 12, "2164": [27, 33], "2184": [0, 3, 8], "219": [12, 50], "2195": [0, 3, 8], "21r": 12, "22": [0, 3, 6, 8, 9, 12, 20, 28, 36, 37, 38, 40, 43, 45, 46, 50, 52], "220": 13, "2204603": 13, "221": 13, "222": [4, 12, 13, 41], "223": [0, 8], "2233": 49, "224": [0, 12], "225": 12, "226": 12, "227": [0, 12, 28, 34], "22822": 0, "2282689": 13, "229e": 12, "22x": 55, "23": [0, 2, 3, 6, 8, 9, 12, 13, 38, 50], "230": [2, 4, 40], "2307": 0, "2311261": 12, "233": [0, 8], "2331838": 0, "234": [0, 28, 34], "235": [0, 3, 12], "236": 13, "237": 13, "239": [0, 8], "24": [0, 4, 9, 12, 13, 21, 28, 34, 36, 37, 38, 42, 43, 45, 46, 49, 50, 52], "240": [0, 3, 8, 12], "242": [0, 3, 12, 13], "243": [0, 3, 8, 13], "2430": 0, "244": [0, 8], "2443": 0, "245": [0, 3], "2463": 45, "247": [0, 8], "248": 49, "249": [12, 49], "25": [0, 4, 5, 6, 7, 8, 12, 13, 21, 27, 40, 45, 49], "250": [7, 12, 24, 27, 49, 68, 96], "2505": 0, "251": 13, "2527": 45, "2532134": 12, "254": 13, "25495": 0, "255": [0, 3, 8, 12], "256": [2, 13, 15, 16, 25, 36, 68], "259": [0, 12], "25g": 14, "25z": 8, "26": [0, 3, 5, 6, 7, 8, 12, 21, 38, 40, 42, 49, 52], "260": 12, "2622": 80, "2635": 12, "265": [0, 3, 12, 49], "2660193": 0, "2660195": 0, "267": [0, 8, 13], "268": [0, 8, 45], "269": [0, 3, 12], "27": [6, 7, 12, 20, 53, 55], "270": [0, 8, 13], "2700": 12, "2707": 50, "271": [0, 38], "273k": 12, "275": [0, 3], "276": [0, 3, 8, 12, 13], "2779": 12, "278": 13, "2799216": 0, "28": [0, 3, 7, 12, 13, 29, 38, 46], "281": [0, 13], "282": [0, 3, 8], "2836": 0, "286": [0, 13], "289": 12, "29": [0, 5, 6, 12, 15, 29, 46, 49], "292": [0, 3, 12, 13], "293": [0, 3, 12], "293k": 12, "2943248": 12, "295": 13, "296": 12, "2967": 50, "297": [0, 3, 38], "298": [0, 3, 8, 12], "2999572": 13, "2_": 7, "2_1": [2, 4], "2_r": 7, "2_t": 7, "2a": 6, "2c": [7, 8, 12], "2d": [0, 2, 3, 4, 5, 6, 15, 26], "2f": 5, "2f8": [46, 50], "2f_o": [4, 8], "2f_od": 8, "2fo": 2, "2fofc": 71, "2fofcwt_no_fil": 4, "2m": [6, 12], "2mf": 12, "2mf_o": [4, 8], "2mfo": [0, 2, 3, 8, 25, 38, 39, 47, 50, 71, 122], "2mg": [8, 47], "2n": 4, "2nd": 132, "2nw": 46, "2r_": 7, "2r_3": 7, "2rg": 12, "2sum": 0, "2theta": [2, 12], "2w": 5, "2wnn": 12, "2wnq": 12, "2wnz": 12, "2xfw": 12, "2\u03b1": 0, "2\u03b8": [11, 12, 23, 44, 49], "2\u03c0": [42, 49], "2\u03c3": 4, "3": [0, 1, 2, 3, 9, 12, 13, 17, 19, 20, 21, 22, 24, 25, 26, 29, 30, 36, 38, 39, 40, 41, 42, 45, 46, 47, 48, 49, 50, 52, 53, 54, 55, 56, 62, 67, 71, 72, 109, 120, 123], "30": [0, 3, 4, 5, 6, 7, 8, 12, 13, 14, 17, 24, 28, 29, 33, 34, 38, 40, 42, 49, 50, 53, 55], "300": [8, 12, 21, 25, 33, 41, 80], "3000": [5, 25, 42], "300k": 12, "3014306": 13, "301_helical_1": 12, "302": [0, 3], "305": 6, "307": [0, 3], "3072": 12, "31": [0, 3, 4, 5, 8, 12, 20, 33, 44, 49, 53], "310": 6, "3108": 45, "311": [0, 3, 8, 49], "312": 12, "315": 12, "316": 0, "318": [0, 3], "31c1ad3": 56, "31jt": 13, "31k": 21, "31mer": 12, "32": [0, 4, 5, 6, 7, 12, 13, 15, 19, 20, 21, 23, 26, 33, 40, 41, 42, 43, 45, 46, 49, 50, 53, 62, 71, 80, 136], "320": [0, 3, 12, 25, 72], "32004": 44, "32008": 5, "321": [0, 3, 4, 12], "321296": 0, "321305": 0, "324": 12, "324th": 7, "325": 0, "326": [0, 3], "3262": 45, "32766": 27, "32767": [27, 44], "32768": [23, 53], "328": 12, "329": 12, "32962": 12, "3299": 0, "32x32": 2, "33": [0, 3, 4, 8, 12, 13, 40, 47], "330": [0, 3], "3309": 0, "333": [4, 46], "334": 12, "335": 0, "33555": 12, "336": [0, 3], "337": [0, 3, 38], "3374214": 13, "3386": 12, "34": [0, 3, 12, 38], "341": 0, "344": [0, 3, 8, 12], "3450": 9, "35": [0, 3, 7, 8, 12, 13, 38, 40, 49], "350": 49, "352": [0, 3, 8], "355": [0, 3, 7, 8], "355472a0": 0, "356": [0, 3, 12], "357": 12, "3571040": 12, "358": [0, 3, 8], "36": [4, 7, 12, 38, 49, 135], "360": [2, 12], "3600": [12, 38], "363": [38, 50], "3631": [0, 3], "3636": [0, 3], "3637": [0, 3], "3641": [0, 3], "367": [0, 3, 8], "369": [0, 3, 12], "36gk": 12, "37": [0, 8, 12, 13, 40, 46], "3730956": 12, "374": 12, "375": [4, 46, 49], "38": [0, 3, 4, 12, 28, 34, 38, 42, 46, 50], "383": [0, 3], "385": [0, 3], "3873216": 12, "3874714": 12, "388": 13, "39": [0, 6, 7, 8, 12, 27, 36, 43, 45, 46], "390": 12, "394": 12, "395": [0, 3], "399": [0, 3], "3c": 12, "3d": [0, 2, 4, 42, 45, 46, 49, 50, 132], "3i4": [46, 50], "3inp": 12, "3ky7": 12, "3l_": 6, "3m1": 12, "3mc4": 12, "3meb": 12, "3p85": 12, "3r6o": 12, "3rd": 132, "3tel": 12, "3x": 49, "3x3": 1, "3\u03c3": [4, 47, 49], "4": [0, 1, 2, 3, 9, 12, 13, 17, 19, 20, 21, 22, 24, 25, 26, 29, 33, 36, 38, 40, 42, 45, 46, 47, 48, 49, 50, 51, 53, 54, 55, 56, 68, 71, 86, 88, 123, 128], "40": [0, 3, 4, 5, 6, 7, 12, 14, 18, 26, 42, 49], "400": [25, 33, 44, 45, 68, 71], "4000": 49, "401": [0, 3, 8, 25, 51, 68, 71], "402": 12, "4020": 0, "403": 12, "404": [0, 6, 8, 71], "405": 0, "408": 7, "409": [25, 71], "4096": [12, 21], "41": [0, 3, 12, 46], "410": [0, 12], "411": [0, 3, 8], "412": 49, "413": [0, 3, 25, 71], "4150": 45, "417": [0, 8], "418": [0, 3, 49], "42": [0, 4, 6, 12, 40, 47, 49], "4200": [0, 3, 8], "422": [4, 12], "424": [0, 3], "425": 13, "426": 12, "428": 13, "42d": [4, 49], "42mer": 12, "43": [0, 6, 7, 12, 13, 23, 36, 46, 49], "430": [13, 40], "4300323": 12, "431": 9, "432": [0, 3, 4], "4356": 25, "4357": 25, "4371": 45, "439": [0, 8], "44": [0, 3, 4, 6, 8, 12, 49], "441": 0, "442": 12, "443": [0, 8], "444": 0, "445": 13, "446": 12, "447": 49, "448": [0, 8], "449": [0, 8], "45": [0, 3, 6, 7, 8, 12, 14, 40, 45], "450": [0, 8, 25], "451": [0, 8, 12], "4510614": 12, "4510615": 12, "453": 0, "454": 30, "458": [0, 3], "46": [4, 7, 12, 13], "461": 0, "463": 12, "464": [0, 3], "465": 38, "466": 30, "46667": 46, "468": [0, 8], "4686876": 12, "47": [0, 3, 12, 13], "470": 4, "472": [0, 3, 8, 12], "475": [0, 3, 8, 12], "477": [0, 8], "478": [0, 3], "48": [0, 7, 12, 13, 21], "480": [0, 3], "481": 0, "4826": 5, "486": [0, 3, 8], "488": 12, "49": [0, 3, 8, 12, 13, 49], "491": [0, 3], "492": 12, "497": [0, 3], "49859": 12, "4a": 12, "4abw": 46, "4bwl": 12, "4chrd": 12, "4d": [4, 7], "4dc8": 56, "4f": [5, 6], "4m": [12, 13, 22, 27, 34], "4mtk": 12, "4nwv": [0, 12, 40, 45, 56], "4nwv_trace": 40, "4p8r": 12, "4x": [49, 55], "4x10": [14, 18], "4x10g": 22, "4\u03c3": [4, 49], "5": [0, 1, 2, 3, 11, 12, 13, 17, 18, 20, 21, 22, 24, 25, 26, 29, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 53, 55, 56, 67, 71, 96, 133, 134], "50": [0, 3, 4, 5, 6, 7, 8, 12, 13, 21, 25, 27, 40, 42, 45, 46, 49, 55, 123, 125], "500": [2, 4, 6, 7, 8, 12, 21, 25, 27, 40, 42, 46, 47, 49, 71, 80], "5000": [25, 80], "5001": 25, "500m": [2, 24], "501": [0, 3, 8], "502": 71, "503": [0, 3, 8], "504": 71, "507": [0, 3], "5080": [21, 38, 50], "51": [0, 3, 4, 7, 12, 39, 47, 49], "51093": 12, "510k": 21, "511": 42, "512": [5, 13, 19, 22, 36, 42], "5128672": 0, "512x1024": 1, "5143480": 34, "517": [0, 3], "51k": 21, "52": [0, 12, 13, 38, 39, 40, 49], "521": [0, 3], "522": [0, 3, 5, 6], "5232": [9, 25, 35, 41, 42, 62, 71], "5233": 9, "525": [0, 3, 26, 36, 43, 45, 59], "528": [0, 3, 8, 13], "5281": [12, 40], "53": [0, 4, 8, 13, 15], "5324": 12, "5325": 12, "534": 13, "53494": 12, "535": 0, "537": 12, "54": [0, 6, 8, 12], "540": [0, 3, 5, 24], "5400": 27, "541": [4, 12], "54187": [2, 46], "544": [0, 3], "545": 12, "54568": 12, "546": 11, "547": [0, 3, 49], "54757": 12, "548": [0, 3], "55": [0, 5, 7, 8, 12, 40, 42, 49, 50, 72], "550": 4, "551": 49, "551699": 0, "554": [0, 3, 5], "557": [0, 49], "558": 0, "56": [12, 38, 50, 56, 71], "560": [0, 3], "5610030a": 9, "564": 12, "565": [0, 3, 50], "56500": 1, "568": 12, "569": [0, 3], "57": [0, 3, 12, 13, 34, 36, 38, 50], "570": 13, "5718": 0, "574": 15, "575": [0, 36], "57668": 46, "58": [4, 6, 7, 12, 44], "580": [26, 36, 45], "583": [0, 3], "5836055": 12, "586": [4, 15, 40], "5886687": 12, "589": [0, 3], "59": [0, 7, 12, 13, 28, 34, 49], "596": [0, 3], "5c": 12, "5cc8": 12, "5e": 27, "5ebi": 12, "5epe": 12, "5f6m": 12, "5j23": 12, "5jk4": 12, "5jvn": 12, "5ky6": 12, "5lyr": 12, "5lzl": 12, "5m": 22, "5m03": 12, "5m17": 12, "5m3w": 12, "5m5d": 12, "5mc": [8, 47], "5mc8": 12, "5mel": 12, "5mln": 12, "5mu": [8, 47], "5nw5": 12, "5ojv": 12, "5reo": [12, 40], "5src": 12, "5t39": 12, "5uth": 12, "5vml": 12, "5x": 55, "6": [0, 1, 2, 3, 12, 17, 19, 20, 21, 22, 24, 25, 26, 33, 36, 38, 40, 42, 43, 45, 46, 47, 48, 49, 50, 52, 55, 56, 59, 61], "60": [0, 4, 5, 6, 8, 12, 24, 25, 26, 29, 36, 38, 42, 43, 45, 48, 49, 59, 71, 125, 128], "600": [2, 7, 13, 42, 49], "6000": [0, 12], "60000": 24, "6000he": 12, "6006": 12, "602": 12, "605": 12, "606": 12, "6072": 12, "60884": [12, 40], "61": [0, 3, 8, 12, 13, 50], "610": 36, "612": 49, "614": 12, "61993": 46, "62": [4, 12, 38, 46, 49], "620": 12, "622": 4, "624933": 9, "63": [0, 3, 7, 8, 12, 13, 38], "630": 49, "6316": 0, "634": [0, 3], "6347466": 12, "636": [0, 3], "637": 12, "64": [6, 7, 8, 12, 19, 20, 24, 25, 26, 36, 38, 40, 43, 45, 50, 52, 59, 71, 99], "640": 0, "644": [0, 3, 5], "648": [0, 3, 5], "64898": [0, 34, 38], "65": [0, 3, 4, 8, 12, 13, 21, 26, 36, 40, 45], "652": [0, 3, 12], "65534": [20, 23, 41, 53], "65535": [5, 20, 53], "65536": 2, "657": 5, "658": [0, 3], "659": [0, 3, 8], "66": [12, 50], "66796": 46, "668": [0, 3, 8, 49], "6697": 12, "67": [4, 12, 13, 49], "671": [12, 49], "67108864": 24, "673": 12, "674": [0, 3], "674b": 0, "678": [0, 3, 8], "68": [0, 12, 13, 38, 50], "681": 12, "682": [0, 3, 8], "6879": 0, "69": [12, 13, 49], "690": 12, "692": 6, "693": 12, "6961763": 12, "697": 40, "698": 12, "699": 12, "6b": 29, "6cdl": 12, "6cee": 12, "6cs9": 12, "6d": 29, "6f3p": 12, "6fid": 12, "6fid_sweep": 12, "6fvz": 12, "6fwc": 12, "6g1f": 12, "6gth": 13, "6gvk": 12, "6h2p": 12, "6h2p_1p89a": 12, "6h2p_nativ": 12, "6h5t": 12, "6hv2": 12, "6hwj": 12, "6i3j": 12, "6ig7": 13, "6irk": 13, "6iu5": 12, "6iu6": 12, "6iu8": 12, "6iu8_mad": 12, "6iu9": 12, "6jgh": 12, "6jgi": 12, "6jgj": 12, "6m": 12, "6mf": 12, "6moj": 12, "6nen": 12, "6o2h": 12, "6o2h_cryst": 12, "6oel": 12, "6oqz": 12, "6oqz_sweep": 12, "6or0": 12, "6or0_sweep": 12, "6p8j": 12, "6p8p": 12, "6pb3": 12, "6pxb": 12, "6pxc": 12, "6qaj": 12, "6r72": 12, "6rlr": 12, "6rym": 12, "6s0l": 13, "6s1u": 12, "6toc": 12, "6ttn": 12, "6u57": 13, "6u7g": 12, "6ukf": 12, "6v2r": 12, "6vww": 12, "6w4h": 12, "6w75": 12, "6wzo": 12, "6yqf": 12, "6z8o": 12, "6z9g": 12, "6ze4": 12, "6zqr": 12, "6zqy": 12, "6zr0": 12, "6\u03c3": 4, "7": [0, 2, 3, 12, 17, 20, 21, 22, 24, 25, 27, 29, 34, 36, 38, 42, 45, 46, 47, 48, 49, 50, 52, 54, 55, 56, 62], "70": [0, 3, 4, 5, 6, 12, 39, 42, 46, 49], "7000": 25, "701": [0, 3, 12], "707": [0, 3], "71": 12, "7124": 46, "7193538": 12, "72": [0, 3, 12, 13, 39], "720": 12, "7200": 40, "726": 0, "727": 50, "729": [0, 34], "73": [0, 3, 8, 12], "733": 7, "734": 13, "736": [4, 12, 49], "737": 34, "74": [6, 12, 13], "740": 12, "746": [38, 50], "747": 12, "749": 49, "74ytyq": 12, "75": [0, 3, 4, 7, 8, 12, 13, 14, 21, 36, 42, 46, 49], "7575": 12, "76": [0, 8, 12], "76066": 0, "76068": 0, "761522": [0, 34, 38], "765": 4, "768": 6, "77": 12, "773": [0, 3, 8], "775": 12, "78": [7, 12, 27, 38, 46], "782": [0, 3, 8], "785": 12, "787": 13, "788": 12, "79": [0, 12, 13, 38, 42, 46, 50], "791": [0, 3, 8, 12], "792": 13, "794": 7, "7953": 12, "7arr": 12, "7atg": 12, "7b2": 12, "7bgt": 12, "7bgu": 12, "7brr": 12, "7d1m": 12, "7d98": 12, "7dkp": 12, "7gxk": 0, "7k1l": 12, "7kcn": 12, "7l6j": 12, "7l84": 12, "7l84_helic": 12, "7mg": [8, 47], "7mzt": 12, "7n0i": 12, "7n2": 12, "7orr": 12, "7os3": 12, "7ou1": 12, "7ph1": 12, "7pq7": 12, "7q6j": 12, "7qi": 12, "7qij": 12, "7qt9": 12, "7qt9_crystal": 12, "7raa": 12, "7ri": 12, "7rji": 12, "7t5t": 12, "7tcd": 12, "7x7": 21, "7yzx": 12, "7zz": 12, "7\u03c3": [4, 7], "8": [0, 1, 2, 3, 5, 6, 9, 10, 12, 13, 15, 17, 19, 20, 21, 24, 25, 26, 27, 28, 33, 36, 37, 38, 40, 42, 43, 45, 46, 47, 48, 49, 50, 52, 53, 54, 55, 56, 59, 71, 80, 88, 135], "80": [4, 6, 7, 8, 12, 13, 21, 36, 39, 40, 42, 45, 46, 49, 50], "800": [12, 40], "802": [0, 3, 51], "805": 13, "806": 12, "8080": 26, "809": [0, 3, 8], "80gb": 49, "81": [0, 7, 12, 49], "810": [0, 3], "816": 12, "817": 49, "82": [0, 3, 12, 13, 47], "820": 6, "824": 38, "83": [0, 7, 8, 12, 13, 49], "830": 5, "835": 12, "836": 38, "84": [7, 8, 12, 40], "842": [0, 8], "843": 12, "845": [0, 3], "846": 6, "85": [0, 3, 4, 12, 42, 49, 55], "850": [0, 3, 8], "854": 0, "855": [0, 3, 8], "8558p": 22, "857": [0, 8], "86": [0, 12, 13, 36, 44], "861": [0, 3], "862": [0, 3], "864": 12, "869": 12, "87": [12, 13, 39], "871": [38, 50], "8739": 12, "8746": 1, "877": [0, 3], "8794": 12, "88": [12, 21], "880": [0, 3, 8], "881": 12, "882": 6, "887": [0, 3, 8], "89": [12, 36, 38, 50], "892": 12, "893": 12, "895": [0, 5, 49], "897": 49, "8a1a": 12, "8agq": 12, "8bkh": 13, "8c3e": 12, "8c3e_scan": 12, "8dqb": 12, "8dyz": 12, "8dyz_wedg": 12, "8dz7": 12, "8dz7_crystal": 12, "8egn": 12, "8iya": 12, "8k1g": 12, "8m": 25, "8oic": 12, "8owm": 12, "8pqd": 12, "8qaw": 12, "8qj5": 12, "8qq7": 12, "8r5r": 12, "8rud": 12, "8s38": 12, "8sa8": 12, "8sqo": 12, "8sqq": 12, "8sqt": 12, "8t7r": 12, "8tdq": 13, "8tha": 12, "8tyi": 12, "8u0i": 12, "8v2t": 12, "8v4j": 12, "8v4o": 12, "8x10": 18, "8x10g": [14, 18, 22], "8xt": 12, "8xte": 12, "8xtf": 12, "8xtg": 12, "8y74": 12, "8ys9": 12, "8\u03c3": 4, "9": [0, 1, 2, 3, 5, 6, 9, 10, 12, 17, 20, 21, 24, 26, 28, 33, 36, 37, 38, 40, 42, 43, 45, 48, 49, 50, 52, 53, 55, 56, 62], "90": [0, 1, 4, 5, 6, 7, 11, 12, 13, 23, 27, 36, 38, 39, 41, 42, 46, 49, 50, 71], "900": [7, 12], "9000": [18, 24], "9001": 24, "90205": 0, "9049184": 0, "905": 12, "907": 12, "91": [7, 12, 49], "9100": 24, "9104": 12, "914": 6, "916": [6, 12], "918": 12, "918400": 49, "919147": 9, "9197": 12, "92": [0, 12, 49], "920": 12, "921": 12, "922": [0, 12], "923": 0, "928": 12, "92k": 21, "93": [7, 12], "930": 12, "931": [0, 3, 34], "9310": 12, "937": 38, "94": [12, 49], "941": 12, "944": [0, 3, 12, 34], "946": 12, "947": 6, "948": [6, 11], "949": 11, "95": [0, 5, 7, 8, 12, 13, 40, 42, 47, 49], "957": 12, "958": 12, "96": [0, 4, 6, 12, 27, 38, 40, 42, 49], "960": 12, "968": [4, 12, 49], "97": [0, 3, 7, 12, 49], "978": 0, "97809553602060000729": 0, "97809553602060000746": 0, "98": [7, 12, 46, 49], "987": [0, 3, 8], "987x": 0, "9887707": 12, "99": [0, 4, 5, 7, 12, 19, 38, 42, 46, 49, 50], "990": 7, "995": [6, 38], "997": 49, "999": [7, 49, 50], "9994": 38, "9999": 46, "9_4": 0, "9b22": 12, "9bn8": 12, "9c18": 12, "9chw": 12, "9crw": 12, "9e2t": 12, "9ea5": 12, "9fcf": 12, "9fcg": 12, "9fhc": 12, "9gdj": 12, "9gjx": [0, 12, 40, 56], "9gqg": 12, "9h0q": 12, "9hnc": 12, "9hs7": 12, "9i0a": 12, "9i80": 12, "9ig7": 12, "9ih9": 12, "9jq9": 12, "9jzo": 12, "9khr": 12, "9lxl": 12, "9m": [2, 12, 22, 24, 27], "9mh4": 12, "9min": 12, "9o0h": 12, "9o4": 13, "9o4t": 13, "9p7q": 12, "9pbb": 12, "9q41": 12, "9q66": 12, "9qvv": 12, "9qw2": 12, "9qw8": 12, "9rc": 12, "9rp9": 12, "9s02": [0, 12, 40, 56], "9s06": 13, "9sl0": 12, "9t6": 12, "9upt": 12, "9v16": 12, "9v3d": 13, "9vx7": 12, "9vyb": 12, "9w3y": 12, "9yl4": 12, "9yzk": 12, "9z44": 12, "9z72": 12, "9zlo": [0, 12, 38, 40, 45, 50, 56], "9zlo_detector": [38, 50], "9zlo_log": [38, 50], "9zlo_plot": [38, 50], "9zlo_refined_map": 38, "9zlo_refined_model": 38, "9zlo_report": [38, 50], "9zlo_unmerg": [38, 50], "9zm0": 12, "9zmu": 12, "A": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 14, 17, 19, 21, 22, 23, 24, 25, 27, 29, 34, 35, 36, 38, 39, 41, 42, 43, 44, 46, 48, 49, 51, 53, 55, 57, 59, 71, 109, 113, 120, 121, 122, 124, 129, 131, 134], "AND": [5, 17, 49, 56], "AS": 29, "And": [4, 5, 6, 29, 30, 42, 46, 50], "As": [7, 8, 12, 15, 23, 24, 26, 39, 42, 44, 45, 47, 77], "At": [6, 7, 8, 9, 11, 12, 22, 25, 42, 46, 47, 48, 49, 133], "BE": 29, "BEING": 29, "BUT": 29, "BY": [0, 12, 29, 38, 56], "Be": 53, "But": [29, 47], "By": [4, 5, 7, 17, 19, 27, 29, 42, 50, 51], "FOR": [29, 49], "For": [1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 15, 18, 19, 22, 23, 24, 25, 26, 27, 28, 29, 31, 36, 37, 40, 42, 43, 44, 45, 46, 47, 49, 51, 52, 53, 58, 59, 60, 68, 71, 72, 80, 91, 93], "IF": 29, "IN": 29, "IT": 34, "If": [2, 4, 6, 9, 12, 13, 14, 17, 19, 24, 27, 29, 36, 37, 38, 40, 42, 45, 47, 50, 62, 68, 71, 80, 90, 92, 96, 101, 134, 139], "In": [0, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 17, 18, 22, 23, 24, 25, 27, 29, 40, 41, 42, 46, 48, 49, 55, 68, 71, 140], "It": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 14, 17, 18, 19, 23, 24, 25, 26, 27, 28, 29, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 55, 56, 58, 68, 71, 93, 96, 109], "Its": [0, 1, 4, 6, 7, 8, 12, 21, 39, 40, 46, 47, 49, 55, 56, 108], "NO": 29, "NOT": [2, 4, 29, 40, 96, 109], "Near": 49, "No": [4, 7, 8, 12, 14, 19, 23, 24, 29, 36, 38, 45, 46, 47, 49, 50, 51, 53, 68, 71, 93], "Not": [1, 12, 24, 29, 39, 42, 46, 47, 49, 56, 68, 71, 81], "OF": [12, 17, 29, 49], "ON": [2, 9, 10, 18, 42, 43, 45, 59], "OR": [29, 56], "Of": [8, 11, 12, 13, 29, 49], "On": [0, 2, 3, 9, 11, 21, 24, 26, 27, 36, 43, 48, 52, 53, 59, 123], "One": [1, 4, 5, 6, 7, 8, 11, 12, 13, 15, 19, 21, 23, 24, 25, 36, 40, 42, 44, 49, 50, 61, 75, 77], "Or": 9, "SUCH": 29, "Such": [2, 5, 7, 11, 17, 22, 24, 29, 42, 49, 55], "THE": [12, 29], "THERE": 29, "TO": 29, "That": [0, 4, 5, 6, 7, 12, 17, 25, 27, 30, 39, 40, 41, 46, 47, 49], "The": [0, 1, 2, 3, 9, 10, 11, 14, 15, 16, 17, 18, 19, 21, 22, 23, 24, 26, 27, 28, 29, 30, 31, 33, 35, 36, 37, 41, 42, 43, 44, 45, 48, 50, 51, 52, 53, 54, 56, 59, 60, 61, 62, 68, 71, 77, 96, 101, 107, 108, 109, 120, 122, 123, 125, 128, 129, 131, 134], "Their": [12, 40, 42, 56], "Then": [7, 8, 11, 19, 25, 33, 40, 49, 59, 62], "There": [1, 2, 4, 5, 6, 7, 11, 14, 15, 19, 24, 27, 46, 47, 49, 53, 55, 96], "These": [1, 2, 5, 7, 9, 12, 15, 18, 19, 21, 23, 24, 25, 26, 40, 46, 51, 56], "To": [0, 1, 5, 6, 9, 15, 19, 24, 25, 26, 27, 29, 31, 36, 37, 38, 45, 46, 47, 49, 50, 51, 71], "WILL": 29, "WITH": [12, 29], "With": [1, 5, 6, 7, 8, 23, 25, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 55, 57, 71, 75, 77, 128], "_": [2, 4, 5, 6, 7, 40, 42, 44, 50], "_0": [5, 7], "_003": 12, "_004": 12, "_01": [2, 50], "_01_": 2, "_01_detector": 50, "_01_imag": 2, "_01_plot": 50, "_01_process": 50, "_1": [7, 8], "_10": [2, 49], "_2": [6, 7, 8], "_3": [8, 13], "__syncwarp": 5, "_a": [0, 49], "_anom": 2, "_atom_sit": [42, 47], "_atom_site_anisotrop": 8, "_axi": 0, "_b": [0, 5, 7, 46, 49], "_before_search": 4, "_blob": [1, 2, 8, 25, 42, 47, 49, 50], "_cell": [39, 46, 49], "_cell_measur": [46, 49], "_corr": 7, "_d": 6, "_data_000001": 23, "_data_000002": 23, "_data_nnnnnn": 57, "_detector": [2, 50], "_diffrn": [39, 44], "_diffrn_ambient_temperatur": 46, "_diffrn_detector": [39, 46], "_diffrn_radi": 12, "_diffrn_radiation_wavelength": 46, "_diffrn_refln": [42, 47], "_doubl": 49, "_e2_minus_1_f": 49, "_end": [2, 23], "_esd": [46, 49], "_f": [7, 49], "_fa": 46, "_g": 7, "_halfcel": 49, "_helical_x": 23, "_i": 6, "_int16": 13, "_intensity_pct": 49, "_intensity_sigma": 46, "_j": 6, "_jfjoch_aniso_delta_b_linear": 46, "_jfjoch_aniso_floor": 46, "_jfjoch_aniso_signific": 46, "_jfjoch_aniso_verdict": 46, "_jfjoch_beam_center_x_pxl": 46, "_jfjoch_beam_center_y_pxl": 46, "_jfjoch_proven": 39, "_jfjoch_radiation_damage_batch": 46, "_kind": 49, "_l_test_mean_l_squar": 46, "_lattic": 49, "_log": [2, 38, 40, 42, 49, 50], "_ma_qa_metr": [4, 49], "_map": [1, 2, 4, 8, 25, 39, 47, 49, 50, 71], "_master": [2, 23, 25, 26, 38, 42, 44, 50], "_misorientation_deg": 49, "_model": [1, 2, 4, 8, 25, 39, 47, 49, 50, 71], "_modul": [23, 42, 44, 50], "_module_plac": [2, 25, 42, 50, 68], "_mr": [2, 4, 38, 39, 42, 47, 48, 49, 50], "_mr_": [47, 49], "_mr_model": [39, 42, 47, 48, 49, 50], "_null": 49, "_nz01_f": 49, "_ob": 42, "_p1": 2, "_pdbx_aniso_b_tensor_eigenvector_": 46, "_pdbx_refine_tl": 8, "_pdbx_reflns_twin": [4, 40, 49], "_plot": [2, 49, 50], "_process": [2, 4, 5, 7, 26, 38, 39, 42, 44, 49, 50, 57, 59], "_r_free": 8, "_rad": [41, 49, 108], "_range_averag": 23, "_range_tot": 23, "_refin": [40, 47], "_refined_": 47, "_refined_map": [1, 2, 8, 25, 39, 42, 47, 50], "_refined_model": [1, 2, 25, 39, 42, 47, 49, 50], "_refln": [2, 4, 7, 39, 40, 42, 46, 47, 49], "_reflns_shel": [7, 39, 46], "_report": [1, 2, 4, 23, 25, 38, 42, 47, 49, 50, 124, 125, 131], "_sfx_nam": 13, "_softwar": [25, 39], "_solvent": [8, 42, 49], "_spots_pct": 49, "_struct_conn": [8, 47], "_sweep_concentr": 49, "_twin_": [2, 4, 39, 47, 49, 50], "_unmerg": [2, 39, 42, 44, 45, 46, 47, 49, 50], "_unmerged_parti": [42, 46, 50], "_volume_ratio": 49, "_y": 23, "_z": [23, 49], "a0201": 12, "a1": 40, "a100": 49, "a15": 46, "a19": 12, "a2": 40, "a200": 12, "a2a": 13, "a32": [0, 3, 8], "a34": [0, 3, 8], "a37": [0, 8], "a42": [0, 3, 8, 120], "a43": [0, 3], "a45": [0, 3, 8], "a46": [0, 8], "a50": [0, 3], "a51": [0, 3, 8], "a52": [0, 3, 8], "a55": [0, 3], "a58": [0, 8], "a60": 0, "a61": [0, 3], "a68": [0, 8], "a7": 122, "a94fd4f": 56, "a_": [5, 42], "a_0": 8, "a_angle_r5": 12, "a_d": 8, "a_mast": [2, 42], "a_q": 8, "aarch64": [2, 36, 43, 45], "aaredb": 0, "aaregui": 2, "ab": [0, 7], "abandon": 2, "abbrevi": 17, "abc": 12, "abil": 29, "abl": [0, 2, 4, 15], "abolish": 12, "abort": [2, 27], "abortu": 12, "about": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 13, 14, 17, 21, 23, 24, 25, 27, 29, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 51, 57, 62, 71, 93, 107, 109, 110, 134], "abov": [0, 1, 2, 4, 5, 6, 7, 8, 9, 12, 14, 15, 16, 20, 21, 23, 24, 25, 29, 30, 33, 35, 36, 37, 38, 39, 40, 42, 43, 44, 45, 46, 47, 49, 50, 56, 57, 92, 120, 123, 133], "abraham": 0, "abramowitz": [0, 8], "abridg": 38, "abscessu": 12, "abscissa": 7, "abseil": [52, 56], "absenc": [0, 1, 2, 3, 4, 6, 12, 23, 24, 29, 39, 40, 41, 42, 46, 47, 48, 49, 50, 55], "absent": [0, 1, 2, 4, 6, 7, 23, 25, 41, 44, 47, 49, 50, 107, 108, 109, 110, 120, 122, 123, 124, 125, 131, 133], "absent_by_abs": 49, "absent_by_statist": 49, "absolut": [1, 2, 4, 5, 6, 7, 13, 29, 39, 46, 50], "absorb": [4, 5, 6, 7, 8, 12, 27, 39, 40, 41, 42, 46, 47, 49, 50, 56], "absorpt": [0, 2, 3, 4, 5, 7, 8, 21, 42, 48, 50], "abstain": 4, "abus": 29, "ac034173t": 0, "acad": [0, 3], "academ": [0, 3, 49], "academia": 61, "acccttctatgacctactcca": 12, "acceler": [0, 2, 3, 7, 9, 14, 15, 28, 34], "accept": [0, 1, 2, 4, 5, 6, 7, 8, 12, 13, 15, 17, 23, 24, 25, 29, 38, 39, 42, 44, 46, 47, 49, 50, 51, 68, 71, 96, 134, 136, 138, 139, 140], "accepted_altern": 40, "acceptor": [8, 49], "access": [0, 2, 9, 14, 17, 20, 23, 26, 29, 45, 52], "access_token": [35, 51, 71], "accid": 39, "accident": 51, "accommod": [14, 19, 22], "accompani": [29, 58], "accord": [1, 9, 14, 15, 16, 22, 24, 29, 71, 92], "accordingli": [2, 5, 17, 41, 47], "account": [0, 2, 6, 7, 40, 49, 71, 72], "accumul": [5, 6, 7, 45, 49], "accur": [0, 3, 5, 6, 12, 98], "accuraci": [0, 3, 6, 8, 49], "acentr": [0, 2, 3, 4, 7, 8, 12, 49, 50], "acet": [8, 47], "acetivibrio": 12, "acetoacetyl": 12, "acetyl": 12, "acetylalanin": 12, "acetylmuram": 12, "acetylmuramoyl": 12, "acetylmuramoylalanin": 12, "acetylneuramin": 12, "acetyltransferas": 12, "achiev": [5, 7, 29], "acid": [0, 2, 3, 8, 12, 47], "acinetobact": 12, "ack": 136, "ack_cod": 24, "ack_fifo_max_occup": 24, "ack_fifo_occup": 24, "ack_for": 24, "ack_processed_imag": 24, "acknowledg": [2, 3, 4, 5, 8, 12, 17, 24, 25, 26, 29, 45, 49, 56, 61, 71], "acl": 51, "aclacinomycin": [0, 3], "acm": [0, 3], "acquir": [27, 29, 62], "acquisit": [0, 2, 6, 9, 12, 15, 16, 22, 27, 30, 34, 37, 38, 43, 44, 45, 51, 61, 62, 63, 68, 71, 80, 140], "acquisition_typ": 23, "acrb": 12, "acronym": 17, "across": [2, 3, 4, 5, 6, 7, 8, 9, 12, 21, 23, 24, 26, 28, 29, 36, 40, 42, 46, 48, 49, 50, 55, 57, 110, 113, 134], "act": [2, 3, 4, 5, 6, 7, 17, 21, 42, 47, 49, 53, 56], "acta": [0, 3, 5, 7, 8, 12, 49], "actinidia": 12, "action": [2, 19, 20, 26, 29], "action_config": 20, "activ": [5, 7, 12, 24, 29, 33, 38], "actual": [1, 2, 4, 5, 6, 7, 11, 19, 23, 29, 36, 42, 45, 46, 48, 49, 51, 71, 108, 110], "ad": [0, 2, 4, 6, 7, 8, 12, 15, 21, 25, 26, 29, 38, 40, 42, 44, 47, 49, 50, 56, 68, 91, 123, 128], "adam": [0, 3, 4, 8], "adapt": [0, 2, 3, 7, 17, 21, 25, 29, 42, 50, 56, 63, 134], "adaptive_threshold": [5, 134], "adaptivespotfindergpu": [5, 21], "adc": [2, 5, 44], "add": [2, 4, 5, 6, 7, 8, 9, 12, 17, 21, 26, 27, 29, 36, 37, 38, 40, 42, 44, 46, 48, 49, 50, 59], "addit": [0, 1, 2, 4, 5, 6, 7, 9, 14, 17, 23, 29, 55], "addition": [4, 5, 6, 12, 27, 36, 52], "addr": 93, "address": [1, 17, 18, 19, 20, 23, 24, 25, 27, 29, 33, 45, 51, 57, 93, 102, 136, 138, 139, 140], "adenosyl": 12, "adenosylhomocystein": 8, "adenosylmethionin": [8, 12], "adjac": [4, 5, 7], "adjoint": [8, 21], "adjust": [2, 5, 6, 18, 19, 42, 71, 92], "adler": 56, "adma": 12, "admit": [0, 4, 5, 6, 7, 8, 25, 38, 39, 42, 47, 48, 49], "adopt": [2, 4, 5, 6, 7, 8, 23, 29, 39, 42, 47, 49], "adopted_twin": 49, "adp": [8, 12, 47], "adsc": [5, 12, 38, 42, 44, 50], "adu": [1, 5, 7, 16, 25, 92, 105], "adu_histogram": [1, 23], "adu_histogram_bin_width": 1, "advanc": [5, 8, 38, 47, 48, 49, 54, 61], "advantag": 40, "advers": 29, "advic": 0, "advice_extend_rotation_deg": 49, "advice_reorient_tilt_deg": 49, "advis": [2, 17, 29, 49], "advisori": 49, "aerogen": 12, "aeruginosa": 12, "aesthet": 2, "af": [0, 38, 47, 49, 50, 56], "affect": [2, 6, 7, 11, 12, 25, 29, 40, 53, 71, 92, 96], "affero": 29, "affin": 42, "affirm": 29, "afford": [4, 7, 27], "afonin": [0, 3, 8], "afresh": 49, "afro": 46, "after": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 17, 19, 21, 24, 25, 27, 29, 30, 36, 38, 39, 42, 44, 46, 47, 49, 50, 68, 71, 75, 77, 96, 122, 123, 125, 128, 129], "afterward": [0, 4, 23, 39, 47], "again": [2, 4, 5, 6, 7, 8, 12, 21, 25, 26, 30, 39, 40, 42, 46, 47, 49, 50, 71], "against": [0, 1, 2, 3, 5, 6, 7, 8, 12, 13, 17, 21, 23, 24, 25, 26, 27, 28, 29, 36, 37, 38, 40, 41, 42, 45, 46, 48, 49, 50, 51, 53, 55, 56, 57, 61, 71, 123, 124], "agarw": [0, 3, 8], "agbh": [26, 41, 42], "agent": 40, "aggreg": [23, 29, 41, 51], "agipd": [13, 44], "agipd_mar18_v10": 13, "agirr": 0, "agnost": 2, "agrafioti": [0, 3], "agre": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 21, 25, 29, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 122, 134], "agreement": [0, 4, 7, 29, 39, 40, 49, 55], "ahead": [4, 6, 40, 49], "ai": [2, 53], "aid": 0, "aim": [0, 2, 4, 6, 23, 29, 51], "aimless": [0, 2, 3, 4, 7, 38, 42, 46, 49, 50], "air": [0, 2, 5, 7, 14, 42], "al": [0, 3, 4, 5, 6, 8, 12, 13, 15, 28, 49, 56], "alanin": 12, "alarm": 6, "alba": 12, "albican": 12, "albula": [23, 30, 86], "alcohol": 12, "aldimin": 12, "aldolas": 12, "alexeev": [0, 3], "algorithm": [0, 1, 2, 3, 5, 6, 8, 34, 38, 39, 42, 47, 48, 49, 54, 61, 62, 71, 89, 95, 96], "alia": [2, 27, 42], "align": [0, 2, 7, 8, 12, 24, 39, 40, 42, 49, 56], "aligna": 24, "alik": [2, 4, 5, 6, 7, 12, 23, 38, 39, 40, 42, 46, 47, 49, 50, 71], "aliv": [2, 24, 25], "all": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 13, 15, 17, 18, 19, 21, 23, 24, 25, 26, 27, 28, 29, 30, 36, 38, 39, 40, 41, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 54, 55, 56, 57, 59, 62, 68, 71, 72, 80, 82, 86, 89, 93, 108, 109, 122, 125, 133, 136, 138, 139, 140], "alleg": [17, 29], "allen": 0, "alloc": [2, 19, 21, 23, 40, 45], "alloreact": 12, "allow": [1, 2, 4, 5, 6, 7, 8, 11, 14, 15, 17, 22, 23, 24, 25, 29, 33, 40, 42, 46, 47, 49, 55, 62, 63, 68, 69, 71, 97, 140], "almalinux": [2, 19], "almost": [2, 4, 5, 6, 7, 23, 30, 40, 49], "alon": [0, 1, 2, 4, 5, 6, 7, 8, 12, 15, 21, 23, 25, 33, 36, 38, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 109], "along": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 23, 26, 29, 40, 42, 44, 46, 48, 49, 53, 71, 77, 90], "alongsid": [2, 6, 7, 12, 23, 30, 36, 41, 49, 50, 56], "alp": 30, "alpha": [1, 4, 5, 6, 7, 8, 12, 27, 38, 42, 49, 137], "alphabet": 44, "alphafold": [0, 2, 3, 4, 38, 39, 40, 42, 47, 49, 50, 56], "alpin": 30, "alreadi": [2, 4, 5, 6, 7, 8, 9, 11, 12, 21, 23, 24, 26, 27, 29, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 52, 55, 57, 71], "also": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 15, 17, 18, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 34, 36, 37, 38, 39, 40, 42, 43, 44, 45, 46, 47, 49, 50, 51, 52, 53, 55, 56, 59, 71, 86, 96, 128, 129, 140], "alter": [2, 7, 20, 50, 55], "altermatt": [0, 8], "altern": [1, 2, 4, 6, 7, 8, 12, 23, 24, 25, 29, 39, 40, 42, 46, 47, 49, 50, 63], "although": [29, 49], "altitud": 30, "altloc": [1, 49], "altogeth": [2, 5, 6, 11], "alveo": [14, 18, 28, 61], "alvra": [2, 13], "alvra103_int16": 13, "alvra213_int16": 13, "alwai": [1, 2, 4, 5, 6, 7, 9, 12, 15, 21, 23, 24, 25, 27, 36, 38, 39, 40, 42, 43, 44, 45, 47, 49, 50, 53, 68, 71, 96, 134, 139], "am": 13, "ambient": 12, "ambient_temp": [39, 44], "ambig": [0, 140], "ambigu": [0, 2, 3, 6, 8, 25, 38, 40, 42, 48, 49, 50], "ambiguity_": 49, "ambiguity_cryst": 49, "ambiguity_data_disagre": [39, 47, 49], "ambiguity_decided_fract": [39, 49], "ambiguity_reindex": [39, 49], "ambiguity_separation_sigma": [39, 49], "ambiguity_time_": 49, "amd": [0, 14, 18, 22, 28, 36, 43, 45, 52, 56, 61], "amid": 8, "amino": [2, 8, 12, 47], "aminolaevulin": 12, "aminotransferas": 12, "among": [0, 2, 3, 4, 6, 7, 8, 12, 17, 23, 25, 29, 38, 42, 44, 47, 49, 50, 52, 123], "amor": [0, 3], "amount": [4, 6, 12, 23, 30, 39], "amp": [8, 12, 47], "amplifi": [4, 5, 7], "amplitud": [0, 2, 3, 4, 5, 6, 8, 12, 38, 39, 40, 42, 46, 47, 48, 49, 50, 55, 107], "amppnp": 12, "an": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 13, 15, 17, 21, 23, 24, 25, 27, 29, 30, 31, 33, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 55, 57, 59, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 89, 90, 91, 92, 93, 95, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "anal": [0, 3], "analog": 12, "analogu": 7, "analys": [0, 1, 2, 3, 4, 5, 6, 23, 24, 25, 26, 28, 38, 40, 42, 44, 57, 61, 127, 128, 134], "analysi": [0, 1, 2, 10, 12, 16, 23, 27, 28, 30, 33, 36, 37, 39, 42, 44, 45, 47, 48, 49, 51, 52, 61, 62, 68, 71, 85, 125, 127, 128, 129], "analysis_rate_hz": 127, "analyt": [7, 8], "analyz": [1, 2, 26], "ancestor": 12, "anchor": [2, 5, 6, 39, 42, 47], "ancillari": 29, "andargor": 56, "anderson": [0, 3, 7], "andr": [0, 3], "angl": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 15, 21, 23, 25, 40, 41, 42, 44, 46, 47, 49, 50, 63, 68, 69, 71, 90, 113, 119, 123, 133], "angle_deg": [50, 105], "angstrom": [1, 8, 12, 23, 27, 63, 71, 120, 122, 124, 125, 132, 134, 137], "angular": [1, 2, 4, 6, 7, 42, 50, 113], "ani": [1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 17, 18, 21, 22, 23, 24, 25, 26, 27, 29, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 49, 50, 51, 53, 56, 57, 58, 59, 68, 71, 108, 134], "aninotransferas": 12, "anis": [8, 47, 49], "aniso": [1, 4], "anisotrop": [0, 2, 3, 4, 6, 7, 8, 21, 39, 40, 46, 47, 49], "anisotropi": [2, 3, 5, 7, 8, 12, 25, 38, 39, 40, 46, 48], "anisotropy_": 4, "anisotropy_d_min_censor": [4, 49], "anisotropy_d_min_princip": 49, "anisotropy_d_min_ratio": 49, "anisotropy_d_min_spread": 49, "anisotropy_delta_b": 49, "anisotropy_delta_b_linear": 49, "anisotropy_detection_limit": 49, "anisotropy_floor": 49, "anisotropy_forbidden_z": 49, "anisotropy_free_direct": 49, "anisotropy_n_observ": 49, "anisotropy_principal_b": 49, "anisotropy_shap": 49, "anisotropy_sigma_systemat": 49, "anisotropy_signific": 49, "anisotropy_verdict": 49, "ann": [0, 3, 8], "anneal": [0, 3, 8], "annot": [0, 8], "announc": [5, 46], "annuli": 7, "annulu": [7, 49], "anod": [0, 2, 3, 4, 12, 38, 44, 46, 50, 55, 97], "anom": [2, 4, 7, 8, 39, 47, 49, 71, 125], "anom_": [38, 42, 49], "anom_measur": [7, 49], "anomal": [0, 1, 2, 3, 7, 8, 21, 25, 38, 39, 42, 46, 47, 50, 71, 122, 125], "anomalous_bijvoet_pair": 49, "anomalous_expect": 8, "anomalous_map": [71, 125], "anomalous_scatter": [4, 49], "anomalous_scatterer_mean_sigma": [4, 39, 49], "anomalous_sigma": [1, 49], "anomalous_sign": 125, "anomalous_sit": 122, "anomalous_site_01": [2, 4, 39, 49], "anomalous_site_10": 4, "anomalous_site_sigma": 122, "anomalous_unexplained_peak": 49, "anomalous_unexplained_peak_01": [4, 39, 49], "anoth": [0, 2, 4, 5, 6, 7, 8, 17, 19, 21, 23, 25, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 55, 57, 71], "answer": [2, 4, 5, 6, 7, 12, 24, 25, 26, 27, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 50, 51, 68, 107, 109, 110, 125], "anthocyanin": 12, "anti": [12, 29], "antibodi": 12, "antigen": 12, "antitoxin": 12, "antiviru": 40, "anyango": 0, "anymor": 2, "anyon": [17, 29, 40, 46, 49, 51, 61], "anyth": [2, 4, 5, 6, 7, 8, 11, 12, 21, 23, 27, 29, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 51, 55, 57, 68], "anytim": [71, 134], "anywai": [6, 7, 19, 42, 50], "anywher": [2, 4, 5, 6, 7, 8, 26, 45, 51], "ao": 0, "aocc": 52, "aom": 0, "ap": [12, 23], "apach": [51, 56], "apart": [2, 4, 5, 6, 7, 8, 12, 23, 26, 36, 38, 39, 40, 42, 44, 46, 47, 48, 49, 50, 59, 107], "apertur": [7, 42], "apex": [12, 44], "api": [0, 2, 5, 11, 12, 13, 23, 25, 28, 29, 31, 35, 36, 37, 51, 56, 57, 58, 61, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "api_cli": [62, 71], "api_inst": [62, 71], "api_respons": 71, "apicli": [35, 62, 71], "apiexcept": [62, 71], "apn": 12, "apo": [7, 12, 13], "app": [0, 26, 36, 59], "appar": 6, "appear": [2, 4, 5, 7, 12, 46, 49, 50, 134], "append": 11, "appendic": 1, "appendix": 68, "appl": [0, 2, 3, 8, 13, 15, 26, 28, 34, 36, 40, 42, 43, 45, 47, 48, 49, 59], "appli": [0, 1, 2, 3, 4, 6, 7, 8, 11, 15, 17, 19, 20, 21, 23, 25, 26, 31, 36, 39, 40, 42, 44, 46, 47, 49, 50, 51, 62, 63, 68, 71, 72, 134], "applic": [0, 3, 7, 8, 9, 17, 19, 23, 25, 26, 29, 36, 38, 41, 51, 59, 61, 62, 71, 80], "apply_mask": [25, 92], "approach": [0, 5, 6, 7, 21, 62, 107], "appropri": [5, 29], "approv": [6, 17], "approx": [4, 5, 6, 7, 8], "approx0": 7, "approx1": 7, "approx10": 7, "approx4": 7, "approxim": [0, 1, 6, 7, 8, 12, 15, 23, 24, 29], "apr": 0, "apt": [2, 9, 26, 37, 43, 45, 53], "aquila": 0, "ar": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 33, 35, 36, 37, 38, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 55, 56, 58, 59, 61, 62, 68, 71, 72, 75, 77, 86, 91, 92, 96, 99, 107, 108, 109, 111, 122, 123, 125, 127, 128, 129, 131, 133, 134, 138, 139, 140], "arabidopsi": 12, "arbit": 6, "arbitr": 4, "arbitrari": [1, 2, 6, 11, 38, 39, 46, 47, 49, 56, 70], "arc": [2, 5, 6, 41, 49, 109], "arcco": [6, 8], "arch": [36, 40], "architectur": [0, 2, 36, 45, 55], "archiv": [0, 2, 4, 9, 13, 23, 24, 36, 37, 38, 40, 42, 43, 44, 52, 53, 57, 59], "arcsin": 6, "arctang": 5, "area": [1, 2, 5, 7, 15, 21, 26, 29, 33, 42, 68, 71], "arena": 40, "arg": [6, 8, 12, 13, 40], "arg184gln": 12, "argu": [0, 4, 6], "argument": [0, 2, 5, 6, 8, 13, 38, 40, 42, 46, 49, 50, 55, 57], "aris": [0, 17, 29], "arithmet": [0, 4, 5, 7, 21, 23], "arm": [1, 2, 4, 5, 6, 7, 9, 12, 23, 24, 27, 36, 39, 43, 44, 45, 49, 52, 55], "arm64": [2, 26, 36, 43, 45, 59], "arm_dat": 1, "around": [0, 2, 3, 4, 5, 6, 8, 21, 23, 30, 40, 41, 49], "arp": 18, "arrai": [0, 2, 6, 23, 24, 28, 33, 34, 42, 44, 46, 49, 50, 62, 68, 71, 104], "arrang": [29, 49], "arriv": [2, 4, 5, 6, 7, 12, 25, 27, 42, 46, 125, 128], "art": [0, 30], "artefact": [2, 4, 6, 12, 23, 26, 45, 52], "articl": 29, "artifact": 56, "arxiv": 0, "as3": 12, "asc": 37, "ascenzo": [0, 3, 8], "ascii": 44, "ashton": [0, 34], "asic": [71, 78], "asid": [5, 6, 7, 42, 49], "asin": 11, "ask": [0, 1, 2, 4, 5, 6, 8, 12, 23, 24, 29, 36, 39, 40, 46, 47, 48, 49, 50, 61, 71, 109, 125], "asn": 8, "asp": 8, "asp0887_09_0114_data_0000": 38, "asp0887_09_0114_mast": [38, 50], "asparaginas": 12, "aspart": 12, "aspect": 0, "assembl": [1, 2, 4, 11, 23, 25, 44, 68, 75, 77], "assembli": [5, 12, 17, 25], "assert": [6, 12, 29, 39, 47, 49], "assess": [0, 1, 2, 3, 8, 23, 133], "asset": [29, 51], "assign": [0, 2, 3, 4, 6, 7, 12, 15, 18, 24, 46, 49, 71], "assist": 0, "assmann": [0, 3, 34], "associ": [5, 12, 17, 19, 29, 38, 133], "assum": [2, 4, 5, 6, 7, 27, 29, 42, 44, 46, 47, 49, 50, 51, 68, 69, 104, 133], "assumed_from_model": [2, 47, 49], "assumpt": [6, 7, 11, 29, 46, 110], "assur": [17, 29], "asu": [4, 7], "asymmetr": [0, 2, 4, 6, 12, 40, 49], "asymmetri": 49, "asymptot": [2, 7, 46], "async": [65, 71], "async_start": [2, 68, 71], "asynchron": [2, 24], "atakisi": [0, 3, 5], "atan2": [5, 11], "atanasova": 0, "atanh": [0, 7, 49], "atbgl1a": 12, "atcc27853": 12, "atg23": 12, "atmospher": 30, "atna": 12, "atnata1": 12, "atom": [0, 1, 2, 3, 4, 7, 8, 21, 26, 38, 39, 40, 41, 42, 44, 46, 47, 48, 49, 61, 120, 122], "atom_gradient_kernel": 21, "atom_nam": 1, "atomicca": 21, "atp": [8, 12, 47], "attach": [14, 18, 23, 28, 29, 36, 40], "attack": 51, "attain": 7, "attempt": [2, 5, 6, 17, 24, 27, 29], "attent": [25, 38, 49, 50, 131], "attenu": [0, 1, 2, 5, 7, 42, 46, 49, 68], "attenuator_foil": 23, "attenuator_transmiss": [1, 23, 68], "attribut": [1, 12, 23, 29, 49], "aubert": [0, 3, 8], "auc": 6, "audit": [12, 38, 42, 49, 51], "auffing": [0, 3, 8], "aureliu": 34, "aureu": 12, "austin": 56, "australian": [12, 38], "auth": 71, "authent": [2, 62, 71], "author": [1, 4, 12, 25, 29, 35, 42, 51, 56, 68], "authorit": [4, 12], "authorship": [2, 49], "auto": [2, 7, 9, 18, 25, 26, 36, 40, 42, 50, 83, 95], "autobuild": 19, "autocontrast": 71, "autoindex": [0, 3], "autolyt": 12, "autom": [0, 1, 2, 3, 6, 8, 23, 25, 85, 133], "automat": [0, 2, 3, 7, 9, 19, 24, 26, 29, 38, 39, 40, 42, 44, 45, 46, 47, 49, 50, 52, 55, 56, 62, 68, 71, 92, 101], "autoproc": [0, 2, 3, 5, 53], "autosol": 46, "autotrac": 46, "autotun": 27, "auxiliari": [3, 26], "avail": [0, 1, 2, 4, 5, 12, 14, 15, 17, 19, 23, 24, 26, 27, 29, 36, 45, 56, 62, 65, 71, 72, 91, 96, 110], "available_slot": 91, "avalanch": 6, "avapritinib": 12, "averag": [0, 4, 5, 6, 7, 8, 39, 40, 44, 46, 47, 49, 50, 101], "avian": 12, "avium": 12, "avoid": [2, 5, 6, 9, 19, 24, 26, 29, 45, 91, 140], "avx": [36, 40, 43, 59], "avx2": [36, 43, 59], "awai": [0, 4, 6, 7, 8, 12, 26, 29, 39, 40, 42, 47, 48, 49, 51], "awar": [2, 3, 7, 53], "ax": [0, 1, 2, 3, 4, 5, 6, 7, 11, 12, 23, 25, 26, 38, 39, 42, 44, 46, 47, 48, 49, 50, 68, 75, 77], "axi": [0, 1, 2, 4, 5, 6, 7, 8, 12, 14, 23, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 53, 62, 68, 69, 71, 77, 90, 119], "axial": [0, 2, 3, 4, 6, 49], "az": 12, "az_int": 100, "az_int_bin_to_phi": 1, "az_int_bin_to_q": 1, "az_int_bin_to_two_theta": 1, "az_int_map": 1, "az_int_phi_bin_count": 1, "az_int_profil": 1, "az_int_profile_count": 1, "az_int_profile_std": 1, "az_int_q_bin_count": 1, "az_int_result": 1, "azim": [1, 5, 23, 41, 42, 71, 118], "azim_bin": 5, "azim_int": [25, 62, 71, 99], "azim_int_set": [2, 63, 71], "azim_int_settings_dict": 63, "azim_int_settings_from_dict": 63, "azim_int_settings_inst": 63, "azimintset": [62, 71, 99, 100], "azimuth": [0, 1, 2, 3, 6, 7, 11, 16, 21, 24, 25, 26, 27, 28, 41, 45, 48, 50, 57, 62, 63, 71, 109, 110, 111, 112, 113], "azimuthal_bin": 63, "azint": [2, 5, 26, 57], "azint_tim": 1, "azint_unit": 71, "azintenginegpu": 21, "azinttim": 23, "a\u00b2": 42, "b": [0, 1, 2, 3, 4, 5, 6, 12, 17, 21, 23, 25, 26, 27, 29, 34, 38, 39, 40, 42, 43, 45, 46, 47, 48, 49, 50, 55, 122, 123, 133, 137], "b1": 40, "b11": 49, "b12": 49, "b13": 49, "b2": 40, "b22": 49, "b23": 49, "b24": [0, 8], "b27": 12, "b33": 49, "b41": [0, 8], "b47": [0, 8], "b48": [0, 3], "b4c": 12, "b50": [0, 3, 5], "b54": [0, 8], "b56": [0, 49], "b58": 0, "b_": [4, 5, 7, 8], "b_cart": [4, 49], "b_env": 8, "b_factor": 1, "b_i": 8, "b_ib_j": 8, "b_iso": [1, 49], "b_iso_wilson_estim": [7, 46], "b_j": 8, "b_master": [2, 42], "b_q": [5, 8], "b_sol": [3, 21], "ba2": 12, "babic": 34, "bach": 30, "bacillu": [12, 40], "back": [0, 2, 4, 5, 6, 7, 8, 11, 12, 21, 23, 24, 25, 26, 27, 30, 33, 36, 38, 39, 41, 42, 44, 45, 46, 48, 49, 50, 51, 55, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "backbon": 8, "backend": 56, "background": [0, 1, 2, 3, 4, 6, 7, 12, 21, 23, 25, 26, 27, 40, 42, 44, 45, 46, 48, 49, 50, 55, 98, 133, 134], "background_direct_beam": 49, "background_mean": 23, "background_vari": 23, "backlog": 24, "backport": [2, 19], "backpressur": [24, 136], "backtrack": 8, "backward": [6, 36], "bacteri": [0, 12], "bacterioferritin": 12, "bacteroid": 12, "bad": [2, 4, 5, 6, 7, 13, 15, 23, 40, 42, 44, 49, 53], "bad_alloc": 45, "bad_pixel": 127, "badli": [4, 110], "bagdona": 0, "bahn": 30, "bail": 0, "baker": [0, 3], "balanc": [7, 8, 23, 51], "ballard": [0, 3], "balloon": 2, "band": [0, 1, 4, 5, 6, 7, 8, 23, 27, 42, 44, 49, 134], "bandwidth": [2, 5, 16, 42, 48, 49], "bank": [0, 8, 12, 13, 23, 40], "banner": 49, "bar": [2, 4, 5, 6, 7, 9, 26, 38, 39, 51, 60], "barba": [0, 3, 34], "bare": [2, 4, 5, 6, 7, 26, 36, 42, 49, 50, 68], "barend": 13, "barlaud": [0, 3, 8], "barrett": 56, "barti": [0, 3], "base": [0, 1, 2, 3, 6, 7, 8, 11, 12, 15, 16, 17, 19, 23, 26, 27, 29, 34, 42, 44, 46, 48, 49, 55, 60, 71, 80, 139], "base64": [25, 56, 71], "base_class": 97, "base_data_ipv4_address": [25, 72], "base_ipv4_addr": 74, "base_mac_addr": 88, "baselin": [5, 36, 40, 44, 52], "baseline_tim": 40, "basf": [0, 46], "bash": [40, 56], "basi": [0, 1, 2, 3, 4, 6, 7, 8, 15, 22, 23, 24, 39, 40, 41, 42, 49, 52], "basic": [2, 7, 18, 27, 29, 38], "basin": 4, "bat": 12, "batch": [1, 2, 6, 7, 21, 26, 38, 42, 45, 46, 49, 50], "batenburg": 12, "batteri": [0, 2, 4, 5, 7, 8, 38, 46, 47, 49, 55, 56], "batty": 0, "baudouin": 56, "baumannii": 12, "baur": [0, 3, 4], "bayesian": [3, 7], "bazgier": 0, "bbk32": 12, "bc2l": 12, "bdf": 9, "beam": [0, 1, 2, 3, 4, 6, 7, 8, 11, 12, 15, 21, 25, 26, 27, 33, 38, 39, 40, 41, 44, 45, 46, 47, 48, 49, 50, 53, 57, 68, 71, 80, 89, 101, 107, 108, 109, 110, 121, 127, 128], "beam_and_lattic": 42, "beam_cent": [1, 2, 23], "beam_center_i": [1, 11, 68], "beam_center_x": [1, 11, 68], "beam_centr": [5, 49], "beam_centre_off": 49, "beam_centre_shift": 49, "beam_centre_toler": 49, "beam_corr_i": [1, 23], "beam_corr_x": [1, 23], "beam_sigma_pxl": 109, "beam_size_i": 1, "beam_size_x": 1, "beam_size_x_um": [2, 68], "beam_size_y_um": [2, 68], "beam_x_pxl": [5, 11, 27, 41, 49, 68, 107, 108, 109, 110, 127], "beam_y_pxl": [11, 27, 41, 49, 68, 107, 108, 110, 127], "beamcent": 89, "beamcenterbackgroundgpu": 21, "beamcenterfftgpu": 21, "beamlin": [0, 2, 5, 6, 7, 11, 12, 13, 22, 23, 25, 28, 34, 39, 42, 44, 49, 50, 51, 61, 68, 69], "beamtim": [6, 44], "bear": [2, 6, 7, 23], "bearer": [2, 25, 26, 35, 62, 68, 71], "bearer_token": 71, "bearerauth": [31, 68, 71], "beat": [2, 4, 5, 6, 8, 20, 39, 42, 47, 49, 55], "beaten": 4, "becam": [2, 23, 25, 49], "becaus": [1, 2, 4, 5, 6, 7, 8, 11, 12, 22, 23, 25, 27, 29, 36, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 109], "becom": [2, 4, 5, 7, 8, 12, 17, 26, 42, 49, 53], "bedem": 0, "been": [2, 4, 5, 7, 8, 12, 26, 27, 29, 40, 44, 46, 47, 49], "befor": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 20, 21, 23, 24, 25, 26, 27, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 71, 75, 77, 99, 107, 109, 123, 125, 126, 136], "beforehand": 40, "began": [6, 8, 49, 71], "begin": [2, 5, 68, 71], "behalf": [7, 17, 29, 40], "behav": [26, 38], "behavior": [2, 18, 19, 24, 25, 27, 71], "behaviour": [0, 2, 23, 42, 46, 49], "behen": [0, 2, 3, 6, 41], "behind": [0, 2, 3, 4, 5, 7, 13, 21, 25, 26, 30, 34, 38, 39, 40, 41, 42, 46, 47, 49, 51, 54], "beilsten": [0, 3], "being": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 17, 19, 24, 25, 27, 28, 29, 38, 39, 42, 44, 46, 47, 49, 51, 56, 71, 107, 140], "believ": [6, 17, 29], "bell": [0, 56], "belong": [0, 1, 2, 4, 5, 6, 12, 15, 23, 24, 26, 33, 42, 44, 46, 49], "below": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21, 23, 24, 25, 26, 27, 29, 36, 38, 39, 40, 42, 44, 46, 47, 49, 50, 51, 52, 53, 55, 56, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "bench_check": 40, "bench_reason": 40, "bench_verdict": 40, "benchmark": [0, 38, 55, 56], "bend": [4, 5, 42, 49], "beneficiari": 17, "benefit": [29, 50, 56], "benoit": 56, "bent": [7, 49], "berka": 0, "berman": 0, "bernal": 12, "bernes": 30, "bernina": 30, "bernstein": 0, "bertoni": 0, "bertrand": 34, "besid": [0, 1, 2, 4, 5, 6, 7, 8, 12, 13, 21, 23, 25, 28, 38, 39, 40, 41, 42, 44, 46, 47, 48, 50, 55, 57, 65, 71, 109], "bessel": [0, 8], "bessi": 12, "best": [0, 2, 3, 4, 5, 7, 8, 21, 22, 29, 39, 40, 42, 44, 46, 47, 48, 49, 50, 51], "beta": [1, 2, 4, 6, 7, 8, 12, 27, 38, 39, 42, 137], "beta4": 12, "beta_i": 6, "beta_x": 6, "better": [0, 2, 4, 5, 6, 7, 8, 9, 12, 39, 40, 41, 42, 44, 47, 48, 49, 50, 86], "between": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 19, 21, 23, 24, 26, 27, 29, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 55, 63, 67, 71, 72, 75, 77, 80, 96, 100, 107, 110, 111, 119, 134], "beyond": [0, 1, 2, 3, 4, 5, 6, 7, 8, 22, 27, 29, 40, 42, 45, 46, 47, 49, 52, 56], "bf01588962": 0, "bf01589116": 0, "bf01932995": 0, "bf2": 12, "bfactor": [1, 23], "bfg": [0, 3, 8, 21], "bfr": 12, "bg": 46, "bgmean": 46, "bgvar": 46, "bhat": 0, "bia": [0, 4, 6, 7, 42, 49], "bias": [0, 3, 4, 5, 6, 7, 12, 42, 49, 50], "bibi": 13, "bifunct": 12, "big": [4, 5, 6, 7, 45], "bigger": 36, "biggest": 40, "bigxtal": 13, "bijvoet": [0, 2, 4, 5, 7, 8, 21, 38, 39, 42, 46, 47, 49, 50, 71, 125], "bilirubin": 12, "biliverdin": 12, "billich": 34, "bimod": 40, "bin": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 15, 21, 23, 25, 26, 36, 38, 40, 41, 42, 43, 44, 45, 49, 51, 59, 62, 63, 71, 110, 111], "bin_to_phi": 23, "bin_to_q": [5, 23], "bin_to_two_theta": 23, "bin_width": 23, "binari": [0, 1, 2, 5, 8, 12, 24, 33, 36, 40, 43, 45, 49, 50, 52, 55, 61, 62, 71], "bind": [0, 2, 3, 4, 6, 8, 12, 24, 42, 47, 51], "binder": 0, "binomi": [5, 6], "biol": [0, 3, 8], "biolog": 0, "biologi": [0, 3, 8], "biomax": [12, 34], "biometrika": [0, 3], "biomolecular": [0, 3], "biorxiv": [0, 13, 34, 38], "biphenyl": 12, "bisect": 4, "bisphosph": 12, "bit": [0, 1, 2, 3, 4, 5, 6, 7, 9, 15, 19, 20, 21, 23, 24, 33, 36, 39, 40, 42, 43, 44, 45, 50, 52, 53, 59, 62, 71, 72, 80, 92], "bit_depth_imag": [23, 25, 92], "bit_depth_readout": [1, 2, 50, 53], "bit_index": 23, "bite": 6, "bitmap": 2, "bitmask": [1, 5, 23], "bitshuffl": [0, 1, 2, 3, 5, 13, 21, 23, 44, 45, 55, 56, 57], "bitshuffle_hperf": 56, "bitstream": 14, "bittrich": 0, "bjel\u010di\u0107": 34, "bkg": [1, 7, 50, 133], "bkg_estim": [1, 101], "bkgestim": [23, 50], "bkgestimatemean": 23, "bl": 12, "bl02u1": 12, "bl11": 12, "bl12": 12, "bl17u1": 12, "bl17um": 12, "bl19u1": 12, "bl2": 13, "bl21": 12, "bl41xu": 12, "bl44xu": 12, "bl9": 12, "blac": 13, "black": 2, "blackwel": [2, 36], "blanc": [0, 3, 8], "blank": [5, 12, 49], "blanton": [0, 3], "bless": [0, 3, 40], "blind": [0, 1, 2, 4, 7, 23, 42, 49, 133], "blk": [25, 102], "blntr_9gjx": 40, "blob": [0, 1, 2, 3, 4, 25, 38, 47, 48, 49, 50, 71, 120, 123], "blob_count": 123, "block": [0, 2, 5, 6, 7, 11, 12, 21, 24, 25, 27, 39, 40, 42, 44, 49, 51, 71, 96, 102, 136], "blondel": [0, 3, 8], "blow": [0, 3, 4], "blur": [4, 8, 21], "bmc": [0, 8], "bmi2": 36, "bmod": 7, "bmra": 12, "board": [9, 10, 14, 22, 62, 82], "bodi": [0, 2, 3, 8, 21, 25, 29, 38, 39, 40, 41, 42, 45, 46, 47, 48, 49, 50, 61, 71, 108, 122, 123], "bodili": 4, "bolotovski": [0, 3, 6], "bond": [0, 8, 21, 25, 47, 49, 123], "bool": [1, 23, 63, 68, 71, 72, 80, 87, 88, 90, 92, 96, 97, 99, 101, 109, 122, 123, 125, 128, 129, 134, 138, 139], "boolean": [1, 24], "boost": 5, "bootstrap": [0, 7, 49], "border": 5, "borderlin": 4, "bordetella": 12, "borrelia": 12, "both": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 14, 15, 17, 18, 19, 21, 23, 24, 25, 26, 28, 29, 30, 34, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 55, 56, 61, 63, 71, 75, 77, 89, 104, 107, 113], "bothrop": 12, "bottom": [11, 18, 26, 49, 50, 90, 135], "bought": [4, 49], "bound": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 23, 24, 25, 36, 40, 42, 45, 49, 51, 71, 113, 114, 133, 136], "boundari": [0, 2, 3, 4, 6, 7, 11, 92], "bourenkov": [0, 3], "bourn": 0, "bovin": [0, 12, 40], "box": [0, 1, 2, 3, 4, 5, 6, 15, 21, 23, 26, 29, 40, 42, 44, 49, 77, 98, 114, 115, 118], "boxsum": [4, 7, 42, 98], "bp230": 12, "bp3": 46, "bpag1": 12, "bpti": 12, "br": 8, "brace": 44, "bragg": [0, 1, 2, 3, 4, 6, 21, 25, 26, 36, 38, 40, 41, 42, 43, 45, 49, 50, 62, 64, 71, 98], "bragg_integr": [2, 62, 71, 99, 100], "bragg_integration_set": [25, 64, 71], "bragg_integration_settings_dict": 64, "bragg_integration_settings_from_dict": 64, "bragg_integration_settings_inst": 64, "bragg_prediction_tim": 1, "braggexp": [0, 21], "braggintegrationenginegpu": 21, "braggintegrationenginemet": 21, "braggintegrationset": [62, 71, 99, 100], "braggpredictiongpu": 21, "braggpredictionrotgpu": 21, "braggpredictiontim": 23, "branch": [19, 36, 38, 40, 49], "bravai": [0, 1, 2, 3, 4, 5, 7, 23, 25, 48, 50, 89, 132], "bravaislattic": 23, "brd4": 12, "breach": 17, "break": [0, 2, 3, 6, 7, 24, 46, 49, 58, 91], "brehm": [0, 3, 7], "brese": [0, 8], "brewster": 0, "brick": 21, "bricogn": [0, 3, 6], "bridg": [5, 7, 36], "brief": [17, 29, 40, 42], "bright": [5, 7, 26], "brighter": 34, "brightest": [5, 7, 50], "bring": [4, 5, 8, 38, 46], "broad": [2, 6, 7], "broadband": 7, "broadcast": 18, "broaden": 7, "broader": [7, 42, 49], "broennimann": 0, "broken": [2, 7, 13, 49], "broker": [1, 2, 5, 6, 7, 8, 9, 11, 23, 24, 26, 27, 28, 34, 35, 36, 37, 38, 39, 41, 42, 44, 45, 47, 49, 50, 51, 56, 57, 59, 61, 68, 100, 128], "broker_a": 9, "broker_b": 9, "broker_crmx": 25, "broker_eig": 25, "broker_loc": 25, "broker_statu": [2, 65, 71], "broker_status_dict": 65, "broker_status_from_dict": 65, "broker_status_inst": 65, "broker_vers": 65, "brokerstatu": [62, 71, 100], "bromodomain": 12, "brought": [4, 21, 30, 39, 47, 49], "brown": [0, 8], "brows": 2, "browser": [2, 9, 12, 28, 45, 51], "brucei": 12, "brucella": 12, "bruker": [2, 12, 44], "brunger": 0, "brute": 6, "br\u00fcckner": [0, 34], "br\u00fcnger": [0, 3, 7, 8], "bsd": [0, 56], "bshuf_zstd": [1, 5], "bshuf_zstd_rl": [1, 5], "bshuf_zstd_rle_huff": [1, 2, 5], "bsl": 56, "bslz4": [1, 5, 68], "bslz4decod": [0, 3], "bslz4decodergpu": 21, "bszstd": 1, "bthtx": 12, "bu": [5, 9, 36, 51, 59], "bubcd": 12, "budget": [4, 7, 8, 21, 27, 40, 42, 45], "buerger": 0, "buffer": [1, 2, 4, 5, 8, 16, 21, 24, 25, 27, 40, 42, 51, 62, 71, 91, 99, 100, 108, 136, 140], "bug": [2, 53], "bugfix": 2, "bui": [2, 4, 7, 8, 22, 49], "build": [0, 1, 2, 4, 5, 6, 7, 8, 9, 12, 21, 23, 25, 28, 38, 42, 43, 46, 47, 48, 49, 50, 52, 53, 54, 55, 59, 61, 62, 71, 128, 129], "build_and_test": [36, 55], "build_cxx_flag": 49, "built": [0, 2, 3, 4, 6, 7, 8, 9, 10, 14, 15, 19, 21, 22, 25, 26, 28, 30, 35, 36, 37, 39, 40, 43, 45, 46, 49, 50, 51, 52, 53, 55, 56, 57, 59, 99, 123, 136], "bulk": [0, 2, 3, 7, 21, 39, 40, 42, 47, 49], "bulldoz": 36, "bullet": 4, "bullou": 12, "bunch": [0, 1, 3], "bundl": [2, 5, 6, 24, 25, 26, 36, 42, 45, 51, 52, 56, 61], "bunk": 34, "bunzip2": 12, "bureau": [0, 8], "burgdorferi": 12, "buri": [0, 8], "burian": 34, "burkholderia": 12, "burlei": 0, "burst": 83, "buschiazzo": 0, "busi": [2, 17, 24, 27, 29, 81, 136], "busier": 21, "buster": [4, 39], "butanamid": 12, "butku": 0, "button": [2, 25, 26, 51, 60], "bv": 49, "bw": 7, "byte": [1, 2, 4, 5, 12, 20, 21, 23, 24, 25, 27, 39, 42, 45, 47, 49, 53, 71, 136], "bytearrai": 71, "bz2": 12, "b\u00e9jar": [0, 34], "c": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 13, 14, 17, 21, 23, 26, 27, 29, 34, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 49, 50, 52, 55, 57, 59, 137], "c00": 13, "c01": 13, "c106a": 12, "c1r": 12, "c2": [0, 2, 4, 7, 39, 49, 50], "c222": 39, "c2221": 39, "c2r": 21, "c3": 12, "c6h8o7": 46, "c71": [0, 8], "c7a": 12, "c9dysh": 12, "c_": [5, 7], "ca": [8, 12, 49], "cabl": [14, 18], "cach": [2, 5, 16, 55], "cacodyl": [8, 12], "cadc": 12, "cadmium": 12, "calc": [4, 8, 47], "calcul": [0, 1, 2, 3, 5, 6, 7, 8, 11, 16, 20, 25, 47, 55, 60, 62, 63, 67, 68, 71], "calib": [13, 26], "calibr": [0, 2, 3, 4, 6, 7, 8, 9, 11, 15, 19, 20, 21, 23, 24, 25, 26, 38, 44, 47, 50, 53, 57, 60, 61, 62, 68, 71, 72, 100, 108, 109, 134], "calibration_fil": [25, 72], "calibration_statistics_inn": [66, 71], "calibration_statistics_inner_dict": 66, "calibration_statistics_inner_from_dict": 66, "calibration_statistics_inner_inst": 66, "calibrationstatisticsinn": [62, 71, 100], "calidifonti": 12, "call": [0, 2, 4, 5, 7, 8, 9, 10, 19, 26, 29, 30, 35, 36, 40, 41, 45, 46, 49, 51, 62, 71], "caller": [2, 5], "calsequestrin": 12, "cambridg": 0, "came": [2, 4, 6, 7, 8, 12, 25, 36, 39, 46], "camera": [5, 42, 44], "campaign": [2, 4, 7, 39, 47], "campeotto": 12, "campylobact": 12, "can": [0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 15, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 29, 30, 31, 33, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 49, 50, 52, 55, 56, 57, 58, 62, 68, 71, 72, 80, 90, 91, 101, 108, 123, 125, 134, 136], "cancel": [2, 7, 8, 16, 20, 24, 25, 42, 49, 50, 51, 55, 62, 71, 101, 123, 125, 128], "cancel_post": 62, "candid": [0, 2, 4, 5, 7, 8, 12, 21, 39, 40, 42, 46, 47, 48, 49], "candida": 12, "cannot": [0, 1, 2, 3, 5, 7, 8, 11, 12, 13, 15, 21, 23, 24, 25, 26, 29, 36, 37, 38, 39, 40, 41, 42, 45, 46, 47, 48, 49, 50, 51, 53, 55, 71, 72, 136], "cannot_determin": [48, 49], "canon": [0, 2, 6, 7, 25, 48, 49, 50, 55], "canton": 30, "canva": 2, "canyon": 30, "cap": [2, 5, 6, 7, 12, 13, 21, 27, 42, 45, 51], "capabl": 15, "capp": 12, "capsid": [8, 40, 45], "captur": [2, 5, 7, 21, 42, 44, 46, 51], "carbohydr": 12, "carbonyl": 0, "carboxamid": 12, "carboxyl": 8, "card": [2, 4, 5, 8, 14, 15, 18, 19, 20, 22, 25, 28, 36, 38, 40, 42, 43, 45, 46, 48, 55, 59, 71], "cardbyt": 21, "cardiac": 12, "cardioderma": 12, "care": [1, 2, 15, 18, 47], "careless": [2, 38, 42, 46, 50], "carlo": 6, "carm1": 12, "carri": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 14, 17, 20, 23, 24, 25, 26, 27, 28, 29, 33, 36, 38, 39, 40, 42, 44, 46, 47, 49, 50, 51, 53, 56, 59, 68, 71, 109, 125], "cartesian": [49, 120], "carugo": [0, 8], "cascad": 2, "case": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 17, 18, 19, 20, 21, 22, 23, 24, 25, 27, 29, 38, 39, 40, 41, 42, 46, 49, 50, 53, 55, 58, 71, 72, 92, 109, 133, 134, 139, 140], "cast": [5, 23, 53], "castellan": [0, 34], "cat": [12, 19], "cat_wiz": [0, 8], "catalyt": 12, "catch": [4, 5, 6, 7, 25, 40, 45, 46], "catch2": [2, 52, 55, 56], "catechin": 12, "categor": 24, "categori": [1, 2, 46], "cation": [8, 12, 49], "cauchi": [2, 7], "caught": [7, 46, 49], "caus": [4, 17, 29, 40, 46, 49], "caution": 4, "caveat": [7, 8, 36, 50], "ca\u00b2": 8, "cbf": [0, 1, 2, 5, 11, 12, 21, 23, 38, 42, 44, 46, 50, 55, 86], "cbf_byte_offset": [0, 5, 21], "cbfdecodergpu": 21, "cbflib": 0, "cbnr": 12, "cbor": [2, 6, 11, 23, 24, 25, 28, 51, 54, 58, 62, 68, 71, 94, 138, 139, 140], "cbx7": 12, "cc": [0, 1, 2, 3, 4, 5, 7, 12, 21, 38, 39, 40, 42, 46, 47, 50, 56, 124], "cc0": [0, 12, 56], "cc1": [0, 2, 3, 5, 7, 21, 25, 26, 38, 39, 40, 42, 47, 48, 49, 50, 124, 125], "cc_": [4, 6, 7], "cc_ab": [0, 49], "cc_anom": [2, 7, 38, 49, 50], "cc_anom_pair": [7, 49], "cc_half": [4, 49, 124], "cc_half_split": 49, "cc_model": [49, 122], "cc_model_": 47, "cc_model_confirmed_to_d_min": [40, 47, 49], "cc_model_overal": 49, "cc_model_reflect": 49, "cc_n": 50, "cc_null": 49, "cc_ref": 124, "cc_star": [4, 49], "cc_to_merg": 50, "cca": 46, "ccanom": [0, 7], "cccggccgga": 12, "ccd": [2, 5, 7, 33, 42, 44, 46], "ccd_detector_descript": 12, "ccd_image_satur": 44, "ccp4": [0, 2, 3, 7, 8, 25, 38, 39, 40, 46, 47, 49, 50, 51, 55, 56, 62, 71, 125], "ccp4_setup": 40, "ccref": [3, 25, 49, 125], "cctbx": [0, 3, 7, 49], "cd": [8, 9, 14, 25, 26, 38, 55, 56], "cd9": 12, "cdnd": 12, "cdot": [4, 5, 6, 7, 8], "cdot10": 4, "cdte": [0, 2, 7, 12], "ceacam6": 12, "ceas": [17, 29], "cehovin": 34, "ceil": [4, 5, 7, 8, 38, 42, 45, 49], "cell": [1, 2, 3, 4, 5, 7, 8, 12, 13, 19, 20, 21, 23, 25, 26, 27, 39, 40, 41, 42, 43, 44, 46, 47, 48, 50, 51, 55, 61, 68, 71, 80, 96, 109, 133, 137], "cell_diff_pct": 40, "cell_dspacing_fit": 49, "cell_esd": 49, "cell_esd_block": 49, "cell_esd_block_count": 49, "cell_esd_lsq": 49, "cell_esd_observ": 49, "cell_esd_reflect": 49, "cell_esd_theta_range_deg": 49, "cell_form": [6, 49], "cell_mismatch": 49, "celsiu": 44, "cen": 4, "censor": [7, 49], "censu": 49, "cent": [4, 5, 6, 7], "center": [0, 1, 2, 3, 4, 5, 11, 14, 23, 27, 42, 49, 68, 71, 89, 116, 132], "center_x_pxl": [23, 116], "center_y_pxl": [23, 116], "centering_untest": 49, "cento": [2, 19, 37], "centr": [0, 1, 2, 3, 4, 6, 7, 8, 12, 21, 23, 25, 26, 38, 39, 40, 41, 44, 45, 46, 47, 48, 49, 50, 53, 55, 57, 71, 77, 107, 109, 110, 122, 127, 128], "central": [8, 12, 28, 36], "centre_statistics_": 49, "centre_statistics_control_f": 49, "centre_statistics_e2_minus_1": 49, "centre_statistics_l": 49, "centre_statistics_l_f": 49, "centre_statistics_nz01": 49, "centre_statistics_reflect": 49, "centre_statistics_verdict": 49, "centre_twinning_exclud": 49, "centric": [0, 2, 3, 4, 7, 8, 12, 23, 49], "centroid": [1, 2, 4, 5, 6, 7, 8, 11, 23, 39, 41, 47, 49, 120], "centrosymmetr": [0, 3, 4, 5, 49, 50], "centrosymmetri": 5, "ceo2": [0, 26, 41, 42], "ceo\u2082": 6, "cere": [2, 6, 8, 52, 56], "cerevisia": 12, "cern": [0, 29, 56, 61], "certain": [15, 19, 29], "certif": [0, 26], "certifi": [4, 109], "cessat": 29, "cf": [23, 132], "cfom": 46, "cg300906j": 12, "cgi": 0, "cglbvh": 12, "cgroup": [42, 45], "ch": [26, 30, 37, 38, 45, 53, 62], "chad": 56, "chaetomium": 12, "chaillet": 0, "chain": [0, 1, 2, 4, 6, 8, 11, 12, 23, 39, 40, 42, 46, 47, 48, 49, 90], "challeng": [0, 34], "chanc": [4, 5, 6, 33, 42, 46, 49], "chang": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 14, 19, 21, 23, 24, 25, 26, 27, 29, 36, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 51, 53, 58, 62, 71, 91, 134], "changelog": [58, 61], "channel": [1, 2, 5, 7, 20, 23, 27, 42, 49, 71], "chaperon": 12, "chapman": 0, "chaptal": 12, "charact": [0, 1, 3, 4, 6, 17, 39, 46], "character": 29, "characteris": 5, "characterist": [0, 3, 17], "charbonni": [0, 3, 8], "charg": [1, 7, 8, 17, 29, 61], "chart": [2, 26, 36], "chase": 49, "chassi": 9, "chateign": 0, "cheap": [6, 26], "check": [2, 3, 5, 6, 7, 8, 9, 11, 12, 13, 21, 22, 24, 26, 27, 38, 39, 42, 43, 45, 46, 47, 48, 49, 50, 52, 55, 56, 96, 110], "checkabl": 5, "checkbox": 2, "checklist": [2, 25, 125, 131], "checkmymet": [0, 8], "checkpoint": 42, "cheetah": [0, 3, 13, 38, 42, 44], "chem": [0, 3, 8, 13], "chemic": [0, 3, 8, 11, 12, 46, 47, 49, 71], "chemistri": 8, "chess": 12, "chi": [1, 2, 4, 7, 12, 23, 49, 69], "chi_axi": [1, 69], "chi_deg": [1, 2, 69], "chicago": 56, "chimer": 12, "chimera": 12, "chip": [2, 15, 25, 33, 36, 42, 50, 53, 92], "chiral": [0, 4, 8, 21, 49, 55], "chi\u00b2": 2, "chlorid": [0, 8], "choic": [0, 2, 3, 4, 5, 7, 8, 12, 23, 26, 37, 38, 39, 40, 42, 45, 46, 47, 49, 50, 56], "cholera": 12, "choos": [0, 2, 4, 5, 6, 29, 39, 40, 42, 46, 47, 48, 49, 50, 51, 62, 71], "chordin": 12, "chose": [4, 8, 22, 46, 47, 49, 50], "chosen": [0, 2, 3, 4, 5, 6, 7, 8, 12, 23, 24, 25, 26, 27, 38, 39, 40, 42, 46, 47, 48, 49, 50, 68, 89, 123], "christian": [0, 56], "chromodomain": 12, "chromon": 12, "chronolog": 46, "chunk": [5, 21, 23, 48], "chymotrypsin": 12, "ci": [2, 8, 21, 55], "cif": [0, 1, 2, 4, 8, 23, 25, 26, 38, 42, 46, 47, 48, 49, 50, 51, 55, 56, 61, 62, 71, 120, 125], "cif2mtz": [39, 42, 46], "circ": [4, 5, 6], "circl": [1, 2, 5, 7, 11, 15, 21, 23, 41, 42, 44, 110, 116, 118], "circuit": 7, "circular": [2, 7, 26, 42, 116, 117], "circumst": [17, 29], "circumvent": 29, "citabl": [0, 12], "citat": [0, 3, 8, 12, 28, 34, 49, 56], "cite": [0, 2, 3, 12, 13, 40, 49, 55, 61], "citrat": 12, "citrobact": 12, "civil": 29, "ck63": 12, "cl": [4, 8, 26, 49], "claim": [2, 4, 5, 6, 7, 12, 17, 29, 36, 39, 49], "clamp": [4, 7, 8, 12, 42, 53], "clang": [26, 36, 52], "clarifi": [2, 22], "clariti": 2, "clash": [0, 4, 8, 47, 49], "clashscor": 8, "class": [0, 1, 2, 4, 5, 6, 12, 19, 23, 29, 39, 40, 46, 47, 49, 55, 62, 71, 97], "classic": [4, 6, 7, 42, 98], "classif": [1, 5], "classifi": [4, 7, 47, 48], "claud": 0, "claus": [0, 56], "clean": [2, 4, 5, 6, 7, 23, 42, 49], "cleanli": [0, 2, 4, 42], "cleanup": 2, "clear": [2, 4, 6, 7, 20, 24, 25, 26, 29, 33, 40, 41, 49, 51, 57, 60, 62, 71, 125], "clearanc": 7, "clearer": 2, "clearli": [4, 5, 7, 12, 29, 30, 39, 42, 46, 49], "clemen": [0, 53], "cli": [2, 26, 36, 37, 49, 52, 57], "clibd": 8, "click": 26, "client": [2, 24, 25, 26, 28, 29, 36, 51, 56, 57, 61, 71], "climb": [4, 30], "clion": 19, "clip": [0, 3, 4, 5, 7, 21, 23, 42, 44, 50, 134], "clipboard": 2, "clock": [2, 20, 40], "clockwis": 11, "close": [2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 24, 25, 27, 29, 38, 40, 42, 47, 49, 50, 60, 71, 134], "closer": [6, 7, 8, 11, 49], "closest": [4, 6, 8, 30, 49, 68], "closur": 8, "cloud": 6, "clsi": 12, "cluster": [5, 26, 36, 49], "cm": 12, "cmac": 20, "cmake": [2, 9, 10, 14, 25, 26, 28, 40, 43, 45, 52, 56], "cmake_64": 26, "cmake_prefix_path": 26, "cmakecach": 40, "cmd": 40, "cmt2": 12, "cn": 47, "co": [0, 2, 4, 5, 6, 7, 8, 12, 30, 42, 49, 107], "coa": 12, "coalesc": 5, "coars": [2, 4, 5, 6, 21, 25, 42, 111, 125], "coarsen": 5, "coarser": [2, 4, 6, 8, 21, 40, 42, 49, 96], "coarsest": [7, 49], "cobalt": 12, "cod": [0, 12], "code": [0, 1, 2, 3, 5, 10, 11, 17, 19, 23, 24, 25, 26, 29, 36, 38, 40, 49, 53, 56, 62, 71, 97, 131], "codegen": 62, "codesign": 26, "codi": 0, "coeffici": [0, 1, 2, 3, 4, 5, 7, 8, 20, 21, 23, 25, 38, 39, 47, 49, 50, 71], "cofactor": [2, 8, 47], "coffset": 44, "coher": [0, 6, 13, 23], "coin": [4, 6], "coincid": [0, 5, 6, 7, 8, 12, 42, 46], "col": [11, 30], "colano": 46, "cold": [9, 40, 42], "coli": 12, "colin": [46, 56], "colinear": 2, "collabor": [0, 17], "collaps": [2, 4, 6, 7, 23, 49], "colleagu": [40, 51], "collect": [0, 1, 2, 3, 5, 6, 7, 13, 15, 20, 24, 26, 27, 28, 29, 30, 33, 34, 38, 39, 42, 44, 51, 53, 55, 56, 57, 59, 61, 62, 65, 67, 68, 71, 80, 91, 101, 121, 125, 127, 128, 129, 134, 139], "collection_effici": 101, "collet": 56, "collid": 6, "collinear": 6, "colon": 68, "color": [2, 71], "colormap": 0, "colour": [0, 2, 26, 50], "column": [0, 1, 2, 4, 5, 7, 8, 11, 23, 33, 39, 40, 42, 44, 45, 46, 47, 50, 55], "com": [3, 18, 53], "combin": [0, 2, 4, 6, 21, 23, 29, 39, 40, 42, 45, 46, 48, 49, 50, 90], "combo": 26, "come": [0, 2, 5, 6, 7, 8, 11, 17, 21, 24, 25, 26, 27, 29, 34, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 55, 61, 71, 97], "command": [1, 2, 6, 7, 9, 13, 14, 26, 27, 28, 29, 37, 38, 40, 44, 45, 46, 49, 50, 55, 57, 61, 71], "command_lin": [2, 39, 49], "comment": [12, 25, 40, 46, 49, 71], "commerci": [14, 29, 49, 61], "commiss": [0, 3, 12], "commit": [2, 4, 5, 6, 29, 39, 40, 48, 49, 56], "common": [0, 1, 2, 4, 5, 7, 8, 29, 40, 46, 47, 48, 49, 50, 133], "commonest": 4, "commonli": 5, "commun": [0, 1, 2, 13, 17, 19, 23, 24, 29, 49, 62], "comp": [0, 3, 8], "compact": [1, 5, 7, 23, 42, 50], "compani": [4, 49, 109], "companion": 23, "compar": [0, 2, 3, 4, 5, 6, 7, 8, 12, 26, 38, 39, 47, 48, 51, 55, 57, 91], "compare_hkl": 49, "comparison": [0, 4, 5, 6, 8, 12, 26, 40, 42, 46, 47, 49, 55, 109], "compat": [0, 1, 2, 4, 7, 8, 9, 17, 18, 22, 23, 27, 28, 36, 51, 52, 53, 56, 61, 86], "compens": 6, "compet": [5, 6, 8, 40], "compil": [2, 4, 8, 9, 10, 17, 29, 36, 40, 45, 47, 49, 52, 55], "complement": 7, "complementari": 6, "complet": [2, 5, 6, 7, 12, 17, 20, 24, 25, 26, 27, 38, 39, 40, 42, 45, 46, 49, 50, 52, 56, 71, 124, 125], "complete_dark": 13, "complex": [0, 11, 12, 22], "compli": [17, 29], "complianc": [17, 29, 97], "compliant": [1, 2, 23, 27, 50], "compon": [0, 2, 3, 4, 6, 7, 8, 17, 21, 29, 36, 37, 49, 52, 58, 61], "compos": [4, 5, 8, 21, 44, 92], "compose_target_kernel": 21, "composit": [0, 4, 6, 7, 8, 21, 46], "compound": [8, 12, 46, 47, 56], "comprehens": 51, "compress": [0, 2, 4, 5, 9, 12, 16, 20, 21, 23, 25, 27, 28, 40, 44, 48, 56, 57, 68, 101], "compression_ratio": 101, "compression_tim": 1, "compressiontim": 23, "compris": 3, "compulsori": [2, 72], "comput": [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 18, 21, 23, 25, 26, 29, 39, 40, 42, 46, 47, 48, 49, 50, 122], "compute_cc_one_half": 7, "concentr": [5, 7, 42, 49], "concept": [3, 7, 23, 50, 51], "concern": [7, 12, 17, 23, 29, 51], "concurr": 4, "condens": 23, "condit": [0, 2, 3, 4, 5, 6, 7, 17, 20, 25, 27, 33, 38, 41, 49, 55, 56, 131], "cone": [1, 2, 3, 4, 5, 23, 49, 133], "confid": [0, 4], "confidenti": 51, "config": [2, 13, 25, 33, 37, 40, 51, 55, 62, 71, 129], "config_azim_int_get": 62, "config_azim_int_put": 62, "config_bragg_integration_get": 62, "config_bragg_integration_put": 62, "config_dark_mask_get": 62, "config_dark_mask_put": 62, "config_detector_get": 62, "config_detector_put": 62, "config_file_writer_get": 62, "config_file_writer_put": 62, "config_image_format_conversion_post": 62, "config_image_format_get": 62, "config_image_format_put": 62, "config_image_format_raw_post": 62, "config_indexing_get": 62, "config_indexing_put": 62, "config_instrument_get": 62, "config_instrument_put": 62, "config_internal_generator_image_put": 62, "config_internal_generator_image_tiff_put": 62, "config_mask_get": 62, "config_mask_tiff_get": 62, "config_roi_get": 62, "config_roi_put": 62, "config_rugnux_get": 62, "config_rugnux_model_delet": 62, "config_rugnux_model_put": 62, "config_rugnux_put": 62, "config_select_detector_get": 62, "config_select_detector_put": 62, "config_spot_finding_get": 62, "config_spot_finding_put": 62, "config_user_mask_get": 62, "config_user_mask_put": 62, "config_user_mask_tiff_get": 62, "config_user_mask_tiff_put": 62, "config_zeromq_metadata_get": 62, "config_zeromq_metadata_put": 62, "config_zeromq_preview_get": 62, "config_zeromq_preview_put": 62, "configur": [1, 2, 5, 6, 7, 11, 17, 19, 22, 23, 26, 27, 28, 35, 36, 40, 43, 45, 49, 51, 52, 55, 56, 57, 58, 59, 60, 62, 63, 68, 71, 99, 136, 140], "confin": [0, 6, 8, 9, 51], "confirm": [2, 4, 5, 7, 9, 12, 24, 40, 47, 49], "conflat": 24, "conflict": 2, "conform": [8, 12, 42, 47, 49], "confus": [2, 11], "cong": 56, "conic": 6, "conj": 21, "conjug": 21, "conlei": 56, "connect": [0, 2, 3, 8, 9, 13, 14, 15, 18, 21, 22, 24, 25, 26, 27, 29, 36, 42, 51, 56, 57, 71, 81, 93, 136], "connected_writ": 93, "connector": [14, 18], "connectx": 22, "consecut": [0, 2, 26, 46, 49, 80], "consensu": 25, "consequ": [5, 29], "consequenti": [17, 29], "conserv": 46, "consid": [2, 5, 7, 15, 17, 29, 42, 53, 58, 67, 80, 96, 134], "consider": 19, "consist": [2, 4, 5, 6, 7, 11, 12, 23, 29, 30, 38, 39, 42, 47, 49, 50, 71], "consol": [40, 50], "consolid": 2, "consortium": 0, "conspicu": 29, "const": 7, "constant": [0, 3, 4, 5, 6, 7, 15, 20, 23, 46, 50, 51, 93], "constantli": [2, 29], "constitut": [17, 29], "constrain": [4, 6, 15, 48, 49, 50], "constraint": [0, 3, 6, 7, 8], "constru": 29, "construct": [4, 5, 6, 7, 12, 49, 55], "consult": [0, 6, 8, 23, 42], "consum": [2, 4, 5, 7, 23, 27, 29, 40, 49, 51], "consumpt": 22, "contact": [0, 8, 21, 29, 47, 49], "contain": [1, 2, 4, 5, 6, 7, 9, 12, 17, 23, 24, 25, 26, 27, 28, 29, 36, 40, 43, 44, 45, 46, 49, 50, 55, 71], "contamin": [0, 7, 55], "content": [0, 1, 2, 3, 4, 5, 9, 12, 14, 19, 24, 25, 26, 28, 29, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 49, 52, 59, 61, 71], "context": [1, 2, 29, 62, 71], "contigu": [2, 7, 8, 19, 49], "continu": [2, 3, 4, 5, 6, 7, 8, 11, 12, 14, 17, 24, 26, 29, 36, 46, 47, 49], "continuum": 4, "contour": [5, 71], "contract": [6, 17, 45], "contractu": 29, "contradict": [29, 49], "contrast": [2, 7, 26, 29, 46, 51, 71], "contribut": [0, 1, 2, 5, 6, 7, 23, 39, 49, 55], "contributor": [29, 56], "contributori": 17, "control": [0, 1, 2, 4, 5, 7, 10, 11, 12, 14, 16, 20, 21, 23, 24, 28, 29, 31, 36, 40, 49, 50, 51, 55, 57, 61, 62, 71, 92], "conv": 13, "convei": [17, 23, 29], "conveni": [23, 29, 31, 37], "convent": [0, 1, 2, 3, 4, 6, 7, 23, 24, 38, 42, 44, 49, 50, 72, 138, 139, 140], "convention": [4, 7], "converg": [0, 2, 6, 7, 41, 107, 109, 110], "convers": [1, 2, 8, 12, 13, 16, 20, 23, 44, 46, 53, 62, 71], "convert": [2, 4, 5, 7, 11, 12, 13, 15, 25, 40, 44, 46, 49, 57, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "convex": [4, 49], "convey": [17, 29], "convict": [6, 49, 50], "convolut": [5, 21], "convolv": 4, "cool": [14, 44, 46], "cooper": [0, 3, 5], "coordin": [0, 1, 2, 3, 4, 6, 7, 8, 12, 39, 40, 42, 47, 49, 50, 56, 71, 104, 114, 116, 122], "coot": [0, 3, 4, 8, 38, 39, 47, 50], "cope": [24, 49], "copi": [0, 1, 2, 3, 4, 5, 6, 8, 9, 11, 12, 13, 17, 19, 21, 23, 26, 29, 36, 38, 39, 40, 42, 43, 45, 47, 48, 49, 50, 52, 56, 122], "copies_lik": 49, "coplanar": 6, "copper": [18, 22], "copyleft": [29, 62], "copyright": [17, 29, 52, 56], "coral": [2, 50], "core": [0, 2, 4, 5, 6, 7, 14, 16, 18, 20, 21, 27, 38, 40, 42, 49, 50], "corkscrew": 30, "corner": [2, 5, 6, 11, 23, 30, 44, 49, 72, 135], "cornish": [0, 3], "coronaviru": 12, "corpor": [9, 56], "corpu": [2, 4, 7], "corr": [2, 7], "correct": [1, 2, 3, 4, 6, 8, 9, 11, 12, 15, 16, 18, 21, 23, 24, 29, 40, 42, 45, 46, 48, 49, 50, 63], "correctli": [0, 2, 7, 9, 11, 12, 19, 23, 36, 53], "correl": [0, 2, 3, 4, 5, 7, 12, 21, 23, 39, 40, 41, 42, 49, 50, 96, 107, 122], "correlation_beam_x_rot1": 107, "correlation_beam_y_rot2": 107, "correspond": [0, 1, 2, 6, 8, 11, 17, 18, 23, 25, 26, 29, 36, 56], "correspondingli": [5, 53], "corrobor": 12, "corrupt": 4, "cos2": 6, "coset": [0, 2, 4, 7, 8, 49], "cosh": 8, "cosin": [0, 6], "cosmic": 5, "cost": [2, 4, 5, 6, 7, 8, 12, 14, 17, 21, 22, 23, 25, 29, 39, 42, 46, 47, 49, 50, 55], "cosym": 0, "cos\u00b2": 49, "cos\u00b2\u03b8": 49, "could": [0, 1, 2, 3, 4, 5, 6, 7, 12, 18, 23, 24, 25, 26, 27, 29, 39, 41, 45, 46, 47, 49, 71, 93, 107, 109, 122, 131, 133], "couldn": 2, "count": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 15, 19, 20, 21, 23, 25, 26, 27, 33, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 51, 53, 55, 67, 68, 72, 80, 92, 96, 101, 133], "count_tim": [1, 23], "count_time_u": [25, 80], "countabl": 5, "counter": [19, 20, 44, 57, 91], "counterclaim": [17, 29], "counterpart": [0, 8, 21, 56], "countrat": 1, "countrate_correction_appli": 23, "countrate_correction_en": 1, "countrate_correction_lookup_t": [1, 23], "countri": [29, 30], "coupl": [4, 5, 6, 7, 23, 26, 41], "cours": 29, "court": 29, "couturi": [0, 3], "cov": 12, "coval": [8, 12, 49], "covari": [7, 41, 49, 107], "coven": 29, "cover": [2, 3, 4, 5, 6, 9, 11, 12, 17, 26, 27, 29, 40, 42, 43, 45, 47, 49, 53, 55, 56, 71], "coverag": [0, 2, 12, 29, 40, 49], "cow": 30, "cowtan": [0, 3, 8], "cp": 46, "cpack": 26, "cpp": [5, 21, 23, 56], "cpu": [0, 1, 2, 4, 5, 6, 7, 10, 15, 21, 22, 23, 25, 26, 28, 29, 33, 38, 39, 42, 43, 45, 47, 49, 50, 52, 54, 55, 56, 57, 59, 60, 63, 71, 123, 128, 129], "cpu_data_analysi": 2, "cpu_data_analysis_decis": 49, "cpu_data_analysis_refin": 49, "crack": 7, "crambin": [0, 3, 8], "crash": [2, 40], "creat": [2, 14, 17, 19, 24, 27, 33, 38, 51, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "creation": 2, "credenti": [26, 35], "credit": [12, 49], "crest": 7, "cristallin": [0, 3], "cristallographi": 0, "criteria": [0, 4, 5, 7, 15], "criterion": [0, 3, 4, 5, 7, 8, 15, 29, 49], "critic": [0, 2], "croll": [0, 3], "cromer": [0, 8, 56], "crop": 2, "cross": [0, 2, 3, 4, 5, 6, 7, 17, 21, 26, 29, 36, 38, 42, 46, 47, 48, 49, 50, 51, 110], "crossref": 12, "crowd": [2, 6, 7, 30, 42, 49], "crowther": [0, 3, 4], "crucial": 7, "cryo": [44, 49], "cryocrystallographi": [0, 3], "cryoprotect": [5, 49], "crypto": 56, "crysalispro": 12, "cryst": [0, 3, 5, 7, 8, 12, 13, 15, 28, 34, 49], "cryst1": 46, "crystal": [0, 1, 2, 3, 4, 5, 6, 8, 12, 13, 21, 23, 25, 26, 38, 39, 40, 41, 42, 44, 46, 47, 48, 50, 55, 56, 68, 119, 132, 134], "crystal_nam": 1, "crystal_out_of_beam": [23, 49], "crystalclear": 0, "crystallin": [6, 49], "crystallis": 2, "crystallit": [4, 5, 7, 42, 49], "crystallograph": [4, 7, 8, 12, 21, 30, 38, 46, 49, 54, 57], "crystallographi": [0, 2, 3, 6, 12, 23, 28, 34, 40, 44, 53, 54, 68, 96], "crystfel": [0, 2, 3, 5, 6, 7, 13, 23, 42, 44, 48, 49, 50, 55], "csi": 13, "cspad": 44, "csr": [8, 21], "csv": 40, "ct": 7, "ctip": 12, "ctrl": [2, 8, 26], "ctruncat": [0, 2, 3, 4, 7, 40, 46, 49], "cu": [8, 21, 46, 56], "cub": [21, 45], "cubic": [1, 2, 4, 6, 12, 46, 49, 55, 120], "cuda": [0, 2, 4, 5, 6, 7, 8, 9, 21, 22, 23, 26, 28, 29, 37, 40, 42, 43, 45, 52, 56, 59, 61], "cuda12": [9, 37, 38, 43, 45, 59], "cuda13": [36, 37, 43, 45, 59], "cuda_device_ord": 9, "cuda_path": 26, "cuda_visible_devic": 9, "cudaerrorcallrequiresnewerdriv": 36, "cudaeventblockingsync": 21, "cudart": 56, "cuenca": [0, 34], "cufft": [2, 4, 8, 21, 25, 26, 29, 36, 42, 43, 45, 52, 56], "cuhf2": 12, "cumul": [0, 3], "cure": [17, 29], "curiou": 51, "curl": [13, 33, 37, 38, 41, 45, 51], "current": [0, 1, 2, 3, 4, 5, 6, 7, 10, 14, 15, 18, 19, 22, 23, 25, 26, 27, 31, 36, 37, 38, 42, 43, 51, 52, 53, 59, 60, 62, 68, 71, 81, 91, 125], "current_count": 91, "current_id": 73, "cursor": [2, 26], "curv": [0, 2, 4, 7, 21, 23, 39, 42, 46, 48, 49, 50, 55], "curvatur": [2, 5, 6, 7, 8, 21, 42, 49], "custom": [8, 24, 29, 47, 62, 71], "custom_geometri": [25, 42, 44, 68, 72, 75, 77], "customarili": 29, "cut": [0, 2, 4, 5, 6, 7, 8, 14, 21, 24, 25, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 56, 71, 123, 125, 128, 129], "cut_": 125, "cutoff": [0, 2, 3, 6, 8, 21, 25, 38, 42, 46, 49, 50, 128, 129], "cv": 53, "cw": 11, "cw20": 12, "cxi": [2, 13, 38, 42, 44, 50], "cxidb": [0, 13], "cxidb_86_themolysin_": 13, "cxidb_90": 13, "cy": [4, 8, 47, 122], "cyan": 2, "cycl": [0, 5, 7, 8, 9, 21, 40, 47, 49], "cyclic": 12, "cyclopropylaminobenzothiazol": 12, "cymborowski": 0, "cys1": 8, "cys2": 8, "cystathionin": 12, "cystein": 8, "cytc_x10sa": 40, "cytidin": 12, "cytidine_omega": 12, "cytochrom": [0, 40], "cytoplasm": 12, "d": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 17, 19, 21, 23, 27, 29, 36, 37, 38, 39, 41, 42, 44, 46, 47, 50, 51, 59, 134], "d1": 44, "d104a": 12, "d13": 12, "d2": 12, "d26n": 12, "d2o": [0, 3], "d368": 0, "d375": 0, "d420": 0, "d427": 0, "d439": 0, "d444": 0, "d52": [0, 8], "d53": [0, 3, 8], "d55": [0, 3, 8], "d57": [0, 3, 8], "d57n": 12, "d58": [0, 3, 8], "d59": [0, 3], "d60": [0, 3, 8], "d61": [0, 3, 7, 8], "d62": [0, 3, 8], "d621": 12, "d62n": 12, "d63": [0, 3], "d64": 0, "d64n": 12, "d66": [0, 3, 7, 8, 49], "d67": [0, 3, 8], "d68": [0, 3, 8], "d69": [0, 3], "d70": [0, 3, 8], "d71": [0, 8], "d72": 0, "d73": [0, 8], "d74": [0, 3], "d75": [0, 3], "d76": [0, 3], "d77": [0, 3, 5], "d78": [0, 3], "d783a": 12, "d79": 0, "d_": [4, 5, 6, 7, 8], "d_0": 8, "d_a": [6, 105], "d_b": 6, "d_c": 6, "d_f": 7, "d_i": 6, "d_j": 8, "d_max": [40, 124], "d_min": [21, 40, 42, 49, 71, 124, 125], "d_min_us": 40, "da": [8, 49], "daemon": 26, "dai": [13, 17, 29, 38, 55], "damag": [0, 2, 6, 7, 17, 29, 44, 49, 50, 121], "damp": [4, 21], "dampnpp": 12, "dan": [0, 3], "danger": 29, "daniel": 56, "dano": 46, "daresburi": 12, "dark": [2, 5, 13, 24, 25, 26, 33, 50, 62, 67, 71], "dark_mask": [62, 71, 99, 100], "dark_mask_set": [67, 71], "dark_mask_settings_dict": 67, "dark_mask_settings_from_dict": 67, "dark_mask_settings_inst": 67, "dark_ref": 13, "darkest": 5, "darkmaskset": [62, 71, 99, 100], "darpin": 12, "dash": 47, "dashboard": [2, 25, 60], "dasip": [0, 3], "dasip48288": 0, "dat": 2, "data": [2, 9, 10, 14, 17, 19, 20, 22, 25, 27, 29, 30, 33, 34, 40, 41, 44, 45, 48, 51, 55, 61, 62, 63, 65, 68, 70, 71, 80, 86, 91, 96, 101, 109, 124, 125, 134, 139], "data_000001": 23, "data_1": 44, "data_collect": [25, 51, 62, 71], "data_collection_d": 12, "data_collection_effici": [1, 23], "data_collection_efficiency_imag": [1, 23], "data_mast": 47, "data_origin": [23, 44], "data_processing_set": 100, "data_reduction_factor_serialmx": [1, 23, 68], "data_root": 40, "data_s": [23, 44], "data_sampl": 39, "databas": [0, 56], "datacit": [12, 13], "datamessag": 2, "dataset": [0, 1, 2, 3, 4, 5, 21, 23, 25, 26, 30, 31, 33, 35, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 53, 55, 57, 60, 61, 63, 68, 71, 86, 91, 134], "dataset_id": 1, "dataset_mast": [38, 42, 43, 50, 59], "dataset_nam": 1, "dataset_name_data_000001": 27, "dataset_set": [2, 23, 41, 44, 49, 68, 71, 96, 108, 109], "dataset_settings_dict": 68, "dataset_settings_from_dict": 68, "dataset_settings_inst": 68, "dataset_settings_smargon": 69, "dataset_settings_smargon_dict": 69, "dataset_settings_smargon_from_dict": 69, "dataset_settings_smargon_inst": 69, "dataset_settings_xray_fluorescence_spectrum": 70, "dataset_settings_xray_fluorescence_spectrum_dict": 70, "dataset_settings_xray_fluorescence_spectrum_from_dict": 70, "dataset_settings_xray_fluorescence_spectrum_inst": 70, "datasetset": [35, 62, 71, 108], "datasetsettingssmargon": [62, 68], "datasetsettingsxrayfluorescencespectrum": [62, 68], "datawritefail": 24, "date": [1, 12, 17, 29, 39, 40, 49], "dauter": [0, 8], "da\u0161kevi\u010d": 0, "db": [4, 21, 39, 40, 42, 47, 49, 56], "dbu": [2, 26], "dc": [8, 12], "dcmake_build_typ": [26, 40, 45], "dcmake_c_flag": [40, 45], "dcmake_cuda_compil": 26, "dcmake_cxx_flag": [40, 45], "dcmake_install_prefix": 9, "dcmake_prefix_path": 26, "dcu": [10, 27], "de": [0, 2, 3, 5, 6, 7, 12, 13, 38, 42, 47, 48, 50], "deacon": 0, "deactiv": [2, 62, 71], "deactivate_post": 62, "dead": [4, 5, 7, 24, 42, 49, 127, 136], "deadlin": [8, 24, 25, 60, 123, 125], "deadline_": [25, 125, 128, 129], "deadlock": 2, "deal": [5, 17, 30, 49], "dealt": [7, 49], "deb": [2, 28, 36, 37], "debian": [2, 37], "debt": 4, "debug": [2, 20, 23, 27, 38, 40, 42, 47, 50, 99], "deby": [4, 7, 49, 50], "dec": 0, "decad": 44, "decai": [2, 7, 21, 42, 48, 49, 50], "decarboxylas": 12, "decemb": 29, "decid": [0, 1, 2, 3, 4, 5, 6, 7, 11, 21, 23, 25, 26, 29, 38, 39, 40, 42, 45, 46, 47, 48, 50, 57, 61, 68, 89, 127, 128], "decil": 4, "decim": [2, 4, 7, 38, 50], "decis": [0, 2, 5, 7, 8, 21, 25, 38, 39, 40, 42, 45, 49, 122], "declar": [2, 4, 5, 11, 12, 17, 23, 24, 31, 40, 44, 49, 53, 109, 136], "declin": [5, 29, 39, 41, 49, 109], "decod": [0, 1, 2, 3, 16, 20, 21, 45, 48], "decoi": [6, 7], "decompos": [11, 46], "decomposit": 4, "decompress": [0, 1, 2, 3, 5, 7, 12, 21, 44, 45], "deconvolv": 7, "decreas": [6, 7, 8], "dectri": [1, 2, 5, 12, 15, 23, 24, 25, 26, 28, 30, 33, 44, 53, 57, 61, 71, 72, 80, 84, 86, 128, 129, 134], "dedic": [2, 9, 16, 18, 23, 24, 40, 51, 56, 96], "dedupl": 6, "deem": [17, 29], "deep": [5, 6, 42], "deeper": [4, 6, 7], "deepest": 4, "deepmind": [0, 56], "defam": 4, "default": [0, 1, 2, 4, 5, 6, 8, 9, 10, 11, 19, 20, 21, 23, 24, 25, 26, 27, 33, 36, 38, 39, 40, 41, 44, 45, 46, 47, 48, 49, 50, 53, 57, 62, 63, 64, 65, 67, 68, 69, 71, 72, 80, 87, 90, 92, 93, 96, 97, 98, 99, 104, 106, 119, 128, 134, 135, 136, 138, 139, 140], "default_set": 72, "defaultapi": [35, 62], "defeat": 4, "defect": [4, 25, 29, 33, 40, 45, 48, 49, 53, 127], "defend": 5, "defens": [29, 40], "defensin": 12, "defer": 4, "deferr": 4, "deficit": [4, 5, 46, 49], "defin": [1, 2, 5, 6, 7, 11, 19, 20, 21, 23, 25, 27, 29, 31, 33, 39, 42, 49, 58, 62, 68, 71, 101], "definit": [1, 2, 3, 4, 7, 8, 9, 11, 15, 17, 29, 49, 62, 71, 90, 97, 119], "defint": 118, "defpix": 0, "deg": [1, 2, 7, 12, 23, 42, 49, 50], "degc": 44, "degener": [4, 5, 6, 7], "degeneraci": [6, 7], "degrad": [7, 23, 39, 45, 49, 50, 53], "degre": [0, 1, 2, 4, 5, 6, 7, 11, 12, 23, 27, 42, 47, 49, 50, 69, 71, 113, 119, 125, 137], "dehydratas": 12, "dehydrogenas": 12, "dehydroquin": 12, "deigen3_dir": 52, "deinococcu": 12, "dejoi": [0, 3], "dekker": 0, "delai": [1, 2, 22, 80], "delet": [7, 12, 17, 25, 43, 45, 46, 62, 71], "delfwt": [4, 39, 47, 71], "deliber": [4, 5, 6, 7, 23, 27, 36, 40, 46, 49, 53], "deliv": [2, 23, 25, 26, 38, 42, 49], "deliveri": 5, "delphi": [7, 42, 46], "delta": [0, 2, 3, 4, 5, 6, 7, 8, 12, 21], "delta_": [5, 6, 7], "delta_cc_half": 49, "delta_cc_half_s": 49, "delta_dummi": 53, "delta_i": 6, "delta_phi": 23, "delta_x": 6, "deltab": [0, 2, 3], "demand": [4, 49], "demo": [38, 45], "demot": [4, 6, 46], "den": 0, "deni": [24, 29], "denitrifican": 12, "denomin": [2, 6, 7, 29, 55], "denot": 2, "dens": [2, 5, 7, 8, 21, 23, 42, 45, 46], "denser": [6, 8, 49], "densest": 49, "densiti": [2, 3, 5, 7, 21, 25, 26, 36, 38, 39, 40, 42, 45, 47, 48, 49, 50, 55, 62, 71, 120, 122], "denzo": 0, "deoxyadenosin": 12, "depart": 7, "depend": [1, 2, 4, 5, 6, 7, 8, 9, 12, 21, 23, 26, 27, 28, 36, 39, 40, 42, 43, 45, 47, 49, 51, 55, 59, 71], "depends_on": [1, 11, 23], "deploi": 9, "deploy": [2, 22, 26, 28, 36, 52, 59, 61], "deposit": [0, 2, 4, 5, 6, 7, 8, 13, 38, 39, 40, 42, 44, 47, 49, 50, 55, 56, 92], "depositor": [0, 8, 12, 40, 47, 56], "deprec": [2, 25, 27, 86], "depress": [7, 42, 49], "depriv": 29, "depth": [0, 1, 2, 4, 5, 6, 7, 12, 48, 49, 80, 92], "der": 8, "deriv": [0, 3, 4, 5, 7, 8, 12, 21, 27, 42, 46, 50, 51, 56, 62, 134], "descend": 30, "descent": 8, "describ": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 15, 21, 23, 24, 25, 26, 36, 37, 38, 39, 40, 41, 42, 44, 46, 47, 49, 50, 51, 53, 54, 55], "descript": [0, 1, 2, 3, 7, 17, 23, 24, 25, 39, 40, 42, 47, 48, 49, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "descriptor": [0, 3, 21], "deshpand": 0, "desi": 12, "design": [0, 6, 7, 8, 12, 14, 15, 17, 18, 29, 34, 40, 49, 51, 54, 56, 58, 61], "desktop": [26, 28, 36, 37, 38, 45, 50, 51, 52, 59, 61], "despit": 4, "destin": [2, 18, 45], "destroi": [4, 7], "desulfovibrio": 12, "det": [5, 41, 42], "det_info": 23, "detail": [4, 9, 10, 11, 14, 17, 20, 25, 29, 31, 32, 38, 40, 45, 47, 57, 60, 68, 131], "detect": [0, 1, 2, 3, 4, 6, 8, 9, 12, 14, 19, 21, 24, 26, 27, 33, 42, 46, 49, 50, 63, 89, 134], "detect_ice_r": [1, 23, 42, 68, 96], "detector": [0, 1, 2, 3, 4, 5, 7, 9, 13, 14, 15, 16, 18, 19, 20, 21, 22, 24, 25, 26, 27, 28, 30, 33, 34, 36, 37, 38, 39, 40, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 54, 57, 60, 61, 62, 63, 68, 71, 73, 74, 77, 80, 81, 82, 92, 99, 100, 101, 107, 108, 109, 110, 127, 128, 133, 134, 135], "detector_2theta": 11, "detector_descript": 1, "detector_dict": 72, "detector_dist": [1, 23, 46, 49], "detector_distance_m": 27, "detector_distance_mm": [49, 68, 107, 110], "detector_from_dict": 72, "detector_geometri": 23, "detector_height": 101, "detector_height_pxl": 27, "detector_inst": 72, "detector_list": [71, 73, 100], "detector_list_dict": 73, "detector_list_el": 74, "detector_list_element_dict": 74, "detector_list_element_from_dict": 74, "detector_list_element_inst": 74, "detector_list_from_dict": 73, "detector_list_inst": 73, "detector_modul": [1, 75], "detector_module_dict": 75, "detector_module_from_dict": 75, "detector_module_inst": 75, "detector_module_plac": [44, 68, 77], "detector_module_placement_dict": 77, "detector_module_placement_from_dict": 77, "detector_module_placement_inst": 77, "detector_nam": 44, "detector_numb": [2, 23], "detector_orientation_mirror_i": [1, 23], "detector_orientation_quarter_turn": [1, 23], "detector_pixel_depth": 101, "detector_select": [71, 79], "detector_selection_dict": 79, "detector_selection_from_dict": 79, "detector_selection_inst": 79, "detector_serial_numb": 1, "detector_set": [25, 71, 80, 99, 100], "detector_settings_dict": 80, "detector_settings_from_dict": 80, "detector_settings_inst": 80, "detector_sn": 12, "detector_statu": [71, 82], "detector_status_dict": 82, "detector_status_from_dict": 82, "detector_status_get": 62, "detector_status_inst": 82, "detector_threshold_ke_v": 67, "detector_tilt": 49, "detector_transl": 1, "detector_trigger_delay_n": [25, 80], "detector_width": 101, "detector_width_pxl": 27, "detectorlist": [62, 71, 100], "detectorlistel": [62, 73], "detectormodul": [62, 72], "detectormoduledirect": [62, 75, 77], "detectormoduleplac": [62, 68], "detectorpowerst": [62, 82], "detectorselect": [62, 71], "detectorset": [62, 71, 72, 99, 100], "detectorspecif": [2, 23], "detectorst": [62, 82], "detectorstatu": [62, 71, 100], "detectortim": [62, 80], "detectortyp": [62, 72, 74], "determin": [0, 1, 2, 3, 5, 6, 7, 8, 12, 23, 25, 26, 29, 38, 39, 40, 41, 42, 46, 47, 48, 49, 50, 51, 80, 91, 125, 132], "determinaci": 0, "determined_from_model": [2, 49], "determinist": [0, 2, 3, 4, 6, 7, 8, 21, 42, 46], "detwin": [4, 8], "deubiquitinas": 12, "dev": [0, 8, 19, 25, 49, 57], "develop": [0, 2, 3, 4, 8, 12, 15, 17, 23, 25, 26, 29, 30, 36, 38, 42, 45, 47, 57, 62], "deviat": [1, 2, 4, 5, 6, 7, 8, 15, 21, 23, 47, 49, 50, 63, 122, 123], "deviator": [0, 4, 7, 46, 49], "devic": [1, 2, 3, 4, 6, 7, 9, 15, 17, 21, 23, 24, 25, 29, 36, 43, 45, 55, 57, 62, 71, 102], "devicebyt": 21, "deviceradixsort": 21, "devicereduc": 21, "devicescan": 21, "df": 21, "df_c": [4, 8], "dfc": [0, 1, 2, 3, 8, 25, 38, 39, 47, 49, 50, 71, 120, 122, 123], "dfegli": 12, "dg": 8, "dgx": [2, 36, 43, 45, 52], "dgzkw3": 12, "dhkl": 46, "di": [2, 4, 12, 49], "diad": 6, "diagnos": [0, 8, 42], "diagnosi": 38, "diagnost": [2, 4, 5, 6, 7, 39, 42, 49, 50, 121], "diagon": 8, "dial": [0, 2, 3, 4, 6, 7, 11, 12, 23, 44, 46, 49, 55], "dialect": 44, "dialog": [2, 26, 51], "diamond": [12, 41, 53], "dict": [63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "dictat": 15, "dictionari": [0, 2, 3, 39, 40, 47, 49, 56, 97, 123], "did": [2, 4, 5, 6, 7, 23, 26, 39, 40, 42, 46, 47, 49, 50, 53, 109, 121, 122, 123], "dideoxymannos": 12, "didn": 22, "diederich": [0, 3, 7, 49], "dien": 12, "differ": [0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 13, 17, 18, 19, 21, 23, 24, 25, 26, 27, 29, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 50, 51, 55, 56, 71, 72, 75, 77, 122, 125, 128], "difference_sigma": 49, "differenti": [0, 3], "difficult": [2, 42], "difficulti": 12, "diffract": [2, 3, 5, 6, 7, 8, 9, 12, 15, 23, 30, 34, 38, 39, 40, 42, 46, 47, 50, 51, 61, 89, 121, 133], "diffractionexperi": 2, "diffus": [7, 12, 49], "difluoroethylglycin": 12, "difluorophenylmethyl": 12, "digit": [2, 4, 6, 7, 17, 26, 38, 40, 44, 45, 50], "dihedr": 6, "dihydroquinoxalin": 12, "dihydrouridin": 8, "dihydroxyglutar": 12, "dikinas": 12, "dilut": [4, 6, 49], "dim": 5, "dimens": [0, 2, 12, 27, 49], "dimension": [0, 3, 6, 23, 26], "dimer": 12, "dimethylguanosin": 8, "dimethylphenyl": 12, "dimmer": 7, "dimn": 42, "dimper": 0, "dimpl": [4, 39, 50], "dioateisomeras": 12, "dioxygen": [8, 47], "dip": [4, 5, 7, 50], "diphosphatas": 12, "dir": [40, 52, 55], "direct": [0, 1, 2, 3, 4, 5, 7, 8, 9, 12, 14, 15, 17, 18, 21, 23, 24, 27, 29, 30, 41, 42, 44, 46, 47, 48, 49, 50, 57, 68, 72, 90, 93, 96, 101, 109, 135], "direct_beam": [5, 49], "direct_beam_i": [1, 2], "direct_beam_x": [1, 2], "direct_beam_x_pxl": [108, 109], "direct_beam_y_pxl": 109, "direction_of_detector_i": 49, "direction_of_detector_x": 49, "directli": [0, 2, 4, 5, 6, 7, 14, 15, 17, 18, 22, 23, 25, 26, 29, 38, 39, 40, 44, 46, 47, 49, 50, 52, 62], "directori": [2, 9, 12, 13, 19, 24, 25, 26, 36, 38, 42, 43, 44, 45, 46, 51, 52, 53, 55, 56, 59, 60, 72], "dirti": 49, "disabl": [1, 2, 4, 5, 6, 7, 18, 24, 26, 27, 42, 49, 50, 57, 71, 90, 92, 134], "disagr": [2, 4, 7, 12, 41, 49, 110], "disagre": [4, 6, 7, 8, 23, 39, 42, 49], "disagreement_pxl": 110, "disappear": [45, 49], "disc": 6, "discard": [0, 2, 4, 5, 6, 7, 15, 42, 44, 49, 101, 134], "disciplin": [0, 3], "disclaim": [17, 29], "disconnect": [2, 27], "discount": 5, "discov": [5, 12], "discoveri": 23, "discrep": 6, "discret": [4, 5, 7, 11, 23, 42, 47, 48], "discrimin": [4, 5, 46], "discriminatori": 29, "disjoint": 9, "disk": [2, 4, 5, 6, 7, 8, 9, 12, 13, 23, 24, 25, 26, 27, 36, 38, 40, 42, 44, 45, 47, 49, 50, 59, 101], "diskquotaexceed": 24, "disord": [5, 12, 49], "disp": 46, "dispatch": [23, 46, 53], "dispers": [0, 5, 8], "displac": [0, 4, 5, 8, 49, 77, 107], "displai": [0, 2, 12, 17, 29, 51, 65], "disposit": [0, 3, 4, 7, 23, 47, 50, 121], "disprov": 7, "disput": 12, "dissect": 0, "dist": [9, 56], "dist_ewald": 1, "distanc": [0, 1, 2, 3, 4, 6, 7, 8, 11, 12, 21, 23, 25, 26, 27, 30, 38, 39, 41, 42, 44, 47, 48, 49, 50, 56, 68, 96, 107, 109, 110, 127, 128], "distance_mm": 127, "distinct": [6, 7, 11, 21, 23, 30, 39, 49, 55], "distinguish": [0, 1, 2, 4, 6, 7, 12, 29, 49], "distl": 0, "distort": [6, 44, 49], "distrib": 0, "distribut": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 17, 19, 24, 26, 29, 36, 37, 43, 45, 46, 47, 48, 49, 53, 59, 62], "distro": [2, 36], "distrust": 5, "disturb": [6, 7, 50], "disulfid": [8, 12], "dithiothreitol": 12, "dittrich": [0, 8], "diverg": [0, 6, 7, 8, 50], "divert": 51, "divid": [0, 4, 5, 6, 7, 8, 13, 15, 39, 40, 42, 46, 49, 55], "divis": [0, 2, 4, 8, 21], "divisor": [5, 7, 46], "djfjoch_install_driver_sourc": 9, "djfjoch_macos_signing_ident": 26, "djfjoch_rugnux_onli": [43, 45], "djfjoch_use_cuda": [2, 26], "djfjoch_viewer_build": [9, 59], "djfjoch_writer_onli": 9, "dkm": [2, 9, 28, 36, 37], "dl380": 22, "dll": [26, 36, 40, 52], "dma": [19, 20], "dmax": [42, 47, 49], "dmesg": [9, 45], "dmg": [26, 36, 59], "dmin": [42, 47, 49], "dmm": [7, 42], "dmmpa": 12, "dmpe": 12, "dmso": [8, 47], "dna": [0, 8, 12, 47], "dnba": 12, "dnf": [2, 9, 19, 37, 43, 45], "do": [0, 2, 3, 4, 5, 6, 7, 8, 9, 12, 13, 21, 22, 23, 25, 26, 29, 38, 39, 42, 44, 45, 46, 47, 49, 51, 53, 62, 64, 92, 134], "doc": [2, 36, 42, 45, 53], "doc_check": [12, 13], "dock": [2, 26], "dockabl": 2, "docker": 2, "document": [0, 1, 2, 3, 5, 11, 14, 16, 17, 23, 27, 29, 31, 32, 36, 51, 68], "dodson": [0, 3, 8], "doe": [0, 1, 2, 3, 5, 6, 8, 9, 11, 12, 13, 14, 17, 21, 23, 24, 25, 26, 27, 29, 30, 36, 38, 39, 41, 42, 44, 45, 46, 47, 48, 49, 50, 53, 55, 56, 57, 61, 71, 96, 101, 109, 110, 119, 128], "doesn": [2, 9, 10, 18, 22, 24, 33, 62, 71, 92, 96], "doi": [0, 3, 8, 12, 13, 28, 34, 38, 40, 49, 55], "domain": [0, 2, 3, 4, 6, 7, 8, 12, 29, 39, 40, 42, 47, 49, 50], "domin": [2, 5, 6, 7, 55], "don": [2, 6, 71, 92], "donat": [0, 8], "done": [2, 4, 5, 7, 9, 15, 19, 20, 21, 23, 38, 39, 42, 46, 49, 62, 68, 71, 96, 127, 134], "donor": [0, 8, 47, 49], "donor_acceptor": 49, "dori": 12, "dose": [0, 2, 4, 7, 12, 42, 46, 49, 50], "dosimetr": 0, "dot": [6, 7], "doubl": [1, 2, 4, 5, 6, 7, 8, 12, 21, 25, 26, 40, 44, 49, 55, 68, 133], "doubled_cell_adopt": 49, "doubled_cell_decis": 49, "doubled_cell_other_cc_half": 49, "doubled_cell_other_cel": 49, "doubled_cell_other_d_min": 49, "doubled_cell_other_fil": 49, "doubled_cell_other_r_fre": 49, "doubled_cell_other_space_group": 49, "doubled_cell_rise_read_on": 49, "doublet": 7, "doubt": [29, 41, 49], "down": [0, 2, 4, 5, 6, 7, 12, 13, 23, 26, 40, 41, 42, 46, 47, 48, 49, 50, 56], "down_weight": 49, "downgrad": [7, 23, 25, 49, 50, 121, 125], "download": [2, 9, 12, 13, 23, 26, 36, 38, 39, 40, 44, 45, 47, 52, 56, 61], "downstream": [1, 2, 4, 5, 6, 7, 15, 23, 24, 25, 28, 29, 38, 44, 46, 49, 50, 53], "downward": [2, 7, 11], "doyl": [0, 3], "dozen": [5, 7, 8, 49], "dppe": 12, "dr": 56, "dracut": 9, "drag": [4, 26, 36, 49, 59], "draw": [0, 2, 3, 4, 5, 7, 8, 21, 26, 38, 46, 47, 49], "drawn": [0, 2, 4, 5, 8, 21, 26, 38, 42, 47, 49, 50], "drew": 49, "drift": [6, 7, 8, 39, 40, 49], "driftless": 6, "drive": [4, 6, 7, 26, 42], "driven": [4, 7, 15, 26, 38, 47], "driver": [2, 26, 28, 37, 38, 40, 43, 45, 52, 54, 58, 59], "drop": [0, 2, 4, 5, 6, 7, 8, 12, 23, 24, 25, 27, 36, 38, 40, 42, 46, 49, 50, 51, 55, 71], "drop_cach": 40, "drown": 6, "dry": [0, 24], "dsba1": 12, "dt": [8, 21], "dtt": 12, "dtype": 33, "duan": [0, 28, 34], "due": [2, 14, 24, 101, 134], "duma": [0, 3], "dummi": 53, "dump": [24, 42], "duplex": 12, "duplic": [2, 23], "durabl": 29, "durat": 25, "duration_": 126, "dure": [0, 1, 2, 4, 7, 9, 14, 23, 24, 25, 28, 33, 34, 40, 43, 45, 56, 57, 65, 68, 69, 71, 93, 103, 134], "durin": [23, 53, 55], "dwell": 29, "dworkowski": 34, "dx": 21, "dxtbx": [0, 11, 23], "dy": 21, "dyn": [0, 34], "dynam": [2, 8, 29, 36], "dz": 21, "dzlib_root": 52, "d\u00b2": [42, 49], "d\u00e9termin": [0, 3], "e": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 15, 16, 22, 23, 24, 25, 26, 29, 38, 39, 41, 42, 44, 46, 47, 50, 55, 62, 68, 71, 96, 97, 101, 119, 120, 121, 122, 126, 131, 132, 133, 134], "e05421": 0, "e07": 12, "e1277": 13, "e192n": 12, "e1m": 25, "e2": 12, "e222q": 12, "e419a": 12, "e504a": 12, "e9m": 2, "e_": [4, 8], "e_b": 8, "e_c": 4, "e_calc": 49, "e_o": 4, "e_ob": 49, "each": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 13, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25, 26, 27, 28, 29, 36, 37, 38, 39, 40, 41, 43, 44, 45, 46, 47, 48, 49, 50, 52, 55, 56, 57, 59, 68, 70, 71, 77, 93, 96, 101, 107, 110, 125, 134], "earli": [2, 5, 7, 8, 38, 49, 125], "earlier": [2, 4, 5, 6, 8, 17, 19, 25, 27, 29, 39, 40, 42, 47, 49, 50], "earn": 6, "easi": 12, "easier": 2, "easili": [12, 17], "eastern": 30, "eavesdrop": 51, "ebi": [0, 56], "echelmei": 13, "echo": [5, 6, 37, 40, 51], "echol": [0, 8], "ed": [0, 3], "edg": [0, 2, 3, 4, 5, 6, 7, 8, 11, 12, 14, 15, 21, 23, 33, 40, 42, 46, 49, 50, 53, 55, 134], "edinburgh": [0, 3], "edit": [8, 12, 26, 40, 49], "edmand": [0, 3], "edo": 12, "eec": [0, 3], "effect": [0, 4, 5, 7, 12, 17, 26, 29, 42, 47, 49, 50, 68, 71, 96, 139], "effici": [0, 1, 2, 7, 23, 25, 26, 30, 40, 42, 46, 133], "effort": [22, 29, 51], "efron": 0, "egg": 12, "eguiraun": 34, "eigen": [2, 4, 26, 36, 40, 46, 52, 56], "eigenvalu": [4, 6, 8, 46, 49], "eigenvector": [8, 46], "eiger": [2, 5, 9, 10, 12, 15, 16, 21, 23, 25, 28, 30, 38, 40, 42, 44, 61, 71, 72, 80, 84, 134], "eiger1": 12, "eiger2": [2, 12, 22], "eiger2cbf": 2, "eiger_bit_depth": 80, "eiger_threshold_ke_v": 80, "eiger_threshold_kev": 25, "eight": [4, 5, 7, 8, 12, 25, 27, 44, 46, 49, 50], "eiler": [0, 3, 7], "either": [3, 4, 5, 6, 7, 8, 11, 12, 17, 23, 24, 25, 26, 27, 29, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 53, 56, 63, 71, 72, 91, 101], "el8": 37, "el9": 37, "elapsed_": 125, "electr": 22, "electron": [0, 1, 2, 3, 7, 8, 23, 29, 44, 62, 68, 71, 97], "electron_sourc": [25, 97], "elem_s": 1, "element": [0, 1, 2, 4, 5, 8, 21, 23, 36, 40, 44, 46, 47, 49, 68, 71, 90], "elementari": 0, "elettra": 12, "eleven": [0, 5, 12, 13, 40, 49], "elif": 0, "elig": 4, "elimin": [0, 3, 8], "ell": 4, "ellips": [2, 7], "ellipsoid": [4, 49], "elong": [6, 7, 8, 49], "elonginb": 12, "elonginc": 12, "els": [2, 4, 6, 7, 8, 11, 12, 21, 23, 25, 26, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 51, 59, 68, 108, 123], "elsewher": [5, 6, 26, 39, 40, 47], "elslig": 0, "em": 49, "em87yl": 12, "emax": 0, "emb": 56, "embed": [0, 2, 13, 26, 27, 47, 49, 59], "embl": [0, 12, 44, 56], "embodi": 29, "emit": [2, 5, 6, 7, 49], "empir": [0, 2, 3, 7, 40, 42, 50, 98], "employ": 29, "empt": 6, "empti": [0, 1, 2, 5, 6, 7, 8, 23, 25, 26, 27, 42, 49, 50, 51, 68, 71, 72, 122, 123, 125, 131, 132], "emslei": [0, 3, 8], "enabl": [0, 1, 2, 5, 7, 9, 15, 17, 18, 24, 25, 26, 27, 29, 42, 45, 49, 51, 68, 90, 92, 128, 129, 134, 138, 139], "enantiomorph": [2, 12, 23, 38, 39, 40, 42, 46, 47, 48, 49, 50, 55, 122], "enantiomorph_veto": [47, 49], "encapsul": 55, "encircl": 7, "encod": [1, 2, 23, 33, 37, 44], "encount": [18, 20, 22, 71], "encourag": 23, "encrypt": 51, "end": [2, 4, 5, 6, 7, 8, 9, 12, 17, 20, 21, 23, 24, 25, 26, 27, 29, 30, 36, 37, 38, 39, 40, 42, 44, 45, 46, 48, 49, 50, 51, 52, 53, 56, 57, 71, 93, 101, 123, 125, 126, 128, 134, 140], "end_dat": 1, "end_tim": [1, 23], "end_time_estim": 23, "endfail": 24, "endian": 1, "endo": 12, "endonucleas": 12, "endopeptidas": 12, "endoribonucleas": 12, "endors": 17, "endpoint": [2, 26, 31, 35, 51, 68, 71], "endriss": [0, 3], "ener_lib": 56, "energi": [0, 1, 2, 4, 7, 8, 13, 15, 20, 21, 23, 25, 27, 42, 44, 49, 50, 55, 67, 68, 70, 72, 80, 92], "energy_e_v": 70, "energy_ev": 70, "enforc": [4, 6, 7, 17, 18, 29, 51, 97], "eng": 0, "engag": [1, 2, 6, 7, 50, 133], "engelmann": 27, "engin": [2, 4, 5, 8, 12, 15, 21, 26, 30, 46, 47], "english": 49, "enhanc": [0, 3, 7, 49], "enlarg": 26, "ennifar": [0, 8], "enorm": [4, 30], "enospc": 55, "enospc_shim": 55, "enough": [2, 4, 5, 6, 7, 8, 11, 12, 19, 22, 25, 27, 36, 40, 41, 42, 44, 46, 49, 55], "enoyl": 12, "ensembl": [4, 7, 46], "ensur": [17, 29, 71], "ent": 39, "enter": [0, 4, 5, 6, 7, 8, 29, 42, 44, 47, 49, 56, 62, 71], "enterocolitica": 12, "enterpris": [9, 12, 19, 52], "entir": [6, 7, 12, 17, 29, 51, 52], "entireti": 5, "entiti": [0, 1, 8, 12, 17, 29, 71], "entity_id": 1, "entri": [0, 1, 2, 4, 5, 6, 7, 8, 13, 18, 21, 24, 25, 27, 36, 39, 40, 42, 44, 49, 50, 53, 56, 57, 59, 68, 72, 75, 77, 125], "entry_1": 44, "enum": [2, 27], "enumer": [4, 5, 6, 41, 42, 85], "envelop": 6, "environ": [0, 2, 8, 19, 26, 42, 51, 71], "enzymol": [0, 3, 8], "eof": 46, "epel": 19, "epimeras": 12, "epix": 44, "epor": 12, "epsilon": [2, 4, 7], "equal": [2, 4, 5, 6, 7, 19, 21, 23, 25, 39, 42, 46, 47, 49, 75, 77, 111], "equat": [0, 2, 3], "equip": [1, 14, 18, 60], "equipment_compon": [1, 23], "equival": [0, 2, 4, 5, 6, 7, 8, 11, 17, 19, 23, 24, 26, 29, 39, 40, 46, 47, 49, 50, 51, 68], "eras": 6, "erf": 7, "eriksson": 34, "err": 133, "erreur": [0, 3], "erron": 29, "error": [0, 1, 2, 3, 4, 5, 6, 8, 11, 12, 14, 15, 20, 21, 23, 24, 25, 27, 33, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 50, 53, 55, 56, 65, 68, 71, 81, 101, 107, 109, 125, 127, 133], "error_messag": [2, 85], "error_message_dict": 85, "error_message_from_dict": 85, "error_message_inst": 85, "error_model_a": [2, 7, 49], "error_model_b": 49, "error_model_c": 49, "error_pixel": [23, 101], "error_pixel_count": 1, "error_valu": [1, 2, 23, 53], "errormessag": 62, "errormodelgpu": 21, "escap": [6, 27], "esd": 8, "espac": [0, 12], "especi": [2, 65], "esrf": [0, 5, 12, 21], "essenti": [7, 17, 29, 46, 49], "establish": [0, 2, 4, 12, 25, 42, 49, 71, 125, 128], "estim": [0, 1, 2, 3, 4, 6, 8, 14, 21, 23, 25, 26, 42, 45, 49, 50, 55, 71, 109, 133], "estimatebandwidth": 7, "estimated_twin_fraction_from": [8, 49], "et": [0, 3, 4, 5, 6, 8, 13, 15, 28, 49, 56], "eta": 12, "etc": [9, 19, 20, 25, 37, 62], "eth": [0, 20], "eth_link_count": 88, "eth_link_statu": 88, "ethernet": [0, 14, 18, 20, 22, 57], "ethyl": 12, "ethylen": [8, 12, 47], "etli": 12, "eula": [56, 61], "europ": 30, "european": [0, 2, 13], "euxfel152": 13, "euxfel83": 13, "euxfel_152": 13, "euxfel_83": 13, "ev": [1, 23], "evalu": [0, 2, 3, 4, 5, 7, 8, 11, 15, 21, 42, 49], "evaluatewithrestraint": 21, "evan": [0, 3], "evas": [4, 48, 49], "evdmo1": 12, "even": [2, 4, 5, 6, 7, 17, 23, 24, 29, 40, 42, 49, 50, 134, 136], "evenli": [42, 49], "event": [1, 2, 6, 7, 21, 23, 25, 29, 44, 46, 49, 51, 62, 71, 97], "event_cod": [62, 71], "eventcod": 23, "ever": [2, 4, 5, 6, 7, 12, 29, 36, 45, 46, 47, 49], "everi": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 18, 21, 23, 24, 25, 26, 27, 28, 29, 33, 35, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 48, 49, 50, 51, 53, 55, 57, 61, 68, 71, 90, 96, 97, 109, 124, 125], "everyon": 29, "everyth": [2, 4, 5, 6, 7, 8, 12, 21, 23, 27, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 51, 55, 59, 61, 71], "everywher": [5, 6, 7, 26, 40, 41, 49], "evict": 40, "evid": [0, 2, 4, 5, 6, 7, 8, 12, 38, 42, 46, 47, 49, 50, 61], "evolv": 0, "ewald": [1, 2, 4, 6, 7, 21, 23, 42, 133], "ex": [26, 36, 40, 43, 59], "exact": [0, 1, 4, 6, 7, 11, 12, 13, 16, 21, 23, 29, 39, 40, 42, 49, 55], "exactli": [1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 14, 21, 23, 24, 25, 27, 30, 38, 39, 41, 44, 45, 46, 47, 49, 50, 55, 68, 70, 109], "exampl": [0, 1, 2, 8, 9, 11, 15, 19, 23, 25, 27, 29, 35, 38, 40, 45, 46, 49], "exce": [4, 5, 6, 7, 8, 12, 40, 42, 49, 50, 53], "exceed": [14, 24], "excel": 0, "except": [1, 5, 6, 8, 12, 15, 17, 23, 24, 26, 36, 39, 40, 47, 49, 50, 56, 62, 71], "excess": [2, 5, 6, 7, 21, 49], "exchang": [8, 20], "excillum": 12, "excit": [2, 4, 5, 6, 21, 42], "excitation_error": 23, "excl": [1, 15], "exclud": [0, 1, 2, 4, 5, 7, 8, 15, 17, 23, 24, 29, 37, 42, 49, 53, 55], "exclus": [0, 5, 7, 8, 17, 29, 42, 49], "excurs": 4, "excus": 29, "execut": [2, 14, 29, 36, 38, 43, 45, 55, 56, 62, 71, 96], "exemplari": 17, "exercis": [12, 17, 29, 40, 55, 57], "exfiltr": 51, "exhaust": [3, 24], "exhibit": 12, "exist": [1, 2, 4, 5, 6, 7, 8, 23, 25, 26, 27, 36, 39, 42, 46, 47, 49, 53, 55, 87], "exit": [2, 7, 27, 38, 40, 41, 45, 46, 49, 109], "exp": [0, 4, 5, 7, 8, 21, 42, 46, 47, 49], "exp_2": 6, "expand": [0, 12, 40, 44, 49], "expans": [0, 3, 58], "expect": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 20, 22, 23, 24, 29, 36, 40, 42, 45, 46, 49, 50, 68, 71, 88, 101, 134], "expected_collection_": 125, "expens": [2, 17, 40], "experi": [0, 1, 2, 3, 6, 12, 18, 23, 38, 39, 40, 41, 49, 51, 60, 68, 93, 101], "experiment": [1, 2, 3, 4, 6, 10, 28, 39, 42, 44, 47, 49, 52, 68, 71], "experiment_group": [1, 27, 68, 101], "experiment_typ": 49, "experimental_coord": 71, "expert": 0, "expir": 2, "explain": [2, 4, 5, 6, 8, 9, 12, 13, 16, 29, 33, 38, 40, 47, 49, 50, 55, 61], "explan": [2, 42], "explanatori": 49, "explicit": [2, 5, 7, 21, 42, 44], "explicitli": [0, 1, 2, 17, 23, 29, 42, 51, 62], "explor": [26, 38], "expon": 4, "exponenti": [2, 7, 8], "export": [2, 4, 6, 7, 12, 38, 40, 42, 45, 50], "expos": [2, 5, 11, 23, 25, 31, 49, 51], "exposur": [1, 2, 4, 5, 23, 41, 49, 50, 80, 92], "express": [0, 2, 5, 6, 7, 14, 16, 17, 26, 29, 40, 42, 46], "expressli": 29, "expt": 44, "exptim": 23, "ext": 8, "extend": [0, 1, 2, 4, 5, 6, 7, 12, 13, 20, 23, 29, 40, 42, 49, 50, 55, 63, 71, 92, 134], "extend_rot": 49, "extens": [0, 1, 2, 4, 27, 29, 39, 44, 49], "extent": [4, 5, 6, 17, 29, 96], "extern": [1, 2, 6, 7, 8, 23, 39, 40, 52, 53, 54, 55, 71, 101], "external_test_data": 0, "external_test_data_stil": 0, "externalproject": 56, "extinct": [2, 4, 5, 7, 41], "extinguish": [2, 4, 5, 6, 49], "extra": [1, 2, 4, 5, 6, 7, 8, 9, 23, 26, 38, 40, 42, 46, 47, 49, 51, 99], "extra_lattice_": 49, "extra_lattice_count": 49, "extra_lattice_intensity_pct": 49, "extracellular": 12, "extract": [2, 4, 5, 6, 12, 13, 36, 43, 49, 53, 57], "extractor": [0, 5, 21], "extrapol": [2, 4, 7], "extrem": [4, 5], "ey": 50, "e\u00b2": [0, 4, 49], "f": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 26, 27, 28, 29, 34, 38, 39, 40, 42, 44, 46, 47, 49, 50, 71], "f1": [0, 12, 38, 42, 47, 49, 50, 56], "f16l": 12, "f2": [42, 49], "f432": 2, "f5": 2, "f8": 46, "f99": 12, "f_": [4, 7, 8], "f_1": 4, "f_c": 4, "f_calc": [21, 49], "f_j": 7, "f_mask": 21, "f_mea": 40, "f_meas_au": [2, 4, 7], "f_meas_sigma_au": 7, "f_model": 21, "f_o": [4, 8], "f_ob": 49, "fab": 12, "fabl": 0, "face": [7, 12, 41, 50, 51, 121], "facil": [1, 2, 5, 12, 13, 22, 23, 29, 39, 44, 51], "facilit": 9, "fact": [4, 6, 7, 27, 47, 49], "factor": [0, 1, 2, 3, 5, 6, 8, 20, 21, 23, 25, 26, 38, 39, 40, 42, 45, 46, 49, 50, 55, 63, 68, 122, 125, 133], "factori": 12, "factual": 17, "fad": [8, 12, 47], "fade": 46, "fail": [2, 4, 5, 6, 7, 12, 17, 19, 21, 24, 25, 27, 29, 36, 38, 39, 40, 42, 45, 46, 47, 48, 49, 53, 55, 68, 123, 125, 127, 131], "failur": [2, 4, 6, 12, 27, 29, 40, 49], "faint": 5, "fair": [17, 29, 40], "fairli": 4, "falciparum": 12, "fall": [0, 2, 3, 4, 5, 6, 7, 8, 21, 24, 26, 36, 38, 42, 45, 47, 49, 50], "fallback": [2, 4, 5, 6, 42, 98], "fallen": [5, 7], "falloff": [7, 40, 49], "fals": [0, 1, 2, 3, 4, 5, 6, 7, 24, 25, 26, 38, 41, 42, 46, 49, 63, 68, 71, 80, 87, 90, 92, 96, 97, 99, 109, 123, 128, 134], "false_pixels_per_fram": [5, 134], "falson": 12, "famili": [6, 12, 29], "famou": 30, "faq": 17, "far": [2, 4, 5, 6, 7, 8, 21, 22, 25, 26, 38, 39, 40, 41, 42, 43, 45, 46, 48, 49, 50, 64, 71, 107, 109, 110, 122, 133, 134], "farther": [7, 49], "fashion": 29, "fast": [0, 1, 2, 3, 4, 5, 8, 11, 21, 22, 23, 25, 36, 40, 42, 44, 45, 52, 56, 61, 68, 75, 77, 90], "fast2sum": 0, "fast_axi": [1, 25, 42, 44, 68, 75, 77], "fast_float": 56, "fast_pixel_direct": [11, 23, 44], "fast_step": [25, 44, 77], "faster": [2, 4, 7, 25, 49, 98], "fatal": [6, 24, 27], "fatbin": 36, "fault": [2, 36, 40, 46, 49], "favor": 29, "favour": [7, 8, 12, 23, 40, 51], "fc": [0, 2, 4, 39, 47], "fcalc": 40, "fdd2": [4, 49], "fdhmp": 12, "fe": [8, 47], "feasibl": 23, "featur": [0, 1, 2, 3, 4, 5, 7, 8, 15, 24, 26, 29, 49, 58, 60], "fed": [4, 7], "fee": [17, 29], "feed": [4, 5, 6, 7, 21, 23, 39], "feedback": [0, 2, 3, 4, 7, 21, 22, 24, 28, 34, 36, 45, 49, 52, 56], "feildel": 56, "felix": 27, "fell": 49, "femtosecond": [0, 3], "fen1": 12, "feng": 0, "ferricyanid": 12, "ferroelast": 7, "ferroelectr": 7, "fest": 0, "fetch": [2, 26, 28, 36, 40, 43, 59, 125], "fetchcont": 56, "few": [1, 2, 4, 5, 6, 7, 8, 12, 23, 25, 28, 30, 40, 42, 43, 44, 46, 47, 49, 50, 51, 71, 109, 134], "fewer": [2, 4, 5, 6, 7, 8, 25, 42, 45, 47, 49], "fewest": 7, "fe\u00b2": 8, "fe\u00b3": 8, "ffbidx": [0, 1, 2, 3, 6, 21, 23, 36, 38, 42, 45, 48, 50, 95, 96], "ffbidxindexercpu": [6, 56], "fft": [0, 1, 2, 3, 4, 5, 8, 21, 23, 25, 36, 42, 45, 46, 47, 48, 50, 95, 96], "fft3d": 6, "fft_high_resolution_a": 96, "fft_max_unit_cell_a": [6, 96], "fft_min_unit_cell_a": [6, 96], "fft_num_vector": 96, "fftindex": 2, "fftindexergpu": 21, "fftw": [0, 1, 2, 4, 5, 21, 23, 26, 36, 42, 45, 52, 55, 56, 95], "fgen": 57, "fibcd1": 12, "fiber": 18, "fibonacci": 6, "fibrinogen": 12, "fibronectin": 12, "field": [0, 1, 2, 7, 11, 12, 24, 25, 26, 27, 40, 41, 42, 44, 46, 50, 51, 53, 60, 68, 85, 108, 109], "fieschi": 12, "fifo": [2, 20, 24, 93], "fifteenth": 8, "fifth": [0, 4, 5, 7, 49], "figur": [0, 2, 4, 6, 8, 40, 47, 49], "filament": 12, "file": [1, 2, 4, 5, 6, 7, 8, 9, 11, 14, 17, 21, 24, 25, 26, 28, 29, 33, 34, 36, 37, 40, 41, 42, 45, 47, 48, 49, 51, 53, 54, 55, 57, 58, 59, 61, 62, 68, 71, 72, 75, 77, 86, 87, 99, 109, 110, 128, 129, 136, 138, 139, 140], "file_beam_x_pxl": 127, "file_beam_y_pxl": 127, "file_clos": [24, 25], "file_direct_beam": 49, "file_distance_mm": 127, "file_format": [1, 23], "file_nam": 23, "file_numb": [27, 71], "file_prefix": [1, 24, 25, 27, 68, 71, 101, 132], "file_tim": 23, "file_writ": [62, 71, 99], "file_writer_format": 2, "file_writer_set": [71, 87, 100], "file_writer_settings_dict": 87, "file_writer_settings_from_dict": 87, "file_writer_settings_inst": 87, "filenam": [26, 27, 36, 68], "filesystem": [2, 27, 51], "filewrit": 53, "filewriterformat": [62, 87], "filewriterset": [62, 71, 99, 100], "filip": 62, "fill": [0, 2, 4, 5, 6, 7, 8, 23, 25, 26, 27, 39, 42, 46, 49, 50, 71], "fill_missing_f_ob": 4, "filter": [0, 1, 2, 4, 5, 6, 8, 12, 13, 21, 23, 44, 46, 68, 96, 101], "filterspotsbycount": 6, "final": [2, 7, 8, 24, 25, 29, 30, 42, 47, 48, 49, 71, 136], "finalis": [0, 2, 23], "finalist": [2, 4, 42], "find": [1, 2, 3, 4, 6, 7, 8, 16, 21, 25, 26, 27, 28, 29, 34, 36, 38, 39, 40, 44, 45, 46, 47, 48, 49, 50, 55, 57, 59, 61, 62, 68, 71, 134], "find_blobs_by_flood_fil": 8, "find_peaks_hol": 46, "find_twin_law": 4, "findabl": [0, 23], "finder": [0, 2, 5, 6, 7, 8, 15, 20, 21, 25, 42, 44, 49, 50], "fine": [4, 5, 6, 7, 8, 12, 21, 23, 25, 36, 42, 49, 96, 111, 125], "finer": [0, 4, 5, 8, 21, 41, 42, 47, 49], "finest": [0, 4, 7, 8, 42, 49], "finger": 12, "finisar": 18, "finish": [1, 2, 4, 5, 8, 17, 25, 26, 27, 38, 40, 49, 50, 57, 71, 140], "finit": [2, 7], "fire": [2, 4, 6, 7, 25, 26, 27, 47, 49, 131], "firewal": [20, 51], "firm": 49, "firmwar": [2, 10, 25, 28, 36, 37, 44], "first": [0, 1, 2, 4, 5, 6, 7, 8, 9, 12, 13, 17, 19, 21, 23, 24, 25, 26, 27, 28, 29, 33, 36, 38, 39, 42, 43, 44, 46, 47, 48, 49, 52, 53, 56, 57, 59, 61, 68, 71, 121, 122, 123, 125, 126, 127, 128, 135], "first_imag": [49, 71, 121], "fisher": [0, 3, 7, 49], "fit": [0, 1, 2, 3, 5, 6, 8, 17, 19, 21, 23, 25, 29, 30, 38, 39, 40, 41, 42, 45, 46, 47, 48, 49, 50, 53, 98, 107, 109, 110, 122], "fit_sigma": [109, 122], "fitperframeg": 21, "fitted_resolut": [2, 49], "fitted_resolution_intern": 49, "five": [3, 4, 6, 7, 8, 21, 37, 39, 40, 41, 45, 49], "fix": [0, 2, 3, 4, 5, 6, 8, 12, 15, 18, 20, 21, 23, 24, 25, 27, 29, 36, 38, 39, 40, 41, 42, 45, 46, 47, 49, 50, 55, 56, 80, 96, 97, 109, 128, 134], "fixtur": 55, "fk1": 12, "fkbp12": 12, "fkbp51": 12, "flack": [0, 12, 46], "flag": [0, 1, 2, 3, 4, 5, 6, 8, 9, 12, 20, 21, 23, 24, 26, 33, 36, 38, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50, 53, 55, 68], "flagship": 23, "flank": [1, 5, 7, 23, 42, 49], "flap": 12, "flash": [20, 28], "flat": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 23, 39, 41, 42, 47, 49, 50, 108], "flatfield": 1, "flatfield_appli": 23, "flatfield_en": 1, "flatten": [1, 4, 23, 41, 49], "flattest": 6, "flavour": 37, "flensburg": [0, 3], "flex": [2, 23, 42, 89], "flexibl": [0, 1, 2, 8, 15], "fli": 42, "flight": [1, 2, 23, 27, 42, 46], "flight_corr": 7, "flight_path": [7, 42, 49], "flight_path_wilson_b": [7, 42], "flip": [2, 4, 5, 6, 7, 8, 11, 39, 47, 49, 90], "float": [0, 1, 2, 5, 6, 7, 8, 20, 21, 23, 27, 42, 44, 45, 56, 62, 63, 65, 66, 67, 68, 69, 70, 71, 72, 74, 75, 77, 80, 88, 90, 92, 96, 101, 104, 106, 107, 109, 110, 113, 116, 119, 120, 122, 123, 124, 125, 126, 127, 128, 129, 132, 133, 134, 137], "float32": [1, 13], "float32_to_int16": 13, "flock": 40, "flood": [0, 4, 5, 6, 8], "floor": [2, 4, 5, 6, 7, 8, 42, 46, 48, 49, 50, 55], "flow": [2, 14, 15, 24, 29, 54], "flto": [36, 40], "fluctuat": 7, "fluoresc": [1, 2, 23, 70], "fluorophenyl": 12, "flush": 24, "flux": [1, 2, 7, 21, 42, 68], "flux_peak_to_trough": 49, "fly": [1, 2, 23, 28, 61], "fma": 36, "fmask_kernel": 21, "fmn": [8, 47], "fmt": 12, "fn": 26, "fo": [0, 2], "fob": [39, 42, 47], "focus": [6, 68], "fofc": 71, "fokin": [0, 3, 8], "fold": [0, 1, 2, 3, 4, 6, 7, 8, 12, 23, 26, 39, 40, 42, 47, 49, 133], "folder": [9, 12, 43, 55], "follow": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 14, 15, 16, 19, 20, 21, 22, 23, 24, 26, 27, 28, 29, 33, 36, 37, 38, 39, 42, 44, 46, 49, 50, 51, 56, 58, 59, 60, 61, 62, 68, 71, 97, 138, 139, 140], "follow_up": 2, "fom": 4, "font": [2, 26], "foot": [1, 2, 23, 108], "footprint": [2, 5, 7, 23, 40, 48, 50], "forbackgroundonly_000nn": 12, "forbid": [4, 6, 29, 49], "forbidden": [4, 49], "forc": [2, 4, 5, 6, 7, 9, 23, 25, 26, 29, 42, 46, 47, 49, 50, 55, 63, 128], "force_cpu": [25, 63], "force_stil": [25, 128, 129], "foreground": [2, 26], "foreign": [6, 12, 39, 49], "forev": 6, "forget": 27, "fork": [2, 27, 53], "form": [0, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 16, 17, 23, 27, 29, 30, 39, 42, 44, 46, 47, 48, 50, 51, 56, 60], "formal": [3, 8, 41], "format": [1, 2, 4, 5, 7, 9, 11, 12, 13, 17, 24, 25, 26, 28, 29, 38, 39, 40, 41, 42, 46, 48, 50, 53, 58, 61, 62, 68, 71, 86, 87], "former": [2, 4, 7, 42], "formul": [0, 3, 8, 21], "formula": [2, 7, 15, 23, 46, 50], "forti": 4, "forward": [1, 4, 6, 21, 23, 24, 25, 26, 36, 68, 101, 140], "found": [0, 1, 2, 4, 5, 6, 7, 8, 9, 21, 23, 25, 26, 29, 33, 39, 40, 41, 42, 44, 46, 47, 49, 50, 109, 110, 126, 131], "foundat": [17, 29, 56], "four": [0, 4, 5, 6, 7, 8, 11, 21, 22, 25, 26, 40, 44, 46, 49, 55, 59], "fourier": [0, 3, 4, 6, 8, 21, 46], "fourm": [0, 3], "fourth": [7, 30, 34], "fp": [2, 4, 8, 39, 42, 46, 47], "fpga": [1, 2, 5, 10, 21, 23, 24, 25, 26, 28, 29, 30, 34, 36, 37, 38, 55, 56, 58, 61, 62, 63, 64, 71, 80, 82, 96, 100, 128, 134], "fpga_statu": [62, 71], "fpga_status_get": 62, "fpga_status_inn": [71, 88], "fpga_status_inner_dict": 88, "fpga_status_inner_from_dict": 88, "fpga_status_inner_inst": 88, "fpga_temp_c": 88, "fpga_temp_deg_c": 82, "fpgastatusinn": [62, 71, 100], "fprime": 56, "fr": 12, "frac": [4, 5, 6, 7, 8], "fraction": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 21, 23, 39, 42, 44, 46, 48, 49, 50, 57, 124, 125, 133], "fraction_of_polar": [5, 42], "fractionalis": 2, "fractioncalc": 46, "fragment": [0, 4, 7, 8, 12, 25, 39, 42, 44, 47, 50], "frame": [0, 1, 2, 3, 4, 5, 11, 12, 13, 16, 18, 20, 21, 22, 23, 25, 26, 28, 30, 33, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 57, 59, 61, 67, 68, 71, 72, 75, 77, 80, 91, 96, 120, 124, 125, 127, 133, 134, 139], "frame_gener": 20, "frame_rang": [25, 125], "frame_scal": [25, 125], "frame_seri": 56, "frame_tim": [1, 23, 68], "frame_time_u": [25, 67, 80], "framedisposit": [23, 49], "framedispositioncod": 23, "frames_blank_end": 49, "frames_blank_start": 49, "frames_downgrad": 49, "frames_merg": 49, "frames_reject": 49, "frames_rejected_pct": 49, "framev1": 44, "framework": [0, 26, 36], "francisella": 12, "frau": 30, "free": [0, 1, 2, 3, 5, 6, 8, 12, 13, 17, 21, 23, 24, 25, 29, 38, 39, 40, 42, 45, 46, 48, 49, 50, 51, 55, 61, 97, 107, 123, 124, 125, 140], "free_set_split": [8, 49], "freed": 40, "freedom": [6, 7, 17, 29], "freeli": 6, "freer_flag": [2, 7, 40, 42, 46, 47, 50], "freez": 2, "frei": 56, "french": [0, 2, 3, 4, 8, 30, 38, 40, 42, 46, 47, 48, 49, 50], "frequenc": [0, 2, 3, 6], "frequent": 23, "fresh": [9, 45, 47, 49], "freshli": [36, 43, 45, 51], "friction": 51, "friedel": [0, 2, 4, 6, 7, 21, 38, 40, 42, 46, 47, 49, 50], "friedels_law": [38, 42, 46, 49], "friend": 53, "friendli": [2, 23, 60], "frigo": 56, "fritz": [0, 8], "from": [1, 2, 3, 8, 9, 11, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 31, 33, 34, 35, 36, 37, 38, 39, 40, 42, 44, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 98, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "from_dict": [63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "from_json": [63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "fromcif": 46, "front": [2, 4, 7, 21, 26, 46, 50, 51, 61], "frontend": [0, 2, 5, 28, 36, 37, 51, 52, 61, 99, 100], "frontend_directori": [9, 25, 99], "frow": 30, "frozen": 6, "fructos": 12, "fsc": 49, "fsf": 29, "fucopyranosyl": 12, "fucos": 12, "fucosidas": 12, "fuent": 0, "fulfil": [15, 29], "full": [0, 1, 2, 3, 4, 6, 8, 11, 12, 16, 17, 19, 21, 23, 24, 25, 26, 27, 28, 29, 34, 35, 36, 38, 39, 40, 42, 43, 45, 46, 47, 48, 49, 50, 51, 55, 56, 57, 59, 61, 62, 68, 71, 72, 101, 113], "fulli": [2, 5, 6, 7, 44, 46, 49, 50], "function": [0, 2, 3, 4, 5, 7, 8, 9, 18, 21, 22, 27, 29, 36, 40, 42, 45, 47, 48, 49, 65, 71, 122], "fundament": [5, 6, 29], "furrer": 34, "further": [2, 4, 5, 6, 7, 8, 12, 27, 29, 38, 39, 42, 45, 47, 50, 52, 71], "furthest": 5, "fusarium": 12, "fuse": [2, 5, 12, 48], "fusion": 12, "futur": [2, 14, 20, 29, 96, 134], "fw": 9, "fw_version": 88, "fwhm": [1, 7, 42, 49, 50, 68, 134], "fwt": [4, 8, 39, 47, 71], "fwt_no_fil": [4, 8, 39], "fx": 1, "fy": 1, "f\u00e9raud": [0, 3, 8], "g": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 15, 16, 22, 23, 24, 25, 26, 34, 42, 44, 46, 47, 49, 50, 68, 71, 97, 101, 119, 120, 121, 122, 126, 131, 132], "g0": [20, 33, 80, 92, 103], "g1": [2, 20, 80, 92], "g2": [2, 20], "g491a": 12, "g_": [4, 7], "g_f": 7, "g_i": 7, "ga": 12, "gabi": 56, "gadet": [0, 3], "gael": 56, "gailli": 56, "gain": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 13, 16, 20, 25, 26, 33, 40, 42, 44, 49, 51, 71, 72, 80, 103], "gain_file_nam": [1, 23], "gain_g0_mean": 66, "gain_g1_mean": 66, "gain_g2_mean": 66, "gain_level": 71, "gamma": [1, 6, 27, 38, 42, 137], "gamma_": 7, "gamma_0": 7, "gap": [2, 4, 5, 6, 7, 8, 25, 33, 42, 44, 49, 50, 51, 53, 71, 109, 134, 135], "gap_i": [25, 135], "gap_x": [25, 135], "garbag": 49, "gasparotto": [0, 3, 6, 34], "gate": [2, 4, 5, 6, 7, 8, 12, 42, 46, 49, 55, 83], "gatekeep": 26, "gather": [8, 21], "gaug": [2, 4, 6, 7, 41, 50], "gaussian": [2, 4, 5, 6, 7, 8, 21, 42, 50, 98], "gave": [2, 47, 49], "gavin": 0, "gb": [0, 13, 21, 22, 28, 34, 38, 40, 43, 45], "gb10": [36, 40, 45], "gbit": [14, 18, 22], "gc376": 12, "gcc": [45, 52, 62], "gdap1": 12, "gdp": [8, 47], "gdri_matrix_": 12, "ge": [4, 5, 6, 7], "gem": [0, 3], "geman": [0, 8], "gemmi": [0, 1, 3, 4, 8, 21, 39, 40, 42, 46, 55, 56], "gemmi_gph": [0, 56], "gen11": 22, "gen4": [14, 88], "gen4x8": 9, "gener": [2, 3, 4, 5, 6, 7, 8, 11, 17, 20, 22, 24, 25, 26, 28, 31, 32, 33, 34, 35, 39, 40, 43, 44, 45, 46, 47, 49, 51, 55, 56, 57, 61, 62, 68, 71, 80, 88, 138, 139], "generalis": 7, "genuin": [2, 4, 5, 6, 7, 11, 12, 30, 46, 53], "geom": [2, 6, 13, 38, 42, 44, 50], "geom_refin": 56, "geom_refinement_algorithm": [1, 23, 25, 96], "geometr": [5, 6, 7, 21, 23, 39, 50], "geometri": [1, 2, 3, 4, 7, 12, 13, 21, 23, 25, 26, 40, 41, 47, 48, 49, 50, 53, 54, 57, 69, 71, 89, 108, 109, 110, 127, 135], "geometry_not_converg": 49, "geometry_transform": [25, 92], "geometry_transformation_appli": 23, "geometry_transformation_en": 1, "geomrefinementalgorithm": [62, 96], "geq": 6, "german": 30, "gessing": 0, "get": [2, 4, 6, 7, 8, 11, 18, 25, 29, 30, 39, 40, 45, 46, 47, 49, 51, 61, 71, 80, 134], "get_statistics_data_collect": 35, "getdefaultplotbin": 2, "gfp": 12, "gh1": 12, "gh200": [2, 36, 43, 45, 52], "gh29": 12, "gh99": 12, "gi_sfx": 13, "giardia": 12, "gib": [19, 40], "gigabyt": 40, "gildea": 0, "gilliland": 0, "git": [2, 20, 40, 62], "gitea": [2, 9, 36, 37, 38, 45, 53, 55, 62], "github": [3, 53], "gitlab": 2, "give": [0, 2, 4, 5, 6, 7, 8, 11, 12, 13, 15, 17, 21, 23, 24, 25, 26, 27, 29, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 55, 77, 97, 108, 121], "given": [0, 1, 2, 3, 4, 5, 7, 8, 9, 11, 12, 13, 15, 17, 18, 19, 21, 23, 24, 25, 26, 29, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 52, 57, 61, 68, 71, 80, 92, 96, 109, 122, 123, 124, 133], "gkab1061": 0, "gkab314": 0, "gkad1011": 0, "gkae1148": [0, 8], "gkag120": [0, 8], "gkr900": 0, "gkw1175": 0, "glanc": 50, "glcnac": 12, "glib": 2, "glibc": [36, 40, 43, 45], "glide": [0, 2, 3, 4, 38, 41, 46, 48, 49, 50], "gligorov": [0, 3], "glitch": 7, "glmu": 12, "gln": 8, "glob": [12, 38, 42, 44], "global": [0, 2, 3, 4, 5, 6, 7, 8, 23, 46, 50, 53, 56, 132], "globalphas": [0, 3], "glover": 34, "glu": 8, "glucos": 12, "glucosamin": 12, "glucosidas": 12, "glucosylglycer": 12, "glutam": 12, "glutathion": 12, "glyceraldehyd": 12, "glycerol": [8, 12, 47], "glycin": 12, "glycogen": 12, "glycol": [8, 12, 47], "glycomimet": 12, "glycosaminoglycan": 12, "glycosom": 12, "glyoxyl": 12, "gmha": 12, "gmp": [8, 12, 47], "gn": 30, "gnocchi": 30, "gnome": 26, "gnu": [17, 52, 61], "gnuplot": 50, "go": [2, 4, 5, 6, 8, 21, 25, 38, 40, 42, 45, 46, 49, 50, 128], "goal": 23, "goe": [2, 4, 5, 6, 7, 8, 21, 25, 26, 28, 38, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 61, 68, 71, 75, 96], "gol": 12, "golden": 6, "golub": [0, 3, 4], "gone": [5, 41, 45, 49, 109], "gonio_scal": 49, "goniomet": [0, 1, 2, 6, 7, 11, 23, 25, 26, 38, 42, 44, 46, 48, 49, 50, 53, 68, 69, 71, 90, 128], "goniometer_rotation_scal": 6, "goniometer_rotation_scale_suspect": 6, "goniostat": 1, "gonzalez": 34, "good": [0, 3, 4, 5, 6, 7, 17, 40, 42, 44, 47, 49, 55, 71, 109], "googl": [0, 2, 56], "gorgisyan": 34, "got": [2, 38, 50, 107, 125], "gotthard": [0, 34], "govern": [4, 17, 29, 42, 45, 49], "gp41": 12, "gpgcheck": 37, "gphl": 53, "gpl": [56, 61, 62], "gplv3": [2, 29, 45, 49], "gpt": [0, 2], "gpu": [0, 2, 3, 4, 6, 7, 9, 10, 15, 23, 25, 26, 28, 30, 34, 38, 39, 42, 43, 47, 48, 49, 50, 52, 54, 55, 56, 57, 59, 61, 65, 123, 127, 128], "gpu_count": [2, 49, 65], "gpu_oth": 40, "gpulock": 40, "grabowski": 0, "grace": 40, "gracefulli": [2, 71], "grade": [4, 22, 49, 50], "gradient": [0, 3, 6, 7, 8, 21, 47], "gradual": 2, "graduat": [0, 3], "grai": 0, "grain": [4, 49], "grant": [17, 29, 45], "graph": 26, "graphic": [0, 2, 3, 22], "grati": 29, "gratuit": 18, "graub\u00fcnden": 30, "graviti": 11, "grayscal": 1, "gra\u017euli": 0, "great": [5, 30], "greater": 12, "greatest": 29, "greedi": 4, "green": [18, 25, 26], "grei": [2, 26, 50], "grep": [9, 49, 50], "greppabl": 49, "grew": 7, "grid": [0, 1, 2, 3, 4, 5, 6, 7, 8, 21, 23, 25, 42, 47, 49, 50, 51, 55, 61, 68, 71, 90, 119, 133], "grid_scan": [1, 23, 68, 90], "grid_scan_dict": 90, "grid_scan_from_dict": 90, "grid_scan_i": 23, "grid_scan_inst": 90, "grid_scan_x": 23, "grid_um": 105, "gridscan": [62, 68], "grimm": 34, "grischun": 30, "griseoviridi": 12, "grl": 12, "gro": 12, "gross": [0, 2, 3, 8], "ground": [4, 13], "group": [1, 2, 3, 5, 6, 8, 9, 10, 13, 19, 21, 24, 25, 26, 27, 36, 39, 40, 42, 44, 46, 48, 50, 51, 54, 55, 56, 61, 68, 71, 101, 122, 123, 125, 126], "grow": [2, 4, 5, 6, 7, 23, 40, 42, 48, 49, 50, 107], "grown": [5, 7], "growth": [7, 12, 40, 42], "gruber": [0, 3, 6], "gruen": 2, "grx2": 12, "gsh": 12, "gstf8": 12, "gt": 61, "gtp": [8, 47], "guanin": 12, "guarante": [1, 24, 29], "guard": [4, 5, 6, 7, 48, 49, 50, 51], "guennebaud": 56, "guess": [6, 8, 26, 39, 40, 46], "gui": [2, 26, 29, 46], "guid": [0, 8, 9, 12, 14, 28, 40, 59, 61], "guidelin": [0, 3, 8], "guillaum": 0, "guttur": 30, "gz": [5, 13, 40, 44, 47], "gzip": [2, 12, 25, 38, 39, 42, 44, 47, 71], "g\u00f6tz": 0, "h": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 21, 23, 25, 26, 27, 34, 39, 41, 42, 44, 46, 49, 50, 51, 55, 56, 57, 64, 75, 77, 134], "h00": 4, "h0l": 4, "h123r": 12, "h2o": [0, 3], "h2u": [8, 47], "h4": 12, "h5": [2, 4, 5, 6, 7, 12, 13, 25, 26, 27, 38, 39, 40, 41, 42, 43, 44, 47, 49, 50, 57, 59, 87], "h5py": 13, "h9n2": 12, "h_f": 6, "h_i": 6, "ha": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 35, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 49, 50, 51, 52, 53, 55, 57, 59, 60, 61, 71, 80, 97, 109, 125, 128, 131, 139], "had": [1, 2, 4, 5, 6, 7, 8, 12, 23, 26, 27, 29, 40, 45, 47, 49], "half": [0, 2, 3, 4, 5, 6, 7, 8, 11, 12, 21, 25, 26, 28, 38, 39, 42, 45, 47, 48, 49, 50, 56, 72, 80, 124, 134], "halid": [0, 8], "hall": [0, 46], "hallucin": 6, "halo": [7, 42], "halv": [4, 5, 6, 7, 8, 12, 30, 45, 49, 50], "hamburg": [12, 44], "hammerslei": 0, "han": 0, "hand": [0, 2, 4, 5, 6, 7, 12, 19, 23, 26, 27, 38, 39, 40, 41, 42, 44, 46, 47, 49, 50, 51, 55, 56], "handbook": [0, 8], "handed": 4, "handl": [2, 4, 6, 7, 9, 10, 12, 15, 18, 20, 26, 34, 38, 42, 46, 47, 49, 50, 51, 55, 86], "handov": 46, "hang": 2, "hantk": 0, "happen": [0, 2, 3, 4, 6, 7, 14, 15, 23, 27, 33, 39, 46, 48, 49, 50, 58, 68, 71], "happili": [42, 53], "har": [14, 18, 55], "hard": [0, 3, 7, 8, 23, 24, 30, 40, 50, 136], "hardcod": 2, "harden": [2, 51], "harder": 42, "hardest": 4, "hardli": 49, "hardwar": [0, 2, 5, 28, 34, 36, 38, 55, 61], "harm": [7, 49], "harmless": [2, 4, 6, 7, 17], "harmon": [0, 2, 3, 5, 6, 7, 42, 48, 49, 50], "harmonic_contamin": 49, "hartlein": 12, "harvard": 0, "has_error_text": 24, "hash": [0, 2, 6, 7, 8, 26, 40, 47], "hassiacum": 12, "haswel": [36, 43], "hat": [6, 7, 9, 52], "hattn": 0, "have": [2, 4, 5, 6, 7, 8, 9, 11, 12, 14, 15, 17, 18, 19, 21, 22, 23, 25, 26, 27, 29, 36, 38, 39, 40, 41, 42, 43, 45, 46, 47, 48, 49, 50, 51, 53, 55, 62, 71, 92, 96, 104, 109], "have_vm_flags_set": 19, "haven": 18, "hawick": 0, "hbm": 14, "hbm_temp_c": 88, "hcl": 12, "hcov": 12, "hdac6": 12, "hdd": 40, "hdf": [44, 56], "hdf5": [0, 1, 2, 3, 5, 6, 9, 11, 12, 13, 24, 25, 26, 28, 36, 37, 38, 39, 42, 44, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 61, 68, 86, 93, 94, 101], "hdf5_source_data": 23, "hdf5_version": 23, "hdf5datafil": 23, "hdf5datafileplugin": 23, "hdf5nxmx": 23, "hdf5plugin": 13, "hdr": 26, "he": 42, "head": [1, 2, 7, 23, 38, 119], "headd": [0, 8], "header": [0, 1, 2, 3, 5, 6, 7, 12, 13, 16, 25, 26, 38, 40, 41, 42, 44, 46, 49, 50, 51, 53, 56, 62, 68, 109], "header_appendix": [1, 27, 68], "header_distance_mm": 109, "headlin": [4, 7], "headroom": 22, "healthi": [4, 49], "heartbeat": [24, 27, 136], "heavi": [0, 3, 4, 8, 39, 40, 49], "heavier": [4, 7, 8, 46], "heaviest": 8, "hec": [8, 47], "height": [1, 4, 8, 11, 25, 33, 39, 44, 49, 74, 75, 77], "held": [0, 2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 25, 26, 27, 38, 40, 42, 44, 47, 48, 49, 50, 55, 127], "helic": [1, 12, 23, 30, 119], "helical_step": 1, "helical_step_um": 119, "helium": [0, 2, 7, 42], "help": [2, 4, 6, 7, 19, 26, 36, 50], "hem": [8, 47], "heme": [8, 40, 47], "hen": [0, 8, 12], "henc": [7, 39], "hendrickson": [0, 3], "hennequin": [0, 3], "hep": 0, "hepi": 12, "hepii": 12, "herbst": [0, 8], "herbstein": [0, 49], "here": [0, 1, 3, 4, 5, 6, 7, 8, 12, 23, 24, 25, 26, 36, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 54, 56, 71, 109, 122], "hereaft": 29, "herebi": 17, "heritag": 30, "hermann": [1, 2, 4, 23, 38, 42], "hero": 2, "hessian": [0, 3, 8], "het_flag": 1, "hetatm": 47, "hex": [2, 26], "hexagon": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 23, 41, 42, 49, 133], "hexapeptid": 12, "hf": 12, "hhai": 12, "hhmm": 40, "hi": [0, 8, 12, 47], "hide": [2, 5, 6, 7, 44, 46, 49], "hideabl": 2, "high": [0, 2, 3, 4, 5, 6, 7, 8, 11, 12, 16, 21, 23, 24, 25, 29, 30, 38, 40, 42, 46, 49, 50, 51, 53, 55, 57, 62, 63, 71, 80, 82, 96, 111, 122, 124, 125, 134], "high_flank": 49, "high_q_recip_a": 63, "high_q_recipa": 2, "high_res_gap_q_recip_a": 134, "high_resolution_limit": [2, 134], "high_resolution_limit_for_spot_count_low_r": 134, "high_voltage_v": [25, 72, 82], "higher": [2, 4, 5, 6, 7, 27, 39, 42, 46, 47, 49, 50, 103], "highest": [1, 2, 4, 5, 6, 7, 21, 23, 24, 26, 30, 36, 42, 49, 55, 63, 68, 71, 120, 122], "highli": [0, 1, 3, 68], "highlight": 2, "hildenborough": 12, "hing": 8, "hinger": 34, "hirata": 0, "hiros": 56, "hirsch": 56, "hirshfeld": [0, 8], "hisn": 8, "hisn3": 12, "hisn5": 12, "hisnd": 8, "histogram": [0, 1, 2, 7, 16, 21, 25, 96], "histor": 7, "histori": [1, 2, 7, 25, 39, 47, 71], "hit": [5, 13, 25, 42], "hiuas": 12, "hiv": 12, "hk": 5, "hkl": [0, 2, 4, 5, 6, 7, 21, 23, 26, 38, 39, 40, 42, 46, 47, 48, 49, 50, 55, 57], "hkl_base": [2, 46], "hkl_cell": 23, "hkl_written": 23, "hklf": [2, 38, 46, 50], "hklin": 46, "hklout": 46, "hl": [2, 20, 56], "hla": 12, "ho": 12, "hob": 46, "hoc": [26, 40], "hoh": [8, 49], "hold": [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 15, 17, 19, 21, 23, 24, 25, 26, 27, 33, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 53, 55, 61, 68, 101, 108, 110, 127, 128], "holder": [5, 29, 42, 52], "hole": [4, 5], "holohedr": [2, 4, 7], "holohedri": [4, 6, 7, 8], "home": [2, 7, 12, 26, 44, 45], "homocystein": 12, "honest": [6, 49, 50], "honour": [2, 19], "hope": 29, "hopefulli": 2, "horizont": [1, 5, 11, 15, 30, 42, 68], "horma1": 12, "hors": [0, 40], "host": [0, 2, 4, 5, 7, 9, 12, 15, 16, 19, 20, 21, 22, 24, 25, 26, 29, 35, 36, 38, 40, 42, 43, 49, 51, 52, 62, 71], "host_librari": 19, "host_writ": 20, "hostnam": [2, 25, 72], "hot": [2, 4, 5, 7, 15, 21, 23, 40, 127], "hot_pixel": 5, "hotpixel": 5, "hotpixelfind": 5, "hotpixelsgpu": 21, "hou": 0, "hough": 41, "hour": [9, 40, 71], "hous": [0, 4, 7, 12, 23, 26, 40, 55], "household": 29, "hover": [2, 25, 26], "how": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 17, 21, 23, 24, 25, 26, 27, 36, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 54, 55, 61, 64, 96, 107, 109, 110, 111, 119, 122, 125, 127, 133], "howel": [0, 3], "howev": [5, 6, 7, 8, 11, 17, 22, 23, 24, 27, 29, 49, 68, 71], "hp": 23, "hpad": 12, "hpe": 22, "hperf": 56, "hpp": 56, "hr": [4, 23, 132], "html": [2, 9, 12, 29, 40, 42, 97], "http": [2, 9, 13, 23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 41, 42, 45, 51, 59, 62, 91, 97, 99, 136, 139, 140], "httplib": [2, 56], "huang": [0, 3], "hubbel": 0, "huber": [0, 3, 8], "human": [12, 40, 56, 85], "hundr": [4, 5, 6, 7, 23, 40, 49], "hundredfold": 7, "hundredth": [6, 7], "hunter": 0, "hurt": [42, 49], "hw": [26, 45], "hx7e": 12, "hybrid": 12, "hydrat": [0, 3, 8], "hydratas": 12, "hydrochlorid": 12, "hydrogen": [0, 3, 4, 5, 8, 21, 40, 42, 46, 47, 49], "hydrogenas": 12, "hydrolas": 12, "hydrophob": [0, 8], "hydroxyhepta": 12, "hydroxylas": 12, "hydroxypyruv": 12, "hyoscyamin": 12, "hyperslab": 23, "hypix": 12, "hypothes": [2, 5, 8, 47, 49], "hypothesi": [2, 3, 5, 6, 39, 40, 42, 47, 48, 50], "hypothet": 29, "hyss": 46, "hz": [10, 22, 23, 25], "h\u1d40g": 49, "h\u2082o": 8, "i": [0, 1, 2, 3, 5, 6, 9, 10, 13, 15, 16, 17, 18, 19, 20, 21, 22, 24, 25, 26, 28, 29, 31, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 65, 68, 69, 71, 72, 75, 77, 80, 88, 89, 90, 91, 92, 93, 96, 97, 99, 101, 104, 107, 108, 109, 110, 119, 120, 122, 123, 124, 125, 127, 128, 129, 132, 133, 134, 135, 136, 138, 139, 140], "i0": 0, "i02": 12, "i03": 12, "i04": 12, "i1": 0, "i19": 12, "i2": [0, 12, 39, 55], "i222": [2, 40], "i23": [2, 12, 55], "i24": 12, "i2c": 20, "i4_1md": [4, 49], "i_": [4, 7], "i_0": [4, 8], "i_1": [4, 8, 49], "i_2": [4, 49], "i_h": 7, "i_model": 49, "i_over_sigma": [49, 124], "i_tru": [1, 23], "ia": [4, 49], "ib": 22, "ibm": 0, "ic": [0, 1, 2, 3, 4, 6, 8, 23, 25, 26, 41, 42, 44, 46, 47, 48, 49, 68, 96, 133, 134], "ice_intensity_bias_z": 49, "ice_intensity_r": 49, "ice_intensity_ring_01": 49, "ice_intensity_ring_05": 49, "ice_intensity_ring_nn": 49, "ice_intensity_z": [7, 49], "ice_r": [1, 38, 49], "ice_reflections_on_rings_pct": 49, "ice_ring_band_01": 49, "ice_ring_band_02": 49, "ice_ring_band_03": 49, "ice_ring_band_04": 49, "ice_ring_band_nn": [7, 49], "ice_ring_scor": [1, 49], "ice_ring_score_mean": 1, "ice_ring_width_q_recip_a": 134, "ice_rings_detect": 49, "ice_spot_ratio": 49, "iceringscor": 23, "iceringscoremean": 23, "ici": 23, "icm": 0, "icmp": [18, 20, 57], "icod": 1, "icon": [2, 36, 59], "id": [1, 2, 6, 19, 20, 23, 25, 26, 36, 40, 45, 46, 47, 49, 55, 62, 68, 71, 74, 79, 97, 133], "id14": 12, "id23": 12, "id29": 12, "id30b": 12, "idea": [5, 7, 29, 30], "ideal": [6, 8], "idempot": 21, "ident": [2, 4, 6, 7, 8, 12, 21, 23, 26, 39, 40, 41, 46, 47, 49, 51, 55], "identif": [0, 3, 8, 120], "identifi": [0, 1, 5, 6, 8, 9, 17, 23, 24, 25, 29, 36, 46, 51, 77], "idiom": 30, "idl": [2, 4, 14, 20, 25, 71, 81, 88], "idxref": [46, 49], "ieee": [0, 3, 8], "ignor": [2, 5, 7, 12, 23, 24, 25, 38, 39, 40, 42, 44, 46, 49, 53, 68, 71, 96, 99, 134], "igpd": 12, "ih": [0, 3, 5], "ihring": [0, 3], "ii": [0, 3, 4, 5, 6, 7, 8, 12, 17], "ii5mt4": 12, "iii": [0, 3, 7, 12], "ij": 7, "il": 12, "illeg": 36, "illumin": [4, 7], "imag": [0, 2, 3, 4, 6, 7, 8, 11, 13, 15, 16, 17, 22, 25, 27, 28, 30, 33, 34, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 54, 57, 59, 60, 61, 62, 67, 68, 71, 75, 77, 80, 89, 90, 91, 92, 93, 96, 97, 99, 101, 108, 109, 119, 121, 125, 126, 127, 128, 129, 132, 133, 134, 136, 138, 139, 140], "image_": 23, "image_analysi": [2, 5, 8, 15, 21, 56, 134], "image_appendix": [1, 68], "image_buff": [25, 51, 62, 71], "image_buffer_clear_post": 62, "image_buffer_image_cbor_get": 62, "image_buffer_image_jpeg_get": 62, "image_buffer_image_tiff_get": 62, "image_buffer_mi_b": 99, "image_buffer_mib": 25, "image_buffer_start_cbor_get": 62, "image_buffer_statu": [71, 91], "image_buffer_status_dict": 91, "image_buffer_status_from_dict": 91, "image_buffer_status_get": 62, "image_buffer_status_inst": 91, "image_count": [23, 71], "image_dtyp": [1, 23], "image_format": [25, 62, 71, 99], "image_format_set": [71, 92, 100], "image_format_settings_dict": 92, "image_format_settings_from_dict": 92, "image_format_settings_inst": 92, "image_id": 1, "image_index": 1, "image_nnnnnn": 23, "image_nr_high": 23, "image_nr_low": 23, "image_numb": [24, 26, 91, 105, 106], "image_push": [25, 62, 71, 99, 100], "image_pusher_statu": [71, 93], "image_pusher_status_dict": 93, "image_pusher_status_from_dict": 93, "image_pusher_status_get": 62, "image_pusher_status_inst": 93, "image_scale_b": 2, "image_scale_cc": 1, "image_scale_corr": [1, 23], "image_scale_factor": 1, "image_scale_mosa": 1, "image_scale_tim": 1, "image_size_i": 1, "image_size_x": 1, "image_socket": [24, 25, 136, 140], "image_std": 23, "image_stream": 27, "image_tim": 92, "image_time_u": 68, "imagebufferstatu": [62, 71, 100], "imageformatset": [62, 71, 99, 100], "imageindex": 23, "imageindexedmean": 23, "imagepreprocessorbuffergpu": 21, "imagepreprocessorgpu": 21, "imagepusherstatu": [62, 71, 100], "imagepushertyp": [62, 93, 99], "images_analys": 127, "images_collect": [1, 101], "images_discarded_lossy_compress": 101, "images_expect": [101, 125], "images_held": 127, "images_index": 127, "images_need": 127, "images_per_fil": [1, 2, 24, 53, 68, 71], "images_per_trigg": [1, 68], "images_process": 49, "images_receiv": 125, "images_s": 101, "images_sent_to_writ": 1, "images_write_error": 93, "images_written": [93, 101], "imagescalebfactor": 2, "imagescalecc": 23, "imagescalefactor": 23, "imagescalemosa": 23, "imagescaletim": 23, "imagespotfindergpu": 21, "imatix": 56, "imd": 12, "imean": [2, 4, 38, 39, 42, 46, 47, 50], "img": 12, "imgcif": [0, 2, 11, 12, 42, 44], "imisf": 12, "imit": 6, "immedi": [17, 27, 40, 71], "immun": [4, 12, 42, 49], "imosflm": 0, "impact": [2, 5, 22, 51], "imped": 51, "imperfect": [2, 6], "imperfectli": [2, 4], "implaus": [2, 7], "implausibli": 7, "implement": [0, 2, 3, 5, 6, 7, 15, 29, 42, 45, 47, 49, 56, 62, 91], "impli": [4, 7, 8, 17, 29, 36, 41, 42, 49, 109, 110], "implic": 17, "implicit": 5, "implied_by_abs": 49, "import": [2, 7, 17, 25, 29, 33, 35, 46, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "impos": [6, 29, 62], "impract": 22, "improb": 4, "improp": [0, 2, 3, 4, 8], "improperli": 2, "improv": [0, 2, 3, 4, 6, 7, 8, 27, 42, 48, 49, 50], "imwrit": 33, "in_preparation_slot": 91, "in_sending_slot": 91, "inabl": 29, "inaccur": 29, "inact": [2, 5, 7, 15, 23, 53, 71], "inc": [29, 56], "incid": [0, 1, 2, 5, 7, 11, 41, 44, 46, 49, 68, 80], "incident": [17, 29], "incident_beam_direct": [46, 49], "incident_beam_s": [1, 2, 23, 68], "incident_energi": 1, "incident_energy_ev": 27, "incident_energy_ke_v": 68, "incident_energy_kev": [49, 92], "incident_wavelength": [1, 23, 68], "incident_wavelength_spread": [1, 23], "incl": 36, "includ": [1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 14, 15, 17, 21, 22, 23, 24, 25, 26, 28, 29, 33, 36, 37, 38, 40, 41, 42, 44, 45, 46, 47, 49, 50, 53, 55, 56, 59, 61, 71, 86, 96, 101], "include_resolution_rang": [49, 50], "inclus": [23, 29, 49, 53, 114, 121], "incom": [12, 18], "incompat": 29, "incomplet": [2, 7, 49], "inconclus": 49, "inconsist": [1, 2, 5, 19, 42], "inconsistent_with_merg": [23, 49], "incorpor": [15, 29], "incorrect": 12, "increas": [1, 2, 4, 5, 7, 11, 24, 46, 80], "increment": [1, 42, 58, 68, 101, 119], "indefinit": [0, 3, 71], "indemnif": 29, "independ": [0, 2, 4, 5, 6, 7, 8, 9, 12, 18, 24, 26, 29, 36, 37, 39, 40, 41, 42, 46, 48, 49, 50, 55, 110], "index": [1, 2, 3, 5, 8, 10, 11, 12, 13, 22, 24, 25, 26, 27, 28, 30, 34, 35, 36, 38, 40, 44, 45, 46, 48, 50, 52, 54, 55, 56, 57, 59, 61, 62, 68, 71, 77, 89, 95, 96, 99, 100, 125, 132, 133, 134, 137], "index_analysis_tim": 1, "index_ice_r": 96, "indexanalysistim": 23, "indexed_lattice_count": 1, "indexedlatticecount": 23, "indexing_algorithm": [1, 23], "indexing_ambigu": 49, "indexing_ambiguity_oper": [47, 49], "indexing_ambiguity_resolv": [39, 47, 49, 50], "indexing_extra_lattic": 1, "indexing_lattic": 1, "indexing_lattice_count": 1, "indexing_peak_check": 0, "indexing_r": [1, 49, 101], "indexing_result": 1, "indexing_set": [25, 71, 96], "indexing_settings_dict": 96, "indexing_settings_from_dict": 96, "indexing_settings_inst": 96, "indexing_tim": 1, "indexing_unit_cel": 1, "indexingalgorithm": [62, 96], "indexinglatticecount": 23, "indexingset": [62, 71, 99, 100], "indexingtim": 23, "indic": [0, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 21, 23, 24, 29, 39, 49, 50], "indict": 4, "indigo": [50, 71], "indirect": 17, "indistinguish": [2, 4, 55], "indistinguishable_altern": 40, "individu": [2, 4, 7, 29, 49], "indu": 12, "induc": 12, "industri": [29, 51, 61], "inert": [5, 7], "ineterfac": 140, "inf": 49, "infer": [0, 2, 3, 7, 22, 42, 49], "inferno": 0, "infin": 2, "inflat": [2, 4, 5, 7, 55], "influenc": [2, 39, 40], "influenza": 12, "info": [1, 2, 23, 26, 46], "inform": [0, 1, 2, 3, 4, 6, 7, 8, 11, 17, 23, 24, 29, 42, 47, 49, 55, 57, 62, 71, 87, 93, 99, 134, 138], "infrastructur": 51, "infring": [17, 29], "infti": 7, "ingest": [2, 7, 21, 45], "inher": 23, "inherit": [2, 7, 47, 49], "inhibitor": 12, "inhous": [12, 40], "init": 9, "initi": [0, 2, 3, 4, 8, 17, 24, 25, 29, 33, 51, 60, 62, 65, 71, 125, 128], "initialis": 2, "initialize_post": 62, "initio": 0, "inject": 39, "inner": [0, 6, 7, 8, 42, 49], "innermost": [2, 23], "innosuiss": 0, "innov": 0, "inorgan": [0, 7, 46], "inp": [12, 46, 49, 53], "input": [1, 2, 4, 5, 6, 7, 13, 21, 23, 24, 25, 26, 27, 38, 39, 40, 45, 46, 47, 48, 49, 50, 51, 55, 56, 61, 71, 96, 109, 134], "input_fil": [39, 49], "input_ident": 39, "input_unit_cel": 2, "ins": [2, 38, 44, 46, 49, 50], "insensit": [5, 7, 41, 42], "insert": [12, 19], "insid": [1, 2, 4, 5, 6, 7, 8, 12, 21, 25, 29, 30, 36, 37, 40, 42, 44, 46, 49, 51, 53, 128], "insignific": 6, "insmod": 9, "inspect": [1, 4, 23, 24], "inspector": [2, 26], "inspir": [0, 3, 4, 5, 7], "inst": [0, 3], "instal": [2, 7, 14, 17, 22, 25, 26, 29, 31, 35, 37, 38, 40, 43, 49, 50, 51, 52, 56, 57, 59, 61, 65], "install_dkm": 19, "instanc": [2, 23, 46, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "instead": [0, 2, 4, 5, 6, 7, 8, 12, 18, 21, 23, 24, 25, 26, 27, 29, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 52, 55, 71, 80, 134, 136, 138, 139, 140], "institut": [17, 30, 49, 61, 62], "instruct": [4, 14, 38, 46, 50], "instrument": [1, 2, 4, 7, 12, 25, 44, 49, 50, 53, 62, 68, 71, 97, 99], "instrument_metadata": [71, 97, 100], "instrument_metadata_dict": 97, "instrument_metadata_from_dict": 97, "instrument_metadata_inst": 97, "instrument_nam": [1, 25, 97], "instrumentmetadata": [62, 71, 99, 100], "insulin": [12, 40], "int": [0, 1, 3, 27, 46, 50, 63, 64, 65, 66, 67, 68, 71, 72, 73, 74, 77, 79, 80, 82, 88, 90, 91, 92, 93, 96, 99, 101, 103, 109, 114, 121, 122, 123, 124, 125, 127, 128, 129, 133, 134, 135, 136, 138, 139, 140], "int16": [1, 13, 23], "int20": 2, "int32": [1, 5, 21, 23], "int32_max": 23, "int32_min": 1, "int64": 1, "int8": [1, 23], "int_0": 7, "int_err": 23, "int_sum": 23, "int_sum_error": 23, "intact": 29, "integ": [0, 1, 2, 4, 5, 6, 11, 15, 20, 21, 23, 33, 42, 49, 68, 71, 80], "integr": [1, 2, 3, 4, 6, 8, 12, 14, 16, 20, 24, 25, 26, 27, 28, 30, 36, 38, 39, 40, 43, 44, 45, 46, 47, 48, 49, 50, 54, 55, 57, 59, 61, 62, 63, 64, 68, 71, 80, 98, 111, 134], "integrate1d": 53, "integrated_reflect": 1, "integratedreflect": 23, "integration_model": 64, "integration_tim": 1, "integrationmodel": [62, 64], "integrationtim": 23, "integrin": 12, "intel": [1, 22, 26, 36, 43, 45, 52, 56, 59], "intellectu": 14, "intend": [4, 5, 6, 10, 17, 26, 29, 46, 51, 62], "intens": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 21, 23, 38, 39, 40, 42, 44, 46, 47, 48, 49, 50, 55, 68, 98, 122, 133], "intensity_mea": [4, 46], "intent": 29, "intention": 7, "interact": [0, 2, 3, 5, 8, 11, 26, 29, 38, 49, 62], "interatom": [0, 8], "intercept": [7, 8], "interchang": [4, 24, 29, 49, 50], "interest": [0, 21, 29, 46, 71], "interf": [2, 29], "interfac": [0, 1, 2, 17, 19, 20, 24, 28, 29, 31, 38, 49, 51, 57, 58, 61, 62, 71, 74, 136, 138, 139, 140], "interior": 5, "interleav": 2, "interleukin": 12, "intermedi": [2, 7, 12, 17], "intern": [0, 1, 2, 3, 4, 7, 11, 12, 17, 20, 23, 39, 42, 49, 51, 57, 58, 62, 71, 80, 93, 99], "internal_frame_gener": [25, 80], "internal_frame_generator_imag": [25, 80], "internal_generator_imag": [62, 71], "internet": [36, 51], "interoper": 23, "interpol": [0, 1, 2, 3, 4, 5, 6, 7, 8, 33], "interpret": [0, 6, 29, 49], "interrupt": [17, 20], "intersect": [4, 7, 21, 40], "intersectin": 12, "interstiti": 46, "interv": [0, 2, 49, 80], "intim": 29, "introduc": [2, 24, 49], "introduct": 0, "intx_max": 23, "intx_min": [1, 23], "inup4q": 12, "invalid": [2, 5, 7, 17, 27, 29, 51, 71], "invari": [2, 4, 5, 6, 7, 49, 55], "invent": 49, "invers": [0, 2, 3, 4, 5, 6, 7, 8, 21, 42, 49], "invert": [2, 4, 7, 38, 39, 46, 47, 49], "investig": [0, 3], "invis": [4, 5, 7, 49], "invoc": 49, "invok": 2, "involut": 8, "involv": [6, 17, 21, 50], "inward": 6, "ioctl": [19, 62], "ioerror": 24, "iol": 12, "ion": [1, 2, 3, 4, 8, 12, 25, 38, 39, 42, 47, 49, 56, 97, 128], "ions_within_4": 49, "ions_within_6": 49, "iotbx": [2, 46, 50], "ip": [0, 2, 14, 18, 20, 27, 51, 93, 101, 136, 138, 139, 140], "ipc": [24, 138, 139, 140], "ipmitool": 9, "ipv4": [18, 20, 25, 57, 102], "irl": 7, "irmer": [0, 8], "iron": [0, 8, 12, 47], "irremov": [0, 8], "irrespect": 80, "irrevoc": [17, 29], "irrmc": [0, 12, 40], "isa": [0, 2, 4, 6, 7, 38, 39, 40, 42, 46, 47, 48, 49, 50, 55, 125], "isa_asymptot": 49, "isa_high": [2, 49], "isa_low": [2, 49], "isc": 56, "island": [0, 4, 21], "iso": 5, "isoform": 12, "isol": [5, 7, 42, 51], "isold": [0, 3], "isom": 12, "isomeras": 12, "isomorph": [0, 2, 4, 39, 42, 49, 50], "isor": [0, 8], "isoreticular": 12, "isotrop": [0, 4, 5, 7, 8, 12, 40, 47, 49], "isotropi": [5, 8, 21, 42, 44, 48], "issu": [2, 18, 22, 27, 40, 101], "isupov": [0, 8], "isym": 46, "it92": [4, 8], "ita": 4, "italian": 30, "item": [2, 4, 7, 29, 39, 46, 49], "iter": [0, 2, 3, 5, 6, 7, 8, 23, 42], "its": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 17, 18, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 33, 34, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 55, 56, 57, 59, 60, 61, 68, 71, 75, 77, 96, 107, 109, 110, 119, 120, 121, 122, 123, 124, 125, 128, 131, 134, 136], "itself": [0, 1, 2, 4, 5, 6, 7, 8, 12, 17, 21, 23, 25, 26, 29, 38, 39, 40, 41, 42, 44, 46, 47, 49, 50, 71, 109], "iucr": [0, 3], "iucrdata": [0, 12], "iucrj": [13, 34], "iv": [2, 5, 12, 27, 34], "ix": 12, "i\u00b2": [46, 49], "i\u2081": 49, "i\u2082": 49, "j": [0, 1, 3, 7, 8, 9, 12, 13, 15, 21, 23, 26, 27, 28, 34, 44, 45, 46, 52, 55, 77], "j_0": 5, "j_f": 7, "j_r": 7, "j_t": 7, "jackknif": 0, "jacob": 56, "jacobi": 8, "jacobian": [0, 3, 4, 6, 21], "jalc": 12, "jammi": 37, "jan": 0, "janin": [0, 3], "janousch": [0, 34], "japan": 0, "jararacussu": 12, "javascript": [56, 99], "jcc": 0, "jcc5": 0, "jdoe": 23, "jean": 56, "jejuni": 12, "jelli": [8, 47], "jensen": 15, "jet": [12, 97], "jetbrain": 0, "jf": 13, "jf06t08v01": 13, "jf06t32v01": 13, "jf16m": 13, "jf4m": 13, "jf_convers": 20, "jf_info": 1, "jfjoch": [2, 9, 19, 25, 26, 28, 31, 35, 36, 37, 53, 59], "jfjoch0": [9, 25, 57], "jfjoch1": 25, "jfjoch_": [39, 46], "jfjoch_action_test": 2, "jfjoch_aniso_": [2, 4], "jfjoch_aniso_d_min_1": 46, "jfjoch_aniso_delta_b": 46, "jfjoch_aniso_shap": 46, "jfjoch_api": [23, 25, 29, 35, 44, 49], "jfjoch_azint": 2, "jfjoch_battery_sit": 40, "jfjoch_brok": [1, 2, 9, 19, 21, 23, 24, 26, 27, 28, 33, 36, 38, 41, 49, 57, 61, 62, 65, 71, 100], "jfjoch_broker_test": 25, "jfjoch_client": [35, 62, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "jfjoch_dataset_set": [5, 49], "jfjoch_diffrn_isa": [2, 7, 46, 49], "jfjoch_diffrn_isa_asymptot": [2, 7, 46], "jfjoch_distance_mm": 46, "jfjoch_driver_dkm": [2, 36], "jfjoch_error_model_a": [7, 46], "jfjoch_error_model_c": [46, 49], "jfjoch_extract_hkl": 2, "jfjoch_fpga_test": [2, 9, 55], "jfjoch_hdf5_enospc_test": 55, "jfjoch_hdf5_test": 55, "jfjoch_l_test_mean_abs_l": 46, "jfjoch_lite_perf_test": [2, 55], "jfjoch_portable_test": 55, "jfjoch_process": 2, "jfjoch_radiation_damage_relative_b": 46, "jfjoch_recompress": 2, "jfjoch_releas": [1, 23], "jfjoch_rugnux": [36, 42, 45], "jfjoch_scal": 2, "jfjoch_second_moment_i": 46, "jfjoch_set": [9, 25, 99], "jfjoch_settings_dict": 99, "jfjoch_settings_from_dict": 99, "jfjoch_settings_inst": 99, "jfjoch_statist": [71, 100], "jfjoch_statistics_dict": 100, "jfjoch_statistics_from_dict": 100, "jfjoch_statistics_inst": 100, "jfjoch_stills_gpu_replai": 25, "jfjoch_test": [2, 55, 56], "jfjoch_use_cuda": [7, 21], "jfjoch_vers": 108, "jfjoch_view": [2, 9, 21, 36, 38, 50, 51, 52, 53, 56, 57, 59], "jfjoch_viewer_build": 56, "jfjoch_viewer_onli": [26, 56], "jfjoch_viewer_remot": 26, "jfjoch_writ": [2, 9, 23, 24, 26, 28, 34, 36, 38, 44, 57, 61, 68, 87], "jfjoch_writer_releas": 23, "jfjoch_xds_plugin": [36, 53], "jfjochcriticalexcept": 2, "jfjochreceiverdarkmask": 25, "jfjochreceiverfpga": 25, "jfjochreceiverlit": 25, "jfjochreceiverrugnuxrot": 25, "jfjochreceiverrugnuxstil": 25, "jfjochset": 62, "jfjochstatist": [62, 71], "jfjt": 24, "jiang": [0, 3, 8], "jit": [2, 36], "jmbi": 0, "jmp47a2_1": 12, "jmp47a2_2": 12, "job": [2, 5, 6, 7, 26, 38, 40, 45, 55], "joch": 30, "johnson": [0, 3], "join": [0, 2, 5, 8, 12, 21, 42, 44, 49, 53], "joint": [0, 3, 6, 7, 42, 48, 49], "jointli": 6, "jon": [0, 5, 21], "jonwright": 3, "joss": 0, "jp": 12, "jpeg": [2, 25, 51, 62, 71], "jpeg_qual": 71, "jpg": [2, 38, 50], "jq": 41, "jr": 0, "json": [0, 1, 2, 8, 9, 11, 12, 13, 23, 24, 25, 27, 38, 39, 40, 41, 42, 47, 49, 50, 55, 56, 57, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "judg": [0, 2, 4, 5, 6, 7, 8, 12, 21, 23, 26, 40, 42, 44, 47, 49, 50], "judgement": 8, "jumbo": 18, "jump": [6, 26], "jumper": [0, 3], "june": 29, "jung": 30, "jungfrau": [1, 2, 5, 6, 9, 10, 13, 14, 16, 19, 20, 22, 23, 24, 25, 27, 28, 30, 33, 34, 44, 53, 57, 60, 61, 62, 68, 71, 72, 80, 84, 92, 128, 134], "jungfrau_convers": [25, 92], "jungfrau_conversion_appli": 23, "jungfrau_conversion_en": 1, "jungfrau_conversion_factor": [1, 23], "jungfrau_conversion_factor_ke_v": 92, "jungfrau_conversion_factor_kev": 25, "jungfrau_fixed_gain_g1": [25, 80], "jungfrau_mask_pixels_without_g0": 92, "jungfrau_pedestal_g0_fram": [25, 80], "jungfrau_pedestal_g0_rms_limit": [25, 92], "jungfrau_pedestal_g1_fram": [25, 80], "jungfrau_pedestal_g2_fram": [25, 80], "jungfrau_pedestal_min_image_count": [25, 80], "jungfrau_storage_cell_count": [25, 80], "jungfrau_storage_cell_delay_n": [25, 80], "jungfrau_use_gain_hg0": [25, 80], "jungfraubahn": 30, "jungfraujoch": [0, 1, 2, 5, 6, 7, 10, 11, 12, 14, 15, 17, 18, 19, 20, 21, 22, 23, 24, 26, 27, 31, 33, 36, 37, 38, 42, 44, 45, 46, 48, 50, 51, 52, 53, 54, 55, 56, 57, 58, 60, 62, 68, 71, 89, 92, 95, 96, 97, 99, 100, 136, 140], "jungfraujoch_http_host": 26, "jungfraujoch_http_port": 26, "jungfraujoch_http_token": [26, 38, 42, 51], "jungfraujochdevic": 19, "just": [2, 4, 5, 6, 7, 15, 23, 26, 40, 42], "k": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 30, 39, 42, 44, 46, 47, 49, 50], "k11": 12, "k138a": 12, "k_": [4, 5, 7, 8], "k_1": 5, "k_b": 5, "k_f": 6, "k_i": 6, "k_sol": [3, 21], "k_u": 21, "kabsch": [0, 3, 4, 7, 49, 98], "kahn": [0, 3, 5], "kal": 56, "kamo": 0, "kang": 13, "kantardjieff": [0, 3, 4], "kap1": 12, "kappa": [7, 8, 12, 49], "kappa_k": 7, "karplu": [0, 3, 7, 8, 49], "kassner": [0, 3, 4], "kaufman": [0, 3, 4], "kb": [1, 5, 24], "kde": 26, "kdir": 19, "kdo8p": 13, "kdo_embed": 13, "keap1": 12, "keeff": [0, 8], "keel": [0, 12], "keep": [0, 1, 2, 4, 5, 6, 7, 8, 9, 12, 13, 18, 21, 23, 24, 25, 27, 28, 29, 30, 36, 38, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 68, 89, 128, 136], "keepal": [2, 71], "kei": [0, 1, 2, 4, 6, 7, 8, 9, 12, 21, 23, 26, 27, 29, 37, 38, 39, 40, 42, 44, 47, 50, 51, 53, 60, 123], "keller": [0, 3], "kelvin": 68, "kepa": 34, "kept": [0, 2, 4, 5, 6, 7, 8, 12, 13, 21, 23, 24, 25, 27, 35, 38, 39, 40, 42, 44, 46, 47, 48, 49, 50, 56, 60, 71, 86, 125], "kernel": [0, 2, 4, 5, 6, 7, 8, 21, 24, 28, 29, 36, 37, 40, 45, 56, 62], "kev": [0, 1, 2, 7, 13, 15, 20, 23, 42, 44, 55, 68], "keyboard": [2, 26], "keychain": 26, "keyr": 37, "keyston": 6, "keyword": [46, 49], "khz": [22, 34], "kieffer": 3, "kill": [5, 38, 40, 45], "killer": 45, "kilohertz": [0, 3, 28, 34], "kinas": 12, "kind": [1, 4, 7, 8, 12, 13, 17, 26, 29, 40, 49, 50, 120], "kinesin": 12, "kingdom": 0, "kirian": [0, 3], "kirk": [0, 3], "kirmizialtin": [0, 8], "kissel": [0, 8], "kit": 12, "kiyoshi": 56, "klebsiella": 12, "kleywegt": [0, 8], "knechtel": [0, 8], "knee": 4, "knife": 12, "knob": [5, 45], "know": [1, 4, 5, 6, 8, 23, 24, 29, 39, 41, 43, 44, 46, 47, 49, 50, 107, 109], "knowingli": 29, "knowledg": [0, 3, 8, 12, 29, 47, 49], "known": [0, 1, 2, 3, 4, 5, 7, 8, 17, 21, 23, 25, 26, 39, 40, 42, 48, 49, 50, 53, 55, 71, 125], "knuth": 0, "ko": 9, "kob": 46, "koba": [0, 3], "kod": 12, "kontogianni": 0, "kowiel": 0, "ko\u010da": 0, "kr": 12, "krasznahorkai": 0, "kroon": 12, "krypton": 12, "kuh": [0, 3], "kullback": [0, 3, 8], "kunstlev": [0, 3, 8], "kursula": [0, 3], "kurtosi": 7, "kver": 19, "ky43": 12, "k\u00f6pke": 0, "k\u0159iv\u00fd": [0, 3], "k\u03b1": 46, "l": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 34, 38, 39, 40, 42, 45, 46, 47, 49, 50], "l1f11v1": 12, "l2": 2, "l4": 22, "l_": [6, 7, 8], "l_d": 6, "l_f": 6, "l_i": 6, "l_test": [8, 49], "l_test_mean_abs_l_before_search": 49, "l_test_vs_tnc": [2, 4, 49], "l_z": 5, "la": [0, 3], "lab": [0, 4, 5, 7], "lab6": [2, 26, 41, 42], "lab6_mast": [41, 42], "label": [0, 1, 2, 3, 4, 7, 8, 21, 23, 25, 38, 39, 40, 42, 46, 47, 49, 50, 55, 56, 124, 130, 131], "label_asym_id": 1, "label_entity_id": 1, "label_seq": 1, "label_seq_id": 1, "labin": 46, "laboratori": [5, 6, 11, 12, 42, 44, 46, 50], "lab\u2086": 6, "lacassagn": [0, 3], "lack": [4, 7, 8, 44, 46, 49], "lactonas": 12, "ladder": [4, 5, 6, 8, 47, 48], "lag": [7, 25], "lai": [25, 44, 49], "laid": [5, 7, 40, 42, 44, 111], "lalanin": 12, "lalanine_sweep": 12, "lambda": [4, 5, 6, 7], "lamblia": 12, "land": [1, 2, 4, 5, 6, 7, 11, 21, 23, 39, 41, 42, 45, 47, 48, 49, 50, 53, 108, 109, 127], "landscap": 30, "lane": [5, 21, 22], "lanebyt": 21, "langl": [4, 7], "langner": 0, "languag": [0, 2, 29, 30, 62], "lapack": 2, "laptop": 40, "larch": [0, 56], "larg": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 15, 21, 23, 24, 25, 27, 30, 38, 40, 42, 43, 49, 50, 56, 109], "larger": [4, 5, 6, 7, 8, 17, 22, 23, 25, 27, 29, 40, 42, 45, 46, 49, 50, 53, 71, 96, 109], "largest": [0, 4, 5, 6, 7, 8, 15, 21, 38, 40, 42, 43, 45, 46, 49, 50, 91, 96], "laser": [0, 1, 97], "laspart": 12, "laspartic_sweep": 12, "last": [2, 4, 5, 6, 7, 8, 12, 20, 21, 23, 24, 25, 26, 38, 40, 42, 44, 45, 46, 47, 49, 50, 55, 62, 71, 121, 125, 128, 129], "last_imag": [49, 121], "last_image_": 125, "last_image_to_written_": 125, "late": [6, 8, 49], "later": [2, 4, 5, 6, 7, 17, 19, 25, 27, 29, 38, 40, 49, 50, 56], "latest": [0, 3, 8, 25, 42, 71, 125], "latin": 30, "latt": [1, 38, 46, 50], "latt_count": 133, "latter": [4, 14, 26, 71], "lattic": [1, 2, 3, 4, 5, 8, 21, 23, 25, 38, 39, 40, 42, 44, 46, 47, 48, 50, 64, 89, 96, 125, 126, 131, 132, 133], "lattice_averag": 49, "lattice_doubl": 40, "lattice_explains_few_spot": 49, "lattice_found": 49, "lattice_halv": 40, "lattice_transl": [2, 49], "lattice_typ": 1, "latticeindex": 23, "latticeindexedextra": 23, "laue": [2, 3, 4, 12, 23, 39, 40, 46, 47, 49], "launch": [2, 21, 26, 36], "lauti": 56, "law": [0, 2, 4, 6, 7, 8, 12, 17, 29, 39, 40, 42, 47, 49, 50], "lawsuit": [17, 29], "layer": [18, 25, 51], "layout": [1, 2, 11, 12, 13, 26, 27, 28, 40, 42, 44, 46, 50, 53, 55, 104], "lcb2": 12, "lcb2_8_newt_001": 12, "lceil": [5, 7], "lcl": [2, 13, 38, 42, 44], "lcls222": 13, "lcls242_": 13, "lcls242_t": 13, "lcls_222": 13, "lcls_242": 13, "ld_1_master": 12, "ld_preload": 55, "ldlsbt": 12, "ldots13": 7, "le": [0, 1, 3, 4, 5, 6, 7, 8], "le1": 12, "lea": [0, 3], "lead": [2, 4, 6, 7, 8, 39, 47, 49, 80], "leaf": 2, "leak": [2, 7, 47], "leakag": 4, "lean": [5, 12], "leaner": 6, "learn": [2, 7, 21, 27, 40, 42, 53, 98], "learnt": 8, "least": [0, 2, 3, 4, 5, 6, 7, 8, 17, 18, 21, 22, 23, 29, 30, 39, 40, 42, 45, 46, 47, 48, 49, 50, 55, 89, 109, 134], "leav": [0, 2, 4, 5, 6, 7, 8, 11, 12, 23, 24, 25, 26, 27, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 55, 120, 131], "lebayl": 0, "lebedev": [0, 3, 8, 12], "leca": 12, "lectin": 12, "led": 12, "ledger": [2, 4, 7, 42], "lee": 13, "leffler": 56, "left": [1, 2, 4, 5, 6, 7, 8, 11, 12, 21, 23, 24, 25, 26, 30, 33, 38, 39, 41, 42, 44, 46, 47, 49, 50, 51, 68, 72, 90, 123, 128, 129, 135], "leftarrow": 7, "leftov": 49, "legaci": [1, 2, 23, 53, 68, 86], "legal": [17, 29], "legend": [1, 2, 50], "leggett": 0, "legitim": [6, 23], "leibler": [0, 3, 8], "lemir": 56, "len": 39, "lend": 6, "length": [1, 2, 4, 5, 6, 7, 8, 11, 12, 23, 39, 42, 44, 49, 50, 70, 123], "length_a_esd": 39, "lengthen": 5, "leonarski": [0, 3, 8, 28, 34, 38, 62], "lesli": [0, 3], "less": [1, 2, 4, 5, 6, 7, 8, 12, 23, 30, 39, 42, 45, 46, 49, 55, 71], "lesser": 29, "lesson": 40, "lesssim": 6, "let": [0, 2, 4, 5, 6, 7, 8, 23, 38, 39, 40, 42, 47, 49, 55, 61, 89], "letter": [0, 1, 7, 47, 132], "leucinostatin": 12, "leukocyt": 12, "levansucras": 12, "level": [1, 2, 3, 6, 7, 9, 12, 16, 21, 23, 24, 25, 26, 29, 36, 38, 40, 42, 43, 44, 45, 49, 50, 51, 55, 56, 57, 59, 65, 71, 103], "levenberg": [4, 21, 56], "lever": 6, "leverag": 5, "le\u00e7on": 0, "lf": 2, "lgpl": [29, 56], "li": [4, 5, 6, 7, 23, 25, 40, 42, 44, 49, 77], "liabil": [17, 29], "liabl": 29, "lib": [19, 36, 53], "libcbf": 44, "libdbu": 2, "liberman": [0, 8, 56], "libgfortran": 2, "libgomp": 2, "libjfjoch_xds_plugin": [36, 53], "libjpeg": 2, "libm": 36, "libmeti": 2, "libopenbla": 2, "libpng": 2, "libquadmath": 2, "librari": [0, 1, 2, 3, 6, 8, 9, 15, 17, 21, 26, 29, 36, 40, 45, 47, 49, 52, 53, 55, 58, 62], "librat": 0, "libtiff": [2, 52, 56], "libz": 2, "libzmq": [52, 56], "licenc": [0, 45, 49, 56, 61], "licens": [0, 2, 4, 14, 26, 45, 49, 52, 53, 54, 56, 61], "license": [17, 29], "licensor": [17, 29], "licheniformi": [12, 40], "lie": [1, 4, 5, 6, 8, 25, 42, 44, 49, 68], "liebschner": [0, 3], "life": [24, 25, 136], "lifecycl": 24, "lifetim": 2, "lift": [4, 7, 8, 42, 46, 49, 55], "ligand": [0, 1, 3, 4, 8, 12, 39, 40, 42, 47, 49], "ligas": 12, "light": [0, 2, 5, 8, 12, 25, 26, 46, 53], "lighter": [2, 4, 6, 49], "like": [2, 4, 5, 6, 7, 8, 9, 12, 13, 22, 23, 25, 26, 27, 29, 36, 39, 41, 42, 44, 45, 46, 47, 48, 49, 50, 52, 53, 56, 59, 109, 120], "likelihood": [0, 2, 3, 4, 7, 21, 38, 42, 47, 48, 49, 50, 122], "likewis": [1, 6, 8, 29], "limit": [0, 2, 3, 5, 6, 7, 8, 15, 17, 22, 23, 25, 26, 29, 37, 38, 39, 42, 44, 45, 46, 47, 49, 50, 51, 56, 62, 63, 71, 109, 122, 124, 125, 134], "line": [0, 2, 4, 5, 7, 8, 11, 13, 15, 16, 21, 25, 26, 28, 29, 30, 37, 38, 44, 45, 46, 49, 50, 56, 57, 61, 71, 121, 131], "linear": [2, 4, 5, 6, 7, 8, 12, 23, 25, 26, 42, 45, 46, 49, 50, 63, 111], "linearli": [7, 8], "link": [0, 1, 2, 7, 8, 12, 14, 18, 21, 22, 23, 26, 29, 35, 36, 37, 43, 44, 45, 47, 48, 49, 52, 53, 59, 86, 88], "linkag": [36, 49], "linker": 12, "links_and_mod": 56, "linktodata_processingvd": 23, "linux": [2, 12, 19, 24, 26, 28, 36, 38, 40, 45, 52, 53, 59, 61, 62], "liquid": 12, "list": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 24, 25, 26, 27, 28, 29, 36, 37, 38, 40, 41, 42, 43, 44, 46, 47, 49, 50, 51, 52, 55, 56, 57, 59, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "listen": [24, 25, 136, 138, 139, 140], "listeria": 12, "lit": [5, 21, 33], "lite": [2, 10, 14, 25, 55, 57, 64, 96, 134], "liter": [5, 68], "literatur": 12, "litig": [17, 29], "littl": [0, 1, 2, 4, 6, 7, 8, 12, 30, 42, 46, 49, 50, 51], "liu": [0, 3, 8], "live": [0, 2, 4, 5, 6, 7, 12, 22, 23, 24, 26, 28, 34, 38, 40, 42, 47, 48, 49, 50, 51, 56, 59, 60, 61, 62, 64, 68, 71, 93, 96, 101, 125, 128, 129, 134], "live_events_get": 62, "llg": 55, "llg_z": [49, 122], "llwngpmav": 12, "lm": 40, "lmsolver": 56, "ln": [4, 5, 6, 7, 8, 21, 49], "lnksta": 9, "lnl": 12, "load": [2, 5, 6, 7, 9, 12, 14, 15, 17, 20, 23, 25, 26, 40, 51, 53, 62, 71, 91], "load_calibr": 20, "load_from_hbm": 20, "loadfil": [26, 51], "loadimag": 26, "lob": 46, "lobe": [5, 6], "local": [0, 2, 3, 4, 6, 8, 21, 26, 29, 39, 49, 50, 55, 59], "localhost": [25, 26, 35, 51, 62, 71], "locat": [0, 1, 2, 3, 7, 8, 11, 12, 17, 26, 92, 99], "loch": 30, "lock": [2, 5, 7, 21], "lockdown": 51, "log": [0, 2, 4, 5, 6, 7, 8, 21, 25, 27, 38, 39, 40, 42, 44, 45, 46, 49, 50, 51], "log10": [2, 5, 23, 25, 42, 63, 111], "log_": 5, "log_2": 6, "logarithm": [0, 2, 5, 6, 7, 49], "logic": 2, "login": 51, "logist": [4, 38, 42, 50], "logo": [2, 17], "lohkamp": [0, 3, 8], "lohmann": 56, "lone": [1, 5, 6, 23, 49, 133], "long": [0, 1, 2, 4, 5, 6, 7, 8, 12, 21, 24, 25, 26, 27, 29, 30, 38, 40, 41, 42, 45, 46, 48, 49, 51, 55, 71, 92, 125, 127, 128, 136], "longer": [2, 4, 5, 6, 7, 8, 12, 17, 19, 25, 27, 39, 40, 42, 46, 47, 48, 49, 86, 128], "longest": [5, 6, 8, 42, 49], "look": [0, 2, 4, 5, 11, 12, 13, 23, 25, 27, 36, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 55, 109, 131], "lookup": [4, 6], "loop": [0, 2, 3, 4, 5, 6, 7, 8, 12, 21, 25, 30, 38, 40, 42, 45, 46, 47], "loos": [6, 40], "loosen": 8, "looser": 4, "lopez": [0, 34], "lorentz": [0, 1, 2, 4, 7, 23, 42, 46], "lose": [2, 4, 6, 7, 8, 12, 27, 42, 48, 49], "loss": [0, 2, 4, 5, 6, 7, 8, 17, 29], "loss_of_centr": [23, 49], "lossi": [1, 15, 16, 20, 68, 101], "lost": [2, 4, 5, 6, 7, 8, 12, 23, 49], "lot": [2, 9, 30], "loup": 56, "lov2": 12, "low": [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 21, 23, 25, 36, 38, 40, 42, 46, 49, 50, 51, 53, 55, 63, 80, 111, 124, 133, 134], "low_complet": 49, "low_flank": 49, "low_outer_flank": 49, "low_q_recip_a": 63, "low_q_recipa": 25, "low_resolution_limit": [2, 134], "lower": [2, 4, 5, 6, 7, 8, 12, 18, 22, 24, 26, 36, 38, 40, 42, 43, 45, 47, 48, 49, 50, 59, 68, 101, 113, 114], "lowercas": 2, "lowest": [1, 2, 4, 5, 7, 8, 21, 23, 27, 39, 42, 47, 49, 50, 71], "lp": [2, 7, 23, 40, 42, 46, 49], "ls_number_reflns_r_fre": 47, "lspci": 9, "lt": 61, "ltd": [0, 3, 56], "ltest": 49, "lto": 40, "luenberg": [0, 3], "lung": 12, "lunin": [0, 3, 8], "lure": [0, 3], "lutterotti": 0, "lutz": 12, "luzzati": [0, 3], "lvert": [5, 7], "ly": [5, 7, 8, 49], "lyas": 12, "lysin": 8, "lyso01": 13, "lyso_ref": 40, "lyso_x10sa_90deg_1": 12, "lyso_x10sa_90deg_pair": 12, "lyso_x10sa_two_cryst": 12, "lysozym": [12, 26, 40, 46, 49, 55], "lyubimov": 0, "lz4": [0, 1, 2, 3, 5, 13, 21, 23, 44, 45, 55, 56, 57], "l\u00b2": 46, "m": [0, 1, 2, 3, 4, 6, 7, 8, 9, 12, 21, 23, 27, 30, 34, 38, 42, 45, 46, 49, 50], "m1": [26, 36, 43, 45, 59], "m153t": 12, "m2": 9, "m20": [9, 46], "m2g": [8, 47], "m3": 12, "m311if": 12, "m3159c": 12, "m336gk": 12, "m33inp": 12, "m33ky7": 12, "m33mc4": 12, "m33meb": 12, "m33p85": 12, "m33r6o": 12, "m34p8r": 12, "m35cc8": 12, "m35j23": 12, "m35jvn": 12, "m35mln": 12, "m35src": 12, "m35uth": 12, "m35vml": 12, "m36cdl": 12, "m36cee": 12, "m36f3p": 12, "m36fvz": 12, "m36fwc": 12, "m36h2p": 12, "m36h5t": 12, "m36hv2": 12, "m36i3j": 12, "m36jgh": 12, "m36jgi": 12, "m36jgj": 12, "m36ttn": 12, "m36u7g": 12, "m36ukf": 12, "m36v2r": 12, "m36vww": 12, "m36w4h": 12, "m36w75": 12, "m36yqf": 12, "m37atg": 12, "m37brr": 12, "m37dkp": 12, "m37k1l": 12, "m37kcn": 12, "m37l6j": 12, "m37mzt": 12, "m37orr": 12, "m37ph1": 12, "m37qi": 12, "m37ri": 12, "m37rji": 12, "m37tcd": 12, "m37yzx": 12, "m38a1a": 12, "m38agq": 12, "m38dqb": 12, "m38egn": 12, "m38iya": 12, "m38k1g": 12, "m38oic": 12, "m38pqd": 12, "m38qj5": 12, "m38r5r": 12, "m38sa8": 12, "m38sqo": 12, "m38sqq": 12, "m38sqt": 12, "m38t7r": 12, "m38tha": 12, "m38u0i": 12, "m38v4o": 12, "m38xbp": 12, "m38ys9": 12, "m39b22": 12, "m39bn8": 12, "m39crw": 12, "m39gjx": [12, 40], "m39hs7": 12, "m39i0a": 12, "m39ig7": 12, "m39ih9": 12, "m39jq9": 12, "m39jzo": 12, "m39mh4": 12, "m39o0h": 12, "m39p7q": 12, "m39pbb": 12, "m39rp9": 12, "m39sl0": 12, "m39vx7": 12, "m39vyb": 12, "m39w3y": 12, "m39yzk": 12, "m39z44": 12, "m39zm0": 12, "m39zmu": 12, "m5": 12, "m_q": 8, "m_u": 7, "m_v": 7, "ma": 2, "mac": [14, 18, 20, 26, 36, 40, 43, 45, 48, 59], "macaron": 56, "macdeployqt": 26, "machin": [0, 2, 4, 6, 8, 9, 14, 16, 21, 26, 28, 29, 36, 37, 38, 41, 42, 43, 45, 48, 49, 50, 52, 59, 123], "machineri": [0, 3, 4, 39, 48, 49], "maco": [2, 8, 9, 21, 38, 42, 43, 45, 47, 49, 55, 59, 61], "macro": [0, 8, 21], "macrocycl": 12, "macrodomain": 12, "macromolecul": 8, "macromolecular": [0, 3, 5, 8, 12, 23, 34, 50, 61, 68], "mad": [5, 12], "made": [1, 2, 4, 5, 6, 7, 8, 15, 17, 19, 21, 23, 25, 26, 29, 38, 39, 40, 42, 44, 46, 47, 49, 71, 109, 122], "magana": 0, "magenta": 50, "magic": [24, 42, 47], "magic_numb": 1, "magma": 0, "magnesium": 12, "magnet": [5, 42], "magnifi": [2, 26], "magnitud": [0, 4, 5, 6, 7, 46, 49], "magnolia": 12, "mai": [1, 2, 4, 5, 6, 7, 8, 17, 21, 23, 24, 27, 29, 39, 40, 42, 44, 46, 47, 48, 49, 50, 51, 53, 62, 136], "maia": [0, 3, 23], "mail": 29, "main": [8, 12, 21, 25, 38, 40, 49, 57], "main_lattice_intensity_pct": 49, "main_lattice_spots_pct": 49, "mainstream": 2, "maintain": [29, 40, 44], "major": [1, 2, 4, 5, 6, 7, 8, 22, 23, 29, 36, 42, 47, 49, 58], "make": [0, 1, 2, 4, 5, 6, 7, 8, 9, 12, 13, 14, 17, 19, 23, 25, 26, 27, 28, 29, 33, 36, 38, 39, 40, 42, 46, 47, 48, 49, 50, 52, 55, 56, 71, 96, 133], "maltophilia": 12, "manag": [0, 2, 3, 6, 9, 20, 36, 37, 40, 43, 45], "manakova": 0, "mandatori": 24, "mani": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 21, 23, 24, 25, 26, 36, 39, 42, 45, 47, 48, 49, 50, 52, 109], "manifest": [12, 13, 36, 40, 55, 56], "manifold": 56, "mannanas": 12, "manner": [17, 29, 140], "mannos": 12, "mannosamin": 12, "mannosylglycer": 12, "manual": [0, 2, 9, 18, 42, 59, 61, 97], "manufactur": [2, 4, 17, 29], "mao": 12, "map": [0, 1, 2, 3, 6, 7, 11, 12, 15, 16, 19, 21, 23, 24, 25, 26, 38, 39, 40, 41, 42, 44, 46, 47, 48, 50, 51, 55, 61, 62, 71, 120, 122, 123, 125, 128], "map_atom_sigma": 122, "map_coeffici": 1, "map_sigma": 49, "maps_from": [4, 39, 47, 49], "maps_prefix": 39, "maptofphigpu": 21, "mar": [13, 44], "marccd": [2, 5, 21, 26, 38, 42, 44, 45, 50, 59], "march": [13, 29, 36, 40, 45, 49], "march_dark_mbco_ii": 13, "margin": [4, 5, 6, 7, 8, 42, 47, 49], "maria": 0, "mark": [2, 4, 5, 7, 15, 21, 23, 24, 25, 29, 33, 38, 39, 40, 42, 44, 46, 47, 49, 50, 53, 56, 58, 68, 71, 92, 96], "marker": [2, 5, 7, 23, 50, 53], "markstein": 0, "marquardt": [4, 21, 56], "martin": 0, "mask": [0, 1, 2, 3, 4, 5, 7, 8, 13, 16, 21, 23, 24, 25, 26, 28, 29, 38, 40, 44, 45, 47, 48, 49, 50, 51, 54, 57, 62, 67, 71, 92, 103, 127, 128], "mask_bad": 44, "mask_chip_edg": [25, 92], "mask_edge_pixel": 44, "mask_fil": [13, 44], "mask_good": 44, "mask_module_edg": [25, 92], "mask_shar": 44, "masked_pixel": 66, "maskn_badbit": 44, "maskn_data": 44, "maskn_fil": 44, "maskn_goodbit": 44, "mason": 12, "mass": [0, 2, 7], "massif": 12, "massiv": 0, "master": [1, 2, 6, 7, 11, 12, 24, 25, 27, 38, 39, 40, 42, 44, 48, 49, 50, 53, 57, 59, 68, 71, 72, 86], "masterpiec": 30, "masui": 56, "match": [2, 4, 5, 6, 7, 10, 12, 14, 21, 23, 24, 33, 37, 39, 40, 42, 43, 44, 46, 47, 49, 71, 134], "mate": [0, 4, 5, 7, 8, 12, 21, 38, 39, 42, 46, 47, 49, 50], "matej": 27, "materi": [0, 1, 2, 7, 17, 29, 42, 47, 51], "materialis": 5, "math": [0, 2, 3, 8], "mathbf": [4, 5, 6, 7, 8], "mathcal": 7, "mathemat": [0, 8], "mathrm": [4, 5, 6, 7, 8], "mathsf": [4, 7], "matplotlib": 0, "matric": [0, 3, 8], "matrix": [0, 3, 6, 8, 11, 12, 18, 23, 39, 46], "matteo": 56, "matter": [1, 4, 5, 6, 7, 11, 23, 25, 36, 39, 40, 41, 44, 46, 47, 49, 50, 51, 53, 65, 107], "matthew": [0, 3, 4, 47, 49, 56], "matur": 2, "mat\u011bj": [0, 34], "mauguin": [1, 2, 4, 23, 38, 42], "max": [1, 2, 5, 6, 7, 12, 15, 20, 23, 24, 26, 27, 34, 40, 42, 56, 68, 82, 106, 133, 136], "max_adu": 53, "max_allowed_pixel_count": 67, "max_backpressure_timeout_m": [24, 136], "max_count": 1, "max_extra_lattic": [1, 23], "max_frames_with_sign": 67, "max_hkl": 64, "max_image_numb": [1, 91], "max_image_number_s": 101, "max_n": 6, "max_pix_per_spot": 134, "max_receiver_delai": [1, 23, 101], "max_spot": 23, "max_spot_count": [1, 2, 68], "max_valu": 23, "max_viable_pixel_valu": 1, "max_x_pxl": [23, 114], "max_y_pxl": [23, 114], "maxc": 1, "maxim": [1, 6, 7], "maxima": 8, "maximis": [5, 7, 42], "maximum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 15, 16, 17, 20, 21, 23, 24, 38, 40, 42, 48, 49, 50, 67, 68, 80, 113], "maxm": 46, "mb": [5, 13, 27, 36, 45], "mbco": 13, "mbco_march": 13, "mbco_march_mask": 13, "mbed": 56, "mbedtl": 56, "mbit": 45, "mc": [9, 14, 23, 28, 36], "mccd": 44, "mcclure": [0, 8], "mccoi": [0, 3, 4], "mcnichola": [0, 8], "mcse": 0, "mcsta": 23, "md": [0, 2, 3, 8, 12, 13, 40, 45, 47, 49, 51, 55, 56], "me": 23, "mea": [2, 4, 6, 7, 12, 39, 49, 50], "mean": [0, 1, 2, 4, 5, 6, 7, 8, 15, 17, 18, 19, 20, 21, 23, 24, 26, 27, 29, 39, 42, 44, 46, 47, 49, 50, 53, 55, 58, 67, 68, 71, 98, 109, 122, 124, 128, 129, 133, 134, 136, 138, 139, 140], "mean_atom_density_sigma": 2, "meaning": [0, 2, 3, 5, 7, 46], "meaningfulli": 4, "meaningless": [4, 40], "meant": [4, 7, 26, 46], "measur": [0, 1, 2, 3, 4, 5, 6, 8, 11, 12, 13, 23, 24, 25, 26, 29, 30, 33, 38, 39, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 54, 55, 57, 60, 68, 70, 71, 77, 88, 97, 98, 100, 109, 120, 124, 134], "measurement_statist": [71, 101], "measurement_statistics_dict": 101, "measurement_statistics_from_dict": 101, "measurement_statistics_inst": 101, "measurementstatist": [62, 71, 100], "mechan": [0, 2, 3, 5, 7, 8, 12, 14, 19, 22, 23, 24, 55, 62], "median": [0, 2, 4, 5, 6, 7, 8, 21, 40, 42, 49, 50], "medic": 0, "medicago": 12, "medium": [2, 12, 17, 23, 29, 42, 46], "meet": [0, 2, 3, 5, 7, 8, 11, 29, 30, 46, 49, 68], "megapixel": 134, "meliloti": 12, "melitensi": 12, "mellanox": [18, 22], "melman": 56, "member": [1, 2, 4, 7, 13, 41, 47, 49, 50, 55], "membran": 12, "memo": 6, "memori": [0, 2, 3, 4, 5, 6, 8, 16, 21, 22, 25, 38, 42, 47, 51, 96], "mend": 8, "mendon\u00e7a": [0, 34], "menu": [2, 7, 29, 36], "mer": 12, "merchant": [17, 29], "mere": [4, 5, 7, 12, 29, 49, 50, 51, 62], "merg": [1, 2, 3, 6, 8, 12, 13, 23, 25, 26, 29, 30, 38, 40, 41, 44, 45, 46, 47, 48, 50, 54, 55, 57, 61, 68, 71, 108, 121, 122, 123, 124, 125, 128, 131], "merging_statist": [2, 7, 46, 50], "merit": [0, 4, 8, 47, 49], "merki": 0, "merohedr": [2, 4, 7, 8, 12, 39, 40, 47, 48, 49], "merohedri": 0, "merritt": [0, 8], "mesnet": [0, 34], "messag": [2, 14, 18, 20, 23, 24, 25, 27, 28, 39, 42, 44, 45, 51, 54, 57, 62, 65, 68, 71, 85, 91, 125, 140], "message_sever": 65, "met": [4, 8, 29], "met16gli": 12, "meta": 56, "metadata": [0, 2, 12, 16, 19, 25, 26, 27, 38, 42, 44, 46, 50, 51, 62, 68, 71, 86, 97, 138], "metadata_mmcif": 1, "metal": [0, 2, 3, 4, 12, 26, 36, 40, 45, 46, 47, 49, 56, 97], "metal_contact": [1, 49], "metaljet": 12, "meter": 27, "metformin": 12, "method": [2, 3, 4, 7, 8, 21, 29, 49, 62, 71, 109, 110], "methyl": [8, 12], "methyladenosin": 8, "methylcytidin": 8, "methylguanosin": 8, "methyltransferas": 12, "meti": 2, "metric": [0, 2, 3, 4, 6, 7, 8, 12, 26, 28, 39, 40, 42, 47, 49], "metrologi": 44, "mev": 0, "meyer": 0, "mf_o": [4, 8], "mfo": [0, 1, 2, 3, 8, 25, 38, 39, 47, 49, 50, 71, 120, 123], "mfx": 13, "mfxl1013721": 13, "mfxlu5017": 13, "mg": [4, 8, 47, 49], "mg2": [0, 3, 8], "mg\u00b2": [0, 8], "mhggh": 12, "mi": [2, 7, 46, 49, 51, 53], "mib": [19, 25, 71, 99], "micro": 2, "microblaz": 20, "microcryst": [0, 5, 49], "micromax": 12, "microsecond": [2, 80], "mid": [5, 27, 40, 50], "middl": [1, 2, 5, 11, 26], "middot": [43, 59, 61], "mie": 0, "might": [2, 6, 11, 19, 22, 29, 71, 80, 140], "miller": [0, 1, 2, 5, 6, 7, 23, 46, 56], "miller_arrai": 46, "milli": 2, "millimetr": [5, 44, 49], "million": [0, 45], "millisecond": [2, 5, 136, 138, 139], "mill\u00e1n": [0, 3], "mimet": 12, "mimic": 4, "mimick": 12, "min": [2, 4, 5, 6, 7, 8, 12, 13, 21, 23, 42, 46, 47, 49, 50], "min_count_time_n": [72, 74], "min_frame_time_n": [72, 74], "min_image_numb": 91, "min_ligand_distance_a": 49, "min_pix_per_spot": 134, "min_valu": 23, "min_viable_pixel_valu": 1, "min_x_pxl": [23, 114], "min_y_pxl": [23, 114], "mind": [46, 50], "mine": 0, "mini": [12, 45], "minibind": 12, "minicbf": [0, 2, 5, 12, 21, 26, 38, 41, 42, 44, 45, 50, 59], "minim": [1, 6, 7, 19, 57], "minimis": [0, 3, 4, 6, 7, 21, 47, 56], "minimum": [1, 2, 6, 7, 15, 16, 20, 23, 36, 42, 46, 72, 80, 96, 113], "minimum_valid_pixel_valu": 53, "miniprotein": 12, "minocyclin": 12, "minor": [0, 1, 2, 3, 4, 36, 42, 47, 58], "minpk": [0, 7, 42, 49], "mint": [0, 51], "minu": [2, 7, 20, 49, 98], "minut": [6, 8, 21, 25, 27, 38, 40, 42, 45, 47, 50, 55, 71], "mirabili": [12, 38, 40], "mirror": [1, 2, 4, 6, 7, 23, 25, 41, 42, 44, 49, 72, 75, 77], "mirror_i": [1, 2, 11, 23, 25, 42, 44, 68, 72, 75, 77], "misalign": [7, 50], "misbehav": [2, 71], "misc": [2, 9, 19], "misdescrib": 6, "misfit": 49, "misjudg": 4, "mislead": [6, 23], "mismatch": [2, 4, 7, 39], "misori": 49, "misorient": 49, "mispredict": 6, "misrepresent": 29, "miss": [0, 1, 2, 4, 5, 6, 7, 8, 16, 23, 38, 39, 40, 42, 46, 47, 49, 50, 68, 71], "mistaken": 39, "mistreat": 49, "mistyp": 51, "mit": 56, "mitig": 51, "mix": [2, 6, 7, 39, 42, 45, 47, 49, 50], "mixtur": 4, "mkdir": [9, 14, 25, 38, 43, 45, 59], "ml": 2, "mle": 7, "mm": [1, 2, 5, 6, 7, 12, 21, 38, 41, 42, 49, 68, 107, 109, 110], "mmap": 19, "mmc": [5, 6, 41], "mmcif": [1, 2, 4, 7, 8, 25, 26, 38, 40, 42, 44, 46, 47, 48, 49, 50, 56, 71], "mmm": [4, 12], "mmp": 12, "mn": [8, 12], "mnsc": 0, "mode": [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 14, 18, 19, 20, 23, 24, 26, 28, 29, 34, 38, 40, 44, 46, 49, 50, 52, 53, 56, 57, 60, 62, 68, 71, 89, 108, 109, 128, 129], "model": [1, 2, 3, 6, 13, 22, 23, 25, 26, 29, 30, 35, 36, 42, 44, 45, 46, 48, 50, 54, 55, 56, 57, 60, 61, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "model_change_of_basi": [2, 39, 47, 49], "model_check": 40, "model_choice_decided_bi": 49, "model_choice_file_prefix": [39, 47, 49], "model_choice_space_group": [39, 47, 49], "model_choice_twin_law": 49, "model_decisions_taken": [47, 49], "model_enantiomorph_adopt": [47, 49, 50], "model_error": [1, 8], "model_fil": 49, "model_fit": [38, 39, 47, 49, 50], "model_fit_null_": 49, "model_fit_null_mean": 49, "model_fit_null_repl": 49, "model_fit_null_sd": 49, "model_fit_sigma": [4, 47, 49], "model_fit_statist": 49, "model_fit_valu": 49, "model_hand": [47, 49], "model_indexing_margin": 49, "model_indexing_margin_nul": 49, "model_indexing_margin_sigma": [39, 47, 49], "model_indexing_oper": [47, 49], "model_load": 129, "model_nam": 122, "model_not_valid": 49, "model_numb": 1, "model_plac": [4, 39, 40, 42, 47, 49], "model_radial_misfit": [4, 39, 49], "model_setting_as_read": [2, 49], "model_size_byt": 129, "model_space_group": [47, 49], "model_space_group_nam": 1, "model_v": [47, 49], "model_v6": [38, 50], "model_valid": [39, 47, 49], "model_validation_reason": [39, 47, 49], "modelcif": [4, 38, 39, 42, 47, 49], "modeldensitygpu": 21, "modeldensitymet": 21, "modelmaskgpu": 21, "modelscalegpu": 21, "modelstructurefactorsgpu": 21, "moder": 8, "modern": [0, 23], "modif": [0, 2, 8, 17, 29, 39], "modifi": [2, 8, 17, 29, 47, 57, 61], "modprob": 19, "modul": [0, 1, 2, 3, 4, 5, 7, 9, 11, 12, 13, 15, 16, 18, 19, 20, 21, 22, 25, 26, 28, 33, 37, 38, 41, 42, 48, 49, 50, 53, 55, 68, 71, 72, 74, 75, 77, 82, 92, 135], "modular": 2, "module_0": [2, 23, 44], "module_00": 23, "module_1": [23, 44], "module_15": 23, "module_7": 23, "module_n": 2, "module_nn": [25, 44, 68], "module_numb": 66, "module_offset": [2, 23], "module_plac": [23, 25, 42, 44, 68, 75, 77], "module_sync": [25, 72], "modules_in_row": [25, 135], "modulesumm": 2, "modulo": [2, 5, 7, 8], "moeck": 0, "mol": [0, 2, 3, 8], "molecul": [0, 2, 3, 4, 6, 7, 8, 12, 38, 40, 42, 44, 47, 48, 49, 134], "molecular": [2, 3, 8, 25, 26, 36, 38, 39, 40, 42, 43, 45, 47, 48, 50, 61, 71, 122], "molecularreplacementgpu": 21, "molecularreplacementmet": 21, "molprob": [8, 46, 47], "moment": [0, 1, 2, 3, 4, 7, 8, 9, 11, 15, 22, 24, 25, 42, 46, 49, 68, 71], "monitor": [2, 5, 9], "monkei": 12, "mono": 46, "monoamin": 12, "monochrom": [7, 12], "monochromat": [1, 2, 7, 12, 42], "monoclin": [0, 1, 2, 3, 4, 6, 7, 8, 39, 49], "monocytogen": 12, "monofluorobutano": 12, "monom": [0, 8, 40, 47, 56], "monomer": 12, "monophosph": 12, "monoton": [4, 6, 7], "monoval": 0, "mont": 6, "montero": 0, "more": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 19, 21, 22, 23, 24, 25, 26, 27, 29, 33, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 49, 50, 55, 68, 71, 96, 98], "moreau": [0, 3, 5], "moreov": 29, "moriarti": 0, "morsh": [0, 8], "mosaic": [0, 1, 2, 3, 6, 21, 23, 26, 42, 44, 50, 55, 134], "mosaicity_deg": 49, "mosaicity_deg_p10": 49, "mosaicity_deg_p90": 49, "mosflm": [0, 3], "most": [0, 2, 4, 5, 6, 7, 8, 12, 13, 19, 21, 23, 25, 26, 27, 29, 33, 35, 38, 40, 41, 42, 44, 45, 46, 47, 49, 50, 51, 59, 68, 71, 89, 123], "mostli": [0, 5, 6, 7, 10, 23, 40, 49, 65], "motif": 12, "motion": [0, 8], "mount": [1, 2, 4, 5, 6, 23, 44, 49], "mountain": 30, "mous": [0, 2, 12], "move": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 21, 23, 25, 26, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 55, 56, 69, 101, 107], "movement": 4, "movi": 2, "mozzanica": [0, 34], "mp": [5, 45, 132], "mp2": 12, "mpag": 12, "mpccd": [2, 13, 44], "mpd": [8, 47], "mper": 12, "mpl": [0, 56], "mpro": 12, "mr": [0, 2, 4, 39, 40, 42, 46, 47, 48, 49, 50, 122], "mr_": [47, 49], "mr_anomalous_invert": 49, "mr_auto": 46, "mr_copi": 49, "mr_d_min": 122, "mr_decis": [38, 47, 49, 50, 122], "mr_enantiomorph": [47, 49], "mr_group": 40, "mr_hand_check": 49, "mr_hand_fit_sigma": 49, "mr_model_kind": [47, 49], "mr_pae_domain": 49, "mr_search_devic": 49, "mr_search_model": [42, 49], "mr_second": 40, "mr_space_group": [40, 122], "mrsa252": 12, "mse": [8, 47], "msg": 85, "msg_zerocopi": 24, "msvc": [2, 26, 36, 40, 52, 59], "msvc2022_64": [26, 36], "mto": [14, 18], "mtp": [14, 18], "mtu": 18, "mtz": [0, 1, 2, 4, 6, 7, 8, 23, 25, 26, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 55, 57, 71], "mtz2sca": [2, 46], "mtzdump": 39, "mtzinfo": 46, "mu": 7, "mu_b": 5, "much": [0, 2, 4, 5, 6, 7, 8, 22, 23, 26, 36, 39, 40, 42, 45, 47, 48, 49], "multi": [0, 2, 4, 7, 23, 42, 44, 134], "multi_twin": [8, 49], "multi_untwin": [8, 49], "multidimarrai": 1, "multidomain": [0, 3], "multilay": [7, 12], "multipixel": [33, 92], "multipl": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 22, 23, 24, 25, 26, 27, 38, 39, 41, 42, 46, 48, 49, 50, 68, 71, 124, 125, 140], "multiple_lattic": [38, 49], "multipli": [1, 4, 5, 6, 7, 8, 15, 23, 45, 46, 80], "multisweep": 12, "multiwavelength": [0, 3], "muon": 97, "murc": 12, "murd": 12, "murshudov": [0, 3, 8, 12], "muscl": 12, "must": [1, 2, 4, 5, 6, 10, 12, 14, 17, 19, 22, 23, 24, 25, 29, 36, 37, 38, 40, 41, 42, 44, 47, 49, 51, 55, 58, 62, 63, 68, 70, 71, 133, 134], "mustyakimov": 0, "mut148233": 12, "mut148591": 12, "mutant": [0, 8, 12], "mutex": 2, "mw": 46, "mx": [0, 1, 2, 5, 6, 7, 12, 26, 28, 36, 37, 38, 39, 40, 44, 45, 46, 47, 49, 50, 52, 55, 57, 61, 62, 69, 72], "mx1": 12, "mx2": 12, "mx225": 13, "mx340": 13, "mxanalyz": 2, "mxrdr": [0, 12], "my": [0, 3], "my_run": 27, "my_sampl": 27, "mycobacterium": 12, "mycolicibacterium": 12, "myob_x10sa": 40, "myoglobin": [0, 40], "myrothecium": 12, "myrun": [38, 42, 46, 50], "myrun_blob": 38, "myrun_cca": 46, "myrun_ct": 46, "myrun_detector": 38, "myrun_log": 38, "myrun_map": 38, "myrun_model": 38, "myrun_mr": 46, "myrun_plot": 38, "myrun_process": [42, 50], "myrun_refined_map": 38, "myrun_refined_model": 38, "myrun_report": [38, 49], "myrun_solv": 38, "myrun_unmerg": [38, 46], "m\u00e4nts\u00e4l\u00e4": [0, 3], "m\u00f6nch": 30, "m\u00fcller": 0, "n": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 15, 16, 21, 26, 36, 38, 39, 40, 42, 44, 45, 46, 47, 49, 50, 55, 62, 71, 72, 80], "n185a": 12, "n2": 8, "n6": 8, "n7": 8, "n7_ligand": 8, "n7_off_plan": 8, "n_": [4, 5, 6, 7], "n_b": [5, 7], "n_fast": [1, 23, 90], "n_imag": [23, 49], "n_ob": 124, "n_site": 46, "n_slow": 1, "n_uniqu": 124, "na": [0, 4, 8, 47, 49], "nabla": 8, "nad": [8, 12, 47], "nadh": 8, "nadp": [8, 12], "nadph": [8, 12], "nai": [8, 47], "naleem": [0, 8], "name": [0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 13, 17, 23, 24, 25, 26, 27, 28, 29, 34, 36, 37, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 51, 53, 55, 56, 57, 61, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "namesak": 49, "nan": [0, 1, 2, 6, 7, 23, 34, 49, 50], "nanosecond": [2, 72], "nap": [8, 47], "nar": 0, "narrow": [4, 5, 6, 7, 8, 12, 26, 42, 49, 134], "nass": [0, 13], "nat": [0, 3, 4, 12, 13], "nation": [0, 8, 30], "nativ": [0, 2, 3, 4, 12, 23, 26, 36, 44, 46, 49, 50, 55], "natl": [0, 3], "nato": [0, 3], "natur": [0, 3, 7, 8, 13, 14, 17, 23, 29], "navaza": [0, 3, 4], "navig": [2, 26, 35], "na\u00efv": 7, "nbuffer": 19, "nc": [0, 2, 3, 4, 8, 12, 21, 40, 47, 49], "nci": 13, "ncomms10882": 0, "ncpu": [26, 45], "ncyc": 46, "ndp": [8, 47], "ne": [7, 8], "near_extinct_class": 49, "nearer": [5, 6, 42, 49, 50], "nearest": [4, 6, 7, 8, 23, 36, 39, 47, 49, 133], "nearest_atom": [1, 49, 120], "nearest_atom_dist": 1, "nearest_atom_distance_a": [49, 120], "nearest_ion_a": 49, "nearest_negative_a": 49, "nearest_positive_a": 49, "nearli": [2, 4, 5, 6, 7, 12, 49], "necessari": [9, 14, 17, 18, 19, 25, 29, 86, 137], "necessarili": [4, 6, 17], "need": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 14, 15, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 36, 37, 38, 39, 41, 42, 43, 44, 45, 46, 47, 49, 50, 52, 53, 54, 55, 59, 60, 61, 62, 71, 72, 96, 111], "neg": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 21, 23, 27, 38, 39, 42, 46, 47, 49, 53, 68, 90, 126], "negat": [6, 11, 23, 46, 49], "negative_within_3": 49, "neggia": [23, 53, 55, 86], "neglig": [7, 17, 50], "negoti": [9, 18], "neighbor": 15, "neighbour": [0, 4, 5, 6, 7, 8, 21, 42, 49, 57], "neither": [0, 4, 5, 6, 7, 8, 9, 12, 23, 25, 26, 29, 36, 38, 39, 40, 42, 44, 45, 46, 49, 50, 52, 63], "neon": 40, "nersc": 13, "nest": [6, 7, 23, 40], "net": [2, 4, 7, 24, 27], "netbsd": 56, "network": [1, 2, 5, 14, 16, 20, 24, 26, 28, 29, 40, 42, 45, 51, 52, 54, 57, 62, 71, 136, 138, 139, 140], "neu5ac": 12, "neural": 2, "neuraminidas": [0, 8], "neutral": 8, "neutron": [0, 3, 97], "never": [0, 2, 4, 5, 6, 7, 8, 11, 12, 19, 21, 23, 24, 25, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 55, 56, 68], "nevertheless": 4, "neviani": 12, "new": [0, 2, 3, 4, 6, 7, 8, 17, 19, 40, 47, 49, 51, 60, 71, 91], "newer": [2, 14, 26, 36, 40, 43, 45, 52, 53, 59, 86], "newest": 45, "newli": 2, "newslett": 0, "newton": [0, 3, 8], "newvil": 56, "next": [0, 2, 3, 4, 5, 6, 7, 8, 23, 24, 25, 26, 29, 36, 38, 39, 40, 42, 46, 47, 48, 50, 51, 59, 71, 125, 126], "nextgendcu": [0, 9], "nexu": [1, 9, 27, 28, 50, 53, 54], "nexusformat": 97, "ng": [52, 56], "nginx": 51, "nguyen": 13, "nh1": 8, "nh2": 8, "nhr": 12, "nh\u2084": 8, "ni": [0, 3, 8], "nichol": [0, 8], "nickel": 12, "nidpp": 12, "niel": 56, "niemi": [0, 3], "niermann": 0, "nifes": 12, "niggli": [0, 1, 2, 3, 4, 6, 23, 40, 48, 49], "niggli_class": 1, "niggliclass": 23, "nimag": [23, 27], "nimages_collect": 23, "nimages_per_trigg": 2, "nimages_written": 23, "nine": [4, 7, 47, 49], "ninja": [26, 36, 52], "nist": [0, 2, 7, 42], "nitroanilin": 12, "nitrogen": [0, 3, 7, 8], "nitroreductas": [12, 40], "nlohmann": [2, 56], "nmeth": 0, "nmodul": [25, 74, 135], "no_diffract": [23, 49], "no_ind": 49, "no_index": 44, "no_lattic": 49, "no_twin_law": [4, 8, 49], "nobl": 37, "nobodi": [1, 6, 12, 23, 27, 40, 90], "noced": [0, 3, 8], "nocuda": [2, 36, 37], "nod": 30, "node": [0, 2, 6, 49, 52], "nofil": 27, "nofilewritten": 86, "nogpgcheck": 37, "nois": [2, 4, 5, 6, 7, 15, 20, 21, 40, 42, 48, 49, 50, 55, 134], "noisi": [0, 7, 33, 49, 53], "noisier": 49, "nomenclatur": [0, 3], "nomin": [4, 5, 6, 11, 44], "non": [0, 1, 2, 4, 5, 6, 7, 8, 9, 12, 14, 15, 17, 24, 25, 26, 27, 28, 29, 33, 38, 39, 40, 41, 42, 44, 45, 46, 49, 50, 53, 68, 96, 108, 109], "noncommerci": 29, "noncrystallograph": [0, 3, 8], "none": [1, 2, 4, 5, 6, 7, 8, 12, 13, 15, 21, 23, 24, 36, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 52, 55, 71, 89, 93, 94, 95, 99, 122, 125, 131], "nonetheless": 6, "nonlinear": [0, 3], "nonstandard": 26, "nonzero": 1, "nor": [0, 4, 5, 6, 7, 8, 9, 17, 21, 25, 26, 29, 36, 40, 42, 46, 49, 50, 52], "normal": [1, 2, 4, 5, 6, 7, 8, 11, 14, 17, 23, 24, 26, 27, 29, 41, 42, 44, 45, 46, 49, 51, 55, 67], "normalis": [0, 1, 2, 4, 6, 7, 8, 21, 40, 46, 48, 49], "nospaceleft": 24, "not_a_trend": 50, "not_applic": 49, "not_comput": 49, "not_connect": 81, "not_converged_reason": [41, 109], "not_detect": 49, "not_determin": [4, 46, 49], "not_measur": [25, 49, 131], "not_perform": [39, 42, 47, 49], "not_plac": [4, 39, 47, 49, 122], "not_read": 49, "not_run": 40, "not_solv": 49, "not_test": 49, "notabl": [1, 2], "notar": [26, 36, 43, 45, 59], "notarize_maco": 26, "notarytool": 26, "notat": [0, 2, 3, 7], "notch": 26, "note": [2, 6, 7, 9, 12, 20, 22, 25, 26, 36, 37, 38, 43, 44, 49, 50, 51, 52, 58, 59, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "noth": [2, 4, 5, 6, 7, 8, 11, 12, 21, 23, 24, 25, 26, 27, 29, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 71, 108, 110, 121, 122], "notic": [2, 4, 5, 17, 26, 29, 36, 49, 52, 53, 61], "notif": [2, 27, 140], "notifi": [17, 29], "notwithstand": 29, "novel": [0, 3, 8], "novo": [0, 2, 5, 6, 7, 12, 38, 42, 47, 48, 50], "now": [2, 4, 5, 6, 7, 12, 19, 26, 40, 125], "nowher": [4, 8, 36, 39, 41, 44, 47, 49], "np": 33, "npeak": 23, "npixel": 23, "nproc": [27, 45, 55], "nprot": 0, "nrngs4": [12, 40], "nsb0497": 0, "nsi": [26, 36], "nsl": 12, "nsp10": 12, "nsp15": 12, "nsp16": 12, "nsp3": 12, "nsrrc": 12, "nsy": 40, "ntd": 12, "nth_element": 21, "ntrigger": [23, 68], "nu": 21, "nuclear": 0, "nucleic": [0, 3, 8], "nucleobas": [0, 3, 8], "nucleocapsid": 12, "nucleotid": [2, 8, 12, 47], "null": [0, 2, 3, 5, 6, 7, 8, 21, 25, 38, 39, 40, 47, 48, 49], "null_sigma": [47, 49], "num": [2, 42], "num_connect": 24, "numa": 2, "numa_polici": 99, "number": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 13, 15, 17, 19, 20, 21, 23, 24, 25, 26, 27, 29, 38, 39, 41, 42, 43, 44, 45, 46, 47, 49, 50, 51, 56, 57, 60, 63, 65, 67, 68, 71, 74, 80, 90, 91, 93, 96, 99, 101, 103, 109, 121, 133, 134, 135, 136, 140], "number_of_cycl": 23, "number_of_fram": 67, "number_of_imag": [1, 71], "number_of_triggers_left": 82, "numer": [0, 1, 2, 3, 7, 12, 55, 63, 68], "numpi": [33, 40, 50], "nvcc": [26, 40], "nvecsum": [8, 49], "nvidia": [2, 9, 21, 22, 26, 29, 38, 40, 43, 45, 49, 50, 52, 56, 59, 61], "nvtx3": 40, "nwriter": [24, 136], "nx": [2, 133], "nx_class": 23, "nxcollect": 23, "nxdetector_modul": [42, 44], "nxmx": [1, 2, 5, 7, 9, 11, 12, 26, 27, 28, 33, 38, 39, 41, 42, 44, 50, 51, 53, 55, 59, 61, 68, 71, 90, 97], "nxmxintegr": [23, 27, 53, 86], "nxmxlegaci": [2, 23, 27, 53, 86], "nxmxonlydata": 86, "nxmxvd": [2, 23, 27, 53, 86, 87], "nxsourc": [1, 97], "nxtransform": 1, "ny": [2, 133], "nyeso1": 12, "nyook": 30, "nz": 8, "o": [0, 2, 3, 4, 5, 6, 7, 8, 9, 12, 24, 26, 34, 36, 37, 38, 39, 40, 41, 42, 45, 46, 47, 49, 50, 55, 71], "o2": [2, 12], "o6": 8, "oF": 23, "ob": [2, 4, 6, 7], "obei": [2, 12], "object": [0, 1, 2, 7, 17, 23, 27, 29, 49, 57, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "oblig": [0, 17, 29], "obliqu": [0, 4, 5, 7, 8, 12, 23, 39, 46, 49], "obs_i": 1, "obs_label": 46, "obs_x": 1, "observ": [0, 1, 2, 3, 4, 5, 8, 12, 13, 21, 23, 25, 38, 39, 42, 45, 46, 49, 50, 124], "observations_reject": [4, 49], "observations_rejected_overload": [7, 46, 49, 50], "observations_rejected_wilson": [4, 49], "observed_fram": 23, "observed_i": 23, "observed_px_x": 23, "observed_x": 23, "obsolet": [12, 19], "obstacl": 6, "obstruct": 5, "obtain": [0, 3, 6, 8, 9, 12, 17], "obtus": [2, 7], "obvers": [0, 6], "oc": [6, 132], "occasion": 29, "occup": [0, 1, 4, 5, 7, 8, 24, 39, 47, 49], "occupi": [7, 49], "occur": 29, "octahedr": 8, "octahedron": 8, "octet": [25, 71], "odd": [4, 7, 50], "oeffner": [0, 3, 4], "off": [0, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 15, 18, 21, 25, 26, 38, 40, 42, 44, 45, 46, 47, 48, 49, 50, 51, 55, 62, 68, 71, 72, 75, 77, 92, 134], "offer": [2, 4, 5, 6, 12, 17, 18, 26, 29, 42, 47, 50], "offici": [12, 29], "offlin": [1, 2, 4, 5, 6, 7, 22, 23, 25, 26, 36, 37, 38, 42, 52, 57, 134], "offset": [1, 2, 5, 7, 9, 11, 21, 23, 41, 44, 45, 46, 49, 50], "offset_unit": 2, "often": [1, 4, 5, 6, 8, 11, 24, 26, 38, 40, 45, 49, 50], "og1": 120, "oh": 12, "ohl": [2, 17, 29, 56], "oi": 1, "ojala": 0, "ok": [2, 9, 19, 22, 24, 25, 40, 49, 50, 71, 104, 125, 131, 138, 139, 140], "old": [2, 5, 25, 40, 42, 51], "older": [23, 36, 40, 42, 53, 91], "oldest": [26, 36], "olex2": 46, "oligomeris": 12, "omc": [8, 47], "omega": [1, 5, 6, 12, 23, 119], "omg": [8, 47], "omit": [1, 2, 7, 23, 25, 27, 41, 42, 49, 51, 53, 63, 68, 71, 108, 113, 134], "omu": [8, 47], "on_gpu": 123, "onc": [0, 1, 2, 4, 5, 6, 7, 8, 12, 21, 24, 25, 26, 28, 38, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 55, 68, 71, 125, 126], "one": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 13, 14, 18, 19, 20, 21, 22, 24, 25, 26, 27, 28, 29, 30, 31, 33, 34, 35, 36, 38, 39, 41, 42, 43, 44, 45, 46, 47, 48, 50, 51, 53, 55, 56, 57, 59, 60, 61, 68, 71, 72, 75, 77, 90, 91, 108, 109, 110, 124, 125, 131, 135], "oneapi": 52, "ones": [0, 2, 3, 4, 5, 6, 7, 8, 12, 14, 21, 23, 25, 26, 36, 38, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 55, 71, 107], "ongo": 51, "onitroanilin": 12, "onli": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 17, 18, 19, 21, 22, 23, 24, 25, 26, 27, 29, 30, 31, 33, 36, 37, 38, 39, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 55, 56, 57, 59, 60, 62, 63, 65, 68, 71, 72, 75, 77, 86, 89, 91, 92, 101, 107, 124, 134, 139], "onlin": [2, 5, 22, 26, 36, 38, 43, 44, 45, 60, 134], "onlyjfjoch": 59, "onlyjfjoch_view": 59, "onlyrugnux": 43, "onto": [0, 4, 6, 7, 8, 12, 23, 36, 40, 44, 49, 59], "onward": [5, 44, 45], "oom": 45, "oopsla": 0, "oosterheert": 12, "op": [2, 4, 7, 50], "opaqu": [1, 5], "open": [0, 1, 2, 3, 4, 5, 6, 8, 9, 12, 13, 19, 24, 25, 36, 38, 39, 40, 42, 44, 46, 47, 48, 49, 50, 51, 59, 61], "openair": 0, "openapi": [1, 2, 9, 25, 29, 36, 41, 44, 54, 58, 62], "openapitool": 62, "openbla": 2, "openssl": 2, "oper": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 14, 15, 16, 18, 19, 20, 21, 22, 23, 24, 25, 27, 29, 30, 38, 39, 40, 42, 46, 48, 49, 51, 60, 65, 71, 92, 93, 134, 139, 140], "operatornam": 7, "opinion": 46, "oppos": 23, "opposit": [2, 4, 5, 6, 7, 11, 12, 23, 46, 49, 50], "opt": [2, 7, 9, 12, 25, 36, 40, 45, 47, 53], "optic": [18, 23, 97], "optim": [0, 2, 3, 4, 6, 8, 9, 19, 91, 104], "optimis": [6, 36], "optimist": [4, 7, 46, 47], "optimum": 55, "option": [1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 15, 21, 22, 24, 25, 26, 28, 29, 36, 38, 40, 43, 44, 49, 50, 51, 52, 53, 55, 57, 61, 62, 63, 65, 68, 69, 71, 72, 74, 80, 87, 89, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 115, 119, 120, 122, 123, 124, 125, 126, 127, 128, 129, 131, 132, 133, 134, 135, 136, 138, 139, 140], "opu": 0, "orang": [18, 25], "orbit": [2, 4, 7, 8, 47], "order": [0, 1, 2, 3, 4, 5, 6, 7, 16, 20, 21, 22, 23, 24, 25, 27, 29, 38, 39, 40, 42, 44, 46, 47, 48, 49, 50, 53, 68, 77, 125, 132], "ordin": [46, 49, 50], "ordinari": [2, 4, 5, 7, 8, 12, 23, 38, 40, 43, 45, 49, 53], "oren": [0, 3, 8], "org": [0, 3, 12, 13, 26, 29, 38, 62, 97], "organ": [0, 3, 8, 29, 46], "orgi": [1, 2, 11, 23, 46, 49], "orgx": [1, 2, 11, 23, 46, 49], "orient": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 21, 23, 38, 39, 41, 42, 44, 46, 47, 48, 49, 53, 89, 122, 133], "orientationonli": 89, "origin": [0, 4, 8, 11, 12, 13, 17, 23, 26, 29, 40, 46, 47, 49, 53, 55, 56, 92], "original_image_id": 1, "orsai": 12, "orthogon": 11, "orthogonalis": 46, "orthorhomb": [1, 2, 4, 6, 7, 8, 12, 39, 49], "os": 9, "oscil": [0, 3, 6, 7, 12], "oscillation_axi": 11, "oscillation_rang": 49, "osinski": 0, "osrt": 40, "other": [2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 17, 18, 19, 21, 22, 24, 25, 29, 30, 33, 36, 38, 39, 40, 41, 42, 44, 47, 48, 49, 50, 52, 53, 55, 56, 57, 59, 61, 62, 68, 71, 93, 109], "other_cell_form_": 49, "other_cell_form_cel": 49, "other_cell_form_fract": 49, "other_cell_form_fram": 49, "otherwis": [1, 2, 4, 5, 6, 7, 8, 9, 12, 17, 21, 23, 24, 25, 27, 29, 35, 36, 39, 40, 42, 44, 45, 46, 47, 49, 50, 56, 57, 68, 71, 80, 87, 122, 123], "otwinowski": [0, 3], "our": [11, 18, 21, 22, 29, 38, 53], "ourselv": [0, 12, 13], "out": [0, 2, 3, 4, 5, 6, 7, 8, 12, 13, 17, 21, 23, 24, 25, 26, 27, 28, 29, 30, 34, 35, 36, 38, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 51, 55, 68, 71, 80, 82, 92, 107, 109, 111, 121, 122, 123], "out_report": 49, "outcom": [5, 21, 23, 27, 57], "outer": [5, 6, 7, 8, 47, 49], "outermost": 7, "outgo": [22, 24], "outgrew": 7, "outgrow": [7, 50], "outlier": [0, 2, 3, 5, 7, 8, 21, 39, 42, 46, 47, 48, 49, 50], "outlin": 2, "outnumb": 6, "outofsequencefil": 46, "output": [2, 4, 5, 6, 7, 8, 9, 10, 12, 15, 20, 21, 24, 25, 26, 27, 29, 42, 45, 46, 47, 48, 49, 53, 55, 62, 71, 92], "output_prefix": 49, "outright": [4, 6, 7, 42, 49], "outsid": [2, 4, 5, 6, 7, 8, 9, 23, 25, 27, 29, 33, 40, 42, 43, 45, 47, 49, 55, 96, 125], "outstand": [24, 140], "outward": [5, 6, 12, 23], "outweigh": [4, 6, 7], "over": [0, 1, 2, 3, 4, 5, 6, 8, 12, 21, 23, 25, 26, 27, 28, 33, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 55, 61, 68, 108, 109, 121, 122, 124, 125, 133, 140], "overal": [0, 1, 2, 3, 4, 6, 7, 8, 21, 39, 40, 46, 47, 49, 125], "overcom": [0, 3, 8], "overcommit": 45, "overfit": 6, "overflow": [2, 8, 44, 46, 51], "overhaul": 2, "overhead": 23, "overlai": [2, 26], "overlap": [2, 4, 5, 6, 7, 8, 12, 21, 38, 40, 42], "overlapped_reflections_major_pct": 49, "overlapped_reflections_pct": 49, "overload": [2, 4, 5, 7, 15, 23, 25, 42, 44, 46, 50], "overloaded_reflect": 49, "overloaded_reflections_kept": 49, "overloaded_reflections_kept_pct": 49, "overloaded_reflections_low_res_pct": 49, "overloaded_reflections_pct": 49, "overrid": [2, 4, 12, 26, 38, 39, 51], "overridden": [7, 12, 26], "overrul": [4, 39, 49], "overview": [0, 2, 3, 38, 61], "overwhelm": 4, "overwhelmingli": 56, "overwrit": [1, 2, 24, 87], "ow": [4, 7, 42, 49], "own": [0, 1, 2, 4, 5, 6, 8, 11, 12, 13, 15, 17, 18, 19, 21, 22, 23, 24, 25, 26, 27, 29, 33, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 55, 56, 57, 59, 60, 61, 68, 71, 96, 101, 107, 109, 110, 121, 122, 125, 131, 134], "owner": [19, 40], "ownership": [7, 21, 42, 51], "ox": 1, "oxalylglycin": 12, "oxi": [8, 47], "oxidas": 12, "oxidoreductas": [0, 3, 12], "oxo": 12, "oxygen": [5, 6, 7, 12], "oxytoca": 12, "p": [0, 1, 2, 3, 5, 6, 7, 8, 9, 12, 13, 17, 23, 26, 27, 34, 38, 39, 40, 42, 43, 45, 46, 47, 49, 50, 59, 68, 101], "p00001": 27, "p00g": 22, "p1": [2, 4, 5, 6, 7, 12, 25, 38, 39, 40, 42, 46, 47, 48, 49, 50], "p11": 12, "p112_1": 4, "p120rasgap": 12, "p12_11": 4, "p13": 12, "p17090": [0, 38, 50, 56], "p190rhogap": 12, "p2": [0, 7, 12, 47], "p20001": 23, "p21": [12, 38], "p21212": 39, "p2221": 39, "p2_1": [4, 49], "p2_12_12": 4, "p2_12_12_1": 4, "p2\u2081": [40, 47], "p2\u20812\u20812": 40, "p2\u20812\u20812\u2081": 40, "p3": [2, 7, 39, 50], "p32322": [0, 56], "p3_1": 4, "p3_2": 4, "p3\u2081": 47, "p3\u208121": 40, "p3\u2082": 47, "p3\u208221": 40, "p4": [2, 7, 38, 39, 50, 55], "p41212": 46, "p43": 12, "p43212": [2, 38, 42, 50], "p4_12_12": 4, "p4_32_12": 4, "p4\u20812\u20812": 47, "p4\u20832\u20812": 47, "p6": [2, 7, 39, 41, 50], "p62894": [0, 56], "p68082": [0, 56], "p6_3": [5, 6], "p6\u208122": 47, "p6\u208522": 47, "p7zip": 12, "p_": 7, "p_j": 7, "p_log": 40, "p_model": 40, "p_report": 40, "p_u": 7, "p_v": 7, "p_z": 7, "pa0012": 12, "pa0091": 12, "paciorek": [0, 3], "pack": [4, 5, 26, 40, 47, 49], "packag": [2, 3, 9, 10, 17, 19, 24, 25, 26, 28, 29, 31, 36, 38, 49, 52, 53, 56, 57, 58, 59, 61, 62, 138], "packet": [1, 2, 16, 18, 20, 23, 25, 51, 57, 71], "packets_expect": [1, 23], "packets_receiv": [1, 23], "packets_sl": 88, "packets_udp": 88, "pad": 23, "padilla": [0, 3, 4, 46, 49], "pae": [38, 47, 49], "page": [0, 2, 3, 9, 12, 21, 25, 26, 28, 35, 36, 43, 53, 54, 59], "pai": [4, 5, 6, 7, 50], "paid": [4, 5, 14], "painter": [0, 8], "pair": [0, 2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 38, 39, 40, 42, 46, 47, 48, 49, 50, 51, 55, 71, 107, 125], "pairsortgpu": 21, "pal": [2, 12, 13, 44], "pal86": 13, "pal90": 13, "pal_86": 13, "pal_90": 13, "palat": 30, "palmitoyl": 12, "palustri": 12, "pan": [12, 26], "pandda": [2, 4, 7, 12, 39, 47, 50], "panel": [1, 2, 6, 7, 13, 23, 26, 38, 42, 44, 50, 61], "pannu": [0, 3, 8], "paper": [0, 3, 5, 12, 13, 22, 28, 29, 38, 40, 49, 50], "par": 7, "paragraph": [5, 29, 46, 48, 49], "parallax": [0, 2, 7], "parallel": [0, 2, 5, 6, 8, 9, 14, 40], "param": 6, "param1": 27, "param2": 27, "paramet": [0, 1, 2, 3, 4, 5, 6, 7, 12, 15, 21, 23, 27, 38, 39, 41, 46, 47, 49, 55, 61, 62, 68, 96, 107, 109, 134, 137], "parameter": 5, "parent": [0, 4, 8, 21, 47], "parenthes": 46, "pari": [0, 3], "pariti": [4, 6, 7, 49], "park": [5, 13], "parkhurst": 0, "pars": [1, 2, 25, 49, 51, 55, 71], "parser": [5, 40], "parson": 12, "part": [0, 1, 2, 3, 4, 5, 7, 8, 9, 11, 12, 13, 17, 21, 23, 25, 29, 30, 33, 36, 39, 40, 41, 42, 45, 46, 47, 48, 49, 50, 55, 56, 58, 109], "parti": [2, 17, 21, 23, 26, 29, 36, 52, 53, 61], "partial": [0, 1, 2, 3, 4, 5, 6, 8, 12, 21, 23, 40, 42, 45, 46, 48, 49, 50, 55, 78], "particl": [12, 68], "particular": [0, 4, 7, 11, 17, 19, 20, 24, 27, 29, 33, 38, 40, 45, 53, 57], "particularli": [23, 119], "partit": [21, 49], "partli": [7, 44, 49], "partner": [0, 4, 8, 49], "pass": [0, 2, 4, 5, 7, 8, 9, 12, 19, 21, 23, 25, 26, 27, 29, 30, 38, 39, 40, 41, 42, 44, 47, 48, 49, 50, 53, 55, 57, 61, 109, 125, 127, 128], "pass_decis": [7, 48, 49], "passag": 49, "passiv": 51, "password": [29, 51], "past": [2, 4, 5, 6, 7, 22, 24, 25, 38, 39, 40, 42, 45, 46, 47, 49, 53], "patch": [2, 5, 40, 50], "patent": [17, 29], "path": [0, 1, 2, 4, 5, 6, 8, 9, 12, 13, 14, 15, 21, 23, 24, 25, 26, 27, 28, 36, 38, 39, 40, 42, 43, 44, 45, 46, 47, 49, 50, 51, 52, 55, 56, 57, 128], "patholog": 12, "pathologi": [2, 25, 26, 49, 125, 131], "pathology_flag": [2, 25, 49, 131], "pattern": [2, 5, 6, 7, 23, 29, 42, 45, 49, 50], "patterson": [0, 2, 3, 4, 12, 49], "pattison": 0, "paul": [30, 61, 62], "payload": [5, 24], "payload_s": 24, "payment": 29, "pbca": [2, 4, 49], "pc": [0, 4], "pci": [14, 16], "pci_bus_id": 9, "pci_dev_id": 88, "pcie": [2, 14, 18, 20, 21, 22, 25, 28, 37, 54, 58, 88, 99], "pcie_100g": 14, "pcie_8x10g": 14, "pcie_devices_inn": 102, "pcie_devices_inner_dict": 102, "pcie_devices_inner_from_dict": 102, "pcie_devices_inner_inst": 102, "pcie_driv": [9, 19], "pcie_link_spe": 88, "pcie_link_width": 88, "pciedevicesinn": [62, 99], "pcm": 12, "pdb": [0, 1, 2, 4, 7, 8, 13, 25, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 55, 56, 61, 71], "pdb_cach": 40, "pdbfile": 46, "pdbx": [2, 7, 39], "pdbx_absdiff_over_sigma_anomal": 7, "pdbx_aniso_b_tensor_": [2, 4], "pdbx_aniso_b_tensor_eigenvalue_1": 46, "pdbx_cc_half": 49, "pdbx_diffrn_protocol": 12, "pdbx_f_minu": 46, "pdbx_f_plu": 46, "pdbx_i_minu": 46, "pdbx_i_plu": 46, "pdbx_monochromatic_or_laue_m_l": 12, "pdbx_r_free_flag": [39, 40, 47], "peak": [0, 1, 2, 4, 5, 7, 8, 12, 21, 23, 25, 27, 30, 38, 39, 42, 44, 45, 49, 123, 128], "peak_list": 23, "peak_list_typ": 23, "peak_shift_a": 8, "peak_sigma": [1, 49, 120], "peakcounticeringcontrol": [5, 23], "peakcounticeringr": [5, 23], "peakcountindex": 23, "peakcountlowr": 23, "peakcountunfilt": [2, 23], "peakdistewaldspher": 23, "peakfinder8": [0, 3, 5], "peakh": 23, "peakiceringr": 23, "peakindex": 23, "peakk": 23, "peakl": 23, "peaklattic": 23, "peakpanel": 23, "peaktotalintens": 23, "peakworkingset64": 40, "peakxposraw": 23, "peakyposraw": 23, "pearson": [4, 12, 49], "pedest": [1, 2, 7, 16, 20, 23, 24, 25, 33, 44, 51, 60, 62, 68, 71, 80, 92, 103], "pedestal_g0_mean": 66, "pedestal_g1_mean": 66, "pedestal_g2_mean": 66, "pedestal_post": 62, "pedestalrm": 2, "peer": [29, 51], "peer_liveness_timeout_m": [24, 136], "peet": 30, "peg": [8, 47], "pegtl": 56, "pemphigoid": 12, "penal": 7, "penalis": [3, 6, 7], "penalti": [0, 7, 25], "pend": 2, "penicillopepsin": [0, 8], "penumbra": 5, "peopl": [0, 12, 13, 30, 40, 46, 59], "peptid": [8, 12, 47], "peptidomimet": 12, "per": [0, 1, 2, 3, 4, 6, 8, 9, 12, 15, 19, 24, 25, 26, 27, 28, 35, 36, 38, 39, 42, 44, 45, 46, 47, 48, 49, 50, 55, 56, 61, 68, 71, 72, 74, 86, 89, 90, 98, 109, 119, 125, 127, 131, 134, 140], "percent": [4, 5, 7, 40, 42, 49, 124], "percentag": [4, 6, 49], "pereyra": [0, 3, 4], "perf": [40, 56], "perfect": [0, 3, 4, 8, 39, 46, 49], "perfectli": [0, 4, 49], "perform": [1, 2, 3, 5, 6, 7, 16, 17, 18, 19, 24, 25, 26, 29, 45, 49, 55, 57, 71, 101, 123], "perframecc": 21, "peril": [0, 3], "period": [5, 6, 8, 17, 24, 48, 71, 138, 139], "period_m": [24, 25, 138, 139], "peripheri": 6, "perman": [17, 29], "permiss": [17, 19, 24, 29, 62], "permissiondeni": 24, "permit": [17, 29], "permut": [0, 2, 4, 6, 39, 42, 49], "perpendicular": [1, 4, 6, 7, 11, 23, 49, 108], "perpetu": [17, 29], "persist": [2, 5, 21, 23, 24, 40, 49], "person": [8, 17, 29, 38, 49, 50, 120], "personnel": 17, "pertin": 29, "perturb": 4, "pertussi": 12, "pessimist": 6, "peter": 56, "petit": 12, "petra": 12, "petsko": [0, 3, 8], "pfizer": 12, "pflugrath": 0, "pg090": 20, "pg099": 20, "pg114": 20, "pg153": 20, "pg195": 20, "pg203": 20, "pg210": 20, "pg293": 20, "pg348": 20, "pg4": [8, 47], "pge": [8, 47], "pgw240050_01": 12, "ph": [1, 12], "phanom": [4, 8, 39, 47, 49, 71], "phase": [0, 2, 3, 4, 5, 6, 7, 8, 21, 23, 25, 39, 40, 47, 49, 53, 55, 56, 71], "phaseolu": 12, "phaser": [0, 2, 3, 38, 49, 55], "phd": 12, "phdelwt": [4, 39, 71], "phenix": [0, 2, 3, 4, 7, 8, 38, 39, 40, 42, 46, 47, 49, 50], "phenylglycin": 12, "phgat": 12, "phi": [1, 2, 5, 6, 7, 12, 21, 23, 41, 42, 46, 63, 69, 107, 119], "phi_": [6, 7], "phi_axi": [1, 69], "phi_deg": [1, 69], "phi_max": 1, "phi_max_deg": [23, 113], "phi_min": 1, "phi_min_deg": [23, 113], "phic": 4, "phicd111_20024_ead": 12, "phillip": [0, 3, 12], "phone": 2, "phosi": 12, "phosphat": [8, 12, 47], "phosphatidylethanolamin": 12, "phospho": 12, "phosphoheptos": 12, "phospholipid": 12, "phosphoru": [4, 39, 49], "phosphorylas": 12, "phosphotyrosin": 12, "photograph": [0, 3], "photon": [1, 5, 7, 12, 13, 15, 20, 23, 27, 42, 44, 50, 53, 55, 68, 92], "photon_count_threshold": 134, "photonjet": 12, "photons\u00b2": 23, "phua": [0, 3], "phwt": [4, 8, 39, 71], "phwt_no_fil": [4, 8, 39], "phy": 12, "physic": [2, 3, 5, 6, 7, 8, 17, 18, 19, 23, 29, 42, 47, 49, 50], "physrevb": 12, "pi": [4, 5, 6, 7, 8, 21, 49], "pick": [0, 2, 4, 7, 12, 19, 21, 25, 26, 36, 38, 39, 40, 41, 46, 50, 57, 59], "pictur": 50, "pid": 40, "piec": [8, 12, 29, 30], "pilatu": [0, 2, 5, 11, 12, 26, 38, 41, 42, 44], "pilatus3": [0, 3, 12], "pile": [5, 49], "pill": 2, "pin": [0, 2, 4, 5, 6, 12, 21, 40, 41, 42, 47, 50, 51, 56, 109], "ping": 18, "pink": [6, 12], "pip": [9, 28, 31, 40], "pip2": 12, "pipe": 38, "pipelin": [0, 2, 3, 5, 12, 14, 20, 21, 22, 23, 25, 26, 27, 30, 36, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 53, 55, 57, 59, 61, 89], "pistach": 2, "pitfal": [0, 8], "pivot": 23, "pix": [2, 5, 42, 50], "pixel": [0, 1, 2, 3, 4, 6, 7, 9, 12, 13, 16, 21, 22, 24, 25, 26, 27, 28, 34, 38, 40, 41, 42, 44, 45, 46, 48, 49, 50, 54, 62, 67, 68, 71, 75, 77, 92, 101, 103, 107, 109, 110, 116, 127, 133, 134, 135], "pixel_mask": [1, 13, 23, 53, 100], "pixel_mask_appli": 23, "pixel_mask_en": 1, "pixel_mask_statist": 103, "pixel_mask_statistics_dict": 103, "pixel_mask_statistics_from_dict": 103, "pixel_mask_statistics_inst": 103, "pixel_s": 23, "pixel_size_i": 1, "pixel_size_m": 27, "pixel_size_mm": 74, "pixel_size_x": 1, "pixel_sum": [1, 2, 23, 133], "pixel_value_low_threshold": 68, "pixelmask": 44, "pixelmaskstatist": [62, 100], "pixelrefin": 2, "piz": 30, "pl": 12, "place": [0, 1, 2, 3, 5, 6, 7, 9, 11, 13, 14, 17, 21, 23, 24, 25, 27, 29, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 54, 55, 61, 62, 68, 71, 92, 109, 122, 123, 124, 125, 129], "placed_model": [1, 125], "placehold": [2, 8, 23, 24, 46, 49, 50], "placement": [1, 2, 3, 6, 8, 21, 23, 25, 39, 40, 42, 45, 47, 49, 50, 55, 56, 68, 122, 123], "placement_cc": 40, "plai": [2, 30, 39, 47, 50], "plain": [1, 2, 4, 5, 6, 7, 8, 19, 26, 36, 40, 42, 44, 45, 49, 51, 71], "plainli": [5, 39, 47], "plan": [4, 21, 25], "planck": 56, "plane": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 21, 23, 25, 38, 42, 44, 48, 49, 50, 68, 77], "plasma": 97, "plasmodium": 12, "plasmoredoxin": 12, "plate": [5, 12], "platform": [0, 12, 26, 28, 38, 56], "plausibl": [5, 6, 7, 42, 46, 133], "plausibli": 55, "playback": 26, "playn": 0, "plddt": [0, 4, 39, 42, 49], "pleas": [2, 19, 29, 34, 38, 40, 62], "plenti": 6, "plor": 0, "plot": [2, 3, 4, 5, 25, 26, 28, 38, 49, 50, 51, 60, 62, 71, 113, 114, 116], "plot_dict": 104, "plot_from_dict": 104, "plot_inst": 104, "plot_typ": 2, "plotli": 104, "plots_dict": 106, "plots_from_dict": 106, "plots_inst": 106, "plotunitx": [62, 106], "plp": 12, "plu": [1, 2, 4, 6, 7, 8, 11, 12, 23, 25, 26, 29, 36, 40, 44, 46, 49, 71], "plug": [7, 40], "plugin": [2, 23, 28, 36, 37, 46, 53, 55], "pm": [4, 5, 7], "pm1": 8, "pm4": 7, "pmatrix": 5, "pmv": 12, "pna": 0, "pna2_1": [4, 49], "pna2\u2081": 50, "pneumonia": 12, "png": 2, "pnma": [4, 49, 50], "po": 12, "pocket": 12, "pocketfft": 56, "pocketfft_hdronli": 56, "pohl": [0, 8], "point": [0, 1, 2, 3, 4, 5, 6, 8, 11, 13, 15, 21, 23, 25, 26, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 59, 68, 70, 71, 72, 109, 120, 134], "pointer": 29, "pointless": [0, 2, 3, 4, 12, 38, 39, 42, 46, 50], "poisson": [0, 3, 4, 5, 7, 42, 68], "poisson_compress": 68, "pol": 5, "polar": [0, 1, 2, 3, 4, 5, 7, 8, 11, 15, 23, 25, 42, 46, 50, 63, 68], "polar_contact": [1, 49], "polaris": [2, 7], "polarization_corr": [25, 63], "polarization_factor": [25, 68], "polici": [0, 56, 71], "polish": 2, "poll": 51, "polychromat": 23, "polym": [4, 8, 42, 49], "polymeras": 12, "polynomi": [0, 3, 8, 56], "polypeptid": 8, "pong": 24, "poni": [1, 2, 5, 7, 11, 26, 41, 42, 46, 49, 53, 57, 68, 107, 108, 109], "poni1": 11, "poni2": 11, "poni_rot": [41, 49, 108], "poni_rot1": 1, "poni_rot1_rad": [68, 107], "poni_rot2": 1, "poni_rot2_rad": [68, 107], "poni_rot3": 1, "poni_rot3_rad": 68, "pool": [2, 4, 5, 6, 7, 23, 24, 26, 40, 41, 42, 49, 55, 96, 100, 109], "poor": [0, 2, 5, 8, 49], "poorli": [6, 7, 38, 109], "pop": 26, "popov": [0, 3], "popul": [0, 3, 4, 6, 23, 27, 39, 40, 42, 49], "populu": 12, "porebski": 0, "porphyrin": 8, "port": [0, 2, 6, 9, 14, 18, 21, 22, 24, 25, 26, 27, 38, 42, 51, 56, 136, 138, 139, 140], "portabl": [2, 5, 9, 26, 36, 52, 55, 59], "portal": [0, 26], "portion": 29, "pos2_1": 12, "pos3_1": 12, "posit": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 21, 23, 25, 26, 38, 39, 41, 42, 44, 46, 48, 49, 50, 55, 71, 75, 77, 90, 119, 120, 133], "position": 69, "positive_within_3": 49, "posix_fadv_dontne": 40, "posix_fadvis": 40, "possess": 29, "possibl": [0, 1, 2, 3, 4, 6, 12, 14, 17, 19, 22, 24, 25, 29, 30, 33, 46, 49, 52, 71], "post": [0, 1, 2, 3, 4, 5, 7, 23, 25, 40, 41, 42, 48, 49, 50, 62, 71, 89, 108, 125, 128], "post_start": 35, "posterior": [0, 7, 49], "postpon": 2, "postrefin": [2, 5, 6, 42, 50], "postrefine_beam_centr": 5, "postrefine_distance_held": 6, "postrefine_refus": 6, "postul": 0, "potassium": 12, "potenti": [2, 17], "potterton": [0, 8], "powder": [0, 2, 3, 4, 5, 7, 25, 26, 38, 42, 57, 107, 108, 109], "powder_": 5, "powder_calibration_fit_sigma": [107, 109], "powder_calibration_fit_sigma_dict": 107, "powder_calibration_fit_sigma_from_dict": 107, "powder_calibration_fit_sigma_inst": 107, "powder_calibration_output": 108, "powder_calibration_output_dict": 108, "powder_calibration_output_from_dict": 108, "powder_calibration_output_inst": 108, "powder_calibration_qu": 109, "powder_calibration_quality_dict": 109, "powder_calibration_quality_from_dict": 109, "powder_calibration_quality_inst": 109, "powder_calibration_spot_check": 110, "powder_calibration_spot_check_dict": 110, "powder_calibration_spot_check_from_dict": 110, "powder_calibration_spot_check_inst": 110, "powder_excluded_from_index": 49, "powder_ice_ring_count": 49, "powder_ice_spot_fract": 49, "powder_indexing_d_min": 49, "powder_non_ice_spot_fract": 49, "powder_r": 49, "powder_ring_count": 49, "powder_rings_a": 49, "powder_rings_detect": 49, "powder_rings_lattice_coverag": 49, "powder_rings_on_own_lattic": 49, "powder_rings_separable_to": 49, "powder_spot_fract": 49, "powdercalibrationfitsigma": [62, 109], "powdercalibrationoutput": 62, "powdercalibrationqu": [62, 108], "powdercalibrationspotcheck": [62, 109], "powel": [0, 3], "power": [2, 4, 5, 9, 14, 19, 22, 29, 40, 42, 49, 57, 71, 78], "power_usage_w": 88, "powerchip": 82, "poweroff": 78, "poweron": 78, "powershel": 40, "ppra": 12, "pprint": [62, 71], "pq": 22, "pr": 133, "practic": [0, 2, 3, 7, 22, 29, 138, 139, 140], "pratt": [0, 8], "pre": [2, 4, 5, 6, 7, 9, 25, 26, 38, 40, 42, 44, 45, 46, 48, 49, 50, 52, 57, 59, 127, 128], "preambl": 17, "prebuilt": 9, "precaut": 6, "preced": [4, 5, 39], "precis": [0, 2, 4, 7, 12, 14, 20, 21, 29, 42, 47, 49, 56], "precomput": 5, "precondit": 6, "pred": [6, 7], "predecessor": 29, "predefin": [16, 23], "predict": [0, 1, 2, 3, 4, 6, 8, 11, 12, 23, 25, 26, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 56, 61, 71, 122], "predicted_aligned_error_v": [47, 49], "predicted_aligned_error_v6": 38, "predicted_i": 23, "predicted_px_x": 23, "predicted_x": 23, "predictor": [4, 42, 64], "prefer": [2, 4, 6, 11, 12, 17, 22, 26, 29, 38, 46, 47, 49, 53, 55], "prefix": [1, 2, 4, 6, 8, 9, 24, 25, 26, 37, 38, 40, 41, 42, 45, 46, 47, 48, 49, 50, 52, 57, 59, 68], "preflight": [24, 27], "prentic": 0, "prep": 12, "prepar": [0, 1, 2, 3, 9, 17, 25, 27, 42, 62, 71, 91], "prepare_topologi": 8, "prepass": [6, 42, 48, 49, 50, 127], "prepass_": 127, "preprocess": [2, 5, 7, 21, 45], "preprocessing_tim": 1, "preprocessingtim": 23, "preprocessor": 15, "prescaling_corr": 7, "presenc": [0, 3, 12, 42, 47], "present": [1, 2, 4, 5, 6, 7, 9, 11, 12, 19, 21, 23, 25, 29, 36, 39, 40, 42, 45, 46, 49, 50, 53, 60, 71, 91, 108, 125], "preserv": [0, 2, 3, 4, 7, 8, 15, 23, 27, 29, 49, 68], "preset": [2, 26], "press": [0, 3, 9, 26], "pressur": [7, 12], "prevent": [2, 17, 29], "preview": [2, 25, 28, 51, 56, 60, 62, 71, 139], "preview_pedestal_tiff_get": 62, "preview_plot_bin_get": 62, "preview_plot_get": 62, "previou": [2, 4, 5, 7, 21, 26, 29, 40, 47, 51, 68, 71], "previous": [2, 39], "prfar": 12, "price": [4, 29], "primari": [9, 28, 34], "primarili": [24, 29], "primarli": 62, "prime": 0, "primit": [2, 4, 5, 6, 12, 40, 41, 46, 49, 50], "princ": 0, "princip": [0, 2, 3, 4, 7, 46, 49], "principl": [0, 4, 6, 22, 47], "print": [2, 4, 7, 12, 26, 27, 38, 39, 40, 41, 42, 43, 45, 46, 47, 49, 50, 55, 57, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "prior": [0, 1, 2, 3, 4, 6, 7, 8, 29, 42, 47, 49], "priori": 6, "prioriti": [4, 21], "prioritis": 42, "pritzel": 0, "privat": [29, 40, 55], "probabl": [0, 3, 4, 8, 12, 47, 49, 68], "probe": [0, 4, 6, 8, 24, 25, 39, 47, 49, 125], "probe_": 125, "problem": [0, 2, 3, 5, 6, 17, 18, 29, 34, 49, 55, 107], "proc": [0, 3, 12, 40], "proce": 24, "procedur": [0, 3, 6, 8, 9, 14, 15, 19, 24, 29, 62, 71, 103], "proceed": [0, 3], "process": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 14, 17, 19, 20, 21, 22, 23, 24, 25, 27, 28, 30, 34, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 55, 57, 61, 62, 63, 68, 71, 96, 125, 128, 129, 140], "process_predicted_model": [0, 3], "processed_imag": 24, "processing_tim": 1, "processingtim": 23, "processor": [0, 2], "procur": [17, 29], "produc": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 15, 23, 24, 26, 29, 38, 39, 42, 45, 46, 49, 50, 55, 56, 57, 92, 108, 109], "product": [0, 2, 4, 7, 17, 23, 29], "profar": 12, "profil": [0, 1, 2, 3, 4, 6, 25, 26, 40, 41, 42, 48, 49, 50, 98, 109, 110, 133], "profile_radiu": 1, "profileempir": 98, "profilegaussian": [64, 98], "profileintegrate2d": 2, "profileradiu": 23, "profiles_process": 42, "profit": 17, "program": [0, 1, 2, 3, 4, 6, 7, 8, 11, 12, 14, 17, 23, 25, 26, 28, 34, 36, 37, 38, 40, 41, 42, 45, 47, 49, 52, 53, 54, 55, 57, 59, 61, 62, 68, 108], "programm": 29, "progress": [2, 7, 38, 49, 50, 51, 65], "prohibit": 29, "project": [0, 2, 3, 4, 5, 7, 8, 12, 21, 26, 30, 36, 40, 42, 45, 48, 49, 50, 56, 62, 96], "project_nam": 1, "prolidas": 12, "proliferatum": 12, "prolyl": 12, "promin": [6, 21, 29], "promis": [44, 46], "promot": [0, 2, 4, 6, 17, 40, 47, 49], "prompt": [2, 26, 49], "pronunci": 30, "proof": [2, 4, 49], "propag": [5, 6, 24, 29], "propel": 12, "proper": [2, 4, 6, 16, 19, 24, 33, 39], "properli": [2, 7, 9, 15, 24], "properti": [0, 4, 6, 7, 8, 14, 15, 23, 24, 29, 39, 41, 46, 49], "propion": 12, "proport": [1, 2, 4, 5, 6, 7, 8, 38, 43, 47, 49], "proportion": 7, "propos": [0, 1, 3, 6, 23, 27, 68, 101], "proprietari": [17, 29, 51], "propto": [7, 8], "prose": 49, "prospect": 17, "prosport": 12, "proteas": 12, "protect": [2, 4, 5, 14, 25, 26, 27, 29, 35, 68, 71], "protein": [0, 2, 3, 4, 6, 7, 8, 12, 46, 47, 49, 50, 56], "proteu": [12, 38, 40], "proteum": 44, "protoc": 0, "protocol": [1, 2, 12, 24, 25, 28, 29, 40, 55, 133], "protocolerror": 24, "proton": 8, "prove": [6, 29], "proven": 23, "provid": [0, 1, 2, 4, 6, 7, 11, 14, 15, 16, 17, 18, 19, 23, 24, 25, 29, 31, 37, 39, 44, 45, 52, 62, 68, 71, 72, 80, 92, 93, 99, 101, 103, 113, 136, 140], "provis": [17, 29, 62], "provision": [25, 29, 125], "proxi": [5, 26, 29, 51], "proxim": 12, "proxima": 12, "prpf3": 12, "prune": 8, "psa": 56, "pseudo": [2, 3, 6, 7, 8, 25, 39, 40, 46, 48], "pseudo_transl": [2, 49], "pseudoazurin": 12, "pseudomallei": 12, "pseudomerohedr": [0, 3], "pseudomona": 12, "pseudorandom": 0, "pseudouridin": 8, "psi": [0, 2, 7, 9, 11, 14, 15, 21, 22, 25, 26, 28, 30, 33, 37, 38, 40, 45, 53, 56, 61, 62, 71, 72, 80], "psi_i": 7, "psi_x": 7, "psu": [8, 47], "ptp": 2, "ptx": 36, "pub": [24, 25, 27, 71, 138, 139], "public": [17, 28, 38, 40, 49, 51, 55, 58, 61], "publicli": 29, "publish": [2, 4, 7, 10, 13, 17, 26, 29, 35, 36, 37, 40, 46, 49], "pucker": 8, "pull": [2, 4, 6, 7, 8, 24, 49, 50, 51, 140], "puller": [2, 24, 125], "puls": [1, 2, 20, 25, 62, 68, 71, 97, 133], "pulse_id": [62, 71], "pulsed_sourc": [25, 97], "pulseid": 23, "pump": 39, "punit": 17, "purchas": 22, "pure": [4, 5, 7, 12, 24, 39, 49], "purin": 8, "purpos": [4, 12, 17, 19, 24, 27, 29, 35, 40, 49, 58], "pursu": 46, "pursuant": [17, 29], "push": [0, 3, 4, 6, 7, 21, 24, 25, 27, 30, 36, 40, 42, 51, 57, 140], "pusher": [2, 24, 25, 27, 62, 71, 93, 128, 129], "pusher_typ": 93, "put": [0, 2, 3, 4, 5, 6, 7, 8, 11, 12, 18, 21, 22, 24, 25, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 55, 62, 71, 110, 129], "putrescinium": 12, "pv": 12, "pvaiii": 12, "pvaspg2": 12, "pvhl": 12, "pwd": 38, "px": [2, 5, 6, 7, 12, 23, 38, 42, 50], "px10": 12, "pxii": 22, "pxl": 2, "py": [8, 12, 13, 25, 40, 47, 55, 56, 62, 71], "pycr1": [12, 40], "pyfai": [1, 2, 3, 5, 11, 23, 26, 41, 42, 68], "pymol": [4, 38, 39, 47, 50], "pyogen": 12, "pypi": [31, 35, 36], "pyridin": 12, "pyrobaculum": 12, "pyrrol": 8, "pyruv": 12, "pytest": 62, "python": [2, 3, 25, 28, 36, 40, 51, 61, 62], "python3": 40, "pythonclientcodegen": 62, "pytorch": [0, 3, 34], "q": [1, 2, 6, 7, 15, 23, 25, 34, 41, 42, 46, 49, 63, 109, 111, 113, 134], "q65mg6": [0, 56], "q_": [5, 7], "q_bin": [5, 23, 25, 63, 111], "q_i": 5, "q_j": 8, "q_max_recip_a": 113, "q_max_recipa": 23, "q_min_recip_a": 113, "q_min_recipa": 23, "q_recip_a": 105, "q_recipa": [71, 105], "q_space": [2, 5, 25, 63], "q_z": 7, "qbin": [62, 63], "qcp": [0, 3], "qe": [1, 2, 7, 23, 42, 46], "qe_corr": 7, "qmax": 1, "qmin": 1, "qquad": [4, 5, 6, 7, 8], "qsfp": [14, 18], "qsfp0": 18, "qsfp1": 18, "qsfp28": 18, "qspi": [9, 28, 56], "qt": [2, 9, 26, 36, 38, 43, 45, 52, 56, 59, 61], "qt6": 56, "qt_qpa_platformthem": 26, "qt_scale_factor": 26, "quad": [4, 5, 6, 7], "quadrant": 2, "quadrat": [5, 8], "quadratur": [7, 46], "quadspi": 20, "qualifi": [4, 29, 40, 46, 49], "qualiti": [2, 3, 4, 5, 7, 17, 23, 28, 29, 38, 39, 40, 47, 50, 55, 60, 71, 121], "quantil": [0, 3, 5], "quantis": 41, "quantit": [0, 7], "quantiti": [0, 1, 2, 3, 4, 6, 7, 8, 12, 23, 26, 39, 46, 49, 50, 124], "quantiz": 2, "quantum": [2, 12, 44, 46], "quarter": [4, 5, 6, 7, 8, 21, 25, 27, 38, 40, 41, 42, 49], "quasi": [0, 3, 8], "quaternion": [0, 3], "queensland": [0, 12], "queri": [23, 40], "question": [0, 4, 6, 17, 24, 38, 40, 46, 47, 49, 50, 109], "queu": [5, 24, 40, 140], "queue": [1, 2, 21, 24, 27, 40, 101, 140], "quick": [2, 35, 45, 50], "quick_integr": [25, 134], "quickintegr": 2, "quickli": 39, "quicklook": 50, "quietli": [12, 40, 41], "quir\u00f3": 0, "quit": 39, "quot": [0, 2, 4, 5, 7, 39, 40, 46, 49, 50, 51, 55, 68, 71, 91, 101, 120, 121, 122, 125, 131, 132, 134], "quota": [24, 42], "q\u00b2": 49, "r": [0, 1, 2, 3, 5, 6, 8, 11, 12, 13, 20, 21, 23, 25, 27, 38, 39, 40, 42, 46, 47, 48, 49, 50, 55, 122, 123, 124, 125], "r00": 13, "r0099": 13, "r0165": 13, "r0243": 13, "r0256": 13, "r0267": 13, "r0292": 13, "r0420": 13, "r1": 42, "r100": 50, "r2": [2, 42], "r21": [0, 8], "r26": [0, 8], "r267e": 12, "r2c": 21, "r2nx": 12, "r3": [2, 42], "r32": 2, "r580": [26, 36, 43, 59], "r80": 42, "r_": [4, 5, 6, 7], "r_0": [7, 8], "r_1": 7, "r_2": 7, "r_3": 7, "r_free": [4, 8, 39, 40, 47, 48, 49, 122, 123, 124], "r_free_before_rigid_bodi": 4, "r_free_flag": [42, 47, 49], "r_mea": [0, 2, 3, 21, 25, 38, 39, 40, 42, 49, 50, 55, 124, 125], "r_meas_weight": 49, "r_merg": [2, 39, 49], "r_model": 49, "r_model_reflect": 49, "r_model_shell_sc": [4, 39, 47], "r_pim": [0, 2, 3, 39, 49], "r_px": 42, "r_split": [2, 25, 40, 48, 49, 124, 125], "r_work": [4, 8, 39, 47, 48, 49, 122, 123], "rac": 8, "rad": [0, 1, 3, 15, 23, 28, 34, 42, 107], "radial": [0, 1, 2, 3, 4, 6, 7, 21, 23, 25, 26, 41, 42, 49, 109, 133], "radian": [7, 68], "radiat": [0, 2, 3, 6, 7, 49, 50, 97, 121], "radiation_damag": [23, 49], "radiation_damage_relative_b": 50, "radicci": 0, "radii": [0, 2, 4, 7, 8, 42, 47, 109], "radioduran": 12, "radiu": [1, 2, 4, 5, 6, 8, 11, 21, 23, 26, 42, 48, 49, 107, 116, 133], "radius_pxl": [23, 116], "radix": 21, "rai": [0, 1, 2, 3, 4, 5, 7, 9, 11, 12, 13, 15, 21, 23, 25, 27, 28, 34, 40, 42, 47, 49, 50, 51, 61, 68, 70, 71, 97], "railwai": 30, "rais": [2, 4, 5, 6, 7, 8, 26, 27, 38, 42, 47, 49, 51, 96], "ram": [9, 22, 38, 40, 43, 45], "ramachandran": [8, 47], "ramp": [4, 50], "ran": [2, 5, 6, 8, 23, 25, 38, 40, 46, 49, 50, 109, 123], "random": [0, 2, 3, 4, 6, 7, 8, 12, 23, 24, 27, 38, 39, 40, 47, 49, 50, 122, 140], "randomli": [6, 47], "rang": [0, 1, 2, 3, 4, 5, 6, 7, 8, 13, 15, 21, 23, 25, 26, 38, 39, 42, 44, 46, 47, 50, 53, 106, 113, 133], "rangl": [4, 7], "rangle_": [4, 7], "rank": [2, 4, 5, 6, 7, 42, 46, 49], "ransei": 0, "rapid": [0, 3], "rar": 12, "rar3": 12, "rare": 2, "raster": 26, "rate": [0, 1, 2, 3, 4, 5, 6, 7, 10, 22, 23, 24, 25, 28, 30, 34, 38, 42, 49, 50, 57, 61, 62, 68, 91, 96, 125, 139], "rather": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 21, 23, 26, 27, 36, 39, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 54, 55, 56, 90, 108, 109], "ratifi": [6, 50], "ratio": [0, 2, 3, 4, 5, 6, 7, 8, 20, 23, 40, 42, 44, 46, 49], "ration": [1, 49], "rau": 56, "raw": [0, 1, 2, 4, 5, 6, 7, 13, 21, 23, 25, 26, 27, 38, 40, 42, 44, 46, 62, 68, 71], "raw_al": 13, "raw_fil": 13, "raw_mor": 13, "ray_wavelength": [46, 49], "rayonix": [12, 13, 44], "rbd": 12, "rbg2f9": 12, "rc": [23, 38, 43, 45, 50, 59, 62], "rceil": [5, 7], "rcsb": [0, 12, 13, 40, 56], "rcv_buffer": 27, "rcv_delai": 23, "rcv_free_send_buff": 23, "rcv_ring_mb": 27, "rcv_watermark": 27, "rd04": 12, "rd71": 0, "re": [0, 2, 3, 4, 5, 6, 7, 8, 12, 23, 26, 27, 38, 40, 44, 46, 47, 48, 49, 50, 53, 55, 56, 57, 133], "reach": [0, 1, 2, 4, 6, 7, 8, 9, 11, 21, 23, 26, 30, 38, 39, 40, 42, 49, 50, 51, 53, 55, 56, 63, 71, 121, 134], "reachabl": [2, 4, 5, 7, 51], "react": [56, 60], "reactor": 97, "read": [2, 3, 4, 5, 6, 7, 8, 11, 13, 19, 21, 23, 24, 25, 26, 27, 29, 33, 35, 36, 38, 39, 41, 42, 44, 45, 46, 47, 48, 49, 50, 53, 55, 57, 71, 80, 82, 92, 109, 110, 120], "readabl": [2, 7, 29, 41, 42, 46, 49, 50, 51, 55, 56, 68, 71, 85], "reader": [0, 1, 2, 4, 5, 12, 23, 24, 25, 40, 44, 46, 47, 49, 62, 71, 75, 77], "readi": [2, 29, 49, 68, 71], "readili": [4, 29], "readm": [2, 12, 13, 35, 38, 40, 45, 47, 55, 56, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "readout": [1, 2, 23, 25, 42, 44, 68, 75, 77], "readout_fast_axi": 23, "readout_slow_axi": 23, "readout_time_n": [25, 72, 74], "real": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 23, 26, 28, 34, 38, 39, 40, 41, 42, 46, 47, 48, 49, 51, 57, 61, 80, 96, 132], "real_tim": 1, "realis": 6, "realli": [2, 5, 6, 8, 12, 39, 44, 50], "reanalyz": 2, "rearrang": [4, 26], "reason": [0, 1, 2, 4, 5, 6, 7, 8, 12, 17, 19, 22, 24, 25, 26, 27, 29, 33, 36, 38, 40, 41, 49, 51, 53, 55, 65, 85, 121, 122, 123], "reav": 12, "rebin": 49, "reboot": [2, 9, 19], "rebrand": 2, "rebuild": [7, 9, 38, 42], "rebuilt": [5, 7, 8, 9, 14, 21, 36], "recalcul": 2, "receipt": [17, 29], "receiv": [1, 2, 5, 7, 14, 17, 19, 20, 23, 24, 26, 27, 28, 29, 30, 36, 51, 57, 65, 68, 71, 99, 101, 125, 128, 129], "receiver_aq_dev_delai": 1, "receiver_buf_in_prepar": 1, "receiver_buf_in_send": 1, "receiver_free_send_buf": 1, "receiver_thread": [25, 99], "recent": [0, 2, 3, 9, 22, 26], "recentr": 49, "receptor": 12, "recheck": 40, "recipi": [17, 29], "reciproc": [0, 1, 2, 3, 4, 6, 8, 12, 21, 23, 49, 61], "reciprocalspaceship": 46, "reclaim": 27, "recogn": 29, "recognis": [0, 2, 7, 23, 39, 42, 44, 47, 48, 50], "recognit": [0, 12], "recollect": 49, "recommend": [2, 6, 9, 11, 23, 24, 25, 37, 42, 47, 49, 52, 53, 68, 71, 96], "recomput": [4, 7, 21, 49, 50], "reconcil": 6, "reconfigur": [49, 51, 71], "reconstruct": [0, 12, 46, 69], "record": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 21, 23, 24, 25, 33, 38, 39, 40, 44, 46, 47, 49, 50, 51, 68, 71, 90, 119], "recov": [0, 2, 4, 5, 6, 7, 11, 23, 27, 49, 50], "recover": 46, "recoveri": [1, 4, 133], "rectangl": 2, "rectangular": [15, 26, 135], "rectifi": 7, "recurs": [0, 3, 8], "red": [9, 25, 26, 52], "redesign": 2, "redford": 34, "redhat": 19, "redirect": 14, "redistribut": [12, 29, 56], "redocli": 32, "redon": 7, "reduc": [0, 1, 2, 3, 4, 5, 6, 7, 12, 15, 21, 24, 39, 40, 48, 49, 68, 100, 121, 139], "reducegroupmean": 21, "reduct": [1, 2, 3, 4, 5, 7, 21, 39, 49], "reductas": 12, "redund": [1, 2, 7], "ref": [4, 6, 7, 12, 13, 39, 42, 47, 55], "ref_altern": 12, "ref_overrid": 12, "ref_override_whi": 12, "refactor": [0, 2], "refer": [0, 1, 2, 4, 5, 9, 11, 12, 17, 21, 23, 24, 25, 26, 29, 31, 35, 38, 42, 44, 48, 50, 55, 56, 57, 71, 96, 124], "refere": 40, "referenc": [2, 55], "reference_cc": 39, "reference_free_flags_inherit": [39, 47], "reference_matched_fract": 39, "reference_mismatch": [7, 12, 39, 49], "reference_oper": 39, "refin": [1, 2, 3, 4, 5, 7, 11, 12, 13, 23, 25, 26, 30, 38, 39, 40, 41, 44, 45, 46, 48, 50, 54, 55, 56, 57, 61, 71, 89, 120, 122, 123, 124, 125, 128, 129], "refine_": [8, 42, 47, 48, 123], "refine_adp_input": [8, 49], "refine_adp_model": [8, 49], "refine_aniso_atom": [8, 49], "refine_as_given": [8, 49], "refine_atom": 49, "refine_atoms_refin": 49, "refine_blob": 49, "refine_blobs_ion": 49, "refine_blobs_ligand": 49, "refine_blobs_model_error": 49, "refine_blobs_wat": 49, "refine_bulk_solvent_b_sol": 49, "refine_bulk_solvent_k_sol": 49, "refine_clash": 49, "refine_d_min": 49, "refine_d_min_limit": 49, "refine_devic": 49, "refine_free_flag": [47, 49], "refine_free_reflect": 49, "refine_free_set_class": [47, 49], "refine_free_set_sourc": [47, 49], "refine_french_wilson": [47, 49], "refine_ncs_": 49, "refine_ncs_chain": 49, "refine_ncs_copi": 49, "refine_ncs_group": 49, "refine_ncs_releas": 49, "refine_ncs_restraint": 49, "refine_ncs_rmsd": 49, "refine_ncs_rmsd_start": 49, "refine_ncs_sigma": 49, "refine_par": [8, 47], "refine_r_fre": [40, 49, 50], "refine_r_free_plac": 49, "refine_r_free_start": [8, 49], "refine_r_work": [49, 50], "refine_r_work_plac": 49, "refine_r_work_start": [8, 47, 49], "refine_reason": 49, "refine_reflect": 49, "refine_residues_fix": 49, "refine_residues_fixed_nam": [47, 49], "refine_rigid_bodi": 49, "refine_rmsd_angl": 49, "refine_rmsd_angles_start": 49, "refine_rmsd_bond": 49, "refine_rmsd_bonds_start": 49, "refine_rmsd_metal_bond": [8, 49], "refine_score_": [8, 42, 47, 49], "refine_score_b_aniso": 49, "refine_score_b_iso": 49, "refine_score_b_sol": 49, "refine_score_fom": 49, "refine_score_hydrogen": 49, "refine_score_k_overal": 49, "refine_score_k_sol": 49, "refine_score_mask_spac": 49, "refine_score_n_fre": 49, "refine_score_n_work": 49, "refine_score_nll_fre": 49, "refine_score_nll_work": 49, "refine_score_r_fre": 49, "refine_score_r_work": 49, "refine_score_rmsd_angl": 49, "refine_score_rmsd_bond": 49, "refine_score_rmsd_bonds_al": 49, "refine_score_rmsd_metal_bond": 49, "refine_score_rmsz_angl": 49, "refine_score_rmsz_bond": 49, "refine_second": 49, "refine_solv": [25, 42, 49, 123, 128, 129], "refine_solvent_": [8, 42, 49], "refine_solvent_ad": [8, 49], "refine_solvent_ambigu": 49, "refine_solvent_best": 49, "refine_solvent_build_round": [8, 49], "refine_solvent_build_second": 49, "refine_solvent_disagre": 49, "refine_solvent_ion": 49, "refine_solvent_ions_disagre": 49, "refine_solvent_label": 49, "refine_solvent_not_solv": [8, 49], "refine_solvent_relabel": [8, 49], "refine_solvent_remov": [8, 49], "refine_solvent_sit": 49, "refine_tls_group": [8, 49], "refine_twin": [8, 42, 47, 49], "refine_twin_fract": [8, 49], "refine_twin_fraction_nul": 49, "refine_twin_free_clos": [8, 49], "refine_twin_law": [8, 49], "refine_twin_multi": [8, 49], "refine_twin_multi_domain": [8, 49], "refine_twin_multi_null_z": 49, "refine_twin_multi_r_fre": 49, "refine_twin_multi_r_free_nul": 49, "refine_twin_multi_r_work": 49, "refine_twin_null_z": [8, 49], "refine_twin_r_fre": 49, "refine_twin_r_free_nul": [8, 49], "refine_twin_r_work": [8, 49], "refine_twin_rul": [8, 49], "refine_twin_split_pair": 49, "refine_untwinned_r_fre": 49, "refine_untwinned_r_work": [8, 49], "refine_xray_weight": 49, "refined_beam_center_i": 1, "refined_beam_center_x": [1, 25], "refined_detector_distance_mm": [1, 25], "refined_detector_tilt": 6, "refined_map_coeffici": 1, "refined_model": [1, 71, 125], "refinement_tim": 1, "refinementgpu": 21, "refinementgpucard": 21, "refinementgpuengin": 21, "refinementgpulan": 21, "refinementminimis": 8, "refinementtim": 23, "refit": [0, 2, 3, 4, 6, 7, 8, 39, 42, 49], "refl": 7, "reflect": [0, 1, 2, 3, 4, 5, 6, 8, 11, 12, 21, 24, 25, 26, 33, 38, 39, 40, 41, 42, 43, 44, 45, 47, 48, 49, 50, 55, 57, 64, 122, 123, 124, 133], "reflecting_rang": 50, "reflecting_range_": 49, "reflex": 55, "reflns_us": [46, 49], "refmac": [4, 7, 8, 12, 21, 38, 47, 49, 55], "refmac5": [0, 2, 3, 8, 39, 40, 46, 47], "refmac_reason": 40, "refmac_refined_ratio": 40, "refmac_refined_reason": 40, "refmac_refined_rfree_shar": 40, "refmac_refined_rfree_shared_depdata": 40, "refmac_rfre": 40, "refmac_rfree_depdata": 40, "refmac_rfree_depflag": 40, "refmac_rfree_ratio": 40, "refmac_statu": 40, "refrain": 29, "refres_": [40, 42, 47, 49], "refres_cc_anom": 49, "refres_cc_half": 49, "refres_complet": 49, "refres_i_over_sigma": 49, "refres_isa": 49, "refres_measured_rang": 49, "refres_multipl": 49, "refres_r_mea": 49, "refres_r_meas_weight": 49, "refres_rang": 49, "refres_shells_past_limit": 49, "refres_sigano": 49, "refres_total_observ": 49, "refres_unique_reflect": 49, "refresh": 2, "refus": [0, 1, 2, 4, 5, 6, 8, 12, 21, 24, 25, 26, 27, 38, 39, 40, 41, 42, 44, 45, 47, 49, 51], "refused_detector_tilt": 6, "refut": [4, 7], "regard": [2, 18, 29], "regardless": [6, 7, 17, 23, 27, 29, 62], "regener": [2, 8, 29, 35, 56], "region": [0, 5, 6, 8, 12, 13, 21, 26, 30, 42, 44, 53, 56, 71], "regist": [12, 15, 26], "registr": 2, "registri": [9, 37], "regress": [7, 8, 40, 46], "regular": [0, 3, 8, 25, 135], "regularis": 7, "regularli": 53, "reimplement": [3, 6], "reindex": [2, 4, 6, 7, 23, 39, 40, 47, 49, 50], "reindexmatrix": [2, 23, 39], "reiniti": 71, "reinstat": [17, 29], "reintroduc": 7, "reiv": [0, 8], "reject": [0, 1, 2, 3, 5, 6, 7, 21, 23, 24, 25, 27, 38, 39, 42, 46, 47, 48, 49, 50, 86, 121, 125], "rel": [0, 1, 2, 4, 5, 6, 7, 9, 11, 12, 13, 23, 24, 25, 27, 39, 40, 42, 44, 46, 49, 50, 62, 71, 96, 139], "relabel": [2, 4, 7, 8, 25, 38, 39, 42, 47, 49, 50, 128], "relaid": 21, "relat": [0, 2, 3, 4, 7, 8, 12, 17, 39, 40, 42, 49], "related_cel": 49, "relationship": 29, "relative_b": 46, "relax": 7, "releas": [0, 1, 2, 9, 12, 17, 19, 23, 24, 25, 26, 28, 29, 37, 38, 40, 42, 43, 49, 50, 52, 53, 59, 61, 71, 96, 134], "relev": [0, 23, 29, 68], "reli": [27, 29, 34], "reliabl": [2, 12, 39, 49], "relicens": 29, "reload": [2, 26], "rem": 46, "remain": [2, 4, 5, 6, 7, 11, 12, 17, 23, 26, 27, 29, 37, 38, 46, 47, 49, 82], "remaind": [0, 24], "remap": [11, 23, 53], "remark": [8, 47], "remark3_count": [47, 49], "remedi": 6, "rememb": [2, 26, 40], "remerg": [4, 42, 50], "remot": [2, 12, 40], "remov": [0, 1, 2, 4, 5, 6, 7, 8, 9, 12, 19, 21, 24, 25, 27, 29, 36, 38, 40, 42, 43, 45, 46, 47, 49, 50, 59, 62, 71, 96, 128, 134], "renam": [2, 23, 24, 25, 27, 40, 46, 49, 71], "render": [2, 29, 42, 49], "renormalis": [7, 42], "renumb": [2, 49], "reopen": 26, "reorder": [4, 16], "reorganis": 2, "reorient": [0, 2, 6, 133], "reorient_cryst": 49, "rep": [12, 13], "repaint": 26, "repair": [4, 5, 29, 46, 49], "repeat": [0, 2, 5, 6, 7, 12, 17, 24, 26, 38, 42, 46, 49, 50], "repeatedli": 4, "replac": [2, 3, 5, 6, 7, 8, 12, 15, 25, 26, 36, 38, 39, 40, 42, 43, 44, 45, 47, 48, 50, 51, 56, 59, 61, 68, 71, 122, 134], "replai": [25, 42, 57], "repli": [18, 25], "replic": [4, 21, 49], "repo": [9, 37], "repod": 12, "repopul": 2, "report": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 19, 23, 24, 25, 26, 38, 39, 41, 42, 43, 45, 46, 47, 48, 50, 51, 53, 55, 57, 61, 71, 109, 121, 122, 123, 124, 125, 131], "report_priv": 40, "report_vers": [2, 49], "repositori": [0, 9, 10, 12, 19, 26, 28, 36, 38, 40, 43, 52, 55, 57, 59, 61, 62], "repres": [4, 6, 7, 29, 40, 42, 71], "represent": [0, 6, 17, 23, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "reprocess": [2, 12, 22, 42, 46], "reproduc": [0, 2, 4, 5, 6, 7, 8, 12, 23, 39, 40, 46, 49, 56, 57], "reproducibli": 2, "repub_watermark": 27, "republish": [2, 23, 51], "repuls": [8, 21], "request": [2, 7, 13, 14, 18, 20, 21, 23, 26, 27, 38, 42, 45, 49, 51, 62, 86], "requir": [2, 5, 6, 7, 9, 14, 17, 19, 23, 25, 26, 28, 29, 36, 42, 45, 46, 47, 49, 50, 53, 54, 56, 57, 63, 68, 71, 96], "rerun": 40, "resampl": [11, 49], "rescal": [0, 1, 2, 3, 4, 5, 7, 8, 23, 46, 49, 55], "rescu": [2, 4, 5, 6, 11, 45, 48], "research": [0, 2, 17, 30, 49], "reserv": [2, 4, 11, 20, 21, 40, 45, 46], "reserved_cpu": [25, 128, 129], "reset": [2, 20, 26, 57, 71, 128], "reshap": [2, 4, 7, 50], "resid": [5, 21, 40, 45], "residu": [0, 2, 4, 7, 8, 11, 12, 21, 39, 41, 42, 47, 48, 49, 107], "residual_median": 21, "residue_nam": 1, "resili": 2, "resiz": [2, 26], "resolut": [0, 1, 2, 3, 6, 7, 8, 11, 12, 13, 15, 20, 21, 23, 25, 26, 33, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 51, 55, 61, 71, 96, 98, 113, 122, 124, 125, 133, 134], "resolution_a": 50, "resolution_combin": 12, "resolution_cut_plain": 49, "resolution_estim": 1, "resolution_fit": 49, "resolutionestim": 23, "resolv": [2, 4, 5, 6, 12, 13, 23, 29, 38, 39, 42, 44, 47, 49], "resonet": 2, "resort": 12, "resourc": [0, 36], "respect": [0, 2, 4, 8, 17, 26, 29], "respond": [4, 7, 18, 24], "respons": [2, 5, 7, 9, 12, 22, 25, 29, 50, 51], "rest": [0, 2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 25, 26, 27, 28, 31, 35, 36, 38, 40, 42, 45, 47, 49, 51, 52, 53, 61, 62, 71, 123], "restart": [8, 25, 26, 71], "restat": 46, "restor": [2, 5, 7, 42], "restrain": [0, 2, 3, 6, 21, 38, 40, 42, 47, 48, 49, 56, 57, 123], "restraint": [0, 2, 3, 6, 21, 40, 47, 49, 56], "restraint_kernel": 21, "restrict": [0, 2, 4, 5, 6, 7, 17, 26, 29, 49, 51, 89, 113], "result": [1, 2, 4, 5, 6, 7, 8, 12, 13, 15, 16, 18, 19, 21, 29, 36, 38, 39, 40, 42, 44, 45, 46, 47, 48, 50, 51, 55, 60, 61, 62, 63, 70, 71, 92, 108, 125, 128, 131, 132], "result_scan_get": 62, "resum": 13, "retain": [7, 17, 23, 29], "retent": 91, "reticular": 0, "retir": [1, 40], "retri": [2, 5, 6, 27, 49, 71], "retriev": [12, 23], "return": [2, 4, 5, 6, 7, 25, 27, 29, 40, 42, 46, 49, 51, 62, 65, 68, 93, 96, 108, 134], "retyp": 49, "reus": [2, 5, 6, 12, 13, 23, 39, 40, 44, 49, 55], "reusabl": 23, "rev": [0, 3, 9, 12], "reveal": [4, 51], "revers": [0, 2, 4, 5, 6, 7, 49, 51], "revert": [2, 5], "review": [2, 29], "revis": [0, 2, 3, 8, 29], "revisit": 4, "revolut": 49, "reweight": [0, 3, 8], "rework": 2, "rewrit": [2, 4], "rewritten": [2, 23], "rf_z": [49, 122], "rfc": 1, "rfree_fract": 7, "rfree_refin": 40, "rgb": 1, "rh": [0, 4, 12, 45], "rhaetian": 30, "rhel": [2, 9, 26, 28, 36, 43, 52, 53, 59], "rhel8": 25, "rhel_release_cod": 19, "rhizobial": 12, "rhizobium": 12, "rho": [4, 7], "rho_q": 8, "rhodopseudomona": 12, "rhombohedr": [0, 4, 6], "rhyme": 30, "rh\u00e4tisch": 30, "ribos": 12, "ribosid": 12, "ribosom": 0, "ribothymidin": 8, "ribulos": 12, "rice": [0, 4, 8, 49], "richardson": 0, "richer": 2, "ride": [0, 3, 8, 21, 47, 49], "ridg": 7, "rif1": 12, "rigaku": [0, 2, 12, 38, 44], "right": [2, 4, 5, 6, 7, 8, 11, 12, 17, 26, 29, 39, 40, 42, 46, 49, 90], "rigid": [0, 2, 3, 6, 8, 21, 25, 38, 39, 40, 42, 44, 45, 47, 48, 49, 50, 61, 122, 123], "rigid_bodi": [39, 47, 49, 122], "rigid_body_angle_deg": 122, "rigid_body_rotation_deg": 4, "rigid_body_shift_a": [4, 122], "rigidbodygpu": 21, "rigidli": 4, "rigu": [0, 8], "ring": [0, 1, 2, 3, 4, 8, 12, 21, 23, 25, 26, 27, 33, 38, 42, 46, 47, 48, 49, 57, 61, 68, 71, 96, 98, 107, 108, 109, 110, 113, 133, 134], "ring_current_m_a": 68, "ring_current_ma": 1, "ring_mod": 23, "ring_point": 109, "ring_seed_distance_mm": 109, "rint": [6, 46, 50], "rio": 13, "rippl": 55, "risc": 0, "rise": [4, 5, 6, 7, 8, 30, 49, 50], "risk": [17, 29, 51], "rival": [4, 49], "rival_refine_merg": 49, "rival_refine_r_fre": 49, "rival_refine_r_work": 49, "rival_refine_replac": 49, "rival_refine_space_group": 49, "rival_refine_twin": 49, "rival_refine_twin_law": 49, "rlp": [1, 46], "rm": [0, 1, 3, 6, 7, 8, 24, 25, 26, 33, 49, 68, 71, 92, 103, 123], "rmem_max": 27, "rms_radial_pxl": 109, "rmsd": [0, 3, 8, 12, 25, 47, 49], "rmsd_angles_deg": 123, "rmsd_bonds_a": 123, "rmsz": [47, 49], "rna": [0, 2, 8, 12, 47], "robin": 24, "robust": [0, 2, 3, 4, 5, 7, 8, 21, 24, 47, 49, 51], "rock": [0, 2, 4, 5, 6, 7, 21, 23, 39, 42, 46, 48, 49, 50, 55], "rocki": [2, 9, 19, 28, 36, 43, 52], "rocky8": 2, "rodin": 12, "roger": [0, 3], "rogu": [0, 3, 51], "roi": [1, 2, 16, 20, 21, 24, 25, 26, 28, 62, 71, 72, 100, 101, 112, 113, 114, 115, 116, 117, 118], "roi_azim_list": 112, "roi_azim_list_dict": 112, "roi_azim_list_from_dict": 112, "roi_azim_list_inst": 112, "roi_azimuth": 113, "roi_azimuthal_dict": 113, "roi_azimuthal_from_dict": 113, "roi_azimuthal_inst": 113, "roi_beam_pixel": 101, "roi_beam_sum": 101, "roi_box": 114, "roi_box_dict": 114, "roi_box_from_dict": 114, "roi_box_inst": 114, "roi_box_list": 115, "roi_box_list_dict": 115, "roi_box_list_from_dict": 115, "roi_box_list_inst": 115, "roi_calc": 20, "roi_circl": 116, "roi_circle_dict": 116, "roi_circle_from_dict": 116, "roi_circle_inst": 116, "roi_circle_list": 117, "roi_circle_list_dict": 117, "roi_circle_list_from_dict": 117, "roi_circle_list_inst": 117, "roi_definit": [71, 118], "roi_definitions_dict": 118, "roi_definitions_from_dict": 118, "roi_definitions_inst": 118, "roi_exampl": 71, "roi_integr": 1, "roi_map": [1, 23], "roi_mod": 72, "roi_nam": 23, "roiazimlist": [62, 118], "roiazimuth": [62, 112], "roibox": [62, 115], "roiboxlist": [62, 118], "roicircl": [62, 117], "roicirclelist": [62, 118], "roidefinit": [62, 71, 100], "roiintegrationgpu": 21, "role": [2, 28], "roll": 24, "rollback": 24, "rom": 29, "romanc": 30, "roo": 30, "room": [6, 12, 21, 23, 92], "root": [2, 5, 6, 7, 9, 13, 19, 20, 21, 25, 27, 40, 43, 45, 46, 62, 71], "root_dir": 27, "rose": 0, "rosetta": 36, "rossmann": [0, 3, 6], "rot": [5, 41, 46], "rot1": [1, 2, 5, 23, 41, 42, 68, 107, 109], "rot2": [1, 2, 5, 23, 41, 42, 68, 107, 109], "rot3": [1, 2, 5, 23, 42, 68], "rot3d": [2, 7, 42, 50], "rotam": [8, 47], "rotat": [1, 2, 3, 4, 5, 8, 11, 12, 13, 23, 25, 26, 28, 33, 36, 39, 40, 41, 44, 45, 46, 47, 48, 49, 51, 55, 61, 68, 69, 71, 96, 97, 107, 119, 121, 122, 124, 125, 128, 129, 132, 133], "rotation_axi": [46, 49, 119], "rotation_axis_dict": 119, "rotation_axis_from_dict": 119, "rotation_axis_inst": 119, "rotation_bravai": 132, "rotation_crystal_lattic": 132, "rotation_extra_lattic": 1, "rotation_index": [25, 96], "rotation_indexing_angular_stride_deg": [25, 96], "rotation_indexing_min_angular_range_deg": [25, 96], "rotation_lattic": 1, "rotation_lattice_typ": 1, "rotation_mast": 50, "rotation_rejected_deg": 49, "rotation_run": 50, "rotation_start_deg": 46, "rotation_unit_cel": 132, "rotationaxi": [62, 68], "rotationlatticeindex": 23, "rotationlatticeindexedextra": 23, "rotationlatticeniggliclass": 23, "rotationscalemerg": [2, 21, 45], "rotationscalemergegpu": 21, "rough": 7, "roughli": [4, 6, 7, 19, 22, 45], "round": [0, 2, 4, 5, 6, 7, 8, 11, 13, 15, 21, 24, 36, 39, 40, 42, 44, 45, 49, 50, 68], "rout": [4, 6, 25, 41, 46, 49], "routabl": 51, "routin": [0, 2, 4, 14, 40, 55, 56], "roversi": [0, 3, 8], "row": [0, 1, 2, 4, 5, 6, 7, 8, 11, 21, 23, 25, 33, 38, 39, 40, 42, 44, 46, 48, 49, 50, 56, 60, 68, 90, 124, 125, 131, 133, 135], "royalti": [17, 29], "rp": 1, "rpa3624": 12, "rpath": 2, "rpm": [2, 9, 19, 25, 26, 28, 36, 37, 40, 52, 53], "rrcat": 12, "rrna": 8, "rsigma": [46, 50], "rsm": 40, "rsp5": 12, "rss": [40, 45], "rtx": [21, 38, 50], "rugnux": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 15, 21, 22, 23, 26, 28, 33, 36, 37, 42, 44, 49, 51, 52, 53, 54, 55, 56, 59, 60, 62, 64, 68, 71, 77, 89, 96, 99, 108, 109, 120, 125, 128, 129, 134], "rugnux_": 40, "rugnux_anomal": 55, "rugnux_clear_post": 62, "rugnux_cli": [7, 23, 42, 49], "rugnux_download": 49, "rugnux_git": 49, "rugnux_live_blob": 120, "rugnux_live_blob_dict": 120, "rugnux_live_blob_from_dict": 120, "rugnux_live_blob_inst": 120, "rugnux_live_frame_rang": 121, "rugnux_live_frame_range_dict": 121, "rugnux_live_frame_range_from_dict": 121, "rugnux_live_frame_range_inst": 121, "rugnux_live_model": 122, "rugnux_live_model_dict": 122, "rugnux_live_model_from_dict": 122, "rugnux_live_model_inst": 122, "rugnux_live_refin": 123, "rugnux_live_refinement_dict": 123, "rugnux_live_refinement_from_dict": 123, "rugnux_live_refinement_inst": 123, "rugnux_live_shel": 124, "rugnux_live_shell_dict": 124, "rugnux_live_shell_from_dict": 124, "rugnux_live_shell_inst": 124, "rugnux_live_statu": [71, 125], "rugnux_live_status_dict": 125, "rugnux_live_status_from_dict": 125, "rugnux_live_status_inst": 125, "rugnux_live_step": 126, "rugnux_live_step_dict": 126, "rugnux_live_step_from_dict": 126, "rugnux_live_step_inst": 126, "rugnux_live_stil": 127, "rugnux_live_stills_dict": 127, "rugnux_live_stills_from_dict": 127, "rugnux_live_stills_inst": 127, "rugnux_map_ccp4_get": 62, "rugnux_model_cif_get": 62, "rugnux_report": [1, 4, 39, 42], "rugnux_set": [71, 128], "rugnux_settings_dict": 128, "rugnux_settings_from_dict": 128, "rugnux_settings_inst": 128, "rugnux_statu": [71, 129], "rugnux_status_dict": 129, "rugnux_status_from_dict": 129, "rugnux_status_get": 62, "rugnux_status_inst": 129, "rugnux_stills_ab": 55, "rugnux_summary_row": 130, "rugnux_summary_row_dict": 130, "rugnux_summary_row_from_dict": 130, "rugnux_summary_row_inst": 130, "rugnux_tim": 40, "rugnux_triage_item": 131, "rugnux_triage_item_dict": 131, "rugnux_triage_item_from_dict": 131, "rugnux_triage_item_inst": 131, "rugnux_vers": 49, "rugnuxliveblob": [62, 123], "rugnuxliveframerang": [62, 125], "rugnuxlivemodel": [62, 125], "rugnuxliverefin": [62, 122], "rugnuxliveshel": [62, 125], "rugnuxlivestatu": [62, 71], "rugnuxlivestep": [62, 125], "rugnuxlivestil": [62, 125], "rugnuxset": [62, 71, 99], "rugnuxstatu": [62, 71], "rugnuxsummaryrow": [62, 125], "rugnuxtriageitem": [62, 125], "rule": [0, 2, 4, 5, 6, 7, 8, 14, 19, 21, 23, 29, 36, 38, 42, 45, 46, 47, 49, 50, 120], "rumantsch": 30, "run": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 15, 19, 21, 22, 23, 24, 26, 29, 30, 33, 36, 37, 38, 39, 41, 43, 44, 46, 48, 51, 52, 53, 54, 55, 56, 57, 59, 60, 61, 62, 65, 68, 71, 75, 77, 96, 101, 107, 108, 109, 122, 123, 124, 125, 126, 127, 128, 129, 131, 136, 137], "run0808_1": 13, "run1": 13, "run130637": 13, "run130642": 13, "run157084": 13, "run157089": 13, "run1_mast": 44, "run2_mast": 44, "run3": 13, "run47": 13, "run67": 13, "run9": 13, "run_": 13, "run_000238": 13, "run_000243": 13, "run_a": 40, "run_b": 40, "run_nam": [1, 24, 27, 68, 71], "run_numb": [1, 24, 27, 68, 71, 101], "runawai": 6, "rung": [5, 6, 8], "runnabl": 25, "runner": [2, 4, 5, 8, 39, 47, 49], "runs_root": 40, "runtim": [26, 29, 36, 52, 59, 61, 62], "rupp": [0, 3, 4], "rvert": [5, 7], "rx": 11, "rx_statu": 18, "ry": 11, "rz": 11, "r\u00f6ttger": [0, 3, 5], "r\u2080": 0, "s0": 46, "s00": 13, "s0013091500077853": 0, "s0021889800018227": 0, "s0021889805040677": 0, "s0021889807021206": 0, "s0021889809016690": 0, "s0021889811041768": 0, "s0021889812002312": 0, "s0021889882011959": 0, "s0021889882012060": 0, "s0021889892009762": 0, "s0021889897008777": 0, "s0025": 0, "s0076": 0, "s01": 13, "s0108270101003961": 12, "s0108270193003464": 12, "s0108767301016658": 0, "s0108767302001046": 0, "s010876730302186x": 0, "s0108767305015266": 0, "s0108767312014535": 0, "s0108767386099622": 0, "s010876738709977x": 0, "s0108767388009195": 0, "s0108767388009596": 0, "s0108767389010718": 0, "s0108767393007597": 0, "s0108767394005726": 0, "s0108767395002340": 0, "s010876739500688x": 0, "s0108767396004370": 0, "s0108767398010186": 0, "s010876810000269x": [0, 49], "s0108768102001039": 0, "s0108768185002063": 0, "s0108768190011041": 0, "s0108768191014726": 0, "s0108768194004933": 0, "s0108768197018454": 0, "s02": 13, "s0365110x49000813": 0, "s0365110x50000513": 0, "s0365110x52002161": 0, "s0365110x67003172": 0, "s0567739476000533": 0, "s0567739476000636": 0, "s0567739476001873": 0, "s0567739478001114": 0, "s0567739478001618": 0, "s0567739481000600": 0, "s0567740868001718": 0, "s0907444900014736": 0, "s0907444900019168": 0, "s0907444901012471": 0, "s0907444902010284": 0, "s0907444902018000": 0, "s0907444903007947": 0, "s0907444903008163": 0, "s0907444904023510": 0, "s0907444905001617": 0, "s0907444905007894": 0, "s0907444905023589": 0, "s0907444905031537": 0, "s0907444905036693": 0, "s0907444905036759": 0, "s0907444906005270": 0, "s0907444906014594": 0, "s0907444906044271": 0, "s090744490705531x": 0, "s0907444909047337": [0, 49], "s0907444909047374": 0, "s0907444910007493": 0, "s090744491003982x": 0, "s0907444910045749": 0, "s0907444910048675": 0, "s0907444911001314": 0, "s0907444911007773": 0, "s0907444911028320": 0, "s090744491105606x": 0, "s0907444912001308": 0, "s0907444912006737": 0, "s0907444912045374": 0, "s0907444913000061": 0, "s0907444913001121": 0, "s0907444995016477": 0, "s0907444996012255": 0, "s0907444999003972": 0, "s090744499900935x": 0, "s0907444999009506": 0, "s0969": 0, "s0p85": 55, "s1": [9, 55], "s12900": 0, "s1399004713025431": 0, "s1399004714001308": 0, "s1399004714003277": 0, "s1399004714014795": 0, "s1399004715004241": 0, "s1600576714007626": 0, "s1600576714011996": 0, "s1600576716005471": 0, "s1600576716013595": 0, "s1600576724003182": [0, 34], "s1600576726008083": [0, 28, 34], "s1600577515003288": 0, "s1600577522010268": [0, 28, 34], "s1p2": 55, "s2052252523008618": 34, "s2052519213010014": 12, "s2052520616017844": 12, "s2053229614024218": 0, "s2059798316002187": 0, "s2059798316014716": 0, "s2059798317000584": 0, "s2059798317000699": 0, "s2059798317001061": 0, "s2059798317017235": 0, "s2059798318002978": 0, "s2059798318004576": 0, "s2059798319011471": 0, "s2059798320003198": 0, "s2059798320006348": 0, "s2059798321001170": 0, "s2059798322010026": 0, "s2059798323003595": 0, "s2414314622008525": 12, "s2414314622010598": 12, "s2414314625005917": 12, "s241431462500879x": 12, "s339": 3, "s350": 3, "s4": 9, "s41586": 0, "s41598": 12, "s65t": 12, "s_": 4, "s_b": 5, "sa": 15, "saccharomyc": 12, "sacla": [2, 13, 38, 42, 44], "sacla236": 13, "sacla237": 13, "sacla243": 13, "sacla_236": 13, "sacla_237": 13, "sacla_243": 13, "sacla_raw": 13, "sad": [4, 12, 46], "sad_fa": 46, "sad_i": 46, "saddl": 30, "safe": [6, 9, 19, 23, 46, 49, 50, 53, 57], "safeguard": [5, 47], "safest": 29, "safeti": [24, 71], "safit": 12, "sah": [8, 12, 47], "sai": [1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 23, 25, 26, 28, 29, 36, 38, 39, 40, 41, 42, 44, 46, 47, 49, 50, 51, 61, 75, 77, 90, 109, 110, 125], "said": [0, 1, 7, 12, 22, 23, 40, 41, 45, 46], "sajson": 56, "sake": 29, "sala": 34, "sale": [17, 29], "salt": [4, 5, 49], "salzburg": 0, "sam": [8, 12, 47, 56], "same": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 15, 17, 18, 21, 23, 24, 25, 26, 27, 28, 29, 30, 33, 36, 37, 38, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 55, 56, 57, 59, 61, 70, 71, 75, 77, 104, 109, 122, 123, 124, 125, 133, 134], "sampl": [0, 1, 2, 3, 4, 5, 6, 7, 11, 21, 27, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 51, 55, 68, 71, 90, 96, 108], "sample_1": 24, "sample_nam": [1, 27, 68], "sample_temperature_k": [1, 68], "sanction": 23, "sandi": 36, "sanit": 40, "santacruz": 13, "sar": 12, "sass": 36, "sat": [4, 49, 133], "satellit": 4, "satisfactori": 17, "satisfi": [6, 7, 17, 29, 71], "satur": [0, 1, 2, 4, 6, 7, 15, 16, 20, 21, 23, 26, 27, 42, 44, 49, 50, 53, 71, 101, 133], "saturated_pixel": [23, 101], "saturated_pixel_count": 1, "saturated_valu": 44, "saturation_valu": [1, 2, 23, 53], "saturn": [2, 12, 44], "saturn944": 12, "sauter": 0, "save": [2, 5, 7, 26, 27, 33, 45, 68, 71, 87, 92, 97], "save_calibr": [24, 68], "saw": [4, 7, 25, 50, 121], "sax": 15, "sbgrid": [0, 12, 40], "sc": 71, "sc6_1_master": 40, "scala": 0, "scalar": [0, 1, 2, 6, 7, 23, 46], "scale": [1, 2, 3, 5, 6, 23, 25, 26, 30, 38, 40, 44, 45, 46, 47, 48, 49, 50, 54, 57, 61, 71, 107, 109, 121, 125], "scale_g": 50, "scale_modulation_peak_to_trough": 49, "scalepack": 0, "scaler": 39, "scaleus": 46, "scaling_not_converg": [25, 38, 42, 49], "scan": [1, 2, 4, 5, 6, 7, 12, 23, 25, 40, 42, 44, 45, 46, 48, 49, 50, 51, 55, 61, 62, 68, 69, 70, 71, 90, 119, 132, 133], "scan_result": [2, 71, 132], "scan_result_dict": 132, "scan_result_from_dict": 132, "scan_result_images_inn": 133, "scan_result_images_inner_dict": 133, "scan_result_images_inner_from_dict": 133, "scan_result_images_inner_inst": 133, "scan_result_inst": 132, "scanresult": [62, 71], "scanresultimagesinn": [62, 132], "scatter": [0, 2, 4, 5, 6, 7, 8, 12, 21, 39, 40, 41, 42, 45, 46, 47, 48, 49, 55, 107, 109], "scatter_kernel": 21, "scattering_typ": 46, "schedul": 4, "schema": [1, 2, 12, 23, 24, 40, 41], "scheme": [2, 6, 15, 26, 31, 44, 49, 51, 62, 68], "scherrer": [30, 61, 62], "schmidt": [0, 8], "schmitt": [0, 34], "schneider": [0, 3, 8], "schomak": [0, 8], "school": [0, 29], "schreur": 12, "schwarzenbach": 0, "sci": [0, 3, 12, 13], "scienc": [0, 3, 34], "scientist": 51, "scope": [3, 5, 29], "score": [0, 1, 2, 3, 5, 6, 7, 8, 12, 21, 25, 26, 38, 39, 40, 42, 46, 47, 48, 49, 50, 55, 122], "score_d_min": 49, "score_sigma_a3": 49, "scorer": 12, "scott": [0, 3, 8], "scottish": 30, "scpa": 12, "scrambl": 7, "scratch": [4, 6, 41], "screen": [0, 1, 4, 7, 9, 12, 26, 38, 39, 50, 119], "screening_wedg": 1, "screening_wedge_deg": 119, "screenshot": 26, "screw": [0, 2, 3, 4, 12, 26, 39, 40, 46, 47, 48, 49, 55], "screw_undetermin": 12, "script": [2, 12, 14, 19, 25, 26, 29, 40, 46, 49, 50, 51, 57, 71], "scsc": 12, "sd": [4, 47, 49], "se": 49, "sea": 9, "seal": 12, "seam": 5, "sean": 56, "search": [0, 2, 3, 4, 5, 7, 8, 21, 25, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 56, 59, 96, 122], "seat": [2, 23, 39], "second": [0, 1, 2, 4, 5, 6, 7, 8, 12, 18, 23, 24, 25, 27, 38, 39, 40, 41, 42, 45, 46, 47, 48, 49, 50, 68, 71, 90, 123, 125, 127, 129, 133, 139], "secondari": [1, 2, 24], "secondarili": 29, "secret": [12, 17, 51, 68], "section": [0, 2, 3, 4, 5, 6, 7, 8, 12, 13, 17, 23, 24, 25, 26, 29, 38, 39, 40, 42, 46, 47, 49, 50, 53, 121, 122], "sector": [1, 2, 5, 6, 15, 21, 23, 26, 110, 113], "secur": [2, 17, 19, 25, 26, 27, 31, 54, 60, 68, 71], "sed": 49, "see": [0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 17, 19, 20, 23, 24, 25, 26, 27, 28, 29, 31, 32, 33, 35, 36, 38, 39, 40, 42, 44, 46, 47, 49, 50, 51, 52, 53, 55, 56, 57, 59, 60, 61, 62, 68, 71, 75, 77, 96, 109, 113, 134], "seed": [4, 5, 6, 42], "seek": 17, "seen": [1, 5, 6, 7, 12, 18, 23, 121], "segment": [2, 8, 21, 49, 51], "sehnal": 0, "select": [0, 1, 2, 4, 5, 7, 15, 21, 23, 24, 26, 41, 44, 46, 47, 49, 62, 68, 71, 89, 95], "select_detector": [62, 71], "selector": 2, "self": [0, 2, 3, 4, 6, 7, 21, 23, 26, 36, 38, 39, 42, 43, 45, 46, 50, 134], "sell": [17, 29], "seltzer": 0, "semant": [2, 54], "semi": [7, 8, 51], "semiconductor": 29, "seminumer": 0, "send": [1, 2, 4, 7, 9, 14, 16, 18, 20, 23, 24, 25, 27, 35, 38, 50, 62, 71, 90, 91, 134, 136, 140], "send_buffer_s": [24, 25, 136, 140], "send_watermark": [24, 25, 140], "sender": [1, 27], "sens": [7, 46, 47], "sensibl": [5, 12], "sensit": [0, 2, 3, 5], "sensor": [0, 1, 2, 7, 11, 12, 23, 33, 42, 44, 46], "sensor_materi": [1, 23, 25, 72], "sensor_thick": [1, 23], "sensor_thickness_um": [25, 72], "sent": [1, 2, 6, 18, 23, 24, 25, 38, 40, 42, 51, 71, 99, 101, 128, 136, 138, 139], "sentenc": [12, 49], "sentinel": 23, "sep": 0, "separ": [0, 1, 2, 3, 4, 5, 6, 7, 9, 12, 14, 18, 22, 23, 26, 28, 29, 30, 36, 39, 40, 42, 44, 46, 47, 49, 50, 51, 55, 56, 71, 107, 109], "seq15": 12, "seq_num": 1, "seqid": 49, "sequenc": [0, 1, 5, 8, 12, 21, 24, 25, 38, 46, 47, 49, 50, 71], "sequenti": [1, 7], "seri": [0, 1, 2, 3, 7, 12, 13, 27, 30, 44, 45, 46, 68], "serial": [1, 2, 3, 4, 5, 6, 7, 12, 21, 23, 24, 28, 34, 39, 40, 48, 49, 53, 54, 55, 57, 58, 61, 68, 124, 125, 127, 128, 138, 139, 140], "serial_modul": 38, "serial_module_plac": 38, "serial_numb": [2, 23, 25, 72, 74, 88], "serialis": 40, "series_id": 1, "series_unique_id": 1, "serin": 12, "seriou": [25, 26, 45, 131], "serv": [4, 5, 7, 8, 9, 12, 13, 25, 28, 29, 51, 56, 61, 125], "server": [2, 9, 13, 14, 18, 25, 26, 28, 29, 33, 36, 40, 45, 61, 71, 82, 140], "server_vers": 82, "servic": [0, 2, 9, 17, 27, 28, 29, 36, 37, 43, 45, 51, 57, 59, 61], "session": [9, 26, 40, 51, 60, 68], "sessionstorag": 51, "set": [0, 1, 2, 3, 4, 5, 6, 8, 9, 11, 12, 13, 16, 17, 18, 19, 20, 21, 23, 24, 27, 33, 37, 41, 42, 44, 45, 46, 48, 49, 50, 51, 55, 57, 60, 61, 62, 63, 64, 67, 68, 71, 72, 80, 92, 96, 97, 99, 119, 123, 124, 125, 126, 134, 136, 139, 140], "set1": 12, "set3": 12, "setdb1": 12, "setgid": 51, "sethttptoken": [26, 51], "settabl": 2, "setting_oper": [4, 39, 49], "setting_sourc": [39, 47, 49], "settl": [0, 2, 4, 5, 6, 7, 12, 23, 38, 39, 40, 42, 44, 46, 47, 49, 50], "setup": [0, 2, 6, 11, 20, 21, 23, 38, 40, 42, 44, 50, 62], "seven": [6, 12, 22, 49], "seventeen": [6, 12], "seventh": 7, "sever": [0, 2, 4, 5, 6, 7, 8, 12, 21, 23, 25, 26, 30, 33, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 50, 55, 131], "sf": [7, 39, 42, 46, 47], "sfac": [46, 50], "sfrm": [2, 12, 38, 42, 44, 50], "sfx": 13, "sg": [2, 4, 39, 47, 49, 50, 122], "sgaltern": 46, "sgi": [0, 56], "sgmt": 12, "sh": [19, 26, 35, 40, 56], "sh2": 12, "sh3a": 12, "sha1": 20, "sha256": 40, "shabalin": 0, "shade": 0, "shadow": [2, 3, 5, 7, 8, 15, 21, 23, 25, 33, 38, 42, 47, 48, 50, 53, 71, 127], "shadow_pixel": 127, "shadowaccumulatorgpu": 21, "shadowmaskgpu": 21, "shaken": 8, "shall": [17, 29], "shallow": [4, 6], "shanno": [0, 3, 8], "shape": [0, 1, 4, 5, 6, 7, 8, 21, 23, 42, 44, 49], "share": [0, 2, 4, 5, 6, 7, 8, 9, 12, 15, 17, 21, 23, 25, 26, 27, 29, 36, 40, 42, 43, 44, 45, 46, 47, 49, 51, 53, 59, 61, 63, 110, 134], "sharff": [0, 3], "sharp": [4, 7], "sharpen": [4, 38, 50], "sharpli": 7, "sheldrick": [0, 3, 8], "shell": [0, 2, 4, 5, 6, 8, 21, 25, 26, 38, 39, 40, 42, 44, 45, 46, 47, 49, 50, 55, 98, 124, 125], "shells_merg": [25, 125], "shelx": [2, 7, 38, 44, 50], "shelxc": [2, 38, 46, 50, 55], "shelxd": [46, 50], "shelxl": [0, 2, 7, 8, 38, 44, 50], "shelxl97": [0, 8], "shelxt": [38, 50], "sheriff": [0, 3], "shield": 0, "shift": [0, 2, 5, 6, 7, 8, 26, 40, 41, 42, 44, 46, 49, 50, 107, 109], "shindyalov": 0, "ship": [2, 6, 7, 26, 28, 36, 40, 42, 43, 45, 46, 52, 53, 57, 59], "shoemak": [0, 3], "short": [0, 2, 4, 5, 6, 7, 8, 12, 21, 23, 25, 29, 38, 40, 42, 44, 45, 46, 48, 49, 50, 53, 123], "shortcut": [2, 36, 59], "shorten": [6, 49], "shorter": [2, 6, 8, 42, 48, 50], "shortest": [6, 8, 39, 42], "shortlist": [5, 6, 21], "shot": [0, 2, 44], "should": [0, 1, 2, 4, 5, 7, 12, 14, 17, 18, 19, 20, 22, 23, 24, 25, 26, 29, 34, 40, 42, 46, 47, 49, 71, 92, 133, 134, 139, 140], "shoulder": [5, 49], "show": [2, 4, 5, 6, 7, 8, 12, 14, 24, 25, 26, 29, 38, 39, 40, 42, 43, 44, 46, 47, 48, 49, 50, 55, 60, 61, 71, 103, 109, 110], "show_beam_cent": 71, "show_predict": 71, "show_res_est": 71, "show_res_r": 71, "show_roi": 71, "show_spot": 71, "show_user_mask": 71, "shower": [5, 49], "shown": [4, 11, 26, 38, 40, 42, 49], "shrank": 7, "shrink": [4, 7, 8, 21, 26, 47, 49], "shrunk": [0, 7], "shuffl": [4, 5, 21, 49], "shutter": [5, 49, 71], "si": [7, 12, 25, 26, 41, 42, 72], "siam": [0, 3], "sibl": [21, 24, 49], "sibling_twin": 49, "sici": 0, "side": [0, 1, 2, 4, 6, 7, 8, 12, 18, 21, 22, 24, 30, 39, 40, 42, 43, 45, 46, 47, 48, 49, 54, 134], "sidebar": 35, "sigano": [0, 2, 7, 38, 39, 49, 50], "sigbg": 46, "sigdano": 46, "sigf": [2, 4, 7, 40, 42, 46, 47, 50], "sigfp": [42, 46, 47], "sighup": 27, "sigi": [42, 46, 47, 50], "sigimean": [4, 42, 46, 47, 50], "sigint": [27, 42], "sigkil": 45, "sigma": [0, 1, 2, 3, 4, 5, 6, 7, 8, 26, 38, 41, 42, 46, 47, 49, 50, 55, 71, 107, 109, 120, 121, 122, 123, 124, 125], "sigma_": [4, 5, 7], "sigma_0": [4, 7], "sigma_2": 5, "sigma_a": [0, 2, 3, 4, 8, 49], "sigma_b": 5, "sigma_c": 4, "sigma_f": 7, "sigma_m": 7, "sigma_m_deg": [49, 50], "sigma_o": 4, "sigma_r": 7, "sigma_t": 7, "sigma_xyz_a": 49, "sigmar": [49, 50], "sign": [0, 1, 2, 4, 5, 6, 7, 11, 15, 23, 24, 26, 29, 36, 37, 39, 40, 42, 43, 44, 45, 46, 48, 49, 50, 59, 71, 92, 136], "signal": [0, 1, 2, 4, 5, 6, 8, 12, 15, 20, 21, 23, 25, 33, 38, 39, 40, 42, 46, 47, 49, 50, 55, 67, 125, 131], "signal_to_noise_threshold": 134, "signatur": [4, 15, 37, 46, 49], "signed": 23, "signed_output": [25, 92], "signific": [0, 2, 4, 5, 7, 29, 41, 42, 49, 55], "significantli": [2, 4, 6, 49], "sigquit": 27, "sigterm": 27, "silenc": [4, 24], "silent": [2, 4, 6, 7, 12, 39, 45, 55], "silicon": [0, 6, 26, 36, 40, 41, 43, 45, 59], "siliconjfjoch": 59, "siliconrugnux": 43, "silver": [0, 2, 3, 6, 41], "sim": 7, "similar": [7, 8, 14, 17, 21, 22, 23, 24, 29, 47, 62], "similarli": 2, "simpl": [0, 4, 7, 40, 42], "simpler": [2, 98], "simplest": [11, 26], "simpli": [4, 5, 7, 8, 27, 39, 46, 47, 49], "simplif": 0, "simplifi": [0, 1, 2, 8, 52], "simplon": [2, 5, 15, 23, 57, 134], "simu": [0, 8], "simul": [0, 2, 3, 4, 6, 8, 9, 14, 25, 29, 42, 49, 71], "simultan": [24, 29], "sin": [4, 5, 6], "sin4": 6, "sinc": [2, 4, 5, 6, 7, 8, 12, 24, 26, 38, 40, 42, 46, 47, 49, 50, 51, 53, 108, 125, 126, 127], "singl": [0, 1, 2, 4, 5, 6, 7, 8, 9, 20, 21, 22, 23, 24, 25, 27, 29, 35, 36, 38, 40, 42, 44, 45, 46, 47, 49, 50, 53, 55, 57, 68, 71, 86, 93, 109], "singleton": 4, "singular": [0, 1, 3, 8], "sinorhizobium": 12, "sit": [2, 4, 5, 6, 7, 8, 11, 14, 26, 38, 39, 40, 42, 43, 45, 46, 49, 55], "site": [0, 2, 3, 7, 8, 12, 13, 27, 30, 35, 36, 38, 39, 40, 42, 44, 47, 49, 55, 56], "situ": 12, "situat": [2, 18, 39, 49], "six": [0, 2, 3, 4, 5, 6, 7, 8, 12, 21, 40, 42, 49], "sixteen": [6, 12], "sixteenth": 5, "sixth": 6, "sixti": 35, "size": [0, 1, 2, 4, 6, 7, 8, 11, 12, 13, 15, 19, 20, 21, 22, 23, 24, 25, 26, 27, 33, 39, 40, 42, 43, 44, 45, 47, 49, 51, 53, 68, 71, 77, 96, 99, 104, 109, 129, 134, 135, 136, 140], "size_i": 106, "size_x": 106, "skeleton": 55, "skew": [2, 7, 42], "skip": [2, 4, 5, 6, 7, 8, 12, 21, 25, 38, 39, 40, 42, 47, 48, 50, 55, 96, 123, 125], "skovoroda": [0, 3, 8], "skubak": 0, "skub\u00e1k": [0, 3, 8], "sl": [0, 1, 12, 16, 69], "slab": 44, "slash": 27, "sleep": 21, "slice": [2, 7, 12, 23, 49], "slid": [6, 7, 8, 49], "slide": [5, 6], "slider": [2, 26], "slightli": [2, 4, 7, 47, 50], "slip": 49, "slippag": 7, "slit": 68, "slope": [2, 5, 7, 42, 49], "slot": [2, 8, 9, 14, 21, 23, 25, 71, 91], "slot_gather_kernel": 21, "slow": [1, 2, 5, 7, 8, 11, 23, 25, 27, 40, 44, 53, 75, 77, 90, 139], "slow_axi": [1, 25, 42, 44, 68, 75, 77], "slow_pixel_direct": [11, 23, 44], "slow_step": [25, 44, 77], "slowdown": 40, "slower": [25, 40, 42, 45, 47, 123], "slowest": [4, 7, 23, 40], "slowli": [7, 8], "sls9": 10, "slsdet8": 37, "slsdet9": [10, 37], "slsdetectorpackag": [10, 28, 37, 52, 56], "sm_121": 36, "sm_70": 36, "sm_90": 36, "small": [0, 2, 3, 4, 5, 6, 7, 8, 12, 13, 21, 22, 24, 25, 26, 27, 30, 38, 39, 40, 41, 42, 44, 45, 47, 48, 49, 96, 134], "smaller": [2, 5, 6, 7, 8, 13, 25, 42, 43, 49, 59, 119], "smallest": [0, 2, 4, 5, 6, 8, 40, 49, 91, 96], "smargon": [1, 2, 23, 68, 69], "smart": [0, 12, 44], "smartnic": [28, 36, 54], "smc04462": 12, "smear": [0, 4, 5, 6, 7, 49, 110], "smegmati": 12, "smghrb": 12, "smi": 40, "smoke": 40, "smooth": [0, 1, 2, 5, 6, 8, 21, 23, 41, 42, 49, 50, 133], "smoothcorr": 21, "smoother": [0, 3, 7], "smv": [0, 2, 5, 26, 38, 42, 44, 50, 59], "sn": 12, "sn001": 25, "sn002": 25, "sn2100": 22, "snake": [1, 2, 90], "snake_scan": [1, 23], "snap": 6, "snapshot": 0, "snell": 0, "so": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 17, 18, 19, 21, 22, 23, 24, 25, 26, 27, 29, 30, 33, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 49, 50, 51, 52, 53, 55, 56, 57, 59, 62, 68, 71, 96, 107, 108, 109, 110, 119, 125, 134, 136], "so_sndbuf": 24, "so_zerocopi": 24, "soak": [4, 8, 47], "sobott": 0, "soc": [0, 3, 13], "socia": 0, "societi": 56, "socket": [1, 2, 25, 27, 51, 57, 62, 71, 93, 101, 136, 138, 139, 140], "socket_address": [25, 71, 138, 139], "socket_numb": [1, 24], "soft": [2, 7, 8, 30, 39, 49, 62, 71, 86], "softli": 47, "softw": [0, 3, 8], "softwar": [1, 2, 3, 5, 17, 23, 25, 28, 29, 30, 36, 49, 54, 55, 61, 71, 99, 134, 136, 140], "software_git_commit": 23, "software_git_d": 23, "sohnck": [2, 4], "sohncke_space_group": [2, 4, 49], "sol": [4, 7, 8, 46, 47], "sold": 29, "sole": [1, 11, 23, 29, 62, 68], "soleil": 12, "solid": [0, 2, 5, 7, 8, 11, 15, 42, 63], "solid_angle_corr": [25, 63], "solidanglearrai": [2, 5], "solu": 46, "solut": [0, 1, 2, 3, 4, 7, 10, 20, 23, 34, 38, 39, 46, 50, 132, 133], "solv": [0, 2, 3, 4, 6, 7, 8, 12, 21, 34, 46], "solvat": [0, 8], "solvent": [2, 3, 5, 7, 21, 25, 38, 39, 40, 42, 46, 47, 49, 123, 128, 129], "solver": [6, 56], "sol\u00e9": 0, "some": [0, 2, 4, 5, 6, 7, 11, 15, 21, 23, 24, 27, 29, 38, 39, 40, 42, 45, 49, 50, 52, 71], "someon": [12, 40], "someth": [1, 4, 5, 6, 7, 11, 12, 17, 23, 26, 30, 39, 49], "sometim": [47, 49, 134], "somewhat": 8, "somewher": [7, 44], "soon": [1, 2, 4, 5, 25, 26, 109], "sooner": 2, "sorri": 46, "sort": [1, 2, 4, 5, 21, 23, 38, 42, 45, 46], "sort_ord": 1, "sound": [5, 30, 39], "sourc": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 17, 19, 20, 21, 25, 28, 29, 34, 35, 36, 37, 38, 39, 40, 42, 44, 49, 50, 52, 53, 57, 61, 68, 97], "source_nam": [1, 25, 97], "source_polarz": [5, 42], "source_run": 40, "source_typ": [1, 25, 97], "south": 30, "sp": 12, "spac": 46, "space": [1, 2, 3, 6, 8, 12, 13, 19, 21, 23, 24, 25, 26, 27, 39, 40, 41, 42, 44, 45, 46, 48, 50, 51, 54, 55, 61, 63, 68, 71, 125, 126, 132, 134], "space_group": [2, 23, 39, 40, 47, 49, 122, 125], "space_group_achiral_altern": 49, "space_group_altern": [2, 46, 49, 50], "space_group_centr": [4, 46, 49, 50], "space_group_enantiomorph": [2, 46, 47, 49, 50], "space_group_nam": [1, 4, 46, 49, 50], "space_group_numb": [1, 2, 23, 27, 49, 50, 68], "space_group_refused_point_group": 46, "space_group_screw_undetermin": 49, "spag": 46, "spallat": 97, "span": [2, 4, 6, 7, 11, 23, 50], "spare": [4, 29], "spark": [2, 36, 43, 45, 52], "spars": [0, 2, 3, 4, 5, 6, 7, 12, 21, 42, 50, 56], "sparseccl": [0, 3, 5, 56], "sparser": 7, "spatial": [7, 44], "spb": 13, "spdlog": [2, 52, 56], "spdx": 56, "speak": [12, 29, 51, 56], "spec": [2, 32, 55], "speci": [8, 12, 49], "special": [0, 4, 5, 6, 8, 12, 15, 16, 17, 18, 19, 20, 29, 49, 55, 71, 92], "specif": [1, 3, 4, 5, 7, 9, 14, 15, 17, 22, 23, 25, 29, 31, 51, 53, 54, 62, 68, 97], "specifi": [15, 17, 23, 29], "spectra": 2, "spectrum": [1, 6, 21, 23], "speed": [2, 6, 9, 18, 40, 45, 49, 55, 88, 92], "spell": [36, 44, 46, 47, 49], "spend": 47, "spent": [1, 6, 40], "spermidin": 12, "sphere": [0, 1, 2, 6, 7, 8, 21, 23, 42, 47, 49, 56, 133], "spheric": [0, 3, 4, 7, 50], "spike": 12, "spill": [4, 40], "spin": 21, "spindl": [0, 1, 2, 4, 5, 7, 11, 23, 44, 46, 49, 50, 90, 119], "spindle_blind": 133, "spindle_blind_fract": [1, 2], "spindle_cap": 49, "spindle_lost_unique_fract": [1, 2, 6, 49], "spindle_symmetry_axis_angle_deg": [2, 49], "spindle_symmetry_axis_ord": [2, 49], "spindleblindfract": [2, 6, 23], "spindleblindfractionmean": 23, "spindlelostuniquefract": [2, 6, 23, 49], "spindletrigg": 6, "spiral": 30, "spirit": [7, 17, 29, 62], "splice": 44, "split": [0, 2, 3, 4, 5, 6, 7, 8, 12, 15, 21, 22, 38, 39, 40, 42, 45, 46, 47, 49, 50, 53, 68], "splitmix64": 0, "splittabl": 0, "spnox": 12, "spoil": 2, "spoken": 30, "spot": [1, 2, 3, 4, 11, 16, 20, 24, 25, 26, 27, 28, 38, 39, 40, 41, 44, 45, 47, 48, 50, 51, 54, 55, 57, 59, 61, 62, 63, 64, 68, 71, 89, 96, 98, 109, 110, 133, 134], "spot_count": 1, "spot_count_ice_control": [1, 5], "spot_count_ice_r": [1, 5], "spot_count_index": 1, "spot_count_low_r": 1, "spot_cross_check": 109, "spot_false_pixels_loosen": [42, 49], "spot_find": [56, 62, 68, 71, 99, 134], "spot_finder_mask": 20, "spot_finding_set": [2, 5, 25, 71, 134], "spot_finding_settings_dict": 134, "spot_finding_settings_from_dict": 134, "spot_finding_settings_inst": 134, "spot_finding_tim": 1, "spot_maximum": 5, "spot_resolution_estim": [2, 5, 49], "spot_width": 7, "spotextractorgpu": [5, 21, 56], "spotextractorgpuparitytest": 5, "spotfindingset": [62, 71, 99, 100], "spotfindingtim": 23, "spots_ic": 133, "spots_index": 133, "spots_low_r": 133, "spread": [2, 4, 5, 6, 7, 8, 9, 12, 21, 40, 42, 48, 49, 50], "spring": 12, "spur": 5, "spuriou": [2, 5, 6, 7, 134], "sq": [20, 68], "sqrt": [2, 4, 5, 6, 7, 8, 15, 16, 21, 49, 68], "sqrtmult": 15, "squar": [0, 1, 2, 3, 4, 5, 6, 7, 8, 21, 23, 25, 44, 47, 49, 89], "squeez": 4, "sr": 12, "src": [2, 9], "srm": 0, "sroka": 0, "ss": 44, "ssd": 50, "sse4": [36, 40], "ssh": [2, 26], "ssl": 2, "ssrf": 12, "ssrl": 12, "ssvm": [0, 3], "ssx": [2, 53, 55], "stabil": [0, 2, 6, 7, 8, 12], "stabl": [0, 2, 7, 9, 14, 23, 36, 49], "stabli": 21, "stack": [0, 2, 7, 9, 11, 14, 20, 23, 36, 37, 44, 45, 71], "stadler": [0, 3, 34], "staff": 51, "stage": [1, 4, 5, 8, 21, 23, 25, 28, 40, 42, 44, 45, 47, 48, 49, 71, 123, 125], "stage_exampl": 71, "stai": [2, 4, 5, 6, 7, 8, 12, 21, 23, 24, 25, 26, 27, 39, 40, 41, 42, 45, 47, 48, 49, 50, 51, 68, 71], "stale": 49, "stall": [2, 20, 24, 27], "stamp": [27, 49], "stand": [0, 2, 4, 5, 6, 7, 8, 12, 25, 29, 39, 41, 42, 44, 46, 48, 49, 50, 55, 57, 109, 122, 131], "standalon": [2, 9, 26, 57, 59], "standard": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 15, 20, 25, 26, 27, 29, 30, 39, 40, 41, 42, 46, 47, 49, 50, 52, 55, 63, 68, 71, 107, 109, 122], "standard_detector_geometri": 135, "standard_detector_geometry_dict": 135, "standard_detector_geometry_from_dict": 135, "standard_detector_geometry_inst": 135, "standard_geometri": [25, 72], "standarddetectorgeometri": [62, 72], "standardis": [0, 7, 23], "standfuss": 34, "staphylococcu": 12, "stapl": [26, 36], "star": 140, "staraniso": [0, 3, 4, 49], "start": [0, 2, 3, 4, 5, 6, 7, 8, 12, 16, 20, 21, 23, 24, 26, 27, 29, 31, 33, 35, 36, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 56, 57, 59, 60, 61, 65, 68, 71, 80, 90, 91, 119, 125, 126, 140], "start_post": 62, "start_tim": [1, 23], "start_to_first_image_": 125, "started_": 126, "startfail": 24, "starting_angl": 49, "startup": [2, 38, 49], "starv": [2, 4, 7], "starvat": [7, 12], "stat": [0, 2, 3], "state": [1, 2, 4, 5, 6, 7, 12, 13, 16, 17, 21, 23, 24, 25, 28, 29, 38, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 51, 60, 62, 65, 71, 81, 82, 90, 108, 119, 122, 123, 125, 127], "statement": [4, 5, 7, 12, 23, 29, 49, 50, 110], "static": [2, 5, 7, 10, 36, 45, 52, 69], "station": [7, 30, 42], "stationari": [2, 5, 23, 42], "statist": [0, 1, 2, 3, 4, 6, 8, 12, 21, 25, 26, 27, 38, 39, 40, 42, 46, 47, 49, 50, 51, 55, 60, 61, 62, 68, 71, 100, 124, 125], "statistics_calibration_get": 62, "statistics_data_collection_get": 62, "statistics_get": 62, "statistiqu": [0, 3], "statu": [2, 7, 18, 20, 24, 25, 26, 29, 39, 40, 45, 46, 47, 49, 51, 57, 62, 71, 93, 128], "status_code_sf": 12, "status_get": 62, "stb": 56, "stb_image_writ": 56, "std": [21, 23, 45], "stddev": 2, "stdout": 49, "steadili": 5, "steal": [7, 51], "stearic": 12, "steel": 0, "steep": [4, 7, 30], "steepest": [7, 8], "steepli": 7, "steer": [23, 38, 47], "stegun": [0, 8], "stein": [0, 3], "steiner": [0, 8], "steller": [0, 3, 6], "stem": 44, "stencil": [7, 21, 42], "stenotrophomona": 12, "step": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 16, 21, 23, 25, 26, 28, 29, 33, 38, 42, 44, 45, 46, 48, 49, 50, 51, 56, 60, 71, 77, 90, 111, 119, 125, 126], "step_i": 23, "step_progress": 125, "step_x": 23, "step_x_axi": 1, "step_x_um": 90, "step_y_axi": 1, "step_y_um": 90, "stereochemistri": [0, 8], "stiff": 8, "still": [0, 1, 2, 3, 4, 5, 8, 11, 12, 19, 21, 23, 24, 25, 26, 27, 39, 40, 44, 45, 46, 48, 51, 54, 55, 61, 68, 71, 119, 123, 125, 128, 129, 134], "still_batteri": [13, 40, 55], "still_manifest": 13, "stillsgivenunitcel": [23, 39], "stillsradialscal": [7, 23], "stillsrockingwidth": 7, "stillsrockingwidthformula": 23, "stillsrockingwidtht": 23, "stillsrockingwidthtabledstar": 23, "stood": [1, 2, 6, 12, 23, 90, 119], "stop": [2, 3, 4, 6, 7, 8, 14, 15, 16, 21, 23, 24, 25, 26, 27, 33, 38, 39, 40, 42, 45, 46, 47, 48, 49, 50, 51, 53, 71, 107, 127], "storag": [0, 1, 2, 3, 8, 19, 20, 23, 29, 51, 60, 68, 71, 80], "storage_cel": 1, "storage_cell_delai": [1, 23], "storage_cell_imag": 23, "storage_cell_numb": [1, 23, 66], "store": [1, 2, 5, 6, 7, 11, 13, 21, 23, 25, 26, 27, 30, 38, 39, 40, 41, 42, 44, 46, 53, 55, 57, 61, 68, 71, 75, 77, 80], "storoni": [0, 3], "str": [65, 68, 71, 72, 74, 82, 85, 88, 93, 97, 99, 101, 102, 104, 106, 108, 109, 113, 114, 116, 119, 120, 121, 122, 123, 125, 126, 127, 130, 131, 132, 136, 138, 139, 140], "straddl": 4, "strai": 51, "straight": [4, 6, 7, 21, 36, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50], "straightforward": 9, "strain": 6, "strategi": [0, 6], "stratif": 7, "stratifi": 7, "streak": [7, 42], "stream": [1, 2, 4, 5, 10, 11, 13, 14, 19, 21, 23, 25, 26, 27, 28, 30, 38, 42, 44, 51, 54, 57, 58, 61, 62, 68, 71, 99, 136, 140], "stream2": [1, 24, 28], "streamwait": 21, "strength": [0, 2, 4, 7, 49], "streptococcu": 12, "streptomyc": 12, "stretch": [0, 2, 4, 7, 23, 25, 30, 49, 50, 121, 125], "strict": [5, 36, 40, 45], "strictli": [1, 2, 4, 7], "stride": [2, 7, 23, 42, 49, 50], "string": [1, 2, 12, 23, 27, 46, 51, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "strip": [2, 49], "strong": [0, 1, 2, 3, 4, 6, 7, 12, 15, 21, 23, 42, 46, 49, 98], "strong_pixel_count": 1, "stronger": [47, 49], "strongest": [0, 1, 3, 4, 5, 6, 7, 8, 23, 39, 42, 46, 49, 50, 122, 123, 133], "strongli": [2, 4, 5, 7, 40, 42, 49, 50, 61], "strongpixel": 23, "strongpixelset": [5, 56], "struct": [0, 3, 8, 34, 46], "struct_a": 46, "structur": [1, 2, 3, 5, 6, 7, 8, 9, 20, 21, 23, 25, 26, 34, 38, 39, 40, 41, 42, 44, 45, 49, 50, 55, 56, 61, 71, 99, 136, 140], "structure_refin": [8, 56], "stuck": 5, "student": 49, "studi": [17, 61], "studio": [26, 36, 52], "stutzeri": 12, "style": [0, 1, 4, 7, 8, 12, 39, 47, 49, 56, 98], "sub": [2, 5, 6, 7, 17, 23, 42, 68, 71], "subchain": [1, 8], "subcommand": 40, "subcommitte": 0, "subdivid": 29, "subgroup": [0, 2, 4, 7, 12, 39, 42, 46, 47, 48, 49, 50], "subject": [5, 6, 7, 17, 29, 62], "sublattic": [5, 6, 12], "sublicens": 29, "submiss": 21, "subprogram": 29, "subproject": 56, "subroutin": 29, "subscrib": 51, "subscript": [2, 26], "subsect": [17, 29], "subsequ": [5, 6, 15, 17, 80], "subset": [0, 8, 9, 13, 15, 21, 23, 25, 47, 55, 56, 96], "subsp": 12, "subspac": [0, 8], "substanc": 0, "substanti": [2, 4, 6, 23, 27, 29, 36], "substitut": [4, 6, 17, 22, 24, 46], "substr": 46, "substrat": [12, 13], "substructur": [0, 46], "subsystem": [2, 14, 20, 30], "subtend": 5, "subtili": 12, "subtler": 50, "subtract": [2, 4, 6, 7, 21, 44, 46, 49], "subunit": 8, "succe": 45, "succeed": [6, 71], "success": [1, 2, 7, 23, 24], "successfulli": [18, 101], "sudo": [9, 19, 37, 43, 45, 62], "sue": 29, "suffic": 29, "suffici": [0, 4, 6, 8, 17], "suffix": [2, 12, 27, 49, 87], "sugar": 8, "suggest": [17, 27, 49], "suit": [0, 3, 4, 42, 46, 134], "suitabl": [6, 46], "suitespars": 2, "sulfat": [8, 47], "sulfur": [4, 46, 49, 55], "sulphat": 12, "sultana": [0, 3, 8], "sum": [0, 1, 2, 4, 5, 6, 7, 8, 11, 15, 21, 23, 25, 26, 41, 42, 46, 49, 50, 51, 57, 101, 109, 110, 133], "sum_": [4, 5, 7], "sum_d": 8, "sum_f": 7, "sum_i": [6, 7], "sum_j": [7, 8], "sum_k": [6, 7], "sum_sq": 23, "sum_squar": 1, "summari": [1, 2, 23, 25, 38, 40, 50, 125, 131], "summaris": [40, 47, 49], "summat": [0, 1, 2, 3, 4, 5, 16, 20, 21, 23, 25, 26, 28, 68, 92, 98], "summation_mod": [1, 23], "summit": 30, "sun": [26, 56], "superbright": 12, "supercel": [2, 6, 12, 25, 42, 49], "supercell_class": 49, "supercell_doubled_cel": 49, "supercell_i_over_sigma": 49, "supercell_occupancy_pct": 49, "supercell_poss": 49, "supercell_rock_pct": 49, "supercell_rock_se_pct": 49, "supergroup": 12, "superlattic": 6, "superposit": [0, 3, 8, 40, 49], "supersed": 71, "superset": 36, "superstructur": [2, 6, 7, 12, 40], "superus": 19, "supplement": [13, 29], "suppli": [0, 3, 4, 6, 7, 36, 39, 41, 46, 49, 50, 56], "support": [1, 2, 3, 6, 7, 8, 11, 12, 14, 17, 18, 20, 22, 24, 26, 28, 29, 36, 41, 42, 43, 44, 49, 50, 51, 53, 54, 59, 62, 71, 86], "suppress": [2, 4, 5, 6, 42, 49], "sure": [29, 45, 71], "surfac": [0, 2, 3, 5, 6, 7, 8, 11, 21, 23, 42, 45, 48, 49, 50], "surfact": 12, "surpris": [0, 40], "surrend": 29, "surround": [8, 38, 49], "survei": [0, 8], "surviv": [2, 4, 5, 7, 13, 29, 30, 42], "suspect": [46, 47], "sustain": [29, 57], "svobodov\u00e1": 0, "swap": [2, 4, 25, 40, 44, 75, 77], "swatman": 0, "sweep": [0, 1, 2, 4, 5, 6, 7, 21, 23, 25, 26, 28, 38, 39, 40, 42, 43, 44, 45, 46, 48, 50, 55, 59, 61, 68, 121, 125, 133], "sweep2": 12, "sweep_00001": [38, 42], "sweep_count": 49, "sweep_coverag": 49, "sweep_coverage_full_turn": 49, "sweep_decay_model": 49, "sweep_disposit": 49, "sweep_gap": 49, "sweep_k_batch_first": 49, "sweep_k_batch_last": 49, "sweep_k_cc_half_alon": 49, "sweep_k_cel": 49, "sweep_k_completeness_alon": 49, "sweep_k_decis": 49, "sweep_k_dist": 49, "sweep_k_dose_rank": 49, "sweep_k_held_out_ad": 49, "sweep_k_held_out_chang": 49, "sweep_k_held_out_change_s": 49, "sweep_k_imag": 49, "sweep_k_includ": 49, "sweep_k_input": 49, "sweep_k_isa": 49, "sweep_k_isomorphism_ratio": 49, "sweep_k_isomorphism_ratio_s": 49, "sweep_k_reindex_cc": 49, "sweep_k_reindex_op": 49, "sweep_k_relative_b": 49, "sweep_k_reprocessed_from": 49, "sweep_k_resolution_alon": 49, "sweep_k_scal": 49, "sweep_k_space_group_alon": 49, "sweep_left_out": 49, "sweep_mast": 50, "sweep_quality_count": 49, "sweep_quality_reason": 49, "sweep_quality_statu": 49, "sweep_refer": 49, "sweep_rot": 49, "sweepqual": [23, 49], "sweepqualityreason": 23, "swing": [5, 11], "swiss": [12, 25, 30], "swissfel": [1, 2, 13, 20, 23], "swissfel_103": 13, "swissfel_213": 13, "switch": [2, 7, 8, 9, 14, 24, 25, 26, 28, 42, 46, 49, 60, 71], "switzerland": [30, 62], "swivel": 12, "swung": [2, 5, 6, 12, 40, 44], "sx": 1, "sxm4": 49, "sy": [1, 2, 19, 40], "syce2": 12, "sym_ov": 40, "sym_screw": 40, "sym_und": 40, "symbol": [2, 4, 6, 7, 25, 38, 39, 42, 46, 47, 56], "symm": [38, 46, 50], "symmetr": [2, 4, 6, 7, 8, 21, 39, 42, 49, 50], "symmetri": [2, 3, 5, 7, 8, 21, 25, 38, 39, 40, 41, 42, 44, 46, 47, 48, 50], "symmetry_ambigu": 49, "symmetry_hypothes": 49, "symmetry_hypothesis_": 49, "symmetry_suspect": 49, "symmorph": [4, 49], "sync": [2, 26], "synchron": [2, 24, 71, 140], "synchronis": 5, "synchrotron": [0, 1, 3, 12, 15, 25, 28, 34, 38, 46, 68, 97], "syntax": 46, "synthas": 12, "synthesi": [0, 4, 16, 25, 29, 55, 57], "synthet": 12, "synthetas": 12, "syringa": 12, "syscal": 62, "sysctl": [26, 45], "syst": 0, "system": [0, 1, 2, 5, 6, 7, 9, 11, 12, 14, 19, 22, 23, 25, 26, 28, 29, 30, 33, 34, 38, 41, 42, 43, 45, 49, 51, 61, 62, 96, 132], "systemat": [0, 2, 4, 6, 12, 29, 39, 40, 41, 42, 46, 48, 49, 50, 55, 109], "systemd": 9, "t": [0, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 18, 19, 21, 22, 24, 27, 33, 34, 41, 42, 47, 49, 62, 65, 71, 92, 96], "t1663r": 12, "t203i": 12, "t39k": [0, 8], "t4": [21, 22, 36, 43, 59], "t4d01f": 0, "t_": [4, 6, 8], "t_b": 5, "t_d": 8, "tab": [2, 25, 26, 51, 60], "tabl": [0, 1, 2, 3, 4, 7, 8, 11, 13, 18, 20, 21, 22, 24, 25, 36, 38, 39, 41, 42, 43, 44, 45, 46, 47, 50, 55, 56, 124, 125], "tabul": [0, 7, 8, 40, 42], "tag": [1, 5, 12, 36, 44, 55], "tail": [4, 5, 6, 7, 12, 42], "takaba": 2, "take": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 13, 21, 22, 23, 25, 26, 28, 29, 36, 38, 39, 41, 42, 43, 44, 45, 47, 48, 49, 50, 51, 53, 55, 59, 60, 61, 63, 68, 71, 121, 125], "taken": [0, 1, 2, 4, 5, 6, 7, 8, 12, 18, 21, 25, 27, 38, 39, 40, 41, 42, 44, 46, 47, 49, 50, 53, 68, 109, 125], "talli": 6, "tan": [5, 6, 7, 11, 23, 41, 109], "tan2": 6, "tangent": 5, "tangenti": [7, 42], "tangibl": 29, "tanh": [4, 8], "tao": 56, "tape": 5, "tar": [9, 12, 13, 36, 38, 40, 43, 45, 59], "tarbal": [12, 13], "target": [0, 2, 3, 4, 7, 12, 14, 19, 21, 26, 36, 37, 40, 42, 45, 47, 49, 50, 51, 53, 56], "task": [2, 40], "tau": [0, 3, 6, 7], "tau_i": 7, "tau_k": 6, "tb": 13, "tbd": 2, "tcl": 14, "tcp": [2, 25, 27, 28, 93, 94, 99, 101, 136, 138, 139], "tcp_keepcnt": 24, "tcp_keepidl": 24, "tcp_keepintvl": 24, "tcp_set": [24, 136], "tcp_settings_dict": 136, "tcp_settings_from_dict": 136, "tcp_settings_inst": 136, "tcpset": [62, 99], "tdo": 12, "teach": 7, "technic": [2, 61], "techniqu": [0, 3, 8, 11], "technolog": 29, "technologi": 56, "tee": 37, "tell": [0, 1, 2, 4, 5, 6, 7, 8, 12, 23, 24, 26, 27, 29, 38, 39, 40, 41, 42, 46, 47, 48, 49, 50], "temp": [2, 44, 46], "temp_thresold_deg_c": 72, "temperatur": [1, 2, 12, 14, 23, 39, 44, 46, 68, 72, 82, 92], "templat": [11, 12, 13, 40, 42, 44, 55], "temporari": [2, 23, 134], "ten": [2, 4, 5, 6, 7, 23, 30, 38, 39, 42, 45, 49], "tend": 50, "tenfold": 4, "tensor": [0, 3, 4, 6, 7, 46, 49], "tenth": [2, 4, 5, 6, 7], "terabyt": 23, "term": [0, 1, 2, 4, 5, 6, 7, 8, 17, 21, 23, 42, 46, 47, 49, 56, 61, 62], "termin": [2, 8, 12, 17, 20, 27, 29, 42, 43, 46, 49, 50, 51], "terminu": 30, "territori": [6, 49], "terwillig": 0, "test": [2, 3, 4, 5, 8, 9, 15, 17, 19, 21, 22, 26, 27, 36, 37, 38, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 52, 53, 54, 56], "test1": 27, "test2": 27, "test_data": 25, "tested_by_model": 49, "testifi": [4, 23], "tetartohedr": [0, 3], "tetragon": [1, 4, 6, 7, 8, 46, 49], "tetrahedr": 8, "tetrahydropyranofuran": 12, "tetramer": 12, "tetraspanin": 12, "tex12": 12, "text": [2, 4, 5, 6, 7, 8, 12, 17, 24, 26, 36, 42, 45, 49, 50, 51, 52, 56, 71, 131], "textbook": [8, 49], "textstyl": 7, "texttt": 7, "textur": [5, 6, 7, 41], "tf": 56, "tf_z": [49, 122], "tfrac": [4, 6, 7], "tfrac1": 7, "tfrac12": [4, 7, 8], "tfrac14": 4, "tfz": 55, "tgz": [2, 9, 26, 36, 38, 43, 45, 53, 59], "th": [0, 2, 4, 42], "th6h": 12, "thaliana": 12, "than": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 17, 19, 21, 23, 24, 25, 26, 27, 29, 33, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 54, 55, 56, 68, 71, 90, 98, 101, 103, 108, 109, 119], "thank": [0, 2, 27], "thauera": 12, "thaumatin": 40, "thei": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 15, 17, 19, 21, 23, 25, 26, 28, 29, 35, 36, 37, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 56, 61, 62, 75, 77, 99, 109, 128], "theirs": [0, 8, 39, 49], "them": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 15, 16, 17, 21, 22, 23, 24, 25, 26, 27, 28, 29, 34, 36, 38, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 51, 52, 54, 55, 56, 60, 61, 68, 108, 125, 127, 128, 134], "theme": [2, 26, 30], "themselv": [0, 2, 4, 5, 7, 12, 13, 21, 38, 39, 41, 44, 46, 49, 56], "theobald": [0, 3], "theori": 17, "thepaut": 12, "therefor": [4, 5, 6, 7, 9, 11, 12, 14, 18, 22, 23, 24, 25, 27, 29, 40, 45, 46, 47, 49, 52, 53], "thermal": [0, 3, 40], "thermocellu": 12, "thermophilum": 12, "theta": [1, 2, 4, 6, 7], "theta_": 6, "theta_k": 6, "theta_max": [46, 49], "theta_min": [46, 49], "thi": [0, 1, 2, 3, 9, 10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21, 22, 24, 25, 26, 27, 29, 30, 33, 36, 41, 44, 48, 51, 53, 55, 56, 58, 61, 62, 63, 65, 68, 71, 72, 80, 86, 89, 91, 92, 93, 96, 99, 101, 107, 108, 109, 124, 128, 131, 133, 134, 136, 139, 140], "thiamin": 12, "thiazolyl": 12, "thick": [1, 2, 7], "thin": [4, 7, 49, 50], "thing": [0, 2, 4, 5, 7, 9, 11, 12, 21, 29, 39, 46, 47, 49, 54, 134], "thiobacillu": 12, "thioether": 8, "thiophen": 12, "thioredoxin": 12, "third": [2, 4, 5, 6, 7, 8, 17, 21, 23, 26, 29, 36, 42, 46, 49, 52, 53, 61], "third_parti": 56, "third_party_licens": 56, "third_party_notic": [0, 2, 45, 49], "thirteen": [12, 55], "thirti": [6, 7, 12], "thorn": [0, 3, 5, 8], "those": [0, 2, 4, 5, 6, 7, 8, 11, 12, 17, 23, 25, 26, 27, 29, 30, 36, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 53, 56, 71, 109, 122], "though": [2, 4, 5, 7, 14, 15, 18, 19, 22, 23, 26, 29, 39, 68, 97, 134], "thousand": [4, 5, 6, 7, 21, 23, 30, 39, 48], "thousandth": 8, "thr": 120, "thread": [2, 4, 5, 6, 7, 8, 19, 21, 24, 25, 26, 38, 40, 42, 45, 49, 50, 55, 57, 60, 96, 99, 128, 129], "thread_count": 96, "threaten": 29, "three": [0, 1, 2, 3, 4, 5, 6, 8, 11, 12, 17, 21, 23, 24, 25, 27, 28, 29, 40, 41, 42, 46, 47, 49, 50, 53, 55], "threofuranosyl": 12, "threshold": [0, 1, 2, 3, 4, 5, 6, 7, 16, 20, 21, 25, 33, 40, 42, 44, 47, 49, 50, 67, 72, 80, 92, 103, 133, 134], "threshold_energi": [1, 23], "throttl": 2, "through": [0, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 19, 20, 21, 23, 25, 26, 28, 29, 30, 36, 40, 44, 45, 46, 47, 48, 49, 50, 53, 55, 57, 61, 62, 110], "throughout": [2, 4, 6, 7, 11, 25, 46, 49], "throughput": [0, 3, 23, 26, 27, 30, 36, 46, 59], "throw": [6, 40], "thrown": 24, "thu": [8, 29], "thymidin": 12, "ti": [4, 5, 6, 7, 8, 23, 36, 42, 46, 49], "tick": [6, 26], "ticket": 36, "tickl": [0, 3], "tie": [2, 4, 6, 8, 38, 46, 49], "tier": [7, 40, 46, 49], "tiff": [1, 2, 25, 26, 33, 44, 51, 62, 71, 86], "tifffil": 33, "tight": [6, 45], "tighten": 8, "tighter": [6, 8], "tightest": 6, "tightli": [8, 49], "tile": [7, 44], "till": [2, 71], "tilt": [0, 1, 2, 4, 5, 6, 7, 11, 23, 26, 41, 42, 46, 48, 49, 107, 109], "tilt_refin": 109, "tilt_signific": 109, "tim": 2, "time": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 13, 17, 21, 24, 25, 26, 27, 28, 29, 33, 34, 36, 38, 39, 42, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 61, 67, 68, 71, 72, 80, 92, 96, 123, 125, 136], "timeout": [2, 24, 40, 71], "timestamp": [2, 23, 38, 50, 87], "tini": 49, "tinycbor": [1, 56], "tinydir": 56, "tip": 6, "titl": [1, 12, 40, 46, 104, 106, 126], "tjon": 0, "tl": [0, 2, 8, 26, 47, 49, 51, 56], "tlsmd": [0, 8], "tmp": [2, 23, 27, 40, 87], "tnc": 49, "tncs_": [2, 4], "tncs_class": 49, "tncs_correl": 49, "tncs_correlation_averag": 49, "tncs_correlation_nul": 49, "tncs_detect": [2, 49], "tncs_modul": 49, "tncs_modulation_averag": 49, "tncs_modulation_depth_pct": 49, "tncs_modulation_nul": 49, "tncs_patterson_null_pct": 49, "tncs_patterson_peak_pct": 49, "tncs_patterson_peak_z": 49, "tncs_pseudo_centr": 49, "tncs_sublattic": 49, "tncs_vector": 49, "tncs_vector_length": 49, "to0": 6, "to_dict": [63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "to_json": [63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "todai": [30, 40, 51], "todd": 56, "todo": [63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "togeth": [0, 2, 4, 5, 6, 7, 8, 15, 21, 23, 24, 26, 30, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51], "toggl": [2, 26], "token": [2, 11, 25, 26, 31, 35, 38, 42, 60, 68, 71], "tolcapon": 12, "told": [2, 4, 6, 7, 23, 26, 36, 38, 42, 44, 45, 47, 49, 59, 107], "toler": [0, 1, 2, 4, 5, 7, 39, 42, 47, 49, 96, 133, 134], "tomykaira": 56, "too": [0, 2, 3, 4, 5, 6, 7, 8, 12, 21, 23, 25, 26, 27, 28, 29, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 55, 109], "too_high_pedestal_rm": 103, "took": [4, 7, 8, 12, 21, 25, 38, 40, 46, 49, 50, 123, 127], "tool": [0, 2, 4, 8, 9, 10, 12, 13, 17, 23, 25, 28, 29, 30, 31, 36, 37, 39, 40, 41, 47, 49, 50, 52, 55, 56, 61], "toolbar": [2, 26], "toolbox": [0, 3], "toolchain": [26, 36, 44], "toolkit": [0, 2, 8, 9, 26, 29, 36, 43, 45, 52, 56, 59], "toolset": [14, 26, 36, 45, 52], "tooltip": [2, 26], "top": [1, 2, 4, 5, 6, 7, 8, 9, 11, 23, 26, 30, 36, 38, 39, 43, 45, 49, 50, 51, 53, 55, 56, 59, 60, 71, 72, 90], "topic": 38, "topologi": [0, 3, 21], "toraya": [0, 3], "toro": [0, 3, 6, 34], "torsion": [0, 3, 8, 21], "tort": 17, "toss": [4, 6], "total": [0, 1, 2, 4, 5, 6, 7, 8, 21, 38, 40, 41, 42, 45, 49, 50, 133], "total_flux": [1, 2, 23, 68], "total_observ": 49, "total_slot": 91, "touch": [2, 4, 5, 7, 21, 40, 42, 45, 49, 51, 55], "tour": [59, 61], "toward": [0, 1, 2, 3, 4, 6, 7, 8, 11, 12, 42, 47, 49, 55], "tp": [12, 132], "tpc": 140, "tpd": 0, "tr": [8, 12], "traccc": [0, 3, 5, 21, 56], "trace": [6, 7, 8, 39, 40, 46], "traceless": 8, "track": [0, 2, 5, 6, 7, 24, 55], "trackbal": 0, "trade": [5, 6, 17, 29], "trademark": [17, 29], "traffic": [22, 51], "trail": [2, 5, 51], "train": [18, 30], "traitement": [0, 3], "trajectori": [6, 8, 47], "tran": [0, 3, 8], "transact": 29, "transceiv": 14, "transcript": 12, "transfer": [17, 19, 29, 68, 100], "transferas": 12, "transform": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 21, 40, 49, 56, 68, 90, 96], "transformation_typ": [1, 23], "transit": [7, 8, 56], "translat": [0, 1, 2, 3, 8, 12, 21, 23, 25, 40, 41, 45, 46, 47, 48, 108, 119, 122], "transmiss": [1, 2, 7, 29, 42, 68], "transmit": [62, 71], "transpar": [23, 24], "transport": [2, 6, 12, 26, 27, 51], "transpos": [5, 21, 44], "transthyretin": 12, "trap": [40, 46, 55], "travel": [1, 25, 41], "travers": 23, "treat": [1, 2, 4, 5, 6, 7, 8, 17, 23, 29, 36, 40, 42, 47, 49, 50, 51, 53, 68, 133], "treati": 29, "treatment": [0, 2, 3, 8, 49], "tree": [2, 6, 13, 21, 40, 49, 52, 59], "trek": [0, 2, 5, 12, 38, 42, 44, 50], "trend": [40, 47], "tri": [2, 4, 5, 6, 8, 12, 39, 40, 44, 47, 49, 55, 89], "triag": [25, 125], "trial": [3, 5, 6, 21, 25, 47, 48, 49, 123], "trichocarpa": 12, "trichomona": 12, "triclin": [1, 4, 6, 12, 38, 39, 41, 48, 49], "trigger": [1, 2, 4, 6, 23, 24, 48, 49, 62, 68, 71, 80, 82, 83, 97], "trigger_post": 62, "trigger_sourc": 23, "trigon": [1, 4, 49], "trilinear": 4, "trim": [2, 4, 6, 7, 9, 21, 25, 38, 39, 42, 50, 56, 72], "trim28": 12, "trim_energies_e_v": 72, "trim_energies_ev": 25, "trimer": 12, "trio": [12, 30], "trip": 5, "trip13": 12, "tripartit": 12, "tripl": [5, 6, 7], "triplet": [4, 6, 49], "trmd": 12, "trna": [8, 12], "troubl": 2, "trough": 4, "true": [1, 2, 4, 5, 6, 7, 23, 24, 25, 26, 27, 39, 42, 47, 49, 50, 63, 68, 71, 72, 92, 96, 134, 138, 139], "trueb": [0, 3], "trueblood": [0, 8], "truli": 7, "truncat": [2, 4, 6, 7, 8, 11, 12, 13, 42, 46, 49], "truncatula": 12, "trust": [0, 3, 5, 6, 8, 23, 46, 49, 51, 53, 56], "trusted_rang": [23, 53], "trustworthi": [5, 41], "truth": [4, 5, 7, 35, 39], "try": [2, 4, 9, 42, 47, 49, 50, 62, 71], "tryggvason": 0, "trypanosoma": 12, "trypsin": 12, "tt": 15, "ttl": [68, 71, 80, 97], "tube": [5, 7, 12, 42, 97], "tularensi": 12, "tune": [0, 2, 5, 6, 15, 42, 50, 134], "tunnel": 30, "turbo": 2, "ture": [2, 36, 43, 59], "turn": [1, 2, 4, 5, 6, 7, 8, 9, 12, 15, 18, 21, 23, 25, 28, 40, 41, 42, 44, 46, 47, 48, 49, 50, 51, 55, 62, 68, 71, 72, 92, 119, 134], "tutori": 13, "twelv": [4, 6, 12], "twenti": [4, 6, 12], "twentieth": 5, "twice": [2, 4, 5, 6, 7, 8, 11, 12, 21, 25, 39, 42, 46, 47, 49], "twin": [2, 3, 6, 7, 25, 39, 40, 42, 46, 47, 48, 50, 131], "twin_domain": 49, "twin_law": 49, "twin_law_n": 49, "twin_subgroup": [47, 49, 122], "twin_subgroup_altern": 49, "twin_subgroup_fil": 49, "twin_subgroup_fract": 49, "twin_subgroup_law": 49, "twin_subgroup_merg": 49, "twin_subgroup_model_twin_fract": 49, "twin_subgroup_r_fre": 49, "twin_subgroup_r_free_twin": 49, "twin_subgroup_r_work": 49, "twin_subgroup_r_work_twin": 49, "twin_subgroup_space_group": 49, "twinning_verdict": [8, 49], "two": [0, 1, 2, 3, 4, 7, 8, 9, 13, 14, 17, 18, 19, 21, 22, 24, 25, 26, 27, 29, 30, 33, 35, 36, 37, 38, 39, 41, 42, 44, 45, 46, 47, 48, 50, 52, 53, 55, 56, 71, 72, 75, 77, 80, 107, 109, 110, 134], "twofold": [4, 12], "tx": [14, 22], "tx_delai": [25, 72], "txt": [1, 2, 4, 23, 25, 38, 40, 42, 47, 49, 50, 56, 124, 125, 131], "type": [0, 2, 4, 5, 6, 7, 8, 12, 15, 19, 23, 25, 26, 29, 39, 41, 43, 44, 45, 46, 49, 50, 51, 53, 56, 62, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "type_exampl": 71, "typescript": [56, 60], "typic": [2, 4, 5, 6, 7, 8, 23, 29, 38, 42, 47, 49, 51], "u": [0, 2, 4, 5, 6, 7, 8, 12, 13, 21, 39, 46, 47, 49, 55, 71], "u11": 1, "u12": 1, "u13": 1, "u22": 1, "u23": 1, "u33": 1, "u55c": [14, 18, 22, 28, 61], "u8": 1, "u_": 8, "u_i": 8, "u_j": 8, "ub_matrix": 23, "ube2e1": 12, "ubiquitin": 12, "ubl": 12, "ubuntu": [2, 9, 26, 28, 36, 43, 52], "uc": 133, "udev": 19, "udp": [2, 12, 16, 18, 20, 23, 28, 57, 74], "udp_interface_count": [25, 72, 74], "uervirojnangkoorn": 0, "ug1469": 14, "ui": [51, 56], "uint16": [1, 23], "uint16_t": 24, "uint32": [1, 23, 33], "uint32_t": 24, "uint64": [1, 23], "uint64_max": 23, "uint64_t": 24, "uint8": [1, 23], "uintx_max": [23, 53], "uiuc": 56, "ulimit": 45, "ultrahigh": 12, "ultrascal": 14, "um": [12, 68], "uma": 12, "umbrella": 12, "un": [5, 6, 21, 46], "unaccept": 29, "unaffect": [2, 11, 23, 49], "unaid": 19, "unalt": 7, "unambigu": 23, "unanim": 12, "unansw": 4, "unassembl": 44, "unassign": [1, 8, 49], "unauthent": 51, "unavail": 1, "unbias": [5, 23], "unblur": 21, "unbound": 7, "unbroken": 50, "unc": 2, "unc3866": 12, "uncap": 7, "uncaught": 40, "uncertainti": [0, 2, 3, 7, 42, 46, 49], "unchang": [0, 2, 4, 6, 7, 8, 11, 23, 39, 40, 42, 47, 49, 55, 57], "unclip": 49, "uncollect": 2, "uncolour": 50, "uncommit": 49, "uncompress": [1, 2, 5, 13, 25, 44], "uncondit": 39, "uncondition": 7, "unconstrain": 6, "unconverg": 4, "unconvert": [15, 44], "uncorrect": [4, 6], "uncut": 6, "undecid": [4, 47, 49], "undeclar": [4, 49], "undeclared_lattice_transl": [2, 49], "undeclared_lattice_translation_pct": 49, "undefin": 2, "undeflect": [1, 2, 23], "under": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 17, 21, 23, 24, 26, 29, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 51, 55, 56, 59, 61, 62, 108], "underflow": 44, "undergo": [0, 37], "underload": [2, 27], "underload_valu": [1, 2, 23, 50, 53], "underneath": [4, 49], "underst": [4, 6, 7], "understood": 23, "undertak": 17, "undetermin": [4, 7, 12, 46, 47, 49, 50], "undilut": 4, "undistort": 6, "undo": [4, 6], "undon": [4, 8], "undul": [5, 42, 50], "unedit": 40, "unencrypt": 51, "unenforc": 17, "unequ": 4, "unesco": 30, "unevenli": 4, "unexplain": [1, 3, 25, 38, 47, 48, 49, 50, 120, 123], "unfilt": 23, "unfit": 7, "unfortun": 22, "unifi": [0, 2, 3, 40], "uniform": [0, 3, 4, 6, 7, 49, 55, 98], "uniformli": [0, 49], "unindex": [6, 23], "uninform": 4, "union": [0, 5, 6, 21], "uniqu": [1, 2, 4, 5, 6, 7, 12, 17, 23, 38, 39, 42, 49, 68, 124], "unique_reflect": 49, "unit": [0, 1, 2, 4, 5, 7, 8, 10, 11, 12, 15, 22, 23, 25, 26, 27, 28, 38, 39, 40, 41, 42, 43, 44, 46, 47, 48, 49, 50, 51, 55, 61, 68, 70, 71, 77, 96, 107, 109, 137], "unit_cel": [1, 2, 23, 27, 68, 101, 137], "unit_cell_const": [46, 49, 50], "unit_cell_dict": 137, "unit_cell_dist_toler": 96, "unit_cell_esd": [1, 23], "unit_cell_from_dict": 137, "unit_cell_inst": 137, "unit_x": 106, "unitcel": [62, 68, 132, 133], "uniti": [7, 42], "univers": [0, 12, 14, 56], "unix": 19, "unknown": [0, 1, 2, 3, 7, 39, 40, 42, 44, 49, 71, 72], "unless": [1, 4, 5, 6, 7, 8, 12, 17, 23, 27, 29, 36, 39, 40, 42, 46, 48, 49, 50, 51, 53, 71, 125, 134], "unlicens": 56, "unlik": [5, 7, 25, 33, 39, 42, 47], "unlimit": 29, "unlist": 6, "unmask": 5, "unmeasur": [1, 2, 4, 6, 23, 25, 49], "unmerg": [1, 2, 4, 6, 7, 38, 39, 40, 42, 45, 48, 49, 50], "unmodel": [3, 8], "unmodifi": [0, 17, 29, 56], "unmov": 4, "unnecessari": [2, 29], "unnorm": 5, "unnormalis": 6, "unobserv": 7, "unpack": [29, 36, 40, 43, 45, 59], "unplac": 4, "unpolar": [5, 42, 50], "unrar": 12, "unreach": 2, "unread": [2, 7, 8, 42, 49], "unrecover": [1, 2, 6, 23, 24, 133], "unrefin": [6, 47], "unrel": [4, 5, 7, 8, 22, 47, 49], "unreli": [6, 7], "unrepair": 6, "unresolv": [12, 49], "unsatur": 49, "unscal": [7, 42, 46], "unscor": [12, 40], "unset": [1, 2, 5, 50, 136], "unshadow": 5, "unsign": [1, 2, 20, 23, 33, 53, 71], "unstabl": [2, 4, 5, 7], "unstat": 108, "unsubscript": 7, "unsum": [15, 46], "untest": [2, 49], "untick": 26, "until": [2, 5, 7, 8, 12, 25, 26, 27, 29, 41, 44, 45, 50, 71, 96, 109, 125], "untilt": [2, 5, 7, 23], "untouch": [4, 6, 7, 11, 42, 46], "untrust": [2, 7, 42, 44, 51, 53], "untrusted_rectangl": 53, "untwin": [0, 4, 8, 12, 40, 46, 49], "unus": [2, 7, 23, 25, 42, 44, 49, 125, 131], "unusable_merg": 49, "unusu": [4, 12, 38], "unweight": [0, 2, 6, 8], "unwrit": 49, "unx": 40, "up": [0, 2, 4, 5, 6, 7, 8, 11, 12, 14, 16, 21, 22, 23, 24, 26, 27, 30, 36, 37, 38, 39, 42, 44, 45, 47, 48, 49, 50, 59, 125], "updat": [0, 2, 3, 7, 8, 9, 17, 19, 25, 26, 29, 37, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "update_monom": [8, 56], "update_vers": 35, "updatecorr": 21, "upgrad": [2, 9, 19, 28, 36], "upload": [2, 5, 12, 21, 25, 26, 33, 37, 47, 60, 62, 71, 129], "upper": [5, 6, 18, 26, 45, 63, 113, 114, 136], "upstream": [2, 7, 56], "uptim": 40, "upward": [4, 7, 11, 49], "uq": [0, 12], "uql": 12, "ure": [12, 38, 40], "uri": [62, 71], "uridin": 12, "url": [2, 6, 26, 36, 38, 42, 51], "ursbi": 34, "urzhumtsev": [0, 3, 8], "us": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 31, 34, 36, 37, 38, 39, 40, 42, 43, 44, 45, 46, 47, 49, 50, 51, 52, 53, 54, 55, 56, 57, 59, 61, 62, 64, 65, 67, 68, 69, 71, 72, 80, 86, 89, 92, 93, 95, 99, 103, 109, 113, 114, 116, 119, 127, 131, 134, 136, 138, 139, 140], "usa": [0, 3], "usabl": [2, 6, 11, 21, 24, 25, 38, 39, 42, 44, 46, 49, 50, 125], "usag": [14, 38, 42, 43, 45, 55, 56, 57], "use_lattice_symmetri": 7, "usefulli": 7, "useless": 49, "user": [0, 2, 3, 4, 6, 7, 8, 9, 13, 14, 19, 21, 25, 26, 27, 29, 36, 39, 40, 46, 48, 49, 50, 51, 52, 53, 56, 60, 61, 62, 68, 71, 103], "user_data": [1, 23, 27, 68], "user_mask": [33, 62, 71, 103], "usernam": 19, "userspac": 62, "usr": [2, 9, 25, 40, 43, 45, 59], "usual": [2, 6, 7, 8, 12, 19, 25, 26, 27, 28, 30, 38, 39, 46, 47, 49, 50, 71, 107], "us\u00f3n": [0, 8], "utc": 2, "utf": [1, 24, 40], "utf8": 40, "util": [0, 2, 3, 57, 93], "uv": 97, "v": [0, 2, 3, 4, 5, 6, 7, 8, 12, 19, 20, 26, 27, 33, 34, 38, 40, 42, 45, 49, 50, 55, 96], "v1": [13, 56], "v100": [2, 26, 36, 43, 45, 59], "v13a": 12, "v163a": 12, "v2": [36, 61], "v3": [2, 36, 40, 45, 61], "v4": 36, "v6": 56, "v612f": 12, "v_": 6, "v_bkg_estim": 1, "v_i": 5, "v_spindle_blind_fract": 1, "vacuum": [1, 2, 7, 23, 42, 46], "vagin": [0, 3, 8, 56], "vaginali": 12, "val1": 68, "val2": 68, "valenc": [0, 8], "valid": [0, 1, 2, 3, 5, 6, 7, 8, 15, 20, 23, 24, 25, 26, 27, 29, 38, 41, 42, 44, 45, 46, 47, 48, 50, 53, 54, 68, 71, 101, 122, 124, 125], "valid_foreground_threshold": 7, "vallei": [6, 30], "valu": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 15, 16, 19, 20, 21, 23, 24, 26, 27, 33, 38, 40, 41, 42, 44, 46, 47, 49, 50, 51, 53, 62, 68, 71, 76, 78, 80, 81, 83, 84, 86, 88, 89, 91, 92, 94, 95, 96, 98, 99, 101, 105, 109, 111, 119, 121, 122, 127, 130, 134], "van": [0, 8], "vanad": 12, "var": 7, "var_bkg": 1, "varadi": 0, "varepsilon": [4, 7, 8], "vari": [4, 5, 7, 8, 44, 46, 50], "variabl": [0, 3, 4, 19, 23, 26, 42, 51], "varianc": [0, 2, 3, 4, 5, 6, 7, 8, 21, 42, 44, 46, 49], "variant": [1, 5, 6, 12, 14, 17, 18, 20, 22, 23, 26, 27, 28, 36, 43, 46, 59], "variat": 50, "variou": 18, "varphi_": 4, "vd": [1, 2, 23], "vec": 42, "vector": [0, 1, 2, 4, 5, 7, 8, 21, 23, 44, 46, 49, 77, 119, 132], "vectoris": [6, 36, 40], "velankar": 0, "veltkamp": 0, "vendor": [0, 21, 22, 52], "venom": 12, "ventura": [26, 36, 43, 45, 59], "verb": 40, "verbatim": [12, 17, 23, 29, 36, 45, 52, 56], "verbos": [2, 27, 42, 99], "verdict": [2, 4, 7, 25, 38, 46, 47, 49, 125, 131], "verdict_text": [2, 49, 125], "veri": [2, 4, 6, 7, 12, 15, 24, 25, 27, 30, 37, 38, 42, 43, 44, 47, 49, 50, 96, 134], "verif": 2, "verifi": [0, 26, 36, 37, 43, 55, 59], "vermot": 12, "verrucaria": 12, "version": [0, 1, 2, 5, 9, 10, 14, 19, 24, 25, 26, 28, 29, 36, 37, 38, 39, 40, 43, 45, 47, 49, 52, 53, 54, 56, 59, 61, 62, 65, 71, 82, 91, 108], "version_get": 62, "versu": [2, 7, 39, 40, 50], "vertic": [1, 2, 5, 15, 42, 68, 90], "vertical_scan": [1, 23], "veto": [2, 4, 6, 47, 49], "vfd": 2, "vgrg1": 12, "vi": 12, "via": [0, 2, 3, 5, 6, 9, 10, 12, 14, 16, 18, 19, 20, 23, 24, 25, 26, 27, 36, 51, 62, 71, 140], "viabl": [2, 5, 23, 80, 96, 133], "viable_cell_min_spot": 96, "vibrat": 0, "vibrio": 12, "view": [2, 11, 23, 29, 59, 60], "viewabl": 17, "viewer": [0, 2, 5, 6, 23, 24, 26, 28, 36, 37, 51, 52, 54, 55, 56], "vintag": 44, "violat": [2, 4, 7, 29], "virginia": 0, "viridi": 0, "virtual": [0, 1, 2, 23, 44, 50, 53, 86], "virtual_pixel_interpolation_appli": 23, "virtual_pixel_interpolation_en": 1, "viru": [8, 12, 40, 45], "visibl": [2, 4, 5, 6, 9, 29, 41, 49, 50], "visibli": [17, 107], "visual": [0, 2, 26, 36, 52], "visualis": 2, "viti": 14, "vitis_hl": 14, "vivado": [0, 2, 9, 36], "vlan": 51, "vm": [40, 49], "vm_flag": 2, "vm_flags_set": 19, "vmhwm": 40, "vnc": 26, "vocabulari": [0, 2, 23, 44, 46], "voic": 12, "void": [29, 71], "vol": [0, 3, 23], "volatil": 71, "volta": [2, 5, 36], "voltag": [71, 82], "volum": [0, 1, 2, 4, 5, 6, 7, 8, 29, 30, 40, 42, 49, 120], "volume_a3": [49, 120], "vonrhein": [0, 3, 53], "vote": [41, 55, 110], "vouch": 4, "vqqihq": 12, "vriez": 13, "vt00022": 12, "vulgari": 12, "vulnificu": 12, "vv": 9, "w": [0, 2, 3, 5, 6, 7, 8, 12, 14, 17, 20, 27, 29, 34, 49], "w01b": 12, "w1_3": 12, "w1_4": 12, "w431": 0, "w437": 0, "w_": 8, "w_0": 8, "w_b": 8, "w_i": 6, "w_j": 7, "wa": [0, 1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 13, 15, 23, 24, 25, 26, 27, 29, 31, 33, 34, 36, 38, 39, 40, 41, 42, 44, 45, 46, 47, 48, 49, 50, 60, 71, 91, 107, 109, 121, 122, 123, 125, 129, 134], "waal": 8, "wagner": 12, "wai": [1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 13, 15, 17, 19, 23, 24, 25, 27, 29, 30, 36, 38, 39, 40, 42, 44, 45, 46, 47, 48, 49, 50, 55, 56, 71, 75, 77], "wait": [0, 2, 4, 6, 21, 24, 25, 27, 40, 45, 62, 68, 71, 81], "wait_till_don": [2, 25, 62, 71], "wait_till_done_post": 62, "wait_until_run": [2, 24, 62, 71], "wait_until_running_post": 62, "waiv": 29, "waiver": 29, "wakonig": 15, "walk": [4, 5, 6, 7, 21, 40, 47, 48, 64], "walker": [0, 3], "walko": 0, "wall": [2, 38, 40, 50, 55, 123], "wall_": 40, "wall_tim": [2, 40, 49], "waller": [4, 7, 49, 50], "wander": 5, "wang": [0, 3, 34, 38], "want": [1, 2, 4, 6, 7, 9, 22, 27, 29, 36, 38, 40, 43, 45, 46, 47, 50], "ward": 12, "warm": 40, "warmer": 2, "warn": [2, 4, 5, 6, 7, 9, 21, 25, 26, 38, 39, 42, 44, 45, 46, 47, 49, 50, 65, 71, 125, 131], "warning_count": 49, "warp": [5, 8, 21], "warranti": [17, 22, 29], "warsaw": 0, "wast": 42, "watch": 40, "water": [0, 1, 2, 4, 8, 24, 25, 38, 39, 40, 42, 47, 49, 123, 128], "waterman": 0, "watermark": [2, 24, 27, 140], "waters_ad": [25, 123], "waters_remov": [25, 123], "wave": 7, "wavelength": [0, 1, 2, 4, 6, 7, 8, 11, 12, 13, 38, 39, 42, 44, 46, 48, 49, 50, 97, 109], "wavevector": 5, "wax": 15, "wddm": 40, "we": [0, 2, 9, 18, 22, 23, 29, 31, 37, 52, 53, 55, 58], "weak": [0, 2, 4, 5, 6, 7, 8, 39, 42, 46, 47, 49, 50], "weak_diffract": [23, 49], "weaken": [7, 50], "weaker": [4, 5, 6, 7, 50], "weakest": [4, 6, 39, 46, 49], "weakli": [2, 6, 17, 50], "web": [0, 2, 5, 25, 28, 37, 51, 56, 61, 71, 99], "webpag": [14, 17], "websit": [10, 14], "wedg": [0, 1, 2, 3, 6, 7, 12, 119, 136], "wei": 0, "weigh": [0, 4, 6, 7, 39, 47, 48, 49], "weight": [0, 2, 3, 4, 5, 6, 7, 11, 15, 20, 21, 23, 25, 38, 39, 40, 42, 46, 47, 48, 49, 50, 55, 121, 123, 125], "weinert": 34, "weiss": [0, 3, 49], "weissig": 0, "welcom": [17, 29], "well": [2, 4, 5, 6, 7, 8, 11, 12, 15, 19, 21, 22, 23, 24, 25, 29, 35, 36, 38, 39, 40, 42, 46, 47, 48, 49, 50, 59, 60, 63, 71], "welterb": 30, "went": [6, 8, 23, 49], "were": [0, 1, 2, 4, 5, 6, 7, 8, 12, 13, 15, 23, 24, 25, 29, 36, 37, 39, 40, 42, 44, 46, 47, 48, 49, 50, 71, 101, 109, 110, 123, 124], "westbrook": 0, "what": [0, 1, 2, 3, 4, 5, 6, 9, 12, 13, 15, 21, 23, 25, 26, 29, 36, 37, 38, 39, 42, 43, 44, 45, 46, 47, 50, 53, 55, 57, 59, 61, 71, 107, 108, 109, 120, 121, 122, 125, 126, 128], "whatev": [1, 2, 4, 5, 6, 7, 8, 9, 21, 23, 26, 27, 29, 39, 40, 41, 42, 45, 47, 49, 77, 96], "wheel": [2, 26], "when": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 18, 19, 21, 22, 23, 24, 25, 26, 28, 29, 36, 38, 39, 40, 41, 42, 45, 46, 47, 48, 49, 50, 53, 55, 57, 59, 60, 62, 68, 71, 107, 108, 109, 110, 125, 134, 136], "whenev": [4, 7, 11, 23, 39, 40, 41, 42, 44, 46, 49, 50, 53, 108, 109], "where": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 14, 15, 17, 21, 23, 25, 27, 29, 30, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 53, 55, 56, 65, 68, 71, 75, 77, 92, 108, 109, 110, 120, 122, 123, 124, 125, 127, 128, 131], "wherea": [2, 4, 7, 23], "wherev": [3, 4, 6, 7, 8, 40, 42, 47, 49, 50], "whether": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 17, 21, 23, 24, 25, 26, 27, 29, 37, 38, 39, 40, 41, 42, 46, 47, 49, 50, 62, 109], "which": [0, 1, 2, 3, 5, 6, 7, 8, 10, 11, 12, 13, 14, 15, 17, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 55, 56, 57, 59, 61, 68, 71, 72, 75, 77, 90, 96, 109, 119, 125, 129, 133, 134, 139], "whichev": [4, 5, 6, 7, 8, 21, 38, 39, 42, 46, 47, 49, 50, 89], "while": [2, 4, 5, 6, 7, 8, 11, 12, 15, 17, 19, 21, 23, 24, 25, 26, 28, 30, 31, 38, 40, 42, 47, 49, 50, 51, 62, 68, 71, 101, 128, 129, 136], "white": [0, 2, 3, 12, 49, 50], "whitespac": 50, "whittak": [0, 3, 7], "who": [4, 12, 17, 29, 40, 49, 51], "whoever": 51, "whole": [0, 1, 2, 4, 5, 6, 7, 8, 13, 17, 21, 23, 25, 26, 27, 29, 30, 36, 38, 39, 40, 41, 42, 44, 46, 47, 49, 50, 53, 58, 68, 71, 124, 125, 127], "wholli": [5, 49], "whom": [0, 29], "whose": [0, 2, 3, 4, 5, 6, 7, 8, 11, 13, 21, 23, 25, 27, 29, 30, 39, 40, 41, 42, 44, 46, 47, 48, 49, 50, 55, 134], "why": [0, 4, 5, 6, 12, 25, 29, 33, 36, 38, 39, 40, 47, 49, 50, 55, 122, 123, 125], "wide": [0, 2, 4, 5, 6, 7, 23, 29, 41, 42, 48, 50], "widen": [0, 2, 4, 5, 6, 7, 8, 12, 21, 26, 42, 45, 47], "wider": [2, 4, 5, 6, 7, 8, 21, 23, 38, 42, 48, 50, 62], "widest": [6, 7, 8, 21], "widget": 2, "width": [0, 1, 2, 5, 6, 9, 11, 12, 15, 23, 33, 39, 40, 42, 45, 49, 50, 63, 68, 74, 88, 98, 134], "wiedorn": 13, "wiggler": [5, 42], "wild": [12, 46], "wildli": 7, "willing": 5, "wilson": [0, 2, 3, 4, 8, 21, 38, 40, 42, 46, 47, 48, 49, 50], "wilson_b": [2, 7, 49], "wilsonoutliersgpu": 21, "win": [2, 4, 5, 6, 26, 39, 40, 45, 47], "win64": [2, 36, 43, 45, 59], "windeployqt": [26, 36], "window": [2, 4, 5, 6, 7, 9, 21, 23, 29, 38, 42, 43, 45, 50, 52, 55, 59, 61], "wing": 7, "wingetopt": 56, "winn": [0, 3, 8], "winner": [4, 6, 21, 49], "winter": [0, 3], "wip": 2, "wipo": 29, "wire": [1, 23, 51], "wise": 2, "wish": 29, "wit": 4, "withdraw": 47, "within": [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 15, 17, 21, 24, 27, 29, 39, 40, 42, 46, 47, 49, 50, 51, 68, 71, 101, 120, 133], "without": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 17, 18, 21, 22, 23, 25, 26, 27, 28, 29, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 57, 58, 59, 61, 62, 90, 108, 110, 123, 125, 131, 134], "wojdyla": [0, 34], "wojdyr": [0, 3, 8], "wolff": 13, "womack": 0, "won": [18, 19, 24, 27, 65], "woolfson": [0, 4, 49], "word": [0, 2, 25, 30, 42, 44, 49, 68, 75, 77, 109, 131], "work": [0, 2, 3, 5, 6, 7, 8, 9, 12, 13, 14, 15, 17, 20, 21, 22, 23, 25, 26, 29, 34, 36, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 55, 61, 62, 109, 122, 123, 134], "workdir": [40, 55], "worker": [2, 38, 42, 45, 50], "workflow": [2, 4, 5, 7, 15, 24, 25, 36, 39, 42, 50, 55, 63, 64, 96, 134], "workload": 26, "workshop": [0, 3], "workstat": 40, "world": [0, 30], "worldwid": [17, 29], "wors": [4, 5, 6, 7, 8, 38, 42, 49, 107], "worst": [1, 4, 6, 7, 8, 23, 41, 42, 47, 49, 133], "worst_fit": [47, 49], "worth": [2, 5, 6, 7, 11, 40, 41, 42, 43, 46, 49, 50], "would": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 21, 22, 23, 24, 25, 26, 27, 29, 35, 39, 40, 41, 42, 44, 45, 46, 47, 49, 50, 68, 87, 108], "wrap": [21, 113], "wrapper": 40, "wright": [0, 3, 5, 21], "write": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 15, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 34, 36, 38, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 53, 55, 56, 57, 68, 71, 91, 108, 109, 140], "write_imag": 1, "write_master_fil": [1, 24], "write_nxmx_hdf5_mast": 68, "writer": [1, 2, 5, 11, 20, 23, 25, 27, 28, 36, 37, 44, 51, 56, 57, 61, 62, 68, 71, 93, 101, 128, 136, 140], "writer_fifo_util": 93, "writer_notification_socket": [24, 25, 27, 140], "writer_notification_zmq_addr": [1, 24], "written": [0, 1, 2, 4, 5, 6, 7, 8, 11, 12, 13, 14, 16, 21, 23, 24, 25, 26, 27, 29, 30, 38, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 55, 57, 59, 60, 68, 71, 86, 90, 93, 101, 125, 128, 134], "wrobel": 0, "wrong": [0, 2, 4, 5, 6, 7, 11, 12, 19, 23, 25, 38, 40, 41, 44, 46, 47, 49, 50, 51, 55, 103, 109, 110], "wrong_gain": 103, "wrongdaqst": 71, "wrongli": [2, 8, 23, 40, 53], "wrote": [2, 4, 5, 6, 23, 24, 39, 40, 42, 44, 47, 49], "wsl2": 2, "wssr": 21, "wu": [0, 3], "ww": 12, "wwp": 12, "wwpdb": 56, "www": 29, "x": [0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 12, 13, 15, 21, 22, 23, 25, 26, 27, 28, 33, 34, 36, 37, 38, 40, 41, 42, 44, 45, 46, 47, 49, 50, 51, 55, 61, 62, 68, 70, 71, 75, 77, 90, 97, 104, 106, 107, 109, 110, 114, 116, 120, 132, 133, 135], "x0": [1, 25, 42, 44, 68, 75, 77], "x06da": 12, "x06sa": [12, 23, 25], "x0_plane": [25, 44, 77], "x10sa": 22, "x11": 26, "x13": 12, "x16": [14, 22], "x220852": 12, "x25": 12, "x250591": 12, "x29a": 12, "x64": 26, "x8": [9, 14, 22, 88], "x86": [2, 36, 38, 40, 43, 45, 52, 59], "x86_64": [2, 9, 36, 38, 43, 45, 53], "x_": [5, 6, 8], "x_f": 7, "x_master": 42, "x_p": 7, "x_pixel_s": 23, "x_pixels_in_detector": 23, "x_weighted_sum": 1, "xaloc": 12, "xbflash": [9, 28, 56], "xbsq": 12, "xcode": [26, 36, 45], "xd": [0, 1, 2, 3, 4, 5, 6, 7, 11, 12, 23, 28, 36, 37, 38, 39, 40, 41, 42, 49, 50, 55, 57], "xdet": 46, "xdgdesktopport": 26, "xds_ascii": [0, 55], "xds_durin": 55, "xds_neggia": 55, "xdscc12": [0, 3], "xeon": 22, "xfel": [0, 2, 5, 7, 12, 34, 38, 42, 48, 50, 54, 55, 62, 68, 71, 97, 133], "xfel2042": 13, "xfel_event_cod": 1, "xfel_event_code_get": 62, "xfel_pulse_id": 1, "xfel_pulse_id_get": 62, "xfel_pulseid": 133, "xia2": [2, 12, 53, 55], "xilinx": [9, 20, 22, 56], "xmax": 1, "xmin": 1, "xn": [1, 23, 44, 76, 77], "xor": 12, "xp": [1, 23, 25, 44, 76, 77], "xpra": 26, "xput": 33, "xrai": 46, "xray_data": 46, "xray_fluorescence_spectrum": 68, "xrd": 12, "xrda": [0, 12], "xrf": 23, "xscale": [0, 7, 42, 49], "xtal": [0, 40, 46, 50], "xtal_1_00042": 44, "xtallographi": 0, "xtaloptim": 2, "xtc": [2, 5, 13, 23, 38, 42, 44, 50], "xtc_more": 13, "xtriag": [0, 3, 4, 7, 46, 49], "xu": 56, "xylanisolven": 12, "xyz": [49, 68], "xyzin": 46, "xyzout": 46, "xzf": [9, 36, 38, 43, 45, 59], "y": [0, 1, 2, 3, 5, 7, 8, 9, 11, 15, 23, 25, 26, 27, 38, 41, 42, 44, 46, 49, 71, 72, 75, 77, 90, 104, 106, 107, 109, 110, 114, 116, 120, 132, 133, 135], "y0": [1, 25, 42, 44, 68, 75, 77], "y0_plane": [25, 44, 77], "y137a": 12, "y_": [5, 6], "y_f": 7, "y_p": 7, "y_pixel_s": 23, "y_pixels_in_detector": 23, "y_weighted_sum": 1, "yamamoto": 0, "yamashita": 0, "yaml": [23, 25, 29, 35, 44, 49], "yann": 56, "ydet": 46, "ye": [47, 53], "year": [0, 17, 29], "yeat": [0, 3, 4, 8, 46, 49], "yeo": 0, "yersinia": 12, "yet": [1, 2, 3, 5, 6, 7, 12, 21, 40, 42, 47, 71], "yield": [2, 5, 6, 7], "yl": 12, "ymax": 1, "ymin": 1, "yml": [36, 55], "yn": [1, 23, 25, 44, 75, 76, 77], "yoke": 30, "yokh": 30, "yokochi": 0, "yoon": 0, "you": [0, 2, 3, 9, 12, 13, 17, 19, 25, 27, 28, 29, 30, 31, 34, 36, 38, 40, 45, 46, 47, 50, 53, 56, 62], "young": 30, "your": [17, 26, 37, 38, 40, 43, 45, 46, 47, 50, 62, 71], "yourself": [29, 36, 40, 50], "yp": [1, 23, 25, 44, 75, 76, 77], "yscv": 12, "yscx": 12, "yscy": 12, "ytterbium": 12, "yuji": 56, "yung": 30, "yyyymmdd": 40, "yzsx": 12, "z": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 34, 38, 42, 46, 47, 49, 50, 71, 104, 120, 122, 132], "z4439011584": 12, "z5198562500": 12, "z_": 5, "z_g": 7, "z_h": 7, "zampieri": 12, "zanuda": [0, 12], "zcfy": 12, "zdenek": 27, "zeldin": 0, "zen": [36, 43], "zenodo": [0, 12, 38, 40, 45], "zero": [0, 1, 2, 4, 5, 6, 7, 8, 12, 15, 16, 20, 23, 26, 33, 36, 38, 40, 41, 42, 43, 44, 45, 46, 49, 55, 67, 68, 108, 109, 133, 134, 139], "zero_fract": [8, 49], "zeromq": [1, 2, 9, 23, 25, 26, 27, 28, 38, 51, 56, 57, 58, 62, 68, 71, 93, 94, 99, 101, 138, 139, 140], "zeromq_metadata": [24, 25, 62, 71, 99, 100], "zeromq_metadata_set": [71, 138], "zeromq_metadata_settings_dict": 138, "zeromq_metadata_settings_from_dict": 138, "zeromq_metadata_settings_inst": 138, "zeromq_preview": [25, 62, 71, 99, 100], "zeromq_preview_set": [71, 139], "zeromq_preview_settings_dict": 139, "zeromq_preview_settings_from_dict": 139, "zeromq_preview_settings_inst": 139, "zeromq_set": [24, 140], "zeromq_settings_dict": 140, "zeromq_settings_from_dict": 140, "zeromq_settings_inst": 140, "zeromqmetadataset": [62, 71, 99, 100], "zeromqpreviewset": [62, 71, 99, 100], "zeromqset": [62, 99], "zerr": [38, 46, 49, 50], "zeta": [1, 4, 5, 7, 21, 23, 42, 46], "zeta_": 7, "zeta_i": 7, "zhang": 0, "zheng": [0, 8], "zimmerman": 0, "zinc": 12, "zinger": [4, 5, 7, 42], "zip": [2, 12, 36, 43, 45, 52], "zlib": [2, 26, 52, 56], "zmq_file_port": 27, "zmq_repub_port": 27, "zn": [8, 47], "zonal": [2, 4], "zone": [0, 2, 3, 4, 7, 8, 12, 42, 49], "zoom": [2, 26], "zstandard": [1, 52, 56, 57], "zstd": [2, 5, 23, 44, 56], "zwart": [0, 7], "\u00b2": [23, 40, 46, 49], "\u00b5m": [13, 42], "\u00b9": [0, 5, 6, 23, 25, 28, 34, 41, 42], "\u00bd": [46, 49], "\u00e5": [0, 3, 4, 5, 6, 7, 8, 12, 13, 21, 23, 25, 40, 41, 42, 45, 46, 48, 49, 50], "\u00e5ngstr\u00f6m": [4, 7, 12], "\u00e5\u00b2": [4, 7, 8, 23, 46, 49, 50], "\u00e5\u00b3": [8, 46], "\u00f1": 30, "\u03b1": [0, 12, 23, 42, 49], "\u03b2": [12, 23, 49], "\u03b3": [12, 23, 49], "\u03b3\u2080": 23, "\u03b3\u2080\u00b2": 23, "\u03b3\u2091": 23, "\u03b4": [46, 49], "\u03b4cc": 50, "\u03b4cc1": [4, 7, 49], "\u03b4\u03c6": 23, "\u03b5": 49, "\u03b6": [3, 23, 42], "\u03b8": 49, "\u03bb": [12, 23, 42], "\u03c3": [0, 3, 4, 5, 8, 21, 23, 25, 38, 39, 42, 46, 49, 50], "\u03c3_bw": 23, "\u03c3_m": [42, 49], "\u03c3a": [23, 48], "\u03c3b": 23, "\u03c3c": 23, "\u03c3\u00b2": [23, 40, 46, 49], "\u03c3\u03b1": 23, "\u03c3\u03b2": 23, "\u03c3\u03b3": 23, "\u03c3\u2080\u00b2": [46, 49], "\u03c4": [7, 49], "\u03c6": [8, 12, 15, 44, 46], "\u03c6_bin": 23, "\u03c7": [12, 44], "\u03c8": 8, "\u03c9": [12, 44], "\u1d40": [46, 49], "\u2086": 8}, "titles": ["Acknowledgements", "CBOR messages", "Changelog", "CPU-side crystallographic data analysis (Jungfraujoch)", "Data analysis: space group and validation (\u00a713\u2013\u00a714)", "Data analysis: from images to spots (\u00a70\u2013\u00a73)", "Data analysis: indexing and geometry (\u00a74\u2013\u00a77)", "Data analysis: integration, scaling and merging (\u00a78\u2013\u00a712)", "Data analysis: refinement of a placed model (\u00a715)", "Deployment", "Supported detectors", "Detector geometry", "External test data", "External test data: serial crystallography (XFEL stills)", "FPGA smartNIC", "FPGA data analysis", "FPGA data flow", "FPGA license", "FPGA network", "FPGA PCIe driver", "FPGA advanced reference", "GPU data analysis", "Hardware requirements", "HDF5 / NeXus data format", "Data streams", "jfjoch_broker", "jfjoch_viewer", "jfjoch_writer", "Jungfraujoch: data acquisition", "License", "Naming", "OpenAPI", "OpenAPI specification", "Pixel mask", "Publications", "OpenAPI Python client", "Release contents", "Linux package repositories", "Rugnux", "Advanced Rugnux", "Measuring Rugnux: validation and timing", "Detector calibration from powder rings (rugnux --mode calibration)", "Command-line options", "Download Rugnux", "Input formats", "Installing Rugnux", "Rugnux with other programs", "Models and reference data", "Overview", "The results report", "Running Rugnux", "Security", "Software requirements", "Integration with MX data processing software", "Technical reference", "Tests", "Third-party software notices", "Tools", "Semantic versioning", "Download the Jungfraujoch Viewer", "Web frontend", "Documentation", "jfjoch-client", "AzimIntSettings", "BraggIntegrationSettings", "BrokerStatus", "CalibrationStatisticsInner", "DarkMaskSettings", "DatasetSettings", "DatasetSettingsSmargon", "DatasetSettingsXrayFluorescenceSpectrum", "jfjoch_client.DefaultApi", "Detector", "DetectorList", "DetectorListElement", "DetectorModule", "DetectorModuleDirection", "DetectorModulePlacement", "DetectorPowerState", "DetectorSelection", "DetectorSettings", "DetectorState", "DetectorStatus", "DetectorTiming", "DetectorType", "ErrorMessage", "FileWriterFormat", "FileWriterSettings", "FpgaStatusInner", "GeomRefinementAlgorithm", "GridScan", "ImageBufferStatus", "ImageFormatSettings", "ImagePusherStatus", "ImagePusherType", "IndexingAlgorithm", "IndexingSettings", "InstrumentMetadata", "IntegrationModel", "JfjochSettings", "JfjochStatistics", "MeasurementStatistics", "PcieDevicesInner", "PixelMaskStatistics", "Plot", "PlotUnitX", "Plots", "PowderCalibrationFitSigma", "PowderCalibrationOutput", "PowderCalibrationQuality", "PowderCalibrationSpotCheck", "QBinning", "RoiAzimList", "RoiAzimuthal", "RoiBox", "RoiBoxList", "RoiCircle", "RoiCircleList", "RoiDefinitions", "RotationAxis", "RugnuxLiveBlob", "RugnuxLiveFrameRange", "RugnuxLiveModel", "RugnuxLiveRefinement", "RugnuxLiveShell", "RugnuxLiveStatus", "RugnuxLiveStep", "RugnuxLiveStills", "RugnuxSettings", "RugnuxStatus", "RugnuxSummaryRow", "RugnuxTriageItem", "ScanResult", "ScanResultImagesInner", "SpotFindingSettings", "StandardDetectorGeometry", "TcpSettings", "UnitCell", "ZeromqMetadataSettings", "ZeromqPreviewSettings", "ZeromqSettings"], "titleterms": {"": [7, 27, 49], "0": [2, 5, 11], "1": [2, 4, 5, 6, 7, 8, 23, 51], "10": [4, 7, 8, 23], "100": 2, "101": 2, "102": 2, "103": 2, "104": 2, "105": 2, "106": 2, "107": 2, "108": 2, "109": 2, "11": [7, 8, 23], "110": 2, "111": 2, "112": 2, "113": 2, "114": 2, "115": 2, "116": 2, "117": 2, "118": 2, "119": 2, "12": [7, 8], "120": 2, "121": 2, "122": 2, "123": 2, "124": 2, "125": 2, "126": 2, "127": 2, "128": 2, "129": 2, "13": [4, 8], "130": 2, "131": 2, "132": 2, "133": 2, "134": 2, "135": 2, "136": 2, "137": 2, "138": 2, "139": 2, "14": 4, "140": 2, "141": 2, "142": 2, "143": 2, "144": 2, "145": 2, "146": 2, "147": 2, "148": 2, "149": 2, "15": 8, "150": 2, "151": 2, "152": 2, "153": 2, "154": 2, "155": 2, "156": 2, "157": 2, "158": 2, "159": 2, "160": 2, "161": 2, "162": 2, "163": 2, "164": 2, "165": 2, "166": 2, "167": 2, "168": 2, "169": 2, "170": 2, "171": 2, "172": 2, "173": 2, "174": 2, "175": 2, "176": 2, "177": 2, "178": 2, "179": 2, "180": 2, "181": 2, "182": 2, "183": 2, "184": 2, "185": 2, "186": 2, "2": [4, 5, 6, 7, 8, 17, 23, 49, 51], "24": 2, "25": 2, "26": 2, "27": 2, "28": 2, "29": 2, "2d": 7, "2theta": 11, "3": [4, 5, 6, 7, 8, 23, 51], "30": 2, "31": 2, "32": 2, "33": 2, "34": 2, "35": 2, "36": 2, "37": 2, "38": 2, "39": 2, "3d": 7, "4": [4, 5, 6, 7, 8, 23], "40": 2, "41": 2, "42": 2, "43": 2, "44": 2, "45": 2, "46": 2, "47": 2, "48": 2, "49": 2, "5": [4, 5, 6, 7, 8, 19, 23], "50": 2, "51": 2, "52": 2, "53": 2, "54": 2, "55": 2, "56": 2, "57": 2, "58": 2, "59": 2, "6": [4, 5, 6, 7, 8, 23], "60": 2, "61": 2, "62": 2, "63": 2, "64": 2, "65": 2, "66": 2, "67": 2, "68": 2, "69": 2, "6oww": 12, "7": [4, 5, 6, 7, 8, 23], "70": 2, "71": 2, "72": 2, "73": 2, "74": 2, "75": 2, "76": 2, "77": 2, "78": 2, "79": 2, "8": [4, 7, 8, 23], "80": 2, "81": 2, "82": 2, "83": 2, "84": 2, "85": 2, "86": 2, "87": 2, "88": 2, "89": 2, "8xbp": 12, "9": [4, 7, 8, 19, 23], "90": 2, "91": 2, "92": 2, "93": 2, "94": 2, "95": 2, "96": 2, "97": 2, "98": 2, "99": 2, "9rci": 12, "A": [11, 26, 40, 45, 47, 50], "AND": 29, "For": 62, "In": 47, "NOT": 51, "No": 27, "Not": 8, "On": [4, 5, 6, 7, 8, 23, 38, 39, 40, 42, 45, 46, 47, 49, 50], "The": [4, 5, 6, 7, 8, 12, 13, 25, 38, 39, 40, 46, 47, 49, 55], "These": 29, "With": 38, "_module_plac": 44, "_process": 23, "ab": 40, "abab": 40, "about": [11, 12], "absenc": 7, "access": [19, 51], "accumul": 21, "ack": 24, "acknowledg": [0, 27], "acquisit": [23, 28], "adapt": 5, "adopt": 0, "adu": 15, "advanc": [20, 39], "advic": 49, "after": [40, 43, 59], "against": [4, 39, 47], "ai": 0, "align": [4, 6], "all": [12, 42, 61], "ambigu": [4, 7, 39, 47], "among": 26, "amplitud": 7, "an": [12, 26], "analysi": [3, 4, 5, 6, 7, 8, 9, 15, 21, 25, 26, 38, 54, 55, 57], "anisotropi": [0, 4, 49], "anomal": [4, 49, 55], "answer": 49, "api": 62, "appl": 21, "appli": [5, 12, 29], "ar": [12, 39, 53], "arbit": 55, "archiv": [12, 45], "arm": [11, 40], "arrai": 1, "artefact": 36, "attenu": 23, "attribut": 56, "audit": 8, "authent": 51, "author": [62, 71], "automat": 4, "auxiliari": 7, "axi": [11, 20], "azimintset": 63, "azimuth": [5, 15, 23, 42], "azint": [23, 42], "b": [7, 8], "back": 40, "background": 5, "bandwidth": 7, "base": [4, 37], "basic": 5, "batteri": [12, 13, 40], "beam": [5, 23, 42], "beam_center_i": 23, "beam_center_x": 23, "bearer": 51, "bearerauth": 62, "benchmark": [40, 57], "besid": 49, "best": 6, "beyond": 23, "bia": 47, "binari": 56, "bit_depth_readout": 23, "blind": 6, "blob": 8, "bodi": 4, "box": 7, "bragg": [5, 7], "braggintegrationset": 64, "bravai": 6, "bring": [6, 47], "broker": 25, "brokerstatu": 65, "bu": 26, "budget": 6, "buffer": 19, "build": [14, 19, 26, 36, 40, 45, 56], "bulk": [4, 8], "c": 56, "cach": 40, "calcul": 15, "calibr": [1, 5, 41, 42], "calibrationstatisticsinn": 66, "can": 51, "cancel": 27, "cancel_post": 71, "candid": 6, "cannot": [4, 6], "card": [9, 21, 57], "cbf": 27, "cbor": 1, "cc": 49, "ccl": 5, "cell": [0, 6, 38, 45, 49], "center": [6, 7], "centr": [5, 11, 42], "cern": 17, "chang": 55, "changelog": 2, "charact": 19, "check": [4, 40], "checklist": 51, "choos": 7, "ci": 40, "cif": 39, "cite": [28, 34, 38], "clarif": 62, "client": [9, 31, 35, 62], "cmake": 19, "code": [9, 12], "collect": [12, 23, 25, 49], "column": [12, 49], "combin": 7, "come": [4, 12, 13], "command": [39, 42], "common": 6, "compar": [40, 46, 49], "compil": [14, 19, 25], "complementari": 23, "compon": [5, 56], "compress": [1, 15], "comput": 0, "condit": [29, 40], "cone": 6, "config_azim_int_get": 71, "config_azim_int_put": 71, "config_bragg_integration_get": 71, "config_bragg_integration_put": 71, "config_dark_mask_get": 71, "config_dark_mask_put": 71, "config_detector_get": 71, "config_detector_put": 71, "config_file_writer_get": 71, "config_file_writer_put": 71, "config_image_format_conversion_post": 71, "config_image_format_get": 71, "config_image_format_put": 71, "config_image_format_raw_post": 71, "config_indexing_get": 71, "config_indexing_put": 71, "config_instrument_get": 71, "config_instrument_put": 71, "config_internal_generator_image_put": 71, "config_internal_generator_image_tiff_put": 71, "config_mask_get": 71, "config_mask_tiff_get": 71, "config_roi_get": 71, "config_roi_put": 71, "config_rugnux_get": 71, "config_rugnux_model_delet": 71, "config_rugnux_model_put": 71, "config_rugnux_put": 71, "config_select_detector_get": 71, "config_select_detector_put": 71, "config_spot_finding_get": 71, "config_spot_finding_put": 71, "config_user_mask_get": 71, "config_user_mask_put": 71, "config_user_mask_tiff_get": 71, "config_user_mask_tiff_put": 71, "config_zeromq_metadata_get": 71, "config_zeromq_metadata_put": 71, "config_zeromq_preview_get": 71, "config_zeromq_preview_put": 71, "configur": [9, 18, 24, 25], "conflict": 27, "connect": 5, "contamin": 49, "content": [23, 36], "convent": [5, 11, 46], "convers": 15, "coordin": [5, 11], "copi": 24, "copyleft": 56, "correct": [0, 5, 7], "cost": 40, "cpu": [3, 8, 36, 40], "crystal": [7, 49], "crystallograph": [0, 3], "crystallographi": [11, 13], "crystfel": [38, 53], "cuda": 36, "custom": 33, "cutoff": [4, 7], "cxi": 23, "d": [26, 49], "darkmaskset": 67, "data": [0, 1, 3, 4, 5, 6, 7, 8, 12, 13, 15, 16, 21, 23, 24, 26, 28, 38, 39, 42, 46, 47, 49, 50, 53, 54, 56, 57], "dataset": [6, 7, 12, 13, 51], "datasetset": 68, "datasetsettingssmargon": 69, "datasetsettingsxrayfluorescencespectrum": 70, "deactivate_post": 71, "decid": [8, 49], "decis": [4, 6, 47], "declar": [0, 7], "decod": 5, "dectri": 10, "default": [7, 42], "defaultapi": 71, "defect": 5, "defens": 12, "definit": 23, "densiti": [0, 4, 8], "depend": [52, 56], "deploy": [9, 51], "deposit": 12, "depth": 23, "deriv": 23, "descript": 12, "detail": [50, 71], "detect": [5, 7], "detector": [6, 10, 11, 12, 23, 41, 42, 72], "detector_status_get": 71, "detectorlist": 73, "detectorlistel": 74, "detectormodul": 75, "detectormoduledirect": 76, "detectormoduleplac": 77, "detectorpowerst": 78, "detectorselect": 79, "detectorset": 80, "detectorst": 81, "detectorstatu": 82, "detectortim": 83, "detectortyp": 84, "determin": 4, "develop": [49, 54], "devic": [5, 19], "diagnost": 23, "dial": 53, "dictionari": 8, "differ": [4, 49], "diffract": [0, 4, 26, 49], "direct": [6, 11], "direct_beam_i": 23, "direct_beam_x": 23, "directli": 56, "directori": [27, 40], "disagre": 12, "displai": 26, "disposit": 49, "distanc": 5, "dkm": 19, "do": 40, "document": [61, 62], "doe": [4, 7, 40, 51], "download": [43, 59], "driver": [9, 19, 36], "e": 49, "each": 42, "electron": 4, "enantiomorph": 4, "end": 1, "endpoint": 62, "entri": [12, 23], "enum": [76, 78, 81, 83, 84, 86, 89, 94, 95, 98, 105, 111], "enumer": 7, "equat": 7, "error": [7, 49], "errormessag": 85, "estim": [5, 7], "everi": 47, "ewald": 5, "exampl": [63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "except": 29, "exchang": 19, "excit": 7, "expect": 25, "experiment": [0, 25, 46], "export": 46, "extens": 23, "extern": [12, 13, 25], "extract": 7, "factor": [4, 7, 12, 47], "fair": 23, "fallback": 7, "fast": 6, "feedback": 6, "fetch": 56, "fft": 6, "field": 23, "file": [0, 12, 13, 19, 23, 27, 38, 39, 44, 46, 50, 56], "filewriterformat": 86, "filewriterset": 87, "final": 27, "find": [0, 5, 15, 23, 42], "firmwar": [9, 14], "first": [11, 40, 45, 50], "fit": [4, 7, 26], "five": 12, "fix": 7, "flag": [7, 19], "flash": 9, "flight": [7, 24], "floor": 36, "flow": 16, "follow": 25, "form": 49, "format": [0, 23, 27, 33, 44, 49, 54], "four": [12, 47], "fpga": [9, 14, 15, 16, 17, 18, 19, 20, 22, 54, 57], "fpga_status_get": 71, "fpgastatusinn": 88, "frame": [6, 7, 14, 15, 24], "free": [4, 7, 47], "french": 7, "from": [0, 4, 5, 6, 7, 12, 13, 26, 41, 43, 45, 59], "frontend": [9, 25, 56, 60], "full": 7, "function": 26, "fund": 0, "further": 49, "gener": [0, 14, 29, 36, 42], "geometri": [0, 5, 6, 8, 11, 38, 42, 44, 46], "geomrefinementalgorithm": 89, "get": [5, 21, 62], "given": 6, "gnu": 29, "good": 51, "gpl": 29, "gpu": [5, 8, 21, 22, 36, 40, 45], "grid": 26, "gridscan": 90, "group": [0, 4, 7, 12, 23, 38, 47, 49], "guid": 26, "guidanc": 47, "gzip": 1, "h5": 23, "hand": 53, "handl": [5, 24], "hardwar": [14, 17, 22, 26, 40, 43, 45, 54], "hbm": 20, "hdf5": [23, 27], "header": [11, 24, 71], "header_appendix": 23, "headlin": 49, "height": 55, "high": 22, "higher": 12, "histogram": [5, 6, 15], "hl": 14, "host": 45, "how": [13, 28, 29, 34, 38], "http": 71, "hypothesi": [4, 49], "i": [4, 7, 8, 11, 12, 14, 23, 27, 30, 51], "ic": [5, 7], "id": 12, "imag": [1, 5, 9, 12, 21, 23, 24, 26, 53], "image_appendix": 23, "image_buffer_clear_post": 71, "image_buffer_image_cbor_get": 71, "image_buffer_image_jpeg_get": 71, "image_buffer_image_tiff_get": 71, "image_buffer_start_cbor_get": 71, "image_buffer_status_get": 71, "image_pusher_status_get": 71, "imagebufferstatu": 91, "imageformatset": 92, "imagepusherstatu": 93, "imagepushertyp": 94, "index": [0, 4, 6, 7, 21, 23, 39, 42, 47, 49], "indexingalgorithm": 95, "indexingset": 96, "infer": 6, "influenc": 47, "inform": 27, "initialize_post": 71, "inlier": 6, "input": [42, 44], "insid": [11, 23], "instal": [9, 19, 28, 36, 45, 62], "instruct": 36, "instrument": 23, "instrumentmetadata": 97, "integr": [0, 5, 7, 15, 21, 23, 42, 53], "integrationmodel": 98, "intens": 12, "interest": [7, 15, 23], "interfac": [9, 25, 26, 54], "interleav": 40, "intrins": 7, "ion": 0, "ip": 24, "issu": 51, "itself": 55, "jfjoch": 62, "jfjoch_brok": 25, "jfjoch_client": 71, "jfjoch_extract_hkl": 57, "jfjoch_fpga_test": 57, "jfjoch_hdf5_test": 57, "jfjoch_lite_perf_test": 57, "jfjoch_pcie_clear_net_count": 57, "jfjoch_pcie_net_cfg": 57, "jfjoch_pcie_statu": 57, "jfjoch_recompress": 57, "jfjoch_simplon_test": 57, "jfjoch_stills_gpu_replai": 57, "jfjoch_stream2_replai": 57, "jfjoch_udp_simul": 57, "jfjoch_view": 26, "jfjoch_writ": 27, "jfjochset": 99, "jfjochstatist": 100, "json": 44, "judg": 55, "jungfrau": 15, "jungfraujoch": [3, 9, 25, 28, 29, 30, 34, 59, 61], "keepal": 24, "kei": 49, "kernel": [9, 19], "kind": 47, "known": [6, 19, 38, 51], "label": 5, "larg": 45, "lattic": [0, 6, 7, 12, 49], "laue": 7, "layout": 23, "led": 18, "letter": 12, "level": [4, 5], "librari": 56, "licenc": [12, 17], "licens": [17, 29, 36, 62], "like": 40, "likelihood": 8, "limit": [4, 12, 40], "line": [39, 40, 42], "link": 56, "linux": [9, 37, 43], "live": 25, "live_events_get": 71, "load": 19, "local": [5, 25], "lock": 40, "look": 26, "machin": 40, "maco": [26, 36, 40], "macromolecular": 11, "mailbox": 20, "main": 9, "manag": 57, "manual": 38, "map": [4, 5, 8, 20, 49], "marccd": 12, "mask": [15, 33, 42, 53], "master": 23, "mean": [11, 40], "measur": [7, 40], "measurementstatist": 101, "medium": 7, "memori": [19, 20, 27, 40, 43, 45], "merg": [0, 4, 5, 7, 21, 39, 42, 49], "messag": 1, "metadata": [1, 23, 24], "metal": [8, 21], "method": 0, "minicbf": 11, "minimis": 8, "minimum": 5, "mirror": 11, "mmcif": 39, "mode": [25, 39, 41, 42, 47], "model": [0, 4, 7, 8, 12, 21, 38, 39, 40, 47, 49, 51, 62], "modul": [6, 23, 44], "module_": 23, "molecul": [46, 50], "molecular": [0, 4, 21, 46, 49], "monitor": 7, "monoclin": 12, "mosaic": [7, 49], "motiv": 23, "mount": 11, "mous": 26, "multi": [6, 12], "must": 53, "mx": [23, 42, 53], "n": 23, "name": [4, 30], "need": 40, "network": [9, 18, 22], "new": 29, "next": 49, "nexu": 23, "non": [23, 36], "note": [1, 4, 23, 56], "notic": 56, "notif": 24, "npm": 56, "nsight": 40, "null": 4, "number": [12, 40], "nvidia": 36, "nvtx": 40, "nxattenu": 23, "nxbeam": 23, "nxdata": 23, "nxdetector": 23, "nxdetector_modul": 23, "nxentri": 23, "nxinstrument": 23, "nxmx": 23, "nxreflect": 23, "nxsampl": 23, "nxsourc": 23, "nxtransform": 23, "object": 6, "observ": [6, 7], "offlin": 9, "one": [12, 23, 40, 49], "onli": 40, "onlin": 25, "onto": [5, 21], "onward": 46, "open": [17, 26], "openapi": [31, 32, 35], "oper": [36, 52], "option": [27, 39, 42, 47], "order": 8, "other": [0, 23, 26, 27, 46], "our": 12, "out": [11, 45], "outlier": 4, "output": [23, 28, 38, 40, 50], "outsid": 11, "over": 7, "overlap": 49, "overload": [49, 53], "overrid": 42, "overview": [6, 48], "overwrit": 27, "own": 7, "ownership": 19, "packag": [0, 37, 43, 45], "page": [4, 5, 6, 7, 8, 23, 38, 39, 40, 42, 45, 46, 47, 49, 50, 61], "paramet": [8, 19, 71], "parameter": 6, "part": 6, "parti": 56, "partial": 7, "pass": 6, "path": 7, "pci": 22, "pcie": [9, 19, 57], "pciedevicesinn": 102, "pdb": 12, "peak": [6, 40, 55], "pedestal_post": 71, "per": [5, 7, 21, 23, 40, 51], "perform": 22, "phase": 46, "phaser": 46, "physic": 0, "pick": 6, "pip": 62, "pixel": [5, 11, 15, 23, 33, 53], "pixelmaskstatist": 103, "place": [4, 8], "placehold": 12, "placement": [0, 4, 44], "plot": [7, 104, 106], "plotunitx": 105, "point": [7, 12], "poni": 23, "post": 6, "powder": [6, 41, 49], "powdercalibrationfitsigma": 107, "powdercalibrationoutput": 108, "powdercalibrationqu": 109, "powdercalibrationspotcheck": 110, "practic": [4, 47, 51], "pre": [21, 24], "preambl": 29, "predict": [5, 7, 21], "prefix": [23, 39, 44], "prescal": 7, "present": 14, "preview": 24, "preview_pedestal_tiff_get": 71, "preview_plot_bin_get": 71, "preview_plot_get": 71, "problem": 19, "process": [26, 53], "profil": [5, 7, 21, 23], "program": [29, 46], "project": [6, 61], "proper": 9, "properti": [63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 74, 75, 77, 79, 80, 82, 85, 87, 88, 90, 91, 92, 93, 96, 97, 99, 100, 101, 102, 103, 104, 106, 107, 108, 109, 110, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140], "protect": 51, "proven": [12, 39], "provid": 51, "proxi": 7, "pseudo": [0, 4, 12, 49], "psi": 10, "public": [0, 29, 34], "publish": [0, 12], "puls": 23, "pyfai": 53, "python": [9, 31, 35], "q": 5, "qbin": 111, "qualiti": [0, 49], "quantiti": 5, "quarter": 11, "question": 12, "quick": 38, "quiet": 40, "r": [4, 7], "r_model_shell_sc": 49, "radial": 5, "radiu": 7, "rai": 8, "rang": [40, 49], "ratio": 15, "raw": 12, "rc": 2, "re": [39, 42], "reach": 5, "read": [0, 12, 28, 40, 51], "receiv": 25, "reciproc": [5, 7, 17], "recommend": 51, "reduct": [0, 6, 12], "refer": [3, 6, 7, 8, 20, 39, 40, 47, 49, 54, 61], "refin": [0, 6, 8, 21, 42, 47, 49], "refine_": 49, "reflect": [7, 23, 46], "refmac": 40, "region": [7, 15, 23], "regist": 20, "reject": 4, "relat": 47, "releas": [14, 36, 45], "remot": 26, "repair": 6, "replac": [0, 4, 21, 24, 46, 49], "report": [27, 40, 49], "repositori": [37, 45, 56], "reprocess": 23, "republish": 27, "request": 71, "requir": [22, 52, 62], "residu": 6, "resolut": [4, 5], "resolv": 7, "respons": 71, "restrain": 8, "restraint": 8, "result": [23, 25, 26, 49], "result_scan_get": 71, "return": 71, "rhel": [19, 37, 45], "rigid": 4, "ring": [5, 6, 7, 41], "robust": 6, "rocki": 45, "roi": [7, 15, 23], "roi_def": 23, "roiazimlist": 112, "roiazimuth": 113, "roibox": 114, "roiboxlist": 115, "roicircl": 116, "roicirclelist": 117, "roidefinit": 118, "romansh": 30, "root": 15, "rot1": 11, "rot2": 11, "rot3": 11, "rotat": [0, 6, 7, 21, 38, 42, 50], "rotationaxi": 119, "row": 12, "rugnux": [9, 25, 30, 34, 38, 39, 40, 41, 43, 45, 46, 47, 50, 57, 61], "rugnux_clear_post": 71, "rugnux_map_ccp4_get": 71, "rugnux_model_cif_get": 71, "rugnux_refine_test": 57, "rugnux_status_get": 71, "rugnuxliveblob": 120, "rugnuxliveframerang": 121, "rugnuxlivemodel": 122, "rugnuxliverefin": 123, "rugnuxliveshel": 124, "rugnuxlivestatu": 125, "rugnuxlivestep": 126, "rugnuxlivestil": 127, "rugnuxset": 128, "rugnuxstatu": 129, "rugnuxsummaryrow": 130, "rugnuxtriageitem": 131, "rule": 40, "run": [9, 13, 25, 27, 28, 40, 42, 45, 47, 49, 50], "runner": 40, "runtim": 56, "sampl": 23, "satur": 5, "scale": [0, 4, 7, 8, 21, 39, 42], "scan": [21, 26], "scanresult": 132, "scanresultimagesinn": 133, "scope": 51, "score": 4, "sdk": 56, "search": 6, "secur": 51, "seed": 7, "select": 6, "self": 5, "semant": [24, 58], "send": 40, "sensit": 56, "serial": [0, 13, 25, 38, 42, 44, 47, 50], "server": 22, "servic": 25, "set": [7, 25, 26, 36, 39, 40, 47, 53], "setuptool": 62, "sever": 49, "shell": 7, "shelx": 46, "shelxl": 46, "shelxt": 46, "ship": [12, 56], "short": 47, "shortcut": 26, "should": 51, "side": [3, 5], "sign": 53, "signal": 7, "simul": 57, "singl": 12, "site": 4, "size": 5, "slot": 22, "small": [46, 50], "smartnic": 14, "smooth": 7, "smv": 12, "snr": 15, "socket": 24, "softwar": [0, 9, 51, 52, 53, 56], "sohnck": 49, "solvent": [0, 4, 8], "someth": 40, "sourc": [23, 26, 43, 45, 56, 59], "space": [0, 4, 5, 7, 38, 47, 49], "spec": 31, "specif": [0, 32], "sphere": 5, "spindl": 6, "split": 24, "spot": [0, 5, 6, 7, 15, 21, 23, 42, 49], "spotfindingset": 134, "squar": 15, "stack": 18, "stage": [6, 7], "standard": 23, "standarddetectorgeometri": 135, "start": [1, 25, 38, 62], "start_post": 71, "state": 11, "static": 56, "statist": [5, 7, 15, 23], "statistics_calibration_get": 71, "statistics_data_collection_get": 71, "statistics_get": 71, "statu": 27, "status_get": 71, "step": [40, 47], "still": [6, 7, 13, 38, 42, 47, 49, 50], "stop": 5, "stream": 24, "strong": 5, "strongli": 17, "structur": [0, 4, 12, 27, 46, 47], "style": 23, "summari": 49, "summat": [7, 15], "superstructur": 49, "suppli": 23, "support": [0, 10, 45], "sweep": [12, 49], "switch": [18, 22], "swung": 11, "symmetr": 12, "symmetri": [0, 4, 6, 12, 49], "synthesi": 14, "sysf": 19, "system": [36, 37, 40, 52], "systemat": 7, "tabl": [12, 23, 40, 49], "take": [40, 46], "target": 8, "tcp": 24, "tcpframehead": 24, "tcpset": 136, "technic": 54, "term": 29, "termin": 38, "test": [0, 6, 7, 12, 13, 25, 55, 57, 62], "tetragon": 12, "text": 1, "them": 13, "theta": 5, "thi": [4, 5, 6, 7, 8, 23, 38, 39, 40, 42, 45, 46, 47, 49, 50], "third": 56, "threat": 51, "three": [7, 26, 38], "threshold": 15, "tiff": 27, "tighten": 6, "time": [23, 40, 56], "token": 51, "toler": 6, "tool": [26, 38, 57], "topologi": 8, "tour": 26, "transceiv": 18, "transform": 23, "translat": [4, 49], "transmiss": 24, "tree": 56, "trial": 8, "trigger_post": 71, "trigon": 12, "turn": 11, "twin": [0, 4, 8, 12, 49], "twin_subgroup_": 49, "two": [5, 6, 11, 12, 23, 40, 49], "type": [1, 24, 71], "u55c": 9, "ubuntu": [37, 45], "unexplain": 8, "unit": [6, 45], "unitcel": 137, "unknown": 6, "unmerg": 46, "unmodel": 0, "up": [25, 40], "us": [0, 13], "usag": [0, 27, 62], "user": [1, 23, 33], "v": 23, "valid": [4, 21, 39, 40, 49], "valu": [12, 13], "vector": [6, 11], "vendor": 56, "verdict": 40, "veri": 45, "verif": 9, "version": [17, 58], "version_get": 71, "vertic": 11, "view": 26, "viewer": [9, 59, 61], "virtual": 19, "vivado": 14, "vocabulari": 49, "wait_till_done_post": 71, "wait_until_running_post": 71, "we": [12, 13], "weak": 56, "web": [9, 60], "weight": 8, "what": [7, 8, 11, 28, 30, 40, 41, 49, 51], "when": [14, 27], "where": [12, 13, 26, 28], "which": [4, 19, 53], "whose": 12, "why": [7, 23], "width": 7, "wilson": 7, "window": [26, 36, 40], "work": 4, "write": 41, "writer": [9, 24], "written": 39, "x": 8, "xd": [46, 53], "xfel": [13, 23, 44], "xfel_event_code_get": 71, "xfel_pulse_id_get": 71, "xilinx": 14, "yet": 8, "you": 51, "your": 29, "z": 39, "zero": 24, "zeromq": 24, "zeromqmetadataset": 138, "zeromqpreviewset": 139, "zeromqset": 140, "\u03c3": 7}}) \ No newline at end of file

Jungfraujoch (1.0.0-rc.186)

Download OpenAPI specification:

Filip Leonarski (Paul Scherrer Institute): filip.leonarski@psi.ch License: GPL-3.0

API to control Jungfraujoch developed by the Paul Scherrer Institute (Switzerland). +Jungfraujoch is a data acquisition and analysis system for pixel array detectors, primarly PSI JUNGFRAU. +Jungfraujoch uses FPGA boards to acquire data at high data rates.

+

License Clarification

While this API definition is licensed under GPL-3.0, the GPL copyleft provisions do not apply +when this file is used solely to generate OpenAPI clients or when implementing applications that +interact with the API. Generated client code and applications using this API definition are not +subject to the GPL license requirements and may be distributed under terms of your choosing.

+

This exception is similar in spirit to the Linux Kernel's approach to userspace API headers and +the GCC Runtime Library Exception. The Linux Kernel developers have explicitly stated that +user programs that merely use the kernel interfaces (syscalls, ioctl definitions, etc.) are not +derivative works of the kernel and are not subject to the terms of the GPL.

+

This exception is intended to allow wider use of this API specification without imposing GPL +requirements on applications that merely interact with the API, regardless of whether they +communicate through network calls or other mechanisms.

+

Initialize detector and data acquisition

Should be used in two cases:

+
    +
  • Detector is in Inactive state
  • +
  • Detector is in Error state +X-ray shutter must be closed. +This operation will reconfigure network interface of the detector. +During operation of the detector it is recommended to use the POST /pedestal operation instead. +If storage cells are used, the execution time might be few minutes. +It also clears the image buffer, the previous collection's plots and live rugnux status, disables live rugnux analysis and removes the rugnux model. +It drops the previous dataset's bearer tokens and resets its settings, so nothing of that dataset stays readable.
  • +
+

This is async function - one needs to use POST /wait_till_done to ensure operation is done.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Collect dark current for the detector

Updates calibration of the JUNGFRAU detector. Must be in Idle state.

+

X-ray shutter must be closed. Recommended to run once per hour for long integration times (> 100 us).

+

This is async function - one needs to use POST /wait_till_done to ensure operation is done.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Start detector

Start data acquisition. +Detector must be in Idle state. +Default behavior is for the call to block until detector is ready to accept soft/TTL triggers. +However, this behavior can be changed by settings async_start to true in the request body, +in which case the call will return immediately and one needs to use /wait_until_running to ensure detector is ready to run. +Optional tokens protect the dataset: while set, its statistics, buffered images and plots +require Authorization: Bearer <token>.

+
Request Body schema: application/json
images_per_trigger
integer <int64> >= 1
Default: 1

For standard synchrotron data collection - this is number of images collected per one TTL trigger +For XFEL (pulsed source) - this number is ignored and set to 1 +For storage cell mode - this number is ignored and set to number of storage cells

+
ntrigger
integer <int64> >= 1
Default: 1

Number of TTL trigger that the detector is expected to receive during data collection

+
image_time_us
integer <int64> >= 0

Image time. +If not provided (or zero value) the frame time is assumed as default. +For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time.
In XFEL mode: summation happens for frames collected with multiple triggers. +Ignored for storage cells and if raw data are saved.

+
beam_x_pxl
required
number <float>

/entry/detector/beam_center_x in NXmx +Beam center in X direction [pixels]

+
beam_y_pxl
required
number <float>

/entry/detector/beam_center_y in NXmx +Beam center in X direction [pixels]

+
detector_distance_mm
required
number <float> >= 0

/entry/detector/distance in NXmx Detector distance [mm]

+
incident_energy_keV
required
number <float> [ 0.001 .. 500 ]

Used to calculate /entry/beam/incident_wavelength in NXmx +Incident particle (photon, electron) energy in keV

+
file_prefix
string
Default: ""

Prefix for filenames. If left empty, no file will be saved.

+
images_per_file
integer <int64> >= 1

Number of images in a single HDF5 data file, taken literally when given. +If omitted, it is chosen from the acquisition: a rotation sweep of at most 20000 images +goes into a single data file, so the dataset stays readable by programs that follow only +the first data file of a legacy master; a grid scan is split on a whole number of fast-axis +rows; anything else (stills, serial) uses 1000.

+
space_group_number
integer <int64> [ 1 .. 230 ]

Number of space group for the crystal. Currently used solely as metadata, not relevant for image processing done in Jungfraujoch.

+
sample_name
string
Default: ""

/entry/sample/name in NXmx +Sample name

+
compression
string
Default: "bslz4"
Enum: "bslz4" "bszstd" "bszstd_rle" "bszstd_rlehuf" "none"

Compression type for the images transferred over ZeroMQ and saved to HDF5 file.

+
total_flux
number <float> >= 0

/entry/beam/total_flux in NXmx +Flux incident on beam plane in photons per second. In other words this is the flux integrated over area. [photons/s]

+
transmission
number <float> [ 0 .. 1 ]

/entry/instrument/attenuator/attenuator_transmission +Transmission of attenuator (filter) [no units]

+
beam_size_x_um
number <float> >= 0

First element of /entry/instrument/beam/incident_beam_size in NXmx +Horizontal size of the X-ray beam where it meets the sample - the FWHM of a focused beam, +the full width of a slit-defined one. [um]

+
beam_size_y_um
number <float> >= 0

Second element of /entry/instrument/beam/incident_beam_size in NXmx +Vertical size of the X-ray beam where it meets the sample. [um]

+
object (rotation_axis)

Definition of a crystal rotation axis

+
object (grid_scan)

Definition of a grid scan. Combine it with a goniometer axis to state the angle the spindle +stood at: send goniometer with step 0 and the start angle of the grid scan, and that +angle is written per image into the NXmx sample transformation chain. Without one the +spindle is recorded at 0, which says that nobody stated an angle rather than that the +spindle stood at 0.

+
header_appendix
any

Header appendix, added as user_data/user to start ZeroMQ message (can be any valid JSON) +In general, it is not saved in HDF5 file.

+

However, if values are placed in "hdf5" object, jfjoch_writer will write them in /entry/user of the HDF5 file. +This applies solely to string and number (double floating-point). No arrays/sub-objects is allowed. +For example {"hdf5": {"val1":1, "val2":"xyz"}}, will write /entry/user/val1 and /entry/user/val2.

+
image_appendix
any

Image appendix, added as user_data to image ZeroMQ message (can be any valid JSON) +Not saved in HDF5 file

+
data_reduction_factor_serialmx
number <float> [ 0 .. 1 ]
Default: 1

Rate at which non-indexed images are accepted to be forwarded to writer. +Value of 1.0 (default) means that all images are written. +Values below zero mean that non-indexed images will be accepted with a given probability.

+
pixel_value_low_threshold
integer <int64> >= 0

Set all counts lower than the value to zero. +When the value is set, negative numbers other than error pixel value are always set to zero. +Setting to zero is equivalent to turning the option off.

+
run_number
integer <int64> >= 0

Number of run within an experimental session. +Transferred over CBOR stream as "series ID", though not saved in HDF5 file. +It is highly recommended to keep this number unique for each data collection during experimental series. +If not provided, the number will be automatically incremented.

+
run_name
string

Unique ID of run. +Transferred over CBOR stream as "unique series ID", though not saved in HDF5 file. +It is highly recommended to keep this name unique for each data collection during experimental series. +If not provided, the name will be automatically generated as number + colon + file_prefix.

+
experiment_group
string

Name of group owning the data (e.g. p-group or proposal number). +Transferred over CBOR stream, though not saved in HDF5 file.

+
poisson_compression
integer <int64> [ 0 .. 16 ]

Enable lossy compression of pixel values that preserves Poisson statistics. +Requires to provide a numerical factor SQ. +Pixel value P will be transformed to round(sqrt(P) * SQ), with rounding to the closest integer. +Compression is turned off if the value is missing or it is set to zero.

+
write_nxmx_hdf5_master
boolean
Default: true

Write NXmx formatted HDF5 master file. Recommended to use for macromolecular crystallography experiments +and to turn off for other experiments.

+
save_calibration
boolean

Forward image calibration (at the moment pedestal and pedestal RMS for JUNGFRAU) using the ZeroMQ stream to writer. +If parameter is not provided calibration will be saved only if more than 4 images are recorded.

+
polarization_factor
number <float> [ -1 .. 1 ]

Polarization factor for integration; 1.0 is horizontal polarization; -1.0 is vertical polarization

+
ring_current_mA
number <float> >= 0

Ring current at the beginning of the data collection

+
sample_temperature_K
number <float> >= 0

Sample temperature in Kelvin

+
poni_rot1_rad
number <float> [ -6.28318530718 .. 6.28318530718 ]
Default: 0

PONI angle rot1 (see PyFAI documentation for details) in radians

+
poni_rot2_rad
number <float> [ -6.28318530718 .. 6.28318530718 ]
Default: 0

PONI angle rot2 (see PyFAI documentation for details) in radians

+
poni_rot3_rad
number <float> [ -6.28318530718 .. 6.28318530718 ]
Default: 0

PONI angle rot3 (see PyFAI documentation for details) in radians

+
object (unit_cell)

Unit cell parameters. Necessary to run indexing. Units of angstrom and degree

+
spot_finding
boolean
Default: true

Enable spot finding and save spots

+
object

Geometry of Smargon goniometer at SLS 2.0 / MX beamlines. +Assuming that Smargon is used as static positioner and not moving during the scan, allowing to reconstruct geometry.

+
max_spot_count
integer [ 10 .. 2000 ]
Default: 250

Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected

+
detect_ice_rings
boolean

Flag spots as ice rings and reduce their effect on indexing. Left out, the broker's own +spot finding treats no spot as an ice ring, rugnux live decides as a bare rugnux would (on +for a rotation sweep, off for stills), and the master file carries no detect_ice_rings.

+
async_start
boolean
Default: false

When set to true, /start will not wait for detector and Jungfraujoch to be ready for the measurement.

+
Array of objects (detector_module_placement)

Where the detector's modules lie for this dataset, as rugnux measures them: rugnux writes +<prefix>_module_placement.json, which holds exactly this field, to be merged into the dataset settings. +Each entry names its module by its readout pixel 0 and readout axes in the stored image (x0, y0, +fast_axis, slow_axis, after mirror_y; see detector_module_placement), in any order; every +module must be named once, and only modules of the detector, else /start fails with 400. The image +is assembled as configured (custom_geometry); the placement goes into the start message and the +NXmx module_NN groups, and the analysis takes it. Omitted or empty: +modules as assembled.

+
tokens
Array of strings[ items non-empty ]

Bearer tokens that protect this dataset: any number, all equivalent (e.g. a beamline +secret and a dataset-specific user secret). While set, the endpoints marked with the +bearerAuth security scheme require Authorization: Bearer <token> and answer 401 otherwise. +Every accepted /start replaces the previous dataset's tokens; omitted or empty means no +protection. Never returned by any endpoint.

+
object

Responses

Request samples

Content type
application/json
{
  • "images_per_trigger": 1,
  • "ntrigger": 1,
  • "image_time_us": 0,
  • "beam_x_pxl": 0.1,
  • "beam_y_pxl": 0.1,
  • "detector_distance_mm": 0.1,
  • "incident_energy_keV": 0.001,
  • "file_prefix": "",
  • "images_per_file": 1,
  • "space_group_number": 1,
  • "sample_name": "",
  • "compression": "bslz4",
  • "total_flux": 0.1,
  • "transmission": 1,
  • "beam_size_x_um": 0.1,
  • "beam_size_y_um": 0.1,
  • "goniometer": {
    },
  • "grid_scan": {
    },
  • "header_appendix": null,
  • "image_appendix": null,
  • "data_reduction_factor_serialmx": 1,
  • "pixel_value_low_threshold": 0,
  • "run_number": 0,
  • "run_name": "string",
  • "experiment_group": "string",
  • "poisson_compression": 16,
  • "write_nxmx_hdf5_master": true,
  • "save_calibration": true,
  • "polarization_factor": -1,
  • "ring_current_mA": 0.1,
  • "sample_temperature_K": 0.1,
  • "poni_rot1_rad": 0,
  • "poni_rot2_rad": 0,
  • "poni_rot3_rad": 0,
  • "unit_cell": {
    },
  • "spot_finding": true,
  • "smargon": {
    },
  • "max_spot_count": 250,
  • "detect_ice_rings": true,
  • "async_start": false,
  • "module_placement": [
    ],
  • "tokens": [
    ],
  • "xray_fluorescence_spectrum": {
    }
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Wait for acquisition running

Block execution of external script till detector and Jungfraujoch are ready to collect data. +To not block web server for a indefinite period of time, the procedure is provided with a timeout. +Extending timeout is possible, but requires to ensure safety that client will not close the connection and retry the connection.

+
query Parameters
timeout
integer [ 0 .. 3600 ]
Default: 60

Timeout in seconds (0 == immediate response)

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Wait for acquisition done

Block execution of external script till initialization, data collection or pedestal is finished. +Running this command does not affect (cancel) running data collection, it is only to ensure synchronous execution of other software.

+

To not block web server for a indefinite period of time, the procedure is provided with a timeout. +Extending timeout is possible, but requires to ensure safety that client will not close the connection and retry the connection.

+
query Parameters
timeout
integer [ 0 .. 3600 ]
Default: 60

Timeout in seconds (0 == immediate response)

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Send soft trigger to the detector

Generate soft trigger

+

Responses

Cancel running data collection

Command will inform FPGA network card to stop pedestal or data collection at the current stage. +Any frame that is currently being processed by CPU will be finished and sent to writer. +Given the command is making sure to gracefully stop data acquisition and detector, it might take some time to switch back after command finished to Idle state.

+

With rugnux live mode (/config/rugnux) the command also cuts the rugnux analysis, during the collection +or after its last image alike: the collection ends with what the analysis has established +(see cut in /rugnux/status). After the last image the collection itself is complete and is not +marked as cancelled.

+

If data collection is not running, the command has no effect.

+

Responses

Prepare detector to turn off

Should be in Idle or Error state. +Command deactivates data acquisition and turns off detector high voltage and ASIC. +Should be used always before turning off power from the detector.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Change detector configuration

Detector settings are ones that have effect on calibration, i.e., pedestal has to be collected again after changing these settings. +This can only be done when detector is Idle, Error or Inactive states. +If detector is in Idle state , pedestal procedure will be executed automatically - there must be no X-rays on the detector during the operation. +If detector is in Inactive or Error states, new settings will be saved, but no calibration will be executed.

+
Request Body schema: application/json
frame_time_us
required
integer <int64> >= 1

Interval between consecutive frames. +This is internal frame time for the JUNGFRAU detector, image time has to be integer multiply of this number. +For EIGER detector this is default frame time, not used otherwise

+
count_time_us
integer <int64>

Integration time of the detector. +If not provided count time will be set to maximum value for a given frame time.

+
internal_frame_generator
boolean
Default: false

Use internal frame generator in FPGA instead of getting data from a real detector

+
internal_frame_generator_images
integer <int64> [ 1 .. 64 ]
Default: 1

Number of images stored in the internal frame generator.

+
detector_trigger_delay_ns
integer <int64> >= 0
Default: 0

Delay between TTL trigger and acquisition start [ns]

+
timing
string (detector_timing)
Default: "trigger"
Enum: "auto" "trigger" "burst" "gated"
eiger_threshold_keV
number <float> [ 1 .. 100 ]

Threshold for the PSI EIGER detector and all DECTRIS detectors. +If value is provided, it will be used for all subsequent acquisitions, irrespective of beam energy. +If value is not provided, threshold will be determined on start of acquisition as half of incident energy. +This might lead to increased start time.

+
eiger_bit_depth
integer <int64>
Enum: 8 16 32

Bit depth of PSI EIGER read-out. This is
If value is not provided, depth will be determined based on the image time:

+
    +
  • Exposure time < 500 microseconds depth of 8 bit will be used,
  • +
  • 500 <= exposure time < 2622 microseconds depth of 16 bit will be used
  • +
  • Exposure time >= 2622 microseconds depth of 32 bit will be used.
  • +
+
jungfrau_pedestal_g0_frames
integer <int64> >= 0
Default: 2000
jungfrau_pedestal_g1_frames
integer <int64> >= 0
Default: 300
jungfrau_pedestal_g2_frames
integer <int64> >= 0
Default: 300
jungfrau_pedestal_min_image_count
integer <int64> >= 32
Default: 128

Minimum number of collected images for pedestal to consider it viable

+
jungfrau_storage_cell_count
integer <int64> [ 1 .. 16 ]
Default: 1
jungfrau_storage_cell_delay_ns
integer <int64> >= 2100
Default: 5000

Delay between two storage cells [ns]

+
jungfrau_fixed_gain_g1
boolean
Default: false

Fix gain to G1 (can be useful for storage cells)

+
jungfrau_use_gain_hg0
boolean
Default: false

Use high G0 (for low energy applications)

+

Responses

Request samples

Content type
application/json
{
  • "frame_time_us": 1,
  • "count_time_us": 0,
  • "internal_frame_generator": false,
  • "internal_frame_generator_images": 1,
  • "detector_trigger_delay_ns": 0,
  • "timing": "auto",
  • "eiger_threshold_keV": 1,
  • "eiger_bit_depth": 8,
  • "jungfrau_pedestal_g0_frames": 2000,
  • "jungfrau_pedestal_g1_frames": 300,
  • "jungfrau_pedestal_g2_frames": 300,
  • "jungfrau_pedestal_min_image_count": 128,
  • "jungfrau_storage_cell_count": 1,
  • "jungfrau_storage_cell_delay_ns": 5000,
  • "jungfrau_fixed_gain_g1": false,
  • "jungfrau_use_gain_hg0": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get detector configuration

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "frame_time_us": 1,
  • "count_time_us": 0,
  • "internal_frame_generator": false,
  • "internal_frame_generator_images": 1,
  • "detector_trigger_delay_ns": 0,
  • "timing": "auto",
  • "eiger_threshold_keV": 1,
  • "eiger_bit_depth": 8,
  • "jungfrau_pedestal_g0_frames": 2000,
  • "jungfrau_pedestal_g1_frames": 300,
  • "jungfrau_pedestal_g2_frames": 300,
  • "jungfrau_pedestal_min_image_count": 128,
  • "jungfrau_storage_cell_count": 1,
  • "jungfrau_storage_cell_delay_ns": 5000,
  • "jungfrau_fixed_gain_g1": false,
  • "jungfrau_use_gain_hg0": false
}

Change indexing algorithm settings

This can only be done when detector is Idle, Error or Inactive states.

+
Request Body schema: application/json
algorithm
required
string (indexing_algorithm)
Default: "FFBIDX"
Enum: "FFBIDX" "FFT" "FFTW" "Auto" "None"

Selection of an indexing algorithm used by Jungfraujoch

+
fft_max_unit_cell_A
required
number <float> [ 50 .. 500 ]
Default: 250

Largest unit cell to be indexed by FFT algorithm; parameter value affects execution time of FFT

+
fft_min_unit_cell_A
required
number <float> [ 5 .. 40 ]
Default: 10

Smallest unit cell to be indexed by FFT algorithm; parameter value affects execution time of FFT

+
fft_high_resolution_A
required
number <float> [ 0.5 .. 6 ]
Default: 2

Sets how finely the FFT samples each search direction: it fixes the extent of the projection +histogram, and with it the transform size, so it affects execution time and memory of FFT. +It does NOT filter spots - every spot is projected whatever its resolution, so raising it +does not make the transform see a coarser subset of the data. +There is also correlation between smallest unit cell and this value, which need to be checked for very small systems.

+
fft_num_vectors
required
integer <int64> >= 128
Default: 16384

Number of search directions for the FFT algorithm; parameter value affects execution time of FFT.

+
tolerance
required
number <float> [ 0 .. 0.5 ]

Acceptance tolerance for spots after the indexing run - the larger the number, the more spots will be accepted

+
thread_count
required
integer <int64> [ 1 .. 64 ]

Thread count for indexing algorithm

+
geom_refinement_algorithm
required
string (geom_refinement_algorithm)
Enum: "BeamCenter" "OrientationOnly" "Flex" "None"

Selection of an post-indexing least-square diffraction geometry refinement algorithm used by Jungfraujoch. +BeamCenter - This option is refining both beam center and lattice (restricted to a chosen/detected Bravais lattice). +OrientationOnly - This option is refining only orientation of the lattice. +Flex - Tries all per-image refinements and keeps whichever indexes the most spots, letting the pipeline decide (the rugnux flex mode).

+
unit_cell_dist_tolerance
required
number <float> [ 0.0001 .. 0.2001 ]
Default: 0.05

Relative distance tolerance for unit cell vs. reference; Lattices outside given tolerance will be ignored

+
viable_cell_min_spots
required
integer <int64> >= 5
Default: 10

Minimum number of indexed spots required for a cell to be considered viable

+
index_ice_rings
required
boolean
Default: false

Include spots marked as ice rings in the indexing run. +If dataset_settings doesn't have detect_ice_rings on, this option will have no effect on processing.

+
rotation_indexing
boolean
Deprecated
Default: false

Ignored: accepted on input and always returned as false; will be removed in a future release. +The Lite and FPGA workflows index each image on its own, rotation or not; rotation indexing is done by rugnux live.

+
rotation_indexing_min_angular_range_deg
number <float> >= 1
Deprecated
Default: 20

Ignored, as rotation_indexing; always returned as 20.0.

+
rotation_indexing_angular_stride_deg
number <float> >= 0
Deprecated
Default: 0.5

Ignored, as rotation_indexing; always returned as 0.5.

+
blocking
required
boolean
Default: true

Indexing in Jungfraujoch goes with a dedicated thread pool. +If set to false, the thread pool is non-blocking, i.e. if there are no threads available, image indexing will be skipped. This option is recommended for real-time processing at high frame rates. +If set to true, the thread pool will block until a thread is available.

+

Responses

Request samples

Content type
application/json
{
  • "algorithm": "FFBIDX",
  • "fft_max_unit_cell_A": 250,
  • "fft_min_unit_cell_A": 10,
  • "fft_high_resolution_A": 2,
  • "fft_num_vectors": 16384,
  • "tolerance": 0.5,
  • "thread_count": 1,
  • "geom_refinement_algorithm": "BeamCenter",
  • "unit_cell_dist_tolerance": 0.05,
  • "viable_cell_min_spots": 10,
  • "index_ice_rings": false,
  • "rotation_indexing": false,
  • "rotation_indexing_min_angular_range_deg": 20,
  • "rotation_indexing_angular_stride_deg": 0.5,
  • "blocking": true
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get indexing configuration

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "algorithm": "FFBIDX",
  • "fft_max_unit_cell_A": 250,
  • "fft_min_unit_cell_A": 10,
  • "fft_high_resolution_A": 2,
  • "fft_num_vectors": 16384,
  • "tolerance": 0.5,
  • "thread_count": 1,
  • "geom_refinement_algorithm": "BeamCenter",
  • "unit_cell_dist_tolerance": 0.05,
  • "viable_cell_min_spots": 10,
  • "index_ice_rings": false,
  • "rotation_indexing": false,
  • "rotation_indexing_min_angular_range_deg": 20,
  • "rotation_indexing_angular_stride_deg": 0.5,
  • "blocking": true
}

Change Bragg integration settings

This can only be done when detector is Idle, Error or Inactive states.

+
Request Body schema: application/json
integration_model
required
string (integration_model)
Default: "ProfileGaussian"
Enum: "ProfileGaussian" "ProfileEmpirical" "BoxSum"

Bragg spot integration model. +ProfileGaussian - profile fit with a measured-width Gaussian (Kabsch-style), the default; more + accurate intensities than box summation. +ProfileEmpirical - profile fit with a per-resolution-shell empirical profile learned from strong spots. +BoxSum - classical uniform box summation minus a ring-mean background; the simpler, faster fallback.

+
max_hkl
integer [ 1 .. 511 ]
Default: 100

How far the Bragg predictor walks the lattice: reflections with |h|,|k|,|l| above this are +never predicted. An axis is truncated once a/d_min exceeds it, so a long axis - or a short +one taken to high resolution - loses its outermost reflections. The cost grows as the cube +(2n+1)^3 of candidates per image, which is why online keeps a fixed, predictable value +instead of taking it from whichever crystal is mounted.

+

Omitting the field selects the default above; it is never interpreted as "choose per +crystal". The offline tools (rugnux, viewer) do derive it from the refined cell when it is +left unset there, but that is their own default and is not reachable through this API.

+

Responses

Request samples

Content type
application/json
{
  • "integration_model": "ProfileGaussian",
  • "max_hkl": 100
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get Bragg integration configuration

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "integration_model": "ProfileGaussian",
  • "max_hkl": 100
}

Change file writer settings

This can only be done when detector is Idle, Error or Inactive states.

+
Request Body schema: application/json
overwrite
boolean
Default: false

Inform jfjoch_write to overwrite existing files. Otherwise files would be saved with .h5.{timestamp}.tmp suffix.

+
format
string (file_writer_format)
Default: "NXmxVDS"
Enum: "NXmxOnlyData" "NXmxLegacy" "NXmxVDS" "NXmxIntegrated" "CBF" "TIFF" "NoFileWritten"

NoFileWritten - no files are written at all +NXmxOnlyData - only data files are written, no master file +NXmxLegacy - legacy format with soft links to data files in the master file; necessary for DECTRIS Albula 4.0 and DECTRIS Neggia +NXmxVDS - newer format with virtual dataset linking data files in the master file, also includes better metadata handling +NXmxIntegrated - single HDF5 per dataset +CBF - DEPRECATED, no longer supported; kept for back compatibility only. Requests using this value are rejected. Only HDF5 formats are written. +TIFF - DEPRECATED, no longer supported; kept for back compatibility only. Requests using this value are rejected. Only HDF5 formats are written.

+

Responses

Request samples

Content type
application/json
{
  • "overwrite": false,
  • "format": "NXmxOnlyData"
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get file writer settings

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "overwrite": false,
  • "format": "NXmxOnlyData"
}

Change instrument metadata

This can only be done when detector is Idle, Error or Inactive states.

+
Request Body schema: application/json
source_name
required
string
source_type
string
Default: ""

Type of radiation source. NXmx gives a fixed dictionary, though Jungfraujoch is not enforcing compliance. +https://manual.nexusformat.org/classes/base_classes/NXsource.html#nxsource +NXsource allows the following:

+

Spallation Neutron Source +Pulsed Reactor Neutron Source +Reactor Neutron Source +Synchrotron X-ray Source +Pulsed Muon Source +Rotating Anode X-ray +Fixed Tube X-ray +UV Laser +Free-Electron Laser +Optical Laser +Ion Source +UV Plasma Source +Metal Jet X-ray

+
instrument_name
required
string
pulsed_source
boolean
Default: false

Settings specific to XFEL (e.g., every image has to come from TTL trigger, save pulse ID and event code)

+
electron_source
boolean
Default: false

Settings specific to electron source (e.g., wavelength definition)

+

Responses

Request samples

Content type
application/json
{
  • "source_name": "Swiss Light Source",
  • "source_type": "Synchrotron X-ray Source",
  • "instrument_name": "CristallinaMX",
  • "pulsed_source": false,
  • "electron_source": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get instrument metadata

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "source_name": "Swiss Light Source",
  • "source_type": "Synchrotron X-ray Source",
  • "instrument_name": "CristallinaMX",
  • "pulsed_source": false,
  • "electron_source": false
}

Change image output format

This can only be done when detector is Idle, Error or Inactive states.

+
Request Body schema: application/json
summation
required
boolean

Enable summation of images to a given image_time +If disabled images are saved according to original detector speed, but image count is adjusted

+
geometry_transform
required
boolean

Place module read-out into their location on composed detector and extend multipixels

+
jungfrau_conversion
required
boolean

Convert pixel value in ADU to photon counts/energy +Only affects JUNGFRAU detector

+
jungfrau_conversion_factor_keV
number <float> [ 0.001 .. 500 ]

Used to convert energy deposited into pixel to counts +If not provided incident_energy_keV is used

+
bit_depth_image
integer <int64>
Enum: 8 16 32

Bit depth of resulting image (it doesn't affect the detector read-out value) +If not provided value is adjusted automatically

+
signed_output
boolean

Controls if pixels have signed output +If not provided value is adjusted automatically

+
mask_module_edges
required
boolean
Default: true

Mask 1 pixel on the module boundary

+
mask_chip_edges
required
boolean
Default: true

Mask multipixels on chip boundary

+
jungfrau_mask_pixels_without_g0
boolean
Default: true

JUNGFRAU: mask pixels that don't operate in G0, but do operate in G1 and G1. +This should be turned off for cases, where detector is operated at room temperature with long exposure time.

+
apply_mask
required
boolean
Default: false

Masked pixels are set to special value in the images produced by Jungfraujoch

+
jungfrau_pedestal_g0_rms_limit
integer <int64> >= 0
Default: 100

Pixels with pedestal G0 RMS above the threshold are marked as masked pixels

+

Responses

Request samples

Content type
application/json
{
  • "summation": true,
  • "geometry_transform": true,
  • "jungfrau_conversion": true,
  • "jungfrau_conversion_factor_keV": 0.001,
  • "bit_depth_image": 8,
  • "signed_output": true,
  • "mask_module_edges": true,
  • "mask_chip_edges": true,
  • "jungfrau_mask_pixels_without_g0": true,
  • "apply_mask": false,
  • "jungfrau_pedestal_g0_rms_limit": 100
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get image output format

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "summation": true,
  • "geometry_transform": true,
  • "jungfrau_conversion": true,
  • "jungfrau_conversion_factor_keV": 0.001,
  • "bit_depth_image": 8,
  • "signed_output": true,
  • "mask_module_edges": true,
  • "mask_chip_edges": true,
  • "jungfrau_mask_pixels_without_g0": true,
  • "apply_mask": false,
  • "jungfrau_pedestal_g0_rms_limit": 100
}

Configure format for raw data collection

This can only be done when detector is Idle, Error or Inactive states.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Configure format for data collection with full conversion

This can only be done when detector is Idle, Error or Inactive states.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Configure spot finding

Can be done anytime, also while data collection is running

+
Request Body schema: application/json
enable
required
boolean
Default: true

Enable spot finding. This is temporary setting, i.e. can be changed anytime during data collection. +Even if disabled spot finding information will still be send and written, though always with zero spots.

+
indexing
required
boolean
Default: true

Enable indexing. This is temporary setting, i.e. can be changed anytime during data collection.

+
signal_to_noise_threshold
required
number <float> >= 0
photon_count_threshold
required
integer <int64> >= 0
min_pix_per_spot
required
integer <int64> >= 1
max_pix_per_spot
required
integer <int64> >= 1
high_resolution_limit
number <float>

High resolution limit for spot finding [Angstrom]. Optional: if omitted, spot finding extends +as far as the detector reaches, i.e. the detection is not clipped in resolution.

+
low_resolution_limit
number <float>

Low resolution limit for spot finding [Angstrom]. Optional: if omitted, spot finding is not +clipped at the low-resolution end. A value of 0 is accepted and means the same thing.

+
high_resolution_limit_for_spot_count_low_res
required
number <float> [ 2 .. 8 ]

High resolution threshold to consider spot "low resolution" [Angstrom]

+
quick_integration
boolean
Deprecated
Default: false

Ignored: accepted on input and always returned as false; will be removed in a future release. +The Lite and FPGA workflows index images but do not integrate them; integration is done by rugnux live.

+
ice_ring_width_q_recipA
required
number <float> [ 0 .. 1 ]
Default: 0.03

Half-width of the ice ring band in q (1/A). Matches the offline default in image_analysis/spot_finding/SpotFindingSettings.h, which was set from a measured ring FWHM of ~0.06; the two must agree or the same data gets a narrower ice band online.

+
high_res_gap_Q_recipA
number <float> [ 0.1 .. 5 ]
Default: 1.5

This parameter is used to remove spurious spots at a very high resolution, that sometimes appear due to very low background close to the edge of the detector. +If there is a gap in (1/d)-space between spots of at least this size, spots on the side of the gap with high resolution will be discarded. This is optional parameter. +This option should be turned OFF for small molecule datasets or for crystals with very low mosaicity, when it is expected to see only few spots in any case.

+
adaptive_threshold
boolean
Default: false

Self-calibrating spot detection: replace the fixed photon_count_threshold by a per-resolution-ring +threshold derived from each image's own noise, so the same setting works across datasets without +per-dataset tuning. photon_count_threshold is then ignored and false_pixels_per_frame sets the +operating point instead. +Used only on detectors whose images are analysed in software (the DECTRIS/SIMPLON workflow). +The JUNGFRAU and EIGER workflows find spots on the FPGA, which applies its own fixed threshold; +there the setting is accepted and ignored, so the same settings can be shared across detectors.

+
false_pixels_per_frame
number <float> [ 1 .. 100000 ]
Default: 100

Operating point of the adaptive threshold: the number of noise pixels tolerated per frame. +About 100 suits a multi-megapixel detector. Ignored unless adaptive_threshold is set.

+

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "indexing": true,
  • "signal_to_noise_threshold": 0.1,
  • "photon_count_threshold": 0,
  • "min_pix_per_spot": 1,
  • "max_pix_per_spot": 1,
  • "high_resolution_limit": 0.1,
  • "low_resolution_limit": 0.1,
  • "high_resolution_limit_for_spot_count_low_res": 2,
  • "quick_integration": false,
  • "ice_ring_width_q_recipA": 0.03,
  • "high_res_gap_Q_recipA": 1.5,
  • "adaptive_threshold": false,
  • "false_pixels_per_frame": 100
}

Get data processing configuration

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "indexing": true,
  • "signal_to_noise_threshold": 0.1,
  • "photon_count_threshold": 0,
  • "min_pix_per_spot": 1,
  • "max_pix_per_spot": 1,
  • "high_resolution_limit": 0.1,
  • "low_resolution_limit": 0.1,
  • "high_resolution_limit_for_spot_count_low_res": 2,
  • "quick_integration": false,
  • "ice_ring_width_q_recipA": 0.03,
  • "high_res_gap_Q_recipA": 1.5,
  • "adaptive_threshold": false,
  • "false_pixels_per_frame": 100
}

Configure azimuthal integration

Can be done when detector is Inactive or Idle

+
Request Body schema: application/json
polarization_corr
required
boolean
Default: true

Apply polarization correction for azimuthal integration (polarization factor must be configured in dataset settings)

+
solid_angle_corr
required
boolean
Default: true

Apply solid angle correction for azimuthal integration

+
high_q_recipA
number <float> [ 0.00002 .. 10 ]

Upper q limit of the azimuthal integration [1/Angstrom]. Optional: if omitted, the integration +(and the adaptive spot detection that shares these q bins) extends to the highest q the +detector reaches.

+
low_q_recipA
required
number <float> [ 0.00001 .. 10 ]
q_spacing
number <float> >= 0.00001

Width of a Q bin [1/Angstrom], for linear binning only. Linear binning takes either this or +q_bins, not both; with neither, the spacing is 0.01 1/Angstrom.

+
q_bins
integer <int64> [ 1 .. 65534 ]

Number of Q bins between low and high Q. Required for log10 binning; for linear binning +an alternative to q_spacing.

+
q_binning
string (q_binning)
Default: "linear"
Enum: "linear" "log10"

How the Q bins of azimuthal integration are laid out between low and high Q. +linear - equal steps in Q. +log10 - equal steps in log10(Q): fine bins at low Q, coarse at high Q. Needs q_bins.

+
azimuthal_bins
integer <int64> [ 1 .. 512 ]
Default: 1

Numer of azimuthal (phi) bins; 1 = standard 1D azimuthal integration

+
force_cpu
boolean
Default: false

Force CPU processing of azimuthal integration in the FPGA data acquisition workflow. +This allows to extend number of azimuthal integration bins, as well as to calculate standard deviation +of the azimuthal integration results.

+

Responses

Request samples

Content type
application/json
{
  • "polarization_corr": true,
  • "solid_angle_corr": true,
  • "high_q_recipA": 0.00002,
  • "low_q_recipA": 0.00001,
  • "q_spacing": 0.00001,
  • "q_bins": 1,
  • "q_binning": "linear",
  • "azimuthal_bins": 1,
  • "force_cpu": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get azimuthal integration configuration

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "polarization_corr": true,
  • "solid_angle_corr": true,
  • "high_q_recipA": 0.00002,
  • "low_q_recipA": 0.00001,
  • "q_spacing": 0.00001,
  • "q_bins": 1,
  • "q_binning": "linear",
  • "azimuthal_bins": 1,
  • "force_cpu": false
}

Load binary image for internal FPGA generator

Load image for internal FPGA generator. This can only happen in Idle state of the detector. +Requires binary blob with 16-bit integer numbers of size of detector in raw/converted coordinates +(depending on detector settings).

+
query Parameters
id
integer <int64> [ 0 .. 127 ]

Image id to upload

+
Request Body schema: application/octet-stream
string <binary>

Responses

Load TIFF image for internal FPGA generator

Load image for internal FPGA generator. This can only happen in Idle state of the detector. +Requires TIFF with 16-bit integer numbers of size of detector in raw/converted coordinates +(depending on detector settings).

+
query Parameters
id
integer [ 0 .. 127 ]

Image ID to upload

+
Request Body schema: image/tiff
string <binary>

Responses

Select detector

Jungfraujoch allows to control multiple detectors and/or region-of-interests. +The command allows to choose one detector from the list (ID has to be consistent with one provided by GET response). +Changing detector will set detector to Inactive state and will require reinitialization.

+
Request Body schema: application/json
id
required
integer <int64>

Responses

Request samples

Content type
application/json
{
  • "id": 1
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

List available detectors

Configured detectors that can be selected by used

+

Responses

Response samples

Content type
application/json
{
  • "detectors": [
    ],
  • "current_id": 0
}

Change rugnux live mode settings

This can only be done when detector is Idle, Error or Inactive states.

+
Request Body schema: application/json
enable
boolean
Default: false

Process DECTRIS rotation collections with rugnux live, and serial collections on the GPU after a pre-pass

+
reserved_cpus
integer <int64> >= 0
Default: 4

CPU threads left to the receiver and the image pusher while rugnux runs

+
deadline_s
number <double> >= 0
Default: 60

Fixed cutoff: this long after the last image the analysis is cut, and the collection ends +with what it has established (as POST /cancel after the last image does). 0 means no cutoff.

+
refine_solvent
boolean
Default: false

With a model: the refinement also builds the solvent - waters added at difference-map peaks and removed +where the maps no longer hold them, waters and ions relabelled (as rugnux --refine-solvent). +Reset to false by POST /initialize.

+
force_still
boolean
Default: false

Process DECTRIS rotation collections as stills, on the serial path (pre-pass, GPU analysis, stills merge), +as rugnux --force-still does. The written file keeps its goniometer. Reset to false by POST /initialize.

+

Responses

Request samples

Content type
application/json
{
  • "enable": false,
  • "reserved_cpus": 4,
  • "deadline_s": 60,
  • "refine_solvent": false,
  • "force_still": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get rugnux live mode settings and model status

Can be done anytime

+

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "reserved_cpus": 0,
  • "deadline_s": 0.1,
  • "refine_solvent": true,
  • "force_still": true,
  • "model_loaded": true,
  • "model_size_bytes": 0
}

Upload the model used by rugnux live mode

This can only be done when detector is Idle, Error or Inactive states. +The model (PDB or mmCIF, optionally gzipped; at most 64 MiB) is used for molecular replacement +and validation of every following rugnux live collection, until it is removed with +DELETE /config/rugnux/model or replaced by another upload.

+
Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Remove the model used by rugnux live mode

This can only be done when detector is Idle, Error or Inactive states.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get live rugnux processing status of the last collection

Can be done anytime

+
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "state": "Idle",
  • "placed_model": true,
  • "refined_model": true,
  • "anomalous_map": true,
  • "anomalous_signal": true,
  • "model": {
    },
  • "stills": {
    },
  • "shells_merge": "string",
  • "shells": [
    ],
  • "overall": {
    },
  • "frame_scales": [
    ],
  • "frame_ranges": [
    ],
  • "space_group": "string",
  • "d_min": 0.1,
  • "isa": 0.1,
  • "probe": "string",
  • "probe_s": 0.1,
  • "start_to_first_image_s": 0.1,
  • "message": "string",
  • "images_expected": 0,
  • "expected_collection_s": 0.1,
  • "images_received": 0,
  • "elapsed_s": 0.1,
  • "step_progress": 1,
  • "steps": [
    ],
  • "last_image_s": 0.1,
  • "cut": "string",
  • "cut_s": 0.1,
  • "last_image_to_written_s": 0.1,
  • "verdict": "string",
  • "verdict_text": "string",
  • "summary": [
    ],
  • "warnings": [
    ],
  • "triage": [
    ]
}

Clear the live rugnux result of the last collection

Puts /rugnux/status back to Idle with nothing of the last run - its merge, model, maps, steps and notes - +as before any collection. The collection's images, plots and the rugnux live settings are kept. +Can be only run when Jungfraujoch is not collecting data.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get the model as placed by the last rugnux live run

The model placed against the data by molecular replacement or validation, as mmCIF - the same text as the +_model.cif file written beside the data: the data's cell and space group, with the input model's own +metadata (entities, sequences, references, authors, software) kept. Kept as long as /rugnux/status. +Where the run refined the model, the refined model unless asked for stage=placed.

+
Authorizations:
bearerAuth
query Parameters
stage
string
Enum: "placed" "refined"

placed: the model as placed; refined: the model refined (refined_model in /rugnux/status). +Default: the refined model where there is one, otherwise the placed one.

+

Responses

Get an electron-density map of the last rugnux live run

The map of the placed model (/rugnux/model.cif) in CCP4 format (mode 2, float), made from the map +coefficients written to _maps.mtz (FWT/PHWT, DELFWT/PHDELWT, ANOM/PHANOM). It covers one unit cell centred on the model - along an axis where +the model reaches further than the cell, the model plus 5 A instead - sampled every d_min/3; the mean and +RMS in its header are those of the unit cell, so contour levels in sigma are the usual ones. Where the run +refined the model, the 2mFo-DFc and mFo-DFc maps are the refined model's unless asked for stage=placed; +the anomalous map stays on the placed model's phases.

+
Authorizations:
bearerAuth
query Parameters
type
string
Default: "2fofc"
Enum: "2fofc" "fofc" "anom"

2fofc: the 2mFo-DFc map; fofc: the mFo-DFc difference map; anom: the anomalous difference map, +(F(+) - F(-)) on the model phases less 90 degrees, where the merge kept the Bijvoet pairs (anomalous_map +in /rugnux/status)

+
stage
string
Enum: "placed" "refined"

placed: the model as placed; refined: the model refined (refined_model in /rugnux/status). +Default: the refined model where there is one, otherwise the placed one.

+

Responses

Set ZeroMQ preview settings

Jungfraujoch can generate preview message stream on ZeroMQ SUB socket. +Here settings of the socket can be adjusted. +While the data structure contains also socket_address, this cannot be changed via HTTP and is ignore in PUT request. +Options set with this PUT request have no effect on HTTP based preview.

+
Request Body schema: application/json
enabled
required
boolean
Default: true

ZeroMQ preview socket is enabled.

+
period_ms
required
integer <int64>
Default: 1000

Period for generating preview image sent to the ZeroMQ interface in milliseconds. Default is 1 second. +If set to zero, all images will be sent ZeroMQ (should be used only in case of relatively slow data collection). +This has no effect on HTTP based preview, which updates always at rate of 1 second.

+
socket_address
string

PUB ZeroMQ socket for preview images. This socket operates at a reduced frame rate. +Images are serialized using CBOR. +Address follows ZeroMQ convention for sockets - in practice ipc:// and tcp://: sockets are OK. +0.0.0.0 instead of IP address is accepted and means listening on all network interfaces.

+

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get ZeroMQ preview settings

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Set ZeroMQ metadata settings

Jungfraujoch can generate metadata message stream on ZeroMQ PUB socket. This stream covers all images. +Here settings of the socket can be adjusted. +While the data structure contains also socket_address, this cannot be changed via HTTP and is ignore in PUT request.

+
Request Body schema: application/json
enabled
required
boolean
Default: true

ZeroMQ metadata socket is enabled.

+
period_ms
required
integer <int64> >= 1
Default: 1000

Period for generating metadata package sent to the ZeroMQ interface in milliseconds.

+
socket_address
string

PUB ZeroMQ socket for image metadata information. +Image metadata are serialized using CBOR. +Address follows ZeroMQ convention for sockets - in practice ipc:// and tcp://: sockets are OK. +0.0.0.0 instead of IP address is accepted and means listening on all network interfaces.

+

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get ZeroMQ metadata socket settings

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Set configuration for dark data collection to calculate mask

This is only possible when operating DECTRIS detectors at the moment; it will be also available for PSI EIGER at some point. +This can only be done when detector is Idle, Error or Inactive states.

+
Request Body schema: application/json
detector_threshold_keV
required
number <float> [ 2.5 .. 100 ]
Default: 3.5

Energy threshold for dark image collection

+
frame_time_us
required
integer <int64> [ 500 .. 100000 ]
Default: 10000

Time between frames for dark image collection

+
number_of_frames
required
integer <int64> >= 0
Default: 1000

Number of frames for dark image collection; zero means no dark collection

+
max_allowed_pixel_count
required
integer <int64> >= 0
Default: 1

Maximum count in a pixel considered normal (not-masked)

+
max_frames_with_signal
required
integer <int64> >= 0
Default: 10

Maximum number of frames with signal in a pixel considered normal (not-masked)

+

Responses

Request samples

Content type
application/json
{
  • "detector_threshold_keV": 3.5,
  • "frame_time_us": 10000,
  • "number_of_frames": 1000,
  • "max_allowed_pixel_count": 1,
  • "max_frames_with_signal": 10
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get settings for dark data collection to calculate mask

Responses

Response samples

Content type
application/json
{
  • "detector_threshold_keV": 3.5,
  • "frame_time_us": 10000,
  • "number_of_frames": 1000,
  • "max_allowed_pixel_count": 1,
  • "max_frames_with_signal": 10
}

Get Jungfraujoch status

Status of the data acquisition

+

Responses

Response samples

Content type
application/json
{
  • "state": "Inactive",
  • "progress": 1,
  • "message": "string",
  • "message_severity": "success",
  • "gpu_count": 0,
  • "broker_version": "1.0.0-rc.128"
}

Get status of FPGA devices

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Return XFEL pulse IDs for the current data acquisition

Return array of XFEL pulse IDs - (-1) if image not recorded

+

Responses

Response samples

Content type
application/json
[
  • 0
]

Return XFEL event codes for the current data acquisition

Return array of XFEL event codes

+

Responses

Response samples

Content type
application/json
[
  • 0
]

Get status of image pusher

Responses

Response samples

Content type
application/json
{
  • "pusher_type": "ZeroMQ",
  • "addr": [
    ],
  • "connected_writers": 0,
  • "images_written": 0,
  • "images_write_error": 0,
  • "writer_fifo_utilization": [
    ]
}

Get detector status

Status of the JUNGFRAU detector

+

Responses

Response samples

Content type
application/json
{
  • "state": "Idle",
  • "powerchip": "PowerOn",
  • "server_version": "string",
  • "number_of_triggers_left": 0,
  • "fpga_temp_degC": [
    ],
  • "high_voltage_V": [
    ]
}

Get ROI definitions

Responses

Response samples

Content type
application/json
{
  • "box": {
    },
  • "circle": {
    },
  • "azim": {
    }
}

Upload ROI definitions

Request Body schema: application/json
required
object (roi_box_list)

List of box ROIs

+
required
object (roi_circle_list)

List of circular ROIs

+
required
object (roi_azim_list)

List of azimuthal ROIs

+

Responses

Request samples

Content type
application/json
{
  • "box": {
    },
  • "circle": {
    },
  • "azim": {
    }
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get general statistics

measurement is omitted unless the request carries a valid bearer token for a protected +dataset (see tokens in /start).

+

Responses

Response samples

Content type
application/json
{
  • "detector": {
    },
  • "detector_list": {
    },
  • "detector_settings": {
    },
  • "image_format_settings": {
    },
  • "instrument_metadata": {
    },
  • "file_writer_settings": {
    },
  • "data_processing_settings": {
    },
  • "measurement": {
    },
  • "broker": {
    },
  • "fpga": [
    ],
  • "calibration": [
    ],
  • "zeromq_preview": {
    },
  • "zeromq_metadata": {
    },
  • "dark_mask": {
    },
  • "pixel_mask": {
    },
  • "roi": {
    },
  • "az_int": {
    },
  • "buffer": {
    },
  • "indexing": {
    },
  • "bragg_integration": {
    },
  • "image_pusher": {
    }
}

Get data collection statistics

Results of the last data collection (dataset name, unit cell, ...)

+
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "file_prefix": "string",
  • "run_number": 0,
  • "experiment_group": "string",
  • "images_expected": 0,
  • "images_collected": 0,
  • "images_sent": 0,
  • "images_written": 0,
  • "images_discarded_lossy_compression": 0,
  • "max_image_number_sent": 0,
  • "collection_efficiency": 1,
  • "compression_ratio": 5.3,
  • "cancelled": true,
  • "max_receiver_delay": 0,
  • "indexing_rate": 0.1,
  • "detector_width": 0,
  • "detector_height": 0,
  • "detector_pixel_depth": 2,
  • "bkg_estimate": 0.1,
  • "unit_cell": "string",
  • "error_pixels": 0.1,
  • "saturated_pixels": 0.1,
  • "roi_beam_pixels": 0.1,
  • "roi_beam_sum": 0.1
}

Get calibration statistics

Statistics are provided for each module/storage cell separately

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get mask of the detector (binary)

Detector must be Initialized. +Get full pixel mask of the detector. +See NXmx standard for meaning of pixel values.

+

Responses

Detector must be Initialized. +Get user mask of the detector (binary) +

Get user pixel mask of the detector in the actual detector coordinates: 0 - good pixel, 1 - masked

+

Responses

Upload user mask of the detector (binary)

Should be in Idle state. +Upload user mask of the detector - this is for example to account for beam stop shadow or misbehaving regions. +If detector is conversion mode the mask can be both in raw (1024x512; stacked modules) or converted coordinates. +In the latter case - module gaps are ignored and don't need to be assigned value. +Mask is expected as binary array (4-byte; unsigned). +0 - good pixel, other value - masked +User mask is stored in NXmx pixel mask (bit 8), as well as used in spot finding and azimuthal integration.

+
Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get mask of the detector (TIFF)

Should be in Idle state. +Get full pixel mask of the detector +See NXmx standard for meaning of pixel values

+

Responses

Detector must be Initialized. +Get user mask of the detector (TIFF) +

Get user pixel mask of the detector in the actual detector coordinates: 0 - good pixel, 1 - masked

+

Responses

Upload user mask of the detector

Should be in Idle state. +Upload user mask of the detector - this is for example to account for beam stop shadow or misbehaving regions. +If detector is conversion mode the mask can be both in raw (1024x512; stacked modules) or converted coordinates. +In the latter case - module gaps are ignored and don't need to be assigned value. +Mask is expected as a single-channel TIFF (8-, 16- or 32-bit integer, signed or unsigned). +0 - good pixel, other value - masked +User mask is stored in NXmx pixel mask (bit 8), as well as used in spot finding and azimuthal integration. +User mask is not automatically applied - i.e. pixels with user mask will have a valid pixel value in the images.

+
Request Body schema: image/tiff
string <binary>

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get pedestal in TIFF format

query Parameters
gain_level
required
integer

Gain level (0, 1, 2)

+
sc
integer

Storage cell number

+

Responses

Generate 1D plot from Jungfraujoch

Authorizations:
bearerAuth
query Parameters
binning
integer
Default: 1

Binning of frames for the plot (0 = default binning)

+
type
required
string
Enum: "bkg_estimate" "spindle_blind_fraction" "azint" "azint_1d" "spot_count" "spot_count_low_res" "spot_count_indexed" "spot_count_ice" "indexing_rate" "indexing_lattice_count" "indexing_unit_cell_length" "indexing_unit_cell_angle" "profile_radius" "mosaicity" "b_factor" "error_pixels" "saturated_pixels" "image_collection_efficiency" "receiver_delay" "receiver_free_send_buf" "strong_pixels" "roi_sum" "roi_mean" "roi_max_count" "roi_pixels" "roi_weighted_x" "roi_weighted_y" "packets_received" "max_pixel_value" "resolution_estimate" "pixel_sum" "processing_time" "beam_center_x" "beam_center_y" "integrated_reflections" "image_scale_factor" "image_scale_cc" "compression_ratio" "ice_ring_score"

Type of requested plot

+
fill
number <float>

Fill value for elements that were missed during data collection

+
experimental_coord
boolean
Default: false

If measurement has goniometer axis defined, plot X-axis will represent rotation angle +If measurement has grid scan defined, plot X-axis and Y-axis will represent grid position, Z will be used as the final value +For still measurement the number is ignored

+
azint_unit
string
Default: "Q_recipA"
Enum: "Q_recipA" "d_A" "two_theta_deg"

Unit used for azim int.

+

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "unit_x": "image_number",
  • "size_x": 0.1,
  • "size_y": 0.1,
  • "plot": [
    ]
}

Generate 1D plot from Jungfraujoch and send in raw binary format. +Data are provided as (32-bit) float binary array. +This format doesn't transmit information about X-axis, only values, so it is of limited use for azimuthal integration. +

Authorizations:
bearerAuth
query Parameters
type
required
string
Enum: "bkg_estimate" "spindle_blind_fraction" "azint" "azint_1d" "spot_count" "spot_count_low_res" "spot_count_indexed" "spot_count_ice" "indexing_rate" "indexing_lattice_count" "indexing_unit_cell_length" "indexing_unit_cell_angle" "profile_radius" "mosaicity" "b_factor" "error_pixels" "saturated_pixels" "image_collection_efficiency" "receiver_delay" "receiver_free_send_buf" "strong_pixels" "roi_sum" "roi_mean" "roi_max_count" "roi_pixels" "roi_weighted_x" "roi_weighted_y" "packets_received" "max_pixel_value" "resolution_estimate" "pixel_sum" "processing_time" "beam_center_x" "beam_center_y" "integrated_reflections" "image_scale_factor" "image_scale_cc" "compression_ratio" "ice_ring_score"

Type of requested plot

+
roi
string non-empty

Name of ROI for which plot is requested

+

Responses

Get full scan result

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "file_prefix": "string",
  • "rotation_unit_cell": {
    },
  • "rotation_crystal_lattice": [
    ],
  • "rotation_bravais": "string",
  • "images": [
    ]
}

Get Start message in CBOR format

Contains metadata for a dataset (e.g., experimental geometry)

+
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Event stream of the collection, for a reader following it

Server-sent events (text/event-stream) for the current collection, from the moment /start has +accepted it: first its whole history, then every change, until it ends or a new collection +begins. Only one reader at a time. Events, each with a JSON data line:

+
    +
  • start {run_number, run_name, file_prefix, number_of_images, images_per_file, cbor} - first, +once the start message is known: at once for a JUNGFRAU, when the detector sends its own for +a DECTRIS. cbor is the start message the writer of the master file received, CBOR in base64; +a reader builds the dataset from it;
  • +
  • file {file_number, file, first_image, image_count} - a data file closed and renamed into +place; file is relative to the collection's root, as the writer named it;
  • +
  • end {images, error?} - every writer acknowledged the end: the data files and the master +file are in place; images is the number of images collected. Also sent, with error, when +the measurement ends any other way - before the start message, for one. The stream then closes;
  • +
  • superseded {run_number} - a new collection began. The stream then closes. +A comment line (: keepalive) every 10 s when nothing happens.
  • +
+
Authorizations:
bearerAuth

Responses

Get image message in CBOR format

Contains full image data and metadata. The image must come from the latest data collection.

+
Authorizations:
bearerAuth
query Parameters
id
integer <int64> >= -2
Default: -1

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get preview image in JPEG format using custom settings

Authorizations:
bearerAuth
query Parameters
id
integer <int64> >= -2
Default: -1

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

+
show_user_mask
boolean
Default: false

Show user mask

+
show_roi
boolean
Default: false

Show ROI areas on the image

+
show_spots
boolean
Default: true

Show spot finding results on the image

+
show_predictions
boolean
Default: false

Show Bragg spot predictions on the image (if available for the image)

+
show_beam_center
boolean
Default: true

Show beam center on the image

+
saturation
number <float> [ -32767 .. 32767 ]

Saturation value to set contrast in the preview image; if not provided, then autocontrast procedure is used

+
jpeg_quality
integer <int64> [ 0 .. 100 ]
Default: 100

Quality of JPEG image (100 - highest; 0 - lowest)

+
show_res_ring
number <float> [ 0.1 .. 100 ]
Default: 0.1

Show resolution ring, provided in Angstrom

+
color
string
Default: "indigo"
Enum: "indigo" "viridis" "bw" "wb" "green" "heat" "magma" "inferno"

Color scale for preview image

+
show_res_est
boolean
Default: false

Show resolution estimation as a ring

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get preview image in TIFF format

Authorizations:
bearerAuth
query Parameters
id
integer <int64> >= -2
Default: -1

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

+

Responses

Clear image buffer

Turns off image buffer for the last data collection. Can be only run when Jungfraujoch is not collecting data.

+

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get status of the image buffers

Can be run at any stage of Jungfraujoch operation, including during data collection. +The status of the image buffer is volatile during data collection - if data collection goes for more images than available buffer slots, +then image might be replaced in the buffer between calling /images and /image.cbor.

+

Responses

Response samples

Content type
application/json
{
  • "min_image_number": 0,
  • "max_image_number": 0,
  • "image_numbers": [
    ],
  • "total_slots": 0,
  • "available_slots": 0,
  • "in_preparation_slots": 0,
  • "in_sending_slots": 0,
  • "current_counter": 0
}

Get Jungfraujoch version of jfjoch_broker

Responses