Main Content

Simulink.SimulationOutput

访问仿真输出和元数据

说明

Simulink.SimulationOutput 对象为与一个仿真相关联的所有数据提供单一访问点。对象的属性包含从仿真记录的所有数据和完整的仿真元数据,包括有关模型配置、仿真计时以及仿真期间出现的错误或警告的信息。

在单个对象中访问仿真结果有助于将仿真结果与其他工作区数据区分开来,并使管理来自多个仿真的数据变得更加容易。对于在仿真期间创建的每个记录变量,Simulink.SimulationOutput 对象都有一个对应的属性。例如,当您使用信号记录来记录数据时,SimulationOutput 对象包含一个默认名称为 logsout 的属性,该属性包含记录的信号数据。要在单个 SimulationOutput 对象中返回仿真结果时访问记录的数据,请使用圆点表示法。

out.logsout

创建对象

仿真模型会在以下任何情况下创建一个或多个 Simulink.SimulationOutput 对象:

  • 启用单一仿真输出参数。

    默认情况下,创建新模型时,单一仿真输出参数处于启用状态。您可以使用“配置参数”对话框来启用该参数。在建模选项卡上的设置下,点击模型设置。然后,在“配置参数”对话框中,选择数据导入/导出,并选择单一仿真输出

  • 您可以使用多个仿真窗格运行一组仿真。

  • 您可以使用一个或多个 Simulink.SimulationInput 对象以编程方式对模型进行仿真。

    使用 simparsimbatchsim 函数运行仿真时,您可以使用 SimulationInput 对象配置仿真。

  • 使用 sim 函数语法仿真模型,该语法将结果以单个仿真输出形式返回。

    有关详细信息,请参阅 sim

属性

全部展开

记录的数据属性

对于在仿真中创建的每个记录变量,Simulink.SimulationOutput 对象包含一个对应的属性。该属性的名称与您为记录变量指定的名称匹配。例如,当您记录输出数据并使用默认变量名称 yout 时,Simulink.SimulationOutput 对象具有包含记录的输出数据的属性 yout

使用“配置参数”对话框的数据导入/导出窗格或通过向您的模型添加记录模块(如 To Workspace 模块),配置要记录的数据和变量名称。下表总结了几种常见记录方法的默认属性名称。

默认属性名称记录源
tout时间记录格式参数指定的格式。
yout输出记录格式参数指定的格式。
xout状态记录格式参数指定的格式。
xFinal最终状态记录

当您选择保存最终工作点时,最终状态将保存为 Simulink.op.ModelOperatingPoint 对象。

保存最终工作点未处于选中状态时,将根据格式参数的值保存最终状态。

有关详细信息,请参阅Save Block States and Simulation Operating Points

logsout信号记录Simulink.SimulationData.Dataset 对象。
dsmout数据存储记录Simulink.SimulationData.Dataset 对象。
simoutTo Workspace 模块保存格式模块参数指定的格式。
recordoutRecord 模块Simulink.SimulationData.Dataset 对象。
ScopeDataScope 模块保存格式模块参数指定的格式。

使用 To File 模块、Record 模块或将数据集数据记录到文件参数记录到文件的数据不会捕获为 Simulink.SimulationOutput 对象的属性。

自定义属性

您可以向 Simulink.SimulationOutput 对象添加属性来存储附加数据或元数据。例如,当您使用 parsimbatchsim 运行并行仿真时,您可以在 Simulink.SimulationOutput 对象上定义属性,以便将数据从并行工作进程发送到客户端。

Simulink.SimulationOutput 对象添加属性类似于在结构体中定义字段。例如,以下代码将值为 1 的属性 NewProperty 添加到 Simulink.SimulationOutput 对象 simOut

simOut.NewProperty = 1;

仿真元数据属性

此 属性 为只读。

关于仿真的信息,以 Simulink.SimulationMetadata 对象形式返回。SimulationMetadata 对象包含:

  • 关于模型的详细信息,包括模型版本和用于创建模型的软件版本

  • 仿真期间出现的警告和错误

  • 计时信息,例如仿真的初始化和执行阶段所花费的时间量

此 属性 为只读。

仿真发出的错误消息,以字符向量形式返回。如果仿真运行时没有出现错误,则 ErrorMessage 属性为空。

提示

当您使用 sim 函数运行仿真时,请将 CaptureErrors 名称-值参量指定为 'on',以在 ErrorMessage 属性中捕获错误消息。默认情况下,系统会在 MATLAB® 命令行窗口中报告错误,而不会在 Simulink.SimulationOutput 对象中捕获。

对象函数

find查询和访问 Simulink.SimulationOutput 对象的属性
get访问 Simulink.SimulationOutput 对象中的仿真结果
getSimulationMetadataAccess simulation metadata in Simulink.SimulationOutput object
plotPlot data in Simulation Data Inspector
removePropertyRemove property from Simulink.SimulationOutput object
setUserDataAdd data to metadata in Simulink.SimulationOutput object
setUserStringAdd string to metadata in Simulink.SimulationOutput object
whoGet names of editable properties on Simulink.SimulationOutput object

示例

全部折叠

此示例中的模型使用几种不同记录方法记录数据。

  • Sine Wave 模块的输出使用信号记录进行记录。

  • Gain 模块的输出使用 To Workspace 模块进行记录。

  • Chirp Signal 模块的输出连接到一个 Scope 模块,该 Scope 模块配置为将数据记录到工作区。

  • Gain、Chirp Signal 和 Square Wave Generator 模块的输出使用 Record 模块记录。

  • Square Wave Generator 模块的输出使用输出记录进行记录。

该模型还配置为记录时间数据。

打开模型。

mdl = "LoggingBlocks_NotSSO";
open_system(mdl)

LoggingBlocks_NotSSO model

访问在单一仿真输出中未返回的数据

LoggingBlock_NotSSO 模型未配置为在单个 Simulink.SimulationOutput 对象中返回仿真结果。

点击运行以仿真模型。或者,以编程方式仿真模型。

sim(mdl)

当模型未配置为在单个输出对象中返回结果时,软件会将来自每种记录方法的数据记录到工作区中的一个单独变量中。例如,输出数据以默认变量名称 yout 记录到工作区中。

The workspace when results are not returned as a single simulation output. The workspace contains these variables: logsout, mdl, recordout, ScopeData, simout, tout, and yout.

您可以使用与所使用的记录方法相关联的变量名称,以编程方式访问记录的数据。例如,访问名为 recordoutSimulink.SimulationData.Dataset 对象,该对象包含使用 Record 模块记录的数据。

recordout
recordout = 
Simulink.SimulationData.Dataset 'Run 1: LoggingBlocks_NotSSO' with 3 elements

                         Name         PropagatedName  BlockPath                   
                         ___________  ______________  ___________________________ 
    1  [1x1 Signal]      Big Sine     Big Sine        LoggingBlocks_NotSSO/Record
    2  [1x1 Signal]      Chirp        Chirp           LoggingBlocks_NotSSO/Record
    3  [1x1 Signal]      Square Wave  Square Wave     LoggingBlocks_NotSSO/Record

  - Use braces { } to access, modify, or add elements using index.

访问作为单一仿真输出返回的数据

要将仿真结果作为单一输出返回,请在“配置参数”对话框中选择单一仿真输出

或者,使用 set_param 函数以编程方式启用单一仿真输出参数。

set_param(mdl,"ReturnWorkspaceOutputs","on")

当您启用单一仿真输出参数时,记录到工作区的所有仿真数据将作为单个 Simulink.SimulationOutput 对象返回,默认变量名称为 out

为了更好地了解在单个 SimulationOutput 对象中返回仿真数据对工作区的影响,您可以从工作区中清除以前的记录数据。

clear

点击运行以再次仿真模型。或者,以编程方式仿真模型。

mdl = "LoggingBlocks_NotSSO";
out = sim(mdl);

记录到工作区的所有仿真数据现在都包含在一个名为 out 的变量中。

The workspace when results are returned as a single simulation output. The workspaces contains the variables mdl and out.

对于仿真期间创建的每个记录变量,Simulink.SimulationOutput 对象 out 都包含一个对应的属性。

out
out = 
  Simulink.SimulationOutput:
              ScopeData: [1x1 Simulink.SimulationData.Dataset] 
                logsout: [1x1 Simulink.SimulationData.Dataset] 
              recordout: [1x1 Simulink.SimulationData.Dataset] 
                 simout: [1x1 timeseries] 
                   tout: [51x1 double] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char] 

您可以使用圆点表示法来访问记录的数据。例如,使用 Record 模块访问记录的数据。

out.recordout
ans = 
Simulink.SimulationData.Dataset 'Run 2: LoggingBlocks_NotSSO' with 3 elements

                         Name         PropagatedName  BlockPath                   
                         ___________  ______________  ___________________________ 
    1  [1x1 Signal]      Big Sine     Big Sine        LoggingBlocks_NotSSO/Record
    2  [1x1 Signal]      Chirp        Chirp           LoggingBlocks_NotSSO/Record
    3  [1x1 Signal]      Square Wave  Square Wave     LoggingBlocks_NotSSO/Record

  - Use braces { } to access, modify, or add elements using index.

要访问 Dataset 对象的元素,请使用花括号。例如,使用索引 1 访问信号 Big Sine

out.recordout{1}
ans = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'Big Sine'
    PropagatedName: 'Big Sine'
         BlockPath: [1x1 Simulink.SimulationData.BlockPath]
          PortType: 'outport'
         PortIndex: 1
            Values: [1x1 timeseries]

信号数据作为 timeseries 对象存储在 Signal 对象的 Values 属性中。

out.recordout{1}.Values
  timeseries

  Common Properties:
            Name: 'Big Sine'
            Time: [51x1 double]
        TimeInfo: tsdata.timemetadata
            Data: [51x1 double]
        DataInfo: tsdata.datametadata

时间值在 timeseries 对象的 Time 属性中。信号值在 Data 属性中。

out.recordout{1}.Values.Data
ans = 51×1

         0
    0.3973
    0.7788
    1.1293
    1.4347
    1.6829
    1.8641
    1.9709
    1.9991
    1.9477
      ⋮

当您以将仿真结果作为单个对象返回的方式仿真模型时,您可以使用 Simulink.SimulationOutput 对象访问所有记录的数据和仿真元数据。

此示例中的模型启用了单一仿真输出参数,并使用多种不同记录方法记录数据。

  • Sine Wave 模块的输出使用信号记录进行记录。

  • Gain 模块的输出使用 To Workspace 模块进行记录。

  • Gain、Chirp Signal 和 Square Wave Generator 模块的输出使用 Record 模块记录。

  • Square Wave Generator 模块的输出使用输出记录进行记录。

该模型还配置为记录时间数据。

打开模型。

mdl = "LoggingBlocks";
open_system(mdl)

The model LoggingBlocks.

创建一个 Simulink.SimulationInput 对象来配置模型的仿真。使用 setModelParameter 函数将 StopTime 参数设置为 20

simIn = Simulink.SimulationInput(mdl);
simIn = setModelParameter(simIn,'StopTime','20');

对模型进行仿真。sim 函数输出 out 是一个 Simulink.SimulationOutput 对象,其中包含从仿真记录的所有数据。每个模块和每种记录类型的数据都存储为与在模块或模型中指定的记录变量的名称匹配的属性。

out = sim(simIn);

您可以使用圆点表示法、get 函数或 find 函数来访问记录的数据。

使用圆点表示法访问使用 To Workspace 模块记录的 Big Sine 信号。

simout = out.simout
  timeseries

  Common Properties:
            Name: 'Big Sine'
            Time: [51x1 double]
        TimeInfo: tsdata.timemetadata
            Data: [51x1 double]
        DataInfo: tsdata.datametadata

使用 get 函数访问使用信号记录来记录的 Sine 信号。

logsout = get(out,"logsout")
logsout = 
Simulink.SimulationData.Dataset 'logsout' with 1 element

                         Name  BlockPath               
                         ____  _______________________ 
    1  [1x1 Signal]      Sine  LoggingBlocks/Sine Wave

  - Use braces { } to access, modify, or add elements using index.

使用 find 函数访问使用输出记录来记录的 Square Wave 信号。

yout = find(out,"yout")
yout = 
Simulink.SimulationData.Dataset 'yout' with 1 element

                         Name         BlockPath             
                         ___________  _____________________ 
    1  [1x1 Signal]      Square Wave  LoggingBlocks/Outport

  - Use braces { } to access, modify, or add elements using index.

您可以使用圆点表示法或使用 getSimulationMetadata 函数来访问仿真元数据。

simMetadata = getSimulationMetadata(out)
simMetadata = 
  SimulationMetadata with properties:

        ModelInfo: [1x1 struct]
       TimingInfo: [1x1 struct]
    ExecutionInfo: [1x1 struct]
       UserString: ''
         UserData: []

仿真元数据以 Simulink.SimulationMetadata 对象形式返回。SimulationMetadata 对象将有关仿真的信息分组为具有结构体值的属性中,并具有允许您指定与仿真相关的字符串和附加数据的属性。

访问 SimulationMetadata 对象的 ExecutionInfo 属性。执行信息显示,仿真运行到其停止时间 20,没有出现警告或错误。

simMetadata.ExecutionInfo
ans = struct with fields:
               StopEvent: 'ReachedStopTime'
         StopEventSource: []
    StopEventDescription: 'Reached stop time of 20'
         ErrorDiagnostic: []
      WarningDiagnostics: [0x1 struct]

Simulink.SimulationOutput 对象表示仿真的结果。SimulationOutput 对象包含仿真元数据和从仿真记录的所有数据。您可以通过添加或删除数据记录和自定义属性来修改 Simulink.SimulationOutput 对象的内容。

打开模型 LoggingBlocks,该模型使用多种记录方法来记录多个输入信号。

  • Sine Wave 模块的输出使用信号记录进行记录。

  • Gain 模块的输出使用 To Workspace 模块进行记录。

  • Gain、Chirp Signal 和 Square Wave Generator 模块的输出使用 Record 模块记录。

  • Square Wave Generator 模块的输出使用输出记录进行记录。

该模型还配置为记录时间数据。

mdl = "LoggingBlocks"
mdl = 
"LoggingBlocks"
open_system(mdl);

The LoggingBlocks model

使用 get_param 函数保存 Sine Wave 模块的振幅频率参数值。将值存储在结构体 sinConfig 中。

sinConfig.sinAmp = get_param(strcat(mdl,"/Sine Wave"),"Amplitude");
sinConfig.sinFreq = get_param(strcat(mdl,"/Sine Wave"),"Frequency");

对模型进行仿真。

simOut = sim(mdl);

仿真结果包含在仿真中创建的所有记录变量。使用 who 函数获取您可以修改的属性的列表。

props = who(simOut)
props = 5x1 cell
    {'logsout'  }
    {'recordout'}
    {'simout'   }
    {'tout'     }
    {'yout'     }

对于此仿真,假设您只想保存与 Sine Wave 模块相关的信号路径的数据。使用 removeProperty 函数删除 recordoutyout 属性。

simOut = removeProperty(simOut,["recordout" "yout"]);
who(simOut)
This Simulink.SimulationOutput object contains these editable properties:

    logsout    simout    tout    

您也可以将数据添加到 Simulink.SimulationOutput 对象,方法是将您自己的属性添加到该对象,或使用 setUserData 函数指定 UserData 对象的 Simulink.SimulationMetadata 属性的值。

假设您要将 Sine Wave 模块的参数值保存为 Simulink.SimulationOutput 对象的属性。使用圆点表示法添加属性 SineWaveParameters,就像向结构体中添加字段一样。

simOut.SineWaveParameters = sinConfig;
who(simOut)
This Simulink.SimulationOutput object contains these editable properties:

    SineWaveParameters    logsout    simout    tout    

您可以使用 sldiagviewer.reportSimulationMetadataDiagnostics 函数来通过诊断查看器显示在 Simulink.SimulationOutput 对象中捕获的错误和警告消息。

打开模型 ex_sldemo_bounce

model = "ex_sldemo_bounce";
open_system(model)

通过将模块 Initial Velocity参数指定为未定义的变量 z,将错误引入模型中。

set_param("ex_sldemo_bounce/Initial Velocity","Value","z");

创建一个 Simulink.SimulationInput 对象来配置仿真。

simIn = Simulink.SimulationInput(model);

对模型进行仿真。当您将 StopOnError 选项指定为 off 时,仿真期间发生的错误和警告会在 SimulationOutput 对象中捕获,而不会在命令行窗口或脚本中报告,也不会中断脚本的进程。

simOut = sim(simIn,"StopOnError","off","ShowProgress","off");

使用 sldiagviewer.reportSimulationMetadataDiagnostics 函数在诊断查看器中显示仿真的警告和错误消息。

sldiagviewer.reportSimulationMetadataDiagnostics(simOut)

版本历史记录

在 R2009b 中推出