{"id":7012,"library":"astropy-healpix","title":"Astropy HEALPix","description":"astropy-healpix provides HEALPix (Hierarchical Equal Area isolations of the Sphere) functionality, including coordinate transformations, pixelization, and query methods, tightly integrated with the Astropy ecosystem. It is currently at version 1.1.3 and maintains an active development status, with releases often coordinated with major Astropy versions or for bug fixes as needed.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/astropy/astropy-healpix","tags":["astronomy","astropy","healpix","coordinates","sky","spatial"],"install":[{"cmd":"pip install astropy-healpix","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for coordinate systems, units, and general astronomical utilities.","package":"astropy","optional":false},{"reason":"Fundamental library for numerical operations on arrays.","package":"numpy","optional":false},{"reason":"Used for certain spatial and mathematical operations.","package":"scipy","optional":false}],"imports":[{"note":"HEALPix is part of the dedicated `astropy-healpix` library, not directly `astropy.healpix` (which might refer to an internal Astropy module or a coordinate frame).","wrong":"from astropy.healpix import HEALPix","symbol":"HEALPix","correct":"from astropy_healpix import HEALPix"},{"symbol":"HpxGeom","correct":"from astropy_healpix import HpxGeom"}],"quickstart":{"code":"from astropy_healpix import HEALPix\nfrom astropy.coordinates import ICRS, SkyCoord\nfrom astropy import units as u\nimport numpy as np\n\n# Create a HEALPix object with nside=32, 'nested' order, and ICRS frame\nhp = HEALPix(nside=32, order='nested', frame=ICRS())\n\n# Convert HEALPix pixel indices to SkyCoord objects\npixel_indices = np.array([0, 100, 20000])\nsky_coords = hp.healpix_to_skycoord(pixel_indices)\n\nprint(f\"Sky Coordinates for pixels {pixel_indices}:\\n{sky_coords}\")\n\n# Convert SkyCoord objects to HEALPix pixel indices\nra = np.array([0, 10, 20]) * u.deg\ndec = np.array([0, 5, 10]) * u.deg\ncoords_to_convert = SkyCoord(ra, dec, frame='icrs')\npix_at_coords = hp.skycoord_to_healpix(coords_to_convert)\n\nprint(f\"HEALPix pixels for coordinates {coords_to_convert}: {pix_at_coords}\")","lang":"python","description":"This quickstart demonstrates how to initialize a `HEALPix` object, convert HEALPix pixel indices to sky coordinates, and convert sky coordinates back to pixel indices. It uses common Astropy coordinate and unit objects for integration."},"warnings":[{"fix":"Explicitly specify `order='ring'` in your `HEALPix` or `HpxGeom` constructor if you intend to use ring ordering (e.g., `HEALPix(nside=32, order='ring', frame=ICRS())`).","message":"The default value of the `order` parameter for `HEALPix` and `HpxGeom` constructors changed from `'ring'` to `'nested'` in `astropy-healpix v1.0.0`. If your code relies on the implicit `'ring'` order from older versions and you update, it will now silently produce incorrect pixel indices or coordinate conversions unless `order='ring'` is explicitly set.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always ensure your `astropy` installation meets the minimum version requirement specified by `astropy-healpix` (typically found in the `pyproject.toml` or `setup.cfg` on GitHub, or PyPI's `Requires-Dist` section).","message":"`astropy-healpix` has specific minimum `astropy` requirements (e.g., `>=5.0.0` for `astropy-healpix` 1.x.x). Using an older `astropy` version can lead to `ImportError`s, `TypeError`s, or unexpected behavior due to API mismatches between the two libraries.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure the value passed to `nside` is always a power of 2. For example, `HEALPix(nside=64, ...)` is valid, but `HEALPix(nside=10, ...)` is not.","message":"The `nside` parameter, which determines the resolution of the HEALPix grid, must always be a power of 2 (e.g., 1, 2, 4, 8, 16, 32, ...). Providing a non-power-of-2 integer will result in a `ValueError`.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The correct import path for the `astropy-healpix` library is `from astropy_healpix import HEALPix` (note the underscore).","cause":"Users often confuse the dedicated `astropy-healpix` library with an internal or deprecated `astropy.healpix` module, leading to incorrect import paths.","error":"ImportError: cannot import name 'HEALPix' from 'astropy.healpix'"},{"fix":"Change `nside` to a power of 2 (e.g., 2, 4, 8, 16, 32, 64, etc.). For instance, `HEALPix(nside=32, ...)` is valid, while `HEALPix(nside=50, ...)` is not.","cause":"The `nside` parameter for `HEALPix` or `HpxGeom` was set to an integer that is not a power of 2.","error":"ValueError: nside must be a power of 2"},{"fix":"Remove the `frame` argument when initializing `HpxGeom`. If you need to work with sky coordinates, use the `HEALPix` class instead.","cause":"The `frame` argument was incorrectly passed to the `HpxGeom` class. `HpxGeom` represents the geometric properties of a HEALPix grid and does not require a coordinate frame; `frame` is only applicable to the `HEALPix` class which handles sky coordinates.","error":"TypeError: HpxGeom() got an unexpected keyword argument 'frame'"}]}