microfluidica/foamlib

foamlib Docker镜像文档

镜像概述

foamlib是一个现代化的Python包，提供与OpenFOAM交互的优雅、简化界面。它旨在使基于OpenFOAM的工作流对研究人员和工程师更加易用、可重现和精确。

!https://github.com/gerlero/foamlib/raw/main/benchmark/benchmark.png

加载包含一百万个单元格的volVectorField

核心功能和特性

• 直观的文件处理：像操作Python对象一样读写OpenFOAM配置和场文件
• 高性能：独立解析器支持ASCII和二进制格式，无论是否压缩
• 异步操作：通过完整的asyncio支持并行运行多个案例
• 类型安全：全类型化API提供更好的开发体验
• 工作流自动化：减少用于前后处理和模拟管理的样板代码
• 完全兼容：适用于来自openfoam.com和openfoam.org的OpenFOAM

核心组件

文件处理

• FoamFile - 读写OpenFOAM配置文件，就像它们是Python字典一样
• FoamFieldFile - 处理场文件，支持ASCII和二进制格式（带或不带压缩）

案例管理

• FoamCase - 配置、运行和访问OpenFOAM案例结果
• AsyncFoamCase - 异步版本，用于并发运行多个案例
• AsyncSlurmFoamCase - 专为基于Slurm的HPC集群设计

安装方法

通过Docker拉取镜像：

bash
docker pull microfluidica/foamlib

使用方法

基本使用示例

bash
# 运行foamlib容器
docker run -it --rm microfluidica/foamlib python

# 在Python交互式环境中使用foamlib
>>> from foamlib import FoamCase
>>> case = FoamCase("path/to/case")
>>> case.run()
>>> latest_time = case[-1]
>>> pressure = latest_time["p"].internal_field
>>> print(f"Max pressure: {max(pressure)}")

Docker Compose配置示例

yaml
version: '3'
services:
  foamlib:
    image: microfluidica/foamlib
    volumes:
      - ./openfoam-cases:/cases
    working_dir: /cases
    command: python run_simulation.py

典型工作流示例

克隆并运行案例

python
import os
from pathlib import Path
from foamlib import FoamCase

# 克隆教程案例
pitz_tutorial = FoamCase(Path(os.environ["FOAM_TUTORIALS"]) / "incompressible/simpleFoam/pitzDaily")
my_pitz = pitz_tutorial.clone("myPitz")

# 运行模拟
my_pitz.run()

# 访问最新时间步的结果
latest_time = my_pitz[-1]
p = latest_time["p"]
U = latest_time["U"]

print(f"Pressure field: {p.internal_field}")
print(f"Velocity field: {U.internal_field}")

异步运行多个案例

python
import asyncio
from foamlib import AsyncFoamCase

async def run_multiple_cases():
    """并发运行多个案例"""
    base_case = AsyncFoamCase("base_case")
    
    # 创建并运行多个具有不同参数的案例
    tasks = []
    for i, velocity in enumerate([1, 2, 3]):
        case = base_case.clone(f"case_{i}")
        case[0]["U"].boundary_field["inlet"].value = [velocity, 0, 0]
        tasks.append(case.run())
    
    # 等待所有案例完成
    await asyncio.gather(*tasks)

# 运行异步函数
asyncio.run(run_multiple_cases())

直接访问场文件

python
from foamlib import FoamFieldFile

# 直接读取场数据
U = FoamFieldFile("0/U")
print(f"速度场形状: {U.internal_field.shape}")
print(f"边界: {list(U.boundary_field)}")

更多资源

• 完整文档: foamlib.readthedocs.io
• GitHub仓库: https://github.com/gerlero/foamlib
• PyPI页面: pypi.org/project/foamlib

引用

如果在研究中使用foamlib，请引用以下文献:

Gerlero, G. S., & Kler, P. A. (2025). foamlib: A modern Python package for working with OpenFOAM. Journal of Open Source Software, 10(109), 7633. [***]

BibTeX格式:

bibtex
@article{foamlib,
    author = {Gerlero, Gabriel S. and Kler, Pablo A.},
    doi = {10.21105/joss.07633},
    journal = {Journal of Open Source Software},
    month = may,
    number = {109},
    pages = {7633},
    title = {{foamlib: A modern Python package for working with OpenFOAM}},
    url = {[***]},
    volume = {10},
    year = {2025}
}