foamlib 0.8.8__py3-none-any.whl → 0.8.9__py3-none-any.whl

foamlib/__init__.py

@@ -1,6 +1,6 @@
 """A Python interface for interacting with OpenFOAM."""
 
-__version__ = "0.8.8"
+__version__ = "0.8.9"
 
 from ._cases import (
     AsyncFoamCase,

foamlib/_cases/_async.py

@@ -45,8 +45,20 @@ class AsyncFoamCase(FoamCaseRunBase):
     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]`.
+    These will return `AsyncFoamCase.TimeDirectory` objects.
 
-    :param path: The path to the case directory.
+    :param path: The path to the case directory. Defaults to the current working
+        directory.
+
+    Example usage: ::
+        from foamlib import AsyncFoamCase
+
+        case = AsyncFoamCase("path/to/case") # Load an OpenFOAM case
+        case[0]["U"].internal_field = [0, 0, 0] # Set the initial velocity field to zero
+        await case.run() # Run the case
+        for time in case: # Iterate over the time directories
+            print(time.time) # Print the time
+            print(time["U"].internal_field) # Print the velocity field
     """
 
     class TimeDirectory(FoamCaseRunBase.TimeDirectory):
@@ -55,7 +67,12 @@ class AsyncFoamCase(FoamCaseRunBase):
             return AsyncFoamCase(self.path.parent)
 
         async def cell_centers(self) -> FoamFieldFile:
-            """Write and return the cell centers."""
+            """
+            Write and return the cell centers.
+
+            Currently only works for reconstructed cases (decomposed cases will need to
+            be reconstructed first).
+            """
             calls = ValuedGenerator(self._cell_centers_calls())
 
             for coro in calls:
@@ -126,7 +143,20 @@ class AsyncFoamCase(FoamCaseRunBase):
         """
         Clean this case.
 
-        :param check: If True, raise a CalledProcessError if the clean script returns a non-zero exit code.
+        If a `clean` or `Allclean` script is present in the case directory, it will be invoked.
+        Otherwise, the case directory will be cleaned using these rules:
+
+        - All time directories except `0` will be deleted.
+        - The `0` time directory will be deleted if `0.orig` exists.
+        - `processor*` directories will be deleted if a `system/decomposeParDict` file is present.
+        - `constant/polyMesh` will be deleted if a `system/blockMeshDict` file is present.
+        - All `log.*` files will be deleted.
+
+        If this behavior is not appropriate for a case, it is recommended to write a custom
+        `clean` script.
+
+        :param check: If True, raise a `CalledProcessError` if the clean script returns a
+            non-zero exit code.
         """
         for coro in self._clean_calls(check=check):
             await coro
@@ -161,11 +191,35 @@ class AsyncFoamCase(FoamCaseRunBase):
         """
         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 parallel: If True, run in parallel using MPI. If None, autodetect whether to run in parallel.
-        :param cpus: The number of CPUs to use. If None, autodetect according to the case.
-        :param check: If True, raise a CalledProcessError if any command returns a non-zero exit code.
-        :param log: If True, log the command output to a file.
+        If `cmd` is given, this method will run the given command in the context of the case.
+
+        If `cmd` is `None`, a series of heuristic rules will be used to run the case. This works as
+        follows:
+
+        - If a `run`, `Allrun` or `Allrun-parallel` script is present in the case directory,
+        it will be invoked. If both `run` and `Allrun` are present, `Allrun` will be used. If
+        both `Allrun` and `Allrun-parallel` are present and `parallel` is `None`, an error will
+        be raised.
+        - If no run script is present but an `Allrun.pre` script exists, it will be invoked.
+        - Otherwise, if a `system/blockMeshDict` file is present, the method will call
+        `self.block_mesh()`.
+        - Then, if a `0.orig` directory is present, it will call `self.restore_0_dir()`.
+        - Then, if the case is to be run in parallel (see the `parallel` option) and no
+        `processor*` directories exist but a`system/decomposeParDict` file is present, it will
+        call `self.decompose_par()`.
+        - Then, it will run the case using the application specified in the `controlDict` file.
+
+        If this behavior is not appropriate for a case, it is recommended to write a custom
+        `run`, `Allrun`, `Allrun-parallel` or `Allrun.pre` script.
+
+        :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 parallel: If `True`, run in parallel using MPI. If None, autodetect whether to run
+            in parallel.
+        :param cpus: The number of CPUs to use. If `None`, autodetect from to the case.
+        :param check: If `True`, raise a `CalledProcessError` if any command returns a non-zero
+            exit code.
+        :param log: If `True`, log the command output to `log.*` files in the case directory.
         """
         for coro in self._run_calls(
             cmd=cmd, parallel=parallel, cpus=cpus, check=check, log=log
@@ -200,9 +254,21 @@ class AsyncFoamCase(FoamCaseRunBase):
         """
         Make a copy of this case.
 
-        Use as an async context manager to automatically delete the copy when done.
+        If used as an asynchronous context manager (i.e., within an `async with` block) the copy
+        will be deleted automatically when exiting the block.
+
+        :param dst: The destination path. If `None`, clone to `$FOAM_RUN/foamlib`.
+
+        :return: The copy of the case.
 
-        :param dst: The destination path. If None, clone to `$FOAM_RUN/foamlib`.
+        Example usage: ::
+            import os
+            from pathlib import Path
+            from foamlib import AsyncFoamCase
+
+            pitz_tutorial = AsyncFoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")
+
+            my_pitz = await pitz_tutorial.copy("myPitz")
         """
         calls = ValuedGenerator(self._copy_calls(dst))
 
@@ -221,9 +287,24 @@ class AsyncFoamCase(FoamCaseRunBase):
         """
         Clone this case (make a clean copy).
 
-        Use as an async context manager to automatically delete the clone when done.
+        This is equivalent to running `(await self.copy()).clean()`, but it can be more efficient
+        in cases that do not contain custom clean scripts.
+
+        If used as an asynchronous context manager (i.e., within an `async with` block) the cloned
+        copy will be deleted automatically when exiting the block.
+
+        :param dst: The destination path. If `None`, clone to `$FOAM_RUN/foamlib`.
+
+        :return: The clone of the case.
+
+        Example usage: ::
+            import os
+            from pathlib import Path
+            from foamlib import AsyncFoamCase
+
+            pitz_tutorial = AsyncFoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")
 
-        :param dst: The destination path. If None, clone to `$FOAM_RUN/foamlib`.
+            my_pitz = await pitz_tutorial.clone("myPitz")
         """
         calls = ValuedGenerator(self._clone_calls(dst))
 

foamlib/_cases/_base.py

@@ -18,16 +18,32 @@ if TYPE_CHECKING:
 
 
 class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
+    """
+    Base class for OpenFOAM cases.
+
+    Provides methods for accessing files and time directories in the case, but does not
+    provide methods for running the case or any commands. Users are encouraged to use
+    `FoamCase` or `AsyncFoamCase` instead of this class.
+
+    Access the time directories of the case as a sequence, e.g. `case[0]` or `case[-1]`.
+    These will return `FoamCaseBase.TimeDirectory` objects.
+
+    :param path: The path to the case directory. Defaults to the current working
+        directory.
+    """
+
     def __init__(self, path: os.PathLike[str] | str = Path()) -> None:
         self.path = Path(path).absolute()
 
     class TimeDirectory(AbstractSet[FoamFieldFile]):
         """
-        An OpenFOAM time directory in a case.
+        A time directory in an OpenFOAM case.
 
-        Use to access field files in the directory, e.g. `time["U"]`.
+        Use to access field files in the directory (e.g. `time["U"]`). These will be
+        returned as `FoamFieldFile` objects.
 
-        :param path: The path to the time directory.
+        It also behaves as a set of `FoamFieldFile` objects (e.g. it can be
+        iterated over with `for field in time: ...`).
         """
 
         def __init__(self, path: os.PathLike[str] | str) -> None:
@@ -39,12 +55,12 @@ class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
 
         @property
         def time(self) -> float:
-            """The time that corresponds to this directory."""
+            """The time that corresponds to this directory, as a float."""
             return float(self.path.name)
 
         @property
         def name(self) -> str:
-            """The name of this time directory."""
+            """The name of this time directory (the time as a string)."""
             return self.path.name
 
         def __getitem__(self, key: str) -> FoamFieldFile:

foamlib/_cases/_run.py

@@ -46,6 +46,12 @@ if TYPE_CHECKING:
 
 
 class FoamCaseRunBase(FoamCaseBase):
+    """
+    Abstract base class of `FoamCase` and `AsyncFoamCase`.
+
+    Do not use this class directly: use `FoamCase` or `AsyncFoamCase` instead.
+    """
+
     class TimeDirectory(FoamCaseBase.TimeDirectory):
         @abstractmethod
         def cell_centers(

foamlib/_cases/_slurm.py

@@ -17,7 +17,16 @@ if TYPE_CHECKING:
 
 
 class AsyncSlurmFoamCase(AsyncFoamCase):
-    """An asynchronous OpenFOAM case that launches jobs on a Slurm cluster."""
+    """
+    An asynchronous OpenFOAM case that launches jobs on a Slurm cluster.
+
+    `AsyncSlurmFoamCase` is a subclass of `AsyncFoamCase`. It provides the same interface,
+    as the latter, except that it will launch jobs on a Slurm cluster (using `salloc` and
+    `srun`) on the user's behalf when running a case or command.
+
+    :param path: The path to the case directory. Defaults to the current working
+        directory.
+    """
 
     @staticmethod
     async def _run(

foamlib/_cases/_sync.py

@@ -33,8 +33,21 @@ class FoamCase(FoamCaseRunBase):
     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]`.
+    These will return `FoamCase.TimeDirectory` objects.
 
-    :param path: The path to the case directory.
+    :param path: The path to the case directory. Defaults to the current working
+        directory.
+
+    Example usage: ::
+
+        from foamlib import FoamCase
+
+        case = FoamCase("path/to/case") # Load an OpenFOAM case
+        case[0]["U"].internal_field = [0, 0, 0] # Set the initial velocity field to zero
+        case.run() # Run the case
+        for time in case: # Iterate over the time directories
+            print(time.time) # Print the time
+            print(time["U"].internal_field) # Print the velocity field
     """
 
     class TimeDirectory(FoamCaseRunBase.TimeDirectory):
@@ -43,7 +56,12 @@ class FoamCase(FoamCaseRunBase):
             return FoamCase(self.path.parent)
 
         def cell_centers(self) -> FoamFieldFile:
-            """Write and return the cell centers."""
+            """
+            Write and return the cell centers.
+
+            Currently only works for reconstructed cases (decomposed cases will need to
+            be reconstructed first).
+            """
             calls = ValuedGenerator(self._cell_centers_calls())
 
             for _ in calls:
@@ -107,7 +125,20 @@ class FoamCase(FoamCaseRunBase):
         """
         Clean this case.
 
-        :param check: If True, raise a CalledProcessError if the clean script returns a non-zero exit code.
+        If a `clean` or `Allclean` script is present in the case directory, it will be invoked.
+        Otherwise, the case directory will be cleaned using these rules:
+
+        - All time directories except `0` will be deleted.
+        - The `0` time directory will be deleted if `0.orig` exists.
+        - `processor*` directories will be deleted if a `system/decomposeParDict` file is present.
+        - `constant/polyMesh` will be deleted if a `system/blockMeshDict` file is present.
+        - All `log.*` files will be deleted.
+
+        If this behavior is not appropriate for a case, it is recommended to write a custom
+        `clean` script.
+
+        :param check: If True, raise a `CalledProcessError` if the clean script returns a
+            non-zero exit code.
         """
         for _ in self._clean_calls(check=check):
             pass
@@ -128,11 +159,35 @@ class FoamCase(FoamCaseRunBase):
         """
         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 parallel: If True, run in parallel using MPI. If None, autodetect whether to run in parallel.
-        :param cpus: The number of CPUs to use. If None, autodetect according to the case.
-        :param check: If True, raise a CalledProcessError if any command returns a non-zero exit code.
-        :param log: If True, log the command output to a file.
+        If `cmd` is given, this method will run the given command in the context of the case.
+
+        If `cmd` is `None`, a series of heuristic rules will be used to run the case. This works as
+        follows:
+
+        - If a `run`, `Allrun` or `Allrun-parallel` script is present in the case directory,
+        it will be invoked. If both `run` and `Allrun` are present, `Allrun` will be used. If
+        both `Allrun` and `Allrun-parallel` are present and `parallel` is `None`, an error will
+        be raised.
+        - If no run script is present but an `Allrun.pre` script exists, it will be invoked.
+        - Otherwise, if a `system/blockMeshDict` file is present, the method will call
+        `self.block_mesh()`.
+        - Then, if a `0.orig` directory is present, it will call `self.restore_0_dir()`.
+        - Then, if the case is to be run in parallel (see the `parallel` option) and no
+        `processor*` directories exist but a`system/decomposeParDict` file is present, it will
+        call `self.decompose_par()`.
+        - Then, it will run the case using the application specified in the `controlDict` file.
+
+        If this behavior is not appropriate for a case, it is recommended to write a custom
+        `run`, `Allrun`, `Allrun-parallel` or `Allrun.pre` script.
+
+        :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 parallel: If `True`, run in parallel using MPI. If None, autodetect whether to run
+            in parallel.
+        :param cpus: The number of CPUs to use. If `None`, autodetect from to the case.
+        :param check: If `True`, raise a `CalledProcessError` if any command returns a non-zero
+            exit code.
+        :param log: If `True`, log the command output to `log.*` files in the case directory.
         """
         for _ in self._run_calls(
             cmd=cmd, parallel=parallel, cpus=cpus, check=check, log=log
@@ -163,9 +218,21 @@ class FoamCase(FoamCaseRunBase):
         """
         Make a copy of this case.
 
-        Use as a context manager to automatically delete the copy when done.
+        If used as a context manager (i.e., within a `with` block) the copy will be deleted
+        automatically when exiting the block.
+
+        :param dst: The destination path. If `None`, clone to `$FOAM_RUN/foamlib`.
 
-        :param dst: The destination path. If None, clone to `$FOAM_RUN/foamlib`.
+        :return: The copy of the case.
+
+        Example usage: ::
+            import os
+            from pathlib import Path
+            from foamlib import FoamCase
+
+            pitz_tutorial = FoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")
+
+            my_pitz = pitz_tutorial.copy("myPitz")
         """
         calls = ValuedGenerator(self._copy_calls(dst))
 
@@ -178,9 +245,24 @@ class FoamCase(FoamCaseRunBase):
         """
         Clone this case (make a clean copy).
 
-        Use as a context manager to automatically delete the clone when done.
+        This is equivalent to running `self.copy().clean()`, but it can be more efficient in cases
+        that do not contain custom clean scripts.
+
+        If used as a context manager (i.e., within a `with` block) the cloned copy will be deleted
+        automatically when exiting the block.
+
+        :param dst: The destination path. If `None`, clone to `$FOAM_RUN/foamlib`.
+
+        :return: The clone of the case.
+
+        Example usage: ::
+            import os
+            from pathlib import Path
+            from foamlib import FoamCase
+
+            pitz_tutorial = FoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")
 
-        :param dst: The destination path. If None, clone to `$FOAM_RUN/foamlib`.
+            my_pitz = pitz_tutorial.clone("myPitz")
         """
         calls = ValuedGenerator(self._clone_calls(dst))
 

foamlib/_files/_files.py

@@ -23,8 +23,9 @@ from ._types import (
     Dict_,
     Dimensioned,
     DimensionSet,
-    Entry,
+    EntryLike,
     Field,
+    FieldLike,
     File,
     MutableEntry,
 )
@@ -40,9 +41,46 @@ class FoamFile(
     """
     An OpenFOAM data file.
 
-    Use as a mutable mapping (i.e., like a dict) to access and modify entries.
+    `FoamFile` supports most OpenFOAM data and configuration files (i.e., files with a
+    "FoamFile" header), including those with regular expressions and #-based directives.
+    Notable exceptions are FoamFiles with #codeStreams and those multiple #-directives
+    with the same name, which are currently not supported. Non-FoamFile output files are
+    also not suppored by this class. Regular expressions and #-based directives can be
+    accessed and modified, but they are not evaluated or expanded by this library.
 
-    Use as a context manager to make multiple changes to the file while saving all changes only once at the end.
+    Use `FoamFile` as a mutable mapping (i.e., like a `dict`) to access and modify
+    entries. When accessing a sub-dictionary, the returned value will be a
+    `FoamFile.SubDict` object, that allows for further access and modification of nested
+    dictionaries within the `FoamFile` in a single operation.
+
+    If the `FoamFile` does not store a dictionary, the main stored value can be accessed
+    and modified by passing `None` as the key (e.g., `file[None]`).
+
+    You can also use the `FoamFile` as a context manager (i.e., within a `with` block)
+    to make multiple changes to the file while saving any and all changes only once at
+    the end.
+
+    :param path: The path to the file. If the file does not exist, it will be created
+        when the first change is made. However, if an attempt is made to access entries
+        in a non-existent file, a `FileNotFoundError` will be raised.
+
+    Example usage: ::
+        from foamlib import FoamFile
+
+        file = FoamFile("path/to/case/system/controlDict") # Load a controlDict file
+        print(file["endTime"]) # Print the end time
+        file["writeInterval"] = 100 # Set the write interval to 100
+        file["writeFormat"] = "binary" # Set the write format to binary
+
+    or (better): ::
+        from foamlib import FoamCase
+
+        case = FoamCase("path/to/case")
+
+        with case.control_dict as file: # Load the controlDict file
+            print(file["endTime"]) # Print the end time
+            file["writeInterval"] = 100
+            file["writeFormat"] = "binary"
     """
 
     Dimensioned = Dimensioned
@@ -51,7 +89,32 @@ class FoamFile(
     class SubDict(
         MutableMapping[str, MutableEntry],
     ):
-        """An OpenFOAM dictionary within a file as a mutable mapping."""
+        """
+        An OpenFOAM sub-dictionary within a file.
+
+        `FoamFile.SubDict` is a mutable mapping that allows for accessing and modifying
+        nested dictionaries within a `FoamFile` in a single operation. It behaves like a
+        `dict` and can be used to access and modify entries in the sub-dictionary.
+
+        To obtain a `FoamFile.SubDict` object, access a sub-dictionary in a `FoamFile`
+        object (e.g., `file["subDict"]`).
+
+        Example usage: ::
+            from foamlib import FoamFile
+
+            file = FoamFile("path/to/case/system/fvSchemes") # Load an fvSchemes file
+            print(file["ddtSchemes"]["default"]) # Print the default ddt scheme
+            file["ddtSchemes"]["default"] = "Euler" # Set the default ddt scheme
+
+        or (better): ::
+            from foamlib import FoamCase
+
+            case = FoamCase("path/to/case")
+
+            with case.fv_schemes as file: # Load the fvSchemes file
+                print(file["ddtSchemes"]["default"])
+                file["ddtSchemes"]["default"] = "Euler"
+        """
 
         def __init__(self, _file: FoamFile, _keywords: tuple[str, ...]) -> None:
             self._file = _file
@@ -63,7 +126,7 @@ class FoamFile(
         def __setitem__(
             self,
             keyword: str,
-            data: Entry,
+            data: EntryLike,
         ) -> None:
             self._file[(*self._keywords, keyword)] = data
 
@@ -93,7 +156,7 @@ class FoamFile(
             return f"{type(self).__qualname__}('{self._file}', {self._keywords})"
 
         def as_dict(self) -> Dict_:
-            """Return a nested dict representation of the dictionary."""
+            """Return a nested dict representation of the sub-dictionary."""
             ret = self._file.as_dict(include_header=True)
 
             for k in self._keywords:
@@ -190,13 +253,15 @@ class FoamFile(
             return FoamFile.SubDict(self, keywords)
         return deepcopy(value)
 
-    def __setitem__(self, keywords: str | tuple[str, ...] | None, data: Entry) -> None:
+    def __setitem__(
+        self, keywords: str | tuple[str, ...] | None, data: EntryLike
+    ) -> None:
         if not keywords:
             keywords = ()
         elif not isinstance(keywords, tuple):
             keywords = (keywords,)
 
-        if keywords and not isinstance(normalize(keywords[-1]), str):
+        if keywords and not isinstance(normalize(keywords[-1], kind=Kind.KEYWORD), str):
             msg = f"Invalid keyword: {keywords[-1]}"
             raise ValueError(msg)
 
@@ -379,15 +444,44 @@ class FoamFile(
 
 
 class FoamFieldFile(FoamFile):
-    """An OpenFOAM dictionary file representing a field as a mutable mapping."""
+    """
+    Subclass of `FoamFile` for representing OpenFOAM field files specifically.
+
+    The difference between `FoamFieldFile` and `FoamFile` is that `FoamFieldFile` has
+    the additional properties `dimensions`, `internal_field`, and `boundary_field` that
+    are commonly found in OpenFOAM field files. Note that these are only a shorthand for
+    accessing the corresponding entries in the file.
+
+    See `FoamFile` for more information on how to read and edit OpenFOAM files.
+
+    :param path: The path to the file. If the file does not exist, it will be created
+        when the first change is made. However, if an attempt is made to access entries
+        in a non-existent file, a `FileNotFoundError` will be raised.
+
+    Example usage: ::
+        from foamlib import FoamFieldFile
+
+        field = FoamFieldFile("path/to/case/0/U") # Load a field
+        print(field.dimensions) # Print the dimensions
+        print(field.boundary_field) # Print the boundary field
+        field.internal_field = [0, 0, 0] # Set the internal field
+
+    or (better): ::
+        from foamlib import FoamCase
+
+        case = FoamCase("path/to/case")
+
+        with case[0]["U"] as field: # Load a field
+            print(field.dimensions)
+            print(field.boundary_field)
+            field.internal_field = [0, 0, 0]
+    """
 
     class BoundariesSubDict(FoamFile.SubDict):
-        def __getitem__(self, keyword: str) -> FoamFieldFile.BoundarySubDict:
+        def __getitem__(self, keyword: str) -> FoamFieldFile.BoundarySubDict | Data:
             value = super().__getitem__(keyword)
-            if not isinstance(value, FoamFieldFile.BoundarySubDict):
-                assert not isinstance(value, FoamFile.SubDict)
-                msg = f"boundary {keyword} is not a dictionary"
-                raise TypeError(msg)
+            if isinstance(value, FoamFieldFile.SubDict):
+                assert isinstance(value, FoamFieldFile.BoundarySubDict)
             return value
 
     class BoundarySubDict(FoamFile.SubDict):
@@ -419,7 +513,7 @@ class FoamFieldFile(FoamFile):
         @value.setter
         def value(
             self,
-            value: Field,
+            value: FieldLike,
         ) -> None:
             self["value"] = value
 
@@ -466,7 +560,7 @@ class FoamFieldFile(FoamFile):
     @internal_field.setter
     def internal_field(
         self,
-        value: Field,
+        value: FieldLike,
     ) -> None:
         self["internalField"] = value
 

foamlib/_files/_serialization.py

@@ -12,7 +12,15 @@ else:
 import numpy as np
 
 from ._parsing import parse_data
-from ._types import Data, Dimensioned, DimensionSet, Entry, is_sequence
+from ._types import (
+    Data,
+    DataLike,
+    Dimensioned,
+    DimensionSet,
+    Entry,
+    EntryLike,
+    is_sequence,
+)
 
 
 class Kind(Enum):
@@ -23,17 +31,18 @@ class Kind(Enum):
     BINARY_FIELD = auto()
     SCALAR_BINARY_FIELD = auto()
     DIMENSIONS = auto()
+    KEYWORD = auto()
 
 
 @overload
-def normalize(data: Data, *, kind: Kind = Kind.DEFAULT) -> Data: ...
+def normalize(data: DataLike, *, kind: Kind = Kind.DEFAULT) -> Data: ...
 
 
 @overload
-def normalize(data: Entry, *, kind: Kind = Kind.DEFAULT) -> Entry: ...
+def normalize(data: EntryLike, *, kind: Kind = Kind.DEFAULT) -> Entry: ...
 
 
-def normalize(data: Entry, *, kind: Kind = Kind.DEFAULT) -> Entry:
+def normalize(data: EntryLike, *, kind: Kind = Kind.DEFAULT) -> Entry:
     if kind in (
         Kind.ASCII_FIELD,
         Kind.SCALAR_ASCII_FIELD,
@@ -52,12 +61,12 @@ def normalize(data: Entry, *, kind: Kind = Kind.DEFAULT) -> Entry:
                 if arr.ndim == 1 or (arr.ndim == 2 and arr.shape[1] in (3, 6, 9)):
                     return arr  # type: ignore [return-value]
 
-            return data
+            return [normalize(d, kind=Kind.SINGLE_ENTRY) for d in data]
 
         if isinstance(data, int):
             return float(data)
 
-        return data
+        return normalize(data)
 
     if isinstance(data, np.ndarray):
         ret = data.tolist()
@@ -83,7 +92,10 @@ def normalize(data: Entry, *, kind: Kind = Kind.DEFAULT) -> Entry:
         return [normalize(d, kind=Kind.SINGLE_ENTRY) for d in data]
 
     if isinstance(data, str):
-        return parse_data(data)
+        parsed_data = parse_data(data)
+        if kind == Kind.KEYWORD and isinstance(parsed_data, bool):
+            return data
+        return parsed_data
 
     if isinstance(
         data,
@@ -96,7 +108,7 @@ def normalize(data: Entry, *, kind: Kind = Kind.DEFAULT) -> Entry:
 
 
 def dumps(
-    data: Entry,
+    data: EntryLike,
     *,
     kind: Kind = Kind.DEFAULT,
 ) -> bytes:

foamlib/_files/_types.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import sys
-from dataclasses import dataclass
 from enum import Enum
 from typing import Dict, NamedTuple, Optional, Union
 
@@ -33,8 +32,13 @@ class DimensionSet(NamedTuple):
 
 Tensor = Union[
     float,
+    "np.ndarray[tuple[int], np.dtype[np.float64]]",
+]
+
+TensorLike = Union[
     Sequence[float],
-    "np.ndarray[tuple[()] | tuple[int], np.dtype[np.float64]]",
+    "np.ndarray[tuple[()], np.dtype[np.float64]]",
+    Tensor,
 ]
 
 
@@ -71,21 +75,25 @@ class TensorKind(Enum):
         raise ValueError(msg)
 
 
-@dataclass
 class Dimensioned:
-    value: Tensor = 0
-    dimensions: DimensionSet | Sequence[float] = ()
-    name: str | None = None
+    def __init__(
+        self,
+        value: TensorLike,
+        dimensions: DimensionSet | Sequence[float],
+        name: str | None = None,
+    ) -> None:
+        if is_sequence(value):
+            self.value: Tensor = np.array(value, dtype=float)  # type: ignore [assignment]
+        else:
+            assert isinstance(value, (int, float, np.ndarray))
+            self.value = float(value)
 
-    def __post_init__(self) -> None:
-        if is_sequence(self.value):
-            self.value = np.asarray(self.value, dtype=float)  # type: ignore [assignment]
+        if not isinstance(dimensions, DimensionSet):
+            self.dimensions = DimensionSet(*dimensions)
         else:
-            assert isinstance(self.value, (int, float, np.ndarray))
-            self.value = float(self.value)
+            self.dimensions = dimensions
 
-        if not isinstance(self.dimensions, DimensionSet):
-            self.dimensions = DimensionSet(*self.dimensions)
+        self.name = name
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Dimensioned):
@@ -99,11 +107,18 @@ class Dimensioned:
 
 
 Field = Union[
-    Tensor,
-    Sequence[Tensor],
+    float,
     "np.ndarray[tuple[int] | tuple[int, int], np.dtype[np.float64 | np.float32]]",
 ]
 
+FieldLike = Union[
+    TensorLike,
+    Sequence[TensorLike],
+    Sequence[Sequence[TensorLike]],
+    Field,
+]
+
+
 Data = Union[
     str,
     int,
@@ -123,11 +138,22 @@ Entry = Union[
 A value that can be stored in an OpenFOAM file.
 """
 
+DataLike = Union[
+    FieldLike,
+    Sequence["EntryLike"],
+    Data,
+]
+
+EntryLike = Union[
+    DataLike,
+    Mapping[str, "EntryLike"],
+]
+
 
 def is_sequence(
-    value: Entry,
+    value: EntryLike,
 ) -> TypeGuard[
-    Sequence[Entry]
+    Sequence[EntryLike]
     | np.ndarray[tuple[int] | tuple[int, int], np.dtype[np.float64 | np.float32]]
 ]:
     return (isinstance(value, Sequence) and not isinstance(value, str)) or (

{foamlib-0.8.8.dist-info → foamlib-0.8.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foamlib
-Version: 0.8.8
+Version: 0.8.9
 Summary: A Python interface for interacting with OpenFOAM
 Project-URL: Homepage, https://github.com/gerlero/foamlib
 Project-URL: Repository, https://github.com/gerlero/foamlib
@@ -27,7 +27,6 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.7
 Requires-Dist: aioshutil<2,>=1
 Requires-Dist: numpy<3,>=1
-Requires-Dist: numpy<3,>=1.25.0; python_version >= '3.10'
 Requires-Dist: pyparsing<4,>=3.1.2
 Requires-Dist: rich<15,>=13
 Requires-Dist: typing-extensions<5,>=4; python_version < '3.11'
@@ -37,22 +36,29 @@ Requires-Dist: pytest-asyncio<0.27,>=0.21; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest<9,>=7; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scipy-stubs; (python_version >= '3.10') and extra == 'dev'
+Requires-Dist: scipy<2,>=1; extra == 'dev'
 Requires-Dist: sphinx-rtd-theme; extra == 'dev'
 Requires-Dist: sphinx<9,>=5; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: ruff; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme; extra == 'docs'
 Requires-Dist: sphinx<9,>=5; extra == 'docs'
 Provides-Extra: lint
 Requires-Dist: ruff; extra == 'lint'
 Provides-Extra: test
+Requires-Dist: mypy<2,>=1; extra == 'test'
 Requires-Dist: pytest-asyncio<0.27,>=0.21; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
 Requires-Dist: pytest<9,>=7; extra == 'test'
+Requires-Dist: scipy<2,>=1; extra == 'test'
 Provides-Extra: typing
 Requires-Dist: mypy<2,>=1; extra == 'typing'
 Requires-Dist: pytest-asyncio<0.27,>=0.21; extra == 'typing'
 Requires-Dist: pytest-cov; extra == 'typing'
 Requires-Dist: pytest<9,>=7; extra == 'typing'
+Requires-Dist: scipy-stubs; (python_version >= '3.10') and extra == 'typing'
+Requires-Dist: scipy<2,>=1; extra == 'typing'
 Description-Content-Type: text/markdown
 
 [<img alt="foamlib" src="https://github.com/gerlero/foamlib/raw/main/logo.png" height="65">](https://github.com/gerlero/foamlib)
@@ -73,11 +79,18 @@ Description-Content-Type: text/markdown
 
 **foamlib** provides a simple, modern, ergonomic and fast Python interface for interacting with [OpenFOAM](https://www.openfoam.com).
 
-<p align="center">
-    <img alt="benchmark" src="https://github.com/gerlero/foamlib/raw/main/benchmark.png" height="250">
-    <br>
-  <i>Parsing a </i>volVectorField<i> with 200k cells.</i>
-</p>
+<div align="center">
+<img alt="benchmark" src="https://github.com/gerlero/foamlib/raw/main/benchmark/benchmark.png" height="250">
+
+Parsing a volVectorField with 200k cells.<sup>[1](#benchmark)</sup>
+</div>
+
+
+## 🚀 Introduction
+
+**foamlib** is a Python package designed to simplify the manipulation of OpenFOAM cases and files. Its standalone parser makes it easy to work with OpenFOAM’s input/output files from Python, while its case-handling capabilities facilitate various execution workflows—reducing boilerplate code and enabling efficient Python-based pre- and post-processing, as well as simulation management.
+
+Compared to [PyFoam](https://openfoamwiki.net/index.php/Contrib/PyFoam) and other similar tools like [fluidfoam](https://github.com/fluiddyn/fluidfoam), [fluidsimfoam](https://foss.heptapod.net/fluiddyn/fluidsimfoam), and [Ofpp](https://github.com/xu-xianghua/ofpp), **foamlib** offers advantages such as modern Python compatibility, support for binary-formatted fields, a fully type-hinted API, and asynchronous operations; making OpenFOAM workflows more accessible and streamlined.
 
 ## 👋 Basics
 
@@ -208,6 +221,159 @@ case = FoamCase(Path(__file__).parent)
 case.run()
 ```
 
-## 📘 Documentation
+## ▶️ A complete example
+
+The following is a fully self-contained example that demonstrates how to create an OpenFOAM case from scratch, run it, and analyze the results.
+
+<details>
+
+<summary>Example</summary>
+
+```python
+#!/usr/bin/env python3
+"""Check the diffusion of a scalar field in a scalarTransportFoam case."""
+
+import shutil
+from pathlib import Path
+
+import numpy as np
+from scipy.special import erfc
+from foamlib import FoamCase
+
+path = Path(__file__).parent / "diffusionCheck"
+shutil.rmtree(path, ignore_errors=True)
+path.mkdir(parents=True)
+(path / "system").mkdir()
+(path / "constant").mkdir()
+(path / "0").mkdir()
+
+case = FoamCase(path)
+
+with case.control_dict as f:
+    f["application"] = "scalarTransportFoam"
+    f["startFrom"] = "latestTime"
+    f["stopAt"] = "endTime"
+    f["endTime"] = 5
+    f["deltaT"] = 1e-3
+    f["writeControl"] = "adjustableRunTime"
+    f["writeInterval"] = 1
+    f["purgeWrite"] = 0
+    f["writeFormat"] = "ascii"
+    f["writePrecision"] = 6
+    f["writeCompression"] = False
+    f["timeFormat"] = "general"
+    f["timePrecision"] = 6
+    f["adjustTimeStep"] = False
+    f["runTimeModifiable"] = False
+
+with case.fv_schemes as f:
+    f["ddtSchemes"] = {"default": "Euler"}
+    f["gradSchemes"] = {"default": "Gauss linear"}
+    f["divSchemes"] = {"default": "none", "div(phi,U)": "Gauss linear", "div(phi,T)": "Gauss linear"}
+    f["laplacianSchemes"] = {"default": "Gauss linear corrected"}
+
+with case.fv_solution as f:
+    f["solvers"] = {"T": {"solver": "PBiCG", "preconditioner": "DILU", "tolerance": 1e-6, "relTol": 0}}
+
+with case.block_mesh_dict as f:
+    f["scale"] = 1
+    f["vertices"] = [
+        [0, 0, 0],
+        [1, 0, 0],
+        [1, 0.5, 0],
+        [1, 1, 0],
+        [0, 1, 0],
+        [0, 0.5, 0],
+        [0, 0, 0.1],
+        [1, 0, 0.1],
+        [1, 0.5, 0.1],
+        [1, 1, 0.1],
+        [0, 1, 0.1],
+        [0, 0.5, 0.1],
+    ]
+    f["blocks"] = [
+        "hex", [0, 1, 2, 5, 6, 7, 8, 11], [400, 20, 1], "simpleGrading", [1, 1, 1],
+        "hex", [5, 2, 3, 4, 11, 8, 9, 10], [400, 20, 1], "simpleGrading", [1, 1, 1],
+    ]
+    f["edges"] = []
+    f["boundary"] = [
+        ("inletUp", {"type": "patch", "faces": [[5, 4, 10, 11]]}),
+        ("inletDown", {"type": "patch", "faces": [[0, 5, 11, 6]]}),
+        ("outletUp", {"type": "patch", "faces": [[2, 3, 9, 8]]}),
+        ("outletDown", {"type": "patch", "faces": [[1, 2, 8, 7]]}),
+        ("walls", {"type": "wall", "faces": [[4, 3, 9, 10], [0, 1, 7, 6]]}),
+        ("frontAndBack", {"type": "empty", "faces": [[0, 1, 2, 5], [5, 2, 3, 4], [6, 7, 8, 11], [11, 8, 9, 10]]}),
+    ]
+    f["mergePatchPairs"] = []
+
+with case.transport_properties as f:
+    f["DT"] = f.Dimensioned(1e-3, f.DimensionSet(length=2, time=-1), "DT")
+
+with case[0]["U"] as f:
+    f.dimensions = f.DimensionSet(length=1, time=-1)
+    f.internal_field = [1, 0, 0]
+    f.boundary_field = {
+        "inletUp": {"type": "fixedValue", "value": [1, 0, 0]},
+        "inletDown": {"type": "fixedValue", "value": [1, 0, 0]},
+        "outletUp": {"type": "zeroGradient"},
+        "outletDown": {"type": "zeroGradient"},
+        "walls": {"type": "zeroGradient"},
+        "frontAndBack": {"type": "empty"},
+    }
+
+with case[0]["T"] as f:
+    f.dimensions = f.DimensionSet(temperature=1)
+    f.internal_field = 0
+    f.boundary_field = {
+        "inletUp": {"type": "fixedValue", "value": 0},
+        "inletDown": {"type": "fixedValue", "value": 1},
+        "outletUp": {"type": "zeroGradient"},
+        "outletDown": {"type": "zeroGradient"},
+        "walls": {"type": "zeroGradient"},
+        "frontAndBack": {"type": "empty"},
+    }
+
+case.run()
+
+x, y, z = case[0].cell_centers().internal_field.T
+
+end = x == x.max()
+x = x[end]
+y = y[end]
+z = z[end]
+
+DT = case.transport_properties["DT"].value
+U = case[0]["U"].internal_field[0]
+
+for time in case[1:]:
+    if U*time.time < 2*x.max():
+        continue
+
+    T = time["T"].internal_field[end]
+    analytical = 0.5 * erfc((y - 0.5) / np.sqrt(4 * DT * x/U))
+    if np.allclose(T, analytical, atol=0.1):
+        print(f"Time {time.time}: OK")
+    else:
+        raise RuntimeError(f"Time {time.time}: {T} != {analytical}")
+```
+
+</details>
+
+
+## 📘 API documentation
+
+For more information on how to use **foamlibs**'s classes and methods, check out the [documentation](https://foamlib.readthedocs.io/).
+
+## 🙋 Support
+
+If you have any questions or need help, feel free to open a [discussion](https://github.com/gerlero/foamlib/discussions).
+
+If you believe you have found a bug in **foamlib**, please open an [issue](https://github.com/gerlero/foamlib/issues).
+
+## 🧑‍💻 Contributing
+
+You're welcome to contribute to **foamlib**! Check out the [contributing guidelines](CONTRIBUTING.md) for more information.
+
+## Footnotes
 
-For more information, check out the [documentation](https://foamlib.readthedocs.io/).
+<a id="benchmark">[1]</a> foamlib 0.8.1 vs PyFoam 2023.7 on a MacBook Air (2020, M1) with 8 GB of RAM. [Benchmark script](benchmark/benchmark.py).

foamlib-0.8.9.dist-info/RECORD

@@ -0,0 +1,20 @@
+foamlib/__init__.py,sha256=UPZX4CKrZGbzDVviSntbJjI7Bcv7ufYZWlGZbVVlHyQ,452
+foamlib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+foamlib/_cases/__init__.py,sha256=_A1TTHuQfS9FH2_33lSEyLtOJZGFHZBco1tWJCVOHks,358
+foamlib/_cases/_async.py,sha256=e4lGTcQBbFGwfG6SmJks5aa5LWd_0dy01kgKZWAgTGQ,11655
+foamlib/_cases/_base.py,sha256=CNfutRnqniTNS1xQZ2EUeK0n2VXTgRoFHadepWBndKs,7434
+foamlib/_cases/_run.py,sha256=aD9JNv7YAs5GJGWXlYQAhr_-QT-46CUxecCPyrCmFA0,15631
+foamlib/_cases/_slurm.py,sha256=2nimUWxHSkZdtmRROzcvnLW5urgmkNqxoTkCUmxALVE,2689
+foamlib/_cases/_subprocess.py,sha256=VHV2SuOLqa711an6kCuvN6UlIkeh4qqFfdrpNoKzQps,5630
+foamlib/_cases/_sync.py,sha256=yhrkwStKri7u41YImYCGBH4REcKn8Ar-32VW_WPa40c,9641
+foamlib/_cases/_util.py,sha256=QCizfbuJdOCeF9ogU2R-y-iWX5kfaOA4U2W68t6QlOM,2544
+foamlib/_files/__init__.py,sha256=q1vkjXnjnSZvo45jPAICpWeF2LZv5V6xfzAR6S8fS5A,96
+foamlib/_files/_files.py,sha256=gSJQjvB1f7N2yJtCTx9kpivKqSSNjDj37qNMpned5CM,19505
+foamlib/_files/_io.py,sha256=BGbbm6HKxL2ka0YMCmHqZQZ1R4PPQlkvWWb4FHMAS8k,2217
+foamlib/_files/_parsing.py,sha256=IB6c9mc0AM_z_Gh7K82Z1ANseGaNwmzUo8AYv3pxEBw,14111
+foamlib/_files/_serialization.py,sha256=QJ-F6BKizVe0gpjnpIfPxNGTqWwalY4PQtCKdDY9D70,5502
+foamlib/_files/_types.py,sha256=PDhFW5hUzcoQsLx7M0Va1oaYV6km02jFgrvKJof0JKQ,3750
+foamlib-0.8.9.dist-info/METADATA,sha256=zkGORMaEmCITWARJJOI-HxsAZGeXknnzKOMqA6ixa-c,14014
+foamlib-0.8.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+foamlib-0.8.9.dist-info/licenses/LICENSE.txt,sha256=5Dte9TUnLZzPRs4NQzl-Jc2-Ljd-t_v0ZR5Ng5r0UsY,35131
+foamlib-0.8.9.dist-info/RECORD,,

foamlib-0.8.8.dist-info/RECORD

@@ -1,20 +0,0 @@
-foamlib/__init__.py,sha256=ef8IIQjKj7fPW-7t7Oeo-bUD9Wy3bJY5Q63lobifP7o,452
-foamlib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-foamlib/_cases/__init__.py,sha256=_A1TTHuQfS9FH2_33lSEyLtOJZGFHZBco1tWJCVOHks,358
-foamlib/_cases/_async.py,sha256=vXpq5T2gDomuawARsLaUEMjUBhMsZK58q7iVwQpXsYE,7903
-foamlib/_cases/_base.py,sha256=37oBbM3NM-hpG7dKewZvyJNtqSAogMurcbmX-wLIgMU,6727
-foamlib/_cases/_run.py,sha256=L2q9wab_pIbDpqC_N59ZpatgvjuDzQAWllQMyOHb1Hk,15475
-foamlib/_cases/_slurm.py,sha256=Hzpf5Ugahwq7sUsCfhZ6JgXDOdkoYGGsHGiO7NV8uFs,2331
-foamlib/_cases/_subprocess.py,sha256=VHV2SuOLqa711an6kCuvN6UlIkeh4qqFfdrpNoKzQps,5630
-foamlib/_cases/_sync.py,sha256=e06aGGZ9n6WTWK9eWZhrezsT4yebGhKPE0sn0nwQH8A,5977
-foamlib/_cases/_util.py,sha256=QCizfbuJdOCeF9ogU2R-y-iWX5kfaOA4U2W68t6QlOM,2544
-foamlib/_files/__init__.py,sha256=q1vkjXnjnSZvo45jPAICpWeF2LZv5V6xfzAR6S8fS5A,96
-foamlib/_files/_files.py,sha256=YAKw3RHEw8eCja4JAxobp6BC-2Kyy7AvG1O7yOqyMic,15414
-foamlib/_files/_io.py,sha256=BGbbm6HKxL2ka0YMCmHqZQZ1R4PPQlkvWWb4FHMAS8k,2217
-foamlib/_files/_parsing.py,sha256=IB6c9mc0AM_z_Gh7K82Z1ANseGaNwmzUo8AYv3pxEBw,14111
-foamlib/_files/_serialization.py,sha256=PvMzNyTja6OKT_GUfExTulx9nMLBjfu0-9yThCKbvxs,5227
-foamlib/_files/_types.py,sha256=m-fFjJnS4sFSavDsijlXpAfEhnbh10RBumSHAT0GOgQ,3408
-foamlib-0.8.8.dist-info/METADATA,sha256=DdEh3U5bZ9VZmxA-3-0GlMgl_XNlPhwRDdE_K41bvT4,7996
-foamlib-0.8.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-foamlib-0.8.8.dist-info/licenses/LICENSE.txt,sha256=5Dte9TUnLZzPRs4NQzl-Jc2-Ljd-t_v0ZR5Ng5r0UsY,35131
-foamlib-0.8.8.dist-info/RECORD,,