Skip to content

Setup

This page takes you from a clean machine to a working DeepLens environment and your first successful lens simulation. The recommended way to work with DeepLens is to clone the repository and develop inside it — see Installation for the full set of options.

Prerequisites

  • Python 3.12
  • Conda (Miniconda or Anaconda) for environment management
  • NVIDIA GPU with CUDA — recommended. DeepLens also runs on CPU, but ray tracing and wave propagation are much faster on a GPU.

On Apple Silicon, init_device() deliberately falls back to CPU because MPS does not support the float64 paths used by coherent and wave-optics workflows. Pass device="mps" explicitly only for a float32 geometric workflow.

1. Clone the repository

git clone https://github.com/vccimaging/DeepLens.git
cd DeepLens

2. Create the conda environment

conda create -n deeplens python=3.12
conda activate deeplens

3. Install the dependencies

python -m pip install -r requirements.txt

This installs PyTorch 2.10.0 and torchvision 0.25.0. The requirements select CUDA 12.8 wheels on Linux and Windows and native wheels on macOS.

4. Verify the install

Running from the repository root, the local deeplens/ package is importable directly — no pip install step is required for the clone-and-develop workflow.

import torch
from deeplens import GeoLens

print(torch.cuda.is_available())  # True if a CUDA GPU is available

5. Run your first demo

0_hello_geolens.py loads a cellphone lens, runs the classical optical analyses (layout, spot, MTF, distortion, vignetting), and renders an image with both ray tracing and PSF-map simulation:

python 0_hello_geolens.py

On success, these files are written to the repository root:

File Description
lens.png Lens cross-section layout
lens_spot.png Spot diagram
lens_mtf.png MTF curves
lens_distortion.png Distortion plot
lens_vignetting.png Relative illumination (vignetting)
render_ray_tracing.png Image rendered by ray tracing
render_psf_map.png Image rendered by PSF-map convolution

See Hello GeoLens for a line-by-line walkthrough of this script.

Troubleshooting

torch.cuda.is_available() returns False: Install a CUDA-enabled PyTorch build for your platform from pytorch.org. DeepLens still runs on CPU, just slower.

FileNotFoundError for a dataset file: Run the script from the repository root so relative paths such as ./datasets/lenses/cellphone/cellphone80deg.json resolve correctly.

ModuleNotFoundError: No module named 'deeplens': Make sure the deeplens environment is active and that you are running from the repository root (or that you installed the package with pip install -e .).

Next steps