Remove legacy device arguments in Trainer (#16171)

Author: awaelchli

docs/source-pytorch/common/trainer.rst

@@ -492,8 +492,6 @@ devices
 ^^^^^^^
 
 Number of devices to train on (``int``), which devices to train on (``list`` or ``str``), or ``"auto"``.
-It will be mapped to either ``gpus``, ``tpu_cores``, ``num_processes`` or ``ipus``,
-based on the accelerator type (``"cpu", "gpu", "tpu", "ipu", "auto"``).
 
 .. code-block:: python
 
@@ -624,56 +622,6 @@ impact to subsequent runs. These are the changes enabled:
 - Disables the Tuner.
 - If using the CLI, the configuration file is not saved.
 
-.. _gpus:
-
-gpus
-^^^^
-
-.. warning:: ``gpus=x`` has been deprecated in v1.7 and will be removed in v2.0.
-    Please use ``accelerator='gpu'`` and ``devices=x`` instead.
-
-.. raw:: html
-
-    <video width="50%" max-width="400px" controls
-    poster="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/pl_docs/trainer_flags/thumb/gpus.jpg"
-    src="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/pl_docs/trainer_flags/gpus.mp4"></video>
-
-|
-
-- Number of GPUs to train on (int)
-- or which GPUs to train on (list)
-- can handle strings
-
-.. testcode::
-
-    # default used by the Trainer (ie: train on CPU)
-    trainer = Trainer(gpus=None)
-
-    # equivalent
-    trainer = Trainer(gpus=0)
-
-Example::
-
-    # int: train on 2 gpus
-    trainer = Trainer(gpus=2)
-
-    # list: train on GPUs 1, 4 (by bus ordering)
-    trainer = Trainer(gpus=[1, 4])
-    trainer = Trainer(gpus='1, 4') # equivalent
-
-    # -1: train on all gpus
-    trainer = Trainer(gpus=-1)
-    trainer = Trainer(gpus='-1') # equivalent
-
-    # combine with num_nodes to train on multiple GPUs across nodes
-    # uses 8 gpus in total
-    trainer = Trainer(gpus=2, num_nodes=4)
-
-    # train only on GPUs 1 and 4 across nodes
-    trainer = Trainer(gpus=[1, 4], num_nodes=4)
-
-See Also:
-    - :ref:`Multi GPU Training <multi_gpu>`
 
 gradient_clip_val
 ^^^^^^^^^^^^^^^^^
@@ -951,33 +899,6 @@ Number of GPU nodes for distributed training.
     # to train on 8 nodes
     trainer = Trainer(num_nodes=8)
 
-num_processes
-^^^^^^^^^^^^^
-
-.. warning:: ``num_processes=x`` has been deprecated in v1.7 and will be removed in v2.0.
-    Please use ``accelerator='cpu'`` and ``devices=x`` instead.
-
-.. raw:: html
-
-    <video width="50%" max-width="400px" controls
-    poster="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/pl_docs/trainer_flags/thumb/num_processes.jpg"
-    src="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/pl_docs/trainer_flags/num_processes.mp4"></video>
-
-|
-
-Number of processes to train with. Automatically set to the number of GPUs
-when using ``strategy="ddp"``. Set to a number greater than 1 when
-using ``accelerator="cpu"`` and ``strategy="ddp"`` to mimic distributed training on a
-machine without GPUs. This is useful for debugging, but **will not** provide
-any speedup, since single-process Torch already makes efficient use of multiple
-CPUs. While it would typically spawns subprocesses for training, setting
-``num_nodes > 1`` and keeping ``num_processes = 1`` runs training in the main
-process.
-
-.. testcode::
-
-    # Simulate DDP for debugging on your GPU-less laptop
-    trainer = Trainer(accelerator="cpu", strategy="ddp", num_processes=2)
 
 num_sanity_val_steps
 ^^^^^^^^^^^^^^^^^^^^
@@ -1320,65 +1241,6 @@ track_grad_norm
     # track the 2-norm
     trainer = Trainer(track_grad_norm=2)
 
-.. _tpu_cores:
-
-tpu_cores
-^^^^^^^^^
-
-.. warning:: ``tpu_cores=x`` has been deprecated in v1.7 and will be removed in v2.0.
-    Please use ``accelerator='tpu'`` and ``devices=x`` instead.
-
-.. raw:: html
-
-    <video width="50%" max-width="400px" controls
-    poster="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/pl_docs/trainer_flags/thumb/tpu_cores.jpg"
-    src="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/pl_docs/trainer_flags/tpu_cores.mp4"></video>
-
-|
-
-- How many TPU cores to train on (1 or 8).
-- Which TPU core to train on [1-8]
-
-A single TPU v2 or v3 has 8 cores. A TPU pod has
-up to 2048 cores. A slice of a POD means you get as many cores
-as you request.
-
-Your effective batch size is batch_size * total tpu cores.
-
-This parameter can be either 1 or 8.
-
-Example::
-
-    # your_trainer_file.py
-
-    # default used by the Trainer (ie: train on CPU)
-    trainer = Trainer(tpu_cores=None)
-
-    # int: train on a single core
-    trainer = Trainer(tpu_cores=1)
-
-    # list: train on a single selected core
-    trainer = Trainer(tpu_cores=[2])
-
-    # int: train on all cores few cores
-    trainer = Trainer(tpu_cores=8)
-
-    # for 8+ cores must submit via xla script with
-    # a max of 8 cores specified. The XLA script
-    # will duplicate script onto each TPU in the POD
-    trainer = Trainer(tpu_cores=8)
-
-To train on more than 8 cores (ie: a POD),
-submit this script using the xla_dist script.
-
-Example::
-
-    python -m torch_xla.distributed.xla_dist
-    --tpu=$TPU_POD_NAME
-    --conda-env=torch-xla-nightly
-    --env=XLA_USE_BF16=1
-    -- python your_trainer_file.py
-
 
 val_check_interval
 ^^^^^^^^^^^^^^^^^^

src/lightning_fabric/accelerators/tpu.py

@@ -41,7 +41,7 @@ def teardown(self) -> None:
     @staticmethod
     def parse_devices(devices: Union[int, str, List[int]]) -> Optional[Union[int, List[int]]]:
         """Accelerator device parsing logic."""
-        return _parse_tpu_cores(devices)
+        return _parse_tpu_devices(devices)
 
     @staticmethod
     def get_parallel_devices(devices: Union[int, List[int]]) -> List[int]:
@@ -128,13 +128,13 @@ def _tpu_distributed() -> bool:
     return xm.xrt_world_size() > 1
 
 
-def _parse_tpu_cores(tpu_cores: Optional[Union[int, str, List[int]]]) -> Optional[Union[int, List[int]]]:
+def _parse_tpu_devices(devices: Optional[Union[int, str, List[int]]]) -> Optional[Union[int, List[int]]]:
     """
-    Parses the tpu_cores given in the format as accepted by the
-    :class:`~pytorch_lightning.trainer.Trainer`.
+    Parses the TPU devices given in the format as accepted by the
+    :class:`~pytorch_lightning.trainer.Trainer` and :class:`~lightning_fabric.Fabric`.
 
     Args:
-        tpu_cores: An int of 1 or string '1' indicates that 1 core with multi-processing should be used
+        devices: An int of 1 or string '1' indicates that 1 core with multi-processing should be used
             An int 8 or string '8' indicates that all 8 cores with multi-processing should be used
             A list of ints or a strings containing a list of comma separated integers
             indicates the specific TPU core to use.
@@ -143,37 +143,37 @@ def _parse_tpu_cores(tpu_cores: Optional[Union[int, str, List[int]]]) -> Optiona
         A list of tpu_cores to be used or ``None`` if no TPU cores were requested
 
     Raises:
-        MisconfigurationException:
-            If TPU cores aren't 1, 8 or [<1-8>]
+        TypeError:
+            If TPU devices aren't 1, 8 or [<1-8>]
     """
-    _check_data_type(tpu_cores)
+    _check_data_type(devices)
 
-    if isinstance(tpu_cores, str):
-        tpu_cores = _parse_tpu_cores_str(tpu_cores.strip())
+    if isinstance(devices, str):
+        devices = _parse_tpu_devices_str(devices.strip())
 
-    if not _tpu_cores_valid(tpu_cores):
-        raise TypeError("`tpu_cores` can only be 1, 8 or [<1-8>]")
+    if not _tpu_devices_valid(devices):
+        raise TypeError("`devices` can only be 1, 8 or [<1-8>] for TPUs.")
 
-    return tpu_cores
+    return devices
 
 
-def _tpu_cores_valid(tpu_cores: Any) -> bool:
+def _tpu_devices_valid(devices: Any) -> bool:
     # allow 1 or 8 cores
-    if tpu_cores in (1, 8, None):
+    if devices in (1, 8, None):
         return True
 
     # allow picking 1 of 8 indexes
-    if isinstance(tpu_cores, (list, tuple, set)):
-        has_1_tpu_idx = len(tpu_cores) == 1
-        is_valid_tpu_idx = 1 <= list(tpu_cores)[0] <= 8
+    if isinstance(devices, (list, tuple, set)):
+        has_1_tpu_idx = len(devices) == 1
+        is_valid_tpu_idx = 1 <= list(devices)[0] <= 8
 
         is_valid_tpu_core_choice = has_1_tpu_idx and is_valid_tpu_idx
         return is_valid_tpu_core_choice
 
     return False
 
 
-def _parse_tpu_cores_str(tpu_cores: str) -> Union[int, List[int]]:
-    if tpu_cores in ("1", "8"):
-        return int(tpu_cores)
-    return [int(x.strip()) for x in tpu_cores.split(",") if len(x) > 0]
+def _parse_tpu_devices_str(devices: str) -> Union[int, List[int]]:
+    if devices in ("1", "8"):
+        return int(devices)
+    return [int(x.strip()) for x in devices.split(",") if len(x) > 0]

src/pytorch_lightning/CHANGELOG.md

@@ -18,6 +18,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
   * Removed the `pytorch_lightning.utilities.enums.AMPType` enum
   * Removed the `DeepSpeedPrecisionPlugin(amp_type=..., amp_level=...)` arguments
 
+- Removed legacy device arguments in Trainer ([#16171](https://github.com/Lightning-AI/lightning/pull/16171))
+  * Removed the `Trainer(gpus=...)` argument
+  * Removed the `Trainer(tpu_cores=...)` argument
+  * Removed the `Trainer(ipus=...)` argument
+  * Removed the `Trainer(num_processes=...)` argument
+
 
 ## [unreleased] - 202Y-MM-DD
 

src/pytorch_lightning/accelerators/tpu.py

@@ -15,7 +15,7 @@
 
 import torch
 
-from lightning_fabric.accelerators.tpu import _parse_tpu_cores, _XLA_AVAILABLE
+from lightning_fabric.accelerators.tpu import _parse_tpu_devices, _XLA_AVAILABLE
 from lightning_fabric.accelerators.tpu import TPUAccelerator as LiteTPUAccelerator
 from lightning_fabric.utilities.types import _DEVICE
 from pytorch_lightning.accelerators.accelerator import Accelerator
@@ -58,7 +58,7 @@ def teardown(self) -> None:
     @staticmethod
     def parse_devices(devices: Union[int, str, List[int]]) -> Optional[Union[int, List[int]]]:
         """Accelerator device parsing logic."""
-        return _parse_tpu_cores(devices)
+        return _parse_tpu_devices(devices)
 
     @staticmethod
     def get_parallel_devices(devices: Union[int, List[int]]) -> List[int]: