Feature/perf roadmap phase1 efficiency map

[magic-alt]

PR #7 已经创建成功，以下是完整的 PR 内容：

---

[Perf] Phase 1 效率图管线：LUT 损耗聚合 / 控制曲面 / 工况能耗 / 温升钩子

链接： magic-alt#7
base: master ← head: feature/perf-roadmap-phase1-efficiency-map

---

背景 / Motivation

上游 Eomys/pyleecan#214 给出了电机性能优化长期路线图，涵盖损耗建模、标准工况能耗、最优控制策略和热耦合等方向。本分支（Phase 1）在已有 LUTdq + DriveCycle 管线（PR #3）基础上，完成路线图第 1/2/5/9/7 项的第一阶段落地。

---

变更摘要 / Changes（5 commits）

Commit	里程碑	内容
a2a7f2d	规划	0001-perf-roadmap-phase1-efficiency-map.md
29bf33c	M1	LUT 损耗聚合
f2ddfc0	M2	控制曲面提取
c0cdef6	M3	工况能耗分解 + 标准循环数据 + 文档
443dc27	M4	温升钩子

M1 — LUT 损耗聚合（#214 第 1、2 项）

• 新增 LOSS_SERIES_KEYS（P_jl / P_fe / P_mag / P_mech / P_loss_total）常量与 extract_loss_series() 工具函数（_utils.py）。
• run_efficiency_map_lut 在结果中写入 result["loss_maps"] 字典及顶层别名，与现有 Tem/Phi_dq 保持向后兼容。

M2 — 最优控制曲面提取（#214 第 9 项）

• 新增 extract_control_surface.py。
• 基于 LUT 网格一次扫描提取 MTPA / MTPV / 弱磁边界，返回含 base_speed_rpm 与 control_region 分区标记的 dict，与 ElecLUTdq.solve_torque 完全解耦。

M3 — 工况能耗与标准循环（#214 第 5 项）

• summarize_drive_cycle_outputs 新增 energy_out_J、energy_in_J、energy_loss_J、energy_loss_breakdown_J、eta_cycle 字段。
• 新增 read_standard_drive_cycle（nedc / wltp_class3），轻量 CSV 数据放入 DriveCycle（< 50 KB）。
• 新增中文工作流文档 Efficiency_Map_DriveCycle_CN.md。

M4 — 温升钩子（#214 第 7 项，最小占位）

• 新增 thermal_hooks.py：get_conductor_resistivity(conductor, T_op)、get_magnet_brm(magnet, T_op) 回调及 apply/build_lut_temperature_context。
• ElecLUTdq.comp_LUTdq 在求解前调用温度上下文；默认等温 20 °C，不改变现有行为，为 Phase 2 HeatTransferFEMM 耦合预留入口。

---

新增文件 / New Files

pyleecan/Functions/Simulation/LUTdq/extract_control_surface.py   (M2)
pyleecan/Functions/Simulation/LUTdq/thermal_hooks.py             (M4)
pyleecan/Functions/Simulation/DriveCycle/read_standard_drive_cycle.py (M3)
pyleecan/Data/DriveCycle/NEDC_segment.csv                        (M3)
pyleecan/Data/DriveCycle/WLTP_class3_segment.csv                 (M3)
Doc/ADR/0001-perf-roadmap-phase1-efficiency-map.md               (规划)
Doc/Efficiency_Map_DriveCycle_CN.md                              (M3)
Tests/Functions/Simulation/test_lutdq_executors.py               (M1–M4)
Tests/Functions/Simulation/test_drive_cycle.py                   (M3)

---

测试 / Tests

pytest -m star Tests
# 25 passed, 6412 deselected

---

兼容性 / Compatibility

• 新增字段均为可选（默认 None），现有 LUT pickle/json 不受影响。
• ElecLUTdq.solve_torque 保持原签名。
• 旧 DriveCycle demo 可继续运行，新指标作为附加输出。
• M4 默认等温 20 °C，与现有行为完全一致。

---

相关 / Related

• ADR: 0001-perf-roadmap-phase1-efficiency-map.md
• Upstream: Roadmap for the performance optimization of electrical motors #214
• Base: master @ 7a7a35f（含 PR replaced mkdir with makedirs to create all the intermediate directories if they don't exist #3 LUTdq 管线、PR Added some class descriptions #5 Elmer 验证、PR PEP8, class generator and black #6 回归修复）

[Copilot]

Pull request overview

This PR implements “Phase 1” of a performance/efficiency-map roadmap on top of the existing LUTdq + DriveCycle pipeline. It adds LUT-based executors (efficiency maps, inductance maps, drive-cycle replays), loss aggregation/energy summaries, temperature hook scaffolding, ParaView automation helpers, plus repo governance/CI policy updates and Windows packaging improvements.

Changes:

• Add LUTdq executors for efficiency maps, inductance maps, and drive-cycle runs (with cache/plot helpers) and extend drive-cycle summaries with energy/loss breakdown metrics.
• Add temperature hook plumbing for LUT workflows (isothermal default), plus control/region classification metadata for maps.
• Add repo policy automation (pre-commit + CI quality gate), additional validation runners/tests, ParaView helpers, and Windows EXE packaging refactors/docs.

Reviewed changes

Copilot reviewed 97 out of 100 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Tutorials/run_lutdq_efficiency_map_demo.py	Adds a lightweight LUTdq efficiency-map demo script (no external solvers).
tools/check_repo_policy.py	Adds policy checks for forbidden artifacts and temporary pytest markers.
Tests/Validation/Loss/test_release_validation_report_generator.py	Adds unit tests for release validation report decision logic.
Tests/Validation/Loss/test_prius_validation_workflow.py	Adds tests for Prius validation preflight and summary generation behavior.
Tests/Validation/Loss/test_elmer_validation_runner_defaults.py	Verifies Elmer validation runners default to baseline settings.
Tests/Validation/Loss/run_elmer_validation_prius.py	Adds Prius Elmer validation runner with baseline checks and reporting.
Tests/Validation/Loss/run_elmer_validation_leaf.py	Adds LEAF Elmer validation runner with reporting.
Tests/Validation/Loss/prius_validation_preflight.py	Adds reusable preflight helpers for files/modules/executables.
Tests/Functions/test_paraview_helpers.py	Adds tests for ParaView helper utilities (resolve/render/launch).
Tests/Functions/test_binary_resolution.py	Adds tests for get_path_binary Windows/env resolution behavior.
Tests/Functions/Simulation/test_drive_cycle.py	Adds tests for drive-cycle CSV IO, OPMatrix build, and summarization.
Tests/conftest.py	Redirects pytest temp usage under .local/pytest-temp with custom tmp_path.
SimulationModels/README.md	Documents tracked simulation model inputs under SimulationModels/.
requirements.txt	Updates/locks some dependencies (e.g., gmsh, PySide6) and comments.
pyleecan/Methods/Simulation/VarSimu/run.py	Improves progress logging robustness for optional OP fields.
pyleecan/Methods/Simulation/Magnetics/comp_axes.py	Forces time periodicity to non-antiperiod for stator-frame magnetic quantities.
pyleecan/Methods/Simulation/MagFEMM/solve_FEMM.py	Disables previous .ans reuse for sliding-band and always clears mi_setprevious.
pyleecan/Methods/Simulation/MagFEMM/comp_flux_airgap.py	Disables FEMM parallel execution for sliding-band calculations.
pyleecan/Methods/Simulation/ElecLUTdq/solve_power.py	Improves limit handling (None → inf), fixes selection conditions, adds region flags.
pyleecan/Methods/Simulation/ElecLUTdq/solve_MTPA.py	Improves limit handling, adds explicit “no feasible point” errors and region flags.
pyleecan/Methods/Simulation/ElecLUTdq/run.py	Routes torque requests to solve_torque; adjusts loss output attachment behavior.
pyleecan/Methods/Simulation/ElecLUTdq/comp_LUTdq.py	Applies LUT temperature context before LUT computation.
pyleecan/Methods/Output/LUT/set_default_simulation.py	Changes LUT default MagFEMM workers to 8.
pyleecan/Methods/Converter/RuleEquation/solve_equation.py	Makes SymPy import lazy and improves error reporting; sets env defaults.
pyleecan/GUI/Dxf/DXF_Surf.py	Lazily imports ezdxf.readfile to avoid import-time dependency failures.
pyleecan/GUI/Dxf/DXF_Slot.py	Lazily imports ezdxf.readfile to avoid import-time dependency failures.
pyleecan/GUI/Dxf/DXF_Hole.py	Lazily imports ezdxf.readfile to avoid import-time dependency failures.
pyleecan/Generator/ClassesRef/Simulation/ElecLUTdq.csv	Registers solve_torque method in generator metadata.
pyleecan/Functions/Simulation/LUTdq/thermal_hooks.py	Adds temperature hook utilities and context builders for future thermal coupling.
pyleecan/Functions/Simulation/LUTdq/save_inductance_map_cache.py	Adds NPZ/JSON caching for inductance-map outputs.
pyleecan/Functions/Simulation/LUTdq/save_efficiency_map_cache.py	Adds NPZ/JSON caching for efficiency-map outputs.
pyleecan/Functions/Simulation/LUTdq/run_op_matrix_lut.py	Adds generic OP-matrix runner using LUT + VarLoadCurrent.
pyleecan/Functions/Simulation/LUTdq/run_inductance_map_lut.py	Adds inductance-map builder from LUT flux interpolation with optional cache/plots.
pyleecan/Functions/Simulation/LUTdq/run_efficiency_map_lut.py	Adds end-to-end efficiency-map workflow (full-load then torque-map sweep).
pyleecan/Functions/Simulation/LUTdq/run_drive_cycle_lut.py	Adds drive-cycle runner through LUT + VarLoadCurrent plus summary integration.
pyleecan/Functions/Simulation/LUTdq/plot_inductance_map.py	Adds standard inductance-map plotting output.
pyleecan/Functions/Simulation/LUTdq/plot_efficiency_map.py	Adds standard efficiency-map plotting including region-colored envelopes.
pyleecan/Functions/Simulation/LUTdq/load_inductance_map_cache.py	Adds inductance-map cache loader.
pyleecan/Functions/Simulation/LUTdq/load_efficiency_map_cache.py	Adds efficiency-map cache loader.
pyleecan/Functions/Simulation/LUTdq/init.py	Exposes new LUTdq pipeline helpers via package exports.
pyleecan/Functions/Simulation/DriveCycle/summarize_drive_cycle_outputs.py	Adds integrated energy metrics + loss breakdown aggregation for drive cycles.
pyleecan/Functions/Simulation/DriveCycle/read_standard_drive_cycle.py	Adds packaged “standard segment” drive-cycle loaders and listing.
pyleecan/Functions/Simulation/DriveCycle/read_drive_cycle_csv.py	Adds robust drive-cycle CSV reader with aliasing and validation.
pyleecan/Functions/Simulation/DriveCycle/build_drive_cycle_op_matrix.py	Adds OPMatrix builder from drive-cycle trajectories (torque/power targets).
pyleecan/Functions/Simulation/DriveCycle/_utils.py	Adds shared drive-cycle validation and numerical integration helpers.
pyleecan/Functions/Simulation/DriveCycle/init.py	Exports DriveCycle helper functions.
pyleecan/Functions/ParaView/resolve_result_file.py	Adds VTU/VTK result discovery helper (latest timestep selection).
pyleecan/Functions/ParaView/render_vtu_screenshot.py	Adds pvpython/pvbatch screenshot rendering helper.
pyleecan/Functions/ParaView/launch_paraview.py	Adds ParaView GUI launcher helper.
pyleecan/Functions/ParaView/build_paraview_render_script.py	Generates a ParaView batch render script with array selection.
pyleecan/Functions/ParaView/init.py	Exposes ParaView helpers.
pyleecan/Functions/get_path_binary.py	Replaces distutils finder; adds env + Windows install path resolution.
pyleecan/Functions/FEMM/update_FEMM_simulation.py	Ensures FEMM circuits reset to zero when currents are absent.
pyleecan/Data/DriveCycle/WLTP_class3_segment.csv	Adds lightweight packaged WLTP segment data.
pyleecan/Data/DriveCycle/NEDC_segment.csv	Adds lightweight packaged NEDC segment data.
pyleecan/Classes/ElecLUTdq.py	Wires solve_torque method into ElecLUTdq class.
mock.py	Adds mock compatibility shim via unittest.mock.
Exe_gen/runtime_pyside6.py	Adds PyInstaller runtime hook for PySide6 DLL/plugin path handling + logging.
Exe_gen/pyleecan.spec	Refactors PyInstaller spec to collect PySide6/shiboken DLLs and localize paths.
Exe_gen/local_build_paths.py	Adds standardized .local/ packaging path layout helpers and migration.
Exe_gen/generate_pyleecan_exe.py	Refactors packaging flow to use .local layout and PyInstaller via subprocess.
Exe_gen/build_local_exe.py	Adds a convenience entrypoint for local EXE builds.
Doc/Prius_Elmer_Explicit_Circuit_CN.md	Documents validated Prius explicit-circuit configuration and baselines (CN).
Doc/Open_Source_Project_Governance_CN.md	Adds governance/process baseline document (CN).
Doc/Nissan_Leaf_2012_Validation_Summary_CN.md	Adds Leaf 2012 validation summary (CN).
Doc/LUT_Execution_CN.md	Documents LUT executors, efficiency map, drive-cycle pipeline, and conventions (CN).
Doc/Local_EXE_Build_CN.md	Documents local Windows EXE build workflow (CN).
Doc/Elmer_ParaView_Validation.md	Documents Elmer/ParaView validation workflow and current baselines (EN).
Doc/Efficiency_Map_DriveCycle_CN.md	Documents efficiency-map → control surface → drive-cycle integration workflow (CN).
Doc/Codeup_Admin_Checklist_CN.md	Adds Codeup admin checklist for protections/rules/pipelines (CN).
Doc/ADR/README.md	Adds ADR usage instructions.
Doc/ADR/0001-perf-roadmap-phase1-efficiency-map.md	Adds ADR describing the Phase 1 performance/efficiency-map roadmap.
Doc/ADR/0000-template.md	Adds ADR template.
CONTRIBUTING.md	Adds contribution workflow, branching, interface/testing expectations.
CHANGELOG.md	Adds initial changelog following “Keep a Changelog”.
AGENTS.md	Documents repo structure and verified commands/conventions.
.pre-commit-config.yaml	Adds/expands pre-commit hooks (whitespace, yaml/json, black, repo policy checks).
.gitignore	Expands ignored local/build/temp artifacts (including .local/).
.github/workflows/quality-gate.yml	Adds Windows CI quality gate (pre-commit + pytest -m star).
.github/PULL_REQUEST_TEMPLATE.md	Adds PR template with scope/validation/compat checklist.
.github/ISSUE_TEMPLATE/feature_request.yml	Adds feature request issue form.
.github/ISSUE_TEMPLATE/config.yml	Adds issue template config + links.
.github/ISSUE_TEMPLATE/bug_report.yml	Adds bug report issue form.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.