2026-11-16 16:51:41 -08:00
|
|
|
|
# Command-line tools
|
|
|
|
|
|
|
|
|
|
|
|
Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references.
|
2026-11-17 16:14:53 -08:00
|
|
|
|
The CLI recognizes gzip-compressed GDSII by its file header. Reported byte offsets
|
|
|
|
|
|
refer to the decompressed layout. The CLI runs independently of Python.
|
2026-11-16 16:51:41 -08:00
|
|
|
|
|
|
|
|
|
|
## Install
|
|
|
|
|
|
|
2026-11-17 15:07:40 -08:00
|
|
|
|
If you downloaded a CLI archive, extract it and add the directory containing
|
|
|
|
|
|
`pheon` (`pheon.exe` on Windows) to your `PATH`. Run `pheon --help` to check it.
|
|
|
|
|
|
|
|
|
|
|
|
To install from a source checkout, use Rust 1.88 or newer:
|
2026-11-16 16:51:41 -08:00
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
cargo install --path . --locked --bin pheon
|
|
|
|
|
|
pheon --help
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
You can also build locally with `cargo build --release --locked --bin pheon`
|
|
|
|
|
|
and run `target/release/pheon` (`pheon.exe` on Windows).
|
|
|
|
|
|
|
|
|
|
|
|
## Inspect a layout
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
pheon dump chip.gds
|
|
|
|
|
|
pheon dump chip.gds --records
|
|
|
|
|
|
pheon hierarchy chip.gds --format ascii --depth 4
|
|
|
|
|
|
pheon hierarchy chip.gds --format mermaid --top CHIP
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 21:49:26 -08:00
|
|
|
|
`dump` lists objects by cell. A prefix such as `3x` counts copies of the same
|
|
|
|
|
|
normalized object within a cell. Coordinates are in database units. Rectangles
|
|
|
|
|
|
show two corners, and longer vertex lists wrap across lines. References show
|
|
|
|
|
|
the target and any array dimensions before the coordinates. Add `--records`
|
2026-11-18 22:58:12 -08:00
|
|
|
|
to inspect the original record sequence, including timestamps. In color
|
|
|
|
|
|
output, the object dump highlights cell headings and layer numbers, and the
|
|
|
|
|
|
record dump highlights record names.
|
2026-11-17 21:49:26 -08:00
|
|
|
|
|
2026-11-18 22:58:12 -08:00
|
|
|
|
`hierarchy` shows direct placement counts on references. `[subtree elided]`
|
|
|
|
|
|
marks a repeated cell whose children were skipped. Repeated leaves show
|
|
|
|
|
|
each parent's placement count without the marker. At the depth limit,
|
|
|
|
|
|
`[children omitted]` marks a cell with further descendants. Mermaid
|
|
|
|
|
|
output is diagram source for a Mermaid renderer.
|
2026-11-16 16:51:41 -08:00
|
|
|
|
|
|
|
|
|
|
## Compare revisions
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
pheon diff before.gds after.gds
|
|
|
|
|
|
pheon diff before.gds after.gds --hierarchy ascii --max-changes 20
|
|
|
|
|
|
pheon diff before.gds after.gds --format json > report.json
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-18 20:12:42 -08:00
|
|
|
|
Text reports start with the result. The headline includes cell counts for
|
|
|
|
|
|
reports with more than three changed cells, incomplete comparisons, or omitted
|
|
|
|
|
|
changes. The `Cells:` section lists removals with `-`, additions with `+`, and
|
|
|
|
|
|
modifications with `*`. Modified cells show counts of rectangles, polygons, and
|
2026-11-18 23:01:57 -08:00
|
|
|
|
boxes changed, moved, added, or removed on each layer. When the only displayed
|
|
|
|
|
|
shape change on a layer is a move, the row shows its displacement in database
|
|
|
|
|
|
units. Repeated reference additions or removals to the same target appear as a
|
|
|
|
|
|
count. When both occur for one target, they share a row. A complete set of edits
|
|
|
|
|
|
to a target also shows
|
2026-11-18 20:12:42 -08:00
|
|
|
|
the total direct placements when there are unchanged placements, for example
|
|
|
|
|
|
`leaf · -3 refs, +6 refs · placements 10 -> 13`.
|
|
|
|
|
|
|
|
|
|
|
|
An unchanged layer name appears inline when the layer occurs on one displayed
|
2026-11-18 23:01:57 -08:00
|
|
|
|
row, as in `1/0 (WG): rectangle moved by (20, -5) dbu`. A layer on several
|
|
|
|
|
|
displayed rows gets one legend entry. Object details use `-` for removals, `+` for additions,
|
2026-11-18 20:12:42 -08:00
|
|
|
|
and `~` for likely replacements. Identical unmatched objects share a row
|
|
|
|
|
|
with a count such as `+ 12× 1/0: path …`. Unmatched paths with five or more
|
|
|
|
|
|
vertices show their width, vertex count, and vertex bounds in one line.
|
2026-11-18 23:16:09 -08:00
|
|
|
|
A unique polygon, box, or path replacement that differs only in layer or
|
|
|
|
|
|
datatype appears on one row, for example `~ 1/0 (WG) → 2/0 (CORE) · rectangle`.
|
2026-11-18 20:12:42 -08:00
|
|
|
|
|
2026-11-18 10:58:19 -08:00
|
|
|
|
Use `--format json` for details of individual objects and `--hierarchy` to see
|
|
|
|
|
|
which parent cells are affected.
|
|
|
|
|
|
|
2026-11-18 22:58:12 -08:00
|
|
|
|
`diff` and `dump` use `--color auto` by default. Colors appear on supported
|
|
|
|
|
|
terminals and are disabled when `NO_COLOR` is set or `TERM=dumb`. Use
|
|
|
|
|
|
`--color=always` to keep colors in a pipe, for example
|
|
|
|
|
|
`pheon diff before.gds after.gds --color=always | less -R`. Use
|
|
|
|
|
|
`--color=never` for plain text. JSON reports and Mermaid diagram source stay plain.
|
|
|
|
|
|
|
2026-11-18 10:58:19 -08:00
|
|
|
|
For large unscoped diffs with substantial byte overlap, Pheon reuses parsed
|
|
|
|
|
|
contents of matching cells. Cell timestamps and file offsets can differ.
|
2026-11-16 16:51:41 -08:00
|
|
|
|
|
|
|
|
|
|
| Exit code | Meaning |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| 0 | Equal under the comparison rules and selected scope. |
|
|
|
|
|
|
| 1 | Differences found in a complete comparison. |
|
|
|
|
|
|
| 2 | Invalid input, a command error, or an incomplete comparison. |
|
|
|
|
|
|
|
|
|
|
|
|
A code of 1 is an expected comparison result. A code of 2 can accompany definite
|
|
|
|
|
|
differences, but equality cannot be established. Read the
|
|
|
|
|
|
[comparison rules](comparison.md) before relying on results in automation, and
|
|
|
|
|
|
the [JSON reference](diff-reports.md) to consume reports programmatically.
|
|
|
|
|
|
|
|
|
|
|
|
## Choose the comparison scope
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
pheon diff before.gds after.gds --top CHIP --layer 1/0
|
|
|
|
|
|
pheon diff before.gds after.gds --cell RESONATOR
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
| Option | Compared content |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| `--top NAME` | The named cell and its reachable descendants in each revision. |
|
|
|
|
|
|
| `--cell NAME` | One cell, including its references, without its descendants. |
|
2026-11-18 23:07:22 -08:00
|
|
|
|
| `--layer L/T\|NAME` | Objects on the selected layer/type pair, plus references leading to that layer. |
|
2026-11-16 16:51:41 -08:00
|
|
|
|
|
|
|
|
|
|
Selectors combine: `--top CHIP --cell RESONATOR` selects that cell within CHIP's
|
|
|
|
|
|
subtree. A name absent from both revisions is an error; presence on only one
|
|
|
|
|
|
side is an addition or deletion. Layer selection omits cells irrelevant to that
|
|
|
|
|
|
layer, but library fields and metadata-version diagnostics remain relevant.
|
|
|
|
|
|
The complete input is parsed before scope selection, so malformed records
|
|
|
|
|
|
outside the scope still fail the command.
|
|
|
|
|
|
|
2026-11-18 23:07:22 -08:00
|
|
|
|
Both `--layer` and `--show-layer` accept exact, case-sensitive names from the
|
|
|
|
|
|
embedded metadata in either revision. If a name refers to several numeric pairs,
|
|
|
|
|
|
Pheon lists the choices. A valid numeric pair always selects that pair directly.
|
|
|
|
|
|
|
2026-11-16 16:51:41 -08:00
|
|
|
|
## Control report detail
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
2026-11-18 23:07:22 -08:00
|
|
|
|
pheon diff before.gds after.gds --show-cell RESONATOR --show-layer WG
|
2026-11-18 23:20:00 -08:00
|
|
|
|
pheon diff before.gds after.gds --show-cell RESONATOR --details --max-changes 20
|
2026-11-16 16:51:41 -08:00
|
|
|
|
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
|
2026-11-18 12:37:10 -08:00
|
|
|
|
without a numeric layer. `--max-changes N` limits displayed object occurrences
|
|
|
|
|
|
after filtering. Text defaults to 100 occurrences and shows a replacement only
|
2026-11-18 20:12:42 -08:00
|
|
|
|
when both objects fit within the limit. Grouped rows count each object toward
|
2026-11-18 23:16:09 -08:00
|
|
|
|
the limit. When a layer filter selects one side of a layer-only replacement,
|
|
|
|
|
|
that side appears as an addition or removal. A single omission line lists
|
|
|
|
|
|
changes hidden by filters or the limit. JSON has no default object limit and reports
|
2026-11-18 12:37:10 -08:00
|
|
|
|
omissions from both display filters and any explicit limit in `report_selection`.
|
|
|
|
|
|
See the [JSON reference](diff-reports.md) for the selection counters.
|
2026-11-16 16:51:41 -08:00
|
|
|
|
|
2026-11-18 23:20:00 -08:00
|
|
|
|
`--details` shows individual object evidence inside modified cells in text
|
|
|
|
|
|
reports. Replacement rows include a nested `-` row for the old object and a
|
|
|
|
|
|
`+` row for the new object, with cell-local coordinates in database units,
|
|
|
|
|
|
retained fields, and properties. Both sides count toward `--max-changes`.
|
|
|
|
|
|
For added and removed cells, the report lists the cell name.
|
|
|
|
|
|
|
2026-11-18 10:58:19 -08:00
|
|
|
|
The diff hierarchy shows directly changed cells, affected ancestors, and targets
|
|
|
|
|
|
of modified references. It includes references from both revisions so removed
|
2026-11-18 12:37:10 -08:00
|
|
|
|
branches remain visible. Counts represent direct placements, with symbolic
|
2026-11-18 20:12:42 -08:00
|
|
|
|
counts for arrays. ASCII uses the cell list's change markers and marks
|
|
|
|
|
|
reference changes whose placement count stays the same. When the cell list
|
|
|
|
|
|
shows all edits to an unchanged target on a single branch, ASCII can omit
|
|
|
|
|
|
that terminal edge. The hierarchy retains ancestor paths, shared branches,
|
|
|
|
|
|
and edges with edits hidden by display filters or limits. ASCII appears when
|
2026-11-18 23:04:24 -08:00
|
|
|
|
there are relationships to show. ASCII diffs fold chains of three or more cells
|
|
|
|
|
|
along unchanged single-placement edges, for example `CHIP → block → * leaf`.
|
|
|
|
|
|
Branch points and changed edges keep their own rows. `--depth` counts the
|
|
|
|
|
|
original edges.
|
2026-11-18 12:37:10 -08:00
|
|
|
|
For the complete graph within the comparison scope, use
|
|
|
|
|
|
`--format json --hierarchy graph` without `--depth`. Display filters leave the
|
|
|
|
|
|
graph intact.
|
2026-11-16 16:51:41 -08:00
|
|
|
|
|
|
|
|
|
|
Next: configure [Git integration](git.md) or add [layer names](layer-names.md).
|