Metadata-Version: 2.4
Name: IeeeTopologyDiagrams
Version: 4.0.2
Summary: IEEE 33-Bus single-line diagram drawing primitives based on Baran.1989 (Main Version)
Author: FedRL.EV
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.5

# IeeeTopologyDiagrams

**IEEE 33-Bus single-line diagram drawing primitives** based on Baran.1989.

**IEEE 33-Bus 单线图绘图基元库**，基于 Baran.1989。

---

## Overview / 概览

This package provides reusable drawing primitives for reproducing the IEEE 33-Bus single-line diagram from:

> M. E. Baran and F. F. Wu, "Network Reconfiguration in Distribution Systems for Loss Reduction and Load Balancing," *IEEE Trans. Power Delivery*, vol. 4, no. 2, pp. 1401–1407, 1989.

本库提供可复用的绘图基元，用于复现 IEEE 33-Bus 单线图。

### Figure 2 — IEEE 33-Bus Single-Line Diagram / IEEE 33-Bus 单线图

![IEEE 33-Bus Single-Line Diagram](images/Figure%202%20-%20One%20line%20diagram%20of%20a%20small%20distribution%20system.png)

### Figure 1 — Schematic diagram of a primary circuit of a distribution system / 配电系统一次回路示意图

![Figure 1 - Schematic diagram of a primary circuit of a distribution system](drawingScripts/Figure%201%20-%20Schematic%20diagram%20of%20a%20primary%20circuit%20of%20a%20distribution%20system.png)

---

## Install / 安装

```bash
pip install IeeeTopologyDiagrams
```

---

## Quick Start / 快速开始

### Generate Figure 2 (Full IEEE 33-Bus Diagram) / 生成 Figure 2（完整 IEEE 33-Bus 单线图）

```bash
IeeeTopologyDiagrams-fig2
```

```python
from IeeeTopologyDiagrams.reproduce_fig2 import draw_ieee33bus_diagram
draw_ieee33bus_diagram()
draw_ieee33bus_diagram('my_diagram.png')   # custom path / 自定义路径
```

### Generate Figure 1 (SS1 + Switches) / 生成 Figure 1（SS1 + 开关）

```bash
IeeeTopologyDiagrams-fig1
```

```python
from IeeeTopologyDiagrams.reproduce_fig1 import draw_ss1_switches_diagram
draw_ss1_switches_diagram()
```

---

## Python API

```python
from IeeeTopologyDiagrams import (
    draw_switch,                  # horizontal closed switch / 水平闭合开关
    draw_switch_vertical,         # vertical closed switch / 垂直闭合开关
    draw_switch_open,             # horizontal open switch / 水平断开开关
    draw_switch_open_vertical,    # vertical open switch / 垂直断开开关
    draw_bar_node,                # vertical bus bar node / 竖形母线节点
    draw_bar_node_switched,       # horizontal node + switch module / 横形节点 + 开关模块
    draw_node,                    # load node / 负荷节点
    draw_tf_node,                 # transformer node / 配变节点
    draw_substation_vertical,     # vertical substation (SS1) / 垂直变电站
    draw_substation_horizontal,   # horizontal substation (SS2) / 水平变电站
    draw_solid_node,              # solid circle node / 实心圆点节点
)
```

---

## CLI / 命令行

### Figure generation / 图生成

| Command / 命令 | Output / 输出 |
|---------------|---------------|
| `IeeeTopologyDiagrams-fig2` | Full Fig.2 IEEE 33-Bus single-line diagram / 完整 Fig.2 单线图 |
| `IeeeTopologyDiagrams-fig1` | Fig.1 SS1 + closed switches + solid nodes / Fig.1 SS1 + 闭合开关 + 实心节点 |

### Element export / 独立元素导出

| Command / 命令 | Output / 输出 | Element / 元素 |
|---------------|---------------|----------------|
| `IeeeTopologyDiagrams-switch` | `switch_symbol.png` | Horizontal closed switch / 水平闭合开关 |
| `IeeeTopologyDiagrams-switch-vertical` | `switch_vertical.png` | Vertical closed switch / 垂直闭合开关 |
| `IeeeTopologyDiagrams-switch-open-h` | `switch_open_h.png` | Horizontal open switch / 水平断开开关 |
| `IeeeTopologyDiagrams-switch-open-v` | `switch_open_v.png` | Vertical open switch / 垂直断开开关 |
| `IeeeTopologyDiagrams-bar-node-short` | `bar_node_short.png` | Vertical bus bar node / 竖形母线节点 |
| `IeeeTopologyDiagrams-bar-node-horizontal` | `bar_node_horizontal.png` | Horizontal bus bar node / 横形母线节点 |
| `IeeeTopologyDiagrams-node15` | `node15.png` | Node 15 module / 节点15模块 |
| `IeeeTopologyDiagrams-load-node` | `load_node.png` | Load node / 负荷节点 |
| `IeeeTopologyDiagrams-tf-node` | `tf_node.png` | Transformer node / 配变节点 |
| `IeeeTopologyDiagrams-ss1` | `ss1_symbol.png` | SS1 vertical substation / SS1 垂直变电站 |
| `IeeeTopologyDiagrams-ss2` | `ss2_symbol.png` | SS2 horizontal substation / SS2 水平变电站 |
| `IeeeTopologyDiagrams-solid-node` | `solid_node.png` | Solid circle node / 实心圆点节点 |

---

## Standalone Scripts / 独立脚本

All `save_*.py` in `drawingScripts/` can be run directly to export individual element PNGs.  
`drawingScripts/` 下所有 `save_*.py` 均可直接运行，输出对应的独立元素 PNG。

```bash
cd v4/drawingScripts/
python save_switch_symbol.py          # Horizontal closed switch / 水平闭合开关
python save_switch_vertical.py        # Vertical closed switch / 垂直闭合开关
python save_switch_open_h.py          # Horizontal open switch / 水平断开开关
python save_switch_open_v.py          # Vertical open switch / 垂直断开开关
python save_bar_node_short.py         # Vertical bus bar node / 竖形母线节点
python save_bar_node_horizontal.py    # Horizontal bus bar node / 横形母线节点
python save_node15.py                 # Node 15 module / 节点15模块
python save_load_node.py              # Load node / 负荷节点
python save_tf_node.py                # Transformer node / 配变节点
python save_ss1_symbol.py             # SS1 vertical substation / SS1 垂直变电站
python save_ss2_symbol.py             # SS2 horizontal substation / SS2 水平变电站
python save_solid_node.py             # Solid circle node / 实心圆点节点
python reproduce_fig1.py              # Fig.1: SS1 + closed switches + solid nodes
python reproduce_fig2.py              # Fig.2: Full IEEE 33-Bus single-line diagram
```

---

## Element Reference / 元素对照表

| Element / 元素 | PNG | CLI | Script / 脚本 |
|---------------|-----|-----|---------------|
| Horizontal closed switch / 水平闭合开关 | `switch_symbol.png` | `...-switch` | `save_switch_symbol.py` |
| Vertical closed switch / 垂直闭合开关 | `switch_vertical.png` | `...-switch-vertical` | `save_switch_vertical.py` |
| Horizontal open switch / 水平断开开关 | `switch_open_h.png` | `...-switch-open-h` | `save_switch_open_h.py` |
| Vertical open switch / 垂直断开开关 | `switch_open_v.png` | `...-switch-open-v` | `save_switch_open_v.py` |
| Vertical bus bar node / 竖形母线节点 | `bar_node_short.png` | `...-bar-node-short` | `save_bar_node_short.py` |
| Horizontal bus bar node / 横形母线节点 | `bar_node_horizontal.png` | `...-bar-node-horizontal` | `save_bar_node_horizontal.py` |
| Node 15 module / 节点15模块 | `node15.png` | `...-node15` | `save_node15.py` |
| Load node / 负荷节点 | `load_node.png` | `...-load-node` | `save_load_node.py` |
| Transformer node / 配变节点 | `tf_node.png` | `...-tf-node` | `save_tf_node.py` |
| SS1 vertical substation / SS1 垂直变电站 | `ss1_symbol.png` | `...-ss1` | `save_ss1_symbol.py` |
| SS2 horizontal substation / SS2 水平变电站 | `ss2_symbol.png` | `...-ss2` | `save_ss2_symbol.py` |
| Solid circle node / 实心圆点节点 | `solid_node.png` | `...-solid-node` | `save_solid_node.py` |
| Fig.1: SS1 + switches + solid nodes | `Figure 1 - ...png` | `...-fig1` | `reproduce_fig1.py` |
| Fig.2: Full IEEE 33-Bus diagram / 完整单线图 | `Figure 2 - ...png` | `...-fig2` | `reproduce_fig2.py` |

---

## Package Structure / 包结构

```
v4/
├── pyproject.toml
├── README.md                       # Bilingual (EN/CN) / 中英双语
├── IeeeTopologyDiagrams/           # Core library / 核心库
│   ├── __init__.py
│   ├── drawing_elements.py         # All drawing primitives / 所有绘图基元
│   ├── coordinates.py              # IEEE 33-Bus coordinates / 坐标常量
│   ├── cli.py                      # CLI entry points / CLI 入口
│   ├── reproduce_fig1.py           # Fig.1 drawing script
│   └── reproduce_fig2.py           # Fig.2 drawing script
├── drawingScripts/                 # Standalone save scripts / 独立保存脚本
│   ├── save_*.py                   # (13 save scripts + 2 reproduce scripts)
│   └── *.png                       # Element output images / 元素输出图片
└── images/                         # Additional images / 额外图片
```

---

## License / 许可证

MIT
