Update README.md

README.md

@@ -1,3 +1,163 @@
----
-license: mit
----
+---
+tags:
+- fourier-neural-operator
+- seismic
+- structural-engineering
+- time-series
+- regression
+- pytorch
+library_name: pytorch
+pipeline_tag: other
+---
+
+# SeFNO — Seismic Floor Acceleration Response Prediction (FNO v1.0+)
+
+Pre-trained **Fourier Neural Operator (FNO)** models for predicting multi-floor acceleration response time histories of MDOF shear buildings subjected to seismic ground motions.
+
+**Code:** [github.com/HKUJasonJiang/Seismic-FNO](https://github.com/HKUJasonJiang/Seismic-FNO)  
+**Dataset:** [<!-- TODO: HuggingFace dataset link -->]
+
+---
+
+## Task
+
+Given a scaled ground motion acceleration time series (3 000 time steps, 50 Hz), the model predicts the roof-floor acceleration response of a target building — a pure **regression** task over 1-D signals.
+
+| Input | Shape | Description |
+|-------|-------|-------------|
+| Ground motion | `(1, 3000)` | Scaled accelerogram (m/s²) |
+
+| Output | Shape | Description |
+|--------|-------|-------------|
+| Floor acceleration | `(1, 3000)` | Roof acceleration response (m/s²) |
+
+---
+
+## Available Models
+
+### Baseline Models
+
+Three FNO configurations trained for 50 epochs on the full KNET dataset (3 474 GMs × 57 amplitude scale factors, 250 building configurations):
+
+| Folder | Hidden (`h`) | Modes (`m`) | Layers (`l`) | Parameters |
+|--------|:-----------:|:-----------:|:------------:|:----------:|
+| `Base-FNO_v1.0+_h64_m64_l4_e50_*/` | 64 | 64 | 4 | ~3 M |
+| `Large-FNO_v1.0+_h64_m512_l8_e50_*/` | 64 | 512 | 8 | ~12 M |
+| `Huge-FNO_v1.0+_h128_m1024_l12_e50_*/` | 128 | 1024 | 12 | ~48 M |
+
+### Experimental Series
+
+| Folder | Runs | Purpose |
+|--------|:----:|---------|
+| `Test-Series (Test-1~10)/` | 10 | Hyper-parameter sweep (modes, layers, hidden channels) |
+| `Efficiency-Series (E-Base, E-Test-1~15)/` | 16 | Dataset-size ablation (varying number of GMs and scale factors) |
+
+Each model folder contains:
+```
+<model_folder>/
+├── model/
+│   └── fno_best.pth          # Best checkpoint (lowest validation loss)
+└── details/
+    ├── training_log.csv       # Epoch-by-epoch MSE / RMSE / MAE / R²
+    ├── training_config.txt    # Full hyperparameter configuration
+    ├── dataset_indices.pkl    # Reproducible train / val / test split indices
+    └── test_results.txt       # Final test-set metrics
+```
+
+---
+
+## Usage
+
+### Install dependencies
+
+```bash
+git clone https://github.com/HKUJasonJiang/Seismic-FNO.git
+cd Seismic-FNO
+pip install -r requirement.txt   # Windows
+# pip install -r requirement_linux.txt  # Linux
+```
+
+### Load a checkpoint and run inference
+
+```python
+import torch
+from neuralop.models import FNO
+
+def load_fno(checkpoint_path, n_modes, hidden_channels, n_layers, device="cuda"):
+    model = FNO(
+        n_modes                  = (n_modes,),
+        hidden_channels          = hidden_channels,
+        in_channels              = 1,
+        out_channels             = 1,
+        n_layers                 = n_layers,
+        projection_channel_ratio = 2,
+        domain_padding           = 0.1,
+    )
+    ckpt  = torch.load(checkpoint_path, map_location=device, weights_only=False)
+    state = ckpt.get("model_state_dict", ckpt)
+    # strip torch.compile prefix if present
+    state = {(k[10:] if k.startswith("_orig_mod.") else k): v for k, v in state.items()}
+    model.load_state_dict(state)
+    return model.to(device).eval()
+
+
+device = "cuda" if torch.cuda.is_available() else "cpu"
+
+# --- Base model ---
+model = load_fno(
+    checkpoint_path = "output/Base-FNO_v1.0+_h64_m64_l4_e50_.../model/fno_best.pth",
+    n_modes         = 64,
+    hidden_channels = 64,
+    n_layers        = 4,
+    device          = device,
+)
+
+# --- Inference on a single ground motion ---
+import numpy as np
+
+gm_array = np.load("my_ground_motion.npy")   # shape (3000,), unit m/s²
+x = torch.from_numpy(gm_array).float().unsqueeze(0).unsqueeze(0).to(device)  # (1,1,3000)
+
+with torch.no_grad():
+    pred = model(x).cpu().numpy().squeeze()   # shape (3000,)
+
+print("Predicted roof acceleration shape:", pred.shape)
+```
+
+### Quick review notebook
+
+Open `quick_inference.ipynb` in the cloned repository to run inference on the held-out test set and visualise time-history and Fourier amplitude spectrum comparisons interactively.
+
+---
+
+## Training Details
+
+| Property | Value |
+|----------|-------|
+| Framework | PyTorch ≥ 2.0 + [neuralop](https://github.com/neuraloperator/neuraloperator) |
+| Loss | MSE |
+| Optimizer | AdamW |
+| LR schedule | StepLR (step=20, γ=0.5) |
+| Batch size | 2 560 |
+| Epochs | 50 (baseline models) |
+| Train / Val / Test split | 70 % / 20 % / 10 % (grouped by GM to prevent leakage) |
+| Dataset | KNET — 3 474 GMs × 57 amplitude scale factors × 250 buildings |
+
+---
+
+## Citation
+
+If you use these models, please cite (forthcoming):
+
+```
+@misc{jiang2025sefno,
+  title  = {SeismicFNO: Fourier Neural Operators for Seismic Structural Response Prediction},
+  author = {Jason Jiang},
+  year   = {2025},
+  url    = {https://github.com/HKUJasonJiang/Seismic-FNO}
+}
+```
+
+## License
+
+[Creative Commons Attribution 4.0 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/)