# AI-Eigen

**Repository Path**: chn-cem/ai-eigen

## Basic Information

- **Project Name**: AI-Eigen
- **Description**: C++ 复数稀疏矩阵特征值求解器
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ARPACK C++ 复数稀疏矩阵特征值求解器

这是一个用C++重构的ARPACK复数稀疏矩阵特征值求解算法，集成了MUMPS库用于线性方程求解。

## 主要特性

- **复数稀疏矩阵支持**: 使用CSR (Compressed Sparse Row) 格式存储
- **多种求解模式**:
  - 标准特征值问题: `A*x = λ*x`
  - 广义特征值问题: `A*x = λ*M*x`
  - Shift-Invert模式: 求解接近给定值的特征值
- **MUMPS集成**: 高效的稀疏线性方程求解
- **Arnoldi迭代**: 基于Arnoldi方法的Krylov子空间算法
- **灵活的特征值选择**: 支持求解最大/最小模、最大/最小实部/虚部的特征值

## 项目结构

```
AI-Eigen/
├── include/
│   ├── CSparseMatrix.h           # 复数稀疏矩阵类
│   ├── MumpsSolver.h             # MUMPS求解器封装
│   └── ArpackEigenSolver.h       # ARPACK特征值求解器
├── src/
│   ├── CSparseMatrix.cpp
│   ├── MumpsSolver.cpp
│   └── ArpackEigenSolver.cpp     # 2766行核心实现
├── examples/
│   ├── quick_validation.cpp              # 快速验证测试
│   ├── comprehensive_benchmark.cpp       # 综合基准测试（与ARPACK对比）
│   ├── extreme_scale_test.cpp            # 超大规模测试
│   ├── ill_conditioned_benchmark.cpp     # 病态矩阵测试
│   ├── repeated_eigenvalue_benchmark.cpp # 重复特征值测试
│   └── README.md                         # 测试套件详细文档
├── CMakeLists.txt
├── BUILD_AND_TEST.md             # 构建和测试指南
├── run_all_tests.bat             # Windows测试脚本
└── run_all_tests.sh              # Linux/Mac测试脚本
```

## 测试套件

本项目包含完整的测试套件，用于验证精度和性能：

### 快速验证（1分钟）
```bash
./build/quick_validation
```

### 完整测试套件（10-30分钟）
```bash
cd build
../run_all_tests.bat    # Windows
../run_all_tests.sh     # Linux/Mac
```

测试包括：
- ✅ **随机特征值问题** - 不同规模的随机稀疏矩阵
- ✅ **病态矩阵** - 条件数从1e4到1e12
- ✅ **重复特征值** - 处理重数高达10的特征值
- ✅ **超大规模** - 最大规模n=125,000
- ✅ **ARPACK对比** - 精度和性能全面比较

详细信息参见 [测试文档](examples/README.md) 和 [构建指南](BUILD_AND_TEST.md)

## 依赖项

- **C++17** 或更高版本
- **BLAS/LAPACK**: 线性代数运算
- **MUMPS**: 稀疏线性方程求解 (可选，用于shift-invert模式)
- **CMake 3.15+**: 构建工具

## 编译

### 1. 安装依赖

**Windows (使用vcpkg):**
```bash
vcpkg install openblas lapack
# MUMPS需要手动编译或使用预编译版本
```

**Linux:**
```bash
sudo apt-get install libblas-dev liblapack-dev libmumps-dev
```

**macOS:**
```bash
brew install openblas lapack mumps
```

### 2. 配置CMake

```bash
mkdir build
cd build

# 如果MUMPS安装在非标准位置，需要指定路径
cmake .. \
  -DMUMPS_INCLUDE_DIR=/path/to/mumps/include \
  -DMUMPS_LIBRARY_DIR=/path/to/mumps/lib

# 或者使用默认设置
cmake ..
```

### 3. 编译

```bash
cmake --build . --config Release
```

## 使用方法

### 基本示例

```cpp
#include "ArpackEigenSolver.h"

using Complex = std::complex<double>;

int main() {
    int n = 100;  // 矩阵维度
    int nev = 6;  // 要计算的特征值数量
    
    // 构建稀疏矩阵 (COO格式)
    std::vector<int> rows, cols;
    std::vector<Complex> values;
    
    // ... 添加矩阵元素 ...
    
    CSparseMatrix A(n, n, rows, cols, values);
    
    // 创建求解器
    ArpackEigenSolver solver(n, nev);
    solver.setMode(ArpackEigenSolver::Mode::Standard);
    solver.setWhich(ArpackEigenSolver::Which::LargestMagnitude);
    solver.setTolerance(1e-8);
    
    // 求解
    solver.compute(A);
    
    // 获取结果
    for (int i = 0; i < solver.converged(); ++i) {
        Complex lambda = solver.eigenvalue(i);
        auto v = solver.eigenvector(i);
        std::cout << "λ[" << i << "] = " << lambda << std::endl;
    }
    
    return 0;
}
```

### 使用Shift-Invert模式

```cpp
// 求解接近 σ = 1.5 的特征值
ArpackEigenSolver solver(n, nev);
solver.setMode(ArpackEigenSolver::Mode::ShiftInvert);
solver.setShift(Complex(1.5, 0.0));
solver.setWhich(ArpackEigenSolver::Which::LargestMagnitude);

solver.compute(A);  // 内部调用MUMPS求解线性方程
```

### 广义特征值问题

```cpp
// 求解 A*x = λ*M*x
CSparseMatrix A(...);
CSparseMatrix M(...);

ArpackEigenSolver solver(n, nev);
solver.setMode(ArpackEigenSolver::Mode::GeneralizedRegular);
solver.compute(A, M);
```

## API参考

### CSparseMatrix

复数稀疏矩阵类，使用CSR格式存储。

```cpp
// 构造函数
CSparseMatrix(int rows, int cols, 
              const std::vector<int>& row_indices,
              const std::vector<int>& col_indices,
              const std::vector<Complex>& values);

// 矩阵-向量乘法
void multiply(const Complex* x, Complex* y) const;
```

### MumpsSolver

MUMPS求解器封装类。

```cpp
// 分析和分解矩阵
void analyze(const CSparseMatrix& matrix);

// 求解线性方程组 A*x = b
void solve(const Complex* b, Complex* x);
```

### ArpackEigenSolver

ARPACK特征值求解器。

```cpp
// 构造函数
ArpackEigenSolver(int n, int nev, int ncv = 0);

// 设置参数
void setMode(Mode mode);
void setWhich(Which which);
void setTolerance(double tol);
void setShift(Complex sigma);

// 求解
void compute(const CSparseMatrix& A);
void compute(const CSparseMatrix& A, const CSparseMatrix& M);

// 获取结果
const std::vector<Complex>& eigenvalues() const;
Complex eigenvalue(int i) const;
std::vector<Complex> eigenvector(int i) const;
int converged() const;
```

## 运行示例

```bash
cd build
./eigen_example
```

示例程序演示了：
1. 标准特征值问题求解
2. Shift-Invert模式使用
3. 特征值/特征向量验证

## 性能说明

- **CSR格式**: 高效的稀疏矩阵存储和运算
- **Arnoldi迭代**: 只需O(k)次矩阵-向量乘法，k << n
- **MUMPS**: 高性能的直接法稀疏求解器，支持并行计算
- 适用于大规模稀疏矩阵 (n > 10000)

## 注意事项

1. **MUMPS配置**: Shift-invert模式需要正确配置MUMPS库
2. **内存使用**: Arnoldi向量数量(ncv)影响内存占用，建议 ncv = 2*nev+1
3. **收敛性**: 对于困难问题，可能需要增加ncv或最大迭代次数
4. **数值稳定性**: 使用Modified Gram-Schmidt正交化保证稳定性

## 许可证

本项目遵循MIT许可证。

## 参考文献

1. R. B. Lehoucq, D. C. Sorensen, and C. Yang, "ARPACK Users' Guide"
2. P. R. Amestoy et al., "A Fully Asynchronous Multifrontal Solver Using Distributed Dynamic Scheduling"
3. Y. Saad, "Iterative Methods for Sparse Linear Systems"