Python Environment Setup

This guide walks you through the steps needed to set up a DysmalPy-ready python installation with the required dependencies.

If you already have an Anaconda python installation on your computer, we recommend making a new environment (see ‘Creating an Anaconda environment’) for installing the DysmalPy dependencies.

Note

If you install the DysmalPy dependencies in an Anaconda environment, and not the root installation, then you will need to activate this environment before running DysmalPy. (See ‘Activating an Anaconda environment’).

Install Anaconda

Currently, Anaconda has installers available for Windows, MacOS, and Linux, which can be downloaded from their website: Anaconda downloads.

This installer (GUI for Windows and MacOS; shell script for Linux) will guide you through the installation process. However, for further instructions or in case problems arise, we refer you to the Anaconda installation guide.

The full Anaconda installation requires at least 3 GB of disk space initially. (Alternatively, you can install Miniconda, which requires only 400 MB of disk space initially)

Creating an Anaconda environment

Note

If you already had an installation of Anaconda, you should ensure it’s up to date before proceeding by running $ conda update conda

If you already have an Anaconda python installation, we suggest creating a new environment where the DysmalPy dependencies can be installed. This ensures that any package dependency requirements do not conflict with dependencies of any other packages you have installed.

To create a new environment with python installed, from the terminal or an Anaconda Prompt, use the following command:

conda create --name my-env python pip

or, if you want to select a specific version of python, use for example:

conda create --name my-env python=3.10 pip

Warning

DysmalPy requires python version >=3.10.

Then follow the prompts to finish creating the new environment my-env.

(Further information about Anaconda environments can be found here).

Now that you have a dedicated environment for DysmalPy, you will either need to activate the environment before you run DysmalPy, or activate it by default by modifying your shell login script (e.g., your .bashrc, .bash_profile, .profile, .tcshrc, … file).

Note

If you are using Windows, it is adviced to use the Anaconda Powershell Prompt to run the commands below.

Activating an Anaconda environment

If you have installed the DysmalPy dependencies in the non-root Anaconda environment, you activate this environment with the following command:

conda activate my-env

or for MacOS and Linux

source activate my-env

or for Windows:

activate my-env

To deactivate the environment, you can then use the command:

conda deactivate

or for MacOS and Linux

source deactivate

or for Windows:

deactivate

Tip

Check that your environment is activated by running

which python

This should return a path ending with envs/my-env/bin/python.

If this is not the version of python returned, you may have to run $ conda deactivate twice (first to deactivate my-env, then to deactivate base). Then reactivate my-env by running $ conda activate my-env.

Adding channels to conda

A number of the DysmalPy dependencies are not available in the default Anaconda channels, but are instead available in the astroconda channel. To ensure this channel is installed, from the terminal or the Anaconda Prompt, run:

conda config --add channels http://ssb.stsci.edu/astroconda

To verify the channel has been added, check that the astroconda url shows up in the list of channels returned by the following command:

conda config --show channels

Installing DysmalPy libraries and dependencies with conda

*REQUIRED*: You need a working C compiler as well as gsl and cython, you can install them with conda:

conda install -c conda-forge c-compiler ;
conda install cython gsl

On linux: you might want to install build-essential instead of c-compiler with sudo apt install build-essential which contains essential build tools.

Attention

Windows users: you NEED to download the visual studio build tools from windows build tools and from there you need to get the default installation of the C++ build tools (Desktop developement with C++).

*ADVANCED*: A set of specific libraries for C++ extensions

To compile the Dysmalpy C++ Gaussian least-squares fitter and the lensing modules, you need a C++ compiler and a set of libraries. The libraries are cfitsio, libcblas. The installation of these libraries is recommended, but not required.

The libraries can be installed using your normal means, or with conda as follows:

conda install -c conda-forge cxx-compiler ;
conda install cfitsio ;
conda install -c conda-forge libcblas

Note

If you are installing dysmalpy on Windows, you will also need to install pthreads with:

conda install -c conda-forge pthreads-win32

Note that the installation directory will be needed later when compiling the extensions. This is either /PATH/TO/ANACONDA if using anaconda as above (where the base /PATH/TO/ANACONDA should be listed under the “active env location” from the output of $ conda info), or whatever directory was specified for the separate install.

Before proceeding, please check if the C++ extesions can be compiled using the libraries that you have installed. Please run the following command (inside the dysmalpy directory where the file setup.py is located):

python setup.py check_build

This should return a message with the information about the extensions that can be compiled and those that cannot.

Note

From the output of the command above, please note that The C++ extension dysmalpy.models.cutils is mandatory, so make sure the compilation was succesful. The dysmalpy.lensingTransformer and dysmalpy.leastChiSquares1D extensions are optional, but recommended if you want to use the lensing or the least-squares fitter modules.

Install python dependencies

Attention

If you want to install the python dependencies with pip, you can skip back to the installation instructions. If you prefer using conda to manage them please continue below.

Most of the dependencies of dysmalpy can be installed with conda (make sure your conda environment is activated, see Activating an Anaconda environment). Three of them will need to be installed using pip at the end.

We will use conda to install AstroPy, emcee, corner, and shapely. We will also ensure that ipython, NumPy, SciPy, matplotlib, dill and pytest are installed, as well as a number of other AstroPy dependencies.

From the terminal or an Anaconda prompt, run the following:

conda install "astropy<6.0.0" "ipython" "numpy<2.0.0" "scipy" "matplotlib" "dill" "pytest" ;
conda install -c astropy -c defaults h5py pandas ;
conda install -c conda-forge -c astropy emcee shapely corner

Finally, install remaining dependencies (spectral-cube, radio-beam, photutils, and dynesty) with pip by running:

pip install spectral-cube radio-beam photutils "dynesty>=2.1.3"

Note

If AstroPy is already installed, it can be updated to the most recent version by running $ conda update astropy. (See also the AstroPy installation documentation.)

Tip

If for some reason the package can’t be found, try running the installation by specifying the astropy or conda-forge channels: $ conda install -c astropy PACKAGE or $ conda install -c conda-forge PACKAGE

If this still fails, as a last resort try to use pip to install the package by running: $ pip install PACKAGE

Once all the dependencies are installed in your conda envinroment, you can go back to the installation instructions to finalize the installation of dysmalpy.