gundam-interface 0.1.0__py3-none-any.whl

gundam_interface/__init__.py

@@ -0,0 +1,38 @@
+"""Public package interface for gundam-interface."""
+
+from ._version import __version__
+from .config import GundamContext
+from .interface import GundamInterface, PostfitThrowSamples
+from .logging import (
+    isNotebookRuntime,
+    maybeRedirectNativeOutput,
+    redirectNativeOutput,
+    temporaryRedirectNativeOutput,
+)
+from .parameters import (
+    GundamParameter,
+    collectActiveParameters,
+    normalizedToPhysical,
+    parameterPriors,
+    parameterSteps,
+    parameterThrowValues,
+    physicalToNormalized,
+)
+
+__all__ = [
+    "__version__",
+    "GundamContext",
+    "GundamInterface",
+    "GundamParameter",
+    "PostfitThrowSamples",
+    "collectActiveParameters",
+    "isNotebookRuntime",
+    "maybeRedirectNativeOutput",
+    "normalizedToPhysical",
+    "parameterPriors",
+    "parameterSteps",
+    "parameterThrowValues",
+    "physicalToNormalized",
+    "redirectNativeOutput",
+    "temporaryRedirectNativeOutput",
+]

gundam_interface/_version.py

@@ -0,0 +1,8 @@
+"""Package version."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gundam-interface")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

gundam_interface/config.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(slots=True)
+class GundamContext:
+    """Runtime context needed to construct the GUNDAM Python interface."""
+
+    nCpuThreads: int
+    pythonPath: str | Path
+    workDir: str | Path
+    configPath: str | Path | None = None
+    overrideList: list[str | Path] = field(default_factory=list)
+    configJsonString: str | None = None
+    forceAsimov: bool | None = None
+    dataType: str | None = None
+    randomSeed: int | None = None
+
+    def __post_init__(self) -> None:
+        self.pythonPath = Path(self.pythonPath).expanduser()
+        self.workDir = Path(self.workDir).expanduser()
+        if self.configPath is not None:
+            self.configPath = Path(self.configPath).expanduser()
+        self.overrideList = [Path(path).expanduser() for path in self.overrideList]
+        if self.configJsonString is not None:
+            self.configJsonString = self.configJsonString.strip()
+
+        if self.nCpuThreads < 1:
+            raise ValueError("nCpuThreads must be >= 1")
+        if self.randomSeed is not None:
+            self.randomSeed = int(self.randomSeed)
+            if self.randomSeed < 0:
+                raise ValueError("randomSeed must be >= 0")
+        if self.configPath is None and self.configJsonString is None:
+            raise ValueError("Either configPath or configJsonString must be provided")
+        self.dataType = self._canonicalDataType(self.dataType, self.forceAsimov)
+
+    @classmethod
+    def fromDict(cls, data: dict[str, Any]) -> "GundamContext":
+        return cls(
+            nCpuThreads=int(data["nCpuThreads"]),
+            pythonPath=data["pythonPath"],
+            workDir=data["workDir"],
+            configPath=data.get("configPath"),
+            overrideList=list(data.get("overrideList", [])),
+            configJsonString=data.get("configJsonString"),
+            forceAsimov=data.get("forceAsimov", data.get("useAsimov")),
+            dataType=data.get("dataType"),
+            randomSeed=data.get("randomSeed", data.get("seed")),
+        )
+
+    @classmethod
+    def fromJsonFile(cls, path: str | Path) -> "GundamContext":
+        with Path(path).open("r", encoding="utf-8") as file:
+            return cls.fromDict(json.load(file))
+
+    def toDict(self, includeConfigJsonString: bool = True) -> dict[str, Any]:
+        data = {
+            "nCpuThreads": self.nCpuThreads,
+            "pythonPath": str(self.pythonPath),
+            "workDir": str(self.workDir),
+            "dataType": self.dataType,
+        }
+        if self.randomSeed is not None:
+            data["randomSeed"] = self.randomSeed
+        if self.configJsonString is not None:
+            if includeConfigJsonString:
+                data["configJsonString"] = self.configJsonString
+        else:
+            data["configPath"] = str(self.configPath)
+            data["overrideList"] = [str(path) for path in self.overrideList]
+        return data
+
+    def toJsonFile(self, path: str | Path) -> None:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("w", encoding="utf-8") as file:
+            json.dump(self.toDict(), file, indent=2, sort_keys=True)
+            file.write("\n")
+
+    @staticmethod
+    def _canonicalDataType(dataType: str | None, forceAsimov: bool | None) -> str:
+        if dataType is None:
+            if forceAsimov is None or forceAsimov:
+                return "Asimov"
+            return "RealData"
+
+        normalized = dataType.replace("_", "").replace("-", "").lower()
+        aliases = {
+            "asimov": "Asimov",
+            "toy": "Toy",
+            "realdata": "RealData",
+            "real": "RealData",
+            "data": "RealData",
+        }
+        try:
+            return aliases[normalized]
+        except KeyError as error:
+            raise ValueError(
+                "dataType must be one of: Asimov, Toy, RealData"
+            ) from error
+
+    @property
+    def absoluteConfigPath(self) -> Path:
+        if self.configPath is None:
+            raise ValueError("No configPath is defined for this GundamContext")
+        if self.configPath.is_absolute():
+            return self.configPath
+        return self.workDir / self.configPath
+
+    @property
+    def absoluteOverridePaths(self) -> list[Path]:
+        overridePaths = []
+        for overridePath in self.overrideList:
+            if overridePath.is_absolute():
+                overridePaths.append(overridePath)
+            else:
+                overridePaths.append(self.workDir / overridePath)
+        return overridePaths
+
+    @property
+    def defaultInitializeLogPath(self) -> Path:
+        return self.workDir / "gundam_initialize.log"
+
+    @property
+    def defaultEvaluateLogPath(self) -> Path:
+        return self.workDir / "gundam_evaluate.log"
+
+    def validatePaths(self) -> None:
+        """Fail early on missing user-provided paths."""
+        if not self.pythonPath.exists():
+            raise FileNotFoundError(f"GUNDAM pythonPath does not exist: {self.pythonPath}")
+        if not self.workDir.exists():
+            raise FileNotFoundError(f"GUNDAM workDir does not exist: {self.workDir}")
+        if self.configJsonString is not None:
+            return
+        if not self.absoluteConfigPath.exists():
+            raise FileNotFoundError(f"GUNDAM config file does not exist: {self.absoluteConfigPath}")
+        for overridePath in self.absoluteOverridePaths:
+            if not overridePath.exists():
+                raise FileNotFoundError(f"GUNDAM override file does not exist: {overridePath}")

gundam_interface/interface.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+import tempfile
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterator
+
+import numpy as np
+
+from .config import GundamContext
+from .logging import maybeRedirectNativeOutput, temporaryRedirectNativeOutput
+from .parameters import (
+    GundamParameter,
+    collectActiveParameters,
+    normalizedToPhysical,
+    parameterPriors,
+    parameterSteps,
+    parameterThrowValues,
+    physicalToNormalized,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PostfitThrowSamples:
+    """GUNDAM post-fit throws with propagated likelihood evaluations."""
+
+    physicalValues: np.ndarray
+    normalizedValues: np.ndarray
+    llh: np.ndarray
+
+
+@contextmanager
+def preservedWorkingDirectory() -> Iterator[None]:
+    originalWorkingDirectory = Path.cwd()
+    try:
+        yield
+    finally:
+        os.chdir(originalWorkingDirectory)
+
+
+@contextmanager
+def temporaryWorkingDirectory(path: str | os.PathLike[str]) -> Iterator[None]:
+    originalWorkingDirectory = Path.cwd()
+    os.chdir(Path(path).expanduser().resolve())
+    try:
+        yield
+    finally:
+        os.chdir(originalWorkingDirectory)
+
+
+class GundamInterface:
+    """Thin Python wrapper around the GUNDAM fitting interface."""
+
+    def __init__(self, context: GundamContext):
+        self.context = context
+        self.gundam: Any | None = None
+        self.configBuilder: Any | None = None
+        self.configJsonString: str | None = None
+        self.fitterEngineConfig: Any | None = None
+        self.engine: Any | None = None
+        self.parameters: list[GundamParameter] = []
+
+    @property
+    def isConfigured(self) -> bool:
+        return self.engine is not None
+
+    @property
+    def isInitialized(self) -> bool:
+        return bool(self.parameters)
+
+    @property
+    def priors(self) -> np.ndarray:
+        return parameterPriors(self.parameters)
+
+    @property
+    def stepSizes(self) -> np.ndarray:
+        return parameterSteps(self.parameters)
+
+    @property
+    def throwValues(self) -> np.ndarray | None:
+        return parameterThrowValues(self.parameters)
+
+    @property
+    def parameterNames(self) -> list[str]:
+        return [parameter.name for parameter in self.parameters]
+
+    def setupPythonPath(self) -> None:
+        pythonPath = str(self.context.pythonPath)
+        if pythonPath not in sys.path:
+            sys.path.insert(0, pythonPath)
+
+        existingPythonPath = os.environ.get("PYTHONPATH", "")
+        pythonPathParts = [part for part in existingPythonPath.split(os.pathsep) if part]
+        if pythonPath not in pythonPathParts:
+            os.environ["PYTHONPATH"] = os.pathsep.join([pythonPath, *pythonPathParts])
+
+    def importGundam(self):
+        self.setupPythonPath()
+        self.gundam = importlib.import_module("GUNDAM")
+        return self.gundam
+
+    def configure(self, validatePaths: bool = True) -> None:
+        with preservedWorkingDirectory():
+            if validatePaths:
+                self.context.validatePaths()
+
+            gundam = self.importGundam()
+            gundam.setLightOutputMode(False)
+            gundam.setNumberOfThreads(self.context.nCpuThreads)
+            workingDirectory = Path(self.context.workDir).expanduser().resolve()
+            gundam.setRuntimeWorkingDirectory(str(workingDirectory))
+
+            with temporaryWorkingDirectory(workingDirectory):
+                configBuilder = self._buildConfigBuilder(gundam)
+                configJsonString = configBuilder.toString()
+
+                configReader = gundam.ConfigUtils.ConfigReader(configBuilder.getConfig())
+                configReader.defineField(
+                    gundam.ConfigUtils.ConfigReader.FieldDefinition("fitterEngineConfig")
+                )
+                fitterEngineConfig = configReader.fetchValueConfigReader("fitterEngineConfig")
+
+            engine = gundam.FitterEngine()
+            engine.setConfig(fitterEngineConfig)
+            self._setEngineRandomSeed(engine, self.context.randomSeed)
+            with temporaryWorkingDirectory(workingDirectory):
+                engine.configure()
+
+            self.configBuilder = configBuilder
+            self.configJsonString = configJsonString
+            self.fitterEngineConfig = fitterEngineConfig
+            self.engine = engine
+
+    def _buildConfigBuilder(self, gundam):
+        if self.context.configJsonString is not None:
+            return self._buildConfigBuilderFromJsonString(gundam, self.context.configJsonString)
+
+        configPath = Path(self.context.absoluteConfigPath).expanduser().resolve()
+        overridePaths = [
+            Path(overridePath).expanduser().resolve()
+            for overridePath in self.context.absoluteOverridePaths
+        ]
+        configBuilder = gundam.ConfigUtils.ConfigBuilder(str(configPath))
+        for overridePath in overridePaths:
+            configBuilder.override(str(overridePath))
+        return configBuilder
+
+    @staticmethod
+    def _buildConfigBuilderFromJsonString(gundam, configJsonString: str):
+        # The Python binding exposes ConfigBuilder(str), but that overload expects a file path.
+        # Keep the public API string-based and isolate the temporary bridge here.
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=".json",
+            encoding="utf-8",
+            delete=True,
+        ) as configFile:
+            configFile.write(configJsonString)
+            configFile.flush()
+            return gundam.ConfigUtils.ConfigBuilder(str(configFile.name))
+
+    def initialize(
+        self,
+        logPath: str | os.PathLike[str] | None = None,
+    ) -> None:
+        with preservedWorkingDirectory():
+            self._requireConfigured()
+            workingDirectory = Path(self.context.workDir).expanduser().resolve()
+
+            if logPath is None:
+                redirectContext = temporaryRedirectNativeOutput("gundam_initialize")
+            else:
+                logPath = Path(logPath).expanduser().resolve()
+                redirectContext = maybeRedirectNativeOutput(logPath)
+
+            with temporaryWorkingDirectory(workingDirectory):
+                with redirectContext:
+                    self._setLikelihoodDataType()
+                    self.engine.initialize()
+
+            self.refreshParameters()
+
+    def refreshParameters(self) -> list[GundamParameter]:
+        self._requireConfigured()
+        parametersManager = (
+            self.engine.getLikelihoodInterface()
+            .getModelPropagator()
+            .getParametersManager()
+        )
+        self.parameters = collectActiveParameters(
+            parametersManager,
+            includeThrowValues=self.context.dataType == "Toy",
+        )
+        return self.parameters
+
+    def getParameterValues(self) -> np.ndarray:
+        self._requireParameters()
+        return np.array([parameter.value for parameter in self.parameters], dtype=np.float64)
+
+    def setParameterValues(self, values: np.ndarray) -> None:
+        self._requireParameters()
+        values = np.asarray(values, dtype=np.float64)
+        if values.shape != self.priors.shape:
+            raise ValueError(f"Expected parameter shape {self.priors.shape}, got {values.shape}")
+        for parameter, value in zip(self.parameters, values):
+            parameter.setValue(float(value))
+
+    def resetToPrior(self) -> None:
+        self._requireParameters()
+        for parameter in self.parameters:
+            parameter.resetToPrior()
+
+    def normalizedToPhysical(self, normalizedValues: np.ndarray) -> np.ndarray:
+        self._requireParameters()
+        return normalizedToPhysical(normalizedValues, self.priors, self.stepSizes)
+
+    def physicalToNormalized(self, physicalValues: np.ndarray) -> np.ndarray:
+        self._requireParameters()
+        return physicalToNormalized(physicalValues, self.priors, self.stepSizes)
+
+    def evaluateLlh(
+        self,
+        physicalValues: np.ndarray | None = None,
+        normalizedValues: np.ndarray | None = None,
+        logPath: str | os.PathLike[str] | None = None,
+    ) -> float:
+        with preservedWorkingDirectory():
+            self._requireParameters()
+            if physicalValues is not None and normalizedValues is not None:
+                raise ValueError("Provide either physicalValues or normalizedValues, not both")
+            if normalizedValues is not None:
+                physicalValues = self.normalizedToPhysical(normalizedValues)
+            if physicalValues is not None:
+                self.setParameterValues(physicalValues)
+
+            if logPath is not None:
+                logPath = Path(logPath).expanduser().resolve()
+            workingDirectory = Path(self.context.workDir).expanduser().resolve()
+
+            with temporaryWorkingDirectory(workingDirectory):
+                with maybeRedirectNativeOutput(logPath):
+                    self.engine.getLikelihoodInterface().propagateAndEvalLikelihood()
+                return float(self.engine.getLikelihoodInterface().getLastLikelihood())
+
+    def minimize(
+        self,
+        logPath: str | os.PathLike[str] | None = None,
+    ) -> float:
+        with preservedWorkingDirectory():
+            self._requireParameters()
+            if logPath is not None:
+                logPath = Path(logPath).expanduser().resolve()
+            workingDirectory = Path(self.context.workDir).expanduser().resolve()
+
+            with temporaryWorkingDirectory(workingDirectory):
+                with maybeRedirectNativeOutput(logPath):
+                    self.engine.getMinimizer().minimize()
+
+            self.refreshParameters()
+            return float(self.engine.getLikelihoodInterface().getLastLikelihood())
+
+    def evaluatePostfitThrows(
+        self,
+        nThrows: int,
+        logPath: str | os.PathLike[str] | None = None,
+        showProgress: bool = True,
+    ) -> PostfitThrowSamples:
+        """Throw post-fit parameters, propagate them, and evaluate their LLH.
+
+        The GUNDAM binding only exposes ``throwPostfitParameters()`` as a state
+        update on the minimizer. This method wraps that operation into a simple
+        batch interface. ``logPath`` is accepted for backward compatibility but
+        is intentionally ignored: native output is not redirected in this loop.
+        """
+        from tqdm.auto import tqdm
+
+        with preservedWorkingDirectory():
+            self._requireParameters()
+            if nThrows < 1:
+                raise ValueError("nThrows must be >= 1")
+            workingDirectory = Path(self.context.workDir).expanduser().resolve()
+
+            physicalValues = np.empty((nThrows, self.priors.shape[0]), dtype=np.float64)
+            normalizedValues = np.empty_like(physicalValues)
+            llh = np.empty(nThrows, dtype=np.float64)
+
+            with temporaryWorkingDirectory(workingDirectory):
+                minimizer = self.engine.getMinimizer()
+                likelihoodInterface = self.engine.getLikelihoodInterface()
+                throwIterator = range(nThrows)
+                if showProgress:
+                    throwIterator = tqdm(
+                        throwIterator,
+                        desc="GUNDAM post-fit throws",
+                        unit="throw",
+                    )
+                for throwIndex in throwIterator:
+                    minimizer.throwPostfitParameters()
+                    physicalValues[throwIndex] = self.getParameterValues()
+                    normalizedValues[throwIndex] = self.physicalToNormalized(
+                        physicalValues[throwIndex]
+                    )
+                    likelihoodInterface.propagateAndEvalLikelihood()
+                    llh[throwIndex] = float(likelihoodInterface.getLastLikelihood())
+
+            self.refreshParameters()
+            return PostfitThrowSamples(
+                physicalValues=physicalValues,
+                normalizedValues=normalizedValues,
+                llh=llh,
+            )
+
+    def setSeed(self, seed: int | None = None) -> None:
+        self._requireConfigured()
+        seed = self.context.randomSeed if seed is None else seed
+        self._setEngineRandomSeed(self.engine, seed)
+
+    @staticmethod
+    def _setEngineRandomSeed(engine, seed: int | None) -> None:
+        if seed is None:
+            return
+        seed = int(seed)
+        if seed < 0:
+            raise ValueError("seed must be >= 0")
+        type(engine).setRandomSeed(seed)
+
+    def _requireConfigured(self) -> None:
+        if self.engine is None:
+            raise RuntimeError("GundamInterface.configure() must be called first")
+
+    def _setLikelihoodDataType(self) -> None:
+        self._requireConfigured()
+        gundam = self.importGundam()
+        likelihoodInterface = self.engine.getLikelihoodInterface()
+        dataType = getattr(gundam.LikelihoodInterface.DataType, self.context.dataType)
+        likelihoodInterface.setDataType(dataType)
+
+    def _requireParameters(self) -> None:
+        self._requireConfigured()
+        if not self.parameters:
+            raise RuntimeError(
+                "No active parameters are loaded. Call initialize() or refreshParameters() first."
+            )

gundam_interface/logging.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+import tempfile
+import threading
+import time
+import uuid
+from contextlib import contextmanager, nullcontext
+from pathlib import Path
+from typing import Iterator
+
+
+def isNotebookRuntime() -> bool:
+    if "ipykernel" in sys.modules:
+        return True
+
+    try:
+        from IPython import get_ipython
+    except ModuleNotFoundError:
+        return False
+
+    shell = get_ipython()
+    if shell is None:
+        return False
+    if shell.__class__.__name__ == "ZMQInteractiveShell":
+        return True
+
+    config = getattr(shell, "config", {})
+    return "IPKernelApp" in config
+
+
+@contextmanager
+def redirectNativeOutput(
+    logPath: str | os.PathLike[str],
+    *,
+    stream: bool = False,
+) -> Iterator[None]:
+    """Redirect C/C++ stdout and stderr to a file.
+
+    This is useful in Jupyter where native C++ loggers can interact poorly with
+    ipykernel stdout capture. Python stdout/stderr are restored after the block.
+    When ``stream`` is true, new log content is also printed as it is written.
+    """
+    path = Path(logPath).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    libc = ctypes.CDLL(None)
+    sys.stdout.flush()
+    sys.stderr.flush()
+    libc.fflush(None)
+
+    stdoutFd = os.dup(1)
+    stderrFd = os.dup(2)
+    streamStopEvent: threading.Event | None = None
+    streamThread: threading.Thread | None = None
+
+    try:
+        with path.open("ab", buffering=0) as nativeLog:
+            streamOffset = nativeLog.tell()
+            if stream:
+                streamStopEvent = threading.Event()
+                streamThread = threading.Thread(
+                    target=_streamLogFile,
+                    args=(path, streamStopEvent, streamOffset, stdoutFd),
+                    daemon=True,
+                )
+                streamThread.start()
+            os.dup2(nativeLog.fileno(), 1)
+            os.dup2(nativeLog.fileno(), 2)
+            yield
+    finally:
+        sys.stdout.flush()
+        sys.stderr.flush()
+        libc.fflush(None)
+        if streamStopEvent is not None:
+            streamStopEvent.set()
+        if streamThread is not None:
+            streamThread.join(timeout=2.0)
+        os.dup2(stdoutFd, 1)
+        os.dup2(stderrFd, 2)
+        os.close(stdoutFd)
+        os.close(stderrFd)
+
+
+def maybeRedirectNativeOutput(
+    logPath: str | os.PathLike[str] | None,
+    *,
+    stream: bool = True,
+):
+    if logPath is None:
+        return nullcontext()
+    return redirectNativeOutput(logPath, stream=stream)
+
+
+@contextmanager
+def temporaryRedirectNativeOutput(prefix: str):
+    if not isNotebookRuntime():
+        yield
+        return
+
+    logPath = (
+        Path(tempfile.gettempdir())
+        / f"{prefix}_{os.getpid()}_{uuid.uuid4().hex[:8]}.log"
+    )
+    try:
+        with redirectNativeOutput(logPath):
+            yield
+    finally:
+        try:
+            if logPath.exists():
+                logContent = logPath.read_text(encoding="utf-8", errors="replace")
+                if logContent:
+                    print(logContent, end="" if logContent.endswith("\n") else "\n")
+        finally:
+            logPath.unlink(missing_ok=True)
+
+
+def _streamLogFile(
+    path: Path,
+    stopEvent: threading.Event,
+    startOffset: int,
+    outputFd: int,
+    pollInterval: float = 0.1,
+) -> None:
+    """Print bytes appended to ``path`` until ``stopEvent`` is set."""
+    try:
+        with path.open("rb") as logFile:
+            logFile.seek(startOffset)
+            while not stopEvent.is_set():
+                _streamAvailableLogBytes(logFile, outputFd)
+                time.sleep(pollInterval)
+            _streamAvailableLogBytes(logFile, outputFd)
+    except OSError:
+        return
+
+
+def _streamAvailableLogBytes(logFile, outputFd: int) -> None:
+    while True:
+        chunk = logFile.read(8192)
+        if not chunk:
+            return
+        if isNotebookRuntime():
+            sys.stdout.write(chunk.decode("utf-8", errors="replace"))
+            sys.stdout.flush()
+        else:
+            os.write(outputFd, chunk)