02 - Installation and environment configuration¶

The current release candidate is LESS 3.0.0rc1. For the version suffix and product naming, see Model Introduction ; for scene reuse methods, see Core Concept ], for method signatures see API Reference .

Hardware requirements¶

LESS provides three backends: Embree CPU, Vulkan Ray Query GPU and NVIDIA OptiX. After installation, it automatically detects the paths available on the current machine.

Requirements	Embree CPU	Vulkan GPU	OptiX GPU
Hardware	Modern x86_64 CPU	NVIDIA, AMD or Intel GPU with Vulkan Ray Query	NVIDIA GPU with OptiX compatibility
Memory	System Memory	4 GB+ Video Memory (8 GB+ recommended)	4 GB+ Video Memory (8 GB+ recommended)
Driver	No GPU driver requirement	Newer graphics card driver from corresponding manufacturer	Newer NVIDIA driver
Operating system	Windows 10/11, Linux	Windows 10/11, Linux	Windows 10/11, Linux
Python	3.10–3.13	3.10–3.13	3.10–3.13

Not compatible with GPU: Automatically use Embree to run all public simulation workflows
With AMD/Intel GPU: The Vulkan backend can be used when the driver supports Ray Query
With NVIDIA GPU: Choose OptiX or Vulkan based on features and performance; production computing usually takes precedence over OptiX
Functionally consistent: Published energy balance, 3D physiological coupling, SIF and LiDAR workflows also run on the Embree CPU

Install¶

Install directly using pip:

pip install less3d

The precompiled wheel already contains three back-end program modules, OptiX PTX, Vulkan SPIR-V and Embree runtime libraries. Ordinary users do not need to install CUDA Toolkit, OptiX SDK or Vulkan SDK; when using GPU, they still need to install the graphics card driver of the corresponding manufacturer.

Optional extensions (extras)¶

Some submodules have additional dependencies on external libraries and are not installed by default with less3d. Add [...] as needed:

Extra	When needed	What to pack
`lidar`	Reconstructing a 3D scene from the `.las/.laz` point cloud (see Chapter 17 ])	`laspy`, `cloth-simulation-filter` (SciPy and trimesh are installed with the main package)
`atmosphere`	Use `less.SixSAtmosphere`; native `less.Atmosphere` does not require this extension (see Atmosphere Model ]	`Py6S`
`dev`	Run `tests/run_all_tests.py` for regression testing (not available to ordinary users)	`pytest`

pip install less3d[lidar]          # Install lidar dependencies
pip install less3d[lidar] -U       # Already installed, updated to the latest

Verify installation¶

import less

# Print version number
print(f"LESS version: {less.__version__}")

# Check whether the three backends are available on this machine
for backend in less.list_backends(probe=True):
    print(backend.name, backend.available,
          backend.unavailable_reason or "")

If everything is OK, you will see output similar to:

LESS version: 3.0.0rc1
optix True
embree True
vulkan True

Backend and device selection¶

LESS provides three backends: NVIDIA OptiX, cross-vendor Vulkan Ray Query and CPU Embree. The default Scene() is automatically selected based on the current environment and required functions:

scene = less.Scene()                          # Default 'auto': automatically selected by function and native environment
scene = less.Scene(backend='optix')           # Mandatory NVIDIA OptiX; if unavailable, an error will be reported directly
scene = less.Scene(backend='vulkan')          # Mandatory Vulkan; supports NVIDIA / AMD / Intel GPU
scene = less.Scene(backend='embree')          # Force CPU (multi-threaded Embree)
scene = less.Scene(backend='vulkan', device=1) # Select a second compatible Vulkan device

Parameters	Default	Meaning
`backend`	`'auto'`	`'auto'` / `'optix'` / `'vulkan'` / `'embree'`. Historical aliases `gpu`/`cuda` refer specifically to OptiX and do not represent all GPU; `vk` → Vulkan, `cpu` → Embree
`device`	`0`	The serial number of the compatible device inside the selected GPU backend; the numbers of OptiX and Vulkan are not guaranteed to be the same

Trade-offs among three backends:

OptiX: Production first choice on NVIDIA GPU, generally the best performance
Vulkan: Across NVIDIA, AMD, Intel GPU, currently still marked as Experimental; the main workflow has returned across backends
Embree: Does not require the CPU path of GPU, also suitable as a numerical reference
Physical Consistency: Common workflows are verified against parsing tolerances or Monte Carlo noise; different backends are not guaranteed to be bit-by-bit identical
Feature check: Use less.can_use("feature_name") to determine whether the current installation can execute a feature; use less.available_features() to list available features.

Users usually only need to know "whether it can currently run". You can view it directly:

print(less.list_backends(probe=True))
print(less.can_use("lidar_waveform", backend="vulkan"))

scene = less.Scene(backend="vulkan")
print(scene.can_use("energy_balance"))

can_use() will consider the code implementation, installation package compilation content and local driver at the same time; users do not need to judge the reasons separately.

Example: Compare the time consumption of three backends on your machine¶

import time
import less

def run(backend):
    scene = less.Scene(backend=backend)
    scene.size = 10.0
    scene.terrain = less.Terrain(property=less.Lambertian(reflectance=0.3))
    scene.illumination = less.Illumination(source=less.Sun(zenith=30, azimuth=150), atmosphere=less.SimpleSpectralAtmosphere(turbidity=2.0))
    sensor = less.OpticalImager(
        less.Orthographic(image_size=256),
        bands=[650, 550, 450], quality=64)
    scene.simulate(sensor)                        # First call to automatically build and warm up
    t0 = time.perf_counter()
    scene.simulate(sensor)
    return time.perf_counter() - t0

for b in ['optix', 'vulkan', 'embree']:
    try:
        print(f"  {b}: {run(b)*1000:.1f} ms")
    except Exception as e:
print(f" {b}: Not available ({type(e).__name__})")

When the GPU backend is available, the first time scene.simulate() automatically builds the scene and prints the actual device name. For example, NVIDIA, AMD, or Intel devices might appear as:

GPU: NVIDIA GeForce RTX 4080 (... MB free)
GPU: AMD Radeon ... (... MB device-local)
GPU: Intel Arc ... (... MB device-local)

This only means that the device has been detected. Whether a certain function can finally be run depends on the return value of scene.can_use(...).

Automatic selection will first try available backends that fit the current workflow. If you need repeatable performance testing or explicitly specify hardware, set backend explicitly and do not rely on auto.

When an explicitly selected backend is unavailable, the reason is given directly, such as lack of compilation support, driver incompatibility, or the device does not support Ray Query, rather than silently switching to another backend.

View built-in examples¶

LESS comes with several demo scenarios that can quickly verify whether the installation is normal:

import less

# List all built-in examples
less.examples.list()

# Run the Autumn Forest example (open the interactive viewer)
less.examples.run("autumn_forest")

# Running the cornfield example
less.examples.run("maize_field")

If the interactive viewer opens normally and displays the 3D scene, the installation is successful.

FAQ¶

Can it be used without GPU?¶

Can. LESS will automatically use the Embree CPU backend on machines that are not compatible with GPU and can run Same public workflow as GPU backend. Large Monte Carlo tasks are generally slower on CPU, but not silent Omit physical processes or return incomplete products.

GPU acceleration does not take effect¶

Run less.list_backends(probe=True) first to view the actual available status of OptiX, Vulkan and Embree. NVIDIA GPU can use OptiX or Vulkan; AMD and Intel GPU can use Vulkan. If the target GPU backend is not available, please update the corresponding manufacturer's graphics card driver and confirm that the device supports Vulkan Ray Query. NVIDIA users can also use nvidia-smi to check driver and device status.

Insufficient video memory¶

RuntimeError: Out of GPU memory

Cause: The scene is too large (too many triangles) or the video memory is occupied by other programs. Solution: Reduce the scene size, close other programs that occupy video memory, or switch to CPU mode.

`image.show()` / `result.show()` No picture¶

Symptoms: In PyCharm (especially older versions) or some Linux desktop environments, after image.show() is called, the window does not pop up and the IDE does not display, but the program continues without an error.

Cause: matplotlib selected a non-interactive backend (such as Agg, module://backend_interagg). LESS leaves visualization to matplotlib and does not choose the backend itself.

Solution: Explicitly select an interactive backend at the top of the script, before import matplotlib:

import matplotlib
matplotlib.use('TkAgg')      # Universal first choice; conda environment comes with Tk
# Or: matplotlib.use('Qt5Agg') # PyQt5 / PySide2 installed
import matplotlib.pyplot as plt

import less                   # After that, the plt call inside less will use TkAgg

Do not hard-write matplotlib.use(...) in the less library - that will destroy the headless server environment (CI / remote batch running). The choice of backend is the responsibility of the user script.

If you just want to save the figure without pop-up windows, just image.save("out.png") / result.save("out.csv"), without relying on the matplotlib backend.

Next step¶

03 - Coordinate system and scene geometry

less.__version__、less.list_backends()
less.available_features()、less.can_use()
less.Scene、less.examples