Set Up Feature and Strategy

A feature calibration is the process of calibrating lookup tables by comparing an electronic control unit (ECU) strategy to a statistical model. A Simulink^® model represents the ECU strategy. For more information about the process, see Process for Calibrating and Filling Feature Tables.

The Model-Based Calibration Toolbox™ calibrates an estimator, or feature, for a control subsystem in an ECU. Features are usually algebraic collections of one or more lookup tables. You use the features to estimate signals in the engine that are unmeasurable, or expensive to measure, and are important for control. The toolbox can calibrate the ECU subsystem by directly comparing it with a plant model of the same feature.

A strategy is an algebraic collection of lookup tables, and forms the structure of the feature. Model-Based Calibration Toolbox uses the strategy to estimate signals in the engine that cannot be measured.

To evaluate the feature side by side with the model, you need to have a strategy that takes some or all of the same variables as the model. The strategy is expressed using Simulink diagrams. You can either import a strategy or you can construct a strategy.

You can import features for selected Simulink subsystems.

Add a Feature

A feature consists of a model and a collection of lookup tables organized in a strategy.

To add a feature, select File > New > Feature. This automatically switches you to the Feature Filling view and adds an empty feature to your session.

An incomplete feature is a feature that does not contain both an assigned model and a strategy. If a feature is incomplete, CAGE displays in the tree display. If a feature is complete, CAGE displays in the tree display.

Import a Strategy from Simulink

Highlight the top feature node in the tree display.
Select File > Import > Strategy.
Select the appropriate Simulink model file.
If there is a single outer outport, CAGE automatically imports the strategy.
If there are multiple outer outports, CAGE prompts you to import all output ports into separate features.
Use the MBC Feature Importer to preview lookup tables and import features for selected Simulink subsystems. Click OK.
To view a text representation of your strategy, select the Feature node.

If parsing the Simulink diagram fails and you see an error message, then the toolbox discards changes in the current CAGE project. Correct the Simulink model and reparse it.

Model Structure and Strategy Hierarchy

CAGE uses the Subsystem hierarchy in the Simulink model to generate subfeatures in CAGE. This makes it easier to understand the structure of the strategy and relate it to the Simulink model. However, be aware how CAGE creates subfeatures from Simulink models:

When a subsystem has more than one outport, CAGE adds the outport name to the subsystem for the subfeature name. Rename an outport before importing if you want a particular name for the CAGE subfeature. CAGE creates unique names.
CAGE creates a subfeature from outports in subsystems. CAGE works backward from outports and includes all input blocks to the outport in the subfeature, including blocks outside the subsystem. Subfeatures are not identical to Simulink subsystems.
CAGE shows the subfeature hierarchy in the Feature tree. Each subfeature is also visible at the top level of the tree.

Lookup Tables, Normalizers, and Constants

Names and reuse

If the parameter is a valid variable name and not a MATLAB^® expression, CAGE uses the variable names to determine the lookup table and normalizer names. This supports lookup table reuse and avoids the need for explicit normalizer blocks.
For constants, CAGE uses the block name or constant variable name, if defined. Constants are reused if they have the same name as an existing constant and the value is the same.
If a lookup table with the same name exists in the project and the input expressions for these lookup tables are the same, then the toolbox reuses the lookup table. Similarly, the toolbox reuses normalizers if they have the same inputs as the existing normalizer.
If a lookup table of the same name exists in project and the new lookup table has different inputs, then CAGE asks what option you want:
- Create a lookup table with a different name (suffix _1).
- Reconnect the lookup table inputs using the current Simulink block connections.
- Cancel. You can then edit the model to resolve differences if desired.

Lookup table and normalizer structure

Shared normalizers can be used as inputs to multiple lookup tables. You can view shared normalizers at the top of the CAGE Lookup Table tree.
You can create 1-D tables with or without normalizers. If you add a CAGE Function block from cgeqlib without a normalizer, a 1-D lookup table with an internal normalizer is created on parsing. If the Function block has a normalizer as its input, then you can use shared normalizers (from the list of available normalizers in CAGE). After creation, you cannot change from using shared normalizers to internal normalizers.
2-D lookup tables always have shared normalizers. If the input to the Table block is not a normalizer, then CAGE creates a normalizer when the strategy is parsed.
CAGE assigns normalizer names using the lookup table breakpoint (or row/column index) variable names, if available. If an expression defines the breakpoints and not a variable, then CAGE names normalizers using the form tablename_normY or tablename_normX.
If you change the name of inports, table, or normalizer blocks for blocks associated with existing CAGE items, then the CAGE items name is changed. The name is unique for the current CAGE project (suffix _1 is added if necessary to create a unique name).
Prelookup tables must feed into an Interpolation block using a Prelookup block.
Normalizer blocks, if used, must be inputs to lookup tables.
Transient feature fills support Simulink models with n-D lookup tables.

Data import

Table and normalizer data is imported from Simulink.
You must be able to run Update Diagram on the Simulink model and the data must have a single source. Otherwise, lookup table data is left empty and you must set up the lookup tables, normalizers, and constants using the Calibration Manager.
Constant data is read from Constant or Gain blocks.

Block Support

CAGE supports a subset of Simulink blocks. To view the supported blocks, open the cgeqlib library.

cgeqlib

Supported blocks for features in Model-Based Calibration Toolbox

This supported blocks are in these library subsystems.

Subsystem Description

System Inputs Supported system input blocks, including the Variable and From Workspace blocks.

Calibration Scalars Supported calibration blocks, including the Constant and Gain blocks.

Lookup Tables Supported lookup table blocks, including the 1-D Lookup Table and Interpolation Using Prelookup blocks.

Signal Routing and Attributes

Supported signal routing blocks, including the Goto and Mux blocks.

CAGE ignores signal conditioning blocks. Several standard Simulink blocks are intended for conditioning signals, but you can ignore the blocks for analysis in CAGE. These blocks include the Signal Conversion, Rate Transition, Data Type Conversion, and Initial Condition blocks. CAGE ignores them, making it easier to import existing strategy diagrams.

Transient Blocks

Supported blocks for feature fills to optimize calibrations with transient controllers.

The subsystem also includes blocks that CAGE uses to create a single top-level feature for the first-order transient system, improving the optimization performance.

The Continuous First-order System block in the cgeqlib library has these Integration Method settings.

Setting	Use Considerations
`Forward Euler`	Most continuous first-order systems
`Backward Euler`	Feed-forward systems Provides numerical stability for feature filling when the sample time is large, including variable sample time
`Trapezoidal`	Feed-forward systems Provides numerical stability for feature filling when the sample time is large, including variable sample time
`Exponential Euler`	Constant time constant Slowly time-varying time constant

Logical Expressions and Switches

Supported logical and switch blocks, including the Logical Operator, Relational Operator, and MultiportSwitch blocks.

When you import the Switch block, CAGE converts it to a CAGE block called IfExpr.

Logical expressions are only an issue if inputs to the logical expression include a lookup table that you are trying to fill. Connecting logical expressions to measured inputs (inports) or constants is fine because the logical expressions do not require differentiation.

Caution

If inputs to the logical or switch blocks include lookup tables that CAGE will try to fill, feature filling may fail. CAGE cannot differentiate non-smooth logical or switch expressions.

If inputs to the logical or switch blocks are measured inputs or constants, however, CAGE can fill the feature.

Math Blocks

Supported math blocks, including the Dot Product and Math Function blocks.

For polynomials, CAGE builds polynomial expressions using Horner’s form (Product and Sum blocks).

Only scalar inputs are supported except for the MATLAB Function, Dot Product, Polynomial, and Interpreted MATLAB Function blocks, which accept multiple inputs as inputs to the expression (e.g., u(1)+u(2)).

Caution

Feature filling may fail if your model contains:

Non-smooth functions like sign and round
Nonlinear expressions in these blocks:
- MATLAB Function
- Interpreted MATLAB Function

Battery Systems

Supported blocks for feature filling models that contain battery blocks from Simscape™ Battery™ and Powertrain Blockset™. Each block models common components used in battery equivalent circuits. They include:

SOC Counter – Keeps track of the state of charge (SOC) by counting coulombs. During battery block calibration, CAGE does not use the SOC Counter block if you select Use measured SOC when importing the block.
RC Circuit (SOC) – Models a resistor and capacitor in parallel. Varies the resistance and capacitance with SOC.
RC Circuit (SOC,T) – Models a resistor and capacitor in parallel. Varies the resistance and capacitance with SOC and temperature.
RC Circuit(SOC, T) Current Directionality – Models a resistor and capacitor in parallel. Varies the resistance and capacitance with SOC and temperature.
RC Circuit(SOC,T,current) – Models a resistor and capacitor in parallel. Varies the resistance and capacitance with SOC, temperature, and current.
Hysteresis Model – Models a hysteresis element in a resistor-capacitor network based on a state estimator. The state estimator is calibrated through the Hysteresis Rate and effectively drives the zero-crossing voltage potential using the Maximum Hysteresis and Instantaneous Hysteresis Voltage tables. The Hysteresis Rate must be a scalar.
Thermal Convection Circuit – Models a convection thermal circuit such that the air temperature source drives power into or out of the battery thermal mass which is heating due to power loss. Use this block to correlate a Simscape Battery block when the Thermal model parameter is set to Lumped thermal mass.

Note
The Equivalent Circuit Battery (Powertrain Blockset) block reports the power being generated within the cell.
Entropic Heating – Models a Lithium Ion exothermic reversible heating model that is the product of current, temperature, and an entropic coefficient. The Entropic Coefficient is a function of SOC. To match the Simscape Battery model, set the State of Charge Breakpoints to the SOC breakpoints for the OCV breakpoints.

For more information on calibrating battery blocks, see Calibrate Powertrain Blockset and Simscape Battery Blocks.

This table summarizes the transient and steady-state block support for feature fills.

Block	Transient	Steady-State
Unit Delay	✔	Ignored
Delay - Discrete, fixed, and variable	✔	Ignored
Discrete-Time Integrator - Forward, backward, and trapezoidal	✔	Not supported
Discrete Transfer Fcn - Initial conditions set to zero with no ability to modify the transfer function	✔	✔ — Treated as a steady-state gain if transfer function is stable
Discrete Filter	✔
Continuous First-Order System^*	✔
First-Order Filter^*	✔
First-Order Transfer Function^*	✔
^*Block that CAGE uses to create a single top-level feature for the first-order transient system, improving the optimization performance. Use the first-order system to estimate time constants and gains specified by lookup tables or scalars in CAGE.

Loop Handling

This table summarizes the CAGE algebraic look implementation for transient and steady-state feature fills.

Feature Fill Type	Implementation
Steady-state	CAGE cannot handle expressions with loops. If CAGE detects a loop, then CAGE asks if you want to break the loop by introducing a variable called `previousOutportName`. If possible, CAGE tries to break loops at a feature boundary (for example, a top level or subsystem output). If you decide not to break the loop, an error message informs you which blocks are involved in the loop. CAGE ignores Delay blocks and Resettable Delay blocks to facilitate loop parsing.
Transient	Transient feature calibration does not allow models with algebraic feedback loops. Each loop must have at least one block with no direct feedthrough for example, a Delay or Discrete-Time Integrator - Forward integration block.

Feature Fill Type

Implementation

Steady-state

CAGE cannot handle expressions with loops. If CAGE detects a loop, then CAGE asks if you want to break the loop by introducing a variable called previousOutportName. If possible, CAGE tries to break loops at a feature boundary (for example, a top level or subsystem output).

If you decide not to break the loop, an error message informs you which blocks are involved in the loop.

CAGE ignores Delay blocks and Resettable Delay blocks to facilitate loop parsing.

Transient

Transient feature calibration does not allow models with algebraic feedback loops. Each loop must have at least one block with no direct feedthrough for example, a Delay or Discrete-Time Integrator - Forward integration block.

Importing Older Strategies

To parse strategies from previous releases, you can use the function cgStrategyTables to set the style for strategy parser behavior. Use cgStrategyTables to import any older strategies saved as Simulink model files.

For strategies from R2013a or later, CAGE interprets the first input to a 2-D lookup table as Y (rows). Previously, CAGE parsed the first input as columns and the second as rows. Use the cgStrategyTables backward compatibility modes for previously saved strategies, if needed.
For strategies from R2008a to R2012b, lookup table blocks are always interpreted as lookup tables, because there are separate lookup and normalizer blocks. In R2008a, a normalizer block was added to the cgeqlib library.
To set the parser style to R2008a, use:
```
cgStrategyTables('R2008a') 
```
For strategies older than R2008a, CAGE interprets 1-D lookup tables as normalizers if they feed into a lookup table.
To parse pre-R2008a strategies, use this function:
```
cgStrategyTables('Pre-R2008a') 
```
This reverts the parser behavior to the pre-R2008a interpretation of 1-D lookup tables. CAGE issues a warning when converting a 1-D lookup table to a normalizer. You can turn off the warning:
```
warning off mbc:cgslparser:ObsoleteNormalizer
```
To reset the parser style to R2013a and later, use:
```
cgStrategyTables('R2013a') 
```
To query the current strategy table style, enter:
```
Style = cgStrategyTables
```

Construct a Strategy

To construct a strategy from CAGE rather than import an existing model:

Highlight the correct feature by selecting the Feature node.

Select Feature > Edit Strategy.

Three Simulink windows open:

Window	Description
Strategy	Use to edit your strategy.
Library, `cgeqlib`	Blocks available for building a strategy.
CAGE Project Library	Existing blocks in your CAGE project, organized into libraries. Blocks are From blocks referencing the CAGE items such as tables and normalizers.

In the strategy window, build your strategy using the blocks in the library windows. To perform a feature calibration, the strategy and the model must have some variables in common.
To parse the strategy into the CAGE session, double-click the blue outport circle.

The cgeqlib library contains all the blocks available for building a strategy.

Export Strategies

Export Simulink strategies if you want to:

Include a strategy in a Simulink vehicle model.
Compile the strategy using Simulink Coder™ to produce C code.
Evaluate the strategy using Simulink.

To export a strategy from CAGE:

Highlight the Feature node that contains the strategy that you want to save.
Select File > Export > Strategy.
Assign a name for your strategy.
The strategy is saved as a Simulink model file.

On export, table data is stored in variables. Indices are written to Simulink parameters using colon expressions.

For 2-D lookup tables, 0:size (Table,1)-1, 0:size (Table,2)-1, TableName
For 1-D lookup tables with shared normalizers, 0:length (Table)-1, TableName
For 1-D lookup tables, NormalizerName and TableName
NormalizerName, 0:length(Normalizer)-1

The data is stored in the model workspace. The model workspace data is copied to the new model when you copy the strategy block. You must be able to run Update Diagram on the Simulink model or the copy process does not work. Copying the strategy model requires a Model-Based Calibration Toolbox.