Step-by-step usage

Downloading the OSA docker image

Download the Docker image from the public Docker Hub to which ISDC has uploaded the software. (This requires 2.6 Gb of disk space and in Internet connection.)

From the Terminal command line type:

• docker pull integralsw/osa

(Note that you can also specify a version with docker pull integralsw/osa:11.1, where the number after the colon, here 11.1, is a tag to the version. There are also 11.0 and 10.2 docker images if you want to download those versions. Omitting the tag will result in downloading the latest version, which is the recommended way.

Docker images will be stored in a system directory. Images can be listed from the command line with the instruction:

• docker image ls

(see documentation for details, e.g., https://docs.docker.com/engine/reference/commandline/images/)

The command:

• docker rmi ``Image-name''

will remove an image.

Defining the arguments and options

Any OSA command can be executed in the docker container after some settings.

The container acts as a separate OS in which the OSA initialization is performed internally with the script ``/init.sh''. However, we have to provide through our local OS input data and a place to write the results. This can be done in the way explained below.

Any OSA command inside the docker image is run from the command line as:

• docker run [arguments] integralsw/osa command

Let's first create temporary directories to mount the home and pfiles to be visible within the docker image. This will avoid ``polluting'' our working directory with unnecessary outputs ($$ is a variable that stores the shell's process ID number²):

• mkdir -pv /tmp/osa-home-$$
• mkdir -pv /tmp/osa-home-$$-pfiles

These directories will be identified and mounted using the docker options

• -v /tmp/osa-home-$$-pfiles:/pfiles
• -v /tmp/osa-home-$$:/home/integral

It is necessary to specify the user name in the docker image to be the same as in the native OS, which is done with the options:

• -rm -it -user $(id -u) -entrypoint=''

The the graphical interface options are defined as:

• -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix on Linux;
• -e DISPLAY=$ip:0 -v /tmp/.X11-unix:/tmp/.X11-unix on OS-X.

Uning Docker,it is easy relax the requirement to use an OSA compliant directory, as described in https://www.isdc.unige.ch/integral/download/osa/doc/11.1/osa_um_intro/index.html. We can run the software somewhere and keep in separated places the ic_tree and the archive. Following the instructions in Section , we can download the ic_tree in a folder which we can refer to with the shell variable CURRENT_IC. Following Section , we can store the archive in a place referred to with the shell variable REP_BASE_PROD These directories will contain the folders ic,idx (CURRENT_IC) and scw,aux (REP_BASE_PROD). We should can mount this directory with the options:

• -v $REP_BASE_PROD/scw:/data/scw:ro \
• -v $REP_BASE_PROD/aux:/data/aux:ro \
• -v $CURRENT_IC/ic:/data/ic:ro \
• -v $CURRENT_IC/idx:/data/idx:ro \

The output data will be contained in the working dir.

In conclusion, these are the arguments and options we need to run OSA within the docker.

• -e DISPLAY=$DISPLAY \
• -v /tmp/.X11-unix:/tmp/.X11-unix \
• -v $PWD:/home/integral \
• -v $REP_BASE_PROD/scw:/data/scw:ro \
• -v $REP_BASE_PROD/aux:/data/aux:ro \
• -v $CURRENT_IC/ic:/data/ic:ro \
• -v $CURRENT_IC/idx:/data/idx:ro \
• -rm -it -user $(id -u) -entrypoint=''\

In OS-X (for a graphical interface, remember to issue xhost + $ip in your shell before running OSA) and change the first line with -e DISPLAY=$ip:0.

Running OSA Commands

We are now ready to work on the <command> to run OSA tasks. Since we need to define some environment variables, it is better to run a shell that will 1) define variables, 2) initialize OSA, and 3) cd into the working directory.

Our command will then be:

• 'bash -c
• export HOME_OVERRRIDE=/home/integral;
• . /init.sh;
• cd \$HOME;
• <our OSA commands>'

Catalogs are shipped with the docker image. However, it is possible to use custom catalogs. What is needed is to place them in a folder mounted in the docker image.

We suggest to place the catalogs in the standard locations in your local file

• $PWD/cat/my_gnrl_refr_cat.fits

and

• $PWD/cat/my_omc_refr_cat.fits

And use them in the call within docker as:

• 'bash -c \
• export HOME_OVERRRIDE=/home/integral;\
• . /init.sh;\
• cd \$HOME;\
• ISDC_REF_CAT=/home/integral/cat/my_gnrl_refr_cat.fits;\
• ISDC_OMC_CAT=/home/integral/cat/my_omc_refr_cat.fits;\
• <our OSA commands>'

We are ready to run og_create program to build our OSA observation group. We use IBIS as a example and assume that we have stored our list of science windows in the file list_scw.txt.

The OSA command is

• og_create idxSwg=list_scw.txt ogid=my_og \
• baseDir=$REP_BASE_PROD instrument=IBIS

However, we have to prepend all the necessary arguments for docker to run properly.

• docker run \
• -e DISPLAY=$DISPLAY \
• -v /tmp/.X11-unix:/tmp/.X11-unix \
• -v $PWD:/home/integral \
• -v $REP_BASE_PROD/scw:/data/scw:ro \
• -v $REP_BASE_PROD/aux:/data/aux:ro \
• -v $CURRENT_IC/ic:/data/ic:ro \
• -v $CURRENT_IC/idx:/data/idx:ro \
• -rm -it -user $(id -u) -entrypoint=''\
• 'bash -c
• export HOME_OVERRRIDE=/home/integral;
• . /init.sh;
• cd \$HOME;
• og_create idxSwg=list_scw.txt ogid=my_og \
• baseDir=$REP_BASE_PROD instrument=IBIS'

This will create a directory obs/my_og, with the observation group for OSA. It is now possible to run ibis_science_analysis via the command:

• docker run \
• -e DISPLAY=$DISPLAY \
• -v /tmp/.X11-unix:/tmp/.X11-unix \
• -v $PWD:/home/integral \
• -v $REP_BASE_PROD/scw:/data/scw:ro \
• -v $REP_BASE_PROD/aux:/data/aux:ro \
• -v $CURRENT_IC/ic:/data/ic:ro \
• -v $CURRENT_IC/idx:/data/idx:ro \
• -rm -it -user $(id -u) -entrypoint=''\
• 'bash -c
• export HOME_OVERRRIDE=/home/integral;
• . /init.sh;
• cd \$HOME/obs/my_og;
• ibis_science_analysis'

The graphical interface opens and you can run the ibis_science_analysis as explained in the relative the user manual (in OS-X, remember to issue xhost+$ip in the shell before running the commands and set the DISPLAY variable accordingly). With these commands, we moved into our observation group within the docker container to run ibis_science_analysis. Results will be locally stored in $PWD/obs/my_og.

To reduce data from other instruments, you should change the call to og_create appropriately and then call jemx_science_analysis, spi_science_analysis,or omc_science_analysis.