# 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)

Pour AMD, les versions du GPU, du système, du pilote et des bibliothèques doivent former une combinaison prise en charge. Ce script ne remplace pas la [matrice officielle de compatibilité ROCm](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Lire le JSON

La structure est stable pour la version 1 :

| Champ | Signification |
| --- | --- |
| `schema`, `script_version` | Format et version du script. |
| `requested_device` | `gpu` ou `cpu` ; `unspecified` si les arguments sont invalides ou l’exécution interrompue. |
| `status`, `code`, `exit_code`, `message` | Résultat global, code stable, code du processus et explication fixe. |
| `stage` | Dernière étape atteinte : import, détection, visibilité, allocation, calcul, gradient, synchronisation, validation, etc. |
| `runtime` | Version numérique du Python utilisé et famille de système ; aucun identifiant de machine. |
| `pytorch` | Version filtrée du paquet, versions de compilation CUDA/HIP, backend déclaré et visibilité GPU quand elle a été interrogée. `null` si PyTorch n’a pas pu être importé. |
| `execution` | Périphérique réellement sélectionné, modèle GPU filtré, mémoire totale rapportée par PyTorch, type, forme des matrices et résultat des vérifications. `null` si le calcul n’a pas été préparé. |
| `host_check` | Présent uniquement sur demande : état de la lecture NVIDIA et deux champs numériques par carte. |

En mode CPU, `pytorch.backend` peut être `cuda` parce qu’il décrit le paquet installé. `execution.backend` reste `cpu` et décrit le calcul exécuté. La disponibilité GPU, le nombre de GPU, le modèle et la mémoire GPU sont alors `null` : ils n’ont pas été mesurés.

Le contrôle multiplie deux matrices 2×2 en `float32`, vérifie le produit `[[4, 4], [10, 8]]`, puis le gradient `[[16, 24], [40, 52]]`. La somme des carrés attendue vaut `196.0`. Ces petits entiers permettent ici une comparaison exacte ; cette propriété ne promet pas la reproductibilité bit à bit d’un modèle quelconque. La vérification utilise [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). La création d’un contexte GPU peut consommer davantage de mémoire que les seules matrices.

`total_memory_bytes` est une capacité rapportée, pas la mémoire libre ou utilisable par votre futur modèle. Le script ne mesure ni la mémoire maximale d’un entraînement, ni l’interconnexion, ni la vitesse, ni le multi-GPU.

## Comprendre un échec

| Sortie | Code JSON | Lecture et prochaine vérification |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Le petit calcul et son gradient sont corrects sur le périphérique indiqué. |
| 2 | `CLI_ARGUMENTS_INVALID` | Relisez `--help` ; la valeur invalide n’est pas recopiée. |
| 3 | `TORCH_MISSING` | PyTorch manque dans ce Python. Vérifiez que vous avez choisi le bon environnement. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch existe mais son import échoue ; vérifiez le paquet et ses dépendances. |
| 5 | `GPU_BACKEND_ABSENT` | Le paquet ne déclare ni CUDA ni HIP. Choisissez une distribution adaptée, ou demandez explicitement CPU. |
| 6 | `GPU_UNAVAILABLE` | Le paquet déclare un backend GPU, mais aucun GPU utilisable n’est visible dans ce processus. Vérifiez accès au périphérique et compatibilité de l’environnement. |
| 7 | `DEVICE_INDEX_INVALID` | L’index demandé n’est pas présent dans la liste visible par PyTorch. |
| 8 | `CHECK_FAILED` | Le calcul ou le gradient diffère du résultat fixe attendu. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Allocation impossible ou erreur du backend ; `stage` précise l’étape, sans exporter l’exception brute. |
| 10 | `TIMEOUT` | Le sous-processus a dépassé le délai et a été arrêté. |
| 11 | `WORKER_FAILED` | Le sous-processus n’a pas fourni de rapport valide. |
| 12 | `OUTPUT_WRITE_FAILED` | Le fichier existe déjà ou n’est pas accessible ; choisissez un nouveau nom. Le statut global échoue même si le calcul précédent avait réussi. |
| 130 | `INTERRUPTED` | Le contrôle a été interrompu. |

Ne transmettez pas un dump complet de votre environnement pour expliquer un échec. Le code et l’étape du rapport constituent un premier constat ; si une investigation plus précise est nécessaire, examinez-la dans votre environnement avant de partager des données.

## Données et limites

Le script n’effectue aucune requête réseau et ne transmet rien à Kernodeck. Il ne lit pas vos notebooks, jeux de données, comptes, paiements ou checkpoints. Il ne collecte pas de variables d’environnement, de liste de paquets, de nom d’hôte, de nom d’utilisateur, de chemin personnel, de numéro de série, de UUID, de processus GPU ou de jeton.

La version Python, la famille du système, les versions techniques, le modèle GPU filtré et la capacité mémoire peuvent révéler une partie de votre environnement matériel. Examinez le rapport avant de le partager. Les messages bruts de PyTorch et du pilote ne sont pas recopiés ; une version ou un modèle non reconnu devient une valeur neutre. Le rapport peut donc omettre un libellé légitime.

Le délai borne le sous-processus de contrôle, pas le fonctionnement du système ou du pilote. Le script ne répare pas un environnement, ne valide pas un noyau spécialisé et ne remplace pas un essai de votre charge de travail. Aucun logiciel tiers malveillant ou modifié n’a été évalué.

## Contrôles réellement effectués le 24 septembre 2026

Les exemples suivants sont les rapports minimisés réellement produits par le script, sans exception brute ni identifiant de machine. Ils concernent l’environnement de contrôle et ne décrivent aucune offre du catalogue Kernodeck.

| Cas exécuté | Environnement | Résultat |
| --- | --- | --- |
| CPU explicite | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Produit et gradient vérifiés ; perte `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU par défaut | Même environnement, compilation CUDA 12.8, NVIDIA GeForce RTX 5070 | Produit et gradient vérifiés sur `cuda:0` ; perte `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch absent | Windows, Python 3.12.14, sans PyTorch | `TORCH_MISSING`, sortie 3. [JSON d’échec](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU rendu invisible au seul processus de test | Python 3.14.6 et paquet CUDA ci-dessus | `GPU_UNAVAILABLE`, sortie 6. |
| Index absent, arguments invalides, fichier existant | Processus de contrôle séparés | Sorties 7, 2 et 12 ; fichier existant conservé. |

La recette compte 44 contrôles, mêlant ces exécutions réelles et des tests unitaires isolés. Les tests unitaires couvrent notamment un paquet sans backend GPU, la détection HIP, une erreur du backend, un délai dépassé et le filtrage des champs. Ils ne constituent pas des exécutions matérielles ROCm. **Aucun GPU AMD/ROCm n’a été exécuté dans cette recette.** NumPy 2.4.4 était importable dans l’environnement de contrôle, mais le script ne l’importe pas directement.

Les [sources consultées et leur rôle](kernodeck-diagnostic-v1-SOURCES.md) distinguent les versions de documentation des versions réellement utilisées. Le [manifeste SHA-256](kernodeck-diagnostic-v1-manifest.json) décrit les fichiers de cette livraison. Les empreintes détectent une différence de fichier ; elles ne sont pas une signature d’auteur.


## Présentation Kernodeck et compatibilité des rapports

La présentation, le nom du fichier et l’aide de commande portent la marque Kernodeck depuis le 25 septembre 2026. Les identifiants techniques du schéma JSON restent stables pour les lecteurs existants. Les trois rapports d’exemple ci-dessus sont conservés à l’octet comme résultats de l’exécution du 24 septembre 2026. Leur présence ne constitue pas une nouvelle exécution de cette présentation. Le manifeste distingue cette réédition des contrôles historiques.