Upload pywavelets/PYWAVELETS_USER_GUIDE.txt with huggingface_hub

pywavelets/PYWAVELETS_USER_GUIDE.txt

@@ -0,0 +1,91 @@
+================================================================================
+  PYWAVELETS - USER GUIDE (Android Python STB) - Generated by RIMI
+================================================================================
+
+PyWavelets 1.10.0 for Android (CPython 3.12, API 24)
+----------------------------------------------------
+PyWavelets (import name: pywt) is a wavelet transform library for Python:
+discrete and stationary wavelet transforms (1D, 2D, nD), wavelet packets,
+continuous wavelet transform (CWT), thresholding, and multilevel analysis.
+
+Provided wheels (C extensions, cross-compiled with NDK r26):
+  pywavelets-1.10.0-cp312-cp312-android_24_arm64_v8a.whl  (real ARM64 phones)
+  pywavelets-1.10.0-cp312-cp312-android_24_x86_64.whl     (x86_64 emulators)
+
+Installation
+------------
+1. Install the numpy 2.5.2 Android wheel FIRST (from its own package
+   folder — do NOT look for numpy in the pywavelets folder):
+     numpy-2.5.2-cp312-cp312-android_24_<arch>.whl
+2. Install the matching pywavelets STANDALONE wheel:
+     pywavelets-1.10.0-cp312-cp312-android_24_<arch>.whl
+   pip resolves the `numpy<3,>=1.26.4` runtime dependency from the
+   already-installed numpy (both wheels share the same Python 3.12 ABI).
+3. Run Test_PyWavelets.py from the Scripts folder; expect ALL PASSED.
+
+Quick start
+-----------
+  import pywt
+  import numpy as np
+
+  x = np.arange(16, dtype=float)
+
+  # 1D discrete transform and perfect reconstruction
+  cA, cD = pywt.dwt(x, 'db1')
+  y = pywt.idwt(cA, cD, 'db1')
+
+  # Multilevel decomposition
+  coeffs = pywt.wavedec(x, 'db2', level=2)
+  y = pywt.waverec(coeffs, 'db2')
+
+  # Stationary (undecimated) transform
+  swt = pywt.swt(x, 'haar', level=1)
+  y = pywt.iswt(swt, 'haar')
+
+  # 2D transform
+  img = np.arange(64, dtype=float).reshape(8, 8)
+  cA, (cH, cV, cD) = pywt.dwt2(img, 'haar')
+  rec = pywt.idwt2((cA, (cH, cV, cD)), 'haar')
+
+  # Denoising-style thresholding
+  t = pywt.threshold(np.linspace(-2, 2, 32), 1.0, mode='soft')
+
+  print(pywt.wavelist()[:5])   # ['bior1.1', 'bior1.3', ...]
+
+Android-specific notes
+----------------------
+* The 4 native modules (pywt/_extensions/_cwt, _dwt, _pywt, _swt,
+  named *.cpython-312.so) link only against librimi.so + system
+  libm/libdl/libc. No C++ runtime is needed (pure C + Cython).
+* 16 KB page aligned, no GNU_RELRO: safe on Android 13+ (no dlopen
+  `can't enable GNU RELRO protection` crash).
+* No OPENBLAS/Fortran dependency — unlike numpy/scipy this wheel is
+  small (~4.3 MB) and has no native deps besides numpy's headers
+  at build time.
+* Shell `python3` on device cannot load these modules (librimi.so needs
+  the app JVM context); always test inside the app via Scripts.
+
+Known upstream quirk (NOT a build defect)
+-----------------------------------------
+The 1.10.0 source distribution ships util/version_utils.py with the
+version constants still at 1.8.0, so `pywt.__version__` reports '1.8.0'
+— the official PyPI 1.10.0 wheels do exactly the same. The *wheel*
+version (pywavelets-1.10.0.dist-info) is 1.10.0. The device test
+therefore checks only that the version string is present.
+
+Tested features (device script Test_PyWavelets.py, 10 checks)
+--------------------------------------------------------------
+  import pywt + numpy / version string / Wavelet('db1') object /
+  wavelist contents (db1, db2, haar, sym2) / dwt+idwt roundtrip /
+  wavedec+waverec roundtrip (db2, level 2) / swt+iswt roundtrip (haar) /
+  dwt2+idwt2 roundtrip (haar, 8x8) / soft+hard threshold smoke /
+  pywt.data.camera() load.
+
+Runtime dependency
+------------------
+  numpy<3,>=1.26.4 (declared in METADATA Requires-Dist; install the
+  numpy 2.5.2 Android wheel from its own package folder separately).
+
+================================================================================
+  Generated by RIMI
+================================================================================