3.6 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 published package with Arrow support:
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
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 for fields and encodings.
The returned arrays own their storage independently of the input buffer.
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.
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.