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 1, 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.
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; CoMx, CoMy, 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 det_bin, scan_bin, and an optional
half-open crop row_start, row_stop, column_start, column_stop. The plan is
checked before any residency change: det_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 (cx, cy, radii, and the fitted
bright-field disk) is in binned detector pixels; sx and sy are in binned,
cropped scan positions. 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.