# Reference bundle

squidpy's [`test_stalign_reference.py`](https://github.com/scverse/squidpy/blob/main/tests/experimental/tl/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.

| `uns` entry | What upstream computed | What it pins in squidpy |
| --- | --- | --- |
| `primitives` | 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 |
| `energy` | The objective at iteration 0, with and without landmarks, for `nt=1` and `nt=3`, at zero and at a warm velocity | `_lddmm_loss` evaluates the same function |
| `gradients` | `dE/dL`, `dE/dT` and the smoothed `dE/dv`, at zero and at a warm velocity | The gradients the descent follows |
| `trajectory_n1`, `_n5`, `_n50` | 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 |
| `converged_n500` | A full 500-iteration run, with target registration error | That a converged fit lands where upstream's does |
| `image_trajectory` | The image path on two differently shaped rasters, its energy trace and the warped image | `fit_stalign_image`, `warp_image` and the public `stalign_align_image` |
| `image_trajectory_matched` | The same images sampled exactly on grid lines | The pinned cost of on-grid sampling |
| `image_mixed_units` | A source and target in different units | The velocity grid upstream builds for mixed units |
| `slice_trajectory` | Section-into-volume (`LDDMM_3D_to_slice`): interpolation, regulariser over two and three axes, trajectory and transforms | The rank-3 solver and `sample_volume`, plus the strict xfail on the rank-3 divergence |

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

```bash
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.
