Jungfraujoch/docs/TOOLS.md

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 with -h or without arguments.

Data analysis

jfjoch_process

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. See jfjoch_process.

jfjoch_scale

Re-scales and merges the already-integrated reflections from one or more _process.h5 files (no re-integration). Useful to re-merge with a different space group, partiality, resolution limit or reference MTZ, or to combine several runs. See jfjoch_process.

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.

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 — indexing, integration 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_azint

Runs CPU azimuthal integration on an existing Jungfraujoch HDF5 file using N threads and writes the result to <prefix>_process.h5. Example:

./jfjoch_azint -o output -N 8 input.h5

The integration settings and geometry default to the values stored in the input file; any of them can be overridden on the command line:

jfjoch_azint {<options>} <input.h5>
   -o, --output-prefix <txt>           Output file prefix (default: output)
   -N, --threads <num>                 Number of threads (default: 1)
   -s, --start-image <num>             Start image number (default: 0)
   -e, --end-image <num>               End image number (default: all)
   -t, --stride <num>                  Image stride (default: 1)
   -v, --verbose                       Verbose output

  Azimuthal integration:
   --min-q <num>                       Minimum Q for integration (1/A)
   --max-q <num>                       Maximum Q for integration (1/A)
   --q-spacing <num>                   Q bin spacing (1/A)
   --azimuthal-bins <num>              Number of azimuthal bins (default: 1)
   --polarization-correction <on|off>  Enable/disable polarization correction
   --solid-angle-correction <on|off>   Enable/disable solid angle correction

  Geometry overrides:
   --beam-x <num>                      Beam center X (pixel)
   --beam-y <num>                      Beam center Y (pixel)
   --detector-distance <num>           Detector distance (mm)
   --wavelength <num>                  Wavelength (A)
   --rot1 <num>                        PONI rotation 1 (rad)
   --rot2 <num>                        PONI rotation 2 (rad)
   --polarization <num>                Polarization factor