Overview

Repo: github.com/ryomenhaider/Vecta

What It Is

Vecta is a computational maths library for ML, built from scratch in C++ with Python bindings, structured chapter-by-chapter after Mathematics for Machine Learning (Deisenroth, Faisal, Ong).

Stack

• C++17 core — no external maths dependencies, everything implemented from scratch
• pybind11 for Python bindings
• scikit-build-core + CMake for packaging
• uv for the Python venv and all package installs (no pip commands)
• Catch2 for C++ unit tests
• pytest for Python-level tests

Status

The project follows the book’s chapters, each with a “stub → real implementation” lifecycle. See the Chapters page for the current status table.

Layout

Each chapter gets matching folders across headers, sources, bindings, the Python package, and both test suites:

include/vecta/<chapter>/      C++ headers
src/<chapter>/                C++ implementation
bindings/<chapter>_bindings.cpp   pybind11 binding code for that chapter
python/vecta/<chapter>/       Python package wrapper
tests/cpp/<chapter>/          Catch2 tests
tests/python/<chapter>/       pytest tests

examples/ is free scratch space for worked examples from the book.

How It Stays Green

Every chapter folder — even stubs — compiles, links, imports from Python, and has a smoke test. The whole pipeline stays green as you go; replace placeholder() with real content in the header/source/bindings/tests for a chapter as you study it.

Chapters

Chapters map to the book’s structure (folder name → book chapter):

“stub” means: it compiles, links, imports from Python, and has a smoke test — so the whole pipeline stays green as you go. Replace placeholder() with real content in the header/source/bindings/tests for a chapter as you study it.

Adding Real Content

Steps

1. Write the real implementation in include/vecta/<chapter>/<chapter>.hpp (and .cpp if needed).
2. Expose it to Python in bindings/<chapter>_bindings.cpp.
3. Delete the placeholder() smoke tests in tests/cpp/<chapter>/ and tests/python/<chapter>/, replacing them with real tests.
4. CMake picks up new .cpp files automatically on the next build (globbing with CONFIGURE_DEPENDS) — no need to edit CMakeLists.txt.

Example

After implementing linear_algebra vectors, the pipeline is:

// include/vecta/linear_algebra/linear_algebra.hpp
#pragma once
namespace vecta {
// real vector implementation here
}

// bindings/linear_algebra_bindings.cpp
#include <pybind11/pybind11.h>
// py::class_<...> bindings here

Then rebuild and run both test suites (see Development).

Development

Environment

Activate the venv created by setup_vecta.sh:

source .venv/bin/activate

Rebuild After C++ Changes

Rebuild + reinstall the Python module after changing C++ code:

uv pip install -e . --no-build-isolation

Python Tests

pytest

C++ Tests

C++ tests live in a separate dev build, not part of the Python wheel. A plain cmake invocation doesn’t automatically know where pybind11’s CMake config lives the way pip/uv pip install does, so point it there explicitly:

PYBIND11_CMAKE_DIR=$(python -c "import pybind11; print(pybind11.get_cmake_dir())")
cmake -S . -B build-tests -DVECTA_BUILD_TESTS=ON -DCMAKE_PREFIX_PATH="$PYBIND11_CMAKE_DIR"
cmake --build build-tests
ctest --test-dir build-tests --output-on-failure