Healpy, a python wrapper for healpix

Description

healpy is a Python package 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.

HEALPix was developed to efficiently process Cosmic Microwave Background data from Cosmology experiments like BOOMERANG and WMAP but it is now used in other branches of Astrophysics to store data from all-sky surveys. The target audience used to be primarily the Cosmology scientific community but currently anyone interested in handling pixelated data on the sphere is very welcome to propose new features.

Capabilities

healpy provides utilities to:

• convert between sky coordinates and pixel indices in HEALPix nested and ring schemes
• find pixels within a disk, a polygon or a strip in the sky
• apply coordinate transformations between Galactic, Ecliptic and Equatorial reference frames
• apply custom rotations either to vectors or full maps
• read and write HEALPix maps to disk in FITS format
• upgrade and downgrade the resolution of existing HEALPix maps
• visualize maps in Mollweide, Gnomonic and Cartographic projections
• transform maps to Spherical Harmonics space and back using multi-threaded C++ routines
• compute Auto and Cross Power Spectra from maps and create map realizations from spectra

The documentation can be found at https://healpy.readthedocs.io, tutorial at https://healpy.readthedocs.io/en/latest/tutorial.html, or execute it on mybinder

Requirements

• Python 3.7, 3.8, 3.9, or 3.10
• Numpy (tested with version >=1.5.0)
• Matplotlib
• Python development package is required for some distribution (e.g., python-dev package for Ubuntu)
• Astropy

Quick installation with Pip

The quickest way to install Healpy is with pip (>= 1.4.2), which automatically fetches the latest version of Healpy and any missing dependencies:

pip install --user healpy

If you have installed with pip, you can keep your installation up to date by upgrading from time to time:

pip install --user --upgrade healpy

See INSTALL.rst for further details and other installation options.

Optional

Healpy depends on the HEALPix C++ and cfitsio C libraries. Source code is include with Healpy and you do not have to install them separately.

However, if you have them installed already, Healpy should detect and reuse them instead of building them from source. To use your own installations of HEALPix and cfitsio, you will also need:

• pkg-config
• HEALPix autotools-style C++ package
• cfitsio

See INSTALL.rst for further instructions.

Known issues

• Building with OpenMP support: the underlying HEALPix C++ library can be built to use OpenMP to speed up some operations on systems with multiple cores. Most, but not all, modern C/C++ compilers support OpenMP, the notable exception being clang.

  If your Healpy build fails with an error message about being unable to link against -lgomp, then this typically means that Healpy detected an already-installed HEALPix C++ library that was built with OpenMP support, but you are trying to build Healpy with a compiler that does not support OpenMP. Try cleaning the build with python setup.py clean --all, and set the environment variables CC and CXX to point to an OpenMP-capable compiler, such as gcc/g++.

• Healpy does not currently support Windows. See healpy#25.

• Incompatibility with cfitisio from HEASOFT: due to a conflict of header file names it is currently not possible to use the cfitsio library provided with the HEASOFT package for compilation of HEALPix C++. HEASOFT's include directory contains a file called "rotmatrix.h" which clashes with HEALPix's own rotmatrix.h.

• Compilation problems in the C++ package: some gcc versions (we have reports for 4.4.5 and 4.4.6) crash with an internal compiler error during compilation of libsharp. Unfortunately we have not found a workaround for this compiler problem. To our knowledge, it has been fixed in gcc 4.4.7 and in the 4.5.x and newer versions.

• Healpy pixel functions, e.g. ang2pix, do not support 32-bit platforms. See healpy#194.

Support

For specific HOWTO questions please create a question on StackOverflow and tag it with the healpy tag, so that answers will be easily searchable on google.

If you think you found a bug or you have install issues, open an issue on GitHub: https://github.com/healpy/healpy/issues

For more general discussion, you can write to the healpy mailing list: https://groups.google.com/d/forum/healpy

Contribute

Project development takes place on github, http://github.com/healpy/healpy, please open an issue over there for reporting bugs or suggest improvements. Collaboration is very welcome, just fork the project on github and send pull requests back to the main repository.

Developers

Core developers:

• Cyrille Rosset
• Andrea Zonca
• Martin Reinecke
• Leo Singer
• Daniel Lenz

List of contributors: https://github.com/healpy/healpy/graphs/contributors

Acknowledgements

1. Cite the HEALPix and healpy papers, see the CITATION file in the repository.
2. Add an acknowledgment statement: "Some of the results in this paper have been derived using the healpy and HEALPix packages".
3. at the first use of the HEALPix acronym, a footnote placed in the main body of the paper referring to the HEALPix web site, currently http://healpix.sf.net
4. You can also directly support the maintenance and development of healpy via Github Sponsors