Healpy

Warnings

• breaking The `blm_gauss()` function in version 1.19.0 was updated to use the `l(l+1)` formula, aligning with `gauss_beam()` and standard definitions. Previously, it used the `l^2` formula. This changes the computed spherical harmonic coefficients for Gaussian beams.
  Fix: If relying on precise `blm_gauss()` values, re-evaluate results or adjust calculations based on the new formula. Consider if older versions should be used for backward compatibility with previous computations.
• gotcha Healpy officially supports Linux and macOS. While Windows is supported through the Windows Subsystem for Linux (WSL), native Windows builds are not supported and may lead to installation or runtime issues.
  Fix: For Windows users, use WSL for a supported environment. Alternatively, consider using `conda` for pre-compiled binaries which often simplify installation on various platforms.
• gotcha When installing from source, especially if external HEALPix C++ or `cfitsio` libraries are detected, compilation might fail if OpenMP is used by the external library but not supported by your C/C++ compiler (e.g., clang). Conflicts with `cfitsio` from HEASOFT due to a `rotmatrix.h` header clash are also known.
  Fix: If OpenMP compilation fails, try `python setup.py clean --all` and set `CC` and `CXX` environment variables to an OpenMP-capable compiler (e.g., `gcc`/`g++`). For `cfitsio` conflicts, ensure you are not using the HEASOFT provided `cfitsio` or compile `healpy` with its bundled `cfitsio` (default behavior if `pkg-config` doesn't find external ones).
• deprecated Starting from `healpy` 1.15.0, the `logging` module is used for messages instead of `warnings`. All `verbose` keywords in functions are deprecated and will be removed in future versions.
  Fix: Configure logging via `import logging; log = logging.getLogger('healpy'); log.setLevel(logging.DEBUG)` for detailed messages. Remove `verbose=True` or similar keyword arguments from function calls.
• gotcha Healpy maps typically use the `hp.UNSEEN` constant (`-1.6375e+30`) to mark invalid or unseen pixels. While most `healpy` functions handle this automatically, directly working with `numpy.ma.MaskedArray` via `hp.ma` requires flipping the mask convention (NumPy's `True` means masked, `healpy`'s mask derived from `UNSEEN` might be `0` for masked).
  Fix: Be mindful of mask conventions when converting between `healpy`'s internal representation and `numpy.ma.MaskedArray`. If `hp.ma` is used, explicitly flip the mask if necessary: `masked_array.mask = ~unseen_mask` or similar, depending on how `unseen_mask` is generated.

Install

• pip install healpy Pip
• conda install -c conda-forge healpy Conda

Imports

• healpy

  import healpy as hp

  Standard alias for convenience.
• mollview

  hp.mollview(map_data)

  Most visualization functions are commonly accessed via the `hp` alias. Ensure `matplotlib.pyplot` is also imported for displaying plots.

Quickstart

This quickstart demonstrates how to create a basic HEALPix map using a NumPy array and visualize it with `healpy.mollview()`. It sets up a map at a given `NSIDE` resolution, populates it with pixel indices, and then displays it with coordinate graticules.

import numpy as np
import healpy as hp
import matplotlib.pyplot as plt

# Define the resolution parameter NSIDE (must be a power of 2)
NSIDE = 32

# Calculate the number of pixels
NPIX = hp.nside2npix(NSIDE)
print(f"Number of pixels for NSIDE={NSIDE}: {NPIX}")

# Create a simple map (e.g., an array with pixel indices)
m = np.arange(NPIX, dtype=float)

# Visualize the map using Mollweide projection
hp.mollview(m, title="Simple Healpix Map (RING ordering)")
hp.graticule() # Add meridians and parallels
plt.show()