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

Per AMD, le versioni del GPU, del sistema, del driver e delle librerie devono formare una combinazione supportata. Questo script non sostituisce la [matrice ufficiale di compatibilità ROCm](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Leggere il JSON

La struttura è stabile per la versione 1:

| Campo | Significato |
| --- | --- |
| `schema`, `script_version` | Formato e versione dello script. |
| `requested_device` | `gpu` o `cpu`; `unspecified` se gli argomenti sono invalidi o l'esecuzione è interrotta. |
| `status`, `code`, `exit_code`, `message` | Risultato globale, codice stabile, codice del processo e spiegazione fissa. |
| `stage` | Ultima fase raggiunta: import, rilevamento, visibilità, allocazione, calcolo, gradiente, sincronizzazione, validazione, ecc. |
| `runtime` | Versione numerica di Python utilizzata e famiglia di sistema; nessun identificatore di macchina. |
| `pytorch` | Versione filtrata del pacchetto, versioni di compilazione CUDA/HIP, backend dichiarato e visibilità GPU quando è stata interrogata. `null` se PyTorch non è stato importato. |
| `execution` | Dispositivo effettivamente selezionato, modello GPU filtrato, memoria totale riportata da PyTorch, tipo, forma delle matrici e risultato delle verifiche. `null` se il calcolo non è stato preparato. |
| `host_check` | Presente solo su richiesta: stato della lettura NVIDIA e due campi numerici per scheda. |

In modalità CPU, `pytorch.backend` può essere `cuda` perché descrive il pacchetto installato. `execution.backend` resta `cpu` e descrive il calcolo eseguito. La disponibilità GPU, il numero di GPU, il modello e la memoria GPU sono quindi `null`: non sono stati misurati.

Il controllo moltiplica due matrici 2×2 in `float32`, verifica il prodotto `[[4, 4], [10, 8]]`, poi il gradiente `[[16, 24], [40, 52]]`. La somma dei quadrati attesa vale `196.0`. Questi piccoli interi permettono qui un confronto esatto; questa proprietà non garantisce la riproducibilità bit per bit di un modello qualsiasi. La verifica utilizza [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). La creazione di un contesto GPU può consumare più memoria delle sole matrici.

`total_memory_bytes` è una capacità riportata, non la memoria libera o utilizzabile dal tuo futuro modello. Lo script non misura né la memoria massima di un addestramento, né l'interconnessione, né la velocità, né il multi-GPU.

## Capire un errore

| Output | Codice JSON | Lettura e prossima verifica |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Il piccolo calcolo e il suo gradiente sono corretti sul dispositivo indicato. |
| 2 | `CLI_ARGUMENTS_INVALID` | Rileggi `--help`; il valore invalido non viene ricopiato. |
| 3 | `TORCH_MISSING` | PyTorch manca in questo Python. Verifica di aver scelto l'ambiente giusto. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch esiste ma il suo import fallisce; verifica il pacchetto e le sue dipendenze. |
| 5 | `GPU_BACKEND_ABSENT` | Il pacchetto non dichiara né CUDA né HIP. Scegli una distribuzione adatta, oppure richiedi esplicitamente CPU. |
| 6 | `GPU_UNAVAILABLE` | Il pacchetto dichiara un backend GPU, ma nessuna GPU utilizzabile è visibile in questo processo. Verifica l'accesso al dispositivo e la compatibilità dell'ambiente. |
| 7 | `DEVICE_INDEX_INVALID` | L'indice richiesto non è presente nella lista visibile a PyTorch. |
| 8 | `CHECK_FAILED` | Il calcolo o il gradiente differisce dal risultato fisso atteso. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Allocazione impossibile o errore del backend; `stage` precisa la fase, senza esportare l'eccezione grezza. |
| 10 | `TIMEOUT` | Il sottoprocesso ha superato il tempo limite ed è stato arrestato. |
| 11 | `WORKER_FAILED` | Il sottoprocesso non ha fornito un report valido. |
| 12 | `OUTPUT_WRITE_FAILED` | Il file esiste già o non è accessibile; scegli un nuovo nome. Lo stato globale fallisce anche se il calcolo precedente era riuscito. |
| 130 | `INTERRUPTED` | Il controllo è stato interrotto. |

Non trasmettere un dump completo del tuo ambiente per spiegare un errore. Il codice e la fase del report costituiscono una prima constatazione; se serve un'indagine più precisa, esaminala nel tuo ambiente prima di condividere dati.

## Dati e limiti

Lo script non effettua alcuna richiesta di rete e non trasmette nulla a Kernodeck. Non legge i tuoi notebook, set di dati, account, pagamenti o checkpoint. Non raccoglie variabili d'ambiente, elenchi di pacchetti, nome host, nome utente, percorsi personali, numeri di serie, UUID, processi GPU o token.

La versione di Python, la famiglia del sistema, le versioni tecniche, il modello GPU filtrato e la capacità di memoria possono rivelare una parte del tuo ambiente hardware. Esamina il report prima di condividerlo. I messaggi grezzi di PyTorch e del driver non vengono copiati; una versione o un modello non riconosciuto diventa un valore neutro. Il report può quindi omettere un'etichetta legittima.

Il timeout limita il sottoprocesso di controllo, non il funzionamento del sistema o del driver. Lo script non ripara un ambiente, non convalida un kernel specializzato e non sostituisce una prova del tuo carico di lavoro. Nessun software di terze parti malevolo o modificato è stato valutato.

## Controlli effettivamente eseguiti il 24 settembre 2026

Gli esempi seguenti sono i report minimizzati realmente prodotti dallo script, senza eccezioni grezze né identificatori della macchina. Riguardano l'ambiente di controllo e non descrivono alcuna offerta del catalogo Kernodeck.

| Caso eseguito | Ambiente | Risultato |
| --- | --- | --- |
| CPU esplicita | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Prodotto e gradiente verificati; perdita `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU predefinita | Stesso ambiente, compilazione CUDA 12.8, NVIDIA GeForce RTX 5070 | Prodotto e gradiente verificati su `cuda:0`; perdita `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch assente | Windows, Python 3.12.14, senza PyTorch | `TORCH_MISSING`, uscita 3. [JSON di errore](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU resa invisibile al solo processo di test | Python 3.14.6 e pacchetto CUDA di cui sopra | `GPU_UNAVAILABLE`, uscita 6. |
| Indice assente, argomenti non validi, file esistente | Processi di controllo separati | Uscite 7, 2 e 12; file esistente conservato. |

La suite di test conta 44 controlli, che combinano queste esecuzioni reali e test unitari isolati. I test unitari coprono in particolare un pacchetto senza backend GPU, il rilevamento HIP, un errore del backend, un timeout superato e il filtraggio dei campi. Non costituiscono esecuzioni hardware ROCm. **Nessuna GPU AMD/ROCm è stata eseguita in questa suite di test.** NumPy 2.4.4 era importabile nell'ambiente di controllo, ma lo script non lo importa direttamente.

Le [fonti consultate e il loro ruolo](kernodeck-diagnostic-v1-SOURCES.md) distinguono le versioni della documentazione dalle versioni realmente utilizzate. Il [manifesto SHA-256](kernodeck-diagnostic-v1-manifest.json) descrive i file di questa distribuzione. Le impronte rilevano una differenza di file; non sono una firma dell'autore.


## Presentazione Kernodeck e compatibilità dei report

La presentazione, il nome del file e la guida dei comandi portano il marchio Kernodeck dal 25 settembre 2026. Gli identificatori tecnici dello schema JSON restano stabili per i lettori esistenti. I tre report di esempio sopra riportati sono conservati byte per byte come risultati dell'esecuzione del 24 settembre 2026. La loro presenza non costituisce una nuova esecuzione di questa presentazione. Il manifesto distingue questa riedizione dai controlli storici.