# ttttOpenFOAMTools

**Repository Path**: tong_yan_jun/tttt-open-foamtools

## Basic Information

- **Project Name**: ttttOpenFOAMTools
- **Description**: 根据工作经验构建一些常用的OpenFOAM工具
- **Primary Language**: Python
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-07-26
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenFOAM 工具集 (OpenFOAM Tools Toolkit)

一个用于 OpenFOAM 计算流体动力学 (CFD) 工作流的混合 Python/C++ 工具集，包含自动化测试、数据解析、日志监控和自定义求解器。

## 项目结构

```
tttt-open-foamtools/
├── app/                          # 独立应用程序
│   ├── of_test/                   # OpenFOAM 自动化测试工具（包含日志监控）
│   └── ofpp/                     # OpenFOAM 数据解析库
├── src/                          # 根级工具
├── tool/                         # 实用脚本
├── solver/                       # 自定义 OpenFOAM 求解器
├── mesh/                        # 网格示例和资源
├── testCases/                   # 演示算例
└── doc/                         # 文档
```

## 核心工具

### 1. runTest - OpenFOAM 自动化测试工具

基于 MVC 架构的自动化工作流工具，用于简化 OpenFOAM 算例的测试和管理。

**功能：**
- 工作流自动化：clean → mesh → solve 流水线
- 智能并行处理：自动调整 `decomposeParDict` 进行临时并行运行
- 实验版本控制：自动备份配置文件并增量记录日志
- 自动检测求解器：从 `system/controlDict` 读取
- **实时日志监控**：Rich 终端 UI 显示 OpenFOAM 求解器日志，支持暂停/继续/退出控制
  - 解析关键指标：Courant Number、Time、deltaT、Solver residuals、ExecutionTime
  - 交互控制：'p' 暂停，'c' 继续，'q' 退出
  - 集成模式：使用 `--monitor` 标志在求解完成后自动启动监控

**安装：**
```bash
cd app/of_test
conda env create -f environment.yml
conda activate foam-tools
pip install -e .
```

**使用：**
```bash
# 完整工作流：清理、生成网格、求解（4核并行）
runTest --all -np 4

# 指定步骤
runTest --mesh --solve simpleFoam

# 实验模式：监控配置文件变化
runTest experiment ./run.sh --watch system/meshDict --tag gridStudy

# 独立监控日志文件
runTest monitor log.simpleFoam

# 求解后自动监控
runTest --solve simpleFoam --monitor
```

**架构：**
- `src/core.py` - 服务层：纯业务逻辑，不打印到 stdout
- `src/cli.py` - 控制器/视图层：基于 Click 的 CLI 和异常处理
- `src/utils.py` - 工具层：上下文管理器和正则表达式解析器

### 2. Ofpp - OpenFOAM 数据解析库

简单的 Python 库，用于将 OpenFOAM 输出文件中的网格或场数据解析为 NumPy 数组，支持 ASCII 和二进制格式。

**功能：**
- 解析场数据：`parse_internal_field()`, `parse_boundary_field()`, `parse_field_all()`
- 解析网格：`FoamMesh` 类提供网格查询接口
- 支持二进制格式：使用 `struct` 解析二进制 OpenFOAM 文件

**安装：**
```bash
cd app/ofpp
pip install Ofpp
```

**使用：**
```python
import Ofpp

# 解析场数据
V = Ofpp.parse_internal_field('0/V')                # 单元体积
wb01 = Ofpp.parse_boundary_field('0.1/alpha.water')  # 边界场

# 解析网格
mesh = Ofpp.FoamMesh('.')
wall_cells = list(mesh.boundary_cells(b'fixedWall'))
cell_neighbour_5 = mesh.cell_neighbour_cells(5)
mesh.is_cell_on_boundary(545)
```

**依赖：**
- NumPy

### 3. 文件合并/分发工具 (foamtools) ⭐推荐

用于合并和分发 OpenFOAM 算例文件的实用工具，使用 `tttt:` 标记识别文件路径。

**功能：**
- 合并多个算例文件为单个大文件
- 根据 `tttt:` 标记将大文件拆分回原始结构
- **YAML 配置驱动**：从配置文件读取要合并的文件列表
- **专用输出目录**：合并后的文件保存在 `.foamtools` 文件夹（不污染算例目录）
- **灵活配置**：支持自定义文件列表和输出位置
- 支持任意 OpenFOAM 算例目录
- 命令行工具支持（`foamtools`）

**安装：**
```bash
cd src
pip install -e .
# 或使用 conda
conda develop .
```

**使用：**
```bash
# 初始化配置文件（推荐）
foamtools init-config

# 使用默认配置文件合并
foamtools quick-merge

# 使用自定义配置文件
foamtools quick-merge -f my_config.yaml

# 合并任意文件
foamtools merge 0/U 0/p system/controlDict

# 分发合并的文件回原始结构
foamtools dispense .foamtools/quick_merge.txt
```

**配置文件示例（foamtools_config.yaml）：**
```yaml
files:
  - "0/p"
  - "0/U"
  - "system/controlDict"

output:
  folder: ".foamtools"
  filename: "merged.txt"
```

详细文档请参见：`src/README.md`

## 自定义求解器

包含三个自定义的 OpenFOAM 求解器：

### bmk_inter_v2306Foam
用于特定研究目的的自定义求解器。

### bmk_pimple_v2306Foam
基于 PIMPLE 算法的自定义求解器。

### testNoHeat_reacEE_v2406Foam
无热传递的化学反应求解器。

**编译：**
```bash
wmake ../solver/<solver_name>
```

## 实用工具 (tool/)

位于 `tool/` 目录的独立脚本：

- `city_clust/` - 城市几何生成和 STL 导出
- `handle_stl/` - STL 文件处理工具
- `stpToStl/` - STP 到 STL 转换工具
- `parReconstructPar.sh` - 并行计算后处理脚本

## 演示算例 (testCases/)

包含完整的 OpenFOAM 算例示例：

### cavity
经典的 OpenFOAM cavity 教程算例。

### demo_case/terrain_with_cloud
包含复杂几何和时变边界条件的演示算例：
- `timeVar_BC.py` - 生成时变边界条件
- `postProcess.py` - 后处理脚本

### demo_case/box_cloud_transient
瞬态算例示例。

### demo_case/202507_multiphse_pipe
多相流管道算例。

## 安装依赖

**Python 依赖：**
```bash
pip install -r requirements.txt
```

主要依赖包括：
- Click - CLI 框架
- Colorama - 终端着色
- NumPy - 数值计算
- VTK - 可视化支持

**OpenFOAM 依赖：**
- OpenFOAM v2306 或 v2406
- cfMesh（用于某些算例）

## 开发指南

### 代码规范

**MVC 架构 (of_test)：**
- 服务层（`core.py`）严禁打印到 stdout
- 服务层不得导入 UI 库（click/colorama）
- 所有文件修改必须使用上下文管理器

**上下文管理器模式：**
```python
with temporary_decompose_modification(decompose_path, np):
    # 临时修改文件
    # 退出时自动恢复
```

**异常处理模式：**
- 服务层抛出异常
- CLI 层捕获并格式化后展示给用户

### Git 忽略规则

项目 `.gitignore` 包含 OpenFOAM 特定模式：
- `polyMesh/` - 网格文件
- `processor*` - 并行计算目录
- `*.foam` - ParaView 文件
- `debug.vtk` - 调试文件

## 已知问题

1. 所有功能均处于实验性质

## 待办事项

- [ ] 所有应用统一使用 `pyproject.toml`
- [ ] 添加 CI/CD 流水线
- [ ] 标准化求解器命名约定
- [ ] 考虑采用 monorepo 工具（poetry 或自定义）

## 许可证

- **Ofpp**: MIT License
- **其他工具**: 未指定

## 作者

- tttt (1136175177@qq.com) - 主要开发
- XU Xianghua (dayigu@gmail.com) - Ofpp 作者

## 参考资源

- [OpenFOAM 官方文档](https://www.openfoam.com/documentation/)
- [cfMesh 文档](https://cfmesh.com/cfmesh/)
- [fluidfoam](https://github.com/fluiddyn/fluidfoam) - OpenFOAM 数据解析参考