PySwarming package

pyswarming.behaviors

The PySwarming behaviors functions are based on researches of different authors, for details, see the documentation available in two forms: docstrings provided with the code, and a loose standing reference guide, available from the PySwarming homepage..

Functions present in pyswarming.behaviors are listed below.

Behaviors

leaderless_heading_consensus inverse_power spring force_law repulsive_force body_force inter_robot_spacing dissipative leader_following collision_avoidance attraction_alignment preferred_direction lennard_jones virtual_viscosity modified_attraction_alignment heading_consensus perimeter_defense environment_exploration aggregation alignment geofencing repulsion target area_coverage collective_navigation flocking

Combined Behaviors

area_coverage = geofencing + repulsion collective_navigation = target + repulsion flocking = aggregation + repulsion + alignment

pyswarming.behaviors.aggregation(r_i, r_j)

Calculates a nondimensional contribution based on the “aggregation algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

Returns:

g_i – array containing g_i

Return type:

numpy.array

pyswarming.behaviors.alignment(v_i, v_j)

Calculates a nondimensional contribution based on the “alignment algorithm”

Parameters:

• v_i (numpy.array) – array must have the robot velocity in cartesian coordinates (i.e. np.asarray([x, y, z])).

• v_j (numpy.array) – array must have the neighborhood velocities in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

Returns:

g_i – array containing g_i

Return type:

numpy.array

pyswarming.behaviors.area_coverage(r_i, r_j, A, alpha, d=2)

Calculate the area coverage nondimensional orientation contribution

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• A (function) – function of the interested region.

• alpha (float) – float parameter to determine the strength of the repulsion.

• d (integer) – integer > 1 parameter is the multipole order.

Returns:

b_AC – array containing contribution

Return type:

numpy.array

pyswarming.behaviors.attraction_alignment(r_i, r_j, theta_j)

Calculate the desired heading of the robot based on the “attraction and alignment algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• theta_j (numpy.array) – array must have the neighborhood orientations in euler angles (i.e. np.asarray([[roll1, pitch1, yaw1], [roll2, pitch2, yaw2], …, [rollN, pitchN, yawN]])).

Returns:

new_theta_i – array containing the new heading

Return type:

numpy.array

pyswarming.behaviors.body_force(r_i, r_j, Lambda, R_i, R_j)

Calculates an output force based on the “body force algorithm”.

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• Lambda (float) – user-defined coefficient.

• R_i (float) – radii of the robot i.

• R_j (numpy.array) – array with the radii of the robots j.

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.collective_navigation(r_i, r_j, T, alpha, d=2)

Calculate the collective navigation nondimensional orientation contribution

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• T (numpy.array) – array must have the target position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• alpha (float) – float parameter to determine the strength of the repulsion.

• d (integer) – integer > 1 parameter is the multipole order.

Returns:

b_CN – array containing contribution

Return type:

numpy.array

pyswarming.behaviors.collision_avoidance(r_i, r_j)

Calculate the desired heading of the robot based on the “collision avoidance algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

Returns:

new_theta_i – array containing the new heading

Return type:

numpy.array

pyswarming.behaviors.dissipative(v_i, v_d, a)

Calculate a force based on the “dissipative force algorithm”

Parameters:

• v_i (numpy.array) – array must have the robot velocity in cartesian coordinates (i.e. np.asarray([x, y, z])).

• v_d (numpy.array) – array must have the desired robot velocity in cartesian coordinates.

• a (float) – damping factor (a > 0).

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.environment_exploration(r_i, r_j, theta_j, H_i, T, r_0)

Calculate the new velocity of the robot based on the “environment exploration algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• theta_j (numpy.array) – array must have the neighborhood orientations in euler angles (i.e. np.asarray([[roll1, pitch1, yaw1], [roll2, pitch2, yaw2], …, [rollN, pitchN, yawN]])).

• H_i (integer) – binary heading consensus weight, being toward a goal (H_i = 1) or with reference to the others robots (H_i = 0).

• T (numpy.array) – array must have the target (goal) position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_0 (float) – reference distance between the robots to create a set of robots within this range.

Returns:

v_i – array containing the new velocity v_i

Return type:

numpy.array

pyswarming.behaviors.flocking(r_i, r_j, v_i, v_j, alpha, d=2)

Calculate the flocking nondimensional orientation contribution

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• alpha (float) – float parameter to determine the strength of the repulsion.

• d (integer) – integer > 1 parameter is the multipole order.

• v_i (numpy.array) – array must have the robot velocity in cartesian coordinates (i.e. np.asarray([x, y, z])).

• v_j (numpy.array) – array must have the neighborhood velocities in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

Returns:

b_F – array containing contribution

Return type:

numpy.array

pyswarming.behaviors.force_law(r_i, r_j, G, m_i, m_j, p)

Calculates an output force based on the “force law algorithm”.

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• G (float) – coefficient that acts like a gravitational constant.

• m_i (float) – mass of robot i.

• m_j (numpy.array) – array of masses of robots j.

• p (float) – user-defined power.

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.geofencing(r_i, A)

Calculates a nondimensional contribution based on the “geofencing algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• A (function) – function of the interested region. e.g. A = lambda x: np.sqrt(x[0]+x[1]+x[2])

Returns:

g_i – array containing contribution

Return type:

numpy.array

pyswarming.behaviors.heading_consensus(theta_i, theta_j)

Calculate the new robot heading based on the “heading consensus algorithm”

Parameters:

• theta_i (numpy.array) – array must have the robot orientation in euler angles (i.e. np.asarray([roll, pitch, yaw])).

• theta_j (numpy.array) – array must have the neighborhood orientations in euler angles (i.e. np.asarray([[roll1, pitch1, yaw1], [roll2, pitch2, yaw2], …, [rollN, pitchN, yawN]])).

Returns:

new_theta_i – array containing the new heading

Return type:

numpy.array

pyswarming.behaviors.inter_robot_spacing(r_i, r_j, alpha, d_0)

Calculates an output force based on the “inter-robot spacing algorithm”.

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• alpha (float) – user-defined coefficient.

• d_0 (float) – user-defined coefficient.

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.inverse_power(r_i, r_j, c_w, sigma_w)

Calculates an output force based on the “inverse-power force laws algorithm”. This is a simplified version, i.e., the coefficients between the particles are assumed to be the same.

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• c_w (numpy.array) – coefficients that depends on w. Where w is the number of inverse-power laws.

• sigma_w (numpy.array) – the inverse power coefficients (sigma_w>0) that depends on w.

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.leader_following(theta_i, theta_j, theta_0, b_i)

Calculate the new robot heading based on the “leader following algorithm”

Parameters:

• theta_i (numpy.array) – array must have the robot orientation in euler angles (i.e. np.asarray([roll, pitch, yaw])).

• theta_j (numpy.array) – array must have the neighborhood orientations in euler angles (i.e. np.asarray([[roll1, pitch1, yaw1], [roll2, pitch2, yaw2], …, [rollN, pitchN, yawN]])).

• theta_0 (numpy.array) – array must have the leader robot orientation in euler angles (i.e. np.asarray([roll, pitch, yaw])).

• b_i (integer) – integer value where the value is 1 if the leader robot is a neighbor or the robot_i, and 0 otherwise.

Returns:

new_theta_i – array containing the new heading

Return type:

numpy.array

pyswarming.behaviors.leaderless_heading_consensus(theta_i, theta_j)

Calculate the new robot heading based on the “leaderless heading consensus algorithm”

Parameters:

• theta_i (numpy.array) – array must have the robot orientation in euler angles (i.e. np.asarray([roll, pitch, yaw])).

• theta_j (numpy.array) – array must have the neighborhood orientations in euler angles (i.e. np.asarray([[roll1, pitch1, yaw1], [roll2, pitch2, yaw2], …, [rollN, pitchN, yawN]])).

Returns:

new_theta_i – array containing the new heading

Return type:

numpy.array

pyswarming.behaviors.lennard_jones(r_i, r_j, epsilon, sigma, normalized=False)

Calculates an output force that produces lattice formations, based on the “Lennard-Jones potential algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• epsilon (float) – depth of the potential well.

• sigma (float) – desired distance between the robots.

• normalized (boolean) – boolean parameter to normalize each term in the sum when normalized = True.

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.modified_attraction_alignment(r_i, r_j, theta_j, h_j)

Calculate the desired heading of the robot based on the “attraction and alignment algorithm” by considering the “social importance” factor “h”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• theta_j (numpy.array) – array must have the neighborhood orientations in euler angles (i.e. np.asarray([[roll1, pitch1, yaw1], [roll2, pitch2, yaw2], …, [rollN, pitchN, yawN]])).

• h_j (numpy.array) – array must have the neighborhood “social importance” factor (i.e. np.asarray([h_j1, h_j2, …, h_jN])).

Returns:

new_theta_i – array containing the new heading

Return type:

numpy.array

pyswarming.behaviors.perimeter_defense(r_i, r_j)

Calculate the new “heading” based on the “perimeter defense algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

Returns:

g_i – array containing g_i

Return type:

numpy.array

pyswarming.behaviors.preferred_direction(theta_i, k_i, w=0.0)

Calculate the preferred direction of the robot based on the “preferred direction algorithm”

Parameters:

• theta_i (numpy.array) – array must have the robot orientation in euler angles (i.e. np.asarray([roll, pitch, yaw])).

• k_i (numpy.array) – array must have the a preferred direction “k” in euler angles (i.e. np.asarray([roll, pitch, yaw])).

• w (float) – float number giving a weight > 0 for the preferred direction.

Returns:

new_theta_i – array containing the new heading

Return type:

numpy.array

pyswarming.behaviors.repulsion(r_i, r_j, alpha, d=2)

Calculates a nondimensional contribution based on the “repulsion algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• alpha (float) – float parameter to determine the strength of the repulsion.

• d (integer) – integer > 1 parameter is the multipole order.

Returns:

g_i – array containing g_i

Return type:

numpy.array

pyswarming.behaviors.repulsive_force(r_i, r_j, A_i, B_i, R_i, R_j)

Calculates an output force based on the “repulsive force algorithm”.

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• A_i (float) – user-defined coefficient.

• B_i (float) – user-defined coefficient.

• R_i (float) – radii of the robot i.

• R_j (numpy.array) – array with the radii of the robots j.

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.spring(r_i, r_j, k, l)

Calculates an output force based on the “spring laws algorithm”. This is a simplified version, i.e., the coefficients between the particles are assumed to be the same.

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• r_j (numpy.array) – array must have the neighborhood positions in cartesian coordinates (i.e. np.asarray([[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]])).

• k (float) – spring constant (k > 0).

• l (float) – desired distance between the robots.

Returns:

f_i – array containing the force

Return type:

numpy.array

pyswarming.behaviors.target(r_i, T)

Calculates a nondimensional contribution based on the “target algorithm”

Parameters:

• r_i (numpy.array) – array must have the robot position in cartesian coordinates (i.e. np.asarray([x, y, z])).

• T (numpy.array) – array must have the target position in cartesian coordinates (i.e. np.asarray([x, y, z])).

Returns:

b_T – array containing contribution

Return type:

numpy.array

pyswarming.behaviors.virtual_viscosity(v_i, xi, xi_dot, xi_conv, xi_stab)

Calculates a virtual viscosity force based on the “virtual viscosity algorithm”

Parameters:

• v_i (numpy.array) – array must have the robot velocity in cartesian coordinates (i.e. np.asarray([x, y, z])).

• xi (float) – damping factor.

• xi_dot (boolean) – boolean parameter to avoid residual oscillations after the convergence, when xi_dot = True.

• xi_conv (float) – damping factor that ensures the convergence.

• xi_stab (float) – damping factor of reference that depends on the orbit at which the reference frame is located.

Returns:

f_i – array containing the force

Return type:

numpy.array

class pyswarming.swarm.Swarm(n, linear_speed=0.5, dT=1.0, deployment_point_limits=[[0.0, 0.0, 0.0], [5.0, 5.0, 0.0]], deployment_orientation_limits=[[0.0, 0.0, 0.0], [0.0, 0.0, 6.283185307179586]], distribution_type='uniform', plot_limits=[[-50.0, 50.0], [-50.0, 50.0]], behaviors=['target'])

Creates a Swarm object of n robots, which allows the use of different behaviors algorithms.

Parameters:

• n (int) – integer number of robots, must be greater than 1 (n > 1).

• linear_speed (float) – float number giving the linear speed of each robot. This speed is used for those behaviors that have an orientation or nonsimensional contributions.

• dT (float) – float number giving the sampling time.

• deployment_point_limits (list) – list containing two lists with the swarm deployment coordinate limits, where the first list is the lower limit [x_min, y_min, z_min] and the second is the upper limit [x_max, y_max, z_max]. For the ‘none’ distribution_type only the lower limit is considered; For the ‘uniform’ distribution_type both limits are considered; For the ‘gaussian’ distribution_type the lower limit is considered as the mean of the distribution and the upper limit is considered as the standard deviation of the distribution.

• deployment_orientation_limits (list) – list containing two lists with the swarm deployment orientation limits, where the first list is the lower limit [roll_min, pitch_min, yaw_min] and the second is the upper limit [roll_max, pitch_max, yaw_max]. For the ‘none’ distribution_type only the lower limit is considered; For the ‘uniform’ distribution_type both limits are considered; For the ‘gaussian’ distribution_type the lower limit is considered as the mean of the distribution and the upper limit is considered as the standard deviation of the distribution.

• distribution_type ({'none', 'uniform', 'gaussian'}) – type of distribution used to create the robots. - ‘none’ : the creation is not based in any distribution. - ‘uniform’ : the creation is based in an uniform distribution. - ‘gaussian’ : the creation is based in an gaussian distribution.

• plot_limits (list) – list containing the plot limits (matplotlib).

• behaviors (list) – list containing the behaviors to be simulated.