=========================================
Triton-distributed-ascend documentation
=========================================

Triton-distributed-ascend is a distributed computing framework extended from the Triton
language and optimized for Ascend AI processors. It enables efficient distributed computing
on Ascend NPUs, with communication primitives and computation-communication overlap
optimizations aimed at large-scale distributed training and inference.

The project builds on the multi-level abstraction capabilities of MLIR to map distributed
operators written in Triton onto Ascend AI processors, and exposes fine-grained interfaces
for controlling on-chip memory and pipeline synchronization.

Getting Started
---------------

Work through these in order:

- :doc:`getting-started/installation` — hardware and software prerequisites, CANN setup,
  and Python dependencies.
- :doc:`getting-started/build` — building Triton-distributed-ascend, AscendNPU-IR, and
  shmem from source.
- :doc:`getting-started/quick-start` — running your first distributed kernel and verifying
  the installation.

See :doc:`getting-started/release_note` for the versioning policy, branch lifecycle, and
compatibility matrices.

Key Features
------------

- **Distributed communication primitives** — AllReduce, AllGather, ReduceScatter, All2All.
- **Computation-communication overlap** — overlapped execution for improved throughput.
- **AscendNPU IR-based compiler optimizations** — optimizations that use Ascend hardware
  features directly.
- **Python-friendly interfaces** — concise Python APIs that integrate into existing deep
  learning frameworks.

Architecture
------------

- :doc:`architecture` — Distributed architecture design, terminology, compilation pipeline,
  and communication engine details.

API Reference
-------------

The API documentation covers five main areas:

- :doc:`api/triton_dist_semantics` — Design philosophy, semantic model, and programming patterns
  for tile-centric computation-communication overlap.
- :doc:`api/triton_dist_language` — Distributed operations for Triton kernels (``wait``,
  ``consume_token``, ``rank``, ``num_ranks``, ``symm_at``, ``notify``, ``extern_call``).
- :doc:`api/shmem_device` — Device-side ACLSHMEM APIs for use within kernels (RMA operations,
  signaling, barriers, and synchronization).
- :doc:`api/shmem_host` — Host-side ACLSHMEM APIs for initialization, memory management,
  and host-initiated communication.
- :doc:`api/helper` — Swizzle helper functions for GEMM and communication tile scheduling.
- :doc:`api/autotune_api` — Distributed autotune API for multi-device kernel tuning.

Developer Guide
---------------

- :doc:`developer-guide/kernel_debugging` — Extracting IR, printing compiler passes, and
  debugging synchronization issues with ``bishengir-compile`` flags.
- :doc:`developer-guide/environment_variable` — Environment variables and compiler options
  for debugging and optimization.
- :doc:`developer-guide/kernel-debugging/precision` — Multi-card fusion operator precision
  verification.
- :doc:`developer-guide/kernel-development/td_kernel_dev` — Single operator development with
  distributed kernels.
- :doc:`developer-guide/kernel-performance/performance_optimization` — Performance optimization
  techniques and best practices.
- :doc:`developer-guide/kernel-performance/operator_performance_testing_and_tuning_autotune_guide` —
  Operator performance testing and autotune feature usage.
- :doc:`developer-guide/kernel-performance/profiling` — Kernel performance profiling guide.

Tutorials
---------

- :doc:`tutorial/allgather_gemm` — AllGather+GEMM fusion optimization tutorial.
- :doc:`tutorial/autotune_optimization_example` — Autotune example and optimization
  practices.
- :doc:`tutorial/reverse_all2all` — Reverse All2All for MoE distributed kernels.

FAQ
---

- :doc:`FAQ` — Frequently asked questions and troubleshooting.

.. toctree::
   :maxdepth: 1
   :caption: Getting Started
   :hidden:

   getting-started/installation
   getting-started/build
   getting-started/quick-start
   getting-started/release_note

.. toctree::
   :maxdepth: 1
   :caption: Architecture
   :hidden:

   architecture

.. toctree::
   :maxdepth: 1
   :caption: API Reference
   :hidden:

   api/triton_dist_semantics
   api/triton_dist_language
   api/shmem_device
   api/shmem_host
   api/helper
   api/autotune_api

.. toctree::
   :maxdepth: 1
   :caption: Developer Guide
   :hidden:

   developer-guide/kernel_debugging
   developer-guide/environment_variable
   developer-guide/kernel-debugging/precision
   developer-guide/kernel-development/td_kernel_dev
   developer-guide/kernel-performance/performance_optimization
   developer-guide/kernel-performance/operator_performance_testing_and_tuning_autotune_guide
   developer-guide/kernel-performance/profiling

.. toctree::
   :maxdepth: 1
   :caption: Tutorials
   :hidden:

   tutorial/allgather_gemm
   tutorial/autotune_optimization_example
   tutorial/reverse_all2all

.. toctree::
   :maxdepth: 1
   :caption: FAQ
   :hidden:

   FAQ