714 lines
24 KiB
Rust
714 lines
24 KiB
Rust
//! 报告与产物写出：CSV / TOML / JSON / Markdown（可选 SVG）。
|
||
//!
|
||
//! 产物布局（`--out-dir`）：
|
||
//!
|
||
//! | 文件 | 内容 |
|
||
//! | --- | --- |
|
||
//! | `trials.csv` | 全部候选：增益 + 指标 + 成本 + 判定（可用任意表格软件复盘） |
|
||
//! | `best.toml` | 可直接粘贴进 `chassis.toml` 的 `[[motor]]` 片段 |
|
||
//! | `best-trace.csv` | 最优增益的完整步响应轨迹 |
|
||
//! | `report.md` | 人类可读总结：设置、Top-N、结论与注意事项 |
|
||
//! | `summary.json` | 机器可读结果（CI / 后续工具消费） |
|
||
//! | `best.svg` | 步响应三联图（仅 `--features plot`） |
|
||
|
||
use std::fmt::Write as _;
|
||
use std::path::{Path, PathBuf};
|
||
|
||
use dji_esc_sim::{LoopLimits, Scenario, Trace};
|
||
use serde::Serialize;
|
||
|
||
use crate::gains::GainSpace;
|
||
use crate::metrics::StepMetrics;
|
||
use crate::search::{Ranked, SearchConfig, Trial, verdict_hint};
|
||
|
||
/// 报告写出错误。
|
||
#[derive(Debug, thiserror::Error)]
|
||
pub enum ReportError {
|
||
/// 目录创建或文件写入失败。
|
||
#[error("io error at {path}: {source}")]
|
||
Io {
|
||
/// 出错路径。
|
||
path: PathBuf,
|
||
/// 底层错误。
|
||
source: std::io::Error,
|
||
},
|
||
/// CSV 写出失败。
|
||
#[error("csv error: {0}")]
|
||
Csv(#[from] csv::Error),
|
||
/// JSON 写出失败。
|
||
#[error("json error: {0}")]
|
||
Json(#[from] serde_json::Error),
|
||
/// TOML 写出失败。
|
||
#[error("toml error: {0}")]
|
||
Toml(#[from] toml::ser::Error),
|
||
/// 没有可用的最优结果。
|
||
#[error("no feasible trial to report")]
|
||
NoBest,
|
||
/// SVG 绘图失败（仅 `--features plot`）。
|
||
#[error("plot error: {0}")]
|
||
Plot(String),
|
||
}
|
||
|
||
fn io(path: impl Into<PathBuf>, source: std::io::Error) -> ReportError {
|
||
ReportError::Io { path: path.into(), source }
|
||
}
|
||
|
||
/// 生成产物所需的上下文。
|
||
#[derive(Debug, Clone)]
|
||
pub struct ReportContext {
|
||
/// 输出目录。
|
||
pub out_dir: PathBuf,
|
||
/// 本次搜索使用的参数空间。
|
||
pub space: GainSpace,
|
||
/// 搜索配置。
|
||
pub config: SearchConfig,
|
||
/// 场景。
|
||
pub scenario: Scenario,
|
||
/// 限幅。
|
||
pub limits: LoopLimits,
|
||
/// 后端描述（`sim(...)` / `bench(...)`）。
|
||
pub backend: String,
|
||
/// 目标轮名（写回 TOML 用）。
|
||
pub motor_name: String,
|
||
/// 验收阈值：最大超调（%）。
|
||
pub max_overshoot_pct: f32,
|
||
/// 验收阈值：最大稳态误差（%）。
|
||
pub max_ss_error_pct: f32,
|
||
/// 最优增益的轨迹（有则写 `best-trace.csv`）。
|
||
pub best_trace: Option<Trace>,
|
||
}
|
||
|
||
/// 写出全部产物，返回写出的文件列表。
|
||
///
|
||
/// # Errors
|
||
///
|
||
/// 目录创建、文件写入或序列化失败时返回 [`ReportError`]。
|
||
pub fn write_reports(ctx: &ReportContext, ranked: &Ranked) -> Result<Vec<PathBuf>, ReportError> {
|
||
std::fs::create_dir_all(&ctx.out_dir).map_err(|e| io(&ctx.out_dir, e))?;
|
||
let mut written = Vec::new();
|
||
|
||
let trials_path = ctx.out_dir.join("trials.csv");
|
||
write_trials_csv(&trials_path, &ranked.trials)?;
|
||
written.push(trials_path);
|
||
|
||
let best_path = ctx.out_dir.join("best.toml");
|
||
write_best_toml(&best_path, ctx, &ranked.best)?;
|
||
written.push(best_path);
|
||
|
||
if let Some(trace) = &ctx.best_trace {
|
||
let trace_path = ctx.out_dir.join("best-trace.csv");
|
||
write_trace_csv(&trace_path, trace)?;
|
||
written.push(trace_path);
|
||
}
|
||
|
||
let report_path = ctx.out_dir.join("report.md");
|
||
write_markdown(&report_path, ctx, ranked)?;
|
||
written.push(report_path);
|
||
|
||
let summary_path = ctx.out_dir.join("summary.json");
|
||
write_summary(&summary_path, ctx, ranked)?;
|
||
written.push(summary_path);
|
||
|
||
#[cfg(feature = "plot")]
|
||
if let Some(trace) = &ctx.best_trace {
|
||
let svg_path = ctx.out_dir.join("best.svg");
|
||
crate::plot::write_step_svg(&svg_path, trace, &ctx.scenario)?;
|
||
written.push(svg_path);
|
||
}
|
||
|
||
Ok(written)
|
||
}
|
||
|
||
/// `trials.csv` 的一行。
|
||
#[derive(Debug, Serialize)]
|
||
struct TrialRow {
|
||
index: u64,
|
||
phase: &'static str,
|
||
kp: f32,
|
||
ki: f32,
|
||
kd: f32,
|
||
feedforward: f32,
|
||
cost: f64,
|
||
verdict: &'static str,
|
||
settled: bool,
|
||
rise_time_s: f32,
|
||
overshoot_pct: f32,
|
||
settling_time_s: f32,
|
||
ss_error_pct: f32,
|
||
steady_rpm: f32,
|
||
iae: f32,
|
||
peak_effort_raw: f32,
|
||
rms_effort_raw: f32,
|
||
saturated_pct: f32,
|
||
max_rpm: f32,
|
||
}
|
||
|
||
impl TrialRow {
|
||
fn from_trial(trial: &Trial) -> Self {
|
||
let metrics = trial.score.metrics.unwrap_or_default();
|
||
Self {
|
||
index: trial.index,
|
||
phase: trial.phase.label(),
|
||
kp: trial.gains.kp,
|
||
ki: trial.gains.ki,
|
||
kd: trial.gains.kd,
|
||
feedforward: trial.gains.feedforward,
|
||
cost: trial.score.cost,
|
||
verdict: trial.score.verdict.label(),
|
||
settled: metrics.settled,
|
||
rise_time_s: metrics.rise_time_s,
|
||
overshoot_pct: metrics.overshoot_pct,
|
||
settling_time_s: metrics.settling_time_s,
|
||
ss_error_pct: metrics.ss_error_pct,
|
||
steady_rpm: metrics.steady_rpm,
|
||
iae: metrics.iae,
|
||
peak_effort_raw: metrics.peak_effort_raw,
|
||
rms_effort_raw: metrics.rms_effort_raw,
|
||
saturated_pct: metrics.saturated_pct,
|
||
max_rpm: metrics.max_rpm,
|
||
}
|
||
}
|
||
}
|
||
|
||
fn write_trials_csv(path: &Path, trials: &[Trial]) -> Result<(), ReportError> {
|
||
let mut writer = csv::Writer::from_path(path)?;
|
||
for trial in trials {
|
||
writer.serialize(TrialRow::from_trial(trial))?;
|
||
}
|
||
writer.flush().map_err(|e| io(path, e))?;
|
||
Ok(())
|
||
}
|
||
|
||
/// 轨迹 CSV 的一行。
|
||
#[derive(Debug, Serialize)]
|
||
struct TraceRow {
|
||
t_s: f32,
|
||
setpoint_rpm: f32,
|
||
rpm: f32,
|
||
effort_raw: i16,
|
||
saturated: bool,
|
||
}
|
||
|
||
fn write_trace_csv(path: &Path, trace: &Trace) -> Result<(), ReportError> {
|
||
let mut writer = csv::Writer::from_path(path)?;
|
||
for index in 0..trace.len() {
|
||
writer.serialize(TraceRow {
|
||
t_s: trace.t_s[index],
|
||
setpoint_rpm: trace.setpoint_rpm[index],
|
||
rpm: trace.rpm[index],
|
||
effort_raw: trace.effort_raw[index],
|
||
saturated: trace.saturated[index],
|
||
})?;
|
||
}
|
||
writer.flush().map_err(|e| io(path, e))?;
|
||
Ok(())
|
||
}
|
||
|
||
/// 可粘贴进既有 `[[motor]]` 段落的增益补丁。
|
||
#[derive(Debug, Serialize)]
|
||
struct GainPatch {
|
||
kp: f32,
|
||
ki: f32,
|
||
kd: f32,
|
||
feedforward: f32,
|
||
}
|
||
|
||
fn write_best_toml(path: &Path, ctx: &ReportContext, best: &Trial) -> Result<(), ReportError> {
|
||
let gains_patch = GainPatch {
|
||
kp: best.gains.kp,
|
||
ki: best.gains.ki,
|
||
kd: best.gains.kd,
|
||
feedforward: best.gains.feedforward,
|
||
};
|
||
let mut text = String::new();
|
||
writeln!(text, "# 由 chassis-tune 生成（seed={}, backend={}）", ctx.config.seed, ctx.backend)
|
||
.ok();
|
||
writeln!(
|
||
text,
|
||
"# 轮子：{}｜场景：{}｜限流 {} raw",
|
||
ctx.motor_name,
|
||
crate::search::scenario_summary(&ctx.scenario),
|
||
ctx.limits.current_limit_raw
|
||
)
|
||
.ok();
|
||
writeln!(text, "# 参数空间：{}", ctx.space.describe()).ok();
|
||
text.push_str("# 把下面四行粘进 chassis.toml 里对应的 [[motor]] 段落即可。\n");
|
||
text.push_str(&toml::to_string(&gains_patch)?);
|
||
std::fs::write(path, text).map_err(|e| io(path, e))?;
|
||
Ok(())
|
||
}
|
||
|
||
/// `summary.json` 的结构。
|
||
#[derive(Debug, Serialize)]
|
||
struct Summary<'a> {
|
||
backend: &'a str,
|
||
seed: u64,
|
||
samples: usize,
|
||
top_k: usize,
|
||
solver: &'static str,
|
||
evals: u64,
|
||
ok_trials: usize,
|
||
rejected_trials: usize,
|
||
scenario: String,
|
||
gain_space: String,
|
||
limits: LimitSummary,
|
||
thresholds: Thresholds,
|
||
best: BestSummary,
|
||
top: Vec<BestSummary>,
|
||
notes: Vec<String>,
|
||
}
|
||
|
||
#[derive(Debug, Serialize)]
|
||
struct LimitSummary {
|
||
current_limit_raw: i16,
|
||
}
|
||
|
||
#[derive(Debug, Serialize)]
|
||
struct Thresholds {
|
||
max_overshoot_pct: f32,
|
||
max_ss_error_pct: f32,
|
||
}
|
||
|
||
#[derive(Debug, Serialize)]
|
||
struct BestSummary {
|
||
index: u64,
|
||
phase: &'static str,
|
||
kp: f32,
|
||
ki: f32,
|
||
kd: f32,
|
||
feedforward: f32,
|
||
cost: f64,
|
||
verdict: &'static str,
|
||
metrics: Option<MetricsSummary>,
|
||
}
|
||
|
||
#[derive(Debug, Serialize)]
|
||
struct MetricsSummary {
|
||
rise_time_s: f32,
|
||
overshoot_pct: f32,
|
||
settling_time_s: f32,
|
||
ss_error_pct: f32,
|
||
steady_rpm: f32,
|
||
iae: f32,
|
||
rms_effort_raw: f32,
|
||
saturated_pct: f32,
|
||
max_rpm: f32,
|
||
}
|
||
|
||
impl MetricsSummary {
|
||
fn from_metrics(metrics: &StepMetrics) -> Self {
|
||
Self {
|
||
rise_time_s: metrics.rise_time_s,
|
||
overshoot_pct: metrics.overshoot_pct,
|
||
settling_time_s: metrics.settling_time_s,
|
||
ss_error_pct: metrics.ss_error_pct,
|
||
steady_rpm: metrics.steady_rpm,
|
||
iae: metrics.iae,
|
||
rms_effort_raw: metrics.rms_effort_raw,
|
||
saturated_pct: metrics.saturated_pct,
|
||
max_rpm: metrics.max_rpm,
|
||
}
|
||
}
|
||
}
|
||
|
||
fn best_summary(trial: &Trial) -> BestSummary {
|
||
BestSummary {
|
||
index: trial.index,
|
||
phase: trial.phase.label(),
|
||
kp: trial.gains.kp,
|
||
ki: trial.gains.ki,
|
||
kd: trial.gains.kd,
|
||
feedforward: trial.gains.feedforward,
|
||
cost: trial.score.cost,
|
||
verdict: trial.score.verdict.label(),
|
||
metrics: trial.score.metrics.as_ref().map(MetricsSummary::from_metrics),
|
||
}
|
||
}
|
||
|
||
fn write_summary(path: &Path, ctx: &ReportContext, ranked: &Ranked) -> Result<(), ReportError> {
|
||
let mut notes = Vec::new();
|
||
if !ranked.best.score.verdict.is_ok() {
|
||
notes.push(format!(
|
||
"没有任何候选达标：最优判定为 {}（{}）",
|
||
ranked.best.score.verdict.label(),
|
||
verdict_hint(ranked.best.score.verdict)
|
||
));
|
||
}
|
||
if let Some(metrics) = ranked.best.score.metrics {
|
||
if metrics.overshoot_pct > ctx.max_overshoot_pct {
|
||
notes.push(format!(
|
||
"最优解超调 {:.1}% 超过阈值 {:.1}%",
|
||
metrics.overshoot_pct, ctx.max_overshoot_pct
|
||
));
|
||
}
|
||
if metrics.ss_error_pct > ctx.max_ss_error_pct {
|
||
notes.push(format!(
|
||
"最优解稳态误差 {:.1}% 超过阈值 {:.1}%",
|
||
metrics.ss_error_pct, ctx.max_ss_error_pct
|
||
));
|
||
}
|
||
if metrics.saturated_pct > 5.0 {
|
||
notes.push(format!("最优解饱和占比 {:.1}%，限流可能偏紧", metrics.saturated_pct));
|
||
}
|
||
}
|
||
// 贴边界的警告排在"通用提醒"之前：它是本次搜索最具体的一条结论。
|
||
notes.extend(ctx.space.boundary_hits(&ranked.best.gains));
|
||
notes.push(
|
||
"仿真整定依赖被控对象模型；上真机前先用 `validate` 在台架上复验（--backend bench）。"
|
||
.into(),
|
||
);
|
||
|
||
let summary = Summary {
|
||
backend: &ctx.backend,
|
||
seed: ctx.config.seed,
|
||
samples: ctx.config.samples,
|
||
top_k: ctx.config.top_k,
|
||
solver: ctx.config.solver.name(),
|
||
evals: ranked.evals,
|
||
ok_trials: ranked.ok_count(),
|
||
rejected_trials: ranked.rejected,
|
||
scenario: crate::search::scenario_summary(&ctx.scenario),
|
||
gain_space: ctx.space.describe(),
|
||
limits: LimitSummary { current_limit_raw: ctx.limits.current_limit_raw },
|
||
thresholds: Thresholds {
|
||
max_overshoot_pct: ctx.max_overshoot_pct,
|
||
max_ss_error_pct: ctx.max_ss_error_pct,
|
||
},
|
||
best: best_summary(&ranked.best),
|
||
top: ranked.top(10).iter().map(best_summary).collect(),
|
||
notes,
|
||
};
|
||
let text = serde_json::to_string_pretty(&summary)?;
|
||
std::fs::write(path, text).map_err(|e| io(path, e))?;
|
||
Ok(())
|
||
}
|
||
|
||
fn write_markdown(path: &Path, ctx: &ReportContext, ranked: &Ranked) -> Result<(), ReportError> {
|
||
let mut text = String::new();
|
||
let best = &ranked.best;
|
||
|
||
writeln!(text, "# 速度环自动整定报告\n").ok();
|
||
write_markdown_conclusion(&mut text, ctx, best);
|
||
write_markdown_settings(&mut text, ctx, ranked);
|
||
write_markdown_top(&mut text, ranked);
|
||
write_markdown_artifacts(&mut text);
|
||
write_markdown_notes(&mut text, ctx, best);
|
||
|
||
std::fs::write(path, text).map_err(|e| io(path, e))?;
|
||
Ok(())
|
||
}
|
||
|
||
/// 结论段：最优增益、指标、验收、无解时的原因。
|
||
fn write_markdown_conclusion(text: &mut String, ctx: &ReportContext, best: &Trial) {
|
||
writeln!(text, "## 结论\n").ok();
|
||
writeln!(
|
||
text,
|
||
"**kp = {:.3} ki = {:.3} kd = {:.3} feedforward = {:.3}**（成本 {:.4}，判定 {}）\n",
|
||
best.gains.kp,
|
||
best.gains.ki,
|
||
best.gains.kd,
|
||
best.gains.feedforward,
|
||
best.cost(),
|
||
best.score.verdict.label()
|
||
)
|
||
.ok();
|
||
if let Some(metrics) = best.score.metrics {
|
||
writeln!(
|
||
text,
|
||
"- 上升时间 {:.0} ms｜超调 {:.1}%｜调节时间 {:.0} ms｜稳态误差 {:.2}%",
|
||
metrics.rise_time_s * 1000.0,
|
||
metrics.overshoot_pct,
|
||
metrics.settling_time_s * 1000.0,
|
||
metrics.ss_error_pct
|
||
)
|
||
.ok();
|
||
writeln!(
|
||
text,
|
||
"- 峰值电流 {:.0} raw｜RMS 电流 {:.0} raw｜饱和 {:.1}%｜峰值转速 {:.0} rpm",
|
||
metrics.peak_effort_raw, metrics.rms_effort_raw, metrics.saturated_pct, metrics.max_rpm
|
||
)
|
||
.ok();
|
||
writeln!(
|
||
text,
|
||
"- 验收：{}（阈值 超调 ≤ {:.1}%，稳态误差 ≤ {:.1}%）\n",
|
||
if ctx.best_passes(&metrics) { "✓ 通过" } else { "✗ 未通过" },
|
||
ctx.max_overshoot_pct,
|
||
ctx.max_ss_error_pct
|
||
)
|
||
.ok();
|
||
}
|
||
if !best.score.verdict.is_ok() {
|
||
writeln!(
|
||
text,
|
||
"> ⚠ 没有任何候选达标（最优：{}）。{}\n",
|
||
best.score.verdict.label(),
|
||
verdict_hint(best.score.verdict)
|
||
)
|
||
.ok();
|
||
}
|
||
}
|
||
|
||
/// 设置段：复现本次搜索所需的全部输入。
|
||
fn write_markdown_settings(text: &mut String, ctx: &ReportContext, ranked: &Ranked) {
|
||
writeln!(text, "## 设置\n").ok();
|
||
writeln!(text, "| 项 | 值 |").ok();
|
||
writeln!(text, "| --- | --- |").ok();
|
||
writeln!(text, "| 后端 | `{}` |", ctx.backend).ok();
|
||
writeln!(text, "| 场景 | `{}` |", crate::search::scenario_summary(&ctx.scenario)).ok();
|
||
writeln!(text, "| 参数空间 | `{}` |", ctx.space.describe()).ok();
|
||
writeln!(text, "| 限流 | {} raw |", ctx.limits.current_limit_raw).ok();
|
||
writeln!(text, "| 种子 | {} |", ctx.config.seed).ok();
|
||
writeln!(
|
||
text,
|
||
"| 搜索 | samples={}, top_k={}, solver={}, max_iters={} |",
|
||
ctx.config.samples,
|
||
ctx.config.top_k,
|
||
ctx.config.solver.name(),
|
||
ctx.config.max_iters
|
||
)
|
||
.ok();
|
||
writeln!(
|
||
text,
|
||
"| 评估 | {} 次（达标 {} / 共 {}） |",
|
||
ranked.evals,
|
||
ranked.ok_count(),
|
||
ranked.trials.len()
|
||
)
|
||
.ok();
|
||
writeln!(text, "| 目标轮 | `{}` |\n", ctx.motor_name).ok();
|
||
}
|
||
|
||
/// Top-10 表格。
|
||
fn write_markdown_top(text: &mut String, ranked: &Ranked) {
|
||
writeln!(text, "## Top 10\n").ok();
|
||
writeln!(
|
||
text,
|
||
"| # | 阶段 | kp | ki | kd | ff | 成本 | 判定 | 超调 % | 稳态误差 % | 调节 ms |"
|
||
)
|
||
.ok();
|
||
writeln!(text, "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |").ok();
|
||
for (rank, trial) in ranked.top(10).iter().enumerate() {
|
||
let metrics = trial.score.metrics.unwrap_or_default();
|
||
writeln!(
|
||
text,
|
||
"| {} | {} | {:.3} | {:.3} | {:.3} | {:.3} | {:.4} | {} | {:.1} | {:.2} | {:.0} |",
|
||
rank + 1,
|
||
trial.phase.label(),
|
||
trial.gains.kp,
|
||
trial.gains.ki,
|
||
trial.gains.kd,
|
||
trial.gains.feedforward,
|
||
trial.cost(),
|
||
trial.score.verdict.label(),
|
||
metrics.overshoot_pct,
|
||
metrics.ss_error_pct,
|
||
metrics.settling_time_s * 1000.0
|
||
)
|
||
.ok();
|
||
}
|
||
writeln!(text).ok();
|
||
}
|
||
|
||
/// 产物清单。
|
||
fn write_markdown_artifacts(text: &mut String) {
|
||
writeln!(text, "## 产物\n").ok();
|
||
writeln!(text, "- `trials.csv`：全部候选（含未达标者与判定原因）").ok();
|
||
writeln!(text, "- `best.toml`：可粘贴的 `[[motor]]` 增益片段").ok();
|
||
writeln!(text, "- `best-trace.csv`：最优增益的完整轨迹").ok();
|
||
writeln!(text, "- `hil-validation.csv`：真机重复性复验（仅 `--backend bench`）").ok();
|
||
writeln!(text, "- `summary.json`：机器可读结果\n").ok();
|
||
}
|
||
|
||
/// 注意事项：把"仿真整定不能替代实车复验"写进报告，而不是只写在 README 里。
|
||
fn write_markdown_notes(text: &mut String, ctx: &ReportContext, best: &Trial) {
|
||
let hits = ctx.space.boundary_hits(&best.gains);
|
||
writeln!(text, "## 注意事项\n").ok();
|
||
writeln!(text, "1. 仿真整定只保证在被控对象模型内最优；模型参数（摩擦 / 延迟）是量级估计，")
|
||
.ok();
|
||
writeln!(
|
||
text,
|
||
" 上真机前请用同一 `--scenario` 跑 `chassis-tune sweep --backend bench` 复验。"
|
||
)
|
||
.ok();
|
||
writeln!(
|
||
text,
|
||
"2. 台架搜索会真的驱动轮子：必须架空或整车固定，且加 `--i-know-the-wheel-spins`。"
|
||
)
|
||
.ok();
|
||
writeln!(
|
||
text,
|
||
"3. `current_limit` 属于安全约束，不参与搜索；它会钳住 PID 输出，也决定饱和判定。"
|
||
)
|
||
.ok();
|
||
writeln!(text, "4. 复现本次结果：同一 `--seed` + 同一参数空间 → 逐位一致。").ok();
|
||
for hit in &hits {
|
||
writeln!(text, "- ⚠ 搜索落在参数空间边界：{hit}").ok();
|
||
}
|
||
writeln!(
|
||
text,
|
||
"5. 本模型不含测量噪声：仿真里更高的增益不会被噪声惩罚，因此最优解可能偏激进——\n 台架复验（`--backend bench`）是把它拉回现实的唯一手段。"
|
||
)
|
||
.ok();
|
||
}
|
||
|
||
impl ReportContext {
|
||
/// 一组指标是否满足验收阈值。
|
||
#[must_use]
|
||
pub fn best_passes(&self, metrics: &StepMetrics) -> bool {
|
||
metrics.settled
|
||
&& metrics.overshoot_pct <= self.max_overshoot_pct
|
||
&& metrics.ss_error_pct <= self.max_ss_error_pct
|
||
}
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
use crate::backend::{Evaluator, SimEvaluator};
|
||
use crate::cost::{Objective, Weights};
|
||
use crate::gains::GainSpace;
|
||
use crate::search::{SearchConfig, sweep};
|
||
use dji_esc_sim::{LoopLimits, PlantEnsemble, PlantParams};
|
||
|
||
fn ranked(name: &str) -> (GainSpace, ReportContext, Ranked) {
|
||
let space = GainSpace::default_gm3508();
|
||
let scenario = Scenario::step(1500.0, 1.0);
|
||
let limits = LoopLimits::gm3508();
|
||
let objective = Objective::new(Weights::default(), scenario, limits);
|
||
let ensemble = PlantEnsemble::homogeneous(PlantParams::gm3508(), 1);
|
||
let evaluator = SimEvaluator::new(ensemble, scenario, limits, objective, 0.0);
|
||
let config = SearchConfig {
|
||
seed: 3,
|
||
samples: 48,
|
||
top_k: 2,
|
||
max_iters: 40,
|
||
max_evals: 900,
|
||
..SearchConfig::default()
|
||
};
|
||
let ranked = sweep(&space, &config, &evaluator, None).unwrap();
|
||
let trace =
|
||
dji_esc_sim::simulate(ranked.best.gains, &PlantParams::gm3508(), &scenario, limits)
|
||
.unwrap();
|
||
let ctx = ReportContext {
|
||
out_dir: std::env::temp_dir().join(format!("chassis-tune-report-{name}")),
|
||
space,
|
||
config,
|
||
scenario,
|
||
limits,
|
||
backend: evaluator.describe(),
|
||
motor_name: "front_left".into(),
|
||
max_overshoot_pct: 20.0,
|
||
max_ss_error_pct: 5.0,
|
||
best_trace: Some(trace),
|
||
};
|
||
(space, ctx, ranked)
|
||
}
|
||
|
||
#[test]
|
||
fn writes_every_artifact() {
|
||
let (_, ctx, ranked) = ranked("writes_every_artifact");
|
||
let _ = std::fs::remove_dir_all(&ctx.out_dir);
|
||
let written = write_reports(&ctx, &ranked).unwrap();
|
||
let names: Vec<String> = written
|
||
.iter()
|
||
.map(|p| p.file_name().unwrap_or_default().to_string_lossy().into_owned())
|
||
.collect();
|
||
for expected in ["trials.csv", "best.toml", "best-trace.csv", "report.md", "summary.json"] {
|
||
assert!(names.iter().any(|n| n == expected), "missing {expected}: {names:?}");
|
||
}
|
||
for path in &written {
|
||
assert!(path.exists(), "{} must exist", path.display());
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn trials_csv_has_a_stable_header_and_one_row_per_trial() {
|
||
let (_, ctx, ranked) = ranked("trials_csv_has_a_stable_header_and_one_row_per_trial");
|
||
write_reports(&ctx, &ranked).unwrap();
|
||
let text = std::fs::read_to_string(ctx.out_dir.join("trials.csv")).unwrap();
|
||
let mut lines = text.lines();
|
||
let header = lines.next().unwrap();
|
||
for column in ["index", "phase", "kp", "ki", "kd", "feedforward", "cost", "verdict"] {
|
||
assert!(header.contains(column), "header missing {column}: {header}");
|
||
}
|
||
assert_eq!(lines.count(), ranked.trials.len());
|
||
}
|
||
|
||
#[test]
|
||
fn best_toml_parses_back_through_the_config_schema() {
|
||
let (_, ctx, ranked) = ranked("best_toml_parses_back_through_the_config_schema");
|
||
write_reports(&ctx, &ranked).unwrap();
|
||
let text = std::fs::read_to_string(ctx.out_dir.join("best.toml")).unwrap();
|
||
// 片段本体是合法 TOML：与其它段落拼起来即可被 chassis-config 读回。
|
||
let patch = text
|
||
.lines()
|
||
.filter(|line| !line.trim_start().starts_with('#'))
|
||
.collect::<Vec<_>>()
|
||
.join("\n");
|
||
let full = format!(
|
||
"[can]\ninterface = \"can0\"\n[mecanum]\nhalf_length = 0.2\nhalf_width = 0.25\nwheel_radius = 0.0762\n\n[[motor]]\nname = \"front_left\"\nesc_id = 1\ndirection = 1\ngear_ratio = 19.203\n{patch}"
|
||
);
|
||
let mut motors = Vec::new();
|
||
for index in 1..4 {
|
||
motors.push(format!(
|
||
"[[motor]]\nname = \"w{index}\"\nesc_id = {}\ndirection = 1\ngear_ratio = 19.203\n",
|
||
index + 1
|
||
));
|
||
}
|
||
let full = format!("{full}\n{}", motors.join("\n"));
|
||
let config = chassis_config::Config::from_toml(&full).expect("best.toml must be readable");
|
||
let gains = config.motors[0].velocity_gains();
|
||
assert_eq!(gains, ranked.best.gains);
|
||
}
|
||
|
||
#[test]
|
||
fn summary_json_is_machine_readable() {
|
||
let (_, ctx, ranked) = ranked("summary_json_is_machine_readable");
|
||
write_reports(&ctx, &ranked).unwrap();
|
||
let text = std::fs::read_to_string(ctx.out_dir.join("summary.json")).unwrap();
|
||
let value: serde_json::Value = serde_json::from_str(&text).unwrap();
|
||
assert_eq!(value["seed"], serde_json::json!(3));
|
||
assert_eq!(value["samples"], serde_json::json!(48));
|
||
assert!(value["best"]["kp"].as_f64().unwrap() > 0.0);
|
||
assert!(value["top"].as_array().unwrap().len() <= 10);
|
||
assert!(!value["notes"].as_array().unwrap().is_empty());
|
||
}
|
||
|
||
#[test]
|
||
fn markdown_mentions_the_gains_and_thresholds() {
|
||
let (_, ctx, ranked) = ranked("markdown_mentions_the_gains_and_thresholds");
|
||
write_reports(&ctx, &ranked).unwrap();
|
||
let text = std::fs::read_to_string(ctx.out_dir.join("report.md")).unwrap();
|
||
assert!(text.contains("kp ="), "{text}");
|
||
assert!(text.contains("Top 10"), "{text}");
|
||
assert!(text.contains("front_left"), "{text}");
|
||
assert!(text.contains("注意事项"), "{text}");
|
||
}
|
||
|
||
#[test]
|
||
fn best_trace_csv_matches_the_trace_length() {
|
||
let (_, ctx, ranked) = ranked("best_trace_csv_matches_the_trace_length");
|
||
write_reports(&ctx, &ranked).unwrap();
|
||
let text = std::fs::read_to_string(ctx.out_dir.join("best-trace.csv")).unwrap();
|
||
let rows = text.lines().count();
|
||
let expected = ctx.best_trace.as_ref().unwrap().len() + 1; // + 表头
|
||
assert_eq!(rows, expected);
|
||
}
|
||
|
||
#[test]
|
||
fn best_passes_respects_the_thresholds() {
|
||
let (_, ctx, _) = ranked("t");
|
||
let passing = StepMetrics {
|
||
settled: true,
|
||
overshoot_pct: 10.0,
|
||
ss_error_pct: 1.0,
|
||
..StepMetrics::default()
|
||
};
|
||
assert!(ctx.best_passes(&passing));
|
||
let overshooting = StepMetrics { overshoot_pct: 50.0, ..passing };
|
||
assert!(!ctx.best_passes(&overshooting));
|
||
let unsettled = StepMetrics { settled: false, ..passing };
|
||
assert!(!ctx.best_passes(&unsettled));
|
||
}
|
||
}
|