diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d126684..100d2ea 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -102,7 +102,7 @@ jobs: env: # cbgen's bundled zlib needs POSIX declarations on Linux. CFLAGS: ${{ runner.os == 'Linux' && '-D_POSIX_C_SOURCE=200809L' || '' }} - run: uv sync --frozen --all-extras + run: uv sync --frozen --extra dev --extra hdf5 --extra bgen - name: Run the optional BGEN suite run: uv run --frozen --no-sync pytest pysnptools/distreader/test_bgen2.py diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 968c81c..97df25f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -50,7 +50,7 @@ jobs: env: # cbgen's bundled zlib uses POSIX fileno in strict C mode. CFLAGS: -D_POSIX_C_SOURCE=200809L - run: uv sync --frozen --all-extras + run: uv sync --frozen --extra dev --extra hdf5 --extra bgen - name: Run the canonical core suite run: uv run --frozen --no-sync python tests/test.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e258135..7861fd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.1.0a1] - 2026-11-17 + +* Add the `cupy` installation extra, using the published bed-reader 1.3.0a1 + alpha for GPU reads and native allocations. CPU execution remains the + default. Initial GPU support targets Python 3.11 through 3.14 on NVIDIA + Windows/Linux x86-64, including WSL2, following CuPy's CUDA prerequisites. + +* Add `ARRAY_DTYPE` defaults for reads, kernels, submatrix copies, and untyped + containers, with explicit dtype taking precedence. Optional dtype signatures + now default to `None`; the unconfigured float64 defaults are unchanged. + Existing floating arrays and standardizers keep their precision. +* Keep Pheno, Dense, Dat, and Ped text parsing on the CPU until a read chooses + its backend and precision, avoiding GPU allocation during metadata access. + +* Keep newly copied supported GPU subsets in CubeCL-backed storage so fitting + Unit/Beta can use native standardization, including FaST-LMM test-SNP blocks + from preloaded `SnpData`. Preserve caller-owned arrays and shared views. + +* Prefer bed-reader's CubeCL allocator for new supported GPU matrices and kernel + outputs, retaining caller-supplied CuPy storage. Fit Unit/Beta natively only + for complete registered matrices; use CuPy for other arrays/views and applying + trained statistics, without CPU fallback. + Honor empty-container factories so `val=None` retains the intended floating + dtype and backend for empty `SnpData` and `KernelData`. + +* Reject zero, negative, and nonfinite `DiagKtoN` normalization denominators with + `ValueError` before changing values on NumPy or CuPy, including empty inputs. + GPU SNP normalization now propagates NaNs into the denominator rather than + silently ignoring them. + +* Reject invalid kernel block sizes, including negative sizes that previously + could silently produce an all-zero kernel. + +* Apply Unit/Beta trained statistics across float32/float64 CPU arrays in either + memory order, fixing a native type error for Fortran-order targets. + +* Fix blocked kernel construction with `BetaTrained`: validate the complete + SNP ID order, reuse the matching fitted moments in each block, and preserve + the original trained standardizer when returning training information. + +* Fix Python CPU Beta standardization of constant SNPs with singular endpoint + densities (for example, `Beta(0.5, 0.5)`): return zeros without invalid + multiplications during fitting or application of trained statistics. + +* Validate `sub_matrix` indices before conversion on both NumPy and CuPy. + Reject floating-point indices, Boolean masks, invalid shapes, and out-of-range + values with `IndexError` instead of truncating, wrapping, or reaching a native panic. +* Preserve float32/float64 when moving numerical values between NumPy and CuPy. +* Support CuPy arrays in `sub_matrix`, preserving the input device, requested + layout, and dtype; reject negative or out-of-range CuPy indices and warn when + narrowing float64 to float32. +* Support Beta standardization on CuPy and reject wholly missing SNPs when + fitting Python/CuPy Unit or Beta standardizers, matching the native path. +* Add a GPU guide with examples and current backend and reader limitations. + ## [1.0.1] - 2026-11-14 * Make `Hashdown` downloads (used by `example_file`) more robust: retry diff --git a/README.md b/README.md index 9e82e92..676830e 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,11 @@ Main Features: New features include multi-threaded BED reading, cluster-ready BED data, on-the-fly SNP generation, and larger in-memory data. +* **Experimental GPU arrays:** Read, standardize, and construct kernels with CuPy. + `ARRAY_MODULE` and `ARRAY_DTYPE` supply optional backend/precision environment defaults. + See the [GPU guide](https://github.com/fastlmm/PySnpTools/blob/cupy-sub-matrix/doc/source/gpu.rst) and [workflow notebook](https://github.com/fastlmm/PySnpTools/blob/cupy-sub-matrix/doc/ipynb/gpu_workflow.ipynb). + The `cupy` extra uses CUDA-enabled bed-reader wheels for native GPU BED reads. + * [DistReader](https://fastlmm.github.io/PySnpTools/#module-pysnptools.distreader): Efficiently work with unphased BGEN format and other diploid, biallelic distribution data. Also, efficiently read parts of files. See [Distribution IPython Notebook](https://nbviewer.jupyter.org/github/fastlmm/PySnpTools/blob/main/doc/ipynb/Dist.ipynb). @@ -30,6 +35,13 @@ Install Requires Python 3.11.5 or later. Python 3.15 qualification is in progress. +For the experimental GPU alpha: + + pip install "pysnptools[cupy]==1.1.0a1" + +GPU use requires compatible NVIDIA hardware, a driver, and CuPy's CUDA setup. +Python 3.15 is currently CPU-only; see the GPU guide for platform limits. + HDF5 support is optional. To read or write HDF5 files, install: pip install pysnptools[hdf5] diff --git a/doc/ipynb/gpu_workflow.ipynb b/doc/ipynb/gpu_workflow.ipynb new file mode 100644 index 0000000..e495a80 --- /dev/null +++ b/doc/ipynb/gpu_workflow.ipynb @@ -0,0 +1,301 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "3ea2976e", + "metadata": {}, + "source": [ + "# From BED files to GPU kernels and PCA\n", + "\n", + "Read SNP data onto the GPU, build a standardized kernel, and plot the first two principal components.\n", + "\n", + "This requires CuPy, Matplotlib, an NVIDIA GPU (CUDA device 0), and matching development versions of PySnpTools and bed-reader built with the **`cubecl-cuda` Cargo feature**. See the [GPU guide](../source/gpu.rst) for setup.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "717f705d", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "# Default precision for this notebook; explicit dtype arguments can override it.\n", + "os.environ[\"ARRAY_DTYPE\"] = \"float32\"\n", + "\n", + "import cupy as cp\n", + "from bed_reader import has_gpu_support\n", + "\n", + "if not has_gpu_support():\n", + " raise RuntimeError(\"Rebuild bed-reader with the cubecl-cuda Cargo feature\")\n", + "\n", + "device = cp.cuda.runtime.getDeviceProperties(cp.cuda.Device().id)\n", + "print(\"GPU:\", device[\"name\"].decode())\n" + ] + }, + { + "cell_type": "markdown", + "id": "d5ade6d8", + "metadata": {}, + "source": [ + "## Specify the sample data" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "6e294270", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "500 samples × 10000 SNPs\n" + ] + } + ], + "source": [ + "from pysnptools.snpreader import Bed\n", + "from pysnptools.util import example_file\n", + "\n", + "# Download and cache the same toy data used by other PySnpTools examples.\n", + "bed_path = example_file(\"pysnptools/examples/toydata.*\", \"*.bed\")\n", + "bed = Bed(bed_path, count_A1=True)\n", + "print(f\"{bed.iid_count} samples × {bed.sid_count} SNPs\")\n" + ] + }, + { + "cell_type": "markdown", + "id": "1ca321b5", + "metadata": {}, + "source": [ + "## Read onto the GPU\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1ebfb0bb", + "metadata": {}, + "outputs": [], + "source": [ + "from bed_reader import is_cubecl_backed\n", + "\n", + "# xp=cp selects CuPy; use xp=\"numpy\" for a CPU read.\n", + "# float32 arithmetic is usually much faster than float64 on consumer GPUs.\n", + "# This read uses the ARRAY_DTYPE setting from the first cell.\n", + "snps = bed.read(xp=cp)\n", + "print(type(snps.val), snps.val.shape, snps.val.dtype)\n", + "print(\"SNP values:\", \"on GPU:\", f\"{isinstance(snps.val, cp.ndarray)},\",\n", + " \"CubeCL-backed:\", is_cubecl_backed(snps.val))\n", + "# SNP values are on the GPU; sample and SNP metadata stay on the CPU.\n" + ] + }, + { + "cell_type": "markdown", + "id": "f5700b3e", + "metadata": {}, + "source": [ + "## Standardize and build a kernel\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "afc8d995", + "metadata": {}, + "outputs": [], + "source": [ + "from pysnptools.standardizer import Unit\n", + "\n", + "# Unit centers and scales each SNP, then replaces missing values with zero.\n", + "# The kernel is the standardized SNP matrix multiplied by its transpose.\n", + "# Both operations stay on the GPU and use ARRAY_DTYPE.\n", + "kernel = snps.read_kernel(Unit(), xp=cp)\n", + "print(type(kernel.val), kernel.val.shape, kernel.val.dtype)\n", + "print(\"Kernel:\", \"on GPU:\", f\"{isinstance(kernel.val, cp.ndarray)},\",\n", + " \"CubeCL-backed:\", is_cubecl_backed(kernel.val))\n" + ] + }, + { + "cell_type": "markdown", + "id": "8339b131", + "metadata": {}, + "source": [ + "## Run PCA and plot\n" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "ea8e504e", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "PCA coordinates: on GPU: True, CubeCL-backed: False\n" + ] + } + ], + "source": [ + "# CuPy performs the eigendecomposition on the GPU.\n", + "eigenvalues, eigenvectors = cp.linalg.eigh(kernel.val)\n", + "# eigh returns eigenvalues in ascending order; select the largest two.\n", + "coordinates = eigenvectors[:, [-1, -2]] * cp.sqrt(eigenvalues[[-1, -2]])\n", + "\n", + "# New CuPy results can have a different owner; they still live on the GPU.\n", + "print(\"PCA coordinates:\", \"on GPU:\", f\"{isinstance(coordinates, cp.ndarray)},\",\n", + " \"CubeCL-backed:\", is_cubecl_backed(coordinates))\n" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "2ad8875c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Plotting coordinates: on GPU: False, CubeCL-backed: False\n" + ] + }, + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAk0AAAGGCAYAAABmPbWyAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAgTFJREFUeJzt3Xd4VFX6B/DvTMqEDOmUhEgJoRlCC0sTROqKIKCsujQroiiwiqsiCgqioKsuFhQU209ZYHUBpcal2MiCoBAhAtISWhKQdJKQNuf3R7jDlHvvnHvn3ml5P8/j88hkypk75b7znve8x8AYYyCEEEIIIbKM3h4AIYQQQog/oKCJEEIIIYQDBU2EEEIIIRwoaCKEEEII4UBBEyGEEEIIBwqaCCGEEEI4UNBECCGEEMKBgiZCCCGEEA4UNBFCCCGEcKCgiRAPuPXWW5GamurtYajyzDPPIDg42NvD8HvTpk1DdHS0t4fhNUuXLoXBYMC5c+e8PRRCVKOgiQSUn376CXfffTeSkpIQFhaG2NhYdOnSBffddx927twJ212DZsyYAYPBYP0vNDQUbdq0wfTp03Hp0iXr9QYMGID4+HjJxwwLC8OIESN0fV7+4JVXXrE7nsHBwbjuuutw77334vTp007X//XXX3H//fejbdu2CAsLQ5MmTdCzZ08888wzOHXqlOhjvPzyyzAYDOjWrZveT0eVxx9/HGFhYQ1+DFrztefka+MhnkNBEwkY8+fPR79+/RAeHo61a9eioKAAp0+fxjvvvIOysjIMHToUv/zyi9Pt8vLywBhDQUEBXn31VXz66acYMmQIampqvPAs/N++ffvAGENZWRlWrFiBrVu3on///iguLrZe591330XPnj1RUVGBNWvWoLCwECdOnMDzzz+P9PR0jBs3zul+GWP4+OOPcd111+HgwYPYu3evB58VIYRQ0EQCxMqVK7FgwQK8+uqreP/995GWlgaz2YyIiAgMGjQIa9euxaeffoqQkBDJ+4iIiMBf//pXTJ8+HYcOHcL27ds9+AwCT6NGjXDLLbdg7ty5OH/+PL788ksAwM6dOzFz5kxMmzYN//73v9G7d2+Eh4cjOjoaY8eOxb59+3DnnXc63d+OHTtw6tQpfPLJJ0hMTMSKFSs8/ZQIIQ0cBU0kIMyfPx+tWrXC3//+d8nr3HvvvVzTOp06dQIAnD17VrPxidmxYwdiYmJw66234vLlywCAkpISPPnkk2jbti1CQ0ORkJCARx55BEVFRdbbbdq0CQaDAbt27cIbb7yBpKQkBAUF4cSJE9a6mcuXL+OBBx5AdHQ0oqOjcffdd6O0tNRpDL/99hvuvPNONG3aFCaTCddffz3efvttTZ+n4/F88cUXER4ejkWLFolePyQkBM8995zT5StWrEBKSgqGDRuGqVOnYs2aNdbjxmPnzp0YPHgwIiIiEB4ejj59+mDdunV211F6/GzddttteOutt1BVVWU3TZmTk2N3PT1fG54xuDoOb731FgwGAzIzM53uf9myZTAYDC6zfOvWrUPXrl0RFhaGTp06Yc2aNaLXe/PNN+3GGRkZiZtuuglbt27lfk489wEAp06dwsSJE5GYmIjw8HCkpqbipZdeQkVFhd31XB133teZBChGiJ87fvw4A8CmTJmi6HbTp09nAFheXp7d5U8//TQDwLZs2cIYY6x///6sefPmkvdjMpnYzTffLPtYo0aNYp07d7b+e8WKFSw4OJjNnDmT1dbWMsYYKy0tZV26dGHt2rVj27ZtY2VlZWz//v2se/fuLC0tjVVVVTHGGNu4cSMDwP7yl7+wRYsWsQsXLrCtW7eynJwc9vDDD7OoqCh23333sc2bN7PS0lKWnp7OIiIi2MMPP2w3pp9++omFh4ezsWPHssOHD7PS0lL25ZdfssjISDZ79mzr9WbPns2CgoJcHs/FixczAGzfvn12l7/99tsMAPvggw9YWVkZCwoKYn/+859d3p+tP/74g4WGhrJ33nmHMcZYbm4uCw4OZitWrOC6/YYNG5jRaGT33nsvy8nJYbm5ueypp55iANjy5cut11Ny/MQ89thjzGQyif5Nj9dG6Rh4jkNxcTEzm81s6tSpTrfv0qULS01NlX38tWvXMoPBwGbOnMnOnz/Pzpw5w6ZMmcLGjh3LALCzZ8+K3q6uro7l5OSwxx57jIWEhLBffvmF6znx3kf79u3ZoEGD2NGjR1llZSU7cuQIe/7559mqVaus1+E97rzjIYGHgibi93bs2MEAsPnz5yu6nWPQVFZWxr744gtmNptZSkqKNUjRMmiqq6tjTz75JAsKCmJLly61u86CBQuYwWBgv/76q93lR44cYQaDgX3yySeMsWtB05133un0OA8//DADwL744gu7y2fOnMlCQ0NZ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qPXfjDH8/vvvqK2txfXXX6/4GFDQRAghhBDCITDCbEIIIYQQnVHQRAghhBDCgYImQgghhBAOFDQRQgghhHCgoIkQQgghhAMFTYQQQgghHChoIoQQQgjhQHvPEUICTnp6OoqLiwHU72Letm1b655jtiorK/Hzzz+joKAA1113HVJSUhAeHu50vT179iAnJwejRo1CRESE3sMnhPgoam5JCAk4qampqK2tRffu3VFRUYFdu3YhJSUFW7ZssXbHfv3117Fw4UIkJSUhKSkJubm5yMvLwxNPPIHHH38cALBu3TrMnz8fV65cwfHjx3HkyBF06tTJi8+MEOJNlGkihASkW2+9Fa+//joA4Pz58+jcuTMWL16MxYsX46WXXsKiRYvw1Vdf4c9//rP1NiUlJdiwYYP131VVVVi5ciWqq6vRq1cvjz8HQohvoZomQkjAS0xMRK9evZCZmYmioiIsWrQIs2bNsguYACAqKgp333239d8TJkxA165dPT1cQoiPoqCJEBLw6urqcOrUKSQkJOCHH35AZWUlxo0b5+1hEUL8DE3PEUIC0u+//441a9agsrISa9euRW5uLh577DHs2bMHANCqVSsvj5AQ4m8o00QICUjHjx/HV199he+//x69evXCkSNH0K1bN+vqt4KCAi+PkBDibyjTRAgJSLaF4LaEgu49e/bQSjhCiCKUaSKENCjt27fH6NGjsWDBAhQVFTn9/cyZM14YFSHEH1CmiRDS4HzyyScYPXo0unbtigcffNDap+l///sfgoKCsH79egDAkSNH8Ouvv+LUqVMAgC1btiAzMxO9evVCcnKyN58CIcQLqLklISTgPPXUU+jevTsmTZokeR2LxYItW7Zg586d1o7gAwYMwC233GK9zoYNG7Bq1Sqn2z744IMYNmyYLmMnhPguCpoIIYQQQjhQTRMhhBBCCAcKmgghhBBCOFDQRAghhBDCgYImQgghhBAOFDQRQgghhHCgoIkQQgghhAMFTYQQQgghHChoIoQQQgjhQEETIYQQQggHCpoIIYQQQjhQ0EQIIYQQwoGCJkIIIYQQDv8PUn27NutGmpsAAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "# Copy only the two plotting coordinates per sample back to the CPU.\n", + "coordinates_cpu = cp.asnumpy(coordinates)\n", + "print(\"Plotting coordinates:\", \"on GPU:\", f\"{isinstance(coordinates_cpu, cp.ndarray)},\",\n", + " \"CubeCL-backed:\", is_cubecl_backed(coordinates_cpu))\n", + "figure, axes = plt.subplots(figsize=(6, 4))\n", + "axes.scatter(coordinates_cpu[:, 0], coordinates_cpu[:, 1])\n", + "axes.set(xlabel=\"PC1\", ylabel=\"PC2\", title=\"GPU kernel PCA on the toy dataset\")\n", + "figure.tight_layout()\n", + "plt.show()\n", + "# Eigenvector signs are arbitrary; the plot may be reflected on another run.\n" + ] + }, + { + "cell_type": "markdown", + "id": "6a4e27f4", + "metadata": {}, + "source": [ + "## Compare kernel creation times\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a074e0b3", + "metadata": {}, + "outputs": [], + "source": [ + "# High-resolution elapsed-time clock, used only for this benchmark.\n", + "from time import perf_counter\n", + "\n", + "import numpy as np\n", + "from pysnptools.snpreader import SnpData\n", + "from pysnptools.standardizer import Identity\n", + "\n", + "# Compare Unit standardization + Z @ Z.T, using the same data and the notebook's ARRAY_DTYPE setting.\n", + "# File reads and case setup are outside the timings; restoring inputs is included.\n", + "cell_started = perf_counter()\n", + "cpu = bed.read(xp=np)\n", + "original_gpu = cp.array(cpu.val)\n", + "# Normal GPU copies prefer CubeCL-backed memory. For cp-basic, explicitly\n", + "# supply a CuPy allocation; SnpData preserves an existing compatible array.\n", + "cases = [\n", + " # Read from in-memory SnpData to get a fresh copy, not from the BED file.\n", + " (\"np\", np, cpu.read(xp=np)),\n", + " (\"cp-basic\", cp, SnpData(iid=cpu.iid, sid=cpu.sid, pos=cpu.pos,\n", + " val=cp.array(cpu.val), xp=cp)),\n", + " # Get a fresh GPU copy of the same in-memory SNP data.\n", + " (\"cp-cubecl\", cp, cpu.read(xp=cp)),\n", + "]\n", + "assert not is_cubecl_backed(cases[1][2].val)\n", + "assert is_cubecl_backed(cases[2][2].val)\n", + "\n", + "def time_batch(data, xp, repetitions):\n", + " if xp is cp:\n", + " # Timing only: exclude earlier GPU work from this batch.\n", + " cp.cuda.runtime.deviceSynchronize()\n", + " started = perf_counter()\n", + " for repetition in range(repetitions):\n", + " # Standardization modifies values, so restore the original SNP values.\n", + " xp.copyto(data.val, cpu.val if xp is np else original_gpu)\n", + " data.standardize(Unit())\n", + " # Already standardized: Identity avoids standardizing a second time.\n", + " product = data.read_kernel(Identity(), xp=xp)\n", + " del product\n", + " if xp is cp:\n", + " # Timing only: wait once for the batch, rather than after every operation.\n", + " # Normal API use handles its own coordination for correct results.\n", + " cp.cuda.runtime.deviceSynchronize()\n", + " return perf_counter() - started\n", + "\n", + "\n", + "# Aim for ~0.8 seconds per backend, keeping the whole cell around 3–4 seconds.\n", + "# Warm up first, then estimate how many repetitions each backend needs.\n", + "results = []\n", + "for label, xp, data in cases:\n", + " time_batch(data, xp, 1)\n", + " seconds_per_kernel = time_batch(data, xp, 2) / 2\n", + " repetitions = max(1, int(0.8 / seconds_per_kernel))\n", + " duration = time_batch(data, xp, repetitions)\n", + " results.append((label, duration * 1000 / repetitions,\n", + " isinstance(data.val, cp.ndarray), is_cubecl_backed(data.val)))\n", + "\n", + "# Compare the time for the same work, independent of calibration batch sizes.\n", + "cpu_milliseconds = results[0][1]\n", + "print(\"Kernel creation: Unit standardization + matrix multiplication (including input reset)\")\n", + "print(f\"{'Backend':<12} {'ms/kernel':>10} {'Speedup vs CPU':>15} {'On GPU':>8} {'CubeCL input':>14}\")\n", + "for label, milliseconds, on_gpu, cubecl_backed in results:\n", + " speedup = f\"{cpu_milliseconds / milliseconds:.1f}x\"\n", + " print(f\"{label:<12} {milliseconds:>10.2f} {speedup:>15} \"\n", + " f\"{'yes' if on_gpu else 'no':>8} {'yes' if cubecl_backed else 'no':>14}\")\n", + "print(f\"Whole timing cell: {perf_counter() - cell_started:.2f} s\")\n", + "\n", + "# cp-basic uses CuPy standardization; cp-cubecl uses native CubeCL standardization.\n", + "# Both use our read_kernel API, with CuPy multiplication and CubeCL-backed output.\n", + "del cases, data, cpu, original_gpu\n" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": ".venv-bed-reader-gpu (3.13.13)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/source/gpu-api-preview.rst b/doc/source/gpu-api-preview.rst new file mode 100644 index 0000000..63806c2 --- /dev/null +++ b/doc/source/gpu-api-preview.rst @@ -0,0 +1,7 @@ +GPU reader API +============== + +The reader API is documented in :doc:`gpu`, with complete executable examples +for explicit backend selection, standardization, native BED reads, and kernels. +The API is part of the current development implementation; this page retains +its earlier URL for existing links. diff --git a/doc/source/gpu.rst b/doc/source/gpu.rst new file mode 100644 index 0000000..a068daa --- /dev/null +++ b/doc/source/gpu.rst @@ -0,0 +1,409 @@ +GPU arrays, readers, and standardization +======================================== + +This guide describes the ``1.1.0a1`` alpha, including the reader GPU API. It +requires bed-reader 1.3.0a1 or later. NumPy runs on the CPU. CuPy support here is +experimental NVIDIA CUDA support; Python HIP support is not implemented. + +Installing the alpha +-------------------- + +The alpha is available on PyPI. Explicitly select it: + +.. code-block:: bash + + pip install "pysnptools[cupy]==1.1.0a1" + # Or, in an existing uv environment: + uv pip install "pysnptools[cupy]==1.1.0a1" + +The extra installs CuPy through ``bed-reader[cupy]``. It follows CuPy's CUDA 13 +driver/toolkit prerequisites; a prebuilt bed-reader wheel does not require +Rust or Maturin. See +`bed-reader's GPU guide `_ +for system-toolkit and pip-managed CUDA options. Initial GPU qualification is +Python 3.11 through 3.14 on NVIDIA Windows/Linux x86-64, including WSL2. +Python 3.15 is currently CPU-only because CuPy 14.2 has no wheel for it. +Linux GPU wheels require glibc 2.35 or later. The published alpha stack passed +native Linux GPU integration tests on Ubuntu 24.04 x86-64 with an RTX 3060, +Python 3.11, and CUDA toolkit 13.3, in addition to WSL2 testing. CPU wheels also cover +Intel Mac, Apple silicon, Linux ARM64, and Windows ARM64; these platforms do not +gain Python GPU support. Normal unpinned installations continue selecting stable +releases. Omit ``[cupy]`` for a CPU-only installation of the alpha. + +The :download:`GPU workflow notebook <../ipynb/gpu_workflow.ipynb>` +uses existing sample BED data to demonstrate GPU reads, standardized kernels, +PCA, and a comparison of NumPy and CuPy kernel construction. + +Backend, dtype, and order +------------------------- + +An explicit ``xp=np``, ``xp=cp``, ``xp="numpy"``, or ``xp="cupy"`` overrides +``ARRAY_MODULE``. Only ``xp=None`` consults that environment variable; absent +both, NumPy is used. Missing CuPy raises ``ImportError``. An unknown module name +raises ``ValueError``; a successful CuPy import does not establish driver or +hardware availability. There is no automatic CPU retry after a GPU error. + +``ARRAY_DTYPE`` supplies a shared precision default for reads, kernels, GPU +allocation, and untyped/list construction. Explicit dtype wins; None or omission +uses this environment variable, then each API's original default. PySnpTools +reads default to float64 without the variable (bed-reader reads default to +float32). Only float32 and float64 are accepted as environment defaults. Existing +floating arrays and standardizers keep their dtype; writers keep their existing +storage/inference rules. NumPy/CuPy functions do not consult this variable. + +Set backend and precision together for a workflow:: + + from unittest.mock import patch + from pysnptools.snpreader import Bed + from pysnptools.standardizer import Unit + from pysnptools.util import example_file + + bed = Bed(example_file("pysnptools/examples/toydata.*", "*.bed"), count_A1=True)[:40, :60] + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy", "ARRAY_DTYPE": "float32"}): + values = bed.read() + kernel = values.read_kernel(Unit()) + assert values.val.dtype.name == kernel.val.dtype.name == "float32" + precise = bed[:2, :3].read(dtype="float64") # explicit override + assert precise.val.dtype.name == "float64" + # Previous settings are restored, even after an exception. + +These environment settings are process-wide; use one consistent policy per +process. This policy requires the alpha versions described above; older +dependencies retain their original defaults but reject +ARRAY_DTYPE rather than silently ignoring it. + +Float64 arithmetic can be much slower than float32 on consumer GPUs; devices +with strong float64 hardware can behave differently. Float64 storage also uses +twice the memory. GPU float64 reads, allocations, and standardization emit +bed-reader's ``GpuFloat64Warning`` (a ``UserWarning``). +Warnings preserve the requested dtype and defaults. Nested library calls point +to the user's call, so Python's default warning filter avoids repeated messages +at that call site. Caller-owned float64 arrays are also covered when standardized. + +For example, use ``reader.read(dtype="float32", xp="cupy")`` when adequate; +omitted dtype uses ARRAY_DTYPE, then float64, even for float32 in-memory sources. Keep +float64 when numerical accuracy requires it, and validate representative results +before switching. CPU float64 and internal float64 reductions for float32 input +do not emit this warning. Float32 storage does not remove every float64 operation. + +.. list-table:: Reader and constructor options + :header-rows: 1 + :widths: 24 22 54 + + * - API or option + - Default + - Behavior + * - ``SnpData(..., xp=...)``, ``KernelData(..., xp=...)`` + - ``xp=None`` + - Selects the module for values; metadata remains NumPy. Float32/float64 + inputs keep their dtype across transfers. Lists and integers normally + use ARRAY_DTYPE, then float64. Same-module floating arrays can share storage. + * - ``SnpReader.read``, ``KernelReader.read`` + - ``xp=None``, ``dtype=None``, ``order="F"`` + - Return ``SnpData`` or ``KernelData``. Every read chooses its backend + independently of the constructor. None uses ARRAY_DTYPE, then float64, + independently of the source dtype. Explicit dtype overrides the environment. + * - ``SnpReader.read_kernel`` + - ``standardizer=None``, ``block_size=None``, ``order="A"`` + - A standardizer is required despite the ``None`` signature default; + omitting it raises ``AssertionError``. Returns ``KernelData``. + Omitted dtype uses ARRAY_DTYPE, then float64; ``xp=None`` uses ARRAY_MODULE. + * - ``order`` + - As above + - ``F`` varies the first index fastest; ``C`` varies the last index + fastest. ``A`` allows the reader to choose. BED maps ``A`` to ``F``; + blocked kernel accumulation maps ``A`` to ``C``. + * - ``view_ok`` + - ``False`` + - Allows sharing when practical for in-memory reads; it does not guarantee + a view. BED reads and kernel products allocate output regardless. + * - ``num_threads`` + - ``None`` + - CPU thread count, also controlled by ``PST_NUM_THREADS``, ``NUM_THREADS``, + then ``MKL_NUM_THREADS``. Ignored by native GPU BED decoding and CuPy math. + * - ``force_python_only`` on reads + - ``False`` + - Selects a CPU reader's Python path where supported. Native GPU BED reads + reject ``True`` with ``ValueError``; it does not select a CPU backend. + +Ordinary numerical reads and standardization support float32 and float64. +BED also supports ``dtype="int8", _require_float32_64=False`` (missing = -127); +int8 data must be converted to floating point before standardization. Float16 +is not a supported numerical read dtype. In-memory constructors preserve array +dtypes, not an arbitrary requested layout; use ``read(order=..., dtype=..., xp=...)`` +for explicit output requirements. Dense kernels have shape samples by samples. + +When new storage is needed for a supported 2-D matrix on CUDA device 0, +PySnpTools prefers bed-reader's ``empty_gpu`` allocator when available. This +includes CPU-to-GPU construction, read copies/conversions and copied subsets, +and kernel outputs. These are ordinary CuPy arrays backed by CubeCL memory. +Caller-supplied CuPy arrays retain their storage when no conversion is needed; +PySnpTools does not copy them merely to change ownership. To choose a CuPy +allocator yourself, create the CuPy array first and pass it to the constructor. + +CuPy-only builds, other devices/ranks/dtypes, and direct CuPy operations (such +as ``values[index]``) continue using CuPy storage. PySnpTools copies a supported +2-D subset into its final CubeCL allocation after gathering on the GPU. Shared +views keep their original allocation; no complete matrix is standardized +through a partial view. +Unavailable native allocation does not move computation to the CPU. An error +from an allocator that was selected propagates without retrying another one. +When an array backed by bed-reader and all its views are dropped, bed-reader +returns its memory to CUDA, where CuPy and other libraries can use it. + +The following complete example checks both directions of environment overrides, +actual array types, dtype, order, and a duplicate-preserving subset. It needs +CuPy and a working GPU, but no native BED GPU build or data download:: + + import cupy as cp + import numpy as np + from unittest.mock import patch + from pysnptools.snpreader import SnpData + from pysnptools.util import asnumpy, sub_matrix + + assert cp.cuda.runtime.getDeviceCount() > 0 + cp.zeros(1).sum().item() + values = np.array([[0, 2], [1, 1], [2, 0]], dtype=np.float32) + data = SnpData(iid=[["family", str(sample)] for sample in range(3)], + sid=["snp0", "snp1"], val=values.copy(), xp=np) + with patch.dict("os.environ", {"ARRAY_MODULE": "numpy"}): + gpu = data.read(dtype="float32", order="C", xp=cp) + subset = gpu[[2, 0, 2], :].read(dtype="float32", order="F", xp=cp) + subset.standardize() # uses CuPy despite ARRAY_MODULE=numpy + assert isinstance(gpu.val, cp.ndarray) and gpu.val.flags.c_contiguous + assert isinstance(subset.val, cp.ndarray) and subset.val.flags.f_contiguous + assert subset.val.dtype == np.float32 + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + host = gpu.read(dtype="float32", order="F", xp=np) + host.standardize() # stays on NumPy + assert isinstance(host.val, np.ndarray) and host.val.flags.f_contiguous + assert host.val.dtype == np.float32 + selected = sub_matrix(gpu.val, [2, 0, 2], [1, 0], dtype=gpu.val.dtype) + assert isinstance(selected, cp.ndarray) and selected.dtype == np.float32 + np.testing.assert_array_equal(asnumpy(selected), values[[2, 0, 2]][:, [1, 0]]) + +``sub_matrix`` chooses from the actual input array, independently of the +environment. It accepts contiguous 2-D/3-D float32/float64 arrays and +one-dimensional integer index sequences, preserving order and duplicates. +It rejects negative, out-of-range, floating-point, and Boolean indices with +``IndexError``. Reader slicing also accepts slices and Boolean masks. +``sub_matrix`` uses ARRAY_DTYPE, then float64: pass ``dtype=values.dtype`` to keep float32. +Narrowing float64 to float32 warns of precision loss. ``asnumpy`` copies a CuPy +array to the host and returns a NumPy array unchanged. + +Standardization and trained statistics +-------------------------------------- + +Unit and Beta modify values in place on their existing device; they do not +consult ``ARRAY_MODULE``. Values must be contiguous floating-point arrays. +Fitting uses CubeCL kernels for a complete registered native matrix (including +an identical full view) within the +native indexing limits; other arrays and views use CuPy kernels. Shape, strides, +dtype, device, and allocation identity must match before native dispatch, so a +slice or transpose cannot accidentally standardize the larger owner. Applying +trained moments uses CuPy without refitting. Both paths preserve the same +missing-value, constant-column, dtype, and ordering semantics. +``return_trained=True`` returns ``(data, trained_standardizer)``; otherwise the +return is the same data object. Training through Unit/Beta returns NumPy +``trained.stats`` with shape ``(sid_count, 2)``: mean and population standard +deviation (``ddof=0``), in the input floating dtype. Even GPU training transfers +these small per-SNP statistics to the CPU. + +Applying trained statistics converts a working copy to the target array's +floating dtype where needed; it does not change the original trained statistics. +Using a float64 target cannot restore precision lost during float32 training. + +.. list-table:: Standardizer behavior + :header-rows: 1 + :widths: 23 77 + + * - Standardizer + - Behavior + * - ``Unit()`` + - Subtract the observed mean and divide by the observed population + standard deviation. Impute NaNs with zero afterward. The final column + variance is generally below one when observations are missing; a + constant column becomes zero. + * - ``Beta(a, b)`` + - Center and multiply by the beta density at the minor allele frequency + ``min(mean / 2, 1 - mean / 2)``; do not divide by standard deviation. + Native and CuPy paths validate means in [0, 2] and beta parameters. + CuPy reduces on the GPU but evaluates the per-SNP density with SciPy + on the CPU, then transfers weights back. + * - ``UnitTrained`` + - Reuse fitted moments. Can select/reorder known SNP IDs automatically; + an unknown ID raises ``KeyError``. Unique training IDs avoid ambiguity. + * - ``BetaTrained`` + - Reuse fitted moments and beta parameters. Requires exactly the same + SNP IDs in the same order; a mismatch raises ``AssertionError``. + Kernel construction checks the full SNP IDs/order, then reuses the + corresponding fitted moments for each block without refitting them. + +Fitting a wholly missing SNP raises ``ValueError``. Applying already-trained +moments does not refit or require an observation: an all-NaN test column becomes +zero. A constant training SNP stores infinite standard deviation and remains +zero in test data even if its new values vary. Unit accepts general finite +values, including negative values; Beta is for allele counts/dosages with valid +allele-frequency means. CPU and GPU rounding need not be identical, especially +for large offsets and small variance. + +For Unit/Beta standardizer methods, ``block_size`` is deprecated, ignored, and +warns when supplied directly. ``SnpData.standardize(block_size=...)`` currently +ignores it without forwarding a warning. ``force_python_only=True`` selects the +NumPy implementation on CPU but is ignored for CuPy arrays; it never transfers +them to the CPU. ``num_threads`` applies to native CPU standardization and is +ignored for CuPy. Constant training columns receive zero Beta weight before +multiplication, including when the beta density is infinite at allele-frequency +endpoints. This applies to both native and Python CPU execution. + +This independent example exercises training, imputation, constant columns, and +applying training moments to different values, on both devices:: + + import cupy as cp + import numpy as np + from pysnptools.snpreader import SnpData + from pysnptools.standardizer import Unit, Beta + from pysnptools.util import asnumpy + + iid = [["family", str(sample)] for sample in range(3)] + sid = ["varying", "constant", "missing"] + values = np.array([[0, 1, 0], [1, 1, np.nan], [2, 1, 2]], dtype=np.float32) + for xp in (np, cp): + for standardizer in (Unit(), Beta(1, 25)): + data = SnpData(iid=iid, sid=sid, val=xp.array(values, order="F"), xp=xp) + result, trained = data.standardize(standardizer, return_trained=True) + assert result is data and isinstance(data.val, xp.ndarray) + assert data.val.dtype == np.float32 and data.val.flags.f_contiguous + assert isinstance(trained.stats, np.ndarray) + assert np.isinf(trained.stats[1, 1]) + np.testing.assert_array_equal(asnumpy(data.val)[:, 1], 0) + assert float(data.val[1, 2]) == 0 + reordered = SnpData(iid=iid, sid=[sid[2], sid[0]], + val=xp.array(values[:, [2, 0]], order="C"), xp=xp) + if isinstance(standardizer, Unit): + reordered.standardize(trained) # UnitTrained remaps known IDs + np.testing.assert_allclose(asnumpy(reordered.val), + asnumpy(data.val)[:, [2, 0]], rtol=1e-6, atol=1e-6) + else: + try: + reordered.standardize(trained) + except AssertionError: + pass # BetaTrained requires exact IDs/order + else: + raise AssertionError("BetaTrained must reject reordered IDs") + missing_test = SnpData(iid=iid, sid=sid, + val=xp.full((3, 3), xp.nan, dtype=xp.float32), xp=xp) + missing_test.standardize(trained) # applying moments does not refit + np.testing.assert_array_equal(asnumpy(missing_test.val), 0) + changed = values.copy() + changed[:, 1] = [0, 1, 2] + fresh = SnpData(iid=iid, sid=sid, val=xp.array(changed, order="F"), xp=xp) + fresh.standardize(trained) + tolerance = 32 * np.finfo(np.float32).eps # small, well-scaled example + np.testing.assert_allclose(asnumpy(fresh.val), asnumpy(data.val), + rtol=tolerance, atol=tolerance) + kernel_source = SnpData(iid=iid, sid=sid, + val=xp.array(changed, order="F"), xp=xp) + unblocked = kernel_source.read_kernel(trained, dtype="float32", xp=xp) + blocked = kernel_source.read_kernel(trained, block_size=2, + dtype="float32", xp=xp) + assert isinstance(blocked.val, xp.ndarray) and blocked.val.dtype == np.float32 + expected_kernel = asnumpy(unblocked.val) + np.testing.assert_allclose(asnumpy(blocked.val), expected_kernel, + rtol=tolerance, + atol=tolerance * np.max(np.abs(expected_kernel))) + empty = SnpData(iid=iid, sid=["empty"], + val=xp.full((3, 1), xp.nan, dtype=xp.float32), xp=xp) + try: + empty.standardize(standardizer) + except ValueError as error: + assert "No individual observed" in str(error) + else: + raise AssertionError("wholly missing training SNP must fail") + +Native GPU BED reads and kernel construction +-------------------------------------------- + +GPU BED decoding requires the matching bed-reader Python extension built with +the ``cubecl-cuda`` Cargo feature, CuPy, a working CUDA driver, and a supported NVIDIA GPU. +``bed_reader.has_gpu_support()`` reports the compiled capability, not runtime +health. Prebuilt CPU wheels are not sufficient; there is no PySnpTools GPU extra. +Native BED reads currently use CUDA device 0; ``xp`` selects the array module, +not a device number. Use CuPy on the same device for this workflow. Standardization +of an existing CuPy array follows that array's device. +Metadata stays on the CPU. Native GPU reads expose Rust-owned device memory +through CuPy, whose views keep that owner alive. + +Missing native GPU support raises ``RuntimeError``. Native reads also reject +``force_python_only=True`` and unsupported dtypes/orders with ``ValueError``. +Other file formats can read on CPU and then transfer values; requesting CuPy +does not promise native GPU I/O for every reader. Custom standardizers must +support the chosen array module. + +This complete example creates its own BED/BIM/FAM files. It checks selected +values, int8 missing representation, and blocked Unit/Beta kernels against +independent NumPy products. Kernel construction uses an internal fused BED +read/standardize operation; callers use the public read methods:: + + import cupy as cp + import numpy as np + from pathlib import Path + from tempfile import TemporaryDirectory + from bed_reader import has_gpu_support, to_bed + from pysnptools.snpreader import Bed + from pysnptools.standardizer import Unit, Beta + + if not has_gpu_support(): + raise RuntimeError("this example requires a bed-reader build with the cubecl-cuda Cargo feature") + rng = np.random.default_rng(19) + values = rng.integers(0, 3, size=(12, 9)).astype(np.float64) + values[0, 0] = np.nan + with TemporaryDirectory() as directory: + path = Path(directory) / "cohort.bed" + to_bed(path, values, count_A1=True) + bed = Bed(path, count_A1=True) + data = bed[[4, 1, 4], :].read(dtype="float32", order="F", xp=cp) + assert isinstance(data.val, cp.ndarray) and data.val.flags.f_contiguous + assert data.val.dtype == np.float32 + np.testing.assert_array_equal(cp.asnumpy(data.val), values[[4, 1, 4]]) + integer = bed.read(dtype="int8", _require_float32_64=False, xp=cp) + assert isinstance(integer.val, cp.ndarray) and integer.val.dtype == np.int8 + assert int(integer.val[0, 0]) == -127 + for standardizer in (Unit(), Beta(1, 25)): + cpu = bed.read(dtype="float32", xp=np).standardize(standardizer) + kernel = bed.read_kernel(standardizer, block_size=3, dtype="float32", + order="C", xp=cp) + assert isinstance(kernel.val, cp.ndarray) + assert kernel.val.dtype == np.float32 and kernel.val.flags.c_contiguous + # Three blocks of well-scaled float32 values accumulate roundoff. + tolerance = 64 * np.finfo(np.float32).eps + np.testing.assert_allclose(cp.asnumpy(kernel.val), cpu.val @ cpu.val.T, + rtol=tolerance, atol=tolerance * bed.sid_count) + host_kernel = kernel.read(dtype="float32", order="F", xp=np) + assert isinstance(host_kernel.val, np.ndarray) + assert host_kernel.val.dtype == np.float32 and host_kernel.val.flags.f_contiguous + +``read_kernel(Unit())`` returns the product of standardized SNPs and their +transpose. It does not normalize the average diagonal to one; apply +``kernel.standardize()`` separately for that. Fitting ``DiagKtoN`` requires a +finite, positive trace (or sum of squared SNP values). Zero, negative, or +nonfinite denominators and empty inputs raise ``ValueError`` on either device +before values change. NaNs are not imputed by this scalar normalization; use +Unit/Beta first when imputation is needed. Applying an already-trained +``DiagKtoN`` scale does not refit it, so zero test data remains zero. + +The requested positive integer +``block_size`` limits each SNP block, including when SNPs are fewer than samples; +``None`` loads all SNPs. Invalid block sizes, including Booleans and negative +values, raise ``ValueError``. It is not a total memory budget. The dense kernel, +CuPy/CubeCL allocator pools, multiplication temporaries, and downstream solver +workspaces also use GPU memory. A lazy ``SnpKernel`` subset can still construct +the full kernel before selecting its rectangle. Native GPU BED buffers are +limited to ``2**32 - 1`` elements, with further native standardization index +limits; these are indexing limits, not claims that the device has that memory. + +PySnpTools forms GPU products and kernel accumulations in the requested floating +dtype, while standardization can use float64 reductions. An output dtype does +not describe every intermediate. A read's ``view_ok`` cannot make a matrix +product into a view. Allocation and CUDA errors propagate rather than selecting +a different backend or reducing the problem silently. diff --git a/doc/source/index.rst b/doc/source/index.rst index 598dd40..0d57f91 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,11 @@ Core Python 3.15 qualification excludes both backends; HDF5 and BGEN remain covered by the Python 3.11 through 3.14 test matrix. +NumPy is the default backend. The development GPU API supports explicit CuPy +reads and device-preserving standardization. ARRAY_MODULE and ARRAY_DTYPE +supply backend/precision defaults when their arguments are omitted; see :doc:`gpu` for prerequisites, +options, exceptions, and complete examples. + :Synopsis: * :mod:`.snpreader`: Efficiently read genetic PLINK formats including \*.bed/bim/fam and phenotype files. Also, efficiently read *parts* of files and standardize data. @@ -51,6 +56,17 @@ covered by the Python 3.11 through 3.14 test matrix. * IPython Notebooks * `General Notebook `_ * `Distribution Notebook `_ + * :download:`GPU workflow notebook <../ipynb/gpu_workflow.ipynb>` (development): BED reads, dosages, trained statistics, blocked kernels, and PCA. + +.. toctree:: + :maxdepth: 2 + + gpu + +.. toctree:: + :hidden: + + gpu-api-preview :Code: @@ -552,6 +568,8 @@ covered by the Python 3.11 through 3.14 test matrix. :undoc-members: :show-inheritance: +.. autofunction:: pysnptools.util.array_dtype + .. autofunction:: pysnptools.util.example_file .. autofunction:: pysnptools.util.snp_gen diff --git a/pyproject.toml b/pyproject.toml index 3c5f4ce..7504f0c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "uv_build" [project] name = "pysnptools" -version = "1.0.1" +version = "1.1.0a1" description = "PySnpTools" readme = "README.md" requires-python = ">=3.11.5" @@ -55,7 +55,10 @@ dependencies = [ # current binary dependencies separately from the optional-feature lock. "pandas>=2.3.3,<4; python_version >= '3.14'", "cloudpickle>=3.1.0", - "bed-reader[samples]>=1.2.0", + # Version 3.5 added Scientific Python OpenBLAS support; 3.8 supports Python 3.15. + "threadpoolctl>=3.5.0; python_version < '3.15'", + "threadpoolctl>=3.8.0; python_version >= '3.15'", + "bed-reader[samples]>=1.3.0a1", "more-itertools>=10.5.0", ] @@ -67,6 +70,7 @@ Source = "https://github.com/fastlmm/PySnpTools" [project.optional-dependencies] +cupy = ["bed-reader[cupy]>=1.3.0a1"] hdf5 = [ "h5py>=3.12.1; python_version < '3.14'", # h5py 3.15.0 is the first release with Python 3.14 wheels. diff --git a/pysnptools/distreader/bgen.py b/pysnptools/distreader/bgen.py index 7c3fcbe..6d4ab17 100644 --- a/pysnptools/distreader/bgen.py +++ b/pysnptools/distreader/bgen.py @@ -869,63 +869,63 @@ def sid_function(id, rsid): def test_bgen_samples_inside_bgen(self): from bgen_reader import example_filepath - with example_filepath("example.32bits.bgen") as filepath: - data = Bgen(filepath) - samples = [ - ("0", "sample_001"), - ("0", "sample_002"), - ("0", "sample_003"), - ("0", "sample_004"), - ] - assert (data.iid[:4] == samples).all() + filepath = example_filepath("example.32bits.bgen") + data = Bgen(filepath) + samples = [ + ("0", "sample_001"), + ("0", "sample_002"), + ("0", "sample_003"), + ("0", "sample_004"), + ] + assert (data.iid[:4] == samples).all() def test_bgen_reader_variants_info(self): from bgen_reader import example_filepath - with example_filepath("example.32bits.bgen") as filepath: - bgen = Bgen(filepath, sid_function="id") + filepath = example_filepath("example.32bits.bgen") + bgen = Bgen(filepath, sid_function="id") - assert bgen.pos[0, 0] == 1 - assert bgen.sid[0] == "SNPID_2" - assert bgen.pos[0, 2] == 2000 + assert bgen.pos[0, 0] == 1 + assert bgen.sid[0] == "SNPID_2" + assert bgen.pos[0, 2] == 2000 - assert bgen.pos[7, 0] == 1 - assert bgen.sid[7] == "SNPID_9" - assert bgen.pos[7, 2] == 9000 + assert bgen.pos[7, 0] == 1 + assert bgen.sid[7] == "SNPID_9" + assert bgen.pos[7, 2] == 9000 - assert bgen.pos[-1, 0] == 1 - assert bgen.sid[-1] == "SNPID_200" - assert bgen.pos[-1, 2] == 100001 + assert bgen.pos[-1, 0] == 1 + assert bgen.sid[-1] == "SNPID_200" + assert bgen.pos[-1, 2] == 100001 - assert (bgen.iid[0] == ("0", "sample_001")).all() - assert (bgen.iid[7] == ("0", "sample_008")).all() - assert (bgen.iid[-1] == ("0", "sample_500")).all() + assert (bgen.iid[0] == ("0", "sample_001")).all() + assert (bgen.iid[7] == ("0", "sample_008")).all() + assert (bgen.iid[-1] == ("0", "sample_500")).all() - g = bgen[0, 0].read() - assert np.isnan(g.val).all() + g = bgen[0, 0].read() + assert np.isnan(g.val).all() - g = bgen[1, 0].read() - a = [[[0.027802362811705648, 0.00863673794284387, 0.9635608992454505]]] - np.testing.assert_array_almost_equal(g.val, a) + g = bgen[1, 0].read() + a = [[[0.027802362811705648, 0.00863673794284387, 0.9635608992454505]]] + np.testing.assert_array_almost_equal(g.val, a) - b = [ + b = [ + [ [ - [ - 0.97970582847010945215516, - 0.01947019668749305418287, - 0.00082397484239749366197, - ] + 0.97970582847010945215516, + 0.01947019668749305418287, + 0.00082397484239749366197, ] ] - g = bgen[2, 1].read() - np.testing.assert_array_almost_equal(g.val, b) + ] + g = bgen[2, 1].read() + np.testing.assert_array_almost_equal(g.val, b) def test_bgen_reader_without_metadata(self): from bgen_reader import example_filepath - with example_filepath("example.32bits.bgen") as filepath: - bgen = Bgen(filepath) - bgen.read() - samples = bgen.iid - assert samples[-1, 1] == "sample_500" + filepath = example_filepath("example.32bits.bgen") + bgen = Bgen(filepath) + bgen.read() + samples = bgen.iid + assert samples[-1, 1] == "sample_500" def test_bgen_reader_file_notfound(self): bgen = Bgen("/1/2/3/example.32bits.bgen") @@ -938,9 +938,9 @@ def test_bgen_reader_file_notfound(self): def test_bgen_reader_no_sample(self): from bgen_reader import example_filepath - with example_filepath("example.32bits.bgen") as filepath: - bgen = Bgen(filepath) - assert bgen.sid_count == 199 + filepath = example_filepath("example.32bits.bgen") + bgen = Bgen(filepath) + assert bgen.sid_count == 199 def test_doctest(self): import doctest @@ -959,29 +959,29 @@ def test_coverage(self): from bgen_reader import example_filepath from pysnptools.distreader import DistGen - with example_filepath("example.32bits.bgen") as filepath: - bgen = Bgen( - filepath, fresh_properties=False, iid_function=lambda sam: ("X", sam) - ) - assert bgen.iid[0, 0] == "X" - metadata_filepath = bgen._open_bgen._metadata2_path - metadata2_temp = metadata_filepath.parent / ( - metadata_filepath.name + ".temp" - ) - del bgen - if metadata2_temp.exists(): - metadata2_temp.unlink() - os.rename(metadata_filepath, metadata2_temp) - bgen = Bgen(filepath) - assert bgen.iid[0, 0] == "0" - bgen[0, 0].read(order="A") - if not os.path.exists("temp"): - os.mkdir("temp") - os.chdir("temp") - file1x = "coverage.bgen" - Bgen.write(file1x, bgen[:100, :100]) - Bgen.write(file1x, bgen[:100, :100]) - os.chdir("..") + filepath = example_filepath("example.32bits.bgen") + bgen = Bgen( + filepath, fresh_properties=False, iid_function=lambda sam: ("X", sam) + ) + assert bgen.iid[0, 0] == "X" + metadata_filepath = bgen._open_bgen._metadata2_path + metadata2_temp = metadata_filepath.parent / ( + metadata_filepath.name + ".temp" + ) + del bgen + if metadata2_temp.exists(): + metadata2_temp.unlink() + os.rename(metadata_filepath, metadata2_temp) + bgen = Bgen(filepath) + assert bgen.iid[0, 0] == "0" + bgen[0, 0].read(order="A") + if not os.path.exists("temp"): + os.mkdir("temp") + os.chdir("temp") + file1x = "coverage.bgen" + Bgen.write(file1x, bgen[:100, :100]) + Bgen.write(file1x, bgen[:100, :100]) + os.chdir("..") distgen0data = DistGen(seed=332, iid_count=10010, sid_count=5).read() file1 = "temp/roundtrip1-big.bgen" diff --git a/pysnptools/distreader/distdata.py b/pysnptools/distreader/distdata.py index 542e97a..1297622 100644 --- a/pysnptools/distreader/distdata.py +++ b/pysnptools/distreader/distdata.py @@ -3,6 +3,7 @@ import logging from pysnptools.distreader import DistReader from pysnptools.pstreader import PstData +from pysnptools.util import array_dtype class DistData(PstData, DistReader): @@ -107,7 +108,7 @@ def __init__(self, iid, sid, val, pos=None, name=None, copyinputs_function=None) row_count=len(self._row), col_count=len(self._col), empty_creator=lambda row_count, col_count: np.empty( - [row_count, col_count, 3], dtype=np.float64 + [row_count, col_count, 3], dtype=array_dtype() ), ) # !!!Replace empty with my FillNA method? self._assert_iid_sid_pos(check_val=True) @@ -134,7 +135,7 @@ def val(self, new_value): row_count=len(self._row), col_count=len(self._col), empty_creator=lambda row_count, col_count: np.empty( - [row_count, col_count, 3], dtype=np.float64 + [row_count, col_count, 3], dtype=array_dtype() ), ) # !!!Replace empty with my FillNA method? self._assert_iid_sid_pos(check_val=True) diff --git a/pysnptools/distreader/distreader.py b/pysnptools/distreader/distreader.py index bfc53d3..9cecb82 100644 --- a/pysnptools/distreader/distreader.py +++ b/pysnptools/distreader/distreader.py @@ -2,6 +2,7 @@ from itertools import * # noqa: F403 import logging from pysnptools.pstreader import PstReader +from pysnptools.util import array_dtype from pysnptools.snpreader._dist2snp import _Dist2Snp @@ -223,7 +224,7 @@ def _read( def read( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, @@ -237,7 +238,8 @@ def read( ndarray may be in any order (either C-, Fortran-contiguous). :type order: string or None - :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for the :attr:`DistData.val` ndarray. + :param dtype: {None, numpy.float64, numpy.float32}, optional -- The data-type for the :attr:`DistData.val` ndarray. + None uses ARRAY_DTYPE, then float64; explicit dtype overrides it. :type dtype: data-type :param force_python_only: optional -- If False (default), may use outside library code. If True, requests that the read @@ -280,7 +282,7 @@ def read( >>> import numpy as np >>> # print np.may_share_memory(subset_distdata.val, subsub_distdata.val) # Do the two ndarray's share memory? They could. Currently they won't. """ - dtype = np.dtype(dtype) + dtype = array_dtype(dtype) val = self._read( None, None, order, dtype, force_python_only, view_ok, num_threads ) @@ -379,7 +381,7 @@ def _as_distdata(distreader, force_python_only, order, dtype, num_threads): Like 'read' except won't read if already a DistData """ - dtype = np.dtype(dtype) + dtype = array_dtype(dtype) if ( hasattr(distreader, "val") diff --git a/pysnptools/kernelreader/_subset.py b/pysnptools/kernelreader/_subset.py index 2879bc5..f0e0eed 100644 --- a/pysnptools/kernelreader/_subset.py +++ b/pysnptools/kernelreader/_subset.py @@ -5,3 +5,13 @@ class _KernelSubset(KernelReader,_PstSubset): def __init__(self, *args, **kwargs): super(_KernelSubset, self).__init__(*args, **kwargs) + + def _read_array(self, row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp): + self._run_once() + row_index = self.compose_indexer_with_indexer( + self._internal.row_count, self._row_indexer, self.row_count, row_index) + col_index = self.compose_indexer_with_indexer( + self._internal.col_count, self._col_indexer, self.col_count, col_index) + return self._internal._read_array(row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp) diff --git a/pysnptools/kernelreader/kerneldata.py b/pysnptools/kernelreader/kerneldata.py index 523cc8c..a0a028b 100644 --- a/pysnptools/kernelreader/kerneldata.py +++ b/pysnptools/kernelreader/kerneldata.py @@ -14,17 +14,21 @@ class KernelData(KernelReader, PstData): It can also be created by calling the :meth:`.KernelReader.read` method on :class:`.SnpKernel`, for example, :class:`.KernelNpz`. It can also be constructed directly. - See :class:`.KernelReader` for details and examples. + See :class:`.KernelReader` for details and examples, and :doc:`/gpu` for + backend selection and device-transfer examples. Existing float32 and float64 + arrays retain their dtype when transferred between NumPy and CuPy. + New supported GPU matrices prefer CubeCL-owned storage when available; + existing CuPy arrays retain their storage when no conversion is needed. **Constructor:** :Parameters: * **iid** (an array of string pairs) -- The :attr:`KernelReader.iid` information. * **iid0** (an array of string pairs) -- The :attr:`KernelReader.iid0` information. * **iid1** (an array of strings pairs) -- The :attr:`KernelReader.iid1` information. - * **val** (a 2-D array of floats) -- The SNP values + * **val** (a 2-D array of floats) -- The kernel values * **name** (optional, string) -- Information to be display about the origin of this data * **xp** (optional, a Python module or string) -- The array module that controls **val**, - for example, 'numpy' or 'cupy'. Defaults to numpy. Can also be set with the - 'ARRAY_MODULE' environment variable. + for example, 'numpy' or 'cupy'. An explicit choice overrides ARRAY_MODULE; + None uses the environment, then NumPy. Missing CuPy raises ImportError. If *iid* is provided, don't provide *iid0* and *iid1*. Likewise, if *iid0* and *iid1* are provided, don't provide *iid*. @@ -128,8 +132,8 @@ def __init__( val, row_count=len(self._row), col_count=len(self._col), - empty_creator=lambda row_count, col_count: xp.empty( - [row_count, col_count], dtype=xp.float64 + empty_creator=lambda row_count, col_count: np.empty( + [row_count, col_count], dtype=pstutil.array_dtype() ), xp=xp, ) @@ -140,7 +144,7 @@ def __init__( @property def val(self): - """The 2D NumPy array of floats that represents the values of the kernel. You can get or set this property. + """The 2D NumPy or CuPy array of floats that represents the values of the kernel. You can get or set this property. >>> from pysnptools.kernelreader import KernelData >>> kerneldata = KernelData(iid=[['fam0','iid0'],['fam0','iid1']], val=[[1.,.5],[.5,1.]]) @@ -156,7 +160,7 @@ def val(self, new_value): row_count=len(self._row), col_count=len(self._col), empty_creator=lambda row_count, col_count: np.empty( - [row_count, col_count], dtype=np.float64 + [row_count, col_count], dtype=pstutil.array_dtype() ), xp=self._xp, ) @@ -189,10 +193,17 @@ def standardize( num_threads=None, ): """Does in-place standardization of the in-memory - kernel data. The method multiples the values with a scalar factor such that the diagonal sums to iid_count. Although it works in place, for convenience - it also returns the KernelData. - - :rtype: :class:`.KernelData` (standardizes in place, but for convenience, returns 'self') + kernel data on its existing NumPy/CuPy device. The default DiagKtoN + multiplies values by a scalar so the diagonal sums to iid_count. + A zero, negative, or nonfinite trace (including an empty kernel) raises + ValueError before changing values. + See :doc:`/gpu` for kernel construction and memory examples. + + :param standardizer: Kernel standardizer; defaults to DiagKtoN(). + :param return_trained: If True, also return the trained standardizer. + :param force_python_only: Passed to the standardizer; ignored by DiagKtoN. + :param num_threads: Passed to the standardizer; ignored by DiagKtoN. + :rtype: KernelData, or (KernelData, trained standardizer) >>> from pysnptools.kernelreader import KernelNpz >>> from pysnptools.util import example_file # Download and return local file name diff --git a/pysnptools/kernelreader/kernelreader.py b/pysnptools/kernelreader/kernelreader.py index 65490e9..459aae9 100644 --- a/pysnptools/kernelreader/kernelreader.py +++ b/pysnptools/kernelreader/kernelreader.py @@ -1,3 +1,4 @@ +import pysnptools.util as pstutil import numpy as np from itertools import * # noqa: F403 import logging @@ -126,8 +127,11 @@ class KernelReader(PstReader): The :meth:`read` Method - By default the :meth:`read` returns a ndarray of numpy.float64 laid out in memory in F-contiguous order (iid0-index varies the fastest). You may, instead, - ask for numpy.float32 or for C-contiguous order or any order. See :meth:`read` for details. + Without ARRAY_DTYPE or an explicit dtype, :meth:`read` returns :class:`.KernelData` with a float64 values array + in F-contiguous order (iid0-index varies the fastest). You may, instead, + ask for numpy.float32 or for C-contiguous order or any order. Explicit ``xp`` + selects NumPy or CuPy and overrides ARRAY_MODULE; the final default is + NumPy. See :meth:`read` and :doc:`/gpu` for options and complete examples. The :meth:`.KernelData.standardize` Method The :meth:`.KernelData.standardize` method, available only on :class:`.KernelData`, does in-place standardization of the in-memory @@ -244,46 +248,56 @@ def col_property(self): def read( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, + xp=None, ): - """Reads the kernel values and returns a :class:`.KernelData` (with :attr:`KernelData.val` property containing a new ndarray of the kernel values). + """Reads the kernel values and returns a :class:`.KernelData` (with :attr:`KernelData.val` property containing a NumPy or CuPy array of kernel values). :param order: {'F' (default), 'C', 'A'}, optional -- Specify the order of the ndarray. If order is 'F' (default), then the array will be in F-contiguous order (iid0-index varies the fastest). If order is 'C', then the returned array will be in C-contiguous order (iid1-index varies the fastest). If order is 'A', then the :attr:`KernelData.val` ndarray may be in any order (either C-, Fortran-contiguous, or even discontiguous). - :type order: string or None + :type order: str - :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for the :attr:`KernelData.val` ndarray. + :param dtype: {None, numpy.float64, numpy.float32}, optional -- The data-type for the :attr:`KernelData.val` ndarray. + None uses ARRAY_DTYPE, then float64; an explicit dtype overrides it. :type dtype: data-type :param force_python_only: optional -- If False (default), may use outside library code. If True, requests that the read - be done without outside library code. + use a Python CPU path where supported. GPU BED reads reject True with ValueError; + this does not select a CPU backend. CuPy standardization ignores this flag. :type force_python_only: bool :param view_ok: optional -- If False (default), allocates new memory for the :attr:`KernelData.val`'s ndarray. If True, if practical and reading from a :class:`KernelData`, will return a new :class:`KernelData` with a ndarray shares memory with the original :class:`KernelData`. Typically, you'll also wish to use "order='A'" to increase the chance that sharing will be possible. - Use these parameters with care because any change to either ndarray (for example, via :meth:`.KernelData.standardize`) will effect + Use these parameters with care because any change to either ndarray (for example, via :meth:`.KernelData.standardize`) will affect the others. Also keep in mind that :meth:`read` relies on ndarray's mechanisms to decide whether to actually share memory and so it may ignore your suggestion and allocate a new ndarray anyway. :type view_ok: bool - :param num_threads: optional -- The number of threads with which to standardize data. Defaults to all available + :param num_threads: optional -- The CPU reader/kernel thread count (ignored by CuPy math). Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. :type num_threads: None or int + :param xp: NumPy or CuPy module or name. An explicit value overrides + ARRAY_MODULE. Only None consults the environment; NumPy is the final default. + Each read selects independently of the source object's constructor. + Missing CuPy raises ImportError. See :doc:`/gpu` for complete examples. + :type xp: module, str, or None + :rtype: :class:`.KernelData` - Calling the method again causes the kernel values to be re-read and creates a new in-memory :class:`.KernelData` with a new ndarray of kernel values. + Each call creates a new :class:`.KernelData`. Values are read again from disk + or copied from memory unless ``view_ok=True`` allows shared storage. - If you request the values for only a subset of the sids or iids, (to the degree practical) only that subset will be read from disk. + If you request the values for only a subset of the rows or columns, (to the degree practical) only that subset will be read from disk. :Example: @@ -301,15 +315,38 @@ def read( >>> import numpy as np >>> #print(np.may_share_memory(subset_kerneldata.val, subsub_kerneldata.val)) # Do the two ndarray's share memory? They could. Currently they won't. """ - dtype = np.dtype(dtype) - val = self._read( - None, None, order, dtype, force_python_only, view_ok, num_threads + dtype = pstutil.array_dtype(dtype) + xp = pstutil.array_module(xp) + val = self._read_array( + None, None, order, dtype, force_python_only, view_ok, num_threads, xp ) from pysnptools.kernelreader import KernelData - ret = KernelData(iid0=self.iid0, iid1=self.iid1, val=val, name=str(self)) + ret = KernelData(iid0=self.iid0, iid1=self.iid1, val=val, name=str(self), xp=xp) return ret + def _read_array(self, row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp): + if not getattr(self, "_read_accepts_slices", False): + # None means an unsliced read, which some readers require. Only + # normalize actual indexers for readers that cannot consume slices. + if row_index is not None: + row_index = self._make_sparray_from_sparray_or_slice(self.row_count, row_index) + if col_index is not None: + col_index = self._make_sparray_from_sparray_or_slice(self.col_count, col_index) + val = self._read(row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads) + # Preserve reader-specific arrays such as memmaps when no transfer is + # needed. The legacy _read contract already guarantees dtype and order. + if pstutil.get_array_module(val) is xp: + return val + if xp is np: + val = pstutil.asnumpy(val) + # Kernels are never standardized natively, so CuPy's own pool serves them. + from pysnptools.util._gpu_warnings import warn_gpu_float64 + warn_gpu_float64(dtype, xp) + return xp.asarray(val, dtype=dtype, order=order) + def iid_to_index(self, list): """Takes a list of iids and returns a list of index numbers. Assumes the kernel is square, so will throw an exception if the row iids are different from the column iids. @@ -383,12 +420,16 @@ def _read_with_standardizing( snp_standardizer=None, kernel_standardizer=DiagKtoN(), return_trained=False, + dtype=None, + xp=None, + num_threads=None, ): assert ( to_kerneldata ), "When working with non-SnpKernels, to_kerneldata must be 'True'" - kernel, kernel_trained = self.read().standardize( - kernel_standardizer, return_trained=True + dtype = pstutil.array_dtype(dtype) + kernel, kernel_trained = self.read(dtype=dtype, xp=xp, num_threads=num_threads).standardize( + kernel_standardizer, return_trained=True, num_threads=num_threads ) if return_trained: diff --git a/pysnptools/kernelreader/snpkernel.py b/pysnptools/kernelreader/snpkernel.py index 6688a3d..dd053ae 100644 --- a/pysnptools/kernelreader/snpkernel.py +++ b/pysnptools/kernelreader/snpkernel.py @@ -1,4 +1,5 @@ import numpy as np +from numbers import Integral from itertools import * # noqa: F403 import logging from pysnptools.standardizer import Identity as SS_Identity @@ -11,15 +12,17 @@ class SnpKernel(KernelReader): """ A :class:`.KernelReader` that creates a kernel from a :class:`.SnpReader`. No SNP data will be read until - the :meth:`SnpKernel.read` method is called. Use block_size to avoid ever reading all the SNP data into memory. - at once. + the :meth:`SnpKernel.read` method is called. A positive block_size limits SNP + blocks during kernel construction; the dense kernel and temporary products + still need memory. Reading a subset can construct the full kernel first. + See :doc:`/gpu` for explicit read backends, dtype/order options, and examples. See :class:`.KernelReader` for general examples of using KernelReaders. **Constructor:** :Parameters: * **snpreader** (:class:`SnpReader`) -- The SNP data * **standardizer** (:class:`Standardizer`) -- How the SNP data should be standardized - * **block_size** (optional, int) -- The number of SNPs to read at a time. + * **block_size** (optional, positive int) -- The number of SNPs to read at a time. Invalid values raise ValueError. If **block_size** is not given, then all SNP data will be read at once. @@ -44,6 +47,12 @@ def __init__(self, snpreader, standardizer=None, block_size=None): super(SnpKernel, self).__init__() assert standardizer is not None, "'standardizer' must be provided" + if block_size is not None and ( + isinstance(block_size, (bool, np.bool_)) + or not isinstance(block_size, Integral) + or block_size <= 0 + ): + raise ValueError("block_size must be a positive integer or None") self.snpreader = snpreader self.standardizer = standardizer @@ -85,45 +94,26 @@ def _read( view_ok, num_threads, ): - dtype = np.dtype(dtype) - # Special case: If square and constant, can push the subsetting into the SnpReader - if ( - self.standardizer.is_constant - and row_index_or_none is not None - and col_index_or_none is not None - and np.array_equal(row_index_or_none, col_index_or_none) - ): - return self.snpreader[row_index_or_none, :]._read_kernel( - self.standardizer, - self.block_size, - order, - dtype, - force_python_only, - view_ok, - num_threads, - ) # !!!LATER can this ever be reached? - else: - # LATER: If it was often that case that we wanted to standardize on all the data, but then only return a slice of the result, - # that could be done with less memory by working in blocks but not tabulating for all the iids. - whole = self.snpreader._read_kernel( - self.standardizer, - self.block_size, - order, - dtype, - force_python_only, - view_ok, - num_threads, - ) - val, shares_memory = self._apply_sparray_or_slice_to_val( - whole, - row_index_or_none, - col_index_or_none, - order, - dtype, - force_python_only, - num_threads, - ) - return val + return self._read_array( + row_index_or_none, col_index_or_none, order, dtype, + force_python_only, view_ok, num_threads, pstutil.array_module()) + + def _read_array(self, row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp): + if (self.standardizer.is_constant and row_index is not None + and col_index is not None and np.array_equal(row_index, col_index)): + return self.snpreader[row_index, :]._read_kernel( + self.standardizer, block_size=self.block_size, order=order, dtype=dtype, + force_python_only=force_python_only, view_ok=view_ok, + num_threads=num_threads, xp=xp) + # LATER: Building just the requested rectangle could save memory. + whole = self.snpreader._read_kernel( + self.standardizer, block_size=self.block_size, order=order, dtype=dtype, + force_python_only=force_python_only, view_ok=view_ok, + num_threads=num_threads, xp=xp) + val, shares_memory = self._apply_sparray_or_slice_to_val( + whole, row_index, col_index, order, dtype, force_python_only, num_threads) + return val def __getitem__(self, iid_indexer_and_snp_indexer): if isinstance(iid_indexer_and_snp_indexer, tuple): @@ -153,6 +143,8 @@ def _read_with_standardizing( kernel_standardizer=DiagKtoN(), return_trained=False, num_threads=None, + dtype=None, + xp=None, ): """ Reads a SnpKernel with two cases @@ -166,12 +158,14 @@ def _read_with_standardizing( """ logging.info("Starting '_read_with_standardizing'") - xp = pstutil.array_module() + xp = pstutil.array_module(xp) + dtype = pstutil.array_dtype(dtype) if to_kerneldata: val, snp_trained = self.snpreader._read_kernel( self.standardizer, block_size=self.block_size, + dtype=dtype, xp=xp, return_trained=True, num_threads=num_threads, ) @@ -180,8 +174,9 @@ def _read_with_standardizing( kernel_standardizer, return_trained=True, num_threads=num_threads ) else: - snpdata, snp_trained = self.snpreader.read().standardize( - self.standardizer, return_trained=True, num_threads=num_threads + snpdata, snp_trained = self.snpreader._read_with_standardizing( + self.standardizer, return_trained=True, num_threads=num_threads, + dtype=dtype, xp=xp ) snpdata, kernel_trained = snpdata.standardize( kernel_standardizer, return_trained=True, num_threads=num_threads @@ -213,13 +208,17 @@ def pos(self): def read_snps( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, + xp=None, ): """Reads the SNP values, applies the standardizer, and returns a :class:`.SnpData`. + Values are standardized on the selected device. See :doc:`/gpu` for + GPU prerequisites, training semantics, and complete workflow examples. + :param order: {'F' (default), 'C', 'A'}, optional -- Specify the order of the ndarray. If order is 'F' (default), then the array will be in F-contiguous order (iid-index varies the fastest). If order is 'C', then the returned array will be in C-contiguous order (sid-index varies the fastest). @@ -227,38 +226,42 @@ def read_snps( ndarray may be in any order (either C-, Fortran-contiguous). :type order: string or None - :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for the :attr:`SnpData.val` ndarray. + :param dtype: {None, numpy.float64, numpy.float32}, optional -- The data-type for the :attr:`SnpData.val` ndarray. + None uses ARRAY_DTYPE, then float64; explicit dtype overrides it. :type dtype: data-type - :param force_python_only: optional -- If False (default), may use outside library code. If True, requests that the read - be done without outside library code. + :param force_python_only: Request a Python CPU path where supported. + Native GPU BED reads reject True; this flag does not select a CPU backend. :type force_python_only: bool - :param view_ok: optional -- If False (default), allocates new memory for the :attr:`SnpData.val`'s ndarray. If True, - if practical and reading from a :class:`SnpData`, will return a new - :class:`SnpData` with a ndarray shares memory with the original :class:`SnpData`. - Typically, you'll also wish to use "order='A'" to increase the chance that sharing will be possible. - Use these parameters with care because any change to either ndarray (for example, via :meth:`.SnpData.standardize`) will effect - the others. Also keep in mind that :meth:`read` relies on ndarray's mechanisms to decide whether to actually - share memory and so it may ignore your suggestion and allocate a new ndarray anyway. + :param view_ok: Accepted for compatibility but ignored. This method reads + independent values before standardizing them in place. :type view_ok: bool - :param num_threads: optional -- The number of threads with which to read data. Defaults to all available + :param num_threads: optional -- The CPU thread count, ignored by GPU decoding and CuPy math. Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. :type num_threads: None or int + :param xp: NumPy or CuPy module or name. An explicit choice overrides + ARRAY_MODULE; None uses the environment, then NumPy. + :type xp: module, str, or None + :rtype: :class:`.SnpData` + >>> from pysnptools.kernelreader import SnpKernel + >>> from pysnptools.snpreader import SnpData + >>> from pysnptools.standardizer import Unit + >>> source = SnpData(iid=[["f", "0"], ["f", "1"]], sid=["s"], val=[[0.], [2.]], xp="numpy") + >>> standardized = SnpKernel(source, Unit()).read_snps(xp="numpy") + >>> standardized.val.tolist() + [[-1.0], [1.0]] """ - dtype = np.dtype(dtype) - return self.snpreader.read( - order=order, - dtype=dtype, - force_python_only=force_python_only, - view_ok=view_ok, - num_threads=num_threads, - ).standardize(self.standardizer, num_threads=num_threads) + dtype = pstutil.array_dtype(dtype) + return self.snpreader._read_with_standardizing( + self.standardizer, order=order, dtype=dtype, xp=xp, + force_python_only=force_python_only, num_threads=num_threads) + if __name__ == "__main__": diff --git a/pysnptools/kernelreader/test.py b/pysnptools/kernelreader/test.py index aeae64c..9579fe7 100644 --- a/pysnptools/kernelreader/test.py +++ b/pysnptools/kernelreader/test.py @@ -38,6 +38,27 @@ def output(self, item): class TestKernelReader(unittest.TestCase): + def test_invalid_block_size(self): + source = SnpData( + iid=[["family", str(sample)] for sample in range(3)], + sid=["snp0", "snp1"], + val=np.array([[0., 0.], [1., 1.], [2., 2.]]), + xp=np, + ) + for block_size in (-1, 0, 0.5, 10.5, True, np.bool_(False), np.nan, np.inf): + with self.subTest(block_size=block_size): + for create_kernel in ( + lambda: source.read_kernel(stdizer.Unit(), block_size=block_size, xp=np), + lambda: SnpKernel(source, stdizer.Unit(), block_size=block_size), + ): + with self.assertRaisesRegex(ValueError, "positive integer or None"): + create_kernel() + # Both ordinary Python and NumPy integer block sizes remain supported. + expected = np.array([[3., 0., -3.], [0., 0., 0.], [-3., 0., 3.]]) + for block_size in (1, np.int64(1), None): + actual = source.read_kernel(stdizer.Unit(), block_size=block_size, xp=np).val + np.testing.assert_allclose(actual, expected, rtol=8 * np.finfo(float).eps, atol=0) + @classmethod def setUpClass(self): self.currentFolder = os.path.dirname(os.path.realpath(__file__)) diff --git a/pysnptools/pstreader/pstdata.py b/pysnptools/pstreader/pstdata.py index 67406c8..4fdebf1 100644 --- a/pysnptools/pstreader/pstdata.py +++ b/pysnptools/pstreader/pstdata.py @@ -1,3 +1,4 @@ +import sys import warnings import numpy as np from itertools import * # noqa: F403 @@ -14,6 +15,28 @@ def _default_empty_creator_val(row_count, col_count): return np.empty([row_count, col_count], dtype="str") + +def _as_array_module(input, xp, require_float32_64): + from pysnptools.util._array import asarray + # Return input as an xp array. An array (from xp or from the other module, numpy or + # cupy) keeps its dtype if it is float32 or float64, or always if require_float32_64 + # is False; otherwise (including a list), use ARRAY_DTYPE, then float64. + def keeps_dtype(array): + return not require_float32_64 or array.dtype in (np.float32, np.float64) + + if isinstance(input, xp.ndarray): # same module + return input if keeps_dtype(input) else asarray(input, dtype=pstutil.array_dtype(), order="K", xp=xp) + + cp = sys.modules.get("cupy") # a cupy array exists only if cupy was imported + if isinstance(input, np.ndarray) or (cp is not None and isinstance(input, cp.ndarray)): + dtype = input.dtype if keeps_dtype(input) else pstutil.array_dtype() + if xp is np: + input = pstutil.asnumpy(input) # cupy forbids implicit conversion to numpy + return asarray(input, dtype=dtype, order="K", xp=xp, copy=True) + + return asarray(input, dtype=pstutil.array_dtype(), order="K", xp=xp) + + class PstData(PstReader): """A :class:`.PstReader` for holding values in-memory, along with related row and col information. It is usually created by calling the :meth:`.PstReader.read` method on another :class:`.PstReader`, for example, :class:`.PstNpz`. It can also be constructed directly. @@ -183,11 +206,11 @@ def _fixup_input_val( assert ( row_count == 0 or col_count == 0 ), "If val is None, either row_count or col_count must be 0" - input = _default_empty_creator_val(row_count, col_count) - elif not isinstance(input, xp.ndarray): - input = xp.array(input, dtype=xp.float64) - elif _require_float32_64 and input.dtype not in [xp.float32, xp.float64]: - input = xp.array(input, dtype=xp.float64) + input = empty_creator(row_count, col_count) + if xp is not np: + input = _as_array_module(input, xp, _require_float32_64) + else: + input = _as_array_module(input, xp, _require_float32_64) assert len(input.shape) in {2, 3}, "Expect val to be two or three dimensional." assert ( @@ -273,6 +296,13 @@ def _read( num_threads, ): dtype = np.dtype(dtype) + xp = pstutil.get_array_module(self.val) + if (xp is not np and PstReader._is_all_slice(row_index_or_none) + and PstReader._is_all_slice(col_index_or_none)): + if view_ok and PstReader._array_properties_are_ok(self.val, order, dtype): + return self.val + from pysnptools.util._array import asarray + return asarray(self.val, dtype=dtype, order=order, xp=xp, copy=True) val, shares_memory = self._apply_sparray_or_slice_to_val( self.val, row_index_or_none, @@ -283,7 +313,11 @@ def _read( num_threads, ) if shares_memory and not view_ok: - val = val.copy(order="K") + if xp is np: + val = val.copy(order="K") + else: + from pysnptools.util._array import asarray + val = asarray(val, dtype=val.dtype, order="K", xp=xp, copy=True) return val diff --git a/pysnptools/pstreader/pstreader.py b/pysnptools/pstreader/pstreader.py index 4ab5f65..8c2411d 100644 --- a/pysnptools/pstreader/pstreader.py +++ b/pysnptools/pstreader/pstreader.py @@ -281,7 +281,7 @@ class PstReader(object): The :meth:`read` Method - By default the :meth:`read` returns a ndarray of numpy.float64 laid out in memory in F-contiguous order (row-index varies the fastest). You may, instead, + Without ARRAY_DTYPE or an explicit dtype, :meth:`read` returns an ndarray of numpy.float64 laid out in memory in F-contiguous order (row-index varies the fastest). You may, instead, ask for numpy.float32 or for C-contiguous order or any order. See :meth:`read` for details. Details of Methods & Properties: @@ -424,7 +424,7 @@ def _read( def read( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, @@ -438,7 +438,8 @@ def read( ndarray may be in any order (either C-, Fortran-contiguous). :type order: string or None - :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for the :attr:`PstData.val` ndarray. + :param dtype: {None, numpy.float64, numpy.float32}, optional -- The data-type for the :attr:`PstData.val` ndarray. + None uses ARRAY_DTYPE, then float64; an explicit dtype overrides it. :type dtype: data-type :param force_python_only: optional -- If False (default), may use outside library code. If True, requests that the read @@ -483,7 +484,7 @@ def read( >>> import numpy as np >>> # print(np.may_share_memory(subset_snpdata.val, subsub_snpdata.val)) # Do the two ndarray's share memory? They could. Currently they won't. """ - dtype = np.dtype(dtype) + dtype = pstutil.array_dtype(dtype) val = self._read( None, None, order, dtype, force_python_only, view_ok, num_threads ) @@ -656,7 +657,7 @@ def _make_sparray_from_sparray_or_slice(count, indexer): @staticmethod def _array_properties_are_ok(val, order, dtype): - dtype = np.dtype(dtype) + dtype = pstutil.array_dtype(dtype) if val.dtype != dtype: return False @@ -677,7 +678,7 @@ def _apply_sparray_or_slice_to_val( force_python_only, num_threads, ): - dtype = np.dtype(dtype) + dtype = pstutil.array_dtype(dtype) if ( PstReader._is_all_slice(row_indexer_or_none) diff --git a/pysnptools/snpreader/_subset.py b/pysnptools/snpreader/_subset.py index 55465cd..4240561 100644 --- a/pysnptools/snpreader/_subset.py +++ b/pysnptools/snpreader/_subset.py @@ -4,3 +4,28 @@ class _SnpSubset(_PstSubset,SnpReader): def __init__(self, *args, **kwargs): super(_SnpSubset, self).__init__(*args, **kwargs) + + def _read_array(self, row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp): + self._run_once() + row_index = self.compose_indexer_with_indexer( + self._internal.row_count, self._row_indexer, self.row_count, row_index) + col_index = self.compose_indexer_with_indexer( + self._internal.col_count, self._col_indexer, self.col_count, col_index) + return self._internal._read_array(row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp) + + def _read_with_standardizing(self, standardizer, order="F", dtype=None, + xp=None, return_trained=False, + force_python_only=False, num_threads=None, + _row_index=None, _col_index=None): + self._run_once() + row_index = self.compose_indexer_with_indexer( + self._internal.row_count, self._row_indexer, self.row_count, _row_index) + col_index = self.compose_indexer_with_indexer( + self._internal.col_count, self._col_indexer, self.col_count, _col_index) + result = self._internal._read_with_standardizing( + standardizer, order=order, dtype=dtype, xp=xp, + return_trained=return_trained, force_python_only=force_python_only, + num_threads=num_threads, _row_index=row_index, _col_index=col_index) + return result diff --git a/pysnptools/snpreader/bed.py b/pysnptools/snpreader/bed.py index 0ebb442..7d2d77d 100644 --- a/pysnptools/snpreader/bed.py +++ b/pysnptools/snpreader/bed.py @@ -29,7 +29,7 @@ class Bed(SnpReader): * **iid** (an array of strings) -- The :attr:`SnpReader.iid` information. If not given, reads info from '.fam' file. * **sid** (an array of strings) -- The :attr:`SnpReader.sid` information. If not given, reads info from '.bim' file. * **pos** (optional, an array of strings) -- The :attr:`SnpReader.pos` information. If not given, reads info from '.bim' file. - * **num_threads** (optinal, int) -- The number of threads with which to read data. Defaults to all available processors. + * **num_threads** (optional, int) -- The number of threads with which to read data. Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. * **skip_format_check** (*bool*) -- By default (False), checks that the '.bed' file starts with the expected bytes @@ -50,8 +50,13 @@ class Bed(SnpReader): **Methods beyond** :class:`.SnpReader` The :meth:`.SnpReader.read` method returns a :class:`SnpData` with a :attr:`SnpData.val` ndarray. By default, this ndarray is - numpy.float32. Optionally, it can be numpy.float16. For :class:`Bed`, however, it can also be numpy.int8 with missing values - represented by -127. + numpy.float64. Optionally, it can be numpy.float32, or numpy.int8 with + ``_require_float32_64=False`` and missing values represented by -127. + Float16 is not supported. ``xp`` selects NumPy/CuPy at read time; native + GPU reads require a CUDA-enabled bed-reader build and reject + ``force_python_only=True``. CPU thread settings and ``view_ok`` do not + control GPU decoding. See :doc:`/gpu` for prerequisites, exceptions, + memory limits, and a complete synthetic BED example. When reading, any chromosome and position values of 0 (the PLINK standard for missing) will be represented in :attr:`pos` as NaN. @@ -339,6 +344,53 @@ def _read( return val + def _read_array(self, row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp): + self._run_once() + return self._open_bed.read( + index=(row_index, col_index), dtype=dtype, + order="F" if order == "A" else order, xp=xp, + force_python_only=force_python_only, num_threads=num_threads) + + def _read_with_standardizing(self, standardizer, order="F", dtype=None, + xp=None, return_trained=False, + force_python_only=False, num_threads=None, + _row_index=None, _col_index=None): + import pysnptools.util as pstutil + from pysnptools.standardizer import Unit, Beta, UnitTrained, BetaTrained + from pysnptools.snpreader import SnpData + + xp = pstutil.array_module(xp) + dtype = pstutil.array_dtype(dtype) + if xp is np or type(standardizer) not in (Unit, Beta) or force_python_only: + return super()._read_with_standardizing( + standardizer, order=order, dtype=dtype, xp=xp, + return_trained=return_trained, force_python_only=force_python_only, + num_threads=num_threads, _row_index=_row_index, _col_index=_col_index) + from bed_reader import bed_reader as native + + self._run_once() + owner = self._open_bed._read_gpu( + (_row_index, _col_index), dtype, "F" if order == "A" else order) + is_beta = type(standardizer) is Beta + stats = native.standardize_gpu( + owner, is_beta, standardizer.a if is_beta else 1.0, + standardizer.b if is_beta else 25.0) + # No CuPy work precedes CubeCL here. Export waits for CubeCL to finish; + # CuPy keeps the owner alive, including when only a view remains. + metadata = self if _row_index is None and _col_index is None else self[_row_index, _col_index] + if hasattr(native, "allocate_gpu"): + from bed_reader._gpu import _as_cupy + values = _as_cupy(owner) + else: + values = xp.asarray(owner) + data = SnpData(iid=metadata.iid, sid=metadata.sid, pos=metadata.pos, + val=values, xp=xp, name=str(metadata)) + data._std_string_list.append(str(standardizer)) + trained = (BetaTrained(standardizer.a, standardizer.b, data.sid, stats) + if is_beta else UnitTrained(data.sid, stats)) + return (data, trained) if return_trained else data + if __name__ == "__main__": logging.basicConfig(level=logging.INFO) diff --git a/pysnptools/snpreader/dat.py b/pysnptools/snpreader/dat.py index c7be3dc..a574d68 100644 --- a/pysnptools/snpreader/dat.py +++ b/pysnptools/snpreader/dat.py @@ -59,7 +59,7 @@ def _read_pstdata(self): ) if len(row) == 0 or len(col) == 0: return SnpData( - iid=row, sid=col, pos=col_property, val=np.empty([len(row), len(col)]) + iid=row, sid=col, pos=col_property, val=np.empty([len(row), len(col)]), xp=np ) datfields = pd.read_csv( self.filename, @@ -79,7 +79,7 @@ def _read_pstdata(self): len(row) == datfields.shape[1] ), "Expect # iids in fam file to match dat file" val = datfields.values.T - snpdata = SnpData(iid=row, sid=col, pos=col_property, val=val) + snpdata = SnpData(iid=row, sid=col, pos=col_property, val=val, xp=np) return snpdata def copyinputs(self, copier): diff --git a/pysnptools/snpreader/dense.py b/pysnptools/snpreader/dense.py index 69876bc..82c2bd5 100644 --- a/pysnptools/snpreader/dense.py +++ b/pysnptools/snpreader/dense.py @@ -3,7 +3,6 @@ from pysnptools.snpreader import SnpReader from pysnptools.snpreader import SnpData import warnings -from pysnptools.pstreader import PstData from pysnptools.pstreader import _OneShot @@ -122,7 +121,7 @@ def _read_pstdata(self): for col_index in range(len(col)): val[:, col_index] = val_list_list[col_index] - return PstData(iid, col, val, col_property=col_property, name=self.filename) + return SnpData(iid=iid, sid=col, val=val, pos=col_property, name=self.filename, xp=np) @staticmethod def write( diff --git a/pysnptools/snpreader/ped.py b/pysnptools/snpreader/ped.py index df1cea6..2e4ba3a 100644 --- a/pysnptools/snpreader/ped.py +++ b/pysnptools/snpreader/ped.py @@ -60,7 +60,7 @@ def _read_pstdata(self): vals=snpsstr[~inan[:,2*i],2*i:2*(i+1)] if vals.shape[0] > 0: snps[~inan[:,2*i],i]+=(vals==vals[0,0]).sum(1) - snpdata = SnpData(iid=row,sid=col,pos=col_property,val=snps) + snpdata = SnpData(iid=row,sid=col,pos=col_property,val=snps,xp=np) return snpdata def copyinputs(self, copier): diff --git a/pysnptools/snpreader/pheno.py b/pysnptools/snpreader/pheno.py index efc5b55..5fe984e 100644 --- a/pysnptools/snpreader/pheno.py +++ b/pysnptools/snpreader/pheno.py @@ -99,7 +99,7 @@ def _read_pstdata(self): col_property.fill(np.nan) val = pheno_input["vals"] - snpdata = SnpData(iid=row, sid=col, pos=col_property, val=val) + snpdata = SnpData(iid=row, sid=col, pos=col_property, val=val, xp=np) return snpdata @staticmethod diff --git a/pysnptools/snpreader/snpdata.py b/pysnptools/snpreader/snpdata.py index 871785c..c78ae8c 100644 --- a/pysnptools/snpreader/snpdata.py +++ b/pysnptools/snpreader/snpdata.py @@ -14,18 +14,24 @@ class SnpData(PstData, SnpReader): """A :class:`.SnpReader` for holding SNP values (or similar values) in-memory, along with related iid and sid information. It is usually created by calling the :meth:`.SnpReader.read` method on another :class:`.SnpReader`, for example, :class:`.Bed`. It can also be constructed directly. - See :class:`.SnpReader` for details and examples. + See :class:`.SnpReader` for details and examples, and :doc:`/gpu` for device + transfers, GPU subsetting, and in-place standardization examples. Float32 and + float64 arrays keep their dtype when transferred between NumPy and CuPy; + lists and integer arrays use ARRAY_DTYPE, then float64. + New supported GPU matrices prefer CubeCL-owned storage when available; + existing CuPy arrays are retained when no conversion is needed. See + :doc:`/gpu` for allocation and standardization dispatch details. **Constructor:** :Parameters: * **iid** (an array of string pair) -- The :attr:`SnpReader.iid` information. * **sid** (an array of strings) -- The :attr:`SnpReader.sid` information. * **val** (a 2-D array of floats) -- The SNP values - * **pos** (optional, an array of strings) -- The :attr:`SnpReader.pos` information + * **pos** (optional, numeric array of shape (sid_count, 3)) -- The :attr:`SnpReader.pos` information * **name** (optional, string) -- Information to be display about the origin of this data * **copyinputs_function** (optional, function) -- *Used internally by optional clustering code* * **xp** (optional, a Python module or string) -- The array module that controls **val**, - for example, 'numpy' or 'cupy'. Defaults to numpy. Can also be set with the - 'ARRAY_MODULE' environment variable. + for example, 'numpy' or 'cupy'. An explicit choice overrides ARRAY_MODULE; + None uses the environment, then NumPy. Missing CuPy raises ImportError. :Example: @@ -100,7 +106,7 @@ def __init__( val, row_count=len(self._row), col_count=len(self._col), - empty_creator=lambda row_count, col_count: np.empty([row_count, col_count], dtype=np.float64), + empty_creator=lambda row_count, col_count: np.empty([row_count, col_count], dtype=pstutil.array_dtype()), _require_float32_64=_require_float32_64, xp=xp, ) @@ -111,7 +117,7 @@ def __init__( @property def val(self): - """The 2D NumPy array of floats that represents the values of the SNPs. You can get or set this property. + """The 2D NumPy or CuPy array of floats that represents the values of the SNPs. You can get or set this property. >>> from pysnptools.snpreader import Bed >>> from pysnptools.util import example_file # Download and return local file name @@ -128,7 +134,7 @@ def val(self, new_value): new_value, row_count=len(self._row), col_count=len(self._col), - empty_creator=lambda row_count, col_count: np.empty([row_count, col_count], dtype=np.float64), + empty_creator=lambda row_count, col_count: np.empty([row_count, col_count], dtype=pstutil.array_dtype()), xp=self._xp, ) self._assert_iid_sid_pos(check_val=True) @@ -186,31 +192,36 @@ def standardize( num_threads=None, ): """Does in-place standardization of the in-memory - SNP data. By default, it applies 'Unit' standardization, that is: the values for each SNP will have mean zero and standard deviation 1.0. - NaN values are then filled with zero, the mean (consequently, if there are NaN values, the final standard deviation will not be zero. + SNP data on the array's device, independently of ARRAY_MODULE. By default, + Unit centers and scales observed values to population standard deviation one, + then replaces NaNs with zero. With missing values, final column variance + is generally below one; constant columns become zero. Wholly missing + training columns raise ValueError. See :doc:`/gpu` for complete examples, + trained-statistic alignment, backend options, and exceptions. Note that, for efficiency, this method works in-place, actually changing values in the ndarray. Although it works in place, for convenience it also returns the SnpData. :param standardizer: optional -- Specify standardization to be applied. - Any :class:`.Standardizer` may be used. Some choices include :class:`.Unit` (default, makes values for each SNP have mean zero and - standard deviation 1.0) and :class:`.Beta`. + Any :class:`.Standardizer` may be used. Some choices include :class:`.Unit` (default, centers and scales observed + values before filling missing values with zero) and :class:`.Beta`. :type standardizer: :class:`.Standardizer` - :param block_size: optional -- Deprecated. + :param block_size: Deprecated and ignored; this wrapper does not forward it. :type block_size: None :param return_trained: If true, returns a second value containing a constant :class:`.Standardizer` trained on this data. :type return_trained: bool - :param force_python_only: optional -- If true, will use pure Python instead of faster C++ libraries. + :param force_python_only: Request Python CPU standardization when supported; + ignored for CuPy, which remains on the existing device. :type force_python_only: bool - :param num_threads: optional -- The number of threads with which to standardize data. Defaults to all available + :param num_threads: optional -- The CPU standardization thread count (ignored for CuPy). Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. :type num_threads: None or int - :rtype: :class:`.SnpData` (standardizes in place, but for convenience, returns 'self') + :rtype: :class:`.SnpData`, or (SnpData, trained standardizer) when return_trained=True >>> from pysnptools.snpreader import Bed >>> from pysnptools.util import example_file # Download and return local file name @@ -246,11 +257,12 @@ def _read_kernel( standardizer, block_size=None, order="A", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, return_trained=False, num_threads=None, + xp=None, ): """ The method creates a kernel for the in-memory SNP data. It handles these cases @@ -258,14 +270,27 @@ def _read_kernel( """ from pysnptools.pstreader import PstReader - dtype = np.dtype(dtype) + dtype = pstutil.array_dtype(dtype) + xp = pstutil.array_module(xp) # Just do a 'python' dot, if no standardization is needed and everything is the right type - if isinstance(standardizer, Identity) and train.val.dtype == dtype: + if (isinstance(standardizer, Identity) and train.val.dtype == dtype + and pstutil.get_array_module(train.val) is xp): time.time() # is_worth_logging = train.val.shape[0] * train.val.shape[1] * test.val.shape[0] > 1e9 # if is_worth_logging: logging.info(" _read_kernel about to multiply train{0} x test{1}".format(train.val.shape,test.val.shape)) - if order == "F": # numpy's 'dot' always returns 'C' order + if xp is not np: + from pysnptools.util._gpu_warnings import warn_gpu_float64 + # A kernel is never standardized natively, so CuPy's own pool serves it. + # Blocked kernels allocate one per block; CuPy reuses that memory, while + # bed-reader returns its allocations to CUDA as soon as they are dropped. + warn_gpu_float64(dtype, xp) + K = xp.empty((train.iid_count, train.iid_count), dtype=dtype, + order="F" if order == "F" else "C") + # dot's out must be C-contiguous; the symmetric product can be + # written through a transpose to retain the requested F layout. + xp.dot(train.val, train.val.T, out=K.T if order == "F" else K) + elif order == "F": # numpy's 'dot' always returns 'C' order K = (train.val.dot(train.val.T)).T else: K = train.val.dot(train.val.T) @@ -285,7 +310,7 @@ def _read_kernel( force_python_only=force_python_only, view_ok=view_ok, return_trained=return_trained, - num_threads=num_threads, + num_threads=num_threads, xp=xp, ) def __repr__(self): diff --git a/pysnptools/snpreader/snpreader.py b/pysnptools/snpreader/snpreader.py index 74712f6..83dc005 100644 --- a/pysnptools/snpreader/snpreader.py +++ b/pysnptools/snpreader/snpreader.py @@ -208,7 +208,7 @@ class SnpReader(PstReader): When Data is Re-Read and Copied: Every time you call a SnpReader's :meth:`read` method, the SnpReader re-reads the SNP value data and returns a new in-memory :class:`.SnpData` - (with :attr:`.SnpData.val` property containing a new ndarray of the SNP values). Likewise, when you call the :meth:`kernel` method, the SnpReader re-reads + (with :attr:`.SnpData.val` property containing a NumPy or CuPy array of SNP values). Likewise, when you call the :meth:`kernel` method, the SnpReader re-reads the data and returns a new kernel ndarray. Here is an example of what not to do, because it causes all the SNP value data to be read twice. @@ -256,7 +256,7 @@ class SnpReader(PstReader): can safely share the memory of the ndarray of SNP values. For this case, the :meth:`read` has optional parameters called view_ok and order. If you override the defaults of "view_ok=False,order='F'" with "view_ok=True,order='A', the :meth:`read` will, if practical, return a new :class:`SnpData` with a ndarray shares memory with the original ndarray. - Use these parameters with care because any change to either ndarray (for example, via :meth:`.SnpData.standardize`) will effect + Use these parameters with care because any change to either ndarray (for example, via :meth:`.SnpData.standardize`) will affect the others. Also keep in mind that :meth:`read` relies on ndarray's mechanisms to decide whether to actually share memory and so it may ignore your suggestion and allocate a new ndarray anyway. @@ -271,14 +271,19 @@ class SnpReader(PstReader): The :meth:`read` Method - By default the :meth:`read` returns a ndarray of numpy.float64 laid out in memory in F-contiguous order (iid-index varies the fastest). You may, instead, - ask for numpy.float32 or for C-contiguous order or any order. See :meth:`read` for details. + Without ARRAY_DTYPE or an explicit dtype, :meth:`read` returns :class:`.SnpData` with a float64 values array + in F-contiguous order (iid-index varies the fastest). You may, instead, + ask for numpy.float32 or for C-contiguous order or any order. Explicit xp overrides + ARRAY_MODULE at every read; NumPy is used when neither is supplied. See + :meth:`read` and :doc:`/gpu` for options and complete examples. The :meth:`.SnpData.standardize` Method The :meth:`.SnpData.standardize` method, available only on :class:`.SnpData`, does in-place standardization of the in-memory - SNP data. By default, it applies 'Unit' standardization, that is: the values for each SNP will have mean zero and standard deviation 1.0. - NaN values are then filled with zeros (consequently, if there are NaN values, the final standard deviation will not be zero). - Note that, for efficiently, this method works in-place, actually changing values in the ndarray. Although it works in place, for convenience + SNP data on the array's current device, independently of ARRAY_MODULE. Unit + centers/scales observed values to population standard deviation one, + then fills NaNs with zero; final variance can be below one. Constant + columns become zero and wholly missing training columns raise ValueError. + Note that, for efficiency, this method works in-place, actually changing values in the ndarray. Although it works in place, for convenience it also returns itself. See :meth:`.SnpData.standardize` for options and details. >>> snp_on_disk = Bed(bedfile,count_A1=False) # Specify some data on disk in Bed format @@ -298,7 +303,7 @@ class SnpReader(PstReader): The :meth:`read_kernel` Method The :meth:`read_kernel` method, available on any SnpReader, returns a :class:`KernelData`. The :attr:`val` property of the :class:`KernelData` is - an ndarray of the (possibility standardized) SNP values multiplied with their transposed selves. When applied to an read-from-disk SnpReader, such as :class:`.Bed`, + an ndarray of the (possibility standardized) SNP values multiplied with their transposed selves. When applied to a read-from-disk SnpReader, such as :class:`.Bed`, the method can save memory by reading (and standardizing) the data in blocks. See :meth:`read_kernel` for details. @@ -425,49 +430,59 @@ def _read( def read( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, _require_float32_64=True, + xp=None, ): - """Reads the SNP values and returns a :class:`.SnpData` (with :attr:`.SnpData.val` property containing a new ndarray of the SNP values). + """Reads the SNP values and returns a :class:`.SnpData` (with :attr:`.SnpData.val` property containing a NumPy or CuPy array of SNP values). :param order: {'F' (default), 'C', 'A'}, optional -- Specify the order of the ndarray. If order is 'F' (default), then the array will be in F-contiguous order (iid-index varies the fastest). If order is 'C', then the returned array will be in C-contiguous order (sid-index varies the fastest). If order is 'A', then the :attr:`.SnpData.val` ndarray may be in any order (either C-, Fortran-contiguous). - :type order: string or None + :type order: str - :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for the :attr:`SnpData.val` ndarray. + :param dtype: {None, numpy.float64, numpy.float32}, optional -- The data-type for the :attr:`SnpData.val` ndarray. (For :class:`Bed`, only, it can also be numpy.int8. Hidden option _require_float32_64 must be set to False. See :class:`Bed` for an example.) + None uses ARRAY_DTYPE, then float64; an explicit dtype overrides it. :type dtype: data-type. :param force_python_only: optional -- If False (default), may use outside library code. If True, requests that the read - be done without outside library code. + use a Python CPU path where supported. GPU BED reads reject True with ValueError; + this does not select a CPU backend. CuPy standardization ignores this flag. :type force_python_only: bool :param view_ok: optional -- If False (default), allocates new memory for the :attr:`SnpData.val`'s ndarray. If True, if practical and reading from a :class:`SnpData`, will return a new :class:`SnpData` with a ndarray shares memory with the original :class:`SnpData`. Typically, you'll also wish to use "order='A'" to increase the chance that sharing will be possible. - Use these parameters with care because any change to either ndarray (for example, via :meth:`.SnpData.standardize`) will effect + Use these parameters with care because any change to either ndarray (for example, via :meth:`.SnpData.standardize`) will affect the others. Also keep in mind that :meth:`read` relies on ndarray's mechanisms to decide whether to actually share memory and so it may ignore your suggestion and allocate a new ndarray anyway. :type view_ok: bool - :param num_threads: optional -- The number of threads with which to read data. Defaults to all available + :param num_threads: optional -- The CPU thread count (ignored by native GPU BED reads and CuPy math). Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. :type num_threads: None or int + :param xp: NumPy or CuPy module or name. An explicit value overrides + ARRAY_MODULE. Only None consults the environment; NumPy is the final default. + Each read selects independently of the source object's constructor. + Missing CuPy raises ImportError. See :doc:`/gpu` for complete examples. + :type xp: module, str, or None + :rtype: :class:`.SnpData` - Calling the method again causes the SNP values to be re-read and creates a new in-memory :class:`.SnpData` with a new ndarray of SNP values. + Each call creates a new :class:`.SnpData`. Values are read again from disk + or copied from memory unless ``view_ok=True`` allows shared storage. - If you request the values for only a subset of the sids or iids, (to the degree practical) only that subset will be read from disk. + If you request the values for only a subset of the rows or columns, (to the degree practical) only that subset will be read from disk. :Example: @@ -485,9 +500,10 @@ def read( >>> import numpy as np >>> # print np.may_share_memory(subset_snpdata.val, subsub_snpdata.val) # Do the two ndarray's share memory? They could. Currently they won't. """ - dtype = np.dtype(dtype) - val = self._read( - None, None, order, dtype, force_python_only, view_ok, num_threads + dtype = pstutil.array_dtype(dtype) + xp = pstutil.array_module(xp) + val = self._read_array( + None, None, order, dtype, force_python_only, view_ok, num_threads, xp ) from pysnptools.snpreader import SnpData @@ -497,10 +513,44 @@ def read( val, pos=self.pos, name=str(self), + xp=xp, _require_float32_64=_require_float32_64, ) return ret + def _read_array(self, row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads, xp): + """Read to the requested module without changing legacy reader overrides.""" + if not getattr(self, "_read_accepts_slices", False): + # None means an unsliced read, which some readers require. Only + # normalize actual indexers for readers that cannot consume slices. + if row_index is not None: + row_index = self._make_sparray_from_sparray_or_slice(self.row_count, row_index) + if col_index is not None: + col_index = self._make_sparray_from_sparray_or_slice(self.col_count, col_index) + val = self._read(row_index, col_index, order, dtype, + force_python_only, view_ok, num_threads) + # Preserve reader-specific arrays such as memmaps when no transfer is + # needed. The legacy _read contract already guarantees dtype and order. + if pstutil.get_array_module(val) is xp: + return val + if xp is np: + val = pstutil.asnumpy(val) + from pysnptools.util._array import asarray + return asarray(val, dtype=dtype, order=order, xp=xp) + + def _read_with_standardizing(self, standardizer, order="F", dtype=None, + xp=None, return_trained=False, + force_python_only=False, num_threads=None, + _row_index=None, _col_index=None): + """Internal read/standardize operation; Bed can keep both steps in CubeCL.""" + dtype = pstutil.array_dtype(dtype) + reader = self if _row_index is None and _col_index is None else self[_row_index, _col_index] + return reader.read(order=order, dtype=dtype, xp=xp, + force_python_only=force_python_only, num_threads=num_threads).standardize( + standardizer, return_trained=return_trained, + force_python_only=force_python_only, num_threads=num_threads) + def iid_to_index(self, list): """Takes a list of iids and returns a list of index numbers @@ -554,23 +604,54 @@ def read_kernel( standardizer=None, block_size=None, order="A", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, + xp=None, ): - """Returns a :class:`KernelData` such that the :meth:`KernelData.val` property will be a ndarray of the standardized SNP values multiplied with their transposed selves. + """Returns a :class:`KernelData` such that the :attr:`KernelData.val` property will be a ndarray of the standardized SNP values multiplied with their transposed selves. - :param standardizer: -- (required) Specify standardization to be applied before the matrix multiply. Any :class:`.Standardizer` may be used. Some choices include :class:`Standardizer.Identity` - (do nothing), :class:`.Unit` (make values for each SNP have mean zero and standard deviation 1.0) and :class:`Beta`. + :param standardizer: -- (required) Specify standardization to be applied before the matrix multiply. Any :class:`.Standardizer` may be used. Some choices include :class:`pysnptools.standardizer.Identity` + (do nothing), :class:`.Unit` (center/scale observed nonconstant values) and :class:`Beta`. + The standardizer must support the selected array module. With BetaTrained, + the full SNP IDs/order must match training; blocks reuse the corresponding + fitted moments without refitting them. :type standardizer: :class:`.Standardizer` - :param block_size: optional -- Default of None (meaning to load all). Suggested number of sids to read into memory at a time. + :param block_size: Positive integer SNP block size, or None (default) to load all. + Invalid values, including Boolean values, raise ValueError. + Limits SNP blocks, not the dense kernel or total GPU memory. A SnpKernel + subset can still construct the full kernel. See :doc:`/gpu` for memory limits. :type block_size: int or None - :rtype: class:`KernelData` + :param order: 'A' (default), 'C', or 'F' for the output kernel layout. + Blocked accumulation uses C order when A is requested. + :type order: str + :param dtype: Output floating dtype, float64 or float32. None uses ARRAY_DTYPE, + then float64; an explicit dtype overrides it. GPU + multiplication and accumulation use this dtype; statistics can use float64. + :type dtype: data-type + :param force_python_only: Request a Python CPU read/standardization path. + GPU BED reads reject True; it does not move computation to the CPU. + :type force_python_only: bool + :param view_ok: Accepted for reader compatibility; the kernel product + allocates new memory regardless of this suggestion. + :type view_ok: bool + :param num_threads: CPU thread count, or None for environment/default selection. + Ignored by native GPU BED reads and CuPy math. + :type num_threads: int or None - Calling the method again causes the SNP values to be re-read and allocates a new class:`KernelData`. + :param xp: NumPy or CuPy module or name. An explicit value overrides + ARRAY_MODULE. Only None consults the environment; NumPy is the final default. + Each read selects independently of the source object's constructor. + Missing CuPy raises ImportError. See :doc:`/gpu` for complete examples. + :type xp: module, str, or None + + :raises AssertionError: if standardizer is None. + :rtype: :class:`.KernelData` + + Calling the method again causes the SNP values to be re-read and allocates a new :class:`.KernelData`. When applied to an read-from-disk SnpReader, such as :class:`.Bed`, the method can save memory by reading (and standardizing) the data in blocks. @@ -586,13 +667,13 @@ def read_kernel( (300, '901.421836') """ assert standardizer is not None, "'standardizer' must be provided" - dtype = np.dtype(dtype) + dtype = pstutil.array_dtype(dtype) from pysnptools.kernelreader import SnpKernel snpkernel = SnpKernel(self, standardizer=standardizer, block_size=block_size) kerneldata = snpkernel.read( - order, dtype, force_python_only, view_ok, num_threads + order, dtype, force_python_only, view_ok, num_threads, xp=xp ) return kerneldata @@ -608,14 +689,14 @@ def kernel( Returns a ndarray of size iid_count x iid_count. The returned array has the value of the standardized SNP values multiplied with their transposed selves. - :param standardizer: -- Specify standardization to be applied before the matrix multiply. Any :class:`.Standardizer` may be used. Some choices include :class:`Standardizer.Identity` + :param standardizer: -- Specify standardization to be applied before the matrix multiply. Any :class:`.Standardizer` may be used. Some choices include :class:`pysnptools.standardizer.Identity` (do nothing), :class:`.Unit` (make values for each SNP have mean zero and standard deviation 1.0), :class:`Beta`. :type standardizer: :class:`.Standardizer` :param block_size: optional -- Default of 10000. None means to load all. Suggested number of sids to read into memory at a time. :type block_size: int or None - :param num_threads: optional -- The number of threads with which to standardize data. Defaults to all available + :param num_threads: optional -- The CPU reader/kernel thread count (ignored by CuPy math). Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. :type num_threads: None or int @@ -627,7 +708,7 @@ def kernel( When applied to an read-from-disk SnpReader, such as :class:`.Bed`, the method can save memory by reading (and standardizing) the data in blocks. - If you request the values for only a subset of the sids or iids, (to the degree practical) only that subset will be read from disk. + If you request the values for only a subset of the rows or columns, (to the degree practical) only that subset will be read from disk. :Example: @@ -655,16 +736,18 @@ def kernel( @staticmethod def _as_snpdata( - snpreader, standardizer, force_python_only, order, dtype, num_threads + snpreader, standardizer, force_python_only, order, dtype, num_threads, xp=None ): """ Like 'read' except (1) won't read if already a snpdata and (2) returns the standardizer """ - dtype = np.dtype(dtype) + dtype = pstutil.array_dtype(dtype) + xp = pstutil.array_module(xp) if ( hasattr(snpreader, "val") and snpreader.val.dtype == dtype + and pstutil.get_array_module(snpreader.val) is xp and isinstance(standardizer, stdizer.Identity) and ( order == "A" @@ -674,31 +757,31 @@ def _as_snpdata( ): return snpreader, stdizer.Identity() else: - return snpreader.read(order=order, dtype=dtype).standardize( - standardizer, - return_trained=True, - force_python_only=force_python_only, - num_threads=num_threads, - ) + return snpreader._read_with_standardizing( + standardizer, order=order, dtype=dtype, xp=xp, return_trained=True, + force_python_only=force_python_only, num_threads=num_threads) def _read_kernel( self, standardizer, block_size=None, order="A", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, return_trained=False, num_threads=None, + xp=None, ): """ Will respect the cupy environment variable. """ - dtype = np.dtype(dtype) - # Do all-at-once (not in blocks) if 1. No block size is given or 2. The #ofSNPs < Min(block_size,iid_count) + dtype = pstutil.array_dtype(dtype) + xp = pstutil.array_module(xp) + # Respect an explicit block size even when the SNP count is below iid_count. + # Do all-at-once only if no blocking was requested or one block covers the data. if block_size is None or ( - self.sid_count <= block_size or self.sid_count <= self.iid_count + self.sid_count <= block_size ): train_data, trained_standardizer = SnpReader._as_snpdata( self, @@ -706,7 +789,7 @@ def _read_kernel( dtype=dtype, order="A", force_python_only=force_python_only, - num_threads=num_threads, + num_threads=num_threads, xp=xp, ) kernel = train_data._read_kernel( stdizer.Identity(), @@ -714,20 +797,33 @@ def _read_kernel( dtype=dtype, force_python_only=force_python_only, view_ok=False, - num_threads=num_threads, + num_threads=num_threads, xp=xp, ) + if xp is not np: + xp.cuda.get_current_stream().synchronize() + # bed-reader returns the dropped data's GPU memory to CUDA, where + # CuPy's eigensolver can use it for its workspace. + del train_data if return_trained: return kernel, trained_standardizer else: return kernel else: # Do in blocks - xp = pstutil.array_module() + is_trained_beta = type(standardizer) is stdizer.BetaTrained + if is_trained_beta: + # Validate the whole SNP order before slicing moments. Positional + # slices also preserve distinct moments for repeated SNP IDs. + assert np.array_equal(standardizer.sid, self.sid), "sid in training and use must be the same and in the same order" + assert standardizer.stats.shape == (self.sid_count, 2), "stats must have size [sid_count,2]" # Set the default order to 'C' because with kernels any order is fine and the Python .dot method likes 'C' best. if order == "A": order = "C" t0 = time.time() - K = xp.zeros([self.iid_count, self.iid_count], dtype=dtype, order=order) + # Kernels are never standardized natively, so CuPy's own pool serves them. + from pysnptools.util._gpu_warnings import warn_gpu_float64 + warn_gpu_float64(dtype, xp) + K = xp.zeros((self.iid_count, self.iid_count), dtype=dtype, order=order) trained_standardizer_list = [] logging.info( f"reading {self.sid_count:,} SNPs in blocks of {block_size:,} and adding up kernels (for {self.iid_count:,} individuals) with {xp.__name__}." @@ -739,15 +835,23 @@ def _read_kernel( for start in range(0, self.sid_count, block_size): ct += block_size + block_standardizer = standardizer + if is_trained_beta: + selection = slice(start, start + block_size) + block_standardizer = stdizer.BetaTrained( + standardizer.a, standardizer.b, + standardizer.sid[selection], standardizer.stats[selection], + ) train_data, trained_standardizer = SnpReader._as_snpdata( self[:, start : start + block_size], - standardizer=standardizer, + standardizer=block_standardizer, dtype=dtype, order="A", force_python_only=force_python_only, - num_threads=num_threads, + num_threads=num_threads, xp=xp, ) - trained_standardizer_list.append(trained_standardizer) + if not is_trained_beta: + trained_standardizer_list.append(trained_standardizer) K += train_data._read_kernel( stdizer.Identity(), block_size=None, @@ -755,8 +859,13 @@ def _read_kernel( dtype=dtype, force_python_only=force_python_only, view_ok=False, - num_threads=num_threads, + num_threads=num_threads, xp=xp, ) + if xp is not np: + # CuPy and CubeCL use different streams. Finish the multiply + # before dropping/recycling a block that may be CubeCL-owned. + xp.cuda.get_current_stream().synchronize() + del train_data if ct % block_size == 0: diff = time.time() - ts if diff > 1 and diff - diff_last > 5: @@ -767,6 +876,8 @@ def _read_kernel( logging.info("%.2f seconds elapsed" % (t1 - t0)) if return_trained: + if is_trained_beta: + return K, standardizer return K, standardizer._merge_trained( trained_standardizer_list ) # turns this into a single standardizer diff --git a/pysnptools/standardizer/_cupy.py b/pysnptools/standardizer/_cupy.py new file mode 100644 index 0000000..e28ad52 --- /dev/null +++ b/pysnptools/standardizer/_cupy.py @@ -0,0 +1,33 @@ +"""Lazily compiled CuPy kernels; importing PySnpTools does not require CuPy.""" +from functools import lru_cache + + +@lru_cache(maxsize=1) +def _sum_squares_kernel(): + import cupy as cp + + # Normalization must propagate NaNs, unlike missing-aware SNP variance. + return cp.ReductionKernel( + "T value", "float64 total", "(double)value * (double)value", + "a + b", "total = a", "0", "normalization_sum_squares") + + +@lru_cache(maxsize=1) +def kernels(): + import cupy as cp + + count = cp.ReductionKernel( + "T value", "int64 count", "value == value ? 1LL : 0LL", + "a + b", "count = a", "0", "observed_count") + total = cp.ReductionKernel( + "T value", "float64 total", "value == value ? (double)value : 0.0", + "a + b", "total = a", "0", "observed_sum") + variance = cp.ReductionKernel( + "T value, float64 mean", "float64 total", + "value == value ? ((double)value - mean) * ((double)value - mean) : 0.0", + "a + b", "total = a", "0", "centered_sum") + apply = cp.ElementwiseKernel( + "T mean, T factor", "T value", + "value = value == value && factor != (T)0 ? (value - mean) * factor : (T)0", + "apply_standardize") + return count, total, variance, apply diff --git a/pysnptools/standardizer/beta.py b/pysnptools/standardizer/beta.py index ff83b76..a48ff40 100644 --- a/pysnptools/standardizer/beta.py +++ b/pysnptools/standardizer/beta.py @@ -1,3 +1,4 @@ +import pysnptools.util as pstutil import numpy as np import logging import warnings @@ -8,7 +9,12 @@ class Beta(Standardizer): """ A :class:`.Standardizer` to beta standardize SNP data. - See :class:`.Standardizer` for more information about standardization. + Subtract the observed mean and multiply by the beta density at the minor + allele frequency; this does not divide by standard deviation. Native and + CuPy paths zero constant columns, impute NaNs with zero, and reject wholly + missing training SNPs and means outside [0, 2]. The CuPy path keeps the + matrix on its device but computes per-SNP beta weights with SciPy on CPU. + See :class:`.Standardizer` and :doc:`/gpu` for options and complete examples. **Constructor:** :Parameters: * **a** (*float*) -- The *a* parameter of the beta distribution @@ -39,6 +45,13 @@ def standardize( force_python_only=False, num_threads=None, ): # !!!later why is the 2nd argument called 'snpdata' here, but 'snps' in unit.py? + """Apply Beta in place on the current array device. + + See :meth:`.Standardizer.standardize` for options and :doc:`/gpu` for + examples. Returns the input, or (input, BetaTrained) with NumPy stats when + return_trained=True. Direct block_size warns and is ignored. CuPy ignores + force_python_only and num_threads. Constant training columns remain zero, + including singular endpoint beta densities, on native and Python CPU paths.""" if block_size is not None: warnings.warn( "block_size is deprecated (and not needed, since standardization is in-place", @@ -71,7 +84,7 @@ def standardize( assert hasattr( snpdata, "val" ), "return_trained=True must be used with SnpData" - return snpdata, BetaTrained(self.a, self.b, snpdata.sid, stats) + return snpdata, BetaTrained(self.a, self.b, snpdata.sid, pstutil.asnumpy(stats)) else: return snpdata diff --git a/pysnptools/standardizer/betatrained.py b/pysnptools/standardizer/betatrained.py index c4278bb..17cef91 100644 --- a/pysnptools/standardizer/betatrained.py +++ b/pysnptools/standardizer/betatrained.py @@ -6,12 +6,17 @@ class BetaTrained(Standardizer): """A :class:`.Standardizer` to beta standardize one set of SNP data based on the mean of another set of SNP data - See :class:`.Standardizer` for more information about standardization. + Requires matching SNP IDs in exactly the training order (AssertionError + otherwise). Kernel construction may split a matching SNP list into blocks; + each block uses its corresponding fitted moments without refitting. Constant + training SNPs remain zero and NaNs become zero. + See :class:`.Standardizer` and :doc:`/gpu` for complete examples. **Constructor:** :Parameters: * **a** (*float*) -- The *a* parameter of the beta distribution * **b** (*float*) -- The *b* parameter of the beta distribution - * **stats** (*ndarray of float*) -- The mean and stddev of each sid + * **sid** (*array of strings*) -- Training SNP IDs, in order. + * **stats** (*ndarray of float*) -- Shape (sid_count, 2), training means and population stddevs. >>> from pysnptools.standardizer import Beta >>> from pysnptools.snpreader import Bed @@ -45,6 +50,11 @@ def is_constant(self): return True def standardize(self, snps, block_size=None, return_trained=False, force_python_only=False, num_threads=None): + """Apply the fitted Beta transform in place on the target array device. + + See :meth:`.Standardizer.standardize` for options and :doc:`/gpu` for + examples. Requires identical SNP IDs/order. Returns the input, or + (input, self) with return_trained=True.""" if block_size is not None: warnings.warn("block_size is deprecated (and not needed, since standardization is in-place", DeprecationWarning) diff --git a/pysnptools/standardizer/diag_K_to_N.py b/pysnptools/standardizer/diag_K_to_N.py index e8444f8..76b0a3b 100644 --- a/pysnptools/standardizer/diag_K_to_N.py +++ b/pysnptools/standardizer/diag_K_to_N.py @@ -1,3 +1,4 @@ +import pysnptools.util as pstutil import numpy as np from pysnptools.standardizer import Standardizer import logging @@ -6,16 +7,21 @@ class DiagKtoN(Standardizer): """ - Both a :class:`.Standardizer` and a A :class:`.KernelStandardizer`. + Both a :class:`.Standardizer` and a :class:`.KernelStandardizer`. When applied to a :class:`.SnpData`, it multiplies the SNP values by the square root of a factor such that a kernel constructed from the SNP values will have a diagonal that sums to iid_count. This class thus standardizes the kernel before it is even constructed. - When applied to a :class:`.KernelData`, it multiplies the kernel values by the a factor such that a kernel + When applied to a :class:`.KernelData`, it multiplies the kernel values by a factor such that a kernel will have a diagonal that sums to iid_count. - See :class:`.Standardizer` for more information about standardization. + Scaling follows the values' existing NumPy or CuPy device. This operation + rescales the whole matrix; it does not center each SNP. Use it on data with + a finite, positive kernel trace. Zero, negative, or nonfinite normalization + denominators, including empty inputs, raise ValueError before values change. + See :doc:`/gpu` for a complete GPU example + and :class:`.Standardizer` for more about standardization. **Constructor:** :Parameters: * **deprecated_iid_count** (*int*) (optional) -- Deprecated. @@ -23,6 +29,7 @@ class DiagKtoN(Standardizer): Example of DiagKtoN to :class:`.SnpData`: + >>> import numpy as np >>> from pysnptools.standardizer import DiagKtoN, Unit, Identity >>> from pysnptools.snpreader import Bed >>> from pysnptools.util import example_file # Download and return local file name @@ -63,7 +70,10 @@ def _standardize_kernel( force_python_only=False, num_threads=None, ): - factor = float(kerneldata.iid_count) / np.diag(kerneldata.val).sum() + xp = pstutil.get_array_module(kerneldata.val) + trace = (np.diag(kerneldata.val).sum() if xp is np + else float(xp.diag(kerneldata.val).sum(dtype=np.float64))) + factor = _normalization_factor(kerneldata.iid_count, trace) if abs(factor - 1.0) > 1e-15: kerneldata._val *= factor @@ -118,8 +128,14 @@ def _standardize_snps( vec = val.reshape(-1, order="A") # make sure no copy was made assert not vec.flags["OWNDATA"] - squared_sum = vec.dot(vec) - factor = float(val.shape[0]) / squared_sum + # Accumulate in float64 without a matrix-sized float64 temporary. + xp = pstutil.get_array_module(val) + if xp is np: + squared_sum = vec.dot(vec) + else: + from pysnptools.standardizer._cupy import _sum_squares_kernel + squared_sum = float(_sum_squares_kernel()(vec)) + factor = _normalization_factor(val.shape[0], squared_sum) if abs(factor - 1.0) > 1e-15: val *= np.sqrt(factor) @@ -135,16 +151,18 @@ def __repr__(self): # !!!move to its own file class DiagKtoNTrained(Standardizer): - """Both a :class:`.Standardizer` and a A :class:`.KernelStandardizer`. + """Both a :class:`.Standardizer` and a :class:`.KernelStandardizer`. When applied to a :class:`.SnpData`, DiagKtoN standardizes one set of SNP data based on another set of SNP data. When applied to a :class:`.KernelData`, DiagKtoN standardizes one kernel data based on another kernel data. - See :class:`.Standardizer` for more information about standardization. + Reuses the fitted scalar on the values' existing NumPy or CuPy device, + without refitting it from the target data. The target kernel's trace need + not equal its sample count. See :class:`.DiagKtoN` for a fitting example. **Constructor:** - :Parameters: * **factor** (*float*) -- The number what when multiplied into the kernel values will make the diagonal of the kernel values to sum to iid_count. + :Parameters: * **factor** (*float*) -- Fitted kernel scale. SNP values are multiplied by its square root. """ @@ -226,6 +244,17 @@ def __repr__(self): return "{0}({1})".format(self.__class__.__name__, self.factor) +def _normalization_factor(sample_count, denominator): + # Validate the existing reduction result: no extra matrix scan or transfer. + if sample_count == 0 or not np.isfinite(denominator) or denominator <= 0: + raise ValueError("DiagKtoN requires a finite, positive normalization denominator and at least one sample") + # Preserve the CPU reduction's scalar dtype and its established rounding. + factor = float(sample_count) / denominator + if not np.isfinite(factor) or factor <= 0: + raise ValueError("DiagKtoN normalization factor must be finite and positive") + return factor + + if __name__ == "__main__": logging.basicConfig(level=logging.INFO) diff --git a/pysnptools/standardizer/standardizer.py b/pysnptools/standardizer/standardizer.py index 73e2804..7de78e1 100644 --- a/pysnptools/standardizer/standardizer.py +++ b/pysnptools/standardizer/standardizer.py @@ -5,6 +5,14 @@ from bed_reader import get_num_threads, standardize_f64, standardize_f32 +def _check_observed(imissX): + # Match the Rust standardizer, which raises for a SNP with no observed values. (The + # Python path, used for cupy arrays, would otherwise silently set that SNP to 0.) + observed_count = (~imissX).sum(axis=0) + if bool((observed_count == 0).any()): + raise ValueError("No individual observed for the SNP.") + + class Standardizer(object): """ A Standardizer is a class such as :class:`.Unit` and :class:`.Beta` to be used by the :meth:`.SnpData.standardize` and :meth:`.SnpReader.read_kernel` method to standardize SNP data. @@ -66,27 +74,32 @@ def standardize( num_threads=None, ): """ - Applies standardization, in place, to :class:`.SnpData` (or a NumPy array). For convenience also returns the :class:`.SnpData` (or a NumPy array). + Applies standardization in place on the existing NumPy/CuPy device. + Returns the same input, or (input, trained standardizer) when requested. + Raw arrays remain accepted but are deprecated; return_trained=True for + Unit/Beta requires SnpData. Values must be contiguous float32/float64. + See :doc:`/gpu` for complete examples and Unit/Beta exceptions. - :param snps: SNP values to standardize - :type snps: :class:`.SnpData` (or a NumPy array) + :param snps: SNP values to standardize, on their existing device + :type snps: :class:`.SnpData` (or a NumPy/CuPy array) - :param block_size: *Not used* + :param block_size: Deprecated and ignored; direct Unit/Beta calls warn. :type block_size: None :param return_trained: If true, returns a second value containing a constant standardizer trained on this data. :type return_trained: bool - :param force_python_only: optional -- If False (default), may use outside library code. If True, requests that the read - be done without outside library code. + :param force_python_only: Request Python CPU standardization where supported. + Ignored by CuPy, which stays on its current device. This is not a + backend switch; see :doc:`/gpu` for CPU Beta fallback limitations. :type force_python_only: bool - :param num_threads: optional -- The number of threads with which to standardize data. Defaults to all available + :param num_threads: optional -- The CPU standardization thread count (ignored for CuPy). Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. :type num_threads: None or int - :rtype: :class:`.SnpData` (or a NumPy array), (optional) constant :class:`.Standardizer` + :rtype: SnpData or array, or a tuple with a trained Standardizer """ if block_size is not None: @@ -114,7 +127,7 @@ def _standardize_unit_and_beta( force_python_only=False, ): """ - When snps is a cupy ndarray, will use cupy to compute new stats for unit. (Other paths are not defined for cupy) + Dispatch Unit/Beta training and application from the actual array module. """ xp = pstutil.get_array_module(snps) @@ -122,6 +135,18 @@ def _standardize_unit_and_beta( snps.flags["C_CONTIGUOUS"] or snps.flags["F_CONTIGUOUS"] ), "Expect snps to be order 'C' or order 'F'" + if xp is not np: + from pysnptools.util._gpu_warnings import warn_gpu_float64 + warn_gpu_float64(snps.dtype, xp) + if apply_in_place and not use_stats: + from pysnptools.util._array import native_owner + owner = native_owner(snps) + if owner is not None: + from bed_reader import bed_reader as native + return native.standardize_gpu(owner, is_beta, a, b) + return Standardizer._standardize_cupy( + snps, is_beta, a, b, apply_in_place, use_stats, stats, xp) + # Make sure stats is the same type as snps. Because we might be creating a new array, we return it if stats is None: stats = xp.empty( @@ -132,10 +157,10 @@ def _standardize_unit_and_beta( elif not ( stats.dtype == snps.dtype # stats must have the same dtype as snps and (stats.flags["OWNDATA"]) # stats must own its data - and (snps.flags["C_CONTIGUOUS"] and stats.flags["C_CONTIGUOUS"]) - or ( - snps.flags["F_CONTIGUOUS"] and stats.flags["F_CONTIGUOUS"] - ) # stats must have the same order as snps + and ( + (snps.flags["C_CONTIGUOUS"] and stats.flags["C_CONTIGUOUS"]) + or (snps.flags["F_CONTIGUOUS"] and stats.flags["F_CONTIGUOUS"]) + ) # Both layouts also require the matching dtype and ownership above. ): stats = xp.array( stats, @@ -202,6 +227,61 @@ def _standardize_unit_and_beta( ) return stats + @staticmethod + def _standardize_cupy(snps, is_beta, beta_a, beta_b, apply_in_place, + use_stats, stats, xp): + """Use reductions and an in-place update, with only per-SNP workspaces. + + Centered float64 reductions also support dosages and large offsets without + the cancellation in E[x*x] - E[x]**2. Transpose F-order inputs so the + elementwise update traverses contiguous memory. + """ + from pysnptools.standardizer._cupy import kernels + + if snps.dtype not in (np.float32, np.float64): + raise ValueError("Standardizing requires float32 or float64") + count_kernel, sum_kernel, variance_kernel, apply_kernel = kernels() + values = snps.T if snps.flags["F_CONTIGUOUS"] else snps + axis = 1 if snps.flags["F_CONTIGUOUS"] else 0 + expand = (lambda vector: vector[:, None]) if axis == 1 else (lambda vector: vector[None, :]) + if use_stats: + stats = xp.asarray(stats, dtype=snps.dtype) + else: + count = count_kernel(values, axis=axis) + if bool((count == 0).any()): + raise ValueError("No individual observed for the SNP.") + mean = sum_kernel(values, axis=axis) / count + variance = variance_kernel(values, expand(mean), axis=axis) / count + deviation = xp.sqrt(variance).astype(snps.dtype) + deviation[deviation == 0] = xp.inf + stats = xp.empty((snps.shape[1], 2), dtype=snps.dtype) + stats[:, 0] = mean + stats[:, 1] = deviation + if bool(xp.isnan(stats[:, 0]).any()) or (is_beta and bool( + ((stats[:, 0] < 0) | (stats[:, 0] > 2)).any())): + raise ValueError("Illegal SNP mean.") + if stats.shape != (snps.shape[1], 2): + raise ValueError("stats must have size [sid_count,2]") + if apply_in_place: + if is_beta: + import scipy.stats as st + + # Match statrs' Beta parameter validation used by native Rust. + if (np.isnan(beta_a) or np.isnan(beta_b) or beta_a <= 0 or beta_b <= 0 + or (np.isinf(beta_a) and np.isinf(beta_b))): + raise ValueError(f"Cannot create Beta distribution with a={beta_a}, b={beta_b}") + mean = pstutil.asnumpy(stats[:, 0]) + maf = mean / 2.0 + maf = np.minimum(maf, 1.0 - maf) + factor = xp.asarray(st.beta.pdf(maf, beta_a, beta_b), dtype=snps.dtype) + # CPU Rust zeros constant columns even for singular Beta PDFs + # at mean 0 or 2, and when applying trained statistics. + factor[xp.isinf(stats[:, 1])] = 0 + else: + factor = 1 / stats[:, 1] + apply_kernel(expand(stats[:, 0]), expand(factor), values) + return stats + @staticmethod def _standardize_unit_python(snps, apply_in_place, use_stats, stats): """ @@ -221,6 +301,7 @@ def _standardize_unit_python(snps, apply_in_place, use_stats, stats): snp_mean = stats[:, 0] snp_std = stats[:, 1] else: + _check_observed(imissX) snp_std = xp.nanstd(snps, axis=0) snp_mean = xp.nanmean(snps, axis=0) # avoid div by 0 when standardizing @@ -240,7 +321,7 @@ def _standardize_unit_python(snps, apply_in_place, use_stats, stats): @property def is_constant(self): """ - Tell if a standardizer's statistics are constant. For example, :class:`.Unit_Trained` contains a pre-specified mean and stddev for each SNP, so :attr:`Unit_Trained.is_constant` is True. + Tell if a standardizer's statistics are constant. For example, :class:`.UnitTrained` contains a pre-specified mean and stddev for each SNP, so :attr:`UnitTrained.is_constant` is True. :class:`.Unit`, on the other hand, measures the mean and stddev for each SNP, so :attr:`Unit.is_constant` is False. :rtype: bool @@ -257,6 +338,7 @@ def _standardize_beta_python(snps, betaA, betaB, apply_in_place, use_stats, stat np.float32, ], "snps must be a float in order to standardize in place." + xp = pstutil.get_array_module(snps) imissX = np.isnan(snps) snp_sum = np.nansum(snps, axis=0) n_obs_sum = (~imissX).sum(0) @@ -265,6 +347,7 @@ def _standardize_beta_python(snps, betaA, betaB, apply_in_place, use_stats, stat snp_mean = stats[:, 0] snp_std = stats[:, 1] else: + _check_observed(imissX) snp_mean = (snp_sum * 1.0) / n_obs_sum snp_std = np.sqrt(np.nansum((snps - snp_mean) ** 2, axis=0) / n_obs_sum) if 0.0 in snp_std: @@ -281,7 +364,12 @@ def _standardize_beta_python(snps, betaA, betaB, apply_in_place, use_stats, stat # avoid div by 0 when standardizing import scipy.stats as st - maf_beta = st.beta.pdf(maf, betaA, betaB) + # scipy needs numpy; maf has one value per SNP, so the round trip is cheap. + maf_beta = xp.asarray(st.beta.pdf(pstutil.asnumpy(maf), betaA, betaB)) + # Constant training SNPs need zero weight before multiplication: + # endpoint Beta densities can be infinite, so even centered zeros + # would otherwise produce NaNs (and varying test values infinities). + maf_beta[snp_std == np.inf] = 0.0 # print("BetaPdf[{0},{1},{2}]={3}".format(maf,betaA,betaB,maf_beta)) snps -= snp_mean snps *= maf_beta diff --git a/pysnptools/standardizer/unit.py b/pysnptools/standardizer/unit.py index 6fb58a0..49ad113 100644 --- a/pysnptools/standardizer/unit.py +++ b/pysnptools/standardizer/unit.py @@ -6,8 +6,11 @@ import pysnptools.util as pstutil class Unit(Standardizer): - """A :class:`.Standardizer` to unit standardize SNP data. For each sid, the mean of the values is zero with standard deviation 1. - NaN values are then filled with zero, the mean (consequently, if there are NaN values, the final standard deviation will not be zero. + """A :class:`.Standardizer` to unit standardize SNP data. Observed nonconstant values are centered and scaled to standard deviation one. + Observed values use population standard deviation (ddof=0); NaNs then become + zero, so final variance can be below one. Constant columns become zero; + wholly missing training columns raise ValueError. NumPy/CuPy arrays stay on + their device, regardless of ARRAY_MODULE. See :doc:`/gpu` for complete examples. See :class:`.Standardizer` for more information about standardization. @@ -27,15 +30,19 @@ def __repr__(self): def standardize(self, snps, block_size=None, return_trained=False, force_python_only=False, num_threads=None): ''' - When cupy environment variable is set, will use cupy. + Standardize on the array's current device, in place. + + See :meth:`.Standardizer.standardize` for shared options and :doc:`/gpu` + for complete examples. Returns the input, or (input, UnitTrained) when + return_trained=True. The trained stats are NumPy arrays. Direct + block_size arguments warn and are ignored; force_python_only and + num_threads do not change CuPy execution. ''' - xp = pstutil.array_module() # Get array module based on any ARRAY_MODULE environ variable. if block_size is not None: warnings.warn("block_size is deprecated (and not needed, since standardization is in-place", DeprecationWarning) if hasattr(snps,"val"): - snps._val = xp.asarray(snps.val) #If cupy, replace SnpData's val with cupy array val = snps.val else: warnings.warn("standardizing an ndarray instead of a SnpData is deprecated", DeprecationWarning) @@ -46,7 +53,7 @@ def standardize(self, snps, block_size=None, return_trained=False, force_python_ if return_trained: assert hasattr(snps,"val"), "return_trained=True requires that snps be a SnpData" - return snps, UnitTrained(snps.sid, stats) + return snps, UnitTrained(snps.sid, pstutil.asnumpy(stats)) else: return snps diff --git a/pysnptools/standardizer/unittrained.py b/pysnptools/standardizer/unittrained.py index e8a968f..deba29e 100644 --- a/pysnptools/standardizer/unittrained.py +++ b/pysnptools/standardizer/unittrained.py @@ -8,10 +8,14 @@ class UnitTrained(Standardizer): """A :class:`.Standardizer` to unit standardize one set of SNP data based on the mean and stddev of another set of SNP data. NaN values are then filled with zero. - See :class:`.Standardizer` for more information about standardization. + Known SNP IDs can be selected or reordered; unknown IDs raise KeyError. + Training moments are reused without refitting. Infinite stored deviation + marks a training constant and zeros later values, including varying ones. + See :class:`.Standardizer` and :doc:`/gpu` for complete examples. **Constructor:** - :Parameters: * **stats** (*ndarray of float*) -- The mean and stddev of each sid + :Parameters: * **sid** (*array of strings*) -- Unique training SNP IDs. + * **stats** (*ndarray of float*) -- Shape (sid_count, 2), training means and population stddevs. >>> from pysnptools.standardizer import Unit >>> from pysnptools.snpreader import Bed @@ -55,6 +59,11 @@ def standardize( force_python_only=False, num_threads=None, ): + """Apply the training moments in place on the target array device. + + See :meth:`.Standardizer.standardize` for options and :doc:`/gpu` for + examples. SnpData IDs are mapped to training statistics; missing IDs raise + KeyError. Returns the input, or (input, self) with return_trained=True.""" if block_size is not None: warnings.warn( "block_size is deprecated (and not needed, since standardization is in-place", diff --git a/pysnptools/test.py b/pysnptools/test.py index 8d5d24d..2a9adac 100644 --- a/pysnptools/test.py +++ b/pysnptools/test.py @@ -31,6 +31,7 @@ from pysnptools.util.test import TestUtilTools from pysnptools.util.filecache.test import TestFileCache from pysnptools.util.filecache.test_hashdown_retry import TestHashdownRetry +from pysnptools.util.mapreduce1.test_threads import TestRunnerThreads from pysnptools.distreader.test import TestDistReaders import unittest @@ -38,6 +39,266 @@ import time +class TestBetaPython(unittest.TestCase): + def test_empty_data_factory(self): + from pysnptools.snpreader import SnpData + from pysnptools.kernelreader import KernelData + + source = SnpData(iid=[], sid=["s0", "s1"], val=None, xp=np) + kernel = KernelData(iid=[], val=None, xp=np) + for target, shape in ((source, (0, 2)), (kernel, (0, 0))): + self.assertIsInstance(target.val, np.ndarray) + self.assertEqual(target.val.dtype, np.float64) + self.assertEqual(target.val.shape, shape) + + def test_trained_statistics_across_dtypes(self): + from pysnptools.snpreader import SnpData + + iid = [["family", str(sample)] for sample in range(3)] + sid = ["variable", "dosage", "constant"] + training_values = [[0, 0.25, 1], [1, 1, 1], [2, 1.75, np.nan]] + test_values = [[0.5, np.nan, 0], [1.75, 0.25, 2], [np.nan, 1.25, 1]] + for training_dtype, target_dtype in ((np.float32, np.float64), (np.float64, np.float32)): + for order in ("C", "F"): + for standardizer in (Unit(), Beta(2, 3)): + training = SnpData(iid=iid, sid=sid, xp=np, + val=np.array(training_values, dtype=training_dtype, order=order)) + _, trained = training.standardize(standardizer, return_trained=True) + original_stats = trained.stats.copy() + # Stored moments are rounded to the target's supported dtype. + means, deviations = trained.stats.astype(target_dtype).astype(np.float64).T + if isinstance(standardizer, Unit): + factors = 1 / deviations + else: + frequencies = np.minimum(means / 2, 1 - means / 2) + factors = 12 * frequencies * (1 - frequencies) ** 2 + factors[np.isinf(deviations)] = 0 + expected = (np.array(test_values) - means) * factors + expected[np.isnan(test_values)] = 0 + for force_python_only in (False, True): + with self.subTest(training_dtype=training_dtype, target_dtype=target_dtype, + order=order, standardizer=standardizer, + force_python_only=force_python_only): + target = SnpData(iid=iid, sid=sid, xp=np, + val=np.array(test_values, dtype=target_dtype, order=order)) + self.assertIs(target.standardize(trained, force_python_only=force_python_only), target) + self.assertEqual(target.val.dtype, target_dtype) + # Small bounded inputs; allow arithmetic and density roundoff. + tolerance = 32 * np.finfo(target_dtype).eps + np.testing.assert_allclose(target.val, expected, rtol=tolerance, atol=tolerance) + np.testing.assert_array_equal(trained.stats, original_stats) + self.assertEqual(trained.stats.dtype, training_dtype) + + def test_blocked_trained_kernel(self): + self._check_blocked_trained_kernel(np) + + def test_blocked_trained_kernel_cupy(self): + try: + import cupy + except ModuleNotFoundError: + self.skipTest("requires CuPy and a working CUDA GPU") + self._check_blocked_trained_kernel(cupy) + + def _check_blocked_trained_kernel(self, xp): + from scipy.stats import beta as beta_distribution + from pysnptools.kernelreader import SnpKernel + from pysnptools.snpreader import SnpData + from pysnptools.standardizer import BetaTrained + from pysnptools.util import asnumpy + + training_values = np.array([ + [0, 2, 1, 0, 0.25, 0, 2], + [0, 2, 1, 0, 0.5, 1, 2], + [0, 2, 1, 1, 1.75, 1, 1], + [np.nan, 2, 1, 1, 1.5, 2, np.nan], + [0, np.nan, 1, 2, 0.75, np.nan, 2], + [0, 2, 1, np.nan, 1, 1, 2], + ]) + # Test means differ from training means; constant training SNPs vary here. + values = np.array([ + [0, 1, 2, 2, 1.75, 2, 0], + [1, 2, 0, 1, np.nan, 2, 1], + [2, 0, 1, 2, 1.5, 0, 0], + [np.nan, 1, 0, np.nan, 1, 1, np.nan], + ]) + # Repeated IDs have distinct moments, so positional correspondence matters. + sid = ["constant0", "constant2", "constant1", "repeated", "dosage", "other", "repeated"] + iid = [["family", str(sample)] for sample in range(len(values))] + for dtype in (np.float32, np.float64): + for order in ("C", "F"): + for beta_a, beta_b in ((0.5, 0.5), (1, 25)): + training = SnpData(iid=[["train", str(sample)] for sample in range(len(training_values))], + sid=sid, val=np.array(training_values, dtype=dtype, order=order), xp=np) + _, trained = training.standardize(Beta(beta_a, beta_b), return_trained=True) + original_stats = trained.stats.copy() + standardized = np.zeros(values.shape, dtype=dtype) + for column in range(3, len(sid)): + mean = dtype(np.nanmean(training_values[:, column])) + minor_frequency = min(float(mean) / 2, 1 - float(mean) / 2) + weight = dtype(beta_distribution.pdf(minor_frequency, beta_a, beta_b)) + observed = ~np.isnan(values[:, column]) + standardized[observed, column] = (values[observed, column].astype(dtype) - mean) * weight + expected = standardized @ standardized.T + reader = SnpData(iid=iid, sid=sid, val=xp.array(values, dtype=dtype, order=order), xp=xp) + # Seven SNP products and block additions contribute rounding. + tolerance = 64 * np.finfo(dtype).eps + unblocked = reader.read_kernel(trained, dtype=dtype, order=order, xp=xp).val + # The native statrs Beta(1,25) density differs from SciPy's + # by about 1.5e-13 relatively here, even without blocking. + # Keep the block comparison at floating-point roundoff; + # allow that library difference only in the independent check. + reference_tolerance = max(tolerance, 1e-12) if xp is np and beta_a == 1 else tolerance + np.testing.assert_allclose(asnumpy(unblocked), expected, + rtol=reference_tolerance, atol=reference_tolerance * len(sid)) + for block_size in (1, 3, 9): + with self.subTest(backend=xp.__name__, dtype=dtype, order=order, + beta_a=beta_a, beta_b=beta_b, block_size=block_size): + kernel = reader.read_kernel(trained, block_size=block_size, dtype=dtype, order=order, xp=xp) + self.assertIsInstance(kernel.val, xp.ndarray) + self.assertEqual(kernel.val.dtype, dtype) + self.assertTrue(kernel.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"]) + np.testing.assert_allclose(asnumpy(kernel.val), asnumpy(unblocked), rtol=tolerance, atol=tolerance * len(sid)) + specified = SnpKernel(reader, trained, block_size=block_size).read(dtype=dtype, order=order, xp=xp) + np.testing.assert_allclose(asnumpy(specified.val), asnumpy(unblocked), rtol=tolerance, atol=tolerance * len(sid)) + result, returned = reader._read_kernel(trained, block_size=block_size, dtype=dtype, + order=order, xp=xp, return_trained=True) + self.assertIs(returned, trained) + np.testing.assert_allclose(asnumpy(result), asnumpy(unblocked), rtol=tolerance, atol=tolerance * len(sid)) + np.testing.assert_array_equal(trained.stats, original_stats) + np.testing.assert_array_equal(trained.sid, sid) + # Blocking must not turn an invalid full-cohort alignment into + # an accepted subset, permutation, or unknown SNP selection. + for selection in (reader[:, :-1], reader[:, ::-1], + SnpData(iid=iid, sid=["unknown"] + sid[1:], val=values, xp=np)): + with self.assertRaisesRegex(AssertionError, "sid in training and use"): + selection.read_kernel(trained, block_size=3, dtype=dtype, xp=xp) + wrong_stats = BetaTrained(beta_a, beta_b, trained.sid, + np.concatenate([trained.stats, trained.stats[:1]])) + with self.assertRaisesRegex(AssertionError, "stats must have size"): + reader.read_kernel(wrong_stats, block_size=3, dtype=dtype, xp=xp) + + def test_constant_columns(self): + from scipy.stats import beta as beta_distribution + from pysnptools.snpreader import SnpData + + values = np.array([ + [0, 2, 1, 0, 0.25], + [0, 2, 1, 1, 0.5], + [np.nan, 2, 1, 2, 1.75], + [0, np.nan, 1, np.nan, 1.5], + ]) + iid = [["family", str(sample)] for sample in range(len(values))] + sid = ["constant0", "constant2", "constant1", "genotype", "dosage"] + for dtype in (np.float32, np.float64): + for order in ("C", "F"): + for beta_a, beta_b in ((0.5, 0.5), (0.5, 2), (2, 0.5), (1, 25)): + with self.subTest(dtype=dtype, order=order, beta_a=beta_a, beta_b=beta_b): + expected = np.zeros(values.shape, dtype=dtype, order=order) + for column in (3, 4): + observed = ~np.isnan(values[:, column]) + mean = values[observed, column].mean() + minor_frequency = min(mean / 2, 1 - mean / 2) + weight = beta_distribution.pdf(minor_frequency, beta_a, beta_b) + expected[observed, column] = (values[observed, column] - mean) * weight + # These well-scaled columns need only a few rounded operations. + tolerance = 32 * np.finfo(dtype).eps + standardizer = Beta(beta_a, beta_b) + for python_only in (False, True): + data = SnpData(iid=iid, sid=sid, val=np.array(values, dtype=dtype, order=order), xp=np) + with np.errstate(invalid="raise"): + result, trained = data.standardize( + standardizer, return_trained=True, force_python_only=python_only + ) + self.assertIs(result, data) + self.assertEqual(data.val.dtype, dtype) + self.assertTrue(data.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"]) + np.testing.assert_array_equal(data.val[:, :3], 0) + np.testing.assert_allclose(data.val, expected, rtol=tolerance, atol=tolerance) + np.testing.assert_array_equal(trained.stats[:3, 0], [0, 2, 1]) + self.assertTrue(np.isinf(trained.stats[:3, 1]).all()) + + changed = np.array(values, dtype=dtype, order=order) + changed[:, :3] = [[0, 1, 2], [1, 2, 0], [2, 0, 1], [np.nan, 1, 0]] + fresh = SnpData(iid=iid, sid=sid, val=changed, xp=np) + with np.errstate(invalid="raise"): + fresh.standardize(trained, force_python_only=True) + np.testing.assert_allclose(fresh.val, expected, rtol=tolerance, atol=tolerance) + + # A contiguous view of a larger allocation automatically uses + # the Python path even when force_python_only is False. + shape = (5, 5) if order == "C" else (4, 6) + backing = np.empty(shape, dtype=dtype, order=order) + view = backing[:4, :5] + view[:] = values + self.assertTrue(view.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"]) + fallback = SnpData(iid=iid, sid=sid, val=view, xp=np) + with np.errstate(invalid="raise"): + fallback.standardize(standardizer) + np.testing.assert_allclose(fallback.val, expected, rtol=tolerance, atol=tolerance) + + +class TestDiagKtoN(unittest.TestCase): + def test_diagKtoN_invalid_denominator(self): + self._check_diagKtoN_denominator(np) + + def test_diagKtoN_invalid_denominator_cupy(self): + try: + import cupy + except ModuleNotFoundError: + self.skipTest("requires CuPy and a working CUDA GPU") + self._check_diagKtoN_denominator(cupy) + + def _check_diagKtoN_denominator(self, xp): + from pysnptools.kernelreader import KernelData + from pysnptools.snpreader import SnpData + from pysnptools.standardizer import DiagKtoN + from pysnptools.util import asnumpy + + def data(values, dtype, order, kernel): + iid = [["family", str(sample)] for sample in range(values.shape[0])] + val = xp.array(values, dtype=dtype, order=order) + if kernel: + return KernelData(iid=iid, val=val, xp=xp) + return SnpData(iid=iid, sid=[str(marker) for marker in range(values.shape[1])], val=val, xp=xp) + + for dtype in (np.float32, np.float64): + for order in ("C", "F"): + for kernel in (False, True): + invalid = [np.zeros((2, 2)), np.array([[np.nan, 0], [0, 1]]), + np.array([[np.inf, 0], [0, 1]]), np.empty((0, 0))] + if kernel: + invalid.append(-np.eye(2)) + else: + invalid.extend([np.empty((0, 2)), np.empty((2, 0))]) + for values in invalid: + for return_trained in (False, True): + with self.subTest(backend=xp.__name__, dtype=dtype, order=order, + kernel=kernel, values=values, return_trained=return_trained): + target = data(values, dtype, order, kernel) + with self.assertRaisesRegex(ValueError, "finite, positive normalization denominator"): + target.standardize(DiagKtoN(), return_trained=return_trained) + np.testing.assert_array_equal(asnumpy(target.val), values) + + # Independently known scales: kernel trace 8 -> factor 1/4; + # SNP sum of squares 4 -> factor 1/2, applied as sqrt(1/2). + values = np.array([[4., 2.], [2., 4.]]) if kernel else np.array([[-1., 1.], [1., -1.]]) + factor = 0.25 if kernel else 0.5 + expected = values * (factor if kernel else np.sqrt(factor)) + target = data(values, dtype, order, kernel) + result, trained = target.standardize(DiagKtoN(), return_trained=True) + self.assertIs(result, target) + self.assertEqual(trained.factor, factor) + self.assertEqual(target.val.dtype, dtype) + self.assertTrue(target.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"]) + # One scalar multiplication; allow sqrt and multiplication roundoff. + np.testing.assert_allclose(asnumpy(target.val), expected, + rtol=8 * np.finfo(dtype).eps, atol=0) + # Applying a fitted scale to zero test data does not refit it. + zero = data(np.zeros((2, 2)), dtype, order, kernel) + zero.standardize(trained) + np.testing.assert_array_equal(asnumpy(zero.val), 0) + + class TestPySnpTools(unittest.TestCase): def xtest_aaa_hdf5_speed(self): # !!too slow to use all the time # currentFolder + "/examples/toydata.5chrom.bed" @@ -1568,11 +1829,14 @@ def getTestSuite(): """ test_suite = unittest.TestSuite([]) + test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestBetaPython)) + test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestDiagKtoN)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestPySnpTools)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestDistReaders)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestDistributedBed)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestFileCache)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestHashdownRetry)) + test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestRunnerThreads)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestUtilTools)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestIntRangeSet)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestSnpDocStrings)) diff --git a/pysnptools/test_array_dtype.py b/pysnptools/test_array_dtype.py new file mode 100644 index 0000000..bc0912e --- /dev/null +++ b/pysnptools/test_array_dtype.py @@ -0,0 +1,118 @@ +"""Resolve precision consistently across readers, kernels, and constructors.""" +import numpy as np +import pytest +import bed_reader +from pysnptools.kernelreader import KernelData, SnpKernel +from pysnptools.pstreader import PstData +from pysnptools.snpreader import SnpData, Bed, Pheno +from pysnptools.standardizer import Identity, Unit +from pysnptools.util import array_dtype, sub_matrix + + +def source(xp=np): + return SnpData(iid=[["f", str(sample)] for sample in range(3)], sid=["a", "b"], + val=np.array([[0., 1.], [1., 0.], [2., 2.]], dtype=np.float64), xp=xp) + + +@pytest.mark.parametrize("configured", ["float32", "float64"]) +@pytest.mark.parametrize("backend", ["numpy", "cupy"]) +def test_read_and_kernel_defaults(monkeypatch, configured, backend): + xp = np if backend == "numpy" else pytest.importorskip("cupy") + if backend == "cupy" and not bed_reader.has_gpu_support(): + pytest.skip("requires the cubecl-cuda Cargo feature") + monkeypatch.setenv("ARRAY_MODULE", backend) + monkeypatch.setenv("ARRAY_DTYPE", configured) + snps = source(xp) + readers = [snps, Bed(bed_reader.sample_file("small.bed"), count_A1=True), + KernelData(iid=snps.iid, val=np.eye(3), xp=xp), SnpKernel(snps, Identity())] + for reader in readers: + result = reader.read(xp=xp) + assert result.val.dtype == np.dtype(configured) + assert isinstance(result.val, xp.ndarray) + assert reader.read(dtype="float64", xp=xp).val.dtype == np.float64 + assert reader.read(dtype="float32", xp=xp).val.dtype == np.float32 + assert snps.read_kernel(Identity(), xp=xp).val.dtype == np.dtype(configured) + assert SnpKernel(snps, Unit()).read_snps(xp=xp).val.dtype == np.dtype(configured) + assert sub_matrix(snps.val, [2, 0], [1, 0]).dtype == np.dtype(configured) + # Existing arrays/standardizers keep their dtype instead of following a new default. + assert snps.val.dtype == np.float64 + snps.standardize() + assert snps.val.dtype == np.float64 + + +def test_generic_reader_and_untyped_containers(monkeypatch): + monkeypatch.setenv("ARRAY_MODULE", "numpy") + monkeypatch.setenv("ARRAY_DTYPE", "float32") + generic = PstData(row=["r"], col=["c"], val=np.array([[1.]], dtype=np.float64)) + assert generic.read().val.dtype == np.float32 + assert generic.val.dtype == np.float64 + snps = SnpData(iid=[["f", "0"]], sid=["s"], val=[[1.]]) + assert snps.val.dtype == np.float32 + assert SnpData(iid=[], sid=[], val=None).val.dtype == np.float32 + assert KernelData(iid=[], val=None).val.dtype == np.float32 + + +def test_default_and_invalid_configuration(monkeypatch): + monkeypatch.delenv("ARRAY_DTYPE", raising=False) + assert array_dtype() == np.float64 + assert array_dtype("float32") == np.float32 + monkeypatch.setenv("ARRAY_DTYPE", "float16") + with pytest.raises(ValueError, match="ARRAY_DTYPE"): + array_dtype() + assert array_dtype("float64") == np.float64 + + +def test_pheno_metadata_does_not_allocate_gpu_float64(monkeypatch): + cupy = pytest.importorskip("cupy") + monkeypatch.setenv("ARRAY_MODULE", "cupy") + monkeypatch.setenv("ARRAY_DTYPE", "float32") + with pytest.MonkeyPatch.context() as patch: + def unexpected(*args, **kwargs): + raise AssertionError("metadata inspection must not allocate GPU values") + patch.setattr(bed_reader._gpu, "empty_gpu", unexpected) + pheno = Pheno({"iid": np.array([["f", "0"]]), "header": ["y"], "vals": np.array([[1e-50]])}) + assert len(pheno.iid) == 1 + assert isinstance(pheno._data.val, np.ndarray) + assert pheno._data.val[0, 0] == 1e-50 + result = pheno.read(xp=cupy) + assert result.val.dtype == np.float32 + + +@pytest.mark.parametrize("format_name", ["Dense", "Dat", "Ped"]) +def test_text_parsing_keeps_raw_values_on_cpu(tmp_path, monkeypatch, format_name): + import warnings + from pysnptools import snpreader + + cupy = pytest.importorskip("cupy") + reader_type = getattr(snpreader, format_name) + snps = source(np) + snps._col_property = np.array([[1, 0, 1], [1, 0, 2]], dtype=np.float64) + path = str(tmp_path / ("source." + format_name.lower())) + reader_type.write(path, snps) + expected = reader_type(path).read(dtype=np.float32, xp=np).val + monkeypatch.setenv("ARRAY_MODULE", "cupy") + monkeypatch.setenv("ARRAY_DTYPE", "float32") + reader = reader_type(path) + with warnings.catch_warnings(): + warnings.simplefilter("error", bed_reader.GpuFloat64Warning) + assert reader.iid_count == snps.iid_count + assert isinstance(reader._data.val, np.ndarray) + actual = reader.read(xp=cupy) + assert actual.val.dtype == np.float32 + np.testing.assert_array_equal(cupy.asnumpy(actual.val), expected) + + +@pytest.mark.parametrize("configured", ["float32", "float64"]) +def test_distribution_reader_precision(monkeypatch, configured): + from pysnptools.distreader import DistData + + monkeypatch.setenv("ARRAY_MODULE", "numpy") + monkeypatch.setenv("ARRAY_DTYPE", configured) + values = np.array([[[.5, .5, 0]], [[0, 0, 1]]], dtype=np.float64) + distributions = DistData(iid=[["f", "0"], ["f", "1"]], sid=["s"], val=values) + assert distributions.val.dtype == np.float64 + actual = distributions.read() + assert actual.val.dtype == np.dtype(configured) + np.testing.assert_array_equal(actual.val, values) + assert distributions.read(dtype="float64").val.dtype == np.float64 + assert distributions.as_snp().read().val.dtype == np.dtype(configured) diff --git a/pysnptools/test_gpu_allocator.py b/pysnptools/test_gpu_allocator.py new file mode 100644 index 0000000..2f04417 --- /dev/null +++ b/pysnptools/test_gpu_allocator.py @@ -0,0 +1,265 @@ +"""Prefer native allocations without taking over caller-provided CuPy memory.""" + +from unittest.mock import patch + +import numpy as np +import pytest + +from bed_reader import bed_reader as native +from pysnptools.kernelreader import KernelData +from pysnptools.snpreader import SnpData +from pysnptools.standardizer import Beta, Identity, Unit + + +@pytest.fixture +def cupy(): + if not hasattr(native, "allocate_gpu"): + pytest.skip("requires the bed-reader CubeCL allocator") + return pytest.importorskip("cupy") + + +def data(values, xp): + return SnpData(iid=[["f", str(sample)] for sample in range(len(values))], + sid=[str(marker) for marker in range(values.shape[1])], val=values, xp=xp) + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +@pytest.mark.parametrize("order", ["C", "F"]) +@pytest.mark.parametrize("standardizer", [Unit(), Beta(2, 3), Beta(1, 25), Beta(0.5, 0.5)]) +def test_host_constructor_native_standardization(cupy, dtype, order, standardizer): + from bed_reader._gpu import _native_owner + + values = np.array([[.25, 1, .5, 0, 2], [.75, 1, np.nan, 0, 2], + [1.75, 1, 1.5, 0, 2], [1.25, 1, .75, 0, 2]], dtype=dtype, order=order) + if isinstance(standardizer, Unit): + values[:, 0] -= 4 + original = values.copy() + target = data(values, cupy) + assert _native_owner(target.val) is not None + pointer = target.val.data.ptr + observed_mean = np.nanmean(values.astype(np.float64), axis=0) + if isinstance(standardizer, Unit): + deviations = np.nanstd(values.astype(np.float64), axis=0) + deviations[deviations == 0] = np.inf + factors = 1 / deviations + else: + frequency = np.minimum(observed_mean / 2, 1 - observed_mean / 2) + variable = np.nanstd(values.astype(np.float64), axis=0) > 0 + factors = np.zeros(len(observed_mean)) + frequency = frequency[variable] + # Independent closed-form densities, evaluated only for variable SNPs. + if (standardizer.a, standardizer.b) == (2, 3): + factors[variable] = 12 * frequency * (1 - frequency) ** 2 + elif (standardizer.a, standardizer.b) == (1, 25): + factors[variable] = 25 * (1 - frequency) ** 24 + else: + factors[variable] = 1 / (np.pi * np.sqrt(frequency * (1 - frequency))) + expected = (values - observed_mean) * factors + expected[np.isnan(values)] = 0 + with patch.object(native, "standardize_gpu", wraps=native.standardize_gpu) as called: + target.standardize(standardizer) + assert called.call_count == 1 + assert target.val.data.ptr == pointer and target.val.dtype == dtype + assert target.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"] + tolerance = 32 * np.finfo(dtype).eps # bounded inputs and centered reductions + if isinstance(standardizer, Beta) and standardizer.a == 1: + # Native statrs Beta(1,25) differs from the closed form by ~1.5e-13. + tolerance = max(tolerance, 1e-12) + np.testing.assert_allclose(cupy.asnumpy(target.val), expected, rtol=tolerance, atol=tolerance) + np.testing.assert_array_equal(values, original) + + +def test_caller_arrays_and_native_views_remain_cupy(cupy): + from bed_reader._gpu import empty_gpu + + for source in (cupy.array([[0., 1.], [1., 1.], [2., 1.]]), + empty_gpu((3, 4))[:, :2], empty_gpu((3, 2)).T): + source[...] = cupy.arange(source.size).reshape(source.shape) + target = data(source, cupy) + assert target.val is source + with patch.object(native, "standardize_gpu", wraps=native.standardize_gpu) as called: + target.standardize() + assert called.call_count == 0 + + +def test_slice_standardizes_only_selected_columns(cupy): + from bed_reader._gpu import empty_gpu + + values = empty_gpu((3, 4)) + values[...] = cupy.array([[0, 1, 7, 8], [1, 1, 7, 8], [2, 1, 7, 8]]) + data(values[:, :2], cupy).standardize() + np.testing.assert_array_equal(cupy.asnumpy(values[:, 2:]), [[7, 8]] * 3) + + +@pytest.mark.parametrize("order", ["C", "F"]) +def test_snp_reads_are_native_and_kernels_use_cupy(cupy, order): + # Only SNP data can use bed-reader's native standardizer. Kernels come from + # CuPy's pool, which reuses memory across blocks instead of reallocating. + from bed_reader._gpu import _native_owner, is_cubecl_backed + + source = data(cupy.array([[0., 1.], [1., 1.], [2., 1.]]), cupy) + copied = source.read(dtype="float64", order=order, xp=cupy) + assert copied.val.data.ptr != source.val.data.ptr + assert _native_owner(copied.val) is not None + for block_size in (None, 1): + kernel = source.read_kernel(Identity(), block_size=block_size, dtype="float64", order=order, xp=cupy) + assert isinstance(kernel.val, cupy.ndarray) and not is_cubecl_backed(kernel.val) + np.testing.assert_array_equal(cupy.asnumpy(kernel.val), [[1, 1, 1], [1, 2, 3], [1, 3, 5]]) + assert kernel.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"] + host = KernelData(iid=source.iid, val=np.eye(3), xp=np) + on_gpu = host.read(xp=cupy).val + assert isinstance(on_gpu, cupy.ndarray) and not is_cubecl_backed(on_gpu) + + +def test_cupy_allocation_without_native_feature(cupy, monkeypatch): + from bed_reader._gpu import _native_owner + + monkeypatch.delattr(native, "allocate_gpu") + target = data(np.array([[0., 1.], [1., 1.], [2., 1.]]), cupy) + assert isinstance(target.val, cupy.ndarray) and _native_owner(target.val) is None + target.standardize() + assert isinstance(target.val, cupy.ndarray) + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +@pytest.mark.parametrize("order", ["C", "F"]) +@pytest.mark.parametrize("native_source", [False, True]) +def test_subset_reads_use_native_standardization(cupy, dtype, order, native_source): + from bed_reader._gpu import _native_owner + + values = np.array([[.25, 1, 5, np.nan], [.75, 1, 6, .5], + [np.nan, 1, 7, 1.5], [1.75, 1, 8, .75], + [1.25, 1, 9, 1.25]], dtype=dtype, order=order) + source = data(values if native_source else cupy.array(values, order=order), cupy) + rows, columns = [4, 1, 4, 0], [3, 0, 1] + selected = source[rows, columns].read(dtype=dtype, order=order, xp=cupy) + expected = values[np.ix_(rows, columns)] + np.testing.assert_array_equal(cupy.asnumpy(selected.val), expected) + np.testing.assert_array_equal(selected.iid, source.iid[rows]) + np.testing.assert_array_equal(selected.sid, source.sid[columns]) + assert _native_owner(selected.val) is not None + assert selected.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"] + + # Independent centered float64 reference, including a missing value and + # constant column. Allow 32 eps for the bounded fractional input reductions. + centered = expected.astype(np.float64) - np.nanmean(expected.astype(np.float64), axis=0) + deviation = np.sqrt(np.nanmean(centered ** 2, axis=0)) + deviation[deviation == 0] = np.inf + expected = centered / deviation + expected[np.isnan(expected)] = 0 + with patch.object(native, "standardize_gpu", wraps=native.standardize_gpu) as called: + selected.standardize(Unit()) + assert called.call_count == 1 + tolerance = 32 * np.finfo(dtype).eps + np.testing.assert_allclose(cupy.asnumpy(selected.val), expected, rtol=tolerance, atol=tolerance) + np.testing.assert_array_equal(cupy.asnumpy(source.val), values) + + +def test_subset_native_failure_propagates_and_unavailable_allocator_uses_cupy(cupy, monkeypatch): + import bed_reader + from bed_reader._gpu import _native_owner + + source = data(cupy.arange(12, dtype=cupy.float32).reshape(4, 3), cupy) + + def fail(*args, **kwargs): + raise RuntimeError("subset allocation failed") + + with monkeypatch.context() as context: + context.setattr(bed_reader._gpu, "empty_gpu", fail) + with pytest.raises(RuntimeError, match="subset allocation failed"): + source[[3, 0], [2, 1]].read(dtype="float32", xp=cupy) + monkeypatch.delattr(native, "allocate_gpu") + selected = source[[3, 0], [2, 1]].read(dtype="float32", xp=cupy) + assert isinstance(selected.val, cupy.ndarray) and _native_owner(selected.val) is None + np.testing.assert_array_equal(cupy.asnumpy(selected.val), [[11, 10], [2, 1]]) + + +@pytest.mark.parametrize("rows,columns", [([], [1, 0]), ([1, 0], []), ([], [])]) +def test_empty_subsets_have_native_storage(cupy, rows, columns): + from bed_reader._gpu import _native_owner + + source = data(cupy.arange(6, dtype=cupy.float32).reshape(3, 2), cupy) + selected = source[rows, columns].read(dtype="float32", xp=cupy) + assert selected.val.shape == (len(rows), len(columns)) + assert _native_owner(selected.val) is not None + + +def test_three_dimensional_subset_remains_cupy(cupy): + from bed_reader._gpu import _native_owner + from pysnptools.util import sub_matrix + + values = np.arange(24, dtype=np.float32).reshape(4, 3, 2) + result = sub_matrix(cupy.array(values), [3, 0], [2, 1], dtype="float32") + assert isinstance(result, cupy.ndarray) and _native_owner(result) is None + np.testing.assert_array_equal(cupy.asnumpy(result), values[np.ix_([3, 0], [2, 1])]) + + +def test_subset_narrowing_warns_and_preserves_values(cupy): + from bed_reader._gpu import _native_owner + + values = np.array([[.25, np.nan], [1.25, 1], [1.75, 2]], dtype=np.float64) + source = data(cupy.array(values), cupy) + with pytest.warns(UserWarning, match="loss of information"): + result = source[[2, 0], [1, 0]].read(dtype="float32", xp=cupy) + assert _native_owner(result.val) is not None and result.val.dtype == np.float32 + np.testing.assert_array_equal(cupy.asnumpy(result.val), values[np.ix_([2, 0], [1, 0])].astype(np.float32)) + + +def test_trained_native_data_uses_cupy_application(cupy): + source = data(np.array([[0., 1.], [1., 1.], [2., 1.]]), cupy) + _, trained = source.standardize(return_trained=True) + target = data(np.array([[0., 1.], [1., 1.], [2., 1.]]), cupy) + with patch.object(native, "standardize_gpu", wraps=native.standardize_gpu) as called: + target.standardize(trained) + assert called.call_count == 0 # applying moments must not refit them + np.testing.assert_array_equal(cupy.asnumpy(target.val), cupy.asnumpy(source.val)) + + +def test_read_narrowing_warns_and_view_permissions_are_preserved(cupy): + from bed_reader._gpu import _native_owner + + source = data(cupy.array([[0.25, 1.], [1.25, 1.], [1.75, 1.]]), cupy) + shared = source.read(dtype="float64", order="A", view_ok=True, xp=cupy) + assert shared.val.data.ptr == source.val.data.ptr + with pytest.warns(UserWarning, match="loss of information"): + narrowed = source.read(dtype="float32", xp=cupy) + assert narrowed.val.dtype == np.float32 and _native_owner(narrowed.val) is not None + np.testing.assert_array_equal(cupy.asnumpy(narrowed.val), cupy.asnumpy(source.val).astype(np.float32)) + + +def test_native_allocation_failure_propagates(cupy, monkeypatch): + import bed_reader + + def fail(*args, **kwargs): + raise RuntimeError("native allocation failed") + + monkeypatch.setattr(bed_reader._gpu, "empty_gpu", fail) + with pytest.raises(RuntimeError, match="native allocation failed"): + data(np.zeros((3, 2)), cupy) + caller_values = cupy.zeros((3, 2)) + target = data(caller_values, cupy) + assert target.val is caller_values + target.standardize() # caller-owned memory does not depend on the native allocator + + +def test_other_ranks_and_int8_remain_supported_storage(cupy): + from bed_reader._gpu import _native_owner + from pysnptools.pstreader import PstData + + values = np.arange(12, dtype=np.float32).reshape(2, 3, 2) + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + target = PstData(row=["0", "1"], col=["s0", "s1", "s2"], val=values) + assert target.val.shape == values.shape and _native_owner(target.val) is None + np.testing.assert_array_equal(cupy.asnumpy(target.val), values) + integer = SnpData(iid=[["f", "0"], ["f", "1"]], sid=["s"], + val=cupy.ones((2, 1), dtype=cupy.int8), xp=cupy, _require_float32_64=False) + with pytest.raises(ValueError, match="float32 or float64"): + integer.standardize() + + +def test_empty_containers_use_floating_native_storage(cupy): + source = SnpData(iid=[], sid=["s0", "s1"], val=None, xp=cupy) + kernel = KernelData(iid=[], val=None, xp=cupy) + for target, shape in ((source, (0, 2)), (kernel, (0, 0))): + assert isinstance(target.val, cupy.ndarray) and target.val.dtype == np.float64 + assert target.val.shape == shape and target.val.data.ptr != 0 diff --git a/pysnptools/test_gpu_api.py b/pysnptools/test_gpu_api.py new file mode 100644 index 0000000..3a84971 --- /dev/null +++ b/pysnptools/test_gpu_api.py @@ -0,0 +1,149 @@ +"""GPU API regressions. Requires the CUDA bed-reader build and a working CuPy GPU.""" +import numpy as np +import pytest +from unittest.mock import patch + +from bed_reader import sample_file +from pysnptools.snpreader import Bed, SnpData +from pysnptools.kernelreader import SnpKernel +from pysnptools.standardizer import Unit, Beta + + +@pytest.fixture +def cupy(): + # Optional GPU qualification is explicitly reported on CPU-only installations. + from bed_reader import has_gpu_support + if not has_gpu_support(): + pytest.skip("requires bed-reader built with the cubecl-cuda Cargo feature") + return pytest.importorskip("cupy") + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +@pytest.mark.parametrize("standardizer", [Unit(), Beta(1, 25)]) +def test_subset_fused_and_blocked(cupy, dtype, standardizer): + reader = Bed(sample_file("toydata.5chrom.bed"), count_A1=True)[::-3, ::97][::-1, ::-1] + expected, trained = reader._read_with_standardizing( + standardizer, dtype=dtype, xp=np, return_trained=True) + with patch("bed_reader.bed_reader.standardize_gpu", wraps=__import__( + "bed_reader.bed_reader", fromlist=["standardize_gpu"]).standardize_gpu) as native: + actual, gpu_trained = reader._read_with_standardizing( + standardizer, dtype=dtype, xp=cupy, return_trained=True) + assert native.call_count == 1 + np.testing.assert_array_equal(cupy.asnumpy(actual.val), expected.val) + np.testing.assert_array_equal(gpu_trained.stats, trained.stats) + kernel = reader.read_kernel(standardizer, block_size=7, dtype=dtype, xp=cupy) + assert native.call_count > 2 # the requested blocks were actually used + # BLAS accumulation order differs between blocked GPU and whole CPU products. + tolerance = 32 * np.finfo(dtype).eps + np.testing.assert_allclose(cupy.asnumpy(kernel.val), expected.val @ expected.val.T, + atol=tolerance * reader.sid_count, rtol=tolerance) + for to_kerneldata in [False, True]: + result = SnpKernel(reader, standardizer, block_size=7)._read_with_standardizing( + to_kerneldata, dtype=dtype, xp=cupy) + val = result.val if to_kerneldata else result.snpreader.val + assert val.dtype == dtype and isinstance(val, cupy.ndarray) + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +@pytest.mark.parametrize("order", ["C", "F"]) +@pytest.mark.parametrize("standardizer", [Beta(1, 25), Beta(0.5, 0.5)]) +def test_blocked_beta_trained_bed(cupy, tmp_path, dtype, order, standardizer): + from bed_reader import to_bed + + rng = np.random.default_rng(37) + values = rng.integers(0, 3, size=(13, 9)).astype(dtype) + values[:8, :2] = [0, 2] # training constants can vary in the test cohort + values[8:, 4] = np.nan # applying moments must not refit an empty test SNP + path = tmp_path / "trained.bed" + to_bed(path, values, count_A1=True) + reader = Bed(path, count_A1=True) + _, trained = reader[:8, :].read(dtype=dtype, xp=np).standardize(standardizer, return_trained=True) + test_reader = reader[8:, :][::-1, :] + standardized = test_reader.read(dtype=dtype, xp=np).standardize(trained).val + expected = standardized @ standardized.T + # Nine well-scaled SNP contributions and three block additions round in dtype. + tolerance = 64 * np.finfo(dtype).eps + for xp in (np, cupy): + kernel = test_reader.read_kernel(trained, block_size=4, dtype=dtype, order=order, xp=xp) + assert isinstance(kernel.val, xp.ndarray) and kernel.val.dtype == dtype + assert kernel.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"] + actual = kernel.val if xp is np else cupy.asnumpy(kernel.val) + np.testing.assert_allclose(actual, expected, rtol=tolerance, atol=tolerance * reader.sid_count) + + +def test_explicit_module_and_existing_array(cupy): + reader = Bed(sample_file("small.bed"), count_A1=True) + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + assert isinstance(reader.read(xp=np).val, np.ndarray) + assert isinstance(reader.read().val, cupy.ndarray) + data = reader.read(xp=np) + data.standardize() + assert isinstance(data.val, np.ndarray) + assert isinstance(reader.read_kernel(Unit(), xp=np).val, np.ndarray) + with patch.dict("os.environ", {"ARRAY_MODULE": "numpy"}): + data = reader.read(xp=cupy) + data.standardize() + assert isinstance(data.val, cupy.ndarray) + assert isinstance(data[::2, :].read(xp=cupy).val, cupy.ndarray) + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +@pytest.mark.parametrize("order", ["F", "C"]) +def test_foreign_dosages_and_trained(cupy, dtype, order): + rng = np.random.default_rng(1) + val = rng.uniform(0.0, 2.0, (41, 6)).astype(dtype) + val[::5, 0] = np.nan + val[:, 1] = 1.0 + iid = np.array([[str(index), str(index)] for index in range(len(val))]) + sid = np.array([str(index) for index in range(val.shape[1])]) + for standardizer in [Unit(), Beta(1, 25)]: + # Beta is only defined for allele frequencies in [0, 1]. + source = val if isinstance(standardizer, Unit) else val[:, :2] + data_np = SnpData(iid=iid, sid=sid[:source.shape[1]], val=np.array(source, order=order), xp=np) + data_cp = SnpData(iid=iid, sid=data_np.sid, val=cupy.array(source, order=order), xp=cupy) + expected, trained_np = data_np.standardize(standardizer, return_trained=True) + actual, trained_cp = data_cp.standardize(standardizer, return_trained=True) + tolerance = 64 * np.finfo(dtype).eps + np.testing.assert_allclose(cupy.asnumpy(actual.val), expected.val, rtol=tolerance, atol=tolerance) + fresh_np = SnpData(iid=iid, sid=data_np.sid, val=np.array(source, order=order), xp=np).standardize(trained_np) + fresh_cp = SnpData(iid=iid, sid=data_np.sid, val=cupy.array(source, order=order), xp=cupy).standardize(trained_cp) + np.testing.assert_allclose(cupy.asnumpy(fresh_cp.val), fresh_np.val, rtol=tolerance, atol=tolerance) + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +def test_large_offset_against_centered_reference(cupy, dtype): + # The legacy Rust CPU standardizer uses E[x*x]-E[x]**2 and loses + # precision here, so use an independent centered float64 reference. + rng = np.random.default_rng(12) + values = (1e4 + rng.random((100, 4))).astype(dtype) + mean = values.astype(np.float64).mean(axis=0).astype(dtype) + deviation = values.astype(np.float64).std(axis=0).astype(dtype) + expected = (values - mean) * (1 / deviation) + data = SnpData(iid=[[str(index), str(index)] for index in range(100)], + sid=["a", "b", "c", "d"], val=cupy.array(values, order="F"), xp=cupy) + actual = data.standardize(Unit()).val + # Parallel reductions can round the large mean by a few ulps. Subtracting + # it and dividing by a small deviation amplifies that error by this ratio. + absolute_tolerance = 8 * np.finfo(dtype).eps * np.max(np.abs(values)) / np.min(deviation) + np.testing.assert_allclose(cupy.asnumpy(actual), expected, + rtol=8 * np.finfo(dtype).eps, atol=absolute_tolerance) + + +@pytest.mark.parametrize("order", ["C", "F"]) +def test_standardize_workspace_is_not_matrix_sized(cupy, order): + rng = np.random.default_rng(8) + values = rng.integers(0, 3, size=(1000, 5000), dtype=np.int8) + pool = cupy.cuda.MemoryPool() + with cupy.cuda.using_allocator(pool.malloc): + data = SnpData( + iid=[[str(index), str(index)] for index in range(values.shape[0])], + sid=[str(index) for index in range(values.shape[1])], + val=cupy.array(values, dtype=np.float32, order=order), xp=cupy) + cupy.cuda.get_current_stream().synchronize() + baseline = pool.total_bytes() + data.standardize(Unit()) + cupy.cuda.get_current_stream().synchronize() + # The 19 MiB matrix must not need a matrix-sized mask/temporary. + # Four MiB allows reduction scratch space and several per-SNP vectors. + assert pool.total_bytes() - baseline < 4 * 2**20 + assert bool(cupy.isfinite(data.val).all()) diff --git a/pysnptools/test_gpu_precision_warning.py b/pysnptools/test_gpu_precision_warning.py new file mode 100644 index 0000000..97b6c09 --- /dev/null +++ b/pysnptools/test_gpu_precision_warning.py @@ -0,0 +1,63 @@ +"""Propagate precision warnings for native and ordinary CuPy allocations/math.""" + +import warnings + +import bed_reader +import numpy as np +import pytest + +from pysnptools.snpreader import SnpData +from pysnptools.standardizer import Identity + +WarningType = bed_reader.GpuFloat64Warning + + +def data(values, xp): + return SnpData(iid=[["f", str(sample)] for sample in range(len(values))], + sid=[str(marker) for marker in range(values.shape[1])], val=values, xp=xp) + + +@pytest.fixture +def cupy(): + return pytest.importorskip("cupy") + + +def test_allocations_warn_for_both_native_and_cupy(cupy, monkeypatch): + from bed_reader import bed_reader as native + + for native_enabled in (True, False): + with monkeypatch.context() as patch: + if not native_enabled: + patch.delattr(native, "allocate_gpu", raising=False) + with pytest.warns(WarningType, match="consumer GPUs") as caught: + result = data(np.ones((3, 2)), cupy) + assert len(caught) == 1 and result.val.dtype == np.float64 + + +def test_existing_arrays_warn_on_math_and_float32_reductions_do_not(cupy): + values = cupy.array([[0., 1.], [1., 1.], [2., 1.]]) + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + result = data(values, cupy) + assert result.val is values and not caught # no allocation or conversion + with pytest.warns(WarningType, match="consumer GPUs"): + result.standardize() + assert result.val.dtype == np.float64 + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + data(np.ones((3, 2), dtype=np.float32), cupy).standardize() + data(np.ones((3, 2)), np).standardize() + assert not any(issubclass(item.category, WarningType) for item in caught) + + +def test_read_kernel_and_default_filter(cupy): + source = data(np.array([[0., 1.], [1., 1.], [2., 1.]]), np) + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("default", WarningType) + result = source.read(dtype="float64", xp=cupy).standardize() + notices = [item for item in caught if issubclass(item.category, WarningType)] + assert len(notices) == 1 + assert result.val.dtype == np.float64 + with pytest.warns(WarningType): + kernel = source.read_kernel(Identity(), dtype="float64", xp=cupy) + assert kernel.val.dtype == np.float64 diff --git a/pysnptools/test_gpu_standardize_general.py b/pysnptools/test_gpu_standardize_general.py new file mode 100644 index 0000000..885d00d --- /dev/null +++ b/pysnptools/test_gpu_standardize_general.py @@ -0,0 +1,120 @@ +"""Independent expectations for fractional Unit/Beta arrays and trained statistics.""" +import numpy as np +import pytest +from scipy.stats import beta as beta_distribution + +from pysnptools.snpreader import SnpData +from pysnptools.standardizer import Unit, Beta + + +def reference(values, standardizer): + expected = np.zeros_like(values) + stats = np.empty((values.shape[1], 2), dtype=values.dtype) + for column in range(values.shape[1]): + valid = ~np.isnan(values[:, column]) + observed = values[valid, column].astype(np.longdouble) + mean = observed.mean() + variance = ((observed - mean) ** 2).mean() + stats[column] = [mean, np.sqrt(variance) if variance > 0 else np.inf] + if variance == 0: + continue + mean, deviation = stats[column] + if isinstance(standardizer, Unit): + factor = values.dtype.type(1) / deviation + else: + maf = float(mean) / 2 + factor = values.dtype.type(beta_distribution.pdf(min(maf, 1 - maf), standardizer.a, standardizer.b)) + expected[valid, column] = (values[valid, column] - mean) * factor + return expected, stats + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +@pytest.mark.parametrize("order", ["C", "F"]) +@pytest.mark.parametrize("standardizer", [Unit(), Beta(2, 3), Beta(0.5, 0.5)]) +def test_fractional_standardization_and_training(dtype, order, standardizer): + cp = pytest.importorskip("cupy") + values = np.array([ + [0.25, 0.75, 0, 2, np.nan], + [0.5, 0.75, 0, 2, np.nan], + [np.nan, 0.75, 0, 2, 1.125], + [1.75, 0.75, 0, 2, np.nan], + [1.125, 0.75, 0, 2, np.nan], + [1.5, 0.75, 0, 2, np.nan], + ], dtype=dtype) + if isinstance(standardizer, Unit): + values[:, 0] -= 4 + values[:, 1] += 3 + elif standardizer.a == 2: + values[:, 0] = [-1.25, 0.25, np.nan, 2.5, 1.125, 1.5] + expected, expected_stats = reference(values, standardizer) + iid = [[str(index), str(index)] for index in range(len(values))] + sid = [str(index) for index in range(values.shape[1])] + # Compare the CPU and GPU public API independently to the same reference. + for xp in [np, cp]: + data = SnpData(iid=iid, sid=sid, val=xp.array(values, order=order), xp=xp) + actual, trained = data.standardize(standardizer, return_trained=True) + tolerance = 16 * np.finfo(dtype).eps + actual_values = actual.val if xp is np else cp.asnumpy(actual.val) + np.testing.assert_allclose(actual_values, expected, rtol=tolerance, atol=tolerance) + np.testing.assert_allclose(trained.stats, expected_stats, rtol=tolerance, atol=tolerance) + assert actual.val.dtype == values.dtype + assert actual.val.flags["C_CONTIGUOUS" if order == "C" else "F_CONTIGUOUS"] + fresh_values = values.copy() + fresh_values[:, 1:] = 0.5 # trained constant columns must still become zero + fresh = SnpData(iid=iid, sid=sid, val=xp.array(fresh_values, order=order), xp=xp) + fresh.standardize(trained) + np.testing.assert_allclose(fresh.val if xp is np else cp.asnumpy(fresh.val), + expected, rtol=tolerance, atol=tolerance) + + +def test_beta_errors_match_cpu(): + cp = pytest.importorskip("cupy") + iid = [["a", "a"], ["b", "b"]] + for xp in [np, cp]: + for standardizer, values, message in [ + (Beta(1, 25), [[-2.5], [-1.5]], "Illegal SNP mean"), + (Beta(-1, 25), [[0.25], [1.25]], "Beta"), + (Unit(), [[np.nan], [np.nan]], "No individual observed"), + ]: + data = SnpData(iid=iid, sid=["s"], val=xp.array(values, dtype=np.float64), xp=xp) + with pytest.raises(ValueError, match=message): + data.standardize(standardizer) + + +@pytest.mark.parametrize("dtype", [np.float32, np.float64]) +@pytest.mark.parametrize("order", ["C", "F"]) +@pytest.mark.parametrize("standardizer", [Unit(), Beta(0.5, 0.5)]) +def test_native_statistics_through_bed_helper(tmp_path, dtype, order, standardizer): + from unittest.mock import patch + from bed_reader import has_gpu_support, to_bed + from bed_reader import bed_reader as native + from pysnptools.snpreader import Bed + + if not has_gpu_support(): + pytest.skip("requires bed-reader built with the cubecl-cuda Cargo feature") + cp = pytest.importorskip("cupy") + values = np.array([[0.25, 0], [0.5, 0], [1.75, 0], [np.nan, 0]], dtype=dtype) + if isinstance(standardizer, Unit): + values[:, 0] -= 4 + path = tmp_path / "owned.bed" + to_bed(path, np.zeros(values.shape, dtype=np.int8)) + reader = Bed(path, count_A1=True) + reader._run_once() + owner = reader._open_bed._read_gpu(dtype=dtype, order=order) + cp.asarray(owner)[...] = cp.asarray(values) + # BED files themselves contain only genotypes. Supply an exported, modified + # owner to test that PySnpTools's native handoff adds no input restriction. + with patch.object(reader._open_bed, "_read_gpu", return_value=owner), \ + patch.object(native, "standardize_gpu", wraps=native.standardize_gpu) as standardize: + data, trained = reader._read_with_standardizing( + standardizer, dtype=dtype, order=order, xp=cp, return_trained=True) + assert standardize.call_count == 1 + expected, stats = reference(values, standardizer) + tolerance = 16 * np.finfo(dtype).eps + np.testing.assert_allclose(cp.asnumpy(data.val), expected, rtol=tolerance, atol=tolerance) + np.testing.assert_allclose(trained.stats, stats, rtol=tolerance, atol=tolerance) + fresh_values = values.copy() + fresh_values[:, 1] = 0.5 + fresh = SnpData(iid=data.iid, sid=data.sid, val=cp.array(fresh_values, order=order), xp=cp) + fresh.standardize(trained) + np.testing.assert_allclose(cp.asnumpy(fresh.val), expected, rtol=tolerance, atol=tolerance) diff --git a/pysnptools/util/__init__.py b/pysnptools/util/__init__.py index b1ba892..5de5891 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -1,8 +1,10 @@ import os import logging import numpy as np +from pysnptools.util._precision import array_dtype import sys from contextlib import contextmanager +from operator import index as integer_index import time import datetime from types import ModuleType @@ -275,7 +277,7 @@ def intersect_ids(idslist): def sub_matrix( - val, row_index_list, col_index_list, order="A", dtype=np.float64, num_threads=None + val, row_index_list, col_index_list, order="A", dtype=None, num_threads=None ): """ Efficiently creates a sub-matrix from a 2-D or 3-D ndarray. @@ -287,13 +289,13 @@ def sub_matrix( :param col_index_list: Tells which columns (and in which order) to copy into the sub-matrix :type col_index_list: list of integers :param order: {'A' (default), 'C', 'F'}, optional -- Specify the order of the sub-matrix to create. - If order is 'C', then the returned sub-matrix will be in C-contiguous order (first index varies the fastest). - If order is 'F', then the array will be in F-contiguous order (second index varies the fastest). + If order is 'C', then the returned sub-matrix will be in C-contiguous order (last index varies the fastest). + If order is 'F', then the array will be in F-contiguous order (first index varies the fastest). If order is 'A', then sub-matrix may be in any order F or C. - :type order: string or None + :type order: str :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for sub-matrix created. :type dtype: data-type - :param num_threads: optional -- The number of threads with which to work. Defaults to all available + :param num_threads: optional -- The CPU thread count, ignored for CuPy. Defaults to all available processors. Can also be set with these environment variables (listed in priority order): 'PST_NUM_THREADS', 'NUM_THREADS', 'MKL_NUM_THREADS'. :type num_threads: None or int @@ -302,15 +304,29 @@ def sub_matrix( >>> import numpy as np >>> import pysnptools.util as pstutil - >>> np.random.seed(0) # set seed so that results are deterministic - >>> matrix = np.random.rand(12,7) # create a 12 x 7 ndarray + >>> rng = np.random.default_rng(0) # deterministic local generator + >>> matrix = rng.random((12, 7)) # create a 12 x 7 ndarray >>> submatrix = pstutil.sub_matrix(matrix,[0,2,11],[6,5,4,3,2,1,0]) >>> print(int(submatrix.shape[0]),int(submatrix.shape[1])) 3 7 >>> print(matrix[2,0] == submatrix[1,6]) #The row # 2 is now #1, the column #0 is now #6. True - Note: Behind the scenes, for performance, this function calls a Rust helper function. + Invalid indices are rejected before integer conversion: + + >>> pstutil.sub_matrix(matrix, [0.9], [0]) + Traceback (most recent call last): + ... + IndexError: row indices must be a one-dimensional sequence of integers, excluding Booleans + + NumPy inputs use a Rust helper; CuPy inputs use CuPy indexing and stay on + the GPU. Row/column indices must be one-dimensional integer sequences, + nonnegative and in range. Invalid indices raise IndexError on both devices; + floating-point values (even 1.0) and Boolean masks are not accepted here. + Use reader slicing for Boolean masks. Both paths + require contiguous float32/float64 inputs, preserve duplicate indices, and + warn when converting float64 to float32. Pass ``dtype=val.dtype`` to preserve + float32; omitted dtype uses ARRAY_DTYPE, then float64. See :doc:`/gpu` for GPU examples. """ if order == "A": @@ -320,7 +336,15 @@ def sub_matrix( effective_order = "C" else: effective_order = order - dtype = np.dtype(dtype) + dtype = array_dtype(dtype) + + # A cupy ndarray can exist only if cupy was already imported, so this check never + # imports cupy and leaves every non-cupy input on the numpy path below. + cp = sys.modules.get("cupy") + if cp is not None and isinstance(val, cp.ndarray): + return _sub_matrix_cupy( + cp, val, row_index_list, col_index_list, effective_order, dtype + ) original_dimensions = len(val.shape) if original_dimensions == 2: @@ -342,8 +366,8 @@ def create_sub_val(dtype): logging.debug("About to call Rust matrixSubset") num_threads = get_num_threads(num_threads) if val.flags["F_CONTIGUOUS"] or val.flags["C_CONTIGUOUS"]: - row_index_list = np.asarray(row_index_list, dtype=np.uintp) - col_index_list = np.asarray(col_index_list, dtype=np.uintp) + row_index_list = _checked_index(row_index_list, iid_count, "row") + col_index_list = _checked_index(col_index_list, sid_count, "column") if val.dtype == np.float64: sub_val = create_sub_val(np.float64) subset_f64_f64( @@ -395,6 +419,79 @@ def create_sub_val(dtype): return sub_val +def _sub_matrix_cupy(cp, val, row_index_list, col_index_list, effective_order, dtype): + # The Rust helper reads host memory, so a cupy (GPU) ndarray, which SnpData holds + # when ARRAY_MODULE is 'cupy', is subset with cupy's own indexing instead. + # The caller passes the already-imported cupy module as cp. + # Validation mirrors the numpy path so both array modules fail the same way. + + if len(val.shape) not in {2, 3}: + raise ValueError("Expect val dimensions of 2 or 3") + if val.dtype not in (np.float64, np.float32): + raise Exception( + "input dtype '{0}' not known, only float64 and float32".format(val.dtype) + ) + if dtype not in (np.float64, np.float32): + raise Exception("dtype '{0}' not known, only float64 and float32".format(dtype)) + if not (val.flags["F_CONTIGUOUS"] or val.flags["C_CONTIGUOUS"]): + raise Exception("input order must be 'F' or 'C'") + if val.dtype == np.float64 and dtype == np.float32: + warnings.warn("Converting float64 to float32 can cause loss of information") + + row_index = _checked_index(row_index_list, val.shape[0], "row") + col_index = _checked_index(col_index_list, val.shape[1], "column") + from pysnptools.util._array import _allocator + + shape = (len(row_index), len(col_index), *val.shape[2:]) + allocator = _allocator(shape, dtype, cp) + if allocator is not None: + # A subset is a new matrix, unlike a caller-supplied array or shared + # view. Put its final dtype/layout in native storage so subsequent + # Unit/Beta fitting can use CubeCL. CuPy's gather is an intermediate; + # copy directly into the final allocation rather than first casting it. + result = allocator(shape, dtype=dtype, order=effective_order) + selected = val[cp.ix_(cp.asarray(row_index), cp.asarray(col_index))] + cp.copyto(result, selected, casting="unsafe") + return result + from pysnptools.util._gpu_warnings import warn_gpu_float64 + warn_gpu_float64(dtype, cp) + sub_val = val[cp.ix_(cp.asarray(row_index), cp.asarray(col_index))] + # Indexing already returns a new array, so copy again only to change dtype or layout. + return sub_val.astype(dtype, order=effective_order, copy=False) + + +def _checked_index(index_list, count, name): + # Preserve sequence elements until validated: NumPy promotion can hide a Boolean + # mixed with integers, or turn mixed signed/unsigned integers into floats. + index = np.asarray(index_list, dtype=None if isinstance(index_list, np.ndarray) else object) + message = f"{name} indices must be a one-dimensional sequence of integers, excluding Booleans" + if index.ndim != 1: + raise IndexError(message) + if index.dtype.kind == "O": + indices = [] + for value in index: + if isinstance(value, (bool, np.bool_)): + raise IndexError(message) + try: + indices.append(integer_index(value)) + except TypeError as error: + raise IndexError(message) from error + index = np.asarray(indices) + elif index.size and index.dtype.kind not in "iu": + raise IndexError(message) + + # Check the original integer range before converting to the Rust helper's uintp. + # This also prevents CuPy's wrapping semantics from selecting the wrong element. + bad = (index < 0) | (index >= count) + if bad.any(): + raise IndexError( + "{0} index {1} is out of range for {2} {0}s".format( + name, index[bad][0], count + ) + ) + return index.astype(np.uintp, copy=False) + + def create_directory_if_necessary(name, isfile=True, robust=False): """ Create a directory for a file if the directory doesn't already exist. @@ -653,7 +750,9 @@ def _datestamp(appendrandom=False): def array_module(xp=None): """ - Find the array module to use, for example **numpy** or **cupy**. + Resolve an explicit module/name, then ARRAY_MODULE, then NumPy. + Missing CuPy raises ImportError; unsupported names raise ValueError. + See :doc:`/gpu` for explicit overrides and actual-device checks. :param xp: The array module to use, for example, 'numpy' (normal CPU-based module) or 'cupy' (GPU-based module). @@ -661,8 +760,7 @@ def array_module(xp=None): from the ARRAY_MODULE environment variable. If not given and ARRAY_MODULE is not set, will use numpy. If 'cupy' is requested, will - try to 'import cupy'. If that import fails, will - revert to numpy. + import cupy. A missing CuPy installation raises ImportError. :type xp: optional, string or Python module :rtype: Python module @@ -670,11 +768,11 @@ def array_module(xp=None): >>> xp = array_module() # will look at environment variable >>> print(xp.zeros((3))) [0. 0. 0.] - >>> xp = array_module('cupy') # will try to import 'cupy' + >>> xp = array_module('numpy') # an explicit module overrides the environment >>> print(xp.zeros((3))) [0. 0. 0.] """ - xp = xp or os.environ.get("ARRAY_MODULE", "numpy") + xp = os.environ.get("ARRAY_MODULE", "numpy") if xp is None else xp if isinstance(xp, ModuleType): return xp @@ -683,16 +781,9 @@ def array_module(xp=None): return np if xp == "cupy": - try: - import cupy as cp # type: ignore + import cupy as cp # type: ignore - return cp - except ModuleNotFoundError as e: - global _warn_array_module_once - if not _warn_array_module_once: - logging.warning(f"Using numpy. ({e})") - _warn_array_module_once = True - return np + return cp raise ValueError(f"Don't know ARRAY_MODULE '{xp}'") @@ -703,8 +794,8 @@ def asnumpy(a): numpy array. (Returns a numpy array unchanged.) >>> from pysnptools.util import asnumpy, array_module - >>> xp = array_module('cupy') - >>> zeros_xp = xp.zeros((3)) # will be cupy if available + >>> xp = array_module('numpy') + >>> zeros_xp = xp.zeros((3)) # explicitly NumPy in this example >>> zeros_np = asnumpy(zeros_xp) # will be numpy >>> zeros_np array([0., 0., 0.]) diff --git a/pysnptools/util/_array.py b/pysnptools/util/_array.py new file mode 100644 index 0000000..f33e083 --- /dev/null +++ b/pysnptools/util/_array.py @@ -0,0 +1,82 @@ +"""Allocate new GPU matrices through bed-reader when its CUDA allocator applies.""" + +import warnings + +import numpy as np +from pysnptools.util._gpu_warnings import warn_gpu_float64 + + +def _allocator(shape, dtype, xp): + if xp is not np: + from bed_reader import bed_reader as native + from bed_reader._gpu import empty_gpu + + # CPU-only bed-reader builds lack the native CubeCL allocator. + if (hasattr(native, "allocate_gpu") + and len(shape) == 2 and max(*shape, shape[0] * shape[1]) <= 2**32 - 1 + and dtype in (np.dtype("int8"), np.dtype("float32"), np.dtype("float64")) + and xp.cuda.Device().id == 0): + return empty_gpu + return None + + +def empty(shape, dtype, order, xp): + dtype = np.dtype(dtype) + allocator = _allocator(shape, dtype, xp) + if allocator is not None: + return allocator(shape, dtype=dtype, order=order) + # CuPy-only builds, other devices, dtypes, and ranks still use GPU memory. + warn_gpu_float64(dtype, xp) + return xp.empty(shape, dtype=dtype, order=order) + + +def asarray(values, dtype, order, xp, copy=False): + dtype = np.dtype(dtype) + if xp is np: + return np.array(values, dtype=dtype, order=order) if copy else np.asarray(values, dtype=dtype, order=order) + if isinstance(values, xp.ndarray): + if values.dtype == np.float64 and dtype == np.float32: + warnings.warn("Converting float64 to float32 can cause loss of information", stacklevel=2) + fits_order = (order in ("A", "K") or + (order == "C" and values.flags.c_contiguous) or + (order == "F" and values.flags.f_contiguous)) + if not copy and values.dtype == dtype and fits_order: + return values + source = values + else: + source = np.asarray(values, dtype=dtype) + if source.ndim != 2: + warn_gpu_float64(dtype, xp) + return xp.array(source, dtype=dtype, order=order) + if order in ("A", "K"): + order = "F" if abs(source.strides[0]) < abs(source.strides[1]) else "C" + if _allocator(source.shape, dtype, xp) is None: + warn_gpu_float64(dtype, xp) + return xp.array(source, dtype=dtype, order=order) + result = empty(source.shape, dtype, order, xp) + if isinstance(source, np.ndarray): + host = np.asarray(source, dtype=dtype, order=order) + result.set(host) + # The temporary host array can die on return; finish the copy first. + xp.cuda.get_current_stream().synchronize() + else: + xp.copyto(result, source, casting="unsafe") + return result + + +def zeros(shape, dtype, order, xp): + if xp is np: + return np.zeros(shape, dtype=dtype, order=order) + result = empty(shape, dtype, order, xp) + result.fill(0) + return result + + +def native_owner(values): + # Ordinary CuPy arrays retain the CuPy path. + # CubeCL's standardizer also indexes four reduction words per dimension. + if max(values.shape) > (2**32 - 1) // 4: + return None + from bed_reader._gpu import _native_owner + + return _native_owner(values) diff --git a/pysnptools/util/_gpu_warnings.py b/pysnptools/util/_gpu_warnings.py new file mode 100644 index 0000000..a254528 --- /dev/null +++ b/pysnptools/util/_gpu_warnings.py @@ -0,0 +1,11 @@ +"""GPU precision notices, delegated to bed-reader.""" + +import numpy as np + + +def warn_gpu_float64(dtype, xp): + if xp is np or np.dtype(dtype) != np.dtype("float64"): + return + from bed_reader._gpu import _warn_gpu_float64 + + _warn_gpu_float64(dtype) diff --git a/pysnptools/util/_precision.py b/pysnptools/util/_precision.py new file mode 100644 index 0000000..5533706 --- /dev/null +++ b/pysnptools/util/_precision.py @@ -0,0 +1,19 @@ +"""Precision defaults shared with bed-reader.""" +from bed_reader._array_module import array_dtype as _array_dtype + + +def array_dtype(dtype=None): + """Resolve an explicit dtype, ARRAY_DTYPE, then float64. + + ARRAY_DTYPE accepts float32 or float64. Explicit values override it; + individual APIs still validate supported types. Existing floating arrays + and standardizers keep their precision. NumPy/CuPy's own defaults are + unaffected. See :doc:`/gpu` for a complete workflow example. + + >>> from unittest.mock import patch + >>> from pysnptools.util import array_dtype + >>> with patch.dict("os.environ", {"ARRAY_DTYPE": "float32"}): + ... print(array_dtype(), array_dtype("float64")) + float32 float64 + """ + return _array_dtype(dtype) diff --git a/pysnptools/util/mapreduce1/runner/_threads.py b/pysnptools/util/mapreduce1/runner/_threads.py new file mode 100644 index 0000000..f0ecb4d --- /dev/null +++ b/pysnptools/util/mapreduce1/runner/_threads.py @@ -0,0 +1,95 @@ +"""Scoped thread limits shared by local multiprocessing runners.""" +from contextlib import contextmanager +from functools import wraps +from inspect import signature +from operator import index +from unittest.mock import patch +import warnings + +from numpy import bool_ +from threadpoolctl import threadpool_limits + + +def environment(num_threads): + """Return startup settings for BLAS, OpenMP, and bed-reader workers.""" + if num_threads is None: + return {} + if isinstance(num_threads, (bool, bool_)): + raise TypeError("num_threads must be a positive integer or None") + num_threads = index(num_threads) + if num_threads <= 0: + raise ValueError("num_threads must be a positive integer or None") + return { + name: str(num_threads) + for name in ( + "MKL_NUM_THREADS", + "OPENBLAS_NUM_THREADS", + "OMP_NUM_THREADS", + "PST_NUM_THREADS", + "BLIS_NUM_THREADS", + ) + } + + +@contextmanager +def limits(num_threads): + """Limit loaded BLAS libraries and restore the caller's settings on exit.""" + if num_threads is None: + yield + return + settings = environment(num_threads) + with patch.dict("os.environ", settings), threadpool_limits( + limits=index(num_threads), user_api="blas" + ): + yield + + +def renamed_num_threads(function): + """Accept the deprecated keyword without changing the canonical signature.""" + parameters = signature(function) + + @wraps(function) + def wrapped(*args, **kwargs): + if "mkl_num_threads" in kwargs: + legacy = kwargs.pop("mkl_num_threads") + # bind_partial also detects an explicitly supplied positional None. + # Checking the value alone cannot distinguish None from omission. + if "num_threads" in parameters.bind_partial(*args, **kwargs).arguments: + raise TypeError("Specify only num_threads; mkl_num_threads is its deprecated alias") + warnings.warn( + "mkl_num_threads is deprecated; use num_threads instead", + DeprecationWarning, + stacklevel=2, + ) + kwargs["num_threads"] = legacy + return function(*args, **kwargs) + + return wrapped + + +def _legacy_get(runner): + warnings.warn("mkl_num_threads is deprecated; use num_threads instead", DeprecationWarning, stacklevel=2) + return runner.num_threads + + +def _legacy_set(runner, num_threads): + warnings.warn("mkl_num_threads is deprecated; use num_threads instead", DeprecationWarning, stacklevel=2) + runner.num_threads = num_threads + + +# Keep the previously writable public attribute synchronized with its new name. +legacy_num_threads = property(_legacy_get, _legacy_set, doc="Deprecated alias of num_threads.") + + + +def _current_threads(runner): + return runner.__dict__["mkl_num_threads"] + + +def _set_current_threads(runner, num_threads): + runner.__dict__["mkl_num_threads"] = num_threads + + +# Keep the historical pickle key while exposing the canonical attribute. +# Default object pickling also preserves slots added by downstream subclasses. +canonical_num_threads = property(_current_threads, _set_current_threads, doc="CPU thread limit, or None.") diff --git a/pysnptools/util/mapreduce1/runner/localinparts.py b/pysnptools/util/mapreduce1/runner/localinparts.py index f7eec4c..072569d 100644 --- a/pysnptools/util/mapreduce1/runner/localinparts.py +++ b/pysnptools/util/mapreduce1/runner/localinparts.py @@ -1,10 +1,10 @@ -from unittest.mock import patch import os import sys import logging from pysnptools.util.mapreduce1.runner import Runner, _JustCheckExists, _run_one_task from pysnptools.util import create_directory_if_necessary import cloudpickle as pickle +from pysnptools.util.mapreduce1.runner import _threads class LocalInParts(Runner): @@ -15,7 +15,8 @@ class LocalInParts(Runner): **Constructor:** :Parameters: * **taskindex** (*number*) -- Which piece of work to run. When 0 to **taskcount**-1, does map work. When **taskcount**, does the reduce work. * **taskcount** (*number*) -- The number of pieces into which to divide the work. - * **mkl_num_threads** (*number*) -- (default None) Limit on the number threads used by the NumPy MKL library. + * **num_threads** (*number*) -- (default None) Maximum threads per process for MKL, OpenBLAS, and PySnpTools CPU operations. None leaves thread settings unchanged. + * **mkl_num_threads** (*number*) -- Deprecated alias for num_threads. Supplying both names, including explicit None, raises TypeError. * **weights** (*array of integers*) -- (default None) If given, tells the relative amount of work assigned to each task. The length of the array must be **taskcount**. If not given, all tasks are assigned the same amount of work. @@ -36,20 +37,21 @@ class LocalInParts(Runner): ... def reducer1(sequence): ... return sum(sequence) ... return map_reduce(range(n),mapper=mapper1,reducer=reducer1,runner=runner) - >>> holder1(100,LocalInParts(0,4)) #Run part 0 of 4 and save partial results to disk as '0.4.p'. - >>> holder1(100,LocalInParts(1,4)) #Run part 1 of 4 and save partial results to disk as '1.4.p'. - >>> holder1(100,LocalInParts(2,4)) #Run part 2 of 4 and save partial results to disk as '2.4.p'. - >>> holder1(100,LocalInParts(3,4)) #Run part 3 of 4 and save partial results to disk as '3.4.p'. - >>> holder1(100,LocalInParts(4,4)) #Read the all partial results and then apply the reduce function and return the result. + >>> holder1(100,LocalInParts(0,4,num_threads=1)) #Run part 0 of 4 and save partial results to disk as '0.4.p'. + >>> holder1(100,LocalInParts(1,4,num_threads=1)) #Run part 1 of 4 and save partial results to disk as '1.4.p'. + >>> holder1(100,LocalInParts(2,4,num_threads=1)) #Run part 2 of 4 and save partial results to disk as '2.4.p'. + >>> holder1(100,LocalInParts(3,4,num_threads=1)) #Run part 3 of 4 and save partial results to disk as '3.4.p'. + >>> holder1(100,LocalInParts(4,4,num_threads=1)) #Read the all partial results and then apply the reduce function and return the result. 328350 """ + @_threads.renamed_num_threads def __init__( self, taskindex, taskcount, - mkl_num_threads=None, + num_threads=None, weights=None, environ=None, result_file=None, @@ -73,7 +75,10 @@ def __init__( self.taskcount = taskcount self.weights = weights self.environ = environ - self.mkl_num_threads = mkl_num_threads + self.num_threads = num_threads + + num_threads = _threads.canonical_num_threads + mkl_num_threads = _threads.legacy_num_threads def run(self, distributable): if self.temp_dir is not None: @@ -82,12 +87,8 @@ def run(self, distributable): tempdir = os.path.join(self.run_dir, distributable.tempdirectory) tempdir = os.path.realpath(tempdir) - with patch.dict( - "os.environ", - {"MKL_NUM_THREADS": str(self.mkl_num_threads)} - if self.mkl_num_threads is not None - else {}, - ) as _: + # Environment variables alone do not reconfigure already loaded BLAS pools. + with _threads.limits(self.num_threads): if self.taskindex != self.taskcount: _JustCheckExists().input(distributable) return _run_one_task( diff --git a/pysnptools/util/mapreduce1/runner/localmultiproc.py b/pysnptools/util/mapreduce1/runner/localmultiproc.py index 19e1c76..3aa4dcf 100644 --- a/pysnptools/util/mapreduce1/runner/localmultiproc.py +++ b/pysnptools/util/mapreduce1/runner/localmultiproc.py @@ -6,6 +6,7 @@ import sys import os.path from pysnptools.util import create_directory_if_necessary, _datestamp +from pysnptools.util.mapreduce1.runner import _threads class LocalMultiProc(Runner): @@ -14,7 +15,8 @@ class LocalMultiProc(Runner): **Constructor:** :Parameters: * **taskcount** (*number*) -- The number of processes to run on. - * **mkl_num_threads** (*number*) -- (default None) Limit on the number threads used by the NumPy MKL library. + * **num_threads** (*number*) -- (default None) Maximum threads per process for MKL, OpenBLAS, and PySnpTools CPU operations. None leaves thread settings unchanged. + * **mkl_num_threads** (*number*) -- Deprecated alias for num_threads. Supplying both names, including explicit None, raises TypeError. * **weights** (*array of integers*) -- (default None) If given, tells the relative amount of work assigned to each task. The length of the array must be **taskcount**. If not given, all tasks are assigned the same amount of work. @@ -35,15 +37,16 @@ class LocalMultiProc(Runner): ... def reducer1(sequence): ... return sum(sequence) ... return map_reduce(range(n),mapper=mapper1,reducer=reducer1,runner=runner) - >>> holder1(100,LocalMultiProc(4)) + >>> holder1(100,LocalMultiProc(4, num_threads=1)) 328350 """ + @_threads.renamed_num_threads def __init__( self, taskcount, - mkl_num_threads=None, + num_threads=None, weights=None, taskindex_to_environ=None, just_one_process=False, @@ -60,11 +63,15 @@ def __init__( logger.addHandler(logging_handler) self.taskcount = taskcount - self.mkl_num_threads = mkl_num_threads + self.num_threads = num_threads self.weights = weights self.taskindex_to_environ = taskindex_to_environ + num_threads = _threads.canonical_num_threads + mkl_num_threads = _threads.legacy_num_threads + def run(self, distributable): + thread_environment = _threads.environment(self.num_threads) _JustCheckExists().input(distributable) os.environ["PATH"] @@ -101,13 +108,20 @@ def run(self, distributable): sys.executable, distributable_py_file, distributablep_filename, - f"LocalInParts({taskindex},{self.taskcount},mkl_num_threads={self.mkl_num_threads},weights={self.weights},environ={environ})".replace( + f"LocalInParts({taskindex},{self.taskcount},num_threads={self.num_threads},weights={self.weights},environ={environ})".replace( " ", "" ), ] # logging.info(command_string_list) - proc = subprocess.Popen(command_string_list, cwd=os.getcwd()) + # Spawned interpreters must see the limits before importing BLAS. + worker_environment = None + if thread_environment: + worker_environment = os.environ.copy() + worker_environment.update(thread_environment) + proc = subprocess.Popen( + command_string_list, cwd=os.getcwd(), env=worker_environment + ) proc_list.append(proc) for taskindex, proc in enumerate(proc_list): @@ -130,7 +144,7 @@ def run(self, distributable): LocalInParts( taskindex, self.taskcount, - mkl_num_threads=self.mkl_num_threads, + num_threads=self.num_threads, weights=self.weights, environ=environ, ).run(distributable) @@ -140,14 +154,16 @@ def run(self, distributable): if self.taskindex_to_environ is not None else None ) - result = _run_one_task( - distributable, - self.taskcount, - self.taskcount, - distributable.tempdirectory, - weights=self.weights, - environ=environ, - ) + # The reducer can also fit models with BLAS already loaded in this process. + with _threads.limits(self.num_threads): + result = _run_one_task( + distributable, + self.taskcount, + self.taskcount, + distributable.tempdirectory, + weights=self.weights, + environ=environ, + ) _JustCheckExists().output(distributable) return result diff --git a/pysnptools/util/mapreduce1/test_threads.py b/pysnptools/util/mapreduce1/test_threads.py new file mode 100644 index 0000000..5e9b135 --- /dev/null +++ b/pysnptools/util/mapreduce1/test_threads.py @@ -0,0 +1,306 @@ +"""Exercise runner thread limits and BLAS pools visible to threadpoolctl.""" +import json +import os +import pickle +import platform +from inspect import signature +from pathlib import Path +from tempfile import TemporaryDirectory +import unittest +from unittest.mock import patch + +import bed_reader +import numpy as np +from scipy import linalg +from threadpoolctl import threadpool_info, threadpool_limits + +from pysnptools.util.mapreduce1 import map_reduce +from pysnptools.util.mapreduce1.mapreduce import _MapReduce +from pysnptools.util.mapreduce1.runner import LocalInParts, LocalMultiProc +from pysnptools.util.mapreduce1.runner import _threads + + +class _RunnerWithSlot(LocalMultiProc): + __slots__ = ("label",) + + +_THREAD_VARIABLES = ( + "MKL_NUM_THREADS", "OPENBLAS_NUM_THREADS", "OMP_NUM_THREADS", + "PST_NUM_THREADS", "BLIS_NUM_THREADS", +) + + +def _snapshot(): + # Load both libraries before inspecting their actual runtime thread counts. + matrix = np.eye(3) + np.dot(matrix, matrix) + linalg.eigh(matrix) + return { + "pools": [(pool["filepath"], pool["num_threads"]) + for pool in threadpool_info() if pool["user_api"] == "blas"], + "environment": {name: os.environ.get(name) for name in _THREAD_VARIABLES}, + "bed_threads": bed_reader.get_num_threads(), + } + + +def _mapper(value): + return _snapshot() + + +def _reducer(sequence): + return {"workers": list(sequence), "reducer": _snapshot()} + + +def _failing_mapper(value): + raise RuntimeError("mapper failed while thread limits were active") + + +def _failing_reducer(sequence): + list(sequence) + raise RuntimeError("reducer failed while thread limits were active") + + +class TestRunnerThreads(unittest.TestCase): + def setUp(self): + temporary = TemporaryDirectory(prefix="pysnptools-runner-threads-") + self.addCleanup(temporary.cleanup) + previous_directory = os.getcwd() + os.chdir(temporary.name) + self.addCleanup(os.chdir, previous_directory) + self.directory = Path(temporary.name) + self.before = _snapshot() + self.assertBlasPools(self.before["pools"]) + + def assertBlasPools(self, pools): + # macOS wheels use Accelerate, which threadpoolctl cannot inspect. + # Windows ARM64 wheels can also lack a discoverable BLAS pool. Keep + # requiring real pools on Linux and Windows x86, and check every pool + # that is visible on any platform; an empty list is not a test skip. + system = platform.system() + windows_arm = system == "Windows" and platform.machine().lower() in ("arm64", "aarch64") + if system != "Darwin" and not windows_arm: + self.assertTrue(pools, "Requires an actual NumPy or SciPy BLAS pool") + + def assertLimited(self, snapshot, count): + self.assertBlasPools(snapshot["pools"]) + self.assertTrue(all(threads == count for path, threads in snapshot["pools"]), snapshot) + self.assertEqual(snapshot["bed_threads"], count) + self.assertEqual(snapshot["environment"], {name: str(count) for name in _THREAD_VARIABLES}) + + def test_platform_specific_pool_checks(self): + for system, machine, requires_pool in ( + ("Darwin", "arm64", False), ("Darwin", "x86_64", False), + ("Windows", "ARM64", False), ("Windows", "aarch64", False), + ("Windows", "AMD64", True), ("Windows", "x86", True), + ("Linux", "x86_64", True), ("Linux", "aarch64", True), + ): + with self.subTest(system=system, machine=machine): + with patch.object(platform, "system", return_value=system), patch.object(platform, "machine", return_value=machine): + snapshot = {"pools": [], "bed_threads": 2, + "environment": {name: "2" for name in _THREAD_VARIABLES}} + if requires_pool: + with self.assertRaisesRegex(AssertionError, "Requires an actual"): + self.assertLimited(snapshot, 2) + else: + self.assertLimited(snapshot, 2) + with self.assertRaises(AssertionError): + self.assertLimited(dict(snapshot, bed_threads=1), 2) + with self.assertRaises(AssertionError): + self.assertLimited(dict(snapshot, environment={}), 2) + self.assertLimited(dict(snapshot, pools=[("blas", 2)]), 2) + with self.assertRaises(AssertionError): + self.assertLimited(dict(snapshot, pools=[("blas", 1)]), 2) + + def test_canonical_signature_and_positional_compatibility(self): + for constructor, positional in ((LocalMultiProc, (2,)), (LocalInParts, (0, 2))): + with self.subTest(constructor=constructor.__name__): + self.assertIsNone(signature(constructor).parameters["num_threads"].default) + self.assertEqual(constructor(*positional, 2).num_threads, 2) + self.assertIsNone(constructor(*positional).num_threads) + self.assertIsNone(constructor(*positional, num_threads=None).num_threads) + # Parameters after the historical thread-count slot keep their positions. + self.assertEqual(LocalMultiProc(2, 1, [1, 1]).weights, [1, 1]) + self.assertEqual(LocalInParts(0, 2, 1, [1, 1]).weights, [1, 1]) + + def test_deprecated_constructor_keyword(self): + for constructor, positional in ((LocalMultiProc, (1,)), (LocalInParts, (0, 1))): + for count in (None, 1, 2): + with self.subTest(constructor=constructor.__name__, count=count): + with self.assertWarnsRegex(DeprecationWarning, "mkl_num_threads.*num_threads"): + runner = constructor(*positional, mkl_num_threads=count) + self.assertEqual(runner.num_threads, count) + with self.assertWarns(DeprecationWarning): + runner = LocalMultiProc(1, mkl_num_threads=2) + result = map_reduce(range(1), mapper=_mapper, reducer=_reducer, runner=runner) + self.assertLimited(result["workers"][0], 2) + self.assertEqual(_snapshot(), self.before) + + def test_constructor_rejects_both_names_even_with_none(self): + for constructor, positional in ((LocalMultiProc, (1,)), (LocalInParts, (0, 1))): + for canonical, legacy in ((None, None), (None, 1), (1, None), (1, 1), (1, 2)): + with self.subTest(constructor=constructor.__name__, canonical=canonical, legacy=legacy): + with self.assertRaisesRegex(TypeError, "Specify only num_threads"): + constructor(*positional, num_threads=canonical, mkl_num_threads=legacy) + with self.assertRaisesRegex(TypeError, "Specify only num_threads"): + constructor(*positional, canonical, mkl_num_threads=legacy) + + def test_deprecated_attribute_remains_synchronized(self): + for runner in (LocalMultiProc(1, num_threads=1), LocalInParts(0, 1, num_threads=1)): + with self.subTest(runner=type(runner).__name__): + with self.assertWarns(DeprecationWarning): + self.assertEqual(runner.mkl_num_threads, 1) + with self.assertWarns(DeprecationWarning): + runner.mkl_num_threads = 2 + self.assertEqual(runner.num_threads, 2) + runner.num_threads = None + with self.assertWarns(DeprecationWarning): + self.assertIsNone(runner.mkl_num_threads) + + def test_legacy_and_current_pickle_states(self): + for runner in (LocalMultiProc(1, num_threads=2), LocalInParts(0, 1, num_threads=2)): + with self.subTest(runner=type(runner).__name__): + self.assertEqual(runner.__getstate__()["mkl_num_threads"], 2) + self.assertNotIn("num_threads", runner.__getstate__()) + self.assertEqual(pickle.loads(pickle.dumps(runner)).num_threads, 2) + # The native pickle state keeps the field used by older releases. + self.assertEqual(runner.__dict__["mkl_num_threads"], 2) + restored = pickle.loads(pickle.dumps(runner)) + self.assertEqual(restored.num_threads, 2) + self.assertNotIn("num_threads", restored.__dict__) + result = map_reduce(range(1), mapper=_mapper, reducer=_reducer, runner=restored) + if result is not None: + self.assertLimited(result["workers"][0], 2) + self.assertEqual(_snapshot(), self.before) + def test_pickle_preserves_subclass_slots(self): + runner = _RunnerWithSlot(1, num_threads=2) + runner.label = "preserved" + restored = pickle.loads(pickle.dumps(runner)) + self.assertEqual(restored.num_threads, 2) + self.assertEqual(restored.label, runner.label) + + def test_shared_limits_restore_loaded_pools_and_environment(self): + for count in (1, 2): + with self.subTest(count=count): + with _threads.limits(count): + self.assertLimited(_snapshot(), count) + self.assertEqual(_snapshot(), self.before) + with self.assertRaisesRegex(RuntimeError, "sentinel"): + with _threads.limits(1): + self.assertLimited(_snapshot(), 1) + raise RuntimeError("sentinel") + self.assertEqual(_snapshot(), self.before) + + def test_none_is_strict_noop(self): + # None must neither change settings nor create a runtime controller. + with patch.object(_threads, "threadpool_limits", side_effect=AssertionError("None created a controller")): + with _threads.limits(None): + self.assertEqual(_snapshot(), self.before) + self.assertEqual(_threads.environment(None), {}) + self.assertEqual(_snapshot(), self.before) + + def test_validate_thread_counts(self): + for count in (True, False, np.bool_(True), np.bool_(False), 1.5, "2", object()): + with self.subTest(count=count): + with self.assertRaises(TypeError): + _threads.environment(count) + with self.assertRaises(TypeError): + with _threads.limits(count): + self.fail("Invalid thread limit was accepted") + for count in (0, -1): + with self.subTest(count=count): + with self.assertRaises(ValueError): + _threads.environment(count) + self.assertEqual(_threads.environment(np.int64(2)), {name: "2" for name in _THREAD_VARIABLES}) + self.assertEqual(_snapshot(), self.before) + + def test_multiprocess_and_debug_routes(self): + for just_one_process in (False, True): + for count in (1, 2): + with self.subTest(just_one_process=just_one_process, count=count): + result = map_reduce( + range(2), mapper=_mapper, reducer=_reducer, + runner=LocalMultiProc(2, num_threads=count, + just_one_process=just_one_process), + ) + self.assertEqual(len(result["workers"]), 2) + for snapshot in result["workers"] + [result["reducer"]]: + self.assertLimited(snapshot, count) + self.assertEqual(_snapshot(), self.before) + + def test_local_in_parts_limits_mapper_and_reducer(self): + self.assertIsNone(map_reduce( + range(1), mapper=_mapper, reducer=_reducer, + runner=LocalInParts(0, 1, num_threads=1), + )) + self.assertEqual(_snapshot(), self.before) + result = map_reduce( + range(1), mapper=_mapper, reducer=_reducer, + runner=LocalInParts(1, 1, num_threads=1), + ) + self.assertLimited(result["workers"][0], 1) + self.assertLimited(result["reducer"], 1) + self.assertEqual(_snapshot(), self.before) + + def test_none_preserves_current_debug_and_local_in_parts_settings(self): + with patch.dict(os.environ, {name: "2" for name in _THREAD_VARIABLES}), threadpool_limits(limits=2, user_api="blas"): + before = _snapshot() + for runner in (LocalMultiProc(1), LocalMultiProc(1, just_one_process=True), LocalInParts(0, 1)): + with self.subTest(runner=type(runner).__name__): + result = map_reduce(range(1), mapper=_mapper, reducer=_reducer, runner=runner) + if result is not None: + self.assertLimited(result["workers"][0], 2) + self.assertLimited(result["reducer"], 2) + self.assertEqual(_snapshot(), before) + self.assertEqual(_snapshot(), self.before) + + def test_mapper_failures_restore_parent(self): + for runner in (LocalMultiProc(1, num_threads=1, just_one_process=True), LocalInParts(0, 1, num_threads=1)): + with self.subTest(runner=type(runner).__name__): + with self.assertRaisesRegex(RuntimeError, "mapper failed"): + map_reduce(range(1), mapper=_failing_mapper, runner=runner) + self.assertEqual(_snapshot(), self.before) + + def test_reducer_failures_restore_parent(self): + for just_one_process in (False, True): + with self.subTest(just_one_process=just_one_process): + with self.assertRaisesRegex(RuntimeError, "reducer failed"): + map_reduce(range(1), mapper=_mapper, reducer=_failing_reducer, + runner=LocalMultiProc(1, num_threads=1, + just_one_process=just_one_process)) + self.assertEqual(_snapshot(), self.before) + # Exercise the independent LocalInParts reduction route too. + distributable = _MapReduce(range(1), _mapper, None, _failing_reducer) + LocalInParts(0, 1, num_threads=1).run(distributable) + with self.assertRaisesRegex(RuntimeError, "reducer failed"): + LocalInParts(1, 1, num_threads=1).run(distributable) + self.assertEqual(_snapshot(), self.before) + + def test_subprocess_startup_limits_precede_numpy_scipy_imports(self): + startup = self.directory / "startup" + startup.mkdir() + script = '''import json, os +from pathlib import Path +import numpy as np +from scipy import linalg +from threadpoolctl import threadpool_info +matrix = np.eye(3) +np.dot(matrix, matrix) +linalg.eigh(matrix) +record = {"environment": {name: os.environ.get(name) for name in %r}, + "pools": [(pool["filepath"], pool["num_threads"]) for pool in threadpool_info() if pool["user_api"] == "blas"]} +Path(os.environ["PYSNPTOOLS_THREAD_STARTUP"], str(os.getpid()) + ".json").write_text(json.dumps(record)) +''' % (_THREAD_VARIABLES,) + (startup / "sitecustomize.py").write_text(script) + pythonpath = str(startup) + if os.environ.get("PYTHONPATH"): + pythonpath += os.pathsep + os.environ["PYTHONPATH"] + with patch.dict(os.environ, {"PYTHONPATH": pythonpath, "PYSNPTOOLS_THREAD_STARTUP": str(startup)}): + map_reduce(range(2), mapper=_mapper, reducer=_reducer, + runner=LocalMultiProc(2, num_threads=1)) + records = [json.loads(path.read_text()) for path in startup.glob("*.json")] + self.assertEqual(len(records), 2, records) + for record in records: + self.assertBlasPools(record["pools"]) + self.assertTrue(all(threads == 1 for path, threads in record["pools"]), record) + self.assertEqual(record["environment"], {name: "1" for name in _THREAD_VARIABLES}) + self.assertEqual(_snapshot(), self.before) diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index 0a3e630..8ecb6f9 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -120,6 +120,187 @@ def test_sub_matrix(self): submatrix = pstutil.sub_matrix(matrix,[0,2,11],[6,5,4,3,2,1,0]) assert matrix[2,0,1] == submatrix[1,6,1] #The row # 2 is now #1, the column #0 is now #6. + def test_sub_matrix_indices(self): + self._check_sub_matrix_indices(np) + + def test_sub_matrix_indices_cupy(self): + try: + import cupy as cp + except ModuleNotFoundError: + raise unittest.SkipTest("cupy is not installed") + self._check_sub_matrix_indices(cp) + + def _check_sub_matrix_indices(self, xp): + import pysnptools.util as pstutil + + invalid_indices = [ + [0.9], [-0.9], [1.0], [0, 0.9], + [np.nan], [np.inf], [-np.inf], [1 + 0j], ["1"], + [True], [False, 1], (np.bool_(True), 1), + np.array([True, False]), np.array([0.9], dtype=object), + [-1], [3], np.array([2**64 - 1], dtype=np.uint64), + [2**64], [2**100], [-2**100], + 0, [[0]], np.empty((0, 1), dtype=np.int64), + ] + valid_indices = [ + [2, 0, 2], (2, 0, 2), range(2, -1, -1), + np.array([2, 0, 2], dtype=np.int32), + np.array([2, 0, 2], dtype=np.uint64), + np.array([2, 0, 2], dtype=object), + [np.int64(2), np.uint64(0)], [], + ] + for shape in [(3, 3), (3, 3, 2)]: + for order in ["C", "F"]: + for dtype in [np.float32, np.float64]: + values = np.arange(np.prod(shape), dtype=dtype).reshape(shape) + matrix = xp.array(values, order=order) + for indices in invalid_indices: + for axis in ["row", "column"]: + with self.subTest(shape=shape, order=order, dtype=dtype, + indices=repr(indices), axis=axis): + rows, columns = (indices, [0]) if axis == "row" else ([0], indices) + with self.assertRaisesRegex(IndexError, axis): + pstutil.sub_matrix(matrix, rows, columns, dtype=dtype) + for indices in valid_indices: + # Independent NumPy indexing supplies the expected Cartesian product. + expected_indices = np.asarray(list(indices), dtype=np.intp) + for rows, columns in [(indices, [2, 0]), ([2, 0], indices)]: + with self.subTest(shape=shape, order=order, dtype=dtype, + rows=repr(rows), columns=repr(columns)): + actual = pstutil.sub_matrix(matrix, rows, columns, + order=order, dtype=dtype) + expected_rows = expected_indices if rows is indices else [2, 0] + expected_columns = expected_indices if columns is indices else [2, 0] + expected = values[np.ix_(expected_rows, expected_columns)] + self.assertIsInstance(actual, xp.ndarray) + self.assertEqual(actual.dtype, dtype) + self.assertTrue(actual.flags[order + "_CONTIGUOUS"]) + np.testing.assert_array_equal(pstutil.asnumpy(actual), expected) + + def test_sub_matrix_cupy(self): + # cupy is optional; this test needs it and a GPU. + try: + import cupy as cp + except ModuleNotFoundError: + raise unittest.SkipTest("cupy is not installed") + import warnings + import pysnptools.util as pstutil + + def sub_matrix_and_warnings(val, out_order, out_dtype): + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + result = pstutil.sub_matrix(val, row_index_list, col_index_list, order=out_order, dtype=out_dtype) + return result, caught + + rng = np.random.default_rng(0) + row_index_list = [0, 2, 11, 2] + col_index_list = [6, 5, 4, 3, 2, 1, 0] + for shape in [(12, 7), (12, 7, 3)]: + for in_order in ["F", "C"]: + for in_dtype in [np.float64, np.float32]: + matrix = np.asarray(rng.random(shape), dtype=in_dtype, order=in_order) + for out_order in ["A", "F", "C"]: + for out_dtype in [np.float64, np.float32]: + expected, expected_warnings = sub_matrix_and_warnings(matrix, out_order, out_dtype) + actual, actual_warnings = sub_matrix_and_warnings(cp.asarray(matrix, order=in_order), out_order, out_dtype) + # Both paths report narrowing; GPU float64 output additionally + # reports its performance cost. Check every notice rather than + # filtering the new category or weakening the precision check. + import bed_reader + warning_type = bed_reader.GpuFloat64Warning + narrowing = in_dtype == np.float64 and out_dtype == np.float32 + precision_warning = ["Converting float64 to float32 can cause loss of information"] + expected_messages = [str(warning.message) for warning in expected_warnings] + assert expected_messages == (precision_warning if narrowing else []), expected_messages + assert len(actual_warnings) == len(expected_warnings) + (out_dtype == np.float64) + for warning in actual_warnings: + if str(warning.message) not in expected_messages: + assert out_dtype == np.float64 + assert issubclass(warning.category, warning_type) + assert "consumer GPUs" in str(warning.message) + assert isinstance(actual, cp.ndarray) + assert actual.dtype == expected.dtype + assert actual.flags["F_CONTIGUOUS"] == expected.flags["F_CONTIGUOUS"] + assert actual.flags["C_CONTIGUOUS"] == expected.flags["C_CONTIGUOUS"] + np.testing.assert_array_equal(cp.asnumpy(actual), expected) + # cupy indexing would silently wrap these, so sub_matrix must reject them. + matrix = cp.asarray(rng.random((12, 7))) + for bad_rows, bad_cols in [([12], [0]), ([-1], [0]), (np.array([-1]), [0]), ([0], [7]), ([0], np.array([-7]))]: + with self.assertRaises(IndexError): + pstutil.sub_matrix(matrix, bad_rows, bad_cols) + + def test_snpdata_subset_cupy(self): + # End to end: SnpData created under ARRAY_MODULE=cupy holds a cupy val and must subset. + try: + import cupy as cp + except ModuleNotFoundError: + raise unittest.SkipTest("cupy is not installed") + from unittest.mock import patch + from pysnptools.snpreader import SnpData + val = np.arange(24, dtype=np.float64).reshape(6, 4) + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + snpdata = SnpData(iid=[["f", str(i)] for i in range(6)], sid=[f"s{j}" for j in range(4)], val=val) + assert isinstance(snpdata.val, cp.ndarray) + subset = snpdata[np.array([True, False, True, True, False, True]), [3, 1]].read() + # The subset stays on the GPU with its dtype (cp.asnumpy would also accept numpy). + assert isinstance(subset.val, cp.ndarray) and subset.val.dtype == np.float64 + np.testing.assert_array_equal(cp.asnumpy(subset.val), val[[0, 2, 3, 5]][:, [3, 1]]) + + def test_snpdata_cupy_keeps_dtype(self): + # A val moved between numpy and cupy keeps the dtype that same-module input keeps. + try: + import cupy as cp + except ModuleNotFoundError: + raise unittest.SkipTest("cupy is not installed") + from unittest.mock import patch + from pysnptools.snpreader import SnpData + iid = [["f", str(i)] for i in range(3)] + sid = ["s0", "s1"] + cases = [ # (input dtype, _require_float32_64, expected dtype) + (np.float32, True, np.float32), + (np.float64, True, np.float64), + (np.int8, True, np.float64), + (np.int8, False, np.int8), + ] + for array_module, target in [("cupy", cp), ("numpy", np)]: + source = np if target is cp else cp + with patch.dict("os.environ", {"ARRAY_MODULE": array_module}): + for in_dtype, require, out_dtype in cases: + val = source.ones((3, 2), dtype=in_dtype) + snpdata = SnpData(iid=iid, sid=sid, val=val, _require_float32_64=require) + assert isinstance(snpdata.val, target.ndarray), (array_module, in_dtype) + assert snpdata.val.dtype == out_dtype, (array_module, in_dtype, require, snpdata.val.dtype) + # Same-module input keeps the same dtype. + same = SnpData(iid=iid, sid=sid, val=target.ones((3, 2), dtype=in_dtype), _require_float32_64=require) + assert same.val.dtype == out_dtype, (array_module, in_dtype, require, same.val.dtype) + lists = SnpData(iid=iid, sid=sid, val=[[1, 2], [3, 4], [5, 6]]) + assert isinstance(lists.val, target.ndarray) and lists.val.dtype == np.float64 + + + def test_standardize_cupy_matches_rust(self): + # cupy arrays are standardized in Python; results and errors must match the Rust path. + try: + import cupy as cp + except ModuleNotFoundError: + raise unittest.SkipTest("cupy is not installed") + from pysnptools.standardizer import Unit, Beta + rng = np.random.default_rng(0) + val = rng.binomial(2, 0.3, (40, 5)).astype(np.float64) + val[[1, 5, 9], 0] = np.nan # some missing + val[:, 1] = 1.0 # constant + val[:, 2] = np.nan # one observed value + val[0, 2] = 2.0 + for standardizer in [Unit(), Beta(1, 25)]: + for dtype in [np.float64, np.float32]: + expected = standardizer.standardize(np.asfortranarray(val.astype(dtype))) + actual = cp.asnumpy(standardizer.standardize(cp.asarray(val.astype(dtype), order="F"))) + assert actual.dtype == expected.dtype + np.testing.assert_allclose(actual, expected, rtol=0, atol=8 * np.finfo(dtype).eps) + all_missing = val.copy() + all_missing[:, 3] = np.nan + for array in [np.asfortranarray(all_missing), cp.asarray(all_missing, order="F")]: + with self.assertRaisesRegex(ValueError, "No individual observed"): + standardizer.standardize(array) def getTestSuite(): diff --git a/specs/GPU_DOCUMENTATION_AUDIT.md b/specs/GPU_DOCUMENTATION_AUDIT.md new file mode 100644 index 0000000..84e9514 --- /dev/null +++ b/specs/GPU_DOCUMENTATION_AUDIT.md @@ -0,0 +1,125 @@ + + +# GPU documentation review + +Reviewed November 16, 2026, from `8c68afc` (immediately before GPU work) +through `366d6bb`, plus the current working changes. Nothing was published. + +## Scope and corrections + +Read the README, changelog, documentation landing page, GPU guide, former API +preview, and changed docstrings in SNP/kernel readers, data containers, +standardizers, and array utilities. Checked their claims against implementation +and examples. The current inventory includes 34 changed class/method docstrings. + +- Kept the README's GPU introduction to one feature bullet linking the guide + and notebook. +- Corrected reader summaries that promised NumPy-only results or a fresh values + allocation even when `view_ok=True` permits sharing. +- Explained independent per-read backend/dtype selection, float32 preservation, + CPU metadata, Cargo feature requirements, native CUDA device 0, ignored CPU + options, missing/constant SNPs, and trained-statistics precision and alignment. +- Documented `SnpKernel.read_snps(xp=...)`, its ignored `view_ok` argument, and + GPU behavior, with a self-contained doctest. +- Corrected normalization prose and a missing NumPy import. Distinguished fitting + `DiagKtoN` from reusing its scalar on different data. +- Added direct notebook downloads to the generated landing page and guide. + +## Confirmed bugs fixed + +1. **Invalid kernel block sizes:** a negative size could silently return an + all-zero kernel. Validate at `SnpKernel` construction, before reads and + allocations. Reject nonpositive, noninteger, and Boolean sizes with + `ValueError`; keep `None` and positive Python/NumPy integers. The regression + checks the public eager/lazy APIs and an analytic nonzero kernel. +2. **Trained statistics across dtypes:** a misplaced Boolean grouping skipped + dtype/ownership checks for F-order statistics. Applying float32 statistics + to float64 native CPU targets (and the reverse) failed with a misleading + ndarray type error. Both layouts now require a compatible working statistics + array. Original fitted moments remain unchanged. The new regression failed + in four native F-order cases before the fix; it checks both standardizers, + both conversion directions, C/F layout, native/Python execution, missing + values, and a training constant against explicit formulas. + +Neither fix changes the numerical algorithm for valid, already-compatible input. +Widening the target dtype does not recover precision lost during training. + +## Normalization follow-up fixed + + + +Before the follow-up, `DiagKtoN` had inconsistent behavior for a zero-trace kernel. With a 2-by-2 zero +`KernelData`, NumPy execution produces NaNs with divide-by-zero/invalid warnings; +CuPy execution raises `ZeroDivisionError`. This was reproduced on the installed +development wheel. The guide/example uses finite positive-trace data, and the +type documentation states that precondition. + +The implementation now validates the existing scalar reduction before division +and mutation. Both devices raise `ValueError` for zero, negative, NaN, or infinite +denominators and for empty inputs, preserving values on rejection. A separate GPU +sum-of-squares reduction propagates NaNs instead of skipping them as the reused +missing-aware variance reduction did. It keeps float64 GPU accumulation and +uses no additional matrix scan or device-to-host transfer. Valid CPU inputs keep +their established scalar dtype and rounding. A nonfinite or underflowed scaling +factor is also rejected. Applying an already-fitted scalar to zero test data +remains supported. + +Focused CPU/GPU regressions passed: both dtypes, C/F order, SNP/kernel data, +both return modes, invalid/empty inputs, analytic valid results, and trained +reuse on zero test data (176 subtests), including against the installed wheel. +The full follow-up suite passed 754 tests in 297 seconds; the 42 focused GPU +cases, complete installed-wheel notebook, and strict Sphinx build also passed. +These results and the changed behavior are reported directly in the conversation. + +Legacy API concerns remain visible in the guide: `SnpData.standardize(block_size)` +and `SnpKernel.read_snps(view_ok)` ignore those arguments, while direct Unit/Beta +calls warn about `block_size`. A future deprecation pass should make those warnings +consistent without silently changing sharing or standardization behavior. + +## Notebook + +`doc/ipynb/gpu_workflow.ipynb` contains 20 cells and a rendered synthetic PCA plot: + +1. Check the native build and actual CUDA execution; report package/device versions. +2. Write local BED/BIM/FAM data under the user's cache, with missing and constant SNPs. +3. Decode on the GPU; check exact hard calls, duplicate subsets, dtypes, C/F layout, + environment overrides, CPU metadata, and device-preserving `sub_matrix`. +4. Check fractional Unit/Beta inputs against independent centered-variance and + polynomial beta-density formulas in both floating dtypes and memory orders. +5. Fit on training rows, apply without refitting, remap UnitTrained SNP IDs, and + reuse GPU-trained float32 moments on a CPU float64 target. +6. Build held-out BetaTrained kernels in blocks and compare against an independent + float64 product. Build and normalize a full-cohort Unit kernel for GPU PCA. +7. Plot only two transferred coordinates; verify eigenpair residuals on the GPU. +8. Demonstrate warm wall-clock timing with device synchronization before and after + each operation, without claiming a tiny example is faster than the CPU. + +The complete notebook passed in a fresh kernel outside the source checkout using +the installed wheel, CPython 3.13, CuPy 14.2, and an NVIDIA RTX 3060. Hard calls use +exact comparisons. Floating checks state roundoff-based tolerances and kernel +absolute-product scales. Temporary BED files are removed at the end. + +## Validation + +- Wheel and source distribution built successfully; the isolated environment was + refreshed with the development wheel. The notebook and all three independent + guide examples passed against that installed wheel. +- The 42 focused GPU API/general-standardization regression cases passed. +- Both newly added CPU regressions passed, including 24 subtests. Final complete + source canonical validation passed 752 tests in 285 seconds, with HDF5 and BGEN + dependencies available and no skipped tests. +- Strict Sphinx HTML generation passed. Local links/fragments and notebook + downloads resolve. Rendered reader and `read_snps` signatures expose `xp=None` + as the last parameter. The PCA output was visually inspected. +- The canonical suite needs legacy source fixtures absent from the wheel; an + attempted installed-wheel canonical invocation failed during fixture setup. + Full canonical coverage therefore uses the source checkout. This does not + replace the separate installed-wheel notebook and GPU tests. + +Logs and generated HTML are under `~/.cache/python-docs-audit/`, including +`pysnptools-doc-review-{final-canonical,gpu,sphinx,examples,notebook}.log` and +`PySnpTools/review-html/`. The reusable notebook runner is +`/mnt/c/deldir/python-docs-audit/run_pysnptools_notebook.py`. + +Not qualified here: the complete Python/OS matrix, HIP, other GPUs, large or +near-capacity performance, or acceptance against future published GPU packages. diff --git a/uv.lock b/uv.lock index cd28fee..e3c394c 100644 --- a/uv.lock +++ b/uv.lock @@ -89,47 +89,50 @@ wheels = [ [[package]] name = "bed-reader" -version = "1.2.0" +version = "1.3.0a1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, { name = "numpy", version = "2.5.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/90/61/30064dd5d26b321708ec6b8b295518bc0078e11cffe1116fda8379dae4f1/bed_reader-1.2.0.tar.gz", hash = "sha256:9d3aef6c0c8eca688149ebc965665fc137ac23d1fb2835969a3a76d642b78ab7", size = 2657117, upload-time = "2026-11-14T02:06:11.997Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/d7/56/516e5dbbd925e291762cfa00d15df406d83e203e62ccafe5d1663a3e9168/bed_reader-1.2.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:ce1497d9caab8b4362ee9e233ddecf3cc2ea90a02e75fc07eee82ea533e23967", size = 7697363, upload-time = "2026-11-14T02:05:11.605Z" }, - { url = "https://files.pythonhosted.org/packages/0a/bb/eab2ce49a26b26f4bdeec13cf0189b16c0b3df901d550979bb37232536e8/bed_reader-1.2.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:27072729a28d033a729c1b4d11c3a79500949f1e76bbb9b27925cf5559ff4752", size = 6940471, upload-time = "2026-11-14T02:05:13.9Z" }, - { url = "https://files.pythonhosted.org/packages/c8/62/e470b263599dcbf19b935957a552601d417562c1b198dc7d2bd8855abb23/bed_reader-1.2.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c7a0a603d2bbbbda26b03bd0d31d70c98649c6320a212d974bec8554aae501f6", size = 7993637, upload-time = "2026-11-14T02:05:15.77Z" }, - { url = "https://files.pythonhosted.org/packages/7d/f6/17a7bc1148a479ea753eeff851dc30cccb394054fc3924a0b51339701d45/bed_reader-1.2.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:225d97f543ff8c6d2137a44bb5882acef650dee36e07d15974a05229212b5e8c", size = 7972039, upload-time = "2026-11-14T02:05:17.505Z" }, - { url = "https://files.pythonhosted.org/packages/c3/ff/812dbae900b29b9ea29b5f7b3f23aaecde8b5fe2771ee00a4cb8f36108b0/bed_reader-1.2.0-cp311-cp311-win_amd64.whl", hash = "sha256:cb5571574a4667482e6b248b3bbe64f9cff051835052918da6a5500dbc04913d", size = 7393103, upload-time = "2026-11-14T02:05:19.261Z" }, - { url = "https://files.pythonhosted.org/packages/96/8a/56731f32845eafd4d731c939c73c595abdafdf924289f4319473c54e973d/bed_reader-1.2.0-cp311-cp311-win_arm64.whl", hash = "sha256:8dec5e520119a207e857acfd6209391cb821cde24eab4c21fa1c66357b564190", size = 7067970, upload-time = "2026-11-14T02:05:20.885Z" }, - { url = "https://files.pythonhosted.org/packages/7a/e2/873fe623fa04ed3bc38c68cecff078fdbcd8244fc1f8e6f8ef41fe41ecf5/bed_reader-1.2.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:b5f953dd36a8c70b5df2284cb63d3f2e16ef7a0908c3eb122df326994f9dc7ce", size = 7700494, upload-time = "2026-11-14T02:05:22.748Z" }, - { url = "https://files.pythonhosted.org/packages/65/eb/76b2313afcda579f45ed11780b307a742caa23fb68be098c87bade939052/bed_reader-1.2.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:010850b4c1ef8a82b474bf0d23131c429736b792b7f7ab6ff320018cb683304a", size = 6940511, upload-time = "2026-11-14T02:05:24.543Z" }, - { url = "https://files.pythonhosted.org/packages/9d/f7/987990688b7c00e872d8c0e14387cdf6c46d133c3b1cbcb4834a67d18b71/bed_reader-1.2.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:929e5fc880681c9f485e3c4e273d07d7e8ba1dde68e9d7bc226ca54280a65d63", size = 7971036, upload-time = "2026-11-14T02:05:26.486Z" }, - { url = "https://files.pythonhosted.org/packages/db/b5/279fe1929e00ccef554ec477e5b0be0e3df404960bceb643085ef2c20aaf/bed_reader-1.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:9320e984b915a6b81b57d09259f5ca80c3d780e0fe7f3dbbdfccc420e49adc14", size = 7966524, upload-time = "2026-11-14T02:05:28.53Z" }, - { url = "https://files.pythonhosted.org/packages/53/f6/f4c72d1f987753c1c011da423531d8a75825843b6ebaaa937bb26ca93d32/bed_reader-1.2.0-cp312-cp312-win_amd64.whl", hash = "sha256:007b1fb7ffd3022720804b44d93d0e4184a0f0bf5cf51a7b82871e930b02c790", size = 7389615, upload-time = "2026-11-14T02:05:30.868Z" }, - { url = "https://files.pythonhosted.org/packages/84/65/2268b2e72dc45d559168043af2e716f05a26a72443853911cc94911560c3/bed_reader-1.2.0-cp312-cp312-win_arm64.whl", hash = "sha256:05904a642a4046e6a5e1b2d35cb58aba45ca3c4e328be6b02b5ccd0c7302c4c2", size = 7070412, upload-time = "2026-11-14T02:05:33.025Z" }, - { url = "https://files.pythonhosted.org/packages/84/59/da826b5602e79380643971b83e95f7d3adc970c8caf3123b8c2eb41ce499/bed_reader-1.2.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:13d8b80e0c7c19cf1c3f252f814616a486af4ac32e8646a9bb46eb26980d2025", size = 7699746, upload-time = "2026-11-14T02:05:35.546Z" }, - { url = "https://files.pythonhosted.org/packages/a4/ac/d08a0fdfe67eaa2b9bc7ccfc72ea558a13a7dfd9d78ef7f6a7046f125efd/bed_reader-1.2.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:c50ac516570e301ee7ec67138e44c7c5470c9a623179ff7ac6a8871160ca10f0", size = 6940105, upload-time = "2026-11-14T02:05:37.563Z" }, - { url = "https://files.pythonhosted.org/packages/92/23/c01ff7238a07019436bddd92b6d13d4176547fd6e84c6af7c4f51d2af61f/bed_reader-1.2.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:0225bfe3bc548683598b49e01538766afaa0ac6b8c7791b038f8a0b91a25e345", size = 7969659, upload-time = "2026-11-14T02:05:39.506Z" }, - { url = "https://files.pythonhosted.org/packages/4d/eb/e78b1a8bbbb8fc05a21c7823f910aeaf0e74b4f00796a27d751545eb13b4/bed_reader-1.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:50b5aadb3d5151bfd41c20cfe5487f2b204a2b7f5d2bdfcfea59f38209de6065", size = 7966232, upload-time = "2026-11-14T02:05:41.408Z" }, - { url = "https://files.pythonhosted.org/packages/bb/fa/4078cf4d06594017450791ffc04f85e9c064ff92a1c543e78eeee610c3ac/bed_reader-1.2.0-cp313-cp313-win_amd64.whl", hash = "sha256:4811c9b19fd5c43008dae0fc339790f24e2c5b81093149b62c598b3f56d45fa3", size = 7389213, upload-time = "2026-11-14T02:05:43.573Z" }, - { url = "https://files.pythonhosted.org/packages/16/fe/6e76375742358e3a9ebb8ad9dc3598fb01fbe5c785e6fc1a6633606e7c78/bed_reader-1.2.0-cp313-cp313-win_arm64.whl", hash = "sha256:685401ae617896c73217d1b3936dec307c990d5f5f73ce4905073d5c4dafe2b1", size = 7069771, upload-time = "2026-11-14T02:05:45.405Z" }, - { url = "https://files.pythonhosted.org/packages/1e/b8/92aa6b61beceb4b838c651cac3d059450a9628575958fb5dff0ae7b2e0fa/bed_reader-1.2.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:7a4d3018c2877cbdc2ed2b2fd074a6a0a36f0b6f23ba478550661f5e72591a43", size = 7703176, upload-time = "2026-11-14T02:05:47.415Z" }, - { url = "https://files.pythonhosted.org/packages/21/b5/d9ff2bb026fc4a659f351a1c360f377e0681713632ed3f9431222d9eca34/bed_reader-1.2.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4dbb9c28f6c4791e2bc11d868fc83e1c4f239ef9729f83e8923eefa40471aabe", size = 6940882, upload-time = "2026-11-14T02:05:49.369Z" }, - { url = "https://files.pythonhosted.org/packages/1a/79/cb11bafb1373f0cb6d9939be48ad361d3cd8aaf178f07dfea4fde315662e/bed_reader-1.2.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:a1ba68077a2c687ea077e79052b3e9a70ac8da1f55afdffcbdbb53c94c2ab4bd", size = 7998285, upload-time = "2026-11-14T02:05:51.504Z" }, - { url = "https://files.pythonhosted.org/packages/21/f1/764ba2892bdfc2be17b93462d2d41267d8a3e7c97cd81fd8bc07f4b52a1b/bed_reader-1.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:759d6cfc90f25b5a86b92296879c16e8e7cb92f3ebadf1386486544ddc4a8fd6", size = 7976017, upload-time = "2026-11-14T02:05:53.385Z" }, - { url = "https://files.pythonhosted.org/packages/92/48/cd8cd4050af5706836675066acc7b8c8747b097fd095feeb54c541daff05/bed_reader-1.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:b117c41ef6ddd684fbe338774a3ca1ff57ae5a87a229cf7f3eaf214c73bfc399", size = 7390946, upload-time = "2026-11-14T02:05:55.364Z" }, - { url = "https://files.pythonhosted.org/packages/97/2a/f532a1a225214775c7d8a12d7954d4461b32d279b3494c346047da5d42ed/bed_reader-1.2.0-cp314-cp314-win_arm64.whl", hash = "sha256:ec2f6a278e70d0a9d21cfbe86f19f4ffe461247c2b11bd9c0b101f06bd32bb41", size = 7070569, upload-time = "2026-11-14T02:05:57.242Z" }, - { url = "https://files.pythonhosted.org/packages/18/73/7d7fd630e5224fe98ffd26f4c086618bc4753049e6fe355131a4b0d84d43/bed_reader-1.2.0-cp315-cp315-macosx_10_12_x86_64.whl", hash = "sha256:55687970bda6dbcf47d9219930267b6cdd6d20424fe7ef8626531c670e251d43", size = 7703500, upload-time = "2026-11-14T02:05:59.371Z" }, - { url = "https://files.pythonhosted.org/packages/6c/da/153aa88168870b89cfba23d1a88f8522e345d12f8dbafb4dfcb694eeb1c9/bed_reader-1.2.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:013158bc55663c978bb8be9b72ad40bb51bacfc1b4053f68adf35bd9aad9b03f", size = 6941476, upload-time = "2026-11-14T02:06:01.241Z" }, - { url = "https://files.pythonhosted.org/packages/43/82/fca856651b3026ac8e29161901a15fdbef3c3f23f8deadc774bdf269deb2/bed_reader-1.2.0-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:bf727e4f056355efe81933310b3b8982f5a28e123468e9d617265571a2b4bdaa", size = 7995642, upload-time = "2026-11-14T02:06:03.352Z" }, - { url = "https://files.pythonhosted.org/packages/65/f6/86cf4d3987dfafb94e5cb2573265f1c8e978051cc279339c093678475517/bed_reader-1.2.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:f5a5806b774241195d6daffaee2a65076002b70b657ad31fb8eae221f648e260", size = 7976438, upload-time = "2026-11-14T02:06:06.159Z" }, - { url = "https://files.pythonhosted.org/packages/79/71/f0af5da2b563416c7d2c714959d7220e7c2a5f2908b7e194de40bf7d1236/bed_reader-1.2.0-cp315-cp315-win_amd64.whl", hash = "sha256:5b84de0d4b26a6cb273fb4a0db5e9135826d9011bcc1de0d5c51561214ac9636", size = 7391098, upload-time = "2026-11-14T02:06:08.333Z" }, - { url = "https://files.pythonhosted.org/packages/42/7a/14e15fbedb95640e67b764589218ab9c3609df3a1a06a97e477c9f499d8f/bed_reader-1.2.0-cp315-cp315-win_arm64.whl", hash = "sha256:f108f85fc2d5f38a81f31e159492b3208a18cb86d491365ebfb12f1d93ba53b5", size = 7070742, upload-time = "2026-11-14T02:06:10.2Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/d2/12/604ad1f036bd0851f5a91bcf13b86c07686ec12ff63f267471a7b956e6cb/bed_reader-1.3.0a1.tar.gz", hash = "sha256:8b7e3f4515a95390d529b9a7762f53c0d2d3432f59b2a5f2f78aba3b061ff7ef", size = 2717943, upload-time = "2026-11-18T03:25:31.567Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8b/61/4ab8e20ea2f7b84ed08c607c351cfc98cdab796e2769925fb20a5c5fd303/bed_reader-1.3.0a1-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:ac3b6bf490ada182e9cc5dc37cc3a49283ff95d64e42aacffcb053cab855731e", size = 7714789, upload-time = "2026-11-18T04:51:08.265Z" }, + { url = "https://files.pythonhosted.org/packages/cc/01/1bd6bf633903f911bd63b34a2cd216b72400dc886a4b108cd11ed8f6d62c/bed_reader-1.3.0a1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:11d31840c2c0a60beaf5879cade5ae3606247564aa09290e7454aaf48c967bfc", size = 6958973, upload-time = "2026-11-18T04:51:10.591Z" }, + { url = "https://files.pythonhosted.org/packages/82/fc/3235d8a6d9b17572c25c0f31571cff79c85406267045a6019a9cb12aed84/bed_reader-1.3.0a1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d773bc733d84be7551ccac0e0bdf319aa80c79ff45d587494b2b39a07fa97626", size = 8014664, upload-time = "2026-11-18T04:51:12.673Z" }, + { url = "https://files.pythonhosted.org/packages/d0/14/ad0d55002ea995efaaf147f8aae826ee0ab3c52372329dc69563f6f00af1/bed_reader-1.3.0a1-cp311-cp311-manylinux_2_35_x86_64.whl", hash = "sha256:e1de6297a2366dee3ce41488d43934a785f562cfcc4c6d994c443a7721f178e9", size = 43996257, upload-time = "2026-11-18T03:24:46.056Z" }, + { url = "https://files.pythonhosted.org/packages/c5/e1/58ce994977eaf52d0fd5caceaed24b9e2c703650816fa9219ee42199ac62/bed_reader-1.3.0a1-cp311-cp311-win_amd64.whl", hash = "sha256:2f8246be9754c1f7f75b23a9e0ac58693891b1c4aa8f3477e77b8936364553b6", size = 34723736, upload-time = "2026-11-18T03:24:50.531Z" }, + { url = "https://files.pythonhosted.org/packages/76/ab/e7b389ee00f043e497d5471c4689e9c34150cbd1911674e8289b9e12c3ab/bed_reader-1.3.0a1-cp311-cp311-win_arm64.whl", hash = "sha256:5fc664dfdafe158cc848083695697e4c3a4c57d5cf943393e873b933f57924cc", size = 7075434, upload-time = "2026-11-18T04:51:14.736Z" }, + { url = "https://files.pythonhosted.org/packages/e2/a3/d16b409c1bdba7c69239d85c802d0e15380f4ea3d3b2b138538be872b812/bed_reader-1.3.0a1-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:2f5d237bfbe414403f15a518cdabe4e9beea1f55681bce67f5b211a344138b19", size = 7718023, upload-time = "2026-11-18T04:51:17.152Z" }, + { url = "https://files.pythonhosted.org/packages/aa/80/c8771f946d1ab57f9866d67737f82b0a24ad17c7e15dd4ba98b5b2dfbbff/bed_reader-1.3.0a1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8e65485cb49012aafd284afba93fcd977304c4ed84e6e14beac8591098ac0c95", size = 6957093, upload-time = "2026-11-18T04:51:19.316Z" }, + { url = "https://files.pythonhosted.org/packages/b8/6c/4d77b324883c8ddc4d3c8f1966b4014ccb0f9443c43ef7591249f526287d/bed_reader-1.3.0a1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:05bbd07bec59378c580650d63596a382a2f834ea2e21c253cb0dcc9e0e6ba867", size = 8009691, upload-time = "2026-11-18T04:51:21.924Z" }, + { url = "https://files.pythonhosted.org/packages/0b/e3/707f19527de7fa164b5e7441e01b3014810d506ae001828a39845533180a/bed_reader-1.3.0a1-cp312-cp312-manylinux_2_35_x86_64.whl", hash = "sha256:f8818b6e8d0a1b02cbb55bb0889eacb166089a26fb633e4da8ceaf2cf14bedbe", size = 43999538, upload-time = "2026-11-18T03:24:55.173Z" }, + { url = "https://files.pythonhosted.org/packages/5f/31/682be4684722ecd8e5c8b8012b570b8cb397d0d6988a4ea091134434132a/bed_reader-1.3.0a1-cp312-cp312-win_amd64.whl", hash = "sha256:21070d562c25a7b83d5613a6cac6557e2fb49cf2fa5275fbae1b2c8c461607e4", size = 34714204, upload-time = "2026-11-18T03:24:59.418Z" }, + { url = "https://files.pythonhosted.org/packages/09/c5/68a722d64c9ec69544f3e177e6fcd2f152f63e2753e90a53109daf75f8b9/bed_reader-1.3.0a1-cp312-cp312-win_arm64.whl", hash = "sha256:80403b15f7f6c0a045e39eabdc6369dba1624ff78a0afc191281f178c11f4f67", size = 7074845, upload-time = "2026-11-18T04:51:24.297Z" }, + { url = "https://files.pythonhosted.org/packages/12/33/f5ccc3ee622595c11a30789ee6edbf06ef776e099f5bc1e7f1f871e815e5/bed_reader-1.3.0a1-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:c43eaecd3b2903855ecfeb8fb8ab5829b4918b4a7caa8686ed5cd100d197f7d0", size = 7717897, upload-time = "2026-11-18T04:51:26.587Z" }, + { url = "https://files.pythonhosted.org/packages/f7/d9/dcd49f662695d72e8a76eb165878de986a1ea6eb73ba4bdb096b8d38475f/bed_reader-1.3.0a1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:0a878a14071af6ee9ef903c08e778b7e0c6667f74b67c71736f7c6bcf348828e", size = 6956664, upload-time = "2026-11-18T04:51:29.061Z" }, + { url = "https://files.pythonhosted.org/packages/fa/23/d09160273de30971865ea24d3aabe7e12219e9f6332d162ae1b047ed4f79/bed_reader-1.3.0a1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b43ebf8c8bdba922c4e3ee0bdedc5603f7ae63ead943a3838e520e3187167575", size = 8008633, upload-time = "2026-11-18T04:51:31.251Z" }, + { url = "https://files.pythonhosted.org/packages/b4/38/355006bc825f037eadacfd66adf06bd47bbce83ec85ab2f657a7139bca30/bed_reader-1.3.0a1-cp313-cp313-manylinux_2_35_x86_64.whl", hash = "sha256:48ad9c22ec825c696792579f72a55c3d129f5085bca31db4f034d43fc4337a43", size = 44004121, upload-time = "2026-11-18T03:25:04.186Z" }, + { url = "https://files.pythonhosted.org/packages/57/92/9d004693c6a28aed80ea90b7a6aa1bd714df1cef48b3c4218520a4baa318/bed_reader-1.3.0a1-cp313-cp313-win_amd64.whl", hash = "sha256:936d7e6d2f2d19c26c54c7eb0ac0d2c4eeb74fa1c21298665e75f20942713235", size = 34712304, upload-time = "2026-11-18T03:25:09.029Z" }, + { url = "https://files.pythonhosted.org/packages/5a/bb/486a505979190837e74758cf428c8257c57c722eb398db6ab0ecca60df51/bed_reader-1.3.0a1-cp313-cp313-win_arm64.whl", hash = "sha256:1cd589cc39e0bbc2679cd8aa0d611c0c089100acad4d9ef3a663fc0511889788", size = 7074162, upload-time = "2026-11-18T04:51:33.678Z" }, + { url = "https://files.pythonhosted.org/packages/1d/93/c4e3d10d63960e7bd81ac9e70eb2095fe21ff74809b33b42e237ae6599bb/bed_reader-1.3.0a1-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:29f5fb95d0ed4e369a2872494a11fd2da552301a3bc4b1dba8eb2fab63417bd0", size = 7720629, upload-time = "2026-11-18T04:51:35.804Z" }, + { url = "https://files.pythonhosted.org/packages/6b/12/92bf28fd116fd4262f92c405ec3181221236882d6dda2a8ab2fd5f131f65/bed_reader-1.3.0a1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:2f66268c56587978dfb20692942ea59379027f7fd3b2164d3bb4869f881ed82c", size = 6958404, upload-time = "2026-11-18T04:51:38.093Z" }, + { url = "https://files.pythonhosted.org/packages/3f/36/725e81935bf4952e3d97db0fb165bbfcc61043399e8e8a51bce4f0125ea5/bed_reader-1.3.0a1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:856debd0d0ccc8271253d83b8d10f395b187050314ddc35a3d83a00ba6cc3c1e", size = 8015326, upload-time = "2026-11-18T04:51:40.228Z" }, + { url = "https://files.pythonhosted.org/packages/45/f3/d41cfc482d10cd2a12fcd3012e9c4bee741015e16ccbfac2ca236d87c57c/bed_reader-1.3.0a1-cp314-cp314-manylinux_2_35_x86_64.whl", hash = "sha256:2a0cc89a3564e5b96cb974907b1c30ca99feef775282e5483bdc895488f0abc2", size = 43999440, upload-time = "2026-11-18T03:25:13.983Z" }, + { url = "https://files.pythonhosted.org/packages/49/e5/11383d4144e8f22d60e4981e01e5c648dca2325a177a95713f781f0e0a89/bed_reader-1.3.0a1-cp314-cp314-win_amd64.whl", hash = "sha256:ed83e8d1561974a92be39d7e1e2f08139a9cfbfd87506b4eec9994a43080ea5c", size = 34713338, upload-time = "2026-11-18T03:25:18.911Z" }, + { url = "https://files.pythonhosted.org/packages/30/ed/16e9f119e3ec6a8d17e1ba2f531df64a6b0549fe3b0b9d23a5dff01802ef/bed_reader-1.3.0a1-cp314-cp314-win_arm64.whl", hash = "sha256:a1b146c7e5d589ba5c6e67685f94efea5d95b46ace042478a9807eeeedeacc64", size = 7080132, upload-time = "2026-11-18T04:51:42.19Z" }, + { url = "https://files.pythonhosted.org/packages/f9/30/c8a2ba44682e15221b8ae76a2fa0a1387f8bd3baf8a9eb9dbf4f4de2c12c/bed_reader-1.3.0a1-cp315-cp315-macosx_10_12_x86_64.whl", hash = "sha256:269363251021474ce2915f59163752246491901fff904b8c1d62c99b1a9d863f", size = 7720898, upload-time = "2026-11-18T04:51:44.265Z" }, + { url = "https://files.pythonhosted.org/packages/5b/aa/7352561a4cbb1e1b8a5e672371537a9d6a97da5dc843a5effcf5dc04e014/bed_reader-1.3.0a1-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:4890aac4239b9532719417fb26b41d370e7c48f81ca063d2d84b9f31346ffe06", size = 6957903, upload-time = "2026-11-18T04:51:46.231Z" }, + { url = "https://files.pythonhosted.org/packages/c1/0f/53b5d7139a1efab09971bb36757e7c925456338858a36f1981ab19aaeb49/bed_reader-1.3.0a1-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:0e65abf6612c07b03803f893639ed2e021e67f344bbf84e266e3180aa8f38447", size = 8016652, upload-time = "2026-11-18T04:51:48.209Z" }, + { url = "https://files.pythonhosted.org/packages/99/78/4a4a2435f94b17fe3b7e5af15e396debca429c434973172ce2de19eee2b8/bed_reader-1.3.0a1-cp315-cp315-manylinux_2_35_x86_64.whl", hash = "sha256:b1ae684b594f62f049e944ed46dbc9f87a8dd13ff22061b2c6fade5892beb305", size = 43998167, upload-time = "2026-11-18T03:25:24.417Z" }, + { url = "https://files.pythonhosted.org/packages/88/06/92bab6b34e46241ba2110c9c1e02122f41c51f582663511653b337e18b31/bed_reader-1.3.0a1-cp315-cp315-win_amd64.whl", hash = "sha256:2d04bbc24d36b6e9ba7437b07c538c03be886c6ec36e27214a91220f24ed7414", size = 34710637, upload-time = "2026-11-18T03:25:29.154Z" }, + { url = "https://files.pythonhosted.org/packages/f7/89/ff5c222caaa771e511dcd5aa4f03ad40b90b3ea1c74828dacb82b75f4f0b/bed_reader-1.3.0a1-cp315-cp315-win_arm64.whl", hash = "sha256:4f6a319d9d9f2de8cbff1246a2e8521858c3b3b569c5466e9f1a460caf4786ca", size = 7080324, upload-time = "2026-11-18T04:51:50.176Z" }, ] [package.optional-dependencies] +cupy = [ + { name = "cupy-cuda13x" }, +] samples = [ { name = "pooch" }, ] @@ -851,6 +854,46 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b6/b1/d9121a717e0f893c64bd6ca7702614778d7df2a5c309128a002421788516/cryptography-50.0.2-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:1ba34f04897fcdaa73f74145c25f3ec146fbd56593853e88adc2e811303c5f42", size = 4726322, upload-time = "2026-09-30T15:29:54.263Z" }, ] +[[package]] +name = "cuda-pathfinder" +version = "1.9.0" +source = { registry = "https://pypi.org/simple" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b6/80/7cf8bbe4a8844198fa64481ffc6642003770999b9ead27e99fc03484989a/cuda_pathfinder-1.9.0-py3-none-any.whl", hash = "sha256:622df7440f7702f36b7a02a1699aa0b084fe04034d9939188fee9b16d0c36366", size = 63362, upload-time = "2026-11-13T17:02:04.522Z" }, +] + +[[package]] +name = "cupy-cuda13x" +version = "14.2.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "cuda-pathfinder" }, + { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, + { name = "numpy", version = "2.5.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, +] +wheels = [ + { url = "https://files.pythonhosted.org/packages/8d/3c/4716e285f8459a5707ef39d84e9a7547bf16f87c583ac4789c0763d6d986/cupy_cuda13x-14.2.0-cp311-cp311-manylinux2014_aarch64.whl", hash = "sha256:a22e2f17c97940cd566f351f186d8fe04285280d052ca1512ff223febbe9979c", size = 74074375, upload-time = "2026-08-20T02:41:04.327Z" }, + { url = "https://files.pythonhosted.org/packages/ac/cb/41b6d8f1880e6f3128f8084b7622b1a3ca2d615ab77af9ef313b4aafed3d/cupy_cuda13x-14.2.0-cp311-cp311-manylinux2014_x86_64.whl", hash = "sha256:f94843e54500a9c8c169135f79572bfaba946efe4f7178e834c227280c1b0c12", size = 69969199, upload-time = "2026-08-20T02:41:07.842Z" }, + { url = "https://files.pythonhosted.org/packages/f8/eb/25b8c1a415ade6479ed684c5cbff1e6f5002a92cbf26ef826df56a40cf69/cupy_cuda13x-14.2.0-cp311-cp311-win_amd64.whl", hash = "sha256:3893acd8d4dc78d113736045eaa306e496ee7bd8253bd959513ba28c91ed396d", size = 36082966, upload-time = "2026-08-20T02:41:10.723Z" }, + { url = "https://files.pythonhosted.org/packages/10/72/ad885cc21a21208b94044b34f50a840394b2e9dbb6111ed43959366aa6eb/cupy_cuda13x-14.2.0-cp311-cp311-win_arm64.whl", hash = "sha256:e0ad42a1ef35549282e2087a7c1e6ec8b7aa624a95e8fc0a60da777ca87e71de", size = 35136070, upload-time = "2026-09-01T06:41:38.284Z" }, + { url = "https://files.pythonhosted.org/packages/dd/c8/68e07ff959f6a9f93169e37a64a4c24223487102b8625191e4a566cab465/cupy_cuda13x-14.2.0-cp312-cp312-manylinux2014_aarch64.whl", hash = "sha256:0a9b6538079c5151dcd99cf44b94cc3f1242315b7de0498b4619cef9b2a7c2c8", size = 73382974, upload-time = "2026-08-20T02:41:13.648Z" }, + { url = "https://files.pythonhosted.org/packages/7e/bf/c4c25e97552320451afdcd459d4b6e0b715459594e998b23051c06db64c3/cupy_cuda13x-14.2.0-cp312-cp312-manylinux2014_x86_64.whl", hash = "sha256:9aafadbe29db3d4285026044aafeb28f2a3de4bd0df70718ec6892b7d27a4ded", size = 69439247, upload-time = "2026-08-20T02:41:17.375Z" }, + { url = "https://files.pythonhosted.org/packages/5e/88/0a4d2d075485c4a82bfcd4725300ff87d17de36dce27b36f720d286f0f70/cupy_cuda13x-14.2.0-cp312-cp312-win_amd64.whl", hash = "sha256:9e8bc8a7693c5c212cd1450d728f47e1f05aa07ae003de30415893d0daf7d243", size = 35986921, upload-time = "2026-08-20T02:41:20.253Z" }, + { url = "https://files.pythonhosted.org/packages/a4/ab/8a756f553397b8509906d4a1d8083d92d3d21cbde115504e7a5db97de61f/cupy_cuda13x-14.2.0-cp312-cp312-win_arm64.whl", hash = "sha256:0dae6d788752c987c1cd87adb903640620820feb895339e8bc51a01fba0fb804", size = 35049803, upload-time = "2026-09-01T06:41:43.442Z" }, + { url = "https://files.pythonhosted.org/packages/3c/02/3cb39774c71a16275c50b5d1e92ddcefa948ff1e69f464249b70a79b0abe/cupy_cuda13x-14.2.0-cp313-cp313-manylinux2014_aarch64.whl", hash = "sha256:449af7f608dc70ce64e8c45cf5a6ea0bbef51623e7c806b1a43445ae3c76e1e0", size = 72969322, upload-time = "2026-08-20T02:41:23.311Z" }, + { url = "https://files.pythonhosted.org/packages/4e/27/216370ae8c39fa9835645be3c27513ab72f52cf4f51faf58d799fba981b6/cupy_cuda13x-14.2.0-cp313-cp313-manylinux2014_x86_64.whl", hash = "sha256:5b79a606f6639d9bed74ef7072f36756a95a804c86d7adb367b39307ac771600", size = 69048238, upload-time = "2026-08-20T02:41:26.831Z" }, + { url = "https://files.pythonhosted.org/packages/5d/75/9df3c545baad4ff2e384db1ff6c8005fa4040492c4ee5672ca8b8711d29d/cupy_cuda13x-14.2.0-cp313-cp313-win_amd64.whl", hash = "sha256:f9a2a55abf889f6df68b5f62cd5f3ec4a2f305ac57ed09becd52e16201edcd86", size = 35965490, upload-time = "2026-08-20T02:41:29.943Z" }, + { url = "https://files.pythonhosted.org/packages/5c/3d/ee85ce39c2f32e8561c81c507df458a914b45d9a0eb1a54e5396c2cfd632/cupy_cuda13x-14.2.0-cp313-cp313-win_arm64.whl", hash = "sha256:5ddaf38291f60ec20e8c7889b28e339bf17ad1b4df768b8bb5e6c9f9e445efbb", size = 35029087, upload-time = "2026-09-01T06:41:48.593Z" }, + { url = "https://files.pythonhosted.org/packages/e5/70/8c80c9e7010193afed8ccb7110d6173aa23bf3a6ce2fc2450244b0fa50a1/cupy_cuda13x-14.2.0-cp314-cp314-manylinux2014_aarch64.whl", hash = "sha256:7ac57c4e16c62f265b5ecc2b45d6bbafe9dc70a99b849ed6cfb8d16f32204589", size = 72840193, upload-time = "2026-08-20T02:41:33.146Z" }, + { url = "https://files.pythonhosted.org/packages/c2/b8/4f4c4f34fc31ab8d136ed965a919505297974629d9852c50e15bfd616281/cupy_cuda13x-14.2.0-cp314-cp314-manylinux2014_x86_64.whl", hash = "sha256:ff0bdebd1b43c0c6db53095784c787c4e4eae671356cf521c4b7482ed78a1a7e", size = 68422828, upload-time = "2026-08-20T02:41:36.527Z" }, + { url = "https://files.pythonhosted.org/packages/7d/5c/58941ece5ed0b2cc8304f8ba81b5e8334759d409306475d53c52ac99809b/cupy_cuda13x-14.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:b99a8bf9d5391954c0c08675a8cb39219923fe2ee249faa3546ebbf75783a360", size = 36110882, upload-time = "2026-08-20T02:41:39.837Z" }, + { url = "https://files.pythonhosted.org/packages/e2/c5/cc7d1a9b764b3f828e09b48a73d0fdeaad15ecd2c7e50507f6d5fcf5fd1a/cupy_cuda13x-14.2.0-cp314-cp314-win_arm64.whl", hash = "sha256:c61c59ba665948c0a855926997ee96026420b628816b2e406998ec797caddb22", size = 35184806, upload-time = "2026-09-01T06:41:58.317Z" }, + { url = "https://files.pythonhosted.org/packages/6f/54/a582ac70e9e75d3fad7ae073051bcd50dd128a1f66dd275291dc5f48d997/cupy_cuda13x-14.2.0-cp314-cp314t-manylinux2014_aarch64.whl", hash = "sha256:e8bb453551deced08ec5c4576da61ebf1e2b4a45aeff48e09f47ec332f7cad3d", size = 73336756, upload-time = "2026-08-20T02:41:42.718Z" }, + { url = "https://files.pythonhosted.org/packages/f9/aa/222151ba5061d7a01efe4009efad9f9a7164e15bb2a494d9aa86efc97d4f/cupy_cuda13x-14.2.0-cp314-cp314t-manylinux2014_x86_64.whl", hash = "sha256:313500c5d415f65d388e84a9d2eb7f07f97c23c85dc5785f986e75d46d9c9693", size = 68792663, upload-time = "2026-08-20T02:41:46.079Z" }, + { url = "https://files.pythonhosted.org/packages/d4/20/13dd37dbeaec879c8348fde2bfca67d96daa56a6e63e4a5083ff61660e53/cupy_cuda13x-14.2.0-cp314-cp314t-win_amd64.whl", hash = "sha256:c517fc55502a7e3d1a8b9310abad95cec61dded5a38d328fe0220bcf7b036268", size = 37004845, upload-time = "2026-08-20T02:41:48.963Z" }, + { url = "https://files.pythonhosted.org/packages/d1/5b/b1367f79abd90a259dbb7f0603dd162c03c3a76ec1d02c2527b0c79d46ba/cupy_cuda13x-14.2.0-cp314-cp314t-win_arm64.whl", hash = "sha256:83885db963eb0b95a0757b4907a37115a1d2aebfa9cf43b99ebac8db35713d37", size = 35485280, upload-time = "2026-09-01T06:41:53.618Z" }, +] + [[package]] name = "cycler" version = "0.12.1" @@ -2444,7 +2487,7 @@ wheels = [ [[package]] name = "pysnptools" -version = "1.0.1" +version = "1.1.0a1" source = { editable = "." } dependencies = [ { name = "bed-reader", extra = ["samples"] }, @@ -2456,6 +2499,7 @@ dependencies = [ { name = "psutil" }, { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, { name = "scipy", version = "1.18.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, + { name = "threadpoolctl" }, ] [package.optional-dependencies] @@ -2463,6 +2507,9 @@ bgen = [ { name = "bgen-reader" }, { name = "cbgen" }, ] +cupy = [ + { name = "bed-reader", extra = ["cupy"] }, +] dev = [ { name = "limix-sphinx-theme" }, { name = "pytest" }, @@ -2495,7 +2542,8 @@ notebook = [ [package.metadata] requires-dist = [ - { name = "bed-reader", extras = ["samples"], specifier = ">=1.2.0" }, + { name = "bed-reader", extras = ["cupy"], marker = "extra == 'cupy'", specifier = ">=1.3.0a1" }, + { name = "bed-reader", extras = ["samples"], specifier = ">=1.3.0a1" }, { name = "bgen-reader", marker = "extra == 'bgen'", specifier = ">=4.0.9" }, { name = "cbgen", marker = "extra == 'bgen'", specifier = ">=1.0.6" }, { name = "cloudpickle", specifier = ">=3.1.0" }, @@ -2526,8 +2574,10 @@ requires-dist = [ { name = "scipy", marker = "python_full_version >= '3.15'", specifier = ">=1.18.1" }, { name = "sphinx", marker = "extra == 'dev'", specifier = ">=6.2.1" }, { name = "sphinx-rtd-theme", marker = "extra == 'dev'", specifier = ">=3.0.1" }, + { name = "threadpoolctl", marker = "python_full_version < '3.15'", specifier = ">=3.5.0" }, + { name = "threadpoolctl", marker = "python_full_version >= '3.15'", specifier = ">=3.8.0" }, ] -provides-extras = ["hdf5", "bgen", "dev"] +provides-extras = ["cupy", "hdf5", "bgen", "dev"] [package.metadata.requires-dev] dev = [ @@ -3420,6 +3470,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/9e/16/428cc7df8670f407c7810882cf736dbc04163ec60589f3bd8ebb6a2c263a/texttable-1.7.3-py2.py3-none-any.whl", hash = "sha256:b8eaebd6d32565ce85b79b17e2aa52815889249b37bb6dd0894d3eca67c329f8", size = 10876, upload-time = "2026-11-12T18:52:50.483Z" }, ] +[[package]] +name = "threadpoolctl" +version = "3.8.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/56/97/b4748951a683e369513691c8eea33d100298d556308dcb0ab66b132a67f0/threadpoolctl-3.8.0.tar.gz", hash = "sha256:01080674ad7ac6182429c918a79de92da789bb448acc02fc0b620b1abd6b6137", size = 39424, upload-time = "2026-11-05T11:08:51.112Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/54/1b/831f2de4840a25db1dd7b1afea433ccafe6bb10aca07e13264f2079462d0/threadpoolctl-3.8.0-py3-none-any.whl", hash = "sha256:f1b49c82704d50f13ffae019c727b0fa4f6791a58f48f06a09c45face1be66da", size = 32091, upload-time = "2026-11-05T11:08:49.773Z" }, +] + [[package]] name = "tinycss2" version = "1.5.1"