Upload numpy/NUMPY_USER_GUIDE.txt with huggingface_hub

numpy/NUMPY_USER_GUIDE.txt

@@ -0,0 +1,534 @@
+================================================================================
+  NUMPY - USER GUIDE (Android Python STB)
+  Generated by RIMI
+================================================================================
+  Covers: what numpy is, install/verify, arrays, dtypes, math, indexing,
+          reshaping, linear algebra, random, file I/O, numpy + Pillow,
+          printing in the terminal, and common pitfalls.
+
+  Written for: Python 3.12.2 (RIMI build) on Android
+  Version:     numpy 2.5.2
+  Scripts dir: /storage/emulated/0/PythonSTB/Scripts/
+  Installed:   /data/user/0/com.pythonstb.rimi/files/python/lib/python3.12/site-packages/
+================================================================================
+
+
+--------------------------------------------------------------------------------
+1) WHAT IS NUMPY?
+--------------------------------------------------------------------------------
+
+NumPy is the fundamental library for fast numerical computing in Python.
+It adds:
+  - n-dimensional arrays (ndarray) - faster and more compact than Python lists
+  - element-wise math without writing loops
+  - linear algebra (matrix multiply, inverse, solve, eig, ...)
+  - random numbers, FFT, sorting, statistics
+  - a bridge to C/Python extensions (OpenCV, Pillow, pandas, scipy, ...)
+
+Typical speedup vs plain Python loops: 10x - 100x or more.
+
+This Android build of numpy is compiled with OpenBLAS, so matrix operations
+are optimized (BLAS/LAPACK) on both arm64 and x86_64.
+
+    import numpy as np
+    print(np.__version__)          # 2.5.2
+    print(np.show_config())        # shows BLAS/LAPACK backend + build info
+
+
+--------------------------------------------------------------------------------
+2) INSTALL / VERIFY
+--------------------------------------------------------------------------------
+
+Install (already done, but if you ever reinstall):
+    pip install numpy              # or install the wheel file directly
+
+Quick smoke test - run in your app:
+    import numpy as np
+    a = np.arange(12).reshape(3, 4)
+    print(a)
+    print("sum:", a.sum(), "max:", a.max(), "shape:", a.shape, "dtype:", a.dtype)
+    print("blas:", np.__config__.show("build") if hasattr(np.__config__, "show") else "n/a")
+
+Expected output pattern:
+    [[ 0  1  2  3]
+     [ 4  5  6  7]
+     [ 8  9 10 11]]
+    sum: 66  max: 11  shape: (3, 4)  dtype: int64
+
+
+--------------------------------------------------------------------------------
+3) ARRAYS - CREATION BASICS
+--------------------------------------------------------------------------------
+
+    import numpy as np
+
+    # from a list
+    a = np.array([1, 2, 3])                     # 1-D, dtype int64
+    b = np.array([[1, 2, 3], [4, 5, 6]])        # 2-D shape (2, 3)
+    c = np.array([1.0, 2.0, 3.0])               # float64
+
+    # zeros / ones / full / identity
+    np.zeros((3, 4))
+    np.ones((2, 2))
+    np.full((2, 3), 7.5)
+    np.eye(4)                                   # 4x4 identity
+    np.identity(3)
+
+    # ranges
+    np.arange(10)                # 0..9
+    np.arange(0, 1, 0.1)         # 0.0, 0.1, ... 0.9
+    np.linspace(0, 1, 5)         # 5 evenly spaced points 0..1
+    np.logspace(1, 3, 3)         # 10, 100, 1000
+
+    # random
+    rng = np.random.default_rng(seed=42)        # reproducible
+    rng.random((3, 3))                          # uniform [0,1)
+    rng.integers(0, 10, size=(2, 5))            # integers 0..9
+    rng.normal(0, 1, size=(4,))                 # normal dist
+    rng.permutation(10)                         # shuffled 0..9
+
+    # important attributes
+    a = np.array([[1, 2, 3], [4, 5, 6]])
+    a.shape          # (2, 3)
+    a.ndim           # 2
+    a.size           # 6
+    a.dtype          # dtype('int64')
+    a.itemsize       # bytes per element
+    a.nbytes         # total bytes
+
+
+--------------------------------------------------------------------------------
+4) DTYPES (data types)
+--------------------------------------------------------------------------------
+
+    np.int8    np.int16   np.int32   np.int64     # signed integers
+    np.uint8   np.uint16  np.uint32  np.uint64    # unsigned integers
+    np.float32 np.float64                        # floats (f32 is half memory)
+    np.complex64 np.complex128                   # complex
+    np.bool_                                      # boolean
+    np.str_     np.bytes_                         # strings (avoid for math)
+    'f4','f8','i1','i2','i4','i8','u1','u2','u4','u8'   # short aliases
+
+    a = np.array([1, 2, 3], dtype=np.uint8)
+    b = a.astype(np.float32)      # convert
+    c = a.astype('f4')
+
+Rules of thumb:
+  - use np.float64 (default) for general math
+  - use np.float32 or np.uint8 for big arrays / images (half the memory)
+  - beware overflow: np.array([200], np.uint8) + 100 wraps to 44
+  - beware int division: np.array([5]) // 2 == 2 (floor), np.array([5]) / 2 == 2.5
+
+
+--------------------------------------------------------------------------------
+5) INDEXING AND SLICING
+--------------------------------------------------------------------------------
+
+    a = np.arange(12).reshape(3, 4)
+    # [[ 0  1  2  3]
+    #  [ 4  5  6  7]
+    #  [ 8  9 10 11]]
+
+    a[0]            # row 0: [0 1 2 3]
+    a[0, 2]         # scalar 2
+    a[:, 1]         # column 1: [1 5 9]
+    a[1:, :2]       # rows 1..2, cols 0..1
+    a[-1]           # last row
+    a[::2]          # every other row
+
+    # boolean masking
+    a[a > 5]                          # 1-D array of values > 5
+    a[(a > 2) & (a < 8)]              # combine masks with & |
+    a[a % 2 == 0]                     # even values
+
+    # fancy indexing with arrays
+    a[[0, 2]]                         # rows 0 and 2
+    idx = np.array([3, 1])
+    a[:, idx]                         # columns 3 and 1
+
+    # assignment with masks
+    a[a < 5] = 0                      # zero out everything below 5
+    a[:, 0] = -1                      # set first column
+
+
+--------------------------------------------------------------------------------
+6) SHAPES - RESHAPE / FLATTEN / TRANSPOSE / BROADCAST
+--------------------------------------------------------------------------------
+
+    a = np.arange(24)
+
+    a.reshape(4, 6)       # same data, new shape
+    a.reshape(2, 3, 4)    # 3-D
+    a.reshape(-1, 6)      # -1 = auto: (4, 6)
+    a.ravel()             # flatten to 1-D (may copy)
+    a.flatten()           # always a copy, 1-D
+    a.T                   # transpose
+    a.reshape(4, 6).T.shape          # (6, 4)
+
+    # add a new axis
+    v = np.array([1, 2, 3])
+    v[np.newaxis, :].shape            # (1, 3)
+    v[:, np.newaxis].shape            # (3, 1)
+
+    # BROADCASTING: shapes line up from the right
+    m = np.ones((3, 4))
+    m + 1                     # scalar broadcast
+    m * np.array([10, 20, 30, 40])     # row vector broadcast over rows
+    m + np.array([[1], [2], [3]])      # column vector broadcast over cols
+    # rule: dimensions must be equal or one of them must be 1
+
+
+--------------------------------------------------------------------------------
+7) MATH - ELEMENT-WISE AND REDUCTIONS
+--------------------------------------------------------------------------------
+
+    a = np.array([1., 2., 3., 4.])
+
+    a + 1, a - 1, a * 2, a / 2, a ** 2, -a          # element-wise
+    np.sqrt(a), np.abs(a), np.exp(a), np.log(a)
+    np.sin(a), np.cos(a), np.tan(a), np.arctan(a)
+    np.round(a), np.floor(a), np.ceil(a), np.clip(a, 1.5, 3.5)
+    np.sign(a), np.mod(a, 2), np.power(a, 3)
+    np.maximum(a, 2), np.minimum(a, 3)
+
+    # reductions (default: over all elements)
+    a.sum()   a.mean()   a.min()   a.max()   a.std()   a.var()
+    a.prod()  a.argmax() a.argmin() a.cumsum() a.cumprod()
+    np.median(a)   np.percentile(a, 50)   np.ptp(a)          # peak-to-peak
+
+    # along an axis
+    m = np.arange(6).reshape(2, 3)
+    m.sum(axis=0)        # per column: [3 5 7]
+    m.sum(axis=1)        # per row:    [3 12]
+    m.max(axis=0), m.min(axis=1)
+
+    # comparisons return boolean arrays
+    (a > 2)            # array([False, False,  True,  True])
+    np.any(a > 2)      # True
+    np.all(a > 2)      # False
+    np.count_nonzero(a > 2)   # 2
+
+
+--------------------------------------------------------------------------------
+8) LINEAR ALGEBRA (OpenBLAS accelerated)
+--------------------------------------------------------------------------------
+
+    a = np.array([[1., 2.], [3., 4.]])
+    b = np.array([[5., 6.], [7., 8.]])
+
+    a @ b                    # matrix multiply (preferred)
+    np.matmul(a, b)          # same
+    a.dot(b)                 # same (older style)
+    a * b                    # ELEMENT-WISE, NOT matrix multiply
+
+    np.linalg.inv(a)         # inverse
+    np.linalg.det(a)         # determinant
+    np.linalg.solve(a, np.array([1., 2.]))   # solve a x = b
+    np.linalg.eig(a)         # eigenvalues + eigenvectors
+    np.linalg.norm(a)        # Frobenius norm
+    np.linalg.qr(a), np.linalg.svd(a)
+    np.linalg.pinv(a)        # pseudo-inverse
+    np.linalg.matrix_power(a, 3)
+
+    # vector ops
+    v = np.array([1., 2., 3.])
+    w = np.array([4., 5., 6.])
+    np.dot(v, w)             # dot product 32.0
+    np.cross(v, w)           # cross product
+    np.inner(v, w)           # inner product
+
+    # useful on the device: transform a 3D point / homography
+    M = np.array([[1., 0., 10.], [0., 1., 20.], [0., 0., 1.]])
+    p = np.array([5., 6., 1.])
+    out = M @ p
+
+
+--------------------------------------------------------------------------------
+9) STACKING, SPLITTING, CONCATENATING
+--------------------------------------------------------------------------------
+
+    a = np.array([1, 2, 3])
+    b = np.array([4, 5, 6])
+
+    np.concatenate((a, b))         # [1 2 3 4 5 6]
+    np.stack((a, b))               # shape (2, 3)
+    np.vstack((a, b))              # vertical: shape (2, 3)
+    np.hstack((a, b))              # horizontal: [1 2 3 4 5 6]
+    np.dstack((a, b))              # depth: shape (1, 3, 2)
+
+    m1 = np.ones((2, 2))
+    m2 = np.zeros((2, 2))
+    np.vstack((m1, m2))            # (4, 2)
+    np.hstack((m1, m2))            # (2, 4)
+
+    # split
+    x = np.arange(10)
+    np.split(x, 2)                 # two arrays of 5
+    np.array_split(x, 3)           # uneven split
+    np.hsplit(m1, 2), np.vsplit(m1, 2)
+
+
+--------------------------------------------------------------------------------
+10) RANDOM NUMBERS
+--------------------------------------------------------------------------------
+
+    rng = np.random.default_rng(2026)      # always seed for reproducibility
+    rng.random((2, 3))                     # [0,1) floats
+    rng.integers(1, 7, size=10)            # die rolls 1..6
+    rng.normal(loc=0, scale=1, size=(3, 3))
+    rng.uniform(0, 10, size=5)
+    rng.choice(np.arange(5), size=10, replace=True)
+    rng.shuffle(np.arange(10))             # in place
+    rng.standard_normal((4,))
+
+    # old style (np.random.rand etc.) also works, but default_rng is preferred.
+
+
+--------------------------------------------------------------------------------
+11) SAVE / LOAD DATA (files)
+--------------------------------------------------------------------------------
+
+    a = np.arange(12).reshape(3, 4)
+
+    # numpy binary format (fast, compact, one array per file)
+    np.save("/storage/emulated/0/Download/a.npy", a)
+    b = np.load("/storage/emulated/0/Download/a.npy")
+
+    # compressed multi-array archive
+    np.savez("/storage/emulated/0/Download/data.npz", x=a, y=a * 2)
+    d = np.load("/storage/emulated/0/Download/data.npz")
+    d["x"], d["y"]
+    # or np.savez_compressed(...) for smaller files
+
+    # text (human readable)
+    np.savetxt("/storage/emulated/0/Download/a.csv", a, delimiter=",")
+    c = np.loadtxt("/storage/emulated/0/Download/a.csv", delimiter=",")
+    # note: loadtxt returns float64; use dtype= to control
+    np.savetxt("/storage/emulated/0/Download/a.tsv", a, delimiter="\t",
+               fmt="%.2f")
+
+    # plain binary (raw, no header)
+    a.tofile("/storage/emulated/0/Download/a.bin")
+    np.fromfile("/storage/emulated/0/Download/a.bin", dtype=np.int64)
+
+
+--------------------------------------------------------------------------------
+12) NUMPY + PILLOW (images are just arrays)
+--------------------------------------------------------------------------------
+
+    from PIL import Image
+    import numpy as np
+
+    # PIL image -> numpy array  (H, W, C)
+    im = Image.open("/storage/emulated/0/Download/photo.jpg").convert("RGB")
+    arr = np.asarray(im)
+    print(arr.shape)          # (height, width, 3)
+    print(arr.dtype)          # uint8
+
+    # numpy array -> PIL image
+    img2 = Image.fromarray(arr)
+    img2.save("/storage/emulated/0/Download/out.jpg", quality=95)
+
+    # grayscale -> (H, W)
+    gray = np.asarray(im.convert("L"))
+    # alpha -> (H, W, 4)
+    rgba = np.asarray(im.convert("RGBA"))
+
+    # process with numpy, then convert back
+    arr2 = arr[:, ::-1]                       # mirror
+    arr3 = np.clip(arr.astype(np.int16) + 50, 0, 255).astype(np.uint8)  # brighten
+    arr4 = 255 - arr                          # invert
+    arr5 = arr.copy(); arr5[..., 0] = 255     # force red channel to max
+    Image.fromarray(arr2).save("/storage/emulated/0/Download/mirror.png")
+    Image.fromarray(arr4).save("/storage/emulated/0/Download/invert.png")
+
+    # crop = slice
+    crop = arr[100:200, 50:150]
+    Image.fromarray(crop).save("/storage/emulated/0/Download/crop.png")
+
+    # resize with numpy (nearest) - better to use PIL resize normally
+    small = arr[::4, ::4]                     # nearest-neighbour downsample
+
+    # build a gradient image
+    h, w = 200, 200
+    yy, xx = np.mgrid[0:h, 0:w]
+    grad = np.stack([
+        (xx * 255 // max(1, w - 1)).astype(np.uint8),
+        (yy * 255 // max(1, h - 1)).astype(np.uint8),
+        ((xx + yy) * 255 // max(1, (w + h) - 2)).astype(np.uint8),
+    ], axis=2)
+    Image.fromarray(grad).save("/storage/emulated/0/Download/gradient.png")
+
+    IMPORTANT:
+      np.asarray(im) may share memory with the PIL image. If you modify arr
+      in place (arr[...] = ...), the image changes too. Use arr.copy() when
+      you need an independent buffer.
+      uint8 arithmetic overflows (255+1 -> 0). Cast to int16 first for math:
+      arr.astype(np.int16).
+
+
+--------------------------------------------------------------------------------
+13) PRINTING ARRAYS / MATRICES IN THE TERMINAL
+--------------------------------------------------------------------------------
+
+    a = np.arange(12).reshape(3, 4)
+
+    print(a)                     # default pretty print
+    print(a.tolist())            # as nested Python lists
+
+    # control the output
+    import numpy as np
+    np.set_printoptions(
+        precision=2,             # decimals for floats
+        threshold=20,            # max elements before "..."
+        edgeitems=3,
+        linewidth=120,
+        suppress=True,           # avoid scientific notation for small numbers
+        formatter={"float_kind": lambda v: f"{v:7.2f}"},
+    )
+    print(a)
+
+    # a small helper to show an array as a grid of numbers
+    def print_matrix(m):
+        m = np.asarray(m)
+        for row in m:
+            print(" ".join(f"{v:8.3f}" for v in row))
+
+    print_matrix(np.random.default_rng(1).random((3, 5)))
+
+    # print a 2D array as colored blocks (with ANSI)
+    def print_heatmap(m, cols=40):
+        m = np.asarray(m, dtype=np.float64)
+        if m.ndim != 2:
+            m = m.reshape(m.shape[0], -1)
+        h, w = m.shape
+        # resample columns to terminal width (nearest)
+        if w > cols:
+            m = m[:, ::max(1, w // cols)][:, :cols]
+            h, w = m.shape
+        lo, hi = m.min(), m.max()
+        rng = (hi - lo) or 1.0
+        out = []
+        for row in m:
+            line = ""
+            for v in row:
+                t = (v - lo) / rng            # 0..1
+                r = int(255 * t)
+                g = int(255 * (1 - t))
+                line += f"\x1b[48;2;{r};{g};0m "
+            out.append(line + "\x1b[0m")
+        print("\n".join(out))
+
+    # example: heatmap of a sinc function
+    import numpy as np
+    x = np.linspace(-6, 6, 80)
+    y = np.linspace(-6, 6, 40)
+    yy, xx = np.meshgrid(y, x, indexing="ij")
+    z = np.sinc(np.sqrt(xx ** 2 + yy ** 2))
+    print_heatmap(z, cols=60)
+
+    # ASCII density plot from a 2D array
+    RAMP = " .:-=+*#%@"
+    def print_ascii_grid(m, cols=60):
+        m = np.asarray(m, dtype=np.float64)
+        if w := m.shape[1] > cols:
+            m = m[:, ::w // cols + 1]
+        lo, hi = m.min(), m.max()
+        rng = (hi - lo) or 1.0
+        for row in m:
+            print("".join(RAMP[int((v - lo) / rng * (len(RAMP) - 1))] for v in row))
+
+    print_ascii_grid(z, cols=70)
+
+
+--------------------------------------------------------------------------------
+14) USEFUL EVERYDAY SNIPPETS
+--------------------------------------------------------------------------------
+
+Statistics of a numeric column:
+    data = np.array([1., 2., 3., 4., 100.])
+    print("mean %.2f  std %.2f  median %.2f  min %.0f  max %.0f" % (
+        data.mean(), data.std(), np.median(data), data.min(), data.max()))
+
+Normalize to [0, 1]:
+    x = np.array([3., 1., 2., 0.])
+    n = (x - x.min()) / (x.max() - x.min())
+
+Standard score (z-score):
+    z = (x - x.mean()) / x.std()
+
+One-hot encode categories:
+    cats = np.array([0, 2, 1, 2, 0])
+    onehot = np.eye(3)[cats]
+
+Extract the diagonal of a matrix:
+    np.diag(np.arange(9).reshape(3, 3))        # [0 4 8]
+
+Histogram:
+    values, edges = np.histogram(rng.normal(size=1000), bins=20)
+
+Find the index of the maximum in each row:
+    m = rng.random((5, 8))
+    m.argmax(axis=1)
+
+Clip and cast for image math:
+    arr.astype(np.float32) * 1.2 + 10  -> clip -> uint8
+
+Simple FIR smoothing:
+    kernel = np.ones(5) / 5
+    smooth = np.convolve(signal, kernel, mode="same")
+
+Measure elapsed time:
+    import time
+    t0 = time.perf_counter()
+    ... work ...
+    print("elapsed %.3f s" % (time.perf_counter() - t0))
+
+
+--------------------------------------------------------------------------------
+15) NUMPY + PANDAS / OTHER PACKAGES
+--------------------------------------------------------------------------------
+
+numpy is the foundation for many packages already on the device:
+
+    import numpy as np
+    import pandas as pd
+    df = pd.DataFrame({"a": [1, 2, 3], "b": [4.0, 5.0, 6.0]})
+    print(df)
+    arr = df.to_numpy()          # DataFrame -> numpy array
+    # pandas is built on numpy; everything in this guide applies.
+
+    # OpenCV (if installed) also exchanges buffers directly:
+    # cv2.cvtColor(img_np, cv2.COLOR_BGR2RGB)
+
+
+--------------------------------------------------------------------------------
+16) PITFALLS & NOTES ON THIS BUILD
+--------------------------------------------------------------------------------
+
+- Version is 2.5.2. numpy 2.x changed some 1.x behaviors:
+    * np.array(None) no longer allowed
+    * np.find_common_type removed
+    * copy keyword defaults changed (np.array(..., copy=None) is common)
+  Code written for numpy 1.x may need small fixes.
+- uint8 overflow: cast to a wider dtype before math on images.
+- Integer division: use // for floor, / for true (float) division.
+- Broadcasting: shapes must be equal or one must be 1; (3,1) * (1,4) -> (3,4).
+- np.asarray may share memory with the source (PIL image); use .copy() to
+  detach.
+- OpenBLAS is compiled in - @ and np.linalg.* are fast; no action needed.
+- Wheels here are tagged cp312-cp312-linux_aarch64 / linux_x86_64
+  (this Android build uses the "linux" platform tag for numpy). Make sure you
+  install the wheel that matches the device ABI (arm64 phone vs x86_64 emulator).
+- Temp files are not needed: save directly to /storage/emulated/0/Download/
+  or any folder the app can write.
+- For very large arrays, watch memory: a float64 array of 10M elements uses
+  80 MB. Use float32 or appropriate dtypes when possible.
+- Reinstall safety: keep a copy of the wheel file
+  (numpy-2.5.2-cp312-cp312-linux_aarch64.whl or _x86_64) in
+  /storage/emulated/0/Download/ so you can reinstall if needed.
+
+================================================================================
+  END OF GUIDE
+  Generated by RIMI
+================================================================================