Howto:Modelling hydrodynamics in JSBSim

From FlightGear wiki
Revision as of 19:20, 13 October 2016 by AndersG (talk | contribs) (→‎Examples)
Jump to navigation Jump to search

Introduction

This page intends to describe how to model hydrodynamic forces and moments in JSBSim (i.e. how things interact with water). It is based around JSBSim external forces and a couple of generic systems for JSBSim that are available in FGData, namely hydrodynamics.xml, hydrodynamic-planing.xml and hydrodynamic-planing-floats.xml.

NOTE: These methods and systems are under active, but slow development, there are known and unknown bugs and inconsistencies present. Future developments may require changes in the per-aircraft files.

The hydrodynamics.xml system receives forces and moments due to the vessel's interaction with water, both hydrostatic and hydrodynamic, defined with respect to the hydrodynamic reference point (HRP) in a separate per-aircraft file and apply them to the vessel using external forces.

The coordinate frame used to define the forces and moments is similar to the body frame but is always aligned with the water surface which is assumed to be horizontal. Forces can also be defined in a horizontal "wind" frame.

NOTE: This is one point where there are known inconsistencies present (read: the coordinate frame definitions need to be sorted out). However, as long as pitch and heel angles are small this should not lead to major issues.

The forces are split into the channels

  • Fbx - body forward. (In the water plane?)
  • Fby - body right. (In the water plane?)
  • Fbz - local up (the same as -Z in the JSBSim local frame).
  • Drag - opposing the relative water flow. (In the water plane?)
  • Side - 90 degrees right from the relative water flow in the surface plane.

The moments are split into the hydrodynamic body frame channels (with the same sense as the normal body frame moments):

  • Pitch
  • Yaw
  • Roll

The properties determining the location and orientation of the vessel w.r.t the the water surface and stream are:

  • hydro/height-agl-ft - Height of the hydrodynamic reference point over the water surface.
  • hydro/beta-deg - angle between the vessel's velocity vector through the water and its longitudinal axis. Analogous to aerodynamics/beta-deg.
  • hydro/pitch-deg - angle between the vessel longitudinal axis and the water surface (ground plane).
  • hydro/roll-deg - angle between the vessel traverse axis and the water surface (ground plane).
  • hydro/v-fps - The vessel's total speed relative the water.

Basic usage

Include the hydrodynamics.xml system in your vessel/aircraft.

Define the following properties in a system of your aircraft:

  • Hydrodynamics reference point:
    <property value="...">metrics/hydro-rp-x-in</property>
    <property value="...">metrics/hydro-rp-y-in</property>
    <property value="...">metrics/hydro-rp-z-in</property>
  • Functions computing the forces in the hydrodynamic body frame
   - hydro/fbx-lbs
   - hydro/fby-lbs
   - hydro/fbz-lbs

Alternative force inputs in the water frame

   - hydro/fdrag-lbs
   - hydro/fside-lbs

Unused properties also have to be declared (and set to zero).

  • Functions computing the moments in the hydrodynamic body frame. FIXME: Yaw is applied in the standard body frame.
   - hydro/yaw-moment-lbsft
   - hydro/pitch-moment-lbsft
   - hydro/roll-moment-lbsft

Define the following external forces in the main FDM file of your aircraft, they will be used to apply the hydrodynamic forces and moments to the vessel:

    <force name="hydro-X" frame="LOCAL">
     <location unit="M">
      { HRP }
     </location>
     <direction>
      <x> 1.0 </x>
      <y> 0.0 </y>
      <z> 0.0 </z>
     </direction>
    </force>
    <force name="hydro-Y" frame="LOCAL">
     <location unit="M">
      { HRP }
     </location>
     <direction>
      <x> 0.0 </x>
      <y> 1.0 </y>
      <z> 0.0 </z>
     </direction>
    </force>
    <force name="hydro-Z" frame="LOCAL">
     <location unit="M">
      { HRP }
     </location>
     <direction>
      <x> 0.0 </x>
      <y> 0.0 </y>
      <z>-1.0 </z>
     </direction>
    </force>

    <force name="hydro-pitch[0]" frame="LOCAL">
     <location unit="M">
      <x> HRP X - 0.3048 </x>
      <y> HRP Y </y>
      <z> HRP Z </z>
     </location>
     <direction>
      <x> 0.0 </x>
      <y> 0.0 </y>
      <z>-1.0 </z>
     </direction>
    </force>
    <force name="hydro-pitch[1]" frame="LOCAL">
     <location unit="M">
      <x> HRP X + 0.3048 </x>
      <y> HRP Y </y>
      <z> HRP Z </z>
     </location>
     <direction>
      <x> 0.0 </x>
      <y> 0.0 </y>
      <z>-1.0 </z>
     </direction>
    </force>

    <force name="hydro-yaw[0]" frame="BODY">
     <location unit="M">
      <x> HRP X </x>
      <y> HRP Y - 0.3048 </y>
      <z> HRP Z </z>
     </location>
     <direction>
      <x> 1.0 </x>
      <y> 0.0 </y>
      <z> 0.0 </z>
     </direction>
    </force>
    <force name="hydro-yaw[1]" frame="BODY">
     <location unit="M">
      <x> HRP X </x>
      <y> HRP Y + 0.3048 </y>
      <z> HRP Z </z>
     </location>
     <direction>
      <x> 1.0 </x>
      <y> 0.0 </y>
      <z> 0.0 </z>
     </direction>
    </force>

    <force name="hydro-roll[0]" frame="LOCAL">
     <location unit="M">
      <x> HRP X </x>
      <y> HRP Y - 0.3048 </y>
      <z> HRP Z </z>
     </location>
     <direction>
      <x> 0.0 </x>
      <y> 0.0 </y>
      <z>-1.0 </z>
     </direction>
    </force>
    <force name="hydro-roll[1]" frame="LOCAL">
     <location unit="M">
      <x> HRP X </x>
      <y> HRP Y + 0.3048 </y>
      <z> HRP Z </z>
     </location>
     <direction>
      <x> 0.0 </x>
      <y> 0.0 </y>
      <z>-1.0 </z>
     </direction>
    </force>

Examples

Examples by the author of the generic systems:

Other aircraft