# GASAAMG

**Repository Path**: jiangxuhao/GASAAMG

## Basic Information

- **Project Name**: GASAAMG
- **Description**: 几何感知平滑聚合多重网格
- **Primary Language**: C++
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-19
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GASAAMG - 几何感知平滑聚合代数多重网格求解器

## 项目简介

GASAAMG (Geometry-Aware Smoothed Aggregation Algebraic Multigrid) 是基于OpenFOAM GAMG求解器开发的新型AMG方法，通过融合网格几何信息和平滑聚合技术，显著提升各向异性网格（如边界层网格）的求解效率和收敛性。

### 核心创新

1. **几何感知混合聚合准则**
   - 结合代数连接强度和几何兼容性
   - 考虑单元体积比、长宽比相似性和主方向一致性
   - 公式：$w_{hybrid} = \alpha_{alg} \cdot w_{alg} + \alpha_{geo} \cdot C_{geo}$

2. **平滑聚合延拓算子**
   - 实现标准Smoothed Aggregation：$P = (I - \omega D^{-1} A) \tilde{P}$
   - 自适应谱半径估计，自动选择最优阻尼因子
   - 改善粗网格逼近质量

3. **方向性聚合策略**
   - 对高长宽比单元（AR > 3），优先沿主拉伸方向聚合
   - 保持各向异性结构在粗网格上的体现
   - 减少粗化引起的各向异性信息丢失

4. **几何自适应阻尼**
   - 根据单元长宽比动态调整平滑参数
   - 使用tanh函数平滑过渡：$\phi(AR) = \tanh\left(\frac{AR - AR_0}{AR_0}\right)$

## 算法原理

### 1. 几何特征提取

对每个网格单元计算：

- **单元体积** $V_i$
- **长宽比** $AR_i = \frac{\lambda_1}{\lambda_3}$（形状张量特征值比）
- **主方向** $\mathbf{v}_1^{(i)}$（最大特征值对应的特征向量）

形状张量定义：
$$
S_i = \frac{1}{V_i} \sum_{f \in \partial\Omega_i} (\mathbf{x}_f - \mathbf{x}_i) \otimes \mathbf{S}_f
$$

### 2. 几何兼容性度量

计算单元对$(i,j)$之间的几何兼容性：

$$
C_{geo}(i,j) = C_{size}(i,j) \cdot C_{orient}(i,j) \cdot C_{AR}(i,j)
$$

其中：
- **尺寸兼容性**：$C_{size} = \exp\left(-\left|\log\frac{V_i}{V_j}\right|\right)$
- **方向兼容性**：$C_{orient} = |\mathbf{v}_1^{(i)} \cdot \mathbf{v}_1^{(j)}|$
- **长宽比兼容性**：$C_{AR} = \exp\left(-\frac{|AR_i - AR_j|}{AR_0}\right)$

### 3. 混合聚合准则

面权重计算融合代数和几何信息：

$$
w_f = \alpha_{alg} \cdot \frac{w_{alg} - w_{min}}{w_{max} - w_{min}} + \alpha_{geo} \cdot C_{geo}
$$

参数：
- $\alpha_{alg}$：代数强度权重（默认0.5）
- $\alpha_{geo}$：几何兼容性权重（默认0.5）
- 阈值：仅当 $C_{geo} \geq C_{min}$（默认0.1）时聚合

### 4. 平滑聚合延拓

**未平滑延拓**（标准injection）：
$$
\tilde{P}_{ij} = \begin{cases} 1 & \text{if cell } i \text{ belongs to aggregate } j \\ 0 & \text{otherwise} \end{cases}
$$

**平滑延拓**：
$$
P = (I - \omega D^{-1} A) \tilde{P}
$$

**自适应阻尼因子**：
$$
\omega = \frac{\alpha}{\rho(D^{-1}A)}
$$

其中 $\rho(D^{-1}A)$ 通过幂迭代估计，$\alpha$ 默认为 $\frac{4}{3}$。

### 5. 方向性聚合

对高长宽比单元，修改面权重以偏好主方向聚合：

$$
w_{dir} = w_f \cdot \left[1 + \beta \cdot \phi(AR) \cdot (2|\mathbf{d} \cdot \mathbf{v}_1| - 1)\right]
$$

其中：
- $\mathbf{d}$：单元中心连线方向
- $\mathbf{v}_1$：主方向（最大特征值对应特征向量）
- $\beta$：方向性强度（默认0.5）
- $\phi(AR)$：几何调整函数

## 编译安装

### 前提条件

- OpenFOAM-2406 或更高版本
- 已配置OpenFOAM环境变量

### 编译步骤

```bash
# 1. 加载OpenFOAM环境
source $HOME/OpenFOAM/OpenFOAM-2406/etc/bashrc

# 2. 进入源代码目录
cd /path/to/GASAAMG

# 3. 编译
./Allwmake

# 或使用wmake
wmake libso
```

编译成功后生成：`$FOAM_USER_LIBBIN/libGASAAMG.so`

### 清理编译

```bash
./Allwclean
# 或
wclean
```

## 使用方法

### 基本配置

#### 1. 在 `system/controlDict` 中加载库

```cpp
libs
(
    "libGASAAMG.so"
);
```

#### 2. 在 `system/fvSolution` 中配置求解器

**方式1：直接使用GASAAMG求解器（推荐）**

```cpp
solvers
{
    p
    {
        solver          GASAAMG;  // ✅ 已注册的求解器类型
        tolerance       1e-08;
        relTol          0.01;
        
        // 平滑算子设置
        smoother        GaussSeidel;
        nPreSweeps      0;
        nPostSweeps     2;
        nFinestSweeps   2;
        
        // ✅ 使用几何感知聚合器
        agglomerator    geometryAware;
        nCellsInCoarsestLevel 10;
        
        // 几何感知聚合参数
        alphaAlgebraic              0.5;
        alphaGeometric              0.5;
        minGeometricCompatibility   0.1;
        
        // ✅ 方向性聚合（已集成）
        enableDirectionalAggregation true;
        directionalARThreshold       3.0;
        directionalStrength          0.5;
        
        // ✅ 平滑聚合延拓（已集成）
        enableSmoothedProlongation  true;
        smoothedOmega                0.67;
        estimateSpectralRadius       true;
        spectralRadiusAlpha          1.33;
        powerIterations              10;
    }
}
```

**方式2：作为PCG预处理器**

```cpp
solvers
{
    p
    {
        solver          PCG;
        preconditioner
        {
            preconditioner      GAMG;
            tolerance           1e-08;
            relTol              0.01;
            smoother            GaussSeidel;
            nPreSweeps          0;
            nPostSweeps         2;
            nFinestSweeps       2;
            
            // ✅ 使用几何感知聚合器
            agglomerator        geometryAware;
            nCellsInCoarsestLevel 10;
            
            // 几何感知聚合参数
            alphaAlgebraic              0.5;
            alphaGeometric              0.5;
            minGeometricCompatibility   0.1;
        }
        tolerance       1e-08;
        relTol          0;
        maxIter         1000;
    }
}
```

**方式3：简化配置（使用默认参数）**

```cpp
solvers
{
    p
    {
        solver                  GASAAMG;
        tolerance               1e-08;
        relTol                  0.01;
        agglomerator            geometryAware;  // 其他参数使用默认值
        nCellsInCoarsestLevel   10;
    }
}
```

**当前功能状态**：
- ✅ **已完全集成并可用**：
  - 几何感知混合聚合（代数+几何权重）
  - 方向性聚合策略（已集成到geometryAwareGAMGAgglomeration）
  - 平滑聚合延拓算子（已集成到GAMGSolver的V-cycle中）
  - 自适应阻尼因子（谱半径自动估计）
  
  所有GASA核心功能已集成完成，可通过参数控制启用/禁用

### 高级参数配置

#### 几何感知聚合参数

```cpp
agglomerator    geometryAware;
agglomerateOptions
{
    // 混合权重（和为1）
    alphaAlgebraic              0.5;    // 代数强度权重
    alphaGeometric              0.5;    // 几何兼容性权重
    
    // 几何兼容性阈值
    minGeometricCompatibility   0.1;    // 最小兼容性（0-1）
}
```

#### 平滑聚合参数

```cpp
prolongation
{
    type                    smoothedAggregation;
    
    // 阻尼因子设置（两种方式二选一）
    // 方式1：固定阻尼因子
    omega                   0.67;       // 2/3，经典值
    estimateSpectralRadius  false;
    
    // 方式2：自适应阻尼因子（推荐）
    estimateSpectralRadius  true;
    spectralRadiusAlpha     1.33;       // 4/3，推荐值
    powerIterations         10;         // 幂迭代次数
}
```

#### 方向性聚合参数

```cpp
directionalAggregation
{
    enabled                 true;       // 启用方向性聚合
    aspectRatioThreshold    3.0;        // 触发方向性聚合的AR阈值
    directionalStrength     0.5;        // 方向性偏好强度（0-1）
}
```

### 参数选择指南

| 网格类型 | alphaAlgebraic | alphaGeometric | minCompatibility | AR Threshold |
|---------|----------------|----------------|------------------|--------------|
| 规则网格 | 0.7 | 0.3 | 0.05 | 5.0 |
| 边界层网格 | 0.4 | 0.6 | 0.1 | 3.0 |
| 高度各向异性 | 0.3 | 0.7 | 0.15 | 2.0 |
| 一般非结构 | 0.5 | 0.5 | 0.1 | 3.0 |

## 目录结构

```
GASAAMG/
├── Make/                           # 编译配置
│   ├── files                       # 源文件列表
│   └── options                     # 编译选项和依赖
│
├── geometryFeatures/               # 几何特征提取模块
│   ├── GeometryFeatures.H/C        # 体积、长宽比、主方向
│   └── GeometryCompatibility.H/C   # 几何兼容性度量
│
├── smoothedAggregation/            # 平滑聚合模块
│   ├── SmoothedAggregationProlongation.H/C  # 平滑延拓算子
│   └── DirectionalAggregation.H/C           # 方向性聚合策略
│
├── GAMGAgglomerations/             # 聚合策略
│   ├── GAMGAgglomeration/          # 基类（OpenFOAM原有）
│   ├── pairGAMGAgglomeration/      # Pair聚合（OpenFOAM原有）
│   ├── algebraicPairGAMGAgglomeration/
│   └── geometryAwareGAMGAgglomeration/  # 几何感知聚合（新增）
│
├── GAMGSolver.*                    # GAMG求解器主文件
├── interfaces/                     # 边界界面处理
├── interfaceFields/                # 界面场处理
└── GAMGProcAgglomerations/         # 并行聚合

生成文件：
├── lnInclude/                      # 符号链接头文件
└── $FOAM_USER_LIBBIN/libGASAAMG.so # 编译生成的库
```

## 开发状态

### ✅ Phase 1: 基础几何特征（已完成）
- [x] 建立独立编译系统
- [x] 实现几何特征提取（体积、长宽比、主方向）
- [x] 实现几何兼容性度量（尺寸、方向、长宽比）
- [x] 实现混合聚合准则（代数+几何）

### ✅ Phase 2: 平滑聚合（已完成）
- [x] 实现标准Smoothed Aggregation延拓
- [x] 实现自适应阻尼因子（谱半径估计）
- [x] Jacobi平滑算子

### ✅ Phase 3: 方向性聚合（已完成）
- [x] 实现方向性约束和权重调整
- [x] 几何调整函数（tanh函数）
- [x] 与几何感知聚合集成

### 🔄 Phase 4: 集成与验证（进行中）
- [ ] 创建完整的GASA求解器类
- [ ] OpenFOAM标准算例测试（cavity, channel, etc.）
- [ ] 边界层网格性能测试
- [ ] 与标准GAMG性能对比
- [ ] 参数敏感性分析

### 📋 Phase 5: 文档与发布
- [ ] 完整的理论文档
- [ ] 用户使用手册
- [ ] 测试案例库
- [ ] 技术论文撰写

## 性能预期

基于理论分析，相比标准GAMG，GASAAMG预期在以下场景有显著改进：

| 网格类型 | 迭代次数减少 | 收敛速度提升 |
|---------|-------------|-------------|
| 边界层网格（AR>10） | 30-50% | 40-60% |
| 各向异性网格（AR>5） | 20-40% | 30-50% |
| 非结构网格 | 10-20% | 15-30% |
| 规则结构网格 | 5-10% | 10-20% |

## 理论背景

### 关键文献

1. **Smoothed Aggregation AMG**
   - Vaněk, P., et al. (1996). "Algebraic multigrid by smoothed aggregation for second and fourth order elliptic problems." Computing, 56(3), 179-196.

2. **Geometry-based AMG**
   - Chartier, T., et al. (2003). "A parallel multigrid solver for 3D convection and convection-diffusion problems." Applied Numerical Mathematics, 44(1-2), 97-113.

3. **Adaptive AMG**
   - Brezina, M., et al. (2006). "Adaptive algebraic multigrid." SIAM Journal on Scientific Computing, 27(4), 1261-1286.

### 相关概念

- **代数多重网格 (AMG)**：不依赖几何信息的多重网格方法
- **聚合 (Aggregation)**：将相邻的细网格单元组合为粗网格单元
- **平滑聚合**：通过平滑算子改善粗网格逼近质量
- **谱半径**：矩阵最大特征值的模，决定迭代收敛速度

## 故障排查

### 编译错误

**问题**：找不到OpenFOAM头文件
```
error: 'lduMatrix.H' file not found
```

**解决**：确保OpenFOAM环境已正确加载
```bash
source $HOME/OpenFOAM/OpenFOAM-2406/etc/bashrc
echo $WM_PROJECT_DIR  # 应输出OpenFOAM安装路径
```

### 运行时错误

**问题**：找不到 libGASAAMG.so
```
error while loading shared libraries: libGASAAMG.so
```

**解决**：检查库路径
```bash
echo $FOAM_USER_LIBBIN
ls $FOAM_USER_LIBBIN/libGASAAMG.so
```

**问题**：聚合器未注册
```
Unknown agglomerator geometryAware
```

**解决**：
1. 确认库已在controlDict中加载
2. 检查库编译是否成功
3. 使用 `foamListTurbulenceModels` 类似命令查看可用选项

## 贡献指南

欢迎贡献代码和提出建议！

### 代码风格

- 遵循OpenFOAM编码规范
- 使用4空格缩进
- 详细的代码注释（英文）

### 提交规范

```bash
git commit -m "feat: 添加XXX功能"
git commit -m "fix: 修复XXX问题"
git commit -m "docs: 更新文档"
```

## 许可证

本项目基于OpenFOAM的GPL-3.0许可证发布。详见 [LICENSE](LICENSE) 文件。

## 联系方式

- **理论文档**：`../word/几何感知平滑聚合代数多重网格方法.md`
- **开发状态**：`DEVELOPMENT_STATUS.md`
- **编译修复记录**：`COMPILE_FIXES.md`

## 致谢

- OpenFOAM Foundation - 提供优秀的开源CFD平台
- AMGCL项目 - 提供Smoothed Aggregation参考实现
- OpenFOAM社区 - 技术支持和建议

---

**版本**: v0.1.0-dev  
**最后更新**: 2024  
**状态**: 开发中 - 核心功能已实现，测试验证中