complexPyTorch

一个用于在 PyTorch 中使用复值神经网络的高级工具箱。

在 PyTorch 1.7 版本之前，复数张量并不受支持。complexPyTorch 的初始版本通过两个张量来表示复数张量，分别存储其实部和虚部。自 1.7 版本起，torch.complex64 类型的复数张量已被支持，但仅有限数量的操作得到支持。当前版本的 complexPyTorch 使用复数张量（因此需要 PyTorch 1.7 或更高版本），并增加了对各种操作和层的支持。

安装

pip install complexPyTorch

使用 PyTorch 的复值网络

人工神经网络主要用于处理以实数值编码的数据，例如数字化的图像或声音。在这样的系统中，使用复数张量几乎没有意义。然而，对于与物理相关的问题，特别是在处理波的传播时，使用复数是有意义的，因为当考虑复数场时，物理规律通常是线性的，因而更为简单。complexPyTorch 是一个基于 PyTorch 高级 API 的复值函数和模块的简单实现。根据 [C. Trabelsi 等人，国际学习表征会议，2018 年]，它允许以下层和函数以复数形式使用：

• Linear
• Conv2d
• ConvTranspose2d
• MaxPool2d
• AvgPool2d
• Relu (ℂRelu)
• Sigmoid
• Tanh
• Dropout2d
• BatchNorm1d（朴素方法和协方差方法）
• BatchNorm2d（朴素方法和协方差方法）
• GRU/BN-GRU Cell

引用代码

如果该代码对您的工作有所帮助，请考虑引用：

语法与用法

其语法旨在模仿 PyTorch 标准实数函数和模块的用法。名称与 nn.modules 和 nn.functional 中的相同，只是模块名以 Complex 开头，例如 ComplexRelu、ComplexMaxPool2d，而函数名则以 complex_ 开头，例如 complex_relu、complex_max_pool2d。唯一的区别在于，前向传播函数接受两个张量，分别对应实部和虚部，并同样返回两个张量。

BatchNorm

对于其他所有层，按照 [C. Trabelsi 等人，国际学习表征会议，2018 年] 的建议，可以通过使用 nn.modules 和 nn.functional 中的函数和模块以直接的方式进行计算。例如，complexFunctions 中的 complex_relu 函数，或者 complexLayers 中对应的 ComplexRelu 模块，只需分别对实部和虚部执行 ReLU 操作，并返回这两个张量即可。而 [[C. Trabelsi 等人，国际学习表征会议，2018 年]] 提出的复数 BatchNorm 则需要计算协方差矩阵的逆平方根。这一功能已在 ComplexbatchNorm1D 和 ComplexbatchNorm2D 中实现，但采用了 PyTorch 的高级 API，速度相对较慢。然而，实验表明，与仅对实部和虚部分别进行 BatchNorm 的朴素方法相比，这种方法的优势可能并不明显。朴素方法可通过 NaiveComplexbatchNorm1D 或 NaiveComplexbatchNorm2D 实现。

示例

为了说明，这里提供一个简单的复数模型示例。请注意，在这个示例中，复数并没有特别的意义，它只是为了展示如何处理复数神经网络。

import torch
import torch.nn as nn
import torch.nn.functional as F
from torchvision import datasets, transforms
from complexPyTorch.complexLayers import ComplexBatchNorm2d, ComplexConv2d, ComplexLinear
from complexPyTorch.complexFunctions import complex_relu, complex_max_pool2d

batch_size = 64
trans = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.5,), (1.0,))])
train_set = datasets.MNIST('../data', train=True, transform=trans, download=True)
test_set = datasets.MNIST('../data', train=False, transform=trans, download=True)

train_loader = torch.utils.data.DataLoader(train_set, batch_size= batch_size, shuffle=True)
test_loader = torch.utils.data.DataLoader(test_set, batch_size= batch_size, shuffle=True)

class ComplexNet(nn.Module):
    
    def __init__(self):
        super(ComplexNet, self).__init__()
        self.conv1 = ComplexConv2d(1, 10, 5, 1)
        self.bn  = ComplexBatchNorm2d(10)
        self.conv2 = ComplexConv2d(10, 20, 5, 1)
        self.fc1 = ComplexLinear(4*4*20, 500)
        self.fc2 = ComplexLinear(500, 10)
             
    def forward(self,x):
        x = self.conv1(x)
        x = complex_relu(x)
        x = complex_max_pool2d(x, 2, 2)
        x = self.bn(x)
        x = self.conv2(x)
        x = complex_relu(x)
        x = complex_max_pool2d(x, 2, 2)
        x = x.view(-1,4*4*20)
        x = self.fc1(x)
        x = complex_relu(x)
        x = self.fc2(x)
        x = x.abs()
        x =  F.log_softmax(x, dim=1)
        return x
    
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = ComplexNet().to(device)
optimizer = torch.optim.SGD(model.parameters(), lr=0.01, momentum=0.9)

def train(model, device, train_loader, optimizer, epoch):
    model.train()
    for batch_idx, (data, target) in enumerate(train_loader):
        data, target = data.to(device).type(torch.complex64), target.to(device)
        optimizer.zero_grad()
        output = model(data)
        loss = F.nll_loss(output, target)
        loss.backward()
        optimizer.step()
        if batch_idx % 100 == 0:
            print('Train Epoch: {:3} [{:6}/{:6} ({:3.0f}%)]\tLoss: {:.6f}'.format(
                epoch,
                batch_idx * len(data), 
                len(train_loader.dataset),
                100. * batch_idx / len(train_loader), 
                loss.item())
            )

# 运行 50 个 epoch 的训练
for epoch in range(50):
    train(model, device, train_loader, optimizer, epoch)

致谢

我要感谢 Piotr Bialecki 在 PyTorch 论坛上提供的宝贵帮助。

complexPyTorch 快速上手指南

环境准备

在开始使用之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：建议 Python 3.7+
• 核心依赖：PyTorch >= 1.7
  • 该工具依赖 PyTorch 原生的复数张量支持（torch.complex64），此特性仅在 PyTorch 1.7 及以上版本中可用。
• 硬件加速（可选）：如需使用 GPU 加速，请确保已安装对应版本的 cudatoolkit。

国内加速建议： 安装 PyTorch 时，推荐使用清华或中科大镜像源以提升下载速度。例如：

pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

通过 pip 直接安装 complexPyTorch：

pip install complexPyTorch

若需使用国内镜像源加速安装：

pip install complexPyTorch -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

complexPyTorch 的 API 设计高度模仿 PyTorch 原生接口。

• 模块命名：在原生模块前加 Complex 前缀（如 ComplexConv2d, ComplexRelu）。
• 函数命名：在原生函数前加 complex_ 前缀（如 complex_relu, complex_max_pool2d）。
• 数据输入：直接使用 PyTorch 原生的复数张量 (torch.complex64)。

以下是一个基于 MNIST 数据集的最小化复数神经网络示例：

import torch
import torch.nn as nn
import torch.nn.functional as F
from complexPyTorch.complexLayers import ComplexBatchNorm2d, ComplexConv2d, ComplexLinear
from complexPyTorch.complexFunctions import complex_relu, complex_max_pool2d

# 定义复数网络模型
class ComplexNet(nn.Module):
    def __init__(self):
        super(ComplexNet, self).__init__()
        # 使用复数层替换标准层
        self.conv1 = ComplexConv2d(1, 10, 5, 1)
        self.bn  = ComplexBatchNorm2d(10)
        self.conv2 = ComplexConv2d(10, 20, 5, 1)
        self.fc1 = ComplexLinear(4*4*20, 500)
        self.fc2 = ComplexLinear(500, 10)
             
    def forward(self, x):
        x = self.conv1(x)
        x = complex_relu(x)                # 使用复数激活函数
        x = complex_max_pool2d(x, 2, 2)    # 使用复数池化
        x = self.bn(x)
        x = self.conv2(x)
        x = complex_relu(x)
        x = complex_max_pool2d(x, 2, 2)
        x = x.view(-1, 4*4*20)
        x = self.fc1(x)
        x = complex_relu(x)
        x = self.fc2(x)
        # 输出前取模长并计算对数概率
        x = x.abs()
        x = F.log_softmax(x, dim=1)
        return x

# 初始化设备与模型
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = ComplexNet().to(device)
optimizer = torch.optim.SGD(model.parameters(), lr=0.01, momentum=0.9)

# 模拟一次前向传播 (假设输入为复数张量)
# 实际使用时请配合 DataLoader 加载真实数据
dummy_input = torch.randn(1, 1, 28, 28, dtype=torch.complex64).to(device)
output = model(dummy_input)
print(f"Output shape: {output.shape}")

关键点说明：

1. 数据类型：输入数据必须转换为复数类型，例如 data.type(torch.complex64)。
2. 损失计算：由于复数无法直接比较大小，通常在网络末端使用 .abs() 取模长，将其转换回实数域后再进行 log_softmax 和损失计算（如 nll_loss）。
3. 批归一化：库中提供了 ComplexBatchNorm2d（基于协方差矩阵，理论更严谨但较慢）和 NaiveComplexBatchNorm2d（分别对实部虚部做 BN，速度快，实验效果差异通常不大），可根据需求选择。