Clarify Pheon installation and first-use examples
This commit is contained in:
parent
31afef0529
commit
4ea14085f7
4 changed files with 31 additions and 28 deletions
|
|
@ -41,7 +41,7 @@ Run Python outside the source checkout to use the installed package:
|
||||||
from pheon import arrow
|
from pheon import arrow
|
||||||
|
|
||||||
layout = arrow.read_path("chip.gds")
|
layout = arrow.read_path("chip.gds")
|
||||||
print(layout.field("cell_names")[0].as_py())
|
print(layout.field("lib_name")[0].as_py())
|
||||||
```
|
```
|
||||||
|
|
||||||
Source installation needs Rust; prebuilt Python wheels bundle the native library.
|
Source installation needs Rust; prebuilt Python wheels bundle the native library.
|
||||||
|
|
|
||||||
|
|
@ -21,7 +21,7 @@ version and the separate C API version.
|
||||||
| `lib_name` | Utf8 | Library name. |
|
| `lib_name` | Utf8 | Library name. |
|
||||||
| `mod_time`, `acc_time` | FixedSizeList(Int16, 6) | Modification/access time: year, month, day, hour, minute, second. |
|
| `mod_time`, `acc_time` | FixedSizeList(Int16, 6) | Modification/access time: year, month, day, hour, minute, second. |
|
||||||
| `cells` | List(Cell) | Cell records. |
|
| `cells` | List(Cell) | Cell records. |
|
||||||
| `cell_names` | List(Utf8) | Names indexed by cell ID. |
|
| `cell_names` | List(Utf8) | Names indexed by cell ID, including targets without cell definitions. |
|
||||||
| `layers` | List(UInt32) | Packed layer/type pairs indexed by layer ID. |
|
| `layers` | List(UInt32) | Packed layer/type pairs indexed by layer ID. |
|
||||||
|
|
||||||
### Cell
|
### Cell
|
||||||
|
|
|
||||||
14
docs/cli.md
14
docs/cli.md
|
|
@ -1,11 +1,14 @@
|
||||||
# Command-line tools
|
# Command-line tools
|
||||||
|
|
||||||
Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references.
|
Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references.
|
||||||
The CLI runs independently of Python.
|
Use uncompressed `.gds` files with the CLI. It runs independently of Python.
|
||||||
|
|
||||||
## Install
|
## Install
|
||||||
|
|
||||||
From a source checkout, with Rust 1.88 or newer:
|
If you downloaded a CLI archive, extract it and add the directory containing
|
||||||
|
`pheon` (`pheon.exe` on Windows) to your `PATH`. Run `pheon --help` to check it.
|
||||||
|
|
||||||
|
To install from a source checkout, use Rust 1.88 or newer:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
cargo install --path . --locked --bin pheon
|
cargo install --path . --locked --bin pheon
|
||||||
|
|
@ -37,9 +40,10 @@ pheon diff before.gds after.gds --hierarchy ascii --max-changes 20
|
||||||
pheon diff before.gds after.gds --format json > report.json
|
pheon diff before.gds after.gds --format json > report.json
|
||||||
```
|
```
|
||||||
|
|
||||||
Reports identify changed objects and their fields, plus affected ancestors in
|
Text reports group changes by cell. A `-` line shows an object from the old file
|
||||||
the hierarchy. Objects that can be paired unambiguously receive a replacement
|
and a `+` line shows one from the new file. A `~` line explains a likely
|
||||||
explanation; ambiguous changes remain removals and additions.
|
replacement when Pheon can pair the two uniquely. Request a hierarchy view to
|
||||||
|
see which parent cells are affected.
|
||||||
|
|
||||||
| Exit code | Meaning |
|
| Exit code | Meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
|
|
|
||||||
|
|
@ -6,16 +6,16 @@ Python 3.11 or newer is required.
|
||||||
|
|
||||||
## Install
|
## Install
|
||||||
|
|
||||||
To install a published package with Arrow support:
|
To install a PyPI release with Arrow support:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python -m pip install 'pheon[arrow]'
|
python -m pip install 'pheon[arrow]'
|
||||||
```
|
```
|
||||||
|
|
||||||
From a source checkout, use `python -m pip install '.[arrow]'`. Source builds
|
For a local wheel, pass its file path followed by `[arrow]` in the same quotes.
|
||||||
require Rust 1.88 or newer. Prebuilt wheels bundle the native library and need
|
Prebuilt wheels bundle the native library. From a source checkout, use
|
||||||
no Rust installation. Use `pheon` without the `arrow` extra if you only need
|
`python -m pip install '.[arrow]'` with Rust 1.88 or newer. The base `pheon`
|
||||||
integer packing; importing it does not import PyArrow.
|
package is enough for integer packing.
|
||||||
|
|
||||||
Run Python outside the source checkout to use the installed package.
|
Run Python outside the source checkout to use the installed package.
|
||||||
|
|
||||||
|
|
@ -25,19 +25,20 @@ Run Python outside the source checkout to use the installed package.
|
||||||
from pheon import arrow
|
from pheon import arrow
|
||||||
|
|
||||||
layout = arrow.read_path("chip.gds")
|
layout = arrow.read_path("chip.gds")
|
||||||
print(layout.field("lib_name")[0].as_py())
|
names = layout.field("cell_names")[0].as_py()
|
||||||
print(layout.field("cell_names")[0].as_py())
|
|
||||||
cells = layout.field("cells")[0].values
|
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
|
`read_path` accepts strings and path-like objects, expands `~`, and recognizes
|
||||||
gzip by its magic bytes. `read_bytes` accepts an uncompressed, contiguous byte
|
gzip by its magic bytes. `read_bytes` accepts an uncompressed, contiguous byte
|
||||||
buffer, such as `bytes`, `bytearray`, or a compatible memoryview.
|
buffer, such as `bytes`, `bytearray`, or a compatible memoryview.
|
||||||
|
|
||||||
Every reader returns a one-row `pyarrow.StructArray`. Geometry is grouped by
|
Every reader returns a one-row `pyarrow.StructArray`. The example uses each
|
||||||
cell and element kind; cell and layer IDs resolve through tables in the same
|
cell's ID to look up its name. The name table can also contain reference targets
|
||||||
result. See the [Arrow reference](arrow-schema.md) for fields and encodings.
|
without cell definitions. Geometry is grouped by cell and element kind. The
|
||||||
The returned arrays own their storage independently of the input buffer.
|
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
|
## Scan, then read selected cells
|
||||||
|
|
||||||
|
|
@ -79,19 +80,17 @@ Python sequences, or scalars and preserve the caller's data, including for
|
||||||
noncontiguous or differently ordered arrays. Pheon currently has no high-level
|
noncontiguous or differently ordered arrays. Pheon currently has no high-level
|
||||||
Python layout writer.
|
Python layout writer.
|
||||||
|
|
||||||
## Errors and native library selection
|
## Handle read errors
|
||||||
|
|
||||||
Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`.
|
Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`.
|
||||||
Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access
|
Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access
|
||||||
errors use Python's normal I/O exceptions.
|
errors use Python's normal I/O exceptions.
|
||||||
|
|
||||||
Python loads its bundled native library. Set `PHEON_LIBRARY` to an explicit
|
## Use from Klamath or Masque
|
||||||
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
|
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
|
installs Pheon with Arrow support. Use the same Python environment as the
|
||||||
as the companion package. A standalone CLI installation does not supply the
|
companion package.
|
||||||
Python bindings.
|
|
||||||
For direct integration without Python, see the [native API guide](native-api.md).
|
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.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue