Singularity API Reference#

This page documents ManipulaPy.singularity, the module for comprehensive singularity analysis of robotic manipulators including detection, visualization, and workspace analysis with optional CUDA acceleration.

Tip

For conceptual explanations, see Singularity Analysis User Guide.

—

Quick Navigation#

—

Singularity Class#

class ManipulaPy.singularity.Singularity(serial_manipulator)[source]#

Bases: object

Singularity and manipulability analysis for a serial manipulator.

Main class for singularity analysis of robotic manipulators providing detection, manipulability analysis, workspace visualization, and condition number computations.

Constructor

Parameters:

serial_manipulator (Any)

__init__(serial_manipulator)[source]#

Initialize the Singularity class with a SerialManipulator object.

Parameters:

serial_manipulator (SerialManipulator) – An instance of SerialManipulator.

Return type:

None

Parameters:

  • serial_manipulator (SerialManipulator) – Instance of SerialManipulator for kinematic computations

—

Singularity Detection#

Primary Detection Methods#

Singularity.singularity_analysis(thetalist)[source]#

Detect singularity using smallest singular value (works for any Jacobian shape).

Computes the space-frame Jacobian at the given configuration and flags a singularity when its smallest singular value falls below 1e-4.

Parameters:

thetalist (ndarray[tuple[Any, ...], dtype[float64]] | List[float]) – Joint angles in radians, length-N array or list, where N is the number of joints.

Returns:

True if the configuration is (near-)singular, otherwise False.

Return type:

bool

Analyzes if the manipulator is at a singularity by computing the determinant of the Jacobian matrix. Uses a threshold of 1e-4 for determinant comparison.

Parameters:

  • thetalist (numpy.ndarray) – Array of joint angles in radians

Returns:

  • bool – True if at singularity (\(\lvert \det(J) \rvert\) < 1e-4), False otherwise

Singularity.near_singularity_detection(thetalist, threshold=0.01)[source]#

Detect if the manipulator is near a singularity by comparing the condition number with a threshold.

Parameters:

  • thetalist (numpy.ndarray) – Array of joint angles in radians.

  • threshold (float, optional) – Threshold value for the condition number. Defaults to 1e-2.

Returns:

True if the manipulator is near a singularity, False otherwise.

Return type:

bool

Detects proximity to singularities using condition number analysis.

Parameters:

  • thetalist (numpy.ndarray) – Array of joint angles in radians

  • threshold (float, optional) – Condition number threshold (default: 1e-2)

Returns:

  • bool – True if near singularity (condition number > threshold), False otherwise

Condition Analysis#

Singularity.condition_number(thetalist)[source]#

Calculate the condition number of the Jacobian for a given set of joint angles.

Parameters:

thetalist (numpy.ndarray) – Array of joint angles in radians.

Returns:

The condition number of the Jacobian matrix.

Return type:

float

Computes the condition number of the Jacobian matrix using singular value decomposition.

Parameters:

  • thetalist (numpy.ndarray) – Array of joint angles in radians

Returns:

  • float – Condition number of the Jacobian matrix

—

Manipulability Analysis#

Ellipsoid Visualization#

Singularity.manipulability_ellipsoid(thetalist, ax=None)[source]#

Plot the manipulability ellipsoid for a given set of joint angles.

Parameters:

  • thetalist (numpy.ndarray) – Array of joint angles in radians.

  • ax (matplotlib.axes._subplots.Axes3DSubplot, optional) – Matplotlib 3D axis to plot on. Defaults to None.

Return type:

None

Generates and plots manipulability ellipsoids for linear and angular velocity components. Uses SVD to compute ellipsoid radii and orientations from Jacobian submatrices.

Parameters:

  • thetalist (numpy.ndarray) – Array of joint angles in radians

  • ax (matplotlib.axes._subplots.Axes3DSubplot, optional) – 3D axis for plotting

Technical Details:

  • Separates Jacobian into linear (J[:3,:]) and angular (J[3:,:]) components

  • Computes SVD for each component: U, S, V = svd(J_component)

  • Ellipsoid radii calculated as 1/sqrt(singular_values)

  • Generates sphere points and transforms using U and radii

  • Creates dual plot with blue (linear) and red (angular) ellipsoids

—

Workspace Analysis#

Monte Carlo Methods#

Singularity.plot_workspace_monte_carlo(joint_limits, num_samples=10000)[source]#

Estimate the robot workspace using Monte Carlo sampling.

Parameters:

  • joint_limits (list) – A list of tuples representing the joint limits.

  • num_samples (int, optional) – Number of samples for Monte Carlo simulation. Defaults to 10000.

Return type:

None

Estimates robot workspace using CUDA-accelerated Monte Carlo sampling. Generates random joint configurations and computes reachable end-effector positions.

Parameters:

  • joint_limits (list) – List of (min, max) tuples for each joint

  • num_samples (int, optional) – Number of Monte Carlo samples (default: 10000)

CUDA Implementation Details:

  • Uses numba.cuda for GPU acceleration

  • Random number generation via xoroshiro128p_uniform_float32

  • Parallel joint angle sampling with configurable thread blocks

  • Thread block size: 256 threads per block

  • Grid size: (num_samples + 255) // 256 blocks

Processing Pipeline:

  1. Initialize CUDA device arrays for joint samples

  2. Generate random states with create_xoroshiro128p_states

  3. Launch CUDA kernel for parallel sampling

  4. Copy samples to host and compute forward kinematics

  5. Generate convex hull from workspace points

  6. Visualize using matplotlib plot_trisurf

—

Mathematical Implementation#

Jacobian Analysis#

All methods rely on the Jacobian matrix computation from the SerialManipulator:

  • Frame: Uses “space” frame for consistency

  • Dimensions: 6×n matrix (6 DOF × n joints)

  • Components: Upper 3 rows (linear), lower 3 rows (angular)

Determinant Computation#

Singularity detection uses numpy.linalg.det() with absolute value comparison:

  • Threshold: 1e-4 (configurable in source)

  • Method: Direct determinant calculation

  • Precision: Double precision floating point

Condition Number Calculation#

Uses numpy.linalg.cond() which implements:

  • Method: Ratio of largest to smallest singular values

  • Algorithm: SVD-based computation

  • Stability: Numerically stable for ill-conditioned matrices

SVD Implementation#

Manipulability ellipsoid generation uses numpy.linalg.svd():

  • Decomposition: J = U @ diag(S) @ V.T

  • Radii computation: 1.0 / sqrt(S)

  • Transformation: Ellipsoid points = U @ diag(radii) @ sphere_points

Convex Hull Generation#

Workspace visualization uses scipy.spatial.ConvexHull:

  • Algorithm: Quickhull algorithm

  • Input: N×3 array of workspace points

  • Output: Triangulated surface mesh

  • Visualization: Matplotlib plot_trisurf with viridis colormap

—

Performance Characteristics#

Computational Complexity#

Method

Complexity

Primary Operations

singularity_analysis

O(n³)

Jacobian + determinant

condition_number

O(n³)

Jacobian + SVD

manipulability_ellipsoid

O(n³ + m)

2×SVD + sphere generation

plot_workspace_monte_carlo

O(k×n²)

k×forward_kinematics + convex_hull

Memory Requirements#

CUDA kernel memory allocation:

  • joint_samples: num_samples × num_joints × float32

  • rng_states: num_samples × state_size

  • device_joint_limits: num_joints × 2 × float32

Thread Configuration#

CUDA kernel execution parameters:

  • threads_per_block: 256 (fixed)

  • blocks_per_grid: ceil(num_samples / 256)

  • total_threads: blocks_per_grid × threads_per_block

—

Data Flow Architecture#

Singularity Analysis Pipeline#

  1. Input: Joint angles (numpy.ndarray)

  2. Jacobian Computation: SerialManipulator.jacobian()

  3. Analysis: Determinant or condition number calculation

  4. Output: Boolean or float result

Manipulability Ellipsoid Pipeline#

  1. Input: Joint angles + optional axis

  2. Jacobian Decomposition: Split into linear/angular components

  3. SVD Analysis: Compute singular values and vectors

  4. Ellipsoid Generation: Transform unit sphere using SVD results

  5. Visualization: Matplotlib 3D surface plotting

Workspace Analysis Pipeline#

  1. CUDA Setup: Initialize device memory and random states

  2. Parallel Sampling: Generate random joint configurations

  3. Host Transfer: Copy samples from GPU to CPU

  4. Forward Kinematics: Batch computation of end-effector positions

  5. Convex Hull: Geometric analysis of workspace boundary

  6. Visualization: 3D triangulated surface rendering

—

Error Handling and Validation#

Input Validation#

  • Joint angles: Verified as numpy arrays with correct dimensions

  • Joint limits: Validated as list of tuples with numeric values

  • Thresholds: Checked for positive numeric values

Numerical Stability#

  • Singular matrices: Handled gracefully in condition number computation

  • Zero determinants: Managed with absolute value thresholding

  • Ill-conditioned systems: SVD provides robust decomposition

CUDA Error Management#

  • Memory allocation: Automatic cleanup on kernel completion

  • Thread synchronization: Implicit synchronization after kernel launch

  • Device compatibility: Runtime detection of CUDA availability

—

See Also#