Documentation and more examples for #1297

[chapulina]

• Targeted at Fix graded buoyancy problems #1297

While reviewing #1297 I was trying to make sense of all the reference frames used throughout the plugin, so I started documenting them as I believe they currently are. Then I added a couple of examples and I think some use cases are still not working well.

I added 2 models with different offsets and volume distributions which I believe should all be equivalent and neutrally buoyant, but see how the model with a collision split in 2 bounces around. I think there's still some offset that's not properly taken into account (assuming I didn't mess anything up setting up the models).

I haven't dug deeply into the math yet to see where the issue could be coming from.

[arjo129]

Thanks for the suggestions and spotting this. I think we aren't handling multiple geometry in collisions correctly. I think this needs to be ticketed somewhere before we forget.

[codecov]

Codecov Report

Merging #1301 (bad001b) into arjo/fix/graded_buoyancy (1d461b8) will not change coverage.
The diff coverage is 100.00%.

@@                    Coverage Diff                    @@
##           arjo/fix/graded_buoyancy    #1301   +/-   ##
=========================================================
  Coverage                     62.23%   62.23%           
=========================================================
  Files                           278      278           
  Lines                         23192    23192           
=========================================================
  Hits                          14433    14433           
  Misses                         8759     8759           

Impacted Files	Coverage Δ
src/systems/buoyancy/Buoyancy.hh	100.00% <ø> (ø)
src/systems/buoyancy/Buoyancy.cc	82.60% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1d461b8...bad001b. Read the comment docs.

[chapulina]

I think we aren't handling multiple geometry in collisions correctly. I think this needs to be ticketed somewhere before we forget.

I pushed a fix on bad001b, mind giving it another try? We were accumulating the forces when we calculated the torque. I think it should be working now.

[arjo129]

Tested and looks good to me. I'll add a similar test case. Thanks for catching this. Seems like a major oversight on my part 🤦‍♂️ .