Skip to content

Tutorial: Scenario + Mission Workflows

This tutorial walks through the scenario-driven mission workflows demonstrated in examples/scenario_missions.py.

It is the best starting point for learning how ASTRODYN-CORE connects:

  • state files (initial_state, scenario, trajectory)
  • propagation builders
  • mission intent compilation
  • detector-driven maneuver execution

Learning goals

By the end of this tutorial, you should be able to:

  • load and inspect scenario/state files
  • enrich scenario metadata and save a modified scenario
  • run an intent-based mission profile export
  • run detector-driven mission execution and inspect the execution report
  • understand which artifacts are generated by each workflow mode

Source script (executable truth)

  • examples/scenario_missions.py

Run the full script:

conda run -n astrodyn-core-env python examples/scenario_missions.py --mode all

The script supports these modes:

  • io
  • inspect
  • intent
  • detector
  • all (runs all workflows in sequence)

Before you run it

Prerequisites:

  • project installed in astrodyn-core-env
  • Orekit available in that environment
  • run from the repo root (the example uses relative paths under examples/)

See:

Mental model (what this example is really teaching)

examples/scenario_missions.py is a guided tour of the mission stack:

  1. State I/O layer (app.state)
  2. Propagation layer (app.propagation)
  3. Mission layer (app.mission)

Instead of manually building every object from scratch, the example shows how a scenario file can become the source of truth for mission execution workflows.

Mode 1: io (state-file I/O + trajectory export + interpolation checks)

Run:

conda run -n astrodyn-core-env python examples/scenario_missions.py --mode io

What happens:

  1. Builds a simple Keplerian propagator from a demo LEO orbit
  2. Saves an initial state YAML file
  3. Exports a sampled trajectory to both YAML and HDF5
  4. Reloads both outputs
  5. Converts them to ephemeris objects
  6. Compares off-grid interpolation against the original propagator

Why this is valuable:

  • it demonstrates the state-file format lifecycle (write -> read -> reuse)
  • it shows that exported trajectories can be used as ephemerides
  • it gives you a concrete interpolation accuracy check

Generated artifacts (under examples/generated/):

  • workflow_initial_state.yaml
  • workflow_cartesian_series.yaml
  • workflow_cartesian_series.h5

Mode 2: inspect (load a mission scenario and enrich metadata)

Run:

conda run -n astrodyn-core-env python examples/scenario_missions.py --mode inspect

Source scenario:

  • examples/state_files/leo_mission_timeline.yaml

What the script does:

  • loads the scenario file
  • prints mission metadata, maneuver count, and attitude timeline entries
  • builds a simple Keplerian propagator for previewing epoch-triggered maneuvers
  • evaluates maneuver trigger epochs and prints radius/attitude context
  • writes an enriched copy of the scenario with derived metadata fields

Generated artifact:

  • examples/generated/scenario_enriched.yaml

This mode is a good pattern for:

  • validating incoming mission files
  • adding derived metadata before running a full mission simulation

Mode 3: intent (compile mission intents and export a mission trajectory)

Run:

conda run -n astrodyn-core-env python examples/scenario_missions.py --mode intent

Source scenario:

  • examples/state_files/leo_intent_mission.yaml

What the script does:

  • loads a scenario containing maneuver intents
  • builds a numerical propagator from the scenario initial state
  • defines a 3-hour output epoch grid
  • runs app.mission.export_trajectory_from_scenario(...)
  • saves a trajectory state series
  • plots orbital elements
  • prints the compiled maneuvers and their inertial delta-v magnitudes

Generated artifacts:

  • examples/generated/mission_profile_series.yaml
  • examples/generated/mission_profile_elements.png

This mode is the clearest example of the "declarative scenario -> compiled maneuvers -> exported trajectory" workflow.

Mode 4: detector (closed-loop event-detector execution)

Run:

conda run -n astrodyn-core-env python examples/scenario_missions.py --mode detector

Source scenario:

  • examples/state_files/leo_detector_mission.yaml

What the script does:

  • loads a detector-driven scenario
  • builds a numerical propagator
  • defines a 12-hour output epoch grid
  • runs app.mission.run_scenario_detector_mode(...)
  • inspects the returned execution report (events, applied, skipped, total delta-v)
  • saves trajectory output and an orbital-elements plot

Generated artifacts:

  • examples/generated/detector_mission_trajectory.yaml
  • examples/generated/detector_mission_elements.png

Why this mode matters:

  • it demonstrates mission logic that depends on runtime conditions, not just fixed epoch triggers
  • it produces an execution report you can use for analysis and validation

Suggested learning order

Use this sequence instead of --mode all when learning:

  1. inspect
  2. io
  3. intent
  4. detector

Why:

  • inspect teaches the scenario schema conceptually
  • io builds confidence in state-file and trajectory workflows
  • intent introduces mission compilation and replay
  • detector adds the most operational complexity last