hoptimal 0.1.0__tar.gz

hoptimal-0.1.0/.dockerignore

@@ -0,0 +1,26 @@
+# Build artifacts — rebuilt inside the image
+build/
+**/__pycache__/
+*.so
+*.pyd
+*.o
+*.a
+
+# Local logs / scratch captured during the Windows dev session
+logs*.txt
+test_results.txt
+
+# Benchmark outputs (regenerated)
+benchmarks/python/results/*.json
+
+# VCS / editor
+.git/
+.gitignore
+.vs/
+.vscode/
+.idea/
+
+# Python packaging cruft
+*.egg-info/
+dist/
+.pytest_cache/

hoptimal-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:   # allow manual runs
+  schedule:
+    - cron: "0 6 * * 1"   # weekly Monday 06:00 UTC — runs the heavy DL job
+
+jobs:
+  # ── Core + classic ML integrations ──────────────────────────────────────────
+  # Reuses the project Dockerfile so CI and local `docker build` are identical.
+  # The `integrations` stage builds the C++ core, runs all 130 tests, builds the
+  # pybind11 module, and runs the sklearn/xgboost/lightgbm/catboost smoke tests.
+  build-and-test:
+    name: build + test (core + integrations)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build and test via Docker (target=integrations)
+        run: docker build --target integrations -t hoptimal:ci .
+
+  # ── Deep-learning integrations (heavy; weekly + manual only) ─────────────────
+  # torch + tensorflow + jax are multi-GB, so this doesn't gate every push.
+  deep-learning:
+    name: deep-learning integrations (torch / jax / tensorflow)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/lib/android || true
+
+      - name: Build and test via Docker (target=dl)
+        run: docker build --target dl -t hoptimal:dl .

hoptimal-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,86 @@
+name: release
+
+# Builds wheels for Linux/macOS/Windows + an sdist, then publishes to PyPI.
+# Triggers when you publish a GitHub Release (recommended), or manually.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  # ── Build binary wheels on every platform ────────────────────────────────────
+  wheels:
+    name: wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # macos-14 (Apple Silicon) cross-builds BOTH arm64 and x86_64 via
+        # CIBW_ARCHS_MACOS below, so a separate macos-13 (Intel) runner would
+        # only produce duplicate wheels — and those Intel runners are queue-
+        # constrained as GitHub winds them down. One macOS runner covers both.
+        os: [ubuntu-latest, windows-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21
+        env:
+          # Skip PyPy and musllinux to keep the matrix lean; add back if wanted.
+          CIBW_SKIP: "pp* *-musllinux_*"
+          # 64-bit only — the C++20 core has no reason to ship 32-bit wheels,
+          # and the 32-bit manylinux/Windows images use an older toolchain.
+          CIBW_ARCHS_LINUX: x86_64
+          CIBW_ARCHS_WINDOWS: AMD64
+          CIBW_ARCHS_MACOS: "x86_64 arm64"
+          # libc++ marks std::variant/std::visit "unavailable" below macOS 10.13,
+          # which this code uses. Raise the x86_64 deployment target (cibuildwheel
+          # clamps arm64 to its 11.0 minimum automatically).
+          CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET=10.13
+          # C++20 needs a modern toolchain — manylinux2014's GCC 10 is too old
+          # for parts of the standard library, so build on the GCC 12 image.
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          # Surface the real CMake/compiler error if a build fails.
+          CIBW_BUILD_VERBOSITY: "1"
+          # Smoke-test each built wheel actually imports + runs.
+          CIBW_TEST_REQUIRES: numpy
+          CIBW_TEST_COMMAND: >-
+            python -c "import hoptimal; s = hoptimal.create_study();
+            print('hoptimal', getattr(hoptimal, '__version__', 'ok'))"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  # ── Build the source distribution ────────────────────────────────────────────
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: ./dist/*.tar.gz
+
+  # ── Publish to PyPI via Trusted Publishing (OIDC, no API tokens) ─────────────
+  publish:
+    name: publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    # Only publish for real releases, not manual dry-runs.
+    if: github.event_name == 'release'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hoptimal
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

hoptimal-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Build artifacts
+build/
+dist/
+*.so
+*.pyd
+*.o
+*.a
+*.egg-info/
+
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+.ipynb_checkpoints/
+
+# Local logs / scratch from the dev session
+logs*.txt
+test_results.txt
+
+# Benchmark run outputs (regenerated; commit curated results only)
+benchmarks/python/results/*.json
+
+# Planning / design docs kept outside the public repo.
+PORTFOLIO_PLAN.md
+hoptimal_architecture.md
+docs/
+
+# Editor / OS
+.vs/
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

hoptimal-0.1.0/CMakeLists.txt

@@ -0,0 +1,121 @@
+cmake_minimum_required(VERSION 3.20)
+project(hoptimal VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+option(HOPTIMAL_BUILD_TESTS      "Build C++ unit/integration tests" ON)
+option(HOPTIMAL_BUILD_BENCHMARKS "Build C++ microbenchmarks"        OFF)
+option(HOPTIMAL_BUILD_PYTHON     "Build pybind11 Python bindings"   OFF)
+option(HOPTIMAL_USE_SANITIZERS   "Enable ASan + UBSan (non-MSVC)"   OFF)
+
+# ── Dependencies (try find_package first, fall back to FetchContent) ──────────
+include(FetchContent)
+
+# Eigen3 — header-only. Prefer a system/vcpkg install; otherwise fetch the
+# source from git. We need only the headers, so we populate the source WITHOUT
+# running Eigen's own CMake: SOURCE_SUBDIR points at a nonexistent directory so
+# FetchContent_MakeAvailable downloads but skips add_subdirectory(). That avoids
+# (a) GitLab archive-checksum drift (we clone a tag instead of pinning a tarball
+# hash) and (b) a duplicate-target clash on Eigen3::Eigen that Eigen's own CMake
+# would otherwise create.
+find_package(Eigen3 3.4 QUIET)
+if(NOT Eigen3_FOUND)
+    message(STATUS "Eigen3 not found — fetching 3.4.0 via FetchContent (needs internet)")
+    FetchContent_Declare(eigen3
+        GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
+        GIT_TAG        3.4.0
+        GIT_SHALLOW    TRUE
+        SOURCE_SUBDIR  cmake-do-not-configure
+    )
+    FetchContent_MakeAvailable(eigen3)
+    if(NOT TARGET Eigen3::Eigen)
+        add_library(Eigen3::Eigen INTERFACE IMPORTED)
+        target_include_directories(Eigen3::Eigen INTERFACE ${eigen3_SOURCE_DIR})
+    endif()
+endif()
+
+# GoogleTest (only when tests are requested)
+if(HOPTIMAL_BUILD_TESTS)
+    find_package(GTest QUIET)
+    if(NOT GTest_FOUND)
+        message(STATUS "GTest not found — fetching via FetchContent")
+        FetchContent_Declare(googletest
+            URL https://github.com/google/googletest/archive/refs/tags/v1.14.0.tar.gz
+        )
+        set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+        FetchContent_MakeAvailable(googletest)
+    endif()
+endif()
+
+# pybind11 (only when Python bindings are requested)
+if(HOPTIMAL_BUILD_PYTHON)
+    find_package(pybind11 QUIET)
+    if(NOT pybind11_FOUND)
+        FetchContent_Declare(pybind11
+            URL https://github.com/pybind/pybind11/archive/refs/tags/v2.12.0.tar.gz
+        )
+        FetchContent_MakeAvailable(pybind11)
+    endif()
+endif()
+
+# ── hoptimal_core static library ──────────────────────────────────────────────────
+add_library(hoptimal_core STATIC
+    # core
+    src/core/search_space.cpp
+    src/core/trial.cpp
+    src/core/study.cpp
+    src/storage/memory_storage.cpp
+    src/samplers/random_sampler.cpp
+    # Gaussian-process Bayesian optimization
+    src/utils/lbfgs.cpp
+    src/gp/kernel.cpp
+    src/gp/gaussian_process.cpp
+    src/gp/acquisition.cpp
+    src/samplers/gp_sampler.cpp
+    # pruners
+    src/pruners/median_pruner.cpp
+    src/pruners/hyperband_pruner.cpp
+)
+
+target_include_directories(hoptimal_core PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+
+target_link_libraries(hoptimal_core PUBLIC Eigen3::Eigen)
+
+# Build with position-independent code so the static hoptimal_core library can be
+# linked into the _hoptimal shared module (pybind11). On Linux, linking a non-PIC
+# static lib into a .so fails ("relocation ... can not be used when making a
+# shared object; recompile with -fPIC"). Harmless for the test executables.
+set_target_properties(hoptimal_core PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+target_compile_options(hoptimal_core PRIVATE
+    $<$<CXX_COMPILER_ID:MSVC>:/W4 /wd4100 /wd4127>
+    $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Wpedantic>
+)
+
+if(HOPTIMAL_USE_SANITIZERS AND NOT MSVC)
+    target_compile_options(hoptimal_core PRIVATE
+        -fsanitize=address,undefined -fno-omit-frame-pointer)
+    target_link_options(hoptimal_core PRIVATE
+        -fsanitize=address,undefined)
+endif()
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+if(HOPTIMAL_BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests/unit)
+    add_subdirectory(tests/integration)
+endif()
+
+# ── Python bindings ───────────────────────────────────────────────────────────
+if(HOPTIMAL_BUILD_PYTHON)
+    pybind11_add_module(_hoptimal python/bindings/bindings.cpp)
+    target_link_libraries(_hoptimal PRIVATE hoptimal_core)
+    # scikit-build-core maps wheel.packages = ["python/hoptimal"] → the `hoptimal`
+    # package at the wheel root, so the compiled module installs into `hoptimal/`.
+    install(TARGETS _hoptimal DESTINATION hoptimal)
+endif()

hoptimal-0.1.0/Dockerfile

@@ -0,0 +1,48 @@
+FROM python:3.11-slim AS core
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        cmake \
+        ninja-build \
+        git \
+        libeigen3-dev \
+        libgtest-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /hoptimal
+COPY . .
+
+RUN cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DHOPTIMAL_BUILD_TESTS=ON \
+ && cmake --build build -j"$(nproc)" \
+ && ctest --test-dir build --output-on-failure
+
+RUN pip install --no-cache-dir . && pip install --no-cache-dir pytest
+
+RUN python -c "import hoptimal; \
+s=hoptimal.create_study('minimize'); \
+s.optimize(lambda t:(t.suggest_float('x',-5,5)-2)**2, 30); \
+print('core OK — best:', s.best_value, s.best_params)"
+
+FROM core AS integrations
+
+RUN pip install --no-cache-dir \
+        scikit-learn \
+        xgboost \
+        lightgbm \
+        catboost \
+        optuna \
+        scikit-optimize
+
+RUN python examples/test_sklearn.py \
+ && python examples/test_xgboost.py \
+ && python examples/test_lightgbm.py \
+ && python examples/test_catboost.py
+
+FROM integrations AS dl
+
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
+RUN pip install --no-cache-dir "jax[cpu]" flax tensorflow-cpu
+
+RUN python examples/test_pytorch.py \
+ && python examples/test_jax.py \
+ && python examples/test_tensorflow.py

hoptimal-0.1.0/LICENSE

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

hoptimal-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: hoptimal
+Version: 0.1.0
+Summary: High-performance hyperparameter optimisation — C++ core, Python bindings
+Keywords: hyperparameter,optimization,bayesian-optimization,gaussian-process,tpe,cma-es,machine-learning,automl
+Author-Email: Daniel Dema <danieldema42@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: OS Independent
+Project-URL: Homepage, https://github.com/danieldema/hoptimal
+Project-URL: Repository, https://github.com/danieldema/hoptimal
+Project-URL: Issues, https://github.com/danieldema/hoptimal/issues
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.3; extra == "sklearn"
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow>=2.13; extra == "tensorflow"
+Provides-Extra: jax
+Requires-Dist: jax>=0.4; extra == "jax"
+Requires-Dist: flax>=0.7; extra == "jax"
+Provides-Extra: xgboost
+Requires-Dist: xgboost>=2.0; extra == "xgboost"
+Provides-Extra: lightgbm
+Requires-Dist: lightgbm>=4.0; extra == "lightgbm"
+Provides-Extra: catboost
+Requires-Dist: catboost>=1.2; extra == "catboost"
+Provides-Extra: benchmark
+Requires-Dist: optuna; extra == "benchmark"
+Requires-Dist: hyperopt; extra == "benchmark"
+Requires-Dist: botorch; extra == "benchmark"
+Requires-Dist: scikit-optimize; extra == "benchmark"
+Requires-Dist: ray[tune]; extra == "benchmark"
+Requires-Dist: flaml; extra == "benchmark"
+Requires-Dist: nevergrad; extra == "benchmark"
+Requires-Dist: plotly; extra == "benchmark"
+Requires-Dist: pandas; extra == "benchmark"
+Requires-Dist: scipy; extra == "benchmark"
+Provides-Extra: all
+Requires-Dist: hoptimal[benchmark,catboost,jax,lightgbm,sklearn,tensorflow,torch,xgboost]; extra == "all"
+Description-Content-Type: text/markdown
+
+# hoptimal
+
+[![CI](https://github.com/danieldema/hoptimal/actions/workflows/ci.yml/badge.svg)](https://github.com/danieldema/hoptimal/actions/workflows/ci.yml)
+![C++20](https://img.shields.io/badge/C%2B%2B-20-blue)
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+**A from-scratch C++ Gaussian-Process Bayesian optimizer with Python bindings — competitive with Optuna and scikit-optimize on sample efficiency.**
+
+hoptimal implements Bayesian optimization (a Gaussian-Process surrogate + acquisition
+functions) in modern C++20, exposed to Python through pybind11. The GP, the
+Cholesky-based inference, the kernel-hyperparameter fitting, and the acquisition
+optimization are all hand-written — no GPyTorch, no BoTorch, no scikit-learn under
+the hood.
+
+## Benchmark
+
+Median regret (best-found − known optimum, lower is better) vs trial number on 8
+standard optimization test functions, 8 seeds each — hoptimal against Optuna and
+scikit-optimize:
+
+![regret curves](benchmarks/python/results/regret_curves.png)
+
+hoptimal's GP methods are **best-in-class**: across the 8 functions they win 4
+outright and place 2nd on the other 4, beating Optuna's TPE and CMA-ES and
+trading wins with scikit-optimize's GP — especially strong on the harder
+higher-dimensional problems (Hartmann-6, Ackley, Rosenbrock, Rastrigin).
+
+| Function | hoptimal (best) | Optuna (best) | scikit-optimize |
+|----------|------------:|--------------:|----------------:|
+| branin       | 0.0018 | 0.70 | **0.0011** |
+| hartmann3    | 0.013  | 0.15 | **0.0002** |
+| hartmann6    | **0.14** | 1.06 | 0.23 |
+| ackley5      | **2.48** | 3.30 | 2.78 |
+| rosenbrock4  | **5.29** | 10.4 | 9.28 |
+| levy5        | 2.17   | **2.07** | 3.98 |
+| rastrigin5   | **18.3** | 27.7 | 41.1 |
+| styblinski5  | 48.8   | 55.5 | **27.7** |
+
+Reproduce: `python benchmarks/python/competitors/bench_competitors.py && python benchmarks/python/visualize.py`
+
+## Quickstart
+
+```python
+import hoptimal
+
+study = hoptimal.create_study("minimize")   # GP + Expected Improvement by default
+
+def objective(trial):
+    x = trial.suggest_float("x", -5.0, 5.0)
+    y = trial.suggest_float("y", -5.0, 5.0)
+    return (x - 2.0) ** 2 + (y + 1.0) ** 2
+
+study.optimize(objective, n_trials=50)
+print(study.best_value, study.best_params)
+```
+
+The `Trial` API mirrors Optuna's, so migration is mostly mechanical. For a
+runnable tour (toy problem → Branin convergence plot → real sklearn model →
+head-to-head vs Optuna) see [`examples/demo.ipynb`](examples/demo.ipynb).
+
+## Features
+
+| Capability | Status |
+|------------|--------|
+| GP Bayesian optimization — **EI**, **UCB**, **PI** acquisitions | ✅ |
+| RBF and Matérn-5/2 kernels, MLE hyperparameter fitting (L-BFGS) | ✅ |
+| Float / int / log-scale / categorical parameters | ✅ |
+| Multi-objective optimization (Pareto front) | ✅ |
+| Median and Hyperband pruners (early stopping) | ✅ |
+| Parallel trials (`n_jobs`) with constant-liar | ✅ |
+| ML integrations: scikit-learn, XGBoost, LightGBM, CatBoost, PyTorch, JAX/Flax, TensorFlow/Keras | ✅ |
+
+All integrations are validated on clean Linux in CI (see the Dockerfile).
+
+### scikit-learn example
+
+```python
+from sklearn.svm import SVC
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from hoptimal.integrations.sklearn import HoptimalSearchCV
+
+pipe = Pipeline([("scaler", StandardScaler()), ("svc", SVC())])
+search = HoptimalSearchCV(
+    pipe,
+    {"svc__C":     ("float", 1e-3, 1e3, {"log": True}),
+     "svc__gamma": ("float", 1e-4, 1e0, {"log": True}),
+     "svc__kernel":("categorical", ["rbf", "sigmoid"])},
+    n_trials=40, cv=5, scoring="accuracy",
+)
+search.fit(X, y)
+print(search.best_score_, search.best_params_)
+```
+
+## Build from source
+
+**With Docker (recommended — builds + tests + validates integrations on clean Linux):**
+
+```bash
+docker build --target core -t hoptimal .          # C++ core + tests + bindings
+docker build --target integrations -t hoptimal .  # + sklearn/xgboost/lightgbm/catboost
+docker build --target dl -t hoptimal .            # + pytorch/jax/tensorflow (heavy)
+```
+
+**Locally** (needs a C++20 compiler, CMake, Eigen3; GoogleTest/pybind11 are
+fetched automatically if absent):
+
+```bash
+# C++ library + tests
+cmake -B build -DHOPTIMAL_BUILD_TESTS=ON
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+
+# Python package
+pip install .
+```
+
+## How it works
+
+Each trial, hoptimal fits a **Gaussian Process** to the observations so far, then
+picks the next point by optimizing an **acquisition function** over the GP's
+posterior. The implementation is hand-written C++:
+
+- **GP regression** with RBF / Matérn-5/2 kernels; inference via a
+  **Cholesky factorization** of `K + σ²I` (with jitter for stability) rather
+  than an explicit inverse.
+- **Kernel hyperparameters** (amplitude, length-scale) fitted by maximizing the
+  log marginal likelihood with L-BFGS and random restarts.
+- **Acquisition** (EI / UCB / PI) optimized over the normalized `[0,1]ᵈ` space
+  via a quasi-random candidate set refined with L-BFGS.
+
+The cost center — repeated Cholesky factorizations and acquisition
+optimization — is exactly why the core is in C++.
+
+## License
+
+MIT — see [LICENSE](LICENSE).