src.environment.problem.SOO.UAV.uav_numpy

========================================================= File Name: uav_numpy.py Author: Sijie Ma (GitHub: Feather_red) Date: 2025-02-17

Description: This script implements UAV path planning based on the paper: “Benchmarking Global Optimization Techniques for Unmanned Aerial Vehicle Path Planning.” It provides a Python migration of a MATLAB implementation.

Features:

  • Implements UAV path planning in a real-world scenario.

  • Uses NumPy for numerical computations.

  • Translates MATLAB code to Python.

Dependencies:

  • numpy

  • torch

  • pickle

References:

  • Shehadeh, M. A., & Kudela, J. (2025). Benchmarking global optimization techniques for unmanned aerial vehicle path planning. arXiv. https://arxiv.org/abs/2501.14503

Version:

  • Python implementation using NumPy

=========================================================

Module Contents

Classes

UAV_Numpy_Problem

Introduction

UAV provides 56 terrain-based landscapes as realistic Unmanned Aerial Vehicle(UAV) path planning problems, each of which is 30D. The objective is to select given number of path nodes (x,y,z coordinates) from the 3D space, so the the UAV could fly as shortly as possible in a collision-free way.

Terrain

Introduction

Represents a UAV path planning problem over a 3D terrain, evaluating the cost of candidate paths based on multiple criteria such as path length, threats, altitude, smoothness, and terrain clearance.

API

class src.environment.problem.SOO.UAV.uav_numpy.UAV_Numpy_Problem[source]

Bases: src.environment.problem.basic_problem.Basic_Problem

Introduction

UAV provides 56 terrain-based landscapes as realistic Unmanned Aerial Vehicle(UAV) path planning problems, each of which is 30D. The objective is to select given number of path nodes (x,y,z coordinates) from the 3D space, so the the UAV could fly as shortly as possible in a collision-free way.

Original paper

“Benchmarking global optimization techniques for unmanned aerial vehicle path planning.” arXiv preprint arXiv:2501.14503 (2025).

Official Implementation

UAV

License

None

Initialization

Introduction

Initializes the UAV problem environment with default attributes for terrain modeling, function evaluation count, optimum value, problem identification, dimensionality, and variable bounds.

Attributes:

  • terrain_model (Any or None): The terrain model associated with the UAV problem.

  • FES (int): The number of function evaluations performed, initialized to 0.

  • optimum (Any or None): The optimum value for the problem, if known.

  • problem_id (Any or None): Identifier for the specific problem instance.

  • dim (Any or None): The dimensionality of the problem.

  • lb (Any or None): The lower bounds for the problem variables.

  • ub (Any or None): The upper bounds for the problem variables.

__str__()[source]

Introduction

Returns a string representation of the terrain associated with this problem instance.

Returns:

  • str: A string in the format “Terrain {problem_id}” where problem_id is the identifier of the problem.

__boundaries__()[source]

Introduction

Computes and sets the lower and upper boundaries for UAV trajectory optimization variables, including position (radial distance, inclination, azimuth) and their velocities, based on the terrain model and problem configuration.

Args:

None

Built-in Attribute:

  • self.lb (np.ndarray): Lower bounds for each optimization variable, tiled for all trajectory points.

  • self.ub (np.ndarray): Upper bounds for each optimization variable, tiled for all trajectory points.

Returns:

None

Raises:

None

spherical_to_cart_vec(solve)[source]

Introduction

Converts a batch of spherical coordinates to Cartesian coordinates for multiple UAV waypoints, applying boundary constraints from the terrain model.

Args:

  • solve (np.ndarray): A 2D NumPy array of shape [NP, 3 * n], where NP is the number of solutions (batches) and n is the number of waypoints. Each row contains concatenated spherical coordinates (r, psi, phi) for each waypoint.

Built-in Attribute:

  • self.terrain_model (dict): A dictionary containing the terrain boundaries and the starting coordinates, with keys ‘start’, ‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’, ‘zmin’, ‘zmax’.

Returns:

  • tuple: A tuple of three np.ndarray objects (x, y, z), each of shape [NP, n], representing the Cartesian coordinates of the waypoints for each solution.

Raises:

  • KeyError: If required keys are missing in self.terrain_model.

  • ValueError: If the input array solve does not have the expected shape.

DistP2S(xs, a, b)[source]

Introduction

Calculates the shortest Euclidean distance from a point to a set of line segments in 2D space using NumPy arrays.

Args:

  • xs (np.ndarray): A 1D array of shape [2], representing the coordinates of the point.

  • a (np.ndarray): A 2D array of shape [2, NP], representing the starting points of the line segments.

  • b (np.ndarray): A 2D array of shape [2, NP], representing the ending points of the line segments.

Returns:

  • np.ndarray: A 1D array of shape [NP], where each element is the shortest distance from the point xs to the corresponding line segment defined by a[:, i] and b[:, i].

Notes:

  • If the segment is degenerate (i.e., a and b are the same point), the distance is computed as the distance from xs to a.

  • If the perpendicular projection of xs onto the line defined by a and b falls outside the segment, the distance to the nearest endpoint is returned.

class src.environment.problem.SOO.UAV.uav_numpy.Terrain(terrain_model, problem_id)[source]

Bases: src.environment.problem.SOO.UAV.uav_numpy.UAV_Numpy_Problem

Introduction

Represents a UAV path planning problem over a 3D terrain, evaluating the cost of candidate paths based on multiple criteria such as path length, threats, altitude, smoothness, and terrain clearance.

Initialization

Initializes the UAV problem environment with the specified terrain model and problem ID.

Args:

  • terrain_model (dict): A dictionary containing terrain model parameters, including the number of UAVs ('n').

  • problem_id (Any): An identifier for the specific problem instance.

Attributes:

  • terrain_model (dict): Stores the provided terrain model.

  • dim (int): The dimensionality of the problem, calculated as three times the number of UAVs.

  • problem_id (Any): Stores the provided problem identifier.

  • optimum (Any or None): Placeholder for the optimum solution, initialized as None.

Notes:

  • Calls the __boundaries__() method to set up problem boundaries.

  • Inherits from the Terrain class.

func(solve)[source]

Introduction

Evaluates the total cost for a set of UAV paths based on multiple criteria, including path length, threats, altitude, smoothness, and terrain constraints. The function computes a weighted sum of these costs for each candidate solution.

Args:

  • solve (np.ndarray): A 2D numpy array of shape [NP, 3 * nv], where each row represents a candidate solution in spherical coordinates for the UAV path.

Built-in Attribute:

  • self.terrain_model (dict): Contains terrain and mission parameters such as start/end locations, threat information, altitude constraints, and penalty values.

Returns:

  • np.ndarray: A 1D numpy array of length NP, where each element is the total cost associated with a candidate UAV path.

Raises:

  • IndexError: If the indices computed for terrain or threat arrays are out of bounds.

  • KeyError: If required keys are missing from the terrain model dictionary.

  • ValueError: If input shapes are inconsistent or invalid for the computations.

are_paths_clear(x_all, y_all, z_abs, H, num_samples=12)[source]

Introduction

Checks whether all line segments connecting adjacent points of multiple UAV paths are completely above the terrain surface.

Args:

  • x_all (np.ndarray): Array of shape (NP, N) containing x coordinates of N points for each of NP paths.

  • y_all (np.ndarray): Array of shape (NP, N) containing y coordinates of N points for each of NP paths.

  • z_abs (np.ndarray): Array of shape (NP, N) containing absolute heights of N points for each of NP paths.

  • H (np.ndarray): 2D array of shape (H_rows, H_cols) representing the terrain height matrix.

  • num_samples (int, optional): Number of sample points to interpolate along each line segment (excluding endpoints). Default is 12.

Returns:

  • np.ndarray: Boolean array of shape (NP,) where each value indicates whether all segments of a path are above the terrain.

Notes:

  • Uses linear interpolation to sample points along each path segment and checks if all sampled points are above the terrain.

  • If any sampled point is not above the terrain, the corresponding path is marked as not clear.