# comtradeOfPython

**Repository Path**: zhangsonggui/comtradeOfPython

## Basic Information

- **Project Name**: comtradeOfPython
- **Description**: 本项目是采用python解析comtrade文件，可实现CFG、DAT、DMF文件的解析和数值计算功能。暂未对2017版本中的CFF格式文件进行解析，后续会进行补充。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 3
- **Created**: 2024-03-23
- **Last Updated**: 2025-12-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 电力数据

## README

# py3comtrade

[![PyPI version](https://img.shields.io/pypi/v/py3comtrade)](https://pypi.org/project/py3comtrade/)
[![License](https://img.shields.io/pypi/l/py3comtrade)](https://pypi.org/project/py3comtrade/)

## 一、项目介绍

py3comtrade 是一个使用 Python 解析 COMTRADE 文件的工具库，支持 CFG、DAT、DMF 文件的解析、数值计算和格式转换功能。COMTRADE（Common Format for Transient Data Exchange）是电力系统暂态数据交换的通用格式标准。

当前支持的功能：
- COMTRADE 文件解析（CFG/DAT/DMF）
- 模拟量与开关量通道数据处理
- 傅里叶变换与电气量计算
- 数据格式转换（CSV/Excel/JSON）
- 故障时刻分析与阻抗计算

> ⚠️ 注意：暂未支持 2017 版本的 CFF 格式文件，后续将逐步完善。

## 二、模块概览

| 模块 | 功能说明 |
|------|----------|
| `model` | COMTRADE 数据模型定义，包含配置、通道、采样等核心对象 |
| `reader` | 文件读取模块，支持 CFG/DAT/DMF 文件解析 |
| `computation` | 数值计算模块，提供傅里叶变换、阻抗计算、序分量分析等功能 |
| `utils` | 工具模块，包含文件处理、编码转换、数据保存等实用工具 |

## 三、安装与使用

### 1. 环境要求

- Python 3.10 或更高版本（推荐使用 3.12）
- 支持 Linux/macOS/Windows

### 2. 安装方式

使用 `uv` 安装（推荐）：
```bash
uv add py3comtrade
```

使用 `pip` 安装：
```bash
pip install py3comtrade
```

### 3. 快速开始

```python
from py3comtrade.reader.comtrade_reader import comtrade_reader

# 指定 COMTRADE 文件路径
comtrade_file_path = "example.cfg"

# 读取 COMTRADE 文件
record = comtrade_reader(comtrade_file_path)

# 获取变电站名称
print(record.header.station_name)

# 获取第一个模拟量通道对象
analog = record.get_channel_obj(1, "ANALOG", "CFGAN")

# 获取该通道的瞬时值数据
instant_data = record.get_channel_instant_data_range(1, "CFGAN", "ANALOG")
```

### 4. 核心功能示例

#### 数据解析
- 支持读取 CFG/DAT/DMF 文件
- 可提取通道信息、采样率、故障时间等元数据

#### 数值计算
```python
from py3comtrade.computation.fourier import compute_dft_component

# 对数据进行傅里叶变换
values = [0.0, 1.0, 0.0, -1.0]  # 示例数据
fundamental = compute_dft_component(values, k=1)
print(f"基波分量: {fundamental}")
```

#### 数据导出
```python
# 导出为 CSV 文件
record.to_csv("output.csv")

# 导出为 Excel 文件
record.to_excel("output.xlsx")
```

## 四、开发与贡献

### 1. 本地开发环境搭建

```bash
# 安装 uv（如未安装）
pip install uv

# 克隆项目
git clone https://gitee.com/zhangsonggui/comtradeOfPython.git

# 创建虚拟环境并安装依赖
cd comtradeOfPython
uv venv
uv pip install -e .
```

### 2. 贡献代码

1. Fork 本仓库
2. 创建 `Feat_xxx` 分支
3. 提交代码变更
4. 提交 Pull Request

## 五、许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

## 六、相关资源

- GitHub 仓库: https://github.com/zhangsonggui/comtradeOfPython
- Gitee 仓库: https://gitee.com/zhangsonggui/comtradeOfPython

---

如有问题或建议，欢迎提交 Issue 或联系项目维护者。