Documentation

idnlgrey

Nonlinear grey-box model

Syntax

sys = idnlgrey(FileName,Order,Parameters)
sys = idnlgrey(FileName,Order,Parameters,InitialStates)
sys = idnlgrey(FileName,Order,Parameters,InitialStates,Ts)
sys = idnlgrey(FileName,Order,Parameters,InitialStates,Ts,Name,Value)

Description

sys = idnlgrey(FileName,Order,Parameters) creates a nonlinear grey-box model using the specified model structure in FileName, number of inputs, outputs, and states in Order, and the model parameters.

sys = idnlgrey(FileName,Order,Parameters,InitialStates) specifies the initial states of the model.

sys = idnlgrey(FileName,Order,Parameters,InitialStates,Ts) specifies the sample time of a discrete-time model.

sys = idnlgrey(FileName,Order,Parameters,InitialStates,Ts,Name,Value) specifies additional attributes of the idnlgrey model structure using one or more Name,Value pair arguments.

Object Description

idnlgrey represents a nonlinear grey-box model. For information about the nonlinear grey-box models, see Estimating Nonlinear Grey-Box Models.

Use the idnlgrey constructor to create the nonlinear grey-box model and then estimate the model parameters using nlgreyest.

For idnlgrey object properties, see Properties.

Examples

collapse all

Create a Nonlinear Grey-Box Model

Load data, and create a nonlinear grey-box model.

load(fullfile(matlabroot,'toolbox','ident','iddemos','data','dcmotordata'));
z = iddata(y, u, 0.1, 'Name', 'DC-motor');
Order = [2 1 2];
Parameters = [1;0.28];
InitialStates = [0;0];
nlgr = idnlgrey('dcmotor_m',Order,Parameters,InitialStates,0,'Name','DC-motor');

Selectively Estimate Parameters of Nonlinear Grey-Box Model

Load data.

load(fullfile(matlabroot,'toolbox','ident','iddemos','data','twotankdata'));
z = iddata(y,u,0.2,'Name','Two tanks');

Create and initialize idnlgrey model object.

%File describing the model structure for a two-tank system. 
FileName = 'twotanks_c';
%The file specifies the state derivatives and model outputs as a function of time, states, inputs, and model parameters.

% Model orders [ny nu nx].
Order = [1 1 2];

% Initial parameters (Np = 6).
Parameters = {0.5;0.0035;0.019; ...
    9.81;0.25;0.016};

% Initial initial states.
InitialStates = [0; 0.1];

% Continuous system.
Ts = 0;

nlgr = idnlgrey(FileName,Order,Parameters,InitialStates,Ts, ...
    'Name','Two tanks');

Set some parameters as constant.

nlgr.Parameters(1).Fixed = true;
nlgr.Parameters(4).Fixed = true;
nlgr.Parameters(5).Fixed = true;

Estimate the model parameters.

nlgr = nlgreyest(z,nlgr);

Related Examples

Input Arguments

collapse all

FileName — Name of the function or MEX-file that stores the model structurestring | function handle

Name of the function or MEX-file storing the model structure, specified as a string (without the file extension) or a function handle for computing the states and the outputs. If 'FileName' is a string, then it must point to a MATLAB® file, P-code file, or MEX-file. For more information about the file variables, see Specifying the Nonlinear Grey-Box Model Structure.

Order — Number of outputs, inputs, and states of the modelvector | structure

Number of outputs, inputs, and states of the model, specified as one of the following:

  • Vector [Ny Nu Nx], specifying the number of model outputs Ny, inputs Nu, and states Nx.

  • Structure with fields'Ny', 'Nu', and 'Nx'.

For time series, Nu is set to 0, and for static model structures, Nx is set to 0.

Parameters — Parameters of the modelstructure | vector | cell array

Parameters of the model, specified as one of the following:

  • Np-by-1 structure array, where Np is the number of parameters. The structure contains the following fields:

    FieldDescriptionDefault
    NameName of the parameters, specified as a string.'pi', where i is an integer in [1,Np]
    UnitUnit of the parameters, specified as a string.''
    ValueInitial value of the parameters, specified as:
    • Finite real scalar

    • Finite real column vector

    • Two-dimensional real matrix

     
    MinimumMinimum value of the parameters, specified as a real scalar, column vector, or matrix of the same size as Value.

    Minimum >= Value for all components.

    -Inf(size(Value))
    MaximumMaximum value of the parameters, specified as a real scalar, column vector, or matrix of the same size as Value.

    Value <= Maximum for all components.

    Inf(size(Value))
    FixedSpecifies whether parameters are fixed to their initial values, specified as a boolean scalar, column vector, or matrix of the same size as Value.false(size(Value))

    — Implies, estimate all parameters

    Use dot notation to access the subfields of the ith parameter. For example, for idnlgrey model M, the ith parameter is accessed through M.Parameters(i) and its subfield Fixed by M.Parameters(i).Fixed.

  • Np-by-1 vector of real finite initial values, InParameters.

    The data is converted into a structure with default values for the fields Name, Unit, Minimum, Maximum, and Fixed.

    Value is assigned the value InParameters(i), where i is an integer in [1,Np]

  • Np-by-1 cell array containing finite real scalars, finite real vectors, or finite real two-dimensional matrices of initial values.

    Default values are used for the fields Name, Unit, Minimum, Maximum, and Fixed.

InitialStates — Initial states of the modelstructure | [] | cell array | {}

Initial states of the model parameters specified as one of the following:

  • Nx-by-1 structure array, where Nx is the number of states. The structure contains the following fields:

    FieldDescriptionDefault
    NameName of the states, specified as a string.'xi', where i is an integer in [1,Nx]
    UnitUnit of the states, specified as a string.''
    ValueInitial value of the initial states, specified as:
    • A finite real scalar

    • A finite real 1-by-Ne vector, where Ne is the number of experiments in the data set to be used for estimation

     
    MinimumMinimum value of the initial states, specified as a real scalar or 1-by-Ne vector of the same size as Value.

    Minimum >= Value for all components.

    -Inf(size(Value))
    MaximumMaximum value of the parameters, specified as a real scalar or 1-by-Ne vector of the same size as Value.

    Value <= Maximum for all components.

    Inf(size(Value))
    FixedSpecifies whether initial states are fixed to their initial values, specified as boolean scalar or 1-by-Ne vector of the same size as Valuetrue(size(Value))

    — Implies, do not estimate the initial states.

    Use dot notation to access the subfields of the ith initial state. For example, for idnlgrey model M, the ith initial state is accessed through M.InitialStates(i) and its subfield Fixed by M.InitialStates(i).Fixed.

  • [].

    A structure is created with default values for the fields Name, Unit, Minimum, Maximum, and Fixed.

    Value is assigned the value 0.

  • A real finite Nx-by-Ne matrix (InitStates).

    Value of the ith structure array element is InitStates(i,Ne), a row vector with Ne elements. Minimum, Maximum, and Fixed will be -Inf, Inf and true row vectors of the same size as InitStates(i,Ne).

  • Cell array with finite real vectors of size 1-by-Ne or {} (same as []).

Ts — Sample time0 (default) | scalar

Sample time, specified as a positive scalar representing the sampling period. The value is expressed in the unit specified by the TimeUnit property of the model. For a continuous time model Ts is equal to 0 (default).

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Use Name,Value arguments to specify additional properties of idnlgrey models during model creation.

Properties

idnlgrey object properties include:

FileName

Name of the function or MEX-file storing the model structure, specified as a string (without extension) or a function handle for computing the states and the outputs. If 'FileName' is a string, then it must point to a MATLAB file, P-code file, or MEX-file. For more information about the file variables, see Specifying the Nonlinear Grey-Box Model Structure.

Order

Number of outputs, inputs, and states of the model, specified as one of the following:

  • Vector [Ny Nu Nx], specifying the number of model outputs Ny, inputs Nu, and states Nx.

  • Structure with fields'Ny', 'Nu', and 'Nx'.

For time series, Nu is set to 0, and for static model structures, Nx is set to 0.

Parameters

Parameters of the model, specified as one of the following:

  • Np-by-1 structure array, where Np is the number of parameters. The structure contains the following fields:

    FieldDescriptionDefault
    NameName of the parameters, specified as a string.'pi', where i is an integer in [1,Np]
    UnitUnit of the parameters, specified as a string.''
    ValueInitial value of the parameters, specified as:
    • Finite real scalar

    • Finite real column vector

    • Two-dimensional real matrix

     
    MinimumMinimum value of the parameters, specified as a real scalar, column vector, or matrix of the same size as Value.

    Minimum >= Value for all components.

    -Inf(size(Value))
    MaximumMaximum value of the parameters, specified as a real scalar, column vector, or matrix of the same size as Value.

    Value <= Maximum for all components.

    Inf(size(Value))
    FixedSpecifies whether parameters are fixed to their initial values, specified as a boolean scalar, column vector, or matrix of the same size as Value.false(size(Value))

    — Implies, estimate all parameters

  • Np-by-1 vector of real finite initial values, InParameters.

    The data is converted into a structure with default values for the fields Name, Unit, Minimum, Maximum, and Fixed.

    Value is assigned the value InParameters(i), where i is an integer in [1,Np]

  • Np-by-1 cell array containing finite real scalars, finite real vectors, or finite real two-dimensional matrices of initial values.

    A structure is created with default values for the fields Name, Unit, Minimum, Maximum, and Fixed.

Use dot notation to access the subfields of the ith parameter. For example, for idnlgrey model M, the ith parameter is accessed through M.Parameters(i) and its subfield Fixed by M.Parameters(i).Fixed.

InitialStates

Initial states of the model parameters specified as one of the following:

  • Nx-by-1 structure array, where Nx is the number of states. The structure contains the following fields:

    FieldDescriptionDefault
    NameName of the states, specified as a string.'xi', where i is an integer in [1,Nx]
    UnitUnit of the states, specified as a string.''
    ValueInitial value of the initial states, specified as:
    • A finite real scalar

    • A finite real 1-by-Ne vector, where Ne is the number of experiments in the data set to be used for estimation

     
    MinimumMinimum value of the initial states, specified as a real scalar or 1-by-Ne vector of the same size as Value.

    Minimum >= Value for all components.

    -Inf(size(Value))
    MaximumMaximum value of the parameters, specified as a real scalar or 1-by-Ne vector of the same size as Value.

    Value <= Maximum for all components.

    Inf(size(Value))
    FixedSpecifies whether initial states are fixed to their initial values, specified as boolean scalar or 1-by-Ne vector of the same size as Valuetrue(size(Value))

    — Implies, do not estimate the initial states

  • [].

    A structure is created with default values for the fields Name, Unit, Minimum, Maximum, and Fixed.

    Value is assigned the value 0.

  • A real finite Nx-by-Ne matrix (InitStates).

    Value of the ith structure array element is InitStates(i,Ne), a row vector with Ne elements. Minimum, Maximum, and Fixed will be -Inf, Inf and true row vectors of the same size as InitStates(i,Ne).

  • Cell array with finite real vectors of size 1-by-Ne or {} (same as []).

    A structure is created with default values for the fields Name, Unit, Minimum, Maximum, and Fixed.

Use dot notation to access the subfields of the ith initial state. For example, for idnlgrey model M, the ith initial state is accessed through M.InitialStates(i) and its subfield Fixed by M.InitialStates(i).Fixed.

FileArgument

Contains auxiliary variables passed to the ODE file (function or MEX-file) specified in FileName, specified as a cell array. These variables are used as extra inputs for specifying the state and/or output equations.
Default: {}.

SimulationOptions

A structure that specifies the simulation method and related options, containing the following fields:

FieldDescriptionDefault
AbsTol

Absolute error tolerance. This scalar applies to all components of the state vector.
Applicable to: Variable step solvers.
Assignable value: A positive real value.

1e-6
FixedStep

Step size used by the solver.
Applicable to: Fixed-step time-continuous solvers.
Assignable values:

  • 'Auto' — Automatically chooses the initial step.

  • A real value such that 0<FixedStep<=1.

'Auto'

— Automatically chooses the initial step.

InitialStep

Specifies the initial step at which the ODE solver starts.
Applicable to: Variable-step, time-continuous solvers.
Assignable values:

  • 'Auto' — Automatically chooses the initial step.

  • A positive real value such that MinStep<=InitialStep<=MaxStep.

'Auto'

— Automatically chooses the initial step.

MaxOrder

Specifies the order of the Numerical Differentiation Formulas (NDF).
Applicable to: ode15s.
Assignable values: 1, 2, 3, 4 or 5.

5
MaxStep

Specifies the largest time step of the ODE solver.
Applicable to: Variable-step, time-continuous solvers.
Assignable values:

  • 'Auto' — Automatically chooses the time step.

  • A positive real value > MinStep.

'Auto'

— Automatically chooses the time step.

MinStep

Specifies the smallest time step of the ODE solver.
Applicable to: Variable-step, time-continuous solvers.
Assignable values:

  • 'Auto' — Automatically chooses the time step.

  • A positive real value < MaxStep.

'Auto'

— Automatically chooses the time step.

RelTol

Relative error tolerance that applies to all components of the state vector. The estimated error in each integration step satisfies |e(i)| <= max(RelTol*abs(x(i)), AbsTol(i)).
Applicable to: Variable-step, time-continuous solvers.
Assignable value: A positive real value.

1e-3

(0.1% accuracy).

Solver

ODE (Ordinary Differential/Difference Equation) solver for solving state space equations.
A. Variable-step solvers for time-continuous idnlgrey models:

  • 'ode45' — Runge-Kutta (4,5) solver for nonstiff problems.

  • 'ode23' — Runge-Kutta (2,3) solver for nonstiff problems.

  • 'ode113' — Adams-Bashforth-Moulton solver for nonstiff problems.

  • 'ode15s' — Numerical Differential Formula solver for stiff problems.

  • 'ode23s' — Modified Rosenbrock solver for stiff problems.

  • 'ode23t' — Trapezoidal solver for moderately stiff problems.

  • 'ode23tb' — Implicit Runge-Kutta solver for stiff problems.

B. Fixed-step solvers for time-continuous idnlgrey models:

  • 'ode5' — Dormand-Prince solver.

  • 'ode4' — Fourth-order Runge-Kutta solver.

  • 'ode3' — Bogacki-Shampine solver.

  • 'ode2' — Heun or improved Euler solver.

  • 'ode1' — Euler solver.

C. Fixed-step solvers for time-discrete idnlgrey models: 'FixedStepDiscrete'

D. General: 'Auto' — Automatically chooses one of the previous solvers.

'Auto'

— Automatically chooses one of the previous solvers.

Report

Summary report that contains information about the estimation options and results when the model is estimated using the nlgreyest command. Use Report to query a model for how it was estimated, including:

  • Estimation method

  • Estimation options

  • Search termination conditions

  • Estimation data fit

The contents of Report are irrelevant if the model was created by construction.

load(fullfile(matlabroot,'toolbox','ident','iddemos','data','dcmotordata'));
z = iddata(y,u,0.1,'Name','DC-motor');
Order = [2 1 2];
Parameters = [1;0.28];
InitialStates = [0;0];
nlgr = idnlgrey('dcmotor_m',Order,Parameters,InitialStates,0, ...
    'Name','DC-motor');

nlgr.Report
         Status: 'Created by direct construction or transformation. Not estimated.'
         Method: ''
            Fit: [1x1 struct]
     Parameters: [1x1 struct]
    OptionsUsed: []
      RandState: []
       DataUsed: [1x1 struct]
    Termination: [1x1 struct]
nlgr.Report.OptionsUsed
ans =

     []

Estimate the parameters of the model object.

nlgr = nlgreyest(z, nlgr);
Status: 'Estimated using NLGREYEST'
         Method: 'Solver: ode45; Search: lsqnonlin'
            Fit: [1x1 struct]
     Parameters: [1x1 struct]
    OptionsUsed: [1x1 idoptions.nlgreyest]
      RandState: []
       DataUsed: [1x1 struct]
    Termination: [1x1 struct]
nlgr.Report.OptionsUsed
Option set for the nlgreyest command:

    GradientOptions: [1x1 struct]
           EstCovar: 1
            Display: 'off'
     Regularization: [1x1 struct]
       SearchMethod: 'auto'
       SearchOption: [1x1 idoptions.search.lsqnonlin]
       OutputWeight: []
           Advanced: [1x1 struct]

If you use nlgreyest to estimate the model, the fields of Report contain information on the estimation data, options, and results.

Report is a read-only property.

For more information on this property and how to use it, see Output Arguments in the nlgreyest reference page and Estimation Report.

TimeVariable

Independent variable for the inputs, outputs, and—when available—internal states, specified as a string.

Default: 't'

NoiseVariance

Noise variance (covariance matrix) of the model innovations e.
Assignable value is an ny-by-ny matrix.
Typically set automatically by the estimation algorithm.

Ts

Sample time. Ts is a positive scalar representing the sampling period. This value is expressed in the unit specified by the TimeUnit property of the model. For a continuous time model, Ts is equal to 0 (default).

Changing this property does not discretize or resample the model.

Default: 0

TimeUnit

String representing the unit of the time variable. This property specifies the units for the time variable, the sample time Ts, and any time delays in the model. Use any of the following values:

  • 'nanoseconds'

  • 'microseconds'

  • 'milliseconds'

  • 'seconds'

  • 'minutes'

  • 'hours'

  • 'days'

  • 'weeks'

  • 'months'

  • 'years'

Changing this property has no effect on other properties, and therefore changes the overall system behavior. Use chgTimeUnit to convert between time units without modifying system behavior.

Default: 'seconds'

InputName

Input channel names. Set InputName to a string for single-input model. For a multi-input model, set InputName to a cell array of strings.

Alternatively, use automatic vector expansion to assign input names for multi-input models. For example, if sys is a two-input model, enter:

sys.InputName = 'controls';

The input names automatically expand to {'controls(1)';'controls(2)'}.

When you estimate a model using an iddata object, data, the software automatically sets InputName to data.InputName.

You can use the shorthand notation u to refer to the InputName property. For example, sys.u is equivalent to sys.InputName.

Input channel names have several uses, including:

  • Identifying channels on model display and plots

  • Extracting subsystems of MIMO systems

  • Specifying connection points when interconnecting models

Default: Empty string '' for all input channels

InputUnit

Input channel units. Use InputUnit to keep track of input signal units. For a single-input model, set InputUnit to a string. For a multi-input model, set InputUnit to a cell array of strings. InputUnit has no effect on system behavior.

Default: Empty string '' for all input channels

InputGroup

Input channel groups. The InputGroup property lets you assign the input channels of MIMO systems into groups and refer to each group by name. Specify input groups as a structure. In this structure, field names are the group names, and field values are the input channels belonging to each group. For example:

sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input channels 1, 2 and 3, 5, respectively. You can then extract the subsystem from the controls inputs to all outputs using:

sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output model. For a multi-output model, set OutputName to a cell array of strings.

Alternatively, use automatic vector expansion to assign output names for multi-output models. For example, if sys is a two-output model, enter:

sys.OutputName = 'measurements';

The output names automatically expand to {'measurements(1)';'measurements(2)'}.

When you estimate a model using an iddata object, data, the software automatically sets OutputName to data.OutputName.

You can use the shorthand notation y to refer to the OutputName property. For example, sys.y is equivalent to sys.OutputName.

Output channel names have several uses, including:

  • Identifying channels on model display and plots

  • Extracting subsystems of MIMO systems

  • Specifying connection points when interconnecting models

Default: Empty string '' for all output channels

OutputUnit

Output channel units. Use OutputUnit to keep track of output signal units. For a single-output model, set OutputUnit to a string. For a multi-output model, set OutputUnit to a cell array of strings. OutputUnit has no effect on system behavior.

Default: Empty string '' for all output channels

OutputGroup

Output channel groups. The OutputGroup property lets you assign the output channels of MIMO systems into groups and refer to each group by name. Specify output groups as a structure. In this structure, field names are the group names, and field values are the output channels belonging to each group. For example:

sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that include output channels 1, and 3, 5, respectively. You can then extract the subsystem from all inputs to the measurement outputs using:

sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''

Notes

Any text that you want to associate with the system. Set Notes to a string or a cell array of strings.

Default: {}

UserData

Any type of data you wish to associate with system. Set UserData to any MATLAB data type.

Default: []

Output Arguments

collapse all

sys — Nonlinear grey-box modelidnlgrey object

Nonlinear grey-box model, returned as an idnlgrey object.

More About

collapse all

Definition of idnlgrey States

The states of an idnlgrey model are defined explicitly in the function or MEX-file storing the model structure. States are required for simulation and prediction of nonlinear grey-box models. Use findstates to search for state values for simulation and prediction with sim(idnlgrey), predict, and compare.

    Note:   The initial values of the states are configured by the InitialStates property of the idnlgrey model.

See Also

| | | | | | |

Was this topic helpful?