torch-complex

library0.4.4pypiunverified

torch-complex is a Python library that provides a custom `ComplexTensor` class and related functional operations for PyTorch. It serves as a temporal solution to enable complex-valued tensor computations in PyTorch, developed primarily because PyTorch historically lacked comprehensive native support for complex tensors. The project's stated goal is to be superseded and eventually 'thrown away' once PyTorch's native complex tensor capabilities are fully mature and performant. The current version is 0.4.4, with a focused release cadence driven by specific needs for complex tensor operations.

ai-ml

pip install torch-complex

INSTALL

IMPORT

SIG · TORCH-COMPLEX

torch-complex

ai-mlenv0.4.4

Install

3.7s avg

Import

—

Disk

90MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.000s · 90.2MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.7s · import 0.000s · 86MB

90MB installed

● package 90MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ComplexTensor

✓ from torch_complex.tensor import ComplexTensor

functional (as F)

✓ import torch_complex.functional as F

✗ import torch_complex.nn as nn

This library does not provide an `nn` module like some other complex PyTorch wrappers; it focuses on `ComplexTensor` and `functional` operations.

This quickstart demonstrates how to create a `ComplexTensor` from NumPy arrays, perform basic arithmetic and functional operations (like matrix multiplication), and move the tensor to a CUDA device if available.

import numpy as np import torch from torch_complex.tensor import ComplexTensor import torch_complex.functional as F # Create ComplexTensor from real and imaginary parts real_part = np.random.randn(3, 10, 10) imag_part = np.random.randn(3, 10, 10) x = ComplexTensor(real_part, imag_part) # Perform basic mathematical operations y = x + x z = F.matmul(x, x) # Equivalent to x @ x w = x.conj() print(f"Original ComplexTensor shape: {x.shape}") print(f"Result of addition (y) shape: {y.shape}") print(f"Result of matrix multiplication (z) shape: {z.shape}") print(f"Conjugate (w) shape: {w.shape}") # Move to CUDA if available if torch.cuda.is_available(): x_cuda = x.cuda() print(f"ComplexTensor moved to CUDA: {x_cuda.device}") else: print("CUDA not available, running on CPU.")

Debug

Known issues

breakingThis library is explicitly a 'temporal' solution and its maintainer intends to 'throw away' the project once native PyTorch ComplexTensor support is fully developed. Users should plan to migrate to native PyTorch complex dtypes (torch.complex64, torch.complex128) in the long term, as native support is now stable and actively maintained.

fix

Monitor PyTorch's native complex tensor development (docs.pytorch.org/docs/stable/complex_numbers.html) and refactor code to use `torch.complex`, `torch.view_as_complex`, etc., as native support matures and covers all required operations.

affects: All versions

gotchaOperations in `torch-complex` are implemented in Python by combining real-valued tensor computations, which can be significantly slower than native C++/CUDA optimized PyTorch operations. This library prioritizes functionality over raw performance.

fix

For performance-critical applications, benchmark `torch-complex` operations against equivalent native PyTorch complex tensor operations (if available for your use case). If native PyTorch meets your needs, prefer it for speed.

affects: All versions

gotchaThis library requires PyTorch >= 1.0. Older versions of PyTorch might not have adequate underlying support for some of the real tensor operations used by `torch-complex`.

fix

Ensure your PyTorch installation is version 1.0 or newer. `pip install torch>=1.0`.

affects: < 1.0

gotchaThere are several similarly named, but distinct, Python packages for complex numbers in PyTorch (e.g., `complexPyTorch`, `pytorch-complex`, `complextorch`). Each may have different `ComplexTensor` implementations and import paths.

fix

Carefully verify that you are importing from `torch_complex.tensor` for `ComplexTensor` and `torch_complex.functional` when using this specific library. Avoid mixing imports or assuming compatibility between different complex tensor libraries.

affects: All versions

Errors

Common errors & fixes

TypeError: 'ComplexTensor' object is not callable

Attempting to call `ComplexTensor` as a function, e.g., `x = ComplexTensor(real_part, imag_part)()` instead of `x = ComplexTensor(real_part, imag_part)`.

fix

The `ComplexTensor` is a class that needs to be instantiated, not called as a function. Remove the extra parentheses when creating an instance.

RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!

Attempting to perform operations between a `ComplexTensor` on one device (e.g., CPU) and a `torch.Tensor` or another `ComplexTensor` on a different device (e.g., GPU).

fix

Ensure all `ComplexTensor` and `torch.Tensor` objects involved in an operation are on the same device using `.to(device)` or `.cuda()`/`.cpu()` methods. Example: `x = x.cuda()` before performing operations with other tensors on CUDA.

AttributeError: 'ComplexTensor' object has no attribute 'some_native_pytorch_method'

`torch-complex`'s `ComplexTensor` is a custom class that reimplements many `torch.Tensor` methods, but it might not cover all specialized native PyTorch tensor methods or those introduced in newer PyTorch versions.

fix

Check the `torch-complex` source or documentation to see if the desired method is implemented. If not, you might need to convert the `ComplexTensor` to its real and imaginary `torch.Tensor` components to use the native method, or consider if native PyTorch complex tensors now support your use case.

Upgrade

Version history

0.4.4latest on PyPI · released Jun 28, 2024

Audit

Dependencies

torchrequiredCore deep learning framework dependency.

numpyoptionalOften used for initial data preparation for ComplexTensor.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

No resource links recorded.