foamlib 0.4.3__tar.gz → 0.5.0__tar.gz

{foamlib-0.4.3 → foamlib-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: foamlib
-Version: 0.4.3
+Version: 0.5.0
 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
@@ -67,9 +68,9 @@ Requires-Dist: foamlib[docs]; extra == "dev"
 
 It offers the following classes:
 
-* [`FoamFile`](https://foamlib.readthedocs.io/en/stable/#foamlib.FoamFile) (and [`FoamFieldFile`](https://foamlib.readthedocs.io/en/stable/#foamlib.FoamFieldFile)): read-write access to OpenFOAM configuration and field files as if they were Python `dict`s, using `foamlib`'s own parser. Supports both ASCII and binary field formats.
-* [`FoamCase`](https://foamlib.readthedocs.io/en/stable/#foamlib.FoamCase): a class for manipulating, executing and accessing the results of OpenFOAM cases.
-* [`AsyncFoamCase`](https://foamlib.readthedocs.io/en/stable/#foamlib.AsyncFoamCase): variant of `FoamCase` with asynchronous methods for running multiple cases at once.
+* [`FoamFile`](https://foamlib.readthedocs.io/en/stable/files.html#foamlib.FoamFile) (and [`FoamFieldFile`](https://foamlib.readthedocs.io/en/stable/files.html#foamlib.FoamFieldFile)): read-write access to OpenFOAM configuration and field files as if they were Python `dict`s, using `foamlib`'s own parser. Supports both ASCII and binary field formats.
+* [`FoamCase`](https://foamlib.readthedocs.io/en/stable/cases.html#foamlib.FoamCase): a class for manipulating, executing and accessing the results of OpenFOAM cases.
+* [`AsyncFoamCase`](https://foamlib.readthedocs.io/en/stable/cases.html#foamlib.AsyncFoamCase): variant of `FoamCase` with asynchronous methods for running multiple cases at once.
 
 ## Get started
 
@@ -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
@@ -131,7 +140,6 @@ from foamlib import AsyncFoamCase
 
 async def run_case():
     my_pitz_async = AsyncFoamCase(my_pitz)
-
     await my_pitz_async.run()
 
 asyncio.run(run_case())

{foamlib-0.4.3 → foamlib-0.5.0}/README.md

@@ -14,9 +14,9 @@
 
 It offers the following classes:
 
-* [`FoamFile`](https://foamlib.readthedocs.io/en/stable/#foamlib.FoamFile) (and [`FoamFieldFile`](https://foamlib.readthedocs.io/en/stable/#foamlib.FoamFieldFile)): read-write access to OpenFOAM configuration and field files as if they were Python `dict`s, using `foamlib`'s own parser. Supports both ASCII and binary field formats.
-* [`FoamCase`](https://foamlib.readthedocs.io/en/stable/#foamlib.FoamCase): a class for manipulating, executing and accessing the results of OpenFOAM cases.
-* [`AsyncFoamCase`](https://foamlib.readthedocs.io/en/stable/#foamlib.AsyncFoamCase): variant of `FoamCase` with asynchronous methods for running multiple cases at once.
+* [`FoamFile`](https://foamlib.readthedocs.io/en/stable/files.html#foamlib.FoamFile) (and [`FoamFieldFile`](https://foamlib.readthedocs.io/en/stable/files.html#foamlib.FoamFieldFile)): read-write access to OpenFOAM configuration and field files as if they were Python `dict`s, using `foamlib`'s own parser. Supports both ASCII and binary field formats.
+* [`FoamCase`](https://foamlib.readthedocs.io/en/stable/cases.html#foamlib.FoamCase): a class for manipulating, executing and accessing the results of OpenFOAM cases.
+* [`AsyncFoamCase`](https://foamlib.readthedocs.io/en/stable/cases.html#foamlib.AsyncFoamCase): variant of `FoamCase` with asynchronous methods for running multiple cases at once.
 
 ## Get started
 
@@ -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
@@ -78,7 +86,6 @@ from foamlib import AsyncFoamCase
 
 async def run_case():
     my_pitz_async = AsyncFoamCase(my_pitz)
-
     await my_pitz_async.run()
 
 asyncio.run(run_case())

{foamlib-0.4.3 → foamlib-0.5.0}/foamlib/__init__.py

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

{foamlib-0.4.3 → foamlib-0.5.0}/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.0/foamlib/_cases/_async.py

@@ -0,0 +1,233 @@
+import asyncio
+import multiprocessing
+import os
+import sys
+import tempfile
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import (
+    Callable,
+    Optional,
+    Union,
+)
+
+if sys.version_info >= (3, 9):
+    from collections.abc import AsyncGenerator, Collection, Sequence
+else:
+    from typing import AsyncGenerator, Collection, 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
+
+
+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)

{foamlib-0.4.3 → foamlib-0.5.0}/foamlib/_cases/_base.py

@@ -3,41 +3,29 @@ import shutil
 import sys
 from pathlib import Path
 from typing import (
-    Any,
     Optional,
-    Tuple,
     Union,
     overload,
 )
 
 if sys.version_info >= (3, 9):
     from collections.abc import (
-        Callable,
-        Collection,
-        Generator,
         Iterator,
-        Mapping,
         Sequence,
         Set,
     )
 else:
     from typing import AbstractSet as Set
     from typing import (
-        Callable,
-        Collection,
-        Generator,
         Iterator,
-        Mapping,
         Sequence,
     )
 
-
 from .._files import FoamFieldFile, FoamFile
-from .._util import is_sequence
 
 
 class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
-    def __init__(self, path: Union[Path, str] = Path()):
+    def __init__(self, path: Union["os.PathLike[str]", str] = Path()):
         self.path = Path(path).absolute()
 
     class TimeDirectory(Set[FoamFieldFile]):
@@ -49,7 +37,7 @@ class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
         :param path: The path to the time directory.
         """
 
-        def __init__(self, path: Union[Path, str]):
+        def __init__(self, path: Union["os.PathLike[str]", str]):
             self.path = Path(path).absolute()
 
         @property
@@ -142,184 +130,15 @@ class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
     def __len__(self) -> int:
         return len(self._times)
 
-    def _clean_paths(self) -> Set[Path]:
-        has_decompose_par_dict = (self.path / "system" / "decomposeParDict").is_file()
-        has_block_mesh_dict = (self.path / "system" / "blockMeshDict").is_file()
-
-        paths = set()
-
-        for p in self.path.iterdir():
-            if p.is_dir():
-                try:
-                    t = float(p.name)
-                except ValueError:
-                    pass
-                else:
-                    if t != 0:
-                        paths.add(p)
-
-                if has_decompose_par_dict and p.name.startswith("processor"):
-                    paths.add(p)
-
-        if (self.path / "0.orig").is_dir() and (self.path / "0").is_dir():
-            paths.add(self.path / "0")
-
-        if has_block_mesh_dict and (self.path / "constant" / "polyMesh").exists():
-            paths.add(self.path / "constant" / "polyMesh")
-
-        if self._run_script() is not None:
-            paths.update(self.path.glob("log.*"))
-
-        return paths
-
     def __delitem__(self, key: Union[int, float, str]) -> None:
         shutil.rmtree(self[key].path)
 
-    def _clone_ignore(
-        self,
-    ) -> Callable[[Union[Path, str], Collection[str]], Collection[str]]:
-        clean_paths = self._clean_paths()
-
-        def ignore(path: Union[Path, str], names: Collection[str]) -> Collection[str]:
-            paths = {Path(path) / name for name in names}
-            return {p.name for p in paths.intersection(clean_paths)}
-
-        return ignore
-
-    def _clean_script(self) -> Optional[Path]:
-        """Return the path to the (All)clean script, or None if no clean script is found."""
-        clean = self.path / "clean"
-        all_clean = self.path / "Allclean"
-
-        if clean.is_file():
-            script = clean
-        elif all_clean.is_file():
-            script = all_clean
-        else:
-            return None
-
-        if sys.argv and Path(sys.argv[0]).absolute() == script.absolute():
-            return None
-
-        return script if Path(sys.argv[0]).absolute() != script.absolute() else None
-
-    def _run_script(self, *, parallel: Optional[bool] = None) -> Optional[Path]:
-        """Return the path to the (All)run script, or None if no run script is found."""
-        run = self.path / "run"
-        run_parallel = self.path / "run-parallel"
-        all_run = self.path / "Allrun"
-        all_run_parallel = self.path / "Allrun-parallel"
-
-        if run.is_file() or all_run.is_file():
-            if run_parallel.is_file() or all_run_parallel.is_file():
-                if parallel:
-                    script = (
-                        run_parallel if run_parallel.is_file() else all_run_parallel
-                    )
-                elif parallel is False:
-                    script = run if run.is_file() else all_run
-                else:
-                    raise ValueError(
-                        "Both (All)run and (All)run-parallel scripts are present. Please specify parallel argument."
-                    )
-            else:
-                script = run if run.is_file() else all_run
-        elif parallel is not False and (
-            run_parallel.is_file() or all_run_parallel.is_file()
-        ):
-            script = run_parallel if run_parallel.is_file() else all_run_parallel
-        else:
-            return None
-
-        if sys.argv and Path(sys.argv[0]).absolute() == script.absolute():
-            return None
-
-        return script
-
-    def _env(self, *, shell: bool) -> Optional[Mapping[str, str]]:
-        sip_workaround = os.environ.get(
-            "FOAM_LD_LIBRARY_PATH", ""
-        ) and not os.environ.get("DYLD_LIBRARY_PATH", "")
-
-        if not shell or sip_workaround:
-            env = os.environ.copy()
-
-            if not shell:
-                env["PWD"] = str(self.path)
-
-            if sip_workaround:
-                env["DYLD_LIBRARY_PATH"] = env["FOAM_LD_LIBRARY_PATH"]
-
-            return env
-        else:
-            return None
-
-    def _run_cmds(
-        self,
-        cmd: Optional[Union[Sequence[Union[str, Path]], str, Path]] = None,
-        *,
-        script: bool = True,
-        parallel: Optional[bool] = None,
-        check: bool = True,
-    ) -> Generator[Tuple[str, Sequence[Any], Mapping[str, Any]], None, None]:
-        if cmd is not None:
-            if parallel:
-                cmd = self._parallel_cmd(cmd)
-
-            yield ("_run", (cmd,), {"check": check})
-        else:
-            script_path = self._run_script(parallel=parallel) if script else None
-
-            if script_path is not None:
-                yield ("_run", ([script_path],), {"check": check})
-
-            else:
-                if not self and (self.path / "0.orig").is_dir():
-                    yield ("restore_0_dir", (), {})
-
-                if (self.path / "system" / "blockMeshDict").is_file():
-                    yield ("block_mesh", (), {"check": check})
-
-                if parallel is None:
-                    parallel = (
-                        self._nprocessors > 0
-                        or (self.path / "system" / "decomposeParDict").is_file()
-                    )
-
-                if parallel:
-                    if (
-                        self._nprocessors == 0
-                        and (self.path / "system" / "decomposeParDict").is_file()
-                    ):
-                        yield ("decompose_par", (), {"check": check})
-
-                yield (
-                    "run",
-                    ([self.application],),
-                    {"parallel": parallel, "check": check},
-                )
-
-    def _parallel_cmd(
-        self, cmd: Union[Sequence[Union[str, Path]], str, Path]
-    ) -> Union[Sequence[Union[str, Path]], str]:
-        if not is_sequence(cmd):
-            return f"mpiexec -np {self._nprocessors} {cmd} -parallel"
-        else:
-            return [
-                "mpiexec",
-                "-np",
-                str(self._nprocessors),
-                cmd[0],
-                "-parallel",
-                *cmd[1:],
-            ]
-
     @property
     def name(self) -> str:
         """The name of the case."""
         return self.path.name
 
-    def file(self, path: Union[Path, str]) -> FoamFile:
+    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)