Metadata-Version: 2.4
Name: gdsdiff
Version: 0.1.0
Summary: Exact, evidence-oriented comparison of GDSII layout geometry
Author-email: Sandbo Chang <sandbochang@outlook.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/SandboChang/gdsdiff
Project-URL: Issues, https://github.com/SandboChang/gdsdiff/issues
Project-URL: Repository, https://github.com/SandboChang/gdsdiff
Keywords: GDSII,CAD,layout,geometry,verification
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gdstk>=1.0.0
Requires-Dist: numpy>=1.26
Provides-Extra: test
Requires-Dist: jsonschema>=4.23; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: tomli; python_version < "3.11" and extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: jsonschema>=4.23; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: tomli; python_version < "3.11" and extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: native-dev
Requires-Dist: cmake>=3.24; extra == "native-dev"
Requires-Dist: pybind11>=2.12; extra == "native-dev"
Dynamic: license-file

# gdsdiff

`gdsdiff` compares the geometry and hierarchy of two GDSII layouts and emits
neutral, machine-readable evidence. It supports exact CPU verification by
default and can use optional CUDA or Apple Metal acceleration when a compatible
system toolchain and device are available.

The package is usable on CPU-only machines. CUDA, Metal, CMake, and compiler
toolchains are runtime capabilities, not mandatory Python dependencies.

## Install

```bash
python -m pip install gdsdiff
```

For local development from this checkout:

```bash
UV_PROJECT_ENVIRONMENT=.venv_wsl UV_LINK_MODE=copy uv sync --locked --extra dev
TMPDIR=/tmp .venv_wsl/bin/python -m pytest
```

Use a repository-local virtual environment: `.venv_wsl` on Windows 11 through
WSL, `.venv_mac` on macOS, and `.venv` on native Linux.

## Command line

```bash
python -m gdsdiff before.gds after.gds --output-dir comparison
```

Exit codes are stable: `0` means the selected failure policy passed, `1` means
differences failed the policy, and `2` means the comparison could not produce
valid evidence. Reports use factual directions such as `coverage_before_only`
and `coverage_after_only`.

## Python API

```python
from gdsdiff import CompareConfig, compare_gds_files

result = compare_gds_files(
    CompareConfig("before.gds", "after.gds", backend="cpu")
)
print(result.status, result.exit_code)
```

Polygon extraction is public so downstream tools such as `ebeamtime` can share
the same zero-copy `PolygonBuffer` representation:

```python
from gdsdiff import extract_gds_polygons

extraction = extract_gds_polygons("layout.gds", layers="1:0,2:0")
print(extraction.buffer.polygon_count)
```

See `docs/` for comparison semantics, report format, engine details, and
debugging guidance.

## Optional acceleration

- CUDA requires an NVIDIA GPU, a compatible driver, and the CUDA toolkit with
  `nvcc` available. On WSL, install the Windows NVIDIA display driver and the
  WSL CUDA toolkit, never a Linux display driver. `nvcc` is discovered from
  `PATH`, `CUDA_HOME`, `/usr/local/cuda`, or `/opt/cuda`.
- On-demand builds default to NVIDIA's `-arch=native`: `nvcc` detects visible
  GPUs and emits native SASS without PTX. For cross-machine builds, set
  `GDSDIFF_CUDA_ARCHITECTURES` to comma-separated compute capabilities without
  decimals (for example, `89,120`). Targets and standard `NVCC_*_FLAGS` are
  included in the content-addressed cache key.
- Metal requires Apple Silicon/macOS with the Xcode command-line tools.
- Missing or unusable accelerators fall back to CPU unless `require_gpu=True`
  is explicitly requested.

Installation and import never compile GPU code. Inspect the CUDA toolchain with
`gdsdiff.inspect_cuda_toolchain()`, then build and verify the optional backend
with `gdsdiff.prepare_cuda()` or `gdsdiff-prepare-cuda --json`. Explicit
`backend="cuda"` use retains lazy preparation. Passive diagnostics and
`discover_native_capabilities()` report only already-prepared backends.

Native artifacts are stored in a private, content-addressed user cache keyed by
source, compiler/toolkit identity, build flags, and native GPU identity. The
optional geometry cache uses JSON plus non-executable NumPy arrays; legacy
pickle cache entries are ignored and rebuilt.

## License

GPL-3.0-only. See `LICENSE`.
