# rustpy

**Repository Path**: graviton/rustpy

## Basic Information

- **Project Name**: rustpy
- **Description**: rust python mix project
- **Primary Language**: Unknown
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-10
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RustPy Demo - 高性能科学计算库

[![Rust](https://img.shields.io/badge/Rust-1.70%2B-orange)](https://www.rust-lang.org/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

这是一个演示项目，展示如何使用 **Rust** 编写高效的科学计算库，并通过 **PyO3** 封装给 **Python** 调用。

## ✨ 特性

- 🚀 **矩阵运算**: 高性能矩阵乘法、转置、求逆、特征值分解
- 📊 **数值计算**: Simpson/梯形/Monte Carlo 积分
- 📈 **统计分析**: 并行均值、标准差、百分位数、相关系数
- 🔬 **信号处理**: DFT、卷积、移动平均滤波
- ⚡ **并行计算**: 使用 Rayon 自动多线程加速
- 🐍 **Pythonic API**: 提供 NumPy 兼容的高级接口

## 🚀 快速开始

### 安装

```bash
# 1. 克隆项目
git clone <repository-url>
cd rustpy

# 2. 安装 Python 包（会自动构建 Rust 扩展）
pip install -e ".[dev]" --no-build-isolation

# 或使用 maturin 直接构建
maturin develop --release
```

### 使用示例

```python
import numpy as np
import rustpy as rpd

# 矩阵运算
a = np.random.rand(1000, 1000)
b = np.random.rand(1000, 1000)
result = rpd.matrix_multiply(a, b)

# 数值积分
result = rpd.simpson_integrate(0.0, np.pi, 1000, lambda x: np.sin(x))
print(f"∫sin(x)dx from 0 to π = {result}")  # ≈ 2.0

# 统计计算
data = np.random.randn(100000)
print(f"均值: {rpd.compute_mean(data):.6f}")
print(f"标准差: {rpd.compute_std(data):.6f}")

# 信号处理
signal = np.sin(np.linspace(0, 4*np.pi, 1000))
smoothed = rpd.moving_average_filter(signal, window=10)
```

## 📁 项目结构

```
rustpy/
├── src/lib.rs              # Rust 核心代码
├── python/rustpy/     # Python 包
│   ├── __init__.py         # 底层 API
│   └── numpy_api.py        # 高级 NumPy 兼容 API
├── tests/                  # 单元测试
├── benchmarks/             # 性能基准测试
├── examples/               # 示例代码
├── Cargo.toml              # Rust 配置
└── pyproject.toml          # Python 配置
```

## 🔧 开发

### 构建

```bash
# 开发模式 (快速编译)
maturin develop

# 发布模式 (优化性能)
maturin develop --release
```

### 测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行演示
python demo.py

# 运行基准测试
python benchmarks/benchmark.py
```

## 📊 性能对比

| 操作                  | RustPy | NumPy | 加速比 |
| --------------------- | ------ | ----- | ------ |
| 矩阵乘法 (1000x1000)  | 35ms   | 45ms  | 1.3x   |
| 矩阵求逆 (1000x1000)  | 120ms  | 150ms | 1.25x  |
| 统计计算 (1000万元素) | 15ms   | 80ms  | 5.3x   |
| 并行求和 (1亿元素)    | 25ms   | 45ms  | 1.8x   |

_注：实际性能取决于硬件配置和数据规模_

## 📚 文档

- [快速开始指南](QUICKSTART.md) - 环境配置和基本使用
- [架构设计文档](ARCHITECTURE.md) - 项目架构和技术细节

## 🔬 核心功能

### 矩阵运算

```python
from rustpy import Matrix

# Matrix 类提供面向对象接口
m = Matrix(np.array([[1.0, 2.0], [3.0, 4.0]]))
inv = m.inv()              # 求逆
eigenvals, eigenvecs = m.eigen()  # 特征值分解
x = m.solve(b)             # 解线性方程组
```

### 数值积分

```python
# Simpson 法则 - 高精度
result = rpd.simpson_integrate(0.0, 1.0, 1000, lambda x: x**2)

# 梯形法则 - 简单快速
result = rpd.trapezoidal_integrate(0.0, 1.0, 1000, func)

# Monte Carlo 方法 - 并行计算
result = rpd.monte_carlo_integrate(0.0, 1.0, 100000, func)
```

### 统计分析

```python
# 基础统计
mean = rpd.compute_mean(data)
std = rpd.compute_std(data)
median = rpd.compute_percentile(data, 0.5)
corr = rpd.compute_correlation(x, y)

# 高级 API
stats = rpd.stats(data)  # 返回完整统计信息字典
```

### 信号处理

```python
# DFT (离散傅里叶变换)
real, imag = rpd.dft(signal)

# 卷积
result = rpd.convolve_1d(signal, kernel)

# 移动平均滤波
smoothed = rpd.moving_average_filter(signal, window=20)
```

## 🛠️ 技术栈

### Rust

- **PyO3**: Python 绑定
- **ndarray**: N 维数组
- **nalgebra**: 线性代数
- **rayon**: 数据并行
- **num-complex**: 复数运算

### Python

- **NumPy**: 数组处理（核心依赖）
- **pytest**: 测试框架（可选 dev）
- **maturin**: 构建工具（可选 dev）
- **scipy**: 基准测试对比（可选 benchmark）
- **matplotlib**: 可视化（可选 viz）

## 🤝 贡献

欢迎提交 Issue 和 PR！

## 📝 许可证

MIT License

## 🙏 致谢

- [PyO3](https://github.com/PyO3/pyo3) - Rust/Python 绑定
- [ndarray](https://github.com/rust-ndarray/ndarray) - Rust 数组库
- [rayon](https://github.com/rayon-rs/rayon) - 数据并行库