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