Main Content

values

Extract values from simulation series

Description

example

vv = values(series) returns a vector or 2-D array of variable values contained in the series, in default units. series is a simscape.logging.Series object. series must include a full identifier path to the series, starting with the workspace log variable name.

example

vv = values(series,Name=Value) specifies additional options using one or more name-value arguments. For example, to return a higher-dimension series data as an N-D array, set Flatten=false.

Examples

collapse all

Return the deformation values of a Translational Spring block, in default units.

Open the Mass-Spring-Damper with Controller example model:

openExample('simscape/MassSpringDamperWithControllerExample')

This example model has data logging enabled for the whole model, with the Workspace variable name parameter set to simlog_MassSpringDamperWithController.

Simulate the model for 1 second, to log the simulation data:

paramNameValStruct.StopTime = '1.0';
out = sim('MassSpringDamperWithController',paramNameValStruct);

Return the deformation values of the Translational Spring block, Spring. x is the deformation variable name, and series is the Series object containing the simulation data for this variable.

v1 = values(out.simlog_MassSpringDamperWithController.Spring.x.series)
v1 =

         0
    0.0652
    0.1153
    0.1587
    0.1947
    0.2179
    0.2228
    0.2046
    0.1591
    0.0840
    0.0193
   -0.0164
   -0.0426
   -0.0648
   -0.0762
   -0.0770
   -0.0747
   -0.0686
   -0.0587
   -0.0519
   -0.0452
   -0.0369
   -0.0282
   -0.0231
   -0.0187
   -0.0140
   -0.0097
   -0.0074
   -0.0054
   -0.0036
   -0.0021
   -0.0011
   -0.0005
   -0.0002
   -0.0000

The v1 vector has 35 values because the simulation series has 35 time steps. The deformation values are in meters (the default unit of the series).

The previous example returns the deformation values of a Translational Spring block in default units, meters. In this example, specify a different unit for extracting the series values. The unit you specify must be commensurate with the default units of the variable values contained in the series.

Return the deformation values of the Translational Spring block, Spring, in millimeters.

v2 = values(out.simlog_MassSpringDamperWithController.Spring.x.series,Units="mm")
v2 =

         0
   65.1626
  115.2876
  158.6666
  194.6648
  217.8816
  222.7924
  204.5943
  159.1137
   83.9882
   19.3122
  -16.4485
  -42.6109
  -64.7991
  -76.1640
  -76.9521
  -74.6976
  -68.5525
  -58.6695
  -51.8953
  -45.1768
  -36.8985
  -28.1789
  -23.1087
  -18.6816
  -14.0093
   -9.7345
   -7.3590
   -5.4308
   -3.5878
   -2.0621
   -1.0952
   -0.5459
   -0.1758
   -0.0334

The v2 vector also has 35 values, but these values are in millimeters, so each value is 1000 times bigger than the respective value in v1.

Input Arguments

collapse all

Simulation series, specified as a simscape.logging.Series object. series must include a full identifier path to the series, starting with the workspace log variable name.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: v2 = values(series,Units="mm")

Units for plotting the data, specified as a unit name or a cell array of unit names. Unit names must appear inside single quotes ('') or double quotes (""). Specified units must be commensurate with the units of the series values.

Example: Units = "mm"

If the series data represents an N-D array, then by default the output is a 2-D array, with time as the first dimension and the series data for each time step flattened into a row vector in the second dimension. If you set Flatten=false, then the output is an (N+1)-dimensional array, with time as the first dimension and the rest of the series data preserved as an N-D array.

For example, if a is a Series object representing data logged for a variable that is a 2x3x4 array, with 1023 time steps in the series, then:

  • values(a) returns a 1023x24 array.

  • values(a,Flatten=false) returns a 1023x2x3x4 array.

If the variable represented by the series is a scalar, then the output is a column vector, of size equal the number of time steps, regardless of the Flatten setting.

Output Arguments

collapse all

Variable values corresponding to the time steps in the simulation series, returned as a vector, 2-D array, or N-D array, depending on the variable size and the value of the Flatten argument.

For example, for a nonscalar variable of size m-by-n:

  • If Flatten=true, this object function returns a 2-D array of steps x (m*n) size, where steps is the number of steps in the series, and each m*n row represents the logged values for the variable at this time step, in a column major form. For example, if a variable size is 2-by-2, then the four elements in the first row vector are the a11, a21, a12, and a22 elements at the first time step.

  • If Flatten=false, the function returns a 3-D array of steps x m x n size, where steps is the number of steps in the series.

Version History

Introduced in R2010b

expand all