pdft 0.2.2__tar.gz → 0.2.4__tar.gz

{pdft-0.2.2 → pdft-0.2.4}/.claude/CLAUDE.md

@@ -80,8 +80,8 @@ src/pdft/
 ├── profiling.py            Cross-cutting profiling helpers
 ├── bases/
 │   ├── base.py             AbstractSparseBasis + bases_allclose + 4 basis dataclasses
-│   ├── circuit/            QFT, EntangledQFT, TEBD, MERA (full circuit topologies)
-│   └── block/              Blocked, Rich, RealRich (parameter-efficient)
+│   ├── circuit/            QFT, EntangledQFT, TEBD, MERA, Rich, RealRich + freeze_as_blocked
+│   └── block/              BlockedBasis (Rich/RealRich re-exported from circuit for back-compat)
 ├── circuit/                Einsum builder (builder.py) + JIT closure cache (cache.py)
 ├── optimizers/             core, gd (RiemannianGD + Armijo), adam (RiemannianAdam), loop
 ├── training/               schedules, single (train_basis), batched, adam_step, eval_loop

pdft-0.2.4/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: pdft
+Version: 0.2.4
+Summary: Python port of ParametricDFT.jl: learning parametric quantum Fourier transforms via manifold optimization.
+Project-URL: Homepage, https://github.com/zazabap/pdft
+Project-URL: Issues, https://github.com/zazabap/pdft/issues
+Project-URL: Upstream, https://github.com/nzy1997/ParametricDFT.jl
+Author: zazabap
+License: MIT License
+        
+        Copyright (c) 2026 zazabap
+        
+        Portions of this project are a Python port of ParametricDFT.jl
+        (https://github.com/nzy1997/ParametricDFT.jl), Copyright (c) 2025 nzy1997,
+        originally released under the MIT License.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: dft,fourier,jax,manifold-optimization,quantum,variational
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: jax>=0.10.0
+Requires-Dist: typing-extensions>=4.5
+Provides-Extra: dev
+Requires-Dist: jaxtyping>=0.2; extra == 'dev'
+Requires-Dist: matplotlib>=3.8; extra == 'dev'
+Requires-Dist: numpy>=1.26; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.6; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: jax[cuda12]>=0.10.0; extra == 'gpu'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# pdft
+
+[![arXiv](https://img.shields.io/badge/arXiv-2608.00053-b31b1b.svg)](https://arxiv.org/abs/2608.00053)
+
+A Python port of [ParametricDFT.jl](https://github.com/nzy1997/ParametricDFT.jl):
+learning parametric quantum Fourier transforms via manifold optimization. The
+package implements a variational approach that approximates the Discrete
+Fourier Transform (DFT) with parameterized quantum circuits.
+
+This is the reference implementation accompanying the paper
+[*Fast Trainable Multilinear Bases for Image Compression*](https://arxiv.org/abs/2608.00053)
+(An, Ni, Zhou, Liu, 2026).
+
+> Status: feature-complete port. All bases (QFT, entangled QFT, TEBD, MERA,
+> Rich/RealRich, DCT-IV, blocked), both Riemannian optimizers (GD + Adam),
+> training, JSON/compression I/O, and visualization are implemented, with
+> parity against the Julia reference verified by committed goldens.
+
+## Installation
+
+From PyPI (Python 3.11+):
+
+```bash
+pip install "pdft>=0.2.3"
+```
+
+> **Note:** the older `pdft==0.2.2` wheel predates `DCT4Basis` and the
+> `parametrization="u4"` option of `TEBDBasis` / `MERABasis`, so it cannot run
+> the paper's DCT-IV, TEBD-U4, or MERA-U4 configurations. If
+> `pdft.__version__` reports `0.2.2`, upgrade with `pip install -U pdft`.
+
+From source:
+
+```bash
+git clone https://github.com/zazabap/pdft.git
+cd pdft
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+Train a parametric QFT basis on a target image with Riemannian gradient
+descent:
+
+```python
+import jax
+import jax.numpy as jnp
+import pdft
+
+target = jax.random.normal(jax.random.PRNGKey(7), (4, 4)).astype(jnp.complex128)
+basis = pdft.QFTBasis(m=2, n=2)
+
+result = pdft.train_basis(
+    basis,
+    target=target,
+    loss=pdft.L1Norm(),
+    optimizer=pdft.RiemannianGD(lr=0.01),
+    steps=50,
+    seed=0,
+)
+print(result.loss_history[0], "->", result.loss_history[-1])
+```
+
+Runnable demos live in [`examples/`](examples/) (each finishes in under
+10 seconds):
+
+```bash
+python examples/basis_demo.py           # train a QFTBasis, plot the loss
+python examples/optimizer_benchmark.py  # GD vs Adam comparison
+python examples/mera_demo.py            # MERA basis training
+```
+
+## Coherence with the pixel basis
+
+Compression cares only how few coefficients a basis needs. Anything that
+recovers an image from a *subset of its pixels* — inpainting, completion,
+compressed sensing — is governed by a second quantity, and it is not sparsity:
+
+    mu(U) = N max_ij |U_ij|^2  in [1, N]
+
+`mu = 1` is maximal incoherence with the pixel basis, the best case for
+recovery from pointwise samples; `mu = N` is an atom living on one pixel,
+invisible to any sample set that misses it.
+
+Every basis here starts at `mu = 1`, and there is a structural reason it can
+stay there: if the only non-diagonal gates are one Hadamard per wire, then
+`|U_ij| = N^{-1/2}` for **every** parameter value, so `mu = 1` identically and
+`sqrt(N) U` is a complex Hadamard matrix. Training the controlled-phase gates
+arbitrarily hard, on any objective, cannot move it. Training the Hadamard /
+`U(4)` gates can and does — randomising them on a `(3, 3)` `QFTBasis` reaches
+`mu = 24.8` out of 64, and on `RichBasis`, which has no diagonal gates at all,
+`mu = 32.5`.
+
+`certify_flat_modulus` answers that before a run rather than measuring it
+after, using the same `frozen_indices` that `train_basis_batched` takes:
+
+```python
+from pdft.coherence import certify_flat_modulus, coherence, diagonal_tensor_indices
+
+basis = pdft.QFTBasis(m=3, n=3)
+coherence(basis)                      # 1.0
+
+cert = certify_flat_modulus(basis)    # nothing frozen
+print(cert.holds, cert.reason)        # False: the Hadamards are trainable
+
+frozen = cert.offending_indices       # exactly what must be held fixed
+assert certify_flat_modulus(basis, frozen_indices=frozen)
+result = pdft.train_basis_batched(basis, frozen_indices=frozen, ...)
+```
+
+Freezing gates is a real trade — it removes the freedom that `RichBasis` and
+`TEBDBasis` add for compression. The point is that the trade is now visible and
+checkable, so it can be made deliberately per task.
+
+## Background
+
+For the theory, see the paper:
+- [Fast Trainable Multilinear Bases for Image Compression](https://arxiv.org/abs/2608.00053) (arXiv:2608.00053)
+
+and the upstream notes:
+- [`note/stepbystep.pdf`](https://github.com/nzy1997/ParametricDFT.jl/blob/main/note/stepbystep.pdf)
+- [`note/main.pdf`](https://github.com/nzy1997/ParametricDFT.jl/blob/main/note/main.pdf)
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```bibtex
+@misc{an2026fast,
+  title         = {Fast Trainable Multilinear Bases for Image Compression},
+  author        = {An, Shiwen and Ni, Zhongyi and Zhou, Huanhai and Liu, Jin-Guo},
+  year          = {2026},
+  eprint        = {2608.00053},
+  archivePrefix = {arXiv},
+  primaryClass  = {eess.IV},
+  url           = {https://arxiv.org/abs/2608.00053},
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE). This project is a derivative port of
+ParametricDFT.jl (Copyright © 2025 nzy1997, MIT).

pdft-0.2.4/README.md

@@ -0,0 +1,143 @@
+# pdft
+
+[![arXiv](https://img.shields.io/badge/arXiv-2608.00053-b31b1b.svg)](https://arxiv.org/abs/2608.00053)
+
+A Python port of [ParametricDFT.jl](https://github.com/nzy1997/ParametricDFT.jl):
+learning parametric quantum Fourier transforms via manifold optimization. The
+package implements a variational approach that approximates the Discrete
+Fourier Transform (DFT) with parameterized quantum circuits.
+
+This is the reference implementation accompanying the paper
+[*Fast Trainable Multilinear Bases for Image Compression*](https://arxiv.org/abs/2608.00053)
+(An, Ni, Zhou, Liu, 2026).
+
+> Status: feature-complete port. All bases (QFT, entangled QFT, TEBD, MERA,
+> Rich/RealRich, DCT-IV, blocked), both Riemannian optimizers (GD + Adam),
+> training, JSON/compression I/O, and visualization are implemented, with
+> parity against the Julia reference verified by committed goldens.
+
+## Installation
+
+From PyPI (Python 3.11+):
+
+```bash
+pip install "pdft>=0.2.3"
+```
+
+> **Note:** the older `pdft==0.2.2` wheel predates `DCT4Basis` and the
+> `parametrization="u4"` option of `TEBDBasis` / `MERABasis`, so it cannot run
+> the paper's DCT-IV, TEBD-U4, or MERA-U4 configurations. If
+> `pdft.__version__` reports `0.2.2`, upgrade with `pip install -U pdft`.
+
+From source:
+
+```bash
+git clone https://github.com/zazabap/pdft.git
+cd pdft
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+Train a parametric QFT basis on a target image with Riemannian gradient
+descent:
+
+```python
+import jax
+import jax.numpy as jnp
+import pdft
+
+target = jax.random.normal(jax.random.PRNGKey(7), (4, 4)).astype(jnp.complex128)
+basis = pdft.QFTBasis(m=2, n=2)
+
+result = pdft.train_basis(
+    basis,
+    target=target,
+    loss=pdft.L1Norm(),
+    optimizer=pdft.RiemannianGD(lr=0.01),
+    steps=50,
+    seed=0,
+)
+print(result.loss_history[0], "->", result.loss_history[-1])
+```
+
+Runnable demos live in [`examples/`](examples/) (each finishes in under
+10 seconds):
+
+```bash
+python examples/basis_demo.py           # train a QFTBasis, plot the loss
+python examples/optimizer_benchmark.py  # GD vs Adam comparison
+python examples/mera_demo.py            # MERA basis training
+```
+
+## Coherence with the pixel basis
+
+Compression cares only how few coefficients a basis needs. Anything that
+recovers an image from a *subset of its pixels* — inpainting, completion,
+compressed sensing — is governed by a second quantity, and it is not sparsity:
+
+    mu(U) = N max_ij |U_ij|^2  in [1, N]
+
+`mu = 1` is maximal incoherence with the pixel basis, the best case for
+recovery from pointwise samples; `mu = N` is an atom living on one pixel,
+invisible to any sample set that misses it.
+
+Every basis here starts at `mu = 1`, and there is a structural reason it can
+stay there: if the only non-diagonal gates are one Hadamard per wire, then
+`|U_ij| = N^{-1/2}` for **every** parameter value, so `mu = 1` identically and
+`sqrt(N) U` is a complex Hadamard matrix. Training the controlled-phase gates
+arbitrarily hard, on any objective, cannot move it. Training the Hadamard /
+`U(4)` gates can and does — randomising them on a `(3, 3)` `QFTBasis` reaches
+`mu = 24.8` out of 64, and on `RichBasis`, which has no diagonal gates at all,
+`mu = 32.5`.
+
+`certify_flat_modulus` answers that before a run rather than measuring it
+after, using the same `frozen_indices` that `train_basis_batched` takes:
+
+```python
+from pdft.coherence import certify_flat_modulus, coherence, diagonal_tensor_indices
+
+basis = pdft.QFTBasis(m=3, n=3)
+coherence(basis)                      # 1.0
+
+cert = certify_flat_modulus(basis)    # nothing frozen
+print(cert.holds, cert.reason)        # False: the Hadamards are trainable
+
+frozen = cert.offending_indices       # exactly what must be held fixed
+assert certify_flat_modulus(basis, frozen_indices=frozen)
+result = pdft.train_basis_batched(basis, frozen_indices=frozen, ...)
+```
+
+Freezing gates is a real trade — it removes the freedom that `RichBasis` and
+`TEBDBasis` add for compression. The point is that the trade is now visible and
+checkable, so it can be made deliberately per task.
+
+## Background
+
+For the theory, see the paper:
+- [Fast Trainable Multilinear Bases for Image Compression](https://arxiv.org/abs/2608.00053) (arXiv:2608.00053)
+
+and the upstream notes:
+- [`note/stepbystep.pdf`](https://github.com/nzy1997/ParametricDFT.jl/blob/main/note/stepbystep.pdf)
+- [`note/main.pdf`](https://github.com/nzy1997/ParametricDFT.jl/blob/main/note/main.pdf)
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```bibtex
+@misc{an2026fast,
+  title         = {Fast Trainable Multilinear Bases for Image Compression},
+  author        = {An, Shiwen and Ni, Zhongyi and Zhou, Huanhai and Liu, Jin-Guo},
+  year          = {2026},
+  eprint        = {2608.00053},
+  archivePrefix = {arXiv},
+  primaryClass  = {eess.IV},
+  url           = {https://arxiv.org/abs/2608.00053},
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE). This project is a derivative port of
+ParametricDFT.jl (Copyright © 2025 nzy1997, MIT).

{pdft-0.2.2 → pdft-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pdft"
-version = "0.2.2"
+version = "0.2.4"
 description = "Python port of ParametricDFT.jl: learning parametric quantum Fourier transforms via manifold optimization."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,7 +30,7 @@ dependencies = [
 dev = [
     "pytest>=7",
     "pytest-cov>=4",
-    "ruff>=0.5",
+    "ruff>=0.6,<0.17",
     "numpy>=1.26",
     "jaxtyping>=0.2",
     "matplotlib>=3.8",
@@ -50,6 +50,29 @@ packages = ["src/pdft"]
 line-length = 100
 target-version = "py311"
 
+[tool.ruff.lint]
+# Declared deliberately, because ruff's *default* rule set widens between
+# releases. With no `select` here and an unpinned `ruff>=0.5` in [dev], lint
+# was a property of the release calendar rather than of the repository: CI
+# went red on `main` with no source change when a newer ruff turned on rules
+# 0.5 did not have (RUF100, I001, C408, B008, ...).
+#
+# This set is pyflakes + import order + pyupgrade + comprehensions: the rules
+# that catch real defects, all of which the codebase already satisfies.
+select = ["E4", "E7", "E9", "F", "I", "UP", "C4"]
+
+# The package configures jax x64 mode before importing anything that reads it,
+# which is a module-level import after a statement by construction. This is
+# what the scattered `# noqa: E402` comments were for; ignoring the rule once
+# here is the same intent without directives that later ruff versions then
+# flag as unused.
+ignore = ["E402"]
+
+# Not enabled, but each is a reasonable thing to opt into later:
+#   "B"   -> 24 findings, almost all `zip()` without `strict=`
+#   "RUF" -> 40 findings, mostly ambiguous-unicode in maths docstrings where
+#            the multiplication sign is intended, so it needs per-site review
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-ra --strict-markers"

{pdft-0.2.2 → pdft-0.2.4}/src/pdft/__init__.py

@@ -17,6 +17,7 @@ Public API: import from subpackages directly, e.g.
     from pdft.optimizers import RiemannianGD, RiemannianAdam
     from pdft.loss import L1Norm, MSELoss
     from pdft.io import save_basis, load_basis, compress
+    from pdft.coherence import coherence, certify_flat_modulus
 
 The names re-exported at the package root below are kept only for the
 small set most commonly used in interactive sessions and notebooks.
@@ -41,14 +42,15 @@ if not _os.environ.get("PDFT_DISABLE_COMPILE_CACHE"):
     except OSError:
         pass
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 __upstream_ref__ = "nzy1997/ParametricDFT.jl@a201a27e47df2f0f3ab460f83d49b6e5f5d1e9ef"
 
 # Slim public re-export hub: most-used names only. Anything else: import
 # from the relevant subpackage directly.
-from .bases import (  # noqa: E402
+from .bases import (
     AbstractSparseBasis,
     BlockedBasis,
+    DCT4Basis,
     EntangledQFTBasis,
     MERABasis,
     QFTBasis,
@@ -56,15 +58,18 @@ from .bases import (  # noqa: E402
     RichBasis,
     TEBDBasis,
     bases_allclose,
+    freeze_as_blocked,
 )
-from .loss import AbstractLoss, L1Norm, MSELoss, loss_function  # noqa: E402
-from .optimizers import RiemannianAdam, RiemannianGD, optimize  # noqa: E402
-from .training import TrainingResult, train_basis, train_basis_batched  # noqa: E402
+from .coherence import certify_flat_modulus, coherence
+from .loss import AbstractLoss, L1Norm, MSELoss, loss_function
+from .optimizers import RiemannianAdam, RiemannianGD, optimize
+from .training import TrainingResult, train_basis, train_basis_batched
 
 __all__ = [
     "AbstractLoss",
     "AbstractSparseBasis",
     "BlockedBasis",
+    "DCT4Basis",
     "EntangledQFTBasis",
     "L1Norm",
     "MERABasis",
@@ -79,6 +84,9 @@ __all__ = [
     "__upstream_ref__",
     "__version__",
     "bases_allclose",
+    "certify_flat_modulus",
+    "coherence",
+    "freeze_as_blocked",
     "loss_function",
     "optimize",
     "train_basis",

{pdft-0.2.2 → pdft-0.2.4}/src/pdft/bases/__init__.py

@@ -3,26 +3,39 @@
 Two families:
 - bases.circuit  — full circuit topologies (QFT, EntangledQFT, TEBD, MERA),
                    comparable to FFT/DCT.
-- bases.block    — parameter-efficient block-structured bases (Blocked,
-                   Rich, RealRich) over arbitrary block partitions.
+- bases.block    — BlockedBasis over arbitrary block partitions (Rich/RealRich
+                   are re-exported here for back-compat; they live in circuit).
 
 The abstract base class and bases_allclose helper live in bases.base.
 """
 
 from .base import (
     AbstractSparseBasis,
+    DCT4Basis,
     EntangledQFTBasis,
     MERABasis,
     QFTBasis,
     TEBDBasis,
     bases_allclose,
 )
-from .block import BlockedBasis, RealRichBasis, RichBasis, fit_to_dct
-from .circuit import entangled_qft_code, ft_mat, ift_mat, mera_code, qft_code, tebd_code
+from .block import BlockedBasis
+from .circuit import (
+    RealRichBasis,
+    RichBasis,
+    entangled_qft_code,
+    fit_to_dct,
+    freeze_as_blocked,
+    ft_mat,
+    ift_mat,
+    mera_code,
+    qft_code,
+    tebd_code,
+)
 
 __all__ = [
     "AbstractSparseBasis",
     "BlockedBasis",
+    "DCT4Basis",
     "EntangledQFTBasis",
     "MERABasis",
     "QFTBasis",
@@ -32,6 +45,7 @@ __all__ = [
     "bases_allclose",
     "entangled_qft_code",
     "fit_to_dct",
+    "freeze_as_blocked",
     "ft_mat",
     "ift_mat",
     "mera_code",

{pdft-0.2.2 → pdft-0.2.4}/src/pdft/bases/base.py

@@ -291,11 +291,15 @@ class TEBDBasis:
         code: object | None = None,
         inv_code: object | None = None,
         seed: int | None = None,
+        parametrization: str = "cp",
     ):
         """When `seed` is provided AND `phases` is None, draws phases from
         `np.random.default_rng(seed).normal(0, 0.1, n_row_gates + n_col_gates)`
         — Julia's `randn(n_gates) * 0.1` convention from
         `ParametricDFT.jl/src/training.jl::_init_circuit`.
+
+        `parametrization` is "cp" (diagonal ring gates on U(1)^4) or "u4"
+        (dense two-qubit ring gates on U(4), the canonical TEBD gate).
         """
         import numpy as np
 
@@ -307,8 +311,12 @@ class TEBDBasis:
         self.n = n
         if phases is None and seed is not None:
             phases = list(np.random.default_rng(seed).normal(0.0, 0.1, m + n))
-        _code, init_tensors, self.n_row_gates, self.n_col_gates = tebd_code(m, n, phases=phases)
-        _inv_code, _, _, _ = tebd_code(m, n, phases=phases, inverse=True)
+        _code, init_tensors, self.n_row_gates, self.n_col_gates = tebd_code(
+            m, n, phases=phases, parametrization=parametrization
+        )
+        _inv_code, _, _, _ = tebd_code(
+            m, n, phases=phases, inverse=True, parametrization=parametrization
+        )
         self.tensors = list(tensors) if tensors is not None else init_tensors
         self.code = code if code is not None else _code
         self.inv_code = inv_code if inv_code is not None else _inv_code
@@ -394,11 +402,15 @@ class MERABasis:
         code: object | None = None,
         inv_code: object | None = None,
         seed: int | None = None,
+        parametrization: str = "cp",
     ):
         """When `seed` is provided AND `phases` is None, draws phases from
         `np.random.default_rng(seed).normal(0, 0.1, n_gates)` — Julia's
         `randn(n_gates) * 0.1` convention from
         `ParametricDFT.jl/src/training.jl::_init_circuit`.
+
+        `parametrization` is "cp" (diagonal disentanglers/isometries on
+        U(1)^4) or "u4" (dense two-qubit gates on U(4), the canonical form).
         """
         import numpy as np
 
@@ -412,8 +424,12 @@ class MERABasis:
             n_row = _n_mera_gates(m) if m >= 2 else 0
             n_col = _n_mera_gates(n) if n >= 2 else 0
             phases = list(np.random.default_rng(seed).normal(0.0, 0.1, n_row + n_col))
-        _code, init_tensors, self.n_row_gates, self.n_col_gates = mera_code(m, n, phases=phases)
-        _inv_code, _, _, _ = mera_code(m, n, phases=phases, inverse=True)
+        _code, init_tensors, self.n_row_gates, self.n_col_gates = mera_code(
+            m, n, phases=phases, parametrization=parametrization
+        )
+        _inv_code, _, _, _ = mera_code(
+            m, n, phases=phases, inverse=True, parametrization=parametrization
+        )
         self.tensors = list(tensors) if tensors is not None else init_tensors
         self.code = code if code is not None else _code
         self.inv_code = inv_code if inv_code is not None else _inv_code
@@ -468,3 +484,107 @@ def _mera_unflatten(aux, leaves) -> MERABasis:
 
 
 tree_util.register_pytree_node(MERABasis, _mera_flatten, _mera_unflatten)
+
+
+# ---------------------------------------------------------------------------
+# DCT4Basis
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DCT4Basis:
+    """DCT-IV tensor-network basis: the real-orthogonal, ancilla-free analogue
+    of :class:`QFTBasis`.
+
+    Mirrors QFTBasis (one tensor list; `inverse_transform` applies
+    `conj(tensors)` through `inv_code`). The gates are emitted by
+    :func:`pdft.bases.circuit.dct4.dct4_code`; at initialization the forward
+    operator is the bit-reversed orthonormal DCT-IV per dimension, and — since
+    DCT-IV is self-inverse — the basis reconstructs exactly. ``tensors`` holds
+    every gate — the affine ``R_y`` rotation layer, the branch Hadamards, the
+    mirror-``Q`` CNOT permutations and the ``Delta`` sign — each a learnable
+    leaf on its auto-selected Riemannian manifold (O(2) / O(4) / phase). The
+    gate tensors are real-valued (stored complex128, zero imaginary), so the
+    unitary manifold trains the real-orthogonal subset under a real objective:
+    exact DCT-IV at init, then relaxed, just as QFT relaxes within U.
+
+    Pytree contract:
+        leaves   = tensors
+        aux data = (m, n, len(tensors), code, inv_code)
+    """
+
+    m: int
+    n: int
+    tensors: list[Array]
+    code: object = field(compare=False, repr=False)
+    inv_code: object = field(compare=False, repr=False)
+
+    def __init__(
+        self,
+        m: int,
+        n: int,
+        tensors: Sequence[Array] | None = None,
+        code: object | None = None,
+        inv_code: object | None = None,
+        parametrization: str = "o4",
+    ):
+        if m < 1 or n < 1:
+            raise ValueError(f"m and n must be >= 1, got m={m}, n={n}")
+        from .circuit.dct4 import dct4_code
+
+        self.m = m
+        self.n = n
+        _code, init_tensors = dct4_code(m, n, parametrization=parametrization)
+        _inv_code, _ = dct4_code(m, n, inverse=True, parametrization=parametrization)
+        self.tensors = list(tensors) if tensors is not None else init_tensors
+        self.code = code if code is not None else _code
+        self.inv_code = inv_code if inv_code is not None else _inv_code
+
+    @property
+    def inv_tensors(self) -> list[Array]:
+        return self.tensors
+
+    @property
+    def image_size(self) -> tuple[int, int]:
+        return (2**self.m, 2**self.n)
+
+    @property
+    def num_parameters(self) -> int:
+        return sum(int(t.size) for t in self.tensors)
+
+    def forward_transform(self, pic: Array) -> Array:
+        from .circuit.dct4 import dct4_ft_mat
+
+        return dct4_ft_mat(self.tensors, self.code, self.m, self.n, pic)
+
+    def inverse_transform(self, pic: Array) -> Array:
+        from .circuit.dct4 import dct4_ift_mat
+
+        return dct4_ift_mat(
+            [jnp.conj(t) for t in self.tensors],
+            self.inv_code,
+            self.m,
+            self.n,
+            pic,
+        )
+
+
+def _dct4basis_flatten(b: DCT4Basis):
+    leaves = tuple(b.tensors)
+    aux = (b.m, b.n, len(b.tensors), b.code, b.inv_code)
+    return leaves, aux
+
+
+def _dct4basis_unflatten(aux, leaves) -> DCT4Basis:
+    m, n, n_fwd, code, inv_code = aux
+    assert len(leaves) == n_fwd
+    out = DCT4Basis.__new__(DCT4Basis)
+    out.m = m
+    out.n = n
+    out.tensors = list(leaves)
+    out.code = code
+    out.inv_code = inv_code
+    return out
+
+
+tree_util.register_pytree_node(DCT4Basis, _dct4basis_flatten, _dct4basis_unflatten)