1====================================
2Healpy, a python wrapper for healpix
3====================================
4
5.. image:: https://travis-ci.org/healpy/healpy.png?branch=master
6 :target: https://travis-ci.org/healpy/healpy
7
8.. image:: https://readthedocs.org/projects/healpy/badge/?version=latest
9 :target: https://readthedocs.org/projects/healpy/?badge=latest
10 :alt: Documentation Status
11
12Description
13-----------
14
15Healpy provides a python package to manipulate healpix maps. It is based on the
16standard numeric and visualisation tools for Python, Numpy and matplotlib.
17
18To find more information about HEALPix, please visit its home page at
19http://healpix.sourceforge.net/.
20
21The documentation can be found at https://healpy.readthedocs.io, tutorial at
22https://healpy.readthedocs.io/en/latest/tutorial.html.
23
24Characteristics
25---------------
26
27* pixelisation manipulation (ang2pix, pix2ang, *etc.*)
28
29* spherical harmonic transforms (map2alm, alm2map, synfast, anafast, *etc.*
30 both for temperature and polarisation)
31
32* plotting capabilities (mollweide and gnomonic projection)
33
34* reading and writing of HEALPix FITS maps and alm
35
36Requirements
37------------
38
39* `Python <http://www.python.org>`_ 2.7, 3.5, or 3.6
40
41* `Numpy <http://numpy.scipy.org/>`_ (tested with version >=1.5.0)
42
43* `Matplotlib <http://matplotlib.sourceforge.net/>`_
44
45* Python development package is required for some distribution (e.g.,
46 python-dev package for Ubuntu)
47
48* `Astropy <http://www.astropy.org>`_
49
50Quick installation with Pip
51---------------------------
52
53The quickest way to install Healpy is with `pip <http://www.pip-installer.org>`_
54(>= 1.4.2), which automatically fetches the latest version of Healpy and any
55missing dependencies::
56
57 pip install --user healpy
58
59If you have installed with ``pip``, you can keep your installation up to date
60by upgrading from time to time::
61
62 pip install --user --upgrade healpy
63
64See `INSTALL.rst <https://github.com/healpy/healpy/blob/master/INSTALL.rst>`_
65for further details and other installation options.
66
67Optional
68--------
69
70Healpy depends on the HEALPix C++ and cfitsio C libraries. Source code is
71include with Healpy and you do not have to install them separately.
72
73However, if you have them installed already, Healpy should detect and reuse
74them instead of building them from source. To use your own installations of
75HEALPix and cfitsio, you will also need:
76
77* `pkg-config <http://pkg-config.freedesktop.org>`_
78
79* `HEALPix
80 <http://sourceforge.net/projects/healpix/files/Healpix_3.11/autotools_packages/>`_
81 autotools-style C++ package
82
83* `cfitsio <http://heasarc.gsfc.nasa.gov/fitsio/>`_
84
85See `INSTALL.rst <https://github.com/healpy/healpy/blob/master/INSTALL.rst>`_
86for further instructions.
87
88Known issues
89------------
90
91* Building with OpenMP support: the underlying HEALPix C++ library can be built
92 to use `OpenMP <http://openmp.org/wp/>`_ to speed up some operations on
93 systems with multiple cores. Most, but not all, modern C/C++ compilers support
94 OpenMP, `the notable exception being clang <http://openmp.llvm.org>`_.
95
96 If your Healpy build fails with an error message about being unable to link
97 against `-lgomp`, then this typically means that Healpy detected an
98 already-installed HEALPix C++ library that was built with OpenMP support, but
99 you are trying to build Healpy with a compiler that does not support OpenMP.
100 Try cleaning the build with `python setup.py clean --all`, and set the
101 environment variables `CC` and `CXX` to point to an OpenMP-capable compiler,
102 such as gcc/g++.
103
104* Healpy does not currently support Windows.
105 See https://github.com/healpy/healpy/issues/25.
106
107* Incompatibility with ``cfitisio`` from ``HEASOFT``: due to a conflict of
108 header file names it is currently not possible to use the cfitsio library
109 provided with the HEASOFT package for compilation of HEALPix C++. HEASOFT's
110 include directory contains a file called "rotmatrix.h" which clashes with
111 HEALPix's own rotmatrix.h.
112
113* Compilation problems in the C++ package: some gcc versions (we have reports
114 for 4.4.5 and 4.4.6) crash with an internal compiler error during compilation
115 of libsharp. Unfortunately we have not found a workaround for this compiler
116 problem. To our knowledge, it has been fixed in gcc 4.4.7 and in the 4.5.x
117 and newer versions.
118
119* Healpy pixel functions, e.g. ``ang2pix``, do not support 32-bit platforms.
120 See https://github.com/healpy/healpy/issues/194.
121
122Support
123-------
124
125For specific *HOWTO* questions please create a question on StackOverflow_ and
126tag it with the `healpy` tag, so that answers will be easily searchable on
127google.
128
129If you think you found a bug or you have install issues, open an issue on GitHub:
130https://github.com/healpy/healpy/issues
131
132For more general discussion, you can write to the healpy mailing list:
133https://groups.google.com/d/forum/healpy
134
135.. _StackOverflow: http://stackoverflow.com/questions/ask
136
137Contribute
138----------
139
140Project development takes place on github, http://github.com/healpy/healpy,
141please open an issue over there for reporting bugs or suggest improvements.
142Collaboration is very welcome, just fork the project on github and send pull
143requests back to the main repository.
144
145Developers
146----------
147Core developers:
148
149* Cyrille Rosset
150* Andrea Zonca
151* Martin Reinecke
152* Leo Singer
153* Daniel Lenz
154
155List of contributors: https://github.com/healpy/healpy/graphs/contributors
156
157Acknowledgements
158----------------
159
160Note that, as stated `here <http://healpix.sourceforge.net/downloads.php>`_
161publications based on work using the HEALPix software package should include
162both of the following:
163
1641. an acknowledgment statement: "Some of the results in this paper have been
165 derived using the HEALPix (Gorski et al., 2005) package". The complete
166 reference is:
167
168 Gorski, K.M., E. Hivon, A.J. Banday, B.D. Wandelt, F.K. Hansen,
169 M. Reinecke, and M. Bartelmann, HEALPix: A Framework for
170 High-resolution Discretization and Fast Analysis of Data
171 Distributed on the Sphere, Ap.J., 622, 759-771, 2005.
172
1732. at the first use of the HEALPix acronym, a footnote placed in the main body
174 of the paper referring to the HEALPix web site, currently
175 http://healpix.sf.net
176
177As healpy is based on HEALPix Software (the C++ library), the same
178condition applies to it.
179
