Python 调用 MWORKS 已有库函数完整案例

案例名称

Python 调用 MWORKS 信号处理库完成电机转速信号去噪与控制性能评估

---

1. 案例定位

本案例面向已经熟悉 Python 的工程用户，演示如何在 Syslab 的 Python 环境中调用 MWORKS / Syslab 已有函数库，并完成一个相对完整的工程数据分析任务。

案例不只是展示 import 和函数调用，而是围绕一个电机闭环调速场景，完整展示以下流程：

1. 使用 Python 构造电机转速响应数据；
2. 模拟传感器测量噪声、尖峰异常点和高频抖动；
3. 调用 MWORKS 信号处理工具箱函数进行滤波；
4. 对比滤波前后的信号变化；
5. 计算控制系统常用性能指标；
6. 保存数据、图片和分析报告；
7. 可进一步通过 MWORKS AI / Syslab MCP 自动生成、运行和解释结果。

---

2. 适用教学场景

本案例适合放在以下课程或教程中：

• Syslab 多语言编程；
• Python 调用 MWORKS / Syslab 工具箱；
• MWORKS AI 自动生成与执行工程脚本；
• 电机控制仿真数据后处理；
• Sysplorer / Sysblock / Syslab 联合仿真后处理；
• 工程信号处理入门案例。

---

3. 用户问题

用户提出的问题可以归纳为：

我已经会 Python，如何调用 MWORKS 已有的科学计算库？

进一步展开后，用户通常关心以下问题：

用户关心点	教程回答方式
Python 能不能直接调用 MWORKS 函数库？	使用 from mworks import TySignalProcessing 导入工具箱
调用后的数据能不能继续用 Python 分析？	将返回结果转换为 numpy 数组后继续处理
能不能用于工程数据，而不是简单数学例子？	构造电机转速传感器数据分析案例
能不能让 AI 自动生成和运行代码？	使用 MWORKS AI / Syslab MCP 执行脚本并返回结果

---

4. 案例背景

假设有一个永磁直流电机转速闭环控制系统，目标转速为：

1500 rpm

电机启动后，转速逐渐上升并接近目标值。实际工程中，转速传感器采集到的信号往往不是完全平滑的，可能包含以下干扰：

1. 随机测量噪声；
2. 高频抖动；
3. 个别尖峰异常点；
4. 稳态阶段的小幅波动。

如果直接使用原始测量信号计算控制指标，可能会导致超调量、调节时间、稳态误差和稳态抖动等评价结果不准确。

因此，本案例使用 Python 构造一段电机转速测试数据，并调用 MWORKS 信号处理库中的 medfilt1 函数对测量信号进行中值滤波，再对滤波前后的控制效果进行定量分析。

---

5. 教学目标

完成本案例后，学员应理解并掌握：

1. 如何在 Syslab 的 Python 环境中调用 MWORKS 已有库函数；
2. 如何使用 MWORKS 信号处理工具箱函数处理 Python 数据；
3. 如何将 MWORKS 函数返回结果继续交给 Python 分析；
4. 如何针对电机转速响应计算控制性能指标；
5. 如何把脚本、图像、数据和报告组织成一个完整工程案例；
6. 如何将该流程扩展为 MWORKS AI / Syslab MCP 自动化教程。

---

6. 案例总体流程

构造电机闭环转速响应
        ↓
加入传感器噪声、高频抖动和尖峰异常点
        ↓
Python 导入 MWORKS 信号处理工具箱
        ↓
调用 TySignalProcessing.medfilt1 进行滤波
        ↓
绘制真实转速、测量转速、滤波转速对比图
        ↓
计算滤波前后的控制性能指标
        ↓
保存 CSV 数据、PNG 图片和 Markdown 报告
        ↓
可选：由 MWORKS AI / Syslab MCP 自动执行并解释结果

---

7. 推荐文件结构

建议将案例组织为如下目录结构：

python_call_mworks_motor_case/
├─ motor_speed_analysis.py
├─ results/
│  ├─ motor_speed_data.csv
│  ├─ motor_speed_filter_compare.png
│  └─ motor_speed_analysis_report.md
└─ README.md

其中：

文件	作用
motor_speed_analysis.py	主程序脚本
motor_speed_data.csv	保存转速数据
motor_speed_filter_compare.png	保存滤波前后对比图
motor_speed_analysis_report.md	保存分析报告
README.md	案例说明文档

---

8. 核心调用方式

本案例的核心调用方式如下：

from mworks import TySignalProcessing

filtered_speed = TySignalProcessing.medfilt1(measured_speed, 9)

含义如下：

代码	含义
from mworks import TySignalProcessing	从 MWORKS 中导入信号处理工具箱
measured_speed	Python 中的一维转速测量数据
medfilt1(measured_speed, 9)	使用长度为 9 的窗口进行一维中值滤波
filtered_speed	滤波后的转速数据

---

9. 完整 Python 示例代码

建议在 Syslab 的 Python 环境中新建 motor_speed_analysis.py 文件，并粘贴以下代码运行。

# motor_speed_analysis.py
# 案例：Python 调用 MWORKS 信号处理库完成电机转速信号去噪与控制性能评估

from mworks import TySignalProcessing

import os
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt


# ============================================================
# 1. 构造电机转速闭环响应数据
# ============================================================

def generate_motor_speed_data():
    """
    构造一个电机转速闭环响应数据：
    - target_speed: 目标转速
    - true_speed: 理想转速响应
    - measured_speed: 加入噪声和尖峰后的传感器测量值
    """
    np.random.seed(42)

    target_speed = 1500.0  # rpm
    t_end = 5.0
    fs = 200               # 采样频率 200 Hz
    t = np.arange(0, t_end, 1 / fs)

    # 构造一个带轻微超调的二阶响应近似
    # 用于模拟电机转速从 0 rpm 上升到 1500 rpm
    damping = 0.55
    wn = 8.0
    wd = wn * np.sqrt(1 - damping ** 2)

    true_speed = target_speed * (
        1
        - np.exp(-damping * wn * t)
        * (
            np.cos(wd * t)
            + damping / np.sqrt(1 - damping ** 2) * np.sin(wd * t)
        )
    )

    # 加入传感器随机噪声
    random_noise = np.random.normal(0, 18, size=len(t))

    # 加入稳态小幅高频抖动
    high_freq_noise = 12 * np.sin(2 * np.pi * 45 * t)

    # 加入尖峰异常点
    spike_noise = np.zeros_like(t)
    spike_indices = np.random.choice(len(t), size=12, replace=False)
    spike_noise[spike_indices] = np.random.choice([-120, 120], size=12)

    measured_speed = true_speed + random_noise + high_freq_noise + spike_noise

    return t, target_speed, true_speed, measured_speed


# ============================================================
# 2. 调用 MWORKS 信号处理库进行滤波
# ============================================================

def filter_speed_with_mworks(measured_speed, window_size=9):
    """
    调用 MWORKS / Syslab 信号处理工具箱函数 medfilt1 进行中值滤波。
    medfilt1 适合去除尖峰类异常噪声。
    """
    filtered_speed = TySignalProcessing.medfilt1(measured_speed, window_size)

    # 将返回值统一转换为 numpy 数组，便于后续 Python 分析
    filtered_speed = np.asarray(filtered_speed, dtype=float)

    return filtered_speed


# ============================================================
# 3. 控制性能指标计算
# ============================================================

def calculate_control_metrics(t, target_speed, speed):
    """
    计算几个常用控制效果指标：
    - 最大超调量
    - 稳态误差
    - 调节时间
    - 稳态抖动 RMS
    """

    # 最大超调量
    max_speed = np.max(speed)
    overshoot = max(0.0, (max_speed - target_speed) / target_speed * 100)

    # 取最后 20% 时间作为稳态区间
    steady_start_index = int(len(t) * 0.8)
    steady_speed = speed[steady_start_index:]

    # 稳态误差
    steady_mean = np.mean(steady_speed)
    steady_error = steady_mean - target_speed

    # 稳态抖动 RMS
    steady_jitter_rms = np.sqrt(np.mean((steady_speed - steady_mean) ** 2))

    # 调节时间：进入 ±2% 误差带并保持到结束
    tolerance = 0.02 * target_speed
    settling_time = None

    for i in range(len(speed)):
        remaining_error = np.abs(speed[i:] - target_speed)
        if np.all(remaining_error <= tolerance):
            settling_time = t[i]
            break

    return {
        "max_speed_rpm": float(max_speed),
        "overshoot_percent": float(overshoot),
        "steady_mean_rpm": float(steady_mean),
        "steady_error_rpm": float(steady_error),
        "steady_jitter_rms_rpm": float(steady_jitter_rms),
        "settling_time_s": None if settling_time is None else float(settling_time),
    }


# ============================================================
# 4. 绘图与结果保存
# ============================================================

def save_results(t, target_speed, true_speed, measured_speed, filtered_speed, output_dir):
    os.makedirs(output_dir, exist_ok=True)

    # 保存 CSV 数据
    csv_path = os.path.join(output_dir, "motor_speed_data.csv")
    df = pd.DataFrame({
        "time_s": t,
        "target_speed_rpm": target_speed,
        "true_speed_rpm": true_speed,
        "measured_speed_rpm": measured_speed,
        "filtered_speed_rpm": filtered_speed,
    })
    df.to_csv(csv_path, index=False, encoding="utf-8-sig")

    # 绘制滤波前后对比图
    fig_path = os.path.join(output_dir, "motor_speed_filter_compare.png")

    plt.figure(figsize=(10, 6))
    plt.plot(t, true_speed, label="True speed")
    plt.plot(t, measured_speed, label="Measured speed", alpha=0.55)
    plt.plot(t, filtered_speed, label="Filtered speed")
    plt.axhline(target_speed, linestyle="--", label="Target speed")

    plt.xlabel("Time / s")
    plt.ylabel("Speed / rpm")
    plt.title("Motor Speed Signal Filtering with MWORKS TySignalProcessing.medfilt1")
    plt.legend()
    plt.grid(True)
    plt.tight_layout()
    plt.savefig(fig_path, dpi=200)
    plt.show()

    return csv_path, fig_path


# ============================================================
# 5. 生成分析报告
# ============================================================

def save_report(raw_metrics, filtered_metrics, csv_path, fig_path, output_dir):
    report_path = os.path.join(output_dir, "motor_speed_analysis_report.md")

    def fmt(value):
        if value is None:
            return "未进入 ±2% 稳定带"
        return f"{value:.4f}"

    report = f"""# 电机转速信号去噪与控制性能评估报告

## 1. 案例说明

本案例使用 Python 构造电机闭环调速响应数据，并调用 MWORKS / Syslab 信号处理工具箱函数 `TySignalProcessing.medfilt1` 对传感器测量转速进行中值滤波。

## 2. 输出文件

- 数据文件：`{csv_path}`
- 对比图：`{fig_path}`

## 3. 原始测量信号指标

| 指标 | 数值 |
|---|---:|
| 最大转速 / rpm | {fmt(raw_metrics["max_speed_rpm"])} |
| 最大超调量 / % | {fmt(raw_metrics["overshoot_percent"])} |
| 稳态平均转速 / rpm | {fmt(raw_metrics["steady_mean_rpm"])} |
| 稳态误差 / rpm | {fmt(raw_metrics["steady_error_rpm"])} |
| 稳态抖动 RMS / rpm | {fmt(raw_metrics["steady_jitter_rms_rpm"])} |
| 调节时间 / s | {fmt(raw_metrics["settling_time_s"])} |

## 4. 滤波后信号指标

| 指标 | 数值 |
|---|---:|
| 最大转速 / rpm | {fmt(filtered_metrics["max_speed_rpm"])} |
| 最大超调量 / % | {fmt(filtered_metrics["overshoot_percent"])} |
| 稳态平均转速 / rpm | {fmt(filtered_metrics["steady_mean_rpm"])} |
| 稳态误差 / rpm | {fmt(filtered_metrics["steady_error_rpm"])} |
| 稳态抖动 RMS / rpm | {fmt(filtered_metrics["steady_jitter_rms_rpm"])} |
| 调节时间 / s | {fmt(filtered_metrics["settling_time_s"])} |

## 5. 结果解释

1. 原始测量信号中包含随机噪声、高频抖动和尖峰异常点。
2. `medfilt1` 中值滤波能够有效抑制尖峰类异常点。
3. 滤波后信号更适合用于计算稳态误差、稳态抖动和调节时间等控制性能指标。
4. 对于实际工程数据，滤波窗口不宜过大，否则可能削弱真实动态响应特征。

## 6. 教程结论

该案例说明：Python 用户可以在 Syslab 环境中直接调用 MWORKS 已有工具箱函数，将 Python 的数据处理流程与 MWORKS 的科学计算函数库结合起来，用于工程信号分析和控制效果评估。
"""

    with open(report_path, "w", encoding="utf-8") as f:
        f.write(report)

    return report_path


# ============================================================
# 6. 主程序
# ============================================================

def main():
    output_dir = "results"

    # 生成数据
    t, target_speed, true_speed, measured_speed = generate_motor_speed_data()

    # 调用 MWORKS 信号处理工具箱
    filtered_speed = filter_speed_with_mworks(measured_speed, window_size=9)

    # 分别计算滤波前后指标
    raw_metrics = calculate_control_metrics(t, target_speed, measured_speed)
    filtered_metrics = calculate_control_metrics(t, target_speed, filtered_speed)

    # 保存数据和图片
    csv_path, fig_path = save_results(
        t,
        target_speed,
        true_speed,
        measured_speed,
        filtered_speed,
        output_dir
    )

    # 保存报告
    report_path = save_report(
        raw_metrics,
        filtered_metrics,
        csv_path,
        fig_path,
        output_dir
    )

    print("========== 分析完成 ==========")
    print(f"CSV 数据文件：{csv_path}")
    print(f"结果图片：{fig_path}")
    print(f"分析报告：{report_path}")

    print("\n--- 原始信号指标 ---")
    for k, v in raw_metrics.items():
        print(f"{k}: {v}")

    print("\n--- 滤波后信号指标 ---")
    for k, v in filtered_metrics.items():
        print(f"{k}: {v}")


if __name__ == "__main__":
    main()

---

10. 代码讲解

10.1 数据构造

t, target_speed, true_speed, measured_speed = generate_motor_speed_data()

该步骤用于模拟一个电机闭环调速响应过程：

• target_speed：目标转速，设为 1500 rpm；
• true_speed：近似真实转速响应；
• measured_speed：加入噪声后的传感器测量转速。

为了让案例更接近真实工程数据，测量信号中加入了：

1. 随机噪声；
2. 高频噪声；
3. 尖峰异常点。

---

10.2 调用 MWORKS 信号处理库

filtered_speed = TySignalProcessing.medfilt1(measured_speed, window_size)

该语句是整个案例的核心。它说明 Python 脚本中的数据可以直接传入 MWORKS / Syslab 的信号处理函数中进行计算。

中值滤波适合处理尖峰异常点。例如电机转速传感器中可能出现瞬时跳点、编码器脉冲异常或采集毛刺，这类异常值会明显影响最大超调量、稳态误差和调节时间的判断。

---

10.3 控制性能指标计算

案例中计算了四类指标：

指标	含义	计算目的
最大超调量	最大转速超过目标转速的比例	判断启动过程是否过冲
稳态误差	稳态平均转速与目标转速的差值	判断控制精度
调节时间	进入目标值 ±2% 范围并保持到结束的时间	判断系统响应快慢
稳态抖动 RMS	稳态阶段围绕平均值的波动强度	判断转速稳定性

---

10.4 结果保存

脚本会自动生成三个结果文件：

results/motor_speed_data.csv
results/motor_speed_filter_compare.png
results/motor_speed_analysis_report.md

其中：

• CSV 文件用于保存数据，方便后续复查；
• PNG 图片用于展示滤波前后对比效果；
• Markdown 报告用于记录计算指标和结论。

---

11. 教学讲解建议

11.1 讲解主线

可以按以下逻辑讲：

1. 用户已经会 Python，不希望重新学习一套复杂接口；
2. MWORKS / Syslab 中已经沉淀了大量工程计算函数；
3. Python 可以作为流程控制和数据处理入口；
4. MWORKS 工具箱函数负责工程算法计算；
5. 结果回到 Python 后继续做可视化和报告生成；
6. MWORKS AI / Syslab MCP 可以进一步完成代码生成、运行验证和结果解释。

---

11.2 关键话术

可以这样向用户解释：

本案例不是让 Python 替代 Syslab，也不是让用户重新学习 Julia，而是让已有 Python 用户可以直接调用 MWORKS/Syslab 中已经沉淀好的科学计算库。Python 负责数据组织、流程控制和结果展示，MWORKS 函数库负责高质量工程计算，MWORKS AI 和 Syslab MCP 负责自动生成、执行和解释结果。

---

12. MWORKS AI / Syslab MCP 演示口令

在课堂或演示中，可以直接给 MWORKS AI 输入以下口令：

请在 Syslab 的 Python 环境中生成并运行一个完整案例：Python 调用 MWORKS 信号处理库完成电机转速信号去噪与控制性能评估。

要求：
1. 使用 Python 构造一个永磁直流电机闭环调速响应，目标转速为 1500 rpm；
2. 模拟传感器测量信号，包括随机噪声、高频抖动和尖峰异常点；
3. 使用 from mworks import TySignalProcessing 导入 MWORKS 信号处理工具箱；
4. 调用 TySignalProcessing.medfilt1 对转速测量信号进行中值滤波；
5. 绘制真实转速、原始测量转速、滤波后转速和目标转速的对比图；
6. 计算滤波前后的最大超调量、稳态误差、调节时间和稳态抖动 RMS；
7. 保存 CSV 数据、结果图片和 Markdown 分析报告；
8. 请通过 Syslab MCP 实际运行脚本，并返回运行日志、输出文件路径和结果分析结论。

---

13. MCP 执行验收点

如果该案例作为 MCP 教程使用，建议要求 AI 最终返回以下验收信息：

验收项	期望结果
脚本是否成功运行	是
是否成功导入 MWORKS 工具箱	成功导入 TySignalProcessing
是否成功调用滤波函数	成功调用 medfilt1
是否生成 CSV 数据	生成 results/motor_speed_data.csv
是否生成结果图片	生成 results/motor_speed_filter_compare.png
是否生成分析报告	生成 results/motor_speed_analysis_report.md
控制指标是否输出	输出超调量、稳态误差、调节时间、稳态抖动 RMS
结果是否有解释	给出滤波前后效果分析

---

14. 预期结果说明

运行成功后，用户应看到一张包含四条曲线的对比图：

1. 目标转速线；
2. 理想转速响应；
3. 带噪声的测量转速；
4. 滤波后的转速。

通常可以观察到：

• 原始测量转速中存在明显尖峰和高频抖动；
• 滤波后曲线更平滑；
• 稳态抖动 RMS 通常会下降；
• 控制性能指标更适合基于滤波后的信号进行评价。

---

15. 可扩展方向

本案例可以继续扩展为以下方向：

扩展方向	示例
读取真实测试数据	从 CSV / Excel 中读取电机转速采样数据
对接 Sysplorer 仿真结果	读取 Sysplorer 导出的仿真结果文件
对接 Sysblock 控制器	分析 Sysblock 控制器输出响应
增加频域分析	调用信号处理工具箱做频谱分析
增加控制系统分析	计算阶跃响应、带宽、稳定裕度等指标
增加报告自动生成	自动生成 Markdown / Word / PDF 报告
增加 AI 自动诊断	让 MWORKS AI 判断噪声来源和控制效果问题

---

16. 课堂演示建议

建议课堂演示分为三段：

第一段：人工讲解代码

重点说明：

from mworks import TySignalProcessing

让用户理解 Python 可以直接调用 MWORKS 工具箱。

第二段：运行完整案例

展示：

• 数据生成；
• 调用滤波函数；
• 生成图像；
• 输出指标；
• 保存报告。

第三段：MWORKS AI 自动生成

展示自然语言口令：

请生成一个 Python 调用 MWORKS 信号处理库的电机转速去噪案例，并通过 Syslab MCP 运行验证。

让用户看到从自然语言到可运行工程脚本的完整闭环。

---

17. 教程结论

本案例说明，Python 用户可以通过 Syslab 的多语言能力调用 MWORKS 已有函数库，将 Python 的灵活数据处理能力与 MWORKS 的工程计算能力结合起来。

对于培训和产品演示来说，该案例的价值不在于单个滤波函数，而在于展示了一条完整路径：

Python 用户需求
    ↓
调用 MWORKS 已有工具箱
    ↓
完成工程数据分析
    ↓
生成图表和指标
    ↓
输出分析报告
    ↓
MWORKS AI / Syslab MCP 自动化运行和解释

因此，该案例可以作为“Python 调用 MWORKS 已有库”的完整教程样例，也可以作为后续控制系统、信号处理、工程仿真后处理类 AI 教程的基础模板。

使用许可

本模型库版权由MoHub版权所有，未经许可，不得用于商业用途。