# ============================================================
# 项目级路径配置
# ============================================================

Paths:
  project_root: "E:/Greentech"
  __comment__: >
    项目根目录，所有路径均相对于该目录展开。
    不同工程师只需修改这一项即可迁移环境。

  raw_data:
    filtered_cycles_dir: "models/uf-rl/datasets/UF_longting_data/processed/filter_segments"
    cycle_file_pattern: "UF{unit}_filtered_cycles.csv"

    enabled_units: [1, 2]
    disabled_units: None

    __comment__: >
      已完成清洗与周期切分的真实工厂数据。
      每个 CSV 对应一个机组，文件内每一行是一个【物理周期】。
      data_to_rl 阶段会：
        - 读取 enabled_units 中所有机组
        - 合并为统一数据集
        - 机组编号仅用于筛选，不进入状态空间

  data_to_rl:
    output_dir: "models/uf-rl/datasets/UF_longting_data/rl_ready/output"
    cache_dir: "models/uf-rl/datasets/UF_longting_data/rl_ready/cache"

    __comment__: >
      data_to_rl 模块输出内容：
        - 全机组合并后的状态空间范围
        - reset 初始状态分布
        - reward 统计量


# ============================================================
# 数据层级定义（非常重要）
# ============================================================

DataHierarchy:

  physical_cycle:
    id_column: "seg_id"
    time_columns:
      start: "start_time"
      end: "end_time"
    __comment__: >
      物理周期是最细粒度的数据层级：
      - 用于物理模型验证
      - 用于环境内部子步模拟
      - 不直接暴露给强化学习算法

  chemical_cycle:
    id_column: "chem_cycle_id"
    validity_column: "chem_cycle_valid"
    step_definition: "one_rl_step_per_chemical_cycle"
    __comment__: >
      化学周期是强化学习的【唯一 step 单位】。
      强化学习中：
        - 一个 step = 一个化学周期
        - 一个状态 = 一个化学周期的整体状态

# ============================================================
# 强化学习状态定义（工程师重点关注）
# ============================================================

RLState:
  level: chemical_cycle
  dimension: 8
  __comment__: >
    强化学习 observation 的定义。
    所有变量在一个 step（化学周期）内保持不变。

  variables:

    q_UF:
      source: "flow_mean"
      aggregation: "mean_within_cycle"
      unit: "m3_per_h"
      description: "化学周期代表性进水流量"
      __comment__: >
        原始数据在物理周期层级变化，
        这里使用化学周期内的平均值作为状态。

    temp:
      source: "temp_mean"
      aggregation: "mean_within_cycle"
      unit: "celsius"
      description: "化学周期代表性水温"

    TMP:
      source: "tmp_start"
      selection: "first_physical_cycle"
      unit: "MPa"
      description: "化学周期起始跨膜压差"
      __comment__: >
        虽然 TMP 在物理周期内会变化，
        但强化学习只关心化学周期开始时的状态。

    R:
      source: "R_scaled_start"
      selection: "first_physical_cycle"
      unit: "scaled_resistance"
      description: "化学周期起始膜阻力"

    nuK:
      source: "cycle_nuK"
      unit: "scaled"
      description: "短期污染增长系数"
      __comment__: >
        在同一化学周期内视为常数，
        后续 step （下一化学周期）中根据动作进行经验性更新。

    slope:
      source: "cycle_long_a"
      unit: "scaled"
      description: "长期不可逆污染幂律系数 a"

    power:
      source: "cycle_long_b"
      unit: "dimensionless"
      description: "长期不可逆污染幂律指数 b"

    ceb_removal:
      source: "cycle_R_removed"
      unit: "scaled"
      description: "CEB 可去除的膜阻力"

# ============================================================
# 状态空间范围提取（reset 使用）
# ============================================================

StateSpaceExtraction:
  enabled: true
  level: chemical_cycle
  include_only_valid_cycles: true

  __comment__: >
    用真实工厂数据统计【合理状态空间范围】，
    用于：
      - reset 初始状态采样
      - 状态边界 sanity check

  statistics:
    method: "empirical"
    percentiles: [1, 5, 50, 95, 99]
    __comment__: >
      使用经验分布统计，避免假设正态分布。

  output:
    save_csv: true
    filename: "state_space_bounds.csv"

# ============================================================
# 物理周期层级的用途声明
# ============================================================

PhysicalCycleUsage:
  enabled: true

  purposes:
    - internal_simulation
    - parameter_sanity_check
    - post_training_validation

  variables_available:
    - R_scaled_start
    - R_scaled_end
    - tmp_start
    - tmp_end
    - flow_mean
    - flow_std
    - temp_mean
    - temp_std

  __comment__: >
    物理周期数据：
      ✔ 可用于环境内部计算
      ✔ 可用于训练后验证
      ✘ 不可作为 RL observation

# ============================================================
# 真实数据在强化学习中的角色（工程边界声明）
# ============================================================

RealDataUsagePolicy:

  reset_initialization:
    enabled: true
    source: "chemical_cycle_state_distribution"
    __comment__: >
      reset 时从真实化学周期状态分布中采样，
      确保训练从“现实可达状态”开始。

  training:
    use_real_transitions: false
    __comment__: >
      真实数据不用于：
        - 动力学拟合
        - 监督策略
      强化学习仍在模拟环境中进行。

  validation:
    enabled: true
    compare_with_real_cycles: true
    __comment__: >
      训练完成后：
        - 将策略运行结果
        - 与真实化学周期统计特性进行对比
      用于评估策略的现实可行性与安全性。

# ============================================================
# 方法论与工程风险声明
# ============================================================

MethodologyNotes:
  - "强化学习的 step 定义严格等同于一个化学周期"
  - "所有 RL 状态变量在一个 step 内视为常数"
  - "物理周期层级仅用于环境内部模拟"
  - "真实数据用于分布约束与验证，而非动力学建模"