TroubleshootingMechJebPVG - KSP-RO/RP-1 GitHub Wiki

Primer Vector Guidance

Primer Vector Guidance is an implementation of a trajectory optimizer that is based around the "indirect" method of optimal control theory using Pontryagin's Minimum Principle and the calculus of variations as synthesized in Lawden's Primer Vectory Theory. It uses the Dormand-Prince Runge Kutta method as a forward integrator (equivalent to Matlab's "ode45") to do multiple shooting and then Levenburg-Marquardt as a quasi-Newtonian root finding algorithm (equivalent to Matlab's "lsqnonlin") to find the optimal solution along with a numerically computed estimate of the Jacobian of the boundary value problem. There are no linear approximations made, so it is considerably more accurate than PEG and other guidance models which use linear gravity models and other approximations, at the cost of substantially more computational overhead (as a result PVG runs in its own dedicated thread, and may take multiple KSP time ticks in order to solve the optimal control problem). The closest real world algorithms to PVG are OPGUID and SWITCH which also used the Calculus of Variations approach, with Runge-Kutta-Fehlberg and a quasi-Newtonian method to solve the root finding problem but with numerical integration of the Jacobian, or analytical computation for coast arcs.

The limitations of PVG are that the indirect method that it uses is sensitive to initial conditions, and is not usable for dissipative systems. In more plain English this means that atmospheric modelling is highly problematic to nearly impossible, particularly for any generalized solver that isn't constrained to specific problems. Path constraints like "do not go below the surface of the Earth" are also not feasible to implement. That means that PVG will remain a vacuum-only optimizer until it is completely rewritten. The biggest take away from this is that it implies that it is up to the human user to deal with the complexities of the initial aerodynamic flight.

Table of Contents

1. Quick Start

2. Pitch Program Tuning

3. When To Press The "Do Not Press" Button

4. Best Practices

5. Diagnosing Issues

§1: Quick Start

TO DO: put a screenshot here of the menu

Setting Up MechJeb

There are a few steps that everyone should take which are more general tips on using MechJeb with RSS/RO and not directly related to PVG launch guidance, but since many "PVG" issues turn out to be general setup issues, here are the first steps anyone should take with MechJeb for RSS/RO:

  • Currently you should be on KSP 1.12 - 1.10 (it may backport to 1.8/1.9 if you ignore the compat checker)
  • You need to be on the most recent dev version of MJ: https://ksp.sarbian.com/jenkins/job/MechJeb2-Dev/
  • In the utilities menu:
    • The throttle limiters need to be all turned off after launch (or do not use them at all -- if you use the g-limiter you have to turn it off)
    • Use RCS to ullage should always be set
    • Prevent unstable ignitions CAN be set, but should be turned off for sounding rocket era.
  • In the settings menu select "module disabling does not kill throttle (RSS/RO)"
  • In the main KSP settings menu you should set the default throttle to 1.0 (technically the above mechjeb setting winds up restoring the default throttle, so it needs to be 1.0)
  • In the attitude adjustment menu make sure you are using the "better controller"
    • Whack the 45 degree phase margin button
    • Whack the restore all other defaults button
  • Ensure that you have enough avionics on all your stages
  • Ensure that your vessel is rooted to a part in the actual payload
  • Ensure that the delta-v stats of MJ make sense

Controls

  • Reset Guidance - This is marked "DO NOT PRESS" because it is not safe to press under all circumstances (see discussion in section below)

  • Target Periapsis, km of altitude - Note that high periapsis targets become increasingly more and more difficult to achieve.

  • Target Apoapsis, km of altitude - Values less than the periapsis down to zero result in circular orbits, negative values are hyperbolic.

  • Attach Altitude, km of altitude - This can be used to pick a specific insertion altitude (useful mostly for shuttle style launches to e.g. 90x180 with attachment at 120km).

  • Orbit Inc, degrees - Target inclination, note that inclination less than your launch site latitude rapidly becomes very expensive (broadly equivalent to a plane-change maneuver of the difference in degrees in low-Earth orbit).

  • Booster Pitch Start, km/s - The initial pitch program is initiated after the rocket hits this speed after a vertical rise. Generally leave at 50 m/s (see discussion in section below).

  • Booster Pitch Rate, deg/s - The rate at which to initially pitch over. This must be tuned broadly to the SLT (sea level thrust-to-weight ratio) of the rocket (see discussion in section below).

  • Guidance Interval, sec - How often the optimizer runs. Leave this at 1 second. It does not permit using lower values, increasing this value would be for computers where the impact on performance is noticeable.

  • Qα limit, Pa-rad - This is the equivalent of the Angle-of-Attack limiter. It is not optional. Values of 1000-4000 are reasonable for real rockets. Generally leave this at 2000. If rockets flip decrease this number for a tighter constraint, if the rockets is highly stable, it can be increased. 1000 Pa-rads is roughly 2 degrees of AoA at a max Q of 30 kPa.

  • Omit Coast - Use this if you are hotstaging a 2 stage-to-orbit rocket and your rocket cannot coast, or if the resulting coast is long and produces a burn-up trajectory (due to PVG being vacuum-only).

Status Display

  • Rocket Stage Analysis - The lines show you how PVG has analyzed your rocket. The first number is the logical stage (first stage, second stage, etc). If it says "burn 2" it is referring to the KSP stage #2 (which corresponds to the ∆v stats display in MechJeb, and the staging controller in KSP). he next number is the planned burntime in seconds. The next number is the planned ∆v in m/s (vacuum ∆v, because PVG is vacuum-only). The number in parenthesis is the residual ∆v in m/s in that stage. It should be positive for the last stage, indicating that some propellant will be left over after the burn, and should be zero for all prior stages. If these numbers do not make sense then guidance has become confused, and Reset Guidance may actually be called for.

  • Guidance Status - This shows the state of the guidance controller state machine.

  • Converges - This is a count of how many times the optimizer has successfully solved the problem, it should increase by one every second.

  • Status - This is the status result from the alglib.net minlmoptimize() call to the Levenburg-Marquardt algorithm (this is for me, probably not you).

  • N - This is the last number of iterations required to converge the solution and the number in parens is the maximum iterations which has been seen.

  • Staleness - This is how old the last successful guidance solution is. It should mostly be on "0s" and if it starts incrementing that implies guidance is actively failing (again consider Reset Guidance).

  • Znorm - This is the distance the optimizer stopped from the origin of the root finding problem on the last run, it should be on the order of 1e-8 or smaller.

  • Last Failure - If this is shown in red it displays the last failure of the optimizer. The optimizer MAY have recovered, so this shows the LAST failure. Check the staleness number and other indications to see if it is currently healthy or not. Some of the error messages like "Target Conditions Unreachable" are human-consumable. Some of them may indicate internal errors and bugs.

  • Autopilot Status - This shows the condition of the overall ascent guidance state machine (the transition from vertical rise, to pitch initiation, to gravity turn, to guidance).

§2: Pitch Program Tuning

PVG is inherently limited because the math that it does does not know about the atmosphere and does not know about the surface of the Earth. It will happily find solutions which will be aerodynamically unstable, will overheat your rocket, or will send it through the surface of the Earth because those trajectories are "optimal solutions" as far as it is concerned.

That means that it is up to the human user to get the rocket out of the atmosphere to begin with. Which means that you must build up some skill at taking the TWR of your first stage along with how "lofted" your target conditions are and determine what to set for Pitch Start and Pitch Rate. The best way to analyze the rocket is to do a launch, and to look at the graphs for Q, AoA and Pitch on the MechJeb flight recorder window.

To set this up, you should open the flight recorder window and ensure that "Time" is displayed in the upper left and not "Downrange" (using "Downrange" distance compresses all the interesting bits and makes it more difficult to interpret). Select the Q, AoA and Pitch graphs, and you should see graphs similar to the ones below. If you do a due-east launch and see a flat line for the AoA graph, it is likely that your rocket does not have the pitch axis aligned correctly and either use the AoS (angle of sideslip) graph, or else use the roll control in the ascent guidance and adjust by 90 degrees, or adjust your command pod by 90 degrees in the VAB.

Overlofted Launch

PVG_launch_overloft

This is a launch which is "overlofted" and has pitched over too slowly. By the time PVG is transitioning to vacuum guidance as it comes out of Max Q it has to pitch down aggressively. You can see the steep transition between 90-95% of MaxQ until the Q-alpha limiter kicks in. Eventually dynamic pressure drops enough that the Q-alpha limiter is no longer kicking in and guidance becomes equal to vacuum guidance and the purple AoA line becomes a smooth parabola again.

To adjust this, simply increase the Pitch Rate. Sometimes the Pitch rate may need to be increase to over 2 degrees/sec for particularly high TWR rockets in the early game and/or Soviet path.

Overpitched Launch

PVG_launch_flat

This is a launch which is too aggressively pitched over. Before the rocket hits max Q the rocket has pitched over so aggressively that it has already "met" the vacuum guidance prediction. This rocket is at a risk of flying a too steep trajectory and overheating or breaking up due to aerodynamic stresses or simply not being able to escape the atmosphere and having aerodynamic constraints pull the trajectory back down to Earth. In order to attempt to save the launch, PVG shifts to vacuum guidance early, subject to the Q-alpha constraint to not flip the rocket. This is what is shown by the purple line deviating from zero before max Q. This is not an extreme example and rockets may deviate even sooner -- which will typically result in failure due to aerodynamic stress or heating. To attempt to save such a rocket launch Q-alpha can be increased to 4000 or so, but that risks the rocket flipping.

In order to fix this problem one should decrease the Pitch Rate, generally in increments of 0.1 deg/sec, down to a minimum of 0.1 deg/sec. If the rocket has such a low TWR and/or the target conditions are high enough that 0.1 deg/sec is still overlofting the rocket, then I typically bump up the Pitch Start to 75 m/s or 100 m/s and back the Pitch Rate off to 0.5 deg/sec again and start over with tuning the Pitch Rate. For most rockets I leave the Pitch Start set at 50 m/s however.

Optimal Launch

PVG_launch_good

This is a near-optimal launch. The pitch program is composed of a vertical rise until the Pitch Start speed (of 50 m/s) is met, which is followed by a pitchover maneuver based on the Pitch Rate setting (this is the downwards bump in the purple AoA line) Very quickly surface velocity of the rocket will "catch up" with this fixed rate Pitch Rate, once it does the manual Pitch rate is no longer followed and the rocket follows a zero Angle-of-Attack gravity turn through max Q (the flat purple AoA line through Max Q, and the slight "knee" in the pitch graph).

Once MaxQ has dropped to 95% of its maximum then the guidance shifts to the PVG vacuum guidance. This is done somewhat gradually by applying a linear scaling as Q drops from 95% to 90% of its maximum (so that the pitch command is gradually introduced) and then subjecting the command to the Q-alpha limitation to constrain the pitch command so as not to flip the rocket, and to gradually allow the vacuum guidance to take over as the dynamic pressure drops.

On this launch the Q-alpha limiter is actually not being activated at all and the purple line for AoA forms a near perfect smooth parabola. On some launches the Q-alpha limiter may kick in and take a small "bite" out of the upper left of the parabola -- this is likely not worth worrying about.

§3: When to Press the "Do Not Press" Button

The biggest issue around the Reset Guidance button is when not to press it. Do not press it when your trajectory includes a planned coast and you are in the coast phase. The bootstrapping process of the launcher assumes a launch from the ground which initiates with a burn phase, and not a coast phase. By resetting the guidance in the middle of a flight you will always re-bootstrap to a burn phase, even if you are currently in the middle of a coast phase. By lighting the rocket when you should be coasting this may be exorbitantly expensive in terms of necessary ∆v compared to the planned trajectory with the coast. Thus, never push the button during a coast phase. If your rockets engines are firing, then it SHOULD be safe to press it.

This may be useful if guidance has gotten badly out of whack. There are several possible symptoms which you can look for.

  • A climbing "staleness" time that is well above "1s". This tracks the last time the optimizer successfully solved the guidance problem and if it being to repetitively fail it will continue climbing instead of resetting to "0s" every time.
  • The rocket stage analysis section of the PVG status output looks completely out of whack. Pay attention to how PVG is analyzing your rocket. If you stages that don't exist, or in the wrong order, repeated stages, or coasts where there shouldn't be, or delta-V (consumed or remaining) values that seem very wrong then stage analysis has gone buggy. Whacking Reset Guidance may fix that.
  • FIXME: put in some others.

§4: Best Practices

Your Delta-V Stats Analysis Must Be Correct

You MUST pay attention to your delta-V stats analysis window. PVG consumes that, analyzes it, and tries to pull off what your actual significant rocket stages look like in order to accurately predict the future. This is a pretty strict Garbage-In-Garbage-Out process, so if your ∆v stats display is off then PVG will be impacted and may be less accurate, may do somewhat wild pitch maneuvers on staging, or may not work at all. When the ∆v stats predict the future accurately then PVG will be accurate and optimal. The causes of ∆v stats being off are many and varied. It may be fundamental rocket design issue (ie. trying to do 1.5 stage) or it may be a VAB mistake (wrong root part), it may be a staging mistake (sep motors in the incorrect stage) or generally just some edge condition of the way MechJeb analyzes the ∆v of stages (which is a remarkably difficult thing to do in KSP). The general rule though is that if the ∆v is off then you need to fix it or PVG will not function correctly.

PVG Must Be Able To Predict The Future And Cannot Read Your Mind

This is the fundamental principle that needs to be understood about any realistic launch-ascent guidance. The need for delta-V stats to be correct is a specific instance of this principle. PVG works best with MechJeb's autostaging enabled, because that interacts correctly with the delta-V stats analysis to correctly predict the future of how your rocket will fly. Since PVG cannot read your mind, it has no idea of when you might press spacebar and manually stage your rocket, which may result in very suboptimal flight if you do not exactly mimic MechJeb's autostaging behavior.

For small changes, the differences may be small, so the jettison of the LES or fairings are events that can happen which only slightly change the mass of the rocket and PVG will only have a very minor pitch up/down change when the staging events happen. The more major the event (like dropping a whole rocket stage) the more PVG will complain via having poor behavior.

The takeaway from this section is to use autostaging and to mostly constrain yourself to rocket designs which can autostage.

No Stage And A Half Support

This is one of the biggest impacts of the prior two principles. Since MechJeb autostaging does not support 1.5 stage, and you have to manually drop the engines on the way to orbit the ∆v stage analysis will be off, MechJeb has no information and cannot predict when you will drop the stage, so PVG knows nothing about it so the predictions will be off. Your available ∆v on the pad will be below how your rocket will actually perform by over 1,000 m/s and you may not be able to find a solution. It may work if you have an upper stage with additional ∆v that PVG can use in its analysis on the pad, when you stage it will then rearrange and pitch up or down. When you stage, it may confuse the stage tracking of PVG and hitting Reset Guidance may be called for. Some users have reported that using kOS to automate the staging in conjunction with PVG to do guidance works well enough. That is very much getting into off-label usage of PVG.

The general recommendation is to restrict yourself to the rocket designs that PVG and MechJeb's autostaging is good at. This lacks historical accuracy, but this is a game, and there's limited resources to implement all the pieces necessary to fly every different kind of rocket. Since RO allows airlighting LR-105s the solution is generally to build stacked Atlas rockets. This is actually more efficient, and is how most RO players progress, and is how RP-1 is balanced, and the accepted mechanic for doing playthroughs (and making the American path harder would just make the Russian path even more OP in the early game).

If you have to ask about 1.5 stage the answer is going to be "No". If you can figure it out for yourself, its still very much off-label and may have sharp edges.

Do Not Adjust Staging After Liftoff

A long time ago circa KSP 0.18 the staging used to be fixed in flight, so whatever you setup in the VAB was what you got. This was later changed so that players could rearrange their staging at will during flight, and lots of absent-minded game players started taking advantage of that. NASA does not do this, and fiddling with staging dynamically, while the rocket is flying to orbit actually is more like doing brain surgery on a walking patient. This is by FAR one of the hardest problems to solve in writing real-life guidance algorithms in KSP, and PVG is the 3rd or 4th iteration in trying to accurately do dynamic logical rocket stage tracking.

The problem is that when you drag the staging around you're changing the properties (thrust, burntime, mass, delta-V) of your stages, and as you drag the rocket around you may go through "moves" which create fairly nonsensical rocket designs before you've arrived at your fixed solution. It is also just difficult to try to track stages when they may be appearing and disappearing. This may also be combined with you dragging around stages and having them appear and disappear and renumber while the rocket is itself autostaging and dropping engines. You can see this in the delta-V window in MechJeb as you drag stages around (take a video of yourself dragging rocket stages around and play it back and meditate on how the delta-V stats reported by MechJeb are jumping around as you do it -- including stage numbering changing and stages appearing and disappearing).

Since PVG consumes the delta-V stats in order to predict the future performance of the rocket, any nonsense numbers, even transiently present in the delta-V window may cause it to hiccup and start producing nonsense guidance. My STRONG recommendation is to check yo staging on the pad and fix it before enabling PVG. If you fiddle with it after PVG is running on the pad then enable/disable PVG to reboot it (or Reset Guidance) after fiddling with staging. If you MUST fiddle with staging on the way to orbit, then pay attention to what PVG's stage analysis plan is telling you, ensure that it still makes sense, DO NOT fiddle with staging during a coast, and you may need to press Reset Guidance after you are done fiddling.

Note that earlier attempts to support more adjustment of staging during flight have now been completely abandoned. The problem is largely too hard to solve since many events may or may not happen around staging events, complicated by things like TestFlight failures causing stages that previously had plenty of burntime to go to zero and need to be jettisoned. MechJeb's pre and post staging delays mean that stages disappearing off the delta-V display and stages being dropped by the staging controller can be on very different ticks. There is no good sequencing heuristic that can be used to sort out the possible complexity and edge conditions. After having burned too much of my life on this problem, it is hereby NOTABUG. If you mess with stages during ascent and it eats your launch that is on you. If you "feel" that due to KSP being a game that you "should" be able to do that, you're welcome to write your own launch optimizer and stop being entitled, I am done with that problem.

Focusing PVG on rocket launches where the user does not attempt any reconfiguration during flight also allows PVG to be more correct and bug free for those flights. Attempts to deal with identifying rocket staging vs. reconfiguration were causing buggy edge conditions for flights where there was no reconfiguration. This allows PVG to be more bug free on the happy path.

Do Not Abuse the G-Limiter

The G-limiter is not integrated with the optimizer. If the insertion state is highly throttle limited, then accuracy will suffer, even if that stage has RCS enabled. It is best for accuracy to do insertion on a stage with lower TWR which does not need thrust limiting for accuracy. If possible, keep the amount of thrust limiting low and keep the max TWR of the stage near the throttle limit.

The implementation is simply that the g-limiter will act like a loss-of-thrust failure and the optimizer will attempt to correct for it, which will result in suboptimal flight. The rocket will pitch strangely when this happens, which is expected.

The min throttle setting can be used to prevent the g-limiter from throttling down the engine beyond the min thrust limit and shutting down the engine. Note that the zero of the throttle is not zero thrust, but relative to the minthrottle/maxthrottle range, so a minthrottle of 5% or so should always be used to prevent engine shutdown.

§5: Diagnosing Issues

Garbage In, Garbage Out

The fundamental rule of PVG is Garbage In, Garbage Out, and you are part of that system. You cannot be garbage and assume that it'll work well. If you can't conceptualize aerodynamics physics at all, if you don't understand that you need to watch your delta-V readouts and the PVG display, if you can't manage to tune your coast phases, or if you fiddle with your stages after you launch then you will not achieve good results.

My Rocket Went Way Over My Apoapsis: Not A Problem

Low TWR upper stages will loft well over their target apoapsis. For a 0.10 TWR upper stage lofting into a 185x185 km LEO target orbit, the Apoapsis may go over 700km (with a 25 minute burn finishing insertion over the coast of Africa when launched from KSC). This is how real rockets actually fly. Look into the trajectories of Atlas V launches with the single RL-10 upper stage. Issues around these lofted trajectories and the subsequent "black zones" of steep failure reentry trajectories are what killed the Ares I project. This is also why the Boeing Starliner project is using dual RL-10 Centaur upper stages to flatten out the trajectory.

You can work to fix this by increasing the TWR of the upper stage, but you may reduce your overall payload to orbit by decreasing the mass ratio by including more engine in the upper stage, particularly with hydrolox. This is not in itself a problem to be solved though, if you get better results with less engines and more lofting, then you have found the more optimal solution.

My Rocket Is Burning Down: Not A Problem

High TWR upper stages suffer the other problem, if your total burntime to orbit is low and the burnout TWR of the rocket is high, then the rocket has a competing problem where it needs to gain enough vertical velocity in order to get to the altitude it needs, then it needs to kill that vertical velocity in order to insert into the orbit in time. Longer burning rockets and lower TWR rockets will remove this, but this trajectory is not an issue. High TWR rockets are still more efficient.

This is also the #1 FAQ that everyone is tired of hearing about on the discord channel, please just don't bring it up. This issue is either entirely due to your inability to understand rocket trajectories or in the case of the periapsis insertion issue it is difficult to fix. It has been discussed to excessive length before and nobody wants to argue with another person about it again.

Excessive Short-Burning Boosters Causing Transition to Guidance too Early

This is caused by the logic that transitions to guidance after Q drops from 90-95 of Max Q. If you put high TWR strap on boosters onto a rocket, you can slam it into the atmosphere hard, then the dynamic pressure drops off sharply before ramping up again. Please just don't build rockets like this and expect them to fly properly. They are likely not very realistic.

You can successfully build a Delta III, but that vehicle does not exhibit the same kinds of dynamic pressure drops on staging (possibly because it transitions from the 6 booster stage to the 3 booster stage). Note that MechJeb's stage analysis and the autostaging code cannot successfully airlight the second stage of solid boosters on a Delta III design. You can use a kOS script or another mod though to control staging.

If you lower the TWR of your solids, reduce the number of them, or extend the burntime of the solids through Max Q that should solve this issue.

Converged Optimizer Iteration Failed Due to Engine Failure

If you get "Converged optimizer iteration failed" during a burn, and particularly if MechJeb suddenly stages when you don't expect it to, and then pitches (probably up), you probably had a failure. Check the F3 logs and look for indications that you had your engine on the prior stage shutdown. Because of the shutdown engine the optimizer can't find a solution and aborts hard. Then it automatically re-bootstraps itself, meanwhile the autostaging code jettisons the now-useless stage (although most of the time it doesn't and just leaves the engine shutdown and does not jettison the stage, i'm honestly unclear under what circumstances the booster gets jettisoned, but I've seen this happen), and it should then try to make it to orbit on the next stage. The error message is preserved to show that something went wrong during the ascent. The failure to find a solution is a symptom, though, the root cause would be the failure, which is only accessible through the F3 log.

Note that this isn't the only possible cause of "converged optimizer iteration failed" but it is likely to be the most common. Anything else where either the vehicle description (thrust, weight, stages, etc) changes, or where the trajectory is forced off-nominal can cause it. So you might see on flights where aerodynamics drags the rocket back down into the atmosphere and burns it up. Or you might see it on flights where you lose avionics and go off-course. You might also see it on flights where the root part of the vessel is wrong and delta-v statistics are wrong, or you have burned out sep motors in the stage (see discussion elsewhere on all these issues), but the most likely and first cause to debug is hitting F3 and looking for a failure.

Throttle Limiters Killing Your Throttle

Don't use any of the throttle limiters. In particular don't worry about Max-Q or anything like that. For orbital class launchers on Earth that are remotely realistic, the atmospheric drag does not matter and it is always more optimal to use bang-bang control (either 0% or 100% throttle). Real rockets throttle down at Max-Q to reduce dynamic pressure and stresses on the airframe which are not modeled sufficiently accurately in KSP to make it a concern, they do not throttle down due to drag. The only useful throttle limiter would be the g-limiter, to prevent splattering kerbals with high g loads, but that hasn't been fixed and re-enabled yet, so generally all the throttle limiters are useless. If they kick in they may kill your throttle on the way to orbit and scrub your launch. This is not unique to PVG.

Insufficient Avionics Problems (My Rocket Starts Burning Straight Down)

In recent versions of RP-1 there is now integration with MechJeb so that if a stage has insufficient avionics, MechJeb's controls are killed.

Due to some bugs in MechJeb's handling of disabling controls, the throttle might also be killed so some instances of "MechJeb kill my throttle on stage separation" may be due to old versions of MechJeb interacting with RP-1 killing MechJeb's controls when there are insufficient avionics.

A good example video of a rocket launch which has insufficient avionics in a second stage is in this video:

IMAGE ALT TEXT HERE

Note that on stage separation the "Insufficient Avionics" banner is flashed on the screen for a few seconds and then disappears. The rocket then flies with a relatively fixed attitude during the period that avionics are disabled, which pushes the Apoapsis to above 200km well above the 150km target orbit. Once the fuel in the rocket is drained below the avionics limit, avionics kicks on again and PVG is able to guide the rocket again, where it finds that it needs to burn straight down in order to achieve the target orbit.

The solution to this is to include sufficient avionics on all stages and stop being a dirty cheater.

The idea of leaving the "Insufficient Avionics" banner on the screen permanently as long as avionics was disabled was discussed but rejected due to it meaning that message would be permanently splashed on the screen during the sounding rocket era. Current builds of MechJeb will display "CONTROL DISABLED (AVIONICS)" in red and all caps instead of "Stable Guidance" as a status in the Ascent Guidance window.

Issues with Autostaging Fairings

The first issue is the Real Scale Boosters (RSB) fairings aren't identified as fairings at all my MechJeb, they're some kind of decoupler rather than a fairing, and MJ would need some heuristics to determine that the decouplers wouldn't drop any other parts or something like that. They just don't work at all for staging the fairings.

Even for regular fairings MJ can't distinguish between interstage fairings and normal fairings. That means that you have to correctly configure the fairing staging in the appropriate point in the KSP staging list manually. The effect of the autostaging then is to block autostaging of that fairing until the conditions are met for autostaging. If you have selected a location which is too soon, then MJ will block all autostaging until the conditions are met.

Furthermore if you are trying to autostage fairings during a coast phase, that gets blocked by the way the coast phase is implemented to block MJ's autostaging. It has no ability to peek into the next stage and see there's a fairing there and fire it when the conditions are met (again issues due to correctly identifying fairings being nontrivial). So the behavior will be to drag the fairings up to the insertion burn.

The best suggestion of how to deal with fairings is probably to not using the fairing autostaging at all right now since it is so fussy. Just ditch them normally when you drop boosters somewhere above 50km or in the stage that initiates a coast phase. Not perfectly realistic but KSP doesn't perfectly model heat and dynamic pressure effects against sensitive payloads so it won't matter and if you drop it sooner you get a tiny bit more ∆v.

Why does my throttle cut off after I disable PVG?

You need to go into the MechJeb Settings menu (not the Utilities menu), and enable the "Module disabling does not kill throttle (RSS/RO)" setting.

Additionally, however, you need to ensure that either you fully throttle up at launch, or else that you go into KSP's settings and find the default throttle setting for launch and set that to 100%. The MechJeb setting only ensures that it does not actively kill the throttle, but that winds up with the throttle being restored to its pre-autopilot setting. If that pre-autopilot setting was zero, then that will still kill the throttle.

Coasts, Target Conditions and Booster ∆v

PVG is limited in where it can insert coasts. It only supports one coast phase before the final orbital insertion stage. This ensures that stages only require one ignition. There are also difficulties with multiple coasts since by adding them PVG (due to its limitation as a vacuum optimizer which does not know about the atmosphere or the surface of the Earth) would invariably produce "optimal" trajectories that would burn up and/or collide with the surface of the Earth.

As a result the position of the coast in the ascent will NOT be optimal at all and will be determined by the rocket designer. The major factor which will determine how high of a target conditions the rocket will be able to hit will be the total delta-V in the first N-1 stages compared to the delta-V fraction in the N-th stage. What this means is that for a two-stage rocket you are better off putting as much available delta-V as possible into the first stage and shrinking the upper stage. By building a rocket "top-down" with a maximally sized upper stage for the payload, and then merely sufficient booster to hit a certain reasonable about of delta-V that will be more limited than building with the largest size booster and then shrinking the upper stage to hit that amount of delta-V. It may also be possible that by taking the maximal booster (largest booster + largest upper stage for largest possible delta-V) that the rocket may actually be able to hit higher targets via shrinking the upper stage (less delta-V available to the rocket, but more delta-V in the booster and better able to hit higher target conditions).

There is no particularly good tooling available to the user to be able to adjust these tradeoffs in the VAB other than manual experimentation. When it comes to determining a given rockets capacity to hit target conditions, you can start usually with a 185x185 orbit. Gradually increase the target orbit and watch the PVG display to see what the "pitch" prediction is from PVG guidance. As you raise the target conditions the pitch will rise to 80 degrees and become expensive in total deltaV due to gravity losses. At some point beyond that PVG will begin to consume more delta-V than the rocket has available. Then the optimizer will begin to fail with "Target is unreachable", eventually it will fail with "Target is unreachable even with infinite ISP", which is normal. Your rocket design is not constructed well enough to reach the target conditions that you want.

In some cases, for elliptical orbits, it may be possible that the rocket can still reach the target conditions, but that PVG is limited by its fixed attachment to the periapsis and a zero-flight-path-angle. That requires PVG to cancel out all of the rockets upwards velocity before shutting off the engines which produces some pitching down and slightly less than optimal delta-V consumption. This is unlikely to be fixed in the near future, so the best alternative is to increase your booster delta-V -- either by shrinking your upper stage, adding a third stage for the insertion burn, or adding strap on solids for more booster stages and delta-V.

Incorrect Staging: Sep Motors In The Wrong Stage

This is a variant of "your ∆v stats must be correct or PVG will not work right". If you put your sep motors into the same stage as the engines (so that they fire at the same time) this will mess up the ∆v display which will mess up PVG. What happens is that MechJeb's FuelFlowSimulation only gives back one number each for the thrust, burntime and ∆v of a KSP stage. For a stage where the sep motors fires with the main engine the thrust returned is equal to the thrust of all the engines, including the sep motors. It then sort of assumes the sep motors will fire for the whole time, returning the correct ∆v value, but a truncated burn time. The result is that PVG thinks the TWR of the stage is wildly higher than it actually is, which will result in suboptimal flight, and a large pitch adjustment on staging after the misconfigured stage is dropped.

To fix this, MechJeb would really need to be able to internally report on "sub-stages" of a KSP stage, and break the burn up.

Launch to Plane and Principia: Rocket Sitting on Pad

You generally can't launch to the plane of the moon with Principia, and you don't want to. This is where stock RSS teaches us all the wrong practices. The inclination of the Moon is substantially below the latitude of KSC and varies from 18°20′ to 28°36′. RSS pins it at the highest value where it works to launch to plane, which is not what any Moon mission did. It is sitting on the pad failing to compute a trajectory because one is actually not feasible, because you need to travel so far south to meet up with the plane.

If you use a parking orbit, you can Match LANs instead of planes, using the "Match LAN" button in PVG instead, do a launch to 28.608 inclination and this will minimize the relative inclination to the Moon. For direct ascents the problem is much more difficult, most players chose to launch polar and eyeball it so the launch is opposite to roughly where the Moon will be in 2-3 days time. Or you can just use Kourou as a launch site, and launch to plane normally.

You generally will then not be exactly in the plane of the Moon (other than Korou launches). The problem there is then that the old coplanar Hohmann transfer function of MechJeb was only coplanar, so it cannot plot any sort of transfer that will impact/intersect the Moon. That is what led me down the road of writing the bi-impulsive transfer planer that could do non-coplanar transfers. That, however, has an issue where it still does not know how to Mid Course Correction burns, so the cost of a bi-impulsive transfer is actually somewhat more than plotting the transfer using a coplanar transfer and then inserting a (higher altitude) MCC in order to fix the inclination.

What MJ really needs is an implementation of Jezewski's Optimal N-impulsive burn planner, but that is still just a figment of my imagination right now (although the Maneuver Planner does now support planning of multiple maneuver nodes).

This also explains why RSS is so cheaty and teaches you all the wrong things, because doing it right is difficult. You installed Principia though and decided you wanted to play in nightmare mode.

Using MechJeb to execute Principia Manuever Nodes

MechJeb now has the ability to execute Principia Maneuver Nodes. The code technically has nothing to do with PVG, but this is probably a good place to document it for Principia players. You should get a "Execute next Principia node" button in the Maneuver Planner + Node Editor. Both inertially-fixed and tracking manœuvres are supported.