README.md

---
license: apache-2.0
tags:
  - coastal-dynamics
  - oceanography
  - wave-prediction
  - physics-informed
  - neural-operator
  - climate
  - earth-science
  - pytorch
language:
  - en
pipeline_tag: other
library_name: pytorch
---

# Naturecode Coastal Dynamics

**State-of-the-Art AI for Coastal Wave Dynamics and Ocean Modeling**

*Initial Release.0 - Foundation Release*

*Designed to augment/replace traditional numerical models like MIKE 21*

---

## Overview

**Naturecode Coastal Dynamics** is a cutting-edge deep learning system for predicting coastal wave dynamics, sediment transport, and ocean conditions. This foundation release establishes the core architecture incorporating the latest advances from 2025-2026 oceanographic AI research.

---

## Architecture Features

| Feature | Source | Description |
|---------|--------|-------------|
| Fourier Neural Operator (FNO) | Li et al. 2021 | Spectral convolutions for PDE solving |
| Mixture-of-Time (MoT) | FuXi-Ocean NeurIPS 2025 | Adaptive temporal fusion for multi-scale forecasting |
| Adaptive Layer Normalization (AdaLN) | FuXi-Ocean NeurIPS 2025 | Context-aware normalization |
| Earthformer Cuboid Attention | NeurIPS 2022 + Science Advances 2024 | Remote swell detection from distant storms |
| Mamba Neural Operator | J. Comp Physics Dec 2025 | 90% error reduction over Transformers |
| MC Dropout | XWaveNet | Uncertainty quantification via Monte Carlo dropout |
| Energy Conservation Loss | OceanCastNet | Physical constraint for long-term stability |
| Diffusion Refinement | OmniCast/GenCast | Probabilistic ensemble forecasting |
| VAE Latent Compression | OmniCast NeurIPS 2025 | Efficient latent-space diffusion |
| Extreme Event Detection | XWaveNet | Multi-threshold wave height exceedance prediction |

### Model Statistics

| Specification | Value |
|---------------|-------|
| Parameters | 14,027,854 (14M) |
| Architecture | Hybrid FNO + Mamba + Swin Transformer |
| Input Channels | 8 |
| Output Channels | 5 |
| Training Epochs | 500 |
| Training Hardware | 8x NVIDIA H100 GPUs |
| Training Data | 18.4M real ocean observations |

---

## Input/Output Specification

### Input Channels (8)

| Channel | Description | Units |
|---------|-------------|-------|
| 0 | Bathymetry | meters (negative = depth) |
| 1 | Wind U-component | m/s |
| 2 | Wind V-component | m/s |
| 3 | Previous wave height | meters |
| 4 | Previous U-velocity | m/s |
| 5 | Previous V-velocity | m/s |
| 6 | Previous surface elevation | meters |
| 7 | Time encoding | normalized [0, 1] |

### Output Channels (5)

| Channel | Description | Units |
|---------|-------------|-------|
| 0 | Significant wave height | meters |
| 1 | U-velocity | m/s |
| 2 | V-velocity | m/s |
| 3 | Surface elevation (eta) | meters |
| 4 | Sediment transport | kg/m2/s |

---

## Intended Use

### Primary Use Cases

- Coastal Engineering: Wave prediction for harbor design, breakwater planning
- Climate Adaptation: Storm surge and extreme event forecasting
- Environmental Monitoring: Sediment transport and coastal erosion prediction
- Marine Operations: Sea state forecasting for shipping and offshore operations
- Research: Accelerating ocean/coastal simulations (1000x faster than MIKE 21)

### Out-of-Scope Uses

- Real-time tsunami warning (requires specialized systems)
- Operational weather forecasting without domain validation
- Areas without adequate bathymetric data

---

## Training Data

### Data Sources

1. Synthetic Physics-Based Data: Generated using simplified shallow water equations
2. NOAA NDBC Buoy Data: Real ocean observations from 60 buoys (2015-2025)
   - Records: 18.4 million timestamped observations
   - Coverage: Pacific, Atlantic, Gulf of Mexico, Hawaii
   - Variables: Wave height, period, direction, wind, SST, pressure

---

## How to Use

### Installation

```bash
pip install torch numpy
```

### Basic Inference

```python
import torch
from model import CoastalDynamicsModel

# Load model
model = CoastalDynamicsModel(embed_dim=128, dropout=0.1)
checkpoint = torch.load('pytorch_model.pt', map_location='cpu')
model.load_state_dict(checkpoint['model_state_dict'])
model.eval()

# Prepare input (B, 8, H, W)
inputs = torch.randn(1, 8, 128, 128)

# Forward pass
with torch.no_grad():
    outputs = model(inputs, return_uncertainty=True, return_extreme_probs=True)

# Access outputs
wave_height = outputs['mean'][:, 0]      # Significant wave height
uncertainty = outputs['std'][:, 0]        # Prediction uncertainty
extreme_probs = outputs['extreme_probs']  # P(wave > 2m, 4m, 6m, 8m)
```

### Uncertainty Quantification

```python
# Monte Carlo Dropout + Diffusion ensemble
results = model.predict_with_uncertainty(
    inputs, 
    num_mc_samples=20,      # Epistemic uncertainty
    num_diffusion_samples=10 # Aleatoric uncertainty
)

print(f"Mean prediction: {results['mean'].shape}")
print(f"MC uncertainty: {results['mc_std'].shape}")
print(f"Diffusion uncertainty: {results['diffusion_std'].shape}")
print(f"Extreme event probs: {results['extreme_probs'].shape}")
```

---

## Performance

| Metric | Value | Description |
|--------|-------|-------------|
| Charbonnier Loss | 0.035 | Robust L1-like loss |
| Physics Loss | 0.067 | Physical consistency |
| NLL (Diffusion) | -3.5 | Log-likelihood |
| Energy Conservation | 0.000 | Perfect conservation |
| Best Total Loss | -1.01 | Combined metric |

---

## Limitations

1. Spatial Resolution: Optimized for 128x128 grids
2. Temporal Resolution: Best for 6-hourly predictions
3. Geographic Bias: Training data primarily from US coastal waters
4. Extreme Events: Rare events (>99th percentile) have inherent prediction challenges
5. Bathymetry Dependency: Requires accurate bathymetric input

---

## Environmental Impact

| Metric | Value |
|--------|-------|
| Training Hardware | 8x NVIDIA H100 GPUs |
| Training Time | ~4 hours |
| Estimated CO2 | ~15 kg CO2eq |
| Cloud Provider | Google Cloud (renewable mix) |

---

## Citation

```bibtex
@misc{naturecode_coastal_dynamics_2026,
  title={Naturecode Coastal Dynamics: Physics-Informed Deep Learning for Ocean Wave Prediction},
  author={Naturecode Team},
  year={2026},
  version={1.0},
  publisher={Hugging Face},
  url={https://huggingface.co/hilarl/naturecode-coastal-dynamics}
}
```

---

## License

This model is released under the Apache 2.0 License.

---

## Acknowledgments

This model builds upon research from:

- FuXi-Ocean (NeurIPS 2025)
- OmniCast (NeurIPS 2025) 
- OceanCastNet
- XWaveNet
- Earthformer (NeurIPS 2022)
- Mamba Neural Operator (J. Comp Physics 2025)
- NOAA National Data Buoy Center

---

## Contact

For questions, collaborations, or access requests:

- Organization: Naturecode

---

Built by Naturecode - Advancing coastal science through AI