Metadata-Version: 2.2
Name: mantissa-cpp
Version: 0.1.1
Summary: Python bindings for the Mantissa C++ math library (linalg module)
Author-Email: YuruTu <707101557@qq.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/YuruTu/Mantissa
Project-URL: Repository, https://gitlab.com/YuruTu/Mantissa
Project-URL: Issues, https://gitlab.com/YuruTu/Mantissa/-/issues
Project-URL: Documentation, https://gitlab.com/YuruTu/Mantissa/-/tree/main/docs
Requires-Python: >=3.8
Requires-Dist: numpy
Description-Content-Type: text/markdown

# Mantissa

> **高性能 C++17 数学算法库** — 模块化架构 · Python 零拷贝绑定 · 多后端可扩展

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![C++17](https://img.shields.io/badge/C%2B%2B-17-00599C.svg)](https://en.cppreference.com/w/cpp/17)
[![Python](https://img.shields.io/badge/Python-3.8%2B-3776AB.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](#构建与测试)
[![nanobind](https://img.shields.io/badge/binding-nanobind%203.0-green)](https://nanobind.readthedocs.io/)

---

## Quick Start

### Python（30 秒上手）

```bash
# PyPI 包名为 mantissa-cpp（mantissa 被 Twisted 项目占用）；
# 安装后 Python 代码仍用 `import mantissa`。
pip install mantissa-cpp
```

```python
import numpy as np
import mantissa

# 对称矩阵特征分解
A = np.array([[4.0, 1.0], [1.0, 3.0]])
values, vectors = mantissa.eig_sym(A)
print(f"Eigenvalues: {values}")   # [2.382, 4.618]

# SVD 分解（支持矩形矩阵）
U, S, Vt = mantissa.svd(A)

# 线性方程组求解 A·X = B
B = np.array([1.0, 2.0])
X = mantissa.solve(A, B)
```

### C++

```cpp
#include <mantissa/linalg/decomposition/svd.hpp>
#include <mantissa/linalg/solve/solve.hpp>

// 构造 Tensor（float64, CPU）
auto A = mantissa::Tensor::from_vector({4.0, 1.0, 1.0, 3.0}, {2, 2});

// SVD 分解
auto [U, S, Vt] = mantissa::linalg::svd(A);

// 求解线性方程组
auto B = mantissa::Tensor::from_vector({1.0, 2.0}, {2});
auto X = mantissa::linalg::solve(A, B);
```

<details>
<summary>C++ 集成步骤（Conan + CMake）</summary>

```powershell
# 1. 添加 Conan remote 并安装依赖
conan remote add gitlab https://gitlab.com/api/v4/projects/86406866/packages/conan
conan remote login gitlab <user> -p <token>
conan install . -of build --build=missing -s build_type=Release -r gitlab

# 2. 配置 + 构建
cmake --preset conan-default
cmake --build --preset conan-release
```

</details>

---

## Feature Highlights

| 特性 | Mantissa | 直接用 Eigen | NumPy/SciPy |
|------|----------|-------------|-------------|
| C++17 原生 API | ✅ Tensor 抽象 + 算子分派 | ❌ 需手动管理 Matrix 类型 | — |
| Python 零拷贝绑定 | ✅ nanobind + Buffer Protocol | ❌ 需自行绑定 | ✅ 原生 |
| 多后端架构 | ✅ CPU / CUDA (planned) | 部分（需手写） | ❌ 仅 CPU |
| 数值安全校验 | ✅ 显式异常，无静默回退 | ❌ UB on misuse | 部分 |
| 模块化按需链接 | ✅ 独立 .so/.dll | Header-only | — |
| abi3 Wheel（一次构建全版本） | ✅ Python 3.8+ | — | — |

---

## 已实现算子

所有算子当前支持 **CPU / float64**，基于 Eigen 5 实现：

| 算子 | 分类 | 描述 | Python |
|------|------|------|--------|
| `eig_sym` | eigen | 对称矩阵特征分解（SelfAdjointEigenSolver） | ✅ |
| `matrix_sqrt` | matrix_func | 对称半正定矩阵平方根 | ✅ |
| `matrix_exp` | matrix_func | 对称矩阵指数 | ✅ |
| `cholesky` | decomposition | Cholesky 分解 A = LLᵀ | ✅ |
| `svd` | decomposition | Thin SVD（支持矩形） | ✅ |
| `solve` | solve | 线性方程组 A·X = B（FullPivLU） | ✅ |

📖 详细 API 文档见 [docs/api/](docs/api/)

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────┐
│  Layer 3 — Python Bindings (nanobind, abi3)          │
├─────────────────────────────────────────────────────┤
│  Layer 2 — Algorithm Layer                           │
│  linalg: eigen · decomposition · matrix_func · solve │
├─────────────────────────────────────────────────────┤
│  Layer 0-1 — Core (Tensor · Storage · Shape · Alloc) │
│  Backend Dispatcher · glog Logging                   │
└─────────────────────────────────────────────────────┘
```

**设计原则**：分层隔离 · 单向依赖 · 后端多态 · 显式优于隐式

📐 完整架构文档见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)

---

## 模块拆分

一个 domain 对应一个动态库，命名规则为 **`mantissa_<domain>_<backend>`**：

| 模块 | 产物 | 说明 |
|------|------|------|
| `core` | `mantissa_core.dll/.so` | 基础设施（Tensor / Storage / Shape / Allocator / Backend / Logging） |
| `linalg` | `mantissa_linalg_cpu.dll/.so` | 线性代数全部算子（子目录仅作源码组织） |

通过 [`cmake/MantissaModule.cmake`](cmake/MantissaModule.cmake) 的 `mantissa_add_module()` 创建模块，自动链接 `mantissa_core`、生成导出宏并注册安装规则。

---

## 构建与测试

### 前置条件

- C++17 编译器（MSVC 2019+ / GCC 9+ / Clang 10+）
- CMake 3.24+
- Conan 2.x
- Python 3.8+（可选，用于 Python 绑定）

### 依赖安装

```powershell
# 添加 GitLab Conan registry（一次性操作）
conan remote add gitlab https://gitlab.com/api/v4/projects/86406866/packages/conan
conan remote login gitlab <user> -p <token>

# 安装依赖
conan install . -of build --build=missing -s build_type=Release -r gitlab
```

### 编译

```powershell
cmake --preset conan-default
cmake --build --preset conan-release
```

### 运行测试（96 个用例）

```powershell
# Windows — 需注入 DLL 路径
cmd /c "build\build\generators\conanrun.bat && ctest --preset conan-release --output-on-failure"

# Linux / macOS
source build/build/generators/conanrun.sh && ctest --preset conan-release --output-on-failure
```

### 构建 Python Wheel

```powershell
pip wheel . --no-build-isolation ^
    -C cmake.args="-DCMAKE_TOOLCHAIN_FILE=build/build/generators/conan_toolchain.cmake"
```

---

## CMake 选项

| 选项 | 默认 | 说明 |
|------|------|------|
| `BUILD_SHARED_LIBS` | `ON` | 以动态库形式构建各模块 |
| `MANTISSA_BUILD_TESTS` | `ON` | 构建单元测试 |
| `MANTISSA_BUILD_PYTHON` | `OFF` | 构建 Python 绑定（nanobind） |
| `MANTISSA_ENABLE_MOCKCPP` | `ON` | 启用 mockcpp 打桩测试 |
| `MANTISSA_ENABLE_NATIVE` | `OFF` | 启用 `-march=native` / `/arch:AVX2` |

---

## Roadmap

```
v0.1  ✅ C++ 核心 + CPU 后端 + Python 绑定 (nanobind abi3)  ← 当前
  │
  ├── v0.2  CI/CD + PyPI 发布 + 文档站
  │
  ├── v0.3  CUDA 后端 (关键算子)
  │
  ├── v0.4  PyTorch 桥接 (autograd + torch.library)
  │
  ├── v1.0  完整多后端 + MPFR 高精度 + 稳定 API
  │
  └── v2.0  JAX 集成 + 分布式后端
```

---

## 项目结构

```
Mantissa/
├── include/mantissa/     公共头文件
│   ├── core/             Layer 0-1：Tensor, Shape, Storage, Backend...
│   └── linalg/           Layer 2：算子接口声明
├── src/                  实现源码
│   ├── core/             核心层实现
│   └── linalg/           算子 CPU 实现
├── python/               nanobind Python 绑定
├── tests/                gtest + mockcpp 测试（96 用例）
├── cmake/                CMake 模块与编译选项
├── docs/                 架构文档与 API 参考
└── examples/             使用示例
```

---

## 文档

| 文档 | 说明 |
|------|------|
| [Getting Started](docs/getting-started.md) | 三条路径快速上手（C++ / Python / 贡献者） |
| [Architecture](docs/ARCHITECTURE.md) | 完整架构设计（分层、后端、扩展机制） |
| [API Reference](docs/api/) | 各算子详细接口文档 |
| [Contributing](CONTRIBUTING.md) | 贡献指南与代码规范 |

---

## License

[MIT](LICENSE) © 2026 Yuru.Tu
