RAMS

Reliability-Aware Multimodal Sky-Sensor Network for Global Horizontal Irradiance Nowcasting

PyTorch implementation combining synchronized numerical histories and sky-image sequences. The repository contains model definitions, explicit window construction, training and evaluation commands, experiment configurations, tests, and selected trained checkpoints. No private observations or sky images are included.

Method

RAMS learns separate feature-selection masks for numerical observations and image embeddings. Consecutive image-embedding differences encode short-term visual change. Both sources are projected into a common representation space. Their absolute difference and element-wise product form a shared comparison context; source-conditioned sigmoid gates then reweight each representation independently. A learned source gate combines the representations with an explicit projected disagreement contribution. Temporal relevance scores are normalized across the input sequence, and their weighted summary predicts a residual relative to the last observed GHI.

The image encoder processes all frames in a batch together, using lightweight depthwise-separable residual blocks. The temporal component is weighted pooling, not recurrence. The released checkpoint variants are described in the model documentation.

Installation

The distribution name is rams-forecast; the Python import and command are rams. The pip distribution contains code only. Private data access requires separate, explicit authorization and is never granted by installing the package.

python -m pip install rams-forecast

Authorized local test data

The local test archive is held in the private Hugging Face repository mdanish3/RAMS-local-test. After the owner grants access, authenticate through hf auth login or a securely supplied HF_TOKEN. No owner credential is included.

rams data download --output ./private-local-test
rams data status --data ./private-local-test
rams data analyze --data ./private-local-test
rams data verify --data ./private-local-test
rams data explore --data ./private-local-test --horizon 3 --sample 0 --output ./sample.html
rams evaluate --checkpoint private-local-test/checkpoints/rams_local_3min.pt \
  --data private-local-test/3min --output ./evaluation.json

The offline HTML preview shows paired images, numerical features, timestamps, measured targets, and persistence. It does not upload data or open a network server. See private-data.md for access limitations and historical protocol details. Keep previews and downloaded data private.

Development Installation

Python 3.10 or newer is required. Install the appropriate PyTorch build for your CPU or CUDA environment, then install this checkout:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest -q

Load a model

import torch
from rams import load_checkpoint

model, metadata = load_checkpoint("checkpoints/rams_folsom_3min.pt")
config = model.network.config

# Shapes only: replace these with correctly scaled, paired observations.
numerical = torch.zeros(1, config.input_steps, config.sensor_features)
images = torch.zeros(1, config.input_steps, 3, config.image_height, config.image_width)
anchor = torch.zeros(1, 1)  # Last observed GHI in the target scaler's units.
with torch.inference_mode():
    prediction_scaled = model(numerical, images, anchor)

Checkpoint metadata supplies the feature order, input and target scalers, exact output leads, and persistence definition. Predictions must be inverse-transformed before computing physical-unit metrics.

Prepare, train, evaluate

Start from timestamped, image-paired records with an explicit chronological split. The input contract is documented in data.md. Original public dataset sources are recorded in src/rams/datasets.py; downloaded data remain outside version control.

rams prepare --records data/paired_records.csv \
  --config configs/rams_folsom_3min.json --output data/prepared

rams train --config configs/rams_folsom_3min.json \
  --data data/prepared --output outputs/folsom_3min \
  --device cuda --batch-size 64 --epochs 100 --patience 15

rams evaluate --checkpoint checkpoints/rams_folsom_3min.pt \
  --data data/prepared/test --output outputs/folsom_3min/evaluation.json

Training fits scalers on the training split only, selects checkpoints using validation RMSE, and never opens the test split. Evaluation exports pooled and per-output metrics plus paired predictions. It does not overwrite the manuscript. The training command is a clean configurable training entry point, not a replay of every historical tuning script; checkpoint-specific training parameters are preserved in each bundle.

Checkpoints

The source repository contains four historical local-data models, twelve primary-seed public-data models (three datasets, four horizons), and the explicitly selected local image-difference ablation. No baseline weights, exploratory trials, optimizer states, or private prediction files are distributed. File sizes and SHA-256 hashes are recorded in checkpoints/manifest.json.

These checkpoints are not embedded in the pip wheel or source distribution. Authorized local users obtain four matching local checkpoints with the private test-data archive; other repository checkpoints must be obtained separately.

All 17 checkpoints were strictly loaded and checked against the original implementation with bit-exact CPU forward parity on synthetic paired inputs. Details are in verification.json. This verifies model conversion, not a new measurement of test-set accuracy.

Protocol matters. The historical local checkpoints pool multiple outputs and retain their original timing and historical persistence reference. Their names must not be interpreted as exact final lead times. Public checkpoints predict one scalar at exactly +180, +300, +420, or +600 seconds. See evaluation.md before comparing results across protocols.

Layout

src/rams/       Model, datasets, scaling, training, inference, and metrics
configs/        Checkpoint-matched model and timing specifications
checkpoints/    Selected weights and integrity manifest
docs/           Architecture, data contract, and evaluation conventions
tests/          Metric, temporal-window, model, and checkpoint checks