Démarrer avec NVSHMEM

Objectif

Guider un débutant vers la prochaine action utile. Enseigner directement le modèle mental stable, la structure du programme, le motif de compilation et le motif de lancement. Router l'installation, les variantes sensibles aux versions, les intégrations avancées et les défaillances vers la compétence spécialisée appropriée.

Prérequis

• Ne demander aucune information d'authentification, logiciel installé ou accès GPU pour l'évaluation d'adéquation et les conseils conceptuels.
• Maintenir disponibles le modèle mental fourni, les appels API de base et le guide des programmes NVSHMEM4Py pour les chemins d'enseignement qui en ont besoin.
• Maintenir disponibles $nvshmem-install, $nvshmem-docs et $nvshmem-troubleshoot-and-report-bugs pour les remises complètes d'installation, spécifiques aux versions et en cas de défaillance. Si une compétence spécialisée est indisponible, suivre la procédure de repli documentée au lieu d'inventer les détails actuels.

Entrées

• Requis : Obtenir l'objectif de l'utilisateur ou l'étape d'apprentissage demandée à partir du prompt utilisateur explicite.
• Optionnel : Obtenir les besoins de communication d'application, la langue, les versions NVSHMEM et NVSHMEM4Py, le chemin du source ou du script, l'interpréteur/environnement Python, le préfixe d'installation, l'architecture GPU cible, le lanceur, les comptes PE et nœuds, et l'environnement cible uniquement quand le chemin sélectionné en a besoin.
• Ordre de précédence des sources : Préférer le prompt utilisateur explicite actuel, puis les arguments d'invocation explicites, puis le contexte d'agent non conflictuel, puis les réponses à des questions de suivi ciblées. Signaler les valeurs conflictuelles au lieu de choisir silencieusement.

Instructions

Limite d'exécution

Par défaut, expliquer le flux de travail et imprimer les commandes pour que l'utilisateur les exécute. Ne pas compiler, lancer un programme, soumettre une tâche au planificateur, allouer des ressources ou modifier l'environnement à moins que l'utilisateur ne le demande explicitement. Traiter les demandes d'apprentissage, de démarrage ou d'aide pour exécuter un programme comme des demandes de conseils, non comme une approbation d'exécution.

Choisir un point de départ

Quand l'étape demandée est claire, ignorer le menu et traiter cette étape. Sinon, demander ce que l'utilisateur veut faire et présenter toutes les options en une seule réponse :

1. Décider si NVSHMEM convient à mon cas d'usage.
2. Apprendre le modèle mental NVSHMEM.
3. Installer NVSHMEM.
4. Exécuter un exemple NVSHMEM précompilé.
5. Compiler ou lier une application C/C++.
6. Écrire un programme NVSHMEM C/C++ ou NVSHMEM4Py.
7. Recommander l'étape suivante.

Pour l'option 7, d'abord déterminer si NVSHMEM convient au motif de communication prévu. Puis demander si NVSHMEM est installé, si un exemple a réussi, et si le code source existe déjà. Recommander le modèle mental quand l'utilisateur est complètement nouveau, l'installation quand NVSHMEM est absent, un exemple précompilé après l'installation, la conception de programme quand aucune source n'existe, et la compilation quand la source est prête.

Décider quand utiliser NVSHMEM

Partir des besoins de communication de l'application plutôt que d'une liste d'API. Décrire NVSHMEM comme une bonne adéquation quand plusieurs de ces conditions s'appliquent :

• Les threads GPU doivent initier la communication directement depuis les kernels CUDA sans rendre le contrôle au CPU pour chaque échange.
• L'application a besoin d'opérations put, get, atomiques, de signalisation ou de synchronisation finement granulaires et unilatérales entre GPUs.
• Les kernels de longue durée ou fusionnés doivent combiner calcul et communication en réduisant les frais généraux de lancement de kernels et de synchronisation CPU-GPU.
• La communication doit se chevaucher avec le calcul pour améliorer l'escalabilité forte quand la quantité de travail par GPU diminue.
• Un espace d'adressage global partitionné avec mémoire GPU symétrique allouée collectivement convient à la disposition des données de l'application.
• L'application utilise déjà des concepts OpenSHMEM ou a besoin de NVSHMEM aux côtés de MPI ou OpenSHMEM pour la communication GPU-résidente.

Donner des motifs de charge de travail représentatifs sans affirmer que NVSHMEM est obligatoire pour eux :

• échanges de voisinage ou de halo dans les stencils multi-GPU, solveurs et simulations ;
• communication irrégulière ou finement granulaire dans les charges de travail graphiques et d'analytique de données ;
• kernels GPU persistants qui communiquent à plusieurs reprises pendant le calcul ;
• réductions, broadcasts, files d'attente et protocoles producteur-consommateur initiés par GPU personnalisés ;
• applications dont l'escalabilité forte est limitée par l'orchestration CPU répétée de la communication GPU.

Expliquer quand un autre modèle peut être plus simple :

• Utiliser CUDA ordinaire pour un seul GPU ou quand aucune communication inter-GPU n'est requise.
• Préférer NCCL quand l'application fait principalement des appels collectifs en vrac standard — en particulier des opérations all-reduce, all-gather, reduce-scatter ou broadcast émises par l'hôte. NCCL convient généralement mieux que NVSHMEM pour ce motif.
• Préférer MPI quand la communication est de coarse-grain, que l'envoi et la réception pilotés par CPU suffisent, ou que l'allocation symétrique compliquerait la conception.
• Reconsidérer NVSHMEM quand la cible ne peut pas fournir l'environnement GPU, lanceur, bootstrap ou transport requis.

D'abord déterminer si le prompt contient déjà suffisamment de détails de communication pour évaluer l'adéquation. Si c'est le cas, conclure immédiatement avec l'une de ces options : bonne adéquation, adéquation possible, ou probablement plus simple avec un autre modèle et expliquer les facteurs décisifs ; ne pas reporter la recommandation derrière une liste de contrôle de questions. Sinon, demander uniquement les faits critiques manquants : où la communication est initiée, si elle est finement ou coarse-grain, quelles opérations dominent, si la communication doit se produire à l'intérieur des kernels, et quelle topologie GPU/nœud est ciblée. Puis donner la même conclusion explicite. Créer un lien vers l'Introduction NVSHMEM et Avantages officielle.

Enseigner le modèle mental

Lire complètement references/mental-model.md avant d'enseigner le chemin conceptuel. Expliquer le modèle mental sans encombrement de noms d'API et utiliser son décalage de bague illustratif quand un exemple concret serait utile. Avant d'introduire les primitives C/C++, lire complètement references/basic-api-calls.md et présenter uniquement les groupes d'API pertinents pour l'objectif de l'utilisateur. Pour une demande Python, lire aussi complètement references/nvshmem4py-programs.md avant de décrire le cycle de vie du programme ou le flux de travail de lancement. Garder les exemples cadrés comme des aides pédagogiques plutôt que comme des recettes spécifiques à l'environnement.

Résoudre le chemin pratique

Collecter uniquement le contexte requis par le chemin sélectionné. Ne pas demander tous les détails d'environnement à l'avance.

Installer NVSHMEM

Avant d'invoquer $nvshmem-install, suivre cet ordre d'entrée : résoudre la version demandée ou latest, demander si l'utilisateur a besoin de C/C++, Python ou les deux, puis à l'étape 3 demander si l'utilisateur est administrateur du système cible avec des droits root ou sudo. Sur un cluster géré, demander aussi si l'utilisateur est autorisé à modifier l'image du nœud de calcul ou la pile de logiciels partagés. Ne pas déduire l'une ou l'autre réponse de l'accès shell, de la disponibilité du gestionnaire de paquets ou du type de cible.

Invoquer $nvshmem-install. Passer le statut d'administrateur et d'autorité d'étendue de cible ensemble avec l'API ou la langue demandée, l'environnement cible, la méthode d'installation préférée, la politique de version et si l'utilisateur a besoin de fichiers runtime, d'en-têtes de développement et de bibliothèques, ou de liaison statique. Pour un utilisateur de cluster sans privilèges, ne pas présenter DEB, RPM, APT, DNF, YUM ou une autre voie de paquet système comme directement utilisable ; préférer un module de site, un conteneur approuvé, un préfixe compatible détenu par l'utilisateur, ou une remise d'administrateur clairement étiquetée.

Concevoir un programme C/C++

Lire references/basic-api-calls.md avant d'expliquer les choix de famille d'API ou de recommander des primitives spécifiques.

Enseigner directement cette structure stable :

1. Choisir l'initialisation. Utiliser nvshmem_init pour le motif autonome de base. Utiliser nvshmemx_init_attr quand l'application doit intégrer un contexte d'amorçage MPI, OpenSHMEM ou autre.
2. Initialiser, interroger un ID PE local au nœud et sélectionner le périphérique CUDA avant d'allouer de la mémoire symétrique ou de lancer des kernels.
3. Allouer les objets symétriques collectivement. Demander à chaque PE d'appeler les routines d'allocation et de désallocation dans le même ordre avec des arguments identiques.
4. Choisir la famille d'opération :
   • Utiliser put ou get pour le mouvement de données à distance.
   • Utiliser les atomiques pour les mises à jour à distance.
   • Utiliser les signaux et les attentes pour la coordination point-à-point.
   • Utiliser les collectifs d'équipe pour la communication de groupe.
5. Choisir le contexte d'invocation : API hôte, API appareil à l'intérieur d'un kernel, ou API sur-stream composée avec le travail de stream CUDA.
6. Identifier les données distantes avec une adresse symétrique et un PE de destination. Ne jamais envoyer une valeur de pointeur symétrique à un autre PE pour qu'il la réutilise comme pointeur local.
7. Ajouter le classement et la finalisation requis. Utiliser nvshmem_fence pour ordonner les opérations ultérieures après les opérations antérieures au même PE, nvshmem_quiet ou sa forme sur-stream pour la finalisation, et les barrières, signaux et attentes, ou les collectifs pour coordonner les PEs.
8. Libérer les allocations symétriques collectivement et finaliser.

Utiliser l'exemple de décalage de bague dans references/mental-model.md comme première illustration concrète ; lire cette référence avant de présenter l'exemple.

Concevoir ou exécuter un programme NVSHMEM4Py

Lire complètement references/nvshmem4py-programs.md. Demander uniquement le chemin du script Python, l'interpréteur Python ou l'environnement, la version NVSHMEM4Py si connue, le choix d'initialisation (autonome ou MPI), le lanceur, les comptes PE et nœuds, et si l'exécution est locale ou planifiée.

Enseigner le même modèle PE, mémoire symétrique, opération unilatérale et finalisation qu'en C/C++, puis le mapper au cycle de vie Python : choisir et définir le périphérique CUDA local, initialiser NVSHMEM4Py, créer collectivement des tableaux symétriques, effectuer la communication et la synchronisation requises, libérer chaque tableau symétrique collectivement et finaliser. Ne pas présenter les noms d'API C/C++ comme des API Python.

Invoquer $nvshmem-docs avec la version NVSHMEM demandée ou latest avant de donner les noms d'API Python, un exemple de code exécutable, la compatibilité des versions de paquet, l'interopérabilité des frameworks, les arguments d'initialisation ou les commandes de lancement exactes. Passer le chemin du script et tous les détails Python, lanceur, PE, nœud et environnement connus. Utiliser le résultat de la documentation pour donner une forme de commande correspondante à la version, exécutable par l'utilisateur. Confirmer que l'environnement Python sélectionné, le script, CUDA, les bibliothèques d'exécution NVSHMEM et le paquet NVSHMEM4Py sont disponibles sur chaque nœud participant.

Quand l'utilisateur fournit un script NVSHMEM4Py simple, utiliser l'exemple dans references/nvshmem4py-programs.md pour tracer sa sélection de périphérique, son initialisation, son allocation symétrique, sa communication, la finalisation de stream, le nettoyage collectif et les exigences de lancement. Identifier les étapes de cycle de vie manquantes ou une inadéquation entre l'initialisation du script et le lanceur ; ne pas exécuter ou réécrire le script à moins qu'on ne le demande.

Commencer par deux PEs sur un nœud et un PE par GPU par défaut. Demander au lanceur de propager l'environnement Python sélectionné et l'environnement CUDA/NVSHMEM à chaque PE. Expliquer la sortie attendue par PE et valider la petite exécution avant de suggérer une exécution plus grande ou multi-nœud.

Compiler et lier C/C++

Demander le chemin du source, le préfixe d'installation NVSHMEM, l'architecture GPU cible et si le projet utilise une commande nvcc directe ou CMake. Pour un fichier source CUDA standard, expliquer que l'application doit activer le code appareil relocalisable, inclure les en-têtes NVSHMEM, rechercher le répertoire de bibliothèque installé et lier à la fois les bibliothèques hôte et appareil.

Fournir cette forme de commande après avoir remplacé ou clairement étiqueté ses variables :

nvcc -rdc=true \
  -ccbin g++ \
  -gencode="$NVCC_GENCODE" \
  -I"$NVSHMEM_HOME/include" \
  application.cu \
  -L"$NVSHMEM_HOME/lib" \
  -lnvshmem_host -lnvshmem_device \
  -o application

Expliquer que NVSHMEM_HOME nomme le préfixe installé et que NVCC_GENCODE doit sélectionner l'architecture GPU cible. Pour CMake, préférer les fichiers de configuration installés avec NVSHMEM et utiliser find_package en mode config ; inspecter le paquet installé avant de nommer une cible importée.

Après la commande de compilation, déclarer que le binaire NVSHMEM résultant est toujours un programme multi-PE et doit être lancé avec nvshmrun, mpirun ou srun à un nombre de PE choisi, généralement un PE par GPU pour la première exécution. Pointer l'utilisateur vers les formes de commande de lanceur dans Exécuter un programme précompilé ; ne pas laisser nvcc ou la compilation CMake comme étape finale.

Exécuter un programme précompilé

Demander le chemin de l'exécutable, le lanceur, les comptes PE et nœuds, et si l'exécution est locale ou planifiée. Confirmer que l'exécutable et les bibliothèques d'exécution NVSHMEM sont visibles sur chaque nœud participant.

Commencer par deux PEs sur un nœud, utiliser un PE par GPU par défaut et élargir uniquement après que la petite exécution réussisse. Présenter la forme de commande qui correspond au lanceur disponible :

mpirun -n <number-of-pes> <program> [arguments]

srun -n <number-of-pes> <program> [arguments]

nvshmrun -n <number-of-pes> <program> [arguments]

Demander au lanceur de propager l'environnement CUDA et NVSHMEM à chaque PE. Expliquer la sortie attendue par PE et la vérifier avant de recommander une exécution plus grande ou multi-nœud.

Invoquer la documentation uniquement pour les variantes

Invoquer $nvshmem-docs avec une version complète demandée ou latest quand la demande a besoin de l'une des conditions suivantes :

• chemins d'exemples ou noms binaires spécifiques aux paquets ;
• PMI, PMI-2, PMIx, installation Hydra ou câblage d'amorçage non-par-défaut ;
• configuration de transport multi-nœud ou dépendances de lien spécifiques au transport ;
• liaison statique, composition de bibliothèque partagée, visibilité des symboles ou chaînes d'outils non-nvcc ;
• noms de paquet CMake ou de cibles importées ;
• disponibilité API, drapeaux, exigences, limitations ou commandes spécifiques à la version.

Limitations

• Fournir des conseils introductifs, non une couverture exhaustive d'API, d'installation, de lanceur, de transport ou de performance.
• Traiter les blocs de commande comme des formes adaptables. Ne pas affirmer qu'ils correspondent à une version installée, un agencement de paquet, une politique de cluster ou une architecture cible sans documentation spécifique à la version et inspection de la cible.
• Couvrir les conseils pour le premier programme et le lancement pour C/C++ CUDA et NVSHMEM4Py. Router les détails d'API Python, l'installation et la compatibilité des versions vers $nvshmem-docs plutôt que de les déduire.
• Évaluer l'adéquation architecturale à partir du motif de communication énoncé ; ne pas promettre d'accélération sans mesures représentatives sur la topologie cible.
• Garder l'exécution en dehors de la portée par défaut. Une demande d'explication, d'intégration ou d'aide pour exécuter un programme n'autorise pas les modifications d'environnement ou l'exécution de charge de travail.

Dépannage

Pour une défaillance d'exécution, passer ou collecter la stanza de lancement complète ou la commande complète ou le script de lot et la sortie stdout et stderr complète de chaque PE, y compris la sortie avant la première erreur et les journaux par PE. Pour une défaillance de compilation ou de liaison, passer ou collecter la commande de compilateur ou d'éditeur de liens complète, la sortie de diagnostic complète, les symboles non définis et l'ordre des bibliothèques. Dans les deux cas, inclure la version NVSHMEM, les versions CUDA et lanceur pertinentes, et les détails d'environnement cible quand disponibles.

Garder les demandes d'installation et de rédaction de programme sur leurs voies normales à moins que l'utilisateur ne signale explicitement une défaillance dans l'une des deux étapes ci-dessus.

Exemples

Évaluation d'adéquation :

Utiliser $nvshmem-get-started pour évaluer si un stencil multi-GPU avec échanges de halo GPU-résidents est une bonne adéquation NVSHMEM ou est plus simple avec MPI.

Demander uniquement les faits de communication qui affectent la décision, puis conclure avec bonne adéquation, adéquation possible ou probablement plus simple avec un autre modèle et expliquer les facteurs décisifs.

Conseils pour le premier programme :

Utiliser $nvshmem-get-started pour m'aider à concevoir, compiler et lancer mon premier programme NVSHMEM ring en C++ sans rien exécuter.

Enseigner le modèle mental avant les primitives concrètes, présenter les formes de compilation et de lancement adaptables et garder l'exécution hors de la portée à moins que l'utilisateur ne la demande séparément.

Conseils de première exécution NVSHMEM4Py :

Utiliser $nvshmem-get-started pour m'aider à exécuter mon premier programme NVSHMEM4Py avec deux GPUs, sans rien exécuter.

Lire le guide des programmes NVSHMEM4Py, collecter le contexte de l'environnement Python et du lanceur, obtenir l'API Python actuelle correspondant à la version et les détails de lancement de $nvshmem-docs, et fournir un plan de première petite exécution exécutable par l'utilisateur.

<!-- ci trigger -->