5.5.1 Introduction
Let’s take a look at the following, very primitive Simulink model.
The gain factor is not a constant value but a workspace variable named k.
>> disp(k) 0.7827
We want to generate C code for this simple model and we want to be able to set a different gain factor at the beginning of each simulation. In other words, we want the gain blocks’s parameter k to be a tunable parameter. Being able to change a block parameter’s value after C code generation, when the code is running, that’s what tunable parameters are all about.
Usually, at the beginning of a simulation, CarMaker reads all information about testruns, vehicle configuration etc. from external parameter files. These files are named Infofiles after the way the data they contain is formatted. The CarMaker target’s tunable parameter inter-face is mostly about storing Matlab workspace variables in Infofiles, retrieving a tunable parameter’s value from an Infofile or setting it directly.
To make use of CarMaker’s tunable parameter interface with a Simulink model one normally has to perform the following steps:
• Enabling tunable parameters in the Simulink model.
• Adding statements to the model wrapper which modify the model’s tunable parameters.
• Creating infofile entries with the values of all parameters to be tuned (optional).
The remaining sections of this chapter will guide you through the details of parameter tun-ing, always keeping an eye on the simple example introduced at the beginning.
Figure 5.13: Simulink model with a single parameter
Figure 5.14: Simulink model with a single parameter
75 Integrating Simulink models
CarMaker’s tunable parameter interface
5.5.2 Enabling tunable parameters in a Simulink model
Let’s continue with our little Simulink model. The next thing we do is to tell Simulink that the workspace variable k should be treated as a tunable parameter and tell Real-Time Work-shop to include special parameter tuning data in the generated C code.
Matlab 6.x For Matlab 6.x models enabling parameter tuning can be done as follows:
In the model window’s menu bar, in theSimulationmenu, we chooseSimulation Param-eters...In the dialog, on theAdvancedtab, we selectInline parametersand click on the Configure... button.
In theModel Parameter Configurationdialog, we add k to the list ofGlobal (tunable) parameters, like in the screendump below.
Make sure that the storage class of the parameter is SimulinkGlobal. The CarMaker target’s tunable parameter interface functions apply to parameters of this storage class only.
Figure 5.15: SelectingInlne parameters
Figure 5.16: Marking parameter k as tunable
76 Integrating Simulink models
CarMaker’s tunable parameter interface
Next, on theReal-Time Workshoptab, we select the CarMaker target and enable code generation for tunable parameters by adding the-aParameterTuning=1option in theSystem target file entry.
Matlab 7.x For Matlab 7.x models the steps are similar to those for Matlab 6.x described above:
In the model window’s menu bar, in theSimulationmenu, chooseConfiguration Param-eters... which opens a dialog.
In the listbox on the left click onOptimization. On the tab selectInline parametersand click on theConfigure...button. This will bring up the sameModel Parameter Configu-ration dialog as described above for our example model.
In the listbox on the left click, underReal-Time Workshopclick onInterface. On the tab, in theData exchangearea, select C-API asInterfaceand make sure thatParameters in C API is enabled.
5.5.3 Modifying tunable parameters in the model wrapper
After you’ve generated C code for your model using the model settings explained in the pre-ceding paragraphs, in principle everything is ready for parameter tuning at runtime. What remains to be done is to write the program statements that assign the tunable parameters of a model their desired values, either coming from an Infofile or being the result of some calculation.
The model wrapper (fileXXX_wrap.c) generated by Real-Time Workshop contains a func-tion called XXX_SetParams() which will be called automatically everytime the model is ini-tialized at the beginning of a simulation. In a newly created wrapper module the function does almost nothing. Add your parameter tuning statements at the location indicated below:
void
XXX_SetParams (SimStruct *rts, struct tMatSuppTunables *tuns, struct tInfos *Inf) {
/*Log("%s_SetParams()\n", Modelname);*/
/*
* Parameter tuning - Part 1
* This is the place to modify parameters of a storage class * other than ‘SimulinkGlobal’.
*/
if (tuns == NULL)
Figure 5.17: Enabling code generation for tunable parameters
77 Integrating Simulink models
CarMaker’s tunable parameter interface
return; /* No tunable parameters in this model. */
/*
* Parameter tuning - Part 2
* This is the place to modify parameters of storage class ‘SimulinkGlobal’, * e.g. using the CarMaker target’s tunable parameter interface.
*/
/*MatSupp_TunRead(tuns, ...);*/
/*MatSupp_TunReadDef(tuns, ...);*/
/*MatSupp_TunReadAll(tuns, ...);*/
}
As you can see, parameter tuning for parameters which were not assigned the Simulink-Global storage class is also possible and has its place in the wrapper. See the BodyCtrl example in theExamples/RTWdirectory of your CarMaker installation, to see how tuning of an ExportedGlobal parameter could be done.
To stay with our simple Simulink model, the parameter tuning code for out simple model may (after having removed most of the comments) look like this:
void
simple_SetParams (SimStruct *rts, struct tMatSuppTunables *tuns, struct tInfos *Inf) {
/*Log("%s_SetParams()\n", Modelname);*/
if (tuns == NULL)
return; /* No tunable parameters in this model. */
MatSupp_TunReadAll(tuns, Inf, Modelname);
}
Running the model in CarMaker would then proceed as follows: During initialization of a simulation, all tunable parameters will be reset to their original values (i.e. the values they had when the C code was generated). After that simple_SetParams() will be called auto-matically. Our function tries to find entries for all the tunable parameters of the model in the vehicle parameter file (Inf handle). If an infofile entry named simple.k is present, k will be set to the entry’s value. If no such entry is present, k will keep its original value (0.7827 in our case). The simulation will then proceed using the actual value of k.
A detailed description of the functions of CarMaker’s tunable parameter interface can be found in the next chapter. At the end of each function’s description you will find one or more small examples which may help you setting up your parameter tuning code in XXX_SetParams().
For accessing Infofile values you may also want to refer to functions of the Infofile library.
See the specific chapter in this manual and also the include file of the library, to be found at include/infoc.h in your CarMaker installation.
5.5.4 Parameter values in Infofiles
The last question is how to make Infofile entries for the tunable parameters of a model. Nor-mally one wants to take a snapshot of the current values of the Matlab workspace variables in question (probably at the time the model C code is generated) and create the correspond-ing entries in an Infofile.
CarMaker’s tunable parameter interface provides several utility commands available at the Matlab prompt, which help you in automatically creating infofile entries for the tunable parameters of a Simulink model. Please refer to the online help of the following commands, their use should be rather self explaining:
>> help cmtuncreate
>> help cmtunappend
78 Integrating Simulink models
CarMaker’s tunable parameter interface
>> help cmtundump
These commands make use of the ifile suite of commands for infofile access, for which an online help is available, too:
>> help ifile
Tunable parameters will be stored using the ifile_setmat command (uses InfoSetMat()) and CarMaker’s tunable parameter interface functions will try to read them using InfoGetMat() and InfoGetMatDef() of the infofile library.
The tInfoMat infofile entries created by InfoSetMat() are capable of storing most of Matlab’s numeric types, including complex and n-dimensional matrices in an infofile entry. For the most common and simple cases like scalars and vectors, however, a tInfoMat entry with its structure header may sometimes be “too much”. For this reason, compatibility with earlier infofile entry formats like
SomeScalar = 3.1415
SomeVector = 10 12 13 14 15 16 17
is provided when reading an entry with InfoGetMat() / InfoGetMatDef(). This means in many cases you may stay with the simpler entries like the ones mentioned, which also has the advantage of being compatible with other CarMaker components with no such strong con-nection to Matlab.
5.5.5 Adding tunable parameters to the CarMaker dictionary
After initialization a tunable parameter’s value remains constant during the whole simula-tion, so normally there’s no point in making it a dictionary quantity so that e.g. it can be mon-itored in IPG-CONTROL. But think of what would be possible if the parameter could be changed on the fly using Direct Variable Access (DVA).
For example, you may want to experiment with a parameter’s value during the simulation, observing the immediate change in your model’s behaviour.
Or suppose you want to be able to activate or deactivate parts of your Simulink model at will. Simply add a Gain block to a signal which multiplies the signal by either 0 or 1, make the block’s gain factor tunable and add it to the CarMaker dictionary.
Definition of such a parameter quantity means adding some code to the function DeclPa-rameterQuants(), to be found in a Simulink model’s wrapper module (XXX_wrap.c). Let’s add a single scalar parameter MyParam to the dictionary:
static void
DeclParameterQuants (struct tMatSuppTunables *tuns) {
MatSupp_TunDDictDefScalar(tuns, “MyParam”, INFOMAT_DOUBLE, “kappa”, “kg/s”);
}
The quantity will be called kappa and its unit will be kg/s. Giving the resulting dictionary quantity a name different from that of the parameter allows for e.g addition of some kind of name prefix like the model’s name etc.
Please note that the DeclParameterQuants() function will be called twice, first with tuns equal toNULL. The reasons for the two invocations lie in the internal sequence of events dur-ing CarMaker testrun initialization. When the function is entered for the first time, the mod-el’s XXX_New() function has not yet been called so absolutely no tunable parameter information is available. Still, this is the time when dictionary quantities must be defined, so the necessary information about the tunable parameter’s type must be supplied explicitly to MatSupp_TunDDictDefScalar(), e.g.INFOMAT_DOUBLE in our case.
Only scalar tunable parameters may be defined as dictionary quantities. For complex tun-able parameters the quantity will reflect only the state of the real part.
79 Integrating Simulink models
CarMaker’s tunable parameter interface
5.5.6 Known limitations
Parameters in multiple model instances in Matlab 6.x
When working with multiple instances of a model, e.g. multipe instances of a tire model, all instances share the same set of tunable parameters. As a consequence, when you modify a tunable parameter in one instance, the modification will apply to all other instances of the model as well and all instances will do their calculations using the parameter’s new value.
Please note that this is a fundamental limitation of Time Workshop’s Generic Real-Time Target in Matlab 6.x, on which the CarMaker target is based, and not a limitation of CarMaker’s tunable parameter interface.
Multiple tunable parameter instances in Matlab 6.x
In Matlab 6.x the generated C code may contain multiple instances of a tunable parameter that all need updating when the parameter’s value is changed (see the Real-Time Work-shop manual for details about parameter instances in the generated C code). The functions of the CarMaker tunable parameter interface do handle this, but when such a tunable parameter is added to the CarMaker dictionary, the dictionary quantity will reflect only the state of the first instance of the tunable parameter. This limitation also applies to changing such a parameter quantity’s value with DVA.
80 Integrating Simulink models
CarMaker’s tunable parameter interface
5.5.7 Tunable parameter interface functions
MatSupp_TunRead() – Read a parameter from an infofile
Syntax
Reads the value of tunable parameter param from the entry named key in infofile inf.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle as well as a vehicle data infofile handle Inf are available by default.
If successful, the function returns 0. In case of an error, -1 is returned and an error message will be issued to the CarMaker log.
Example
MatSupp_TunRead(tuns, “MyParam”, Inf, “Body.mass”);
MatSupp_TunReadDef() – Read a parameter from an infofile
Syntax
Reads the value of tunable parameter param from the entry named key in infofile inf. If for any reason he value cannot be set from the infofile entry, the provided default value is used instead. A default value of NULL means to use the parameter’s original value as the default.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle as well as a vehicle data infofile handle Inf are available by default.
If successful, the function returns 0. In case of an error, -1 is returned and an error message will be issued to the CarMaker log.
Example
MatSupp_TunReadDef(tuns, “MyParam1”, Inf, “Steering.Rack2StWhl”, NULL);
81 Integrating Simulink models
CarMaker’s tunable parameter interface
tInfoMat *mat = InfoMatMakeScalar(INFOMAT_DOUBLE, 0, 3.14, 0);
MatSupp_TunReadDef(tuns, “MyParam2”, Inf, “Body.mass”, mat);
MatSupp_TunReadAll() – Read all parameters from an infofile
Syntax
This is a convenience function that reads the values of all tunable parameters of a Simulink model from the infofile inf. Each parameter’s name is used as the key to look up the corre-sponding infofile entry.
Optionally a prefix can be prepended to all names – e.g. if a parameter’s name is“kappa”
and keyprefix is“SuperABS”, the resulting infofile key will be“SuperABS.kappa”. A keyprefix value ofNULL or an empty string““ both mean that no prefix should be prepended.
Internally the function callsMatSupp_TunRead(), i.e. for each parameter a corresponding info-file entry is considered to be mandatory. If an entry for a parameter cannot be read an error message will be issued to the CarMaker log.
The function returns the number of parameters that could not be read.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle as well as a vehicle data infofile handle Inf are available by default.
Example
MatSupp_TunReadAll(tuns, Inf, Modelname);
MatSupp_TunReadAll(tuns, Inf, “SuperABS“);
MatSupp_TunReadAll(tuns, Inf, ““);
MatSupp_TunReadAllOpt() – Read all parameters from an infofile
Syntax
This is a convenience function that reads the values of all tunable parameters of a Simulink model from the infofile inf. Each parameter’s name is used as the key to look up the corre-sponding infofile entry.
82 Integrating Simulink models
CarMaker’s tunable parameter interface
Optionally a prefix can be prepended to all names – e.g. if a parameter’s name is“kappa”
and keyprefix is“SuperABS”, the resulting infofile key will be“SuperABS.kappa”. A keyprefix value ofNULL or an empty string““ both mean that no prefix should be prepended.
Internally the function callsMatSupp_TunReadDef(..., NULL), i.e. for each parameter a cor-responding infofile entry is considered to be optional. No error will be issued if a parameter cannot be read.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle as well as a vehicle data infofile handle Inf are available by default.
Example
MatSupp_TunReadAllOpt(tuns, Inf, Modelname);
MatSupp_TunReadAllOpt(tuns, Inf, “SuperABS“);
MatSupp_TunReadAllOpt(tuns, Inf, ““);
MatSupp_TunGetDbl() – Get a parameter’s value
Syntax
double MatSupp_TunGetDbl ( const tMatSuppTunables *tuns, const char *param
)
Description
Returns the value of tunable parameter param, automatically converting from the parame-ter’s internal type to type double.
Only non-complex scalar parameters may be accessed with this function. For other types use MatSupp_TunGetDblVec() or MatSupp_TunGetMat().
In case of an error the function returns 0.0 and an error message will be issued to the CarMaker log.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle is available by default.
Example
kappa = MatSupp_TunGetDbl(tuns, “kappa”);
MatSupp_TunGetDblVec() – Get a parameter’s value
Syntax
double *MatSupp_TunGetDblVec ( const tMatSuppTunables *tuns, const char *param,
int *nvalues )
83 Integrating Simulink models
CarMaker’s tunable parameter interface
Description
Returns the value of tunable parameter param in an array of type double, automatically con-verting from the parameter’s internal type. The number of elements will be stored in nval-ues. After use the array should be free()’ed by the caller.
Both non-complex scalar and vector parameters may be accessed with this function. For other types MatSupp_TunGetMat() should be used.
In case of an error the function returnsNULLand an error message will be issued to the CarMaker log.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle is available by default.
Example double *values;
int i, nvalues;
values = MatSupp_TunGetDblVec(tuns, “MyParam“, &nvalues);
for (i=0; i<nvalues; i++)
Log(“MyParam[%d] = %g\n“, i, values[i]);
free(values);
MatSupp_TunGetMat() – Get a parameter’s value
Syntax
tInfoMat *MatSupp_TunGetMat ( const tMatSuppTunables *tuns, const char *param
)
Description
Returns the value of tunable parameter param in a tInfoMat structure. After use InfoF-reeMat() should be called to release the tInfoMat structure.
Almost all parameter types, real or complex, may be accessed with this function.
In case of an error the function returnsNULLand an error message will be issued to the CarMaker log.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle is available by default.
Example tInfoMat *mat;
mat = MatSupp_TunGetMat(tuns, “MyParam”);
/* ...modify mat’s value as you like... */
MatSupp_TunSetFromMat(tuns, “MyParam”, mat);
InfoFreeMat(mat);
84 Integrating Simulink models
CarMaker’s tunable parameter interface
MatSupp_TunSetFromDbl() – Set a parameter’s value
Syntax
Sets tunable parameter param to the specified value, automatically converting to the parameter’s internal type.
Only non-complex scalar parameters may be accessed with this function. For other types use MatSupp_TunSetDblVec() or MatSupp_TunSetMat().
If successful, the function returns 0. In case of an error, -1 is returned and an error message will be issued to the CarMaker log.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle is available by default.
Example
MatSupp_TunSetFromDbl(tuns, “MyParam”, 42.0);
MatSupp_TunSetFromDblVec() – Set a parameter’s value
Syntax
Sets tunable parameter param to the data stored in the values array with nvalues many entries, automatically converting the data to the parameter’s internal type.
Both non-complex scalar and vector parameters may be accessed with this function. For other types MatSupp_TunSetMat() should be used.
If successful, the function returns 0. In case of an error, -1 is returned and an error message will be issued to the CarMaker log.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle is available by default.
Example double vec[3];
vec[0] = 3.14;
vec[1] = 6.28;
85
Sets tunable parameter param to the specified value.
Almost all parameter types, real or complex, may be accessed with this function.
If successful, the function returns 0. In case of an error, -1 is returned and an error message will be issued to the CarMaker log.
The function is intended to be used from within XXX_SetParams() in the model wrapper. In this context a valid tuns handle is available by default.
Example
mat = InfoMatMakeRowVector(INFOMAT_DOUBLE, 3, vec, NULL);
MatSupp_TunSetFromMat(tuns, “MyParam”, mat);
InfoFreeMat(mat);
MatSupp_TunDDictDefScalar – Define a parameter quantity
Syntax
int MatSupp_TunDDictDefScalar ( const tMatSuppTunables *tuns, const char *param,
tInfoMatType type,
const char *name, const char *value )
Description
Makes tunable scalar parameter param an analog, non-monotonic CarMaker dictionary quantity. The quantity can be given a name different from that of the parameter.
The type argument serves as an aid when the function is called with tuns equal toNULL. It
The type argument serves as an aid when the function is called with tuns equal toNULL. It