previous up next
Up: Main Page Next: Main Page Top: Main Page

HEALPix Facility Installation Guidelines

This document describes the installation for the HEALPix facilities.

Eric Hivon, Anthony J. Banday, Matthias Bartelmann, Benjamin D. Wandelt, Frode K. Hansen and Krzysztof M. Górski


Revision: Version 3.83; November 13, 2024

https://healpix.sourceforge.io
http://healpix.sf.net


TABLE OF CONTENTS

Introduction

In this document the installation procedure for the HEALPix distribution is outlined. HEALPix comprises a suite of Fortran 90, C++, IDL, Java and Python routines providing both stand-alone facilities and callable subroutines as an alternative for those users who wish to build their own tools. A set of C subroutines and functions is also provided.

The distribution can be downloaded as a gzipped tarred file, or as a zipped file, which can respectively be unpacked by executing the commands1
% gunzip Healpix_3.83.tar.gz
% tar -xpf Healpix_3.83.tar
or
% tar -xzpf Healpix_3.83.tar.gz
or
% unzip Healpix_3.83.zip
creating a directory named Healpix_3.83 whose structure is shown in Figure 1.

Figure 1: The directory structure for the HEALPix distribution.
Image new_dir_tree

As with most freely available software, the distribution comes with caveats, the major one being that although we have attempted to automate the installation as much as possible, not all eventualities can ever be foreseen. We have tested the installation on the following platforms:
AIX, IRIX, IRIX64, Linux, SunOS, ALPHA and Darwin (MacOS)

There may be problems in the facility build due to the local system configuration which is beyond our control.


Installation Requirements


Table 1: Documentation on the installation and usage of the different packages
Healpix Package Information on installation Information on routines
     
Fortran 90 This document "Fortran Facilities" and "Fortran Subroutines" documents
     
IDL/GDL/FL This document "IDL Facilities"
     
C++ This document "C++ Facilities and Subroutines" (HTML only)
     
C This document, or src/C/README "C Subroutines Overview"
     
Java src/java/README "Java Overview" (HTML only)
     
Python This document, or src/healpy/INSTALL "Healpy Documentation" (HTML only)
     
   


The major part of the HEALPix distribution is written in both Fortran 90 and C++ and so the appropriate compiler(s) must be present (Linux and Darwin users should look at Section 7.1 about free F90 compilers. Microsoft Windows users should look at Section 7.2). Many visualisation tools and map manipulation routines are provided in IDL (please note that at least version 6.4 is required), Java and Python. Some of the HEALPix routines are also available in C.
Starting with version 3.0, the healpy (HEALPix in Python) library has been integrated into HEALPix releases. Since it is, to a large extent, a wrapper to the C++ routines, installing it also requires a C++ compiler (on top of python and a few supporting Python libraries) but it will perform its own compilation of the current HEALPix C++ library.
Starting with version 3.10, all the (computation intensive) Spherical Harmonics operations required by the C++, Fortran and Python routines are performed with the highly optimized C-written libsharp library, also included in the package, and which was further optimized in version 3.60.

This section and the next focus on the compilation and installation of the C, C++, Fortran 90, IDL and Python routines and libsharp library. For more information on the Java routines see table 1.

The configure script is written in the Bourne shell. The script attempts to generate a Makefile which is tailored to one of the above Operating Systems (OS's) and using Makefile.in as a template for non system-specific statements. Only the basic UNIX make facility is required to build the software, although we do still recommend the GNU make facility (https://ftp.gnu.org/gnu/make/). In addition, several environment configuration files and an IDL/GDL/FL startup file are generated. These automatically establish various environment variables and aliases to make the use of the HEALPix package simpler.

The HEALPix Fortran 90, C++, C and Python distributions also require the publicly available CFITSIO library. Versions 4.2.0 (Nov 2022) or higher are recommended since they simultaneously meet Fortran 90 routines requirements, fix previous security vulnerabilities and are compatible with Apple's ARM chips.

Software Package Source
   
CFITSIO V 4.2.0 or more https://heasarc.gsfc.nasa.gov/fitsio/
   
 




The IDL visualization software is commercially available at

Software Package Source
   
IDL V 6.4 or more https://www.harrisgeospatial.com/Software-Technology/IDL
   
 




while the GNU Data Language GDL, a free open clone of IDL 7.1, or the freeware Fawlty Language FL, a free closed clone of IDL 8, can also be used (with some caveats, listed respectively in §7.9 and §7.10) and can be downloaded for free from

Software Package Source
   
GDL 1.0.1 or more https://github.com/gnudatalanguage/gdl
FL 0.79.50 or more https://www.flxpert.hu/fl or https://bitbucket.org/fawlty/fl/src/master
   
 




As it was already the case in version 1.20, users no longer need to acquire the IDL Astronomy User's Library (https://github.com/wlandsman/IDLAstro) or the COBE (IDL) Analysis Software (https://lambda.gsfc.nasa.gov/product/cobe/cgis.cfm), although we do recommend these packages to the user. The 100-odd routines required for version 3.83 are contained in the subdirectory Healpix_3.83/src/idl/zzz_external. These procedures are included in the HEALPix package unchanged and solely for the purpose of making it self contained. In this way, we remove the burden of installation of additional libraries from the end user.

The Python healpy package requires

Software Package Source
   
Python 3.10 or more https://www.python.org
Numpy 2.0 or more https://numpy.scipy.org
Matplotlib 0.91.2 or more https://matplotlib.sourceforge.net
Cython https://cython.org
Astropy.io.fits https://www.astropy.org
(PyFITS) https://pypi.org/project/pyfits/3.3
   
 




While not required, the IPython (https://ipython.org) and jupyter (https://jupyter.org) interfaces can also be useful.

A parallel implementation (based on OpenMP, for shared memory architectures) of the Spherical Harmonics Transforms involved in F90 synfast, anafast, smoothing, plmgen, alteralm and C++ synalm_cxx, alm2map_cxx, anafast_cxx, smoothing_cxx, rotalm_cxx ... is now available by default and can be readily compiled and used with the standard installation script.

A set of routines with MPI parallelization (for distributed memory architectures) is also available for Spherical Harmonics Transform, thanks to the work of H.K. Eriksen (UIO) and Snorre Boasson (ITEA, NTNU). See the F90 subroutines documentation for more information on how to use those routines in your code.

We found that it was remarkably difficult to find random number generators in the public domain which are simple yet powerful and easy to use. We are providing one (both in C++ and F90) which is an adaptation of an xorshift generator described in Marsaglia (Journal of Statistical Software 2003, vol 8). It has a theoretical period of $2^{128}-1 \approx 3.4\ 10^{38}$.


healpix_doc: an easy access to HEALPix documentation

The shell script healpix_doc now is available to provide easy access to the HTML, PDF and/or EPUB documentation of all Healpix packages. It will automatically open a web browser, a PDF viewer, or an EPUB viewer (among those found on the system) on the documentation available locally (at $HEALPIX/doc) or on remote web sites. To use it, simply type
     $HEALPIX/healpix_doc -e      or
     $HEALPIX/healpix_doc -h      or
     $HEALPIX/healpix_doc -p     
to access respectively the EPUB, HTML and PDF documentation. The default browser and viewers used by healpix_doc can optionally be set with the environment variables $HEALPIX_HTML_BROWSER, $HEALPIX_EPUB_VIEWER and $HEALPIX_PDF_VIEWER.
EPUB is an open e-book format whose dynamical layout allows the same document to be read comfortably on screens of any size. It is supported by many commercial and free e-readers, with sometimes unequal results. Among the free ones we tested, we can recommend

The Installation Procedure

If the user has one of the supported OS's, then installation proceeds utilizing the following commands. If your OS is not supported, the configuration step should be omitted, Makefile.in should be copied as Makefile and explicitly tailored to the user environment.

% ./configure [-L] [—auto=<list>] uses Makefile.in as a template to build the correct Makefile (from user inputs as required), it will also configure the IDL/GDL/FL routines
% make builds all the facilities
% make test tests all the facility previously compiled
% make clean removes object (*.o) files
% make tidy removes object files, module files (*.mod), executables and libraries
% make distclean same as above and restores the directories to the state of the original distribution
These different steps are detailed below.


./configure [-L] [—auto=<list>] [-h] [-v]

The ./configure script manages the configuration of the C, C++, Fortran90, IDL and Python suites of routines and facilities.

An online help is available with ./configure -h, while ./configure -v will return the HEALPix release number (currently 3.83) and exit.

The -L option can be used to write the HEALPix specific configuration files into the HEALPix directory itself rather than in installer's home directory (see §4.1.1). Using the -L option is recommended when doing a project or system wide installation of HEALPix to be accessed by several different users.

Two new features have been introduced in version 3.60.

These two new features can of course be combined. For instance, in Bourne related shells (eg, sh, bash, dash, ksh, zsh), the command
FC=ifort CC=icc ./configure -–auto=f90
and in C related shells (eg, csh, tcsh)
setenv FC ifort ; setenv CC icc ; ./configure -–auto=f90
will automatically run the configure script for the libsharp (if not previously done) and f90 package items, using Intel's Fortran and C compilers.


Configuration profile

A feature introduced in previous releases and enhanced since v2.10, is that the configure script creates a shell configuration file
(located in ${HOME}/.healpix/3_83 _$\langle$OS_TYPE$\rangle$/config or in
${HEALPIX}/confdir/3_83 _$\langle$OS_TYPE$\rangle$/config if ./configure -L was used) according to shell type in which various environment variables and aliases are defined for your convenience. If you agree upon prompting (or set the boolean environment variable PROFILE_EDIT to an affirmative value), it will also change your default system profile during installation to automatically source this profile. If you do not agree to this change (or set the boolean environment variable PROFILE_EDIT to a false value), you will need to explicitly source the configuration file above for any session in which you intend to run HEALPix facilities. In particular, you will have to make sure that the HEALPIX system variable is correctly defined (as the full path to the HEALPix directory) before running the package.

C configuration

The ./configure script will ask for the C compiler and options to be used, and for the full path of an installed cfitsio library to (optionally) link to. By default, only a static library is created, but the user can also ask for a shared (Unix/Linux systems) or dynamic (Darwin) library.
The environment variables CC, C_FITS (boolean), FITSDIR, FITSINC and C_SHARED (boolean) can be used to control the script behavior.
After compilation (see make section) and linking, all libraries will be in ${HEALPIX}/lib/chealpix.* .
See also §6 on pkg-config.


C++ configuration

Starting with version 3.60, the ./configure script will be used to provide information (like the choice of C++ compiler and options) to an automated (autoconf generated) configure script, (located in src/cxx/configure), which will take care of the configuration.
The environment variables CC, CXX, CXXFLAGS, FITSDIR and FITSINC can be used to customize the whole process. If the latter two are not explicitely set, the autoconf configure script will look for a cfitsio installation on its own.
The configuration of libsharp will be also taken care of at this stage.
The boolean variable CXX_PARAL, introduced in version 3.80 and defaulting to 1 (=true), controls whether the code will be parallelized (with OpenMP) or not. To obtain a serial implementation of the code, set CXX_PARAL=0 and make sure no OpenMP related flags appear in CXXFLAGS.
At odds with previous versions, the C++ binaries, libraries and header files will be installed in ${HEALPIX}/bin, ${HEALPIX}/lib and ${HEALPIX}/include directories respectively.
If the HEALPix configuration file is sourced as described in §4.1.1, the full path to the C++ executables will be added to the environment PATH variable.
See also §6 on pkg-config.

Fortran 90 configuration

When you run ./configure on a supported system you will be prompted to enter compiler optimisation flags. We have not attempted to provide the best optimisation flags for all operating systems. The configure script will have a guess at optimisation options for some systems, but it is up to the user to figure out an optimal set2. From our experience, we have not found significant accumulation of numerical error even when using the most aggressive optimisation level available.
The environment variable FITSDIR, CC, FC, F_AR, F_DIRSUFF, F_OPT, F_SHARED (boolean) and F_PARAL (boolean) can be used to customize the configuration.
The configuration of libsharp will be also taken care of at this stage.
If the HEALPix configuration file is sourced as described in §4.1.1, the full path to the F90 executables will be added to the environment PATH variable.
See also §6 on pkg-config.


IDL/GDL/FL configuration

You will be asked for the external applications, such as gv, xpdf, display, $\ldots$ you want to use to visualize the GIF, JPEG, PDF, Postscript and PNG files created by IDL, GDL or FL.
The environment variables papersize, ps_com, pdf_com and gif_com can be used to customize this configuration.
If the HEALPix configuration file is sourced as described in §4.1.1, the aliases hidl (hidlde), hgdl (hgdlde) and/or hfl (hflde) are also defined to give you access to HEALPix routines from respectively IDL, GDL and/or FL, with a command-line (or graphical) interface.
See the HEALPix IDL Document for more information on using HEALPix IDL/GDL/FL together with other IDL libraries, and §7.9,7.10 on using GDL or FL instead of IDL.


Java installation

The configuration and installation of the HEALPix Java package is currently handled separately. See table 1 for more information.


Python (healpy) installation

Starting with version HEALPix-3.83 (healpy-1.18) python wheels will be generated by the package installer pip3 (https://pypi.org/project/pip), instead of .egg files previously generated by easy_install.
The ./configure script will ask for the Python command you want to use (in case several coexist on your computer) and check that its version number meets the healpy requirements (see above), as well as for C and C++ compilers, and finally the list of arguments you want to pass to the pip command. The latter default value is “install . -–user”, where the dot (.) refers to the local healpy source directory (${HEALPIX}/src/healpy). The -–user flag can be dropped if the installation is made system-wide (by a root user) or in a virtual environnement (like for instance in conda), while the flag -e or -–editable can be inserted (ie, looking like 'install -e . -–user') to keep the installed package editable.
The environment variables PYTHON, C, CXX and PIPARGS can be used to customize the configuration process.
Note that during the compilation with make (see below), the pip command will prompt a fresh compilation of the ${HEALPIX}/src/cxx/* libraries, with all the options necessary to Python linkage, and can be done independently of the C++ installation described above.
Note also that the healpy compilation will very likely require an active network connection in order to download on the fly some of the required Python ancillary packages.


libsharp library

The libsharp C-written library for optimized Spherical Harmonics operations is used by the C++, Fortran, IDL and healpy routines and facilities. Starting with version 3.60, a new, faster, implementation is in use, and will be configured (only once) at the same time as any of the C++ or Fortran packages, but can also be configured on its own.
The environment variables CC and SHARP_COPT can be used to set respectively the C compiler and its options proposed during the interactive or automated configuration process.
For optimal performance, the C compilation flags should include -ffast-math and -march=native (or your compiler's equivalent options), and may look like SHARP_COPT='-O3 -ffast-math -march=native -fopenmp' (multi-worded values must be enclosed in quotes).
If you are using gcc or clang (see below) and you want to produce a portable, high-performance library, and if you compiler and assembler support it, you can also replace -march=native by -DMULTIARCH.
If you are using clang to compile libsharp, make sure it supports OpenMP (as in version 3.7 or more), and that OpenMP is enabled explicitly among the compiler options (possibly requiring the flag -fopemp=libomp or -fopemp=libiomp5 instead of the usual -fopemp or by specifying the location of the OpenMP libraries during compilation and at run time).
The boolean variable SHARP_PARAL, introduced in version 3.80 and defaulting to 1 (=true), controls whether the library will be parallelized (with OpenMP) or not. To obtain a serial implementation of libsharp, set SHARP_PARAL=0 and make sure no OpenMP related flags appear in SHARP_COPT.
After compilation and installation (which, for libsharp only, are done as early as the configure step) the resulting library will be in ${HEALPIX}/lib/libsharp* and the header files in ${HEALPIX}/include/libsharp/sharp*.h.
See also §6 on pkg-config.

Compilation and installation

The
     make     
command will compile one or several of the C, C++, F90, libsharp and Python packages depending on what was configured with the ./configure script. Specific packages can be compiled with the respective commands 

   make c-all
   make cpp-all
   make f90-all
   make sharp-all
   make healpy-all

To perform several compilation jobs simultaneously, the command make -j [number_of_jobs] can be used.

Please neglect any possible warnings at compile time. If you run into trouble please refer to the section Troubleshooting and further information.

After running make, the user must re-login to ensure that the new profiles built by the installation procedure are correctly sourced. Only then will the user have full access to the specific HEALPix environment variables etc.

Testing the installation

All installed libraries and executables can be tested with 

   make test

while specific tests of the C, C++ and Fortran products can be performed with, respectively 

   make c-test
   make cpp-test
   make f90-test
   make sharp-test
   make healpy-test
For f90-test, Table 2 lists the codes tested with the parameter files used, as well as the data files produced and the respective reference files.


Table 2: Data files and images produced by the Fortran codes during the tests, and the respective reference files to which they can be compared. All the files listed are located or produced in the Healpix_3.83/test directory. The GIF images of full sky maps were produced using map2gif. NA: No image available, because the data set is not a sky map
code & parameter file output data reference data output image reference image
synfast syn.par test_map.fits map.fits test_map.gif map.gif
test_alm.fits alm.fits NA NA
smoothing smo.par test_sm.fits map_sm.fits test_sm.gif map_sm.gif
ud_grade udg.par test_LOres.fits map_LOres.fits test_LOres.gif map_LOres.gif
hotspot hot.par test_ext.fits map_ext.fits test_ext.gif map_ext.gif
test_max.asc max.asc NA NA
test_min.asc min.asc NA NA
anafast ana.par test_cl.fits cl_out.fits NA NA
— ana2maps.par test_cl2maps.fits cl2maps.fits NA NA
— ana_w2.par test_cl_w2.fits cl_w2.fits NA NA
alteralm alt.par test_almdec.fits almdec.fits NA NA
median_filter med.par test_mf.fits map_mf.fits test_mf.gif map_mf.gif
sky_ng_sim ngfs.par test_ngfs.fits map_ngfs.fits test_ngfs.gif map_ngfs.gif
process_mask prmask.par test_distmask.fits distmask.fits test_distmask.gif distmask.gif


Notes:

In order to test the new HEALPix profile set-up one can then attempt to run any C++ or F90 facility from any directory on your system. Similarly, IDL, GDL or FL can be tested by invoking respectively hidl (or hidlde), hgdl (or hgdlde), or hfl (or hflde).

Cleaning up

Three levels of cleaning are available: 
  make clean
will remove the intermediate files created during compilation, such as object files, (Fortran) modules files, ... found in the source or build directories; 
  make tidy
same as above, and will also remove the HEALPix executables, libraries and module and/or include files; 
  make distclean
will return the HEALPix directory to its original 'distribution' state by discarding the same files as above, as well as the executable and library directories and the top level Makefile.

As a consequence, make clean can be used after a successful compilation and installation in order to remove now useless intermediate files while keeping the codes functional, while make tidy should be used between consecutive (failed) attempts with different compilers, compiler versions or compiler options, to avoid any conflict between new and pre-existing files.

Linking a code with HEALPix library

Third party or user-developed codes may require HEALPix as an external library. An easy way to achieve this linking is to use the pkg-config facility (now available on many systems, including Linux, Unix*, MacOS and MS Windows), following the procedure described in §6 on pkg-config.

A Note on Re-installation

As a result of the line added to your shell profile which explicitly sources the HEALPix profile, care must be taken if the package is reinstalled in a different directory. If such reinstallation is desired, the included line must be removed from your system profile, allowing the corrected version to be added.


Pkg-config files

Starting with HEALPix 3.12, pkg-config (.pc) files are generated during the configuration of the libsharp, C, C++ and F90 packages, and are initially located respectively in ${HEALPIX}/lib/pkgconfig/libsharp.pc, ${HEALPIX}/lib/pkgconfig/chealpix.pc, ${HEALPIX}/lib/pkgconfig/healpix_cxx.pc, and
${HEALPIX}/libsuffix/pkgconfig/healpix.pc.

If the pkg-config software is available on your system (see https://www.freedesktop.org/wiki/Software/pkg-config/ to download, install and use it) and if the location of the HEALPix pkg-config files above are known to it (either by moving/copying them to one of the standard locations returned by
pkg-config -–variable=pc_path pkg-config
or by customizing the environment variable PKG_CONFIG_PATH4), then linking your own or third-party code with the C, C++, F90 HEALPix library simply becomes
cc `pkg-config -–cflags -–libs chealpix` mycode.c -o mycode
c++ `pkg-config -–cflags -–libs healpix_cxx` mycode.cpp -o mycode
FC `pkg-config -–cflags -–libs healpix` mycode.f90 -o mycode
(where FC has to be replaced by the Fortran compiler used to generate the HEALPix library).


Troubleshooting and further information

This section contains a list of difficulties which we have dealt with. It is by no means exhaustive. In case of problems, see https://healpix.sourceforge.io/support.php or contact healpix-support at lists.sourceforge.net


Free Fortran90/95 Compilers

Some free Fortran90/95 compilers that can be used to compile HEALPix are listed below. They all support the few Fortran 2003 features used in HEALPix. See http://fortranwiki.org/fortran/show/Compilers for an extended list of free, freemium and commercial Fortran compilers.


Installation under Microsoft Windows

Detailed instructions to install HEALPix on Windows 7 using Cygwin, kindly provided by John Arballo, are available in §7.2.1, while other configurations are discussed in §7.2.2.


Installation on Windows 7 with Cygwin

The three steps (installation of Cygwin, cfitsio and HEALPix respectively) must be done in that order.

A: Install Cygwin

  1. Go to https://www.cygwin.com/and click on `Install Cygwin' in the menu on the left.

  2. Click on setup-x86.exe (for 32-bit installation) or setup-x86_64.exe (for 64-bit installation) and then `Save File' when prompted.

  3. Go to your Downloads folder (or wherever you saved setup-x86*.exe) and double-click on the setup-x86*.exe file to run it.

  4. Accept all defaults, except:

    1. You have to `Choose A Download Site'. (eg: https://ftp.gtlib.gatech.edu).
    2. When prompted to `Select Packages', expand `Default' (if you see a `+' to the left of it), expand `Devel', then find and add the following packages (click on `Skip' for each of them so it changes to the version number and a checkbox appears in the `Bin' column):
           gcc-core     
           gcc-fortran     
           gcc-g++     
           make     
  The installation will take a few minutes.

B: Install CFITSIO Library

  1. Get the latest source code package from NASA's HEASARC website (https://heasarc.gsfc.nasa.gov/FTP/software/fitsio/c/cfitsio_latest.tar.gz). When prompted to save the file, in the Save dialog window, navigate to C:\cygwin64\usr\local (assuming you accepted the defaults when installing Cygwin), click on `New folder' and  name it `src', go into that folder and `Save'.
  2. Open a Cygwin terminal (via the new Desktop icon or through your Start menu).
  3. Enter the following commands at the '$' prompt:
         $ cd /usr/local/src     
         $ tar zxvf cfitsio_latest.tar.gz     
         $ cd cfitsio     
         $ ./configure -–prefix=/usr     
         $ make     
         $ make install     
         $ cd ../     
  4. Leave the Cygwin terminal open.

C: Install HEALPix

  1. Get the latest version of HEALPix from SourceForge (https://sourceforge.net/projects/healpix/files/latest/download). When prompted to save the file, save it in C:\cygwin64\usr\local\src.
  2. In Windows Explorer, navigate to C:\cygwin64\usr\local\src, right-click on Healpix_3.83_*.zip and `Extract all...'. Accept the default location.
  3. In the Cygwin terminal, type the following commands at the '$' prompt
    (use the names of the Healpix directories for the version you installed):
         $ cd Healpix_3.83_*     
         $ cd Healpix_3.83     
         $ ./configure     
    Select an option from the menu (e.g., `2' for the C package) and accept all of the defaults except that the first time you run configure, you'll be prompted at the end to modify your home shell profile ('.profile'). Enter `y' at this prompt.
         $ make     
         $ make test     
         $ make tidy     


Other Windows configurations

Installation on Windows versions other than 7 should be very similar to the one detailed above.
In step A above, replacing Cygwin with MinGW (http://www.mingw.org/) together with the MSYS collection of GNU utilities (see http://www.mingw.org/wiki/msys and https://sourceforge.net/projects/mingw/files) is also possible. The Unix/Linux tools required include sh, make, awk, grep, sed, ls, wc, cat, more, nm, ar, as well as C, C++ and Fortran compilers.
The latest gfortran binaries for Cygwin and/or MinGW can be found at, eg https://cygwin.com/cgi-bin2/package-grep.cgi?grep=gcc-fortran&arch=x86_64, following the tips found at https://gcc.gnu.org/wiki/GFortranBinaries.

Problems with CFITSIO

Compilation of CFITSIO Fortran wrappers

The most common problem with the Fortran HEALPix compilation will produce messages like: 
  ld: Undefined symbols:
   _ftbnfm_
   _ftclos_
   _ftcrhd_
   _ftdkey_
   ...
or 
  fitstools.f90: undefined reference to `ftdkey_'
  fitstools.f90: undefined reference to `ftbnfm_'
  fitstools.f90: undefined reference to `ftclos_'
  ...
or 
 Undefined symbols:
  "_ftghbn_", referenced from:
      ___fitstools_MOD_read_fits_cut4.clone.2 in libhealpix.a(fitstools.o)
      ___fitstools_MOD_getsize_fits.clone.1 in libhealpix.a(fitstools.o)
      ___fitstools_MOD_getsize_fits in libhealpix.a(fitstools.o)
   ...
 ld: symbol(s) not found
 collect2: ld returned 1 exit status
and occurs when the CFITSIO installation script could not find a valid fortran compiler.
To solve this problem
  1. Go into the CFITSIO directory.
    Assuming that ifort is available on your system (it can be replaced below by gfortran, g95, f77, f2c, $\ldots$) type:
         ./configure FC=ifort     
         make     
         make install      (optional).
  2. Then go back into the HEALPix directory and do
         ./configure      (making sure that you are using the newly created libcfitsio.a library)
         make     
         make test     
See also the note below on 64 bit architectures.

CFITSIO problems on systems with 64 bit architecture

  1. Linux, Mac OS X

    If the HEALPix codes are compiled in 64 bits, and the GNU C Compiler (gcc) is used to compiled CFITSIO, then issue the following commands in the CFITSIO directory: 

      ./configure FC='gcc -m64'
  make

    You can then force compilation to the same binary format by entering -m64 when asked for the optimisation options in the HEALPix configure script.

  2. IRIX64

    On a 64-bit architecture such as IRIX64, CFITSIO will have to be compiled in the same binary format as the HEALPix codes. This can be achieved by typing the following on the command line in the CFITSIO directory: 

      rm config.cache    
  setenv CC 'cc -n32'
  ./configure
  make

    Alternatively you can replace the -n32 with -64. You can then force compilation to the same binary format by entering either -n32 or -64 when asked for the optimisation options in the HEALPix configure script.

CFITSIO linking problems

A particular problem encountered with the CFITSIO Version 2.0 release relates to the inclusion of various libraries within the system release for a given machine. This led to some modifications to the Makefile to include the specific library links -lm -lnsl -lsocket on SunOS, but only -lm for IRIX64. If your OS is not completely supported by the distribution, you may find this as one source of errors. The CFITSIO developers recommend compilation of the testprog routine. Inspection of the libraries linked after executing the make testprog statement will reveal those you need to include in the Makefile.

CFITSIO and Debian/Linux

Some problems have been reported on Debian/Linux systems during the linking to the CFITSIO library shipped with Linux. If these problems occur, try to recompile the CFITSIO library from scratch before linking to HEALPix.


CFITSIO and libcurl

Starting with version 3.42, CFITSIO is by default linked with the curl library (https://curl.haxx.se/libcurl, used to read remote FITS files via https) whenever it is available. This shared or dynamic library is pretty standard on modern systems, and often located in /usr/lib or /usr/lib64, and the command curl-config can be used to determine its location. In this case, when executing the HEALPix code, the system must know where to find this library at runtime as explained for instance here for Linux/Unix or there for MacOSX.


CFITSIO from Heasoft

The Heasoft suite of software packages for High Energy Astrophysics, also hosted at HEASARC and available as source files or precompiled binaries, includes a cfitsio library and its header files. However, trying to link HEALPix to that installation of cfitsio will generally fail, because It is therefore recommended to link HEALPix to a cfitsio library compiled locally and not included in Heasoft.
If Heasoft's cfitsio is to be used, Heasoft must have been compiled locally from source files, and the paths provided during the HEALPix configuration must be FITSDIR=${HEADAS}/../heacore/PLATFORM/lib and FITSINC=${HEADAS}/../heacore/PLATFORM/include (instead of the expected FITSDIR=${HEADAS}/lib and FITSINC=${HEADAS}/include) where PLATFORM depends on your computer and operating system and may look like x86_64-pc-linux-gnu-libc2.29.

CFITSIO, Fortran codes and Apple's ARM chips

If HEALPix-F90 codes (or any other Fortran code) are linked with cfitsio on Apple's ARM chips (M1 and M2), then version 4.1.0 (March 2022) or above of cfitsio must be used, see Section 2.

diff shows that the test files are different from the supplied files

This by itself is no cause for concern. When comparing using a diff on the test files will most likely report a difference even when the installation has been successful. This may be due to the fact that different installations have different floating point representations. Also, the FITS files carry date information.

Try unlimit

If you have unforeseen problems at runtime, try unlimit (under csh or tcsh) or ulimit (under sh or bash), in order to increase the heap and stack memory size. It sometimes helps.

hidl usage

We have found that in very rare cases the alias hidl is not recognised by the user's system. Usually, this is related to the local system's IDL script. A quick-fix is achieved by setting the environment variable IDL_STARTUP to be equal to the HEALPix startup file HEALPix_startup including the directory path to the file. This enables the user to access the HEALPix IDL procedures simply by invoking IDL. For example, in the typical installation documented above for a user running the tcsh shell, the command
setenv IDL_STARTUP /disk1/user1/HEALPix_3.83/src/idl/HEALPix_startup
should be issued (or added to the user's shell profile).

If the user already has an IDL startup file, then this should be merged with HEALPix_startup. This temporary solution does mean that the HEALPix IDL procedures are available in the IDL_PATH at all times, which may lead to conflicts with user-defined procedures. The hidl invocation was intended to circumvent these issues, allowing HEALPix IDL procedures to be available only when desired.

A proper fix requires the user to ask the local system administrator to adjust the local IDL script.

Using HEALPix IDL together with other IDL libraries

See the homonymous section in the "IDL Facilities Overview"


Mac OS X, X11 and IDL cursor

If the IDL cursor does not work correctly on X11 windows under Mac OS X, and the 2nd and 3rd button clicks are ineffective, type at your X11 prompt and restart X11.
Note that the command ls -lrt $HOME/Library/Preferences/*[xX]11*plist can be used to determine the X window system installed on your Mac. See also http://www.idlcoyote.com/misc_tips/maccursor.html and mollcursor documentation in "IDL Facilities").


Using GDL instead of IDL

GNU Data Language (GDL), is a free clone of IDL 7.1, with support for some IDL 8.0 features (for more information see https://github.com/gnudatalanguage/gdl). Both the source code and precompiled executables for various platforms are available.

When used to run IDL-Healpix routines, GDL 1.0.1 or more gives very satisfactory results6. The calculations agree with those done under IDL, with comparable computation times, but a few minor features, mostly related to the font selection, are missing.

GDL+HEALPix specific requirements

To fully enjoy GDL capabilities

Impact of GDL limitations on HEALPix


Using FL instead of IDL

Fawlty Language (FL) is a black-box implementation of IDL 8.0, for which precompiled self-contained packages are available for Linux, Windows, MacOSX and more from https://www.flxpert.hu/fl.

Most of the IDL routines and features have been implemented, with a few exceptions (like xloadct) and the restrictions listed below.

FL+HEALPix specific requirements

To fully enjoy FL capabilities

Impact of FL limitations on HEALPix


Appendix I: Recent Changes and New Features

Bug corrections and Improvements in Version 3.83

General


C++


IDL


Python

Bug corrections and Improvements in Version 3.82


C


C++

Fortran 90 facilities and subroutines


IDL


Python


Bug corrections and Improvements in Version 3.81

C++

IDL

Python


Bug corrections and Improvements in Version 3.80

General

C++

Fortran 90 facilities and subroutines

IDL

Python

Appendix II: Older changes (versions 3.00 to 3.70)

Bug corrections and Improvements in Version 3.70 (2020-07)General Fortran 90 facilities and subroutines IDL Python Bug corrections and Improvements in Version 3.60 (2019-12)General

C++

Fortran 90 facilities and subroutines IDL Python

Bug corrections and Improvements in Version 3.50 (2018-11)

Fortran 90 facilities and subroutines

C++ IDL Python

Bug corrections and Improvements in Version 3.40 (2018-06)

General

C++ Fortran 90 facilities and subroutines

IDL

Python

Bug corrections and Improvements in Version 3.31 (2016-08)

General

C++ Fortran 90 facilities and subroutines IDL Python

Bug corrections and Improvements in Version 3.30 (2015-10)

C++

Fortran 90 facilities and subroutines

IDL

Java

Python

Bug corrections and Improvements in Version 3.20 (2014-12)

General

C

C++

Fortran 90 facilities and subroutines

IDL

Java

Python

Bug corrections and Improvements in Version 3.11 (2013-04)

General

C++

Fortran 90 facilities and subroutines IDL

Bug corrections and Improvements in Version 3.10 (2013-03) General N/AC

C++

Fortran 90 facilities and subroutines

IDL

Java N/APython

Bug corrections and Improvements in Version 3.0 (2012-11)

General Introduction of the script healpix_doc for easy access to the HEALPix PDF and HTML documentation.

C

C++

Fortran 90 facilities and subroutines

IDL

Java

Python

About this document ...

HEALPix Facility Installation Guidelines

This document was generated using the LaTeX2HTML translator Version 2020 (Released January 1, 2020)

The command line arguments were:
latex2html -dir ../../healpix-dynamicPages/html -up_url main.htm -up_title 'Main Page' -down_url main.htm -down_title 'Main Page' -math -html_version 5.0,latin1 -antialias -bottom_navigation -short_extn -white -local_icons -noexternal_images -address 'Version 3.83, 2024-11-13' -info 1 -toc_depth 8 -split 3 -prefix install -external_file ./install -t 'Installing HEALPix' install

The translation was initiated on 2024-11-13

previous up next
Up: Main Page Next: Main Page Top: Main Page
Version 3.83, 2024-11-13