sunpy

用途

SunPy 是社区开发、免费且开源的太阳物理学软件包，用于太阳物理数据分析。它构建在 Astropy 生态之上，并扩展了太阳物理学家所需的功能。

适用场景包括：

从 VSO、JSOC 及其他存档搜索和下载太阳数据。
可视化太阳图像（EUV、磁图、白光）。
在不同太阳坐标框架之间转换坐标（例如 Stonyhurst 到 Helioprojective）。
分析太阳时间序列数据（GOES X 射线通量、太阳黑子数）。
校正太阳差动自转。
叠加不同仪器的数据（例如 AIA 与 HMI）。
在日面上进行边缘拟合与特征追踪。

主要能力与核心原则

Map 对象：二维空间数据的主要数据结构，将图像数组与元数据（FITS 头）和坐标参考系（WCS）结合，支持物理上准确的绘图与裁剪。

太阳坐标：太阳物理使用许多非笛卡尔框架。SunPy 处理将三维太阳位置投影到二维望远镜平面的数学运算，并考虑地球相对于太阳的位置。

Fido（Federated IDO）：统一的数据搜索接口。定义所需条件（时间、仪器、波长），Fido 会自动跨不同提供方查找。

TimeSeries：用于处理光变曲线。

太阳物理算法：包括边缘拟合与日面数学（如 all_coordinates_is_on_disk）。

性能优化：支持降采样预览（resample）和并行下载（Fido.fetch 的 max_conn 参数）。

使用方式

安装：

pip install "sunpy[all]"

标准导入：

import sunpy.map
import sunpy.coordinates
from sunpy.net import Fido, attrs as a
import astropy.units as u
from astropy.coordinates import SkyCoord

基本模式 — 搜索、下载与绘图：

from sunpy.net import Fido, attrs as a
import sunpy.map

# 1. 搜索数据
result = Fido.search(a.Time("2011/06/07 06:30", "2011/06/07 06:35"),
                     a.Instrument.aia,
                     a.Wavelength(171*u.angstrom))

# 2. 下载（返回文件路径列表）
# downloaded_files = Fido.fetch(result)

# 3. 创建并绘图
# aiayamap = sunpy.map.Map(downloaded_files[0])
# aiayamap.peek()

太阳地图（sunpy.map）操作与可视化：支持坐标感知绘图、绘制边缘、绘制网格、地图加减等。地图加减要求共享相同 WCS。

太阳坐标（sunpy.coordinates）框架转换：支持 Helioprojective、Heliographic Stonyhurst 等框架，以及使用差动自转旋转坐标（solar_rotate_coordinate）。

数据搜索（sunpy.net.Fido）复杂查询：支持组合查询，如同时搜索 GOES X 射线耀斑与 AIA 图像，使用逻辑运算符组合条件。

时间序列（sunpy.timeseries）：加载 GOES 数据、绘图、导出为 Pandas DataFrame 并进行滚动平均。

关键规则

推荐做法：

使用 sunpy.map.Map，这是处理具有正确坐标元数据的太阳图像的唯一可靠方式。
使用物理单位，波长、距离和时间始终使用 astropy.units。
检查观测者信息，确保地图头具有有效的观测者元数据。
规范化地图，比较图像时使用 map.plot(norm=...) 或 aiamap.exposure_time 考虑不同曝光时间。
矢量化坐标转换，SkyCoord 数组比单点快得多。
使用 Fido 下载，它可以处理重试、本地缓存和多个提供方。

避免做法：

不要用原始 plt.imshow 绘图，这会忽略世界坐标系（WCS），应使用 ax = plt.subplot(projection=my_map)。
不要忽略时间尺度，注意 UTC 与 TAI 的区别。
不要硬编码波长，使用 a.Wavelength(193 * u.AA) 确保搜索单位感知。
不要手动裁剪，不要切片 numpy 数组，应使用 my_map.submap(bottom_left, top_right) 以保留坐标元数据。

反模式（切勿）：

不要按像素索引手动裁剪，会丢失坐标。应使用 SkyCoord 和 submap。
不要硬编码太阳半径或距离。应从地图或常量获取，如 my_map.dsun。

适用场景与工作流

多仪器叠加分析（AIA 与 HMI）：将 HMI 重投影到 AIA 视角，叠加 HMI 等值线（磁场）于 AIA（热等离子体）图像上。

测量耀斑通量演化：从时间序列文件截取耀斑窗口，获取峰值时间和通量。

图像序列差动自转校正：将一系列地图旋转到参考时间（注意：基本旋转与太阳表面差动自转不同，后者需使用 differential_rotation 模块）。

性能优化：

大 AIA 图像（4096x4096）绘图慢，可降采样（resample）。
Fido.fetch 可使用多连接加速下载（max_conn=5）。

常见陷阱与解决方案

“缺少观测者”错误：计算失败因为 SunPy 不知道卫星位置。可在 FITS 头缺失时手动设置观测者（使用 get_body_heliographic_stonyhurst）。

方向问题（北不在上）：太阳望远镜会旋转。可使用 aia_map.rotate() 将太阳北与 Y 轴对齐。

搜索结果为空：提供方可能宕机，应始终检查结果长度，若为空则抛出错误。

限制与说明

本文档未提供 SunPy 的具体版本号、系统要求、收费模式（描述为免费开源）、支持的数据源完整列表、全部功能模块清单等。部分功能（如差动自转校正的具体实现细节）需参考官方文档。

参考文档：

官方文档：https://docs.sunpy.org/
SunPy Gallery：https://docs.sunpy.org/en/stable/generated/gallery/index.html
搜索模式：sunpy.map.Map、sunpy.net.Fido、sunpy.coordinates.frames、sunpy.timeseries

SunPy 是探索离我们最近的恒星动力学的权威工具包。通过整合物理单位和太阳专用坐标系，它支持稳健且可复现的日球层物理研究。