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) 获得。
教程 Creating an array-based NumPy trace step template(创建基于数组的 NumPy trace step 模板) 以教程 How to create a package with a trace analysis(如何创建包含 Trace 分析的 Package) 为基础,说明如何创建基于数组的 NumPy trace step 模板 CheckTreshold;该模板也作为 ecu.test 的示例模板提供。
CountSamples 是 ecu.test 附带的另一个示例模板,并配有较为完整的文档,可帮助进一步理解如何创建基于数组的 NumPy trace step 模板。 (这些示例模板位于 trace step 模板目录下的子文件夹
ExampleTraceStepTemplates/NumPyArrayBased中,前提是在打开 ecu.test-Workspace 时已勾选复制示例文件选项。)下一节中的示例 Calculating an output signal(计算输出信号) 演示如何使用基于数组的 NumPy trace step 模板进行信号计算。
随后,示例 Time axis definition(时间轴定义) 说明如何在基于数组的 NumPy trace step 模板中处理时间轴。
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 分析后,生成的测试报告将包含下图:
和信号的阈值检查结果¶
图中蓝色和灰色分别表示记录信号 SigA 和 SigB,橙色表示和信号。此外,从时间戳 7 开始的区间以红色高亮,因为从该时刻起和信号超过了阈值。
Example: Time axis definition(示例:时间轴定义)¶
在前一个示例中,两个信号 SigA 和 SigB 来自同一个 CSV 文件 SigAB.csv,因此采样时间完全一致。如果改为加入文件 SigC.csv 中的另一个记录信号 SigC(同样位于文件夹 ExampleTraces/NumPyArrayBased),并将其绑定到通用信号 Signal2(即对 SigA 与 SigC 求和),则会得到不同的结果图:
采用标准时间轴定义(‘Signal1 or Signal2’)的和信号阈值检查¶
图中用实心圆标出了采样时刻,以强调这样一个事实:只要 Signal1 或 Signal2 任一发生采样,就会计算 Signal3。换言之,这里形成了一个公共时间轴,其中包含 Signal1 和 Signal2 两者的采样时刻。这是构建公共时间轴的标准规则,可通过表达式 Signal1 or Signal2 表示。当在新建基于数组的 NumPy trace step 模板向导中勾选 Time axis definition 选项时,该表达式会自动预填入:
带时间轴定义的基于数组 NumPy trace step 模板创建向导¶
不过,也可以在向导中或稍后在方法 GetTimeAxisDefinition() 中指定其他时间轴定义。将该方法实现为如下形式:
def GetTimeAxisDefinition(cls):
return 'Signal1 and Signal2'
则会定义一个公共时间轴,其中仅包含 Signal1 和 Signal2 同时被采样的时间戳。测试报告中将得到如下图所示结果:
采用时间轴定义 ‘Signal1 and Signal2’ 的和信号阈值检查¶
下面的时间轴定义仅采用 Signal2 的采样时刻:
def GetTimeAxisDefinition(cls):
return 'Signal2'
应用该时间轴定义后,将得到如下图所示结果:
采用时间轴定义 ‘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])