Upload README.md with huggingface_hub

README.md

@@ -1,121 +1,65 @@
----
-language: en
-tags:
-  - time-series
-  - forecasting
-  - chronos
-  - patch-aliasing
-  - t5
-license: apache-2.0
----
+# Chronos-Bolt Patch-Stride Sweep
 
-# Chronos-Bolt Patch Sweep — Studio sull'Aliasing Strutturale
+Retrained variants of [Chronos-Bolt Tiny](https://huggingface.co/amazon/chronos-bolt-tiny) (~8.7M params) with different **patch size (P)** and **patch stride (S)** configurations, trained from scratch on the full official Chronos pre-training data.
 
-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.
+## Purpose
 
-## Risultati principali
+These models support the **structural patch-aliasing** study: investigating how the (P, S) patch geometry of Chronos-Bolt creates frequency-dependent artifacts in time-series forecasting. Each model is trained identically except for the patch geometry, so any downstream difference in aliasing probes is attributable to (P, S).
 
-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`.
+## Models
 
-| 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 |
+| Subfolder | P | S | Overlap | Status |
+|---|---|---|---|---|
+| `p8-s8-seed42` | 8 | 8 | 0.000 | done |
+| `p16-s4-seed42` | 16 | 4 | 0.750 | done |
+| `p16-s8-seed42` | 16 | 8 | 0.500 | done |
+| `p16-s12-seed42` | 16 | 12 | 0.250 | done |
+| `p16-s16-seed42` | 16 | 16 | 0.000 | done |
+| `p24-s8-seed42` | 24 | 8 | 0.667 | done |
+| `p24-s12-seed42` | 24 | 12 | 0.500 | done |
+| `p24-s16-seed42` | 24 | 16 | 0.333 | done |
+| `p24-s20-seed42` | 24 | 20 | 0.167 | done |
+| `p24-s24-seed42` | 24 | 24 | 0.000 | done |
+| `p32-s32-seed42` | 32 | 32 | 0.000 | done |
 
-## Modelli
+More models (P=32 stride series + odd-stride S=15 variants) are in training and will be uploaded as they complete.
 
-| 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 |
+## Training setup
 
-> **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.
+All models share the same training regime (only P and S vary):
 
-## Training
+- **Architecture**: Chronos-Bolt Tiny (T5-based, ~8.7M params), random initialization
+- **Data**: Official Chronos pre-training corpus — TSMixup (10M series) + KernelSynth (1M series) at 9:1 ratio
+- **Steps**: 100,000 (fixed budget across all runs)
+- **Optimizer**: AdamW, lr=1e-3, linear decay, no warmup
+- **Batch size**: 32
+- **Precision**: fp32 + TF32 matmuls (Ampere+ GPUs)
+- **Context**: 2048 tokens, prediction horizon: 64
+- **Quantiles**: 9 (0.1 to 0.9)
+- **Seed**: 42
 
-- **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
+Full provenance is recorded in each subfolder's `run_config.json`.
 
-Ogni modello è allenato con lo stesso seed (42), stesso dataset, stessi iperparametri. L'unica variabile è la geometria della patch (P, S).
-
-## Come usare
+## Usage
 
 ```python
-from chronos import ChronosBoltPipeline
-import torch
+from chronos import BaseChronosPipeline
 
-# Caricare un singolo modello retrained
-pipe = ChronosBoltPipeline.from_pretrained(
+pipe = BaseChronosPipeline.from_pretrained(
     "federicosabbadini/chronos-bolt-patch-sweep",
-    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",
+    subfolder="p24-s16-seed42",
+    device_map="cpu",
 )
-
-# Forecast
-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
-```
-
-### Caricare tutti i modelli per confronto
-
-```python
-REPO = "federicosabbadini/chronos-bolt-patch-sweep"
-VARIANTS = ["p16-s12-seed42", "p16-s8-seed42", "p16-s4-seed42",
-            "p8-s8-seed42", "p24-s24-seed42"]
-
-models = {}
-for name in VARIANTS:
-    models[name] = ChronosBoltPipeline.from_pretrained(
-        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"
-)
-```
-
-## 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
 ```
 
-## Codice sorgente
+## Files per model
 
-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.
+- `config.json` — model architecture config
+- `model.safetensors` — trained weights (~34 MB)
+- `run_config.json` — full training provenance + result metrics
+- `loss_history.npy` — per-step training loss
+- `loss_curve.png` — training loss plot
 
-## Licenza
+## License
 
-Apache 2.0 — stesso della famiglia Chronos.
+The models are derived from the Chronos architecture (Apache-2.0) and trained on the official Chronos datasets. See the original [Chronos repository](https://github.com/amazon-science/chronos-forecasting) for details.