---
title: "Unstable Orbits and the Three-Body Problem"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Unstable Orbits and the Three-Body Problem}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

```{r}
library(orbitr)
```

If you start plugging in random masses and velocities, you'll quickly discover that most configurations are wildly unstable. This isn't a bug — it's physics. Stable orbits are the exception, not the rule.

In a two-body system, stability is relatively easy to achieve: give the smaller body the right velocity at the right distance and it traces a clean ellipse forever. But the moment you add a third body, things get chaotic. The three-body problem has no general closed-form solution — small differences in initial conditions lead to dramatically different outcomes, including bodies being flung out of the system entirely.

## A Chaotic Triple-Star System

Here's an example: three equal-mass stars arranged in a triangle with slightly asymmetric velocities. It starts off looking like an interesting dance, but the asymmetry compounds and eventually one or more stars get ejected:

```{r three-body-sim}
three_body <- create_system() |>
  add_body("Star A", mass = 1e30, x = 1e11, y = 0, vx = 0, vy = 15000) |>
  add_body("Star B", mass = 1e30, x = -5e10, y = 8.66e10, vx = -12990, vy = -7500) |>
  add_body("Star C", mass = 1e30, x = -5e10, y = -8.66e10, vx = 14000, vy = -8000) |>
  simulate_system(time_step = seconds_per_hour, duration = seconds_per_year * 3)

three_body |> plot_orbits()
```

The static plot is honestly hard to read — three crossed paths without a sense of *when* anything happens. Animating it makes the chaos legible. Watch the slingshot ejection unfold in real time:

```{r eval = FALSE}
animate_system(three_body, fps = 15, duration = 6)
```

![](../man/figures/unstable-orbits-three-body-anim.gif)

This is actually what happens in real stellar dynamics — close three-body encounters in star clusters frequently eject one star at high velocity while the remaining two settle into a tighter binary. The process is called gravitational slingshot ejection.

## Troubleshooting Unstable Simulations

If your simulations are producing messy, diverging trajectories, here are a few things to check before assuming something is wrong:

**Velocity too high or too low.** At a given distance $r$ from a central mass $M$, the circular orbit speed is $v = \sqrt{GM/r}$. Deviating significantly from this produces eccentric orbits or escape trajectories.

**Bodies too close together.** Close encounters produce extreme accelerations that can blow up numerically. Try increasing `softening` or using a smaller `time_step`.

**Three or more bodies.** Chaos is the natural state of N-body systems. The stable examples in the documentation are carefully tuned — don't expect random configurations to behave.

**Time step too large.** If bodies move a significant fraction of their orbital radius in a single step, the integrator can't track the orbit accurately. Try halving `time_step` and see if the result changes.

The built-in constants and examples in `orbitr` are designed to give you stable starting points. From there you can tweak parameters and watch how the system responds — that's where the real intuition for orbital mechanics comes from.