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.