Instalación de cuPyNumeric (usuario)

Objetivo

Utiliza esta habilidad para instalar cuPyNumeric para su uso desde Python y para comprobar que la instalación funciona correctamente (incluido el uso de la GPU). Aplícala siempre que un usuario desee ejecutar cuPyNumeric a través de conda o pip. No la utilices para compilar desde el código fuente (para modificar o contribuir), ya que eso queda fuera del alcance de esta habilidad.

Normas obligatorias

• Nunca ejecutes instalaciones. No ejecutes «pip install», «conda install» ni ningún instalador. Muestra el comando; deja que el usuario lo ejecute.
• Aísla siempre el proceso. No realices instalaciones en el conda base, en el Python del sistema ni en entornos globales compartidos.
• Detecta antes de recomendar. Las comprobaciones de solo lectura con --version están bien.

Requisitos previos

Confirma estos requisitos del sistema antes de recomendar cualquier instalación:

• GPU: capacidad de cálculo ≥ 7,0 (Volta+). También se admite el uso exclusivo de la CPU.
• CUDA: 12.2+.
• SO: Linux (x86_64 / aarch64), macOS aarch64 (solo paquetes «pip wheel»), Windows a través de WSL.
• Python: de la versión 3.11 a la 3.14 en Linux; de la versión 3.11 a la 3.13 en macOS aarch64.
• conda: ≥ 24.1 (solo en la ruta de conda).
• Gestor de paquetes: conda (recomendado por el desarrollador original) o pip. Si no está presente ninguno de los dos, instala primero uno de ellos (consulta las instrucciones).

Instrucciones

Sigue estos pasos en orden: confirma los requisitos previos, responde a las preguntas de alcance, instala a través de la ruta elegida y, a continuación, verifica.

Pregúntate antes de instalar

1. ¿Gestor de paquetes? Comprueba conda --version y pip --version. Es preferible conda (recomendado por el desarrollador original); en su defecto, utiliza pip.
2. ¿Entorno de destino? Máquina con GPU, portátil solo con CPU, nube, contenedor o servidor remoto.
3. ¿Versión de CUDA? Pregunta solo si vas a forzar la variante con GPU en un host sin una GPU visible. Compruébalo con nvidia-smi / nvcc --version.

Inicio: instala primero un gestor de paquetes

Si no está disponible ni conda ni pip, instala uno. Indica el comando y el enlace a la documentación; no lo ejecutes: ` curl | bash ` requiere la confianza del usuario.

Recomendado: Miniforge (conda completo, conda-forge por defecto)

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

Documentación: https://github.com/conda-forge/miniforge

Alternativa: Python + pip

Instala Python desde el gestor de paquetes de tu sistema operativo (apt/dnf/brew) o desde https://www.python.org/downloads/. Si falta pip en una instalación existente de Python: python -m ensurepip --upgrade.

Tras la instalación, abre un nuevo terminal para que el binario quede en la variable PATH.

Instalación — ruta de conda

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

En un entorno ya existente: conda install -c conda-forge -c legate cupynumeric.

conda selecciona automáticamente la variante de GPU o CPU en función de si nvidia-smi funciona en el momento de la instalación. Para anular esta selección, consulta más abajo.

Forzar la variante de GPU

Establece CONDA_OVERRIDE_CUDA solo cuando no se detecte ninguna GPU en el momento de la instalación (por ejemplo, al compilar un contenedor para un host con GPU). Utiliza la versión de CUDA del host de ejecución:

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

Versión nocturna (menos validada)

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

Instalación — ruta de pip

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

Verificar

Prueba básica (ejecutar siempre)

Ejecuta un script autónomo a través del lanzador de Legate; no es necesario extraer el repositorio.

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

Se espera que sum: 45 y matmul: 64.0. Si falta el comando «legate», el entorno no está activado; consulta la sección «Solución de problemas».

Comprobación del uso de la GPU (obligatoria cuando hay una GPU compatible)

Superar la prueba de humo no garantiza el uso de la GPU: una instalación de la variante para CPU en un equipo con GPU también produce resultados correctos. Ejecuta ambos pasos.

1. Forzar el inicio de la GPU. legate --gpus N solicita N GPU; falla rápidamente si no hay ninguna GPU visible o si está instalada la variante para CPU.

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"

El resultado esperado es 16777216,0. Si detectas el controlador CUDA, libcudart o no hay GPUs disponibles, significa que está instalada la variante para CPU; reinstala con CONDA_OVERRIDE_CUDA.

2. Confirma que se ha utilizado la GPU. Ejecuta un bucle matmul con límite de tiempo junto con nvidia-smi, todo desde un único shell — sin necesidad de un segundo 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())   # forzar la sincronización para que la operación matmul se ejecute realmente
    iters += 1
print("iters:", iters)
EOF
legate --gpus 1 "$SCRIPT" &
WORKLOAD=$!
sleep 5                                     # búfer para el arranque de Legate
for _ in $(seq 10); do                      # 10 muestras a intervalos de 1 s — cubre el arranque lento
  nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
  sleep 1
done
wait "$WORKLOAD"
rm -rf "$TMPDIR_GPU"

Se espera que «memory.used» se sitúe en el rango de los GiB en la mayoría de las muestras y que «utilization.gpu» presente valores significativos en varias de ellas. Si ambos valores se mantienen en el nivel de referencia en todas las muestras, la variante de la GPU no está instalada; comprueba «conda list cupynumeric» en busca de *_gpu (no *_cpu).

Recetas más detalladas

Consulta verification_examples.md para comprobaciones de múltiples GPU, recurso alternativo de CPU, contenedores y resolución de problemas.

Limitaciones

• No mezcles conda y pip en un mismo entorno. La mezcla anula la primera instalación y provoca errores al importar. Para cambiar, ejecuta primero `pip uninstall nvidia-cupynumeric ` o `conda remove cupynumeric `.
• Utiliza el lanzador «legate» para ejecuciones con múltiples GPU o múltiples rangos. Python sin más ejecuta un único proceso: «legate --gpus 2 script.py».
• Fuerza la variante de GPU en un host solo con CPU mediante CONDA_OVERRIDE_CUDA. De lo contrario, conda selecciona automáticamente la variante de CPU o GPU a partir de nvidia-smi en el momento de la instalación.
• Se requiere Volta o una versión más reciente. Pascal (GTX 10xx / P100) no es compatible.
• Comprueba que conda --version sea≥ 24.1. Las versiones anteriores impiden la selección de variantes sin avisar.
• Considera que los entornos multinodo, MPI y UCX quedan fuera del alcance de esta guía. Consulta https://docs.nvidia.com/legate/latest/networking-wheels.html y https://docs.nvidia.com/legate/latest/mpi-wrapper.html.

Solución de problemas

• ModuleNotFoundError: No hay ningún módulo llamado «cupynumeric» → Ejecuta «which python» y «pip list | grep cupynumeric» (o «conda list | grep cupynumeric») desde el mismo shell para detectar la incompatibilidad de entornos.
• Error de importación relacionado con CUDA / libcudart → Vuelve a instalar con CONDA_OVERRIDE_CUDA=""; la variante para CPU está en un equipo con GPU, o las versiones de CUDA no coinciden.
• legate: comando no encontrado → Activa el entorno y, a continuación, ejecuta «which legate » para confirmarlo.
• Más lento que NumPy en un portátil → Es de esperar en problemas pequeños (sobrecarga de Legate por tarea). Consulta las preguntas frecuentes de cuPyNumeric.

Véase también

• references/verification_examples.md — ejemplos de verificación y resolución de problemas.
• Documentación del proyecto original: https://docs.nvidia.com/cupynumeric/latest/installation.html
• Requisitos de Legate: https://docs.nvidia.com/legate/latest/installation.html