Main Content

idpar

Create parameter for initial states and input level estimation

Syntax

p = idpar(paramvalue)
p = idpar(paramname,paramvalue)

Description

p = idpar(paramvalue) creates an estimable parameter with initial value paramvalue. The parameter, p, is either scalar or array-valued, with the same dimensions as paramvalue. You can configure attributes of the parameter, such as which elements are fixed and which are estimated, and lower and upper bounds.

p = idpar(paramname,paramvalue) sets the Name property of p to paramname.

Input Arguments

paramvalue

Initial parameter value.

paramvalue is a numeric scalar or array that determines both the dimensions and initial values of the estimable parameter p. For example, p = idpar(eye(3)) creates a 3-by-3 parameter whose initial value is the identity matrix.

paramvalue should be:

  • A column vector of length Nx, the number of states to estimate, if you are using p for initial state estimation.

  • An Nx-by-Ne array, if you are using p for initial state estimation with multi-experiment data. Ne is the number of experiments.

  • A column vector of length Nu, the number of inputs to estimate, if you are using p for input level estimation.

  • An Nu-by-Ne array, if you are using p for input level estimation with multi-experiment data.

If the initial value of a parameter is unknown, use NaN.

paramname

Name property of p, specified as a character vector. For example, you can assign 'x0' as the name of a parameter created for initial state estimation.

The Name property is not used in state estimation or input level estimation. You can optionally assign a name for convenience.

Default: 'par'

Output Arguments

p

Estimable parameter, specified as a param.Continuous object.

p can be either scalar- or array-valued. p takes its dimensions and initial value from paramvalue.

p contains the following fields:

  • Value — Scalar or array value of the parameter.

    The dimension and initial value of p.Value are taken from paramvalue when p is created.

  • Minimum — Lower bound for the parameter value. When you use p in state estimation or input value estimation, the estimated value of the parameter does not drop below p.Minimum.

    The dimensions of p.Minimum must match the dimensions of p.Value.

    For array-valued parameters, you can:

    • Specify lower bounds on individual array elements. For example, p.Minimum([1 4]) = -5 .

    • Use scalar expansion to set the lower bound for all array elements. For example, p.Minimum = -5

    Default: -Inf

  • Maximum — Upper bound for the parameter value. When you use p in state estimation or input value estimation, the estimated value of the parameter does not exceed p.Maximum.

    The dimensions of p.Maximum must match the dimensions of p.Value.

    For array-valued parameters, you can:

    • Specify upper bounds on individual array elements. For example, p.Maximum([1 4]) = 5 .

    • Use scalar expansion to set the upper bound for all array elements. For example, p.Maximum = 5

    Default: Inf

  • Free — Boolean specifying whether the parameter is a free estimation variable.

    The dimensions of p.Free must match the dimensions of p.Value. By default, all values are free (p.Free = true).

    If you want to estimate p.Value(k) , set p.Free(k) = true. To fix p.Value(k), set p.Free(k) = false. Doing so allows you to control which states or input values are estimated and which are not.

    For array-valued parameters, you can:

    • Fix individual array elements. For example, p.Free([1 4]) = false; p.Free = [1 0; 0 1].

    • Use scalar expansion to fix all array elements. For example, p.Free = false.

    Default: true (1)

  • Scale — Scaling factor for normalizing the parameter value.

    p.Scale is not used in initial state estimation or input value estimation.

    Default: 1

  • Info — Structure array for storing parameter units and labels. The structure has Label and Unit fields.

    Use these fields for your convenience, to store parameter units and labels. For example, p.Info(1,1).Unit = 'rad/m'; p.Info(1,1).Label = 'engine speed'.

    The dimensions of p.Info must match the dimensions of p.Value.

    Default: '' for both Label and Unit fields

  • Name — Parameter name.

    This property is read-only. It is set to the paramname input argument when you create the parameter.

    Default: ''

Examples

collapse all

Create and configure a parameter for estimating the initial state values of a 4-state system. Fix the first state value to 1. Limit the second and third states to values between 0 and 1.

paramvalue = [1; nan(3,1)];
p = idpar('x0',paramvalue);
p.Free(1) = 0;
p.Minimum([2 3]) = 0;
p.Maximum([2 3]) = 1;

The column vector paramvalue specifies an initial value of 1 for the first state. paramvalue further specifies unknown values for the remaining 3 states.

Setting p.Free(1) to false fixes p.Value(1) to 1. Estimation using p does not alter that value.

Setting p.Minimum and p.Maximum for the second and third entries in p limits the range that those values can take when p is used in estimation.

You can now use p in initial state estimation, such as with the findstates command. For example, use opt = findstatesOptions('InitialState',p) to create a findstates options set that uses p. Then, call findstates with that options set.

Tips

Use idpar to create estimable parameters for:

  • Initial state estimation for state-space model estimation (ssest), prediction (predict), and forecasting (forecast)

  • Explicit initial state estimation with findstates

  • Input level estimation for process model estimation with pem

Specifying estimable state values or input levels gives you explicit control over the behavior of individual state values during estimation.

Version History

Introduced in R2012a