Model-Based Calibration Toolbox™

User-Defined Optimization

Introducing User-Defined Optimization

User-defined optimizations are described in the following sections:

• Implementing Your Optimization Algorithm in CAGE describes how to customize the optimization template to use your optimization routines in CAGE.

• There is a step-by-step guide to using the example provided to help you understand how to modify the template file to use your own optimization functions. See the optimization tutorial sectionWorked Example Optimization in the Getting Started documentation.

In many cases the standard routines supplied for constrained single objective (foptcon, ga, and patternsearch) and multiobjective optimization (NBI) are sufficient to allow you to solve your optimization problem. Sometimes, however, you need to write a customized optimization algorithm. This can be useful in many situations, for example,

• For an expert to capture an optimization process to solve a particular problem, for example, determination of optimal spark angle and exhaust gas recirculation rate on a port-fuel injection engine

• To implement an alternative optimization algorithm to those supplied

• To implement a complex constraint or objective that is only possible through writing M-code

• To produce custom output graphics

User-defined optimization functions in CAGE allow advanced users to write their own optimization routines that can access current CAGE data. In order to access the user function from CAGE, you must register the M-file with CAGE and place it on the MATLAB path. It is crucial that this function conforms to the template specified. The following sections describe this process.

Back to Top

Implementing Your Optimization Algorithm in CAGE

At some point a CAGE optimization function calls on an algorithm to optimize the objective functions over the free variables. You can implement the algorithm in the CAGE optimization function as an external M-file. Use the template file as a basis for your optimization function. The best way to understand how to alter the template file to implement your own optimization algorithms is to compare it with the worked example, as described in the optimization tutorial.

• See the following optimization tutorial sections in the Getting Started documentation:

  • Worked Example Optimization describes the process of using the worked example

  • Creating an Optimization from Your Own Algorithm describes in detail the steps necessary to use an example optimization algorithm in CAGE

• About the Worked Example Optimization Algorithm

  examines the coding involved in implementing an external optimizer in a CAGE optimization M-file

• Checking User-Defined Optimizations into CAGE explains how to check in your optimization function so you can use it in CAGE

Optimization Function Structure

The optimization function M-files have two sections. To compare these sections in the worked example with the template file on which it is based:

1. Locate and open the file mbcOStemplate in the mbctraining directory

2. Type the following at the command line to open the example:

   edit mbcOSworkedexample
   

The two sections are the Options section and Evaluate section.

1. The Options function section contains the settings that define your optimization. Here you can set up these attributes:

   • Name

   • Description

   • Free variables

   • Objective functions

   • Constraints

   • Helper data sets

   • Optimization parameters

   CAGE interacts with the cgoptimoptions object, where all these settings are stored.

   See Methods of cgoptimoptions for information about setting up the options section.

   If you leave the cgoptimoptions function unchanged, your optimization function must be able to support the default options. That is, your optimization will have:

   • One objective

   • Any number of constraints (selected by the user in CAGE )

2. The Evaluate function section contains your optimization routine. CAGE calls this section when the Run button is clicked.

   Place your optimization routine under this section, interacting with CAGE (obtaining inputs and sending outputs) via the cgoptimstore object. Your optimization must conform to the following syntax:

   optimstore = <Your_Optimization> (optimstore)
   

   where <Your_Optimization> is the name of your optimization function.

   Any subfunctions called by your optimization routine should also be placed at the bottom of this section.

   See Methods of cgoptimstore.

Note   Be careful not to overwrite the worked example and template files when you are trying them out — save them under a new name when you make changes.

There is a step-by-step guide describing how to modify the template using the worked example optimization function in the optimization tutorial. See Worked Example Optimization in the Getting Started documentation.

Back to Top

About the Worked Example Optimization Algorithm

mbcweoptimizer is an example of a user-specified optimization that solves the following problem:

max TQ over (AFR, SPK).

• [bestafr, bestspk] = mbcweoptimizer(TQ) finds a maximum (bestafr, bestspk) to the function TQ.

  TQ must be a function (or a function handle) where the first two input arguments are AFR and SPK respectively. TQ functions with more parameters can be used. The extra parameters to these functions can be specified using anonymous functions. For example if a TQ model has N and L inputs, you can use the following call to mbcweoptimizer:

  [bestafr, bestspk] = mbcweoptimizer(@(afr, spk)TQ(afr, spk, N, L))
  

• [bestafr, bestspk]=mbcweoptimizer(TQ, afrrng, spkrng) finds a maximum (bestafr,bestspk) to the function TQ.

  afrrng and spkrng are 1-by-2 row vectors containing search ranges for those variables.

• [bestafr, bestspk]=mbcweoptimizer(TQ, afrrng, spkrng, res) finds a maximum (bestafr,bestspk) to the function TQ.

  This optimization is performed over a res-by-res grid of (AFR, SPK) values. If res is not specified, the default grid resolution is 25.

The Structure of the Worked Example

The best way to understand how to implement an external optimizer in a CAGE optimization function is to study the details of the example.

• To view the whole worked example M-file, at the command line, type

  edit mbcOSworkedexample
  

The following code section is taken from the Evaluate section of the worked example file as an example.

The code fragment above is in the i_Evaluate subfunction. This subfunction is called once for each run of the script. The line of code labeled A above calls the worked example optimization algorithm external to the optimization function. As with functions in the Optimization Toolbox product, the first argument to the call to the optimizer is a function handle that evaluates the objectives at a given input point. We recommend you place the function pointed at by the function handle in the optimization file. If you do not place them in the same file you must make sure the evaluate function M-file is on the MATLAB path. As an example, the optimization evaluation function in the worked example optimization is shown in the code fragment following.

The inputs to n_evalTQ are the required inputs for the torque (in this case) model. To evaluate the objective, the evaluate method from the optimstore object is used. In the above example, the line of code referenced by B evaluates the torque model in the worked example at the (afr, spk) input points. The values of (N, L) at the current run are used in the evaluation of the torque model. CAGE retrieves these values from optimstore when the torque model is evaluated.

The two subfunctions presented above are an example of how to implement an external optimizer in a CAGE optimization M-file.

See also the optimization tutorial section Creating an Optimization from Your Own Algorithm in the Getting Started documentation, which describes in detail the steps involved in incorporating an example algorithm into a CAGE optimization M-file.

Back to Top

Checking User-Defined Optimizations into CAGE

When you have modified the template to create your own optimization function, you must check it into the Model-Based Calibration Toolbox product in order to use the function in CAGE. Once you have checked in your optimization function it appears in the Optimization Wizard. See Optimization Wizard.

To check a user-defined optimization into CAGE,

1. Select File -> Preferences.

2. Click the Optimization tab and click Add... to browse to your M-file. Select the file and click Open. This registers the optimization function with CAGE. You need to do this when you customize your own optimizations.

   

   The example shows the worked example function, which is already registered with CAGE for use in the optimization tutorial.

3. You can click Test to check that the optimization function is correctly set up. This is a very useful function when you use your own functions; if anything is incorrectly set up the test results tell you where to start correcting your function.

   You can see an example of this by saving a copy of the worked example file and changing one of the variable names (such as afr) to a number. Try to check this altered function into CAGE and the Test button will return an informative error specifying the line you have altered.

4. Click OK to dismiss the CAGE Preferences dialog box and return to the CAGE browser.

   Registered optimizations appear in the Optimization Wizard when you set up a new optimization.

Back to Top

Interpreting Sum Optimization Output

Optimization Function Reference