foamlib 0.9.4__py3-none-any.whl → 0.9.6__py3-none-any.whl

foamlib/__init__.py

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

foamlib/_cases/_async.py

@@ -44,13 +44,14 @@ 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.
+    Access the time directories of the case as a sequence, e.g. ``case[0]`` or ``case[-1]``.
+    These will return :class:`AsyncFoamCase.TimeDirectory` objects.
 
     :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
@@ -82,7 +83,7 @@ class AsyncFoamCase(FoamCaseRunBase):
 
     max_cpus = multiprocessing.cpu_count()
     """
-    Maximum number of CPUs to use for running instances of `AsyncFoamCase` concurrently.
+    Maximum number of CPUs to use for running instances of :class:`AsyncFoamCase` concurrently.
 
     Defaults to the number of CPUs on the system.
     """
@@ -143,19 +144,23 @@ class AsyncFoamCase(FoamCaseRunBase):
         """
         Clean this case.
 
-        If a `clean` or `Allclean` script is present in the case directory, it will be invoked.
+        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.
+        - 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.
+        ``clean`` script.
 
-        :param check: If True, raise a `CalledProcessError` if the clean script returns a
+        :param check: If True, raise a :class:`CalledProcessError` if the clean script returns a
             non-zero exit code.
         """
         for coro in self._clean_calls(check=check):
@@ -191,35 +196,40 @@ class AsyncFoamCase(FoamCaseRunBase):
         """
         Run this case, or a specified command in the context of this case.
 
-        If `cmd` is given, this method will run the given command in the context of the case.
+        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
+        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()`.
+        - 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
+          :meth:`block_mesh()`.
+
+        - Then, if a ``0.orig`` directory is present, it will call :meth:`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 :meth:`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.
+        ``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
+        :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
+        :param cpus: The number of CPUs to use. If ``None``, autodetect from to the case.
+        :param check: If ``True``, raise a :class:`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.
+        :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
@@ -262,6 +272,7 @@ class AsyncFoamCase(FoamCaseRunBase):
         :return: The copy of the case.
 
         Example usage: ::
+
             import os
             from pathlib import Path
             from foamlib import AsyncFoamCase
@@ -298,6 +309,7 @@ class AsyncFoamCase(FoamCaseRunBase):
         :return: The clone of the case.
 
         Example usage: ::
+
             import os
             from pathlib import Path
             from foamlib import AsyncFoamCase

foamlib/_cases/_base.py

@@ -23,10 +23,10 @@ class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
 
     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.
+    :class:`FoamCase` or :class:`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.
+    Access the time directories of the case as a sequence, e.g. ``case[0]`` or ``case[-1]``.
+    These will return class:`FoamCaseBase.TimeDirectory` objects.
 
     :param path: The path to the case directory. Defaults to the current working
         directory.
@@ -39,11 +39,11 @@ class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
         """
         A time directory in an OpenFOAM case.
 
-        Use to access field files in the directory (e.g. `time["U"]`). These will be
-        returned as `FoamFieldFile` objects.
+        Use to access field files in the directory (e.g. ``time["U"]``). These will be
+        returned as :class:`FoamFieldFile` objects.
 
-        It also behaves as a set of `FoamFieldFile` objects (e.g. it can be
-        iterated over with `for field in time: ...`).
+        It also behaves as a set of :class:`FoamFieldFile` objects (e.g. it can be
+        iterated over with ``for field in time: ...``).
         """
 
         def __init__(self, path: os.PathLike[str] | str) -> None:
@@ -154,7 +154,7 @@ class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
 
     @property
     def _nsubdomains(self) -> int | None:
-        """Return the number of subdomains as set in the decomposeParDict, or None if no decomposeParDict is found."""
+        """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):

foamlib/_cases/_run.py

@@ -47,9 +47,9 @@ if TYPE_CHECKING:
 
 class FoamCaseRunBase(FoamCaseBase):
     """
-    Abstract base class of `FoamCase` and `AsyncFoamCase`.
+    Abstract base class of :class:`FoamCase` and :class:`AsyncFoamCase`.
 
-    Do not use this class directly: use `FoamCase` or `AsyncFoamCase` instead.
+    Do not use this class directly: use :class:`FoamCase` or :class:`AsyncFoamCase` instead.
     """
 
     class TimeDirectory(FoamCaseBase.TimeDirectory):

foamlib/_cases/_slurm.py

@@ -20,9 +20,9 @@ class AsyncSlurmFoamCase(AsyncFoamCase):
     """
     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.
+    :class:`AsyncSlurmFoamCase` is a subclass of :class:`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.
@@ -64,12 +64,12 @@ class AsyncSlurmFoamCase(AsyncFoamCase):
         """
         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. If 0, run locally.
-        :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.
-        :param fallback: If True, fall back to running the command locally if Slurm is not available.
+        :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. If ``0``, run locally.
+        :param check: If ``True``, raise a :class:`CalledProcessError` if any command returns a non-zero exit code.
+        :param log: If ``True``, log the command output to a file.
+        :param fallback: If ``True``, fall back to running the command locally if Slurm is not available.
         """
         for coro in self._run_calls(
             cmd=cmd,

foamlib/_cases/_sync.py

@@ -32,8 +32,8 @@ 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.
+    Access the time directories of the case as a sequence, e.g. ``case[0]`` or ``case[-1]``.
+    These will return :class:`FoamCase.TimeDirectory` objects.
 
     :param path: The path to the case directory. Defaults to the current working
         directory.
@@ -125,19 +125,23 @@ class FoamCase(FoamCaseRunBase):
         """
         Clean this case.
 
-        If a `clean` or `Allclean` script is present in the case directory, it will be invoked.
+        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.
+        - 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.
+        ``clean`` script.
 
-        :param check: If True, raise a `CalledProcessError` if the clean script returns a
+        :param check: If True, raise a :class:`CalledProcessError` if the clean script returns a
             non-zero exit code.
         """
         for _ in self._clean_calls(check=check):
@@ -159,35 +163,40 @@ class FoamCase(FoamCaseRunBase):
         """
         Run this case, or a specified command in the context of this case.
 
-        If `cmd` is given, this method will run the given command in the context of the case.
+        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
+        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()`.
+        - 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 :param:`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
+          :meth:`block_mesh()`.
+
+        - Then, if a ``0.orig`` directory is present, it will call :meth:`restore_0_dir()`.
+
+        - Then, if the case is to be run in parallel (see the :param:`parallel` option) and no
+          ``processor*`` directories exist but a ``system/decomposeParDict`` file is present, it will
+          call :meth:`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.
+        ``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
+        :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
+        :param cpus: The number of CPUs to use. If ``None``, autodetect from to the case.
+        :param check: If ``True``, raise a :class:`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.
+        :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
@@ -218,14 +227,15 @@ class FoamCase(FoamCaseRunBase):
         """
         Make a copy of this case.
 
-        If used as a context manager (i.e., within a `with` block) the copy will be deleted
+        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
@@ -245,17 +255,18 @@ class FoamCase(FoamCaseRunBase):
         """
         Clone this case (make a clean copy).
 
-        This is equivalent to running `self.copy().clean()`, but it can be more efficient in cases
+        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
+        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`.
+        :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

foamlib/_files/_files.py

@@ -72,30 +72,31 @@ class FoamFile(
     """
     An OpenFOAM data file.
 
-    `FoamFile` supports most OpenFOAM data and configuration files (i.e., files with a
+    :class:`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 `FoamFile` as a mutable mapping (i.e., like a `dict`) to access and modify
+    Use :class:`FoamFile` as a mutable mapping (i.e., like a :class:`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.
+    :class:`FoamFile.SubDict` object, that allows for further access and modification of nested
+    dictionaries within the :class:`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]`).
+    If the :class:`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)
+    You can also use the :class:`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.
+        in a non-existent file, a :class:`FileNotFoundError` will be raised.
 
     Example usage: ::
+
         from foamlib import FoamFile
 
         file = FoamFile("path/to/case/system/controlDict") # Load a controlDict file
@@ -104,6 +105,7 @@ class FoamFile(
         file["writeFormat"] = "binary" # Set the write format to binary
 
     or (better): ::
+
         from foamlib import FoamCase
 
         case = FoamCase("path/to/case")
@@ -123,14 +125,15 @@ class FoamFile(
         """
         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.
+        :class:`FoamFile.SubDict` is a mutable mapping that allows for accessing and modifying
+        nested dictionaries within a :class:`FoamFile` in a single operation. It behaves like a
+        :class:`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"]`).
+        To obtain a :class:`FoamFile.SubDict` object, access a sub-dictionary in a :class:`FoamFile`
+        object (e.g., ``file["subDict"]``).
 
         Example usage: ::
+
             from foamlib import FoamFile
 
             file = FoamFile("path/to/case/system/fvSchemes") # Load an fvSchemes file
@@ -138,6 +141,7 @@ class FoamFile(
             file["ddtSchemes"]["default"] = "Euler" # Set the default ddt scheme
 
         or (better): ::
+
             from foamlib import FoamCase
 
             case = FoamCase("path/to/case")
@@ -200,7 +204,7 @@ class FoamFile(
 
     @property
     def version(self) -> float:
-        """Alias of `self["FoamFile", "version"]`."""
+        """Alias of ``self["FoamFile"]["version"]``."""
         ret = self["FoamFile", "version"]
         if not isinstance(ret, (int, float)):
             msg = "version is not a number"
@@ -213,7 +217,7 @@ class FoamFile(
 
     @property
     def format(self) -> Literal["ascii", "binary"]:
-        """Alias of `self["FoamFile", "format"]`."""
+        """Alias of ``self["FoamFile"]["format"]``."""
         ret = self["FoamFile", "format"]
         if not isinstance(ret, str):
             msg = "format is not a string"
@@ -229,7 +233,7 @@ class FoamFile(
 
     @property
     def class_(self) -> str:
-        """Alias of `self["FoamFile", "class"]`."""
+        """Alias of ``self["FoamFile"]["class"]``."""
         ret = self["FoamFile", "class"]
         if not isinstance(ret, str):
             msg = "class is not a string"
@@ -242,7 +246,7 @@ class FoamFile(
 
     @property
     def location(self) -> str:
-        """Alias of `self["FoamFile", "location"]`."""
+        """Alias of ``self["FoamFile"]["location"]``."""
         ret = self["FoamFile", "location"]
         if not isinstance(ret, str):
             msg = "location is not a string"
@@ -255,7 +259,7 @@ class FoamFile(
 
     @property
     def object_(self) -> str:
-        """Alias of `self["FoamFile", "object"]`."""
+        """Alias of ``self["FoamFile"]["object"]``."""
         ret = self["FoamFile", "object"]
         if not isinstance(ret, str):
             msg = "object is not a string"
@@ -500,7 +504,7 @@ class FoamFile(
         :param file: The Python object to serialize. This can be a dictionary, list,
             or any other object that can be serialized to the OpenFOAM format.
         :param ensure_header: Whether to include the "FoamFile" header in the output.
-            If `True`, a header will be included if it is not already present in the
+            If ``True``, a header will be included if it is not already present in the
             input object.
         """
         header: SubDict | None
@@ -547,20 +551,21 @@ class FoamFile(
 
 class FoamFieldFile(FoamFile):
     """
-    Subclass of `FoamFile` for representing OpenFOAM field files specifically.
+    Subclass of :class:`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
+    The difference between :class:`FoamFieldFile` and :class:`FoamFile` is that :class:`FoamFieldFile` has
+    the additional properties :attr:`dimensions`, :attr:`internal_field`, and :attr:`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.
+    See :class:`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.
+        in a non-existent file, a :class:`FileNotFoundError` will be raised.
 
     Example usage: ::
+
         from foamlib import FoamFieldFile
 
         field = FoamFieldFile("path/to/case/0/U") # Load a field
@@ -569,6 +574,7 @@ class FoamFieldFile(FoamFile):
         field.internal_field = [0, 0, 0] # Set the internal field
 
     or (better): ::
+
         from foamlib import FoamCase
 
         case = FoamCase("path/to/case")
@@ -591,7 +597,7 @@ class FoamFieldFile(FoamFile):
 
         @property
         def type(self) -> str:
-            """Alias of `self["type"]`."""
+            """Alias of ``self["type"]``."""
             ret = self["type"]
             if not isinstance(ret, str):
                 msg = "type is not a string"
@@ -606,7 +612,7 @@ class FoamFieldFile(FoamFile):
         def value(
             self,
         ) -> Field:
-            """Alias of `self["value"]`."""
+            """Alias of ``self["value"]``."""
             return cast(
                 "Field",
                 self["value"],
@@ -641,7 +647,7 @@ class FoamFieldFile(FoamFile):
 
     @property
     def dimensions(self) -> DimensionSet | Sequence[float]:
-        """Alias of `self["dimensions"]`."""
+        """Alias of ``self["dimensions"]``."""
         ret = self["dimensions"]
         if not isinstance(ret, DimensionSet):
             msg = "dimensions is not a DimensionSet"
@@ -656,7 +662,7 @@ class FoamFieldFile(FoamFile):
     def internal_field(
         self,
     ) -> Field:
-        """Alias of `self["internalField"]`."""
+        """Alias of ``self["internalField"]``."""
         return cast("Field", self["internalField"])
 
     @internal_field.setter
@@ -668,7 +674,7 @@ class FoamFieldFile(FoamFile):
 
     @property
     def boundary_field(self) -> FoamFieldFile.BoundariesSubDict:
-        """Alias of `self["boundaryField"]`."""
+        """Alias of ``self["boundaryField"]``."""
         ret = self["boundaryField"]
         if not isinstance(ret, FoamFieldFile.BoundariesSubDict):
             assert not isinstance(ret, FoamFile.SubDict)

foamlib/_files/_parsing.py

@@ -363,11 +363,14 @@ _FIELD = (Keyword("uniform", _IDENTBODYCHARS).suppress() + _TENSOR) | (
 _DIRECTIVE = Word("#", _IDENTBODYCHARS)
 _TOKEN = dbl_quoted_string | _DIRECTIVE | _IDENTIFIER
 _DATA = Forward()
+_DATA_ENTRY = Forward()
 _KEYWORD_ENTRY = _keyword_entry_of(
-    _TOKEN | _list_of(_IDENTIFIER), Opt(_DATA, default="")
+    _TOKEN | _list_of(_IDENTIFIER),
+    Opt(_DATA, default=""),
+    directive=_DIRECTIVE,
+    data_entry=_DATA_ENTRY,
 )
 _DICT = _dict_of(_TOKEN, _DATA)
-_DATA_ENTRY = Forward()
 _LIST_ENTRY = _DICT | _KEYWORD_ENTRY | _DATA_ENTRY
 _LIST = _list_of(_LIST_ENTRY)
 _NUMBER = (
@@ -388,9 +391,9 @@ _DATA <<= _DATA_ENTRY[1, ...].set_parse_action(
 
 _STANDALONE_DATA = (
     _ascii_numeric_list(dtype=int, ignore=_COMMENT)
+    | _ascii_numeric_list(dtype=float, nested=3, ignore=_COMMENT)
     | _binary_numeric_list(dtype=np.int64)
     | _binary_numeric_list(dtype=np.int32)
-    | _ascii_numeric_list(dtype=float, nested=3, ignore=_COMMENT)
     | _binary_numeric_list(dtype=np.float64, nested=3)
     | _binary_numeric_list(dtype=np.float32, nested=3)
     | _DATA

foamlib/_files/_serialization.py

@@ -87,7 +87,7 @@ def normalize_data(
                 if arr.ndim == 1 or (arr.ndim == 2 and arr.shape[1] in (3, 6, 9)):
                     return arr  # type: ignore [return-value]
 
-            return [normalize_data(d) for d in data]  # type: ignore [arg-type]
+            return [normalize_data(d) for d in data]  # type: ignore [arg-type, misc]
 
         if isinstance(data, int):
             return float(data)
@@ -112,7 +112,7 @@ def normalize_data(
     if keywords is None and isinstance(data, tuple) and len(data) == 2:
         k, v = data
         assert not isinstance(k, Mapping)
-        return (
+        return (  # type: ignore [return-value]
             normalize_keyword(k),  # type: ignore [arg-type]
             normalize_data(v) if not isinstance(v, Mapping) else v,  # type: ignore [arg-type, misc]
         )
@@ -122,10 +122,10 @@ def normalize_data(
         and not isinstance(data, DimensionSet)
         and not isinstance(data, tuple)
     ):
-        return [normalize_data(d) for d in data]  # type: ignore [arg-type]
+        return [normalize_data(d) for d in data]  # type: ignore [arg-type, misc]
 
     if isinstance(data, tuple) and not isinstance(data, DimensionSet):
-        return tuple(normalize_data(d) for d in data)
+        return tuple(normalize_data(d) for d in data)  # type: ignore [misc]
 
     if isinstance(data, str):
         s = loads(data)
@@ -247,7 +247,8 @@ def dumps(
     if isinstance(data, tuple):
         if tuple_is_entry:
             k, v = data
-            ret = dumps(k)
+            ret = b"\n" if isinstance(k, str) and k[0] == "#" else b""
+            ret += dumps(k)
             val = dumps(
                 v,
                 keywords=(*keywords, k)
@@ -256,7 +257,9 @@ def dumps(
             )
             if val:
                 ret += b" " + val
-            if not isinstance(v, Mapping):
+            if isinstance(k, str) and k[0] == "#":
+                ret += b"\n"
+            elif not isinstance(v, Mapping):
                 ret += b";"
             return ret
 

foamlib/_files/_types.py

@@ -199,25 +199,38 @@ FieldLike = Union[
 ]
 
 
-Data = Union[
+DataEntry = Union[
     str,
     int,
     float,
     bool,
     Dimensioned,
     DimensionSet,
-    Tuple["Data", ...],
-    List[Union["Data", Tuple["Data", Union["Data", "SubDict"]]]],
+    List[Union["DataEntry", Tuple["DataEntry", Union["DataEntry", "SubDict"]]]],
     Field,
 ]
 
-DataLike = Union[
-    Data,
-    Tuple["DataLike", ...],
-    Sequence[Union["DataLike", Tuple["DataLike", Union["DataLike", "SubDictLike"]]]],
+DataEntryLike = Union[
+    DataEntry,
+    Sequence[
+        Union[
+            "DataEntryLike",
+            Tuple["DataEntryLike", Union["DataEntryLike", "SubDictLike"]],
+        ]
+    ],
     FieldLike,
 ]
 
+Data = Union[
+    DataEntry,
+    Tuple[DataEntry, ...],
+]
+
+DataLike = Union[
+    DataEntryLike,
+    Tuple["DataEntryLike", ...],
+]
+
 StandaloneData = Union[
     Data,
     "np.ndarray[tuple[int], np.dtype[np.int64 | np.int32]]",

{foamlib-0.9.4.dist-info → foamlib-0.9.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foamlib
-Version: 0.9.4
+Version: 0.9.6
 Summary: A Python interface for interacting with OpenFOAM
 Project-URL: Homepage, https://github.com/gerlero/foamlib
 Project-URL: Repository, https://github.com/gerlero/foamlib
@@ -196,148 +196,9 @@ case = FoamCase(Path(__file__).parent)
 case.run()
 ```
 
-## ▶️ A complete example
+## 📘 Documentation
 
-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/).
+For details on how to use **foamlib**, check out the [documentation](https://foamlib.readthedocs.io/).
 
 ## 🙋 Support
 

foamlib-0.9.6.dist-info/RECORD

@@ -0,0 +1,20 @@
+foamlib/__init__.py,sha256=vCYvM91T-aVKjhzaBbxMdeEvOdQ_0dFOLV5vLi7yMoU,452
+foamlib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+foamlib/_cases/__init__.py,sha256=_A1TTHuQfS9FH2_33lSEyLtOJZGFHZBco1tWJCVOHks,358
+foamlib/_cases/_async.py,sha256=1NuBaKa7NC-320SFNYW7JWZ5rAi344br_SoEdl64dmo,11797
+foamlib/_cases/_base.py,sha256=0Bb45FWxxMRnx6njtnJ3Tqh2_NcphrPtVSFjmfYbTjw,7480
+foamlib/_cases/_run.py,sha256=C5sf-PWE73cqyPVmmWDiZU3V9QYVsrhSXpgil7aIp10,15659
+foamlib/_cases/_slurm.py,sha256=X8eSL_tDnip3bPHb2Fot-n1yD0FfiVP5sCxHxjKt1f0,2748
+foamlib/_cases/_subprocess.py,sha256=VHV2SuOLqa711an6kCuvN6UlIkeh4qqFfdrpNoKzQps,5630
+foamlib/_cases/_sync.py,sha256=lsgJV2dMAAmmsiJMtzqy1bhW3yAZQOUMXh3h8jNqyes,9799
+foamlib/_cases/_util.py,sha256=QCizfbuJdOCeF9ogU2R-y-iWX5kfaOA4U2W68t6QlOM,2544
+foamlib/_files/__init__.py,sha256=q1vkjXnjnSZvo45jPAICpWeF2LZv5V6xfzAR6S8fS5A,96
+foamlib/_files/_files.py,sha256=HwK7ptuxmbpymXaAr6Lsd1g-qc6trGZSC1Ch1wVHQFQ,22863
+foamlib/_files/_io.py,sha256=BGbbm6HKxL2ka0YMCmHqZQZ1R4PPQlkvWWb4FHMAS8k,2217
+foamlib/_files/_parsing.py,sha256=AOrAEhX418ExfuX-_gKezQPLpu6B-fZmAVpJ1EVMWGw,17718
+foamlib/_files/_serialization.py,sha256=P7u2EUx0OwvfVYinp46CpzdjGYGXJVN0-xXXuOYogfA,8020
+foamlib/_files/_types.py,sha256=eNVxuK_NDRqh0mrTcseuAD3lqn4VEBGVUYhXn-T1zEU,7884
+foamlib-0.9.6.dist-info/METADATA,sha256=V2i6Gb4Yl07tXbwKGNLNUyi3LN6ozr4cl79CUWeuK-w,8701
+foamlib-0.9.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+foamlib-0.9.6.dist-info/licenses/LICENSE.txt,sha256=5Dte9TUnLZzPRs4NQzl-Jc2-Ljd-t_v0ZR5Ng5r0UsY,35131
+foamlib-0.9.6.dist-info/RECORD,,

foamlib-0.9.4.dist-info/RECORD

@@ -1,20 +0,0 @@
-foamlib/__init__.py,sha256=LQALCtihE20dGUDWlQdYlr_X7vLFUhOExPzWqPtDDAY,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=nbf9SPGH4v4-H4mxiMtiD8YuBJJdGC8RFlV_KLFM6bA,22676
-foamlib/_files/_io.py,sha256=BGbbm6HKxL2ka0YMCmHqZQZ1R4PPQlkvWWb4FHMAS8k,2217
-foamlib/_files/_parsing.py,sha256=CWALQclNOXUlPylI98h2DxMNz5OE0KZf9Gioc9h3OWU,17659
-foamlib/_files/_serialization.py,sha256=R7hnUNWH1McOnu4k7grfbJKvNGhADSSTIOIXrDDtw74,7800
-foamlib/_files/_types.py,sha256=SmKA6I1l6Q7JHOlhLFV1s2cU3tkeBQmj13lW3ETlKU0,7710
-foamlib-0.9.4.dist-info/METADATA,sha256=jRLgmp_A9dsqH2P_RzhESlkSBLlGB3XeC4xFljDzhRM,12906
-foamlib-0.9.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-foamlib-0.9.4.dist-info/licenses/LICENSE.txt,sha256=5Dte9TUnLZzPRs4NQzl-Jc2-Ljd-t_v0ZR5Ng5r0UsY,35131
-foamlib-0.9.4.dist-info/RECORD,,