氢原子轨道生成与可视化

Hydrogen Atom Orbital Generator & Visualizer

一个用于生成氢原子实轨道（real orbitals）三维数据并进行交互式可视化的小工具集。
A small toolkit for generating 3D data of hydrogen-atom real orbitals and interactive visualization.

  • 命令行生成数据 → orbital.py (CLI data generator)
  • 图形界面可视化 → 3DView.py (Tkinter + Matplotlib GUI)

示例图.png

功能特性 · Features

  • 基于解析波函数（径向 Rₙₗ × 实球谐 Y）精确计算氢原子实轨道，非数值求解薛定谔方程。
  • Computes orbitals analytically (radial Rₙₗ × real spherical harmonics), no numerical PDE solving.
  • 支持 s / p / d / f / g 轨道，其中 s/p/d/f提供标准的实轨道组合（如2px、3dxy、4fz3`）。
  • Supports s / p / d / f / g ; standard real-orbital combinations provided for s/p/d/f.
  • 可输出波函数 ψ（可正可负）或概率密度 |ψ|²（非负）。
  • Output either the wavefunction ψ (signed) or the probability density |ψ|² (non-negative).
  • GUI 支持截面彩虹图、径向分布曲线、三维等值面（marching cubes）。
  • GUI features: cross-section heatmaps, radial-distribution curves, and 3D isosurfaces (marching cubes).

项目结构 · Project Structure

文件 File说明 Description
orbital.py命令行工具，输入轨道名称，生成三维矩阵并保存为.npy
3DView.pyTkinter GUI，加载.npy/.txt 数据并可视化
requirements.txtPython 依赖清单
LICENSEMIT 许可证

安装 · Installation

1. 克隆仓库 / Clone

git clone https://github.com/ZTPchemistry/Hydrogen-Atom-Orbital-Generator-Visualizer
cd Hydrogen-Atom-Orbital-Generator-Visualizer

2. 安装依赖 / Install dependencies

pip install -r requirements.txt

Linux 用户注意： GUI 依赖 Tkinter（Python 标准库），但部分发行版需单独安装：

# Debian / Ubuntu
sudo apt install python3-tk
# Fedora
sudo dnf install python3-tkinter

快速开始 · Quick Start

1. 生成轨道数据 · Generate orbital data

python orbital.py 2px
# → 生成 2px_prob_200.npy（概率密度 |ψ|²，200³ 网格）

python orbital.py 3dxy --type wavefunction --grid 256
# → 生成 3dxy_psi_256.npy（波函数 ψ，256³ 网格）

python orbital.py 1s --grid 150 --box 20 --out my_orbital.npy
# → 自定义网格、空间边长与输出文件名

python orbital.py --list
# → 列出所有支持的轨道名称

2. 可视化 · Visualize

python 3DView.py

界面按钮说明 / GUI buttons:

  • 加载 .npy（三维矩阵）：加载 orbital.py 生成的矩阵数据
  • 加载 .txt（四列表格）：加载 N×4 格式（x, y, z, value）散点数据
  • 截面方向 / 位置：切换 XY/YZ/XZ 截面并滑动位置
  • 径向分布：沿自定义方向向量绘制平均值的径向分布
  • 等值面阈值：用 marching cubes 提取并显示三维等值面

支持的轨道 · Supported Orbitals

l轨道类型 Type示例 Examples
0 (s)ns1s, 2s, 3s
1 (p)npz, npx, npy2px, 2py, 2pz, 3px
2 (d)ndz2, ndxz, ndyz, ndx2-y2, ndxy3dxy, 3dxz, 3dz2, 4dx2-y2
3 (f)nfz3, nfxz2, nfyz2, nfz(x2-y2), nfxyz, nfx(x2-3y2), nfy(3x2-y2)4fz3, 4fxyz, 5fx(x2-3y2)

简写规则：2p 默认生成 2pz，3d 默认 3dz2，4f 默认 4fz3。
Shorthand: 2p → 2pz, 3d → 3dz2, 4f → 4fz3.

命令行参数 · CLI Reference

python orbital.py <轨道名称> [选项]
参数 Argument说明 Description默认值 Default
orbital轨道名称，如2px / 3dxy / 1s / 4fz3必填 required
-t, --type输出类型：wavefunction（ψ）或 probability（|ψ|²）probability
-g, --grid三维网格分辨率（N³ 个数据点）200
-b, --box模拟空间边长，单位：玻尔半径 a₀15
-o, --out输出文件名自动生成
--list列出所有支持轨道后退出—

输出文件 · Output Files

orbital.py 生成的文件名格式为 <轨道>_<类型>_<网格>_xmin_xmax_ymin_ymax_zmin_zmax_dx_dy_dz.npy，
例如 2px_prob_200_-7.5_7.5_-7.5_7.5_-7.5_7.5_0.075_0.075_0.075.npy。
数据是三维 NumPy 数组（float64），形状 (grid, grid, grid)，坐标范围编码在文件名中。
Files are named <orbital>_<type>_<grid>_xmin_xmax_ymin_ymax_zmin_zmax_dx_dy_dz.npy
(e.g. 2px_prob_200_-7.5_7.5_-7.5_7.5_-7.5_7.5_0.075_0.075_0.075.npy); the array is a (grid, grid, grid) float64 array, with the coordinate range encoded in the filename.

3DView.py 会自动从文件名解析坐标范围，无需手动输入。
若你使用 --out 自定义文件名（不含范围信息），加载时 3DView 会提示手动输入，默认参数（--box 15 --grid 200）对应值如下：
3DView.py auto-parses the range from the filename. If you pass a custom --out name (without range info), you'll be prompted to enter it manually; defaults (--box 15 --grid 200) are:

参数值（--box 15 --grid 200）
xmin / ymin / zmin-7.5
xmax / ymax / zmax+7.5
dx / dy / dz0.075（= 15 / 200）

注意事项 · Notes

  1. 内存 / Memory：grid=200 时单文件约 64 MB（200³ × 8 字节），grid=256 约 134 MB。
  2. scipy 版本 / scipy version：兼容新旧球谐函数接口——sph_harm_y（scipy ≥ 1.15）与旧版 sph_harm 回退均已支持，requirements.txt 要求 scipy>=1.8。
  3. GUI 环境 / GUI environment：3DView.py 需要图形界面环境，无法在无显示器的服务器 / 纯 WSL 中直接运行（需 X server）。

许可证 · License

MIT © 2026 ZTPchemistry