# Diagnostic PyTorch Kernodeck — version 1.0.0

Ce script vérifie qu’un petit calcul PyTorch et son gradient s’exécutent sur le périphérique demandé. Il produit un rapport JSON limité à des champs techniques utiles. Par défaut, il exige un GPU ; un contrôle CPU doit être demandé explicitement.

Il ne lance aucun entraînement, ne mesure aucun débit et ne certifie ni une offre commerciale, ni une capacité d’entraînement, ni la stabilité d’une machine sur la durée. Son code original est fourni sous [licence MIT](kernodeck-diagnostic-v1-LICENSE.md).

## Préparer et lancer

Téléchargez [le script](kernodeck-diagnostic-v1.py), puis ouvrez un terminal dans son dossier. Utilisez le Python de votre environnement de travail, avec PyTorch déjà installé. Le script emploie la bibliothèque standard de Python 3.10 ou ultérieur ; les environnements réellement contrôlés sont détaillés plus bas. Aucune installation ou modification de pilote n’est effectuée.

```sh
python kernodeck-diagnostic-v1.py
```

Cette commande sélectionne le premier GPU visible par PyTorch. Elle échoue avec un code de sortie non nul si PyTorch, le backend GPU ou le périphérique utilisable manque. Elle ne se rabat pas sur CPU.

Pour vérifier uniquement le calcul sur CPU :

```sh
python kernodeck-diagnostic-v1.py --device cpu
```

Pour choisir un GPU visible et conserver un rapport dans un nouveau fichier :

```sh
python kernodeck-diagnostic-v1.py --device-index 0 --output diagnostic.json
```

Le chemin de sortie est choisi par vous et n’apparaît pas dans le rapport. Un fichier existant n’est jamais écrasé. Sans `--output`, le script ne crée aucun fichier. Vous pouvez lire le code de sortie avec `$LASTEXITCODE` dans PowerShell ou `echo $?` dans un shell POSIX.

Si l’import de PyTorch demande plus de temps, augmentez le délai, dans la limite prévue :

```sh
python kernodeck-diagnostic-v1.py --timeout 60
```

| Option publique | Valeur et effet |
| --- | --- |
| `--device gpu` | Valeur par défaut ; exige un GPU CUDA ou ROCm utilisable. |
| `--device cpu` | Calcul CPU explicite ; ne vérifie pas la visibilité du pilote GPU. |
| `--device-index N` | Index PyTorch visible, entre 0 et 63 ; défaut 0. Sans effet sur le calcul CPU. |
| `--timeout N` | Délai du sous-processus de calcul, entre 5 et 120 secondes ; défaut 30. |
| `--host-check` | Lecture NVIDIA facultative, limitée à 3 secondes supplémentaires. |
| `--output FICHIER` | Écrit aussi le JSON dans un nouveau fichier UTF-8. |
| `--help` | Affiche l’aide, sans importer PyTorch. |

Le téléchargement ne contient pas PyTorch, CUDA, ROCm ou leurs pilotes. Pour choisir une installation adaptée à votre système, partez du [sélecteur officiel PyTorch](https://docs.pytorch.org/get-started/locally/). Une installation valide sur une autre machine ne prouve pas la compatibilité de votre GPU.

## CUDA, ROCm et contrôle hôte

Le script examine `torch.version.hip` avant `torch.version.cuda`. Un paquet ROCm est identifié comme `rocm`, même si sa valeur CUDA est `null`. PyTorch utilise aussi `torch.cuda` et le nom de périphérique `cuda` sur ROCm : un rapport `execution.device: "cuda:0"` n’implique donc pas à lui seul une carte NVIDIA. Consultez aussi `execution.backend`. [Documentation HIP de PyTorch](https://docs.pytorch.org/docs/2.14/notes/hip.html)

`torch.cuda.is_available()` indique si CUDA est actuellement disponible pour PyTorch. Le script complète cette observation par un calcul, son gradient et une synchronisation du périphérique demandé. Il ne déduit pas qu’un modèle réel tiendra en mémoire. [Disponibilité](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.is_available.html) · [Synchronisation](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.synchronize.html)

Avec `--host-check`, une commande NVIDIA distincte demande seulement la version du pilote et la mémoire totale en MiB. Sa sortie doit respecter un format numérique strict. L’absence de `nvidia-smi`, un délai dépassé ou une sortie inconnue n’annule pas un calcul réussi. Cette lecture ne constitue pas un diagnostic hôte AMD et n’est pas nécessaire au contrôle CPU. Elle peut voir des cartes que le processus PyTorch ne voit pas ; la liste hôte n’est pas appariée aux index PyTorch. [Requêtes sélectives NVIDIA](https://docs.nvidia.com/deploy/nvidia-smi/index.html)

Voor AMD moeten de versies van de GPU, het systeem, het stuurprogramma en de bibliotheken een ondersteunde combinatie vormen. Dit script vervangt niet de [officiële ROCm-compatibiliteitsmatrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## De JSON lezen

De structuur is stabiel voor versie 1:

| Veld | Betekenis |
| --- | --- |
| `schema`, `script_version` | Formaat en versie van het script. |
| `requested_device` | `gpu` of `cpu`; `unspecified` als de argumenten ongeldig zijn of de uitvoering is onderbroken. |
| `status`, `code`, `exit_code`, `message` | Algemeen resultaat, stabiele code, procescode en vaste uitleg. |
| `stage` | Laatste bereikte stap: import, detectie, zichtbaarheid, toewijzing, berekening, gradiënt, synchronisatie, validatie, enz. |
| `runtime` | Numerieke versie van de gebruikte Python en systeemfamilie; geen machine-identificatie. |
| `pytorch` | Gefilterde versie van het pakket, compilatieversies CUDA/HIP, opgegeven backend en GPU-zichtbaarheid wanneer die is opgevraagd. `null` als PyTorch niet kon worden geïmporteerd. |
| `execution` | Werkelijk geselecteerd apparaat, gefilterd GPU-model, door PyTorch gerapporteerd totaal geheugen, type, vorm van de matrices en resultaat van de controles. `null` als de berekening niet is voorbereid. |
| `host_check` | Alleen op verzoek aanwezig: status van het uitlezen van NVIDIA en twee numerieke velden per kaart. |

In CPU-modus kan `pytorch.backend` `cuda` zijn, omdat het het geïnstalleerde pakket beschrijft. `execution.backend` blijft `cpu` en beschrijft de uitgevoerde berekening. De GPU-beschikbaarheid, het aantal GPU's, het model en het GPU-geheugen zijn dan `null`: ze zijn niet gemeten.

De controle vermenigvuldigt twee 2×2-matrices in `float32`, verifieert het product `[[4, 4], [10, 8]]` en vervolgens de gradiënt `[[16, 24], [40, 52]]`. De verwachte som van de kwadraten is `196.0`. Deze kleine gehele getallen maken hier een exacte vergelijking mogelijk; deze eigenschap belooft niet de bit-voor-bit reproduceerbaarheid van om het even welk model. De verificatie gebruikt [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). Het aanmaken van een GPU-context kan meer geheugen verbruiken dan alleen de matrices.

`total_memory_bytes` is een gerapporteerde capaciteit, niet het vrije of bruikbare geheugen voor je toekomstige model. Het script meet niet het maximale geheugen van een training, noch de interconnectie, noch de snelheid, noch multi-GPU.

## Een fout begrijpen

| Uitvoer | JSON-code | Interpretatie en volgende controle |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | De kleine berekening en haar gradiënt zijn correct op het aangegeven apparaat. |
| 2 | `CLI_ARGUMENTS_INVALID` | Lees `--help` opnieuw; de ongeldige waarde wordt niet overgenomen. |
| 3 | `TORCH_MISSING` | PyTorch ontbreekt in deze Python. Controleer of je de juiste omgeving hebt gekozen. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch bestaat, maar de import mislukt; controleer het pakket en zijn afhankelijkheden. |
| 5 | `GPU_BACKEND_ABSENT` | Het pakket declareert noch CUDA noch HIP. Kies een geschikte distributie, of vraag expliciet CPU. |
| 6 | `GPU_UNAVAILABLE` | Het pakket declareert een GPU-backend, maar er is geen bruikbare GPU zichtbaar in dit proces. Controleer de toegang tot het apparaat en de compatibiliteit van de omgeving. |
| 7 | `DEVICE_INDEX_INVALID` | De opgevraagde index staat niet in de lijst die PyTorch ziet. |
| 8 | `CHECK_FAILED` | De berekening of de gradiënt wijkt af van het vaste verwachte resultaat. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Toewijzing onmogelijk of fout van de backend; `stage` geeft de stap aan, zonder de ruwe uitzondering te exporteren. |
| 10 | `TIMEOUT` | Het subproces heeft de tijdslimiet overschreden en is gestopt. |
| 11 | `WORKER_FAILED` | Het subproces heeft geen geldig rapport geleverd. |
| 12 | `OUTPUT_WRITE_FAILED` | Het bestand bestaat al of is niet toegankelijk; kies een nieuwe naam. De algemene status mislukt, zelfs als de vorige berekening was geslaagd. |
| 130 | `INTERRUPTED` | De controle is onderbroken. |

Deel geen volledige dump van je omgeving om een fout uit te leggen. De code en de stap van het rapport vormen een eerste vaststelling; als een preciezer onderzoek nodig is, bekijk dat dan in je omgeving voordat je gegevens deelt.

## Gegevens en beperkingen

Het script voert geen netwerkverzoeken uit en stuurt niets naar Kernodeck. Het leest je notebooks, datasets, accounts, betalingen of checkpoints niet. Het verzamelt geen omgevingsvariabelen, pakketlijsten, hostnamen, gebruikersnamen, persoonlijke paden, serienummers, UUID's, GPU-processen of tokens.

De Python-versie, de systeemfamilie, de technische versies, het gefilterde GPU-model en de geheugencapaciteit kunnen een deel van je hardwareomgeving onthullen. Bekijk het rapport voordat je het deelt. De onbewerkte berichten van PyTorch en het stuurprogramma worden niet overgenomen; een onbekende versie of een onbekend model wordt een neutrale waarde. Het rapport kan dus een legitiem label weglaten.

De time-out begrenst het controle-subproces, niet de werking van het systeem of het stuurprogramma. Het script herstelt geen omgeving, valideert geen gespecialiseerde kernel en vervangt geen test van je workload. Er is geen kwaadaardige of gewijzigde software van derden beoordeeld.

## Controles die daadwerkelijk zijn uitgevoerd op 24 september 2026

De volgende voorbeelden zijn de geminimaliseerde rapporten die het script daadwerkelijk heeft geproduceerd, zonder onbewerkte uitzondering of machine-identificatie. Ze hebben betrekking op de controleomgeving en beschrijven geen enkel aanbod uit de catalogus van Kernodeck.

| Uitgevoerd geval | Omgeving | Resultaat |
| --- | --- | --- |
| Expliciete CPU | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Product en gradiënt geverifieerd; verlies `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| Standaard GPU | Dezelfde omgeving, CUDA 12.8-compilatie, NVIDIA GeForce RTX 5070 | Product en gradiënt geverifieerd op `cuda:0`; verlies `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch ontbreekt | Windows, Python 3.12.14, zonder PyTorch | `TORCH_MISSING`, uitvoer 3. [JSON van fout](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU onzichtbaar gemaakt voor alleen het testproces | Python 3.14.6 en bovenstaand CUDA-pakket | `GPU_UNAVAILABLE`, uitvoer 6. |
| Index ontbreekt, ongeldige argumenten, bestaand bestand | Afzonderlijke controleprocessen | Uitvoer 7, 2 en 12; bestaand bestand behouden. |

De testset bevat 44 controles, een mix van deze daadwerkelijke uitvoeringen en geïsoleerde unit tests. De unit tests dekken onder meer een pakket zonder GPU-backend, HIP-detectie, een backend-fout, een overschreden time-out en het filteren van velden. Ze vormen geen hardware-uitvoeringen van ROCm. **Er is geen AMD/ROCm-GPU uitgevoerd in deze testset.** NumPy 2.4.4 was importeerbaar in de controleomgeving, maar het script importeert het niet rechtstreeks.

De [geraadpleegde bronnen en hun rol](kernodeck-diagnostic-v1-SOURCES.md) onderscheiden de versies van documentatie van de versies die daadwerkelijk zijn gebruikt. Het [SHA-256-manifest](kernodeck-diagnostic-v1-manifest.json) beschrijft de bestanden van deze levering. De vingerafdrukken detecteren een verschil in een bestand; ze zijn geen handtekening van de auteur.


## Kernodeck-presentatie en compatibiliteit van rapporten

De presentatie, de bestandsnaam en de opdrachthulp dragen sinds 25 september 2026 het merk Kernodeck. De technische identificatoren van het JSON-schema blijven stabiel voor bestaande lezers. De drie voorbeeldrapporten hierboven worden byte voor byte bewaard als resultaten van de uitvoering van 24 september 2026. Hun aanwezigheid vormt geen nieuwe uitvoering van deze presentatie. Het manifest onderscheidt deze heruitgave van de historische controles.