exact-kmeans 0.1.0__tar.gz

exact_kmeans-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Algorithms and Data Structures Group of the Heinrich Heine University Düsseldorf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exact_kmeans-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.1
+Name: exact-kmeans
+Version: 0.1.0
+Summary: Computes an optimal k-means solution for small instances and small k.
+License: LICENSE
+Author: Melanie Schmidt
+Author-email: mschmidt@hhu.de
+Requires-Python: >=3.8.1,<4.0.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: gurobipy (>=11.0.3,<12.0.0) ; python_version >= "3.9"
+Requires-Dist: gurobipy (>=9.5.1,<10.0.0) ; python_version < "3.9"
+Requires-Dist: numpy (>=1.24.4,<2.0.0) ; python_version < "3.12"
+Requires-Dist: numpy (>=1.26.4,<2.0.0) ; python_version >= "3.12"
+Requires-Dist: pandas (>=2.0.3,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: scikit-learn (>=1.3.2,<2.0.0) ; python_version < "3.12"
+Requires-Dist: scikit-learn (>=1.4.2,<2.0.0) ; python_version >= "3.12"
+Requires-Dist: tqdm (>=4.66.4,<5.0.0)
+Description-Content-Type: text/markdown
+
+[![Build Status](https://github.com/algo-hhu/exact-kmeans/actions/workflows/mypy-flake-test.yml/badge.svg)](https://github.com/algo-hhu/exact-kmeans/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.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![Stable Version](https://img.shields.io/pypi/v/exact-kmeans?label=stable)](https://pypi.org/project/exact-kmeans/)
+
+# exact-kmeans
+
+This package computes exact solutions to the $k$-means problem using integer linear programming (ILP).
+Since our plain ILP solution to the problem was too slow, we implemented a branch-and-bound algorithm that computes multiple ILP solutions for different cluster sizes to find the optimal cluster sizes $[c_1, \ldots, c_k]$.
+The ILPs are implemented using [Gurobi](https://www.gurobi.com/). You will need a [Gurobi license](https://www.gurobi.com/downloads/) to be able to run the code.
+
+The algorithm works as follows:
+- We run $k$-means++ on the data to get an initial upper bound for the cost of an optimal solution.
+- We try to find the largest cluster size $c_1$ that a cluster in the optimal solution may have. We use the fact that the cost of a cluster in the optimal solution is less than the initial upper bound. We do this by solving an ILP (ILP#1).
+- We iterate through all possible cluster sizes $c_1 \geq c_2 \ldots \geq c_k$ and compute for each of them a solution using an ILP (ILP#2). However, we don't actually iterate through all the sizes, but use a branch-and-bound algorithm to skip some of them if the cost exceeds the initial upper bound. You can see an example of this in the tree in the "Plot the Branch and Bound Tree" section.
+
+Both ILPs get cluster sizes $c_1,\ldots, c_i$ with $i\leq k$ as input and compute an optimal solution to the following modification of the $k$-means problem:
+- the number of clusters is $i$
+- the clusters have sizes $c_1,\ldots, c_i$
+- if $n$ is the number of data points $n-c_1-\ldots -c_i$ points are not part of any cluster
+
+ILP#1 gets one single cluster size $c_1$ as input and computes an optimal solution with one single cluster of size $c_1$. We use ILP#1 to compute a lower bound to the cost of a cluster of size $c_1$. If this cost is already larger than the initial upper bound, then we know that the cluster sizes of an optimal solution must be all less than $c_1$. Therefore we can discard all cluster sizes greater equal $c_1$ when searching for the cluster sizes of an optimal solution.
+
+ILP#2 gets cluster sizes $c_1,\ldots, c_i$ with $2\leq i\leq k$ as input. If $c_1,\ldots, c_i$ are also cluster sizes which are represented in the optimal solution the cost that ILP#2 computes should be less than the initial upper bound. We add a constraint to ILP#2 bounding the cost by initial upper bound. Therefore either ILP#2 is infeasible or it outputs an optimal solution of $i$ clusters with sizes $c_1,\ldots, c_i$ and cost smaller than initial upper bound.
+
+To search for the cluster sizes of an optimal solution we use a branch and bound approach. In a branch node of level $i$ the $i$ largest cluster sizes $c_1, \ldots, c_i$ are already fixed. The variables `branching_levels` and `fill_cluster_sizes` define the behavior on these branching nodes. If `branching_levels` is greater equal to the level $i$ of the node then we use ILP#2 to bound the current cost and decide if we branch, otherwise we always branch on this node. If the variable `fill_cluster_sizes` is set to true we compute the smallest possible remaining cluster sizes $c_{i+1},\ldots, c_{k}$ and run ILP#2 with cluster sizes $c_1,\ldots, c_k$. If the variable `fill_cluster_sizes` is set to false we run ILP#2 only with the fixed cluster sizes $c_1,\ldots, c_i$. Setting `fill_cluster_sizes` to true may lead to less branching but can increase the solving time of ILP#2.
+
+To customize the runs, you can create a config file. The default config file is [`config/default.yaml`](config/default.yaml). You can also pass a different config file as an argument.
+- `num_processes` (integer or float) sets the number of processes used. The algorithm was parallelized using the `multiprocessing` package, so you can set the number of processes that you want to use. If you use an integer, at most that number of processes will be taken, otherwise if you use a float, it will be a fraction of the available CPUs. If the parameter is not passed, the algorithm will use all available CPUs.
+- `bound_model_params` are the arguments that are passed to the ILP#1 model. Please have a look at the [Gurobi documentation](https://www.gurobi.com/documentation/9.1/refman/parameters.html) for more information.
+- `model_params` are the arguments that are passed to the ILP#2 model. Please have a look at the [Gurobi documentation](https://www.gurobi.com/documentation/9.1/refman/parameters.html) for more information.
+- `branching_priorities` (true/false) enables the use of branching priorities. If true, the priority of the $x$ variable will be higher than the other variables. According to our tests, this speeds up the solving.
+- `replace_min` (true/false) replaces a minimum constraint with a linear version. According to our tests, this speeds up the solving.
+- `branching_levels` (integer) Sets the maximum level of a branching node where we run ILP#2 to bound the cost. Since this can increase the number of ILPs that are computed, it may only make sense for small levels.
+- `fill_cluster_sizes` (true/false) If set to false we run ILP#2  only with cluster sizes fixed at the branching node. If set to true we fill the cluster sizes up to $k$. Setting the variable to true can result in a larger computation time for ILP#2 but may result in less branching, which can save time. For small $k$ we recommend setting it to false and for large $k$ we recommend setting it to true.
+
+
+## Installation
+
+For this package to work, you need to have a working installation of [Gurobi](https://www.gurobi.com/). You can get a free academic license [here](https://www.gurobi.com/academia/academic-program-and-licenses/).
+[Here](https://support.gurobi.com/hc/en-us/articles/4534161999889-How-do-I-install-Gurobi-Optimizer) you can find a guide on how to install it.
+
+```bash
+pip install exact-kmeans
+```
+
+## Use within Python
+
+```python
+from exact_kmeans import ExactKMeans
+from exact_kmeans.util import JsonEncoder
+from ucimlrepo import fetch_ucirepo
+
+# For example, you can import data from the UCI repository
+# but you can also use your own dataset
+iris = fetch_ucirepo(id=53)
+
+X = iris.data.features
+
+ilp = ExactKMeans(X=X, k=3)
+res = ilp.optimize()
+
+with open("output.json", "w") as f:
+    json.dump(res, f, indent=4, cls=JsonEncoder)
+```
+
+## Command Line
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install the package
+```bash
+poetry install
+```
+
+Run the program
+```bash
+poetry run python -m exact_kmeans --data-path iris.csv --verbose --results-path test/iris.json --k 3 --config-file config/default.yaml
+```
+
+Your `data-path` should be a file with a header containing only the comma-separated data points. Example:
+```csv
+0,1,2,3
+5.1,3.5,1.4,0.2
+4.9,3.0,1.4,0.2
+4.7,3.2,1.3,0.2
+4.6,3.1,1.5,0.2
+5.0,3.6,1.4,0.2
+...
+```
+
+## Plot the Branch and Bound Tree
+
+Assuming that you have run the program and stored the results in a JSON file, you can plot the tree produced by the algorithm.
+
+```bash
+poetry run python plot_tree.py --output-json output.json --plot-folder plots
+```
+
+This will create a tree that looks like this:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/algo-hhu/exact-kmeans/main/images/tree.png" alt="Tree Example"/>
+</p>
+
+The nodes can have the following colors:
+- Red: The cluster sizes were infeasible.
+- Green: The cluster sizes were feasible.
+- Gray: The node was a branching node.
+- Orange/Yellow: The node was skipped because it had a too high initial cost.
+- The optimal node has a gold border.
+
+The nodes have the following information:
+- The cluster sizes that were tested.
+- The amount of seconds it took.
+- The cost of the solution. This is only shown if the node has $k$ clusters and is feasible.
+
+## Development
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install the package
+```bash
+poetry install
+```
+
+Run the tests
+```bash
+poetry run python -m unittest discover tests -v
+```
+
+## Disclaimer
+
+This package requires the Gurobi Optimizer, which is a commercial optimization solver. Users must obtain their own licenses for Gurobi.
+Gurobi License: You are responsible for complying with all Gurobi licensing terms. For more information, visit the [Gurobi Licensing Page](https://www.gurobi.com/academia/academic-program-and-licenses/).
+
+<!--
+## Citation
+
+If you use this code, please cite [the following paper]():
+
+```
+```
+-->
+

exact_kmeans-0.1.0/README.md

@@ -0,0 +1,149 @@
+[![Build Status](https://github.com/algo-hhu/exact-kmeans/actions/workflows/mypy-flake-test.yml/badge.svg)](https://github.com/algo-hhu/exact-kmeans/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.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![Stable Version](https://img.shields.io/pypi/v/exact-kmeans?label=stable)](https://pypi.org/project/exact-kmeans/)
+
+# exact-kmeans
+
+This package computes exact solutions to the $k$-means problem using integer linear programming (ILP).
+Since our plain ILP solution to the problem was too slow, we implemented a branch-and-bound algorithm that computes multiple ILP solutions for different cluster sizes to find the optimal cluster sizes $[c_1, \ldots, c_k]$.
+The ILPs are implemented using [Gurobi](https://www.gurobi.com/). You will need a [Gurobi license](https://www.gurobi.com/downloads/) to be able to run the code.
+
+The algorithm works as follows:
+- We run $k$-means++ on the data to get an initial upper bound for the cost of an optimal solution.
+- We try to find the largest cluster size $c_1$ that a cluster in the optimal solution may have. We use the fact that the cost of a cluster in the optimal solution is less than the initial upper bound. We do this by solving an ILP (ILP#1).
+- We iterate through all possible cluster sizes $c_1 \geq c_2 \ldots \geq c_k$ and compute for each of them a solution using an ILP (ILP#2). However, we don't actually iterate through all the sizes, but use a branch-and-bound algorithm to skip some of them if the cost exceeds the initial upper bound. You can see an example of this in the tree in the "Plot the Branch and Bound Tree" section.
+
+Both ILPs get cluster sizes $c_1,\ldots, c_i$ with $i\leq k$ as input and compute an optimal solution to the following modification of the $k$-means problem:
+- the number of clusters is $i$
+- the clusters have sizes $c_1,\ldots, c_i$
+- if $n$ is the number of data points $n-c_1-\ldots -c_i$ points are not part of any cluster
+
+ILP#1 gets one single cluster size $c_1$ as input and computes an optimal solution with one single cluster of size $c_1$. We use ILP#1 to compute a lower bound to the cost of a cluster of size $c_1$. If this cost is already larger than the initial upper bound, then we know that the cluster sizes of an optimal solution must be all less than $c_1$. Therefore we can discard all cluster sizes greater equal $c_1$ when searching for the cluster sizes of an optimal solution.
+
+ILP#2 gets cluster sizes $c_1,\ldots, c_i$ with $2\leq i\leq k$ as input. If $c_1,\ldots, c_i$ are also cluster sizes which are represented in the optimal solution the cost that ILP#2 computes should be less than the initial upper bound. We add a constraint to ILP#2 bounding the cost by initial upper bound. Therefore either ILP#2 is infeasible or it outputs an optimal solution of $i$ clusters with sizes $c_1,\ldots, c_i$ and cost smaller than initial upper bound.
+
+To search for the cluster sizes of an optimal solution we use a branch and bound approach. In a branch node of level $i$ the $i$ largest cluster sizes $c_1, \ldots, c_i$ are already fixed. The variables `branching_levels` and `fill_cluster_sizes` define the behavior on these branching nodes. If `branching_levels` is greater equal to the level $i$ of the node then we use ILP#2 to bound the current cost and decide if we branch, otherwise we always branch on this node. If the variable `fill_cluster_sizes` is set to true we compute the smallest possible remaining cluster sizes $c_{i+1},\ldots, c_{k}$ and run ILP#2 with cluster sizes $c_1,\ldots, c_k$. If the variable `fill_cluster_sizes` is set to false we run ILP#2 only with the fixed cluster sizes $c_1,\ldots, c_i$. Setting `fill_cluster_sizes` to true may lead to less branching but can increase the solving time of ILP#2.
+
+To customize the runs, you can create a config file. The default config file is [`config/default.yaml`](config/default.yaml). You can also pass a different config file as an argument.
+- `num_processes` (integer or float) sets the number of processes used. The algorithm was parallelized using the `multiprocessing` package, so you can set the number of processes that you want to use. If you use an integer, at most that number of processes will be taken, otherwise if you use a float, it will be a fraction of the available CPUs. If the parameter is not passed, the algorithm will use all available CPUs.
+- `bound_model_params` are the arguments that are passed to the ILP#1 model. Please have a look at the [Gurobi documentation](https://www.gurobi.com/documentation/9.1/refman/parameters.html) for more information.
+- `model_params` are the arguments that are passed to the ILP#2 model. Please have a look at the [Gurobi documentation](https://www.gurobi.com/documentation/9.1/refman/parameters.html) for more information.
+- `branching_priorities` (true/false) enables the use of branching priorities. If true, the priority of the $x$ variable will be higher than the other variables. According to our tests, this speeds up the solving.
+- `replace_min` (true/false) replaces a minimum constraint with a linear version. According to our tests, this speeds up the solving.
+- `branching_levels` (integer) Sets the maximum level of a branching node where we run ILP#2 to bound the cost. Since this can increase the number of ILPs that are computed, it may only make sense for small levels.
+- `fill_cluster_sizes` (true/false) If set to false we run ILP#2  only with cluster sizes fixed at the branching node. If set to true we fill the cluster sizes up to $k$. Setting the variable to true can result in a larger computation time for ILP#2 but may result in less branching, which can save time. For small $k$ we recommend setting it to false and for large $k$ we recommend setting it to true.
+
+
+## Installation
+
+For this package to work, you need to have a working installation of [Gurobi](https://www.gurobi.com/). You can get a free academic license [here](https://www.gurobi.com/academia/academic-program-and-licenses/).
+[Here](https://support.gurobi.com/hc/en-us/articles/4534161999889-How-do-I-install-Gurobi-Optimizer) you can find a guide on how to install it.
+
+```bash
+pip install exact-kmeans
+```
+
+## Use within Python
+
+```python
+from exact_kmeans import ExactKMeans
+from exact_kmeans.util import JsonEncoder
+from ucimlrepo import fetch_ucirepo
+
+# For example, you can import data from the UCI repository
+# but you can also use your own dataset
+iris = fetch_ucirepo(id=53)
+
+X = iris.data.features
+
+ilp = ExactKMeans(X=X, k=3)
+res = ilp.optimize()
+
+with open("output.json", "w") as f:
+    json.dump(res, f, indent=4, cls=JsonEncoder)
+```
+
+## Command Line
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install the package
+```bash
+poetry install
+```
+
+Run the program
+```bash
+poetry run python -m exact_kmeans --data-path iris.csv --verbose --results-path test/iris.json --k 3 --config-file config/default.yaml
+```
+
+Your `data-path` should be a file with a header containing only the comma-separated data points. Example:
+```csv
+0,1,2,3
+5.1,3.5,1.4,0.2
+4.9,3.0,1.4,0.2
+4.7,3.2,1.3,0.2
+4.6,3.1,1.5,0.2
+5.0,3.6,1.4,0.2
+...
+```
+
+## Plot the Branch and Bound Tree
+
+Assuming that you have run the program and stored the results in a JSON file, you can plot the tree produced by the algorithm.
+
+```bash
+poetry run python plot_tree.py --output-json output.json --plot-folder plots
+```
+
+This will create a tree that looks like this:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/algo-hhu/exact-kmeans/main/images/tree.png" alt="Tree Example"/>
+</p>
+
+The nodes can have the following colors:
+- Red: The cluster sizes were infeasible.
+- Green: The cluster sizes were feasible.
+- Gray: The node was a branching node.
+- Orange/Yellow: The node was skipped because it had a too high initial cost.
+- The optimal node has a gold border.
+
+The nodes have the following information:
+- The cluster sizes that were tested.
+- The amount of seconds it took.
+- The cost of the solution. This is only shown if the node has $k$ clusters and is feasible.
+
+## Development
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install the package
+```bash
+poetry install
+```
+
+Run the tests
+```bash
+poetry run python -m unittest discover tests -v
+```
+
+## Disclaimer
+
+This package requires the Gurobi Optimizer, which is a commercial optimization solver. Users must obtain their own licenses for Gurobi.
+Gurobi License: You are responsible for complying with all Gurobi licensing terms. For more information, visit the [Gurobi Licensing Page](https://www.gurobi.com/academia/academic-program-and-licenses/).
+
+<!--
+## Citation
+
+If you use this code, please cite [the following paper]():
+
+```
+```
+-->

exact_kmeans-0.1.0/config/default.yaml

@@ -0,0 +1,29 @@
+ilp_version: v4
+
+num_processes: 0.5
+branch_priorities: true
+replace_min: true
+branching_ilp: true
+branching_levels: 2
+fill_cluster_sizes: false
+
+model_params:
+  TimeLimit: 28800
+  BarHomogeneous: 1
+  BarConvTol: 0.001
+  FeasibilityTol: 0.001
+  # Method: 2
+  # Crossover: 0
+  # NodeMethod: 2
+
+bound_model_params:
+  TimeLimit: 1800
+  BarConvTol: 0.0001
+  FeasibilityTol: 0.0001
+  # Concurrent spin time: 9.02s (can be avoided by choosing Method=3)
+  Method: 3
+
+# https://support.gurobi.com/hc/en-us/community/posts/4406728832145-Crossover-Takes-Long
+# Method: 2
+# Crossover: 0
+# NodeMethod: 2

exact_kmeans-0.1.0/exact_kmeans/__init__.py

@@ -0,0 +1,3 @@
+from exact_kmeans.ilp import ExactKMeans
+
+__all__ = ["ExactKMeans"]

exact_kmeans-0.1.0/exact_kmeans/__main__.py

@@ -0,0 +1,110 @@
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+from time import time
+
+import pandas as pd
+
+from exact_kmeans.ilp import ExactKMeans
+from exact_kmeans.util import JsonEncoder, get_git_hash
+
+logger = logging.getLogger(__name__)
+
+
+def set_up_logger(log_file: Path, mode: str = "w+") -> None:
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+    formatter = logging.Formatter(
+        "[%(asctime)s: %(levelname)s/%(filename)s:%(lineno)d] %(message)s"
+    )
+
+    stdout_handler = logging.StreamHandler(sys.stdout)
+    stdout_handler.setLevel(logging.DEBUG)
+    stdout_handler.setFormatter(formatter)
+
+    file_handler = logging.FileHandler(log_file, mode=mode)
+    file_handler.setLevel(logging.DEBUG)
+    file_handler.setFormatter(formatter)
+
+    logger = logging.getLogger()
+
+    logger.addHandler(file_handler)
+    logger.addHandler(stdout_handler)
+
+
+if __name__ == "__main__":
+
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument("--k", type=int, required=True)
+    parser.add_argument("--data-path", type=Path, required=True)
+    parser.add_argument("--config-file", type=Path, default="config/default.yaml")
+    parser.add_argument("--kmeans-iterations", type=int, default=100)
+    parser.add_argument("--results-path", type=Path, default=None)
+    parser.add_argument("--load-existing-run-path", type=Path, default=None)
+    parser.add_argument("--cache-current-run-path", type=Path, default=None)
+
+    parser.add_argument("--verbose", action="store_true")
+
+    args = parser.parse_args()
+
+    set_up_logger(
+        args.results_path.parent / args.results_path.name.replace(".json", ".log"),
+    )
+
+    if args.verbose:
+        logging.getLogger().setLevel(logging.INFO)
+    else:
+        logging.getLogger().setLevel(logging.WARNING)
+
+    data = pd.read_csv(args.data_path)
+    X = data.values
+    logger.info(f"The data has the following shape: {X.shape}")
+
+    ilp = ExactKMeans(
+        X=X,
+        k=args.k,
+        config_file=args.config_file,
+        load_existing_run_path=args.load_existing_run_path,
+        cache_current_run_path=args.cache_current_run_path,
+        kmeans_iterations=args.kmeans_iterations,
+    )
+
+    start = time()
+    res = ilp.optimize()
+    ilp_time = time() - start
+
+    if args.results_path is not None:
+        args.results_path.parent.mkdir(parents=True, exist_ok=True)
+        model = res["model"]
+        res_eval = {
+            "version": ilp.ilp_version,
+            "time": ilp_time,
+            "initial_labels": res["initial_labels"],
+            "labels": res["labels"],
+            "objective": res["objective"],
+            "cluster_size_objectives": res["cluster_size_objectives"],
+            "best_cluster_sizes": res["best_cluster_sizes"],
+            "processed_cluster_sizes": res["processed_cluster_sizes"],
+            "changed_model_params": ilp.changed_model_params,
+            "changed_bound_params": ilp.changed_bound_model_params,
+            "optimal": model.Status == 2,
+            "git_hash": get_git_hash(),
+        }
+        for var_name, var in [
+            ("gap", "MIPGap"),
+            ("num_constraints", "NumConstrs"),
+            ("num_variables", "NumVars"),
+            ("upper_bound", "ObjVal"),
+            ("lower_bound", "ObjBound"),
+            ("solver_time", "Runtime"),
+        ]:
+            res_eval[var_name] = getattr(model, var)
+
+        with open(args.results_path, "w") as f:
+            json.dump(res_eval, f, indent=4, cls=JsonEncoder)
+
+        ilp.print_model(
+            args.results_path.parent, args.results_path.name.replace(".json", "")
+        )

exact_kmeans-0.1.0/exact_kmeans/callbacks.py

@@ -0,0 +1,60 @@
+import logging
+
+import gurobipy as gp
+import numpy as np
+from gurobipy import GRB
+
+from exact_kmeans.util import print_variables
+
+logger = logging.getLogger(__name__)
+
+
+def add_cuts(model: gp.Model, where: int, v: int, n: int, k: int) -> None:
+    if where == GRB.Callback.MIPNODE:
+        status = model.cbGet(GRB.Callback.MIPNODE_STATUS)
+        if status != GRB.OPTIMAL:
+            return
+        for i in range(v, n):
+            for j in range(i + 1, n):
+                for ll in range(v, k):
+                    zs = [
+                        model.getVarByName(f"z[{i},{j},{ll},{m}]") for m in range(v, n)
+                    ]
+                    relaxed_z = model.cbGetNodeRel(zs)  # type: ignore
+                    y = model.getVarByName(f"y[{i},{j},{ll}]")
+                    if not np.isclose(
+                        sum(relaxed_z), model.cbGetNodeRel(y), atol=0.001  # type: ignore
+                    ):
+                        logger.info(
+                            f"Add cut for z[{i},{j},{ll},:] ({sum(relaxed_z)}) "
+                            "and y[{i},{j},{ll}] ({model.cbGetNodeRel(y)})"
+                        )
+                        model.cbCut(gp.quicksum(zs) == y)  # type: ignore
+
+
+def variable_bounds(model: gp.Model, where: int) -> None:
+    if where in {GRB.Callback.MIPNODE, GRB.Callback.MIPSOL, GRB.Callback.MIP}:
+        for var in model.getVars():
+            # This does not work, the lower and upper bounds of the variables are never updated?
+            if var.LB != 0 or var.UB != 1:
+                print()
+                print(var, var.LB, var.UB)
+                print()
+
+
+def relax_callback(model: gp.Model, where: int) -> None:
+    if where == GRB.Callback.MIPNODE:
+        status = model.cbGet(GRB.Callback.MIPNODE_STATUS)
+        if status == GRB.OPTIMAL:
+            with open("relaxed-example.txt", "w") as of:
+                for txt in print_variables(
+                    model.getVars(), model.cbGetNodeRel(model.getVars())
+                ):
+                    of.write(txt)
+                # dd = {
+                #     var.VarName: val
+                #     for var, val in zip(
+                #         model.getVars(), model.cbGetNodeRel(model.getVars())
+                #     )
+                # }
+            model.terminate()

exact_kmeans-0.1.0/exact_kmeans/dynamic_program/__init__.py

@@ -0,0 +1,3 @@
+from exact_kmeans.dynamic_program.dp_plain import compute_bounds
+
+__all__ = ["compute_bounds"]

exact_kmeans-0.1.0/exact_kmeans/dynamic_program/dp_plain.py

@@ -0,0 +1,98 @@
+import math
+from typing import Dict
+
+import numpy as np
+
+
+def DP_init(n_points: int, k: int, lb: Dict[int, float]) -> np.ndarray:
+    # make array one dimension larger to avoid substracting 1 every time
+    r = np.zeros(shape=(n_points + 1, k + 1), dtype=float)
+
+    r[0][0] = 0
+    r[1][0] = math.inf
+    r[0][1] = math.inf
+
+    for covered in range(1, n_points + 1):
+        if covered in lb:
+            r[covered][1] = lb[covered]
+        else:
+            r[covered][1] = math.inf
+        r[covered][0] = math.inf
+
+    for clusters in range(2, k + 1):
+        r[0][clusters] = math.inf
+        r[1][clusters] = math.inf
+
+    # print(r)
+    return r
+
+
+def DP_recursion(n_points: int, k: int, lb: Dict[int, float], r: np.ndarray) -> None:
+    for covered in range(2, n_points + 1):
+        for clusters in range(2, k + 1):
+            max_size = min(covered - clusters + 1, n_points - k + 1)
+            # print(f"Covered: {covered}, Clusters: {clusters}, max_size= {max_size}")
+            min_curr = math.inf
+
+            for cluster_size in range(1, max_size + 1):
+                if cluster_size in lb:
+                    min_new = r[covered - cluster_size][clusters - 1] + lb[cluster_size]
+                else:
+                    min_new = math.inf
+
+                if min_new < min_curr:
+                    min_curr = min_new
+
+            r[covered][clusters] = min_curr
+
+
+def DP_recursion_print_part(
+    n_points: int, k: int, lb: Dict[int, float], r: np.ndarray
+) -> None:
+    partition = {(i, 1): [i] for i in range(0, n_points + 1)}
+
+    for covered in range(2, n_points + 1):
+        for clusters in range(2, k + 1):
+            max_size = min(covered - clusters + 1, n_points - k + 1)
+            # print(f"Covered: {covered}, Clusters: {clusters}, max_size= {max_size}")
+            min_curr = math.inf
+            min_size = 0
+
+            for cluster_size in range(1, max_size + 1):
+                if cluster_size in lb:
+                    min_new = r[covered - cluster_size][clusters - 1] + lb[cluster_size]
+                else:
+                    min_new = math.inf
+
+                if min_new < min_curr:
+                    min_curr = min_new
+                    min_size = cluster_size
+
+            r[covered][clusters] = min_curr
+            new_part = partition[(covered - min_size, clusters - 1)][:]
+            new_part.append(min_size)
+            partition.update({(covered, clusters): new_part})
+
+    for i in range(1, n_points + 1):
+        print(f"Number of points {i}:")
+        for j in range(1, min(k + 1, i + 1)):
+            curr = partition[(i, j)]
+            print(f"{curr} ", end="")
+        print("\n")
+
+
+def compute_bounds(
+    n_points: int, k: int, lb: Dict[int, float], print_part: bool = False
+) -> np.ndarray:
+    if n_points == 0 or k == 0:
+        raise ValueError(
+            f"Number of points (n={n_points}) "
+            f"and number of clusters (k={k}) must be greater than 0"
+        )
+    r = DP_init(n_points, k, lb)
+    if print_part:
+        DP_recursion_print_part(n_points, k, lb, r)
+    else:
+        DP_recursion(n_points, k, lb, r)
+
+    return r