# Propagation Call Chain Analysis

## Session Date
2026-04-20

## Objective
Audit all call sites of `propagate_orbital_elements()` for spacecraft and trace the `update_simulation()` call chain through `execute_pending_maneuvers()` and `update_spacecraft_physics()` to identify inefficiencies and confusing branching.

## Recent Changes

### 2026-04-20: Eliminated Redundant Propagation in `check_maneuver_trigger()`

Replaced the per-frame propagation probe in `check_maneuver_trigger()` (true-anomaly branch) with a direct analytical calculation using mean anomaly delta.

**What changed:**
- Removed `propagate_orbital_elements()` call from `check_maneuver_trigger()` — eliminates ~24k redundant Kepler solves per Hohmann transfer wait period
- Removed dead `angle_between()` static helper
- Replaced the `angle_between`, `future_diff`, and `wraparound_crossing` checks with a cleaner `dt_needed <= 0.0` guard
- Added TODO comment noting elliptical-orbits-only limitation

**Impact:**
- Same correctness, fewer function calls, simpler logic
- All 154 tests pass (240,445 assertions)
- For a Hohmann transfer with ~244,000s wait time and DT=10s: ~24,400 fewer `propagate_orbital_elements()` calls

**Remaining:** See Issue 1 below — still has a TODO for parabolic/hyperbolic orbit support.

### 2026-04-20: Merged Maneuver Execution into Single Propagation Pass

Consolidated `execute_pending_maneuvers()` into `update_spacecraft_physics()` so every spacecraft goes through exactly one propagation path.

**What changed:**
- Removed `spacecraft_handled_this_frame[256]` static array (magic number)
- Removed `reset_spacecraft_tracking()` function
- Removed `execute_pending_maneuvers()` function
- Check maneuver triggers before propagation in `update_spacecraft_physics`
- Propagate to burn time, execute burn, propagate remainder (same order as old code)
- Removed `execute_pending_maneuvers` declaration from `simulation.h`

**Impact:**
- Single propagation call per spacecraft per frame (was 2 separate code paths)
- No static array with hardcoded size
- Simpler call chain: no separate maneuver pass
- Enables sub-step interpolation for true-anomaly triggers
- Sets up foundation for interpolated time triggers

**Remaining:** Adds TODO in `update_spacecraft_physics` about testing interpolated burns.

---

## Call Chain: `update_simulation()` (Current)

```
update_simulation()
│
├── update_bodies_physics()
│   └── for each body:
│       ├── find_dominant_body()
│       ├── orbital_elements_to_cartesian() → expected_vel
│       ├── velocity drift check (every frame)
│       ├── cartesian_to_orbital_elements() (if drift > 1e-6)
│       └── propagate_orbital_elements()
│
├── compute_global_coordinates()
│
├── update_spacecraft_physics()
│   └── for each craft:
│       ├── orbital_elements_to_cartesian() → expected_vel
│       ├── velocity drift check
│       ├── cartesian_to_orbital_elements() (if drift)
│       ├── check_maneuver_trigger() ← inline, before propagation
│       │   ├── TRIGGER_TIME: sim->time >= trigger_value
│       │   └── TRIGGER_TRUE_ANOMALY:
│       │       └── analytical mean anomaly delta (no propagation)
│       └── if maneuver fired:
│       │   ├── propagate_orbital_elements(burn_dt)
│       │   ├── execute_maneuver()
│       │   │   ├── apply_impulsive_burn()
│       │   │   └── cartesian_to_orbital_elements()
│       │   └── propagate_orbital_elements(remaining_dt)
│       └── else:
│           └── propagate_orbital_elements(sim->dt)
│
├── compute_spacecraft_globals()
└── sim->time += sim->dt
```

## Issues Found

### Issue 1: Redundant Propagation for True-Anomaly Triggers

**Status:** RESOLVED — eliminated in favor of analytical mean anomaly delta calculation.

**Location:** `src/maneuver.cpp`, `check_maneuver_trigger()` (true-anomaly branch)

Previously, for every frame that a true-anomaly maneuver was pending, `propagate_orbital_elements()` was called as a "look-ahead" probe to determine if the target angle was approaching.

```cpp
// OLD (maneuver.cpp:147) — REMOVED
OrbitalElements future_elements = propagate_orbital_elements(craft->orbit, sim->dt, parent->mass);
```

**Resolution:** Replaced with direct analytical computation of `dt_needed` from mean anomaly delta. The analytical solution is more precise (no discretization error) and eliminates ~24k redundant Kepler solves per Hohmann transfer wait period at DT=10s.

**Remaining:** The current implementation only handles elliptical orbits. TODO comment added for parabolic (Barker's equation) and hyperbolic branches.

### Issue 2: Mixed Concerns in `execute_pending_maneuvers()`

**Status:** RESOLVED — merged into `update_spacecraft_physics()`.

The function previously performed two distinct responsibilities:
1. **Checking** trigger conditions (calls `check_maneuver_trigger()`)
2. **Executing** the burn (propagation → burn → propagation)

**Resolution:** Trigger checking now happens inline in `update_spacecraft_physics()` before the propagation decision. The code is cleaner: check → decide propagation amount → propagate → burn (if needed) → propagate remainder.

### Issue 3: Ambiguous `scheduled_dt` Semantics

**Status:** PARTIALLY RESOLVED — semantics are now clearer but still differ by trigger type.

| Trigger Type | `scheduled_dt` meaning | Set by |
|-------------|----------------------|--------|
| `TRIGGER_TIME` | Always 0.0 (never set) | Never |
| `TRIGGER_TRUE_ANOMALY` | Seconds until exact burn position | `check_maneuver_trigger()` |

In `update_spacecraft_physics()`:

```cpp
if (maneuver_fired) {
    craft->orbit = propagate_orbital_elements(craft->orbit, burn_dt, ...);
    execute_maneuver(fired_maneuver, ...);
    craft->orbit = propagate_orbital_elements(craft->orbit, remaining_dt, ...);
}
```

For `TRIGGER_TIME`, `burn_dt == 0` is still a coincidence — the field is never set. The branching is now explicit via `maneuver_fired` flag, which is clearer.

### Issue 4: Time-Triggered Burns Propagate from Wrong State

**Status:** UNRESOLVED — root cause of burn timing quantization.

For time triggers, the sequence is:

```
Frame N:  sim->time = 310.0  (trigger_value = 305.0)
          check: 310 >= 305 → true
          burn_dt = 0
          remaining_dt = 10
          execute_maneuver() → burn applies at sim->time=310
          propagate craft by 10s starting from sim->time=310
```

The craft's orbit state is at `sim->time=310`, not at the trigger time `305`. The burn fires 5s late and the post-burn propagation starts from the wrong orbital position. This is the root cause of the burn timing quantization problem documented in `docs/planning/hohmann-rendezvous-quantization-fix.md`.

**TODO in code:** `update_spacecraft_physics()` has a TODO suggesting `dt_to_burn = trigger_value - (sim->time - sim->dt)` for exact placement.

### Issue 5: Hardcoded Array Size

**Status:** RESOLVED — removed `spacecraft_handled_this_frame[256]` static array.

**Location:** Previously `src/simulation.cpp`, static declaration

```cpp
// REMOVED
static bool spacecraft_handled_this_frame[256];
```

**Resolution:** The array is no longer needed since maneuver checking is inline in the propagation loop. No separate tracking mechanism required.

### Issue 6: Duplicated Propagation Logic

**Status:** RESOLVED — single propagation path.

The "normal" propagation path and the maneuver path are now the same code path:

```cpp
if (maneuver_fired) {
    craft->orbit = propagate_orbital_elements(craft->orbit, burn_dt, ...);
    execute_maneuver(...);
    craft->orbit = propagate_orbital_elements(craft->orbit, remaining_dt, ...);
} else {
    craft->orbit = propagate_orbital_elements(craft->orbit, sim->dt, ...);
}
```

When `burn_dt == 0` and `remaining_dt == sim->dt`, the maneuver path is: propagate(0) → burn → propagate(sim->dt). The normal path is: propagate(sim->dt). The propagation logic is no longer duplicated.

## Call Sites Summary

### Final State (3 call sites)

| Location | Function | Context | dt value |
|----------|----------|---------|----------|
| `simulation.cpp:287` | `update_bodies_physics()` | Normal body propagation | `sim->dt` |
| `simulation.cpp:315` | `update_spacecraft_physics()` | Normal craft propagation | `sim->dt` |
| `simulation.cpp:338` | `update_spacecraft_physics()` | Pre-burn sub-step propagation | `burn_dt` (0 to `sim->dt`) |
| `simulation.cpp:343` | `update_spacecraft_physics()` | Post-burn remaining propagation | `sim->dt - burn_dt` |

Remaining: 4 call sites (1 for bodies, 3 for spacecraft), 2 distinct contexts for spacecraft (normal propagation, sub-step execution).

## Remaining Work

### Interpolated Time Triggers (TODO in code)

For `TRIGGER_TIME`, `scheduled_dt` is always 0, so the burn applies at `sim->time` (step boundary). To achieve exact placement:

1. In `check_maneuver_trigger()` for `TRIGGER_TIME`: compute `dt_to_burn = trigger_value - (sim->time - sim->dt)` when `sim->time >= trigger_value`
2. Set `scheduled_dt = dt_to_burn` (positive value, 0 to `sim->dt`)
3. The propagation loop then does: `propagate(dt_to_burn)` → burn → `propagate(remaining)`

This would place the burn at the exact trigger time, not the step boundary. See `docs/planning/hohmann-rendezvous-quantization-fix.md` for quantization analysis.

### Parabolic/Hyperbolic Orbit Support (TODO in code)

The analytical `dt_needed` calculation in `check_maneuver_trigger()` only handles elliptical orbits. TODO comment added for:
- Parabolic: Barker's equation `D + D³/3 = M`, where `D = tan(ν/2)`
- Hyperbolic: `e·sinh(H) - H = M`, using hyperbolic anomaly `H`