cicuetea 1.0.0__tar.gz

cicuetea-1.0.0/.gitignore

@@ -0,0 +1,64 @@
+# macOS
+.DS_Store
+._*
+
+# Build directories (out-of-source CMake: build/, build2/, xcodeBuild/, ...)
+build*/
+*Build/
+cmake-build-*/
+
+# In-source CMake/CTest artifacts (safety net if configured at the root)
+CMakeCache.txt
+CMakeFiles/
+CMakeScripts/
+cmake_install.cmake
+CTestTestfile.cmake
+install_manifest.txt
+compile_commands.json
+CMakeLists.txt.user
+Testing/
+Makefile
+_deps/
+
+# Compiled artifacts
+*.o
+*.obj
+*.a
+*.lib
+*.so
+*.dylib
+*.dll
+*.d
+*.gch
+*.pch
+*.exe
+*.out
+*.app
+
+# Doxygen output (docs/Doxyfile is tracked; its output is not)
+docs/html/
+docs/latex/
+
+# Editors / tools
+.vscode/
+.history/
+
+# MATLAB autosaves and figure files
+*.asv
+*.m~
+*.autosave
+*.fig
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ipynb_checkpoints/
+dist/
+*.egg-info/
+
+# Local scratch (not part of the release)
+BenchTests/
+ReleaseChecklist.md

cicuetea-1.0.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: cicuetea
+Version: 1.0.0
+Summary: Real-time invertible Constant-Q Transform (CQT) engine based on nonstationary Gabor frames — Python reference implementation
+Project-URL: Homepage, https://github.com/jdsierral/CiCueTea
+Project-URL: Documentation, https://jdsierral.github.io/CiCueTea/
+Project-URL: Repository, https://github.com/jdsierral/CiCueTea
+Author: Juan Sierra
+License-Expression: MIT
+Keywords: audio,constant-q transform,cqt,dsp,nsgf,spectral processing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: demo
+Requires-Dist: matplotlib; extra == 'demo'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cicuetea
+
+Python reference implementation of **CiCueTea**, a real-time, invertible
+Constant-Q Transform (CQT) engine based on nonstationary Gabor frames (NSGF).
+
+This package is an offline, NumPy/SciPy reference — dense and sparse forward/inverse
+transforms, sparse-to-dense rasterization, and the block slicing/splicing utilities used to
+build a streaming pipeline on top of it. The real-time, allocation-free implementation lives
+in the C++ library this package accompanies.
+
+```python
+import numpy as np
+from cicuetea import NsgfCQT
+
+fs, n_samples, frac, f_min, f_max = 48000, 2**16, 1 / 48, 100, 10000
+x = np.random.randn(n_samples)
+
+cqt = NsgfCQT("dense", fs, n_samples, frac, f_min, f_max)
+X = cqt.forward(x)
+y = cqt.inverse(X)
+```
+
+Full documentation, the C++ engine, and the MATLAB reference implementation live at
+<https://github.com/jdsierral/CiCueTea>.
+
+## License
+
+MIT — see [LICENSE](https://github.com/jdsierral/CiCueTea/blob/main/LICENSE).

cicuetea-1.0.0/README.md

@@ -0,0 +1,28 @@
+# cicuetea
+
+Python reference implementation of **CiCueTea**, a real-time, invertible
+Constant-Q Transform (CQT) engine based on nonstationary Gabor frames (NSGF).
+
+This package is an offline, NumPy/SciPy reference — dense and sparse forward/inverse
+transforms, sparse-to-dense rasterization, and the block slicing/splicing utilities used to
+build a streaming pipeline on top of it. The real-time, allocation-free implementation lives
+in the C++ library this package accompanies.
+
+```python
+import numpy as np
+from cicuetea import NsgfCQT
+
+fs, n_samples, frac, f_min, f_max = 48000, 2**16, 1 / 48, 100, 10000
+x = np.random.randn(n_samples)
+
+cqt = NsgfCQT("dense", fs, n_samples, frac, f_min, f_max)
+X = cqt.forward(x)
+y = cqt.inverse(X)
+```
+
+Full documentation, the C++ engine, and the MATLAB reference implementation live at
+<https://github.com/jdsierral/CiCueTea>.
+
+## License
+
+MIT — see [LICENSE](https://github.com/jdsierral/CiCueTea/blob/main/LICENSE).

cicuetea-1.0.0/examples/Demo1.py

@@ -0,0 +1,44 @@
+import matplotlib.pyplot as plt
+import numpy as np
+import scipy.signal as sg
+import cicuetea.nsgf_cqt as NsgfCQT
+from cicuetea.slicing import *
+from psychoacoustics import *
+
+
+def dB(X):
+    return 20.0 * np.log10(np.abs(X) + 1e-10)
+
+def rms(x):
+    return np.sqrt(np.mean(np.abs(x)**2.0))
+
+fs = 48000
+nSamps = 2**18
+frac = 1.0
+fMin = 100
+fMax = 10000
+
+t = np.arange(nSamps) / fs
+x = sg.chirp(t, fMin, t[-1], fMax, 'logarithmic')
+w = sg.windows.kaiser(nSamps, 20)
+x *= w
+
+sERB = NsgfCQT.NsgfVQT('dense', fs, nSamps, freq2erb, 1/2)
+sCQT = NsgfCQT.NsgfVQT('dense', fs, nSamps, np.log2, 1/12)
+
+Xerb = sERB.forward(x)
+Xcqt = sCQT.forward(x)
+
+
+plt.figure(1)
+plt.clf()
+plt.subplot(2, 1, 1)
+plt.pcolormesh(sERB.time_axis, sERB.band_axis, dB(Xerb).T)
+plt.clim(-100, 0)
+
+plt.subplot(2, 1, 2)
+plt.pcolormesh(sCQT.time_axis, sCQT.band_axis, dB(Xcqt).T)
+plt.clim(-100, 0)
+
+
+

cicuetea-1.0.0/examples/Demo2.py

@@ -0,0 +1,85 @@
+import matplotlib.pyplot as plt
+import numpy as np
+import scipy.fft as fft
+import scipy.signal as sg
+import cicuetea.nsgf_cqt as NsgfCQT
+from cicuetea.slicing import *
+
+def pow2db(x):
+    return 10.0 * np.log10(np.abs(x))
+
+def dB(X):
+    return 20.0 * np.log10(np.abs(X) + 1e-10)
+
+def rms(x):
+    return np.sqrt(np.mean(np.abs(x)**2.0))
+
+fs = 48000
+nSamps = 2**18
+frac = 1.0
+fMin = 100
+fMax = 10000
+
+t = np.arange(nSamps) / fs
+x = sg.chirp(t, fMin, t[-1], fMax, 'logarithmic')
+w = sg.windows.kaiser(nSamps, 20)
+x *= w
+
+s1 = NsgfCQT.NsgfCQT('dense', fs, nSamps, frac)
+s2 = NsgfCQT.NsgfCQT('sparse', fs, nSamps, frac)
+
+X1 = s1.forward(x)
+X2 = s2.forward(x)
+X2 = s2.rasterize(X2)
+
+plt.figure(1)
+plt.clf()
+plt.subplot(3, 1, 1)
+plt.pcolormesh(s1.time_axis, s1.band_axis, dB(X1).T)
+plt.yscale('log')
+plt.clim(-100, 0)
+
+plt.subplot(3, 1, 2)
+plt.pcolormesh(s2.time_axis, s2.band_axis, dB(X2).T)
+plt.yscale('log')
+plt.clim(-100, 0)
+
+plt.subplot(3, 1, 3)
+plt.pcolormesh(s2.time_axis, s2.band_axis, dB(X1 - X2).T)
+plt.yscale('log')
+plt.clim(-100, 0)
+
+g1 = s1.g[:s1.n_freqs//2+1,:]
+h1 = fft.irfft(g1, s1.n_samples, 0)
+h1 = fft.ifftshift(h1, 0)
+h1 = h1 / np.max(np.abs(h1), 0)
+
+h2 = np.zeros_like(h1)
+for k in np.arange(s2.n_bands):
+    g_i = np.zeros(s2.n_samples)
+    g_i[s2.idxs[k]] = s2.g[k]
+    g_i = g_i[:s2.n_freqs//2+1]
+    h2[:,k] = fft.ifftshift(fft.irfft(g_i, s2.n_samples))
+h2 = h2 / np.max(np.abs(h2), 0)
+
+plt.figure(2)
+plt.clf()
+plt.subplot(2, 1, 1)
+plt.semilogx(s1.band_axis, pow2db(np.mean(np.abs(X1)**2.0, 0)))
+plt.semilogx(s2.band_axis, pow2db(np.mean(np.abs(X2)**2.0, 0)), "-.")
+plt.legend(["dense", "sparse"])
+
+plt.subplot(2, 1, 2)
+plt.plot(s1.time_axis, pow2db(np.mean(np.abs(X1)**2.0, 1)))
+plt.plot(s2.time_axis, pow2db(np.mean(np.abs(X2)**2.0, 1)), "-.")
+plt.legend(["dense", "sparse"])
+
+plt.figure(3)
+plt.clf()
+plt.subplot(1, 2, 1)
+plt.plot(s1.time_axis, h1 + np.arange(s1.n_bands))
+plt.xlim([-0.02, 0.02])
+
+plt.subplot(1, 2, 2)
+plt.plot(s2.time_axis, h2 + np.arange(s2.n_bands))
+plt.xlim([-0.02, 0.02])

cicuetea-1.0.0/examples/Demo3.py

@@ -0,0 +1,95 @@
+import matplotlib.pyplot as plt
+import numpy as np
+import scipy.signal as sg
+import cicuetea.nsgf_cqt as NsgfCQT
+from cicuetea.slicing import *
+
+
+def dB(X):
+    return 20.0 * np.log10(np.abs(X))
+
+def rms(x):
+    return np.sqrt(np.mean(np.abs(x)**2.0))
+
+fs = 48000
+nSamps = 2**20
+frac = 1.0
+fMin = 100
+fMax = 10000
+
+blockSize = 2**14
+overlapSize = blockSize//2
+win = np.sqrt(sg.windows.hann(blockSize, False))
+
+t = np.arange(nSamps) / fs
+x = sg.chirp(t, fMin, t[-1], fMax, 'logarithmic')
+w = sg.windows.kaiser(nSamps, 20)
+x *= w
+x[:blockSize] = 0
+x[-blockSize:] = 0
+
+sRef = NsgfCQT.NsgfCQT('dense', fs, nSamps, frac)
+XcqRef = sRef.forward(x)
+
+s = NsgfCQT.NsgfCQT('dense', fs, blockSize, frac)
+
+xBuf = slicer(x, blockSize, overlapSize)
+xBuf *= win
+XcqShort = [s.forward(xBuf[i,:]) for i in range(xBuf.shape[0])]
+XcqShort = np.stack(XcqShort, axis=0)
+XcqShort = XcqShort.transpose((0, 2, 1))
+XcqShort *= win
+Xcq = spectral_splicer(XcqShort, overlapSize)
+XcqShort_ = spectral_slicer(Xcq, blockSize, overlapSize)
+XcqShort_ *= win
+xBuf_ = [s.inverse(XcqShort_[i,:,:].T) for i in range(XcqShort_.shape[0])]
+xBuf_ = np.stack(xBuf_, axis=0)
+xBuf_ *= win
+x_ = splicer(xBuf_, overlapSize)
+
+err1 = rms(XcqRef - Xcq)
+err2 = rms(x - x_)
+
+plt.figure(1)
+plt.clf()
+plt.subplot(3, 1, 1)
+plt.plot(t, x)
+plt.xlabel("Time")
+plt.ylabel("Amplitude")
+plt.title("Original Time-domain signal")
+
+plt.subplot(3, 1, 2)
+plt.plot(t, x_)
+plt.xlabel("Time")
+plt.ylabel("Amplitude")
+plt.title("Reconstructed Time-domain signal")
+
+plt.subplot(3, 1, 3)
+plt.plot(t, x - x_)
+plt.tight_layout()
+plt.xlabel("Time")
+plt.ylabel("Amplitude")
+plt.title("Signal error")
+
+plt.figure(2)
+plt.clf()
+cRange = [-60, 0]
+plt.subplot(2, 1, 1)
+plt.pcolormesh(t, s.band_axis, dB(Xcq.T))
+plt.yscale('log')
+plt.clim(cRange)
+plt.colorbar()
+plt.xlabel("Time")
+plt.ylabel("Frequency")
+plt.title("CQT as Computed from spliced short NSGF-CQT")
+
+plt.subplot(2, 1, 2)
+plt.pcolormesh(t, s.band_axis, dB(XcqRef.T))
+plt.yscale('log')
+plt.clim(cRange)
+plt.colorbar()
+plt.xlabel("Time")
+plt.ylabel("Frequency")
+plt.title("CQT as Computed from dense signal")
+
+plt.tight_layout()

cicuetea-1.0.0/examples/psychoacoustics.py

@@ -0,0 +1,104 @@
+"""
+Psychoacoustic Scale Conversion Functions
+
+This module provides functions to convert between frequency (Hz) and various psychoacoustic scales:
+- Mel scale
+- ERB (Equivalent Rectangular Bandwidth) scale
+- Bark scale
+
+References and usage notes are included in the docstrings of each function.
+"""
+import numpy as np
+
+def freq2mel(freq):
+    """
+    Frequency to Mel conversion
+    
+    The mel scale is a linearization of the pitch space perception. The idea is that musical intervals are not exactly logarithmically spaced in the frequency axis. Accordingly, a span of 4 perfect octaves (2^4) is perceived as wider than what 4 musical octaves should be, for example. Psychoacoustical analysis was performed to obtain statistical proof of said pitch space compression.
+    
+    This mainly applies for perception of pitch space and does not take into account the implications of more complex tones.
+    
+    (Notice that this concept has been criticized even by one of its main authors and needs further revision. It is possible that other scales might be more relevant.)
+    
+    Parameters:
+        freq (float or array-like): Frequency in Hz
+    Returns:
+        float or ndarray: Value(s) in Mel scale
+    """
+    freq = np.asarray(freq)
+    return 1127 * np.log1p(freq / 700)
+
+def mel2freq(mel):
+    """
+    Mel to frequency conversion
+    
+    See freq2mel for details on the Mel scale.
+    
+    Parameters:
+        mel (float or array-like): Value(s) in Mel scale
+    Returns:
+        float or ndarray: Frequency in Hz
+    """
+    mel = np.asarray(mel)
+    return 700 * (np.exp(mel / 1127) - 1)
+
+def freq2erb(freq):
+    """
+    Frequency to Equivalent Rectangular Bandwidth (ERB) conversion
+    
+    The ERB scale is a model of listening critical bands where a dense ERB shares particular perceptual characteristics based on masking curves, equal loudness perception, and even complex tone integration. Notice however that any of these can be affected by other objective signal properties like loudness and timbre.
+    
+    Reference:
+    [1] Moore and Glasberg "A Revision of Zwicker's Loudness Model," ACTA Acustica, vol. 82, pp. 335-345, 1996
+    
+    Parameters:
+        freq (float or array-like): Frequency in Hz
+    Returns:
+        float or ndarray: Value(s) in ERB scale
+    """
+    freq = np.asarray(freq)
+    return 21.4 * np.log10(4.37 * freq / 1000 + 1.0)
+
+def erb2freq(erb):
+    """
+    Equivalent Rectangular Bandwidth (ERB) to frequency conversion
+    
+    See freq2erb for details on the ERB scale.
+    
+    Parameters:
+        erb (float or array-like): Value(s) in ERB scale
+    Returns:
+        float or ndarray: Frequency in Hz
+    """
+    erb = np.asarray(erb)
+    return 1000 * (10 ** (erb / 21.4) - 1.0) / 4.37
+
+def freq2bark(freq):
+    """
+    Frequency to Bark scale conversion
+    
+    The bark scale is a psychoacoustically defined scale of perception of frequency space in which the perception of such space is linearized. The idea behind it is that human perception is based on critical bands of hearing that share specific behaviors. The bandwidth of such frequencies is not constant across frequency, so the purpose of the bark scale is to quantify such bandwidth across frequencies.
+    
+    Reference: H. Traunmüller (1990) "Analytical expressions for the tonotopic sensory scale" J. Acoust. Soc. Am. 88: 97-100.
+    
+    Parameters:
+        freq (float or array-like): Frequency in Hz
+    Returns:
+        float or ndarray: Value(s) in Bark scale
+    """
+    freq = np.asarray(freq)
+    return (26.81 / (1 + 1960 / freq)) - 0.53
+
+def bark2freq(bark):
+    """
+    Bark scale to frequency conversion
+    
+    See freq2bark for details on the Bark scale.
+    
+    Parameters:
+        bark (float or array-like): Value(s) in Bark scale
+    Returns:
+        float or ndarray: Frequency in Hz
+    """
+    bark = np.asarray(bark)
+    return 1960 / (26.81 / (bark + 0.53) - 1)

cicuetea-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cicuetea"
+version = "1.0.0"
+description = "Real-time invertible Constant-Q Transform (CQT) engine based on nonstationary Gabor frames — Python reference implementation"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Juan Sierra" }]
+keywords = ["constant-q transform", "cqt", "nsgf", "spectral processing", "audio", "dsp"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+    "Intended Audience :: Science/Research",
+]
+dependencies = [
+    "numpy",
+    "scipy",
+]
+
+[project.optional-dependencies]
+demo = ["matplotlib"]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/jdsierral/CiCueTea"
+Documentation = "https://jdsierral.github.io/CiCueTea/"
+Repository = "https://github.com/jdsierral/CiCueTea"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cicuetea"]

cicuetea-1.0.0/src/cicuetea/__init__.py

@@ -0,0 +1,15 @@
+"""Python reference implementation of CiCueTea's NSGF Constant-Q Transform."""
+
+from .nsgf_cqt import NsgfCQT, NsgfVQT
+from .slicing import slicer, splicer, spectral_slicer, spectral_splicer
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "NsgfCQT",
+    "NsgfVQT",
+    "slicer",
+    "splicer",
+    "spectral_slicer",
+    "spectral_splicer",
+]

cicuetea-1.0.0/src/cicuetea/nsgf_cqt.py

@@ -0,0 +1,265 @@
+import numpy as np
+import scipy.fft as fft
+
+
+class NsgfCQT:
+    def __init__(self, mode, sample_rate, n_samples, 
+                 frac=1/12, f_min=1e2, f_max=1e4, f_ref=1e3, threshold=1e-6):
+        sample_rate = float(sample_rate)
+        n_samples = int(n_samples)
+        frac = float(frac)
+        f_min = float(f_min)
+        f_max = float(f_max)
+        f_ref = float(f_ref)
+        
+        # Structural validity
+        assert sample_rate > 0, "Sample rate must be positive"
+        assert n_samples > 0, "Block must be non-empty"
+        if mode == "sparse":  # power-of-two spans (pad_indices) assume it
+            assert (n_samples & (n_samples - 1)) == 0, "n_samples must be a power of 2"
+        assert frac > 0, "frac (reciprocal of bands per octave) must be positive"
+        assert f_ref > 0, "Reference frequency must be positive"
+        assert f_min > 0, "Lower bound must be positive"
+        assert f_min < f_max, "The range must be a range (f_min < f_max)"
+        assert f_max * 2 < sample_rate, "Higher bound must be below nyquist"
+
+        self.min_bw = 4
+
+        n_bands_up = int(np.ceil(1 / frac * np.log2(f_max / f_ref)))
+        n_bands_dn = int(np.ceil(1 / frac * np.log2(f_ref / f_min)))
+        n_bands = n_bands_dn + n_bands_up + 1
+        n_freqs = n_samples
+        bands = np.arange(-n_bands_dn, n_bands_up + 1)
+        band_axis = f_ref * 2.0 ** (frac * bands)               
+        time_axis = np.arange(-n_samples / 2, n_samples / 2) / sample_rate
+        freq_axis = np.arange(n_freqs) * sample_rate / n_freqs  
+
+        c = np.log(4) / (frac ** 2.0)                   # Horizontal Scale Factor
+        # log2(0) at the DC bin is fine: -inf yields a Gaussian weight of exactly 0
+        with np.errstate(divide="ignore"):
+            outer_diff = np.subtract.outer(np.log2(freq_axis), np.log2(band_axis))
+        g = np.exp(-c * outer_diff ** 2.0)              # Analytic Gaussians
+        g[np.where(freq_axis < band_axis[0]), 0] = 1    # Make lowest band an LPF
+        g[np.where(freq_axis > band_axis[-1]), -1] = 1  # Make highest band an HPF
+
+        if mode == "sparse":                # In sparse mode truncate gaussians
+            g[np.where(g < threshold)] = 0
+
+        d = np.sum(g ** 2.0, 1)
+
+        # Measured frame health. Two failure modes: coverage gaps (bins no atom reaches) show up as an ill-conditioned 
+        # frame operator; unresolved atoms (bands too narrow for the grid) are invisible in d and are caught by per-atom 
+        # support instead. (The old identity check rms(sum(g*g_dual) - 1) was algebraically zero by construction — it 
+        # could only ever catch exact 0/0 NaNs.)
+        dh = d[freq_axis <= sample_rate / 2]
+        assert dh.min() > 1e-6 * dh.max(), \
+            "Frame operator ill-conditioned: coverage gaps (Q too high or threshold too aggressive)"
+        support = np.count_nonzero(g > threshold, axis=0)
+        assert support.min() >= self.min_bw, \
+            "Atoms unresolved by the frequency grid (Q too high for this block size)"
+
+        g_dual = g / d[:, None]             # Compute the dual frame
+
+        g[np.where(freq_axis > sample_rate / 2), :] = 0
+        g_dual[np.where(freq_axis > sample_rate / 2), :] = 0
+
+        self.sample_rate = sample_rate
+        self.n_samples = n_samples
+        self.n_freqs = n_freqs
+        self.n_bands = n_bands
+        self.f_min = f_min
+        self.f_max = f_max
+        self.f_ref = f_ref
+        self.time_axis = time_axis
+        self.band_axis = band_axis
+        self.freq_axis = freq_axis
+        self.g = g
+        self.d = d
+        self.g_dual = g_dual
+        self.mode = mode
+
+        if mode == "sparse":
+            idxs = [None] * n_bands
+            g_list = [None] * n_bands
+            g_dual_list = [None] * n_bands
+            shifts = [None] * n_bands
+
+            for k in range(n_bands):
+                ii = np.where(g[:, k] != 0)[0]
+                ii = NsgfCQT.pad_indices(ii)
+                n_coefs = len(ii)
+                offset = ii[0]
+                idxs[k] = ii
+                n = np.arange(n_coefs)
+                shifts[k] = np.exp(1j * 2 * np.pi * offset * n / n_coefs)
+                g_list[k] = g[ii,k]
+                g_dual_list[k] = g_dual[ii,k]
+
+            self.g = g_list
+            self.g_dual = g_dual_list
+            self.idxs = idxs
+            self.shifts = shifts
+
+
+    def forward(self, x):
+        X = fft.fft(x, self.n_samples) / self.n_samples
+
+        if self.mode == "dense":
+            X_cq = 2 * self.n_samples * fft.ifft(X[:, None] * self.g, self.n_samples, 0)
+        elif self.mode == "sparse":
+            X_cq = [None] * self.n_bands
+            for k in range(self.n_bands):
+                n_coefs = float(len(self.idxs[k]))
+                Xi = fft.ifft(X[self.idxs[k]] * self.g[k])
+                Xi = Xi * 2 * n_coefs * self.shifts[k]
+                X_cq[k] = Xi
+        return X_cq
+
+
+    def inverse(self, X_cq):
+        if self.mode == "dense":
+            X = 1.0 / (2.0 * self.n_samples) * np.sum(fft.fft(X_cq, self.n_samples, 0) * self.g_dual, 1)
+        elif self.mode == "sparse":
+            X = np.zeros(self.n_samples, dtype=np.complex128)
+            for k in range(self.n_bands):
+                n_coefs = len(self.idxs[k])
+                Xi = X_cq[k] * (self.shifts[k].conj() / (2.0 * n_coefs))
+                Xi = fft.fft(Xi) * self.g_dual[k]
+                X[self.idxs[k]] += Xi
+        x = fft.irfft(X, self.n_samples) * self.n_samples
+        return x
+    
+
+    @staticmethod
+    def pad_indices(indices):
+        i0 = indices[0]
+        n_idx = indices.size
+        if n_idx < 4:
+            n_idx = 4
+        n_idx_pow2 = int(2 ** np.ceil(np.log2(n_idx)))
+        indices = i0 + np.arange(n_idx_pow2)
+        return indices
+    
+
+    def rasterize(self, X_cq):
+        """Reconstruct the dense [n_samples, n_bands] representation from
+        sparse coefficients: undo the per-band phase and scaling, recover the
+        band's span spectrum, and embed it at its true bins. Exactly equal to
+        the dense transform's columns (up to the sparsity threshold), unlike
+        naive bandlimited interpolation, which assumes baseband input while
+        the coefficients carry the (aliased) carrier."""
+        X_r = np.zeros([self.n_samples, self.n_bands], dtype=np.complex128)
+        for k in range(self.n_bands):
+            n_coefs = len(self.idxs[k])
+            Xi = X_cq[k] * (self.shifts[k].conj() / (2.0 * n_coefs))
+            spec = np.zeros(self.n_freqs, dtype=np.complex128)
+            spec[self.idxs[k]] = fft.fft(Xi)
+            X_r[:, k] = 2 * self.n_samples * fft.ifft(spec)
+        return X_r
+    
+class NsgfVQT(NsgfCQT):
+    def __init__(self, mode, sample_rate, n_samples, f_map=np.log2,
+                 frac=1/12, f_min=1e2, f_max=1e4, f_ref=1e3, threshold=1e-6):
+        sample_rate = float(sample_rate)
+        n_samples = int(n_samples)
+        frac = float(frac)
+        f_min = float(f_min)
+        f_max = float(f_max)
+        f_ref = float(f_ref)
+        # Structural validity: each condition provably breaks the transform on
+        # its own. Feasibility with fuzzy boundaries (Q vs. block length) is
+        # measured on the constructed frame below, not predicted from the
+        # parameters; sub-octave ranges are legitimate. (The C++ version
+        # additionally requires power-of-two n_samples in both modes, since
+        # its FFT backends do.)
+        assert sample_rate > 0, "Sample rate must be positive"
+        assert n_samples > 0, "Block must be non-empty"
+        if mode == "sparse":  # power-of-two spans (pad_indices) assume it
+            assert (n_samples & (n_samples - 1)) == 0, "n_samples must be a power of 2"
+        assert frac > 0, "frac (reciprocal of bands per octave) must be positive"
+        assert f_ref > 0, "Reference frequency must be positive"
+        assert f_min > 0, "Lower bound must be positive"
+        assert f_min < f_max, "The range must be a range (f_min < f_max)"
+        assert f_max * 2 < sample_rate, "Higher bound must be below nyquist"
+
+        self.min_bw = 4
+
+        n_bands_up = int(np.ceil(1 / frac * (f_map(f_max) - f_map(f_ref))))
+        n_bands_dn = int(np.ceil(1 / frac * (f_map(f_ref) - f_map(f_min))))
+        n_bands = n_bands_dn + n_bands_up + 1
+        n_freqs = n_samples
+        bands = np.arange(-n_bands_dn, n_bands_up + 1)
+        band_axis = f_map(f_ref) + (frac * bands)               
+        time_axis = np.arange(-n_samples / 2, n_samples / 2) / sample_rate 
+        freq_axis = np.arange(n_freqs) * sample_rate / n_freqs  
+
+        c = np.log(4) / (frac ** 2.0)                   # Horizontal Scale Factor
+        # f_map(0) at the DC bin may be -inf (e.g. log2): Gaussian weight becomes exactly 0
+        with np.errstate(divide="ignore"):
+            warped_fax = f_map(freq_axis)
+        outer_diff = np.subtract.outer(warped_fax, band_axis)
+        g = np.exp(-c * outer_diff ** 2.0)              # Analytic Gaussians
+        g[np.where(warped_fax < band_axis[0]), 0] = 1    # Make lowest band an LPF
+        g[np.where(warped_fax > band_axis[-1]), -1] = 1  # Make highest band an HPF
+
+        if mode == "sparse":                # In sparse mode truncate gaussians
+            g[np.where(g < threshold)] = 0
+
+        d = np.sum(g ** 2.0, 1)
+
+        # Measured frame health (mirrors the C++ checks). Two failure modes:
+        # coverage gaps (bins no atom reaches) show up as an ill-conditioned
+        # frame operator; unresolved atoms (bands too narrow for the grid)
+        # are invisible in d and are caught by per-atom support instead.
+        # (The old identity check rms(sum(g*g_dual) - 1) was algebraically
+        # zero by construction — it could only ever catch exact 0/0 NaNs.)
+        dh = d[freq_axis <= sample_rate / 2]
+        assert dh.min() > 1e-6 * dh.max(), \
+            "Frame operator ill-conditioned: coverage gaps (Q too high or threshold too aggressive)"
+        support = np.count_nonzero(g > threshold, axis=0)
+        assert support.min() >= self.min_bw, \
+            "Atoms unresolved by the frequency grid (Q too high for this block size)"
+
+        g_dual = g / d[:, None]             # Compute the dual frame
+
+        g[np.where(freq_axis > sample_rate / 2), :] = 0
+        g_dual[np.where(freq_axis > sample_rate / 2), :] = 0
+
+        self.sample_rate = sample_rate
+        self.n_samples = n_samples
+        self.n_freqs = n_freqs
+        self.n_bands = n_bands
+        self.f_map = f_map
+        self.f_min = f_min
+        self.f_max = f_max
+        self.f_ref = f_ref
+        self.time_axis = time_axis
+        self.band_axis = band_axis
+        self.freq_axis = freq_axis
+        self.g = g
+        self.d = d
+        self.g_dual = g_dual
+        self.mode = mode
+
+        if mode == "sparse":
+            idxs = [None] * n_bands
+            g_list = [None] * n_bands
+            g_dual_list = [None] * n_bands
+            shifts = [None] * n_bands
+
+            for k in range(n_bands):
+                ii = np.where(g[:, k] != 0)[0]
+                ii = NsgfCQT.pad_indices(ii)
+                n_coefs = len(ii)
+                offset = ii[0]
+                idxs[k] = ii
+                n = np.arange(n_coefs)
+                shifts[k] = np.exp(1j * 2 * np.pi * offset * n / n_coefs)
+                g_list[k] = g[ii,k]
+                g_dual_list[k] = g_dual[ii,k]
+
+            self.g = g_list
+            self.g_dual = g_dual_list
+            self.idxs = idxs
+            self.shifts = shifts
+

cicuetea-1.0.0/src/cicuetea/slicing.py

@@ -0,0 +1,85 @@
+import numpy as np
+
+def slicer(x, block_size, overlap_size):
+    """
+    Slice a 1D array into overlapping blocks.
+
+    Parameters:
+        x (np.ndarray): Input 1D array.
+        block_size (int): Size of each block.
+        overlap_size (int): Number of samples that overlap between blocks.
+
+    Returns:
+        np.ndarray: 2D array of shape (n_blocks, block_size) containing the blocks.
+    """
+    n_samps = x.size
+    hop_size = block_size - overlap_size  # Step size between blocks
+    # Compute indices for each block
+    idx = np.add.outer(np.arange(0, n_samps - block_size + 1, hop_size), np.arange(block_size))
+    return x[idx]
+
+def splicer(x, overlap_size):
+    """
+    Reconstruct a 1D array from overlapping blocks (inverse of slicer).
+
+    Parameters:
+        x (np.ndarray): 2D array of shape (n_blocks, block_size) containing the blocks.
+        overlap_size (int): Number of samples that overlap between blocks.
+
+    Returns:
+        np.ndarray: Reconstructed 1D array.
+    """
+    n_blocks, block_size = x.shape
+    hop_size = block_size - overlap_size
+    pos = 0
+
+    n_samples = hop_size * n_blocks + overlap_size  # Total length of reconstructed signal
+    y = np.zeros(n_samples, dtype=x.dtype)  # follow the input (real stays real)
+
+    for i in np.arange(n_blocks):
+        ii = np.arange(block_size) + pos  # Indices for current block
+        y[ii] += x[i, :]
+        pos += hop_size
+    return y
+
+def spectral_slicer(X, block_size, overlap_size):
+    """
+    Slice a 2D array (e.g., time-frequency representation) into overlapping blocks along the first axis.
+
+    Parameters:
+        X (np.ndarray): 2D array of shape (n_samples, n_bands).
+        block_size (int): Size of each block.
+        overlap_size (int): Number of samples that overlap between blocks.
+
+    Returns:
+        np.ndarray: 3D array of shape (n_blocks, n_bands, block_size) containing the blocks.
+    """
+    n_samps, n_bands = X.shape
+    hop_size = block_size - overlap_size
+    n_blocks = int(np.ceil((n_samps - overlap_size) / hop_size))
+    X_block = np.zeros([n_blocks, n_bands, block_size], dtype='complex128')
+    for k in np.arange(n_bands):
+        # Slice each band independently
+        X_block[:, k, :] = slicer(X[:, k], block_size, overlap_size)
+    return X_block
+
+def spectral_splicer(X_block, overlap_size):
+    """
+    Reconstruct a 2D array from overlapping blocks (inverse of spectral_slicer).
+
+    Parameters:
+        X_block (np.ndarray): 3D array of shape (n_blocks, n_bands, block_size) containing the blocks.
+        overlap_size (int): Number of samples that overlap between blocks.
+
+    Returns:
+        np.ndarray: 2D array of shape (n_samples, n_bands) reconstructed from the blocks.
+    """
+    n_blocks, n_bands, block_size = X_block.shape
+    hop_size = block_size - overlap_size
+    n_samps = hop_size * n_blocks + overlap_size  # Total length of reconstructed signal
+
+    X = np.zeros([n_samps, n_bands], dtype='complex128')
+    for k in np.arange(n_bands):
+        # Reconstruct each band independently
+        X[:, k] = splicer(X_block[:, k, :], overlap_size)
+    return X

cicuetea-1.0.0/tests/test_roundtrip.py

@@ -0,0 +1,51 @@
+import numpy as np
+import pytest
+
+from cicuetea import NsgfCQT, NsgfVQT
+
+
+def _rms(x):
+    return np.sqrt(np.mean(np.abs(x) ** 2.0))
+
+
+@pytest.mark.parametrize("mode", ["dense", "sparse"])
+@pytest.mark.parametrize("frac", [1.0, 1 / 12])
+def test_cqt_roundtrip(mode, frac):
+    fs = 48000
+    n_samples = 2**14
+    x = np.random.default_rng(0).standard_normal(n_samples)
+
+    cqt = NsgfCQT(mode, fs, n_samples, frac=frac, f_min=100, f_max=10000)
+    y = cqt.inverse(cqt.forward(x))
+
+    assert _rms(x - y) < 1e-10
+
+
+def test_vqt_roundtrip():
+    fs = 48000
+    n_samples = 2**14
+    x = np.random.default_rng(1).standard_normal(n_samples)
+
+    vqt = NsgfVQT("dense", fs, n_samples, f_map=np.log2, frac=1 / 12)
+    y = vqt.inverse(vqt.forward(x))
+
+    assert _rms(x - y) < 1e-10
+
+
+def test_rasterize_matches_dense():
+    fs = 48000
+    n_samples = 2**14
+    x = np.random.default_rng(2).standard_normal(n_samples)
+
+    dense = NsgfCQT("dense", fs, n_samples, frac=1 / 12)
+    sparse = NsgfCQT("sparse", fs, n_samples, frac=1 / 12)
+
+    X_dense = dense.forward(x)
+    X_sparse = sparse.rasterize(sparse.forward(x))
+
+    assert _rms(X_dense - X_sparse) < 1e-5
+
+
+def test_rejects_invalid_range():
+    with pytest.raises(AssertionError):
+        NsgfCQT("dense", 48000, 2**14, frac=1 / 12, f_min=10000, f_max=100)