Reference bundle#
squidpy’s test_stalign_reference.py
compares the port against numbers upstream STalign computed. Those numbers are generated here, once,
and published as one file: stalign_reference.zarr.zip, a release asset that squidpy downloads and
checks against a pinned sha256.
Why the outputs are stored rather than recomputed#
Upstream can’t be a squidpy test dependency. It is GPL-3.0, runs on PyTorch, and pins
numpy==1.23.4/torch==2.0.0, which have no wheels for current Pythons. It is vendored here at a fixed commit and never installed.The outputs never change unless the inputs do. Upstream is pinned and the inputs are seeded, so every run produces the same numbers. Recomputing them in every squidpy CI job would cost torch, the vendored checkout and a minute of CPU, and add nothing.
They’re generated on one platform. BLAS/FFT reduction order differs between macOS Accelerate and Linux OpenBLAS, so the bundle is generated once on ubuntu, the platform squidpy’s CI compares on, and the workflow checks that a second run gives identical arrays.
The intermediate values say where a disagreement starts. A port can match at the end and differ along the way, or differ at the end because of one early step. Storing every stage (rasterisation, energy, gradients, a few iterations, the converged fit) means a failing test points at the stage that broke, not only at a wrong final affine.
One file, pinned by hash. An AnnData in a zipped zarr store is one download, can’t change silently, holds the provenance next to the numbers, and reads with
anndata.read_zarr, which squidpy already depends on.
The inputs are synthetic and seeded (src/squidpy_ports/stalign/fixtures.py); no upstream data is
redistributed.
What it holds#
It is an empty AnnData whose uns holds everything. uns["fixtures"] has every parameter the
sections were generated with (SEED, RASTER_PARAMS, LDDMM_PARAMS, IMAGE_PARAMS,
SLICE_PARAMS, the iteration counts, MIXED_TARGET_STEP) and the checksum of fixtures.py, so
squidpy’s tests read them rather than keep their own copy. Every other uns entry is one section, a dict of arrays, and carries a
provenance entry: upstream commit, squidpy-ports commit, torch / numpy / Python versions,
platform and timestamp.
|
What upstream computed |
What it pins in squidpy |
|---|---|---|
|
The point clouds and landmarks, rasters and their axes, interpolation inside and outside the domain, the regulariser, the backward grid, point transforms, affines from well- and ill-conditioned landmarks |
Each building block on its own, at ~1e-12 |
|
The objective at iteration 0, with and without landmarks, for |
|
|
|
The gradients the descent follows |
|
The state after 1, 5 and 50 iterations |
That the loop matches step by step; 50 is past the first mixture-weight update at iteration 50 |
|
A full 500-iteration run, with target registration error |
That a converged fit lands where upstream’s does |
|
The image path on two differently shaped rasters, its energy trace and the warped image |
|
|
The same images sampled exactly on grid lines |
The pinned cost of on-grid sampling |
|
A source and target in different units |
The velocity grid upstream builds for mixed units |
|
Section-into-volume ( |
The rank-3 solver and |
Regenerating#
Regenerate when the upstream pin, fixtures.py or the solver settings in generate.py change. Run the Generate reference bundle
workflow and publish its artifact as a new release:
gh workflow run generate.yaml -R theislab/squidpy-ports
gh run download <run-id> -R theislab/squidpy-ports -n stalign-reference-bundle
gh release create stalign-reference-vN stalign_reference.zarr.zip -R theislab/squidpy-ports \
--notes "Generated by run <run-id>."
Then point squidpy’s _BUNDLE_URL and _BUNDLE_SHA256 at the new asset and the hash the workflow
prints. The workflow’s commands, which install from uv.lock, write the same store locally, but
don’t publish a local build.