Singularity API Reference — ManipulaPy 1.1.0 Documentation
Description: This page documents ManipulaPy.singularity, the module for comprehensive singularity analysis of robotic manipulators including detection, visualization, and workspace analysis with optional CUDA a...

# 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 `.

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 10); backlink

Inline interpreted text or phrase reference start-string without end-string.

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 10); backlink

Inline interpreted text or phrase reference start-string without end-string.

—

## Quick Navigation

—

## Singularity Class

—

## Singularity Detection

### Primary Detection Methods

### Condition Analysis

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 77)

Title underline too short.

    Condition Analysis
    -----------------

—

## Manipulability Analysis

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 94)

Title underline too short.

    Manipulability Analysis
    ======================

### Ellipsoid Visualization

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 97)

Title underline too short.

    Ellipsoid Visualization
    ----------------------

—

## Workspace Analysis

### Monte Carlo Methods

—

## Mathematical Implementation

### Jacobian Analysis

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 158)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 167)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 176)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 185)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 194)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 232)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 241)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 252)

Title underline too short.

    Data Flow Architecture
    =====================

### Singularity Analysis Pipeline

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 255)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 294)

Title underline too short.

    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

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/singularity.rst, line 301)

Title underline too short.

    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

- Kinematics API Reference – SerialManipulator class for Jacobian computation

- Utils Module – Mathematical utilities and matrix operations

- Path Planning API Reference – Trajectory planning with singularity considerations

- Control API Reference – Control algorithms affected by singularities