cordic-fixedpoint-algorithm

基于定点数的 CORDIC 算法 Python 参考实现。

支持圆周模式（sin/cos/atan2/模长）与双曲模式（sinh/cosh/tanh/ln/√x）， 全程纯整数运算，CORDIC 迭代核零乘法。

---

特性

• 圆周旋转：sin(θ), cos(θ)，支持 [-π, π] 全范围（自动象限折叠）
• 圆周向量：atan2(y, x) 角度 + magnitude 模长，全象限
• 双曲旋转：sinh(x), cosh(x), tanh(x)
• 双曲向量：ln(x), √x，含范围规约（无输入上限）
• 预计算常数表（const.txt）：增益系数在编译期烤进初始值，运行时零重算
• CORDIC 迭代核：只有 >>、+、-，零乘法
• 可配置 frac_bits（默认 28）和 n_iters（默认 20）
• 饱和截断防止数值回绕
• 219 条 TDD 测试全部通过
• 交互式命令行计算器（main.py）

---

乘法统计（运行时）

函数	乘法次数	说明
sin, cos	0	初始 x₀ = 1/Kc，从常数表直接加载
sinh, cosh, tanh	0	初始 x₀ = Kh，从常数表直接加载
atan2（角度）, ln	0	z 寄存器自然积累，无增益影响
sqrt	1	预缩放输入 x，消除后乘
magnitude（模长）	2	分别预缩放输入 x 和 y

---

快速上手

1. 生成预计算常数表

python const.py

输出 const.txt，包含所有 LUT 表和增益系数（整数格式）。

2. 启动交互式计算器

python main.py

╔══════════════════════════════════════════════════════════════╗
║            CORDIC 定点数计算器  （纯移位+加减，无乘法）           ║
╠══════════════════════════════════════════════════════════════╣
║  sin 1.5708   cos 3.1416   atan2 3 4   mag 3 4              ║
║  sinh 0.5     cosh 1.0     tanh 0.8                         ║
║  ln 2.718     sqrt 144                                      ║
║  deg 45 sin   （度数模式）                                    ║
╚══════════════════════════════════════════════════════════════╝
cordic> sqrt 144
  结果 = 11.99999988    黄金值 = 12.00000000    误差 Δ = 1.19e-07
cordic> deg 60 sin
  结果 = 0.86602527    黄金值 = 0.86602540    误差 Δ = 1.28e-07

3. 作为库使用

pip install -e ".[dev]"

from cordic import sin_cos, atan2_magnitude, sinh_cosh, cordic_ln, cordic_sqrt

s, c = sin_cos(1.0472)                  # sin(60°), cos(60°)
angle, mag = atan2_magnitude(3.0, 4.0) # atan2=0.9273, |v|=5.0
sh, ch = sinh_cosh(0.5)                 # sinh≈0.5211, cosh≈1.1276
print(cordic_ln(100))                   # ≈ 4.6052
print(cordic_sqrt(144))                 # ≈ 12.0

---

项目结构

├── const.py              预计算常数生成脚本（运行一次）
├── const.txt             预计算常数表（整数 LUT + 增益系数）
├── main.py               交互式命令行计算器
├── pyproject.toml        项目配置 + pytest 设置
├── .gitignore
│
├── src/cordic/           核心库（可作为库导入）
│   ├── fixed_point.py    定点数类（Q 格式，饱和截断）
│   ├── lut.py            arctan/arctanh LUT + 增益系数
│   ├── core.py           CORDIC 迭代核（圆周/双曲）
│   ├── circular.py       圆周模式 API
│   └── hyperbolic.py     双曲模式 API（含范围规约）
│
├── tests/                TDD 测试套件（219 条，全部通过）
│
└── docs/
    ├── prd.md            产品需求文档
    ├── algorithm_history.md  CORDIC 历史（1959 年的故事）
    ├── fixed_point_basics.md 定点数科普
    ├── circular_mode.md      圆周模式原理
    ├── hyperbolic_mode.md    双曲模式 + ln/√ 推导
    └── doc_tree.md           完整目录说明

---

精度指标

配置	最大绝对误差
n_iters=14, frac_bits=15（16 位仿真）	< 1×10⁻³
n_iters=20, frac_bits=28（默认）	< 1×10⁻⁴
n_iters=28, frac_bits=28（高精度）	< 1×10⁻⁶

---

运行测试

pytest tests/ -v

---

License

MIT