Organize documentation into focused user guides

This commit is contained in:
Jan Petykiewicz 2026-11-16 16:51:41 -08:00
commit a384bb2f89
11 changed files with 798 additions and 681 deletions

133
docs/arrow-schema.md Normal file
View file

@ -0,0 +1,133 @@
# Arrow layout reference
This reference is for consumers of Pheon's Arrow readers. Each result is a
one-row `StructArray` representing a GDSII library. The
[Python guide](python.md) shows how to obtain and access it.
Geometry fields named `layer` are **indices into the result's `layers` table**.
Reference `target` and cell `id` values index its `cell_names` table. Resolve IDs
using tables from the same result; a selected read can assign different IDs.
`pheon_arrow_schema_version()` currently returns 1 for all layouts below.
Consumers of the [C API](native-api.md) must check both this application schema
version and the separate C API version.
## Full library
| Field | Arrow type | Meaning |
| --- | --- | --- |
| `meters_per_db_unit` | Float64 | Database unit size in meters. |
| `user_units_per_db_unit` | Float64 | User units per database unit. |
| `lib_name` | Utf8 | Library name. |
| `mod_time`, `acc_time` | FixedSizeList(Int16, 6) | Modification/access time: year, month, day, hour, minute, second. |
| `cells` | List(Cell) | Cell records. |
| `cell_names` | List(Utf8) | Names indexed by cell ID. |
| `layers` | List(UInt32) | Packed layer/type pairs indexed by layer ID. |
### Cell
| Field | Arrow type | Meaning |
| --- | --- | --- |
| `id` | UInt32 | Index into `cell_names`. |
| `file_offset` | UInt64 | Byte offset immediately after STRNAME, before the first element or ENDSTR. |
| `srefs`, `arefs` | List(SRef), List(ARef) | References without properties. |
| `sref_props`, `aref_props` | List(SRefProp), List(ARefProp) | References with properties. |
| `rect_batches` | List(RectBatch) | Optimized rectangular boundaries. |
| `boundary_batches` | List(BoundaryBatch) | Other boundaries without properties. |
| `boundary_props` | List(BoundaryProp) | Boundaries with properties. |
| `paths` | List(Path) | Paths. |
| `nodes`, `boxes` | List(BoxNode) | Node and box elements. |
| `texts` | List(Text) | Text labels. |
## Hierarchy scan and selected reads
Scans return the same metadata and `cell_names`, omit `layers`, and replace
`cells` with these records:
| Field | Arrow type | Meaning |
| --- | --- | --- |
| `id` | UInt32 | Index into this result's `cell_names`. |
| `struct_start_offset` | UInt64 | Inclusive offset of BGNSTR. |
| `struct_end_offset` | UInt64 | Exclusive offset after ENDSTR. |
| `refs` | List(ScanRef) | References sorted by target ID, with properties omitted. |
ScanRef has ARef's fields below. An SREF uses zero basis vectors and counts
`(1, 1)`. Geometry and text are skipped without decoding.
Pass complete half-open cell ranges to `read_selected_library` in Rust or
`read_cells_bytes` in Python/C. The result uses the full library layout, with
cells in requested order. An empty selection returns metadata and empty lists.
Offsets always refer to the original uncompressed input. The Rust selected
reader returns the original input slice as its remainder.
## Packed values
| Value | Storage | Decoding |
| --- | --- | --- |
| Layer/type pair in `layers` | UInt32 | Layer in high 16 bits; datatype/texttype/boxtype/nodetype in low 16 bits. |
| Point or vector | UInt64 | Signed Int32 x in high 32 bits, signed Int32 y in low 32 bits. |
| Array counts | UInt32 | Columns in high 16 bits, rows in low 16 bits. |
Layer halves preserve the original 16-bit patterns; reinterpret them as signed
Int16 where an integration uses signed GDS layer values. Array counts originate
from positive Int16 values. Flattened coordinate lists below use `[x, y, ...]`
in integer database units.
## References
| SRef field | Arrow type | Meaning |
| --- | --- | --- |
| `target` | UInt32 | Target cell ID. |
| `invert_y` | Boolean | Reflection flag. |
| `scale` | Float64 | Magnification. |
| `angle_rad` | Float64 | Rotation in radians. |
| `xy` | UInt64 | Packed origin. |
ARef adds `xy0` and `xy1` (UInt64 packed column/row increments) and `counts`
(UInt32). SRefProp and ARefProp add `properties: List(Property)`.
Array increments must be exact signed 32-bit integers. All Arrow readers reject
fractional or out-of-range endpoint/count division rather than rounding it.
One-placement AREFs can be normalized to SREFs. The review CLI retains original
endpoints and distinguishes SREF from AREF independently of this representation.
## Geometry and text
Every `layer` below is a UInt32 **table index**, not a packed pair.
| Type | Fields beyond `layer` |
| --- | --- |
| RectBatch | `rects: List(Int32)`, flattened `[min_x, min_y, max_x, max_y]` rectangles. |
| BoundaryBatch | `vertices: List(Int32)`; `vertex_offsets: List(UInt32)` gives each boundary's start in points, not scalar coordinates. |
| BoundaryProp | `vertices: List(Int32)`; `properties: List(Property)`. |
| BoxNode | `xy: List(Int32)`; `properties: List(Property)`. |
| Path | Fields below. |
| Text | Fields below. |
| Path field | Arrow type | Meaning |
| --- | --- | --- |
| `path_type` | Int16, nullable | Stored path type. |
| `extension_start`, `extension_end` | Int32, nullable | End extensions. |
| `width` | Int32, nullable | Null when WIDTH is absent. |
| `xy` | List(Int32) | Centerline coordinates. |
| `properties` | List(Property) | Element properties. |
| Text field | Arrow type | Meaning |
| --- | --- | --- |
| `presentation_horiz`, `presentation_vert`, `presentation_font` | UInt8, nullable | Presentation attributes. |
| `path_type` | Int16, nullable | Stored path type. |
| `width` | Int32, nullable | Stored width. |
| `invert_y` | Boolean, nullable | Reflection flag. |
| `mag` | Float64, nullable | Magnification. |
| `angle_deg` | Float64, nullable | Rotation in degrees. |
| `xy` | UInt64 | Packed position. |
| `string` | Utf8 | Label text. |
| `properties` | List(Property) | Element properties. |
Property contains `key: Int16` and `value: Utf8`. The reader preserves property
order and duplicates. Property-list fields are nullable in the schema; the
reader normally emits valid lists, including empty ones.
Geometry batching and reference normalization mean this layout is not a verbatim
record stream; use the [CLI's record dump](cli.md#inspect-a-layout) when original
records matter.

94
docs/cli.md Normal file
View file

@ -0,0 +1,94 @@
# 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:
```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
```
`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
```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
```
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](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. |
| `--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
```sh
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](git.md) or add [layer names](layer-names.md).

58
docs/comparison.md Normal file
View 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.

45
docs/development.md Normal file
View file

@ -0,0 +1,45 @@
# Development
This guide is for contributors building and checking Pheon. For usage, start
with the [CLI](cli.md) or [Python](python.md) guide.
## Build and test
The checkout selects the stable Rust toolchain; the minimum supported compiler
is 1.88. Python bindings require Python 3.11 or newer.
```sh
cargo test --locked
cargo test --release --locked
cargo build --release --locked
python -m pip install '.[arrow]'
python -I tools/check_installed.py
```
Use `RUSTUP_TOOLCHAIN=1.88.0` to check source builds against the minimum compiler.
The Python package bundles its native library during installation. To test a
newly built library without reinstalling, set `PHEON_LIBRARY` to its absolute
path and run `python -m unittest discover -s tests/python` from the checkout.
Unset this override when checking installed artifacts with `check_installed.py`.
## Interfaces and reports
The CFFI declarations live in [pheon/_ffi.h](../pheon/_ffi.h). Keep them aligned
with the exported native functions. The C API version and
[Arrow layout version](arrow-schema.md) are independent of package releases and
the [JSON report schema](diff-reports.md).
Review tests cover comparison semantics, CLI behavior, symbolic array counts,
and versioned report goldens. To regenerate JSON goldens after deliberately
changing their contract:
```sh
PHEON_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
```
Inspect the resulting diff. Goldens normalize the producer version to `test`;
a package version change alone should not alter them. JSON Schema checks verify
structure, while semantic tests verify links, totals, and result/exit agreement.
See [building releases](releases.md) for source archives, wheels, and standalone
CLI artifacts.

View file

@ -1,4 +1,9 @@
# Machine-readable diff reports
# JSON diff reports
Use JSON reports to automate layout review while retaining the evidence behind
a result. The [comparison rules](comparison.md) define equality; the
[version 1 JSON Schema](diff-report-v1.schema.json) defines every field.
A [complete example](../tests/golden/report-geometry.json) shows geometry changes.
```sh
pheon diff before.gds after.gds --format json > report.json
@ -6,184 +11,116 @@ pheon diff before.gds after.gds --format json --hierarchy graph
pheon diff before.gds after.gds --format json --top CHIP --layer 1/0
```
The command writes one UTF-8 JSON document followed by a newline to stdout.
Comparison diagnostics belong to that document. Output write failures are
reported on stderr and return 2; interrupted output is not a valid report.
JSON output currently belongs to `diff`; `dump`, `hierarchy`, and the Git
external driver retain their existing text interfaces. No external process is
used to produce a report.
`diff` writes one UTF-8 JSON document and a newline to stdout, including comparison
diagnostics. Output write failures go to stderr and return 2; interrupted output
is invalid. Other CLI commands retain text output.
The [version 1 JSON Schema](diff-report-v1.schema.json) defines the structure.
[Golden reports](../tests/golden/report-geometry.json) illustrate complete
evidence; other `report-*.json` goldens cover equality, metadata, incomplete
comparison, and failure. Their producer version is replaced with `test` so
package version changes do not alter the fixtures.
## Check the result first
## Versions and determinism
Pheon emits schema version 1 with producer name `pheon`. This schema has not
had a public release. The comparison profile remains `klamath-object-v2`, and
the `KLAMATH_LAYER_NAMES_V1` GDS marker retains its existing meaning.
`schema_version` describes the report structure. `comparison_profile` names the
equality rules, currently `klamath-object-v2`. `producer.version` identifies the
implementation. These versions are independent. Consumers interpreting equality
must understand the comparison profile as well as the schema.
Compatible additions may introduce optional fields. Consumers should ignore
unfamiliar additional fields and handle unfamiliar diagnostic codes and matching
rules without treating them as equality. Removed fields or changed meanings
require a new schema version. The schema intentionally permits additional fields.
For the same inputs, paths, options, and producer version, serialization is
deterministic. Cells, layer pairs, fields, properties, and graph edges are sorted.
Duplicate objects and properties remain separate occurrences. Reports contain
no generation timestamp or required content fingerprint.
## Result and exit status
| `status` | `result` | Exit code | Interpretation |
| `status` | `result` | Exit code | Meaning |
| --- | --- | --- | --- |
| `complete` | `equal` | 0 | Equal under the recorded profile and scope. |
| `complete` | `different` | 1 | Differences found. |
| `incomplete` | `different` | 2 | Definite differences found, with comparison limitations. |
| `incomplete` | `different` | 2 | Definite differences, with comparison limitations. |
| `incomplete` | `unknown` | 2 | Equality cannot be established. |
| `failed` | `unknown` | 2 | No comparison result is available. |
| `failed` | `unknown` | 2 | No comparison result. |
Unsupported records, future metadata versions, unresolved references, and
hierarchy cycles make the comparison incomplete. Malformed input, read errors,
invalid scopes, and invalid command arguments produce failed reports. CI must
check completeness as well as differences. An exit code of 1 is a normal
comparison outcome, including when stdout is redirected to a report file.
A code of 1 is an expected result, including when saving a report. Unsupported
records, future metadata, unresolved references, and cycles make a comparison
incomplete. Malformed input, I/O errors, invalid scopes, and command errors fail.
Library and cell timestamps are excluded from the comparison profile. A valid,
complete timestamp-only comparison returns 0. Raw record dumps remain available
for examining those timestamps.
`summary` covers the whole scoped comparison before display filters. Counts are
`exact` for complete results and `observed` for incomplete ones. Failed reports
have a null summary and empty change arrays. Replacement suggestions and affected
ancestors do not add to change counts.
`summary` counts the entire scoped comparison, before display selection. Its
`counts` is `exact` for a complete comparison and `observed` for an incomplete
one. Failed reports have a null summary and empty change arrays. Replacement
suggestions and affected ancestors never add to change counts.
## Scope and evidence selection
## Scope, selection, and numbers
`scope` records `top`, `cell`, and numeric `layer` selectors; null means
unrestricted. The full input is parsed before scope selection.
`scope` records the actual `top`, `cell`, and numeric `layer` selectors. Null
means unrestricted. The complete file is parsed before applying scope, so an
invalid record outside the selected subtree still fails the command.
`report_selection` records display-only cell/layer filters and `max_objects`.
JSON is unbounded by default. Explicit `--max-changes N` limits total emitted
removals plus additions, with removals first within each cell. Selection counters
`filtered_cells`, `filtered_objects`, `limited_objects`, and `emitted_objects`
explain omissions. `truncated` is true when filtering or limits omit evidence.
Library changes, layer-name changes, diagnostics, summaries, and the optional
graph remain. Replacement links appear only if both objects are emitted.
`report_selection` records display-only `cell`, `layer`, and `max_objects`.
JSON has no default object limit. Explicit `--max-changes N` limits the total
number of emitted object occurrences across both sides. Removals precede
additions within each cell. `filtered_cells`, `filtered_objects`,
`limited_objects`, and `emitted_objects` explain evidence selection. `truncated`
is true if filtering or a limit omits any changed cell or object. Library and
layer-name changes, diagnostics, summaries, and the optional graph are retained.
A replacement is emitted only when both linked objects are included.
## Read values safely
All aggregate counts, limits, and byte offsets are unsigned decimal **strings**.
This avoids loss of precision in JSON consumers using binary64 numbers.
Coordinates, numeric tags, layer/type pairs, widths, and array dimensions are
bounded integers represented as JSON numbers. Null means absent or unavailable;
zero and empty arrays do not imply absence.
Aggregate counts, limits, and byte offsets are unsigned decimal **strings** to
avoid JSON number precision loss. Coordinates, numeric tags, layer/type pairs,
widths, and array dimensions are bounded JSON numbers. Null means absent or
unavailable; zero and empty arrays remain meaningful values.
`inputs.old` and `inputs.new` contain input paths, presence, and UNITS fields.
Presence is distinct from an empty library. The Rust API also supports absent
Git revisions using `Document::empty_like`; no units are invented for absent
inputs. Failed reports may have null presence and units. Argument failures can
lack input/selection context because the command could not be parsed.
`inputs.old` and `inputs.new` record paths, presence, and UNITS. An absent revision
is distinct from an empty library. The Rust API supports absent Git revisions
with `Document::empty_like`. Failed reports may lack presence, units, or argument
context. Non-UTF-8 paths use null `path` and `path_encoded_hex`: `0x`-prefixed
platform-native Rust path bytes, not a portable filename encoding.
Paths are UTF-8 when representable. Otherwise `path` is null and
`path_encoded_hex` preserves Rust's platform-native encoded path bytes, prefixed
with `0x`. This is platform-dependent evidence rather than a portable path name.
## Interpret changes
## Change evidence
| Section | Evidence |
| --- | --- |
| `library_changes` | Typed before/after header fields, including unscaled UNITS. Presence changes use a null tag and boolean values. |
| `layer_name_changes` | Before/after names for numeric pairs `{ "number": 1, "purpose": 0 }`. |
| `layer_legend` | Unchanged names available in scope. Annotation labels do not also appear as object changes. |
| `cell_changes` | Name, nullable before/after cell records, attributes, removed/added objects, and replacement suggestions. A null side means absent; an existing empty cell still has a byte offset. |
`library_changes` records changed header fields as typed before/after arrays.
Library presence changes use the special field `presence`, a null tag, and
boolean before/after values. Units are not rescaled to a common grid.
Objects retain kind, numeric tag, layer, target, bounds, source side and half-open
byte range, typed fields, and a sorted property multiset including duplicates.
Convenience fields include origin, width, and reference dimensions. SREF counts
are `[1, 1]`; kind and retained fields still distinguish a one-element AREF.
`layer_name_changes` records numeric pairs with before/after names. A layer
pair is `{ "number": 1, "purpose": 0 }`, where purpose is DATATYPE, TEXTTYPE,
BOXTYPE, or NODETYPE according to the object kind. `layer_legend` contains
unchanged names available in the scope. Embedded annotation labels are excluded
from ordinary object changes. A metadata rename appears once.
Coordinates are cell-local database units. Bounds are stored-coordinate
envelopes, excluding stroke width, rendered text, and recursive target geometry.
Consider UNITS before deriving physical dimensions.
Each `cell_changes` entry has its name, nullable before/after cell records,
attribute evidence, removed and added objects, and replacement suggestions.
A null cell side means the cell is absent in that scope. An existing empty
cell has a byte offset and an empty attribute array.
Fields contain `tag`, display `name`, `encoding`, decoded `value`, and
`payload_hex`. Numeric tags are authoritative. XY values are lists of points;
other numeric values are arrays. Unsupported encodings have null values and
preserved bytes. Invalid UTF-8 strings/properties have null decoded values;
hex preserves their bytes.
Each object retains:
Evidence follows the comparison profile: boundary/box rings are canonicalized,
string padding is removed, and fields/properties are sorted. REAL8 encodings and
explicit defaults remain significant. Source offsets locate original records.
- Its kind and numeric tag, numeric layer pair, target cell, and coordinate envelope.
- Its original source side and byte range `[byte_offset, end_offset)`.
- Typed field records and the sorted property multiset, including duplicates.
- Convenience fields for text/reference origin, path/text width, and reference
array dimensions. SREF dimensions are `[1, 1]`; the kind and retained fields
distinguish an SREF from a one-element AREF and explicit fields from omission.
Coordinates are cell-local integer database units. `bounds` contains
`[xmin, ymin, xmax, ymax]` of stored coordinates. It excludes path stroke width,
rendered text dimensions, and recursively transformed target geometry.
Equal envelopes do not establish geometric equality. Unit changes must be
considered before deriving physical movements or dimensions.
A retained field has a numeric `tag`, convenience `name`, `encoding`, decoded
`value`, and `payload_hex`. The numeric tag is authoritative; names are display
aids. XY values are arrays of `[x, y]` pairs. Other numeric fields are arrays
of their declared type. Unsupported encodings retain bytes with a null value.
String and property values are null if their bytes are not valid UTF-8;
`payload_hex` always preserves them without replacement characters.
Payloads follow the comparison profile: boundary/box rings use canonical start
and winding, string padding is removed, and fields/properties are sorted. They
are comparison evidence, not a verbatim serialization of the source records.
REAL8 payload encodings are retained exactly alongside their decoded values.
Explicit defaults and omitted fields remain distinct. Source ranges allow raw
record inspection when original encoding or order is needed.
Replacement suggestions link report-local removed/added IDs, with a `match_rule`,
typed `field_changes`, and `properties_changed`. Their explanation is optional
for consumers to display and must not be parsed. Current matching rules are
`unique_kind_layer_bounds`, `unique_kind_layer`, and `unique_kind_target`.
These are explanatory matches, not persistent identity or shape equivalence.
Ambiguous candidates stay independent removals and additions. IDs are unique
within a report and have no meaning across reports.
Replacements link report-local removed/added IDs with `match_rule`,
`field_changes`, and `properties_changed`. Rules are `unique_kind_layer_bounds`,
`unique_kind_layer`, or `unique_kind_target`. IDs are not persistent identities;
ambiguous candidates stay separate. Explanation text is for display only.
## Diagnostics and hierarchy
Diagnostics have `code`, `severity`, `message`, input `side`, original byte
offset, cell, layer, and target context. Unknown context is null. Messages are
for display; codes and context support automation. Current limitation codes are
`unsupported_record`, `unsupported_metadata_version`, `unresolved_reference`,
`hierarchy_cycle`, and `scope_mismatch`. Failure codes are `invalid_input`,
`io_error`, `invalid_scope`, and `command_error`. Fatal parser errors currently
retain their location in the human message; their structured byte offset is
null. Consumers must not depend on message wording.
Diagnostics provide `code`, `severity`, `message`, input side, byte offset, cell,
layer, and target; unknown context is null. Use codes and context for automation.
Fatal parser locations currently appear only in the human message, with null
structured offsets. Do not parse message wording.
`--hierarchy graph` includes the full scoped union graph of both revisions.
Otherwise `hierarchy` is null. Nodes are keyed by cell name, with per-side
states `included`, `outside_scope`, `unresolved`, or `absent`. Their `change`
is `direct`, `affected` through a descendant, or `unchanged`.
Limitation codes are `unsupported_record`, `unsupported_metadata_version`,
`unresolved_reference`, `hierarchy_cycle`, and `scope_mismatch`. Failure codes are
`invalid_input`, `io_error`, `invalid_scope`, and `command_error`.
Edges record parent, target, before/after direct placement counts, and whether
the underlying reference records changed. AREF columns times rows contribute
symbolically; arrays are never expanded. Counts are direct edge multiplicities,
not recursively accumulated placements. Shared cells occur once. Removed edges
remain visible, and ancestors are computed over the union of both revisions.
Graph content is independent of display filters and object limits. Text depth
limits and ASCII/Mermaid choices do not apply to JSON graphs.
`--hierarchy graph` includes the full scoped union graph; otherwise `hierarchy`
is null. Nodes are keyed by name, with per-side states `included`, `outside_scope`,
`unresolved`, or `absent`, and change states `direct`, `affected`, or `unchanged`.
Edges record parent, target, before/after direct placement counts, and changed
reference records. Array multiplicities are symbolic, not expanded or recursively
accumulated. Shared cells occur once and removed edges remain. Display filters,
object limits, and text depth do not trim the graph.
## Development
## Versions
`cargo test --test review` checks report semantics, CLI behavior, and versioned
goldens. To intentionally regenerate report goldens after reviewing a contract
change, run:
`schema_version` is 1, `comparison_profile` is `klamath-object-v2`, and
`producer.name` is `pheon`. Structure, equality rules, and producer version evolve
independently. Understand the profile before interpreting equality. Consumers
should tolerate additional optional fields and unknown codes/rules without
assuming equality. Removed fields or changed meanings require a schema change.
```sh
PHEON_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
```
Schema validators can validate the goldens or actual CLI output against
`diff-report-v1.schema.json`. Schema validation does not replace semantic checks
such as replacement links, summary totals, or status/exit-code agreement.
Serialization is deterministic for identical inputs, paths, options, and producer
version. Sorted evidence retains duplicates. Reports have no generation timestamp
or required content fingerprint. See [development](development.md) for contract
tests and golden updates.

59
docs/git.md Normal file
View file

@ -0,0 +1,59 @@
# Git integration
Configure Git to show meaningful GDSII changes during review. Install the
[Pheon CLI](cli.md#install) first, then choose one of the following drivers.
Templates are also available in [contrib/git](../contrib/git/).
## Object comparison
Use the external driver for object-aware comparison and affected hierarchy.
Add this to your repository's `.gitattributes`:
```gitattributes
*.gds diff=pheon
```
Add this to `.git/config`, or use the same section in your user Git config:
```gitconfig
[diff "pheon"]
command = pheon git-diff --hierarchy ascii --
binary = true
trustExitCode = false
```
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`.
For an existing `diff=layout` attribute, put the configuration under
`[diff "layout"]` instead. Attribute names only select a Git driver.
The external driver returns 0 after rendering either an equal or different
comparison, and nonzero for invalid or incomplete comparisons. For automation
that needs equality status, run `pheon diff OLD NEW` directly; it returns
0, 1, or 2 as described in the [CLI guide](cli.md).
## Normalized text comparison
Use text conversion when you want Git to compare normalized text dumps. Set
`.gitattributes` to:
```gitattributes
*.gds diff=pheon-text
```
Configure the driver:
```gitconfig
[diff "pheon-text"]
textconv = pheon dump
binary = true
cachetextconv = true
```
Git can cache converted text. Invalidate that cache when upgrading to a tool or
comparison profile that changes the dump format, or disable `cachetextconv`.
These diffs are for human review; they are not patches that can be applied to
GDSII files. See the [comparison rules](comparison.md) for normalization details.

19
docs/index.md Normal file
View file

@ -0,0 +1,19 @@
# Pheon documentation
Start with a guide for the task you want to perform.
| Task | Guide |
| --- | --- |
| Inspect layouts, compare revisions, or view hierarchy | [Command-line tools](cli.md) |
| Load geometry or selected cells in Python | [Python](python.md) |
| Review GDSII files with Git | [Git integration](git.md) |
| Add readable names to numeric layers | [Layer names](layer-names.md) |
| Understand what a comparison considers equal | [Comparison rules](comparison.md) |
For integrations, use the [Arrow layout reference](arrow-schema.md),
[Rust and C API guide](native-api.md), or [JSON report reference](diff-reports.md).
For contributors and maintainers, see [development](development.md) and
[building releases](releases.md).
Return to the [project introduction](../README.md).

44
docs/layer-names.md Normal file
View file

@ -0,0 +1,44 @@
# Layer names
Attach readable names to numeric GDSII layer/type pairs so Pheon can show a
legend in comparison reports. Names are annotations; geometry keeps its numeric
layer assignments.
## Add or update names
```sh
pheon name-layers chip.gds named.gds --cell CHIP --carrier 900/7 \
--name 1:0:WG --name 2:0:METAL
```
Choose an existing cell and an otherwise unused `(layer, texttype)` pair in that
cell as the carrier. The carrier must contain no ordinary design objects.
The output path must be new; Pheon refuses to overwrite any existing file,
including the input.
The command consolidates the legend into that cell. Existing mappings remain
unless you override them with `--name`. It creates no cells or references, and
copies other records, timestamps, unknown records, and trailing padding byte for
byte. Input and annotation validation finish before the output is created.
## Annotation format
A text label whose exact string is `KLAMATH_LAYER_NAMES_V1` identifies a carrier
pair in its cell. Every other text label on that pair in the same cell is a
mapping of the form:
```text
layer:datatype:name
```
For example, `1:0:WG` names pair `(1, 0)` as WG. Numbers are unsigned 16-bit
decimals. The name must be nonempty UTF-8 and may contain colons; only the first
two colons separate fields. The legacy marker remains part of the format.
Mappings are collected across the library. Identical duplicates are accepted;
conflicting names for the same pair are errors. Recognized annotation labels
are excluded from ordinary object comparison. The name mapping compares
separately, while unchanged names remain available in the report legend.
Pheon does not currently read LayoutEditor LayerNames metadata, extract layers,
or remap geometry. See the [CLI guide](cli.md) for layer selection during review.

68
docs/native-api.md Normal file
View file

@ -0,0 +1,68 @@
# Rust and C integration
Use the Rust library or C API to read GDSII into Arrow without Python. For the
returned data layout, see the [Arrow reference](arrow-schema.md).
## Rust
Add `pheon` as a dependency. The library readers accept GDSII byte slices:
```rust
use pheon::library::read_library;
let bytes = std::fs::read("chip.gds").expect("read layout");
let (_remainder, layout) = read_library(&bytes).expect("parse layout");
println!("{layout:?}");
```
`read_library` reads geometry; `scan_library` returns metadata, references, and
cell ranges. Pass `(start, end)` ranges from a scan to `read_selected_library`
to load only those cells. Each range must span one complete cell. Readers return
`(remainder, StructArray)` on success. The selected reader returns the original
input as its remainder, since selection is random access.
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
exact for representable in-range `f64` values: magnitudes below `2^-260`
underflow to zero; magnitudes at least `2^252` and nonfinite values are rejected.
## C API
Build the shared library with `cargo build --release --locked`. The
[header](../pheon/_ffi.h) defines the functions and Arrow C Data structures.
The library is `libpheon.so`, `libpheon.dylib`, or `pheon.dll` on Linux, macOS,
or Windows respectively.
| Function | Input | Result |
| --- | --- | --- |
| `read_path` | NUL-terminated path | Full layout. |
| `read_bytes` | Byte pointer and size | Full layout. |
| `scan_bytes` | Byte pointer and size | Metadata, references, and cell ranges. |
| `read_cells_bytes` | Bytes and cell ranges | Full layout for selected cells. |
`read_path` accepts UTF-8 paths on Windows and filesystem bytes on Unix. It reads
uncompressed GDSII; Python's `read_path` adds gzip handling.
For `read_cells_bytes`, `ranges` points to alternating uint64 start/end offsets
and `range_count` is the number of cells, not the number of offsets. Ranges are
half-open, from BGNSTR through the end of ENDSTR. Range values must be aligned,
native-endian uint64 values. Input buffers must remain readable for the call.
Null buffer pointers are allowed only when their corresponding length is zero.
### Status and ownership
Each reader returns 0 on success and -1 on failure. Call `last_error_message()`
on the same thread after a failure. It returns a borrowed NUL-terminated message;
copy it before the next parser call or thread exit. It returns null after a
successful parser call.
Supply valid, writable, initialized `ArrowArray` and `ArrowSchema` structures
without live allocations to overwrite. A failed call leaves them unchanged.
Successful outputs own their storage independently of the input buffer. Transfer
ownership to an Arrow importer, or call each non-null release callback exactly
once. Do not release structures again after an importer takes ownership.
`pheon_abi_version()` and `pheon_arrow_schema_version()` both currently return 1.
Check both before using the API. The C calling/ownership contract and Arrow
layout have separate versions; neither is the package version or the
[JSON report schema](diff-reports.md).

97
docs/python.md Normal file
View file

@ -0,0 +1,97 @@
# Python
Use `pheon.arrow` to load GDSII geometry into PyArrow, scan a hierarchy, or read
only selected cells. The base `pheon` package also provides integer packing.
Python 3.11 or newer is required.
## Install
To install a published package with Arrow support:
```sh
python -m pip install 'pheon[arrow]'
```
From a source checkout, use `python -m pip install '.[arrow]'`. Source builds
require Rust 1.88 or newer. Prebuilt wheels bundle the native library and need
no Rust installation. Use `pheon` without the `arrow` extra if you only need
integer packing; importing it does not import PyArrow.
Run Python outside the source checkout to use the installed package.
## Read a layout
```python
from pheon import arrow
layout = arrow.read_path("chip.gds")
print(layout.field("lib_name")[0].as_py())
print(layout.field("cell_names")[0].as_py())
cells = layout.field("cells")[0].values
```
`read_path` accepts strings and path-like objects, expands `~`, and recognizes
gzip by its magic bytes. `read_bytes` accepts an uncompressed, contiguous byte
buffer, such as `bytes`, `bytearray`, or a compatible memoryview.
Every reader returns a one-row `pyarrow.StructArray`. Geometry is grouped by
cell and element kind; cell and layer IDs resolve through tables in the same
result. See the [Arrow reference](arrow-schema.md) for fields and encodings.
The returned arrays own their storage independently of the input buffer.
## Scan, then read selected cells
```python
from pathlib import Path
from pheon import arrow
content = Path("chip.gds").read_bytes() # Uncompressed GDSII bytes.
scan = arrow.scan_bytes(content)
cells = scan.field("cells")[0].values
ranges = list(zip(
cells.field("struct_start_offset").to_pylist(),
cells.field("struct_end_offset").to_pylist(),
))
selected = arrow.read_cells_bytes(content, ranges[:2])
```
Scanning returns library metadata, cell names, references, and complete cell byte
ranges without decoding geometry or text. Selected reads return the full layout
schema for the requested cells, in the requested order. Use the selected result's
own name and layer tables: IDs may differ between reads.
Ranges must have shape `(N, 2)` with nonnegative integer offsets. Each half-open
range must span exactly one complete cell, from BGNSTR through ENDSTR. An empty
list returns metadata without cells. For compressed files, decompress the bytes
before scanning or selecting ranges.
## Pack integers
```python
import pheon
int2_bytes = pheon.pack_int2([1, 2, 3])
int4_bytes = pheon.pack_int4([100, 200])
```
These helpers return big-endian GDSII integer bytes. They accept NumPy arrays,
Python sequences, or scalars and preserve the caller's data, including for
noncontiguous or differently ordered arrays. Pheon currently has no high-level
Python layout writer.
## Errors and native library selection
Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`.
Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access
errors use Python's normal I/O exceptions.
Python loads its bundled native library. Set `PHEON_LIBRARY` to an explicit
library path before importing Pheon to override it during development. The
loader checks C API and Arrow schema compatibility. It does not discover a
Cargo-installed executable or search PATH for a library.
Klamath's `native` extra installs Pheon's packing helpers; Masque's `arrow` extra
installs Pheon with Arrow support. Install these in the same Python environment
as the companion package. A standalone CLI installation does not supply the
Python bindings.
For direct integration without Python, see the [native API guide](native-api.md).

View file

@ -1,51 +1,48 @@
# Building and validating a release
# Building releases
The source archive, Python wheels and standalone CLI are separate artifacts.
Python wheels contain `pheon` and its shared library; Cargo installation contains
the CLI. Neither installation searches for the other.
This guide is for maintainers producing source archives, Python wheels, and
standalone CLI artifacts. See [development](development.md) for local checks.
Build the source archive and then the wheel from that archive:
## Build from the source archive
```sh
python -m pip install build
python -m build
```
The default `build` invocation builds its wheel from the source archive. Both
carry the Cargo version, license and locked dependency resolution. A source build
requires Rust 1.88 or newer. The checkout selects current stable through
`rust-toolchain.toml`; `RUSTUP_TOOLCHAIN=1.88.0` selects the minimum compiler
explicitly for source-package builds. An installed wheel has no Rust runtime
requirement.
The default invocation builds the wheel from the source archive. Both use the
Cargo version, license, and locked dependencies. Source builds require Rust 1.88
or newer; the checkout selects stable. Use `RUSTUP_TOOLCHAIN=1.88.0` to check the
minimum compiler explicitly.
The package workflow builds the archive once, then uses cibuildwheel to build
from it and repair wheels for Linux x86-64/ARM64, macOS x86-64/ARM64 and Windows
x86-64. Repair uses the platform tools supplied by cibuildwheel. Wheels must keep
the `py3-none` interpreter/ABI tags and a platform tag, including an appropriate
manylinux tag for Linux releases. Local unrepaired `linux_*` wheels are development
artifacts, not portable Linux releases.
Python wheels contain the package and shared library. Cargo installation
provides the CLI. Neither installation discovers or depends on the other.
Each repaired wheel is tested on Python 3.11 through 3.14 without rebuilding it.
Tests run in isolated mode against the installed package and bundled library,
including an import that verifies integer packing does not import PyArrow. To
repeat that check locally after installing a wheel and PyArrow:
## Validate artifacts
The [package workflow](../.github/workflows/packages.yml) builds one source archive
and uses cibuildwheel to build and repair wheels for Linux and macOS x86-64/ARM64,
and Windows x86-64. Wheels use `py3-none` interpreter/ABI tags plus a platform tag.
Linux releases need an appropriate manylinux tag; unrepaired local `linux_*`
wheels are development artifacts.
The workflow tests each repaired wheel on Python 3.11–3.14 without rebuilding it.
Tests run in isolated mode against the installed package and bundled library.
To repeat the check after installing a wheel and PyArrow:
```sh
python -I /path/to/pheon/tools/check_installed.py
```
Unset `PHEON_LIBRARY` for artifact tests. It exists to select an explicit external
library during development, and version checks apply equally to that library.
The minimum Rust compiler and current stable compiler run native tests in both
debug and release modes. CLI artifacts contain the executable, license, README
and Git integration templates. They are tied to their build OS and architecture.
Unset `PHEON_LIBRARY` for artifact checks. Native checks cover minimum and stable
Rust in debug and release modes. Standalone CLI artifacts contain the executable,
license, README, documentation, and Git templates; each targets one OS and
architecture.
Workflows upload build artifacts only. They do not publish to PyPI, crates.io,
or a hosted release. The repository URL and checkout directory can be renamed
to `pheon` separately; no remote repository settings are changed by this work.
## Publish separately
The project rename provides no Python import shim or old CLI alias. Companion
releases must migrate their imports and dependencies together. The Python C API
version and Arrow layout version are currently 1. CLI reports use schema version
1 and retain the `klamath-object-v2` comparison profile and existing GDS layer-name
metadata marker.
Workflows upload artifacts; they do not publish to PyPI, crates.io, or a hosted
release. Review the artifacts and test results before publishing them.
Coordinate companion package dependencies when changing Python interfaces.
C API, Arrow layout, JSON schema, and comparison-profile versions have separate
contracts; see the [native API](native-api.md) and [report reference](diff-reports.md).