Interoperability between cuDF and CuPy#
This notebook provides introductory examples of how you can use cuDF and CuPy together to take advantage of CuPy array functionality (such as advanced linear algebra operations).
import timeit
import cupy as cp
from packaging import version
import cudf
if version.parse(cp.__version__) >= version.parse("10.0.0"):
cupy_from_dlpack = cp.from_dlpack
else:
cupy_from_dlpack = cp.fromDlpack
Converting a cuDF DataFrame to a CuPy Array#
If we want to convert a cuDF DataFrame to a CuPy ndarray, There are multiple ways to do it:
We can use the dlpack interface.
We can also use
DataFrame.values
.We can also convert via the CUDA array interface by using cuDF’s
to_cupy
functionality.
nelem = 10000
df = cudf.DataFrame(
{
"a": range(nelem),
"b": range(500, nelem + 500),
"c": range(1000, nelem + 1000),
}
)
%timeit arr_cupy = cupy_from_dlpack(df.to_dlpack())
%timeit arr_cupy = df.values
%timeit arr_cupy = df.to_cupy()
340 μs ± 5.05 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
689 μs ± 7.05 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
673 μs ± 3.99 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
arr_cupy = cupy_from_dlpack(df.to_dlpack())
arr_cupy
array([[ 0, 500, 1000],
[ 1, 501, 1001],
[ 2, 502, 1002],
...,
[ 9997, 10497, 10997],
[ 9998, 10498, 10998],
[ 9999, 10499, 10999]])
Converting a cuDF Series to a CuPy Array#
There are also multiple ways to convert a cuDF Series to a CuPy array:
We can pass the Series to
cupy.asarray
as cuDF Series exposes__cuda_array_interface__
.We can leverage the dlpack interface
to_dlpack()
.We can also use
Series.values
col = "a"
%timeit cola_cupy = cp.asarray(df[col])
%timeit cola_cupy = cupy_from_dlpack(df[col].to_dlpack())
%timeit cola_cupy = df[col].values
390 μs ± 1.29 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
706 μs ± 4.4 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
480 μs ± 3.24 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
cola_cupy = cp.asarray(df[col])
cola_cupy
array([ 0, 1, 2, ..., 9997, 9998, 9999])
From here, we can proceed with normal CuPy workflows, such as reshaping the array, getting the diagonal, or calculating the norm.
reshaped_arr = cola_cupy.reshape(50, 200)
reshaped_arr
array([[ 0, 1, 2, ..., 197, 198, 199],
[ 200, 201, 202, ..., 397, 398, 399],
[ 400, 401, 402, ..., 597, 598, 599],
...,
[9400, 9401, 9402, ..., 9597, 9598, 9599],
[9600, 9601, 9602, ..., 9797, 9798, 9799],
[9800, 9801, 9802, ..., 9997, 9998, 9999]])
reshaped_arr.diagonal()
array([ 0, 201, 402, 603, 804, 1005, 1206, 1407, 1608, 1809, 2010,
2211, 2412, 2613, 2814, 3015, 3216, 3417, 3618, 3819, 4020, 4221,
4422, 4623, 4824, 5025, 5226, 5427, 5628, 5829, 6030, 6231, 6432,
6633, 6834, 7035, 7236, 7437, 7638, 7839, 8040, 8241, 8442, 8643,
8844, 9045, 9246, 9447, 9648, 9849])
cp.linalg.norm(reshaped_arr)
array(577306.967739)
Converting a CuPy Array to a cuDF DataFrame#
We can also convert a CuPy ndarray to a cuDF DataFrame. Like before, there are multiple ways to do it:
Easiest; We can directly use the
DataFrame
constructor.We can use CUDA array interface with the
DataFrame
constructor.We can also use the dlpack interface.
For the latter two cases, we’ll need to make sure that our CuPy array is Fortran contiguous in memory (if it’s not already). We can either transpose the array or simply coerce it to be Fortran contiguous beforehand.
%timeit reshaped_df = cudf.DataFrame(reshaped_arr)
10.6 ms ± 128 μs per loop (mean ± std. dev. of 7 runs, 1 loop each)
reshaped_df = cudf.DataFrame(reshaped_arr)
reshaped_df.head()
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 |
1 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | ... | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | 398 | 399 |
2 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | ... | 590 | 591 | 592 | 593 | 594 | 595 | 596 | 597 | 598 | 599 |
3 | 600 | 601 | 602 | 603 | 604 | 605 | 606 | 607 | 608 | 609 | ... | 790 | 791 | 792 | 793 | 794 | 795 | 796 | 797 | 798 | 799 |
4 | 800 | 801 | 802 | 803 | 804 | 805 | 806 | 807 | 808 | 809 | ... | 990 | 991 | 992 | 993 | 994 | 995 | 996 | 997 | 998 | 999 |
5 rows × 200 columns
We can check whether our array is Fortran contiguous by using cupy.isfortran or looking at the flags of the array.
cp.isfortran(reshaped_arr)
False
In this case, we’ll need to convert it before going to a cuDF DataFrame. In the next two cells, we create the DataFrame by leveraging dlpack and the CUDA array interface, respectively.
%%timeit
fortran_arr = cp.asfortranarray(reshaped_arr)
reshaped_df = cudf.DataFrame(fortran_arr)
10.9 ms ± 86.7 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)
%%timeit
fortran_arr = cp.asfortranarray(reshaped_arr)
reshaped_df = cudf.from_dlpack(fortran_arr.toDlpack())
10.3 ms ± 65.5 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)
fortran_arr = cp.asfortranarray(reshaped_arr)
reshaped_df = cudf.DataFrame(fortran_arr)
reshaped_df.head()
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 |
1 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | ... | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | 398 | 399 |
2 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | ... | 590 | 591 | 592 | 593 | 594 | 595 | 596 | 597 | 598 | 599 |
3 | 600 | 601 | 602 | 603 | 604 | 605 | 606 | 607 | 608 | 609 | ... | 790 | 791 | 792 | 793 | 794 | 795 | 796 | 797 | 798 | 799 |
4 | 800 | 801 | 802 | 803 | 804 | 805 | 806 | 807 | 808 | 809 | ... | 990 | 991 | 992 | 993 | 994 | 995 | 996 | 997 | 998 | 999 |
5 rows × 200 columns
Converting a CuPy Array to a cuDF Series#
To convert an array to a Series, we can directly pass the array to the Series
constructor.
cudf.Series(reshaped_arr.diagonal()).head()
0 0
1 201
2 402
3 603
4 804
dtype: int64
Interweaving CuDF and CuPy for Smooth PyData Workflows#
RAPIDS libraries and the entire GPU PyData ecosystem are developing quickly, but sometimes a one library may not have the functionality you need. One example of this might be taking the row-wise sum (or mean) of a Pandas DataFrame. cuDF’s support for row-wise operations isn’t mature, so you’d need to either transpose the DataFrame or write a UDF and explicitly calculate the sum across each row. Transposing could lead to hundreds of thousands of columns (which cuDF wouldn’t perform well with) depending on your data’s shape, and writing a UDF can be time intensive.
By leveraging the interoperability of the GPU PyData ecosystem, this operation becomes very easy. Let’s take the row-wise sum of our previously reshaped cuDF DataFrame.
reshaped_df.head()
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 |
1 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | ... | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | 398 | 399 |
2 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | ... | 590 | 591 | 592 | 593 | 594 | 595 | 596 | 597 | 598 | 599 |
3 | 600 | 601 | 602 | 603 | 604 | 605 | 606 | 607 | 608 | 609 | ... | 790 | 791 | 792 | 793 | 794 | 795 | 796 | 797 | 798 | 799 |
4 | 800 | 801 | 802 | 803 | 804 | 805 | 806 | 807 | 808 | 809 | ... | 990 | 991 | 992 | 993 | 994 | 995 | 996 | 997 | 998 | 999 |
5 rows × 200 columns
We can just transform it into a CuPy array and use the axis
argument of sum
.
new_arr = cupy_from_dlpack(reshaped_df.to_dlpack())
new_arr.sum(axis=1)
array([ 19900, 59900, 99900, 139900, 179900, 219900, 259900,
299900, 339900, 379900, 419900, 459900, 499900, 539900,
579900, 619900, 659900, 699900, 739900, 779900, 819900,
859900, 899900, 939900, 979900, 1019900, 1059900, 1099900,
1139900, 1179900, 1219900, 1259900, 1299900, 1339900, 1379900,
1419900, 1459900, 1499900, 1539900, 1579900, 1619900, 1659900,
1699900, 1739900, 1779900, 1819900, 1859900, 1899900, 1939900,
1979900])
With just that single line, we’re able to seamlessly move between data structures in this ecosystem, giving us enormous flexibility without sacrificing speed.
Converting a cuDF DataFrame to a CuPy Sparse Matrix#
We can also convert a DataFrame or Series to a CuPy sparse matrix. We might want to do this if downstream processes expect CuPy sparse matrices as an input.
The sparse matrix data structure is defined by three dense arrays. We’ll define a small helper function for cleanliness.
def cudf_to_cupy_sparse_matrix(data, sparseformat="column"):
"""Converts a cuDF object to a CuPy Sparse Column matrix."""
if sparseformat not in (
"row",
"column",
):
raise ValueError("Let's focus on column and row formats for now.")
_sparse_constructor = cp.sparse.csc_matrix
if sparseformat == "row":
_sparse_constructor = cp.sparse.csr_matrix
return _sparse_constructor(cupy_from_dlpack(data.to_dlpack()))
We can define a sparsely populated DataFrame to illustrate this conversion to either sparse matrix format.
df = cudf.DataFrame()
nelem = 10000
nonzero = 1000
for i in range(20):
arr = cp.random.normal(5, 5, nelem)
arr[cp.random.choice(arr.shape[0], nelem - nonzero, replace=False)] = 0
df["a" + str(i)] = arr
df.head()
a0 | a1 | a2 | a3 | a4 | a5 | a6 | a7 | a8 | a9 | a10 | a11 | a12 | a13 | a14 | a15 | a16 | a17 | a18 | a19 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | 11.331250 | 0.000000 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 6.536755 | 2.657841 | 0.000000 | 0.0 | 0.000000 |
1 | 0.000000 | 0.000000 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 0.000000 | 5.812992 | 8.258568 | 0.0 | 0.000000 |
2 | 0.000000 | 0.000000 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 7.417438 | 0.0 | 0.0 | 0.0 | 0.000000 | 0.000000 | 0.000000 | 0.0 | 0.000000 |
3 | 0.000000 | 0.000000 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 0.000000 | 0.000000 | 0.000000 | 0.0 | 0.000000 |
4 | 3.787363 | 0.477243 | 0.0 | 6.051172 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.000000 | 0.0 | 0.0 | 0.0 | 0.000000 | 0.000000 | 0.000000 | 0.0 | -0.221498 |
sparse_data = cudf_to_cupy_sparse_matrix(df)
print(sparse_data)
<Compressed Sparse Column sparse matrix of dtype 'float64'
with 20000 stored elements and shape (10000, 20)>
Coords Values
(0, 0) 11.33125012510515
(256, 0) 10.35076450211901
(1025, 0) 13.131318068212249
(258, 0) -0.8256917503281647
(1411, 0) 7.240860805815855
(4, 0) 3.7873634763787325
(388, 0) 11.272040303348604
(902, 0) 3.276475472582007
(1032, 0) 11.491649361028863
(393, 0) 4.552421986471534
(138, 0) 9.194119794142825
(266, 0) 2.761791190745708
(394, 0) 2.7911333353407315
(268, 0) 5.624830850289776
(524, 0) 2.586692567521643
(270, 0) -0.4301381930119019
(1422, 0) -2.670344307194136
(783, 0) 14.27591553549854
(911, 0) 6.402226313895185
(1295, 0) 8.649941606510653
(1423, 0) 16.68643793342138
(20, 0) 6.474458877523693
(148, 0) 4.266440584149669
(916, 0) 0.2723862512436509
(149, 0) 3.9158998847316537
: :
(7805, 19) 2.184772158636337
(8573, 19) 8.579794066251624
(9214, 19) -0.3269005964603311
(8575, 19) 5.727882673628815
(9954, 19) 6.1155742778909845
(9827, 19) 4.352982460073818
(9828, 19) 1.155168220699963
(9573, 19) 3.9854303681358774
(9702, 19) -4.101511465788882
(9958, 19) 4.19374215238937
(9703, 19) 8.032306427727752
(9577, 19) 5.0343097524808815
(9706, 19) -2.0582395364086183
(9451, 19) -4.15672942294981
(9580, 19) 4.815572608088967
(9712, 19) 8.17145242726513
(9457, 19) 8.136626505015105
(9331, 19) 0.7681555522047268
(9589, 19) 7.841985652823531
(9847, 19) 6.97036966172625
(9467, 19) 7.595516224176323
(9468, 19) 5.6845257865708065
(9469, 19) -1.5907809377977866
(9470, 19) 3.206716764976286
(9599, 19) -0.8706680744168493
From here, we could continue our workflow with a CuPy sparse matrix.
For a full list of the functionality built into these libraries, we encourage you to check out the API docs for cuDF and CuPy.