# 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 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_PROCESS.md).

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

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