gmat-run

Run GMAT mission scripts from Python and get results as pandas DataFrames.

What this is

gmat-run drives NASA's General Mission Analysis Tool (GMAT) from Python. You bring a working .script; gmat-run discovers your GMAT install, loads the mission, lets you override fields from Python with type coercion, runs it headlessly, and parses GMAT's ReportFile, ephemeris, ContactLocator, and solver-log output into typed pandas DataFrames.

What this is not

• Not a way to build GMAT missions from scratch in Python — see gmatpyplus for that.
• Not a .script text generator — see pygmat.
• Not a parallel sweep runner — see gmat-sweep, an astro-tools project built on top.

Requirements

• Python 3.10, 3.11, or 3.12.
• A local GMAT install. gmat-run does not ship GMAT binaries — install GMAT separately from gmat.gsfc.nasa.gov.

Supported GMAT versions

Report any version-specific breakage as an issue and we'll add a CI cell for it.

Installation

pip install gmat-run

Optional extras unlock format- and feature-specific code paths. Each is named after the dependency it pulls in:

Install one or more at once:

pip install gmat-run[spiceypy]
pip install gmat-run[astropy,ccsds-ndm]

Quick start

Load a script, override a field, run the mission, and read each output GMAT wrote as a pandas DataFrame:

from gmat_run import Mission

mission = Mission.load("flyby.script")
mission["Sat.SMA"] = 7000
result = mission.run()

# ReportFile → DataFrame, with UTCGregorian / *ModJulian epoch columns
# promoted to datetime64[ns].
result.reports["ReportFile1"].plot(x="UTCGregorian", y="Sat.Earth.Altitude")

# EphemerisFile → DataFrame, dispatching on file format.
ephem = result.ephemerides["EphemerisFile1"]

# ContactLocator → DataFrame; df.attrs["report_format"] carries the variant.
contacts = result.contacts["ContactLocator1"]

# Solver → DataFrame per Target/Optimize run: iteration history, residuals,
# and a convergence flag. result.converged["DC"] is the quick yes/no.
iterations = result.solver_runs["DC"]

Mission.load discovers a local GMAT install (honouring the GMAT_ROOT environment variable or a gmat_root= argument), bootstraps gmatpy, and parses the script into the live GMAT object graph. Subscript access reads and writes fields against that graph with type coercion:

mission.run() executes the mission sequence headlessly, captures GMAT's log, and returns a Results exposing four lazy mappings — reports, ephemerides, contacts, and solver_runs — each keyed by the GMAT resource name and parsing to a DataFrame on first access. See Outputs below for the formats covered.

A gmat-run console script is also installed for shell-script and smoke-test use:

gmat-run run flyby.script --out results/

See the CLI reference for flags, exit codes, and sample output.

Outputs

Results exposes four mappings, each keyed by the GMAT resource name as declared in the .script:

• ReportFile → DataFrame, with UTCGregorian and *ModJulian epoch columns promoted to datetime64[ns].
• EphemerisFile → DataFrame, dispatching on file format: CCSDS-OEM and STK-TimePosVel are read out of the box; SPK (NASA SPICE binary) is read with the [spiceypy] extra installed. Code-500 (GSFC binary) is not implemented — see Known limitations.
• ContactLocator → DataFrame, supporting Legacy and the five tabular ReportFormat variants. df.attrs["report_format"] carries the variant name so downstream code can branch on it without inspecting the column set.
• Solver → one DataFrame per Target / Optimize run, parsed from the iteration log GMAT writes for each Solver. One row per iteration, with a column per Vary variable, the goal/constraint residuals, and a status column; df.attrs["converged"] and the Results.converged shortcut answer the yes/no. DifferentialCorrector and Yukon are covered.

Each mapping has a sibling path accessor — report_paths, ephemeris_paths, contact_paths, and solver_paths — mapping each resource name to the file GMAT wrote, so you can locate an output without parsing it.

Documentation

Full docs at https://astro-tools.github.io/gmat-run/, including a getting-started guide, GMAT install instructions, a Run gmat-run in your CI cookbook page, the CLI reference, and the API reference.

Runnable example notebooks:

• Load / run / plot — load a stock GMAT sample, run it, and plot altitude over time end-to-end.
• Parameter sweep — vary Sat.SMA across a range, run the same script for each, and overlay the resulting orbits.
• Ground track — read an EphemerisFile from Results.ephemerides and plot the spacecraft's ground track on an equirectangular world map.
• Export to CCSDS-OEM — run a stock GMAT sample that emits an STK ephemeris, convert it to a CCSDS-OEM file with Results.write_oem, re-parse the result, and visualise the trajectory in 3D.
• Time-scale conversion — propagate across the 2017-01-01 leap-second boundary and convert the resulting ReportFile's epoch columns between A1, TAI, UTC, TT, and TDB with gmat_run.time and the parser-level convert_to= keyword.
• Solver iterations — target a Hohmann transfer with a DifferentialCorrector and read the iteration history back from Results.solver_runs: the Vary variables, the Achieve goal residuals, and a convergence flag.

Development

To work on gmat-run itself:

git clone https://github.com/astro-tools/gmat-run.git
cd gmat-run
uv sync --all-groups

See CONTRIBUTING.md for the full branch / PR / test workflow.

Licence

MIT. See LICENSE.