Setting up a virtual environment

This chapter walks you through creating an isolated Python environment and installing PyTorch and SVETlANNa into it, on Windows, macOS and Linux.

What is a virtual environment, and why bother?

A virtual environment is a self-contained folder holding its own copy of the Python interpreter and its own site-packages directory. Anything you install while the environment is active goes into that folder and nowhere else.

Without one, every pip install writes into a single system-wide location, which causes three recurring problems:

With a virtual environment each project gets its own dependency set, you never need administrator rights, and deleting the project means deleting one folder.

Requirements

• Python 3.11 or newer — SVETlANNa declares requires-python >= 3.11.
• Roughly 3 GB of free disk space (PyTorch wheels are large).
• An NVIDIA GPU is optional; everything below also works on the CPU.

Check the version you have:

py --version

python3 --version

python3 --version

sudo apt install python3.12 python3.12-venv

Step by step

mkdir my-optics-project
cd my-optics-project

py -3.12 -m venv .venv

python3 -m venv .venv

python3 -m venv .venv

.venv\Scripts\Activate.ps1

.venv\Scripts\activate.bat

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

source .venv/bin/activate

source .venv/bin/activate

python -c "import sys; print(sys.executable)"

python -m pip install --upgrade pip

pip install torch

pip install torch --index-url https://download.pytorch.org/whl/cu128

pip install torch

pip install torch

pip install torch --index-url https://download.pytorch.org/whl/cpu

pip install torch --index-url https://download.pytorch.org/whl/cu128

pip install svetlanna

pip install "svetlanna[pandas]"

git clone https://github.com/CompPhysLab/SVETlANNa.git
cd SVETlANNa
pip install -e .

python -c "import torch, svetlanna; print(torch.__version__); print('svetlanna ok')"

import torch
from svetlanna import SimulationParameters, Wavefront
from svetlanna.units import ureg
 
print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
print("MPS available:", torch.backends.mps.is_available())   # Apple Silicon
 
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("Field shape:", wf.shape)

PyTorch: 2.14.0
CUDA available: False
MPS available: True
Field shape: torch.Size([128, 128])

pip freeze > requirements.txt

python -m venv .venv
source .venv/bin/activate        # .venv\Scripts\Activate.ps1 on Windows
pip install -r requirements.txt

Everyday use

cd my-optics-project
source .venv/bin/activate        # .venv\Scripts\Activate.ps1 on Windows
# ... work ...
deactivate                       # leave the environment

To delete an environment, just remove the folder — nothing is registered anywhere else:

rm -rf .venv                     # rmdir /s .venv on Windows

Jupyter

To use the environment as a Jupyter kernel:

pip install jupyterlab ipykernel
python -m ipykernel install --user --name my-optics-project
jupyter lab

Then pick my-optics-project from the kernel list. If import svetlanna fails inside a notebook, you are almost certainly running a different kernel — check with:

import sys; print(sys.executable)

Alternative tools

venv requires nothing beyond Python itself, which is why it is used above. Two popular alternatives do the same job:

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install torch svetlanna

conda create -n optics python=3.12
conda activate optics
pip install torch svetlanna

Troubleshooting

What next?

• Installation — GPU notes and dependency details
• Quickstart — a complete optical system in five minutes