gdsdiff 0.1.0__py3-none-any.whl

gdsdiff/extract.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from decimal import Decimal
+from fractions import Fraction
+from pathlib import Path
+from typing import Iterable
+
+import numpy as np
+
+from .config import LayerSpec, parse_layer_selector
+from ._environment import get_environment
+from .gds_metadata import decimal_from_number
+from .geometry import LayerTable, PolygonBuffer, normalize_polygon_points, polygon_bbox, polygon_flags
+from .grid import DEFAULT_COORDINATE_SAFETY_LIMIT, snap_to_grid
+from .inventory import select_top_cell
+from .multiprocessing_support import fork_context
+from .semantics import PathPolicy
+
+_WORKER_RAW_POLYGONS = None
+_WORKER_SELECTED_LAYERS = None
+_WORKER_GRID = None
+_WORKER_UNIT = None
+_WORKER_FAST_SCALE = None
+
+
+@dataclass(frozen=True)
+class ExtractionStats:
+    raw_polygon_count: int
+    kept_polygon_count: int
+    vertex_count: int
+    max_snap_error_dbu: Decimal
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "raw_polygon_count": self.raw_polygon_count,
+            "kept_polygon_count": self.kept_polygon_count,
+            "vertex_count": self.vertex_count,
+            "max_snap_error_dbu": str(self.max_snap_error_dbu),
+        }
+
+
+@dataclass(frozen=True)
+class ExtractionResult:
+    path: Path
+    top_name: str
+    buffer: PolygonBuffer
+    stats: ExtractionStats
+
+
+def extract_gds_polygons(
+    path: str | Path,
+    *,
+    top_name: str | None = None,
+    layers: str | LayerSpec | Iterable[str | tuple[int, int] | LayerSpec] = "all",
+    meters_per_dbu: Decimal | str | float | None = None,
+    path_policy: PathPolicy | str = PathPolicy.GDSTK,
+) -> ExtractionResult:
+    import gdstk
+
+    path = Path(path)
+    path_policy = PathPolicy.coerce(path_policy)
+    if path_policy == PathPolicy.REPORT_ONLY:
+        raise ValueError("report-only path policy cannot produce a passing extraction")
+    lib = gdstk.read_gds(str(path))
+    top = select_top_cell(lib, top_name=top_name)
+    if path_policy == PathPolicy.REJECT and top.get_paths():
+        raise ValueError("selected geometry contains paths and path_policy='reject'")
+    grid = decimal_from_number(meters_per_dbu) if meters_per_dbu is not None else decimal_from_number(lib.precision)
+    unit = decimal_from_number(lib.unit)
+    raw_polygons = top.get_polygons(apply_repetitions=True, include_paths=True)
+    selected_layers = _selected_layer_set(layers, raw_polygons)
+    layer_table = LayerTable(tuple(sorted(selected_layers)))
+    layer_index = layer_table.index_by_layer
+
+    records, max_error = _extract_polygon_records(raw_polygons, selected_layers, grid, unit)
+
+    all_vertices: list[tuple[int, int]] = []
+    offsets: list[int] = [0]
+    layer_ids: list[int] = []
+    bboxes: list[tuple[int, int, int, int]] = []
+    flags: list[int] = []
+    source_ids: list[int] = []
+
+    for source_id, spec, normalized, bbox, polygon_flag in records:
+        all_vertices.extend(normalized)
+        offsets.append(len(all_vertices))
+        layer_ids.append(layer_index[spec])
+        bboxes.append(bbox)
+        flags.append(polygon_flag)
+        source_ids.append(source_id)
+
+    buffer = PolygonBuffer(
+        vertices_xy=np.asarray(all_vertices, dtype=np.int64).reshape((-1, 2)),
+        polygon_offsets=np.asarray(offsets, dtype=np.uint64),
+        layer_ids=np.asarray(layer_ids, dtype=np.uint32),
+        bboxes=np.asarray(bboxes, dtype=np.int64).reshape((-1, 4)),
+        flags=np.asarray(flags, dtype=np.uint32),
+        source_ids=np.asarray(source_ids, dtype=np.uint64),
+        layer_table=layer_table,
+    )
+    return ExtractionResult(
+        path=path,
+        top_name=top.name,
+        buffer=buffer,
+        stats=ExtractionStats(
+            raw_polygon_count=len(raw_polygons),
+            kept_polygon_count=buffer.polygon_count,
+            vertex_count=buffer.vertex_count,
+            max_snap_error_dbu=max_error,
+        ),
+    )
+
+
+def _selected_layer_set(layers, raw_polygons: list[gdstk.Polygon]) -> set[LayerSpec]:
+    if layers == "all":
+        return {LayerSpec(polygon.layer, polygon.datatype) for polygon in raw_polygons}
+    parsed = parse_layer_selector(layers)
+    if parsed == "all":
+        return {LayerSpec(polygon.layer, polygon.datatype) for polygon in raw_polygons}
+    return set(parsed)
+
+
+def _extract_polygon_records(
+    raw_polygons: list[gdstk.Polygon],
+    selected_layers: set[LayerSpec],
+    grid: Decimal,
+    unit: Decimal,
+) -> tuple[
+    list[tuple[int, LayerSpec, tuple[tuple[int, int], ...], tuple[int, int, int, int], int]],
+    Decimal,
+]:
+    fast_scale = _fast_integer_snap_scale(unit, grid)
+    if fast_scale is not None:
+        return _extract_polygon_records_fast(raw_polygons, selected_layers, fast_scale)
+
+    worker_count = _resolve_extract_worker_count(len(raw_polygons))
+    if worker_count <= 1:
+        return _extract_polygon_records_serial(raw_polygons, selected_layers, grid, unit)
+
+    chunk_count = max(worker_count, worker_count * 8)
+    chunk_size = max(1, (len(raw_polygons) + chunk_count - 1) // chunk_count)
+    chunks = tuple((start, min(start + chunk_size, len(raw_polygons))) for start in range(0, len(raw_polygons), chunk_size))
+    context = fork_context()
+    if context is None:
+        return _extract_polygon_records_serial(raw_polygons, selected_layers, grid, unit)
+
+    global _WORKER_RAW_POLYGONS, _WORKER_SELECTED_LAYERS, _WORKER_GRID, _WORKER_UNIT
+    _WORKER_RAW_POLYGONS = raw_polygons
+    _WORKER_SELECTED_LAYERS = selected_layers
+    _WORKER_GRID = grid
+    _WORKER_UNIT = unit
+    try:
+        try:
+            with context.Pool(processes=worker_count) as pool:
+                chunk_results = pool.map(_extract_polygon_records_worker, chunks, chunksize=1)
+        except OSError:
+            return _extract_polygon_records_serial(raw_polygons, selected_layers, grid, unit)
+    finally:
+        _WORKER_RAW_POLYGONS = None
+        _WORKER_SELECTED_LAYERS = None
+        _WORKER_GRID = None
+        _WORKER_UNIT = None
+
+    records = []
+    max_error = Decimal(0)
+    for chunk_records, chunk_max_error in chunk_results:
+        records.extend(chunk_records)
+        max_error = max(max_error, chunk_max_error)
+    records.sort(key=lambda record: record[0])
+    return records, max_error
+
+
+def _fast_integer_snap_scale(unit: Decimal, grid: Decimal) -> int | None:
+    if get_environment("GDSDIFF_EXTRACT_DECIMAL", "GDS_GPU_COMPARE_EXTRACT_DECIMAL") == "1":
+        return None
+    try:
+        ratio = Fraction(unit) / Fraction(grid)
+    except (ArithmeticError, ValueError):
+        return None
+    if ratio.denominator != 1:
+        return None
+    scale = ratio.numerator
+    if scale <= 0:
+        return None
+    return scale
+
+
+def _extract_polygon_records_fast(
+    raw_polygons: list[gdstk.Polygon],
+    selected_layers: set[LayerSpec],
+    scale: int,
+) -> tuple[
+    list[tuple[int, LayerSpec, tuple[tuple[int, int], ...], tuple[int, int, int, int], int]],
+    Decimal,
+]:
+    worker_count = _resolve_extract_worker_count(len(raw_polygons))
+    if worker_count <= 1:
+        return _extract_polygon_records_fast_from_range(raw_polygons, selected_layers, scale, 0, len(raw_polygons))
+
+    chunk_count = max(worker_count, worker_count * 8)
+    chunk_size = max(1, (len(raw_polygons) + chunk_count - 1) // chunk_count)
+    chunks = tuple((start, min(start + chunk_size, len(raw_polygons))) for start in range(0, len(raw_polygons), chunk_size))
+    context = fork_context()
+    if context is None:
+        return _extract_polygon_records_fast_from_range(raw_polygons, selected_layers, scale, 0, len(raw_polygons))
+
+    global _WORKER_RAW_POLYGONS, _WORKER_SELECTED_LAYERS, _WORKER_FAST_SCALE
+    _WORKER_RAW_POLYGONS = raw_polygons
+    _WORKER_SELECTED_LAYERS = selected_layers
+    _WORKER_FAST_SCALE = scale
+    try:
+        try:
+            with context.Pool(processes=worker_count) as pool:
+                chunk_results = pool.map(_extract_polygon_records_fast_worker, chunks, chunksize=1)
+        except OSError:
+            return _extract_polygon_records_fast_from_range(raw_polygons, selected_layers, scale, 0, len(raw_polygons))
+    finally:
+        _WORKER_RAW_POLYGONS = None
+        _WORKER_SELECTED_LAYERS = None
+        _WORKER_FAST_SCALE = None
+
+    records = []
+    max_error = Decimal(0)
+    for chunk_records, chunk_max_error in chunk_results:
+        records.extend(chunk_records)
+        max_error = max(max_error, chunk_max_error)
+    records.sort(key=lambda record: record[0])
+    return records, max_error
+
+
+def _extract_polygon_records_fast_worker(
+    chunk: tuple[int, int],
+) -> tuple[
+    list[tuple[int, LayerSpec, tuple[tuple[int, int], ...], tuple[int, int, int, int], int]],
+    Decimal,
+]:
+    if _WORKER_RAW_POLYGONS is None or _WORKER_SELECTED_LAYERS is None or _WORKER_FAST_SCALE is None:
+        raise RuntimeError("fast extraction worker globals are not initialized")
+    start, stop = chunk
+    return _extract_polygon_records_fast_from_range(
+        _WORKER_RAW_POLYGONS,
+        _WORKER_SELECTED_LAYERS,
+        _WORKER_FAST_SCALE,
+        start,
+        stop,
+    )
+
+
+def _extract_polygon_records_fast_from_range(
+    raw_polygons: list[gdstk.Polygon],
+    selected_layers: set[LayerSpec],
+    scale: int,
+    start: int,
+    stop: int,
+) -> tuple[
+    list[tuple[int, LayerSpec, tuple[tuple[int, int], ...], tuple[int, int, int, int], int]],
+    Decimal,
+]:
+    records = []
+    max_error = 0.0
+    float_scale = float(scale)
+    for source_id in range(start, stop):
+        polygon = raw_polygons[source_id]
+        spec = LayerSpec(polygon.layer, polygon.datatype)
+        if spec not in selected_layers:
+            continue
+        points = np.asarray(polygon.points, dtype=np.float64)
+        if points.size == 0:
+            continue
+        scaled = points * float_scale
+        snapped = _round_half_away_from_zero(scaled)
+        if snapped.size and np.max(np.abs(snapped)) > DEFAULT_COORDINATE_SAFETY_LIMIT:
+            raise OverflowError("coordinate exceeds configured safety limit")
+        max_error = max(max_error, float(np.max(np.abs(scaled - snapped))))
+        snapped_points = tuple((int(x), int(y)) for x, y in snapped.astype(np.int64, copy=False))
+        normalized = normalize_polygon_points(snapped_points)
+        if not normalized:
+            continue
+        records.append((source_id, spec, normalized, polygon_bbox(normalized), polygon_flags(normalized)))
+    return records, Decimal(str(max_error))
+
+
+def _round_half_away_from_zero(values: np.ndarray) -> np.ndarray:
+    return np.copysign(np.floor(np.abs(values) + 0.5), values)
+
+
+def _resolve_extract_worker_count(raw_polygon_count: int) -> int:
+    if raw_polygon_count < _parallel_min_polygons():
+        return 1
+    return max(1, os.cpu_count() or 1)
+
+
+def _parallel_min_polygons() -> int:
+    try:
+        value = int(
+            get_environment(
+                "GDSDIFF_PARALLEL_MIN_POLYGONS",
+                "GDS_GPU_COMPARE_PARALLEL_MIN_POLYGONS",
+                "",
+            )
+            or ""
+        )
+    except ValueError:
+        return 30_000
+    return value if value > 0 else 30_000
+
+
+def _extract_polygon_records_serial(
+    raw_polygons: list[gdstk.Polygon],
+    selected_layers: set[LayerSpec],
+    grid: Decimal,
+    unit: Decimal,
+) -> tuple[
+    list[tuple[int, LayerSpec, tuple[tuple[int, int], ...], tuple[int, int, int, int], int]],
+    Decimal,
+]:
+    return _extract_polygon_records_from_range(raw_polygons, selected_layers, grid, unit, 0, len(raw_polygons))
+
+
+def _extract_polygon_records_worker(
+    chunk: tuple[int, int],
+) -> tuple[
+    list[tuple[int, LayerSpec, tuple[tuple[int, int], ...], tuple[int, int, int, int], int]],
+    Decimal,
+]:
+    if (
+        _WORKER_RAW_POLYGONS is None
+        or _WORKER_SELECTED_LAYERS is None
+        or _WORKER_GRID is None
+        or _WORKER_UNIT is None
+    ):
+        raise RuntimeError("extraction worker globals are not initialized")
+    start, stop = chunk
+    return _extract_polygon_records_from_range(
+        _WORKER_RAW_POLYGONS,
+        _WORKER_SELECTED_LAYERS,
+        _WORKER_GRID,
+        _WORKER_UNIT,
+        start,
+        stop,
+    )
+
+
+def _extract_polygon_records_from_range(
+    raw_polygons: list[gdstk.Polygon],
+    selected_layers: set[LayerSpec],
+    grid: Decimal,
+    unit: Decimal,
+    start: int,
+    stop: int,
+) -> tuple[
+    list[tuple[int, LayerSpec, tuple[tuple[int, int], ...], tuple[int, int, int, int], int]],
+    Decimal,
+]:
+    records = []
+    max_error = Decimal(0)
+    for source_id in range(start, stop):
+        polygon = raw_polygons[source_id]
+        spec = LayerSpec(polygon.layer, polygon.datatype)
+        if spec not in selected_layers:
+            continue
+        snapped_points: list[tuple[int, int]] = []
+        for point in polygon.points:
+            x_physical = decimal_from_number(float(point[0])) * unit
+            y_physical = decimal_from_number(float(point[1])) * unit
+            x = snap_to_grid(x_physical, grid)
+            y = snap_to_grid(y_physical, grid)
+            max_error = max(max_error, abs(x_physical / grid - Decimal(x)), abs(y_physical / grid - Decimal(y)))
+            snapped_points.append((x, y))
+        normalized = normalize_polygon_points(snapped_points)
+        if not normalized:
+            continue
+        records.append((source_id, spec, normalized, polygon_bbox(normalized), polygon_flags(normalized)))
+    return records, max_error

gdsdiff/gds_metadata.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from pathlib import Path
+
+
+def decimal_from_number(value: int | float | str | Decimal) -> Decimal:
+    if isinstance(value, Decimal):
+        return value
+    return Decimal(str(value))
+
+
+@dataclass(frozen=True)
+class GdsMetadata:
+    path: Path
+    unit_m: Decimal
+    precision_m: Decimal
+    cell_count: int
+    top_names: tuple[str, ...]
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "path": str(self.path),
+            "unit_m": str(self.unit_m),
+            "precision_m": str(self.precision_m),
+            "cell_count": self.cell_count,
+            "top_names": list(self.top_names),
+        }
+
+
+def read_gds_metadata(path: str | Path) -> GdsMetadata:
+    import gdstk
+
+    path = Path(path)
+    lib = gdstk.read_gds(str(path))
+    return GdsMetadata(
+        path=path,
+        unit_m=decimal_from_number(lib.unit),
+        precision_m=decimal_from_number(lib.precision),
+        cell_count=len(lib.cells),
+        top_names=tuple(cell.name for cell in lib.top_level()),
+    )

gdsdiff/geometry.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .config import LayerSpec
+
+FLAG_FEWER_THAN_THREE_POINTS = 1 << 0
+FLAG_ZERO_AREA = 1 << 1
+
+
+@dataclass(frozen=True)
+class LayerTable:
+    layers: tuple[LayerSpec, ...]
+
+    def __post_init__(self) -> None:
+        if len(set(self.layers)) != len(self.layers):
+            raise ValueError("LayerTable cannot contain duplicate layers")
+
+    @property
+    def index_by_layer(self) -> dict[LayerSpec, int]:
+        return {layer: index for index, layer in enumerate(self.layers)}
+
+    def to_json(self) -> list[dict[str, int]]:
+        return [layer.to_json() for layer in self.layers]
+
+
+@dataclass(frozen=True)
+class PolygonBuffer:
+    vertices_xy: np.ndarray
+    polygon_offsets: np.ndarray
+    layer_ids: np.ndarray
+    bboxes: np.ndarray
+    flags: np.ndarray
+    source_ids: np.ndarray
+    layer_table: LayerTable
+    polygon_hashes: np.ndarray | None = None
+
+    def __post_init__(self) -> None:
+        if self.vertices_xy.dtype != np.int64 or self.vertices_xy.ndim != 2 or self.vertices_xy.shape[1] != 2:
+            raise TypeError("vertices_xy must be an int64 array with shape (N, 2)")
+        if self.polygon_offsets.dtype != np.uint64 or self.polygon_offsets.ndim != 1:
+            raise TypeError("polygon_offsets must be a uint64 vector")
+        if self.layer_ids.dtype != np.uint32 or self.layer_ids.ndim != 1:
+            raise TypeError("layer_ids must be a uint32 vector")
+        if self.bboxes.dtype != np.int64 or self.bboxes.shape != (self.polygon_count, 4):
+            raise TypeError("bboxes must be an int64 array with shape (N_polygons, 4)")
+        if self.flags.dtype != np.uint32 or self.flags.shape != (self.polygon_count,):
+            raise TypeError("flags must be a uint32 vector with one entry per polygon")
+        if self.source_ids.dtype != np.uint64 or self.source_ids.shape != (self.polygon_count,):
+            raise TypeError("source_ids must be a uint64 vector with one entry per polygon")
+        if self.polygon_hashes is not None and (
+            self.polygon_hashes.dtype != np.uint64 or self.polygon_hashes.shape != (self.polygon_count, 2)
+        ):
+            raise TypeError("polygon_hashes must be a uint64 array with shape (N_polygons, 2)")
+        if len(self.polygon_offsets) != self.polygon_count + 1:
+            raise ValueError("polygon_offsets length must be polygon_count + 1")
+        if len(self.polygon_offsets) and int(self.polygon_offsets[0]) != 0:
+            raise ValueError("polygon_offsets must start at zero")
+        if len(self.polygon_offsets) and int(self.polygon_offsets[-1]) != self.vertex_count:
+            raise ValueError("final polygon offset must equal vertex count")
+
+    @property
+    def polygon_count(self) -> int:
+        return len(self.layer_ids)
+
+    @property
+    def vertex_count(self) -> int:
+        return len(self.vertices_xy)
+
+    def polygon_vertices(self, index: int) -> np.ndarray:
+        start = int(self.polygon_offsets[index])
+        end = int(self.polygon_offsets[index + 1])
+        return self.vertices_xy[start:end]
+
+
+def normalize_polygon_points(points: list[tuple[int, int]]) -> tuple[tuple[int, int], ...]:
+    if len(points) > 1 and points[0] == points[-1]:
+        points = points[:-1]
+    normalized: list[tuple[int, int]] = []
+    for point in points:
+        if not normalized or normalized[-1] != point:
+            normalized.append(point)
+    if len(normalized) > 1 and normalized[0] == normalized[-1]:
+        normalized.pop()
+    return tuple(normalized)
+
+
+def polygon_bbox(points: tuple[tuple[int, int], ...]) -> tuple[int, int, int, int]:
+    xs = [point[0] for point in points]
+    ys = [point[1] for point in points]
+    return min(xs), min(ys), max(xs), max(ys)
+
+
+def polygon_twice_area(points: tuple[tuple[int, int], ...]) -> int:
+    if len(points) < 3:
+        return 0
+    area = 0
+    for index, point in enumerate(points):
+        next_point = points[(index + 1) % len(points)]
+        area += point[0] * next_point[1] - next_point[0] * point[1]
+    return abs(area)
+
+
+def polygon_flags(points: tuple[tuple[int, int], ...]) -> int:
+    flags = 0
+    if len(set(points)) < 3:
+        flags |= FLAG_FEWER_THAN_THREE_POINTS
+    if polygon_twice_area(points) == 0:
+        flags |= FLAG_ZERO_AREA
+    return flags

gdsdiff/grid.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from fractions import Fraction
+from math import gcd, lcm
+
+from .config import GridSpec
+from .gds_metadata import GdsMetadata, decimal_from_number
+
+INT64_LIMIT = 2**63 - 1
+DEFAULT_COORDINATE_SAFETY_LIMIT = 2**62
+MAX_AUTO_GRID_DENOMINATOR = 10**18
+
+
+@dataclass(frozen=True)
+class GridResolution:
+    grid: GridSpec
+    ratio_residual: Decimal
+    method: str
+
+    def to_json(self) -> dict[str, object]:
+        data = self.grid.to_json()
+        data["ratio_residual"] = str(self.ratio_residual)
+        data["method"] = self.method
+        return data
+
+
+def _fraction_from_decimal(value: Decimal) -> Fraction:
+    return Fraction(value)
+
+
+def _decimal_from_fraction(value: Fraction) -> Decimal:
+    return Decimal(value.numerator) / Decimal(value.denominator)
+
+
+def _rational_gcd(left: Fraction, right: Fraction) -> Fraction:
+    numerator = gcd(abs(left.numerator), abs(right.numerator))
+    denominator = lcm(left.denominator, right.denominator)
+    return Fraction(numerator, denominator)
+
+
+def _integer_related(left: Decimal, right: Decimal) -> bool:
+    larger = max(left, right)
+    smaller = min(left, right)
+    ratio = larger / smaller
+    return ratio == ratio.to_integral_value()
+
+
+def resolve_comparison_grid(
+    old: GdsMetadata,
+    new: GdsMetadata,
+    *,
+    dbu: Decimal | str | float | None = None,
+    precision: Decimal | str | float | None = None,
+    max_denominator: int = MAX_AUTO_GRID_DENOMINATOR,
+) -> GridResolution:
+    explicit_dbu = decimal_from_number(dbu) if dbu is not None else None
+    explicit_precision = decimal_from_number(precision) if precision is not None else None
+    if explicit_dbu is not None and explicit_precision is not None and explicit_dbu != explicit_precision:
+        raise ValueError("explicit dbu and precision must match")
+    explicit = explicit_dbu if explicit_dbu is not None else explicit_precision
+    if explicit is not None:
+        _validate_positive_decimal(explicit, "comparison grid")
+        return GridResolution(
+            grid=GridSpec(
+                meters_per_dbu=explicit,
+                source_old_precision_m=old.precision_m,
+                source_new_precision_m=new.precision_m,
+                selection_mode="explicit",
+            ),
+            ratio_residual=Decimal(0),
+            method="explicit",
+        )
+
+    old_precision = old.precision_m
+    new_precision = new.precision_m
+    _validate_positive_decimal(old_precision, "old precision")
+    _validate_positive_decimal(new_precision, "new precision")
+
+    if old_precision == new_precision:
+        selected = old_precision
+        method = "equal-source-precision"
+    elif _integer_related(old_precision, new_precision):
+        selected = min(old_precision, new_precision)
+        method = "integer-related-source-precision"
+    else:
+        old_fraction = _fraction_from_decimal(old_precision)
+        new_fraction = _fraction_from_decimal(new_precision)
+        selected_fraction = _rational_gcd(old_fraction, new_fraction)
+        if selected_fraction.denominator > max_denominator:
+            raise ValueError("automatic grid denominator exceeds limit; pass explicit dbu")
+        selected = _decimal_from_fraction(selected_fraction)
+        method = "rational-common-subgrid"
+
+    return GridResolution(
+        grid=GridSpec(
+            meters_per_dbu=selected,
+            source_old_precision_m=old_precision,
+            source_new_precision_m=new_precision,
+            selection_mode="auto",
+        ),
+        ratio_residual=Decimal(0),
+        method=method,
+    )
+
+
+def snap_to_grid(value_m: Decimal | str | float | int, meters_per_dbu: Decimal | str | float) -> int:
+    value = decimal_from_number(value_m)
+    q = decimal_from_number(meters_per_dbu)
+    _validate_positive_decimal(q, "meters_per_dbu")
+    scaled = value / q
+    sign = -1 if scaled < 0 else 1
+    magnitude = abs(scaled)
+    whole = int(magnitude)
+    fraction = magnitude - whole
+    if fraction >= Decimal("0.5"):
+        whole += 1
+    snapped = sign * whole
+    validate_int64_coordinate(snapped)
+    return snapped
+
+
+def max_snap_error_dbu(values_m: list[Decimal], meters_per_dbu: Decimal) -> Decimal:
+    if not values_m:
+        return Decimal(0)
+    errors = []
+    for value in values_m:
+        snapped = Decimal(snap_to_grid(value, meters_per_dbu))
+        errors.append(abs(value / meters_per_dbu - snapped))
+    return max(errors)
+
+
+def validate_int64_coordinate(value: int, *, safety_limit: int = DEFAULT_COORDINATE_SAFETY_LIMIT) -> None:
+    if abs(value) > INT64_LIMIT:
+        raise OverflowError("coordinate exceeds signed int64 range")
+    if abs(value) > safety_limit:
+        raise OverflowError("coordinate exceeds configured safety limit")
+
+
+def _validate_positive_decimal(value: Decimal, name: str) -> None:
+    if not value.is_finite() or value <= 0:
+        raise ValueError(f"{name} must be finite and positive")