Docs don't match behaviour: "start with default settings", filter description, sample rate, CPU/GPU differences, versions

[joeljose]

Severity: Low.

Where	Docs say	Reality
README Tips	"Start with default settings and adjust from there."	the defaults apply no filter, and a small drift ruins the output (#14)
README (Butterworth section)	the filter "rejects low-frequency drift (camera shake, thermal effects)"	only when -fl is given; the default is no filter (#14). Crash and skip cases are covered in #15
README CPU/GPU differences	"similar but not bit-identical… different DTCWT implementations"	running the GPU code on CPU torch, CPU and GPU outputs correlate at 1.000 on synthetic tests. Mention the measured agreement, which is reassuring, and the GPU partial-batch frame loss (#16)
README Pipeline	"The sample_rate is set to the video's FPS"	int(fps) truncates; container fps is often wrong (#15). Recommend resampling for playback
README Performance	GPU timings only	add CPU timings (≈ 78 min for Chips1; see the performance issue)
README Setup	"Python 3.8+"	images and CI use Python 3.11; the lower bounds aren't tested
README Future Work	wrapped phase "produces lower-amplitude signals"	the bigger problem is wrap-around relative to frame 0 under drift (#17), which has a straightforward fix
Versioning	VERSION is the "single source of truth"	__version__ is also hard-coded in visualmic.py, and test_version_flag hard-codes '2.0.0'. Read the version from package metadata, or test that the two match
Dockerfile.gpu comment	pytorch_wavelets "last commit 2023", so PyTorch 2.1.2 is required	worked on torch 2.14 CPU in this audit (see the build issue)

Suggested fix

Correct each row. Add a short "Getting good results" section:

• always pass --fps with the true capture rate;
• use -fl of about 20-100 Hz;
• pick an ROI on the vibrating object;
• expect roughly fps/2 of audio bandwidth.