Skip to content

Install discovery

Locate and validate a local GMAT install. The single public entry point is locate_gmat; it returns a GmatInstall describing the resolved install or raises GmatNotFoundError listing every location it checked.

Mission.load calls locate_gmat for you — reach for the function directly only when you need the resolved paths before loading a script (e.g. to print the version), or when you want to drive bootstrap yourself. See Getting started → Quick start for the typical flow, and Install GMAT for where the discovery looks on each platform.

locate_gmat 

locate_gmat(
    gmat_root: str | PathLike[str] | None = None,
) -> GmatInstall

Find a usable GMAT install on the local machine.

Search order:

  1. The gmat_root argument, if provided.
  2. The GMAT_ROOT environment variable, if set.
  3. Platform-standard install locations (Windows Program Files, Linux ~/gmat-* and /opt/gmat-*, macOS /Applications).
  4. The PATH, by locating known GMAT executables.

The first valid candidate wins. An explicit override (argument or environment variable) does not fall through to later steps if its candidate is invalid — user-specified locations fail loudly.

When multiple platform-glob candidates exist, the lexically greatest basename wins (e.g. gmat-R2026a beats gmat-R2024a).

Raises:

Type Description
GmatNotFoundError

No valid GMAT install was found in any search location.

GmatInstall dataclass 

GmatInstall(
    root: Path,
    bin_dir: Path,
    api_dir: Path,
    output_dir: Path,
    version: str | None,
)

A resolved GMAT install on the local filesystem.