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
From PyPI, the Python Package index:
pip install tdgl
From GitHub:
pip install git+https://github.com/loganbvh/py-tdgl.git
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]"
Contributing to pyTDGL <about/contributing:Contributing>
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"}
.
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]
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]
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 μ(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.
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.
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()