# PEGLand: Pinpoint Powered Landing Guidance

> [!CAUTION]
> When you type `pegland` into kOS terminal, Atmosphere Autopilot (AA) might be activated on its default keybinding `[P]`, causing flight control wobbling. You can press `[P]` another time to deactivate AA, or change keybindings.

`pegland` is one of the most exciting programs in this mod, adapted from the PEG launch guidance algorithm developed by NASA in the 1980s for the Space Shuttle program, achieving fuel-optimal pinpoint landing in a vacuum environment.

Reference: [An explicit solution to the exoatmospheric powered flight guidance and trajectory optimization problem for rocket propelled vehicles | Guidance, Navigation, and Control and Co-located Conferences](https://arc.aiaa.org/doi/10.2514/6.1977-1051)

## Algorithm Principles

From a proper pre-landing orbit, PEGLand ignite the engines and guide the lander until it lands on celestial surface safe and sound.

PEGLand contains three guidance phases:

- **Descent Phase**: Decelerates from landing orbit and descends, aiming near the landing point. First estimates the ignition position, then after coasting to the ignition position, uses the PEG algorithm to iteratively predict the landing point and update control parameters, achieving fuel-optimal descent. **There is no unpowered coasting phase during descent; the program burns at nearly constant throttle until it reaches the vicinity of the surface.** The descent phase is accurate if the spacecraft's engines have 60% throttle capability or can be restarted. If the engines can neither throttle nor restart, the guidance program prioritizes the target speed and altitude at the end of the descent phase over landing accuracy to ensure safety;
- **Approach Phase**: Slowly moves from near the landing point to 50cm above the landing point. Uses the same quadratic guidance algorithm as the Apollo missions to reduce landing error to the decimeter level. The approach phase requires the spacecraft to have deep-throttling engines capable of hovering; if conditions are not met, the approach phase can be skipped;
- **Final Phase**: Descends slowly from above the landing point, eliminates horizontal velocity, and touches down at 5cm/s.

## Using PEGLand

```kOS
switch to 0.  // Switch to the flight center's document system
run pegland(P_GUI, P_PREC, P_NOWAIT, P_ADJUST, P_ENGINE)
Parameters:
   P_GUI: Open GUI. Default is true
   P_PREC: Add approach phase for high-precision landing. Default is false
   P_NOWAIT: Start descent program immediately without waiting to coast to ignition position (i.e., ignite_now in GUI window). Default is false
   P_ADJUST: Target correction vector. Default is V(0,0,0)
   P_ENGINE: Engine mode.
      "current": (default) Use currently activated engines
      <label>: Search for engines matching the label and activate at ignition. Especially useful for solid rockets
```

**Examples:**

```kOS
switch to 0.  // Switch to the flight center's document system
run pegland.  // Open PEGLand GUI. (RECOMMENDED)
run pegland(0,1,1). // Don't open GUI, start engine descent immediately, add approach phase
run pegland(0,0,0,V(0,0,0),"descent"). // Don't open GUI, use engines labeled "descent" for calculations
run pegland(0,0,0,V(-50,10,1)).  // Move target: 50m south, 10m east, 1m up
```

## PEGLand GUI

PEG algorithm is not magic, it works only if certain physical constraints are met, which means it is your responsibility to drive the spacecraft to a proper pre-landing orbit.

Before activating PEGLand guidance and starting iterative calculations, I strongly recommend you click the `Analyze Orbit` button to quickly analyze your landing orbit and check the landing conditions. It will give you two indicators with recommended value ranges. Within the recommended range, fuel requirements for the landing process are basically the same. But if you deviate too far, it will cause serious fuel waste or even guidance divergence.

- `descent distance`: Orbital altitude directly above the target landing point. Descending from too high an orbit requires the spacecraft to pitch down and accelerate to reach the ground in a limited time; for too low an orbit, the spacecraft needs to spend fuel maintaining altitude.
- `lateral distance`: Distance of the landing point from the orbital plane. PEGLand needs to control yaw angle to correct normal errors; excessive normal distance increases fuel consumption and may even cause guidance divergence.

`Analyze Orbit` takes the next maneuver node into account. If you are not in a proper landing orbit, you plan a maneuver node and hit `Analyze Orbit` again.

![](../pictures/PEGLand/gui_analyze_orbit.png)

In most cases, you can complete guidance setup with one click in the PEGLand GUI and dynamically adjust parameters during landing. Basic settings include:

- `Active`: Activate/stop guidance program. Activating this button will cause the guidance program to immediately start calculating and execute landing as planned; stopping guidance will return the guidance program to its initial state
- `Ignite Now`: Ignite immediately without waiting for the spacecraft to coast to the ignition position
- `Add Approach Phase`: Add approach phase to achieve precise landing
- `start phase`: Which guidance phase to start from. If you're already very close to the ground and not moving fast, you can start soft landing from `final phase`
- `Roll`: Spacecraft roll angle
- `Emergency Suppress`: Emergency stop. Immediately stops kOS control of the vehicle's attitude and throttle, returning control to you.

<img src=../pictures/PEGLand/gui_explained_eng.png width=60%>

### Adjusting the Landing Point

On wakeup, PEGLand automatically read activated waypoint as landing target. If there is no activated waypoint, then it will try to find the impact point. If that fails again, then you need to set it manually.

You can click `use current waypoint`, or `use impact point` or manually enter the landing point latitude and longitude, **and click `update target`** to set the landing point. During landing, if you find the original landing point unsuitable, PEGLand also provides a very convenient visual adjustment function. Click `show target` to display the landing position on the HUD, then click the adjustment buttons to move the landing point forward, backward, left, right, or in cardinal directions. The distance moved with each click can be set in `Moving step`.

The `Find landing site within` button is a more automated method that will randomly sample points within a certain range around the original target and find the flattest landing site. It will also tell you the slope of the new landing site.

![](../pictures/PEGLand/gui_sample_site.png)

**Note:**

- If you are in impacting orbit, using impact point as target might be a good choice. Or you can just start from final phase to perform an untargeted suicide burn landing
- Only descent and approach phases allow landing point adjustments
- Excessive landing point adjustments may cause guidance divergence
- Try to adjust when still far from the landing point
- For spacecraft whose engines can neither throttle nor restart, adjusting the landing site is meaningless.

### Adjusting Descent Phase Targets

Descent phase targets need to be set manually, though in most cases the default settings are sufficient. But you may need to adjust these parameters to make approach phase performance more as expected. In PEGLand, the transition condition from descent phase to approach phase is kind of complicated. Descent phase doesn't aim at the actual target, instead, it will create a virtual target nearby. You need to assign where and how fast the virtual target is, to ensure approach phase have a good start. Before your vessel reach the virtual target (`Quit Time` ahead of reaching it), the descent phase quit and approach phase (or final phase) take over.

<img src=../pictures/PEGLand/des2app.jpg width=60%>

![](../pictures/PEGLand/gui_explained_destarget.png)

Main descent phase targets are defined by five parameters:

- `RT`: Height above target
- `VRT`: Vertical descent velocity
- `LT`: Horizontal distance from target
- `VLT`: Horizontal velocity
- `Quit Time`: When to finish descent phase

Creating a good start state for approach phase can save you fuel and improve landing accuracy. When the approach phase starts, longer distance and slower horizontal speed will make approach phase longer. Longer approach phase duration wastes fuel and throttle may exceed physical limits; shorter duration may result in insufficient landing accuracy.

⚠**Note**: Switching from Descent Phase to Approach Phase often involves pitch changes. If your lander is large and attitude control is relatively slow, you should appropriately extend the `Quit Time` to provide sufficient time to adjust attitude.

**Descent Trajectory Shaping**

When you are flying low, there is apparent risk hitting into terrain, as PEG algorithm cannot perceive obstructs along the trajectory. However, PEGLand does provide you tool to shape the trajectory. When you are still far away from the descent target, the shaping tool create a shaping target above the descent target, thus raise your trajectory. Once you've passed distance threshold, the guidance switches to descent target immediately.

For example, if there is a mountain with altitude of 1.5 km in the course, 5km from the landing target, and you are sure to collide into it if you do nothing special. You can aim at several hundreds meters above the target when you are 5 km away.

### About Unthrottable Spacecraft

PEGLand controls the landing point and ensures a safe landing by adjusting engine throttle or restarting the engines. It automatically checks whether the spacecraft's engines have enough remaining ignitions to determine whether restarts should be allowed. You can also adjust this policy manually. The `Engine Settings` section contains two related options:

- `Allow Restart`: Whether engine restarts are allowed
- `Tolerance`: Restart tolerance. The engines shutdown or restart when the target throttle falls outside the tolerance range. Increasing this value reduces the number of shutdowns and restarts, but also reduces guidance stability and accuracy

## Tips

1. Ensure the spacecraft meets landing requirements: sufficient Δv. If final stage thrust-to-weight ratio range includes 1, recommend adding approach phase for more elegant landing;

2. Whether in GUI or command-line mode, PEGLand will try to read the active waypoint. You can set waypoints through WaypointManager, saving the trouble of manually entering latitude and longitude;

   <img src=../pictures/PEGLand/waypointmanager.png width=60%>

3. For non-throttling engines or engines with limited throttling ability, unfortunately I cannot guarantee landing accuracy (neither can the geniuses at NASA), but you can simulate landing once, then adjust the landing point based on landing error, which can reduce error to 100 meters. If you have brought RCS on ship it would be much easier. You can manually fire RCS engines forward or backward to simulate engine throttling, keeping the predicted error displayed on PEGLand near zero. This won't consume you a lot RCS fuel;

4. If the lower bound of thrust-to-weight ratio at final landing is too high, be careful - this might be more dangerous than Falcon 9's suicide burn;

5. Currently PEGLand only supports single-stage rocket landings, but you can switch engines or stage during landing, then press the "0" key, and the program will update engine parameters. PEGLand will not be optimized for multi-stage rockets in the future - while mathematically feasible, predicting engine parameters for future stages is super troublesome;

6. When entering commands in the kOS terminal, other mods may be accidentally activated, such as **Atmosphere Autopilot (P)**. These autopilot mods will compete with kOS for control, causing the ship to shake violently. **Turn off other autopilots like SAS, MechJeb, and Atmosphere Autopilot**.
