Metadata-Version: 2.4
Name: gmat-run
Version: 0.6.0
Summary: Run GMAT mission scripts from Python and get results as pandas DataFrames.
Project-URL: Homepage, https://github.com/astro-tools/gmat-run
Project-URL: Repository, https://github.com/astro-tools/gmat-run
Project-URL: Issues, https://github.com/astro-tools/gmat-run/issues
Author: Dimitrije Jankovic
License-Expression: MIT
License-File: LICENSE
Keywords: astrodynamics,gmat,mission-analysis,orbital-mechanics,space
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: astropy
Requires-Dist: astropy>=6.0; extra == 'astropy'
Provides-Extra: ccsds-ndm
Requires-Dist: ccsds-ndm>=3.0; extra == 'ccsds-ndm'
Provides-Extra: examples
Requires-Dist: matplotlib>=3.8; extra == 'examples'
Provides-Extra: spiceypy
Requires-Dist: spiceypy>=6.0; extra == 'spiceypy'
Description-Content-Type: text/markdown

# gmat-run

[![CI](https://github.com/astro-tools/gmat-run/actions/workflows/ci.yml/badge.svg)](https://github.com/astro-tools/gmat-run/actions/workflows/ci.yml)
[![Docs](https://github.com/astro-tools/gmat-run/actions/workflows/docs.yml/badge.svg)](https://astro-tools.github.io/gmat-run/)
[![PyPI](https://img.shields.io/pypi/v/gmat-run.svg)](https://pypi.org/project/gmat-run/)
[![Python versions](https://img.shields.io/pypi/pyversions/gmat-run.svg)](https://pypi.org/project/gmat-run/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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`](https://github.com/weasdown/gmatpyplus) for that.
- **Not** a `.script` text generator — see [`pygmat`](https://pypi.org/project/pygmat/).
- **Not** a parallel sweep runner — see [`gmat-sweep`](https://github.com/astro-tools/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](https://gmat.gsfc.nasa.gov/).

### Supported GMAT versions

| GMAT release | Status | CI |
|---|---|---|
| R2026a | Primary development target | Exercised on every PR (Ubuntu + Windows + macOS, Python 3.10/3.11/3.12) |
| R2025a | Supported | Exercised on every PR (Ubuntu + Windows + macOS, Python 3.10/3.11/3.12) |
| R2022a | Expected to work | Not exercised in CI (Python 3.9 ABI floor; see [known limitations](https://astro-tools.github.io/gmat-run/known-limitations/)) |

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

## Installation

```bash
pip install gmat-run
```

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

| Extra | Pulls in | Unlocks |
|---|---|---|
| `[spiceypy]` | `spiceypy` | SPK (NASA SPICE binary) ephemeris parsing. |
| `[ccsds-ndm]` | `ccsds-ndm` | CCSDS-OEM export via `Results.write_oem`. |
| `[astropy]` | `astropy` | Leap-second-correct time-scale conversion via `gmat_run.time`. |

Install one or more at once:

```bash
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:

```python
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:

| Pattern | Example |
|---------|---------|
| `Resource.Field` | `mission["Sat.SMA"] = 7000` |
| `Resource.SubResource.Field` | `mission["FM.Drag.CSSISpaceWeatherFile"] = "/path/CSSI.txt"` |
| `Variable.Value` | `mission["elapsed_seconds.Value"] = 86400.0` |

`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](#outputs) below for the formats covered.

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

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

See the [CLI reference](https://astro-tools.github.io/gmat-run/cli/) 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](https://astro-tools.github.io/gmat-run/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](https://astro-tools.github.io/gmat-run/getting-started/),
[GMAT install instructions](https://astro-tools.github.io/gmat-run/install-gmat/),
a [Run gmat-run in your CI](https://astro-tools.github.io/gmat-run/ci-with-setup-gmat/)
cookbook page,
the [CLI reference](https://astro-tools.github.io/gmat-run/cli/),
and the [API reference](https://astro-tools.github.io/gmat-run/reference/).

Runnable example notebooks:

- [Load / run / plot](https://astro-tools.github.io/gmat-run/examples/01_load_run_plot/) —
  load a stock GMAT sample, run it, and plot altitude over time end-to-end.
- [Parameter sweep](https://astro-tools.github.io/gmat-run/examples/02_parameter_sweep/) —
  vary `Sat.SMA` across a range, run the same script for each, and overlay the resulting
  orbits.
- [Ground track](https://astro-tools.github.io/gmat-run/examples/03_ground_track/) — read an
  `EphemerisFile` from `Results.ephemerides` and plot the spacecraft's ground track on an
  equirectangular world map.
- [Export to CCSDS-OEM](https://astro-tools.github.io/gmat-run/examples/04_export_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](https://astro-tools.github.io/gmat-run/examples/05_time_scales/) —
  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](https://astro-tools.github.io/gmat-run/examples/06_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:

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full branch / PR / test workflow.

## Licence

MIT. See [LICENSE](LICENSE).
