
Autor: Joonas Puura, 12.05.2016


Failid:
    Makefile
        Rakenduse kompileerimiseks. make.
        
    main.c
        Ksurealt parameetrite lugemine ja nendele kohaselt tegutsemine. 
        
        Eduka lpetamise korral tagastab 0.
        Vea korral sulgeb programmi.
        
    auxfunctions.c/.h
        Sisaldab peamiste abifunktsioonide realisatsioone
        
        Defineeritud makrod:
            #define LLOYD 1
            #define ELKAN 2
            #define MCQUEEN 3
            #define HAMERLY 4
            #define FIND_CLOSEST 5
            #define HARTIGAN 6

            #define RANDOM_INIT 1
            #define KPP_INIT 2
            #define FIRST_N 3
            #define RANDOM_PARTITION 4
            #define FURTHEST_FIRST 5

            #define EUCLIDEAN_METRIC 1
            #define MANHATTAN_METRIC 2
    
        int get_option_location(int argc, char *argv[], char *choice)
            Otsib etteantud sne massiivist, kui esineb, siis tagastab indeksi.
            Kasutatakse ksurealt antud parameetrite seest otsimiseks.
            
            argc   [IN] - ksureaparameetrite arv
            argv   [IN] - ksureaparameetrite snemassiiv
            choice [IN] - otsitav sne
            
            Tagastusvrtus (int):
                -1, kui ei leidunud
                Leidumise korral vastav indeks.
                
                
        double* get_points_from_file(const char *fileName, size_t *n, size_t *d)
            Andes ette objektide failinime loeb failist sisse objektid.
            Esimeselt realt loetakse kaks tisarvu, vastavalt n ja d.
            Jrgmistelt ridadelt loetakse sisse n*d ujukomaarvu.
            
            fileName [IN] - failinimi, millest objektid loetakse
            n       [OUT] - failist esimeselt realt loetud esimene tisarv, mis thistab objektide arvu failis
            d       [OUT] - failist esimest realt loetud teine tisarv, mis thistab andmete dimensionaalsust
            
            
            Tagastusvrtus (double*):
                Tagastab double tpi massiivi mluala suuruses sizeof(double)*n*d otsviida.
                0, kui lugemine ebannestus 
                Vea korral vljub programmist (nt pole piisavalt objekte failis).
                
                
        void print_clustering(size_t *assignments, size_t n)
            Kirjutab objektide klastrikuuluvused standardvljundisse
            
            assignments [IN] - massiiv tisarvudest, kuhu objektid kuuluvad
            n           [IN] - objektide arv.
            
        int write_assignments_to_file(char *fileName, size_t *clustering, size_t n)   
            Kirjutab objektide kuuluvused etteantud nimega faili.
            
            fileName    [IN] - failinimi, millesse ritatakse kirjutada objektide kuuluvused.
            assignments [IN] - massiiv tisarvudest, kuhu objektid kuuluvad
            n           [IN] - objektide arv.
            
            
            Tagastusvrtus (int):
                0, kui kik nnestus
               -1, kui failiavamine ebannestus.
            
        int write_centers_to_file(char *fileName, double *centers, size_t d, size_t k)
            Kirjutab keskpunktid etteantud nimega faili.
            
            fileName   [IN] - failinimi, millesse ritatakse kirjutada objektide kuuluvused.
            centers    [IN] - keskpunktide massiiv
            d          [IN] - keskpunktide dimensionaalsus
            k          [IN] - keskpunktide arv
            
            
        double* get_centers_from_file(char *fileName, size_t d, size_t *k)
            Loeb keskpunktid etteantud nimega failist.
            Loeb esimeselt realt tisarvu k, mis salvestatakse k muutujasse.
            Jrgmistelt ridadelt loetakse k*d ujukomaarvu, mis tagastatakse keskpunktidena.
            
            d          [IN] - keskpunktide dimensionaalsus
            k          [OUT] - keskpunktide arv            
            
            Tagastusvrtus (double*):
                Tagastab double tpi massiivi mluala suuruses sizeof(double)*k*d otsviida.
                0, kui lugemine ebannestus 
                Vea korral vljub programmist (nt pole piisavalt objekte failis).
                
                
        unsigned long long llrand()
            Funktsioon suurte pseudojuhuslike tisarvude genereerimiseks.
            
            Tagastusvrtus (long long):
                Juhuslik long long tpi tisarv.
        
        void find_closest_centers(double *points, size_t n, size_t d, size_t k, double* clusterCenters, size_t* assignments, metricType m_metric)
            Funktsioon igale punktile lhima keskpunkti otsimiseks. Kasutatakse peamiselt siis, kui ette anda keskpunktide fail ja nha antud keskpunktide korral klasterdust.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            clusterCenters [IN] - Keskpunktide massiiv
            assignments    [OUT] - massiiv tisarvudest, kuhu objektid kuuluvad
            m_metric [IN] - meetrika, mida kasutatakse.
            
        int algorithm_choice(char* algorithm)
            Funktsioon algoritmi valimiseks.
            
            algorithm - sne
            
            Tagastusvrtus (int):
                -1, kui algoritmi ei leidnud.
                Vastasel juhul algoritmile vastav tisarv
                
            
        int initmethod_choice(char* method)    
            Funktsioon keskpunktide valimise algoritmi valimiseks.
            
            method - sne
            
            Tagastusvrtus (int):
                -1, kui algoritmi ei leidnud.
                Vastasel juhul algoritmile vastav tisarv
                
        double calculate_e_value(double *points, size_t n, size_t d, double *clusterCenters, size_t *assignments)
            Funktsioon TWGD (Total Within Group Distance) arvutamiseks.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            clusterCenters [IN] - Keskpunktide massiiv
            assignments    [IN] - massiiv tisarvudest, kuhu objektid kuuluvad            
            
            Tagastusvrtus (double):
                tagastab TWGD
                
        double calculate_sqrd_value(double *points, size_t n, size_t d, double *clusterCenters, size_t *assignments)       
            Funktsioon WCSS (Within Cluster Sum of Squares) arvutamiseks.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            clusterCenters [IN] - Keskpunktide massiiv
            assignments    [IN] - massiiv tisarvudest, kuhu objektid kuuluvad            
            
            Tagastusvrtus (double):
                tagastab WCSS            
    
    
    clusteringalgorithms.h
        Kasutatakse mugavamaks algoritmide piste sisselaadimiseks.
        
        
    commonmacros.h
        Defineerib mningad programmis korduvalt kasutatavad makrod.
        Mlu vabastamise makro ALFREE(name) ja mlu allokeerimise nnestumise kontroll ALCHECK(name)
        
        Max ja min makrod:
            #define MAX(X,Y) ((X) > (Y) ? (X) : (Y))
            #define MIN(X,Y) ((X) < (Y) ? (X) : (Y))
            
            
        typedef double (*metricType)(size_t, double*, double*); - meetrikate tbi definitsioon.

    
    initmethods.c/.h
    
        static size_t in_array(size_t* array, size_t nr, size_t n)
            Funktsioon otsimaks, kas mingi tisarv paikneb etteantud tisarvude massiivis.
            
            array [IN] - tisarvude massiiv
            nr    [IN] - otsitav tisarv
            n     [IN] - massiivi pikkus
            
            Tagastusvrtus (int):
                1, kui tisarv esines massiivis
                0, kui tisarvu ei esinenud massiivis
                
                
        double* random_cluster_init(double* data, size_t n, int d, size_t k, unsigned int seed)
            Funktsioon algkeskpunktide valikuks. Kasutab Forgy meetodit k keskpunkti valimiseks, millest saavad algsed keskpunktid.
        
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            seed   [IN] - pseudojuhusliku arvugeneraatori seeme
            
            Tagastusvrtus (double*):
                Suvaliselt valitud keskpunktide massiiv. sizeof(double)*k*d
        
        double* pick_n_first(double* data, size_t n, size_t d, size_t k)
            Funktsioon valib algkeskpunktideks objektide failist k esimest.
            

                points [IN] - objektide massiiv
                n      [IN] - objektide arv
                d      [IN] - objektide ja keskpunktide dimensionaalsus
                k      [IN] - keskpunktide arv
                
                Tagastusvrtus (double*):
                    Keskpunktide massiiv. sizeof(double)*k*d        
        
        double* kmeans_pp(double* data, size_t n, int d, size_t k, unsigned int seed, metricType m_metric)
            Funktsioon kasutab k-means++ algkeskpunktide valikuks.
            
            
                points [IN] - objektide massiiv
                n      [IN] - objektide arv
                d      [IN] - objektide ja keskpunktide dimensionaalsus
                k      [IN] - keskpunktide arv
                seed   [IN] - pseudojuhusliku arvugeneraatori seeme
                m_metric [IN] kasutatav meetrika
                
                Tagastusvrtus (double*):
                    Valitud keskpunktide massiiv. sizeof(double)*k*d        
                    
        double* furthest_first(double* data, size_t n, size_t d, size_t k, unsigned int seed, metricType m_metric)
                Funktsioon kasutab kaugem enne meetodit algsete keskpunktide valikuks.
                
                points [IN] - objektide massiiv
                n      [IN] - objektide arv
                d      [IN] - objektide ja keskpunktide dimensionaalsus
                k      [IN] - keskpunktide arv
                seed   [IN] - pseudojuhusliku arvugeneraatori seeme
                m_metric [IN] kasutatav meetrika
                
                Tagastusvrtus (double*):
                    Valitud keskpunktide massiiv. sizeof(double)*k*d    
            
        double* random_partition(double* data, size_t n, size_t d, size_t k, unsigned int seed);
            Funktsioon jagamise meetodil algkeskpunktide valikuks
        
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            seed   [IN] - pseudojuhusliku arvugeneraatori seeme
                
            Tagastusvrtus (double*):
                Valitud keskpunktide massiiv. sizeof(double)*k*d    
        
        
    lloyd.c/.h
        void lloyd_clustering(double *points, size_t n, size_t d, size_t k, int iterations, double *clusterCenters, size_t *assignments, metricType m_metric);
            Funktsioon Lloydi algoritmi rakendamiseks.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            iterations [IN] - max iteratsioonide arv
            clusterCenters [IN/OUT] - keskpunktide massiiv
            assignments    [OUT] - massiiv tisarvudest, kuhu objektid kuuluvad.
            m_metric [IN] - meetrika, mida klasterdamisel kasutatakse.

        
    elkan.c/.h
        void elkan_clustering(double *points, size_t n, size_t d, size_t k, int iterations, double *clusterCenters, size_t *assignments, metricType m_metric);
            Funktsioon Elkani algoritmi rakendamiseks.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            iterations [IN] - max iteratsioonide arv
            clusterCenters [IN/OUT] - keskpunktide massiiv
            assignments    [OUT] - massiiv tisarvudest, kuhu objektid kuuluvad.
            m_metric [IN] - meetrika, mida klasterdamisel kasutatakse.

    hamerly.c/.h
        void hamerly_clustering(double *points, size_t n, size_t d, size_t k, int iterations, double *clusterCenters, size_t *assignments, metricType m_metric);
            Funktsioon Hamerly algoritmi rakendamiseks.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            iterations [IN] - max iteratsioonide arv
            clusterCenters [IN/OUT] - keskpunktide massiiv
            assignments    [OUT] - massiiv tisarvudest, kuhu objektid kuuluvad.
            m_metric [IN] - meetrika, mida klasterdamisel kasutatakse.

    
    macqueen.c/.h
        void macqueen_clustering(double *points, size_t n, size_t d, size_t k, int iterations, double *clusterCenters, size_t *assignments, metricType m_metric);
            Funktsioon MacQueeni algoritmi rakendamiseks.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            iterations [IN] - max iteratsioonide arv
            clusterCenters [IN/OUT] - keskpunktide massiiv
            assignments    [OUT] - massiiv tisarvudest, kuhu objektid kuuluvad.
            m_metric [IN] - meetrika, mida klasterdamisel kasutatakse.

   
    hartiganwong.c/.h
        void hartigan_clustering(double *points, size_t n, size_t d, size_t k, int iterations, double *clusterCenters, size_t *assignments, metricType m_metric);
            Funktsioon Hartigan-Wongi algoritmi rakendamiseks.
            
            points [IN] - objektide massiiv
            n      [IN] - objektide arv
            d      [IN] - objektide ja keskpunktide dimensionaalsus
            k      [IN] - keskpunktide arv
            iterations [IN] - max iteratsioonide arv
            clusterCenters [IN/OUT] - keskpunktide massiiv
            assignments    [OUT] - massiiv tisarvudest, kuhu objektid kuuluvad.
            m_metric [IN] - meetrika, mida klasterdamisel kasutatakse.


    metrics.c/.h
        Failis hoitakse meetrikate arvutamise funktsioone.
        
        double euclid(size_t d, double* data1, double* data2);
            
            d      [IN] - vektorite dimensionaalsus
            data1  [IN] - esimene andmeobjekt
            data2  [IN] - teine andmeobjekt
            
            Tagastusvrtus (double):
                Eukleidiline kaugus kahe andmeobjekti data1 ja data2 vahel.
            
            