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 :doc:`../user_guide/Singularity_Analysis `.

β€”

Quick Navigation

β€”

Singularity Class

β€”

Singularity Detection

Primary Detection Methods

Condition Analysis

β€”

Manipulability Analysis

Ellipsoid Visualization

β€”

Workspace Analysis

Monte Carlo Methods

β€”

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