HealFormer Nside=1024 DECaLS projection checkpoint
This is the public high-resolution checkpoint for HealFormer (Mask-Aware
HEALPix Transformer). It reconstructs weak-lensing convergence (kappa)
directly on a NESTED HEALPix sphere from noisy, incomplete shear maps.
Source code · Dataset · Executable notebook · Paper · arXiv
Model overview
HealFormer uses spatially contiguous HEALPix patches, explicit mask/edge labels,
and learned mask tokens to retain survey-boundary information without a planar
projection. This checkpoint uses the learned positional projection required
by the released Nside=1024 workflow. Positional interpolation is disabled.
| Property | Value |
|---|---|
| Resolution | Nside=1024 (12,582,912 pixels) |
| Input | Physical gamma1, gamma2, and integer mask_npix |
| Output | One physical convergence (kappa) map |
| Ordering | HEALPix NESTED |
| Patch size | 16 pixels |
| Encoder | 12 layers, hidden size 768, 12 attention heads |
| Decoder | 8 layers, hidden size 512, 16 attention heads |
| Position embedding | Learned projection; interpolation disabled |
| Released evaluation | One fixed DECaLS-labeled footprint; map rotation disabled |
mask_npix uses 0 = visible, 1 = reconstruction edge, and
2 = unseen/excluded. The repository contains complete weights under the
standard filenames config.json and model.safetensors; it does not contain
LoRA/adapter tensors.
Quickstart
Install the inference package:
python -m pip install "healformers>=0.2,<0.3"
Run the checksummed public representative sample:
from healformers import get_public_release
release = get_public_release(1024)
artifacts = release.download_evaluation_artifacts(include_ensemble=False)
sample = release.load_representative_sample(artifacts.representative_sample)
pipeline = release.load_pipeline(device="cuda")
kappa = pipeline(*sample.shear, sample.mask_npix)[0, 0]
print(kappa.shape) # (12582912,)
Use device="cpu" when a GPU is unavailable. get_public_release(1024) pins
the model and dataset revisions, verifies SHA-256 digests, and rejects an
interpolation checkpoint, a rotated map, or any mask other than the released
fixed footprint. For custom inputs, follow the
inference example.
100-sample fixed-mask diagnostics
The released evaluation contains 100 validation skies using the fixed DECaLS-labeled footprint:
| Metric | Ensemble mean ± sample standard deviation |
|---|---|
| Power-ratio RMSE around one | 0.0884 ± 0.0179 |
| Mean harmonic cross correlation | 0.9622 ± 0.0010 |
The uncertainty is sky-to-sky sample variation, not uncertainty on the mean.
The executable notebook renders these arrays alongside the four Nside=256
fixed-mask cases and compares HealFormer with spherical Kaiser--Squires.
DECaLS label note: the footprint labeled “DECaLS” in the paper and released artifacts is the combined DECaLS+DES footprint. This is a label-recording offset; the stored mask, calculations, method, and conclusions are unchanged.
Intended use and limitations
This checkpoint is intended for research on simulated spherical weak-lensing
mass mapping at Nside=1024 under the released fixed-footprint, preprocessing,
and physical-unit conventions. It has not been validated as a drop-in estimator
for real survey catalogs, survey-specific calibration systematics, spatially
varying noise, arbitrary masks, or rotated footprints. It does not provide
posterior uncertainty or cosmological-parameter inference.
Inference at this resolution is memory intensive. Validate new noise models, smoothing scales, orderings, and map conventions before scientific use.
Files and integrity
release-manifest.json records the byte size and SHA-256 digest of every
release file. The companion dataset repository contains the fixed footprint,
representative inference sample, and raw 100-sample harmonic arrays.
Citation
@article{wang2026advancing,
title={Advancing weak lensing mass mapping with a mask-aware HEALPix transformer},
author={Wang, Yihe and Yu, Yu},
journal={Physical Review D},
volume={113},
number={4},
pages={043553},
year={2026},
publisher={APS},
doi={10.1103/kc9z-jllp}
}
The model files are released under Apache-2.0.