Metadata-Version: 2.4
Name: IeeeTopologyDiagrams
Version: 4.0.3
Summary: IEEE 33-Bus single-line diagram drawing primitives based on Baran.1989 (Main Version)
Author: 黎湛联 (Zhanlian Li)
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

**Author: 黎湛联 (Zhanlian Li)**

**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 / 配电系统一次回路示意图（主图 / Main）

![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)

> **Figure 1 (partial)** — 半成品版本，仅含 SS1 + 两个闭合开关：`Figure 1 (partial) - SS1 with closed switches.png`
> 由 `IeeeTopologyDiagrams-fig1` / `reproduce_fig1.py` 生成。

---

## 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 — Main / 生成 Figure 1 主图（SS1 + CB/CB拓扑图 + 分支 + 馈线延伸）

```bash
IeeeTopologyDiagrams-cb1cb2
```

```python
from IeeeTopologyDiagrams.reproduce_fig_cb1_cb2 import draw_cb1_cb2_diagram
draw_cb1_cb2_diagram()
draw_cb1_cb2_diagram('my_topology.png')   # custom path / 自定义路径
```

### Generate Figure 1 — Partial / 生成 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,                  # circuit breaker closed (horizontal) / 水平常闭断路器
    draw_switch_vertical,         # circuit breaker closed (vertical) / 垂直常闭断路器
    draw_switch_open,             # circuit breaker open (horizontal) / 水平常开断路器
    draw_switch_open_vertical,    # circuit breaker open (vertical) / 垂直常开断路器
    draw_bar_node,                # vertical bus bar segment / 竖形母线分段
    draw_bar_node_switched,       # horizontal bus bar segment + switch / 横形母线分段 + 开关模块
    draw_node,                    # load node / 负荷节点
    draw_tf_node,                 # distribution transformer node / 配电变压器节点
    draw_substation_vertical,     # vertical substation (SS1) / 垂直变电站
    draw_substation_horizontal,   # horizontal substation (SS2) / 水平变电站
    draw_solid_node,              # solid dot (bus connection point) / 实心圆点（母线连接点）
    draw_feeder_extension,        # vertical feeder extension (dashed) / 垂直馈线延伸（虚线）
    draw_feeder_extension_horizontal,  # horizontal feeder extension (dashed) / 水平馈线延伸（虚线）
    draw_branch,                   # lateral branch / 配电支路
)
```

---

## CLI / 命令行

### Figure generation / 图生成

| Command / 命令 | Output / 输出 |
|---------------|---------------|
| `IeeeTopologyDiagrams-fig2` | Full Fig.2 IEEE 33-Bus single-line diagram / 完整 Fig.2 单线图 |
| `IeeeTopologyDiagrams-cb1cb2` | **Fig.1 Main** — SS1 + CB topology with branches & feeder extensions / **Fig.1 主图**— SS1+CB拓扑图含分支与馈线延伸 |
| `IeeeTopologyDiagrams-fig1` | **Fig.1 Partial** — SS1 + two closed switches only / **Fig.1 半成品**— 仅 SS1 + 两个闭合开关 |

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

| Command / 命令 | Output / 输出 | Element / 元素 |
|---------------|---------------|----------------|
| `IeeeTopologyDiagrams-switch` | `switch_symbol.png` | Circuit breaker closed (horizontal) / 水平常闭断路器 |
| `IeeeTopologyDiagrams-switch-vertical` | `switch_vertical.png` | Circuit breaker closed (vertical) / 垂直常闭断路器 |
| `IeeeTopologyDiagrams-switch-open-h` | `switch_open_h.png` | Circuit breaker open (horizontal) / 水平常开断路器 |
| `IeeeTopologyDiagrams-switch-open-v` | `switch_open_v.png` | Circuit breaker open (vertical) / 垂直常开断路器 |
| `IeeeTopologyDiagrams-bar-node-short` | `bar_node_short.png` | Vertical bus bar segment / 竖形母线分段 |
| `IeeeTopologyDiagrams-bar-node-horizontal` | `bar_node_horizontal.png` | Horizontal bus bar segment / 横形母线分段 |
| `IeeeTopologyDiagrams-node15` | `node15.png` | Node 15 module / 节点15模块 |
| `IeeeTopologyDiagrams-load-node` | `load_node.png` | Load node / 负荷节点 |
| `IeeeTopologyDiagrams-tf-node` | `tf_node.png` | Distribution 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 dot (bus connection point) / 实心圆点（母线连接点） |
| `IeeeTopologyDiagrams-branch` | `branch.png` | Lateral branch / 配电支路 |

---

## 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          # Circuit breaker closed (horizontal) / 水平常闭断路器
python save_switch_vertical.py        # Circuit breaker closed (vertical) / 垂直常闭断路器
python save_switch_open_h.py          # Circuit breaker open (horizontal) / 水平常开断路器
python save_switch_open_v.py          # Circuit breaker open (vertical) / 垂直常开断路器
python save_bar_node_short.py         # Vertical bus bar segment / 竖形母线分段
python save_bar_node_horizontal.py    # Horizontal bus bar segment / 横形母线分段
python save_node15.py                 # Node 15 module / 节点15模块
python save_load_node.py              # Load node / 负荷节点
python save_tf_node.py                # Distribution 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 dot (bus connection point) / 实心圆点（母线连接点）
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 / 脚本 |
|---------------|-----|-----|---------------|
| Circuit breaker closed (horizontal) / 水平常闭断路器 | `switch_symbol.png` | `...-switch` | `save_switch_symbol.py` |
| Circuit breaker closed (vertical) / 垂直常闭断路器 | `switch_vertical.png` | `...-switch-vertical` | `save_switch_vertical.py` |
| Circuit breaker open (horizontal) / 水平常开断路器 | `switch_open_h.png` | `...-switch-open-h` | `save_switch_open_h.py` |
| Circuit breaker open (vertical) / 垂直常开断路器 | `switch_open_v.png` | `...-switch-open-v` | `save_switch_open_v.py` |
| Vertical bus bar segment / 竖形母线分段 | `bar_node_short.png` | `...-bar-node-short` | `save_bar_node_short.py` |
| Horizontal bus bar segment / 横形母线分段 | `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` |
| Distribution 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 dot (bus connection point) / 实心圆点（母线连接点） | `solid_node.png` | `...-solid-node` | `save_solid_node.py` |
| Vertical feeder extension / 垂直馈线延伸 | — | — | `draw_feeder_extension()` |
| Horizontal feeder extension / 水平馈线延伸 | — | — | `draw_feeder_extension_horizontal()` |
| Lateral branch / 配电支路 | `branch.png` | `...-branch` | `draw_branch()` |
| **Fig.1 Main: SS1 + CB topology** / **Fig.1 主图**：SS1+CB拓扑图（含分支与馈线延伸） | `Figure 1 - ...png` | `...-cb1cb2` | `reproduce_fig_cb1_cb2.py` |
| **Fig.1 Partial: SS1 + switches only** / **Fig.1 半成品**：仅 SS1 + 两个闭合开关 | `Figure 1 (partial) - ...png` | `...-fig1` | `reproduce_fig1.py` |
| Fig.2: Full IEEE 33-Bus diagram / 完整单线图 | `Figure 2 - ...png` | `...-fig2` | `reproduce_fig2.py` |

---

## Package Structure / 包结构

```
v4.0.3/
├── 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_fig_cb1_cb2.py    # Fig.CB1CB2 drawing script (SS1 + CB1-5)
│   └── reproduce_fig2.py           # Fig.2 drawing script
├── drawingScripts/                 # Standalone save scripts / 独立保存脚本
│   ├── save_*.py                   # (14 save scripts + 3 reproduce scripts)
│   └── *.png                       # Element output images / 元素输出图片
└── images/                         # Additional images / 额外图片
```

---

## License / 许可证

MIT
