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

For AMD, the GPU, system, driver, and library versions must form a supported combination. This script does not replace the [official ROCm compatibility matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Reading the JSON

The structure is stable for version 1:

| Field | Meaning |
| --- | --- |
| `schema`, `script_version` | Format and version of the script. |
| `requested_device` | `gpu` or `cpu`; `unspecified` if the arguments are invalid or execution was interrupted. |
| `status`, `code`, `exit_code`, `message` | Overall result, stable code, process code, and fixed explanation. |
| `stage` | Last stage reached: import, detection, visibility, allocation, compute, gradient, synchronization, validation, etc. |
| `runtime` | Numeric version of the Python used and system family; no machine identifier. |
| `pytorch` | Filtered package version, CUDA/HIP build versions, declared backend, and GPU visibility when it was queried. `null` if PyTorch could not be imported. |
| `execution` | Device actually selected, filtered GPU model, total memory reported by PyTorch, type, matrix shapes, and check results. `null` if the computation was not prepared. |
| `host_check` | Present only on request: NVIDIA read status and two numeric fields per card. |

In CPU mode, `pytorch.backend` can be `cuda` because it describes the installed package. `execution.backend` remains `cpu` and describes the computation performed. GPU availability, GPU count, GPU model, and GPU memory are then `null`: they were not measured.

The check multiplies two 2×2 matrices in `float32`, verifies the product `[[4, 4], [10, 8]]`, then the gradient `[[16, 24], [40, 52]]`. The expected sum of squares is `196.0`. These small integers allow an exact comparison here; this property does not promise bit-for-bit reproducibility of any given model. The verification uses [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). Creating a GPU context can consume more memory than the matrices alone.

`total_memory_bytes` is a reported capacity, not the free or usable memory for your future model. The script measures neither the peak memory of a training run, nor interconnect, nor speed, nor multi-GPU.

## Understanding a failure

| Exit | JSON code | Reading and next check |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | The small computation and its gradient are correct on the indicated device. |
| 2 | `CLI_ARGUMENTS_INVALID` | Re-read `--help`; the invalid value is not copied. |
| 3 | `TORCH_MISSING` | PyTorch is missing from this Python. Check that you selected the right environment. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch exists but its import fails; check the package and its dependencies. |
| 5 | `GPU_BACKEND_ABSENT` | The package declares neither CUDA nor HIP. Choose a suitable distribution, or explicitly request CPU. |
| 6 | `GPU_UNAVAILABLE` | The package declares a GPU backend, but no usable GPU is visible in this process. Check device access and environment compatibility. |
| 7 | `DEVICE_INDEX_INVALID` | The requested index is not present in the list visible to PyTorch. |
| 8 | `CHECK_FAILED` | The computation or gradient differs from the expected fixed result. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Allocation failed or backend error; `stage` indicates the step, without exporting the raw exception. |
| 10 | `TIMEOUT` | The subprocess exceeded the time limit and was stopped. |
| 11 | `WORKER_FAILED` | The subprocess did not provide a valid report. |
| 12 | `OUTPUT_WRITE_FAILED` | The file already exists or is not accessible; choose a new name. The overall status fails even if the previous computation had succeeded. |
| 130 | `INTERRUPTED` | The check was interrupted. |

Do not send a full dump of your environment to explain a failure. The code and the stage in the report are a first finding; if a more detailed investigation is needed, examine it in your environment before sharing data.

## Data and limitations

The script makes no network requests and transmits nothing to Kernodeck. It does not read your notebooks, datasets, accounts, payments, or checkpoints. It does not collect environment variables, package lists, hostnames, usernames, personal paths, serial numbers, UUIDs, GPU processes, or tokens.

The Python version, OS family, technical versions, filtered GPU model, and memory capacity may reveal part of your hardware environment. Review the report before sharing it. Raw PyTorch and driver messages are not copied over; an unrecognized version or model becomes a neutral value. The report may therefore omit a legitimate label.

The timeout bounds the check subprocess, not the operation of the system or driver. The script does not repair an environment, validate a specialized kernel, or replace a trial run of your workload. No malicious or modified third-party software was evaluated.

## Checks actually performed on September 24, 2026

The following examples are the minimized reports actually produced by the script, with no raw exception or machine identifier. They concern the control environment and do not describe any offering in the Kernodeck catalog.

| Case run | Environment | Result |
| --- | --- | --- |
| Explicit CPU | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Product and gradient verified; loss `196.0`. [CPU JSON](kernodeck-diagnostic-v1-cpu-example.json) |
| Default GPU | Same environment, CUDA 12.8 build, NVIDIA GeForce RTX 5070 | Product and gradient verified on `cuda:0`; loss `196.0`. [CUDA JSON](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch absent | Windows, Python 3.12.14, without PyTorch | `TORCH_MISSING`, exit 3. [Failure JSON](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU made invisible to the test process only | Python 3.14.6 and CUDA package above | `GPU_UNAVAILABLE`, exit 6. |
| Missing index, invalid arguments, existing file | Separate check processes | Exits 7, 2, and 12; existing file preserved. |

The test suite contains 44 checks, combining these real runs and isolated unit tests. The unit tests cover, among other things, a package without a GPU backend, HIP detection, a backend error, an exceeded timeout, and field filtering. They do not constitute ROCm hardware runs. **No AMD/ROCm GPU was run in this test suite.** NumPy 2.4.4 was importable in the control environment, but the script does not import it directly.

The [sources consulted and their role](kernodeck-diagnostic-v1-SOURCES.md) distinguish documentation versions from the versions actually used. The [SHA-256 manifest](kernodeck-diagnostic-v1-manifest.json) describes the files in this delivery. The fingerprints detect a file difference; they are not an author signature.


## Kernodeck branding and report compatibility

The branding, file name, and command help have carried the Kernodeck brand since September 25, 2026. The technical identifiers of the JSON schema remain stable for existing readers. The three example reports above are preserved byte-for-byte as results of the September 24, 2026 run. Their presence does not constitute a new run of this branding. The manifest distinguishes this reissue from the historical checks.