{
"info": {
"author": "Ziheng Chen",
"author_email": "zihengchen2015@u.northwestern.edu",
"bugtrack_url": null,
"classifiers": [
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3"
],
"description": "# Image Algorithm for General Purpose\n\n\nImage Algorithm is a clustering algorithm based [fast search and find of density peaks](http://science.sciencemag.org/content/344/6191/1492). \nComparing with other popular clustering methods, such as DBSCAN, one of the most prominent advantages of Image Algorithm is being highly parallelizable. This repository is an implementation of Image Algorithm for general purpose, supporting strong and easy GPU acceleration. \n\nFor now, the implementation includes three backends: numpy, CUDA and OpenCL.\n\n| backend | dependency | Support Platform | Support Device |\n| :---: | :---: | :---: | :---: |\n| [`numpy`](http://www.numpy.org) | None | Mac/Linux/Windows | CPU |\n| [`CUDA`](https://en.wikipedia.org/wiki/CUDA) | pycuda | Linux | Only NVIDIA GPU |\n| [`OpenCL`](https://en.wikipedia.org/wiki/OpenCL) | pyopencl | Mac | NVIDIA/AMD/Intel GPU, multi-core CPU |\n\nIt has been tested that all three backends give the identical clustering results. Therefore users can feel free to choose whichever faster and easier for their purposes. \n\n\nFor all three backends, two kinds of data structure can be taken in: Flat list and kdbin. KDBin, bins in k-dimention, accommodates points inside spatial bins in k-dimention with dynamic bin distribution and flexible bin capacity. Techniqually it uses hashmap and a set of memory references to obtain nearest neighboring bins and points inside, such that query of neighborhood for each point is O(1) complexity. Performance test shows a strong acceleration in density calculation using KDBin data structure.\n\n| supported data structure | `rho` Calculation | `rhorank` and `nh` Calculation |\n| :---: | :---: | :---: |\n| [`numpy`](http://www.numpy.org) | list/bin | list/bin |\n| [`CUDA`](https://en.wikipedia.org/wiki/CUDA) | list/bin | list |\n| [`OpenCL`](https://en.wikipedia.org/wiki/OpenCL) | list/bin | list |\n\nFor density rho calculation, performance tested is shown below.\n
\n\n\n\n\n\n\nTo do list\n\n* [ ] Calculate `rhorank` in CUDA/OpenCL via 'Merge Sorted List' for parallel sorting.\n* [ ] Support `nh` search in nearest neighboring bins in CUDA/OpenCL\n\n\n## Installation \n\n\n```bash\npip install ImageAlgoKD\n```\n\nRegarding dependency, no dependency is required for numpy backend. And it usually does a good job dealing with small dataset and needs no extra packages. However, for users wanting to use GPU acceleration with either CUDA or OpenCL backend, extra dependency is required. \n\n```bash\n# if want to use opencl backend\npip install pyopencl\n# if want to use CUDA backend\npip install pycuda\n```\n\n## Quick Start\nThe primary usage of the module is the following\nFirst of all, import ImageAlgo class for K-Dimension\n```python\nfrom ImageAlgoKD import *\n```\n\nDeclare an instance of ImageAlgoKD with your algorithm parameters. Then give it the input data points.\n```python\nia = ImageAlgoKD(MAXDISTANCE=20, KERNEL_R=1.0)\nia.setInputsPoints(Points(np.genfromtxt(\"../data/basic.csv\",delimiter=',')))\n```\n\nThen run the clustering over input data points.\n```python\nia.run(\"numpy\")\n# ia.run(\"opencl\") or ia.run(\"cuda\") if want run in parallel\n```\n\nIn the end, the clustering result can be access by\n```python\nia.points.clusterID\n```\n\n## Algorithm Parameters\n\n| Parameters | Comments | Default Value |\n|:------------------:|----------------------------------------------------------------|:-------------:|\n| MAXDISTANCE | the separation distance of the point with highest density. | 10.0 |\n| KERNEL_R | 'd_c' in density calculation | 1.0 |\n| KERNEL_R_NORM | 'd_0' in density calculation | 1.0 |\n| KERNEL_R_POWER | 'k' in density calculation. | 0.0 |\n| DECISION_RHO_KAPPA | the ratio of density threshold of seeds to the highest density | 4.0 |\n| DECISION_NHD | the separation threshold of seeds | 1.0 |\n| CONTINUITY_NHD | the separation threshold of continuous clusters | 1.0 |\n\nwhere density is defined as\n\n
\n\n## Examples\n\n### I. Basic\n\n
\n\nPerform IA clustering on 1000 toy 2D points, sampled from two Gaussian Distrituion and noise. The toy data is in `data/basic.csv`, while the corresponding jupyter notebook can be found [here](/example/example_basic.ipynb) in `examples/`.\n\n### II. MNIST\n
\n \n \n
\n\nPerform IA clustering on 1000 MNIST 28x28 dimension points. The MNIST data is in `data/mnist.csv`, while the corresponding jupyter notebook can be found [here](/example/example_mnist.ipynb) in `examples/`.\n\n### III. HGCal\n\n\n
\n 
\n