yuvaltassa / mmx

Multithreaded matrix operations on N-D arrays (a Matlab plug-in)

mmx

Multithreaded matrix operations on N-D arrays (a Matlab plug-in)

mmx treats an N-D matrix of double precision values as a set of pages of 2D matrices, and performs various matrix operations on those pages.

mmx uses multithreading over the higher dimensions (coarse-grained multithreading) to achieve good performance. Full singleton expansion is available for most operations.

Matrix multiplication:

C = mmx('mult', A, B)

is equivalent to

for i=1:N, 
  C(:,:,i) = A(:,:,i) * B(:,:,i); 
end

Singleton expansion is enabled on all dimensions so for example if

A = randn(5,4,3,10,1); 
B = randn(4,6,3,1 ,6); 
C = randn(5,6,3,10,6); 

then

C = mmx('mult', A, B)

is equivalent to

for i = 1:3 
  for j = 1:10 
    for k = 1:6 
      C(:,:,i,j,k) = A(:,:,i,j,1) * B(:,:,i,1,k); 
    end 
  end 
end

Transposition:

C = mmx('mult', A, B, mod)

where mod is a modifier string, will transpose one or both of A and B. Possible values for mod are 'tn', 'nt' and 'tt' where 't' stands for 'transposed' and 'n' for 'not-transposed'. For example

>> size(mmx('mult',randn(4,2),randn(4,2),'tn')) 
ans = 2 2

Squaring:

C = mmx('square', A, [])     % C = A*A' 
C = mmx('square', A, [],'t') % C = A'*A
C = mmx('square', A, B)      % C = (A*B'+B*A') / 2
C = mmx('square', A, B, 't') % C = (A'*B+B'*A) / 2

Cholesky factorization:

C = mmx('chol', A, []) % C = chol(A)

Solving linear equations:

C = mmx('backslash', A, B) % C = A\B

Unlike other mmx commands, 'backslash' does not support singleton expansion. If A is square, mmx will use LU factorization, otherwise it will use QR factorization. In the underdetermined case, (i.e. when size(A,1) < size(A,2)), mmx will give the least-norm solution which is equivalent to C = pinv(A)*B, (unlike Matlab's mldivide).

C = mmx('backslash', A, B, 'U') or mmx('backslash', A, B, 'L') will perform C = A\B assuming that A is upper or lower triangular, respectively.

C = mmx('backslash', A, B, 'P') will perform C = A\B assuming that A is symmetric positive definite.

mmx(n) does thread control: mmx will automatically start a number of threads equal to the number of available processors, however the number can be set manually to n using the command mmx(n). mmx(0) clears the threads from memory.

IMPORTANT NOTE: The functions which assume special types of square matrices as input ('chol' or 'backslash' for 'U','L' or 'P' modifiers) do not check that the inputs are what you say they are, and produce no error if they are not. Caveat computator.

Compilation:

Run build_mmx. Type help build_mmx to read about compilation issues and options.

Performance:

mmx's Issues

Reason: image not found

I'm running Matlab 2020b on OS X 11.5.2 using Intel® Parallel Studio XE 2020 update 4.

I copied and pasted the OS X commands from build_mmx.m, and it ran to completion for "single" but did moan about versions. See below.

Then when I run test_mmx it complains that library is not loaded, but its where build_mmx instructed. I guess I don't understand how "path" is resolved...

-jj

==========

test_mmx
compare_chol_flops.m compare_mult_T.m compare_mult_flops.m matlab_mprod.m test_mmx.m

Invalid MEX-file '/Users/jj/Downloads/mmx-master/src/mmx.mexmaci64': dlopen(/Users/jj/Downloads/mmx-master/src/mmx.mexmaci64, 6): Library not loaded:
@rpath/libsingle_mkl_ilp64.dylib
Referenced from: /Users/jj/Downloads/mmx-master/src/mmx.mexmaci64
Reason: image not found

Error in test_mmx (line 4)
mmx(i);

==========

but it is in /Applications/MATLAB_R2020b.app/extern/lib/maci64...

ls -ltr /Applications/MATLAB_R2020b.app/extern/lib/maci64

-r--r--r-- 1 jj admin 295 Mar 9 2009 mexFunction.map
-r--r--r-- 1 jj admin 325 Mar 9 2009 fexport.map
-r--r--r-- 1 jj admin 353 Nov 10 2015 fortran_exportsmexfileversion.map
-r--r--r-- 1 jj admin 337 Nov 10 2015 c_exportsmexfileversion.map
-r--r--r-- 1 jj admin 280 Oct 27 2017 cppMexFunction.map
-rwxr-xr-x 1 root admin 50447416 Aug 23 14:06 libsingle_mkl_ilp64.dylib

==========

build_mmx(1)

Trying to compile 'mmx_mkl_single', using
CXXFLAGS="$CXXFLAGS -I/opt/intel/mkl/include ", LDFLAGS="$LDFLAGS -L/Applications/MATLAB_R2020b.app/extern/lib/maci64 ", -lsingle_mkl_ilp64, -lpthread, -DUNIX_SYSTEM, -DUSE_BLAS, -DMKL_ILP64,
Building with 'Xcode Clang++'.
ld: warning: dylib (/Applications/MATLAB_R2020b.app/extern/lib/maci64/libsingle_mkl_ilp64.dylib) was built for newer macOS version (11.0) than being linked (10.14)

ld: warning: dylib (/Applications/MATLAB_R2020b.app/extern/lib/maci64/libsingle_mkl_ilp64.dylib) was built for newer macOS version (11.0) than being linked (10.14)

MEX completed successfully.
Compilation of 'mmx_mkl_single' succeeded.
Compiling again to 'mmx' target using 'mmx_mkl_single' build.
Building with 'Xcode Clang++'.
ld: warning: dylib (/Applications/MATLAB_R2020b.app/extern/lib/maci64/libsingle_mkl_ilp64.dylib) was built for newer macOS version (11.0) than being linked (10.14)

ld: warning: dylib (/Applications/MATLAB_R2020b.app/extern/lib/maci64/libsingle_mkl_ilp64.dylib) was built for newer macOS version (11.0) than being linked (10.14)

MEX completed successfully.

Support for gpuArray inputs

At present, when trying to pass gpuArray inputs (of underlying type double) to mmx, it fails with the reason that

Only inputs of type 'double' are supported.

Which is understandable since a gpuArray double isn't strictly double, but this is also unfortunate since we're unable to make use of the potential performance benefits of GPUs.

A possible solution to this could employ the MAGMA library, which is essentially LAPACK/BLAS for GPUs, for gpuArray inputs.

failed to compile mex / missing file single_mkl_ilp64.*

I'm getting an error when I try to run build_mmx.m Is the file single_mkl_ilp64.* missing from the repo? I don't see this in any of the directories. I'm in the folder /src when I run it — should I be somewhere else? Are there more general instructions for compiling?

Error message I get:

Compilation of 'mmx_mkl_single' failed with error:
ls: *single_mkl_ilp64.*: No such file or directory

==========
Trying to compile 'mmx_mkl_multi', using 
CXXFLAGS="\$CXXFLAGS -I/Applications/MATLAB_R2017b.app/extern/lib/maci64 ", -lmwblas, -lmwlapack, -lpthread, -DUNIX_SYSTEM, -DUSE_BLAS, 
Compilation of 'mmx_mkl_multi' failed with error:
/Applications/MATLAB_R2017b.app/extern/lib/maci64/mmx.cpp not found; check that you are in the correct current folder, and check the spelling of '/Applications/MATLAB_R2017b.app/extern/lib/maci64/mmx.cpp'.
==========
Trying to compile 'mmx_naive', using 
-lpthread, -DUNIX_SYSTEM, 
Compilation of 'mmx_naive' failed with error:
/Applications/MATLAB_R2017b.app/extern/lib/maci64/mmx.cpp not found; check that you are in the correct current folder, and check the spelling of '/Applications/MATLAB_R2017b.app/extern/lib/maci64/mmx.cpp'.

mkl root is not /opt/intel/mkl in latest version

I downloaded the version 2021.3 Intel Math Kernel Library (MKL), which is under a big pacakge called oneapi. After installation I found that mkl path is now

/opt/intel/oneapi/mkl/latest/

compile error on windows: expected initializer before 'teval'

I tried compiling from matlab 2017a on windows 10 using the MinGW64 Compiler (C).

During compilation, I get the following error

Trying to compile 'mmx_naive', using 
-DWIN_SYSTEM, 
Building with 'MinGW64 Compiler (C++)'.
Compilation of 'mmx_naive' failed with error:
C:\Users\acooman\Documents\mmx\src\mmx.cpp:80:16: error: expected initializer before 'teval'
 DWORD _stdcall teval(void* pn) 
                ^

A solution to fix this can be found on this page:
joncox123/Cortexsys#15

Fix:
In mmx.cpp Line 80 add a double underscore to stdcall instead of a single one:

DWORD __stdcall teval(void* pn)

I don't know whether this will break the other builds, so I hesitate to propose this fix as a commit.