This document summarizes what we changed in nnAudio, which problems were fixed, how to run the project locally, and what results we expect to see.

The work described here focuses on the professor's explicit requests: compatibility with current Torch and dependencies, issue #132, issue #136, and a citation reminder for users.

The current local verification environment is:

• Python: 3.11.10
• Torch: 2.10.0+cpu
• NumPy: 2.4.3
• SciPy: 1.17.1
• librosa: 0.11.0
• nnAudio package version: 0.3.4

Notes:

• The codebase has been updated to run correctly in this modern dependency environment.
• We did not bump the package version to 2.0; functionally, this is the start of maintaining a newer generation of nnAudio, not a formal package release named 2.0.

This file received the largest set of changes and addresses two main issues.

Original problem:

• torch.jit.script(STFT(...)) failed
• torch.jit.script(iSTFT(...)) also failed

Main causes:

1. Dynamic module attribute assignment inside forward()
2. Dynamic padding module construction inside forward()
3. None handling in iSTFT that was not TorchScript-friendly

What we changed:

1. Replaced dynamic attribute writes with local variables
2. Replaced dynamically constructed padding modules with functional padding
3. Tightened argument handling for TorchScript-facing paths

Result:

• STFT can now be compiled with torch.jit.script(...)
• iSTFT can now be compiled with torch.jit.script(...)

Original problem:

• freq_scale='linear' or freq_scale='log' produced clearly poor inverse reconstructions
• The code did not fail, which was misleading for users

What we changed:

1. Added explicit inverse-support checks
2. Defined reliable inverse support only for the standard uniform-bin case with freq_scale='no'
3. Non-uniform frequency scales (linear, log, log2) now raise a clear runtime error on inverse
4. Initialization warnings were added to mark these configurations as analysis-only

Result:

• freq_scale='no': inverse still works
• freq_scale='linear' / 'log' / 'log2': inverse no longer silently returns bad audio; it now fails explicitly

This file was updated to support the TorchScript fix for issue #132.

What we changed:

1. Added explicit type annotations to torch_window_sumsquare(...) and overlap_add(...)
2. Adjusted fold(..., stride=...) argument handling to better match current Torch / TorchScript behavior

Result:

• The helper functions used by iSTFT can now be handled correctly by TorchScript

This file received new regression tests.

New coverage includes:

1. TorchScript compilation for STFT
2. TorchScript compilation for iSTFT
3. Rejection behavior for inverse on non-uniform frequency scales

Result:

• These behaviors are now covered by tests instead of being only manually verified once

This file was updated for modern SciPy compatibility.

Original problem:

• scipy.signal.blackmanharris was no longer available at the old location under the current SciPy version

What we changed:

• Switched to scipy.signal.windows.blackmanharris

Result:

• CFP-related tests now pass again

This file was updated to fix VQT/CQT compatibility behavior.

Original problem:

• VQT(gamma=0) should theoretically reduce to CQT, but it showed a meaningful mismatch against CQT1992v2

What we changed:

• When gamma == 0, VQT now explicitly routes through CQT1992v2

Result:

• VQT(gamma=0) is aligned with CQT behavior
• The related tests now pass

This file implements the citation reminder requested by the professor.

Added:

1. __citation__
2. cite()
3. show_citation()
4. CitationReminderWarning
5. Import-time citation reminder
6. NNAUDIO_DISABLE_CITATION_REMINDER=1 to suppress the reminder

Result:

• import nnAudio now reminds users to cite the paper
• Users can also access the citation programmatically

This is a new test file for citation-related behavior.

Coverage includes:

1. Citation text exists and contains the DOI
2. The import-time warning appears
3. The suppress environment variable works

To avoid misleading users about issue #136, we also updated:

1. README.md
2. Sphinx/source/intro.rst
3. Sphinx/source/index.rst

The purpose here was not to expand scope, but to document the new supported/unsupported boundary clearly.

At this point, the following problems have been addressed:

1. Core compatibility issues with current Torch and current dependencies
2. issue #132: STFT / iSTFT could not be compiled with TorchScript
3. issue #136: non-uniform frequency-scale inverse silently returned poor results
4. CFP initialization failed under modern SciPy
5. VQT(gamma=0) did not align with CQT behavior
6. The package had no built-in citation reminder

cd /junyi/nnAudio
source .venv/bin/activate

pytest Installation/tests -q

pytest Installation/tests/test_stft.py -q

python - <<'PY'
import nnAudio
print(nnAudio.__version__)
print(nnAudio.__citation__)
PY

NNAUDIO_DISABLE_CITATION_REMINDER=1 python - <<'PY'
import nnAudio
print(nnAudio.__version__)
PY

Command:

pytest Installation/tests -q

Expected result:

• You should currently see 57 passed
• A number of warnings are acceptable
• There should be no failed tests

STFT and iSTFT should now compile with torch.jit.script(...) and should no longer raise the original issue #132 errors.

For:

• freq_scale='no'

Expected result:

• inverse works
• reconstruction error remains very small

For:

• freq_scale='linear'
• freq_scale='log'
• freq_scale='log2'

Expected result:

• inverse raises a clear exception
• this is expected behavior, not a bug

Reason:

• under the current implementation, these inverse paths are not numerically reliable
• explicit failure is safer than silently returning poor output

Command:

python - <<'PY'
import nnAudio
PY

Expected result:

• a CitationReminderWarning is shown
• it reminds the user to cite the nnAudio paper

The test suite now passes completely, but a few warnings are still present:

1. CFP still emits a divide by zero warning
2. torch.stft(return_complex=False) has a future deprecation warning
3. torch.jit.script itself is deprecated in newer Torch versions

These are not blockers for the professor's current task, but they are reasonable cleanup targets for a later maintenance pass.

Against the professor's explicit task list:

1. Current Torch / dependency compatibility: validated locally in a modern environment
2. issue #132: completed
3. issue #136: completed via a safe supported/unsupported boundary
4. Citation reminder: completed via import-time reminder

At this stage, the core task requested by the professor can be considered complete.