Welcome to pyswarming’s documentation!



pyswarming is a research toolkit for Swarm Robotics.



You can install pyswarming from PyPI using pip (Recommended):

pip install pyswarming


pyswarming’s dependencies are: numpy, numdifftools and matplotlib.

Algorithms covered

This library includes the following algorithms to be used in swarm robotics:

  • Leaderless heading consensus: the collective performs heading consensus [1];

  • Inverse power: ajustable attraction and repulsion laws [2];

  • Spring: allows the robots to maintain a desired distance between them [2];

  • Force law: mimics the gravitational force [3];

  • Repulsive force: makes the individuals repulse each other [4];

  • Body force: introduces a body force that considers the radii of the robots [4];

  • Inter robot spacing: allows the robots to maintain a desired distance between them [5];

  • Dissipative: a dissipative force that reduces the “energy” of the robots [5];

  • Leader following: the collective performs heading consensus with a leader [6];

  • Collision avoidance: the robot stays away from neighbors in the vicinity [7];

  • Attraction alignment: the robot becomes attracted and aligned [7];

  • Preferred direction: the robot has a preference to move toward a preset direction [7];

  • Lennard-Jones: allows the formation of lattices [8];

  • Virtual viscosity: a viscous force that reduces the “oscillation” of the robots [8];

  • Modified attraction alignment: the robot becomes attracted and aligned by considering a “social importance” factor [9];

  • Heading consensus: the collective performs heading consensus [10];

  • Perimeter defense: the robots maximize the perimeter covered in an unknown environment [10];

  • Environment exploration: provides spatial coverage [10];

  • Aggregation: makes all the individuals aggregate collectively [11];

  • Alignment: the collective performs heading consensus [11];

  • Geofencing: attract the robots towards area A [11];

  • Repulsion: makes all the individuals repulse collectively [11];

  • Target: the robot goes to an specific target location [11];

  • Area coverage: using the Geofencing and Repulsion algorithms [11];

  • Collective navigation: using the Target and Repulsion algorithms [11];

  • Flocking: using the Aggregation, Repulsion and Alignment algorithms [11];


Examples using pyswarming.swarm

Repulsion (low-code)

For this example we will use a low-code approach, i.e., pyswarming.swarm, for details, see the examples or the notebooks folder.

# importing the swarm creator
import pyswarming.swarm as ps

# creating the swarm
my_swarm = ps.Swarm(n = 10, # number of robots
                    linear_speed = 0.5, # linear speed of each robot
                    dT = 1.0, # sampling time
                    deployment_point_limits = [[0.0, 0.0, 0.0], [5.0, 5.0, 0.0]], # lower and upper limits for the position deployment
                    deployment_orientation_limits = [[0.0, 0.0, 0.0], [0.0, 0.0, 2*3.1415]], # lower and upper limits for the orientation deployment
                    distribution_type =  'uniform', # type of distribution used to deploy the robots
                    plot_limits = [[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim
                    behaviors = ['repulsion']) # list of behaviors

Respulsion (without low-code)

Considering a swarm of robots, they can show different behaviors by using pyswarming, for details, see the examples or the notebooks folder.

# importing pyswarming behaviors
import pyswarming.behaviors as pb

# importing numpy to work with arrays
import numpy as np

# importing matplotlib to plot the animation
import matplotlib.pyplot as plt
import matplotlib.animation as animation

# importing functools.partial to use in the animation
from functools import partial

# define each robot (x, y, z) position
robot_poses = np.asarray([[1., 1., 0.],
                        [-1., 1., 0.],
                        [1., -1., 0.],
                        [-1., -1., 0.]])

# set the robot linear velocity
robot_speed = 0.025

# First set up the figure, the axis, and the plot element we want to animate
fig, ax = plt.subplots()

ax.set_title('Repulsion behavior')

robot1, = ax.plot([], [], marker='o', lw=0)
robot2, = ax.plot([], [], marker='o', lw=0)
robot3, = ax.plot([], [], marker='o', lw=0)
robot4, = ax.plot([], [], marker='o', lw=0)

# initialization function: plot the background of each frame
def init():
   robot1.set_data([], [])
   robot2.set_data([], [])
   robot3.set_data([], [])
   robot4.set_data([], [])
   return (robot1,robot2,robot3,robot4,)

# animation function. This is called sequentially
def animate(i, robot_poses):
   for r_ind in range(len(robot_poses)):
      r_i = robot_poses[r_ind]
      r_j = np.delete(robot_poses, np.array([r_ind]), axis=0)
      robot_poses[r_ind] += robot_speed*pb.repulsion(r_i, r_j, 5.0)
   robot1.set_data(robot_poses[0][0], robot_poses[0][1])
   robot2.set_data(robot_poses[1][0], robot_poses[1][1])
   robot3.set_data(robot_poses[2][0], robot_poses[2][1])
   robot4.set_data(robot_poses[3][0], robot_poses[3][1])
   return (robot1,robot2,robot3,robot4,)

# call the animator. blit=True means only re-draw the parts that
# have changed.
anim = animation.FuncAnimation(fig, partial(animate, robot_poses=robot_poses), init_func=init,
                              frames=480, interval=1, blit=True)