Simplify and speed up GDSII diffs

Summarize added and removed cells, group references, and keep replacement pairs together at text display limits. Trim hierarchy labels and summarize long unmatched paths.

Stream JSON object evidence and reduce parsing and comparison allocations. Parse large revisions concurrently and adaptively reuse matching cell bodies when most of the layout is shared.
This commit is contained in:
Jan Petykiewicz 2026-11-18 10:58:19 -08:00
commit 8efeb04aab
3 changed files with 1137 additions and 261 deletions

View file

@ -46,13 +46,18 @@ pheon diff before.gds after.gds --hierarchy ascii --max-changes 20
pheon diff before.gds after.gds --format json > report.json
```
Text reports start with the result and group changes by cell. Added and removed
cell headings give the object count within the comparison scope. Each layer
lists counts of rectangles, polygons, and boxes changed, moved, added, or removed.
Added or removed cells also count references by target.
Other objects use `-` for removals, `+` for additions, and `~` for likely
replacements. Use `--format json` for details of individual objects and
`--hierarchy` to see which parent cells are affected.
Text reports start with the result and counts of modified, added, and removed
cells. Added and removed cells show their object counts and group references by
target. Modified cells show counts of rectangles, polygons, and boxes changed,
moved, added, or removed on each layer. Repeated reference additions or removals
to the same target also appear as a count. Object details use `-` for removals,
`+` for additions, and `~` for likely replacements. Unmatched paths with five
or more vertices show their width, vertex count, and vertex bounds in one line.
Use `--format json` for details of individual objects and `--hierarchy` to see
which parent cells are affected.
For large unscoped diffs with substantial byte overlap, Pheon reuses parsed
contents of matching cells. Cell timestamps and file offsets can differ.
| Exit code | Meaning |
| --- | --- |
@ -95,14 +100,16 @@ pheon diff before.gds after.gds --hierarchy mermaid --depth 4
`--show-cell` and `--show-layer` filter displayed changes without changing the
comparison, totals, or exit status. A layer display filter hides references
without a numeric layer. `--max-changes N` limits displayed object occurrences.
A paired replacement uses two occurrences. The text report counts omissions
from filters and limits before listing cell changes. JSON includes all changed
objects unless the limit is explicit.
Text shows a replacement only when both objects fit within the limit.
A single omission line lists changes hidden by filters or the limit. JSON
includes all changed objects unless the limit is explicit.
The diff hierarchy marks directly changed cells, affected ancestors, and
unchanged targets of modified references. It includes references from both
revisions so removed branches remain visible. Counts represent direct placements;
arrays remain symbolic. `--depth` limits text diagrams. For a complete graph in
The diff hierarchy shows directly changed cells, affected ancestors, and targets
of modified references. It includes references from both revisions so removed
branches remain visible. Counts represent direct placements;
arrays remain symbolic. ASCII omits the section when there are no cell changes
and marks reference changes whose placement count stays the same.
`--depth` limits text diagrams. For a complete graph in
JSON, use `--format json --hierarchy graph`; text depth and display filters do
not trim that graph.

View file

@ -23,9 +23,10 @@ Add this to `.git/config`, or use the same section in your user Git config:
```
Then run `git diff` as usual. The driver reads Git's temporary old and new files
and handles additions, deletions, and renames. Keep the final `--`: Git appends
its path and revision arguments after it. Put Pheon options before that marker,
for example `--top CHIP` or `--show-layer 1/0`.
and handles additions, deletions, and renames. The heading names the file and
indicates whether it was added or deleted. Keep the final `--` because Git appends
its path and revision arguments after it. Put Pheon options such as `--top CHIP`
or `--show-layer 1/0` before that marker.
For an existing `diff=layout` attribute, put the configuration under
`[diff "layout"]` instead. Attribute names only select a Git driver.

View file

@ -26,10 +26,19 @@ Layout-review APIs live in `pheon::review`, with layer-name helpers in
`Comparison::between(&old, &new)` captures an owned result with revision metadata,
changes, and structured diagnostics. Use `outcome()` for completeness, equality,
and exit status. Its `text`, `json_report`, and `hierarchy` renderers work after
the source documents and byte buffers are dropped. Standalone hierarchy inspection
uses `Document::hierarchy`. Reference counts are captured with the result;
union-graph and ancestor analysis run only when a hierarchy is requested.
and exit status. Its renderers work after the source documents and byte buffers
are dropped. `json_report` returns a JSON value, and `write_json_report` writes
object evidence incrementally to a writer. `Document::hierarchy` inspects a
single revision. A comparison captures reference counts and analyzes the union
graph and ancestors when a hierarchy is requested.
`TextComparison::between` captures the data needed for text and hierarchy
reports. Layered objects in added and removed cells contribute to the cell's
object count.
Use `RevisionPair::parse(&old_bytes, &new_bytes)` for an unscoped comparison
that can reuse matching cells. Its `compare` and `compare_text` methods return
the corresponding owned comparison.
The `record`, `records`, and `basic` modules also provide low-level GDSII record
writing. There is no high-level writer for the Arrow layout. REAL8 writing is