MATLAB Functions

In addition to functions written in ATLAS's Function Definition Language (FDL) ATLAS 10 is able to call external interpreters to evaluate functions written in alternative languages. This guide explains how to construct a function which evaluates in MATLAB.  In ATLAS 9, to access data from MATLAB you must write a script which uses the ActiveX API to read the data and process it plus write it back into ATLAS.  This new method takes the hard work away and leaves you to concentrate on just the function implementation rather than the method of passing data between ATLAS and MATLAB. 

Important Notes

• It is not possible to open MATLAB functions inside the ATLAS 10 Function Editor. Doing so may cause ATLAS 10 to terminate abnormally.
• You must have a working, licensed MATLAB installation on the PC running ATLAS 10 with MATLAB functions. Presently R2015b 64bit and R2016b 64bit versions have been tested.

Example

A MATLAB function comprises at least two parts; an .XFN file which gives ATLAS 10 an XML interface to the MATLAB function and a .M file which contains the actual MATLAB script implementation. .M files can call one another so it is possible to have multiple .M files making up a single definition.

The .XFN file must be in the ATLAS 10 Functions directory: %HOMEPATH%\Documents\McLaren Electronic Systems\SQL Race\Functions

The .M files are referenced by absolute path from the .XFN file so can be located anywhere. All .M files which make up a single function definition however must be in the same folder or in folders on the MATLAB path. In this example they will be placed in the ATLAS 10 Functions directory like the .XFN file above.

1. The three files in this example are CalculateSlipRatios.xfn, calculateslipratios.m and slipratio.m, download these and place them all in the functions directory.
2. Edit the CalculateSlipRatios.xfn file in any normal text editor, find the <FilePath>...</FilePath> line (line 54) and edit it so the correct, absolute path to the calculateslipratios.m file is in the inner pair of square brackets.
3. Start ATLAS 10 (or if it is already running, restart it).
4. Four ATLAS input parameters are referenced; vCar:Chassis, vWheelFL:Chassis, vWheelFR:Chassis, vWheelRL:Chassis and vWheelRR:Chassis so for the function to calculate, data containing these parameters must be loaded.
5. Four output parameters are calculated: rSlipRatioFL:Functions, rSlipRatioFR:Functions, rSlipRatioRL:Functions and rSlipRatioRR:Functions. These should now be available to add to any display from the ATLAS 10 Parameter Browser or Quick Access shortcut.

MATLAB Function .XFN File in detail

In order to write your own MATLAB functions a template .XFN file is provided to download. The template looks like this:

Firstly the InputParameters section defines which ATLAS parameter identifiers are to be sourced by the MATLAB function. There should be an Identifier line for each input parameter to the function.

The OutputParameters section defines the output function parameter properties for each value the MATLAB function calculates. Each OutputParameter must have a Name, Description, Units, Format, DisplayMin and DisplayMax. Your MATLAB function can define more than one output parameter.

The calculation defaults should be left as they are, these will be described in more detail in later Help documents.

The FilePath line is the link between ATLAS and the MATLAB .M file which contains the implementation in MATLAB script. This is an absolute path.

The InputMappings section defines how the ATLAS input parameter identifiers appear to MATLAB in the .M script. In this example the input parameter vCar:Chassis is translated to a MATLAB variable named simply vCar which is referenced in the code. There must be a Mapping entry for each of the Identifiers lines in the InputParameters section.

The OutputMappings section defines how the MATLAB output parameters appear to ATLAS 10 in the Parameter Browser. In this example the MATLAB variable output by the script rSlipRatioFL will appear with the rSlipRatioFL:Functions identifier in ATLAS. There must be a Mapping entry for each of the OutputParameter entries in the OutputParameters section.

MATLAB Function .M File in detail

The absolute basic .M file just assigns values to the OutputParameter Mapping MATLAB variable names. Our slightly more complicated example uses a MATLAB function call, referencing the input variables as arguments and assigns the function return to the output variable names. Any valid MATLAB code can appear in the .M files.

So in our example the .XFN function definition references calculateslipratios.m:

This calls the MATLAB function slipratio() using the input parameter names as the function arguments and assigns the function return to the four output variables. The actual calculation is done inside slipratio.m which defines a standard function in MATLAB:

The Future

MATLAB functions are a relatively new feature in ATLAS 10 and this document is here to help you get started with the basics and preview the capabilities. It is intended that in the future the .XFN file will be generated by the ATLAS 10 Function Editor meaning it is only necessary to point ATLAS at the .M file implementation. Please use Zendesk to raise further questions.