SimReady Conform FET_022_NEWTON
Purpose
Use this exact feature skill when the selected profile, validation report, or user request names FET_022_NEWTON. It repairs or stages Newton driven-joint conformance without drifting into another runtime contract.
Default to FET_022_NEWTON@0.1.0 when the user asks for this feature without a version. Use an older integer version only when the profile, validation report, or user explicitly pins it. If the report names a different FET_###_RUNTIME feature, switch to that feature's matching skill before editing.
Source of Truth
Before changing an asset or package, read:
nv_core/tiers/simready_foundation_tier_core/simready/foundation/tier_core/features/FET_022_NEWTON-0.1.0.json
nv_core/tiers/simready_foundation_tier_core/simready/foundation/tier_core/features/FET_022_NEWTON.md
Treat the selected JSON manifest as authoritative for dependencies and requirement IDs. Use the feature markdown for human-readable contract details, requirement links, samples, benchmarks, and adapters.
Feature Versions
Newton Actuation Vocabulary
This feature uses the published Newton USD schemas (newton-usd-schemas) for joint tuning
and actuation. Author these on the Newton runtime layer only; keep the composed stage
strictly Newton (RV.011: no Mjc* / Physx* schemas or attributes).
- Joint tuning —
NewtonJointAPI on each UsdPhysics.Joint (NEWTON.DJ.002):
newton:armature, newton:damping, newton:friction — finite and non-negative.
newton:velocityLimit — positive, or inf for no clamping.
newton:limitStiffness, newton:limitDamping — finite and non-negative, or the -inf
sentinel that defers to the engine default (limitStiffness may also be inf for a hard
limit). All values broadcast to every DOF; angular attributes use degrees. The bare
newton:* attributes without the applied API are also accepted.
- Actuation (
NEWTON.DJ.001) — each non-fixed articulation joint must be actuated in exactly
one of three ways (unless physics:excludeFromArticulation = true): a PhysicsDriveAPI:<axis>,
a NewtonActuator that targets it, or a NewtonMimicAPI coupling to a leader joint. A mimic
follower is actuated indirectly through the coupling, so it needs no drive or actuator of its
own. In an isolated Newton runtime layer, give each joint exactly one actuation source to avoid
double-driving. The usual pattern removes the neutral PhysicsDriveAPI:angular (and
PhysicsJointStateAPI:angular) in the Newton runnable and drives the leaders via NewtonActuator.
Keep the standard PhysicsDriveAPI only when the same joint must serve multiple runtimes in one
composition.
NewtonActuator (typed prim): rel newton:targets -> a PhysicsRevoluteJoint or
PhysicsPrismaticJoint (first target honored). Actuators use radians.
- Apply exactly one control law:
NewtonPDControlAPI (newton:kp, newton:kd,
newton:constEffort), NewtonPIDControlAPI (adds newton:ki, newton:integralMax), or
NewtonNeuralControlAPI (newton:modelPath).
- Optional clamps:
NewtonMaxEffortClampingAPI (newton:maxEffort),
NewtonDCMotorClampingAPI (newton:maxMotorEffort, newton:saturationEffort,
newton:velocityLimit), NewtonPositionBasedClampingAPI (newton:lookupPositions,
newton:lookupEfforts). Optional NewtonActuatorDelayAPI (newton:delaySteps, integer >= 0).
- Authored gains/clamps must be finite and non-negative;
newton:constEffort finite.
- Do not guess actuator gains. Derive them from the source robot's servo/drive parameters
(for example, map MuJoCo servo gains to
newton:kp/newton:kd and neutral
maxForce to newton:maxEffort).
- Mimic (coupled) joints —
NewtonMimicAPI on the follower UsdPhysics.Joint
(NEWTON.DJ.003): author rel newton:mimicJoint pointing at exactly one leader joint (never
the follower itself), with finite newton:mimicCoef0 (offset) and newton:mimicCoef1 (scale)
enforcing joint0 = coef0 + coef1 * joint1; newton:mimicEnabled is a boolean. Apply only on
single-DOF joints — a parallel-jaw gripper's second finger typically mimics the first with
coef1 = 1.0 (or -1.0 to reverse). Do not invent a mimic relationship: only author it when
the source mechanism is actually coupled.
- Mimic followers carry no drive (avoid the hollow pass). As of
NEWTON.DJ.001, a
NewtonMimicAPI follower is a valid actuation form on its own: the coupling ties the follower's
DOF to its leader, so the follower needs no PhysicsDriveAPI or NewtonActuator. Author the
mimic coupling and leave the follower drive-less — this is the clean, non-hollow pattern. Do
not add an inert placeholder drive (older assets did this before the rule accepted mimic
followers; it is now unnecessary), and never add an active or damped follower drive: a
non-zero-stiffness/damping follower drive with a fixed target fights the leader through the
coupling and can pin the whole mechanism — it passes static NEWTON.DJ.* validation but the
leader barely moves in simulation (a hollow pass). Drive only the leader joint(s), via a
NewtonActuator (preferred) or a PhysicsDriveAPI with gains strong enough for the Newton
solver; runtime-neutral gains tuned for PhysX are usually far too soft. Verify real travel with
runtime evidence (for example simready-benchmark joint_movement) before trusting the pass —
a wide driven-joint tolerance can otherwise mask a near-zero leader motion.
- Armature for stability on tightly-coupled loops. On closely-packed, mimic-coupled
mechanisms (parallel-jaw grippers, four-bar finger linkages) the Newton solver is prone to
instability. Authoring
newton:armature (via NewtonJointAPI, NEWTON.DJ.002) augments each
DOF's rotational inertia and markedly stabilizes the solver across the coupled loop without
changing the observed travel. Derive values from the source robot's Newton reference where one
exists; the Newton team's tuned robotiq_2f85 reference uses roughly newton:armature = 0.005
on the driven leader joint and 0.001 on the mimic followers as a sound starting point. Keep
every value finite and non-negative.
Parallel-Jaw Gripper Grasp (Newton)
A parallel-jaw gripper (for example the Robotiq 2F-85) that must actually hold an object in a
grasp-and-lift test (FET_028) needs more than a statically-valid driven-joint graph. Patterns
that pass NEWTON.DJ.* but drop the object in simulation, and their fixes:
- Drive both jaw leaders, symmetrically and gently. Driving one jaw leader and letting the
opposite jaw only mimic it makes the following jaw go slack on off-center or spherical objects,
which then squirt/roll out. Instead give each jaw leader its own matched
NewtonActuator
(same newton:kp/newton:kd) and split the linkage so each jaw's passive followers mimic that
jaw's leader. Keep the effort gentle (the 2F-85 uses newton:maxEffort ≈ 2.5 per jaw) so
the close conforms to the object instead of slamming/ejecting it.
- Give the pads a real, RV.011-clean contact surface. A
purpose = "guide" box collider is
skipped by the benchmark's grip geometry (it computes bounds over default/render purposes)
and by Newton, so the fingers have nothing to grip with. Instead reuse the actual rubber-pad
mesh: in the Newton layer de-instance the fingertip pad mesh, delete its Physx*CollisionAPI
schemas, and prepend NewtonCollisionAPI + NewtonMeshCollisionAPI (convex hull) bound to a
high-friction NewtonMaterialAPI (see FET_003_NEWTON). This keeps the composition RV.011-clean
(no leaked PhysX collision) while giving a large flat contact patch. If you must keep a separate
proxy collider hidden from render, use visibility = "invisible" with default purpose, never
purpose = "guide".
- The
FET_028 grasp behavior is proven by runtime evidence (simready-benchmark
gripper_close_lift_{cube,sphere}), not static validation; report it as a runtime check.
Workflow
- Confirm the input exists and identify the exact selected feature/version from the profile TOML, validation report, or user request.
- Load the selected
FET_022_NEWTON manifest and the feature markdown before editing.
- Load requirement docs linked from the feature markdown for every reported failing requirement.
- Create or use a staged output location unless the user explicitly asks for in-place edits.
- Repair only the requirements listed by the selected
FET_022_NEWTON manifest and its dependencies.
- Rerun the same profile gate or the narrowest available feature/capability validation gate. If runtime evidence is required and unavailable, report that limitation instead of claiming a pass.
- Summarize the selected
FET_022_NEWTON version, changed files, validation evidence, and the first remaining blocker or next exact feature gate.
Feature Guidance
- Repair only the requirements listed by the selected
FET_022_NEWTON manifest and its dependencies.
- Author
NewtonJointAPI tuning and NewtonActuator actuation per the vocabulary above; do
not apply Mjc* / Physx* joint or actuator schemas on the Newton layer.
- On coupled (mimic) mechanisms, leave the followers drive-less — the
NewtonMimicAPI coupling
satisfies NEWTON.DJ.001 — and tune only the leader(s). Do not author inert placeholder drives,
and never add an active follower drive: it passes static validation but resists the leader and
pins the mechanism in simulation.
- For parallel-jaw grippers that must hold an object, drive both jaw leaders with matched gentle
NewtonActuators and give the pads a real RV.011-clean mesh collider (see "Parallel-Jaw Gripper
Grasp" above); a single-jaw drive or a purpose = "guide" collider passes validation but drops
the object in the grasp benchmark.
- On tightly-coupled loops, author
newton:armature (finite, non-negative) on every articulation
joint for Newton solver stability — for example ~0.005 on the driven leader and ~0.001 on
mimic followers — sourced from the robot's Newton reference where one exists.
- Do not add schemas, metadata, or runtime behavior for a sibling runtime feature.
- Report missing runtime/tooling evidence as a validation limitation instead of claiming a pass.
Samples
sample_content/common_assets/robots_general/Robotiq/2F-85/simready_usd/runnables/physics/newton.usda
— parallel-jaw gripper: two gentle NewtonActuators driving both jaw leaders, drive-less
NewtonMimicAPI followers split per jaw, newton:armature on the leaders, and RV.011-clean pad
contact (de-instanced fingertip mesh with NewtonMeshCollisionAPI bound to a high-friction
NewtonMaterialAPI).
Report Fields
| Field |
Meaning |
feature |
Exact feature ID and version, for example FET_022_NEWTON@0.1.0. |
input |
Source asset, package root, or package definition inspected. |
output |
Staged output path, or in-place only when explicitly requested. |
requirements_repaired |
Requirement IDs repaired in this pass. |
validation |
Command or inspection used to verify this exact feature. |
status |
passed, failed, skipped, or blocked. |
next_step |
The next exact feature skill or user/runtime evidence needed. |
1---2name: simready-foundation-conform-fet-022-newton3description: "Use for repairing exact FET_022_NEWTON SimReady conformance for Newton driven-joint conformance. Use when a profile, validation report, or user request names FET_022_NEWTON; default to version `0.1.0` unless a profile or report pins another version."4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/nvidia/simready-foundation-conform-fet-022-newton7 author: "Shaad Boochoon <sboochoon@nvidia.com>"8 tags:9 - simready10 - conformance11 - newton12---1314# SimReady Conform FET_022_NEWTON1516## Purpose1718Use this exact feature skill when the selected profile, validation report, or user request names `FET_022_NEWTON`. It repairs or stages Newton driven-joint conformance without drifting into another runtime contract.1920Default to `FET_022_NEWTON@0.1.0` when the user asks for this feature without a version. Use an older integer version only when the profile, validation report, or user explicitly pins it. If the report names a different `FET_###_RUNTIME` feature, switch to that feature's matching skill before editing.2122## Source of Truth2324Before changing an asset or package, read:2526- `nv_core/tiers/simready_foundation_tier_core/simready/foundation/tier_core/features/FET_022_NEWTON-0.1.0.json`27- `nv_core/tiers/simready_foundation_tier_core/simready/foundation/tier_core/features/FET_022_NEWTON.md`2829Treat the selected JSON manifest as authoritative for dependencies and requirement IDs. Use the feature markdown for human-readable contract details, requirement links, samples, benchmarks, and adapters.3031## Feature Versions3233| Version | Dependencies | Requirements |34|---|---|---|35| `0.1.0` | FET_004_ROBOT_NEWTON@0.1.0 | `DJ.011`, `NEWTON.DJ.001`, `NEWTON.DJ.002`, `NEWTON.DJ.003` |3637## Newton Actuation Vocabulary3839This feature uses the published Newton USD schemas (`newton-usd-schemas`) for joint tuning40and actuation. Author these on the Newton runtime layer only; keep the composed stage41strictly Newton (RV.011: no `Mjc*` / `Physx*` schemas or attributes).4243- **Joint tuning — `NewtonJointAPI`** on each `UsdPhysics.Joint` (`NEWTON.DJ.002`):44 - `newton:armature`, `newton:damping`, `newton:friction` — finite and non-negative.45 - `newton:velocityLimit` — positive, or `inf` for no clamping.46 - `newton:limitStiffness`, `newton:limitDamping` — finite and non-negative, or the `-inf`47 sentinel that defers to the engine default (`limitStiffness` may also be `inf` for a hard48 limit). All values broadcast to every DOF; angular attributes use degrees. The bare49 `newton:*` attributes without the applied API are also accepted.50- **Actuation** (`NEWTON.DJ.001`) — each non-fixed articulation joint must be actuated in exactly51 one of three ways (unless `physics:excludeFromArticulation = true`): a `PhysicsDriveAPI:<axis>`,52 a `NewtonActuator` that targets it, **or** a `NewtonMimicAPI` coupling to a leader joint. A mimic53 follower is actuated indirectly through the coupling, so it needs **no** drive or actuator of its54 own. In an isolated Newton runtime layer, give each joint exactly one actuation source to avoid55 double-driving. The usual pattern removes the neutral `PhysicsDriveAPI:angular` (and56 `PhysicsJointStateAPI:angular`) in the Newton runnable and drives the leaders via `NewtonActuator`.57 Keep the standard `PhysicsDriveAPI` only when the same joint must serve multiple runtimes in one58 composition.59 - **`NewtonActuator`** (typed prim): `rel newton:targets` -> a `PhysicsRevoluteJoint` or60 `PhysicsPrismaticJoint` (first target honored). Actuators use radians.61 - Apply exactly one control law: `NewtonPDControlAPI` (`newton:kp`, `newton:kd`,62 `newton:constEffort`), `NewtonPIDControlAPI` (adds `newton:ki`, `newton:integralMax`), or63 `NewtonNeuralControlAPI` (`newton:modelPath`).64 - Optional clamps: `NewtonMaxEffortClampingAPI` (`newton:maxEffort`),65 `NewtonDCMotorClampingAPI` (`newton:maxMotorEffort`, `newton:saturationEffort`,66 `newton:velocityLimit`), `NewtonPositionBasedClampingAPI` (`newton:lookupPositions`,67 `newton:lookupEfforts`). Optional `NewtonActuatorDelayAPI` (`newton:delaySteps`, integer >= 0).68 - Authored gains/clamps must be finite and non-negative; `newton:constEffort` finite.69- Do not guess actuator gains. Derive them from the source robot's servo/drive parameters70 (for example, map MuJoCo servo gains to `newton:kp`/`newton:kd` and neutral71 `maxForce` to `newton:maxEffort`).72- **Mimic (coupled) joints — `NewtonMimicAPI`** on the follower `UsdPhysics.Joint`73 (`NEWTON.DJ.003`): author `rel newton:mimicJoint` pointing at exactly one leader joint (never74 the follower itself), with finite `newton:mimicCoef0` (offset) and `newton:mimicCoef1` (scale)75 enforcing `joint0 = coef0 + coef1 * joint1`; `newton:mimicEnabled` is a boolean. Apply only on76 single-DOF joints — a parallel-jaw gripper's second finger typically mimics the first with77 `coef1 = 1.0` (or `-1.0` to reverse). Do not invent a mimic relationship: only author it when78 the source mechanism is actually coupled.79- **Mimic followers carry no drive (avoid the hollow pass).** As of `NEWTON.DJ.001`, a80 `NewtonMimicAPI` follower is a valid actuation form on its own: the coupling ties the follower's81 DOF to its leader, so the follower needs **no** `PhysicsDriveAPI` or `NewtonActuator`. Author the82 mimic coupling and leave the follower **drive-less** — this is the clean, non-hollow pattern. Do83 **not** add an inert placeholder drive (older assets did this before the rule accepted mimic84 followers; it is now unnecessary), and never add an **active or damped** follower drive: a85 non-zero-stiffness/damping follower drive with a fixed target fights the leader through the86 coupling and can pin the whole mechanism — it passes static `NEWTON.DJ.*` validation but the87 leader barely moves in simulation (a hollow pass). Drive only the **leader** joint(s), via a88 `NewtonActuator` (preferred) or a `PhysicsDriveAPI` with gains strong enough for the Newton89 solver; runtime-neutral gains tuned for PhysX are usually far too soft. Verify real travel with90 runtime evidence (for example `simready-benchmark` `joint_movement`) before trusting the pass —91 a wide driven-joint tolerance can otherwise mask a near-zero leader motion.92- **Armature for stability on tightly-coupled loops.** On closely-packed, mimic-coupled93 mechanisms (parallel-jaw grippers, four-bar finger linkages) the Newton solver is prone to94 instability. Authoring `newton:armature` (via `NewtonJointAPI`, `NEWTON.DJ.002`) augments each95 DOF's rotational inertia and markedly stabilizes the solver across the coupled loop without96 changing the observed travel. Derive values from the source robot's Newton reference where one97 exists; the Newton team's tuned `robotiq_2f85` reference uses roughly `newton:armature = 0.005`98 on the driven leader joint and `0.001` on the mimic followers as a sound starting point. Keep99 every value finite and non-negative.100101## Parallel-Jaw Gripper Grasp (Newton)102103A parallel-jaw gripper (for example the Robotiq 2F-85) that must actually **hold** an object in a104grasp-and-lift test (`FET_028`) needs more than a statically-valid driven-joint graph. Patterns105that pass `NEWTON.DJ.*` but drop the object in simulation, and their fixes:106107- **Drive both jaw leaders, symmetrically and gently.** Driving one jaw leader and letting the108 opposite jaw only *mimic* it makes the following jaw go slack on off-center or spherical objects,109 which then squirt/roll out. Instead give **each** jaw leader its own matched `NewtonActuator`110 (same `newton:kp`/`newton:kd`) and split the linkage so each jaw's passive followers mimic *that111 jaw's* leader. Keep the effort **gentle** (the 2F-85 uses `newton:maxEffort ≈ 2.5` per jaw) so112 the close conforms to the object instead of slamming/ejecting it.113- **Give the pads a real, RV.011-clean contact surface.** A `purpose = "guide"` box collider is114 skipped by the benchmark's grip geometry (it computes bounds over `default`/`render` purposes)115 and by Newton, so the fingers have nothing to grip with. Instead reuse the actual rubber-pad116 mesh: in the Newton layer de-instance the fingertip pad mesh, `delete` its `Physx*CollisionAPI`117 schemas, and `prepend` `NewtonCollisionAPI` + `NewtonMeshCollisionAPI` (convex hull) bound to a118 high-friction `NewtonMaterialAPI` (see `FET_003_NEWTON`). This keeps the composition RV.011-clean119 (no leaked PhysX collision) while giving a large flat contact patch. If you must keep a separate120 proxy collider hidden from render, use `visibility = "invisible"` with default purpose, never121 `purpose = "guide"`.122- The `FET_028` grasp behavior is proven by runtime evidence (`simready-benchmark`123 `gripper_close_lift_{cube,sphere}`), not static validation; report it as a runtime check.124125## Workflow1261271. Confirm the input exists and identify the exact selected feature/version from the profile TOML, validation report, or user request.1282. Load the selected `FET_022_NEWTON` manifest and the feature markdown before editing.1293. Load requirement docs linked from the feature markdown for every reported failing requirement.1304. Create or use a staged output location unless the user explicitly asks for in-place edits.1315. Repair only the requirements listed by the selected `FET_022_NEWTON` manifest and its dependencies.1326. Rerun the same profile gate or the narrowest available feature/capability validation gate. If runtime evidence is required and unavailable, report that limitation instead of claiming a pass.1337. Summarize the selected `FET_022_NEWTON` version, changed files, validation evidence, and the first remaining blocker or next exact feature gate.134135## Feature Guidance136137- Repair only the requirements listed by the selected `FET_022_NEWTON` manifest and its dependencies.138- Author `NewtonJointAPI` tuning and `NewtonActuator` actuation per the vocabulary above; do139 not apply `Mjc*` / `Physx*` joint or actuator schemas on the Newton layer.140- On coupled (mimic) mechanisms, leave the followers **drive-less** — the `NewtonMimicAPI` coupling141 satisfies `NEWTON.DJ.001` — and tune only the leader(s). Do not author inert placeholder drives,142 and never add an active follower drive: it passes static validation but resists the leader and143 pins the mechanism in simulation.144- For parallel-jaw grippers that must hold an object, drive **both** jaw leaders with matched gentle145 `NewtonActuator`s and give the pads a real RV.011-clean mesh collider (see "Parallel-Jaw Gripper146 Grasp" above); a single-jaw drive or a `purpose = "guide"` collider passes validation but drops147 the object in the grasp benchmark.148- On tightly-coupled loops, author `newton:armature` (finite, non-negative) on every articulation149 joint for Newton solver stability — for example `~0.005` on the driven leader and `~0.001` on150 mimic followers — sourced from the robot's Newton reference where one exists.151- Do not add schemas, metadata, or runtime behavior for a sibling runtime feature.152- Report missing runtime/tooling evidence as a validation limitation instead of claiming a pass.153154## Samples155156- `sample_content/common_assets/robots_general/Robotiq/2F-85/simready_usd/runnables/physics/newton.usda`157 — parallel-jaw gripper: two gentle `NewtonActuator`s driving both jaw leaders, drive-less158 `NewtonMimicAPI` followers split per jaw, `newton:armature` on the leaders, and RV.011-clean pad159 contact (de-instanced fingertip mesh with `NewtonMeshCollisionAPI` bound to a high-friction160 `NewtonMaterialAPI`).161162## Report Fields163164| Field | Meaning |165|---|---|166| `feature` | Exact feature ID and version, for example `FET_022_NEWTON@0.1.0`. |167| `input` | Source asset, package root, or package definition inspected. |168| `output` | Staged output path, or `in-place` only when explicitly requested. |169| `requirements_repaired` | Requirement IDs repaired in this pass. |170| `validation` | Command or inspection used to verify this exact feature. |171| `status` | `passed`, `failed`, `skipped`, or `blocked`. |172| `next_step` | The next exact feature skill or user/runtime evidence needed. |