Script Language

Initialization

The first section in a script file, referred to as Initialization, is responsible for creating resources and setting their initial state. The Initialization section can contain the following types of statements:

Only literal assignments are allowed in this section; no execution of commands or evaluation of parameters is done. In the GUI, the Initialization section maps directly to the Resources tree. All resources created, and all fields set, in this section appear as resources in the GUI when the script is loaded.

Mission Sequence

The Mission Sequence section contains the Mission Sequence, or the list of GMAT commands that are executed sequentially when the mission is run. The Mission Sequence section can contain the following types of statements:

The Mission Sequence begins at the first instance of the BeginMissionSequence command; therefore, this must be the first command statement in the script file. For backwards compatibility, if the BeginMissionSequence command is missing, the Mission Sequence begins with the first command encountered.

In the GUI, the Mission Sequence section maps directly to the Mission tree. Each statement in the script (with the exception of the BeginScript/EndScript compound command) is displayed as a single element in the tree.

Source Text

A GMAT script consists of a single file containing characters from the 7-bit US-ASCII character set. The script language is case-sensitive, so this line creates four different Variable resources:

Create Variable x X y Y

The script language is made up of lines. A line can be:

Statement lines can be split over multiple physical lines with the continuation marker (“...”).

Line Termination

Script lines are terminated by any of the following ASCII character sequences:

White Space

White space can appear above or below any line, before or after any statement within a line, and many other places in a script. The following characters are recognized as white space:

Horizontal tab characters are preserved in string literals, but are replaced by spaces in some other contexts (e.g. equations, comments).

Comments

Comments begin with the percent symbol (“%”, hex: 25) and extend to the end of the line. There is no multi-line or embedded comment in the script language.

File Paths

Several resource types have fields that accept file paths as input. The general syntax of such paths is common to the language, but some specific behavior is specified by each resource.

Forward slashes and backslashes can be used interchangeably within GMAT, and can be mixed in a single path. The following three paths are considered identical:

          data/planetary_ephem/spk/de421.bsp
data\planetary_ephem\spk\de421.bsp
data\planetary_ephem/spk\de421.bsp
        

Absolute paths are passed to the underlying operating system as-is, aside from normalizing the slashes.

For input files, relative paths are first considered relative to the script file, then to a location defined by each resource type separately, and usually defined in the GMAT startup file. For details, see the reference documentation for each resource type.

For output files, relative paths are considered relative to the script file. If only a filename is specified, the file is placed into the output location defined in the GMAT startup file (usually GMAT's output folder).

File paths are written as string literals (see Strings under Data Types). Quotes are mandatory if the path contains spaces, but are optional otherwise.

Literals

Resources

            Create Spacecraft Spacecraft
Create Spacecraft aSat
          

Compound Types

            anOrbitView.DrawObject = [true true]             % boolean array
aSat.OrbitColor = [255 0 0]                      % integer array
anOrbitView.ViewPointVector = [3e4, 1.2, -14]    % real array
aSpacecraft.OrbitSpiceKernelName = ...
    {'file1.bsp', 'file2.bsp'}                   % string array
          

            aForceModel.PointMasses = {'Luna', Mars}  % array of resource references
aReport.Add = {Sat1.X, 'Sat1.Y', Sat1.Z}  % array of parameter references
          

Relational Operators

The following relational operators are supported in logical expressions:

The relational operators are scalar operators; they do not operate on Array resources (only individual elements).

Each relational operator operates on the values of its arguments, not on their identity. Consider the example:

Create Variable x y
x = 5
y = 5

BeginMissionSequence

If x == y
    % body
EndIf 

Logical Operators

The following logical operators are supported in logical expressions:

The logical AND operator exhibits short-circuit behavior. That is, if the left-hand side of the operator evaluates to false, the right-hand side is not evaluated, though it is still parsed for syntactic validity.

Logical Expressions

Logical expressions are composed of relational expressions combined with logical operators.

Relational expressions must contain one relational operator and two valid arguments. Literal boolean values are not supported, and numeric values are not interpreted as truth or falsehood. See the following examples:

          1 == 5          % false
1 ~= 5          % true
true            % error
1               % error
A               % where "A" is an Array resource; error
1 == 5 <= 3     % error
        

Logical expressions must contain at least one relational expression. Multiple relational expressions are combined using logical operators. All relational expressions are evaluated first, from left to right, then the full logical expression is evaluated from left to right, though the short-circuit AND operator (“&”) may terminate the full evaluation. Parentheses are not allowed. See the following examples:

1 == 1                   % true
2 ~= 4 | 3 == 3          % true
8 >= 3 & 3 < 4           % true
2 < 4 & 1 > 3 | 5 == 5   % true
2 < 4 & (1 > 3 | 5 == 5) % error
1 & 1                    % error
true | false             % error      

Statement Structure

Script statements consist of (in order):

Any statement in the script may be prefixed by the characters “GMAT “. This prefix is optional and has no effect, but is supported for backward compatibility.

A statement can be split over multiple physical lines by using the line continuation marker, three sequential period characters (“...”, hex: 2E2E2E), before each line break within the statement.

Any statement may be terminated with a semicolon character (“;”, hex: 3B). The semicolon is optional and has no effect, but is supported for backward compatibility. Multiple statements cannot be combined on a line.

White space may occur before or after a statement, or between any of the components listed above. It is also generally allowed anywhere inside of a statement, and any exceptions are noted in the documentation specific to that statement.

The Create Statement

The Create statement is a special statement that creates resources and assigns them names. It is only valid in the Initialization section of the script. It has the following components:

The Create keyword indicates the start of the statement. It is followed by the resource type, which indicates the type of resource to create. This is followed by a resource name, a user-defined name that is then used to refer to that particular resource. This name must follow the resource naming rules, listed previously.

The only exception to this syntax is when creating an Array resource, in which case the dimension of the resource must also be specified

Multiple resource names are allowed, in which case multiple resources of the same type will be created. Multiple names are separated by white space or by commas (“,”, hex: 2C).

See the following examples:

          Create Spacecraft aSat  % creates a resource "aSat" of type Spacecraft
Create ForceModel aFM
Create Propagator aProp
Create Variable x y     % creates two Variable resources: "x" and "y"
Create String s1, s2    % creates two String resources: "s1" and "s2"
Create Array A[2,2]     % creates a 2x2 Array resource named "A"
        

Initialization Statements

Initialization statements are special statements that assign initial values to resource fields. They are only valid in the Initialization section of the script, and generally take the following form:

resource.field = value

ForceModel.GravityField.PrimaryBody.Degree = value

          Create Spacecraft aSat
Create XYPlot aPlot
Create Variable x y z

x = 7100                   % valid
aSat.X = 7100              % valid
aSat.X = 7100 + 2          % error (mathematical expression)

aSat.X = x                 % error (field accepts literal, and variable
                           % evaluation does not occur)
aPlot.XVariable = x        % valid (field accepts reference to Variable x)
aPlot.YVariables = {y, z}  % valid (field accepts array of references to
                           % Variables y and z)
        

Create Spacecraft aSat1 aSat2
aSat2 = aSat1                   % Valid only for Spacecraft resources