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:

python

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

bibtex

@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.

lalala404/healformer-nside1024-decals

HealFormer Nside=1024 DECaLS projection checkpoint