ArticulationEntity#

Fully qualified name: isaacsim::physics::entities::ArticulationEntity

class ArticulationEntity : public isaacsim::physics::entities::PhysicsEntity#

Wrapper over a batch of simulated articulation prims.

Extends PhysicsEntity with articulation specific state and properties: kinematic tree topology (links, joints, degrees of freedom), root pose and velocity, DOF state and drive configuration, link mass properties, dynamics quantities (Jacobian and mass matrices, compensation forces), and fixed tendon properties.

Batched quantities are laid out with N as the number of selected prims, D as the number of degrees of freedom, L as the number of links, and T as the number of fixed tendons. All methods that accept an indices parameter operate only on the prims at those positions; when indices is omitted, all wrapped prims are processed. Inputs smaller than the expected shape are broadcast.

Public Functions

ArticulationEntity(
const std::string &engine,
const std::variant<std::string, std::vector<std::string>> &paths,
)#

Construct an articulation entity wrapper for one or more USD prim paths.

Parameters:
  • engine – [in] Name of the physics engine that simulates the prims.

  • paths – [in] Single path string or list of path strings. May include regular expressions.

Throws:

std::runtime_error – if the entity cannot be created for the given engine and paths.

~ArticulationEntity() = default#
size_t numDofs() const#

Return the number of degrees of freedom (DOFs) per wrapped articulation.

Throws:

std::runtime_error – if the DOF count cannot be queried from the physics engine.

Returns:

Count of DOFs.

std::vector<std::string> dofNames() const#

Return the names of the degrees of freedom (DOFs), in DOF index order.

Throws:

std::runtime_error – if the DOF names cannot be queried from the physics engine.

Returns:

Ordered list of DOF names (size D).

std::vector<std::vector<std::string>> dofPaths() const#

Return the USD prim paths of the degrees of freedom (DOFs) of each wrapped articulation.

Throws:

std::runtime_error – DOF paths are not exposed by the tensor API.

Returns:

Ordered list of DOF path lists, one list per articulation.

array::Array dofTypes() const#

Return the joint types of the degrees of freedom (DOFs), in DOF index order.

Throws:

std::runtime_error – DOF types are not exposed by the tensor API.

Returns:

DOF types (shape (N,D)).

size_t numJoints() const#

Return the number of joints per wrapped articulation.

Throws:

std::runtime_error – if the joint count cannot be queried from the physics engine.

Returns:

Count of joints.

std::vector<std::string> jointNames() const#

Return the names of the joints, in joint index order.

Throws:

std::runtime_error – if the joint names cannot be queried from the physics engine.

Returns:

Ordered list of joint names.

std::vector<std::vector<std::string>> jointPaths() const#

Return the USD prim paths of the joints of each wrapped articulation.

Throws:

std::runtime_error – Joint paths are not exposed by the tensor API.

Returns:

Ordered list of joint path lists, one list per articulation.

array::Array jointTypes() const#

Return the joint types, in joint index order.

Throws:

std::runtime_error – Joint types are not exposed by the tensor API.

Returns:

Joint types.

size_t numLinks() const#

Return the number of links per wrapped articulation.

Throws:

std::runtime_error – if the link count cannot be queried from the physics engine.

Returns:

Count of links.

std::vector<std::string> linkNames() const#

Return the names of the links, in link index order.

Throws:

std::runtime_error – if the link names cannot be queried from the physics engine.

Returns:

Ordered list of link names (size L).

std::vector<std::vector<std::string>> linkPaths() const#

Return the USD prim paths of the links of each wrapped articulation.

Throws:

std::runtime_error – Link paths are not exposed by the tensor API.

Returns:

Ordered list of link path lists, one list per articulation.

size_t numShapes() const#

Return the number of collision shapes per wrapped articulation.

Throws:

std::runtime_error – if the shape count cannot be queried from the physics engine.

Returns:

Count of collision shapes.

size_t numFixedTendons() const#

Return the number of fixed tendons per wrapped articulation.

Throws:

std::runtime_error – if the tendon count cannot be queried from the physics engine.

Returns:

Count of fixed tendons.

std::tuple<size_t, size_t, size_t> jacobianMatrixShape() const#

Return the shape of the Jacobian matrix of a single articulation.

The shape depends on the number of links, the number of DOFs, and whether the articulation base is fixed:

  • Fixed base: (L-1, 6, D)

  • Floating base: (L, 6, D+6)

Each link contributes 6 rows representing its linear and angular motion along the three coordinate axes. For floating bases, the 6 extra columns correspond to the linear and angular degrees of freedom of the free root link.

Returns:

Jacobian matrix shape as (rows, 6, columns).

std::tuple<size_t, size_t> massMatrixShape() const#

Return the shape of the generalized mass matrix of a single articulation.

The shape depends on the number of DOFs and whether the articulation base is fixed:

  • Fixed base: (D, D)

  • Floating base: (D+6, D+6)

Returns:

Mass matrix shape as (rows, columns).

array::Array getLinkIndices(
const std::variant<std::string, std::vector<std::string>> &names,
)#

Resolve link names to their link indices.

Parameters:

names – [in] Single link name or list of link names.

Throws:

std::invalid_argument – if any name does not match a link of the articulation.

Returns:

Link indices, in the order the names were given.

array::Array getJointIndices(
const std::variant<std::string, std::vector<std::string>> &names,
)#

Resolve joint names to their joint indices.

Parameters:

names – [in] Single joint name or list of joint names.

Throws:

std::invalid_argument – if any name does not match a joint of the articulation.

Returns:

Joint indices, in the order the names were given.

array::Array getDofIndices(
const std::variant<std::string, std::vector<std::string>> &names,
)#

Resolve degree of freedom (DOF) names to their DOF indices.

Parameters:

names – [in] Single DOF name or list of DOF names.

Throws:

std::invalid_argument – if any name does not match a DOF of the articulation.

Returns:

DOF indices, in the order the names were given.

std::tuple<array::Array, array::Array> getDofLimits(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the position limits of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

A pair of (lower limits, upper limits), both with shape (N,D).

void setDofLimits(
const std::optional<array::Array> &lower = std::nullopt,
const std::optional<array::Array> &upper = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the position limits of the degrees of freedom (DOFs) of the selected articulations.

At least one of lower or upper must be provided.

Parameters:
  • lower – [in] Lower limits (shape (N,D)). Optional.

  • upper – [in] Upper limits (shape (N,D)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Throws:

std::invalid_argument – if both lower and upper are undefined.

std::tuple<array::Array, array::Array, array::Array> getDofFrictionProperties(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the friction properties of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

A triple of (static friction efforts, dynamic friction efforts, viscous friction coefficients), all with shape (N,D).

void setDofFrictionProperties(
const std::optional<array::Array> &staticFrictions = std::nullopt,
const std::optional<array::Array> &dynamicFrictions = std::nullopt,
const std::optional<array::Array> &viscousFrictions = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the friction properties of the degrees of freedom (DOFs) of the selected articulations.

At least one of the friction properties must be provided.

Warning

The static frictions must be greater than or equal to the dynamic frictions.

Parameters:
  • staticFrictions – [in] Static friction efforts (shape (N,D)). Optional.

  • dynamicFrictions – [in] Dynamic friction efforts (shape (N,D)). Optional.

  • viscousFrictions – [in] Viscous friction coefficients (shape (N,D)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Throws:

std::invalid_argument – if all friction properties are undefined.

std::tuple<array::Array, array::Array, array::Array> getDofDriveModelProperties(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the drive model properties of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

A triple of (speed effort gradients, maximum actuator velocities, velocity-dependent resistances), all with shape (N,D).

void setDofDriveModelProperties(
const std::optional<array::Array> &speedEffortGradients = std::nullopt,
const std::optional<array::Array> &maximumActuatorVelocities = std::nullopt,
const std::optional<array::Array> &velocityDependentResistances = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the drive model properties of the degrees of freedom (DOFs) of the selected articulations.

At least one of the drive model properties must be provided.

Parameters:
  • speedEffortGradients – [in] Speed effort gradients (shape (N,D)). Optional.

  • maximumActuatorVelocities – [in] Maximum actuator velocities (shape (N,D)). Optional.

  • velocityDependentResistances – [in] Velocity-dependent resistances (shape (N,D)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Throws:

std::invalid_argument – if all drive model properties are undefined.

array::Array getDofArmatures(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the armatures of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Armatures (shape (N,D)).

void setDofArmatures(
const array::Array &armatures,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the armatures of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • armatures – [in] Armatures to apply (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

void setDofPositionTargets(
const array::Array &positions,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the position targets of the degrees of freedom (DOFs) of the selected articulations.

The targets are tracked by the implicit PD controller of each DOF drive.

Parameters:
  • positions – [in] Position targets in distance or radians, depending on the DOF type (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

array::Array getDofPositionTargets(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the position targets of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Position targets in distance or radians, depending on the DOF type (shape (N,D)).

void setDofPositions(
const array::Array &positions,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the positions of the degrees of freedom (DOFs) of the selected articulations.

This method teleports the DOFs to the specified positions.

Parameters:
  • positions – [in] Positions in distance or radians, depending on the DOF type (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

array::Array getDofPositions(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the positions of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Positions in distance or radians, depending on the DOF type (shape (N,D)).

void setDofVelocityTargets(
const array::Array &velocities,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the velocity targets of the degrees of freedom (DOFs) of the selected articulations.

The targets are tracked by the implicit PD controller of each DOF drive.

Parameters:
  • velocities – [in] Velocity targets in distance/second or radians/second, depending on the DOF type (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

array::Array getDofVelocityTargets(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the velocity targets of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Velocity targets in distance/second or radians/second, depending on the DOF type (shape (N,D)).

void setDofVelocities(
const array::Array &velocities,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the velocities of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • velocities – [in] Velocities in distance/second or radians/second, depending on the DOF type (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

array::Array getDofVelocities(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the velocities of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Velocities in distance/second or radians/second, depending on the DOF type (shape (N,D)).

void setDofEfforts(
const array::Array &efforts,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the actuation efforts of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • efforts – [in] Actuation forces or torques, depending on the DOF type (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

array::Array getDofEfforts(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the actuation efforts of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Actuation forces or torques, depending on the DOF type (shape (N,D)).

array::Array getDofProjectedJointForces(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the projected joint forces of the degrees of freedom (DOFs) of the selected articulations.

These are the incoming joint forces of the links projected onto the motion direction, that is, the active component of the force.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Projected joint forces (shape (N,D)).

std::tuple<array::Array, array::Array> getDofGains(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the implicit PD controller gains of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

A pair of (stiffnesses, dampings), both with shape (N,D).

void setDofGains(
const std::optional<array::Array> &stiffnesses = std::nullopt,
const std::optional<array::Array> &dampings = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
bool updateDefaultGains = true,
)#

Set the implicit PD controller gains of the degrees of freedom (DOFs) of the selected articulations.

At least one of stiffnesses or dampings must be provided.

Parameters:
  • stiffnesses – [in] Stiffnesses (shape (N,D)). Optional.

  • dampings – [in] Dampings (shape (N,D)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

  • updateDefaultGains – [in] Whether to record the resulting gains of all wrapped articulations as the new defaults used by switchDofControlMode.

Throws:

std::invalid_argument – if both stiffnesses and dampings are undefined.

void switchDofControlMode(
const std::string &mode,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Switch the control mode of the degrees of freedom (DOFs) of the selected articulations.

The mode is expressed as an adjustment of the implicit PD controller gains:

  • "position": default stiffnesses and default dampings.

  • "velocity": zero stiffnesses and default dampings.

  • "effort": zero stiffnesses and zero dampings.

The default gains are those recorded by the most recent setDofGains call with updateDefaultGains enabled. If none has been made, the gains in effect on the first call to this method are adopted as the defaults, so that switching away from and back to "position" restores the original gains.

See also

setDofGains

Parameters:
  • mode – [in] Control mode. Supported modes are "position", "velocity" and "effort".

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Throws:

std::invalid_argument – if the control mode is not supported.

array::Array getDofMaxEfforts(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the maximum efforts of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Maximum forces or torques, depending on the DOF type (shape (N,D)).

void setDofMaxEfforts(
const array::Array &maxEfforts,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the maximum efforts of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • maxEfforts – [in] Maximum forces or torques, depending on the DOF type (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

array::Array getDofMaxVelocities(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the maximum velocities of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Maximum velocities in distance/second or radians/second, depending on the DOF type (shape (N,D)).

void setDofMaxVelocities(
const array::Array &maxVelocities,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Set the maximum velocities of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • maxVelocities – [in] Maximum velocities in distance/second or radians/second, depending on the DOF type (shape (N,D)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

std::vector<std::vector<std::string>> getDofDriveTypes(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the drive types of the degrees of freedom (DOFs) of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Drive type names (shape (N,D)). Possible values are "force", "acceleration", and "none" when the drive type is not set.

std::tuple<array::Array, array::Array> getWorldPoses(
const std::optional<array::Array> &indices = std::nullopt,
)#

Get the world-frame poses of the root links of the selected articulations.

Parameters:

indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Returns:

A pair of (positions, orientations). Positions have shape (N,3); orientations are quaternions xyzw with shape (N,4).

void setWorldPoses(
const std::optional<array::Array> &positions = std::nullopt,
const std::optional<array::Array> &orientations = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the world-frame poses of the root links of the selected articulations.

At least one of positions or orientations must be provided. This method teleports the articulations to the specified poses.

Parameters:
  • positions – [in] World-frame positions (shape (N,3)). Optional.

  • orientations – [in] Orientations as quaternions xyzw (shape (N,4)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Throws:

std::invalid_argument – if both positions and orientations are undefined.

std::tuple<array::Array, array::Array> getVelocities(
const std::optional<array::Array> &indices = std::nullopt,
)#

Get the world-frame velocities of the root links of the selected articulations.

Parameters:

indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Returns:

A pair of (linear velocities, angular velocities), both with shape (N,3), in distance/second and radians/second respectively.

void setVelocities(
const std::optional<array::Array> &linearVelocities = std::nullopt,
const std::optional<array::Array> &angularVelocities = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the world-frame velocities of the root links of the selected articulations.

At least one of linearVelocities or angularVelocities must be provided.

Parameters:
  • linearVelocities – [in] Linear velocities in distance/second (shape (N,3)). Optional.

  • angularVelocities – [in] Angular velocities in radians/second (shape (N,3)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Throws:

std::invalid_argument – if both linearVelocities and angularVelocities are undefined.

std::tuple<array::Array, array::Array> getLinkIncomingJointForce(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
)#

Get the incoming joint forces and torques of the links of the selected articulations.

In a kinematic tree each link has a single incoming joint. This method reports the total 6D force/torque transmitted through that joint under external loads.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

Returns:

A pair of (forces, torques), both with shape (N,L,3).

array::Array getJacobianMatrices(
const std::optional<array::Array> &indices = std::nullopt,
)#

Get the Jacobian matrices of the selected articulations.

Parameters:

indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Returns:

Jacobian matrices, with the leading dimension N followed by the per-articulation Jacobian matrix shape.

array::Array getMassMatrices(
const std::optional<array::Array> &indices = std::nullopt,
)#

Get the generalized mass matrices of the selected articulations.

See also

massMatrixShape

Parameters:

indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Returns:

Mass matrices, with the leading dimension N followed by the per-articulation mass matrix shape.

array::Array getDofCoriolisAndCentrifugalCompensationForces(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the Coriolis and centrifugal compensation forces of the selected articulations.

These are the DOF forces required to counteract the Coriolis and centrifugal forces for the current articulation state.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Compensation forces. Shape is (N,D) for a fixed articulation base, and (N,D+6) for a floating base, where the extra components are the forces acting on the root link.

array::Array getDofGravityCompensationForces(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &dofIndices = std::nullopt,
)#

Get the gravity compensation forces of the selected articulations.

These are the DOF forces required to counteract gravity for the current articulation pose.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • dofIndices – [in] Indices of DOFs to process (shape (D,)). If omitted, all DOFs are processed.

Returns:

Compensation forces. Shape is (N,D) for a fixed articulation base, and (N,D+6) for a floating base, where the extra components are the forces acting on the root link.

array::Array getLinkMasses(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
bool inverse = false,
)#

Get the masses of the links of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

  • inverse – [in] Whether to return the inverse masses (true) or the masses (false).

Returns:

Masses or inverse masses (shape (N,L)).

void setLinkMasses(
const array::Array &masses,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
)#

Set the masses of the links of the selected articulations.

Parameters:
  • masses – [in] Masses to apply (shape (N,L)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

std::tuple<array::Array, array::Array> getLinkComs(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
)#

Get the centers of mass of the links of the selected articulations, expressed in their local frames.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

Returns:

A pair of (positions, orientations). Positions have shape (N,L,3); orientations are quaternions xyzw with shape (N,L,4).

void setLinkComs(
const std::optional<array::Array> &positions = std::nullopt,
const std::optional<array::Array> &orientations = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
)#

Set the centers of mass of the links of the selected articulations, expressed in their local frames.

At least one of positions or orientations must be provided.

Parameters:
  • positions – [in] Center of mass positions (shape (N,L,3)). Optional.

  • orientations – [in] Center of mass orientations as quaternions xyzw (shape (N,L,4)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

Throws:

std::invalid_argument – if both positions and orientations are undefined.

array::Array getLinkInertias(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
bool inverse = false,
)#

Get the inertia tensors of the links of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

  • inverse – [in] Whether to return the inverse inertia tensors (true) or the inertia tensors (false).

Returns:

Flattened row-major 3x3 inertia tensors (shape (N,L,9)).

void setLinkInertias(
const array::Array &inertias,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
)#

Set the inertia tensors of the links of the selected articulations.

Parameters:
  • inertias – [in] Flattened row-major 3x3 inertia tensors (shape (N,L,9)).

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

array::Array getLinkEnabledGravities(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
)#

Get the gravity-enabled state of the links of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

Returns:

Boolean flags (shape (N,L)). true if gravity affects the link, false otherwise.

void setLinkEnabledGravities(
const array::Array &enabled,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &linkIndices = std::nullopt,
)#

Enable or disable gravity for the links of the selected articulations.

Parameters:
  • enabled – [in] Boolean flags (shape (N,L)). true applies gravity, false excludes it.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • linkIndices – [in] Indices of links to process (shape (L,)). If omitted, all links are processed.

array::Array getFixedTendonStiffnesses(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &tendonIndices = std::nullopt,
)#

Get the stiffnesses of the fixed tendons of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • tendonIndices – [in] Indices of tendons to process (shape (T,)). If omitted, all tendons are processed.

Returns:

Stiffnesses (shape (N,T)).

array::Array getFixedTendonDampings(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &tendonIndices = std::nullopt,
)#

Get the dampings of the fixed tendons of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • tendonIndices – [in] Indices of tendons to process (shape (T,)). If omitted, all tendons are processed.

Returns:

Dampings (shape (N,T)).

array::Array getFixedTendonLimitStiffnesses(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &tendonIndices = std::nullopt,
)#

Get the limit stiffnesses of the fixed tendons of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • tendonIndices – [in] Indices of tendons to process (shape (T,)). If omitted, all tendons are processed.

Returns:

Limit stiffnesses (shape (N,T)).

std::tuple<array::Array, array::Array> getFixedTendonLimits(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &tendonIndices = std::nullopt,
)#

Get the length limits of the fixed tendons of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • tendonIndices – [in] Indices of tendons to process (shape (T,)). If omitted, all tendons are processed.

Returns:

A pair of (lower limits, upper limits), both with shape (N,T).

array::Array getFixedTendonRestLengths(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &tendonIndices = std::nullopt,
)#

Get the rest lengths of the fixed tendons of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • tendonIndices – [in] Indices of tendons to process (shape (T,)). If omitted, all tendons are processed.

Returns:

Rest lengths (shape (N,T)).

array::Array getFixedTendonOffsets(
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &tendonIndices = std::nullopt,
)#

Get the length offsets of the fixed tendons of the selected articulations.

Parameters:
  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • tendonIndices – [in] Indices of tendons to process (shape (T,)). If omitted, all tendons are processed.

Returns:

Offsets (shape (N,T)).

void setFixedTendonProperties(
const std::optional<array::Array> &stiffnesses = std::nullopt,
const std::optional<array::Array> &dampings = std::nullopt,
const std::optional<array::Array> &limitStiffnesses = std::nullopt,
const std::optional<array::Array> &lowerLimits = std::nullopt,
const std::optional<array::Array> &upperLimits = std::nullopt,
const std::optional<array::Array> &restLengths = std::nullopt,
const std::optional<array::Array> &offsets = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
const std::optional<array::Array> &tendonIndices = std::nullopt,
)#

Set the properties of the fixed tendons of the selected articulations.

At least one of the tendon properties must be provided.

Parameters:
  • stiffnesses – [in] Stiffnesses (shape (N,T)). Optional.

  • dampings – [in] Dampings (shape (N,T)). Optional.

  • limitStiffnesses – [in] Limit stiffnesses (shape (N,T)). Optional.

  • lowerLimits – [in] Lower length limits (shape (N,T)). Optional.

  • upperLimits – [in] Upper length limits (shape (N,T)). Optional.

  • restLengths – [in] Rest lengths (shape (N,T)). Optional.

  • offsets – [in] Length offsets (shape (N,T)). Optional.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

  • tendonIndices – [in] Indices of tendons to process (shape (T,)). If omitted, all tendons are processed.

Throws:

std::invalid_argument – if all tendon properties are undefined.

size_t numPrims() const noexcept#

Return the number of wrapped prims.

Returns:

Count of prims managed by this entity.

array::Array getData(
const std::string &name,
const std::optional<array::Array> &indices = std::nullopt,
)#

Read a named data buffer for the selected prims.

Parameters:
  • name – [in] Name of the data buffer to read.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Throws:

std::runtime_error – if the buffer name is not supported by the entity.

Returns:

Buffer contents, with the leading dimension matching the number of selected prims.

void setData(
const std::string &name,
const array::Array &data,
const std::optional<array::Array> &indices = std::nullopt,
)#

Write a named data buffer for the selected prims.

Parameters:
  • name – [in] Name of the data buffer to write.

  • data – [in] New buffer contents, with the leading dimension matching the number of selected prims.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Throws:

std::runtime_error – if the buffer name is not supported by the entity.

std::vector<array::Array> getMultiData(
const std::string &name,
const std::optional<array::Array> &indices = std::nullopt,
)#

Read a named data buffer that is composed of several arrays for the selected prims.

Parameters:
  • name – [in] Name of the data buffer to read.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Throws:

std::runtime_error – if the buffer name is not supported by the entity.

Returns:

Ordered list of buffer components.

void setMultiData(
const std::string &name,
const std::vector<array::Array> &data,
const std::optional<array::Array> &indices = std::nullopt,
)#

Write a named data buffer that is composed of several arrays for the selected prims.

Parameters:
  • name – [in] Name of the data buffer to write.

  • data – [in] Ordered list of buffer components to write.

  • indices – [in] Indices of prims to process (shape (N,)). If omitted, all wrapped prims are processed.

Throws:

std::runtime_error – if the buffer name is not supported by the entity.

Protected Attributes

std::shared_ptr<isaacsim::physics::tensors::EntityView> m_entityView#

View of the wrapped prims held by the physics engine.