libxc 使用重构 · Pull Request !107 · RESTGroup/rest

该 PR 将引入重构的 libxc FFI wrapper。
https://docs.rs/libxc/latest/libxc/
https://github.com/restGroup/libxc-rs

该重构对目前的 PR 有影响。!105

## 动机

- **功能拆分**：REST 本体的目标是实现电子结构算法、以及整合算法形成完整的程序。FFI 作为非常底层的功能，是可以去耦的。
- **功能改进**：提供所有 pylibxc 功能，以及与 pylibxc 相似的命名规则，以及更改 hybrid/omega 泛函的功能。
- **内存资源管理**：现在的 libxc 封装类型 `LibXCFunctional` 实现了 Drop trait，避免要对原先 `XcFuncType` 显示调用 `xc_func_end()` (手动释放内存的写法容易导致 leak 或 double free，实际上我们以前用 libxc 的大多数时候都是 leak 内存的，尽管 leak 的量不大)。
- **简化编译**：删除 build.rs 中不必要的 bindgen 处理。(related to [rest_tensors!9](https://gitee.com/restgroup/rest_tensors/pulls/9))

------

下述长文档可折叠。该文档由 deepseek-v4-pro 生成。

<summary>libxc 使用重构 (长文档)</summary>

# PR: libxc 使用重构 — 长文档

## 1. 架构变更概述

```
重构前:
  rest ──> src/dft/libxc/mod.rs (XcFuncType 结构体 + 方法)
               └── src/dft/libxc/ffi_xc.rs (unsafe C FFI 声明)
               └── src/dft/libxc/libxc_full.rs (功能性常量全集)
               └── src/dft/libxc/names_and_values.rs (build.rs 自动生成)

重构后:
  rest ──> external crate libxc (社区维护)
               └── libxc::functional::LibXCFunctional (安全 Rust 封装)
               └── libxc::enums::LibXCFamily, LibXCSpin, LibXCFlags
               └── libxc::util::* (辅助函数)
           └── src/dft/libxc_helper.rs (薄封装, 向后兼容)
```

## 2. 类型映射表

| 旧类型 (手写) | 新类型 (外部 crate) | 说明 |
|---|---|---|
| `libxc::XcFuncType` | `libxc::functional::LibXCFunctional` | 功能性对象, 不再需要手动释放 |
| `libxc::LibXCFamily` | `libxc::enums::LibXCFamily` | 枚举命名有差异 (见下) |
| `libxc::XcFuncType::xc_func_family` (字段) | `LibXCFunctional::family()` (方法) | 从公开字段改为访问器方法 |
| `LibXCFamily::Unknown` | (不存在) | 旧代码的 Unknown 变体不再使用 |

### 2.1 LibXCFamily 枚举变体对照

| 旧名称 | 新名称 | 备注 |
|---|---|---|
| `LDA` | `LDA` | 一致 |
| `GGA` | `GGA` | 一致 |
| `MGGA` | `MGGA` | 一致 |
| `HybridGGA` | `HybGGA` | 重命名 |
| `HybridMGGA` | `HybMGGA` | 重命名 |
| (无) | `HybLDA` | 新增变体 |
| `Unknown` | (无) | 不再提供; 旧代码中的 `Unknown` 转换为 `panic!` |

## 3. 函数与方法变换表

### 3.1 构造与销毁

| 旧接口 | 新接口 | 备注 |
|---|---|---|
| `XcFuncType::xc_func_init(code, spin)` | `xc_func_init(code, spin)` (libxc_helper) | 内部调用 `LibXCFunctional::from_number(...)` |
| `xc_func.xc_func_end()` | (删除) | RAII 自动释放 |

### 3.2 信息与元数据

| 旧接口 | 新接口 |
|---|---|
| `xc_func.xc_func_info_printout()` | `println!("{}", xc_func.describe())` |
| `xc_func.get_libxc_family()` | `xc_func.family()` |
| `xc_func.get_family_name()` | (不再直接可用; 替换为 `{xc_family:?}` panic 消息) |
| `xc_func.get_libxc_references()` | `xc_func.references()` (返回 `&[LibXCReference]`, 通过 `.ref_text` 获取文本) |

### 3.3 功能性特性检测

| 旧接口 | 新接口 |
|---|---|
| `xc_func.is_rsh()` | `xc_func.is_hyb_cam()` |
| `xc_func.use_exact_exchange()` | (不再需要; 通过 `hyb_exx_coef()` 返回值判断) |
| `xc_func.use_density_gradient()` | `!matches!(xc_func.family(), LDA \| HybLDA)` |
| `xc_func.use_kinetic_density()` | `xc_func.needs_tau()` |
| `xc_func.use_laplacian()` | `xc_func.needs_laplacian()` |
| `xc_func.is_nlc()` | `xc_func.flags().contains(LibXCFlags::VV10)` |

### 3.4 泛函参数获取

| 旧接口 | 新接口 | 备注 |
|---|---|---|
| `xc_func.xc_hyb_exx_coeff()` | `xc_func.hyb_exx_coef()` | 新接口返回 `Option<f64>`, 非泛函返回 `None` |
| `xc_func.xc_hyb_cam_coef()` -> `(omega, alpha, beta)` | `xc_func.cam_coef()` -> `Option<(omega, alpha, beta)>` | 新接口返回 `Option`, 非 CAM 泛函返回 `None` |

### 3.5 DFT 计算 (XC 能量与势)

| 旧接口 (XcFuncType 方法) | 新接口 (libxc_helper 自由函数) |
|---|---|
| `xc_func.lda_exc_vxc(rho)` | `lda_exc_vxc(&xc_func, rho)` |
| `xc_func.gga_exc_vxc(rho, sigma)` | `gga_exc_vxc(&xc_func, rho, sigma)` |
| `xc_func.mgga_exc_vxc(rho, sigma, lapl, tau)` | `mgga_exc_vxc(&xc_func, rho, sigma, lapl, tau)` |
| `xc_func.lda_exc(rho)` | `lda_exc(&xc_func, rho)` |
| `xc_func.gga_exc(rho, sigma)` | `gga_exc(&xc_func, rho, sigma)` |
| `xc_func.mgga_exc(rho, sigma, lapl, tau)` | `mgga_exc(&xc_func, rho, sigma, lapl, tau)` |
| `eval_libxc_func_new(xc_func, ...)` | `eval_libxc_func_new(&xc_func, ...)` (签名不变, 传引用) |

### 3.6 XC 版本信息

| 旧接口 | 新接口 |
|---|---|
| `unsafe { xc_version(&mut vmajor, &mut vminor, &mut vmicro) }` | `libxc::util::libxc_version()` -> `(i32, i32, i32)` |

### 3.7 功能性查询 (parse_xc/xc_helper.rs)

| 旧接口 (unsafe FFI) | 新接口 (libxc crate util) |
|---|---|
| `unsafe { xc_functional_get_name(id) }` -> `CStr` | `libxc::util::libxc_functional_get_name(id)` -> `Option<String>` |
| `unsafe { xc_number_of_functionals() }` + `unsafe { xc_available_functional_numbers(ptr) }` | `libxc::util::libxc_available_functional_numbers()` -> `Vec<i32>` |

## 4. 已删除的 `get_hybrid` trait 实现

`src/dft/parse_xc/parse.rs` 中移除了为 `XcFuncType` 实现的 `get_hybrid()` 方法:

```rust
// 旧代码 (已删除)
impl XcFuncType {
    pub fn get_hybrid(&self) -> f64 {
        match self.xc_func_family {
            LibXCFamily::HybridGGA | LibXCFamily::HybridMGGA => {
                self.xc_hyb_exx_coeff()
            },
            _ => 0.0,
        }
    }
}
```

该逻辑在调用处内联为 `xc_func.hyb_exx_coef().unwrap_or(0.0)`。

## 5. build.rs 变更

- 删除了 `generate_libxc_names_and_values()` 函数 (约 50 行)。该函数之前从 `libxc_full.rs` 中解析所有 `pub const XC_*` 常量生成 `names_and_values.rs`。
- 从 `library_names` 列表中移除了 `"xc"` (不再需要链接 libxc, 由外部 crate 处理)。

## 6. `xc_code_fdqc` 的变更

名称查找逻辑从遍历 `libxc_names_values::MAP` 改为遍历 `LIBXC_FUNC_MAP`（来自 `libxc` crate 的常量映射）。行为等价。

移除了已废弃的 `xc_code_to_name` 函数 (最后一次 commit 删除)。

## 7. 使用 `use_density_gradient` / `use_kinetic_density` 的重构

`DFA4REST::use_density_gradient()` 和 `DFA4REST::use_kinetic_density()` 从手动遍历 (曾经调用已不存在的 `xc_func.use_density_gradient()` / `xc_func.use_kinetic_density()`) 改为使用 Rust 迭代器链式调用。

## 8. 注意事项

- **`.xc_func_end()` 全部移除**：外部 crate `libxc` 的 `LibXCFunctional` 实现了 `Drop`, 在离开作用域时自动释放 C 端资源。
- **`HybridGGA` → `HybGGA`, `HybridMGGA` → `HybMGGA`**：这是外部 crate 的命名约定, 在项目内全局替换。
- **`cam_coef()` 和 `hyb_exx_coef()` 返回 `Option`**：调用方需要处理 `None` 情况 (非泛函或非 CAM), 通常用 `unwrap_or(0.0)` 或 `unwrap_or((0.0, 0.0, 0.0))`。

</details>

类型	指派人员	状态
审查	张颖已审查通过	已完成 (1/1人)
测试	张颖已测试通过	已完成 (1/1人)

RESTGroup/rest .gitee-modal { width: 500px !important; }

搜索帮助

RESTGroup/rest