code/tt_diffusion_planner/ttaw/__init__.py

# SPDX-License-Identifier: Apache-2.0
"""ttaw: shared infrastructure of the Autoware ports to one Tenstorrent Blackhole p150 (ttnn / tt-metalium).

The package is the source of truth under ``common/ttaw`` and is vendored into every bundle as the sub-package
``code/<pkg>/ttaw`` by ``common/tools/vendor.py``. Rules that keep one tree valid in both places:

- relative imports only (``from .device import open_device``), never ``import ttaw``;
- importing any module has no side effects: no ``import ttnn`` / ``torch`` at module level, no device, no network,
  no environment reads (ttnn and torch are imported inside the functions that need them);
- optimization knobs are read once at model build (:mod:`.knobs`) and each has an env A/B switch;
- custom kernel ``.cpp`` files are package data, located with :func:`.ops.kernel_path`.

Modules (see ``API.md`` for the full guide):

==================  ======  =============================================================================
module              id      what it provides
==================  ======  =============================================================================
``device``          C01     ``open_device`` (ETH dispatch default, ``auto`` patch detection), ``describe_device``
``trace``           C02     ``TraceRunner``: persistent I/O, warm-up, capture, variants, 1CQ / 2CQ, state
``tensors``         C03     tile padding, layout / dtype helpers, fp32 islands, zero-copy host staging buffers
``weights``         C04     ``OnnxWeights``, BN folding in fp64, safetensors / ``.pth`` loading, weight cache
``precision``       C05     explicit ``compute_kernel_config`` factory and per-module policy tables
``knobs``           --      env A/B knobs read once at build
``metrics``         C06     PCC variants, argmax agreement, IoU, top-K overlap, detection matching, ADE/FDE
``golden``          C06     golden ``.npz`` files, tap registry, gate registry that never loosens, reports
``profiling``       C07     stage bench (p50/p99), Tracy signposts, ops-CSV summarizer, AICLK sampler
``io``              C08     point cloud / image / calibration decoding, output encoders
``outputs``         C08     ``Detections3D`` ``Detections2D`` ``Segmentation3D`` ``Mask2D`` ``Trajectory``
``api_base``        C08     ``ModelBase`` (from_pretrained, weights resolution, warm-up, lock, info, close)
``server``          C08     FastAPI app factory (``server.app``); stdlib client, smoke and reference checks
                            (``server.client``, ``server.smoke``)
``image``           C14     bit-exact Autoware image pre-processing from cached LUTs (YOLOX letterbox, BEVDet crop)
``image_area``      C14     METEOR preset: OpenCV ``INTER_AREA`` down-scaling of uint8 frames, bit-exact
``image_linear``    C14     SceneSeg preset: OpenCV ``INTER_LINEAR`` / ``INTER_NEAREST`` resizes of uint8 frames and the
                            VisionPilot normalisation (BGR / RGB), bit-exact
``image_triangle``  C14     StreamPETR preset: Autoware's anti-aliased triangle resize + crop + normalise kernel,
                            bit-exact (normalisation presets autoware_main / autoware_0.52 / awml_training)
``geometry``        C10     rigid transforms (float64), Autoware's float32 sweep transform, yaw conventions
``pointcloud``      C11     Autoware multi-sweep densification state machine (per stream), hygiene masks
``voxelize``        C12     deterministic pillars, 9/10/11-feature decoration, canvas scatter / gather index
``sparse``          C13     sparse-conv rulebooks: spconv-faithful sub-manifold / strided neighbour maps (gather
                            form), tile-ordered im2col and to-dense gather indices, capacity buckets, oracles
``nms``             C15     circle NMS, perception_utils IoU-BEV NMS, area class remapper
``decode``          C16     CenterHead dense decode (and at given cells), Autoware DetectedObject mapping
``ops``             --      kernel package-data helpers (custom ``generic_op`` kernels live in ``ops/kernels``)
``ops.conv``        C17     conv2d builders (weights prepared once, fused activations, DRAM slicing), K-split,
                            ConvTranspose k == s, feature-map glue
``ops.upsample``    C18     nearest up-sampling, ``F.interpolate`` matrices, separable device resize
``ops.attention``   C20     SDPA wrapper (non-causal, explicit scale, chunk table, aligned masked keys), heads
``ops.gather``      C19     gather-form scatter (zero sentinel row + TILE / PADDED ``ttnn.embedding``), row gathers
``ops.topk``        C21     top-k proposal selection (class-major ``topk_large_indices`` row, exact decode, set metrics)
``ops.heatmap``     C22     sigmoid + 3x3 local max of TF / BF / PT heatmaps (one exact masked chain)
``ops.deform``      C23     grid_sample helpers: fp32 affine / resize grids (exact identity), P9 rules, kernel emulation
``ops.segment``     K1      per-segment max over rows sorted by segment (``generic_op`` kernel, exact, no
                            per-core args), the log-step stock-op fallback, CSR / shift tables, oracles
``models``          C24 C25 device sub-networks: ``models.second`` (SECOND + SECONDFPN), ``models.pillars``
                    C27 C26 (PillarFeatureNet + its input staging), ``models.centerhead`` (CenterPoint dense
                            head: K-split shared conv, merged heads), ``models.resnet`` (ResNet
                            bottleneck / basic-block builders, cameras as batch), ``models.transfusion_head``
                            (TransFusion query head: selection, query init, decoder layer, merged heads)
==================  ======  =============================================================================
"""

__version__ = "0.23.2"

__all__ = [
    "__version__",
    "api_base",
    "decode",
    "device",
    "geometry",
    "golden",
    "image",
    "image_area",
    "image_linear",
    "image_triangle",
    "io",
    "knobs",
    "metrics",
    "models",
    "nms",
    "ops",
    "outputs",
    "pointcloud",
    "precision",
    "profiling",
    "server",
    "sparse",
    "tensors",
    "trace",
    "voxelize",
    "weights",
]


def __getattr__(name: str):
    """Load submodules on first attribute access (``ttaw.trace``), keeping ``import ttaw`` free of side effects."""
    if name in __all__ and name != "__version__":
        import importlib

        return importlib.import_module(f".{name}", __name__)
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")


def __dir__():
    return sorted(set(globals()) | set(__all__))