Upload README.md with huggingface_hub

README.md

@@ -1,102 +1,121 @@
 ---
-license: apache-2.0
+language: en
 tags:
   - time-series
   - forecasting
   - chronos
   - patch-aliasing
-language:
-  - en
+  - t5
+license: apache-2.0
 ---
 
-# Chronos-Bolt Patch Sweep
+# Chronos-Bolt Patch Sweep — Studio sull'Aliasing Strutturale
 
-A collection of **Chronos-Bolt Tiny** models retrained **from scratch** (random weights) on the official [Chronos pre-training corpus](https://huggingface.co/datasets/autogluon/chronos_datasets) (TSMixup 10M + KernelSynth 1M), varying only the **patch geometry** (input_patch_size `P` and input_patch_stride `S`).
+Collezione di modelli **Chronos-Bolt Tiny** (~8.65M parametri) riallenati da zero con diverse geometrie di patch (P, S) per studiare l'aliasing strutturale introdotto dall'embedding a patch nei transformer per serie temporali.
 
-The goal is to study **structural aliasing** in patched time-series transformers: how the choice of patch size and stride affects the model's ability to represent different frequency components.
+## Risultati principali
 
-## Models
+L'embedding a patch proietta P campioni consecutivi in un singolo token. Quando un'oscillazione completa esattamente un intero numero di cicli nella finestra di P campioni (`cpp = freq × P / fs = intero`), la proiezione lineare cancella l'oscillazione. Questo produce **nulli nella risposta in frequenza** a posizioni prevedibili: `f_null = k × fs / P`.
 
-| Subfolder | P | S | Overlap Ratio | Approx Patches | Params | Final Loss | Speed (it/s) |
-|-----------|---|---|---------------|-----------------|--------|------------|--------------|
-| `p16-s16-seed42` | 16 | 16 | 0.00 (contiguous) | 128 | 8.65M | 36.09 | 4.94 |
-| `p16-s12-seed42` | 16 | 12 | 0.25 | 170 | 8.65M | 35.34 | 6.78 |
-| `p16-s8-seed42` | 16 | 8 | 0.50 | 255 | 8.65M | 36.97 | 3.80 |
-| `p16-s4-seed42` | 16 | 4 | 0.75 | 509 | 8.65M | 36.70 | 3.58 |
-| `p8-s8-seed42` | 8 | 8 | 0.00 (contiguous) | 256 | 8.63M | 37.62 | 7.03 |
-| `p24-s24-seed42` | 24 | 24 | 0.00 (contiguous) | 86 | 8.67M | 34.90 | 4.50 |
+| Ipotesi | Esito |
+|---------|-------|
+| La larghezza P della patch determina la posizione dei nulli | **Confermata** — nulli a k×fs/P |
+| I nulli cadono a cpp intero indipendentemente da P | **Confermata** — P=8, P=16, P=24 collassano tutti a cpp intero |
+| L'overlap (stride ridotto) mitiga il nullo | **Rigettata** — S=4 collassa quanto S=16 |
+| La banda utile del forecaster è fs/P | **Confermata** — recovery crolla sopra questa soglia |
 
-### Experimental design
+## Modelli
 
-- **Overlap axis** (fixed P=16, varying S): `S=16` (no overlap) → `S=12` (25%) → `S=8` (50%) → `S=4` (75%). Tests whether overlapping patches reduce aliasing artifacts.
-- **Patch-size axis** (contiguous, S=P): `P=8` → `P=16` → `P=24`. Tests how the patch size itself (the effective sampling window) affects frequency representation.
+| Cartella | P | S | Overlap | Step | Stato | Ruolo |
+|----------|---|---|---------|------|-------|-------|
+| `p16-s12-seed42` | 16 | 12 | 25% | 100k | done | Asse stride |
+| `p16-s8-seed42` | 16 | 8 | 50% | 100k | done | Asse stride |
+| `p16-s4-seed42` | 16 | 4 | 75% | 100k | done | Asse stride |
+| `p8-s8-seed42` | 8 | 8 | 0% | 100k | done | Asse patch-size |
+| `p24-s24-seed42` | 24 | 24 | 0% | 100k | done | Asse patch-size |
+| `p16-s16-seed42` | 16 | 16 | 0% | 10k | **stale** | Sostituito dall'ufficiale |
 
-All other hyperparameters are fixed at the official Chronos-Bolt Tiny values so any downstream difference is attributable to P/S alone.
+> **Nota su p16-s16.** Il retrain p16-s16-seed42 si è fermato a ~33k step e i pesi su HF sono quelli vecchi a 10k. Per il confronto P=16 S=16 usiamo direttamente il modello ufficiale [`amazon/chronos-bolt-tiny`](https://huggingface.co/amazon/chronos-bolt-tiny) (200k step, corpus completo, stessa geometria P=16 S=16). È il miglior anchor possibile per l'asse stride.
 
-## Training details
+## Training
 
-- **Base architecture**: [amazon/chronos-bolt-tiny](https://huggingface.co/amazon/chronos-bolt-tiny) (T5-based, ~8.65M params)
-- **Weights**: trained from scratch (random init), NOT fine-tuned from the official checkpoint
-- **Dataset**: `autogluon/chronos_datasets` — TSMixup 10M + KernelSynth 1M (official Chronos corpus)
-- **Steps**: 10,000 (vs official 200k — reduced compute budget; all models compared only against each other)
-- **Batch size**: 32
-- **Optimizer**: AdamW (fused), LR=1e-3, linear decay, no warmup
-- **Precision**: fp32 + TF32 matmuls on NVIDIA RTX 5060 Laptop GPU
-- **Context length**: 2048 tokens
-- **Prediction length**: 64 steps
-- **Quantiles**: 9 (0.1 to 0.9)
+- **Architettura:** T5-based (Chronos-Bolt Tiny), ~8.65M parametri
+- **Dataset:** [autogluon/chronos_datasets](https://huggingface.co/datasets/autogluon/chronos_datasets) — TSMixup 10M + KernelSynth 1M, interleaving 9:1
+- **Step:** 100,000 (streaming da HF, shuffle buffer 10k)
+- **Ottimizzatore:** AdamW fused, LR 1e-3 → 0 (linear decay), no warmup
+- **Batch size:** 32, gradient clipping 1.0
+- **Precisione:** fp32 + TF32 (RTX 5060 Laptop, sm_120)
+- **Context/Prediction:** 2048 / 64
 
-## Usage
+Ogni modello è allenato con lo stesso seed (42), stesso dataset, stessi iperparametri. L'unica variabile è la geometria della patch (P, S).
+
+## Come usare
 
 ```python
 from chronos import ChronosBoltPipeline
 import torch
 
-# Load any single model
-pipeline = ChronosBoltPipeline.from_pretrained(
+# Caricare un singolo modello retrained
+pipe = ChronosBoltPipeline.from_pretrained(
     "federicosabbadini/chronos-bolt-patch-sweep",
-    subfolder="p16-s16-seed42",
+    subfolder="p8-s8-seed42",
     device_map="cuda",
     torch_dtype=torch.float32,
 )
 
+# Caricare il modello ufficiale come reference P=16 S=16
+official = ChronosBoltPipeline.from_pretrained(
+    "amazon/chronos-bolt-tiny",
+    device_map="cuda",
+)
+
 # Forecast
-context = torch.tensor([...])  # your time series as a 1D tensor
-forecast = pipeline.predict(context, prediction_length=64)
-# forecast shape: (1, num_samples, 64)
+import numpy as np
+context = torch.tensor(np.random.randn(512), dtype=torch.float32)
+forecast = pipe.predict(context, prediction_length=64)  # [1, 9, 64] — 9 quantili
+median = forecast[0, 4, :]  # quantile 0.5
 ```
 
-### Load all models for comparison
+### Caricare tutti i modelli per confronto
 
 ```python
-from chronos import ChronosBoltPipeline
-import torch
-
 REPO = "federicosabbadini/chronos-bolt-patch-sweep"
-MODEL_NAMES = [
-    "p16-s16-seed42", "p16-s12-seed42", "p16-s8-seed42",
-    "p16-s4-seed42", "p8-s8-seed42", "p24-s24-seed42",
-]
+VARIANTS = ["p16-s12-seed42", "p16-s8-seed42", "p16-s4-seed42",
+            "p8-s8-seed42", "p24-s24-seed42"]
 
 models = {}
-for name in MODEL_NAMES:
+for name in VARIANTS:
     models[name] = ChronosBoltPipeline.from_pretrained(
-        REPO, subfolder=name,
-        device_map="cuda", torch_dtype=torch.float32,
+        REPO, subfolder=name, device_map="cuda", torch_dtype=torch.float32
     )
+
+# Aggiungere l'ufficiale come p16-s16
+models["p16-s16 (official)"] = ChronosBoltPipeline.from_pretrained(
+    "amazon/chronos-bolt-tiny", device_map="cuda"
+)
 ```
 
-## Files per model
+## Struttura del repository
+
+```
+├── manifest.csv                    # tabella riassuntiva di tutti i run
+├── p16-s12-seed42/
+│   ├── config.json                 # config del modello (include P, S)
+│   ├── model.safetensors           # pesi finali (100k step)
+│   ├── run_config.json             # iperparametri del training
+│   ├── loss_history.npy            # curva di loss
+│   └── loss_curve.png              # plot della loss
+├── p16-s8-seed42/                  # stessa struttura
+├── p16-s4-seed42/
+├── p8-s8-seed42/
+├── p24-s24-seed42/
+└── p16-s16-seed42/                 # ⚠️ stale — pesi a 10k, non usare
+```
 
-Each subfolder contains:
-- `config.json` — HuggingFace model config (includes `chronos_config` with P, S values)
-- `model.safetensors` — trained weights (~33 MB)
-- `run_config.json` — full provenance + training result metadata
-- `loss_history.npy` — per-step training loss array (10,000 values)
-- `loss_curve.png` — training loss plot
+## Codice sorgente
 
-The root `manifest.csv` summarizes all finished runs.
+Il codice di training, valutazione e analisi è nel repository GitHub: i script di sweep frequenziale, il notebook inspector, e i generatori di segnali sintetici con injection controllata.
 
-## Citation
+## Licenza
 
-This work is part of a research project on patch aliasing in time-series transformers. The base model architecture and training pipeline are adapted from [Chronos](https://github.com/amazon-science/chronos-forecasting) (Apache-2.0).
+Apache 2.0 — stesso della famiglia Chronos.