Simulation API Reference — ManipulaPy 1.1.0 Documentation
Description: This page documents ManipulaPy.sim, the module for PyBullet-based simulation capabilities with real-time visualization, physics simulation, and interactive control. — Quick Navigation: — Simulation...

# Simulation API Reference

This page documents ManipulaPy.sim, the module for PyBullet-based simulation capabilities with real-time visualization, physics simulation, and interactive control.

Tip

For conceptual explanations, see Simulation Module User Guide.

—

## Quick Navigation

—

## Simulation Class

—

## Simulation Management

### Environment Setup

### Robot Initialization

—

## Robot Control and State

### Joint Control

### Trajectory Execution

### Controller Integration

—

## Interactive Controls

### GUI Elements

### Manual Control

—

## Visualization and Analysis

### Trajectory Visualization

### Data Management

—

## Safety and Monitoring

—

## Main Execution

—

## Logging and Utilities

—

## Usage Examples

### Basic Simulation Setup

    from ManipulaPy.sim import Simulation
    import numpy as np

    # Define joint limits for a 6-DOF robot
    joint_limits = [(-np.pi, np.pi)] * 6
    torque_limits = [(-50, 50)] * 6

    # Create simulation instance
    sim = Simulation(
        urdf_file_path="robot.urdf",
        joint_limits=joint_limits,
        torque_limits=torque_limits,
        time_step=0.01,
        real_time_factor=1.0
    )

    # Initialize robot and components
    sim.initialize_robot()
    sim.initialize_planner_and_controller()

### Running a Trajectory

    # Define a simple trajectory
    trajectory = [
        [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],  # Start position
        [0.5, 0.3, -0.2, 0.1, 0.4, 0.0], # Intermediate
        [1.0, 0.5, -0.5, 0.2, 0.6, 0.1]  # End position
    ]

    # Run the trajectory
    final_ee_pos = sim.run_trajectory(trajectory)
    print(f"Final end-effector position: {final_ee_pos}")

### Interactive Manual Control

    # Add GUI controls
    sim.add_joint_parameters()
    sim.add_reset_button()
    sim.add_additional_parameters()

    # Start manual control mode
    sim.manual_control()

### Controller Integration

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

Title underline too short.

    Controller Integration
    ---------------------

    import cupy as cp

    # Define control parameters
    desired_positions = np.array([[0.1, 0.2, 0.3, 0.0, 0.0, 0.0]])
    desired_velocities = np.zeros_like(desired_positions)
    desired_accelerations = np.zeros_like(desired_positions)

    # Control gains
    Kp = np.array([100, 100, 100, 50, 50, 50])
    Ki = np.array([1, 1, 1, 0.5, 0.5, 0.5])
    Kd = np.array([10, 10, 10, 5, 5, 5])

    # Gravity and external forces
    g = [0, 0, -9.81]
    Ftip = [0, 0, 0, 0, 0, 0]

    # Run controller
    final_pos = sim.run_controller(
        sim.controller,
        desired_positions,
        desired_velocities,
        desired_accelerations,
        g, Ftip, Kp, Ki, Kd
    )

### Collision Monitoring

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

Title underline too short.

    Collision Monitoring
    -------------------

    # Enable collision checking during simulation
    while True:
        # Update robot state
        joint_positions = sim.get_joint_parameters()
        sim.set_joint_positions(joint_positions)

        # Check for collisions
        sim.check_collisions()

        # Step simulation
        sim.step_simulation()

### Data Logging and Analysis

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

Title underline too short.

    Data Logging and Analysis
    ------------------------

    # Save joint states during simulation
    sim.save_joint_states("robot_states.csv")

    # Visualize trajectory in 3D
    joint_trajectory = [
        [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
        [0.5, 0.5, 0.5, 0.0, 0.0, 0.0],
        [1.0, 1.0, 1.0, 0.0, 0.0, 0.0]
    ]

    ee_trajectory = []
    for joints in joint_trajectory:
        # Calculate end-effector position for each joint configuration
        ee_pos = sim.robot.forward_kinematics(joints)[:3, 3]
        ee_trajectory.append(ee_pos)

    sim.plot_trajectory_in_scene(joint_trajectory, ee_trajectory)

### Complete Simulation Loop

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

Title underline too short.

    Complete Simulation Loop
    -----------------------

    # Complete example with trajectory execution and manual control
    try:
        # Generate trajectory using path planner
        thetastart = np.zeros(6)
        thetaend = np.array([0.5, 0.3, -0.2, 0.1, 0.4, 0.0])

        trajectory_data = sim.trajectory_planner.joint_trajectory(
            thetastart, thetaend, Tf=5.0, N=100, method=3
        )

        # Run the main simulation loop
        sim.run(trajectory_data["positions"])

    except KeyboardInterrupt:
        print("Simulation interrupted by user")
    finally:
        sim.close_simulation()

—

## Configuration Options

### Simulation Parameters

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

Title underline too short.

    Simulation Parameters
    --------------------

The simulation can be configured with various parameters:

Parameter | Default | Description
--- | --- | ---
`time_step` | 0.01 | Physics simulation time step in seconds
`real_time_factor` | 1.0 | Speed multiplier for real-time simulation
`joint_limits` | Required | List of (min, max) tuples for each joint
`torque_limits` | None | Optional torque limits for each joint

### Physics Settings

The simulation uses PyBullet’s physics engine with the following default settings:

- Gravity: [0, 0, -9.81] m/s²

- Solver iterations: PyBullet default

- Contact breaking threshold: PyBullet default

- Collision detection: Enabled for all robot links

### GUI Controls

When using interactive mode, the following GUI elements are available:

- Joint sliders: Individual control for each robot joint

- Reset button: Return robot to home position

- Gravity control: Adjust gravitational acceleration

- Time step control: Modify simulation time step

—

## Performance Considerations

### GPU Acceleration

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

Title underline too short.

    GPU Acceleration
    ---------------

The simulation module integrates with CuPy for GPU-accelerated computations:

- Controller calculations use CuPy arrays for improved performance

- Large trajectory computations benefit from GPU acceleration

- Memory management is handled automatically

### Real-time Performance

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

Title underline too short.

    Real-time Performance
    --------------------

For optimal real-time performance:

- Use appropriate `time_step` values (0.001-0.01 seconds)

- Adjust `real_time_factor` based on computational load

- Monitor collision detection frequency for complex robots

- Consider reducing visualization quality for faster simulation

—

## Error Handling

### Common Issues and Solutions

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

Title underline too short.

    Common Issues and Solutions
    --------------------------

Note

The simulation module includes comprehensive error handling for common issues:

URDF Loading Errors

  - Verify URDF file path and format

  - Check for missing mesh files or textures

  - Ensure joint limits are properly defined

Physics Instability

  - Reduce time step for better numerical stability

  - Check for unrealistic joint limits or masses

  - Verify contact parameters are reasonable

GUI Issues

  - Ensure PyBullet GUI mode is properly initialized

  - Check for conflicting parameter names

  - Verify graphics drivers support OpenGL

Memory Issues

  - Monitor CuPy memory usage for large trajectories

  - Use batch processing for very long simulations

  - Clear visualization lines periodically

—

## Integration with Other Modules

### Path Planning Integration

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

Title underline too short.

    Path Planning Integration
    ------------------------

    # Using trajectory planner with simulation
    from ManipulaPy.path_planning import TrajectoryPlanning

    planner = TrajectoryPlanning(
        sim.robot,
        sim.urdf_file_path,
        sim.dynamics,
        sim.joint_limits,
        sim.torque_limits
    )

    # Generate smooth trajectory
    trajectory = planner.joint_trajectory(
        thetastart, thetaend, Tf=3.0, N=150, method=5
    )

    # Execute in simulation
    sim.run_trajectory(trajectory["positions"])

### Control System Integration

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

Title underline too short.

    Control System Integration
    -------------------------

    # Advanced controller setup
    from ManipulaPy.control import ManipulatorController

    controller = ManipulatorController(sim.dynamics)

    # Auto-tune controller gains
    Ku, Tu = controller.find_ultimate_gain_and_period(
        thetalist=np.zeros(6),
        desired_joint_angles=np.array([0.1, 0.2, 0.1, 0.0, 0.1, 0.0]),
        dt=sim.time_step
    )

    Kp, Ki, Kd = controller.tune_controller(Ku, Tu, kind="PID")

    # Use tuned gains in simulation
    sim.run_controller(controller, positions, velocities, accelerations,
                      g, Ftip, Kp, Ki, Kd)

### Vision System Integration

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

Title underline too short.

    Vision System Integration
    ------------------------

    # Camera-based simulation feedback
    from ManipulaPy.vision import Vision
    from ManipulaPy.perception import Perception

    # Setup vision system (if available)
    vision = Vision(use_pybullet_debug=True)
    perception = Perception(vision_instance=vision)

    # Use perception for obstacle avoidance in simulation
    obstacles, labels = perception.detect_and_cluster_obstacles()

    # Modify trajectory based on detected obstacles
    # (Implementation depends on specific requirements)

—

## See Also

- Control API Reference – Controller implementations for simulation

- Path Planning API Reference – Trajectory generation for simulation

- URDF Processor API Reference – URDF loading and robot model creation

- Dynamics API Reference – Robot dynamics for physics simulation

- Kinematics API Reference – Forward and inverse kinematics

- Vision API Reference – Computer vision integration

- Perception API Reference – Environmental perception capabilities

## External References

- PyBullet Documentation

- CuPy Documentation

- URDF Specification