Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
15 changed files with 798 additions and 681 deletions
2
.github/workflows/packages.yml
vendored
2
.github/workflows/packages.yml
vendored
|
|
@ -116,7 +116,7 @@ jobs:
|
|||
cp target/release/pheon cli-dist/
|
||||
fi
|
||||
cp LICENSE.md README.md cli-dist/
|
||||
cp -R contrib cli-dist/
|
||||
cp -R contrib docs cli-dist/
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: cli-${{ matrix.os }}
|
||||
|
|
|
|||
154
ARROW_SCHEMA.md
154
ARROW_SCHEMA.md
|
|
@ -1,154 +0,0 @@
|
|||
# Arrow Schema Documentation
|
||||
|
||||
Pheon's native `pheon_arrow_schema_version()` returns 1 for the full-read,
|
||||
scan and selected-read layouts documented here. This version is independent
|
||||
of the C API version, package release and CLI JSON report schema. The stable
|
||||
Arrow C Data Interface transports these application-specific layouts; consumers
|
||||
must check both the native API and application schema before reading data.
|
||||
|
||||
This project uses Apache Arrow to represent GDSII (Graphic Data System II) library data. The schema is optimized for memory efficiency and fast access, employing several packed representations for common data types.
|
||||
|
||||
## Top-Level Structure
|
||||
|
||||
The top-level object is a `StructArray` representing the entire GDSII library.
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `meters_per_db_unit` | `Float64` | Database unit size in meters. |
|
||||
| `user_units_per_db_unit` | `Float64` | Number of user units in one database unit. |
|
||||
| `lib_name` | `Utf8` | The name of the GDSII library. |
|
||||
| `mod_time` | `FixedSizeList(Int16, 6)` | Last modification time [year, month, day, hour, minute, second]. |
|
||||
| `acc_time` | `FixedSizeList(Int16, 6)` | Last access time [year, month, day, hour, minute, second]. |
|
||||
| `cells` | `List(Cell)` | A list of cells (structures) in the library. |
|
||||
| `cell_names` | `List(Utf8)` | Names of all cells, indexed by their ID. |
|
||||
| `layers` | `List(UInt32)` | List of packed layer/datatype pairs, indexed by their ID. |
|
||||
|
||||
## Cell Structure
|
||||
|
||||
Each cell in the `cells` list is a `StructArray`.
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | `UInt32` | Unique identifier for the cell. |
|
||||
| `file_offset` | `UInt64` | Byte offset immediately after the cell's `STRNAME` record (the first element, or `ENDSTR` for an empty cell). Identical for full and selected reads. |
|
||||
| `srefs` | `List(SRef)` | Simple structure references (no properties). |
|
||||
| `arefs` | `List(ARef)` | Array references (no properties). |
|
||||
| `sref_props` | `List(SRefProp)` | Structure references with properties. |
|
||||
| `aref_props` | `List(ARefProp)` | Array references with properties. |
|
||||
| `rect_batches` | `List(RectBatch)` | Batches of rectangular boundaries (optimized). |
|
||||
| `boundary_batches` | `List(BoundaryBatch)` | Batches of generic boundaries. |
|
||||
| `boundary_props` | `List(BoundaryProp)` | Individual boundaries with properties. |
|
||||
| `paths` | `List(Path)` | Path elements. |
|
||||
| `nodes` | `List(BoxNode)` | Node elements. |
|
||||
| `boxes` | `List(BoxNode)` | Box elements. |
|
||||
| `texts` | `List(Text)` | Text labels. |
|
||||
|
||||
## Hierarchy Scan Schema
|
||||
|
||||
`scan_library` and `scan_bytes` return the same library metadata and `cell_names`
|
||||
as a full read, with the following `cells` schema and no `layers` field:
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | `UInt32` | Cell ID indexing this result's `cell_names`. |
|
||||
| `struct_start_offset` | `UInt64` | Inclusive byte offset of the `BGNSTR` record. |
|
||||
| `struct_end_offset` | `UInt64` | Exclusive byte offset immediately after `ENDSTR`. |
|
||||
| `refs` | `List(ScanRef)` | SREFs and AREFs, including references with properties, sorted by target ID. |
|
||||
|
||||
Each scan reference has `target`, `invert_y`, `scale`, `angle_rad`, `xy`, `xy0`,
|
||||
`xy1`, and `counts`, using the ARef types and packed encodings described below.
|
||||
SREFs use zero basis vectors and counts `(1, 1)`. Properties are omitted from the
|
||||
scan output; geometry and text are skipped without decoding.
|
||||
|
||||
Pass the half-open scan ranges to `read_selected_library` or `read_cells_bytes`
|
||||
to obtain the full library schema for just those cells. Each range must contain
|
||||
exactly one complete cell, from `BGNSTR` through `ENDSTR`. Cells appear in the
|
||||
requested order. Cell and layer IDs are assigned within each result, so use
|
||||
`cell_names` and `layers` from that result when resolving them; IDs can differ
|
||||
from a full read or a scan. An empty selection returns metadata and empty lists.
|
||||
The Rust random-access reader returns the original input slice as its remainder.
|
||||
|
||||
## Element Types
|
||||
|
||||
### Common Packed Encodings
|
||||
|
||||
- **Layer ID (`UInt32`)**: A packed representation of `(layer, datatype)`.
|
||||
- `layer = (layer_id >> 16) as i16`
|
||||
- `datatype = (layer_id & 0xFFFF) as i16`
|
||||
- **XY Coordinate (`UInt64`)**: A packed representation of a single point `(x, y)`.
|
||||
- `x = (xy >> 32) as i32`
|
||||
- `y = (xy & 0xFFFFFFFF) as i32`
|
||||
- **Array Counts (`UInt32`)**: A packed representation of `(columns, rows)`.
|
||||
- `columns = (counts >> 16) as i16`
|
||||
- `rows = (counts & 0xFFFF) as i16`
|
||||
|
||||
### Reference Elements (SRef / ARef)
|
||||
|
||||
References point to other cells in the library.
|
||||
|
||||
**SRef (Simple Reference)**:
|
||||
- `target`: `UInt32` (Cell ID)
|
||||
- `invert_y`: `Boolean` (Vertical flip)
|
||||
- `scale`: `Float64` (Magnification)
|
||||
- `angle_rad`: `Float64` (Rotation in radians)
|
||||
- `xy`: `UInt64` (Packed origin point)
|
||||
|
||||
**ARef (Array Reference)**:
|
||||
- Same as SRef, plus:
|
||||
- `xy0`: `UInt64` (Packed column basis vector increment)
|
||||
- `xy1`: `UInt64` (Packed row basis vector increment)
|
||||
- `counts`: `UInt32` (Packed columns and rows)
|
||||
|
||||
Array increments must be exact signed 32-bit integer database-unit values. Full
|
||||
reads, hierarchy scans, selected reads, and their FFI entry points reject arrays
|
||||
whose endpoint/count division is fractional or outside that range. They never
|
||||
round or truncate placements. The review CLI retains original endpoints and can
|
||||
compare fractional arrays independently of this Arrow representation.
|
||||
|
||||
**SRefProp / ARefProp**:
|
||||
- Same as above, plus a `properties` field.
|
||||
|
||||
### Boundary Elements
|
||||
|
||||
Boundaries are grouped into batches for efficiency when they share properties or are simple rectangles.
|
||||
|
||||
**RectBatch**:
|
||||
- `layer`: `UInt32` (Packed Layer ID)
|
||||
- `rects`: `List(Int32)` (Flattened list of `[min_x, min_y, max_x, max_y]` for each rectangle)
|
||||
|
||||
**BoundaryBatch**:
|
||||
- `layer`: `UInt32` (Packed Layer ID)
|
||||
- `vertices`: `List(Int32)` (Flattened list of all vertices for all boundaries in the batch)
|
||||
- `vertex_offsets`: `List(UInt32)` (Start index for each boundary in the `vertices` list)
|
||||
|
||||
**BoundaryProp**:
|
||||
- Individual boundary with `properties`.
|
||||
|
||||
### Other Elements
|
||||
|
||||
**Path**:
|
||||
- `layer`: `UInt32`
|
||||
- `path_type`: `Int16` (Optional)
|
||||
- `extension_start`: `Int32` (Optional)
|
||||
- `extension_end`: `Int32` (Optional)
|
||||
- `width`: `Int32` (Optional; null when `WIDTH` is absent)
|
||||
- `xy`: `List(Int32)` (centerline coordinates)
|
||||
- `properties`: `List(Property)`
|
||||
|
||||
**Text**:
|
||||
- `layer`: `UInt32`
|
||||
- `presentation_horiz`: `UInt8`
|
||||
- `presentation_vert`: `UInt8`
|
||||
- `presentation_font`: `UInt8`
|
||||
- `path_type`: `Int16`
|
||||
- `width`: `Int32`
|
||||
- `invert_y`: `Boolean`
|
||||
- `mag`: `Float64`
|
||||
- `angle_deg`: `Float64`
|
||||
- `xy`: `UInt64` (Packed position)
|
||||
- `string`: `Utf8`
|
||||
- `properties`: `List(Property)`
|
||||
|
||||
**Property**:
|
||||
- `key`: `Int16`
|
||||
- `value`: `Utf8`
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
include Cargo.toml Cargo.lock rust-toolchain.toml README.md ARROW_SCHEMA.md LICENSE.md
|
||||
include Cargo.toml Cargo.lock rust-toolchain.toml README.md LICENSE.md
|
||||
recursive-include src *.rs
|
||||
recursive-include pheon *.py *.h py.typed
|
||||
recursive-include tests *.rs *.py *.json *.txt *.mmd
|
||||
|
|
|
|||
358
README.md
358
README.md
|
|
@ -1,337 +1,57 @@
|
|||
# Pheon
|
||||
|
||||
A fast GDSII parser and writer in Rust, with Apache Arrow integration for efficient data handling.
|
||||
Pheon reads GDSII layouts into Apache Arrow and provides command-line tools for
|
||||
inspecting and comparing layout revisions. It is written in Rust, with Python
|
||||
bindings and a C API.
|
||||
|
||||
Pheon provides native GDSII codecs and a standalone layout review CLI. The Rust
|
||||
crate, Python package and executable are all named `pheon`. Python Klamath and
|
||||
Masque remain separate consumers. The former `klamath_rs_ext` import and
|
||||
`klamath` executable are not provided as aliases.
|
||||
- Inspect cells, records, and reference hierarchies.
|
||||
- Compare layout objects, with text or JSON reports and Git integration.
|
||||
- Read geometry into Arrow, or scan the hierarchy before loading selected cells.
|
||||
|
||||
## Overview
|
||||
Comparisons ignore timestamps and element order while preserving duplicates and
|
||||
other object details. They compare object fields and coordinates exactly; see the
|
||||
[comparison rules](docs/comparison.md) for supported normalization and limits.
|
||||
|
||||
`pheon` is designed to handle large GDSII files with high performance. It uses Apache Arrow as its primary in-memory data representation, allowing for efficient memory usage and easy integration with other tools in the Arrow ecosystem (like pandas, polars, or DuckDB via Python bindings).
|
||||
## Try the command-line tools
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Arrow Schema Documentation](ARROW_SCHEMA.md): Detailed information about the Arrow schema used for GDSII data.
|
||||
|
||||
## Features
|
||||
|
||||
- Fast parsing of GDSII files.
|
||||
- Efficient memory representation using Apache Arrow.
|
||||
- Support for common GDSII elements: SREF, AREF, Boundary, Path, Text, etc.
|
||||
- Optimized "batch" representations for rectangles and boundaries sharing the same layer.
|
||||
- C-compatible FFI for integration with other languages (e.g., Python).
|
||||
|
||||
REAL8 writing uses normalized GDS encodings and represents every in-range `f64`
|
||||
exactly. Finite magnitudes below `2^-260` underflow to canonical zero; nonfinite
|
||||
values and magnitudes at or above `2^252` are rejected by the encoder.
|
||||
|
||||
## Usage
|
||||
|
||||
`read_path` exports a library through the Arrow C Data Interface. Allocate
|
||||
initialized `ArrowArray` and `ArrowSchema` output structures, then check the
|
||||
returned status: `0` means success and `-1` means failure. Only import the Arrow
|
||||
outputs after success; the caller owns their release callbacks. Failed calls
|
||||
leave the outputs unchanged. `pheon/_ffi.h` declares the C API; `test.py`
|
||||
demonstrates the supported Python reader.
|
||||
|
||||
`last_error_message()` returns a UTF-8, null-terminated error string, or null
|
||||
after a successful parser call. Errors belong to the calling thread. Copy the
|
||||
message before making another parser call on that thread, and before the thread
|
||||
exits; calls on other threads do not invalidate it. Parser panics that unwind
|
||||
are converted into errors.
|
||||
|
||||
For partial reads, call `scan_bytes` with a borrowed GDSII byte buffer to obtain
|
||||
cell ranges and references without decoding geometry. Pass the desired ranges
|
||||
to `read_cells_bytes` to load their full contents. Both calls use the same Arrow
|
||||
outputs and status/error handling as `read_path`:
|
||||
|
||||
```c
|
||||
int scan_bytes(const uint8_t *data, size_t size,
|
||||
struct ArrowArray *array, struct ArrowSchema *schema);
|
||||
int read_cells_bytes(const uint8_t *data, size_t size,
|
||||
const uint64_t *ranges, size_t range_count,
|
||||
struct ArrowArray *array, struct ArrowSchema *schema);
|
||||
```
|
||||
|
||||
`ranges` contains alternating inclusive start and exclusive end offsets, with
|
||||
two native-endian `uint64_t` values per cell. Each range must cover one complete
|
||||
cell. A null `ranges` pointer is accepted when `range_count` is zero. Likewise,
|
||||
null `data` is accepted for zero bytes and produces an ordinary parse error for
|
||||
the empty input. Nonempty buffers must be readable for the duration of the call;
|
||||
range values must be aligned. Exported Arrow data owns its storage independently
|
||||
of the input. See [Arrow Schema Documentation](ARROW_SCHEMA.md) for the scan
|
||||
schema, offset definitions, and ID assignment.
|
||||
|
||||
## Python package and validation
|
||||
|
||||
Python 3.11 or newer is required. Source builds require Rust 1.88 or newer;
|
||||
installing a prebuilt wheel requires no Rust compiler. The shared library uses
|
||||
a C ABI rather than Python's or Rust's native ABI, so one platform wheel serves
|
||||
multiple Python minor versions. CFFI, NumPy and optional PyArrow must themselves
|
||||
support the selected interpreter. A Rust application uses the crate normally
|
||||
and compiles it with its own compatible toolchain. The checkout selects the
|
||||
stable toolchain locally through `rust-toolchain.toml`, without changing your
|
||||
global default. CI checks both Rust 1.88 and current stable.
|
||||
From a source checkout, install the CLI with Rust 1.88 or newer:
|
||||
|
||||
```sh
|
||||
python3 -m pip install 'pheon[arrow]'
|
||||
cargo install --path . --locked --bin pheon
|
||||
pheon dump chip.gds
|
||||
pheon diff before.gds after.gds
|
||||
pheon hierarchy chip.gds --format mermaid
|
||||
```
|
||||
|
||||
`diff` returns 0 for equality, 1 for differences, and 2 for invalid or incomplete
|
||||
comparisons. Start with the [CLI guide](docs/cli.md), then set up
|
||||
[Git integration](docs/git.md) if you review layouts in a repository.
|
||||
|
||||
## Read layouts in Python
|
||||
|
||||
Python 3.11 or newer is required. From a source checkout:
|
||||
|
||||
```sh
|
||||
python -m pip install '.[arrow]'
|
||||
```
|
||||
|
||||
Run Python outside the source checkout to use the installed package:
|
||||
|
||||
```python
|
||||
from pheon import arrow
|
||||
|
||||
library = arrow.read_path('chip.gds') # one-row StructArray; also accepts gzip
|
||||
scan = arrow.scan_bytes(gds_bytes)
|
||||
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(gds_bytes, ranges[:2])
|
||||
layout = arrow.read_path("chip.gds")
|
||||
print(layout.field("cell_names")[0].as_py())
|
||||
```
|
||||
|
||||
`read_bytes` reads a complete borrowed buffer. Full, scanned and selected Arrow
|
||||
results own their storage independently of that buffer. `PheonError` reports
|
||||
native parse failures; malformed range shapes and types raise Python value/type
|
||||
errors before calling native code. Integer packing needs no PyArrow import.
|
||||
Source installation needs Rust; prebuilt Python wheels bundle the native library.
|
||||
The [Python guide](docs/python.md) covers installation, selected reads, and integer
|
||||
packing. The [Arrow reference](docs/arrow-schema.md) describes the returned data.
|
||||
|
||||
### Discovery and companion packages
|
||||
## Learn more
|
||||
|
||||
Klamath's `native` extra installs `pheon`; Masque's `arrow` extra installs
|
||||
`pheon[arrow]`. Klamath imports Pheon's packing helpers, while Masque calls
|
||||
`pheon.arrow` and translates parse failures to its existing error type.
|
||||
Browse the [documentation](docs/index.md) for layer names, native integration,
|
||||
JSON reports, development, and releases. For writing, Pheon provides low-level
|
||||
GDSII record helpers in Rust.
|
||||
|
||||
The Python loader selects the library bundled with the imported `pheon` package,
|
||||
or the exact file selected by `PHEON_LIBRARY`. It checks C ABI version 1 and
|
||||
Arrow layout schema version 1 before exposing native functions. Incompatible
|
||||
or unversioned libraries fail with an import error. Those versions are independent
|
||||
of package releases and the CLI's JSON report schema.
|
||||
|
||||
`cargo install --path . --locked --bin pheon` installs the CLI, not the Python
|
||||
package or a discoverable shared library. Klamath does not search PATH or Cargo
|
||||
directories for it. To reuse an external native build, install the Python
|
||||
components too and set `PHEON_LIBRARY`; an editable source install is useful
|
||||
during development. The old library override variables are not recognized.
|
||||
|
||||
The Python packing helpers require NumPy and CFFI, both declared as runtime
|
||||
dependencies. Setuptools invokes `cargo build --release --lib` and bundles the
|
||||
C ABI shared library in a platform-specific wheel. Its version comes from
|
||||
`Cargo.toml`. The C declarations are in `pheon/_ffi.h`; the loader uses
|
||||
CFFI ABI mode, so no Python extension compilation or Maturin is required.
|
||||
|
||||
```sh
|
||||
python3 -m pip install .
|
||||
```
|
||||
|
||||
To build a source archive and a wheel with the `build` frontend and installed
|
||||
Setuptools/Wheel tooling:
|
||||
|
||||
```sh
|
||||
python3 -m build --no-isolation
|
||||
```
|
||||
|
||||
Source archives include a Cargo lockfile, and wheel builds use `--locked` so
|
||||
building from an archive retains the resolved Rust dependency versions. Wheels
|
||||
are tagged for the build platform and use the Python-independent `py3-none` ABI.
|
||||
The CLI continues to build directly with Cargo and has no Python dependency.
|
||||
|
||||
For source-tree development, point the CFFI loader at a Cargo-built library:
|
||||
|
||||
```sh
|
||||
cargo build --release --lib
|
||||
PHEON_LIBRARY="$PWD/target/release/libpheon.so" \
|
||||
python3 -m unittest discover -s tests/python -v
|
||||
```
|
||||
|
||||
Use `libpheon.dylib` on macOS or `pheon.dll` on Windows. Without
|
||||
the explicit override, the loader uses the library bundled inside the package.
|
||||
After installing a wheel, run its tests outside the source checkout to exercise
|
||||
the installed package:
|
||||
|
||||
```sh
|
||||
python3 -I -m unittest discover -s /absolute/path/to/pheon/tests/python -v
|
||||
```
|
||||
|
||||
The Python tests cover multidimensional and noncontiguous packing, input
|
||||
preservation, range errors, and the C declarations for Arrow exports and release
|
||||
callbacks, input lifetimes and ABI mismatches. Run `cargo test` and
|
||||
`cargo test --release` for native validation. See [release validation](docs/releases.md)
|
||||
for wheel builds, platform repair and testing the same artifact on multiple
|
||||
Python versions.
|
||||
|
||||
## Layout review CLI
|
||||
|
||||
The review CLI is a standalone Rust executable:
|
||||
|
||||
```sh
|
||||
cargo build --bin pheon
|
||||
target/debug/pheon dump chip.gds
|
||||
target/debug/pheon dump chip.gds --records
|
||||
target/debug/pheon diff old.gds new.gds --hierarchy ascii
|
||||
target/debug/pheon diff old.gds new.gds --hierarchy mermaid --max-changes 20
|
||||
target/debug/pheon hierarchy chip.gds --format mermaid --depth 4
|
||||
target/debug/pheon diff old.gds new.gds --top CHIP --layer 1/0
|
||||
target/debug/pheon diff old.gds new.gds --show-layer 1/0
|
||||
target/debug/pheon diff old.gds new.gds --format json
|
||||
target/debug/pheon diff old.gds new.gds --format json --hierarchy graph
|
||||
target/debug/pheon name-layers chip.gds named.gds --cell CHIP --carrier 900/7 --name 1:0:WG
|
||||
```
|
||||
|
||||
The object dump is deterministic and omits source offsets. Record dumps preserve
|
||||
record order and show offsets, tags, sizes, and values, including records the
|
||||
object reviewer does not support. They can inspect an invalid metadata declaration
|
||||
without invoking object-level validation. Zero padding after ENDLIB is accepted.
|
||||
|
||||
The fixed `klamath-object-v2` comparison profile:
|
||||
|
||||
- Matches cells by name and layers by numeric pair. The default scope is the
|
||||
entire library; explicit selectors are recorded in each report.
|
||||
- Ignores library/cell timestamps, cell order, element order, and property order.
|
||||
- Normalizes boundary/box starting vertex and winding, retaining other vertices.
|
||||
- Preserves duplicate objects and duplicate properties as multisets.
|
||||
- Compares paths, labels, references, array endpoints/counts, properties, and all
|
||||
retained flags exactly. Explicit defaults and their omission remain distinct;
|
||||
SREFs and single-element AREFs remain distinct. REAL8 encodings are retained.
|
||||
- Reports library fields, including UNITS, separately. It does not rescale files
|
||||
into a shared grid, infer cell renames, or perform geometric Boolean operations.
|
||||
- Uses bounding boxes as coordinate envelopes, not evidence of equality. Path
|
||||
envelopes do not include stroke width; text/reference envelopes are coordinates,
|
||||
not rendered or recursively transformed bounds.
|
||||
- Returns an incomplete result for unsupported records, future metadata versions,
|
||||
unresolved references, or cycles. These cannot produce an equality claim.
|
||||
|
||||
`diff` exits with **0** for equality under this profile, **1** for differences,
|
||||
and **2** for invalid input or incomplete comparison. `--max-changes` limits the
|
||||
number of object details displayed, not the comparison. Source offsets are
|
||||
included in changed-object reports for tracing changes back to record dumps.
|
||||
|
||||
`diff --format json` emits a versioned report with typed before/after evidence,
|
||||
structured diagnostics, and independent comparison status and completeness.
|
||||
JSON includes all changes by default. Explicit display filters and `--max-changes`
|
||||
record omitted evidence without changing totals or exit status. `--hierarchy graph`
|
||||
adds the complete scoped reference graph, with symbolic array multiplicities;
|
||||
`--depth` applies to text output only. Timestamp-only changes still return 0.
|
||||
Input and argument errors also produce JSON when requested. See the
|
||||
[report contract](docs/diff-reports.md) and
|
||||
[version 1 JSON Schema](docs/diff-report-v1.schema.json).
|
||||
|
||||
Unmatched objects are paired for explanation only when candidates are unique by
|
||||
type/layer/bounding box, then by type/layer among the remaining objects.
|
||||
References additionally match by target. Ambiguous groups stay additions and
|
||||
removals. Reports explain reference movement, array-count changes, path widths,
|
||||
and polygons changed within the same bounds. Full before/after records remain
|
||||
visible, and duplicate counts remain significant. Unchanged layer names appear
|
||||
once as a legend for changed objects on those layers.
|
||||
|
||||
### Comparison scope and display filters
|
||||
|
||||
`--top NAME` compares that cell and its reachable subtree independently in each
|
||||
revision. `--cell NAME` compares the exact cell, including its reference records,
|
||||
without comparing descendant contents. Combine the two to select a cell within
|
||||
a subtree. A selector absent from both revisions is an error; absence on one
|
||||
side is an addition/deletion.
|
||||
|
||||
`--layer L/T` selects objects on a numeric layer/type pair, plus references whose
|
||||
targets use that layer transitively. Cells with no relevant content are omitted.
|
||||
Unresolved references, cycles, and unsupported records with unknown layer effect
|
||||
remain incomplete results. Unsupported objects on another known layer can be
|
||||
excluded. Library fields, including units, remain compared. Unsupported layer-name
|
||||
version diagnostics are always retained, since those declarations can affect any
|
||||
layer or cell in the library. Scoped dumps and
|
||||
hierarchy views accept the same selectors. Scope selection parses the complete
|
||||
input: malformed record grammar and conflicting metadata are still errors.
|
||||
|
||||
`--show-cell NAME` and `--show-layer L/T` filter object details in a diff report
|
||||
without changing comparison status, totals, metadata changes, or hierarchy.
|
||||
References have no numeric layer and are hidden by `--show-layer`. The comparison
|
||||
scope and any display-only filter are printed explicitly. The Rust API accepts
|
||||
one combined `Scope`; applying another scope to an already scoped document is
|
||||
rejected rather than losing reference coverage information.
|
||||
|
||||
Hierarchy output distinguishes directly changed cells, affected ancestors, and
|
||||
unchanged targets of modified references. It includes edges from both revisions,
|
||||
so removed branches remain visible. Counts are direct edge multiplicities,
|
||||
including arrays, rather than expanded placements. Shared definitions are marked
|
||||
as already shown in text and appear once in Mermaid. `--depth` limits displayed
|
||||
descendants only. The CLI emits Mermaid source, requiring no diagram renderer.
|
||||
|
||||
Layer names are read from labels in an existing cell. A label with the exact
|
||||
string `KLAMATH_LAYER_NAMES_V1` identifies an annotation carrier `(layer, texttype)`
|
||||
pair within that cell. All other labels on that same pair in that same cell must
|
||||
be `layer:datatype:name` declarations, for example `1:0:WG`. The carrier pair is
|
||||
not fixed; choose a suitable annotation layer in the design's technology.
|
||||
Declarations split at the first two colons, allowing colons in names. Numeric
|
||||
fields are unsigned 16-bit decimal integers. Names are nonempty UTF-8 strings.
|
||||
Repeated identical declarations are accepted; conflicting declarations fail.
|
||||
Names are collected across the library. Recognized metadata labels are omitted
|
||||
from object comparison; mappings are compared separately and printed once per
|
||||
numeric pair, so renaming a layer does not rewrite every shape description.
|
||||
|
||||
`name-layers INPUT OUTPUT --cell NAME --carrier L/T --name L:T:NAME ...` writes
|
||||
this convention. It consolidates existing recognized declarations into one legend
|
||||
in the chosen existing cell, retains existing names not explicitly updated, and
|
||||
overrides the named pairs. The chosen carrier must contain no ordinary design
|
||||
objects in that cell. Unrelated records, timestamps, unknown records and trailing
|
||||
padding are copied byte-for-byte. No structures or references are added. Output
|
||||
must be a new file: the CLI refuses to overwrite an existing destination, including
|
||||
the input. Invalid declarations, conflicting arguments, oversized labels and
|
||||
future metadata versions fail before output creation.
|
||||
|
||||
The record-preserving review adapter retains information normalized or omitted
|
||||
by the Arrow geometry reader; existing Arrow APIs are unchanged. Structured Rust
|
||||
change records feed the text and hierarchy renderers. LayoutEditor's `LayerNames`
|
||||
extension, layout extraction/remapping, and geometric Boolean comparison remain
|
||||
outside the current CLI.
|
||||
|
||||
### Git integration
|
||||
|
||||
Install the executable on PATH with `cargo install --path . --bin pheon`.
|
||||
The templates in [contrib/git/config](contrib/git/config) and
|
||||
[contrib/git/attributes](contrib/git/attributes) provide two alternative drivers.
|
||||
For structural summaries and affected hierarchy, add this attribute:
|
||||
|
||||
```gitattributes
|
||||
*.gds diff=pheon
|
||||
```
|
||||
|
||||
Configure the native external driver in Git config:
|
||||
|
||||
```gitconfig
|
||||
[diff "pheon"]
|
||||
command = pheon git-diff --hierarchy ascii --
|
||||
binary = true
|
||||
trustExitCode = false
|
||||
```
|
||||
|
||||
The adapter consumes Git's old/new temporary files directly, handles additions,
|
||||
deletions and renames, and quotes display paths. It returns success after rendering
|
||||
either equality or differences, as expected by the external-driver protocol.
|
||||
Invalid or incomplete comparisons retain a nonzero exit and diagnostics. Scope
|
||||
and display options can precede the final `--` in the configured command. Existing
|
||||
repositories using `diff=layout` can put the same command under `[diff "layout"]`.
|
||||
|
||||
For ordinary Git line diffs, use canonical textconv instead:
|
||||
|
||||
```gitattributes
|
||||
*.gds diff=pheon-text
|
||||
```
|
||||
|
||||
Configure the driver in Git config:
|
||||
|
||||
```gitconfig
|
||||
[diff "pheon-text"]
|
||||
textconv = pheon dump
|
||||
binary = true
|
||||
cachetextconv = true
|
||||
```
|
||||
|
||||
This is a human review representation, not an applicable GDS patch. Invalidate
|
||||
Git's textconv cache when changing the dump profile/tool version. For automated
|
||||
equality checks, use `pheon diff` and its exit status directly.
|
||||
|
||||
`tests/review.rs` contains ten initial fixture pairs, checked-in canonical/text/
|
||||
Mermaid goldens, metadata byte-preservation checks, scope and report regressions,
|
||||
and actual Git integration tests. It also checks near-limit polygon records,
|
||||
2048-cell hierarchies and arrays representing over a billion placements without
|
||||
expanding them. Run `cargo test` and `cargo test --release` for debug and optimized
|
||||
validation. No KLayout installation or Python package is required.
|
||||
Licensed under [GPL-3.0-only](LICENSE.md).
|
||||
|
|
|
|||
133
docs/arrow-schema.md
Normal file
133
docs/arrow-schema.md
Normal 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
94
docs/cli.md
Normal 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
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.
|
||||
45
docs/development.md
Normal file
45
docs/development.md
Normal 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.
|
||||
|
|
@ -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
59
docs/git.md
Normal 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
19
docs/index.md
Normal 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
44
docs/layer-names.md
Normal 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
68
docs/native-api.md
Normal 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
97
docs/python.md
Normal 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).
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue