TorchGDM

nano-optics full-field solver, written in PyTorch.

TorchGDM is a PyTorch implementation of the Green's dyadic method (GDM), a electro-dynamics full-field volume integral technique. It's main features are multi-scale simulations combining volume discretized and effective e/m polarizability models, as well as the general support of torch's automatic differentiation.

TorchGDM is available on the gitlab repository and via PyPi and pip. Please visit also the TorchGDM documentation website.

TorchGDM is originally based on various theoretical works by Christian Girard at CEMES (see e.g. Ch. Girard 2005 Rep. Prog. Phys. 68 1883), with contributions from G. Colas des Francs, A. Arbouet, R. Marty, C. Majorel, A. Patoux, Y. Brûlé, S. Ponomareva, A. Azéma and P. R. Wiecha.

If you use TorchGDM for your projects, please cite the accompanying paper (arxiv:2505.09545).

Getting started

Simulate and plot the scattering cross section spectrum between 550nm and 950nm of a GaN nano-cube (240nm side length), placed in vacuum, illuminated by an x-polarized plane wave:

import torch
import matplotlib.pyplot as plt
import torchgdm as tg

# --- simulation setup
# - vacuum environment
mat_env = tg.materials.MatConstant(eps=1.0)
env = tg.env.EnvHomogeneous3D(env_material=mat_env)

# - illumination field(s) and wavelength
wavelengths = torch.linspace(550.0, 950.0, 25)
plane_wave = tg.env.freespace_3d.PlaneWave(e0p=1.0, e0s=0.0)

# - discretized structure
structure = tg.struct3d.StructDiscretizedCubic3D(
    discretization_config=tg.struct3d.cube(l=8),
    step=30.0,    # in nm
    materials=tg.materials.MatDatabase("GaN"),
)

# - define and run simulation.
sim = tg.Simulation(
    structures=[structure],
    illumination_fields=[plane_wave],
    environment=env,
    wavelengths=wavelengths,
)
sim.plot_structure()  # visualize structure
sim.run()             # run the main simulation

# - post-processing: cross sections
cs_results = sim.get_spectra_crosssections()

# plot
plt.figure(figsize=(5, 4))
plt.plot(tg.to_np(wavelengths), tg.to_np(cs_results["scs"]))
plt.xlabel("wavelength (nm)")
plt.ylabel("scs (nm^2)")
plt.show()

GPU support

TorchGDM was tested on CUDA GPUs and google TPUs. All you need is a GPU enabled version of pytorch. Running on GPU can be enabled by using:

  import torchgdm as tg
  tg.use_cuda(True)

Alternatively, GPU usage can be controlled by setting the device manually:

  sim = tg.Simulation(...)
  sim.set_device("cuda")

Features

List of features

General:

• pure python
• run on CPU and GPU, parallelized and vectorized
• full support of torch's automatic differentiation

Simulations:

• 2D and 3D discretized nano-structures
• 2D and 3D effective polarizability models (multiple electric and magnetic dipoles)
• mix of discretized / effective model structures
• far-field (plane wave, focused Gaussian beam) and local illumination (point/line emitters)

Post-processing:

• cross sections (extinction, scattering, absorption)
• near-fields and far-fields
• optical chirality
• Poynting vector
• field gradients
• exact multipole decomposition
• Green's tensors in complex environments
• LDOS / decay rate
• efficient rasterscan simulations
• extract ED/MD dipole pair effective polarizability models
• plotting tools for convenient 2D / 3D visualizations
• ...

Extensible:

• Object-oriented extensibility
• materials
• structures
• illuminations
• environments (via Green's tensors)

Installing / Requirements

TorchGDM is pure python. Installation via pip is possible on all major operating systems:

pip install -U torchgdm

TorchGDM was tested under linux and windows with python versions 3.9 to 3.12. It requires following python packages

• pytorch (v2.6+)
• numpy

Following not strictly required packages will be automatically installed:

• scipy (for several tools)
• tqdm (progress bars)
• pyyaml (support for refractiveindex.info permittivity data)
• matplotlib (2d plotting)
• alphashape (2d contour plotting)
• psutil (for automatic memory purge)

Further optional dependencies

• treams (for T-matrix and Mie theory tools)
• pyvista (3d visualizations)
• ipywidgets, jupyterlab and trame (for jupyter inline 3D visualizations)
• scikit-learn (automatic GPM extraction)
• pymiecs (for some Mie theory unit tests)

(install all optional dependencies via pip: pip install -U torchgdm[all])

Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.

Links

• torchgdm documentation: https://homepages.laas.fr/pwiecha/torchgdm_doc/
• link to PyPi: https://pypi.org/project/torchgdm/
• gitlab repository: https://gitlab.com/wiechapeter/torchgdm
• issue tracker: https://gitlab.com/wiechapeter/torchgdm/-/issues
  • in case of sensitive bugs you can also contact me directly at pwiecha|AT|laas|DOT|fr.
• related projects:
  • pyGDM2: https://homepages.laas.fr/pwiecha/pygdm_doc/

Licensing

The code in this project is licensed under the GNU GPLv3.