Metadata-Version: 2.4
Name: kulun
Version: 1.1.0
Summary: Coulomb titration .dat data processing and scientific plotting CLI tool
Home-page: https://github.com/EricZhangpku/kulun
Author: Jiahang Zhang
Author-email: 2062605586@qq.com
Project-URL: Bug Tracker, https://github.com/EricZhangpku/kulun/issues
Project-URL: Source, https://github.com/EricZhangpku/kulun
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# `kulun` — 库仑滴定数据处理与科研绘图工具

[![PyPI version](https://img.shields.io/pypi/v/kulun)](https://pypi.org/project/kulun/)
[![Python](https://img.shields.io/pypi/pyversions/kulun)](https://pypi.org/project/kulun/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`kulun` 是一个用 Python 编写的命令行工具，专门用于提取、合并并绘制由 *北大化院定分实验教学组* 开发的库仑滴定软件所生成的 `.dat` 数据文件。该工具能够快速绘制滴定曲线及一阶导数图，并自动标注突跃点的时间间隔。

---

## 目录

- [安装](#安装)
- [快速开始](#快速开始)
- [命令详解](#命令详解)
  - [1. 提取数据 `-e`](#1-提取数据--e)
  - [2. 合并数据 `-c`](#2-合并数据--c)
  - [3. 提取 + 合并 `-ec`](#3-提取--合并--ec)
  - [4. 绘制科研图 `-p`](#4-绘制科研图--p)
  - [5. 合并 + 绘图 `-cp`](#5-合并--绘图--cp)
  - [6. 一步到位 `-ecp`](#6-一步到位--ecp)
- [常见问题](#常见问题)
- [从源码安装（开发者）](#从源码安装开发者)
- [许可证](#许可证)

---

## 安装

确保电脑上已安装 Python 3.7 或更高版本，然后在终端中运行：

```bash
pip install kulun
```

安装完成后，在终端输入以下命令验证是否成功：

```bash
kulun --version
```

如果输出了版本号（如 `kulun 1.1.0`），说明安装成功。

> *如果你是第一次接触终端*——
> - **Windows**: 按 `Win(⊞) + R`，输入 "cmd" 回车。
> - **macOS**: 按 `Command(⌘) + 空格`，搜索 "终端" 或 "Terminal" 并打开。

---

## 快速开始

下面用一个典型的数据处理流程演示 `kulun` 的用法：

```bash
# 第 1 步：将 .dat 文件提取为表格
kulun -e my_data.dat
# → 生成 my_data.csv

# 第 2 步：绘制滴定曲线和一阶导数图
kulun -p my_data.csv
# → 生成 my_data.png（300 dpi 科研插图）
```

如果你有多个 `.dat` 文件需要**顺序**拼接后再出图，可以用以下代码一行搞定：

```bash
kulun -ecp file1.dat file2.dat file3.dat
# → 提取 → 合并 → 绘图，一步完成
```

---

## 命令详解

### 1. 提取数据 `-e`

> 从库仑滴定仪导出的 `.dat` 文件中提取时间和电位两列数据，保存为 `.csv` 表格。

```bash
# 处理单个文件
kulun -e sample.dat

# 处理整个文件夹里的所有 .dat 文件
kulun -e ./data_folder/
```

| 输入 | 输出 |
|------|------|
| `sample.dat` | `sample.csv` |

---

### 2. 合并数据 `-c`

> 将多次实验的 CSV 文件按顺序拼接成一个，时间轴自动连续平移。

```bash
kulun -c part1.csv part2.csv part3.csv
```

程序会交互式询问合并后的文件名（比如输入 `combined.csv`）。

> **注意：** 文件的传入顺序很重要，请按照实验进行的先后顺序排列。

---

### 3. 提取 + 合并 `-ec`

> `-e` + `-c` 的组合方法：先提取每个 `.dat`，再合并成一个 CSV。

```bash
kulun -ec run1.dat run2.dat run3.dat
```

> **注意：** 此模式下**不支持传入文件夹**，请逐个指定 `.dat` 文件。

---

### 4. 绘制科研图 `-p`

> 对 CSV 数据绘图，自动识别平行滴定曲线、计算一阶导数、标注突跃点时间。

```bash
kulun -p data.csv
```

**输出图片包含：**
- 蓝色曲线：原始数据 & Savitzky-Golay 平滑曲线
- 红色曲线：一阶导数 d*E*/d*t*
- 红色三角：突跃点（导数极值点）
- 灰色虚线：突跃点在时间轴上的投影
- 图片底部：每条平行曲线的突跃时间间隔

---

### 5. 合并 + 绘图 `-cp`

> `-c` + `-p` 的组合方法：合并多个 CSV，再绘制合并后的总图。

```bash
kulun -cp part1.csv part2.csv part3.csv
```

---

### 6. 一步到位 `-ecp`

> `kulun` 一步到位的命令：把原始 `.dat` 文件直接变成科研插图。

```bash
kulun -ecp run1.dat run2.dat run3.dat
```

等价于手动执行：

```bash
# -ecp 内部自动完成以下三步：
kulun -ec run1.dat run2.dat run3.dat   # 提取 + 合并
kulun -p combined.csv                  # 绘图
```

---

## 常见问题

### Q: 安装时报错 `pip: command not found`

说明电脑上还没有 Python。请先去 [python.org](https://www.python.org/downloads/) 下载安装 Python（安装时勾选 "Add Python to PATH"），然后再运行 `pip install kulun`。

### Q: 绘图中文显示为方框

这是字体问题，`kulun` 已自动适配 Windows / macOS / Linux 的中文字体（宋体/黑体），一般不需要额外配置。如果仍有问题，请提交 [Issue](https://github.com/EricZhangpku/kulun/issues)。

### Q: 绘图时报错缺少库

`kulun` 依赖 `numpy`、`scipy`、`matplotlib`，安装时会自动带上。如果你用了虚拟环境，请确认已激活：

```bash
# 先激活虚拟环境，再安装
pip install kulun
```

### Q: 图片坐标轴数字太小或排版不美观

这是为了兼顾多条平行曲线的复杂场景而做的自动布局。如果需要定制，请提交 [Issue](https://github.com/EricZhangpku/kulun/issues) 说明具体需求。

### Q: 如何卸载

```bash
pip uninstall kulun
```

### Q: 如何更新到最新版本

```bash
pip install --upgrade kulun
```

---

## 从源码安装（开发者）

```bash
git clone https://github.com/EricZhangpku/kulun.git
cd kulun
pip install -e .
```

---

## 许可证

MIT License · [EricZhangpku](https://github.com/EricZhangpku)
