View source for User-Supplied Matlab Function Formats

This page describes the required formatting for user-supplied MATLAB functions whose purpose is to calculate [[functional variables]].

Rave can run any MATLAB function as long as it obeys some not-very-constraining rules about the function definition line, (i.e. the first line of the function), and some slightly-more-constraining rules about the input and output formats and [[vectorization]]. The good news is that these rules ensure that it is always possible to write a "wrapper" function that can act as an interface between Rave and your existing data-generating MATLAB functions. In other words, Rave only constraints the functional interface, not what happens inside the body of the function. You can even call external programs, for example using the MATLAB "system" command, and you can read/write files if necessary. 


=Function Interface Requirements=
The constraints Rave places on the function definition line relate to how you specify the inputs to the function. This is because Rave needs to be able to parse your function and determine what data to send it and how to send the data. 

You have three options for what you use as the function definition line. Regardless of which option you use, the [[functional variable]] names must appear as outputs of the function. Rave will use the names of the function's outputs as the names of the corresponding [[functional variables]]. The name of the function itself (i.e. the .m file name) does not matter as long as it is a legal matlab function name (i.e. must begin with a letter and cannot contain spaces or symbols other than _ ).

'''NOTE: The function declaration must be the FIRST line of the file. You may not place comments or empty space above the function declaration.'''

===Variable Names as Inputs===
You can use the input variable's names as the inputs to the function. An obvious constraint in this case is that the variable names must be legal MATLAB variable names. For example, the following function definition would work:

<syntaxhighlight>
function [y,z]=myFunction(x1,x2)
</syntaxhighlight>

This function calculates two [[functional variables]] (y, z) as functions of two existing variables, x1,x2. Rave does not restrict the order in which you list the input variables; list them in whatever order works for you. You could also use:
<syntaxhighlight>
function [y,z]=myFunction(x2,x1)
</syntaxhighlight>

The order of the outputs matters insofar as any time Rave lists the variable names they will appear in the same order in which they appeared in the function definition.

===Single-Input Format===

An alternative option is to specify a single input to the function. When you import the function, Rave will ask which variables to use as inputs to the function. The actual input data that Rave sends the function will then be an array in which each column represents one variable in your [[data set]].  

The benefit of this format is that it places no restrictions on your variable names; they do not need to be legal MATLAB variable names. However it can be more difficult to implement this type of function because you need to ensure that your code correctly deals the columns of the input array to variables. 

'''Example:'''

Consider the [[data set]]:
<pre>
Case Number,Thrust,Payload,Range1,Range2,FPR,LPCPR,OPR,T4max,Vratio,Loading,HPT Stages
1,28000,39000,250,2000,1.5,2.2,30,3125,1.8,0.2,1
2,28000,39000,250,2000,1.5,2.2,30,3125,1.8,0.3,1
3,28000,39000,250,2000,1.5,2.2,30,3125,1.87,0.2,1
... ... ... ... ... ... ... ... ... ... ... ... ...
</pre>

And suppose we have a function that calculates five output variables
<pre> Fan_Diameter Max_Range TOFL TSFC Engine_Weight</pre>
as functions of six of the [[independent variables]]:
<pre>FPR, LPCPR, OPR, T4max, Vratio, Loading</pre>

The function definition using the ''Variable-Names-as-Inputs'' syntax would look like:
<syntaxhighlight>
function [Fan_Diameter Max_Range TOFL TSFC Engine_Weight]=myFunction(FPR,LPCPR,OPR,T4max,Vratio,Loading)
</syntaxhighlight>


The function definition using the ''Single-Input'' syntax would look like:
<syntaxhighlight>
function [Fan_Diameter Max_Range TOFL TSFC Engine_Weight]=myFunction(inputs)
</syntaxhighlight>
where we have chosen to name the array of input data "inputs". (You can use any name you like, as long as it is not also the name of a variable in the [[data set]]. For example we could not have called it "FPR" in this example.)

Later in the function, you would need to turn the columns of ''inputs'' into individual variables. The variables appear in the columns that match their order in the [[data set]]. Referring to the [[data set]] excerpt above, we see that FPR is the 6th variable (after Case Number,Thrust,Payload,Range1,Range2) thus the values of FPR will be in the 6th column of the ''inputs'' array.

<syntaxhighlight>
FPR=inputs(:,6);
LPCPR=inputs(:,7);
OPR=inputs(:,8);
T4max=inputs(:,9);
Vratio=inputs(:,10);
Loading=inputs(:,11);
</syntaxhighlight>

===Three-Input Format===

=Function Attributes=
'''Note: This section concerns a future version of Rave'''
Future versions of Rave will allow more flexibility in the user supplied .m file functions. In order for you to communicate certain attributes of your functions to Rave, you can list these attributes in a comment on the second line of your m-file (immediately following the function declaration at the top.) When Rave reads in your .m file, it will scan the second line for keywords that it recognizes as attribute names and will then apply those attributes when evaluating your function.

*The function attributes must be on the SECOND LINE of the file, immediately following the function declaration line with no other lines of comments or empty space in between. All attributes must appear in this second line; do not wrap to additional lines. 
*Note that Rave only looks for attributes when it initially reads in the function. This means that if you change the attributes while using Rave, your changes will not take effect until you restart Rave. (Or save and reload your [[Rave Project]] file.)
*Attributes are only relevant to .m function files. Imported .txt functions or functions you create within Rave never have attributes. 

'''Future Versions''' of Rave will recognize the following attributes (case insensitive but must otherwise must appear exactly as below including the #)
* #OnePointAtATime - Indicates to Rave that your function is not vectorized (i.e. that it can only evaluate one point at a time) and that Rave must call it in a loop in order to evaluate multiple points.
* #OneToMany - Indicates to Rave that this is a "probabilistic" function that returns a vector of points for each input point. In this case, the output arrays must be CELL ARRAYS, where the ith cell contains the vector of results that correspond to the ith row of the input vectors. The input arrays must still be regular numerical arrays -- only the outputs are cells.

=Vectorization Requirements=
When Rave needs to evaluate your functions at multiple data points, it DOES NOT call your function multiple times in a loop. Instead, it creates input arrays with ''n'' rows, where ''n'' is the number of points to be evaluated. This is done because "good practice" in MATLAB is to avoid using for loops and instead call functions in this "vectorized" way.

The outputs returned by your function must also be vectors with ''n'' rows. For best speed, it is recommended that you code your user-supplied Rave functions to avoid using loops, and this is usually possible if your function is written in "pure matlab". However in some cases your function will require a for loop, for example if it calls an external analysis code that is only capable of evaluating a single function at a time. In such cases, you must include the loop inside the body of your user-supplied .m function.