Python package

ndtbl

Pure-Python tools for reading, writing, inspecting, and generating .ndtbl files without depending on the C++ binaries.

The package is useful when you want to:

inspect an existing table on a machine without the C++ toolchain
generate small synthetic tables for tests, examples, and development
query one concrete grid point from the command line
read or write .ndtbl files directly from Python workflows using NumPy arrays

🔧 Features

Read .ndtbl metadata or full payloads
Write .ndtbl files compatible with the current C++ implementation
Inspect files from the command line with metadata and sample values
Query one point in a table by zero-based grid indices
Generate small predefined linear tables for development workflows

⚙️ Installation

Install from the package directory:

python -m pip install .

Or install from PyPI:

python -m pip install ndtbl

For development:

python -m pip install -v -e .[lint,tests]

🐍 Python API

The core API revolves around FieldGroup, UniformAxis, ExplicitAxis, read_group, and write_group.

import numpy as np

from ndtbl import FieldGroup, UniformAxis, ExplicitAxis, read_group, write_group

group = FieldGroup(
    axes=(ExplicitAxis([0.0, 0.1, 1.0]), UniformAxis(10.0, 20.0, 2)),
    field_names=("A", "B"),
    values=np.array(
        [
            [[1.0, 10.0], [2.0, 20.0]],
            [[3.0, 30.0], [4.0, 40.0]],
            [[5.0, 50.0], [6.0, 60.0]],
        ],
        dtype=np.float64,
    ),
)

write_group("example.ndtbl", group)

loaded = read_group("example.ndtbl")
print(loaded.field_names)
print(loaded.values[1, 0, :])

write_group refuses to write files larger than 128 MiB by default. Pass max_size_mib=... when a larger output is intentional.

The values array shape is axis_0 x axis_1 x ... x field.

Demo notebook

Use the demo notebook to test the Python functionality of ndtbl and see how it can be used to read and write binary .ndtbl files.

💻 CLI

The package installs one executable, ndtbl, with three subcommands:

inspect prints metadata and a configurable number of sample values
query prints the field values at one point addressed by zero-based indices
generate creates a simple synthetic table with linear fields

Show the top-level help:

ndtbl --help

`inspect`

Inspect an existing file:

ndtbl inspect example.ndtbl

Limit the number of printed sample points:

ndtbl inspect example.ndtbl --samples 3

`query`

Query one point in the table using zero-based indices in axis order:

ndtbl query example.ndtbl 1 0

Print metadata before the queried values:

ndtbl query --metadata example.ndtbl 1 0

For a 3D table, provide three indices:

ndtbl query example-3d.ndtbl 1 2 0

`generate`

Generate a small linear table:

ndtbl generate output.ndtbl \
  --axis 0 1 3 \
  --axis 10 20 2 \
  --field-linear A 1.0 2.0 0.0 \
  --field-linear B 5.0 0.0 -1.0

Use float32 output instead of the default float64:

ndtbl generate output.ndtbl \
  --axis 0 1 3 \
  --field-linear A 1.0 2.0 \
  --dtype float32

Raise or lower the generation safety limit:

ndtbl generate output.ndtbl \
  --axis 0 1 100 \
  --axis 0 1 100 \
  --field-linear A 0.0 1.0 1.0 \
  --max-size-mib 32

--field-linear expects NAME OFFSET C0 [C1 ...], with one coefficient per axis in storage order.