PyClustering Documentation

PyClustering is an open-source data mining library designed for cluster analysis. It is implemented in both Python and C++ to provide a wide range of clustering algorithms, including bio-inspired oscillatory networks.

Key features include:

• Hybrid Implementation: Uses a C++ core by default for maximum performance (especially for differential equation-based oscillatory networks). If no C++ compiler is detected, it falls back to pure Python implementations optimized with NumPy.
• Parallelism: Optimized C++14 implementations use std::thread on most platforms and the Parallel Patterns Library on Windows.
• Visualization: Supports 2D and 3D plots of cluster embeddings, image segments, and synchronization process graphs for oscillatory networks.
• Core Dependencies: Requires NumPy and SciPy for data processing, and MatPlotLib and Pillow for visualization.

PyClustering algorithms are implemented in both Python and C/C++. By default, the library attempts to use the C/C++ implementation (ccore=True) for better performance. If the C/C++ core is unavailable or if you want to use the pure Python implementation, you can explicitly set the ccore flag to False.

# As by default - C/C++ part of the library is used
xmeans_instance_1 = xmeans(data_points, start_centers, 20, ccore=True);

# The same - C/C++ part of the library is used by default
xmeans_instance_2 = xmeans(data_points, start_centers, 20);

# Switch off core - Python is used
xmeans_instance_3 = xmeans(data_points, start_centers, 20, ccore=False);

Specialized data containers are available in the pyclustering.container Python module and the ccore::container C++ namespace.

Available Containers:

• KD Tree: Python and C++
• CF Tree: Python only

Graph coloring algorithms are located in the pyclustering.gcolor Python module. Currently, these implementations are Python-only.

Available Algorithms:

• DSatur
• Hysteresis
• GColorSync

Neural network and oscillatory network models are available in the pyclustering.nnet Python module. Some models are implemented in both Python and C++ (ccore::nnet), while others are Python-only.

Available Models:

• CNN (Chaotic Neural Network): Python only
• fSync (Landau-Stuart/Kuramoto based): Python only
• HHN (Hodgkin-Huxley based): Python and C++
• Hysteresis Oscillatory Network: Python only
• LEGION (Local Excitatory Global Inhibitory): Python and C++
• PCNN (Pulse-Coupled Neural Network): Python and C++
• SOM (Self-Organized Map): Python and C++
• Sync (Kuramoto based): Python and C++
• SyncPR (Pattern Recognition): Python and C++
• SyncSegm (Image Segmentation): Python and C++

For Windows users, you can build the C++ core using Visual Studio:

1. Clone the repository: https://github.com/annoviko/pyclustering.git
2. Open the folder pyclustering/ccore.
3. Open the Visual Studio project ccore.sln.
4. Select the solution platform: x86 or x64.
5. Build the pyclustering-shared project.
6. Add the pyclustering folder to your Python path or install it using setup.py.

# install pyclustering library
$ python3 setup.py install

# optionally - test the library
$ python3 setup.py test

To build the C++ PyClustering library on Windows, download the release source files and extract them. Navigate to the pyclustering/ccore directory and open the ccore.sln solution file using Visual Studio.

Build Configurations:

• Use the Release configuration to build a dynamic library.
• Use the Release Static Library configuration to build a static library.

For Windows users, you can build the C++ core using Visual Studio:

1. Clone the repository.
2. Open the pyclustering/ccore folder.
3. Open the ccore.sln project.
4. Select your platform (x86 or x64).
5. Build the pyclustering-shared project.
6. Add the pyclustering folder to your Python path or run python3 setup.py install.

# install pyclustering library
$ python3 setup.py install

# optionally - test the library
$ python3 setup.py test

To build the C++ PyClustering library on Linux or MacOS, download the release source files, extract them, and navigate to the pyclustering/ccore directory. You can then use make to build either a shared (dynamic) library or a static library.

Requirements:

• A compiler that supports C++14.
• make utility.

You can use CMake to generate build files and build the pyclustering-shared target.

# get sources of the pyclustering library, for example, from repository
$ mkdir pyclustering
$ cd pyclustering/
$ git clone https://github.com/annoviko/pyclustering.git .

# generate build files.
$ mkdir build
$ cmake ..

# build pyclustering-shared target depending on what was generated (Makefile or MSVC solution)
# if Makefile has been generated then
$ make pyclustering-shared

# return to parent folder of the pyclustering library
$ cd ../

# install pyclustering library
$ python3 setup.py install

# optionally - test the library
$ python3 setup.py test

The simplest way to install the library is using the pip3 package manager.

$ pip3 install pyclustering