{"id":6374,"library":"healpy","title":"Healpy","description":"Healpy is a Python package, currently at version 1.19.0, designed to handle pixelated data on the sphere. It is based on the Hierarchical Equal Area isoLatitude Pixelization (HEALPix) scheme and bundles the HEALPix C++ library. Primarily used in astrophysics and cosmology, Healpy provides tools for map manipulation, spherical harmonic transforms, and visualization of all-sky data.","status":"active","version":"1.19.0","language":"en","source_language":"en","source_url":"https://github.com/healpy/healpy","tags":["astronomy","cosmology","HEALPix","spherical geometry","data visualization","scientific computing"],"install":[{"cmd":"pip install healpy","lang":"bash","label":"Pip"},{"cmd":"conda install -c conda-forge healpy","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Core numerical operations and map representation (tested with >=1.19).","package":"numpy","optional":false},{"reason":"Required for visualization functions (optional since 1.17.0).","package":"matplotlib","optional":true},{"reason":"Required for some advanced functions (optional since 1.17.0).","package":"scipy","optional":true}],"imports":[{"note":"Standard alias for convenience.","symbol":"healpy","correct":"import healpy as hp"},{"note":"Most visualization functions are commonly accessed via the `hp` alias. Ensure `matplotlib.pyplot` is also imported for displaying plots.","wrong":"healpy.mollview() without alias","symbol":"mollview","correct":"hp.mollview(map_data)"}],"quickstart":{"code":"import numpy as np\nimport healpy as hp\nimport matplotlib.pyplot as plt\n\n# Define the resolution parameter NSIDE (must be a power of 2)\nNSIDE = 32\n\n# Calculate the number of pixels\nNPIX = hp.nside2npix(NSIDE)\nprint(f\"Number of pixels for NSIDE={NSIDE}: {NPIX}\")\n\n# Create a simple map (e.g., an array with pixel indices)\nm = np.arange(NPIX, dtype=float)\n\n# Visualize the map using Mollweide projection\nhp.mollview(m, title=\"Simple Healpix Map (RING ordering)\")\nhp.graticule() # Add meridians and parallels\nplt.show()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.19.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions (source builds)"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.15.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}