mbcrunner Class

Programmatically run CAGE functions

Since R2024b

Description

The mbcrunner class is a handle class.

Use the mbcrunner class and methods to programmatically run CAGE operations.

Creation

Description

obj = mbcrunner creates an mbcrunner handle object to the current project in the CAGE app.

obj = mbcrunner(projectFile) creates an mbcrunner handle object to the CAGE project specified by projectFile.

obj = mbcrunner(projectFile,inBrowser) opens the specified project in the CAGE app when you specify inBrowser as true.

Input Arguments

projectFile — CAGE project filename

string scalar

CAGE project filename, specified as a string scalar.

Data Types: string

inBrowser — Option to use current project in CAGE browser

false (default) | true

Option to use the current project in the CAGE browser, specified as false or true.

Data Types: logical

Properties

ProjectName — Name of CAGE project

string

Name of the CAGE Project, specified as a string.

Attributes:

GetAccess	public
SetAccess	private

Data Types: string

Tables — Table names of all nonempty lookup tables

vector of strings

Table names of all nonempty lookup tables in the CAGE project, specified as a vector of strings.

Attributes:

GetAccess	public
SetAccess	private

TableValues — Table values for current CAGE project

structure

Table values for the current CAGE project, specified as a structure.

Attributes:

GetAccess	public
SetAccess	private

Data Types: struct

Optimizations — Names of all runnable optimizations

vector of strings

Names of all runnable optimizations in the CAGE project, specified as a vector of strings.

Attributes:

GetAccess	public
SetAccess	private

Features — Names of features that have fill settings defined

vector of strings

Names of features that have fill settings defined in the CAGE project, specified as a vector of strings.

Attributes:

GetAccess	public
SetAccess	private

Models — Names of models in CAGE project

vector of strings

Names of the models in the CAGE project, specified as a vector of strings.

Attributes:

GetAccess	public
SetAccess	private

Variables — Names of variables in CAGE project

vector of strings

Names of the variables in the CAGE project, specified as a vector of strings.

Attributes:

GetAccess	public
SetAccess	private

Methods

Public Methods

characterizeBattery	Characterize equivalent circuit battery in CAGE project
evaluateFeature	Evaluate feature in CAGE project with data set
exportCalibration	Export calibration items from CAGE project
fill	Fill feature in CAGE project
importModels	Import new models into CAGE project
importOptimizationData	Import data for optimization in CAGE project
loadProject	Load CAGE project
optimizationResults	Retrieve optimization results
runOptimization	Run optimization in CAGE project
saveProject	Save CAGE project
updateBreakpoints	Update lookup table breakpoints in CAGE project
updateConstraints	Update optimization constraint bounds in CAGE project

Examples

Automate CAGE Operations Using mbcrunner Class

Use the mbcrunner class and methods to perform these operations programmatically for a CAGE project:

• Update project constraints.

• Import new models and rerun optimizations and feature filling.

• Retrieve the optimization results to calculate the sum objective and visualize the results.

Load Model Project

Use the mbcmodel.LoadProject method to load the gasolineOneStage.mat model project from the mbctraining folder.

proj = mbcmodel.LoadProject(fullfile( ...
    matlabroot,'toolbox', 'mbc', 'mbctraining', 'gasolineOneStage.mat'));

Create mbcrunner Object

Load the Gasoline_optimization.cag project from the mbctraining folder as the template for the mbcrunner object.

runner = mbcrunner(fullfile( ...
    matlabroot,"toolbox","mbc","mbctraining","Gasoline_optimization.cag"));

Update CAGE Project Constraints

Use the updateConstraints method to update the RESIDFRAC constraint to 24 in the BTQ_Optimization optimization.

updateConstraints(runner,"BTQ_Optimization","RESIDFRAC",24);

Update the RESIDFRAC constraint to 24 in the Sum_BTQ_Optimization optimization.

updateConstraints(runner,"Sum_BTQ_Optimization","RESIDFRAC",24);

Import Models and Rerun Optimizations

Use the importModels method to import the models from the model project to the CAGE project and rerun the optimizations and feature filling.

[models,updatedItems,updatedTables,msg] = importModels(runner,proj);

Retrieve Optimization Results

Use the optimizationResults method to retrieve the results of the Sum_BTQ_Optimization optimization.

results = optimizationResults(runner,"Sum_BTQ_Optimization");

Calculate Sum Objective

To calculate the sum objective, multiply the weights by the model values and sum all the elements.

objectiveValue = sum(results.BTQ_weights.*results.BTQ);

Visualize Residual Fraction Constraint Results

Plot the residual fraction results to review which operating points are near the limit of 24.

plot(results.RESIDFRAC, '*');
yline(24);
ylabel("RESIDFRAC");

Version History

Introduced in R2024b