FRR-36 MatlabFunction

Feature Spec and Test Procedures

Lead: Joel

Developer: Linda

Tester: Shawn

 

Explore

Known Bugs

Failing Tests

Other Findings

Requirements

FRR-36 (new)

Interface/Functional Spec

Overview

Description

Fields

GUI

Remarks

Search Path

Examples

Test Procedures

Assumptions

Existing Tests

Recommended Additional Tests

Nominal Tests

Edge/Corner/Stress

Unique Validation

Unique Mode Tests

Unique GUI Tests

Explore

Known Bugs

 

JIRA ID

Summary

Rec.

GMT-161

Common Tasks: Calling MATLAB Functions: Calling a MATLAB Function

P1. Joel will fix.

GMT-1098

Tab key navigation fails

Appears fixed

GMT-1106

Filename extension and Matlab path checks

Appears fixed

GMT-2315

Relative GMAT_FUNCTION_PATH paths don't work on Windows

Verify

GMT-2425

GMAT does not perform any pre-run-script checks when adding a Matlab function

Duplicate of GMT-1106

GMT-2906

Incorrect usage of relative paths when setting GmatFunction.FunctionPath

Needs tests

GMT-3034

Cannot create MatlabFunction with same name as an existing .gmf file

P1

GMT-3106

Make GMAT Functions a plugin

P1

Failing Tests

There are no failing tests as of 2011-11-15.

Other Findings

JIRA ID

Summary

Rec.

GMT-3321 , GMT-3322

MATLAB functions sometimes use stale data or path information if the window isn’t closed between runs (edit matlab function and rerun, change FunctionPath and rerun)

P1

Requirements

FRR-36 (new)

 

ID

Requirement

FRR-36.1

The system shall allow the user to declare a name as the name of an external function in the MATLAB language.

FRR-36.2

The system shall allow the user to specify a path to search for the declared function.

Interface/Functional Spec

Overview

 

Declaration of an external MATLAB function.

Description

The MatlabFunction resource declares to GMAT that the name given refers to an existing external function in the MATLAB language. This function can be called in the Mission Sequence like a built-in function, with some limitations. See the MATLAB Function Call reference for details. Both user-created functions and built-in functions (like cos or path ) are supported.

 

GMAT supports passing data to and from MATLAB through the function. It requires that a supported and properly configured version of MATLAB exist on the system.

 

See Also : MATLAB Function Call , MATLAB Interface

Fields

See the User Interface Spec spreadsheet for reference information for fields.

GUI

Figure 1 : The MATLAB Function GUI window

 

The MatlabFunction GUI window is very simple; it has a single file input box for the function path, and a Browse button that lets you graphically select the path.

Remarks

Search Path

When a function declared as a MatlabFunction is called, GMAT starts MATLAB in the background with a custom, configurable search path. MATLAB then searches for the named function in this search path. The search is case-sensitive, so the name of the function name and the MatlabFunction resource must be identical.

 

The search path consists of the following components, in order:

1         FunctionPath field of the associated MatlabFunction resource (default: empty)

2         MATLAB_FUNCTION_PATH entries in the GMAT startup file (default: < GMAT >\userfunctions\matlab )

3         MATLAB search path (returned by the MATLAB path() function)

 

If multiple MATLAB functions are called within a run, the FunctionPath fields for each are prepended to the search path at the time of the function call.

 

Multiple paths can be combined in the FunctionPath field by separating the paths with a semicolon (on Windows) or a colon (on Mac OS X and Linux).

Working Directory

When MATLAB starts in the background, its working directory is set to the GMAT bin directory.

Examples

 

Call a simple built-in MATLAB function:

 

Create MatlabFunction sinh

Create Variable x y

 

BeginMissionSequence

 

x = 1

[y] = sinh(x)

 

Call an external custom MATLAB function:

 

Create Spacecraft aSat

Create ImpulsiveBurn aBurn

Create Propagator aProp

 

Create MatlabFunction CalcHohmann

CalcHohmann.FunctionPath = 'C:\path\to\functions'

 

Create Variable a_target mu dv1 dv2

mu = 398600.4415

 

BeginMissionSequence

 

% calculate burns for circular Hohmann transfer

[dv1, dv2] = CalcHohmann(aSat.SMA, a_target, mu)

 

% perform first maneuver

aBurn.Element1 = dv1

Maneuver aBurn(aSat)

 

% propagate to apoapsis

Propagate aProp(aSat) {aSat.Apoapsis}

 

% perform second burn

aBurn.Element1 = dv2

Maneuver aBurn(aSat)

 

Return the MATLAB search path and working directory:

 

Create MatlabFunction path pwd

Create String pathStr pwdStr

Create ReportFile aReport

 

BeginMissionSequence

 

[pathStr] = path

[pwdStr] = pwd

 

Report aReport pathStr

Report aReport pwdStr

Test Procedures

Assumptions

(None)

Existing Tests

(None)

Recommended Additional Tests

Nominal Tests

All test names begin with the prefix “ MatlabFunction_ ”.

Status

Name

Summary

Builtin

Declare and call MATLAB built-in function

Custom

Declare and call custom function


(2012-11-20)

(Manual)

Declare and call custom function with specified absolute path

Relative

Declare and call custom function with specified relative path


(2012-11-20)

(Manual)

Path variations in startup file

 

Edge/Corner/Stress

All test names begin with the prefix “ MatlabFunction_ ”.

Status

Name

Summary

Custom_magic

Declare and call custom function with same name as MATLAB built-in function

Custom_DegToRad , Custom_DegToRad_Assignment

Declare and call custom function with same name as GMAT built-in function

 

Unique Validation

All test names begin with the prefix “ MatlabFunction_Validation ”.

Status

Name

Summary

FunctionPath_*

Invalid function path

FunctionType_*

Run the wrong type of function

 

Unique Mode Tests

 

Status

Name

Summary

 

 

 

 

 

 

 

 

 

 

 

Unique GUI Tests

These are tests that are unique to the GUI interface for this feature that are not covered by the standard GUI test template and procedures.

 

Status

Name

Summary