二维热传导模型（Heat2D）

一个使用 Python 实现的二维平板瞬态热传导数值模拟项目。程序采用显式有限差分法（FTCS）求解二维热传导方程，并使用 Matplotlib 动画展示温度场随时间的变化。

项目目前支持矩形区域、恒定热扩散率、固定温度边界和高斯型初始温度分布，适合用于学习二维热传导方程、有限差分离散方法和小型科学计算项目的工程化组织。

功能特性

• 使用 NumPy 完成二维网格和温度场计算；
• 使用显式有限差分格式推进时间；
• 根据网格间距和热扩散率自动计算稳定时间步长；
• 支持自定义平板尺寸、网格节点数、热扩散率和模拟时间；
• 使用两个高斯热斑构造直观的热扩散与融合演示；
• 使用固定温度（Dirichlet）边界条件；
• 使用 Matplotlib 动画显示温度扩散过程；
• 使用 dataclass 集中管理模拟参数；
• 提供基于标准库 unittest 的自动化测试；
• 同时支持脚本入口和 Python 包入口。

数学模型

对于各向同性、均匀且没有内部热源的二维平板，温度场满足：

$$\frac{\partial T}{\partial t}=\alpha \left( \frac{\partial^2 T}{\partial x^2}+ \frac{\partial^2 T}{\partial y^2} \right)$$

其中：

• $T(x,y,t)$：温度，单位为 $^\circ\mathrm{C}$；
• $t$：时间，单位为 $\mathrm{s}$；
• $x,y$：空间坐标，单位为 $\mathrm{m}$；
• $\alpha$：热扩散率，单位为 $\mathrm{m^2/s}$。

计算区域为：

$$0 \leq x \leq L_x, \qquad 0 \leq y \leq L_y$$

初始条件

初始温度由两个位于平板水平中线上的二维高斯热斑叠加而成：

$$T(x,y,0)=20+280\exp\left[-\frac{(x-0.3L_x)^2+(y-0.5L_y)^2}{2\sigma^2} \right]+280\exp\left[-\frac{(x-0.7L_x)^2+(y-0.5L_y)^2}{2\sigma^2} \right]$$

两个热斑的中心分别位于 $(0.3L_x,0.5L_y)$ 和 $(0.7L_x,0.5L_y)$，单个热斑的理论峰值约为 $300\,^\circ\mathrm{C}$。由于两个高斯分布会少量重叠，实际初始最高温度会略高于 $300\,^\circ\mathrm{C}$。参数 $\sigma$ 控制热斑宽度：$\sigma$ 越大，两个初始热区越宽、越容易重叠。

这组初始条件能够直观展示：

• 两个高温峰值随时间逐渐降低；
• 热斑覆盖范围逐渐扩大；
• 两个原本分离的热区逐渐连接并融合；
• 最终温度场在固定低温边界作用下趋近 $20\,^\circ\mathrm{C}$。

边界条件

平板四条边采用固定温度边界：

$$T=20\,^\circ\mathrm{C}$$

每次完成时间推进后，程序都会重新施加该边界条件。

数值方法

空间二阶导数使用中心差分，时间方向使用向前差分。内部节点的更新格式为：

$$T_{i,j}^{n+1}=T_{i,j}^{n}+r_x\left(T_{i,j+1}^{n}-2T_{i,j}^{n}+T_{i,j-1}^{n}\right)+r_y\left(T_{i+1,j}^{n}-2T_{i,j}^{n}+T_{i-1,j}^{n}\right)$$

其中：

$$r_x=\frac{\alpha\Delta t}{\Delta x^2}, \qquad r_y=\frac{\alpha\Delta t}{\Delta y^2}$$

二维显式差分格式需要满足稳定性条件：

$$r_x+r_y\leq\frac{1}{2}$$

程序首先计算理论稳定时间步上限：

$$\Delta t_{\max}=\frac{1}{2\alpha\left(1/\Delta x^2+1/\Delta y^2\right)}$$

实际使用：

$$\Delta t=0.8\Delta t_{\max}$$

因此正常情况下 $r_x+r_y=0.4$，为理论稳定上限保留了安全余量。求解器内部也会再次检查稳定性条件。

frames 表示动画保存的输出时刻数量，并不等于数值计算的时间步数。两个输出时刻之间，求解器可能执行多次数值时间推进。

默认参数

参数	代码名称	默认值	说明
平板长度	x_length	1.0 m	x 方向区域长度
平板宽度	y_length	1.0 m	y 方向区域长度
x 方向节点数	nx	121	包含两端边界节点
y 方向节点数	ny	121	包含两端边界节点
热扩散率	alpha	0.01 m²/s	控制温度扩散速度
高斯热斑宽度	sigma	0.12 m	控制两个初始热斑的宽度
模拟总时间	time	2.0 s	数值模拟终止时刻
动画帧数	frames	100	保存和显示的温度场数量

在默认参数下：

• $\Delta x=\Delta y\approx0.00833\,\mathrm{m}$；
• 自动计算得到 $\Delta t\approx0.001389\,\mathrm{s}$；
• 完整模拟大约执行 1440 次显式时间推进；
• 最终保存 100 个用于动画显示的温度场。

项目结构

二维热传导模型v2/
├── heat2d/
│   ├── __init__.py            # 定义包的公共接口
│   ├── __main__.py            # python -m heat2d 入口
│   ├── app.py                 # 组织完整模拟流程
│   ├── config.py              # 参数数据类和交互式配置
│   ├── grid.py                # 网格与稳定时间步生成
│   ├── boundary.py            # 固定温度边界条件
│   ├── initial_conditions.py  # 双高斯热斑初始温度场
│   ├── solver.py              # 显式有限差分求解器
│   └── visualization.py       # Matplotlib 温度场动画
├── tests/
│   ├── test_config.py
│   ├── test_grid.py
│   ├── test_initial_conditions.py
│   └── test_solver.py
├── main.py                    # 兼容的脚本启动入口
├── pyproject.toml             # 项目信息与依赖声明
├── .gitignore                 # Git 忽略规则
└── README.md                  # 项目文档

程序的主要调用流程为：

读取用户配置
    ↓
创建空间网格并计算稳定时间步
    ↓
生成双高斯热斑初始温度场
    ↓
显式有限差分时间推进
    ↓
保存指定输出时刻的温度场
    ↓
生成 Matplotlib 动画

环境要求

• Python 3.10 或更高版本；
• NumPy；
• Matplotlib。

项目已在 Python 3.14、NumPy 2.4 和 Matplotlib 3.11 环境中运行验证。

安装

进入项目根目录后，建议先创建独立虚拟环境：

python -m venv .venv
.venv\Scripts\Activate.ps1

然后以可编辑模式安装项目及其依赖：

python -m pip install -e .

可编辑安装适合开发阶段。修改 heat2d/ 中的代码后，不需要重复安装项目。

运行模拟

推荐使用包入口：

python -m heat2d

也可以使用根目录兼容入口：

python main.py

程序会依次询问模拟参数：

请输入平板长度,默认值为1.0:
请输入平板宽度,默认值为1.0:
请输入x方向网格格数,默认值为101:
...

直接按 Enter 会采用当前参数的默认值。完成参数输入后，程序计算温度场并显示动画窗口。

运行测试

测试使用 Python 标准库 unittest，不需要额外安装测试框架：

python -m unittest discover -s tests -v

现有测试覆盖：

测试文件	覆盖内容
test_config.py	默认配置、自定义输入、类型转换和非法网格数
test_grid.py	网格形状、间距、坐标方向和稳定时间步
test_initial_conditions.py	四周边界、双热斑位置和温度场对称性
test_solver.py	恒温场、输入保护、解析解精度和稳定性异常

在 VS Code 中，可以选择左侧“测试”视图并配置：

测试框架：unittest
测试目录：tests
文件模式：test_*.py

在代码中调用

除了交互式入口，也可以直接调用各个数值模块：

import numpy as np

from heat2d import SimulationConfig, solve
from heat2d.grid import create_grid
from heat2d.initial_conditions import initial_temperature

config = SimulationConfig()

X, Y, dx, dy, dt = create_grid(
    config.x_length,
    config.nx,
    config.y_length,
    config.ny,
    config.alpha,
)

temperature = initial_temperature(config.sigma, X, Y)
times = np.linspace(0, config.time, config.frames)

history = solve(
    temperature,
    times,
    config.alpha,
    dt,
    dx,
    dy,
)

history 是一个温度数组列表，每个元素对应 times 中的一个输出时刻，数组形状为 (ny, nx)。

结果解释

动画颜色表示平板各位置的温度：

• 初始时刻，平板中线左右两侧各有一个约 $300\,^\circ\mathrm{C}$ 的宽高温区域；
• 随时间推进，两个热斑向周围扩散并逐渐融合；
• 四条边始终保持在 $20\,^\circ\mathrm{C}$；
• 在没有内部热源的情况下，整个区域最终趋近边界温度。

增大 alpha 会加快温度扩散；增大 sigma 会扩大初始高温区域；增加网格节点数会提高空间分辨率，但也会减小稳定时间步并增加计算量。

模型假设与局限

当前模型采用以下假设：

• 材料均匀且各向同性；
• 热扩散率不随位置和温度变化；
• 平板内部没有热源；
• 不考虑对流边界和辐射换热；
• 四条边使用相同的固定温度；
• 使用显式时间推进，细网格下需要较多时间步；
• 当前实现保存全部动画帧，超大网格可能占用较多内存。

因此，本项目适合教学、算法验证和中小规模模拟，不应直接用于未经验证的工程安全计算。

后续改进方向

• 将边界温度、初始峰值温度加入配置；
• 支持不同边界上的独立温度条件；
• 增加绝热、对流和周期边界条件；
• 支持位置或温度相关的材料参数；
• 增加内部热源项；
• 实现隐式格式或 Crank–Nicolson 方法；
• 支持保存 GIF、MP4、图片和数值结果；
• 增加命令行参数和配置文件输入；
• 增加收敛性分析、性能测试和测试覆盖率报告。

常见问题

提示缺少 NumPy 或 Matplotlib

请确认使用了正确的 Python 解释器，并在项目根目录执行：

python -m pip install -e .

执行 python -m heat2d 时找不到模块

请确认终端当前目录是包含 pyproject.toml 和 heat2d/ 的项目根目录，或者先执行可编辑安装。

动画窗口没有出现

请确认当前环境支持图形界面，并且 Matplotlib 使用的是交互式后端。在无图形界面的服务器环境中，可以扩展程序，将动画保存为文件。

网格越细是否一定越好

更细的网格通常能提高空间精度，但显式格式的稳定时间步会随网格间距平方减小，因此计算量会快速增加。建议结合解析解或网格收敛性测试选择合适的分辨率。