Technical Documentation

Finite metric spaces as native C++ numerical objects.

METRIC works with records and explicit metrics. The core engine owns the metric-space model; bindings adapt external language data to that native implementation.

Finite Metric Spaces

A finite metric space is a finite record set `X = {x0, x1, ..., xn}` plus a distance function `d(x, y)`. The metric gives the dataset its geometry. Operators document when they require non-negativity, identity, symmetry, and the triangle inequality.

Records do not need to be vectors. METRIC can use strings with edit distance, histograms with transport distance, process curves with alignment distance, mixed records with composed domain penalties, or vectors with Euclidean distance.

Engine Model

RecordSet + Metric -> MetricSpace -> Representation -> Operator -> Result

MetricSpaceStores records, stable IDs, metric traits, metadata, and version state.

RepresentationRuns the same space implicitly, through a distance matrix, graph, tree index, or mapped space.

OperatorComputes neighbors, groups, representatives, graph diagnostics, entropy, MGC, mappings, and reductions.

ResultPreserves IDs, strategy metadata, representation metadata, warnings, diagnostics, and lineage.

C++ API

#include <metric/distance.hpp>
#include <metric/engine.hpp>

#include <string>
#include <vector>

std::vector<std::string> records = {"metric", "metrics", "matrix", "tree"};
auto space = metric::make_space(records, metric::Edit<char>{});

auto neighbors = metric::find_neighbors(
    space,
    std::string("metricks"),
    metric::count{2},
    metric::strategies::cover_tree{});

The detailed C++ reference is maintained in docs/api/cpp.md.

Bindings

Python exposes selected native surfaces for user records, result objects, and adapters. Algorithmic work belongs to the C++ implementation. Binding documentation is maintained in docs/api/python.md.

from metric import Edit, Space

records = ["cat", "cot", "coat", "dog"]
space = Space(records, Edit())
print(space.neighbors("cut", k=2))

Hero Examples

String edit space: metric correct 4/4, vector baseline misses 4/4.
Histogram transport: metric correct 4/4, vector baseline misses 4/4.
External process curves: metric correct 16/16, vector baseline misses 16/16.
Distribution/image recoding: metric correct 4/4, vector baseline misses 4/4.
Mixed structured records: metric correct 4/4, vector baseline misses 4/4.
Cross-space MGC: dependency detected, raw vector pairing misses 9/12.
PHATE-AE pipeline: native component provenance plus process-curve latent nearest families correct for 6/6 while the vector baseline misses 6/6.

The documented outputs are in docs/examples/engine-demo-outputs.md.

Status Labels

METRIC labels public surfaces as promoted, compatibility, beta, experimental, or historical. The module matrix is maintained in docs/stability.md.