Metadata-Version: 2.4
Name: rams-forecast
Version: 0.1.1
Summary: Reliability-aware multimodal sky-sensor networks for GHI nowcasting
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: Pillow>=10
Requires-Dist: torch>=2.2
Requires-Dist: huggingface-hub>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"

# 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](docs/model.md).

## 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.

```bash
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.

```bash
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](docs/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:

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

## Load a model

```python
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](docs/data.md). Original public
dataset sources are recorded in `src/rams/datasets.py`; downloaded data remain
outside version control.

```bash
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](docs/evaluation.md) before comparing results across protocols.

## Layout

```text
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
```

