Update planning doc with completed refactoring status
Mark Issues 1, 2, 5, 6 as RESOLVED. Mark Issue 3 as PARTIALLY RESOLVED.
Mark Issue 4 as UNRESOLVED (time-triggered quantization).
Update call chain diagram to show current merged structure.
Update call sites summary to show final 4 call sites (3 contexts).
Add remaining work section for interpolated time triggers and
parabolic/hyperbolic orbit support.
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()`
@ -22,18 +25,34 @@ Replaced the per-frame propagation probe in `check_maneuver_trigger()` (true-ano
**Remaining:** See Issue 1 below — still has a TODO for parabolic/hyperbolic orbit support.
---
### 2026-04-20: Merged Maneuver Execution into Single Propagation Pass
## 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.
Consolidated `execute_pending_maneuvers()` into `update_spacecraft_physics()` so every spacecraft goes through exactly one propagation path.
if (check_maneuver_trigger(maneuver, craft, sim)) { // CHECKING
// ... propagation, burn, more propagation // EXECUTING
}
}
}
```
The trigger-checking logic (especially the true-anomaly branch with its Kepler equation solving) is interleaved with the execution logic. This makes it difficult to reason about what happens in each phase and complicates testing.
**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
The `scheduled_dt` field in `Maneuver` has different meanings depending on trigger type:
**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()` |
For `TRIGGER_TIME`, `scheduled_dt == 0` is a coincidence — the field is never set. The code works, but the reason is opaque. The branching (`if dt_to_burn > 0`) exists only for true-anomaly triggers, but a reader cannot tell this from the code alone.
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.
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.
A global array with a hardcoded size of 256. If more than 256 spacecraft are added, the tracking silently truncates. It should be part of `SimulationState` or dynamically sized. There is already a FIXME comment on this line.
**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
The "normal" propagation path in `update_spacecraft_physics()` and the maneuver path in `execute_pending_maneuvers()` are essentially duplicates:
When no sub-step is needed, the maneuver path is: propagate → convert → burn → propagate → convert. The propagation and coordinate conversion logic is duplicated across both code paths.
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
### Before fix (5 call sites)
### Final State (3 call sites)
| Location | Function | Context | dt value |
|----------|----------|---------|----------|
| `simulation.cpp:287` | `update_bodies_physics()` | Normal body propagation | `sim->dt` |
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)
