# ๐ cvnn-utils - A *FULL-COMPLEX* CVNN Tool Pack
> **โ is not โยฒ.**
> *A lightweight, mathematically rigorous toolkit for building truly complex-valued neural networks in PyTorch.*
[](LICENSE)
[](https://pytorch.org)
[](https://python.org)
[](https://github.com/psf/black)
---
## ๐จ The Problem: Most "Complex" NNs Are Wrong
Most so-called "complex-valued neural networks" (CVNNs) in deep learning **are not truly complex** โ they treat โ as โยฒ by splitting real/imaginary parts and processing them separately. This approach:
- โ **Breaks complex linearity**: `f(az) โ aยทf(z)` for `a โ โ`
- โ **Destroys phase equivariance**: Rotating input phase doesn't rotate output phase
- โ **Violates Wirtinger calculus**: Invalid gradients in complex domain
- โ **Ignores algebraic structure**: Treats โ as just two real numbers
> **This is like building a quantum computer that treats qubits as classical bits.**
> *You're missing the entire point of using complex numbers.*
---
## โ
The Solution: Respect โ as a Field
**cvnn-utils** provides *mathematically correct* implementations of neural network components that:
- โ
**Preserve complex linearity**: `f(az) = aยทf(z)`
- โ
**Maintain phase equivariance**: Input phase rotation โ Output phase rotation
- โ
**Use proper complex differentiation**: Valid Wirtinger gradients
- โ
**Respect โ algebraic structure**: No arbitrary โยฒ splitting
> **This is how complex-valued deep learning should be done.**
---
## ๐ฆ Key Features
### ๐น **Mathematically Sound Components**
- `ComplexStandardBatchNorm2d`: Proper complex batch norm (not covariance-based)
- `ComplexGlobalAvgPool2d`: The *only* mathematically valid complex pooling
- `ComplexModLeakyReLU`: Phase-invariant activation (|z| based)
- `ComplexConv2d` & `ComplexLinear`: Proper complex weight initialization
### ๐น **Dangerous Operation Warnings**
- โ ๏ธ Blocks ill-defined operations like `ComplexAvgPool2d` by default
- ๐ซ Explicit warnings when using `allow_inconsistencies=True`
- ๐ก Educational messages explaining *why* certain operations are problematic
### ๐น **Philosophy-Driven Design**
- **No `ComplexToReal` trap**: Forces users to make conscious design choices
- **Clear documentation**: Every class explains its mathematical properties
- **No false abstractions**: Only provides operations that respect โ structure
---
## ๐ Quick Start
### Installation
```bash
pip install git+https://github.com/KrisTHL181/cvnn-utils.git
```
### Basic Usage
```python
import cvnn_utils as cvnn
import torch
# Create a truly complex network
model = torch.nn.Sequential(
cvnn.ComplexConv2d(3, 64, 3, padding=1),
cvnn.ComplexStandardBatchNorm2d(64),
cvnn.ComplexModLeakyReLU(64),
cvnn.ComplexConv2d(64, 64, 3, stride=2, padding=1), # not pooling!
torch.nn.Flatten()
)
# Get complex output
z = model(torch.randn(16, 3, 32, 32).to(torch.complex64))
# Now decide HOW to map to real logits (your design choice):
logits = z.real @ W_r.T + z.imag @ W_i.T + b # Option 1
# OR
logits = classifier(z.abs()) # Option 2
# OR
logits = (z * w.conj()).real.sum(dim=1) # Option 3
```
### Why This Matters: Phase Equivariance Test
```python
# Test phase rotation invariance
theta = 0.785 # ฯ/4
phase = torch.exp(1j * theta)
z = torch.randn(1, 3, 32, 32, dtype=torch.complex64)
z_rotated = z * phase
output = model(z)
output_rotated = model(z_rotated)
# In a proper CVNN:
assert torch.allclose(output_rotated, output * phase, atol=1e-5)
```
---
## ๐ง Core Philosophy: โ is Not โยฒ
### The Critical Mistake
Most CVNN implementations commit this error:
```python
# WRONG: Treats complex as two real channels
real_out = F.conv2d(x.real, weight.real) - F.conv2d(x.imag, weight.imag)
imag_out = F.conv2d(x.real, weight.imag) + F.conv2d(x.imag, weight.real)
```
This **breaks complex linearity** because:
```
f(az) = f(aยท(x+iy)) โ aยทf(z) = aยท(real_out + iยทimag_out)
```
### The Correct Approach
A *true* complex operation satisfies:
```
f(az) = aยทf(z) for all a โ โ
```
Which requires:
```python
# CORRECT: Proper complex convolution
output = F.conv2d(x, weight) # PyTorch natively supports complex conv!
```
**cvnn-utils** ensures all operations respect this fundamental property.
---
## ๐ Supported Components
| Component | Status | Mathematical Properties |
| -------------------------------- | ------ | ------------------------------------------- |
| `ComplexConv2d` | โ
| โ-linear, phase equivariant |
| `ComplexLinear` | โ
| โ-linear, phase equivariant |
| `ComplexStandardBatchNorm2d` | โ
| โ-linear, phase equivariant |
| `ComplexCovarianceBatchNorm2d` | โ ๏ธ | NOT โ-linear (for non-circular data only) |
| `ComplexGlobalAvgPool2d` | โ
| Only valid complex pooling |
| `ComplexModLeakyReLU` | โ
| Phase invariant, |
| `ComplexDropout` | โ
| โ-linear variants |
| `ComplexAvgPool2d` | โ | BLOCKED by default (mathematically invalid) |
| `ComplexAdaptiveAvgPool2d` | โ | BLOCKED for output_size > 1 |
---
## โ Why This Matters: Real-World Impact
### In Signal Processing Tasks:
- **Radar/Communication**: Preserves phase information critical for direction finding
- **MRI Reconstruction**: Maintains complex coil sensitivity relationships
- **Audio Processing**: Keeps phase coherence in STFT representations
### In Computer Vision:
- **Rotation-invariant features**: Phase equivariance enables better rotation handling
- **Frequency-domain learning**: Proper complex ops are essential for FFT-based networks
- **Polar representation**: |z| (magnitude) and arg(z) (phase) have distinct meanings
> **When you break complex structure, you lose these advantages.**
---
## ๐ Documentation
Each component includes **clear documentation of its mathematical properties**:
```python
class ComplexStandardBatchNorm2d(ComplexModule):
"""
Standard Complex Batch Normalization.
Preserves:
- โ
Complex linearity (f(az) = a f(z), a โ โ)
- โ
Phase equivariance (rotation-invariant up to scale)
- โ
C-differentiability (Wirtinger sense)
Does NOT model:
- โ Non-circularity (improperness): E[z^2] โ 0
Use this as the default BN in most CVNN applications.
"""
```
---
## ๐ค Contributing
We welcome contributions that:
- Add mathematically sound complex operations
- Improve documentation with rigorous explanations
- Create tutorials demonstrating proper CVNN usage
- Develop tests verifying complex properties
**Please avoid**:
- Adding operations that treat โ as โยฒ without warning
- Creating abstractions that hide mathematical choices
- Implementing "convenience" layers that encourage bad practices
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
---
## ๐ Join the Movement
Stop pretending complex numbers are just two real numbers.
Start building neural networks that **respect the algebraic structure of โ**.
**cvnn-utils** is the first step toward *mathematically correct* complex-valued deep learning.
---
> โ is not โยฒ.
> **Respect the field.**
[](https://github.com/KrisTHL181/cvnn-utils/stargazers)
*Star this repo if you believe complex-valued deep learning deserves mathematical rigor.*
Raw data
{
"_id": null,
"home_page": "https://github.com/KrisTHL181/cvnn-utils",
"name": "cvnn-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "deep learning, complex-valued, neural network, cvnn, pytorch",
"author": "KrisTHL181",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f0/22/d8ffb028994fd83cc78ace3614601bbbb8ff7d37aab6beb8e27676a4c634/cvnn_utils-0.1.10.tar.gz",
"platform": null,
"description": "# \ud83c\udf0a cvnn-utils - A *FULL-COMPLEX* CVNN Tool Pack\n\n> **\u2102 is not \u211d\u00b2.**\n> *A lightweight, mathematically rigorous toolkit for building truly complex-valued neural networks in PyTorch.*\n\n[](LICENSE)\n[](https://pytorch.org)\n[](https://python.org)\n[](https://github.com/psf/black)\n\n---\n\n## \ud83d\udea8 The Problem: Most \"Complex\" NNs Are Wrong\n\nMost so-called \"complex-valued neural networks\" (CVNNs) in deep learning **are not truly complex** \u2014 they treat \u2102 as \u211d\u00b2 by splitting real/imaginary parts and processing them separately. This approach:\n\n- \u274c **Breaks complex linearity**: `f(az) \u2260 a\u00b7f(z)` for `a \u2208 \u2102`\n- \u274c **Destroys phase equivariance**: Rotating input phase doesn't rotate output phase\n- \u274c **Violates Wirtinger calculus**: Invalid gradients in complex domain\n- \u274c **Ignores algebraic structure**: Treats \u2102 as just two real numbers\n\n> **This is like building a quantum computer that treats qubits as classical bits.**\n> *You're missing the entire point of using complex numbers.*\n\n---\n\n## \u2705 The Solution: Respect \u2102 as a Field\n\n**cvnn-utils** provides *mathematically correct* implementations of neural network components that:\n\n- \u2705 **Preserve complex linearity**: `f(az) = a\u00b7f(z)`\n- \u2705 **Maintain phase equivariance**: Input phase rotation \u2192 Output phase rotation\n- \u2705 **Use proper complex differentiation**: Valid Wirtinger gradients\n- \u2705 **Respect \u2102 algebraic structure**: No arbitrary \u211d\u00b2 splitting\n\n> **This is how complex-valued deep learning should be done.**\n\n---\n\n## \ud83d\udce6 Key Features\n\n### \ud83d\udd39 **Mathematically Sound Components**\n\n- `ComplexStandardBatchNorm2d`: Proper complex batch norm (not covariance-based)\n- `ComplexGlobalAvgPool2d`: The *only* mathematically valid complex pooling\n- `ComplexModLeakyReLU`: Phase-invariant activation (|z| based)\n- `ComplexConv2d` & `ComplexLinear`: Proper complex weight initialization\n\n### \ud83d\udd39 **Dangerous Operation Warnings**\n\n- \u26a0\ufe0f Blocks ill-defined operations like `ComplexAvgPool2d` by default\n- \ud83d\udeab Explicit warnings when using `allow_inconsistencies=True`\n- \ud83d\udca1 Educational messages explaining *why* certain operations are problematic\n\n### \ud83d\udd39 **Philosophy-Driven Design**\n\n- **No `ComplexToReal` trap**: Forces users to make conscious design choices\n- **Clear documentation**: Every class explains its mathematical properties\n- **No false abstractions**: Only provides operations that respect \u2102 structure\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install git+https://github.com/KrisTHL181/cvnn-utils.git\n```\n\n### Basic Usage\n\n```python\nimport cvnn_utils as cvnn\nimport torch\n\n# Create a truly complex network\nmodel = torch.nn.Sequential(\n cvnn.ComplexConv2d(3, 64, 3, padding=1),\n cvnn.ComplexStandardBatchNorm2d(64),\n cvnn.ComplexModLeakyReLU(64),\n cvnn.ComplexConv2d(64, 64, 3, stride=2, padding=1), # not pooling!\n torch.nn.Flatten()\n)\n\n# Get complex output\nz = model(torch.randn(16, 3, 32, 32).to(torch.complex64))\n\n# Now decide HOW to map to real logits (your design choice):\nlogits = z.real @ W_r.T + z.imag @ W_i.T + b # Option 1\n# OR\nlogits = classifier(z.abs()) # Option 2\n# OR\nlogits = (z * w.conj()).real.sum(dim=1) # Option 3\n```\n\n### Why This Matters: Phase Equivariance Test\n\n```python\n# Test phase rotation invariance\ntheta = 0.785 # \u03c0/4\nphase = torch.exp(1j * theta)\n\nz = torch.randn(1, 3, 32, 32, dtype=torch.complex64)\nz_rotated = z * phase\n\noutput = model(z)\noutput_rotated = model(z_rotated)\n\n# In a proper CVNN:\nassert torch.allclose(output_rotated, output * phase, atol=1e-5)\n```\n\n---\n\n## \ud83e\udde0 Core Philosophy: \u2102 is Not \u211d\u00b2\n\n### The Critical Mistake\n\nMost CVNN implementations commit this error:\n\n```python\n# WRONG: Treats complex as two real channels\nreal_out = F.conv2d(x.real, weight.real) - F.conv2d(x.imag, weight.imag)\nimag_out = F.conv2d(x.real, weight.imag) + F.conv2d(x.imag, weight.real)\n```\n\nThis **breaks complex linearity** because:\n\n```\nf(az) = f(a\u00b7(x+iy)) \u2260 a\u00b7f(z) = a\u00b7(real_out + i\u00b7imag_out)\n```\n\n### The Correct Approach\n\nA *true* complex operation satisfies:\n\n```\nf(az) = a\u00b7f(z) for all a \u2208 \u2102\n```\n\nWhich requires:\n\n```python\n# CORRECT: Proper complex convolution\noutput = F.conv2d(x, weight) # PyTorch natively supports complex conv!\n```\n\n**cvnn-utils** ensures all operations respect this fundamental property.\n\n---\n\n## \ud83d\udcda Supported Components\n\n| Component | Status | Mathematical Properties |\n| -------------------------------- | ------ | ------------------------------------------- |\n| `ComplexConv2d` | \u2705 | \u2102-linear, phase equivariant |\n| `ComplexLinear` | \u2705 | \u2102-linear, phase equivariant |\n| `ComplexStandardBatchNorm2d` | \u2705 | \u2102-linear, phase equivariant |\n| `ComplexCovarianceBatchNorm2d` | \u26a0\ufe0f | NOT \u2102-linear (for non-circular data only) |\n| `ComplexGlobalAvgPool2d` | \u2705 | Only valid complex pooling |\n| `ComplexModLeakyReLU` | \u2705 | Phase invariant, |\n| `ComplexDropout` | \u2705 | \u2102-linear variants |\n| `ComplexAvgPool2d` | \u274c | BLOCKED by default (mathematically invalid) |\n| `ComplexAdaptiveAvgPool2d` | \u274c | BLOCKED for output_size > 1 |\n\n---\n\n## \u2753 Why This Matters: Real-World Impact\n\n### In Signal Processing Tasks:\n\n- **Radar/Communication**: Preserves phase information critical for direction finding\n- **MRI Reconstruction**: Maintains complex coil sensitivity relationships\n- **Audio Processing**: Keeps phase coherence in STFT representations\n\n### In Computer Vision:\n\n- **Rotation-invariant features**: Phase equivariance enables better rotation handling\n- **Frequency-domain learning**: Proper complex ops are essential for FFT-based networks\n- **Polar representation**: |z| (magnitude) and arg(z) (phase) have distinct meanings\n\n> **When you break complex structure, you lose these advantages.**\n\n---\n\n## \ud83d\udcd6 Documentation\n\nEach component includes **clear documentation of its mathematical properties**:\n\n```python\nclass ComplexStandardBatchNorm2d(ComplexModule):\n \"\"\"\n Standard Complex Batch Normalization.\n \n Preserves:\n - \u2705 Complex linearity (f(az) = a f(z), a \u2208 \u2102)\n - \u2705 Phase equivariance (rotation-invariant up to scale)\n - \u2705 C-differentiability (Wirtinger sense)\n \n Does NOT model:\n - \u274c Non-circularity (improperness): E[z^2] \u2260 0\n \n Use this as the default BN in most CVNN applications.\n \"\"\"\n```\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions that:\n\n- Add mathematically sound complex operations\n- Improve documentation with rigorous explanations\n- Create tutorials demonstrating proper CVNN usage\n- Develop tests verifying complex properties\n\n**Please avoid**:\n\n- Adding operations that treat \u2102 as \u211d\u00b2 without warning\n- Creating abstractions that hide mathematical choices\n- Implementing \"convenience\" layers that encourage bad practices\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n---\n\n\n## \ud83c\udf1f Join the Movement\n\nStop pretending complex numbers are just two real numbers.\nStart building neural networks that **respect the algebraic structure of \u2102**.\n\n**cvnn-utils** is the first step toward *mathematically correct* complex-valued deep learning.\n\n---\n\n> \u2102 is not \u211d\u00b2.\n> **Respect the field.**\n\n[](https://github.com/KrisTHL181/cvnn-utils/stargazers)\n*Star this repo if you believe complex-valued deep learning deserves mathematical rigor.*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight, principled toolkit for Complex-Valued Neural Networks in PyTorch.",
"version": "0.1.10",
"project_urls": {
"Homepage": "https://github.com/KrisTHL181/cvnn-utils"
},
"split_keywords": [
"deep learning",
" complex-valued",
" neural network",
" cvnn",
" pytorch"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e8a7b5cfd55622cca16d4fd1fe1a39a9d70025d96bf484f4660de57b80478aff",
"md5": "f90202519e1789f3df891fadd6cd4654",
"sha256": "ae7373503c234de65a5e8bbe33eafc93092d23068bc0176c31385526abc6856a"
},
"downloads": -1,
"filename": "cvnn_utils-0.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f90202519e1789f3df891fadd6cd4654",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15596,
"upload_time": "2025-08-18T20:23:23",
"upload_time_iso_8601": "2025-08-18T20:23:23.317537Z",
"url": "https://files.pythonhosted.org/packages/e8/a7/b5cfd55622cca16d4fd1fe1a39a9d70025d96bf484f4660de57b80478aff/cvnn_utils-0.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f022d8ffb028994fd83cc78ace3614601bbbb8ff7d37aab6beb8e27676a4c634",
"md5": "8e58ae827765b38b0b313d3419b2f0a8",
"sha256": "67e231859f95e10ebaf24877157f8c7d6cfa228643c35c88ff3cac3647ad344d"
},
"downloads": -1,
"filename": "cvnn_utils-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "8e58ae827765b38b0b313d3419b2f0a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17287,
"upload_time": "2025-08-18T20:23:24",
"upload_time_iso_8601": "2025-08-18T20:23:24.816290Z",
"url": "https://files.pythonhosted.org/packages/f0/22/d8ffb028994fd83cc78ace3614601bbbb8ff7d37aab6beb8e27676a4c634/cvnn_utils-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 20:23:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KrisTHL181",
"github_project": "cvnn-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cvnn-utils"
}
JSON
