EIR-1 MATLAB Interface

Feature Spec and Test Procedures

Lead: Joel

Developer: Linda

Tester: Shawn

 

Explore

Known Bugs

Failing Tests

Other Findings

Requirements

Interface/Functional Spec

Overview

Description

GUI

Remarks

Interface Setup

MATLAB Engine Connection

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-927

Libration script Matlab problem/rerun issue

P3. M→G issue

GMT-998

No Pause/Stop button when using Matlab

P3. M→G issue

GMT-999

Multi-Matlab run bug

P3. M→G issue

GMT-1190

MATLAB Callbacks on Linux and Mac

P3. Linux/Mac issue

GMT-1191

Scripts run through MATLAB don't allow access to reports in GUI

P3. M→G issue

GMT-1340

Matlab connection issue

Document

GMT-1347

Matlab window not reopening

Verify

GMT-1458

Getting data from GMAT while in MATLAB

Improvement

GMT-1472

MATLAB->GMAT not working

P3. M→G issue

GMT-1486

Matlab Engine Error Log

Improvement

GMT-1539

Matlab Server: Single quote stripped from lines passed to GMAT

P3. M→G issue

GMT-2054

GMAT crashes when MATLAB engine does not open on Mac

P3. Mac issue

GMT-2247

DOCUMENT:  MATLAB interface requires manual configuration by user

Document

GMT-2327

Spawned MATLAB command window sometimes doesn't close

P1

GMT-2828

build suggestion for libMatlabInterface and libFminconOptimizer

Improvement

GMT-2920

Closing MATLAB window after running function causes further runs to fail

P1

GMT-2923

MATLAB interface timeout

P1

GMT-2948

On Linux, the MATLAB interface does not work and is unstable

P3. Linux issue

 

Failing Tests

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

Other Findings

 

JIRA ID

Summary

Rec.

 

 

 

 

Requirements

 

ID

Requirement

EIR-1.1

The system shall support an interface that allows GMAT to call MATLAB functions according to the requirements FRC-17 and FRR-36.

EIR-1.2.0

The interface shall allow the user to choose among the following modes for MATLAB calls:

EIR-1.2.1

    1) Each GMAT instantiation on a single system creates its own, non-shared, instantiation of MATLAB by calling the engOpenSingleUse() interface.

EIR-1.2.2

    2) Each GMAT instantiation  on a single system shares the same instantiation of MATLAB by calling the engOpen() interface.

EIR-1.3

Suggest we remove this requirement: The system shall support an interface that allows a user to run a GMAT script from MATLAB .  This interface is defined as the MATLAB->GMAT interface.

EIR-1.4

The system shall initiate the interface once per session, as needed, and reuse the interface for all subsequent operations.

 

Interface/Functional Spec

Overview

Interface to MATLAB system

Description

The MATLAB interface provides a link to the Mathworks MATLAB environment, allowing GMAT to run MATLAB functions as if they were native functions in the GMAT script language.

 

The interface cannot be controlled directly through the script language, though it can be in the GMAT GUI. Instead, GMAT starts the interface automatically when it calls a MATLAB function.

 

For details on declaring a MATLAB function, see the MatlabFunction reference. For details on calling a function and passing data, see the MATLAB Function Call reference.

 

See Also : MatlabFunction , MATLAB Function Call

GUI

Figure 1 MATLAB Interface

 

The MATLAB interface provides an icon in the Interfaces folder in the R esources tree that can be used to control the interface. Right-clicking the icon shows two options: Open and Close .

 

The Open menu item causes GMAT to open a connection to the MATLAB Engine, which in turns displays a MATLAB command window in the background. This connection is then used for all communication between GMAT and MATLAB until the connection is closed. Only one connection can be open at a time.

 

The Close menu item causes GMAT to close any open connection to the MATLAB Engine. If no connection is open, it has no effect.

Remarks

Interface Setup

The following conditions must be true for GMAT to successfully initiate communication with MATLAB. All conditions must be true for the same instance of MATLAB.

      A compatible, licensed version of MATLAB must be installed on the same machine on which GMAT is running. GMAT officially supports the current version of MATLAB at the time of release, though versions R2006b and newer have been known to work.

      The architecture (32-bit or 64-bit) of GMAT and the installed version of MATLAB must match. For example, the 32-bit version of GMAT is compatible only with the 32-bit version of MATLAB.

      On Windows:

      The following path (where < MATLAB > is the path to the installed version of MATLAB) must be present in the Path environment variable. For some older versions of MATLAB, this path must be present before the default Windows paths.

     < MATLAB >\bin\win32 (or win64 for use with 64-bit versions of GMAT)

      MATLAB must be registered as a COM server. This is done automatically by the MATLAB installer. To do it manually, open an elevated command window and run the command:
matlab -regserver
Make sure the proper instance of MATLAB is being run by this command.

      On Mac OS X:

      The MATLABFORGMAT environment variable must exist and contain the full path to the MATLAB application bundle (e.g. /Applications/MATLAB_R2012b/MATLAB_R2012b.app ).

      On Linux:

      What goes here?

MATLAB Engine Connection

 

Caution: GMAT does not close the MATLAB Command Window it creates after a run has completed. This allows manual inspection of the MATLAB workspace, but it can lead to confusing behavior if MATLAB functions or paths are changed and rerun in the same window.

 

We recommend closing the MATLAB Command Window by right-clicking Matlab in the Resources tree and clicking Close between each run if you are actively editing the script.

 

When GMAT runs a mission that contains a MATLAB function call, it opens a connection to the MATLAB engine before it makes the function call. It then reuses this connection for the rest of the GMAT session.

 

The MATLAB Engine can be controlled manually through the Open and Close options available by right-clicking the Matlab item in the Resources tree.

Examples

(Same examples as MatlabFunction )

Test Procedures

Assumptions

(None)

Existing Tests

(None)

Recommended Additional Tests

Nominal Tests

 

Status

Name

Summary

(2012-11-20)

(Manual)

Supported versions of MATLAB

(2012-11-20)

(Manual)

Correct paths in system path

(2012-11-20)

(Manual)

Matching architectures

 

 

Edge/Corner/Stress

 

Priority

Status

Name

Summary

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Unique Validation

 

Status

Name

Summary

(2012-11-20)

(Manual)

Non-matching architectures

(2012-11-20)

(Manual)

Not registered as COM server

(2012-11-20)

(Manual)

Missing paths in system path

 

Unique Mode Tests

 

Priority

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.

Priority

Status

Name

Summary