# pa_lib

**Repository Path**: morning-coder/pa_lib

## Basic Information

- **Project Name**: pa_lib
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 功率分析, 电能质量监, 智能电表, 变频器

## README

# pa_lib — 工业级三相功率分析算法库

> 版本 1.0.0 | C99 标准 | 平台无关 | 零外部依赖

## 简介

pa_lib 是一套面向功率分析仪/功率计的纯 C 算法库,覆盖从 ADC 码值到最终测量参数的完整计算链。

**核心特性:**

- 平台无关: 纯 C99, 不依赖任何 OS/硬件 API, 可运行于 STM32/ZYNQ/Linux/Windows
- 工业健壮: 全入参校验、除零保护、NaN 屏蔽、溢出防护
- 高精度: Kahan 补偿求和, RMS 误差 < 0.001%, 功率误差 < 0.01%
- 模块化: 12 个独立模块, 按需裁剪, 最小化耦合
- float/double 可切换: 编译时通过宏选择精度

**支持的测量参数:**

| 类别 | 参数 |
|------|------|
| 基础量 | Vrms, Irms, Vpp, Vpeak, Vdc, CF (波峰因子), FF (波形因子) |
| 功率 | P (有功), Q (无功), S (视在), PF (真功率因数), DPF (位移功率因数) |
| 频率 | 过零检测法 + FFT 抛物线插值, 精度 ±0.01Hz |
| 谐波 | 1~50 次谐波幅值/相位/功率, THD-F (IEC), THD-R (IEEE) |
| 三相 | 3P4W/3P3W(Aron) 合成, 不平衡度 (对称分量法), 相序判别 |
| 效率 | 瞬时效率 + 积分式效率 |
| 无功方法 | 几何法, 时移法, 希尔伯特变换法 (三种可选) |

## 快速上手

```c
#include "pa_lib.h"

/* 1. 准备整周期的电压/电流数据 */
pa_float_t v_data[200]; /* 200 点 = 1 周期 @10kHz/50Hz */
pa_float_t i_data[200];

/* 2. 计算 RMS */
pa_float_t v_rms;
pa_rms_calc_simple(v_data, 200, &v_rms);

/* 3. 计算功率 */
pa_float_t p, s, q, pf, phase;
pa_power_calc(v_data, i_data, 200, &p, &s, &q, &pf, &phase);
```

## 编译

```bash
# 编译 Demo 1 (单相基础测量)
gcc -std=c99 -I include -I src -o demo1 demo/demo_single_phase.c \
    src/pa_rms.c src/pa_power.c src/pa_math_util.c -lm

# 使用 double 精度
gcc -std=c99 -DPA_USE_DOUBLE -I include -I src -o demo1 ...

# 修改 FFT 最大点数
gcc -std=c99 -DPA_FFT_SIZE_MAX=4096 -I include -I src -o demo2 ...
```

## 目录结构

```
pa_lib/
├── include/          公开头文件 (用户只需 #include "pa_lib.h")
├── src/              源文件实现
├── demo/             5 个演示程序
├── test/             单元测试
└── doc/              详细文档
```

## 文档

| 文档 | 内容 |
|------|------|
| doc/00_快速入门.md | 5 分钟上手 |
| doc/01_架构设计说明.md | 分层架构、数据流、模块依赖 |
| doc/02_API参考手册.md | 全部公开 API 详细说明 |
| doc/03_算法原理详解.md | 数学推导与工程实现 |
| doc/05_校准与精度分析.md | 校准流程与误差模型 |
| doc/06_FAQ与注意事项.md | 常见陷阱与最佳实践 |

## 编码规范

- 所有公开符号以 `pa_` 前缀开头
- 函数返回 `pa_err_t`, 计算结果通过指针输出
- 禁止 malloc/free, 所有状态通过结构体传递
- 中文注释, Doxygen 风格