# Python Package Structure

This document outlines the directory structure and module organization for the `inire` auto-router package.

## 1. Directory Layout

```
inire/
├── __init__.py             # Exposes the main `Router` class and key types
├── geometry/               # Core geometric primitives and operations
│   ├── __init__.py
│   ├── primitives.py       # Point, Port, Polygon, Arc classes
│   ├── collision.py        # R-Tree wrapper and intersection logic
│   └── components.py       # Move generators (Straight, Bend90, SBend)
├── router/                 # Search algorithms and pathfinding
│   ├── __init__.py
│   ├── astar.py            # Hybrid State-Lattice A* implementation
│   ├── graph.py            # Node, Edge, and Graph data structures
│   ├── cost.py             # Cost functions (length, bend, proximity)
│   ├── danger_map.py       # Pre-computed grid for heuristic proximity costs
│   └── pathfinder.py       # Multi-net "Negotiated Congestion" manager
├── utils/                  # Utility functions
│   ├── __init__.py
│   └── visualization.py    # Plotting tools for debug/heatmaps (matplotlib/klayout)
└── tests/                  # Unit and integration tests
    ├── __init__.py
    ├── conftest.py         # Pytest fixtures (common shapes, PDK cells)
    ├── test_primitives.py  # Tests for Port and coordinate transforms
    ├── test_components.py  # Tests for Straight, Bend90, SBend generation
    ├── test_collision.py   # Tests for R-Tree and dilation logic
    ├── test_cost.py        # Tests for Danger Map and cost evaluation
    ├── test_astar.py       # Tests for single-net routing (mazes, snapping)
    └── test_pathfinder.py  # Multi-net "Negotiated Congestion" benchmarks
```

## 2. Module Responsibilities

### `inire.geometry`
*   **`primitives.py`**: Defines the `Port` named tuple `(x, y, theta)` and helper functions for coordinate transforms.
*   **`collision.py`**: Wraps the `rtree` or `shapely` library. Handles the "Analytic Correctness" checks (exact polygon distance).
*   **`components.py`**: Logic to generate "Moves" from a start port. E.g., `SBend.generate(start_port, offset, radius)` returns a list of polygons and the end port. Handles $O > 2R$ logic.

### `inire.router`
*   **`astar.py`**: The heavy lifter. Maintains the `OpenSet` (priority queue) and `ClosedSet`. Implements the "Snap-to-Target" logic.
*   **`cost.py`**: compute $f(n) = g(n) + h(n)$. encapsulates the "Danger Map" and Path R-Tree lookups.
*   **`danger_map.py`**: Manages the pre-computed proximity grid used for $O(1)$ heuristic calculations.
*   **`pathfinder.py`**: Orchestrates the multi-net loop. Tracks the Path R-Tree for negotiated congestion and triggers reroutes.

### `inire.tests`
*   **Structure:** Tests are co-located within the package for ease of access.
*   **Fixtures:** `conftest.py` will provide standard PDK cells (e.g., a $10\mu m$ radius bend) to avoid repetition in test cases.

## 3. Dependencies
*   `numpy`: Vector math.
*   `shapely`: Polygon geometry and intersection.
*   `rtree`: Spatial indexing.
*   `networkx` (Optional): Not used for core search to ensure performance.