interface.py

"""High-level interface for model potentials and external calculations.

Provides a small, test-friendly API surface that wraps:

- Rosenbrock function and gradient (via `potentials.py`)
- Müller–Brown potential and gradient (via `potentials.py`)
- Turbomole preparation / (optional) run helpers
- Hummr template insertion / (optional) run helpers

Design notes:
- This module avoids running external binaries by default. `run_*` helpers take
  `run=False` by default; when `run=True` they attempt to call subprocess, and
  will raise a friendly exception if the executable is not available.
- The Molecule class from `molecule.py` is used to prepare coordinates and
  to insert the molecule into Hummr templates.
"""
from __future__ import annotations

from typing import Sequence, Optional
import subprocess
import shlex
import os

from potentials import rosenbrock, rosenbrock_grad, muller_brown, muller_brown_grad
from molecule import Molecule


class ExternalProgramNotFound(RuntimeError):
    """Raised when a requested external program is not found on PATH."""


# -------------------- potentials wrappers --------------------

def rosenbrock_value(x: Sequence[float], a: float = 1.0, b: float = 100.0) -> float:
    """Compute Rosenbrock function value.

    Thin wrapper around `potentials.rosenbrock` kept for consistent interface.
    """
    return rosenbrock(x, a=a, b=b)


def rosenbrock_gradient(x: Sequence[float], a: float = 1.0, b: float = 100.0):
    """Return gradient of Rosenbrock as numpy array.

    Requires numpy; the underlying function will raise a RuntimeError if numpy
    is not available.
    """
    return rosenbrock_grad(x, a=a, b=b)


def muller_brown_value(xy: Sequence[float]) -> float:
    """Evaluate Müller–Brown potential at 2D point (x,y)."""
    return muller_brown(xy)


def muller_brown_gradient(xy: Sequence[float]):
    """Return gradient of Müller–Brown potential at 2D point (x,y)."""
    return muller_brown_grad(xy)


# -------------------- turbomole and hummr helpers (re-exports) --------------------
# Import and re-export the helper functions from the respective modules so tests
# can import them from this high-level `interface` module.
from turbomole_interface import (
    prepare_turbomole_coord,
    run_turbomole,
    turbomole_prepare_and_maybe_run,
    ExternalProgramNotFound as _TURBO_EXTERNAL,
)
from hummr_interface import (
    prepare_hummr_input,
    run_hummr,
    hummr_prepare_and_maybe_run,
)

# Expose a consistent ExternalProgramNotFound name from the turbomole module
# so callers importing it from `interface` get the same class used by helpers.
ExternalProgramNotFound = _TURBO_EXTERNAL