From 9882129fe239e278b21c46135987d204c29ba0b4 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 06:57:13 -0800 Subject: [PATCH 01/21] Let sub_matrix subset cupy arrays and keep float32 when moving data to cupy --- pysnptools/pstreader/pstdata.py | 7 +++- pysnptools/util/__init__.py | 35 ++++++++++++++++++++ pysnptools/util/test.py | 58 +++++++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 1 deletion(-) diff --git a/pysnptools/pstreader/pstdata.py b/pysnptools/pstreader/pstdata.py index 67406c8..e9ce9c5 100644 --- a/pysnptools/pstreader/pstdata.py +++ b/pysnptools/pstreader/pstdata.py @@ -185,7 +185,12 @@ def _fixup_input_val( ), "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) + # When moving a numpy ndarray to another array module (e.g. cupy), + # keep float32 rather than silently upcasting it to float64. + if isinstance(input, np.ndarray) and input.dtype == np.float32: + input = xp.array(input, dtype=xp.float32) + else: + 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) diff --git a/pysnptools/util/__init__.py b/pysnptools/util/__init__.py index b1ba892..c8f2824 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -322,6 +322,11 @@ def sub_matrix( effective_order = order dtype = np.dtype(dtype) + if not isinstance(val, np.ndarray): + return _sub_matrix_cupy( + val, row_index_list, col_index_list, effective_order, dtype + ) + original_dimensions = len(val.shape) if original_dimensions == 2: iid_count, sid_count = val.shape @@ -395,6 +400,36 @@ def create_sub_val(dtype): return sub_val +def _sub_matrix_cupy(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. + # Validation mirrors the numpy path so both array modules fail the same way. + import cupy as cp # type: ignore + + if not isinstance(val, cp.ndarray): + raise TypeError( + "Expect val to be a numpy or cupy ndarray, not '{0}'".format(type(val)) + ) + 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") + + # uintp (like the Rust path) rejects negative indexes; cupy indexing wants intp. + row_index = cp.asarray(np.asarray(row_index_list, dtype=np.uintp).astype(np.intp)) + col_index = cp.asarray(np.asarray(col_index_list, dtype=np.uintp).astype(np.intp)) + sub_val = val[cp.ix_(row_index, col_index)] + return cp.array(sub_val, dtype=dtype, order=effective_order) + + def create_directory_if_necessary(name, isfile=True, robust=False): """ Create a directory for a file if the directory doesn't already exist. diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index 0a3e630..b52c536 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -120,6 +120,64 @@ 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_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 + 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]: + with warnings.catch_warnings(): + warnings.simplefilter("ignore", UserWarning) + expected = pstutil.sub_matrix(matrix, row_index_list, col_index_list, order=out_order, dtype=out_dtype) + actual = pstutil.sub_matrix(cp.asarray(matrix, order=in_order), row_index_list, col_index_list, order=out_order, dtype=out_dtype) + 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) + + 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() + np.testing.assert_array_equal(cp.asnumpy(subset.val), val[[0, 2, 3, 5]][:, [3, 1]]) + + def test_snpdata_cupy_keeps_float32(self): + # A numpy float32 val moved to cupy must stay float32 (not be upcast to float64). + 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"] + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + for in_dtype, out_dtype in [(np.float32, np.float32), (np.float64, np.float64), (np.int8, np.float64)]: + snpdata = SnpData(iid=iid, sid=sid, val=np.ones((3, 2), dtype=in_dtype)) + assert isinstance(snpdata.val, cp.ndarray) + assert snpdata.val.dtype == out_dtype, (in_dtype, snpdata.val.dtype) + def getTestSuite(): From 1988d199ba66bf0e29959407fd53cf159bb97d2e Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 07:05:08 -0800 Subject: [PATCH 02/21] Detect cupy arrays directly in sub_matrix and reject out-of-range cupy indexes --- pysnptools/util/__init__.py | 30 +++++++++++++++++++++--------- pysnptools/util/test.py | 5 +++++ 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/pysnptools/util/__init__.py b/pysnptools/util/__init__.py index c8f2824..d895ad3 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -322,7 +322,10 @@ def sub_matrix( effective_order = order dtype = np.dtype(dtype) - if not isinstance(val, np.ndarray): + # 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( val, row_index_list, col_index_list, effective_order, dtype ) @@ -406,10 +409,6 @@ def _sub_matrix_cupy(val, row_index_list, col_index_list, effective_order, dtype # Validation mirrors the numpy path so both array modules fail the same way. import cupy as cp # type: ignore - if not isinstance(val, cp.ndarray): - raise TypeError( - "Expect val to be a numpy or cupy ndarray, not '{0}'".format(type(val)) - ) 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): @@ -423,13 +422,26 @@ def _sub_matrix_cupy(val, row_index_list, col_index_list, effective_order, dtype if val.dtype == np.float64 and dtype == np.float32: warnings.warn("Converting float64 to float32 can cause loss of information") - # uintp (like the Rust path) rejects negative indexes; cupy indexing wants intp. - row_index = cp.asarray(np.asarray(row_index_list, dtype=np.uintp).astype(np.intp)) - col_index = cp.asarray(np.asarray(col_index_list, dtype=np.uintp).astype(np.intp)) - sub_val = val[cp.ix_(row_index, col_index)] + row_index = _checked_index(row_index_list, val.shape[0], "row") + col_index = _checked_index(col_index_list, val.shape[1], "column") + sub_val = val[cp.ix_(cp.asarray(row_index), cp.asarray(col_index))] return cp.array(sub_val, dtype=dtype, order=effective_order) +def _checked_index(index_list, count, name): + # cupy indexing silently wraps negative and out-of-range indexes, so check them on + # the host first. (The Rust path rejects them too, though with a less clear error.) + index = np.asarray(index_list, dtype=np.intp) + 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 + + def create_directory_if_necessary(name, isfile=True, robust=False): """ Create a directory for a file if the directory doesn't already exist. diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index b52c536..52e3050 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -146,6 +146,11 @@ def test_sub_matrix_cupy(self): 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. From 4d3cbe13df1e0d9e18724d5786ce6f83f2243b56 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 07:07:50 -0800 Subject: [PATCH 03/21] Pass the cupy module to _sub_matrix_cupy instead of importing it again --- pysnptools/util/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pysnptools/util/__init__.py b/pysnptools/util/__init__.py index d895ad3..127fc24 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -327,7 +327,7 @@ def sub_matrix( cp = sys.modules.get("cupy") if cp is not None and isinstance(val, cp.ndarray): return _sub_matrix_cupy( - val, row_index_list, col_index_list, effective_order, dtype + cp, val, row_index_list, col_index_list, effective_order, dtype ) original_dimensions = len(val.shape) @@ -403,11 +403,11 @@ def create_sub_val(dtype): return sub_val -def _sub_matrix_cupy(val, row_index_list, col_index_list, effective_order, dtype): +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. - import cupy as cp # type: ignore if len(val.shape) not in {2, 3}: raise ValueError("Expect val dimensions of 2 or 3") From 2f6503407324f7281f5942078bb4b507d7dcca40 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 09:04:23 -0800 Subject: [PATCH 04/21] Avoid a second GPU copy in _sub_matrix_cupy --- pysnptools/util/__init__.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pysnptools/util/__init__.py b/pysnptools/util/__init__.py index 127fc24..07d6ddd 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -425,7 +425,8 @@ def _sub_matrix_cupy(cp, val, row_index_list, col_index_list, effective_order, d row_index = _checked_index(row_index_list, val.shape[0], "row") col_index = _checked_index(col_index_list, val.shape[1], "column") sub_val = val[cp.ix_(cp.asarray(row_index), cp.asarray(col_index))] - return cp.array(sub_val, dtype=dtype, order=effective_order) + # 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): From 5a45e810a16a576a3f499586d2939a59a024d301 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 09:10:50 -0800 Subject: [PATCH 05/21] Keep dtype when moving PstData val between numpy and cupy, in both directions --- pysnptools/pstreader/pstdata.py | 21 ++++++++++++++++----- pysnptools/util/test.py | 28 +++++++++++++++++++++------- 2 files changed, 37 insertions(+), 12 deletions(-) diff --git a/pysnptools/pstreader/pstdata.py b/pysnptools/pstreader/pstdata.py index e9ce9c5..fe724cb 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 @@ -185,12 +186,22 @@ def _fixup_input_val( ), "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): - # When moving a numpy ndarray to another array module (e.g. cupy), - # keep float32 rather than silently upcasting it to float64. - if isinstance(input, np.ndarray) and input.dtype == np.float32: - input = xp.array(input, dtype=xp.float32) + # An ndarray from another array module (numpy <-> cupy) keeps the dtype that + # same-module input keeps (below): float32 or float64, or any dtype when + # _require_float32_64 is False. Anything else (for example, a list) becomes float64. + cp = sys.modules.get("cupy") + is_ndarray = isinstance(input, np.ndarray) or ( + cp is not None and isinstance(input, cp.ndarray) + ) + if is_ndarray and ( + not _require_float32_64 or input.dtype in (np.float32, np.float64) + ): + dtype = input.dtype else: - input = xp.array(input, dtype=xp.float64) + dtype = np.float64 + if is_ndarray and xp is np: + input = pstutil.asnumpy(input) # cupy forbids implicit conversion to numpy + input = xp.array(input, dtype=dtype) elif _require_float32_64 and input.dtype not in [xp.float32, xp.float64]: input = xp.array(input, dtype=xp.float64) diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index 52e3050..74337d5 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -167,8 +167,8 @@ def test_snpdata_subset_cupy(self): subset = snpdata[np.array([True, False, True, True, False, True]), [3, 1]].read() np.testing.assert_array_equal(cp.asnumpy(subset.val), val[[0, 2, 3, 5]][:, [3, 1]]) - def test_snpdata_cupy_keeps_float32(self): - # A numpy float32 val moved to cupy must stay float32 (not be upcast to float64). + 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: @@ -177,11 +177,25 @@ def test_snpdata_cupy_keeps_float32(self): from pysnptools.snpreader import SnpData iid = [["f", str(i)] for i in range(3)] sid = ["s0", "s1"] - with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): - for in_dtype, out_dtype in [(np.float32, np.float32), (np.float64, np.float64), (np.int8, np.float64)]: - snpdata = SnpData(iid=iid, sid=sid, val=np.ones((3, 2), dtype=in_dtype)) - assert isinstance(snpdata.val, cp.ndarray) - assert snpdata.val.dtype == out_dtype, (in_dtype, snpdata.val.dtype) + 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 From 2640a5eebb2cfdb1d604c5b4388dd4e0afac66ad Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 09:16:47 -0800 Subject: [PATCH 06/21] Match the Rust standardizer on cupy: raise for an all-missing SNP, and make Beta work --- pysnptools/standardizer/standardizer.py | 14 +++++++++++++- pysnptools/util/test.py | 25 +++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/pysnptools/standardizer/standardizer.py b/pysnptools/standardizer/standardizer.py index 73e2804..df243c8 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. @@ -221,6 +229,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 @@ -257,6 +266,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 +275,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 +292,8 @@ 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)) # print("BetaPdf[{0},{1},{2}]={3}".format(maf,betaA,betaB,maf_beta)) snps -= snp_mean snps *= maf_beta diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index 74337d5..fdc4149 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -198,6 +198,31 @@ def test_snpdata_cupy_keeps_dtype(self): 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(): """ From 481bde4ac3c23132073644ae2a4d1007829e1592 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 13:53:50 -0800 Subject: [PATCH 07/21] Restructure PstData val conversion into one helper with a case per input kind --- pysnptools/pstreader/pstdata.py | 42 ++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/pysnptools/pstreader/pstdata.py b/pysnptools/pstreader/pstdata.py index fe724cb..d5746b9 100644 --- a/pysnptools/pstreader/pstdata.py +++ b/pysnptools/pstreader/pstdata.py @@ -15,6 +15,27 @@ 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): + # 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, and for anything else (for example, a list), it becomes 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 xp.array(input, dtype=xp.float64) + + 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 np.float64 + if xp is np: + input = pstutil.asnumpy(input) # cupy forbids implicit conversion to numpy + return xp.array(input, dtype=dtype) # other module (always copies) + + return xp.array(input, dtype=np.float64) # not an array + + 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. @@ -185,25 +206,8 @@ def _fixup_input_val( 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): - # An ndarray from another array module (numpy <-> cupy) keeps the dtype that - # same-module input keeps (below): float32 or float64, or any dtype when - # _require_float32_64 is False. Anything else (for example, a list) becomes float64. - cp = sys.modules.get("cupy") - is_ndarray = isinstance(input, np.ndarray) or ( - cp is not None and isinstance(input, cp.ndarray) - ) - if is_ndarray and ( - not _require_float32_64 or input.dtype in (np.float32, np.float64) - ): - dtype = input.dtype - else: - dtype = np.float64 - if is_ndarray and xp is np: - input = pstutil.asnumpy(input) # cupy forbids implicit conversion to numpy - input = xp.array(input, dtype=dtype) - elif _require_float32_64 and input.dtype not in [xp.float32, xp.float64]: - input = xp.array(input, dtype=xp.float64) + 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 ( From d06c81b4474fe9cd6ab2cbd54d9b638e20bc8633 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 14:14:06 -0800 Subject: [PATCH 08/21] Require sub_matrix's precision warning on both paths in test_sub_matrix_cupy --- pysnptools/util/test.py | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index fdc4149..cc59023 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -128,6 +128,13 @@ def test_sub_matrix_cupy(self): 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, [str(warning.message) for warning in caught] + rng = np.random.default_rng(0) row_index_list = [0, 2, 11, 2] col_index_list = [6, 5, 4, 3, 2, 1, 0] @@ -137,10 +144,13 @@ def test_sub_matrix_cupy(self): 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]: - with warnings.catch_warnings(): - warnings.simplefilter("ignore", UserWarning) - expected = pstutil.sub_matrix(matrix, row_index_list, col_index_list, order=out_order, dtype=out_dtype) - actual = pstutil.sub_matrix(cp.asarray(matrix, order=in_order), row_index_list, col_index_list, order=out_order, dtype=out_dtype) + 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 warn exactly when narrowing float64 to float32, and otherwise not at all. + narrowing = in_dtype == np.float64 and out_dtype == np.float32 + precision_warning = ["Converting float64 to float32 can cause loss of information"] + assert expected_warnings == (precision_warning if narrowing else []), expected_warnings + assert actual_warnings == expected_warnings, actual_warnings assert isinstance(actual, cp.ndarray) assert actual.dtype == expected.dtype assert actual.flags["F_CONTIGUOUS"] == expected.flags["F_CONTIGUOUS"] From d647dbcc7f50360e8d5f766e4effeeb90c525c99 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Sun, 15 Nov 2026 14:24:35 -0800 Subject: [PATCH 09/21] Check that a cupy SnpData subset stays on the GPU with its dtype --- pysnptools/util/test.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index cc59023..3dbb7ab 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -175,6 +175,8 @@ def test_snpdata_subset_cupy(self): 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): From 89d259bb248bdb547a37884d887e60e476d2f839 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Mon, 16 Nov 2026 15:22:26 -0800 Subject: [PATCH 10/21] Document GPU arrays and preview explicit reader backend APIs --- CHANGELOG.md | 8 ++ README.md | 10 ++ doc/source/gpu-api-preview.rst | 93 +++++++++++++++++ doc/source/gpu.rst | 144 ++++++++++++++++++++++++++ doc/source/index.rst | 6 ++ pysnptools/kernelreader/kerneldata.py | 4 +- pysnptools/snpreader/snpdata.py | 7 +- pysnptools/util/__init__.py | 10 +- 8 files changed, 276 insertions(+), 6 deletions(-) create mode 100644 doc/source/gpu-api-preview.rst create mode 100644 doc/source/gpu.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index e258135..bee98be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +* 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..ef1a80f 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,16 @@ Existing HDF5 users upgrading from an earlier release should install this extra. pip install pysnptools[bgen] +GPU arrays (development branch) +=============================== + +`SnpData` and `KernelData` support NumPy/CuPy values, with float32/float64 +preserved during device transfers. CuPy subsetting stays on the GPU, and Unit +and Beta standardization work on CuPy arrays. See the [GPU guide](doc/source/gpu.rst) +for complete examples, backend selection, dtype rules, and current reader +limitations. The [API preview](doc/source/gpu-api-preview.rst) covers the +concurrent explicit reader API and native GPU BED changes. These branch features are not necessarily in the published package. + Documentation ------------- diff --git a/doc/source/gpu-api-preview.rst b/doc/source/gpu-api-preview.rst new file mode 100644 index 0000000..2c2faa5 --- /dev/null +++ b/doc/source/gpu-api-preview.rst @@ -0,0 +1,93 @@ +Explicit GPU reader API preview +=============================== + +This page describes the coordinated GPU API changes currently being developed +alongside this documentation. They are present in the original development +checkout but are not part of this documentation branch's committed code base. +Use :doc:`gpu` for the committed API. Installing the published package is not +sufficient to run this preview; the matching PySnpTools and GPU-enabled +bed-reader implementations are required. + +Select the device at each read +------------------------------ + +``SnpReader.read``, ``SnpReader.read_kernel``, and ``KernelReader.read`` gain an +``xp`` argument accepting NumPy/CuPy modules or their names. An explicit value +overrides ``ARRAY_MODULE``. Otherwise the environment selects the module, with +NumPy as the final default. Specify both ``xp`` and ``dtype`` at read boundaries +so the result does not depend on a surrounding workflow's environment. + +This complete in-memory example uses no files. It checks explicit backend +selection against an opposing environment, selects a subset on the GPU, and +standardizes on the array's existing device:: + + import cupy as cp + import numpy as np + from unittest.mock import patch + from pysnptools.snpreader import SnpData + from pysnptools.standardizer import Unit + + assert cp.cuda.runtime.getDeviceCount() > 0 + 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, xp=np) + with patch.dict("os.environ", {"ARRAY_MODULE": "numpy"}): + gpu = data.read(dtype="float32", xp=cp) + subset = gpu[[2, 0], :].read(dtype="float32", xp=cp) + subset.standardize(Unit()) + assert isinstance(subset.val, cp.ndarray) and subset.val.dtype == np.float32 + np.testing.assert_allclose(cp.asnumpy(subset.val), [[1, -1], [-1, 1]], + rtol=1e-6, atol=1e-6) + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + host = gpu.read(dtype="float32", xp=np) + host.standardize(Unit()) + assert isinstance(host.val, np.ndarray) + +The standardization change is significant: an existing array determines the +device, regardless of ``ARRAY_MODULE``. It resolves the Unit device mismatch +described in the committed guide. Subsetting still needs a read to materialize +values, and that read has its own device and dtype choice. A default float64 +read does not preserve float32 merely because the input is float32. + +Read BED data and form a kernel +------------------------------- + +With the matching CUDA-enabled bed-reader build and CuPy, BED reads request +GPU decoding directly. Kernel construction can read and standardize BED blocks +on the GPU before CuPy multiplication. A separate public ``read().standardize()`` +sequence remains supported; callers do not need private fused-read methods. +For an existing BED dataset with accompanying BIM/FAM files:: + + from pysnptools.snpreader import Bed + from pysnptools.kernelreader import SnpKernel + + bed = Bed("cohort.bed", count_A1=True) + block = bed[:100, :200].read(dtype="float32", xp=cp) + block.standardize(Unit()) + kernel = bed.read_kernel(Unit(), block_size=7, dtype="float32", xp=cp) + kernel_again = SnpKernel(bed, Unit(), block_size=7).read( + dtype="float32", xp=cp + ) + assert isinstance(kernel.val, cp.ndarray) and kernel.val.dtype == np.float32 + np.testing.assert_allclose(cp.asnumpy(kernel.val), cp.asnumpy(kernel_again.val), + rtol=1e-5, atol=1e-5) + +The requested SNP block size is respected even when there are fewer SNPs than +samples, unlike the shortcut described in the committed guide. It limits the +SNP blocks, not the dense kernel, eigensolver workspace, or allocator pools. +Only BED decoding is native GPU I/O here; other formats can read on the CPU and +transfer values to the selected device. + +CuPy Unit/Beta standardization also supports general floating-point arrays, +including dosages, with per-SNP workspaces. Missing values become zero after +standardization; fitting a wholly missing SNP raises. Applying trained +statistics preserves the training SNP order and constant-column behavior. +The new CuPy Beta path evaluates its weights on the GPU, replacing the committed +implementation's SciPy round trip. Float32 reductions and general floating-point +statistics need not be bit-identical to CPU results. + +A BED GPU request without a GPU-enabled native build raises instead of quietly +reading the BED values on the CPU. This differs from the committed FaST-LMM +native-reader fallback. Module-name resolution can still fall back to NumPy +when importing CuPy fails; import CuPy explicitly and pass the module when +checking GPU execution. Driver errors and insufficient memory remain errors. diff --git a/doc/source/gpu.rst b/doc/source/gpu.rst new file mode 100644 index 0000000..c447832 --- /dev/null +++ b/doc/source/gpu.rst @@ -0,0 +1,144 @@ +GPU arrays, subsetting, and standardization +=========================================== + +The GPU changes described here are under development on this branch. They are +not a promise that the latest published PySnpTools contains these changes. +CuPy is optional and must be installed separately for your GPU platform. +For the concurrent explicit reader API and native GPU BED path, see +:doc:`gpu-api-preview`. + +Construct arrays and select a backend +------------------------------------- + +``SnpData`` and ``KernelData`` accept ``xp`` as a module or module name. +An explicit choice overrides ``ARRAY_MODULE``; without either, NumPy is used. +The numerical values live in the selected module; IDs and position metadata +remain NumPy arrays on the CPU. Moving an existing float32 or float64 array +between NumPy and CuPy preserves its dtype. Lists and integer arrays normally +become float64. A same-module floating-point input can share storage, so copy it +first when later in-place changes must not affect the caller. + +This complete example needs CuPy and a working GPU, but no BED file or native +GPU bed-reader build:: + + import cupy as cp + import numpy as np + from pysnptools.snpreader import SnpData + from pysnptools.util import asnumpy + + assert cp.cuda.runtime.getDeviceCount() > 0 + 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, xp=cp + ) + assert isinstance(data.val, cp.ndarray) and data.val.dtype == np.float32 + host = SnpData(iid=data.iid, sid=data.sid, pos=data.pos, + val=data.val, xp=np) + np.testing.assert_array_equal(host.val, values) + assert host.val.dtype == np.float32 + np.testing.assert_array_equal(asnumpy(data.val), values) + +``asnumpy`` transfers a CuPy array to the CPU and returns a NumPy array unchanged. +``array_module("cupy")`` can log a warning and select NumPy if the CuPy import +fails. Importing CuPy explicitly, as above, avoids accidentally mistaking this +fallback for a successful GPU run. Driver/runtime failures are separate errors. + +Subset without moving values to the CPU +--------------------------------------- + +``sub_matrix`` dispatches from the actual input array, independently of +``ARRAY_MODULE``. It supports contiguous float32/float64 arrays with two or three +dimensions and keeps the result on the input device. Row and column lists select +a Cartesian product, preserving order and duplicates. On the CuPy path, negative +or out-of-range indices raise ``IndexError`` instead of CuPy's wrapping behavior:: + + from pysnptools.util import sub_matrix + + selected = sub_matrix(data.val, [2, 0, 2], [1, 0], + dtype=data.val.dtype, order="F") + assert isinstance(selected, cp.ndarray) + assert selected.dtype == np.float32 and selected.flags.f_contiguous + np.testing.assert_array_equal(cp.asnumpy(selected), values[[2, 0, 2]][:, [1, 0]]) + +The default result dtype is float64; pass ``dtype`` explicitly to keep float32. +Narrowing float64 to float32 emits a precision warning. These low-level index +rules differ from reader slicing, which accepts slices and Boolean masks. + +On this committed branch, reader ``read`` methods do not yet accept ``xp``. +They consult ``ARRAY_MODULE`` when constructing the returned data object, even +if the original object was constructed with an explicit ``xp``. To keep an +in-memory subset on the GPU, set the environment for the read and request the +dtype explicitly. The context below restores the prior environment:: + + from unittest.mock import patch + + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + subset = data[[2, 0], :].read(dtype="float32") + assert isinstance(subset.val, cp.ndarray) and subset.val.dtype == np.float32 + np.testing.assert_array_equal(cp.asnumpy(subset.val), values[[2, 0]]) + +``ARRAY_MODULE`` is process-wide. Avoid changing it concurrently with other +workflows. An in-memory CuPy array does not imply that all readers, writers, or +utility functions accept CuPy inputs. + +Standardize and reuse training statistics +----------------------------------------- + +``Unit`` and ``Beta`` standardize numerical values in place. On this branch, +keep ``ARRAY_MODULE`` consistent with the data device when calling Unit: it +consults the environment and can fail when asked to convert CuPy values to +NumPy implicitly. Unit centers each SNP and divides by its observed standard deviation; +missing values become zero. A SNP with no observations raises ``ValueError``. +A constant training SNP has an infinite stored standard deviation so a trained +standardizer zeros that SNP in later data too. Beta centers and weights SNPs +using the beta density at the minor allele frequency; it is not Unit scaling. +Its SciPy beta-density calculation transfers per-SNP values through the CPU. + +Using the ``data`` from the first example:: + + from pysnptools.standardizer import Unit, Beta + + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + standardized, trained = data.standardize(Unit(), return_trained=True) + assert standardized is data + assert isinstance(data.val, cp.ndarray) and data.val.dtype == np.float32 + fresh = SnpData(iid=data.iid, sid=data.sid, + val=cp.asarray(values), xp=cp) + fresh.standardize(trained) + np.testing.assert_allclose(cp.asnumpy(fresh.val), cp.asnumpy(data.val), + rtol=1e-6, atol=1e-6) + weighted = SnpData(iid=data.iid, sid=data.sid, + val=cp.asarray(values), xp=cp).standardize(Beta(1, 25)) + assert isinstance(weighted.val, cp.ndarray) + +The tolerance here is for this small, well-scaled float32 example, not a general +numerical guarantee. Applying trained statistics requires matching SNP IDs and +order; reuse statistics fitted on training data when transforming test data. +The training call has already changed ``data.val`` in place. + +Read files and construct a kernel +--------------------------------- + +On this branch, selecting CuPy for a PySnpTools BED read transfers values after +the existing file read; it does not itself request native GPU BED decoding. +FaST-LMM's GPU BED integration is a separate path. For an existing BED dataset:: + + from pysnptools.snpreader import Bed + + with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): + bed = Bed("cohort.bed", count_A1=True) + block = bed[:100, :200].read(dtype="float32").standardize(Unit()) + kernel = bed.read_kernel(Unit(), block_size=1000, dtype="float32") + assert isinstance(block.val, cp.ndarray) + assert isinstance(kernel.val, cp.ndarray) + +The BED file must have accompanying BIM and FAM files. Keep ``count_A1`` explicit. +``read_kernel(Unit())`` forms the product of standardized SNPs and their +transpose; use kernel standardization separately if a unit average diagonal is +needed. ``block_size`` is a suggested SNP block size and does not cap total GPU +memory. The result is still a dense samples-by-samples matrix. In the committed +implementation, the small-SNP/low-rank path can read all SNPs despite a requested +block size, and kernel accumulation can use float64 before the requested output +cast. Do not infer an all-float32 computation or a memory guarantee from the +returned dtype. diff --git a/doc/source/index.rst b/doc/source/index.rst index 598dd40..0478930 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -52,6 +52,12 @@ covered by the Python 3.11 through 3.14 test matrix. * `General Notebook `_ * `Distribution Notebook `_ +.. toctree:: + :maxdepth: 2 + + gpu + gpu-api-preview + :Code: * `PyPi `_ diff --git a/pysnptools/kernelreader/kerneldata.py b/pysnptools/kernelreader/kerneldata.py index 523cc8c..fdc7d61 100644 --- a/pysnptools/kernelreader/kerneldata.py +++ b/pysnptools/kernelreader/kerneldata.py @@ -14,7 +14,9 @@ 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. **Constructor:** :Parameters: * **iid** (an array of string pairs) -- The :attr:`KernelReader.iid` information. diff --git a/pysnptools/snpreader/snpdata.py b/pysnptools/snpreader/snpdata.py index 871785c..9cb36cb 100644 --- a/pysnptools/snpreader/snpdata.py +++ b/pysnptools/snpreader/snpdata.py @@ -14,7 +14,10 @@ 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 normally become float64. **Constructor:** :Parameters: * **iid** (an array of string pair) -- The :attr:`SnpReader.iid` information. @@ -111,7 +114,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 diff --git a/pysnptools/util/__init__.py b/pysnptools/util/__init__.py index 07d6ddd..6c5bd98 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -287,8 +287,8 @@ 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 :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for sub-matrix created. @@ -310,7 +310,11 @@ def sub_matrix( >>> 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. + NumPy inputs use a Rust helper; CuPy inputs use CuPy indexing and stay on + the GPU. CuPy row/column indices must be nonnegative and in range. Both paths + require contiguous float32/float64 inputs, preserve duplicate indices, and + warn when converting float64 to float32. Pass ``dtype=val.dtype`` to preserve + float32; the default output dtype is float64. See :doc:`/gpu` for GPU examples. """ if order == "A": From 366d6bb51c21f6ee4cc3024d74b40b625ae35b30 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Mon, 16 Nov 2026 19:05:14 -0800 Subject: [PATCH 11/21] Add explicit reader backends and fix GPU standardization Route GPU BED reads and blocked kernels through bed-reader while keeping existing arrays on their device. Preserve Unit/Beta missing-value and constant-column behavior, reuse fitted Beta moments in blocked kernels, and validate sub_matrix indices before conversion. Add CPU/GPU regressions and update the Python API documentation. --- CHANGELOG.md | 11 + README.md | 14 +- doc/source/gpu-api-preview.rst | 98 +----- doc/source/gpu.rst | 382 +++++++++++++++------ doc/source/index.rst | 8 + pysnptools/kernelreader/_subset.py | 10 + pysnptools/kernelreader/kerneldata.py | 19 +- pysnptools/kernelreader/kernelreader.py | 52 ++- pysnptools/kernelreader/snpkernel.py | 87 ++--- pysnptools/snpreader/_subset.py | 25 ++ pysnptools/snpreader/bed.py | 52 ++- pysnptools/snpreader/snpdata.py | 30 +- pysnptools/snpreader/snpreader.py | 188 +++++++--- pysnptools/standardizer/_cupy.py | 23 ++ pysnptools/standardizer/beta.py | 17 +- pysnptools/standardizer/betatrained.py | 14 +- pysnptools/standardizer/diag_K_to_N.py | 14 +- pysnptools/standardizer/standardizer.py | 88 ++++- pysnptools/standardizer/unit.py | 19 +- pysnptools/standardizer/unittrained.py | 13 +- pysnptools/test.py | 150 ++++++++ pysnptools/test_gpu_api.py | 149 ++++++++ pysnptools/test_gpu_standardize_general.py | 120 +++++++ pysnptools/util/__init__.py | 77 +++-- pysnptools/util/test.py | 57 +++ 25 files changed, 1331 insertions(+), 386 deletions(-) create mode 100644 pysnptools/standardizer/_cupy.py create mode 100644 pysnptools/test_gpu_api.py create mode 100644 pysnptools/test_gpu_standardize_general.py diff --git a/CHANGELOG.md b/CHANGELOG.md index bee98be..d352eed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +* 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 diff --git a/README.md b/README.md index ef1a80f..e123ba0 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,12 @@ Existing HDF5 users upgrading from an earlier release should install this extra. pip install pysnptools[bgen] GPU arrays (development branch) -=============================== - -`SnpData` and `KernelData` support NumPy/CuPy values, with float32/float64 -preserved during device transfers. CuPy subsetting stays on the GPU, and Unit -and Beta standardization work on CuPy arrays. See the [GPU guide](doc/source/gpu.rst) -for complete examples, backend selection, dtype rules, and current reader -limitations. The [API preview](doc/source/gpu-api-preview.rst) covers the -concurrent explicit reader API and native GPU BED changes. These branch features are not necessarily in the published package. +------------------------------- + +Readers accept explicit NumPy/CuPy backends; standardization follows the array's +device. GPU BED reads require a CUDA-enabled bed-reader build. See the +[GPU guide](doc/source/gpu.rst) for prerequisites, options, and complete examples. +These development features are not necessarily in the published packages. Documentation ------------- diff --git a/doc/source/gpu-api-preview.rst b/doc/source/gpu-api-preview.rst index 2c2faa5..63806c2 100644 --- a/doc/source/gpu-api-preview.rst +++ b/doc/source/gpu-api-preview.rst @@ -1,93 +1,7 @@ -Explicit GPU reader API preview -=============================== +GPU reader API +============== -This page describes the coordinated GPU API changes currently being developed -alongside this documentation. They are present in the original development -checkout but are not part of this documentation branch's committed code base. -Use :doc:`gpu` for the committed API. Installing the published package is not -sufficient to run this preview; the matching PySnpTools and GPU-enabled -bed-reader implementations are required. - -Select the device at each read ------------------------------- - -``SnpReader.read``, ``SnpReader.read_kernel``, and ``KernelReader.read`` gain an -``xp`` argument accepting NumPy/CuPy modules or their names. An explicit value -overrides ``ARRAY_MODULE``. Otherwise the environment selects the module, with -NumPy as the final default. Specify both ``xp`` and ``dtype`` at read boundaries -so the result does not depend on a surrounding workflow's environment. - -This complete in-memory example uses no files. It checks explicit backend -selection against an opposing environment, selects a subset on the GPU, and -standardizes on the array's existing device:: - - import cupy as cp - import numpy as np - from unittest.mock import patch - from pysnptools.snpreader import SnpData - from pysnptools.standardizer import Unit - - assert cp.cuda.runtime.getDeviceCount() > 0 - 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, xp=np) - with patch.dict("os.environ", {"ARRAY_MODULE": "numpy"}): - gpu = data.read(dtype="float32", xp=cp) - subset = gpu[[2, 0], :].read(dtype="float32", xp=cp) - subset.standardize(Unit()) - assert isinstance(subset.val, cp.ndarray) and subset.val.dtype == np.float32 - np.testing.assert_allclose(cp.asnumpy(subset.val), [[1, -1], [-1, 1]], - rtol=1e-6, atol=1e-6) - with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): - host = gpu.read(dtype="float32", xp=np) - host.standardize(Unit()) - assert isinstance(host.val, np.ndarray) - -The standardization change is significant: an existing array determines the -device, regardless of ``ARRAY_MODULE``. It resolves the Unit device mismatch -described in the committed guide. Subsetting still needs a read to materialize -values, and that read has its own device and dtype choice. A default float64 -read does not preserve float32 merely because the input is float32. - -Read BED data and form a kernel -------------------------------- - -With the matching CUDA-enabled bed-reader build and CuPy, BED reads request -GPU decoding directly. Kernel construction can read and standardize BED blocks -on the GPU before CuPy multiplication. A separate public ``read().standardize()`` -sequence remains supported; callers do not need private fused-read methods. -For an existing BED dataset with accompanying BIM/FAM files:: - - from pysnptools.snpreader import Bed - from pysnptools.kernelreader import SnpKernel - - bed = Bed("cohort.bed", count_A1=True) - block = bed[:100, :200].read(dtype="float32", xp=cp) - block.standardize(Unit()) - kernel = bed.read_kernel(Unit(), block_size=7, dtype="float32", xp=cp) - kernel_again = SnpKernel(bed, Unit(), block_size=7).read( - dtype="float32", xp=cp - ) - assert isinstance(kernel.val, cp.ndarray) and kernel.val.dtype == np.float32 - np.testing.assert_allclose(cp.asnumpy(kernel.val), cp.asnumpy(kernel_again.val), - rtol=1e-5, atol=1e-5) - -The requested SNP block size is respected even when there are fewer SNPs than -samples, unlike the shortcut described in the committed guide. It limits the -SNP blocks, not the dense kernel, eigensolver workspace, or allocator pools. -Only BED decoding is native GPU I/O here; other formats can read on the CPU and -transfer values to the selected device. - -CuPy Unit/Beta standardization also supports general floating-point arrays, -including dosages, with per-SNP workspaces. Missing values become zero after -standardization; fitting a wholly missing SNP raises. Applying trained -statistics preserves the training SNP order and constant-column behavior. -The new CuPy Beta path evaluates its weights on the GPU, replacing the committed -implementation's SciPy round trip. Float32 reductions and general floating-point -statistics need not be bit-identical to CPU results. - -A BED GPU request without a GPU-enabled native build raises instead of quietly -reading the BED values on the CPU. This differs from the committed FaST-LMM -native-reader fallback. Module-name resolution can still fall back to NumPy -when importing CuPy fails; import CuPy explicitly and pass the module when -checking GPU execution. Driver errors and insufficient memory remain errors. +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 index c447832..9b56a2e 100644 --- a/doc/source/gpu.rst +++ b/doc/source/gpu.rst @@ -1,144 +1,298 @@ -GPU arrays, subsetting, and standardization -=========================================== +GPU arrays, readers, and standardization +======================================== -The GPU changes described here are under development on this branch. They are -not a promise that the latest published PySnpTools contains these changes. -CuPy is optional and must be installed separately for your GPU platform. -For the concurrent explicit reader API and native GPU BED path, see -:doc:`gpu-api-preview`. +This guide describes the current development implementation, including the +reader GPU API. Matching development versions of PySnpTools and bed-reader are +required; installing the published packages does not necessarily provide these +features. NumPy runs on the CPU. CuPy support here is experimental CUDA support; +Python HIP support is not implemented. -Construct arrays and select a backend -------------------------------------- +Backend, dtype, and order +------------------------- -``SnpData`` and ``KernelData`` accept ``xp`` as a module or module name. -An explicit choice overrides ``ARRAY_MODULE``; without either, NumPy is used. -The numerical values live in the selected module; IDs and position metadata -remain NumPy arrays on the CPU. Moving an existing float32 or float64 array -between NumPy and CuPy preserves its dtype. Lists and integer arrays normally -become float64. A same-module floating-point input can share storage, so copy it -first when later in-place changes must not affect the caller. +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. -This complete example needs CuPy and a working GPU, but no BED file or native -GPU bed-reader build:: +.. 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 + become float64. Same-module floating arrays can share storage. + * - ``SnpReader.read``, ``KernelReader.read`` + - ``xp=None``, ``dtype=np.float64``, ``order="F"`` + - Return ``SnpData`` or ``KernelData``. Every read chooses its backend + independently of the constructor and its requested output dtype. + * - ``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``. + Output dtype defaults to float64; ``xp=None`` uses the environment. + * - ``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. + +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 + 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, xp=cp - ) - assert isinstance(data.val, cp.ndarray) and data.val.dtype == np.float32 - host = SnpData(iid=data.iid, sid=data.sid, pos=data.pos, - val=data.val, xp=np) - np.testing.assert_array_equal(host.val, values) + 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 - np.testing.assert_array_equal(asnumpy(data.val), values) + 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]]) -``asnumpy`` transfers a CuPy array to the CPU and returns a NumPy array unchanged. -``array_module("cupy")`` can log a warning and select NumPy if the CuPy import -fails. Importing CuPy explicitly, as above, avoids accidentally mistaking this -fallback for a successful GPU run. Driver/runtime failures are separate errors. +``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`` defaults to 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. -Subset without moving values to the CPU ---------------------------------------- +Standardization and trained statistics +-------------------------------------- -``sub_matrix`` dispatches from the actual input array, independently of -``ARRAY_MODULE``. It supports contiguous float32/float64 arrays with two or three -dimensions and keeps the result on the input device. Row and column lists select -a Cartesian product, preserving order and duplicates. On the CuPy path, negative -or out-of-range indices raise ``IndexError`` instead of CuPy's wrapping behavior:: +Unit and Beta modify values in place on their existing device; they do not +consult ``ARRAY_MODULE``. Values must be contiguous floating-point arrays. +``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. - from pysnptools.util import sub_matrix +.. list-table:: Standardizer behavior + :header-rows: 1 + :widths: 23 77 - selected = sub_matrix(data.val, [2, 0, 2], [1, 0], - dtype=data.val.dtype, order="F") - assert isinstance(selected, cp.ndarray) - assert selected.dtype == np.float32 and selected.flags.f_contiguous - np.testing.assert_array_equal(cp.asnumpy(selected), values[[2, 0, 2]][:, [1, 0]]) + * - 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. -The default result dtype is float64; pass ``dtype`` explicitly to keep float32. -Narrowing float64 to float32 emits a precision warning. These low-level index -rules differ from reader slicing, which accepts slices and Boolean masks. +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. -On this committed branch, reader ``read`` methods do not yet accept ``xp``. -They consult ``ARRAY_MODULE`` when constructing the returned data object, even -if the original object was constructed with an explicit ``xp``. To keep an -in-memory subset on the GPU, set the environment for the read and request the -dtype explicitly. The context below restores the prior environment:: +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. - from unittest.mock import patch +This independent example exercises training, imputation, constant columns, and +applying training moments to different values, on both devices:: - with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): - subset = data[[2, 0], :].read(dtype="float32") - assert isinstance(subset.val, cp.ndarray) and subset.val.dtype == np.float32 - np.testing.assert_array_equal(cp.asnumpy(subset.val), values[[2, 0]]) + import cupy as cp + import numpy as np + from pysnptools.snpreader import SnpData + from pysnptools.standardizer import Unit, Beta + from pysnptools.util import asnumpy -``ARRAY_MODULE`` is process-wide. Avoid changing it concurrently with other -workflows. An in-memory CuPy array does not imply that all readers, writers, or -utility functions accept CuPy inputs. + 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") -Standardize and reuse training statistics ------------------------------------------ +Native GPU BED reads and kernel construction +-------------------------------------------- -``Unit`` and ``Beta`` standardize numerical values in place. On this branch, -keep ``ARRAY_MODULE`` consistent with the data device when calling Unit: it -consults the environment and can fail when asked to convert CuPy values to -NumPy implicitly. Unit centers each SNP and divides by its observed standard deviation; -missing values become zero. A SNP with no observations raises ``ValueError``. -A constant training SNP has an infinite stored standard deviation so a trained -standardizer zeros that SNP in later data too. Beta centers and weights SNPs -using the beta density at the minor allele frequency; it is not Unit scaling. -Its SciPy beta-density calculation transfers per-SNP values through the CPU. +GPU BED decoding requires the matching bed-reader Python extension built with +``cubecl-cuda``, 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. +Metadata stays on the CPU. Native GPU reads expose Rust-owned device memory +through CuPy, whose views keep that owner alive. -Using the ``data`` from the first example:: +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 - with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): - standardized, trained = data.standardize(Unit(), return_trained=True) - assert standardized is data - assert isinstance(data.val, cp.ndarray) and data.val.dtype == np.float32 - fresh = SnpData(iid=data.iid, sid=data.sid, - val=cp.asarray(values), xp=cp) - fresh.standardize(trained) - np.testing.assert_allclose(cp.asnumpy(fresh.val), cp.asnumpy(data.val), - rtol=1e-6, atol=1e-6) - weighted = SnpData(iid=data.iid, sid=data.sid, - val=cp.asarray(values), xp=cp).standardize(Beta(1, 25)) - assert isinstance(weighted.val, cp.ndarray) - -The tolerance here is for this small, well-scaled float32 example, not a general -numerical guarantee. Applying trained statistics requires matching SNP IDs and -order; reuse statistics fitted on training data when transforming test data. -The training call has already changed ``data.val`` in place. - -Read files and construct a kernel ---------------------------------- - -On this branch, selecting CuPy for a PySnpTools BED read transfers values after -the existing file read; it does not itself request native GPU BED decoding. -FaST-LMM's GPU BED integration is a separate path. For an existing BED dataset:: + 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 - from pysnptools.snpreader import Bed +``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. The requested positive integer +``block_size`` limits each SNP block, including when SNPs are fewer than samples; +``None`` loads all SNPs. 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. - with patch.dict("os.environ", {"ARRAY_MODULE": "cupy"}): - bed = Bed("cohort.bed", count_A1=True) - block = bed[:100, :200].read(dtype="float32").standardize(Unit()) - kernel = bed.read_kernel(Unit(), block_size=1000, dtype="float32") - assert isinstance(block.val, cp.ndarray) - assert isinstance(kernel.val, cp.ndarray) - -The BED file must have accompanying BIM and FAM files. Keep ``count_A1`` explicit. -``read_kernel(Unit())`` forms the product of standardized SNPs and their -transpose; use kernel standardization separately if a unit average diagonal is -needed. ``block_size`` is a suggested SNP block size and does not cap total GPU -memory. The result is still a dense samples-by-samples matrix. In the committed -implementation, the small-SNP/low-rank path can read all SNPs despite a requested -block size, and kernel accumulation can use float64 before the requested output -cast. Do not infer an all-float32 computation or a memory guarantee from the -returned dtype. +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 0478930..c9e206d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,10 @@ 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; 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. @@ -56,6 +60,10 @@ covered by the Python 3.11 through 3.14 test matrix. :maxdepth: 2 gpu + +.. toctree:: + :hidden: + gpu-api-preview :Code: 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 fdc7d61..4765aed 100644 --- a/pysnptools/kernelreader/kerneldata.py +++ b/pysnptools/kernelreader/kerneldata.py @@ -25,8 +25,8 @@ class KernelData(KernelReader, PstData): * **val** (a 2-D array of floats) -- The SNP 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*. @@ -142,7 +142,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.]]) @@ -191,10 +191,15 @@ 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. + 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..84c9474 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 @@ -248,6 +249,7 @@ def read( 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). @@ -256,34 +258,41 @@ def read( 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. :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. - 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: @@ -302,14 +311,34 @@ def read( >>> #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 + 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) + 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 +412,15 @@ def _read_with_standardizing( snp_standardizer=None, kernel_standardizer=DiagKtoN(), return_trained=False, + dtype=np.float64, + 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 + 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..c364f05 100644 --- a/pysnptools/kernelreader/snpkernel.py +++ b/pysnptools/kernelreader/snpkernel.py @@ -11,8 +11,10 @@ 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. @@ -85,45 +87,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 +136,8 @@ def _read_with_standardizing( kernel_standardizer=DiagKtoN(), return_trained=False, num_threads=None, + dtype=np.float64, + xp=None, ): """ Reads a SnpKernel with two cases @@ -166,12 +151,13 @@ def _read_with_standardizing( """ logging.info("Starting '_read_with_standardizing'") - xp = pstutil.array_module() + xp = pstutil.array_module(xp) 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 +166,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 @@ -217,6 +204,7 @@ def read_snps( force_python_only=False, view_ok=False, num_threads=None, + xp=None, ): """Reads the SNP values, applies the standardizer, and returns a :class:`.SnpData`. @@ -252,13 +240,10 @@ def read_snps( """ 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) + 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/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..41e63fd 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,47 @@ 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=np.float64, + 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) + 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] + data = SnpData(iid=metadata.iid, sid=metadata.sid, pos=metadata.pos, + val=xp.asarray(owner), 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/snpdata.py b/pysnptools/snpreader/snpdata.py index 9cb36cb..f97ecd4 100644 --- a/pysnptools/snpreader/snpdata.py +++ b/pysnptools/snpreader/snpdata.py @@ -23,12 +23,12 @@ class SnpData(PstData, SnpReader): :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: @@ -189,8 +189,12 @@ 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. @@ -199,21 +203,22 @@ def standardize( standard deviation 1.0) 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 @@ -254,6 +259,7 @@ def _read_kernel( 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 @@ -262,9 +268,11 @@ def _read_kernel( from pysnptools.pstreader import PstReader dtype = np.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)) @@ -288,7 +296,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..099cd82 100644 --- a/pysnptools/snpreader/snpreader.py +++ b/pysnptools/snpreader/snpreader.py @@ -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. @@ -272,13 +272,17 @@ 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. + 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 +302,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. @@ -430,6 +434,7 @@ def read( 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). @@ -438,7 +443,7 @@ def read( 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. (For :class:`Bed`, only, it can also be numpy.int8. Hidden option _require_float32_64 must be set @@ -446,28 +451,35 @@ def read( :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. - 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: @@ -486,8 +498,9 @@ def read( >>> # 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 + 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 +510,42 @@ 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) + return xp.asarray(val, dtype=dtype, order=order) + + def _read_with_standardizing(self, standardizer, order="F", dtype=np.float64, + 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.""" + 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 @@ -558,19 +603,48 @@ def read_kernel( 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. + 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 (default) or float32. 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. @@ -592,7 +666,7 @@ def read_kernel( 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 +682,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 +701,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 +729,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) + 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,12 +750,9 @@ 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, @@ -691,14 +764,17 @@ def _read_kernel( 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) + 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 +782,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,15 +790,29 @@ 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() + del train_data + # Return CubeCL's unused blocks to the driver before CuPy's + # eigensolver needs its workspace (the libraries have separate pools). + from bed_reader import has_gpu_support + if has_gpu_support(): + from bed_reader.bed_reader import gpu_memory_cleanup + gpu_memory_cleanup() 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" @@ -739,15 +829,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,18 +853,30 @@ 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: logging.info(f"read {ct:,} SNPs in {diff:.2f} seconds") diff_last = diff + if xp is not np: + from bed_reader import has_gpu_support + if has_gpu_support(): + from bed_reader.bed_reader import gpu_memory_cleanup + gpu_memory_cleanup() t1 = time.time() 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..3882a22 --- /dev/null +++ b/pysnptools/standardizer/_cupy.py @@ -0,0 +1,23 @@ +"""Lazily compiled CuPy kernels; importing PySnpTools does not require CuPy.""" +from functools import lru_cache + + +@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..79ce067 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 @@ -63,7 +64,9 @@ 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) + factor = (float(kerneldata.iid_count) / np.diag(kerneldata.val).sum() + if xp is np else float(kerneldata.iid_count) / float(xp.diag(kerneldata.val).sum(dtype=np.float64))) if abs(factor - 1.0) > 1e-15: kerneldata._val *= factor @@ -118,7 +121,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) + # 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 kernels + # The centered reduction with mean zero is a sum of squares. + squared_sum = float(kernels()[2](vec, xp.asarray(0.0, dtype=np.float64))) factor = float(val.shape[0]) / squared_sum if abs(factor - 1.0) > 1e-15: diff --git a/pysnptools/standardizer/standardizer.py b/pysnptools/standardizer/standardizer.py index df243c8..4b5334c 100644 --- a/pysnptools/standardizer/standardizer.py +++ b/pysnptools/standardizer/standardizer.py @@ -74,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: @@ -122,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) @@ -130,6 +135,10 @@ 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: + 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( @@ -210,6 +219,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): """ @@ -249,7 +313,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 @@ -294,6 +358,10 @@ def _standardize_beta_python(snps, betaA, betaB, apply_in_place, use_stats, stat # 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..d0c89fd 100644 --- a/pysnptools/test.py +++ b/pysnptools/test.py @@ -38,6 +38,155 @@ import time +class TestBetaPython(unittest.TestCase): + 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 TestPySnpTools(unittest.TestCase): def xtest_aaa_hdf5_speed(self): # !!too slow to use all the time # currentFolder + "/examples/toydata.5chrom.bed" @@ -1568,6 +1717,7 @@ def getTestSuite(): """ test_suite = unittest.TestSuite([]) + test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestBetaPython)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestPySnpTools)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestDistReaders)) test_suite.addTests(unittest.TestLoader().loadTestsFromTestCase(TestDistributedBed)) 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_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 6c5bd98..76e2bfb 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -3,6 +3,7 @@ import numpy as np import sys from contextlib import contextmanager +from operator import index as integer_index import time import datetime from types import ModuleType @@ -290,10 +291,10 @@ def sub_matrix( 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,16 +303,26 @@ 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 + 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. CuPy row/column indices must be nonnegative and in range. Both paths + 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; the default output dtype is float64. See :doc:`/gpu` for GPU examples. @@ -354,8 +365,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( @@ -434,9 +445,27 @@ def _sub_matrix_cupy(cp, val, row_index_list, col_index_list, effective_order, d def _checked_index(index_list, count, name): - # cupy indexing silently wraps negative and out-of-range indexes, so check them on - # the host first. (The Rust path rejects them too, though with a less clear error.) - index = np.asarray(index_list, dtype=np.intp) + # 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( @@ -444,7 +473,7 @@ def _checked_index(index_list, count, name): name, index[bad][0], count ) ) - return index + return index.astype(np.uintp, copy=False) def create_directory_if_necessary(name, isfile=True, robust=False): @@ -705,7 +734,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). @@ -713,8 +744,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 @@ -722,11 +752,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 @@ -735,16 +765,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}'") @@ -755,8 +778,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/test.py b/pysnptools/util/test.py index 3dbb7ab..c1ed926 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -120,6 +120,63 @@ 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: From 73cce290df6deb388c34f670f60c2bcdae489c79 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Tue, 17 Nov 2026 10:15:21 -0800 Subject: [PATCH 12/21] Save detailed GPU workflow notebook before simplification --- doc/ipynb/gpu_workflow.ipynb | 522 +++++++++++++++++++++++++++++++++++ 1 file changed, 522 insertions(+) create mode 100644 doc/ipynb/gpu_workflow.ipynb diff --git a/doc/ipynb/gpu_workflow.ipynb b/doc/ipynb/gpu_workflow.ipynb new file mode 100644 index 0000000..de3f471 --- /dev/null +++ b/doc/ipynb/gpu_workflow.ipynb @@ -0,0 +1,522 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c9fa26e3", + "metadata": {}, + "source": [ + "# From BED files to GPU kernels and PCA\n", + "\n", + "PySnpTools can read into CuPy, standardize on the array's device, reuse fitted statistics, and construct kernels in SNP blocks. This notebook combines those operations with independently checked calculations. It uses the existing PySnpTools toy dataset, downloaded and cached by `example_file` on first use.\n", + "\n", + "**Requirements:** matching development versions of PySnpTools and bed-reader, the bed-reader extension built with the **`cubecl-cuda` Cargo feature**, CuPy, a working CUDA driver, and an NVIDIA GPU (CUDA device 0). Also install Jupyter and Matplotlib in the notebook environment. These experimental features are not necessarily in published packages. See the [GPU guide](../source/gpu.rst) for supported options and limitations.\n", + "\n", + "PySnpTools imports appear where they are first used. The capability check verifies the build; an actual CuPy operation verifies runtime access. A missing GPU is an error, so this notebook cannot quietly become a CPU demonstration." + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "a51c5ac4", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:20.566020Z", + "iopub.status.busy": "2026-11-17T05:27:20.565884Z", + "iopub.status.idle": "2026-11-17T05:27:21.782664Z", + "shell.execute_reply": "2026-11-17T05:27:21.781779Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "GPU: NVIDIA GeForce RTX 3060\n", + "{'pysnptools': '1.0.1', 'bed-reader': '1.2.1'} CuPy: 14.2.0\n" + ] + } + ], + "source": [ + "from importlib.metadata import version\n", + "from time import perf_counter\n", + "from unittest.mock import patch\n", + "\n", + "import cupy as cp\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np\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", + "device = cp.cuda.runtime.getDeviceProperties(cp.cuda.Device().id)\n", + "print(\"GPU:\", device[\"name\"].decode())\n", + "print({package: version(package) for package in (\"pysnptools\", \"bed-reader\")}, \"CuPy:\", cp.__version__)" + ] + }, + { + "cell_type": "markdown", + "id": "a1f9675f", + "metadata": {}, + "source": [ + "## Open an existing sample dataset\n", + "\n", + "Use the same toy dataset as other PySnpTools examples. `example_file` downloads and caches the BED/BIM/FAM files together. We select 96 samples and 256 SNPs to keep the walkthrough quick; change or remove the selection to try more data.\n", + "\n", + "BED stores allele counts (0/1/2). A separate, small in-memory example below demonstrates fractional dosages, missing values, and constant columns.\n" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "76f6cf6a", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:21.784125Z", + "iopub.status.busy": "2026-11-17T05:27:21.783915Z", + "iopub.status.idle": "2026-11-17T05:27:21.800654Z", + "shell.execute_reply": "2026-11-17T05:27:21.799661Z" + } + }, + "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", + "bed_path = example_file(\"pysnptools/examples/toydata.*\", \"*.bed\")\n", + "bed = Bed(bed_path, count_A1=True)\n", + "sample_count, snp_count = bed.iid_count, bed.sid_count\n", + "print(f\"{sample_count} samples × {snp_count} SNPs\")" + ] + }, + { + "cell_type": "markdown", + "id": "a116db4b", + "metadata": {}, + "source": [ + "## Select a backend, dtype, and memory order\n" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "0c2b5e31", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:21.802297Z", + "iopub.status.busy": "2026-11-17T05:27:21.802167Z", + "iopub.status.idle": "2026-11-17T05:27:21.885835Z", + "shell.execute_reply": "2026-11-17T05:27:21.885005Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " float32 F order: True\n", + " float64 C order: True\n" + ] + } + ], + "source": [ + "# We use float32 because it is much, much faster on consumer GPUs than float64.\n", + "\n", + "# Read on the CPU for comparison; reads otherwise default to float64.\n", + "cpu = bed.read(dtype=\"float32\", xp=np)\n", + "snp_values, iid = cpu.val, cpu.iid\n", + "\n", + "# Upload packed BED bytes and decode on the GPU.\n", + "# .val is a CuPy array backed by Rust-owned memory; its views retain ownership.\n", + "# F order stores each SNP's sample values together; C order stores each sample's SNP values together.\n", + "gpu = bed.read(dtype=\"float32\", order=\"F\", xp=cp)\n", + "assert isinstance(gpu.val, cp.ndarray) and gpu.val.flags.f_contiguous\n", + "# Sample IDs, SNP IDs, and positions stay on the CPU.\n", + "assert gpu.val.dtype == np.float32 and isinstance(gpu.iid, np.ndarray)\n", + "# Copy to the CPU only to check equality, including missing values (NaNs).\n", + "# Decoded allele counts are exact, so no floating-point tolerance is needed.\n", + "np.testing.assert_array_equal(cp.asnumpy(gpu.val), snp_values)\n", + "\n", + "# Module names work too; this read uses float64 and C order.\n", + "# float64 is supported; its arithmetic can be much slower on consumer GPUs.\n", + "selected = bed[:4, :6].read(dtype=\"float64\", order=\"C\", xp=\"cupy\")\n", + "assert selected.val.flags.c_contiguous and selected.val.dtype == np.float64\n", + "np.testing.assert_array_equal(cp.asnumpy(selected.val), snp_values[:4, :6])\n", + "np.testing.assert_array_equal(selected.iid, iid[:4])\n", + "print(type(gpu.val), gpu.val.dtype, \"F order:\", gpu.val.flags.f_contiguous)\n", + "print(type(selected.val), selected.val.dtype, \"C order:\", selected.val.flags.c_contiguous)\n" + ] + }, + { + "cell_type": "markdown", + "id": "7cb970c2", + "metadata": {}, + "source": [ + "## Set a shared backend default\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "49974ed6", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:21.887241Z", + "iopub.status.busy": "2026-11-17T05:27:21.887115Z", + "iopub.status.idle": "2026-11-17T05:27:21.986725Z", + "shell.execute_reply": "2026-11-17T05:27:21.985652Z" + } + }, + "outputs": [], + "source": [ + "from pysnptools.standardizer import Unit\n", + "from pysnptools.util import sub_matrix\n", + "\n", + "# Everything inside uses this default where xp=None is supported,\n", + "# including reads inside other functions. Explicit xp still takes precedence.\n", + "# The environment is process-wide: avoid conflicting defaults in concurrent workflows.\n", + "with patch.dict(\"os.environ\", {\"ARRAY_MODULE\": \"cupy\"}):\n", + " device_default = bed[:4, :6].read(dtype=\"float32\", xp=None)\n", + " assert isinstance(device_default.val, cp.ndarray)\n", + " # Omitting xp is equivalent to xp=None.\n", + " also_device = bed[:4, :6].read(dtype=\"float32\")\n", + " assert isinstance(also_device.val, cp.ndarray)\n", + "\n", + " # Override the CuPy default for this read.\n", + " host = bed[:4, :6].read(dtype=\"float32\", xp=np)\n", + " assert isinstance(host.val, np.ndarray)\n", + "# Exiting the block restores the previous environment, even on failure.\n", + "\n", + "with patch.dict(\"os.environ\", {\"ARRAY_MODULE\": \"numpy\"}):\n", + " host_default = bed[:4, :6].read(dtype=\"float32\")\n", + " assert isinstance(host_default.val, np.ndarray)\n", + " # Override the NumPy default for this read.\n", + " device_copy = gpu.read(dtype=\"float32\", xp=cp)\n", + " # Standardization follows the existing array, regardless of the environment.\n", + " device_copy.standardize(Unit())\n", + " assert isinstance(device_copy.val, cp.ndarray)\n", + "\n", + "# Without ARRAY_MODULE, xp=None defaults to NumPy.\n", + "# sub_matrix instead follows the input device; preserve float32 explicitly.\n", + "subset = sub_matrix(gpu.val, [7, 2, 7], [5, 3, 0], dtype=gpu.val.dtype, order=\"C\")\n", + "assert isinstance(subset, cp.ndarray) and subset.dtype == np.float32\n", + "np.testing.assert_array_equal(cp.asnumpy(subset), snp_values[[7, 2, 7]][:, [5, 3, 0]])\n" + ] + }, + { + "cell_type": "markdown", + "id": "2e9f0c0e", + "metadata": {}, + "source": [ + "## Fractional dosages: Unit and Beta\n", + "\n", + "Unit uses each SNP's observed mean and population standard deviation (`ddof=0`), then fills missing values with zero. Final variance can be below one after imputation. Constant training columns become zero and store infinite standard deviation; fitting a wholly missing SNP raises `ValueError`.\n", + "\n", + "Beta centers values and multiplies by a beta density at the minor-allele frequency; it **does not divide by the standard deviation**. Our Beta(2, 3) reference uses the polynomial density `12 p (1-p)²`, independently of PySnpTools and SciPy. Beta needs valid allele-frequency means. Unit also accepts negative and out-of-range finite values.\n", + "\n", + "This deliberately small reference loops over SNPs using centered float64 residuals, avoiding raw-moment subtraction `E[x²] − E[x]²`. Tolerances are 32 machine epsilons for these small, bounded inputs; results need not be bit-identical across floating algorithms." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "55b296e5", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:21.988206Z", + "iopub.status.busy": "2026-11-17T05:27:21.988057Z", + "iopub.status.idle": "2026-11-17T05:27:22.354015Z", + "shell.execute_reply": "2026-11-17T05:27:22.353032Z" + } + }, + "outputs": [], + "source": [ + "from pysnptools.snpreader import SnpData\n", + "from pysnptools.standardizer import Beta\n", + "\n", + "dosages = np.array([\n", + " [0.25, 1.0, 0.5],\n", + " [0.75, 1.0, np.nan],\n", + " [np.nan, 1.0, 1.5],\n", + " [1.75, 1.0, 1.0],\n", + " [1.25, 1.0, 0.75],\n", + "], dtype=np.float64)\n", + "dosage_iid = [[\"family\", str(sample)] for sample in range(len(dosages))]\n", + "dosage_sid = [\"dosage\", \"constant\", \"missing\"]\n", + "\n", + "def reference(values, beta=False):\n", + " result = np.zeros(values.shape, dtype=np.float64)\n", + " stats = np.empty((values.shape[1], 2), dtype=np.float64)\n", + " for column in range(values.shape[1]):\n", + " observed = ~np.isnan(values[:, column])\n", + " finite = values[observed, column].astype(np.float64)\n", + " mean = finite.mean()\n", + " deviation = np.sqrt(np.mean((finite - mean) ** 2))\n", + " stats[column] = [mean, deviation if deviation != 0 else np.inf]\n", + " if deviation == 0:\n", + " continue\n", + " if beta:\n", + " frequency = min(mean / 2, 1 - mean / 2)\n", + " factor = 12 * frequency * (1 - frequency) ** 2\n", + " else:\n", + " factor = 1 / deviation\n", + " result[observed, column] = (finite - mean) * factor\n", + " return result, stats\n", + "\n", + "for dtype in (np.float32, np.float64):\n", + " tolerance = 32 * np.finfo(dtype).eps\n", + " for order in (\"C\", \"F\"):\n", + " for standardizer in (Unit(), Beta(2, 3)):\n", + " values = dosages.astype(dtype)\n", + " if isinstance(standardizer, Unit):\n", + " values[:, 0] -= 4 # Unit supports finite values outside [0, 2].\n", + " expected, expected_stats = reference(values, beta=isinstance(standardizer, Beta))\n", + " data = SnpData(iid=dosage_iid, sid=dosage_sid,\n", + " val=cp.array(values, order=order), xp=cp)\n", + " _, trained = data.standardize(standardizer, return_trained=True)\n", + " assert isinstance(data.val, cp.ndarray) and data.val.dtype == dtype\n", + " assert data.val.flags[\"C_CONTIGUOUS\" if order == \"C\" else \"F_CONTIGUOUS\"]\n", + " assert isinstance(trained.stats, np.ndarray)\n", + " np.testing.assert_allclose(cp.asnumpy(data.val), expected, rtol=tolerance, atol=tolerance)\n", + " np.testing.assert_allclose(trained.stats, expected_stats, rtol=tolerance, atol=tolerance)\n", + "print(\"Fractional Unit/Beta checks passed for both floating dtypes and orders\")" + ] + }, + { + "cell_type": "markdown", + "id": "6713ed45", + "metadata": {}, + "source": [ + "## Fit once; apply without refitting\n", + "\n", + "Fit on training samples, then apply those moments to a held-out cohort. Only the small per-SNP statistics are returned to the CPU. The matrix stays on the GPU. Beta's per-SNP density evaluation uses SciPy on the CPU; that is different from transferring the matrix to a CPU standardizer.\n", + "\n", + "UnitTrained can select and reorder known SNP IDs. BetaTrained requires the exact training IDs and order. Neither refits missing test columns or columns that were constant during training.\n", + "\n", + "Trained statistics can also cross devices and floating dtypes. The CPU float64 application below uses the stored float32 moments; a wider target cannot restore precision already lost during training." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "66812d3b", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:22.356128Z", + "iopub.status.busy": "2026-11-17T05:27:22.355975Z", + "iopub.status.idle": "2026-11-17T05:27:22.389392Z", + "shell.execute_reply": "2026-11-17T05:27:22.388196Z" + } + }, + "outputs": [], + "source": [ + "training_rows = np.arange(0, sample_count, 2)\n", + "test_rows = np.arange(1, sample_count, 2)\n", + "training = bed[training_rows, :].read(dtype=\"float32\", xp=cp)\n", + "_, fitted_unit = training.standardize(Unit(), return_trained=True)\n", + "test = bed[test_rows, :].read(dtype=\"float32\", xp=cp).standardize(fitted_unit)\n", + "assert isinstance(test.val, cp.ndarray) and isinstance(fitted_unit.stats, np.ndarray)\n", + "\n", + "# An independent application of the stored moments, not a fit on test rows.\n", + "means, deviations = fitted_unit.stats.T\n", + "expected_test = (snp_values[test_rows].astype(np.float64) - means) / deviations\n", + "expected_test[np.isnan(snp_values[test_rows])] = 0\n", + "float32_tolerance = 32 * np.finfo(np.float32).eps\n", + "np.testing.assert_allclose(cp.asnumpy(test.val), expected_test,\n", + " rtol=float32_tolerance, atol=float32_tolerance)\n", + "reordered = bed[test_rows, [5, 3, 0]].read(dtype=\"float32\", xp=cp).standardize(fitted_unit)\n", + "np.testing.assert_array_equal(cp.asnumpy(reordered.val), cp.asnumpy(test.val)[:, [5, 3, 0]])\n", + "print(\"Stored moments:\", fitted_unit.stats.shape, fitted_unit.stats.dtype)\n", + "\n", + "# Reuse GPU-trained float32 moments on a CPU float64/F-order target.\n", + "host_test = bed[test_rows, :].read(dtype=\"float64\", order=\"F\", xp=np).standardize(fitted_unit)\n", + "assert isinstance(host_test.val, np.ndarray) and host_test.val.flags.f_contiguous\n", + "np.testing.assert_allclose(host_test.val, expected_test,\n", + " rtol=8 * np.finfo(np.float64).eps,\n", + " atol=8 * np.finfo(np.float64).eps)" + ] + }, + { + "cell_type": "markdown", + "id": "2a1df512", + "metadata": {}, + "source": [ + "## Build kernels in SNP blocks, reusing Beta training statistics\n", + "\n", + "A kernel is `Z @ Z.T`, where `Z` contains standardized SNP values. Native BED kernel construction reads and standardizes on the GPU. A positive integer `block_size` bounds each SNP block, **not the dense sample-by-sample kernel or all temporary allocations**. It is not an out-of-core eigensolver.\n", + "\n", + "We train Beta on one cohort and build the held-out kernel with those exact moments. PySnpTools validates the complete SNP order before using the matching trained statistics for each block. We also compare with an independent float64 product, explicitly allowing float32 accumulation roundoff: 64 epsilons relative, and 64 epsilons times the reference absolute-product scale for the absolute error." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "79fd8736", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:22.390943Z", + "iopub.status.busy": "2026-11-17T05:27:22.390804Z", + "iopub.status.idle": "2026-11-17T05:27:22.558631Z", + "shell.execute_reply": "2026-11-17T05:27:22.557264Z" + } + }, + "outputs": [], + "source": [ + "beta_training = bed[training_rows, :].read(dtype=\"float32\", xp=cp)\n", + "_, fitted_beta = beta_training.standardize(Beta(2, 3), return_trained=True)\n", + "means, deviations = fitted_beta.stats.T\n", + "frequency = np.minimum(means.astype(np.float64) / 2, 1 - means.astype(np.float64) / 2)\n", + "weights = 12 * frequency * (1 - frequency) ** 2\n", + "weights[np.isinf(deviations)] = 0\n", + "expected_beta = (snp_values[test_rows].astype(np.float64) - means) * weights\n", + "expected_beta[np.isnan(snp_values[test_rows])] = 0\n", + "expected_kernel = expected_beta @ expected_beta.T\n", + "absolute_product_scale = np.max(np.abs(expected_beta) @ np.abs(expected_beta).T)\n", + "kernel_tolerance = 64 * np.finfo(np.float32).eps\n", + "\n", + "beta_kernel = bed[test_rows, :].read_kernel(\n", + " fitted_beta, block_size=37, dtype=\"float32\", order=\"C\", xp=cp)\n", + "assert isinstance(beta_kernel.val, cp.ndarray) and beta_kernel.val.flags.c_contiguous\n", + "np.testing.assert_allclose(cp.asnumpy(beta_kernel.val), expected_kernel,\n", + " rtol=kernel_tolerance,\n", + " atol=kernel_tolerance * absolute_product_scale)\n", + "unit_kernel = bed.read_kernel(Unit(), block_size=37, dtype=\"float64\", order=\"F\", xp=cp)\n", + "expected_unit, _ = reference(snp_values)\n", + "np.testing.assert_allclose(cp.asnumpy(unit_kernel.val), expected_unit @ expected_unit.T,\n", + " rtol=64 * np.finfo(np.float64).eps,\n", + " atol=64 * np.finfo(np.float64).eps * snp_count)\n", + "print(\"Beta test kernel:\", beta_kernel.val.shape, beta_kernel.val.dtype)\n", + "print(\"Unit full-cohort kernel:\", unit_kernel.val.shape, unit_kernel.val.dtype)" + ] + }, + { + "cell_type": "markdown", + "id": "605d368a", + "metadata": {}, + "source": [ + "## Normalize and perform PCA on the GPU\n", + "\n", + "`DiagKtoN` scales the whole kernel to have average diagonal one; Unit standardization alone does not promise that after missing-value imputation. Use a finite, positive-trace kernel. Normalization and the eigendecomposition operate on CuPy arrays. Only the two plotting coordinates and a few eigenvalues are copied back.\n", + "\n", + "The plot shows the toy samples without assigning population labels; it is a demonstration, not a biological finding. Eigenvector signs are arbitrary; the sign of an axis can change between valid runs." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8fc1345b", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:22.560506Z", + "iopub.status.busy": "2026-11-17T05:27:22.560347Z", + "iopub.status.idle": "2026-11-17T05:27:22.891710Z", + "shell.execute_reply": "2026-11-17T05:27:22.890688Z" + } + }, + "outputs": [], + "source": [ + "from pysnptools.standardizer import DiagKtoN\n", + "\n", + "unit_kernel.standardize(DiagKtoN())\n", + "trace = float(cp.trace(unit_kernel.val))\n", + "np.testing.assert_allclose(trace, sample_count, rtol=64 * np.finfo(np.float64).eps, atol=0)\n", + "eigenvalues, eigenvectors = cp.linalg.eigh(unit_kernel.val)\n", + "# Check the two eigenpairs before copying their small plotting coordinates.\n", + "residual = unit_kernel.val @ eigenvectors[:, -2:] - eigenvectors[:, -2:] * eigenvalues[-2:]\n", + "relative_residual = float(cp.linalg.norm(residual) / cp.linalg.norm(unit_kernel.val))\n", + "assert relative_residual < 1e-12 # float64 eigensolver, small well-scaled matrix\n", + "coordinates = cp.asnumpy(eigenvectors[:, [-1, -2]] * cp.sqrt(eigenvalues[[-1, -2]]))\n", + "figure, axes = plt.subplots(figsize=(6, 4))\n", + "axes.scatter(coordinates[:, 0], coordinates[:, 1])\n", + "axes.set(xlabel=\"PC1\", ylabel=\"PC2\", title=\"GPU kernel PCA on the toy dataset\")\n", + "figure.tight_layout()\n", + "plt.show()\n", + "print(\"Largest eigenvalues:\", cp.asnumpy(eigenvalues[-3:][::-1]))" + ] + }, + { + "cell_type": "markdown", + "id": "bc8618f3", + "metadata": {}, + "source": [ + "## Time completed work\n", + "\n", + "CuPy launches are asynchronous. Synchronize before and after a wall-clock measurement so the interval includes completed work. Warm up the exact operation first; this excludes first-use compilation from the reported time. This measures a complete local-file read/standardize/kernel pipeline, including host work and synchronization. It is not isolated kernel time or a claim that this small example is faster than the CPU.\n", + "\n", + "Use representative data and repeated measurements for a performance study. Native decoding and CuPy may use different streams; device-wide synchronization covers both." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a4b2cf69", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-17T05:27:22.893354Z", + "iopub.status.busy": "2026-11-17T05:27:22.893181Z", + "iopub.status.idle": "2026-11-17T05:27:22.984297Z", + "shell.execute_reply": "2026-11-17T05:27:22.983498Z" + } + }, + "outputs": [], + "source": [ + "def timed_kernel_read():\n", + " return bed.read_kernel(Unit(), block_size=37, dtype=\"float32\", xp=cp)\n", + "\n", + "warmup = timed_kernel_read()\n", + "cp.cuda.runtime.deviceSynchronize()\n", + "del warmup\n", + "elapsed = []\n", + "for repetition in range(3):\n", + " cp.cuda.runtime.deviceSynchronize()\n", + " started = perf_counter()\n", + " measured_kernel = timed_kernel_read()\n", + " cp.cuda.runtime.deviceSynchronize()\n", + " elapsed.append(perf_counter() - started)\n", + " assert isinstance(measured_kernel.val, cp.ndarray)\n", + " del measured_kernel\n", + "print(f\"Completed GPU pipeline, median of 3 warm runs: {np.median(elapsed) * 1000:.2f} ms\")" + ] + }, + { + "cell_type": "markdown", + "id": "27d75937", + "metadata": {}, + "source": [ + "The same explicit-backend and trained-statistics choices carry into FaST-LMM association workflows; see its GPU guide for worker execution and backend selection. This notebook stops at PySnpTools' public kernel API.\n", + "\n", + "CPU reads remain available with `xp=np`. Integer BED reads are supported with the documented opt-in, but int8 standardization is rejected; read or convert to float32/float64 first. Other file formats may read on the CPU and then transfer. GPU availability errors are not silently retried on the CPU.\n", + "\n", + "The downloaded sample files stay cached for reuse. Device arrays own their decoded data. Dropping arrays releases ownership, but allocation pools can retain memory for reuse; deleting a name is not a guarantee that another GPU library immediately receives that memory." + ] + } + ], + "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 +} From 1a60cfcd315ca4fe766dcf104f61a19a65be4cad Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Tue, 17 Nov 2026 12:40:39 -0800 Subject: [PATCH 13/21] Preserve CubeCL GPU allocations and simplify the GPU workflow --- CHANGELOG.md | 22 + README.md | 12 +- doc/ipynb/gpu_workflow.ipynb | 556 ++++++++--------------- doc/source/gpu.rst | 69 ++- doc/source/index.rst | 1 + pysnptools/kernelreader/kerneldata.py | 8 +- pysnptools/kernelreader/kernelreader.py | 15 +- pysnptools/kernelreader/snpkernel.py | 38 +- pysnptools/kernelreader/test.py | 21 + pysnptools/pstreader/pstdata.py | 24 +- pysnptools/snpreader/bed.py | 7 +- pysnptools/snpreader/snpdata.py | 16 +- pysnptools/snpreader/snpreader.py | 17 +- pysnptools/standardizer/_cupy.py | 10 + pysnptools/standardizer/diag_K_to_N.py | 43 +- pysnptools/standardizer/standardizer.py | 16 +- pysnptools/test.py | 112 +++++ pysnptools/test_gpu_allocator.py | 262 +++++++++++ pysnptools/test_gpu_precision_warning.py | 63 +++ pysnptools/util/__init__.py | 15 + pysnptools/util/_array.py | 86 ++++ pysnptools/util/_gpu_warnings.py | 24 + specs/GPU_DOCUMENTATION_AUDIT.md | 125 +++++ 23 files changed, 1129 insertions(+), 433 deletions(-) create mode 100644 pysnptools/test_gpu_allocator.py create mode 100644 pysnptools/test_gpu_precision_warning.py create mode 100644 pysnptools/util/_array.py create mode 100644 pysnptools/util/_gpu_warnings.py create mode 100644 specs/GPU_DOCUMENTATION_AUDIT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d352eed..45085f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +* 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. diff --git a/README.md b/README.md index e123ba0..e87650a 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ 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. + See the [GPU guide](doc/source/gpu.rst) and [workflow notebook](doc/ipynb/gpu_workflow.ipynb). + Requires matching development packages and a CUDA-enabled bed-reader 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). @@ -40,14 +44,6 @@ Existing HDF5 users upgrading from an earlier release should install this extra. pip install pysnptools[bgen] -GPU arrays (development branch) -------------------------------- - -Readers accept explicit NumPy/CuPy backends; standardization follows the array's -device. GPU BED reads require a CUDA-enabled bed-reader build. See the -[GPU guide](doc/source/gpu.rst) for prerequisites, options, and complete examples. -These development features are not necessarily in the published packages. - Documentation ------------- diff --git a/doc/ipynb/gpu_workflow.ipynb b/doc/ipynb/gpu_workflow.ipynb index de3f471..d9587f1 100644 --- a/doc/ipynb/gpu_workflow.ipynb +++ b/doc/ipynb/gpu_workflow.ipynb @@ -2,81 +2,54 @@ "cells": [ { "cell_type": "markdown", - "id": "c9fa26e3", + "id": "3ea2976e", "metadata": {}, "source": [ "# From BED files to GPU kernels and PCA\n", "\n", - "PySnpTools can read into CuPy, standardize on the array's device, reuse fitted statistics, and construct kernels in SNP blocks. This notebook combines those operations with independently checked calculations. It uses the existing PySnpTools toy dataset, downloaded and cached by `example_file` on first use.\n", + "Read SNP data onto the GPU, build a standardized kernel, and plot the first two principal components.\n", "\n", - "**Requirements:** matching development versions of PySnpTools and bed-reader, the bed-reader extension built with the **`cubecl-cuda` Cargo feature**, CuPy, a working CUDA driver, and an NVIDIA GPU (CUDA device 0). Also install Jupyter and Matplotlib in the notebook environment. These experimental features are not necessarily in published packages. See the [GPU guide](../source/gpu.rst) for supported options and limitations.\n", - "\n", - "PySnpTools imports appear where they are first used. The capability check verifies the build; an actual CuPy operation verifies runtime access. A missing GPU is an error, so this notebook cannot quietly become a CPU demonstration." + "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": 28, - "id": "a51c5ac4", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:20.566020Z", - "iopub.status.busy": "2026-11-17T05:27:20.565884Z", - "iopub.status.idle": "2026-11-17T05:27:21.782664Z", - "shell.execute_reply": "2026-11-17T05:27:21.781779Z" - } - }, + "execution_count": 13, + "id": "717f705d", + "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "GPU: NVIDIA GeForce RTX 3060\n", - "{'pysnptools': '1.0.1', 'bed-reader': '1.2.1'} CuPy: 14.2.0\n" + "GPU: NVIDIA GeForce RTX 3060\n" ] } ], "source": [ - "from importlib.metadata import version\n", - "from time import perf_counter\n", - "from unittest.mock import patch\n", - "\n", "import cupy as cp\n", - "import matplotlib.pyplot as plt\n", - "import numpy as np\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", - "print({package: version(package) for package in (\"pysnptools\", \"bed-reader\")}, \"CuPy:\", cp.__version__)" + "print(\"GPU:\", device[\"name\"].decode())\n" ] }, { "cell_type": "markdown", - "id": "a1f9675f", + "id": "d5ade6d8", "metadata": {}, "source": [ - "## Open an existing sample dataset\n", - "\n", - "Use the same toy dataset as other PySnpTools examples. `example_file` downloads and caches the BED/BIM/FAM files together. We select 96 samples and 256 SNPs to keep the walkthrough quick; change or remove the selection to try more data.\n", - "\n", - "BED stores allele counts (0/1/2). A separate, small in-memory example below demonstrates fractional dosages, missing values, and constant columns.\n" + "## Specify the sample data" ] }, { "cell_type": "code", - "execution_count": 29, - "id": "76f6cf6a", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:21.784125Z", - "iopub.status.busy": "2026-11-17T05:27:21.783915Z", - "iopub.status.idle": "2026-11-17T05:27:21.800654Z", - "shell.execute_reply": "2026-11-17T05:27:21.799661Z" - } - }, + "execution_count": 14, + "id": "6e294270", + "metadata": {}, "outputs": [ { "name": "stdout", @@ -90,411 +63,250 @@ "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", - "sample_count, snp_count = bed.iid_count, bed.sid_count\n", - "print(f\"{sample_count} samples × {snp_count} SNPs\")" + "print(f\"{bed.iid_count} samples × {bed.sid_count} SNPs\")\n" ] }, { "cell_type": "markdown", - "id": "a116db4b", + "id": "1ca321b5", "metadata": {}, "source": [ - "## Select a backend, dtype, and memory order\n" + "## Read onto the GPU\n" ] }, { "cell_type": "code", - "execution_count": 30, - "id": "0c2b5e31", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:21.802297Z", - "iopub.status.busy": "2026-11-17T05:27:21.802167Z", - "iopub.status.idle": "2026-11-17T05:27:21.885835Z", - "shell.execute_reply": "2026-11-17T05:27:21.885005Z" - } - }, + "execution_count": 15, + "id": "1ebfb0bb", + "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - " float32 F order: True\n", - " float64 C order: True\n" + " (500, 10000) float32\n", + "SNP values: on GPU: True, CubeCL-backed: True\n" ] } ], "source": [ - "# We use float32 because it is much, much faster on consumer GPUs than float64.\n", - "\n", - "# Read on the CPU for comparison; reads otherwise default to float64.\n", - "cpu = bed.read(dtype=\"float32\", xp=np)\n", - "snp_values, iid = cpu.val, cpu.iid\n", - "\n", - "# Upload packed BED bytes and decode on the GPU.\n", - "# .val is a CuPy array backed by Rust-owned memory; its views retain ownership.\n", - "# F order stores each SNP's sample values together; C order stores each sample's SNP values together.\n", - "gpu = bed.read(dtype=\"float32\", order=\"F\", xp=cp)\n", - "assert isinstance(gpu.val, cp.ndarray) and gpu.val.flags.f_contiguous\n", - "# Sample IDs, SNP IDs, and positions stay on the CPU.\n", - "assert gpu.val.dtype == np.float32 and isinstance(gpu.iid, np.ndarray)\n", - "# Copy to the CPU only to check equality, including missing values (NaNs).\n", - "# Decoded allele counts are exact, so no floating-point tolerance is needed.\n", - "np.testing.assert_array_equal(cp.asnumpy(gpu.val), snp_values)\n", - "\n", - "# Module names work too; this read uses float64 and C order.\n", - "# float64 is supported; its arithmetic can be much slower on consumer GPUs.\n", - "selected = bed[:4, :6].read(dtype=\"float64\", order=\"C\", xp=\"cupy\")\n", - "assert selected.val.flags.c_contiguous and selected.val.dtype == np.float64\n", - "np.testing.assert_array_equal(cp.asnumpy(selected.val), snp_values[:4, :6])\n", - "np.testing.assert_array_equal(selected.iid, iid[:4])\n", - "print(type(gpu.val), gpu.val.dtype, \"F order:\", gpu.val.flags.f_contiguous)\n", - "print(type(selected.val), selected.val.dtype, \"C order:\", selected.val.flags.c_contiguous)\n" + "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", + "snps = bed.read(dtype=\"float32\", 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": "7cb970c2", + "id": "f5700b3e", "metadata": {}, "source": [ - "## Set a shared backend default\n" + "## Standardize and build a kernel\n" ] }, { "cell_type": "code", - "execution_count": null, - "id": "49974ed6", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:21.887241Z", - "iopub.status.busy": "2026-11-17T05:27:21.887115Z", - "iopub.status.idle": "2026-11-17T05:27:21.986725Z", - "shell.execute_reply": "2026-11-17T05:27:21.985652Z" + "execution_count": 16, + "id": "afc8d995", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " (500, 500) float32\n", + "Kernel: on GPU: True, CubeCL-backed: True\n" + ] } - }, - "outputs": [], + ], "source": [ "from pysnptools.standardizer import Unit\n", - "from pysnptools.util import sub_matrix\n", "\n", - "# Everything inside uses this default where xp=None is supported,\n", - "# including reads inside other functions. Explicit xp still takes precedence.\n", - "# The environment is process-wide: avoid conflicting defaults in concurrent workflows.\n", - "with patch.dict(\"os.environ\", {\"ARRAY_MODULE\": \"cupy\"}):\n", - " device_default = bed[:4, :6].read(dtype=\"float32\", xp=None)\n", - " assert isinstance(device_default.val, cp.ndarray)\n", - " # Omitting xp is equivalent to xp=None.\n", - " also_device = bed[:4, :6].read(dtype=\"float32\")\n", - " assert isinstance(also_device.val, cp.ndarray)\n", - "\n", - " # Override the CuPy default for this read.\n", - " host = bed[:4, :6].read(dtype=\"float32\", xp=np)\n", - " assert isinstance(host.val, np.ndarray)\n", - "# Exiting the block restores the previous environment, even on failure.\n", - "\n", - "with patch.dict(\"os.environ\", {\"ARRAY_MODULE\": \"numpy\"}):\n", - " host_default = bed[:4, :6].read(dtype=\"float32\")\n", - " assert isinstance(host_default.val, np.ndarray)\n", - " # Override the NumPy default for this read.\n", - " device_copy = gpu.read(dtype=\"float32\", xp=cp)\n", - " # Standardization follows the existing array, regardless of the environment.\n", - " device_copy.standardize(Unit())\n", - " assert isinstance(device_copy.val, cp.ndarray)\n", - "\n", - "# Without ARRAY_MODULE, xp=None defaults to NumPy.\n", - "# sub_matrix instead follows the input device; preserve float32 explicitly.\n", - "subset = sub_matrix(gpu.val, [7, 2, 7], [5, 3, 0], dtype=gpu.val.dtype, order=\"C\")\n", - "assert isinstance(subset, cp.ndarray) and subset.dtype == np.float32\n", - "np.testing.assert_array_equal(cp.asnumpy(subset), snp_values[[7, 2, 7]][:, [5, 3, 0]])\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. Keep float32 explicitly: the default is float64.\n", + "kernel = snps.read_kernel(Unit(), dtype=\"float32\", 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": "2e9f0c0e", + "id": "8339b131", "metadata": {}, "source": [ - "## Fractional dosages: Unit and Beta\n", - "\n", - "Unit uses each SNP's observed mean and population standard deviation (`ddof=0`), then fills missing values with zero. Final variance can be below one after imputation. Constant training columns become zero and store infinite standard deviation; fitting a wholly missing SNP raises `ValueError`.\n", - "\n", - "Beta centers values and multiplies by a beta density at the minor-allele frequency; it **does not divide by the standard deviation**. Our Beta(2, 3) reference uses the polynomial density `12 p (1-p)²`, independently of PySnpTools and SciPy. Beta needs valid allele-frequency means. Unit also accepts negative and out-of-range finite values.\n", - "\n", - "This deliberately small reference loops over SNPs using centered float64 residuals, avoiding raw-moment subtraction `E[x²] − E[x]²`. Tolerances are 32 machine epsilons for these small, bounded inputs; results need not be bit-identical across floating algorithms." + "## Run PCA and plot\n" ] }, { "cell_type": "code", - "execution_count": null, - "id": "55b296e5", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:21.988206Z", - "iopub.status.busy": "2026-11-17T05:27:21.988057Z", - "iopub.status.idle": "2026-11-17T05:27:22.354015Z", - "shell.execute_reply": "2026-11-17T05:27:22.353032Z" - } - }, - "outputs": [], - "source": [ - "from pysnptools.snpreader import SnpData\n", - "from pysnptools.standardizer import Beta\n", - "\n", - "dosages = np.array([\n", - " [0.25, 1.0, 0.5],\n", - " [0.75, 1.0, np.nan],\n", - " [np.nan, 1.0, 1.5],\n", - " [1.75, 1.0, 1.0],\n", - " [1.25, 1.0, 0.75],\n", - "], dtype=np.float64)\n", - "dosage_iid = [[\"family\", str(sample)] for sample in range(len(dosages))]\n", - "dosage_sid = [\"dosage\", \"constant\", \"missing\"]\n", - "\n", - "def reference(values, beta=False):\n", - " result = np.zeros(values.shape, dtype=np.float64)\n", - " stats = np.empty((values.shape[1], 2), dtype=np.float64)\n", - " for column in range(values.shape[1]):\n", - " observed = ~np.isnan(values[:, column])\n", - " finite = values[observed, column].astype(np.float64)\n", - " mean = finite.mean()\n", - " deviation = np.sqrt(np.mean((finite - mean) ** 2))\n", - " stats[column] = [mean, deviation if deviation != 0 else np.inf]\n", - " if deviation == 0:\n", - " continue\n", - " if beta:\n", - " frequency = min(mean / 2, 1 - mean / 2)\n", - " factor = 12 * frequency * (1 - frequency) ** 2\n", - " else:\n", - " factor = 1 / deviation\n", - " result[observed, column] = (finite - mean) * factor\n", - " return result, stats\n", - "\n", - "for dtype in (np.float32, np.float64):\n", - " tolerance = 32 * np.finfo(dtype).eps\n", - " for order in (\"C\", \"F\"):\n", - " for standardizer in (Unit(), Beta(2, 3)):\n", - " values = dosages.astype(dtype)\n", - " if isinstance(standardizer, Unit):\n", - " values[:, 0] -= 4 # Unit supports finite values outside [0, 2].\n", - " expected, expected_stats = reference(values, beta=isinstance(standardizer, Beta))\n", - " data = SnpData(iid=dosage_iid, sid=dosage_sid,\n", - " val=cp.array(values, order=order), xp=cp)\n", - " _, trained = data.standardize(standardizer, return_trained=True)\n", - " assert isinstance(data.val, cp.ndarray) and data.val.dtype == dtype\n", - " assert data.val.flags[\"C_CONTIGUOUS\" if order == \"C\" else \"F_CONTIGUOUS\"]\n", - " assert isinstance(trained.stats, np.ndarray)\n", - " np.testing.assert_allclose(cp.asnumpy(data.val), expected, rtol=tolerance, atol=tolerance)\n", - " np.testing.assert_allclose(trained.stats, expected_stats, rtol=tolerance, atol=tolerance)\n", - "print(\"Fractional Unit/Beta checks passed for both floating dtypes and orders\")" - ] - }, - { - "cell_type": "markdown", - "id": "6713ed45", + "execution_count": 17, + "id": "ea8e504e", "metadata": {}, - "source": [ - "## Fit once; apply without refitting\n", - "\n", - "Fit on training samples, then apply those moments to a held-out cohort. Only the small per-SNP statistics are returned to the CPU. The matrix stays on the GPU. Beta's per-SNP density evaluation uses SciPy on the CPU; that is different from transferring the matrix to a CPU standardizer.\n", - "\n", - "UnitTrained can select and reorder known SNP IDs. BetaTrained requires the exact training IDs and order. Neither refits missing test columns or columns that were constant during training.\n", - "\n", - "Trained statistics can also cross devices and floating dtypes. The CPU float64 application below uses the stored float32 moments; a wider target cannot restore precision already lost during training." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "66812d3b", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:22.356128Z", - "iopub.status.busy": "2026-11-17T05:27:22.355975Z", - "iopub.status.idle": "2026-11-17T05:27:22.389392Z", - "shell.execute_reply": "2026-11-17T05:27:22.388196Z" + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "PCA coordinates: on GPU: True, CubeCL-backed: False\n" + ] } - }, - "outputs": [], - "source": [ - "training_rows = np.arange(0, sample_count, 2)\n", - "test_rows = np.arange(1, sample_count, 2)\n", - "training = bed[training_rows, :].read(dtype=\"float32\", xp=cp)\n", - "_, fitted_unit = training.standardize(Unit(), return_trained=True)\n", - "test = bed[test_rows, :].read(dtype=\"float32\", xp=cp).standardize(fitted_unit)\n", - "assert isinstance(test.val, cp.ndarray) and isinstance(fitted_unit.stats, np.ndarray)\n", - "\n", - "# An independent application of the stored moments, not a fit on test rows.\n", - "means, deviations = fitted_unit.stats.T\n", - "expected_test = (snp_values[test_rows].astype(np.float64) - means) / deviations\n", - "expected_test[np.isnan(snp_values[test_rows])] = 0\n", - "float32_tolerance = 32 * np.finfo(np.float32).eps\n", - "np.testing.assert_allclose(cp.asnumpy(test.val), expected_test,\n", - " rtol=float32_tolerance, atol=float32_tolerance)\n", - "reordered = bed[test_rows, [5, 3, 0]].read(dtype=\"float32\", xp=cp).standardize(fitted_unit)\n", - "np.testing.assert_array_equal(cp.asnumpy(reordered.val), cp.asnumpy(test.val)[:, [5, 3, 0]])\n", - "print(\"Stored moments:\", fitted_unit.stats.shape, fitted_unit.stats.dtype)\n", - "\n", - "# Reuse GPU-trained float32 moments on a CPU float64/F-order target.\n", - "host_test = bed[test_rows, :].read(dtype=\"float64\", order=\"F\", xp=np).standardize(fitted_unit)\n", - "assert isinstance(host_test.val, np.ndarray) and host_test.val.flags.f_contiguous\n", - "np.testing.assert_allclose(host_test.val, expected_test,\n", - " rtol=8 * np.finfo(np.float64).eps,\n", - " atol=8 * np.finfo(np.float64).eps)" - ] - }, - { - "cell_type": "markdown", - "id": "2a1df512", - "metadata": {}, + ], "source": [ - "## Build kernels in SNP blocks, reusing Beta training statistics\n", - "\n", - "A kernel is `Z @ Z.T`, where `Z` contains standardized SNP values. Native BED kernel construction reads and standardizes on the GPU. A positive integer `block_size` bounds each SNP block, **not the dense sample-by-sample kernel or all temporary allocations**. It is not an out-of-core eigensolver.\n", - "\n", - "We train Beta on one cohort and build the held-out kernel with those exact moments. PySnpTools validates the complete SNP order before using the matching trained statistics for each block. We also compare with an independent float64 product, explicitly allowing float32 accumulation roundoff: 64 epsilons relative, and 64 epsilons times the reference absolute-product scale for the absolute error." + "# 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": null, - "id": "79fd8736", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:22.390943Z", - "iopub.status.busy": "2026-11-17T05:27:22.390804Z", - "iopub.status.idle": "2026-11-17T05:27:22.558631Z", - "shell.execute_reply": "2026-11-17T05:27:22.557264Z" - } - }, - "outputs": [], - "source": [ - "beta_training = bed[training_rows, :].read(dtype=\"float32\", xp=cp)\n", - "_, fitted_beta = beta_training.standardize(Beta(2, 3), return_trained=True)\n", - "means, deviations = fitted_beta.stats.T\n", - "frequency = np.minimum(means.astype(np.float64) / 2, 1 - means.astype(np.float64) / 2)\n", - "weights = 12 * frequency * (1 - frequency) ** 2\n", - "weights[np.isinf(deviations)] = 0\n", - "expected_beta = (snp_values[test_rows].astype(np.float64) - means) * weights\n", - "expected_beta[np.isnan(snp_values[test_rows])] = 0\n", - "expected_kernel = expected_beta @ expected_beta.T\n", - "absolute_product_scale = np.max(np.abs(expected_beta) @ np.abs(expected_beta).T)\n", - "kernel_tolerance = 64 * np.finfo(np.float32).eps\n", - "\n", - "beta_kernel = bed[test_rows, :].read_kernel(\n", - " fitted_beta, block_size=37, dtype=\"float32\", order=\"C\", xp=cp)\n", - "assert isinstance(beta_kernel.val, cp.ndarray) and beta_kernel.val.flags.c_contiguous\n", - "np.testing.assert_allclose(cp.asnumpy(beta_kernel.val), expected_kernel,\n", - " rtol=kernel_tolerance,\n", - " atol=kernel_tolerance * absolute_product_scale)\n", - "unit_kernel = bed.read_kernel(Unit(), block_size=37, dtype=\"float64\", order=\"F\", xp=cp)\n", - "expected_unit, _ = reference(snp_values)\n", - "np.testing.assert_allclose(cp.asnumpy(unit_kernel.val), expected_unit @ expected_unit.T,\n", - " rtol=64 * np.finfo(np.float64).eps,\n", - " atol=64 * np.finfo(np.float64).eps * snp_count)\n", - "print(\"Beta test kernel:\", beta_kernel.val.shape, beta_kernel.val.dtype)\n", - "print(\"Unit full-cohort kernel:\", unit_kernel.val.shape, unit_kernel.val.dtype)" - ] - }, - { - "cell_type": "markdown", - "id": "605d368a", + "execution_count": 18, + "id": "2ad8875c", "metadata": {}, - "source": [ - "## Normalize and perform PCA on the GPU\n", - "\n", - "`DiagKtoN` scales the whole kernel to have average diagonal one; Unit standardization alone does not promise that after missing-value imputation. Use a finite, positive-trace kernel. Normalization and the eigendecomposition operate on CuPy arrays. Only the two plotting coordinates and a few eigenvalues are copied back.\n", - "\n", - "The plot shows the toy samples without assigning population labels; it is a demonstration, not a biological finding. Eigenvector signs are arbitrary; the sign of an axis can change between valid runs." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "8fc1345b", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:22.560506Z", - "iopub.status.busy": "2026-11-17T05:27:22.560347Z", - "iopub.status.idle": "2026-11-17T05:27:22.891710Z", - "shell.execute_reply": "2026-11-17T05:27:22.890688Z" + "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" } - }, - "outputs": [], + ], "source": [ - "from pysnptools.standardizer import DiagKtoN\n", + "import matplotlib.pyplot as plt\n", "\n", - "unit_kernel.standardize(DiagKtoN())\n", - "trace = float(cp.trace(unit_kernel.val))\n", - "np.testing.assert_allclose(trace, sample_count, rtol=64 * np.finfo(np.float64).eps, atol=0)\n", - "eigenvalues, eigenvectors = cp.linalg.eigh(unit_kernel.val)\n", - "# Check the two eigenpairs before copying their small plotting coordinates.\n", - "residual = unit_kernel.val @ eigenvectors[:, -2:] - eigenvectors[:, -2:] * eigenvalues[-2:]\n", - "relative_residual = float(cp.linalg.norm(residual) / cp.linalg.norm(unit_kernel.val))\n", - "assert relative_residual < 1e-12 # float64 eigensolver, small well-scaled matrix\n", - "coordinates = cp.asnumpy(eigenvectors[:, [-1, -2]] * cp.sqrt(eigenvalues[[-1, -2]]))\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[:, 0], coordinates[:, 1])\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", - "print(\"Largest eigenvalues:\", cp.asnumpy(eigenvalues[-3:][::-1]))" + "# Eigenvector signs are arbitrary; the plot may be reflected on another run.\n" ] }, { "cell_type": "markdown", - "id": "bc8618f3", + "id": "6a4e27f4", "metadata": {}, "source": [ - "## Time completed work\n", - "\n", - "CuPy launches are asynchronous. Synchronize before and after a wall-clock measurement so the interval includes completed work. Warm up the exact operation first; this excludes first-use compilation from the reported time. This measures a complete local-file read/standardize/kernel pipeline, including host work and synchronization. It is not isolated kernel time or a claim that this small example is faster than the CPU.\n", - "\n", - "Use representative data and repeated measurements for a performance study. Native decoding and CuPy may use different streams; device-wide synchronization covers both." + "## Compare kernel creation times\n" ] }, { "cell_type": "code", - "execution_count": null, - "id": "a4b2cf69", - "metadata": { - "execution": { - "iopub.execute_input": "2026-11-17T05:27:22.893354Z", - "iopub.status.busy": "2026-11-17T05:27:22.893181Z", - "iopub.status.idle": "2026-11-17T05:27:22.984297Z", - "shell.execute_reply": "2026-11-17T05:27:22.983498Z" - } - }, - "outputs": [], - "source": [ - "def timed_kernel_read():\n", - " return bed.read_kernel(Unit(), block_size=37, dtype=\"float32\", xp=cp)\n", - "\n", - "warmup = timed_kernel_read()\n", - "cp.cuda.runtime.deviceSynchronize()\n", - "del warmup\n", - "elapsed = []\n", - "for repetition in range(3):\n", - " cp.cuda.runtime.deviceSynchronize()\n", - " started = perf_counter()\n", - " measured_kernel = timed_kernel_read()\n", - " cp.cuda.runtime.deviceSynchronize()\n", - " elapsed.append(perf_counter() - started)\n", - " assert isinstance(measured_kernel.val, cp.ndarray)\n", - " del measured_kernel\n", - "print(f\"Completed GPU pipeline, median of 3 warm runs: {np.median(elapsed) * 1000:.2f} ms\")" - ] - }, - { - "cell_type": "markdown", - "id": "27d75937", + "execution_count": 29, + "id": "a074e0b3", "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Kernel creation: Unit standardization + matrix multiplication (including input reset)\n", + "Backend ms/kernel Speedup vs CPU On GPU CubeCL input\n", + "np 26.97 1.0x no no\n", + "cp-basic 4.26 6.3x yes no\n", + "cp-cubecl 1.69 16.0x yes yes\n", + "Whole timing cell: 1.90 s\n" + ] + } + ], "source": [ - "The same explicit-backend and trained-statistics choices carry into FaST-LMM association workflows; see its GPU guide for worker execution and backend selection. This notebook stops at PySnpTools' public kernel API.\n", + "# High-resolution elapsed-time clock, used only for this benchmark.\n", + "from time import perf_counter\n", "\n", - "CPU reads remain available with `xp=np`. Integer BED reads are supported with the documented opt-in, but int8 standardization is rejected; read or convert to float32/float64 first. Other file formats may read on the CPU and then transfer. GPU availability errors are not silently retried on the CPU.\n", + "import numpy as np\n", + "from pysnptools.snpreader import SnpData\n", + "from pysnptools.standardizer import Identity\n", "\n", - "The downloaded sample files stay cached for reuse. Device arrays own their decoded data. Dropping arrays releases ownership, but allocation pools can retain memory for reuse; deleting a name is not a guarantee that another GPU library immediately receives that memory." + "# Compare Unit standardization + Z @ Z.T, using identical float32/F-order data.\n", + "# File reads and case setup are outside the timings; restoring inputs is included.\n", + "cell_started = perf_counter()\n", + "cpu = bed.read(dtype=\"float32\", 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(dtype=\"float32\", 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(dtype=\"float32\", 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(), dtype=\"float32\", 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" ] } ], diff --git a/doc/source/gpu.rst b/doc/source/gpu.rst index 9b56a2e..a754513 100644 --- a/doc/source/gpu.rst +++ b/doc/source/gpu.rst @@ -7,6 +7,11 @@ required; installing the published packages does not necessarily provide these features. NumPy runs on the CPU. CuPy support here is experimental CUDA support; Python HIP support is not implemented. +The :download:`GPU workflow notebook <../ipynb/gpu_workflow.ipynb>` +combines local BED reads, fractional dosages, trained standardizers, blocked +kernels, and PCA. It creates its own data and checks results against independent +NumPy calculations. + Backend, dtype, and order ------------------------- @@ -16,6 +21,20 @@ 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. +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`` with older dependencies). +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; +reads otherwise default to 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 @@ -31,7 +50,8 @@ hardware availability. There is no automatic CPU retry after a GPU error. * - ``SnpReader.read``, ``KernelReader.read`` - ``xp=None``, ``dtype=np.float64``, ``order="F"`` - Return ``SnpData`` or ``KernelData``. Every read chooses its backend - independently of the constructor and its requested output dtype. + independently of the constructor. The read's dtype default is float64, + even when the source stores float32; pass ``dtype="float32"`` to keep it. * - ``SnpReader.read_kernel`` - ``standardizer=None``, ``block_size=None``, ``order="A"`` - A standardizer is required despite the ``None`` signature default; @@ -62,6 +82,25 @@ 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. +CubeCL and CuPy cache allocations in separate pools. After dropping arrays and +their views, ``bed_reader.gpu_memory_cleanup()`` releases unused native storage +for other GPU libraries; it preserves live arrays and does not clear CuPy's pool. + 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:: @@ -107,12 +146,23 @@ 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 @@ -225,9 +275,12 @@ Native GPU BED reads and kernel construction -------------------------------------------- GPU BED decoding requires the matching bed-reader Python extension built with -``cubecl-cuda``, CuPy, a working CUDA driver, and a supported NVIDIA GPU. +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. @@ -282,9 +335,17 @@ read/standardize operation; callers use the public read methods:: ``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. The requested positive integer +``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. It is not a total memory budget. The dense kernel, +``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 diff --git a/doc/source/index.rst b/doc/source/index.rst index c9e206d..24a6634 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -55,6 +55,7 @@ options, exceptions, and complete examples. * 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 diff --git a/pysnptools/kernelreader/kerneldata.py b/pysnptools/kernelreader/kerneldata.py index 4765aed..14375c3 100644 --- a/pysnptools/kernelreader/kerneldata.py +++ b/pysnptools/kernelreader/kerneldata.py @@ -17,12 +17,14 @@ class KernelData(KernelReader, PstData): 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'. An explicit choice overrides ARRAY_MODULE; @@ -130,7 +132,7 @@ def __init__( val, row_count=len(self._row), col_count=len(self._col), - empty_creator=lambda row_count, col_count: xp.empty( + empty_creator=lambda row_count, col_count: np.empty( [row_count, col_count], dtype=xp.float64 ), xp=xp, @@ -193,6 +195,8 @@ def standardize( """Does in-place standardization of the in-memory 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(). diff --git a/pysnptools/kernelreader/kernelreader.py b/pysnptools/kernelreader/kernelreader.py index 84c9474..5b61861 100644 --- a/pysnptools/kernelreader/kernelreader.py +++ b/pysnptools/kernelreader/kernelreader.py @@ -127,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. + By default :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 @@ -251,7 +254,7 @@ def read( 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). @@ -290,7 +293,8 @@ def read( :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 rows or columns, (to the degree practical) only that subset will be read from disk. @@ -337,7 +341,8 @@ def _read_array(self, row_index, col_index, order, dtype, return val if xp is np: val = pstutil.asnumpy(val) - return xp.asarray(val, dtype=dtype, order=order) + from pysnptools.util._array import asarray + return asarray(val, dtype=dtype, order=order, xp=xp) def iid_to_index(self, list): """Takes a list of iids and returns a list of index numbers. diff --git a/pysnptools/kernelreader/snpkernel.py b/pysnptools/kernelreader/snpkernel.py index c364f05..ea59b6e 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 @@ -21,7 +22,7 @@ class SnpKernel(KernelReader): **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. @@ -46,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 @@ -208,6 +215,9 @@ def read_snps( ): """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). @@ -218,26 +228,32 @@ def read_snps( :param dtype: {numpy.float64 (default), numpy.float32}, optional -- The data-type for the :attr:`SnpData.val` ndarray. :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_with_standardizing( 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 d5746b9..2afaf72 100644 --- a/pysnptools/pstreader/pstdata.py +++ b/pysnptools/pstreader/pstdata.py @@ -17,6 +17,7 @@ def _default_empty_creator_val(row_count, col_count): 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, and for anything else (for example, a list), it becomes float64. @@ -24,16 +25,16 @@ 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 xp.array(input, dtype=xp.float64) + return input if keeps_dtype(input) else asarray(input, dtype=np.float64, 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 np.float64 if xp is np: input = pstutil.asnumpy(input) # cupy forbids implicit conversion to numpy - return xp.array(input, dtype=dtype) # other module (always copies) + return asarray(input, dtype=dtype, order="K", xp=xp, copy=True) - return xp.array(input, dtype=np.float64) # not an array + return asarray(input, dtype=np.float64, order="K", xp=xp) class PstData(PstReader): @@ -205,7 +206,9 @@ 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) + 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) @@ -293,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, @@ -303,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/snpreader/bed.py b/pysnptools/snpreader/bed.py index 41e63fd..40d62ed 100644 --- a/pysnptools/snpreader/bed.py +++ b/pysnptools/snpreader/bed.py @@ -378,8 +378,13 @@ def _read_with_standardizing(self, standardizer, order="F", dtype=np.float64, # 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=xp.asarray(owner), xp=xp, name=str(metadata)) + 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)) diff --git a/pysnptools/snpreader/snpdata.py b/pysnptools/snpreader/snpdata.py index f97ecd4..53dd4c7 100644 --- a/pysnptools/snpreader/snpdata.py +++ b/pysnptools/snpreader/snpdata.py @@ -18,6 +18,9 @@ class SnpData(PstData, SnpReader): 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 normally become 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. @@ -199,8 +202,8 @@ def standardize( 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: Deprecated and ignored; this wrapper does not forward it. @@ -276,7 +279,14 @@ def _read_kernel( 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._array import empty + K = empty((train.iid_count, train.iid_count), dtype=dtype, + order="F" if order == "F" else "C", xp=xp) + # 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) diff --git a/pysnptools/snpreader/snpreader.py b/pysnptools/snpreader/snpreader.py index 099cd82..2494c1d 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. @@ -271,7 +271,8 @@ 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, + By default :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. @@ -436,7 +437,7 @@ def read( _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). @@ -477,7 +478,8 @@ def read( :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 rows or columns, (to the degree practical) only that subset will be read from disk. @@ -533,7 +535,8 @@ def _read_array(self, row_index, col_index, order, dtype, return val if xp is np: val = pstutil.asnumpy(val) - return xp.asarray(val, dtype=dtype, order=order) + from pysnptools.util._array import asarray + return asarray(val, dtype=dtype, order=order, xp=xp) def _read_with_standardizing(self, standardizer, order="F", dtype=np.float64, xp=None, return_trained=False, @@ -615,6 +618,7 @@ def read_kernel( :type standardizer: :class:`.Standardizer` :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 @@ -817,7 +821,8 @@ def _read_kernel( if order == "A": order = "C" t0 = time.time() - K = xp.zeros([self.iid_count, self.iid_count], dtype=dtype, order=order) + from pysnptools.util._array import zeros + K = zeros((self.iid_count, self.iid_count), dtype=dtype, order=order, xp=xp) 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__}." diff --git a/pysnptools/standardizer/_cupy.py b/pysnptools/standardizer/_cupy.py index 3882a22..e28ad52 100644 --- a/pysnptools/standardizer/_cupy.py +++ b/pysnptools/standardizer/_cupy.py @@ -2,6 +2,16 @@ 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 diff --git a/pysnptools/standardizer/diag_K_to_N.py b/pysnptools/standardizer/diag_K_to_N.py index 79ce067..76b0a3b 100644 --- a/pysnptools/standardizer/diag_K_to_N.py +++ b/pysnptools/standardizer/diag_K_to_N.py @@ -7,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. @@ -24,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 @@ -65,8 +71,9 @@ def _standardize_kernel( num_threads=None, ): xp = pstutil.get_array_module(kerneldata.val) - factor = (float(kerneldata.iid_count) / np.diag(kerneldata.val).sum() - if xp is np else float(kerneldata.iid_count) / float(xp.diag(kerneldata.val).sum(dtype=np.float64))) + 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 @@ -126,10 +133,9 @@ def _standardize_snps( if xp is np: squared_sum = vec.dot(vec) else: - from pysnptools.standardizer._cupy import kernels - # The centered reduction with mean zero is a sum of squares. - squared_sum = float(kernels()[2](vec, xp.asarray(0.0, dtype=np.float64))) - factor = float(val.shape[0]) / squared_sum + 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) @@ -145,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. """ @@ -236,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 4b5334c..7de78e1 100644 --- a/pysnptools/standardizer/standardizer.py +++ b/pysnptools/standardizer/standardizer.py @@ -136,6 +136,14 @@ def _standardize_unit_and_beta( ), "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) @@ -149,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, diff --git a/pysnptools/test.py b/pysnptools/test.py index d0c89fd..c6e8914 100644 --- a/pysnptools/test.py +++ b/pysnptools/test.py @@ -39,6 +39,55 @@ 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) @@ -187,6 +236,68 @@ def test_constant_columns(self): 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" @@ -1718,6 +1829,7 @@ 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)) diff --git a/pysnptools/test_gpu_allocator.py b/pysnptools/test_gpu_allocator.py new file mode 100644 index 0000000..b8aeb3f --- /dev/null +++ b/pysnptools/test_gpu_allocator.py @@ -0,0 +1,262 @@ +"""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 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 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_reads_and_kernel_outputs_are_native(cupy, order): + from bed_reader._gpu import _native_owner + + 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 _native_owner(kernel.val) is not None + 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) + assert _native_owner(host.read(xp=cupy).val) is not None + + +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, "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, "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_precision_warning.py b/pysnptools/test_gpu_precision_warning.py new file mode 100644 index 0000000..0fc04d8 --- /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 = getattr(bed_reader, "GpuFloat64Warning", UserWarning) + + +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/util/__init__.py b/pysnptools/util/__init__.py index 76e2bfb..a62ddee 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -439,6 +439,21 @@ def _sub_matrix_cupy(cp, val, row_index_list, col_index_list, effective_order, d 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) diff --git a/pysnptools/util/_array.py b/pysnptools/util/_array.py new file mode 100644 index 0000000..de428e4 --- /dev/null +++ b/pysnptools/util/_array.py @@ -0,0 +1,86 @@ +"""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: + import bed_reader + from bed_reader import bed_reader as native + + allocator = getattr(bed_reader, "empty_gpu", None) + if (allocator is not None and 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 allocator + 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): + # Older bed-reader releases and 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 + import bed_reader + + if not hasattr(bed_reader, "empty_gpu"): + 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..045bf52 --- /dev/null +++ b/pysnptools/util/_gpu_warnings.py @@ -0,0 +1,24 @@ +"""GPU precision notices, including compatibility with older bed-reader builds.""" + +import warnings + +import numpy as np + + +def warn_gpu_float64(dtype, xp): + if xp is np or np.dtype(dtype) != np.dtype("float64"): + return + import bed_reader + + warn = getattr(bed_reader, "_warn_gpu_float64", None) + if warn is not None: + warn(dtype) + else: + # CuPy-only use remains supported with older published bed-reader builds. + warnings.warn( + "float64 arithmetic can be much slower than float32 on consumer GPUs. Float64 GPU arrays " + "also use twice the storage. Consider float32 where its precision is sufficient; " + "the requested dtype is unchanged.", + getattr(bed_reader, "GpuFloat64Warning", UserWarning), + stacklevel=2, + ) 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. From e99633fd37a114d0e3786422990a1c4340db39d1 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Tue, 17 Nov 2026 13:57:21 -0800 Subject: [PATCH 14/21] Update BGEN tests for sample paths returned by bgen-reader --- pysnptools/distreader/bgen.py | 134 +++++++++++++++++----------------- 1 file changed, 67 insertions(+), 67 deletions(-) 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" From cab478191c0c26953bdbaaabf8c7cfa4c60bb634 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Tue, 17 Nov 2026 13:57:21 -0800 Subject: [PATCH 15/21] Honor ARRAY_DTYPE across reads, kernels, and GPU workflows --- CHANGELOG.md | 7 ++ README.md | 1 + doc/ipynb/gpu_workflow.ipynb | 77 +++++---------- doc/source/gpu.rst | 43 +++++++-- doc/source/index.rst | 5 +- pysnptools/distreader/distdata.py | 5 +- pysnptools/distreader/distreader.py | 10 +- pysnptools/kernelreader/kerneldata.py | 4 +- pysnptools/kernelreader/kernelreader.py | 12 ++- pysnptools/kernelreader/snpkernel.py | 10 +- pysnptools/pstreader/pstdata.py | 8 +- pysnptools/pstreader/pstreader.py | 13 +-- pysnptools/snpreader/bed.py | 3 +- pysnptools/snpreader/dat.py | 4 +- pysnptools/snpreader/dense.py | 3 +- pysnptools/snpreader/ped.py | 2 +- pysnptools/snpreader/pheno.py | 2 +- pysnptools/snpreader/snpdata.py | 10 +- pysnptools/snpreader/snpreader.py | 25 ++--- pysnptools/test_array_dtype.py | 120 ++++++++++++++++++++++++ pysnptools/util/__init__.py | 7 +- pysnptools/util/_precision.py | 30 ++++++ pysnptools/util/test.py | 18 +++- 23 files changed, 299 insertions(+), 120 deletions(-) create mode 100644 pysnptools/test_array_dtype.py create mode 100644 pysnptools/util/_precision.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 45085f4..027913c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +* 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. diff --git a/README.md b/README.md index e87650a..0e32f6c 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Main Features: 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](doc/source/gpu.rst) and [workflow notebook](doc/ipynb/gpu_workflow.ipynb). Requires matching development packages and a CUDA-enabled bed-reader for native GPU BED reads. diff --git a/doc/ipynb/gpu_workflow.ipynb b/doc/ipynb/gpu_workflow.ipynb index d9587f1..e495a80 100644 --- a/doc/ipynb/gpu_workflow.ipynb +++ b/doc/ipynb/gpu_workflow.ipynb @@ -14,19 +14,16 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": null, "id": "717f705d", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "GPU: NVIDIA GeForce RTX 3060\n" - ] - } - ], + "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", @@ -79,25 +76,17 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": null, "id": "1ebfb0bb", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " (500, 10000) float32\n", - "SNP values: on GPU: True, CubeCL-backed: True\n" - ] - } - ], + "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", - "snps = bed.read(dtype=\"float32\", xp=cp)\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", @@ -114,26 +103,17 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": null, "id": "afc8d995", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " (500, 500) float32\n", - "Kernel: on GPU: True, CubeCL-backed: True\n" - ] - } - ], + "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. Keep float32 explicitly: the default is float64.\n", - "kernel = snps.read_kernel(Unit(), dtype=\"float32\", xp=cp)\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" @@ -221,23 +201,10 @@ }, { "cell_type": "code", - "execution_count": 29, + "execution_count": null, "id": "a074e0b3", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Kernel creation: Unit standardization + matrix multiplication (including input reset)\n", - "Backend ms/kernel Speedup vs CPU On GPU CubeCL input\n", - "np 26.97 1.0x no no\n", - "cp-basic 4.26 6.3x yes no\n", - "cp-cubecl 1.69 16.0x yes yes\n", - "Whole timing cell: 1.90 s\n" - ] - } - ], + "outputs": [], "source": [ "# High-resolution elapsed-time clock, used only for this benchmark.\n", "from time import perf_counter\n", @@ -246,20 +213,20 @@ "from pysnptools.snpreader import SnpData\n", "from pysnptools.standardizer import Identity\n", "\n", - "# Compare Unit standardization + Z @ Z.T, using identical float32/F-order data.\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(dtype=\"float32\", xp=np)\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(dtype=\"float32\", xp=np)),\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(dtype=\"float32\", xp=cp)),\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", @@ -274,7 +241,7 @@ " 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(), dtype=\"float32\", xp=xp)\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", diff --git a/doc/source/gpu.rst b/doc/source/gpu.rst index a754513..9e7a28f 100644 --- a/doc/source/gpu.rst +++ b/doc/source/gpu.rst @@ -21,6 +21,35 @@ 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 new policy requires matching development versions of bed-reader +and PySnpTools; 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 @@ -30,7 +59,7 @@ 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; -reads otherwise default to float64 even for float32 in-memory sources. Keep +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. @@ -46,17 +75,17 @@ do not emit this warning. Float32 storage does not remove every float64 operatio - ``xp=None`` - Selects the module for values; metadata remains NumPy. Float32/float64 inputs keep their dtype across transfers. Lists and integers normally - become float64. Same-module floating arrays can share storage. + use ARRAY_DTYPE, then float64. Same-module floating arrays can share storage. * - ``SnpReader.read``, ``KernelReader.read`` - - ``xp=None``, ``dtype=np.float64``, ``order="F"`` + - ``xp=None``, ``dtype=None``, ``order="F"`` - Return ``SnpData`` or ``KernelData``. Every read chooses its backend - independently of the constructor. The read's dtype default is float64, - even when the source stores float32; pass ``dtype="float32"`` to keep it. + 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``. - Output dtype defaults to float64; ``xp=None`` uses the environment. + 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 @@ -137,7 +166,7 @@ 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`` defaults to float64: pass ``dtype=values.dtype`` to keep float32. +``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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 24a6634..0d57f91 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,7 +15,8 @@ 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; see :doc:`gpu` for prerequisites, +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: @@ -567,6 +568,8 @@ options, exceptions, and complete examples. :undoc-members: :show-inheritance: +.. autofunction:: pysnptools.util.array_dtype + .. autofunction:: pysnptools.util.example_file .. autofunction:: pysnptools.util.snp_gen 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/kerneldata.py b/pysnptools/kernelreader/kerneldata.py index 14375c3..a0a028b 100644 --- a/pysnptools/kernelreader/kerneldata.py +++ b/pysnptools/kernelreader/kerneldata.py @@ -133,7 +133,7 @@ def __init__( row_count=len(self._row), col_count=len(self._col), empty_creator=lambda row_count, col_count: np.empty( - [row_count, col_count], dtype=xp.float64 + [row_count, col_count], dtype=pstutil.array_dtype() ), xp=xp, ) @@ -160,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, ) diff --git a/pysnptools/kernelreader/kernelreader.py b/pysnptools/kernelreader/kernelreader.py index 5b61861..e9613bf 100644 --- a/pysnptools/kernelreader/kernelreader.py +++ b/pysnptools/kernelreader/kernelreader.py @@ -127,7 +127,7 @@ class KernelReader(PstReader): The :meth:`read` Method - By default :meth:`read` returns :class:`.KernelData` with a float64 values array + 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 @@ -248,7 +248,7 @@ def col_property(self): def read( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, @@ -263,7 +263,8 @@ def read( ndarray may be in any order (either C-, Fortran-contiguous, or even discontiguous). :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 @@ -314,7 +315,7 @@ 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) + 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 @@ -417,13 +418,14 @@ def _read_with_standardizing( snp_standardizer=None, kernel_standardizer=DiagKtoN(), return_trained=False, - dtype=np.float64, + dtype=None, xp=None, num_threads=None, ): assert ( to_kerneldata ), "When working with non-SnpKernels, to_kerneldata must be '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 ) diff --git a/pysnptools/kernelreader/snpkernel.py b/pysnptools/kernelreader/snpkernel.py index ea59b6e..dd053ae 100644 --- a/pysnptools/kernelreader/snpkernel.py +++ b/pysnptools/kernelreader/snpkernel.py @@ -143,7 +143,7 @@ def _read_with_standardizing( kernel_standardizer=DiagKtoN(), return_trained=False, num_threads=None, - dtype=np.float64, + dtype=None, xp=None, ): """ @@ -159,6 +159,7 @@ def _read_with_standardizing( """ logging.info("Starting '_read_with_standardizing'") xp = pstutil.array_module(xp) + dtype = pstutil.array_dtype(dtype) if to_kerneldata: val, snp_trained = self.snpreader._read_kernel( @@ -207,7 +208,7 @@ def pos(self): def read_snps( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, @@ -225,7 +226,8 @@ 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: Request a Python CPU path where supported. @@ -255,7 +257,7 @@ def read_snps( >>> standardized.val.tolist() [[-1.0], [1.0]] """ - dtype = np.dtype(dtype) + 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) diff --git a/pysnptools/pstreader/pstdata.py b/pysnptools/pstreader/pstdata.py index 2afaf72..4fdebf1 100644 --- a/pysnptools/pstreader/pstdata.py +++ b/pysnptools/pstreader/pstdata.py @@ -20,21 +20,21 @@ 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, and for anything else (for example, a list), it becomes float64. + # 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=np.float64, order="K", xp=xp) + 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 np.float64 + 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=np.float64, order="K", xp=xp) + return asarray(input, dtype=pstutil.array_dtype(), order="K", xp=xp) class PstData(PstReader): 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/bed.py b/pysnptools/snpreader/bed.py index 40d62ed..7d2d77d 100644 --- a/pysnptools/snpreader/bed.py +++ b/pysnptools/snpreader/bed.py @@ -352,7 +352,7 @@ def _read_array(self, row_index, col_index, order, 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=np.float64, + 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): @@ -361,6 +361,7 @@ def _read_with_standardizing(self, standardizer, order="F", dtype=np.float64, 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, 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 53dd4c7..e6903b9 100644 --- a/pysnptools/snpreader/snpdata.py +++ b/pysnptools/snpreader/snpdata.py @@ -17,7 +17,7 @@ class SnpData(PstData, SnpReader): 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 normally become float64. + 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. @@ -106,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, ) @@ -134,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) @@ -257,7 +257,7 @@ def _read_kernel( standardizer, block_size=None, order="A", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, return_trained=False, @@ -270,7 +270,7 @@ 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 diff --git a/pysnptools/snpreader/snpreader.py b/pysnptools/snpreader/snpreader.py index 2494c1d..0617087 100644 --- a/pysnptools/snpreader/snpreader.py +++ b/pysnptools/snpreader/snpreader.py @@ -271,7 +271,7 @@ class SnpReader(PstReader): The :meth:`read` Method - By default :meth:`read` returns :class:`.SnpData` with a float64 values array + 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 @@ -430,7 +430,7 @@ def _read( def read( self, order="F", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, num_threads=None, @@ -446,9 +446,10 @@ def read( ndarray may be in any order (either C-, Fortran-contiguous). :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 @@ -499,7 +500,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) xp = pstutil.array_module(xp) val = self._read_array( None, None, order, dtype, force_python_only, view_ok, num_threads, xp @@ -538,11 +539,12 @@ def _read_array(self, row_index, col_index, order, dtype, from pysnptools.util._array import asarray return asarray(val, dtype=dtype, order=order, xp=xp) - def _read_with_standardizing(self, standardizer, order="F", dtype=np.float64, + 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( @@ -602,7 +604,7 @@ 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, @@ -626,7 +628,8 @@ def read_kernel( :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 (default) or float32. GPU + :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. @@ -664,7 +667,7 @@ 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 @@ -738,7 +741,7 @@ def _as_snpdata( """ 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 ( @@ -763,7 +766,7 @@ def _read_kernel( standardizer, block_size=None, order="A", - dtype=np.float64, + dtype=None, force_python_only=False, view_ok=False, return_trained=False, @@ -773,7 +776,7 @@ def _read_kernel( """ Will respect the cupy environment variable. """ - dtype = np.dtype(dtype) + 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. diff --git a/pysnptools/test_array_dtype.py b/pysnptools/test_array_dtype.py new file mode 100644 index 0000000..82f2caf --- /dev/null +++ b/pysnptools/test_array_dtype.py @@ -0,0 +1,120 @@ +"""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_legacy_dependency_and_invalid_configuration(monkeypatch): + monkeypatch.delenv("ARRAY_DTYPE", raising=False) + assert array_dtype() == np.float64 + monkeypatch.delattr(bed_reader, "array_dtype") + assert array_dtype() == np.float64 + assert array_dtype("float32") == np.float32 + monkeypatch.setenv("ARRAY_DTYPE", "float32") + with pytest.raises(RuntimeError, match="bed-reader"): + 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, "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/util/__init__.py b/pysnptools/util/__init__.py index a62ddee..5de5891 100644 --- a/pysnptools/util/__init__.py +++ b/pysnptools/util/__init__.py @@ -1,6 +1,7 @@ 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 @@ -276,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. @@ -325,7 +326,7 @@ def sub_matrix( 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; the default output dtype is float64. See :doc:`/gpu` for GPU examples. + float32; omitted dtype uses ARRAY_DTYPE, then float64. See :doc:`/gpu` for GPU examples. """ if order == "A": @@ -335,7 +336,7 @@ 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. diff --git a/pysnptools/util/_precision.py b/pysnptools/util/_precision.py new file mode 100644 index 0000000..05a69b5 --- /dev/null +++ b/pysnptools/util/_precision.py @@ -0,0 +1,30 @@ +"""Precision defaults shared with bed-reader without breaking older CPU installs.""" +import os + +import bed_reader +import numpy as np + + +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 + """ + resolver = getattr(bed_reader, "array_dtype", None) + if resolver is not None: + return resolver(dtype) + # Supported older bed-reader releases lack this new optional policy. Keep + # their legacy defaults/explicit arguments working; never ignore a requested + # environment policy that the installed dependency cannot implement. + if dtype is None and "ARRAY_DTYPE" in os.environ: + raise RuntimeError("ARRAY_DTYPE requires bed-reader with array_dtype support") + return np.dtype("float64" if dtype is None else dtype) diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index c1ed926..dbbc1f7 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -190,7 +190,7 @@ 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, [str(warning.message) for warning in caught] + return result, caught rng = np.random.default_rng(0) row_index_list = [0, 2, 11, 2] @@ -203,11 +203,21 @@ def sub_matrix_and_warnings(val, out_order, out_dtype): 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 warn exactly when narrowing float64 to float32, and otherwise not at all. + # 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 = getattr(bed_reader, "GpuFloat64Warning", UserWarning) narrowing = in_dtype == np.float64 and out_dtype == np.float32 precision_warning = ["Converting float64 to float32 can cause loss of information"] - assert expected_warnings == (precision_warning if narrowing else []), expected_warnings - assert actual_warnings == expected_warnings, actual_warnings + 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"] From 5ff6a0ee95c3881fef1d77a7e89a0a0da4313f78 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Tue, 17 Nov 2026 19:41:57 -0800 Subject: [PATCH 16/21] Prepare PySnpTools 1.1.0a1 with published GPU dependencies --- .github/workflows/ci.yml | 2 +- .github/workflows/release.yml | 2 +- CHANGELOG.md | 7 +++ README.md | 11 +++- doc/source/gpu.rst | 41 +++++++++++---- pyproject.toml | 5 +- uv.lock | 99 ++++++++++++++++++++++------------- 7 files changed, 115 insertions(+), 52 deletions(-) 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 027913c..7861fd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ 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. diff --git a/README.md b/README.md index 0e32f6c..2d5e511 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ Main Features: * **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](doc/source/gpu.rst) and [workflow notebook](doc/ipynb/gpu_workflow.ipynb). - Requires matching development packages and a CUDA-enabled bed-reader for native GPU BED reads. + 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. @@ -35,6 +35,13 @@ Install Requires Python 3.11.5 or later. Python 3.15 qualification is in progress. +For the experimental GPU alpha, after `1.1.0a1` is published: + + 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/source/gpu.rst b/doc/source/gpu.rst index 9e7a28f..feeb580 100644 --- a/doc/source/gpu.rst +++ b/doc/source/gpu.rst @@ -1,16 +1,37 @@ GPU arrays, readers, and standardization ======================================== -This guide describes the current development implementation, including the -reader GPU API. Matching development versions of PySnpTools and bed-reader are -required; installing the published packages does not necessarily provide these -features. NumPy runs on the CPU. CuPy support here is experimental CUDA support; -Python HIP support is not implemented. +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 +-------------------- + +Publication is pending. After the alpha is published, 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. Native Linux GPU testing remains +outstanding; the Linux wheels have been tested under WSL2. Other CPU platforms +may require building bed-reader from its source distribution until their alpha +wheels are available. 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>` -combines local BED reads, fractional dosages, trained standardizers, blocked -kernels, and PCA. It creates its own data and checks results against independent -NumPy calculations. +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 ------------------------- @@ -46,8 +67,8 @@ Set backend and precision together for a workflow:: # Previous settings are restored, even after an exception. These environment settings are process-wide; use one consistent policy per -process. This new policy requires matching development versions of bed-reader -and PySnpTools; older dependencies retain their original defaults but reject +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 diff --git a/pyproject.toml b/pyproject.toml index 3c5f4ce..bc3e3fc 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,7 @@ 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", + "bed-reader[samples]>=1.3.0a1", "more-itertools>=10.5.0", ] @@ -67,6 +67,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/uv.lock b/uv.lock index cd28fee..daf2566 100644 --- a/uv.lock +++ b/uv.lock @@ -89,47 +89,30 @@ 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/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/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/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/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/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" }, ] [package.optional-dependencies] +cupy = [ + { name = "cupy-cuda13x" }, +] samples = [ { name = "pooch" }, ] @@ -851,6 +834,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 +2467,7 @@ wheels = [ [[package]] name = "pysnptools" -version = "1.0.1" +version = "1.1.0a1" source = { editable = "." } dependencies = [ { name = "bed-reader", extra = ["samples"] }, @@ -2463,6 +2486,9 @@ bgen = [ { name = "bgen-reader" }, { name = "cbgen" }, ] +cupy = [ + { name = "bed-reader", extra = ["cupy"] }, +] dev = [ { name = "limix-sphinx-theme" }, { name = "pytest" }, @@ -2495,7 +2521,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" }, @@ -2527,7 +2554,7 @@ requires-dist = [ { name = "sphinx", marker = "extra == 'dev'", specifier = ">=6.2.1" }, { name = "sphinx-rtd-theme", marker = "extra == 'dev'", specifier = ">=3.0.1" }, ] -provides-extras = ["hdf5", "bgen", "dev"] +provides-extras = ["cupy", "hdf5", "bgen", "dev"] [package.metadata.requires-dev] dev = [ From 8006a8a627c26187c9c40a2bdd8c1c1b348192df Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Tue, 17 Nov 2026 20:58:12 -0800 Subject: [PATCH 17/21] Use published alpha CPU wheels in PySnpTools qualification --- README.md | 2 +- doc/source/gpu.rst | 8 ++++---- uv.lock | 20 ++++++++++++++++++++ 3 files changed, 25 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2d5e511..676830e 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ Install Requires Python 3.11.5 or later. Python 3.15 qualification is in progress. -For the experimental GPU alpha, after `1.1.0a1` is published: +For the experimental GPU alpha: pip install "pysnptools[cupy]==1.1.0a1" diff --git a/doc/source/gpu.rst b/doc/source/gpu.rst index feeb580..be1b217 100644 --- a/doc/source/gpu.rst +++ b/doc/source/gpu.rst @@ -8,7 +8,7 @@ experimental NVIDIA CUDA support; Python HIP support is not implemented. Installing the alpha -------------------- -Publication is pending. After the alpha is published, explicitly select it: +The alpha is available on PyPI. Explicitly select it: .. code-block:: bash @@ -24,9 +24,9 @@ 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. Native Linux GPU testing remains -outstanding; the Linux wheels have been tested under WSL2. Other CPU platforms -may require building bed-reader from its source distribution until their alpha -wheels are available. Normal unpinned installations continue selecting stable +outstanding; the Linux wheels have been tested under WSL2. 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>` diff --git a/uv.lock b/uv.lock index daf2566..ae961a9 100644 --- a/uv.lock +++ b/uv.lock @@ -97,16 +97,36 @@ dependencies = [ ] 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] From f739d82801761885ec67d2ce5f6d4889d599dbde Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Wed, 18 Nov 2026 06:46:08 -0800 Subject: [PATCH 18/21] Record native Linux NVIDIA alpha validation --- doc/source/gpu.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/gpu.rst b/doc/source/gpu.rst index be1b217..4517655 100644 --- a/doc/source/gpu.rst +++ b/doc/source/gpu.rst @@ -23,8 +23,9 @@ Rust or Maturin. See 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. Native Linux GPU testing remains -outstanding; the Linux wheels have been tested under WSL2. CPU wheels also cover +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. From 75652cec21624db4d5fc7720cca94dd162f706b2 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Wed, 18 Nov 2026 06:43:50 -0800 Subject: [PATCH 19/21] Honor num_threads across MKL and OpenBLAS local runners Keep mkl_num_threads as a deprecated alias, preserve positional and pickle compatibility, and scope thread limits to workers and reductions. Cover startup, restoration, failures, and compatibility with regression tests. --- pyproject.toml | 3 + pysnptools/test.py | 2 + pysnptools/util/mapreduce1/runner/_threads.py | 95 ++++++ .../util/mapreduce1/runner/localinparts.py | 31 +- .../util/mapreduce1/runner/localmultiproc.py | 46 ++- pysnptools/util/mapreduce1/test_threads.py | 271 ++++++++++++++++++ uv.lock | 12 + 7 files changed, 430 insertions(+), 30 deletions(-) create mode 100644 pysnptools/util/mapreduce1/runner/_threads.py create mode 100644 pysnptools/util/mapreduce1/test_threads.py diff --git a/pyproject.toml b/pyproject.toml index bc3e3fc..7504f0c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,6 +55,9 @@ dependencies = [ # current binary dependencies separately from the optional-feature lock. "pandas>=2.3.3,<4; python_version >= '3.14'", "cloudpickle>=3.1.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", ] diff --git a/pysnptools/test.py b/pysnptools/test.py index c6e8914..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 @@ -1835,6 +1836,7 @@ def getTestSuite(): 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/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..1efa4b0 --- /dev/null +++ b/pysnptools/util/mapreduce1/test_threads.py @@ -0,0 +1,271 @@ +"""Exercise real loaded BLAS pools and subprocess startup thread limits.""" +import json +import os +import pickle +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.assertTrue(self.before["pools"], "Requires an actual NumPy or SciPy BLAS pool") + + def assertLimited(self, snapshot, count): + self.assertTrue(snapshot["pools"], "No loaded BLAS pools were observed") + 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_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.assertTrue(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/uv.lock b/uv.lock index ae961a9..e3c394c 100644 --- a/uv.lock +++ b/uv.lock @@ -2499,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] @@ -2573,6 +2574,8 @@ 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 = ["cupy", "hdf5", "bgen", "dev"] @@ -3467,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" From 110ef95959329b23c20696d40f29f193d6efb321 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Wed, 18 Nov 2026 19:46:39 -0800 Subject: [PATCH 20/21] Rely on bed-reader's GPU memory handling and use CuPy for kernels Remove fallbacks for bed-reader versions older than the required alpha, import bed-reader's GPU helpers from their internal modules, and drop the manual gpu_memory_cleanup calls now that bed-reader returns memory on drop. Allocate kernel matrices from CuPy's pool, which reuses memory across blocks; only SNP data needs bed-reader allocations for native standardization. --- doc/source/gpu.rst | 7 +++---- pysnptools/kernelreader/kernelreader.py | 6 ++++-- pysnptools/snpreader/snpdata.py | 10 +++++++--- pysnptools/snpreader/snpreader.py | 19 ++++++------------- pysnptools/test_array_dtype.py | 10 ++++------ pysnptools/test_gpu_allocator.py | 19 +++++++++++-------- pysnptools/test_gpu_precision_warning.py | 2 +- pysnptools/util/_array.py | 14 +++++--------- pysnptools/util/_gpu_warnings.py | 19 +++---------------- pysnptools/util/_precision.py | 17 +++-------------- pysnptools/util/test.py | 2 +- 11 files changed, 48 insertions(+), 77 deletions(-) diff --git a/doc/source/gpu.rst b/doc/source/gpu.rst index 4517655..a068daa 100644 --- a/doc/source/gpu.rst +++ b/doc/source/gpu.rst @@ -75,7 +75,7 @@ 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`` with older dependencies). +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. @@ -148,9 +148,8 @@ 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. -CubeCL and CuPy cache allocations in separate pools. After dropping arrays and -their views, ``bed_reader.gpu_memory_cleanup()`` releases unused native storage -for other GPU libraries; it preserves live arrays and does not clear CuPy's pool. +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 diff --git a/pysnptools/kernelreader/kernelreader.py b/pysnptools/kernelreader/kernelreader.py index e9613bf..459aae9 100644 --- a/pysnptools/kernelreader/kernelreader.py +++ b/pysnptools/kernelreader/kernelreader.py @@ -342,8 +342,10 @@ def _read_array(self, row_index, col_index, order, dtype, 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) + # 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. diff --git a/pysnptools/snpreader/snpdata.py b/pysnptools/snpreader/snpdata.py index e6903b9..c78ae8c 100644 --- a/pysnptools/snpreader/snpdata.py +++ b/pysnptools/snpreader/snpdata.py @@ -280,9 +280,13 @@ def _read_kernel( # 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 xp is not np: - from pysnptools.util._array import empty - K = empty((train.iid_count, train.iid_count), dtype=dtype, - order="F" if order == "F" else "C", xp=xp) + 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) diff --git a/pysnptools/snpreader/snpreader.py b/pysnptools/snpreader/snpreader.py index 0617087..83dc005 100644 --- a/pysnptools/snpreader/snpreader.py +++ b/pysnptools/snpreader/snpreader.py @@ -801,13 +801,9 @@ def _read_kernel( ) 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 - # Return CubeCL's unused blocks to the driver before CuPy's - # eigensolver needs its workspace (the libraries have separate pools). - from bed_reader import has_gpu_support - if has_gpu_support(): - from bed_reader.bed_reader import gpu_memory_cleanup - gpu_memory_cleanup() if return_trained: return kernel, trained_standardizer else: @@ -824,8 +820,10 @@ def _read_kernel( if order == "A": order = "C" t0 = time.time() - from pysnptools.util._array import zeros - K = zeros((self.iid_count, self.iid_count), dtype=dtype, order=order, xp=xp) + # 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__}." @@ -874,11 +872,6 @@ def _read_kernel( logging.info(f"read {ct:,} SNPs in {diff:.2f} seconds") diff_last = diff - if xp is not np: - from bed_reader import has_gpu_support - if has_gpu_support(): - from bed_reader.bed_reader import gpu_memory_cleanup - gpu_memory_cleanup() t1 = time.time() logging.info("%.2f seconds elapsed" % (t1 - t0)) diff --git a/pysnptools/test_array_dtype.py b/pysnptools/test_array_dtype.py index 82f2caf..bc0912e 100644 --- a/pysnptools/test_array_dtype.py +++ b/pysnptools/test_array_dtype.py @@ -52,14 +52,12 @@ def test_generic_reader_and_untyped_containers(monkeypatch): assert KernelData(iid=[], val=None).val.dtype == np.float32 -def test_legacy_dependency_and_invalid_configuration(monkeypatch): +def test_default_and_invalid_configuration(monkeypatch): monkeypatch.delenv("ARRAY_DTYPE", raising=False) assert array_dtype() == np.float64 - monkeypatch.delattr(bed_reader, "array_dtype") - assert array_dtype() == np.float64 assert array_dtype("float32") == np.float32 - monkeypatch.setenv("ARRAY_DTYPE", "float32") - with pytest.raises(RuntimeError, match="bed-reader"): + monkeypatch.setenv("ARRAY_DTYPE", "float16") + with pytest.raises(ValueError, match="ARRAY_DTYPE"): array_dtype() assert array_dtype("float64") == np.float64 @@ -71,7 +69,7 @@ def test_pheno_metadata_does_not_allocate_gpu_float64(monkeypatch): with pytest.MonkeyPatch.context() as patch: def unexpected(*args, **kwargs): raise AssertionError("metadata inspection must not allocate GPU values") - patch.setattr(bed_reader, "empty_gpu", unexpected) + 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) diff --git a/pysnptools/test_gpu_allocator.py b/pysnptools/test_gpu_allocator.py index b8aeb3f..2f04417 100644 --- a/pysnptools/test_gpu_allocator.py +++ b/pysnptools/test_gpu_allocator.py @@ -70,7 +70,7 @@ def test_host_constructor_native_standardization(cupy, dtype, order, standardize def test_caller_arrays_and_native_views_remain_cupy(cupy): - from bed_reader import empty_gpu + 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): @@ -83,7 +83,7 @@ def test_caller_arrays_and_native_views_remain_cupy(cupy): def test_slice_standardizes_only_selected_columns(cupy): - from bed_reader import empty_gpu + 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]]) @@ -92,8 +92,10 @@ def test_slice_standardizes_only_selected_columns(cupy): @pytest.mark.parametrize("order", ["C", "F"]) -def test_reads_and_kernel_outputs_are_native(cupy, order): - from bed_reader._gpu import _native_owner +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) @@ -101,11 +103,12 @@ def test_reads_and_kernel_outputs_are_native(cupy, order): 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 _native_owner(kernel.val) is not None + 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) - assert _native_owner(host.read(xp=cupy).val) is not None + 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): @@ -162,7 +165,7 @@ def fail(*args, **kwargs): raise RuntimeError("subset allocation failed") with monkeypatch.context() as context: - context.setattr(bed_reader, "empty_gpu", fail) + 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") @@ -230,7 +233,7 @@ def test_native_allocation_failure_propagates(cupy, monkeypatch): def fail(*args, **kwargs): raise RuntimeError("native allocation failed") - monkeypatch.setattr(bed_reader, "empty_gpu", fail) + 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)) diff --git a/pysnptools/test_gpu_precision_warning.py b/pysnptools/test_gpu_precision_warning.py index 0fc04d8..97b6c09 100644 --- a/pysnptools/test_gpu_precision_warning.py +++ b/pysnptools/test_gpu_precision_warning.py @@ -9,7 +9,7 @@ from pysnptools.snpreader import SnpData from pysnptools.standardizer import Identity -WarningType = getattr(bed_reader, "GpuFloat64Warning", UserWarning) +WarningType = bed_reader.GpuFloat64Warning def data(values, xp): diff --git a/pysnptools/util/_array.py b/pysnptools/util/_array.py index de428e4..f33e083 100644 --- a/pysnptools/util/_array.py +++ b/pysnptools/util/_array.py @@ -8,15 +8,15 @@ def _allocator(shape, dtype, xp): if xp is not np: - import bed_reader from bed_reader import bed_reader as native + from bed_reader._gpu import empty_gpu - allocator = getattr(bed_reader, "empty_gpu", None) - if (allocator is not None and hasattr(native, "allocate_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 allocator + return empty_gpu return None @@ -73,14 +73,10 @@ def zeros(shape, dtype, order, xp): def native_owner(values): - # Older bed-reader releases and ordinary CuPy arrays retain the CuPy path. + # 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 - import bed_reader - - if not hasattr(bed_reader, "empty_gpu"): - 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 index 045bf52..a254528 100644 --- a/pysnptools/util/_gpu_warnings.py +++ b/pysnptools/util/_gpu_warnings.py @@ -1,6 +1,4 @@ -"""GPU precision notices, including compatibility with older bed-reader builds.""" - -import warnings +"""GPU precision notices, delegated to bed-reader.""" import numpy as np @@ -8,17 +6,6 @@ def warn_gpu_float64(dtype, xp): if xp is np or np.dtype(dtype) != np.dtype("float64"): return - import bed_reader + from bed_reader._gpu import _warn_gpu_float64 - warn = getattr(bed_reader, "_warn_gpu_float64", None) - if warn is not None: - warn(dtype) - else: - # CuPy-only use remains supported with older published bed-reader builds. - warnings.warn( - "float64 arithmetic can be much slower than float32 on consumer GPUs. Float64 GPU arrays " - "also use twice the storage. Consider float32 where its precision is sufficient; " - "the requested dtype is unchanged.", - getattr(bed_reader, "GpuFloat64Warning", UserWarning), - stacklevel=2, - ) + _warn_gpu_float64(dtype) diff --git a/pysnptools/util/_precision.py b/pysnptools/util/_precision.py index 05a69b5..5533706 100644 --- a/pysnptools/util/_precision.py +++ b/pysnptools/util/_precision.py @@ -1,8 +1,5 @@ -"""Precision defaults shared with bed-reader without breaking older CPU installs.""" -import os - -import bed_reader -import numpy as np +"""Precision defaults shared with bed-reader.""" +from bed_reader._array_module import array_dtype as _array_dtype def array_dtype(dtype=None): @@ -19,12 +16,4 @@ def array_dtype(dtype=None): ... print(array_dtype(), array_dtype("float64")) float32 float64 """ - resolver = getattr(bed_reader, "array_dtype", None) - if resolver is not None: - return resolver(dtype) - # Supported older bed-reader releases lack this new optional policy. Keep - # their legacy defaults/explicit arguments working; never ignore a requested - # environment policy that the installed dependency cannot implement. - if dtype is None and "ARRAY_DTYPE" in os.environ: - raise RuntimeError("ARRAY_DTYPE requires bed-reader with array_dtype support") - return np.dtype("float64" if dtype is None else dtype) + return _array_dtype(dtype) diff --git a/pysnptools/util/test.py b/pysnptools/util/test.py index dbbc1f7..8ecb6f9 100644 --- a/pysnptools/util/test.py +++ b/pysnptools/util/test.py @@ -207,7 +207,7 @@ def sub_matrix_and_warnings(val, out_order, out_dtype): # reports its performance cost. Check every notice rather than # filtering the new category or weakening the precision check. import bed_reader - warning_type = getattr(bed_reader, "GpuFloat64Warning", UserWarning) + 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] From 238aae1f98d72f7ae578047f628056e4aa9a23c3 Mon Sep 17 00:00:00 2001 From: Carl Kadie Date: Thu, 19 Nov 2026 07:08:14 -0800 Subject: [PATCH 21/21] Make runner thread tests respect platform BLAS visibility --- pysnptools/util/mapreduce1/test_threads.py | 43 ++++++++++++++++++++-- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/pysnptools/util/mapreduce1/test_threads.py b/pysnptools/util/mapreduce1/test_threads.py index 1efa4b0..5e9b135 100644 --- a/pysnptools/util/mapreduce1/test_threads.py +++ b/pysnptools/util/mapreduce1/test_threads.py @@ -1,7 +1,8 @@ -"""Exercise real loaded BLAS pools and subprocess startup thread limits.""" +"""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 @@ -68,14 +69,48 @@ def setUp(self): self.addCleanup(os.chdir, previous_directory) self.directory = Path(temporary.name) self.before = _snapshot() - self.assertTrue(self.before["pools"], "Requires an actual NumPy or SciPy BLAS pool") + 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.assertTrue(snapshot["pools"], "No loaded BLAS pools were observed") + 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__): @@ -265,7 +300,7 @@ def test_subprocess_startup_limits_precede_numpy_scipy_imports(self): records = [json.loads(path.read_text()) for path in startup.glob("*.json")] self.assertEqual(len(records), 2, records) for record in records: - self.assertTrue(record["pools"]) + 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)