Skip to content

mamut_routing_lib.distances

Distance-matrix sidecar of a collection base instance (mamut-distances).

One sidecar per (base, metric): the full (n+1) x (n+1) matrix of the fastest (free-flow travel times) or shortest (path lengths) metric, values rounded to the family's precision (Poryos2026: 3 decimals). Slim CVRP/VRPTW instances reference it by sha-pinned collection-relative path instead of embedding the matrix; the fastest sidecar of a base must equal the free-flow node-to-node times of its road-graph sidecar after the same rounding (generation gate). Hashed over its uncompressed canonical JSON bytes, gzip mtime=0, like every other sidecar.

DISTANCES_FORMAT module-attribute 

DISTANCES_FORMAT = 'mamut-distances'

DISTANCES_FORMAT_VERSION module-attribute 

DISTANCES_FORMAT_VERSION = 1

DISTANCES_PLAIN_SUFFIX module-attribute 

DISTANCES_PLAIN_SUFFIX = '.json'

DISTANCES_GZIP_SUFFIX module-attribute 

DISTANCES_GZIP_SUFFIX = '.json.gz'

DISTANCES_INFIX module-attribute 

DISTANCES_INFIX = '.distances-'

DistancesFormatError

Bases: ValueError

Raised when a distances sidecar violates the canonical format.

InstanceDistances dataclass 

InstanceDistances(base_name: str, benchmark_name: str, metric: str, num_customers: int, values: list[list[float]], generator: dict[str, Any] = dict(), format_version: int = DISTANCES_FORMAT_VERSION)

In-memory content of a distances sidecar.

base_name instance-attribute 

base_name: str

benchmark_name instance-attribute 

benchmark_name: str

metric instance-attribute 

metric: str

num_customers instance-attribute 

num_customers: int

values instance-attribute 

values: list[list[float]]

generator class-attribute instance-attribute 

generator: dict[str, Any] = field(default_factory=dict)

format_version class-attribute instance-attribute 

format_version: int = DISTANCES_FORMAT_VERSION

distances_to_canonical_json_bytes 

distances_to_canonical_json_bytes(distances: InstanceDistances) -> bytes

Serialize to the canonical JSON bytes (the input of the distances sha256).

Fixed key order, one matrix row per line, floats via Python's shortest round-trip repr, gzip-independent.

Source code in MAMUT-routing-tools/MAMUT-routing-lib/src/mamut_routing_lib/distances.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def distances_to_canonical_json_bytes(distances: InstanceDistances) -> bytes:
    """Serialize to the canonical JSON bytes (the input of the distances sha256).

    Fixed key order, one matrix row per line, floats via Python's shortest
    round-trip repr, gzip-independent.
    """
    header_lines = [
        "{",
        f'    "format": {json.dumps(DISTANCES_FORMAT)},',
        f'    "format_version": {json.dumps(distances.format_version)},',
        f'    "base_name": {json.dumps(distances.base_name)},',
        f'    "benchmark_name": {json.dumps(distances.benchmark_name)},',
        f'    "metric": {json.dumps(distances.metric)},',
        f'    "num_customers": {json.dumps(distances.num_customers)},',
        f'    "generator": {json.dumps(distances.generator, sort_keys=True)},',
        '    "values": [',
    ]
    body = ",\n".join("        " + json.dumps(row) for row in distances.values)
    text = "\n".join(header_lines) + "\n" + body + "\n    ]\n}\n"
    return text.encode("utf-8")

compute_distances_sha256 

compute_distances_sha256(distances: InstanceDistances) -> str
Source code in MAMUT-routing-tools/MAMUT-routing-lib/src/mamut_routing_lib/distances.py 
95
96
def compute_distances_sha256(distances: InstanceDistances) -> str:
    return hashlib.sha256(distances_to_canonical_json_bytes(distances)).hexdigest()

save_instance_distances 

save_instance_distances(distances: InstanceDistances, path: str | Path) -> None

Write the sidecar; gzip iff the path ends with .json.gz (mtime=0).

The conventional name is <base>.distances-<metric>.json[.gz]; the .distances- infix is required so the sidecar is never confused with other artifact kinds.

Source code in MAMUT-routing-tools/MAMUT-routing-lib/src/mamut_routing_lib/distances.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def save_instance_distances(distances: InstanceDistances, path: str | Path) -> None:
    """Write the sidecar; gzip iff the path ends with ``.json.gz`` (``mtime=0``).

    The conventional name is ``<base>.distances-<metric>.json[.gz]``; the
    ``.distances-`` infix is required so the sidecar is never confused with
    other artifact kinds.
    """
    _validate_distances(distances)
    target = Path(path)
    if DISTANCES_INFIX not in target.name:
        raise DistancesFormatError(f"distances path must contain {DISTANCES_INFIX!r}: {target.name}")
    data = distances_to_canonical_json_bytes(distances)
    target.parent.mkdir(parents=True, exist_ok=True)
    if target.name.endswith(DISTANCES_GZIP_SUFFIX):
        target.write_bytes(gzip.compress(data, mtime=0))
    elif target.name.endswith(DISTANCES_PLAIN_SUFFIX):
        target.write_bytes(data)
    else:
        raise DistancesFormatError(
            f"distances path must end with {DISTANCES_PLAIN_SUFFIX} or {DISTANCES_GZIP_SUFFIX}: {target.name}"
        )

load_instance_distances 

load_instance_distances(path: str | Path) -> InstanceDistances
Source code in MAMUT-routing-tools/MAMUT-routing-lib/src/mamut_routing_lib/distances.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
def load_instance_distances(path: str | Path) -> InstanceDistances:
    source = Path(path)
    raw = source.read_bytes()
    if source.name.endswith(DISTANCES_GZIP_SUFFIX):
        raw = gzip.decompress(raw)
    payload = json.loads(raw.decode("utf-8"))
    if payload.get("format") != DISTANCES_FORMAT:
        raise DistancesFormatError(f"unexpected format marker: {payload.get('format')!r}")
    if payload.get("format_version") != DISTANCES_FORMAT_VERSION:
        raise DistancesFormatError(f"unsupported format_version: {payload.get('format_version')!r}")
    distances = InstanceDistances(
        base_name=str(payload["base_name"]),
        benchmark_name=str(payload["benchmark_name"]),
        metric=str(payload["metric"]),
        num_customers=int(payload["num_customers"]),
        values=[list(row) for row in payload["values"]],
        generator=dict(payload.get("generator", {})),
    )
    _validate_distances(distances)
    return distances