MATLAB Functions

Function Signature

As an example, consider the file MATLAB_CalcObject_Eval.m, which contains the following:

function [output] = Matlab_CalcObject_Eval(input)
switch input.method
    
    case 'register'
        
        % create output here to register inputs/outputs
    
    case 'compute'
    
        computeData = input.methodData;
                % create output struct containing values for the outputs based on the
        % inputs in computeData
        
    otherwise
        output = [];
end

Every MATLAB .m file must follow this same paradigm. Note that input is a MATLAB Struct whose method value is a string (the calling mode). On compute, the inputs are to be extracted from computeData for use in computing output.

Registration of Input and Output Arguments

Each script function requests inputs and outputs by returning a descriptor for each of the requested arguments. The descriptor contains a list of strings of the form "keyword, value". STK parses the keyword-value pairs to identify the requested argument. The number of keyword-value pairs that is required to describe an argument depends upon the complexity of the argument: simple inputs and outputs require fewer pairs than more complicated ones. If a requested argument cannot be identified, then that script function is disabled.

Note: The keyword string is case insensitive—we capitalize certain letters for legibility in examples and documentation. The value string is case sensitive however, with some exceptions (e.g., ArgumentType values of "Input" and "Output" are actually case insensitive).

Every requested input or output argument descriptor must contain the keywords ArgumentType and ArgumentName. The value of ArgumentType is either Input or Output. The value of ArgumentName can be any user-specified variable name that obeys the language's syntax for a valid variable name. (Thus, special characters and spaces are not allowed.) The ArgumentName is intended to be a unique name for that argument when referenced in the script.

Note: The order of the keyword-value pairs within an argument descriptor is arbitrary, although we adopt a convention where ArgumentType is first, so that you can identify which arguments are inputs and outputs more readily.

Argument descriptors in MATLAB are specified in the form of a MATLAB CellArray. For example, the code:

incDescriptor = {   'ArgumentType','Input',...
                    'ArgumentName','inc',...
                    'Name','Inclination',...
                    'Type','CalcObject'};

describes an Input argument which is a CalcObject named Inclination, which will be referred to in this .m file by the name 'inc'. When the script is called in compute mode, the name 'inc' will be used to extract the input value for this argument.

Here is an example showing 3 arguments (1 output, 2 inputs) being registered:

case 'register'
        
        valueDescriptor = {      'ArgumentType','Output',...
                        'ArgumentName','value',...
                                        'Name','Value'};
    
        incDescriptor = {       'ArgumentType','Input',...
                        'ArgumentName','inc',...
                                        'Name','Inclination',...
                              ,'CalcObject'};
        rightAscDescriptor = {  'ArgumentType','Input',...
                        'ArgumentName','rightAsc',...
                            'Name','RAAN',...
                            'Type','CalcObject'};
    
    output = {valueDescriptor, incDescriptor, rightAscDescriptor};

Computing Outputs from Inputs

When the script is called upon to compute, the inputs and outputs are handled as follows:

case 'compute'
    
        computeData = input.methodData;
        output.value = cos(computeData.inc)*cos(computeData.rightAsc);

Note that the ArgumentNames are used to extract and set the data.

Note: Arrays in MATLAB are passed as column vectors, not row vectors.

STK Programming Interface 11.0.1