Buckaroo's Flightgear Projects
Guide To YASim: Contents

What is YASim?

By Gary "Buckaroo" Neely

YASim is a flight dynamics model (FDM), a mathematical construct of algorithms and data that determines the physics of flight within the simulator. The 3D aircraft model has nothing to do with flight dynamics-- the 3D model is essentially just a picture to look at. It's the flight model, the FDM, that dictates how the model flies. YASim's author, Andy Ross, amusingly titled his work "Yet Another Simulator"

YASim uses the geometry of the aircraft to generate basic flight characteristics. For example, you feed the FDM informaton about the a wing, its shape, its chord, sweep, taper, incidence, span, stall characteristics, etc., and the FDM calculates the wing's contribution to the physics of flight. Provide the FDM information about the fuselage, its length, max width, taper, etc., and the FDM calculates the effect of this body on flight. Add in details about the power plant, the position of landing gear, fuel tanks, the aircraft weight, weight of extra payload. Describe the the aircraft's low speed, high angle of attack flight and the low angle of attack cruise flight, and the FDM uses these to model the extremes of flight. When you're done, you've created a mathematical model of the aircraft that can be used in a real-time simulation.

Out of the box, a YASim FDM is a crude approximation at best. YASim is not a magic solution where you plug in the aircraft dimensions and out pops a realistic flight model. Any YASim FDM will require much adjustement before you get a result that approaches authentic behavior. With experience, YASim can quickly give you a flyable solution, but obtaining realistic results requires research and effort. Be prepared to spend a lot of time refining your solution. In the end, your YASim result is only as good as your knowledge of the aircraft and your time spent tweaking the FDM.

YASim is capable of generating simulations for both fixed-wing and rotary-wing aircraft. This guide is aimed at fixed-wing developers. I have no experience developing helicopters, so at present this guide does not include sections dedicated to rotary-wing elements. Even so, helicopter enthusiasts may find other portions of this guide useful.

YASim and JSBsim

YASim is one of the two most commonly used FDMs in Flightgear. JSBsim is the other popular FDM used by the Flightgear community. I began working with FDMs using JBSim, but found the learning curve rather steep and moved over to working with YASim. YASim, despite very poor documentation, seemed more approachable and intuitive. My problem was not with JSBsim itself, rather it was my insufficient understanding of aerodynamics. I don't regret my YASim experience, far from it, yet if I knew four or five years ago what I know now, I might have stayed with JSBsim given its more versatile approach.

JSBsim and YASim have strengths and weaknesses. JSBsim is a richer, more flexible development environment, but the learning curve is steep and you will need more than a casual knowledge of aerodynamics. It also helps if you are comfortable with programming or scripting. If you have aerodynamic data for your aircraft and desire programatic control over all elements of the simulation, then JSBsim is the better choice. If you lack such data but know the geometry of the aircraft and have access to the same information available to a real pilot, then YASim can provide a simulation that is more than adequate for general aviation aircraft.

Make no mistake-- both YASim and JSBsim require a working knowledge of the fundamentals of flight.

YASim Issues

Any appraisal of YASim must acknowledge its limitations. The most consequential have little to do with flight simulation:

Documentation: YASim has almost no documentation except a short guide that lists and briefly defines parameters used to create a YASim FDM. Likewise, documentation of the underlying code is very thin. This situation is hard to justify given that YASim has been around for more than ten years and is heavily used by the Flightgear community. This guide is meant to help address that issue for FDM developers of fixed-wing aircraft. Unfortunately I know of no effort addressing the code documentation problem.

The code base: YASim has not seen dedicated development for a number of years and the code base has no active maintainer. The original developer has moved on to other projects. The code, while brilliant in places, has its share of ugly sections and is very poorly documented. Some portions of the simulation are crude hacks meant for later replacement. There are ongoing questions regarding possible bugs in the simulation. (I've discovered at least one significant bug myself.) Since there is no code maintainer, getting a change made to the code base is like waiting for an ice cube to melt in Antarctica. Some excellent modifications by experienced developers have gotten lost waiting for review and never made it into YASim. In other cases, hacks that never should have been implemented have somehow entered the code base.

YASim has some limitations as a flight simulator. Here are some I've observed or suspect:

- YASim was originally built to simulate subsonic general aviation aircraft. If the developer is not demanding precise realism, YASim can simulate aircraft up to the transonic realm, but it lacks provisions that make it suitable for accurate simulation of supersonic aircraft. Simulation of the transonic realm is mitigated by the fact that many aircraft like modern airliners have features that minimize transonic effects to the point where a pilot does not even notice them. This allows the YASim developer to ignore the problem for many aircraft in the transonic realm. In other cases, transonic effects can be simuated with some clever Nasal scripting. But the YASim developer should be aware that the FDM will not yield realistic characteristics at near-supersonic speeds or faster.

- YASim cannot simulate a true flying wing. YASim requires that the aircraft have a horizontal stabilizer to offset pitching moments generated in flight. In a flying wing, these moments are offset by reverse or "reflex" camber in the trailing edge of the wing's airfoil and other methods. If exact fidelity is not required and you just want your model to fly reasonably, you can cheat in YASim by placing a horizontal stabilizer close to the wing's trailing surface. But it won't be a true flying wing simulation.

- Currently there is no way to change the incidence of a flight surface in flight. YASim cannot simulate an all-moving flight surface such as stabilators or alter trim by changing incidence.

- The nature of YASim does not lend itself to easily creating multiple models with different engine specifications. You cannot simply "bolt on" a different engine by changing engine parameters and get the expected performance change. If you simply change engine parameters, YASim will try to balance the changes elsewhere to give the same approach and cruise characteristics. This means you won't get the results you expect without alterations elsewhere in the FDM. Similarly, adding floats to an aircraft requires significant FDM refinement. To be fair, this would be true of a real-life aircraft designer.

- Many engine elements are not well simulated. The YASim piston engine simulation is adequate for engine performance, but gives poor results for fuel consumption, manifold pressure values, and engine temperature values. For a good simulation, the developer should replace or modify YASim results with custom values using Nasal scripting. Jet engine simulation is rather simple and works best for older low-bypass engines. Turboprop engine code is rather rudimentary. Propeller feathering is not yet implemented.

- YASim is not an advanced simulator. The effects of flight surfaces are cummulative on the model, but all surfaces operate in their own space and don't affect the results of other surfaces. You won't see deep-stall issues where a wing or fuselage blocks airflow over the tail. You won't see induced drag benefits from adding little winglet surfaces at wingtips. Aircraft like the Cessna 172 won't pitch up when flaps are deployed due to increased airflow over the stabilizer. This isn't to say you can't simulate such things while using a YASim FDM, only that YASim isn't going to automagically do it for you.

- There are some basic simulation issues. Ground interaction has always been a bit twitchy. Induced drag has a bug (but there is an easy work-around for that). There may be a bug that causes aircraft to unduly turn into the wind upon landing. Airfoil lift and moment calculations are not all they could be. It's difficult to get exact pitch behavior upon flap deployment. Flap lift and drag cannot be interpolated to different values over the range of flap deployment. Etc. Most of these can be mitigated with tweaking and patience, or overcome by some clever thinking.

YASim And This Guide

YASim is well-suited to simulation of general aviation aircraft and most sport aviation. If you are modeling an aircraft in those categories, YASim can do a good job. I've created aircraft that fly close to flight manual parameters and reported behavior. But YASim won't do this for free. You will have to research your aircraft and understand what YASim is doing with the values you give it. Helping you understand how YASim uses these values is the purpose of this guide.