flowboost 0.2.2__tar.gz

flowboost-0.2.2/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: flowboost
+Version: 0.2.2
+Summary: Multi-objective Bayesian optimization library for OpenFOAM
+Keywords: OpenFOAM,CFD,Bayesian optimization,Multi-objective optimization,HPC,Cluster computing
+Author: Daniel Virokannas
+Author-email: Daniel Virokannas <46869890+499602D2@users.noreply.github.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Dist: ax-platform>=1.0
+Requires-Dist: coloredlogs>=15
+Requires-Dist: pandas>=2.2
+Requires-Dist: polars>=1.11
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyarrow>=15
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: tomlkit>=0.12
+Requires-Dist: polars-lts-cpu>=0.20 ; extra == 'lts-cpu'
+Maintainer: Daniel Virokannas, Bulut Tekgul
+Maintainer-email: Daniel Virokannas <46869890+499602D2@users.noreply.github.com>, Bulut Tekgul <bulut.tekgul@wartsila.com>
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/499602D2/flowboost
+Provides-Extra: lts-cpu
+Description-Content-Type: text/markdown
+
+# 🏄‍♂️ FlowBoost — Multi-objective Bayesian optimization for OpenFOAM
+
+![Python](https://img.shields.io/badge/python-3.10_%7C_3.11_%7C_3.12_%7C_3.13_%7C_3.14-blue)
+
+FlowBoost is a highly configurable and extensible library for handling and optimizing OpenFOAM CFD simulations. It provides ready bindings for state-of-the-art Bayesian optimization using Meta's Ax, powered by PyTorch, and simple interfaces for using any other optimization library.
+
+## Features
+- Easy API syntax (see `examples/`)
+- Ready bindings for [Meta's Ax (Adaptive Experimentation Platform)](https://ax.dev/)
+  - Multi-objective, high-dimensional Bayesian optimization
+  - SAASBO, GPU acceleration
+- Fully hands-off cluster-native job management
+- Simple interfaces for OpenFOAM cases (`flowboost.Case`)
+- Use any optimization backend by implementing a few interfaces
+
+## Examples
+The `examples/` directory contains code examples for simplified real-world scenarios:
+
+1. `aerofoilNACA0012Steady`: parameter optimization for a NACA 0012 aerofoil steady-state simulation
+
+By default, FlowBoost uses Ax's [Service API](https://ax.dev/) as its optimization backend. In practice, any optimizer can be used, as long as it conforms to the abstract `flowboost.optimizer.Backend` base class, which the backend interfaces in `flowboost.optimizer.interfaces` implement.
+
+## OpenFOAM case abstraction
+Working with OpenFOAM cases is performed through the `flowboost.Case` abstraction, which provides a high-level API for OpenFOAM case-data and configuration access. The `Case` abstraction can be used as-is outside of optimization workflows:
+
+```python
+from flowboost import Case
+
+# Clone tutorial to current working directory (or a specified dir)
+tutorial_case = Case.from_tutorial("fluid/aerofoilNACA0012Steady")
+
+# Dictionary read/write access
+control_dict = tutorial_case.dictionary("system/controlDict")
+control_dict.entry("writeInterval").set("5000")
+
+# Access data in an evaluated case
+case = Case("my/case/path")
+df = case.data.simple_function_object_reader("forceCoeffsCompressible")
+```
+
+## Installation
+FlowBoost requires Python 3.10 or later.
+
+### uv (recommended)
+```shell
+uv add flowboost
+```
+
+### pip
+```shell
+pip install flowboost
+```
+
+### CPU compatibility
+In order to use the standard `polars` package, your CPU should support AVX2 instructions ([and other SIMD instructions](https://github.com/pola-rs/polars/blob/78dc62851a13b87dc751a627e1e96ba1bf1549ee/py-polars/polars/_cpu_check.py)). These are typically available in Intel Broadwell/4000-series and later, and all AMD Zen-based CPUs.
+
+If your CPU is from 2012 or earlier, you will most likely receive an illegal instruction error. This can be solved by installing the `lts-cpu` extra:
+
+```shell
+uv add flowboost[lts-cpu]
+# or: pip install flowboost[lts-cpu]
+```
+
+This installs `polars-lts-cpu`, which is functionally identical but not as performant.
+
+## Development
+
+The project is packaged using [uv](https://docs.astral.sh/uv/). The code is linted and formatted using [Ruff](https://docs.astral.sh/ruff/).
+
+```shell
+uv sync
+uv run pytest
+```
+
+### GPU acceleration
+If your environment has a CUDA-compatible NVIDIA GPU, you should verify you have a recent CUDA Toolkit release. Otherwise, GPU acceleration for PyTorch will not be available. This is especially critical if you are using SAASBO for high-dimensional optimization tasks (≥20 dimensions).
+
+```shell
+nvcc -V
+
+# Verify CUDA availability
+python3 -c "import torch; print(torch.cuda.is_available())"
+```
+
+### Testing
+Passing the full test suite requires OpenFOAM to be installed and sourced. FlowBoost has only been tested using the [openfoam.org](https://openfoam.org/) lineage (not the ESI/openfoam.com fork), specifically version 11.
+
+If you wish to contribute code to the project, please ensure your contribution still passes the current test coverage.
+
+## Acknowledgments
+The base functionality for FlowBoost was created as part of a mechanical engineering master's thesis at Aalto University, funded by Wärtsilä. Wärtsilä designs and manufactures marine combustion engines and energy solutions in Vaasa, Finland.

flowboost-0.2.2/README.md

@@ -0,0 +1,91 @@
+# 🏄‍♂️ FlowBoost — Multi-objective Bayesian optimization for OpenFOAM
+
+![Python](https://img.shields.io/badge/python-3.10_%7C_3.11_%7C_3.12_%7C_3.13_%7C_3.14-blue)
+
+FlowBoost is a highly configurable and extensible library for handling and optimizing OpenFOAM CFD simulations. It provides ready bindings for state-of-the-art Bayesian optimization using Meta's Ax, powered by PyTorch, and simple interfaces for using any other optimization library.
+
+## Features
+- Easy API syntax (see `examples/`)
+- Ready bindings for [Meta's Ax (Adaptive Experimentation Platform)](https://ax.dev/)
+  - Multi-objective, high-dimensional Bayesian optimization
+  - SAASBO, GPU acceleration
+- Fully hands-off cluster-native job management
+- Simple interfaces for OpenFOAM cases (`flowboost.Case`)
+- Use any optimization backend by implementing a few interfaces
+
+## Examples
+The `examples/` directory contains code examples for simplified real-world scenarios:
+
+1. `aerofoilNACA0012Steady`: parameter optimization for a NACA 0012 aerofoil steady-state simulation
+
+By default, FlowBoost uses Ax's [Service API](https://ax.dev/) as its optimization backend. In practice, any optimizer can be used, as long as it conforms to the abstract `flowboost.optimizer.Backend` base class, which the backend interfaces in `flowboost.optimizer.interfaces` implement.
+
+## OpenFOAM case abstraction
+Working with OpenFOAM cases is performed through the `flowboost.Case` abstraction, which provides a high-level API for OpenFOAM case-data and configuration access. The `Case` abstraction can be used as-is outside of optimization workflows:
+
+```python
+from flowboost import Case
+
+# Clone tutorial to current working directory (or a specified dir)
+tutorial_case = Case.from_tutorial("fluid/aerofoilNACA0012Steady")
+
+# Dictionary read/write access
+control_dict = tutorial_case.dictionary("system/controlDict")
+control_dict.entry("writeInterval").set("5000")
+
+# Access data in an evaluated case
+case = Case("my/case/path")
+df = case.data.simple_function_object_reader("forceCoeffsCompressible")
+```
+
+## Installation
+FlowBoost requires Python 3.10 or later.
+
+### uv (recommended)
+```shell
+uv add flowboost
+```
+
+### pip
+```shell
+pip install flowboost
+```
+
+### CPU compatibility
+In order to use the standard `polars` package, your CPU should support AVX2 instructions ([and other SIMD instructions](https://github.com/pola-rs/polars/blob/78dc62851a13b87dc751a627e1e96ba1bf1549ee/py-polars/polars/_cpu_check.py)). These are typically available in Intel Broadwell/4000-series and later, and all AMD Zen-based CPUs.
+
+If your CPU is from 2012 or earlier, you will most likely receive an illegal instruction error. This can be solved by installing the `lts-cpu` extra:
+
+```shell
+uv add flowboost[lts-cpu]
+# or: pip install flowboost[lts-cpu]
+```
+
+This installs `polars-lts-cpu`, which is functionally identical but not as performant.
+
+## Development
+
+The project is packaged using [uv](https://docs.astral.sh/uv/). The code is linted and formatted using [Ruff](https://docs.astral.sh/ruff/).
+
+```shell
+uv sync
+uv run pytest
+```
+
+### GPU acceleration
+If your environment has a CUDA-compatible NVIDIA GPU, you should verify you have a recent CUDA Toolkit release. Otherwise, GPU acceleration for PyTorch will not be available. This is especially critical if you are using SAASBO for high-dimensional optimization tasks (≥20 dimensions).
+
+```shell
+nvcc -V
+
+# Verify CUDA availability
+python3 -c "import torch; print(torch.cuda.is_available())"
+```
+
+### Testing
+Passing the full test suite requires OpenFOAM to be installed and sourced. FlowBoost has only been tested using the [openfoam.org](https://openfoam.org/) lineage (not the ESI/openfoam.com fork), specifically version 11.
+
+If you wish to contribute code to the project, please ensure your contribution still passes the current test coverage.
+
+## Acknowledgments
+The base functionality for FlowBoost was created as part of a mechanical engineering master's thesis at Aalto University, funded by Wärtsilä. Wärtsilä designs and manufactures marine combustion engines and energy solutions in Vaasa, Finland.

flowboost-0.2.2/flowboost/config/config.py

@@ -0,0 +1,72 @@
+import importlib.resources as pkg_resources
+import logging
+import shutil
+from pathlib import Path
+
+import tomlkit
+
+DEFAULT_CONFIG_NAME: str = "flowboost_config.toml"
+
+
+def validate(config: dict) -> bool:
+    """Validate the TOML configuration file.
+
+    Args:
+        config_path (Path): The path to the TOML configuration file.
+
+    Returns:
+        bool: True if the configuration is valid, False otherwise.
+    """
+    # Check for offload_acquisition
+    offload_acquisition = config.get("scheduler", {}).get("offload_acquisition", False)
+
+    if offload_acquisition:
+        # Ensure acquisition configuration is present and valid
+        if "scheduler.acquisition" not in config:
+            logging.error(
+                "Offload acquisition is enabled, but `[scheduler.acquisition]` not configured"
+            )
+            return False
+
+    return True
+
+
+def create(dir: Path, filename: str = DEFAULT_CONFIG_NAME) -> dict:
+    with pkg_resources.path("flowboost.config", DEFAULT_CONFIG_NAME) as config_path:
+        if not config_path.exists():
+            raise FileNotFoundError(f"Configuration template not found [{config_path}]")
+
+        dest = Path(dir, filename)
+        if dest.exists():
+            raise FileExistsError("Configuration already exists, but create() called")
+
+        shutil.copy(config_path, dest)
+        with open(dest, "r") as config_file:
+            config = tomlkit.load(config_file)
+
+        if not validate(config):
+            raise ValueError("Default configuration is invalid")
+
+        return config
+
+
+def load(dir: Path, filename: str = DEFAULT_CONFIG_NAME) -> dict:
+    fpath = Path(dir, filename)
+
+    if not fpath.exists():
+        return create(dir=dir, filename=filename)
+
+    with open(fpath, "r") as toml_f:
+        config = tomlkit.load(toml_f)
+
+    if not validate(config):
+        raise ValueError("Configuration is invalid")
+
+    return config
+
+
+def save(config: dict, dir: Path, filename: str = DEFAULT_CONFIG_NAME):
+    fpath = Path(dir, filename)
+
+    with open(fpath, "w") as toml_f:
+        tomlkit.dump(config, toml_f)

flowboost-0.2.2/flowboost/config/optifoam_config.toml

@@ -0,0 +1,32 @@
+[session]
+name = ""
+data_dir = ""
+archival_dir = ""
+dataframe_format = "polars"
+created_at = ""
+
+[template]
+path = ""
+additional_files = []
+
+[optimizer]
+type = "Ax"
+offload_acquisition = false # Acquisition offloading in cluster env
+
+[scheduler]
+type = ""     # Manager-implementing class name
+job_limit = 1 # Also node reservation limit (TODO not always)
+
+[scheduler.OpenFOAM]
+# Can also be provided in your template case's Allrun script
+# args = { pe = "orte 36", M = "user@example.com", m = "base" }
+# setup = [
+#     "module load gnu openmpi",
+#     "source /nfs/prg/OpenFOAM/OpenFOAM-dev/etc/bashrc",
+# ]
+
+[scheduler.acquisition]
+# This is a required configuration if you desire offloaded acquisition
+# args = { q = "gpgpu", M = "user@example.com", m = "base" }
+# setup = ["source /nfs/prg/anaconda3/bin/activate", "conda activate py3.10"]
+# torch_device = ""

flowboost-0.2.2/flowboost/manager/interfaces/local.py

@@ -0,0 +1,66 @@
+import logging
+import os
+import signal
+import subprocess
+from pathlib import Path
+from typing import Any, Optional
+
+import psutil
+
+from flowboost.manager.manager import Manager
+from flowboost.openfoam.interface import FOAM
+
+
+class Local(Manager):
+    def __init__(self, wdir: Path | str, job_limit: int = 1) -> None:
+        super().__init__(wdir, job_limit)
+        self.shell: str = "bash"  # os.getenv("SHELL", "bash")
+
+    @staticmethod
+    def _is_available() -> bool:
+        available = FOAM.in_env()
+        if not available:
+            logging.error("OpenFOAM not found in PATH")
+
+        return available
+
+    def _submit_job(
+        self,
+        job_name: str,
+        submission_cwd: Path,
+        script: Path,
+        script_args: dict[str, Any] = {},
+    ) -> Optional[str]:
+        # Base command
+        cmd = [self.shell, script]
+
+        if script_args:
+            script_kv = Manager._construct_scipt_args(script_args, " ")
+            cmd.extend(script_kv)
+
+        # Execute the script and get the PID
+        process = subprocess.Popen(cmd, cwd=submission_cwd, start_new_session=True)
+        pid = process.pid
+
+        # Create and track the job
+        return str(pid)
+
+    def _cancel_job(self, job_id: str) -> bool:
+        try:
+            os.kill(int(job_id), signal.SIGTERM)
+        except OSError:
+            return False
+
+        return True
+
+    def _job_has_finished(self, job_id: str) -> bool:
+        try:
+            # Check if the process is still running
+            process = psutil.Process(int(job_id))
+            # If the process is running or sleeping, it's not finished
+            if process.status() in [psutil.STATUS_RUNNING, psutil.STATUS_SLEEPING]:
+                return False
+        except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+            return True
+
+        return True

flowboost-0.2.2/flowboost/manager/interfaces/sge.py

@@ -0,0 +1,79 @@
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Optional
+
+from flowboost.manager.manager import Manager
+
+
+class SGE(Manager):
+    def __init__(self, wdir: Path | str, job_limit: int) -> None:
+        super().__init__(wdir, job_limit)
+
+    @staticmethod
+    def _is_available() -> bool:
+        if shutil.which("qsub") and shutil.which("qstat"):
+            return True
+
+        logging.error("qsub or qstat commands not found in PATH")
+        return False
+
+    def _submit_job(
+        self,
+        job_name: str,
+        submission_cwd: Path,
+        script: Path,
+        script_args: dict[str, Any] = {},
+    ) -> Optional[str]:
+        # Base command with name
+        cmd = ["qsub", "-N", job_name]
+
+        if script_args:
+            # If Allrun accepts args, pass them
+            script_kv = Manager._construct_scipt_args(script_args)
+            cmd.extend(["-v", script_kv])
+
+        cmd.append(str(script))
+
+        # Run in case working directory
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=submission_cwd)
+
+        if result.returncode != 0:
+            logging.error(f"Error submitting job: out='{result.stderr.strip()}'")
+            return None
+
+        job_id = result.stdout.split()[2].split(".")[0]
+        return job_id
+
+    def _cancel_job(self, job_id: str) -> bool:
+        cmd = ["qdel", job_id]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        if result.returncode != 0:
+            logging.error(f"Error cancelling jobs: {result.stderr.strip()}")
+            return False
+
+        return True
+
+    def _job_has_finished(self, job_id: str) -> bool:
+        cmd = ["qstat", "-j", job_id]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        if result.returncode == 1:
+            if "Following jobs do not exist" in result.stderr:
+                # Job does not exist, meaning it has ended: OK
+                return True
+
+            logging.warning(
+                f"Querying job finish status failed: {result.stderr.strip()}"
+            )
+            return False
+
+        return False
+
+    def _get_job_info(self, job_id: str) -> str:
+        """Fetch job details from Sun Grid Engine using the given job_id."""
+        cmd = ["qstat", "-j", job_id]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        return result.stdout

flowboost-0.2.2/flowboost/manager/interfaces/slurm.py

@@ -0,0 +1,84 @@
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Optional
+
+from flowboost.manager.manager import Manager
+
+class Slurm(Manager):
+    def __init__(self, wdir: Path | str, job_limit: int) -> None:
+        super().__init__(wdir, job_limit)
+
+    @staticmethod
+    def _is_available() -> bool:
+        if shutil.which("sbatch") and shutil.which("squeue"):
+            return True
+
+        logging.error("sbatch or squeue commands not found in PATH")
+        return False
+
+    def _submit_job(
+        self,
+        job_name: str,
+        submission_cwd: Path,
+        script: Path,
+        script_args: dict[str, Any] = {},
+    ) -> Optional[str]:
+        # Base command with name
+        cmd = ["sbatch", "--job-name", job_name]
+
+        if script_args:
+            # If Allrun accepts args, pass them
+            script_kv = Manager._construct_scipt_args(script_args)
+            cmd.extend(["-v", script_kv])
+
+        cmd.append(str(script))
+        # Run in case working directory
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=submission_cwd)
+
+        if result.returncode != 0:
+            logging.error(f"Error submitting job: out='{result.stderr.strip()}'")
+            return None
+
+        job_id = result.stdout.split()[-1]
+        return job_id
+
+
+    def _cancel_job(self, job_id: str) -> bool:
+        cmd = ["scancel", job_id]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        if result.returncode != 0:
+            logging.error(f"Error cancelling jobs: {result.stderr.strip()}")
+            return False
+
+        return True
+
+    def _job_has_finished(self, job_id: str) -> bool:
+        """Check if a Slurm job has finished."""
+        cmd = ["squeue", "-j", job_id, "-h"]  # -h suppresses header
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        if result.returncode != 0:
+            # Job not in queue - likely finished or never existed
+            if "Invalid job id specified" in result.stderr:
+                return True
+
+            logging.warning(
+                f"Querying job finish status failed: {result.stderr.strip()}"
+            )
+            return False
+
+        # If squeue returns successfully with output, job is still running/pending
+        if result.stdout.strip():
+            return False
+
+        # Empty output means job finished
+        return True
+
+    def _get_job_info(self, job_id: str) -> str:
+        """Fetch job details from Slurm using the given job_id."""
+        cmd = ["scontrol", "show", "job", job_id]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        return result.stdout