Installation

Follow these instructions to install DESC and its dependencies. Note that most of the installation options here do not install JAX with GPU support. We do include installation instructions to install JAX with GPU support on some computing clusters that we have tested. In general, to install JAX with GPU support, please refer to the JAX installation docs.

For information on using conda, see here. Other package managers like venv could be used instead of conda, we have just chosen conda as our package manager of choice, and only test with conda environments, so your mileage may vary with other managers.

Attention

DESC requires python>=3.10. If you have python2 also locally installed, replace all pip commands with pip3 and all python commands with python3 to ensure the correct python version is used.

Attention

If you are on Windows, consider using the Windows Subsystem for Linux (WSL) to install DESC.

We don’t test or support DESC on Windows OS, and there have been some instances that numerical discrepancies on Windows can cause failures or wrong results. For these reasons, we recommend using WSL if you have a Windows machine. For instructions on how to install WSL see here. For using WSL in VS Code see here.

On Your Local Machine

Install from PyPI

pip install desc-opt

Or from GitHub (for development builds)

First download the repository from GitHub.

git clone https://github.com/PlasmaControl/DESC.git
cd DESC

Now use pip to install packages (this will only install DESC + JAX with CPU capabilities, NOT GPU)

tested to work on M1 Macbook on May 3, 2023

conda create --name desc-env 'python>=3.10, <=3.13'
conda activate desc-env
pip install --editable .
# optionally install developer requirements (if you want to run tests)
pip install -r devtools/dev-requirements.txt

On Most Linux Computing Clusters

These examples use conda environments. On computing clusters you must ensure to module load anaconda in order to use conda (or in some clusters, you must specify the version of anaconda module you want).

CPU

Install from PyPI

pip install desc-opt

Or from GitHub (for development builds)

First download the repository from GitHub.

git clone https://github.com/PlasmaControl/DESC.git
cd DESC
# load your python module
module load anaconda  # this command may vary depending on cluster

Now use pip to install packages (this will only install DESC + JAX with CPU capabilities, NOT GPU)

conda create --name desc-env 'python>=3.10, <=3.13'
conda activate desc-env
pip install --editable .
# optionally install developer requirements (if you want to run tests)
pip install -r devtools/dev-requirements.txt

CPU+GPU

We will show the installation instructions that work for the clusters we’ve tested. If your cluster is not shown, try the installation for the cluster most resembling your own, or see if your cluster has specific JAX GPU installation instructions, as that is the main installation difference between clusters. (note, most of these clusters below are x86_64 architectures, see the JAX installation docs for more info if you have a different architecture ).

Attention

Note that DESC does not always test on or guarantee support of the latest version of JAX (which does not have a stable 1.0 release yet), and thus older versions of GPU-accelerated versions of JAX may need to be installed, which may in turn require lower versions of JaxLib, as well as CUDA and CuDNN.

Checking your Installation

To check that you have properly installed DESC and its dependencies, try the following:

python
>>> from desc import set_device  # only needed if running on a GPU
>>> set_device('gpu')  # only needed if running on a GPU
>>> from desc.backend import print_backend_info
>>> print_backend_info()

You should see an output stating the DESC version, the JAX version, and your device (CPU or GPU).

You can also try running an example input file (filepath shown here is from the DESC folder, if you have cloned the git repo, otherwise the file can be found and downloaded here):

python -m desc -vv desc/examples/SOLOVEV

Troubleshooting

We list here some common problems encountered during installation and their possible solutions. If you encounter issues during installation, please leave us an issue on Github and we will try our best to help!

Tip

Problem: I’ve installed DESC, but when I check my installation I get an error ModuleNotFoundError: No module named 'desc'.

Solution:

This may be caused by DESC not being on your PYTHONPATH, or your environment containing DESC not being activated.

Try adding the DESC directory to your PYTHONPATH manually by adding the line export PYTHONPATH="$PYTHONPATH:path/to/DESC" (where /path/to/DESC is the path to the DESC folder on your machine) to the end of your ~/.bashrc (or other shell configuration) file. You will also need to run source ~/.bashrc after making the change to ensure that your path updates properly for your current terminal session.

Try ensuring you’ve activated the conda environment that DESC is in ( conda activate desc-env ), then retry using DESC.

Tip

Problem: I’ve installed DESC, but when I check my installation I get an error ModuleNotFoundError: No module named 'termcolor' (or another module which is not desc).

Solution:

You likely are not running python from the environment in which you’ve installed DESC. Try ensuring you’ve activated the conda environment that DESC is in( conda activate desc-env ), then retry using DESC.

Tip

Problem: I’m attempting to install jax with pip on a cluster, I get an error ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. desc-opt 0.9.2+587.gc0b44414.dirty... with a list of incompatiblities.

Solution:

This may be caused by a version of DESC already having been installed in your base conda environment.

Try removing the DESC folder completely, ensuring that pip list in your base conda environment no longer lists desc-opt as a package, then redo the installation instructions.