diff --git a/docs/examples/train_neural_network.rst b/docs/examples/custom_objective_function.rst similarity index 100% rename from docs/examples/train_neural_network.rst rename to docs/examples/custom_objective_function.rst diff --git a/docs/examples/custom_optimization_loop.rst b/docs/examples/custom_optimization_loop.rst index 09d1703a..fea3a029 100644 --- a/docs/examples/custom_optimization_loop.rst +++ b/docs/examples/custom_optimization_loop.rst @@ -23,24 +23,7 @@ class. 2. Operate on it according to our custom algorithm with the help of the ``Topology`` class; and 3. Update the ``Swarm`` class with the new attributes. -.. code:: ipython3 - - import sys - # Change directory to access the pyswarms module - sys.path.append('../') - -.. code:: ipython3 - - print('Running on Python version: {}'.format(sys.version)) - - -.. parsed-literal:: - - Running on Python version: 3.6.3 |Anaconda custom (64-bit)| (default, Oct 13 2017, 12:02:49) - [GCC 7.2.0] - - -.. code:: ipython3 +.. code-block:: python # Import modules import numpy as np @@ -64,7 +47,7 @@ Now, the global best PSO pseudocode looks like the following (adapted from `A. Engelbrecht, "Computational Intelligence: An Introduction, 2002 `__): -.. code:: python +.. code-block:: python # Python-version of gbest algorithm from Engelbrecht's book for i in range(iterations): @@ -90,7 +73,7 @@ Let's make a 2-dimensional swarm with 50 particles that will optimize the sphere function. First, let's initialize the important attributes in our algorithm -.. code:: ipython3 +.. code-block:: python my_topology = Star() # The Topology Class my_options = {'c1': 0.6, 'c2': 0.3, 'w': 0.4} # arbitrarily set @@ -99,14 +82,14 @@ our algorithm print('The following are the attributes of our swarm: {}'.format(my_swarm.__dict__.keys())) -.. parsed-literal:: +.. code:: The following are the attributes of our swarm: dict_keys(['position', 'velocity', 'n_particles', 'dimensions', 'options', 'pbest_pos', 'best_pos', 'pbest_cost', 'best_cost', 'current_cost']) Now, let's write our optimization loop! -.. code:: ipython3 +.. code-block:: python iterations = 100 # Set 100 iterations for i in range(iterations): @@ -133,7 +116,7 @@ Now, let's write our optimization loop! print('The best position found by our swarm is: {}'.format(my_swarm.best_pos)) -.. parsed-literal:: +.. code:: Iteration: 1 | my_swarm.best_cost: 0.0180 Iteration: 21 | my_swarm.best_cost: 0.0023 @@ -147,7 +130,7 @@ Now, let's write our optimization loop! Of course, we can just use the ``GlobalBestPSO`` implementation in PySwarms (it has boundary support, tolerance, initial positions, etc.): -.. code:: ipython3 +.. code-block:: python from pyswarms.single import GlobalBestPSO @@ -155,7 +138,7 @@ PySwarms (it has boundary support, tolerance, initial positions, etc.): optimizer.optimize(f, iters=100, print_step=20, verbose=2) -.. parsed-literal:: +.. code:: INFO:pyswarms.single.global_best:Iteration 1/100, cost: 0.025649680624878678 INFO:pyswarms.single.global_best:Iteration 21/100, cost: 0.00011046719760866999 @@ -167,12 +150,3 @@ PySwarms (it has boundary support, tolerance, initial positions, etc.): Final cost: 0.0001 Best value: [0.007417861777661566, 0.004421058167808941] - - - - -.. parsed-literal:: - - (7.457042867564255e-05, array([0.00741786, 0.00442106])) - - diff --git a/docs/examples/inverse_kinematics.rst b/docs/examples/inverse_kinematics.rst index f5bea9dc..0dc6f95a 100644 --- a/docs/examples/inverse_kinematics.rst +++ b/docs/examples/inverse_kinematics.rst @@ -6,23 +6,7 @@ In this example, we are going to use the ``pyswarms`` library to solve a it as an optimization problem. We will use the ``pyswarms`` library to find an *optimal* solution from a set of candidate solutions. -.. code:: python - - import sys - # Change directory to access the pyswarms module - sys.path.append('../') - -.. code:: python - - print('Running on Python version: {}'.format(sys.version)) - - -.. parsed-literal:: - - Running on Python version: 3.6.0 (v3.6.0:41df79263a11, Dec 23 2016, 07:18:10) [MSC v.1900 32 bit (Intel)] - - -.. code:: python +.. code-block:: python # Import modules import numpy as np @@ -35,26 +19,8 @@ find an *optimal* solution from a set of candidate solutions. %load_ext autoreload %autoreload 2 -.. code:: python - - %%html - - # Styling for the text below - - - -.. raw:: html - - - # Styling for the text below - - Introduction -============ +------------ Inverse Kinematics is one of the most challenging problems in robotics. The problem involves finding an optimal *pose* for a manipulator given @@ -77,7 +43,7 @@ trying to solve the problem for 6 or even more DOF can lead to challenging algebraic problems. IK as an Optimization Problem -============================= +----------------------------- In this implementation, we are going to use a *6-DOF Stanford Manipulator* with 5 revolute joints and 1 prismatic joint. Furthermore, @@ -117,7 +83,7 @@ And for our end-tip position we define the target vector We can then start implementing our optimization algorithm. Initializing the Swarm -====================== +~~~~~~~~~~~~~~~~~~~~~~ The main idea for PSO is that we set a swarm :math:`\mathbf{S}` composed of particles :math:`\mathbf{P}_n` into a search space in order to find @@ -147,7 +113,7 @@ generate the :math:`N-1` particles using a uniform distribution which is controlled by the hyperparameter :math:`\epsilon`. Finding the global optimum -========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to find the global optimum, the swarm must be moved. This movement is then translated by an update of the current position given @@ -174,7 +140,7 @@ point :math:`[-2,2,3]` as our target for which we want to find an optimal pose of the manipulator. We start by defining a function to get the distance from the current position to the target position: -.. code:: python +.. code-block:: python def distance(query, target): x_dist = (target[0] - query[0])**2 @@ -194,7 +160,7 @@ values and a list of the respective maximal values. The rest can be handled with variables. Additionally, we define the joint lengths to be 3 units long: -.. code:: python +.. code-block:: python swarm_size = 20 dim = 6 # Dimension of X @@ -214,7 +180,7 @@ for that. So we define a function that calculates these. The function uses the rotation angle and the extension :math:`d` of a prismatic joint as input: -.. code:: python +.. code-block:: python def getTransformMatrix(theta, d, a, alpha): T = np.array([[np.cos(theta) , -np.sin(theta)*np.cos(alpha) , np.sin(theta)*np.sin(alpha) , a*np.cos(theta)], @@ -228,7 +194,7 @@ Now we can calculate the transformation matrix to obtain the end tip position. For this we create another function that takes our vector :math:`\mathbf{X}` with the joint variables as input: -.. code:: python +.. code-block:: python def get_end_tip_position(params): # Create the transformation matrices for the respective joints @@ -252,7 +218,7 @@ actual function that we want to optimize. We just need to calculate the distance between the position of each swarm particle and the target point: -.. code:: python +.. code-block:: python def opt_func(X): n_particles = X.shape[0] # number of particles @@ -265,7 +231,7 @@ Running the algorithm Braced with these preparations we can finally start using the algorithm: -.. code:: python +.. code-block:: python %%time # Call an instance of PSO @@ -295,13 +261,6 @@ Braced with these preparations we can finally start using the algorithm: Final cost: 0.0000 Best value: [ -2.182725 1.323111 1.579636 ...] - - -.. parsed-literal:: - - Wall time: 13.6 s - - Now let’s see if the algorithm really worked and test the output for ``joint_vars``: @@ -314,7 +273,6 @@ Now let’s see if the algorithm really worked and test the output for [-2. 2. 3.] - Hooray! That’s exactly the position we wanted the tip to be in. Of course this example is quite primitive. Some extensions of this idea could involve the consideration of the current position of the diff --git a/docs/examples/tutorials.rst b/docs/examples/tutorials.rst new file mode 100644 index 00000000..42fd5095 --- /dev/null +++ b/docs/examples/tutorials.rst @@ -0,0 +1,11 @@ +Tutorials +========= +Below are some examples describing how the PySwarms API works. +If you wish to check the actual Jupyter Notebooks, please go to this `link `_ + +.. toctree:: + + basic_optimization + custom_objective_function + custom_optimization_loop + visualization diff --git a/docs/examples/usecases.rst b/docs/examples/usecases.rst index 3a5a16bb..325fecf3 100644 --- a/docs/examples/usecases.rst +++ b/docs/examples/usecases.rst @@ -1,12 +1,9 @@ -Use-case examples -================= -Below are some of the applications where PySwarms can be used. +Use-cases +========= +Below are some examples on how to use PSO in different applications. If you wish to check the actual Jupyter Notebooks, please go to this `link `_ .. toctree:: - basic_optimization - train_neural_network - custom_optimization_loop feature_subset_selection - visualization \ No newline at end of file + inverse_kinematics diff --git a/docs/examples/visualization.rst b/docs/examples/visualization.rst index a43c11af..7e5ec401 100644 --- a/docs/examples/visualization.rst +++ b/docs/examples/visualization.rst @@ -16,29 +16,13 @@ and Windows users, it can be installed via: $ conda install -c conda-forge ffmpeg -.. code:: ipython3 - - import sys - # Change directory to access the pyswarms module - sys.path.append('../') - -.. code:: ipython3 - - print('Running on Python version: {}'.format(sys.version)) - - -.. code:: shell - - Running on Python version: 3.6.3 |Anaconda custom (64-bit)| (default, Oct 13 2017, 12:02:49) [GCC 7.2.0] - - In this example, we will demonstrate three plotting methods available on PySwarms: - ``plot_cost_history``: for plotting the cost history of a swarm given a matrix - ``plot_contour``: for plotting swarm trajectories of a 2D-swarm in two-dimensional space - ``plot_surface``: for plotting swarm trajectories of a 2D-swarm in three-dimensional space -.. code:: ipython3 +.. code-block:: python # Import modules import matplotlib.pyplot as plt @@ -62,14 +46,14 @@ simply create an instance of its class ``pyswarms.single.GlobalBestPSO`` by passing the required parameters that we will use. Then, we'll call the ``optimize()`` method for 100 iterations. -.. code:: ipython3 +.. code-block:: python options = {'c1':0.5, 'c2':0.3, 'w':0.9} optimizer = ps.single.GlobalBestPSO(n_particles=50, dimensions=2, options=options) cost, pos = optimizer.optimize(fx.sphere_func, iters=100) -.. parsed-literal:: +.. code-block:: INFO:pyswarms.single.global_best:================================ Optimization finished! @@ -86,12 +70,12 @@ To plot the cost history, we simply obtain the ``cost_history`` from the Furthermore, this method also accepts a keyword argument ``**kwargs`` similar to ``matplotlib``. This enables us to further customize various artists and elements in the plot. In addition, we can obtain the -following histories from the same class: - mean\_neighbor\_history: -average local best history of all neighbors throughout optimization - -mean\_pbest\_history: average personal best of the particles throughout -optimization +following histories from the same class: + + * mean\_neighbor\_history: average local best history of all neighbors throughout optimization + * mean\_pbest\_history: average personal best of the particles throughout optimization -.. code:: ipython3 +.. code-block:: python plot_cost_history(cost_history=optimizer.cost_history) plt.show() @@ -112,7 +96,7 @@ necessitating the installation of a writer module). For the proceeding examples, we will convert the animations into an HTML5 video. In such case, we need to invoke some extra methods to do just that. -.. code:: ipython3 +.. code-block:: python # equivalent to rcParams['animation.html'] = 'html5' # See http://louistiao.me/posts/notebooks/save-matplotlib-animations-as-gifs/ @@ -123,12 +107,10 @@ function. This enables us to visually recognize where the particles are with respect to our objective function. We can accomplish that using the ``Mesher`` class. -.. code:: ipython3 +.. code-block:: python from pyswarms.utils.plotters.formatters import Mesher -.. code:: ipython3 - # Initialize mesher with sphere function m = Mesher(func=fx.sphere_func) @@ -147,7 +129,7 @@ pass this together with the ``Mesher`` to the ``plot_contour()`` function. In addition, we can also mark the global minima of the sphere function, ``(0,0)``, to visualize the swarm's "target". -.. code:: ipython3 +.. code-block:: python # Make animation animation = plot_contour(pos_history=optimizer.pos_history, @@ -169,20 +151,16 @@ position of the particles, while the third column is the fitness of that given position. You need to set this up on your own, but we have provided a helper function to compute this automatically -.. code:: ipython3 +.. code-block:: python # Obtain a position-fitness matrix using the Mesher.compute_history_3d() # method. It requires a cost history obtainable from the optimizer class pos_history_3d = m.compute_history_3d(optimizer.pos_history) -.. code:: ipython3 - # Make a designer and set the x,y,z limits to (-1,1), (-1,1) and (-0.1,1) respectively from pyswarms.utils.plotters.formatters import Designer d = Designer(limits=[(-1,1), (-1,1), (-0.1,1)], label=['x-axis', 'y-axis', 'z-axis']) -.. code:: ipython3 - # Make animation animation3d = plot_surface(pos_history=pos_history_3d, # Use the cost_history we computed mesher=m, designer=d, # Customizations @@ -191,4 +169,4 @@ provided a helper function to compute this automatically # Enables us to view it in a Jupyter notebook HTML(animation3d.to_html5_video()) -.. image:: https://i.imgur.com/IhbKTIE.gif \ No newline at end of file +.. image:: https://i.imgur.com/IhbKTIE.gif diff --git a/docs/index.rst b/docs/index.rst index 0ec0adf9..c542f96a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -85,6 +85,7 @@ Launching pad :maxdepth: 2 :caption: Examples + Tutorials Use-cases .. toctree::