Add ActivationCoordinateActuator.h

Author: chrisdembia

Bindings/OpenSimHeaders_actuators.h

@@ -5,6 +5,7 @@
 
 #include <OpenSim/Actuators/osimActuatorsDLL.h>
 #include <OpenSim/Actuators/CoordinateActuator.h>
+#include <OpenSim/Actuators/ActivationCoordinateActuator.h>
 #include <OpenSim/Actuators/PointActuator.h>
 #include <OpenSim/Actuators/TorqueActuator.h>
 #include <OpenSim/Actuators/BodyActuator.h>

Bindings/actuators.i

@@ -1,6 +1,7 @@
 //osimActuators
 %include <OpenSim/Actuators/osimActuatorsDLL.h>
 %include <OpenSim/Actuators/CoordinateActuator.h>
+%include <OpenSim/Actuators/ActivationCoordinateActuator.h>
 %include <OpenSim/Actuators/PointActuator.h>
 %include <OpenSim/Actuators/TorqueActuator.h>
 %include <OpenSim/Actuators/BodyActuator.h>

CHANGELOG.md

@@ -8,7 +8,7 @@ This is not a comprehensive list of changes but rather a hand-curated collection
 
 v4.2
 ====
-- 
+- Add the ActivationCoordinateActuator component, which is a CoordinateActuator with simple activation dynamics.
 
 v4.1
 ====

OpenSim/Actuators/ActivationCoordinateActuator.h

@@ -0,0 +1,108 @@
+#ifndef OPENSIM_ACTIVATION_COORDINATE_ACTUATOR_H
+#define OPENSIM_ACTIVATION_COORDINATE_ACTUATOR_H
+/* -------------------------------------------------------------------------- *
+ *                  OpenSim:  ActivationCoordinateActuator.h                  *
+ * -------------------------------------------------------------------------- *
+ * The OpenSim API is a toolkit for musculoskeletal modeling and simulation.  *
+ * See http://opensim.stanford.edu and the NOTICE file for more information.  *
+ * OpenSim is developed at Stanford University and supported by the US        *
+ * National Institutes of Health (U54 GM072970, R24 HD065690) and by DARPA    *
+ * through the Warrior Web program.                                           *
+ *                                                                            *
+ * Copyright (c) 2005-2020 Stanford University and the Authors                *
+ * Author(s): Christopher Dembia                                              *
+ *                                                                            *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may    *
+ * not use this file except in compliance with the License. You may obtain a  *
+ * copy of the License at http://www.apache.org/licenses/LICENSE-2.0.         *
+ *                                                                            *
+ * Unless required by applicable law or agreed to in writing, software        *
+ * distributed under the License is distributed on an "AS IS" BASIS,          *
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   *
+ * See the License for the specific language governing permissions and        *
+ * limitations under the License.                                             *
+ * -------------------------------------------------------------------------- */
+
+#include "osimActuatorsDLL.h"
+
+#include "CoordinateActuator.h"
+
+namespace OpenSim {
+
+/// Similar to CoordinateActuator (simply produces a generalized force) but
+/// with first-order linear activation dynamics. This actuator has one state
+/// variable, `activation`, with \f$ \dot{a} = (x - a) / \tau \f$, where
+/// \f$ a \f$ is activation, \f$ x \f$ is excitation, and \f$ \tau \f$ is the
+/// activation time constant (there is no separate deactivation time constant).
+/// The statebounds_activation output is used in Moco to set default values for
+/// the activation state variable.
+/// <b>Default %Property Values</b>
+/// @verbatim
+/// activation_time_constant: 0.01
+/// default_activation: 0.5
+/// @endverbatim
+class OSIMACTUATORS_API ActivationCoordinateActuator
+        : public CoordinateActuator {
+    OpenSim_DECLARE_CONCRETE_OBJECT(ActivationCoordinateActuator,
+        CoordinateActuator);
+public:
+    OpenSim_DECLARE_PROPERTY(activation_time_constant, double,
+        "Larger value means activation can change more rapidly "
+        "(units: seconds; default: 0.01 seconds).");
+
+    OpenSim_DECLARE_PROPERTY(default_activation, double,
+        "Value of activation in the default state returned by initSystem() "
+        "(default: 0.5).");
+
+    OpenSim_DECLARE_OUTPUT(statebounds_activation, SimTK::Vec2,
+        getBoundsActivation, SimTK::Stage::Model);
+
+    ActivationCoordinateActuator() {
+        constructProperties();
+    }
+
+    /// The lower bound on activation is getMinControl() and the upper bound is
+    /// getMaxControl().
+    /// Whether these bounds are enforced is determined by the solver used.
+    SimTK::Vec2 getBoundsActivation(const SimTK::State&) const {
+        return SimTK::Vec2(getMinControl(), getMaxControl());
+    }
+
+protected:
+    void extendAddToSystem(SimTK::MultibodySystem& system) const override {
+        Super::extendAddToSystem(system);
+        addStateVariable("activation", SimTK::Stage::Dynamics);
+    }
+
+    void extendInitStateFromProperties(SimTK::State& s) const override {
+        Super::extendInitStateFromProperties(s);
+        setStateVariableValue(s, "activation", get_default_activation());
+    }
+
+    void extendSetPropertiesFromState(const SimTK::State& s) override {
+        Super::extendSetPropertiesFromState(s);
+        set_default_activation(getStateVariableValue(s, "activation"));
+    }
+
+    void computeStateVariableDerivatives(const SimTK::State& s) const override {
+        // No need to do clamping, etc; CoordinateActuator is bidirectional.
+        const auto& tau = get_activation_time_constant();
+        const auto& x = getControl(s);
+        const auto& a = getStateVariableValue(s, "activation");
+        const SimTK::Real adot = (x - a) / tau;
+        setStateVariableDerivativeValue(s, "activation", adot);
+    }
+
+    double computeActuation(const SimTK::State& s) const override {
+        return getStateVariableValue(s, "activation") * getOptimalForce();
+    }
+private:
+    void constructProperties() {
+        constructProperty_activation_time_constant(0.010);
+        constructProperty_default_activation(0.5);
+    }
+};
+
+} // namespace OpenSim
+
+#endif // OPENSIM_ACTIVATION_COORDINATE_ACTUATOR_H

OpenSim/Actuators/RegisterTypes_osimActuators.cpp

@@ -27,6 +27,7 @@
 #include "RegisterTypes_osimActuators.h"
 
 #include "CoordinateActuator.h"
+#include "ActivationCoordinateActuator.h"
 #include "PointActuator.h"
 #include "TorqueActuator.h"
 #include "BodyActuator.h"
@@ -78,6 +79,7 @@ OSIMACTUATORS_API void RegisterTypes_osimActuators()
   try {
 
     Object::registerType( CoordinateActuator() );
+    Object::registerType( ActivationCoordinateActuator() );
     Object::registerType( PointActuator() );
     Object::registerType( TorqueActuator() );
     Object::registerType( BodyActuator() );

OpenSim/Actuators/osimActuators.h

@@ -24,6 +24,7 @@
  * -------------------------------------------------------------------------- */
 
 #include "CoordinateActuator.h"
+#include "ActivationCoordinateActuator.h"
 #include "PointActuator.h"
 #include "TorqueActuator.h"
 #include "BodyActuator.h"