hpc-runner 0.1.0__py3-none-any.whl

hpc_runner/core/descriptors.py

@@ -0,0 +1,56 @@
+"""Base descriptor pattern for scheduler arguments."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class SchedulerArg(ABC, Generic[T]):
+    """Base descriptor for scheduler arguments.
+
+    Attributes:
+        flag: The scheduler's command-line flag name
+        converter: Function to convert Python value to string
+        validator: Optional validation function
+        doc: Documentation string
+        env_var: Optional environment variable override
+    """
+
+    def __init__(
+        self,
+        flag: str,
+        *,
+        converter: Callable[[T], str] = str,
+        validator: Callable[[T], bool] | None = None,
+        doc: str = "",
+        env_var: str | None = None,
+    ):
+        self.flag = flag
+        self.converter = converter
+        self.validator = validator
+        self.doc = doc
+        self.env_var = env_var
+        self._name: str | None = None
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self._name = name
+
+    def __get__(self, obj: Any, objtype: type | None = None) -> T | None:
+        if obj is None:
+            return self  # type: ignore[return-value]
+        return obj.__dict__.get(self._name)  # type: ignore[arg-type]
+
+    def __set__(self, obj: Any, value: T | None) -> None:
+        if value is not None and self.validator:
+            if not self.validator(value):
+                raise ValueError(f"Invalid value for {self._name}: {value}")
+        obj.__dict__[self._name] = value  # type: ignore[index]
+
+    @abstractmethod
+    def to_args(self, value: T | None) -> list[str]:
+        """Convert value to command-line arguments."""
+
+    @abstractmethod
+    def to_directive(self, value: T | None) -> str | None:
+        """Convert value to script directive (e.g., #SBATCH, #$)."""

hpc_runner/core/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions for hpc-tools."""
+
+
+class HPCToolsError(Exception):
+    """Base exception for hpc-tools."""
+
+
+class SchedulerError(HPCToolsError):
+    """Error related to scheduler operations."""
+
+
+class SubmissionError(SchedulerError):
+    """Error during job submission."""
+
+
+class JobNotFoundError(SchedulerError):
+    """Job ID not found."""
+
+
+class ConfigError(HPCToolsError):
+    """Error in configuration."""
+
+
+class ConfigNotFoundError(ConfigError):
+    """Configuration file not found."""
+
+
+class ValidationError(HPCToolsError):
+    """Validation error for job parameters."""

hpc_runner/core/job.py

@@ -0,0 +1,149 @@
+"""Job model for HPC job submission."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from hpc_runner.core.resources import ResourceSet
+
+if TYPE_CHECKING:
+    from hpc_runner.core.result import JobResult
+    from hpc_runner.schedulers.base import BaseScheduler
+
+
+@dataclass
+class Job:
+    """Represents a job to be submitted.
+
+    Attributes:
+        command: The command to execute (string or list)
+        name: Job name (auto-generated if not provided)
+        cpu: Number of CPUs/cores/slots
+        mem: Memory requirement (e.g., "16G", "4096M")
+        time: Wall time limit (e.g., "4:00:00", "1-00:00:00")
+        queue: Queue/partition name
+        nodes: Number of nodes (for MPI jobs)
+        tasks: Number of tasks (for MPI jobs)
+        resources: Additional resource requests
+        modules: Environment modules to load
+        modules_path: Additional module paths
+        inherit_env: Inherit current environment
+        workdir: Working directory (default: current)
+        stdout: Stdout file path (supports templates)
+        stderr: Stderr file path (None = merge with stdout)
+        raw_args: Raw scheduler arguments (passthrough)
+        sge_args: SGE-specific raw arguments
+        slurm_args: Slurm-specific raw arguments
+        pbs_args: PBS-specific raw arguments
+    """
+
+    command: str | list[str]
+    name: str | None = None
+    cpu: int | None = None
+    mem: str | None = None
+    time: str | None = None
+    queue: str | None = None
+    nodes: int | None = None
+    tasks: int | None = None
+    resources: ResourceSet = field(default_factory=ResourceSet)
+    modules: list[str] = field(default_factory=list)
+    modules_path: list[str] = field(default_factory=list)
+    inherit_env: bool = True
+    workdir: Path | str | None = None
+    stdout: str | None = None
+    stderr: str | None = None  # None = merge with stdout
+
+    # Raw passthrough arguments
+    raw_args: list[str] = field(default_factory=list)
+    sge_args: list[str] = field(default_factory=list)
+    slurm_args: list[str] = field(default_factory=list)
+    pbs_args: list[str] = field(default_factory=list)
+
+    # Dependency management
+    dependencies: list[JobResult] = field(default_factory=list)
+    dependency_type: str = "afterok"  # afterok, afterany, after, afternotok
+
+    def __post_init__(self) -> None:
+        if self.name is None:
+            self.name = self._generate_name()
+        if isinstance(self.command, list):
+            self.command = " ".join(self.command)
+        if self.workdir is not None and not isinstance(self.workdir, Path):
+            self.workdir = Path(self.workdir)
+
+    def _generate_name(self) -> str:
+        """Generate job name from command."""
+        user = os.environ.get("USER", "user")
+        # Extract first word of command, strip path
+        cmd_str = self.command if isinstance(self.command, str) else self.command[0]
+        cmd = cmd_str.split()[0]
+        cmd = Path(cmd).name
+        cmd = re.sub(r"[^a-zA-Z0-9_-]", "_", cmd)
+        return f"{user}_{cmd}"
+
+    def submit(self, scheduler: BaseScheduler | None = None) -> JobResult:
+        """Submit the job.
+
+        Args:
+            scheduler: Scheduler to use. Auto-detects if None.
+
+        Returns:
+            JobResult with job ID and status methods
+        """
+        from hpc_runner.schedulers import get_scheduler
+
+        if scheduler is None:
+            scheduler = get_scheduler()
+        return scheduler.submit(self)
+
+    def after(self, *jobs: JobResult, type: str = "afterok") -> Job:
+        """Add dependency on other jobs.
+
+        Args:
+            jobs: Jobs this job depends on
+            type: Dependency type (afterok, afterany, after, afternotok)
+        """
+        self.dependencies.extend(jobs)
+        self.dependency_type = type
+        return self
+
+    @classmethod
+    def from_config(
+        cls,
+        tool_or_type: str,
+        command: str | None = None,
+        **overrides: Any,
+    ) -> Job:
+        """Create job from configuration.
+
+        Args:
+            tool_or_type: Tool name or job type from config
+            command: Override command (uses config template if None)
+            **overrides: Override any job parameters
+        """
+        from hpc_runner.core.config import load_config
+
+        config = load_config()
+        job_config = config.get_job_config(tool_or_type)
+
+        if command:
+            job_config["command"] = command
+        job_config.update(overrides)
+
+        # Handle resources specially
+        if "resources" in job_config and isinstance(job_config["resources"], list):
+            resource_set = ResourceSet()
+            for r in job_config["resources"]:
+                resource_set.add(r["name"], r["value"])
+            job_config["resources"] = resource_set
+
+        return cls(**job_config)
+
+    @property
+    def merge_output(self) -> bool:
+        """Whether stderr should be merged with stdout."""
+        return self.stderr is None

hpc_runner/core/job_array.py

@@ -0,0 +1,58 @@
+"""Job array support for batch processing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Iterator
+
+if TYPE_CHECKING:
+    from hpc_runner.core.job import Job
+    from hpc_runner.core.result import ArrayJobResult
+    from hpc_runner.schedulers.base import BaseScheduler
+
+
+@dataclass
+class JobArray:
+    """Represents an array job.
+
+    Attributes:
+        job: Base job specification
+        start: Array start index
+        end: Array end index
+        step: Array step (default 1)
+        max_concurrent: Max simultaneous tasks (throttling)
+    """
+
+    job: Job
+    start: int = 1
+    end: int = 1
+    step: int = 1
+    max_concurrent: int | None = None
+
+    @property
+    def range_str(self) -> str:
+        """Format as scheduler range string."""
+        s = f"{self.start}-{self.end}"
+        if self.step != 1:
+            s += f":{self.step}"
+        if self.max_concurrent:
+            s += f"%{self.max_concurrent}"
+        return s
+
+    @property
+    def indices(self) -> Iterator[int]:
+        """Iterate over array indices."""
+        return iter(range(self.start, self.end + 1, self.step))
+
+    @property
+    def count(self) -> int:
+        """Number of array tasks."""
+        return len(range(self.start, self.end + 1, self.step))
+
+    def submit(self, scheduler: BaseScheduler | None = None) -> ArrayJobResult:
+        """Submit the array job."""
+        from hpc_runner.schedulers import get_scheduler
+
+        if scheduler is None:
+            scheduler = get_scheduler()
+        return scheduler.submit_array(self)

hpc_runner/core/resources.py

@@ -0,0 +1,49 @@
+"""Resource abstraction for job resource requests."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Resource:
+    """A scheduler resource request.
+
+    Examples:
+        Resource("gpu", 2)              # 2 GPUs
+        Resource("xilinx", 1)           # 1 Xilinx license
+        Resource("mem", "16G")          # Memory
+    """
+
+    name: str
+    value: int | str
+
+    # Scheduler-specific mappings (populated by scheduler)
+    _sge_resource: str | None = field(default=None, repr=False)
+    _slurm_gres: str | None = field(default=None, repr=False)
+
+
+@dataclass
+class ResourceSet:
+    """Collection of resources for a job."""
+
+    resources: list[Resource] = field(default_factory=list)
+
+    def add(self, name: str, value: int | str) -> "ResourceSet":
+        """Add a resource to the set."""
+        self.resources.append(Resource(name, value))
+        return self
+
+    def get(self, name: str) -> Resource | None:
+        """Get a resource by name."""
+        for r in self.resources:
+            if r.name == name:
+                return r
+        return None
+
+    def __iter__(self):
+        return iter(self.resources)
+
+    def __len__(self) -> int:
+        return len(self.resources)
+
+    def __bool__(self) -> bool:
+        return bool(self.resources)

hpc_runner/core/result.py

@@ -0,0 +1,157 @@
+"""Job result and status types."""
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from hpc_runner.core.job import Job
+    from hpc_runner.core.job_array import JobArray
+    from hpc_runner.schedulers.base import BaseScheduler
+
+
+class JobStatus(Enum):
+    """Unified job status across schedulers."""
+
+    PENDING = auto()  # Waiting in queue
+    RUNNING = auto()  # Currently executing
+    COMPLETED = auto()  # Finished successfully
+    FAILED = auto()  # Finished with error
+    CANCELLED = auto()  # User cancelled
+    TIMEOUT = auto()  # Hit time limit
+    UNKNOWN = auto()  # Cannot determine
+
+
+@dataclass
+class JobResult:
+    """Result of a submitted job.
+
+    Provides methods to query status, wait for completion,
+    and access output.
+    """
+
+    job_id: str
+    scheduler: "BaseScheduler"
+    job: "Job"
+
+    _cached_status: JobStatus | None = field(default=None, repr=False)
+
+    @property
+    def status(self) -> JobStatus:
+        """Get current job status (queries scheduler)."""
+        return self.scheduler.get_status(self.job_id)
+
+    @property
+    def is_complete(self) -> bool:
+        """Check if job has finished (success or failure)."""
+        return self.status in (
+            JobStatus.COMPLETED,
+            JobStatus.FAILED,
+            JobStatus.CANCELLED,
+            JobStatus.TIMEOUT,
+        )
+
+    @property
+    def returncode(self) -> int | None:
+        """Get exit code (None if not complete)."""
+        if not self.is_complete:
+            return None
+        return self.scheduler.get_exit_code(self.job_id)
+
+    def wait(self, poll_interval: float = 5.0, timeout: float | None = None) -> JobStatus:
+        """Block until job completes.
+
+        Args:
+            poll_interval: Seconds between status checks
+            timeout: Max seconds to wait (None = forever)
+
+        Returns:
+            Final job status
+        """
+        import time
+
+        start = time.time()
+        while not self.is_complete:
+            if timeout and (time.time() - start) > timeout:
+                raise TimeoutError(f"Job {self.job_id} did not complete within {timeout}s")
+            time.sleep(poll_interval)
+        return self.status
+
+    def cancel(self) -> bool:
+        """Cancel the job."""
+        return self.scheduler.cancel(self.job_id)
+
+    def stdout_path(self) -> Path | None:
+        """Get path to stdout file."""
+        return self.scheduler.get_output_path(self.job_id, "stdout")
+
+    def stderr_path(self) -> Path | None:
+        """Get path to stderr file."""
+        return self.scheduler.get_output_path(self.job_id, "stderr")
+
+    def read_stdout(self, tail: int | None = None) -> str:
+        """Read stdout content."""
+        path = self.stdout_path()
+        if not path or not path.exists():
+            return ""
+        content = path.read_text()
+        if tail:
+            lines = content.splitlines()
+            content = "\n".join(lines[-tail:])
+        return content
+
+    def read_stderr(self, tail: int | None = None) -> str:
+        """Read stderr content."""
+        path = self.stderr_path()
+        if not path or not path.exists():
+            return ""
+        content = path.read_text()
+        if tail:
+            lines = content.splitlines()
+            content = "\n".join(lines[-tail:])
+        return content
+
+
+@dataclass
+class ArrayJobResult:
+    """Result of a submitted array job."""
+
+    base_job_id: str
+    scheduler: "BaseScheduler"
+    array: "JobArray"
+
+    def task_id(self, index: int) -> str:
+        """Get job ID for specific array task."""
+        return f"{self.base_job_id}.{index}"
+
+    def task_status(self, index: int) -> JobStatus:
+        """Get status of specific array task."""
+        return self.scheduler.get_status(self.task_id(index))
+
+    def wait(self, poll_interval: float = 5.0) -> dict[int, JobStatus]:
+        """Wait for all array tasks to complete."""
+        import time
+
+        results: dict[int, JobStatus] = {}
+        pending = set(self.array.indices)
+
+        while pending:
+            for idx in list(pending):
+                status = self.task_status(idx)
+                if status in (
+                    JobStatus.COMPLETED,
+                    JobStatus.FAILED,
+                    JobStatus.CANCELLED,
+                    JobStatus.TIMEOUT,
+                ):
+                    results[idx] = status
+                    pending.remove(idx)
+            if pending:
+                time.sleep(poll_interval)
+
+        return results
+
+    def cancel(self) -> bool:
+        """Cancel all array tasks."""
+        return self.scheduler.cancel(self.base_job_id)

hpc_runner/core/types.py

@@ -0,0 +1,13 @@
+"""Type aliases for hpc-tools."""
+
+from pathlib import Path
+from typing import TypeAlias
+
+# Path types
+PathLike: TypeAlias = str | Path
+
+# Command types
+Command: TypeAlias = str | list[str]
+
+# Resource value types
+ResourceValue: TypeAlias = int | str

hpc_runner/schedulers/__init__.py

@@ -0,0 +1,60 @@
+"""Scheduler registry and auto-detection."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+from hpc_runner.schedulers.detection import detect_scheduler
+
+if TYPE_CHECKING:
+    from hpc_runner.schedulers.base import BaseScheduler
+
+_SCHEDULERS: dict[str, str] = {
+    "sge": "hpc_runner.schedulers.sge:SGEScheduler",
+    "slurm": "hpc_runner.schedulers.slurm:SlurmScheduler",
+    "pbs": "hpc_runner.schedulers.pbs:PBSScheduler",
+    "local": "hpc_runner.schedulers.local:LocalScheduler",
+}
+
+
+def get_scheduler(name: str | None = None) -> "BaseScheduler":
+    """Get scheduler instance.
+
+    Args:
+        name: Scheduler name or None to auto-detect
+
+    Returns:
+        Scheduler instance
+    """
+    if name is None:
+        name = detect_scheduler()
+
+    if name not in _SCHEDULERS:
+        available = list(_SCHEDULERS.keys())
+        raise ValueError(f"Unknown scheduler: {name}. Available: {available}")
+
+    # Lazy import
+    module_path, class_name = _SCHEDULERS[name].rsplit(":", 1)
+    module = importlib.import_module(module_path)
+    scheduler_class = getattr(module, class_name)
+
+    return scheduler_class()
+
+
+def register_scheduler(name: str, import_path: str) -> None:
+    """Register a custom scheduler.
+
+    Args:
+        name: Scheduler name
+        import_path: Import path like "mypackage.scheduler:MyScheduler"
+    """
+    _SCHEDULERS[name] = import_path
+
+
+def list_schedulers() -> list[str]:
+    """List available scheduler names."""
+    return list(_SCHEDULERS.keys())
+
+
+__all__ = ["get_scheduler", "register_scheduler", "list_schedulers", "detect_scheduler"]

hpc_runner/schedulers/base.py

@@ -0,0 +1,76 @@
+"""Abstract base class for scheduler implementations."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from hpc_runner.core.job import Job
+    from hpc_runner.core.job_array import JobArray
+    from hpc_runner.core.result import ArrayJobResult, JobResult, JobStatus
+
+
+class BaseScheduler(ABC):
+    """Abstract base class for scheduler implementations.
+
+    Each scheduler must implement:
+    - submit(): Submit a job
+    - submit_array(): Submit an array job
+    - cancel(): Cancel a job
+    - get_status(): Query job status
+    - get_exit_code(): Get job exit code
+    - get_output_path(): Get output file path
+    - generate_script(): Generate job script
+    - build_submit_command(): Build submission command
+    """
+
+    name: str  # e.g., "sge", "slurm", "local"
+
+    @abstractmethod
+    def submit(self, job: "Job", interactive: bool = False) -> "JobResult":
+        """Submit a job to the scheduler.
+
+        Args:
+            job: Job specification
+            interactive: Run interactively (blocking)
+
+        Returns:
+            JobResult with job ID and methods
+        """
+
+    @abstractmethod
+    def submit_array(self, array: "JobArray") -> "ArrayJobResult":
+        """Submit an array job."""
+
+    @abstractmethod
+    def cancel(self, job_id: str) -> bool:
+        """Cancel a job by ID."""
+
+    @abstractmethod
+    def get_status(self, job_id: str) -> "JobStatus":
+        """Get current status of a job."""
+
+    @abstractmethod
+    def get_exit_code(self, job_id: str) -> int | None:
+        """Get exit code of completed job."""
+
+    @abstractmethod
+    def get_output_path(self, job_id: str, stream: str) -> Path | None:
+        """Get path to output file.
+
+        Args:
+            job_id: Job ID
+            stream: "stdout" or "stderr"
+        """
+
+    @abstractmethod
+    def generate_script(self, job: "Job") -> str:
+        """Generate job script content."""
+
+    @abstractmethod
+    def build_submit_command(self, job: "Job") -> list[str]:
+        """Build the submission command (e.g., qsub args)."""
+
+    def get_scheduler_args(self, job: "Job") -> list[str]:
+        """Get scheduler-specific raw args from job."""
+        return getattr(job, f"{self.name}_args", [])

hpc_runner/schedulers/detection.py

@@ -0,0 +1,34 @@
+"""Auto-detection of available scheduler."""
+
+import os
+import shutil
+
+
+def detect_scheduler() -> str:
+    """Auto-detect available scheduler.
+
+    Order of precedence:
+    1. HPC_SCHEDULER environment variable
+    2. SGE (check for qsub with SGE_ROOT)
+    3. Slurm (check for sbatch)
+    4. PBS (check for qsub with PBS_CONF_FILE)
+    5. Local fallback
+    """
+    # Environment override
+    if scheduler := os.environ.get("HPC_SCHEDULER"):
+        return scheduler.lower()
+
+    # Check for SGE (also uses qsub but has SGE_ROOT)
+    if shutil.which("qsub") and os.environ.get("SGE_ROOT"):
+        return "sge"
+
+    # Check for Slurm
+    if shutil.which("sbatch") and shutil.which("squeue"):
+        return "slurm"
+
+    # Check for PBS/Torque
+    if shutil.which("qsub") and os.environ.get("PBS_CONF_FILE"):
+        return "pbs"
+
+    # Fallback to local
+    return "local"

hpc_runner/schedulers/local/__init__.py

@@ -0,0 +1,5 @@
+"""Local scheduler for testing and development."""
+
+from hpc_runner.schedulers.local.scheduler import LocalScheduler
+
+__all__ = ["LocalScheduler"]