Creating array-based NumPy trace step templates(创建基于数组的 NumPy trace step 模板)

创建新 trace step 模板的流程已在章节 General approach(一般方法) 中说明。尽管各种模板在信号和参数的创建方式上相同,但实际分析逻辑的实现方式差异明显。

基于数组的 NumPy trace step 模板允许使用用户自定义 Python 代码,以 NumPy 数组形式访问所有输入和输出信号的数值与时间戳。每个此类模板的核心都是实现类中的 Process() 方法。该方法在每次 Trace 分析运行时调用一次,并接收以下参数:

parameters:

Python 字典,包含模板中定义的每个 trace step 参数的取值。

report:

用于访问测试报告的对象。

timeAxis:

由简单时间戳组成的公共时间轴 NumPy 数组。

ranges:

触发区间列表。对于不含触发器的分析,会提供一个覆盖公共时间轴所描述全部时间范围的单一区间。

signals:

Python 字典,包含模板中定义的每个输入和输出信号对应的信号对象。通过这些信号对象,可以访问相应信号在其整个时间范围内的数值和时间戳。

有关基于数组的 NumPy Trace 步骤模板的所有相关方法和接口的完整说明,以及在外部编辑器中启用类型检查和自动补全的提示, 请参见 Trace Analysis API 文档。

建议进一步阅读

下列教程和示例适合作为基于数组的 NumPy trace step 模板的延伸阅读。所有教程都默认读者具备 Python 编程基础。若具备 NumPy 基础会更有帮助,这部分内容可通过阅读章节 Using NumPy(使用 NumPy) 获得。

Example: Calculating an output signal(示例:计算输出信号)

教程 Creating an array-based NumPy trace step template(创建基于数组的 NumPy trace step 模板) 逐步构建了 trace step 模板 CheckTreshold,用于检查信号是否超过给定阈值。在此基础上,本示例将重点说明如何将两个信号相加,并对得到的和信号执行阈值检查。

为了保持模板 CheckThresold 不变并可继续复用,更合理的做法是在独立的 trace step 中完成信号计算,再在后续应用 CheckThreshold。因此,本示例说明如何开发基于数组的 NumPy trace step 模板 AddSignals,对两个信号求和并将结果写入第三个信号。

首先,创建一个名为 AddSignals 的新基于数组的 NumPy trace step 模板(如tutorial(教程)所示),并声明以下信号:

  • Signal1 和 Signal2,方向为 IN

  • Signal3,方向为 OUT

该模板的 Process() 方法需按如下方式实现:

def Process(self, parameters, report, timeAxis, ranges, signals):
    """
    ...

    """
    outSignal = signals['Signal3']
    for triggerRange in ranges:
        timestamps = triggerRange.GetTimestamps()
        outValues = triggerRange.GetValues('Signal1') + triggerRange.GetValues('Signal2')

        outSignal.Emit(timestamps, outValues)

要使用 trace step 模板 AddSignals,必须在 Trace 分析中至少声明三个通用信号:两个用于相加,另一个用于接收计算得到的和信号。后者就是随后要通过 CheckThreshold 检查的信号。

创建好模板 AddSignals 后,按照以下步骤完成最初提出的整体任务:

  • 创建一个新的 Package。

  • 插入 SigAB.csv(位于文件夹 ExampleTraces/NumPyArrayBased)及其中两个信号 SigA 和 SigB 作为信号记录,具体方法见章节 How to create a package with a trace analysis(如何创建包含 Trace 分析的 Package)。

  • 创建一个新的 Trace 分析。

  • 声明三个通用信号 Signal1、Signal2 和 Signal3。

  • 将记录信号 SigA 绑定到 Signal1,将记录信号 SigB 绑定到 Signal2。

  • 使用新建模板 AddSignals 创建一个 trace step,并将其输入和输出信号绑定到 Trace 分析中同名的通用信号。

  • 使用教程中开发的模板 CheckThreshold 创建一个 trace step。将通用信号 Signal3(包含 AddSignal step 输出结果)绑定到其输入信号,并将 threshold 设为 10。

  • 在 CheckTreshold step 上附加一个绘图 step。配置该图,使除 CheckThreshold 的输入信号外,还绘制通用信号 Signal1 和 Signal2(将这些信号从 not plotted 拖到 Upper plot)。对所有信号都设置标记样式 ‘o’(双击各信号后选择该样式)。

运行该 Trace 分析后,生成的测试报告将包含下图:

../../../../../_images/Beispiel_AddSignals_Plot.png

和信号的阈值检查结果

图中蓝色和灰色分别表示记录信号 SigA 和 SigB,橙色表示和信号。此外,从时间戳 7 开始的区间以红色高亮,因为从该时刻起和信号超过了阈值。

Example: Time axis definition(示例:时间轴定义)

在前一个示例中,两个信号 SigA 和 SigB 来自同一个 CSV 文件 SigAB.csv,因此采样时间完全一致。如果改为加入文件 SigC.csv 中的另一个记录信号 SigC(同样位于文件夹 ExampleTraces/NumPyArrayBased),并将其绑定到通用信号 Signal2(即对 SigA 与 SigC 求和),则会得到不同的结果图:

../../../../../_images/Beispiel_TimeAxis_or.png

采用标准时间轴定义(‘Signal1 or Signal2’)的和信号阈值检查

图中用实心圆标出了采样时刻,以强调这样一个事实:只要 Signal1 或 Signal2 任一发生采样,就会计算 Signal3。换言之,这里形成了一个公共时间轴,其中包含 Signal1 和 Signal2 两者的采样时刻。这是构建公共时间轴的标准规则,可通过表达式 Signal1 or Signal2 表示。当在新建基于数组的 NumPy trace step 模板向导中勾选 Time axis definition 选项时,该表达式会自动预填入:

../../../../../_images/Beispiel_TimeAxis_Wizard.png

带时间轴定义的基于数组 NumPy trace step 模板创建向导

不过,也可以在向导中或稍后在方法 GetTimeAxisDefinition() 中指定其他时间轴定义。将该方法实现为如下形式:

def GetTimeAxisDefinition(cls):
    return 'Signal1 and Signal2'

则会定义一个公共时间轴,其中仅包含 Signal1 和 Signal2 同时被采样的时间戳。测试报告中将得到如下图所示结果:

../../../../../_images/Beispiel_TimeAxis_and.png

采用时间轴定义 ‘Signal1 and Signal2’ 的和信号阈值检查

下面的时间轴定义仅采用 Signal2 的采样时刻:

def GetTimeAxisDefinition(cls):
    return 'Signal2'

应用该时间轴定义后,将得到如下图所示结果:

../../../../../_images/Beispiel_TimeAxis_SigC.png

采用时间轴定义 ‘Signal2’ 的和信号阈值检查

信息

在基于数组的 NumPy trace step 模板的 Process() 方法中,触发区间 triggerRange 的 triggerRange.GetValues(...) 和 triggerRange.GetTimestamps() 方法始终基于公共时间轴。因此,如果原始信号在公共时间轴所包含的某个时间戳上没有采样,这些方法可能会按照 sample-and-hold 原则引入附加采样点。

信号对象 signal 的方法 signal.GetValues(...) 和 signals.GetTimestamps(...) 返回的是原始采样点。也可以通过指定可选参数 fromTo,将其限制在特定时间范围内。

更多细节请参见 Trace Analysis API 文档。

Example: Helper functions(示例:辅助函数)

基于数组的 NumPy trace step 模板必须继承类 NumPyBasedTraceStep。 除定义通用接口外,该类还提供了一些实用的辅助函数,您可以在自己的模板中通过 self. 或 NumPyBasedTraceStep. 调用。下面以一个 Process 方法为例说明这些辅助方法的用法。

def Process(self, parameters, report, timeAxis, ranges, signals):
    """
    ...

    """
    # Non-interpolated timestamps and values of Signal1
    signal1 = signals['Signal1']
    actualTimestamps = signal1.GetTimestamps()
    actualValues = signal1.GetValues()

    ############################################################################################
    # FitToAxis
    ############################################################################################
    # Example: Interpolate values of Signal1 to another time axis using sample and hold
    #
    # In this example, timeAxis, i.e. the common time axis of all input signals of the
    # template-based trace step, is used as the target time axis.

    interpValues = self.FitToAxis(actualTimestamps, actualValues, timeAxis)

    print(actualTimestamps)  # [0.0,      1.0,      2.0]
    print(actualValues)      # [1.0,      5.0,      9.0]
    print(timeAxis)          # [0.0, 0.5, 1.0, 1.5, 2.0, 2.5]
    print(interpValues)      # [1.0, 1.0, 5.0, 5.0, 9.0, 9.0]

    # Note: Such interpolation is performed automatically for all trigger ranges. For a trigger
    # range named triggerRange, triggerRange.GetTimestamps() provides the common time axis and
    # triggerRange.GetValues('Signal1') provides matching, possibly interpolated, signal values.


    ############################################################################################
    # CalculateMaskForRange
    ############################################################################################
    # Example: Determine a mask for all values of Signal1, which are in the right open interval
    # [1.0, 9.0)
    mask = self.CalculateMaskForRange(actualValues, minVal=1.0, maxVal=9.0, rightOpen=True)
    resultValues = actualValues[mask]
    resultTimestamps = actualTimestamps[mask]

    print(actualTimestamps)     # [0.0,      1.0,      2.0]
    print(actualValues)         # [1.0,      5.0,      9.0]
    print(mask)                 # [True,     True,     False]

    print(resultTimestamps)     # [0.0,      1.0]
    print(resultValues)         # [1.0,      5.0]

    for triggerRange in ranges:
        timestamps = triggerRange.GetTimestamps()
        interpValuesInRange = triggerRange.GetValues('Signal1')

        ########################################################################################
        # CalculateRanges
        ########################################################################################
        # Example: Check at which times Signal1 == 5.0 holds, and list subranges in the report,
        # for which the expectation was fulfilled or not fulfilled, respectively
        #
        # The example outputs assume a trigger range from 0.5 to 2.0 (open on the right,
        # therefore 2.0 is not checked).

        print(timestamps)           # [0.5, 1.0, 1.5]
        print(interpValuesInRange)  # [1.0, 5.0, 5.0]

        reportElements = {
            True: ('Check OK', report.RESULT_ID_SUCCESS),
            False: ('Check FAILED', report.RESULT_ID_FAILED),
        }

        result = interpValuesInRange == 5.0
        resultSubRanges = self.CalculateRanges(result)

        print(result)           # [False, True, True]
        print(resultSubRanges)  # [(0, 1, False), (1, 3, True)]
        for subRange in resultSubRanges:
            triggerRange.Range(
                timestamps[subRange[0]], timestamps[subRange[1]-1],
                reportElements[subRange[2]][0], reportElements[subRange[2]][1])