atomppgen.export

赝势导出模块

提供多种格式的赝势文件导出功能： - JSON：结构化元数据（参数、验证结果） - NPZ：数值数据（径向网格、势能、波函数） - UPF：Quantum ESPRESSO 兼容格式（实验性，当前仅提供最小可解析结构）

主要函数

export_pseudopotential : 统一导出接口

Functions

`export_pseudopotential`(ae_result, tm_dict, ...)	导出赝势到多种格式
`export_upf`(data, output_path[, metadata])	导出 UPF v2（实验性）

Classes

PseudopotentialData(Z, symbol, spin_mode, ...)

完整赝势数据包

class atomppgen.export.PseudopotentialData(Z, symbol, spin_mode, xc_functional, generation_params, radial_grid, radial_weights, ae_eigenvalues_by_l, ae_wavefunctions_by_l, pseudo_wavefunctions_by_l, semilocal_potentials_by_l, validation_report, generation_date, kb_loc_channel=None, kb_V_loc=None, kb_beta_l=None, kb_D_l=None, code_version='0.1.0', git_commit=None)[源代码]

完整赝势数据包

聚合全电子解、TM伪化、势反演、验证报告等所有数据源，用于统一格式导出。

参数:

Z (int)
symbol (str)
spin_mode (str)
xc_functional (str)
generation_params (Dict)
radial_grid (ndarray)
radial_weights (ndarray)
ae_eigenvalues_by_l (Dict[int, ndarray])
ae_wavefunctions_by_l (Dict[int, List[ndarray]])
pseudo_wavefunctions_by_l (Dict[int, ndarray])
semilocal_potentials_by_l (Dict[int, ndarray])
validation_report (ValidationReport)
generation_date (str)
kb_loc_channel (int | None)
kb_V_loc (ndarray | None)
kb_beta_l (Dict[int, ndarray] | None)
kb_D_l (Dict[int, float] | None)
code_version (str)
git_commit (str | None)

Z

原子序数

Type:: int

symbol

元素符号（如 'Al'）

Type:: str

spin_mode

自旋模式（'LDA' / 'GGA'）

Type:: str

xc_functional

交换关联泛函（'PZ81' / 'VWN'）

Type:: str

generation_params

生成参数（TM参数、网格参数等）

Type:: Dict

radial_grid

径向网格，单位 Bohr

Type:: np.ndarray

radial_weights

积分权重

Type:: np.ndarray

ae_eigenvalues_by_l

全电子本征值（按角动量 l 索引），单位 Hartree

Type:: Dict[int, np.ndarray]

ae_wavefunctions_by_l

全电子径向波函数（u = r·R）

Type:: Dict[int, List[np.ndarray]]

pseudo_wavefunctions_by_l

赝波函数（伪化后的价电子态）

Type:: Dict[int, np.ndarray]

semilocal_potentials_by_l

半局域势 V_l(r)，单位 Hartree

Type:: Dict[int, np.ndarray]

kb_loc_channel

KB 局域通道角动量量子数 l*（可选）

Type:: Optional[int]

kb_V_loc

KB 局域势 V_loc(r)，单位 Hartree（可选）

Type:: Optional[np.ndarray]

kb_beta_l

KB 投影子 {l: β_l(r)}（可选，已归一化）

Type:: Optional[Dict[int, np.ndarray]]

kb_D_l

KB 耦合系数 {l: D_l}（可选，Hartree）

Type:: Optional[Dict[int, float]]

validation_report

完整验证报告

Type:: ValidationReport

generation_date

生成时间戳（ISO 8601格式）

Type:: str

code_version

代码版本号

Type:: str

git_commit

Git 提交哈希（可选）

Type:: Optional[str]

Z: int

symbol: str

spin_mode: str

xc_functional: str

generation_params: Dict

radial_grid: ndarray

radial_weights: ndarray

ae_eigenvalues_by_l: Dict[int, ndarray]

ae_wavefunctions_by_l: Dict[int, List[ndarray]]

pseudo_wavefunctions_by_l: Dict[int, ndarray]

semilocal_potentials_by_l: Dict[int, ndarray]

validation_report: ValidationReport

generation_date: str

kb_loc_channel: Optional[int] = None

kb_V_loc: Optional[ndarray] = None

kb_beta_l: Optional[Dict[int, ndarray]] = None

kb_D_l: Optional[Dict[int, float]] = None

code_version: str = '0.1.0'

git_commit: Optional[str] = None

__init__(Z, symbol, spin_mode, xc_functional, generation_params, radial_grid, radial_weights, ae_eigenvalues_by_l, ae_wavefunctions_by_l, pseudo_wavefunctions_by_l, semilocal_potentials_by_l, validation_report, generation_date, kb_loc_channel=None, kb_V_loc=None, kb_beta_l=None, kb_D_l=None, code_version='0.1.0', git_commit=None)

参数:

Z (int)
symbol (str)
spin_mode (str)
xc_functional (str)
generation_params (Dict)
radial_grid (ndarray)
radial_weights (ndarray)
ae_eigenvalues_by_l (Dict[int, ndarray])
ae_wavefunctions_by_l (Dict[int, List[ndarray]])
pseudo_wavefunctions_by_l (Dict[int, ndarray])
semilocal_potentials_by_l (Dict[int, ndarray])
validation_report (ValidationReport)
generation_date (str)
kb_loc_channel (int | None)
kb_V_loc (ndarray | None)
kb_beta_l (Dict[int, ndarray] | None)
kb_D_l (Dict[int, float] | None)
code_version (str)
git_commit (str | None)

返回类型:

None

atomppgen.export.export_pseudopotential(ae_result, tm_dict, inv_dict, validation_report, output_prefix, kb_result=None, formats=['json', 'npz'], metadata=None)[源代码]

导出赝势到多种格式

参数:

ae_result (AEAtomResult) -- 全电子原子解
tm_dict (Dict[int, TMResult]) -- 各通道TM伪化结果（按角动量 l 索引）
inv_dict (Dict[int, InvertResult]) -- 各通道势反演结果（按角动量 l 索引）
validation_report (ValidationReport) -- 完整验证报告
output_prefix (str) -- 输出文件名前缀（如 'outputs/al_lda'）
formats (List[str], default=['json', 'npz']) -- 导出格式列表，支持 'json', 'npz', 'upf'
metadata (Optional[Dict], default=None) -- 额外元数据（如 git_commit, 备注）
kb_result (KBResult | None)

返回:

生成的文件路径列表

返回类型:

List[Path]

抛出:

ValueError -- 若 tm_dict 和 inv_dict 的 l 通道不一致

示例

>>> files = export_pseudopotential(
...     ae, tm_dict, inv_dict, report,
...     output_prefix='outputs/al_lda',
...     formats=['json', 'npz']
... )
>>> print(files)
[PosixPath('outputs/al_lda.json'), PosixPath('outputs/al_lda.npz')]

备注

输出单位约定： - 能量：Hartree 原子单位 - 长度：Bohr

JSON格式包含元数据和验证报告，NPZ格式包含数值数组。推荐同时导出JSON+NPZ以获得完整数据集。

atomppgen.export.export_upf(data, output_path, metadata=None)[源代码]

导出 UPF v2（实验性）

当前目标是提供“最小可解析、字段可追溯”的 UPF 结构，便于后续逐步对齐 QE 的严格要求。若要获得严格可用于 Quantum ESPRESSO 的 UPF，请关注后续版本更新。

参数:

data (PseudopotentialData) -- 完整赝势数据包
output_path (str | Path) -- 输出文件路径（建议后缀为 .upf）
metadata (dict, optional) -- 额外信息；UPF 需要的关键字段可在此给出： - z_valence : float（建议显式提供）

返回:

生成的 UPF 文件路径

返回类型:

Path