The eROSITA Science Analysis Software System (eSASS) is distributed in a tgz file for Ubuntu systems. eSASS is also distributed in a Docker-container, which can be used on macOS, Windows and other Linux distributions. Directions on how to download, install and use eSASS and the Docker-container can be found in the following.
On this page
The eSASS package and the eROSITA calibration database are available at:
https://erosita.mpe.mpg.de/eSASS4EDR-download/
To download their contents, first, download the script eSASS4EDRmirror.sh. After downloading, confirm that the script is executable (the script can be done executable by typing chmod +x eSASS4EDRmirror.sh). Then, the script must be executed in a bash terminal:
$ ./eSASS4EDRmirror.sh
Executing this script will mirror all or parts of the eSASS4EDR-download area to your local disk. The script eSASS4EDRmirror.sh accepts the following command-line options:
eSASS: to download eSASS s/w for autoconf build (~200 MB).CALDB: to download calibration files (~2.0 GB).UDCAL: to update calibration files.DEMO: to download demo script (~12 kB).If for instance you are not interested in the demo script, you could execute the following:
$ cd /<my eSASS path> $ ./eSASS4EDRmirror.sh eSASS $ ./eSASS4EDRmirror.sh CALDB
After downloading, you should have this directory structure on your disk:
/<my eSASS path>/caldb /<my eSASS path>/demo /<my eSASS path>/sw_edr /<my eSASS path>/external /<my eSASS path>/unpack_edr.sh
Go to directory /<my eSASS path>/ and execute the following command:
$ ./unpack_edr.sh eSASS4EDR sw_edr
This will extract the full eSASS directory structure from the eSASS task archive in directory eSASS4EDR.
Start by building the Healpix software package, provided with eSASS. Go to directory
$ cd /<my eSASS path>/external/Healpix_3.50
and launch the configure script there:
gfortran). gcc).libcfitsio.a library.locate can be used to find the directory ~/lib/ where libcfitsio.a is placed, which comes with the HEASOFT installation). It is advisable to give the full path. Finally, execute: make.
Note: The other software packages provided in the external directory will be built automatically.
Go to directory:
$ cd /<my eSASS path>/eSASS4EDR/autoconf
to perform the configuration of the installation. This can be achieved by launching the configure script there.
There are two main libraries required by configure: Healpix and HEASOFT. In most cases you will have a "default" HEASOFT installation, so you will have to provide the additional argument --with-headas=/path/to/heasoft/, for example:
$ ./configure --with-healpix=/<my eSASS path>/external/Healpix_3.50 --with-headas=$HEADAS
The Healpix option requires the absolute path.
You should be notified if you are missing crucial libraries on your system, such as GSL. You can now either specify to compile these libraries or install them on your own (for example, --with-gsl=system). In general eSASS ships with the source code for missing libraries except for HEASOFT. To avoid issues with automake versions it is recommended to first execute autoreconf. Moreover, on some systems configure will report executing aclocal before you run configure again.
Thus a more complex setup can look like this:
$ autoreconf -i $ aclocal $ ./configure --with-caldb=yes --with-healpix=/<my eSASS path>/external/Healpix_3.50 \ --with-headas=$HEADAS --with-gsl=compile --with-fftw=compile --with-lapack=compile
Continue the eSASS build by executing:
$ make $ make install
If you do not get any error message, congratulations! Your eSASS build should now be complete.
Finally, run the command
$ make clean
to optionally remove files that are no longer needed after the completion of the build.
To enable the eSASS environment, execute the following command (either sh or csh version):
$ source /<my eSASS path>/eSASS4EDR/bin/esass-init.[c]sh
Available task patches will be announced. Make sure your eSASS task archive is current by executing the eSASS4EDRmirror.sh script as described under Downloading. Then go to directory $SASS_ROOT/erosita/task/ and execute the following command:
$ tar -xzf $SW_EXPARCH/<task>_<n.m>.tgz
where <task> and <n.m> are the task name and version you want to update to. Then, go to the directory /<my eSASS path>/eSASS4EDR/build/ and execute:
$ make clean
Finally, go to /<my eSASS path>/eSASS4EDR/autoconf and execute:
$ make $ make install
You can also downgrade to a previous task version in the same way.
If the execution of the configure command for eSASS ends with the message:
checking for library containing hpsharp_execute... no configure: error: healpix not found
Check that you have compiled Healpix without OMP support meaning you choose the answer 0 when asked for
Do you want to use : 0) the standard serial implementation ? 1) the parallel implementation
One can check if Healpix was compiled using OMP support by executing
$ grep -n openmp Makefile
If the output looks like
Makefile:30:F90_FFLAGS = -O3 -I$(F90_INCDIR) -DGFORTRAN -fno-second-underscore -fopenmp -fPIC Makefile:32:F90_CFLAGS = -O3 -std=c99 -DgFortran -fopenmp -fPIC
it means that Healpix was compiled with OMP support. Therefore, Healpix should be re-configured before proceeding.
Users with macOS, Windows and Linux distributions different from Ubuntu can use Docker to run eSASS on their computers. Containerization systems like Docker are meant as a way to distribute applications and their dependencies in a stable, lightweight way. For our usage here think of it as a small virtual machine that comes with eSASS and HEASoft pre-installed.
To start an eSASS container you need to install a Docker client and get it running in your machine:
Please note that a Docker client should not be simply be installed on servers with multiple users as that would introduce the possibility to circumvent file permissions on that machine. If this setup is unavoidable please consider setting up the client to run in Rootless mode.
There are two Docker containers based on the eSASS4EDR installation available in the Docker Hub eROSITA repositories:
Both Docker containers are configured to use the CALDB from /home/idies/caldb. The environment variable CALDB is set to $CALDB=/home/idies/caldb and for esass-minimal it is expected that the external CALDB gets mounted there.
The eSASS software in the containers comes pre-compiled, but they also contain the source code of the eSASS software and of all its tasks. When launching the containers, the esass-init.[c]sh script is already launched and the programs can immediately be used. The binaries are located in:
/home/idies/sw/eSASS4EDR/bin/
The sources of the tasks are located in:
/home/idies/sw/eSASS4EDR/erosita/task/<taskname>
All software was built against the HEASoft installation in /opt/heasoft.
With the Docker client running you should be able to start a container running the full esass image like so:
$ docker run -it --rm erosita/esass:latest /bin/bash
or the minimal version where the CALDB directory is mounted from /path/to/caldb on the host machine:
$ docker run --volume /path/to/caldb:/home/idies/caldb -it --rm erosita/esass-minimal:latest /bin/bash
Note: The first execution of a Docker run command should start downloading the Docker image onto disk and it will take some minutes. The next executions of a Docker run on a previously downloaded image will be faster.
For an in-depth description of the command-line arguments used in the calls above you can refer to the reference manual online,
but in short -it starts the container in an interactive session, --rm removes the container after execution and -v or --volume makes host machine directories accessible inside the container.
The call to Bash, in the end, is the command that gets executed in the container, so together with -it, it will dump you in a shell inside the running container.
One can of course specify other commands here such as direct calls to eSASS commands or scripts to execute.
In case the run command does not start the download automatically, the Docker image can be fetched manually with pull:
$ docker pull erosita/esass:latest
This is also the command to use when a new eSASS user release comes out. The pull command will update the locally stored image from the registry.
Just like a virtual machine, a Docker container behaves a lot like a remote Linux machine from the perspective of the host computer, and a bit of effort needs to be spent to make it convenient to work in this setup. There are also a number of caveats one needs to be aware of:
The docker run commands above will start a container that only exists until one exits the shell again - with the next initialisation one gets a completely fresh copy. This means that any files which get written inside a container disappear with it.
While it is possible to keep a container running and connect to it, it is still advisable to keep your data and programs outside of it.
The easiest way to accomplish that is to use the -v / --volume option as above. The option can be used several times to mount many different directories.
An extension of the point above, the software installed inside it resets itself with each new container. So while it is possible to install missing python modules or install a program locally they would be gone the next time. There are a number of ways around this problem:
docker commit to add it to your local repository. Each container you now start from your new image will have the software installed.
You would, of course, have to do this again the next time a new eSASS version comes out, so if you see yourself doing this often you can automate the process by creating a Dockerfile that uses an eSASS image as the base.
In order for programs running inside the Docker container to display graphical user interfaces on the X-window system of the host machine the $DISPLAY variable needs to get set inside the container and connections have to be allowed on the host machine:
$ xhost + 127.0.0.1 # allow access to xhost from localhost 127.0.0.1 being added to access control list $ docker run -ti --rm -e DISPLAY=host.docker.internal:0 erosita/esass:latest /bin/bash
If all goes well programs like fv will work as expected now. Unfortunately, the details can vary a bit depending of the operating system and setup of the host machine. The above was tested on macOS.
There is a known problem with X11 forwarding on macOS and docker. Please have a look on this page for a solution. In addition to the listed Macs it was also tested on Macbook pro M1 silicon (arm 64) running SONOMA V14.5, Docker Desktop 4.25.0, XQuartz 2.8.5 (xorg-server 21.1.6).
It can be that the default memory and CPU settings inside the client after installing, may be a bit low to work on the data. If this is the case, when running an eSASS task the user might get the following error:
died with <Signals.SIGKILL: 9 >.
The most probable cause is the lack of memory in the Docker. The solution is to increase the memory allowed to the Docker client. To do this, go to the Docker engine Dashboard.