MaterialDFT 是一个独立开发的实验性 DFT 代码库，提供与 VASP 兼容的输入输出格式。当前重点是 PBE、static、non-spin、单线程计算路径，通过 VASP 风格输入输出和本地 C++/pybind11 后端运行算例，而后与相同输入的 VASP 跑出来的结果作为对标基线。

当前仓库覆盖了与 VASP PBE static non-spin 对应的单线程计算路径。目标输入形式是 VASP 风格的 INCAR、POSCAR、KPOINTS，运行时会根据 POTCAR 库组装赝势信息，并在 runs/ 下生成 VASP-like 输出文件，例如 OUTCAR、OSZICAR、vasprun.xml、CHGCAR、CONTCAR、EIGENVAL 和 DOSCAR。

仓库主要模块如下：

• cpp_core/：C++ 自实现计算核心，包括平面波基、FFT、局域/非局域赝势、PAW 运行时、PBE/Libxc 接口、SCF 循环、blocked Davidson 对角化、混合、能量与输出组装。
• src/materialdft/：Python API、运行服务、输入准备、manifest 生成、后端调度和 VASP-like I/O。
• src/materialdft_cpp_core/：pybind11 C++ 扩展的 Python 包装入口。
• scripts/：常用运行脚本，包括 scripts/run_cpp_core.sh。
• schema/、openapi/：manifest/API contract 定义。
• tests/：单元测试、数值路径测试、VASP-like 输出测试和部分 parity/debug 测试。
• docs/：公开资料、审计笔记和实现依据材料。
• example/：测试用例输入示例。
• cases/：测试报告中涵盖的全部算例输入。

如需与 VASP 结果做数值对比，仍需使用与 VASP 一致的 POTCAR 文件。POTCAR 属于 VASP 授权材料，本仓库不内置、不分发；用户需在持有有效 VASP license 的前提下自备 potpaw_PBE.64 文件夹，并在运行时通过 POTCAR_ROOT 指向该目录。

实现流程以 VASP Wiki 公开信息为主线，依据其公开描述实现 static SCF 计算流程，包括输入参数默认值、POTCAR 元数据、KPOINTS 语义、电子步迭代、混合、能量项和输出字段。

VASP Wiki 没有披露或描述不足的部分，会参考 DFT 相关公开论文，以及 Quantum ESPRESSO、GPAW、ABINIT 等第三方开源 DFT 代码中的实现方法进行补齐。对于公开资料中仍然缺少依据的细节，则采用 controlled probe 的方式，让 AI 在受控算例、数值 trace 和输出差异中自由探索候选实现，再通过回归测试和 parity 检查筛选。

也就是说，当前实现完全基于公开资料、第三方开源实现和数值实验独立构建，不涉及 VASP 源码或任何需要 license 才能获取的信息。

当前只对标了 VASP 的 static、non-spin 计算路径。对角化迭代仅实现与 VASP ALGO = Normal 同类的 blocked Davidson 路径；其他对角化模式不作为当前正式支持目标。

当前 VASP 风格输入解析支持以下 INCAR 参数，并映射到内部 input.settings：

KPOINTS 当前支持 VASP 常见的 automatic mesh 格式，包括 Gamma 和 Monkhorst-Pack 网格。POSCAR 支持常见直接坐标结构输入。

建议使用 Python 3.10+ 环境。示例：

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

如果只使用 Python API、输入解析或 manifest 工具，不编译 C++ 扩展，可以跳过 native build：

MaterialDFT_BUILD_CPP_CORE=0 pip install -e .[dev]

运行 PBE 路径需要 Libxc。Ubuntu/Debian 系统可以先尝试安装发行版包：

sudo apt-get update
sudo apt-get install -y libxc-dev pkg-config

安装后确认版本和 CMake 配置是否可见：

pkg-config --modversion libxc
find /usr -name 'LibxcConfig.cmake' -o -name 'libxc.pc' 2>/dev/null

如果系统包版本过旧，或需要使用自定义 Libxc，可以从源码安装到仓库下的 third_party/libxc：

mkdir -p third_party/src
cd third_party/src

curl -L -o libxc-6.2.2.tar.gz \
    https://gitlab.com/libxc/libxc/-/archive/6.2.2/libxc-6.2.2.tar.gz
tar xf libxc-6.2.2.tar.gz

cmake -S libxc-6.2.2 -B libxc-6.2.2-build -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX="$PWD/../libxc" \
    -DBUILD_SHARED_LIBS=ON \
    -DENABLE_FORTRAN=OFF

cmake --build libxc-6.2.2-build --parallel 4
cmake --install libxc-6.2.2-build

cd ../..

自定义安装完成后，后续 CMake 通过 MaterialDFT_LIBXC_PREFIX 指向该路径，例如 third_party/libxc。

构建 C++ cpp_core 的示例：

cmake -S . -B build/cpp_core_libxc -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DMaterialDFT_USE_LIBXC=ON \
    -DMaterialDFT_LIBXC_PREFIX=/path/to/libxc-6-or-newer

cmake --build build/cpp_core_libxc --parallel 4

如果系统已有可被 CMake 找到的 Libxc，也可以省略 MaterialDFT_LIBXC_PREFIX：

cmake -S . -B build/cpp_core_libxc -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DMaterialDFT_USE_LIBXC=ON

cmake --build build/cpp_core_libxc --parallel 4

CMake 构建需要 C++17 编译器、CMake、Ninja、FFTW3、LAPACK/BLAS、Python 开发头文件和 pybind11。若本地没有 pybind11，项目 CMake 可通过 FetchContent 获取；若系统 Python 头文件缺失，仓库会回退到 third_party/python_headers/。

将 VASP 格式的 INCAR、POSCAR、KPOINTS 放入同一个算例文件夹(见example/input)。脚本会在该文件夹中查找或生成 manifest.json，并根据 POTCAR_ROOT 指向的 POTCAR 库组装运行所需赝势。

示例命令：

CASE_DIR=/home/MaterialDFT-demo/S01_static_metal_bulk_mp_001/input \
POTCAR_ROOT=/home/potpaw_PBE.64 \
PYTHON_BIN=/home/.venv/bin/python \
bash scripts/run_cpp_core.sh OMPI=1

如果 C++ 扩展没有安装进 Python 包目录，也可以显式指定构建产物目录：

CPP_CORE_BUILD_DIR=/home/MaterialDFT-demo/build/cpp_core_libxc \
CASE_DIR=/home/MaterialDFT-demo/S01_static_metal_bulk_mp_001/input \
POTCAR_ROOT=/home/potpaw_PBE.64 \
PYTHON_BIN=/home/.venv/bin/python \
bash scripts/run_cpp_core.sh OMPI=1

生成的算例输出默认放在当前仓库下的 runs/ 文件夹中。每次运行会创建一个独立的 run_<timestamp>_<id>/ 子目录，核心结果在：

runs/<run_id>/result.json
runs/<run_id>/artifacts/

如需修改输出路径，可以设置 RUNS_DIR，或直接修改 scripts/run_cpp_core.sh 中的默认路径。

当前 benchmark 以 VASP 参考结果为基线，覆盖 static nonspin 单点计算场景，主要包括金属体相、金属缺陷、半导体体相、绝缘体体相、分子盒，以及 Edge 30 扩展集合中的 shifted k-mesh、非正交晶胞、低对称氧化物、perovskite、多元素和重元素 PAW 等输入类型。

本轮对比使用每个算例 OSZICAR 最后收敛行中的自由能 F 和 E0 作为数值指标，用于评估 MaterialDFT-demo 与 VASP 基线在收敛能量上的差距。从结果来看，MaterialDFT-demo 在小金属体相、简单 primitive 半导体/绝缘体、部分 perovskite 小原胞上已经能达到 1e-5 到 1e-3 eV 量级的误差；但在低对称非正交晶胞、分子盒、层状/六方体系、部分二元半导体、金属缺陷超胞和复杂过渡金属/重元素氧化物上，偏差仍可达 1e-2。因此，当前阶段为部分 static nonspin 场景的 OSZICAR 收敛能量已接近VASP，不声明为对 VASP 的全面数值对齐。

详细测试报告已放在：

docs/materialdft_demo_vs_vasp_oszicar_report.md