Clarify Pheon installation and first-use examples

This commit is contained in:
Jan Petykiewicz 2026-11-17 15:07:40 -08:00
commit 4ea14085f7
4 changed files with 31 additions and 28 deletions

View file

@ -41,7 +41,7 @@ Run Python outside the source checkout to use the installed package:
from pheon import arrow from pheon import arrow
layout = arrow.read_path("chip.gds") layout = arrow.read_path("chip.gds")
print(layout.field("cell_names")[0].as_py()) print(layout.field("lib_name")[0].as_py())
``` ```
Source installation needs Rust; prebuilt Python wheels bundle the native library. Source installation needs Rust; prebuilt Python wheels bundle the native library.

View file

@ -21,7 +21,7 @@ version and the separate C API version.
| `lib_name` | Utf8 | Library name. | | `lib_name` | Utf8 | Library name. |
| `mod_time`, `acc_time` | FixedSizeList(Int16, 6) | Modification/access time: year, month, day, hour, minute, second. | | `mod_time`, `acc_time` | FixedSizeList(Int16, 6) | Modification/access time: year, month, day, hour, minute, second. |
| `cells` | List(Cell) | Cell records. | | `cells` | List(Cell) | Cell records. |
| `cell_names` | List(Utf8) | Names indexed by cell ID. | | `cell_names` | List(Utf8) | Names indexed by cell ID, including targets without cell definitions. |
| `layers` | List(UInt32) | Packed layer/type pairs indexed by layer ID. | | `layers` | List(UInt32) | Packed layer/type pairs indexed by layer ID. |
### Cell ### Cell

View file

@ -1,11 +1,14 @@
# Command-line tools # Command-line tools
Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references. Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references.
The CLI runs independently of Python. Use uncompressed `.gds` files with the CLI. It runs independently of Python.
## Install ## Install
From a source checkout, with Rust 1.88 or newer: If you downloaded a CLI archive, extract it and add the directory containing
`pheon` (`pheon.exe` on Windows) to your `PATH`. Run `pheon --help` to check it.
To install from a source checkout, use Rust 1.88 or newer:
```sh ```sh
cargo install --path . --locked --bin pheon cargo install --path . --locked --bin pheon
@ -37,9 +40,10 @@ pheon diff before.gds after.gds --hierarchy ascii --max-changes 20
pheon diff before.gds after.gds --format json > report.json pheon diff before.gds after.gds --format json > report.json
``` ```
Reports identify changed objects and their fields, plus affected ancestors in Text reports group changes by cell. A `-` line shows an object from the old file
the hierarchy. Objects that can be paired unambiguously receive a replacement and a `+` line shows one from the new file. A `~` line explains a likely
explanation; ambiguous changes remain removals and additions. replacement when Pheon can pair the two uniquely. Request a hierarchy view to
see which parent cells are affected.
| Exit code | Meaning | | Exit code | Meaning |
| --- | --- | | --- | --- |

View file

@ -6,16 +6,16 @@ Python 3.11 or newer is required.
## Install ## Install
To install a published package with Arrow support: To install a PyPI release with Arrow support:
```sh ```sh
python -m pip install 'pheon[arrow]' python -m pip install 'pheon[arrow]'
``` ```
From a source checkout, use `python -m pip install '.[arrow]'`. Source builds For a local wheel, pass its file path followed by `[arrow]` in the same quotes.
require Rust 1.88 or newer. Prebuilt wheels bundle the native library and need Prebuilt wheels bundle the native library. From a source checkout, use
no Rust installation. Use `pheon` without the `arrow` extra if you only need `python -m pip install '.[arrow]'` with Rust 1.88 or newer. The base `pheon`
integer packing; importing it does not import PyArrow. package is enough for integer packing.
Run Python outside the source checkout to use the installed package. Run Python outside the source checkout to use the installed package.
@ -25,19 +25,20 @@ Run Python outside the source checkout to use the installed package.
from pheon import arrow from pheon import arrow
layout = arrow.read_path("chip.gds") layout = arrow.read_path("chip.gds")
print(layout.field("lib_name")[0].as_py()) names = layout.field("cell_names")[0].as_py()
print(layout.field("cell_names")[0].as_py())
cells = layout.field("cells")[0].values cells = layout.field("cells")[0].values
print([names[cell_id] for cell_id in cells.field("id").to_pylist()])
``` ```
`read_path` accepts strings and path-like objects, expands `~`, and recognizes `read_path` accepts strings and path-like objects, expands `~`, and recognizes
gzip by its magic bytes. `read_bytes` accepts an uncompressed, contiguous byte gzip by its magic bytes. `read_bytes` accepts an uncompressed, contiguous byte
buffer, such as `bytes`, `bytearray`, or a compatible memoryview. buffer, such as `bytes`, `bytearray`, or a compatible memoryview.
Every reader returns a one-row `pyarrow.StructArray`. Geometry is grouped by Every reader returns a one-row `pyarrow.StructArray`. The example uses each
cell and element kind; cell and layer IDs resolve through tables in the same cell's ID to look up its name. The name table can also contain reference targets
result. See the [Arrow reference](arrow-schema.md) for fields and encodings. without cell definitions. Geometry is grouped by cell and element kind. The
The returned arrays own their storage independently of the input buffer. returned arrays own their storage independently of the input buffer.
See the [Arrow reference](arrow-schema.md) for fields and encodings.
## Scan, then read selected cells ## Scan, then read selected cells
@ -79,19 +80,17 @@ Python sequences, or scalars and preserve the caller's data, including for
noncontiguous or differently ordered arrays. Pheon currently has no high-level noncontiguous or differently ordered arrays. Pheon currently has no high-level
Python layout writer. Python layout writer.
## Errors and native library selection ## Handle read errors
Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`. Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`.
Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access
errors use Python's normal I/O exceptions. errors use Python's normal I/O exceptions.
Python loads its bundled native library. Set `PHEON_LIBRARY` to an explicit ## Use from Klamath or Masque
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 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 installs Pheon with Arrow support. Use the same Python environment as the
as the companion package. A standalone CLI installation does not supply the companion package.
Python bindings.
For direct integration without Python, see the [native API guide](native-api.md). See [development](development.md) to test a locally built native library from
Python, or the [native API guide](native-api.md) to call the library directly.