pheon/docs/comparison.md

58 lines
2.7 KiB
Markdown
Raw Normal View History

# 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](cli.md) 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
Unmatched objects can be paired to explain a replacement when the pairing is
unique by kind, layer, and bounds, then by kind and layer. References also use
their target cell. Ambiguous candidates remain independent removals and
additions. Pairing helps explain the report; it does not establish persistent
object identity or change the underlying 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](layer-names.md) 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](diff-reports.md) describes the status fields and retained
evidence.