rename dynamics to clamping

Author: jvonmuralt

README.md

@@ -17,16 +17,17 @@ An actuator is composed from three building blocks:
 
 - **Controller** — computes raw forces from state error (PD, PID, neural network).
 - **Delay** — optional pre-controller modifier that delays targets by N timesteps.
-- **Dynamics** — post-controller modifiers that shape forces (clamping,
-  saturation, angle-dependent limits, …).
+- **Clamping** — post-controller force bounds (symmetric limits,
+  velocity-dependent saturation, angle-dependent torque curves, …).
+  Order does not matter — each clamping intersects its limits independently.
 
 The `Actuator` class wires them together:
 
 ```
 Actuator
 ├── Controller  (compute raw forces)
 ├── Delay       (optional: delays targets by N timesteps)
-└── Dynamics[]  (post-controller force modifiers, applied in order)
+└── Clamping[]  (post-controller force bounds)
     ├── Clamp              (±max_force)
     ├── DCMotorSaturation  (velocity-dependent saturation)
     └── RemotizedClamp     (angle-dependent lookup)
@@ -79,7 +80,7 @@ pip install "newton-actuators[torch-cu13]" --extra-index-url https://download.py
 
 - **PDController**: `f = constant + act + Kp·(target_pos - q) + Kd·(target_vel - v)`
 - **PIDController**: `f = constant + act + Kp·e + Ki·∫e·dt + Kd·de`
-- **NetMLPController**: `f = network(cat(pos_error_history, vel_history)) * torque_scale`
+- **NetMLPController**: `f = network(cat(pos_error_history, vel_history))`
 - **NetLSTMController**: `f, (h', c') = network(input, (h, c))`
 
 ### Delay
@@ -88,25 +89,25 @@ pip install "newton-actuators[torch-cu13]" --extra-index-url https://download.py
 |---|---|---|
 | `Delay` | Delays targets by N timesteps (circular buffer) | Yes |
 
-Passed to `Actuator` via the `delay=` parameter (not in the dynamics list).
+Passed to `Actuator` via the `delay=` parameter (not in the clamping list).
 
-### Dynamics
+### Clamping
 
-| Dynamic | Description | Stateful |
+| Clamping | Description | Stateful |
 |---|---|---|
 | `Clamp` | Box-clamp to ±max_force | No |
 | `DCMotorSaturation` | Velocity-dependent torque–speed saturation | No |
 | `RemotizedClamp` | Angle-dependent torque limits via lookup table | No |
 
 ### Actuator (Composer)
 
-`Actuator(input_indices, output_indices, controller, delay=None, dynamics=[...])`
-composes a controller with an optional delay and zero or more dynamics.
+`Actuator(input_indices, output_indices, controller, delay=None, clamping=[...])`
+composes a controller with an optional delay and zero or more clamping objects.
 The `step()` method runs:
 
 1. **Delay** — read delayed targets from buffer (skipped if no delay or buffer still filling)
 2. **Controller** — compute raw forces
-3. **Dynamics** — modify forces (e.g. `Clamp`, `DCMotorSaturation`)
+3. **Clamping** — bound forces (e.g. `Clamp`, `DCMotorSaturation`)
 4. **Scatter-add** — accumulate forces into the output array
 5. **State updates** — update delay buffer and controller state
 
@@ -120,7 +121,7 @@ The `step()` method runs:
 
 ## Workflow
 
-1. **Create an actuator** by composing a controller with dynamics
+1. **Create an actuator** by composing a controller with clamping
 2. **Check statefulness**: call `actuator.is_stateful()`
 3. **Initialize states**: for stateful actuators, create double-buffered states with `actuator.state()`
 4. **Simulation loop**: call `actuator.step()` each timestep
@@ -143,7 +144,7 @@ actuator = Actuator(
         kp=wp.array([100.0, 100.0, 100.0], dtype=wp.float32),
         kd=wp.array([10.0, 10.0, 10.0], dtype=wp.float32),
     ),
-    dynamics=[
+    clamping=[
         Clamp(max_force=wp.array([50.0, 50.0, 50.0], dtype=wp.float32)),
     ],
 )
@@ -166,7 +167,7 @@ actuator = Actuator(
         kd=wp.array([5.0, 5.0], dtype=wp.float32),
         integral_max=wp.array([10.0, 10.0], dtype=wp.float32),
     ),
-    dynamics=[
+    clamping=[
         Clamp(max_force=wp.array([50.0, 50.0], dtype=wp.float32)),
     ],
 )
@@ -182,7 +183,7 @@ for step in range(num_steps):
 
 ### Composing: PD + Delay + DC Motor Saturation
 
-The composer pattern lets you freely combine controllers and dynamics:
+The composer pattern lets you freely combine controllers and clamping:
 
 ```python
 from newton_actuators import Delay, DCMotorSaturation
@@ -192,7 +193,7 @@ actuator = Actuator(
     output_indices=indices,
     controller=PDController(kp=kp, kd=kd),
     delay=Delay(delay=5),
-    dynamics=[
+    clamping=[
         DCMotorSaturation(
             saturation_effort=sat_effort,
             velocity_limit=vel_limit,
@@ -211,7 +212,7 @@ actuator = Actuator(
     input_indices=indices,
     output_indices=indices,
     controller=NetLSTMController(network=my_lstm_model),
-    dynamics=[Clamp(max_force=max_force)],
+    clamping=[Clamp(max_force=max_force)],
 )
 
 state = actuator.state()

newton_actuators/__init__.py

@@ -12,10 +12,10 @@
     PIDController,
 )
 from ._src.delay import Delay
-from ._src.dynamics import (
+from ._src.clamping import (
     Clamp,
     DCMotorSaturation,
-    Dynamic,
+    Clamping,
     RemotizedClamp,
 )
 from ._src.usd_parser import (
@@ -35,8 +35,8 @@
     "PIDController",
     "NetMLPController",
     "NetLSTMController",
-    # Dynamics
-    "Dynamic",
+    # Clamping
+    "Clamping",
     "Clamp",
     "DCMotorSaturation",
     "Delay",

newton_actuators/_src/actuator.py

@@ -11,7 +11,7 @@
 
 from .controllers.base import Controller
 from .delay import Delay
-from .dynamics.base import Dynamic
+from .clamping.base import Clamping
 
 
 # TODO: replace with a Transmission class that applies gear ratios / linkage
@@ -33,7 +33,7 @@ class ActuatorState:
     """Composed state for an Actuator.
 
     Holds the controller state and, if a delay is present, the delay
-    state. Dynamics are stateless.
+    state. Clamping objects are stateless.
     """
 
     controller_state: Any = None
@@ -47,15 +47,15 @@ def reset(self) -> None:
 
 
 class Actuator:
-    """Composed actuator: controller + optional delay + dynamics.
+    """Composed actuator: controller + optional delay + clamping.
 
     An actuator reads from simulation state/control arrays, computes
-    forces via a controller, applies dynamics (clamping, saturation, etc.),
+    forces via a controller, applies clamping (force limits, saturation, etc.),
     and writes the result to the output array.
 
-    Delay is handled separately from dynamics because it is the only
+    Delay is handled separately from clamping because it is the only
     pre-controller modifier (it replaces targets with delayed versions).
-    All dynamics are post-controller (they modify forces).
+    All clamping is post-controller (it bounds forces).
 
     Usage::
 
@@ -64,7 +64,7 @@ class Actuator:
             output_indices=indices,
             controller=PDController(kp=kp, kd=kd),
             delay=Delay(delay=5),
-            dynamics=[Clamp(max_force=max_f)],
+            clamping=[Clamp(max_force=max_f)],
         )
 
         # Simulation loop
@@ -77,7 +77,7 @@ class Actuator:
             for single-output or (N, M) for multi-output actuators.
         controller: Controller that computes raw forces.
         delay: Optional Delay instance for input delay.
-        dynamics: List of Dynamic objects (post-controller force modifiers).
+        clamping: List of Clamping objects (post-controller force bounds).
         state_pos_attr: Attribute on sim_state for positions.
         state_vel_attr: Attribute on sim_state for velocities.
         control_target_pos_attr: Attribute on sim_control for target positions.
@@ -92,7 +92,7 @@ def __init__(
         output_indices: wp.array,
         controller: Controller,
         delay: Delay | None = None,
-        dynamics: list[Dynamic] | None = None,
+        clamping: list[Clamping] | None = None,
         state_pos_attr: str = "joint_q",
         state_vel_attr: str = "joint_qd",
         control_target_pos_attr: str = "joint_target_pos",
@@ -104,7 +104,7 @@ def __init__(
         self.output_indices = output_indices
         self.controller = controller
         self.delay = delay
-        self.dynamics = dynamics or []
+        self.clamping = clamping or []
         self.num_actuators = len(input_indices)
 
         if len(output_indices) != self.num_actuators:
@@ -128,8 +128,8 @@ def __init__(
 
         controller.set_device(device)
         controller.set_indices(input_indices, self._sequential_indices)
-        for dyn in self.dynamics:
-            dyn.set_device(device)
+        for clamp in self.clamping:
+            clamp.set_device(device)
         if self.delay is not None:
             self.delay.set_indices(self.num_actuators, self._sequential_indices)
 
@@ -139,8 +139,8 @@ def SHARED_PARAMS(self) -> set[str]:
         params |= self.controller.SHARED_PARAMS
         if self.delay is not None:
             params |= self.delay.SHARED_PARAMS
-        for d in self.dynamics:
-            params |= d.SHARED_PARAMS
+        for c in self.clamping:
+            params |= c.SHARED_PARAMS
         return params
 
     def is_stateful(self) -> bool:
@@ -149,7 +149,7 @@ def is_stateful(self) -> bool:
 
     def is_graphable(self) -> bool:
         """Return True if all components can be captured in a CUDA graph."""
-        return self.controller.is_graphable() and all(d.is_graphable() for d in self.dynamics)
+        return self.controller.is_graphable() and all(c.is_graphable() for c in self.clamping)
 
     def has_transmission(self) -> bool:
         """Return True if this actuator applies a transmission transform."""
@@ -185,7 +185,7 @@ def step(
 
         1. **Delay** — read delayed targets from buffer.
         2. **Controller** — compute raw forces.
-        3. **Dynamics** — modify forces and scatter-add to output.
+        3. **Clamping** — bound forces and scatter-add to output.
         4. **State updates** — update delay buffer and controller state.
 
         If the delay buffer is still filling, steps 2-3 are skipped
@@ -244,9 +244,9 @@ def step(
                 dt,
             )
 
-            # --- 3. Dynamics: modify forces + write output ---
-            for dyn in self.dynamics:
-                dyn.modify_forces(
+            # --- 3. Clamping: bound forces + write output ---
+            for clamp in self.clamping:
+                clamp.modify_forces(
                     self._forces, positions, velocities,
                     self.input_indices, self.num_actuators,
                 )

…wton_actuators/_src/dynamics/__init__.py …wton_actuators/_src/clamping/__init__.pynewton_actuators/_src/dynamics/__init__.py renamed to newton_actuators/_src/clamping/__init__.py newton_actuators/_src/dynamics/__init__.py renamed to newton_actuators/_src/clamping/__init__.py

@@ -1,14 +1,14 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 The Newton Developers
 # SPDX-License-Identifier: Apache-2.0
 
-from .base import Dynamic
+from .base import Clamping
 from .clamp import Clamp
 from .dc_motor_saturation import DCMotorSaturation
 from .remotized_clamp import RemotizedClamp
 
 __all__ = [
     "Clamp",
     "DCMotorSaturation",
-    "Dynamic",
+    "Clamping",
     "RemotizedClamp",
 ]

newton_actuators/_src/dynamics/base.py newton_actuators/_src/clamping/base.pynewton_actuators/_src/dynamics/base.py renamed to newton_actuators/_src/clamping/base.py

@@ -6,15 +6,16 @@
 import warp as wp
 
 
-class Dynamic:
-    """Base class for post-controller dynamics that modify forces.
+class Clamping:
+    """Base class for post-controller force clamping.
 
-    Dynamics are stacked on top of a controller to add behaviors such as
-    clamping or velocity-dependent saturation. They modify forces in-place
+    Clamping objects are stacked on top of a controller to bound
+    output forces — symmetric limits, velocity-dependent saturation,
+    angle-dependent torque curves, etc. They modify forces in-place
     after the controller has computed them.
 
     For input delay, use the ``Delay`` class (passed separately to the
-    Actuator, not as a Dynamic).
+    Actuator, not as a Clamping).
 
     Class Attributes:
         SHARED_PARAMS: Parameter names that are instance-level (shared across

newton_actuators/_src/dynamics/clamp.py newton_actuators/_src/clamping/clamp.pynewton_actuators/_src/dynamics/clamp.py renamed to newton_actuators/_src/clamping/clamp.py

@@ -6,7 +6,7 @@
 
 import warp as wp
 
-from .base import Dynamic
+from .base import Clamping
 
 
 @wp.kernel
@@ -19,7 +19,7 @@ def _box_clamp_kernel(
     forces[i] = wp.clamp(forces[i], -max_force[i], max_force[i])
 
 
-class Clamp(Dynamic):
+class Clamp(Clamping):
     """Box-clamp dynamic.
 
     Clamps controller output forces to ±max_force per actuator.

…ors/_src/dynamics/dc_motor_saturation.py …ors/_src/clamping/dc_motor_saturation.pynewton_actuators/_src/dynamics/dc_motor_saturation.py renamed to newton_actuators/_src/clamping/dc_motor_saturation.py newton_actuators/_src/dynamics/dc_motor_saturation.py renamed to newton_actuators/_src/clamping/dc_motor_saturation.py

@@ -6,7 +6,7 @@
 
 import warp as wp
 
-from .base import Dynamic
+from .base import Clamping
 
 
 @wp.kernel
@@ -35,7 +35,7 @@ def _dc_motor_clamp_kernel(
     forces[i] = wp.clamp(forces[i], min_torque, max_torque)
 
 
-class DCMotorSaturation(Dynamic):
+class DCMotorSaturation(Clamping):
     """DC motor velocity-dependent torque saturation.
 
     Clips controller output using the torque–speed characteristic:

…tuators/_src/dynamics/remotized_clamp.py …tuators/_src/clamping/remotized_clamp.pynewton_actuators/_src/dynamics/remotized_clamp.py renamed to newton_actuators/_src/clamping/remotized_clamp.py newton_actuators/_src/dynamics/remotized_clamp.py renamed to newton_actuators/_src/clamping/remotized_clamp.py

@@ -6,7 +6,7 @@
 import numpy as np
 import warp as wp
 
-from .base import Dynamic
+from .base import Clamping
 
 
 @wp.func
@@ -49,7 +49,7 @@ def _remotized_clamp_kernel(
     forces[i] = wp.clamp(forces[i], -limit, limit)
 
 
-class RemotizedClamp(Dynamic):
+class RemotizedClamp(Clamping):
     """Angle-dependent torque clamping via lookup table.
 
     Replaces a fixed ±max_force box clamp with angle-dependent torque

newton_actuators/_src/controllers/base.py

@@ -12,7 +12,7 @@ class Controller:
     Controllers are the core computation component in an actuator. They read
     positions, velocities, and targets, then write raw (unclamped) forces to
     a scratch buffer. Clamping and other post-processing is handled by
-    Dynamic objects composed on top.
+    Clamping objects composed on top.
 
     Subclasses must override ``compute`` and ``resolve_arguments``.
 

newton_actuators/_src/controllers/net_lstm.py

@@ -14,7 +14,7 @@ class NetLSTMController(Controller):
 
     Uses a pre-trained LSTM network to compute joint torques from position
     error and velocity. The network maintains hidden and cell state across
-    timesteps to capture temporal dynamics.
+    timesteps to capture temporal patterns.
 
     The network must be callable as:
         torques, (h_new, c_new) = network(input, (h, c))