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 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"`

### 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 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, 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

**and the corresponding serial MATLAB script**

`main_mpi.m`

**is the additional simulation attribute, which ensures the MPI-enabled ParaMonte library routines will be called for the parallel simulation.**

`main.m`

**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 thanto run applications in parallel. A prime example of this is`mpiexec`

. 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.`ibrun`

**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

**or**

`-n 3`

**at most, when invoking the MPI launcher).**

`-n 4`

## 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.

- on
- 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).