91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
# Python
|
|
|
|
Use `pheon.arrow` to load GDSII geometry into PyArrow, scan a hierarchy, or read
|
|
only selected cells. The package also provides integer packing.
|
|
Python 3.11 or newer is required.
|
|
|
|
## Install
|
|
|
|
Install Pheon from [PyPI](https://pypi.org/project/pheon/).
|
|
|
|
```sh
|
|
python -m pip install pheon
|
|
```
|
|
|
|
The package installs PyArrow for layout reads. Existing `pheon[arrow]`
|
|
requirements still work. [Prebuilt wheels](https://pypi.org/project/pheon/#files)
|
|
bundle the native library. On platforms without a compatible wheel, pip builds
|
|
the library from source and needs Rust 1.88 or newer and a native linker.
|
|
|
|
From a source checkout, install with `python -m pip install .`, then run Python
|
|
outside the checkout to import 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.
|
|
|
|
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.
|