Documentation

MATLink has four functions that handle various aspects of startup and shutdown of MATLAB and the underlying engine

• ConnectEngine and DisconnectEngine, which interacts with the MATLAB engine.
• OpenMATLAB and CloseMATLAB, which interacts with MATLAB.

OpenMATLAB, automatically calls ConnectEngine if the engine is not running, so one can launch MATLAB directly with it after loading the package. Similarly, DisconnectEngine will automatically terminate any open connection to MATLAB before shutting down the engine.

MATLink uses a session folder in $TemporaryDirectory to save scripts and functions defined during the current session. These are removed when DisconnectEngine is called, or by the operating system (typically after a reboot or daily, depending on the system), if there are any abandoned directories after a crash. To manually remove those folders, run MATLink`Developer`CleanupTemporaryDirectories[].

ConnectEngine[] will connect to the MATLAB engine using MathLink.

Details & Options

• On linux and OS X, if the mengine binary is not found, ConnectEngine will try to auto compile it.
• ConnectEngine creates a session directory in $TemporaryDirectory to which MScripts are written. This directory is automatically removed when DisconnectEngine is called.

DisconnectEngine[] will terminate the MathLink connection with the MATLAB engine.

Details & Options

• If a MATLAB connection is alive, DisconnectEngine will terminate it before shutting down the engine.
• DisconnectEngine deletes the session directory in $TemporaryDirectory that was created by ConnectEngine.

OpenMATLAB[] will start an instance of MATLAB for use with MATLink.

Details & Options

• If the MATLAB engine is not running, OpenMATLAB will call ConnectEngine[] to launch the engine before starting MATLAB

CloseMATLAB[] will close the currently open instance of MATLAB.

Arbitrary MATLAB code can be evaluated in three ways — using MEvaluate, MATLABCell or CommandWindow (only the first two are available on non-Windows operating systems). The primary difference between the three functions is:

• MEvaluate is a Mathematica function that takes MATLAB input as strings, and can be conveniently used in larger programs
• MATLABCell is a styled cell in a Mathematica notebook, that is useful for interactive work
• CommandWindow is just a Mathematica function that activates a native MATLAB command window interface. With this, one works directly with MATLAB, independent of MATLink (although the variables are still accessible via MATLink).

Since there is overhead in transferring instructions and output with MEvaluate, it is advisable to not display output where not necessary (both, in MATLAB and Mathematica). If you need to run the same set of instructions repeatedly, use an MScript instead of MEvaluate.

MEvaluate["code"] will execute code in MATLAB as if it were entered at the command prompt and returns the output as text.

Details & Options

• MEvaluate, when successful, will always return a string containing the output from MATLAB's command window.

Possible issues

• MEvaluate performance suffers if the output is not suppressed in MATLAB code. If you do not need to see the output of MEvaluate, use MEvaluate["command;"] instead of MEvaluate["command"];.
• The output length of MEvaluate is limited to approximatey 100,000 characters. The rest will be truncated.

CommandWindow["action"] will perform "action" on MATLAB's built-in command window. This function works only on Windows.

Details & Options

• CommandWindow["Show"] displays the command window. When an evaluation is not in progress, this window can be used to input MATLAB commands independently of MATLink.
• CommandWindow["Hide"] hides the command window.

MATLABCell[] creates a program cell in the current notebook, whose contents are interpreted as MATLAB code.

MATLAB programming involves script files, which are a series of sequential instructions to the interpreter (executed in the base workspace) or functions, which take zero or more inputs and return zero or more outputs (executed in its own workspace). The MScript and MFunction functions allow one to execute MATLAB scripts and functions from within Mathematica. This makes it easy to reuse code found online, either on the MathWorks File Exchange or elsewhere, instead of reimplementing it in Mathematica.

In MATLAB, one can define functions to have completely different behaviour based on the number of output arguments for the same set of input arguments. This is at odds with the behaviour in Mathematica (and in functional programming languages in general), where a function's behaviour is determined solely by its inputs. To bridge this divide, MFunction offers the functionality to use the multiple output form of MATLAB functions, but the number of outputs must be set explicitly when defining the function.

MScript["scriptname", "commands"] will create a MATLAB script containing commands.

Details & Options

• MScript["scriptname", "commands"] returns MScript["scriptname"], which can be evaluated using MEvaluate.

hello = MScript["hello", "disp('Hello world!')"];
MEvaluate@hello
(* Out[1] = "Hello world!" *)

• When creating new scripts, MScript will not overwrite exsiting .m files. To force overwrite an existing file, use the option "Overwrite" -> True (default value for "Overwrite" is False).

MFunction["func"] represents a MATLAB function func (that is on MATLAB's path), and can be called directly from within Mathematica.
MFunction["func", "body"] creates a new .m file with the contents body and returns MFunction["func"].

Examples

• Calling a built-in MATLAB function

  eig = MFunction["eig"];
  eig[{{1, 2}, {3, 4}}]
  (* Out[1]= {{-0.372281}, {5.37228}} *)
  

• Creating a custom function and using it

  add = MFunction["add", "
  	function res = add(x,y)
  		res = x+y
  	end "];
  add[3, 4]
  (* Out[1] = 7 *)
  

• Creating an anonymous function and using it

  add = MFunction["add", "@(x,y)x+y"];
  add[3, 4]
  (* Out[1] = 7 *)
  

  Anonymous functions defined in this manner form a closure, as in MATLAB.

Details & Options

• Use MFunction["func", "OutputArguments" -> n] when func returns more than one argument (default value for "OutputArguments" is 1).

eigsys = MFunction["eig", "OutputArguments" -> 2];
eigsys[{{1, 2}, {3, 4}}]
(* Out[1]= {{{-0.824565, -0.415974}, {0.565767, -0.909377}}, {{-0.372281, 0.}, {0., 5.37228}}} *)

• If func returns no outputs (or to suppress output), use MFunction["func", "Output" -> False] (default value for "Output" is True).

imagesc = MFunction["imagesc", "Output" -> False];
data = Import["ExampleData/ozonemap.hdf", {"Datasets", "TOTAL_OZONE"}][[20 ;;, All]];
imagesc[data];

Note that MATLAB plots will be opened in a new window, unlike Mathematica plots which are displayed inside the notebook.

• When creating new functions using the syntax MFunction["func", "body"], MFunction will not overwrite exsiting .m files. To force overwrite an existing file, use the option "Overwrite" -> True (default value for "Overwrite" is False).
• If the first character in "body" is @, then the function is defined as an anonymous function in MATLAB's workspace and no function file is created.

Possible issues

• By default MFunction assumes a single output argument, which causes errors in some MATLAB functions that return no output.

MFunction["disp"]["Hello"]
MATLink::errx: Error using disp
Too many output arguments.
(* Out[1]= $Failed *)

Use "Output" -> False in such situations.