1# GraphBLAS/GraphBLAS: MATLAB interface for SuiteSparse:GraphBLAS 2 3SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2021, All Rights Reserved. 4The @GrB MATLAB interface (including its test suite and demos) is under the GNU 5GPLv3 (or later) license. 6SPDX-License-Identifier: GPL-3.0-or-later 7You may not use the @GrB MATLAB interface under the Apache-2.0 license. 8 9The GrB class provides an easy-to-use MATLAB interface to SuiteSparse:GraphBLAS. 10 11To install it for use in MATLAB, first compile the GraphBLAS library, 12-lgraphblas (or -lgraphblas_rename for MATLAB R2021a and later). See the 13instructions in the top-level GraphBLAS folder for details. Be sure to use 14OpenMP for best performance. The default installation process places the 15GraphBLAS library in /usr/local/lib. If you do not have root access and cannot 16install GraphBLAS into /usr/local/lib, then follow the instructions below to 17modify your library path, but instead of /usr/local/lib, use 18/home/me/SuiteSparse/GraphBLAS/build, where "/home/me/SuiteSparse/GraphBLAS" is 19where you placed your copy of GraphBLAS. 20 21If you have MATLAB R2021a, the gbmake script will link against the library 22-lgraphblas_rename, not -lgraphblas, because that version of MATLAB includes 23its own version of SuiteSparse:GraphBLAS (v3.3.3, an earlier one). To avoid 24a name conflict, you must compile the -lgraphblas_rename library in 25/home/me/SuiteSparse/GraphBLAS/GraphBLAS/build. 26 27MATLAB needs to know where to find the compiled GraphBLAS library. On 28Linux/Unix, if you are using the bash or korn shells, make sure that add the 29following to your login profile (typically .bash_profile for bash, or .profile 30for korn): 31 32 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib 33 export LD_LIBRARY_PATH 34 35On Linux/Unix with the csh, tcsh or related shells, use: 36 37 setenv PATH $PATH\:/usr/local/lib 38 39On the Mac, use the following: 40 41 DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/usr/local/lib 42 export DYLD_LIBRARY_PATH 43 44If you don't have system priveledges to change /usr/local/lib, then add the 45build folder to your LD_LIBRARY_PATH instead, either. For MATLAB R2020b 46and earlier: /home/me/SuiteSparse/GraphBLAS/build for libgraphblas.so, 47For R2021a: /home/me/SuiteSparse/GraphBLAS/GraphBLAS/build for for 48libgraphblas_rename.so. 49 50On Windows 10, on the Search bar type env and hit enter; (or you can 51right-click My Computer or This PC and select Properties, and then select 52Advanced System Settings). Select "Edit the system environment variables", 53then "Environment Variables". Under "System Variables" select "Path" and click 54"Edit". These "New" to add a path and then "Browse". Browse to the folder 55(for example: C:/Users/me/Documents/SuiteSparse/GraphBLAS/build/Release) and 56add it to your path. For MATLAB R2021a and later, you must use the 57libgraphblas_rename.dll, in: /User/me/SuiteSparse/GraphBLAS/GraphBLAS/build/Release 58instead. Then close the editor, sign out of Windows and sign back in again. 59 60For more details on setting your Linux/Unix/Mac library path for MATLAB see 61https://www.mathworks.com/help/matlab/matlab_external/building-on-unix-operating-systems.html 62 63Next, start MATLAB and go to this GraphBLAS/GraphBLAS folder. Type 64 65 addpath (pwd) 66 67to add the GraphBLAS interface to your path. Then do 68 69 savepath 70 71Or, if that function is not allowed because of file permissions, add this 72command to your startup.m file: 73 74 % add the MATLAB interface to the MATLAB path 75 addpath ('/home/me/SuiteSparse/GraphBLAS/GraphBLAS') : 76 77where the path /home/me/SuiteSparse/GraphBLAS/GraphBLAS is the full path to 78this folder. 79 80The name "GraphBLAS/GraphBLAS" is used for this folder so that this can be done 81in MATLAB: 82 83 help graphblas 84 85To get additional help, type: 86 87 methods GrB 88 help GrB 89 90Next, go to the GraphBLAS/GraphBLAS/@GrB/private folder and compile the MATLAB 91mexFunctions. Assuming your working directory is GraphBLAS/GraphBLAS 92(where this README.md file is located), do the following: 93 94 cd @GrB/private 95 gbmake 96 97To run the demos, go to the GraphBLAS/GraphBLAS/demo folder and type: 98 99 gbdemo 100 gbdemo2 101 102The output of these demos on a Dell XPS 13 laptop and an NVIDIA DGX Station can 103also be found in GraphBLAS/GraphBLAS/demo/html, in both PDF and HTML formats. 104 105To test your installation, go to GraphBLAS/GraphBLAS/test and type: 106 107 gbtest 108 109If everything is successful, it should report 'gbtest: all tests passed'. 110Note that gbtest tests all features of the MATLAB interface to 111SuiteSparse/GraphBLAS, including error handling, so you can expect to see 112error messages during the test. This is expected. 113 114# FUTURE: Not yet supported for GrB matrices in MATLAB: 115 116 linear indexing 117 2nd output for [x,i] = max (...) and [x,i] = min (...); needs 118 modified reduction methods inside GraphBLAS 119 'includenan' for min and max 120 min and max for complex matrices 121 singleton expansion 122 3D and higher dimensional matrices: 123 this might be done by converting the higher dimensioal 124 indices down to a large 2D space, and relying on hypersparsity. 125 saturating element-wise binary and unary operators for integers. 126 See also the discussion in the User Guide, and the details 127 in MATLAB_vs_GraphBLAS.txt in this folder. 128 129The last two features don't exist for MATLAB sparse matrices. 130 131These functions are supported, but are not yet as fast as they could be: 132bandwidth, eps, isbanded, isdiag, ishermitian, issymmetric, istril, istriu, 133spfun. 134 135