Installation¶
SuperScreen
requires Python >=3.7, <3.10
and can be installed either from
PyPI, the Python Package index,
or from the SuperScreen
GitHub repository.
We recommend creating a new
conda environment
for SuperScreen
to avoid dependency conflicts with other packages. To create a new conda environment called
superscreen
, run conda create --name superscreen python=3.x
, where x
is one of {7, 8, 9}
.
After the environment has been created, run conda activate superscreen
to activate it.
Important
On Windows, ensure that the latest Microsoft Visual C++ runtime is installed before installing
superscreen
.On MacOS, ensure that Xcode command line tools are installed before installing
superscreen
.
Install via pip
¶
From PyPI, the Python Package Index:
pip install superscreen
From the SuperScreen GitHub repository:
pip install git+https://github.com/loganbvh/superscreen.git
Developer Installation¶
To install an editable version of SuperScreen
, run:
git clone https://github.com/loganbvh/superscreen.git
cd superscreen
pip install -e .
Verify the installation¶
To verify your installation by running the superscreen
test suite,
execute the following commands in a Python session:
>>> import superscreen.testing as st
>>> st.run()
If you prefer, you can also run the superscreen
tests in a single line:
python -m superscreen.testing
GPU acceleration¶
SuperScreen
can use a graphics processing unit (GPU) as a hardware accelerator to speed up computations.
GPU acceleration relies on the JAX library from Google and requires
a machine running Linux (or Windows Subsystem Linux, WSL)
with an Nvidia GPU.
Note
These installation instructions require that you have installed superscreen
in a conda environment
as described above. Below we assume that this conda environment is called superscreen
.
CUDA and JAX can be installed as follows:
# Activate superscreen conda environment
conda activate superscreen
# Install CUDA from the Nvidia conda channel:
# https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#conda-installation
conda install cuda -c nvidia
# Install JAX based on instructions provided by Google:
# https://github.com/google/jax#installation
pip install --upgrade pip
pip install --upgrade "jax[cuda]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
Once installed, running SuperScreen
on a GPU is as simple as passing the keyword argument gpu=True
to
superscreen.solve()
. See GPU acceleration for an demonstration of
GPU-accelerated SuperScreen
simulations.
Note
To ensure that JAX can find the appropriate GPU libraries, you may need to update the environment variable
export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib:${LD_LIBRARY_PATH}
after activating your
conda environment and before starting Python. Alternatively, in your Python session you can run:
>>> import os
>>> os.environ["LD_LIBRARY_PATH"] = f"$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
If you don’t set this environment variable, you may see a CUDA-related error such as cuSolver internal error
when you try to run superscreen.solve(..., gpu=True)
. $CONDA_PREFIX
is an environment variable
set automatically by conda that points to the directory of the active conda environment.
For example, it might be $HOME/opt/anaconda3/envs/superscreen
.