Running the ParaMonte MATLAB applications | ParaMonte: Parallel Monte Carlo Library

The procedure for running MATLAB simulations, whether serial or parallel, is identical to the procedure for running C/C++/Fortran applications, except that the user needs to replace the executable’s name main.exe with matlab -batch "main" on a command prompt to run the MATLAB script. Here, main is the name of the MATLAB script containing your ParaMonte simulation code (whether serial or parallel, does not matter).

Important: If you are a macOS (Darwin) user and you have downloaded the prebuilt ParaMonte libraries directly via a web-browser from the GitHub release page to use on your macOS system, read this troubleshooting page before attempting to run ParaMonte simulations.

Running MATLAB simulations on the command-prompt

Running MATLAB simulations on the command-prompt on a single processor

Suppose you want to run this MATLAB script named main.m which calls the ParaMonte library routines to sample a mathematical objective function implemented in this MATLAB file named logfunc.m on a single processor. Assuming that you have already successfully installed the ParaMonte MATLAB library on your system, all you need to do is to,

open a MATLAB-aware terminal (e.g., the Windows cmd.exe command-prompt on Windows or the Bash terminal on Linux/macOS),
navigate to the folder containing your code, and,
type the following on the command line,
```
matlab -batch "main"
```
Tip: If the matlab executable is not recognized by the Bash terminal, see this page for a solution.

Running MATLAB simulations on the command-prompt on multiple processors

Important: To run MPI-parallel MATLAB applications, an MPI runtime library is required (ideally, the Intel MPI library on Windows/Linux and Open-MPI library on macOS). The ParaMonte library can install the missing MPI library for you automatically, if you do not have it. At the time of installation, the ParaMonte MATLAB library automatically asks for your permission to install any missing libraries on your system when you type

addpath(genpath("./"),"-begin"); % add the ParaMonte library directories to MATLAB's list of search paths.
pm = paramonte(); % instantiate an object of class paramonte.

for the first time in MATLAB session. So, make sure to run the above command(s) for the first time after installing the ParaMonte library on your system, and before running any MPI-parallel ParaMonte simulations. To verify the existence of the runtime libraries on your system at any later time after running the above command(s), type,

pm.verify()

in your MATLAB session.

Suppose you want to run this MPI-enabled MATLAB script named main_mpi.m which calls the ParaMonte library parallel routines to sample a mathematical objective function implemented in this MATLAB file named logfunc.m on multiple processors.

Tip: Note that the only difference between the above MPI-enabled MATLAB script main_mpi.m and the corresponding serial MATLAB script main.m is the additional simulation attribute,

pmpd.mpiEnabled = true;

which ensures the MPI-enabled ParaMonte library routines will be called for the parallel simulation. Absolutely NO MPI parallel programming is needed by the user to run the ParaMonte MATLAB simulations in parallel.

Assuming that you have already successfully installed the ParaMonte MATLAB library on your system, all you need to do is to,

open a MATLAB-aware terminal (e.g., the Windows cmd.exe command-prompt on Windows or the Bash terminal on Linux/macOS),
navigate to the folder containing your code, and,
run the following on the command line,
- On Windows
  Invoke the MPI launcher mpiexec on the command line via,
```
mpiexec -localonly -n 3 matlab -batch "main_mpi"
```
  where the flag -localonly ensures that the simulation is run only on a single node. This option avoids the invocation of the Hydra service which would require prior registration of the service. The flag -n 3 assigns three MPI tasks to three physical processors for the simulation. Change the number 3 to as many processor counts as you wish to use.
  
  Tip: To run your simulation on a cluster of nodes, follow the guidelines and instructions provided by the Intel MPI library development team.
- On Linux / macOS
  Invoke the MPI launcher mpiexec on the command line via,
```
mpiexec -n 3 matlab -batch "main_mpi"
```
  The flag -n 3 assigns three MPI tasks to three physical processors for the simulation. Change the number 3 to as many processor counts as you wish to use.
  
  Note: Some supercomputing centers (for example, the Texas Advanced Computing Center) may have their dedicated MPI launchers other than mpiexec to run applications in parallel. A prime example of this is ibrun. Consult your supercomputing center to ensure you invoke the right MPI launcher for parallel applications, in particular, when running the application on a cluster of nodes of multiple processors.
  
  Tip: If the matlab executable is not recognized by the Bash terminal, see this page for a solution.

Warning: Do not specify more parallel (MPI or Coarray) tasks than the available number of physical processors on your system. If there are fewer physical processors available on the machine than the requested parallel tasks, some processors will be assigned more than one task. This will significantly degrade the performance of your simulation and will potentially eliminate any benefits gained from running your simulation in parallel. For example, if you are running a parallel simulation on a quad-core laptop (with four physical processors), then the maximum number of parallel tasks should not go beyond 4 under any circumstances (for example, set -n 3 or -n 4 at most, when invoking the MPI launcher).

Running MATLAB simulations from within a MATLAB session

You can also run the ParaMonte simulations from within a MATLAB session, but only in serial mode (since parallel simulations cannot be performed from within a MATLAB session). To run serial simulations from within MATLAB,

Depending on your operating system,
- on Windows, either open a MATLAB session from the Windows Startup Menu or simply call the MATLAB executable on the Windows command line.
- on Linux/macOS, open a MATLAB session by calling the MATLAB executable on the Bash terminal,
```
matlab
```
  Important: It is imperative that you open your MATLAB session by calling the matlab executable from the Bash command line since the standard output of the ParaMonte library redirects to the Bash command line as opposed to the MATLAB command line.
  
  Tip: If the matlab executable is not recognized by the Bash terminal, see this page for a solution.
Change the working directory of MATLAB to the folder containing your main.m script.
Before running the script, make sure you have added the path to the root directory of the ParaMonte library to your MATLAB’s list of search paths via,
```
addpath(genpath(ParaMonteRootDir));
```
where you will have to replace the variable ParaMonteRootDir with a string (e.g., "./") that points to the root directory of the ParaMonte MATLAB library (i.e., the directory in which the ParaMonte library’s license file LICENSE exists).

If you have any questions about the topics discussed on this page, feel free to ask in the comment section below, or raise an issue on the GitHub page of the library, or reach out to the ParaMonte library authors.