flspp 0.1.0__tar.gz

flspp-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.1
+Name: flspp
+Version: 0.1.0
+Summary: 
+Author: Lukas Drexler
+Author-email: lukas.drexler@hhu.de
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: scikit-learn (>=1.4.2,<2.0.0)
+Description-Content-Type: text/markdown
+
+[![Build Status](https://github.com/algo-hhu/FLSpp/actions/workflows/mypy-flake-test.yml/badge.svg)](https://github.com/algo-hhu/FLSpp/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Supported Python version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)
+[![Stable Version](https://img.shields.io/pypi/v/flspp?label=stable)](https://pypi.org/project/flspp/)
+
+# FLS++
+
+An implementation of the FLS++ algorithm for k-means Clustering, as presented in [1]. This is an improvement of the LS++ algorithm presented by Lattanzi and Sohler in [2].
+
+One can think of the algorithm as working in 3 phases:
+
+1. Initializing centers with k-means++ (as presented in [3]).
+2. Improving the center set by performing local search swaps (for details, see [1]).
+3. Converging the solution with LLoyd's algorithm (also known as "the" k-means algorithm).
+
+In [2] it is shown that `O(k log log k)` local search iterations yield a constant factor approximation. However, in both [1] and [2] it is shown that, in practice, a very small number of iterations (e.g. 20) already yields very good results, at very reasonable runtime.
+
+The interface is built in the same way as scikit-learn's KMeans for better compatibility.
+
+## References
+
+[1] Theo Conrads, Lukas Drexler, Joshua Könen, Daniel R. Schmidt and Melanie Schmidt. "Local Search k-means++ with Foresight" (2024)
+
+[2] Silvio Lattanzi and Christian Sohler. A better k-means++ algorithm via local search. In Proc.444
+of the 36th ICML, volume 97 of Proceedings of Machine Learning Research, pages 3662–3671.445
+PMLR, 09–15 Jun 2019
+
+[3] David Arthur and Sergei Vassilvitskii. K-means++: The advantages of careful seeding. In409
+Proceedings of the 18th SODA, page 1027–1035, USA, 2007
+
+## Installation
+
+```bash
+pip install flspp
+```
+
+## Example
+
+```python
+from flspp import FLSpp
+
+example_data = [
+    [1.0, 1.0, 1.0],
+    [1.1, 1.1, 1.1],
+    [1.2, 1.2, 1.2],
+    [2.0, 2.0, 2.0],
+    [2.1, 2.1, 2.1],
+    [2.2, 2.2, 2.2],
+]
+
+flspp = FLSpp(n_clusters=2)
+labels = flspp.fit_predict(example_data)
+centers = flspp.cluster_centers_
+
+print(labels) # [1, 1, 1, 0, 0, 0]
+print(centers) # [[2.1, 2.1, 2.1], [1.1, 1.1, 1.1]]
+```
+
+## Development
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install clang
+```bash
+sudo apt-get install clang
+```
+
+Set clang variables
+```bash
+export CXX=/usr/bin/clang++
+export CC=/usr/bin/clang
+```
+
+Install the package
+```bash
+poetry install
+```
+
+If the installation does not work and you do not see the C++ output, you can build the package to see the stack trace
+```bash
+poetry build
+```
+
+Run the tests
+```bash
+poetry run python -m unittest discover tests -v
+```
+
+## Citation
+
+If you use this code, please cite the following paper:
+
+```
+Theo Conrads, Lukas Drexler, Joshua Könen, Daniel R. Schmidt and Melanie Schmidt. "Local Search k-means++ with Foresight" (2024). Accepted at SEA 2024.
+```
+

flspp-0.1.0/README.md

@@ -0,0 +1,98 @@
+[![Build Status](https://github.com/algo-hhu/FLSpp/actions/workflows/mypy-flake-test.yml/badge.svg)](https://github.com/algo-hhu/FLSpp/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Supported Python version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)
+[![Stable Version](https://img.shields.io/pypi/v/flspp?label=stable)](https://pypi.org/project/flspp/)
+
+# FLS++
+
+An implementation of the FLS++ algorithm for k-means Clustering, as presented in [1]. This is an improvement of the LS++ algorithm presented by Lattanzi and Sohler in [2].
+
+One can think of the algorithm as working in 3 phases:
+
+1. Initializing centers with k-means++ (as presented in [3]).
+2. Improving the center set by performing local search swaps (for details, see [1]).
+3. Converging the solution with LLoyd's algorithm (also known as "the" k-means algorithm).
+
+In [2] it is shown that `O(k log log k)` local search iterations yield a constant factor approximation. However, in both [1] and [2] it is shown that, in practice, a very small number of iterations (e.g. 20) already yields very good results, at very reasonable runtime.
+
+The interface is built in the same way as scikit-learn's KMeans for better compatibility.
+
+## References
+
+[1] Theo Conrads, Lukas Drexler, Joshua Könen, Daniel R. Schmidt and Melanie Schmidt. "Local Search k-means++ with Foresight" (2024)
+
+[2] Silvio Lattanzi and Christian Sohler. A better k-means++ algorithm via local search. In Proc.444
+of the 36th ICML, volume 97 of Proceedings of Machine Learning Research, pages 3662–3671.445
+PMLR, 09–15 Jun 2019
+
+[3] David Arthur and Sergei Vassilvitskii. K-means++: The advantages of careful seeding. In409
+Proceedings of the 18th SODA, page 1027–1035, USA, 2007
+
+## Installation
+
+```bash
+pip install flspp
+```
+
+## Example
+
+```python
+from flspp import FLSpp
+
+example_data = [
+    [1.0, 1.0, 1.0],
+    [1.1, 1.1, 1.1],
+    [1.2, 1.2, 1.2],
+    [2.0, 2.0, 2.0],
+    [2.1, 2.1, 2.1],
+    [2.2, 2.2, 2.2],
+]
+
+flspp = FLSpp(n_clusters=2)
+labels = flspp.fit_predict(example_data)
+centers = flspp.cluster_centers_
+
+print(labels) # [1, 1, 1, 0, 0, 0]
+print(centers) # [[2.1, 2.1, 2.1], [1.1, 1.1, 1.1]]
+```
+
+## Development
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install clang
+```bash
+sudo apt-get install clang
+```
+
+Set clang variables
+```bash
+export CXX=/usr/bin/clang++
+export CC=/usr/bin/clang
+```
+
+Install the package
+```bash
+poetry install
+```
+
+If the installation does not work and you do not see the C++ output, you can build the package to see the stack trace
+```bash
+poetry build
+```
+
+Run the tests
+```bash
+poetry run python -m unittest discover tests -v
+```
+
+## Citation
+
+If you use this code, please cite the following paper:
+
+```
+Theo Conrads, Lukas Drexler, Joshua Könen, Daniel R. Schmidt and Melanie Schmidt. "Local Search k-means++ with Foresight" (2024). Accepted at SEA 2024.
+```

flspp-0.1.0/build.py

@@ -0,0 +1,46 @@
+from typing import Any, Dict
+
+from setuptools import Extension
+from setuptools.command.build_ext import build_ext
+from setuptools.errors import CompileError
+
+extension = Extension(
+    name="flspp._core",
+    sources=[
+        "flspp/_core.cpp",
+        "flspp/clustering_algorithm.cpp",
+        "flspp/clustering.cpp",
+        "flspp/makros.cpp",
+        "flspp/random_generator.cpp",
+    ],
+    include_dirs=["flspp"],
+)
+
+# Thank you https://github.com/dstein64/kmeans1d!
+
+
+class BuildExt(build_ext):
+    """A custom build extension for adding -stdlib arguments for clang++."""
+
+    def build_extensions(self) -> None:
+        # '-std=c++11' is added to `extra_compile_args` so the code can compile
+        # with clang++. This works across compilers (ignored by MSVC).
+        for extension in self.extensions:
+            extension.extra_compile_args.append("-std=c++11")
+
+        try:
+            build_ext.build_extensions(self)
+        except CompileError:
+            # Workaround Issue #2.
+            # '-stdlib=libc++' is added to `extra_compile_args` and `extra_link_args`
+            # so the code can compile on macOS with Anaconda.
+            for extension in self.extensions:
+                extension.extra_compile_args.append("-stdlib=libc++")
+                extension.extra_link_args.append("-stdlib=libc++")
+            build_ext.build_extensions(self)
+
+
+def build(setup_kwargs: Dict[str, Any]) -> None:
+    setup_kwargs.update(
+        {"ext_modules": [extension], "cmdclass": {"build_ext": BuildExt}}
+    )

flspp-0.1.0/flspp/__init__.py

@@ -0,0 +1,3 @@
+from flspp.core import FLSpp
+
+__all__ = ["FLSpp"]

flspp-0.1.0/flspp/_core.cpp

@@ -0,0 +1,109 @@
+#include <Python.h>
+
+#include "random_generator.h"
+#include "clustering_algorithm.h"
+#include "additional_vector_stuff.h"
+#include "makros.h"
+
+std::vector<Point> array_to_vector(double **array, int rows, int columns)
+{
+
+    std::vector<Point> points;
+
+    for (int i = 0; i < rows; ++i)
+    {
+        std::vector<double> row;
+        for (int j = 0; j < columns; ++j)
+        {
+            row.push_back(array[i][j]);
+        }
+        Point p = Point(columns, i, row);
+        points.push_back(p);
+    }
+
+    return points;
+}
+
+// Thank you https://github.com/dstein64/kmeans1d!
+
+extern "C"
+{
+// "__declspec(dllexport)" causes the function to be exported when compiling on Windows.
+// Otherwise, the function is not exported and the code raises
+//   "AttributeError: function 'cluster' not found".
+// Exporting is a Windows platform requirement, not just a Visual Studio requirement
+// (https://stackoverflow.com/a/22288874/1509433). The _WIN32 macro covers the Visual
+// Studio compiler (MSVC) and MinGW. The __CYGWIN__ macro covers gcc and clang under
+// Cygwin.
+#if defined(_WIN32) || defined(__CYGWIN__)
+    __declspec(dllexport)
+#endif
+    double
+    cluster(double **array,
+            uint n,
+            uint d,
+            uint k,
+            uint lloyd_iterations,
+            uint local_search_iterations,
+            int *labels,
+            double *centers,
+            int *iterations)
+    {
+
+        /*
+         * double** array: input points (as an array of coordinate arrays)
+         * int n: number of input points
+         * int d: dimension/number of features
+         * int k: number of centers
+         * int lloyd_iterations: how many iterations of lloyd's algorithm are performed (choose -1 for precision-based termination)
+         * int local_search_iterations: how many local search steps /center swaps are performed
+         * int* cluster: array of length n, which will eventually contain the labels for each point (i.e. cluster membership)
+         * double** centers: (k x d)-array, which will eventually contain coordinates of final centers
+         */
+
+        // transform input array to vector of "Points" (to be able to use existing constructor for FLSPP object)
+        std::vector<Point> points = array_to_vector(array, n, d);
+
+        // create FLSPP object from vector of points
+        FLSPP my_flspp(points);
+
+        // output_algorithm object contains information such as final labels and final centers
+        output_algorithm flspp_output = my_flspp.algorithm(k);
+
+        memcpy(labels, flspp_output.final_labels.data(), n * sizeof(int));
+
+        // flspp_output has vector<Point> attribute final_centers, containing the final centers as instances of class Point
+        for (int j = 0; j < k; ++j)
+        {
+            // get coordinates of j-th center
+            std::vector<double> center_coordinates = flspp_output.final_centers[j].coordinates;
+            // We save it in a continuous array
+            for (int l = 0; l < d; ++l)
+            {
+                centers[j * d + l] = center_coordinates[l];
+                // std::cout << centers[j][l] << " ";
+            }
+            // std::cout << std::endl;
+        }
+
+        *iterations = flspp_output.iterations;
+
+        return flspp_output.cost;
+    }
+} // extern "C"
+
+static PyMethodDef module_methods[] = {
+    {NULL, NULL, 0, NULL}};
+
+static struct PyModuleDef _coremodule = {
+    PyModuleDef_HEAD_INIT,
+    "flspp._core",
+    NULL,
+    -1,
+    module_methods,
+};
+
+PyMODINIT_FUNC PyInit__core(void)
+{
+    return PyModule_Create(&_coremodule);
+}

flspp-0.1.0/flspp/additional_vector_stuff.h

@@ -0,0 +1,39 @@
+#pragma once
+#include <vector>
+#include <iterator>
+#include "clustering.h"
+#include "makros.h"
+
+// overload comparison of vectors
+// template<typename T>
+// bool operator==(const std::vector<T>& lhs, const std::vector<T>& rhs);
+
+// templates can not be compiled => They can not be included in a cpp file
+// https://stackoverflow.com/questions/1639797/template-issue-causes-linker-error-c
+
+template <typename T>
+inline bool operator==(const std::vector<T> &lhs, const std::vector<T> &rhs)
+{
+	if (lhs.size() != rhs.size())
+		return false;
+	for (int i = 0; i < lhs.size(); i++)
+	{
+		if (lhs[i] != rhs[i])
+			return false;
+	}
+	return true;
+}
+
+template <typename T>
+std::ostream &operator<<(std::ostream &os, const std::vector<T> &vec)
+{
+	for (auto elem : vec)
+	{
+		os << elem << " ";
+	}
+	return os;
+}
+
+// printing vectors
+// template <typename T>
+// std::ostream& operator << (std::ostream& os, const std::vector<T>& vec);

flspp-0.1.0/flspp/clustering.cpp

@@ -0,0 +1,70 @@
+//
+// Created by lukas on 01.12.22.
+// Implementation of classes defined in clustering.h
+
+#include "clustering.h"
+
+Point::Point(int dim, int ind, std::vector<double> coord) : dimension(dim), index(ind), coordinates(coord)
+{
+}
+
+Point::Point(Point const &p) : dimension(p.dimension), index(p.index), coordinates(p.coordinates)
+{
+}
+
+Point::Point()
+{
+}
+
+bool operator==(const Point &lhs, const Point &rhs)
+{
+    // we only compare the coordinates, since some of the other values may not be initialized
+    return lhs.coordinates == rhs.coordinates;
+}
+
+bool operator!=(const Point &lhs, const Point &rhs)
+{
+    return !(lhs == rhs);
+}
+
+std::ostream &operator<<(std::ostream &os, const Point &p)
+{
+    os << "[ " << p.coordinates << "]";
+
+    return os;
+}
+
+void Point::operator+=(const Point &other)
+{
+    if (coordinates.size() != other.coordinates.size())
+    {
+        throw std::invalid_argument("Points must have the same number of dimensions.");
+    }
+
+    for (size_t i = 0; i < coordinates.size(); ++i)
+    {
+        coordinates[i] += other.coordinates[i];
+    }
+}
+
+double euclidean_distance_squared(Point &x, Point &y)
+{
+    double distance = 0;
+    double a, b;
+    for (int i = 0; i < x.dimension; ++i)
+    {
+        // distance += (x.coordinates[i] - y.coordinates[i]) * (x.coordinates[i] - y.coordinates[i]);
+        // distance += std::pow(x.coordinates[i] - y.coordinates[i],2);
+        a = x.coordinates[i];
+        b = y.coordinates[i];
+        distance += (a - b) * (a - b);
+    }
+    return distance;
+}
+
+Cluster::Cluster(int ind, Point centr) : index(ind), centroid(centr) {}
+
+void Cluster::add_member(Point p)
+{
+    members.push_back(p);
+}

flspp-0.1.0/flspp/clustering.h

@@ -0,0 +1,56 @@
+//
+// Created by lukas on 21.11.22.
+//
+
+// #ifndef FLS___CLUSTERING_H
+// #define FLS___CLUSTERING_H
+
+#pragma once
+#include <vector>
+#include <iterator>
+#include <iostream>
+#include <cmath>
+
+#include "additional_vector_stuff.h"
+#include "makros.h"
+
+// MAYBE TWO DISTINCT CLASSES: ONE FOR "NORMAL" POINTS, ONE FOR CENTERS?
+class Point
+{
+public:
+    int dimension;
+    int index;
+
+    std::vector<double> coordinates;
+
+    Point(int dim, int ind, std::vector<double> coord);
+    Point(Point const &p);
+    Point();
+
+    void operator+=(const Point &other);
+};
+
+bool operator==(const Point &lhs, const Point &rhs);
+bool operator!=(const Point &lhs, const Point &rhs);
+
+// Overload the += operator to add another Point to this Point
+
+std::ostream &operator<<(std::ostream &os, const Point &p);
+
+double euclidean_distance_squared(Point &x, Point &y);
+
+class Cluster
+{
+public:
+    int index;
+    Point centroid;
+
+    Cluster(int ind, Point centr);
+
+    void add_member(Point p);
+
+private:
+    std::vector<Point> members;
+};
+
+// #endif //FLS___CLUSTERING_H