-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathinstall.tex
3513 lines (3222 loc) · 163 KB
/
install.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% -*- LaTeX -*-
\documentclass[12pt,twoside]{article}
%\usepackage{titlesec,xr-hyper,healpix,graphicx,html,makeidx}
\usepackage{xr-hyper,healpix,graphicx,html,makeidx,dirtree}
%xr-hyper first to have correct Equation and Figure cross-referencing in html
%putting hyperref first screws up references in html
%%%
\usepackage{ae,lmodern}% load vectorial font, keep PDF small *and* good quality when in T1 font
\usepackage[T1]{fontenc}% underscore searchable in PDF, but larger PDF http://latex-community.org/forum/viewtopic.php?t=8891
\usepackage{tocloft} % to indent sections in TOC https://texblog.org/2011/09/09/10-ways-to-customize-tocloflot/
\begin{htmlonly}
\input{hpxversion}
\input{idlversion}
\input{gdlversion}
\input{flversion}
\input{hpyversion}
\input{healpix_src_url}
\input{hpxwebsites}
\end{htmlonly}
\hypersetup{%
pdftitle={HEALPix Installation Guidelines},%
pdfauthor={E. Hivon et al},%
pdfkeywords={HEALPix, Installation},%
colorlinks=true}
\newcommand{\nside}{N_{\mathrm{side}}}
\newcommand{\npix}{N_{\mathrm{pix}}}
\newcommand{\lmax}{\ell_{\mathrm{max}}}
\newcommand{\doubledash}{\latexhtml{-{}-}{-{}--}}
\renewcommand{\contentsname}{{TABLE OF CONTENTS}}
% in LaTeX2HTML:
% \hyperref{HTML text}{PDF text1}{PDF text2}{label}
% in PDFTeX:
% \hyperref{URL}{cat}{name}{text}
%
% command for external link
\newcommand{\linklatexhtml}[3]{% \linklatexhtml{name}{latex_target}{html_target}
\latexhtml{\htmladdnormallink{#1}{#2}}{\htmladdnormallink{#1}{#3}}}
% commands for arbitrary link
\newcommand{\mylink}[2]{% \mylink{link_id}{link_text} (internal link)
\latexhtml{\hyperlink{#1}{#2}}{\hyperref{#2}{}{}{#1}}}
\newcommand{\mylinkext}[2]{% \mylink{link_id}{link_text} (external link)
\latexhtml{\htmlref{#2}{#1}}{\hyperref{#2}{}{}{#1}}}
%\latexhtml{\hyperref[#1]{#2}}{\hyperref{#2}{}{}{#1}}}
%\latexhtml{\hyperref{#2}{}{}{#1}}{\hyperref{#2}{}{}{#1}}}
% \newcommand{\mylink}[2]{% \mylink{link_id}{link_text}
% \latexhtml{\hyperlink{#1}{#2}}{\htmlref{#2}{#1}}}
% \newcommand{\mylink}[2]{% \mylink{link_id}{link_text}
% \latexhtml{\hyperref{#1}{}{}{#2}}{\hyperref{#2}{}{}{#1}}}
% commands for targets
% http://tex.stackexchange.com/questions/17057/hypertarget-seems-to-aim-a-line-too-low
\makeatletter
\newcommand{\nop}[1]{\Hy@raisedlink{\hypertarget{#1}{}}}
\makeatother
\newcommand{\mytarget}[1]{\nop{#1}}% \mytarget{id}
\begin{htmlonly}
\newcommand{\mytarget}[1]{\label{#1}}
\end{htmlonly}
% \newcommand{\crossref}[3]{% \crossref{text}{latex_target}{html_target}
% \latexhtml{\htmlref{#1}{#2}}{%
% \htmladdnormallink{#1}{#3}}}
% \newcommand{\crossref}[3]{% \crossref{text}{latex_target}{html_target}
% \latexhtml{\htmlref{#1}{#2}}{%
% \htmlref{#1}{#2}}}
%%%%%\externalref{#1}{#2}}}
%\begin{latexonly}
%\end{latexonly}
%\input psfig
\sloppy
\setcounter{secnumdepth}{10}%must be non-zero for cross-reference of Figs and Sections
\setcounter{tocdepth}{10}
\newcounter{append}
%\newcounter{figure}
%\newcounter{tab}
% CROSS-LINK
%%%%http://tex.stackexchange.com/questions/41539/does-hyperref-work-between-two-files
%% add xr-hyper (part of hyperref) to used packages, *BEFORE* hyperref (or html)
\newcommand{\facname}{} % must be here because it is in idl.tex
\newcommand{\FACNAME}{} % must be here because it is in idl.tex
\externaldocument{intro}[intro.pdf]
%\externaldocument{install}[install.pdf]
\externaldocument{csub}[csub.pdf]
\externaldocument{idl}[idl.pdf]
\externaldocument{facilities}[facilities.pdf]
\externaldocument{subroutines}[subroutines.pdf]
\begin{htmlonly}
\externallabels{.}{/tmp/introlabels.pl}
\externallabels{.}{/tmp/intro_labels.pl}
%\externallabels{.}{/tmp/installlabels.pl}
\externallabels{.}{/tmp/csublabels.pl}
\externallabels{.}{/tmp/csub_labels.pl}
\externallabels{.}{/tmp/idllabels.pl}
\externallabels{.}{/tmp/idl_labels.pl}
\externallabels{.}{/tmp/facilitieslabels.pl}
\externallabels{.}{/tmp/fac_labels.pl}
\externallabels{.}{/tmp/subroutineslabels.pl}
\externallabels{.}{/tmp/sub_labels.pl}
\end{htmlonly}
%%%%%
\begin{document}
\title{\healpix Facility Installation Guidelines}
\docid{INSTALLATION GUIDE}
\docrv{Version \hpxversion}
\author{Eric Hivon, Anthony J.~Banday, Matthias Bartelmann, Benjamin D.~Wandelt,
Frode K.~Hansen and Krzysztof M.~G{\oacute}rski}
\abstract{This document describes the installation for the \healpix facilities.}
%\input{hpxwebsite}
%\website{\hpxws}
\defwebsite
\date{\today}
\frontpage
\tableofcontents
\newpage
\section{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, {\em or} as a zipped file,
which can respectively be unpacked by executing the commands\footnote{Microsoft Windows users can have a look at \\
\url{https://sourceforge.net/p/healpix/wiki/Windows\%20and\%20peazip/}} \hfill\newline
%\begin{verbatim}
\texttt{\% gunzip Healpix\_\hpxversion.tar.gz}\hfill\\
\texttt{\% tar -xpf Healpix\_\hpxversion.tar}\hfill\\
or \hfill\\
\texttt{\% tar -xzpf Healpix\_\hpxversion.tar.gz}\hfill\\
or \hfill\\
\texttt{\% unzip Healpix\_\hpxversion.zip}\hfill\\
%\end{verbatim}
creating a directory named \texttt{Healpix\_\hpxversion}\ whose structure is shown in Figure
\ref{fig:dirtree}.
% Dir_tree figures produced by make_dir_tree.csh
\begin{figure}[!ht]
\latexhtml{%for latex
% cf extratbb -vO image_file
%\centerline{\includegraphics[bb=0 0 418 284,width=\textwidth,clip]{fig/new_dir_tree.pdf}}
\centerline{\includegraphics[bb=0 0 399 295,width=\textwidth,clip]{fig/new_dir_tree.pdf}}
}{%for html
\centerline{\includegraphics[width=520pt]{fig/new_dir_tree}}% %\centerline{\psfig{figure=fig/dir_tree.eps,width=\textwidth}}
% \latexhtml{%for latex
% % cf extratbb -vO image_file
% %\centerline{\includegraphics[bb=0pt 0pt 562pt 478pt,width=\textwidth,clip]{fig/dir_tree.pdf}}
% \centerline{\includegraphics[bb=0 0 506 430,width=\textwidth,clip]{fig/dir_tree.pdf}}
% }{%for html
% \centerline{\includegraphics[width=0.5\textwidth]{fig/dir_tree}}
}
\caption[Directory structure]{%
\label{page:dirtree}
\label{fig:dirtree} % put \label *IN* \caption !!!!!
The directory structure for the \healpix distribution. }
\end{figure}
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: \hfill\newline
\noindent AIX, IRIX, IRIX64, Linux, SunOS, ALPHA and Darwin (MacOS) \hfill\newline
There may be problems in the facility build due to the local system
configuration which is beyond our control.
\section{Installation Requirements}
\label{sec:requirements}
%--------------------------------------------------------------------
\begin{table}[!h]
\begin{tabular}{p{0.15\hsize} p{0.35\hsize} p{0.4\hsize}} \hline
\textbf{Healpix Package} & \textbf{Information on installation} &
\textbf{Information on routines}\\ \hline
& & \\ %%% for presentation
%
Fortran 90 & This document &
\linklatexhtml{"Fortran Facilities"}{facilities.pdf}{facilities.htm} and
\linklatexhtml{"Fortran Subroutines"}{subroutines.pdf}{subroutines.htm} documents \\
%
& & \\
%
IDL/GDL/FL & This document &
\linklatexhtml{"IDL Facilities"}{idl.pdf}{idl.htm}\\
& & \\
%
C++ & This document &
% C++ & This document, or \phantom{filling up --} \texttt{src/cxx/README.compilation} &
%\htmladdnormallink{"C++ Facilities and Subroutines"}{index_cxx.html}
\linklatexhtml{"C++ Facilities and Subroutines"}{../html/index_cxx.html}{index_cxx.html}
(HTML only)\\
%
& & \\
%
C & This document, or \phantom{filling up --} \texttt{src/C/README} &
\linklatexhtml{"C Subroutines Overview"}{csub.pdf}{csub.htm} \\
%
& & \\
%
Java & \texttt{src/java/README} &
%\htmladdnormallink{"Java Overview"}{java/index.html}
\linklatexhtml{"Java Overview"}{../html/java/index.html}{java/index.html}
(HTML only)\\
%
& & \\
%
Python & This document, or \phantom{filling up --} \texttt{src/healpy/INSTALL} &
\linklatexhtml{"Healpy
Documentation"}{https://healpy.readthedocs.io/en/latest}{https://healpy.readthedocs.io/en/latest}
(HTML only)\\
%
& \\ \hline %%% for presentation
\end{tabular}
\caption[Documentation]{%
\label{page:allpackages}
\label{tab:allpackages} % put \label *IN* \caption !!!!!
Documentation on the installation and usage of the different packages}
\end{table}
%--------------------------------------------------------------------
The major part of the \healpix distribution is written in both \textbf{Fortran 90} and \textbf{C++} and
so the appropriate compiler(s) must be present (Linux and Darwin users should look
at Section~\ref{sec:freef90compilers} about free F90 compilers. Microsoft Windows
users should look at Section~\ref{sec:windows}). Many visualisation tools and map
manipulation routines are provided in \textbf{IDL} (please note
that at least version \idlversion is required), \textbf{Java} and \textbf{Python}. Some of the \healpix routines are
also available in \textbf{C}. \\
Starting with version 3.0, the
\linklatexhtml{healpy}{\hpysite}{\hpysite}
(HEALPix in \textbf{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 \texttt{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 \texttt{libsharp} library,
also included in the package, and which was further optimized in
\mylink{install:v360}{version 3.60}.
{\em This section and the next focus on the compilation and installation of the
\textbf{C}, \textbf{C++}, \textbf{Fortran~90}, \textbf{IDL} and
\textbf{Python} routines and \textbf{libsharp} library. For more information on the
\textbf{Java} routines see table~\ref{tab:allpackages}.}
The configure script is written in the Bourne shell. The script
attempts to generate a \texttt{Makefile} which is tailored to one of
the above Operating Systems (OS's) and using
\texttt{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 (\url{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 \textbf{Fortran 90}, \textbf{C++}, \textbf{C} and \textbf{Python} distributions also
require the publicly available CFITSIO library.
Versions 4.2.0 (Nov 2022) or higher are recommended since they simultaneously meet
\textbf{Fortran 90} routines requirements, fix previous security vulnerabilities
and are compatible with Apple's ARM chips.
% Note that the
% \textbf{Fortran 90} routines require
% version 3.20 or more (post August 2009)
% of CFITSIO on most platforms, except on Apple's ARM (M1 and M2) chips, which
% require version 4.1.0 (March 2022) or more. Out of security concerns, the CFITSIO developers recommend using version 3.44 (April 2018) or more.
\begin{tabular}{p{0.3\hsize} p{0.6\hsize}} \hline
\textbf{Software Package} & \textbf{Source} \\ \hline
& \\ %%% for presentation
CFITSIO V 4.2.0 or more
& \url{https://heasarc.gsfc.nasa.gov/fitsio/}
\\
& \\ \hline %%% for presentation
\end{tabular}\vspace{3ex}
The \textbf{IDL} visualization software is commercially
available at
\begin{tabular}{p{0.3\hsize} p{0.6\hsize}} \hline
\textbf{Software Package} & \textbf{Source} \\ \hline
& \\ %%% for presentation
IDL V \idlversion or more & \url{https://www.harrisgeospatial.com/Software-Technology/IDL}
\\
& \\ \hline %%% for presentation
\end{tabular}\vspace{3ex}
%
while the GNU Data Language \textbf{GDL}, a {\em free open} clone of IDL 7.1,
or
the freeware Fawlty Language \textbf{FL}, a {\em free closed} clone of IDL 8,
can also be used (with some
caveats, listed respectively in \S\ref{install:using_gdl} and \S\ref{install:using_fl}) and can be downloaded for free from
\begin{tabular}{p{0.3\hsize} p{0.6\hsize}} \hline
\textbf{Software Package} & \textbf{Source} \\ \hline
& \\ %%% for presentation
GDL \gdlversion\ or more &
\url{\gdlsite}
\\ %%% for presentation
FL \flversion or more &
\url{\flsitea} or \url{\flsiteb}
\\
& \\ \hline %%% for presentation
\end{tabular}\vspace{3ex}
%\vspace{3ex}
%(versions 5.3 to 6.2 have been extensively used during the development
%of the \healpix IDL codes).
As it was already the case in version 1.20, users no longer need to acquire the
\textbf{IDL}
Astronomy User's Library
%(\url{https://idlastro.gsfc.nasa.gov/homepage.html})
(\url{https://github.com/wlandsman/IDLAstro})
or the COBE (IDL) Analysis Software (\url{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 \hpxversion\ are contained in the
subdirectory \texttt{Healpix\_\hpxversion/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 \textbf{Python} \texttt{healpy} package requires
\begin{tabular}{p{0.3\hsize} p{0.6\hsize}} \hline
\textbf{Software Package} & \textbf{Source} \\ \hline
& \\ %%% for presentation
Python 3.9 or more & \url{https://www.python.org}
\\
Numpy 2.0 or more & \url{https://numpy.scipy.org}
\\
Matplotlib 0.91.2 or more & \url{https://matplotlib.sourceforge.net}
\\
Cython & \url{https://cython.org}
\\
Astropy.io.fits & \url{https://www.astropy.org}
\\
(PyFITS) & \url{https://pypi.org/project/pyfits/3.3}
\\
& \\ \hline %%% for presentation
\end{tabular}\vspace{3ex}
While not required, the
\texttt{IPython} (\url{https://ipython.org})
and
\texttt{jupyter} (\url{https://jupyter.org})
interfaces can also be useful.
% For convenience we provide the freely available FFTPACK\footnote{At
% {\tt
% http://math.nist.gov/cgi-bin/gams-serve/list-package-components/FFTPACK.html}}
% routines "rffti", "rfftf" and "rfftb".
%
%% At the user choice (at installation time) the FFT operations can be
%% performed with the FFT code shipped with the package, or with the
%% freely available FFTW. In the latter case FFTW should be compiled in
%% double precision.
A parallel implementation (based on OpenMP, for shared memory architectures) of the Spherical Harmonics
Transforms involved in \textbf{F90} \texttt{synfast, anafast, smoothing, plmgen, alteralm}
and \textbf{C++}
\texttt{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 \textbf{F90}
subroutines documentation for more information on how to use those routines in
your code.
%% , thanks to the work of St\'ephane Colombi. It has
%% only been tested on SGI and DEC computers.
%% At this point, it can \textbf{not} be used together with FFTW.
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 \textbf{C++} and \textbf{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}$.
%% One of us (BDW) has therefore attempted to create one and we
%% provide it as free software with this package (cf. Appendix I).
\section{\texttt{healpix\_doc}: an easy access to \healpix documentation}
\mytarget{install:healpix_doc}
The shell script \texttt{healpix\_doc} now is available to provide easy
access to the HTML, PDF and/or EPUB documentation of {\em 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 \texttt{\$HEALPIX/doc}) or on remote web sites. To use it, simply type\\
\mycode{\$HEALPIX/healpix\_doc -e} or\\
\mycode{\$HEALPIX/healpix\_doc -h} or\\
\mycode{\$HEALPIX/healpix\_doc -p}\\
to access respectively the EPUB, HTML and PDF documentation. The default browser and
viewers used by \texttt{healpix\_doc} can {\em optionally} be set with the
environment variables
\texttt{\$HEALPIX\_HTML\_BROWSER},
\texttt{\$HEALPIX\_EPUB\_VIEWER} and
\texttt{\$HEALPIX\_PDF\_VIEWER}.\\
\htmladdnormallink{EPUB}{https://en.wikipedia.org/wiki/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 {\em free} ones we tested, we can recommend
\begin{itemize}
\item \texttt{ebook-viewer}, included in the open source Calibre e-book manager package
(\url{https://calibre-ebook.com}, used to generate the \healpix EPUB files)
available for many platforms, including Linux, MacOS and Windows,
\item \texttt{Books} (formerly iBooks), pre-installed in MacOS and \htmladdnormallink{available for download}{https://apps.apple.com/us/app/apple-books/id364709193} for iOS and watchOS,
\item the cost-free, ad-free
\htmladdnormallink{\texttt{Lithium EPUB reader}}{https://play.google.com/store/apps/details?id=com.faultexception.reader&hl=en} for Android.
\end{itemize}
\section{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, \texttt{Makefile.in} should be copied as \texttt{Makefile} and explicitly
tailored to the user environment.
\begin{flushright}
\begin{tabular}{p{0.3\hsize} p{0.60\hsize}}
\texttt{\% ./configure} {\em [-L] [\doubledash auto=<list>]} & uses \texttt{Makefile.in} as a template to build
the correct Makefile (from user inputs as required), it
will also configure the IDL/GDL/FL routines\\
\texttt{\% make} & builds all the facilities \\
\texttt{\% make test} & tests all the facility previously compiled \\
\texttt{\% make clean} & removes object (\texttt{*.o}) files \\
%%%%%\texttt{\% make vclean} &
\texttt{\% make tidy} & removes object files, module files (\texttt{*.mod}), executables and libraries \\
\texttt{\% make distclean} & same as above and restores the directories to the state of the
original distribution \\
%% \texttt{\% ./config\_preview} & configure the IDL previewer
\end{tabular}
\end{flushright}
These different steps are detailed below.
\subsection{./configure [-L] [\doubledash auto=<list>] [-h] [-v]}
\label{sub:configure}
\mytarget{install:configure}
The \texttt{./configure} script manages the configuration of the C, C++,
Fortran90, IDL and Python suites of routines and facilities.
An online help is available with
\texttt{./configure~-h}, while
\texttt{./configure~-v}
will return the \healpix release number (currently \hpxversion) and exit.
The \texttt{-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
\S\ref{subsub:conf}).
Using the \texttt{-L} option is recommended when doing a {\em project} or {\em system wide} installation of
\healpix to be accessed by several different users.
Two new features have been introduced in \mylink{install:v360}{version 3.60}.
\begin{itemize}
\item The \texttt{configure} script now supports the \texttt{\doubledash auto=}{\it <list>}
option to perform an automated (batch) configuration of the various packages using default answers
provided by the script (possibly customized with environment variables described below)
where {\it <list>} is a comma separated list of items to be configured, to be chosen (and combined)
among
\begin{itemize}
\item \texttt{all}: (re-)configures everything; \\
\texttt{\doubledash auto=all} is the same as \texttt{\doubledash auto=profile,sharp,c,cxx,f90,idl,healpy};
\item \texttt{c}: configures C and the required items, same as \texttt{profile,c};
\item \texttt{cxx}: configures C++ and the required items, same as \texttt{profile,cxx},\\
libsharp will also be configured, compiled and installed if it was not previously done;
\item \texttt{cpp}: same as \texttt{cxx} (see above);
\item \texttt{f90}: configures F90 and the required items, same as \texttt{profile,f90},\\
libsharp will also be configured, compiled and installed if it was not previously done;
\item \texttt{idl}: configures IDL and the required items, same as \texttt{profile,idl};
\item \texttt{sharp}: forces the (re-)configuration, compilation and installation of libsharp (required by F90 and C++);
\item \texttt{profile}: configures user or system configuration files (required by C, C++, F90 and IDL);
\item \texttt{healpy}: configures healpy.
\end{itemize}
\item If the environment variables
\texttt{CC} (C compiler, relevant for C,C++,F90,healpy,sharp),
\texttt{C\_FITS}, \texttt{C\_SHARED} (\mylink{install:C:config}{C}),
\texttt{CXX}, \texttt{CXXFLAGS}, \texttt{CXX\_PARAL} (\mylink{install:cpp_config}{C++}),
\texttt{FC}, \texttt{F\_AR}, \texttt{F\_DIRSUFF}, \texttt{F\_OPT},
\texttt{F\_PARAL}, \texttt{F\_SHARED} (\mylink{install:f90:config}{F90}),
\texttt{FITSDIR}, \texttt{FITSINC} (C,C++,F90),
\texttt{PYTHON} (\mylink{install:healpy:config}{healpy}),
\texttt{PROFILE\_EDIT} (\mylink{install:profile}{profile}),
\texttt{SHARP\_COPT}, \texttt{SHARP\_PARAL} (\mylink{install:libsharp:config}{sharp}),
and \texttt{papersize}, \texttt{ps\_com}, \texttt{pdf\_com}, \texttt{gif\_com} (\mylink{install:idlgdlconfig}{IDL})
%see configure -h
are defined prior to calling the \texttt{configure} script, they will change the
default values proposed in the (interactive or automated) configuration process.\\
\mytarget{install:configure:boolean}%
\textbf{The online help \texttt{./configure~-h} will show the current value of these variables.}\\
As detailed further down, several of these variables are \textbf{boolean} in nature, with the values
\texttt{1}, \texttt{y}, \texttt{Y}, \texttt{t} or \texttt{T} meaning 'true',
and
\texttt{0}, \texttt{n}, \texttt{N}, \texttt{f} or \texttt{F} meaning 'false'.
\end{itemize}
These two new features can of course be combined.
For instance, in Bourne related shells (eg, \texttt{sh, bash, dash, ksh, zsh}), the command\\
\texttt{FC=ifort CC=icc ./configure \doubledash auto=f90}\\
and in C related shells (eg, \texttt{csh, tcsh})\\
\texttt{setenv FC ifort ; setenv CC icc ; ./configure \doubledash auto=f90}\\
will automatically run the \texttt{configure} script for the \texttt{libsharp} (if not previously done)
and \texttt{f90} package items, using Intel's Fortran and C compilers.
\mytarget{install:profile}%
\subsubsection{Configuration profile}%
\label{subsub:conf}%
%
A feature introduced in previous releases and enhanced since v2.10, is that
the configure script creates a shell configuration file \hfill\\
(located in
\texttt{\$\{HOME\}/.healpix/\hpxverstex\_}{\em $\langle$OS\_TYPE$\rangle$}\texttt{/config}
or in
\hfill\\
\texttt{\$\{HEALPIX\}/confdir/\hpxverstex\_}{\em $\langle$OS\_TYPE$\rangle$}\texttt{/config}
if \texttt{./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 \mylink{install:configure:boolean}{boolean}
environment variable \texttt{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 \mylink{install:configure:boolean}{boolean} environment variable \texttt{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.
\textbf{In particular, you will have to make sure that the \texttt{HEALPIX} system variable is correctly
defined (as the full path to the \healpix directory) before running
the package}.
% And finally, the current \texttt{./configure} script allows several compilations of
% the Healpix routines to coexist by letting the user choose the name of directories
% containing the executables, libraries and include files.
\mytarget{install:C:config}%
\subsubsection{C configuration}%
%
The \texttt{./configure} script will ask for the C compiler and options to
be used, and for the full path of an installed \texttt{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 \texttt{CC}, \texttt{C\_FITS} (\mylink{install:configure:boolean}{boolean}), \texttt{FITSDIR}, \texttt{FITSINC}
and \texttt{C\_SHARED} (\mylink{install:configure:boolean}{boolean}) can be used to control the script behavior.\\
After compilation
(see \texttt{make} section) and linking, all libraries will be
in \texttt{\$\{HEALPIX\}/lib/chealpix.*}\ .\\
See also \S\ref{sec:pkg-config} on \mylink{install:pkg-config}{\texttt{pkg-config}}.
\mytarget{install:cpp_config}%
\subsubsection{C++ configuration}%
\label{sec:cpp_config}%
%
Starting with \mylink{install:v360}{version 3.60}, the \texttt{./configure} script will be used to
provide information (like the choice of C++ compiler and options)
to an automated (\texttt{autoconf} generated) configure script,
(located in \texttt{src/cxx/configure}), which will take care of the configuration.\\
The environment variables \texttt{CC}, \texttt{CXX}, \texttt{CXXFLAGS}, \texttt{FITSDIR} and \texttt{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 \texttt{cfitsio} installation on its own.\\
The configuration of \mylink{install:libsharp:config}{\texttt{libsharp}} will be also taken care of at this stage.\\
The \mylink{install:configure:boolean}{boolean} variable \texttt{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 \texttt{CXX\_PARAL=0} and make sure no OpenMP related flags appear in \texttt{CXXFLAGS}.\\
At odds with previous versions, the C++ binaries, libraries and header files will be installed in
\texttt{\$\{HEALPIX\}/bin},
\texttt{\$\{HEALPIX\}/lib} and
\texttt{\$\{HEALPIX\}/include} directories respectively.
\\
If the \healpix configuration file is sourced as described in \S\ref{subsub:conf}, the full path to the C++
executables will be added to the environment PATH variable.\\
See also \S\ref{sec:pkg-config} on \mylink{install:pkg-config}{\texttt{pkg-config}}.
\mytarget{install:f90:config}%
\subsubsection{Fortran 90 configuration}%
%
When you run \texttt{./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 set\footnote{In particular, the Intel Fortran
Compiler, available for free for Linux systems with Intel-like processors, have
specific tuning options for each Intel processor family and instructions set. Please consult
the online help (\texttt{ifort -help}) or PDF documentation ({\tt
/opt/intel/composer*/Documentation/en\_US/Release\_NotesF.pdf}) or HTML documentation
(\texttt{
/opt/intel/composer*/Documentation/en\_US/documentation\_f.htm}) for further
information.}.
From our experience,
we have not found significant accumulation of numerical error even
when using the most aggressive optimisation level available. \\
The environment variable \texttt{FITSDIR}, \texttt{CC}, \texttt{FC},
\texttt{F\_AR}, \texttt{F\_DIRSUFF}, \texttt{F\_OPT},
\texttt{F\_SHARED} (\mylink{install:configure:boolean}{boolean}) and \texttt{F\_PARAL} (\mylink{install:configure:boolean}{boolean}) can be used to customize the configuration.\\
The configuration of \mylink{install:libsharp:config}{\texttt{libsharp}} will be also taken care of at this stage.\\
If the \healpix configuration file is sourced as described in \S\ref{subsub:conf}, the full path to the F90
executables will be added to the environment PATH variable.\\
See also \S\ref{sec:pkg-config} on \mylink{install:pkg-config}{\texttt{pkg-config}}.
\mytarget{install:idlgdlconfig}%
\subsubsection{IDL/GDL/FL configuration}%
\label{install:idlgdlconfig}%
%
You will be asked for the external applications, such as \texttt{gv}, \texttt{xpdf}, \texttt{display},
$\ldots$ you want to use to visualize the
GIF, JPEG, PDF, Postscript and PNG files \mylinkext{idl:mollview:preview}{created by IDL, GDL or FL}. \\
The environment variables \texttt{papersize}, \texttt{ps\_com}, \texttt{pdf\_com} and \texttt{gif\_com} can be
used to customize this configuration.\\
If the \healpix configuration file is
sourced as described in \S\ref{subsub:conf}, the aliases
\texttt{hidl} (\texttt{hidlde}),
\texttt{hgdl} (\texttt{hgdlde}) and/or
\texttt{hfl} (\texttt{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 \linklatexhtml{\healpix IDL Document}{idl.pdf}{idl.htm} for more
information on using \healpix IDL/GDL/FL together with other IDL libraries, and \S\ref{install:using_gdl},\ref{install:using_fl} on using GDL or FL instead of IDL.
\subsubsection{Java installation}%
\mytarget{install:java:config}%
%
The configuration and installation of the \healpix Java package is currently
handled separately. See table~\ref{tab:allpackages} for more information.
\mytarget{install:healpy:config}%
\subsubsection{Python (healpy) installation}%
\label{install:healpy:config}%
%
% The \texttt{./configure} script will
% ask for the parent directory containing the \texttt{lib/libcfitsio.*} library and
% the {\tt
% include/fitsio.h} include file (therefore \texttt{/usr/local} or \texttt{/usr} often are the correct
% choices) and
% the environment variable CFITSIO\_EXT\_PREFIX
% will be set accordingly.\\
% The configuration and installation of the Healpix Python package (healpy) is currently
% not handled by the \texttt{configure} script: see table~\ref{tab:allpackages} for more
% information.
The \texttt{./configure} script will ask for the Python command you want to use
(in case many coexist on your computer) and will check that its version number meets the \texttt{healpy} requirements (see above), as well as for C and C++ compilers.\\
The environment variables \texttt{PYTHON}, \texttt{C} and \texttt{CXX} can be used to customize the configuration process.\\
Note that during the compilation with \texttt{make} (see below), the
\texttt{src/healpy/setup.py} Python script will be invoked to automatically prompt a {\em fresh} compilation of the
\texttt{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 \texttt{healpy} compilation will very likely
require an active network connection in order
to download on the fly some of the required Python ancillary packages.
\mytarget{install:libsharp:config}%
\subsubsection{libsharp library}%
\label{install:libsharp:config}%
%
The \texttt{libsharp} C-written library for optimized Spherical Harmonics operations
is used by the C++, Fortran, IDL and healpy routines and facilities.
Starting with \mylink{install:v360}{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 \texttt{CC} and \texttt{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 \texttt{-ffast-math}
and \texttt{-march=native} (or your compiler's equivalent options), and may look like
\texttt{SHARP\_COPT='-O3 -ffast-math -march=native -fopenmp'} (multi-worded values must be enclosed in quotes).\\
If you are using \texttt{gcc} or \texttt{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 \texttt{-march=native} by \texttt{-DMULTIARCH}.\\
If you are using \texttt{clang} to compile \texttt{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 \texttt{-fopemp=libomp} or \texttt{-fopemp=libiomp5}
instead of the usual \texttt{-fopemp}
or by specifying the location of the OpenMP libraries during compilation and at run time).\\
The \mylink{install:configure:boolean}{boolean} variable \texttt{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 \texttt{libsharp}, set \texttt{SHARP\_PARAL=0} and make sure no OpenMP related flags appear in \texttt{SHARP\_COPT}.\\
After compilation and installation (which, for \texttt{libsharp} only,
are done as early as the \texttt{configure} step)
the resulting library will be in
\texttt{\$\{HEALPIX\}/lib/libsharp*} and the header files in
\texttt{\$\{HEALPIX\}/include/libsharp/sharp*.h}.\\
See also \S\ref{sec:pkg-config} on \mylink{install:pkg-config}{\texttt{pkg-config}}.
\subsection{Compilation and installation}
The \\
\mycode{make} \\
command will compile one or several of the C, C++, F90, libsharp and Python packages
depending on what was configured with the \texttt{./configure} script.
Specific packages can be compiled with the respective commands
\begin{verbatim}
make c-all
make cpp-all
make f90-all
make sharp-all
make healpy-all
\end{verbatim}
To perform several compilation jobs simultaneously, the command \texttt{make -j }\textit{[number\_of\_jobs]}
can be used.
Please neglect any possible warnings at compile time. If you run into
trouble please refer to the section \htmlref{{\bf Troubleshooting and further
information}}{sec:troubleshoot}.
After running \texttt{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.
\subsection{Testing the installation}
All installed libraries and executables can be tested with
\begin{verbatim}
make test
\end{verbatim}
while specific tests of the C, C++ and Fortran products can be performed with,
respectively
\begin{verbatim}
make c-test
make cpp-test
make f90-test
make sharp-test
make healpy-test
\end{verbatim}
For \texttt{f90-test}, Table~\ref{tab:f90_tests} lists the codes tested with the
parameter files used, as well as the data files produced and the respective
reference files.
\begin{table}[!h]
\footnotesize
\begin{tabular}{lllll}
\hline
{\bf code} \& parameter file & output data & reference data & output image & reference image \\
\hline
{\bf synfast} syn.par & test\_map.fits & map.fits & test\_map.gif & map.gif \\
& test\_alm.fits & alm.fits & {\em NA} & {\em NA} \\
{\bf smoothing} smo.par & test\_sm.fits & map\_sm.fits & test\_sm.gif & map\_sm.gif \\
{\bf ud\_grade} udg.par & test\_LOres.fits & map\_LOres.fits & test\_LOres.gif & map\_LOres.gif \\
{\bf hotspot} hot.par & test\_ext.fits & map\_ext.fits & test\_ext.gif & map\_ext.gif \\
& test\_max.asc & max.asc & {\em NA} & {\em NA} \\
& test\_min.asc & min.asc & {\em NA} & {\em NA} \\
{\bf anafast} ana.par & test\_cl.fits & cl\_out.fits & {\em NA} & {\em NA} \\
{\bf ---} ana2maps.par & test\_cl2maps.fits & cl2maps.fits & {\em NA} & {\em NA} \\
{\bf ---} ana\_w2.par & test\_cl\_w2.fits & cl\_w2.fits & {\em NA} & {\em NA} \\
{\bf alteralm} alt.par & test\_almdec.fits & almdec.fits & {\em NA} & {\em NA} \\
{\bf median\_filter} med.par & test\_mf.fits & map\_mf.fits & test\_mf.gif & map\_mf.gif \\
{\bf sky\_ng\_sim} ngfs.par & test\_ngfs.fits & map\_ngfs.fits & test\_ngfs.gif & map\_ngfs.gif \\
{\bf process\_mask} prmask.par & test\_distmask.fits & distmask.fits & test\_distmask.gif & distmask.gif \\
\hline
\end{tabular}
\caption[Data files]{
\label{page:f90_tests}
\label{tab:f90_tests} % put \label *IN* \caption !!!!!
\footnotesize
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 \texttt{Healpix\_\hpxversion/test} directory. The GIF images of full sky maps were
produced using \texttt{map2gif}. {\em NA}: No image available, because the data set
is not a sky map}
\normalsize
\end{table}
{\bf{Notes:}}
\begin{itemize}
\item the input power spectrum (in {\tt
Healpix\_\hpxversion/test/cl.fits}) used to generate the Fortran90 test maps
is currently the WMAP 1yr best fit, in $(\mu{\mathrm{K}})^2$, and is therefore different from the one
included in releases 1.* (that can still be found in \texttt{cl\_old.fits}).
% See \htmladdnormallink{\texttt{ http://lambda.gsfc.nasa.gov/}}{http://lambda.gsfc.nasa.gov/}
% for details on WMAP and its data products.
\item Other input fiducial $C(\ell)$, all in $(\mu{\mathrm{K}})^2$ and defined on the multipole range
$[0, \lmax]$, have been included for convenience in
\htmladdnormallink{\texttt{Healpix\_\hpxversion/test/}}{\srcurl test}
in a \healpix compatible format.
\\
%\begin{table}
\begin{tabular}{llll}
\hline
%%%% \textbf{File name} & \textbf{alias} & \textbf{Origin} & $\lmax$\\ \hline
{\bf File name} & {\bf alias} & {\bf Origin} & $\lmax$ \\ \hline % better in latex2html
wmap\_lcdm\_pl\_model\_yr1\_v1.fits & cl.fits &
\htmladdnormallink{WMAP}{https://lambda.gsfc.nasa.gov/}-1yr (2005) & 3000 \\
wmap\_lcdm\_sz\_lens\_wmap5\_cl\_v3.fits & cl\_wmap5.fits & WMAP-5yr (2008) & 2000 \\
wmap\_lcdm\_sz\_lens\_wmap7\_cl\_v4.fits & cl\_wmap7.fits & WMAP-7yr (2011) & 3726 \\
planck2013ext\_lcdm\_cl\_v1.fits & cl\_planck1.fits &
\htmladdnormallink{Planck}{https://www.cosmos.esa.int/web/planck} 2013 & 4500 \\
planck2015\_lcdm\_cl\_v2.fits & cl\_planck2.fits & Planck 2015 & 4900 \\
planck2018\_lcdm\_cl\_v3.fits & cl\_planck3.fits & Planck 2018 & 5000 \\
\hline
\end{tabular}
% \caption[Cl files]{
% \label{page:cl_files}
% \label{tab:cl_files} % put \label *IN* \caption !!!!!
% Available $C(l)$ files
% }
% \end{table}
\\
For more information on their respective origin and underlying model see their FITS header, or
\htmladdnormallink{\texttt{Healpix\_\hpxversion/test/README}}{\srcurl test/README}.
%
% \item the file {\tt Healpix\_\hpxversion/test/wmap\_lcdm\_sz\_lens\_wmap5\_cl\_v3.fits}
% was added for convenience, even though
% it is currently *NOT* used for any of the simulated test maps.
% It has been adapted to run with \healpix from WMAP 5yr best fit model for
% $\Lambda$-CDM + SZ + lensing with B mode = 0, in $(\mu$K$)^2$ (input file:
% \htmladdnormallink{{\footnotesize{\tt http://lambda.gsfc.nasa.gov/data/map/dr3/dcp/params/c\_l/wmap\_lcdm\_sz\_lens\_wmap5\_\-cl\_v3.dat}}}{http://lambda.gsfc.nasa.gov/data/map/dr3/dcp/params/c_l/wmap_lcdm_sz_lens_wmap5_cl_v3.dat}).
% For the value of the cosmological parameters, see
% \htmladdnormallink{{\footnotesize{\tt http://lambda.gsfc.nasa.gov/product/map/dr3/params/lcdm\_sz\_lens\_wmap5.cfm}}}{%
% http://lambda.gsfc.nasa.gov/product/map/dr3/params/lcdm_sz_lens_wmap5.cfm}
% %
% \item the file {\tt Healpix\_\hpxversion/test/wmap\_lcdm\_sz\_lens\_wmap7\_cl\_v4.fits}
% was added for convenience, even though
% it is currently *NOT* used for any of the simulated test maps.
% %
% \item Planck2013
% %
% \item Planck2015
\end{itemize}
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
\texttt{hidl} (or \texttt{hidlde}), \texttt{hgdl} (or \texttt{hgdlde}), or \texttt{hfl} (or \texttt{hflde}).
\subsection{Cleaning up}
Three levels of cleaning are available:
\begin{verbatim}
make clean
\end{verbatim}
will remove the intermediate files created during compilation, such as object
files, (Fortran) modules files, ... found in the source or build directories;
\begin{verbatim}
make tidy
\end{verbatim}
same as above, and will also remove the \healpix executables, libraries and module and/or
include files;
\begin{verbatim}
make distclean
\end{verbatim}
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, \texttt{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
\texttt{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.
\subsection{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 \texttt{pkg-config} facility
(now available on many systems, including Linux, Unix*, MacOS and MS Windows),
following the procedure described in \S\ref{sec:pkg-config} on \mylink{install:pkg-config}{\texttt{pkg-config}}.
% \section{Upgrading from 2.0 to 2.1}
% The internal structure of release 2.1 is quite different from release 2.0 and to
% avoid confusion during the compilation we highly recommend to put the new
% release in a {\em different} directory, rather than putting the new package on
% top of the old one.
% If you actually change the name of the 'active' \healpix directory care must be taken that
% all references to the old directory are removed from your system profile before
% adding the new ones (see Note on {\it Re}-installation).
% \section{Upgrading from 2.10 to 2.11}
%% See the \htmladdnormallink{\healpix Primer}{intro.htm} for a note on the change of convention for polarization.
\section{A Note on {\it 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.
\section{Pkg-config files}
\label{sec:pkg-config}
\mytarget{install:pkg-config}
Starting with \healpix 3.12, \texttt{pkg-config} (\texttt{.pc}) files are generated
during the configuration of the
\mylink{install:libsharp:config}{libsharp},
\mylink{install:C:config}{C},
\mylink{install:cpp_config}{C++} and
\mylink{install:f90:config}{F90} packages, and are initially located respectively in
\texttt{\$\{HEALPIX\}/lib/pkgconfig/libsharp.pc},
\texttt{\$\{HEALPIX\}/lib/pkgconfig/chealpix.pc},
\texttt{\$\{HEALPIX\}/lib/pkgconfig/healpix\_cxx.pc},
and \hfill \\
\texttt{\$\{HEALPIX\}/lib}{\em suffix}\texttt{/pkgconfig/healpix.pc}.
If the
\htmladdnormallink{\texttt{pkg-config} software}{https://en.wikipedia.org/wiki/Pkg-config}
is available on your system (see
\url{https://www.freedesktop.org/wiki/Software/pkg-config/} to download, install and
use it) and if the location of
the \healpix \texttt{pkg-config} files above are known to it (either by moving/copying them
to one of the standard locations returned by \hfill \\
\texttt{pkg-config \doubledash variable=pc\_path pkg-config}\\
or by customizing the environment variable \texttt{PKG\_CONFIG\_PATH}%
\footnote{a third option is provide the location of the \texttt{.pc} file in full at each
\texttt{pkg-config} invocation : {\it eg}\\ {\tt
pkg-config \doubledash cflags \doubledash libs }{\em full\_path}\texttt{/healpix.pc}}),
then linking your own or third-party code with the
C,
C++,
F90 \healpix library simply becomes \\
\texttt{cc `pkg-config \doubledash cflags \doubledash libs chealpix` mycode.c -o mycode} \\
\texttt{c++ `pkg-config \doubledash cflags \doubledash libs healpix\_cxx` mycode.cpp -o mycode} \\
{\em FC} \texttt{ `pkg-config \doubledash cflags \doubledash libs healpix` mycode.f90 -o mycode}\\
(where {\em FC} has to be replaced by the Fortran compiler used to generate the
\healpix library).
\section{Troubleshooting and further information}
\label{sec:troubleshoot}
This section contains a list of difficulties which we have dealt
with. It is by no means exhaustive.
In case of problems, see \url{\healpixsupport} or contact \healpixmail
% A troubleshooting forum has
% been established at \htmladdnormallink{{\tt \healpixwebpage/healpixSoftwareProblemsBugsSolutions.shtml}}{\healpixwebpage/healpixSoftwareProblemsBugsSolutions.shtml}, where we
% list current questions and solutions to known problems (for
% a given release). A bug tracker is also available on SourceForge \htmladdnormallink{at this address}{http://sourceforge.net/tracker/?group_id=130539&atid=718128}.
% If the problem you encounter is not addressed in those forums nor below,
% please contact \healpixmail
\subsection{Free Fortran90/95 Compilers}
\label{sec:freef90compilers}
Some {\bf free} Fortran90/95 compilers that can be used to compile \healpix are listed below.
They all support the few Fortran 2003 features used in \healpixns.
\begin{itemize}
%
\item {\bf Intel Fortran} compilers for Linux based computers \texttt{ifx}
(since version 2021) and previously
\texttt{ifort} (versions
11.* to 19.*\footnote{problems have been reported with one of the code (\texttt{sky\_ng\_sim}) when compiled with
\texttt{ifort 14.0.1.106}}) \hfill \\
\url{https://software.intel.com/en-us/fortran-compilers}
%%%%%http://www.intel.com/software/products/compilers/downloads/forlin.htm}}{http://www.intel.com/software/products/compilers/downloads/forlin.htm}
%
\item {\bf GNU Fortran 95} compiler (\texttt{gfortran}) included in GNU Compiler Collection {\em GCC} version 4.0.0
and up and available for Linux, Mac OSX, Windows, Sun ... platforms
\hfill \\
\url{https://www.gnu.org/software/gcc/fortran/}. \hfill \\
GFortran binaries for all platforms can also be downloaded from \hfill \\
\url{https://gcc.gnu.org/wiki/GFortranBinaries}. \hfill \\
Please note that only recent versions of \texttt{gfortran} (Aug 2005
and later) compile \healpix correctly, and v4.2.1 and more have given satisfying
results so far, including native OpenMP support.
%
\item {\bf Nvidia's LLVM-based Fortran} compiler (\texttt{flang}) available as pre-compiled executables and libraries for Linux \hfill \\
\url{https://www.scivision.co/flang-compiler-build-tips} \hfill \\
and as source files for all platforms \hfill \\
\url{https://github.com/flang-compiler/flang/wiki/Building-Flang}.
%
\item {\bf Nvidia's PGI Fortran} (formerly Portland Group) compilers (\texttt{pgf90}) available as freemium (without support) or commercially for Linux, Mac OSX and Windows from
\hfill \\ \url{https://www.pgroup.com/index.htm}.
%
\item {\bf G95} compiler available for Linux, Mac OSX, Windows, Sun and HP platforms with 32 and 64 bit architectures (eg, x86 and x86-64). In the latter case, the '32bit default integer' (32bit DI) version of \texttt{g95} {\em must} be used. Note that this compiler was last released in 2013, and it generally generates slower codes
than the compilers listed above.
\hfill \\ \url{http://www.g95.org}
\end{itemize}
See \url{http://fortranwiki.org/fortran/show/Compilers} for an extended list of free, freemium and commercial Fortran compilers.
%\newpage %------------ TEMPORARY