kulun 1.1.1

Coulomb titration .dat data processing and scientific plotting CLI tool

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

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

---

目录

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

---

安装

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

pip install kulun

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

kulun --version

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

如果你是第一次接触终端——

• Windows: 按 Win(⊞) + R，输入 "cmd" 回车。
• macOS: 按 Command(⌘) + 空格，搜索 "终端" 或 "Terminal" 并打开。

---

快速开始

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

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

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

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

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

---

命令详解

1. 提取数据 -e

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

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

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

输入	输出
sample.dat	sample.csv

---

2. 合并数据 -c

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

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

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

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

---

3. 提取 + 合并 -ec

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

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

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

---

4. 绘制科研图 -p

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

kulun -p data.csv

输出图片包含：

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

---

5. 合并 + 绘图 -cp

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

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

---

6. 一步到位 -ecp

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

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

等价于手动执行：

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

---

常见问题

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

说明电脑上还没有 Python。请先去 python.org 下载安装 Python（安装时勾选 "Add Python to PATH"），然后再运行 pip install kulun。

Q: 绘图中文显示为方框

这是字体问题，kulun 已自动适配 Windows / macOS / Linux 的中文字体（宋体/黑体），一般不需要额外配置。如果仍有问题，请提交 Issue。

Q: 绘图时报错缺少库

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

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

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

这是为了兼顾多条平行曲线的复杂场景而做的自动布局。如果需要定制，请提交 Issue 说明具体需求。

Q: 如何卸载

pip uninstall kulun

Q: 如何更新到最新版本

pip install --upgrade kulun

---

从源码安装（开发者）

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

---

许可证

MIT License · EricZhangpku