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.0?

• 🌐 Peluncuran Resmi samudra_graph: Modul publik GNN independen (from samudra_graph import SamudraGraph) untuk pemodelan iklim terpadu multi-variabel (Suhu, Kelembapan Relatif, Curah Hujan Tweedie, dan Tekanan Permukaan).
• 🏆 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 mencakup peta atensi spasial, manifold PCA topografi, verifikasi adiabatic lapse rate, dan audit batas analitik.
• 🛰️ Mesoscale ERA5 Grid Selection: 4 strategi pemilihan sel reanalisis (Nearest, k-NN, Physical Radius Cutoff, Local 3x3 Patch, serta Contextual-Only Mode).

📦 Instalasi

Paket dapat diinstal langsung dari PyPI:

pip install 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 5 Baris

from samudra_graph import SamudraGraph

# 1. Inisialisasi model SOTA GNN-Attention
model = SamudraGraph(
    architecture="gnn-attention",
    variables=["temp", "rh", "rain", "pressure"],
    era5_grid_strategy="radius",
    era5_radius_km=25.0,
    masked_node_prob=0.20,
)

# 2. Latih model dengan data panel observasi
model.fit("data/m9/m9_multivariable_aligned_panel.csv", epochs=35)

# 3. Prediksi out-of-sample forward dengan rentang ketidakpastian konformal
preds = model.predict(test_start="2026-01-01", test_end="2026-08-01", return_uncertainty=True)

# 4. Rekonstruksi 3 Pilar: Gap-Filling, Virtual Stations, & Historical Hindcast
imputed = model.fill_gaps(outage_stations=["96001", "96011"])
virtual = model.virtual_stations(locations=[(-6.2, 106.8, "Jakarta_Ungauged")])
hindcast = model.hindcast(start_date="2021-01-01", end_date="2024-07-01")

# 5. Terbitkan bukti fisik hubungan fisis (Physics Explainability Suite)
model.explain(output_dir="outputs/explainability")

🏛️ 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/