97 lines
3.6 KiB
Markdown
97 lines
3.6 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 published package with Arrow support:
|
|
|
|
```sh
|
|
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
|
|
|
|
```python
|
|
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](arrow-schema.md) for fields and encodings.
|
|
The returned arrays own their storage independently of the input buffer.
|
|
|
|
## 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.
|
|
|
|
## 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](native-api.md).
|