foamlib 0.4.4__tar.gz → 0.5.1__tar.gz

{foamlib-0.4.4 → foamlib-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: foamlib
-Version: 0.4.4
+Version: 0.5.1
 Summary: A Python interface for interacting with OpenFOAM
 Author-email: "Gabriel S. Gerlero" <ggerlero@cimec.unl.edu.ar>
 Project-URL: Homepage, https://github.com/gerlero/foamlib
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
@@ -123,6 +124,14 @@ my_pitz.clean()
 my_pitz.control_dict["writeInterval"] = 10
 ```
 
+### Make multiple file reads and writes in a single go
+
+```python
+with my_pitz.fv_schemes as f:
+    f["gradSchemes"]["default"] = f["divSchemes"]["default"]
+    f["snGradSchemes"]["default"] = "uncorrected"
+```
+
 ### Run a case asynchronously
 
 ```python
@@ -146,6 +155,25 @@ U = FoamFieldFile(Path(my_pitz) / "0/U")
 print(U.internal_field)
 ```
 
+### Run an optimization loop in parallel
+
+```python
+import os
+from pathlib import Path
+from foamlib import AsyncFoamCase
+from scipy.optimize import differential_evolution
+
+base = AsyncFoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")
+
+async def cost(x):
+    async with base.clone() as clone:
+        clone[0]["U"].boundary_field["inlet"].value = [x[0], 0, 0]
+        await clone.run()
+        return abs(clone[-1]["U"].internal_field[0][0])
+
+result = differential_evolution(cost, bounds=[(-1, 1)], workers=AsyncFoamCase.map, polish=False)
+```
+
 ## Documentation
 
 For more information, check out the [documentation](https://foamlib.readthedocs.io/).

{foamlib-0.4.4 → foamlib-0.5.1}/README.md

@@ -70,6 +70,14 @@ my_pitz.clean()
 my_pitz.control_dict["writeInterval"] = 10
 ```
 
+### Make multiple file reads and writes in a single go
+
+```python
+with my_pitz.fv_schemes as f:
+    f["gradSchemes"]["default"] = f["divSchemes"]["default"]
+    f["snGradSchemes"]["default"] = "uncorrected"
+```
+
 ### Run a case asynchronously
 
 ```python
@@ -93,6 +101,25 @@ U = FoamFieldFile(Path(my_pitz) / "0/U")
 print(U.internal_field)
 ```
 
+### Run an optimization loop in parallel
+
+```python
+import os
+from pathlib import Path
+from foamlib import AsyncFoamCase
+from scipy.optimize import differential_evolution
+
+base = AsyncFoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")
+
+async def cost(x):
+    async with base.clone() as clone:
+        clone[0]["U"].boundary_field["inlet"].value = [x[0], 0, 0]
+        await clone.run()
+        return abs(clone[-1]["U"].internal_field[0][0])
+
+result = differential_evolution(cost, bounds=[(-1, 1)], workers=AsyncFoamCase.map, polish=False)
+```
+
 ## Documentation
 
 For more information, check out the [documentation](https://foamlib.readthedocs.io/).

{foamlib-0.4.4 → foamlib-0.5.1}/foamlib/__init__.py

@@ -1,11 +1,10 @@
 """A Python interface for interacting with OpenFOAM."""
 
-__version__ = "0.4.4"
+__version__ = "0.5.1"
 
 from ._cases import (
     AsyncFoamCase,
     CalledProcessError,
-    CalledProcessWarning,
     FoamCase,
     FoamCaseBase,
 )
@@ -19,5 +18,4 @@ __all__ = [
     "FoamFieldFile",
     "FoamFileBase",
     "CalledProcessError",
-    "CalledProcessWarning",
 ]

{foamlib-0.4.4 → foamlib-0.5.1}/foamlib/_cases/__init__.py

@@ -1,12 +1,11 @@
 from ._async import AsyncFoamCase
 from ._base import FoamCaseBase
+from ._subprocess import CalledProcessError
 from ._sync import FoamCase
-from ._util import CalledProcessError, CalledProcessWarning
 
 __all__ = [
     "FoamCaseBase",
     "FoamCase",
     "AsyncFoamCase",
     "CalledProcessError",
-    "CalledProcessWarning",
 ]

foamlib-0.5.1/foamlib/_cases/_async.py

@@ -0,0 +1,245 @@
+import asyncio
+import multiprocessing
+import os
+import sys
+import tempfile
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Callable, Optional, TypeVar, Union
+
+if sys.version_info >= (3, 9):
+    from collections.abc import (
+        AsyncGenerator,
+        Awaitable,
+        Collection,
+        Iterable,
+        Sequence,
+    )
+else:
+    from typing import AsyncGenerator, Awaitable, Collection, Iterable, Sequence
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+import aioshutil
+
+from ._recipes import _FoamCaseRecipes
+from ._subprocess import run_async
+from ._util import awaitableasynccontextmanager
+
+X = TypeVar("X")
+Y = TypeVar("Y")
+
+
+class AsyncFoamCase(_FoamCaseRecipes):
+    """
+    An OpenFOAM case with asynchronous support.
+
+    Provides methods for running and cleaning cases, as well as accessing files.
+
+    Access the time directories of the case as a sequence, e.g. `case[0]` or `case[-1]`.
+
+    :param path: The path to the case directory.
+    """
+
+    max_cpus = multiprocessing.cpu_count()
+    """
+    Maximum number of CPUs to use for running `AsyncFoamCase`s concurrently. Defaults to the number of CPUs on the system.
+    """
+
+    _reserved_cpus = 0
+    _cpus_cond = None  # Cannot be initialized here yet
+
+    @staticmethod
+    @asynccontextmanager
+    async def _cpus(cpus: int) -> AsyncGenerator[None, None]:
+        if AsyncFoamCase._cpus_cond is None:
+            AsyncFoamCase._cpus_cond = asyncio.Condition()
+
+        cpus = min(cpus, AsyncFoamCase.max_cpus)
+        if cpus > 0:
+            async with AsyncFoamCase._cpus_cond:
+                await AsyncFoamCase._cpus_cond.wait_for(
+                    lambda: AsyncFoamCase.max_cpus - AsyncFoamCase._reserved_cpus
+                    >= cpus
+                )
+                AsyncFoamCase._reserved_cpus += cpus
+        try:
+            yield
+        finally:
+            if cpus > 0:
+                async with AsyncFoamCase._cpus_cond:
+                    AsyncFoamCase._reserved_cpus -= cpus
+                    AsyncFoamCase._cpus_cond.notify(cpus)
+
+    @staticmethod
+    async def _rmtree(
+        path: Union["os.PathLike[str]", str], ignore_errors: bool = False
+    ) -> None:
+        await aioshutil.rmtree(path, ignore_errors=ignore_errors)  # type: ignore [call-arg]
+
+    @staticmethod
+    async def _copytree(
+        src: Union["os.PathLike[str]", str],
+        dest: Union["os.PathLike[str]", str],
+        *,
+        symlinks: bool = False,
+        ignore: Optional[
+            Callable[[Union["os.PathLike[str]", str], Collection[str]], Collection[str]]
+        ] = None,
+    ) -> None:
+        await aioshutil.copytree(src, dest, symlinks=symlinks, ignore=ignore)
+
+    async def clean(
+        self,
+        *,
+        script: bool = True,
+        check: bool = False,
+    ) -> None:
+        """
+        Clean this case.
+
+        :param script: If True, use an (All)clean script if it exists. If False, ignore any clean scripts.
+        :param check: If True, raise a CalledProcessError if the clean script returns a non-zero exit code.
+        """
+        for name, args, kwargs in self._clean_cmds(script=script, check=check):
+            await getattr(self, name)(*args, **kwargs)
+
+    async def _run(
+        self,
+        cmd: Union[Sequence[Union[str, "os.PathLike[str]"]], str],
+        *,
+        parallel: bool = False,
+        cpus: int = 1,
+        check: bool = True,
+        log: bool = True,
+    ) -> None:
+        with self._output(cmd, log=log) as (stdout, stderr):
+            if parallel:
+                if isinstance(cmd, str):
+                    cmd = [
+                        "mpiexec",
+                        "-n",
+                        str(cpus),
+                        "/bin/sh",
+                        "-c",
+                        f"{cmd} -parallel",
+                    ]
+                else:
+                    cmd = ["mpiexec", "-n", str(cpus), *cmd, "-parallel"]
+
+            async with self._cpus(cpus):
+                await run_async(
+                    cmd,
+                    check=check,
+                    cwd=self.path,
+                    env=self._env(shell=isinstance(cmd, str)),
+                    stdout=stdout,
+                    stderr=stderr,
+                )
+
+    async def run(
+        self,
+        cmd: Optional[Union[Sequence[Union[str, "os.PathLike[str]"]], str]] = None,
+        *,
+        script: bool = True,
+        parallel: Optional[bool] = None,
+        cpus: Optional[int] = None,
+        check: bool = True,
+    ) -> None:
+        """
+        Run this case, or a specified command in the context of this case.
+
+        :param cmd: The command to run. If None, run the case. If a sequence, the first element is the command and the rest are arguments. If a string, `cmd` is executed in a shell.
+        :param script: If True and `cmd` is None, use an (All)run(-parallel) script if it exists for running the case. If False or no run script is found, autodetermine the command(s) needed to run the case.
+        :param parallel: If True, run in parallel using MPI. If None, autodetect whether to run in parallel.
+        :param check: If True, raise a CalledProcessError if any command returns a non-zero exit code.
+        """
+        for name, args, kwargs in self._run_cmds(
+            cmd=cmd, script=script, parallel=parallel, cpus=cpus, check=check
+        ):
+            await getattr(self, name)(*args, **kwargs)
+
+    async def block_mesh(self, *, check: bool = True) -> None:
+        """Run blockMesh on this case."""
+        await self.run(["blockMesh"], check=check)
+
+    async def decompose_par(self, *, check: bool = True) -> None:
+        """Decompose this case for parallel running."""
+        await self.run(["decomposePar"], check=check)
+
+    async def reconstruct_par(self, *, check: bool = True) -> None:
+        """Reconstruct this case after parallel running."""
+        await self.run(["reconstructPar"], check=check)
+
+    async def restore_0_dir(self) -> None:
+        """Restore the 0 directory from the 0.orig directory."""
+        for name, args, kwargs in self._restore_0_dir_cmds():
+            await getattr(self, name)(*args, **kwargs)
+
+    @awaitableasynccontextmanager
+    @asynccontextmanager
+    async def copy(
+        self, dst: Optional[Union["os.PathLike[str]", str]] = None
+    ) -> "AsyncGenerator[Self]":
+        """
+        Make a copy of this case.
+
+        Use as an async context manager to automatically delete the copy when done.
+
+        :param dst: The destination path. If None, copy to a temporary directory.
+        """
+        if dst is None:
+            dst = Path(tempfile.mkdtemp(), self.name)
+            tmp = True
+        else:
+            tmp = False
+
+        for name, args, kwargs in self._copy_cmds(dst):
+            await getattr(self, name)(*args, **kwargs)
+
+        yield type(self)(dst)
+
+        if tmp:
+            assert isinstance(dst, Path)
+            await self._rmtree(dst.parent)
+        else:
+            await self._rmtree(dst)
+
+    @awaitableasynccontextmanager
+    @asynccontextmanager
+    async def clone(
+        self, dst: Optional[Union["os.PathLike[str]", str]] = None
+    ) -> "AsyncGenerator[Self]":
+        """
+        Clone this case (make a clean copy).
+
+        Use as an async context manager to automatically delete the clone when done.
+
+        :param dst: The destination path. If None, clone to a temporary directory.
+        """
+        if dst is None:
+            dst = Path(tempfile.mkdtemp(), self.name)
+            tmp = True
+        else:
+            tmp = False
+
+        for name, args, kwargs in self._clone_cmds(dst):
+            await getattr(self, name)(*args, **kwargs)
+
+        yield type(self)(dst)
+
+        if tmp:
+            assert isinstance(dst, Path)
+            await self._rmtree(dst.parent)
+        else:
+            await self._rmtree(dst)
+
+    @staticmethod
+    def map(coro: Callable[[X], Awaitable[Y]], iterable: Iterable[X]) -> Iterable[Y]:
+        """Run an async function on each element of an iterable concurrently."""
+        return asyncio.get_event_loop().run_until_complete(
+            asyncio.gather(*(coro(arg) for arg in iterable))
+        )

foamlib-0.5.1/foamlib/_cases/_base.py

@@ -0,0 +1,213 @@
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import (
+    Optional,
+    Union,
+    overload,
+)
+
+if sys.version_info >= (3, 9):
+    from collections.abc import (
+        Iterator,
+        Sequence,
+        Set,
+    )
+else:
+    from typing import AbstractSet as Set
+    from typing import (
+        Iterator,
+        Sequence,
+    )
+
+from .._files import FoamFieldFile, FoamFile
+
+
+class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
+    def __init__(self, path: Union["os.PathLike[str]", str] = Path()):
+        self.path = Path(path).absolute()
+
+    class TimeDirectory(Set[FoamFieldFile]):
+        """
+        An OpenFOAM time directory in a case.
+
+        Use to access field files in the directory, e.g. `time["U"]`.
+
+        :param path: The path to the time directory.
+        """
+
+        def __init__(self, path: Union["os.PathLike[str]", str]):
+            self.path = Path(path).absolute()
+
+        @property
+        def time(self) -> float:
+            """The time that corresponds to this directory."""
+            return float(self.path.name)
+
+        @property
+        def name(self) -> str:
+            """The name of this time directory."""
+            return self.path.name
+
+        def __getitem__(self, key: str) -> FoamFieldFile:
+            if (self.path / f"{key}.gz").is_file() and not (self.path / key).is_file():
+                return FoamFieldFile(self.path / f"{key}.gz")
+            else:
+                return FoamFieldFile(self.path / key)
+
+        def __contains__(self, obj: object) -> bool:
+            if isinstance(obj, FoamFieldFile):
+                return obj.path.parent == self.path
+            elif isinstance(obj, str):
+                return (self.path / obj).is_file() or (
+                    self.path / f"{obj}.gz"
+                ).is_file()
+            else:
+                return False
+
+        def __iter__(self) -> Iterator[FoamFieldFile]:
+            for p in self.path.iterdir():
+                if p.is_file() and (
+                    p.suffix != ".gz" or not p.with_suffix("").is_file()
+                ):
+                    yield FoamFieldFile(p)
+
+        def __len__(self) -> int:
+            return len(list(iter(self)))
+
+        def __delitem__(self, key: str) -> None:
+            if (self.path / f"{key}.gz").is_file() and not (self.path / key).is_file():
+                (self.path / f"{key}.gz").unlink()
+            else:
+                (self.path / key).unlink()
+
+        def __fspath__(self) -> str:
+            return str(self.path)
+
+        def __repr__(self) -> str:
+            return f"{type(self).__qualname__}('{self.path}')"
+
+        def __str__(self) -> str:
+            return str(self.path)
+
+    @property
+    def _times(self) -> Sequence["FoamCaseBase.TimeDirectory"]:
+        times = []
+        for p in self.path.iterdir():
+            if p.is_dir():
+                try:
+                    float(p.name)
+                except ValueError:
+                    pass
+                else:
+                    times.append(FoamCaseBase.TimeDirectory(p))
+
+        times.sort(key=lambda t: t.time)
+
+        return times
+
+    @overload
+    def __getitem__(
+        self, index: Union[int, float, str]
+    ) -> "FoamCaseBase.TimeDirectory": ...
+
+    @overload
+    def __getitem__(self, index: slice) -> Sequence["FoamCaseBase.TimeDirectory"]: ...
+
+    def __getitem__(
+        self, index: Union[int, slice, float, str]
+    ) -> Union["FoamCaseBase.TimeDirectory", Sequence["FoamCaseBase.TimeDirectory"]]:
+        if isinstance(index, str):
+            return FoamCaseBase.TimeDirectory(self.path / index)
+        elif isinstance(index, float):
+            for time in self._times:
+                if time.time == index:
+                    return time
+            raise IndexError(f"Time {index} not found")
+        return self._times[index]
+
+    def __len__(self) -> int:
+        return len(self._times)
+
+    def __delitem__(self, key: Union[int, float, str]) -> None:
+        shutil.rmtree(self[key].path)
+
+    @property
+    def name(self) -> str:
+        """The name of the case."""
+        return self.path.name
+
+    def file(self, path: Union["os.PathLike[str]", str]) -> FoamFile:
+        """Return a FoamFile object for the given path in the case."""
+        return FoamFile(self.path / path)
+
+    @property
+    def _nsubdomains(self) -> Optional[int]:
+        """Return the number of subdomains as set in the decomposeParDict, or None if no decomposeParDict is found."""
+        try:
+            nsubdomains = self.decompose_par_dict["numberOfSubdomains"]
+            if not isinstance(nsubdomains, int):
+                raise TypeError(
+                    f"numberOfSubdomains in {self.decompose_par_dict} is not an integer"
+                )
+            return nsubdomains
+        except FileNotFoundError:
+            return None
+
+    @property
+    def _nprocessors(self) -> int:
+        """Return the number of processor directories in the case."""
+        return len(list(self.path.glob("processor*")))
+
+    @property
+    def application(self) -> str:
+        """The application name as set in the controlDict."""
+        application = self.control_dict["application"]
+        if not isinstance(application, str):
+            raise TypeError(f"application in {self.control_dict} is not a string")
+        return application
+
+    @property
+    def control_dict(self) -> FoamFile:
+        """The controlDict file."""
+        return self.file("system/controlDict")
+
+    @property
+    def fv_schemes(self) -> FoamFile:
+        """The fvSchemes file."""
+        return self.file("system/fvSchemes")
+
+    @property
+    def fv_solution(self) -> FoamFile:
+        """The fvSolution file."""
+        return self.file("system/fvSolution")
+
+    @property
+    def decompose_par_dict(self) -> FoamFile:
+        """The decomposeParDict file."""
+        return self.file("system/decomposeParDict")
+
+    @property
+    def block_mesh_dict(self) -> FoamFile:
+        """The blockMeshDict file."""
+        return self.file("system/blockMeshDict")
+
+    @property
+    def transport_properties(self) -> FoamFile:
+        """The transportProperties file."""
+        return self.file("constant/transportProperties")
+
+    @property
+    def turbulence_properties(self) -> FoamFile:
+        """The turbulenceProperties file."""
+        return self.file("constant/turbulenceProperties")
+
+    def __fspath__(self) -> str:
+        return str(self.path)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__qualname__}('{self.path}')"
+
+    def __str__(self) -> str:
+        return str(self.path)