Getting Started with SpectraLoRA¶
Welcome to the official documentation for SpectraLoRA, a Physics-Aware Parameter-Efficient Fine-Tuning (PEFT) library built for Geospatial Foundation Models.
The Problem with Standard LoRA in Geospatial AI¶
Standard Low-Rank Adaptation (LoRA) is an incredible tool for text models (LLMs). However, when applied to multi-spectral satellite imagery, standard LoRA treats all input channels blindly. It applies the same learned weight updates regardless of whether it is looking at the Sahara Desert, the Amazon Rainforest, or the concrete skyline of Doha.
The SpectraLoRA Solution¶
SpectraLoRA introduces a Physics-Aware Mixture-of-Experts (MoE) architecture. Instead of one generic adapter, SpectraLoRA injects a bank of specialized LoRA adapters (e.g., an "Urban Expert," a "Water Expert," and a "Vegetation Expert").
Before the model processes an image patch, our Physics Engine calculates its Spectral Fingerprint (NDVI, NDWI, BSI, etc.). A tiny neural router then dynamically blends the adapters based on the physical properties of the terrain.
Core Equation¶
The forward pass of a SpectraLoRALayer is defined as:
Where: * \(x\) is the input tensor. * \(z\) is the 5-dimensional physics context vector. * \(Gate_i(z)\) is the soft-routing probability for expert \(i\). * \(Adapter_i(x)\) is the low-rank projection \(B(A(x))\).
Quick Installation¶
Install directly from PyPI:
pip install spectralora
Basic Usage¶
from spectra_lora import load_prithvi_model, inject_spectra_lora
# 1. Load the frozen foundation model
model = load_prithvi_model()
# 2. Inject the physics-aware adapters into the Attention layers
model = inject_spectra_lora(model)
# 3. Model is ready for your PyTorch training loop!
Built-in Experiment Tracking¶
By default, SpectraLoRA actively tracks your training loops. The moment you run an experiment, it creates a spectralora_experiments.db SQLite file in your local directory, saving your configuration, epoch durations, and validation metrics.
For enterprise users running cluster training, you can securely route this data to PostgreSQL by setting the SPECTRALORA_DB_URL environment variable. See the MLOps Tracking page for advanced usage.
Spatially-Aware Training (v0.2.0+)¶
SpectraLoRA goes beyond traditional folder-based data loading. By connecting to a PostGIS database, you can dynamically filter your training data based on geographic bounds, acquisition dates, and cloud cover.
(Drop an architecture diagram in your assets folder showing raw images going into PostGIS!)
To build your catalog, simply point the ingestion engine at your satellite imagery:
from spectra_lora import ingest_satellite_folder
# Extracts GPS coordinates and saves them to PostGIS
ingest_satellite_folder("dataset_224x224")
See the Spatial Catalog page for a full guide on querying this data during training.