# 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:

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

- [Install](../getting-started/install.md)
- [Orekit Data](../getting-started/orekit-data.md)
- [Run Examples](../getting-started/examples.md)
- [Common Setup Issues](../troubleshooting/common-setup-issues.md)

## 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:

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

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

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

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

## Related docs

- [Propagation Quickstart](propagation-quickstart.md)
- [How-To / Cookbook](../how-to/index.md)
- [API: `astrodyn_core`](../reference/api/astrodyn_core.md)
- [API: `astrodyn_core.propagation`](../reference/api/propagation.md)
