The eROSITA Science Analysis Software System (eSASS) for the eROSITA Data Release 1 (DR1), i.e., eSASS4DR1, is distributed in a tgz file for Ubuntu and macOS systems. eSASS is also distributed in a Docker-container, which can be used on Windows and other Linux distributions. Instructions on how to download, install, use eSASS4DR1 and the Docker-container can be found in the following.
On this page
The following table shows the operative systems were the eSASS4DR1 release was tested:
| OS family | Name | Version | CPU architecture | native compilation | Docker X86_64 | Docker ARM64 |
|---|---|---|---|---|---|---|
| MacOsX | Catalina | 10.15.7 | X86_64 | OK | OK slow | NO |
| MacOsX | Big sur | 11.7.10 | X86_64 | OK | Not tested | NO |
| MacOsX | Monterey | 12.6.8 | X86_64 | OK | OK | NO |
| MacOsX | Ventura | 13.6 | ARM64 | OK | NO | OK |
| Linux | Ubuntu bionic | 18.04 LTS | X86_64 | OK | Not supported | NO |
| Linux | Ubuntu Focal | 20.04 LTS | X86_64 | OK | OK | NO |
| Linux | Ubuntu Jammy | 22.04 LTS | X86_64 | OK | OK | NO |
A Docker container is available if your operating system is not listed in the table above. To figure out which type of Docker container to use, you need to identify your CPU type. Most Linux and Windows computers use X86_64 CPUs, while Mac "Silicon" uses ARM64 CPUs.
Please follow the instructions in the "Using eSASS on Windows and other Linux distributions" through the Docker section.
Minimum requirements:
The eSASS4DR1 package can be downloaded as a unique archive tarball from the following link:
The CALDB is also available as a unique tarball. You can download it via the following link:
Note: The size of the CALDB is roughly 2 GB. Please make sure that you have enough space before downloading it.
After downloading the eSASS4DR1 package, you must move the file to an installation folder (/<my eSASS path>/) and extract the content. You achieve this by executing the following command:
$ tar zxf eSASS4DR1.tgz
The eSASS4DR1 contains two subfolders: eSASS and external.
Similarly, the CALDB4DR1 can be extracted in a location of your preference. This exact CALDB location must be given as a parameter in the installation process (see below)
The eSASS software requires external packages to fully function (e.g., HEALPix, lapack, etc). While these libraries are supplied with the eSASS4DR1 package, you can use your installations or previous installations of such software. Two important external software installations, for which you must be very careful, are described in the following.
Note: The other software packages provided in the external directory will be built automatically.
There are two possibilities to configure HEALPix:
$ 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 Finally, execute: make.
The eSASS software also requires the fftw library installed in your system. In Ubuntu systems, it can be installed by typing sudo apt-get install fftw3 and sudo apt-get install libfftw3-dev in a terminal. This process requires administrator privileges, i.e., sudo password. In macOS systems, please install the fftw-3, fftw-3-long, and fftw-3-single, either using MacPorts or Brew.
macOS systems also require: autoconf, automake, coreutils, libtool, ncurses, readline, realpath, libpng, and perl.
From this point on, it is assumed that:
HEADAS.fftw library installed on your computer.You can proceed with the eSASS installation as described below.
Source your HEASOFT installation:
if you are using bash,
$ source $HEADAS/headas-init.sh
if you are using csh,
$ source $HEADAS/headas-init.csh
Go to the directory:
$ cd /<my eSASS path>/eSASS4DR1/eSASS/autoconf
The autoconf/automake needs to know the path to the various compilers. This can be done either by setting some environment variables before starting or during the configure command (see below). To set up the needed variables before to start
in bash:
$ export CC=/path/to/gcc $ export CXX=/path/to/g++ $ export FC=/path/to/gfortran $ export F77=/path/to/gfortran
in csh
% setenv CC /path/to/gcc % setenv CXX /path/to/g++ % setenv FC /path/to/gfortran % setenv F77 /path/to/gfortran
The eSASS4DR1 configuration of the installation is achieved by:
$ aclocal $ autoreconf -fi -v $ ./configure --with-caldb=/<my CALDB path>/ --with-healpix=/<my HEALPix path> \ --with-headas=$HEADAS --with-gsl=compile --with-lapack=system
If you have not set the environment variables for the compilers before, you can pass them during the configure command as follows:
$ FC=/path/to/gfortran F77=/path/to/gfortran CC=/path/to/gcc CXX=/path/to/g++ \ ./configure --with-caldb=/<my CALDB path>/ --with-healpix=/<my HEALPix path> \ --with-headas=$HEADAS --with-gsl=compile --with-lapack=system
To identify if the eSASS4DR1 configuration succeeded, the end of the configure command output must look like this:
### CALDB SETUP ### configure: Using caldb directory /full.path/to/caldb as you provided for setup ### Installation location: /<my eSASS path>/eSASS4DR1/eSASS ###
Continue the eSASS build by executing:
$ make $ make install
If you do not get any error messages, 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>/eSASS4DR1/eSASS/bin/esass-init.[c][z]sh
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 chose the option 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 Windows and Linux distributions different from Ubuntu can use Docker to run eSASS on their computers. Containerisation 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 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 four Docker containers based on the eSASS4DR1 installation available in the Docker Hub eROSITA repositories:
Two for the X86_64 CPUs (Intel) architecture family, two for the ARM64 (Apple silicon) CPUs architecture family. They follow the naming convention:
All 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 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/eSASS4DR1/bin/
The sources of the tasks are located in:
/home/idies/sw/eSASS4DR1/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 this:
X86_64:
$ docker run -it --rm erosita/esass-x64:latest /bin/bash
ARM64:
$ docker run -it --rm erosita/esass-arm64:latest /bin/bash
or the minimal version where the CALDB directory is mounted from /path/to/caldb on the host machine:
X86_64:
$ docker run --volume /path/to/caldb:/home/idies/caldb -it \ --rm erosita/esass-minimal-x64:latest /bin/bash
ARM64:
$ docker run --volume /path/to/caldb:/home/idies/caldb -it \ --rm erosita/esass-minimal-arm64: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.
To mount a local folder to be accessible from inside the Docker, to save your results, you can use the --volume option, in the following example the data in your home folder $HOME/ErositaData/
would be visible in the docker in the folder /home/idies/mydata :
$ docker run --volume $HOME/ErositaData/:/home/idies/mydata \ --rm <path-to-docker:tag> /bin/bash
It is possible to mount more than one external folder, you simply have to use one --volume per mounted folder.
In case the run command does not start the download automatically, the Docker image can be fetched manually with pull:
$ docker pull <path-to-docker:tag>
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 a container 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-x64:latest /bin/bash
If all goes well, programs like fv will work as expected now. Unfortunately, the details can vary a bit depending on the operating system and setup of the host machine. The above was tested on macOS.
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.
The eSASS team provides a script to test your eSASS4DR1 installation. This script can also help you learn to call the different eSASS tasks and code in python3 for exhaustive works with eROSITA data.
In the subfolder /<my eSASS path>/eSASS4DR1/eSASS/scripts/, you can find a python3 script named demoscript_4DR1.py. This script calls all the eSASS tasks with some predefined parameters. demoscript_4DR1.py takes two parameters as input: an event file name and an output folder name. You can give the relative or absolute path for both files. You can call the script's help by running:
python3 $SASS_ROOT/scripts/demoscript_4DR1.py -h