runsim 0.1.0__py3-none-any.whl

runsim/__init__.py

@@ -0,0 +1,8 @@
+"""runsim -- Unified interface for running reservoir simulators."""
+
+from runsim.base import Simulator
+from runsim.dumux import DuMux
+from runsim.opm import OPMFlow
+
+__version__ = "0.1.0"
+__all__ = ["Simulator", "OPMFlow", "DuMux"]

runsim/base.py

@@ -0,0 +1,76 @@
+"""Abstract base class for reservoir simulators."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class Simulator(ABC):
+    """Base class for all simulator wrappers.
+
+    Subclasses must implement `_find_executable` and `run`.
+    """
+
+    def __init__(self, name: str, executable: str | None = None):
+        self.name = name
+        if executable is not None:
+            self.executable = Path(executable)
+        else:
+            self.executable = self._find_executable()
+
+    @abstractmethod
+    def _find_executable(self) -> Path:
+        """Locate the simulator binary on this system."""
+        ...
+
+    @abstractmethod
+    def run(
+        self,
+        deck_file: str | Path,
+        output_dir: str | Path,
+        **kwargs,
+    ) -> subprocess.CompletedProcess:
+        """Run a simulation and return the completed process."""
+        ...
+
+    def version(self) -> str:
+        """Return the simulator version string."""
+        if not self.is_available():
+            return "not installed"
+        try:
+            result = subprocess.run(
+                [str(self.executable), "--version"],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            output = result.stdout.strip() or result.stderr.strip()
+            return output.split("\n")[0] if output else "unknown"
+        except (subprocess.TimeoutExpired, OSError):
+            return "unknown"
+
+    def is_available(self) -> bool:
+        """Check if the simulator binary exists and is executable."""
+        return self.executable is not None and self.executable.is_file()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(executable={self.executable!r})"
+
+
+def find_in_paths(*candidates: str | Path) -> Path | None:
+    """Return the first existing executable from a list of candidate paths."""
+    for p in candidates:
+        path = Path(p)
+        if path.is_file():
+            return path
+    # Fall back to PATH lookup
+    return None
+
+
+def find_on_path(name: str) -> Path | None:
+    """Find an executable on the system PATH."""
+    found = shutil.which(name)
+    return Path(found) if found else None

runsim/dumux.py

@@ -0,0 +1,71 @@
+"""DuMux porous media simulator wrapper (stub)."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from runsim.base import Simulator
+
+
+class DuMux(Simulator):
+    """Run DuMux simulations.
+
+    This is a stub -- DuMux executables are problem-specific (each example
+    compiles to its own binary). Full integration will be added when
+    standard DuMux workflows are established.
+
+    Usage:
+        sim = DuMux(executable="/path/to/dumux_example")
+        result = sim.run(input_file="params.input", output_dir="./output")
+    """
+
+    def __init__(self, executable: str | None = None):
+        super().__init__(name="dumux", executable=executable)
+
+    def _find_executable(self) -> Path:
+        """Search for a DuMux binary in common locations."""
+        pkg_dir = Path(__file__).resolve().parent  # runsim/ (package)
+        project_root = pkg_dir.parent.parent  # opm/
+        install_dir = project_root / "dumux-build" / "dumux-install"
+
+        # DuMux doesn't have a single binary -- check install dir exists
+        if install_dir.is_dir():
+            # Return the install bin directory as a marker
+            bin_dir = install_dir / "bin"
+            if bin_dir.is_dir():
+                # Return first executable found, if any
+                for f in sorted(bin_dir.iterdir()):
+                    if f.is_file() and f.stat().st_mode & 0o111:
+                        return f
+        return Path("dumux")  # placeholder
+
+    def run(
+        self,
+        deck_file: str | Path = "",
+        output_dir: str | Path = ".",
+        **kwargs,
+    ) -> subprocess.CompletedProcess:
+        """Run a DuMux simulation.
+
+        Args:
+            deck_file: Path to input file (DuMux uses .input parameter files).
+            output_dir: Directory for simulation output.
+            **kwargs: Additional parameters.
+
+        Returns:
+            subprocess.CompletedProcess with stdout/stderr.
+        """
+        output_dir = Path(output_dir).resolve()
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        cmd = [str(self.executable)]
+
+        if deck_file:
+            cmd.append(str(Path(deck_file).resolve()))
+
+        for key, value in kwargs.items():
+            cmd.append(f"-{key}")
+            cmd.append(str(value))
+
+        return subprocess.run(cmd, capture_output=True, text=True, cwd=output_dir)

runsim/opm.py

@@ -0,0 +1,93 @@
+"""OPM Flow reservoir simulator wrapper."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from runsim.base import Simulator, find_in_paths, find_on_path
+
+
+class OPMFlow(Simulator):
+    """Run OPM Flow simulations (native or Docker).
+
+    Usage:
+        sim = OPMFlow()                         # auto-detect executable
+        sim = OPMFlow(mode="docker")            # use Docker wrapper
+        sim = OPMFlow(executable="/path/to/flow")  # explicit path
+
+        result = sim.run("SPE1CASE1.DATA", output_dir="./output")
+    """
+
+    def __init__(
+        self,
+        mode: str = "native",
+        executable: str | None = None,
+    ):
+        self.mode = mode  # "native" or "docker"
+        super().__init__(name="opm-flow", executable=executable)
+
+    def _find_executable(self) -> Path:
+        """Search for the flow binary in common locations."""
+        # Determine project paths relative to this file
+        pkg_dir = Path(__file__).resolve().parent  # runsim/ (package)
+        project_dir = pkg_dir.parent  # runsim/ (project root)
+        project_root = project_dir.parent  # opm/
+        venv_dir = project_dir / ".venv"
+
+        if self.mode == "docker":
+            candidates = [
+                venv_dir / "bin" / "flow-docker",
+            ]
+        else:
+            candidates = [
+                venv_dir / "bin" / "flow",
+                project_root / "opm-build" / "opm-install" / "bin" / "flow",
+            ]
+
+        found = find_in_paths(*candidates)
+        if found is not None:
+            return found
+
+        # Try system PATH
+        binary_name = "flow-docker" if self.mode == "docker" else "flow"
+        on_path = find_on_path(binary_name)
+        if on_path is not None:
+            return on_path
+
+        # Return the most likely path even if it doesn't exist yet
+        return candidates[0] if candidates else Path("flow")
+
+    def run(
+        self,
+        deck_file: str | Path,
+        output_dir: str | Path,
+        **kwargs,
+    ) -> subprocess.CompletedProcess:
+        """Run an OPM Flow simulation.
+
+        Args:
+            deck_file: Path to the .DATA deck file.
+            output_dir: Directory for simulation output.
+            **kwargs: Additional flags passed as --key=value.
+
+        Returns:
+            subprocess.CompletedProcess with stdout/stderr.
+        """
+        deck_file = Path(deck_file).resolve()
+        output_dir = Path(output_dir).resolve()
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        cmd = [
+            str(self.executable),
+            f"--output-dir={output_dir}",
+        ]
+
+        # Add extra keyword arguments as --key=value flags
+        for key, value in kwargs.items():
+            flag = key.replace("_", "-")
+            cmd.append(f"--{flag}={value}")
+
+        cmd.append(str(deck_file))
+
+        return subprocess.run(cmd, capture_output=True, text=True)

runsim-0.1.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: runsim
+Version: 0.1.0
+Summary: Unified interface for running reservoir simulators
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# runsim
+
+> **Note:** This package is under active development. APIs and CLI interfaces may change.
+
+Unified runner for reservoir simulators, data assimilation, and optimization on macOS.
+
+## Structure
+
+```
+runsim/
+├── runsim.sh                 # Unified CLI entry point
+├── pyproject.toml            # Python package config (uv + hatchling)
+├── runsim/                   # Python package (flat layout)
+│   ├── __init__.py
+│   ├── base.py               #   Abstract Simulator class
+│   ├── opm.py                #   OPM Flow wrapper
+│   └── dumux.py              #   DuMux wrapper (stub)
+├── simulators/
+│   ├── common.sh             # Shared helpers + path resolution
+│   ├── setup_env.sh          # Create venv, install packages, Docker setup
+│   ├── opm/                  # OPM Flow simulator
+│   │   ├── README.md
+│   │   ├── install.sh        #   Build from source (macOS)
+│   │   ├── install-docker.sh #   Install via Docker
+│   │   ├── run.sh            #   Run bundled test suite (native)
+│   │   ├── run-docker.sh     #   Run bundled test suite (Docker)
+│   │   └── Dockerfile
+│   ├── pet/                  # Python Ensemble Toolbox
+│   │   ├── README.md
+│   │   ├── install.sh        #   Download repos + pip install
+│   │   └── run.sh            #   Run PET examples (DA/optimization)
+│   ├── jutuldarcy/           # JutulDarcy simulator
+│   │   ├── README.md
+│   │   ├── install.sh        #   Install Python/Julia mode
+│   │   └── run.sh            #   Run simulations
+│   └── dumux/                # DuMux simulator
+│       ├── README.md
+│       ├── install.sh        #   Build from source (macOS)
+│       ├── run.sh            #   Run simulations
+│       └── Dockerfile
+└── .venv/                    # Python virtual environment (auto-created)
+```
+
+## Quick Start
+
+```bash
+# 1. Set up environment (venv + packages + OPM Docker)
+./runsim.sh setup
+
+# 2. List available PET examples
+./runsim.sh pet --list
+
+# 3. Run an example
+./runsim.sh pet Quadratic           # Analytic (no Docker needed)
+./runsim.sh pet 3dBox/tiny          # OPM Flow (~2 min)
+```
+
+## CLI
+
+```
+./runsim.sh <command> [args...]
+
+Commands:
+  flow [flow-args...]           Run native OPM Flow (passthrough to binary)
+  flow-docker [flow-args...]    Run OPM Flow via Docker (passthrough)
+  jutuldarcy [args...]          Run JutulDarcy simulation
+  dumux [args...]               Run DuMux simulation
+  dumux-docker [args...]        Run DuMux via Docker
+  pet [options] <example>       Run PET example (data assimilation / optimization)
+  setup                         Bootstrap environment (venv, PET, Docker)
+  help                          Show help
+```
+
+### Running Simulators
+
+```bash
+# OPM Flow (native) -- passthrough to flow binary
+./runsim.sh flow --version
+./runsim.sh flow --output-dir=./out SPE1CASE1.DATA
+
+# OPM Flow (Docker)
+./runsim.sh flow-docker --version
+./runsim.sh flow-docker --output-dir=./out SPE1CASE1.DATA
+
+# JutulDarcy
+./runsim.sh jutuldarcy --test
+./runsim.sh jutuldarcy /path/to/DECK.DATA
+
+# DuMux
+./runsim.sh dumux /path/to/executable
+```
+
+### Running PET Examples
+
+```bash
+./runsim.sh pet --list                                # List available examples
+./runsim.sh pet LinearModel                           # Analytic DA
+./runsim.sh pet 3dBox/tiny                            # 10x10x2 grid (~2 min)
+./runsim.sh pet --simulator flow 3dBox/tiny           # Native OPM Flow (default)
+./runsim.sh pet --simulator flow-docker 3dBox/tiny    # Docker
+./runsim.sh pet 3SpotRobust --variant bhp             # Specific variant
+./runsim.sh pet --clean 3dBox/tiny                    # Clean outputs then run
+```
+
+### Bundled Test Suites
+
+Per-simulator test suites are available via direct script access:
+
+```bash
+./simulators/opm/run.sh                               # Native OPM, all cases
+./simulators/opm/run-docker.sh                         # Docker, all cases
+./simulators/jutuldarcy/run.sh --test                  # JutulDarcy SPE1
+```
+
+## Simulators
+
+### OPM Flow (Docker) -- Recommended for quick start
+
+Runs via Docker on any platform. Simplest setup.
+
+```bash
+./simulators/opm/install-docker.sh          # Pull image + create flow wrapper
+./simulators/opm/install-docker.sh --test   # + run SPE1 validation
+```
+
+> Apple Silicon note: The Docker image is `linux/amd64` and runs under Rosetta/QEMU emulation.
+
+### OPM Flow (Native macOS)
+
+Full ARM-native performance. Builds Dune 2.10 + OPM from source.
+
+```bash
+./simulators/opm/install.sh              # Full build (~30-60 min, skips if installed)
+./simulators/opm/install.sh --deps-only  # Homebrew + Dune only
+./simulators/opm/install.sh --test       # Build + SPE1 test
+./simulators/opm/install.sh --rebuild    # Force full rebuild
+```
+
+Requires: Xcode CLI tools, Homebrew, cmake, boost, suite-sparse, cjson, fmt.
+
+### JutulDarcy
+
+Differentiable reservoir simulator (Julia). Two modes available:
+
+```bash
+./simulators/jutuldarcy/install.sh              # Python mode (pip install jutuldarcy)
+./simulators/jutuldarcy/install.sh --julia      # Julia mode (JutulDarcy.jl + juliacall)
+./simulators/jutuldarcy/install.sh --both       # Both modes
+./simulators/jutuldarcy/install.sh --test       # Install + verify
+```
+
+### DuMux
+
+DUNE-based porous media simulator. Builds from source.
+
+```bash
+./simulators/dumux/install.sh              # Full build (shares Dune with OPM if available)
+./simulators/dumux/install.sh --deps-only  # Homebrew + Dune only
+./simulators/dumux/install.sh --rebuild    # Force full rebuild
+```
+
+### PET (Python Ensemble Toolbox)
+
+Download PET repositories and install Python packages:
+
+```bash
+./simulators/pet/install.sh            # Download repos + pip install PET/SimulatorWrap
+./simulators/pet/install.sh --status   # Show which repos/packages are present
+```
+
+### Verifying Installations
+
+```bash
+./runsim.sh flow --version             # e.g. "flow 2026.04-pre"
+./runsim.sh flow-docker --version      # e.g. "flow 2025.10"
+
+# JutulDarcy (Python mode)
+.venv/bin/python -c "import jutuldarcy; print(jutuldarcy.__version__)"
+
+# runsim Python package
+.venv/bin/python -c "from runsim import OPMFlow; print(OPMFlow().version())"
+```
+
+## Python Package
+
+The `runsim` package provides a programmatic interface to simulators:
+
+```python
+from runsim import OPMFlow
+
+sim = OPMFlow()                         # auto-detect native binary
+sim = OPMFlow(mode="docker")            # use Docker wrapper
+
+# Check availability
+print(sim.version())                    # "flow 2026.04-pre"
+print(sim.is_available())               # True
+
+# Run a simulation
+result = sim.run("SPE1CASE1.DATA", output_dir="./output")
+print(result.returncode)                # 0 on success
+```
+
+## PET Examples
+
+```
+EXAMPLE                TYPE   SIMULATOR  NOTES
+───────                ────   ─────────  ─────
+LinearModel            DA     none
+3dBox/tiny             DA     flow       needs data generation
+3dBox/small            DA     flow       needs data generation
+3dBox/medium           DA     flow       needs data generation
+3dBox/large            DA     flow       needs data generation
+3dBox/flowrock         DA     flow       needs data generation
+Spe11b                 DA     flow       needs data generation
+3Spot                  Opt    flow
+3SpotRobust            Opt    flow       variants: bhp, rate
+3SpotEcalc             Opt    flow
+5SpotInverted          Opt    flow
+5SpotLineSearch        Opt    flow
+Rosenbrock             Opt    none
+Quadratic              Opt    none
+```
+
+Type: **DA** = Data Assimilation (ES-MDA), **Opt** = Optimization
+
+## Dependencies
+
+- **Python 3.11+**
+- **uv** (recommended) or pip
+- **Docker Desktop** (for OPM Flow Docker mode)
+- [PET](https://github.com/Python-Ensemble-Toolbox) -- data assimilation framework
+- [SimulatorWrap](https://github.com/Python-Ensemble-Toolbox) -- simulator wrappers
+- [OPM Flow](https://opm-project.org/) -- reservoir simulator
+- [JutulDarcy.jl](https://github.com/sintefmath/JutulDarcy.jl) -- differentiable simulator (optional)
+- [DuMux](https://dumux.org/) -- porous media simulator (optional)
+
+## Parent Repository Layout
+
+```
+project/
+├── runsim/                   # This project
+├── pet-repos/
+│   ├── PET-main/             # Python Ensemble Toolbox source
+│   ├── SimulatorWrap-main/   # Simulator wrapper source
+│   └── Examples-main/        # PET example cases
+├── opm-repos/
+│   └── opm-data-master/      # Standard OPM test data (SPE1-9, Norne)
+├── opm-build/                # Native OPM build artifacts (if built)
+└── dumux-build/              # Native DuMux build artifacts (if built)
+```

runsim-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+runsim/__init__.py,sha256=MjHmKmESySDirrqpQSjs0CVN5IG1GmedPlIEqfSGFlM,232
+runsim/base.py,sha256=bI3a_GXPpxKxWiysTggjev-TGMEfC45X2MZsrV07u3g,2254
+runsim/dumux.py,sha256=W1-CsERb51FXFm9xZ1HCjSO2ApSHtcbLa35L1euXA5U,2362
+runsim/opm.py,sha256=Diyc9pTb7beVDeeGHt-Md6aWfphkP6kx1Q6QWFZholw,2907
+runsim-0.1.0.dist-info/METADATA,sha256=OTnHvDE6C_DYM96sa8ZXdSpCF6Q6zqc5XKjOpmJgkiQ,9119
+runsim-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+runsim-0.1.0.dist-info/licenses/LICENSE,sha256=aGB5s5F-X6HF1RzssFMwzlq3gFgxTIx8xX8OIvrfaV8,1072
+runsim-0.1.0.dist-info/RECORD,,

runsim-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

runsim-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Roman Manasipov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.