Merge pull request #784 from AaltoSciComp/gpu-cuda-compute

simo-tuomisto · web-flow · commit 54cea9889897 · 2025-09-17T14:11:03.000+03:00
Update docs to new GPU request syntax
diff --git a/triton/apps/keras.rst b/triton/apps/keras.rst
@@ -24,7 +24,7 @@ Example
 
 ::
 
-   srun --gres=gpu:1 --pty bash
+   srun --gpus=1 --pty bash
    module load scicomp-python-env
    python3
    >>> import keras
diff --git a/triton/examples/cntk/cntk_mnist.rst b/triton/examples/cntk/cntk_mnist.rst
@@ -14,7 +14,7 @@ One can run this example with ``srun``::
 
   wget https://raw.githubusercontent.com/AaltoSciComp/scicomp-docs/master/triton/examples/cntk/cntk_mnist.py
   module load nvidia-cntk
-  srun --time=00:15:00 --gres=gpu:1 singularity_wrapper exec python cntk_mnist.py
+  srun --time=00:15:00 --mem=4G --gpus=1 singularity_wrapper exec python cntk_mnist.py
 
 or with ``sbatch`` by submitting
 :download:`cntk_mnist.sh</triton/examples/cntk/cntk_mnist.sh>`:
diff --git a/triton/examples/cntk/cntk_mnist.sh b/triton/examples/cntk/cntk_mnist.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
-#SBATCH --gres=gpu:1
 #SBATCH --time=00:15:00
+#SBATCH --gpus=1
 
 module load nvidia-cntk
 
diff --git a/triton/examples/cntk/cntk_mnist_ex4.sh b/triton/examples/cntk/cntk_mnist_ex4.sh
@@ -1,6 +1,7 @@
 #!/bin/bash
-#SBATCH --gres=gpu:1
 #SBATCH --time=00:15:00
+#SBATCH --mem=4G
+#SBATCH --gpus=1
 
 module load nvidia-cntk
 
diff --git a/triton/examples/detectron/detectron.sh b/triton/examples/detectron/detectron.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 #SBATCH --time=00:30:00
 #SBATCH --mem=8G
-#SBATCH --gres=gpu:teslap100:1
+#SBATCH --gpus=1
 #SBATCH -o detectron.out
 
 module load singularity-detectron
diff --git a/triton/examples/detectron/detectron2.sh b/triton/examples/detectron/detectron2.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 #SBATCH --time=00:30:00
 #SBATCH --mem=8G
-#SBATCH --gres=gpu:teslap100:1
+#SBATCH --gpus=1
 #SBATCH -o detectron.out
 
 module load singularity-detectron
diff --git a/triton/examples/openpose/openpose.sh b/triton/examples/openpose/openpose.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 #SBATCH --time=00:10:00
 #SBATCH --mem=8G
-#SBATCH --gres=gpu:1
+#SBATCH --gpus=1
 
 module load singularity-openpose/v1.5.1
 
diff --git a/triton/examples/python/simple_python_gpu.sh b/triton/examples/python/simple_python_gpu.sh
@@ -1,8 +1,9 @@
 #!/bin/bash
-#SBATCH --cpus-per-task 1       # The number of CPUs your code can use, if in doubt, use 1 for CPU only code or 6 if you run on GPUs (since code running on GPUs commonly allows parallelization of data provision to the GPU)
-#SBATCH --mem 10G               # The amount of memory you expect your code to need. Format is 10G for 10 Gigabyte, 500M for 500 Megabyte etc
+#SBATCH --cpus-per-task=1       # The number of CPUs your code can use, if in doubt, use 1 for CPU only code or 6 if you run on GPUs (since code running on GPUs commonly allows parallelization of data provision to the GPU)
+#SBATCH --mem=10G               # The amount of memory you expect your code to need. Format is 10G for 10 Gigabyte, 500M for 500 Megabyte etc
 #SBATCH --time=01:00:00         # Time in HH:MM:SS or DD-HH of your job. the maximum is 120 hours or 5 days.
-#SBATCH --gres=gpu:1            # Additional specific ressources can be requested via gres. Mainly used for requesting GPUs format is: gres=RessourceType:Number
+#SBATCH --gpus=1                # Request a GPU
+
 module load python-scicomp-env  # or `module load mamba` if you use your own environment.
 source activate yourEnvironment # if you use your own environment
 python yourScriptName.py ARG    
diff --git a/triton/examples/pytorch/pytorch_mnist.rst b/triton/examples/pytorch/pytorch_mnist.rst
@@ -16,7 +16,7 @@ One can run this example with ``srun``:
 
   $ wget https://raw.githubusercontent.com/AaltoSciComp/scicomp-docs/master/triton/examples/pytorch/pytorch_mnist.py
   $ module load scicomp-python-env
-  $ srun --time=00:15:00 --gres=gpu:1 python pytorch_mnist.py
+  $ srun --time=00:15:00 --mem=4G --gpus=1 python pytorch_mnist.py
 
 or with ``sbatch`` by submitting
 :download:`pytorch_mnist.sh</triton/examples/pytorch/pytorch_mnist.sh>`:
diff --git a/triton/examples/pytorch/pytorch_mnist.sh b/triton/examples/pytorch/pytorch_mnist.sh
@@ -1,6 +1,7 @@
 #!/bin/bash
-#SBATCH --gres=gpu:1
 #SBATCH --time=00:15:00
+#SBATCH --mem=4G
+#SBATCH --gpus=1
 
 module load scicomp-python-env
 
diff --git a/triton/examples/pytorch/pytorch_singularity_mnist.rst b/triton/examples/pytorch/pytorch_singularity_mnist.rst
@@ -13,7 +13,7 @@ One can run this example with ``srun``::
 
   wget https://raw.githubusercontent.com/AaltoSciComp/scicomp-docs/master/triton/examples/pytorch/pytorch_mnist.py
   module load nvidia-pytorch/20.02-py3
-  srun --time=00:15:00 --gres=gpu:1 singularity_wrapper exec python pytorch_mnist.py
+  srun --time=00:15:00 --mem=4G --gpus=1 singularity_wrapper exec python pytorch_mnist.py
 
 or with ``sbatch`` by submitting
 :download:`pytorch_singularity_mnist.sh</triton/examples/pytorch/pytorch_singularity_mnist.sh>`:
diff --git a/triton/examples/pytorch/pytorch_singularity_mnist.sh b/triton/examples/pytorch/pytorch_singularity_mnist.sh
@@ -1,6 +1,7 @@
 #!/bin/bash
-#SBATCH --gres=gpu:1
 #SBATCH --time=00:15:00
+#SBATCH --mem=4G
+#SBATCH --gpus=1
 
 module load nvidia-pytorch/20.02-py3
 
diff --git a/triton/examples/tensorflow/tensorflow_mnist.rst b/triton/examples/tensorflow/tensorflow_mnist.rst
@@ -16,7 +16,7 @@ One can run this example with ``srun``:
 
   $ wget https://raw.githubusercontent.com/AaltoSciComp/scicomp-docs/master/triton/examples/tensorflow/tensorflow_mnist.py
   $ module load scicomp-python-env
-  $ srun --time=00:15:00 --gres=gpu:1 python tensorflow_mnist.py
+  $ srun --time=00:15:00 --mem=4G --gpus=1 python tensorflow_mnist.py
 
 or with ``sbatch`` by submitting
 :download:`tensorflow_mnist.sh</triton/examples/tensorflow/tensorflow_mnist.sh>`:
diff --git a/triton/examples/tensorflow/tensorflow_mnist.sh b/triton/examples/tensorflow/tensorflow_mnist.sh
@@ -1,6 +1,7 @@
 #!/bin/bash
-#SBATCH --gres=gpu:1
 #SBATCH --time=00:15:00
+#SBATCH --mem=4G
+#SBATCH --gpus=1
 
 module load scicomp-python-env
 
diff --git a/triton/examples/tensorflow/tensorflow_singularity_mnist.rst b/triton/examples/tensorflow/tensorflow_singularity_mnist.rst
@@ -13,7 +13,7 @@ One can run this example with ``srun``::
 
   wget https://raw.githubusercontent.com/AaltoSciComp/scicomp-docs/master/triton/examples/tensorflow/tensorflow_mnist.py
   module load nvidia-tensorflow/20.02-tf1-py3
-  srun --time=00:15:00 --gres=gpu:1 singularity_wrapper exec python tensorflow_mnist.py
+  srun --time=00:15:00 --mem=4G --gpus=1 singularity_wrapper exec python tensorflow_mnist.py
 
 or with ``sbatch`` by submitting
 :download:`tensorflow_singularity_mnist.sh</triton/examples/tensorflow/tensorflow_singularity_mnist.sh>`:
diff --git a/triton/examples/tensorflow/tensorflow_singularity_mnist.sh b/triton/examples/tensorflow/tensorflow_singularity_mnist.sh
@@ -1,6 +1,7 @@
 #!/bin/bash
-#SBATCH --gres=gpu:1
 #SBATCH --time=00:15:00
+#SBATCH --mem=4G
+#SBATCH --gpus=1
 
 module load nvidia-tensorflow/20.02-tf1-py3
 
diff --git a/triton/ref/gpu.rst b/triton/ref/gpu.rst
@@ -2,18 +2,23 @@
    :delim: |
    :header-rows: 1
 
-   Card                 | Slurm partition (``--partition=``) | Slurm feature name (``--constraint=``) | Slurm gres name (``--gres=gpu:NAME:n``) | total amount   | nodes        | architecture   | compute threads per GPU   | memory per card   | CUDA compute capability
-   NVIDIA V100          | ``gpu-v100-32g``                   | ``volta``                              | ``v100``                                | 40             | gpu[1-10]    | Volta          | 5120                      | 32GB              | 7.0
-   NVIDIA V100          | ``gpu-v100-32g``                   | ``volta``                              | ``v100``                                | 40             | gpu[28-37]   | Volta          | 5120                      | 32GB              | 7.0
-   NVIDIA V100          | ``gpu-v100-16g``                   | ``volta``                              | ``v100``                                | 176            | dgx[1-2,8-27]| Volta          | 5120                      | 16GB              | 7.0
-   NVIDIA V100          | ``gpu-v100-32g``                   | ``volta``                              | ``v100``                                | 32             | dgx[3,5-7]   | Volta          | 5120                      | 32GB              | 7.0
-   NVIDIA A100          | ``gpu-a100-80g``                   | ``ampere``                             | ``a100``                                | 56             | gpu[11-17,38-44] | Ampere     | 7936                      | 80GB              | 8.0
-   NVIDIA H100          | ``gpu-h100-80g``                   | ``hopper``                             | ``h100``                                | 16             | gpu[45-48]   | Hopper         | 16896                     | 80GB              | 9.0
-   NVIDIA H200          | ``gpu-h200-35g-ia``                | ``hopper``                             | ``h200-35g``                            | 24             | gpu[49]      | Hopper         |                           | 35GB              | 9.0
-   NVIDIA H200(*)       | ``gpu-h200-141g-ellis``, ``gpu-h200-141g-short``  | ``hopper``              | ``h200``                                | 112            | gpu[50-63]   | Hopper         |                           | 141GB             | 9.0
-   AMD MI100            | ``gpu-amd``                        |    features not supported              | ``-p gpu-amd --gres=gpu:mi100``         | 1              | gpuamd[1]    |                |                           |                   |
-   AMD MI210            | ``gpu-amd``                        |    features not supported              | ``-p gpu-amd --gres=gpu:mi210``         | 2              | gpuamd[1]    |                |                           |                   |
+   GPU brand name       | GPU name in Slurm (``--gpus=NAME:n``)  | Amount of VRAM                   | CUDA compute capability         | total amount   | nodes            | GPUs per node | Compute threads per GPU   | Slurm partition (``--partition=``)               |
+   NVIDIA H200(*)       | ``h200``                               | 141GB (``--gres=gpu-vram:141g``) | 9.0 (``--gres=min-cuda-cc=90``) | 112            | gpu[50-63]       | 8             | 16896                     | ``gpu-h200-141g-ellis``, ``gpu-h200-141g-short`` |
+   NVIDIA H200(**)      | ``h200_2g.35gb``                       | 35GB  (``--gres=gpu-vram:35g``)  | 9.0 (``--gres=min-cuda-cc=90``) | 24             | gpu[49]          | 24            | 4224                      | ``gpu-h200-35g-ia-ellis``, ``gpu-h200-35g-ia``   |
+   NVIDIA H100          | ``h100``                               | 80GB  (``--gres=gpu-vram:80g``)  | 9.0 (``--gres=min-cuda-cc=90``) | 16             | gpu[45-48]       | 4             | 16896                     | ``gpu-h100-80g``                                 |
+   NVIDIA A100          | ``a100``                               | 80GB  (``--gres=gpu-vram:80g``)  | 8.0 (``--gres=min-cuda-cc=80``) | 56             | gpu[11-17,38-44] | 4             | 7936                      | ``gpu-a100-80g``                                 |
+   NVIDIA V100          | ``v100``                               | 32GB  (``--gres=gpu-vram:32g``)  | 7.0 (``--gres=min-cuda-cc=70``) | 40             | gpu[28-37]       | 4             | 5120                      | ``gpu-v100-32g``                                 |
+   NVIDIA V100          | ``v100``                               | 32GB  (``--gres=gpu-vram:32g``)  | 7.0 (``--gres=min-cuda-cc=70``) | 40             | gpu[1-10]        | 4             | 5120                      | ``gpu-v100-32g``                                 |
+   NVIDIA V100          | ``v100``                               | 32GB  (``--gres=gpu-vram:32g``)  | 7.0 (``--gres=min-cuda-cc=70``) | 32             | dgx[3,5-7]       | 8             | 5120                      | ``gpu-v100-32g``                                 |
+   NVIDIA V100          | ``v100``                               | 16GB  (``--gres=gpu-vram:16g``)  | 7.0 (``--gres=min-cuda-cc=70``) | 176            | dgx[1-2,8-27]    | 8             | 5120                      | ``gpu-v100-16g``                                 |
+   AMD MI210            | ``mi210`` with  ``-p gpu-amd``         | 32GB                             |                                 | 2              | gpuamd[1]        | 2             | 7680                      | ``gpu-amd``                                      |
+   AMD MI100            | ``mi100`` with  ``-p gpu-amd``         | 64GB                             |                                 | 1              | gpuamd[1]        | 1             | 6656                      | ``gpu-amd``                                      |
 
-(*) These GPUs have a priority queue for the ellis project, since they were procured for this project. 
-Any job submitted to the short queue might be preempted if a job requiring the resources comes in from the ellis queue. 
-They are not allocated automatcally unless you specifically request a job on their partition.
+To request multiple gres, e.g. both 32GB of memory and compute capability 8.0, use a comma separated list: ``--gres=gpu-vram:32g,min-cuda-cc=80``.
+
+(*) These GPUs have a priority queue for the Ellis project, since they were
+procured for this project. Any job submitted to the short queue might be
+preempted if a job requiring the resources comes in from the Ellis queue.
+
+(**) These GPUs are split from a single GPU with NVIDIA's 
+`Multi-Instance GPU <https://docs.nvidia.com/datacenter/tesla/mig-user-guide/index.html>`__-feature.
diff --git a/triton/ref/slurm.rst b/triton/ref/slurm.rst
@@ -34,7 +34,7 @@
                             ! ``--constraint=localdisk``     ! request nodes that have local disks
 			    ! ``--tmp=nnnG``                 ! Request ``nnn`` GB of :doc:`local disk storage space </triton/usage/localstorage>`
                             ! ``--array=``\ *0-5,7,10-15*    ! Run job multiple times, use variable ``$SLURM_ARRAY_TASK_ID`` to adjust parameters.
-                            ! ``--gres=gpu``                 ! request a GPU, or ``--gres=gpu:``\ *n* for multiple
+                            ! ``--gpus=1``                   ! request a GPU, or ``--gpus=N`` for multiple
                             ! ``--mail-type=``\ *TYPE*       ! notify of events: ``BEGIN``, ``END``, ``FAIL``, ``ALL``, ``REQUEUE`` (not on triton) or ``ALL.`` MUST BE used with ``--mail-user=`` only
                             ! ``--mail-user=``\ *first.last@aalto.fi* ! Aalto email to send the notification about the job. External email addresses doesn't work.
    ``srun``                 ! ``-N`` *N_NODES* hostname    ! Print allocated nodes (from within script)
diff --git a/triton/tut/gpu.rst b/triton/tut/gpu.rst
@@ -6,11 +6,15 @@ GPU computing
 
 .. admonition:: Abstract
 
-   * Request a GPU with the Slurm option ``--gpus=1`` or
-     ``--gres=gpu:1`` (some clusters need ``--partition=gpu`` or similar).
-   * Select a certain type of GPU with e.g. ``--constraint='volta'``
-     (see :doc:`the quick reference for names <../ref/index>`).
-   * Monitor GPU performance with ``sacct -j JOBID -o TRESUsageInAve -p``.
+   * Request a GPU with the Slurm option ``--gpus=1``.
+   * Select a certain type of GPU with e.g. ``--gpus=h200:1``.
+   * Select a GPU with certain amount of memory with e.g.
+     ``--gpus=1 --gres=min-vram:80g``.
+   * Select a GPU with certain CUDA compute capability with e.g.
+     ``--gpus=1 --gres=min-cuda-cc:80``.
+   * See :ref:`the quick reference <available-gpus>` for available GPU names,
+     memory capacities and compute capabilities.
+   * Monitor GPU performance with ``seff JOBID``.
    * You can test out small jobs of 30 minutes or less in the
      ``gpu-debug``-partition (``--partition=gpu-debug``).
    * If you aren't fully sure of how to scale up, contact us
@@ -70,75 +74,92 @@ they generally outperform the best desktop GPUs.
 
 
 
-Reserving resources for GPU programs
-------------------------------------
+Reserving a GPU
+---------------
 
 Slurm keeps track of the GPU resources as generic resources (GRES) or
 trackable resources (TRES). They are basically limited resources that you
 can request in addition to normal resources such as CPUs and RAM.
 
-To request GPUs on Slurm, you should use the ``--gpus=1`` or ``--gres=gpu:1``
--flags.
+To request GPUs on Slurm, you should use the ``--gpus=N``, where ``N``
+is the number of GPUs you wish to request.
+
+For example, ``--gpus=1`` will give you a single GPU.
+
+.. note::
+
+   Most GPU programs cannot utilize more than one GPU at a time. Before
+   trying to reserve multiple GPUs you should verify that your code
+   can utilize them.
+
 
 Choosing a specific type of GPU
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 In most cases you will want to choose a GPU that suits your specific use case.
 
-There are three ways you can use to choose the GPU type:
+You can use the syntax ``--gpus=GPU_TYPE:1`` where ``GPU_TYPE`` is a name
+chosen by the admins for the GPU.
+
+For example, ``--gpus=h200:1`` would give you a H100 card.
 
-1. All compute nodes with GPUs are separated into partitions based on their GPU
-   architectures.
+See the :ref:`available GPUs reference <available-gpus>` for more information on
+available GPUs.
 
-   Thus you can choose the GPU type by limiting your job to the partitions that
-   have GPUs that you want to use with ``--partition=GPU_PARTITION``, where
-   ``GPU_PARTITION`` is the name of the partition. You can specify multiple
-   partition, separated by commas.
 
-   For example ``--partition=gpu-a100-80g,gpu-h100-80g`` would give you a
-   A100 or H100 GPU.
+Choosing a GPU based on available VRAM
+--------------------------------------
 
-2. You can restrict yourself to a certain type of GPU card by using
-   using the ``--constraint`` option.  For example, to restrict the submission to
-   Ampere generation GPUs only you can use ``--constraint='ampere'``.
+Different GPUs have different amounts of VRAM (video random access memory)
+available. If you're running a program that requires some minimum amount of
+GPU VRAM memory (e.g. running an LLM AI model), you can choose only those
+GPUs that have enough memory.
 
-   For choosing between multiple generations, you can use the ``|``-character
-   between generations. For example, if you want to restrict the submission
-   Volta or Ampere generations you can use ``--constraint='volta|ampere'``.
-   Remember to use the quotes since ``|`` is the shell pipe.
+To specify the amount of memory you require, use syntax
+``--gres=min-vram:NNg``, where ``NN`` is the amount of VRAM needed.
 
-3. You can use the syntax ``--gpus=GPU_TYPE:1`` (or ``--gres=gpu:GPU_TYPE:1``),
-   where ``GPU_TYPE`` is a name chosen by the admins for the GPU.
+As with any GPU request, you'll need to specify the amount of GPUs you want
+with ``--gpus=N`` as well.
 
-   For example, ``--gpus=v100:1`` would give you a V100 card.
+For example, specifying ``--gpus=1`` and ``--gres=min-vram:40g`` would give
+you a single GPU with at least 40GB of memory.
 
 See the :ref:`available GPUs reference <available-gpus>` for more information on
-available partitions and feature names.
+available GPUs.
 
-In the cluster you can run ``slurm features`` or
-``sinfo -o '%50N %18F %26f %30G'`` to see what GPU resources are available.
 
+Choosing a GPU based on CUDA compute capability
+-----------------------------------------------
 
+Different GPUs have different chip architectures that support different levels
+of CUDA compute capability. CUDA compute capability represents various different
+hardware features that the GPU chips are capable of implementing (bfloat16
+support, lower precision floating point arithmetic etc.).
 
-Reserving more than one GPU
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sometimes codes and libraries require GPUs that support some minimum level of
+CUDA compute capability. In these cases you'll want to choose GPUs based on their
+compute capability.
 
-You can request more than one GPU with ``--gpus=G``, where ``G`` is
-the number of the requested GPUs.
+To specify the minimum compute capability, use syntax ``--gres=min-cuda-cc:CC``,
+where ``CC`` is the compute capability as a number (so compute capability 3.5
+would be 35 and compute capability 8.0 would be 80).
 
-.. note::
+As with any GPU request, you'll need to specify the amount of GPUs you want
+with ``--gpus=N`` as well.
+
+For example, specifying ``--gpus=1`` and ``--gres=min-cuda-cc:80`` would give
+you a single GPU with minimum compute capabilty support of 8.0.
+
+See the :ref:`available GPUs reference <available-gpus>` for more information on
+available GPUs.
 
-   Most GPU programs cannot utilize more than one GPU at a time. Before
-   trying to reserve multiple GPUs you should verify that your code
-   can utilize them.
 
 Reserving a GPU from the debug queue
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
 There is a ``gpu-debug``-partition that you can use to run short jobs
 (30 minutes or less) for quick tests and debugging. Use
-``--partition=gpu-debug`` for this.
+``--partition=gpu-debug`` to ask for a GPU from this partition.
 
 
 Running an example program that utilizes GPU
