Add files using upload-large-folder tool

README.md

@@ -8,54 +8,60 @@ tags:
 - egms
 ---
 
-# EGMS-QA · Encoder
+# EGMS-QA Encoder
 
-Frozen spatio-temporal encoder checkpoint for **EGMS-QA**, a natural-language
-question-answering system over
-[European Ground Motion Service](https://egms.land.copernicus.eu/) (EGMS)
-persistent-scatterer displacement time series.
+Frozen spatio-temporal encoder checkpoint for EGMS-QA, a natural-language
+question-answering system over European Ground Motion Service persistent-
+scatterer displacement time series.
 
-The encoder maps a variable-size 7 km tile of point displacement histories to a
-fixed **65-token** representation (1 tile summary + 8×8 spatial cells, 256-d),
-trained self-supervised with masked reconstruction. It is frozen downstream.
+The encoder maps a variable-size 7 km tile to 65 tokens: one tile-summary token
+plus 64 spatial-cell tokens on an 8×8 grid, each with dimension 256. It was
+trained by synchronized-block masked reconstruction and remains frozen during
+translator training.
 
-Code: [`src/egms_encoder`](https://github.com/risenyard/egms-qa/tree/main/src/egms_encoder) ·
-Companion repos: [`risenyard/egms-qa-dataset`](https://huggingface.co/datasets/risenyard/egms-qa-dataset) ·
-[`risenyard/egms-qa-translator`](https://huggingface.co/risenyard/egms-qa-translator)
+Code: [`risenyard/egms-qa`](https://github.com/risenyard/egms-qa/tree/main/src/egms_encoder) ·
+Dataset: [`risenyard/egms-qa-dataset`](https://huggingface.co/datasets/risenyard/egms-qa-dataset) ·
+Translators: [`risenyard/egms-qa-translator`](https://huggingface.co/risenyard/egms-qa-translator)
 
 ## Files
 
-| file | what it is |
+| file | contents |
 |---|---|
-| `encoder.pt` | frozen encoder checkpoint (`model` state dict + training args) |
-| `normalization.json` | mean / std / residual-std used to normalize the input series |
-| `args.json` | training configuration that produced the checkpoint |
+| `encoder.pt` | model state dictionary and embedded training arguments |
+| `normalization.json` | input mean, standard deviation, and residual statistics |
+| `args.json` | normalized public training and architecture configuration |
 
-The precomputed **token cache** and the **processed source tiles** live in the dataset repo
-[`risenyard/egms-qa-dataset`](https://huggingface.co/datasets/risenyard/egms-qa-dataset)
-(`artifacts/representations/`, `artifacts/source_tiles/`). The dataset release
-installer links those publication paths to `data/encoder/tokens/` and
-`data/tiles/`; the split manifest is in the code repo under
-`data/encoder/manifest/`.
-
-## Use
-
-Download the flat files into the checkout path the code expects, then load with
-the `egms_encoder` model code from the GitHub repo and re-extract tokens:
+## Use with the structured dataset release
 
 ```bash
-hf download risenyard/egms-qa-encoder --local-dir data/encoder/checkpoint
+git clone https://github.com/risenyard/egms-qa
+cd egms-qa
+pip install -e .
+
+hf download risenyard/egms-qa-encoder \
+    --local-dir data/encoder/checkpoint
 hf download risenyard/egms-qa-dataset \
     --repo-type dataset --local-dir release/egms-qa-dataset
 python -m egms_qa.release install \
     --release-dir release/egms-qa-dataset --target-root .
 
-python -m egms_encoder.extract_tokens \
-    --checkpoint data/encoder/checkpoint/encoder.pt \
-    --manifest   data/encoder/manifest/split.parquet \
-    --output-dir outputs/tokens
+python -m egms_encoder.extract_tokens --output-dir outputs/tokens
 ```
 
-`normalization.json` and `args.json` sit next to `encoder.pt`, so the checkpoint
-is self-contained. Most users can skip extraction and use the released token
-cache from the dataset repo. Licensed CC-BY-4.0.
+Most translator users can use the released token cache under
+`artifacts/representations/` in the dataset repository and skip encoder
+execution entirely.
+
+## Data and scope
+
+The model consumes the `[8,302)` slice of each processed 304-step source tile,
+giving 294 input steps. Coordinates are centred per tile and divided by the
+3,500 m half-width before coordinate embedding.
+
+The encoder represents observed deformation histories; it does not determine
+cause, forecast motion, certify structural safety, or replace expert InSAR and
+geotechnical assessment.
+
+The checkpoint is CC-BY-4.0. Copernicus-derived source measurements are
+distributed separately in `risenyard/egms-qa-dataset` under the CLMS data
+policy and attribution conditions documented there.

args.json

@@ -1,53 +1,64 @@
 {
-  "checkpoint_every_steps": 5000,
-  "coord_scale": 3500.0,
-  "d_model": 256,
-  "device": "cuda:0",
-  "dropout": 0.1,
-  "duration_hours": null,
-  "eval_mask_ratio": 0.3,
-  "init_from_checkpoint": null,
-  "input_length": 294,
-  "log_every_steps": 200,
-  "lr": 0.0004,
-  "lr_scheduler": "cosine",
-  "mask_ratio": 0.3,
-  "mask_schedule": "fixed",
-  "mask_strategy": "block",
-  "max_steps": 150000,
-  "max_tile_points": 4096,
-  "min_lr": 3e-05,
-  "min_tile_points": 200,
-  "model_version": "v3_3",
-  "num_heads": 8,
-  "num_layers": 6,
-  "output_dir": "outputs/encoder_pretrain",
-  "patch_size": 8,
-  "point_sampling": "residual_weighted",
-  "precision": "bf16",
-  "residual_consistency_weight": 0.1,
-  "residual_head_lr": 0.0001,
-  "residual_head_mode": "additive",
-  "residual_loss_weight": 1.0,
-  "residual_sampling_alpha": 0.75,
-  "resume_from": null,
-  "scheduler_total_steps": 150000,
-  "seed": 42,
-  "split_strategy": "random",
-  "stratify_bins": 3,
-  "sync_mask": true,
-  "temporal_heads": 4,
-  "temporal_layers": 2,
-  "test_fraction": 0.1,
-  "tile_size": 7000.0,
-  "tiles_per_batch": 8,
-  "train_window_steps": 1000,
-  "v4_config": "data/processed/v4/v4_data_config.json",
-  "v4_normalization": "data/processed/v4/v4_normalization.json",
-  "val_batches": 16,
-  "val_every_steps": 1000,
-  "val_fraction": 0.1,
-  "val_seed": 1729,
-  "warmup_steps": 1000,
-  "weight_decay": 0.01
-}
+  "schema_version": "egms-qa-encoder-training-config-1.0",
+  "release_name": "egms-qa-encoder",
+  "architecture": {
+    "class": "egms_encoder.models.tile_encoder.TileEncoder",
+    "input_length": 294,
+    "patch_size": 8,
+    "d_model": 256,
+    "temporal_layers": 2,
+    "temporal_heads": 4,
+    "spatial_layers": 6,
+    "spatial_heads": 8,
+    "dropout": 0.1,
+    "coord_scale_m": 3500.0,
+    "residual_head_mode": "additive"
+  },
+  "data": {
+    "manifest": "data/encoder/manifest/split.parquet",
+    "data_config": "data/encoder/manifest/data_config.json",
+    "normalization": "data/encoder/checkpoint/normalization.json",
+    "tile_size_m": 7000.0,
+    "minimum_points_per_tile": 200,
+    "maximum_points_per_tile": 4096,
+    "split_seed": 1729
+  },
+  "masking": {
+    "strategy": "synchronized_block",
+    "train_ratio": 0.3,
+    "evaluation_ratio": 0.3,
+    "schedule": "fixed"
+  },
+  "point_sampling": {
+    "method": "residual_weighted",
+    "residual_sampling_alpha": 0.75
+  },
+  "loss": {
+    "residual_loss_weight": 1.0,
+    "residual_consistency_weight": 0.1
+  },
+  "optimization": {
+    "optimizer": "AdamW",
+    "maximum_steps": 150000,
+    "tiles_per_batch": 8,
+    "learning_rate": 0.0004,
+    "minimum_learning_rate": 0.00003,
+    "residual_head_learning_rate": 0.0001,
+    "scheduler": "cosine",
+    "scheduler_total_steps": 150000,
+    "warmup_steps": 1000,
+    "weight_decay": 0.01,
+    "precision": "bf16",
+    "seed": 42
+  },
+  "validation": {
+    "batches": 16,
+    "interval_steps": 1000,
+    "seed": 1729
+  },
+  "checkpointing": {
+    "interval_steps": 5000,
+    "log_interval_steps": 200,
+    "rolling_window_steps": 1000
+  }
+}