Keep the arrow extra available for existing requirements. Update wheel checks and install instructions, and verify that integer packing leaves PyArrow unloaded.
95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
# 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 PyPI release:
|
|
|
|
```sh
|
|
python -m pip install pheon
|
|
```
|
|
|
|
The package installs PyArrow for layout reads. Existing `pheon[arrow]`
|
|
requirements still work. Prebuilt wheels bundle the native library. From a
|
|
source checkout, use `python -m pip install .` with Rust 1.88 or newer.
|
|
|
|
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")
|
|
names = layout.field("cell_names")[0].as_py()
|
|
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
|
|
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`. The example uses each
|
|
cell's ID to look up its name. The name table can also contain reference targets
|
|
without cell definitions. Geometry is grouped by cell and element kind. The
|
|
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
|
|
|
|
```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.
|
|
|
|
## Handle read errors
|
|
|
|
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.
|
|
|
|
## Use from Klamath or Masque
|
|
|
|
Klamath's `native` extra installs Pheon's packing helpers. Masque's `arrow` extra
|
|
installs Pheon for layout reads. Use the same Python environment as the
|
|
companion package.
|
|
|
|
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.
|