Metadata-Version: 2.4
Name: phyxexp
Version: 0.1.0
Summary: 用于大学物理实验数据处理的Python库，支持物理量单位管理、不确定度计算、线性拟合等
Author: Log-Dog012
License: MIT
Project-URL: Homepage, https://gitee.com/Log-Dog012/phyexp
Project-URL: Repository, https://gitee.com/Log-Dog012/phyexp
Project-URL: Documentation, https://gitee.com/Log-Dog012/phyexp-demo
Keywords: physics,experiment,uncertainty,unit,fitting
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: uncertainties
Requires-Dist: pint
Requires-Dist: matplotlib
Provides-Extra: report
Requires-Dist: pypandoc>=1.13; extra == "report"
Requires-Dist: nbclient>=0.9; extra == "report"
Requires-Dist: nbformat>=5.5; extra == "report"
Requires-Dist: cairosvg; extra == "report"
Dynamic: license-file

# 大学物理实验数据处理库

**简化物理实验数据处理，自动生成规范报告要素**


## 项目简介

这是一个专为大学物理实验设计的 Python 工具库，旨在解决实验数据处理中的痛点：
- 繁琐的单位换算与误差计算
- 粗糙的手动图表绘制与拟合
- 标准化实验报告的格式排版

通过简单的接口，你可以快速完成数据录入、误差分析、曲线拟合，并自动生成符合实验报告规范的表格、图表和计算过程，让精力更专注于实验本身而非机械操作。

我们还在[`phyexp-demo`](https://gitee.com/Log-Dog012/phyexp-demo)（独立仓库）中持续更新实验报告模板（主要是`ipynb`的`notebook`格式，对应北航物理实验课程），包括密里根油滴实验、磁场测量、弗兰克-赫兹实验等，希望能帮助大家！


## 安装

PyPI 发布名是 **`phyxexp`**（`import` 名仍为 `phyexp`，不影响任何代码）：

```bash
pip install phyxexp          # 基础功能
pip install phyxexp[report]  # 报告生成工具（nb2latex）
```

或从 Gitee 直接安装最新开发版：

```bash
pip install "phyexp @ git+https://gitee.com/Log-Dog012/phyexp.git"
```

## 快速上手

```python
from phyexp import 多次测量结果, 相对误差, SLR
```


## 核心功能

1. **物理量处理**  
   支持带单位（基于`pint`）和不确定度（基于`uncertainties`）的物理量运算（如 5.2±0.1 米 + 30 厘米 自动换算并传递误差）。

2. **数据处理与误差分析**  
   - 基础统计：均值、标准差、标准误差计算  
   - 不确定度传递：自动计算直接/间接测量量的 A 类、B 类不确定度  
   - 异常值处理：支持 3σ 原则、格拉布斯检验剔除异常数据

3. **曲线拟合与可视化**  
   - 常用拟合：线性拟合（含相关系数）、非线性拟合（指数、多项式等）  
   - 标准化图表：自动添加误差棒、拟合曲线、物理量单位标签（如“时间 t / s”）

4. **报告辅助工具**  
   - 自动生成数据表格（支持 Markdown/LaTeX 格式）  
   - **`nb2latex`**：把实验报告 notebook 一键转成可排版 LaTeX 并编译 PDF
     ```bash
     pip install phyxexp[report]   # 报告工具依赖（pypandoc/nbclient/cairosvg）
     python -m phyexp.nb2latex 实验报告.ipynb --execute --compile
     ```
     生成 `<名字>_report/`（report.tex + figures/ + build.bat）：公式用 LaTeX 渲染、
     数据表转 booktabs 表格、代码入 listings、输出图片自动提取；配合 xelatex 编译中文 PDF。
   - 导出计算过程与结论模板，贴合实验报告规范


## 发布到 PyPI

PyPI 发布名是 **`phyxexp`**（`import phyexp` 不变）。发布流程：

```bash
pip install build twine
python -m build                  # 生成 dist/ 下的 sdist + wheel
twine upload dist/*              # 需要 PyPI 账号（www.pypi.org/manage/account/token/ 生成令牌）
```

版本号在 `pyproject.toml` 的 `version` 字段，每次发布递增。


## 说明文档策略

本仓库的说明文档采用“源码注释驱动”的方式维护：

- 公开 API 的使用说明写在模块和函数的 docstring 中。
- `README.md` 只保留项目总览、安装方式、入口说明和常见用法。
- `_` 开头的内部辅助函数默认不进入正式文档，避免把实现细节暴露成对外承诺。
- 后续如果补充自动文档站点，可以直接基于这些 docstring 生成，不需要重复手写两套内容。
- 当前的生成入口是 `python tools/build_docs.py`，默认会把公开 API 导出为 `docs/api.md`。

这样做的好处是文档和代码同步更新，维护成本最低，也最适合当前这个面向课程实验的数据处理库。


## 开发计划

- 近期：完善基础误差计算与线性拟合功能  
- 中期：增加非线性拟合、自定义单位支持、LaTeX 报告生成  
- 远期：开发 GUI 界面、批量处理多组实验数据  


## 反馈与贡献

- 如有 bug 或需求，欢迎在 [Gitee 仓库](https://gitee.com/Log-Dog012/phyexp) 提交 Issues  
- 欢迎 Fork 仓库并提交 Pull Request，一起完善这个工具！
