inire/docs/plans/package_structure.md

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.