pheon/docs/python.md

96 lines
3.4 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 with Arrow support:
```sh
python -m pip install 'pheon[arrow]'
```
For a local wheel, pass its file path followed by `[arrow]` in the same quotes.
Prebuilt wheels bundle the native library. From a source checkout, use
`python -m pip install '.[arrow]'` with Rust 1.88 or newer. The base `pheon`
package is enough for integer packing.
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 with Arrow support. 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.