Rename ClusterEnvironment.creates_processes (#10106)

Co-authored-by: tchaton <[email protected]>

Author: awaelchli

CHANGELOG.md

@@ -435,6 +435,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Deprecated passing `resume_from_checkpoint` to the `Trainer` constructor in favor of `trainer.fit(ckpt_path=)` ([#10061](https://github.com/PyTorchLightning/pytorch-lightning/pull/10061))
 
 
+- Deprecated `ClusterEnvironment.creates_children()` in favor of `ClusterEnvironment.creates_processes_externally` (property) ([#10106](https://github.com/PyTorchLightning/pytorch-lightning/pull/10106))
+
+
 ### Removed
 
 - Removed deprecated `metrics` ([#8586](https://github.com/PyTorchLightning/pytorch-lightning/pull/8586/))

docs/source/clouds/cluster.rst

@@ -290,8 +290,9 @@ and node rank (node id). Here is an example of a custom
 
 
     class MyClusterEnvironment(ClusterEnvironment):
-        def creates_children(self) -> bool:
-            # return True if the cluster is managed (you don't launch processes yourself)
+        @property
+        def creates_processes_externally(self) -> bool:
+            """Return True if the cluster is managed (you don't launch processes yourself)"""
             return True
 
         def world_size(self) -> int:

pytorch_lightning/plugins/environments/cluster_environment.py

@@ -13,14 +13,30 @@
 # limitations under the License.
 from abc import ABC, abstractmethod
 
+from pytorch_lightning.utilities import rank_zero_deprecation
+
 
 class ClusterEnvironment(ABC):
     """Specification of a cluster environment."""
 
+    @property
     @abstractmethod
-    def creates_children(self) -> bool:
+    def creates_processes_externally(self) -> bool:
         """Whether the environment creates the subprocesses or not."""
 
+    def creates_children(self) -> bool:
+        """Whether the environment creates the subprocesses or not.
+
+        .. deprecated:: v1.5
+            This method was deprecated in v1.5 and will be removed in v1.6. Use the property
+            :attr:`creates_processes_externally` instead.
+        """
+        rank_zero_deprecation(
+            f"`{self.__class__.__name__}.creates_children()` was deprecated in v1.5 and will be removed in v1.6."
+            " Use the property :attr:`creates_processes_externally` instead."
+        )
+        return self.creates_processes_externally
+
     @abstractmethod
     def master_address(self) -> str:
         """The master address through which all processes connect and communicate."""

pytorch_lightning/plugins/environments/kubeflow_environment.py

@@ -35,7 +35,8 @@ def is_using_kubeflow() -> bool:
         excluded_env_vars = ("GROUP_RANK", "LOCAL_RANK", "LOCAL_WORLD_SIZE")
         return all(v in os.environ for v in required_env_vars) and not any(v in os.environ for v in excluded_env_vars)
 
-    def creates_children(self) -> bool:
+    @property
+    def creates_processes_externally(self) -> bool:
         return True
 
     def master_address(self) -> str:

pytorch_lightning/plugins/environments/lightning_environment.py

@@ -40,7 +40,8 @@ def __init__(self):
         self._global_rank: int = 0
         self._world_size: int = 1
 
-    def creates_children(self) -> bool:
+    @property
+    def creates_processes_externally(self) -> bool:
         """Returns whether the cluster creates the processes or not.
 
         If at least :code:`LOCAL_RANK` is available as environment variable, Lightning assumes the user acts as the

pytorch_lightning/plugins/environments/lsf_environment.py

@@ -52,7 +52,8 @@ def is_using_lsf() -> bool:
         required_env_vars = ("LSB_JOBID", "LSB_HOSTS", "JSM_NAMESPACE_LOCAL_RANK", "JSM_NAMESPACE_SIZE")
         return all(v in os.environ for v in required_env_vars)
 
-    def creates_children(self) -> bool:
+    @property
+    def creates_processes_externally(self) -> bool:
         return True
 
     def master_address(self):

pytorch_lightning/plugins/environments/slurm_environment.py

@@ -24,7 +24,8 @@
 class SLURMEnvironment(ClusterEnvironment):
     """Cluster environment for training on a cluster managed by SLURM."""
 
-    def creates_children(self) -> bool:
+    @property
+    def creates_processes_externally(self) -> bool:
         return True
 
     def master_address(self) -> str:

pytorch_lightning/plugins/environments/torchelastic_environment.py

@@ -31,7 +31,8 @@ def is_using_torchelastic() -> bool:
         required_env_vars = ("RANK", "GROUP_RANK", "LOCAL_RANK", "LOCAL_WORLD_SIZE")
         return all(v in os.environ for v in required_env_vars)
 
-    def creates_children(self) -> bool:
+    @property
+    def creates_processes_externally(self) -> bool:
         return True
 
     def master_address(self) -> str:

pytorch_lightning/plugins/training_type/ddp.py

@@ -177,7 +177,7 @@ def _is_single_process_single_device(self) -> bool:
 
     def setup_environment(self) -> None:
         # start the other scripts
-        if not self.cluster_environment.creates_children():
+        if not self.cluster_environment.creates_processes_externally:
             self._call_children_scripts()
 
         # set the task idx
@@ -277,7 +277,7 @@ def _check_can_spawn_children(self):
             raise RuntimeError(
                 "Lightning attempted to launch new distributed processes with `local_rank > 0`. This should not happen."
                 " Possible reasons: 1) LOCAL_RANK environment variable was incorrectly modified by the user,"
-                " 2) `ClusterEnvironment.creates_children()` incorrectly implemented."
+                " 2) `ClusterEnvironment.creates_processes_externally` incorrectly implemented."
             )
 
     def set_world_ranks(self) -> None:

tests/accelerators/test_accelerator_connector.py

@@ -369,7 +369,8 @@ class CustomCluster(LightningEnvironment):
         def master_address(self):
             return "asdf"
 
-        def creates_children(self) -> bool:
+        @property
+        def creates_processes_externally(self) -> bool:
             return True
 
     trainer = Trainer(