Installation

New to Python packaging? Start with Setting up a virtual environment — it covers the whole setup for Windows, macOS and Linux step by step.

Requirements

Python 3.11+
PyTorch 2.0+ — installed separately, see below
CUDA (optional, for GPU acceleration)

Installing

SVETlANNa does not declare torch as a dependency, so that you can choose the CPU or CUDA build yourself. Install PyTorch before SVETlANNa.

pip


pip install torch
pip install svetlanna

Verifying the installation

Import the library


import svetlanna
import torch
print(f"PyTorch: {torch.__version__}")

Check the GPU


import torch
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU: {torch.cuda.get_device_name(0)}")

Run a test


from svetlanna import SimulationParameters, Wavefront
from svetlanna.units import ureg
 
params = SimulationParameters.from_ranges(
    x_range=(-1*ureg.mm, 1*ureg.mm), x_points=128,
    y_range=(-1*ureg.mm, 1*ureg.mm), y_points=128,
    wavelength=632.8*ureg.nm
)
 
wf = Wavefront.plane_wave(params)
print(f"Test passed. Shape: {wf.shape}")

GPU support

SVETlANNa uses CUDA automatically when PyTorch is installed with GPU support.

To move a simulation onto the GPU:


from svetlanna import SimulationParameters, Wavefront
from svetlanna.units import ureg
 
params = SimulationParameters.from_ranges(
    x_range=(-1*ureg.mm, 1*ureg.mm), x_points=512,
    y_range=(-1*ureg.mm, 1*ureg.mm), y_points=512,
    wavelength=632.8*ureg.nm
)
 
# move to the GPU (in-place)
params.to("cuda")
 
# every object created from these parameters now lives on the GPU
wf = Wavefront.gaussian_beam(params, waist_radius=0.3*ureg.mm)
print(f"Device: {wf.device}")  # cuda:0

Dependencies

Package	Purpose
`torch`	Tensor maths, autograd, CUDA — install it yourself
`numpy`	Helper operations
`matplotlib`	Visualisation
`jinja2`	Templates for the HTML widgets
`anywidget`	Jupyter widgets
`pandas`	Optional extra: `pip install "svetlanna[pandas]"`

Common problems

CUDA out of memory: with large grids (> 1024×1024) make sure you have enough GPU memory. Call torch.cuda.empty_cache() to release cached blocks.

ModuleNotFoundError: No module named 'torch': PyTorch is not part of the SVETlANNa dependency set. Run pip install torch.

Import error: if import svetlanna fails, check your Python version (python --version, 3.11+ required) and that the right virtual environment is active.