foamlib 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

foamlib/__init__.py

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

foamlib/_cases/_async.py

@@ -127,7 +127,7 @@ class AsyncFoamCase(FoamCaseRunBase):
     async def _rmtree(
         path: os.PathLike[str] | str, *, ignore_errors: bool = False
     ) -> None:
-        await aioshutil.rmtree(path, ignore_errors=ignore_errors)  # type: ignore [call-arg]
+        await aioshutil.rmtree(path, ignore_errors=ignore_errors, onerror=None)
 
     @staticmethod
     async def _copytree(

foamlib/_files/_parsing.py

@@ -120,7 +120,7 @@ def _ascii_numeric_list(
 
         ret: np.ndarray[
             tuple[int] | tuple[int, int], np.dtype[np.integer | np.floating]
-        ] = np.fromstring(s, sep=" ", dtype=dtype)  # type: ignore[assignment]
+        ] = np.fromstring(s, sep=" ", dtype=dtype)
 
         if nested is not None:
             ret = ret.reshape(-1, nested)
@@ -183,7 +183,7 @@ def _binary_numeric_list(
         if nested is not None:
             ret = ret.reshape(-1, nested)
 
-        return ret  # type: ignore[return-value]
+        return ret
 
     return (
         common.integer.copy().add_parse_action(process_count) + list_
@@ -236,7 +236,7 @@ def _ascii_face_list(*, ignore: Regex | None = None) -> ParserElement:
         i = 0
         while i < raw.size:
             assert raw[i] in (3, 4)
-            values.append(raw[i + 1 : i + raw[i] + 1])  # type: ignore[arg-type]
+            values.append(raw[i + 1 : i + raw[i] + 1])
             i += raw[i] + 1
 
         return [values]

foamlib/_files/_serialization.py

@@ -58,11 +58,11 @@ def normalize_data(
             pass
         else:
             if np.issubdtype(arr.dtype, np.integer) and arr.ndim == 1:
-                return arr  # type: ignore [return-value]
+                return arr
             if arr.ndim == 2 and arr.shape[1] == 3:
                 if not np.issubdtype(arr.dtype, np.floating):
                     arr = arr.astype(float)
-                return arr  # type: ignore [return-value]
+                return arr
 
     if keywords is not None and (
         keywords == ("internalField",)
@@ -86,7 +86,7 @@ def normalize_data(
                     arr = arr.astype(float)
 
                 if arr.ndim == 1 or (arr.ndim == 2 and arr.shape[1] in (3, 6, 9)):
-                    return arr  # type: ignore [return-value]
+                    return arr
 
             return [normalize_data(d) for d in data]  # type: ignore [arg-type, return-value]
 
@@ -197,7 +197,7 @@ def dumps(
         )
         and isinstance(data, (int, float, np.ndarray))
     ):
-        data = np.asarray(data)  # type: ignore [assignment]
+        data = np.asarray(data)
         class_ = header.get("class", "") if header else ""
         assert isinstance(class_, str)
         scalar = "Scalar" in class_

foamlib/_files/_types.py

@@ -89,7 +89,7 @@ class Dimensioned:
         name: str | None = None,
     ) -> None:
         if is_sequence(value):
-            self.value: Tensor = np.array(value, dtype=float)  # type: ignore [assignment]
+            self.value: Tensor = np.array(value, dtype=float)
         else:
             assert isinstance(value, (int, float, np.ndarray))
             self.value = float(value)
@@ -113,7 +113,7 @@ class Dimensioned:
             other = Dimensioned(other, DimensionSet())
 
         return Dimensioned(
-            self.value + other.value,  # type: ignore [arg-type]
+            self.value + other.value,
             self.dimensions + other.dimensions,
             f"{self.name}+{other.name}"
             if self.name is not None and other.name is not None
@@ -125,7 +125,7 @@ class Dimensioned:
             other = Dimensioned(other, DimensionSet())
 
         return Dimensioned(
-            self.value - other.value,  # type: ignore [arg-type]
+            self.value - other.value,
             self.dimensions - other.dimensions,
             f"{self.name}-{other.name}"
             if self.name is not None and other.name is not None
@@ -137,7 +137,7 @@ class Dimensioned:
             other = Dimensioned(other, DimensionSet())
 
         return Dimensioned(
-            self.value * other.value,  # type: ignore [arg-type]
+            self.value * other.value,
             self.dimensions * other.dimensions,
             f"{self.name}*{other.name}"
             if self.name is not None and other.name is not None
@@ -149,7 +149,7 @@ class Dimensioned:
             other = Dimensioned(other, DimensionSet())
 
         return Dimensioned(
-            self.value / other.value,  # type: ignore [arg-type]
+            self.value / other.value,
             self.dimensions / other.dimensions,
             f"{self.name}/{other.name}"
             if self.name is not None and other.name is not None
@@ -161,7 +161,7 @@ class Dimensioned:
             return NotImplemented
 
         return Dimensioned(
-            self.value**exponent,  # type: ignore [arg-type]
+            self.value**exponent,
             self.dimensions**exponent,
             f"pow({self.name},{exponent})" if self.name is not None else None,
         )

foamlib/postprocessing/__init__.py

@@ -0,0 +1,6 @@
+"""
+The postprocessing module provides utilities for processing and analyzing simulation data.
+
+It includes table readers and data extraction tools.
+
+"""

foamlib/postprocessing/load_tables.py

@@ -0,0 +1,311 @@
+# ruff: noqa: UP045
+"""Load OpenFOAM post-processing tables."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional, Union
+
+import pandas as pd
+
+from .table_reader import TableReader
+
+
+def _of_case(dirnames: list[str]) -> bool:
+    """Classify directory as OpenFOAM case.
+
+    Parameters
+    ----------
+    dirnames : list[str]
+        list of directories in the folder
+
+    Returns
+    ofcase : bool
+        is the folder an OpenFOAM Case
+    """
+    has_constant = "constant" in dirnames
+    has_system = "system" in dirnames
+    return has_constant and has_system
+
+
+def of_cases(dir_name: Union[str, Path]) -> list[str]:
+    """List all OpenFOAM cases in folder.
+
+    Parameters
+    ----------
+    dir_name : str
+        name of the search directory
+
+    Returns
+    ofcases : List[str]
+        pathes of the OpenFOAM directories
+    """
+    cases = []
+    for path, dirnames, _ in os.walk(dir_name):
+        if _of_case(dirnames):
+            cases.append(path)
+            dirnames[:] = []
+    return cases
+
+
+@dataclass
+class DataSource:
+    """
+    Describes a location of simulation output data inside a case directory.
+
+    Attributes
+    ----------
+    file_name : str
+        The name of the file to be read (e.g., 'forces.dat').
+    folder : Union[str, Path]
+        The subdirectory where the file is located, relative to case path.
+    time_resolved : bool
+        Whether data is stored in time-specific subdirectories.
+    postproc_prefix : str
+        Prefix for the post-processing directory, typically 'postProcessing'.
+    """
+
+    file_name: str
+    folder: Union[str, Path]
+    postproc_prefix: str
+    time_resolved: bool = True
+    _times: set[str] = field(default_factory=set, init=False, repr=False)
+
+    def add_time(self, t: str) -> None:
+        """Add a time step to the data source.
+
+        Parameters
+        ----------
+        t : str
+            Time step to add.
+        """
+        self._times.add(t)
+
+    @property
+    def times(self) -> list[str]:
+        """Get the list of time steps for this output file.
+
+        Returns
+        -------
+        list[str]
+            List of time steps as strings.
+        """
+        return sorted(self._times)
+
+    def postproc_folder(self, case_path: Path) -> Path:
+        """Return the path to the target's base directory under postProcessing/."""
+        return case_path / self.postproc_prefix / self.folder
+
+    def resolve_paths(self, case_path: Path) -> list[Path]:
+        """
+        Compute full file paths for this target inside the given case.
+
+        Parameters
+        ----------
+        case_path : Path
+            Root path of the case directory.
+
+        Returns
+        -------
+        list[Path]
+            List of resolved file paths to load.
+        """
+        base = self.postproc_folder(case_path)
+        if self.time_resolved:
+            return [base / t / self.file_name for t in self.times]
+        return [base / self.file_name]
+
+
+def functionobject(file_name: str, folder: Union[str, Path]) -> DataSource:
+    """
+    Create a DataTarget for a standard OpenFOAM function object.
+
+    Parameters
+    ----------
+    name : str
+        The function object name (and default folder).
+    file_name : str, optional
+        The file name to look for (defaults to '<name>.dat').
+
+    Returns
+    -------
+    DataTarget
+    """
+    return DataSource(
+        file_name=file_name,
+        folder=folder,
+        time_resolved=True,
+        postproc_prefix="postProcessing",
+    )
+
+
+def datafile(
+    file_name: str, folder: Union[str, Path], *, time_resolved: bool = False
+) -> DataSource:
+    """
+    Create a DataTarget for a custom or non-OpenFOAM output file.
+
+    Parameters
+    ----------
+    file_name : str
+        Name of the file (e.g., 'output.xml').
+    folder : str or Path
+        Subdirectory where the file is located (relative to 'postProcessing/').
+    time_resolved : bool
+        Whether the data is organized by time subfolders.
+
+    Returns
+    -------
+    DataTarget
+    """
+    return DataSource(
+        file_name=file_name,
+        folder=folder,
+        time_resolved=time_resolved,
+        postproc_prefix=".",
+    )
+
+
+def load_tables(
+    source: DataSource,
+    dir_name: Union[str, Path],
+    filter_table: Optional[
+        Callable[[pd.DataFrame, list[dict[str, str]]], pd.DataFrame]
+    ] = None,
+    reader_fn: Optional[Callable[[Path], Optional[pd.DataFrame]]] = None,
+) -> Optional[pd.DataFrame]:
+    """
+    Load and concatenate all available dataframes for a DataTarget across cases and time steps.
+
+    Parameters
+    ----------
+    source : DataSource
+        source data descriptor for resolving output paths.
+    dir_name : str or Path
+        Root directory where OpenFOAM cases are stored.
+    filter_table : callable, optional
+        Function to filter or modify the dataframe after reading.
+    reader_fn : callable, optional
+        Function to read a file into a DataFrame. Defaults to TableReader().read.
+        that considers the specific file format
+
+    Returns
+    -------
+    pd.DataFrame or None
+        Concatenated dataframe of all found data, or None if nothing was found.
+    """
+    all_tables = []
+    reader_fn = reader_fn or TableReader().read
+
+    for case in of_cases(dir_name):
+        case_path = Path(case)
+        target_folder = source.postproc_folder(case_path)
+
+        # Skip if the target folder does not exist
+        if not target_folder.exists():
+            continue
+
+        # Discover time steps if needed
+        if source.time_resolved and not source.times:
+            for item in target_folder.iterdir():
+                if item.is_dir() and _is_float(item.name):
+                    source.add_time(item.name)
+
+        for file_path in source.resolve_paths(case_path):
+            if not file_path.exists():
+                continue
+
+            table = reader_fn(file_path)
+            if table is None:
+                continue
+
+            # Load case metadata
+            json_path = case_path / "case.json"
+            parameters = []
+            if json_path.exists():
+                with open(json_path) as f:
+                    json_data = json.load(f)
+                    parameters = json_data.get("case_parameters", [])
+
+            # Add time value if applicable
+            if source.time_resolved and len(source.times) > 1:
+                time_str = file_path.parent.name
+                parameters.append({"category": "timeValue", "name": time_str})
+
+            # add parameters as columns
+            for parameter in parameters:
+                category = parameter["category"]
+                name = parameter["name"]
+                table[category] = name
+
+            if filter_table:
+                table = filter_table(table, parameters)
+
+            all_tables.append(table)
+
+    if all_tables:
+        return pd.concat(all_tables, ignore_index=True)
+
+    return None
+
+
+def _is_float(s: str) -> bool:
+    try:
+        float(s)
+    except ValueError:
+        return False
+    return True
+
+
+def _discover_function_objects(
+    file_map: dict[str, DataSource], postproc_root: Path
+) -> None:
+    for dirpath, _, filenames in os.walk(postproc_root):
+        base = Path(dirpath).name
+
+        if not _is_float(base):
+            # Skip directories that are not time directories
+            continue
+
+        time = base
+        time_path = Path(dirpath)
+        rel_to_postproc = time_path.relative_to(postproc_root)
+        folder = rel_to_postproc.parent
+        folder_str = str(folder) if folder != Path() else ""
+
+        for fname in filenames:
+            key = f"{folder_str}--{fname}"
+
+            if key not in file_map:
+                file_map[key] = functionobject(file_name=fname, folder=folder)
+
+            file_map[key].add_time(time)
+
+
+def list_function_objects(cases_folder: str = "Cases") -> dict[str, DataSource]:
+    """List all output files in OpenFOAM cases.
+
+    Parameters
+    ----------
+    cases_folder : str
+        Name of the search directory.
+
+    Returns
+    -------
+    file_map : dict[str, list[OutputFile]]
+        Dictionary with keys as file names and values as OutputFile objects.
+    """
+    file_map: dict[str, DataSource] = {}
+
+    for case_path_str in of_cases(cases_folder):
+        case_path = Path(case_path_str)
+        postproc_root = case_path / "postProcessing"
+        if not postproc_root.exists():
+            continue
+
+        _discover_function_objects(file_map, postproc_root)
+
+    return file_map

foamlib/postprocessing/table_reader.py

@@ -0,0 +1,315 @@
+# ruff: noqa: UP045
+"""This module provides a utility class for reading tabular data from files with various extensions."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from itertools import islice
+from pathlib import Path
+from typing import Callable, ClassVar, Optional, Union
+
+import pandas as pd
+from defusedxml.ElementTree import parse
+
+
+class ReaderNotRegisteredError(Exception):
+    """Exception raised when no reader is registered for a given file extension."""
+
+
+class TableReader:
+    """
+    TableReader is a utility class for reading tabular data from files with various extensions.
+
+    It uses a registry pattern to associate file extensions with specific reader functions.
+
+    Attributes:
+        _registry (Dict[str, Callable[[str], pd.DataFrame]]): A class-level dictionary that maps
+            file extensions (as strings) to reader functions. Each reader function takes a file
+            path as input and returns a pandas DataFrame.
+
+    Methods:
+        register(extension: str) -> Callable[[Callable[[str], pd.DataFrame]], Callable[[str], pd.DataFrame]]:
+            A class method decorator used to register a reader function for a specific file extension.
+            The extension is case-insensitive.
+
+        read(filepath: Union[str, Path]) -> pd.DataFrame:
+            Reads a file and returns its contents as a pandas DataFrame. The file extension is used
+            to determine the appropriate reader function. Raises a ValueError if no reader is registered
+            for the file's extension.
+    """
+
+    _registry: ClassVar[
+        dict[str, Callable[[Union[str, Path], Optional[list[str]]], pd.DataFrame]]
+    ] = {}
+
+    def __init__(self) -> None:
+        """Initialize the TableReader instance."""
+
+    @classmethod
+    def register(
+        cls, extension: str
+    ) -> Callable[
+        [Callable[[Union[str, Path], Optional[list[str]]], pd.DataFrame]],
+        Callable[[Union[str, Path], Optional[list[str]]], pd.DataFrame],
+    ]:
+        """
+        Register a reader function for a specific file extension.
+
+        The extension is case-insensitive.
+
+        Args:
+            extension (str): The file extension (e.g., ".dat", ".raw") to register the reader for.
+
+        Returns:
+            Callable[[Callable[[str, Optional[list[str]]], pd.DataFrame]], Callable[[str, Optional[list[str]]], pd.DataFrame]]:
+                A decorator that registers the function as a reader for the specified extension.
+        """
+
+        def decorator(
+            func: Callable[[Union[str, Path], Optional[list[str]]], pd.DataFrame],
+        ) -> Callable[[Union[str, Path], Optional[list[str]]], pd.DataFrame]:
+            cls._registry[extension.lower()] = func
+            return func
+
+        return decorator
+
+    def read(
+        self, filepath: Union[str, Path], column_names: Optional[list[str]] = None
+    ) -> pd.DataFrame:
+        """
+        Read a file and return its contents as a pandas DataFrame.
+
+        The file extension is used to determine the appropriate reader function.
+
+        Raises:
+            ValueError: If no reader is registered for the file's extension.
+
+        Args:
+            filepath (Union[str, Path]): The path to the file to be read.
+
+        Returns:
+            pd.DataFrame: The contents of the file as a pandas DataFrame.
+        """
+        ext = str(Path(filepath).suffix.lower())
+        if ext not in self._registry:
+            error_message = f"No reader registered for extension: '{ext}'"
+            raise ReaderNotRegisteredError(error_message)
+        return self._registry[ext](filepath, column_names)
+
+
+def is_convertible_to_float(values: list[str]) -> bool:
+    """
+    Check if all values in a list are convertible to floats.
+
+    Args:
+        values (list[str]): A list of string values to check.
+    Returns:
+        bool: True if all values are convertible to floats, False otherwise.
+    """
+    try:
+        [float(value) for value in values]
+    except ValueError:
+        return False
+    else:
+        return True
+
+
+def extract_column_names(filepath: Union[str, Path]) -> Optional[list[str]]:
+    """
+    Extract column names from the first 20 lines of a file.
+
+    Args:
+        filepath (str): The path to the file from which to extract column names.
+    Returns:
+        Optional[list[str]]: A list of column names extracted from the file, or None if no
+            comment lines are found.
+    """
+    with open(filepath) as f:
+        first_lines = [line.strip() for line in islice(f, 20)]
+
+    # Filter only comment lines
+    comment_lines = [line for line in first_lines if line.startswith("#")]
+
+    if not comment_lines:
+        return None
+
+    # Take the last comment line and split into column names
+    last_comment = comment_lines[-1]
+    headers = last_comment.lstrip("#").strip()
+    return headers.split()
+
+
+def update_column_names(
+    table: pd.DataFrame, column_names: Optional[list[str]]
+) -> pd.DataFrame:
+    """
+    Update the column names of a DataFrame if provided.
+
+    Args:
+        table (pd.DataFrame): The DataFrame to update.
+        column_names (Optional[list[str]]): The new column names to set.
+    Returns:
+        pd.DataFrame: The updated DataFrame with new column names.
+    """
+    if column_names is not None:
+        if len(column_names) != len(table.columns):
+            error_message = (
+                f"Number of column names ({len(column_names)}) does not match "
+                f"number of columns in DataFrame ({len(table.columns)})."
+            )
+            raise ValueError(error_message)
+        table.columns = pd.Index(column_names)
+    return table
+
+
+def read_oftable(
+    filepath: Union[str, Path], column_names: Optional[list[str]] = None
+) -> pd.DataFrame:
+    """
+    Use a regular expression to parse the file and separate on parentheses and whitespace.
+
+    Args:
+        filepath (str): The path to the .oftable file to be read.
+        column_names (Optional[list[str]]): Optional column names to assign to the DataFrame.
+
+    Returns:
+        pd.DataFrame: The contents of the .oftable file as a pandas DataFrame.
+    """
+    table = pd.read_csv(
+        filepath, comment="#", sep=r"[()\s]+", engine="python", header=None
+    )
+    # Remove empty columns
+    table = table.dropna(axis=1, how="all")
+    column_headers = extract_column_names(filepath)
+    if column_names is not None:
+        column_headers = column_names
+        if len(column_names) != len(table.columns):
+            column_names = None
+    if column_headers is None or len(column_headers) != len(table.columns):
+        column_headers = None
+    update_column_names(table, column_headers)
+    return table
+
+
+@TableReader.register(".dat")
+def read_dat(
+    filepath: Union[str, Path], column_names: Optional[list[str]] = None
+) -> pd.DataFrame:
+    """Read a .dat file and return a DataFrame."""
+    return read_oftable(filepath, column_names=column_names)
+
+
+@TableReader.register(".raw")
+def read_raw(
+    filepath: Union[str, Path], column_names: Optional[list[str]] = None
+) -> pd.DataFrame:
+    """Read a .raw file and return a DataFrame."""
+    if column_names is None:
+        column_names = extract_column_names(filepath)
+    table = pd.read_csv(filepath, comment="#", sep=r"\s+", header=None)
+    update_column_names(table, column_names)
+    return table
+
+
+@TableReader.register("")
+def read_default(
+    filepath: Union[str, Path], column_names: Optional[list[str]] = None
+) -> pd.DataFrame:
+    """Read a file with no extension and return a DataFrame."""
+    return read_oftable(filepath, column_names=column_names)
+
+
+@TableReader.register(".xy")
+def read_xy(
+    filepath: Union[str, Path], column_names: Optional[list[str]] = None
+) -> pd.DataFrame:
+    """Read a .xy file and return a DataFrame."""
+    if column_names is None:
+        column_names = extract_column_names(filepath)
+    table = pd.read_csv(filepath, comment="#", sep=r"\s+", header=None)
+    update_column_names(table, column_names)
+    return table
+
+
+@TableReader.register(".csv")
+def read_csv(
+    filepath: Union[str, Path], column_names: Optional[list[str]] = None
+) -> pd.DataFrame:
+    """Read a .csv file and return a DataFrame."""
+    with open(filepath) as f:
+        first_lines = list(islice(f, 20))
+
+    non_comment_lines = [line for line in first_lines if not line.startswith("#")]
+
+    # check if all of the lines can be converted to floats
+    # assume the they are comma separated
+    entries = [line.split(",") for line in non_comment_lines]
+
+    # Check if all entries in each line are convertible to floats
+    has_header = not all(is_convertible_to_float(entry) for entry in entries)
+
+    if has_header:
+        table = pd.read_csv(filepath, comment="#")
+    else:
+        table = pd.read_csv(filepath, comment="#", header=None)
+    update_column_names(table, column_names)
+    return table
+
+
+def read_catch2_benchmark(
+    filepath: Union[str, Path], column_names: Optional[list[str]] = None
+) -> pd.DataFrame:
+    """Read a Catch2 XML benchmark results file and return a DataFrame."""
+    tree = parse(filepath)
+    root = tree.getroot()
+    if root is None:
+        err_msg = f"Unable to parse XML file: {filepath}"
+        raise ValueError(err_msg)
+
+    records = []
+
+    def _parse_sections(
+        sections: list[ET.Element], test_case_name: str, section_path: list[str]
+    ) -> None:
+        for section in sections:
+            name = section.attrib.get("name", "")
+            new_path = [*section_path, name]
+
+            subsections = section.findall("Section")
+            if subsections:
+                _parse_sections(subsections, test_case_name, new_path)
+            else:
+                benchmark = section.find("BenchmarkResults")
+                if benchmark is not None:
+                    mean = benchmark.find("mean")
+
+                    if mean is not None:
+                        record = {
+                            "test_case": test_case_name,
+                            "benchmark_name": benchmark.attrib.get("name"),
+                            "avg_runtime": float(mean.attrib.get("value", 0)),
+                        }
+
+                        # Add dynamic section depth fields
+                        for i, sec_name in enumerate(new_path):
+                            record[f"section{i + 1}"] = sec_name
+
+                        records.append(record)
+
+    for testcase in root.findall("TestCase"):
+        test_case_name = testcase.attrib.get("name")
+        if test_case_name:
+            _parse_sections(testcase.findall("Section"), str(test_case_name), [])
+
+    table = pd.DataFrame(records)
+
+    # Fill missing sectionN columns with empty string (not NaN)
+    max_sections = max((len(r) - 18 for r in records), default=0)
+    for i in range(1, max_sections + 1):
+        col = f"section{i}"
+        if col not in table.columns:
+            table[col] = ""
+
+    if column_names:
+        table = table[column_names]
+    return table

foamlib/preprocessing/__init__.py

@@ -0,0 +1 @@
+"""The preprocessing module provides tools and utilities for generating and modifying OpenFOAM cases."""

foamlib/preprocessing/case_modifier.py

@@ -0,0 +1,45 @@
+# ruff: noqa: UP006, D100
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+from pydantic import BaseModel
+
+from foamlib import FoamCase
+from foamlib.preprocessing.of_dict import FoamDictAssignment
+
+
+class CaseParameter(BaseModel):
+    """Class to represent a parameter for a case."""
+
+    category: str
+    name: str
+
+
+class CaseModifier(BaseModel):
+    """Class to handle the modification of a case by setting instruction-value pairs."""
+
+    template_case: Path
+    output_case: Path
+    key_value_pairs: List[FoamDictAssignment]
+    case_parameters: List[CaseParameter]
+
+    def create_case(self) -> FoamCase:
+        """Create a new case by copying the template case to the output case directory."""
+        of_case = FoamCase(path=self.template_case)
+        of_case.copy(dst=self.output_case)
+
+        return of_case
+
+    def modify_case(self) -> FoamCase:
+        """Modify the case by setting the instruction-value pairs and saving the case."""
+        of_case = FoamCase(path=self.output_case)
+
+        for pair in self.key_value_pairs:
+            pair.set_value(case_path=self.output_case)
+
+        with open(self.output_case / "case.json", "w") as json_file:
+            json_file.write(self.model_dump_json(indent=4))
+
+        return of_case

foamlib/preprocessing/grid_parameter_sweep.py

@@ -0,0 +1,27 @@
+# ruff: noqa: UP006, D100
+from __future__ import annotations
+
+from typing import Any, List
+
+from pydantic import BaseModel
+
+from foamlib.preprocessing.of_dict import FoamDictInstruction
+
+
+class CaseParameter(BaseModel):
+    """Class to represent a parameter for a case."""
+
+    name: str
+    values: List[Any]
+
+
+class GridParameter(BaseModel):
+    """Class to handle a grid parameter sweep by creating multiple cases based on parameter combinations."""
+
+    parameter_name: str
+    modify_dict: List[FoamDictInstruction]
+    parameters: List[CaseParameter]
+
+    def case_names(self) -> List[str]:
+        """Return the names of the cases."""
+        return [param.name for param in self.parameters]

foamlib/preprocessing/of_dict.py

@@ -0,0 +1,40 @@
+# ruff: noqa: UP006, D100, UP045
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+from pydantic import BaseModel
+
+from foamlib import FoamFile
+
+
+class FoamDictInstruction(BaseModel):
+    """Class representing an instruction to get a value from a FoamFile."""
+
+    file_name: Union[str, Path]
+    keys: List[str]
+
+    def get_value(self) -> Any:
+        """Get the value from the FoamFile based on the instruction."""
+        of_dict = FoamFile(self.file_name)
+        return of_dict.get(tuple(self.keys))
+
+
+class FoamDictAssignment(BaseModel):
+    """Class handling the modification of a FoamFile by setting a value for a given instruction."""
+
+    instruction: FoamDictInstruction
+    value: Any
+
+    def set_value(self, case_path: Optional[Path] = None) -> FoamFile:
+        """Set the value in the FoamFile with the given value and instruction."""
+        of_file = Path(self.instruction.file_name)
+        if case_path is not None:
+            of_file = case_path / of_file
+        if not of_file.exists():
+            err_msg = f"The file {of_file} does not exist."
+            raise FileNotFoundError(err_msg)
+        of_dict = FoamFile(of_file)
+        of_dict[tuple(self.instruction.keys)] = self.value
+        return of_dict

foamlib/preprocessing/parameter_study.py

@@ -0,0 +1,113 @@
+"""Parameter study module for generating multiple cases based on parameter combinations."""
+
+# ruff: noqa: UP006
+from __future__ import annotations
+
+import itertools
+from pathlib import Path
+from typing import List, Union
+
+import pandas as pd
+from pydantic import BaseModel
+
+from foamlib import FoamFile
+from foamlib.preprocessing.case_modifier import CaseModifier, CaseParameter
+from foamlib.preprocessing.grid_parameter_sweep import GridParameter
+from foamlib.preprocessing.of_dict import FoamDictAssignment, FoamDictInstruction
+
+
+class ParameterStudy(BaseModel):
+    """Class to handle a parameter study by creating multiple cases based on parameter combinations."""
+
+    cases: List[CaseModifier]
+
+    def create_study(self, study_base_folder: Path = Path()) -> None:
+        """Create multiple cases based on the parameter combinations."""
+        with open(study_base_folder / "parameter_study.json", "w") as json_file:
+            json_file.write(self.model_dump_json(indent=2))
+
+        for of_case in self.cases:
+            of_case.create_case()
+            of_case.modify_case()
+
+    def __add__(self, other: ParameterStudy) -> ParameterStudy:
+        """Combine two ParameterStudy instances."""
+        return ParameterStudy(cases=self.cases + other.cases)
+
+
+def csv_generator(
+    csv_file: str,
+    template_case: Union[str, Path],
+    output_folder: Union[str, Path] = Path("Cases"),
+) -> ParameterStudy:
+    """Generate a parameter study from a CSV file."""
+    parastudy = pd.read_csv(csv_file).to_dict(orient="records")
+    parameter = FoamFile(
+        Path(template_case) / "system" / "simulationParameters"
+    ).as_dict()
+    parameter_keys = set(parameter.keys())
+    case_keys = set(parastudy[0].keys())
+    category_keys = case_keys - parameter_keys - {"case_name"}
+
+    cases = []
+    for of_case in parastudy:
+        case_mod = CaseModifier(
+            template_case=Path(template_case),
+            output_case=Path(output_folder) / of_case["case_name"],
+            key_value_pairs=[
+                FoamDictAssignment(
+                    instruction=FoamDictInstruction(
+                        file_name=Path("system/simulationParameters"), keys=[str(key)]
+                    ),
+                    value=value,
+                )
+                for key, value in of_case.items()
+                if key in parameter_keys
+            ],
+            case_parameters=[
+                CaseParameter(category=str(key), name=of_case[str(key)])
+                for key, value in of_case.items()
+                if key in category_keys
+            ],
+        )
+        cases.append(case_mod)
+
+    return ParameterStudy(cases=cases)
+
+
+def grid_generator(
+    parameters: List[GridParameter],
+    template_case: Union[str, Path],
+    output_folder: Union[str, Path] = Path("Cases"),
+) -> ParameterStudy:
+    """Generate a parameter study based on grid parameters."""
+    cases = []
+
+    categories = [param.parameter_name for param in parameters]
+    case_instructions = [ins for param in parameters for ins in param.modify_dict]
+    case_parameters = itertools.product(*[param.parameters for param in parameters])
+
+    for case_parameter in case_parameters:
+        flattened_parameters = list(
+            itertools.chain.from_iterable(val.values for val in case_parameter)  # noqa: PD011
+        )
+        case_name = [val.name for val in case_parameter]
+        case_modifications = [
+            FoamDictAssignment(
+                instruction=case_instructions[i],
+                value=flattened_parameters[i],
+            )
+            for i in range(len(case_instructions))
+        ]
+        case_mod = CaseModifier(
+            template_case=Path(template_case),
+            output_case=Path(output_folder) / "_".join(case_name),
+            key_value_pairs=case_modifications,
+            case_parameters=[
+                CaseParameter(category=categories[i], name=str(case_parameter[i].name))
+                for i in range(len(case_parameter))
+            ],
+        )
+        cases.append(case_mod)
+
+    return ParameterStudy(cases=cases)

foamlib/preprocessing/system.py

@@ -0,0 +1,38 @@
+# ruff: noqa: N802, D100
+from __future__ import annotations
+
+from pathlib import Path
+
+from foamlib.preprocessing.of_dict import FoamDictInstruction
+
+
+def simulationParameters(keys: list[str]) -> FoamDictInstruction:
+    """Return the FoamDictInstruction for simulationParameters."""
+    return FoamDictInstruction(
+        file_name=Path("system/simulationParameters"),
+        keys=keys,
+    )
+
+
+def controlDict(keys: list[str]) -> FoamDictInstruction:
+    """Return the FoamDictInstruction for controlDict."""
+    return FoamDictInstruction(
+        file_name=Path("system/controlDict"),
+        keys=keys,
+    )
+
+
+def fvSchemes(keys: list[str]) -> FoamDictInstruction:
+    """Return the FoamDictInstruction for fvSchemes."""
+    return FoamDictInstruction(
+        file_name=Path("system/fvSchemes"),
+        keys=keys,
+    )
+
+
+def fvSolution(keys: list[str]) -> FoamDictInstruction:
+    """Return the FoamDictInstruction for fvSolution."""
+    return FoamDictInstruction(
+        file_name=Path("system/fvSolution"),
+        keys=keys,
+    )

{foamlib-1.0.0.dist-info → foamlib-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foamlib
-Version: 1.0.0
+Version: 1.1.0
 Summary: A Python interface for interacting with OpenFOAM
 Project-URL: Homepage, https://github.com/gerlero/foamlib
 Project-URL: Repository, https://github.com/gerlero/foamlib
@@ -34,6 +34,7 @@ Provides-Extra: docs
 Requires-Dist: ruff; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme; extra == 'docs'
 Requires-Dist: sphinx<9,>=5; extra == 'docs'
+Requires-Dist: sphinxcontrib-mermaid; extra == 'docs'
 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)
@@ -51,6 +52,8 @@ Description-Content-Type: text/markdown
 ![OpenFOAM](https://img.shields.io/badge/openfoam-.com%20|%20.org-informational)
 [![Docker](https://github.com/gerlero/foamlib/actions/workflows/docker.yml/badge.svg)](https://github.com/gerlero/foamlib/actions/workflows/docker.yml)
 [![Docker image](https://img.shields.io/badge/docker%20image-microfluidica%2Ffoamlib-0085a0)](https://hub.docker.com/r/microfluidica/foamlib/)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.07633/status.svg)](https://doi.org/10.21105/joss.07633)
+
 
 **foamlib** provides a simple, modern, ergonomic and fast Python interface for interacting with [OpenFOAM](https://www.openfoam.com).
 
@@ -92,6 +95,12 @@ Compared to [PyFoam](https://openfoamwiki.net/index.php/Contrib/PyFoam) and othe
     conda install -c conda-forge foamlib
     ```
 
+* With [Homebrew](https://brew.sh):
+
+    ```bash
+    brew install gerlero/openfoam/foamlib
+    ```
+
 ### 🐑 Clone a case
 
 ```python
@@ -210,6 +219,39 @@ If you believe you have found a bug in **foamlib**, please open an [issue](https
 
 You're welcome to contribute to **foamlib**! Check out the [contributing guidelines](CONTRIBUTING.md) for more information.
 
-## Footnotes
+## 🖋️Citation
+
+If you find **foamlib** useful for your work, don't forget to cite it!
+
+Citations help us a lot. You may find the following snippets useful:
+
+<details>
+<summary>BibTeX</summary>
+
+```bibtex
+@article{foamlib,
+    author = {Gerlero, Gabriel S. and Kler, Pablo A.},
+    doi = {10.21105/joss.07633},
+    journal = {Journal of Open Source Software},
+    month = may,
+    number = {109},
+    pages = {7633},
+    title = {{foamlib: A modern Python package for working with OpenFOAM}},
+    url = {https://joss.theoj.org/papers/10.21105/joss.07633},
+    volume = {10},
+    year = {2025}
+}
+```
+
+</details>
+
+<details>
+<summary>APA</summary>
+
+Gerlero, G. S., & Kler, P. A. (2025). foamlib: A modern Python package for working with OpenFOAM. Journal of Open Source Software, 10(109), 7633. https://doi.org/10.21105/joss.07633
+
+</details>
+
+## 👟 Footnotes
 
 <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-1.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+foamlib/__init__.py,sha256=DQJDDDj9OtWfj8xuZhADwfIJvsAkCeIChgIb7Z_5S-k,452
+foamlib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+foamlib/_cases/__init__.py,sha256=_A1TTHuQfS9FH2_33lSEyLtOJZGFHZBco1tWJCVOHks,358
+foamlib/_cases/_async.py,sha256=1syaHJ_OjB64SntT-rGOeV8IBFYs6ud4ZEcNrCDczIM,11784
+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=uMCn4kNdVJBbcEl7sTSDn9bpc6JUZtNUBbyio7oMqSg,24346
+foamlib/_files/_io.py,sha256=BGbbm6HKxL2ka0YMCmHqZQZ1R4PPQlkvWWb4FHMAS8k,2217
+foamlib/_files/_parsing.py,sha256=Y8Ft3Jh3TtvU8kp5YoOPkHVOVrec3bTzZTxBdcJPh3o,20450
+foamlib/_files/_serialization.py,sha256=sB3ySNSOEWMfMjmXVEysZa2GXSQ7m1Z7UrPLXlBBQoA,8050
+foamlib/_files/_types.py,sha256=fPoQeWMfFn5VQrCvLNbM1-TKUVUswFLSzIvUQQrro1M,8038
+foamlib/postprocessing/__init__.py,sha256=fKnBSOOL1wEnx5U1kNGqq6a97yVpwynwUpRQS8X_kW8,154
+foamlib/postprocessing/load_tables.py,sha256=cXNA2rCH5Lw8KGrZzCUd7vyVRmb5y1fP_pbrtEFW8p4,8580
+foamlib/postprocessing/table_reader.py,sha256=khCNjlFY-RuU6I29eK1WCK3B2wsq9QmWkzazNUcbvDk,10965
+foamlib/preprocessing/__init__.py,sha256=fHIVJyygymfWrwSf3usSZfrgEwAjaWnb_THUrX7taJI,105
+foamlib/preprocessing/case_modifier.py,sha256=GsqrPpEF3Rox1xcfBvGYhs1fDn6prR2hpSLY0M-2S_g,1292
+foamlib/preprocessing/grid_parameter_sweep.py,sha256=1D60KxVzps0xqinDEaA93wcnURYsWTAgJ8FcTwvIi4k,699
+foamlib/preprocessing/of_dict.py,sha256=MxdZsFd5yIsS1DHsbRa25eqPGe9IOmNE8EDY8Ok66Xg,1293
+foamlib/preprocessing/parameter_study.py,sha256=xQEhzOsOqZTpRcOmNWnyi18rus6BcLyDbg3ZXGHEKHQ,4080
+foamlib/preprocessing/system.py,sha256=EMCobbfg_upGC5-KSeuZagBOePQKcH2itGMjcMOlsFA,1047
+foamlib-1.1.0.dist-info/METADATA,sha256=GK1FTmI-2-0D23tExr1dzId9w7Vz61ZV1ucu22hbqso,9814
+foamlib-1.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+foamlib-1.1.0.dist-info/licenses/LICENSE.txt,sha256=5Dte9TUnLZzPRs4NQzl-Jc2-Ljd-t_v0ZR5Ng5r0UsY,35131
+foamlib-1.1.0.dist-info/RECORD,,

foamlib-1.0.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-foamlib/__init__.py,sha256=SRh8WyeRM2a0qihkJBUyUH1n5DEfiMnAhzMNmbbKB3Y,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=uMCn4kNdVJBbcEl7sTSDn9bpc6JUZtNUBbyio7oMqSg,24346
-foamlib/_files/_io.py,sha256=BGbbm6HKxL2ka0YMCmHqZQZ1R4PPQlkvWWb4FHMAS8k,2217
-foamlib/_files/_parsing.py,sha256=zLRXwv9PEil-vlIr1QiIEw8bhanRQ_vbVIEdTHv4bdI,20534
-foamlib/_files/_serialization.py,sha256=kQfPfuTXtc9jryQdieCbAX0-8_Oz__vY_kr7uH9f_rU,8172
-foamlib/_files/_types.py,sha256=7reA_TjRjCFV3waQVaGaYWURFoN8u92ao-NH9rESiAk,8202
-foamlib-1.0.0.dist-info/METADATA,sha256=Hfbzls1UGXMQQBRiTvHwAiCeKt5mxMwjqpMpmvG6l7M,8701
-foamlib-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-foamlib-1.0.0.dist-info/licenses/LICENSE.txt,sha256=5Dte9TUnLZzPRs4NQzl-Jc2-Ljd-t_v0ZR5Ng5r0UsY,35131
-foamlib-1.0.0.dist-info/RECORD,,