TinyMath 头文件¶

概述¶

tiny_math.h 是 TinyMath 库的 统一入口 。只需包含这一个头文件，即可访问所有数学功能——从基本的向量运算到高级的迭代求解器和特征值分解。

它充当一个包含枢纽：无需记忆每个子模块的头文件路径，只需

#include "tiny_math.h"

一切自动就绪。

架构与依赖流¶

头文件按复杂度递增的层次组织，每一层都构建在上一层之上：

%%{init: {'themeVariables': {'fontSize': '32px'}}}%%
graph BT
    subgraph Stdlib["C 标准库"]
        STD["stdio.h / stdlib.h / string.h<br/>math.h / stdbool.h / stdint.h"]
    end

    subgraph Independent["独立基础层"]
        TOOL["tiny_toolbox.h<br/><i>FreeRTOS, ESP-IDF,<br/>时间, 日志, 堆</i>"]
        CONST["tiny_constants.h<br/><i>π, √2, 位操作宏</i>"]
        ERR["tiny_error_type.h<br/><i>错误码</i>"]
    end

    subgraph Config["配置中心<br/><b>每个子模块都包含它</b>"]
        CONF["tiny_math_config.h"]
    end

    subgraph Submodules["核心子模块（各自独立）"]
        VEC["tiny_vec.h<br/><b>向量</b>"]
        LINALG["tiny_linalg.h<br/><b>线性代数</b>"]
        CFLOAT["tiny_cfloat.h<br/><b>复数</b>"]
        DECOMP["tiny_decomp.h<br/><b>分解</b>"]
        EIGEN["tiny_eigen.h<br/><b>特征值</b>"]
        MODAL["tiny_modal.h<br/><b>模态</b>"]
        ITER["tiny_iterative.h<br/><b>迭代方法</b>"]
        MAT["tiny_mat.h<br/><b>C 矩阵</b>"]
        MATCPP["tiny_matrix.hpp<br/><b>C++ Mat</b>"]
    end

    subgraph Entry["统一入口"]
        MATH["tiny_math.h<br/><b>汇总所有子模块</b>"]
    end

    subgraph Test["测试套件（由 TINY_MATH_ENABLE_TESTS 控制）"]
        TEST_VEC["test/vec/tiny_vec_test.h"]
        TEST_MAT["test/mat/tiny_mat_test.h"]
        TEST_CPP["test/mat/tiny_matrix_test.hpp"]
    end

    STD --> TOOL
    STD --> CONST
    STD --> ERR
    TOOL --> CONF
    CONST --> CONF
    ERR --> CONF

    CONF --> VEC
    CONF --> LINALG
    CONF --> CFLOAT
    CONF --> DECOMP
    CONF --> EIGEN
    CONF --> MODAL
    CONF --> ITER
    CONF --> MAT
    CONF -.->|"#ifdef __cplusplus"| MATCPP

    VEC --> MATH
    LINALG --> MATH
    CFLOAT --> MATH
    DECOMP --> MATH
    EIGEN --> MATH
    MODAL --> MATH
    ITER --> MATH
    MAT --> MATH
    MATCPP -.->|"#ifdef __cplusplus"| MATH

    VEC -.-> TEST_VEC
    MAT -.->|C| TEST_MAT
    MATCPP -.->|"C++"| TEST_CPP

    style CONF fill:#eef2ff,stroke:#4f6af5,stroke-width:2px
    style MATH fill:#eef2ff,stroke:#4f6af5
    style TOOL fill:#f8fafc,stroke:#94a3b8
    style CONST fill:#f8fafc,stroke:#94a3b8
    style ERR fill:#f8fafc,stroke:#94a3b8
    style VEC fill:#f8fafc,stroke:#94a3b8
    style LINALG fill:#f8fafc,stroke:#94a3b8
    style CFLOAT fill:#f8fafc,stroke:#94a3b8
    style DECOMP fill:#f8fafc,stroke:#94a3b8
    style EIGEN fill:#f8fafc,stroke:#94a3b8
    style MODAL fill:#f8fafc,stroke:#94a3b8
    style ITER fill:#f8fafc,stroke:#94a3b8
    style MAT fill:#f8fafc,stroke:#94a3b8
    style MATCPP fill:#f8fafc,stroke:#94a3b8

包含顺序

子模块按 计算复杂度递增 排列：vec → linalg → cfloat → decomp → eigen/modal → iterative → mat/matrix。这既是推荐的学习路径，也反映了真实的依赖关系。

子模块参考¶

子模块	头文件	功能描述	文档
向量	`tiny_vec.h`	一维向量算术：加、减、乘、除、开方、点积（支持 stride）	API → · 代码 →
线性代数	`tiny_linalg.h`	二维矩阵逐元素运算：加、减、乘、转置、范数、单位矩阵、填充、对角	API → · 代码 →
复数	`tiny_cfloat.h`	`tiny_cfloat_t` 类型及运算：加、减、乘、除、绝对值、辐角、开方、对数	API → · 代码 →
矩阵分解	`tiny_decomp.h`	矩阵分解：修正 Gram-Schmidt QR、Householder QR	API → · 代码 →
特征值	`tiny_eigen.h`	2×2 闭式解、Hessenberg 约化、Francis 双移位 QR、Schur 提取	API → · 代码 →
模态分析	`tiny_modal.h`	MIMO 模态分析：极点 → 频率/阻尼、MAC、模态滤波/排序	API → · 代码 →
迭代方法	`tiny_iterative.h`	Krylov 子空间方法：Arnoldi、Lanczos、随机 SVD、线性算子接口	API → · 代码 →
C 矩阵	`tiny_mat.h`	C 接口工具：矩阵打印、分解/特征向量提取的 C 包装	API → · 代码 →
C++ Mat	`tiny_matrix.hpp`	全功能 C++ Mat 类：构造函数、运算符重载、ROI、视图、块操作（仅 C++）	API → · 代码 →

C/C++ 双路径设计¶

TinyMath 同时支持 C 和 C++ 编译模式：

// C/C++ 子模块（始终可用）
#include "tiny_vec.h"       // 纯 C
#include "tiny_linalg.h"     // 纯 C
#include "tiny_cfloat.h"     // 纯 C
#include "tiny_decomp.h"     // 纯 C
#include "tiny_eigen.h"      // 纯 C
#include "tiny_modal.h"      // 纯 C
#include "tiny_iterative.h"  // 纯 C
#include "tiny_mat.h"        // 纯 C

// 仅 C++（有条件包含）
#ifdef __cplusplus
#include "tiny_matrix.hpp"   // 需要 C++ 编译器
#endif

最后的 extern "C" 块预留用于未来扩展——确保该作用域下新增的 C 函数在 C++ 编译时获得 C 链接。

测试开关¶

测试文件默认不包含。仅在预处理器宏 TINY_MATH_ENABLE_TESTS 被定义时才激活，通常通过以下方式设置：

# 在 CMakeLists.txt 或 sdkconfig 中
add_compile_definitions(TINY_MATH_ENABLE_TESTS)

#ifdef TINY_MATH_ENABLE_TESTS
#include "test/vec/tiny_vec_test.h"   // 向量测试函数
#include "test/mat/tiny_mat_test.h"   // 矩阵 C 测试函数

#ifdef __cplusplus
#include "test/mat/tiny_matrix_test.hpp"  // 矩阵 C++ 测试函数
#endif
#endif /* TINY_MATH_ENABLE_TESTS */

为什么需要开关？

测试代码会显著增加二进制体积。在资源受限的 MCU（ESP32、STM32）上，仅在调试版本中包含测试代码。通过 TINY_MATH_ENABLE_TESTS 控制，发布版本自动排除。

源码¶

/**
 * @file tiny_math.h
 * @author SHUAIWEN CUI (SHUAIWEN001@e.ntu.edu.sg)
 * @brief This file is the header file for the tiny_math middleware.
 * @version 1.0
 * @date 2025-03-26
 * @copyright Copyright (c) 2025
 *
 */

#pragma once

/* DEPENDENCIES */

// this layer
#include "tiny_math_config.h"

/* SUBMODULES */

// vector operations
#include "tiny_vec.h"

// linalg operations (element-wise, contiguous)
#include "tiny_linalg.h"

// complex float arithmetic
#include "tiny_cfloat.h"

// matrix decompositions (QR, MGS, HQR)
#include "tiny_decomp.h"

// eigenvalue computation (Francis QR, Hessenberg)
#include "tiny_eigen.h"

// modal analysis (eigs→freq/damp, MAC)
#include "tiny_modal.h"

// iterative methods (Arnoldi, Lanczos, RSVD)
#include "tiny_iterative.h"

// matrix operations
#include "tiny_mat.h"

// advanced matrix operations
#ifdef __cplusplus

#include "tiny_matrix.hpp"

#endif

/* TEST — guarded by TINY_MATH_ENABLE_TESTS (defined in sdkconfig or build flags) */
#ifdef TINY_MATH_ENABLE_TESTS

#include "test/vec/tiny_vec_test.h"
#include "test/mat/tiny_mat_test.h"

#ifdef __cplusplus
#include "test/mat/tiny_matrix_test.hpp"
#endif

#endif /* TINY_MATH_ENABLE_TESTS */

#ifdef __cplusplus
extern "C"
{
#endif

#ifdef __cplusplus
}
#endif

代码来源

以上代码直接取自 tiny_math.h。请始终以 GitHub 上的文件为权威版本。

快速开始¶

#include "tiny_math.h"

// 直接使用任意子模块
float a[3] = {1.0f, 2.0f, 3.0f};
float b[3] = {4.0f, 5.0f, 6.0f};
float c[3];

tiny_vec_add_f32(a, b, c, 3, 1, 1, 1);
// c = {5.0f, 7.0f, 9.0f}