Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
58
docs/comparison.md
Normal file
58
docs/comparison.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
# Comparison rules
|
||||
|
||||
Pheon compares GDSII objects using the `klamath-object-v2` 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.
|
||||
Loading…
Reference in a new issue