Skip to content
BranchesTags

Repository files navigation

GMAT Agent Skill

Natural language interface for GMAT (General Mission Analysis Tool) — describe space missions in plain English and get simulation results.

Language: 中文文档

Note: This project is in its early stages and under active development. If you encounter any issues, please open an issue or reach out directly. Contributions and pull requests are welcome.

Overview

GMAT Agent bridges the gap between natural language and GMAT's scripting language. You describe what you want — "propagate a LEO satellite for 3 days" — and the agent generates a valid GMAT script, executes it, and returns structured results.

User: "Design a Hohmann transfer from 300km LEO to GEO"
  → LLM generates .script file
  → python_runner.py executes via GMAT Python API
  → Returns: ΔV, final orbit parameters, report data

Requirements

Component Version Notes
GMAT R2020a or later Full installation (bin/, data/, plugins/)
Python 3.9+ Must match GMAT's Python version
GMAT Python API Built-in gmatpy module in GMAT bin/

Quick Start

1. Configure GMAT Path

Edit assets/default_config.yaml — change one line:

gmat_root: "C:\\YourPath\\gmat-win-R2026a"   # ← your GMAT installation

Or set the GMAT_ROOT environment variable (optional override).

2. Run a Test

python scripts/runner/python_runner.py \
  --script references/templates/simple_propagation.script \
  --objects Sat

Expected output:

{
  "success": true,
  "stage": "read",
  "objects": {
    "Sat": {
      "SMA": 7094.91,
      "ECC": 0.011,
      "INC": 44.94,
      "RMAG": 7027.32
    }
  }
}

3. Use in VS Code Chat

Type /gmat-agent followed by your mission description, e.g.:

/gmat-agent propagate a 500km circular orbit for 7 days, output position and velocity

The agent reads assets/system_prompt.txt (complete GMAT scripting reference), generates a valid .script file, executes it, and reports the results.

Configuration

All paths are consolidated in assets/default_config.yaml — the single configuration point:

# === GMAT Installation Path ===
# Change this to your GMAT root directory (contains bin/, data/, output/)
gmat_root: "e:\\GMAT\\GMATdev\\gmat-win-R2026a"

# Auto-derived from gmat_root (usually no need to change)
gmat_bin: "{gmat_root}\\bin"
output_dir: "{gmat_root}\\output"

Supports both absolute and relative paths. Relative paths resolve from the assets/ directory.

Path Resolution Order

  1. --gmat-root CLI argument (explicit override)
  2. GMAT_ROOT environment variable
  3. gmat_root in default_config.yaml

Usage

Python Runner CLI

# Minimal (reads config automatically)
python scripts/runner/python_runner.py --script mission.script

# Read specific objects after execution
python scripts/runner/python_runner.py --script mission.script --objects "Sat,Sat2"

# CSV / Markdown output (default: JSON)
python scripts/runner/python_runner.py --script mission.script --objects Sat --format csv
python scripts/runner/python_runner.py --script mission.script --objects Sat --format markdown

Output Format

Default JSON (also supports --format csv|markdown):

{
  "success": true,
  "stage": "read",
  "error": "",
  "objects": {
    "Sat": { "SMA": 7094.9, "ECC": 0.011, "INC": 44.9 }
  },
  "reports": {
    "columns": ["Sat.X", "Sat.Y", "Sat.Z"],
    "data": [[7100.0, 0.0, 1300.0], ...]
  }
}

Error stages: config → init → load → run → read.

Testing

Run smoke tests to verify core pipeline integrity:

python scripts/test/smoke_test.py            # all tests
python scripts/test/smoke_test.py --verbose  # detailed output

Covers: simple propagation, parameterized propagation, script validation, error diagnostics, OEM parsing.

GUI Compatibility

All scripts are standard GMAT .script files, fully compatible with GMAT.exe. Open and run for 3D visualization. For GUI-specific rules (OFI field limits, API/GUI separation, OpenFramesInterface setup), see SKILL.md and system_prompt.txt.

Python Runner — Full Features

python_runner.py now includes three additional capabilities:

Template Parameterization

Use {{KEY}} placeholders in scripts and override with --var / -D:

python scripts/runner/python_runner.py --script references/templates/parameterized_propagation.script \
  -D SMA=7200 -D INC=60 -D DURATION=7 --objects Sat

Script Validation

Pre-check script syntax via GmatConsole before execution:

# Validate only (no execution)
python scripts/runner/python_runner.py --script test.script --validate-only

# Validate then execute
python scripts/runner/python_runner.py --script test.script --validate --objects Sat

Error Diagnostics

When load_script() or run_mission() fails, python_runner.py automatically extracts line-level error messages from GmatLog.txt or falls back to GmatConsole for detailed diagnostics. Errors include exact line numbers and field names.

OEM Data Fetching

Automatically download the latest CSS orbital data from cmse.gov.cn:

# Full download (dedup by filename)
python scripts/fetch/fetch_oem.py

# Preview only (no download)
python scripts/fetch/fetch_oem.py --dry-run

# JSON output
python scripts/fetch/fetch_oem.py --json

Data is stored in data/oem/. Each run downloads new files and skips already-cached ones.

Parameter Scanning

Batch-scan orbital parameters and automatically summarize results:

# Single parameter: SMA 6600→7600 km, step 200
python scripts/analysis/parameter_scan.py -p SMA=6600:7600:200 --objects Sat

# Grid scan: SMA × Inclination
python scripts/analysis/parameter_scan.py -p SMA=6600:7600:1000 -p INC=0:90:45

# Output to CSV + trend plot
python scripts/analysis/parameter_scan.py -p SMA=6600:7600:200 --csv results.csv --plot trend.png

Outputs a terminal table with SMA, ECC, period, perigee/apogee. Supports --csv, --json-output, and --plot (requires matplotlib).

OEM Pipeline — CSS Orbit Analysis

Three tools for processing CCSDS OEM v2.0 files (e.g., China Space Station ephemeris):

Tool Purpose
oem_reader.py Parse OEM → Cartesian states → Keplerian elements (numpy, no GMAT API)
plot_altitude.py 3-panel altitude time series: Perigee/Apogee, SMA+trend, Eccentricity
maneuver_detector.py Dual-mode detection: impulsive (chemical) + continuous (Hall/EP) thrust via 10-bin trend analysis 
# Quick orbit summary
python oem_reader.py CSS_OEM.dat

# Altitude visualization
python plot_altitude.py CSS_OEM.dat -o altitude.png --step 4

# Maneuver detection (orbit-period smoothing to avoid J2 false positives)
# Maneuver detection (auto-threshold, dual-mode)
python maneuver_detector.py CSS_OEM.dat

# JSON output for programmatic use
python maneuver_detector.py CSS_OEM.dat --json

Launch Window Prediction

launch_window.py computes CSS overflight windows for launch sites (Shenzhou / Tianzhou missions):

  • Algorithm: Kepler + J2 back-propagation → EME2000→ECEF→elevation → pass detection
  • Direction filter: Only NW→SE descending passes accepted (range safety — China launches southeast toward open ocean)
  • Default threshold: 60° peak elevation
  • Sites: Jiuquan (40.96°N, 100.29°E) and Wenchang (19.32°N, 109.80°E)
# Shenzhou from Jiuquan
python launch_window.py CSS_OEM.dat -s Jiuquan --t0 "2026-05-24T23:08:36+08:00" -e 60

# Tianzhou from Wenchang (future prediction)
python launch_window.py CSS_OEM.dat -s Wenchang -e 60 -w 24

# JSON output for scripts
python launch_window.py CSS_OEM.dat -s Jiuquan --json

Verified: Shenzhou-23 (launched May 24, 2026 at 23:08 BJT) — the only valid window detected is a descending pass peaking at 79.1° elevation with AOS at 23:06 BJT, matching the actual T0 within 2 minutes.

Examples

Description Template
Simple orbit propagation (3 days) references/templates/simple_propagation.script
Parameterized propagation (CLI vars) references/templates/parameterized_propagation.script
Hohmann transfer targeting references/templates/impulsive_targeting.script
Continuous low-thrust references/templates/finite_burn.script
GmatFunction call (Hohmann) references/templates/gmat_function_hohmann.script
GmatFunction body references/templates/HohmannTarget.gmf

Example prompts for VS Code Chat:

  • "Simulate a LEO satellite at 500km altitude for 3 days"
  • "Design a Hohmann transfer from 300km to GEO, find the required ΔV"
  • "Scan SMA from 6600 to 7600 km and record orbital period"
  • "Model a continuous-thrust spiral from LEO to 10000km over 10 days"

File Structure

gmat-agent/
├── SKILL.md                    # Skill definition (VS Code)
├── README.md                   # This file (English)
├── README_CN.md                # Chinese documentation
├── gmat-triage.instructions.md # 5-layer decision tree
├── assets/                     # Declarative config + LLM prompts
│   ├── system_prompt.txt       # LLM system prompt (GMAT scripting reference)
│   └── default_config.yaml     # Single configuration point
├── scripts/                    # All executable Python tools
│   ├── fetch/
│   │   └── fetch_oem.py        # OEM data fetcher from cmse.gov.cn
│   ├── runner/
│   │   └── python_runner.py    # Core engine: load → execute → read results
│   │                           #   + --validate, --var, error diagnostics
│   ├── analysis/
│   │   ├── oem_reader.py       # OEM parser: CCSDS OEM v2.0 → Cartesian → Keplerian
│   │   ├── plot_altitude.py    # Altitude plotter: perigee/apogee time series
│   │   ├── maneuver_detector.py # Maneuver detector: 10-bin trend, dual-mode (impulsive + continuous)
│   │   └── parameter_scan.py   # Parameter scanner: batch propagation + summary table/plot
│   └── prediction/
│       └── launch_window.py    # Launch window calculator for CSS missions
├── data/
│   └── oem/                    # Downloaded OEM data (auto-populated by fetch_oem.py)
└── references/                 # Read-only reference material
    ├── templates/
    │   ├── simple_propagation.script
    │   ├── parameterized_propagation.script  # {{KEY}} template vars with defaults
    │   ├── impulsive_targeting.script
    │   └── finite_burn.script
    └── samples/                # 19 curated official GMAT examples + INDEX.md

Verified Scripting Rules

These were discovered through live testing against GMAT's Python API and GmatConsole:

  1. All assignment lines end with semicolons — including ReportFile. RF.Filename = 'out.txt'; correct, without ; causes parse errors
  2. ... is the line continuation marker inside {} blocks
  3. ReportFile auto-writes at mission end — no explicit Report RF; needed
  4. RF.Add only accepts Cartesian parameters (Sat.EarthMJ2000Eq.X), not Keplerian (Sat.Earth.SMA)
  5. The Moon is named Luna in the Python API
  6. DifferentialCorrector field: MaximumIterations not MaxIterations
  7. ChemicalThruster.C1 is thrust coefficient (N), not Isp. GravitationalAccel is in SI units (m/s²): use 9.81 not 0.00981
  8. ChemicalTank.PressureModel = PressureRegulated; (not PressureRegulated = true)
  9. MixRatio array size must match tank count: [1] for one tank
  10. Target/Vary/Achieve syntax: Vary 'desc' DC(var=val, {opts}) — DC goes outside the quotes

Troubleshooting

Problem Solution
stage: "config" error Check gmat_root in default_config.yaml
stage: "init" error Verify GMAT bin/ contains gmatpy.pyd. Run BuildApiStartupFile.py first if needed.
stage: "load" error Script syntax error. Check the error message for specifics. Common: semicolons after ReportFile lines, wrong parameter names in RF.Add.
stage: "run" error Physics or configuration issue. Check: are point masses correct? Is DateFormat set before Epoch?
Orbit diverges (hyperbolic) Remove PointMasses, use Earth-only gravity for MVP.
ModuleNotFoundError: gmatpy Add GMAT bin/ to PYTHONPATH or run from a directory where sys.path can reach it.

Limitations

  • MVP scope: Propagation + Maneuvers + Targeting. No Orbit Determination.
  • Automated execution uses Python API only: The agent runs scripts via python_runner.py — no GMAT.exe or GmatConsole.exe direct execution during automated workflows. However, all generated .script files are standard GMAT format and can be opened in the GUI for 3D visualization.
  • Complex task workflow: For non-trivial tasks, the agent iterates and validates via Python API first, then provides a GUI-ready version with OpenFramesInterface for user visualization.
  • No automatic iteration loop: The LLM generates one script at a time. Multi-turn refinement is manual.
  • ReportFile parameters: Only Cartesian frame parameters in RF.Add. Keplerian elements must be read via GetRuntimeObject().GetNumber().
  • Third-body gravity: Point masses (Sun, Moon) may cause issues in API mode.
  • Template parameterization: parameterized_propagation.script supports {{KEY}} placeholders with built-in defaults (edit the %% Defaults: comment line to change). Omitted variables auto-fill from defaults — safe to override only the ones you need (e.g. -D SMA=7200). Other templates (simple_propagation.script, impulsive_targeting.script, finite_burn.script) have hardcoded values and don't support -D.

License

This Skill is provided as-is under the same terms as GMAT (Apache 2.0).

About

GMAT Agent — Natural language interface for GMAT space mission simulation. Describe missions in plain English/Chinese and get simulation results.

Topics

gmat

Resources

Readme
Apache-2.0 license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages