📄 File manipulation

class foamlib.FoamFile(path: PathLike[str] | str)

Bases: MutableMultiMapping[str | None, Data | StandaloneData | FoamFile.SubDict | None], PathLike[str], FoamFileIO

An OpenFOAM data file.

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, which are currently not supported. Non-FoamFile output files are also not supported 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 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.

Parameters:: 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"

property version: float: Alias of self["FoamFile"]["version"].

property format: Literal['ascii', 'binary']: Alias of self["FoamFile"]["format"].

property class_: str: Alias of self["FoamFile"]["class"].

property location: str: Alias of self["FoamFile"]["location"].

property object_: str: Alias of self["FoamFile"]["object"].

__getitem__(keywords: str | tuple[str, Unpack[tuple[str, ...]]]) → Data | FoamFile.SubDict | None

__getitem__(keywords: None | tuple[()]) → StandaloneData

Get the first value for a key.

Raises a KeyError if the key is not found.

__setitem__(keywords: str | tuple[str, Unpack[tuple[str, ...]]], data: DataLike | SubDictLike | None) → None

__setitem__(keywords: None | tuple[()], data: StandaloneDataLike) → None

__setitem__(keywords: slice, data: FileDictLike) → None

Set the value for a key.

If the key does not exist, it is added with the specified value.

If the key already exists, the first item is assigned the new value, and any other items with the same key are removed.

__contains__(keywords: object) → bool: Check if the FoamFile contains the given keyword or tuple of keywords.

get(keywords: str | tuple[str, Unpack[tuple[str, ...]]], default: _D = None, /) → Data | FoamFile.SubDict | None | _D
get(keywords: None | tuple[()], default: _D = None, /) → StandaloneData | _D

getone(keywords: str | tuple[str, Unpack[tuple[str, ...]]], /) → Data | FoamFile.SubDict | None

getone(keywords: None | tuple[()], /) → StandaloneData

Get the first value for a key.

Raises a KeyError if the key is not found and no default is provided.

getall(keywords: str | tuple[str, Unpack[tuple[str, ...]]], /) → Collection['Data | FoamFile.SubDict | None']

getall(keywords: None | tuple[()], /) → Collection[StandaloneData]

Get all values for a key.

Raises a KeyError if the key is not found and no default is provided.

add(keywords: str | tuple[str, Unpack[tuple[str, ...]]], data: DataLike | SubDictLike | None) → None
add(keywords: None | tuple[()], data: StandaloneDataLike) → None: Add a new value for a key.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

pop(key: _K, /) → _V: Same as popone.

popone(keywords: str | tuple[str, Unpack[tuple[str, ...]]], /) → Data | SubDict | None

popone(keywords: None | tuple[()], /) → StandaloneData

Remove and return the first value for a key.

Raises a KeyError if the key is not found.

popall(key: _K, /) → Collection[_V]

Remove and return all values for a key.

Raises a KeyError if the key is not found and no default is provided.

__len__() → int: Return the number of top-level keywords in the FoamFile (excluding the FoamFile header if present).

__iter__() → Iterator[str | None]: Iterate over the top-level keys in the FoamFile (excluding the FoamFile header if present).

keys(*, include_header: bool = False) → KeysView

Return a collection of the keywords in the FoamFile.

Parameters:: include_header – Whether to include the “FoamFile” header in the output.

values(*, include_header: bool = False) → ValuesView

Return a collection of the values in the FoamFile.

Parameters:: include_header – Whether to include the “FoamFile” header in the output.

items(*, include_header: bool = False) → ItemsView

Return a collection of the items (keyword-value pairs) in the FoamFile.

Parameters:: include_header – Whether to include the “FoamFile” header in the output.

clear(include_header: bool = False) → None

Remove all entries from the FoamFile.

Parameters:: include_header – Whether to also remove the “FoamFile” header.

Update the multi-mapping with items from another object.

This replaces existing values for keys found in the other object.

extend(other: SupportsKeysAndGetItem[str | None, str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], ...]]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], ...]]] | Mapping[str, DataLike | SubDictLike | None] | None] | Iterable[tuple[str | None, str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], ...]]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], ...]]] | Mapping[str, DataLike | SubDictLike | None] | None]] = (), /, **kwargs: str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], ...]]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | ndarray[tuple[int], dtype[int64 | int32 | float64]] | ndarray[tuple[int, Literal[3]], dtype[float64 | float32]] | list[ndarray[tuple[Literal[3, 4]], dtype[int64]]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | Sequence[int] | Sequence[float] | Sequence[ndarray[tuple[Literal[3]], dtype[floating]]] | Sequence[ndarray[tuple[Literal[3, 4]], dtype[integer]]] | Sequence[Sequence[int]], ...]]] | Mapping[str, DataLike | SubDictLike | None] | None) → None: Extend the multi-mapping with items from another object.

Merge another object into the multi-mapping.

Keys from other that already exist in the multi-mapping will not be replaced.

Return a nested dict representation of the file.

Parameters:: include_header – Whether to include the “FoamFile” header in the output.

__enter__() → Self: Read the file from disk if not already read, and defer writing of changes until the context is exited.

__exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) → None: If this is the outermost context, write any deferred file changes to disk.

Standalone deserializing function.

Deserialize the OpenFOAM FoamFile format to Python objects.

Parameters:

s – The string to deserialize. This can be a dictionary, list, or any other object that can be serialized to the OpenFOAM format.
include_header – Whether to include the “FoamFile” header in the output. If True, the header will be included if it is present in the input object.

Standalone serializing function.

Serialize Python objects to the OpenFOAM FoamFile format.

Parameters:

file – The Python object to serialize. This can be a dictionary, list, or any other object that can be serialized to the OpenFOAM format.
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 input object.

class SubDict(_file: FoamFile, _keywords: tuple[str, Unpack[tuple[str, ...]]])

Bases: MutableMultiMapping[str, Data | FoamFile.SubDict | None]

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"

SubDict.__getitem__(keyword: str) → Data | FoamFile.SubDict | None

Get the first value for a key.

Raises a KeyError if the key is not found.

Set the value for a key.

If the key does not exist, it is added with the specified value.

If the key already exists, the first item is assigned the new value, and any other items with the same key are removed.

SubDict.__contains__(keyword: object) → bool

SubDict.get(k[, d]) → D[k] if k in D, else d. d defaults to None.

SubDict.getone(key: _K, /) → _V

Get the first value for a key.

Raises a KeyError if the key is not found and no default is provided.

SubDict.getall(keyword: str, /) → Collection[Data | FoamFile.SubDict | None]

Get all values for a key.

Raises a KeyError if the key is not found and no default is provided.

SubDict.add(keyword: str, data: str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], ...]]] | Mapping[str, DataLike | SubDictLike | None] | None) → None: Add a new value for a key.

SubDict.setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

SubDict.pop(key: _K, /) → _V: Same as popone.

SubDict.popone(keyword: str, /) → Data | SubDict | None

Remove and return the first value for a key.

Raises a KeyError if the key is not found.

SubDict.popall(key: _K, /) → Collection[_V]

Remove and return all values for a key.

Raises a KeyError if the key is not found and no default is provided.

SubDict.__len__() → int: Return the total number of items (key-value pairs).

SubDict.__iter__() → Iterator[str]

Return an iterator over the keys.

Keys with multiple values will be yielded multiple times.

SubDict.keys() → KeysView: Return a view of the keys in the MultiMapping.

SubDict.values() → ValuesView: Return a view of the values in the MultiMapping.

SubDict.items() → ItemsView: Return a view of the items (key-value pairs) in the MultiMapping.

SubDict.clear() → None: Remove all items from the multi-mapping.

Update the multi-mapping with items from another object.

This replaces existing values for keys found in the other object.

SubDict.extend(other: SupportsKeysAndGetItem[str, str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], ...]]] | Mapping[str, DataLike | SubDictLike | None] | None] | Iterable[tuple[str, str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], ...]]] | Mapping[str, DataLike | SubDictLike | None] | None]] = (), /, **kwargs: str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]] | tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], Unpack[tuple[str | int | float | bool | Dimensioned | DimensionSet | list[DataEntry | KeywordEntry | Dict] | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]] | Integral | Real | Sequence[int | float] | Sequence[DataEntryLike | KeywordEntryLike | DictLike] | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]] | Sequence[float | ndarray[tuple[Literal[3, 6, 9]], dtype[float64]] | Real | Sequence[float | Real] | ndarray[tuple[Literal[3, 6, 9]], dtype[floating | integer]]], ...]]] | Mapping[str, DataLike | SubDictLike | None] | None) → None: Extend the multi-mapping with items from another object.

Merge another object into the multi-mapping.

Keys from other that already exist in the multi-mapping will not be replaced.

SubDict.as_dict() → dict[str, Data | SubDict | None] | MultiDict[str, Data | SubDict | None]: Return a nested dict representation of the sub-dictionary.

class foamlib.FoamFile.Dimensioned

Alias of Dimensioned provided for backward compatibility.

Prefer using foamlib.Dimensioned directly.

class foamlib.FoamFile.DimensionSet

Alias of DimensionSet provided for backward compatibility.

Prefer using foamlib.DimensionSet directly.

class foamlib.FoamFieldFile(path: PathLike[str] | str)

Bases: FoamFile

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.

Parameters:: 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]

property internal_field: float | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]]: Alias of self["internalField"].

property boundary_field: BoundariesSubDict: Alias of self["boundaryField"].

property dimensions: DimensionSet: Alias of self["dimensions"].

class BoundariesSubDict(_file: FoamFile, _keywords: tuple[str, Unpack[tuple[str, ...]]]): Bases: SubDict

class BoundarySubDict(_file: FoamFile, _keywords: tuple[str, Unpack[tuple[str, ...]]])

Bases: SubDict

An OpenFOAM dictionary representing a boundary condition as a mutable mapping.

property BoundarySubDict.value: float | ndarray[tuple[int] | tuple[int, Literal[3, 6, 9]], dtype[floating]]: Alias of self["value"].

property BoundarySubDict.type: str: Alias of self["type"].

Additional classes

class foamlib.Dimensioned(value: TensorLike, dimensions: DimensionSetLike, name: str | None = None)

A numerical value with associated physical dimensions.

Corresponds to the dimensioned<…> type in OpenFOAM.

The value can be a single number (scalar) or a 1D array (vector or tensor).

Parameters:

value – The numerical value.
dimensions – The physical dimensions as a DimensionSet or a sequence of up to 7 numbers.
name – An optional name for the dimensioned quantity.

Set of physical dimensions represented as powers of base SI units.

Corresponds to the dimensionSet type in OpenFOAM.

Parameters:

mass – Power of the mass dimension.
length – Power of the length dimension.
time – Power of the time dimension.
temperature – Power of the temperature dimension.
moles – Power of the amount of substance dimension.
current – Power of the electric current dimension.
luminous_intensity – Power of the luminous intensity dimension.

Exceptions

class foamlib.FoamFileDecodeError(contents: bytes | bytearray, pos: int, *, expected: str): Error raised when a FoamFile cannot be parsed.