SamudraAI & SamudraGraph 🌊🌐

SamudraAI adalah platform komputasi cerdas iklim (Deep Climate Science) terpadu untuk wilayah kepulauan Indonesia. Paket ini menyediakan arsitektur Dual-Engine canggih:

1. Engine 1 (samudra_ai): Koreksi bias model iklim global (GCM) dan downscaling resolusi spasial berbasis Convolutional Neural Network (CNN, ConvLSTM2D, U-Net, dan Conv1D-BiGRU-Attention).
2. Engine 2 (samudra_graph): Pemodelan graf spasial-klimatologis dan rekonstruksi iklim (Graph Neural Networks) berbasis Dynamic Relational GATv2, topologi heterogen stasiun BMKG & sel reanalisis ERA5, kuantifikasi ketidakpastian konformal, serta pembuktian fisis termodinamika.

🚀 Apa yang Baru di v2.7.7?

• ⚡ Akselerasi Otomatis GPU CUDA Penuh: Deteksi perangkat keras cerdas (device=None / 'cuda'), alokasi VRAM GPU untuk tensor batch & model PyTorch, serta Per-Device Edge Tensor Caching yang memangkas waktu latih dari ~49 detik/epoch (CPU) menjadi ~3–5 detik/epoch di GPU Google Colab / server (~10x speedup).
• 🗺️ Plot Topologi Regional Fokus Resolusi Tinggi: Dukungan visualisasi regional (region="jawa", region="papua", dll.) pada sg.plot_topology(), lengkap dengan anotasi label nama stasiun resmi BMKG (white-pill callout) dan visualisasi keterhubungan ganda (bipartite ERA5 $\leftrightarrow$ BMKG dan k-NN intra-BMKG).
• 🎯 Laju Belajar Mandiri untuk Spesialis Curah Hujan: Metode sg.fit_specialist(target_variable="bmkg_rainfall") secara cerdas mengadopsi laju belajar stabil (eff_lr = 0.0015) guna mencegah fluktuasi gradien ekstrem pada Tweedie Deviance Loss, sementara sg.fit() standar tetap mempertahankan arsitektur murni dan self.learning_rate seragam untuk seluruh variabel.
• 🏷️ Kontekstualisasi Header Evaluasi Metrik: Deteksi cerdas antara evaluasi HISTORICAL HINDCAST RECONSTRUCTION (masa lalu) vs OUT-OF-SAMPLE FORWARD TEST (masa depan) pada laporan konsol dan judul plot evaluasi.

🚀 Apa yang Baru di v2.7.4?

• 🔄 Ekstraksi & Penyelarasan Otomatis ERA5 Dinamis: Penyelarasan otomatis fitur reanalisis atmosfer ERA5 terdekat (era5_t2m, era5_d2m, era5_sp, era5_ssrd, era5_pev, era5_w10, era5_rh, era5_tp) langsung dari berkas kisi NetCDF secara efisien di memori. Berkas CSV stasiun BMKG kini dapat murni memuat kolom observasi in-situ BMKG tanpa perlu duplikasi kolom ERA5 secara statis.
• 🎯 Integrasi Multi-Modal pada Tahap 1 VIF Screening (screen_features()): Mengakomodasi kandidat prediktor gabungan (observasi in-situ BMKG + batas reanalisis ERA5 global) secara langsung ke dalam kalkulasi VIF pra-pelatihan, menghasilkan hingga 12–13 fitur kandidat prediktor non-redundant.
• 🛑 Fitur Early Stopping & Best Weights Restoration: Penambahan mekanisme penghentian dini otomatis pada SamudraGraph.fit() (early_stopping=True, early_stopping_patience=7, early_stopping_min_delta=1e-4) yang memantau kurva konvergensi loss dan secara otomatis memulihkan state bobot model terbaik (best_model_state_dict) untuk mencegah overfitting serta mengoptimalkan waktu komputasi.
• 🛡️ Pencegahan Nilai NaN Kisi Pesisir (Valid Land Mask Slicing): Algoritma pencarian sel reanalisis terdekat kini memprioritaskan sel daratan berhingga (finite land cells) terdekat untuk stasiun kepulauan dan pesisir sehingga menjamin 100% data valid (0% NaN) pada seluruh deret waktu ERA5 1950–2026.

🚀 Apa yang Baru di v2.7.3?

• 💾 Model Checkpoint Save & Load (model.save() & SamudraGraph.load()): Menyimpan seluruh bobot model neural network, topologi graf heterogen, kalibrator kuantil conformal, dan scaler normalisasi ke berkas checkpoint .pt. Pengguna dapat memuat kembali model terlatih kapan saja untuk langsung menjalankan inferensi (predict(), hindcast(), dll.) tanpa perlu pelatihan ulang (zero retraining overhead). Parameter save_path juga disematkan langsung pada fit().
• 🌐 NetCDF Terpadu (Unified ERA5 Dataset): Penggabungan variabel geopotensial orografi z langsung ke dalam berkas NetCDF ERA5 (data_ERA5_indo_1950_2026.nc). Input masukan kini ringkas hanya 2 berkas (DATA_PANEL dan DATA_ERA5), tanpa memerlukan berkas metadata terpisah (metadata_ERA5_indo.nc).
• 🏔️ Resolusi Elevasi Orografi Otomatis: Seluruh builder topologi multisel ERA5 (nearest, knn, radius, patch) dan lookup relief elevasi otomatis mengekstrak elevasi meter fisis ($z / 9.80665$) langsung dari berkas NetCDF primer.
• 📊 Live Progress Tracking & Interactive tqdm: Menambahkan pelacak progres pelatihan interaktif pada SamudraGraph.fit() dengan visual progress bar tqdm per epoch dan per variabel (estimasi waktu dan nilai loss real-time), disertai mekanisme fallback ke logging periodik.
• 🛠️ Ketahanan Dependensi & Headless Execution: Menghapus impor grafis tidak terpakai pada level modul core dan menambahkan dependensi resmi tqdm pada distribusi pyproject.toml.

🚀 Apa yang Baru di v2.7.2?

• 🛠️ Hotfix VIF Screening (model.screen_features()): Perbaikan impor eksplisit transformer VIFScreeningSelector pada modul core sehingga tahap eksplorasi fitur dan kalkulasi skor VIF berjalan mulus di seluruh runtime.
• ⚡ High-Level Interactive API: Otomatisasi visualisasi dan evaluasi dengan parameter plot=True dan evaluate=True pada fit(), predict(), hindcast(), fill_gaps(), dan virtual_stations().
• 🔍 Guided Feature Exploration & VIF Screening (model.screen_features()): Evaluasi multikolinearitas pra-pelatihan otomatis, penghitungan Variance Inflation Factor eksak, dan pemangkasan fitur redundan secara stepwise dengan output tabel ranking & plot grafik batang.
• 📁 Ekspor 1-Pintu (export_all()): Ekspor seluruh hasil rekonstruksi sekaligus ke standar biner internasional CF-1.8 DSG NetCDF-4 dan BMKG archive CSV.
• 🌐 Spatio-Temporal GNN Level 2 ("st-gnn"): Arsitektur unggulan MultiVariableSpatioTemporalGAT2 dengan modular window_size (default: 3 bulan = 1 fase monsun penuh).
• 🏆 State-of-the-Art GNN-Attention (GATv2): Pembobotan pesan dinamis (anisotropic dynamic attention) yang mempertimbangkan jarak fisik geodesik, relief orografi topografi riil ($\Delta z$), dan tipe relasi busur RGAT.
• 🌫️ Graph Masked Autoencoder Pretraining: Regulasi masked node dropout induktif yang melatih model merekonstruksi informasi secara mandiri saat sensor stasiun padam (blackout). Peningkatan akurasi gap-filling $+13.8%$ hingga $+38.5%$!
• 🎯 Graph Conformal Prediction (G-CP): Kuantifikasi ketidakpastian probabilistik adaptif dengan jaminan cakupan fisik matematis $90%$ yang mematuhi batas fisis (RH $[0, 100%]$, Hujan $\ge 0$).
• 🧭 Modular Edge Attributes (2D / 4D / 5D): Pilihan atribut busur dari baseline parsimonious 2D ([distance, elevation]), 4D kompas arah periodik, hingga 5D proyeksi vektor adveksi angin monsun.
• 🔬 Physics Explainability Suite: Generator bukti fisis otomatis via model.explain() (peta atensi spasial, manifold PCA topografi, verifikasi adiabatic lapse rate, dan audit batas analitik).

📦 Instalasi

Paket dapat diinstal langsung dari PyPI:

pip install --upgrade samudra-ai

Setelah instalasi, kedua modul dapat langsung diimpor:

import samudra_ai     # Engine 1: CNN GCM Bias Correction
import samudra_graph  # Engine 2: Spatial Graph Neural Networks

🌐 ENGINE 2: SAMUDRAGRAPH (samudra_graph)

samudra_graph dirancang khusus untuk merekonstruksi dan memodelkan variabel iklim multivariat di wilayah kepulauan Indonesia dengan topografi kompleks dan keterbatasan jaringan sensor in-situ.

⚡ Quickstart Bersih & Interaktif (Colab Ready)

from samudra_graph import SamudraGraph

# 1. Inisialisasi model Level 2 ST-GNN
model = SamudraGraph(
    architecture="st-gnn",
    variables=["temp", "rh", "rain", "pressure"],
    window_size=3,
    era5_grid_strategy="radius",
    era5_radius_km=25.0,
    nc_path="data/data_ERA5_indo_1950_2026.nc",
)

# 2. Latih model (otomatis plot topologi & kurva loss)
model.fit(
    train_data="data/bmkg_monthly_1981_2026.csv",
    train_start="1991-01-01",
    train_end="2020-12-01",
    epochs=35,
    plot=True,
)

# 3. Prediksi out-of-sample forward (otomatis hitung metrik & plot)
preds = model.predict(
    test_start="2021-01-01",
    test_end="2024-07-01",
    evaluate=True,
    plot=True,
)

# 4. Rekonstruksi 3 Pilar: Hindcast, Gap-Filling, & Virtual Stations
hindcast = model.hindcast(start_date="1981-01-01", end_date="1990-12-01", plot=True)
imputed = model.fill_gaps(station_data="data/bmkg_monthly_1981_2026.csv", plot=True)
virtual = model.virtual_stations(start_date="2021-01-01", end_date="2024-07-01", plot=True)

# 5. Ekspor produk lengkap ke CF-1.8 DSG NetCDF-4 & BMKG CSV
model.export_all(hindcast=hindcast, filled=imputed, virtual=virtual, forecast=preds)

# 6. Terbitkan bukti fisik hubungan fisis (Physics Explainability Suite)
model.explain()

🏛️ Arsitektur yang Didukung

⏱️ Penggunaan Modular Time Window (window_size):

Pada arsitektur "st-gnn", parameter panjang jendela waktu deret bulan (window_size, atau alias time_window) bersifat modular dan dapat diatur bebas sesuai kebutuhan riset:

# Default rekomendasi: window_size=3 (merepresentasikan 1 musim penuh monsun Indonesia)
model = SamudraGraph(architecture="st-gnn", window_size=3)

# Eksplorasi siklus transisi monsun (misal 6 bulan atau 9 bulan)
model_6m = SamudraGraph(architecture="st-gnn", window_size=6)

📊 Hasil Uji Benchmark Utama SamudraGraph

• Spatio-Temporal Memory (Level 2 ST-GNN): Integrasi memori rekuren GRU modular ($W=3$) memangkas error barometrik tekanan stasiun sebesar $+55.31%$ (MAE $10.99 \to 4.91\text{ hPa}$), menurunkan error curah hujan sebesar $+20.62%$ (MAE $156.4 \to 124.15\text{ mm}$), dan melesatkan korelasi hujan ke $r = 0.5586$ (vs $r=0.3050$ pada baseline snapshot).
• Akurasi Suhu Permukaan: Rekor MAE terendah $0.6030^\circ\text{C}$ dicapai pada strategi Physical Radius Cutoff $25\text{ km}$ ($+10.72%$ skill gain dibanding baseline), dan meningkat ke $0.5288^\circ\text{C}$ pada ST-GNN $W=9$.
• Akurasi Kelembapan Relatif: MAE $2.7708%$ ($+5.28%$ skill gain).
• Korelasi Tekanan Stasiun: Korelasi Pearson melonjak dari $r=0.2751$ ke $r=0.7014$ nasional ($r=0.8385$ di Sumatra dan $r=0.9809$ di Jawa) berkat integrasi orografi geopotensial riil dan memori barometrik.
• Puncak Monsun Barat: Varian adveksi angin 5D memangkas MAE menjadi $0.6189^\circ\text{C}$ ($+3.82%$ skill gain saat monsun Asia aktif melintasi Laut Jawa).
• Validasi Hukum Termodinamika: Gradien adiabatik suhu empiris terhadap elevasi terbukti mematuhi environmental lapse rate atmosfer tropis ($-5.82^\circ\text{C} / \text{km}$).

🌊 ENGINE 1: SAMUDRAAI (samudra_ai)

samudra_ai berfokus pada koreksi bias data iklim global (GCM) terhadap observasi grid atau stasiun BMKG menggunakan deep learning.

📊 Perbandingan 4 Model SamudraAI

🎯 Panduan Pemilihan Model SamudraAI

• SamudraAI (CNN-BiLSTM): Training paling cepat & konsumsi VRAM paling ringan. Cocok untuk studi regional skala besar atau baseline cepat.
• SamudraAI2 (ConvLSTM2D): Memodelkan dependensi spasial & temporal secara bersamaan. Keseimbangan baik antara akurasi & komputasi.
• SamudraAI3 (U-Net + ConvLSTM): Ekstraksi fitur multi-skala dengan skip connections. Unggul untuk wilayah dengan topografi kompleks dan hujan ekstrem.
• SamudraAI1D (Conv1D + BiGRU + Attention): Model station-based downscaling dengan integrasi metadata fisik (lat/lon, elevasi, seasonal) dan MC Dropout 95% confidence interval.

🛠️ Ringkasan API SamudraAI

import samudra_ai

# Contoh penggunaan SamudraAI1D untuk koreksi stasiun
model_cnn = samudra_ai.SamudraAI1D(time_seq=9, mode="suhu")
model_cnn.fit(gcm_grid, station_df)
corrected = model_cnn.correction(gcm_grid, station_df)
model_cnn.evaluate_and_plot(raw_gcm_data, ref_data, output_dir="outputs/plots")

📋 Persyaratan Lingkungan (Requirements)

• Python: >= 3.9
• Machine Learning: torch >= 2.0.0, tensorflow >= 2.10
• Sains Data & Geospasial: numpy, pandas, xarray, netCDF4, h5netcdf, scipy, scikit-learn
• Visualisasi: matplotlib, seaborn, cartopy (opsional untuk peta geografis)

📄 Lisensi & Sitasi

Proyek ini dilisensikan di bawah MIT License. Lihat berkas LICENSE untuk detailnya.

Jika Anda menggunakan SamudraAI atau SamudraGraph dalam penelitian ilmiah, silakan sitasi:

@software{samudra_ai_2026,
  author = {Adityo Wicaksono},
  title = {SamudraAI: Deep Learning & Graph Neural Networks for Climate Science},
  version = {2.7.0},
  year = {2026},
  url = {https://pypi.org/project/samudra-ai/}
}

📧 Kontak & Kolaborasi

• Pusat Riset: BMKG (Badan Meteorologi, Klimatologi, dan Geofisika), Indonesia
• Author: Adityo Wicaksono (adityo.wicaksono@bmkg.go.id)
• GitHub: https://github.com/adityoAJA/samudra-ai
• PyPI Package: https://pypi.org/project/samudra-ai/