Coding Project 5 / Five-Sampling-Time SVPWM Waveform Study

Run the SVPWM tutorial, zoom into five sampling times, and reconstruct the zero-sequence voltage. 运行 SVPWM tutorial，放大到5 个 sampling time，并重构零序电压。

This version of Coding Project 5 is focused and concrete. You will run simulation/tutorials_ep6_svpwm.py, observe the key voltage and current waveforms within a window of exactly five control sampling periods, then compute and plot the zero-sequence voltage from theory and from numerical signals. 这一版 Coding Project 5 的要求非常聚焦。你要运行 simulation/tutorials_ep6_svpwm.py，在恰好 5 个控制采样周期的窗口内观察关键电压和电流波形，然后分别用理论表达式和数值信号计算并画出零序电压。

Core script核心脚本
simulation/tutorials_ep6_svpwm.py
Observation window观察窗口
5 × CTRL.CL_TS
Core quantity核心量
u_nG / u_ng / u_0
Report format报告格式
PDF / 4 required figures
Background / Why this matters

Why look at only five sampling times?为什么只看 5 个 sampling time？

Lecture 5 explains SVPWM as an actuator-side realization problem. But if you plot only long-time waveforms, you mainly see the slow envelope. The PWM structure, duty-ratio changes, terminal-voltage switching, and the role of zero-sequence voltage are much clearer when you zoom into a very short window. This project therefore asks for a five-sampling-time microscope view. Lecture 5 把 SVPWM 解释成执行器侧的实现问题。但如果你只画长时间波形，主要看到的是慢变化包络。PWM 结构、占空比变化、端电压切换以及零序电压的作用，都要在很短的时间窗口内才看得清楚。因此这次作业要求你做一个5 个采样周期的显微镜视图。

Core class message核心提示 This is a waveform-reading project. The point is not only to run the script, but to explain what each fast-switching waveform means physically. 这次是一个“读波形”的作业。重点不只是把脚本跑起来，而是要解释每个快速切换波形对应的物理含义。
Goal / Deliverable

Main deliverable核心交付物

You should be able to say:你最后应该能明确说明：

  1. Which voltage and current signals are visible inside five sampling times.在 5 个 sampling time 内，到底能看到哪些关键电压/电流信号。
  2. How the zero-sequence voltage is obtained from the theory formula involving the max and min of the three phase voltages.如何通过“三相相电压的 max / min”理论公式得到零序电压。
  3. How the same quantity can also be reconstructed numerically from the simulated inverter voltages.如何从仿真的逆变器电压信号中，用数值方式重构出同一个量。

Minimum result最低完成标准

  • Run the tutorial successfully.成功运行 tutorial。
  • Zoom into one five-sampling-time window.选取一个 5 个采样周期的放大窗口。
  • Plot and interpret the required signals.画出并解释要求的信号。

Strong result更强的完成效果

  • Compute both theoretical and numerical zero-sequence voltage.同时算出理论零序电压和数值零序电压。
  • Overlay them and explain any mismatch.把两者叠加比较，并解释偏差来源。
  • State your sign convention for u_0, u_nG, or u_ng clearly.明确说明你对 u_0、u_nG 或 u_ng 的定义与符号约定。
Setup / Practical Notes

How to run the tutorial for this assignment如何为本次作业运行 tutorial

Recommended setting推荐设置 To see switching details, set MACHINE_SIMULATIONs_PER_SAMPLING_PERIOD to a value much larger than 1, for example 50, 100, or 500. If it stays at 1, the fast PWM structure is too compressed or bypassed for this assignment. 为了看清开关细节，建议把 MACHINE_SIMULATIONs_PER_SAMPLING_PERIOD 设成远大于 1 的值，例如 50、100 或 500。如果保持为 1，这次作业所需要的快速 PWM 结构会看不清，甚至被近似绕过。 
# Suggested starting point
cd C:\Users\lenovo\Codes\ACMSimPy
python simulation\tutorials_ep6_svpwm.py

# Recommended next step
copy simulation\tutorials_ep6_svpwm.py simulation\study_svpwm_project5.py
Pick a time window of length 5 * CTRL.CL_TS.选取长度为 5 * CTRL.CL_TS 的观察窗口。
Choose the window after the initial transient, preferably where the waveform is already periodic.观察窗口尽量选在初始过渡结束之后，最好在波形已经进入周期状态的位置。
Add your own logging if the existing watch list is not enough.如果现有 watch list 不够用，就自己补充记录信号。
Signals / What to Observe

Key voltage and current waveforms inside five sampling times5 个 sampling time 内必须观察的关键电压电流波形

Signal group信号组 Recommended variables推荐变量 Why it matters为什么重要
Command voltages控制器电压命令 CTRL.cmd_uab[0], CTRL.cmd_uab[1], optionally reconstructed phase commands These are the control-side references before the inverter realizes them.这是进入逆变器之前的控制器参考电压。
Terminal or phase potentials端点或相电位 svgen1.voltage_potential_at_terminal[0:3] These are the most direct signals for reconstructing u_nG or u_ng.这是重构 u_nG 或 u_ng 最直接的信号。
Applied inverter voltages in $\alpha\beta$实际施加的 $\alpha\beta$ 电压 ACM.uab[0], ACM.uab[1] These show what the machine really receives after switching-level realization.这体现了开关级实现后电机真正接收到的电压。
Phase or Clarke currents相电流或 Clarke 电流 ACM.ia, ACM.ib, ACM.ic or CTRL.iab[0:2] These let you see how the current responds inside the short PWM window.这可以让你看到电流在短 PWM 窗口内的响应细节。
Important implementation note一个重要实现提醒 In this tutorial, some of the later watch_data entries are reused or commented in ways that can be confusing. So for this assignment, it is acceptable — and often better — to add your own explicit named logging for terminal voltages and reconstructed zero-sequence voltage. 这个 tutorial 里，后几路 watch_data 的标签和实际用途有些复用，直接照名字读可能会混淆。因此这次作业中，允许你自己补充更明确的信号记录，尤其是端点电压和零序电压。
Theory / Zero-Sequence Voltage

How to write the zero-sequence voltage expression如何写出零序电压表达式

Let the three phase-voltage commands before zero-sequence injection be $u_a^*,u_b^*,u_c^*$. You may reconstruct them from the inverse Clarke relation, or directly from your own code variables. 设零序注入之前的三相相电压参考为 $u_a^*,u_b^*,u_c^*$。你可以通过 inverse Clarke 关系把它们重构出来，也可以直接从你代码里已有的变量得到。

A convenient reconstruction is一种方便的重构方式是

$$ u_a^* = u_\alpha^*,\qquad u_b^* = -\frac{1}{2}u_\alpha^* + \frac{\sqrt{3}}{2}u_\beta^*,\qquad u_c^* = -\frac{1}{2}u_\alpha^* - \frac{\sqrt{3}}{2}u_\beta^*. $$

The standard zero-sequence injection expression is标准零序注入表达式是

$$ u_{0,\mathrm{th}} = -\frac{\max(u_a^*,u_b^*,u_c^*) + \min(u_a^*,u_b^*,u_c^*)}{2}. $$

Depending on your notation, you may report this as an injected common-mode voltage, or convert it into u_nG / u_ng. The sign depends on your definition, so you must state the convention explicitly.根据你的记号习惯，你可以把它写成注入的共模电压，也可以再转换成 u_nG / u_ng。但符号会依赖你的定义，所以必须先把参考节点和符号约定写清楚。

A numerical route from simulated terminal potentials is一种基于仿真端点电位的数值路线是

$$ u_{nG,\mathrm{num}} = \frac{u_{aG}+u_{bG}+u_{cG}}{3}, \qquad u_{an}=u_{aG}-u_{nG},\; u_{bn}=u_{bG}-u_{nG},\; u_{cn}=u_{cG}-u_{nG}. $$
What is acceptable可接受的写法 It is acceptable if your report uses either u_0, u_nG, or u_ng, as long as you define the node names clearly and keep the sign convention consistent throughout the report. 如果你的报告使用的是 u_0、u_nG 或 u_ng 中的任意一种，都是可以接受的；但你必须把节点含义写清楚，并在全文中保持符号约定一致。
Experiments / Required Work

Required experiments必做实验

Experiment 1: Run and zoom实验 1：运行并放大

  1. Run tutorials_ep6_svpwm.py with switching-level inverter behavior enabled.在启用开关级逆变器行为的条件下运行 tutorials_ep6_svpwm.py。
  2. Pick one short time interval of exactly five control sampling periods.选取一个长度恰好为 5 个控制采样周期的时间区间。
  3. Use this same window for all required plots.后面所有必做图都尽量使用同一个窗口。

Experiment 2: Voltage and current observation实验 2：电压与电流波形观察

  1. Plot the key voltage signals inside the five-sampling-time window.在 5 个采样周期窗口里画出关键电压信号。
  2. Plot the key current signals in the same window.在同一个窗口里画出关键电流信号。
  3. Comment on which signals switch rapidly and which ones look averaged.说明哪些信号快速切换，哪些信号更像平均量。

Experiment 3: Theoretical zero-sequence reconstruction实验 3：理论零序电压重构

  1. Reconstruct the three phase-voltage commands.重构三相相电压参考。
  2. Use the max/min formula to compute the theoretical zero-sequence voltage.用 max/min 公式计算理论零序电压。
  3. Plot that quantity in the same five-sampling-time window.在同一个 5 个采样周期窗口内画出来。

Experiment 4: Numerical zero-sequence reconstruction实验 4：数值零序电压重构

  1. Use simulated terminal voltages or direct subtraction/averaging to compute u_nG or u_ng.利用仿真的端点电压，或者直接通过数值相减/求平均，计算 u_nG 或 u_ng。
  2. Overlay the numerical result with the theoretical result.把数值结果和理论结果叠加比较。
  3. Explain whether any difference is due to sign convention, implementation details, or logging choice.解释差异究竟来自符号约定、实现细节，还是记录方式。
Figures / Required in the PDF

Four required figures4 张必做图

F1

Voltage-waveform zoom电压波形放大图

A five-sampling-time zoom showing the key voltage signals. At minimum, include controller voltage reference plus inverter-side voltage signals that are actually used to reconstruct the zero-sequence quantity.一个 5 个采样周期窗口下的电压波形放大图。至少要包含控制器电压参考，以及后面用来重构零序量的逆变器侧电压信号。

F2

Current-waveform zoom电流波形放大图

A five-sampling-time zoom showing the key current signals, such as $i_a,i_b,i_c$ or the Clarke currents. Your caption should state exactly which current coordinates you chose.一个 5 个采样周期窗口下的电流波形放大图，例如 $i_a,i_b,i_c$ 或 Clarke 电流。图注里要明确说明你选的是哪一组电流坐标。

F3

Theoretical zero-sequence voltage理论零序电压图

Plot the zero-sequence voltage obtained from the theoretical max/min expression. If you call it u_0, u_nG, or u_ng, define that choice explicitly in the caption.画出通过理论 max/min 表达式得到的零序电压。如果你把它记成 u_0、u_nG 或 u_ng，必须在图注中写清楚。

F4

Numerical vs theoretical comparison数值与理论对比图

Overlay the numerically reconstructed zero-sequence voltage with the theoretical one. If you prefer, add a second subplot for their difference.把数值重构的零序电压和理论零序电压叠加到同一张图里。若需要，也可以加第二个子图来画它们的误差。

Analysis / Explain the Results

Questions your report must answer报告必须回答的问题

Q1

Why is a five-sampling-time zoom more informative for SVPWM than a long-time full-run plot?为什么对于 SVPWM 来说，5 个采样周期的放大图比长时间全程图更有信息量？

Q2

Which of your observed voltage signals are control references, and which ones are already inverter-realized quantities?你观察到的电压信号里，哪些是控制器参考，哪些已经是逆变器实现后的量？

Q3

Why does the theoretical zero-sequence voltage depend on the max and min of the three phase-voltage commands?为什么理论零序电压会和三相相电压参考的 max 与 min 有关？

Q4

How did you numerically reconstruct u_nG or u_ng, and what sign convention did you use?你是怎样数值重构 u_nG 或 u_ng 的？你的符号约定是什么？

Q5

If the theoretical and numerical curves are not identical, what are the most plausible reasons: sign convention, discretization, PWM realization, or logging mismatch?如果理论曲线和数值曲线不完全重合，最可能的原因是什么：符号约定、离散化、PWM 实现，还是记录信号不一致？

Q6

How do your figures help explain the statement “SVPWM uses zero-sequence freedom without changing the desired line voltages”?你的图是怎样帮助解释“SVPWM 利用零序自由度，但不改变目标线电压”这句话的？

What strong reports do好的报告会这样做 They do not only show a formula. They also show how that formula becomes a measurable waveform in the tutorial. 好的报告不只是把公式抄出来，而是要把公式和 tutorial 里真正可观测到的波形对应起来。
Report / PDF Only

Suggested PDF structure建议的 PDF 结构

Recommended outline推荐提纲

  1. State the script, the sampling-time definition, and your observation window.说明所用脚本、采样周期定义和观察窗口。
  2. List the voltage and current signals you observed.列出你观察的电压和电流信号。
  3. Derive the theoretical zero-sequence expression.推导理论零序电压表达式。
  4. Explain the numerical reconstruction method.解释数值重构方法。
  5. Show F1–F4 and answer Q1–Q6.展示 F1–F4，并回答 Q1–Q6。

Checklist before export导出 PDF 前检查

All 4 required figures are present and use the same five-sampling-time window where appropriate.4 张必做图齐全，并尽量使用同一个 5 个采样周期窗口。
Your report clearly defines u_0, u_nG, or u_ng.报告里明确给出了 u_0、u_nG 或 u_ng 的定义。
The theoretical max/min formula is written correctly.理论 max/min 公式书写正确。
The numerical reconstruction route is explained clearly.数值重构路线解释清楚。
Any mismatch between theory and numerical curves is discussed rather than ignored.理论与数值曲线若有差异，报告里有解释，而不是直接忽略。
Axes, units, legends, and the exact time window are readable.坐标轴、单位、图例和具体时间窗口都清楚可读。

Suggested filename: codingProject5_name.pdf建议文件名：codingProject5_姓名.pdf