findop

Steady-state operating point from specifications (trimming) or simulation

Syntax

op = findop(mdl,opspec)

op = findop(mdl,opspec,param)

op = findop(___,options)

[op,opreport]
= findop(___)

op = findop(mdl,tsnapshot)

op = findop(mdl,tsnapshot,param)

Description

op = findop(mdl,opspec) returns the operating point of the model that meets the specifications in opspec. Typically, you trim the model at a steady-state operating point. The Simulink^® model must be open. If opspec is an array of operating points specifications, findop returns an array of corresponding operating points.

example

op = findop(mdl,opspec,param) batch trims the model for the parameter value variations specified in param.

example

op = findop(___,options) trims the model using additional optimization algorithm options.

example

[op,opreport] = findop(___) returns an operating point search report, opreport, for any of the previous syntaxes.

example

op = findop(mdl,tsnapshot) simulates the model using the model initial conditions, and extracts operating points at simulation snapshot times specified in tsnapshot.

example

op = findop(mdl,tsnapshot,param) batch simulates the model using the parameter value variations specified in param.and extracts operating points at simulation snapshot times.

example

Examples

collapse all

Trim Model to Meet State Specifications

Open Script

Open the Simulink model.

mdl = 'watertank';
open_system(mdl)

Trim the model to find a steady-state operating point where the water tank level is 10.

Create default operating point specification object.

opspec = operspec(mdl);

Configure specifications for the first model state. The first state must be at steady state with a lower bound of 0. Provide an initial guess of 2 for the state value.

opspec.States(1).SteadyState = 1;
opspec.States(1).x = 2;
opspec.States(1).Min = 0;

Configure the second model state as a known state with a value of 10.

opspec.States(2).Known = 1;
opspec.States(2).x = 10;

Find the operating point that meets these specifications.

op = findop(mdl,opspec);

 Operating point search report:
---------------------------------

opreport = 


 Operating point search report for the Model watertank.
 (Time-Varying Components Evaluated at time t=0)

Operating point specifications were successfully met.
States: 
----------
 Min     x     Max   dxMin    dx   dxMax 
______ ______ ______ ______ ______ ______
                                         
(1.) watertank/PID Controller/Integrator/Continuous/Integrator
  0    1.2649  Inf     0      0      0   
(2.) watertank/Water-Tank System/H
  10     10     10     0      0      0   

Inputs: None 
----------

Outputs: None 
----------

Batch Trim Simulink Model for Parameter Variation

Open Script

Open the Simulink model.

mdl = 'watertank';
open_system(mdl)

Vary parameters A and b within 10% of their nominal values, and create a 3-by-4 parameter grid.

[A_grid,b_grid] = ndgrid(linspace(0.9*A,1.1*A,3),...
                         linspace(0.9*b,1.1*b,4));

Create a parameter structure array, specifying the name and grid points for each parameter.

params(1).Name = 'A';
params(1).Value = A_grid;
params(2).Name = 'b';
params(2).Value = b_grid;

Create a default operating point specification for the model.

opspec = operspec(mdl);

Trim the model using the specified operating point specification and parameter grid.

opt = findopOptions('DisplayReport','off');
op = findop(mdl,opspec,params,opt);

op is a 3-by-4 array of operating point objects that correspond to the specified parameter grid points.

Trim Model Using Specified Optimizer Type

Open Script

Open the Simulink model.

mdl = 'watertank';
open_system(mdl)

Create a default operating point specification object.

opspec = operspec(mdl);

Create an option set that sets the optimizer type to gradient descent and suppresses the search report display.

opt = findopOptions('OptimizerType','graddescent','DisplayReport','off');

Trim the model using the specified option set.

op = findop(mdl,opspec,opt);

Obtain Operating Point Search Report

Open Script

Open the Simulink model.

mdl = 'watertank';
open_system(mdl)

Create default operating point specification object.

opspec = operspec(mdl);

Configure specifications for the first model state.

opspec.States(1).SteadyState = 1;
opspec.States(1).x = 2;
opspec.States(1).Min = 0;

Configure specifications for the second model state.

opspec.States(2).Known = 1;
opspec.States(2).x = 10;

Find the operating point that meets these specifications, and return the operating point search report. Create an option set to suppress the search report display.

opt = findopOptions('DisplayReport',false);
[op,opreport] = findop(mdl,opspec,opt);

opreport describes how closely the optimization algorithm met the specifications at the end of the operating point search.

opreport

opreport = 


 Operating point search report for the Model watertank.
 (Time-Varying Components Evaluated at time t=0)

Operating point specifications were successfully met.
States: 
----------
 Min     x     Max   dxMin    dx   dxMax 
______ ______ ______ ______ ______ ______
                                         
(1.) watertank/PID Controller/Integrator/Continuous/Integrator
  0    1.2649  Inf     0      0      0   
(2.) watertank/Water-Tank System/H
  10     10     10     0      0      0   

Inputs: None 
----------

Outputs: None 
----------

dx is the time derivative for each state. Since all dx values are zero, the operating point is at steady state.

Extract Operating Points at Simulation Snapshots

Open Script

Open the Simulink model.

mdl = 'magball';
open_system(mdl)

Simulate the model, and extract operating points at 10 and 20 time units.

op = findop(mdl,[10,20]);

op is a column vector of operating points, with one element for each snapshot time.

Display the first operating point.

op(1)

ans = 


 Operating point for the Model magball.
 (Time-Varying Components Evaluated at time t=10)

States: 
----------
    x     
__________
          
(1.) magball/Controller/PID Controller/Filter/Cont. Filter/Filter
5.4732e-07
(2.) magball/Controller/PID Controller/Integrator/Continuous/Integrator
 14.0071  
(3.) magball/Magnetic Ball Plant/Current
  7.0036  
(4.) magball/Magnetic Ball Plant/dhdt
8.443e-08 
(5.) magball/Magnetic Ball Plant/height
   0.05   

Inputs: None 
----------

Vary Parameters and Extract Operating Points at Simulation Snapshots

Open Script

Open Simulink model.

mdl = 'watertank';
open_system(mdl)

Specify parameter values. The parameter grids are 5-by-4 arrays.

[A_grid,b_grid] = ndgrid(linspace(0.9*A,1.1*A,5),...
                         linspace(0.9*b,1.1*b,4));
params(1).Name = 'A';
params(1).Value = A_grid;
params(2).Name = 'b';
params(2).Value = b_grid;

Simulate the model and extract operating points at 0, 5, and 10 time units.

op = findop(mdl,[0 5 10],params);

findop simulates the model for each parameter value combination, and extracts operating points at the specified simulation times.

op is a 3-by-5-by-4 array of operating point objects.

size(op)

ans =

     3     5     4

Input Arguments

collapse all

`mdl` — Simulink model name
character vector | string

Simulink model name, specified as a character vector or string. The model must be in the current working folder or on the MATLAB^® path.

`opspec` — Operating point specifications
`OperatingSpec` object | array of `OperatingSpec` objects

Operating point specifications for trimming the model, specified as an OperatingSpec object or an array of OperatingSpec objects created using the operspec function.

If opspec is an array, findop returns an array of corresponding operating points using a single model compilation.

`param` — Parameter samples
structure | structure array

Parameter samples for trimming, specified as one of the following:

Structure — Vary the value of a single parameter by specifying parameters as a structure with the following fields.
- Name — Parameter name, specified as a character vector or string. You can specify any model parameter that is a variable in the model workspace, the MATLAB workspace, or a data dictionary. If the variable used by the model is not a scalar variable, specify the parameter name as an expression that resolves to a numeric scalar value. For example, use the first element of vector V as a parameter.
  parameters.Name = 'V(1)';
- Value — Parameter sample values, specified as a double array.
For example, vary the value of parameter A in the 10% range.
```
parameters.Name = 'A';
parameters.Value = linspace(0.9*A,1.1*A,3);
```

Structure array — Vary the value of multiple parameters. For example, vary the values of parameters A and b in the 10% range.

[A_grid,b_grid] = ndgrid(linspace(0.9*A,1.1*A,3),...
                         linspace(0.9*b,1.1*b,3));
parameters(1).Name = 'A';
parameters(1).Value = A_grid;
parameters(2).Name = 'b';
parameters(2).Value = b_grid;

When you specify parameter value variations, findop batch trims the model for each parameter value combination, and returns an array of corresponding operating points. If param specifies tunable parameters only, then the software batch trims the model using a single compilation.

If you specify opspec as a single operspec object and the parameter values in param produce states that conflict with known states in opspec, findop trims the model using the specifications in opspec. To trim the model at state values derived from the parameter values, specify opspec as an array of corresponding operspec objects. For an example, see Batch Trim Simulink Model for Parameter Variation.

`options` — Trimming options
`findopOptions` option set

Trimming options, specified as a findopOptions option set.

`tsnapshot` — Simulation snapshot times
scalar | vector

Simulation snapshot times at which to extract the operating point of the model, specified as a scalar for a single snapshot or a vector for multiple snapshots. findop simulates the model and computes an operating point for the state of the model at each snapshot time.

Output Arguments

collapse all

`op` — Operating point
`OperatingPoint` object | array of `OperatingPoint` objects

Operating point, returned as an OperatingPoint object or an array of OperatingPoint objects. The dimensions of op depend on the specified parameter variations and either the operating-point specifications or the simulation snapshot time.

Parameter Variation	Find operating point for...	Resulting `op` Dimensions
No parameter variation	Single operating-point specification, specified by `opspec`	single operating-point object
	Single snapshot time, specified by `tsnapshot`	single operating-point object
	N₁-by-`...`-by-N_m array of operating-point specifications, specified by `opspec`	N₁-by-`...`-by-N_m
	N_s snapshots, specified by `tsnapshot`	Column vector of length N_s
N₁-by-`...`-by-N_m parameter grid, specified by `param`	Single operating-point specification, specified by `opspec`	N₁-by-`...`-by-N_m
	Single snapshot time, specified by `tsnapshot`
	N₁-by-`...`-by-N_m array of operating-point specifications, specified by `opspec`
	N_s snapshots, specified by `tsnapshot`	N_s-by-N₁-by-`...`-by-N_m.

For example, suppose:

opspec is a single operating-point specification object and param specifies a 3-by-4-by-2 parameter grid. In this case, op is a 3-by-4-by-2 array of operating points.
tsnapshot is a scalar and param specifies a 5-by-6 parameter grid. In this case, op is a 1-by-5-by-6 array of operating points.
tsnapshot is a row vector with three elements and param specifies a 5-by-6 parameter grid. In this case, op is a 3-by-5-by-6 array of operating points.

Each operating-point object has the following properties:

Property Description

Model Simulink model name, returned as a character vector.

States

State operating point, returned as a vector of state objects. Each entry in States represents the supported states of one Simulink block.

For a list of supported states for operating point objects, see Simulink Model States Included in Operating Point Object.

Note

If the block has multiple named continuous states, States contains one structure for each named state.

Each state object has the following fields:

Field	Description
`Nx` (read only)	Number of states in the block
`Block`	Block path, returned as a character vector.
`StateName`	State name
`x`	Values of all supported block states, returned as a vector of length `Nx`.
`Ts`	Sample time and offset of each supported block state, returned as a vector. For continuous-time systems, `Ts` is zero.
`SampleType`	State time rate, returned as one of the following: `'CSTATE'` — Continuous-time state `'DSTATE'` — Discrete-time state
`inReferencedModel`	Flag indicating whether the block is inside a reference model, returned as one of the following: `1` — Block is inside a reference model. `0` — Block is in the current model file.
`Description`	Block state description, returned as a character vector.

Inputs

Input level at the operating point, returned as a vector of input objects. Each entry in Inputs represents the input levels of one root-level inport block in the model.

Each input object has the following fields:

Field	Description
`Nu` (read only)	Number of inport block signals
`Block`	Inport block name
`PortDimensions`	Dimension of signals accepted by the inport
`u`	Inport block input levels at the operating point, returned as a vector of length `Nu`.
`Description`	Inport block input description, returned as a character vector.

Time

Times at which any time-varying functions in the model are evaluated, returned as a vector.

Version

Object version number

You can edit the properties of op using dot notation or the set function.

`opreport` — Operating point search report
`OperatingReport` object | array of `OperatingReport` objects

Operating point search report, returned as an OperatingReport object. If op is an array of OperatingPoint objects, then opreport is an array of corresponding OperatingReport objects.

This report displays automatically, even when you suppress the output using a semicolon. To hide the report, set the DisplayReport field in options to 'off'.

Each operating point search report has the following properties:

Property Description

Model

Model property value of op

Inputs

Inputs property value of op

Outputs

Output values at the computed operating point. This object contains the same fields as the Outputs property of opspec, with the addition of yspec, which is the desired output value.

States

States property value of op with the addition of dx, which contains the state derivative values. For discrete-time states, dx is the difference between the next state value and the current one; that is, x(k+1) – x(k).

Time Time property value of op

TerminationString Optimization termination condition, returned as a character vector.

OptimizationOutput

Optimization algorithm search results, returned as a structure with the following fields:

Field	Description
`iterations`	Number of iterations performed during the optimization
`funcCount`	Number of function evaluations performed during the optimization
`lssteplength`	Size of line search step relative to search direction (active-set optimization algorithm only)
`stepsize`	Displacement in the state vector at the final iteration (active-set and interior-point optimization algorithms)
`algorithm`	Optimization algorithm used
`firstorderopt`	Measure of first-order optimization, for the trust-region-reflective optimization algorithm; `[]` for other algorithms
`constrviolation`	Maximum of constraint functions
`message`	Exit message

For more information about the optimization algorithm, see the Optimization Toolbox™ documentation.

More About

collapse all

Steady-State Operating Point (Trim Condition)

A steady-state operating point of a model, also called an equilibrium or trim condition, includes state variables that do not change with time.

A model can have several steady-state operating points. For example, a hanging damped pendulum has two steady-state operating points at which the pendulum position does not change with time. A stable steady-state operating point occurs when a pendulum hangs straight down. When the pendulum position deviates slightly, the pendulum always returns to equilibrium. In other words, small changes in the operating point do not cause the system to leave the region of good approximation around the equilibrium value.

An unstable steady-state operating point occurs when a pendulum points upward. As long as the pendulum points exactly upward, it remains in equilibrium. However, when the pendulum deviates slightly from this position, it swings downward and the operating point leaves the region around the equilibrium value.

When using optimization search to compute operating points for nonlinear systems, your initial guesses for the states and input levels must be near the desired operating point to ensure convergence.

When linearizing a model with multiple steady-state operating points, it is important to have the right operating point. For example, linearizing a pendulum model around the stable steady-state operating point produces a stable linear model, whereas linearizing around the unstable steady-state operating point produces an unstable linear model.

Tips

You can initialize an operating point search at a simulation snapshot or a previously computed operating point using initopspec.
Linearize the model at the operating point op using linearize.
To extract state and input values from an operating point object, use getstatestruct and getinputstruct, respectively.

Algorithms

By default, findop uses the optimizer graddescent-elim. To use a different optimizer, change the value of OptimizerType in options using findopOptions.

findop automatically sets these Simulink model properties for optimization:

BufferReuse = 'off'
BlockReductionOpt = 'off'
SaveFormat = 'StructureWithTime'

After the optimization completes, Simulink restores the original model properties.

Alternative Functionality

App

As an alternative to the findop command, you can find operating points in one of the following ways.

Compute operating points using the Steady State Manager. For an example, see Compute Operating Points from Specifications Using Steady State Manager.
If you are computing an operating point for linearization, you can find the operating point and linearize the model using the Model Linearizer. For an example, see Compute Operating Points from Specifications Using Model Linearizer.

Version History

Introduced before R2006a

expand all

R2021b: `PortWidth` property of operating point inputs and outputs will be removed

The input and output PortWidth properties of operating points and operating point search reports will be removed in a future release. Use the new Nu and Ny properties instead.

To update your code, change instances of PortWidth to either Nu or Ny as shown in the following table.

Not Recommended	Recommended
[op,report] = findop("scdplane",10); numOut = op.Outputs(1).PortWidth; numIn = report.Inputs(1).PortWidth;	[op,report] = findop("scdplane",10); numOut = op.Outputs(1).Ny; numIn = report.Inputs(1).Nu;

findop

Syntax

Description

Examples

Trim Model to Meet State Specifications

Batch Trim Simulink Model for Parameter Variation

Trim Model Using Specified Optimizer Type

Obtain Operating Point Search Report

Extract Operating Points at Simulation Snapshots

Vary Parameters and Extract Operating Points at Simulation Snapshots

Input Arguments

`mdl` — Simulink model name
character vector | string

`opspec` — Operating point specifications
`OperatingSpec` object | array of `OperatingSpec` objects

`param` — Parameter samples
structure | structure array

`options` — Trimming options
`findopOptions` option set

`tsnapshot` — Simulation snapshot times
scalar | vector

Output Arguments

`op` — Operating point
`OperatingPoint` object | array of `OperatingPoint` objects

`opreport` — Operating point search report
`OperatingReport` object | array of `OperatingReport` objects

More About

Steady-State Operating Point (Trim Condition)

Tips

Algorithms

Alternative Functionality

App

Version History

R2021b: `PortWidth` property of operating point inputs and outputs will be removed

See Also

Topics

findop

Syntax

Description

Examples

Trim Model to Meet State Specifications

Batch Trim Simulink Model for Parameter Variation

Trim Model Using Specified Optimizer Type

Obtain Operating Point Search Report

Extract Operating Points at Simulation Snapshots

Vary Parameters and Extract Operating Points at Simulation Snapshots

Input Arguments

mdl — Simulink model name character vector | string

opspec — Operating point specifications OperatingSpec object | array of OperatingSpec objects

param — Parameter samples structure | structure array

options — Trimming options findopOptions option set

tsnapshot — Simulation snapshot times scalar | vector

Output Arguments

op — Operating point OperatingPoint object | array of OperatingPoint objects

opreport — Operating point search report OperatingReport object | array of OperatingReport objects

More About

Steady-State Operating Point (Trim Condition)

Tips

Algorithms

Alternative Functionality

App

Version History

R2021b: PortWidth property of operating point inputs and outputs will be removed

See Also

Topics

`mdl` — Simulink model name
character vector | string

`opspec` — Operating point specifications
`OperatingSpec` object | array of `OperatingSpec` objects

`param` — Parameter samples
structure | structure array

`options` — Trimming options
`findopOptions` option set

`tsnapshot` — Simulation snapshot times
scalar | vector

`op` — Operating point
`OperatingPoint` object | array of `OperatingPoint` objects

`opreport` — Operating point search report
`OperatingReport` object | array of `OperatingReport` objects

R2021b: `PortWidth` property of operating point inputs and outputs will be removed