healformer-nside256-mixed

HealFormer Nside=256 mixed-mask checkpoint

This is the public Nside=256 checkpoint for HealFormer (Mask-Aware HEALPix Transformer), a spherical transformer that reconstructs weak-lensing convergence (kappa) from noisy, incomplete shear maps. One checkpoint is used unchanged with the fixed KiDS, DES, DECaLS-labeled, and Planck footprints.

Source code · Dataset · Executable notebook · Paper · arXiv

Model overview

HealFormer works directly on NESTED HEALPix maps instead of projecting the sphere onto a plane. It divides the map into spatially contiguous HEALPix patches and uses explicit mask/edge labels plus learned mask tokens to retain survey-boundary information during reconstruction.

mask_npix uses 0 = visible, 1 = reconstruction edge, and 2 = unseen/excluded. The public repository uses the standard filenames config.json and model.safetensors; it contains complete weights rather than 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(256)
artifacts = release.download_evaluation_artifacts(include_ensemble=False)
sample = release.load_representative_sample(artifacts.representative_sample)
pipeline = release.load_pipeline(device="cpu")

kappa = pipeline(*sample.shear, sample.mask_npix)[0, 0]
print(kappa.shape)  # (786432,)

get_public_release(256) pins the model and dataset revisions, verifies SHA-256 digests, and validates the mask/no-rotation contract before inference. For custom arrays, follow the inference example.

100-sample fixed-mask diagnostics

The released evaluation uses 100 validation skies for every fixed footprint. Power error is the per-sky RMSE of C_ell(pred) / C_ell(true) around one. Cross correlation is the mean C_ell(true,pred) / sqrt(C_ell(true) C_ell(pred)). Values are the ensemble mean and one sample standard deviation, not standard errors.

The notebook linked above reproduces representative residual/hist2d figures and renders the checksummed 100-sample power-ratio and cross-correlation bands for HealFormer and 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=256, using the released preprocessing and physical-unit conventions. It has not been validated as a drop-in estimator for real survey catalogs, survey-specific calibration systematics, or spatially varying noise. It does not provide posterior uncertainty or cosmological-parameter inference.

New masks, noise models, smoothing scales, orderings, or map conventions should be validated before scientific use. The published benchmark uses fixed masks; it does not claim rotation invariance.

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 masks, representative inference samples, 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.