# Kernodeck Wznowienie v1 — checkpoint, który jest naprawdę wznawiany

To oryginalne ćwiczenie uczy małej zależności numerycznej na 24 syntetycznych wierszach. Jego celem jest **zweryfikowanie wznowienia treningu**, a nie uzyskanie najlepszego modelu czy zmierzenie GPU. Obliczenia są jawnie wymuszone na **CPU**, w `float64`, z jednym wątkiem PyTorch.

Kontrola porównuje 10 ciągłych kroków z 5 krokami, checkpointem, a następnie 5 nowymi krokami w **innym procesie Pythona**. Czwarty proces celowo pomija przywracanie generatorów losowych: jego dryf musi zostać wykryty. Żadne zdalne zasoby, dane klienta ani wstępnie wytrenowane wagi nie są pobierane.

## Wymagania wstępne

- Środowisko Python z już zainstalowanymi PyTorch i NumPy. Dostarczony dowód został wykonany z **Python 3.14.6, PyTorch 2.11.0+cu128 i NumPy 2.4.4**.
- Około 1 MB dostępnego miejsca na cztery małe foldery wyjściowe. Zależności Pythona zajmują własną przestrzeń.
- Uruchamiaj polecenia z rozpakowanego folderu `kernodeck-reprise-v1`.

Sufiks `+cu128` opisuje pakiet obecny podczas testu; nie oznacza, że to ćwiczenie używało CUDA. **Żadne obliczenia CUDA, ROCm, AMP, wielokartowe ani rozproszone nie są walidowane przez ten zasób.** Nie używa on workerów DataLoader. Inne środowisko musi wytworzyć własny dowód; równość nie jest gwarantowana między wersjami ani platformami.

## Polecenie weryfikacyjne

```console
python -B verify_resume.py --output runs/preuve-cpu
```

`-B` zapobiega tworzeniu pamięci podręcznej bajtkodu w folderze projektu. Katalog wyjściowy musi być nowy: żadne istniejące uruchomienie nie jest nadpisywane. Aby zacząć od nowa, użyj na przykład `runs/preuve-cpu-2`.

Program wykonuje cztery polecenia tym samym interpreterem Pythona, a następnie zapisuje `runs/preuve-cpu/verification.json`. Pełne uruchomienie oczekuje:

```json
{"device":"cpu","all_checks_passed":true,"positive":true,"negative_divergence_detected":true,"report":"verification.json"}
```

Kod wyjścia wynosi **0**, jeśli protokół się powiedzie, **1**, jeśli porównanie zawiedzie, **2**, jeśli weryfikacji nie udało się ukończyć. Sukces wymaga jednocześnie pozytywnego wznowienia i obserwowalnego niepowodzenia kontroli negatywnej. Sam plik checkpointu obecny na dysku nie wystarcza.

## Wykonanie trzech kroków ręcznie

```console
python -B train.py --steps 10 --output runs/continu
python -B train.py --steps 5 --output runs/coupure
python -B train.py --steps 5 --resume runs/coupure/checkpoint.pt --output runs/reprise
```

Każda linia uruchamia osobny proces. `--steps` oznacza **dodatkowe kroki**, więc trzecie polecenie kończy się na kroku 10. Każdy folder zawiera `checkpoint.pt`, jego skrót `checkpoint.pt.sha256` oraz czytelne podsumowanie `summary.json`. Checkpointy są tworzone przez ćwiczenie podczas uruchomienia; nie są dystrybuowane w archiwum.

Aby zaobserwować przypadek niekompletny, użyj nowego folderu:

```console
python -B train.py --steps 5 --resume runs/coupure/checkpoint.pt --omit-rng-restore --output runs/reprise-incomplete
```

To ostatnie polecenie może zakończyć się bez błędu Pythona. **Nie dowodzi to poprawnego wznowienia.** Polecenie `verify_resume.py` porównuje wyniki i stwierdza różnicę.

## Co model faktycznie robi

`data.csv` zawiera siatkę dwóch zmiennych i syntetyczny cel: `target = 0.7*x1 - 0.4*x2 + 0.15*x1*x2 + 0.1`. Nie imituje żadnego pomiaru klienta. Sieć ma dwa wejścia, warstwę ośmiu neuronów, `Tanh`, dropout 0,25 i wyjście, czyli 33 parametry.

Trening używa Adam z początkowym współczynnikiem 0,03. StepLR dzieli ten współczynnik przez dwa co trzy kroki. Każdy batch zawiera cztery wiersze: 10 kroków zużywa więc 40 obserwacji, przechodząc ponownie przez niektóre wiersze po pierwszej epoce. Permutacja, epoka, kursor i liczba zużytych obserwacji są zachowywane. Przy cięciu po pięciu krokach kursor wynosi 20 z 24: wznowienie następuje **w środku przebiegu po danych**.

Trzy źródła losowości wpływają na pracę: Python ustawia lekkie wzmocnienie na wejściach, generator NumPy PCG64 tworzy szum i permutacje, PyTorch tworzy dropout. Ponowne ustawienie początkowego seeda nie odtwarza stanów osiągniętych przy cięciu.

## Co checkpoint zachowuje i w jakiej kolejności jest odczytywany

Słownik zawiera wagi, stan Adam, stan StepLR, postęp danych, trzy RNG, historię strat i tempa oraz odciski kodu i CSV. Tryb `train()` jest przywracany na potrzeby wznowienia; końcowy pomiar MSE używa `eval()` i nie zużywa dropoutu.

Przy wznowieniu kod najpierw buduje model, optymalizator i **harmonogram**, a następnie ładuje wagi, stan harmonogramu i stan optymalizatora. RNG są przywracane na końcu, po konstrukcjach, które zużywają losowość. Ten wybór jest zgodny z ostrzeżeniem w dokumentacji [Optimizer.load_state_dict](https://docs.pytorch.org/docs/2.11/generated/torch.optim.Optimizer.load_state_dict.html).

Stan Pythona to struktura prymitywów. PCG64 udostępnia słownik liczb całkowitych i łańcuchów znaków; żaden obiekt `ndarray` NumPy nie jest serializowany jako stan RNG. Stan PyTorch CPU to tensor bajtów. Kolejne losowania są kontrolowane bez modyfikowania zapisanego stanu.

## Odczyt dowodu i tolerancja

`verification-cpu.json` to publiczny dowód z rzeczywistego uruchomienia tej wersji. `source` zawiera SHA-256 skryptów i CSV. `protocol` opisuje cztery procesy, precyzję i tolerancję. `resume_boundary` weryfikuje kolejne losowanie każdego RNG i kolejne tempo użyte po przerwaniu.

Porównanie wymaga tej samej kolejności wierszy, tego samego postępu i tego samego stanu harmonogramu. Maksymalna akceptowana różnica bezwzględna dla wag, stanu optymalizatora, strat, MSE i temp wynosi **1e-12**, bez tolerancji względnej (`rtol=0`). Raport zachowuje zmierzone różnice, nawet gdy wynoszą zero. Weryfikuje również kolejne losowanie RNG na końcu obu przebiegów.

Kontrola negatywna musi pokazać, że pominięcie RNG zmienia wynik. Jej MSE może być niższa lub wyższa: ten test weryfikuje trajektorię wznowienia, a nie ranking jakości. Oczekiwana rozbieżność daje więc `passed: false` w tym podteście i `divergence_detected: true`; protokół globalny może wtedy zakończyć się powodzeniem.

## Ładowanie wyłącznie własnego checkpointu

Loader używa jawnie `torch.load(..., map_location="cpu", weights_only=True)` i nie oferuje żadnego fallbacku do `weights_only=False`. Najpierw weryfikuje powiązany odcisk, ogranicza rozmiar i sprawdza schemat, wersje, kod i dane. Odrzuca niekompletny stan zamiast po cichu resetować część treningu.

Używaj wyłącznie checkpointów, które **sam utworzyłeś w ramach tego ćwiczenia i przechowujesz pod własną kontrolą**. Odcisk służy do wykrycia modyfikacji; nie uwierzytelnia nadawcy. Ograniczone ładowanie nie czyni nieznanego pliku godnym zaufania. Zobacz [torch.load](https://docs.pytorch.org/docs/2.11/generated/torch.load.html) i [serializację PyTorch](https://docs.pytorch.org/docs/2.11/notes/serialization.html).

## Dostosowanie ćwiczenia do własnego projektu

Zidentyfikuj stany, które rzeczywiście zużywa Twój własny trening: sampler, augmentacja, optymalizator, harmonogram i konkretne generatory. Jeśli używasz AMP, dodaj stan skalera na spójnej granicy; to ćwiczenie tego nie robi. Trening rozproszony wymaga również obsługi swoich procesów i ich podziału danych.

Nie wyciągaj z tego małego dowodu wniosków o czasie wynajmu, przepustowości, zużyciu VRAM ani gwarancji wznowienia dla innego modelu. Powtórz metodę: krótki reprezentatywny zestaw, przerwanie w połowie pracy, inny proces, jawne porównanie i kontrola negatywna.

## Zawartość i licencje

- `train.py`, `verify_resume.py`, ta dokumentacja i manifest: licencja MIT, zobacz `LICENSE-MIT.txt`.
- `data.csv`: oryginalne dane syntetyczne udostępnione na licencji CC0 1.0, zobacz `DATA-LICENSE-CC0.txt`.
- `verification-cpu.json`: pomiary z tego ćwiczenia, bez danych osobowych, pełne środowisko, ścieżki lokalne, tokeny ani identyfikatory sesji.
- `manifest.json`: dokładna lista dystrybuowanych plików i ich SHA-256. Manifest nie odwołuje się do samego siebie.
- `SOURCES.md`: oficjalne linki i ograniczenia dokumentacyjne.

Zależności PyTorch, NumPy i Python zachowują własne licencje. Nie są redystrybuowane w pliku ZIP.


## Prezentacja Kernodeck i zgodność projektu

Ta ponowna publikacja z 25 września 2026 r. aktualizuje nazwę archiwum, dokumentację i markę. Skrypty `train.py` i `verify_resume.py`, plik CSV oraz `verification-cpu.json` pozostają identyczne z dostawą wykonaną 24 września 2026 r. Pole techniczne `project` zachowuje swój identyfikator dla istniejących czytników raportów. W ramach tej ponownej publikacji nie uruchomiono ponownie żadnych obliczeń ani kontroli CPU/GPU.