_api-control:

Control API Reference

This page documents ManipulaPy.control, the module for manipulator control algorithms with GPU acceleration.

Tip

For conceptual explanations, see Control Module User Guide.

β€”

Quick Navigation

β€”

ManipulatorController Class

class ManipulaPy.control.ManipulatorController(dynamics)[source]

Bases: object

Main class for control of robotic manipulators using CuPy-accelerated algorithms.

Constructor

Parameters:

dynamics (Any) –

__init__(dynamics)[source]

Initialize the ManipulatorController with the dynamics of the manipulator.

Note: Control algorithms now use CPU (NumPy) to avoid GPU-CPU transfer overhead, since the dynamics module operates on NumPy arrays.

Parameters:

dynamics (ManipulatorDynamics) – An instance of ManipulatorDynamics.

Return type:

None

Parameters:

  • dynamics (ManipulatorDynamics) – Instance providing dynamics computations

computed_torque_control(thetalistd, dthetalistd, ddthetalistd, thetalist, dthetalist, g, dt, Kp, Ki, Kd)[source]

Computed Torque Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead. The dynamics module operates on NumPy arrays, so keeping everything on CPU is more efficient than repeated GPU↔CPU transfers.

Parameters:
Returns:

Torque command (CPU-based NumPy array).

Return type:

NDArray

pd_control(desired_position, desired_velocity, current_position, current_velocity, Kp, Kd)[source]

PD Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

PD control signal (CPU-based NumPy array).

Return type:

NDArray

pid_control(thetalistd, dthetalistd, thetalist, dthetalist, dt, Kp, Ki, Kd)[source]

PID Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

PID control signal (CPU-based NumPy array).

Return type:

NDArray

robust_control(thetalist, dthetalist, ddthetalist, g, Ftip, disturbance_estimate, adaptation_gain)[source]

Robust Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Robust control torque (CPU-based NumPy array).

Return type:

NDArray

adaptive_control(thetalist, dthetalist, ddthetalist, g, Ftip, measurement_error, adaptation_gain)[source]

Adaptive Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Adaptive control torque (CPU-based NumPy array).

Return type:

NDArray

kalman_filter_predict(thetalist, dthetalist, taulist, g, Ftip, dt, Q)[source]

Kalman Filter Prediction.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

None

Return type:

None

kalman_filter_update(z, R)[source]

Kalman Filter Update.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

None

Return type:

None

kalman_filter_control(thetalistd, dthetalistd, thetalist, dthetalist, taulist, g, Ftip, dt, Q, R)[source]

Kalman Filter Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Estimated joint angles and velocities (CPU-based NumPy arrays).

Return type:

tuple

feedforward_control(desired_position, desired_velocity, desired_acceleration, g, Ftip)[source]

Feedforward Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Feedforward torque (CPU-based NumPy array).

Return type:

NDArray

pd_feedforward_control(desired_position, desired_velocity, desired_acceleration, current_position, current_velocity, Kp, Kd, g, Ftip)[source]

PD Feedforward Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Control signal (CPU-based NumPy array).

Return type:

NDArray

static enforce_limits(thetalist, dthetalist, tau, joint_limits, torque_limits)[source]

Enforce joint and torque limits.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Clipped joint angles, velocities, and torques (CPU-based NumPy arrays).

Return type:

tuple

plot_steady_state_response(time, response, set_point, title='Steady State Response')[source]

Plot the steady-state response of the controller.

Parameters:

  • time (np.ndarray) – Array of time steps.

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

  • title (str, optional) – Title of the plot.

Returns:

None

calculate_rise_time(time, response, set_point)[source]

Calculate the rise time.

Parameters:

  • time (np.ndarray) – Array of time steps.

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

Returns:

Rise time.

Return type:

float

calculate_percent_overshoot(response, set_point)[source]

Calculate the percent overshoot.

Parameters:

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

Returns:

Percent overshoot.

Return type:

float

calculate_settling_time(time, response, set_point, tolerance=0.02)[source]

Calculate the settling time.

Parameters:

  • time (np.ndarray) – Array of time steps.

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

  • tolerance (float) – Tolerance for settling time calculation.

Returns:

Settling time.

Return type:

float

calculate_steady_state_error(response, set_point)[source]

Calculate the steady-state error.

Parameters:

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

Returns:

Steady-state error.

Return type:

float

joint_space_control(desired_joint_angles, current_joint_angles, current_joint_velocities, Kp, Kd)[source]

Joint Space Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Control torque (CPU-based NumPy array).

Return type:

NDArray

cartesian_space_control(desired_position, current_joint_angles, current_joint_velocities, Kp, Kd)[source]

Cartesian Space Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Control torque (CPU-based NumPy array).

Return type:

NDArray

tune_controller(Ku, Tu, kind='PID')[source]

Convenience wrapper that logs and returns NumPy arrays (length = DOF).

find_ultimate_gain_and_period(thetalist, desired_joint_angles, dt, max_steps=1000)[source]

Find the ultimate gain and period using the Ziegler–Nichols method.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:

  • thetalist (ndarray[Any, dtype[float64]] | List[float]) – Initial joint angles (shape [6]).

  • desired_joint_angles (ndarray[Any, dtype[float64]] | List[float]) – Step target angles (shape [6]).

  • dt (float) – Simulation time step.

  • max_steps (int) – Number of integration steps to try.

Returns:

  • ultimate_gain (float)

  • ultimate_period (float)

  • gain_history (list of float)

  • error_history (list of np.ndarray)

Return type:

tuple

β€”

Control Strategies

Basic Controllers

ManipulatorController.pid_control(thetalistd, dthetalistd, thetalist, dthetalist, dt, Kp, Ki, Kd)[source]

PID Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

PID control signal (CPU-based NumPy array).

Return type:

NDArray

ManipulatorController.pd_control(desired_position, desired_velocity, current_position, current_velocity, Kp, Kd)[source]

PD Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

PD control signal (CPU-based NumPy array).

Return type:

NDArray

Advanced Controllers

ManipulatorController.computed_torque_control(thetalistd, dthetalistd, ddthetalistd, thetalist, dthetalist, g, dt, Kp, Ki, Kd)[source]

Computed Torque Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead. The dynamics module operates on NumPy arrays, so keeping everything on CPU is more efficient than repeated GPU↔CPU transfers.

Parameters:
Returns:

Torque command (CPU-based NumPy array).

Return type:

NDArray

ManipulatorController.adaptive_control(thetalist, dthetalist, ddthetalist, g, Ftip, measurement_error, adaptation_gain)[source]

Adaptive Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Adaptive control torque (CPU-based NumPy array).

Return type:

NDArray

ManipulatorController.robust_control(thetalist, dthetalist, ddthetalist, g, Ftip, disturbance_estimate, adaptation_gain)[source]

Robust Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Robust control torque (CPU-based NumPy array).

Return type:

NDArray

Feedforward Control

ManipulatorController.feedforward_control(desired_position, desired_velocity, desired_acceleration, g, Ftip)[source]

Feedforward Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Feedforward torque (CPU-based NumPy array).

Return type:

NDArray

ManipulatorController.pd_feedforward_control(desired_position, desired_velocity, desired_acceleration, current_position, current_velocity, Kp, Kd, g, Ftip)[source]

PD Feedforward Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Control signal (CPU-based NumPy array).

Return type:

NDArray

Space-Specific Control

ManipulatorController.joint_space_control(desired_joint_angles, current_joint_angles, current_joint_velocities, Kp, Kd)[source]

Joint Space Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Control torque (CPU-based NumPy array).

Return type:

NDArray

ManipulatorController.cartesian_space_control(desired_position, current_joint_angles, current_joint_velocities, Kp, Kd)[source]

Cartesian Space Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Control torque (CPU-based NumPy array).

Return type:

NDArray

β€”

State Estimation

ManipulatorController.kalman_filter_predict(thetalist, dthetalist, taulist, g, Ftip, dt, Q)[source]

Kalman Filter Prediction.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

None

Return type:

None

ManipulatorController.kalman_filter_update(z, R)[source]

Kalman Filter Update.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

None

Return type:

None

ManipulatorController.kalman_filter_control(thetalistd, dthetalistd, thetalist, dthetalist, taulist, g, Ftip, dt, Q, R)[source]

Kalman Filter Control.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Estimated joint angles and velocities (CPU-based NumPy arrays).

Return type:

tuple

β€”

Performance Analysis Tools

ManipulatorController.plot_steady_state_response(time, response, set_point, title='Steady State Response')[source]

Plot the steady-state response of the controller.

Parameters:

  • time (np.ndarray) – Array of time steps.

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

  • title (str, optional) – Title of the plot.

Returns:

None

ManipulatorController.calculate_rise_time(time, response, set_point)[source]

Calculate the rise time.

Parameters:

  • time (np.ndarray) – Array of time steps.

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

Returns:

Rise time.

Return type:

float

ManipulatorController.calculate_percent_overshoot(response, set_point)[source]

Calculate the percent overshoot.

Parameters:

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

Returns:

Percent overshoot.

Return type:

float

ManipulatorController.calculate_settling_time(time, response, set_point, tolerance=0.02)[source]

Calculate the settling time.

Parameters:

  • time (np.ndarray) – Array of time steps.

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

  • tolerance (float) – Tolerance for settling time calculation.

Returns:

Settling time.

Return type:

float

ManipulatorController.calculate_steady_state_error(response, set_point)[source]

Calculate the steady-state error.

Parameters:

  • response (np.ndarray) – Array of response values.

  • set_point (float) – Desired set point value.

Returns:

Steady-state error.

Return type:

float

β€”

Auto-Tuning and Limits

ManipulatorController.ziegler_nichols_tuning(Ku, Tu, kind='PID')[source]
ManipulatorController.tune_controller(Ku, Tu, kind='PID')[source]

Convenience wrapper that logs and returns NumPy arrays (length = DOF).

ManipulatorController.find_ultimate_gain_and_period(thetalist, desired_joint_angles, dt, max_steps=1000)[source]

Find the ultimate gain and period using the Ziegler–Nichols method.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:

  • thetalist (ndarray[Any, dtype[float64]] | List[float]) – Initial joint angles (shape [6]).

  • desired_joint_angles (ndarray[Any, dtype[float64]] | List[float]) – Step target angles (shape [6]).

  • dt (float) – Simulation time step.

  • max_steps (int) – Number of integration steps to try.

Returns:

  • ultimate_gain (float)

  • ultimate_period (float)

  • gain_history (list of float)

  • error_history (list of np.ndarray)

Return type:

tuple

static ManipulatorController.enforce_limits(thetalist, dthetalist, tau, joint_limits, torque_limits)[source]

Enforce joint and torque limits.

Uses CPU-based computation to avoid GPU-CPU transfer overhead.

Parameters:
Returns:

Clipped joint angles, velocities, and torques (CPU-based NumPy arrays).

Return type:

tuple

β€”

See Also