_api-control:

Control API Reference#

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

Note

As of v1.3.2, the control module is GPU-optional / backend-agnostic: it runs on NumPy by default and accepts CuPy arrays where available. Public type hints no longer reference cp.ndarray — inputs are coerced to NumPy internally, so callers can mix backends freely.

Tip

For conceptual explanations, see Control Module User Guide.

—

Quick Navigation#

—

ManipulatorController Class#

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

Bases: object

CPU-based manipulator controller implementations and tuning utilities.

Main class for control of robotic manipulators. Backend-agnostic: works with NumPy or CuPy arrays (CuPy inputs are coerced to NumPy internally as of v1.3.2).

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

—

Control Strategies#

Basic Controllers#

ManipulatorController.pid_control(thetalistd, dthetalistd, thetalist, dthetalist, dt, Kp, Ki, Kd, i_clamp=None)[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, i_clamp=None)[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

Raises:

  • ValueError – if kalman_filter_predict has not been called (self.x_hat is None).

  • ValueError – if self.P is None or does not have shape (n, n) where n == self.x_hat.shape[0].

Return type:

None

Changed in version 1.3.2: Both the x_hat and P preconditions are now validated up-front and raise ValueError with a descriptive message instead of failing inside the matrix algebra.

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

Return type:

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.

Returns the first time at which the response enters the tolerance band and never leaves it again. Returns float('inf') when the response never enters the band, or enters but does not remain settled through the end of the recorded data.

Parameters:

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

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

  • set_point (float) – Desired set point value.

  • tolerance (float) – Fractional tolerance band (default 0.02 = 2 %).

  • time – Array of time steps.

  • response – Array of response values.

  • set_point – Desired set point value (may be negative).

  • tolerance – Fractional tolerance band (default 0.02 = 2 %).

Returns:

Settling time, or inf if the response never settles.

Return type:

float

Returns:

First time at which the response enters the tolerance band and never leaves it again, or float('inf') if it never settles.

Return type:

float

Changed in version 1.3.2: Returns the first time the response enters the settling band and stays there (was returning the last cross). Negative setpoints are now handled correctly.

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

Compute Ziegler-Nichols controller gains.

Parameters:
Returns:

Tuple of (Kp, Ki, Kd) gains.

Return type:

Tuple[float | ndarray[tuple[Any, …], dtype[float64]], float | ndarray[tuple[Any, …], dtype[float64]], float | ndarray[tuple[Any, …], dtype[float64]]]

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

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

Parameters:
Return type:

Tuple[float | ndarray[tuple[Any, …], dtype[float64]], float | ndarray[tuple[Any, …], dtype[float64]], float | ndarray[tuple[Any, …], dtype[float64]]]

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