Skip to content

Commit

Permalink
Update docs and swarm.py
Browse files Browse the repository at this point in the history
  • Loading branch information
@mrsonandrade
mrsonandrade committed Jul 24, 2023
1 parent e7b1920 commit 2a733c6
Show file tree
Hide file tree
Showing 11 changed files with 180 additions and 211 deletions.
35 changes: 35 additions & 0 deletions .readthedocs.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.8"
# You can also specify other tool versions:
# nodejs: "20"
# rust: "1.70"
# golang: "1.20"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/source/conf.py
# You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
# builder: "dirhtml"
# Fail on all warnings to avoid broken references
# fail_on_warning: true

# Optionally build your docs in additional formats such as PDF and ePub
# formats:
# - pdf
# - epub

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- requirements: docs/requirements.txt
Binary file added docs/readme_pics/RepulsionLowCode.gif
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 5 additions & 13 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,28 +16,21 @@
sys.path.insert(0, os.path.abspath("../.."))

autodoc_mock_imports = [
"numpy",
"matplotlib",
]

master_doc = "index"

# -- Project information -----------------------------------------------------

project = "pyswarming"
copyright = "2023, pyswarming developers"
author = "pyswarming developers"

# The full version, including alpha/beta/rc tags
release = "1.1.1"

project = "PySwarming"

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"sphinx_rtd_theme",
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
Expand All @@ -62,7 +55,6 @@
# html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
autodoc_default_options = {
'special-members': '__init__',
}
5 changes: 4 additions & 1 deletion docs/source/example_notebooks/01_Getting_Started.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,10 @@
" distribution_type = 'uniform', # type of distribution used to deploy the robots\n",
" plot_limits = [[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim\n",
" behaviors = ['repulsion']) # list of behaviors\n",
"my_swarm.simulate()"
"anim = my_swarm.simulate(mode='simulate')\n",
"\n",
"from IPython.display import HTML\n",
"HTML(anim.to_jshtml())"
]
},
{
Expand Down
20 changes: 16 additions & 4 deletions docs/source/example_notebooks/02_Simple_Examples.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,10 @@
" plot_limits = [[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim\n",
" behaviors = ['target']) # list of behaviors\n",
"my_swarm.behaviors_dict['r_out']['target']['T'] = [-40, -40, 0] # setting the target position [x, y, z]\n",
"my_swarm.simulate()"
"anim = my_swarm.simulate(mode='simulate')\n",
"\n",
"from IPython.display import HTML\n",
"HTML(anim.to_jshtml())"
]
},
{
Expand Down Expand Up @@ -70,7 +73,10 @@
" distribution_type = 'uniform', # type of distribution used to deploy the robots\n",
" plot_limits = [[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim\n",
" behaviors = ['aggregation']) # list of behaviors\n",
"my_swarm.simulate()"
"anim = my_swarm.simulate(mode='simulate')\n",
"\n",
"from IPython.display import HTML\n",
"HTML(anim.to_jshtml())"
]
},
{
Expand Down Expand Up @@ -102,7 +108,10 @@
" distribution_type = 'uniform', # type of distribution used to deploy the robots\n",
" plot_limits = [[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim\n",
" behaviors = ['repulsion']) # list of behaviors\n",
"my_swarm.simulate()"
"anim = my_swarm.simulate(mode='simulate')\n",
"\n",
"from IPython.display import HTML\n",
"HTML(anim.to_jshtml())"
]
},
{
Expand Down Expand Up @@ -135,7 +144,10 @@
" plot_limits = [[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim\n",
" behaviors = ['aggregation', 'repulsion', 'target']) # list of behaviors\n",
"my_swarm.behaviors_dict['r_out']['target']['T'] = [-20, -20, 0] # setting the target position [x, y, z]\n",
"my_swarm.simulate()"
"anim = my_swarm.simulate(mode='simulate')\n",
"\n",
"from IPython.display import HTML\n",
"HTML(anim.to_jshtml())"
]
}
],
Expand Down
219 changes: 81 additions & 138 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,6 @@ Introduction

``pyswarming`` is a research toolkit for Swarm Robotics.

The package is currently maintained by `@mrsonandrade <http://github.com/mrsonandrade>`_.

https://github.com/mrsonandrade/pyswarming

Install
Expand Down Expand Up @@ -63,7 +61,8 @@ This library includes the following algorithms to be used in swarm robotics:
* **Collective navigation**: using the Target and Repulsion algorithms [11]_;
* **Flocking**: using the Aggregation, Repulsion and Alignment algorithms [11]_;

.. rubric:: References
References
==========

.. [1] T. Vicsek, A. Czirók, E. Ben-Jacob, I. Cohen, and O. Shochet, “Novel Type of Phase Transition in a System of Self-Driven Particles,” Phys. Rev. Lett., vol. 75, no. 6, pp. 1226–1229, Aug. 1995. https://doi.org/10.1103/PhysRevLett.75.1226.
Expand All @@ -88,157 +87,101 @@ This library includes the following algorithms to be used in swarm robotics:
.. [11] B. M. Zoss et al., “Distributed system of autonomous buoys for scalable deployment and monitoring of large waterbodies,” Auton. Robots, vol. 42, no. 8, pp. 1669–1689, Dec. 2018. https://doi.org/10.1007/s10514-018-9702-0.
Examples using pyswarming.swarm
========
::
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 <https://github.com/mrsonandrade/pyswarming/tree/main/examples>`_ or the `notebooks <https://github.com/mrsonandrade/pyswarming/tree/main/notebooks>`_ folder.
::
# importing the swarm creator
import pyswarming.swarm as sw

Repulsion
------
::
my_swarm = sw.Swarm(10, # number of robots
0.5, # linear speed of each robot
1.0, # sampling time
[0.0, 0.0], # robots deployed randomly around x = 0.0, y = 0.0 (+- 5.0 meters)
[[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim
['repulsion']) # list of behaviors
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
my_swarm.simulate()

Collective navigation
------
::
my_swarm = sw.Swarm(10, # number of robots
0.5, # linear speed of each robot
1.0, # sampling time
[0.0, 0.0], # robots deployed randomly around x = 0.0, y = 0.0 (+- 5.0 meters)
[[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim
['repulsion']) # list of behaviors
my_swarm.behaviors_dict['r_out']['collective_navigation']['alpha'] = 2.0 # setting the strength of the repulsion
my_swarm.behaviors_dict['r_out']['collective_navigation']['T'] = np.array([-40, -40, 0]) # setting the target
my_swarm.simulate()
.. image:: ../readme_pics/RepulsionLowCode.gif

Target + Aggregation
------
Respulsion (without low-code)
----------------------------
Considering a swarm of robots, they can show different behaviors by using ``pyswarming``, for details, see the `examples <https://github.com/mrsonandrade/pyswarming/tree/main/examples>`_ or the `notebooks <https://github.com/mrsonandrade/pyswarming/tree/main/notebooks>`_ folder.
::
my_swarm = sw.Swarm(10, # number of robots
0.5, # linear speed of each robot
1.0, # sampling time
[0.0, 0.0], # robots deployed randomly around x = 0.0, y = 0.0 (+- 5.0 meters)
[[-50.0, 50.0], [-50.0, 50.0]], # plot limits x_lim, y_lim
['target','aggregation']) # list of behaviors
my_swarm.behaviors_dict['r_out']['target']['T'] = np.array([-40, -40, 0]) # setting the target
my_swarm.simulate()

Other Examples
========
Considering a swarm of robots, they can show different behaviors by using ``pyswarming``. The following codes are simplified implementations, for detailed ones, see the `Examples <https://github.com/mrsonandrade/pyswarming/tree/main/Examples>`_ folder.::
# importing pyswarming behaviors
import pyswarming.behaviors as pb

import pyswarming.behaviors as ps
# importing numpy to work with arrays
import numpy as np

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

# define the robot (x, y, z) position
r_i = np.asarray([0., 0., 0.])

# set the robot linear velocity
s_i = 1.0

# define a target (x, y, z) position
T = np.asarray([8., 8., 0.])

for t in range(15):

# print the robot (x, y, z) position
print(r_i)

# update the robot (x, y, z) position
r_i += s_i*ps.target(r_i, T)


.. image:: ../readme_pics/Target.gif
:alt: target

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

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

# set the robot linear velocity
s_i = 1.0

for t in range(15):

# print the robot (x, y, z) positions
print(r)

# update the robot (x, y, z) positions
for r_ind in range(len(r)):
r_i = r[r_ind]
r_j = np.delete(r, np.array([r_ind]), axis=0)
r[r_ind] += s_i*ps.aggregation(r_i, r_j)

.. image:: ../readme_pics/Aggregation.gif

Repulsion
---------
::

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

# set the robot linear velocity
s_i = 1.0

for t in range(15):

# print the robot (x, y, z) positions
print(r)

# update the robot (x, y, z) positions
for r_ind in range(len(r)):
r_i = r[r_ind]
r_j = np.delete(r, np.array([r_ind]), axis=0)
r[r_ind] += s_i*ps.repulsion(r_i, r_j, 3.0)
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_xlim([-10,10])
ax.set_ylim([-10,10])
ax.set_xlabel('X(m)')
ax.set_ylabel('Y(m)')
ax.grid()
ax.set_aspect('equal')
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)

anim
plt.show()

.. image:: ../readme_pics/Repulsion.gif

Aggregation + Repulsion
-----------------------
::

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

# set the robot linear velocity
s_i = 1.0

for t in range(15):

# print the robot (x, y, z) positions
print(r)

# update the robot (x, y, z) positions
for r_ind in range(len(r)):
r_i = r[r_ind]
r_j = np.delete(r, np.array([r_ind]), axis=0)
r[r_ind] += s_i*(ps.aggregation(r_i, r_j) + ps.repulsion(r_i, r_j, 5.0))

.. image:: ../readme_pics/AggregationRepulsion.gif



Expand Down

0 comments on commit 2a733c6

Please sign in to comment.