Add JointAPI schema in mjcPhysics.

PiperOrigin-RevId: 778030981
Change-Id: I22a4bf2a550fb78e47bef0ff171b10ce5912887e

include/mujoco/experimental/usd/mjcPhysics/jointAPI.h

@@ -0,0 +1,622 @@
+// Copyright 2025 DeepMind Technologies Limited
+//
+// 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.
+
+#ifndef MJCPHYSICS_GENERATED_JOINTAPI_H
+#define MJCPHYSICS_GENERATED_JOINTAPI_H
+
+/// \file mjcPhysics/jointAPI.h
+
+#include <mujoco/experimental/usd/mjcPhysics/api.h>
+#include <mujoco/experimental/usd/mjcPhysics/tokens.h>
+#include <pxr/base/gf/matrix4d.h>
+#include <pxr/base/gf/vec3d.h>
+#include <pxr/base/gf/vec3f.h>
+#include <pxr/base/tf/token.h>
+#include <pxr/base/tf/type.h>
+#include <pxr/base/vt/value.h>
+#include <pxr/pxr.h>
+#include <pxr/usd/usd/apiSchemaBase.h>
+#include <pxr/usd/usd/prim.h>
+#include <pxr/usd/usd/stage.h>
+
+PXR_NAMESPACE_OPEN_SCOPE
+
+class SdfAssetPath;
+
+// -------------------------------------------------------------------------- //
+// PHYSICSJOINTSAPI                                                           //
+// -------------------------------------------------------------------------- //
+
+/// \class MjcPhysicsJointAPI
+///
+/// API describing a Mujoco joint.
+///
+/// For any described attribute \em Fallback \em Value or \em Allowed \em Values
+/// below that are text/tokens, the actual token is published and defined in
+/// \ref MjcPhysicsTokens. So to set an attribute to the value "rightHanded",
+/// use MjcPhysicsTokens->rightHanded as the value.
+///
+class MjcPhysicsJointAPI : public UsdAPISchemaBase {
+ public:
+  /// Compile time constant representing what kind of schema this class is.
+  ///
+  /// \sa UsdSchemaKind
+  static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI;
+
+  /// Construct a MjcPhysicsJointAPI on UsdPrim \p prim .
+  /// Equivalent to MjcPhysicsJointAPI::Get(prim.GetStage(), prim.GetPath())
+  /// for a \em valid \p prim, but will not immediately throw an error for
+  /// an invalid \p prim
+  explicit MjcPhysicsJointAPI(const UsdPrim &prim = UsdPrim())
+      : UsdAPISchemaBase(prim) {}
+
+  /// Construct a MjcPhysicsJointAPI on the prim held by \p schemaObj .
+  /// Should be preferred over MjcPhysicsJointAPI(schemaObj.GetPrim()),
+  /// as it preserves SchemaBase state.
+  explicit MjcPhysicsJointAPI(const UsdSchemaBase &schemaObj)
+      : UsdAPISchemaBase(schemaObj) {}
+
+  /// Destructor.
+  MJCPHYSICS_API
+  virtual ~MjcPhysicsJointAPI();
+
+  /// Return a vector of names of all pre-declared attributes for this schema
+  /// class and all its ancestor classes.  Does not include attributes that
+  /// may be authored by custom/extended methods of the schemas involved.
+  MJCPHYSICS_API
+  static const TfTokenVector &GetSchemaAttributeNames(
+      bool includeInherited = true);
+
+  /// Return a MjcPhysicsJointAPI holding the prim adhering to this
+  /// schema at \p path on \p stage.  If no prim exists at \p path on
+  /// \p stage, or if the prim at that path does not adhere to this schema,
+  /// return an invalid schema object.  This is shorthand for the following:
+  ///
+  /// \code
+  /// MjcPhysicsJointAPI(stage->GetPrimAtPath(path));
+  /// \endcode
+  ///
+  MJCPHYSICS_API
+  static MjcPhysicsJointAPI Get(const UsdStagePtr &stage, const SdfPath &path);
+
+  /// Returns true if this <b>single-apply</b> API schema can be applied to
+  /// the given \p prim. If this schema can not be a applied to the prim,
+  /// this returns false and, if provided, populates \p whyNot with the
+  /// reason it can not be applied.
+  ///
+  /// Note that if CanApply returns false, that does not necessarily imply
+  /// that calling Apply will fail. Callers are expected to call CanApply
+  /// before calling Apply if they want to ensure that it is valid to
+  /// apply a schema.
+  ///
+  /// \sa UsdPrim::GetAppliedSchemas()
+  /// \sa UsdPrim::HasAPI()
+  /// \sa UsdPrim::CanApplyAPI()
+  /// \sa UsdPrim::ApplyAPI()
+  /// \sa UsdPrim::RemoveAPI()
+  ///
+  MJCPHYSICS_API
+  static bool CanApply(const UsdPrim &prim, std::string *whyNot = nullptr);
+
+  /// Applies this <b>single-apply</b> API schema to the given \p prim.
+  /// This information is stored by adding "PhysicsJointsAPI" to the
+  /// token-valued, listOp metadata \em apiSchemas on the prim.
+  ///
+  /// \return A valid MjcPhysicsJointAPI object is returned upon success.
+  /// An invalid (or empty) MjcPhysicsJointAPI object is returned upon
+  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
+  /// resulting in failure.
+  ///
+  /// \sa UsdPrim::GetAppliedSchemas()
+  /// \sa UsdPrim::HasAPI()
+  /// \sa UsdPrim::CanApplyAPI()
+  /// \sa UsdPrim::ApplyAPI()
+  /// \sa UsdPrim::RemoveAPI()
+  ///
+  MJCPHYSICS_API
+  static MjcPhysicsJointAPI Apply(const UsdPrim &prim);
+
+ protected:
+  /// Returns the kind of schema this class belongs to.
+  ///
+  /// \sa UsdSchemaKind
+  MJCPHYSICS_API
+  UsdSchemaKind _GetSchemaKind() const override;
+
+ private:
+  // needs to invoke _GetStaticTfType.
+  friend class UsdSchemaRegistry;
+  MJCPHYSICS_API
+  static const TfType &_GetStaticTfType();
+
+  static bool _IsTypedSchema();
+
+  // override SchemaBase virtuals.
+  MJCPHYSICS_API
+  const TfType &_GetTfType() const override;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCSPRINGDAMPER
+  // --------------------------------------------------------------------- //
+  /// When both numbers are positive, the compiler will override any stiffness
+  /// and damping values specified with the attributes below, and will instead
+  /// set them automatically so that the resulting mass-spring-damper for this
+  /// joint has the desired time constant (first value) and damping ratio
+  /// (second value). This is done by taking into account the joint inertia in
+  /// the model reference configuration. Note that the format is the same as the
+  /// solref parameter of the constraint solver.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double[] mjc:springdamper = [0, 0]` |
+  /// | C++ Type | VtArray<double> |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->DoubleArray |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcSpringdamperAttr() const;
+
+  /// See GetMjcSpringdamperAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcSpringdamperAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCSOLREFLIMIT
+  // --------------------------------------------------------------------- //
+  /// Constraint solver parameters for simulating joint limits.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double[] mjc:solreflimit = [0.02, 1]` |
+  /// | C++ Type | VtArray<double> |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->DoubleArray |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcSolreflimitAttr() const;
+
+  /// See GetMjcSolreflimitAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcSolreflimitAttr(VtValue const &defaultValue = VtValue(),
+                                        bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCSOLIMPLIMIT
+  // --------------------------------------------------------------------- //
+  /// Constraint solver parameters for simulating joint limits.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double[] mjc:solimplimit = [0.9, 0.95, 0.001,
+  /// 0.5, 2]` | | C++ Type | VtArray<double> | | \ref Usd_Datatypes "Usd Type"
+  /// | SdfValueTypeNames->DoubleArray | | \ref SdfVariability "Variability" |
+  /// SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcSolimplimitAttr() const;
+
+  /// See GetMjcSolimplimitAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcSolimplimitAttr(VtValue const &defaultValue = VtValue(),
+                                        bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCSOLREFFRICTION
+  // --------------------------------------------------------------------- //
+  /// Constraint solver parameters for simulating dry friction.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double[] mjc:solreffriction = [0.02, 1]` |
+  /// | C++ Type | VtArray<double> |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->DoubleArray |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcSolreffrictionAttr() const;
+
+  /// See GetMjcSolreffrictionAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcSolreffrictionAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCSOLIMPFRICTION
+  // --------------------------------------------------------------------- //
+  /// Constraint solver parameters for simulating dry friction.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double[] mjc:solimpfriction = [0.9, 0.95, 0.001,
+  /// 0.5, 2]` | | C++ Type | VtArray<double> | | \ref Usd_Datatypes "Usd Type"
+  /// | SdfValueTypeNames->DoubleArray | | \ref SdfVariability "Variability" |
+  /// SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcSolimpfrictionAttr() const;
+
+  /// See GetMjcSolimpfrictionAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcSolimpfrictionAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCSTIFFNESS
+  // --------------------------------------------------------------------- //
+  /// Joint stiffness. If this value is positive, a spring will be created with
+  /// equilibrium position given by springref below. The spring force is
+  /// computed along with the other passive forces.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:stiffness = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcStiffnessAttr() const;
+
+  /// See GetMjcStiffnessAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcStiffnessAttr(VtValue const &defaultValue = VtValue(),
+                                      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCACTUATORFRCRANGEMIN
+  // --------------------------------------------------------------------- //
+  /// Minimum range for clamping total actuator forces acting on this joint. See
+  /// Force limits for details. It is available only for scalar joints (hinge
+  /// and slider) and ignored for ball and free joints. The compiler expects the
+  /// first value to be smaller than the second value. Setting this attribute
+  /// without specifying actuatorfrclimited is an error if compiler-autolimits
+  /// is 'false'.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:actuatorfrcrange:min = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcActuatorfrcrangeMinAttr() const;
+
+  /// See GetMjcActuatorfrcrangeMinAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcActuatorfrcrangeMinAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCACTUATORFRCRANGEMAX
+  // --------------------------------------------------------------------- //
+  /// Maximum range for clamping total actuator forces acting on this joint. See
+  /// Force limits for details. It is available only for scalar joints (hinge
+  /// and slider) and ignored for ball and free joints. The compiler expects the
+  /// first value to be smaller than the second value. Setting this attribute
+  /// without specifying actuatorfrclimited is an error if compiler-autolimits
+  /// is 'false'.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:actuatorfrcrange:max = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcActuatorfrcrangeMaxAttr() const;
+
+  /// See GetMjcActuatorfrcrangeMaxAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcActuatorfrcrangeMaxAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCACTUATORFRCLIMITED
+  // --------------------------------------------------------------------- //
+  /// This attribute specifies whether actuator forces acting on the joint
+  /// should be clamped. See Force limits for details. It is available only for
+  /// scalar joints (hinge and slider) and ignored for ball and free joints.
+  /// This attribute interacts with the actuatorfrcrange attribute. If this
+  /// attribute is 'false', actuator force clamping is disabled. If it is
+  /// 'true', actuator force clamping is enabled. If this attribute is 'auto',
+  /// and autolimits is set in compiler, actuator force clamping will be enabled
+  /// if actuatorfrcrange is defined.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform token mjc:actuatorfrclimited = "auto"` |
+  /// | C++ Type | TfToken |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  /// | \ref MjcPhysicsTokens "Allowed Values" | false, true, auto |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcActuatorfrclimitedAttr() const;
+
+  /// See GetMjcActuatorfrclimitedAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcActuatorfrclimitedAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCACTUATORGRAVCOMP
+  // --------------------------------------------------------------------- //
+  /// If this flag is enabled, gravity compensation applied to this joint is
+  /// added to actuator forces (mjData.qfrc_actuator) rather than passive forces
+  /// (mjData.qfrc_passive). Notionally, this means that gravity compensation is
+  /// the result of a control system rather than natural buoyancy. In practice,
+  /// enabling this flag is useful when joint-level actuator force clamping is
+  /// used. In this case, the total actuation force applied on a joint,
+  /// including gravity compensation, is guaranteed to not exceed the specified
+  /// limits. See Force limits and actuatorfrcrange for more details on this
+  /// type of force limit.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform bool mjc:actuatorgravcomp = 0` |
+  /// | C++ Type | bool |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcActuatorgravcompAttr() const;
+
+  /// See GetMjcActuatorgravcompAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcActuatorgravcompAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCMARGIN
+  // --------------------------------------------------------------------- //
+  /// The distance threshold below which limits become active. Recall that the
+  /// Constraint solver normally generates forces as soon as a constraint
+  /// becomes active, even if the margin parameter makes that happen at a
+  /// distance. This attribute together with solreflimit and solimplimit can be
+  /// used to model a soft joint limit.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:margin = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcMarginAttr() const;
+
+  /// See GetMjcMarginAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcMarginAttr(VtValue const &defaultValue = VtValue(),
+                                   bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCREF
+  // --------------------------------------------------------------------- //
+  /// The reference position or angle of the joint. This attribute is only used
+  /// for slide and hinge joints. It defines the joint value corresponding to
+  /// the initial model configuration. The amount of spatial transformation that
+  /// the joint applies at runtime equals the current joint value stored in
+  /// mjData.qpos minus this reference value stored in mjModel.qpos0. The
+  /// meaning of these vectors was discussed in the Stand-alone section in the
+  /// Overview chapter.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:ref = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcRefAttr() const;
+
+  /// See GetMjcRefAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcRefAttr(VtValue const &defaultValue = VtValue(),
+                                bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCSPRINGREF
+  // --------------------------------------------------------------------- //
+  /// The joint position or angle in which the joint spring (if any) achieves
+  /// equilibrium. Similar to the vector mjModel.qpos0 which stores all joint
+  /// reference values specified with the ref attribute above, all spring
+  /// reference values specified with this attribute are stored in the vector
+  /// mjModel.qpos_spring. The model configuration corresponding to
+  /// mjModel.qpos_spring is also used to compute the spring reference lengths
+  /// of all tendons, stored in mjModel.tendon_lengthspring. This is because
+  /// tendons can also have springs.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:springref = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcSpringrefAttr() const;
+
+  /// See GetMjcSpringrefAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcSpringrefAttr(VtValue const &defaultValue = VtValue(),
+                                      bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCARMATURE
+  // --------------------------------------------------------------------- //
+  /// Additional inertia associated with movement of the joint that is not due
+  /// to body mass. This added inertia is usually due to a rotor (a.k.a
+  /// armature) spinning faster than the joint itself due to a geared
+  /// transmission. The value applies to all degrees of freedom created by this
+  /// joint. Besides increasing the realism of joints with geared transmission,
+  /// positive armature significantly improves simulation stability, even for
+  /// small values, and is a recommended possible fix when encountering
+  /// stability issues.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:armature = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcArmatureAttr() const;
+
+  /// See GetMjcArmatureAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcArmatureAttr(VtValue const &defaultValue = VtValue(),
+                                     bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCDAMPING
+  // --------------------------------------------------------------------- //
+  /// Damping applied to all degrees of freedom created by this joint. Unlike
+  /// friction loss which is computed by the constraint solver, damping is
+  /// simply a force linear in velocity. It is included in the passive forces.
+  /// Despite this simplicity, larger damping values can make numerical
+  /// integrators unstable, which is why our Euler integrator handles damping
+  /// implicitly. See Integration in the Computation chapter.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:damping = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcDampingAttr() const;
+
+  /// See GetMjcDampingAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcDampingAttr(VtValue const &defaultValue = VtValue(),
+                                    bool writeSparsely = false) const;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // MJCFRICTIONLOSS
+  // --------------------------------------------------------------------- //
+  /// Friction loss due to dry friction. This value is the same for all degrees
+  /// of freedom created by this joint. Semantically friction loss does not make
+  /// sense for free joints, but the compiler allows it. To enable friction
+  /// loss, set this attribute to a positive value.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform double mjc:frictionloss = 0` |
+  /// | C++ Type | double |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetMjcFrictionlossAttr() const;
+
+  /// See GetMjcFrictionlossAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateMjcFrictionlossAttr(
+      VtValue const &defaultValue = VtValue(),
+      bool writeSparsely = false) const;
+
+ public:
+  // ===================================================================== //
+  // Feel free to add custom code below this line, it will be preserved by
+  // the code generator.
+  //
+  // Just remember to:
+  //  - Close the class declaration with };
+  //  - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
+  //  - Close the include guard with #endif
+  // ===================================================================== //
+  // --(BEGIN CUSTOM CODE)--
+};
+
+PXR_NAMESPACE_CLOSE_SCOPE
+
+#endif

include/mujoco/experimental/usd/mjcPhysics/tokens.h

@@ -63,7 +63,8 @@ struct MjcPhysicsTokensType {
   /// Fallback value for MjcPhysicsSceneAPI::GetJacobianAttr(), Fallback value
   /// for MjcPhysicsActuatorAPI::GetMjcActLimitedAttr(), Fallback value for
   /// MjcPhysicsActuatorAPI::GetMjcCtrlLimitedAttr(), Fallback value for
-  /// MjcPhysicsActuatorAPI::GetMjcForceLimitedAttr(),  This token represents
+  /// MjcPhysicsActuatorAPI::GetMjcForceLimitedAttr(), Fallback value for
+  /// MjcPhysicsJointAPI::GetMjcActuatorfrclimitedAttr(),  This token represents
   /// the auto constraint Jacobian and matrices computed from it.
   const TfToken auto_;
   /// \brief "cg"
@@ -98,7 +99,8 @@ struct MjcPhysicsTokensType {
   ///
   /// Possible value for MjcPhysicsActuatorAPI::GetMjcActLimitedAttr(), Possible
   /// value for MjcPhysicsActuatorAPI::GetMjcCtrlLimitedAttr(), Possible value
-  /// for MjcPhysicsActuatorAPI::GetMjcForceLimitedAttr()
+  /// for MjcPhysicsActuatorAPI::GetMjcForceLimitedAttr(), Possible value for
+  /// MjcPhysicsJointAPI::GetMjcActuatorfrclimitedAttr()
   const TfToken false_;
   /// \brief "filter"
   ///
@@ -154,6 +156,26 @@ struct MjcPhysicsTokensType {
   ///
   /// MjcPhysicsActuatorAPI
   const TfToken mjcActRangeMin;
+  /// \brief "mjc:actuatorfrclimited"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcActuatorfrclimited;
+  /// \brief "mjc:actuatorfrcrange:max"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcActuatorfrcrangeMax;
+  /// \brief "mjc:actuatorfrcrange:min"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcActuatorfrcrangeMin;
+  /// \brief "mjc:actuatorgravcomp"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcActuatorgravcomp;
+  /// \brief "mjc:armature"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcArmature;
   /// \brief "mjc:biasPrm"
   ///
   /// MjcPhysicsActuatorAPI
@@ -182,6 +204,10 @@ struct MjcPhysicsTokensType {
   ///
   /// MjcPhysicsActuatorAPI
   const TfToken mjcCtrlRangeMin;
+  /// \brief "mjc:damping"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcDamping;
   /// \brief "mjc:dynPrm"
   ///
   /// MjcPhysicsActuatorAPI
@@ -294,6 +320,10 @@ struct MjcPhysicsTokensType {
   ///
   /// MjcPhysicsActuatorAPI
   const TfToken mjcForceRangeMin;
+  /// \brief "mjc:frictionloss"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcFrictionloss;
   /// \brief "mjc:gainPrm"
   ///
   /// MjcPhysicsActuatorAPI
@@ -322,6 +352,10 @@ struct MjcPhysicsTokensType {
   ///
   /// MjcPhysicsActuatorAPI
   const TfToken mjcLengthRangeMin;
+  /// \brief "mjc:margin"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcMargin;
   /// \brief "mjc:mpos"
   ///
   /// MjcPhysicsKeyframe
@@ -442,6 +476,10 @@ struct MjcPhysicsTokensType {
   ///
   /// MjcPhysicsKeyframe
   const TfToken mjcQvel;
+  /// \brief "mjc:ref"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcRef;
   /// \brief "mjc:refSite"
   ///
   /// MjcPhysicsActuatorAPI
@@ -454,6 +492,34 @@ struct MjcPhysicsTokensType {
   ///
   /// MjcPhysicsActuatorAPI
   const TfToken mjcSliderSite;
+  /// \brief "mjc:solimpfriction"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcSolimpfriction;
+  /// \brief "mjc:solimplimit"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcSolimplimit;
+  /// \brief "mjc:solreffriction"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcSolreffriction;
+  /// \brief "mjc:solreflimit"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcSolreflimit;
+  /// \brief "mjc:springdamper"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcSpringdamper;
+  /// \brief "mjc:springref"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcSpringref;
+  /// \brief "mjc:stiffness"
+  ///
+  /// MjcPhysicsJointAPI
+  const TfToken mjcStiffness;
   /// \brief "muscle"
   ///
   /// Possible value for MjcPhysicsActuatorAPI::GetMjcBiasTypeAttr(), Possible
@@ -498,7 +564,8 @@ struct MjcPhysicsTokensType {
   ///
   /// Possible value for MjcPhysicsActuatorAPI::GetMjcActLimitedAttr(), Possible
   /// value for MjcPhysicsActuatorAPI::GetMjcCtrlLimitedAttr(), Possible value
-  /// for MjcPhysicsActuatorAPI::GetMjcForceLimitedAttr()
+  /// for MjcPhysicsActuatorAPI::GetMjcForceLimitedAttr(), Possible value for
+  /// MjcPhysicsJointAPI::GetMjcActuatorfrclimitedAttr()
   const TfToken true_;
   /// \brief "user"
   ///
@@ -522,6 +589,10 @@ struct MjcPhysicsTokensType {
   ///
   /// Schema identifier and family for MjcPhysicsActuatorAPI
   const TfToken PhysicsActuatorAPI;
+  /// \brief "PhysicsJointsAPI"
+  ///
+  /// Schema identifier and family for MjcPhysicsJointAPI
+  const TfToken PhysicsJointsAPI;
   /// \brief "SceneAPI"
   ///
   /// Schema identifier and family for MjcPhysicsSceneAPI

src/experimental/usd/mjcPhysics/generatedSchema.usda

@@ -355,3 +355,58 @@ class Keyframe "Keyframe" (
     )
 }
 
+class "PhysicsJointsAPI" (
+    doc = "API describing a Mujoco joint."
+)
+{
+    uniform token mjc:actuatorfrclimited = "auto" (
+        allowedTokens = ["false", "true", "auto"]
+        doc = "This attribute specifies whether actuator forces acting on the joint should be clamped. See Force limits for details. It is available only for scalar joints (hinge and slider) and ignored for ball and free joints. This attribute interacts with the actuatorfrcrange attribute. If this attribute is 'false', actuator force clamping is disabled. If it is 'true', actuator force clamping is enabled. If this attribute is 'auto', and autolimits is set in compiler, actuator force clamping will be enabled if actuatorfrcrange is defined."
+    )
+    uniform double mjc:actuatorfrcrange:max = 0 (
+        doc = "Maximum range for clamping total actuator forces acting on this joint. See Force limits for details. It is available only for scalar joints (hinge and slider) and ignored for ball and free joints. The compiler expects the first value to be smaller than the second value. Setting this attribute without specifying actuatorfrclimited is an error if compiler-autolimits is 'false'."
+    )
+    uniform double mjc:actuatorfrcrange:min = 0 (
+        doc = "Minimum range for clamping total actuator forces acting on this joint. See Force limits for details. It is available only for scalar joints (hinge and slider) and ignored for ball and free joints. The compiler expects the first value to be smaller than the second value. Setting this attribute without specifying actuatorfrclimited is an error if compiler-autolimits is 'false'."
+    )
+    uniform bool mjc:actuatorgravcomp = 0 (
+        doc = "If this flag is enabled, gravity compensation applied to this joint is added to actuator forces (mjData.qfrc_actuator) rather than passive forces (mjData.qfrc_passive). Notionally, this means that gravity compensation is the result of a control system rather than natural buoyancy. In practice, enabling this flag is useful when joint-level actuator force clamping is used. In this case, the total actuation force applied on a joint, including gravity compensation, is guaranteed to not exceed the specified limits. See Force limits and actuatorfrcrange for more details on this type of force limit."
+    )
+    uniform double mjc:armature = 0 (
+        doc = "Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually due to a rotor (a.k.a armature) spinning faster than the joint itself due to a geared transmission. The value applies to all degrees of freedom created by this joint. Besides increasing the realism of joints with geared transmission, positive armature significantly improves simulation stability, even for small values, and is a recommended possible fix when encountering stability issues."
+    )
+    uniform double mjc:damping = 0 (
+        doc = "Damping applied to all degrees of freedom created by this joint. Unlike friction loss which is computed by the constraint solver, damping is simply a force linear in velocity. It is included in the passive forces. Despite this simplicity, larger damping values can make numerical integrators unstable, which is why our Euler integrator handles damping implicitly. See Integration in the Computation chapter."
+    )
+    uniform double mjc:frictionloss = 0 (
+        doc = "Friction loss due to dry friction. This value is the same for all degrees of freedom created by this joint. Semantically friction loss does not make sense for free joints, but the compiler allows it. To enable friction loss, set this attribute to a positive value."
+    )
+    uniform double mjc:margin = 0 (
+        doc = "The distance threshold below which limits become active. Recall that the Constraint solver normally generates forces as soon as a constraint becomes active, even if the margin parameter makes that happen at a distance. This attribute together with solreflimit and solimplimit can be used to model a soft joint limit."
+    )
+    uniform double mjc:ref = 0 (
+        doc = "The reference position or angle of the joint. This attribute is only used for slide and hinge joints. It defines the joint value corresponding to the initial model configuration. The amount of spatial transformation that the joint applies at runtime equals the current joint value stored in mjData.qpos minus this reference value stored in mjModel.qpos0. The meaning of these vectors was discussed in the Stand-alone section in the Overview chapter."
+    )
+    uniform double[] mjc:solimpfriction = [0.9, 0.95, 0.001, 0.5, 2] (
+        doc = "Constraint solver parameters for simulating dry friction."
+    )
+    uniform double[] mjc:solimplimit = [0.9, 0.95, 0.001, 0.5, 2] (
+        doc = "Constraint solver parameters for simulating joint limits."
+    )
+    uniform double[] mjc:solreffriction = [0.02, 1] (
+        doc = "Constraint solver parameters for simulating dry friction."
+    )
+    uniform double[] mjc:solreflimit = [0.02, 1] (
+        doc = "Constraint solver parameters for simulating joint limits."
+    )
+    uniform double[] mjc:springdamper = [0, 0] (
+        doc = "When both numbers are positive, the compiler will override any stiffness and damping values specified with the attributes below, and will instead set them automatically so that the resulting mass-spring-damper for this joint has the desired time constant (first value) and damping ratio (second value). This is done by taking into account the joint inertia in the model reference configuration. Note that the format is the same as the solref parameter of the constraint solver."
+    )
+    uniform double mjc:springref = 0 (
+        doc = "The joint position or angle in which the joint spring (if any) achieves equilibrium. Similar to the vector mjModel.qpos0 which stores all joint reference values specified with the ref attribute above, all spring reference values specified with this attribute are stored in the vector mjModel.qpos_spring. The model configuration corresponding to mjModel.qpos_spring is also used to compute the spring reference lengths of all tendons, stored in mjModel.tendon_lengthspring. This is because tendons can also have springs."
+    )
+    uniform double mjc:stiffness = 0 (
+        doc = "Joint stiffness. If this value is positive, a spring will be created with equilibrium position given by springref below. The spring force is computed along with the other passive forces."
+    )
+}
+

src/experimental/usd/mjcPhysics/jointAPI.cpp

@@ -0,0 +1,303 @@
+// Copyright 2025 DeepMind Technologies Limited
+//
+// 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 <mujoco/experimental/usd/mjcPhysics/jointAPI.h>
+
+#include <pxr/usd/sdf/assetPath.h>
+#include <pxr/usd/sdf/types.h>
+#include <pxr/usd/usd/schemaRegistry.h>
+#include <pxr/usd/usd/typed.h>
+
+PXR_NAMESPACE_OPEN_SCOPE
+
+// Register the schema with the TfType system.
+TF_REGISTRY_FUNCTION(TfType) {
+  TfType::Define<MjcPhysicsJointAPI, TfType::Bases<UsdAPISchemaBase> >();
+}
+
+/* virtual */
+MjcPhysicsJointAPI::~MjcPhysicsJointAPI() {}
+
+/* static */
+MjcPhysicsJointAPI MjcPhysicsJointAPI::Get(const UsdStagePtr &stage,
+                                           const SdfPath &path) {
+  if (!stage) {
+    TF_CODING_ERROR("Invalid stage");
+    return MjcPhysicsJointAPI();
+  }
+  return MjcPhysicsJointAPI(stage->GetPrimAtPath(path));
+}
+
+/* virtual */
+UsdSchemaKind MjcPhysicsJointAPI::_GetSchemaKind() const {
+  return MjcPhysicsJointAPI::schemaKind;
+}
+
+/* static */
+bool MjcPhysicsJointAPI::CanApply(const UsdPrim &prim, std::string *whyNot) {
+  return prim.CanApplyAPI<MjcPhysicsJointAPI>(whyNot);
+}
+
+/* static */
+MjcPhysicsJointAPI MjcPhysicsJointAPI::Apply(const UsdPrim &prim) {
+  if (prim.ApplyAPI<MjcPhysicsJointAPI>()) {
+    return MjcPhysicsJointAPI(prim);
+  }
+  return MjcPhysicsJointAPI();
+}
+
+/* static */
+const TfType &MjcPhysicsJointAPI::_GetStaticTfType() {
+  static TfType tfType = TfType::Find<MjcPhysicsJointAPI>();
+  return tfType;
+}
+
+/* static */
+bool MjcPhysicsJointAPI::_IsTypedSchema() {
+  static bool isTyped = _GetStaticTfType().IsA<UsdTyped>();
+  return isTyped;
+}
+
+/* virtual */
+const TfType &MjcPhysicsJointAPI::_GetTfType() const {
+  return _GetStaticTfType();
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcSpringdamperAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcSpringdamper);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcSpringdamperAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcSpringdamper, SdfValueTypeNames->DoubleArray,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcSolreflimitAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcSolreflimit);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcSolreflimitAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcSolreflimit, SdfValueTypeNames->DoubleArray,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcSolimplimitAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcSolimplimit);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcSolimplimitAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcSolimplimit, SdfValueTypeNames->DoubleArray,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcSolreffrictionAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcSolreffriction);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcSolreffrictionAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcSolreffriction, SdfValueTypeNames->DoubleArray,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcSolimpfrictionAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcSolimpfriction);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcSolimpfrictionAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcSolimpfriction, SdfValueTypeNames->DoubleArray,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcStiffnessAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcStiffness);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcStiffnessAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcStiffness, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcActuatorfrcrangeMinAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcActuatorfrcrangeMin);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcActuatorfrcrangeMinAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcActuatorfrcrangeMin, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcActuatorfrcrangeMaxAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcActuatorfrcrangeMax);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcActuatorfrcrangeMaxAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcActuatorfrcrangeMax, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcActuatorfrclimitedAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcActuatorfrclimited);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcActuatorfrclimitedAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcActuatorfrclimited, SdfValueTypeNames->Token,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcActuatorgravcompAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcActuatorgravcomp);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcActuatorgravcompAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcActuatorgravcomp, SdfValueTypeNames->Bool,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcMarginAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcMargin);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcMarginAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcMargin, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcRefAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcRef);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcRefAttr(VtValue const &defaultValue,
+                                                  bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcRef, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcSpringrefAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcSpringref);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcSpringrefAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcSpringref, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcArmatureAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcArmature);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcArmatureAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcArmature, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcDampingAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcDamping);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcDampingAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcDamping, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+UsdAttribute MjcPhysicsJointAPI::GetMjcFrictionlossAttr() const {
+  return GetPrim().GetAttribute(MjcPhysicsTokens->mjcFrictionloss);
+}
+
+UsdAttribute MjcPhysicsJointAPI::CreateMjcFrictionlossAttr(
+    VtValue const &defaultValue, bool writeSparsely) const {
+  return UsdSchemaBase::_CreateAttr(
+      MjcPhysicsTokens->mjcFrictionloss, SdfValueTypeNames->Double,
+      /* custom = */ false, SdfVariabilityUniform, defaultValue, writeSparsely);
+}
+
+namespace {
+static inline TfTokenVector _ConcatenateAttributeNames(
+    const TfTokenVector &left, const TfTokenVector &right) {
+  TfTokenVector result;
+  result.reserve(left.size() + right.size());
+  result.insert(result.end(), left.begin(), left.end());
+  result.insert(result.end(), right.begin(), right.end());
+  return result;
+}
+}  // namespace
+
+/*static*/
+const TfTokenVector &MjcPhysicsJointAPI::GetSchemaAttributeNames(
+    bool includeInherited) {
+  static TfTokenVector localNames = {
+      MjcPhysicsTokens->mjcSpringdamper,
+      MjcPhysicsTokens->mjcSolreflimit,
+      MjcPhysicsTokens->mjcSolimplimit,
+      MjcPhysicsTokens->mjcSolreffriction,
+      MjcPhysicsTokens->mjcSolimpfriction,
+      MjcPhysicsTokens->mjcStiffness,
+      MjcPhysicsTokens->mjcActuatorfrcrangeMin,
+      MjcPhysicsTokens->mjcActuatorfrcrangeMax,
+      MjcPhysicsTokens->mjcActuatorfrclimited,
+      MjcPhysicsTokens->mjcActuatorgravcomp,
+      MjcPhysicsTokens->mjcMargin,
+      MjcPhysicsTokens->mjcRef,
+      MjcPhysicsTokens->mjcSpringref,
+      MjcPhysicsTokens->mjcArmature,
+      MjcPhysicsTokens->mjcDamping,
+      MjcPhysicsTokens->mjcFrictionloss,
+  };
+  static TfTokenVector allNames = _ConcatenateAttributeNames(
+      UsdAPISchemaBase::GetSchemaAttributeNames(true), localNames);
+
+  if (includeInherited)
+    return allNames;
+  else
+    return localNames;
+}
+
+PXR_NAMESPACE_CLOSE_SCOPE
+
+// ===================================================================== //
+// Feel free to add custom code below this line. It will be preserved by
+// the code generator.
+//
+// Just remember to wrap code in the appropriate delimiters:
+// 'PXR_NAMESPACE_OPEN_SCOPE', 'PXR_NAMESPACE_CLOSE_SCOPE'.
+// ===================================================================== //
+// --(BEGIN CUSTOM CODE)--

src/experimental/usd/mjcPhysics/plugInfo.json

@@ -23,6 +23,16 @@
             ],
             "schemaKind": "singleApplyAPI"
           },
+          "MjcPhysicsJointAPI": {
+            "alias": {
+              "UsdSchemaBase": "PhysicsJointsAPI"
+            },
+            "autoGenerated": true,
+            "bases": [
+              "UsdAPISchemaBase"
+            ],
+            "schemaKind": "singleApplyAPI"
+          },
           "MjcPhysicsKeyframe": {
             "alias": {
               "UsdSchemaBase": "Keyframe"

src/experimental/usd/mjcPhysics/schema.usda

@@ -695,3 +695,78 @@ class Keyframe "Keyframe"
   )
 }
 
+class "PhysicsJointsAPI"
+(
+    customData = {
+        string className = "JointAPI"
+    }
+    doc = """API describing a Mujoco joint."""
+
+    inherits = </APISchemaBase>
+)
+{
+    uniform double[] mjc:springdamper = [0, 0] (
+        doc = "When both numbers are positive, the compiler will override any stiffness and damping values specified with the attributes below, and will instead set them automatically so that the resulting mass-spring-damper for this joint has the desired time constant (first value) and damping ratio (second value). This is done by taking into account the joint inertia in the model reference configuration. Note that the format is the same as the solref parameter of the constraint solver."
+    )
+
+    uniform double[] mjc:solreflimit = [0.02, 1.0] (
+        doc = "Constraint solver parameters for simulating joint limits."
+    )
+
+    uniform double[] mjc:solimplimit = [0.9, 0.95, 0.001, 0.5, 2.0] (
+        doc = "Constraint solver parameters for simulating joint limits."
+    )
+
+    uniform double[] mjc:solreffriction = [0.02, 1.0] (
+        doc = "Constraint solver parameters for simulating dry friction."
+    )
+
+    uniform double[] mjc:solimpfriction = [0.9, 0.95, 0.001, 0.5, 2.0] (
+        doc = "Constraint solver parameters for simulating dry friction."
+    )
+
+    uniform double mjc:stiffness = 0 (
+        doc = "Joint stiffness. If this value is positive, a spring will be created with equilibrium position given by springref below. The spring force is computed along with the other passive forces."
+    )
+
+    uniform double mjc:actuatorfrcrange:min = 0 (
+        doc = "Minimum range for clamping total actuator forces acting on this joint. See Force limits for details. It is available only for scalar joints (hinge and slider) and ignored for ball and free joints. The compiler expects the first value to be smaller than the second value. Setting this attribute without specifying actuatorfrclimited is an error if compiler-autolimits is 'false'."
+    )
+
+    uniform double mjc:actuatorfrcrange:max = 0 (
+        doc = "Maximum range for clamping total actuator forces acting on this joint. See Force limits for details. It is available only for scalar joints (hinge and slider) and ignored for ball and free joints. The compiler expects the first value to be smaller than the second value. Setting this attribute without specifying actuatorfrclimited is an error if compiler-autolimits is 'false'."
+    )
+
+    uniform token mjc:actuatorfrclimited = "auto" (
+        doc = "This attribute specifies whether actuator forces acting on the joint should be clamped. See Force limits for details. It is available only for scalar joints (hinge and slider) and ignored for ball and free joints. This attribute interacts with the actuatorfrcrange attribute. If this attribute is 'false', actuator force clamping is disabled. If it is 'true', actuator force clamping is enabled. If this attribute is 'auto', and autolimits is set in compiler, actuator force clamping will be enabled if actuatorfrcrange is defined."
+        allowedTokens = ["false", "true", "auto"]
+    )
+
+    uniform bool mjc:actuatorgravcomp = false (
+        doc = "If this flag is enabled, gravity compensation applied to this joint is added to actuator forces (mjData.qfrc_actuator) rather than passive forces (mjData.qfrc_passive). Notionally, this means that gravity compensation is the result of a control system rather than natural buoyancy. In practice, enabling this flag is useful when joint-level actuator force clamping is used. In this case, the total actuation force applied on a joint, including gravity compensation, is guaranteed to not exceed the specified limits. See Force limits and actuatorfrcrange for more details on this type of force limit."
+    )
+
+    uniform double mjc:margin = 0 (
+        doc = "The distance threshold below which limits become active. Recall that the Constraint solver normally generates forces as soon as a constraint becomes active, even if the margin parameter makes that happen at a distance. This attribute together with solreflimit and solimplimit can be used to model a soft joint limit."
+    )
+
+    uniform double mjc:ref = 0 (
+        doc = "The reference position or angle of the joint. This attribute is only used for slide and hinge joints. It defines the joint value corresponding to the initial model configuration. The amount of spatial transformation that the joint applies at runtime equals the current joint value stored in mjData.qpos minus this reference value stored in mjModel.qpos0. The meaning of these vectors was discussed in the Stand-alone section in the Overview chapter."
+    )
+
+    uniform double mjc:springref = 0 (
+        doc = "The joint position or angle in which the joint spring (if any) achieves equilibrium. Similar to the vector mjModel.qpos0 which stores all joint reference values specified with the ref attribute above, all spring reference values specified with this attribute are stored in the vector mjModel.qpos_spring. The model configuration corresponding to mjModel.qpos_spring is also used to compute the spring reference lengths of all tendons, stored in mjModel.tendon_lengthspring. This is because tendons can also have springs."
+    )
+
+    uniform double mjc:armature = 0 (
+        doc = "Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually due to a rotor (a.k.a armature) spinning faster than the joint itself due to a geared transmission. The value applies to all degrees of freedom created by this joint. Besides increasing the realism of joints with geared transmission, positive armature significantly improves simulation stability, even for small values, and is a recommended possible fix when encountering stability issues."
+    )
+
+    uniform double mjc:damping = 0 (
+        doc = "Damping applied to all degrees of freedom created by this joint. Unlike friction loss which is computed by the constraint solver, damping is simply a force linear in velocity. It is included in the passive forces. Despite this simplicity, larger damping values can make numerical integrators unstable, which is why our Euler integrator handles damping implicitly. See Integration in the Computation chapter."
+    )
+
+    uniform double mjc:frictionloss = 0 (
+        doc = "Friction loss due to dry friction. This value is the same for all degrees of freedom created by this joint. Semantically friction loss does not make sense for free joints, but the compiler allows it. To enable friction loss, set this attribute to a positive value."
+    )
+}

src/experimental/usd/mjcPhysics/tokens.cpp

@@ -39,6 +39,11 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
       mjcActLimited("mjc:actLimited", TfToken::Immortal),
       mjcActRangeMax("mjc:actRange:max", TfToken::Immortal),
       mjcActRangeMin("mjc:actRange:min", TfToken::Immortal),
+      mjcActuatorfrclimited("mjc:actuatorfrclimited", TfToken::Immortal),
+      mjcActuatorfrcrangeMax("mjc:actuatorfrcrange:max", TfToken::Immortal),
+      mjcActuatorfrcrangeMin("mjc:actuatorfrcrange:min", TfToken::Immortal),
+      mjcActuatorgravcomp("mjc:actuatorgravcomp", TfToken::Immortal),
+      mjcArmature("mjc:armature", TfToken::Immortal),
       mjcBiasPrm("mjc:biasPrm", TfToken::Immortal),
       mjcBiasType("mjc:biasType", TfToken::Immortal),
       mjcCrankLength("mjc:crankLength", TfToken::Immortal),
@@ -46,6 +51,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
       mjcCtrlLimited("mjc:ctrlLimited", TfToken::Immortal),
       mjcCtrlRangeMax("mjc:ctrlRange:max", TfToken::Immortal),
       mjcCtrlRangeMin("mjc:ctrlRange:min", TfToken::Immortal),
+      mjcDamping("mjc:damping", TfToken::Immortal),
       mjcDynPrm("mjc:dynPrm", TfToken::Immortal),
       mjcDynType("mjc:dynType", TfToken::Immortal),
       mjcFlagActuation("mjc:flag:actuation", TfToken::Immortal),
@@ -74,6 +80,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
       mjcForceLimited("mjc:forceLimited", TfToken::Immortal),
       mjcForceRangeMax("mjc:forceRange:max", TfToken::Immortal),
       mjcForceRangeMin("mjc:forceRange:min", TfToken::Immortal),
+      mjcFrictionloss("mjc:frictionloss", TfToken::Immortal),
       mjcGainPrm("mjc:gainPrm", TfToken::Immortal),
       mjcGainType("mjc:gainType", TfToken::Immortal),
       mjcGear("mjc:gear", TfToken::Immortal),
@@ -81,6 +88,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
       mjcJointInParent("mjc:jointInParent", TfToken::Immortal),
       mjcLengthRangeMax("mjc:lengthRange:max", TfToken::Immortal),
       mjcLengthRangeMin("mjc:lengthRange:min", TfToken::Immortal),
+      mjcMargin("mjc:margin", TfToken::Immortal),
       mjcMpos("mjc:mpos", TfToken::Immortal),
       mjcMquat("mjc:mquat", TfToken::Immortal),
       mjcOptionActuatorgroupdisable("mjc:option:actuatorgroupdisable",
@@ -114,9 +122,17 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
       mjcOptionWind("mjc:option:wind", TfToken::Immortal),
       mjcQpos("mjc:qpos", TfToken::Immortal),
       mjcQvel("mjc:qvel", TfToken::Immortal),
+      mjcRef("mjc:ref", TfToken::Immortal),
       mjcRefSite("mjc:refSite", TfToken::Immortal),
       mjcShellinertia("mjc:shellinertia", TfToken::Immortal),
       mjcSliderSite("mjc:sliderSite", TfToken::Immortal),
+      mjcSolimpfriction("mjc:solimpfriction", TfToken::Immortal),
+      mjcSolimplimit("mjc:solimplimit", TfToken::Immortal),
+      mjcSolreffriction("mjc:solreffriction", TfToken::Immortal),
+      mjcSolreflimit("mjc:solreflimit", TfToken::Immortal),
+      mjcSpringdamper("mjc:springdamper", TfToken::Immortal),
+      mjcSpringref("mjc:springref", TfToken::Immortal),
+      mjcStiffness("mjc:stiffness", TfToken::Immortal),
       muscle("muscle", TfToken::Immortal),
       newton("newton", TfToken::Immortal),
       none("none", TfToken::Immortal),
@@ -131,6 +147,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
       Keyframe("Keyframe", TfToken::Immortal),
       MeshCollisionAPI("MeshCollisionAPI", TfToken::Immortal),
       PhysicsActuatorAPI("PhysicsActuatorAPI", TfToken::Immortal),
+      PhysicsJointsAPI("PhysicsJointsAPI", TfToken::Immortal),
       SceneAPI("SceneAPI", TfToken::Immortal),
       SiteAPI("SiteAPI", TfToken::Immortal),
       allTokens({affine,
@@ -155,6 +172,11 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
                  mjcActLimited,
                  mjcActRangeMax,
                  mjcActRangeMin,
+                 mjcActuatorfrclimited,
+                 mjcActuatorfrcrangeMax,
+                 mjcActuatorfrcrangeMin,
+                 mjcActuatorgravcomp,
+                 mjcArmature,
                  mjcBiasPrm,
                  mjcBiasType,
                  mjcCrankLength,
@@ -162,6 +184,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
                  mjcCtrlLimited,
                  mjcCtrlRangeMax,
                  mjcCtrlRangeMin,
+                 mjcDamping,
                  mjcDynPrm,
                  mjcDynType,
                  mjcFlagActuation,
@@ -190,6 +213,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
                  mjcForceLimited,
                  mjcForceRangeMax,
                  mjcForceRangeMin,
+                 mjcFrictionloss,
                  mjcGainPrm,
                  mjcGainType,
                  mjcGear,
@@ -197,6 +221,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
                  mjcJointInParent,
                  mjcLengthRangeMax,
                  mjcLengthRangeMin,
+                 mjcMargin,
                  mjcMpos,
                  mjcMquat,
                  mjcOptionActuatorgroupdisable,
@@ -227,9 +252,17 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
                  mjcOptionWind,
                  mjcQpos,
                  mjcQvel,
+                 mjcRef,
                  mjcRefSite,
                  mjcShellinertia,
                  mjcSliderSite,
+                 mjcSolimpfriction,
+                 mjcSolimplimit,
+                 mjcSolreffriction,
+                 mjcSolreflimit,
+                 mjcSpringdamper,
+                 mjcSpringref,
+                 mjcStiffness,
                  muscle,
                  newton,
                  none,
@@ -244,6 +277,7 @@ MjcPhysicsTokensType::MjcPhysicsTokensType()
                  Keyframe,
                  MeshCollisionAPI,
                  PhysicsActuatorAPI,
+                 PhysicsJointsAPI,
                  SceneAPI,
                  SiteAPI}) {}