visiontrack-cpp 0.1.0__tar.gz

visiontrack_cpp-0.1.0/.github/workflows/parity-isolation.yml

@@ -0,0 +1,91 @@
+# A single-purpose experiment, not part of releasing.
+#
+# ANSWERED. Neither compiler was at fault, and neither was NumPy's version.
+# Both arms pass on manylinux_2_28 (gcc 12: 25 passed; clang 21.1.8: 25
+# passed) with the same NumPy 2.4.6 that failed on manylinux2014. The real
+# variable was the base image: NumPy >= 2.4 needs glibc 2.27 and ships no
+# manylinux2014 wheel, so on CentOS 7 pip compiled NumPy from source against
+# a different LAPACK -- visible as a wheel tagged linux_x86_64 instead of
+# manylinux_*. The comparison had been against a rebuilt oracle, not against
+# the reference. release.yml now pins manylinux_2_28 and ci/check_oracle.py
+# refuses to run the suite against a NumPy whose BLAS is not a known-good
+# backend. Kept here as a working harness for the next question of this shape.
+#
+# Original framing follows.
+#
+# CI run 2 found that the Kalman parity tests fail on Linux x86_64 with NumPy
+# 2.4.6 by 1-2 ULP, while passing on:
+#   * macOS arm64 / clang  with NumPy 2.2.6, 2.4.6 and 2.5.3
+#   * Windows x86_64 / MSVC with NumPy 2.2.6, 2.4.6 and 2.5.3
+#   * Linux x86_64 / gcc   with NumPy 2.2.6
+#
+# So neither "x86_64" nor "NumPy >= 2.4" explains it alone; it is the two
+# together. Two candidates remain, and they assign blame to opposite sides:
+#
+#   (a) gcc's codegen for the Eigen Kalman path -> our bug, and fixable.
+#   (b) NumPy's manylinux build reducing in a different order than its macOS
+#       and Windows wheels -> the oracle differs per platform, and the C++ is
+#       faithful to the reference it was written against.
+#
+# Each arm compiles a C++17 probe before cibuildwheel runs, and the step is
+# chained with && rather than tolerated with || true. The first attempt at this
+# experiment installed a clang too old for C++17 and failed for that reason
+# instead of for a parity reason -- an arm that cannot build is not evidence,
+# and it must say so in its own words rather than as a generic CMake error.
+#
+# This holds the platform, the image, the Python and the NumPy version fixed
+# and varies ONLY the compiler. clang passing while gcc fails points at (a). Both failing
+# points at (b). Anything else means the experiment is wrong, not the answer.
+name: parity-isolation
+
+on:
+  workflow_dispatch:
+
+jobs:
+  linux-compiler:
+    name: linux cp311 numpy==2.4.6 (${{ matrix.cc }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - cc: gcc      # the control arm: must reproduce the failure
+            cxx: g++
+          - cc: clang    # the treatment arm
+            cxx: clang++
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build and test one wheel
+        uses: pypa/cibuildwheel@v2.21.3
+        env:
+          # One interpreter only. The point is the compiler, and every extra
+          # build is wall-clock spent not answering the question.
+          CIBW_BUILD: "cp311-manylinux_x86_64"
+          CIBW_ARCHS_LINUX: "x86_64"
+          # manylinux_2_28 (AlmaLinux 8), not the default manylinux2014
+          # (CentOS 7). EPEL on CentOS 7 ships clang 3.4.2 -- a 2014 compiler
+          # that cannot compile C++17, so CMake rejected it as broken and the
+          # first attempt at this experiment produced a clang arm that never
+          # ran a test. Both arms use the same image so the compiler is the
+          # only difference between them; the gcc-on-manylinux2014 result from
+          # release run 2 stays the separate reproduction data point.
+          CIBW_MANYLINUX_X86_64_IMAGE: "manylinux_2_28"
+          CIBW_BEFORE_ALL_LINUX: >-
+            dnf install -y clang &&
+            ${{ matrix.cxx }} --version &&
+            printf 'int main(){ if constexpr(true) return 0; return 1; }' > /tmp/probe.cpp &&
+            ${{ matrix.cxx }} -std=c++17 /tmp/probe.cpp -o /tmp/probe
+          CIBW_ENVIRONMENT_LINUX: "CC=${{ matrix.cc }} CXX=${{ matrix.cxx }}"
+          # NumPy is pinned here, unlike in release.yml. In an experiment the
+          # oracle must be held fixed: a floating NumPy would let the variable
+          # under test and the reference move at the same time.
+          CIBW_TEST_REQUIRES: "pytest>=7.0 visiontrack-mot==0.2.0 numpy==2.4.6"
+          CIBW_TEST_COMMAND: >-
+            python -c "import visiontrack_cpp, numpy, json;
+            print('COMPILER_ARM=${{ matrix.cc }}');
+            print(json.dumps(visiontrack_cpp.build_info(), indent=2));
+            print('numpy', numpy.__version__);
+            numpy.show_config()"
+            && pytest {project}/tests/test_parity_kalman.py -v
+            && pytest {project}/tests -q

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

@@ -0,0 +1,132 @@
+# Build wheels on every supported platform, then publish them to PyPI with
+# trusted publishing -- no API token anywhere in this repository or in its
+# secrets.
+#
+# The parity claim in the README is a claim about a *binary*, not about source
+# code: it holds only if the compiler that produced the binary left every
+# floating-point operation alone. That is why every wheel built here runs
+# tests/test_build_integrity.py before it is allowed out. A wheel whose
+# compiler contracted `a + b*c` into an FMA is not a slower-but-correct wheel,
+# it is a wheel that quietly breaks the one guarantee this project makes, and
+# it must fail the build rather than ship.
+#
+# Confirmed passing: arm64/clang (macos-14) and x86_64/MSVC (windows-latest),
+# both across NumPy 2.2.6, 2.4.6 and 2.5.3.
+#
+# Linux's earlier NumPy >= 2.4 failures were traced to manylinux2014 compiling
+# NumPy locally against a different LAPACK. The manylinux_2_28 image and oracle
+# integrity check below now prevent that false comparison; the latest complete
+# three-platform manual run passed.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  wheels:
+    name: wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Never cancel siblings: when one platform's parity gate fails, the
+      # interesting question is whether the others failed too, and a cancelled
+      # job answers nothing.
+      fail-fast: false
+      matrix:
+        # macos-13 (Intel) is deliberately absent. It sat queued without ever
+        # being scheduled on two consecutive runs -- GitHub is retiring those
+        # runners -- and a release must not be gated on a runner that does not
+        # arrive. x86_64 is still covered by ubuntu-latest and windows-latest,
+        # and clang is still covered by macos-14, so the cell it would have
+        # filled (clang x x86_64) is the product of two factors already tested.
+        os: [ubuntu-latest, macos-14, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21.3
+        env:
+          CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-*"
+          # PyPy has no pybind11 story here worth supporting, and musllinux
+          # doubles the Eigen build for a platform nobody has asked for.
+          CIBW_SKIP: "pp* *-musllinux_* *_i686 *-win32"
+          CIBW_ARCHS_MACOS: "auto"
+          CIBW_ARCHS_LINUX: "x86_64"
+          # manylinux_2_28, not the default manylinux2014. This is a parity
+          # setting, not a modernisation: NumPy >= 2.4 requires glibc 2.27 and
+          # ships no manylinux2014 wheel, so on CentOS 7 pip silently compiled
+          # NumPy from source (the giveaway is a wheel tagged linux_x86_64
+          # rather than manylinux_*). A source-built NumPy links a different
+          # LAPACK than the official OpenBLAS wheel, and its np.linalg.solve
+          # returns answers 1-2 ULP away. Three Kalman parity tests failed for
+          # exactly that reason, and the tracker was never involved: the
+          # oracle had been rebuilt underneath the comparison.
+          CIBW_MANYLINUX_X86_64_IMAGE: "manylinux_2_28"
+          # Matches what RELEASE.md requires of a local build: without this the
+          # wheel is tagged for whatever macOS built it, which forces every
+          # older-macOS user to compile a package that ships as a binary.
+          MACOSX_DEPLOYMENT_TARGET: "11.0"
+          CIBW_TEST_REQUIRES: "pytest>=7.0 visiontrack-mot==0.2.0"
+          # scipy gates ~10 tests in test_lapjv.py, which skip cleanly without
+          # it. It is deliberately NOT in CIBW_TEST_REQUIRES: inside the
+          # manylinux image pip resolved a scipy with no matching wheel, fell
+          # back to a source build, and failed for want of OpenBLAS -- taking
+          # the parity gate down with it. An optional test dependency must not
+          # be able to fail this job, so it is installed best-effort and the
+          # tests it gates skip when it is absent.
+          CIBW_BEFORE_TEST: "pip install scipy || true"
+          # Two preconditions, then the suite. The second one exists because
+          # its absence cost a full day: parity is measured against NumPy, so
+          # a NumPy that pip built from source is not the reference and any
+          # comparison to it is meaningless. Asserting the BLAS turns that
+          # from three inscrutable 1-ULP failures into one sentence naming the
+          # cause.
+          CIBW_TEST_COMMAND: >-
+            python {project}/ci/check_oracle.py
+            && pytest {project}/tests -q
+        # No continue-on-error on any platform. It was here for Windows while
+        # MSVC's FP behaviour was an open question; that question is now
+        # answered (fp_contract_off is true under /fp:precise) and the flag has
+        # to go, because it does not just tolerate a failure -- it rewrites the
+        # step's `conclusion` to success while the real `outcome` is failure.
+        # A parity gate that reports green when it failed is worse than no gate.
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pipx run build --sdist
+      - run: pipx run twine check dist/*.tar.gz
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    # Only a tag publishes. A manual workflow_dispatch run builds and tests
+    # everything and stops, which is what you want when the question is "do
+    # the wheels build?" rather than "should this go out?".
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - run: ls -la dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

visiontrack_cpp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+build/
+dist/
+*.so
+*.dylib
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.venv/
+CMakeCache.txt
+CMakeFiles/
+compile_commands.json

visiontrack_cpp-0.1.0/CMakeLists.txt

@@ -0,0 +1,115 @@
+cmake_minimum_required(VERSION 3.20)
+project(visiontrack_cpp LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# When Eigen is not already on the machine, download a pinned copy rather than
+# failing. Pinned, not "latest": Eigen chooses different kernels between
+# versions, and this project's correctness claim is bit-for-bit agreement with
+# a NumPy reference. A floating version would make the wheel's numerics depend
+# on the day it was built. Set -DVT_FETCH_EIGEN=OFF to forbid the download and
+# require a system Eigen instead.
+option(VT_FETCH_EIGEN "Download a pinned Eigen if none is installed" ON)
+# OFF builds against the pinned Eigen even when the machine has one. That is
+# the setting a release wheel wants: it makes the binary's numerics a property
+# of this repo rather than of whatever the build host happened to have in
+# /opt/homebrew. It is also the only way to exercise the download path on a
+# machine that already has Eigen.
+option(VT_SYSTEM_EIGEN "Prefer an already-installed Eigen over the pinned one" ON)
+set(VT_EIGEN_TAG "3.4.0" CACHE STRING "Eigen release to fetch when none is found")
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+
+# Eigen is header-only. Prefer a real config package, then the usual system
+# include paths, and only then the network.
+if(VT_SYSTEM_EIGEN)
+  find_package(Eigen3 3.3 QUIET NO_MODULE)
+endif()
+if(Eigen3_FOUND)
+  set(VT_EIGEN_TARGET Eigen3::Eigen)
+  message(STATUS "Eigen: found via CMake config")
+else()
+  if(VT_SYSTEM_EIGEN)
+    find_path(VT_EIGEN_INCLUDE_DIR NAMES Eigen/Dense
+              HINTS /opt/homebrew/opt/eigen/include/eigen3
+                    /usr/local/opt/eigen/include/eigen3
+                    /usr/include/eigen3)
+  endif()
+  if(VT_EIGEN_INCLUDE_DIR)
+    message(STATUS "Eigen: using include dir ${VT_EIGEN_INCLUDE_DIR}")
+  elseif(VT_FETCH_EIGEN)
+    message(STATUS "Eigen: not installed, fetching pinned ${VT_EIGEN_TAG}")
+    include(FetchContent)
+    # CMake 3.30 deprecated single-argument FetchContent_Populate in favour of
+    # MakeAvailable. MakeAvailable is wrong here: it would add_subdirectory()
+    # Eigen's own project, pulling in its tests, BLAS/LAPACK shims and install
+    # rules -- none of which this build wants, and some of which break on
+    # toolchains that build the extension fine. Populate-only is the intent, so
+    # the old behaviour is requested explicitly rather than tripped into.
+    if(POLICY CMP0169)
+      cmake_policy(SET CMP0169 OLD)
+    endif()
+    FetchContent_Declare(
+      eigen
+      URL https://gitlab.com/libeigen/eigen/-/archive/${VT_EIGEN_TAG}/eigen-${VT_EIGEN_TAG}.tar.gz
+    )
+    # Populate only. Eigen's own CMake project pulls in tests, BLAS shims and
+    # install rules that this build has no use for and that break some
+    # toolchains; the headers are the entire dependency.
+    FetchContent_Populate(eigen)
+    set(VT_EIGEN_INCLUDE_DIR ${eigen_SOURCE_DIR})
+  else()
+    message(FATAL_ERROR
+      "No Eigen available: none installed (or VT_SYSTEM_EIGEN=OFF) and "
+      "VT_FETCH_EIGEN=OFF.\n"
+      "  macOS:  brew install eigen\n"
+      "  Debian: apt install libeigen3-dev")
+  endif()
+endif()
+
+# PARITY: forbid floating-point contraction. clang defaults to -ffp-contract=fast
+# at -O2/-O3, which fuses `a + b*c` into a single FMA that rounds ONCE where
+# NumPy rounds twice. That is a 1-ULP difference on every height-scaled term of
+# the Kalman process noise -- invisible in isolation, and exactly the kind of
+# drift that flips a near-tied association later. Correctness here means
+# "identical to the oracle", not "more accurate".
+#
+# On an unrecognised compiler this stops the build instead of guessing. A wheel
+# built without the flag is not slightly off, it is wrong, and silently
+# omitting the flag is the one failure this project cannot afford to be quiet
+# about. `visiontrack_cpp.build_info()["fp_contract_off"]` re-checks the same
+# property against the binary that actually came out, so a toolchain that
+# ignores the flag is still caught -- at import, by the tests, not in the field.
+if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU|IntelLLVM")
+  add_compile_options(-ffp-contract=off)
+elseif(MSVC)
+  # /fp:precise disables contraction -- verified, not assumed: a Windows CI
+  # wheel reports fp_contract_is_off() == true and passes the parity suite.
+  #
+  # /Zc:__cplusplus is needed because MSVC otherwise hardcodes __cplusplus to
+  # 199711L for backward compatibility, no matter which standard it is
+  # actually compiling. Without it, build_info() reports a C++ standard the
+  # build is not using, and the integrity tests correctly call that a lie.
+  add_compile_options(/fp:precise /Zc:__cplusplus)
+else()
+  message(FATAL_ERROR
+    "Unknown compiler '${CMAKE_CXX_COMPILER_ID}': no way to disable FP "
+    "contraction, which this project's parity guarantee depends on.")
+endif()
+
+pybind11_add_module(visiontrack_cpp bind/module.cpp)
+target_include_directories(visiontrack_cpp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+
+if(Eigen3_FOUND)
+  target_link_libraries(visiontrack_cpp PRIVATE ${VT_EIGEN_TARGET})
+else()
+  target_include_directories(visiontrack_cpp PRIVATE ${VT_EIGEN_INCLUDE_DIR})
+endif()
+
+install(TARGETS visiontrack_cpp DESTINATION .)

visiontrack_cpp-0.1.0/LICENSE

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

visiontrack_cpp-0.1.0/NEXT_STEPS.md

@@ -0,0 +1,43 @@
+# VisionTrack C++ — next-step checklist
+
+VisionTrack C++ is the parity-gated performance implementation of the NumPy
+reference. Its core engineering phases are resolved; future work should protect
+the parity claim rather than broaden the tracker into a second research repo.
+
+## Active focus — publish version 0.1.0
+
+- [ ] Confirm the PyPI project or pending trusted publisher is available.
+- [ ] Rebuild source and platform-wheel artifacts from a clean release commit.
+- [ ] Run the oracle-integrity check and full parity suite on every wheel.
+- [ ] Publish only after all platform gates pass.
+- [ ] Verify installation from PyPI in clean Python 3.10–3.13 environments.
+- [ ] Replace provisional installation wording with a verified release link and
+      record the release date.
+
+As of 2026-09-13, the PyPI JSON endpoint for `visiontrack-cpp` returns 404; the
+package is not yet publicly installable under that name. The repository's
+GitHub Actions environment named `pypi` also returns 404, so the environment
+and PyPI pending trusted publisher must be configured before creating `v0.1.0`.
+
+## After publication — maintain the contract
+
+- [x] Add a small CI check for the learning hub and release-document links.
+- [ ] Regenerate parity and benchmark reports from the exact release commit.
+- [ ] Document the supported NumPy-oracle matrix for each release.
+- [ ] Test new compiler, Eigen, Python, and NumPy versions deliberately before
+      claiming support.
+- [ ] Keep research-only GMC, OC-SORT, and learned residual behavior in the
+      NumPy repository unless a measured production need justifies a port.
+
+## Explicit non-goals
+
+- [ ] Do not add a GPU path without new measurements that overturn the existing
+      float64, dispatch-overhead, and Amdahl conclusions.
+- [ ] Do not trade bit-exact default behavior for a benchmark headline.
+- [ ] Do not duplicate the detector, evaluation platform, or research harness.
+
+## Completion rule
+
+The next release is complete only when an ordinary user can install the package,
+inspect its build information, reproduce parity, and trace the published
+benchmark to the same source revision.