Installing Solarsoft on a Mac
Updated: 28-Aug-2023.
This guide is
for an installation of Solarsoft IDL on a Mac. However, the steps are
valid for any Linux/Unix machine except for the final one
about Launch Daemons.
Before Starting
Shell selection
I use the default Mac shell zsh, which is very similar to
bash. The steps below are the same for bash except that the
.bashrc file is edited instead of .zshrc. If you use a C-shell
(csh or tcsh) then check the Additional Information section at
the bottom of this document.
If you want to change your shell, start up 'Terminal' and go to
'Preferences...'. Under 'General' you should see 'Shells open with:'.
To specify tcsh you would put '/bin/tcsh' in the 'Command'
box.
The .zshrc file
The .zshrc file may already exist on your computer. It is
found in your home directory, and it is automatically run when you
start a Terminal session. In the steps described below, you
will be asked to add entries to this file. Below I give an
example .zshrc file that contains the lines needed for Solarsoft.
Example .zshrc file for
SSW.
Whenever you make an addition or edit to your .zshrc file you need to do the
following to make sure the change is propagated to your session.
> source .zshrc
If you delete something from the .zshrc file, then you
should open a new shell window or tab to prevent the previous
setting from being remembered.
Modifying PATH
We will create shell scripts as part of the SSW installation
and these will go in the sub-directory "scripts". The directory
should be added to $PATH. This is done by adding the line below
to your .zshrc file:
export PATH=$PATH:$HOME/scripts
Installing wget
The Unix wget software is needed to perform Solarsoft
updates. Check if you already have wget installed by doing
'which wget' from the Unix command line.
If you don't have it, then next check if you have Anaconda
installed (e.g., for Python), then you can install wget with
> conda install wget
If you don't have Anaconda, then you can use Homebrew.
Please check
the instructions
at the Stereo Science Center website. You will need
admin privileges to install Homebrew.
XQuartz
In order to display graphics windows from IDL you will need an
X Window System for the Mac. The standard one is XQuartz
(https://www.xquartz.org/),
which was initiated by Apple but is not
distributed with Macs.
Once XQuartz is installed it should automatically start when
the IDL session begins (you should a new X icon appear on your
taskbar). If it doesn't, Harris provides a webpage with help information.
Step 1 - basic installation
Go to the Solarsoft
Installation form at LMSAL. For the drop down list 'SSW Path
Suggestions' select '$HOME/ssw'.
Do not click on any
of the options boxes for instruments. Instead go straight to the
'Generate installation script' button and click on it. Download the
script to your computer and run it with:
> csh -f [script_name]
This will download the files for the basic SSW installation,
and you should see the folder 'ssw' appear in your home directory.
Step 2 - run SSW IDL
Go to your .zshrc or equivalent file in your home directory
and add the following lines to it:
export SSW=$HOME/ssw
export SSW_INSTR="chianti eis sot xrt aia hmi eve secchi ssc iris so pfss psp"
export SSW_SITE_SETUP=$SSW/site/setup
The environment variable $SSW_INSTR is the one that determines
which instrument paths will be added to your SSW. This should be
customized to the instruments/packages that you use.
Now create a new file
called simply 'sidl' and put it in the directory 'scripts'. This file
should contain the following lines:
#!/bin/csh
source $SSW/gen/setup/setup.ssw
sswidl $argv
Warning: note that this is a C-shell script. If
your default shell is zsh or bash, then be careful if you have
an old .cshrc file in your home directory, as the above script will
run this instead of your default file (.zshrc or .bashrc).
The script needs to be executable, so do:
> chmod u+x sidl
If you now source your .zshrc file and do:
> sidl
your Solarsoft IDL session should start up.
Step 3 - perform first update of SSW
Now we want to update SSW for the first time, which will download all
the instrument paths defined by $SSW_INSTR. Go to your ~/scripts folder
and create a new file called 'update_ssw'. Put the following lines in
this file:
#!/bin/csh
$SSW/gen/bin/ssw_batch go_update_ssw
$SSW_SITE_SETUP/update_ssw.log
Make the script executable by doing:
> chmod u+x update_ssw
Now execute the script with:
> csh -f ~/scripts/update_ssw
which will download all the files for your instrument list.
This should take a long time (perhaps a few hours), and you can check progress by taking a
look at the file ~/ssw/site/setup/update_ssw.log.
Step 4 - setting up an automatic SSW update
The easiest way to do this is with a cron job, however
Apple recommend to implement these sorts of jobs through Launch Agents
and Daemons. It's possible that cron may be disabled in the future, but
it still works with MacOS 10.12 (Sierra). I suggest trying the Launch Daemon first, and then using cron if it fails.
Cron job
Open the cron file by doing:
> crontab -e
and insert the line:
30 12 * * * ~/scripts/update_ssw
which tells the computer to run the script at 12:30 every day.
Launch Daemon
It's first necessary to create a property list (plist) file.
The one I use
for updating SSW is available here.
Copy it to the directory $HOME/Library/LaunchAgents on your Mac, and
rename it 'com.ssw.plist'.
Now open this file with an editor, and you should see the line:
<string>/Users/young/scripts/update_ssw</string>
This is pointing to the location of the script that updates
SSW (see Step 3 above), and should be edited to your own upgrade script.
Further down the file you should see a tag for 'Minute' with a
value of 15, and another tag for 'Hour' with a value of 12. These mean
that the script will be called at 12:15. Since no other time
information is specified then the script will be run every day at this
time.
Further information about Launch agents and plists are
available from an Apple
webpage.
The script should start automatically, but you may need to
restart your computer. I suggest setting the update time to shortly
after your current time and then you should see the script start, e.g., by checking the ~/ssw/site/setup/update_ssw.log file.
Note: I was able to get this working on my MacBook, but it
failed on my iMac. I don't have admin privileges on my iMac, so this
may be the problem.
Additional information
IDL Startup file
This file is usually used to set additional environment variables associated with instruments or your personal work.
To use it, first create an idl_startup.pro file. I put mine in
~/idl_lib/idl_startup.pro. Then set the environment variable
$IDL_STARTUP to point to this file in your .zshrc file:
export IDL_STARTUP=~/idl_lib/idl_startup.pro
After sourcing your .zshrc file IDL will now execute the startup file when it starts up. Note this is independent of Solarsoft.
Please check my example startup file to see the sorts of things it can include.
Solarsoft Database directory (SSWDB)
A number of missions have sets of auxilliary files that are
not stored in the main SSW directory but instead in the Solarsoft
Database directory (usually referred to as SSWDB or SDB). You may find
that if you try to prep a mission data file the software will complain
that some calibration file is missing. Typically this file will be in a
SSWDB directory. An example of this behavior is for the SOHO/EIT instrument. Here I describe how to set up SSWDB.
Firstly, go to your .zshrc or equivalent file and add
export SDB=$HOME/sswdb
which will tell the software where you want your SSWDB files to be located.
Now, go to the directory $SSW/site/setup and you should see a
file called 'setup.sswdb_upgrade'. Open this file with a text editor
and you should see a list of entries that are commented out with "#".
Hopefully, amongst these entries you should see the instrument you are
interested in. I've attached my sswdb_upgrade file here and you'll see that I've uncommented soho/eit, soho/cds and some hinode directories.
When you upgrade SSW (see Step 3 or Step 4 above) then you
should find that your $SDB directory becomes populated with the
directories you specified.
The reason SSWDB is kept separately from SSW is that the
directory sizes can be very large, so you should be careful with which
directories you bring over. Also note that you may not need an entire
directory. For example, I bring over soho/eit/response rather than
soho/eit since I only need this for prepping EIT data. Check the
instrument analysis guides for details.
NOTE: I couldn't get the hinode/xrt/xrt_msu_coalign directory
to download. It turns out a sub-directory can only be downloaded if
it's listed in the file $SSW/gen/setup/sswdb_descriptions.dat.
C-shell users
If you are using a C-shell (csh, tcsh), then you need to swap
"export" commands to "setenv". For example, for Step 2 we have:
setenv SSW $HOME/ssw
setenv SSW_INSTR "chianti eis sot xrt aia hmi eve secchi ssc iris so pfss psp"
setenv SSW_SITE_SETUP $SSW/site/setup
These go in your .cshrc or .tcshrc file.
Page maintained by Dr Peter R Young.
|