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/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/trainer/connectors/accelerator_connector.py

@@ -99,10 +99,6 @@ def __init__(
         replace_sampler_ddp: bool = True,
         deterministic: Optional[Union[bool, _LITERAL_WARN]] = False,
         auto_select_gpus: Optional[bool] = None,  # TODO: Remove in v1.10.0
-        num_processes: Optional[int] = None,  # deprecated
-        tpu_cores: Optional[Union[List[int], str, int]] = None,  # deprecated
-        ipus: Optional[int] = None,  # deprecated
-        gpus: Optional[Union[List[int], str, int]] = None,  # deprecated
     ) -> None:
         """The AcceleratorConnector parses several Trainer arguments and instantiates the Strategy including other
         components such as the Accelerator and Precision plugins.
@@ -157,7 +153,6 @@ def __init__(
 
         # Raise an exception if there are conflicts between flags
         # Set each valid flag to `self._x_flag` after validation
-        # For devices: Assign gpus, ipus, etc. to the accelerator flag and devices flag
         self._strategy_flag: Optional[Union[Strategy, str]] = None
         self._accelerator_flag: Optional[Union[Accelerator, str]] = None
         self._precision_flag: Optional[Union[int, str]] = None
@@ -177,9 +172,6 @@ def __init__(
             plugins=plugins,
             sync_batchnorm=sync_batchnorm,
         )
-        self._check_device_config_and_set_final_flags(
-            devices=devices, num_nodes=num_nodes, num_processes=num_processes, gpus=gpus, ipus=ipus, tpu_cores=tpu_cores
-        )
         # 2. Instantiate Accelerator
         self._set_accelerator_if_ipu_strategy_is_passed()
 
@@ -189,6 +181,7 @@ def __init__(
         elif self._accelerator_flag == "gpu":
             self._accelerator_flag = self._choose_gpu_accelerator_backend()
 
+        self._check_device_config_and_set_final_flags(devices=devices, num_nodes=num_nodes)
         self._set_parallel_devices_and_init_accelerator()
 
         # 3. Instantiate ClusterEnvironment
@@ -362,10 +355,6 @@ def _check_device_config_and_set_final_flags(
         self,
         devices: Optional[Union[List[int], str, int]],
         num_nodes: int,
-        num_processes: Optional[int],
-        gpus: Optional[Union[List[int], str, int]],
-        ipus: Optional[int],
-        tpu_cores: Optional[Union[List[int], str, int]],
     ) -> None:
         self._num_nodes_flag = int(num_nodes) if num_nodes is not None else 1
         self._devices_flag = devices
@@ -381,76 +370,12 @@ def _check_device_config_and_set_final_flags(
                 f" using {accelerator_name} accelerator."
             )
 
-        # TODO: Delete this method when num_processes, gpus, ipus and tpu_cores gets removed
-        self._map_deprecated_devices_specific_info_to_accelerator_and_device_flag(
-            devices, num_processes, gpus, ipus, tpu_cores
-        )
-
         if self._devices_flag == "auto" and self._accelerator_flag is None:
             raise MisconfigurationException(
                 f"You passed `devices={devices}` but haven't specified"
                 " `accelerator=('auto'|'tpu'|'gpu'|'ipu'|'cpu'|'hpu'|'mps')` for the devices mapping."
             )
 
-    def _map_deprecated_devices_specific_info_to_accelerator_and_device_flag(
-        self,
-        devices: Optional[Union[List[int], str, int]],
-        num_processes: Optional[int],
-        gpus: Optional[Union[List[int], str, int]],
-        ipus: Optional[int],
-        tpu_cores: Optional[Union[List[int], str, int]],
-    ) -> None:
-        """Emit deprecation warnings for num_processes, gpus, ipus, tpu_cores and set the `devices_flag` and
-        `accelerator_flag`."""
-        if num_processes is not None:
-            rank_zero_deprecation(
-                f"Setting `Trainer(num_processes={num_processes})` is deprecated in v1.7 and will be removed"
-                f" in v2.0. Please use `Trainer(accelerator='cpu', devices={num_processes})` instead."
-            )
-        if gpus is not None:
-            rank_zero_deprecation(
-                f"Setting `Trainer(gpus={gpus!r})` is deprecated in v1.7 and will be removed"
-                f" in v2.0. Please use `Trainer(accelerator='gpu', devices={gpus!r})` instead."
-            )
-        if tpu_cores is not None:
-            rank_zero_deprecation(
-                f"Setting `Trainer(tpu_cores={tpu_cores!r})` is deprecated in v1.7 and will be removed"
-                f" in v2.0. Please use `Trainer(accelerator='tpu', devices={tpu_cores!r})` instead."
-            )
-        if ipus is not None:
-            rank_zero_deprecation(
-                f"Setting `Trainer(ipus={ipus})` is deprecated in v1.7 and will be removed"
-                f" in v2.0. Please use `Trainer(accelerator='ipu', devices={ipus})` instead."
-            )
-        self._gpus: Optional[Union[List[int], str, int]] = gpus
-        self._tpu_cores: Optional[Union[List[int], str, int]] = tpu_cores
-        deprecated_devices_specific_flag = num_processes or gpus or ipus or tpu_cores
-        if deprecated_devices_specific_flag and deprecated_devices_specific_flag not in ([], 0, "0"):
-            if devices:
-                # TODO improve error message
-                rank_zero_warn(
-                    f"The flag `devices={devices}` will be ignored, "
-                    f"instead the device specific number {deprecated_devices_specific_flag} will be used"
-                )
-
-            if [(num_processes is not None), (gpus is not None), (ipus is not None), (tpu_cores is not None)].count(
-                True
-            ) > 1:
-                # TODO: improve error message
-                rank_zero_warn("more than one device specific flag has been set")
-            self._devices_flag = deprecated_devices_specific_flag
-
-            if self._accelerator_flag is None:
-                # set accelerator type based on num_processes, gpus, ipus, tpu_cores
-                if ipus:
-                    self._accelerator_flag = "ipu"
-                if tpu_cores:
-                    self._accelerator_flag = "tpu"
-                if gpus:
-                    self._accelerator_flag = "cuda"
-                if num_processes:
-                    self._accelerator_flag = "cpu"
-
     def _set_accelerator_if_ipu_strategy_is_passed(self) -> None:
         # current logic only apply to object config
         # TODO this logic should apply to both str and object config
@@ -503,12 +428,7 @@ def _set_parallel_devices_and_init_accelerator(self) -> None:
             )
 
         self._set_devices_flag_if_auto_passed()
-
-        self._gpus = self._devices_flag if not self._gpus else self._gpus
-        self._tpu_cores = self._devices_flag if not self._tpu_cores else self._tpu_cores
-
         self._set_devices_flag_if_auto_select_gpus_passed()
-
         self._devices_flag = accelerator_cls.parse_devices(self._devices_flag)
         if not self._parallel_devices:
             self._parallel_devices = accelerator_cls.get_parallel_devices(self._devices_flag)
@@ -523,9 +443,13 @@ def _set_devices_flag_if_auto_select_gpus_passed(self) -> None:
                 "The Trainer argument `auto_select_gpus` has been deprecated in v1.9.0 and will be removed in v1.10.0."
                 " Please use the function `pytorch_lightning.accelerators.find_usable_cuda_devices` instead."
             )
-        if self._auto_select_gpus and isinstance(self._gpus, int) and isinstance(self.accelerator, CUDAAccelerator):
+        if (
+            self._auto_select_gpus
+            and isinstance(self._devices_flag, int)
+            and isinstance(self.accelerator, CUDAAccelerator)
+        ):
             self._devices_flag = pick_multiple_gpus(
-                self._gpus,
+                self._devices_flag,
                 # we already show a deprecation message when user sets Trainer(auto_select_gpus=...)
                 _show_deprecation=False,
             )