sdo.Experiment

Specify experiment I/O data, model parameters, and initial state values

Description

Use an sdo.Experiment object to associate input and output data with signals in a Simulink^® model. Typically, you associate measured data that you collect from an experiment with the corresponding signals in the model.

You can use the createSimulator function of an experiment to create a simulation object. Use the simulation object to simulate the model and compare measured and simulated data. If the simulated response does not match the experimental data, you can estimate model parameter values for which the model response matches the measured data.

To specify model parameters for estimation, first create an estimation objective function, using the sdo.Experiment object and experiment design variables, to evaluate design requirements. You can then use sdo.optimize to estimate the parameter values that satisfy the design requirements. For more information about the workflow, see Write a Cost Function and Estimate Model Parameter Values (Code).

Creation

Syntax

exp = sdo.Experiment(modelname)

Description

exp = sdo.Experiment(modelname) creates an sdo.Experiment object and sets the ModelName property. The remaining properties have default values.

Properties

InitialStates — Model initial state

[] (default) | param.State object | vector of param.State objects

Model initial state for the experiment, specified as a param.State object or vector of param.State objects.

• To specify a single initial state, use a param.State object.

• To specify multiple initial states, use a vector of param.State objects.

To obtain model initial states from a Simulink model, use sdo.getStateFromModel.

Use this property only for specifying initial states that differ from the initial state values defined in the model.

• To estimate the value of an initial state, set the Free property of the initial state to true.

  When you have multiple experiments for a given model, you can estimate model initial states on a per-experiment basis. To do so, specify the model initial states for each experiment. You can optionally specify an initial guess for the initial state values for any of the experiments using the Value property of the state parameters.

• To specify an initial state value as a known quantity, not to be estimated, set its Free property to false.

After specifying the initial states that you are estimating for an experiment, use getValuesToEstimate. getValuesToEstimate returns a vector of all the model parameters and initial states that you want to estimate. You use this vector as an input to sdo.optimize to specify the parameters that you want to estimate.

InputData — Experiment input data

[] (default) | data object

Experiment input data, specified as a data object. Use this property to specify signals to apply to root-level input ports. For information on supported forms of input data, see Forms of Input Data.

ModelName — Model name associated with experiment

'' (default) | character vector | string

Simulink model name associated with the experiment, specified as a character vector or string.

The model must be available on the MATLAB^® path.

Example: 'spe_engine_throttle'

OutputData — Experiment output data

[] (default) | Simulink.SimulationData.Signal object | vector of Simulink.SimulationData.Signal objects

Experiment output data, specified as a Simulink.SimulationData.Signal object or vector of Simulink.SimulationData.Signal objects.

• To specify a single output signal, use a Simulink.SimulationData.Signal object.

• To specify multiple output signals, use a vector of Simulink.SimulationData.Signal objects.

Parameters — Model parameter values

[] (default) | param.Continuous object | vector of param.Continuous objects

Model parameter values for the experiment, specified as a param.Continuous object or vector of param.Continuous objects.

• To specify a value for a single parameter, use a param.Continuous object.

• To specify values for multiple parameters, use a vector of param.Continuous objects.

To obtain model parameters from a Simulink model, use sdo.getParameterFromModel.

Use this property only for specifying parameter values that differ from the parameter values defined in the model.

• To estimate the value of a parameter, set the Free property of the parameter to true.

  When you have multiple experiments for a given model, you can:

  • Estimate a model parameter on a per-experiment basis. To do so, specify the model parameter for each experiment. You can optionally specify the initial guess for the parameter value for any of the experiments using the Value property.

  • Estimate one value for a model parameter using all the experimental data. To do so, do not specify the model parameter for the experiments. Instead, call sdo.optimize with the model parameter directly.

  For an example of estimating model parameters on a per-experiment basis and using data from multiple experiments, see Estimate Model Parameters per Experiment (Code).

• To specify a parameter value as a known quantity (not to be estimated), set its Free property to false.

After specifying the parameters that you are estimating for an experiment, use getValuesToEstimate. getValuesToEstimate returns a vector of all the model parameters and initial states that you want to estimate. You use this vector as an input to sdo.optimize to specify the parameters that you want to estimate.

Name — Experiment name

[] (default) | character vector | string

Experiment name, specified as a character vector or string.

Example: 'Exp1'

Description — Experiment description

[] (default) | character vector | string

Experiment description, specified as a character vector or string.

Example: 'Pendulum experiment 1'

OutputDataWeights — Weights for output data

{} (default) | cell array

Weights for the output data, specified as a cell array. The number of elements in this cell array must be equal to the number of elements in the OutputData property. Each element in the cell array can be either:

• a scalar — The same weight is applied to each data point of the corresponding data in the OutputData property.

• a vector — The number of elements in the vector must be equal to the number of data points in the corresponding data in the OutputData property. Each vector element denotes the weight of the corresponding data point.

• empty — The default weight of 1 is applied to the corresponding data in the OutputData property.

When OutputData=[], the software sets the OutputDataWeights to {} by default because there are no output signals. When you specify an output signal using the OutputData property, the software sets the corresponding element in the OutputDataWeights cell array to [1] by default.

You can use OutputDataWeights to specify both the relative importance of each data point within an output data signal and the relative importance of different output data signals. You can also specify the relative importance among the different output data signals using this property. For example, {[2],[1]} means that the first data signal in OutputData is twice as important as the second.

During optimization, when calculating the objective to minimize, the software uses the specified weights as multiplicative factors. That is, Error Objective = Residual Error * OutputDataWeights * ExperimentWeight. For information on experiment weights, see the ExperimentWeight property.

Example: {[1],[2,1,5],{},[3]}

ExperimentWeight — Weight for experiment

1 (default) | real nonnegative scalar

Weight for experiment, specified as a real nonnegative scalar.

Use this property to specify the relative contributions of different experiments to parameter estimation.

During optimization, when calculating the objective to minimize, the software uses the specified weights as multiplicative factors. That is, Error Objective = Residual Error * OutputDataWeights * ExperimentWeight. For information on output data weights, see the OutputDataWeights property.

Example: 2

Object Functions

createSimulator	Create simulation object from experiment to compare measured and simulated data
getValuesToEstimate	Get model initial states and parameters for estimation from experiment
prepareToDeploy	Configure experiment for deployment with Simulink Compiler
setEstimatedValues	Update experiments with estimated model initial states and parameter values
updateIOData	Update experiment input and output data

Examples

Specify Input/Output Data for Parameter Estimation

Load the measured experiment data.

load sdoBattery_ExperimentData

The variable Charge_Data, which contains the data measured during a battery charging experiment, is loaded into the MATLAB® workspace. The first column contains time data. The second and third columns contain the current and voltage data, respectively.

Specify an experiment for a model.

modelname = 'sdoBattery';
exp = sdo.Experiment(modelname);
exp.Name = 'Charging';
exp.Description = 'Battery charging data collected on March 15, 2013.';

Specify input data for the experiment.

exp.InputData = timeseries(Charge_Data(:,2),Charge_Data(:,1));

Specify output data for the experiment.

VoltageSig = Simulink.SimulationData.Signal;
VoltageSig.Name      = 'Voltage';
VoltageSig.BlockPath = 'sdoBattery/SOC -> Voltage';
VoltageSig.PortType  = 'outport';
VoltageSig.PortIndex = 1;
VoltageSig.Values    = timeseries(Charge_Data(:,3),Charge_Data(:,1));

exp.OutputData = VoltageSig;

Alternatives

Estimate Parameters and States

Version History

Introduced in R2012b

R2026a: Specify weights for experiments and output data

You can now specify the relative contributions of different experiments to parameter estimation by setting weights for the experiments. To set the experiment weights, specify the new ExperimentWeight property of each sdo.Experiment object as a real nonnegative scalar.

You can specify the relative importance of each data point in an output data signal with respect to other data points in the same output data signal. To set the output data weights, specify the new OutputDataWeights property of each sdo.Experiment object as a cell array. You can also specify the relative importance among the different output data signals using this property.