# JSBSim Aerodynamics

JSBSim provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the JSBSim framework, and how to create FDMs that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the JSBSim sense of the output of a function derived from a coefficient.

JSBSim provides three Forces and three Moments (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

## Frames

JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.

**Body XYZ**The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being down. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

**Wind XYZ**The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

**Wind UVW**This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

## Angles

These two angles define the direction the relative wind is blowing in regard to the body frame.

**Alpha**Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in JSBSim.**Beta**Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

## QBar

QBar, or dynamic pressure, is the product of velocity^2*(air density)/2

**QBarUW**Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane airspeed components contribution.**QBarUV**Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane airspeed components contribution.- It is possible to calculate other dynamic pressures for special purposes, such as QBarU for control surfaces.

The Greek letter rho or "ρ" is commonly used for air density. Normally, Qbar is based on the total free stream velocity, V[∞], so:

**qbar = 1/2*ρ*(V[∞])^2**

V[∞] is a vector and can be broken down into components commonly called U, V, W. By definition, U, V, and W are all at right angle to each other, so we use Pythagoras to say:

**(V[∞])^2 = U^2 + V^2 + W^2**

and rewrite

**qbar = 1/2*ρ*(U^2 + V^2 + W^2)**

QbarUV drops the vertical component, W, and just uses:

**qbarUV = 1/2*ρ*(U^2 + V^2)**

QbarUW drops the horizontal component and just uses:

**qbarUW = 1/2*ρ*(U^2 + W^2)**

And for the special case of qbarU, only use the axial component.

**qbarU = 1/2*rho*(U^2)**

Since its one dimensional, preserving the sign to show direction is valid:

**qbarU = 1/2*ρ*(U*abs(U))**

Qbar, qbarUV and qbarUW, can not have signs because they are multidimensional, use the reported alpha or beta angles to decide where the pressure is coming from.

## Metrics

The metrics section provides a standard place to record common aircraft dimensions. Aeromatic built FDMs only use four of the defined properties.

- Wing Area - metrics/Sw-sqft
- Wing Span - metrics/bw-ft
- Wing Chord - metrics/cbarw-ft
- AeroRP - the location where the aerodynamic forces are applied to the model. If this location is not exactly equal to the center of gravity (CoG) then moments, or twisting forces, will be created. Conventional aircraft need AeroRP to be aft of the CoG for stability.

Other dimensions Aeromatic creates but does not use are: (tail arms are used by the JSBSim Turbulence code)

- Horizontal Tail Area - Sh-sqft
- Horizontal Tail Arm - lh-ft
- Vertical Tail Area - Sv-sqft
- Vertical Tail Arm - lv-ft

Other elements in metrics:

- EYEPOINT - where G-forces are computed for the pilot
- VRP - the world position reported by JSBSim to FlightGear is for this location in the structural frame. Hence, the VRP location should match the origin of the coordinate system(s) used to position views, sounds and the 3d model in the FlightGear XML files.

```
<metrics>
<wingarea unit="{FT2 | M2}"> {number} </wingarea>
<wingspan unit="{FT | M}"> {number} </wingspan>
<chord unit="{FT | M}"> {number} </chord>
<htailarea unit="{FT2 | M2}"> {number} </htailarea>
<htailarm unit="{FT | M}"> {number} </htailarm>
<vtailarea unit="{FT2 | M}"> {number} </vtailarea>
<vtailarm unit="{FT | M}"> {number} </vtailarm>
<wing_incidence unit="{RAD | DEG}"> {number} </wing_incidence>
<pitot_angle unit="{RAD | DEG}"> {number} </pitot_angle>
<location name="{AERORP | EYEPOINT | VRP}" unit="{IN | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
{other location blocks}
</metrics>
```

## Forces

For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable FDM, is the Normal, Axial, Side method.

**Lift: CL**Lift is the portion of the aerodynamic force that is at a right angle to the relative wind**and**lies within the x-z-axis plane (usually the aircraft's symmetry plane)**and**is oriented towards the aircraft's upside. (During inverted flight, it points to the ground).- Lift is a function of QBar * Wing Area * Cl
_{lift}. Cl_{lift}is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers. At least for unswept wings, using**QBarUW**is more appropriate for CL than the generic QBar. Otherwise, your aircraft will likely be prone to the issue Pitch oscillations at rest, Brakes ON, with pure crosswind. Swept wings might need a different treatment that we have not investigated further.*However this has only been tested for the particular case of the c172, these are not universal laws but rather guidance or at the very least trouble shooting.*

- Lift is a function of QBar * Wing Area * Cl
**Drag: CD**Drag is the portion of the aerodynamic force that is parallel to the relative wind.- It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.

**Side: CY**Side is the portion of the aerodynamic force that is at a right angle to both the Lift and the Drag vector. It usually points to the aircraft's right side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it may become ambiguous which direction the forces are applied. If an aircraft's body-x-axis is oriented exactly perpendicular to the relative wind, the definitions given above cannot be applied.

Enter the Axial, Normal, Side system.

**Axial: CA**Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.**Normal: CN**Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.**Side: CY**Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

## Moments

**Roll: Cl**Aerodynamic rolling moment comes from multiple sources:- One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
- Another roll moment source is main wing dihedral angle. If a dihedral wing encounters a sidewind component, let's say from the right, then the effective angle of attack will slightly increase for the right wing and decrease for the left wing. This is because - from the wing's perspective - the side wind component approaches the right wing from below (leading to an increase in AOA and more lift) and the left wing from above (leading to a decrease in AOA and less lift). Rolling the aircraft to one side will induce a side motion which leads to a resulting difference in lift, creating a roll moment counteracting the initial roll angle and providing roll stability.

**Pitch: Cm**The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. At least for unswept wings, using**QBarUW**is more appropriate for Cm than the generic QBar. Otherwise, your aircraft will likely be prone to the issue Pitch oscillations at rest, Brakes ON, with pure crosswind. Swept wings might need a different treatment that we have not investigated further.*However this has only been tested for the particular case of the c172, these are not universal laws but rather guidance or at the very least trouble shooting.***Yaw: Cn**The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUV is more appropriate for Cn than the generic QBar.

## Effects

**Stall**- A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.

```
<hysteresis_limits unit="{RAD | DEG}">
<min> {number} </min>
<max> {number} </max>
</hysteresis_limits>
```

**Spin**- Spins are caused loss of stability in the Yaw Moment axis. A stock Aeromatic FDM yaw section does not take alpha into account when calculating the yaw moment.**Aerodynamic Reference Point**- JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.

```
<aero_ref_pt_shift_x>
<function>
{function contents}
</function>
</aero_ref_pt_shift_x>
```

**Lift Due To Elevator**- There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.