API docs by Redocly

Jungfraujoch (1.0.0-rc.95)

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.

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. Doesn't run calibration procedure. When the function returns, detector is ready to accept soft/TTL triggers.

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> >= 0
Default: 1000

Number of files in a single HDF5 data file (0 = write all images to a single data file).

space_group_number
integer <int64> [ 1 .. 194 ]

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" "none"

Compression type for the images transferred over ZeroMQ and saved to HDF5 file.

total_flux
number <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]

transmission
number <float> [ 0 .. 1 ]

/entry/instrument/attenuator/attenuator_transmission Transmission of attenuator (filter) [no units]

object (rotation_axis)

Definition of a crystal rotation axis

object (grid_scan)

Definition of a grid scan (mutually exclusive with rotation_axis)

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/data 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

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

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": 1000,
  • "space_group_number": 1,
  • "sample_name": "",
  • "compression": "bslz4",
  • "total_flux": 0.1,
  • "transmission": 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,
  • "max_spot_count": 250,
  • "detect_ice_rings": true,
  • "xray_fluorescence_spectrum": {
    }
}

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.

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 EIGER detector. 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 EIGER read-out. If value is not provided bit depth is adjusted automatically based on the image time.

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

Highest resolution of spots used for FFT algorithm; parameter value affects execution time of FFT. There is also correlation between smallest unit cell and max resolution, 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" "None"

Selection of an post-indexing detector geometry refinement algorithm used by Jungfraujoch. This option is using non-linear least squares optimization to find unit cell and beam center.

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.

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
}

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
}

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: "NXmxLegacy"
Enum: "None" "NXmxLegacy" "NXmxVDS" "CBF" "TIFF" "NoFileWritten"

None - no master file written 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

Responses

Request samples

Content type
application/json
{
  • "overwrite": false,
  • "format": "None"
}

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": "None"
}

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
required
number <float>

High resolution limit for spot finding [Angstrom]

low_resolution_limit
required
number <float>

Low resolution limit for spot finding [Angstrom]

high_resolution_limit_for_spot_count_low_res
required
number <float> [ 2 .. 8 ]

High resolution threshold to consider spot "low resolution" [Angstrom]

quick_integration
required
boolean
Default: false

Quick integration of Bragg spots in diffraction images. If enabled it will likely reduce performance of Jungfraujoch for datasets with a very high indexing rate. (experimental feature)

ice_ring_width_q_recipA
required
number <float> [ 0 .. 1 ]
Default: 0.02

Width of ice ring in q-space in reciprocal space

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.

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.02,
  • "high_res_gap_Q_recipA": 1.5
}

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.02,
  • "high_res_gap_Q_recipA": 1.5
}

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
required
number <float>
low_q_recipA
required
number <float>
q_spacing
required
number <float>
azimuthal_bins
integer <int64> [ 1 .. 256 ]
Default: 1

Numer of azimuthal (phi) bins; 1 = standard 1D azimuthal integration

Responses

Request samples

Content type
application/json
{
  • "polarization_corr": true,
  • "solid_angle_corr": true,
  • "high_q_recipA": 0.1,
  • "low_q_recipA": 0.1,
  • "q_spacing": 0.1,
  • "azimuthal_bins": 1
}

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.1,
  • "low_q_recipA": 0.1,
  • "q_spacing": 0.1,
  • "azimuthal_bins": 1
}

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
}

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"
}

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
}

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

query Parameters
compression
boolean
Default: false

Enable DEFLATE compression of output data.

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": {
    },
  • "pixel_mask": {
    },
  • "roi": {
    },
  • "az_int": {
    },
  • "buffer": {
    },
  • "indexing": {
    }
}

Get data collection statistics

Results of the last data collection

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_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 TIFF (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. 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

query Parameters
binning
integer

Binning of frames for the plot (0 = default binning)

compression
boolean
Default: false

Enable DEFLATE compression of output data.

type
required
string
Enum: "bkg_estimate" "azint" "azint_1d" "spot_count" "spot_count_low_res" "spot_count_indexed" "spot_count_ice" "indexing_rate" "indexing_time" "indexing_unit_cell_length" "indexing_unit_cell_angle" "profile_radius" "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"

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": [
    ]
}

Get full scan result

Responses

Response samples

Content type
application/json
{
  • "file_prefix": "string",
  • "images": [
    ]
}

Get Start message in CBOR format

Contains metadata for a dataset (e.g., experimental geometry)

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get image message in CBOR format

Contains full image data and metadata. The image must come from the latest data collection.

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

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_beam_center
boolean
Default: true

Show beam center on the image

saturation
number <float> [ -32767 .. 32767 ]
Default: 10

Saturation value to set contrast in the preview image

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" "heat"

Color scale for preview image: 0 - indigo, 1 - viridis, 2 - B/W, 3 - heat

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get preview image in TIFF format

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
}

Get Jungfraujoch version of jfjoch_broker

Responses