Pipeline with Monolithic CASA¶

Prerequisites¶

It is recommended to put the CASA bin directory first on your path for the duration of the installation procedure.

Downloading and Installing CASA¶

If you don’t already have CASA installed, you can find recent builds at CASA pre-releases. Sort by “Last Modified” to find the most recent version.

After downloading a CASA build, follow the instructions on the CASA Installation Guide to install CASA.

Dependency Requirements¶

Following the change from PIPE-1699, Pipeline now specifies the required standard Python dependencies in a requirements.txt file, and recommends using pip to install them directly from the Python Package Index (PyPI). The pipeline/extern directory now only contains the non-standard Python packages/modules contributed by the developers and heuristics development team.

Note that this file is currently not used by setup.py to auto-install dependencies, and only serves as a reference for development and packaging purposes. In addition, the list only includes dependencies that are not bundled in the monolith CASA release designated for the next Pipeline release, and their version specifications are continuously examined against potential compatibility issues with other Python packages already shipped in CASA. The developer team will maintain the file to reflect the current state of the dependency requirements across the development cycle.

To use this file manually, you can type the following command:

PYTHONNOUSERSITE=1 ${casa_bin}/pip3 install --disable-pip-version-check \
    --upgrade-strategy=only-if-needed -r requirements.txt

Note that here casa_bin is the path to the CASA bin directory. On macOS, this is typically /Applications/CASA.app/Contents/MacOS; on Linux, it is the bin/ directory inside the unpacked CASA tarball, e.g. casa-6.5.3-28-py3.8/bin. PYTHONNOUSERSITE=1 is used to prevent the pip command from checking dependencies from the user’s site-packages directory. This is necessary to isolate the user’s site-packages directory from your CASA development environment, which is generally confined to the unpacked CASA tarball directory. You may create a series of alias shortcuts to avoid accidentally using the wrong Python environment and tools:

alias casa_pip='PYTHONNOUSERSITE=1 ${casa_bin}/pip3 --disable-pip-version-check'
alias casa_python='PYTHONNOUSERSITE=1 ${casa_bin}/python3'

The pip command above should install the dependencies in the CASA site-packages directory, which can be verified with this:

CASA <1>: import astropy
CASA <2>: astropy.__version__
Out[2]: '5.2.1'
CASA <3>: astropy.__path__
Out[3]: ['/opt/casa_dist/casa-6.5.3-28-py3.8/lib/py/lib/python3.8/site-packages/astropy']

Standard install¶

The Pipeline can be built and installed like any standard Python packages, with

casa_pip install .

If Pipeline is already installed, this command will upgrade the package with the new installation.

You can also build a local wheel for easy distribution: casa_pip wheel --no-deps . For a custom installation with optional dependencies (e.g. building docs, running pytest plugins, or performance profiling), one can also try

casa_pip install .[dev]

casa_pip install .[docs]

Developer install¶

As a developer, you will quickly grow weary of creating an egg every time you wish to exercise new code. The pipeline supports developer installations. In this mode, a pseudo installation is made which adds your source directory to the CASA site-packages. Hence the working version you are editing will become the pipeline version available to CASA.

casa_pip install --editable .

To uninstall the developer installation, execute

casa_pip uninstall pipeline

Pairing CASA and Pipeline at runtime¶

To pair and use a working copy of Pipeline with the local CASA installation temporarily without touching your CASA copy, you can add the Pipeline source code path to the CASA/Python sys.path at runtime. This can be conveniently achieved by adding the example code block below to your CASA rcdir (default to ~/.casa) startup.py:

import sys, os
pipe_path=os.environ.get('PIPE_PATH', None)
if isinstance(pipe_path,str):
    pipe_abspath=os.path.abspath(os.path.expanduser(pipe_path))
    if os.path.isdir(pipe_abspath) or os.path.islink(pipe_abspath):
        print("\nAdding the Pipeline package from: {} to the Python interpreter sys.path\n".format(pipe_abspath))
        sys.path.insert(0, pipe_abspath)
        import pipeline
        import pipeline.infrastructure.executeppr as eppr  
        pipeline.initcli() 

Here PIPE_PATH is a shell environment variable that points at your Pipeline code path, e.g., export PIPE_PATH=/path/to/workspace/pipeline_branches/main.

Note that this use case will only work if the CASA installation has all dependency libraries required by the Pipeline package. For a pristine “vanilla” CASA build without Pipeline pre-installed, this can be done with:

casa_pip install --upgrade-strategy=only-if-needed -r requirements.txt