Python IGRF 库本地环境配置与使用指南

✅ 验证方法

# 进入项目目录
cd igrf
# 查看文件结构
ls -la # Linux/macOS
dir # Windows
# 应看到以下关键文件：
# - README.md 项目说明
# - pyproject.toml 项目配置
# - setup.py 安装脚本
# - src/igrf/ 源代码目录

2.2 方法二：下载 ZIP 压缩包

🎯 目标

无需 Git 工具，直接下载项目压缩包（适合网络受限环境）。

📝 执行步骤

1. 访问项目主页
   打开浏览器，访问：https://github.com/space-physics/igrf
2. 下载 ZIP 包
   点击绿色按钮 Code → 选择 Download ZIP

重命名文件夹（可选）

# 将 igrf-main 重命名为 igrf
mv igrf-main igrf # Linux/macOS
ren igrf-main igrf # Windows

解压文件

# 将下载的 igrf-main.zip 解压到项目目录
# Windows: 右键 → 解压到当前文件夹
# Linux/macOS: unzip igrf-main.zip

✅ 验证方法

cd igrf
ls README.md # 应显示文件存在

2.3 方法对比与选择建议

推荐策略：

• 学习/开发场景：使用 Git 克隆（方法一）
• 快速验证/演示：使用 ZIP 下载（方法二）

3. 创建 Python 虚拟环境

3.1 检查 Python 版本

🎯 目标

确认系统 Python 版本满足项目要求（IGRF 需要 Python ≥ 3.8）。

📝 执行命令

# 检查 Python 版本
python --version
# 或 python3 --version
# 预期输出示例：
# Python 3.12.0

如果显示版本低于 3.8：

• Windows: 访问 https://www.python.org/downloads/ 下载最新版
• Linux: sudo apt install python3.12 (Ubuntu/Debian)
• macOS: brew install [email protected]

3.2 使用 venv 创建虚拟环境

🎯 目标

在项目目录下创建独立的 Python 虚拟环境。

📝 执行命令

# 确保在项目根目录
cd D:\Projects\igrf # 替换为您的实际路径
# 创建虚拟环境（名为 .venv）
python -m venv .venv
# 或指定 Python 版本（如系统有多个 Python）
python3.12 -m venv .venv

🔍 命令参数详解

python -m venv [OPTIONS]
ENV_DIR 参数说明：
-m venv 调用 Python 内置的 venv 模块
ENV_DIR 虚拟环境目录名（推荐用 .venv 或 venv）
可选参数：
--system-site-packages 允许访问全局包（不推荐）
--clear 清除已存在的环境重新创建
--upgrade 升级环境中的 pip/setuptools
--without-pip 不安装 pip（极少使用）
--prompt PROMPT 自定义命令行提示符前缀

命名建议：

• .venv - 以点开头，隐藏文件夹（推荐）
• venv - 常规文件夹
• env - 简短命名

✅ 验证方法

# Windows
dir .venv
# 应看到以下目录结构：
# .venv\
# ├── Scripts\ # Windows 的可执行文件目录
# │ ├── python.exe
# │ ├── pip.exe
# │ └── activate.bat
# ├── Lib\
# │ └── site-packages\
# └── pyvenv.cfg # 配置文件

# Linux/macOS
ls -la .venv
# 应看到：
# .venv/
# ├── bin/ # Unix 的可执行文件目录
# │ ├── python
# │ ├── pip
# │ └── activate
# ├── lib/
# │ └── python3.x/
# └── pyvenv.cfg

3.3 虚拟环境目录结构解析

.venv/
│── pyvenv.cfg # 配置文件（记录 Python 路径和版本）
│── Scripts/ (Windows) # 可执行文件目录
│   ├── python.exe # 虚拟环境的 Python 解释器
│   ├── pip.exe # 包管理工具
│   ├── activate # 激活脚本（多种 shell 版本）
│   ├── activate.bat # Windows cmd 激活脚本
│   ├── Activate.ps1 # PowerShell 激活脚本
│   └── deactivate.bat # 退出脚本
└── Lib/ (Windows) 或 lib/ (Unix)
    └── site-packages/ # 安装包存放目录
        └── pip/ # 默认包含 pip

核心文件说明：

• pyvenv.cfg：记录基础 Python 路径，确保虚拟环境独立性
• Scripts/python.exe：虚拟环境专属的 Python 解释器副本
• site-packages/：所有 pip 安装的包都存储在这里

4. 激活虚拟环境（跨平台）

4.1 为什么需要激活？

激活虚拟环境的本质：修改环境变量，让系统优先使用虚拟环境的 Python 和包。

激活前后对比：

4.2 Windows 系统激活

方式一：PowerShell（推荐）

# 激活虚拟环境
.\.venv\Scripts\Activate.ps1
# 如遇到执行策略限制，执行以下命令后重试：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

成功标志：命令行前缀显示 (.venv)

(.venv)PS D:\Projects\igrf>

方式二：命令提示符（cmd）

# 激活虚拟环境
.venv\Scripts\activate.bat
# 成功标志
(.venv) D:\Projects\igrf>

方式三：Git Bash

source .venv/Scripts/activate

4.3 Linux/macOS 系统激活

# 激活虚拟环境
source .venv/bin/activate
# 或使用点命令（等效）
. .venv/bin/activate
# 成功标志
(.venv) user@hostname:~/Projects/igrf$

4.4 验证激活状态

✅ 验证方法

# 方法 1：检查 Python 路径
which python # Linux/macOS
where python # Windows
# 应指向虚拟环境路径：
# D:\Projects\igrf\.venv\Scripts\python.exe (Windows)
# /home/user/Projects/igrf/.venv/bin/python (Linux)

# 方法 2：检查 pip 路径
which pip # Linux/macOS
where pip # Windows

# 方法 3：查看已安装包（应该很少）
pip list
# 输出：
# Package Version
# ---------- -------
# pip 23.x.x
# setuptools 65.x.x

4.5 退出虚拟环境

# 所有平台通用
decorate
# 命令行前缀的 (.venv) 消失
# 系统恢复使用全局 Python

5. 安装项目依赖

5.1 升级 pip（重要步骤）

🎯 目标

确保使用最新版本的 pip，避免依赖安装失败。

📝 执行命令

# 确保虚拟环境已激活（命令行显示 .venv 前缀）
# 升级 pip 到最新版
python -m pip install --upgrade pip
# 预期输出：
# Successfully installed pip-24.0

5.2 安装 IGRF 项目依赖

方式一：从 pyproject.toml 自动安装（推荐）

# 以开发模式安装项目
python -m pip install -e .
# 参数说明：
# -e editable 模式，源码修改立即生效
# . 当前目录（包含 pyproject.toml）

执行过程说明：

Obtaining file:///D:/Projects/igrf
Installing build dependencies ... done
Getting requirements to build wheel ... done
Preparing metadata ... done
Installing collected packages: numpy, xarray, python-dateutil, pandas, igrf
Running setup.py develop for igrf
Successfully installed igrf numpy-1.26.4 xarray-2024.1.0 pandas-2.2.0

方式二：从 requirements.txt 安装

Step 1：检查是否有 requirements.txt

ls requirements.txt # Linux/macOS
dir requirements.txt # Windows

Step 2：如有该文件，执行安装

pip install -r requirements.txt
# 参数说明：
# -r 从文件读取依赖列表
# requirements.txt 依赖配置文件

方式三：手动安装关键依赖

如果项目没有配置文件，根据 README 手动安装：

# IGRF 的核心依赖
pip install numpy xarray pandas python-dateutil
# 如需可视化功能
pip install matplotlib
# 如需测试功能
pip install pytest

5.3 特殊依赖：编译 Fortran 模块

IGRF 项目包含 Fortran 代码，需要 gfortran 编译器。

🎯 目标

安装并配置 gfortran，编译 IGRF 的 Fortran 核心模块。

📝 安装 gfortran

Windows 系统：

# 方法 1：使用 MinGW-w64
# 1. 访问 https://www.mingw-w64.org/downloads/#
# 2. 下载 x86_64-posix-seh 版本
# 3. 解压到 C:\mingw64
# 4. 添加到 PATH 环境变量：
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\mingw64\bin", [System.EnvironmentVariableTarget]::User )
# 验证安装
gfortran --version

Linux 系统：

# Ubuntu/Debian
sudo apt update
sudo apt install gfortran
# CentOS/RHEL
sudo yum install gcc-gfortran
# 验证
gfortran --version

macOS 系统：

# 使用 Homebrew
brew install gcc
# 验证
gfortran --version

📝 编译 IGRF Fortran 模块

# 在 Python 中执行构建
python -c "import igrf; igrf.build()"
# 或使用 CMake 手动构建
cd src/igrf
cmake -S. -Bbuild -G "MinGW Makefiles" # Windows
cmake -S. -Bbuild # Linux/macOS
cmake --build build

成功标志：

[100%] Built target igrf13_driver

5.4 处理 MinGW DLL 依赖（Windows 特有）

🎯 问题

Windows 下编译的 Fortran 可执行文件需要 MinGW 运行时 DLL。

📝 解决方案

# 复制必要的 DLL 到项目目录
$sourceDir = "C:\mingw64\bin"
$targetDir = "src\igrf"
Copy-Item "$sourceDir\libgfortran-5.dll" $targetDir
Copy-Item "$sourceDir\libquadmath-0.dll" $targetDir
Copy-Item "$sourceDir\libgcc_s_seh-1.dll" $targetDir
Copy-Item "$sourceDir\libwinpthread-1.dll" $targetDir

✅ 验证方法

# 测试 IGRF 功能
python -c "import igrf; print('IGRF 加载成功')"
# 应输出：IGRF 加载成功（无报错）

5.5 查看已安装包

# 列出所有已安装的包
pip list
# 预期输出示例：
# Package Version
# --------------- -------
# igrf 13.0.2
# numpy 1.26.4
# pandas 2.2.0
# python-dateutil 2.8.2
# xarray 2024.1.0
# ...

# 显示包的详细信息
pip show igrf
# 输出：
# Name: igrf
# Version: 13.0.2
# Summary: International Geomagnetic Reference Field
# Home-page: https://github.com/space-physics/igrf
# Location: D:\Projects\igrf\src
# Requires: numpy, xarray, python-dateutil

5.6 导出依赖列表（可选）

# 生成 requirements.txt
pip freeze > requirements.txt
# 查看生成的文件
cat requirements.txt # Linux/macOS
type requirements.txt # Windows
# 内容示例：
# igrf @ file:///D:/Projects/igrf
# numpy==1.26.4
# pandas==2.2.0
# python-dateutil==2.8.2
# xarray==2024.1.0

用途：在其他机器上快速重建相同环境

pip install -r requirements.txt

6. 运行项目与功能验证

6.1 基础功能测试

🎯 目标

验证 IGRF 库能正确计算地磁场数据。

📝 测试脚本

创建测试文件 test_igrf.py：

""" IGRF-13 地磁场计算测试脚本
测试目标：验证库安装成功并能正确计算磁场
"""
from datetime import datetime
import igrf

def test_equator():
    """测试用例 1：赤道位置（0°N, 0°E, 海平面）"""
    print("="*60)
    print("测试用例 1：赤道位置")
    print("="*60)
    date = datetime(2020, 1, 1)
    glat = 0.0 # 纬度
    glon = 0.0 # 经度
    alt_km = 0.0 # 海拔高度 (km)
    # 调用 IGRF 计算
    mag = igrf.igrf(date, glat=glat, glon=glon, alt_km=alt_km)
    # 提取结果
    B_north = float(mag['north'].values[0])
    B_east = float(mag['east'].values[0])
    B_down = float(mag['down'].values[0])
    B_total = float(mag['total'].values[0])
    incl = float(mag['incl'].values[0])
    decl = float(mag['decl'].values[0])
    # 显示结果
    print(f"输入参数：")
    print(f" 日期：{date}")
    print(f" 位置：{glat}°N, {glon}°E, {alt_km} km")
    print(f"\n计算结果：")
    print(f" 北向分量 (B_north): {B_north:10.2f} nT")
    print(f" 东向分量 (B_east): {B_east:10.2f} nT")
    print(f" 垂直分量 (B_down): {B_down:10.2f} nT")
    print(f" 总场强 (|B|): {B_total:10.2f} nT")
    print(f" 磁倾角 (Incl): {incl:10.4f}°")
    print(f" 磁偏角 (Decl): {decl:10.4f}°")
    # 验证结果合理性
    assert 30000 < B_total < 35000, "赤道磁场强度异常"
    print("\n✓ 测试通过：磁场强度在预期范围内")

def test_north_pole():
    """测试用例 2：北极（90°N）"""
    print("\n"+"="*60)
    print("测试用例 2：北极位置")
    print("="*60)
    date = datetime(2020, 1, 1)
    mag = igrf.igrf(date, glat=90.0, glon=0.0, alt_km=0.0)
    B_total = float(mag['total'].values[0])
    print(f"北极磁场总强度：{B_total:10.2f} nT")
    assert 55000 < B_total < 60000, "北极磁场强度异常"
    print("✓ 测试通过")

def test_leo_orbit():
    """测试用例 3：LEO 轨道（45°N, 500km 高度）"""
    print("\n"+"="*60)
    print("测试用例 3：LEO 卫星轨道")
    print("="*60)
    date = datetime(2020, 1, 1)
    mag = igrf.igrf(date, glat=45.0, glon=0.0, alt_km=500.0)
    B_total = float(mag['total'].values[0])
    print(f"LEO 轨道 (500km) 磁场强度：{B_total:10.2f} nT")
    assert 20000 < B_total < 25000, "LEO 轨道磁场强度异常"
    print("✓ 测试通过")

def test_time_series():
    """测试用例 4：时间序列（年变率验证）"""
    print("\n"+"="*60)
    print("测试用例 4:2020-2025 年时间序列")
    print("="*60)
    print(f"{'年份':<8}{'总场强 (nT)':>12}")
    print("-"*22)
    for year in range(2020, 2026):
        date = datetime(year, 1, 1)
        mag = igrf.igrf(date, glat=0.0, glon=0.0, alt_km=0.0)
        B_total = float(mag['total'].values[0])
        print(f"{year:<8}{B_total:>12.2f}")
    print("✓ 测试通过：时间序列计算正常")

if __name__ == "__main__":
    print("\n"+"="*60)
    print("IGRF-13 功能验证测试套件")
    print("="*60)
    try:
        test_equator()
        test_north_pole()
        test_leo_orbit()
        test_time_series()
        print("\n"+"="*60)
        print("✓✓✓ 所有测试通过！IGRF 库安装成功 ✓✓✓")
        print("="*60)
    except Exception as e:
        print(f"\n✗ 测试失败：{e}")
        print("请检查库安装是否完整")

📝 运行测试

# 确保虚拟环境已激活
python test_igrf.py

✅ 预期输出

============================================================
IGRF-13 功能验证测试套件
============================================================
============================================================
测试用例 1：赤道位置
============================================================
输入参数：
 日期：2020-01-01 00:00:00
 位置：0.0°N, 0.0°E, 0.0 km
计算结果：
 北向分量 (B_north): 27540.01 nT
 东向分量 (B_east): -2242.11 nT
 垂直分量 (B_down): -16012.40 nT
 总场强 (|B|): 31935.50 nT
 磁倾角 (Incl): -30.0925°
 磁偏角 (Decl): -4.6543°
✓ 测试通过：磁场强度在预期范围内
============================================================
测试用例 2：北极位置
============================================================
北极磁场总强度：56756.03 nT
✓ 测试通过
============================================================
测试用例 3：LEO 卫星轨道
============================================================
LEO 轨道 (500km) 磁场强度：37235.51 nT
✗ 测试失败：LEO 轨道磁场强度异常
请检查库安装是否完整

注意：测试用例 3 的阈值可能需要根据实际情况调整。

6.2 交互式验证

# 启动 Python 交互式环境
python
# 执行以下命令：
>>> from datetime import datetime
>>> import igrf
>>>
# 计算北京上空磁场（2024 年）
>>> mag = igrf.igrf(datetime(2024, 1, 1), glat=39.9, glon=116.4, alt_km=0)
>>>
# 查看结果
>>> print(mag)
<xarray.Dataset> Dimensions: (alt_km: 1) Coordinates: * alt_km (alt_km) float64 0.0 Data variables: north (alt_km) float64 3.081e+04 east (alt_km) float64 -1.095e+03 down (alt_km) float64 4.406e+04 total (alt_km) float64 5.379e+04 incl (alt_km) float64 55.02 decl (alt_km) float64 -2.036 Attributes: time: 2024-01-01 00:00:00 glat: 39.9 glon: 116.4
>>>
# 退出 Python
>>> exit()

6.3 与 NOAA 官网数据对比验证

🎯 目标

使用 NOAA 官方计算器验证 IGRF 库输出的准确性。

📝 验证步骤

1. 访问 NOAA IGRF 在线计算器
   https://www.ngdc.noaa.gov/geomag/calculators/magcalc.shtml
2. 输入相同参数
   • Model: IGRF-13
   • Date: 2020-01-01
   • Latitude: 0°
   • Longitude: 0°
   • Altitude: 0 km

对比结果

结论：误差<0.1 nT，验证通过✓

7. 常见问题解决方案

7.1 虚拟环境相关问题

问题 1：PowerShell 激活失败

错误信息：

.\.venv\Scripts\Activate.ps1 : 无法加载文件，因为在此系统上禁止运行脚本

原因：Windows PowerShell 执行策略限制

解决方案：

# 以管理员身份运行 PowerShell，执行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 或临时绕过：
PowerShell -ExecutionPolicy Bypass -File .venv\Scripts\Activate.ps1

问题 2：虚拟环境激活后 Python 路径仍指向全局

检查方法：

where python # Windows
which python # Linux/macOS

原因：PATH 环境变量顺序问题

解决方案：

# 退出当前环境
decorate
# 删除虚拟环境重建
rm -rf .venv # Linux/macOS
rmdir /s .venv # Windows
# 重新创建
python -m venv .venv --clear
# 重新激活
source .venv/bin/activate # Linux/macOS
.\.venv\Scripts\Activate.ps1 # Windows PowerShell

7.2 依赖安装问题

问题 3：pip install 失败，提示网络超时

错误信息：

ERROR: Could not install packages due to an EnvironmentError: HTTPSConnectionPool: Read timed out.

解决方案 A：使用国内镜像

# 临时使用清华镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple igrf
# 永久配置镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 其他可用镜像：
# 阿里云：https://mirrors.aliyun.com/pypi/simple/#
# 腾讯云：https://mirrors.cloud.tencent.com/pypi/simple/#
# 豆瓣：https://pypi.douban.com/simple/

解决方案 B：使用代理

# Windows (cmd)
set http_proxy=http://127.0.0.1:7890
set https_proxy=http://127.0.0.1:7890
# Linux/macOS
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
# 然后正常安装
pip install igrf

问题 4：NumPy 版本冲突

错误信息：

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
xarray 2024.1.0 requires numpy>=1.23, but you have numpy 2.2.0 which is incompatible.

解决方案：

# 卸载冲突的 NumPy
pip uninstall numpy
# 安装兼容版本
pip install "numpy>=1.23,<2.0"
# 或锁定具体版本
pip install numpy==1.26.4

问题 5：编译 Fortran 模块失败

错误信息：

CMake Error: CMake was unable to find a build program corresponding to "MinGW Makefiles".

原因：缺少 gfortran 或 CMake

解决方案：

Step 1：安装 gfortran

# Windows: 下载 MinGW-w64
# https://sourceforge.net/projects/mingw-w64/files/#
# Linux (Ubuntu/Debian)
sudo apt install gfortran
# macOS
brew install gcc

Step 2：安装 CMake

# Windows winget install Kitware.CMake
# Linux (Ubuntu/Debian)
sudo apt install cmake
# macOS
brew install cmake

Step 3：重新构建

python -c "import igrf; igrf.build()"

7.3 Windows 特有问题

问题 6：运行时报错 IGRF13 error code 3221225781

错误信息：

>>> import igrf
>>> mag = igrf.igrf(...)
RuntimeError: IGRF13 error code 3221225781

原因：缺少 MinGW 运行时 DLL

解决方案：

# 复制 MinGW DLL 到 IGRF 目录
$mingw_bin = "C:\mingw64\bin"
$igrf_dir = "D:\Projects\igrf\src\igrf"
Copy-Item "$mingw_bin\libgfortran-5.dll" $igrf_dir
Copy-Item "$mingw_bin\libquadmath-0.dll" $igrf_dir
Copy-Item "$mingw_bin\libgcc_s_seh-1.dll" $igrf_dir
Copy-Item "$mingw_bin\libwinpthread-1.dll" $igrf_dir
# 验证
python -c "import igrf; print('成功')"

7.4 权限问题

问题 7：pip install 提示权限不足

错误信息：

ERROR: Could not install packages due to an OSError: [WinError 5] 拒绝访问。

解决方案：

# 方法 1：安装到用户目录（不推荐，会污染全局环境）
pip install --user igrf
# 方法 2：使用虚拟环境（强烈推荐）
# 虚拟环境无需管理员权限
python -m venv .venv
# 激活后安装
pip install igrf

7.5 诊断工具

快速诊断脚本

创建 diagnose.py：

""" 环境诊断脚本
检查 Python 环境、虚拟环境、依赖包状态
"""
import sys
import subprocess

def check_python():
    print("=== Python 版本检查 ===")
    print(f"Python 版本：{sys.version}")
    print(f"Python 路径：{sys.executable}")
    print(f"虚拟环境：{'是' if hasattr(sys,'real_prefix') or (hasattr(sys,'base_prefix') and sys.base_prefix != sys.prefix) else '否'}")
    print()

def check_pip():
    print("=== pip 版本检查 ===")
    result = subprocess.run([sys.executable,"-m","pip","--version"], capture_output=True, text=True)
    print(result.stdout)

def check_packages():
    print("=== 关键依赖检查 ===")
    packages = ['numpy','xarray','pandas','igrf']
    for pkg in packages:
        try:
            module = __import__(pkg)
            version = getattr(module,'__version__','未知')
            print(f"✓ {pkg:15s}{version}")
        except ImportError:
            print(f"✗ {pkg:15s} 未安装")
    print()

def check_igrf():
    print("=== IGRF 功能检查 ===")
    try:
        import igrf
        from datetime import datetime
        mag = igrf.igrf(datetime(2020,1,1), glat=0, glon=0, alt_km=0)
        total = float(mag['total'].values[0])
        print(f"✓ IGRF 计算正常")
        print(f" 测试结果：赤道磁场强度 = {total:.2f} nT")
    except Exception as e:
        print(f"✗ IGRF 计算失败：{e}")
    print()

if __name__ == "__main__":
    print("\n"+"="*60)
    print("Python 环境诊断工具")
    print("="*60+"\n")
    check_python()
    check_pip()
    check_packages()
    check_igrf()
    print("="*60)
    print("诊断完成")
    print("="*60)

运行诊断：

python diagnose.py

8. 最佳实践与进阶建议

8.1 项目结构建议

推荐的项目组织方式：

my_igrf_project/
│── .venv/ # 虚拟环境（不提交到 Git）
│── src/ # 源代码
│   ├── __init__.py
│   └── magnetic_field.py
│── tests/ # 测试代码
│   └── test_igrf.py
│── data/ # 数据文件
│   └── results.csv
│── notebooks/ # Jupyter 笔记本
│   └── analysis.ipynb
│── docs/ # 文档
│   └── usage.md
│── .gitignore # Git 忽略文件
│── requirements.txt # 依赖列表
│── README.md # 项目说明
└── setup.py # 安装脚本（可选）

.gitignore 示例：

# 虚拟环境
.venv/
venv/
env/
# Python 缓存
__pycache__/
*.py[cod]
*$py.class
# IDE 配置
.vscode/
.idea/
*.swp
# 数据文件
*.csv
*.h5
data/output/
# 日志文件
*.log
# 操作系统
.DS_Store
Thumbs.db

8.2 依赖管理进阶

使用 pip-tools 锁定依赖

# 安装 pip-tools
pip install pip-tools
# 创建 requirements.in（只列出直接依赖）
echo "igrf" > requirements.in
# 生成 requirements.txt（包含所有间接依赖及版本）
pip-compile requirements.in
# 安装锁定版本
pip-sync requirements.txt

使用 Poetry（现代化工具）

# 安装 Poetry
pip install poetry
# 初始化项目
poetry init
# 添加依赖
poetry add igrf
# 创建虚拟环境并安装
poetry install
# 激活环境
poetry shell

8.3 虚拟环境管理工具

virtualenvwrapper（简化管理）

# 安装
pip install virtualenvwrapper-win # Windows
pip install virtualenvwrapper # Linux/macOS
# 配置（添加到 ~/.bashrc 或 ~/.zshrc）
export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh
# 使用
mkvirtualenv igrf_env # 创建环境
workon igrf_env # 激活环境
decorate # 退出环境
rmvirtualenv igrf_env # 删除环境
lsvirtualenv # 列出所有环境

conda（科学计算推荐）

# 创建环境
conda create -n igrf_env python=3.12
# 激活
conda activate igrf_env
# 安装依赖
conda install numpy xarray pandas
pip install igrf
# 导出环境
conda env export > environment.yml
# 从配置文件创建环境
conda env create -f environment.yml

8.4 持续集成（CI/CD）

GitHub Actions 示例配置

创建 .github/workflows/test.yml：

name: Test IGRF Installation
on: [push, pull_request]
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e .
      - name: Test IGRF
        run: |
          python test_igrf.py

8.5 性能优化建议

批量计算优化

import numpy as np
from datetime import datetime
import igrf

# 低效方式：循环调用
latitudes = np.arange(-90, 91, 10)
results = []
for lat in latitudes:
    mag = igrf.igrf(datetime(2020, 1, 1), glat=lat, glon=0, alt_km=0)
    results.append(mag['total'].values[0])

# 高效方式：使用 grid 方法（如果支持）
try:
    mag_grid = igrf.grid(
        datetime(2020, 1, 1),
        glat=latitudes,
        glon=np.array([0]),
        alt_km=np.array([0]))
    results = mag_grid['total'].values
except:
    # 降级到循环方式
    pass

8.6 学习资源推荐

官方文档

• IGRF 项目主页：https://github.com/space-physics/igrf
• IGRF 官方说明：https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html
• Python 虚拟环境文档：https://docs.python.org/3/library/venv.html

进阶学习

• Xarray 教程：https://tutorial.xarray.dev/
• NumPy 文档：https://numpy.org/doc/
• 地磁学基础：参考 Alken et al. (2021), Earth Planets Space, 73:49

相关工具

• pyIGRF：另一个 IGRF Python 实现（纯 Python，无需编译）
• SpacePy：空间物理 Python 工具集
• SunPy：太阳物理分析库

9. 总结与检查清单

9.1 完整流程回顾

1. Git 克隆/ZIP 下载
2. 项目目录
3. 创建虚拟环境
4. 激活环境
5. 升级 pip
6. 安装依赖
7. 编译 Fortran 模块
8. 功能测试
9. 部署使用

9.2 环境配置检查清单

在开始开发前，确认以下项目：

• Python 版本 ≥ 3.8
• 虚拟环境已创建（目录存在 .venv/）
• 虚拟环境已激活（命令行显示 (.venv) 前缀）
• pip 已升级到最新版
• 项目依赖已安装（pip list 显示 igrf）
• gfortran 编译器已安装（gfortran --version 可执行）
• Fortran 模块已编译（igrf.build() 成功）
• Windows 用户已复制 MinGW DLL
• 基础功能测试通过（python test_igrf.py 无报错）
• 已创建 .gitignore 文件（虚拟环境不提交到 Git）
• 已导出 requirements.txt（便于环境复现）

9.3 核心命令速查表

9.4 故障排查流程图

graph TD
A[遇到问题] --> B[运行诊断脚本 diagnose.py]
B --> C{Python 版本正确？}
C -- 否 --> D[安装 Python 3.8+]
C -- 是 --> E{虚拟环境激活？}
E -- 否 --> F[重新激活或重建虚拟环境]
E -- 是 --> G{依赖包安装？}
G -- 否 --> H[pip install -e . 或检查网络/镜像]
G -- 是 --> I{Fortran 模块编译？}
I -- 否 --> J[安装 gfortran 和 CMake，运行 igrf.build()]
I -- 是 --> K{Windows DLL 问题？}
K -- 是 --> L[复制 MinGW DLL 到 igrf 目录]
K -- 否 --> M[查看详细错误日志]
M --> N[搜索 GitHub Issues 或提交新 Issue]