samudra-ai 2.6.8

Paket Python untuk pengolahan koreksi bias pada model iklim global menggunakan deep learning menggunakan CNN dan LSTM.

samudra-ai

Library Python samudra-ai versi terbaru

SamudraAI 🌊

Paket Python versi terbaru untuk melakukan pengolahan koreksi bias model iklim global menggunakan arsitektur deep learning.

SamudraAI memudahkan peneliti dan praktisi di bidang ilmu iklim untuk menerapkan metode koreksi bias yang canggih pada data GCM (General Circulation Model) menggunakan data observasi sebagai referensi.

---

✨ Fitur Terbaru v2.5.6

• 🆕 Physics-Aware Auto-Config: Model secara otomatis menyesuaikan arsitektur berdasarkan karakteristik fisika variabel iklim (suhu vs hujan)
• 🆕 Station-Based Downscaling: SamudraAI1D dengan akurasi state-of-the-art untuk koreksi bias tingkat stasiun
• 🆕 Uncertainty Quantification: Monte Carlo Dropout untuk probabilistic forecasting dengan 95% confidence interval
• 🆕 Smart Visualization: Peta akurasi Cartopy, grafik time series, dan plot uncertainty otomatis
• 🆕 Multi-Variable Support: Optimasi khusus untuk suhu, curah hujan, angin, dan kelembaban
• 🆕 4 Model Pilihan: Dari yang ringan (SamudraAI) hingga high-precision (SamudraAI3/SamudraAI1D)

---

📊 Perbandingan 4 Model SamudraAI

Fitur	SamudraAI	SamudraAI2	SamudraAI3	SamudraAI1D
Arsitektur	CNN + BiLSTM	ConvLSTM2D	U-Net + ConvLSTM	Conv2D + BiGRU + Attention
Tipe Output	Grid 2D	Grid 2D Sequence	Grid 2D Sequence	Titik Stasiun
Input Data	Grid GCM	Grid GCM	Grid GCM	Grid GCM + Stasiun
VRAM Usage	🟢 2-4 GB	🟡 6-8 GB	🔴 12-16 GB	🟢 4-6 GB
Training Speed	🟢 Cepat	🟡 Sedang	🔴 Lambat	🟡 Sedang
Detail Spasial	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Konteks Temporal	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Uncertainty	❌	❌	❌	✅ MC Dropout
Best Use Case	Baseline cepat	Sequence forecast	High-precision grid	Koreksi stasiun

---

🎯 Panduan Pemilihan Model

1️⃣ SamudraAI (CNN-BiLSTM)

✅ Kelebihan:

• Training paling cepat & konsumsi VRAM paling ringan
• Robust terhadap noise & missing data berkat pooling & dropout
• Sangat baik menangkap tren temporal & rata-rata regional
• Bekerja stabil dengan dataset terbatas

⚠️ Kekurangan:

• Global pooling menghilangkan detail spasial resolusi tinggi
• Output spasial direkonstruksi dari Dense layer → cenderung smooth/blur
• Kurang optimal untuk pola lokal tajam (gradien pesisir, orografis)

🎯 Kapan Dipilih: Bias correction parameter iklim, studi regional skala besar, environment dengan GPU terbatas, atau baseline cepat.

---

2️⃣ SamudraAI2 (ConvLSTM2D)

✅ Kelebihan:

• Memodelkan dependensi spasial & temporal secara bersamaan
• Struktur spasial lebih terjaga dibanding pooling-based model
• Evolusi temporal halus berkat filter rekuren spasial
• Keseimbangan baik antara akurasi & biaya komputasi

⚠️ Kekurangan:

• Dapat kesulitan dengan skala spasial sangat tidak seragam
• Output sequence-to-sequence perlu slicing manual untuk next-step prediction
• VRAM lebih tinggi dari SamudraAI

🎯 Kapan Dipilih: Downscaling dan koreksi bias dengan transisi temporal yang penting dan resolusi temporal yang lebih tinggi.

---

3️⃣ SamudraAI3 (U-Net + ConvLSTM)

✅ Kelebihan:

• Ekstraksi fitur multi-skala (detail lokal + konteks global)
• Skip connections mempertahankan pola resolusi tinggi
• Dynamic resize menangani input dimensi ganjil/kecil secara robust (padding='same')

⚠️ Kekurangan:

• Konsumsi VRAM & waktu training paling tinggi
• Memerlukan tuning dropout & learning rate agar tidak overfit
• Rentan noise jika data training terlalu sedikit atau tidak stabil

🎯 Kapan Dipilih: Koreksi bias high-precision (curah hujan ekstrem), region dengan topografi/pesisir kompleks.

4️⃣ SamudraAI1D (Conv1D + BiGRU + Attention) 🆕

Arsitektur Station-Based untuk Koreksi Bias Presisi Tinggi

✅ Kelebihan:

• Physics-Aware: Otomatis menyesuaikan patch_size berdasarkan variabel (3 untuk hujan, 5 untuk suhu)
• Hybrid Architecture: Dilated Conv2D (spasial) + BiGRU (temporal) + Attention (fokus kritis)
• Metadata Fusion: Mengintegrasikan koordinat (lat/lon), elevasi, dan fitur seasonal (sin/cos)
• Robust Training: Anti-NaN, anti-overfitting, dengan EarlyStopping & ReduceLROnPlateau
• Uncertainty Quantification: MC Dropout untuk 95% confidence interval
• Production-Ready: Validasi pada 117-182 stasiun BMKG se-Indonesia

⚠️ Kekurangan:

• Memerlukan data observasi stasiun (CSV/Excel)
• Training lebih lama untuk dataset besar (>100 stasiun)
• Memerlukan GPU dengan VRAM minimal 4GB

🎯 Kapan Dipilih:

• Koreksi bias tingkat stasiun dengan akurasi tinggi
• Downscaling dari GCM/Reanalysis ke titik observasi
• Aplikasi operasional BMKG, pertanian presisi, early warning system
• Ketika Anda butuh uncertainty quantification untuk risk assessment

---

🌍 Use Cases

Use Case	Model Rekomendasi	Alasan
Downscaling cepat, GPU terbatas	SamudraAI	VRAM rendah, training cepat
Sequence forecasting	SamudraAI2	Output sequence native
Topografi kompleks	SamudraAI3	Detail spasial tajam
Koreksi bias stasiun	SamudraAI1D	Presisi tinggi + uncertainty
Early warning system	SamudraAI1D	Titik spesifik + risk assessment
Studi iklim regional	SamudraAI / SamudraAI3	Peta 2D lengkap

---

📦 Instalasi

Anda dapat menginstal SamudraAI langsung dari PyPI menggunakan pip:

pip install samudra-ai

🛠️ API Reference

SamudraAI (CNN-BiLSTM)

Class untuk downscaling grid 2D.

Parameters:

• config (ModelConfig): Konfigurasi model

Methods:

• fit(gcm_input, obs_target): Training
• predict(gcm_input): Generate data masa depan terkoreksi
• correction(gcm_grid, station_df): Generate data historical terkoreksi
• evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
• analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
• save(path) / load(path): Persistensi

SamudraAI2 (ConvLSTM2D)

Class untuk sequence-to-sequence forecasting.

Parameters:

• config (ModelConfig2): Konfigurasi model

Methods:

• fit(gcm_input, obs_target): Training
• predict(gcm_input): Generate data masa depan terkoreksi
• correction(gcm_grid, station_df): Generate data historical terkoreksi
• evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
• analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
• save(path) / load(path): Persistensi

SamudraAI3 (U-Net + ConvLSTM)

Class untuk high-precision downscaling.

Parameters:

• config (ModelConfig3): Konfigurasi model

Methods:

• fit(gcm_input, obs_target): Training
• predict(gcm_input): Generate data masa depan terkoreksi
• correction(gcm_grid, station_df): Generate data historical terkoreksi
• evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
• analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
• save(path) / load(path): Persistensi

SamudraAI1D (Station-Based) 🆕

Class untuk station-based bias correction.

Parameters:

• time_seq (int): Ukuran window temporal (default: 9)
• config (ModelConfig1D, optional): Konfigurasi custom
• mode (str, optional): Mode auto-config (suhu, hujan, angin, kelembaban)
• patch_size (int, optional): Override patch size

Methods:

• fit(gcm_grid, station_df): Training
• correction(gcm_grid, station_df): Generate data terkoreksi
• evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
• analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
• save(path) / load(path): Persistensi

Requirements

• Python >= 3.9
• TensorFlow >= 2.15
• NumPy, Pandas, Xarray
• Scikit-learn, Matplotlib
• Cartopy (opsional, untuk visualisasi geografis)

✅ Best Practice

• ✅ Disarankan menggunakan TensorFlow GPU untuk performa optimal
• ✅ Disarankan memiliki memory / RAM yang cukup untuk pengolahan data dengan resolusi tinggi dan luasan domain yang besar
• ✅ Jalankan versi tunning yang sudah ter hardcore. Bila hasil kurang optimal bisa menyesuaikan ulang parameter tunningnya secara manual
• ✅ Gunakan mode="suhu" atau mode="hujan" untuk auto-config optimal
• 💡 Format .nc/.xlsx hasil koreksi bisa langsung digunakan untuk plotting dan analisis

How To Use :

https://github.com/adityoAJA/samudra-ai/blob/main/How-to-use-samudra-ai.txt

📄 Lisensi :

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

📧 Kontak:

Untuk pertanyaan, issue, atau peluang kolaborasi: GitHub: https://github.com/adityoAJA/samudra-ai Email: [[e-mail]]

@software{samudra_ai_2026, author = {Adityo A.J.}, title = {SamudraAI: Deep Learning for Climate Bias Correction}, version = {2.5.6}, year = {2026}, url = {https://pypi.org/project/samudra-ai/} }