radical.orbit 0.2.0__py3-none-any.whl

radical/orbit/__init__.py

@@ -0,0 +1,61 @@
+
+# ── Public client surface — bind these BEFORE the plugin imports ─────────────
+
+from .plugin_base           import Plugin  # noqa: F401
+from .plugin_session_base   import PluginSession  # noqa: F401
+from .ui_schema             import (UIConfig, UIForm, UIField,  # noqa: F401
+                                    UIMonitor, UINotifications,
+                                    ui_config_to_dict)
+
+from .service           import EndpointService  # noqa: F401
+from .bridge            import Bridge  # noqa: F401
+from .client            import BridgeClient, EndpointClient, PluginClient  # noqa: F401
+
+# Public alias — ``Endpoint`` is the natural counterpart to ``Bridge``.
+Endpoint = EndpointService
+
+
+# ── Plugins ──────────────────────────────────────────────────────────────────
+
+from .plugin_xgfabric    import PluginXGFabric    # noqa: F401
+from .plugin_iri_connect import PluginIRIConnect  # noqa: F401
+from .plugin_queue_info  import PluginQueueInfo   # noqa: F401
+from .plugin_sysinfo    import PluginSysInfo  # noqa: F401
+from .plugin_staging    import PluginStaging  # noqa: F401
+from .plugin_task_dispatcher import PluginTaskDispatcher  # noqa: F401
+
+# Optional plugins with external dependencies.
+try:
+    from .plugin_lucid import PluginLucid  # noqa: F401
+except ImportError:
+    pass
+
+try:
+    from .plugin_psij import PluginPSIJ  # noqa: F401
+except ImportError:
+    pass
+
+try:
+    from .plugin_rhapsody import PluginRhapsody  # noqa: F401
+except ImportError:
+    pass
+
+try:
+    from .plugin_globus import PluginGlobus  # noqa: F401
+except ImportError:
+    pass
+
+
+# ── Version (generated at install time) ──────────────────────────────────────
+
+# _version.py is generated by setup.py at install time and is
+# git-ignored.  When running from an uninstalled source tree the
+# import will fail and we fall back to dev markers.
+try:
+    from ._version import version, version_detail  # noqa: F401
+except ImportError:
+    version        = 'unknown'
+    version_detail = 'unknown'
+
+__version__ = version
+

radical/orbit/_prof.py

@@ -0,0 +1,8 @@
+
+try:
+    from radical.prof import Profiler
+except ImportError:
+    class Profiler:
+        def __init__(self, name, ns=None): pass
+        def prof(self, *args, **kwargs):   pass
+        def close(self):                   pass

radical/orbit/_version.py

@@ -0,0 +1,3 @@
+# This file is auto-generated by setup.py — do not edit.
+version        = '0.2.0'
+version_detail = '0.2.0-v0.1.0-265-g4b12570@master'

radical/orbit/batch_system.py

@@ -0,0 +1,195 @@
+"""
+Batch system abstraction.
+
+Encapsulates everything about the local HPC scheduler that callers
+outside of ``queue_info`` need to know: presence detection, in-allocation
+detection, normalized job state, node lookup, cancel, allocation summary.
+
+Backend implementations live in ``batch_system_slurm.py`` and
+``batch_system_pbs.py`` and register themselves via ``_REGISTRY`` below.
+``detect_batch_system()`` returns the first backend whose ``detect()`` is
+true; otherwise ``NullBatchSystem``.
+
+State vocabulary (used everywhere outside the backend modules):
+    PENDING    — queued, not yet running
+    RUNNING    — running on compute nodes
+    DONE       — completed successfully
+    FAILED     — completed with non-zero exit, NODE_FAIL, PREEMPTED, TIMEOUT, …
+    CANCELLED  — user- or admin-cancelled
+    HELD       — held / suspended
+    UNKNOWN    — backend reported nothing (job gone, transient error, no scheduler)
+"""
+
+from abc import ABC, abstractmethod
+
+
+# Normalized state vocabulary
+STATE_PENDING   = 'PENDING'
+STATE_RUNNING   = 'RUNNING'
+STATE_DONE      = 'DONE'
+STATE_FAILED    = 'FAILED'
+STATE_CANCELLED = 'CANCELLED'
+STATE_HELD      = 'HELD'
+STATE_UNKNOWN   = 'UNKNOWN'
+
+TERMINAL_STATES = frozenset({STATE_DONE, STATE_FAILED, STATE_CANCELLED})
+
+
+class BatchSystem(ABC):
+    """Per-process scheduler interface.
+
+    Subclasses are stateless; one instance per backend is held in the
+    module-level cache returned by :func:`detect_batch_system`.
+    """
+
+    name          : str = 'none'   # short identifier
+    psij_executor : str = 'local'  # corresponding PsiJ executor name
+
+    @classmethod
+    @abstractmethod
+    def detect(cls) -> bool:
+        """Return True if this scheduler is installed locally."""
+
+    @abstractmethod
+    def in_allocation(self) -> bool:
+        """True when this process runs inside a batch job."""
+
+    @abstractmethod
+    def job_id(self) -> 'str | None':
+        """Native job id of the current allocation, or None on a login node."""
+
+    @abstractmethod
+    def job_state(self, native_id) -> str:
+        """Return a normalized state string for *native_id*.
+
+        Returns one of the STATE_* constants. Returns STATE_UNKNOWN on any
+        error (job gone, command failure, timeout, parse error).
+        """
+
+    @abstractmethod
+    def job_nodes(self, native_id) -> list:
+        """Return the list of compute node hostnames allocated to *native_id*.
+
+        Returns an empty list if the job is not running or the lookup fails.
+        """
+
+    @abstractmethod
+    def nodelist(self) -> list:
+        """Return the expanded list of hostnames in *this* endpoint's allocation.
+
+        Returns an empty list when the endpoint is not running inside a job (i.e.
+        on a login node) or when the scheduler doesn't expose the info.
+        Hostnames are returned one per node, in scheduler-reported order.
+        """
+
+    @abstractmethod
+    def cancel(self, native_id) -> None:
+        """Cancel *native_id*. Raises RuntimeError on failure."""
+
+    @abstractmethod
+    def job_allocation(self) -> 'dict | None':
+        """Return allocation info about the current batch job, or None.
+
+        On a login node returns None. Inside a batch job returns a dict with
+        keys: job_id, partition, n_nodes, nodelist, cpus_per_node,
+        gpus_per_node, account, job_name, runtime (seconds, None for
+        unlimited).
+
+        Raises RuntimeError when in_allocation() is true but details cannot
+        be collected.
+        """
+
+    def terminal_states(self) -> frozenset:
+        """The set of normalized states that mean 'job is done'."""
+        return TERMINAL_STATES
+
+    def default_custom_attributes(self) -> dict:
+        """Per-site PSIJ custom_attributes to merge into every submission.
+
+        Returned when the caller submits via the PSIJ executor that
+        corresponds to this backend (``psij_executor`` on the class).
+        Caller-provided attributes take precedence on key conflicts.
+
+        Default: no defaults.  Site-specific subclasses override to
+        encode hard requirements (e.g. Aurora's ``filesystems=home:flare``
+        resource is mandatory for qsub).
+        """
+        return {}
+
+
+class NullBatchSystem(BatchSystem):
+    """Fallback when no scheduler is installed (e.g. dev laptop)."""
+
+    name          = 'none'
+    psij_executor = 'local'
+
+    @classmethod
+    def detect(cls) -> bool:
+        return True   # always last in the registry; matches everything
+
+    def in_allocation(self) -> bool:
+        return False
+
+    def job_id(self) -> 'str | None':
+        return None
+
+    def job_state(self, native_id) -> str:
+        return STATE_UNKNOWN
+
+    def job_nodes(self, native_id) -> list:
+        return []
+
+    def nodelist(self) -> list:
+        return []
+
+    def cancel(self, native_id) -> None:
+        raise RuntimeError(f"no batch system available to cancel job {native_id}")
+
+    def job_allocation(self) -> 'dict | None':
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Registry + detection
+# ---------------------------------------------------------------------------
+
+_REGISTRY : list = []   # populated by backend modules at import time
+_DETECTED : 'BatchSystem | None' = None
+
+
+def register_backend(cls) -> None:
+    """Register a BatchSystem subclass. Called by backend modules at import."""
+    if cls not in _REGISTRY:
+        _REGISTRY.append(cls)
+
+
+def detect_batch_system(force: bool = False) -> BatchSystem:
+    """Return the active batch system, probing the registry on first call.
+
+    Result is cached. Pass ``force=True`` to re-probe (mainly for tests).
+    """
+    global _DETECTED
+    if _DETECTED is not None and not force:
+        return _DETECTED
+
+    # Import backend modules so they register. Local import avoids circular
+    # imports during package init.
+    from . import batch_system_slurm   # noqa: F401
+    from . import batch_system_pbs     # noqa: F401
+
+    for cls in _REGISTRY:
+        try:
+            if cls.detect():
+                _DETECTED = cls()
+                return _DETECTED
+        except Exception:
+            continue
+
+    _DETECTED = NullBatchSystem()
+    return _DETECTED
+
+
+def reset_detection() -> None:
+    """Clear the cached detection (tests only)."""
+    global _DETECTED
+    _DETECTED = None

radical/orbit/batch_system_pbs.py

@@ -0,0 +1,329 @@
+"""PBSPro implementation of BatchSystem.
+
+Targets PBS Professional (Altair) as found on Aurora and similar ALCF
+systems. Uses qstat / qdel for job control. Aurora's PBSPro publishes
+state info both as text (qstat -f) and partially as JSON (qstat -f -F json
+on recent versions); this backend only relies on text output, which is
+universal.
+"""
+
+import os
+import shutil
+import subprocess
+
+from .batch_system import (BatchSystem, register_backend,
+                           STATE_PENDING, STATE_RUNNING, STATE_DONE,
+                           STATE_FAILED, STATE_CANCELLED,
+                           STATE_HELD, STATE_UNKNOWN)
+
+
+# PBS single-letter state → normalized vocabulary.
+# Reference: PBSPro qstat manual (job_state column).
+_STATE_MAP = {
+    'Q': STATE_PENDING,    # queued
+    'W': STATE_PENDING,    # waiting (begin time / dependency)
+    'T': STATE_PENDING,    # being moved
+    'R': STATE_RUNNING,    # running
+    'B': STATE_RUNNING,    # array job: at least one subjob running
+    'E': STATE_RUNNING,    # exiting (still cleaning up)
+    'F': STATE_DONE,       # finished (PBSPro only with -x)
+    'X': STATE_DONE,       # subjob completed (array)
+    'H': STATE_HELD,       # held
+    'S': STATE_HELD,       # suspended
+    'M': STATE_HELD,       # moved to another server
+    'U': STATE_HELD,       # cycle-harvesting suspension
+}
+
+
+def _parse_pbs_walltime(s: str) -> 'int | None':
+    """Parse a PBS walltime string ([[HH:]MM:]SS) to seconds.
+
+    Returns None on empty / unset values.
+    """
+    if not s:
+        return None
+    s = s.strip()
+    if not s:
+        return None
+    parts = s.split(':')
+    try:
+        if   len(parts) == 3: h, m, sec = (int(p) for p in parts)
+        elif len(parts) == 2: h, m, sec = 0, int(parts[0]), int(parts[1])
+        elif len(parts) == 1: h, m, sec = 0, 0, int(parts[0])
+        else: raise ValueError
+    except ValueError as e:
+        raise RuntimeError(f"Cannot parse PBS walltime: {s!r}") from e
+    return h * 3600 + m * 60 + sec
+
+
+def _parse_qstat_f(stdout: str) -> dict:
+    """Parse ``qstat -f <jobid>`` text output into a {key: value} dict.
+
+    PBSPro indents every attribute line (``    key = value``).  Continuation
+    lines for long values are indented *more* than attribute lines and may
+    themselves contain ``=`` characters (e.g. inside ``Resource_List.select``).
+    The rule used here: the first indented attribute line sets the
+    *attribute-indent* width; any line indented strictly deeper is a
+    continuation of the prior key.
+    Section headers like ``Job Id: 12345`` are ignored.
+    """
+    result = {}
+    cur_key = None
+    cur_val_parts = []
+    attr_indent = None    # set by the first attribute line we see
+
+    def _flush():
+        if cur_key is not None:
+            result[cur_key] = ''.join(cur_val_parts).strip()
+
+    for raw in stdout.splitlines():
+        if not raw or not raw.strip():
+            continue
+        stripped = raw.strip()
+        if stripped.startswith('Job Id:'):
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        is_continuation = (attr_indent is not None
+                           and indent > attr_indent
+                           and cur_key is not None)
+        if is_continuation:
+            cur_val_parts.append(stripped)
+            continue
+        if attr_indent is None:
+            attr_indent = indent
+        # A new attribute line.
+        if '=' in stripped:
+            _flush()
+            k, v = stripped.split('=', 1)
+            cur_key = k.strip()
+            cur_val_parts = [v.strip()]
+        elif cur_key is not None:
+            # No '=' and not deeper indented → treat as plain continuation.
+            cur_val_parts.append(stripped)
+    _flush()
+    return result
+
+
+def _parse_exec_host(s: str) -> list:
+    """Parse PBS exec_host into a list of hostnames.
+
+    Format: ``host1/0*64+host2/0*64`` (host/cpuset*ncpus pairs).
+    Returns deduplicated host list preserving order.
+    """
+    if not s:
+        return []
+    seen = set()
+    hosts = []
+    for token in s.split('+'):
+        host = token.split('/', 1)[0].split('.', 1)[0]
+        if host and host not in seen:
+            seen.add(host)
+            hosts.append(host)
+    return hosts
+
+
+def _read_pbs_nodefile() -> list:
+    """Return deduplicated host list from $PBS_NODEFILE, empty if missing."""
+    path = os.environ.get('PBS_NODEFILE')
+    if not path or not os.path.isfile(path):
+        return []
+    try:
+        with open(path) as f:
+            lines = [l.strip() for l in f if l.strip()]
+    except OSError:
+        return []
+    seen = set()
+    hosts = []
+    for h in lines:
+        h = h.split('.', 1)[0]
+        if h not in seen:
+            seen.add(h)
+            hosts.append(h)
+    return hosts
+
+
+class PBSProBatchSystem(BatchSystem):
+    """PBSPro scheduler interface."""
+
+    name          = 'pbs'
+    psij_executor = 'pbs'
+
+    def __init__(self) -> None:
+        super().__init__()
+        # Native ids we've been asked to cancel.  PBSPro's qstat letter
+        # codes have no dedicated 'cancelled' value — the job ends up in
+        # 'F' (finished) just like a normal exit, so we remember the
+        # intent here and map terminal states to STATE_CANCELLED in
+        # job_state().
+        self._cancelled: set = set()
+
+    @classmethod
+    def detect(cls) -> bool:
+        return shutil.which('qstat') is not None
+
+    def in_allocation(self) -> bool:
+        return bool(os.environ.get('PBS_JOBID'))
+
+    def job_id(self) -> 'str | None':
+        return os.environ.get('PBS_JOBID')
+
+    def job_state(self, native_id) -> str:
+        try:
+            r = subprocess.run(
+                ['qstat', '-f', str(native_id)],
+                capture_output=True, text=True, timeout=10)
+        except (OSError, subprocess.TimeoutExpired):
+            return STATE_UNKNOWN
+        if r.returncode != 0:
+            # try -x to look up finished jobs
+            try:
+                r = subprocess.run(
+                    ['qstat', '-x', '-f', str(native_id)],
+                    capture_output=True, text=True, timeout=10)
+            except (OSError, subprocess.TimeoutExpired):
+                return STATE_UNKNOWN
+            if r.returncode != 0:
+                return STATE_UNKNOWN
+        info = _parse_qstat_f(r.stdout)
+        code = info.get('job_state', '').strip()
+        if not code:
+            return STATE_UNKNOWN
+        state = _STATE_MAP.get(code[0].upper(), STATE_UNKNOWN)
+        if str(native_id) in self._cancelled and state in (STATE_DONE, STATE_FAILED):
+            return STATE_CANCELLED
+        return state
+
+    def job_nodes(self, native_id) -> list:
+        try:
+            r = subprocess.run(
+                ['qstat', '-f', str(native_id)],
+                capture_output=True, text=True, timeout=10)
+        except (OSError, subprocess.TimeoutExpired):
+            return []
+        if r.returncode != 0:
+            return []
+        info = _parse_qstat_f(r.stdout)
+        return _parse_exec_host(info.get('exec_host', ''))
+
+    def nodelist(self) -> list:
+        # PBS_NODEFILE lists each host once per slot; ``_read_pbs_nodefile``
+        # already dedupes and short-circuits on a missing / empty file.
+        return _read_pbs_nodefile()
+
+    def cancel(self, native_id) -> None:
+        r = subprocess.run(['qdel', str(native_id)],
+                           capture_output=True, text=True, timeout=10)
+        if r.returncode != 0:
+            raise RuntimeError(f"qdel failed: {r.stderr.strip()}")
+        self._cancelled.add(str(native_id))
+
+    def job_allocation(self) -> 'dict | None':
+        job_id = os.environ.get('PBS_JOBID')
+        if not job_id:
+            return None
+
+        # Node count from PBS_NODEFILE first (always present in jobs),
+        # fall back to qstat -f Resource_List.nodect if needed.
+        nodes = _read_pbs_nodefile()
+        n_nodes = len(nodes) or None
+
+        # Pull walltime / partition / account from qstat.
+        runtime    = None
+        partition  = os.environ.get('PBS_QUEUE') or os.environ.get('PBS_O_QUEUE')
+        account    = os.environ.get('PBS_ACCOUNT')
+        job_name   = os.environ.get('PBS_JOBNAME')
+        nodelist   = ','.join(nodes) if nodes else None
+        cpus_per_node = None
+        gpus_per_node = None
+
+        try:
+            r = subprocess.run(
+                ['qstat', '-f', job_id],
+                capture_output=True, text=True, timeout=10)
+            if r.returncode == 0:
+                info = _parse_qstat_f(r.stdout)
+                runtime = _parse_pbs_walltime(
+                    info.get('Resource_List.walltime', ''))
+                if not n_nodes:
+                    nct = info.get('Resource_List.nodect', '')
+                    try:
+                        n_nodes = int(nct) if nct else None
+                    except ValueError:
+                        n_nodes = None
+                if not partition:
+                    partition = info.get('queue', '') or None
+                if not account:
+                    account = info.get('Account_Name', '') or None
+                if not job_name:
+                    job_name = info.get('Job_Name', '') or None
+                if not nodelist:
+                    eh = info.get('exec_host', '')
+                    if eh:
+                        nodelist = ','.join(_parse_exec_host(eh))
+
+                # Extract per-node resources from select=... when possible.
+                # Format: "1:ncpus=64:ngpus=4" or "2:ncpus=64".
+                select = info.get('Resource_List.select', '')
+                if select:
+                    chunk = select.split('+', 1)[0]
+                    tokens = chunk.split(':')
+                    for tok in tokens:
+                        if tok.startswith('ncpus='):
+                            try: cpus_per_node = int(tok[6:])
+                            except ValueError: pass
+                        elif tok.startswith('ngpus='):
+                            try: gpus_per_node = int(tok[6:])
+                            except ValueError: pass
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            if not n_nodes:
+                raise RuntimeError(
+                    f"PBS_JOBID={job_id!r} is set but cannot query qstat: {exc}"
+                ) from exc
+
+        if not n_nodes:
+            raise RuntimeError(
+                f"PBS_JOBID={job_id!r} is set but node count is unavailable")
+
+        return {
+            'job_id'       : job_id,
+            'partition'    : partition,
+            'n_nodes'      : int(n_nodes),
+            'nodelist'     : nodelist,
+            'cpus_per_node': cpus_per_node,
+            'gpus_per_node': gpus_per_node,
+            'account'      : account,
+            'job_name'     : job_name,
+            'runtime'      : runtime,
+        }
+
+
+class AuroraPBSBatchSystem(PBSProBatchSystem):
+    """Aurora (ALCF) specialization of PBSPro.
+
+    Aurora requires ``#PBS -l filesystems=<list>`` on every submission
+    (qsub rejects jobs without it), and the expected user base of
+    radical.orbit is not expected to know PBS-level resource names.  This
+    class fills in the defaults so that the UI and the Python client API
+    both succeed out of the box; user-supplied values still win on
+    conflict.
+
+    Detection: the vendor-installed ``/opt/aurora`` directory is present
+    on both login and compute nodes and is unambiguous (no hostname
+    regex, no subprocess calls).
+    """
+
+    name = 'pbs-aurora'
+
+    @classmethod
+    def detect(cls) -> bool:
+        return (super().detect()
+                and os.path.isdir('/opt/aurora'))
+
+    def default_custom_attributes(self) -> dict:
+        return {'pbs.l': 'filesystems=home:flare'}
+
+
+# Register Aurora before the generic backend so detect_batch_system()
+# picks the specialization on ALCF hosts.
+register_backend(AuroraPBSBatchSystem)
+register_backend(PBSProBatchSystem)