Skip to main content

SpectraLoRA: Physics-Aware Fine-Tuning for Geospatial Foundation Models

Status Python PyTorch

SpectraLoRA is a specialized Parameter-Efficient Fine-Tuning (PEFT) library designed for multispectral satellite imagery. Unlike standard LoRA, which treats all input channels equally, SpectraLoRA introduces a Physics-Aware Gating Mechanism that dynamically routes information to specialized adapters based on the spectral signature of the terrain (e.g., Vegetation, Water, Urban).

This architecture is designed to fine-tune massive Geospatial Foundation Models (like IBM/NASA Prithvi-100M) on consumer hardware while enforcing physical consistency in predictions.


🏗️ System Architecture

SpectraLoRA operates as a "Sidecar" to the frozen foundation model. It intercepts data flow to inject physics context without altering the pre-trained weights.

Key Innovations

  1. Spectral Fingerprinting: Calculates real-time physics indices (NDVI, NDWI, BSI) before the model runs.
  2. Mixture-of-Experts (MoE): A bank of specialized Low-Rank Adapters (e.g., one for forests, one for cities).
  3. Dynamic Gating: A lightweight router that blends adapters based on the material properties of the image patch.
  4. Built-in MLOps Tracking: Automatically logs hyperparameters, training loss, and GeoAI-specific metrics (mIoU, Physics Violations) to local SQLite or enterprise PostgreSQL databases.
  5. Geospatial Data Catalog: Leverages PostGIS to ingest, index, and dynamically filter satellite chips using precise Earth coordinates (EPSG:4326) directly within the PyTorch training loop.

🖼️ Visualizing Results

SpectraLoRA is built to handle highly diverse, complex geographies—from arid deserts to dense coastal urban infrastructure. The library includes built-in batch prediction tools to visualize the AI's 4-class segmentation (Barren, Vegetation, Water, Urban) side-by-side with true-color satellite imagery.

SpectraLoRA Doha Prediction (Example output showing true RGB imagery alongside the SpectraLoRA physics-routed prediction)


📂 Project Structure

SpectraLoRA/
├── spectra_lora/               # The Core Library Package
│   ├── __init__.py             # API Exporter
│   ├── config.py               # Phase 1: Global Configuration & Band Maps
│   ├── spectral_ops.py         # Phase 1: The Physics Engine (NDVI/BSI Math)
│   ├── gating_network.py       # Phase 2: The Neural Router (MLP)
│   ├── layers.py               # Phase 2: The Custom SpectraLoRALayer
│   ├── model_wrapper.py        # Phase 3: The Surgeon (Model Loader & Injector)
│   └── utils.py                # Helpers: GeoTIFF Loading & Visualization
│
├── experiments/                # Execution Scripts & Testing
│   ├── train.py                # Phase 4: Training Loop & Context Patching
│   ├── evaluate.py             # Phase 4: Physics-Aware Evaluation Metrics
│   ├── predict.py              # Phase 5: Batch Inference & Visualization tool
│   └── predictions_output/     # Saved side-by-side RGB vs AI prediction plots
│
├── setup.py                    # PyPI Installation Configuration
├── requirements.txt            # Dependencies
├── LICENSE                     # MIT License
└── README.md                   # This file

📚 Documentation

For a complete guide on how the Physics Engine works, detailed API references, and advanced usage tutorials, please visit our official documentation site:

📖 Read the SpectraLoRA Documentation Here

🚀 Quick Start

Installation

You can install the library directly via pip:

pip install spectralora

(Alternatively, clone the repository and run pip install -r requirements.txt for development).

Usage (Python API)

Use SpectraLoRA to upgrade a standard Prithvi model with physics-aware adapters:

from spectra_lora import load_prithvi_model, inject_spectra_lora

# 1. Load the frozen Foundation Model (Prithvi-100M)
model = load_prithvi_model()

# 2. Perform Surgery: Inject SpectraLoRA layers
model = inject_spectra_lora(model)

# 3. The model is now ready for training!
# Only the adapter parameters (approx 1-5%) are trainable.

📖 Detailed File Guide

1. The Physics Core (spectra_lora/)

  • spectral_ops.py: The mathematical heart of the library. It takes raw satellite tensors and calculates 5 physics indices: NDVI (Vegetation), SAVI (Soil-Adjusted Vegetation), NDWI (Water), NDBI (Built-up), and BSI (Bare Soil). This ensures the model "sees" physics, not just pixels.
  • config.py: The blueprint. Defines the Band Map (Blue=0, NIR=3, etc.) to ensure calculations are accurate for the Prithvi model. It also sets LoRA hyperparameters (Rank=4, Alpha=8).
  • utils.py: Handles the messy parts of Geospatial AI. Contains load_geotiff to normalize 16-bit satellite data into float32 tensors, and visualization tools to debug the spectral fingerprint.

2. The Neural Architecture (spectra_lora/)

  • gating_network.py: A tiny Multi-Layer Perceptron (MLP). It takes the 5-dimensional physics vector from spectral_ops and outputs soft mixing weights (e.g., [0.8, 0.1, 0.1]) to control the adapters.
  • layers.py: The custom PyTorch module. It replaces standard Linear layers. It contains:
  • The Frozen original weights.
  • The Adapter Bank (3 parallel LoRA experts).
  • The Gating Network.
  • Logic: $Output = Frozen(x) + \sum_{i} (Gate_i(z) \cdot Adapter_i(x))$

3. The Integration (spectra_lora/)

  • model_wrapper.py: The "Surgeon." It downloads the Prithvi architecture code dynamically from Hugging Face (since it's not in standard transformers), loads the weights, and recursively swaps Attention layers with SpectraLoRALayer.
  • __init__.py: Exposes the high-level API so you can import functions cleanly.
  • db.py: The MLOps database engine. Utilizes SQLAlchemy to auto-generate tracking schemas and securely log experiment data without forcing users to write manual SQL.
  • ingest.py: The Spatial Crawler. Automatically extracts geographic bounding boxes and metadata (like cloud cover) from raw .tif files and populates the PostGIS spatial catalog.

4. Experiments (experiments/)

  • train.py: The training engine. It includes a critical Runtime Patch (patch_model_for_context) that allows the model to access the global "Physics Context" without rewriting the original Prithvi code.
  • evaluate.py: A custom validator. Beyond standard mIoU, it calculates a "Physics Violation Score"—counting how many times the model predicted "Vegetation" in a pixel where the NDVI was clearly "Desert."
  • predict.py: A batch-processing visualization tool that iterates through .tif datasets and outputs RGB-vs-Prediction maps.

📊 Citation

If you use this code for your research, please cite:

@software{spectralora2026,
  author = {Munieb Abdelrahman},
  title = {SpectraLoRA: Band-Specific Low-Rank Adaptation for Geospatial Foundation Models},
  year = {2026},
  url = {[https://github.com/MuniebA/SpectraLoRA](https://github.com/MuniebA/SpectraLoRA)}
}

Metadata

Release files for spectralora 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spectralora 0.2.0
File Size Uploaded Provenance Actions
spectralora-0.2.0.tar.gz 20.3 kB Without provenance Details for spectralora-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spectralora 0.2.0
File Interpreter ABI Platform Actions
spectralora-0.2.0-py3-none-any.whl Python 3 none any Details for spectralora-0.2.0-py3-none-any.whl

Total release size: 40.4 kB

Release files / spectralora-0.2.0.tar.gz

Download URL spectralora-0.2.0.tar.gz
Size 20.3 kB
Tags Source
SHA-256 checksum
How to use checksums
811fa4a37586fa9f436c149fa7070fd7afe35d0140484cf98b0edb0546724815
BLAKE2b-256 checksum
How to use checksums
4f394b60d794de6f3c6f10367d5f5260fa37784428f90a0eeb5e701345a97c7e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.6

Release files / spectralora-0.2.0-py3-none-any.whl

Download URL spectralora-0.2.0-py3-none-any.whl
Size 20.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
65a5fde349b472fb2fbcdc92c2565e03cef7ccc45c8d743e0bbe83dcc3e0628e
BLAKE2b-256 checksum
How to use checksums
c4ba051f8f555e2c31d51c82638aae2800cc3b4e7d71e6b62b2ec860793ab139
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.6

Security for spectralora 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page