Raising an Orbit

This tutorial raises a vehicle from its circular orbit to a higher circular orbit, with two burns. The first burn raises the apoapsis to the target altitude. The second burn, at the apoapsis, raises the periapsis to match. The script flies the active vehicle, which needs an engine and the propellant for both burns.

The complete script is raise_orbit.py.

Pointing the Vehicle

We point the vehicle prograde with its auto-pilot, and wait until it faces that way:

auto_pilot.mode = ksa.AutoPilotMode.prograde
auto_pilot.engage()
auto_pilot.wait()

The auto-pilot is the game’s flight computer. It keeps tracking prograde while the engines burn.

Raising the Apoapsis

We light the engines at full throttle, and wait for the apoapsis to reach the target. The event is a server side function, which the server evaluates each frame:

control.throttle = 1
control.engine_on = True
apoapsis_reached = conn.add_event(lambda: orbit.apoapsis_altitude > TARGET_ALTITUDE)
with apoapsis_reached.condition:
    apoapsis_reached.wait()
control.engine_on = False

Planning the Second Burn

The vis-viva equation gives the speed at apoapsis now, and the speed of a circular orbit there. The difference is the change in velocity the burn needs:

mu = orbit.body.gravitational_parameter
r = orbit.apoapsis
v1 = math.sqrt(mu * (2 / r - 1 / orbit.semi_major_axis))
v2 = math.sqrt(mu / r)
delta_v = v2 - v1

The rocket equation turns that into a burn time, from the vehicle’s mass, thrust and specific impulse:

exhaust_velocity = vehicle.specific_impulse * 9.80665
initial_mass = vehicle.mass
final_mass = initial_mass / math.exp(delta_v / exhaust_velocity)
mass_flow_rate = vehicle.available_thrust / exhaust_velocity
burn_time = (initial_mass - final_mass) / mass_flow_rate

Coasting to Apoapsis

We warp to 10 seconds before the burn, which is centered on the apoapsis, and then wait for the burn to start:

burn_ut = ksa.ut + orbit.time_to_apoapsis - burn_time / 2
ksa.warp_to(burn_ut - 10)
auto_pilot.wait()
burn_start = conn.add_event(lambda: ksa.ut >= burn_ut)
with burn_start.condition:
    burn_start.wait()

Raising the Periapsis

The second burn ends at its planned time, or when the periapsis reaches the target, whichever is first:

control.engine_on = True
burn_end = burn_ut + burn_time
burn_done = conn.add_event(
    lambda: ksa.ut >= burn_end or orbit.periapsis_altitude >= TARGET_ALTITUDE
)
with burn_done.condition:
    burn_done.wait()
control.engine_on = False
auto_pilot.disengage()