Working with functions

Introduction

One of the great things about Rave is that it can work not only with static data sets, but with functions of variables that appear in data sets. For example, if you load a data set that contains a variable called "Weight (lbs)", you can easily create a new variable called "Weight (kg)" whose values are equal to Weight (lbs) / 2.2046. If later the values for the variable Weight (lbs) change, the values for Weight (kg) will automatically update to reflect that change, because the two are functionally related.

The above example is an extremely simple function. In general there is no limit to how complicated your function can be, although if the function takes a long time to run it may be impractical for some applications. Functions can have multiple variables as inputs, and may have other functional variables as inputs as well (for example, y = f(x), z = g(y)).

An important limitation, however, is that the relations between your variables must form a "directed acyclic graph". Put simply, this means that each functional variable must be able to be represented as a function of only independent variables in the data set (although as described above, your actual implementation may involve other functional variables). Functions that form a "circular logic" loop are not allowed (for example y=f(z), z=g(y) ).

Functions vs. Functional Variables

A functional variable is a variable in Rave whose value is calculated by a function. A "function" in this context is a MATLAB .m function file, in particular it is a MATLAB file that calculates the functional variable as one of its outputs. You create functional variables in Rave by loading functions into Rave or by creating functions using Rave. Note that if you create the function using Rave, the actual MATLAB function file will get created "behind the scenes" and you will typically never directly view or edit the function file.

The sections below describe the two ways of creating functional variables: loading functions, and creating functions.

Loading Functions into Rave

Rave can load two types of functions: plain text functions, and MATLAB .m file functions. Plain text functions are limited to fairly simple mathematical expressions, whereas MATLAB .m file functions can do almost anything.

In either case, the functions must be of the form: [one ore more functional variables ] = function of(one or more Rave variables)

The important thing here is that the inputs to the function must be variables that exist in your data set at the time you load the function. This limitation automatically ensures that your network of functions obeys the "directed acyclic graph" constraint. For example, it is impossible to load two functions y=f(z) and z=g(y), because the input variable of whichever function you attempt to load first would not yet exist as a variable in Rave.

In all cases, functions are loaded from the Model Tab. Follow the link to the model tab for a description of the buttons that appear on that tab.

Loading a Plain Text Function

Rave can load simple "plain text" functions that meet the following criteria:

• The function calculates a single output variable. It may have any number of input variables.
• The function involves only basic math operators: + - * / ^ abs(), sin(), cos(), log() etc...
• The function can theoretically be represented as a single statement (line) of MATLAB code. I.e. it cannot involve "if" statements, "for" loops etc.
• The names of all input variables are legal matlab variable names. This generally means they must begin with a letter and cannot contain symbols (other than _) or spaces.

Rave can load plain text functions either from a .txt file, or you can type/paste them into a dialog box. In either case, the content of the function should be only the right hand side of the equals sign. For example, if you have the function y = x1 + x2, you would use only "x1+x2" as the content of the function. You will supply the name of the output variable when you load the function into Rave.

• Tip: If you are loading a function stored in a .txt file, Rave will suggest the file name as the default variable name. So you can save time by using the functional variable's names as your file names.

• Developer tip: The function that Rave uses to convert plain text files to .m files is named ravetxt2m.m

Examples: A simple function may look like:

x1 + cos(x2) * abs(x1/x2) - exp(x) + x^2

A more complicated function could be:

exp(11.6703935+Thrust*-0.0000326600101+FPR*-1.41803275+LPCPR*0.00415193051+OPR*-0.0029531291+T4max*-0.000195797154+Vratio*-1.92648403+Loading*0.360255868+Payload*0.0000284530331+Range2*0.000163181712+Thrust*Thrust*0.000000000606111453+FPR*Thrust*-0.00000438394509+FPR*FPR.*0.508561336+LPCPR*Thrust*-0.000000658367223+LPCPR*FPR*-0.0092802591+LPCPR*LPCPR*0.0160130278+OPR*Thrust*0.00000000140482047+OPR*FPR.*0.000770681078+OPR*LPCPR*0.0000346999344+OPR*OPR*0.0000202874834+T4max*Thrust*-0.00000000212251231+T4max*FPR*-0.0000692665696+T4max*LPCPR*0.000036486005+T4max*OPR*-0.00000109566933+T4max*T4max*0.0000000544769111+Vratio*Thrust*-0.000000980437888+Vratio*FPR*-0.0132480486+Vratio*LPCPR*-0.0825760778+Vratio*OPR.*0.00185308179+Vratio*T4max*-0.0000103482963+Vratio*Vratio*0.570256604+Loading*Thrust*0.000000941943684+Loading*FPR*-0.0350705609+Loading*LPCPR*-0.0595044256+Loading*OPR*0.00249845651+Loading*T4max*-0.0000518362764+Loading*Vratio*-0.00857311658+Loading*Loading*-0.0755155667+Payload*Thrust*-0.000000000179474291+Payload*FPR*-0.00000118332246+Payload*LPCPR*-0.000000114138247+Payload*OPR*-0.00000000578049718+Payload*T4max*0.000000000171659028+Payload*Vratio*0.000000279097022+Payload*Loading*-0.000000166412116+Payload*Payload*-0.0000000000599337645+Range2*Thrust*-0.000000000837792856+Range2*FPR*0.0000218442552+Range2*LPCPR*-0.000000383165627+Range2*OPR*-0.000000264719975+Range2*T4max*-0.0000000167869449+Range2*Vratio*0.0000190871404+Range2*Loading*0.000000714906327+Range2*Payload*-0.000000000182036483+Range2*Range2*-0.000000000321241661)

Three-Input Format

Modeled Variables

When you import a function, you are given the option to define its output variable to be a new model of an existing variable in your data set. Regardless of what you choose, the output of the function will be added to your data set as a new variable. If you select a variable from the list, Rave will note that the selected variable and the new variable that you are creating are linked in the sense that they both represent the same physical quantity, though they may have different numerical values since they come from different sources.

Currently this linking does not affect Rave in any way.

In the future, you will be able to perform some special tasks with variables that are linked in this way.

Note: Whenever you create a surrogate model, it is automatically linked as a model of the variable it is based on.

Objective Functions

Objective functions can be created by clicking the "Create New Objective Fcn" button on the Model Tab. Objective functions are similar to general user-supplied functions, with the following exceptions:

• Objective functions get recalculated whenever the user changes the Data Set, the Preferences or the Targets. General user-supplied functions only get recalculated when the user changes the Data Set. Consequently, any function that uses Preferences or Targets should be set as an Objective function.

Objective functions can be created by using the "Create New Objective Fcn" gui, which comes with built-in templates that help you automatically generate code for these functions.

Function files created by Rave

Whenever you load a function into Rave that is not a .m MATLAB file, Rave creates a .m "wrapper" function that it calls in place of the function you specified. This function in turn calls the original file you specified in a way that is compatible with Rave.

• When you load a .txt function, the .m file that is created contains all the information that was in your .txt file. Rave does not use the .txt file, only the .m file. You can delete or move the original .txt file and it won't break Rave.
• When you load any type of function other than a .txt file or a .m file, Rave creates a new .m file to run the function, but it also uses the original file you specified and any other files that depend on this file. Make sure to keep all such dependent files in a place where Rave can find them.

See also: MATLAB search path