foamlib

https://foamlib.readthedocs.io/en/stable/
Admin
foamlib is a modern Python package that simplifies working with OpenFOAM input/output data by...
Tokens:29,514
Snippets:174
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install foamlib preprocessing dependencies

Source: https://foamlib.readthedocs.io/en/stable/_sources/parametricstudy.rst.txt

Command to install the necessary extra dependencies for the preprocessing module.

```bash
pip install foamlib[preprocessing]
```

--------------------------------

### Install foamlib Post-processing Dependencies

Source: https://foamlib.readthedocs.io/en/stable/postprocessing.html

Install the necessary dependencies for the foamlib.postprocessing module using pip. This command ensures all required packages are available for post-processing functionalities.

```bash
pip install foamlib[postprocessing]

```

--------------------------------

### List and Load Output Files with foamlib

Source: https://foamlib.readthedocs.io/en/stable/postprocessing.html

List all output files within a directory and load specific data into a DataFrame. This example shows how to use list_outputfiles to find 'forces--force.dat' and then load_tables to process this data from the specified directory.

```python
out_files = list_outputfiles(root / "Cases")

forces = load_tables(
    source=out_files["forces--force.dat"],
    dir_name=root / "Cases"
)


```

--------------------------------

### Define OpenFOAM simulation parameters dictionary

Source: https://foamlib.readthedocs.io/en/stable/_sources/parametricstudy.rst.txt

Example of a custom OpenFOAM dictionary file used to store parameters for the study.

```c++
/*--------------------------------*- C++ -*----------------------------------*\
| =========                 |                                                 |
| \      /  F ield         | OpenFOAM: The Open Source CFD Toolbox           |
|  \    /   O peration     | Version:  plus                                  |
|   \  /    A nd           | Web:      www.OpenFOAM.com                      |
|    \/     M anipulation  |                                                 |
\*---------------------------------------------------------------------------*/
FoamFile
{
    version     2.0;
    format      ascii;
    class       dictionary;
    location    "system";
    object      simulationParameters;
}
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

NX 23;
NY 8;

someModel SomeModelName;


// ************************************************************************* //
```

--------------------------------

### Load Time Series Data with foamlib

Source: https://foamlib.readthedocs.io/en/stable/postprocessing.html

Load time series data from OpenFOAM post-processing files into a pandas DataFrame. This example demonstrates loading 'force.dat' files from multiple cases and saving the combined data to a CSV. The resulting DataFrame includes case name, time, and force components.

```python
from foamlib.postprocessing.load_tables import OutputFile, list_outputfiles, load_tables

forces = load_tables(
    source=OutputFile(file_name="force.dat", folder="forces"), dir_name="Cases"
)
forces.to_csv(
    results / "forces.csv",
    index=False,
)


```

--------------------------------

### SubDict Key-Value Operations

Source: https://foamlib.readthedocs.io/en/stable/files.html

Methods for managing key-value pairs within a SubDict, including setting, getting, adding, and removing items.

```APIDOC
## SubDict Operations

### Description
Provides methods for managing key-value pairs in a multi-value dictionary.

### Methods

#### `__contains__(_keyword : object_) → bool`
Checks if a key exists in the SubDict.

#### `get(_k_[, _d_]) → D[k] if k in D, else d. d defaults to None.`
Retrieves the value for a key. Returns a default value if the key is not found.

#### `getone(_key : _K_, _/_) → _V`
Gets the first value associated with a key. Raises KeyError if the key is not found and no default is provided.

#### `getall(_keyword : str_, _/_) → Collection[Data | FoamFile.SubDict | None]`
Retrieves all values associated with a key. Raises KeyError if the key is not found.

#### `add(_keyword : str_, _data : ...)`
Adds a new value for a specified key. The `data` parameter can accept various types including strings, numbers, lists, and more complex structures.

#### `setdefault(_k_[, _d_]) → D.get(k,d), also set D[k]=d if k not in D`
Gets the value for a key, or sets it to a default value if the key does not exist, and returns the value.

#### `pop(_key : _K_, _/_) → _V`
Removes and returns the first value associated with a key. Equivalent to `popone`.

#### `popone(_keyword : str_, _/_) → Data | SubDict | None`
Removes and returns the first value for a key. Raises KeyError if the key is not found.

#### `popall(_key : _K_, _/_) → Collection[_V]`
Removes and returns all values associated with a key. Raises KeyError if the key is not found.

#### `__len__() → int`
Returns the total number of items (key-value pairs) in the SubDict.

#### `__iter__() → Iterator[str]`
Returns an iterator over the keys. Keys with multiple values will be yielded multiple times.

#### `keys() → KeysView`
Returns a view of the keys in the SubDict.

#### `values() → ValuesView`
Returns a view of the values in the SubDict.

#### `items() → ItemsView`
Returns a view of the items (key-value pairs) in the SubDict.

#### `clear() → None`
Removes all items from the SubDict.
```

--------------------------------

### Context Management (__enter__ / __exit__)

Source: https://foamlib.readthedocs.io/en/stable/files.html

Methods for managing file read/write operations using context managers to defer disk writes.

```APIDOC
## __enter__()

### Description
Reads the file from disk if it has not been read yet and sets up the context to defer writing changes until the context is exited.

## __exit__(exc_type, exc_val, exc_tb)

### Description
If this is the outermost context, it commits any deferred file changes to the disk.

### Parameters
- **exc_type** (type[BaseException] | None) - Optional - The exception type if an error occurred.
- **exc_val** (BaseException | None) - Optional - The exception value.
- **exc_tb** (TracebackType | None) - Optional - The traceback object.
```

--------------------------------

### Load and manipulate an OpenFOAM case

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Demonstrates loading a case, modifying a field, running the solver, and iterating through time directories.

```python
from foamlib import FoamCase

case = FoamCase("path/to/case") # Load an OpenFOAM case
case[0]["U"].internal_field = [0, 0, 0] # Set the initial velocity field to zero
case.run() # Run the case
for time in case: # Iterate over the time directories
    print(time.time) # Print the time
    print(time["U"].internal_field) # Print the velocity field
```

--------------------------------

### Load Time Series Data

Source: https://foamlib.readthedocs.io/en/stable/_sources/postprocessing.rst.txt

Loads time-series data from specified output files within OpenFOAM cases and saves it to a CSV. Requires 'foamlib[postprocessing]' installation.

```python
from foamlib.postprocessing.load_tables import OutputFile, list_outputfiles, load_tables

forces = load_tables(
    source=OutputFile(file_name="force.dat", folder="forces"), dir_name="Cases"
)
forces.to_csv(
    results / "forces.csv",
    index=False,
)
```

--------------------------------

### FoamDictInstruction for fvSolution

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Returns a FoamDictInstruction object for modifying the fvSolution file. Use this to configure solver settings and convergence criteria.

```python
foamlib.preprocessing.system.fv_solution(_keys : list[str]_) -> FoamDictInstruction
```

--------------------------------

### Load and Filter Spatial Data

Source: https://foamlib.readthedocs.io/en/stable/_sources/postprocessing.rst.txt

Loads spatial data (e.g., surface data) from OpenFOAM cases and applies a custom filter to process the data. The example filters for maximum height.

```python
from foamlib.postprocessing.load_tables import OutputFile, load_tables

def max_height_filter(table: pd.DataFrame, parameters: dict[str, str]) -> pd.DataFrame:
    """Filter the table to get the maximum height."""
    d = {
        "x": [table["x"].max()],
        "y": [table["y"].max()],
        "z": [table["z"].max()],
    }
    d.update(parameters)
    return pd.DataFrame(d)


file = OutputFile(file_name="U_freeSurface.raw", folder="freeSurface")
surface_heights = load_tables(
    source=file, dir_name=root / "Cases", filter_table=max_height_filter
)
surface_heights.to_csv(
    results / "surface_heights.csv",
    index=False,
)
```

--------------------------------

### AsyncFoamCase.run

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Executes an OpenFOAM case or a specific command within the case context.

```APIDOC
## async run(cmd, *, parallel, cpus, check, log)

### Description
Runs the OpenFOAM case or a specified command. If no command is provided, it follows heuristic rules to execute scripts like Allrun or blockMesh.

### Parameters
#### Request Body
- **cmd** (Sequence[str | PathLike[str]] | str | None) - Optional - The command to run. If None, runs the case.
- **parallel** (bool | None) - Optional - If True, run in parallel using MPI.
- **cpus** (int | None) - Optional - Number of CPUs to use.
- **check** (bool) - Optional - If True, raise CalledProcessError on non-zero exit.
- **log** (bool | str | PathLike[str]) - Optional - Log output to files.
```

--------------------------------

### FoamFile Class Initialization

Source: https://foamlib.readthedocs.io/en/stable/files.html

Initializes a new FoamFile instance to interact with an OpenFOAM file.

```APIDOC
## FoamFile(path)

### Description
Initializes an OpenFOAM data file object. If the file does not exist, it is created upon the first modification.

### Parameters
#### Path Parameters
- **path** (str | PathLike) - Required - The filesystem path to the OpenFOAM file.

### Request Example
from foamlib import FoamFile
file = FoamFile("path/to/case/system/controlDict")
```

--------------------------------

### Convenience Functions for FoamDictInstruction

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Reference for convenience functions available in `foamlib.preprocessing.system` for creating `FoamDictInstruction` objects.

```APIDOC
## Convenience Functions for FoamDictInstruction

### Description
This section lists the convenience functions provided by the `foamlib.preprocessing.system` module to easily create `FoamDictInstruction` objects for common OpenFOAM dictionary files.

### Functions

#### `controlDict(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Alias for `control_dict()`. Returns the `FoamDictInstruction` for `controlDict`.
- **Deprecated**: Since version 1.3.0. Use `control_dict()` instead.

#### `control_dict(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Returns the `FoamDictInstruction` for `controlDict`.

#### `fvSchemes(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Alias for `fv_schemes()`. Returns the `FoamDictInstruction` for `fvSchemes`.
- **Deprecated**: Since version 1.3.0. Use `fv_schemes()` instead.

#### `fv_schemes(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Returns the `FoamDictInstruction` for `fvSchemes`.

#### `fvSolution(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Alias for `fv_solution()`. Returns the `FoamDictInstruction` for `fvSolution`.
- **Deprecated**: Since version 1.3.0. Use `fv_solution()` instead.

#### `fv_solution(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Returns the `FoamDictInstruction` for `fvSolution`.

#### `simulationParameters(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Alias for `simulation_parameters()`. Returns the `FoamDictInstruction` for `simulationParameters`.
- **Deprecated**: Since version 1.3.0. Use `simulation_parameters()` instead.

#### `simulation_parameters(_keys: list[str]) -> FoamDictInstruction`
- **Description**: Returns the `FoamDictInstruction` for `simulationParameters`.

### Parameters
- **_keys** (list[str]): A list of keys within the target dictionary to be modified.
```

--------------------------------

### run(cmd, parallel, cpus, check, log)

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Runs the OpenFOAM case or a specified command.

```APIDOC
## run(cmd, parallel, cpus, check, log)

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

### Parameters
#### Query Parameters
- **cmd** (Sequence[str | PathLike[str]] | str) - Optional - The command to run. If None, run the case.
- **parallel** (bool) - Optional - If True, run in parallel using MPI. If None, autodetect.
- **cpus** (int) - Optional - The number of CPUs to use.
- **check** (bool) - Optional - If True, raise a CalledProcessError if any command returns a non-zero exit code.
- **log** (bool | str | PathLike[str]) - Optional - If True, log the command output to log.* files.
```

--------------------------------

### Access and modify OpenFOAM files

Source: https://foamlib.readthedocs.io/en/stable/files.html

Demonstrates direct file manipulation using the FoamFile class and the recommended context manager approach for safer updates.

```python
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
```

```python
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"
```

--------------------------------

### AsyncSlurmFoamCase.run

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Runs an OpenFOAM case on a Slurm cluster.

```APIDOC
## async run(cmd, *, parallel, cpus, check, log, fallback)

### Description
Subclass of AsyncFoamCase that launches jobs on a Slurm cluster using salloc and srun.

### Parameters
#### Request Body
- **cmd** (Sequence[str | PathLike[str]] | str | None) - Optional - Command to run.
- **parallel** (bool | None) - Optional - Run in parallel using MPI.
- **cpus** (int | None) - Optional - Number of CPUs to use. If 0, run locally.
- **check** (bool) - Optional - Raise error on non-zero exit.
- **log** (bool | str | PathLike[str]) - Optional - Log output to file.
- **fallback** (bool) - Optional - Fall back to local execution if Slurm is unavailable.
```

--------------------------------

### Clone an OpenFOAM case

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Demonstrates creating a clean copy of an existing case using the clone method.

```python
import os
from pathlib import Path
from foamlib import AsyncFoamCase

pitz_tutorial = AsyncFoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")

my_pitz = await pitz_tutorial.clone("myPitz")
```

--------------------------------

### Copy an OpenFOAM case

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Demonstrates creating a copy of an existing case using the copy method.

```python
import os
from pathlib import Path
from foamlib import AsyncFoamCase

pitz_tutorial = AsyncFoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")

my_pitz = await pitz_tutorial.copy("myPitz")
```

--------------------------------

### Run concurrent optimization tasks

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Demonstrates using an async objective function with case cloning for parallel optimization workflows.

```python
import os
from pathlib import Path
from foamlib import AsyncSlurmFoamCase
from scipy.optimize import differential_evolution

# Set up base case for optimization
base = AsyncSlurmFoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")

async def objective_function(x):
    async with base.clone() as case:
        # Set inlet velocity based on optimization parameters
        case[0]["U"].boundary_field["inlet"].value = [x[0], 0, 0]

        # Run with fallback to local execution if Slurm unavailable
        await case.run(fallback=True)

        # Return objective (minimize velocity magnitude at outlet)
        return abs(case[-1]["U"].internal_field[0][0])
```

--------------------------------

### Run a scalar transport diffusion check

Source: https://foamlib.readthedocs.io/en/stable/example.html

This script initializes a OpenFOAM case, configures solver settings, defines mesh and boundary conditions, runs the simulation, and validates the results against an analytical solution.

```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 foamlib import Dimensioned, DimensionSet, FoamCase
from scipy.special import erfc

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"] = Dimensioned(1e-3, DimensionSet(length=2, time=-1), "DT")

with case[0]["U"] as f:
    f.dimensions = 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 = 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()

internal_field = case[0].cell_centers().internal_field
assert isinstance(internal_field, np.ndarray)
x, y, z = internal_field.T

end = x == x.max()
x = x[end]
y = y[end]
z = z[end]

DT = case.transport_properties["DT"].value  # ty: ignore[possibly-missing-attribute]
internal_field = case[0]["T"].internal_field
assert isinstance(internal_field, np.ndarray)
U = internal_field[0]

for time in case[1:]:
    if U * time.time < 2 * x.max():
        continue

    internal_field = time["T"].internal_field
    assert isinstance(internal_field, np.ndarray)
    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:
        msg = f"Time {time.time}: {T} != {analytical}"
        raise RuntimeError(msg)
```

--------------------------------

### foamlib.typing Module Overview

Source: https://foamlib.readthedocs.io/en/stable/typing.html

Overview of the standard and accepted types available in the foamlib.typing module.

```APIDOC
## foamlib.typing

### Description
The typing module defines the core data structures and type aliases used throughout foamlib to ensure consistent data handling.

### Standard Types
- **SubDict**
- **Data**
- **StandaloneData**
- **DataEntry**
- **StandaloneDataEntry**
- **Dict**
- **KeywordEntry**
- **List**
- **Field**
- **Tensor**

### Other Accepted Types (Like Types)
- **SubDictLike**
- **DataLike**
- **StandaloneDataLike**
- **DataEntryLike**
- **StandaloneDataEntryLike**
- **DictLike**
- **KeywordEntryLike**
- **ListLike**
- **FieldLike**
- **TensorLike**
- **DimensionSetLike**
```

--------------------------------

### Initialize CSV Generator for Parametric Study

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Import the csv_generator from the foamlib.preprocessing.parameter_study module to create parametric studies based on CSV files. This is the entry point for CSV-driven case generation.

```python
from foamlib.preprocessing.parameter_study import csv_generator
```

--------------------------------

### AsyncFoamCase.run_all

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Runs multiple OpenFOAM cases or awaitables concurrently.

```APIDOC
## async static run_all(cases)

### Description
Executes multiple cases concurrently, with parallelism limited by the max_cpus attribute.

### Parameters
#### Request Body
- **cases** (Iterable[AsyncFoamCase | Awaitable[object]]) - Required - Instances of AsyncFoamCase or awaitables.
```

--------------------------------

### Define Grid Parameters with FoamLib

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Use CaseParameter and GridParameter from foamlib.preprocessing to define and manage grid parameters for case generation. FoamDictInstruction specifies which files and keys to modify.

```python
from foamlib.preprocessing.grid_parameter_sweep import CaseParameter, GridParameter
from foamlib.preprocessing.of_dict import FoamDictInstruction
```

--------------------------------

### FoamCase and AsyncFoamCase Execution

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Methods for running, cleaning, and managing OpenFOAM cases synchronously and asynchronously.

```APIDOC
## FoamCase / AsyncFoamCase Execution

### Description
Classes for executing OpenFOAM simulations. AsyncFoamCase provides additional asynchronous capabilities for parallel execution.

### Methods
- **block_mesh()** - Run blockMesh
- **clean()** - Clean case directory
- **clone()** - Clone the case
- **copy()** - Copy the case
- **decompose_par()** - Run decomposePar
- **reconstruct_par()** - Run reconstructPar
- **restore_0_dir()** - Restore the 0 directory
- **run()** - Execute the simulation

### AsyncFoamCase Specific Methods
- **map()** - Map fields
- **run_all()** - Run all cases in a batch
- **max_cpus** (int) - Configuration for parallel execution
```

--------------------------------

### FoamFile Methods (G, I, K, L, M, P, S, U, V)

Source: https://foamlib.readthedocs.io/en/stable/genindex.html

This section details various methods available for FoamFile objects, including retrieval, manipulation, and management of file contents and properties.

```APIDOC
## FoamFile Methods

### get()

- **Description**: Retrieves a value from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### getall()

- **Description**: Retrieves all values from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### getone()

- **Description**: Retrieves a single value from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### items()

- **Description**: Returns an iterable of key-value pairs from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### keys()

- **Description**: Returns an iterable of keys from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### loads()

- **Description**: Loads data into a FoamFile object from a string.
- **Method**: static
- **Endpoint**: N/A (Static method)

### merge()

- **Description**: Merges another FoamFile object into the current one.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### pop()

- **Description**: Removes and returns a value associated with a key from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### popall()

- **Description**: Removes and returns all values from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### popone()

- **Description**: Removes and returns a single value from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### setdefault()

- **Description**: Sets a default value for a key if it does not exist in the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### update()

- **Description**: Updates the FoamFile with key-value pairs from another dictionary or iterable.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

### values()

- **Description**: Returns an iterable of values from the FoamFile.
- **Method**: (Implicitly called by accessing properties or methods)
- **Endpoint**: N/A (Method within an object)

```

--------------------------------

### System Module Functions (S)

Source: https://foamlib.readthedocs.io/en/stable/genindex.html

This section details functions available in the foamlib.preprocessing.system module.

```APIDOC
## foamlib.preprocessing.system Functions

### simulation_parameters()

- **Description**: Retrieves simulation parameters.
- **Method**: (Implicitly called)
- **Endpoint**: N/A (Function within a module)

### simulationParameters()

- **Description**: Retrieves simulation parameters (alternative naming).
- **Method**: (Implicitly called)
- **Endpoint**: N/A (Function within a module)

```

--------------------------------

### FoamCase, AsyncFoamCase, and AsyncSlurmFoamCase

Source: https://foamlib.readthedocs.io/en/stable/_sources/cases.rst.txt

Information on the main FoamCase classes for synchronous and asynchronous case management.

```APIDOC
## FoamCase Class

### Description
Represents a synchronous interface for managing FoamLib simulation cases.

### Members
(Details of members are not specified in the provided text, but it inherits from FoamCaseBase and has additional members.)

## AsyncFoamCase Class

### Description
Represents an asynchronous interface for managing FoamLib simulation cases.

### Members
(Details of members are not specified in the provided text, but it inherits from FoamCaseBase and has additional members.)

## AsyncSlurmFoamCase Class

### Description
Represents an asynchronous interface for managing FoamLib simulation cases specifically for Slurm environments.

### Members
(Details of members are not specified in the provided text, but it inherits from FoamCaseBase and has additional members.)
```

--------------------------------

### Grid Parameter Definition and Study Generation

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

This section demonstrates how to define grid parameters and generate a study with multiple simulation cases by varying these parameters.

```APIDOC
## Grid Parameter Definition and Study Generation

### Description
This code defines two `GridParameter` objects: `grid` for varying grid resolution and `init_height` for varying initial height. It then uses the `grid_generator` function to create a study that generates multiple simulation cases by combining these parameters. The `create_study` method is called to finalize the case generation.

### Parameters
- **grid**: A `GridParameter` object defining grid resolution variations.
  - `parameters`:
    - `name`: "coarse", `values`: [23, 8, 19, 42, 4]
    - `name`: "mid", `values`: [46, 16, 38, 84, 8]
    - `name`: "fine", `values`: [92, 32, 76, 168, 16]
- **init_height**: A `GridParameter` object defining initial height variations.
  - `parameters`:
    - `name`: "height_02", `values`: [0.2]
    - `name`: "height_03", `values`: [0.3]
    - `name`: "height_04", `values`: [0.4]

### Study Generation
- **grid_generator**: Function to create a study from a list of `GridParameter` objects.
  - `parameters`:
    - `parameters` (list): List of `GridParameter` objects.
    - `template_case` (Path): Path to the template case.
    - `output_folder` (Path): Folder to store the generated cases.

### Study Creation
- **study.create_study**: Method to create the study cases.
  - `study_base_folder` (Path): Base folder for the study.

### Request Example
```python
from pathlib import Path
from foamlib.preprocessing.grid_parameter_sweep import GridParameter, grid_generator
from foamlib.preprocessing.foam_dict_instruction import FoamDictInstruction

def grid_parameters(scale) -> list[int]:
    return [
        int(23 * scale),
        int(8 * scale),
        int(19 * scale),
        int(42 * scale),
        int(4 * scale),
    ]

grid = GridParameter(
    parameter_name="grid",
    modify_dict=[
        FoamDictInstruction(
            file_name=Path("system/simulationParameters"),
            keys=[f"res{i}"],
        )
        for i in range(1, 6)
    ],
    parameters=[
        CaseParameter(name="coarse", values=grid_parameters(1)),
        CaseParameter(name="mid", values=grid_parameters(2)),
        CaseParameter(name="fine", values=grid_parameters(4))
    ]
)

init_height = GridParameter(
    parameter_name="initHeight",
    modify_dict=[
        FoamDictInstruction(
            file_name=Path("system/simulationParameters"),
            keys=["initHeight"],
        )
    ],
    parameters=[
        CaseParameter(name="height_02", values=[0.2]),
        CaseParameter(name="height_03", values=[0.3]),
        CaseParameter(name="height_04", values=[0.4])
    ],
)

template_case = Path("path/to/template/case") # Replace with actual path
root = Path("output/directory") # Replace with actual path

study = grid_generator(
    parameters=[grid, init_height],
    template_case=template_case,
    output_folder=root / "Cases",
)

study.create_study(study_base_folder=root)
```

### Response
This process generates multiple simulation cases in the specified output folder, with each case named according to the parameters used. No direct API response is returned, but the file system is updated.
```

--------------------------------

### Include simulation parameters in OpenFOAM dictionary

Source: https://foamlib.readthedocs.io/en/stable/_sources/parametricstudy.rst.txt

Syntax for including the parameter file and referencing variables within an OpenFOAM dictionary.

```c++
#include "system/simulationParameters"

blocks
(
    hex (0 1 2 3 4 5 6 7) ($NX $NY 1) simpleGrading (1 1 1)
);
```

--------------------------------

### FoamDictInstruction for simulationParameters

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Returns a FoamDictInstruction object for modifying the simulationParameters dictionary. This is typically used for setting simulation-specific parameters.

```python
foamlib.preprocessing.system.simulation_parameters(_keys : list[str]_) -> FoamDictInstruction
```

--------------------------------

### FoamDictInstruction for fvSchemes

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Returns a FoamDictInstruction object for modifying the fvSchemes file. This is useful for specifying solver schemes and discretization methods.

```python
foamlib.preprocessing.system.fv_schemes(_keys : list[str]_) -> FoamDictInstruction
```

--------------------------------

### FoamDictInstruction for controlDict

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Returns a FoamDictInstruction object specifically for modifying the controlDict file. Use this function when you need to specify keys within controlDict.

```python
foamlib.preprocessing.system.control_dict(_keys : list[str]_) -> FoamDictInstruction
```

--------------------------------

### clone(dst)

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Clones the current OpenFOAM case to a new directory.

```APIDOC
## clone(dst)

### Description
Clone this case (make a clean copy). This is equivalent to running self.copy().clean(), but it can be more efficient in cases that do not contain custom clean scripts.

### Parameters
#### Path Parameters
- **dst** (PathLike[str] | str) - Optional - The destination path. If None, clone to a new directory in $FOAM_RUN/foamlib.

### Returns
- **Self** - The clone of the case.
```

--------------------------------

### static loads()

Source: https://foamlib.readthedocs.io/en/stable/files.html

Parses a string or byte input into a nested dictionary representation of the file content.

```APIDOC
## static loads()

### Description
Parses the provided input (bytes, bytearray, or string) and returns a nested dictionary representation of the file.

### Parameters
#### Query Parameters
- **s** (bytes | bytearray | str) - Required - The input data to be parsed.
- **include_header** (bool) - Optional - Whether to include the “FoamFile” header in the output. Defaults to False.

### Response
#### Success Response (200)
- **dict** (dict) - A nested dictionary or MultiDict representation of the parsed file data.
```

--------------------------------

### TimeDirectory Class

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Represents a time directory in an OpenFOAM case.

```APIDOC
## class TimeDirectory

### Description
A time directory in an OpenFOAM case. Used to access field files in the directory.

### Properties
- **name** (str) - The name of this time directory.
- **time** (float) - The time that corresponds to this directory.

### Methods
- **cell_centers()** - Write and return the cell centers.
```

--------------------------------

### FoamCase Class

Source: https://foamlib.readthedocs.io/en/stable/cases.html

An OpenFOAM case with synchronous execution capabilities.

```APIDOC
## class foamlib.FoamCase

### Description
Extends FoamCaseBase to provide methods for running and cleaning cases, as well as accessing files.

### Methods
- **block_mesh(check: bool = True, log: bool | str | PathLike[str] = True)** - Run blockMesh on this case.
- **clean(check: bool = False)** - Clean this case by removing time directories and temporary files.
```

--------------------------------

### AsyncFoamCase Methods

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Methods for managing and manipulating OpenFOAM case directories.

```APIDOC
## async cell_centers()

### Description
Write and return the cell centers. Currently only works for reconstructed cases.

## async block_mesh(check: bool = True, log: bool | str | PathLike[str] = True)

### Description
Run blockMesh on this case.

## async clean(check: bool = False)

### Description
Clean the case directory by removing time directories, processor directories, and log files.

### Parameters
#### Query Parameters
- **check** (bool) - Optional - If True, raise a CalledProcessError if the clean script returns a non-zero exit code.

## clone(dst: PathLike[str] | str | None = None)

### Description
Clone this case to create a clean copy. Can be used as an asynchronous context manager.

### Parameters
#### Query Parameters
- **dst** (PathLike[str] | str) - Optional - The destination path.

## copy(dst: PathLike[str] | str | None = None)

### Description
Make a copy of this case. Can be used as an asynchronous context manager.

### Parameters
#### Query Parameters
- **dst** (PathLike[str] | str) - Optional - The destination path.

## async decompose_par(check: bool = True, log: bool | str | PathLike[str] = True)

### Description
Decompose this case for parallel running.

## static map(coro: Callable[[_X], Awaitable[_Y]], iterable: Iterable[_X])

### Description
Run an async function on each element of an iterable concurrently, with automatic CPU limit management.

### Parameters
#### Query Parameters
- **coro** (Callable) - Required - An async function to run.
- **iterable** (Iterable) - Required - An iterable of arguments.
```

--------------------------------

### Access and Modify fvSchemes using FoamFile

Source: https://foamlib.readthedocs.io/en/stable/files.html

Demonstrates loading an fvSchemes file and modifying a specific setting using FoamFile.SubDict. This method is useful for direct file manipulation.

```python
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
```

--------------------------------

### List Output Files

Source: https://foamlib.readthedocs.io/en/stable/_sources/postprocessing.rst.txt

Lists all output files in a given directory and loads specified data into a dataframe. Useful for identifying and accessing post-processing results.

```python
out_files = list_outputfiles(root / "Cases")

forces = load_tables(
    source=out_files["forces--force.dat"], dir_name=root / "Cases"
)
```

--------------------------------

### Load and Modify OpenFOAM Field Files

Source: https://foamlib.readthedocs.io/en/stable/files.html

Demonstrates how to load an OpenFOAM field file directly or via a FoamCase object to access and modify field properties.

```python
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
```

```python
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]
```

--------------------------------

### FoamCaseBase Class

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Base class for accessing OpenFOAM case files and time directories.

```APIDOC
## class foamlib.FoamCaseBase

### Description
Base class for OpenFOAM cases. Provides methods for accessing files and time directories in the case.

### Parameters
- **path** (PathLike[str] | str) - Optional - The path to the case directory. Defaults to the current working directory.

### Properties
- **name** (str) - The name of the case.
- **control_dict** (FoamFile) - The controlDict file.
- **block_mesh_dict** (FoamFile) - The blockMeshDict file.
- **decompose_par_dict** (FoamFile) - The decomposeParDict file.
- **fv_schemes** (FoamFile) - The fvSchemes file.
- **fv_solution** (FoamFile) - The fvSolution file.
- **transport_properties** (FoamFile) - The transportProperties file.
- **turbulence_properties** (FoamFile) - The turbulenceProperties file.
- **application** (str) - The application name.
```

--------------------------------

### FoamCaseBase.TimeDirectory Properties and Methods

Source: https://foamlib.readthedocs.io/en/stable/_sources/cases.rst.txt

Details the properties and methods for accessing and manipulating time directories within a FoamLib case.

```APIDOC
## FoamCaseBase.TimeDirectory Properties

### Description
Represents a specific time directory within a simulation case.

### Properties
- **name** (string) - The name of the time directory (e.g., '0', '1000').
- **time** (float) - The numerical time value of the directory.

## FoamCaseBase.TimeDirectory Methods

### Description
Provides methods for interacting with a specific time directory.

### Methods
- **__getitem__(key)** - Get an item (e.g., a field file) from the time directory.
- **__iter__()** - Iterate over the items in the time directory.
- **__contains__(item)** - Check if an item exists in the time directory.
- **__len__()** - Get the number of items in the time directory.
- **__delitem__(key)** - Delete an item from the time directory.
```

--------------------------------

### FoamLib Exceptions

Source: https://foamlib.readthedocs.io/en/stable/_sources/cases.rst.txt

Documentation for exceptions raised by the FoamLib library.

```APIDOC
## CalledProcessError Exception

### Description
Exception raised when an external process called by FoamLib returns a non-zero exit code.

### Members
(Details of members are not specified in the provided text, but it can be inspected for error details.)
```

--------------------------------

### Create Study with CSV Generator

Source: https://foamlib.readthedocs.io/en/stable/parametricstudy.html

Use the CSV generator to create simulation cases based on parameters defined in a CSV file. Specify paths for the CSV, template, and output folder.

```python
csv_generator(
    csv_file="path/to/your/parameters.csv",
    template_case="path/to/template/case",
    output_folder="path/to/output/folder"
).create_study()
```

--------------------------------

### Run OpenFOAM Case on Slurm

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Run an OpenFOAM case on a Slurm cluster using `AsyncSlurmFoamCase`. This method allows specifying parallel execution, number of CPUs, and error checking. It also includes a fallback option to run locally if Slurm is unavailable.

```python
slurm_case = AsyncSlurmFoamCase("path/to/slurm/case")
await slurm_case.run(parallel=True, cpus=8, fallback=True)
```

--------------------------------

### Run an OpenFOAM Case

Source: https://foamlib.readthedocs.io/en/stable/cases.html

Executes an OpenFOAM case or a specified command within the case context. It intelligently invokes run scripts or default commands like blockMesh and the solver based on available files. Supports parallel execution and error checking.

```python
run(_cmd : Sequence[str | PathLike[str]] | str | None = None_, _*_ , _parallel : bool | None = None_, _cpus : int | None = None_, _check : bool = True_, _log : bool | str | PathLike[str] = True_)

```

--------------------------------

### foamlib.typing Module

Source: https://foamlib.readthedocs.io/en/stable/_sources/typing.rst.txt

Overview of standard types and flexible type variants used for OpenFOAM data representation in foamlib.

```APIDOC
## foamlib.typing

### Description
Provides type aliases for OpenFOAM data structures and flexible 'Like' variants for type conversion.

### Standard Types
- **File**: Alias for OpenFOAM file structures.
- **SubDict**: Alias for dictionary subsets.
- **Data**: General data structure alias.
- **StandaloneData**: Alias for standalone data objects.
- **DataEntry**: Alias for data entries.
- **StandaloneDataEntry**: Alias for standalone data entries.
- **Dict**: Alias for dictionary structures.
- **KeywordEntry**: Alias for keyword-based entries.
- **List**: Alias for list structures.
- **Field**: Alias for field data.
- **Tensor**: Alias for tensor data.

### Accepted 'Like' Types
These variants accept the standard type plus other formats that can be converted to the standard type:
- **FileLike**, **SubDictLike**, **DataLike**, **StandaloneDataLike**, **DataEntryLike**, **StandaloneDataEntryLike**, **DictLike**, **KeywordEntryLike**, **ListLike**, **FieldLike**, **TensorLike**, **DimensionSetLike**
```
Tokens:
Raw