irsim.lib.algorithm

Core algorithms for IR-SIM simulation.

This package contains: - kinematics: Robot kinematics functions - rvo: Reciprocal Velocity Obstacle algorithm - social_force_model: Anisotropic Social Force Model (Moussaïd 2009) - generation: Polygon generation utilities

Submodules

• irsim.lib.algorithm.generation
• irsim.lib.algorithm.kinematics
• irsim.lib.algorithm.rvo
• irsim.lib.algorithm.social_force_model

Classes

reciprocal_vel_obs	A class to implement the Reciprocal Velocity Obstacle (RVO) algorithm for multi-robot collision avoidance.
social_force_model	Social Force Model controller for a single agent.

Functions

generate_polygon(→ numpy.ndarray)	Generate a random polygon around a center point.
random_generate_polygon(...)	reference: https://stackoverflow.com/questions/8997099/algorithm-to-generate-random-2d-polygon
ackermann_kinematics(→ numpy.ndarray)	Calculate the next state for an Ackermann steering vehicle.
differential_kinematics(→ numpy.ndarray)	Calculate the next state for a differential wheel robot.
omni_angular_kinematics(→ numpy.ndarray)	Calculate the next state for an omnidirectional robot with angular velocity.
omni_kinematics(→ numpy.ndarray)	Calculate the next position for an omnidirectional robot.

Package Contents

irsim.lib.algorithm.generate_polygon(center: list[float], avg_radius: float, irregularity: float, spikeyness: float, num_vertices: int) → numpy.ndarray

Generate a random polygon around a center point.

Parameters:

• center (Tuple[float, float]) – Center of the polygon.

• avg_radius (float) – Average radius from the center to vertices.

• irregularity (float) – Variance of angle spacing between vertices. Range [0, 1]

• spikeyness (float) – Variance of radius from the center. Range [0, 1]

• num_vertices (int) – Number of vertices for the polygon.

Returns:

Vertices of the polygon in CCW order.

Return type:

numpy.ndarray

irsim.lib.algorithm.random_generate_polygon(number: int = 1, center_range: list[float] | None = None, avg_radius_range: list[float] | None = None, irregularity_range: list[float] | None = None, spikeyness_range: list[float] | None = None, num_vertices_range: list[int] | None = None, **kwargs: Any) → numpy.ndarray | list[numpy.ndarray]

reference: https://stackoverflow.com/questions/8997099/algorithm-to-generate-random-2d-polygon

Generate random polygons with specified properties.

Parameters:

• number (int) – Number of polygons to generate (default 1).

• center_range (List[float]) – Range for the polygon center [min_x, min_y, max_x, max_y].

• avg_radius_range (List[float]) – Range for the average radius of the polygons.

• irregularity_range (List[float]) – Range for the irregularity of the polygons.

• spikeyness_range (List[float]) – Range for the spikeyness of the polygons.

• num_vertices_range (List[int]) – Range for the number of vertices of the polygons.

Returns:

List of vertices for each polygon or a single polygon’s vertices if number=1.

irsim.lib.algorithm.ackermann_kinematics(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float, noise: bool = False, alpha: list[float] | None = None, mode: str = 'steer', wheelbase: float = 1) → numpy.ndarray

Calculate the next state for an Ackermann steering vehicle.

Parameters:

• state – A 4x1 vector [x, y, theta, steer_angle] representing the current state.

• velocity – A 2x1 vector representing the current velocities, format depends on mode. For “steer” mode, [linear, steer_angle] is expected. For “angular” mode, [linear, angular] is expected.

• step_time – The time step for the simulation.

• noise – Boolean indicating whether to add noise to the velocity (default False).

• alpha – List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). alpha[0] and alpha[1] are for linear velocity, alpha[2] and alpha[3] are for angular velocity.

• mode – The kinematic mode, either “steer” or “angular” (default “steer”).

• wheelbase – The distance between the front and rear axles (default 1).

Returns:

A 4x1 vector representing the next state.

Return type:

new_state

irsim.lib.algorithm.differential_kinematics(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float, noise: bool = False, alpha: list[float] | None = None) → numpy.ndarray

Calculate the next state for a differential wheel robot.

Parameters:

• state – A 3x1 vector [x, y, theta] representing the current position and orientation.

• velocity – A 2x1 vector [linear, angular] representing the current velocities.

• step_time – The time step for the simulation.

• noise – Boolean indicating whether to add noise to the velocity (default False).

• alpha – List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). alpha[0] and alpha[1] are for linear velocity, alpha[2] and alpha[3] are for angular velocity.

Returns:

A 3x1 vector [x, y, theta] representing the next state.

Return type:

next_state

irsim.lib.algorithm.omni_angular_kinematics(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float, noise: bool = False, alpha: list[float] | None = None) → numpy.ndarray

Calculate the next state for an omnidirectional robot with angular velocity.

Uses body-frame velocity: the first two components are forward and lateral speeds relative to the robot heading, and the third is yaw rate.

Parameters:

• state – A 3x1 vector [x, y, theta] representing the current position and orientation.

• velocity – A 3x1 vector [forward, lateral, yaw_rate] in body frame.

• step_time – The time step for the simulation.

• noise – Boolean indicating whether to add noise to the velocity (default False).

• alpha – List of noise parameters [alpha_fwd, alpha_lat, alpha_yaw] (default [0.03, 0.03, 0.03]). Each value scales the standard deviation for the corresponding velocity channel.

Returns:

A 3x1 vector [x, y, theta] representing the next state.

Return type:

next_state

irsim.lib.algorithm.omni_kinematics(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float, noise: bool = False, alpha: list[float] | None = None) → numpy.ndarray

Calculate the next position for an omnidirectional robot.

Uses body-frame velocity: the two components are forward and lateral speeds relative to the robot heading (theta). Since omni robots have no yaw control, theta remains unchanged.

Parameters:

• state – A 3x1 vector [x, y, theta] representing the current state.

• velocity – A 2x1 vector [forward, lateral] in body frame.

• step_time – The time step for the simulation.

• noise – Boolean indicating whether to add noise to the velocity (default False).

• alpha – List of noise parameters for the velocity model (default [0.03, 0.03]).

Returns:

A 3x1 vector [x, y, theta] representing the next state.

Theta is preserved unchanged.

Return type:

next_state

class irsim.lib.algorithm.reciprocal_vel_obs(state: list, obs_state_list=None, vxmax=1.5, vymax=1.5, acce=0.5, factor=1.0, line_obs_list=None)

A class to implement the Reciprocal Velocity Obstacle (RVO) algorithm for multi-robot collision avoidance.

Parameters:

• state (list) – The rvo state of the agent [x, y, vx, vy, radius, vx_des, vy_des].

• obs_state_list (list) – List of states of static obstacles [[x, y, vx, vy, radius]].

• vxmax (float) – Maximum velocity in the x direction.

• vymax (float) – Maximum velocity in the y direction.

• acce (float) – Acceleration limit.

• factor (float) – Penalty weighting factor for velocity selection.

• line_obs_list (list) – List of line segments [[x1, y1, x2, y2], …].

state

obs_state_list = None

line_obs_list = None

vxmax = 1.5

vymax = 1.5

acce = 0.5

factor = 1.0

update(state, obs_state_list, line_obs_list=None)

cal_vel(mode='rvo')

Calculate the velocity of the agent based on the Reciprocal Velocity Obstacle (RVO) algorithm.

Parameters:

mode (str) – The vo configure to calculate the velocity. It can be “rvo”, “hrvo”, or “vo”. - rvo: Reciprocal Velocity Obstacle (RVO) algorithm, for multi-robot collision avoidance. - hrvo: Hybrid Reciprocal Velocity Obstacle (HRVO) algorithm, for multi-robot collision avoidance. - vo: Velocity Obstacle (VO) algorithm, for obstacle-robot collision avoidance.

Returns:

Selected velocity [vx, vy].

Return type:

list[float]

config_rvo()

config_rvo_mode(obstacle)

config_hrvo()

config_hrvo_mode(obstacle)

config_vo()

config_vo_mode(obstacle)

config_vo_lines()

Compute VO cones for line segment obstacles.

For each segment, compute the angular span as seen from the agent, expanded by asin(r / dist) on each side to account for the agent radius. The apex is [0, 0] since line obstacles are static.

vel_candidate(rvo_list)

vo_out(vx, vy, rvo_list)

vel_select(vo_outside, vo_inside)

penalty(vel, vel_des, factor)

static between_vector(line_left_vector, line_right_vector, line_vector)

static cross_product(vector1, vector2)

class irsim.lib.algorithm.social_force_model(state: list, neighbor_list: list | None = None, line_obs_list: list | None = None, vmax: float = 1.5, step_time: float = 0.1, relaxation_time: float = 0.5, force_factor_desired: float = 1.0, force_factor_social: float = 2.1, force_factor_obstacle: float = 10.0, sigma_obstacle: float = 0.8, lambda_importance: float = 2.0, gamma: float = 0.35, n_angular: float = 2.0, n_velocity: float = 3.0, neighbor_range: float = 10.0, safety_radius: float = 0.0)

Social Force Model controller for a single agent.

The interface mirrors reciprocal_vel_obs so the two algorithms are interchangeable from a behavior method.

Parameters:

• state (list) – Agent state [x, y, vx, vy, radius, vx_des, vy_des, theta].

• neighbor_list (list) – Other moving/static circular agents [[x, y, vx, vy, radius], ...].

• line_obs_list (list) – Line obstacles [[x1, y1, x2, y2], ...].

• vmax (float) – Speed cap applied after the velocity update.

• step_time (float) – Integration step dt.

• relaxation_time (float) – tau in the desired-force term.

• force_factor_desired (float) – Weight alpha_D on the desired force.

• force_factor_social (float) – Weight alpha_S on the social force.

• force_factor_obstacle (float) – Weight alpha_O on the obstacle force.

• sigma_obstacle (float) – Decay length of the obstacle repulsion.

• lambda_importance (float) – Weight of relative velocity in the interaction direction (lambda in Moussaïd 2009).

• gamma (float) – Sets the interaction range B = gamma * ||t||.

• n_angular (float) – Angular sharpness n for the sideways force.

• n_velocity (float) – Angular sharpness n' for the slowdown force.

• neighbor_range (float) – Max distance for an agent to count as a social-force neighbor.

• safety_radius (float) – Personal-space buffer subtracted from the agent-to-agent distance inside the social-force exponential. 0 reproduces the upstream behavior (point agents). > 0 shifts the decay closer-in so the repulsion saturates at 2 * safety_radius of centre-to-centre clearance, effectively giving each agent a body radius for SFM.

state

neighbor_list

line_obs_list

vmax = 1.5

step_time = 0.1

relaxation_time = 0.5

force_factor_desired = 1.0

force_factor_social = 2.1

force_factor_obstacle = 10.0

sigma_obstacle = 0.8

lambda_importance = 2.0

gamma = 0.35

n_angular = 2.0

n_velocity = 3.0

neighbor_range = 10.0

safety_radius = 0.0

update(state: list, neighbor_list: list, line_obs_list: list | None = None) → None

Refresh the per-step inputs without re-instantiating.

cal_vel() → list

Integrate one SFM step and return the new global velocity.

Returns:

Updated velocity [vx, vy], clipped to vmax.

Return type:

list[float]

desired_force() → list

Relaxation toward the desired velocity v0 * e_goal.

The desired velocity is supplied directly via state[5:7].

social_force() → list

Anisotropic neighbor repulsion (Moussaid-Helbing 2009).

Iterates over all neighbors within neighbor_range and sums their contribution.

obstacle_force() → list

Exponential repulsion summed over all nearby line obstacles.

The upstream reference uses only the single nearest obstacle, which oscillates in symmetric environments (two parallel walls flip which one is “nearest” each step). We use the Helbing-Molnar (1995) summation form instead: every segment within 5 * sigma_obstacle contributes an exponentially decayed push, so symmetric walls cancel and the agent walks the centreline. The integration is also clamped against overlap (distance < 0 would otherwise make exp(-distance/sigma) explode).