XAJ
这一页展示的是 XAJ 在 HydroPilot 里的典型模型路径，也就是怎样把基于 xaj.yaml 和 CSV 文件组织的工程整理成一条可验证、可重复评估、可接入 UQPyL 的运行链。
亮点
- 基于 CSV 的 reader 和 writer
- 面向 RIVID 的参数定位
- 对非 SWAT 水文模型的模板支持
什么情况下最适合看这一页
如果你的项目符合下面这些条件，这一页最有参考价值：
- 工程本身基于
xaj.yaml和 CSV 输入输出组织 - 参数主要存放在
parameters.csv - 输出主要来自
streamflow.csv、Runoff_Yield.csv这类 CSV 文件 - 模型目标更适合通过
RIVID过滤表达，而不是 SWAT 风格的 HRU 逻辑
典型配置形态
这条路径通常从 version: xaj 开始：
version: xaj
basic:
projectPath: ./xaj
workPath: ./work
command: ./pyxaj.exe run xaj.yaml模板会把它展开成带有 CSV reader 和 CSV writer 的通用配置。
为什么这条模型路径有价值
它说明 HydroPilot 并不只是 SWAT 的外壳。只要参数写入和结果读取能够被明确表达，它就能用同样的编排方式支持别的水文模型。
放到实际项目里，这一页真正有价值的地方在于：
- 它说明 HydroPilot 并不依赖 SWAT 那套定宽文件体系
- 只要你的模型工程有稳定的参数表和输出表，HydroPilot 就可能接得进去
- 对很多以 CSV 为核心的数据驱动模型来说，这条线反而会更自然
HydroPilot 在这里帮你做什么
对于 XAJ 风格工程，HydroPilot 可以帮你做这些事：
- 从
xaj.yaml发现工程元数据 - 从
parameters.csv解析参数写入目标 - 把命名变量映射到具体输出文件和列
- 在需要时利用
rivid精确定位参数行或结果列
这意味着 XAJ 这条线更接近“基于表格结构的工程编排”，而不是“基于固定文本布局的文件编辑”。
最小配置形态
version: xaj
basic:
projectPath: ./xaj
workPath: ./work
command: ./pyxaj.exe run xaj.yaml
parameters:
design:
- name: KC
bounds: [0.5, 2.0]
- name: WM
bounds: [80, 200]
physical:
- name: KC
mode: v
filter:
rivid: 60711600这就是 XAJ 路径最常见的起点形态：CSV 参数、面向 RIVID 的定位，以及由模板展开成通用配置。
继续往下补时，真实配置一般还会增加：
series：指定读哪个输出文件、哪一列、哪段时间obs：实测数据的位置functions / derived / objectives：定义评价指标
这也正好说明，HydroPilot 更像一个通用的水文执行层，而不只是服务 SWAT。
一个更完整的使用方式
如果把它放到一个完整率定流程里，通常会这样推进：
- 先确认
xaj.yaml能被正确发现 - 再确认
parameters.csv中的参数定位没有问题 - 再确认输出 CSV 的列头、
rivid和rowRanges能正确匹配 - 最后再把这些序列接成目标函数，进入重复评估或优化流程
这样做的好处是，参数写入、输出提取和评价逻辑可以逐步分开验证，不容易把问题混在一起。
完整工作流示例：从 CSV 工程走到率定与敏感性分析
XAJ 这条线特别适合承接完整案例，因为它的数据结构天然更清晰。一个更像真实业务的完整工作流，通常可以这样组织：
- 用
version: xaj描述项目目录和运行命令 - 从
parameters.csv中挑出待分析或待率定的参数 - 从
streamflow.csv或Runoff_Yield.csv中提取目标序列 - 先构造单目标评价函数，例如
NSE - 用
hydropilot-validate和hydropilot-test确认 CSV 读写链路无误 - 再决定先做敏感性分析，还是直接进入率定
相比 SWAT 这类依赖大量定宽文本文件的工程，XAJ 的优势在于：参数表、输出表和对象定位关系往往更直观，所以特别适合拿来做一条从“模型接入”直接走到“分析或率定”的完整案例。
一份可用于完整流程的基础配置
version: xaj
basic:
projectPath: ./xaj
workPath: ./work
command: ./pyxaj.exe run xaj.yaml
parameters:
design:
- name: KC
bounds: [0.5, 2.0]
- name: WM
bounds: [80, 200]
- name: B
bounds: [0.1, 0.6]
physical:
- name: KC
mode: v
filter:
rivid: 60711600
- name: WM
mode: v
filter:
rivid: 60711600
- name: B
mode: v
filter:
rivid: 60711600
series:
- id: flow
sim:
file: streamflow.csv
variable: Q
rivid: 60711600
rowRanges:
- [1, 1096]
obs:
file: obs_flow.csv
rowRanges:
- [1, 1096]
colNum: 1
functions:
- name: NSE
kind: builtin
derived:
- id: nse_flow
call:
func: NSE
args: [flow.sim, flow.obs]
objectives:
- id: obj_nse
ref: nse_flow
sense: max这份配置体现的是 XAJ 路径最关键的结构：
- 参数通过表结构和
rivid来定位 - 输出提取也是围绕 CSV 列和对象标识来完成
- 一旦
series、derived和objectives接好了，就已经具备进入算法驱动流程的条件
一条更自然的扩展顺序
如果你既想做率定，也想做敏感性分析，更推荐按下面的顺序推进：
- 先确认
parameters.csv的列名、参数名和过滤条件都对得上 - 再确认
streamflow.csv的列头、rivid和观测值长度完全一致 - 先只接一个目标，例如出口流量的
NSE - 先跑敏感性分析，判断
KC、WM、B哪些参数更值得率定 - 再把高敏感参数交给 UQPyL 做优化
这样做的好处是，参数筛选和率定会更有依据，不至于一开始就把所有参数都丢给优化器。
一个完整案例可以怎样展开
如果后面要把这一页继续做成更扎实的完整案例，最值得保留的一条主线就是：
- HydroPilot 负责 XAJ 的参数写入和结果提取
- UQPyL 先对
KC、WM、B等参数做敏感性分析 - 根据敏感性排序收缩参数集合
- 再用单目标或多目标优化器做率定
- 最后比较率定前后流量过程线和指标提升
这条主线的好处是非常完整，而且和 UQPyL 的能力结合得也最自然。
和 UQPyL 怎么接
当 XAJ 配置已经能稳定完成单次评估后，就可以直接用 UQPyLAdapter 暴露成问题接口：
from hydropilot.integrations import UQPyLAdapter
with UQPyLAdapter("my_xaj.yaml") as problem:
print(problem.nInput)
print(problem.lb)
print(problem.ub)后续你可以按目标选择不同方向：
- 如果参数较多，先做敏感性分析
- 如果目标明确，直接做单目标率定
- 如果既关心总量误差也关心过程线形状，再扩展成多目标问题
这一类配置最擅长处理什么
- 基于 CSV 的参数写入
- 基于 CSV 的输出提取
- 根据工程元数据做行列解析
- 在没有 SWAT 定宽文件前提下完成模型专属运行
常见注意点
这一类案例里最常见的问题通常不是算法，而是表结构本身：
parameters.csv的列名和配置里的参数名对不上- 输出 CSV 的列头和
variable/rivid不匹配 - 行范围写对了，但观测值和模拟值时间上并没有对齐
- 工程本身虽然能运行，但输出文件结构和预期不一致
因此，XAJ 这条线最重要的原则不是“先优化”，而是“先把表结构和读取逻辑验证清楚”。
建议的第一步
最稳妥的做法，是从一个已经稳定具备 xaj.yaml 和 CSV 输出的工程开始，先确认 HydroPilot 能正确发现参数表和输出表头，再继续补目标函数和优化逻辑。
和 UQPyL 的连接点
这里仍然适用同样的分工方式：HydroPilot 负责模型执行和 CSV 层集成，UQPyL 可以通过 UQPyLAdapter 接手优化或率定逻辑。