Differential Kinematics

The moro.differential_kinematics module provides task-space Jacobian selection, forward Cartesian velocity propagation, numerical velocity-level inverse kinematics, singularity diagnostics, condition-number analysis, and Yoshikawa velocity manipulability.

Differential kinematics for serial manipulators.

This module builds on the geometric Jacobian already provided by Robot. It owns task-space row selection, forward Cartesian velocity propagation, and numerical velocity-level inverse kinematics.

class moro.differential_kinematics.VelocityIKSolution(qd: MutableDenseMatrix, unconstrained_qd: MutableDenseMatrix, desired_velocity: MutableDenseMatrix, achieved_velocity: MutableDenseMatrix, residual: MutableDenseMatrix, residual_norm: float, rank: int, condition_number: float, method: str, success: bool, limited: bool, message: str)

Bases: object

Result returned by solve_velocity_ik().

achieved_velocity: MutableDenseMatrix

condition_number: float

desired_velocity: MutableDenseMatrix

limited: bool

message: str

method: str

qd: MutableDenseMatrix

rank: int

residual: MutableDenseMatrix

residual_norm: float

success: bool

unconstrained_qd: MutableDenseMatrix

moro.differential_kinematics.cartesian_velocity(robot, q, qd, *, task='twist', parameters=None)

Propagate joint velocity into the selected Cartesian task velocity.

Computes J_task(q) * qd using the exact task-component ordering. Exact SymPy arithmetic is preserved when all symbols are resolved.

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

q, qdvector-like

Configuration and joint velocity in robot.qs order.

taskstr or sequence of str, optional

Task preset or explicit ordered task subset.

parametersmapping, optional

SymPy-object substitutions for remaining symbolic quantities.

Returns:

sympy.Matrix

Cartesian task velocity as a column matrix.

moro.differential_kinematics.condition_number(robot, q, *, task='twist', parameters=None)

Return the condition number of the selected task Jacobian.

The compact SVD spectrum and automatic rank threshold are used. A numerically rank-deficient Jacobian returns math.inf.

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

qvector-like

Joint configuration.

taskstr or sequence of str, optional

Task preset or explicit ordered task subset.

parametersmapping, optional

SymPy-object substitutions for non-joint symbolic quantities.

Returns:

float

sigma_max / sigma_min for full-rank tasks, otherwise infinity.

moro.differential_kinematics.is_singular(robot, q, *, task='twist', parameters=None, tol=None)

Return whether the selected task Jacobian is numerically singular.

Singularity is task dependent and is defined by rank(J_task) < min(m, n) under the active rank threshold.

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

qvector-like

Joint configuration.

taskstr or sequence of str, optional

Task preset or explicit ordered task subset.

parametersmapping, optional

SymPy-object substitutions for non-joint symbolic quantities.

tolpositive real, optional

Absolute singular-value threshold. If omitted, use the automatic scale-aware threshold.

Returns:

bool

True when the selected task Jacobian is rank deficient.

moro.differential_kinematics.jacobian_rank(robot, q, *, task='twist', parameters=None, tol=None)

Return numerical rank of the selected task Jacobian.

With tol=None, rank uses the shared scale-aware threshold max(m, n) * eps * sigma_max. An explicit tol is interpreted as an absolute singular-value threshold.

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

qvector-like

Joint configuration.

taskstr or sequence of str, optional

Task preset or explicit ordered task subset.

parametersmapping, optional

SymPy-object substitutions for non-joint symbolic quantities.

tolpositive real, optional

Absolute singular-value threshold. If omitted, use the automatic scale-aware threshold.

Returns:

int

Numerical rank of the selected task Jacobian.

moro.differential_kinematics.manipulability(robot, q, *, task, parameters=None)

Return Yoshikawa velocity manipulability for an explicit task.

For m <= n, the metric is computed as the product of compact singular values, equivalent to sqrt(det(J J.T)) for full-row-rank tasks. Rank-deficient tasks return exactly 0.0. For m > n, the m-dimensional Yoshikawa volume is necessarily zero and this function also returns 0.0.

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

qvector-like

Joint configuration.

taskstr or sequence of str

Explicit task preset or ordered task subset. This argument is required because manipulability depends strongly on task choice.

parametersmapping, optional

SymPy-object substitutions for non-joint symbolic quantities.

Returns:

float

Yoshikawa velocity manipulability for the selected task.

Notes

No characteristic-length or translational/angular normalization is applied in Moro 0.5.0.

moro.differential_kinematics.singular_values(robot, q, *, task='twist', parameters=None)

Return compact singular values of the selected task Jacobian.

The selected task Jacobian is evaluated numerically and analyzed with the shared economy-size SVD policy. Values are ordered from largest to smallest and the result has length min(m, n).

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

qvector-like

Joint configuration.

taskstr or sequence of str, optional

Task preset or explicit ordered task subset.

parametersmapping, optional

SymPy-object substitutions for non-joint symbolic quantities.

Returns:

sympy.Matrix

Numerical singular values as a column matrix.

moro.differential_kinematics.solve_velocity_ik(robot, q, velocity, *, task='twist', method='pinv', damping=None, joint_velocity_limits=None, parameters=None, tol=1e-09)

Solve velocity-level inverse kinematics for a selected task.

One SVD supports the inverse operator, numerical rank, and condition number. Optional joint-velocity limits are applied by component-wise clipping after the unconstrained solve, then task diagnostics are recomputed from the returned velocity.

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

qvector-like

Joint configuration.

velocityvector-like

Desired task velocity in the ordering defined by task.

taskstr or sequence of str, optional

Task preset or explicit ordered task subset.

method{“pinv”, “dls”}, optional

Numerical inverse method.

dampingpositive real, optional

Required for dls and invalid for pinv.

joint_velocity_limitssequence, optional

Symmetric positive magnitudes or explicit (lower, upper) pairs.

parametersmapping, optional

SymPy-object substitutions for non-joint symbolic quantities.

tolpositive real, optional

Task-space residual tolerance used only for success.

Returns:

VelocityIKSolution

Joint velocity and task-space/numerical diagnostics.

moro.differential_kinematics.task_jacobian(robot, q=None, *, task='twist', parameters=None)

Return a selected task Jacobian derived from robot.J.

Parameters:

robot

Object exposing compatible J, qs, and dof attributes.

qvector-like, optional

Joint configuration in robot.qs order. If omitted, the selected Jacobian remains symbolic in the joint variables.

taskstr or sequence of str, optional

“linear”, “angular”, “twist”, or an explicit ordered subset of vx, vy, vz, wx, wy, wz.

parametersmapping, optional

SymPy-object substitutions for non-joint model parameters.

Returns:

sympy.Matrix

Task Jacobian with one row per requested task component.