3.6 KiB
Command-line tools
Use pheon to inspect a GDSII file, compare revisions, or trace cell references.
The CLI runs independently of Python.
Install
From a source checkout, with Rust 1.88 or newer:
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
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
dump shows a normalized layout description. Add --records to inspect raw
records, including timestamps. hierarchy shows cell references without
expanding array placements. Shared cells are marked rather than repeated
indefinitely. Mermaid output is diagram source for a Mermaid renderer.
Compare revisions
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
Reports identify changed objects and their fields, plus affected ancestors in the hierarchy. Objects that can be paired unambiguously receive a replacement explanation; ambiguous changes remain removals and additions.
| 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 before relying on results in automation, and the JSON reference to consume reports programmatically.
Choose the comparison scope
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. |
--layer L/T |
Objects on a numeric layer/type pair, plus references leading to that layer. |
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.
Control report detail
pheon diff before.gds after.gds --show-cell RESONATOR --show-layer 1/0
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;
JSON includes all changed objects unless this 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
JSON, use --format json --hierarchy graph; text depth and display filters do
not trim that graph.
Next: configure Git integration or add layer names.