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.

—

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

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

# 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

# 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

# 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

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

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

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

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

# 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

# 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

# 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)

—

Simulation API Reference

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

Running a Trajectory

Interactive Manual Control

Controller Integration

Collision Monitoring

Data Logging and Analysis

Complete Simulation Loop

Configuration Options

Simulation Parameters

Physics Settings

GUI Controls

Performance Considerations

GPU Acceleration

Real-time Performance

Error Handling

Common Issues and Solutions

Integration with Other Modules

Path Planning Integration

Control System Integration

Vision System Integration

See Also

External References