torchrtm 1.2.7

Torch-based Vegetation Radiative Transfer Model library (PROSPECT, SAIL, SMAC)

TorchRTM: A PyTorch-based Radiative Transfer Modeling Toolkit

TorchRTM is a GPU-accelerated, modular, and research-ready radiative transfer modeling (RTM) library built on top of PyTorch.

Features

It integrates:

• Leaf RTMs: PROSPECT-5B, PROSPECT-D, PROSPECT-PRO
• Canopy RTMs: 4SAIL, PROSAIL
• Atmospheric Modeling: SMAC (TOC→TOA conversion)
• LUT Tools: Torchlut (LUT generator), Torchlut_pred (GPU KNN retrieval)
• High Performance: Batch computation, CUDA support

TorchRTM is ideal for remote sensing, vegetation trait retrieval, radiative transfer simulation, environmental monitoring, machine learning and RTM-based inversion workflows.

🌟 Key Features

• Full PROSPECT + PROSAIL + SMAC integration
• GPU-accelerated simulations for millions of samples
• High-performance LUT generator (Torchlut)
• Fast KNN-style LUT-based retrieval engine (Torchlut_pred)
• Supports PROSPECT-5B / D / PRO
• Supports TOC and TOA reflectance
• Fully compatible with PyTorch pipelines and deep learning models

📦 Installation

pip install torchrtm

Requirements

• Python ≥ 3.9
• PyTorch ≥ 1.12
  (Install PyTorch based on your hardware: https://pytorch.org/get-started/locally/)

📘 User Guide

This README includes complete usage documentation for:

1. PROSPECT / PROSAIL model
2. SMAC atmospheric correction
3. Torchlut – fast LUT generator
4. Torchlut_pred – GPU KNN retrieval
5. Full inversion pipeline (LUT → retrieval)

---

1. PROSAIL / PROSPECT Model Usage

TorchRTM provides a unified PROSAIL implementation:

from torchrtm.models import prosail

rho, tau = prospectd(traits, N, alpha=alpha, print_both=True) 
# also supports: prospect5b / prospectpro

Parameters

Name	Type	Description
traits	Tensor (batch, n_traits)	Leaf biochemical parameters (Cab, Car, Cbrown, Cw, Cm, etc.)
N	Tensor (batch)	Leaf structure parameter
alpha	Tensor	Leaf transmittance parameter (commonly 40°)
print_both	bool	if print both of rho,tau, if not only output rho

Notes

traits must be provided in a fixed parameter order depending on the PROSPECT model version:

• prospect5b → Cab, Car, Cbrown, Cw, Cm
• prospectd → Cab, Car, Cbrown, Cw, Cm, Canth
• prospectpro → Cab, Car, Cbrown, Cw, Canth, Prot, Cbc

Returns

A tensor of size:

(batch, spectral_length), (batch, spectral_length)

Containing:

Output	Description
rho	Leaf reflectance spectrum computed by the PROSPECT model (leaf-scale bi-directional reflectance).
tau	Leaf transmittance spectrum computed by the PROSPECT model (leaf-scale bi-directional transmittance).

prosail(
    traits, N, LIDFa, LIDFb, lai, q,
    tts, tto, psi, tran_alpha, psoil,
    batch_size=0, prospect_type='prospect5b', lidtype=1
)

Parameters

Name	Type	Description
traits	Tensor (batch, n_traits)	Leaf biochemical parameters (Cab, Car, Cbrown, Cw, Cm, etc.)
N	Tensor (batch)	Leaf structure parameter
LIDFa / LIDFb	Tensor	Leaf inclination distribution parameters
lai	Tensor	Leaf Area Index
q	Tensor	Hotspot parameter
tts	Tensor	Solar zenith angle (degrees)
tto	Tensor	Observer zenith angle (degrees)
psi	Tensor	Relative azimuth angle (degrees)
tran_alpha	Tensor	Leaf transmittance parameter (commonly 40°)
psoil	Tensor	Soil moisture parameter
batch_size	int	Processing batch size (for GPU memory control)
prospect_type	str	"prospect5b", "prospectd", "prospectpro"
lidtype	int	LIDF type (1–4)

Returns

A tensor of size:

(batch, spectral_length, 7)

Containing:

Output	Description
rdd	diffuse–diffuse canopy reflectance; reflectance of the canopy under diffuse illumination, integrated over diffuse exit directions.
tdd	diffuse–diffuse canopy transmittance; transmission of diffuse incident radiation through the canopy.
tsd	direct-to-diffuse transmission; direct solar radiation transmitted through the canopy and emerging as diffuse flux.
rsd	direct-to-diffuse reflectance; solar-incident radiation reflected by the canopy as diffuse flux.
tdo	diffuse-to-directional transmission; diffuse illumination transmitted in the sensor viewing direction.
rdo	diffuse-to-directional reflectance; diffuse illumination reflected in the sensor viewing direction.
tss	direct-to-direct transmission; transmission of direct solar beam through the canopy without scattering.
too	directional-to-directional transmission; radiation transmitted in the sensor direction, preserving its direction (reverse-beam path).
rsod	direct-to-directional reflectance; bi-directional reflectance for solar illumination and sensor viewing direction (BRF component).

Example: Simulating Canopy Reflectance

from torchrtm.models import prosail
import torch

B = 5000
device = "cuda"

traits = torch.rand(B, 5).to(device)
N = torch.rand(B).to(device)
LIDFa = torch.zeros(B).to(device)
LIDFb = torch.zeros(B).to(device)
lai = torch.ones(B).to(device) * 3
q = torch.ones(B).to(device) * 0.5
tts = torch.ones(B).to(device) * 30
tto = torch.ones(B).to(device) * 20
psi = torch.ones(B).to(device) * 10
alpha = torch.ones(B).to(device) * 40
psoil = torch.ones(B).to(device) * 0.5

toc = prosail(
    traits, N, LIDFa, LIDFb, lai, q,
    tts, tto, psi, alpha, psoil,
    batch_size=5000,
    prospect_type="prospect5b",
    lidtype=2
)

print(toc.shape)

---

2. SMAC Atmospheric Correction

TorchRTM supports SMAC for TOA correction.

from torchrtm.atmosphere.smac import smac
from torchrtm.data_loader import load_smac_sensor

Example

coefs, sm_wl = load_smac_sensor("S2A")

Ta_s, Ta_o, T_g, ra_dd, ra_so, ta_ss, ta_sd, ta_oo, ta_do = smac(
    tts=torch.tensor([30.0]),
    tto=torch.tensor([20.0]),
    psi=torch.tensor([10.0]),
    coefs=coefs
)

TOC → TOA Conversion

from torchrtm.atmosphere.smac import toc_to_toa

R_TOC, R_TOA = toc_to_toa(
    toc, sm_wl - 400,
    ta_ss, ta_sd, ta_oo, ta_do,
    ra_so, ra_dd, T_g
)

---

3. Torchlut: High-Performance LUT Generator

Generates millions of simulated samples using PROSPECT, PROSAIL, or ATOM.

from torchrtm.utils.torch_utils import Torchlut

Torchlut() — API Documentation

Torchlut(
    model='prospect5b',
    table_size=500000,
    std=0,
    batch=10000,
    wavelength=None,
    sensor_name='LANDSAT4-TM',
    sail_prospect='prospectd',
    use_atom=False,
    para_addr=None
)

Parameters

Parameter	Description
model	"prospect5b", "prospectd", "prospectpro", "prosail"
table_size	Number of samples to generate
std	Gaussian noise standard deviation
batch	Simulation batch size
wavelength	Select specific wavelength indices
sensor_name	Used when use_atom=True
sail_prospect	Leaf model used inside PROSAIL
use_atom	Enable ATOM (PROSAIL + SMAC)
para_addr	Parameter range configuration

Notes

When use_atom=True, the following sensor spectral-response files are supported:

• LANDSAT4-TM
• LANDSAT5-TM
• LANDSAT7-ETM
• LANDSAT8-OLI
• Sentinel2A-MSI
• Sentinel2B-MSI
• Sentinel3A-OLCI
• Sentinel3B-OLCI
• TerraAqua-MODIS

Returns

ref_list   # reflectance (TOC or TOA)
para_list  # parameter vectors

Torchlut Example

ref, params = Torchlut(
    model="prospectd",
    table_size=100000,
    batch=5000,
    std=0.01
)

---

4. Torchlut_pred: GPU KNN Retrieval Engine

Fast, block-wise KNN retrieval optimized for LUT inversion.

from torchrtm.utils.torch_utils import Torchlut_pred

Torchlut_pred() — API Documentation

Torchlut_pred(
    xb, xq, y,
    k=5,
    distance_order=2,
    xb_block=1000,
    batch_size=200,
    device="cuda"
)

Parameters

Parameter	Description
xb	Database features (N, D)
xq	Query features (M, D)
y	Database target values (N,) or (N, D_out)
k	Number of nearest neighbors
distance_order	1 = Manhattan, 2 = Euclidean, etc. We recommand to set it as 9
xb_block	Split xb to avoid GPU OOM
batch_size	Query batch size
device	cuda / cpu

Returns

preds: shape (M,) or (M, D_out)

How It Works (Internal Mechanism)

1. Move all tensors to GPU
2. Process queries in batches
3. For each batch, iterate through xb in blocks
4. Compute distance matrix efficiently (when distance_order = 2): $$|x-y| = \sqrt{x^2 + y^2 - 2xy}$$
5. Select global top-k neighbors
6. Average retrieved y-values

Supports multi-million LUT inference on consumer GPUs.

Example

preds = Torchlut_pred(
    xb=torch.tensor(ref),
    xq=torch.tensor(query_ref),
    y=torch.tensor(params),
    k=5,
    device="cuda"
)

---

5. Complete Retrieval Pipeline

# Step 1: Build LUT
ref_lut, para_lut = Torchlut(model="prospectd", table_size=300000)

# Step 2: Convert measured reflectance to tensor
xq = torch.tensor(measured_ref)

# Step 3: KNN retrieval
pred = Torchlut_pred(
    xb=torch.tensor(ref_lut),
    xq=xq,
    y=torch.tensor(para_lut),
    k=5
)

---

🤝 Contributing

PRs and issues are welcome!
Please include tests and clear descriptions.

---

📜 License

MIT License.

---