runops 0.2.0__py3-none-any.whl

runops/adapters/generic.py

@@ -0,0 +1,439 @@
+"""Generic simulator adapter providing reasonable defaults.
+
+This adapter handles simulators that follow common conventions:
+a single executable, a single input file, and standard output
+locations within the ``work/`` directory.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from runops.adapters.base import SimulatorAdapter
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+INPUT_DIR = "input"
+WORK_DIR = "work"
+ANALYSIS_DIR = "analysis"
+STATUS_DIR = "status"
+SUBMIT_DIR = "submit"
+
+EXIT_CODE_FILE = "exit_code"
+STDOUT_FILE = "stdout.log"
+STDERR_FILE = "stderr.log"
+
+SUMMARY_FILE = "summary.json"
+
+_RESOLVER_MODES = frozenset({"package", "local_source", "local_executable"})
+
+
+class GenericAdapter(SimulatorAdapter):
+    """Generic adapter that works for many simple simulators.
+
+    Conventions:
+    - Input files live in ``<run_dir>/input/``.
+    - Execution happens in ``<run_dir>/work/``.
+    - Success is determined by a zero exit code written to
+      ``<run_dir>/work/exit_code``.
+
+    Class Attributes:
+        adapter_name: Registry key for this adapter.
+    """
+
+    adapter_name: str = "generic"
+
+    # ------------------------------------------------------------------
+    # SimulatorAdapter interface
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        """Return the canonical name of this adapter."""
+        return self.adapter_name
+
+    def render_inputs(
+        self,
+        case_data: dict[str, Any],
+        run_dir: Path,
+    ) -> list[str]:
+        """Copy input files listed in *case_data* into the run directory.
+
+        If ``case_data["params"]`` exists, it is serialised as a JSON file
+        named ``params.json`` inside ``<run_dir>/input/``.
+
+        If ``case_data["case"]["input_files"]`` is a list of source paths,
+        each file is copied into ``<run_dir>/input/``.
+
+        Args:
+            case_data: Merged case/survey parameters.
+            run_dir: Target run directory.
+
+        Returns:
+            List of relative paths (from *run_dir*) to generated input files.
+
+        Raises:
+            ValueError: If required case metadata is missing.
+        """
+        case_section = case_data.get("case", {})
+        if not case_section:
+            msg = "case_data must contain a 'case' section"
+            raise ValueError(msg)
+
+        input_dir = run_dir / INPUT_DIR
+        input_dir.mkdir(parents=True, exist_ok=True)
+
+        created: list[str] = []
+
+        # Serialise parameters
+        params = case_data.get("params")
+        if params is not None:
+            params_file = input_dir / "params.json"
+            params_file.write_text(json.dumps(params, indent=2))
+            created.append(str(params_file.relative_to(run_dir)))
+
+        # Copy explicit input files
+        source_files: list[str] = case_section.get("input_files", [])
+        for src_str in source_files:
+            src = Path(src_str)
+            if not src.is_file():
+                logger.warning("Input file not found, skipping: %s", src)
+                continue
+            dest = input_dir / src.name
+            shutil.copy2(src, dest)
+            created.append(str(dest.relative_to(run_dir)))
+
+        return created
+
+    def resolve_runtime(
+        self,
+        simulator_config: dict[str, Any],
+        resolver_mode: str,
+    ) -> dict[str, Any]:
+        """Resolve the simulator runtime from *simulator_config*.
+
+        Supports three resolver modes defined in SPEC section 16:
+
+        * ``package`` -- looks up ``executable`` in ``$PATH``.
+        * ``local_source`` -- uses ``source_repo`` and optionally runs
+          ``build_command`` to produce ``executable``.
+        * ``local_executable`` -- uses a fully-qualified ``executable``
+          path directly.
+
+        Args:
+            simulator_config: Simulator section from ``simulators.toml``.
+            resolver_mode: One of ``"package"``, ``"local_source"``,
+                ``"local_executable"``.
+
+        Returns:
+            Runtime information dictionary with at least ``executable``
+            and ``resolver_mode`` keys.
+
+        Raises:
+            ValueError: If *resolver_mode* is unsupported or required keys
+                are missing.
+        """
+        if resolver_mode not in _RESOLVER_MODES:
+            msg = (
+                f"Unsupported resolver_mode '{resolver_mode}'. "
+                f"Expected one of {sorted(_RESOLVER_MODES)}"
+            )
+            raise ValueError(msg)
+
+        runtime: dict[str, Any] = {"resolver_mode": resolver_mode}
+
+        if resolver_mode == "package":
+            exe_name = simulator_config.get("executable", "")
+            if not exe_name:
+                msg = "simulator_config must specify 'executable' for package mode"
+                raise ValueError(msg)
+            resolved = shutil.which(exe_name)
+            runtime["executable"] = resolved if resolved else exe_name
+            runtime["source"] = "package"
+
+        elif resolver_mode == "local_source":
+            source_repo = simulator_config.get("source_repo", "")
+            executable = simulator_config.get("executable", "")
+            if not source_repo or not executable:
+                msg = (
+                    "simulator_config must specify 'source_repo' and "
+                    "'executable' for local_source mode"
+                )
+                raise ValueError(msg)
+            runtime["source_repo"] = source_repo
+            runtime["executable"] = executable
+            runtime["build_command"] = simulator_config.get("build_command", "")
+
+        elif resolver_mode == "local_executable":
+            executable = simulator_config.get("executable", "")
+            if not executable:
+                msg = (
+                    "simulator_config must specify 'executable' "
+                    "for local_executable mode"
+                )
+                raise ValueError(msg)
+            runtime["executable"] = executable
+
+        return runtime
+
+    def build_program_command(
+        self,
+        runtime_info: dict[str, Any],
+        run_dir: Path,
+    ) -> list[str]:
+        """Build ``[executable, ...]`` for the simulator.
+
+        The generic adapter simply returns the executable path.  If an
+        ``input/params.json`` file exists it is passed as the first
+        positional argument.
+
+        Args:
+            runtime_info: Output from :meth:`resolve_runtime`.
+            run_dir: The run directory.
+
+        Returns:
+            Command as a list of strings (no MPI launcher prefix).
+        """
+        executable: str = runtime_info.get("executable", "")
+        if not executable:
+            msg = "runtime_info must contain 'executable'"
+            raise ValueError(msg)
+
+        cmd = [executable]
+        params_file = run_dir / INPUT_DIR / "params.json"
+        if params_file.exists():
+            cmd.append(str(params_file))
+        return cmd
+
+    def detect_outputs(self, run_dir: Path) -> dict[str, Any]:
+        """Scan ``<run_dir>/work/`` for output files.
+
+        Args:
+            run_dir: The run directory.
+
+        Returns:
+            Mapping of descriptive label to relative path strings.
+        """
+        work_dir = run_dir / WORK_DIR
+        if not work_dir.is_dir():
+            logger.warning("work/ directory not found in %s", run_dir)
+            return {}
+
+        outputs: dict[str, Any] = {}
+        stdout = work_dir / STDOUT_FILE
+        stderr = work_dir / STDERR_FILE
+
+        if stdout.exists():
+            outputs["stdout"] = str(stdout.relative_to(run_dir))
+        if stderr.exists():
+            outputs["stderr"] = str(stderr.relative_to(run_dir))
+
+        # Collect remaining files (excluding status markers)
+        for path in sorted(work_dir.iterdir()):
+            if path.name in {STDOUT_FILE, STDERR_FILE, EXIT_CODE_FILE}:
+                continue
+            if path.is_file():
+                outputs[path.stem] = str(path.relative_to(run_dir))
+            elif path.is_dir():
+                outputs[path.name] = str(path.relative_to(run_dir))
+
+        return outputs
+
+    def detect_status(self, run_dir: Path) -> str:
+        """Determine simulation status from ``work/exit_code`` and logs.
+
+        The detection logic is:
+
+        1. If ``work/exit_code`` exists and contains ``0``, return
+           ``"completed"``.
+        2. If ``work/exit_code`` exists with a non-zero value, return
+           ``"failed"``.
+        3. If ``work/`` contains output files but no exit code, return
+           ``"running"``.
+        4. Otherwise return ``"unknown"``.
+
+        Args:
+            run_dir: The run directory.
+
+        Returns:
+            A status string.
+        """
+        work_dir = run_dir / WORK_DIR
+        exit_code_path = work_dir / EXIT_CODE_FILE
+
+        if exit_code_path.exists():
+            try:
+                code = int(exit_code_path.read_text().strip())
+            except (ValueError, OSError):
+                return "unknown"
+            return "completed" if code == 0 else "failed"
+
+        # No exit code yet -- check whether work/ has any content
+        if work_dir.is_dir() and any(work_dir.iterdir()):
+            return "running"
+
+        return "unknown"
+
+    def summarize(self, run_dir: Path) -> dict[str, Any]:
+        """Produce a basic summary of the run.
+
+        For the generic adapter this includes:
+        - detected outputs (file listing)
+        - detected status
+        - exit code (if available)
+
+        Args:
+            run_dir: The run directory.
+
+        Returns:
+            Summary dictionary.
+        """
+        summary: dict[str, Any] = {}
+        errors: list[str] = []
+
+        try:
+            summary["status"] = self.detect_status(run_dir)
+        except Exception as exc:
+            errors.append(f"detect_status: {exc}")
+            summary["status"] = "unknown"
+
+        try:
+            summary["outputs"] = self.detect_outputs(run_dir)
+        except Exception as exc:
+            errors.append(f"detect_outputs: {exc}")
+            summary["outputs"] = {}
+
+        exit_code_path = run_dir / WORK_DIR / EXIT_CODE_FILE
+        if exit_code_path.exists():
+            try:
+                summary["exit_code"] = int(exit_code_path.read_text().strip())
+            except (ValueError, OSError) as exc:
+                errors.append(f"exit_code: {exc}")
+
+        if errors:
+            summary["errors"] = errors
+
+        return summary
+
+    def collect_provenance(
+        self,
+        runtime_info: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Collect provenance information from *runtime_info*.
+
+        Gathers:
+        - resolver mode
+        - executable path and SHA-256 hash (if the file exists)
+        - source repository git commit (if ``local_source`` mode)
+
+        Args:
+            runtime_info: Output from :meth:`resolve_runtime`.
+
+        Returns:
+            Provenance dictionary.
+        """
+        provenance: dict[str, Any] = {
+            "resolver_mode": runtime_info.get("resolver_mode", ""),
+            "executable": runtime_info.get("executable", ""),
+            "exe_hash": "",
+            "git_commit": "",
+            "git_dirty": False,
+            "source_repo": runtime_info.get("source_repo", ""),
+            "build_command": runtime_info.get("build_command", ""),
+            "package_version": runtime_info.get("package_version", ""),
+        }
+
+        # Executable hash
+        exe_path = Path(runtime_info.get("executable", ""))
+        if exe_path.is_file():
+            provenance["exe_hash"] = _compute_file_hash(exe_path)
+
+        # Git provenance for local_source
+        if runtime_info.get("resolver_mode") == "local_source":
+            repo = runtime_info.get("source_repo", "")
+            if repo:
+                git_info = _collect_git_info(Path(repo))
+                provenance["git_commit"] = git_info.get("commit", "")
+                provenance["git_dirty"] = git_info.get("dirty", False)
+
+        return provenance
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _compute_file_hash(path: Path) -> str:
+    """Return ``sha256:<hex>`` hash of a file.
+
+    Args:
+        path: Path to the file.
+
+    Returns:
+        Hash string prefixed with ``sha256:``.
+    """
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return f"sha256:{h.hexdigest()}"
+
+
+def _collect_git_info(repo_path: Path) -> dict[str, Any]:
+    """Collect basic git info from a repository path.
+
+    Args:
+        repo_path: Path to the git repository root.
+
+    Returns:
+        Dictionary with ``commit``, ``dirty``, and ``branch`` keys.
+        Returns empty values on failure rather than raising.
+    """
+    info: dict[str, Any] = {"commit": "", "dirty": False, "branch": ""}
+    if not repo_path.is_dir():
+        return info
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=repo_path,
+            check=False,
+        )
+        if result.returncode == 0:
+            info["commit"] = result.stdout.strip()
+
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            cwd=repo_path,
+            check=False,
+        )
+        if result.returncode == 0:
+            info["dirty"] = bool(result.stdout.strip())
+
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=repo_path,
+            check=False,
+        )
+        if result.returncode == 0:
+            info["branch"] = result.stdout.strip()
+    except FileNotFoundError:
+        logger.debug("git not found on PATH; skipping git provenance")
+
+    return info

runops/adapters/registry.py

@@ -0,0 +1,244 @@
+"""Adapter registry for looking up simulator adapters by name.
+
+Provides both a module-level functional API and an ``AdapterRegistry`` class
+for explicit lifetime control.  The module-level functions delegate to a
+shared global instance.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from runops.adapters.base import SimulatorAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class AdapterRegistry:
+    """Registry that maps simulator names to adapter classes.
+
+    Attributes:
+        _entries: Internal mapping from name to adapter class.
+    """
+
+    def __init__(self) -> None:
+        self._entries: dict[str, type[SimulatorAdapter]] = {}
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        adapter_cls: type[SimulatorAdapter],
+        *,
+        name: str | None = None,
+    ) -> type[SimulatorAdapter]:
+        """Register a simulator adapter class.
+
+        Can be used as a decorator::
+
+            @registry.register
+            class MyAdapter(SimulatorAdapter):
+                adapter_name = "my_sim"
+
+        Args:
+            adapter_cls: The adapter class to register.
+            name: Explicit adapter name.  If not provided, reads the
+                ``name`` property from a temporary instance or the
+                ``adapter_name`` class attribute.
+
+        Returns:
+            The adapter class (unchanged).
+
+        Raises:
+            ValueError: If an adapter with the same name is already
+                registered.
+            AttributeError: If no name can be resolved.
+        """
+        resolved_name = self._resolve_name(adapter_cls, name)
+        if resolved_name in self._entries:
+            msg = f"Adapter already registered: {resolved_name}"
+            raise ValueError(msg)
+        self._entries[resolved_name] = adapter_cls
+        logger.debug(
+            "Registered adapter '%s' -> %s", resolved_name, adapter_cls.__name__
+        )
+        return adapter_cls
+
+    # ------------------------------------------------------------------
+    # Lookup
+    # ------------------------------------------------------------------
+
+    def get(self, name: str) -> type[SimulatorAdapter]:
+        """Retrieve a registered adapter class by name.
+
+        Args:
+            name: Canonical adapter name.
+
+        Returns:
+            The adapter class.
+
+        Raises:
+            KeyError: If no adapter is registered under the given name.
+        """
+        if name not in self._entries:
+            msg = f"Unknown adapter: {name}. Available: {self.list_adapters()}"
+            raise KeyError(msg)
+        return self._entries[name]
+
+    def list_adapters(self) -> list[str]:
+        """Return the names of all registered adapters.
+
+        Returns:
+            Sorted list of adapter names.
+        """
+        return sorted(self._entries)
+
+    # ------------------------------------------------------------------
+    # Config loading
+    # ------------------------------------------------------------------
+
+    def load_from_config(self, simulators_config: dict[str, Any]) -> None:
+        """Auto-register adapters referenced in a simulators.toml config.
+
+        For each simulator entry that specifies an ``adapter`` key, this
+        method attempts to import and register the adapter module.  Entries
+        whose adapter is already registered are silently skipped.
+
+        The import convention is::
+
+            runops.adapters.<adapter_name>
+
+        Args:
+            simulators_config: The parsed ``[simulators]`` table from
+                ``simulators.toml``.
+        """
+        simulators = simulators_config.get("simulators", simulators_config)
+        for sim_name, sim_cfg in simulators.items():
+            if not isinstance(sim_cfg, dict):
+                continue
+            adapter_name = sim_cfg.get("adapter", "")
+            if not adapter_name or adapter_name in self._entries:
+                continue
+            # Try contrib/ first, then top-level adapters/
+            imported = False
+            for module_path in (
+                f"runops.adapters.contrib.{adapter_name}",
+                f"runops.adapters.{adapter_name}",
+            ):
+                try:
+                    importlib.import_module(module_path)
+                    logger.debug(
+                        "Auto-imported adapter module '%s' for simulator '%s'",
+                        module_path,
+                        sim_name,
+                    )
+                    imported = True
+                    break
+                except ImportError:
+                    continue
+            if not imported:
+                logger.warning(
+                    "Could not import adapter for simulator '%s'",
+                    sim_name,
+                )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _resolve_name(
+        adapter_cls: type[SimulatorAdapter],
+        explicit_name: str | None,
+    ) -> str:
+        """Determine the canonical name for an adapter class.
+
+        Args:
+            adapter_cls: The adapter class.
+            explicit_name: An explicitly provided name, if any.
+
+        Returns:
+            The resolved adapter name.
+
+        Raises:
+            AttributeError: If no name can be determined.
+        """
+        if explicit_name is not None:
+            return explicit_name
+        # Try class-level adapter_name attribute first
+        attr_name: str = getattr(adapter_cls, "adapter_name", "")
+        if attr_name:
+            return attr_name
+        msg = (
+            f"{adapter_cls.__name__} must define 'adapter_name' "
+            "or pass 'name' to register()"
+        )
+        raise AttributeError(msg)
+
+
+# ------------------------------------------------------------------
+# Global registry and module-level convenience functions
+# ------------------------------------------------------------------
+
+_global_registry = AdapterRegistry()
+
+
+def register(
+    adapter_cls: type[SimulatorAdapter],
+    *,
+    name: str | None = None,
+) -> type[SimulatorAdapter]:
+    """Register an adapter in the global registry.
+
+    Args:
+        adapter_cls: The adapter class to register.
+        name: Explicit adapter name.
+
+    Returns:
+        The adapter class (unchanged).
+    """
+    return _global_registry.register(adapter_cls, name=name)
+
+
+def get(name: str) -> type[SimulatorAdapter]:
+    """Retrieve an adapter class from the global registry.
+
+    Args:
+        name: Canonical adapter name.
+
+    Returns:
+        The adapter class.
+    """
+    return _global_registry.get(name)
+
+
+def list_adapters() -> list[str]:
+    """Return all adapter names in the global registry.
+
+    Returns:
+        Sorted list of adapter names.
+    """
+    return _global_registry.list_adapters()
+
+
+def load_from_config(simulators_config: dict[str, Any]) -> None:
+    """Load adapters into the global registry from simulators.toml config.
+
+    Args:
+        simulators_config: The parsed simulators configuration.
+    """
+    _global_registry.load_from_config(simulators_config)
+
+
+def get_global_registry() -> AdapterRegistry:
+    """Return the global ``AdapterRegistry`` instance.
+
+    Returns:
+        The shared global registry.
+    """
+    return _global_registry

runops/cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI entry points for runops."""
+
+from __future__ import annotations