Main Content

sdo.Experiment

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

expand all in page

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.

example

Properties

expand all

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.

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.

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'

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.

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.

Experiment name, specified as a character vector or string.

Example: 'Exp1'

Experiment description, specified as a character vector or string.

Example: 'Pendulum experiment 1'

Object Functions

createSimulatorCreate simulation object from experiment to compare measured and simulated data
getValuesToEstimateGet model initial states and parameters for estimation from experiment
prepareToDeploy Configure experiment for deployment with Simulink Compiler
setEstimatedValuesUpdate experiments with estimated model initial states and parameter values
updateIODataUpdate experiment input and output data

Examples

collapse all

Open Live Script

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;

Version History

Introduced in R2012b

See Also

| | |

Topics