docs/source/example_notebooks/01_Getting_Started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started\n",
    "\n",
    "Depending on your knowledge of Python and swarm behaviors, you can take two approaches to using PySwarming:\n",
    "\n",
    "1. **Simple and low-code simulations**: start using the PySwarming.Swarm class, which allows the creation of virtual swarms to be used with\n",
    "some behaviors functions.\n",
    "2. **Custom animated simulations**: here you are able to use all the available behaviors, however, you will need to code a little bit more, i.e., the creation of the swarm, the animation, and so on.\n",
    "\n",
    "Below you have examples of each approach mentioned above. For more examples, you can see the [notebooks](https://github.com/mrsonandrade/pyswarming/tree/main/notebooks) and [examples](https://github.com/mrsonandrade/pyswarming/tree/main/examples) directories of PySwarming.\n",
    "\n",
    "## (Approach 1) Low-code: PySwarming.Swarm\n",
    "\n",
    "**Non-Beginners**: If you're already familiar with Python and swarm behaviors, you can see a more customized example [here](#approach-2-gentler-introduction-to-custom-animations).\n",
    "\n",
    "### Simulating repulsion behavior among the swarm\n",
    "The idea of this simulation is to use the low-code tool from PySwarming, which enables us to carry out simplified animations with some behaviors.\n",
    "\n",
    "Firstly, we need to set some parameters to create our swarm, such as the number of robots, the linear speed of the robots, and so on.\n",
    "After that, we simply call `simulate()`.\n",
    "\n",
    "For details, see the code below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "051ef3c4",
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "# importing the swarm creator\n",
    "import pyswarming.swarm as ps\n",
    "\n",
    "# creating the swarm\n",
    "my_swarm = ps.Swarm(n = 10, # number of robots\n",
    "                    linear_speed = 0.5, # linear speed of each robot\n",
    "                    dT = 1.0, # sampling time\n",
    "                    deployment_point_limits = [[0.0, 0.0, 0.0], [5.0, 5.0, 0.0]], # lower and upper limits for the position deployment\n",
    "                    deployment_orientation_limits = [[0.0, 0.0, 0.0], [0.0, 0.0, 2*3.1415]], # lower and upper limits for the orientation deployment\n",
    "                    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",
    "anim = my_swarm.simulate(mode='anim')\n",
    "\n",
    "from IPython.display import HTML\n",
    "HTML(anim.to_jshtml())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d96ce01d",
   "metadata": {},
   "source": [
    "## (Approach 2) Custom Animations\n",
    "\n",
    "### Simulating repulsion behavior among the swarm\n",
    "The idea of this simulation is to use a more complicated setup with a little more knowledge of Python, Robotics, and PySwarming. In this setup, we need to define the initial pose of the robots, their linear speed, the animation functions, and so on. This enables us to carry out even more customized animations/simulations of the swarm.\n",
    "\n",
    "For details, see the code below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7adbfb3a",
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "# importing pyswarming behaviors\n",
    "import pyswarming.behaviors as ps\n",
    "\n",
    "# importing numpy to work with arrays\n",
    "import numpy as np\n",
    "\n",
    "# importing matplotlib to plot the animation\n",
    "import matplotlib.pyplot as plt\n",
    "import matplotlib.animation as animation\n",
    "\n",
    "# importing functools.partial to use in the animation\n",
    "from functools import partial\n",
    "\n",
    "# define each robot (x, y, z) position\n",
    "robot_poses = np.asarray([[1., 1., 0.],\n",
    "                          [-1., 1., 0.],\n",
    "                          [1., -1., 0.],\n",
    "                          [-1., -1., 0.]])\n",
    "\n",
    "# set the robot linear velocity\n",
    "robot_speed = 0.025\n",
    "\n",
    "# First set up the figure, the axis, and the plot element we want to animate\n",
    "fig, ax = plt.subplots()\n",
    "\n",
    "ax.set_xlim([-10,10])\n",
    "ax.set_ylim([-10,10])\n",
    "ax.set_xlabel('X(m)')\n",
    "ax.set_ylabel('Y(m)')\n",
    "ax.grid()\n",
    "ax.set_aspect('equal')\n",
    "ax.set_title('Repulsion behavior')\n",
    "\n",
    "robot1, = ax.plot([], [], marker='o', lw=0)\n",
    "robot2, = ax.plot([], [], marker='o', lw=0)\n",
    "robot3, = ax.plot([], [], marker='o', lw=0)\n",
    "robot4, = ax.plot([], [], marker='o', lw=0)\n",
    "\n",
    "# initialization function: plot the background of each frame\n",
    "def init():\n",
    "    robot1.set_data([], [])\n",
    "    robot2.set_data([], [])\n",
    "    robot3.set_data([], [])\n",
    "    robot4.set_data([], [])\n",
    "    return (robot1,robot2,robot3,robot4,)\n",
    "\n",
    "# animation function. This is called sequentially\n",
    "def animate(i, robot_poses):\n",
    "    for r_ind in range(len(robot_poses)):\n",
    "        r_i = robot_poses[r_ind]\n",
    "        r_j = np.delete(robot_poses, np.array([r_ind]), axis=0)\n",
    "        robot_poses[r_ind] += robot_speed*ps.repulsion(r_i, r_j, 5.0)\n",
    "    robot1.set_data(robot_poses[0][0], robot_poses[0][1])\n",
    "    robot2.set_data(robot_poses[1][0], robot_poses[1][1])\n",
    "    robot3.set_data(robot_poses[2][0], robot_poses[2][1])\n",
    "    robot4.set_data(robot_poses[3][0], robot_poses[3][1])\n",
    "    return (robot1,robot2,robot3,robot4,)\n",
    "\n",
    "# call the animator. blit=True means only re-draw the parts that \n",
    "# have changed.\n",
    "anim = animation.FuncAnimation(fig, partial(animate, robot_poses=robot_poses), init_func=init,\n",
    "                               frames=480, interval=1, blit=True)\n",
    "\n",
    "anim\n",
    "\n",
    "from IPython.display import HTML\n",
    "HTML(anim.to_jshtml())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f17d538b",
   "metadata": {},
   "source": [
    "Again, for more examples, you can see the [notebooks](https://github.com/mrsonandrade/pyswarming/tree/main/notebooks) and [examples](https://github.com/mrsonandrade/pyswarming/tree/main/examples) directories of PySwarming."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.0 64-bit",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.0"
  },
  "vscode": {
   "interpreter": {
    "hash": "7e1998ff7f8aa20ada591c520b972326324e5ea05489af9e422744c7c09f6dad"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}