.. _fast_math_func_test_zh:

快速数学函数测试示例
====================

概述
----

本示例演示了 HPM Math 中间件中快速数学函数的使用方法，包括性能测试和精度测试。
该实现提供了优化的三角函数和反三角函数，可在速度和精度之间进行配置权衡。

支持的函数
----------

1. **Sin/Cos 函数**\ （基于查找表）

   - ``hpm_math_fast_sinf`` / ``hpm_math_fast_cosf``：无插值（最快）
   - ``hpm_math_fast_sinf_linear`` / ``hpm_math_fast_cosf_linear``：线性插值
   - ``hpm_math_fast_sinf_quadratic`` / ``hpm_math_fast_cosf_quadratic``：二次插值（最精确）

2. **SinCos 函数**\ （优化的同时计算 sin+cos）

   - ``hpm_math_fast_sincosf_linear``：线性插值同时计算 sin 和 cos
   - ``hpm_math_fast_sincosf_quadratic``：二次插值同时计算 sin 和 cos
   - 比分别调用 sinf 和 cosf 快得多（共享角度归一化和索引计算）

3. **Tan 函数**\ （使用优化的 sincosf）

   - ``hpm_math_fast_tanf_linear``：线性插值
   - ``hpm_math_fast_tanf_quadratic``：二次插值
   - ``hpm_math_fast_tanf_hybrid``：混合方法（最高精度，约 2.5 倍提升）

     - 在奇点附近使用多项式近似，避免除法误差放大
     - 其他区域使用 sin/cos 除法，获得最佳整体精度

4. **Atan/Atan2 函数**\ （多项式逼近 + 范围归约）

   - ``hpm_math_fast_atanf``：快速反正切，使用范围归约
   - ``hpm_math_fast_atan2f``：快速双参数反正切

测试项目
--------

本测试包含以下测试项目：

**性能测试**

对每个函数进行 1000 次迭代，测量 CPU 时钟周期数。

1. Sin 函数

   - ``sinf`` (标准库)：标准库正弦函数
   - ``hpm_math_fast_sinf``：快速正弦，无插值
   - ``hpm_math_fast_sinf_linear``：快速正弦，线性插值
   - ``hpm_math_fast_sinf_quadratic``：快速正弦，二次插值

2. Cos 函数

   - ``cosf`` (标准库)：标准库余弦函数
   - ``hpm_math_fast_cosf``：快速余弦，无插值
   - ``hpm_math_fast_cosf_linear``：快速余弦，线性插值
   - ``hpm_math_fast_cosf_quadratic``：快速余弦，二次插值

3. SinCos 函数

   - ``hpm_math_fast_sincosf_linear``：同时计算 sin+cos，线性插值
   - ``hpm_math_fast_sincosf_quadratic``：同时计算 sin+cos，二次插值

4. Tan 函数

   - ``tanf`` (标准库)：标准库正切函数
   - ``hpm_math_fast_tanf_linear``：快速正切，线性插值
   - ``hpm_math_fast_tanf_quadratic``：快速正切，二次插值
   - ``hpm_math_fast_tanf_hybrid``：快速正切，混合方法

5. Atan 函数

   - ``atanf`` (标准库)：标准库反正切函数
   - ``hpm_math_fast_atanf``：快速反正切，范围归约

6. Atan2 函数

   - ``atan2f`` (标准库)：标准库双参数反正切
   - ``hpm_math_fast_atan2f``：快速双参数反正切

**精度测试**

与标准库对比，在数百万个测试点上测量最大误差和平均误差。

1. Sin 精度：在 [0, 2π] 范围内以 1e-6 rad 间隔测试 6,530,344 个点
2. Cos 精度：在 [0, 2π] 范围内以 1e-6 rad 间隔测试 6,530,344 个点
3. Tan 精度：在 [0, 2π] 范围内测试 6,110,914 个点，避开奇点（``|x - π/2| > 0.1``\ ）
4. Atan 精度：在 [-10, 10] 范围内以 0.0001 间隔测试 199,874 个点
5. Atan2 精度：使用单位圆坐标测试 6,284 个点

性能测试结果
------------

以下结果在 HPM6E00EVK 600MHz 上测得（表大小：4096）。

.. note::

   性能可能因芯片型号、编译器优化级别、缓存配置和其他系统设置而有所不同。
   以下结果仅供参考。

**Sin 函数（每 1000 次操作的时钟周期数）**

+----------------------------------+----------+----------+
| 函数                             | 总计     | 每次     |
+==================================+==========+==========+
| sinf (标准库)                    | 104053   | 104      |
+----------------------------------+----------+----------+
| hpm_math_fast_sinf               | 14118    | 14       |
+----------------------------------+----------+----------+
| hpm_math_fast_sinf_linear        | 26442    | 26       |
+----------------------------------+----------+----------+
| hpm_math_fast_sinf_quadratic     | 39815    | 40       |
+----------------------------------+----------+----------+

**Cos 函数（每 1000 次操作的时钟周期数）**

+----------------------------------+----------+----------+
| 函数                             | 总计     | 每次     |
+==================================+==========+==========+
| cosf (标准库)                    | 106108   | 106      |
+----------------------------------+----------+----------+
| hpm_math_fast_cosf               | 18059    | 18       |
+----------------------------------+----------+----------+
| hpm_math_fast_cosf_linear        | 29426    | 29       |
+----------------------------------+----------+----------+
| hpm_math_fast_cosf_quadratic     | 43418    | 43       |
+----------------------------------+----------+----------+

**SinCos 函数（每 1000 次操作的时钟周期数）**

+----------------------------------+----------+----------+
| 函数                             | 总计     | 每次     |
+==================================+==========+==========+
| hpm_math_fast_sincosf_linear     | 33480    | 33       |
+----------------------------------+----------+----------+
| hpm_math_fast_sincosf_quadratic  | 47801    | 48       |
+----------------------------------+----------+----------+

**Tan 函数（每 1000 次操作的时钟周期数）**

+----------------------------------+----------+----------+
| 函数                             | 总计     | 每次     |
+==================================+==========+==========+
| tanf (标准库)                    | 144019   | 144      |
+----------------------------------+----------+----------+
| hpm_math_fast_tanf_linear        | 51416    | 51       |
+----------------------------------+----------+----------+
| hpm_math_fast_tanf_quadratic     | 65778    | 66       |
+----------------------------------+----------+----------+
| hpm_math_fast_tanf_hybrid        | 105441   | 105      |
+----------------------------------+----------+----------+

**Atan/Atan2 函数（每 1000 次操作的时钟周期数）**

+----------------------------------+----------+----------+
| 函数                             | 总计     | 每次     |
+==================================+==========+==========+
| atanf (标准库)                   | 178337   | 178      |
+----------------------------------+----------+----------+
| hpm_math_fast_atanf              | 58052    | 58       |
+----------------------------------+----------+----------+
| atan2f (标准库)                  | 218747   | 218      |
+----------------------------------+----------+----------+
| hpm_math_fast_atan2f             | 57391    | 57       |
+----------------------------------+----------+----------+

精度测试结果
------------

**Sin 精度（6,530,344 个测试点）**

+-------------------------+-----------+-----------+
| 方法                    | 最大误差  | 平均误差  |
+=========================+===========+===========+
| 无插值                  | 1.53e-03  | 4.84e-04  |
+-------------------------+-----------+-----------+
| 线性插值                | 5.36e-07  | 1.46e-07  |
+-------------------------+-----------+-----------+
| 二次插值                | 5.59e-07  | 6.41e-08  |
+-------------------------+-----------+-----------+

**Cos 精度（6,530,344 个测试点）**

+-------------------------+-----------+-----------+
| 方法                    | 最大误差  | 平均误差  |
+=========================+===========+===========+
| 无插值                  | 1.53e-03  | 4.87e-04  |
+-------------------------+-----------+-----------+
| 线性插值                | 6.56e-07  | 1.60e-07  |
+-------------------------+-----------+-----------+
| 二次插值                | 5.36e-07  | 7.61e-08  |
+-------------------------+-----------+-----------+

**Tan 精度（6,110,914 个测试点，避开奇点）**

+-------------------------+-----------+-----------+
| 方法                    | 最大误差  | 平均误差  |
+=========================+===========+===========+
| 线性插值                | 3.91e-05  | 7.53e-07  |
+-------------------------+-----------+-----------+
| 二次插值                | 3.91e-05  | 7.56e-07  |
+-------------------------+-----------+-----------+
| 混合方法                | 1.53e-05  | 6.17e-07  |
+-------------------------+-----------+-----------+

**Atan 精度（199,874 个测试点，范围 [-10, 10]）**

+-------------------------+-----------+-----------+
| 方法                    | 最大误差  | 平均误差  |
+=========================+===========+===========+
| 快速（范围归约）        | 5.01e-06  | 2.49e-07  |
+-------------------------+-----------+-----------+

**Atan2 精度（6,284 个测试点）**

+-------------------------+-----------+-----------+
| 方法                    | 最大误差  | 平均误差  |
+=========================+===========+===========+
| 快速（范围归约）        | 5.01e-06  | 3.88e-07  |
+-------------------------+-----------+-----------+

测试配置
--------

误差阈值（可通过宏配置）：

- Sin/Cos 无插值：1e-2
- Sin/Cos 线性插值：1e-4
- Sin/Cos 二次插值：1e-5
- Tan 线性：1e-3
- Tan 二次：1e-4
- Tan 混合：2e-5
- Atan/Atan2：1e-4

使用方法
--------

示例自动运行全面测试并在调试控制台显示结果，无需用户交互。

许可证
------

BSD-3-Clause