简介：GCAM-Core 是全球变化分析模型（Global Change Analysis Model）的源码资源，由联合全球变化研究所（JGCRI）主导开发并长期维护，面向能源、气候、经济、土地利用、水资源等领域的科研人员与综合评估建模学习者。它在一个统一的经济框架内耦合人类活动与自然系统，可用于探索温室气体减排政策、国际协议对能源系统及土地覆盖的连锁影响，适合具备一定 C++ 基础、从事人地系统耦合研究的中高级用户。资源以 zip 压缩包形式提供，整体约 114.08MB，文件类型涵盖 C++ 源码、模型配置与输入数据等，便于本地编译与二次开发。目前已有 2295 人学习下载，说明其在综合评估社区中具有较高关注度。借助该模型，读者可深入理解部门间交互机制、复现典型气候情景，并基于源码开展人为决策成分与地球系统模型的集成分析，为政策评估与学术研究提供可扩展的工具基础。

1. GCAM 全球变化分析模型：一个把能源、气候、经济、水土全串起来的 C++ 集成评估引擎

如果你只做单一领域的模型，比如纯电力系统优化或者纯土地利用变化模拟，那 GCAM 可能不是你的第一选择。但如果你需要回答“碳税提高 50 美元后，2030 年全球土地利用怎么变、电力结构怎么调、农业用水涨多少”这类跨系统耦合问题，那 GCAM 就是绕不开的工具。它把能源、气候、经济、土地、水五个模块塞进同一个 C++ 求解框架里，用统一的价格信号驱动各模块联动。源码包解压后是一个完整的 CMake 工程，核心求解器、数据输入系统、场景配置全部开放。适合做 integrated-assessment 方向的研究生、政策模拟工程师，以及想拿它当底座做二次开发的团队。下面从跑通到改造，把这份源码拆开讲。

2. 架构拆解：五个模块怎么在一个 C++ 求解器里联动

2.1 模块划分与数据流

GCAM 的代码结构不是按“功能”切的，而是按“系统”切的。源码根目录下你会看到几个核心文件夹：cvs负责读取 XML 格式的输入数据，containers定义各模块的数据结构，functions放求解算法，util是基础工具。真正跑起来的时候，数据流是这样的：XML 数据库文件先被cvs解析成内存对象，然后functions里的市场求解器迭代出各商品（能源、农产品、水、碳）的均衡价格，最后reporting模块把结果写成 XML 或 CSV。

这个设计的好处是模块之间通过“价格-数量”信号耦合，而不是硬编码调用。比如电力模块算出电价，土地利用模块根据电价和碳价决定种什么，农业模块再根据土地价格算灌溉用水。你改任何一个模块的假设，其他模块会自动响应。

2.2 核心求解器：市场均衡怎么迭代

GCAM 的求解器在functions/supply_demand_curve.cpp和functions/market.cpp里。它用的是迭代式市场出清，不是一次性解一个巨大的优化问题。每个市场（比如“美国电力市场”“全球碳市场”）维护一个价格，求解器反复调用供给函数和需求函数，直到超额需求收敛到零附近。

// 简化后的市场迭代逻辑（基于源码结构重写） for (int iter = 0; iter < max_iterations; ++iter) { double total_supply = 0.0; double total_demand = 0.0; // 遍历该市场下所有供给方和需求方 for (auto& supplier : market.suppliers) { total_supply += supplier->getSupply(market.price); } for (auto& demander : market.demanders) { total_demand += demander->getDemand(market.price); } double excess = total_demand - total_supply; if (fabs(excess) < convergence_tolerance) { break; // 收敛，退出迭代 } // 价格调整：超额需求为正则涨价，为负则降价 market.price *= (1.0 + excess * price_adjustment_factor); }

这段逻辑的关键参数是convergence_tolerance和price_adjustment_factor。前者控制精度，默认在configuration.xml里设成 0.001 左右；后者控制迭代步长，设大了会震荡，设小了收敛慢。我一般会先把 tolerance 放宽到 0.01 跑通，再收紧到 0.001 出正式结果。

2.3 XML 输入系统：场景配置的入口

GCAM 的所有输入——基准年数据、技术成本曲线、政策假设——都写在 XML 文件里。cvs文件夹下的解析器负责把这些 XML 转成 C++ 对象。比如你要加一个碳税场景，不需要改代码，只需要在input/policy/下新建一个 XML：

<scenario name="carbon_tax_50"> <policy name="global_carbon_tax"> <ghgpolicy> <policy-name>global_carbon_tax</policy-name> <policy-type>carbon-tax</policy-type> <tax>50</tax> <!-- 单位：美元/吨碳 --> <start-year>2025</start-year> <end-year>2100</end-year> </ghgpolicy> </policy> </scenario>

这个 XML 被解析后，会在每个迭代步里给所有碳排放源加一个额外成本。注意tax的单位是美元/吨碳，不是二氧化碳，换算时乘 3.67。这个坑我踩过，第一次跑出来的减排量比预期大了三倍多。

2.4 编译与依赖：CMake 工程怎么配

源码包用 CMake 管理构建。依赖主要有三个：Boost（智能指针和文件系统）、Xerces-C++（XML 解析）、以及一个可选的 Java 运行时（用于部分报告生成脚本）。在 Ubuntu 上，依赖安装命令是：

sudo apt-get install cmake libboost-all-dev libxerces-c-dev default-jre

然后进源码目录编译：

mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j$(nproc)

编译产物是gcam.exe，放在build/下。第一次编译大概需要 10 到 15 分钟，取决于机器核数。如果报 Xerces 找不到，检查XERCES_INCLUDE_DIR和XERCES_LIBRARY这两个 CMake 变量，手动指定路径。

3. 跑通第一个场景：从配置到出结果的完整链路

3.1 配置文件结构

跑 GCAM 之前，先看exe/configuration.xml。这个文件定义了输入数据库路径、输出目录、求解器参数、要跑哪些场景。关键字段：

我一般会复制一份configuration.xml改成configuration_carbon_tax.xml，只改scenarioName和inputFile里引用的政策 XML，这样不同场景互不干扰。

3.2 运行命令与日志解读

运行命令很简单：

./gcam.exe -C configuration_carbon_tax.xml

-C指定配置文件。跑起来后终端会刷迭代日志，每行显示当前迭代次数、最大超额需求、以及哪个市场还没收敛。如果看到某个市场反复出现在日志里，说明那个市场的供给或需求函数有问题。常见的是价格弹性设得太大，导致价格在两步之间来回跳。

日志里还有一个关键指标叫NPV of total cost，这是全期总成本的净现值。如果这个值在迭代后期还在大幅波动，说明求解没稳定，结果不可信。

3.3 输出文件解析

跑完后输出目录下会生成几个文件：database_basexdb.xml是完整结果数据库，database_basexdb.csv是扁平化后的表格。CSV 文件可以直接用 Python 的 pandas 读：

import pandas as pd df = pd.read_csv('output/database_basexdb.csv') # 筛选 2030 年全球电力结构 elec_2030 = df[(df['year'] == 2030) & (df['region'] == 'global') & (df['sector'] == 'electricity')] print(elec_2030[['technology', 'output']])

输出里的output单位是 EJ（艾焦耳），换算成 TWh 要乘 277.78。这个换算关系在util/unit_conversion.cpp里有定义，改单位系统的时候要同步改这里。

3.4 常见运行失败与排查

第一次跑最容易遇到的是内存不够。GCAM 全量跑一次大概需要 8 到 16 GB 内存，如果机器只有 8 GB，建议先用-DCMAKE_BUILD_TYPE=Debug编译一个调试版，然后在配置里把maxIterations降到 50，先看能不能跑通前几十步。另一个常见问题是 XML 解析报错，通常是某个标签拼写错了或者层级不对。Xerces 的报错信息会给出行号，对着行号去查那个 XML 文件就行。

4. 避坑与排查：跑 GCAM 常翻车的五个地方

4.1 迭代不收敛，日志刷屏

现象：终端一直刷迭代日志，跑到maxIterations还没停，最后输出结果里很多市场是空的。

原因：通常是某个市场的价格调整因子设得太大，或者供给/需求函数在某个价格区间内不连续。GCAM 里有些技术有“最小运行规模”约束，价格低于某个阈值时供给直接掉到零，导致价格震荡。

解决：先把price_adjustment_factor从默认的 0.3 降到 0.1，再跑一次。如果还不收敛，去supply_demand_curve.cpp里找到那个市场的供给函数，检查有没有硬编码的阈值。我一般会在阈值附近加一个线性过渡段，让供给曲线连续。

4.2 XML 改了但结果没变

现象：明明改了政策 XML 里的碳税值，跑出来的排放跟基准场景一模一样。

原因：configuration.xml里的inputFile指向的是主数据库，政策 XML 需要在主数据库里被引用才会生效。如果你只新建了一个政策 XML 但没在主数据库的<scenario>组件里引用它，GCAM 根本不会读。

解决：打开主数据库 XML，找到<scenarios>标签，在里面加一行<scenario name="carbon_tax_50"/>，名字要跟你新建的政策 XML 里的scenario name一致。

4.3 编译报错找不到 Boost

现象：cmake ..时报Could NOT find Boost。

原因：Boost 版本太老或者安装不完整。GCAM 需要 Boost 1.60 以上，而且需要filesystem和system两个组件。

解决：先sudo apt-get install libboost-filesystem-dev libboost-system-dev，如果还不行，在 CMake 命令里手动指定-DBOOST_ROOT=/usr/local。实在不行就下 Boost 源码编译安装，但那样比较费时间。

4.4 输出 CSV 里中文乱码

现象：用 Excel 打开输出 CSV，区域名里的中文显示成乱码。

原因：GCAM 输出默认用 UTF-8 编码，Excel 在 Windows 上默认用 GBK 打开。

解决：用 Python 的 pandas 读，或者用 LibreOffice 打开。如果非要用 Excel，先用iconv -f UTF-8 -t GBK转一遍。我一般直接在 Python 里做后续分析，不经过 Excel。

4.5 跑完发现结果跟文献对不上

现象：基准场景的 2100 年温度升幅跟 IPCC 报告里的参考值差很多。

原因：GCAM 本身不包含气候模型，它只算排放。温度升幅需要把排放结果喂给一个气候模型（比如 MAGICC）才能算出来。如果你直接拿 GCAM 的排放当温度看，那肯定对不上。

解决：GCAM 输出里有一个climate_model模块的接口，在configuration.xml里开启climateModel选项，它会调用一个简化的气候响应函数。但那个函数精度有限，正式研究里还是建议把排放结果导出，用专门的气候模型跑。

5. 二次开发：改模块、加技术、接外部模型的实操思路

5.1 加一种新能源技术

GCAM 里加新技术不需要改 C++ 代码，只需要在 XML 里定义技术参数。比如加一个“海上风电”技术，在input/energy/technology/下新建 XML：

<technology name="offshore_wind"> <type>electricity</type> <efficiency>0.45</efficiency> <capital-cost>2000</capital-cost> <!-- 美元/kW --> <fixed-om>50</fixed-om> <!-- 美元/kW/年 --> <variable-om>0.01</variable-om> <!-- 美元/kWh --> <lifetime>25</lifetime> <available-year>2030</available-year> </technology>

然后在电力模块的供给曲线 XML 里引用这个技术。关键参数是capital-cost和efficiency，前者决定投资成本，后者决定每单位燃料能发多少电。改这两个值，技术的竞争力会明显变化。

5.2 修改求解器收敛参数

如果你做的是长期场景（比如 2100 年），默认的收敛参数可能不够。在configuration.xml里把maxIterations调到 500，convergenceTolerance调到 0.0005。但注意，调紧之后跑一次的时间会翻倍。我一般先用松参数跑通，确认逻辑没问题，再用紧参数出正式结果。

5.3 接外部模型：以水模块为例

GCAM 的水模块输出的是各区域的取水量和耗水量。如果你想接一个水文模型算径流，需要把 GCAM 的输出转成水文模型的输入格式。常见做法是写一个 Python 脚本，读 GCAM 的 CSV，按经纬度插值到水文模型的网格上。GCAM 的区域划分是 32 个经济区，不是规则网格，所以插值的时候要注意区域边界。

import pandas as pd import numpy as np # 读 GCAM 水模块输出 water = pd.read_csv('output/database_basexdb.csv') water = water[water['sector'] == 'water_withdrawal'] # 按区域聚合，转成水文模型需要的格式 water_agg = water.groupby(['region', 'year'])['output'].sum().reset_index() water_agg.to_csv('hydro_model_input.csv', index=False)

这个脚本只是示例，实际插值需要区域形状文件。GCAM 的input/gis/目录下有区域边界数据，可以拿来用。

5.4 验证改造是否生效

改完模块后，怎么知道改对了？我的习惯是跑三个场景：基准、只改一个参数、改多个参数。然后对比三个场景的输出差异。如果只改一个参数时输出没变化，说明那个参数没被正确读取。如果改多个参数时输出变化方向跟预期相反，说明模块之间的耦合逻辑有问题。

具体验证步骤：先跑基准场景，记录关键指标（比如 2030 年可再生能源占比）；然后只改一个参数（比如把风电成本降 20%），再跑一次，看可再生能源占比是否上升；最后同时改风电成本和碳税，看两个政策是否有协同效应。如果协同效应为负，说明模块之间的价格信号传递有问题。

5.5 一个我常犯的错误

刚开始改 GCAM 的时候，我总想直接改 C++ 源码里的硬编码参数，觉得那样最直接。结果每次重新编译都要等十几分钟，而且改完经常忘了同步改 XML，导致代码和配置不一致。后来我强制自己：所有参数改动先走 XML，只有 XML 表达不了的逻辑才改 C++。从那以后我每次改完参数都强制走一遍“改 XML → 跑基准 → 对比输出”的流程，再也没出现过配置和代码打架的情况。希望帮到你。

本文还有配套的精品资源，点击获取