K-means application / PySke examples documentation

docs/api.rst

@@ -1,2 +1,161 @@
 PySke API
-=========
+#########
+
+PySke API offer applications implemented with list and tree skeletons.
+The user can use the sequential or parallel version.
+The parallel version allows a faster execution time when its launched on several processors, cores or computers.
+
+Run examples with parallel computing:
+
+    .. code-block:: console
+
+        mpirun -np NB_CORES python3 PROGRAM_NAME [OPTIONS]
+
+Examples without :code:`--data` option are only runnable in parallel.
+
+List Examples
+=============
+
+Dot Product
+-----------
+
+.. py:module:: pyske.examples.list.dot_product
+
+
+Dot Product functions
+^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: opt_dot_product
+
+.. autofunction:: dot_product
+
+Running Example
+^^^^^^^^^^^^^^^
+
+.. autoprogram:: pyske.examples.list.util:dot_product_parser()
+    :prog: dot_product_main.py
+
+
+Discrete Fast Fourier Transform
+-------------------------------
+.. py:module:: pyske.examples.list.fft
+
+Fast Fourier Transform function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: fft
+
+Running Example
+^^^^^^^^^^^^^^^
+
+.. autoprogram:: pyske.examples.list.util:standard_parser(data_arg=False)
+    :prog: fft_main.py
+
+
+K-means Clustering
+------------------
+
+K-means clustering is an unsupervised algorithm that aims to partition group of points in k clusters.
+
+K-means function
+^^^^^^^^^^^^^^^^
+
+.. py:module:: pyske.examples.list.k_means
+
+.. autofunction:: k_means
+
+Initialization functions
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the standard method that initializes the centroids. This method chooses the centroids in order that each point is as far as possible from the other.
+
+.. autofunction:: k_means_init
+
+
+Point Interface
+^^^^^^^^^^^^^^^
+
+K-means algorithm takes a list of points in parameters. For now two versions implement this class, one for 2 dimension points and another for 3 dimension points.
+
+Point 2D class implementation:
+
+.. autoclass:: pyske.core.util.point_2D.Point_2D
+    :members:
+    :special-members:
+    :member-order: bysource
+
+Running Example
+^^^^^^^^^^^^^^^
+
+.. autoprogram:: pyske.examples.list.util:k_means_parser()
+    :prog: k_means_main.py
+
+
+Maximum Prefix Sum
+------------------
+
+.. py:module:: pyske.examples.list.maximum_prefix_sum
+
+Maximum Prefix Sum function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: mps
+
+Running Example
+^^^^^^^^^^^^^^^
+
+.. autoprogram:: pyske.examples.list.util:standard_parser()
+    :prog: maximum_prefix_sum_main.py
+
+Maximum Segment Sum
+-------------------
+
+Running Example
+^^^^^^^^^^^^^^^
+
+.. autoprogram:: pyske.examples.list.util:standard_parser()
+    :prog: maximum_segment_sum_main.py
+
+Parallel Regular Sampling Sort
+------------------------------
+
+.. py:module:: pyske.examples.list.regular_sampling_sort
+
+
+Broadcast function
+^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: bcast
+
+Sort function
+^^^^^^^^^^^^^
+
+.. autofunction:: pssr
+
+
+Running Example
+^^^^^^^^^^^^^^^
+
+.. autoprogram:: pyske.examples.list.util:standard_parser()
+    :prog: regular_sampling_sort_main.py
+
+Variance Example
+----------------
+
+.. py:module:: pyske.examples.list.variance
+
+Variance function
+^^^^^^^^^^^^^^^^^
+
+.. autofunction:: variance
+
+Running Example
+^^^^^^^^^^^^^^^
+
+.. autoprogram:: pyske.examples.list.util:standard_parser()
+    :prog: variance_main.py
+
+
+Tree Examples
+=============
+

docs/conf.py

@@ -10,9 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
 
 
 # -- Project information -----------------------------------------------------
@@ -31,6 +31,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.autodoc",
+    "sphinxcontrib.autoprogram"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -52,4 +54,4 @@
 # 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']
+html_static_path = ['_static']

docs/index.rst

@@ -7,7 +7,7 @@ Welcome to PySke's documentation!
 =================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    intro

pyske/core/util/point_2D.py

@@ -0,0 +1,91 @@
+"""
+A module to represent a 2D point
+"""
+
+from math import sqrt
+from pyske.core.util.point_Interface import Point_Interface
+
+
+class Point_2D(Point_Interface):
+    """A class to represent a 2D point"""
+
+    def __init__(self, x=0, y=0):
+        self.__x = x
+        self.__y = y
+
+    def __repr__(self):
+        return "(%s, %s)" % (self.__x, self.__y)
+
+    def __eq__(self, other):
+        """
+        Equality between two points
+        """
+        if isinstance(other, Point_2D):
+            return self.__x == other.__x and self.__y == other.__y
+        return False
+
+    def __add__(self, other):
+        """
+        Addition of two points
+
+        Examples::
+
+            >>> p1 = Point_2D(5,5)
+            >>> p2 = Point_2D(5,7)
+            >>> p1 + p2
+            (10, 12)
+        """
+        if isinstance(other, Point_2D):
+            return Point_2D(self.x + other.x, self.y + other.y)
+
+    def __mul__(self, other):
+        """
+        Multiplication by a point or a scalar
+
+        Examples::
+
+            >>> p1 = Point_2D(5,5)
+            >>> p2 = Point_2D(5,7)
+            >>> p1 * 5
+            (25, 25)
+            >>> p1 * p2
+            (25, 35)
+        """
+        if isinstance(other, Point_2D):
+            return Point_2D(self.x * other.x, self.y * other.y)
+        if isinstance(other, int) or isinstance(other, float):
+            return Point_2D(self.x * other, self.y * other)
+
+    def __truediv__(self, other):
+        if isinstance(other, int):
+            return Point_2D(self.x / other, self.y / other)
+
+    @property
+    def x(self):
+        """X getter"""
+        return self.__x
+
+    @property
+    def y(self):
+        """Y getter"""
+        return self.__y
+
+    def distance(self, other: 'Point_2D'):
+        """
+        Returns the distance from another point.
+
+        Examples::
+
+            >>> from pyske.core.util.point_2D import Point_2D
+            >>> p1 = Point_2D(5,5)
+            >>> p2 = Point_2D(5,7)
+            >>> p1.distance(p2)
+            2.0
+
+        :param other: a point
+        :return: distance from other point
+
+        """
+        dx = self.__x - other.x
+        dy = self.__y - other.y
+        return sqrt(dx ** 2 + dy ** 2)

pyske/core/util/point_3D.py

@@ -0,0 +1,95 @@
+"""
+A module to represent a 3D point
+"""
+
+from math import sqrt
+from pyske.core.util.point_Interface import Point_Interface
+
+
+class Point_3D(Point_Interface):
+    """A class to represent a 3D point"""
+
+    def __init__(self, x=0, y=0, z=0):
+        self.__x = x
+        self.__y = y
+        self.__z = z
+
+    def __repr__(self):
+        return "(%s, %s, %s)" % (self.__x, self.__y, self.__z)
+
+    def __eq__(self, other):
+        if isinstance(other, Point_3D):
+            return self.__x == other.__x and self.__y == other.__y and self.__z == other.__z
+        return False
+
+    def __add__(self, other):
+        """
+        Addition of two points
+
+        Examples::
+
+            >>> p1 = Point_3D(5,5,2)
+            >>> p2 = Point_3D(5,7,1)
+            >>> p1 + p2
+            (10, 12, 3)
+        """
+        if isinstance(other, Point_3D):
+            return Point_3D(self.x + other.x, self.y + other.y, self.z + other.z)
+
+    def __mul__(self, other):
+        """
+        Multiplication by a point or a scalar
+
+        Examples::
+
+            >>> p1 = Point_3D(5,5,2)
+            >>> p2 = Point_3D(5,7,1)
+            >>> p1 * 5
+            (25, 25, 10)
+            >>> p1 * p2
+            (25, 35, 2)
+        """
+        if isinstance(other, Point_3D):
+            return Point_3D(self.x * other.x, self.y * other.y, self.z * other.z)
+        if isinstance(other, int) or isinstance(other, float):
+            return Point_3D(self.x * other, self.y * other, self.z * other.z)
+
+    def __truediv__(self, other):
+        if isinstance(other, int):
+            return Point_3D(self.x / other, self.y / other, self.z / other)
+
+    @property
+    def x(self):
+        """X getter"""
+        return self.__x
+
+    @property
+    def y(self):
+        """Y getter"""
+        return self.__y
+
+    @property
+    def z(self):
+        """Z getter"""
+        return self.__z
+
+    def distance(self, other):
+        """
+        Returns the distance from another 3D point.
+
+        Examples::
+
+            >>> from pyske.core.util.point_2D import Point_2D
+            >>> p1 = Point_3D(5,5,2)
+            >>> p2 = Point_3D(5,7,1)
+            >>> p1.distance(p2)
+            2.24
+
+        :param other: a point
+        :return: distance from other point
+
+        """
+        dx = self.__x - other.x
+        dy = self.__y - other.y
+        dz = self.__z - other.z
+        return sqrt(dx ** 2 + dy ** 2 + dz ** 2)