YASim: Difference between revisions

:''Why YASim? YASim uses the geometry of the aircraft to generate the base flight characteristics. While this suggests a 'realistic' or out-of-the-box approach, it is a only rough approximation that will require much tweaking before you get a result that approaches realism. If you have solid flight data for your aircraft such as wind-tunnel data or you are looking to eventually generate a hyper-realistic simulation, JSBSim is probably a better approach. If you lack such data but know the geometry of the aircraft and have access to the same flight characteristics and limits as a real pilot would, then YASim can provide a solution that is more than sufficient for most simulation needs.''

All positions specified are in metres (which is weird, since all other units in the file are English). The X axis points forward, Y is left, and Z is up. Take your right hand, and hold it like a gun. Your first and second fingers are the X and Y axes, and your upwards-pointing thumb is the Z. This is slightly different from the coordinate system used by [[JSBSim]]. Sorry. The origin can be placed anywhere, so long as you are consistent. I use the nose of the aircraft.

The top-level element for the file. It contains only one attribute:  

* '''mass:''' The empty (no fuel) weight, in pounds. It does include the weight of the engine(s), so when you add the engine weight in its tag, it acts just like a ballast.

The approach parameters for the aircraft. The solver will generate an aircraft that matches these settings. The element can (and should) contain <control> elements indicating pilot input settings, such as flaps and throttle, for the approach.

* '''speed:''' The approach airspeed, in knots TAS.

* '''aoa:''' The approach angle of attack, in degrees

* '''fuel:''' Fraction (0-1) of fuel in the tanks. Default is 0.2.

The cruise speed and altitude for the solver to match. As above, this should contain <control> elements indicating aircraft configuration. Especially, make sure the engines are generating enough thrust at cruise!

* '''speed:''' The cruise speed, in knots TAS.

* '''alt:''' The cruise altitude, in feet MSL.

* '''fuel:''' Fraction (0-1) of fuel in the tanks. Default is 0.2.

The location of the cockpit (pilot eyepoint).

* '''x,y,z:''' eyepoint location (see coordinates note)

This defines a tubelike structure. It will be given an even mass and aerodynamic force distribution by the solver. You can have as many as you like, in any orientation you please.

* '''ax,ay,az:''' One end of the tube (typically the front)

* '''cx,cy,cz:''' Factors for the generated drag in the fuselages "local coordinate system" with x pointing from end to front, z perpendicular to x with y=0 in the aircraft coordinate system. E.g. for a fuselage of a height of 2 times them width you can define cy=2 and (due to the doubled front surface) cx=2.

This defines the main wing of the aircraft. You can have only one (but see below about using vstab objects for extra lifting surfaces). The wing should have a <stall> subelement to indicate stall behavior, control surface subelements (flap0, flap1, spoiler, slat) to indicate what and where the control surfaces are, and <control> subelements to map user input properties to the control surfaces.

* '''x,y,z:''' The "base" of the wing, specified as the location of the mid-chord (not leading edge, trailing edge, or aerodynamic center) point at the root of the LEFT (!) wing.

* '''camber:''' The lift produced by the wing at zero angle of attack, expressed as a fraction of the maximum lift produced at the stall AoA.

These defines the horizontal stabilizer of the aircraft. Internally, it is just a wing object and therefore works the same in XML. You are allowed only one hstab object; the solver needs to know which wing's incidence to play with to get the aircraft trimmed correctly.

A "vertical" stabilizer. Like hstab, this is just another wing, with a few special properties. The surface is not "mirrored" as are wing and hstab objects. If you define a left wing only, you'll only get a left wing. The default dihedral, if unspecified, is 90 degrees instead of zero. But all parameters are equally settable, so there's no requirement that this object be "vertical" at all. You can use it for anything you like, such as extra wings for biplanes. Most importantly, these surfaces are not involved with the solver computation, so you can have none, or as many as you like.

A mirrored horizontal stabilizer. Exactly the same as wing, but not involved with the solver computation, so you can have none, or as many as you like.

A subelement of a wing (or hstab/vstab/mstab) that specifies the stall behavior.

* '''aoa:''' The stall angle (maximum lift) in degrees. Note that this is relative to the wing, not the fuselage (since the wing may have a non-zero incidence angle).

* '''peak:''' The height of the lift peak, relative to the post-stall secondary lift peak at 45 degrees. Defaults to 1.5. This one is deep voodoo, and probably doesn't need to change much. Bug me for an explanation if you're curious.

These are subelements of wing/hstab/vstab objects, and specify the location and effectiveness of the control surfaces.

* '''start:''' The position along the wing where the control surface begins.Zero is the root, one is the tip.

* '''aoa:''' Applicable only to slats. This indicates the angle by which the stall AoA is translated by the slat extension.

    

A very simple "thrust only" engine object. Useful for things like thrust vectoring nozzles. All it does is map its THROTTLE input axis to its output thrust rating. Does not consume fuel, etc...

* '''thrust:''' Maximum thrust in pounds

* '''vx,vy,vy:''' The direction of the thrust in airframe coordinates. The vector will be normalized automatically, so any non-zero vector will work fine.

A turbojet/fan engine. It accepts a <control> subelement to map a property to its throttle setting, and an <actionpt> subelement to place the action point of the thrust at a different position than the mass of the engine.

* '''x,y,z:''' The location of the engine, as a point mass. If no actionpt is specified, this will also be the point of application of thrust.

* '''spool-time:''' Time, in seconds, for the engine to respond to 90% of a commanded powersetting.

A propeller. This element requires an engine subtag. Currently <piston-engine> and <turbine-engine> are supported.

* '''x,y,z:''' The position of the mass (!) of the engine/propeller combination. If the point of force application is different (and it will be) it should be set with an <actionpt> subelement.

* '''compression:''' The engine compression ratio.

Defines a landing gear. Accepts <control> subelements to map properties to steering and braking. Can also be used to simulate floats. Although the coefficients are still called ..fric, it is calculated in fluids as a drag (proportional to the square of the speed). In fluids gears are not considered to detect crashes (as on ground).  

* '''x,y,z:''' The location of the fully-extended gear tip.

* '''ignored-by-solver:''' with the on-water/on-solid tags you can have more than one set of gears in one aircraft, If the solver (who automatically generates the spring constants) would take all gears into account, the result would be wrong. E. G. set this tag to "1" for all gears, which are not active on runways. Defaults to "0". You can not exclude all gears in the solving process.

Defines a catapult launchbar or strop.

* '''x,y,z:''' The location of the mount point of the launch bar or strop on the aircraft.

* '''holdback-length:''' The length of the holdback from mount point to tip. Note: holdback up-angle and down-angle are the same as those defined for the launchbar and are not specified in the configuration.

A fuel tank. Tanks in the aircraft are identified numerically (starting from zero), in the order they are defined in the file. If the left tank is first, "tank[0]" will be the left tank.  

* '''x,y,z:''' The location of the tank.

* '''jet:''' A boolean. If present, this causes the fuel density to be treated as Jet-A. Otherwise, gasoline density is used. A more elaborate density setting (in pounds per gallon, for example) would be easy to implement. Bug me.

This is a mechanism for modifying the mass distribution of the aircraft. A ballast setting specifies that a particular amount of the empty weight of the aircraft must be placed at a given location. The remaining non-ballast weight will be distributed "intelligently" across the fuselage and wing objects. Note again: this does NOT change the empty weight of the aircraft.  

* '''x,y,z:''' The location of the ballast.

* '''mass:''' How much mass, in pounds, to put there. Note that this value can be negative. I find that I often need to "lighten" the tail of the aircraft.

This is an added weight, something not part of the empty weight of the aircraft, like passengers, cargo, or external stores. The actual value of the mass is not specified here, instead, a mapping to a property is used. This allows external code, such as the panel, to control the weight (loading a given cargo configuration from preference files, dropping bombs at runtime, etc...)

* '''x,y,z:''' The location of the weight.

* '''weight:''' Weight setting in pounds.

This element manages a mapping from fgfs properties (user input) to settable values on the aircraft's objects. Note that the value to be set MUST (!) be valid on the given object type. This is not checked for by the parser, and will cause a runtime crash if you try it. Wing's don't have throttle controls, etc... Note that multiple axes may be set on the same value. They are summed before setting.

* '''axis:''' The name of the double-valued fgfs property "axis" to use as input, such as "/controls/flight/aileron".

* '''src0/src1/dst0/dst1:''' If present, these defined a linear mapping from the source to the output value. Input values in the range src0-src1 are mapped linearly to dst0-dst1, with clamping for input values that lie outside the range.

This can be used to pass the value of a YASim control axis (after all mapping and summing is applied) back to the property tree.

* '''control:''' Name of the control axis. See above.

* '''min/max:''' Clamping applied to output value.

Some controls (most notably flaps and hydraulics) have maximum slew rates and cannot respond instantly to pilot input. This can be implemented with a control-speed tag, which defines a "transition time" required to slew through the full input range. Note that this tag is semi-deprecated, complicated control input filtering can be done much more robustly from a Nasal script.

* '''control:''' Name of the control axis. See above.

* '''transition-time:''' Time in seconds to slew through input range.

This tag is used to define a particular setting for a control axis inside the <cruise> or <approach> tags, where obviously property input is not available. It can be used, for example, to inform the solver that the approach performance values assume full flaps, etc...

* '''axis:''' Name of the control input (i.e. a property name)

* '''value:''' Value of the control axis.

A hitch, can be used for winch-start (in gliders) or aerotow (in gliders and motor aircraft) or for external cargo with helicopter. You can do aerotow over the net via multiplayer (see j3 and bocian as an example).

* '''name:''' the name of the hitch. must be aerotow if you want to do aerotow via multiplayer. You will find many properties at /sim/hitches/name. Most of them are directly tied to the internal variables, you can modify them as you like. You can add a listener to the property "broken", e. g. for playing a sound.

* '''x,y,z:''' The position of the hitch

* '''force-is-calculated-by-other:''' if you want to simulate aerotowing over the internet, set this value to "1" in the motor aircraft. Don't specify or set this to zero in gliders. In a LAN the time lag might be small enough to set it on both aircraft to "0". It's intended, that this is done automatically in the future.

The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.

* '''length:''' upstretched length in metres

* '''break-force:''' in N

* '''mp-auto-connect-period:''' the every x seconds a towed multiplayer aircraft is searched. If found, this tow is connected automatically, parameters are copied from the other aircraft. Should be set only in the motor aircraft, not in the glider

The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.

* '''max-tow-length:''' in m

* '''max-force:''' in N

[[File:Yasim_visualisation_dc6.png|thumb|dc6 fdm in Blender]]To make the programmed aircraft visible it is possible to load and compare it with the 3D model within [[Blender]]. The applaud for this ''very'' usefull script goes to M. Franz, thank you very much!

A note about step (0) for Windows users: the mentioned path is inside the folder where Blender lives, something like <code>C:\Program Files\Blender Foundation\Blender\.blender\scripts</code>.

By use of a standard command line, we can see what the YASim solver is calculating. First, open up a command line prompt, and enter in the location of YASim.exe, and then the location of the YASim xml file. For example, here's what you would type in for a standard Windows 32-bit installation, and viewing the [[Boeing 777-200ER]]'s YASim file.

* '''CG:''' Center of gravity of the aircraft in coordinates. Unless it's supposed to be offset, it should always have a Y value of 0.

The YASim standalone solver also has some command line flags that change it's behaviour.

<code>"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\777-200\777-200ER.xml" -g -a 1000 -s 150</code>

Andy Ross's original design notes for YASim can be found in [ftp://ftp.uni-duisburg.de/FlightGear/Docs/YASim-simnotes.pdf this PDF file]. These provide some useful background for how YASim works.

{{FDM}}