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

Para AMD, las versiones de la GPU, del sistema, del controlador y de las bibliotecas deben formar una combinación admitida. Este script no sustituye a la [matriz oficial de compatibilidad de ROCm](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Leer el JSON

La estructura es estable para la versión 1:

| Campo | Significado |
| --- | --- |
| `schema`, `script_version` | Formato y versión del script. |
| `requested_device` | `gpu` o `cpu`; `unspecified` si los argumentos no son válidos o la ejecución se interrumpe. |
| `status`, `code`, `exit_code`, `message` | Resultado global, código estable, código del proceso y explicación fija. |
| `stage` | Última etapa alcanzada: import, detección, visibilidad, asignación, cálculo, gradiente, sincronización, validación, etc. |
| `runtime` | Versión numérica de Python utilizado y familia de sistema; ningún identificador de máquina. |
| `pytorch` | Versión filtrada del paquete, versiones de compilación CUDA/HIP, backend declarado y visibilidad de GPU cuando se consultó. `null` si PyTorch no se pudo importar. |
| `execution` | Dispositivo realmente seleccionado, modelo de GPU filtrado, memoria total informada por PyTorch, tipo, forma de las matrices y resultado de las comprobaciones. `null` si el cálculo no se preparó. |
| `host_check` | Presente solo bajo petición: estado de la lectura NVIDIA y dos campos numéricos por tarjeta. |

En modo CPU, `pytorch.backend` puede ser `cuda` porque describe el paquete instalado. `execution.backend` sigue siendo `cpu` y describe el cálculo ejecutado. La disponibilidad de GPU, el número de GPU, el modelo y la memoria de GPU son entonces `null`: no se midieron.

La comprobación multiplica dos matrices 2×2 en `float32`, verifica el producto `[[4, 4], [10, 8]]`, y luego el gradiente `[[16, 24], [40, 52]]`. La suma de los cuadrados esperada vale `196.0`. Estos enteros pequeños permiten aquí una comparación exacta; esta propiedad no promete la reproducibilidad bit a bit de un modelo cualquiera. La verificación utiliza [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). La creación de un contexto GPU puede consumir más memoria que las solas matrices.

`total_memory_bytes` es una capacidad informada, no la memoria libre o utilizable por tu futuro modelo. El script no mide ni la memoria máxima de un entrenamiento, ni la interconexión, ni la velocidad, ni el multi-GPU.

## Entender un fallo

| Salida | Código JSON | Lectura y siguiente comprobación |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | El pequeño cálculo y su gradiente son correctos en el dispositivo indicado. |
| 2 | `CLI_ARGUMENTS_INVALID` | Vuelve a leer `--help`; el valor inválido no se copia. |
| 3 | `TORCH_MISSING` | Falta PyTorch en este Python. Comprueba que hayas elegido el entorno correcto. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch existe pero su import falla; verifica el paquete y sus dependencias. |
| 5 | `GPU_BACKEND_ABSENT` | El paquete no declara ni CUDA ni HIP. Elige una distribución adaptada, o solicita explícitamente CPU. |
| 6 | `GPU_UNAVAILABLE` | El paquete declara un backend GPU, pero no hay ninguna GPU utilizable visible en este proceso. Verifica el acceso al dispositivo y la compatibilidad del entorno. |
| 7 | `DEVICE_INDEX_INVALID` | El índice solicitado no está presente en la lista visible por PyTorch. |
| 8 | `CHECK_FAILED` | El cálculo o el gradiente difiere del resultado fijo esperado. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Asignación imposible o error del backend; `stage` precisa la etapa, sin exportar la excepción en bruto. |
| 10 | `TIMEOUT` | El subproceso superó el tiempo límite y se detuvo. |
| 11 | `WORKER_FAILED` | El subproceso no proporcionó un informe válido. |
| 12 | `OUTPUT_WRITE_FAILED` | El archivo ya existe o no es accesible; elige un nombre nuevo. El estado global falla aunque el cálculo anterior hubiera tenido éxito. |
| 130 | `INTERRUPTED` | La comprobación se interrumpió. |

No transmitas un dump completo de tu entorno para explicar un fallo. El código y la etapa del informe constituyen una primera constatación; si se necesita una investigación más precisa, examínala en tu entorno antes de compartir datos.

## Datos y límites

El script no realiza ninguna solicitud de red ni transmite nada a Kernodeck. No lee tus notebooks, conjuntos de datos, cuentas, pagos ni checkpoints. No recopila variables de entorno, listas de paquetes, nombre de host, nombre de usuario, rutas personales, número de serie, UUID, procesos de GPU ni tokens.

La versión de Python, la familia del sistema, las versiones técnicas, el modelo de GPU filtrado y la capacidad de memoria pueden revelar parte de tu entorno de hardware. Examina el informe antes de compartirlo. Los mensajes sin procesar de PyTorch y del controlador no se copian; una versión o un modelo no reconocido se convierte en un valor neutro. Por lo tanto, el informe puede omitir una etiqueta legítima.

El tiempo límite acota el subproceso de control, no el funcionamiento del sistema o del controlador. El script no repara un entorno, no valida un kernel especializado y no sustituye una prueba de tu carga de trabajo. No se ha evaluado ningún software de terceros malicioso o modificado.

## Controles realmente efectuados el 24 de septiembre de 2026

Los siguientes ejemplos son los informes minimizados realmente producidos por el script, sin excepción sin procesar ni identificador de máquina. Corresponden al entorno de control y no describen ninguna oferta del catálogo de Kernodeck.

| Caso ejecutado | Entorno | Resultado |
| --- | --- | --- |
| CPU explícita | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Producto y gradiente verificados; pérdida `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU por defecto | Mismo entorno, compilación CUDA 12.8, NVIDIA GeForce RTX 5070 | Producto y gradiente verificados en `cuda:0`; pérdida `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch ausente | Windows, Python 3.12.14, sin PyTorch | `TORCH_MISSING`, salida 3. [JSON de fallo](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU invisible solo para el proceso de prueba | Python 3.14.6 y el paquete CUDA anterior | `GPU_UNAVAILABLE`, salida 6. |
| Índice ausente, argumentos no válidos, archivo existente | Procesos de control separados | Salidas 7, 2 y 12; archivo existente conservado. |

El conjunto de pruebas cuenta con 44 controles, que combinan estas ejecuciones reales y pruebas unitarias aisladas. Las pruebas unitarias cubren, en particular, un paquete sin backend de GPU, la detección de HIP, un error del backend, un tiempo límite superado y el filtrado de campos. No constituyen ejecuciones de hardware ROCm. **No se ha ejecutado ninguna GPU AMD/ROCm en este conjunto de pruebas.** NumPy 2.4.4 era importable en el entorno de control, pero el script no lo importa directamente.

Las [fuentes consultadas y su función](kernodeck-diagnostic-v1-SOURCES.md) distinguen las versiones de documentación de las versiones realmente utilizadas. El [manifiesto SHA-256](kernodeck-diagnostic-v1-manifest.json) describe los archivos de esta entrega. Las huellas detectan una diferencia de archivo; no son una firma de autor.


## Presentación de Kernodeck y compatibilidad de los informes

La presentación, el nombre del archivo y la ayuda de comando llevan la marca Kernodeck desde el 25 de septiembre de 2026. Los identificadores técnicos del esquema JSON permanecen estables para los lectores existentes. Los tres informes de ejemplo anteriores se conservan byte a byte como resultados de la ejecución del 24 de septiembre de 2026. Su presencia no constituye una nueva ejecución de esta presentación. El manifiesto distingue esta reedición de los controles históricos.