Howto:Modelling hydrodynamics in JSBSim

From FlightGear wiki
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>

Generating hydrostatic buoyancy coefficients

To make something float with the hydrodynamics system the buoyancy forces and moments need to be computed and then input to the generic part of the system as shown above. One way to compute these forces and moments is to generate buoyancy coefficients as functions of (read: tables indexed by) the position and orientation of the vessel/aircraft relative to the surface of the water it floats on.

'To be continued... for now, see the MFI-9B development repository. '

One Gerris buoyancy case for a float of the MFI-9B float-plane visualized in the Gerris gfsview3d tool. The water line is at the edge of the dark blue colour. It looks curved due to the various levels of cell refinement over the domain.

Modelling hydrodynamic coefficients

The hydrostatic coefficients described above allow the vessel to float, so the next problem is to make it move through the water. Starting with drag there are different modes of movement on the water, namely

  • displacement, the vessel pushing through the water;
  • planing, the vessel skimming along the surface of the water pushing down on it rather than through it; and
  • semi-planing, a mix of the above.

For a non-planing vessel the drag is roughly proportional to the square of the speed through the water while a planing vessel has much more complicated drag function as it goes through displacement, semi-planing and planing phases as speed increases.

As an example consider the plot below of the towing power (drag times velocity) of a Swedish Navy T21 class MTB as speed increases from 0 to nearly 60 knots. The blue line is from a real tow tank test ("Resultat av släpförsök med svenska patent nr. 109626", A. F. Nordström, Statens Skeppsprovningsanstalt, Göteborg, 1941-10-01) and shows the complex shape of the drag function. One can guess that the curve up to about 10 knots is mostly due to quadratic displacement drag. Above this speed the vessel enters the planing phase and the displacement is reduced as more and more of the weight is supported by the planing forces. This reduces the increase in drag considerably. Finally, from about 38 knots and over another quadratic growth phase takes over. My hypothesis is that this phase is due to the rudders that remain in the water and ought to have (from standard fluid dynamics) a rather small but quadratic drag function.

Hydrodynamic drag of a MTB after ad hoc tuning. Total (green) and parts, displacement (red), planing (cyan) and rudder assembly (purple), of the hydrodynamic drag of the Swedish Navy T21 class MTB from a single acceleration run in JSBSim/standalone. The blue line is a real tow tank result traced from a diagram in "Resultat av släpförsök med svenska patent nr. 109626", A. F. Nordström, Statens Skeppsprovningsanstalt, Göteborg, 1941-10-01 available as an image (ID 2008:25:869:1) from Sjöhistoriska museet under CC BY-SA.

'To be continued... '

Examples

Examples by the author of the generic systems:

Other aircraft