feat(WastewaterTreatment): add BSM1 aeration control benchmark

[Mingqwqqaq]

中文说明

本 PR 新增 WastewaterTreatment/BSM1AerationControl，作为 Frontier-Engineering 中污水处理方向的反馈控制任务。

该任务基于 IWA Benchmark Simulation Model No. 1（BSM1）：候选控制器需要根据带噪过程观测，每 15 分钟调整三个好氧反应池的氧传质系数和内回流量，并在出水质量、能耗、排放达标和控制平滑性之间取得平衡。

评测覆盖旱天、降雨和暴雨三种确定性工况，每个工况仿真 14 天，并使用最后 7 天计算工程指标。

核心设计

• 实现五级 ASM1 生化反应器和十层 Takacs 二沉池。
• 控制量包括 3–5 号反应池 KLa 与内回流量。
• 提供带噪溶解氧、硝酸盐、氨氮和进出水观测。
• 对 action schema、数值范围和相邻时刻变化率进行严格校验。
• 评分综合考虑：
  • BSM1 出水质量指数（EQI）；
  • 曝气、泵送和搅拌能耗；
  • 控制动作平滑性；
  • NH4-N、总氮、COD、TSS 和 BOD5 超标程度。
• candidate 在独立、带时限的 JSON-lines worker 进程中运行。
• 提供中英文文档、可演化基线、统一评测元数据和 baseline result log。

来源与许可

工艺布局、ASM1 动力学、二沉池模型、排放限值和能耗公式参考：

• IWA BSM1 General Description
• fau-evt/bsm2-python

适配自 bsm2-python 的部分保留了 BSD-3-Clause 许可证。

仓库没有重新分发官方动态进水文件，而是根据公开的 BSM1 平均进水参数和天气事件说明生成确定性、质量守恒的 BSM1-derived 轨迹。

English Summary

This PR adds WastewaterTreatment/BSM1AerationControl, a feedback-control benchmark for the WastewaterTreatment domain in Frontier-Engineering.

The task evaluates whether an agent can design a controller that adjusts oxygen-transfer coefficients in aerobic reactors 3–5 and the internal recycle flow using noisy process observations.

Controllers are evaluated across deterministic dry, rain, and storm scenarios while balancing effluent quality, aeration/pumping/mixing energy, actuator smoothness, and discharge-limit compliance.

Key Features

• Five ASM1 reactors and a ten-layer Takacs secondary settler.
• Fifteen-minute feedback-control intervals over 14-day simulations.
• Dry, rain, and storm hydraulic-load scenarios.
• Strict action schema, range, and slew-rate validation.
• Absolute engineering score without a frozen candidate baseline.
• Separate bounded worker process for candidate controllers.
• Unified frontier_eval integration.
• English and Chinese documentation.
• Independent ASM1 and Takacs numerical oracles generated from
  bsm2-python commit 73caa8b.

Quality Assurance

Direct evaluation

python verification/evaluator.py scripts/init.py \
  --metrics-out metrics.json \
  --artifacts-out artifacts.json

[github-actions]

🤖 AI Code Review (gemini-3-flash-preview)

🇬🇧 English Analysis

1. Executive Summary

• Core Purpose: This PR introduces a new engineering benchmark task named BSM1AerationControl under the WastewaterTreatment category. It simulates an activated-sludge plant based on the IWA Benchmark Simulation Model No. 1 (BSM1) and requires the design of a feedback controller to optimize effluent quality and energy consumption across varying weather conditions.
• Modified File Structure & Modifications:
  • TASK_DETAILS.md & TASK_DETAILS_zh-CN.md: Added the new task entry to the global task list.
  • benchmarks/WastewaterTreatment/BSM1AerationControl/README.md (and _zh-CN.md): Provided setup instructions, evaluation commands, and task overview.
  • benchmarks/WastewaterTreatment/BSM1AerationControl/Task.md (and _zh-CN.md): Defined the engineering background, observation/action interfaces, and the multi-objective scoring model.
  • benchmarks/WastewaterTreatment/BSM1AerationControl/verification/bsm1_model.py: Implemented the core process model, including ASM1 kinetics and the Takacs secondary settler using ODE integration.
  • benchmarks/WastewaterTreatment/BSM1AerationControl/verification/evaluator.py: Implemented the simulation loop, scenario management, and metric calculation.
  • benchmarks/WastewaterTreatment/BSM1AerationControl/baseline/solution.py: Provided a fixed-operating-point reference policy.
  • benchmarks/WastewaterTreatment/BSM1AerationControl/frontier_eval/: Added configuration files (eval_command.txt, constraints.txt, etc.) for integration with the frontier_eval framework.

2. AI Content Analysis

• Estimated AI Component: 15%
• Reasoning & Evidence: The core logic in bsm1_model.py is highly domain-specific, involving precise biochemical engineering constants (e.g., ASM1 parameters like $Y_H, Y_A, f_P$) and complex ODE systems that are unlikely to be generated by a general-purpose AI without significant human guidance or existing specialized codebases. The AI contribution is likely limited to boilerplate code in the evaluator.py, standard unit test structures, and the initial drafting/translation of the Markdown documentation. The variable naming (e.g., SNO, SNH, XBH) follows strict domain conventions rather than generic AI naming patterns.

3. Engineering & Economic Assessment

• Engineering Reality Check: This is a high-fidelity engineering problem. It moves beyond "toy examples" by implementing a standard industry benchmark (BSM1). It correctly handles realistic constraints such as sensor noise, actuator slew limits (rate of change), and diverse hydraulic scenarios (dry, rain, storm). The use of odeint for process simulation reflects production-grade scientific computing.
• Economic Value: High. Wastewater treatment is an energy-intensive industrial process. Optimizing aeration and pumping while maintaining regulatory compliance directly translates to significant operational cost savings and environmental impact reduction.

4. Quality Assurance

• Verification & Testing:
  • frontier_eval Integration: Yes
  • task_name: WastewaterTreatment/BSM1AerationControl
  • Execution & Dependencies: The README.md clearly documents the installation of dependencies via verification/requirements.txt and provides exact commands for direct evaluation, regression testing, and unified evaluation.
• Documentation Quality: The documentation is excellent. It provides both English and Chinese versions, includes detailed design notes in references/design_notes.md, and explicitly states the scoring formulas. No significant grammatical errors or formatting inconsistencies were detected.
• Organizational Structure: The structure is highly logical and modular. It separates the physical model (bsm1_model.py), the evaluation logic (evaluator.py), and the agent interface (init.py), facilitating scalability and maintenance.

5. Security & Privacy Check

• Sensitive Files: Clean. No .env, API keys, or IDE-specific configurations were found.
• Absolute Paths: None detected. The code uses Path(__file__).resolve() to handle relative paths correctly.

---

🇨🇳 中文分析

1. 摘要

• 核心目的: 此 PR 在 WastewaterTreatment 类别下引入了一个名为 BSM1AerationControl 的新工程基准任务。该任务基于 IWA 一号基准仿真模型 (BSM1) 模拟活性污泥处理厂，要求设计反馈控制器，以在不同天气条件下优化出水质量和能耗。
• 修改的文件结构与变更摘要:
  • TASK_DETAILS.md & TASK_DETAILS_zh-CN.md: 在全局任务列表中添加了新任务条目。
  • benchmarks/WastewaterTreatment/BSM1AerationControl/README.md (及 _zh-CN.md): 提供了环境安装、评测命令和任务概览。
  • benchmarks/WastewaterTreatment/BSM1AerationControl/Task.md (及 _zh-CN.md): 定义了工程背景、观测/动作接口以及多目标评分模型。
  • benchmarks/WastewaterTreatment/BSM1AerationControl/verification/bsm1_model.py: 实现了核心工艺模型，包括 ASM1 动力学和使用 ODE 积分的 Takacs 二沉池模型。
  • benchmarks/WastewaterTreatment/BSM1AerationControl/verification/evaluator.py: 实现了仿真循环、场景管理和指标计算。
  • benchmarks/WastewaterTreatment/BSM1AerationControl/baseline/solution.py: 提供了一个固定工况的参考策略。
  • benchmarks/WastewaterTreatment/BSM1AerationControl/frontier_eval/: 添加了用于集成到 frontier_eval 框架的配置文件（如 eval_command.txt, constraints.txt 等）。

2. AI 成分分析

• 预估 AI 含量: 15%
• 判断依据与证据: bsm1_model.py 中的核心逻辑具有高度的领域特定性，涉及精确的生化工程常数（如 ASM1 参数 $Y_H, Y_A, f_P$）和复杂的 ODE 系统，通用 AI 在没有人类深度指导或现有专业代码库的情况下很难生成。AI 的贡献可能仅限于 evaluator.py 中的样板代码、标准单元测试结构以及 Markdown 文档的初步起草和翻译。变量命名（如 SNO, SNH, XBH）遵循严格的领域惯例，而非通用的 AI 命名模式。

3. 工程与经济评估

• 工程现实检验: 这是一个高保真的工程问题。它通过实现行业标准基准 (BSM1) 超越了“玩具示例”。它正确处理了现实约束，如传感器噪声、执行器变化率限制（slew limits）以及多样化的水力场景（旱天、降雨、暴雨）。使用 odeint 进行过程仿真反映了生产级的科学计算水平。
• 经济价值: 高。废水处理是能源密集型工业过程。在保持合规性的同时优化曝气和泵送，可直接转化为显著的运营成本节约和环境影响减少。

4. 质量保证

• 验证与测试:
  • frontier_eval 集成: 是
  • task_name: WastewaterTreatment/BSM1AerationControl
  • 运行与依赖: README.md 清晰地记录了通过 verification/requirements.txt 安装依赖的方法，并提供了直接评测、回归测试和统一评测的确切命令。
• 文档质量: 文档质量极佳。提供了中英双语版本，在 references/design_notes.md 中包含详细的设计说明，并明确列出了评分公式。未检测到明显的语法错误或格式不一致。
• 组织结构: 文件组织逻辑清晰且模块化。它将物理模型 (bsm1_model.py)、评测逻辑 (evaluator.py) 和智能体接口 (init.py) 分离，有利于扩展和维护。

5. 安全与隐私检查

• 敏感文件: 未发现异常。未发现 .env、API 密钥或 IDE 特定配置。
• 绝对路径: 未检测到。代码使用 Path(__file__).resolve() 正确处理相对路径。