|
FhSim
3.1.0
Marine systems simulation
|
|
|
FhSim
3.1.0
Marine systems simulation
|
Six degree-of-freedom rigid body for a torpedo-shaped survey AUV.
Collaboration diagram for Autonomous underwater vehicle:A survey AUV modelled as a rigid cylinder in six degrees of freedom, carrying a battery state. The state layout, the constant diagonal mass matrix, the flow frame → AddXxxForces into one wrench → derivatives pipeline (fhsim_base's HydroBody) and the FinalSetup environment lookup all follow TrawlDoorBase, so a reader who knows the trawl door knows this file.
The hull is idealised as a solid cylinder of uniform density. Length, Diameter and AverageDensity are the only geometric parameters; the volume, the mass and the inertia are derived from them, so displacement, mass and inertia cannot be configured into an inconsistent combination and the buoyancy trim is the single number AverageDensity:
\begin{eqnarray*} r &=& \frac{D}{2} \\ \nabla &=& \pi r^2 L \\ m &=& \rho_{avg} \nabla \\ I_{xx} &=& \frac{1}{2} m r^2 \\ I_{yy} = I_{zz} &=& \frac{m (3 r^2 + L^2)}{12} \end{eqnarray*}
With the defaults (2.0 m by 0.20 m at 1020 kg/m³ in 1025 kg/m³ water) the vehicle has about 0.31 kg of net buoyancy, so a dead vehicle surfaces.
The mass matrix \(M = \mathrm{diag}(m + A_{11}, \ldots, I_{zz} + A_{66})\) is assembled and inverted once, in the constructor. It stays diagonal because the body origin is placed at the centre of buoyancy and the centre of gravity is carried as the offset COG, whose only effect is a moment.
The weight acts at COG and is the entire pitch and roll restoring model. The buoyancy is \(\rho g \nabla f\) applied at the body origin, where \(f\) is the submerged fraction. Because the hull is a cylinder, \(f\) is the exact circular-segment area of a horizontal cylinder rather than the ad-hoc linear ramp used by TrawlDoorBase, so surfacing is \(C^1\): \(f = F(d/r)\) with \(d\) the depth of the axis below the surface and \(F\) environment::body_submergence::CircleWetFraction (fhsim_environment).
The thruster delivers \(T = k_T\,\mathrm{clamp}(P_{cmd}, 0, P_{max})\) along body x at ThrusterPos, so a thruster placed off the x axis produces a moment as well. The model is deliberately speed independent: real thrust at fixed shaft power falls with speed, and ThrustPerPower is calibrated at the cruise point rather than being a propeller curve. Because thrust is linear in propulsion power and independent of surge speed, accelerations from rest and speeds away from cruise are overestimated. ComputeThrust() is virtual so that a bollard-pull blend can replace it later without touching any caller.
The hull load is the sum of the axial drag, the cross-flow strip theory, the slender-body lift, the roll damping and the two fin planes. It comes from the module auv_hull in AuvHullLaw.h (auv_hull::AddHullLoad), and the wake caster uses the same step. See there for the laws, their formulas and the fin sign convention.
A vehicle whose COG is too far below the centre of buoyancy simply cannot dive: the righting moment beats the fin moment at every reachable angle, and the symptom is a vehicle that flies level and a dive autopilot stuck at its integrator limit. The constructor therefore warns when
\[ A_{fin}\, q_{dyn}\, C_{l,max}\, |x_{fin}| \le m g |COG_z| \sin(\mathrm{DiveAngle}), \]
naming both assumptions it had to make in the message, because neither belongs to this class:
DiveAngleForAuthorityCheck, defaulting to the 0.349 rad that AuvUndulateDiveControl defaults to;MaxPropulsionPower, which is the design cruise point of the suggested parameter set (30 W of 120 W, giving 1.5 m/s).The check uses RudderClMax, which is the peak of the lift curve and is reached at RudderAoaMax, not at MaxRudderAngle. Since MaxRudderAngle is deliberately inside the stall, the attainable coefficient is about 0.9 of RudderClMax, and the check is correspondingly optimistic by that much. It is written that way on purpose: it is a necessary condition, so it never warns about a vehicle that can in fact dive.
The battery discharges at the clamped propulsion power plus the constant HotelPower while it holds any energy, and stops — rather than going negative — when it is flat. A flat battery also stops the thrust. The discharge is driven by an input port and by the sign of the battery state alone, so the whole battery row of the Jacobian is identically zero, exactly as in Actuator.
With CastWake the vehicle casts its hull wake and a propeller jet together (feature propeller-jet, owner rulings O12a, O13a, O14a), through an environment::wake::BodyFlowInteraction of a self-propelled body (fhsim_environment doc/user/wakes.md, "A self-propelled body"; the jet law is marenv doc/wake.md § 4.2); the wake parameters are those of fhsim_environment's doc/user/wake-parameters.md. Default CastWake is false: the vehicle casts nothing and its results are unchanged.
ThrusterPos, the shaft along body x, diameter PropellerDiameter (default 0.6 Diameter). Its effective thrust is the thrust of the unchanged law, ComputeThrust() of the clamped ThrustPower (zero with a flat battery), since the vehicle has no thrust deduction (t = 0); the command is the one at the step's start (PreOdeFcn). The advance speed is the surge through the water at the body origin: the current with the other objects' wakes and jets, without the waves.In steady cruise thrust balances that drag, so the far field carries about no momentum: the jet's excess cancels the hull wake's deficit in the integral (Auv_SteadyCruiseFarFieldIsMomentumless).
The vehicle reads its water velocity through the BodyFlowInteraction, in OdeFcn, OdeJacobian, InputPortJacobian and the Speed output alike: the current with every other object's wake and jet, never its own (D3), plus the waves. It meets the other objects' wakes with or without CastWake. With the default ExternalWakeUpdate="Step" they are taken once per step at the vehicle's position at the step's start and held for the step, a field whose effect stays below the cutoff dropped; with ExternalWakeUpdate="Evaluation" the vehicle reads the live flow.
AddedMass, v_w the water velocity in the body frame and v_r = v − v_w (owner rulings R100, FISH-0093, R106, R107, R112 and R113; Fossen 2011, ch. 3, 6 and 10; rigid_body::OmegaTermsWrench). A turning vehicle keeps its velocity over ground and develops the sideslip of a turn; one carried by a uniform current at zero relative velocity keeps drifting with it, whatever its added mass. The added-mass matrix is diagonal, so the coupling terms of a hull whose origin is not at mid-length are absent.RudderYaw and RudderDive take effect within the step they are commanded.ThrusterPos, both on the schedule of the wake parameters. The jet's thrust is the speed-independent law above (FISH-0033), so the jet of a vehicle accelerating from rest is too strong. The vehicle cannot cast with a WakeGroup.All four input ports must be connected; a constant is the usual choice while the control stack is not yet wired:
| Name | Width | Description |
|---|---|---|
| ThrustPower | 1 | Commanded propulsion power [W], clamped to [0, MaxPropulsionPower] before it is used. |
| RudderYaw | 1 | Commanded deflection of the fin pair that turns the vehicle in the horizontal plane [rad], that is the pair whose chord lies in the body x-y plane. Named by effect, not by fin plane. A positive command gives a positive yaw rate, that is a turn to starboard. Clamped to plus or minus MaxRudderAngle. |
| RudderDive | 1 | Commanded deflection of the fin pair that pitches the vehicle in the vertical plane [rad], that is the stern planes, whose chord lies in the body x-z plane. Named by effect, not by fin plane. A positive command gives a nose-down, that is negative, pitch moment and therefore a dive. Clamped to plus or minus MaxRudderAngle. |
| ExternalForce | 3 | An external force in the NED frame [N], applied at the body origin and therefore contributing no moment. |
| Name | Width | Description |
|---|---|---|
| Pos | 3 | Position of the body origin in NED [m]. |
| Vel | 3 | Velocity of the body origin in NED [m/s]. |
| Quater | 4 | Attitude quaternion, scalar first [q0, q1, q2, q3]. |
| Euler | 3 | Roll, pitch and yaw [rad], from the ZYX convention. |
| Heading | 1 | Yaw angle [rad], the third element of Euler. |
| Pitch | 1 | Pitch angle [rad], the second element of Euler. Positive is nose up. |
| Depth | 1 | Depth below the mean free surface [m], positive down. |
| Speed | 1 | Forward speed through the water [m/s], the body-x component of the velocity relative to the fluid. This, not the speed over ground and not the magnitude of the velocity, is what a speed autopilot regulates. |
| Altitude | 1 | Height of the body origin above the seafloor [m]. |
| SeaDepth | 1 | Depth of the seafloor below the surface at the vehicle position [m]. |
| Battery | 1 | Remaining battery energy [J]. |
| BatteryFraction | 1 | Remaining battery energy as a fraction of InitialBattery. |
| Thrust | 1 | The thrust actually delivered along body x [N], which is zero while the battery is flat. |
| Name | Width | Description |
|---|---|---|
| Length | 1 | Hull length [m] (Default: 2.0). |
| Diameter | 1 | Hull diameter [m] (Default: 0.20). |
| AverageDensity | 1 | Mean density of the whole vehicle [kg/m³] (Default: 1020). Below Rho the vehicle is positively buoyant. This one number is the buoyancy trim. |
| Rho | 1 | Density of the sea water [kg/m³] (Default: 1025). |
| COG | 3 | Centre of gravity in the body frame [m], relative to the centre of buoyancy at the origin (Default: "0,0,0.020"). The vertical component is the entire pitch and roll restoring model. |
| AddedMass | 6 | Added mass and added inertia on the diagonal, [A11, A22, A33, A44, A55, A66] in kg and kg·m² (Default: "3.2, 58, 58, 0.1, 19, 19"). A44 is floored well above zero so that the mass matrix stays invertible for a body of revolution. |
| ThrustPerPower | 1 | Thrust delivered per watt of propulsion power [N/W] (Default: 0.30). Calibrated at the cruise point, 9.0 N from 30 W. |
| MaxPropulsionPower | 1 | The largest propulsion power the thruster accepts [W] (Default: 120, four times cruise). Commands are clamped to [0, this]. |
| HotelPower | 1 | The constant payload, computer and navigation load [W] (Default: 15). It is drawn whenever the battery holds any energy. |
| ThrusterPos | 3 | Position of the thruster in the body frame [m] (Default: "-1.0, 0, 0"). An axial thruster on the x axis contributes no moment, but the moment is computed anyway so that an offset thruster stays correct. |
| AxialDragCoeff | 1 | Hull drag coefficient on the frontal area pi D²/4 [-] (Default: 0.25). Gives 9.0 N at 1.5 m/s, which matches published REMUS-class drag. |
| CrossFlowDragCoeff | 1 | Two-dimensional cross-flow drag coefficient of a hull section [-] (Default: 1.2, the normal drag coefficient of the environment cylinder law). Set it to zero to remove the viscous cross-flow drag; the slender-body hull lift and the Munk moment stay. |
| SectionX | 3 | Body-frame x of the centroid of each strip-theory section [m] (Default: Length/3, 0, -Length/3, that is the centroids of three equal thirds). |
| SectionDiameter | 3 | Cross-flow diameter of each section [m] (Default: Diameter for all three). Override it together with SectionLength to taper a non-cylindrical hull; the defaults are the cylinder the rest of the class assumes. The aftmost section's diameter is also the base of the slender-body hull lift. |
| SectionLength | 3 | Length of each section [m] (Default: Length/3 for all three). The sum is not forced to equal Length, so a tapered hull can leave gaps or overlap. |
| RollDampingLinear | 1 | Linear roll damping [N·m·s] (Default: 4.6, chosen to critically damp the 12.6 N·m/rad roll mode of the default trim). Strip theory contributes nothing about the x axis, so this term and RollDampingQuadratic are the whole roll damping. |
| RollDampingQuadratic | 1 | Quadratic roll damping [N·m·s²] (Default: 1.0). |
| RudderArea | 1 | Planform area of one fin plane [m²] (Default: 0.016, that is two 0.10 by 0.08 m fins). Set it to zero to remove the fins entirely, which is what the hull-only regression inputs do. |
| RudderAspectRatio | 1 | Aspect ratio of a fin [-] (Default: 1.25). It enters the induced drag alone, not the lift curve. |
| RudderPos | 3 | Position of both fin planes in the body frame [m] (Default: "-0.85, 0, 0"). Both the force and the moment act here, so moving the fins aft increases the control moment in proportion. |
| RudderClMax | 1 | Peak lift coefficient of a fin [-] (Default: 0.8). |
| RudderAoaMax | 1 | Angle of attack at which the peak lift is reached [rad] (Default: 0.436, that is 25 degrees). The lift curve is C1 through this angle, by construction; see AuvFoil. |
| RudderCd0 | 1 | Profile drag coefficient of a fin at zero lift [-] (Default: 0.02). |
| RudderOswald | 1 | Oswald span efficiency of the fin induced drag [-] (Default: 0.9). |
| MaxRudderAngle | 1 | Mechanical stop on the commanded deflection [rad] (Default: 0.35, that is 20 degrees, inside the 25 degree stall). Commands are clamped to plus or minus this before the flow angle is added. |
| DiveAngleForAuthorityCheck | 1 | The dive angle the startup dive-authority warning is evaluated at [rad] (Default: 0.349, that is 20 degrees, the default DiveAngle of AuvUndulateDiveControl). It is a parameter because the dive angle belongs to the dive controller, not to the vehicle, so hard-coding it would make the warning unfalsifiable for a differently configured controller. Set it to zero to silence the check. |
| InitialBattery | 1 | Battery energy at the start of the mission [J] (Default: 1.8e6, that is 0.5 kWh). |
| CastWake | 1 | The vehicle casts its hull wake and propeller jet (see Wake); the other wake parameters (Wake*, ExternalWakeUpdate) are listed in fhsim_environment's doc/user/wake-parameters.md. (Default: false) |
| PropellerDiameter | 1 | Diameter of the propeller whose jet the vehicle casts [m], > 0; read only with CastWake. (Default: 0.6 Diameter) |
| Name | Width | Description |
|---|---|---|
| Pos | 3 | Position in NED [m] (Default: "0,0,0"). |
| Quater | 4 | Attitude quaternion, scalar first (Default: "1,0,0,0"). |
| LocalVel | 3 | Velocity in the body frame [m/s] (Default: "0,0,0"). |
| Omega | 3 | Angular velocity in the body frame [rad/s] (Default: "0,0,0"). |
| Battery | 1 | Battery energy [J] (Default: InitialBattery). |
AuvSurvey.xml is the whole stack in one model: the environment, this vehicle, the three PID loops that fly it, the dive and mission guidance and all three instruments. It is also the regression input tests/in/AuvSurvey/AuvSurvey_in.xml, byte for byte, so the example and the test cannot drift apart; AuvSurvey_Test asserts that they are identical. A co-simulation variant of the same scenario, with the FMU boundary added, is examples/input/FMU/AuvSurvey/model.xml.
This SimObject is referred to as Auv/Vehicle
1.9.8