Metadata-Version: 2.1
Name: mx_driving
Version: 26.1.0rc1.post2
Summary: mx_driving v26.1.0rc1 for PyTorch 2.6.x/2.7.x/2.8.x on Atlas A2 (Ascend NPU acceleration for autonomous driving)
Author: Ascend Contributors
Keywords: mx_driving
Requires-Dist: torch>=2.6.0,<2.9.0
Requires-Dist: numpy
Requires-Dist: pyyaml
Requires-Dist: scipy
Description-Content-Type: text/markdown

# mx_driving

## Overview

**mx_driving** is an operator and model acceleration library for autonomous driving, embodied intelligence VLA, and world models, developed on the **Ascend NPU** platform. It provides a suite of high-performance operators and model migration examples that support the **PyTorch** framework, enabling developers to leverage the powerful compute capabilities of **Ascend AI Processors** for autonomous driving workloads.

Ascend is a full-stack AI computing infrastructure for industry applications and services based on Huawei Ascend processors and software. For more information about Ascend, see [Ascend Community](https://www.hiascend.com/en/).

## Installation

### From Binary

1. **Install PyTorch and torch-npu**

Before installing mx_driving, complete the installation of PyTorch and torch-npu. For torch-npu installation, refer to [torch-npu on PyPI](https://pypi.org/project/torch-npu/).

```bash
# Install PyTorch
pip install torch==2.7.1

# Install torch-npu
pip install torch-npu==2.7.1
```

2. **Install mx_driving**

mx_driving provides two PyPI packages based on hardware platform:

| PyPI Package | Hardware | Install Command |
| --- | --- | --- |
| `mx-driving` | Atlas A2 (default) | `pip install mx-driving` |
| `mx-driving-a5` | Atlas A5 | `pip install mx-driving-a5` |

Both packages provide the same `import mx_driving` interface. Choose based on your hardware:

```bash
# For Atlas A2 (default, most users)
pip install mx-driving

# For Atlas A5
pip install mx-driving-a5
```

If you need a specific PyTorch version:

```bash
# Atlas A2 + PyTorch 2.1.x
pip install mx-driving==26.1.0rc1.post1

# Atlas A2 + PyTorch 2.6.x/2.7.x/2.8.x (this version)
pip install mx-driving==26.1.0rc1.post2

# Atlas A5 + PyTorch 2.6.x/2.7.x/2.8.x
pip install mx-driving-a5==26.1.0rc1.post2
```

> **Note:** `mx-driving` and `mx-driving-a5` cannot be installed simultaneously since both provide the `mx_driving` Python package.

### From Source

For source compilation, refer to [Deploying Driving SDK Environment](https://gitcode.com/Ascend/DrivingSDK/blob/master/docs/zh/installation/installation.md).

## Getting Started

### Prerequisites

Initialize the **CANN** environment variable:

```bash
source /usr/local/Ascend/ascend-toolkit/set_env.sh
```

### Quick Verification

You can quickly verify the installation with a simple example using the `scatter_max` operator:

```python
import torch
import torch_npu
from mx_driving import scatter_max

updates = torch.tensor([[2, 0, 1, 3, 1, 0, 0, 4],
                        [0, 2, 1, 3, 0, 3, 4, 2],
                        [1, 2, 3, 4, 4, 3, 2, 1]], dtype=torch.float32).npu()
indices = torch.tensor([0, 2, 0], dtype=torch.int32).npu()
out = updates.new_zeros((3, 8))
out, argmax = scatter_max(updates, indices, out)
print(out)
print(argmax)
```

### One-Click Patcher

mx_driving provides a one-click Patcher mechanism that automatically replaces GPU-based implementations with NPU-optimized implementations, enabling seamless model migration from GPU to Ascend NPU:

```python
from mx_driving import patcher
patcher.patch_all()
```

For more details, refer to [One-Click Patcher](https://gitcode.com/Ascend/DrivingSDK/blob/master/docs/zh/features/patcher.md).

## High-Performance API

mx_driving provides various categories of high-performance operators optimized for Ascend NPU:

| Category | Operators |
| --- | --- |
| General | `scatter_max`, `scatter_mean`, `scatter_add`, `knn`, `furthest_point_sampling`, `group_points`, `unique_voxel`, `graph_softmax`, ... |
| Sampling | `bev_pool_v1`, `bev_pool_v2`, `bev_pool_v3`, `npu_voxel_pooling_train`, `roiaware_pool3d`, `border_align`, ... |
| Voxelization | `voxelization`, `dynamic_scatter` |
| Detection | `nms3d`, `boxes_iou_bev`, `box_iou_quadri`, `diff_iou_rotated_2d`, `points_in_boxes_all`, ... |
| Sparse | `SparseConv3d`, `SubMConv3d`, `SparseInverseConv3d` |
| Fusion | `multi_scale_deformable_attn`, `deformable_aggregation`, `npu_add_relu`, `npu_fused_bias_leaky_relu`, `npu_batch_matmul`, ... |

For the complete API list, refer to [API Reference](https://gitcode.com/Ascend/DrivingSDK/blob/master/docs/zh/api/README.md).

## Supported Models

mx_driving provides migration and optimization examples for autonomous driving models on Ascend servers, including perception, planning, end-to-end, and VLA models:

- **BEVFusion** — Multi-task multi-sensor fusion framework
- **BEVFormer** — Bird's-eye-view perception from camera images
- **Sparse4D** — Sparse 4D perception framework
- And more...

For the full model list, refer to [Model Support List](https://gitcode.com/Ascend/DrivingSDK/blob/master/docs/zh/models/support_list.md).

## PyTorch and Python Version Compatibility

### mx-driving (Atlas A2)

| Version | CPU Architecture | Python Version | PyTorch Version | torch_npu Version |
| --- | --- | --- | --- | --- |
| 26.1.0rc1.post1 | x86 & aarch64 | 3.8, 3.9, 3.10, 3.11 | 2.1.0 | v2.1.0-26.1.0rc1 |
| 26.1.0rc1.post2 | x86 & aarch64 | 3.9, 3.10, 3.11 | 2.6.0/2.7.1/2.8.0 | v2.7.1-26.1.0rc1 |

### mx-driving-a5 (Atlas A5)

| Version | CPU Architecture | Python Version | PyTorch Version | torch_npu Version |
| --- | --- | --- | --- | --- |
| 26.1.0rc1.post2 | x86 & aarch64 | 3.9, 3.10, 3.11 | 2.6.0/2.7.1/2.8.0 | v2.7.1-26.1.0rc1 |

## Hardware Support

| Product Series | Product Model |
| --- | --- |
| Atlas A2 Training Series | Atlas 800T A2, Atlas 900 A2 PoD, Atlas 200T A2 Box16, Atlas 300T A2 |
| Atlas A3 Training Series | Atlas 800T A3, Atlas 900 A3 SuperPoD |

## Branch Maintenance Policies

| Status | Duration | Description |
| --- | --- | --- |
| Planning | 1-3 months | Plan features |
| Development | 3 months | Develop features |
| Maintained | 6-12 months | Incorporate resolved issues and release versions. Regular versions: 6 months; Long-term support versions: 12 months |
| Unmaintained | 0-3 months | Incorporate resolved issues, no dedicated maintainers, no releases |
| End Of Life (EOL) | N/A | No longer accept any modifications |

## Version Maintenance

| Version | Maintenance Policy | Status | Release Date | Subsequent Status | EOL Date |
| --- | --- | --- | --- | --- | --- |
| v26.1.0rc1 | Release Candidate | Maintained | 2026/05/30 | Expected unmaintained from 2026/11/30 | |
| v26.0.0 | Regular Release | Maintained | 2026/03/30 | Expected unmaintained from 2026/09/30 | |
| v7.3.0 | Regular Release | Maintained | 2025/12/30 | Expected unmaintained from 2026/06/30 | |
| v7.2.RC1 | Regular Release | Maintained | 2025/09/30 | Unmaintained from 2026/03/30 | |
| v7.1.RC1 | Regular Release | Unmaintained | 2025/06/30 | Unmaintained from 2025/12/30 | |

## Suggestions and Communication

If you have any questions or suggestions, you can submit [Issues](https://gitcode.com/Ascend/DrivingSDK/issues). We will reply as soon as possible.

## License

- Driving SDK is licensed under the [Apache-2.0 License](https://gitcode.com/Ascend/DrivingSDK/blob/master/LICENSE).
- Documentation under the `docs` directory is licensed under CC-BY 4.0.

## Contributing

Before contributing, please sign the [Open Source Contributor License Agreement (CLA)](https://clasign.osinfra.cn/sign/gitee_ascend-1611222220829317930).

If you encounter a bug, please [submit an issue](https://gitcode.com/Ascend/DrivingSDK/issues).

If you plan to contribute bug fixes, please submit Pull Requests. See [contribution guidelines](https://gitcode.com/Ascend/DrivingSDK/blob/master/CONTRIBUTING.md) for details.

If you plan to contribute new features, please create an issue for discussion first.
