Navigation

rlmesh.adapters.Actuator

classfrom rlmesh.adapters import Actuator[source]

One contiguous slice of an action vector.

Actuator(
    role: str | None = None,
    dim: int = 0,
    encoding: RotationEncoding | CustomEncoding | None = None,
    range: tuple[float, float] | None = None,
    binary: bool = False,
    scale: float | Sequence[float] | None = None,
    invert: bool = False,
    threshold: float | None = None,
    clip: bool = False,
    fill: float = 0.0,
    optional: bool = False,
    *,
    frame: Frame | None = None,
    reference: Reference | None = None,
    part: str | None = None,
    offset: float | Sequence[float] | None = None,
    labels: Sequence[str] | None = None,
)

scale, offset, invert, and threshold declare a side’s actuator convention. They can be set on either side and compose as literal transforms applied after the declared formats (rotation, range) are bridged – model-side first (the model’s own output convention, in the model’s own axis order), then the reorder by labels, then env-side – each in the order scale, offset, invert, threshold, then binary. So an env declares its quirk once for every model to inherit, and a model whose output differs from a shared env it cannot edit declares the bridge on its own actuator (e.g. a gripper-sign flip as invert=True). clip is the exception: it stays env-side only, clamping to the env actuator’s range.

Attributes

role

attribute[source]
role: str | None

Semantic role used for matching, e.g. action/gripper. None makes the actuator opaque: it occupies dim dims of the action with the constant fill, matched by no model output – the action-side mirror of a role-less Field. Use it for dims the env requires but no model produces (e.g. a control-mode selector). An opaque actuator carries only dim and fill.

dim

attribute[source]
dim: int

Number of action dimensions occupied by this component.

encoding

attribute[source]
encoding: RotationEncoding | CustomEncoding | None

Rotation encoding when the component is a rotation.

range

attribute[source]
range: tuple[float, float] | None

Optional (low, high) range of the component values.

binary

attribute[source]
binary: bool

Whether the component encodes a binary decision (resolved adapters snap the value to a definite side after range mapping: >= 0 opens (+1), below closes (-1); a value exactly on the boundary opens rather than emitting an undefined 0).

scale

attribute[source]
scale: float | Sequence[float] | None

Optional multiplier applied to the model value for this role: one float, or a sequence with one value per axis in this side’s own labels order (serialized as axis_scale).

invert

attribute[source]
invert: bool

Negate the model value for this role (equivalent to scale=-1 but explicit; the common gripper-sign correction).

threshold

attribute[source]
threshold: float | None

Subtract this from the value, recentering the decision boundary – typically paired with binary so the snap splits at threshold instead of zero.

clip

attribute[source]
clip: bool

Clamp this actuator’s mapped value to its declared range. The per-component safety clamp the global Action.clip cannot give a mixed-range action: a global clip applies one bound to every dim, so it is wrong when dims have different ranges (e.g. delta-pos in [-1, 1] but rotation in [-pi/2, pi/2]). clip=True requires range.

fill

attribute[source]
fill: float

Constant emitted for each dim of an opaque (role-less) actuator, and the fallback for an optional roled actuator. Defaults to 0.0; inert (must stay 0.0) on a roled, non-optional actuator.

optional

attribute[source]
optional: bool

On a roled actuator, make the role optional – if no model output declares it, fill the actuator’s dim dims with fill instead of failing resolution (the action-side mirror of a model input’s optional zero-fill). A model that does output the role drives it normally. Meaningless on a role-less actuator (already always filled).

frame

attribute[source]
frame: Frame | None

Coordinate frame a Cartesian command’s axes are expressed in. Required of an absolute pose (action/eef_*) under the require-frames tier; a delta (action/delta_eef_*) may declare it too (a tool-frame delta and a base-frame delta are different commands), and when both sides do they must agree. Keyword-only, omitted from the wire when unset.

reference

attribute[source]
reference: Reference | None

What a delta command is integrated against (action/delta_eef_*): an env declares what its Cartesian controller adds the delta to – the measured pose ("current") or the last commanded target ("target") – and a model declares what it was trained against. A disagreement is a hard resolve error, which is what stops an absolute-pose head from binding cleanly to a delta controller. reference says what a delta is added to; frame says which axes it is expressed in. Declare both unless the controller fixes the frame.

part

attribute[source]
part: str | None

The body part this actuator drives, when the role repeats across a body (LEFT_ARM, RIGHT_ARM, or any identifier both sides agree on): an identity key the resolver matches on, never a value it checks. Keyword-only and omitted from the wire when unset; an opaque actuator may not carry one.

offset

attribute[source]
offset: float | Sequence[float] | None

Optional addend applied after scale (value * scale + offset), a float or a per-axis sequence like scale: the stand pose a joint-position target is expressed around. Keyword-only.

labels

attribute[source]
labels: Sequence[str] | None

The axis names this actuator drives, dim of them in this side’s own order. When a model names labels the env actuator must name the same set; the model’s output is then reordered onto the env’s axes by name. Keyword-only and omitted from the wire when unset; an opaque actuator may not carry them.