sdo.Experiment class

Package: sdo

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

Description

An experiment specifies input and output data for a Simulink^® model. You can also specify model parameters and initial-state values.

Typically, you use experiments to estimate unknown model parameter values. You can also use the createSimulator method of an experiment to create a simulation object. Use the simulation object to simulate the model and compare measured and simulated data.

Construction

exp = sdo.Experiment(modelname)

Constructs an sdo.Experiment object. It assigns the specified model name to the ModelName property and default values to the remaining properties.

Input Arguments

modelname

Simulink model name, specified as a character vector or string. For example, 'spe_engine_throttle'.

The model must either be open or appear on the MATLAB^® path.

Properties

`InitialStates`	Model initial-state for the experiment, specified as a `param.State` object. To specify multiple initial-states, use a vector of `param.State` objects. To obtain model initial states, 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. Default: `[]`
`InputData`	Experiment input data. Specify signals to apply to root-level input ports. For information on supported forms of input data, see Forms of Input Data (Simulink). Default: `[]`
`ModelName`	Simulink model name associated with the experiment, specified as a character vector. For example, `'sldo_model1'`. The model must appear on the MATLAB path. Default: `''`
`OutputData`	Experiment output data, specified as a `Simulink.SimulationData.Signal` object. To specify multiple output signals, use a vector of `Simulink.SimulationData.Signal` objects. Default: `[]`
`Parameters`	Model parameter value for the experiment, specified as a `param.Continuous` object. To specify values for multiple parameters, use a vector of `param.Continuous` objects. To obtain model parameters, use `sdo.getParameterFromModel`. Use this property only for specifying parameters values that differ from the parameters 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. Default: `[]`
`Name`	Experiment name, specified as a character vector. For example, `'Exp1'`. Default: `''`
`Description`	Experiment description, specified as a character vector. For example, `'Pendulum experiment 1'`. Default: `''`

Methods

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

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects (MATLAB).

Examples

collapse all

Specify Input-Output Data for Parameter Estimation

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;

Alternatives

Estimate Parameters and States

Documentation