ndtbl

ndtbl is an n-dimensional table format and toolkit.

This repository currently contains two user-facing parts:

• a header-only C++14 library in include/ndtbl/
• a separate pure-Python package in python/ndtbl/ for reading, writing, inspecting, querying, and generating .ndtbl files

The C++ reader can also be built with optional POSIX mmap memory mapping support so payloads can stay file-backed instead of always being copied into heap memory entirely.

🗂️ Layout

• app/: C++ command-line tool for inspecting .ndtbl files
• benchmarks/: C++ benchmarks
• cmake/: CMake modules
• doc/: Sphinx and Doxygen documentation
• include/ndtbl/: public C++ headers
• python/ndtbl/: pure-Python package and ndtbl CLI
• tests/: Catch2-based C++ test suite

🖥️ Which interface to use

Use the C++ library when you want to integrate ndtbl's lookup logic directly into a C++ application.

Use the Python package when you want a pip-installable Python interface for creating .ndtbl files from NumPy arrays, inspecting existing .ndtbl files, or running queries against them. The Python package also provides a convenient CLI for inspecting, querying, and generating .ndtbl files. See python/ndtbl/README.md for Python package details.

If you want to inspect .ndtblfiles with a C++ command-line tool, use the C++ ndtbl-inspect executable built from app/. It is not prebuilt; it becomes available only after running the local CMake build.

📋 Prerequisites

Building the C++ project requires:

• a C++14-compliant compiler for the header-only library interface
• a compiler with C++20 support for the executables in app/ and tests in tests/
• CMake >= 3.23
• Doxygen only if you want to build the documentation
• Catch2 only if you want to build the optional C++ test suite

🛠️ Build

From the top-level ndtbl/ directory:

cmake -B build -Dndtbl_BUILD_TESTING=OFF -Dndtbl_BUILD_DOCS=OFF
cmake --build build

This produces the C++ command-line tool in build/app/:

• build/app/ndtbl-inspect

Relevant CMake options:

• ndtbl_BUILD_TESTING: build the C++ test suite, default OFF
• ndtbl_BUILD_BENCHMARKS: build developer lookup benchmarks, default OFF
• ndtbl_BUILD_DOCS: build the documentation, default ON for top-level builds
• ndtbl_ENABLE_MMAP: enable POSIX-only mmap-backed payload reads, default OFF

When ndtbl_ENABLE_MMAP=OFF (the default), read_group() reads payload data into owned heap storage. When ndtbl_ENABLE_MMAP=ON, supported POSIX builds use read-only memory mapping instead, which can reduce heap usage for large tables and enables shared memory access in multi-process environments.

If you want to install the C++ headers and CMake package metadata:

cmake --install build --prefix /desired/prefix

To enable optional mmap-backed reads on supported POSIX platforms:

cmake -B build -Dndtbl_ENABLE_MMAP=ON
cmake --build build

⚙️ C++ Tool Workflow

Inspect existing .ndtbl files:

./build/app/ndtbl-inspect output.ndtbl

📐 Interpolation

The standard C++ lookup path uses multilinear interpolation through explicit evaluate_all_linear() and Grid::prepare_linear() calls. This path uses 2^Dim table points per query and keeps the hot path allocation-free.

The C++ API also exposes local tensor-product cubic interpolation through explicit evaluate_all_cubic() and Grid::prepare_cubic() calls. Cubic interpolation uses 4^Dim table points, can be much more expensive in high dimensions, and may overshoot smooth-looking table data enough to produce unwanted values. Bounds handling is independent of interpolation order: queries outside the table domain can either clamp or throw according to the selected bounds_policy.

🐍 Python Package

The repository also ships a separate Python package in python/ndtbl/.

That package installs a different CLI executable named ndtbl, with the subcommands:

• inspect
• query
• generate

Install it from the package directory:

cd python/ndtbl
python -m pip install .

After that, the Python CLI is available:

ndtbl --help

See python/ndtbl/README.md for usage examples and Python API details.

🧪 Testing

Enable the C++ test suite during configuration:

cmake -B build -Dndtbl_BUILD_TESTING=ON
cmake --build build

Then run:

cd build
ctest --output-on-failure

⏱️ Benchmarks

The lookup-time benchmarks use Google Benchmark and measure query preparation, prepared evaluation, typed combined lookup, and runtime-erased combined lookup for representative 2D, 4D, and 6D tables. See benchmarks/README.md for the benchmark case definitions and interpretation.

Build the benchmark target:

cmake -B build -Dndtbl_BUILD_BENCHMARKS=ON
cmake --build build --target ndtbl_lookup_benchmarks

Run a benchmark:

./build/benchmarks/ndtbl_lookup_benchmarks

📖 Documentation

Online documentation is available at ndtbl.readthedocs.io.

To build the docs locally, first install the documentation requirements from the top-level ndtbl/ directory:

python -m pip install -r doc/requirements.txt

Then build the Sphinx target:

cmake -B build -Dndtbl_BUILD_DOCS=ON -Dndtbl_BUILD_TESTING=OFF
cmake --build build --target sphinx-doc

Open build/doc/sphinx/index.html in a browser to inspect the generated site.