{"id":14979,"library":"torch-complex","title":"Temporal PyTorch Complex Tensor Class","description":"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.","status":"maintenance","version":"0.4.4","language":"en","source_language":"en","source_url":"https://github.com/kamo-naoyuki/torch_complex","tags":["pytorch","complex numbers","deep learning","tensor","machine learning"],"install":[{"cmd":"pip install torch-complex","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core deep learning framework dependency.","package":"torch","optional":false},{"reason":"Often used for initial data preparation for ComplexTensor.","package":"numpy","optional":true}],"imports":[{"symbol":"ComplexTensor","correct":"from torch_complex.tensor import ComplexTensor"},{"note":"This library does not provide an `nn` module like some other complex PyTorch wrappers; it focuses on `ComplexTensor` and `functional` operations.","wrong":"import torch_complex.nn as nn","symbol":"functional (as F)","correct":"import torch_complex.functional as F"}],"quickstart":{"code":"import numpy as np\nimport torch\nfrom torch_complex.tensor import ComplexTensor\nimport torch_complex.functional as F\n\n# Create ComplexTensor from real and imaginary parts\nreal_part = np.random.randn(3, 10, 10)\nimag_part = np.random.randn(3, 10, 10)\nx = ComplexTensor(real_part, imag_part)\n\n# Perform basic mathematical operations\ny = x + x\nz = F.matmul(x, x) # Equivalent to x @ x\nw = x.conj()\n\nprint(f\"Original ComplexTensor shape: {x.shape}\")\nprint(f\"Result of addition (y) shape: {y.shape}\")\nprint(f\"Result of matrix multiplication (z) shape: {z.shape}\")\nprint(f\"Conjugate (w) shape: {w.shape}\")\n\n# Move to CUDA if available\nif torch.cuda.is_available():\n    x_cuda = x.cuda()\n    print(f\"ComplexTensor moved to CUDA: {x_cuda.device}\")\nelse:\n    print(\"CUDA not available, running on CPU.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"This 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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"Operations 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your PyTorch installation is version 1.0 or newer. `pip install torch>=1.0`.","message":"This 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`.","severity":"gotcha","affected_versions":"< 1.0"},{"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.","message":"There 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The `ComplexTensor` is a class that needs to be instantiated, not called as a function. Remove the extra parentheses when creating an instance.","cause":"Attempting to call `ComplexTensor` as a function, e.g., `x = ComplexTensor(real_part, imag_part)()` instead of `x = ComplexTensor(real_part, imag_part)`.","error":"TypeError: 'ComplexTensor' object is not callable"},{"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.","cause":"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).","error":"RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!"},{"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.","cause":"`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.","error":"AttributeError: 'ComplexTensor' object has no attribute 'some_native_pytorch_method'"}],"ecosystem":"pypi"}