WEBVTT 1 00:00:01.927 --> 00:00:07.000 Hi folks welcome to the HEASARC the High Energy Astrophysics Science Archive Research Center 1 00:00:08.000 --> 00:00:13.000 This video tutorial will go through the steps necessary to install HEASoft on your machine 1 00:00:13.100 --> 00:00:19.488 We'll explain some of the different aspects to pay attention to and share resources that will help you install the software 2 00:00:20.000 --> 00:00:22.900 If for some reason you can't install HEASoft on your machine 2 00:00:23.000 --> 00:00:26.900 For example if you don't have permissions to install software and your organization doesn't offer it 2 00:00:27.000 --> 00:00:32.900 you can download the pre-built binaries although they're not normally recommended or use a Docker image. 2 00:00:33.000 --> 00:00:35.000 Even better you can use SciServer. 2 00:00:36.000 --> 00:00:41.188 More information about those tools can be found linked from the software page. 3 00:00:41.809 --> 00:00:50.556 For this video we're going to be installing HEASoft from source on a Mac so let's get started with the installation process 4 00:00:51.202 --> 00:00:59.095 We're going to head here on the HEASoft web page you can see that the latest version is 6.34 5 00:00:59.413 --> 00:01:02.098 as of August 2024. 6 00:01:03.350 --> 00:01:12.626 If you've already downloaded the source code you can go ahead and click on the installation instructions for either PC Linux or Mac OS 7 00:01:13.958 --> 00:01:20.032 We're going to show how to grab a fresh download of the source code so I'm going to click on download here 8 00:01:22.740 --> 00:01:27.906 Note again we do recommend the source code distribution not the pre-compiled binaries 9 00:01:28.189 --> 00:01:30.370 So I'm going to click on source code 10 00:01:34.739 --> 00:01:37.859 And I'm on an Intel Mac 11 00:01:38.522 --> 00:01:46.000 On a OS X 14 so I'm going to select that check box and then you scroll down and step two where 11 00:01:46.100 --> 00:01:49.900 you download the desired packages you select which packages you want 11 00:01:50.100 --> 00:01:54.900 you can click all if you want every single package that's part of HEASoft 11 00:01:54.000 --> 00:02:01.000 then it'll come with all of the mission software all the general use the spectral analysis all of these tools. 11 00:02:01.000 --> 00:02:11.858 If you're curious what's in a tool you can click on a link. For example click on heatools and it will bring you this link of all the tools that are included. 12 00:02:12.462 --> 00:02:16.786 If I'm curious what is ftcreate you can click on it and find the help 13 00:02:17.006 --> 00:02:21.798 for that specific tool I'm going to go back. 14 00:02:22.223 --> 00:02:24.683 For example let's say I want Xspec 15 00:02:25.407 --> 00:02:30.121 Xspec comes packaged with the HEAGen tools and the HEASPtools those are often used together. 16 00:02:30.350 --> 00:02:40.906 And then I decide "oh I also want HEATools" I can just add that check mark "oh I actually want all of them" so I'm going to click all of the General-Use FTOOLS and it will get everything. 17 00:02:41.380 --> 00:02:49.414 And then you can hit submit and it will download that tarball for you so we will wait while that happens. 18 00:02:54.642 --> 00:03:04.527 Okay so the tool is downloaded and I've copied it into my ~/software directory. You can see here in my terminal. 19 00:03:07.134 --> 00:03:12.748 And here is the tarball that is about two and a half gigabytes. 20 00:03:14.054 --> 00:03:20.155 Now we're going to untar that file. 22 00:03:25.885 --> 00:03:29.000 And while that is untarring we're going to 23 00:03:30.000 --> 00:03:33.900 head back to the instructions. I'll hide my terminal for now. 23 00:03:34.000 --> 00:03:41.543 Head back to the the download page and scroll down step 3 Install the Software 24 00:03:42.213 --> 00:03:54.544 And then you can click on the link for which operating system you're on this machine is a Mac OS so I'm going to click on Mac OS and that will bring us to the more detailed instruction page 25 00:03:54.835 --> 00:03:56.794 For installing HEASoft 26 00:03:58.915 --> 00:04:02.900 So one thing to note about HEASoft one important thing is 26 00:04:03.000 --> 00:04:06.000 it's pretty straightforward at its core. 26 00:04:06.100 --> 00:04:11.000 It's the three basic gnu util steps of configure make and make install. 26 00:04:11.100 --> 00:04:17.219 But before we get to those steps first we're going to go over the prerequisites. 27 00:04:18.916 --> 00:04:23.305 We need the different compilers 28 00:04:24.956 --> 00:04:34.467 Stepping back we'll note that HEASoft on silicon Macs the default build is the native arm64 architecture 29 00:04:36.348 --> 00:04:41.137 And if you're on an Intel Mac it's an x86 architecture. 30 00:04:42.855 --> 00:04:52.000 So now we can scroll down and see what compilers are required. We do require C C++ Perl Fortran. 30 00:04:52.500 --> 00:04:55.718 We recommend the Apple Xcode C compilers 31 00:04:57.267 --> 00:05:03.369 And you can install them with the command listed on this page xcode-select --install 32 00:05:04.198 --> 00:05:11.000 We also require a Fortran compiler that is not provided by Xcode. Xcode doesn't include a Fortran compiler 32 00:05:11.100 --> 00:05:21.859 so you can download that from any of your preferred Mac package managers you can download it from Macports if you prefer that or Homebrew or any of your preferred package managers 33 00:05:23.235 --> 00:05:28.262 And just make sure that you know where it's installed after you install a Fortran compiler 34 00:05:31.734 --> 00:05:35.000 With installing a Fortran compiler through a third party package 34 00:05:35.100 --> 00:05:42.000 you do want to make sure that that third party package stays up to date with your Xcode command line tools the CLT. 34 00:05:42.100 --> 00:05:51.547 Since these third-party compilers use the CLT they need to be rebuilt and reinstalled whenever you update your CLT 35 00:05:54.482 --> 00:06:06.908 And then python if you are going to use any of these parts of HEASoft HEASoftPy PyXspec HEASP IXPE or NICER you also need python those tools used python 36 00:06:07.546 --> 00:06:25.040 So you can install that any of your preferred ways again one of the package managers using conda various ways that you can install python along with the required minimum versions of the extra packages pip astropy numpy scipy matplotlib 37 00:06:25.885 --> 00:06:36.786 And note also HEASoftPy uses pip during the installation during the building therefore it requires access to the internet while you're in the build step 38 00:06:40.121 --> 00:06:51.327 And then we're going to move on to environment variables. Before compiling it helps to set some environment variables to tell HEASoft where your compilers are 39 00:06:52.357 --> 00:06:53.939 So where your 40 00:06:57.187 --> 00:07:12.437 C compiler C++ Perl Fortran Python interpreter all of those are located. I'm on a bash I use bash in my terminal so I can copy these lines right here and I know that this is where 41 00:07:13.391 --> 00:07:17.319 my files are so I'm going to bring up my terminal again 42 00:07:18.338 --> 00:07:23.652 You can see that the tarball did untar. It took just a couple of minutes 43 00:07:25.126 --> 00:07:27.176 So I'm going to just paste those in. 44 00:07:28.389 --> 00:07:32.077 My Fortran compiler 45 00:07:32.077 --> 00:07:36.222 I downloaded Fortran using Macports 46 00:07:36.985 --> 00:07:42.414 and my Fortran compiler is in a different spot so I'm going to grab that from my notes 47 00:07:43.910 --> 00:07:46.128 I'm going to copy that in here. 48 00:07:52.283 --> 00:07:57.873 I'm on an Intel machine for Macports so you can see that this is where fortran 49 00:07:59.176 --> 00:08:00.896 was installed on my machine 50 00:08:01.576 --> 00:08:06.499 For my python I am using I have installed miniforge 51 00:08:07.300 --> 00:08:11.225 for my python so I'm going to copy that from my notes as well. 52 00:08:11.824 --> 00:08:14.598 There are all of my environment variables 53 00:08:15.839 --> 00:08:19.523 that I need to set before building HEASoft. 54 00:08:21.171 --> 00:08:23.295 The next step 55 00:08:25.195 --> 00:08:27.443 after setting your environment variables 56 00:08:28.704 --> 00:08:40.579 And there are some extra if you have trouble you can unset some of these flags. You can put your usr/bin in front of your path. Sometimes these help if there are difficulties with building or configuring. 57 00:08:41.275 --> 00:08:43.358 So then we're going to move on to configure. 58 00:08:43.718 --> 00:08:52.453 And configure just like any gnu util there is there a lot of options for configure. you can type configure --help 59 00:08:53.316 --> 00:08:57.336 well first I'm going to move into the directory. 60 00:09:01.261 --> 00:09:05.031 So we want to go into the BUILD_DIR directory. 61 00:09:05.465 --> 00:09:09.569 And we can see the configure file is listed right here. 62 00:09:15.135 --> 00:09:19.094 You can see all of the different standard options that come with configure. 63 00:09:20.113 --> 00:09:28.000 Some of these are very useful for example if you want to install your HEASoft in a different location than a default 63 00:09:28.100 --> 00:09:44.832 the default is under the heasoft-6.34 directory under a platform specific directory in there. If you want to install it for example let's say I want it just straight in my software or in my usr/bin I would do 64 00:09:47.220 --> 00:09:53.000 --prefix=/my/preferred/location 66 00:09:53.375 --> 00:10:02.152 and then it would install it into that location I want it in my default location so I'm going to stick there 67 00:10:03.841 --> 00:10:08.542 I'm going to then go ahead and just copy this 68 00:10:09.194 --> 00:10:18.085 This command it's redirecting the output of the configure command with this arrow into config.txt 69 00:10:19.266 --> 00:10:34.050 we do recommend redirecting all of your output into another file so that if there's a problem with any step of installing the software you can send us these text files and that will help us troubleshoot what went wrong on the system. 70 00:10:34.474 --> 00:10:36.555 So I'm just going to go ahead and copy that 71 00:10:37.067 --> 00:10:44.957 And paste that in here and then I'm going to wait. That'll take about 10 or 15 minutes and then we'll come back and move on to the next step. 72 00:10:49.381 --> 00:10:52.687 Okay and now the configure step has finished. 73 00:10:52.687 --> 00:10:55.993 you can see it took about 14 minutes. 74 00:10:56.724 --> 00:11:00.035 We're going to look at that log file. 75 00:11:00.422 --> 00:11:04.755 Before we can proceed to the next step the current step has to succeed. 76 00:11:04.755 --> 00:11:09.087 We're going to check and make sure that it succeeded so I'm just going to 77 00:11:09.087 --> 00:11:13.420 look at that file go all the way down to the end and it 78 00:11:13.420 --> 00:11:17.752 says Finished. That's great the last line is Finished that means it was successful 79 00:11:18.379 --> 00:11:22.273 n configuring. so now I'm going to 80 00:11:23.234 --> 00:11:26.371 Go on to the build step so I'm 81 00:11:26.371 --> 00:11:29.507 going to scroll down a little bit 82 00:11:30.255 --> 00:11:33.671 And I'm just going to again just copy that make 83 00:11:33.671 --> 00:11:37.087 sure we're redirecting the output into a log file 84 00:11:37.635 --> 00:11:40.532 so that I can check that later and if there's 85 00:11:40.532 --> 00:11:43.429 any problem we can look at that for troubleshooting. 86 00:11:44.763 --> 00:11:46.075 I want to copy that in 87 00:11:46.470 --> 00:11:50.736 And hit enter. The build step will take a lot longer. It could take 88 00:11:50.736 --> 00:11:55.001 a few hours even depending on how large your downloaded source tarball is and 89 00:11:55.001 --> 00:11:59.266 how powerful your machine is. So we will wait for this to finish now. 90 00:12:04.236 --> 00:12:07.870 Okay and now we can see that the make step has finished. 91 00:12:07.870 --> 00:12:11.504 Just as before we are going to make sure that it 92 00:12:11.504 --> 00:12:15.139 succeeded before we can move on to the next step. 93 00:12:15.643 --> 00:12:20.504 So I'm going to do just a tail on that file. Great 94 00:12:20.504 --> 00:12:25.364 and it says Finished make all so that step was successful. 95 00:12:25.696 --> 00:12:30.355 So now I can move on to the installation step. And 96 00:12:30.355 --> 00:12:35.015 you can see that it took about an hour from 1615 until 97 00:12:35.015 --> 00:12:39.674 17:19 on my machine and with the packages that I had 98 00:12:39.674 --> 00:12:44.333 downloaded in the source code tarball it took about an hour. 99 00:12:45.777 --> 00:12:48.314 The next step is installation so 100 00:12:48.314 --> 00:12:50.852 I will scroll up on 101 00:12:51.076 --> 00:12:55.730 the website behind step A4 Install. 102 00:12:57.513 --> 00:13:00.573 I can just copy 103 00:13:02.354 --> 00:13:07.088 this line again 'make install' I'm going to redirect it 104 00:13:07.088 --> 00:13:11.821 to a file called install.txt so that we can look 105 00:13:11.821 --> 00:13:16.555 for troubleshooting steps again and I will enter that 106 00:13:17.351 --> 00:13:22.262 Now while that's installing again as we talked about with the configure step 107 00:13:22.262 --> 00:13:27.174 it's going to install in the default location which is under the 108 00:13:27.174 --> 00:13:32.085 current HEASoft directory under a platform specific directory there if I 109 00:13:32.085 --> 00:13:36.996 had wanted to install the software elsewhere I would have added that 110 00:13:36.996 --> 00:13:41.908 prefix option to the configure step. Because I didn't it's going to 111 00:13:41.908 --> 00:13:46.819 install in the default and we'll find that once this install step finishes. 112 00:13:51.652 --> 00:13:55.529 Okay so now the install step has finished. 113 00:13:55.529 --> 00:14:00.869 I cleared my screen but you can see that 115 00:14:01.490 --> 00:14:07.460 the install text file is here. 117 00:14:08.961 --> 00:14:13.471 And we're going to check that as we did with other steps to make sure that it succeeded. 118 00:14:17.087 --> 00:14:20.126 Great and the last line is "Finished make install" 119 00:14:20.126 --> 00:14:23.166 so we know that that step succeeded. 120 00:14:23.762 --> 00:14:29.918 So now we are going to go up 122 00:14:30.550 --> 00:14:33.223 a directory into the main HEASoft-6.34 123 00:14:33.624 --> 00:14:36.691 directory and we're going to see 124 00:14:37.125 --> 00:14:40.657 Here is the install directory the x86 the platform 125 00:14:40.657 --> 00:14:44.190 specific directory is now under our HEASoft directory 126 00:14:44.413 --> 00:14:48.408 If I had specified with the configure command 127 00:14:48.408 --> 00:14:52.403 the prefix option if I had specified a different location 128 00:14:52.403 --> 00:14:56.398 then this platform specific directory 129 00:14:56.947 --> 00:14:59.960 it would not be here the install directories would be elsewhere. 130 00:15:00.946 --> 00:15:05.715 So for now the next step we are going to go to initializing. 131 00:15:05.715 --> 00:15:10.484 Initializing is required for every new terminal session that you want 132 00:15:10.484 --> 00:15:15.253 to use the HEASoft tools. You need to export HEADAS to 133 00:15:15.253 --> 00:15:20.022 export this path into a HEADAS environment variable the path 134 00:15:20.022 --> 00:15:24.791 to where it's installed and then you need to source this headas-init.sh file 135 00:15:24.791 --> 00:15:29.559 csh if you're using a C-shell. 136 00:15:30.457 --> 00:15:33.764 So I'm going to go into this x86 directory 137 00:15:34.803 --> 00:15:36.209 We can see 138 00:15:36.518 --> 00:15:40.801 those init files. We can see which directory we're 139 00:15:40.801 --> 00:15:45.083 in and I'm going to just do a shortcut export HEADAS=$PWD 140 00:15:46.678 --> 00:15:51.510 I can do that because that's where I am right 141 00:15:51.510 --> 00:15:56.343 now if you were going to put this as a shortcut or an alias 142 00:15:57.430 --> 00:16:01.341 Iin your RC file then you would need to spell out the entire directory. 143 00:16:02.310 --> 00:16:04.400 But right now I can echo 144 00:16:08.068 --> 00:16:10.586 that environment variable and show that it's pointing 145 00:16:10.586 --> 00:16:13.104 exactly where I want it to be. 146 00:16:13.747 --> 00:16:17.104 And now I'm going to source that file so 147 00:16:17.104 --> 00:16:20.461 I'm going to copy this command 148 00:16:20.461 --> 00:16:23.818 "source headas-init.sh" 149 00:16:24.912 --> 00:16:29.114 And now I can see that "which ftlist" 150 00:16:29.592 --> 00:16:31.607 it's here in my path. 151 00:16:32.156 --> 00:16:35.961 I can run the tools. I can run ftversion 152 00:16:35.961 --> 00:16:39.765 and see that I am using version 6.34. 153 00:16:40.293 --> 00:16:43.699 And that is how you get started in 154 00:16:43.699 --> 00:16:47.105 installing and then beginning to run the tools 155 00:16:47.105 --> 00:16:50.511 for HEASoft after it's initialized. 156 00:16:50.939 --> 00:16:55.399 Now to start actually using the tools and understanding how to do 157 00:16:55.399 --> 00:16:59.858 analysis there are a lot of user guides. For example, Xspec, 158 00:16:59.858 --> 00:17:04.317 a lot of the mission guides there have very detailed analysis 159 00:17:04.317 --> 00:17:08.776 help pages so you can explore the different missions and figure 160 00:17:08.776 --> 00:17:13.236 out what is best needed in order to analyze your data. 161 00:17:13.907 --> 00:17:18.599 And you can explore the HEASARC website for more guidance about actually 162 00:17:18.599 --> 00:17:23.290 using the software. If you have any questions about installing the software or 163 00:17:23.290 --> 00:17:27.981 if you've run into any troubles feel free to message our help desk. 164 00:17:28.700 --> 00:17:32.314 That is here at the very bottom 165 00:17:32.559 --> 00:17:37.438 of this installation guide there's a link to the help desk. So you can click that 166 00:17:37.438 --> 00:17:42.317 and message us if you have any difficulties. Good luck with your data analysis