Mission

Mission is the main entry point. Construct one via Mission.load, which discovers a local GMAT install, bootstraps gmatpy, and parses a .script into the live GMAT object graph. Field access uses dotted-path keys against that graph (mission["Sat.SMA"]); Mission.run executes the mission sequence headlessly and returns a Results.

See Getting started → Quick start for the full load → override → run → plot flow.

Mission

Mission(
    *,
    gmat: ModuleType,
    install: GmatInstall,
    script_path: Path,
)

A loaded GMAT .script with dotted-path field access.

Construct via :meth:load. Reads return Python-typed values; writes coerce to the GMAT-expected type and reject the rest with :class:~gmat_run.errors.GmatFieldError.

attitude_input_paths property

attitude_input_paths: Mapping[str, Path]

Resolved paths of every CCSDS-AEM file consumed by the loaded script.

Walks every Spacecraft resource on first access; selects those with Attitude == "CCSDS-AEM"; reads AttitudeFileName and resolves relative paths against :attr:script_path's parent directory (the same convention GMAT itself uses, since LoadScript is invoked with the script's full path). Absolute paths are kept as-is.

The returned mapping is keyed by Spacecraft resource name and is a read-only view. Discovery is cached for the life of the Mission.

Returns an empty mapping when no Spacecraft uses CCSDS-AEM, when the gmat module does not expose a SPACECRAFT enum, or when the registry walk raises (defensive: an obscure plugin failure should not block the rest of the Mission's surface).

attitude_inputs property

attitude_inputs: Mapping[str, DataFrame]

Parsed CCSDS-AEM attitude files consumed by the loaded script.

Lazy: each entry is parsed on first __getitem__ via :func:gmat_run.parsers.aem_ephemeris.parse, then cached. Iterating the mapping or calling len is free — only access materialises a DataFrame.

Keyed by Spacecraft resource name. Use :attr:attitude_input_paths to recover the raw path without parsing.

gmat property

gmat: ModuleType

The bootstrapped gmatpy module.

Escape hatch for callers that need raw SWIG access. Not part of the stable public surface — the documented contract is the dotted-path __getitem__ / __setitem__ interface.

load classmethod

load(
    path: str | PathLike[str],
    *,
    gmat_root: str | PathLike[str] | None = None,
) -> Mission

Load a GMAT .script and return a :class:Mission handle.

Discovers GMAT via :func:~gmat_run.install.locate_gmat (honouring gmat_root / GMAT_ROOT), bootstraps gmatpy via :func:~gmat_run.runtime.bootstrap, and parses the script via gmat.LoadScript.

path is resolved against the caller's CWD at submit time (~ is expanded, relative paths become absolute). The resolved value is exposed via :attr:script_path.

Raises:

Type	Description
GmatNotFoundError	No usable GMAT install was found.
GmatLoadError	gmatpy could not be loaded, or LoadScript returned False (parse error — check the GMAT log file).

summary

summary() -> MissionSummary

Return a structured snapshot of this loaded mission.

See :class:~gmat_run.summary.MissionSummary for the schema. Walks the gmat object graph each call — there is no cache, so a Mission whose fields were edited via __setitem__ and re-summarised reflects the latest state. The walk only enumerates resources by name and the command graph one level deep; it does not materialise field values (use mission["Sat.SMA"] for that).

run

run(
    *,
    working_dir: str | PathLike[str] | None = None,
    overwrite: bool = False,
) -> Results

Execute the loaded mission sequence and return a :class:Results.

Redirects every relative ReportFile, EphemerisFile, and ContactLocator output and the GMAT log into working_dir (or an isolated temp directory when None), runs gmat.RunScript(), and builds a :class:Results populated with the resolved output paths and the captured log.

Filename rewrite. A relative Filename on an output subscriber is rewritten to an absolute path inside working_dir before the run, so a stock script's outputs land in the per-run workspace instead of the GMAT install's default output directory (the charter's "no pollution of the user's cwd" rule). Absolute filenames in the script are left alone — the user has a specific destination in mind and the run honours it. The rewrite is the only mechanism GMAT actually consults at write time; FileManager.OUTPUT_PATH is cached per-subscriber at Initialize time and ignored thereafter. The rewrite is reverted once the run is over — reading mission["RF.Filename"] afterwards yields the script's declared value again, not the workspace path. Mission stays a view of the loaded script (as with :attr:attitude_inputs); the resolved output locations live on the returned :class:Results. Each :meth:run therefore redirects independently of any earlier run on the same Mission.

Solver logs. Every Target / Optimize run writes a per-Solver .data iteration log. Its <Solver>.ReportFile field is rewritten into working_dir by the same mechanism, so the log is surfaced through :attr:Results.solver_runs and shares the workspace's lifetime. A Solver resource that no Target / Optimize block exercises writes nothing and is simply absent from the mapping.

Working directory (when working_dir is set explicitly):

• The directory is created if missing; if creation or any write into it fails, :class:~gmat_run.errors.GmatRunError is raised before RunScript is invoked, with GmatRunError.path set to the offending directory.
• If working_dir resolves to the same directory as :attr:script_path's parent, a :class:UserWarning is emitted — GMAT outputs in that case may overwrite the user's source files.
• Pre-existing files inside working_dir whose names match the run's resolved output paths are detected before RunScript. Default policy: raise :class:~gmat_run.errors.GmatRunError and skip the run, so the prior run's artefacts are not silently mixed with the new run's. Pass overwrite=True to unlink the colliding files and proceed. The gate is scoped to files inside working_dir only — absolute filenames pinned outside (see below) are the user's destination and are never touched.
• After a successful run, any output that landed outside working_dir (because the script declared an absolute Filename) is summarised as a one-line [gmat-run] note: … notice prepended to :attr:Results.log.

Parameters:

Name	Type	Description	Default
working_dir	str | PathLike[str] | None	Directory GMAT writes its outputs into. ~ is expanded and relative paths are resolved against the caller's CWD at submit time, so the stored :attr:Results.output_dir is always absolute regardless of what the caller passed in. None creates a fresh :class:tempfile.TemporaryDirectory whose lifetime is tied to the returned :class:Results — the directory survives until the caller drops the result, so lazy report parsing keeps working without a context manager. Call :meth:Results.persist before that to copy the artefacts to a permanent location.	None
overwrite	bool	When True, unlink any pre-existing files in working_dir that collide with the run's resolved output paths before invoking RunScript. When False (the default), a collision raises :class:~gmat_run.errors.GmatRunError. Ignored when working_dir is None (a fresh temp directory cannot contain colliding artefacts).	False

Raises:

Type	Description
GmatRunError	RunScript returned a non-success status, raised a GMAT engine exception, or a pre-run gate failed (working_dir not creatable, not writable, or contained colliding output files with overwrite=False). The captured log is attached via GmatRunError.log (empty for pre-run gate failures); the offending directory or file is attached via GmatRunError.path.