Installation

pyTDGL requires python 3.8, 3.9, 3.10, or 3.11. We recommend creating a new conda environment for pyTDGL to avoid dependency conflicts with other packages. To create and activate a conda environment called tdgl, run:

conda create --name tdgl python="3.10"
conda activate tdgl

Install via pip

• From PyPI, the Python Package index:

  pip install tdgl
  

• From GitHub:

  pip install git+https://github.com/loganbvh/py-tdgl.git
  

Editable installation

To install an editable version of pyTDGL for development, run:

git clone https://github.com/loganbvh/py-tdgl.git
cd py-tdgl
pip install -e ".[dev,docs]"

See also

Contributing to pyTDGL

Alternative sparse solvers

tdgl supports multiple solvers for sparse systems of linear equations: SuperLU (the default), UMFPACK, and MKL PARDISO.

SuperLU, the default solver, is included in scipy and therefore requires no additional installation.

The other solvers, UMFPACK and PARDISO, may outperform SuperLU on certain problems and certain CPU hardware. In particular, PARDISO is optimized for Intel CPUs and, unlike SuperLU and UMFPACK, PARDISO is multithreaded. This means that PARDISO may perform best when solving models with very large meshes on Intel CPUs.

Your mileage may vary, so we encourage you to try the different solvers if you are looking to optimize the run time of your tdgl simulations. The sparse solver can be specified by setting the sparse_solver attribute of tdgl.SolverOptions to one of {"superlu", "umfpack", "pardiso"}.

Installing UMFPACK

UMFPACK requires the SuiteSparse library, which can be installed using conda.

# After activating your conda environment for tdgl
conda install -c conda-forge suitesparse

pip install swig scikit-umfpack
# or pip install tdgl[umfpack]

Installing PARDISO

Note

The MKL PARDISO solver can only be used with Intel CPUs.

tdgl supports the PyPardiso interface to the PARDISO solver. PyPardiso can be installed using either pip or conda.

# After activating your conda environment for tdgl
pip install pypardiso
# or conda install -c conda-forge pypardiso
# or pip install tdgl[pardiso]

GPU acceleration

For users with an NVIDIA or AMD GPU, tdgl can be accelerated using the CuPy library. First install the appropriate version of cupy for your GPU hardware and driver version (see installation instructions here). Then set the gpu attribute of tdgl.SolverOptions to True. Setting tdgl.SolverOptions.gpu = True means that essentially all portions of the simulation except the sparse linear solve used to compute the scalar electric potential \(\mu(\mathbf{r}, t)\) will be performed on the GPU. The sparse linear solve will be performed on the CPU using the solver specified by tdgl.SolverOptions.sparse_solver (by default, SuperLU). One can also perform the sparse linear solve on the GPU using cupy by setting tdgl.SolverOptions.sparse_solver = "cupy", however emperically it seems that this is slower than performing the sparse linear solve on the CPU.

Important

Using cupy with an NVIDIA GPU requires the NVIDIA CUDA Toolkit. You can check whether the CUDA toolkit is installed and on the system path by running

nvcc --version

from the command line. The version of cupy you install must be compatible with the version of the CUDA Toolkit you have installed.

You can install the CUDA Toolkit either directly from the NVIDIA website or from the NVIDIA conda channel. To install the CUDA Toolkit using conda, activate the conda environment for tdgl and run

conda install cuda -c nvidia

If you have installed the CUDA Toolkit but nvcc --version still fails, you may need to update the PATH and LD_LIBRARY_PATH environment variables to point to your CUDA installation.

# If you installed CUDA Toolkit directly from the NVIDIA website,
# resulting in CUDA being installed in /usr/local/cuda:
export PATH=/usr/local/cuda/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

# If you installed CUDA using conda, activate the appropriate conda environment and run:
export PATH=${CONDA_PREFIX}/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

The exact path to your CUDA installation may vary depending on operating system and configuration. You may want to add the appropriate PATH and LD_LIBRARY_PATH modifications to your ~/.bashrc file.

For more detailed installation instructions, see the NVIDIA documentation.

Due to overheads related to transferring data between the CPU and GPU, it is expected that cupy will provide a significant speedup only for models with relatively large meshes and/or models that include screening. Please open a GitHub issue if you have any problems using tdgl with cupy.

Note

Note that cupy support for AMD GPUs is currently experimental.

Verifying the installation

If you would like to verify your installation by running the tdgl test suite, execute the following command in a terminal:

python -m tdgl.testing

If you prefer, you can instead run the following commands in a Python session:

>>> import tdgl.testing
>>> tdgl.testing.run()