pheon/docs/comparison.md

2.8 KiB

Comparison rules

Pheon compares GDSII objects using the pheon-structural-v1 profile. Use it to review exact layout changes while ignoring incidental ordering and timestamps. The CLI guide explains how to choose cells and layers.

What counts as equal

Cells match by name and layers by numeric layer/type pair. By default, the comparison includes the entire library.

Pheon ignores library and cell timestamps, cell order, element order, and property order. Boundary and box rings are normalized for their starting vertex and winding direction. Other vertices remain significant. Repeated objects and properties are compared as multisets, so duplicates still count.

Other retained details compare exactly: paths, labels, reference transforms, array endpoints and counts, properties, and flags. An explicitly stored default is distinct from an omitted field. An SREF is distinct from a one-element AREF. REAL8 encodings are retained, so differently encoded values can compare as changed even when their decoded values agree.

Library fields, including UNITS, compare separately. Coordinates are not rescaled to a shared grid. Cell renames are additions and deletions; Pheon does not infer identity from similar content. It does not perform geometric Boolean operations, XOR, or tolerance-based matching.

Read change explanations

Pheon first pairs unmatched polygons, boxes, and paths that differ only in layer or type, with exactly one candidate in each revision. It then checks the remaining objects for unique matches by kind, layer, and bounds, followed by kind and layer. Reference matching uses the target cell. Ambiguous candidates are reported as separate removals and additions. These explanations apply to the current report and preserve the underlying addition and removal counts.

Reported bounds are envelopes of stored coordinates in cell-local database units. They exclude path width, rendered text size, and recursively transformed reference geometry. Account for UNITS before interpreting a physical dimension or movement.

Recognized layer-name annotations are removed from ordinary object comparison. Their name mapping compares separately, so a layer rename appears once.

Know when a result is incomplete

Unsupported records, future metadata versions, unresolved references, and hierarchy cycles prevent a complete comparison. Pheon reports known differences but returns 2 rather than claiming equality.

Scope can exclude a record known to belong to another layer. Unsupported records whose layer is unknown can still make a layer-scoped comparison incomplete. Library fields and future metadata diagnostics remain visible. Malformed input fails before scope is applied.

For automation, check completeness as well as differences. The JSON report reference describes the status fields and retained evidence.