Jungfraujoch/docs/TOOLS.md

# Tools

Besides the main services ([`jfjoch_broker`](JFJOCH_BROKER.md),
[`jfjoch_writer`](JFJOCH_WRITER.md), [`jfjoch_viewer`](JFJOCH_VIEWER.md)), 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.md).

`rugnux` installs on its own, as the `rugnux` package or as a standalone archive — see
[Installing Rugnux](RUGNUX_INSTALL.md).

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