Skip to content

Commit 29c13bf

Browse files
arjo129arjo129
authored
Document behaviour changes introduced #1784 (#1888)
* Document behaviour changes introduced #1784 The PR in #1784 claimed not to introduce behaviour changes, but actually ended up introducing behaviour changes. Specifically, it would break a lot of marine simulation code that runs on our tools. The issue in question is a matter of naming parameters. In the past `<xUU>` used to refer to the quadratic drag term in the diagonal axis. This term would be multiplied by the absolute velocity. After #1784 this term was multiplied by the velocity (no absolute). An equivalent term of `<xUabsU>` This behaviour change likely breaks all previous maritime simulations that rely on our hydrodynamics plugin. There are several options: 1. Revert #1784 2. Make `<xUU>` mirror `<xUabsU>` 3. Document the change and mark it as breaking. This PR goes with option 3 as there are already code bases using `<xUabsU>` nota tion instead of `<xUU>`. We also add a warning if someone does use the `<xUU>` term that points to this PR for details. Signed-off-by: Arjo Chakravarty <[email protected]>
1 parent a22e7f7 commit 29c13bf

File tree

7 files changed

+103
-80
lines changed

7 files changed

+103
-80
lines changed

‎examples/worlds/auv_controls.sdf

+6-6
Original file line numberDiff line numberDiff line change
@@ -147,17 +147,17 @@
147147
<kDotP>0</kDotP>
148148
<mDotQ>-33.46</mDotQ>
149149
<nDotR>-33.46</nDotR>
150-
<xUU>-6.2282</xUU>
150+
<xUabsU>-6.2282</xUabsU>
151151
<xU>0</xU>
152-
<yVV>-601.27</yVV>
152+
<yVabsV>-601.27</yVabsV>
153153
<yV>0</yV>
154-
<zWW>-601.27</zWW>
154+
<zWabsW>-601.27</zWabsW>
155155
<zW>0</zW>
156-
<kPP>-0.1916</kPP>
156+
<kPabsP>-0.1916</kPabsP>
157157
<kP>0</kP>
158-
<mQQ>-632.698957</mQQ>
158+
<mQabsQ>-632.698957</mQabsQ>
159159
<mQ>0</mQ>
160-
<nRR>-632.698957</nRR>
160+
<nRabsR>-632.698957</nRabsR>
161161
<nR>0</nR>
162162
</plugin>
163163

‎examples/worlds/multi_lrauv_race.sdf

+18-18
Original file line numberDiff line numberDiff line change
@@ -145,17 +145,17 @@
145145
<kDotP>0</kDotP>
146146
<mDotQ>-33.46</mDotQ>
147147
<nDotR>-33.46</nDotR>
148-
<xUU>-6.2282</xUU>
148+
<yUabsU>-6.2282</yUabsU>
149149
<xU>0</xU>
150-
<yVV>-601.27</yVV>
150+
<yVabsV>-601.27</yVabsV>
151151
<yV>0</yV>
152-
<zWW>-601.27</zWW>
152+
<zWabsW>-601.27</zWabsW>
153153
<zW>0</zW>
154-
<kPP>-0.1916</kPP>
154+
<kPabsP>-0.1916</kPabsP>
155155
<kP>0</kP>
156-
<mQQ>-632.698957</mQQ>
156+
<mQabsQ>-632.698957</mQabsQ>
157157
<mQ>0</mQ>
158-
<nRR>-632.698957</nRR>
158+
<nRabsR>-632.698957</nRabsR>
159159
<nR>0</nR>
160160
</plugin>
161161

@@ -239,17 +239,17 @@
239239
<kDotP>0</kDotP>
240240
<mDotQ>-33.46</mDotQ>
241241
<nDotR>-33.46</nDotR>
242-
<xUU>-6.2282</xUU>
242+
<yUabsU>-6.2282</yUabsU>
243243
<xU>0</xU>
244-
<yVV>-601.27</yVV>
244+
<yVabsV>-601.27</yVabsV>
245245
<yV>0</yV>
246-
<zWW>-601.27</zWW>
246+
<zWabsW>-601.27</zWabsW>
247247
<zW>0</zW>
248-
<kPP>-0.1916</kPP>
248+
<kPabsP>-0.1916</kPabsP>
249249
<kP>0</kP>
250-
<mQQ>-632.698957</mQQ>
250+
<mQabsQ>-632.698957</mQabsQ>
251251
<mQ>0</mQ>
252-
<nRR>-632.698957</nRR>
252+
<nRabsR>-632.698957</nRabsR>
253253
<nR>0</nR>
254254
</plugin>
255255

@@ -333,17 +333,17 @@
333333
<kDotP>0</kDotP>
334334
<mDotQ>-33.46</mDotQ>
335335
<nDotR>-33.46</nDotR>
336-
<xUU>-6.2282</xUU>
336+
<yUabsU>-6.2282</yUabsU>
337337
<xU>0</xU>
338-
<yVV>-601.27</yVV>
338+
<yVabsV>-601.27</yVabsV>
339339
<yV>0</yV>
340-
<zWW>-601.27</zWW>
340+
<zWabsW>-601.27</zWabsW>
341341
<zW>0</zW>
342-
<kPP>-0.1916</kPP>
342+
<kPabsP>-0.1916</kPabsP>
343343
<kP>0</kP>
344-
<mQQ>-632.698957</mQQ>
344+
<mQabsQ>-632.698957</mQabsQ>
345345
<mQ>0</mQ>
346-
<nRR>-632.698957</nRR>
346+
<nRabsR>-632.698957</nRabsR>
347347
<nR>0</nR>
348348
</plugin>
349349

‎src/systems/hydrodynamics/Hydrodynamics.cc

+19-1
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,8 @@ void Hydrodynamics::Configure(
183183
// Use SNAME 1950 convention to load the coeffecients.
184184
const auto snameConventionVel = "UVWPQR";
185185
const auto snameConventionMoment = "xyzkmn";
186+
187+
bool warnBehaviourChange = false;
186188
for(auto i = 0; i < 6; i++)
187189
{
188190
for(auto j = 0; j < 6; j++)
@@ -193,11 +195,17 @@ void Hydrodynamics::Configure(
193195
SdfParamDouble(_sdf, prefix, 0);
194196
for(auto k = 0; k < 6; k++)
195197
{
198+
auto fieldName = prefix + snameConventionVel[k];
196199
this->dataPtr->stabilityQuadraticDerivative[i*36 + j*6 + k] =
197200
SdfParamDouble(
198201
_sdf,
199-
prefix + snameConventionVel[k],
202+
fieldName,
200203
0);
204+
205+
if (_sdf->HasElement(fieldName)) {
206+
warnBehaviourChange = true;
207+
}
208+
201209
this->dataPtr->stabilityQuadraticAbsDerivative[i*36 + j*6 + k] =
202210
SdfParamDouble(
203211
_sdf,
@@ -207,6 +215,16 @@ void Hydrodynamics::Configure(
207215
}
208216
}
209217

218+
219+
if (warnBehaviourChange)
220+
{
221+
ignwarn << "You are using parameters that may cause instabilities "
222+
<< "in your simulation. If your simulation crashes we recommend "
223+
<< "renaming <xUU> -> <xUabsU> and likewise for other axis "
224+
<< "for more information see:" << std::endl
225+
<< "\thttps://github.com/gazebosim/gz-sim/pull/1888" << std::endl;
226+
}
227+
210228
// Added mass according to Fossen's equations (p 37)
211229
this->dataPtr->Ma = Eigen::MatrixXd::Zero(6, 6);
212230
for(auto i = 0; i < 6; i++)

‎src/systems/hydrodynamics/Hydrodynamics.hh

+12-7
Original file line numberDiff line numberDiff line change
@@ -51,17 +51,17 @@ namespace systems
5151
/// * <kDotP> - Added mass in roll direction [kgm^2]
5252
/// * <mDotQ> - Added mass in pitch direction [kgm^2]
5353
/// * <nDotR> - Added mass in yaw direction [kgm^2]
54-
/// * <xUU> - Quadratic damping, 2nd order, x component [kg/m]
54+
/// * <xUabsU> - Quadratic damping, 2nd order, x component [kg/m]
5555
/// * <xU> - Linear damping, 1st order, x component [kg]
56-
/// * <yVV> - Quadratic damping, 2nd order, y component [kg/m]
56+
/// * <yVabsV> - Quadratic damping, 2nd order, y component [kg/m]
5757
/// * <yV> - Linear damping, 1st order, y component [kg]
58-
/// * <zWW> - Quadratic damping, 2nd order, z component [kg/m]
58+
/// * <zWabsW> - Quadratic damping, 2nd order, z component [kg/m]
5959
/// * <zW> - Linear damping, 1st order, z component [kg]
60-
/// * <kPP> - Quadratic damping, 2nd order, roll component [kg/m^2]
60+
/// * <kPabsP> - Quadratic damping, 2nd order, roll component [kg/m^2]
6161
/// * <kP> - Linear damping, 1st order, roll component [kg/m]
62-
/// * <mQQ> - Quadratic damping, 2nd order, pitch component [kg/m^2]
62+
/// * <mQabsQ> - Quadratic damping, 2nd order, pitch component [kg/m^2]
6363
/// * <mQ> - Linear damping, 1st order, pitch component [kg/m]
64-
/// * <nRR> - Quadratic damping, 2nd order, yaw component [kg/m^2]
64+
/// * <nRabsR> - Quadratic damping, 2nd order, yaw component [kg/m^2]
6565
/// * <nR> - Linear damping, 1st order, yaw component [kg/m]
6666
/// ### Cross terms
6767
/// In general we support cross terms as well. These are terms which act on
@@ -72,7 +72,12 @@ namespace systems
7272
/// and yaw axis respectively.
7373
/// * Added Mass: <{x|y|z|k|m|n}Dot{U|V|W|P|Q|R}> e.g. <xDotR>
7474
/// Units are either kg or kgm^2 depending on the choice of terms.
75-
/// * Quadratic Damping: <{x|y|z|k|m|n}{U|V|W|P|Q|R}{U|V|W|P|Q|R}>
75+
/// * Quadratic Damping With abs term (this is probably what you want):
76+
/// <{x|y|z|k|m|n}{U|V|W|P|Q|R}abs{U|V|W|P|Q|R}>
77+
/// e.g. <xRabsQ>
78+
/// Units are either kg/m or kg/m^2.
79+
/// * Quadratic Damping (could lead to unwanted oscillations):
80+
/// <{x|y|z|k|m|n}{U|V|W|P|Q|R}{U|V|W|P|Q|R}>
7681
/// e.g. <xRQ>
7782
/// Units are either kg/m or kg/m^2.
7883
/// * Linear Damping: <{x|y|z|k|m|n}{U|V|W|P|Q|R}>. e.g. <xR>

‎test/worlds/hydrodynamics.sdf

+24-24
Original file line numberDiff line numberDiff line change
@@ -104,17 +104,17 @@
104104
<kDotP>0</kDotP>
105105
<mDotQ>0</mDotQ>
106106
<nDotR>0</nDotR>
107-
<xUU>0</xUU>
107+
<xUabsU>0</xUabsU>
108108
<xU>0</xU>
109-
<yVV>0</yVV>
109+
<yVabsV>0</yVabsV>
110110
<yV>0</yV>
111-
<zWW>11.5359</zWW>
111+
<zWabsW>11.5359</zWabsW>
112112
<zW>0.211869</zW>
113-
<kPP>0</kPP>
113+
<kPabsP>0</kPabsP>
114114
<kP>0</kP>
115-
<mQQ>0</mQQ>
115+
<mQabsQ>0</mQabsQ>
116116
<mQ>0</mQ>
117-
<nRR>0</nRR>
117+
<nRabsR>0</nRabsR>
118118
<nR>0</nR>
119119
</plugin>
120120
</model>
@@ -163,17 +163,17 @@
163163
<kDotP>0</kDotP>
164164
<mDotQ>0</mDotQ>
165165
<nDotR>0</nDotR>
166-
<xUU>0</xUU>
166+
<xUabsU>0</xUabsU>
167167
<xU>0</xU>
168-
<yVV>0</yVV>
168+
<yVabsV>0</yVabsV>
169169
<yV>0</yV>
170-
<zWW>94.2475</zWW>
170+
<zWabsW>94.2475</zWabsW>
171171
<zW>0.0037699</zW>
172-
<kPP>0</kPP>
172+
<kPabsP>0</kPabsP>
173173
<kP>0</kP>
174-
<mQQ>0</mQQ>
174+
<mQabsQ>0</mQabsQ>
175175
<mQ>0</mQ>
176-
<nRR>0</nRR>
176+
<nRabsR>0</nRabsR>
177177
<nR>0</nR>
178178
</plugin>
179179
</model>
@@ -222,17 +222,17 @@
222222
<kDotP>0</kDotP>
223223
<mDotQ>0</mDotQ>
224224
<nDotR>0</nDotR>
225-
<xUU>0</xUU>
225+
<xUabsU>0</xUabsU>
226226
<xU>0</xU>
227-
<yVV>0</yVV>
227+
<yVabsV>0</yVabsV>
228228
<yV>0</yV>
229-
<zWW>94.2475</zWW>
229+
<zWabsW>94.2475</zWabsW>
230230
<zW>0.0037699</zW>
231-
<kPP>0</kPP>
231+
<kPabsP>0</kPabsP>
232232
<kP>0</kP>
233-
<mQQ>0</mQQ>
233+
<mQabsQ>0</mQabsQ>
234234
<mQ>0</mQ>
235-
<nRR>0</nRR>
235+
<nRabsR>0</nRabsR>
236236
<nR>0</nR>
237237
</plugin>
238238
</model>
@@ -281,17 +281,17 @@
281281
<kDotP>0</kDotP>
282282
<mDotQ>0</mDotQ>
283283
<nDotR>0</nDotR>
284-
<xUU>0</xUU>
284+
<xUabsU>0</xUabsU>
285285
<xU>0</xU>
286-
<yVV>0</yVV>
286+
<yVabsV>0</yVabsV>
287287
<yV>0</yV>
288-
<zWW>94.2475</zWW>
288+
<zWabsW>94.2475</zWabsW>
289289
<zW>0.0037699</zW>
290-
<kPP>0</kPP>
290+
<kPabsP>0</kPabsP>
291291
<kP>0</kP>
292-
<mQQ>0</mQQ>
292+
<mQabsQ>0</mQabsQ>
293293
<mQ>0</mQ>
294-
<nRR>0</nRR>
294+
<nRabsR>0</nRabsR>
295295
<nR>0</nR>
296296
</plugin>
297297
</model>

‎test/worlds/hydrodynamics_flags.sdf

+18-18
Original file line numberDiff line numberDiff line change
@@ -107,17 +107,17 @@
107107
<kDotP>0</kDotP>
108108
<mDotQ>-33.46</mDotQ>
109109
<nDotR>-33.46</nDotR>
110-
<xUU>-6.2282</xUU>
110+
<xUabsU>-6.2282</xUabsU>
111111
<xU>0</xU>
112-
<yVV>-601.27</yVV>
112+
<yVabsV>-601.27</yVabsV>
113113
<yV>0</yV>
114-
<zWW>-601.27</zWW>
114+
<zWabsW>-601.27</zWabsW>
115115
<zW>0</zW>
116-
<kPP>-0.1916</kPP>
116+
<kPabsP>-0.1916</kPabsP>
117117
<kP>0</kP>
118-
<mQQ>-632.698957</mQQ>
118+
<mQabsQ>-632.698957</mQabsQ>
119119
<mQ>0</mQ>
120-
<nRR>-632.698957</nRR>
120+
<nRabsR>-632.698957</nRabsR>
121121
<nR>0</nR>
122122
<disable_added_mass>true</disable_added_mass>
123123
<disable_coriolis>true</disable_coriolis>
@@ -222,17 +222,17 @@
222222
<kDotP>0</kDotP>
223223
<mDotQ>-33.46</mDotQ>
224224
<nDotR>-33.46</nDotR>
225-
<xUU>-6.2282</xUU>
225+
<xUabsU>-6.2282</xUabsU>
226226
<xU>0</xU>
227-
<yVV>-601.27</yVV>
227+
<yVabsV>-601.27</yVabsV>
228228
<yV>0</yV>
229-
<zWW>-601.27</zWW>
229+
<zWabsW>-601.27</zWabsW>
230230
<zW>0</zW>
231-
<kPP>-0.1916</kPP>
231+
<kPabsP>-0.1916</kPabsP>
232232
<kP>0</kP>
233-
<mQQ>-632.698957</mQQ>
233+
<mQabsQ>-632.698957</mQabsQ>
234234
<mQ>0</mQ>
235-
<nRR>-632.698957</nRR>
235+
<nRabsR>-632.698957</nRabsR>
236236
<nR>0</nR>
237237
<disable_added_mass>true</disable_added_mass>
238238
</plugin>
@@ -336,17 +336,17 @@
336336
<kDotP>0</kDotP>
337337
<mDotQ>-33.46</mDotQ>
338338
<nDotR>-33.46</nDotR>
339-
<xUU>-6.2282</xUU>
339+
<xUabsU>-6.2282</xUabsU>
340340
<xU>0</xU>
341-
<yVV>-601.27</yVV>
341+
<yVabsV>-601.27</yVabsV>
342342
<yV>0</yV>
343-
<zWW>-601.27</zWW>
343+
<zWabsW>-601.27</zWabsW>
344344
<zW>0</zW>
345-
<kPP>-0.1916</kPP>
345+
<kPabsP>-0.1916</kPabsP>
346346
<kP>0</kP>
347-
<mQQ>-632.698957</mQQ>
347+
<mQabsQ>-632.698957</mQabsQ>
348348
<mQ>0</mQ>
349-
<nRR>-632.698957</nRR>
349+
<nRabsR>-632.698957</nRabsR>
350350
<nR>0</nR>
351351
<disable_coriolis>true</disable_coriolis>
352352
</plugin>

‎tutorials/underwater_vehicles.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -78,17 +78,17 @@ name="ignition::gazebo::systems::Hydrodynamics">
7878
<kDotP>0</kDotP>
7979
<mDotQ>-33.46</mDotQ>
8080
<nDotR>-33.46</nDotR>
81-
<xUU>-6.2282</xUU>
81+
<xUabsU>-6.2282</xUabsU>
8282
<xU>0</xU>
83-
<yVV>-601.27</yVV>
83+
<yVabsV>-601.27</yVabsV>
8484
<yV>0</yV>
85-
<zWW>-601.27</zWW>
85+
<zWabsW>-601.27</zWabsW>
8686
<zW>0</zW>
87-
<kPP>-0.1916</kPP>
87+
<kPabsP>-0.1916</kPabsP>
8888
<kP>0</kP>
89-
<mQQ>-632.698957</mQQ>
89+
<mQabsQ>-632.698957</mQabsQ>
9090
<mQ>0</mQ>
91-
<nRR>-632.698957</nRR>
91+
<nRabsR>-632.698957</nRabsR>
9292
<nR>0</nR>
9393
</plugin>
9494
```

0 commit comments

Comments
 (0)