qsubcompile.m

function [fcomp] = qsubcompile(fname, varargin)

% QSUBCOMPILE compiles your function into an standalone executable that can easily
% be distributed on a cluster by QSUBCELLFUN. Running a compiled version of your
% function does not take any additional MATLAB licenses. Note that it does require
% that the corresponding MATLAB run-time environment (MCR) is installed on your
% cluster.
%
% Use as
%   compiledfun = qsubcompile(fname)
%   argout      = qsubcellfun(compiledfun, argin, ...)
% or
%   compiledfun = qsubcompile(fname)
%   jobid       = qsubfeval(compiledfun, argin, ...)
%   argout      = qsubget(jobid)
%
% Optional input arguments should be specified in key-value pairs
% and can include
%   batchid     = string that is used for the compiled application filename 
%                 and to identify the jobs in the queue, the default is
%                 automatically determined and looks like user_host_pid_batch.
%   toolbox     = string or cell-array with strings, additional Mathworks 
%                 toolboxes to include (see below).
%   executable  = string with the name of a previous compiled executable 
%                 to start, which usually takes the form "run_xxx.sh". This 
%                 implies that compilation does not have to be done.
%   numthreads  = number of threads, can be 1 or inf (default = 1)
%
% When executing a single batch of jobs using QSUBCELLFUN, you can also
% compile your function on the fly with the compile flag like this
%   argout      = qsubcellfun(fname, argin, ..., 'compile', 'yes')
% Using this syntax, the compiled function will be automatically cleaned
% up immediately after execution.
%
% If you need to include additional functions that are not automatically
% detected as dependencies by the MATLAB compiler, e.g. because using
% constructs like feval(sprintf(...)), you can specify fname as a
% cell-array. For example
%   compiledfun = qsubcompile({@ft_definetrial, @trialfun_custom})
%
% If you need to include Mathworks toolboxes that are not automatically
% detected as dependencies by the MATLAB compiler, you can specify them
% like this
%   compiledfun = qsubcompile(fname, 'toolbox', {'signal', 'image', 'stats'})
%
% A common problem for compilation is caused by the use of addpath in
% your startup.m file. Please change your startup.m file into
%   if ~isdeployed
%    % here goes the original content of your startup file
%    % ...
%   end
%
% If you want to execute the same function multiple times with different input
% arguments, you only have to compile it once. The name of the executable can be
% specified as input parameter, and the specified function within the executable
% can be re-execured. An example is specyfying the executable as run_fieldtrip.sh,
% which is a compiled version of the complete FieldTrip toolbox.
%
% See also QSUBCELLFUN, QSUBFEVAL, MCC, ISDEPLOYED

% -----------------------------------------------------------------------
% Copyright (C) 2012-2016, Robert Oostenveld
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/
%
% $Id$
% -----------------------------------------------------------------------

% Note that the user-function will be wrapped into qsubexec, which takes care of
% the loading and saving of the input and output arguments.

% It is possible for the user to have multiple MATLAB sessions running at the same
% time (on the same or different computers) and to start multiple instances of
% qsubcellfun. To ensure that those do not interfere with each others, each batch
% of jobs (i.e. instance of qsubcellfun) should get a unique identifier that is
% used in the filename of the temporary mat files.

% get the optional input arguments
batch      = ft_getopt(varargin, 'batch',   getbatch());               % this is a number that is automatically incremented
batchid    = ft_getopt(varargin, 'batchid', generatebatchid(batch));   % this is a string like user_host_pid_batch
toolbox    = ft_getopt(varargin, 'toolbox', {});
executable = ft_getopt(varargin, 'executable');
numthreads = ft_getopt(varargin, 'numthreads', 1); % our experience is that in many cases it is better to have multiple jobs on a single machine instead of a single multi-threaded job

if ischar(toolbox)
  % this should be a cell-array with strings
  toolbox = {toolbox};
end

% some temporary filse are made during compilation, these flags determine
% whether they can be cleaned up afterwards
hasreadme = exist('./readme.txt', 'file');
hasmcclog = exist('./mccExcludedFiles.log', 'file');

if iscell(fname)
  fdeps = fname(2:end);  % this remains a cell-array
  fname = fname{1};      % this is a handle or string
else
  fdeps = {};
end

if isa(fname, 'function_handle')
  % convert the function handle back into a string (e.g. @plus should be 'plus')
  fname = func2str(fname);
end

for i=1:length(fdeps)
  if isa(fdeps{i}, 'function_handle')
    fdeps{i} = func2str(fdeps{i});
  end
end

if numthreads==1
  % pass the singleCompThread option to the MCR
  runtimeopt = '-nodisplay,-singleCompThread';
elseif numthreads>0 && isinf(numthreads)
  % the default behavior of the MCR is to start as many computational threads as cores available
  runtimeopt = '-nodisplay';
else
  error('unsupported number of threads (%d)', numthreads);
end

if ~isempty(toolbox)
  % each toolbox should be added to the mcc command line as -p <full_path>
  toolboxopt = cell(1,length(toolbox));
  for i=1:length(toolbox)
    % find the directory where the toolbox is to be found
    toolboxpath = fileparts(which(fullfile(toolbox{i}, 'Contents.m')));
    if isempty(toolboxpath)
      error('the Mathworks toolbox "%s" could not be found', toolbox{i});
    else
      fprintf('including %s\n', toolboxpath);
    end
    toolboxopt{2*(i-1)+1} = '-p';
    toolboxopt{2*(i-1)+2} = toolboxpath;
  end
else
  toolboxopt = {};
end

if ~isempty(executable)
  % compilation is not needed, just wrap the user-specified executable and the function name
  % into the output structure for use by qsubcellfun or qsubfexec
  [p, f, x] = fileparts(executable);
  if isempty(p) || p(1)~='/'
    p = fullfile(pwd, p);
  end
  % precisely locate the executable, including the full path
  executable = fullfile(p, [f x]);
  if ~exist(executable, 'file')
    error('executable "%s" does not exist', executable);
  end
  fprintf('using "%s"\n', executable);
else
  % try to compile into a stand-allone application
  fprintf('compiling %s into %s\n', fname, batchid);
  % ensure that cellfun is included, it might be needed for stacked jobs
  mcc('-N', '-R', runtimeopt, '-o', batchid, toolboxopt{:}, '-m', 'qsubexec', 'cellfun', fname, fdeps{:});
  fprintf('finished compiling\n');
  executable = fullfile(pwd, sprintf('run_%s.sh', batchid));
end

if ~hasreadme
  delete('./readme.txt');
end

if ~hasmcclog
  delete('./mccExcludedFiles.log');
end

% remember all details
fcomp.fname       = fname;
fcomp.fdeps       = fdeps;
fcomp.batch       = batch;
fcomp.batchid     = batchid;
fcomp.executable  = executable;