Explicitly consider buoyancy vs. gravity

[ryancoe]

Currently, we assume equilibrium for the gravity and buoyancy of the body. This can be a bit unintuitive. We want to alter the residual equation to include gravity and buoyancy. In the case that these are not balanced (e.g., a tether or mooring system provides some additional pretension), the user will need to include a f_add that balances the gravity and buoyancy forces.

https://github.com/SNL-WaterPower/WecOptTool/blob/51c3aea47098ab1a7cf6c2a8f9801ff60de5645e/wecopttool/core.py#L786

f_b = f_b0 + kx, where k = 0 for a submerged body

We considered altering the impedance, but gravity is not position (state) dependent.

[ryancoe]

Everything is more complicated in execution... ;)
When you consider arbitrary degrees of freedom (not just heave), this gets harder to generalize. The options we considered:

1. Leave buoyancy/gravity implicit (current implementation)
2. Internally calculate f_b and f_g based on mesh -- this is what we originally thought we'd do, but now that we think about generalizing it for arbitrary degrees of freedom, this doesn't look like a viable option (note that there's an open PR for capytaine to get hydrostatics)
3. Have the user (optionally) pass functions for calculating f_b and f_g. This looks like the best option for users, because:
   • More explicit (easier to understand)
   • We can automate the post-processing

We will go with option 3. We will change f_add argument to WEC class to be a dict with the keys being the names and the values being function handles. For example:

def my_buoyancy_function(my_wec, x_wec, x_opt):
    ...
    return  f_b     # of size n_dof x n_collocation_points

f_add = {
         'f_b': my_buoyancy_function, 
         'f_g': my_gravity_function, 
         'f_pto': my_pto_function, 
         'f_nlhydro': my_nonlinear_hyrdodynamics_function, 
         'f_mooring`: my_mooring_function,
          }

This will allow us to automatically generate an xarray.DataSet during post-processing the breakouts out these different components.

[cmichelenstrofer]

• Currently assuming the WEC is in heave equilibrium and the net force required to maintain that position (zero if floating, cable tension if pre-tensioned) is implicit. This is not wrong, but can be unintuitive.
• The center of gravity and center of buoyancy create a pitch and a roll restoring stiffness. This is not currently captured.
• There is a Capytaine PR for hydrostatic stiffness for arbitrary DOFs. This should be completed and included in Capytaine.
• Something similar will need to be done for the Fg for arbitrary DOFs
• This is not trivial, need to capture range of possible DOFs: rigid body translations, rigid body rotation about COG, rotation about other axes, relative translation or rotation between rigid bodies, other generalized DOFs (e.g. compression)

[ryancoe]

Per our discussion today, @cmichelenstrofer and I decided we should put effort towards helping merge capytaine #106, as this works based on the unit vectors of the surface mesh and BEM DOFs, thus requiring no additional input from the user.

[cmichelenstrofer]

@ryancoe Should we re-open this issue since we do want to eventually move to "option 2: Internally calculate f_b and f_g based on mesh" using Capytaine.

[ryancoe]

Let's make a new issue so that the final result is a been between Option 2 and Option 3: we allow user to set functions, but we give them tools for building these functions.