Add `NewtonJointAPI`

[andrewkaufman]

Is this a new feature, an improvement, or a change to existing functionality?

New Feature

Feature Description

NewtonJointAPI is an extension to UsdPhysicsJoint to configure per-DOF joint attributes.

It is a single-apply API, with arrays specifying which DOFs are affected, and a series of equally sized arrays specifying per-DOF properties (see additional context for justification). These arrays should be indexed according to the primary dofs token array.

For single-DOF joints (Prismatic & Revolute) a special DOF token distance or angle should be specified. All other DOF tokens should match UsdPhysicsLimitAPI instance-name tokens.

The following array attributes will be provided in the initial implementation:

newton:dofs

A token array specifying the affected DOFs for this joint

An empty array can be seen as disabling the NewtonJointAPI without explicitly removing it.

newton:armature

An additional source of intertia affecting each DOF which is not due to body mass. This is often used to represent a rotor (a.k.a armature) but can also be used as a way of stabalizing simulation for some solvers.

The default value for unspecified armature is 0.

Units:

• Linear joint: mass
• Angular joint: mass * distance^2

Note: A future Actuator Prim may also provide armature, in which case this value could be omitted for actuated joints. If both are authored, the two values should be summed.

newton:staticFrictionEffort

The maximum static friction force or torque applied to resist motion in stationary joints. Prevents motion initiation until the applied force exceeds this threshold.

The default value for unspecified staticFrictionEffort is 0.

Units:

• Linear joint: force (mass * distance / second^2)
• Angular joint: torque (mass * distance^2 / second^2)

newton:dynamicFrictionEffort

Coulomb friction force or torque applied to resist motion in moving joints. Should be less than or equal to staticFrictionEffort.

The default value for unspecified dynamicFrictionEffort is 0.

Units:

• Linear joint: force (mass * distance / second^2)
• Angular joint: torque (mass * distance^2 / second^2)

newton:viscousDamping

Coefficient used to calculate velocity-dependent friction effort. Total friction effort in moving joints is:
- sign(jointVelocity) * (dynamicFrictionEffort + viscousDamping * abs(jointVelocity))

The default value for unspecified viscousDamping is 0.

Units:

• Linear joint: force * second / distance
• Angular joint: torque * second / degrees

Example

A 3 DOF "planar" joint might look like:

def Joint "Foo" (
    prepend apiSchemas = ["NewtonJointAPI"]
)
{
    uniform token[] newton:dofs = [ "transX", "transY", "rotZ" ]
    uniform float[] newton:armature = [ 0.1, 0.2, 0.3 ]
    uniform float[] newton:dynamicFrictionEffort = [10.0, 10.0, 10.0]
    // remaining attrs unspecified & use defined fallback values for all DOFs
}

Additional context or alternatives

Despite being per-DOF, NewtonJointAPI is not a multi-apply API (unlike UsdPhysicsLimitAPI). The rationalle from the design meeting is that multi-apply APIs are overly clunky in client code & drastically reduce legibility of authored content (both text USDA and in GUIs).

The only benefit we saw for multi-apply was to obtian sparse single-valued attributes, which are easier to override & timesample.

However, as Joint DOF arrays are very small (0-6 values), it should not be necessary to author them sparsly for perf reasons. The particular values on NewtonJointAPI are also uniform/static configuration of default state; there is no user need to timesample these values. Additionally, in newer USD runtimes, sparse editing of array attributes is possible, so there is no significant loss of functionailty (in the mid/long term) and dense overrides of small arrays are easy enough to manage (in the short term).

Code of Conduct

• I agree to follow newton-usd-schemas Code of Conduct
• I have searched the open issues and have found no duplicates

[andrewkaufman]

@vastsoun @preist-nvidia @havess please review the description & see if this matches what we agreed to in the meeting today. There were some extra complication to consider when I wrote it up... hopefully I inferred what you all expected.

@Milad-Rakhsha-NV @AlesBorovicka please review when you have time as well. You can watch the meeting recording first if you feel you want more context.

[andrewkaufman]

@eric-heiden @adenzler-nvidia I would appreciate your thoughts on the static/dynamicFrictionEffort & viscousDamping in particular 🙏

These don't map to anything in newton currently afaik, but PhysX does have all 3 of these per-DOF & in the schema design meeting there was agreement that they're useful for more solvers.

[AlesBorovicka]

The rationalle from the design meeting is that multi-apply APIs are overly clunky in client code & drastically reduce legibility of authored content (both text USDA and in GUIs).

This should not really be a reason, inventing new pattern does not sound like a good approach if you want this to be included in a standard. When we designed UsdPhysics the authoring was never a first principle you can always have tooling around.
With this you are tied to one setting for all DOF, its restrictive with this design more then the per dof multiple-apply schema.

[adenzler-nvidia]

I agree with Ales on the multi-apply issue.

For the main question - I don't have a strong opinion but we should probably go and prototype this in some of the solvers first. I don't know about whether kamino has such a sophisticed joint friction model, but MuJoCo definitely does not, and it's going to be hard to exactly map these parameters.

[preist-nvidia]

@AlesBorovicka - I'll defer to you and @andrewkaufman for multi-apply or not, but the config of multi-dof is possible with this, since armature, etc. are arrays that correspond to the joint dof tokens. So this is not correct:

With this you are tied to one setting for all DOF

@adenzler-nvidia @eric-heiden - for mujoco we have the dynamicFriction map to frictionloss modeling dry friction, and the viscous damping maps to damping. The static friction effort is currently only available in PhysX, so if we include it in the Newton API it may not be supported by any solver until we add it somewhere. So maybe omit for now until we have better solver support? Unless the idea of Newton schema should extend to PhysX.

[havess]

The multi-apply issue is not a hill I'll defend too strongly, I agree with Ales that it may cause some friction down the line towards adoption into a standard but to raise my 2c (and echo the meeting notes a bit) I think multi-apply schemas are confusing to people not familiar with USD, confusing to read in the scene description, and a pain to author.

Yes you can make tooling that hides the multi-apply schema but its much easier to make tooling that lets you just set values in an array. I may be biased coming from MuJoCo where most of our data is just in indexed arrays, but people seem to like the simplicity.

[yuvaltassa]

I don't have an opinion about the multi-apply business, but here are two comments that may or may not be helpful:

Dynamic friction

The default value for unspecified dynamicFrictionEffort is 0.

This seems questionable to me. IIUC, no one is supporting dynamic joint friction (or maybe PhysX does?), but let's imagine someone adds this in the future. Suddenly joints that used to always be frictional would lose all friction. Would the following not be a more sensible default?

The default value for unspecified dynamicFrictionEffort is the current value of staticFrictionEffort.

Since dynamic friction has to be leq to static, I think this would lead to less surprising behavior. But maybe the way USD defaults work make this infeasible. I suppose one way of doing this sensibly would be for the user to specify the amount by which dynamic friction is smaller than static, this way a default of 0 makes sense.

Per-dof settings for quaternions

Imagine a ball and socket joint. Let's say I want non-isotropic resistance (friction or damping), and that this is implemented in reality by say, grooves in the metal. The grooves can be either on the ball or on the socket, i.e. the anisotropy can be either in the parent frame or in child frame. Both are technically possible. In a different context (actuator transmission), MuJoCo calls this "jointinparent".

Regarding armature, I would be very, very careful about associating non-isotropic armature with a quaternion. Especially if you were thinking of doing it in the parent frame, I suspect this might turn out to be extremely nonphysical (as in, not energy or angmom conserving, blowing up in the user's face unphysical).

[preist-nvidia]

Friction

@yuvaltassa - in PhysX @jvonmuralt added a stribeck-like model combining static/dynamic dry friction and viscous friction: https://docs.omniverse.nvidia.com/kit/docs/omni_physics/latest/dev_guide/rigid_bodies_articulations/articulations.html#articulation-joint-friction

Is it correct to map MuJoCo frictionloss to dynamic = static friction efforts since it is just a constrained constant friction opposing motion?

If yes, my statement above that dynamicFrictionEffort would map to frictionloss is incorrect. Given the difference in implementation in PhysX and MuJoCo, maybe the only Newton schema should be viscousDamping, and MJCSchema determines frictionloss, and PhysXSchema continues to define the static/dynamic friction efforts.

I agree the defaults question is tricky. I think that we can solve this with the schema resolver logic @Milad-Rakhsha-NV proposed here: https://newton-physics.github.io/newton/concepts/usd_parsing.html#priority-based-resolution

I.e. the user would make the solver-specific schema higher priority, and the solver-specific schema default would win against a Newton schema default. Once a solver replaces their specific schema with newton schema, they'd adopt the Newton schema default which could change behavior, so not great / a reason not to adopt the schema. Existing assets would have to author the attribute to the solver specific default to maintain behavior.

Armature

I was not aware of stability implications of non-isotropic armature on multi-dof joints, and I can't really think of a real-world case for non-isotropic armature that you wouldn't build by composing the mechanism with multiple 1-dof joints and separate bodies.

But then we are back at the question: Should we make these joint properties apply uniformly to all dofs of the joint. IIRC the robotics folks asked us to expose per-dof in PhysX, maybe @Milad-Rakhsha-NV remembers a technical reason (beyond matching armature values 1:1 to dofs).