Code covered by the BSD License  

Highlights from
lapack

lapack

by

 

09 Oct 2007 (Updated )

Easily call any LAPACK or BLAS routine from inside Matlab.

lapack(varargin);
function [varargout] = lapack(varargin);
%LAPACK Call any LAPACK or BLAS function or subroutine.  
%   C = LAPACK('FUNC', A1, A2, ...) 
%   [R1, R2, ...] = LAPACK('FUNC', A1, A2, ...)
%   calls the BLAS/LAPACK function named FUNC, passing it arguments
%   A1, A2, ..., then returns the results in the cell array C or in
%   the arguments R1, R2, ...
%
%   PROTO = LAPACK('FUNC') returns the prototype for the BLAS/LAPACK
%   function named FUNC as a string.
%
%   [R1, R2, ...] = LAPACK(PROTO, A1, A2, ...)
%   C = LAPACK(PROTO, A1, A2, ...)
%   where PROTO is a string similar to that returned by LAPACK('FUNC').
%   This form allows selection of a subset of the arguments to be
%   returned.  It also allows using functions from a newer version of
%   the BLAS/LAPACK libraries where the prototype is not known.
%
%   The PROTO argument is a string of the form 'T=FUNC(T,T,T,...)',
%   where T indicates the FORTRAN type of each argument to the routine
%   as well as the type of any return value. Lowercase values indicate
%   that this is an input value only, while uppercase values indicate
%   that it is an output (and possibly also an input) value.  Valid
%   values for T are
%
%      T    FORTRAN Type       Acceptable Matlab Type
%   --------------------------------------------------------------------------
%     s,S - REAL               single, double*
%     d,D - DOUBLE PRECISION   double*
%     c,C - COMPLEX            single, complex single*, double, complex double 
%     z,Z - COMPLEX*16         double, complex double*
%     i,I - INTEGER            int32*, int64*, double, logical
%     l,L - LOGICAL            int32*, int64, double, logical
%     h,H - CHARACTER          char*
%            * indicates the type that will be returned
%
%   Even if the BLAS/LAPACK routine specifies something as an output,
%   is is okay to specify it as input only (lowercase) if you are not
%   interested in that result.
%
%   The easiest place to find the descriptions of the arguments for
%   BLAS/LAPACK functions is from the FORTRAN source code, which
%   include comments that thoroughly describe each argument.  
%   They are available through the LAPACKHELP command.
%
% Examples:
%
%   Call the BLAS routine xDOT and xDOTC to compute inner product of X and Y
%     dot = lapack('D=DDOT(i,d,i,d,i)', length(X), X, 1, Y, 1)
%     dot = lapack('S=SDOT(i,s,i,s,i)', length(X), X, 1, Y, 1)
%     dot = lapack('Z=zdotc(i,z,i,z,i)', length(X), X, 1, Y, 1)
%   which are all equivalent to the Matlab expression
%     dot = X'*Y
%   the first lapack statement is also equivalent to
%     C = lapack('ddot', length(X), X, 1, Y, 1);
%     dot = C{1}
%
%   Call the LAPACK routine DGESVD to compute the SVD of the m by n matrix X
%     [m,n] = size(X);   % determine the dimensions of X
%     C = lapack('dgesvd', 'A', 'A', m, n, X, m, zeros(n,1), ...
%                zeros(m), m, zeros(n), n, zeros(5*m,1), 5*m, 0);
%     [s,U,VT] = C{[7,8,10]};
%     V = VT';
%   which is equivalent to the Matlab expressions:
%     [U,S,V] = svd(X);
%     s = diag(S);
%   equivalently we could specify a prototype for DGESVD:
%     [s,U,VT] = lapack('DGESVD(h,h,i,i,d,i,D,D,i,D,i,d,i,i)', ...
%                     'A', 'A', m, n, X, m, zeros(n,1), ...
%                      zeros(m), m, zeros(n), n, zeros(5*m,1), 5*m, 0);
%     V = VT';
%   to see a description of what the arguments for DGESVD should be type:
%     lapackhelp('dgesvd');
%
%   Call the LAPACK function LSAME to compare two characters
%     lapack('L=LSAME(h,h)', 'x', 'y')
%   which is equivalent to the Matlab expression
%     'x' == 'y'
%
%   Call the BLAS routine DGEMM
%     C = lapack('DGEMM',TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC);
%   the cell array C will have 13 elements corresponding to the updated
%   arguments passed to the DGEMM function.  To determine what each
%   argument stands for, type lapackhelp('dgemm') in Matlab.
%
% See also LAPACKHELP.

%   Copyright 2007-2009, Timothy Toolan, University of Rhode Island

% If we are in this function, then an appropriate compiled version
% does not exist, so ask the user if they want to build one.
reply = input(['The function ''lapack'' requires a compiled mex version, ' ...
               'create now? (Y/n): '], 's');

if (isempty(reply) || strcmpi(reply(1), 'y'))
  % To ensure the compiled version has a higher precedence than this
  % m-file, it should be placed in the directory where this m-file
  % resides.  We will also assume the C source file resides there.
  [dir, name, ext] = fileparts(which('lapack'));
  if (~length(dir) || ~strcmpi(name, 'lapack'))
    error('Could not determine directory containing this script (lapack.m).');
  end

  % On UNIX, we need to link to the library 'libdl' to allow runtime
  % linking to the internal Matlab LAPACK and BLAS functions.
  libs = '';
  if (isunix) 
    libs = '-ldl'; 
  end
  
  largedims = '';
  [arch, maxsize] = computer;
  if (maxsize > 2^31)
    largedims = '-largeArrayDims';
  end
  
  % Build the executable in the directory that contains this m-file.
  olddir = pwd;
  cd(dir);
  try
    eval(['mex ' largedims ' ' libs  ' lapack.c']); 
  catch exception
    cd(olddir);
    rethrow(exception);
  end
  cd(olddir);
  
  % Verify that we sucessfully created the mex file before we try to call it.
  [dir, name, ext] = fileparts(which('lapack'));
  if (~strcmpi(name, 'lapack') || ~strcmpi(ext, ['.' mexext]))
    error(['Could not create the compiled version of ''lapack''.' ...
           '  Try creating manually.']);
  end
  
  % Call the newly compiled function.
  [varargout{1:nargout}] = lapack(varargin{:});
else
  % If the user pressed 'n' to complation, so throw an error.
  error('Please create a compiled mex version of the function ''lapack''.');
end




Contact us