# PyPhotSystem

**Repository Path**: Photlab/pyphot-system

## Basic Information

- **Project Name**: PyPhotSystem
- **Description**: 光纤传输系统、模块仿真运算库
- **Primary Language**: Python
- **License**: MulanPubL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2024-10-30
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: eda

**Tags**: None

## README

# 🚀 PyPhotSystem 部署与开发指南

## 1. 📦 模块简介

PyPhotSystem 是一款面向光纤通信领域的仿真工具库，主要包含两大核心模块：

- **光纤传输系统仿真**：涵盖发射端、光纤、接收端全链路仿真
- **模块仿真**：提供多个独立的光通信功能模块

- 项目地址：https://gitee.com/Photlab/pyphot-system.git

---

## 2. ⚙️ 功能说明

### 2.1 核心组件

PyPhotSystem 已实现的核心仿真组件包括：

| 类别     | 组件名称                                                      |
| -------- | ------------------------------------------------------------- |
| 信号生成 | 随机二进制生成器、QAM调制器、RRC脉冲整形                      |
| 噪声模拟 | DAC量化噪声、激光器相位噪声、高斯白噪声、ADC量化噪声          |
| 信道仿真 | 双偏振光纤传输信道、收发端激光器频偏、接收机I/Q失衡           |
| 信号处理 | IQ正交化补偿、频偏估计和补偿、帧同步、自适应均衡、BPS相位恢复 |
| 性能分析 | 星座图绘制、眼图绘制、误码率计算、Q影响因子计算、信号功率计算 |
| 系统模块 | 发射机、接收机                                                |

### 2.2 扩展特性

- 支持多后端计算库：numpy / cupy / torch
- 支持 GPU 加速计算（依赖 cupy/torch GPU 版本）

---

## 3. 🧩 依赖环境

### 3.1 Python 版本要求

请确保 Python 版本 **<= 3.12**(建议3.11)：

```bash
python --version
```

### 3.2 配置国内镜像源（推荐）

加速依赖包下载，避免网络问题：

```bash
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple
pip config set install.trusted-host mirrors.aliyun.com
```

### 3.3 创建虚拟环境

避免依赖冲突，建议使用独立虚拟环境：

```bash
python -m venv .venv
```

### 3.4 激活虚拟环境

- Windows 系统：

```bash
.venv\Scripts\activate
```

- macOS / Linux 系统：

```bash
source .venv/bin/activate
```

### 3.5 升级 pip

确保 pip 为最新版本，避免安装失败：

```bash
python -m pip install --upgrade pip
```

### 3.6 安装项目依赖

激活虚拟环境后，安装全部依赖：

```bash
pip install -r requirements.txt
```

### 3.7 安装支持GPU计算 PyTorch（可选）

#### 3.7.1 CPU 版本（基础仿真）

```bash
pip install torch
```

#### 3.7.2 GPU 版本（加速计算）

需先确保显卡驱动和 CUDA 环境已正确安装：

```bash
# 官方源
pip install torch --index-url https://download.pytorch.org/whl/cu126

# 国内镜像源（推荐）
pip install torch -f https://mirrors.aliyun.com/pytorch-wheels/cu126/
```

> ⚠️ 注意：Torch 与 CUDA 版本需匹配，具体参考：  
> https://pytorch.org/get-started/previous-versions/

---

## 4. 🛠️ 开发指南

本节以开发名为 `temp` 的新组件为例，介绍完整开发流程。

### 4.1 编写组件代码

在 `phot/components/` 目录下选择对应分类文件夹，创建 `temp.py` 文件：

```python
import numpy as np  # 引入必要的依赖包

def temp(signals, arg1: int, arg2: float, **kwargs):
    """
    自定义组件功能描述（示例：信号幅度调整组件）
    :param signals: 输入复数信号数组（一维复数数组）
    :param arg1: 幅度缩放倍数（整数）
    :param arg2: 直流偏置（浮点数）
    :returns: 处理后的输出信号数组
    """
    # 示例算法实现
    output_signals = signals[0] * arg1 + arg2
    return [output_signals]

if __name__ == '__main__':
    # 组件单元测试代码
    test_signal = np.array([1+2j, 3+4j, 5+6j], dtype=np.complex128)
    result = temp([test_signal], 2, 0.5)
    print("测试结果：", result)
```

> 📌 规范要求：
>
> - 组件函数名与脚本文件名保持一致（区分大小写）
> - 必须标注参数类型和功能说明
> - 自定义算法需封装到 `phot/optical/` 目录后引入
> - 项目信号值为list包含numpy一维数组, list的长度为信号的偏振数

### 4.2 编写 TOML 配置文件

在项目根目录 `toml/` 下创建 `temp.toml` 配置文件：

```toml
[temp]                              # 组件名（与函数名一致）
is_class = false                    # 是否为类组件（false 表示函数组件）
frontend_name = "自定义Temp组件"    # 前端显示名称
description = "信号幅度调整与偏置组件" # 组件描述
is_analyzer = false                 # 是否为分析器组件（false 表示处理组件）

[temp.parameters]
[temp.parameters.arg1]
frontend_name = "幅度缩放倍数"      # 前端显示参数名
data_type = "int"                   # 参数数据类型
value = "2"                         # 参数默认值
unit = ""                           # 参数单位（无则留空）
unit_type = ""                      # 单位类型（无则留空）

[temp.parameters.arg2]
frontend_name = "直流偏置"          # 前端显示参数名
data_type = "float"                 # 参数数据类型
value = "0.5"                       # 参数默认值
unit = "V"                          # 参数单位
unit_type = "voltage"               # 单位类型

[temp.input]
signals = "输入信号"                # 输入参数前端显示名

[temp.output]
signals = "输出信号"                # 输出参数前端显示名
```

> 📌 全局参数说明：
> 若组件需使用全局参数（如符号数、采样率），需在 `toml/global_params.toml` 中添加：
>
> ```toml
> # 全局参数示例
> num_symbols = 2**16                # 符号数目
> bits_per_symbol = 3                # 调制格式
> total_baud = 40e9                  # 信号波特率
> up_sampling_factor = 4             # 上采样倍数
> sampling_rate = up_sampling_factor * total_baud  # 采样率
> reference_frequency = 193.1e12     # 参考频率
> ```

### 4.3 集成到运算库

在组件所在目录的 `__init__.py` 文件中引入新组件：

```python
# 示例：phot/components/process/__init__.py
from .temp import temp                  # 引入新开发的temp组件
from .down_sample import down_sample
from .gen_bits import gen_bits
from .Mapper_PAM_M import Mapper_PAM_M
from .modulation import modulation
from .pulse_shaper import pulse_shaper
from .re_sample import re_sample
from .up_sample import up_sample
```

### 4.4 组件测试

在项目根目录创建测试文件（如 `test_temp_component.py`）：

```python
import phot

# 构造测试信号
test_signal = np.array([1+2j, 3+4j, 5+6j], dtype=np.complex128)

# 调用新开发的组件
output_signal = phot.temp(signals=test_signal, arg1=2, arg2=0.5)

# 输出测试结果
print("输入信号：", test_signal)
print("输出信号：", output_signal)
```

运行测试：

```bash
python test_temp_component.py
```

### 4.5 联合测试

将新组件接入完整仿真链路测试，参考示例文件 `example_module_DSP.py` 编写联合测试用例，验证组件与其他模块的兼容性。

---

## 5. 🐞 调试方法

### 5.1 基础调试

直接运行项目示例文件，通过 `print` 输出中间变量：

```bash
python example*.py
```

### 5.2 断点调试

- 使用 PyCharm / VS Code 打开项目
- 在组件代码关键位置设置断点
- 以调试模式运行测试文件，逐步检查变量和执行流程

---

## 6. 📦 打包方式

将项目打包为 Wheel 安装包，便于分发和部署：

```bash
python setup.py bdist_wheel
```

打包成功后，会在项目根目录生成 `/dist` 文件夹，包含如下格式的安装包：

```
phot-*.*.*-py3-none-any.whl
```

---

## 7. 🚀 部署步骤

### 7.1 环境准备

确保目标机器已安装：

- Python 3.12+
- pip 最新版本
- 对应版本的 CUDA（如需 GPU 加速）

### 7.2 安装 Wheel 包

在 Wheel 文件所在目录执行安装命令：

```bash
pip install phot-*.*.*-py3-none-any.whl
```

参考3.7安装对应torch

### 7.3 验证部署

安装完成后，在 Python 环境中验证：

```python
import phot
# 调用任意组件验证是否安装成功
num_symbols= 2**16
bits_per_symbol = 4

signal_bits = gen_bits(num_symbols, bits_per_symbol)

print("部署验证成功，生成的随机比特数：", len(signal_bits[0])
```

---

## 8. ©️ 版权声明

本项目归 PhotLab 团队所有，仅供科研与内部使用，未经许可不得用于商业用途。

---