Feature: add `ForceProducer` and `ForceConsumer` APIs

[adamkewley]

This PR adds ForceProducer, ForceConsumer, and ForceApplier and rolls them out to as many OpenSim::Force implementations as feasible.

Overview

• ForceProducer is an abstract OpenSim::Force that downstream classes can use, rather than Force, to emit their forces one-by-one to a ForceConsumer.
• ForceConsumer is an abstract class with consumption methods (e.g. consumePointForce) that directly mirror the of OpenSim::Force equivalents (e.g. Force::applyForceToPoint).
• ForceApplier is a ForceConsumer that applies each consumed force to a SimTK::Vector_<SimTK::SpatialForce> of body forces and a SimTK::Vector of mobility (generalized) forces.

Key features:

• ForceProducer's virtual one-by-one API is in contrast to OpenSim::Force, where forces are added by directly modifying the physics engine's bodyForces and generalizedForces vectors in-place. The benefit of this is that it decouples "force production/consumption" from "force application", which lets not-simbody (e.g. UIs) use the force API more easily.
• ForceConsumer's API is designed with the similar naming, the same arguments, and the same spatial (e.g. torques in ground) requirements as the equivalent OpenSim::Force API methods. This makes it easier to port OpenSim::Force code to the ForceConsumer API. The ForceConsumer API also separates "body forces" from "point forces", so that concrete ForceProducers are able to emit point-force information to other systems (e.g. debuggers that would like to print point forces).
• ForceProducer's API provides a default implementation of OpenSim::Force::computeForce, which internally uses ForceApplier apply the one-at-a-time forces to the vectors that OpenSim::Force::computeForce uses. This makes ForceProducer backwards-compatible with any existing code that handles OpenSim::Forces.
• The API's compatibility means no breaking changes for downstream code - save for a small, probably easy-to-update, change to the virtual API of AbstractGeometryPath.

The ForceConsumer API

The ForceConsumer API is an abstract class that has a public API that consumes four types of forces:

class ForceConsumer {
public:
    void consumeGeneralizedForce(const SimTK::State&, const Coordinate&, double);
    void consumeBodySpatialVec(const SimTK::State&, const PhysicalFrame&, const SimTK::SpatialVec&);
    void consumeTorque(const SimTK::State&, const PhysicalFrame&, const SimTK::Vec3&);
    void consumePointForce(const SimTK::State&, const PhysicalFrame&, const SimTK::Vec3&, const SimTK::Vec3&);

    // (see diff for the entire definition)
};

Concrete implementations of ForceConsumer may override each of the corresponding virtual void implConsume* methods in order to consume that type of force. The default implementation of each implConsume* function does nothing (e.g. it ignores the force). A concrete implementation does not have to do anything with a force, which enables using the API to (e.g.) implement force debuggers, force visualizers, point-force reporters, and so on.

The ForceProducer API

The ForceProducer API is an abstract class that exposes produceForces:

class ForceProducer {
public:
    void produceForces(const SimTK::State&, ForceConsumer&) const;

    // supplies a default implementation of `OpenSim::Force::computeForce`
    void computeForce(const SimTK::State&, SimTK::Vector_<SimTK::SpatialVec>&, SimTK::Vector&) const override;

    // (see diff for the entire definition)
};

Concrete implementations can then inherit from ForceProducer and supply an implProduceForces in which the concrete implementation calls (e.g.) ForceConsumer::consumePointForce. The default ForceProducer::computeForce implementation uses ForceApplier to satisfy the OpenSim::Force API. It's overrided, rather than finald, because there is legacy code in OpenSim that does extra stuff after computeForce is called (e.g. resetting state variables). An ideal implementation would final computeForce.

Motivation (why add this?)

The OpenSim::Force API isn't easy for downstream code, such as OpenSim Creator's, to hook into. Because the OpenSim::Force API couples force generation/production with application. Because of this, downstream code has to:

• Allocate zero-initialized vectors of body+generalized+particle forces, to emulate acting as a simbody engine.
• Use a ForceAdaptor to mutate those vectors.
• Re-scan the vectors to figure out which forces affected which bodies in the model.

The OpenSim::Force API also erases point-force information. At the OpenSim::Force layer of the API, all forces are already resolved into body forces and body torques. However, downstream code might want to visualize point-forces (e.g. when visualizing ExternalForce, PrescribedForce, and GeometryPath).

Brief Summary of Changes

• Added ForceProducer
• Added ForceConsumer
• Added ForceApplier
• Added basic test suite for ForceProducer
• Rolled out ForceConsumer and ForceProducer APIs to all existing OpenSim classes that were previously using the Force API.
  • This is so that almost any force in opensim-core can be queried using the ForceProducer API
  • It also ensures the API is actually robust enough to rollout to a wide variety of Force implementations
• BREAKING (virtual API) CHANGE: Replaced virtual AbstractGeometryPath::addInEquivalentForces with a virtual AbstractGeometryPath::produceForces API:
  • The change is to facilitate integrating ForceProducers with AbstractGeometryPath (e.g. necessary for PathActuator and similar).
  • For backwards compatiblity, added a concrete AbstractGeometryPath::addInEquivalentForces function that uses the new produceForces API internally.
  • Although this is a BREAKING, change, it only breaks the virtual, not public, API of AbstractGeometryPath. I consider this a minor breakage, because the API is very new, it's unlikely 3rd-party code is implementing it, and porting the implementation to use ForceConsumer is an easy change.
• Added ForceProducer and ForceConsumer APIs to the SWIG bindings
• Added any additional template instantiations to the SWIG bindings
• Tried to find+replace relevant comments that say "applies force" to instead say "produces/computes force". This is to make it clear that the forces aren't actually applied by the methods anymore.

No changes were made to any existing test suites, binding tests, etc. This is to say, these changes should not have broken the existing functionality of the OpenSim API - apart from the virtual API change in AbstractGeometryPath.

Testing I've completed

• Added a basic unit test suite for ForceProducer to ensure it behaves as expected
• Added a unit test that compares the mutations applied by ForceApplier (via ForceProducer::computeForce) to the mutations caused by a "typical" Force usage.
• Almost all Forces were ported to this API. Any existing test suite that tests force components will also be indirectly testing this API (e.g. any tests testing muscle implementations are now indirectly exercising the new API).

Looking for feedback on...

• Design direction, usefulness, rollout, etc.

CHANGELOG.md

Updated.

---

This change is 

[adamkewley]

The rollout if now almost complete, and it's compiling + passing on mac + ubuntu. The Windows issue is external (CI images were updated and now there's warnings/errors - see #3895)

[adamkewley]

testMocoInverse seems to be broken on Windows (but is otherwise fine on Linux+Mac O_o) - I'm assuming a slight numeric difference has been introduced by the rewrite of GeometryPath::implProduceForces (it was cleaned up from addInEquivalentForces).

[adamkewley]

After reverting the GeometryPath implementation to basically be exactly the same as the existing addInEquivalentForces, but now using the ForceConsumer API, I can get testMocoInverse to pass - it's probably a numeric instability that needs to be carefully handled in a separate PR (cleaning up that part of the code would be useful, in general, for point-force visualization).

[adamkewley]

The build is working, test passing etc. with the reversion - I'll tackle it in a separate PR.

I have also added a test that compares the Force API mutations to the ForceConsumer API mutations to ensure that they are like-for-like - and actually edit the force vectors.

I'll un-WIP this and try to wrangle someone for a review.

[adamkewley]

When self-reviewing the diff I found a few things that need to be re-thought:

• The appliesForce member from Force should only be checked by ForceApplier. ForceProducers should unconditionally produce their forces when directly requested for them. If there's a desire to disable the ability to even ask a ForceProducer to produce its forces (side-effect free), then a new property called producesForces should be added. This is to discriminate between "produces forces into a consumer" from "applies forces to a multibody system"
• The Force API changes (protected --> public) aren't strictly necessary because ForceApplier directly uses the SimbodyMattterSubsystem API.

[adamkewley]

Ok, now it's ready for review :wink:

[adamkewley]

Thanks for reviewing, @pepbos

@nickbianco - this PR also impacts the AbstractGeometryPath API slightly (it not "produces" forces rather than addInEquivalentForces). Is that an acceptable change (I've ported FunctionBasedPath etc. to make it compatible).

If so, and if there's no further review comments, I'll go ahead and merge this

[adamkewley]

I think I'm going to go ahead and merge this as-is: the use of raw pointer members is limited to private variables and can be refactored later if there's long term maintenance concerns (which there might be - I'm still undecided on the best approach), and the pointer-based constructor, which is more explicit at the cost of having a more C/C++ey feel, can always be overridden with an additional reference-based constructor if it becomes a pain point later on.

Just FYI, I plan on integrating the API immediately into the dev (main) branch of OSC so that I can start visualizing force vectors etc. using the API - I imagine that doing so will probably kick up some circumstances that require additional PRs to fix. For example, GeometryPath is producing two tension force vectors per path point - I anticipate that it's nicer to visualize the resultant vector, which would require rewriting that function a little bit. I also anticipate similar changes might be nice in other force components (e.g. contact forces would be lovely to visualize), but I don't know which/where until I start attaching a visualizer to the API.

Cheers to @nickbianco and @pepbos for reviewing this.