Documentation for foamlib

A Python interface for interacting with OpenFOAM.

class foamlib.AsyncFoamCase(path: Path | str = PosixPath('.'))

Bases: FoamCaseBase

An OpenFOAM case with asynchronous support.

Provides methods for running and cleaning cases, as well as accessing files.

Access the time directories of the case as a sequence, e.g. case[0] or case[-1].

Parameters:

path – The path to the case directory.

async block_mesh(*, check: bool = True) → None

Run blockMesh on this case.

async clean(*, script: bool = True, check: bool = False) → None

Clean this case.

Parameters:

  • script – If True, use an (All)clean script if it exists. If False, ignore any clean scripts.

  • check – If True, raise a CalledProcessError if the clean script returns a non-zero exit code.

async clone(dest: Path | str) → AsyncFoamCase

Clone this case (make a clean copy).

Parameters:

dest – The destination path.

async copy(dest: Path | str) → AsyncFoamCase

Make a copy of this case.

Parameters:

dest – The destination path.

async decompose_par(*, check: bool = True) → None

Decompose this case for parallel running.

max_cpus = 2

Maximum number of CPUs to use for running `AsyncFoamCase`s concurrently. Defaults to the number of CPUs on the system.

async reconstruct_par(*, check: bool = True) → None

Reconstruct this case after parallel running.

async run(cmd: Sequence[str | Path] | str | Path | None = None, *, script: bool = True, parallel: bool | None = None, cpus: int | None = None, check: bool = True) → None

Run this case, or a specified command in the context of this case.

Parameters:

  • 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.

  • script – If True and cmd is None, use an (All)run(-parallel) script if it exists for running the case. If False or no run script is found, autodetermine the command(s) needed to run the case.

  • parallel – If True, run in parallel using MPI. If None, autodetect whether to run in parallel.

  • cpus – The number of CPUs to reserve for the run. The run will wait until the requested number of CPUs is available. If None, autodetect the number of CPUs to reserve.

  • check – If True, raise a CalledProcessError if a command returns a non-zero exit code.

exception foamlib.CalledProcessError(returncode, cmd, output=None, stderr=None)

Bases: CalledProcessError

Exception raised when a process fails and check=True.

exception foamlib.CalledProcessWarning

Bases: Warning

Warning raised when a process prints to stderr and check=True.

class foamlib.FoamCase(path: Path | str = PosixPath('.'))

Bases: FoamCaseBase

An OpenFOAM case.

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].

Parameters:

path – The path to the case directory.

block_mesh(*, check: bool = True) → None

Run blockMesh on this case.

clean(*, script: bool = True, check: bool = False) → None

Clean this case.

Parameters:

  • script – If True, use an (All)clean script if it exists. If False, ignore any clean scripts.

  • check – If True, raise a CalledProcessError if the clean script returns a non-zero exit code.

clone(dest: Path | str) → FoamCase

Clone this case (make a clean copy).

Parameters:

dest – The destination path.

copy(dest: Path | str) → FoamCase

Make a copy of this case.

Parameters:

dest – The destination path.

decompose_par(*, check: bool = True) → None

Decompose this case for parallel running.

reconstruct_par(*, check: bool = True) → None

Reconstruct this case after parallel running.

run(cmd: Sequence[str | Path] | str | Path | None = None, *, script: bool = True, parallel: bool | None = None, check: bool = True) → None

Run this case, or a specified command in the context of this case.

Parameters:

  • 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.

  • script – If True and cmd is None, use an (All)run(-parallel) script if it exists for running the case. If False or no run script is found, autodetermine the command(s) needed to run the case.

  • parallel – If True, run in parallel using MPI. If None, autodetect whether to run in parallel.

  • check – If True, raise a CalledProcessError if any command returns a non-zero exit code.

class foamlib.FoamCaseBase(path: Path | str = PosixPath('.'))

Bases: Sequence[FoamCaseBase.TimeDirectory]

class TimeDirectory(path: Path | str)

Bases: Set[FoamFieldFile]

An OpenFOAM time directory in a case.

Use to access field files in the directory, e.g. time[“U”].

Parameters:

path – The path to the time directory.

property name: str

The name of this time directory.

property time: float

The time that corresponds to this directory.

property application: str

The application name as set in the controlDict.

property block_mesh_dict: FoamFile

The blockMeshDict file.

property control_dict: FoamFile

The controlDict file.

property decompose_par_dict: FoamFile

The decomposeParDict file.

file(path: Path | str) → FoamFile

Return a FoamFile object for the given path in the case.

property fv_schemes: FoamFile

The fvSchemes file.

property fv_solution: FoamFile

The fvSolution file.

property name: str

The name of the case.

property transport_properties: FoamFile

The transportProperties file.

property turbulence_properties: FoamFile

The turbulenceProperties file.

class foamlib.FoamDict

Bases: object

Data

A value that can be stored in an OpenFOAM dictionary.

alias of str | int | float | bool | Dimensioned | DimensionSet | Sequence[Data] | Mapping[str, Data]

class DimensionSet(mass, length, time, temperature, moles, current, luminous_intensity)

Bases: NamedTuple

current: int | float

Alias for field number 5

length: int | float

Alias for field number 1

luminous_intensity: int | float

Alias for field number 6

mass: int | float

Alias for field number 0

moles: int | float

Alias for field number 4

temperature: int | float

Alias for field number 3

time: int | float

Alias for field number 2

class Dimensioned(value: int | float | collections.abc.Sequence[int | float] = 0, dimensions: Union[ForwardRef('FoamDict.DimensionSet'), collections.abc.Sequence[Union[int, float]]] = (), name: str | None = None)

Bases: object

dimensions: DimensionSet | Sequence[int | float] = ()
name: str | None = None
value: int | float | Sequence[int | float] = 0
abstract as_dict() → Dict[str, Data | _Dict]

Return a nested dict representation of the dictionary.

class foamlib.FoamFieldFile(path: str | Path)

Bases: FoamFile

An OpenFOAM dictionary file representing a field as a mutable mapping.

class BoundariesSubDict(_file: FoamFile, _keywords: Tuple[str, ...])

Bases: SubDict

class BoundarySubDict(_file: FoamFile, _keywords: Tuple[str, ...])

Bases: SubDict

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

property type: str

Alias of self[“type”].

property value: int | float | Sequence[int | float | Sequence[int | float]] | ndarray[Tuple, dtype[generic]] | ndarray[Tuple[int], dtype[generic]] | ndarray[Tuple[int, int], dtype[generic]]

Alias of self[“value”].

property boundary_field: BoundariesSubDict

Alias of self[“boundaryField”].

property dimensions: DimensionSet | Sequence[int | float]

Alias of self[“dimensions”].

property internal_field: int | float | Sequence[int | float | Sequence[int | float]] | ndarray[Tuple, dtype[generic]] | ndarray[Tuple[int], dtype[generic]] | ndarray[Tuple[int, int], dtype[generic]]

Alias of self[“internalField”].

class foamlib.FoamFile(path: str | Path)

Bases: FoamDict, MutableMapping[str | Tuple[str, …], FoamFile.Data | FoamFile.SubDict], FoamFileIO

An OpenFOAM dictionary file.

Use as a mutable mapping (i.e., like a dict) to access and modify entries.

Use as a context manager to make multiple changes to the file while saving all changes only once at the end.

class SubDict(_file: FoamFile, _keywords: Tuple[str, ...])

Bases: FoamDict, MutableMapping[str, FoamFile.Data | FoamFile.SubDict]

An OpenFOAM dictionary within a file as a mutable mapping.

as_dict() → Dict[str, Data | _Dict]

Return a nested dict representation of the dictionary.

clear() → None.  Remove all items from D.
update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

as_dict() → Dict[str, Data | _Dict]

Return a nested dict representation of the file.

clear() → None.  Remove all items from D.
update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

Indices and tables