pheon/docs/python.md
Jan Petykiewicz f474e9848c Require PyArrow in the Python package
Keep the arrow extra available for existing requirements. Update wheel checks and install instructions, and verify that integer packing leaves PyArrow unloaded.
2026-11-18 12:36:58 -08:00

3.3 KiB

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:

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

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 for fields and encodings.

Scan, then read selected cells

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

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 to test a locally built native library from Python, or the native API guide to call the library directly.