Protocol and integration#
The service implementation lives in src/quantem/gpu/remote. It composes the
public IO, detector, and DPC functions rather than duplicating their kernels.
Implementation map#
Layer |
Source |
Responsibility |
|---|---|---|
CLI entry |
|
parse |
HTTP application |
|
versioned routes, payload headers, lifecycle |
browse service |
|
capabilities, request plans, exact products |
catalog |
|
session folders, master discovery, readiness |
residency |
|
GPU pool, admission, placement, eviction |
bin and crop plan |
|
binned and cropped views of one resident |
saved SSB phases |
|
acquisition-verified saved phase transfer |
transport tests |
|
routes, headers, errors, admission, lifecycle, dense parity |
Version negotiation#
The capabilities route reports protocol name quantem-gpu-browse, protocol
version 2, backend/device information, feature capabilities, per-device
admission telemetry, and implementation_revision. Clients must validate this
response before assuming an endpoint or field exists. New optional response
fields are additive; changed scientific meaning requires a protocol version
change.
Every route refuses a query parameter it does not declare with HTTP 400. The
message names the unknown parameters, the protocol version and the parameters
the route takes, so a client that still sends the names of an earlier version
(sx, cx, det_bin, inner) is told so, not answered with the image of
the default scan position or mask.
Endpoints#
Route |
Contract |
|---|---|
|
protocol, GPU pool, live admission capacity, features |
|
catalog of session folders and their masters |
|
acquisitions being written and ready, with a change token |
|
BF, ABF, ADF, HAADF, DF exact count images; CoMrow, CoMcol, CoMmag, DPC, iCoM |
|
exact counts inside a circle, square, or annulus detector |
|
exact diffraction pattern at one scan position |
|
saved SSB phases verified against the acquisition identity |
Binary 2D images use application/octet-stream with width, height, and dtype
headers. Integer count images are encoded as little-endian unsigned 32-bit
values after an overflow check; clients must not infer native counts from
display-scaled data.
Bins and crops#
Every product request carries the plan detector_bin, scan_bin, and an optional
half-open crop row_start, row_stop, col_start, col_stop. The plan is
checked before any residency change: detector_bin must divide both detector sizes,
scan_bin is 1, 2, 4, 8, or 16, and the crop must lie inside the scan. A
rejected plan returns 400 and leaves the resident acquisition untouched.
All plans of one acquisition read the same encoded resident, so changing bin
or crop never reloads it. Binning adds exact integer counts. Scan bins keep the
partial bins at the bottom and right edges of the crop, where the missing
positions count as zero. Detector geometry (center_row_px, center_col_px,
inner_radius_px, outer_radius_px, and the fitted bright-field disk) is in
binned detector pixels; /api/browse/realspace takes its ring as
inner_bright_field_fraction and outer_bright_field_fraction of the fitted
bright-field radius. scan_row and scan_col of /api/browse/cbed are in
binned, cropped scan positions. Protocol version 2 introduced these names. Centre-of-mass products divide exact
integer moments in binned detector coordinates by the exact total count. These
products equal, value for value, the products of a dense volume binned and
cropped the same way (tests/contracts/remote/test_browse_plans.py).
Client integration contract#
A client persists the scan and detector regions, scan and detector bins, output
shapes and dtypes, backend/device, and implementation revision with every
derived product. It uses (row, column) ≡ (r, c) for all public coordinates.
The service may add scheduling, cache reuse, or a faster kernel without changing this contract. It may not silently alter coverage, detector geometry, precision, masks, calibration, or reconstruction parameters.