Introduction

GMAT provides a flexible mechanism that lets users place both scalar and matrix computations into the command sequence for a mission. This mechanism is called inline mathematics in GMAT. For architectural design and specification on inline mathematics, refer to Chapter 30 “Inline Mathematics in GMAT” in /doc/SystemDocs/ArchitecturalSpecification/GMAT-Architectural-Specification.pdf. 

The GMAT function allows users to write a sub-script and save to separate file and called from the main script or within a function itself. For architectural design and specification on GMAT functions, refer to Chapter 31 “GMAT and MATLAB Functions” in /doc/SystemDocs/ArchitecturalSpecification/GMAT-Architectural-Specification.pdf.

The Built-in GMAT function is predefined function implemented in GMAT which allows to access internal objects and perform specified tasks, such as reading a file, perform coordinate system conversion, etc.

There are many types of built-in functions implemented in GMAT. However new functions can be created to extend GMAT to perform a new task. This document will describe a general procedure to add a new function to the baseline GMAT code.

Overview

Inline functions can be used in the script for math or string operations. The assignment command supports the use of inline mathematical expressions on the right-hand side of the command. These expressions follow the general syntax rules of MATLAB expressions, and can use a variety of operators and built-in functions. The built-in GMAT functions can be used to access internal data and perform predefined tasks.

The following sample script shows how math equations used in the script:

Create Spacecraft Sat;

Create Variable a b c d result;

Create Array A[3,3] B[3,3] C[1,1];

BeginMissionSequence

C(1,1) = A(1,1) + B(1,1);

Sat.X = Sat.X + 1000;

result = Sat.X/(1000/c/d) - 1.09056168*10^(-5);

result = sin(  abs(-.5 ) + acos(.5 ) -  asin(.5 ) * atan(.5 ) * atan2(.5,.5));

...

The following sample script shows how built-in GMAT functions can be used in the script: 

Create Spacecraft sat;

sat.EphemerisName = 'Code500_86400sec.eph';

Create String initialEpoch finalEpoch;

Create Array initialState[6,1] finalState[6,1]

BeginMissionSequence

[initialEpoch, initialState, finalEpoch, finalState] = GetEphemStates('Code500', sat, 'A1ModJulian', EarthMJ2000Eq);

See GMAT help document for more sample scripts. 

The following table briefly describes the difference between math node functions and built-in GMAT functions: 

As of November 8, 2016, there are 34 math functions (Abs, Acos, Acosh, Add, Asin, Asinh, Atan, Atan2, Ceil, Cos, Cosh, DegToRad, Determinant, Divide, Exp, Fix, Floor, Inverse, Log, Log10, Multiply, Negate, Norm, Power, RadToDeg, Rand, Randn, Sin, Sinh, Sqrt, Subtract, Tan, Tanh, Tranpose), 4 numeric functions (Cross3, Diag, Min, Mod), 5 string functions (Sprintf, Strcat, Strcmp, Strfind, Strrep), and 3 BuiltinGmatFunction (GetEphemState, GetLastState, SetSeed) are implemented in GMAT.

Procedure for adding a new math function

As the following class diagram shows, note that not all math functions are shown in the diagram, all math functions used in the arithmetic equation should be derived from the MathFunction class.

All math functions must operate on Real or Rmatrix values. There are math Math functions such as Sin()or Cos() require only one Real input and returning return one Real output and while other functions require two Real inputs such as Add() or Multiply(). If a new function needs only one Real input and output, it can be created by copying Sin() function. For step by step procedure,   Below is the procedure for creating a new Round() function will be created as an example. Round() function returns that returns the nearest integer value in Real, rounding away from zero in halfway cases.

1. Copy base/math/Sin.hpp and Sin.cpp to base/math/Round.hpp and Round.cpp.
2. Replace “Sin” to with “Round” in Round.hpp and Round.cpp files.
3. Update file prolog and method prologs.
4. In Round::Evaluate(), make sure it is calling GmatMathUtil::Round() with leftNode value.
5. In base/interpreter/MathParser.cpp, add “round” to realFuncList in MathParser::BuildAllFunctionList().
6. In base/factory/MathFactory.cpp, add “#include “Round.hpp” and add new math node type “Round” in MathFactory::CreateMathNode() to create an instance of Round. In MathFactory::BuildCreatables(), add “Round” to creatable list.
7. Add math/Round.cpp to base/CMakeList.txt.
8. Build GMAT.
9. Create a script to test Round() function in the script and run the test.

...

Procedure for adding a new string function

...