hitspy 0.1.0__tar.gz

hitspy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kostas Florios
+
+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.

hitspy-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+global-include *.cpp *.hpp *.h

hitspy-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: hitspy
+Version: 0.1.0
+Summary: Fast OpenMP-parallelized discrete tabu search with pybind11 C++ bindings for maximum score estimator
+Author-email: Kostas Florios <cflorios@aueb.gr>
+License: MIT
+Project-URL: Homepage, https://github.com/kflorios/hitspy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Dynamic: license-file
+
+# hitspy
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**hitspy** is a high-performance Python package providing C++ implementation of discrete Tabu Search algorithm for maximum score estimation. Powered by **pybind11** and parallelized with **OpenMP**, `hitspy` accelerates Hyperplanes Intersection evaluation and search routines across large search spaces.
+
+---
+
+## Key Features
+
+- ⚡ **High Performance**: Core optimization routines written in C++ for maximum throughput.
+- 🚀 **Parallel Computing**: OpenMP multi-threading support for fast neighborhood evaluations.
+- 🐍 **Seamless Python API**: Native `numpy` array integration using `pybind11`.
+
+---
+
+## Installation
+
+### From Source (Locally)
+
+Download the main folder of the package, cd to it and provide
+in your preferred environment:
+
+```bash
+pip install -e .
+```
+---
+
+### Requirements
+Python 3.8 and above, MS Visual Studio 2019 and above
+
+## API Reference
+
+### `hitspy.run_tabu_search`
+
+Executes an OpenMP-accelerated discrete Tabu Search algorithm for maximum score estimator computation.
+
+```python
+hitspy.run_tabu_search(
+    X: numpy.ndarray,
+    y: numpy.ndarray,
+    b0: float,
+    d: float,
+    iSeed: int
+) -> numpy.ndarray
+```
+
+## Complete Example: Multi-Seed Benchmark (20 Random Starts)
+
+This benchmark demonstrates how to execute 20 distinct random restarts using `hitspy`, summarize overall solution quality, and compute selection frequency statistics for each attribute.
+
+```python
+import numpy as np
+import pandas as pd
+from hitspy import run_tabu_search
+
+# 1. Load and preprocess data
+X_raw = np.loadtxt("X.txt")
+y_raw = np.loadtxt("y.txt")
+
+X = X_raw[:, 1:]
+y = y_raw[:, 1].astype(int)
+X=np.transpose(X)
+X = np.ascontiguousarray(X, dtype=np.float64)
+
+# 2. Parameters
+b0 = -1.0
+d = 10000
+num_runs = 20
+
+# Generate 20 distinct random seeds
+np.random.seed(42)  # For reproducible seed generation
+seeds = np.random.randint(0, 1000000, size=num_runs)
+
+# 3. Storage for results
+results_list = []
+
+print("Starting 20 runs...")
+
+# 4. Run loop
+for i in range(num_runs):
+    print('run...:',i+1)
+    current_seed = int(seeds[i])
+
+    # Execute Tabu Search
+    #attrs, coeffs, score = run_tabu_search(X=X, y=y, b0=b0, d=d, iSeed=current_seed)
+    attrs, coeffs, score = run_tabu_search(X=X, y=y, b0=b0, d=d, iSeed=12345+i+1)
+
+    # hitspy returns 'attributes' as a 1D numpy array/list and 'score' / 'coeffs' as keys in the dict
+
+    # Save metrics
+    results_list.append(
+        {
+            "Run": i + 1,
+            "Seed": 12345+i+1,
+            "Score": score,
+            "Coeffs": coeffs,
+            "Attrs": attrs
+        }
+    )
+
+# 5. Combine into a single DataFrame
+results_df = pd.DataFrame(results_list)
+
+# 6. Display results table
+print(results_df.to_string(index=False))
+
+# 7. Summary statistics
+print("\n=== Summary Across 20 Runs ===")
+print("Best Score Found: ", results_df["Score"].max())
+print("Mean Score:       ", results_df["Score"].mean())
+print("Score Std Dev:    ", results_df["Score"].std(ddof=1))
+```
+
+## Acknowledgements 
+
+I would like to thank Dr. **Alexandros Louka** and Professor **Yannis Bilias** for their valuable help and the shared ideas for the development of HITSpy. The development of the HITSpy software was supported by the Hellenic Foundation for Research and Innovation (H.F.R.I.) under the '2nd Call for H.F.R.I. Research Projects to support Post-Doctoral Researchers' (Project Number: 902). 
+
+## Citation
+
+If you use `hitspy` in your research, please cite the underlying methodology papers:
+
+```bibtex
+@article{florios2025hits,
+  title={HITS: Hyperplanes intersection tabu search for maximum score estimation},
+  author={Florios, Kostas and Louka, Alexandros and Bilias, Yannis},
+  journal={SoftwareX},
+  volume={30},
+  pages={102164},
+  year={2025},
+  publisher={Elsevier}
+}
+
+@article{manski1975maximum,
+  title={Maximum score estimation of the stochastic utility model of choice},
+  author={Manski, Charles F},
+  journal={Journal of econometrics},
+  volume={3},
+  number={3},
+  pages={205--228},
+  year={1975},
+  publisher={Elsevier}
+}

hitspy-0.1.0/README.md

@@ -0,0 +1,143 @@
+# hitspy
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**hitspy** is a high-performance Python package providing C++ implementation of discrete Tabu Search algorithm for maximum score estimation. Powered by **pybind11** and parallelized with **OpenMP**, `hitspy` accelerates Hyperplanes Intersection evaluation and search routines across large search spaces.
+
+---
+
+## Key Features
+
+- ⚡ **High Performance**: Core optimization routines written in C++ for maximum throughput.
+- 🚀 **Parallel Computing**: OpenMP multi-threading support for fast neighborhood evaluations.
+- 🐍 **Seamless Python API**: Native `numpy` array integration using `pybind11`.
+
+---
+
+## Installation
+
+### From Source (Locally)
+
+Download the main folder of the package, cd to it and provide
+in your preferred environment:
+
+```bash
+pip install -e .
+```
+---
+
+### Requirements
+Python 3.8 and above, MS Visual Studio 2019 and above
+
+## API Reference
+
+### `hitspy.run_tabu_search`
+
+Executes an OpenMP-accelerated discrete Tabu Search algorithm for maximum score estimator computation.
+
+```python
+hitspy.run_tabu_search(
+    X: numpy.ndarray,
+    y: numpy.ndarray,
+    b0: float,
+    d: float,
+    iSeed: int
+) -> numpy.ndarray
+```
+
+## Complete Example: Multi-Seed Benchmark (20 Random Starts)
+
+This benchmark demonstrates how to execute 20 distinct random restarts using `hitspy`, summarize overall solution quality, and compute selection frequency statistics for each attribute.
+
+```python
+import numpy as np
+import pandas as pd
+from hitspy import run_tabu_search
+
+# 1. Load and preprocess data
+X_raw = np.loadtxt("X.txt")
+y_raw = np.loadtxt("y.txt")
+
+X = X_raw[:, 1:]
+y = y_raw[:, 1].astype(int)
+X=np.transpose(X)
+X = np.ascontiguousarray(X, dtype=np.float64)
+
+# 2. Parameters
+b0 = -1.0
+d = 10000
+num_runs = 20
+
+# Generate 20 distinct random seeds
+np.random.seed(42)  # For reproducible seed generation
+seeds = np.random.randint(0, 1000000, size=num_runs)
+
+# 3. Storage for results
+results_list = []
+
+print("Starting 20 runs...")
+
+# 4. Run loop
+for i in range(num_runs):
+    print('run...:',i+1)
+    current_seed = int(seeds[i])
+
+    # Execute Tabu Search
+    #attrs, coeffs, score = run_tabu_search(X=X, y=y, b0=b0, d=d, iSeed=current_seed)
+    attrs, coeffs, score = run_tabu_search(X=X, y=y, b0=b0, d=d, iSeed=12345+i+1)
+
+    # hitspy returns 'attributes' as a 1D numpy array/list and 'score' / 'coeffs' as keys in the dict
+
+    # Save metrics
+    results_list.append(
+        {
+            "Run": i + 1,
+            "Seed": 12345+i+1,
+            "Score": score,
+            "Coeffs": coeffs,
+            "Attrs": attrs
+        }
+    )
+
+# 5. Combine into a single DataFrame
+results_df = pd.DataFrame(results_list)
+
+# 6. Display results table
+print(results_df.to_string(index=False))
+
+# 7. Summary statistics
+print("\n=== Summary Across 20 Runs ===")
+print("Best Score Found: ", results_df["Score"].max())
+print("Mean Score:       ", results_df["Score"].mean())
+print("Score Std Dev:    ", results_df["Score"].std(ddof=1))
+```
+
+## Acknowledgements 
+
+I would like to thank Dr. **Alexandros Louka** and Professor **Yannis Bilias** for their valuable help and the shared ideas for the development of HITSpy. The development of the HITSpy software was supported by the Hellenic Foundation for Research and Innovation (H.F.R.I.) under the '2nd Call for H.F.R.I. Research Projects to support Post-Doctoral Researchers' (Project Number: 902). 
+
+## Citation
+
+If you use `hitspy` in your research, please cite the underlying methodology papers:
+
+```bibtex
+@article{florios2025hits,
+  title={HITS: Hyperplanes intersection tabu search for maximum score estimation},
+  author={Florios, Kostas and Louka, Alexandros and Bilias, Yannis},
+  journal={SoftwareX},
+  volume={30},
+  pages={102164},
+  year={2025},
+  publisher={Elsevier}
+}
+
+@article{manski1975maximum,
+  title={Maximum score estimation of the stochastic utility model of choice},
+  author={Manski, Charles F},
+  journal={Journal of econometrics},
+  volume={3},
+  number={3},
+  pages={205--228},
+  year={1975},
+  publisher={Elsevier}
+}

hitspy-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel", "pybind11>=2.10.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hitspy"
+version = "0.1.0"
+description = "Fast OpenMP-parallelized discrete tabu search with pybind11 C++ bindings for maximum score estimator"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Kostas Florios", email = "cflorios@aueb.gr" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=1.20.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/kflorios/hitspy"

hitspy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hitspy-0.1.0/setup.py

@@ -0,0 +1,45 @@
+import sys
+from setuptools import setup, Extension
+from setuptools.command.build_ext import build_ext
+
+class BuildExt(build_ext):
+    """Custom build extension to handle compiler-specific flags."""
+    def build_extensions(self):
+        compiler = self.compiler.compiler_type
+        for ext in self.extensions:
+            if compiler == "msvc":
+                ext.extra_compile_args = ["/O2", "/openmp", "/std:c++14"]
+            else:
+                ext.extra_compile_args = ["-O3", "-fopenmp", "-std=c++14"]
+                ext.extra_link_args = ["-fopenmp"]
+        super().build_extensions()
+
+class get_pybind_include:
+    """Helper class to delay importing pybind11 until build time."""
+    def __str__(self):
+        import pybind11
+        return pybind11.get_include()
+
+ext_modules = [
+    Extension(
+        "hitspy._hitspy",
+        sources=[
+            "src/hitspy/tabu_bindings.cpp",
+            "src/hitspy/tabu_api.cpp",
+            "src/hitspy/bsort.cpp",
+            "src/hitspy/evaluate_neighbourhood.cpp",
+            "src/hitspy/EvaluateScore1.cpp",
+            "src/hitspy/gelim.cpp",
+        ],
+        include_dirs=[
+            get_pybind_include(),
+            "src/hitspy",
+        ],
+        language="c++",
+    )
+]
+
+setup(
+    ext_modules=ext_modules,
+    cmdclass={"build_ext": BuildExt},
+)

hitspy-0.1.0/src/hitspy/EvaluateScore1.cpp

@@ -0,0 +1,43 @@
+#include "tabu_search.hpp"
+
+// -----------------------------------------------------------------------------
+// EvaluateScore1
+//   sump(i) = sum_j beta(j)*Z(j+1,i) + b0*Z(1,i)
+//   firep(i) = sign(sump(i))
+//   sfire = sum_i data_y(i)*firep(i)
+//   h = (1 + sfire/T) / 2
+// -----------------------------------------------------------------------------
+void EvaluateScore1(
+	const double w[pmax],
+	int T,
+	int p,
+	double &h,
+	const double Z[pmax][Tmax],
+	double b0,
+	const int data_y[Tmax]
+)
+{
+	double beta[pmax];
+	int firep[Tmax];
+
+	for (int j = 0; j < p; ++j)
+		beta[j] = w[j];
+
+	int sfire = 0;
+
+	for (int i = 0; i < T; ++i)
+	{
+		double s = 0.0;
+
+		for (int j = 0; j < p; ++j)
+			s += beta[j] * Z[j + 1][i];
+
+		s += b0 * Z[0][i];
+
+		firep[i] = (s >= 0.0 ? 1 : -1);
+
+		sfire += data_y[i] * firep[i];
+	}
+
+	h = (1.0 + double(sfire) / double(T)) * 0.5;
+}

hitspy-0.1.0/src/hitspy/__init__.py

@@ -0,0 +1,4 @@
+from ._hitspy import run_tabu_search
+
+__version__ = "0.1.0"
+__all__ = ["run_tabu_search"]

hitspy-0.1.0/src/hitspy/bsort.cpp

@@ -0,0 +1,26 @@
+#include "tabu_search.hpp"
+
+// -----------------------------------------------------------------------------
+// bsort: sort nat[0..np-1] into snat[0..np-1] in increasing order
+// Fortran original:
+//   do i=1,np
+//   do i=1,np-1
+//      do j=i+1,np
+// -----------------------------------------------------------------------------
+void bsort(int np, const int nat[], int snat[])
+{
+    // copy input
+    for (int i = 0; i < np; ++i)
+        snat[i] = nat[i];
+
+    // simple bubble/selection hybrid as in Fortran
+    for (int i = 0; i < np - 1; ++i) {
+        for (int j = i + 1; j < np; ++j) {
+            if (snat[i] > snat[j]) {
+                int tmp = snat[i];
+                snat[i] = snat[j];
+                snat[j] = tmp;
+            }
+        }
+    }
+}

hitspy-0.1.0/src/hitspy/evaluate_neighbourhood.cpp

@@ -0,0 +1,159 @@
+#include "tabu_search.hpp"
+
+// -----------------------------------------------------------------------------
+// evaluate_neighbourhood
+// 0-based C++ translation of the Fortran routine.
+//
+// This routine evaluates all possible substitutions of attribute i_idx
+// with every candidate id[j], j = 0..n-1, except those already in natsol.
+//
+// It performs:
+//   - triviality check
+//   - tabu check
+//   - local system solve (gelim)
+//   - bounds check
+//   - score computation (EvaluateScore1)
+//   - tracking of best dz_i and MaxScoreEver_i
+//
+// This version is called inside an OpenMP parallel loop in main.cpp.
+// -----------------------------------------------------------------------------
+void evaluate_neighbourhood(
+	int i_idx,
+	int p,
+	int n,
+	const int natsol[pmax],
+	const int Mat[pmax][Itmax],
+	const double Z[pmax][Tmax],
+	const double y[Tmax],
+	const int id[Tmax],
+	const double xlbound[pmax],
+	const double xubound[pmax],
+	double b0,
+	double MaxScore,
+	int ntenure,
+	int csubstitutionstotal,
+	int T,
+	double &dz_i,
+	int natcur_i[pmax],
+	double &MaxScoreEver_i,
+	int natever_i[pmax],
+	int &row_i,
+	int &cbd_i,
+	int &cinfsd_i,
+	const int data_y[Tmax]
+)
+{
+	row_i = 0;
+	cbd_i = 0;
+	cinfsd_i = 0;
+	dz_i = -1.0;
+	MaxScoreEver_i = -1.0e99;
+
+	int nat_local[pmax];
+	int snat_local[pmax];
+	double b_local[pmax];
+	double A_local[pmax][pmax];
+	double bb_local[pmax];
+	double x_local[pmax];
+
+	for (int j = 0; j < n; ++j)
+	{
+		bool trivial = false;
+		for (int iii = 0; iii < p; ++iii)
+		{
+			if (natsol[iii] == id[j])
+			{
+				trivial = true;
+				break;
+			}
+		}
+		if (trivial)
+			continue;
+
+		row_i++;
+
+		for (int iii = 0; iii < p; ++iii)
+			nat_local[iii] = (iii == i_idx ? id[j] : natsol[iii]);
+
+		bsort(p, nat_local, snat_local);
+
+		bool tabu = false;
+		for (int k = 0; k < ntenure; ++k)
+		{
+			int ct = 0;
+			for (int iii = 0; iii < p; ++iii)
+			{
+				if (snat_local[iii] == Mat[iii][csubstitutionstotal + k])
+					ct++;
+			}
+			if (ct == p)
+			{
+				tabu = true;
+				break;
+			}
+		}
+		if (tabu)
+			continue;
+
+		for (int iii = 0; iii < p; ++iii)
+			b_local[iii] = (y[nat_local[iii]] >= 0.0 ? 1.0 : 0.0);
+
+		for (int iii = 0; iii < p; ++iii)
+		{
+			for (int jjj = 0; jjj < p; ++jjj)
+			{
+				A_local[jjj][iii] =
+					(1.0 - 2.0 * b_local[jjj]) *
+					Z[iii + 1][id[nat_local[jjj]]];
+			}
+		}
+
+		for (int iii = 0; iii < p; ++iii)
+		{
+			bb_local[iii] =
+				b0 * (-1.0 + 2.0 * b_local[iii]) *
+				Z[0][id[nat_local[iii]]];
+		}
+
+		gelim(p, A_local, bb_local, x_local);
+
+		bool infeasible = false;
+		for (int iii = 0; iii < p; ++iii)
+		{
+			if (x_local[iii] < xlbound[iii] ||
+				x_local[iii] > xubound[iii])
+			{
+				cinfsd_i++;
+				infeasible = true;
+				break;
+			}
+		}
+		if (infeasible)
+			continue;
+
+		double score1;
+		EvaluateScore1(
+			x_local, T, p, score1,
+			Z, b0, data_y
+		);
+
+		double dz = score1 - MaxScore;
+
+		if (dz > 0.0)
+			cbd_i++;
+
+		if (score1 > MaxScoreEver_i)
+		{
+			MaxScoreEver_i = score1;
+			for (int iii = 0; iii < p; ++iii)
+				natever_i[iii] = nat_local[iii];
+		}
+
+		if (dz > dz_i)
+		{
+			dz_i = dz;
+			for (int iii = 0; iii < p; ++iii)
+				natcur_i[iii] = nat_local[iii];
+		}
+	}
+}

hitspy-0.1.0/src/hitspy/gelim.cpp

@@ -0,0 +1,60 @@
+#include "tabu_search.hpp"
+
+// -----------------------------------------------------------------------------
+// gelim: Gaussian elimination (Fortran version preserved exactly)
+// 0-based C++ translation of the Fortran routine:
+//
+//   do i=1,np-1
+//      do j=i+1,np
+//         p = sk(j,i)/sk(i,i)
+//         r1(j) = r1(j) - p*r1(i)
+//         do k=1,np
+//             sk(j,k) = sk(j,k) - p*sk(i,k)
+//         enddo
+//      enddo
+//   enddo
+//
+//   Back substitution, then restore original sk and r1
+// -----------------------------------------------------------------------------
+void gelim(int np,
+           double sk[pmax][pmax],
+           double r1[pmax],
+           double u[pmax])
+{
+    double bsk[pmax][pmax];
+    double br1[pmax];
+
+    // Save original sk and r1 (Fortran behavior)
+    for (int i = 0; i < np; ++i) {
+        br1[i] = r1[i];
+        for (int j = 0; j < np; ++j)
+            bsk[i][j] = sk[i][j];
+    }
+
+    // Forward elimination
+    for (int i = 0; i < np - 1; ++i) {
+        for (int j = i + 1; j < np; ++j) {
+            double p = sk[j][i] / sk[i][i];
+            r1[j] -= p * r1[i];
+            for (int k = 0; k < np; ++k)
+                sk[j][k] -= p * sk[i][k];
+        }
+    }
+
+    // Back substitution
+    for (int l = np - 1; l >= 0; --l) {
+        u[l] = r1[l] / sk[l][l];
+        for (int j = l - 1; j >= 0; --j) {
+            double p1 = sk[j][l] / sk[l][l];
+            sk[j][l] = 0.0;
+            r1[j] -= p1 * r1[l];
+        }
+    }
+
+    // Restore original sk and r1 (Fortran semantics)
+    for (int i = 0; i < np; ++i) {
+        r1[i] = br1[i];
+        for (int j = 0; j < np; ++j)
+            sk[i][j] = bsk[i][j];
+    }
+}

hitspy-0.1.0/src/hitspy/tabu_api.cpp

@@ -0,0 +1,274 @@
+#include "tabu_search.hpp"
+
+// Portable RNG
+static inline double get_random() {
+    return double(rand()) / double(RAND_MAX);
+}
+
+// -----------------------------------------------------------------------------
+// Public API entry point callable from Python (pybind11)
+// -----------------------------------------------------------------------------
+extern "C" int run_tabu_search(
+    double* X,
+    int T,
+    int p_in,
+    int* y_in,
+    double b0,
+    double d,
+    int iSeed,                 // <-- NEW ARGUMENT
+    int* out_attributes,
+    double* out_coeffs,
+    double* out_score
+)
+{
+	srand(iSeed);
+	//srand(12345);   // or use time(NULL) if you want nondeterministic runs
+	//srand((unsigned)time(NULL)); //If you want randomness each run:	
+
+    int p = p_in - 1;   // number of attributes (excluding intercept)
+
+    static double Z[pmax][Tmax];   // now pmax and Tmax are known
+    static double y[Tmax];
+    static int data_y[Tmax];
+    static int id[Tmax];
+
+    if (p <= 0 || p > pmax)
+        return -10;
+    if (T <= 0 || T > Tmax)
+        return -11;
+
+    // Core data
+    /*double Z[pmax][Tmax];
+    double y[Tmax];
+    int data_y[Tmax];
+    int id[Tmax];*/
+
+    // Working arrays
+    double A[pmax][pmax], b[pmax], bb[pmax];
+    double mA[pmax][pmax], mb[pmax], bmb[pmax];
+    double x[pmax], score1, MaxScore0, MaxScore, MaxScoreEver;
+    double Af[pmax][pmax], bf[pmax], bbf[pmax];
+    double ArgMax[pmax];
+
+    int nat[pmax], natsol[pmax], natcur[pmax], natever[pmax];
+    int Mat[pmax][Itmax], snat[pmax], snatsol[pmax];
+
+    double xlbound[pmax], xubound[pmax];
+
+    int ntenure, niterover, niternotimproved;
+    int csubstitutionstotal, cbdsubseq, cbd, cinfsd;
+    double dzmax;
+    int row;
+
+    // -------------------------------------------------------------------------
+    // Copy inputs into local arrays
+    // -------------------------------------------------------------------------
+    for (int i = 0; i < T; ++i) {
+        id[i] = i;
+        data_y[i] = y_in[i];
+        y[i] = double(y_in[i]);
+    }
+
+    for (int j = 0; j < p_in; ++j) {
+        for (int i = 0; i < T; ++i) {
+            Z[j][i] = X[j*T + i];
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Bounds (you can later tie these to d if desired)
+    // -------------------------------------------------------------------------
+    for (int j = 0; j < p; ++j) {
+        xlbound[j] = -d;
+        xubound[j] =  d;
+    }
+
+    // -------------------------------------------------------------------------
+    // Initial nat (first p indices)
+    // -------------------------------------------------------------------------
+    /*for (int j = 0; j < p; ++j)
+        nat[j] = j;*/
+	for (int j = 0; j < p; ++j) {
+    double rr = get_random();
+    nat[j] = int(std::floor(rr * T));
+}
+    printf("Initial nat: ");
+	for (int j = 0; j < p; ++j) printf("%d ", nat[j]);
+	printf("\n");
+
+
+    bsort(p, nat, snat);
+    for (int j = 0; j < p; ++j)
+        natsol[j] = snat[j];
+
+    // -------------------------------------------------------------------------
+    // Build mb
+    // -------------------------------------------------------------------------
+    for (int j = 0; j < p; ++j)
+        mb[j] = (y[id[natsol[j]]] >= 0.0 ? 1.0 : 0.0);
+
+    // -------------------------------------------------------------------------
+    // Build mA and bmb
+    // -------------------------------------------------------------------------
+    for (int j = 0; j < p; ++j)
+        for (int i = 0; i < p; ++i)
+            mA[i][j] = (1.0 - 2.0 * mb[i]) * Z[j + 1][ id[natsol[i]] ];
+
+    for (int i = 0; i < p; ++i)
+        bmb[i] = b0 * (-1.0 + 2.0 * mb[i]) * Z[0][ id[natsol[i]] ];
+
+    // -------------------------------------------------------------------------
+    // Solve initial system
+    // -------------------------------------------------------------------------
+    gelim(p, mA, bmb, x);
+
+    for (int i = 0; i < p; ++i) {
+        if (x[i] < xlbound[i] || x[i] > xubound[i]) {
+            return -2; // infeasible initial solution
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Evaluate initial score
+    // -------------------------------------------------------------------------
+    EvaluateScore1(
+        x, T, p, score1,
+        Z, b0, data_y
+    );
+    MaxScore0 = score1;
+    MaxScore = MaxScore0;
+    MaxScoreEver = MaxScore0;
+
+    // -------------------------------------------------------------------------
+    // Tabu parameters
+    // -------------------------------------------------------------------------
+    ntenure = 200;
+    niterover = 200;
+    niternotimproved = 200;
+
+    for (int j = 0; j < p; ++j)
+        for (int i = 0; i < ntenure; ++i)
+            Mat[j][i] = -1;
+
+    csubstitutionstotal = 0;
+    cbdsubseq = 0;
+
+    // -------------------------------------------------------------------------
+    // Main tabu loop
+    // -------------------------------------------------------------------------
+    while (true) {
+
+        cbd = 0;
+        cinfsd = 0;
+        dzmax = -1.0;
+        row = 0;
+
+        bsort(p, natsol, snatsol);
+        for (int i = 0; i < p; ++i)
+            natsol[i] = snatsol[i];
+
+        for (int i = 0; i < p; ++i)
+            b[i] = (y[id[natsol[i]]] >= 0.0 ? 1.0 : 0.0);
+
+        for (int j = 0; j < p; ++j)
+            for (int i = 0; i < p; ++i)
+                A[i][j] = (1.0 - 2.0 * b[i]) * Z[j + 1][ id[natsol[i]] ];
+
+        for (int i = 0; i < p; ++i)
+            bb[i] = b0 * (-1.0 + 2.0 * b[i]) * Z[0][ id[natsol[i]] ];
+
+        int row_i_arr[pmax];
+        int cbd_i_arr[pmax];
+        int cinfsd_i_arr[pmax];
+        double dz_i_arr[pmax];
+        double MaxScoreEver_i_arr[pmax];
+        int natcur_i_arr[pmax][pmax];
+        int natever_i_arr[pmax][pmax];
+
+        #pragma omp parallel for default(shared)
+        for (int i = 0; i < p; ++i) {
+            evaluate_neighbourhood(
+                i, p, T,
+                natsol, Mat,
+                Z, y, id,
+                xlbound, xubound,
+                b0, MaxScore,
+                ntenure, csubstitutionstotal, T,
+                dz_i_arr[i], natcur_i_arr[i],
+                MaxScoreEver_i_arr[i], natever_i_arr[i],
+                row_i_arr[i], cbd_i_arr[i], cinfsd_i_arr[i],
+                data_y
+            );
+        }
+
+        for (int i = 0; i < p; ++i) {
+            row += row_i_arr[i];
+            cbd += cbd_i_arr[i];
+            cinfsd += cinfsd_i_arr[i];
+
+            if (MaxScoreEver_i_arr[i] > MaxScoreEver) {
+                MaxScoreEver = MaxScoreEver_i_arr[i];
+                for (int j = 0; j < p; ++j)
+                    natever[j] = natever_i_arr[i][j];
+            }
+
+            if (dz_i_arr[i] > dzmax) {
+                dzmax = dz_i_arr[i];
+                for (int j = 0; j < p; ++j)
+                    natcur[j] = natcur_i_arr[i][j];
+            }
+        }
+
+        csubstitutionstotal++;
+
+        if (cbd == 0)
+            cbdsubseq++;
+
+        if (csubstitutionstotal == niterover ||
+            cbdsubseq == niternotimproved)
+            break;
+
+        for (int j = 0; j < p; ++j)
+            natsol[j] = natcur[j];
+
+        MaxScore += dzmax;
+
+        bsort(p, natsol, snatsol);
+        for (int j = 0; j < p; ++j)
+            Mat[j][ntenure + csubstitutionstotal] = snatsol[j];
+
+		printf("iteration...%d...:",csubstitutionstotal);
+		printf("current natsol: ");
+		for (int j = 0; j < p; ++j) printf("%d ", natsol[j]);
+		printf("\n");
+		
+    }
+
+    // -------------------------------------------------------------------------
+    // Final evaluation
+    // -------------------------------------------------------------------------
+    for (int j = 0; j < p; ++j)
+        bf[j] = (y[id[natever[j]]] >= 0.0 ? 1.0 : 0.0);
+
+    for (int j = 0; j < p; ++j)
+        for (int l = 0; l < p; ++l)
+            Af[l][j] = (1.0 - 2.0 * bf[l]) * Z[j + 1][ id[natever[l]] ];
+
+    for (int j = 0; j < p; ++j)
+        bbf[j] = b0 * (-1.0 + 2.0 * bf[j]) * Z[0][ id[natever[j]] ];
+
+    gelim(p, Af, bbf, x);
+    EvaluateScore1(
+        x, T, p, score1,
+        Z, b0, data_y
+    );
+
+    for (int j = 0; j < p; ++j) {
+        out_attributes[j] = natever[j];
+        out_coeffs[j] = x[j];
+    }
+
+    *out_score = score1;
+
+    return 0;
+}

hitspy-0.1.0/src/hitspy/tabu_bindings.cpp

@@ -0,0 +1,86 @@
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+#include "tabu_search.hpp"
+
+extern "C" int run_tabu_search(
+    double* X,
+    int T,
+    int p_in,
+    int* y_in,
+    double b0,
+    double d,
+    int iSeed,                 // <-- NEW ARGUMENT
+    int* out_attributes,
+    double* out_coeffs,
+    double* out_score
+);
+
+namespace py = pybind11;
+
+py::tuple py_run_tabu_search(py::array_t<double> X,
+                             py::array_t<int> y,
+                             double b0,
+                             double d,
+                             int iSeed)
+{
+    if (X.ndim() != 2)
+        throw std::runtime_error("X must be 2D (p_in x T)");
+    if (y.ndim() != 1)
+        throw std::runtime_error("y must be 1D (T,)");
+
+    int p_in = static_cast<int>(X.shape(0));
+    int T    = static_cast<int>(X.shape(1));
+
+    if (y.shape(0) != T)
+        throw std::runtime_error("y length must match X.shape[1]");
+
+    auto X_buf = X.request();
+    auto y_buf = y.request();
+
+    double* X_ptr = static_cast<double*>(X_buf.ptr);
+    int*    y_ptr = static_cast<int*>(y_buf.ptr);
+
+    int p = p_in - 1;
+    if (p <= 0 || p > pmax)
+        throw std::runtime_error("p_in-1 must be in [1, pmax]");
+
+    py::array_t<int>    attrs({p});
+    py::array_t<double> coeffs({p});
+    double score = 0.0;
+
+    auto attrs_buf   = attrs.request();
+    auto coeffs_buf  = coeffs.request();
+
+    int*    attrs_ptr  = static_cast<int*>(attrs_buf.ptr);
+    double* coeffs_ptr = static_cast<double*>(coeffs_buf.ptr);
+
+int ret = run_tabu_search(
+    X_ptr,
+    T,
+    p_in,
+    y_ptr,
+    b0,
+    d,
+    iSeed,                 // <-- pass seed
+    attrs_ptr,
+    coeffs_ptr,
+    &score
+);
+
+    if (ret != 0)
+        throw std::runtime_error("run_tabu_search failed with code " + std::to_string(ret));
+
+    return py::make_tuple(attrs, coeffs, score);
+}
+
+PYBIND11_MODULE(_hitspy, m) {
+    m.doc() = "Pybind11 bindings for hitspy discrete tabu search";
+
+    m.def("run_tabu_search", &py_run_tabu_search,
+          py::arg("X"),
+          py::arg("y"),
+          py::arg("b0"),
+          py::arg("d"),
+          py::arg("iSeed"),
+          "Run discrete tabu search with user-specified RNG seed.");
+}

hitspy-0.1.0/src/hitspy/tabu_search.hpp

@@ -0,0 +1,69 @@
+#ifndef TABU_SEARCH_HPP
+#define TABU_SEARCH_HPP
+
+#include <cstdio>
+#include <cstdlib>
+#include <cmath>
+#include <cstring>
+#include <algorithm>
+#include <omp.h>
+
+// -----------------------------------------------------------------------------
+// Global constants (Fortran PARAMETER)
+// -----------------------------------------------------------------------------
+static const int Tmax = 50000;
+static const int pmax = 20;
+static const int Itmax = 1000;
+
+// -----------------------------------------------------------------------------
+// Function prototypes
+// -----------------------------------------------------------------------------
+
+// bsort: sort nat[0..np-1] into snat[0..np-1]
+void bsort(int np, const int nat[], int snat[]);
+
+// Gaussian elimination (Fortran gelim)
+void gelim(int np,
+           double sk[pmax][pmax],
+           double r1[pmax],
+           double u[pmax]);
+
+// EvaluateScore1: compute score h
+void EvaluateScore1(
+    const double w[pmax],
+    int T,
+    int p,
+    double &h,
+    const double Z[pmax][Tmax],
+    double b0,
+    const int data_y[Tmax]
+);
+
+// evaluate_neighbourhood: OpenMP-parallelized neighborhood evaluation
+void evaluate_neighbourhood(
+    int i_idx,
+    int p,
+    int n,
+    const int natsol[pmax],
+    const int Mat[pmax][Itmax],
+    const double Z[pmax][Tmax],
+    const double y[Tmax],
+    const int id[Tmax],
+    const double xlbound[pmax],
+    const double xubound[pmax],
+    double b0,
+    double MaxScore,
+    int ntenure,
+    int csubstitutionstotal,
+    int T,
+    double &dz_i,
+    int natcur_i[pmax],
+    double &MaxScoreEver_i,
+    int natever_i[pmax],
+    int &row_i,
+    int &cbd_i,
+    int &cinfsd_i,
+    const int data_y[Tmax]
+);
+
+#endif // TABU_SEARCH_HPP

hitspy-0.1.0/src/hitspy.egg-info/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: hitspy
+Version: 0.1.0
+Summary: Fast OpenMP-parallelized discrete tabu search with pybind11 C++ bindings for maximum score estimator
+Author-email: Kostas Florios <cflorios@aueb.gr>
+License: MIT
+Project-URL: Homepage, https://github.com/kflorios/hitspy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Dynamic: license-file
+
+# hitspy
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**hitspy** is a high-performance Python package providing C++ implementation of discrete Tabu Search algorithm for maximum score estimation. Powered by **pybind11** and parallelized with **OpenMP**, `hitspy` accelerates Hyperplanes Intersection evaluation and search routines across large search spaces.
+
+---
+
+## Key Features
+
+- ⚡ **High Performance**: Core optimization routines written in C++ for maximum throughput.
+- 🚀 **Parallel Computing**: OpenMP multi-threading support for fast neighborhood evaluations.
+- 🐍 **Seamless Python API**: Native `numpy` array integration using `pybind11`.
+
+---
+
+## Installation
+
+### From Source (Locally)
+
+Download the main folder of the package, cd to it and provide
+in your preferred environment:
+
+```bash
+pip install -e .
+```
+---
+
+### Requirements
+Python 3.8 and above, MS Visual Studio 2019 and above
+
+## API Reference
+
+### `hitspy.run_tabu_search`
+
+Executes an OpenMP-accelerated discrete Tabu Search algorithm for maximum score estimator computation.
+
+```python
+hitspy.run_tabu_search(
+    X: numpy.ndarray,
+    y: numpy.ndarray,
+    b0: float,
+    d: float,
+    iSeed: int
+) -> numpy.ndarray
+```
+
+## Complete Example: Multi-Seed Benchmark (20 Random Starts)
+
+This benchmark demonstrates how to execute 20 distinct random restarts using `hitspy`, summarize overall solution quality, and compute selection frequency statistics for each attribute.
+
+```python
+import numpy as np
+import pandas as pd
+from hitspy import run_tabu_search
+
+# 1. Load and preprocess data
+X_raw = np.loadtxt("X.txt")
+y_raw = np.loadtxt("y.txt")
+
+X = X_raw[:, 1:]
+y = y_raw[:, 1].astype(int)
+X=np.transpose(X)
+X = np.ascontiguousarray(X, dtype=np.float64)
+
+# 2. Parameters
+b0 = -1.0
+d = 10000
+num_runs = 20
+
+# Generate 20 distinct random seeds
+np.random.seed(42)  # For reproducible seed generation
+seeds = np.random.randint(0, 1000000, size=num_runs)
+
+# 3. Storage for results
+results_list = []
+
+print("Starting 20 runs...")
+
+# 4. Run loop
+for i in range(num_runs):
+    print('run...:',i+1)
+    current_seed = int(seeds[i])
+
+    # Execute Tabu Search
+    #attrs, coeffs, score = run_tabu_search(X=X, y=y, b0=b0, d=d, iSeed=current_seed)
+    attrs, coeffs, score = run_tabu_search(X=X, y=y, b0=b0, d=d, iSeed=12345+i+1)
+
+    # hitspy returns 'attributes' as a 1D numpy array/list and 'score' / 'coeffs' as keys in the dict
+
+    # Save metrics
+    results_list.append(
+        {
+            "Run": i + 1,
+            "Seed": 12345+i+1,
+            "Score": score,
+            "Coeffs": coeffs,
+            "Attrs": attrs
+        }
+    )
+
+# 5. Combine into a single DataFrame
+results_df = pd.DataFrame(results_list)
+
+# 6. Display results table
+print(results_df.to_string(index=False))
+
+# 7. Summary statistics
+print("\n=== Summary Across 20 Runs ===")
+print("Best Score Found: ", results_df["Score"].max())
+print("Mean Score:       ", results_df["Score"].mean())
+print("Score Std Dev:    ", results_df["Score"].std(ddof=1))
+```
+
+## Acknowledgements 
+
+I would like to thank Dr. **Alexandros Louka** and Professor **Yannis Bilias** for their valuable help and the shared ideas for the development of HITSpy. The development of the HITSpy software was supported by the Hellenic Foundation for Research and Innovation (H.F.R.I.) under the '2nd Call for H.F.R.I. Research Projects to support Post-Doctoral Researchers' (Project Number: 902). 
+
+## Citation
+
+If you use `hitspy` in your research, please cite the underlying methodology papers:
+
+```bibtex
+@article{florios2025hits,
+  title={HITS: Hyperplanes intersection tabu search for maximum score estimation},
+  author={Florios, Kostas and Louka, Alexandros and Bilias, Yannis},
+  journal={SoftwareX},
+  volume={30},
+  pages={102164},
+  year={2025},
+  publisher={Elsevier}
+}
+
+@article{manski1975maximum,
+  title={Maximum score estimation of the stochastic utility model of choice},
+  author={Manski, Charles F},
+  journal={Journal of econometrics},
+  volume={3},
+  number={3},
+  pages={205--228},
+  year={1975},
+  publisher={Elsevier}
+}

hitspy-0.1.0/src/hitspy.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+src/hitspy/EvaluateScore1.cpp
+src/hitspy/bsort.cpp
+src/hitspy/evaluate_neighbourhood.cpp
+src/hitspy/gelim.cpp
+src/hitspy/tabu_api.cpp
+src/hitspy/tabu_bindings.cpp
+src/hitspy/EvaluateScore1.cpp
+src/hitspy/__init__.py
+src/hitspy/bsort.cpp
+src/hitspy/evaluate_neighbourhood.cpp
+src/hitspy/gelim.cpp
+src/hitspy/tabu_api.cpp
+src/hitspy/tabu_bindings.cpp
+src/hitspy/tabu_search.hpp
+src/hitspy.egg-info/PKG-INFO
+src/hitspy.egg-info/SOURCES.txt
+src/hitspy.egg-info/dependency_links.txt
+src/hitspy.egg-info/requires.txt
+src/hitspy.egg-info/top_level.txt
+tests/test_tabu.py

hitspy-0.1.0/src/hitspy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hitspy-0.1.0/src/hitspy.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.20.0

hitspy-0.1.0/src/hitspy.egg-info/top_level.txt

@@ -0,0 +1 @@
+hitspy

hitspy-0.1.0/tests/test_tabu.py

@@ -0,0 +1 @@
+