Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
97
docs/python.md
Normal file
97
docs/python.md
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
# 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).
|
||||
Loading…
Reference in a new issue