Metadata-Version: 2.1
Name: XPySom
Version: 1.0.5
Summary: Minimalistic implementation of batch Self Organizing Maps (SOM) for parallel execution on CPU or GPU.
Home-page: https://github.com/Manciukic/xpysom
Author: Riccardo Mancini
Author-email: r.mancini@santannapisa.it
License: GNU General Public License v3.0
Download-URL: https://github.com/Manciukic/xpysom/archive/v1.0.5.tar.gz
Description: <h1>XPySom</h1>
        
        Self Organizing Maps
        --------------------
        
        XPySom is a minimalistic implementation of the Self Organizing Maps (SOM) that can seamlessly leverage vector/matrix operations made available on Numpy or CuPy, resulting in an efficient implementation for both multi-core CPUs and GP-GPUs. XPySom has been realized as a quite invasive modification to the MiniSom code available at: https://github.com/JustGlowing/minisom.git.
        
        SOM is a type of Artificial Neural Network able to convert complex, nonlinear statistical relationships between high-dimensional data items into simple geometric relationships on a low-dimensional display.
        
        Installation
        ---------------------
        
        You can download XPySom from PyPi:
        
            pip install xpysom
        
        By default, dependencies for GPU execution are not downloaded. 
        You can also specify a CUDA version to automatically download also those 
        requirements. For example, for CUDA Toolkit 10.2 you would write:
        
            pip install xpysom[cuda102]
        
        Alternatively, you can manually install XPySom.
        Download XPySom to a directory of your choice and use the setup script:
        
            git clone https://github.com/Manciukic/xpysom.git
            python setup.py install
        
        How to use it
        ---------------------
        
        The module interface is similar to [MiniSom](https://github.com/JustGlowing/minisom.git). In the following only the basics of the usage are reported, for an overview of all the features, please refer to the original MiniSom examples you can refer to: https://github.com/JustGlowing/minisom/tree/master/examples (you can find the same examples also in this repository but they have not been updated yet).
        
        In order to use XPySom you need your data organized as a Numpy matrix where each row corresponds to an observation or as list of lists like the following:
        
        ```python
        data = [[ 0.80,  0.55,  0.22,  0.03],
                [ 0.82,  0.50,  0.23,  0.03],
                [ 0.80,  0.54,  0.22,  0.03],
                [ 0.80,  0.53,  0.26,  0.03],
                [ 0.79,  0.56,  0.22,  0.03],
                [ 0.75,  0.60,  0.25,  0.03],
                [ 0.77,  0.59,  0.22,  0.03]]      
        ```
        
         Then you can train XPySom just as follows:
        
        ```python
        from xpysom import XPySom    
        som = XPySom(6, 6, 4, sigma=0.3, learning_rate=0.5) # initialization of 6x6 SOM
        som.train(data, 100) # trains the SOM with 100 iterations
        ```
        
        You can obtain the position of the winning neuron on the map for a given sample as follows:
        
        ```
        som.winner(data[0])
        ```
        
        By default, XPySom executes on the GPU if available (and required packages are
        correctly installed). You can override this behaviour by passing the `xp` 
        parameter to XPySom set to the package you want to use (only Numpy and Cupy
        have been tested, but in theory any Numpy-compliant package would work).
        
        ```python
        from xpysom import XPySom   
        import numpy as np
        
        som = XPySom(6, 6, 4, sigma=0.3, learning_rate=0.5, xp=np)
        ```
        
        Differences with MiniSom
        ---------------------
         - The batch SOM algorithm is used (instead of the online used in MiniSom). Therefore, use only `train` to train the SOM, `train_random` and `train_batch` are not present.
         - `decay_function` input parameter is no longer a function but one of `'linear'`,
         `'exponential'`, `'asymptotic'`. As a consequence of this change, `sigmaN` and `learning_rateN` have been added as input parameters to represent the values at the last iteration.
         - New input parameter `std_coeff`, used to calculate gaussian exponent denominator `d = 2*std_coeff**2*sigma**2`. Default value is 0.5 (as in [Somoclu](https://github.com/peterwittek/somoclu), which is **different from MiniSom original value** sqrt(pi)).
         - New input parameter `xp` (default = `cupy` module). Back-end to use for computations.
         - New input parameter `n_parallel` to set size of the mini-batch (how many input samples to elaborate at a time).
         - **Hexagonal** grid support is **experimental** and is significantly slower than rectangular grid.  
        
        Additional documentation
        ---------------------
        A publication about the design and performance of XPySom has been accepted for presentation at the [IEEE 32nd International Symposium on Computer Architecture and High Performance Computing](https://sbac2020.dcc.fc.up.pt/):
          -  Riccardo Mancini, Antonio Ritacco, Giacomo Lanciano and Tommaso Cucinotta. "XPySom: High-Performance Self-Organizing Maps," IEEE 32nd International Symposium on Computer Architecture and High Performance Computing, September 8-11, 2020. Porto, Portugal (turned to a virtual on-line event due to the Covid-19 emergency).
        
        
        TODO
        ---------------------
        
         - [ ] Update examples in `examples/`
         - [ ] Improve hexagonal grid support
        
        Compatibility notes
        ---------------------
        XPySom has been tested under Python 3.7.6 with CuPy 7.4.0 or Numpy 1.18.1.
        
        License
        ---------------------
        
        XPySom
        Copyright (C) 2020 Riccardo Mancini
        
        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.
        
        XPySom is a modification of the original MiniSom by Giuseppe Vettigli, 
        which is licensed under the Creative Commons Attribution 3.0 Unported License
        and can be found at the following [link](https://github.com/JustGlowing/minisom).
        
Keywords: machine learning,neural networks,clustering,dimentionality reduction
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
Provides-Extra: cuda90
Provides-Extra: cuda92
Provides-Extra: cuda100
Provides-Extra: cuda101
Provides-Extra: cuda102
