Installation

From Sources

The sources for ism3d can be downloaded from the Github repo.

You can either clone the public repository and install the copy of source with:

$ git clone git://github.com/r-xue/ism3d
$ pip install --user .

To do this in one step, you can also run this command in your terminal:

$ pip install --user --upgrade git+https://github.com/r-xue/ism3d.git

Dependencies

While most dependecies will be automatically checked and installed from the standard PyPI installation (specified in setup.cfg), we note that some might require manual installations on certain platforms (most likley on macOS):

• required, for Measurement Sets I/O

  • FINUFFT

  • casa6

• required, for galactic dynamics modeling from mass potentials

  • galpy

• optional, for moderate performance improvement

  • mkl_fft/mkl_random (improve FFT speed)

• test-only, for running certain benchmarking tests and tutorials

  • galario

  • python-casacore & casacore

For development, one can manually install most dependencies with:

$ pip install --user -r ./requirements_dev.txt

From Docker Hub

The ism3d repository contains a Dockerfile, that automatically builds the rxastro/ism3d:dev images hosted at the Docker Hub. The image contains a base Linux environment (based on Ubuntu 20.04) with the ism3d prototype, casa6, and other Python packages (astropy, Jupyter, etc.) already installed.

https://registry.hub.docker.com/r/rxastro/ism3d

Note

The Docker image rxastro/ism3d:dev is built upon the base image offered by the casa6-docker project:

https://registry.hub.docker.com/r/rxastro/casa6

The container launch instruction is the similar with that of rxastro/casa6:latest.

Launch with an interactive shell

To launch the container with an interactive shell on a host with Docker Desktop running, just type:

$ docker run -it -v ~/Workspace:/root/WorkDir rxastro/ism3d:dev bash

This will download the image rxastro/ism3d:dev, start a container instance, and login as root (bravely…). It will also try to mount the host directory ~/Workspace (assuming it exists) to /root/WorkDir of your container. After this, you can perform code development and data analysis in /root/WorkDir of your container (now pointing to ~/Workspace on the host), with the access of tools/environment (e.g. casa6, astropy, etc.) residing in the image.

In case you would like to manually update local-cached images for whatever reasons, you probably want to run this before launching the container again:

$ docker pull rxastro/ism3d:dev

Run a Jupyter server

A Jupyter server has been built in the Docker image rxastro/ism3d:dev (see the Dockerfile content for its customization). This creates a useful feature of rx.astro/ism3d:dev: you can connect your host web browser to the Jupyter server running its container instance. This gives you a portable development environment semi-isolated from your host OS that offers all Jupyter-based features (e.g. Widgets) along with many Python packages: casatools, casatasks, astropy, numpy, matplotlib, and more.

To log in a rxastro/ism3d:dev container and start the Jupyter session,

user@host      $ docker run -v ~/Workspace:/root/WorkDir --env PORT=8890 -it -p 8890:8890 rxastro/ism3d:dev bash
root@container $ jupyter-lab # start a Jupyter session

Then you can move back to the host, open a web browser, and connect it to the Jupyter server running on the guest OS:

user@host      $ firefox --new-window ${address:8890-with-token}

Launch with Singularity

Docker images can be imported to Singularity for HPC-based deployment:

$ singularity pull docker://rxastro/ism3d:dev
$ file casa6_latest.sif
$ singularity inspect casa6_latest.sif
$ singularity exec -H $HOME/vh:/Users/Rui casa6_latest.sif /bin/bash

Note

There are significant design differences between Docker and Singularity, and a detailed demonstration is beyond the scope of this documentation.