Changed TORQUE to PBS (#491)

Renamed TORQUE scheduler related classes, objects, templates, etc to PBS in code and documentation.

* changed torque to pbs

* fixed isort error

* changed torque to pbs

* rename PBSScheduler

* rename PBSScheduler

* rename PBSScheduler

* Add changelog entry.

* Rename Torque -> PBS in more places.

* Update contributors.yaml

* Added back deprecated class for DefaultTorqueEnvironment.

* Remove extra line in contributors.yaml.

* Fix import.

Co-authored-by: Bradley Dice <[email protected]>

changelog.txt

@@ -17,6 +17,11 @@ Added
 - Documentation for all directives (#480).
 - Defined validators for the ``fork`` directive (#480).
 
+Changed
++++++++
+
+- Renamed TorqueEnvironment and related classes to PBSEnvironment (#491).
+
 Fixed
 +++++
 
@@ -82,7 +87,7 @@ Changed
 - Command line interface always uses ``--job-id`` instead of ``--jobid`` (#363, #386).
 - ``CPUEnvironment`` and ``GPUEnvironment`` classes are deprecated (#381).
 - Docstrings are now written in `numpydoc style <https://numpydoc.readthedocs.io/en/latest/format.html>`__ (#392).
-- Default environment for the University of Minnesota Mangi cluster changed from SLURM to Torque (#393).
+- Default environment for the University of Minnesota Mangi cluster changed from Torque to SLURM (#393).
 - Run commands are evaluted lazily (#70, #396).
 - Deprecated method ``export_job_statuses`` (#402).
 - Improved internal caching of scheduler status (#410).

contributors.yaml

@@ -142,4 +142,9 @@ contributors:
     family-names: Gnabro
     given-names: Ange-Desire
     affiliation: ""
+  -
+    family-names: Zhao
+    given-names: Charlotte
+    orcid: "https://orcid.org/0000-0003-4915-1064"
+    affiliation: "University of Michigan"
 ...

doc/api.rst

@@ -187,7 +187,7 @@ Compute Environments
 .. autoclass:: flow.environment.SimpleSchedulerEnvironment
     :members:
 
-.. autoclass:: flow.environment.TorqueEnvironment
+.. autoclass:: flow.environment.PBSEnvironment
     :members:
 
 .. autoclass:: flow.environment.SlurmEnvironment
@@ -219,13 +219,13 @@ Schedulers
 .. autoclass:: flow.scheduling.lsf.LSFScheduler
     :members:
 
-.. autoclass:: flow.scheduling.simple_scheduler.SimpleScheduler
+.. autoclass:: flow.scheduling.pbs.PBSScheduler
     :members:
 
-.. autoclass:: flow.scheduling.slurm.SlurmScheduler
+.. autoclass:: flow.scheduling.simple_scheduler.SimpleScheduler
     :members:
 
-.. autoclass:: flow.scheduling.torque.TorqueScheduler
+.. autoclass:: flow.scheduling.slurm.SlurmScheduler
     :members:
 
 Error Classes

doc/supported_environments.rst

@@ -18,9 +18,9 @@ The package currently ships with scheduler support for:
 
 .. toctree::
 
-   supported_environments/slurm
-   supported_environments/torque
    supported_environments/lsf
+   supported_environments/pbs
+   supported_environments/slurm
 
 Any supercomputing system utilizing these schedulers is supported out of the box.
 In addition, the package provides specialized submission templates for the following environments:

doc/supported_environments/pbs.rst

@@ -0,0 +1,12 @@
+.. _pbs:
+
+PBS
+===
+
+`Link to qsub man page <https://linux.die.net/man/1/qsub-torque>`_
+
+.. autoclass:: flow.environment.DefaultPBSEnvironment
+
+.. literalinclude:: ../../flow/templates/pbs.sh
+   :language: jinja
+   :caption: pbs.sh

flow/environment.py

@@ -16,6 +16,7 @@
 import socket
 from functools import lru_cache
 
+from deprecation import deprecated
 from signac.common import config
 
 from .directives import (
@@ -34,10 +35,11 @@
 from .scheduling.base import JobStatus
 from .scheduling.fake_scheduler import FakeScheduler
 from .scheduling.lsf import LSFScheduler
+from .scheduling.pbs import PBSScheduler
 from .scheduling.simple_scheduler import SimpleScheduler
 from .scheduling.slurm import SlurmScheduler
-from .scheduling.torque import TorqueScheduler
 from .util import config as flow_config
+from .version import __version__
 
 logger = logging.getLogger(__name__)
 
@@ -391,11 +393,11 @@ class SimpleSchedulerEnvironment(ComputeEnvironment):
     template = "simple_scheduler.sh"
 
 
-class TorqueEnvironment(ComputeEnvironment):
-    """An environment with TORQUE scheduler."""
+class PBSEnvironment(ComputeEnvironment):
+    """An environment with PBS scheduler."""
 
-    scheduler_type = TorqueScheduler
-    template = "torque.sh"
+    scheduler_type = PBSScheduler
+    template = "pbs.sh"
 
 
 class SlurmEnvironment(ComputeEnvironment):
@@ -420,8 +422,8 @@ class NodesEnvironment(ComputeEnvironment):
     """
 
 
-class DefaultTorqueEnvironment(NodesEnvironment, TorqueEnvironment):
-    """Default environment for clusters with a TORQUE scheduler."""
+class DefaultPBSEnvironment(NodesEnvironment, PBSEnvironment):
+    """Default environment for clusters with a PBS scheduler."""
 
     @classmethod
     def add_args(cls, parser):
@@ -450,6 +452,16 @@ def add_args(cls, parser):
         )
 
 
+@deprecated(
+    deprecated_in="0.14",
+    removed_in="0.16",
+    current_version=__version__,
+    details="DefaultTorqueEnvironment has been renamed to DefaultPBSEnvironment",
+)
+class DefaultTorqueEnvironment(DefaultPBSEnvironment):  # noqa: D101
+    pass
+
+
 class DefaultSlurmEnvironment(NodesEnvironment, SlurmEnvironment):
     """Default environment for clusters with a SLURM scheduler."""
 

flow/scheduling/torque.py → flow/scheduling/pbs.py

@@ -1,9 +1,9 @@
 # Copyright (c) 2018 The Regents of the University of Michigan
 # All rights reserved.
 # This software is licensed under the BSD 3-Clause License.
-"""Implementation of the scheduling system for TORQUE schedulers.
+"""Implementation of the scheduling system for PBS schedulers.
 
-This module implements the Scheduler and ClusterJob classes for TORQUE.
+This module implements the Scheduler and ClusterJob classes for PBS.
 """
 import errno
 import getpass
@@ -18,7 +18,7 @@
 
 
 def _fetch(user=None):
-    """Fetch the cluster job status information from the TORQUE scheduler.
+    """Fetch the cluster job status information from the PBS scheduler.
 
     Parameters
     ----------
@@ -28,8 +28,8 @@ def _fetch(user=None):
 
     Yields
     ------
-    :class:`~.TorqueJob`
-        Torque cluster job.
+    :class:`~.PBSJob`
+        PBS cluster job.
 
     """
     if user is None:
@@ -52,13 +52,13 @@ def _fetch(user=None):
             raise
     except OSError as error:
         if error.errno == errno.ENOENT:
-            raise RuntimeError("Torque not available.")
+            raise RuntimeError("PBS not available.")
         else:
             raise error
 
 
-class TorqueJob(ClusterJob):
-    """Implementation of the abstract ClusterJob class for TORQUE schedulers."""
+class PBSJob(ClusterJob):
+    """Implementation of the abstract ClusterJob class for PBS schedulers."""
 
     def __init__(self, node):
         self.node = node
@@ -80,10 +80,10 @@ def status(self):
         return JobStatus.registered
 
 
-class TorqueScheduler(Scheduler):
-    r"""Implementation of the abstract Scheduler class for TORQUE schedulers.
+class PBSScheduler(Scheduler):
+    r"""Implementation of the abstract Scheduler class for PBS schedulers.
 
-    This class can submit cluster jobs to a TORQUE scheduler and query their
+    This class can submit cluster jobs to a PBS scheduler and query their
     current status.
 
     Parameters
@@ -95,7 +95,7 @@ class TorqueScheduler(Scheduler):
 
     """
 
-    # The standard command used to submit jobs to the TORQUE scheduler.
+    # The standard command used to submit jobs to the PBS scheduler.
     submit_cmd = ["qsub"]
 
     def __init__(self, user=None):
@@ -106,7 +106,7 @@ def jobs(self):
         self._prevent_dos()
         nodes = _fetch(user=self.user)
         for node in nodes.findall("Job"):
-            yield TorqueJob(node)
+            yield PBSJob(node)
 
     def submit(
         self, script, *, after=None, hold=False, pretend=False, flags=None, **kwargs
@@ -161,7 +161,7 @@ def submit(
 
     @classmethod
     def is_present(cls):
-        """Return True if a TORQUE scheduler is detected."""
+        """Return True if a PBS scheduler is detected."""
         try:
             subprocess.check_output(["qsub", "--version"], stderr=subprocess.STDOUT)
         except subprocess.CalledProcessError: