operspec

Operating point specifications

collapse all in page

Syntax

opspec = operspec(mdl)
opspec = operspec(mdl,dim)

Description

example

opspec = operspec(mdl) returns the default operating point specification object for the Simulink® model mdl. Use opspec for steady-state operating point trimming using findop.

example

opspec = operspec(mdl,dim) returns an array of default operating point specification objects with the specified dimensions, dim.

Examples

collapse all

Open Script

Open Simulink model.

sys = 'watertank';
open_system(sys)

Create the default operating point specification object for the model.

opspec = operspec(sys)

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

States: 
----------
(1.) watertank/PID Controller/Integrator/Continuous/Integrator
	 spec:  dx = 0,  initial guess: 0
(2.) watertank/Water-Tank System/H
	 spec:  dx = 0,  initial guess: 1

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

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

opspec contains specifications for the two states in the model. Since the model has no root level inports or outports, opspec does not contain input or output specifications. To add output specifications, use addoutputspec.

Modify the operating point specifications for each state using dot notation. For example, configure the first state to:

  • Be at steady state.

  • Have a lower bound of 0.

  • Have an initial value of 2 for trimming.

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

You can create new operspec variables in three ways:

  • Using the operspec command

  • Using assignment with the equals (=) operator

  • Using the copy command

Using the = operator results in linked variables that both point to the same underlying data. Using the copy command results in an independent operspec object. In this example, create operspec objects both ways, and examine their behavior.

mdl = 'watertank';
open_system(mdl);
opspec1 = operspec(mdl)
 Operating point specification for the Model watertank.
 (Time-Varying Components Evaluated at time t=0)

States: 
----------
(1.) watertank/PID Controller/Integrator/Continuous/Integrator
	 spec:  dx = 0,  initial guess: 0
(2.) watertank/Water-Tank System/H
	 spec:  dx = 0,  initial guess: 1

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

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

Create a new operating point specification object using assignment with the = operator. 

opspec2 = opspec1;

opspec2 is an operspec object that points to the same underlying data as opspec1. Because of this link, you cannot independently change properties of the two operspec objects. To see this, change a property of opspec2. For instance, change the initial value for the first state from 0 to 2. The change shows in the States section of the display.

opspec2.States(1).x = 2
 Operating point specification for the Model watertank.
 (Time-Varying Components Evaluated at time t=0)

States: 
----------
(1.) watertank/PID Controller/Integrator/Continuous/Integrator
	 spec:  dx = 0,  initial guess: 2
(2.) watertank/Water-Tank System/H
	 spec:  dx = 0,  initial guess: 1

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

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

Examine the display of opspec1 to see that the corresponding property value of opspec1 also changes from 0 to 2.

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

States: 
----------
(1.) watertank/PID Controller/Integrator/Continuous/Integrator
	 spec:  dx = 0,  initial guess: 2
(2.) watertank/Water-Tank System/H
	 spec:  dx = 0,  initial guess: 1

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

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

To create an independent copy of an operating point specification, use the copy command. 

opspec3 = copy(opspec1);

Now, when you change a property of opspec3, opspec1 does not change. For instance, change the initial value for the first state from 2 to 4. 

opspec3.States(1).x = 4
 Operating point specification for the Model watertank.
 (Time-Varying Components Evaluated at time t=0)

States: 
----------
(1.) watertank/PID Controller/Integrator/Continuous/Integrator
	 spec:  dx = 0,  initial guess: 4
(2.) watertank/Water-Tank System/H
	 spec:  dx = 0,  initial guess: 1

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

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

In opspec1, the corresponding value remains 2. 

opspec1.States(1).x
ans = 2

This copy behavior occurs because operspec is a handle object. For more information about handle objects, see Handle Object Behavior.

Open Script

Open Simulink model.

sys = 'watertank';
open_system(sys)

Create a 2-by-3 array of operating point specification objects. You can batch trim model at multiple operating points using such arrays.

opspec = operspec(sys,[2,3]);

Each element of opspec contains a default operating point specification object for the model.

Modify the operating point specification objects using dot notation. For example, configure the second state of the specification object in row 1, column 3.

opspec(1,3).States(2).SteadyState = 1;
opspec(1,3).States(1).x = 2;

You can also create multidimensional arrays of operating point specification objects. For example, create a 3-by-4-by-5 array.

opspec = operspec(sys,[3,4,5]);

Input Arguments

collapse all

Simulink model name, specified as a character vector or string.

Array dimensions, specified as one of the following:

  • Integer — Create a column vector of dim operating point specification objects.

  • Row vector of integers — Create an array of operating point specification objects with the dimensions specified by dim.

    For example, to create a 4-by-5 array of operating point specification objects, use:

    opspec = operspec(mdl,[4,5]);

    To create a multidimensional array of operating point specification objects, specify additional dimensions. For example, to create a 2-by-3-by-4 array, use:

    opspec = operspec(mdl,[2,3,4]);

Output Arguments

collapse all

Operating point specifications, returned as an operating point specification object or an array of such objects.

You can modify the operating point specifications using dot notation. For example, if opspec is a single operating point specification object, opspec.States(1).x accesses the state values of the first model state. If opspec is an array of specification objects opspec(2,3).Inputs(1).u accesses the input level of the first inport block for the specification in row 2, column 3.

Each specification object has the following properties:

PropertyDescription
ModelSimulink model name, returned as a character vector.
States

State operating point specifications, returned as a vector of state specification 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. Edit the properties of this object using dot notation or the set function.

Note

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

Each state specification object has the following fields:

FieldDescription
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, specified as a vector of length Nx.

If the corresponding flag in Known field of States is 1, x contains the known state values. Otherwise, x contains initial guesses for the state values.

Ts

(Only for discrete-time states) Sample time and offset of each supported block state, returned as a vector.

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.

Known

Flags indicating whether state values are known during trimming, specified as a logical vector of length Nx.

  • 1 — Known value that is fixed during operating point search

  • 0 (default) — Unknown value found by optimization

To fix a state during an operating point search, set the corresponding Known flag to 1, and specify the value for that state using the x property of States.

SteadyState

Flags indicating whether output values are at steady state during trimming, specified as a logical vector of length Nx.

  • 1 (default) — Equilibrium state

  • 0 — Nonequilibrium state

Min

Minimum bounds on state values, specified as a vector of length Nx. By default, the minimum bound for each state is -Inf.

Max

Maximum bounds on state values, specified as a vector of length Nx. By default, the maximum bound for each state is Inf.

dxMin

Minimum bounds on state derivatives that are not at steady-state, specified as a vector of length Nx. By default, the minimum bound for each state derivative is -Inf. When you specify a derivative bound, you must also set SteadyState to 0.

dxMax

Maximum bounds on state derivatives that are not at steady-state, specified as a vector of length Nx. By default, the maximum bound for each state derivative is Inf. When you specify a derivative bound, you must also set SteadyState to 0.

Description

Block state description, specified as a character vector.

Inputs

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

Each input specification object has the following fields:

FieldDescription
Block

Inport block name

PortWidth

Number of inport block signals

PortDimensions

Dimension of signals accepted by the inport

u

Inport block input levels at the operating point, returned as a vector of length PortWidth.

If the corresponding flag in Known field of Inputs is 1, u contains the known input values. Otherwise, u contains initial guesses for the input values.

Known

Flags indicating whether input levels are known during trimming, specified as a logical vector of length PortWidth.

  • 1 — Known input level that is fixed during operating point search

  • 0 (default) — Unknown input level found by optimization

To fix an input level during an operating point search, set the corresponding Known flag to 1, and specify the input value using the u property of Inputs.

Min

Minimum bounds on input levels, specified as a vector of length PortWidth. By default, the minimum bound for each input is -Inf.

Max

Maximum bounds on input levels, specified as a vector of length PortWidth. By default, the maximum bound for each input is Inf.

Description

Inport block input description, specified as a character vector.

Outputs

Output level specifications at the operating point, returned as a vector of output specification objects. Each entry in Outputs represents the output levels of one root-level outport block of the model or one trim output constraint in the model.

You can specify additional trim output constraints using addoutputspec.

Each output specification object has the following fields:

FieldDescription
Block

Outport block name

PortWidth

Number of outport block signals

PortNumber

Number of this outport in the model

y

Outport block output levels at the operating point, specified as a vector of length PortWidth.

If the corresponding flag in Known field of Outputs is 1, y contains the known output values. Otherwise, y contains initial guesses for the output values.

Known

Flags indicating whether output levels are known during trimming, specified as a logical vector of length PortWidth.

  • 1 — Known output level that is fixed during operating point search

  • 0 (default) — Unknown output level found by optimization

To fix an output level during an operating point search, set the corresponding Known flag to 1, and specify the output value using the y property of Outputs.

Min

Minimum bounds on output levels, specified as a vector of length PortWidth. By default, the minimum bound for each output is -Inf.

Max

Maximum bounds the output levels, specified as a vector of length PortWidth. By default, the maximum bound for each output is Inf.

Description

Outport block input description, specified as a character vector.

Time

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

CustomObjFcn

Function providing an additional custom objective function for trimming, specified as a handle to the custom function, or a character vector or string that contains the function name. The custom function must be on the MATLAB® path or in the current working folder.

You can specify a custom objective function as an algebraic combination of model states, inputs, and outputs. For more information, see Compute Operating Points Using Custom Constraints and Objective Functions.

CustomConstrFcn

Function providing additional custom constraints for trimming, specified as a handle to the custom function, or a character vector or string that contains the function name. The custom function must be on the MATLAB path or in the current working folder.

You can specify custom equality and inequality constraints as algebraic combinations of model states, inputs, and outputs. For more information, see Compute Operating Points Using Custom Constraints and Objective Functions.

CustomMappingFcn

Function that maps model states, inputs, and outputs to the vectors accepted by CustomConstrFcn and CustomObjFcn, specified as a handle to the custom function, or a character vector or string that contains the function name. The custom function must be on the MATLAB path or in the current working folder.

For complex models, you can pass subsets of the model inputs, outputs, and states to the custom constraint and objective functions using a custom mapping function. If you specify a custom mapping, you must use the mapping for both the custom constraint function and the custom objective function. For more information, see Compute Operating Points Using Custom Constraints and Objective Functions.

Tips

  • To display the operating point specification object properties, use get.

  • You can create new operspec variables of in 3 ways:

    • Construct a new object with the operspec command.

    • Create a new variable by assignment with the equals (=) operator.

    • Copy an operspec object using the copy command.

    Using operspec or copy creates a new, independent object. When you use assignment, there is a link between the old and new variable. For an example, see Copy an Operating-Point Specification.

See Also

| | |

Introduced before R2006a

Simulink Control Design Documentation

Support