HContainer 模块介绍
作者：郑大也
单位：北京科学智能研究院
最后更新时间：2024/07/14
一、概述
HContainer 是 ABACUS 软件中的一个组件，用于存储和操作描述电子体系的哈密顿量矩阵的数据结构，适用于处理具有稀疏性的哈密顿量。
代码地址：/source/module_hamilt_lcao/module_hcontainer/
包含的文件：atom_pair.h, atom_pair.cpp, base_matrix.h, base_matrix.cpp, transfer.h, transfer.cpp, hcontainer_funcs.h, func_transfer.cpp, func_folding.cpp, output_hcontainer.h, output_hcontainer.cpp, hcontainer.h, hcontainer.cpp
1. 特点
- 模板化：
HContainer目前支持double和std::complex<double>两种数据类型，也可以根据需求提供更多的数值类型支持。 - 稀疏性处理：针对哈密顿量矩阵的稀疏特性，HContainer 提供了专门的存储和访问机制。
- 并行支持：HContainer 支持 MPI 并行，可以高效地在多处理器上进行数据分配和收集。
- 灵活的内存管理：HContainer 允许用户自定义内存分配策略，支持内存池的使用，以提高内存使用效率。
2. 使用场景
- 需要按原子对存储实空间数值原子轨道基组（LCAO）哈密顿量时。
- 需要按块稀疏矩阵形式存储的对象，比如 LCAO 基组密度矩阵等。
二、主要组件
1. HContainer 类
HContainer 类是本模块的核心，提供以下关键功能：
- 初始化：支持通过
Parallel_Orbitals类的实例对象初始化原子对。 内存分配：
- 存储结构：
HContainer类内部使用std::vector<AtomPair<T>>来存储原子对的信息（AtomPair），这些原子对按照原子序号的矩阵(i, j)排序。 - 稀疏表：
HContainer包含两个成员变量sparse_ap和sparse_ap_index，这两个std::vector<std::vector<int>>用作稀疏表，以快速定位原子对。 - 内存池：提供
allocate方法，允许用户指定内存池或由 HContainer 自行分配内存。
- 存储结构：
- 数据访问：通过
data方法获取特定原子对的哈密顿量矩阵数据指针。 原子对操作：提供
insert_pair、find_pair和get_atom_pair等方法，方便用户操作原子对。- find_pair 方法：
- 根据原子索引
atom_i和atom_j，find_pair方法可以快速定位并返回一个指向AtomPair的指针。 - 由于
atom_pairs容器中的原子对是排序的，find_pair可能使用二分查找算法来实现快速搜索。
- 根据原子索引
- get_atom_pair 方法：
- 这个方法返回一个对
AtomPair的引用，基于原子序号atom_i和atom_j。 - 与
find_pair类似，这个方法也依赖于原子对的排序来快速定位。
- 这个方法返回一个对
- find_matrix 方法：
- 这个方法可以根据原子索引和 R 指标来查找
BaseMatrix。 - 它首先使用
find_pair找到相应的AtomPair，然后在AtomPair中搜索具有匹配 R 指标的BaseMatrix。
- 这个方法可以根据原子索引和 R 指标来查找
- find_pair 方法：
- R 指数循环：通过
fix_R和unfix_R方法，用户可以固定或解除对特定布拉维格矢 R 的哈密顿量矩阵的操作。 - Gamma 模式：
fix_gamma方法允许 HContainer 进入 Gamma 模式，该模式下只处理R=(0,0,0)的哈密顿量矩阵。
三、使用示例
1. 初始化 HContainer
HContainer 作为一个类，可以用于实例化存储局域原子轨道基组下的哈密顿量矩阵、重叠矩阵等矩阵。
<em>// 假设ucell是已经初始化的UnitCell对象</em>
HContainer<double> HR(ucell);
<em>// 或者使用Parallel_Orbitals对象paraV来对HContainer初始化</em>
HContainer<double> HR(paraV);
// 使用确定的<IJR>原子对数组初始化
HContainer<double> HR(paraV, data_pointer, ijr_info)；
2. 插入原子对
在初始化 HContainer 的对象时有一个重要步骤，即插入原子对信息。当收集完所有原子对信息之后，即可对 HContainer 的对象进行内存分配。
// double是数据类型，这里0和1代表原子序号i和j（在所有原子中的序数）
AtomPair<double> atom_ij(0, 1, paraV);
// 在HContainer中插入原子对的信息
HR.insert_pair(atom_ij);
3. 内存分配
在对 HContainer 分配内存时使用 allocate() 函数。此时可以让 HContainer 自身来管理内存空间，也可使用自定义的数组（如这里给出的例子）
double* custom_memory = new double[custom_size];
HR.allocate(custom_memory, true); <em>// 使用自定义内存并初始化为零</em>
4. 数据访问
HContainer 的 data() 函数的参数为原子 i 和 j 的指标，以及布拉维格式 R，返回的是一个类型 T（doube 或者 complex
double* data_pointer = HR.data(0, 1, {0, 0, 0});
通过 R，返回的是一个类型 T（doube 或者 complex
double* data_ijr_pointer = HR.data(i, j, r_index);
5. R 指数循环
固定布拉维格子 R，对原子对进行循环操作。
HR.fix_R(0, 0, 0);
for (int i = 0; i < HR.size_atom_pairs(); i++) {
double* data = HR.data(i);
<em>// 操作data...</em>
}
HR.unfix_R();
6. 并行数据传输
6.1 HTransPara 和 HTransSerial 类
这两个类用于处理 HContainer 在并行环境下的数据传输：
- HTransPara：负责并行处理器间的数据打包、发送和接收。
- HTransSerial：负责串行处理器与并行处理器间的数据传输。
在
func_transfer.cpp文件里定义了一系列用于并行数据同步的接口，目前支持 5 种传输功能：- transferSerial2Parallels 单进程上完整 HContainer 对象往多进程上 2D 块并行存储 HContainer 对象数据传输；（典型应用场景：暂无）
- transferParallels2Serial 多进程上 2D 块并行存储 HContainer 对象往单进程上完整 HContainer 对象数据传输；（典型应用场景：gatherParallels）
- transferSerials2Parallels 多进程上每进程各一个未并行存储的 HContainer 对象往多进程上 2D 块并行存储的 HContainer 对象数据传输并求和（典型应用场景：格点积分 transfer_pvpR）；
- transferParallels2Serials 多进程上 2D 块并行存储 HContainer 对象往多进程上传输目标进程需要的稀疏特征的未进行并行存储的 HContainer 对象（典型应用场景：格点积分 transfer_DM2DtoGrid）。
- gatherParallels 多进程上 2D 块并行存储 HContainer 对象往单进程上未并行且为空的 HContainer 对象数据传输（典型应用场景：write_dmr）
6.2 并行模式下的注意事项
- 并行程序编写：HContainer 中内置了2D 块轨道并行方案，通过指针 const Parallel_Orbitals* paraV 控制具体的并行方案，每个原子对的稠密矩阵在任何核数并行下都依然是稠密矩阵，调用 HContainer 时不需要手动判断轨道的并行方式，可以结合Parallel_Orbitals类中提供的获取 local 轨道指标的功能函数辅助完成高效的并行程序编写。
- 数据同步：由于 HContainer 中采用了 2D 块轨道并行方案，一个矩阵元数据只唯一存储在其中一个进程的 HContainer 对象上，不需要进行手动同步，数据格式转换或并行方案切换时，可以手动调用hcontainer_funcs.h中提供的功能函数。
注 1：目前已开发的基于 HContainer 的功能函数有限，有更多对 HContainer 的接口需求请提交 Issue。
注 2：更多详细 Demo 代码和设计思路详见飞书文档 HContainer 类设计文档