Installation de cuPyNumeric (utilisateur)

Objectif

Utilisez cette compétence pour installer cuPyNumeric afin de l'utiliser depuis Python et pour vérifier que l'installation fonctionne correctement (y compris l'utilisation du GPU). Appliquez-la chaque fois qu'un utilisateur souhaite exécuter cuPyNumeric via conda ou pip. Ne l'utilisez pas pour compiler à partir du code source (pour modifier ou contribuer) — cela n'entre pas dans le cadre de cette compétence.

Règles obligatoires

• N’exécutez jamais les installations. N’exécutez pas pip install, conda install ni aucun programme d’installation. Affichez la commande ; laissez l’utilisateur l’exécuter.
• Isolez toujours l’environnement. Pas d’installation dans le répertoire conda de base, dans Python système ou dans des environnements globaux partagés.
• Détectez avant de recommander. Les vérifications en lecture seule de la version (« --version ») sont acceptables.

Prérequis

Vérifiez que la configuration système suivante est respectée avant de recommander toute installation :

• GPU: capacité de calcul ≥ 7,0 (Volta+). Prise en charge également en mode CPU seul.
• CUDA: 12.2+.
• Système d'exploitation: Linux (x86_64 / aarch64), macOS aarch64 (wheels pip uniquement), Windows via WSL.
• Python: versions 3.11 à 3.14 sous Linux ; versions 3.11 à 3.13 sous macOS aarch64.
• conda: ≥ 24.1 (chemin conda uniquement).
• Gestionnaire de paquets: conda (recommandé par l'éditeur) ou pip. Si aucun des deux n'est présent, installez-en un au préalable (voir les instructions).

Instructions

Suivez ces étapes dans l'ordre : vérifiez les prérequis, répondez aux questions de cadrage, effectuez l'installation via le chemin choisi, puis vérifiez le résultat.

À vérifier avant l'installation

1. Gestionnaire de paquets ? Vérifiez conda --version et pip --version. Privilégiez conda (recommandé par l'éditeur) ; utilisez pip à défaut.
2. Cible d'environnement ? Machine GPU, ordinateur portable CPU uniquement, cloud, conteneur ou serveur distant.
3. Version de CUDA ? Ne posez cette question que si vous imposez la variante GPU sur un hôte ne disposant pas de GPU visible. Vérifiez avec `nvidia-smi ` ou `nvcc --version`.

Bootstrap — installez d’abord un gestionnaire de paquets

Si ni conda ni pip ne sont disponibles, installez-en un. Indiquez la commande et le lien vers la documentation ; ne l'exécutez pas — curl | bash nécessite la confiance de l'utilisateur.

Recommandé : Miniforge (conda complet, conda-forge par défaut)

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash "Miniforge3-$(uname)-$(uname -m).sh"

Documentation : https://github.com/conda-forge/miniforge

Alternative : Python + pip

Installez Python à partir du gestionnaire de paquets de votre système d'exploitation (apt/dnf/brew) ou via https://www.python.org/downloads/. Si pip n'est pas présent sur une installation Python existante : python -m ensurepip --upgrade.

Après l'installation, ouvrez un nouveau terminal pour que le binaire soit ajouté au PATH.

Installation — chemin conda

conda create -n cupynumeric -c conda-forge -c legate cupynumeric
conda activate cupynumeric

Dans un environnement existant : ` conda install -c conda-forge -c legate cupynumeric`.

conda sélectionne automatiquement la variante GPU ou CPU en fonction de la disponibilité de nvidia-smi au moment de l'installation. Pour passer outre, voir ci-dessous.

Forcer la variante GPU

Définissez CONDA_OVERRIDE_CUDA uniquement lorsqu’aucun GPU n’est détecté au moment de l’installation (par exemple, lors de la création d’un conteneur pour un hôte GPU). Utilisez la version CUDA de l’hôte d’exécution :

CONDA_OVERRIDE_CUDA="12.2" conda install -c conda-forge -c legate cupynumeric

Version « nightly » (moins validée)

conda install -c conda-forge -c legate-nightly cupynumeric

Installation — chemin pip

python -m venv .venv
source .venv/bin/activate
pip install nvidia-cupynumeric

Vérification

Test de fonctionnement (à effectuer systématiquement)

Exécutez un script autonome via le lanceur Legate — aucun checkout du dépôt n'est nécessaire.

TMP=$(mktemp -d)
cat > "$TMP/smoke.py" <<'EOF'
import cupynumeric as np
a = np.arange(10)
b = np.ones((4, 4))
print("somme :", a.sum())            # résultat attendu : 45
print("matmul :", (b @ b).sum())   # résultat attendu : 64,0
EOF
legate "$TMP/smoke.py"
rm -rf "$TMP"

Résultats attendus : somme : 45 et matmul : 64,0. Si la commande « legate » est absente, l'environnement n'est pas activé — voir la section Dépannage.

Vérification de l'utilisation du GPU (obligatoire lorsqu'un GPU pris en charge est présent)

La réussite d’un test de validation ne prouve pas l’utilisation du GPU — une installation de la variante CPU sur une machine équipée d’un GPU produit également des résultats corrects. Exécutez les deux étapes.

1. Forcez le lancement du GPU. La commande ` legate --gpus N ` demande N GPU ; elle échoue rapidement si aucun GPU n’est détecté ou si la variante CPU est installée.

TMP=$(mktemp -d)
cat > "$TMP/check.py" <<'EOF'
import cupynumeric as np
print(np.ones((4096, 4096)).sum())
EOF
legate --gpus 1 "$TMP/check.py"
rm -rf "$TMP"

Le résultat attendu est 16777216,0. Si vous voyez le pilote CUDA, libcudart ou si aucun GPU n’est disponible, c’est que la variante CPU est installée ; réinstallez avec CONDA_OVERRIDE_CUDA.

2. Vérifiez que le GPU a bien été utilisé. Exécutez une boucle matmul avec une limite de temps en parallèle avec nvidia-smi, le tout depuis un seul shell — pas de conflit avec un deuxième terminal :

TMPDIR_GPU=$(mktemp -d)
SCRIPT="$TMPDIR_GPU/cupynumeric_gpu_check.py"
cat > "$SCRIPT" <<'EOF'
import cupynumeric as np, time
a = np.ones((10000, 10000))
deadline = time.time() + 20
iters = 0
while time.time() < deadline:
    b = a @ a
    _ = float(b.sum())   # forcer la synchronisation pour que la multiplication matricielle s'exécute réellement
    iters += 1
print("iters:", iters)
EOF
legate --gpus 1 "$SCRIPT" &
WORKLOAD=$!
sleep 5                                     # délai pour le démarrage de Legate
for _ in $(seq 10); do                      # 10 échantillons à 1 s — couvre un démarrage lent
  nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
  sleep 1
done
wait "$WORKLOAD"
rm -rf "$TMPDIR_GPU"

On s'attend à ce que la valeur memory.used soit de l'ordre du GiB pour la plupart des échantillons et à ce que la valeur utilization.gpu soit significative pour plusieurs d'entre eux. Si ces deux valeurs restent au niveau de référence pour tous les échantillons, cela signifie que la variante GPU n'est pas installée — vérifiez la liste conda cupynumeric pour voir s'il y a des éléments *_gpu (et non *_cpu).

Recettes plus avancées

Consultez le fichier verification_examples.md pour les vérifications multi-GPU, le repli sur CPU, les conteneurs et le dépannage.

Limitations

• Ne mélangez pas conda et pip dans un même environnement. Ce mélange remplace la première installation et provoque une erreur lors de l’importation. Pour changer, exécutez d’abord `pip uninstall nvidia-cupynumeric ` ou `conda remove cupynumeric `.
• Utilisez le lanceur « legate » pour les exécutions multi-GPU / multi-rank. Python standard s’exécute en un seul processus : `legate --gpus 2 script.py`.
• Forcez la variante GPU sur un hôte exclusivement CPU à l’aide de CONDA_OVERRIDE_CUDA. Sans cela, conda sélectionne automatiquement la variante CPU ou GPU à partir de nvidia-smi au moment de l’installation.
• Volta ou version plus récente requise. Pascal (GTX 10xx / P100) n’est pas pris en charge.
• Vérifiez que conda --version est ≥ 24.1. Les versions antérieures empêchent la sélection de variante sans avertissement.
• Les configurations multi-nœuds / MPI / UCX sont hors du champ d’application. Reportez-vous à https://docs.nvidia.com/legate/latest/networking-wheels.html et https://docs.nvidia.com/legate/latest/mpi-wrapper.html.

Dépannage

• ModuleNotFoundError : Aucun module nommé « cupynumeric » → Exécutez « which python » et « pip list | grep cupynumeric » (ou « conda list | grep cupynumeric ») depuis le même shell pour identifier l’incompatibilité d’environnement.
• ImportError mentionnant CUDA / libcudart → Réinstallez avec CONDA_OVERRIDE_CUDA=""; la variante CPU se trouve sur une machine équipée d’un GPU, ou les versions de CUDA ne correspondent pas.
• legate : commande introuvable → Activez l’environnement, puis exécutez `which legate ` pour vérifier.
• Plus lent que NumPy sur un ordinateur portable → C’est normal pour les petits problèmes (surcoût de Legate par tâche). Consultez la FAQ de cuPyNumeric.

Voir également

• references/verification_examples.md — exemples de vérification et de dépannage.
• Documentation en amont : https://docs.nvidia.com/cupynumeric/latest/installation.html
• Exigences de Legate : https://docs.nvidia.com/legate/latest/installation.html